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

package/dist/doc/VJoySelectableItem/guideline.md

@@ -0,0 +1,351 @@
+---
+component: VJoySelectableItem
+status: deprecated
+language: en
+dsds: JoySelectableItem.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Selectable item
+
+Use **`VJoySelectableItem`** when a choice should look like a **selectable tile** — a bordered card the user clicks to select or deselect — rather than a classic radio circle or checkbox row.
+
+In single-selection mode it behaves like a radio (one value per `name` group). In multi-selection mode it embeds `VJoyCheckbox` inside the tile. In product code, compose items almost always through **`VJoySelectableItemGroup`**; use the item alone only when you own grouping, legend, and validation yourself.
+
+> **Deprecated:** `VJoySelectableItem` and `VJoySelectableItemGroup` are deprecated. For new work, prefer `VJoyRadio` / `VJoyRadioGroup` (single choice), `VJoyCheckboxCard` (card-style booleans / multi-select), or `VJoyButtonCard` (navigation or action, not value selection). Keep this component only for maintaining existing flows until migration.
+
+| | |
+| --- | --- |
+| **Code** | `VJoySelectableItem` from `@maltjoy/core-vue` |
+| **Design** | [ZeroHeight — Selectable item](https://zeroheight.com/6bf479565/p/24f9a1-selectable-item) |
+| **Storybook** | [VJoySelectableItemGroup docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-forms-vjoyselectableitemgroup--docs) (`VJoySelectableItem` is a subcomponent) |
+| **DSDS (machine)** | [`JoySelectableItem.dsds.json`](./JoySelectableItem.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoySelectableItem")` (when indexed) — until then, read `VJoySelectableItem.vue` and `VJoySelectableItem.types.ts` |
+
+---
+
+## When to use this component
+
+Use a selectable item when options should read as **peer tiles** in a horizontal or wrapped row — for example picking a plan cadence, a delivery speed, or a small set of filters where each option has a short label and optional sublabel.
+
+Tiles work best with **2–5** options visible at once. Pair them inside `VJoySelectableItemGroup` so the fieldset, group label, `v-model:value`, and `invalid` / `errorMessage` are handled consistently.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| New feature work (any card picker) | `VJoyRadio` + `outline`, `VJoyCheckboxCard`, or `VJoyButtonCard` per interaction type |
+| Exactly one choice, compact list (no tile chrome) | `VJoyRadio` inside `VJoyRadioGroup` |
+| Multiple independent checkboxes in a list | `VJoyCheckbox` / `VJoyCheckboxGroup` or `VJoyCheckboxCard` |
+| Long or searchable option lists | `VJoySelect` |
+| Card that navigates or runs an action | `VJoyButtonCard` |
+| Custom clickable `<div>` tiles | Still use a Joy selection component + tokens — don’t reinvent tile chrome |
+
+> **Removed from the API:** the `ai` visual variant existed in older releases and has been removed. Do not emit `variant="ai"` or custom AI tile styling on this component.
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Wrapper | Yes | `.joy-selectable-item__wrapper` — click target and focus orchestration |
+| Native control | Yes* | Hidden `<input type="radio">` when `multiple` is false; `VJoyCheckbox` when `multiple` is true |
+| Tile surface | Yes | `.joy-selectable-item` — bordered, centered label area |
+| Primary label | Yes | Default slot (single mode) or checkbox label slot (multiple mode) |
+| Sublabel | No | `selectable-item-sublabel` slot or `subLabel` prop — stays normal weight when selected |
+| Focus ring | Yes | Outline on the tile when the native control is focused — don’t remove it in product CSS |
+
+### Selection modes
+
+Controlled by the `multiple` prop (usually set by `VJoySelectableItemGroup`).
+
+| Mode | `multiple` | Control | Model on `@update:checked` |
+| --- | --- | --- | --- |
+| Single | `false` (default) | Hidden radio + `<label for="…">` | Emits the option `value` when selected; emits empty string when the user clicks the already-selected tile (deselect) |
+| Multiple | `true` | `VJoyCheckbox` with `display-focus="false"` | Emits boolean checked state (group aggregates into a `value` array) |
+
+### Default values
+
+- `disabled` defaults to **`false`**
+- `invalid` defaults to **`false`**
+- `multiple` defaults to **`false`**
+- `required` defaults to **`false`**
+- `id` — auto-generated via Vue `useId()` when omitted; **SHOULD** set explicitly when not used inside a group
+- `checked` — controlled from parent / group; no implicit default in the component
+
+Props, events, and slots: use Joy MCP (when available), Storybook, or `VJoySelectableItem.vue` — this page focuses on **when** and **how**, not a full API dump.
+
+### Grouping
+
+- **SHOULD** render selectable items only inside `VJoySelectableItemGroup` in product forms.
+- **MUST** give siblings the same `name` in single-selection mode so the browser treats them as one radio group.
+- **MUST** set a distinct `value` (and stable `id`) per tile.
+- Set group-level `invalid` and `errorMessage` on `VJoySelectableItemGroup`; the group forwards `invalid` to each item.
+
+---
+
+## Sizes
+
+There is **no `size` prop**. Tile dimensions come from Joy tokens inside `JoySelectableItem.scss` — **don’t hardcode tile width or height** in apps.
+
+| Aspect | Guidance |
+| --- | --- |
+| Min height | `--selectable-item-min-height` (54px) on single-selection tiles |
+| Default width | `--selectable-item-flex-rule: 0 0 215px` per tile in a single-selection group |
+| Full-width row | Set `fullWidth` on `VJoySelectableItemGroup` (single selection only) — tiles grow with `flex: 1` |
+| Typography | `--joy-font-size-primary-300`; label bold when checked |
+| Spacing | Group gap uses `--joy-core-spacing-5`; tile padding uses `--joy-core-spacing-3` (single) or checkbox label padding (multiple) |
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Default (unchecked) | Neutral border (`--joy-color-neutral-30`); normal label weight |
+| Checked | Secondary border and text (`--joy-color-secondary-50`); primary label **bold**; sublabel stays normal weight |
+| Hover | Border accent on enabled tiles (pointer devices) |
+| Focus | Visible outline on the tile (`--joy-form-field-focus-width` / `--joy-form-field-focus-color`) |
+| Disabled | Muted text and neutral background; `not-allowed` cursor — **explain why** when the reason isn’t obvious |
+| Invalid | Error border on the tile (`--joy-color-error-50`); pair with `errorMessage` on the group — don’t rely on color alone |
+| Focusing (wrapper) | `joy-selectable-item--focusing` while the inner control is focused |
+
+In single-selection mode, clicking a **checked** tile clears the selection (emits `''`). Confirm product rules allow “no selection” before relying on this behavior.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Selection and hierarchy
+
+- **SHOULD** offer **2–5** tiles; beyond that, prefer `VJoySelect` or a vertical radio/checkbox group.
+- **SHOULD** pre-select a sensible default when one option is clearly recommended.
+- **SHOULD** keep option labels parallel (same grammar and similar length).
+- **MUST NOT** use selectable items for navigation or one-off actions — use `VJoyButtonCard`.
+- **MUST NOT** build new features on this deprecated API — migrate to `VJoyRadio`, `VJoyCheckboxCard`, or `VJoyButtonCard`.
+
+### Implementation
+
+- **MUST** bind `checked` and listen for `@update:checked` (or use `VJoySelectableItemGroup` with `v-model:value`).
+- **MUST** use only documented props from `VJoySelectableItem.vue` / `TVJoySelectableItemProps`.
+- **MUST** style with Joy tokens — no custom `.joy-selectable-item` chrome overrides.
+- **MUST NOT** invent props (`variant`, `size`, `ai`, `color`, …).
+- **MUST** set `value` on every item used in forms.
+- **SHOULD** put primary copy in the default slot; `label` prop is not rendered by the Vue component — use the slot (or the group’s `label` / `item` slot).
+- **SHOULD** use `subLabel` or `#selectable-item-sublabel` for secondary detail, not a second line in the primary label.
+
+### Interaction
+
+- **MUST** set `disabled` on tiles the user cannot choose.
+- **SHOULD** explain disabled tiles when the restriction isn’t clear from context.
+- **SHOULD** use the group `item` slot (with `VJoyIcon` etc.) for rich tile content instead of bolting icons onto custom markup.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `VJoySelectableItemGroup` + `options` / `v-model:value` | Lone tiles without group legend or validation |
+| Parallel short labels + sublabels | Long paragraphs inside the tile |
+| `invalid` + `errorMessage` on the group | Red borders with no error text |
+| Migrate new work to Radio / CheckboxCard / ButtonCard | New `VJoySelectableItem` usage |
+| `fullWidth` for equal-width single-select rows | Hardcoded `215px` tile widths in app CSS |
+
+---
+
+## Content
+
+Tile copy should make each option distinct at a glance and read consistently as a set.
+
+### Label formula
+
+**Short noun phrase or concise statement** naming the option:
+
+- ✅ Monthly  
+- ✅ Express delivery  
+- ✅ PDF export  
+
+Use the **same part of speech** across siblings.
+
+### Sublabel
+
+One line of supporting detail — price, timing, eligibility. Sublabels stay regular weight when the tile is selected so the primary label carries emphasis.
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | Label the **option**, not the action — ✅ `Standard` · ❌ `Select standard` |
+| **MUST** | Keep primary labels ≤ ~30 characters; move detail to sublabel |
+| **MUST** | Use sentence case for labels and sublabels |
+| **MUST NOT** | Repeat the group legend in every tile label |
+| **MUST NOT** | Use Yes / No as two tile labels when the question isn’t literally binary — name the outcomes |
+| **SHOULD** | Put prices or counts in the sublabel, not the main label |
+| **SHOULD** | Write the group `label` as a question or instruction (`Billing frequency`, `Export format`) |
+| **SHOULD** | Keep `value` a stable programmatic key; localize slot content only |
+
+### Patterns
+
+**Plan / tier pickers** — primary label = plan name; sublabel = price or cadence; optional icon via group `#item` slot.
+
+**Validation** — group `label` + `errorMessage` when `invalid`: ✅ `Choose a delivery speed` + `Select one option to continue`.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Native `radio` (single) or `checkbox` (multiple) — not a clickable `<div>` alone |
+| Name | Primary label from default slot (or checkbox label in multiple mode); group name from `VJoySelectableItemGroup` `label` / external `VJoyLabel` |
+| Keyboard | **Space** toggles focused control; **Arrow keys** move between radios in the same `name` group (single mode) |
+| Focus | Visible focus ring on the tile; checkbox inner focus ring suppressed via `display-focus="false"` to avoid double rings |
+| Disabled | `disabled` on the native control; `aria-disabled` on the wrapper when disabled |
+| Invalid | Error styling plus visible `errorMessage` from the group |
+| Grouping | `VJoySelectableItemGroup` renders a `<fieldset>`; associate legend via `VJoyLabel` |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import {
+  VJoySelectableItem,
+  VJoySelectableItemGroup,
+  type TJoySelectableItemOption,
+} from '@maltjoy/core-vue'
+
+const plan = ref('monthly')
+
+const options: TJoySelectableItemOption[] = [
+  { id: 'plan-monthly', value: 'monthly', label: 'Monthly', subLabel: 'Billed each month' },
+  { id: 'plan-yearly', value: 'yearly', label: 'Yearly', subLabel: 'Save 20%' },
+]
+
+// Standalone single-selection tile (unusual — prefer the group)
+const standalone = ref('a')
+</script>
+
+<template>
+  <!-- Recommended: group + v-model:value -->
+  <VJoySelectableItemGroup
+    v-model:value="plan"
+    label="Billing frequency"
+    :options="options"
+  />
+
+  <!-- Multi-select -->
+  <VJoySelectableItemGroup
+    v-model:value="['pdf']"
+    multiple
+    label="Export formats"
+    :options="[
+      { id: 'fmt-pdf', value: 'pdf', label: 'PDF' },
+      { id: 'fmt-docx', value: 'docx', label: 'DOCX' },
+    ]"
+  />
+
+  <!-- Custom tile body via item slot -->
+  <VJoySelectableItemGroup v-model:value="plan" :options="options">
+    <template #item="option">
+      <strong>{{ option.label }}</strong>
+    </template>
+  </VJoySelectableItemGroup>
+
+  <!-- Standalone item (you manage group semantics) -->
+  <VJoySelectableItem
+    id="tile-a"
+    name="letters"
+    value="a"
+    :checked="standalone === 'a'"
+    @update:checked="(v) => { standalone = v as string }"
+  >
+    Option A
+    <template #selectable-item-sublabel>Detail for A</template>
+  </VJoySelectableItem>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if components are already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoySelectableItemGroup` | Fieldset, options array, `v-model:value`, `invalid`, `fullWidth` |
+| `VJoyRadio` / `VJoyRadioGroup` | **Preferred** replacement for single selection (including `outline` cards) |
+| `VJoyCheckboxCard` | **Preferred** replacement for card-style checkbox / multi-select |
+| `VJoyButtonCard` | Card that navigates or triggers an action |
+| `VJoyCheckbox` | Embedded inside multiple-mode tiles (`display-focus="false"`) |
+| `VJoyLabel` / `VJoyFormError` | External legend or group-level error display |
+| `VJoySelect` | Long dropdown lists instead of tiles |
+
+---
+
+## For agents
+
+Maps to `agentDocumentBlocks` in [`JoySelectableItem.dsds.json`](./JoySelectableItem.dsds.json). **Do not use this component for new UI** — emit replacements below.
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| New single-choice card picker | `VJoyRadio` `theme="outline"` in `VJoyRadioGroup` | `VJoySelectableItem` |
+| New multi-select card picker | `VJoyCheckboxCard` / `VJoyCheckboxGroup` | `VJoySelectableItemGroup` `multiple` |
+| Card link or CTA | `VJoyButtonCard` | Selectable item tiles |
+| Maintain legacy tile group | `VJoySelectableItemGroup` + options | Custom div tiles |
+| Rich icon in tile | `#item` slot on group | Invented `icon` prop on item (not rendered) |
+
+### Hard rules
+
+1. **MUST** read `VJoySelectableItem.vue` and `VJoySelectableItem.types.ts` (or MCP when available) before generating props.  
+2. **MUST** prefer `VJoySelectableItemGroup` over standalone items in forms.  
+3. **MUST** set `id` and `value` on every option object; shared `name` for single-selection siblings.  
+4. **MUST** bind group state with `v-model:value` (`string` single, `array` multiple).  
+5. **MUST NOT** invent props — no `variant`, `size`, or `ai`.  
+6. **MUST NOT** override `.joy-selectable-item` border, padding, min-height, or flex basis in product CSS.  
+7. **MUST NOT** use for new features — deprecated in favor of Radio / CheckboxCard / ButtonCard.  
+8. **SHOULD** set `invalid` and `errorMessage` on the group, not only on items.  
+9. **SHOULD** use `subLabel` / `#selectable-item-sublabel` for secondary text.
+
+### Checklist
+
+- [ ] Confirmed legacy maintenance (not greenfield) or documented migration target
+- [ ] `VJoySelectableItemGroup` used for form fields when possible
+- [ ] Each option has `id`, `value`, and label content in slot / `options`
+- [ ] `v-model:value` type matches `multiple` (`string` vs `array`)
+- [ ] No invented props / no custom tile chrome CSS
+- [ ] Group `label` + `errorMessage` when `invalid`
+- [ ] Parallel concise labels; detail in sublabel
+- [ ] Replacement component identified for new work
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoySelectableItem.dsds.json`](./JoySelectableItem.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy / selection modes | `anatomy` |
+| Sizes (no size API) | `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 |