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

package/dist/doc/VJoyCheckbox/guideline.md

@@ -0,0 +1,317 @@
+---
+component: VJoyCheckbox
+status: draft
+language: en
+dsds: JoyCheckbox.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Checkbox
+
+Use **`VJoyCheckbox`** when the user can select zero, one, or more independent options — or confirm a single binary choice such as consent or agreement.
+
+It supports checked, indeterminate, disabled, and invalid states; native form attributes (`name`, `value`, `required`); a label via prop or slot; and an optional `checkbox-content` area for helper text or related UI below the control.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyCheckbox` from `@maltjoy/core-vue` |
+| **Design** | [Joy — Checkbox](https://zeroheight.com/6bf479565/) (page id `1423608`) |
+| **Storybook** | [VJoyCheckbox docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-forms-vjoycheckbox--docs) |
+| **DSDS (machine)** | [`JoyCheckbox.dsds.json`](./JoyCheckbox.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyCheckbox")` |
+
+---
+
+## When to use this component
+
+Use a checkbox when options are **not mutually exclusive** — the user may select none, one, or several. Typical jobs: multi-select filters, bulk actions, feature toggles in a list, or a standalone consent / confirmation (“I agree to the terms”).
+
+Each checkbox is an independent control. For several related options, compose multiple `VJoyCheckbox` instances or use `VJoyCheckboxGroup` so selection is managed as an array.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Exactly one option from a short list | `VJoyRadio` / `VJoyRadioGroup` |
+| A single on/off setting with immediate effect (settings row) | `VJoyToggle` |
+| Multi-select with array state handled for you | `VJoyCheckboxGroup` |
+| Rich card layout (title, sublabel, body) | `VJoyCheckboxCard` |
+| List row with custom chrome wrapping a control | `VJoySelectableItem` (often with checkbox slot) |
+| Custom-styled `<input type="checkbox">` | Still use `VJoyCheckbox` + 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` — 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 |
+| --- | --- | --- |
+| Wrapper | Yes | Root container (`.joy-checkbox__wrapper`) |
+| Label | Yes | Clickable `<label>` wrapping the control and primary text |
+| Input | Yes | Native `<input type="checkbox">` with `data-joy-form-field` |
+| Label text | Yes* | Default slot or `label` prop (*one of them should provide an accessible name) |
+| `checkbox-content` | No | Slot below the label row for helper text, links, or extra UI |
+| Focus ring | Yes | Shown on keyboard focus when `displayFocus` is true |
+
+The component `provide`s `JoyFormElementContext` so it integrates with Joy form field patterns (e.g. labels, validation).
+
+### Default values
+
+- `checked` defaults to **`false`**
+- `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)
+- `displayFocus` defaults to **`true`** (`@internal` — used by `VJoySelectableItem` to avoid double focus rings)
+
+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**. Checkbox dimensions and colors come from component CSS variables (e.g. `--checkbox-size: 20px`) and Joy tokens — **don’t hardcode box size or border colors** in product CSS.
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Default (unchecked) | Empty box; label in normal weight; clickable |
+| Checked | Filled box with checkmark; label in **bold** |
+| Indeterminate | Dash icon in box; label in **bold**; use for partial “select all” |
+| Hover | Subtle background on the label row (pointer devices) |
+| Focus | Visible focus ring on the label (`displayFocus`) |
+| Active / pressed | Checked background darkens briefly while pressed |
+| Disabled | No interaction; muted checkbox and label — **explain why** nearby when possible |
+| Invalid | Error styling on the **unchecked** box only; cleared while checked |
+
+**Invalid vs checked:** a checked checkbox **cannot** appear invalid — `checked` wins. Unchecking restores `invalid` if the prop is still true. User interaction that checks the box clears invalid styling even before the `checked` prop updates.
+
+**Indeterminate lifecycle:** any user change clears indeterminate (component sets `isIndeterminate` to `false` on `change`).
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Selection model
+
+- **SHOULD** use checkboxes when options are independent and any combination is valid.
+- **MUST NOT** use checkboxes when only one option may be selected — use radio buttons.
+- **SHOULD** use `VJoyCheckboxGroup` when managing an array of selected `value`s.
+- **SHOULD** use `indeterminate` only on parent “select all” controls, not on leaf options.
+
+### Implementation
+
+- **MUST** bind state with `v-model:checked` (or `:checked` + `@update:checked`).
+- **MUST** use only documented props from MCP or `JoyCheckbox.types.ts`.
+- **MUST** use Joy tokens — no custom `.joy-checkbox` chrome CSS.
+- **MUST NOT** invent props (`size`, `variant`, `color`, …).
+- **MUST NOT** combine `indeterminate` with `v-model:checked` on the same instance.
+- **MUST** set distinct `id` / `name` / `value` when submitting multiple checkboxes in a form.
+- **SHOULD** set `invalid` from form validation only while the box is unchecked.
+
+### Interaction
+
+- **MUST** keep the label clickable (don’t detach label from input with custom markup).
+- **SHOULD** place error or helper copy in `checkbox-content` or adjacent `VJoyFormGroup` messaging — not only color.
+- **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 multi-select arrays | Many unrelated checkboxes without group semantics |
+| `indeterminate` on “select all” parent | `indeterminate` on every leaf option |
+| Explain disabled checkboxes | Disabled with no reason in the UI |
+| Radio for exclusive lists | Checkboxes for “pick one” |
+
+---
+
+## Content
+
+Checkbox labels describe **what will be selected or enabled** when the box is checked. They are scannable, specific, and parallel when shown in a list.
+
+### Label formula
+
+**Noun phrase or short statement** that states the option (English):
+
+- ✅ Email notifications  
+- ✅ I agree to the Terms of Service  
+- ✅ Select all projects  
+
+For groups, keep labels **parallel** (same grammar and length order of magnitude):
+
+- ✅ PDF · DOCX · XLSX  
+- ❌ Export as PDF · Word document · spreadsheet (xlsx)
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | Every checkbox has a visible label (prop or default slot) — no unlabeled checkboxes |
+| **MUST** | Label describes the option, not the action of clicking — ✅ `Weekly digest` · ❌ `Click to enable weekly digest` |
+| **MUST** | Standalone consent labels name what is being agreed to — ✅ `I agree to the Terms of Service` |
+| **MUST NOT** | Duplicate the group legend in every option label when `VJoyCheckboxGroup` already provides a fieldset legend |
+| **MUST NOT** | Use Yes / No as the only labels in a multi-option list — name each option |
+| **SHOULD** | ≤ 60 characters per label; wrap rather than truncate |
+| **SHOULD** | Sentence case for standalone statements; title case or parallel nouns for option lists (match product locale rules) |
+| **SHOULD** | Put legal links or long explanations in `checkbox-content`, not in the primary label |
+| **SHOULD** | “Select all” / parent row: `Select all` or `Select all {noun}` — not `All` alone |
+
+### Patterns
+
+**Standalone** — One checkbox for consent, opt-in, or binary confirmation. Label is a full thought; details and links go in `checkbox-content`.
+
+**Multi-select list** — Options are independent (filters, permissions, export formats). Use a group legend via `VJoyCheckboxGroup` and short parallel option labels.
+
+**Bulk / select all** — Parent checkbox uses `indeterminate` when some children are checked; label e.g. `Select all items`. Child labels name each row.
+
+**Validation** — Pair `invalid` with explicit error text in `checkbox-content` or form-level error (e.g. “You must accept the terms to continue”). Don’t rely on red border alone.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Native `checkbox` via `<input type="checkbox">` |
+| Name | From default slot or `label` prop; associated via wrapping `<label>` |
+| Keyboard | **Space** toggles when focused; **Tab** moves focus |
+| Focus | Visible focus indicator (`joy-checkbox__focusing`); don’t remove in product CSS |
+| Grouping | Multiple related checkboxes: `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` property on the input |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { VJoyCheckbox } from '@maltjoy/core-vue'
+
+const agreed = ref(false)
+const selectAll = ref(false)
+const selected = ref(['email'])
+</script>
+
+<template>
+  <!-- Standalone consent -->
+  <VJoyCheckbox v-model:checked="agreed" label="I agree to the Terms of Service">
+    <template #checkbox-content>
+      <small>Read the <a href="/terms">Terms of Service</a>.</small>
+    </template>
+  </VJoyCheckbox>
+
+  <!-- Invalid until checked -->
+  <VJoyCheckbox
+    v-model:checked="agreed"
+    :invalid="!agreed"
+    label="I agree to the Terms of Service"
+  />
+
+  <!-- Indeterminate parent (no v-model:checked on same node) -->
+  <VJoyCheckbox :indeterminate="true" label="Select all projects" />
+
+  <!-- Multi-select value in a form -->
+  <VJoyCheckbox
+    v-model:checked="selected.includes('email')"
+    name="channels"
+    value="email"
+    label="Email notifications"
+    @update:checked="(on) => { /* update selected array */ }"
+  />
+
+  <!-- Disabled -->
+  <VJoyCheckbox disabled label="Archived project (cannot select)" />
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyCheckbox` is already global.
+
+For managed multi-select arrays, prefer `VJoyCheckboxGroup` — see its Storybook docs.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyCheckboxGroup` | Several related options; `v-model:value` as string array |
+| `VJoyCheckboxCard` | Checkbox with card chrome, title, sublabel, and body |
+| `VJoyRadio` / `VJoyRadioGroup` | Exactly one choice from a list |
+| `VJoyToggle` | Single on/off setting (especially settings-style rows) |
+| `VJoySelectableItem` | Custom list row; may embed `VJoyCheckbox` with `displayFocus={false}` |
+| `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 [`JoyCheckbox.dsds.json`](./JoyCheckbox.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Independent multi-select | `VJoyCheckbox` or `VJoyCheckboxGroup` | `VJoyRadio` |
+| Pick exactly one | `VJoyRadio` / `VJoyRadioGroup` | `VJoyCheckbox` |
+| Settings on/off row | `VJoyToggle` | Checkbox for a single immediate toggle |
+| Select all / partial selection parent | `VJoyCheckbox` with `indeterminate` | `indeterminate` + `v-model:checked` on same node |
+| Card with title + description | `VJoyCheckboxCard` | Raw `VJoyCheckbox` + custom card CSS |
+| Array of selected values | `VJoyCheckboxGroup` | Manual array wiring without group when options are fixed |
+
+### Hard rules
+
+1. **MUST** call `joy_get_component_info("VJoyCheckbox")` or read `JoyCheckbox.types.ts` before generating props.  
+2. **MUST** use `v-model:checked` (or `:checked` + `@update:checked`) for boolean state.  
+3. **MUST NOT** invent props — there is no `variant`, `size`, or `color`.  
+4. **MUST NOT** set `indeterminate` on the same instance as `v-model:checked`.  
+5. **MUST NOT** override `.joy-checkbox` size, border, or background with custom CSS.  
+6. **MUST** treat `invalid` as visible only when unchecked; checking clears invalid styling.  
+7. **SHOULD** use `checkbox-content` for helper text, links, and errors — not overloaded primary labels.  
+8. **SHOULD** use `value` + `name` when multiple checkboxes submit as part of one form field set.
+
+### Checklist
+
+- [ ] Correct component (`VJoyCheckbox` or named alternative)
+- [ ] Props from MCP / types only — no invented API
+- [ ] `v-model:checked` wired; indeterminate parent not v-modelled
+- [ ] Visible label on every instance
+- [ ] No custom `.joy-checkbox` chrome CSS
+- [ ] Exclusive choice → radio, not checkbox
+- [ ] Multi-option array → consider `VJoyCheckboxGroup`
+- [ ] Invalid / disabled states have explanatory text when user-visible
+- [ ] `id` / `name` / `value` set appropriately for forms
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyCheckbox.dsds.json`](./JoyCheckbox.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy | `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 |
+| Token sizing | `design-specifications` in JSON (token names, not raw px dumps) |