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

package/dist/doc/VJoyFormError/metadata.json

@@ -26,15 +26,6 @@
         "true"
       ]
     },
-    {
-      "name": "noHtmlErrorText",
-      "type": "string | undefined",
-      "required": false,
-      "description": "Error message to display. If you need a list of errors, use the slot instead",
-      "possibleValues": [
-        "string"
-      ]
-    },
     {
       "name": "errors",
       "type": "string[] | undefined",
@@ -69,11 +60,6 @@
       "type": "boolean",
       "isMethod": false
     },
-    {
-      "name": "noHtmlErrorText",
-      "type": "string | undefined",
-      "isMethod": false
-    },
     {
       "name": "errors",
       "type": "string[] | undefined",

package/dist/doc/VJoyFormFieldSkeleton/guideline.md

@@ -0,0 +1,159 @@
+---
+component: VJoyFormFieldSkeleton
+status: draft
+language: en
+dsds: JoyFormFieldSkeleton.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Form field skeleton
+
+Use **`VJoyFormFieldSkeleton`** when a form or form-like layout is loading and you need placeholder bars that match real field height and border radius.
+
+It is a non-interactive shimmer block (100% width by default). Pair multiple instances inside **`VJoyWrapper`** to build skeleton forms; use `flex` and `width` to mirror horizontal rows or fixed-width fields.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyFormFieldSkeleton` from `@maltjoy/core-vue` |
+| **Design** | [Figma — Joy Core Design System](https://www.figma.com/design/jfndp2QBJGS9yeuWbeGuvD/) |
+| **Storybook** | [VJoyFormFieldSkeleton docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-skeletons-vjoyformfieldskeleton--docs) |
+| **DSDS (machine)** | [`JoyFormFieldSkeleton.dsds.json`](./JoyFormFieldSkeleton.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyFormFieldSkeleton")` |
+
+---
+
+## When to use this component
+
+Use a form field skeleton while form content is fetching — for example a settings panel, onboarding step, or filter drawer where inputs will appear once data arrives.
+
+Stack several skeletons in a column to suggest labels and fields, or place them in a row with `flex` to mimic split inputs (e.g. first name / last name).
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Generic blocks, avatars, or arbitrary dimensions | `VJoyBlockSkeleton` (circle variant, custom height/width) |
+| Full-page or section-blocking load | `VJoyScreenLoader` or `VJoySpinner` |
+| Actual form input (even disabled) | `VJoyInput`, `VJoySelect`, etc. — skeletons are not form controls |
+| Custom shimmer divs / ad-hoc placeholder CSS | Still use `VJoyFormFieldSkeleton` + Joy tokens |
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Root `div` | Yes | `.joy-form-skeleton` block with shimmer animation |
+| Size modifier | Yes | `joy-form-skeleton--{size}` — sets height and border radius from form size tokens |
+| Shimmer | Yes | Neutral gradient animation (`shine` keyframes) — do not override in product CSS |
+
+There are no slots, events, or child parts. The root is marked `aria-hidden="true"` because it is decorative loading chrome.
+
+### Default values
+
+- `size` defaults to **`medium`** — also accepts `small`, `xsmall`, `xxsmall` (same scale as form fields)
+- `flex` defaults to **`"1"`** — flex-grow when siblings sit inside `VJoyWrapper`
+- `width` has **no default** — omit for full width; set a CSS length (e.g. `200px`) for fixed-width placeholders
+
+### Layout with `VJoyWrapper`
+
+The component injects `VJoyWrapperContext` to adjust flex basis:
+
+- **Row layout** (default) — equal-width siblings when `flex="1"` and no `width`
+- **Column layout** (`direction="column"`) — flex basis becomes `auto` so stacked skeletons keep natural field height
+- **Proportional rows** — set different `flex` values (`2`, `3`, `1`) on siblings for unequal column widths
+
+Props and exposed members: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Layout and fidelity
+
+- **SHOULD** wrap skeletons in **`VJoyWrapper`** — spacing and flex behavior are designed for it.
+- **SHOULD** match **`size`** to the form fields that will replace the skeletons.
+- **SHOULD** use **`width`** for fields that won’t span full width (e.g. a short submit-button placeholder).
+- **SHOULD** use **`flex`** on siblings to mirror real horizontal field proportions.
+- **MUST NOT** present skeletons as interactive controls or bind them to `v-model`.
+
+### Implementation
+
+- **MUST** use only documented props (`size`, `width`, `flex`) from MCP or the component source.
+- **MUST** use Joy tokens — no custom `.joy-form-skeleton` color or animation overrides.
+- **MUST NOT** invent props (`variant`, `height`, `loading`, …).
+- **MUST NOT** remove `aria-hidden` or add roles that imply a real input.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `VJoyWrapper` + stacked skeletons for a form | Lone skeletons with hand-rolled margins |
+| `size="medium"` when fields will be medium | Random pixel heights in product CSS |
+| `flex="2"` / `flex="3"` for split rows | Custom flex divs with neutral backgrounds |
+| Swap skeletons for real fields when data loads | Disabled `VJoyInput` as a loading placeholder |
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Decorative only — root has `aria-hidden="true"` |
+| Announcement | Screen readers should **not** treat skeletons as form fields; ensure real labels/inputs appear when loading completes |
+| Motion | Continuous shimmer animation — respect `prefers-reduced-motion` at the app level if product policy requires it |
+| Focus | No focusable elements — don’t add `tabindex` or click handlers |
+
+When loading finishes, replace skeletons with labelled form controls so users get proper names and validation feedback.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { VJoyFormFieldSkeleton, VJoyWrapper } from '@maltjoy/core-vue'
+</script>
+
+<template>
+  <!-- Stacked form fields -->
+  <VJoyWrapper direction="column" align="flex-end">
+    <VJoyFormFieldSkeleton />
+    <VJoyFormFieldSkeleton />
+    <VJoyFormFieldSkeleton />
+    <VJoyFormFieldSkeleton width="200px" />
+  </VJoyWrapper>
+
+  <!-- Horizontal row with proportional widths -->
+  <VJoyWrapper>
+    <VJoyFormFieldSkeleton flex="2" />
+    <VJoyFormFieldSkeleton flex="3" />
+    <VJoyFormFieldSkeleton flex="1" />
+  </VJoyWrapper>
+
+  <!-- Compact density -->
+  <VJoyWrapper>
+    <VJoyFormFieldSkeleton size="xsmall" width="200px" />
+  </VJoyWrapper>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyFormFieldSkeleton` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyWrapper` | Spacing and flex layout for skeleton rows and columns |
+| `VJoyBlockSkeleton` | Non-form placeholders (text blocks, avatars, custom dimensions) |
+| `VJoyInput` / `VJoySelect` / `VJoyTextarea` | Real form fields once data is ready |
+| `VJoyFormGroup` | Label + field + error grouping after loading |
+| `VJoySpinner` / `VJoyScreenLoader` | Inline or full-viewport loading indicators |

package/dist/doc/VJoyFormGroup/guideline.md

@@ -0,0 +1,285 @@
+---
+component: VJoyFormGroup
+status: draft
+language: en
+dsds: JoyFormGroup.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Form group
+
+Use **`VJoyFormGroup`** when a single form field needs a vertical stack — label, control, and validation message — with consistent inner spacing and predictable gaps between fields.
+
+It is a layout primitive: one default slot, no props. It applies Joy spacing tokens, resets bottom margins on common Joy form children, and adds outer spacing when several groups are stacked.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyFormGroup` from `@maltjoy/core-vue` |
+| **Design** | [Figma — Joy Core Design System](https://www.figma.com/design/jfndp2QBJGS9yeuWbeGuvD/) |
+| **Storybook** | [VJoyFormGroup docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-functional-vjoyformgroup--docs) |
+| **DSDS (machine)** | [`JoyFormGroup.dsds.json`](./JoyFormGroup.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyFormGroup")` |
+
+---
+
+## When to use this component
+
+Use a form group when one logical field is composed of several Joy pieces that should read as a unit — for example `VJoyLabel` + `VJoyInput` + `VJoyFormError`, or `VJoyLabel` + `VJoyCheckbox` + `VJoyFormError`.
+
+Stack multiple `VJoyFormGroup` instances to build a form: each group is one field row; adjacent groups get automatic vertical separation via `--form-group-outer-gap`.
+
+The component also normalizes spacing by clearing default bottom margins on supported Joy form children inside the group, so you don’t fight double margins between label, control, and error.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| General flex layout (rows, button groups, arbitrary gap/direction) | `VJoyWrapper` |
+| A set of mutually exclusive radio options | `VJoyRadioGroup` (fieldset + legend + layout) — **do not** wrap bare `VJoyRadio` in `VJoyFormGroup` |
+| Multi-checkbox array with group legend | `VJoyCheckboxGroup` |
+| Horizontal toolbars or filter rows | `VJoyWrapper` or `VJoyFilterBar` |
+| Semantic grouping of related radios/checkboxes (fieldset) | `VJoyRadioGroup` / `VJoyCheckboxGroup` — not `VJoyFormGroup` alone |
+| Custom `<div>` + manual margin CSS for the same job | Still use `VJoyFormGroup` + Joy tokens |
+
+> **ESLint:** `@maltjoy/eslint-rules/no-vjoyformgroup-vjoyradio` flags `VJoyRadio` nested directly in `VJoyFormGroup`. Wrap radios in `VJoyRadioGroup` first; a `VJoyRadioGroup` inside `VJoyFormGroup` is valid.
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Root container | Yes | `<div class="joy-form-group">`; receives `$attrs` (`id`, `data-testid`, `aria-*`, …) |
+| Default slot | Yes | Label, form control(s), and optional `VJoyFormError` (or related helpers) |
+| Inner gap | Yes | Column flex with `gap: var(--form-group-inner-gap)` (`--joy-core-spacing-2`) |
+| Outer gap | Yes* | `margin-top` on a following `.joy-form-group` (`--form-group-outer-gap` → `--joy-core-spacing-8`) |
+
+\*Applied only between consecutive form groups, not before the first.
+
+### Default values
+
+`VJoyFormGroup` exposes **no props** and **no events**.
+
+- Inner gap token: **`--joy-core-spacing-2`** (via `--form-group-inner-gap`)
+- Outer gap between stacked groups: **`--joy-core-spacing-8`** (via `--form-group-outer-gap`)
+- Margin reset (`margin-bottom: 0`) applies to: `.joy-label__group--standalone`, `.joy-checkbox`, `.joy-form-error`, `.joy-input--wrapper`, `.joy-radio-group-container`
+
+Slots and attrs: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Composition patterns
+
+**External label** — `VJoyLabel` above the control; common for checkboxes and selects:
+
+```vue
+<VJoyFormGroup>
+  <VJoyLabel text="Terms and conditions" />
+  <VJoyCheckbox v-model:checked="agreed" label="I accept the terms and conditions" />
+  <VJoyFormError v-if="showError" :errors="['You must accept the terms and conditions']" />
+</VJoyFormGroup>
+```
+
+**Built-in label** — control carries its own `label` prop (e.g. `VJoyInput`):
+
+```vue
+<VJoyFormGroup>
+  <VJoyInput v-model="email" label="Email" name="email" :invalid="showError" />
+  <VJoyFormError v-if="showError" :errors="['You must enter an email']" />
+</VJoyFormGroup>
+```
+
+**Radio options** — use `VJoyRadioGroup` inside the group for the option set; add `VJoyFormError` when validation fails at group level.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Structure
+
+- **SHOULD** use one `VJoyFormGroup` per logical field (one label + one primary control + its errors).
+- **SHOULD** order slot content top-to-bottom: label → control → error/helper.
+- **SHOULD** stack fields by placing sibling `VJoyFormGroup` elements — don’t insert arbitrary wrappers that break outer-gap spacing.
+- **MUST NOT** wrap a bare `VJoyRadio` in `VJoyFormGroup` — use `VJoyRadioGroup` (ESLint enforced).
+
+### Implementation
+
+- **MUST** compose with Joy form components (`VJoyLabel`, `VJoyInput`, `VJoyFormError`, …) — don’t rely on raw `<input>` margins.
+- **MUST** pass layout/test hooks via attrs on `VJoyFormGroup` (`id`, `data-testid`) when needed — there are no dedicated props.
+- **MUST NOT** invent props on `VJoyFormGroup` — the API is slot-only.
+- **MUST NOT** override `.joy-form-group` gap or adjacent `margin-top` with hardcoded pixel spacing in product CSS.
+- **MUST NOT** re-add large `margin-bottom` on children inside the group — the component clears them on purpose.
+- **SHOULD** pair `invalid` on the control with `VJoyFormError` text — color alone is not enough.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| One group per field | One group wrapping an entire multi-field form without inner groups |
+| `VJoyRadioGroup` for radio sets | Lone `VJoyRadio` inside `VJoyFormGroup` |
+| Sibling `VJoyFormGroup` for vertical forms | Manual `margin-bottom: 24px` on every input |
+| `VJoyWrapper` for non-form flex layouts | `VJoyFormGroup` for button rows or generic grids |
+| Attrs on the root for `id` / `data-testid` | Fake props like `gap` or `spacing` |
+
+---
+
+## Accessibility
+
+`VJoyFormGroup` is a **presentational** wrapper. It does not replace fieldset/legend semantics — use `VJoyRadioGroup` or `VJoyCheckboxGroup` when a group of options shares one legend.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Generic `<div>` — not a fieldset, not a label |
+| Naming | Accessible names come from child controls and `VJoyLabel` / built-in labels |
+| Grouping | For related options, use components that render `<fieldset>` + `<legend>` |
+| Errors | `VJoyFormError` provides alert semantics; keep it inside the same form group as the invalid control |
+| Attributes | `$attrs` merge onto the root — use `aria-labelledby` / `aria-describedby` only when wiring to real child `id`s |
+| Focus | Focus moves to focusable children inside the slot; the wrapper itself is not focusable |
+
+Target: **WCAG 2.2 AA** where the product requires it — meet requirements through child labels, errors, and proper option-group components.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import {
+  VJoyFormGroup,
+  VJoyLabel,
+  VJoyInput,
+  VJoyCheckbox,
+  VJoySelect,
+  VJoyFormError,
+} from '@maltjoy/core-vue'
+
+const name = ref('')
+const email = ref('')
+const agreed = ref(false)
+const plan = ref('')
+const showErrors = ref(false)
+</script>
+
+<template>
+  <!-- Label + input + error -->
+  <VJoyFormGroup>
+    <VJoyLabel text="Full name" />
+    <VJoyInput
+      v-model="name"
+      name="signup-name"
+      placeholder="Enter your name"
+      :invalid="showErrors && !name"
+    />
+    <VJoyFormError v-if="showErrors && !name" :errors="['You must enter a name']" />
+  </VJoyFormGroup>
+
+  <!-- Built-in label on the control -->
+  <VJoyFormGroup>
+    <VJoyInput
+      v-model="email"
+      label="Email"
+      name="signup-email"
+      placeholder="name@company.com"
+      :invalid="showErrors && !email"
+    />
+    <VJoyFormError v-if="showErrors && !email" :errors="['You must enter an email']" />
+  </VJoyFormGroup>
+
+  <!-- Checkbox consent -->
+  <VJoyFormGroup>
+    <VJoyLabel text="Terms and conditions" />
+    <VJoyCheckbox
+      v-model:checked="agreed"
+      label="I accept the terms and conditions"
+      :invalid="showErrors && !agreed"
+    />
+    <VJoyFormError
+      v-if="showErrors && !agreed"
+      :errors="['You must accept the terms and conditions']"
+    />
+  </VJoyFormGroup>
+
+  <!-- Select without separate error in this example -->
+  <VJoyFormGroup>
+    <VJoyLabel text="Plan" />
+    <VJoySelect v-model="plan" name="signup-plan" :invalid="showErrors && !plan">
+      <option value="starter">Starter</option>
+      <option value="pro">Pro</option>
+    </VJoySelect>
+  </VJoyFormGroup>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyFormGroup` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyLabel` | Field title, required mark, legend text above a control |
+| `VJoyFormError` | Validation message below the control (`role="alert"`) |
+| `VJoyInput` / `VJoySelect` / `VJoyCheckbox` / … | The actual form control inside the group |
+| `VJoyRadioGroup` | Exclusive radio options with fieldset semantics |
+| `VJoyCheckboxGroup` | Multi-select checkboxes with group legend |
+| `VJoyWrapper` | Non-field flex layouts, rows, or custom gap/direction |
+| `VJoyInputPassword` | Password field with requirements slot (often stacked in a form group) |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyFormGroup.dsds.json`](./JoyFormGroup.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Label + one control + error stack | `VJoyFormGroup` wrapping children | A raw `<div class="field">` with manual margins |
+| Vertical list of separate fields | Sibling `VJoyFormGroup` per field | One `VJoyFormGroup` around the whole form without per-field groups |
+| Radio button set | `VJoyRadioGroup` (optionally inside `VJoyFormGroup`) | `VJoyFormGroup` > `VJoyRadio` without `VJoyRadioGroup` |
+| Checkbox multi-select group | `VJoyCheckboxGroup` | `VJoyFormGroup` as fieldset substitute |
+| Horizontal button/filter layout | `VJoyWrapper` | `VJoyFormGroup` |
+| Arbitrary flex gap/direction | `VJoyWrapper` | Invented `gap` prop on `VJoyFormGroup` |
+
+### Hard rules
+
+1. **MUST** call `joy_get_component_info("VJoyFormGroup")` before generating markup — there are **no props**.  
+2. **MUST** use the default slot only; pass `id`, `data-testid`, and `aria-*` via attributes on the component.  
+3. **MUST NOT** nest `VJoyRadio` directly in `VJoyFormGroup` — wrap with `VJoyRadioGroup`.  
+4. **MUST NOT** invent props (`gap`, `spacing`, `direction`, …).  
+5. **MUST NOT** override `.joy-form-group` gap or stacked `margin-top` with custom CSS.  
+6. **SHOULD** place `VJoyFormError` immediately after the invalid control in the same group.  
+7. **SHOULD** use one `VJoyFormGroup` per logical field when building forms.
+
+### Checklist
+
+- [ ] Correct component (`VJoyFormGroup` or named alternative)
+- [ ] No invented props — slot + attrs only
+- [ ] One group per field; siblings for multi-field forms
+- [ ] Radios inside `VJoyRadioGroup`, not bare `VJoyRadio`
+- [ ] `invalid` on control + `VJoyFormError` when validation fails
+- [ ] No custom `.joy-form-group` spacing CSS
+- [ ] Fieldset semantics delegated to `VJoyRadioGroup` / `VJoyCheckboxGroup` when needed
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyFormGroup.dsds.json`](./JoyFormGroup.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy | `anatomy` |
+| Best practices | `guidelines` |
+| Accessibility | `accessibility` |
+| Examples | `sections` |
+| For agents | `agentDocumentBlocks` |
+| Slots / attrs | `api` in JSON + Joy MCP |
+| Imports | `imports` in JSON |
+| Token spacing | `design-specifications` (`--form-group-inner-gap`, `--form-group-outer-gap`) |