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

package/dist/doc/VJoyInputDigit/guideline.md

@@ -0,0 +1,381 @@
+---
+component: VJoyInputDigit
+status: draft
+language: en
+dsds: JoyInputDigit.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Input digit
+
+Use **`VJoyInputDigit`** when the user must enter a **fixed-length numeric code** — SMS or email verification (OTP), two-factor authentication, or a short PIN.
+
+It renders a row of single-character fields, auto-advances focus as digits are typed, supports paste across slots, and binds to `v-model` as one joined string. Each slot is a `VJoyInput` with `autocomplete="one-time-code"` for mobile OTP autofill.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyInputDigit` from `@maltjoy/core-vue` |
+| **Design** | [Figma — Joy Core Design System](https://www.figma.com/design/jfndp2QBJGS9yeuWbeGuvD/) |
+| **Storybook** | [VJoyInputDigit docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-forms-vjoyinputdigit--docs) |
+| **DSDS (machine)** | [`JoyInputDigit.dsds.json`](./JoyInputDigit.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyInputDigit")` |
+
+---
+
+## When to use this component
+
+Use an input digit when the expected value is **exactly N digits** (default **6**) and splitting the code into separate boxes helps users read, verify, and paste codes from SMS or authenticator apps.
+
+Typical flows: account verification after sign-up, login step-up, payment confirmation, or device pairing. Pair the control with a visible group label (`VJoyLabel`), instructions, and `VJoyFormError` when validation fails.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Single-line free text (email, name, search) | `VJoyInput` |
+| Password with show/hide toggle | `VJoyInputPassword` |
+| Numeric value with unit (€, %, days…) | `VJoyInputNumber` |
+| Multi-line text | `VJoyTextarea` |
+| Alphanumeric or variable-length codes | `VJoyInput` (with `maxlength` and validation) |
+| Choosing from a known set of options | `VJoySelect` or `VJoyRadio` |
+| Several hand-built single-char `VJoyInput`s | `VJoyInputDigit` — it handles focus, paste, and joined `v-model` |
+| Custom-styled OTP boxes | Still use `VJoyInputDigit` + Joy tokens |
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Wrapper | Yes | Root `.joy-input-digit__wrapper` (inline-flex column) |
+| Slot row | Yes | `.joy-input-digit` flex container with gap between cells |
+| Digit cell | Yes | One `VJoyInput` per slot (`size="medium"`, `type="number"`, `inputmode="numeric"`, `maxlength="1"`) |
+| Joined value | Yes | `v-model` / `modelValue` — all digits concatenated (e.g. `"204918"`) |
+| Focus ring | Yes | Inherited from inner `VJoyInput` — do not remove in product CSS |
+
+Native attributes (`data-test`, `aria-*`, etc.) passed on the component are forwarded to **every** inner `<input>`. The `name` prop becomes a prefix: `name-1`, `name-2`, … per slot.
+
+### Default values
+
+- `modelValue` defaults to **`""`**
+- `length` defaults to **`6`** (minimum effective length is **1**)
+- `invalid` defaults to **`false`**
+- `disabled` defaults to **`false`**
+- `name` defaults to **`"joy-input-digit"`**
+- `inputAriaLabel` defaults to **`"Digit"`** — each slot gets `{inputAriaLabel} {index}/{length}` (e.g. `Digit 1/6`)
+
+Props, events, and exposed members: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Interaction model
+
+- **Type** — Digits `0–9` only; non-numeric keys are blocked. Entering a digit moves focus to the next slot.
+- **Multi-char input** — Typing or pasting several digits at once fills subsequent slots from the current index.
+- **Backspace** — Clears the current slot; if already empty, focus moves to the previous slot.
+- **Arrow keys** — Left / right move between slots; up / down are suppressed.
+- **Paste** — Clipboard text is sanitized to digits and distributed across slots from the focused index.
+- **Focus / click** — Content of the active slot is selected for easy replacement.
+
+`change` emits whenever the joined value changes (with the originating `Event`). Use `focusInput(index)` from a template ref when you need programmatic focus (e.g. after a resend-code action).
+
+---
+
+## Variants
+
+`VJoyInputDigit` has **no visual variant prop** (no primary/secondary). Meaning comes from **state** (`invalid`, `disabled`) applied uniformly to every slot.
+
+### Default (valid)
+
+Use for standard OTP entry. Inner inputs use centered text and Joy form-field tokens.
+
+### Invalid
+
+Set `invalid` when the submitted code failed verification. Pair with `VJoyFormError` (or equivalent) — the red border on each cell is not enough on its own.
+
+Avoid toggling `invalid` while the user is still typing unless the code length is complete and clearly wrong.
+
+### Disabled
+
+Use when entry is blocked (cooldown, permissions, workflow step). **Always explain why** nearby.
+
+### Not in the API: per-slot size
+
+Inner inputs are always `size="medium"` with digit-specific geometry from `--input-digit-*` tokens in `JoyInputDigit.scss`. There is no `size` prop — do not simulate small/large OTP cells with custom CSS.
+
+### Not in the API: letters or separators
+
+Only single numeric digits are accepted. Alphanumeric codes or masked patterns (e.g. `XXX-XXX`) are not supported — use `VJoyInput` with validation instead.
+
+---
+
+## Sizes
+
+The component exposes **no size API**. Cell width, height, gap, radius, and font size are defined by Joy tokens inside the component:
+
+| Token / aspect | Source |
+| --- | --- |
+| Cell width | `--joy-core-spacing-9` via `--input-digit-width` |
+| Cell height | `--input-digit-height` (56px in component SCSS) |
+| Corner radius | `--joy-core-radius-3` |
+| Gap between cells | `--input-digit-gap` (10px) |
+| Typography | `--joy-font-size-primary-600` |
+
+**Do not hardcode** OTP box dimensions in apps — overrides break alignment with `VJoyInput` focus and error states.
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Default | Empty or partially filled slots; editable; neutral borders from inner `VJoyInput` |
+| Focus | Active slot selected; visible focus ring on the inner input |
+| Filled | Digits centered in each cell; joined `modelValue` updates on every change |
+| Invalid | Error border and text color on **all** slots when `invalid` is true |
+| Disabled | All slots non-interactive; muted styling; explain why nearby |
+| Paste | Multiple digits fill from the focused index; non-digits stripped |
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Labels and forms
+
+- **MUST** provide a visible group label (`VJoyLabel` or equivalent) describing what code is expected — slots alone are not a sufficient name.
+- **MUST** set `name` to a stable, form-specific prefix (e.g. `signup-otp`) so autofill and tests bind correctly.
+- **SHOULD** set `inputAriaLabel` to match the group label context — ✅ `Security code digit` · default `Digit` is generic.
+- **SHOULD** wrap the field with instructions and errors in `VJoyWrapper` for consistent spacing.
+- **SHOULD** match `length` to the backend contract (4, 6, 8…) — do not assume 6 if the API expects another length.
+
+### Implementation
+
+- **MUST** bind with `v-model` (`modelValue` / `update:modelValue`).
+- **MUST** use only documented props from MCP or `JoyInputDigit.types.ts`.
+- **MUST** style with Joy tokens — no custom `.joy-input-digit` chrome (width, height, gap, border).
+- **MUST NOT** invent props (`size`, `variant`, `mask`, `separator`, …).
+- **MUST NOT** compose several standalone `VJoyInput` fields for OTP — use `VJoyInputDigit`.
+- **MUST** set `invalid` when showing a verification error and render `VJoyFormError` with a actionable message.
+- **SHOULD** call `focusInput(0)` after resending a code so keyboard users can continue immediately.
+
+### Interaction
+
+- **SHOULD** auto-submit or advance the flow when `modelValue.length === length` only if the product spec requires it — still handle invalid codes gracefully.
+- **SHOULD** offer “Resend code” as a separate action (link or button), not inside the digit cells.
+- **MUST NOT** clear the field silently on error without telling the user what to do next.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `VJoyInputDigit` + group label + error message | Six bare inputs with no label |
+| `length` aligned with server OTP size | Always default 6 when API sends 4 digits |
+| `inputAriaLabel` tied to the flow (`Verification code digit`) | Rely on `Digit` in production |
+| `invalid` + `VJoyFormError` on failed verify | Red cells with no explanation |
+| Joy digit tokens | Hardcoded `48px` / `56px` cell sizes |
+| Paste-friendly joined `v-model` | Manual per-cell state in the parent |
+
+---
+
+## Content
+
+Copy around an OTP field should reduce anxiety and tell users **where** the code comes from and **what** to do if it fails.
+
+### Group label formula
+
+**Noun phrase** naming the code, not the action:
+
+- ✅ Verification code  
+- ✅ Security code  
+- ✅ Authentication code  
+
+### Instruction formula
+
+**Where the code was sent + what to enter**:
+
+- ✅ `Enter the 6-digit code we sent to name@company.com.`  
+- ✅ `Enter the code from your authenticator app.`
+
+### Error formula
+
+**What failed + how to recover**:
+
+- ✅ `That code didn’t work. Check the message and try again, or resend a new code.`  
+- ❌ `Invalid code`
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | Label the group, not each cell — cell names come from `inputAriaLabel` |
+| **MUST** | State code length when it is not 6 — ✅ `Enter the 4-digit PIN` with `length="4"` |
+| **MUST** | Error messages explain retry or resend — not only `Invalid` |
+| **MUST NOT** | Use placeholder text inside digit cells — they are single-digit inputs |
+| **MUST NOT** | Embed the secret code in helper text |
+| **SHOULD** | Mention expiry or resend cooldown in helper text when applicable |
+| **SHOULD** | Keep `inputAriaLabel` short and consistent with the visible label |
+| **SHOULD** | Localize group label, instructions, errors, and `inputAriaLabel` together |
+
+### Patterns
+
+**Email / SMS OTP** — Label “Verification code”, instruction with destination email or phone, resend link below, auto-focus first slot on mount.
+
+**2FA app** — Label “Authentication code”, instruction references the app; `length` often 6.
+
+**PIN (4 digits)** — Set `length="4"`; label “PIN” or “Security PIN”; avoid calling it a “password” unless it truly is one.
+
+**Failed verify** — Set `invalid`, show `VJoyFormError`, keep entered digits visible so the user can edit rather than retype from scratch unless security policy requires clearing.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Row of native `<input type="number">` elements (via inner `VJoyInput`) |
+| Group name | From associated `VJoyLabel` / page heading — supplement with instructions |
+| Per-slot name | `aria-label` from `inputAriaLabel` + index (`Verification code digit 1/6`) |
+| Value | Joined string via `v-model`; each cell holds one digit |
+| Keyboard | Digits `0–9`; **Backspace** edits or moves back; **Arrow left/right** move between slots; **Tab** moves out of the group |
+| Focus | Visible focus ring on the active inner input — do not remove focus tokens |
+| Paste | Supported; non-digits stripped — announce errors separately via `VJoyFormError` |
+| Autofill | `autocomplete="one-time-code"` on each input for SMS OTP autofill on supported platforms |
+| Invalid | `invalid` styles all slots; pair with `VJoyFormError` (`role="alert"`) for the message |
+| Disabled | All slots `disabled`; do not rely on color alone — provide text explanation |
+| Tracking | Each inner input exposes `data-joy-form-field` for design-system field collection |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import {
+  VJoyInputDigit,
+  VJoyLabel,
+  VJoyFormError,
+  VJoyWrapper,
+} from '@maltjoy/core-vue'
+
+const code = ref('')
+const showError = ref(false)
+
+async function verify() {
+  showError.value = code.value.length === 6 && code.value !== '123456'
+}
+</script>
+
+<template>
+  <VJoyWrapper direction="column" row-gap="4">
+    <VJoyLabel for="signup-otp">Verification code</VJoyLabel>
+    <p>Enter the 6-digit code we sent to your email.</p>
+
+    <VJoyInputDigit
+      id="signup-otp"
+      v-model="code"
+      name="signup-otp"
+      :length="6"
+      input-aria-label="Verification code digit"
+      :invalid="showError"
+      @change="verify"
+    />
+
+    <VJoyFormError
+      v-if="showError"
+      message="That code didn't work. Check your email and try again."
+    />
+  </VJoyWrapper>
+
+  <!-- 4-digit PIN -->
+  <VJoyInputDigit
+    v-model="code"
+    name="device-pin"
+    :length="4"
+    input-aria-label="PIN digit"
+    disabled
+  />
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyInputDigit` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyInput` | Single-line free text; not fixed-length numeric codes |
+| `VJoyLabel` | Group label above the digit row |
+| `VJoyFormError` | Inline message when verification fails |
+| `VJoyWrapper` | Spacing between label, digit row, helper, and error |
+| `VJoyButton` | Submit, resend code, or continue after entry |
+| `VJoyInputPassword` | Secret strings with visibility toggle |
+| `VJoyInputNumber` | Numeric values with optional unit suffix |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyInputDigit.dsds.json`](./JoyInputDigit.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Fixed-length numeric OTP / PIN | `VJoyInputDigit` | Multiple `VJoyInput` with `maxlength="1"` |
+| Single-line text or email | `VJoyInput` | `VJoyInputDigit` |
+| Alphanumeric backup codes | `VJoyInput` + validation | `VJoyInputDigit` |
+| Password | `VJoyInputPassword` | `VJoyInputDigit` |
+| Amount with currency unit | `VJoyInputNumber` | `VJoyInputDigit` |
+
+### Hard rules
+
+1. **MUST** call `joy_get_component_info("VJoyInputDigit")` or read `JoyInputDigit.types.ts` before generating props.  
+2. **MUST** bind `v-model` for the joined digit string.  
+3. **MUST** set `name` to a unique form prefix.  
+4. **MUST** set `length` to match the expected code size (default `6`).  
+5. **MUST** set `inputAriaLabel` to a meaningful base string (not bare `Digit` in product UI).  
+6. **MUST** set `invalid` when verification fails and render `VJoyFormError` with a message.  
+7. **MUST NOT** invent props (`size`, `variant`, `mask`, `type`, …).  
+8. **MUST NOT** override `.joy-input-digit` or inner `.joy-input` width, height, gap, or border.  
+9. **SHOULD** pair with a visible `VJoyLabel` and short instructions.  
+10. **SHOULD** use `focusInput(0)` on the exposed ref after resend-code actions.
+
+### Checklist
+
+- [ ] Correct component (`VJoyInputDigit`, not manual OTP inputs)
+- [ ] Props from MCP or types only
+- [ ] `v-model` + `name` present
+- [ ] `length` matches backend OTP size
+- [ ] Visible group label + `inputAriaLabel` aligned with copy
+- [ ] `invalid` + `VJoyFormError` on verification failure
+- [ ] No invented props / no custom digit-cell CSS
+- [ ] Disabled state explained if user-visible
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyInputDigit.dsds.json`](./JoyInputDigit.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy / interaction | `anatomy` |
+| Variants (state-based) | `variants` |
+| Sizes (fixed geometry) | `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 |