@maltjoy/mcp-server 0.4.0 → 0.6.0-beta.0

package/dist/doc/VJoyDrawerTrigger/guideline.md

@@ -0,0 +1,145 @@
+---
+component: VJoyDrawerTrigger
+status: draft
+language: en
+dsds: JoyDrawerTrigger.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Drawer trigger
+
+Use **`VJoyDrawerTrigger`** when a control in the page should open a **`VJoyDrawer`** — without wiring `@click` handlers that call `drawer.show()` yourself.
+
+Pass the drawer’s template ref via the `drawer` prop and put the clickable UI (usually a `VJoyButton`) in the default slot. On click, the trigger emits `click`, then awaits `drawer.show()`.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyDrawerTrigger` from `@maltjoy/core-vue` |
+| **Design** | [Figma — Joy Core Design System](https://www.figma.com/design/jfndp2QBJGS9yeuWbeGuvD/) |
+| **Storybook** | [VJoyDrawer docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-overlays-vjoydrawer--docs) (`VJoyDrawerTrigger` is a subcomponent) |
+| **DSDS (machine)** | [`JoyDrawerTrigger.dsds.json`](./JoyDrawerTrigger.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyDrawerTrigger")` |
+
+---
+
+## When to use this component
+
+Use a drawer trigger when opening a side panel is tied to an explicit user action on a nearby control — for example “Filters”, “Details”, or “Edit”.
+
+It keeps drawer markup (`VJoyDrawer`) separate from the opener while avoiding boilerplate `@click` + `ref.show()` wiring. The default slot accepts any Vue nodes; multiple root nodes each receive the open handler.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Open the drawer from code (route change, API callback, timer) | Call `drawerRef.show()` on the `VJoyDrawer` ref directly |
+| A centered modal overlay | `VJoyDialog` + `VJoyDialogTrigger` (or manual `dialog.show()`) |
+| A mobile bottom sheet | `VJoyBottomSheet` + `VJoyBottomSheetTrigger` |
+| Only a click handler with no drawer | Put `@click` on the control — don’t wrap with `VJoyDrawerTrigger` |
+| Custom trigger chrome with ad-hoc CSS | Still use `VJoyDrawerTrigger` + a Joy button/link in the slot |
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| `drawer` prop | Yes | Template ref to the target `VJoyDrawer` (`InstanceType<typeof VJoyDrawer>`) |
+| Default slot | Yes | One or more trigger elements (e.g. `VJoyButton`, `<button>`, `VJoyLink`) |
+| Click bridge | Yes (internal) | Attaches `@click` to each slotted root vnode, then calls `drawer.show()` |
+
+### Default values
+
+- `drawer` has **no default** — pass the ref from the parent (may be `null` until `VJoyDrawer` mounts; the component re-reads the ref via an internal computed before opening).
+
+Props, events, and slots: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### API summary (from source)
+
+| Kind | Name | Notes |
+| --- | --- | --- |
+| Prop | `drawer` | `VJoyDrawer` instance ref; `null` / `undefined` until mounted |
+| Event | `click` | Emitted when the user activates the trigger, **before** `drawer.show()` |
+| Slot | `default` | Trigger UI; each root vnode gets the open click handler |
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Implementation
+
+- **MUST** declare `const drawer = ref<InstanceType<typeof VJoyDrawer> | null>(null)` and bind it with `ref="drawer"` on `VJoyDrawer` and `:drawer="drawer"` on the trigger.
+- **SHOULD** use `VJoyButton` (or another Joy interactive) in the default slot so variant, size, and focus styles stay consistent.
+- **SHOULD** `await` side effects in a parent `@click` listener only when you need logic *before* open; opening is already handled by the trigger.
+- **MUST NOT** invent props — the API is only `drawer` plus the `click` event and default slot.
+- **MUST NOT** add custom CSS on the trigger wrapper — it renders slot content as-is with no chrome.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| Pair with a sibling `VJoyDrawer` that owns header, body, and footer slots | Put drawer content inside the trigger |
+| Use an accessible button or link in the slot | Use a non-focusable `<div>` as the only trigger |
+| Call `drawer.show()` directly when opening without a click | Wrap programmatic openers in `VJoyDrawerTrigger` |
+
+---
+
+## Accessibility
+
+Behaviors depend on the **slotted trigger**, not on extra markup from `VJoyDrawerTrigger`.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Inherited from the slot (e.g. `button` from `VJoyButton`) |
+| Name | **MUST** expose an accessible name on the trigger (`label` on `VJoyButton`, visible text, or `aria-label`) |
+| Keyboard | **MUST** use a native `<button>` or `VJoyButton` / focusable link so Enter and Space activate the drawer |
+| Focus after open | Managed by `VJoyDrawer` (dialog semantics, focus trap) — don’t fight it from the trigger |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { VJoyDrawer, VJoyDrawerTrigger, VJoyButton } from '@maltjoy/core-vue'
+
+const drawer = ref<InstanceType<typeof VJoyDrawer> | null>(null)
+</script>
+
+<template>
+  <VJoyDrawer ref="drawer">
+    <template #drawer-header>Filters</template>
+    <template #drawer-body>Filter controls go here.</template>
+  </VJoyDrawer>
+
+  <VJoyDrawerTrigger :drawer="drawer" @click="/* optional */">
+    <VJoyButton label="Open filters" variant="secondary" />
+  </VJoyDrawerTrigger>
+</template>
+```
+
+Manual open (no trigger component):
+
+```vue
+<VJoyButton label="Open filters" @click="drawer?.show()" />
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyDrawerTrigger` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyDrawer` | The side panel overlay (header, body, footer, `show` / `hide`) |
+| `VJoyDialogTrigger` | Same open-on-click pattern for `VJoyDialog` |
+| `VJoyBottomSheetTrigger` | Same pattern for `VJoyBottomSheet` on mobile-first flows |
+| `VJoyButton` | Default choice for the trigger slot |

package/dist/doc/VJoyDropdown/guideline.md

@@ -0,0 +1,393 @@
+---
+component: VJoyDropdown
+status: draft
+language: en
+dsds: JoyDropdown.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Dropdown
+
+Use **`VJoyDropdown`** when the user needs a contextual panel of actions or choices that opens from a trigger — overflow menus, filter pickers, or compact option lists.
+
+It composes a focusable trigger (`dropdown-button` slot) with an overlay list (`VJoyDropdownList` internally). You can drive a predefined `options` array, or inject fully custom content through slots. Positioning (`direction`, `justify`), sizing, and click-outside behavior are built in.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyDropdown` from `@maltjoy/core-vue` |
+| **Design** | [Figma — Joy components](https://www.figma.com/design/jfndp2QBJGS9yeuWbeGuvD/) |
+| **Storybook** | [VJoyDropdown docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-forms-vjoydropdown--docs) |
+| **DSDS (machine)** | [`JoyDropdown.dsds.json`](./JoyDropdown.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyDropdown")` |
+
+---
+
+## When to use this component
+
+Use a dropdown when a compact trigger should reveal a short list of choices or contextual actions without leaving the current view — for example a row overflow menu, a filter chip that opens checkboxes, or a button that reveals cities to pick from.
+
+It fits patterns where the trigger is custom (button, icon button, filter chip) and the panel content may be a simple option list **or** richer form controls in the header, body, or footer slots.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| A labeled form field for single selection (native select semantics) | `VJoySelect` |
+| Persistent navigation menus (sidebar, app nav) | `VJoyMenu` + `VJoyMenuItem` |
+| Short explanatory text on hover / focus only | `VJoyTooltip` |
+| A standalone scrollable list without open/close trigger logic | `VJoyDropdownList` |
+| Custom `position: absolute` panels with ad-hoc markup | Still use `VJoyDropdown` + Joy tokens — don’t reinvent overlay behavior |
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Trigger wrapper | Yes | Click target wrapping the `dropdown-button` slot |
+| `dropdown-button` slot | Yes | The visible control that opens the panel — **must be focusable** (`VJoyButton`, `VJoyIconButton`, etc.) |
+| Dropdown list | Yes (when open) | `VJoyDropdownList` panel with options or custom slots |
+| `dropdown-header` slot | No | Content above the list (search field, title, filters) |
+| `dropdown-items` slot | No | Fully custom body — e.g. `VJoyCheckboxGroup` |
+| `dropdown-item` slot | No | Scoped slot to customize each option row when using `options` |
+| `dropdown-footer` slot | No | Actions below the list (Apply, Submit) |
+| Click-outside layer | Yes | Closes the panel when clicking outside trigger + list |
+
+### Default values
+
+- `direction` defaults to **`down`**
+- `justify` defaults to **`left`**
+- `size` defaults to **`medium`** (list item density)
+- `closeOnSelect` defaults to **`true`**
+- `width` defaults to **`300`** (px max-width of the list)
+- `height` defaults to **`300`** (px max-height of the scrollable items area)
+- `dropdownGap` defaults to **`12`** (px between trigger and list)
+- `modelValue` defaults to **`""`**
+- `options` defaults to **`[]`**
+- `reset` defaults to **`false`**
+- `appendTo` defaults to **`"body"`**
+- `disableTeleport` defaults to **`false`**
+
+Props, events, and slots: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+---
+
+## Variants
+
+`VJoyDropdown` has no visual emphasis variants. Choose **positioning** based on available space and reading direction.
+
+### Direction: `down` (default)
+
+Use when there is room below the trigger — the common case for toolbars, table rows, and form fields.
+
+Avoid when the trigger sits near the bottom of the viewport; prefer `up` so the list stays visible.
+
+### Direction: `up`
+
+Use when the trigger is low on the page or inside a bottom-aligned container (drawer footers, bottom toolbars).
+
+Pair with a chevron-up icon on the trigger when the open direction helps users predict behavior.
+
+### Justify: `left` (default)
+
+Align the list’s leading edge with the trigger’s leading edge. Default for LTR layouts and left-aligned controls.
+
+### Justify: `right`
+
+Align the list’s trailing edge with the trigger’s trailing edge. Use for right-aligned icon buttons (overflow / kebab menus).
+
+### Not in the API: center alignment
+
+Some design explorations show centered panels. **`justify` only supports `left` and `right`** (`TJoyDropdownJustify`). Do not invent `center` — adjust trigger placement or confirm with design before extending the API.
+
+---
+
+## Sizes
+
+`size` controls **list item density** inside `VJoyDropdownList`, not the trigger button. Size the trigger separately on `VJoyButton` / `VJoyIconButton`.
+
+| Size | Use when |
+| --- | --- |
+| `medium` | Default product menus and option lists |
+| `small` | Dense toolbars, filter bars, tables |
+| `xsmall` | Very compact UI (match trigger `xsmall` buttons) |
+
+Heights and padding come from Joy list tokens inside the component — **don’t hardcode item heights** in apps.
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Closed | Only the trigger is visible; list is not in the DOM |
+| Open | List animates in (`direction` controls animation); `dropdown:open` fires |
+| Hiding | Close animation plays (~300 ms) before the list unmounts; `dropdown:hide` fires after |
+| Option selected | Matching `modelValue` row shows selected styling (`aria-selected="true"`) |
+| Option disabled | Row is non-interactive (`disabled: true` on the option) |
+| Multi-step panel | With `close-on-select="false"`, list stays open while user edits checkboxes; footer Submit closes manually |
+| Reset available | With `reset`, a reset CTA appears in the list header; fires `dropdown:reset` (does not clear models automatically) |
+
+Clicking the trigger toggles open/closed. Clicking outside, pressing **Escape** or **Tab** in the list (options mode), or resizing the window closes the panel.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Trigger and hierarchy
+
+- **MUST** provide a focusable element in `dropdown-button` (button or icon button — not a bare `<div>`).
+- **MUST** set an accessible name on icon-only triggers (`label` / `aria-label` on `VJoyIconButton`).
+- **SHOULD** use `VJoyIconButton` with a dots / overflow icon for row-level action menus.
+- **SHOULD** use `VJoyButton` with a chevron when the trigger also communicates the open direction.
+
+### Options and selection
+
+- **MUST** give every option a unique `id` (and optional `value` when `modelValue` should differ from `id`).
+- **MUST** bind `v-model` when selection should persist and reflect the chosen option.
+- **SHOULD** set `close-on-select="false"` when the panel contains multi-select controls (`VJoyCheckboxGroup`) and needs an explicit Apply / Submit in `dropdown-footer`.
+- **SHOULD** handle `dropdown:reset` when `reset` is true — the component does not clear parent state by itself.
+
+### Layout and positioning
+
+- **SHOULD** set `width` to fit the longest expected label (or search field) without truncation.
+- **SHOULD** set `height` when the option count can overflow the viewport — the items area scrolls internally.
+- **SHOULD** pick `direction="up"` when placing dropdowns near the bottom edge of drawers, modals, or the viewport.
+- **MUST NOT** hardcode `z-index` on the list — Joy uses `--joy-core-z-index-dropdown`.
+
+### Implementation
+
+- **MUST** use only documented prop / enum values (MCP / `JoyDropdown.types.ts`).
+- **MUST** use Joy tokens and slots — no custom overlay chrome CSS.
+- **MUST NOT** invent props (`align`, `open`, `variant`, …).
+- **MUST NOT** mount `VJoyDropdownList` directly when you need open/close, click-outside, and trigger focus management — use `VJoyDropdown`.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `VJoyDropdown` + slots for custom filter panels | Raw `position: absolute` div menus |
+| `reset` + `@dropdown:reset` handler | Expect `reset` to clear `v-model` automatically |
+| `close-on-select="false"` + footer Submit for multi-select | Let each checkbox click close the panel |
+| `aria-label` on icon-only triggers | Icon button with no accessible name |
+| Match list `size` to trigger density | Mismatched xsmall trigger + medium list items |
+
+---
+
+## Content
+
+Dropdowns surface user-facing copy on the trigger, in each option, and sometimes in header/footer actions. Keep labels scannable — users open the panel to decide quickly.
+
+### Label formula
+
+**Trigger (button with text):** **noun or noun phrase** describing what opens — e.g. `Cities`, `Filters`, `More actions`.
+
+**Trigger (icon-only):** short **verb + object** in the accessible name — e.g. `Open menu`, `Show cities`, `Filter results`.
+
+**Options:** **plain noun or short phrase** — e.g. `Paris`, `Delete project`, `Export as PDF`. Use parallel grammar across siblings.
+
+**Reset CTA:** **verb + scope** — e.g. `Reset filter`, `Clear selection`. Default fallback in code is `Reset` if `reset-label` is omitted.
+
+**Footer actions:** same rules as `VJoyButton` — infinitive verb + noun (`Apply filters`, `Save changes`).
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | Icon-only triggers have an accessible name (`label` / `aria-label`) |
+| **MUST** | Option labels stay concise; long text truncates with `title` tooltip on the row |
+| **MUST** | Disabled options include context elsewhere if the reason isn’t obvious |
+| **MUST NOT** | Vague triggers — ❌ `Click here`, ❌ `Options` alone when a specific noun fits |
+| **MUST NOT** | Duplicate the trigger label on every option when the list context is clear |
+| **SHOULD** | ≤ 3 words per option where possible |
+| **SHOULD** | Use sentence case for multi-word labels |
+| **SHOULD** | Name destructive actions explicitly — ✅ `Delete project` · ❌ `Delete` alone in a mixed menu |
+| **SHOULD** | Localize `reset-label` — do not rely on the English default `Reset` in product UI |
+
+### Patterns
+
+**Overflow / kebab menu** — Icon trigger: `Open menu` or `More actions for {item name}`. Options are imperative verbs: `Edit`, `Duplicate`, `Archive`. Destructive action last with explicit wording.
+
+**Filter chip dropdown** — Trigger shows current filter state: `Continent: Europe` or `Status (2)`. Header may hold search. Footer holds `Apply filters` when `close-on-select` is false.
+
+**Searchable list** — Put `VJoyInput` in `dropdown-header`. Filter `options` in the parent; keep the placeholder specific (`Search cities`).
+
+**Multi-select with checkboxes** — Checkbox group label describes the set (`Choose options…`). Footer `Submit` or `Apply` confirms; don’t close on each toggle.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Trigger name | Visible text or `aria-label` / `label` on icon buttons — required when there is no visible text |
+| List labeling | On mount, the first child of the trigger receives `generatedId`; the listbox uses `aria-labelledby` with that id |
+| Role (options mode) | `role="listbox"` on the `<ul>`; each row `role="option"` with `aria-selected` / `aria-disabled` |
+| Focus on open | First focusable field inside the list receives focus when the panel opens |
+| Focus on close | Focus returns to the element that opened the panel |
+| Click outside | Clicking outside trigger + list closes the panel |
+| Keyboard (options list) | **ArrowUp** / **ArrowDown** move focus; **Home** / **End** jump; **Enter** selects; **Escape** / **Tab** close |
+| Keyboard (custom slot body) | When using `dropdown-items` without `options`, list keyboard patterns are not enforced — manage focus inside custom content |
+| Window resize | Panel closes to avoid stranded overlays |
+| Disabled options | `aria-disabled="true"`; not selectable |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { VJoyDropdown, VJoyButton, VJoyIconButton } from '@maltjoy/core-vue'
+import type { TJoyDropdownOption } from '@maltjoy/core-vue'
+
+const city = ref('')
+const cities: TJoyDropdownOption[] = [
+  { id: 'paris', label: 'Paris' },
+  { id: 'toulouse', label: 'Toulouse' },
+  { id: 'bordeaux', label: 'Bordeaux' },
+]
+</script>
+
+<template>
+  <!-- Predefined options + icon trigger -->
+  <VJoyDropdown v-model="city" :options="cities" width="200" justify="left">
+    <template #dropdown-button>
+      <VJoyIconButton variant="secondary" icon="pen" size="xsmall" label="Show cities" />
+    </template>
+  </VJoyDropdown>
+
+  <!-- Text trigger, opens upward near page bottom -->
+  <VJoyDropdown v-model="city" :options="cities" direction="up" width="200">
+    <template #dropdown-button>
+      <VJoyButton variant="secondary" size="xsmall" icon="chevron-up" icon-position="right">
+        Direction up
+      </VJoyButton>
+    </template>
+  </VJoyDropdown>
+
+  <!-- Custom body: checkboxes + footer submit -->
+  <VJoyDropdown :close-on-select="false" size="small" justify="right" width="200" height="200">
+    <template #dropdown-button>
+      <VJoyButton variant="secondary" size="xsmall" icon="chevron-down" icon-position="right">
+        Filters
+      </VJoyButton>
+    </template>
+    <template #dropdown-items>
+      <!-- VJoyCheckboxGroup or other controls -->
+    </template>
+    <template #dropdown-footer>
+      <VJoyButton size="xxsmall" variant="main">Apply filters</VJoyButton>
+    </template>
+  </VJoyDropdown>
+
+  <!-- Filter bar reset pattern -->
+  <VJoyDropdown
+    reset
+    reset-label="Reset filter"
+    :close-on-select="false"
+    @dropdown:reset="() => { /* clear parent filter state */ }"
+  >
+    <template #dropdown-button>
+      <VJoyButton variant="secondary" size="xsmall">Continent</VJoyButton>
+    </template>
+    <template #dropdown-items>
+      <!-- filter controls -->
+    </template>
+  </VJoyDropdown>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyDropdown` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyDropdownList` | You need only the list UI, without trigger / overlay lifecycle |
+| `VJoySelect` | Labeled single-select form field with integrated styling |
+| `VJoyMenu` | Persistent navigation menus with `VJoyMenuItem` |
+| `VJoyButton` / `VJoyIconButton` | Triggers inside `dropdown-button` |
+| `VJoyCheckboxGroup` | Multi-select content inside `dropdown-items` |
+| `VJoyFilterBar` | Composed filter UI that embeds `VJoyDropdown` patterns |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyDropdown.dsds.json`](./JoyDropdown.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Overflow / contextual menu from a trigger | `VJoyDropdown` | Custom absolutely positioned `<div>` menus |
+| Labeled form single-select | `VJoySelect` | `VJoyDropdown` mimicking a native select |
+| App / sidebar navigation | `VJoyMenu` | `VJoyDropdown` for persistent nav |
+| List panel only (no trigger) | `VJoyDropdownList` | `VJoyDropdown` with empty `dropdown-button` |
+| Multi-select filters with Apply | `VJoyDropdown` + `close-on-select="false"` + footer button | `close-on-select` default `true` on checkbox panels |
+| Icon-only trigger | `VJoyIconButton` in `dropdown-button` | Bare icon without `label` / `aria-label` |
+
+### Hard rules
+
+1. **MUST** call `joy_get_component_info("VJoyDropdown")` and/or `joy_get_component_types("VJoyDropdown")` before generating props.
+2. **MUST** always provide the `dropdown-button` slot with a focusable Joy trigger component.
+3. **MUST** set an accessible name when the trigger has no visible text.
+4. **MUST** use `TJoyDropdownOption` shape for `options` (`id`, `label`, optional `value`, `href`, `disabled`, `checked`).
+5. **MUST** wire `@dropdown:reset` when `reset` is true — reset does not mutate parent state.
+6. **MUST NOT** invent props (`variant`, `open`, `align`, `center`, …) or enum values outside types.
+7. **MUST NOT** override `.joy-dropdown` / `.joy-dropdown__list` positioning, `z-index`, or animation in product CSS.
+8. **SHOULD** set `direction="up"` when the story/layout places the trigger near the bottom of the viewport.
+9. **SHOULD** use `justify="right"` for right-aligned overflow icon buttons.
+10. **SHOULD** pass `width` / `height` as strings (pixel values without units in the prop value, e.g. `width="200"`).
+
+### Slot map
+
+| Slot | Maps to | Typical content |
+| --- | --- | --- |
+| `dropdown-button` | Trigger | `VJoyButton`, `VJoyIconButton` |
+| `dropdown-header` | List header | `VJoyInput` search, title text |
+| `dropdown-items` | Custom list body | `VJoyCheckboxGroup`, freeform markup |
+| `dropdown-item` | Option row template | Custom label / link per `option` |
+| `dropdown-footer` | List footer | `VJoyButton` Apply / Submit |
+
+### Checklist
+
+- [ ] Correct component (`VJoyDropdown` or named alternative)
+- [ ] Props / enums from MCP or `JoyDropdown.types.ts` only
+- [ ] `dropdown-button` slot present with focusable trigger
+- [ ] Icon-only trigger has accessible name
+- [ ] `v-model` bound when single selection from `options` should persist
+- [ ] `close-on-select` set intentionally for multi-step / multi-select panels
+- [ ] `dropdown:reset` handler when `reset` is true
+- [ ] No invented props / no custom dropdown chrome CSS
+- [ ] `direction` / `justify` match viewport space and trigger alignment
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyDropdown.dsds.json`](./JoyDropdown.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy | `anatomy` |
+| Direction / justify / sizes | `variants` |
+| States | `states` |
+| Best practices / content rules | `guidelines` (+ `content`) |
+| Accessibility | `accessibility` |
+| Examples | `sections` |
+| For agents | `agentDocumentBlocks` |
+| Props detail | `api` in JSON + Joy MCP |
+| Imports | `imports` in JSON |

package/dist/doc/VJoyDropdown/metadata.json

@@ -70,7 +70,7 @@
                   "type": "string",
                   "declarations": [
                     {
-                      "file": "/home/kevincarnaille/dev/design-system/packages/core-vue/src/components/JoyDropdown/JoyDropdown.types.ts",
+                      "file": "/Users/pierrereynaud/Documents/Work/design-system/packages/core-vue/src/components/JoyDropdown/JoyDropdown.types.ts",
                       "range": [
                         183,
                         194
@@ -88,7 +88,7 @@
                   "type": "string | undefined",
                   "declarations": [
                     {
-                      "file": "/home/kevincarnaille/dev/design-system/packages/core-vue/src/components/JoyDropdown/JoyDropdown.types.ts",
+                      "file": "/Users/pierrereynaud/Documents/Work/design-system/packages/core-vue/src/components/JoyDropdown/JoyDropdown.types.ts",
                       "range": [
                         199,
                         214
@@ -113,7 +113,7 @@
                   "type": "string",
                   "declarations": [
                     {
-                      "file": "/home/kevincarnaille/dev/design-system/packages/core-vue/src/components/JoyDropdown/JoyDropdown.types.ts",
+                      "file": "/Users/pierrereynaud/Documents/Work/design-system/packages/core-vue/src/components/JoyDropdown/JoyDropdown.types.ts",
                       "range": [
                         219,
                         233
@@ -131,7 +131,7 @@
                   "type": "string | undefined",
                   "declarations": [
                     {
-                      "file": "/home/kevincarnaille/dev/design-system/packages/core-vue/src/components/JoyDropdown/JoyDropdown.types.ts",
+                      "file": "/Users/pierrereynaud/Documents/Work/design-system/packages/core-vue/src/components/JoyDropdown/JoyDropdown.types.ts",
                       "range": [
                         238,
                         252
@@ -154,7 +154,7 @@
                   "type": "boolean | undefined",
                   "declarations": [
                     {
-                      "file": "/home/kevincarnaille/dev/design-system/packages/core-vue/src/components/JoyDropdown/JoyDropdown.types.ts",
+                      "file": "/Users/pierrereynaud/Documents/Work/design-system/packages/core-vue/src/components/JoyDropdown/JoyDropdown.types.ts",
                       "range": [
                         295,
                         314
@@ -185,7 +185,7 @@
                   "type": "boolean | undefined",
                   "declarations": [
                     {
-                      "file": "/home/kevincarnaille/dev/design-system/packages/core-vue/src/components/JoyDropdown/JoyDropdown.types.ts",
+                      "file": "/Users/pierrereynaud/Documents/Work/design-system/packages/core-vue/src/components/JoyDropdown/JoyDropdown.types.ts",
                       "range": [
                         357,
                         375