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

package/dist/doc/VJoyCheckboxCard/guideline.md

@@ -0,0 +1,381 @@
+---
+component: VJoyCheckboxCard
+status: draft
+language: en
+dsds: JoyCheckboxCard.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Checkbox card
+
+Use **`VJoyCheckboxCard`** when the user can select **zero, one, or more** independent options and each option needs a **card layout** — a primary label, optional sublabel, and room for supporting content.
+
+The whole card is clickable (except nested interactive controls). It wraps `VJoyCheckbox` with bordered card chrome, optional `header-right` metadata, and a `checkbox-card-content` body slot. Bind state with `v-model:checked`.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyCheckboxCard` from `@maltjoy/core-vue` |
+| **Design** | [Figma — Joy components](https://www.figma.com/design/jfndp2QBJGS9yeuWbeGuvD/) |
+| **Storybook** | [VJoyCheckboxCard docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-forms-vjoycheckboxcard--docs) |
+| **DSDS (machine)** | [`JoyCheckboxCard.dsds.json`](./JoyCheckboxCard.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyCheckboxCard")` |
+
+---
+
+## When to use this component
+
+Use a checkbox card when options are **not mutually exclusive** and each choice benefits from a scannable title, short supporting line, and optional body copy — for example feature add-ons, permission bundles, export formats with descriptions, or filter tiles in a grid.
+
+Compose several cards inside `VJoyCheckboxGroup` when you manage a shared array of selected `value`s, or bind each card independently when selections are unrelated.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Compact label-only multi-select | `VJoyCheckbox` inside `VJoyCheckboxGroup` |
+| Exactly one option from a short list | `VJoyRadio` (`theme="outline"`) inside `VJoyRadioGroup` |
+| A single on/off setting (settings row) | `VJoyToggle` |
+| List row with custom chrome wrapping a control | `VJoySelectableItem` (often with checkbox slot) |
+| Custom-styled card + checkbox markup | Still use `VJoyCheckboxCard` + Joy tokens — don’t reinvent chrome |
+
+> **Indeterminate:** use for “select all” / partial selection in parent rows. Do not bind `indeterminate` together with `v-model:checked` on the same instance — see [MDN indeterminate checkboxes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#indeterminate_state_checkboxes).
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Card container | Yes | Root `.joy-checkbox-card` — receives hover, focus, checked, invalid, and disabled styling |
+| Checkbox input | Yes | Native `<input type="checkbox">` inside embedded `VJoyCheckbox` (`data-joy-form-field`) |
+| Label | Yes | Primary title via the `label` prop (`.joy-checkbox-card__label`) |
+| Sublabel | No | Secondary line via `subLabel` (`.joy-checkbox-card__sublabel`) |
+| `header-right` | No | Right-aligned slot beside the label row (e.g. a tag or short meta) |
+| `checkbox-card-content` | No | Body content below the header (`.joy-checkbox-card__content`) |
+| Focus ring | Yes | Card border uses focus token when the checkbox is focused — don’t remove it in product CSS |
+
+The card delegates checkbox semantics to `VJoyCheckbox`. Clicks on the card surface toggle selection unless they target the native label/input or a nested interactive element (`a`, `button`, `textarea`, `select`, `option`, `[role="button"]`, or `[data-no-card-toggle]`).
+
+### Default values
+
+- `checked` defaults to **`false`**
+- `subLabel` defaults to **`""`** (hidden when empty)
+- `indeterminate` defaults to **`false`**
+- `invalid` defaults to **`false`**
+- `disabled` defaults to **`false`**
+- `required` defaults to **`false`**
+- `value` defaults to **`"on"`** (used when building multi-value form submissions)
+- `fitContent` defaults to **`false`** (card stretches to container width)
+
+Props, events, and slots: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Layout
+
+- **Full width (default):** card fills its parent — typical in vertical stacks and form fields.
+- **`fitContent`:** card width shrinks to content — use in horizontal groups or inline pickers when labels are short.
+
+There is **no `variant` or `size` prop**. Border, radius, spacing, and typography come from Joy tokens inside the component — **don’t hardcode card dimensions or border colors** in product CSS.
+
+---
+
+## Variants
+
+`VJoyCheckboxCard` has **no visual emphasis variants** (no primary/secondary). Appearance is controlled by **state** (`checked`, `indeterminate`, `invalid`, `disabled`, focus, hover) and the optional **`fitContent`** layout flag.
+
+Choose `VJoyRadio` with `theme="outline"` when only one option may be selected, not this component.
+
+---
+
+## Sizes
+
+`VJoyCheckboxCard` exposes **no size API**. The embedded checkbox uses the standard Joy checkbox size; card padding and borders use Joy spacing and form tokens (`--joy-core-spacing-4`, `--joy-form-border-width`, `--joy-core-radius-4`).
+
+| Aspect | Guidance |
+| --- | --- |
+| Card width | Default full width; `fitContent` for compact tiles |
+| Checkbox control | Inherited from `VJoyCheckbox` — don’t override `.joy-checkbox` size in apps |
+| Density | Prefer fewer cards per row or shorter copy — not invented `size` props |
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Default (unchecked) | Neutral border; empty checkbox; full card clickable |
+| Checked | Secondary accent border; filled checkbox; label in **bold** |
+| Indeterminate | Secondary accent border; dash in checkbox; label in **bold** |
+| Hover | Border uses hover token (pointer devices, when not disabled) |
+| Focus | Border uses focus token while the checkbox input is focused |
+| Disabled | Muted border and text; no toggle — **explain why** nearby when possible |
+| Invalid | Error border on the **unchecked** card only; cleared while checked |
+
+**Invalid vs checked:** a checked card **cannot** appear invalid — `checked` wins. Unchecking restores `invalid` if the prop is still true.
+
+**Indeterminate lifecycle:** any user change clears indeterminate (component sets internal indeterminate to `false` on toggle).
+
+**Nested actions:** buttons, links, and other controls inside `checkbox-card-content` keep their own click behavior; the card does not toggle when those are clicked.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Selection model
+
+- **SHOULD** use checkbox cards when options are independent and any combination is valid.
+- **MUST NOT** use checkbox cards when only one option may be selected — use `VJoyRadio` with `theme="outline"`.
+- **SHOULD** place related cards in `VJoyCheckboxGroup` and wire `v-model:value` on the group (or manage `checked` / `value` explicitly in the default slot).
+- **SHOULD** use `indeterminate` only on parent “select all” controls, not on every leaf card.
+
+### Implementation
+
+- **MUST** bind state with `v-model:checked` (or `:checked` + `@update:checked`).
+- **MUST** use only documented props from MCP or `JoyCheckboxCard.types.ts`.
+- **MUST** use Joy tokens — no custom `.joy-checkbox-card` chrome CSS.
+- **MUST NOT** invent props (`variant`, `size`, `color`, …).
+- **MUST NOT** combine `indeterminate` with `v-model:checked` on the same instance.
+- **MUST** set distinct `id` / `name` / `value` when submitting multiple cards in one form.
+- **SHOULD** set `invalid` from form validation only while the card is unchecked.
+- **SHOULD** add `data-no-card-toggle` on custom interactive elements in the body when they must not toggle the card.
+
+### Interaction
+
+- **MUST** keep the entire card surface toggling selection except for documented interactive exclusions.
+- **SHOULD** put error or helper copy in `checkbox-card-content` or adjacent form messaging — not only border color.
+- **SHOULD** use `fitContent` in horizontal `VJoyCheckboxGroup` layouts only when labels and body copy stay short.
+- **SHOULD** disable rather than hide options the user cannot choose, when the choice must remain visible.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `v-model:checked` for boolean state | Manual `input.checked` without updating model |
+| `VJoyCheckboxGroup` for related multi-select | Unrelated cards with no group legend when context needs one |
+| `header-right` for tags / short meta | Primary actions in `header-right` that compete with card toggle |
+| `data-no-card-toggle` on nested buttons/links | Expect card click to fire when user clicks a button in the body |
+| `VJoyRadio` outline for exclusive choice | Checkbox cards for “pick one” |
+
+---
+
+## Content
+
+Card copy should make each option scannable: a clear **title** (`label`), an optional **one-line hook** (`subLabel`), and longer detail in `checkbox-card-content`.
+
+### Label formula
+
+**Noun phrase or short statement** naming what is selected when checked:
+
+- ✅ Email digests  
+- ✅ Advanced analytics  
+- ✅ Export as PDF  
+
+Keep labels **parallel** across siblings (same grammar and similar length):
+
+- ✅ PDF · DOCX · XLSX  
+- ❌ Export as PDF · Word document · spreadsheet (xlsx)
+
+### Sublabel and body copy
+
+- **`subLabel`** — one supporting line (price, cadence, eligibility, timing).  
+- **`checkbox-card-content`** — feature bullets, legal snippets, illustrations, or validation messages.  
+- **`header-right`** — short non-interactive metadata (`VJoyTag`, price badge).
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | Every card has a visible `label` — no unlabeled checkbox cards |
+| **MUST** | Label describes the option, not the click action — ✅ `Weekly digest` · ❌ `Click to enable weekly digest` |
+| **MUST NOT** | Duplicate the group legend in every card label when `VJoyCheckboxGroup` already provides one |
+| **MUST NOT** | Use Yes / No as the only labels in a multi-card set — name each outcome |
+| **SHOULD** | ≤ 60 characters for `label`; wrap rather than truncate |
+| **SHOULD** | Keep `subLabel` to one line; move paragraphs to `checkbox-card-content` |
+| **SHOULD** | Put legal links or long explanations in `checkbox-card-content`, not in the primary label |
+| **SHOULD** | “Select all” parent: `Select all` or `Select all {noun}` — not `All` alone |
+
+### Patterns
+
+**Feature add-ons** — `label` names the feature, `subLabel` states cost or scope, `checkbox-card-content` lists what’s included.
+
+**Filter tiles** — short parallel labels; optional `fitContent` in a horizontal group; avoid long body copy in horizontal layouts.
+
+**Validation** — pair `invalid` with explicit error text in `checkbox-card-content` or form-level error (e.g. “Select at least one export format”). Don’t rely on red border alone.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Native `checkbox` via embedded `<input type="checkbox">` |
+| Name | From `label` prop (rendered in the checkbox label association) |
+| Keyboard | **Space** toggles when the checkbox is focused; **Tab** moves focus to the input |
+| Focus | Visible focus on the card border (`joy-checkbox-card--focusing`); don’t remove in product CSS |
+| Large target | Card click toggles selection for pointer users; nested controls remain independently operable |
+| Grouping | Related cards: `VJoyCheckboxGroup` uses `<fieldset>` + legend |
+| Disabled | `disabled` on input; explain restriction in visible text when it matters |
+| Invalid | Don’t rely on color alone — provide text for the error |
+| Indeterminate | Exposed to AT via native `indeterminate` on the input |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { VJoyCheckboxCard, VJoyCheckboxGroup, VJoyTag } from '@maltjoy/core-vue'
+
+const analytics = ref(false)
+const selected = ref(['pdf'])
+</script>
+
+<template>
+  <!-- Standalone card -->
+  <VJoyCheckboxCard
+    v-model:checked="analytics"
+    label="Advanced analytics"
+    sub-label="Includes funnel and cohort reports"
+  >
+    <template #checkbox-card-content>
+      Available on Pro plans. Data refreshes every 24 hours.
+    </template>
+  </VJoyCheckboxCard>
+
+  <!-- With header metadata -->
+  <VJoyCheckboxCard
+    v-model:checked="analytics"
+    label="Priority support"
+    sub-label="24/7 chat"
+  >
+    <template #header-right>
+      <VJoyTag variant="important" size="xsmall">New</VJoyTag>
+    </template>
+  </VJoyCheckboxCard>
+
+  <!-- Inside a group (wire slot helpers from VJoyCheckboxGroup) -->
+  <VJoyCheckboxGroup v-model:value="selected" label="Export formats" direction="vertical">
+    <template #default="{ isChecked, updateModel }">
+      <VJoyCheckboxCard
+        value="pdf"
+        label="PDF"
+        sub-label="Best for sharing"
+        :checked="isChecked('pdf')"
+        @update:checked="updateModel('pdf', $event)"
+      />
+      <VJoyCheckboxCard
+        value="csv"
+        label="CSV"
+        sub-label="Best for spreadsheets"
+        :checked="isChecked('csv')"
+        @update:checked="updateModel('csv', $event)"
+      />
+    </template>
+  </VJoyCheckboxGroup>
+
+  <!-- Compact horizontal tiles -->
+  <VJoyCheckboxGroup direction="horizontal">
+    <VJoyCheckboxCard fit-content label="PDF" :checked="true" />
+    <VJoyCheckboxCard fit-content label="DOCX" :checked="false" />
+  </VJoyCheckboxGroup>
+
+  <!-- Invalid until selected -->
+  <VJoyCheckboxCard
+    v-model:checked="analytics"
+    :invalid="!analytics"
+    label="I agree to the data processing terms"
+  />
+
+  <!-- Body action that must not toggle the card -->
+  <VJoyCheckboxCard v-model:checked="analytics" label="Custom integration">
+    <template #checkbox-card-content>
+      <button type="button" data-no-card-toggle>Configure webhook</button>
+    </template>
+  </VJoyCheckboxCard>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyCheckboxCard` is already global.
+
+When using `VJoyCheckboxGroup`’s default slot, bind each card with `isChecked(value)` and `updateModel(value, $event)` from the slot props — the group does not auto-bind `checked` for slot children.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyCheckbox` | Label-only multi-select without card chrome |
+| `VJoyCheckboxGroup` | Shared legend, layout, and array `v-model:value` |
+| `VJoyRadio` / `VJoyRadioGroup` | Exactly one choice (`theme="outline"` for card-like radios) |
+| `VJoyToggle` | Single on/off preference row |
+| `VJoyTag` | Short metadata in `header-right` |
+| `VJoyLabel` / `VJoyFormGroup` | Field legends, required marks, and form-level validation messaging |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyCheckboxCard.dsds.json`](./JoyCheckboxCard.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Multi-select with title + description cards | `VJoyCheckboxCard` | Custom bordered div + raw checkbox |
+| Compact multi-select list | `VJoyCheckbox` | `VJoyCheckboxCard` without sublabel/body need |
+| Pick exactly one rich option | `VJoyRadio` `theme="outline"` | `VJoyCheckboxCard` |
+| Managed array of selected values | `VJoyCheckboxGroup` + cards or checkboxes | Orphan cards with no group when options are related |
+| Select all / partial parent | `VJoyCheckboxCard` or `VJoyCheckbox` with `indeterminate` | `indeterminate` + `v-model:checked` on same node |
+
+### Hard rules
+
+1. **MUST** call `joy_get_component_info("VJoyCheckboxCard")` or read `JoyCheckboxCard.types.ts` before generating props.  
+2. **MUST** use `v-model:checked` (or `:checked` + `@update:checked`) for boolean state.  
+3. **MUST** set `label` on every instance — there is no default slot for the title.  
+4. **MUST NOT** invent props — there is no `variant`, `size`, or `color`.  
+5. **MUST NOT** set `indeterminate` on the same instance as `v-model:checked`.  
+6. **MUST NOT** override `.joy-checkbox-card` border, padding, radius, or background with custom CSS.  
+7. **MUST** treat `invalid` as visible only when unchecked; checking clears invalid styling.  
+8. **SHOULD** use `checkbox-card-content` for helper text, links, and errors — not overloaded `label` / `subLabel`.  
+9. **SHOULD** add `data-no-card-toggle` on interactive elements in the body that must not toggle the card.
+
+### Checklist
+
+- [ ] Correct component (`VJoyCheckboxCard` or named alternative)
+- [ ] Props from MCP / types only — no invented API
+- [ ] `label` set; `v-model:checked` wired; indeterminate parent not v-modelled
+- [ ] Exclusive choice → `VJoyRadio`, not checkbox card
+- [ ] Related options → `VJoyCheckboxGroup` with legend when needed
+- [ ] No custom `.joy-checkbox-card` chrome CSS
+- [ ] Nested buttons/links use `data-no-card-toggle` when they must not toggle
+- [ ] Invalid / disabled states have explanatory text when user-visible
+- [ ] `id` / `name` / `value` set appropriately for forms
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyCheckboxCard.dsds.json`](./JoyCheckboxCard.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy | `anatomy` |
+| Variants / layout (`fitContent`) | `variants` |
+| 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 |