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

package/dist/doc/VJoyCollapse/guideline.md

@@ -0,0 +1,362 @@
+---
+component: VJoyCollapse
+status: draft
+language: en
+dsds: JoyCollapse.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Collapse
+
+Use **`VJoyCollapse`** with **`VJoyCollapseItem`** children when related content should stay on the page but only expand on demand — FAQs, optional form sections, filter groups, or side-panel detail blocks.
+
+The container coordinates open state across items, supports **accordion** mode (one open panel at a time), optional **`v-model`** for programmatic control, and a visual **`mode`** (`default` or experimental `outline`).
+
+| | |
+| --- | --- |
+| **Code** | `VJoyCollapse` + `VJoyCollapseItem` from `@maltjoy/core-vue` |
+| **Design** | [ZeroHeight — Collapse](https://zeroheight.com/6bf479565/) (page id `4065429`) |
+| **Storybook** | [VJoyCollapse docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-buttons-vjoycollapse--docs) |
+| **DSDS (machine)** | [`JoyCollapse.dsds.json`](./JoyCollapse.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyCollapse")` · `joy_get_component_info("VJoyCollapseItem")` |
+
+---
+
+## When to use this component
+
+Use a collapse when users benefit from scanning **section titles first** and opening only what they need. Typical jobs: FAQ lists, advanced settings tucked under a heading, grouped filters, or dense side panels where full content would overwhelm the initial view.
+
+Each `VJoyCollapseItem` is an independent disclosure: a clickable summary (header, optional subheader, optional icon) and a panel with the main content. Use **`accordion`** when only one section should be open at a time (classic FAQ). Leave accordion off when several sections may stay open together.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Peer sections where every label should stay visible and one panel swaps in place | `VJoyTabs` |
+| A linear multi-step flow with progress | `VJoyStepper` |
+| Blocking focus on one decision or form | `VJoyDialog` |
+| A single show/hide block with no list of sections | A heading + conditional content, or one `VJoyCollapseItem` only when the Joy pattern is required |
+| Primary app or site navigation | App shell patterns (`VJoyMenu`, sidebar, header nav) |
+| Custom accordion markup / ad-hoc chevron rows | Still use `VJoyCollapse` + `VJoyCollapseItem` + Joy tokens |
+
+> **Naming:** there is no separate `VJoyAccordion` component. Set `accordion` on `VJoyCollapse` and bind `v-model`.
+
+---
+
+## How it works
+
+`VJoyCollapse` reads **`VJoyCollapseItem`** children from its default slot (including via `v-for`), forwards `mode`, and syncs open state either from each item’s `open` prop or from the parent’s `v-model` array.
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Collapse container | Yes | Root `.joy-collapse` — stacks items; adds dividers in `default` mode |
+| Collapse item | Yes (≥1) | `VJoyCollapseItem` — one disclosure per child |
+| Summary control | Yes | Clickable header row (`role="button"`) — toggles the panel |
+| Header | Yes | Title text (`header` prop on each item) |
+| Subheader | No | Secondary line under the header (`subheader` prop) |
+| Summary icon | No | Leading `VJoyIcon` (`summaryIcon` on the item) |
+| Header right slot | No | `collapse-header-right` — tags, badges, or actions before the chevron |
+| Preview slot | No | `collapse-preview` — short snippet visible while collapsed (outline mode) |
+| Chevron marker | Yes | `chevron-down` icon; rotates when open |
+| Detail panel | Yes | Default slot content; `role="region"` when open, labelled by item `id` |
+| Focus ring | Yes | Outline mode highlights border on focus — don’t remove in product CSS |
+
+### Default values
+
+- `accordion` on `VJoyCollapse` defaults to **`false`**
+- `modelValue` on `VJoyCollapse` defaults to **`[]`**
+- `mode` on `VJoyCollapse` defaults to **`default`** (passed to every item)
+- `open` on `VJoyCollapseItem` defaults to **`false`**
+- `header` on `VJoyCollapseItem` is **required**
+
+Props, events, and slots: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Open-state patterns
+
+**Uncontrolled (per item)** — set `open` on individual items. When `modelValue` is empty, the parent respects each item’s `open` prop.
+
+```vue
+<VJoyCollapse>
+  <VJoyCollapseItem header="Shipping" :open="true">…</VJoyCollapseItem>
+  <VJoyCollapseItem header="Billing">…</VJoyCollapseItem>
+</VJoyCollapse>
+```
+
+**Controlled (`v-model`)** — bind `v-model` to a `string[]` of open item keys. **Give each item a stable `id`**; if `id` is omitted, the **`header` string** is used as the key (fragile when copy changes).
+
+```vue
+<VJoyCollapse v-model="openSections">
+  <VJoyCollapseItem id="shipping" header="Shipping">…</VJoyCollapseItem>
+  <VJoyCollapseItem id="billing" header="Billing">…</VJoyCollapseItem>
+</VJoyCollapse>
+```
+
+**Accordion** — set `accordion` and use `v-model`. Opening one item closes the others; closing the active item yields an empty array.
+
+---
+
+## Variants
+
+Visual treatment is driven by **`mode`** on `VJoyCollapse` (inherited by items). Choose by layout context, not decoration.
+
+### `default`
+
+Stacked rows with **bottom borders** between items (`--joy-color-neutral-30`). Use in side panels, settings stacks, and inline FAQ lists where items should read as one continuous list.
+
+Avoid when each section should feel like a separate card (use `outline`).
+
+### `outline`
+
+**Experimental** — bordered cards (`--joy-core-radius-4`), hover/focus elevation, and active border (`--joy-color-secondary-50`). Use when sections need stronger separation or when pairing with `subheader`, `summaryIcon`, or `collapse-preview`.
+
+Design notes indicate this mode may become the default later — prefer it for new card-like layouts after checking with design.
+
+### Not in the API: separate item `mode`
+
+`VJoyCollapseItem` exposes `mode`, but the parent **`VJoyCollapse` `mode` prop is the supported way** to style a group. Don’t mix modes inside one collapse unless you have an explicit design exception.
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Collapsed (default) | Summary visible; panel hidden; chevron points down |
+| Expanded | Panel visible; chevron rotated 180°; `joy-collapse-item--open` on the item |
+| Hover (`outline`) | Border and shadow emphasize the card (pointer devices) |
+| Focus (`outline`) | Same border treatment as hover — keyboard users must see it |
+| Multiple open | Default when `accordion` is false — several panels may be open |
+| Accordion open | At most one panel open; previous panel closes on open |
+| Controlled open | `v-model` array lists ids (or headers) of open items |
+| Preview visible | `collapse-preview` slot content shown in the summary area while collapsed |
+
+There is **no disabled API** on collapse items. Hide sections users cannot access, or explain unavailability in the panel content.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Structure / selection
+
+- **MUST** compose `VJoyCollapse` with **`VJoyCollapseItem`** children — not hand-rolled disclosure rows.
+- **SHOULD** keep section count modest (roughly **3–8** items); beyond that, reconsider IA or use tabs/navigation.
+- **SHOULD** put the most important or frequently opened section first when order is flexible.
+- **MUST** use `accordion` + `v-model` when only one section may be open (FAQ pattern).
+- **MUST NOT** nest collapses more than one level deep without a strong content reason.
+
+### Implementation
+
+- **MUST** set a stable **`id`** on every `VJoyCollapseItem` when using `v-model` or accordion mode.
+- **MUST** use only documented props and `mode` values (`default`, `outline`) from MCP or types.
+- **MUST** style with Joy tokens — no custom `.joy-collapse-item` chrome overrides.
+- **MUST NOT** invent props (`size`, `variant`, `disabled`, …).
+- **SHOULD** prefer `v-model` over scattering `open` props when open state is shared or persisted.
+- **SHOULD** set `mode="outline"` on the parent for card-style sections; keep `default` for divider lists.
+
+### Slots and composition
+
+- **SHOULD** use `collapse-header-right` for status tags or counts — not for the only label of the section.
+- **SHOULD** use `collapse-preview` only for **short, scannable** summaries (chips, one line) — not full panel content.
+- **MUST NOT** put primary actions that belong in the page footer only inside a collapsed panel without a visible summary cue.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| Stable `id` + `v-model` for controlled state | Rely on `header` text as the model key when copy may change |
+| `accordion` for single-open FAQ | `accordion` without `v-model` |
+| Short parallel headers across items | Long questions as headers with no subheader |
+| `summaryIcon` when it reinforces category | Decorative icon on every row |
+| Joy spacing / border tokens | Hardcoded borders, radii, or chevron rotation CSS |
+
+---
+
+## Content
+
+Collapse copy lives in the **header** (always visible) and optional **subheader** / **preview**. Panel body copy follows normal page writing rules.
+
+### Header formula
+
+**Short noun phrase or tight question** — parallel grammar across items in the same collapse:
+
+- ✅ Shipping address  
+- ✅ Payment method  
+- ✅ How do I cancel my subscription?  
+
+Use **sentence case**. FAQ sets may use questions; settings stacks usually use labels.
+
+### Subheader formula
+
+**One line of context** under the header — eligibility, scope, or “last updated” — not a repeat of the header:
+
+- ✅ Header: `Notifications` · Subheader: `Email and push`  
+- ❌ Subheader repeats the header verbatim  
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | Every item has a **`header`** — the summary control has no other accessible name |
+| **MUST** | Headers stay **distinct** within the set — no two items that differ only by punctuation |
+| **MUST NOT** | Use “Click to expand” or “Show more” as the only header text |
+| **MUST NOT** | Hide critical warnings only inside collapsed content without a clear header cue |
+| **SHOULD** | Keep headers **≤ 60 characters**; move detail into subheader or panel |
+| **SHOULD** | Use parallel structure across items (all questions, or all labels) |
+| **SHOULD** | Put counts or status in `collapse-header-right` (`VJoyTag`) when they help scanning |
+| **SHOULD** (FR) | Follow French grammar for questions and articles when localized |
+
+### Patterns
+
+**FAQ** — `accordion` + `v-model`; question as `header`; answer in the default slot. Open the first item only if it is the top question.
+
+**Advanced settings** — `default` mode; neutral headers (`Advanced options`); sensitive fields stay in the panel.
+
+**Filter groups** — Multiple sections may stay open; use `collapse-preview` in `outline` mode to show active filter chips when collapsed.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Summary role | `role="button"` on the summary row — not a native `<button>` |
+| Panel role | `role="region"` when open, associated via `aria-labelledby` to the item’s `id` |
+| Naming | Accessible name comes from **`header`** text |
+| Keyboard | **Enter** on the focused summary toggles open/closed; **Tab** moves between summaries |
+| Focus | Preserve visible focus styling in `outline` mode — don’t remove border/shadow on `:focus` |
+| Icons | `summaryIcon` and chevron are decorative (`aria-hidden` on the leading icon) |
+| `id` | **Set `id` on each item** so the open panel is correctly labelled |
+| Expand state | Chevron rotation is visual only — ensure header text makes open/closed state clear in context |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { VJoyCollapse, VJoyCollapseItem, VJoyTag } from '@maltjoy/core-vue'
+
+const openFaq = ref(['billing'])
+const openFilters = ref(['status', 'location'])
+</script>
+
+<template>
+  <!-- Default list -->
+  <VJoyCollapse>
+    <VJoyCollapseItem header="General" :open="true">
+      General settings content
+    </VJoyCollapseItem>
+    <VJoyCollapseItem header="Security">
+      Security settings content
+    </VJoyCollapseItem>
+  </VJoyCollapse>
+
+  <!-- Accordion FAQ with v-model -->
+  <VJoyCollapse v-model="openFaq" :accordion="true">
+    <VJoyCollapseItem id="shipping" header="When will my order ship?">
+      Orders ship within 2 business days.
+    </VJoyCollapseItem>
+    <VJoyCollapseItem id="billing" header="How do I update billing?">
+      Open account settings → Billing.
+    </VJoyCollapseItem>
+  </VJoyCollapse>
+
+  <!-- Outline mode with header actions -->
+  <VJoyCollapse v-model="openFilters" mode="outline">
+    <VJoyCollapseItem id="status" header="Status" summary-icon="filter">
+      <template #collapse-header-right>
+        <VJoyTag label="2 active" size="small" />
+      </template>
+      Filter controls…
+    </VJoyCollapseItem>
+    <VJoyCollapseItem id="location" header="Location" summary-icon="filter">
+      Location filter controls…
+    </VJoyCollapseItem>
+  </VJoyCollapse>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyCollapse` and `VJoyCollapseItem` are already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyCollapseItem` | Required child — header, panel, slots, and per-item props |
+| `VJoyTabs` | Peer sections with always-visible tab labels |
+| `VJoyTag` | Status or count in `collapse-header-right` |
+| `VJoyTagsList` | Preview chips in `collapse-preview` |
+| `VJoyIcon` | Icons referenced by `summaryIcon` |
+| `VJoyDialog` | Blocking confirmation or short focused task |
+| `VJoyStepper` | Linear steps with progress |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyCollapse.dsds.json`](./JoyCollapse.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Expandable sections on one surface | `VJoyCollapse` + `VJoyCollapseItem` | Custom chevron `<motion.div>` lists |
+| Only one open section (FAQ) | `VJoyCollapse` with `accordion` + `v-model` | Multiple `open` props without parent sync |
+| Swap peer panels with visible tabs | `VJoyTabs` | `VJoyCollapse` for primary nav |
+| Card-style expandable blocks | `VJoyCollapse` `mode="outline"` | Custom bordered accordions |
+| Single inline show/hide | One `VJoyCollapseItem` or conditional `v-if` | Full collapse for one trivial line |
+
+### Hard rules
+
+1. **MUST** call `joy_get_component_info("VJoyCollapse")` and `joy_get_component_info("VJoyCollapseItem")` (or read types) before generating props.
+2. **MUST** emit **`VJoyCollapseItem`** inside **`VJoyCollapse`** default slot — one child per section.
+3. **MUST** set **`id`** on every item when using `v-model` or `accordion`.
+4. **MUST** bind `v-model` (string array) when controlling open state from the parent.
+5. **MUST** set `accordion` when only one item may be open.
+6. **MUST NOT** invent props (`size`, `variant`, `disabled`, …).
+7. **MUST NOT** override `.joy-collapse-item` borders, padding, radius, or chevron styles.
+8. **SHOULD** set `mode` on `VJoyCollapse` (not per-item) for consistent styling.
+9. **SHOULD** use `summaryIcon` only with valid Joy icon names from MCP.
+
+### Checklist
+
+- [ ] `VJoyCollapse` + one `VJoyCollapseItem` per section
+- [ ] Stable `id` on each item when using `v-model` or `accordion`
+- [ ] `accordion` + `v-model` for single-open FAQ
+- [ ] `mode` is `default` or `outline` only
+- [ ] Props from MCP / types — no invented enums
+- [ ] No custom collapse chrome CSS
+- [ ] Headers short, parallel, and meaningful
+- [ ] `collapse-preview` stays short; full content in default slot
+- [ ] Critical info not hidden only inside collapsed panels without header cue
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyCollapse.dsds.json`](./JoyCollapse.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy | `anatomy` |
+| Variants (`mode`) | `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 styling | `design-specifications` in JSON (`--joy-color-neutral-30`, `--joy-core-radius-4`, spacing tokens) |