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

package/dist/doc/VJoyMenuItem/guideline.md

@@ -0,0 +1,352 @@
+---
+component: VJoyMenuItem
+status: draft
+language: en
+dsds: JoyMenuItem.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Menu item
+
+Use **`VJoyMenuItem`** when you need a single row inside a navigation menu — a labeled choice that navigates somewhere, fires an in-page action, or shows selection and status at a glance.
+
+Each item renders as a `role="menuitem"` list row with optional leading icon, required text label, and optional trailing status icon. The inner control can be a native link (`<a>`), a `<button>`, or a router component (`RouterLink`, `NuxtLink`) passed through the `type` prop.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyMenuItem` from `@maltjoy/core-vue` |
+| **Design** | [Figma — Joy components](https://www.figma.com/design/jfndp2QBJGS9yeuWbeGuvD/) |
+| **Storybook** | [VJoyMenu docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-navigation-vjoymenu--docs) (see **WithSubItem** story) |
+| **DSDS (machine)** | [`JoyMenuItem.dsds.json`](./JoyMenuItem.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyMenuItem")` — if unavailable, read `VJoyMenuItem.vue` and `JoyMenu.metadata.md` |
+
+> **MCP note:** Joy MCP may not return `VJoyMenuItem` API yet (docs generation is broken for this component). Use `VJoyMenuItem.vue`, `JoyMenu.metadata.md`, or Storybook **WithSubItem** as the source of truth until MCP is updated.
+
+---
+
+## When to use this component
+
+Use a menu item when building a **persistent navigation list** inside `VJoyMenu` — for example app sidebar links, station pickers, or settings sections where each row is a destination or action.
+
+`VJoyMenuItem` is the preferred way to declare menu rows (icons, current state, disabled rows, router links). Compose one or more items in the **default slot** of `VJoyMenu`.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Contextual overflow / action menu from a trigger | `VJoyDropdown` + `VJoyDropdownList` |
+| Labeled single-select form field | `VJoySelect` |
+| Tabbed content switching on the same surface | `VJoyTabs` |
+| Standalone CTA or form submit | `VJoyButton` |
+| Data list rows with rich left/right content | `VJoyListItem` |
+| Custom `<li>` markup with ad-hoc menu styling | Still use `VJoyMenuItem` + Joy tokens — don’t reinvent menu row chrome |
+
+> **Deprecated:** do not drive menu rows through `VJoyMenu`’s `items` prop for new work. That array API is deprecated — use `VJoyMenuItem` children in the default slot instead.
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| List row (`<li>`) | Yes | Outer `role="menuitem"` wrapper with `aria-label`, `aria-disabled`, and `aria-current` |
+| Inner control | Yes | `.joy-menu-item__inner` — `<a>`, `<button>`, router component, or `<div>` when `disabled` |
+| Label | Yes | Text from the `label` prop (`.joy-menu-item__label`) |
+| Leading icon | No | `VJoyIcon` when `icon` is set (`.joy-menu-item__icon-left`) |
+| Status icon | No | Trailing `VJoyIcon` when `status` is set (`.joy-menu-item__icon-right`); color via `statusColor` |
+| Focus ring | Yes | Inset `box-shadow` on inner `:focus` — don’t remove it in product CSS |
+
+### Default values
+
+- `type` defaults to **`'a'`** (native anchor)
+- `disabled` defaults to **`false`**
+- `current` defaults to **`false`**
+- `href`, `icon`, `status`, `statusColor`, and `linkProps` are optional
+
+Props, events, and composition: use Joy MCP (when available), `VJoyMenuItem.vue`, or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Link types
+
+| `type` | Inner element | Props / attrs |
+| --- | --- | --- |
+| `'a'` (default) | `<a href="…">` | `href` prop + native attrs via `$attrs` (`target`, `rel`, `data-*`, …) |
+| `'button'` | `<button type="button">` | Native button attrs via `$attrs`; emits `click` |
+| `RouterLink` / `NuxtLink` / custom component | Dynamic `:is="type"` | Pass routing props via `linkProps` (e.g. `{ to: '/' }`) |
+
+When `disabled` is true, the inner control becomes a **non-interactive `<div>`** — clicks do not emit `click`.
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Default | Neutral text (`--joy-color-neutral-60`); row is interactive |
+| Hover | Light secondary background (`--joy-color-secondary-10`) on the inner control |
+| Focus | Secondary background + inset information focus ring (`--joy-color-information-50`) |
+| Current | `current` prop — secondary background and secondary text color; `aria-current` on the row |
+| Disabled | Muted text, disabled background (`--joy-color-state-disabled-background`), `cursor: not-allowed`; inner is `<div>`; `aria-disabled="true"`; no `click` emission |
+
+Long labels truncate with ellipsis; the full string is available via the native `title` attribute on the row.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Composition
+
+- **MUST** place `VJoyMenuItem` inside `VJoyMenu` (default slot) so keyboard navigation and `role="menu"` semantics stay correct.
+- **MUST** set `aria-label` on `VJoyMenu` when the menu’s purpose isn’t obvious from visible context alone.
+- **SHOULD** use at most one `current` item per menu when indicating the active destination.
+- **SHOULD** order items logically — primary destinations first, destructive or rare actions last.
+
+### Implementation
+
+- **MUST** use only documented props from `VJoyMenuItem.vue` / `JoyMenu.metadata.md` — no invented props.
+- **MUST** style with Joy tokens — no custom `.joy-menu-item` chrome overrides.
+- **MUST** pass `href` when `type` is `'a'` and the row navigates.
+- **MUST** pass `linkProps` when `type` is `RouterLink`, `NuxtLink`, or another component.
+- **MUST NOT** use `VJoyMenu`’s deprecated `items` array for new menus.
+- **MUST NOT** hardcode row height — the component uses `--joy-form-field-height-medium`.
+- **SHOULD** pass native HTML attributes (`target`, `rel`, `data-test-id`, …) as attributes on `VJoyMenuItem` when `type` is `'a'` or `'button'` (they flow through `$attrs`).
+
+### Icons and status
+
+- **SHOULD** use `icon` for wayfinding (user, settings, section glyph) — not decoration alone.
+- **SHOULD** use `status` + `statusColor` for semantic feedback (check, warning, lock) — keep one trailing icon per row.
+- **MUST NOT** rely on icon color alone to convey meaning — the `label` must still describe the action or destination.
+
+### Interaction
+
+- **MUST** set `disabled` when the row must not activate; explain why elsewhere if the reason isn’t obvious.
+- **SHOULD** use `type="button"` + `@click` for in-page actions that do not navigate.
+- **SHOULD** use `type` router component + `linkProps` for SPA navigation instead of `<a>` + manual router pushes.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `VJoyMenu` + `VJoyMenuItem` slot children | Deprecated `items` prop on `VJoyMenu` |
+| `linkProps` with `NuxtLink` / `RouterLink` | Plain `<a>` + `@click` router hacks |
+| `current` for the active nav target | Multiple `current` rows without reason |
+| Concise `label` text (1–3 words) | Vague labels (`Click here`, `Menu`) |
+| `status` for lock / check / warning | Random decorative trailing icons |
+| Explain disabled rows when needed | Disabled row with no context |
+
+---
+
+## Content
+
+Menu items are scanned quickly. Labels must be short, parallel, and predictable.
+
+### Label formula
+
+**Navigation rows:** **noun or short noun phrase** — e.g. `Profile`, `Billing`, `Paris Montparnasse`.
+
+**Action rows** (`type="button"`): **verb or verb + object** — e.g. `Sign out`, `Export data`.
+
+Use **parallel grammar** across siblings (all nouns or all verbs — don’t mix styles in one menu).
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | `label` is required and becomes the accessible name (`aria-label` + `title`) |
+| **MUST** | Keep labels concise; overflow shows ellipsis — don’t rely on truncation for critical detail |
+| **MUST NOT** | Vague labels — ❌ `Click here`, ❌ `Options`, ❌ `Item 1` in product UI |
+| **MUST NOT** | Duplicate the parent menu title on every row when context is already clear |
+| **SHOULD** | 1–3 words per item |
+| **SHOULD** | Sentence case for multi-word labels |
+| **SHOULD** | Name destructive actions explicitly — ✅ `Delete project` · ❌ `Delete` alone in a mixed menu |
+| **SHOULD** | Start each item the same way (all verbs or all nouns) for scannability |
+
+### Patterns
+
+**App / settings navigation** — Noun labels: `Account`, `Notifications`, `Privacy`. Mark the active section with `current`.
+
+**Router-linked sidebar** — `:type="NuxtLink"` (or `RouterLink`) + `:link-props="{ to: '/path' }"`. Label names the destination page.
+
+**Status feedback** — Trailing `status` icon with `statusColor`: check for completed setup, lock for gated features, warning for attention needed. Label still states the destination.
+
+**Disabled rows** — Keep the label readable; use `status="lock"` when helpful. Explain gating in surrounding UI or a tooltip on a related control — not only via icon color.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Outer `<li role="menuitem">` inside `VJoyMenu`’s `role="menu"` list |
+| Name | From `label` (`aria-label` on the row; `title` for truncated text) |
+| Current page | `current` sets `aria-current` on the row and visible current styling |
+| Disabled | `aria-disabled="true"` on the row; inner becomes non-focusable `<div>` |
+| Keyboard | Arrow keys, Home, End, Enter, and Space are handled by parent `VJoyMenu` — don’t reimplement list keyboard logic on individual items |
+| Focus | Inner control shows visible focus ring — keep it in product CSS |
+| Icons | Leading/trailing icons are decorative when `label` is present — Joy icons default to `aria-hidden` where appropriate |
+| Links | Use real `<a href>` or router links — not clickable `<div>` except when `disabled` |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { VJoyMenu, VJoyMenuItem } from '@maltjoy/core-vue'
+
+// Nuxt example — use your app's NuxtLink import
+// import { NuxtLink } from '#components'
+</script>
+
+<template>
+  <VJoyMenu aria-label="Account sections">
+    <!-- Default: native link -->
+    <VJoyMenuItem label="Profile" href="/profile" icon="user" />
+
+    <!-- Current section -->
+    <VJoyMenuItem
+      label="Billing"
+      href="/billing"
+      icon="credit-card"
+      current
+      status="check-circle"
+      status-color="success"
+    />
+
+    <!-- Opens in new tab -->
+    <VJoyMenuItem
+      label="Help center"
+      href="https://help.malt.com"
+      target="_blank"
+      rel="noopener noreferrer"
+    />
+
+    <!-- In-page action -->
+    <VJoyMenuItem
+      label="Sign out"
+      type="button"
+      icon="logout"
+      @click="onSignOut"
+    />
+
+    <!-- SPA navigation (Nuxt) -->
+    <!--
+    <VJoyMenuItem
+      label="Dashboard"
+      :type="NuxtLink"
+      :link-props="{ to: '/' }"
+      icon="home"
+    />
+    -->
+
+    <!-- Disabled row -->
+    <VJoyMenuItem
+      label="Team settings"
+      disabled
+      icon="company-placeholder"
+      status="lock"
+    />
+  </VJoyMenu>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyMenuItem` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyMenu` | Parent list with keyboard navigation and `role="menu"` |
+| `VJoyDropdown` | Contextual menus opened from a trigger |
+| `VJoyDropdownList` | Option list UI without full menu semantics |
+| `VJoyIcon` | Icon primitive used for `icon` and `status` |
+| `VJoyButton` | Standalone actions outside a menu list |
+| `VJoyTabs` | Switching content panels on the same surface |
+| `VJoyTooltip` | Extra detail for disabled or icon-only adjacent controls |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyMenuItem.dsds.json`](./JoyMenuItem.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Row inside a nav / settings menu | `VJoyMenu` + `VJoyMenuItem` | Raw `<li>` with custom menu CSS |
+| Overflow menu from a button | `VJoyDropdown` | `VJoyMenu` for kebab menus |
+| SPA route in a menu | `VJoyMenuItem` + `:type="NuxtLink"` / `RouterLink` + `link-props` | `<a>` + `@click` router navigation |
+| External URL | `VJoyMenuItem` + `href` (default `type="a"`) | `type="button"` + window.location |
+| In-page menu action | `VJoyMenuItem` + `type="button"` + `@click` | `href="#"` + click handler |
+| Active nav destination | `current` on one item | Custom “selected” CSS classes |
+| Deprecated data-driven menu | `VJoyMenuItem` children | `VJoyMenu` `items` prop |
+
+### Hard rules
+
+1. **MUST** read `VJoyMenuItem.vue` and/or `JoyMenu.metadata.md` before generating props (`joy_get_component_info` may not work yet).
+2. **MUST** wrap items in `VJoyMenu` with an `aria-label` when context is not self-evident.
+3. **MUST** set `label` on every item — there is no default slot for label text.
+4. **MUST** use `linkProps` when `type` is a Vue/router component; use `href` + `$attrs` when `type` is `'a'`.
+5. **MUST** use `type="button"` for actions that emit `click` without navigation.
+6. **MUST NOT** invent props (`variant`, `size`, `selected`, `active`, …).
+7. **MUST NOT** override `.joy-menu-item` / `.joy-menu-item__inner` background, padding, height, or focus ring.
+8. **MUST NOT** use `VJoyMenu` `items` prop in new code.
+9. **SHOULD** set at most one `current` item per menu for active-route indication.
+10. **SHOULD** use kebab-case in templates for multi-word props (`status-color` → `statusColor`).
+
+### Documented props (from source)
+
+| Prop | Type / notes |
+| --- | --- |
+| `label` | `string` — **required** |
+| `href` | `string` — for `type="a"` |
+| `icon` | `TJoyIconsNames` — leading icon |
+| `current` | `boolean` — active / current destination |
+| `disabled` | `boolean` |
+| `status` | `TJoyIconsNames` — trailing status icon |
+| `statusColor` | `TJoyIconsColors` — trailing icon color |
+| `type` | `Component \| 'a' \| 'button'` — default `'a'` |
+| `linkProps` | `ComponentProps<T>` — for non-native `type` |
+
+**Event:** `click` — emitted on inner activation when not `disabled` (typically `type="button"`).
+
+### Checklist
+
+- [ ] Correct component (`VJoyMenuItem` inside `VJoyMenu`, or named alternative)
+- [ ] Props from source / metadata only — no invented props
+- [ ] `label` set on every row
+- [ ] `href` or `linkProps` matches `type` (link vs router vs button)
+- [ ] `current` used intentionally (≤ 1 per menu in most cases)
+- [ ] `disabled` rows explained when reason isn’t obvious
+- [ ] No custom `.joy-menu-item` chrome CSS
+- [ ] No deprecated `VJoyMenu` `items` array for new menus
+- [ ] Native attrs on `VJoyMenuItem` when using `'a'` or `'button'`
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyMenuItem.dsds.json`](./JoyMenuItem.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy / link types | `anatomy` |
+| States | `states` |
+| Best practices / content rules | `guidelines` (+ `content`) |
+| Accessibility | `accessibility` |
+| Examples | `sections` |
+| For agents | `agentDocumentBlocks` |
+| Props detail | `api` in JSON + Joy MCP (when available) |
+| Imports | `imports` in JSON |
+| Token sizing | `design-specifications` in JSON (`--joy-form-field-height-medium`, color tokens) |