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

package/dist/doc/VJoyCheckboxGroup/guideline.md

@@ -0,0 +1,363 @@
+---
+component: VJoyCheckboxGroup
+status: draft
+language: en
+dsds: JoyCheckboxGroup.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Checkbox group
+
+Use **`VJoyCheckboxGroup`** when the user may select **zero, one, or more** options from a related set and you want selection managed as an **array** (`v-model:value`).
+
+It renders a semantic `<fieldset>` with an optional group legend, lays out `VJoyCheckbox` (or `VJoyCheckboxCard`) children, and handles add/remove in the model when you pass `options`. Use the default slot when you need explicit children or card layouts.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyCheckboxGroup` from `@maltjoy/core-vue` |
+| **Design** | [Joy — Checkbox](https://zeroheight.com/6bf479565/) (page id `1423608`) |
+| **Storybook** | [VJoyCheckboxGroup docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-forms-vjoycheckboxgroup--docs) |
+| **DSDS (machine)** | [`JoyCheckboxGroup.dsds.json`](./JoyCheckboxGroup.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyCheckboxGroup")` |
+
+---
+
+## When to use this component
+
+Use a checkbox group when several options are **independent** — filters, export formats, notification channels, permissions, or bulk-selection lists — and the bound state should be a **string array** of selected `value`s.
+
+The `options` prop is the fast path for a uniform list of `VJoyCheckbox` rows. For `VJoyCheckboxCard`, mixed layouts, or per-option `disabled` / `invalid`, declare children in the **default slot** and wire `checked` + `@update:checked` via the slot props (`isChecked`, `updateModel`).
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Exactly one option from a short list | `VJoyRadio` inside `VJoyRadioGroup` |
+| A single on/off preference (settings row) | `VJoyToggle` |
+| One standalone checkbox (consent, select-all row) | `VJoyCheckbox` alone |
+| Rich card option without composing the group yourself | `VJoyCheckboxCard` inside `VJoyCheckboxGroup` (default slot) |
+| Long or searchable option lists (roughly 8+) | `VJoySelect` or `VJoySelectableItemGroup` |
+| Custom-styled checkbox list markup | Still use `VJoyCheckboxGroup` + Joy tokens — don’t reinvent chrome |
+
+> **Deprecated:** `VJoyMultiCheckbox` is an alias kept for backward compatibility. Use `VJoyCheckboxGroup` for new work.
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Fieldset wrapper | Yes | Root `<fieldset class="joy-checkbox-group__wrapper">` — groups related checkboxes for AT |
+| Group legend | No | `VJoyLabel` as `<legend>` when `label` is set |
+| Options container | Yes | Flex container (`.joy-checkbox-group`) with `direction` modifier |
+| Checkbox children | Yes | `VJoyCheckbox` from `options`, or explicit children in the default slot |
+| `checkbox` slot | No | Custom inner label per option when using `options` |
+| Focus rings | Yes | On each child checkbox — don’t remove in product CSS |
+
+The group `provide`s `JoyFormElementContext` so it integrates with Joy form field patterns.
+
+### Default values
+
+- `options` defaults to **`[]`**
+- `value` defaults to **`[]`** — bind with `v-model:value`
+- `direction` defaults to **`vertical`**
+- `required` defaults to **`false`**
+- `labelSize` defaults to **`medium`**
+- `requiredMark` defaults to **`false`**
+
+Props, events, and slots: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Layout (`direction`)
+
+| Value | Use when |
+| --- | --- |
+| `vertical` | Default — stacked options, longer labels, or `VJoyCheckboxCard` with sublabels |
+| `horizontal` | Few short labels in a row (filters, compact toolbars). Avoid horizontal `VJoyCheckboxCard` when sublabels or body copy are long |
+
+Spacing between items uses `--joy-core-spacing-4` inside the group — **don’t hardcode gap or margin** on `.joy-checkbox-group` in apps.
+
+### Composition modes
+
+**`options` prop** — Group renders `VJoyCheckbox` per option, syncs `v-model:value`, and supports the `checkbox` slot for custom label markup. Each option needs a stable `id` and distinct `value`.
+
+**Default slot** — Replaces `options` rendering entirely. Slot props: `value`, `isChecked(value)`, `updateModel(value, checked)`. **You must** bind each child’s `checked` and `@update:checked` (or equivalent) — the group does not auto-wire children in this mode.
+
+---
+
+## States
+
+Group-level behavior; per-checkbox hover, focus, checked, disabled, and invalid styling live on **`VJoyCheckbox`** / **`VJoyCheckboxCard`**.
+
+| State | What the user sees / can do |
+| --- | --- |
+| Default | Zero or more options checked; each checkbox independently toggleable |
+| Checked (per option) | Option’s `value` is present in `value` array; child shows checked styling |
+| Unchecked (per option) | Option’s `value` absent from array |
+| Disabled (per option) | Set on the child checkbox — use the default slot when an option in `options` must be disabled (`options` rendering does not pass `disabled` today) |
+| Invalid (per option) | Set `invalid` on the child; pair with visible error text — don’t rely on color alone |
+| Required group | `required` / `requiredMark` on the group affect the legend; enforce “at least one selected” in form validation and show `VJoyFormError` when needed |
+
+**Array updates:** checking pushes `value` into the array; unchecking removes it. Order follows user interaction, not display order — compare with `Set` semantics if order must not matter.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Selection model
+
+- **SHOULD** use checkbox groups when any combination of options is valid (including none), unless product rules require at least one.
+- **MUST NOT** use a checkbox group when only one option may be selected — use `VJoyRadioGroup`.
+- **SHOULD** keep **2–7** visible options; beyond that, consider `VJoySelect` or a searchable list.
+- **SHOULD** use distinct, stable `value` strings (API keys); keep human copy in `label`.
+
+### Implementation
+
+- **MUST** bind `v-model:value` (or `:value` + `@update:value`) to a string array.
+- **MUST** give every option a unique `id` and `value`.
+- **MUST** use only documented props and `direction` values from MCP (`vertical`, `horizontal`).
+- **MUST** use Joy tokens — no custom `.joy-checkbox-group` layout overrides.
+- **MUST NOT** invent props (`variant`, `size`, `multiple`, …).
+- **SHOULD** prefer `options` for simple lists; use the **default slot** for `VJoyCheckboxCard`, mixed children, or per-option `disabled` / `invalid`.
+- **SHOULD** set `name` on children when submitting native forms (via `option.name` or explicit props in the default slot).
+
+### Interaction
+
+- **MUST** wire default-slot children with `isChecked` / `updateModel` — Storybook documents this explicitly.
+- **SHOULD** use `direction="horizontal"` only when labels stay short on one line.
+- **SHOULD** explain disabled options when the reason isn’t obvious from context.
+- **SHOULD** validate “at least one required” at submit with a group-level message, not only `required` on the fieldset.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `v-model:value` as string array | Boolean per checkbox without syncing the array |
+| Group `label` as the fieldset legend | Repeat the legend text in every option label |
+| Default slot for cards / disabled options | Cram long sublabels into horizontal layout |
+| `VJoyFormError` for group validation | Error color with no message |
+| `VJoyCheckboxGroup` in filter dropdowns | Lone checkboxes with no group semantics |
+
+---
+
+## Content
+
+Group copy frames the set; option labels name each choice. Follow the same label rules as `VJoyCheckbox`.
+
+### Legend (group label)
+
+Write the **`label`** as a short question or category name:
+
+- ✅ Notification channels  
+- ✅ Export formats  
+- ✅ Which permissions should this role have?
+
+Avoid repeating this text in every checkbox label.
+
+### Option labels
+
+**Noun phrase or short statement** per option, **parallel** grammar across siblings:
+
+- ✅ Email · Push · SMS  
+- ✅ PDF · DOCX · XLSX  
+
+Use the `checkbox` slot (with `options`) or card `label` / `subLabel` when an option needs extra detail — not an overloaded primary label.
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | Provide a group `label` when the set needs context for screen reader users (unless an adjacent heading already names the set) |
+| **MUST** | Keep option labels scannable — describe the option, not the click action |
+| **MUST NOT** | Duplicate the group legend in every option label |
+| **MUST NOT** | Use Yes / No as the only labels in a multi-option list — name each outcome |
+| **SHOULD** | ≤ 60 characters per option label; move detail to `subLabel` or card content |
+| **SHOULD** | Use `optionalLabel` on the legend when the whole group is optional |
+| **SHOULD** | Localize `label` and option copy; keep `value` as a stable programmatic key |
+
+### Patterns
+
+**Filters** — Horizontal group with short labels inside `VJoyDropdown` (`close-on-select="false"` when users pick several before Apply). Legend names the dimension (`Status`, `Format`).
+
+**Permissions / bulk export** — Vertical list; pre-check sensible defaults when product rules allow.
+
+**Validation** — Legend + `VJoyFormError` below the group: ✅ `Select at least one format` + `Choose one or more formats to continue`.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Native `<fieldset>`; group name from `<legend>` (`VJoyLabel` when `label` is set) |
+| Children | Each option remains a native checkbox (`VJoyCheckbox` / card wrapping one) |
+| Name | Group from legend; each option from its label slot or `label` prop |
+| Keyboard | **Tab** between checkboxes; **Space** toggles focused checkbox |
+| Focus | Visible focus ring on each child — don’t remove in product CSS |
+| Selection | Multiple selections allowed; state reflected in `value` array and each `checked` binding |
+| Required | If the form requires at least one selection, expose failure in text (`VJoyFormError`), not only `required` on the fieldset |
+| Disabled | `disabled` on individual inputs; explain restriction in visible copy when it matters |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { VJoyCheckboxGroup, VJoyCheckbox, VJoyCheckboxCard } from '@maltjoy/core-vue'
+
+const formats = ref(['pdf'])
+const channels = ref<string[]>([])
+</script>
+
+<template>
+  <!-- Options prop — managed array -->
+  <VJoyCheckboxGroup
+    v-model:value="formats"
+    label="Export formats"
+    :options="[
+      { id: 'fmt-pdf', value: 'pdf', label: 'PDF' },
+      { id: 'fmt-docx', value: 'docx', label: 'DOCX' },
+      { id: 'fmt-xlsx', value: 'xlsx', label: 'XLSX' },
+    ]"
+  />
+
+  <!-- Horizontal filters -->
+  <VJoyCheckboxGroup
+    v-model:value="channels"
+    label="Notification channels"
+    direction="horizontal"
+    :options="[
+      { id: 'ch-email', value: 'email', label: 'Email' },
+      { id: 'ch-push', value: 'push', label: 'Push' },
+      { id: 'ch-sms', value: 'sms', label: 'SMS' },
+    ]"
+  />
+
+  <!-- Default slot — explicit children (wire v-model helpers) -->
+  <VJoyCheckboxGroup v-model:value="formats" label="Plans">
+  <template #default="{ isChecked, updateModel }">
+    <VJoyCheckboxCard
+      id="plan-pro"
+      value="pro"
+      label="Pro"
+      sub-label="For growing teams"
+      :checked="isChecked('pro')"
+      @update:checked="(on) => updateModel('pro', on)"
+    />
+    <VJoyCheckboxCard
+      id="plan-enterprise"
+      value="enterprise"
+      label="Enterprise"
+      sub-label="Contact sales"
+      disabled
+      :checked="isChecked('enterprise')"
+      @update:checked="(on) => updateModel('enterprise', on)"
+    />
+  </template>
+  </VJoyCheckboxGroup>
+
+  <!-- Customize option label markup via checkbox slot -->
+  <VJoyCheckboxGroup
+    v-model:value="channels"
+    label="Channels"
+    :options="[
+      { id: 'ch-email', value: 'email', label: 'Email' },
+      { id: 'ch-push', value: 'push', label: 'Push' },
+    ]"
+  >
+    <template #checkbox="option">
+      <strong>{{ option.label }}</strong>
+    </template>
+  </VJoyCheckboxGroup>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyCheckboxGroup` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyCheckbox` | Single checkbox or explicit child inside the group |
+| `VJoyCheckboxCard` | Card-style options with title, sublabel, and body |
+| `VJoyRadioGroup` / `VJoyRadio` | Exactly one choice from a list |
+| `VJoyToggle` | Single on/off setting |
+| `VJoyLabel` | Custom legend HTML — prefer `label` prop for plain text |
+| `VJoyFormError` | Group-level validation message |
+| `VJoyDropdown` | Filter UI hosting a checkbox group in `dropdown-items` |
+| `VJoySelectableItemGroup` | Alternative multi-select list pattern |
+| `VJoyMultiCheckbox` | **Deprecated** — use `VJoyCheckboxGroup` |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyCheckboxGroup.dsds.json`](./JoyCheckboxGroup.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Multiple independent selections as an array | `VJoyCheckboxGroup` + `v-model:value` | `VJoyRadioGroup` |
+| Exactly one of a few options | `VJoyRadioGroup` | `VJoyCheckboxGroup` |
+| One consent / binary checkbox | `VJoyCheckbox` | Group with a single member |
+| Card multi-select in a group | `VJoyCheckboxGroup` default slot + `VJoyCheckboxCard` | Custom card divs |
+| Simple uniform option list | `options` prop | Manual array splice without the group |
+| Per-option disabled or invalid with `options` | Default slot + explicit children | Assuming `options[].disabled` is wired (it is not in the template today) |
+| Filter menu multi-select | `VJoyCheckboxGroup` inside `VJoyDropdown` | Standalone checkboxes without fieldset |
+
+### Hard rules
+
+1. **MUST** call `joy_get_component_info("VJoyCheckboxGroup")` (or read `VJoyCheckboxGroup.vue` types) before generating props.  
+2. **MUST** bind `v-model:value` to a **string array** (or compatible array of option values).  
+3. **MUST** use `direction` only as `vertical` or `horizontal`.  
+4. **MUST** give each option a unique `id` and `value`.  
+5. **MUST** wire default-slot children with `isChecked` / `updateModel` from slot props.  
+6. **MUST NOT** invent props (`multiple`, `variant`, `size`, …).  
+7. **MUST NOT** override `.joy-checkbox-group` gap, flex, or fieldset chrome in product CSS.  
+8. **MUST NOT** use `VJoyMultiCheckbox` in new code — emit `VJoyCheckboxGroup`.  
+9. **SHOULD** use `options` for flat `VJoyCheckbox` lists; default slot for `VJoyCheckboxCard` or mixed layouts.  
+10. **SHOULD** keep horizontal layout for short labels only.
+
+### Checklist
+
+- [ ] Correct component (`VJoyCheckboxGroup` or named alternative)
+- [ ] `v-model:value` bound to an array
+- [ ] `direction` from MCP enum only
+- [ ] Unique `id` / `value` per option
+- [ ] Default slot children wired with `isChecked` / `updateModel`
+- [ ] Group `label` set when the set needs a programmatic name
+- [ ] No invented props / no custom group layout CSS
+- [ ] Exclusive choice → radio group, not checkbox group
+- [ ] Validation uses visible error text (`VJoyFormError`) when at least one selection is required
+- [ ] Disabled / invalid per option via explicit children when `options` is insufficient
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyCheckboxGroup.dsds.json`](./JoyCheckboxGroup.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy / layout | `anatomy` |
+| 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 |
+| Layout tokens | `design-specifications` in JSON (`--joy-core-spacing-4`) |