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

package/dist/doc/VJoyInput/guideline.md

@@ -0,0 +1,401 @@
+---
+component: VJoyInput
+status: draft
+language: en
+dsds: JoyInput.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Input
+
+Use **`VJoyInput`** when the user needs to enter a single line of text — names, emails, search queries, short identifiers, or other free-form values in a form.
+
+It supports labels, optional leading icons, a clear action, validation styling, and binds to `v-model`. Native attributes such as `placeholder`, `autocomplete`, and `aria-*` pass through to the underlying `<input>`.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyInput` from `@maltjoy/core-vue` |
+| **Design** | [Figma — Joy Core Design System](https://www.figma.com/design/jfndp2QBJGS9yeuWbeGuvD/) |
+| **Storybook** | [VJoyInput docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-forms-vjoyinput--docs) |
+| **DSDS (machine)** | [`JoyInput.dsds.json`](./JoyInput.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyInput")` |
+
+---
+
+## When to use this component
+
+Use an input when someone must type or paste a value that is not constrained to a fixed list — for example an email address, company name, reference code, or search term.
+
+Pair it with a visible label, validation feedback when needed, and (inside forms) `VJoyWrapper` for consistent spacing.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Password with show/hide toggle | `VJoyInputPassword` |
+| Numeric value with a unit suffix (€, %, days…) | `VJoyInputNumber` |
+| Multi-line text (description, comment, bio) | `VJoyTextarea` |
+| One-time / verification code (OTP) | `VJoyInputDigit` |
+| Choosing from a known set of options | `VJoySelect`, `VJoyRadio`, or `VJoySelectableItemGroup` |
+| Multiple tags or tokenized values | `VJoyTagsInput` |
+| Read-only display of existing data | `VJoyText` or plain text — not a disabled input masquerading as content |
+| Custom-styled `<input>` / ad-hoc field chrome | Still use `VJoyInput` + Joy tokens |
+
+> **Deprecated:** do not use the default slot for labels on new work — prefer the `label` prop or a separate `VJoyLabel`. Do not use `type="password"` on `VJoyInput` — use `VJoyInputPassword`.
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Root container | Yes | Size wrapper (`joy-input--{size}`) |
+| Label | No | `VJoyLabel` from the `label` prop (or deprecated default slot) |
+| Field wrapper | Yes | Positions icon, input, clear control, and `right-action` slot |
+| Leading icon | No | Decorative `VJoyIcon` on the left (`icon` prop) |
+| Native `<input>` | Yes | The actual form control; receives `$attrs` (placeholder, autocomplete, etc.) |
+| Clear control | No | `VJoyIconButton` when `clearable` and the field has a non-empty string value |
+| Right action | No | `right-action` slot for custom trailing UI (e.g. password toggle in `VJoyInputPassword`) |
+| Focus ring | Yes | Applied on focus via Joy form-field tokens — do not remove in product CSS |
+
+### Default values
+
+- `size` defaults to **`medium`**
+- `type` defaults to **`text`**
+- `labelSize` defaults to **`medium`**
+- `modelModifiers` defaults to **`{ lazy: false }`** (updates on `input`)
+- `clearAriaLabel` defaults to **`"Clear input"`** — override when `clearable` is true
+- `disabled`, `invalid`, `required`, `readonly`, `clearable`, `requiredMark`, and `autofocus` default to **`false`**
+
+Props, events, and slots: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+---
+
+## Variants
+
+`VJoyInput` has no visual “variant” prop (no primary/secondary). Visual meaning comes from **state** (`invalid`, `disabled`, `readonly`) and **density** (`size`).
+
+### Default (valid)
+
+Use for standard editable fields. Border uses neutral tokens; focus uses `--joy-color-state-focus`.
+
+### Invalid
+
+Set `invalid` when server-side or client-side validation failed. Pair with `VJoyFormError` (or equivalent) so the error is announced — the red border alone is not enough.
+
+Avoid toggling `invalid` while the user is still typing unless the value is clearly wrong (e.g. empty required field on blur).
+
+### Readonly
+
+Use when the value must remain visible but not editable (e.g. prefilled reference). Prefer readonly over disabled when the user should still read and copy the value.
+
+### Disabled
+
+Use when the field cannot be edited and the reason is external (permissions, workflow step). **Always explain why** nearby.
+
+### Not in the API: `unit`
+
+Joy MCP may list a `unit` prop on `VJoyInput`. It is **not** on `VJoyInputProps` in `JoyInput.types.ts`. Use **`VJoyInputNumber`** for values with a trailing unit label.
+
+### Not in the API: floating label
+
+Some legacy design docs describe a floating label pattern. `VJoyInput` uses a **top label** (`label` / `VJoyLabel`) — do not simulate floating labels with custom CSS.
+
+---
+
+## Sizes
+
+Choose size for **density** within the form. Heights and radii come from `--joy-form-field-height-*` and `--joy-form-field-radius-*` — **do not hardcode pixel heights** in apps.
+
+| Size | Use when |
+| --- | --- |
+| `small` | Dense toolbars, filter bars, inline filters (often with a search icon) |
+| `medium` | Default product forms |
+| `large` | Marketing-scale or hero forms where fields need more prominence |
+
+Match label size to field size when possible (`labelSize` aligns with `VJoyLabel` sizes).
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Default | Empty or filled; editable; neutral border |
+| Hover | Border shifts to `--joy-color-state-hover` (pointer devices) |
+| Focus | Focus border `--joy-color-state-focus`; wrapper gets `joy-input--focusing` |
+| Valid (implicit) | `joy-input--valid` when not `invalid` and not disabled |
+| Invalid | Error border and text color; icon follows error color |
+| Disabled | Not interactive; muted background and border; explain why nearby |
+| Readonly | Value visible; no edit; default cursor; no focus styling for readonly |
+| Clearable | Clear icon appears when `clearable` and string `modelValue` is non-empty; clears via `update:modelValue` with `''` |
+
+`type="number"` fields block mouse-wheel from changing the value while focused.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Labels and forms
+
+- **MUST** provide a visible label for every input (via `label`, `VJoyLabel`, or an associated `<label for="…">`).
+- **MUST** set `name` (and `id` when multiple fields share a form) so labels, autofill, and tests bind correctly. `id` falls back to `name`.
+- **SHOULD** use `requiredMark` together with `required` when the asterisk pattern is used in the product.
+- **SHOULD** use `optionalLabel` on non-required fields when the form mixes required and optional inputs.
+- **SHOULD** wrap related fields in `VJoyWrapper` for spacing; margin adjusts automatically when inside a wrapper.
+
+### Implementation
+
+- **MUST** use only documented prop / enum values from MCP or `JoyInput.types.ts`.
+- **MUST** bind value with `v-model` (`modelValue` / `update:modelValue`).
+- **MUST** style with Joy tokens — no custom `.joy-input` chrome (border, height, radius, padding).
+- **MUST NOT** invent props (`unit`, `variant`, `errorMessage`, …).
+- **MUST NOT** use `type="password"` — use `VJoyInputPassword`.
+- **MUST** override `clearAriaLabel` when the default `"Clear input"` is too generic (e.g. `"Clear search"`).
+- **SHOULD** use `v-model.lazy` (via `modelModifiers: { lazy: true }`) when updates on every keystroke are expensive.
+
+### Validation and errors
+
+- **MUST** set `invalid` when showing a validation error for this field.
+- **MUST** show the error message in `VJoyFormError` (or equivalent) below the field — not only red border.
+- **MUST NOT** rely on placeholder color alone to convey errors.
+
+### Icons and actions
+
+- **SHOULD** use `icon` only when it reinforces meaning (search, calendar, user) — decorative-only icons add noise.
+- **SHOULD** use `clearable` for search or filter fields where resetting is common.
+- **MUST NOT** put the only accessible name of the field on an icon — the label carries the name.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `label` + `name` on every field | Placeholder as the only label |
+| `VJoyFormError` with `invalid` | Red border with no message |
+| `VJoyInputPassword` for passwords | `type="password"` on `VJoyInput` |
+| `VJoyInputNumber` for amounts with units | Invented `unit` prop on `VJoyInput` |
+| `clearAriaLabel` tailored to context | Generic clear button with no accessible name |
+| Joy form-field size tokens | Hardcoded `32` / `40` / `48`px heights |
+
+---
+
+## Content
+
+Inputs expose label, placeholder, and optional helper copy. All must help users enter the **right** value the **first** time.
+
+### Label formula
+
+**Noun or short noun phrase** describing the data (not the action):
+
+- ✅ Email address  
+- ✅ Company name  
+- ✅ Project reference  
+
+Use sentence case. Questions are acceptable for uncommon fields (✅ `What is your VAT number?`) but prefer nouns when the field is standard.
+
+### Placeholder formula
+
+**Example or format hint** — not a repeat of the label:
+
+- ✅ `name@company.com` (under label “Email address”)  
+- ✅ `AB-12345` (under label “Reference code”)  
+
+- ❌ `Email address` as placeholder when the label already says “Email address”
+
+### Optional / required markers
+
+| Pattern | When |
+| --- | --- |
+| `required` + `requiredMark` | Required field in a form that uses asterisks |
+| `optionalLabel` (e.g. “optional”) | Field is not required among mostly required fields |
+
+Do not mark every optional field “optional” when the form is entirely optional.
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | Every field has a visible label — never placeholder-only |
+| **MUST** | Error messages state what went wrong and how to fix it — ✅ `Enter a valid email address` · ❌ `Invalid` |
+| **MUST** | `clearAriaLabel` describes what is cleared — ✅ `Clear search` · ❌ `Click here` |
+| **MUST NOT** | Use labels that only make sense after failure — ❌ `Correct email` |
+| **MUST NOT** | Embed instructions inside the label that belong in helper text |
+| **SHOULD** | Keep labels ≤ 3–5 words when possible |
+| **SHOULD** | Use placeholders for format examples, not requirements |
+| **SHOULD** | Match autocomplete attributes to the data (`email`, `name`, `organization`) via native attrs |
+| **SHOULD** | Use consistent terminology with adjacent fields and page headings |
+| **SHOULD** (FR) | Follow French grammar for labels and optional markers when the UI is localized |
+
+### Patterns
+
+**Forms** — One idea per field. Split “First name” and “Last name” instead of a single “Full name” when both are needed downstream.
+
+**Search / filters** — Short placeholder with action implied: `Search projects…`. Pair with `icon="search"` and `clearable` when results update live.
+
+**Readonly / disabled** — Label stays descriptive; explain unavailability in helper text or tooltip, not by changing the label to “Disabled email”.
+
+**Errors** — Show on blur or submit for most fields; avoid shouting errors on first keystroke unless the format is unambiguous (e.g. OTP length).
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Native `<input>` with appropriate `type` |
+| Name | From associated `VJoyLabel` / `<label for>`; `label` prop wires `for` to `id \|\| name` |
+| Value | Controlled via `v-model`; clear action emits empty string |
+| Keyboard | Standard text editing; Tab moves focus; clear button is a real button (`VJoyIconButton`) |
+| Focus | Visible focus ring on the input — do not remove `outline` / focus tokens |
+| Invalid | `invalid` styles the field; pair with `VJoyFormError` (`role="alert"`) for the message |
+| Disabled | Native `disabled`; do not rely on color alone — provide text explanation |
+| Readonly | Native `readonly`; value still readable and copyable |
+| Icons | Leading icon is decorative; clear button has `clearAriaLabel` |
+| Autocomplete | Pass `autocomplete` via attrs when the data type is known |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { VJoyInput, VJoyLabel, VJoyFormError, VJoyWrapper } from '@maltjoy/core-vue'
+
+const email = ref('')
+const search = ref('')
+const showError = ref(false)
+</script>
+
+<template>
+  <!-- Standard form field -->
+  <VJoyWrapper direction="column" row-gap="4">
+    <VJoyInput
+      v-model="email"
+      name="email"
+      label="Email address"
+      placeholder="name@company.com"
+      autocomplete="email"
+      required
+      required-mark
+      :invalid="showError"
+    />
+    <VJoyFormError v-if="showError" message="Enter a valid email address" />
+  </VJoyWrapper>
+
+  <!-- Search with icon + clear -->
+  <VJoyInput
+    v-model="search"
+    name="project-search"
+    size="small"
+    icon="search"
+    clearable
+    clear-aria-label="Clear search"
+    placeholder="Search projects…"
+  />
+
+  <!-- Custom label composition -->
+  <VJoyLabel for="company-legal-name" required>
+    Legal company name
+    <template #label-legend>As shown on official documents</template>
+  </VJoyLabel>
+  <VJoyInput
+    id="company-legal-name"
+    v-model="email"
+    name="company-legal-name"
+    placeholder="Acme SAS"
+  />
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyInput` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyLabel` | Rich labels (legend, tooltip) separate from the field |
+| `VJoyFormError` | Inline validation message below the field |
+| `VJoyWrapper` | Form layout and spacing between fields |
+| `VJoyInputPassword` | Password entry with visibility toggle |
+| `VJoyInputNumber` | Numeric values with optional unit suffix |
+| `VJoyTextarea` | Multi-line text |
+| `VJoyInputDigit` | Fixed-length codes (OTP, PIN) |
+| `VJoySelect` | Single choice from a list |
+| `VJoyIcon` / `VJoyIconButton` | Icons inside `right-action` when building composed fields |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyInput.dsds.json`](./JoyInput.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Single-line free text | `VJoyInput` | Raw `<input class="…">` |
+| Password | `VJoyInputPassword` | `VJoyInput` + `type="password"` |
+| Number with unit (€, %, days) | `VJoyInputNumber` | `VJoyInput` + `unit` |
+| Multi-line text | `VJoyTextarea` | Tall `VJoyInput` |
+| OTP / verification code | `VJoyInputDigit` | Multiple single-char `VJoyInput`s |
+| Pick one of N known options | `VJoySelect` / radios | `VJoyInput` with datalist hack |
+| Search/filter bar | `VJoyInput` + `icon="search"` + optional `clearable` | Custom search div |
+| Display-only value | `VJoyText` | `disabled` input without reason |
+
+### Hard rules
+
+1. **MUST** call `joy_get_component_info("VJoyInput")` or read `JoyInput.types.ts` before generating props.  
+2. **MUST** bind `v-model` for editable values.  
+3. **MUST** set `name` (and `id` when needed for label association).  
+4. **MUST** pass native attrs (`placeholder`, `autocomplete`, `maxlength`, `aria-*`) on the component — they flow to `<input>`.  
+5. **MUST** set `invalid` when showing validation errors and render `VJoyFormError` with a message.  
+6. **MUST** set a specific `clearAriaLabel` when `clearable` is true.  
+7. **MUST NOT** emit `unit` on `VJoyInput` — use `VJoyInputNumber`.  
+8. **MUST NOT** emit `type="password"` — use `VJoyInputPassword`.  
+9. **MUST NOT** use the default slot for new labels — use `label` or `VJoyLabel`.  
+10. **MUST NOT** override `.joy-input` height, border, radius, or padding.  
+11. **SHOULD** use `size="small"` in dense toolbars; default `medium` elsewhere.  
+12. **SHOULD** use `VJoyWrapper` in multi-field forms.
+
+### Checklist
+
+- [ ] Correct component (or named alternative from table above)
+- [ ] Props / enums from MCP or types only
+- [ ] `v-model` + `name` present
+- [ ] Visible label (not placeholder-only)
+- [ ] `invalid` + `VJoyFormError` when validation fails
+- [ ] `clearAriaLabel` set when `clearable`
+- [ ] No invented props / no custom input chrome CSS
+- [ ] Password → `VJoyInputPassword`; number + unit → `VJoyInputNumber`
+- [ ] Disabled / readonly explained if user-visible
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyInput.dsds.json`](./JoyInput.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy | `anatomy` |
+| Sizes | `variants` |
+| 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 (`--joy-form-field-height-*`, `--joy-form-field-radius-*`) |

package/dist/doc/VJoyInput/metadata.json

@@ -1,7 +1,7 @@
 {
   "name": "JoyInput",
   "displayName": "VJoyInput",
-  "description": "A comprehensive form input component with extensive customization and validation features.\nSupports multiple input types, icon support, clearable functionality, unit displays, and comprehensive validation states.\nFeatures auto-focus capabilities, accessibility compliance, and seamless integration with form validation systems.",
+  "description": "A comprehensive form input component with extensive customization and validation features.\nSupports multiple input types, icon support, clearable functionality, and comprehensive validation states.\nFeatures auto-focus capabilities, accessibility compliance, and seamless integration with form validation systems.",
   "category": "Forms",
   "props": [
     {
@@ -163,18 +163,9 @@
       "type": "string | undefined",
       "required": false,
       "default": "\"text\"",
-      "description": "",
+      "description": "HTML input type. Use VJoyInputPassword for password fields.",
       "possibleValues": null
     },
-    {
-      "name": "unit",
-      "type": "string | undefined",
-      "required": false,
-      "description": "Adds a legend like symbol on the right of the component. Made for number based values",
-      "possibleValues": [
-        "string"
-      ]
-    },
     {
       "name": "readonly",
       "type": "boolean | undefined",
@@ -311,9 +302,9 @@
       "isMethod": true
     },
     {
-      "name": "unit",
-      "type": "string | undefined",
-      "isMethod": false
+      "name": "focus",
+      "type": "() => void",
+      "isMethod": true
     }
   ],
   "hasVModel": true