diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/.pages b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/.pages new file mode 100644 index 0000000000..111529b9fc --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/.pages @@ -0,0 +1,11 @@ +# AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY +# To update: edit a *.docs.md in vc-shell, then run yarn docs:sync +title: Components +nav: + - layout + - form + - data-display + - feedback + - navigation + - media + - misc diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/data-display/.pages b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/data-display/.pages new file mode 100644 index 0000000000..7908a3783d --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/data-display/.pages @@ -0,0 +1,8 @@ +# AUTO-GENERATED FROM vc-shell — DO NOT EDIT MANUALLY +# To update: edit a *.docs.md in vc-shell, then run yarn docs:sync +title: Data Display +nav: + - VcAccordion: vc-accordion.md + - VcDataTable: vc-data-table.md + - VcGallery: vc-gallery.md + - VcImageTile: vc-image-tile.md diff --git a/platform/developer-guide/docs/custom-apps-development/vc-shell/components/data-display/vc-accordion.md b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/data-display/vc-accordion.md new file mode 100644 index 0000000000..8974098497 --- /dev/null +++ b/platform/developer-guide/docs/custom-apps-development/vc-shell/components/data-display/vc-accordion.md @@ -0,0 +1,311 @@ + + + + + +# VcAccordion + +Collapsible content sections with smooth CSS grid animations, customizable collapsed heights with fade-out preview, and four visual variants. Supports both data-driven rendering via `items` array and slot-based composition with `VcAccordionItem`. + +## When to Use + +- FAQ sections, expandable product details, or grouped settings +- Progressive disclosure to reduce visual clutter on content-heavy pages +- Partial content preview in collapsed state (via `collapsedHeight`) +- Expandable form sections or configuration panels + +When NOT to use: + +- For navigation groups -- use `VcMenuGroup` +- For tab-based content switching -- use `VcTabs` +- For single collapsible panels without siblings -- use `VcAccordionItem` directly + +## Quick Start + +
+ + Open in Storybook ↗ +
+ +```vue + + + +``` + +## Features + +!!! tip "Use v-model to control initial open state" +Without `v-model`, no items are expanded on mount. Pass an initial value to pre-open a specific item. + +### Visual Variants + +Four variants control the visual grouping and spacing of accordion items. + +| Variant | Description | +| ----------- | ------------------------------------------------------------------------ | +| `default` | Items stacked with shared top/bottom borders, no gaps | +| `bordered` | Single outer border wrapping all items, items separated by inner borders | +| `separated` | Card-like items with 12px gaps between them, each with its own border | +| `ghost` | Transparent background, minimal styling, no borders or padding | + +```vue + +``` + +### Controlled with v-model + +Use `v-model` to control which items are expanded. In single mode, the value is a single `string | number`. In multiple mode, the value is an array. + +```vue + + + +``` + +
+ + Open in Storybook ↗ +
+ +### Multiple Open Items + +Set `multiple` to `true` to allow expanding several items simultaneously. The `v-model` value becomes an array. + +```vue + +``` + +
+ + Open in Storybook ↗ +
+ +### Partial Content Preview (collapsedHeight) + +When `collapsedHeight` > 0, collapsed items show that many pixels of content with a fade-out gradient. The chevron only appears when content overflows. + +```vue + +``` + +### Maximum Expanded Height + +Limit expanded content height with `maxExpandedHeight`. Content scrolls when it exceeds the limit. + +```vue + +``` + +### Per-Item Height Overrides + +Each item can override the global `collapsedHeight` and `maxExpandedHeight`: + +```ts +const items = [ + { id: "summary", title: "Summary", content: longText, collapsedHeight: 0 }, + { id: "preview", title: "Description", content: longText, collapsedHeight: 80 }, + { id: "terms", title: "Terms", content: veryLongText, maxExpandedHeight: 300 }, +]; +``` + +### Custom Title and Slot-based Composition + +For full control, use the default slot with `VcAccordionItem` children instead of the `items` prop. + +```vue + + + + Details about the new feature... + + Standard content. + +``` + +### Dynamic Component Content + +The `content` property in `AccordionItem` accepts both strings and Vue components, allowing you to embed interactive content inside accordion panels. + +## Recipes + +### FAQ Page with Preselected Item + +```vue + + + +``` + +## Common Mistakes + +### 1. Expecting items to open by default without v-model + +```vue + + + + + +``` + +### 2. Mixing items prop with default slot + +Both render together -- items-prop items appear first, then slot content. Omit `items` if using only slots. + +### 3. Using multiple mode with single-value v-model + +```vue + + + + + +``` + +## AccordionItem Interface + +```ts +interface AccordionItem { + id?: string | number; // Unique identifier (falls back to array index) + title: string; // Header text + content?: string | Component; // Body content (string or Vue component) + titleSlot?: Component; // Custom title component (alternative to #title slot) + collapsedHeight?: number; // Per-item collapsed height override (px) + maxExpandedHeight?: number; // Per-item max expanded height override (px) + disabled?: boolean; // Prevents toggling this item +} +``` + +## Props + +| Prop | Type | Default | Description | +| ------------------- | --------------------------------------------------- | ----------- | ----------------------------------------------------- | +| `items` | `AccordionItem[]` | `[]` | Array of items to render | +| `modelValue` | `(string \| number) \| (string \| number)[]` | -- | Controlled expanded state via `v-model` | +| `multiple` | `boolean` | `false` | Allow multiple items to be expanded simultaneously | +| `variant` | `"default" \| "bordered" \| "separated" \| "ghost"` | `"default"` | Visual style variant | +| `collapsedHeight` | `number` | `0` | Default collapsed height in pixels for all items | +| `maxExpandedHeight` | `number` | -- | Maximum expanded height (content scrolls if exceeded) | + +## Events + +| Event | Payload | Description | +| ------------------- | -------------------------------------------- | ------------------------------------ | +| `update:modelValue` | `(string \| number) \| (string \| number)[]` | Emitted when expanded item(s) change | + +## Slots + +| Slot | Description | +| --------- | ---------------------------------------------------------------- | +| `default` | Place `VcAccordionItem` components directly for custom rendering | + +### VcAccordionItem Slots + +| Slot | Description | +| --------- | ------------------------------------------------------- | +| `title` | Custom title rendering (replaces the `title` prop text) | +| `default` | Content body of the accordion item | + +## CSS Variables + +| Variable | Default | Description | +| ------------------------------------------ | ---------------------- | ----------------------------------------- | +| `--accordion-item-border-color` | `var(--neutrals-200)` | Border color for items and dividers | +| `--accordion-item-border-radius` | `6px` | Border radius of item containers | +| `--accordion-item-header-padding` | `12px 16px` | Header button padding | +| `--accordion-item-header-background` | `var(--additional-50)` | Header background color | +| `--accordion-item-header-background-hover` | `var(--neutrals-50)` | Header background on hover | +| `--accordion-item-header-color` | `var(--secondary-950)` | Header text color | +| `--accordion-item-content-padding` | `16px` | Content body padding | +| `--accordion-item-content-background` | `var(--additional-50)` | Content body background | +| `--accordion-item-transition-duration` | `300ms` | Expand/collapse animation duration | +| `--accordion-item-fade-height` | `60px` | Fade gradient height on collapsed preview | +| `--accordion-item-focus-ring-color` | `var(--primary-100)` | Focus ring color for keyboard navigation | + +> **Note:** The `ghost` variant overrides several variables to transparent/zero values for minimal appearance. + +## Accessibility + +- Each header is a focusable `