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

package/dist/doc/VJoyButton/guideline.md

@@ -0,0 +1,371 @@
+---
+component: VJoyButton
+status: draft
+language: en
+dsds: JoyButton.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Button
+
+Use **`VJoyButton`** when the user needs to take an action — save, confirm, continue, or cancel.
+
+It supports variants and sizes, optional icons, a loading state, full-width layout, and can look like a button while navigating somewhere when you set a native `href` (the root becomes an `<a>`). Native `<button>` / `<a>` attributes (for example `disabled`, `type`, `target`, `rel`) are passed through via `useAttrs` — they are not declared as component props.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyButton` from `@maltjoy/core-vue` |
+| **Design** | [Figma — Buttons](https://www.figma.com/design/jfndp2QBJGS9yeuWbeGuvD/?node-id=12704-7106) |
+| **Storybook** | [VJoyButton docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-buttons-vjoybutton--docs) |
+| **DSDS (machine)** | [`JoyButton.dsds.json`](./JoyButton.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyButton")` |
+
+---
+
+## When to use this component
+
+Use a button to help someone carry out an action in the current view — for example submitting a form, confirming a dialog, or starting the next step. `VJoyButton` is the default choice for labeled actions with clear emphasis (main, primary, secondary, ghost) and optional leading or trailing icons.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Icon only (no visible text) | [`VJoyIconButton`](https://doc.malt.tech/joy-storybook/?path=/docs/components-buttons-vjoyiconbutton--docs) |
+| A text link inside a sentence or paragraph | `VJoyLink` |
+| A custom-styled `<button>` / `<a>` | Still use `VJoyButton` + Joy tokens — don’t reinvent chrome |
+
+> **Deprecated:** do not use `circle` on `VJoyButton` for new work. The prop may still appear in older MCP snapshots; it is not part of the current `VJoyButton` API. Prefer `VJoyIconButton`.
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Container | Yes | Root `<button>`, or `<a>` when `href` is set on the element |
+| Label | Yes | Text from the default slot or the `label` prop (rendered in `.joy-button--slot`) |
+| Icon | No | Leading or trailing `VJoyIcon` when `icon` is set (`iconPosition`: `left` or `right`) |
+| Spinner | No | `VJoySpinner` shown when `loading` is true; replaces visible label color |
+| Ripple | Yes | `v-joy-ripple` on the root — tactile feedback on press |
+| Focus ring | Yes | Keyboard focus via border + inset box-shadow — don’t remove it in product CSS |
+
+### Default values
+
+- `variant` defaults to **`primary`**
+- `size` defaults to **`medium`**
+- `iconPosition` defaults to **`left`**
+- `loading` defaults to **`false`**
+- `full` defaults to **`false`**
+- Native `type` defaults to **`button`** when the root is a `<button>`
+
+Props, events, and slots: use Joy MCP (`joy_get_component_info`, `joy_get_component_types`) or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+---
+
+## Variants
+
+Pick emphasis from what the action means on the surface — not from which swatch “looks nicer.”
+
+Allowed values (from `TJoyButtonVariants`): `main`, `primary`, `secondary`, `ghost`, `admin`, `main-ai`, `primary-ai`, `secondary-ai`, `ghost-ai`. There is no `admin-ai`.
+
+### Main
+
+Use for the **single principal CTA** on a page, dialog finalize, or side-panel finalize.
+
+Avoid a second `main` on the **same** surface. The app header, a modal, and a side panel may each have their own `main`.
+
+### Primary
+
+Use for important actions that are **not** the page’s principal CTA. This is the component default.
+
+Avoid competing with an existing `main` for the same decision.
+
+### Secondary
+
+Use for companions to `main` or `primary` — Cancel, Decline, Back.
+
+Avoid using secondary alone when users still need a clear primary action.
+
+### Ghost
+
+Lowest emphasis; no filled background. Use for tertiary or toolbar-like actions.
+
+Avoid for high-stakes confirmations.
+
+### Admin
+
+Internal / admin tooling only. Do not use on customer-facing product UI.
+
+### AI variants (`main-ai`, `primary-ai`, `secondary-ai`, `ghost-ai`)
+
+Use only when the action is explicitly part of an AI feature. Don’t invent custom “AI” colors on a non-AI variant.
+
+### Not in the API: White
+
+ZeroHeight shows a **White** variant. It is **not** in `TJoyButtonVariants`. Do not emit `variant="white"`. Prefer `secondary` or `ghost`, or confirm with design before adding a new API value.
+
+---
+
+## Sizes
+
+Choose size for **density**, not decoration. Heights come from `--joy-form-field-height-*` inside the component — **don’t hardcode pixel heights** in apps.
+
+| Size | Use when |
+| --- | --- |
+| `large` | Hero / marketing-scale CTAs. Only size with a built-in min-width (`calc(var(--joy-core-spacing-base) * 40)`). |
+| `medium` | Default product actions |
+| `small` | Dense toolbars |
+| `xsmall` | Compact UI |
+| `xxsmall` | Inline / very tight layouts |
+
+> ZeroHeight’s “120px min-width” rule is **not** implemented. Don’t use `120px`.
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Default | Enabled and interactive |
+| Hover | Pointer highlight (pointer devices) |
+| Focus | Visible focus ring (keyboard / AT) — `border` + inset `box-shadow` |
+| Active | Pressed; ripple feedback |
+| Disabled | Not interactive (`disabled` attribute) — **always explain why** nearby (tooltip or helper) |
+| Loading | Spinner (white on filled variants; teal on `ghost` / `secondary`); root is non-interactive (`disabled` when `loading`); label text becomes transparent — keep the same `size` so layout doesn’t jump |
+| Full width | `full` prop sets `width: 100%` on the root |
+
+Prefer `loading` during async work instead of only swapping the label or silently disabling.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (same idea as DSDS `guidelines.level`).
+
+### Hierarchy
+
+- **SHOULD** use one `main` CTA per surface (page / dialog / panel counted separately).
+- **SHOULD** pair `secondary` or `ghost` with a stronger CTA when both appear.
+- **SHOULD** put the fuller label on the stronger CTA in a pair (`Approve request` + `Decline`).
+
+### Implementation
+
+- **MUST** use only `variant` / `size` / `iconPosition` values from MCP or `JoyButton.types.ts`.
+- **MUST** style with Joy tokens / utilities — no custom `.joy-button` chrome.
+- **MUST NOT** invent props (`color`, `white`, `height`, …).
+- **MUST NOT** use deprecated `circle` — use `VJoyIconButton`.
+- **MUST NOT** hardcode heights or `min-width: 120px`.
+- **SHOULD** pass native attributes (`disabled`, `href`, `type`, `target`, `rel`) as HTML attributes, not as invented props.
+- **SHOULD** use the default slot for rich label content; use `label` for simple string labels.
+
+### Interaction
+
+- **MUST** set `loading` for async work.
+- **MUST** explain disabled buttons when the user can see them.
+- **SHOULD** set `href` when the control navigates with button chrome (root becomes `<a>`).
+- **SHOULD** use `full` only when the button should span its container (for example mobile primary actions).
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| Use `size` + tokens | Hardcode `24` / `32` / `40` / `48` / `64`px |
+| One `main` per surface | Several competing `main` CTAs |
+| `VJoyIconButton` for icon-only | `VJoyButton` + `circle` |
+| Explain why it’s disabled | A disabled button with no reason |
+| Label = the outcome | Vague labels (`Click`, `Submit`, `Maybe later`) |
+| `loading` during submit | Only changing label text |
+
+---
+
+## Content
+
+Buttons drive action. Labels must be clear, predictable, and aligned with what happens next.
+
+### Label formula
+
+**Infinitive verb + noun** (English):
+
+- ✅ Upload document
+- ✅ Send message
+- ✅ Delete project
+
+**Exceptions:** `Close`, `Cancel`, and `Done` may stand alone (especially on secondary).
+
+Use the default slot or `label` prop — both render the same visible text. Prefer the slot when the label needs markup; prefer `label` for simple strings in Storybook / generated UIs.
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | ≤ 25 characters; never truncate with ellipsis — wrap if needed |
+| **MUST** | Active voice — ✅ `Send message` · ❌ `Message will be sent` |
+| **MUST NOT** | Vague verbs alone — ❌ `Click`, ❌ `Submit` |
+| **MUST NOT** | Yes / No pairs — ✅ `Enable notifications` / `Keep disabled` |
+| **MUST NOT** | User or object names — ✅ `Send quote` · ❌ `Send quote to Jane Doe` |
+| **SHOULD** | ≤ 3 words |
+| **SHOULD** | Counts in parentheses — ✅ `Delete files (6)` |
+| **SHOULD** | Echo title / header wording when it helps |
+| **SHOULD** | Name the destination — ✅ `Continue to payment` · ❌ `Next` (except linear funnels) |
+| **SHOULD** | Secondary still names an action — ✅ `View details`, `Skip step` |
+| **SHOULD NOT** (EN) | Padding articles / pronouns — ❌ `Send my quote` |
+| **SHOULD** (FR) | Articles / pronouns when grammar needs them — _mon profil_, _le projet_ |
+| **SHOULD** | Neutral tone; joyful copy only for tours / promo dialogs |
+
+### Patterns
+
+**Funnels** — Use `Next` / `Previous` only in linear flows. Otherwise name the destination (`Continue to payment`, `Review and confirm`). Keep the same verb + object when the action repeats.
+
+**Dialogs** — Secondary must not guilt the user:
+
+- ✅ Not now · Skip step · Continue without AI
+- ❌ No thanks · I hate saving money
+
+Destructive confirms name the object: ✅ `Delete project brief`, `Cancel subscription`.
+
+**Icons** — Prefer text. Use an icon with label when it reinforces meaning (`icon` + `iconPosition`). Use icon alone only if the meaning is unambiguous (e.g. trash = delete); otherwise add a tooltip. No visible text → `VJoyIconButton`.
+
+**Loading** — Keep a short, present-tense label (`Saving`, `Sending`) while `loading` is true; the spinner provides the progress cue.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Native `<button>` or `<a href>` — never a clickable `<div>` |
+| Name | From default slot or `label`; `aria-labelledby` points to the label span when slot or `label` is present |
+| Keyboard | **Enter** and **Space** activate a `<button>`; links follow native link keyboard behavior |
+| Focus | Keep the focus ring visible — component uses `border` + inset `box-shadow` on `:focus` |
+| Loading | Non-interactive (`disabled` when `loading`); prefer the `loading` prop over manual disable |
+| Disabled | Don’t rely on color alone; provide text explaining why |
+| Icons | Decorative icons are `aria-hidden="true"` (Joy default) |
+| Type | Default `type="button"` on `<button>` roots to avoid accidental form submit |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { VJoyButton } from '@maltjoy/core-vue'
+</script>
+
+<template>
+  <!-- Principal CTA -->
+  <VJoyButton variant="main" size="medium" label="Send quote" />
+
+  <!-- Companions -->
+  <VJoyButton variant="secondary" size="medium" label="Cancel" />
+  <VJoyButton variant="ghost" size="medium" label="View details" />
+
+  <!-- Async -->
+  <VJoyButton variant="main" :loading="true" label="Saving" />
+
+  <!-- As link -->
+  <VJoyButton variant="primary" href="/settings" label="Open settings" />
+
+  <!-- With icon -->
+  <VJoyButton variant="primary" icon="add" icon-position="left" label="Create project" />
+
+  <!-- Full width (e.g. mobile) -->
+  <VJoyButton variant="primary" full label="Continue" />
+
+  <!-- Slot instead of label -->
+  <VJoyButton variant="secondary">
+    Delete files (6)
+  </VJoyButton>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyButton` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyIconButton` | Icon-only actions |
+| `VJoyLink` | Inline text navigation |
+| `VJoySpinner` | Standalone loading indicator (button embeds its own when `loading`) |
+| `VJoyIcon` | Icon primitive used inside the button |
+| `VJoyTooltip` | Explain disabled reasons or icon meaning |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyButton.dsds.json`](./JoyButton.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Icon only | `VJoyIconButton` | `VJoyButton` + `circle` |
+| Navigate in body copy | `VJoyLink` | Ghost button in a paragraph |
+| In-page action | `VJoyButton` | Custom CSS button |
+| Navigate with button chrome | `VJoyButton` + `href` attribute | `<button>` + `@click` router push for external-style links |
+| AI feature | `*-ai` variant (`main-ai`, `primary-ai`, `secondary-ai`, `ghost-ai`) | Non-ai + invented AI styling |
+| Admin-only UI | `variant="admin"` | `admin` on customer surfaces |
+| Full-width mobile CTA | `VJoyButton` + `full` | Custom `width: 100%` on `.joy-button` |
+
+### Hard rules
+
+1. **MUST** call `joy_get_component_info("VJoyButton")` and/or `joy_get_component_types("VJoyButton")` (or read `JoyButton.types.ts`) before generating props.
+2. **MUST** use only documented props: `variant`, `size`, `loading`, `full`, `icon`, `iconPosition`, `label`, `id`.
+3. **MUST** pass native HTML attributes (`disabled`, `href`, `type`, `target`, `rel`, …) as attributes on `VJoyButton`, not as invented props.
+4. **MUST** pass `href` when the control navigates with button chrome.
+5. **MUST** set `loading` for async submit.
+6. **MUST NOT** use `variant="white"`, `variant="admin-ai"`, hardcoded heights, or `min-width: 120px`.
+7. **MUST NOT** override `.joy-button` background, padding, radius, or height.
+8. **MUST NOT** use `circle` — it is not in the current component API.
+9. **SHOULD** default to `variant="primary"` and `size="medium"`; use `main` only for the surface’s principal CTA.
+10. **SHOULD** use `icon-position="left"` (default) or `icon-position="right"` — kebab-case in templates matches Vue prop `iconPosition`.
+
+### Valid enums (from `JoyButton.types.ts`)
+
+| Prop | Values |
+| --- | --- |
+| `variant` | `main`, `primary`, `secondary`, `ghost`, `admin`, `main-ai`, `primary-ai`, `secondary-ai`, `ghost-ai` |
+| `size` | `xxsmall`, `xsmall`, `small`, `medium`, `large` |
+| `iconPosition` | `left`, `right` |
+| `icon` | Any `TJoyIconsNames` value (see Joy Icon docs / MCP) |
+
+### Checklist
+
+- [ ] Correct component (`VJoyButton` or named alternative)
+- [ ] Props / enums from MCP or types only
+- [ ] No invented props / no custom button chrome CSS
+- [ ] Native attrs (`disabled`, `href`, …) passed as HTML attributes
+- [ ] Label ≤ 25 characters; verb + noun (EN) unless exception
+- [ ] Icon-only → `VJoyIconButton`
+- [ ] Disabled / loading explained if user-visible
+- [ ] At most one `main` per surface (documented exceptions OK)
+- [ ] `loading` set for async actions; same `size` retained
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyButton.dsds.json`](./JoyButton.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy | `anatomy` |
+| Variants / 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 (token names, not raw px dumps) |

package/dist/doc/VJoyButton/metadata.json

@@ -29,17 +29,6 @@
         "true"
       ]
     },
-    {
-      "name": "circle",
-      "type": "boolean | undefined",
-      "required": false,
-      "default": "false",
-      "description": "If you only need a button with an icon. To keep your component accessible, you can give a text as slot, it will be used as title and aria-label.\nThis property takes effect only if icon property is set",
-      "possibleValues": [
-        "false",
-        "true"
-      ]
-    },
     {
       "name": "variant",
       "type": "TJoyButtonVariants | undefined",
@@ -124,11 +113,6 @@
       "type": "boolean",
       "isMethod": false
     },
-    {
-      "name": "circle",
-      "type": "boolean",
-      "isMethod": false
-    },
     {
       "name": "variant",
       "type": "TJoyButtonVariants",