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

package/dist/doc/VJoyPanelSection/guideline.md

@@ -0,0 +1,160 @@
+---
+component: VJoyPanelSection
+status: draft
+language: en
+dsds: JoyPanelSection.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Panel section
+
+Use **`VJoyPanelSection`** when you need a titled subsection inside a panel body — for example grouping related fields, separating informational blocks, or breaking long panel content into scannable chunks.
+
+The component has no props: it exposes two named slots (`panel-section-title`, `panel-section-content`) with Joy typography on each block. Title and content wrappers render only when their slot is filled.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyPanelSection` from `@maltjoy/core-vue` |
+| **Storybook** | [VJoyPanel docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-layout-vjoypanel--docs) (`VJoyPanelSection` is a subcomponent) |
+| **DSDS (machine)** | [`JoyPanelSection.dsds.json`](./JoyPanelSection.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyPanelSection")` |
+
+---
+
+## When to use this component
+
+Use a panel section when content inside `VJoyPanel`’s `panel-body` needs a **local heading plus body copy** without promoting that block to a full panel header. Typical jobs: labeled groups of form fields, short explanatory text above a control cluster, or multiple logical blocks inside one card.
+
+Compose one or more `VJoyPanelSection` elements inside `panel-body`. Spacing between sections is handled by `VJoyPanel` styles — don’t add manual top margins on the section root.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Panel-level title, subtitle, or header actions | `VJoyPanel` slots (`panel-title`, `panel-subtitle`, `panel-title-action`) |
+| Standalone card with header, body, and footer | `VJoyPanel` |
+| Page-level layout (header, sidebar, main) | `VJoyTemplate` |
+| Flex row/column spacing between siblings | `VJoyWrapper` |
+| Form label + control + errors as one unit | `VJoyFormGroup` |
+| Custom heading + body markup with ad-hoc font sizes | Still use `VJoyPanelSection` + Joy typography tokens |
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Root (`div.joy-panel-section`) | Yes | Block container; always rendered |
+| Title block (`.joy-panel-section__title`) | No | Renders only when `panel-section-title` slot has content |
+| Content block (`.joy-panel-section__content`) | No | Renders only when `panel-section-content` slot has content |
+
+### Typography
+
+| Slot | Token / style |
+| --- | --- |
+| `panel-section-title` | `primary-650` (section heading weight) |
+| `panel-section-content` | `primary-400` (body text weight) |
+
+Margins on title and content are reset to `0` inside the component. Vertical rhythm between multiple sections inside a panel comes from `VJoyPanel` (`margin-top` / `padding-top` on `.joy-panel-section` siblings).
+
+### Default values
+
+- **No props** — composition is slot-only.
+- Either slot may be omitted; empty slots do not render their wrapper `div`.
+
+Slots: 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**).
+
+### Composition
+
+- **SHOULD** place `VJoyPanelSection` inside `VJoyPanel`’s `panel-body` — that is the intended parent context.
+- **SHOULD** provide both title and content slots when the section needs a visible heading.
+- **MAY** use only `panel-section-content` for untitled blocks (wrapper still applies body typography).
+- **MUST NOT** use `VJoyPanelSection` as a replacement for the panel header — panel title/subtitle belong on `VJoyPanel`.
+- **MUST NOT** add custom top margins on `.joy-panel-section` — parent panel spacing already accounts for section stacks.
+
+### Implementation
+
+- **MUST NOT** invent props (`title`, `variant`, `size`, …) — the API is slot-only.
+- **MUST NOT** override `.joy-panel-section__title` / `__content` font rules in product CSS; put semantic markup in slots (`h3`, `p`, `VJoyText`, …) and let Joy tokens apply.
+- **SHOULD** keep section titles short (one line when possible) so they scan inside dense panels.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| Nest sections in `panel-body` between form groups or lists | Duplicate `panel-title` in every subsection |
+| Plain text or heading elements in slots | Inline `font-size` / `font-weight` on slot content |
+| Multiple sections for distinct blocks in one panel | A separate `VJoyPanel` per small text block |
+
+---
+
+## Accessibility
+
+`VJoyPanelSection` is a **non-interactive layout container** (`div`). It has no focusable parts and does not define ARIA roles.
+
+| Behavior | Expectation |
+| --- | --- |
+| Semantics | Put heading semantics in `panel-section-title` (e.g. `h3`, `h4`) — the section root is not a heading |
+| Reading order | Title block precedes content block in the DOM when both slots are used |
+| Keyboard | No keyboard behavior on the section itself; interactive children keep their own focus order |
+| Landmarks | Do not rely on the section as a landmark; use appropriate heading levels inside slots |
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { VJoyPanel, VJoyPanelSection, VJoyCheckboxGroup } from '@maltjoy/core-vue'
+import { ref } from 'vue'
+
+const critical = ref<string[]>([])
+const other = ref<string[]>([])
+</script>
+
+<template>
+  <VJoyPanel>
+    <template #panel-title>
+      <h2>Migration status</h2>
+    </template>
+
+    <template #panel-body>
+      <VJoyPanelSection>
+        <template #panel-section-title>Critical components</template>
+        <template #panel-section-content>Only for SSR rendering.</template>
+      </VJoyPanelSection>
+
+      <VJoyCheckboxGroup v-model:value="critical" :options="[]" />
+
+      <VJoyPanelSection>
+        <template #panel-section-title>Other components</template>
+        <template #panel-section-content>Not critical.</template>
+      </VJoyPanelSection>
+
+      <VJoyCheckboxGroup v-model:value="other" :options="[]" />
+    </template>
+  </VJoyPanel>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyPanelSection` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyPanel` | Card container with header, body, footer, and loading — parent of panel sections |
+| `VJoyFormGroup` | Label + field + errors for a single form control |
+| `VJoyWrapper` | Flex layout and gaps between siblings inside a section |
+| `VJoyText` | Long copy inside `panel-section-content` when utility typography classes are needed |
+| `VJoyTemplate` | Full page shell, not in-panel subsections |

package/dist/doc/VJoyPasswordRequirement/guideline.md

@@ -0,0 +1,336 @@
+---
+component: VJoyPasswordRequirement
+status: draft
+language: en
+dsds: JoyPasswordRequirement.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Password requirement
+
+Use **`VJoyPasswordRequirement`** when you need to show the status of a single password-strength rule — for example “At least 8 characters” or “Contains an uppercase letter”.
+
+Each row pairs a short label with a status icon (`neutral`, `success`, or `error`). Compose several rows under **`VJoyInputPassword`** via the `password-requirements` slot so users see live feedback while choosing a password.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyPasswordRequirement` from `@maltjoy/core-vue` |
+| **Design** | [Figma — Joy Core Design System](https://www.figma.com/design/jfndp2QBJGS9yeuWbeGuvD/) |
+| **Storybook** | [VJoyPasswordRequirement docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-forms-vjoypasswordrequirement--docs) |
+| **DSDS (machine)** | [`JoyPasswordRequirement.dsds.json`](./JoyPasswordRequirement.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyPasswordRequirement")` |
+
+---
+
+## When to use this component
+
+Use a password requirement row when signup or password-reset flows must communicate **multiple independent rules** and whether each rule is met.
+
+Typical pattern: bind `VJoyInputPassword` with `v-model`, evaluate each rule in app logic, and render one `VJoyPasswordRequirement` per rule inside `#password-requirements`. The parent `VJoyWrapper` in `VJoyInputPassword` stacks rows with consistent spacing.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| The password field itself (show/hide toggle, label, validation border) | `VJoyInputPassword` |
+| A single global error after submit (“Password too weak”) | `VJoyFormError` below the field |
+| A strength meter / score bar | A dedicated meter component or custom UI — not this row pattern |
+| One-line helper text with no per-rule status | Plain `VJoyText` or `VJoyLabel` legend |
+| Custom-styled checklist under a password field | Still use `VJoyPasswordRequirement` + Joy tokens — don’t reinvent row chrome |
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Root container | Yes | `.joy-password-requirement` with status modifier class |
+| Status icon | Yes | `VJoyIcon` — `circle` (neutral), `check-circle` (success), or `warning` (error) |
+| Label | Yes | `.joy-password-requirement__label` — text from the `label` prop |
+| Form error hook | No | `data-joy-form-error` on the root when `status="error"` |
+
+The component is **presentational**: it does not validate passwords itself. Parent code computes `status` from the current value and focus state.
+
+### Default values
+
+- `status` defaults to **`neutral`**
+- `label` is **required**
+
+Props, events, and slots: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Status semantics
+
+Map `status` to user context, not only to “rule passed / failed”:
+
+| `status` | Meaning (typical) |
+| --- | --- |
+| `neutral` | User is editing the password; this rule is **not yet** satisfied |
+| `success` | This rule **is** satisfied for the current value |
+| `error` | Field is **not focused** and this rule is still **not** satisfied (show after blur or submit) |
+
+Avoid flipping a row to `error` while the field is still focused unless product rules explicitly require it.
+
+---
+
+## Variants
+
+`status` is the only visual variant. Pick it from **validation context**, not from decorative preference.
+
+### `neutral`
+
+Use while the user is typing and the rule has not been met yet.
+
+Icon: `circle` in neutral color. Label uses `--joy-color-neutral-40`.
+
+### `success`
+
+Use when the current password value satisfies this rule.
+
+Icon: `check-circle` in success color. Label uses `--joy-color-success-90`.
+
+### `error`
+
+Use when the rule is unmet and the password field is no longer focused (blur, tab away, or post-submit).
+
+Icon: `warning` (`xsmall`) in error color. Label uses `--joy-color-error-50`. Root receives `data-joy-form-error` for Joy form error integration.
+
+### Not in the API: `valid` / `invalid`
+
+Some samples use `status="valid"` or `status="invalid"`. The documented enum is **`success`**, **`error`**, and **`neutral`** only (`TVJoyPasswordRequirementStatus` in `JoyPasswordRequirement.types.ts`). Do not emit `valid` or `invalid`.
+
+---
+
+## States
+
+| State | What the user sees |
+| --- | --- |
+| `neutral` | Hollow circle icon; muted label — rule pending while editing |
+| `success` | Check icon; success-colored label — rule met |
+| `error` | Warning icon; error-colored label — rule failed after focus left the field |
+| Multiple rows | Independent status per rule; stack in `#password-requirements` |
+
+There is no hover, focus, disabled, or loading API on this component.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Composition
+
+- **MUST** render requirement rows inside `VJoyInputPassword`’s `#password-requirements` slot (or an equivalent stacked list directly under the password field).
+- **SHOULD** show **3–6** rules — enough guidance without overwhelming the form.
+- **SHOULD** evaluate rules in parent logic and pass the computed `status` per row.
+- **MUST NOT** use this component as the only validation feedback — still set `invalid` on `VJoyInputPassword` and show `VJoyFormError` when submission fails.
+
+### Implementation
+
+- **MUST** use only `neutral`, `success`, and `error` for `status` (MCP / `JoyPasswordRequirement.types.ts`).
+- **MUST** provide a non-empty `label` string per row.
+- **MUST** style with Joy tokens — no custom `.joy-password-requirement` chrome overrides.
+- **MUST NOT** invent props (`size`, `variant`, `icon`, …).
+- **MUST NOT** embed validation logic inside the component — keep rules in the parent.
+
+### Interaction timing
+
+- **SHOULD** use `neutral` while the password field is focused and a rule is unmet.
+- **SHOULD** promote unmet rules to `error` on blur or submit, not on every keystroke.
+- **SHOULD** set `success` as soon as a rule is satisfied, even while focused.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| One row per rule with a clear `label` | One row that concatenates every rule |
+| `#password-requirements` on `VJoyInputPassword` | Orphan rows with no password field |
+| `success` / `error` / `neutral` only | `valid` / `invalid` status values |
+| Parent-owned validation logic | Expect the component to validate passwords |
+| `VJoyFormError` for submit-level failures | Only red requirement rows with no summary error |
+
+---
+
+## Content
+
+Each row’s `label` is the only user-facing copy. Write rules so users can scan the list quickly.
+
+### Label formula
+
+**Short requirement statement** — what the password must include:
+
+- ✅ At least 8 characters  
+- ✅ Contains an uppercase letter  
+- ✅ Contains a number or symbol  
+
+Use sentence case. Start with “At least…”, “Contains…”, or “Must include…” for parallel structure across rows.
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | State the rule positively — ✅ `Contains an uppercase letter` · ❌ `No uppercase missing` |
+| **MUST** | Keep each label to one idea — split compound rules into separate rows |
+| **MUST** | Use the same grammatical pattern for every row in the list |
+| **MUST NOT** | Repeat the field label (“Password”) on every requirement row |
+| **MUST NOT** | Use jargon without context — ❌ `Meets entropy threshold` |
+| **SHOULD** | Put numeric thresholds in the label — ✅ `At least 12 characters` |
+| **SHOULD** | Order rules from basic to advanced (length before complexity) |
+| **SHOULD** (FR) | Follow French grammar for labels when the UI is localized |
+
+### Patterns
+
+**Signup** — Show all rules as `neutral` on first focus; flip to `success` per rule as the user types; on blur, any remaining failures become `error`.
+
+**Reset password** — Same list as signup for consistency; reuse labels across flows.
+
+**Submit** — If the form is submitted with failures, set unmet rows to `error` and add a `VJoyFormError` such as `Your password does not meet all requirements`.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Presentational `div` — not a form control |
+| Name | Rule text comes from the visible `label` span |
+| Icons | Decorative status indicators; meaning is duplicated in label text |
+| Error integration | `status="error"` sets `data-joy-form-error` on the row for Joy form patterns |
+| Live updates | When statuses change as the user types, ensure the password field’s accessible name and any `VJoyFormError` still describe overall failure — don’t rely on color alone |
+| Grouping | Multiple rows under one password field should read as a related checklist; keep DOM order matching visual order |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import {
+  VJoyInputPassword,
+  VJoyPasswordRequirement,
+  VJoyFormError,
+  type TVJoyPasswordRequirementStatus,
+} from '@maltjoy/core-vue'
+
+const password = ref('')
+const focused = ref(false)
+const submitted = ref(false)
+
+const rules = [
+  { id: 'length', label: 'At least 8 characters', test: (v: string) => v.length >= 8 },
+  { id: 'upper', label: 'Contains an uppercase letter', test: (v: string) => /[A-Z]/.test(v) },
+  { id: 'symbol', label: 'Contains a number or symbol', test: (v: string) => /[\d\W]/.test(v) },
+]
+
+function statusFor(test: (v: string) => boolean): TVJoyPasswordRequirementStatus {
+  if (test(password.value)) return 'success'
+  if (focused.value) return 'neutral'
+  if (submitted.value) return 'error'
+  return 'neutral'
+}
+
+const allValid = computed(() => rules.every((r) => r.test(password.value)))
+</script>
+
+<template>
+  <VJoyInputPassword
+    v-model="password"
+    name="new-password"
+    label="Password"
+    autocomplete="new-password"
+    :invalid="submitted && !allValid"
+    @focus="focused = true"
+    @blur="focused = false"
+  >
+    <template #password-requirements>
+      <VJoyPasswordRequirement
+        v-for="rule in rules"
+        :key="rule.id"
+        :label="rule.label"
+        :status="statusFor(rule.test)"
+      />
+    </template>
+  </VJoyInputPassword>
+
+  <VJoyFormError
+    v-if="submitted && !allValid"
+    message="Your password does not meet all requirements"
+  />
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyPasswordRequirement` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyInputPassword` | Password entry with show/hide toggle and `#password-requirements` slot |
+| `VJoyFormError` | Overall validation message on submit |
+| `VJoyWrapper` | Layout inside `VJoyInputPassword` stacks requirement rows automatically |
+| `VJoyInput` | Non-password single-line text — not for password + rules |
+| `VJoyIcon` | Status glyphs are internal; don’t recompose rows with raw icons |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyPasswordRequirement.dsds.json`](./JoyPasswordRequirement.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Per-rule password feedback under a field | `VJoyPasswordRequirement` in `#password-requirements` | Custom `<ul>` with manual icon colors |
+| Password input with toggle | `VJoyInputPassword` | `VJoyInput` + `type="password"` |
+| Single submit error for the field | `VJoyFormError` | Only requirement rows |
+| Rule passed / failed / pending | `status="success"` / `error` / `neutral` | `valid` / `invalid` |
+
+### Hard rules
+
+1. **MUST** call `joy_get_component_info("VJoyPasswordRequirement")` (or read `JoyPasswordRequirement.types.ts`) before generating props.
+2. **MUST** set `label` on every row.
+3. **MUST** use `status` values `neutral`, `success`, or `error` only.
+4. **MUST** place rows in `VJoyInputPassword`’s `#password-requirements` slot unless the layout explicitly mirrors that pattern.
+5. **MUST NOT** invent props (`size`, `variant`, `valid`, `invalid`, …).
+6. **MUST NOT** override `.joy-password-requirement` colors, gap, or font size in app CSS.
+7. **SHOULD** compute `status` in parent script — the component does not validate passwords.
+8. **SHOULD** pair requirement rows with `VJoyFormError` when the form is submitted invalid.
+
+### Checklist
+
+- [ ] `VJoyInputPassword` + `#password-requirements` slot
+- [ ] One `VJoyPasswordRequirement` per rule with `label`
+- [ ] `status` is `neutral`, `success`, or `error` only
+- [ ] No invented props / no custom requirement-row CSS
+- [ ] Parent logic owns rule tests and focus/submit timing
+- [ ] `VJoyFormError` (or equivalent) on submit when rules fail
+- [ ] Labels are short, parallel, and positively phrased
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyPasswordRequirement.dsds.json`](./JoyPasswordRequirement.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy | `anatomy` |
+| Status (`status`) | `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 / colors | `design-specifications` in JSON (`--joy-font-size-primary-300`, `--joy-color-neutral-40`, `--joy-color-success-90`, `--joy-color-error-50`) |

package/dist/doc/VJoyPasswordRequirement/metadata.json

@@ -1,7 +1,7 @@
 {
   "name": "JoyPasswordRequirement",
   "displayName": "VJoyPasswordRequirement",
-  "description": "A component to display a password requirement status.\nThis is meant to be displayed under a VJoyInput of type password.",
+  "description": "A component to display a password requirement status.\nThis is meant to be displayed under VJoyInputPassword.",
   "category": "Forms",
   "props": [
     {

package/dist/doc/VJoyProductTour/JoyProductTour.types.ts

@@ -1,5 +1,4 @@
 import {TJoyIconsNames} from '../JoyIcon/JoyIcon.types';
-import VJoyProductTourInner from './VJoyProductTourInner.vue';
 
 export const PRODUCT_TOUR_POSITIONS = ['left', 'right', 'top', 'bottom'] as const;
 export type TJoyProductTourPositions = (typeof PRODUCT_TOUR_POSITIONS)[number];