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

package/dist/doc/VJoyInputNumber/guideline.md

@@ -0,0 +1,414 @@
+---
+component: VJoyInputNumber
+status: draft
+language: en
+dsds: JoyInputNumber.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Input Number
+
+Use **`VJoyInputNumber`** when the user must enter a numeric value that is shown with a **unit suffix** on the right — amounts (€), percentages (%), durations (days), or other quantities where the unit is fixed for the field.
+
+It is built on `VJoyInput` with `type="number"` by default, supports labels and validation states, and binds to `v-model`. Native attributes such as `placeholder`, `min`, `max`, `step`, and `aria-*` pass through to the underlying `<input>`.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyInputNumber` from `@maltjoy/core-vue` |
+| **Design** | [Figma — Joy Core Design System](https://www.figma.com/design/jfndp2QBJGS9yeuWbeGuvD/) |
+| **Storybook** | [VJoyInputNumber docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-forms-vjoyinputnumber--docs) |
+| **DSDS (machine)** | [`JoyInputNumber.dsds.json`](./JoyInputNumber.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyInputNumber")` |
+
+---
+
+## When to use this component
+
+Use a number input with unit when someone must type or adjust a quantity and the unit is **known and fixed** for that field — for example a price in euros, a percentage, or a duration in days.
+
+Pair it with a visible label, validation feedback when needed, and (inside forms) `VJoyWrapper` for consistent spacing. Set `unit` to the symbol or short suffix users expect; use `unit=""` when no suffix should appear but you still want number-input behaviour from this component.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Free-form text (names, emails, references) | `VJoyInput` |
+| Numeric value **without** a unit suffix | `VJoyInput` with `type="number"` |
+| Password with show/hide toggle | `VJoyInputPassword` |
+| Multi-line text | `VJoyTextarea` |
+| One-time / verification code (OTP) | `VJoyInputDigit` |
+| Choosing from a known set of options | `VJoySelect`, `VJoyRadio`, or `VJoySelectableItemGroup` |
+| Numeric value with a **clear** action | `VJoyInput` with `type="number"` and `clearable` — `VJoyInputNumber` does not support `clearable` |
+| `unit` on `VJoyInput` (legacy) | `VJoyInputNumber` — the `unit` prop was removed from `VJoyInput` in v6 |
+| Custom-styled `<input>` / ad-hoc field chrome | Still use `VJoyInputNumber` + Joy tokens |
+
+> **Deprecated:** do not use the default slot for labels on new work — prefer the `label` prop or a separate `VJoyLabel`. Do not pass `clearable` or `clearAriaLabel` — they are stripped and not supported on this component.
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Root wrapper | Yes | `joy-input-unit` container around the inner input |
+| Inner `VJoyInput` | Yes | Handles label, field chrome, validation styling, and the native `<input>` |
+| Label | No | `VJoyLabel` from the `label` prop (or deprecated default slot) |
+| Native `<input>` | Yes | Form control; `type` defaults to `number`; receives forwarded attrs |
+| Unit badge | No | Pill on the right (`unit` prop); hidden when `unit` is an empty string |
+| Leading icon | No | Decorative `VJoyIcon` on the left (`icon` prop) |
+| Focus ring | Yes | Applied on focus via Joy form-field tokens — do not remove in product CSS |
+
+The unit renders in the `right-action` slot of the inner input. It is **presentational** — the value in `v-model` does not include the unit string.
+
+### Default values
+
+- `type` defaults to **`number`**
+- `unit` defaults to **`€`**
+- `name` defaults to **`joy-input-number`**
+- `size` defaults to **`medium`** (inherited from inner `VJoyInput`)
+- `labelSize` defaults to **`medium`**
+- `modelModifiers` defaults to **`{ lazy: false }`** (updates on `input`)
+- `disabled`, `invalid`, `required`, `readonly`, `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
+
+`VJoyInputNumber` has no visual “variant” prop. Visual meaning comes from **state** (`invalid`, `disabled`, `readonly`) and **density** (`size`).
+
+### Default (valid)
+
+Use for standard editable numeric 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 quote amount). 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: `clearable`
+
+`VJoyInputNumber` omits `clearable` and `clearAriaLabel` from its props. Attributes with those names are **ignored** — do not rely on a clear button. Use `VJoyInput` with `type="number"` when a clear action is required.
+
+### Not in the API: custom unit slot
+
+The unit is controlled only by the `unit` string prop. There is no slot to replace the unit badge with custom markup.
+
+---
+
+## Sizes
+
+Choose size for **density** within the form. Field heights come from `--joy-form-field-height-*`; the unit badge scales with the field via `--input-unit-height` — **do not hardcode pixel heights** in apps.
+
+| Size | Use when |
+| --- | --- |
+| `small` | Dense toolbars, filter bars, inline numeric filters |
+| `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; unit badge visible when `unit` is non-empty |
+| 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 |
+| Disabled | Not interactive; muted styling; explain why nearby |
+| Readonly | Value visible; no edit; no focus styling for readonly |
+| Empty unit | `unit=""` hides the unit badge; input behaves as a number field without suffix |
+
+Mouse-wheel does not change the value while a `type="number"` field is focused (inherited from `VJoyInput`).
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Labels and forms
+
+- **MUST** provide a visible label for every field (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.
+
+### Unit and value
+
+- **MUST** set `unit` to the correct suffix for the field (`€`, `%`, `days`, …) — do not bake the unit into the label when the badge already shows it.
+- **SHOULD** use `unit=""` only when you need this component’s number behaviour without a visible suffix.
+- **MUST NOT** store the unit in `v-model` — the model is the numeric string only; formatting with unit belongs in display/submit logic.
+- **SHOULD** pass `min`, `max`, and `step` via native attrs when the allowed range is fixed.
+
+### Implementation
+
+- **MUST** use only documented prop / enum values from MCP or `JoyInput.types.ts` (plus `unit` on this component).
+- **MUST** bind value with `v-model` (`modelValue` / `update:modelValue`).
+- **MUST** style with Joy tokens — no custom `.joy-input` or `.joy-input-unit` chrome.
+- **MUST NOT** invent props (`clearable`, `variant`, `errorMessage`, …).
+- **MUST NOT** pass `clearable` or `clearAriaLabel` — they are not supported.
+- **MUST NOT** use `VJoyInput` with a `unit` prop — use `VJoyInputNumber` (enforced by `no-vjoyinput-unit` ESLint rule).
+- **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.
+- **MUST NOT** rely on placeholder color alone to convey errors.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `label="Daily rate"` + `unit="€"` | `label="Daily rate (€)"` when the badge shows € |
+| `VJoyInputNumber` for priced amounts | `VJoyInput` + `unit` (removed) |
+| `min` / `max` / `step` via native attrs | Custom spin buttons or ad-hoc unit markup |
+| `VJoyFormError` with `invalid` | Red border with no message |
+| `unit=""` when no suffix is needed | Dummy unit just to use the component |
+| Joy form-field size tokens | Hardcoded `32` / `40` / `56`px heights |
+
+---
+
+## Content
+
+Inputs expose label, placeholder, optional helper copy, and a unit suffix. All must help users enter the **right numeric value** the **first** time.
+
+### Label formula
+
+**Noun or short noun phrase** describing the quantity — **without** repeating the unit shown in the badge:
+
+- ✅ Daily rate (with `unit="€"`)  
+- ✅ Discount (with `unit="%"`)  
+- ✅ Notice period (with `unit="days"`)  
+
+Use sentence case. The unit badge carries the suffix; the label names what is being measured.
+
+### Placeholder formula
+
+**Example or format hint** — not a repeat of the label or unit:
+
+- ✅ `1200` (under label “Daily rate” with `unit="€"`)  
+- ✅ `0` (under label “Discount” with `unit="%"`)  
+
+- ❌ `€` or `1200 €` as placeholder when the unit badge already shows €
+
+### Unit copy
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | Use standard symbols users recognize (`€`, `%`, `kg`) or short approved abbreviations (`days`, `h`) |
+| **MUST NOT** | Put long explanations in `unit` — use helper text or `VJoyLabel` legend |
+| **SHOULD** | Stay consistent with locale (currency symbol, `%` placement) across the product |
+| **SHOULD** | Omit the badge (`unit=""`) when the unit is obvious from context and would clutter the field |
+
+### 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 |
+
+### 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 an amount between 1 and 999` · ❌ `Invalid` |
+| **MUST NOT** | Duplicate the unit in the label when `unit` is set |
+| **MUST NOT** | Use labels that only make sense after failure — ❌ `Correct amount` |
+| **SHOULD** | Keep labels ≤ 3–5 words when possible |
+| **SHOULD** | Use placeholders for example values, not requirements |
+| **SHOULD** | Match terminology with adjacent fields and page headings |
+| **SHOULD** (FR) | Follow French grammar for labels and unit symbols when the UI is localized |
+
+### Patterns
+
+**Money** — Label names the amount type (`Price`, `Daily rate`); `unit` holds the currency. Formatting (decimals, thousands) is an app concern, not the badge.
+
+**Percentages** — Label describes what is measured (`Discount`, `Commission`); `unit="%"`. Consider `min="0"` `max="100"` via attrs when appropriate.
+
+**Durations / counts** — Short unit strings (`days`, `h`, `mo`) in `unit`; label states what is counted (`Notice period`, `Experience`).
+
+**Errors** — Show on blur or submit for most fields; pair `invalid` with a specific `VJoyFormError` message.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Native `<input>` with `type="number"` by default (overridable via `type`) |
+| Name | From associated `VJoyLabel` / `<label for>`; `label` prop wires `for` to `id \|\| name` |
+| Value | Controlled via `v-model`; emits string updates |
+| Unit | Visual suffix; not a substitute for the accessible name — label must still describe the field |
+| Keyboard | Standard editing; Tab moves focus; number spinners follow browser defaults |
+| Focus | Visible focus ring on the input — do not remove focus tokens |
+| Wheel | Wheel does not change value while focused (`type="number"`) |
+| Invalid | `invalid` styles the field; pair with `VJoyFormError` (`role="alert"`) for the message |
+| Disabled | Native `disabled`; provide text explanation nearby |
+| Readonly | Native `readonly`; value still readable and copyable |
+| Programmatic focus | Exposed `focus()` delegates to the inner input |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { VJoyInputNumber, VJoyFormError, VJoyWrapper } from '@maltjoy/core-vue'
+
+const price = ref('120')
+const discount = ref('')
+const showError = ref(false)
+</script>
+
+<template>
+  <!-- Price with default unit (€) -->
+  <VJoyInputNumber
+    v-model="price"
+    name="daily-rate"
+    label="Daily rate"
+    placeholder="1200"
+    min="0"
+    step="1"
+    required
+    required-mark
+  />
+
+  <!-- Custom unit -->
+  <VJoyInputNumber
+    v-model="discount"
+    name="discount"
+    label="Discount"
+    unit="%"
+    placeholder="0"
+    min="0"
+    max="100"
+    :invalid="showError"
+  />
+  <VJoyFormError v-if="showError" message="Enter a value between 0 and 100" />
+
+  <!-- No visible unit suffix -->
+  <VJoyInputNumber
+    v-model="price"
+    name="quantity"
+    label="Quantity"
+    unit=""
+    min="1"
+  />
+
+  <!-- Form layout -->
+  <VJoyWrapper direction="column" row-gap="4">
+    <VJoyInputNumber
+      v-model="price"
+      name="project-budget"
+      label="Project budget"
+      unit="€"
+      size="medium"
+    />
+  </VJoyWrapper>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyInputNumber` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyInput` | Free text or plain `type="number"` without unit badge (supports `clearable`) |
+| `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 |
+| `VJoyTextarea` | Multi-line text |
+| `VJoySelect` | Single choice from a list |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyInputNumber.dsds.json`](./JoyInputNumber.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Numeric value + unit suffix (€, %, days) | `VJoyInputNumber` | `VJoyInput` + `unit` |
+| Plain number, no unit badge | `VJoyInput` + `type="number"` | `VJoyInputNumber` with fake unit |
+| Number + clear button | `VJoyInput` + `type="number"` + `clearable` | `VJoyInputNumber` + `clearable` |
+| Free text | `VJoyInput` | `VJoyInputNumber` |
+| Password | `VJoyInputPassword` | `VJoyInput` + `type="password"` |
+| Pick one of N options | `VJoySelect` / radios | Number input for enums |
+
+### Hard rules
+
+1. **MUST** call `joy_get_component_info("VJoyInputNumber")` or read `VJoyInputNumber.vue` / `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** set `unit` to the correct suffix; use `unit=""` when no badge is wanted.  
+5. **MUST** pass native attrs (`placeholder`, `min`, `max`, `step`, `aria-*`) on the component — they flow to `<input>`.  
+6. **MUST** set `invalid` when showing validation errors and render `VJoyFormError` with a message.  
+7. **MUST NOT** emit `unit` on `VJoyInput` — use `VJoyInputNumber`.  
+8. **MUST NOT** emit `clearable` or `clearAriaLabel` on `VJoyInputNumber` — not supported.  
+9. **MUST NOT** use the default slot for new labels — use `label` or `VJoyLabel`.  
+10. **MUST NOT** override `.joy-input` / `.joy-input-unit` height, border, radius, or padding.  
+11. **SHOULD** default `type` to `number`; override only when a documented use case requires it.  
+12. **SHOULD** use `VJoyWrapper` in multi-field forms.
+
+### Checklist
+
+- [ ] Correct component (`VJoyInputNumber` vs `VJoyInput` / alternatives)
+- [ ] Props / enums from MCP or types only
+- [ ] `v-model` + `name` present
+- [ ] Visible label (not placeholder-only)
+- [ ] `unit` set appropriately; not duplicated in label
+- [ ] `invalid` + `VJoyFormError` when validation fails
+- [ ] No `clearable` / `clearAriaLabel`
+- [ ] No invented props / no custom input chrome CSS
+- [ ] Disabled / readonly explained if user-visible
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyInputNumber.dsds.json`](./JoyInputNumber.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy | `anatomy` |
+| Sizes / states | `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-*`, `--input-unit-height`) |

package/dist/doc/VJoyInputNumber/metadata.json

@@ -29,7 +29,7 @@
       "type": "string | undefined",
       "required": false,
       "default": "\"number\"",
-      "description": "",
+      "description": "HTML input type. Use VJoyInputPassword for password fields.",
       "possibleValues": null
     },
     {
@@ -85,7 +85,7 @@
       "name": "name",
       "type": "string | undefined",
       "required": false,
-      "default": "\"joy-input-password\"",
+      "default": "\"joy-input-number\"",
       "description": "",
       "possibleValues": [
         "string"
@@ -155,16 +155,6 @@
         "Partial<Record<\"number\" | \"trim\" | \"lazy\", boolean>>"
       ]
     },
-    {
-      "name": "unit",
-      "type": "string | undefined",
-      "required": false,
-      "default": "\"\\u20AC\"",
-      "description": "Adds a legend like symbol on the right of the component. Made for number based values",
-      "possibleValues": [
-        "string"
-      ]
-    },
     {
       "name": "readonly",
       "type": "boolean | undefined",
@@ -175,6 +165,16 @@
         "false",
         "true"
       ]
+    },
+    {
+      "name": "unit",
+      "type": "string | undefined",
+      "required": false,
+      "default": "\"\\u20AC\"",
+      "description": "Unit label displayed on the right side of the number input.",
+      "possibleValues": [
+        "string"
+      ]
     }
   ],
   "events": [
@@ -184,7 +184,12 @@
       "signature": "(event: \"update:modelValue\", value: string): void"
     }
   ],
-  "slots": [],
+  "slots": [
+    {
+      "name": "default",
+      "description": ""
+    }
+  ],
   "exposed": [
     {
       "name": "invalid",
@@ -232,13 +237,13 @@
       "isMethod": false
     },
     {
-      "name": "unit",
-      "type": "string",
+      "name": "readonly",
+      "type": "boolean",
       "isMethod": false
     },
     {
-      "name": "readonly",
-      "type": "boolean",
+      "name": "unit",
+      "type": "string",
       "isMethod": false
     },
     {