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

package/dist/doc/VJoyDropdownList/guideline.md

@@ -0,0 +1,396 @@
+---
+component: VJoyDropdownList
+status: draft
+language: en
+dsds: JoyDropdownList.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Dropdown list
+
+Use **`VJoyDropdownList`** when you need the scrollable option panel of a dropdown — selectable rows, optional header/footer, and listbox keyboard support — without the trigger, overlay positioning, or open/close lifecycle.
+
+It powers `VJoyDropdown` internally and can be mounted standalone when the parent already controls visibility and placement. Bind selection with `v-model`, pass an `options` array, or inject fully custom body content through slots.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyDropdownList` from `@maltjoy/core-vue` |
+| **Design** | [Figma — Joy components](https://www.figma.com/design/jfndp2QBJGS9yeuWbeGuvD/) |
+| **Storybook** | [VJoyDropdownList docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-forms-vjoydropdownlist--docs) |
+| **DSDS (machine)** | [`JoyDropdownList.dsds.json`](./JoyDropdownList.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyDropdownList")` |
+
+---
+
+## When to use this component
+
+Use a dropdown list when a panel must show one or more selectable rows (or custom filter controls) inside an already-open overlay — for example the list body of `VJoyDropdown`, a filter bar panel you position yourself, or a popover whose open state lives in the parent.
+
+It fits both **predefined option lists** (`options` + `v-model`) and **custom bodies** (`dropdown-list-items` slot with `VJoyCheckboxGroup` or other form controls).
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Trigger + open/close + click-outside + focus return | `VJoyDropdown` |
+| Labeled single-select form field (native select semantics) | `VJoySelect` |
+| Persistent navigation menus | `VJoyMenu` + `VJoyMenuItem` |
+| Every option visible at once (2–7 parallel choices) | `VJoyRadio` inside `VJoyRadioGroup` |
+| Card-style selectable tiles | `VJoySelectableItemGroup` |
+| Custom `position: absolute` panels with ad-hoc list markup | Still use `VJoyDropdownList` + Joy tokens — don’t reinvent list chrome |
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Root container | Yes | `.joy-dropdown-list` — bordered panel with elevation and fixed `width` |
+| Header | No | `.joy-dropdown-list__header` — optional reset CTA and/or `dropdown-list-header` slot |
+| Reset control | No | Text button when `reset` is true; emits `reset` (does not clear parent state) |
+| Items scroller | Yes | `.joy-dropdown-list__items` — scrollable area capped by `height` |
+| Options list | No* | `<ul role="listbox">` with `<li role="option">` rows when `options` is non-empty |
+| Custom items body | No* | `dropdown-list-items` slot — replaces the built-in list when `options` is empty |
+| Option label | No | Default `<span>{{ option.label }}</span>` or scoped `label` slot per row |
+| Footer | No | `.joy-dropdown-list__footer` via `dropdown-list-footer` slot |
+
+\* Use either the built-in `options` list **or** `dropdown-list-items`, not both for the same purpose.
+
+### Default values
+
+- `size` defaults to **`medium`**
+- `width` defaults to **`300`** (px, applied as inline `width` / `max-width`)
+- `height` defaults to **`300`** (px max-height of the scrollable items area)
+- `options` defaults to **`[]`**
+- `reset` defaults to **`false`**
+- `modelValue` has no default — bind when selection should persist
+
+Props, events, and slots: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Option shape
+
+Each entry in `options` should provide:
+
+- **`id`** (required, unique) — row identity and default `v-model` value
+- **`label`** (required) — visible text; also used for `title` tooltip and `aria-label` on the row
+- **`value`** (optional) — alternate `v-model` value when it must differ from `id`
+- **`disabled`** (optional, default `false`) — non-interactive row
+- **`href`** (optional) — when the `label` slot renders a link, **Enter** delegates to the anchor click
+
+### Events the parent should handle
+
+| Event | When it fires | Typical parent action |
+| --- | --- | --- |
+| `update:modelValue` | User selects an enabled option | Persist selection; optionally close overlay (`VJoyDropdown` does this when `closeOnSelect` is true) |
+| `close:dropdownList` | **Escape** or **Tab** while focus is inside the built-in listbox | Close the surrounding overlay and return focus to the trigger |
+| `reset` | User clicks the reset CTA (`reset` prop) | Clear filter / checkbox state in the parent — the list does not mutate models |
+
+---
+
+## Variants
+
+`VJoyDropdownList` has **no visual emphasis variants** (no primary/secondary). Appearance is controlled by **size**, **selection state**, and **disabled** rows only.
+
+Choose a different component if you need card layouts, native form-field chrome, or trigger-driven overlay behavior.
+
+### Not in the API: `dropdown-list-item` slot
+
+`defineSlots` documents a `dropdown-list-item` scoped slot, but the template wires **`label`** for per-row customization. Use `#label="{ …option }"` (or let `VJoyDropdown` forward `dropdown-item`) — do not rely on `dropdown-list-item` until it is implemented.
+
+---
+
+## Sizes
+
+`size` controls **row density** (height and font size via form-size tokens). It does not size header/footer padding beyond shared spacing tokens.
+
+| Size | Use when |
+| --- | --- |
+| `medium` | Default product menus and option lists |
+| `small` | Dense toolbars, filter bars, tables |
+| `xsmall` | Very compact UI (match `xsmall` triggers on `VJoyButton` / `VJoyIconButton`) |
+
+Heights come from `--dropdown-item-height` / `--dropdown-item-font-size` inside the component — **don’t hardcode item heights** in apps.
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Default row | Neutral text; pointer cursor; hover highlights row |
+| Selected row | `joy-dropdown-list__item--selected` — secondary background and text color; `aria-selected="true"` |
+| Focused row | Inset focus ring on the `<li>` (`box-shadow` focus token) |
+| Disabled row | Muted text; `cursor: not-allowed`; not clickable; `aria-disabled="true"` |
+| Scroll overflow | Items area scrolls vertically when content exceeds `height` |
+| Custom slot body | `dropdown-list-items` adds padding class; built-in listbox keyboard patterns are **not** applied |
+| Reset visible | Header shows reset CTA when `reset` is true |
+
+On mount, if `modelValue` matches an option, that row receives focus and the scroller scrolls it into view.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Selection and data
+
+- **MUST** give every option a unique `id`.
+- **MUST** bind `v-model` when a single selected value should persist across opens.
+- **SHOULD** set `value` on an option only when the stored model must differ from `id`.
+- **SHOULD** handle `@reset` when `reset` is true — the component does not clear parent state.
+- **SHOULD** listen for `@close:dropdown-list` when the list sits inside a custom overlay (mirror `VJoyDropdown` behavior).
+
+### Layout
+
+- **SHOULD** set `width` to fit the longest expected label (rows truncate with ellipsis; full text is in `title`).
+- **SHOULD** set `height` when option count can exceed the viewport — scrolling is internal to the items area.
+- **MUST NOT** hardcode panel border, radius, shadow, or `z-index` — Joy tokens apply via `.joy-dropdown-list`.
+
+### Composition
+
+- **SHOULD** prefer `VJoyDropdown` when you need a trigger, click-outside, open/close animation, and focus return.
+- **SHOULD** use `dropdown-list-items` + `VJoyCheckboxGroup` for multi-select filter panels; keep the list open until the parent closes it.
+- **MUST** set `aria-label` or `aria-labelledby` when the list is not labelled by a visible trigger element (standalone panels).
+
+### Implementation
+
+- **MUST** use only documented prop / enum values (MCP / `JoyDropdownList.types.ts`).
+- **MUST** use Joy tokens and slots — no custom list chrome CSS.
+- **MUST NOT** invent props (`variant`, `open`, `direction`, …).
+- **MUST NOT** mount `VJoyDropdownList` without a parent plan for open/close and focus when users expect dropdown behavior — use `VJoyDropdown`.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `VJoyDropdown` for full dropdown UX | `VJoyDropdownList` alone with no overlay logic |
+| `label` slot for custom row content | Undocumented `dropdown-list-item` slot |
+| `@reset` handler when `reset` is true | Expect reset to clear `v-model` automatically |
+| `aria-labelledby` from trigger id (`VJoyDropdown` pattern) | Orphan listbox with no accessible name |
+| Match list `size` to trigger density | `xsmall` trigger + `medium` rows |
+
+---
+
+## Content
+
+Dropdown lists surface copy on options, in the optional header/footer, and on the reset control. Keep labels scannable — users scan the panel to decide quickly.
+
+### Label formula
+
+**Options:** **plain noun or short phrase** — e.g. `Paris`, `Export as PDF`, `Last 30 days`. Use parallel grammar across siblings.
+
+**Header slot:** **instruction or context** — e.g. `Select a station`, `Filter by status`.
+
+**Reset CTA:** **verb + scope** — e.g. `Reset filter`, `Clear selection`. Code falls back to `Reset` when `reset-label` is omitted.
+
+**Footer actions:** same rules as `VJoyButton` — infinitive verb + noun (`Apply filters`, `Save changes`).
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **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 option labels — ❌ `Item 1`, ❌ `Click here` |
+| **MUST NOT** | Duplicate header context on every option when the list topic 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 list |
+| **SHOULD** | Localize `reset-label` — do not rely on the English default `Reset` in product UI |
+| **SHOULD** (FR) | Follow French grammar for labels and reset copy when the UI is localized |
+
+### Patterns
+
+**Simple pick list** — Options are place names or enum values. No header unless the trigger label is ambiguous.
+
+**Filter panel** — Header holds search or title; body uses `dropdown-list-items` with checkboxes; footer holds `Apply filters`; `reset` clears parent filter state.
+
+**Link rows** — Use the `label` slot to render `<a href="…">`; **Enter** on a focused row activates the link instead of emitting `update:modelValue`.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| List naming | Set `aria-label` or `aria-labelledby` on the listbox — `VJoyDropdown` passes the trigger’s generated id via `aria-labelledby` |
+| Role (options mode) | `role="listbox"` on `<ul>`; each row `role="option"` with `aria-selected` / `aria-disabled` |
+| Row name | `aria-label` and `title` use `option.label` |
+| Focus on mount | Selected option receives focus; scroller scrolls it into view |
+| Keyboard (built-in list) | **ArrowUp** / **ArrowDown** move focus; **Home** / **End** jump; **Enter** selects or activates link; **Space** prevented from scrolling page while row focused |
+| Keyboard (close) | **Escape** or **Tab** while focus is inside the listbox emits `close:dropdownList` |
+| Keyboard (custom slot) | When using `dropdown-list-items` without `options`, listbox patterns are not enforced — manage focus inside custom content |
+| Disabled options | `aria-disabled="true"`; not selectable on click |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { VJoyDropdownList, VJoyButton } from '@maltjoy/core-vue'
+
+interface StationOption {
+  id: string
+  label: string
+  value?: string
+  disabled?: boolean
+}
+
+const station = ref('toulouse')
+const open = ref(false)
+
+const stations: StationOption[] = [
+  { id: 'paris', label: 'Paris Montparnasse' },
+  { id: 'toulouse', label: 'Toulouse Matabiau' },
+  { id: 'bordeaux', label: 'Bordeaux Saint-Jean' },
+  { id: 'marseille', label: 'Marseille Saint-Charles', disabled: true },
+]
+
+function clearFilter() {
+  station.value = ''
+}
+</script>
+
+<template>
+  <!-- Built-in options + v-model -->
+  <VJoyDropdownList
+    v-model="station"
+    :options="stations"
+    aria-label="French stations"
+    width="300"
+    height="200"
+    size="medium"
+  />
+
+  <!-- Header, reset, and footer -->
+  <VJoyDropdownList
+    v-model="station"
+    :options="stations"
+    reset
+    reset-label="Clear selection"
+    width="280"
+    height="240"
+    aria-labelledby="station-picker-label"
+    @reset="clearFilter"
+  >
+    <template #dropdown-list-header>
+      <span id="station-picker-label">Choose a station</span>
+    </template>
+    <template #dropdown-list-footer>
+      <VJoyButton size="xxsmall" variant="main">Done</VJoyButton>
+    </template>
+  </VJoyDropdownList>
+
+  <!-- Custom body (no built-in keyboard listbox) -->
+  <VJoyDropdownList width="240" height="200" aria-label="Filter options">
+    <template #dropdown-list-items>
+      <!-- VJoyCheckboxGroup or other controls -->
+    </template>
+  </VJoyDropdownList>
+
+  <!-- Custom row label -->
+  <VJoyDropdownList v-model="station" :options="stations" aria-label="Stations">
+    <template #label="{ label, href }">
+      <a v-if="href" :href="href">{{ label }}</a>
+      <span v-else>{{ label }}</span>
+    </template>
+  </VJoyDropdownList>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyDropdownList` is already global.
+
+For trigger, positioning, and click-outside, wrap usage in `VJoyDropdown` instead of reimplementing those behaviors around the list alone.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyDropdown` | Full dropdown with trigger, overlay lifecycle, and focus management |
+| `VJoySelect` | Labeled single-select form field with native `<select>` semantics |
+| `VJoyCheckboxGroup` | Multi-select content inside `dropdown-list-items` |
+| `VJoyFilterBar` | Composed filter UI that embeds dropdown patterns |
+| `VJoyButton` | Footer actions and standalone triggers when not using `VJoyDropdown` |
+| `VJoyMenu` | Persistent navigation menus with `VJoyMenuItem` |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyDropdownList.dsds.json`](./JoyDropdownList.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Overflow / contextual menu from a trigger | `VJoyDropdown` | `VJoyDropdownList` without overlay parent |
+| List panel only (parent owns open/close) | `VJoyDropdownList` | `VJoyDropdown` with empty `dropdown-button` |
+| Labeled form single-select | `VJoySelect` | `VJoyDropdownList` mimicking a native select |
+| Multi-select filters with checkboxes | `VJoyDropdown` or `VJoyDropdownList` in custom overlay + `dropdown-list-items` | `options` array with fake checkbox markup |
+| Custom row content per option | `#label` scoped slot | `dropdown-list-item` slot (not wired) |
+
+### Hard rules
+
+1. **MUST** call `joy_get_component_info("VJoyDropdownList")` and/or read `JoyDropdownList.types.ts` before generating props.
+2. **MUST** give every `options` entry a unique `id` and a `label`.
+3. **MUST** bind `v-model` when single selection from `options` should persist.
+4. **MUST** set `aria-label` or `aria-labelledby` when no visible trigger labels the list.
+5. **MUST** handle `@reset` when `reset` is true — reset does not mutate parent state.
+6. **MUST** handle `@close:dropdown-list` when embedding in a custom overlay (close on Escape / Tab from list focus).
+7. **MUST NOT** invent props (`variant`, `direction`, `justify`, `open`, …) or size values outside `xsmall` | `small` | `medium`.
+8. **MUST NOT** override `.joy-dropdown-list` border, shadow, radius, or item heights in product CSS.
+9. **SHOULD** use `VJoyDropdown` instead of standalone list when trigger + click-outside are needed.
+10. **SHOULD** pass `width` / `height` as strings (pixel values without units in the prop value, e.g. `width="300"`).
+
+### Slot map
+
+| Slot | Typical content |
+| --- | --- |
+| `dropdown-list-header` | Title, search field, instructions |
+| `dropdown-list-items` | `VJoyCheckboxGroup`, custom markup (replaces built-in `options` list) |
+| `label` | Custom per-row content (text, links) |
+| `dropdown-list-footer` | `VJoyButton` Apply / Done |
+
+### Checklist
+
+- [ ] Correct component (`VJoyDropdownList` or named alternative)
+- [ ] Props / enums from MCP or types only
+- [ ] `options` rows have unique `id` + `label`
+- [ ] `v-model` bound when selection should persist
+- [ ] `aria-label` or `aria-labelledby` set for standalone list
+- [ ] `@reset` handler when `reset` is true
+- [ ] `@close:dropdown-list` wired when inside custom overlay
+- [ ] `#label` slot for row customization (not `dropdown-list-item`)
+- [ ] No invented props / no custom list chrome CSS
+- [ ] `size` matches surrounding trigger density
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyDropdownList.dsds.json`](./JoyDropdownList.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy | `anatomy` |
+| 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 |
+| Token sizing | `design-specifications` in JSON (`--dropdown-item-height`, form-size tokens) |

package/dist/doc/VJoyDropdownList/metadata.json

@@ -70,7 +70,7 @@
                   "type": "string",
                   "declarations": [
                     {
-                      "file": "/home/kevincarnaille/dev/design-system/packages/core-vue/src/components/JoyDropdownList/VJoyDropdownList.vue",
+                      "file": "/Users/pierrereynaud/Documents/Work/design-system/packages/core-vue/src/components/JoyDropdownList/VJoyDropdownList.vue",
                       "range": [
                         2376,
                         2387
@@ -88,7 +88,7 @@
                   "type": "string | undefined",
                   "declarations": [
                     {
-                      "file": "/home/kevincarnaille/dev/design-system/packages/core-vue/src/components/JoyDropdownList/VJoyDropdownList.vue",
+                      "file": "/Users/pierrereynaud/Documents/Work/design-system/packages/core-vue/src/components/JoyDropdownList/VJoyDropdownList.vue",
                       "range": [
                         2396,
                         2411
@@ -113,7 +113,7 @@
                   "type": "string",
                   "declarations": [
                     {
-                      "file": "/home/kevincarnaille/dev/design-system/packages/core-vue/src/components/JoyDropdownList/VJoyDropdownList.vue",
+                      "file": "/Users/pierrereynaud/Documents/Work/design-system/packages/core-vue/src/components/JoyDropdownList/VJoyDropdownList.vue",
                       "range": [
                         2420,
                         2434
@@ -131,7 +131,7 @@
                   "type": "string | undefined",
                   "declarations": [
                     {
-                      "file": "/home/kevincarnaille/dev/design-system/packages/core-vue/src/components/JoyDropdownList/VJoyDropdownList.vue",
+                      "file": "/Users/pierrereynaud/Documents/Work/design-system/packages/core-vue/src/components/JoyDropdownList/VJoyDropdownList.vue",
                       "range": [
                         2443,
                         2457
@@ -154,7 +154,7 @@
                   "type": "boolean | undefined",
                   "declarations": [
                     {
-                      "file": "/home/kevincarnaille/dev/design-system/packages/core-vue/src/components/JoyDropdownList/VJoyDropdownList.vue",
+                      "file": "/Users/pierrereynaud/Documents/Work/design-system/packages/core-vue/src/components/JoyDropdownList/VJoyDropdownList.vue",
                       "range": [
                         2516,
                         2535
@@ -185,7 +185,7 @@
                   "type": "boolean | undefined",
                   "declarations": [
                     {
-                      "file": "/home/kevincarnaille/dev/design-system/packages/core-vue/src/components/JoyDropdownList/VJoyDropdownList.vue",
+                      "file": "/Users/pierrereynaud/Documents/Work/design-system/packages/core-vue/src/components/JoyDropdownList/VJoyDropdownList.vue",
                       "range": [
                         2594,
                         2612
@@ -265,7 +265,7 @@
     },
     {
       "name": "dropdown-list-items",
-      "description": "Free slot in order to render any kind of component. Can be handy to use it with VJoyMultiCheckbox for instance."
+      "description": "Free slot in order to render any kind of component. Can be handy to use it with VJoyCheckboxGroup for instance."
     },
     {
       "name": "dropdown-list-item",