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

package/dist/doc/VJoyTitleBrand/guideline.md

@@ -0,0 +1,155 @@
+---
+component: VJoyTitleBrand
+status: draft
+language: en
+dsds: JoyTitleBrand.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Title brand
+
+Use **`VJoyTitleBrand`** when a page, dialog, or marketing block needs a striking title with one or more **brand-highlighted** word segments — a rotated primary background behind selected text.
+
+The root element is configurable (`tag`, default `p`). Wrap highlighted words in a **`<span>`** in the default slot; the component applies highlight styling automatically. Typical placements include `VJoyTemplate` headers and `VJoyDialog` titles.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyTitleBrand` from `@maltjoy/core-vue` |
+| **Design** | [Figma — Joy Core Design System](https://www.figma.com/design/jfndp2QBJGS9yeuWbeGuvD/) |
+| **Storybook** | [VJoyTitleBrand docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-view-vjoytitlebrand--docs) |
+| **DSDS (machine)** | [`JoyTitleBrand.dsds.json`](./JoyTitleBrand.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyTitleBrand")` |
+
+---
+
+## When to use this component
+
+Use a title brand when the heading should feel **on-brand and energetic** — onboarding heroes, funnel steps, dialog headers, or landing sections where one or two words deserve extra emphasis.
+
+The highlight is purely presentational: surrounding copy stays in the default title color; `<span>` children get inverted text on a tilted primary swatch. Multiple `<span>` segments are supported in one title.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Standard body or UI typography | `VJoyText` |
+| A plain semantic heading without brand highlight | Native `h1`–`h6` with Joy font utility classes |
+| Panel or card title chrome (actions, subtitle row) | `VJoyPanel` header slots |
+| Inline emphasis inside a paragraph | `VJoyText` or semantic `<strong>` — not a full title component |
+| Custom highlight markup / ad-hoc CSS for the same job | Still use `VJoyTitleBrand` + `<span>` — don’t reinvent the highlight |
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Root element | Yes | Dynamic tag (`tag` prop) with `.joy-title-brand` and `.joy-font-secondary-200` |
+| Default slot | Yes | Title text; mix plain text and `<span>` for highlights |
+| Highlight (`span`) | No | One or more segments with rotated `--joy-color-primary-50` background and `--joy-color-neutral-0` text |
+
+### Default values
+
+- `tag` defaults to **`p`**
+- Typography: **`joy-font-secondary-200`** on the root (secondary font family, weight 200)
+- Title color: **`--joy-color-text-title`**
+- Highlight padding/gap: **`--joy-core-spacing-1`** / **`--joy-core-spacing-2`**; highlight radius **`--joy-core-radius-5`**
+
+Props and slots: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Highlight behavior
+
+Only **direct `<span>` children** in the default slot receive the brand highlight (`:deep(span)`). Plain text nodes render without a background. Each span gets a slight **−1°** rotation on its background pseudo-element.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Semantics and hierarchy
+
+- **MUST** set `tag` to the correct heading level (`h1`–`h6`) when the title is a real page or section heading — don’t leave the default `p` for primary document titles.
+- **SHOULD** respect heading order (one `h1` per view; don’t skip levels).
+- **SHOULD** keep highlighted segments **short** (roughly one to three words) so the tilted swatch stays readable on narrow viewports.
+
+### Content and layout
+
+- **MUST** use **`<span>`** for highlighted words — no extra wrappers, classes, or inline styles on highlights.
+- **SHOULD** limit highlights to **one or two** segments per title; more reads as noisy (see Storybook “Corner case”).
+- **SHOULD** place the component in template or dialog **header** slots where brand tone is intentional — not for dense data tables or settings labels.
+
+### Implementation
+
+- **MUST** use only documented props from MCP (`tag` is the sole prop).
+- **MUST** use Joy tokens — **MUST NOT** override `.joy-title-brand` colors, padding, or pseudo-element rotation in product CSS.
+- **MUST NOT** invent props (`variant`, `size`, `highlight`, …).
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `tag="h1"` / `h2` for real headings | Default `p` for the main page title |
+| `<span>brand</span>` for emphasis | Custom `<mark>` or colored `<strong>` for the same effect |
+| Short highlighted phrases | Entire title wrapped in one `<span>` |
+| `VJoyTitleBrand` in template/dialog headers | Brand title styling on every `h2` in the app |
+
+---
+
+## Accessibility
+
+`VJoyTitleBrand` is **presentational and non-interactive**. Accessible structure depends on the chosen `tag` and slot content.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Comes from `tag` — `h1`–`h6` for headings, `p` for non-heading brand copy |
+| Name | Full title text (plain + span content) forms the accessible name |
+| Heading outline | Use semantic heading tags when the title denotes page/section hierarchy |
+| Highlight | Decorative background only; meaning must not rely on color or rotation alone |
+| Focus | Not focusable — no keyboard interaction |
+| Contrast | Highlight uses `--joy-color-neutral-0` on `--joy-color-primary-50`; ensure surrounding title color meets product contrast requirements |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { VJoyTitleBrand } from '@maltjoy/core-vue'
+</script>
+
+<template>
+  <!-- Page hero — semantic heading + one highlight -->
+  <VJoyTitleBrand tag="h1">
+    Welcome to Malt <span>freelancers</span>
+  </VJoyTitleBrand>
+
+  <!-- Dialog or template header -->
+  <VJoyTitleBrand tag="h2">
+  Title of the page <span>with brand</span>
+  </VJoyTitleBrand>
+
+  <!-- Multiple highlights (use sparingly) -->
+  <VJoyTitleBrand tag="h2">
+    Title of the page <span>with brand</span> but not <span>only</span>
+  </VJoyTitleBrand>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyTitleBrand` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyTemplate` | Full-page layout with header area for branded titles |
+| `VJoyDialog` | Modal headers that can host a brand title |
+| `VJoyText` | Standard typography without brand highlight |
+| `VJoyPanel` | Card/section titles with actions and structured header |
+| `VJoyFunnel` | Multi-step flows where a brand moment may appear in the header |

package/dist/doc/VJoyToggle/guideline.md

@@ -0,0 +1,327 @@
+---
+component: VJoyToggle
+status: draft
+language: en
+dsds: JoyToggle.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Toggle
+
+Use **`VJoyToggle`** when the user needs to switch a single setting **on or off** with immediate effect — especially in settings rows, preferences, or compact forms.
+
+It supports checked and disabled states, a label via prop or slot (left or right of the switch), native form attributes (`name`, `value`, `required`), and two visual variants: **`default`** (customer product) and **`admin`** (internal tooling).
+
+| | |
+| --- | --- |
+| **Code** | `VJoyToggle` from `@maltjoy/core-vue` |
+| **Design** | [Joy — Toggle](https://zeroheight.com/6bf479565/p/67497f) (page id `1423634`) |
+| **Storybook** | [VJoyToggle docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-forms-vjoytoggle--docs) |
+| **DSDS (machine)** | [`JoyToggle.dsds.json`](./JoyToggle.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyToggle")` |
+
+---
+
+## When to use this component
+
+Use a toggle when there are **exactly two mutually exclusive states** (on / off) that the user may change often and see take effect right away — for example enabling notifications, showing optional UI, or turning a feature on.
+
+Toggles work well when space is tight and the two states are clearly related. Place the label beside the switch so the user knows what flips when they interact with the control.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| More than two options | `VJoyRadio` / `VJoyRadioGroup` or `VJoySelect` |
+| Multiple independent selections | `VJoyCheckbox` / `VJoyCheckboxGroup` |
+| Consent, agreement, or “I accept…” copy | `VJoyCheckbox` |
+| Options that are not mutually exclusive | `VJoyCheckbox` |
+| A change that only applies after Save / Submit | Checkbox or explicit submit — not an instant toggle |
+| Customer-facing product UI with admin chrome | `variant="default"` — never `admin` |
+| Custom-styled switch markup | Still use `VJoyToggle` + Joy tokens — don’t reinvent chrome |
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Wrapper | Yes | Root container (`.joy-toggle__wrapper`) |
+| Label | Yes | Clickable `<label>` wrapping the input and content row |
+| Input | Yes | Visually hidden `<input type="checkbox">` with `data-joy-form-field` and `role="checkbox"` |
+| Switch track | Yes | `.joy-toggle__symbol` — rounded track behind the bubble |
+| Bubble | Yes | `.joy-toggle__symbol-bubble` — slides horizontally when checked |
+| Variant icon | No | Smile SVG (`default`) or `VJoyIcon` `eye` (`admin`) inside the bubble |
+| Label text | Yes* | Default slot or `label` prop in `.joy-toggle__content-label` (*one must provide an accessible name) |
+| Focus ring | Yes | Outline on the track when the input is focused (`joy-toggle__focusing`) |
+
+The component `provide`s `JoyFormElementContext` so it integrates with Joy form field patterns (e.g. labels, validation groups).
+
+### Default values
+
+- `modelValue` defaults to **`false`**
+- `variant` defaults to **`default`**
+- `labelPosition` defaults to **`right`**
+- `disabled` defaults to **`false`**
+- `invalid` defaults to **`false`** (declared on props; no dedicated invalid styling in component CSS yet — pair with `VJoyFormError` or group messaging)
+- `required` defaults to **`false`**
+- `value` defaults to **`"on"`** (submitted value when checked in native forms)
+
+Props, events, and slots: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Visual treatment
+
+There is **no `size` prop**. Track and bubble dimensions come from component CSS variables (e.g. `--toggle-width`, `--toggle-height`) and Joy color tokens — **don’t hardcode switch width, height, or track colors** in product CSS.
+
+---
+
+## Variants
+
+Pick variant by **surface audience**, not by color preference.
+
+### `default`
+
+Use on **customer-facing** product UI. The bubble shows the Joy smile motif when checked.
+
+Avoid `admin` styling on public or client surfaces.
+
+### `admin`
+
+Use **only** in internal / admin tooling. Checked state uses quaternary tokens; the bubble shows an **eye** icon instead of the smile.
+
+Avoid `variant="admin"` outside admin contexts — it is documented separately in Storybook under Admin.
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Off (`modelValue: false`) | Bubble on the left; neutral track; label in normal weight |
+| On (`modelValue: true`) | Bubble slides right; track uses secondary (or quaternary for `admin`); smile or eye visible in bubble |
+| Hover | Track and bubble border lighten (pointer devices); checked hover uses `--toggle-bg-color-hover-checked` |
+| Focus | Visible focus outline on the track — don’t remove in product CSS |
+| Disabled | No interaction; muted track, bubble, label, and icon — **explain why** nearby when possible |
+| Disabled + on | Same as disabled with bubble in the “on” position |
+
+Bind state with `v-model` (or `:model-value` + `@update:modelValue`). Changes emit immediately on `change` — there is no separate “Apply” step inside the component.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Selection model
+
+- **SHOULD** use a toggle only for **two** mutually exclusive, immediately applied states.
+- **MUST NOT** use a toggle when the user can select multiple options — use checkboxes.
+- **MUST NOT** use a toggle when more than two choices exist — use radio or select.
+- **SHOULD** prefer `VJoyCheckbox` when the label is a consent statement (“I agree to…”) rather than a setting name.
+
+### Implementation
+
+- **MUST** bind state with `v-model` (or `:model-value` + `@update:modelValue`).
+- **MUST** use only documented props from MCP or `VJoyToggle.vue` props.
+- **MUST** use Joy tokens — no custom `.joy-toggle` track, bubble, or focus CSS.
+- **MUST NOT** invent props (`size`, `color`, `checked` as v-model name, …).
+- **MUST** use `variant="default"` on customer surfaces; reserve `admin` for internal tools.
+- **SHOULD** set `name` and `value` when multiple toggles participate in the same native form submit.
+- **SHOULD** surface validation errors with `VJoyFormError` or `VJoyFormGroup` — don’t rely on `invalid` alone until invalid styling is wired.
+
+### Interaction
+
+- **MUST** keep the label clickable (component wraps input in `<label>` — don’t break that association).
+- **SHOULD** use `labelPosition="left"` when the switch must align with a column of controls on the right (e.g. settings tables).
+- **SHOULD** disable rather than hide a setting the user cannot change, when the setting must remain visible.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `v-model` for on/off state | Separate Save button for a single instant setting (unless product requires it) |
+| Short setting names as labels | Full sentences that read like checkboxes (“I agree…”) |
+| `default` on product UI | `admin` variant on customer flows |
+| `VJoyCheckbox` for consent | Toggle for legal acceptance |
+| Radio / select for 3+ options | Toggle as a multi-option picker |
+
+---
+
+## Content
+
+Toggle labels name **what is enabled when the switch is on**. They are scannable, parallel in lists, and use the **infinitive** mood in English (per Joy conjugation guidelines).
+
+### Label formula
+
+**Infinitive verb + optional object** (English):
+
+- ✅ Enable notifications  
+- ✅ Show completed projects  
+- ✅ Use dark mode  
+
+The label describes the **on** state. Off is implied.
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | Every toggle has a visible label (prop or default slot) — no unlabeled switches |
+| **MUST** | Label states what is on when checked — ✅ `Enable email alerts` · ❌ `Email alerts are enabled` |
+| **MUST** | Use infinitive mood (EN) — ✅ `Show profile` · ❌ `Showing profile` |
+| **MUST NOT** | Use Yes / No as the only label — name the setting |
+| **MUST NOT** | Use checkbox-style agreement copy — ✅ move to `VJoyCheckbox` |
+| **SHOULD** | ≤ 40 characters; wrap rather than truncate |
+| **SHOULD** | Sentence case; parallel grammar in stacked settings |
+| **SHOULD** | Avoid “Turn on/off” padding when the infinitive alone is clear — ✅ `Enable notifications` |
+| **SHOULD** (FR) | Follow product locale rules; infinitive is still preferred for toggle labels |
+
+### Patterns
+
+**Settings row** — One toggle per row; label on the right by default. Group related toggles under a `VJoyLabel` or section heading.
+
+**Dialog / panel** — Use when the choice is binary and applies immediately (e.g. “Show archived items”). Prefer explicit labels over “On / Off” alone.
+
+**Forms** — If the form is submitted as a whole, still bind `v-model`; set `name` / `value` so unchecked toggles behave as expected in native submit (checkbox semantics).
+
+**Validation** — When a toggle must be on to proceed, show error copy next to the control (`VJoyFormError`) rather than only relying on border color.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Native checkbox (`<input type="checkbox">`) with `role="checkbox"` |
+| Name | From default slot or `label` prop; associated via wrapping `<label>` |
+| State | `aria-checked` reflects `modelValue` |
+| Keyboard | **Space** toggles when focused; **Tab** moves focus |
+| Focus | Visible focus ring on the track (`joy-toggle__focusing`); don’t remove in product CSS |
+| Disabled | `disabled` on input; explain restriction in visible text when it matters |
+| Motion | Bubble animates with `--joy-transition-duration-default`; respect `prefers-reduced-motion` at app level if you add wrappers |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { VJoyToggle } from '@maltjoy/core-vue'
+
+const notifications = ref(true)
+const showArchived = ref(false)
+</script>
+
+<template>
+  <!-- Basic setting (label right) -->
+  <VJoyToggle v-model="notifications" label="Enable notifications" />
+
+  <!-- Label on the left (settings table alignment) -->
+  <VJoyToggle
+    v-model="showArchived"
+    label="Show archived projects"
+    label-position="left"
+  />
+
+  <!-- Custom label slot -->
+  <VJoyToggle v-model="showArchived">
+    Show <strong>archived</strong> projects
+  </VJoyToggle>
+
+  <!-- Disabled -->
+  <VJoyToggle disabled :model-value="true" label="Managed by your organization" />
+
+  <!-- Native form field -->
+  <VJoyToggle
+    v-model="notifications"
+    name="email_alerts"
+    value="enabled"
+    label="Enable email alerts"
+  />
+
+  <!-- Admin tooling only -->
+  <VJoyToggle variant="admin" v-model="showArchived" label="Admin view" />
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyToggle` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyCheckbox` | Consent, multi-select, or non-immediate binary confirmation |
+| `VJoyCheckboxGroup` | Several independent checkboxes with shared legend |
+| `VJoyRadio` / `VJoyRadioGroup` | Exactly one of three or more visible options |
+| `VJoySelect` | Many options or searchable lists |
+| `VJoyLabel` / `VJoyFormGroup` | Section headings, required marks, and form-level validation messaging |
+| `VJoyFormError` | Explicit error text when validation fails |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyToggle.dsds.json`](./JoyToggle.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Single on/off setting, immediate | `VJoyToggle` | `VJoyCheckbox` for a settings row |
+| “I agree to terms” | `VJoyCheckbox` | `VJoyToggle` |
+| Pick one of 3+ options | `VJoyRadio` / `VJoySelect` | `VJoyToggle` |
+| Multi-select filters | `VJoyCheckbox` / `VJoyCheckboxGroup` | `VJoyToggle` |
+| Customer product UI | `VJoyToggle` `variant="default"` | `variant="admin"` |
+| Internal admin surface | `VJoyToggle` `variant="admin"` | `admin` on public pages |
+
+### Hard rules
+
+1. **MUST** read `VJoyToggle.vue` props (or MCP when available) before generating props — `joy_get_component_info("VJoyToggle")` may not be registered yet.  
+2. **MUST** use `v-model` / `:model-value` + `@update:modelValue` — not `v-model:checked`.  
+3. **MUST NOT** invent props — there is no `size`, `checked` v-model alias, or `color`.  
+4. **MUST NOT** override `.joy-toggle` track, bubble, or focus styles with custom CSS.  
+5. **MUST NOT** use `variant="admin"` outside admin / internal tooling.  
+6. **MUST** provide a visible label (prop or default slot) on every instance.  
+7. **SHOULD** use infinitive labels (EN): `Enable notifications`, not `Notifications enabled`.  
+8. **SHOULD** use `label-position="left"` only when layout requires label-before-switch alignment.
+
+### Checklist
+
+- [ ] Correct component (`VJoyToggle` or named alternative)
+- [ ] Props from source / MCP only — no invented API
+- [ ] `v-model` wired for boolean on/off state
+- [ ] Visible label on every instance
+- [ ] `variant="default"` on customer surfaces
+- [ ] No custom `.joy-toggle` chrome CSS
+- [ ] 3+ options → radio or select, not toggle
+- [ ] Consent copy → checkbox, not toggle
+- [ ] Disabled / validation explained in visible text when user-facing
+- [ ] `name` / `value` set when needed for native form submit
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyToggle.dsds.json`](./JoyToggle.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy | `anatomy` |
+| Variants | `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 (token names, not raw px dumps) |