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

package/dist/doc/VJoyMenu/guideline.md

@@ -0,0 +1,304 @@
+---
+component: VJoyMenu
+status: draft
+language: en
+dsds: JoyMenu.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Menu
+
+Use **`VJoyMenu`** when the user needs a **persistent vertical list of navigation destinations** — typically the sidebar in an app shell built with `VJoyTemplate`.
+
+Compose it with **`VJoyMenuItem`** children for links, buttons, or router-aware navigation. Each item can show a leading icon, a trailing status icon, a current-page state, and disabled styling. Keyboard navigation (arrow keys, Home/End, Enter) is built in.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyMenu` + `VJoyMenuItem` from `@maltjoy/core-vue` |
+| **Design** | [ZeroHeight — Menu](https://zeroheight.com/6bf479565/p/955426-menu) |
+| **Storybook** | [VJoyMenu docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-navigation-vjoymenu--docs) |
+| **DSDS (machine)** | [`JoyMenu.dsds.json`](./JoyMenu.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyMenu")` · `joy_get_component_info("VJoyMenuItem")` |
+
+---
+
+## When to use this component
+
+Use a menu when users move between **sections or routes** from a fixed sidebar — for example app settings areas, account navigation, or funnel step lists inside `VJoyTemplate`.
+
+`VJoyMenuItem` supports plain anchors (`href`), buttons (`type="button"`), and framework links (`RouterLink` / `NuxtLink` via `type` + `linkProps`). Mark the active destination with `current`.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| A contextual panel that opens from a trigger (overflow, filters) | `VJoyDropdown` |
+| Switching peer content panels on the same page | `VJoyTabs` |
+| Choosing one value inside a labeled form field | `VJoySelect` |
+| Short hover-only hints | `VJoyTooltip` |
+| Main content layout chrome | `VJoyPanel` (not as a wrapper around the menu) |
+| Custom `<ul>` / sidebar markup with ad-hoc CSS | Still use `VJoyMenu` + `VJoyMenuItem` + Joy tokens |
+
+> **Deprecated:** do not use the `items` prop on `VJoyMenu` for new work. Prefer `VJoyMenuItem` in the default slot. The `menu-item` slot only applies to the deprecated `items` API.
+
+---
+
+## How it works
+
+`VJoyMenu` renders a bordered `<ul role="menu">`. Each `VJoyMenuItem` renders a `<li role="menuitem">` with an inner interactive element (`<a>`, `<button>`, or a custom link component).
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Menu list (`VJoyMenu`) | Yes | Root `<ul>` with border, radius, and keyboard handling |
+| `aria-label` | Yes* | Accessible name for the menu (`ariaLabel` prop) — required when no visible heading labels the list |
+| `VJoyMenuItem` (default slot) | Yes (preferred) | One row per destination |
+| Leading icon | No | `icon` on `VJoyMenuItem` |
+| Label | Yes | Primary text on each item (`label` prop) |
+| Status icon | No | Trailing `status` + optional `statusColor` (check, warning, lock, …) |
+| Current indicator | No | `current` highlights the active destination (`aria-current`) |
+| `menu-item` slot | No | Custom inner content per row — **only** for deprecated `items` prop |
+
+### Default values
+
+- `items` defaults to **`[]`** (deprecated — prefer slot composition)
+- `VJoyMenuItem` `type` defaults to **`"a"`** (anchor)
+- `disabled` defaults to **`false`**
+- `current` defaults to **`false`**
+
+Props, events, and slots: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Visual treatment
+
+There is **no `variant` or `size` prop**. Item height, padding, colors, and border radius come from Joy tokens inside the component (e.g. `--joy-form-field-height-medium`, `--joy-core-radius-3`) — **don’t hardcode menu item heights or border colors** in product CSS.
+
+The list uses `--menu-item-min-width: 120px` internally. Long labels truncate with ellipsis; the full label is available via the native `title` attribute.
+
+### App shell placement
+
+In Malt apps, `VJoyMenu` belongs in **`VJoyTemplate`’s `#template-sidebar` slot** (enforced by the `require-vjoymenu-template-sidebar` ESLint rule). Do **not** nest `VJoyMenu` inside `VJoyPanel` (`no-vjoymenu-vjoypanel` rule) — the menu and panel serve different layout roles.
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Default | Neutral text; row is interactive |
+| Hover | Secondary background highlight (pointer devices) |
+| Focus | Inset focus ring on the inner control; current row also uses secondary background |
+| Current (`current`) | Secondary background and text color — marks the active page/section |
+| Disabled | Muted text, disabled background, `cursor: not-allowed`; not clickable |
+| Keyboard active (deprecated `items` mode) | `aria-activedescendant` tracks the focused row while arrowing |
+| Link item | Default `type="a"` or router link navigates on click / Enter |
+| Button item | `type="button"` fires `@click` on `VJoyMenuItem` without navigation |
+
+When a disabled item is visible, **explain why** nearby (tooltip or helper text) if the reason is not obvious from context.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Placement and hierarchy
+
+- **MUST** place `VJoyMenu` inside `VJoyTemplate` `#template-sidebar` in app-shell layouts.
+- **MUST NOT** nest `VJoyMenu` inside `VJoyPanel`.
+- **SHOULD** mark exactly one item `current` for the active route or section (when applicable).
+- **SHOULD** keep the menu list focused on navigation — avoid embedding heavy forms or multi-step panels inside menu rows.
+
+### Composition
+
+- **MUST** use `VJoyMenuItem` children for new work — not the deprecated `items` prop.
+- **MUST** set `aria-label` on `VJoyMenu` when the sidebar has no visible heading that names the list.
+- **SHOULD** use `type="button"` only when the row triggers an in-page action without navigation.
+- **SHOULD** use `RouterLink` / `NuxtLink` (`type` + `linkProps`) for SPA navigation instead of full page reloads.
+- **SHOULD** use `status` icons sparingly — completion, warning, or lock states users must notice at a glance.
+
+### Implementation
+
+- **MUST** use only documented prop values (MCP / `JoyMenu.types.ts` / `VJoyMenuItem` props).
+- **MUST** style with Joy tokens — no custom `.joy-menu-list` or `.joy-menu-item` chrome overrides.
+- **MUST NOT** invent props (`variant`, `size`, `open`, …).
+- **MUST NOT** use `VJoyMenu` for transient overlay menus — use `VJoyDropdown`.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `VJoyMenu` + `VJoyMenuItem` in `#template-sidebar` | `items` prop for new screens |
+| `current` on the active route | Multiple `current` items for one section |
+| `RouterLink` / `NuxtLink` for in-app nav | Raw `<a href>` that reloads the SPA unnecessarily |
+| `aria-label` when no visible list title | Unnamed menu for screen-reader users |
+| `status` for lock / warning / done | Decorative status icons on every row |
+
+---
+
+## Content
+
+Menu items are navigation labels. They should be scannable at a glance and parallel in grammar.
+
+### Label formula
+
+**Navigation items:** **short noun or noun phrase** naming the destination — e.g. `Dashboard`, `Billing`, `Team members`.
+
+**Action rows (`type="button"`):** **infinitive verb + noun** when the row triggers an action — e.g. `Sign out`, `Create project`.
+
+**Status context:** rely on the `status` icon + `statusColor` for lock/warning/done; don’t repeat the same meaning in the label unless needed for clarity.
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | Each `label` is unique within the menu |
+| **MUST** | Labels stay concise — long text truncates with ellipsis (`title` shows the full string) |
+| **MUST** | Disabled items include context elsewhere if the reason isn’t obvious |
+| **MUST NOT** | Vague labels — ❌ `Click here`, ❌ `Menu item` |
+| **MUST NOT** | Duplicate the section heading on every row when the group context is clear |
+| **SHOULD** | ≤ 3 words per label where possible |
+| **SHOULD** | Sentence case for multi-word labels |
+| **SHOULD** | Parallel grammar across siblings (`Overview`, `Settings`, `Billing` — not mixed verb/noun styles) |
+| **SHOULD** | Localize labels — menu copy is user-facing product UI |
+
+### Patterns
+
+**App sidebar** — Group related destinations under `VJoyTemplate` sidebar chrome (headings outside the menu if needed). One `current` item matching the active route.
+
+**Funnel / step list** — Each row is a step name (`Company details`, `Payment`). Use `status="check-circle"` + `statusColor="success"` for completed steps, `status="lock"` for locked future steps.
+
+**Mixed link + action** — Navigation rows use default `type="a"` or router links; a final `Sign out` row uses `type="button"`.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Menu role | `role="menu"` on the `<ul>`; each row `role="menuitem"` |
+| Name | `aria-label` on `VJoyMenu` when no visible heading names the list |
+| Current page | `aria-current` on the item with `current` |
+| Disabled | `aria-disabled="true"`; not activatable |
+| Row name | `aria-label` and `title` from each item’s `label` |
+| Keyboard (list focus) | **ArrowDown** / **ArrowUp** move between enabled items; **Home** / **End** jump to first/last; **Enter** activates the focused row (clicks inner link/button); **Tab** clears active descendant tracking |
+| Space | Prevented from scrolling when an item is focused (deprecated `items` keyboard path) |
+| Focus ring | Visible inset ring on focused items — don’t remove in product CSS |
+| Icons | Leading/trailing icons are decorative when the label conveys meaning (Joy default) |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { VJoyMenu, VJoyMenuItem } from '@maltjoy/core-vue'
+import { NuxtLink } from '#components'
+</script>
+
+<template>
+  <!-- Preferred: VJoyMenuItem composition inside app shell -->
+  <VJoyTemplate>
+    <template #template-sidebar>
+      <VJoyMenu aria-label="Account navigation">
+        <VJoyMenuItem icon="user" label="Profile" href="/account/profile" />
+        <VJoyMenuItem icon="billing" label="Billing" href="/account/billing" current />
+        <VJoyMenuItem
+          icon="team"
+          label="Team members"
+          :type="NuxtLink"
+          :link-props="{ to: '/account/team' }"
+        />
+        <VJoyMenuItem
+          label="Security"
+          status="warning"
+          status-color="warning"
+          href="/account/security"
+        />
+        <VJoyMenuItem label="Archived" disabled icon="company-placeholder" status="lock" />
+        <VJoyMenuItem type="button" label="Sign out" @click="/* handle sign out */" />
+      </VJoyMenu>
+    </template>
+
+    <template #template-main>
+      <!-- page content -->
+    </template>
+  </VJoyTemplate>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyMenu` / `VJoyMenuItem` are already global. For Vue Router, pass `RouterLink` as `type` with `link-props="{ to: '...' }"` the same way as `NuxtLink` in Storybook.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyMenuItem` | Each row inside `VJoyMenu` (required for new work) |
+| `VJoyTemplate` | App shell with `#template-sidebar` slot for the menu |
+| `VJoyDropdown` | Contextual menus opened from a trigger |
+| `VJoyTabs` | Peer content panels on one page |
+| `VJoyPanel` | Main or sidebar content blocks — not as a parent of `VJoyMenu` |
+| `VJoyIcon` | Icons on menu items (`icon`, `status`) |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyMenu.dsds.json`](./JoyMenu.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Persistent sidebar / app navigation | `VJoyMenu` + `VJoyMenuItem` | `VJoyDropdown` |
+| Overflow menu from a button | `VJoyDropdown` | `VJoyMenu` |
+| Tab panels on one page | `VJoyTabs` | `VJoyMenu` for section switching |
+| Form single-select | `VJoySelect` | `VJoyMenu` |
+| SPA route link | `VJoyMenuItem` + `RouterLink`/`NuxtLink` | Raw `<li><a>` lists |
+
+### Hard rules
+
+1. **MUST** call `joy_get_component_info("VJoyMenu")` and `joy_get_component_info("VJoyMenuItem")` before generating props.
+2. **MUST** compose menus with `VJoyMenuItem` in the default slot — not the deprecated `items` prop.
+3. **MUST** set `aria-label` on `VJoyMenu` when no visible heading names the list.
+4. **MUST** place `VJoyMenu` in `VJoyTemplate` `#template-sidebar` for app-shell layouts.
+5. **MUST NOT** nest `VJoyMenu` inside `VJoyPanel`.
+6. **MUST NOT** invent props (`variant`, `size`, `open`, …) or override `.joy-menu-list` / `.joy-menu-item` chrome.
+7. **SHOULD** set `current` on the item matching the active route.
+8. **SHOULD** use `type="button"` only for non-navigation actions (e.g. sign out).
+
+### Checklist
+
+- [ ] Correct component (`VJoyMenu` + `VJoyMenuItem`, or named alternative)
+- [ ] Props from MCP / types only — no `items` prop on new code
+- [ ] `aria-label` on the menu when needed
+- [ ] `#template-sidebar` placement in `VJoyTemplate` layouts
+- [ ] Not nested inside `VJoyPanel`
+- [ ] At most one `current` item per logical section
+- [ ] Router links use `type` + `linkProps`, not bare `href` reloads in SPAs
+- [ ] No invented props / no custom menu chrome CSS
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyMenu.dsds.json`](./JoyMenu.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy | `anatomy` |
+| Visual treatment (no variants/sizes) | `design-specifications` |
+| 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/VJoyMenu/metadata.json

@@ -27,7 +27,7 @@
                   "type": "string | undefined",
                   "declarations": [
                     {
-                      "file": "/home/kevincarnaille/dev/design-system/packages/core-vue/src/components/JoyMenu/JoyMenu.types.ts",
+                      "file": "/Users/pierrereynaud/Documents/Work/design-system/packages/core-vue/src/components/JoyMenu/JoyMenu.types.ts",
                       "range": [
                         80,
                         92
@@ -52,7 +52,7 @@
                   "type": "string",
                   "declarations": [
                     {
-                      "file": "/home/kevincarnaille/dev/design-system/packages/core-vue/src/components/JoyMenu/JoyMenu.types.ts",
+                      "file": "/Users/pierrereynaud/Documents/Work/design-system/packages/core-vue/src/components/JoyMenu/JoyMenu.types.ts",
                       "range": [
                         97,
                         111
@@ -70,7 +70,7 @@
                   "type": "string | undefined",
                   "declarations": [
                     {
-                      "file": "/home/kevincarnaille/dev/design-system/packages/core-vue/src/components/JoyMenu/JoyMenu.types.ts",
+                      "file": "/Users/pierrereynaud/Documents/Work/design-system/packages/core-vue/src/components/JoyMenu/JoyMenu.types.ts",
                       "range": [
                         116,
                         130
@@ -88,7 +88,7 @@
                   "type": "JoyIconsId | undefined",
                   "declarations": [
                     {
-                      "file": "/home/kevincarnaille/dev/design-system/packages/core-vue/src/components/JoyMenu/JoyMenu.types.ts",
+                      "file": "/Users/pierrereynaud/Documents/Work/design-system/packages/core-vue/src/components/JoyMenu/JoyMenu.types.ts",
                       "range": [
                         135,
                         153
@@ -123,16 +123,16 @@
                       "\"arrow-right\"",
                       "\"art\"",
                       "\"axa-logo\"",
-                      "\"badge-recommended-hover\"",
-                      "\"badge-recommended\"",
                       "\"ban\"",
                       "\"bank\"",
                       "\"bars\"",
                       "\"bell\"",
+                      "\"bike\"",
                       "\"block-shield\"",
                       "\"bricks\"",
-                      "\"briefcase-hover\"",
                       "\"briefcase\"",
+                      "\"building-column\"",
+                      "\"business-suitcase\"",
                       "\"calendar\"",
                       "\"camcorder\"",
                       "\"camera-device\"",
@@ -159,12 +159,13 @@
                       "\"clock\"",
                       "\"cloud-upload\"",
                       "\"code\"",
+                      "\"colaborator-add\"",
                       "\"communication\"",
                       "\"company-placeholder\"",
+                      "\"computer\"",
                       "\"conditions\"",
                       "\"conference\"",
                       "\"contact\"",
-                      "\"cookie\"",
                       "\"cost-plus\"",
                       "\"creditcard\"",
                       "\"cross\"",
@@ -184,17 +185,19 @@
                       "\"eye\"",
                       "\"facebook\"",
                       "\"favorite-add\"",
+                      "\"favotite-add\"",
                       "\"fee\"",
                       "\"file-check\"",
                       "\"file-pdf\"",
                       "\"file\"",
                       "\"five-day\"",
                       "\"flag\"",
+                      "\"folder-arrow-down\"",
+                      "\"folder-text\"",
                       "\"freelancer-placeholder\"",
                       "\"fullscren\"",
+                      "\"furniture\"",
                       "\"gasoline\"",
-                      "\"globe-hover\"",
-                      "\"globe\"",
                       "\"google\"",
                       "\"granular-report\"",
                       "\"graph-high\"",
@@ -211,7 +214,6 @@
                       "\"home\"",
                       "\"ico-list\"",
                       "\"identity-switch\"",
-                      "\"image\"",
                       "\"info-circle\"",
                       "\"instagram\"",
                       "\"insurance\"",
@@ -220,7 +222,6 @@
                       "\"legal-check\"",
                       "\"legal\"",
                       "\"linkedin\"",
-                      "\"list-file\"",
                       "\"list\"",
                       "\"location\"",
                       "\"lock\"",
@@ -236,18 +237,16 @@
                       "\"money\"",
                       "\"mood-bad\"",
                       "\"mood-good\"",
-                      "\"newspaper\"",
+                      "\"moped\"",
+                      "\"motorcycle\"",
                       "\"open-conversation\"",
                       "\"paperclip\"",
                       "\"pen\"",
                       "\"pencil\"",
                       "\"phone\"",
-                      "\"plane-full\"",
                       "\"plus-circle\"",
                       "\"pound-circle\"",
                       "\"print\"",
-                      "\"profile-picture-hover\"",
-                      "\"profile-picture\"",
                       "\"projectmanager-agile\"",
                       "\"qr-code\"",
                       "\"question-circle\"",
@@ -273,15 +272,13 @@
                       "\"sort-asc\"",
                       "\"sort-desc\"",
                       "\"sparkle\"",
-                      "\"sparkles\"",
                       "\"star-fill\"",
                       "\"star-half\"",
-                      "\"star-message\"",
                       "\"star\"",
-                      "\"super-malter\"",
                       "\"swipe\"",
                       "\"switch\"",
                       "\"sync-reset\"",
+                      "\"sync\"",
                       "\"tab-inverted\"",
                       "\"tab\"",
                       "\"taxi\"",
@@ -301,6 +298,9 @@
                       "\"user-lighter\"",
                       "\"user-remove\"",
                       "\"user\"",
+                      "\"users-add\"",
+                      "\"users-check\"",
+                      "\"users-remove\"",
                       "\"users\"",
                       "\"video-camera\"",
                       "\"videogame\"",
@@ -332,7 +332,7 @@
                   "type": "boolean | undefined",
                   "declarations": [
                     {
-                      "file": "/home/kevincarnaille/dev/design-system/packages/core-vue/src/components/JoyMenu/JoyMenu.types.ts",
+                      "file": "/Users/pierrereynaud/Documents/Work/design-system/packages/core-vue/src/components/JoyMenu/JoyMenu.types.ts",
                       "range": [
                         158,
                         176
@@ -363,7 +363,7 @@
                   "type": "boolean | undefined",
                   "declarations": [
                     {
-                      "file": "/home/kevincarnaille/dev/design-system/packages/core-vue/src/components/JoyMenu/JoyMenu.types.ts",
+                      "file": "/Users/pierrereynaud/Documents/Work/design-system/packages/core-vue/src/components/JoyMenu/JoyMenu.types.ts",
                       "range": [
                         219,
                         238