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

package/dist/doc/VJoyButtonCard/guideline.md

@@ -0,0 +1,384 @@
+---
+component: VJoyButtonCard
+status: draft
+language: en
+dsds: JoyButtonCard.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Button card
+
+Use **`VJoyButtonCard`** when the user needs a **rich, card-shaped call to action** — a title, subtitle, illustration, or other composed content that would not fit in a standard `VJoyButton`.
+
+The component supplies bordered card chrome, hover and focus feedback, and disabled handling. **You compose and style the inner content** via the default slot. It can act as an in-page action (`@click`), a native link (`href`), or a router link (`type` + attrs such as `to`).
+
+| | |
+| --- | --- |
+| **Code** | `VJoyButtonCard` from `@maltjoy/core-vue` |
+| **Design** | [ZeroHeight — ButtonCard](https://zeroheight.com/6bf479565/) (page id `3079912`) |
+| **Storybook** | [VJoyButtonCard docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-buttons-vjoybuttoncard--docs) |
+| **DSDS (machine)** | [`JoyButtonCard.dsds.json`](./JoyButtonCard.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyButtonCard")` |
+
+---
+
+## When to use this component
+
+Use a button card when the choice or action needs **more than a short label** — for example branching onboarding paths, profile-type pickers, or navigation tiles with an icon, title, and supporting line.
+
+Typical jobs: “choose your account type”, “complete your freelance profile”, or opening a destination that benefits from a scannable card layout. The whole card surface is the click target.
+
+Compose several cards in a group when each option represents a **distinct path or action**. Add a group label (`VJoyLabel` or a heading) when the set needs framing context.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| A short text label only (save, cancel, continue) | `VJoyButton` |
+| Icon-only action | `VJoyIconButton` |
+| Inline text navigation in body copy | `VJoyLink` |
+| Picking one option from a list (form data, shipping method) | `VJoyRadio` (`theme="outline"`) inside `VJoyRadioGroup` |
+| Multi-select with card layout | `VJoyCheckboxCard` inside `VJoyCheckboxGroup` |
+| Toggle a single on/off setting | `VJoyToggle` |
+| Custom bordered div + click handler | Still use `VJoyButtonCard` + Joy tokens — don’t reinvent chrome |
+
+> **Deprecated:** `VJoySelectableItem` / `VJoySelectableItemGroup` remain deprecated. Use `VJoyButtonCard` when the interaction is a **CTA or link**, `VJoyCheckboxCard` for boolean multi-select cards, and `VJoyRadio` for exclusive choice.
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Card container | Yes | Root `.joy-button-card` — border, padding, hover, focus, disabled styling |
+| Default slot content | Yes | **Your** title, subtitle, icon, image, or layout — not provided by the component |
+| Focus ring | Yes | `outline` on `:focus-visible` — don’t remove it in product CSS |
+
+There is no built-in title, subtitle, or icon API. Structure copy and imagery in the slot (for example `<strong>` + `<span>`, or `VJoyText` / `VJoyIcon`).
+
+### Rendering modes
+
+The `type` prop chooses the root element (default **`"button"`** — a naming legacy, not always a native `<button>`):
+
+| Configuration | Root element | Typical use |
+| --- | --- | --- |
+| Default (`type="button"`, no `href`) | `<div role="button" tabindex="0">` | In-page action via `@click` |
+| `href` set (default `type`) | `<a href="…">` | External or same-origin navigation |
+| `type="a"` | `<a>` | Explicit anchor; pass `href` via attrs or prop |
+| `type={RouterLink}` (or other component) | That component | SPA routing — pass `to` and other attrs |
+
+Native attributes (`target`, `rel`, `to`, `aria-*`, `@click`, …) pass through via `useAttrs` (`inheritAttrs: false` on the component).
+
+### Default values
+
+- `disabled` defaults to **`false`**
+- `type` defaults to **`"button"`** (renders pseudo-button `<div>` or `<a>` when `href` is set — see table above)
+- `align` defaults to **`"left"`**
+
+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 `variant` or `size` prop**. Border, radius, padding, and colors come from Joy tokens inside the component (`--joy-core-spacing-3`, `--joy-core-radius-4`, `--joy-color-neutral-*`, state tokens) — **don’t hardcode card dimensions or border colors** in product CSS. Card width is **`fit-content`** by default.
+
+---
+
+## Variants
+
+`VJoyButtonCard` has **no visual emphasis variants** (no primary/secondary). Meaning comes from **content** in the slot and from **state** (`disabled`, hover, focus).
+
+### Content alignment (`align`)
+
+| Value | Use when |
+| --- | --- |
+| `left` | Default — text-heavy cards, LTR product UI |
+| `center` | Icon-above-title tiles, symmetric marketing pickers |
+| `right` | Rare; RTL-like layout or deliberate visual balance |
+
+`align` only sets `text-align` on the card — it does not change padding or border.
+
+### Not in the API: selected / checked state
+
+ZeroHeight usage text describes a **“Selected”** border for card pickers. `VJoyButtonCard` has **no `selected`, `checked`, or `active` prop**. For exclusive or multi selection, use `VJoyRadio` (`theme="outline"`) or `VJoyCheckboxCard`. Use `VJoyButtonCard` when the card **navigates or triggers an action**, not when it toggles form value.
+
+### Not in the API: loading
+
+There is no `loading` prop. Keep layout stable with surrounding UI or disable the card while async work runs.
+
+---
+
+## Sizes
+
+`VJoyButtonCard` exposes **no size API**. Padding and border width are fixed in component styles.
+
+| Aspect | Guidance |
+| --- | --- |
+| Card width | `fit-content` — wrap in a grid or `VJoyWrapper` for equal-width groups |
+| Inner typography | Use `VJoyText`, headings, or Joy utility classes in the slot — don’t invent `size` on the card |
+| Density | Prefer shorter copy over shrinking padding via custom CSS |
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Default | Neutral border; pointer cursor; entire card clickable |
+| Hover | Border uses `--joy-color-state-hover` (pointer devices, when not disabled) |
+| Focus | Visible `outline` + hover border token on `:focus-visible` |
+| Disabled | Muted border, background, and text; `aria-disabled="true"`; `tabindex="-1"`; clicks prevented — **explain why** nearby when possible |
+| Pseudo-button keyboard | **Enter** and **Space** synthesize a click on the `<div role="button">` root |
+| Anchor / router | Native link or router keyboard behavior; disabled still sets `aria-disabled` and blocks interaction |
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### When to choose this over a plain button
+
+- **SHOULD** use button cards for **branching** choices that change the user’s path or open a rich destination.
+- **MUST NOT** use button cards for simple form fields where `VJoyRadio` or `VJoySelect` is enough.
+- **SHOULD** use `VJoyButton` when the label fits in one short line.
+
+### Groups and hierarchy
+
+- **SHOULD** make each card in a group **meaningfully distinct** — if two labels could be swapped, rewrite them.
+- **SHOULD** add a group label (`VJoyLabel` or heading) when options aren’t self-evident.
+- **SHOULD** avoid a competing principal `VJoyButton` (`variant="main"`) directly beside the card group — subordinate “Continue” below the choice.
+- **MUST NOT** nest secondary links, tooltips, or buttons inside the card — the whole surface is one target.
+
+### Implementation
+
+- **MUST** use only documented props from MCP or `JoyButtonCard.types.ts` (`disabled`, `href`, `type`, `align`).
+- **MUST** style inner content with Joy typography / spacing utilities — no custom `.joy-button-card` border, padding, radius, or background overrides.
+- **MUST NOT** invent props (`variant`, `size`, `selected`, `loading`, …).
+- **MUST** pass `href` (or router `to`) when the card navigates; use `@click` on the pseudo-button for in-page actions.
+- **SHOULD** set `target` and `rel="noopener"` on external links.
+- **SHOULD** lay out groups with `VJoyWrapper` (grid / flex + gap) rather than margin hacks between cards.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| Rich slot content (title + subtitle + icon) | `VJoyButton` with multi-line slot hacks |
+| `VJoyRadio` outline for exclusive form choice | `VJoyButtonCard` pretending to be a radio |
+| One clear action per card surface | Submit button inside the card |
+| `disabled` + visible explanation | Disabled card with no reason |
+| Joy tokens in slot typography | Hardcoded card border / padding in apps |
+
+---
+
+## Content
+
+Slot copy should help users **self-select** the right path. Follow the same patterns as ZeroHeight ButtonCard content guidelines.
+
+### Group label (optional)
+
+Use when the card set needs a framing question or context:
+
+- ✅ What type of account are you creating?
+- ✅ Account type
+- ❌ Please select one of the following options.
+
+Use sentence case. End questions with `?`.
+
+### Label (title in slot)
+
+**Short noun phrase** naming the path or option — the first thing users read:
+
+- ✅ Freelance profile
+- ✅ Company account
+
+Keep labels **parallel** across siblings (same grammar). Target **two to four words**, one line, sentence case, no trailing punctuation.
+
+### Subtitle (supporting line in slot)
+
+Clarifies the label — answers “is this the right option for me?”:
+
+- ✅ Complete your skills and availability.
+- ✅ Manage team members and billing.
+
+One or two lines. Don’t restate the label. Use a full sentence with a period, or a tight noun phrase without one — stay consistent within the group.
+
+### Icon / illustration
+
+- **SHOULD** reinforce the label; omit if decorative only.
+- **MUST NOT** use an icon as the only accessible name — pair with visible text.
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | Every card has a visible primary label in the slot |
+| **MUST** | Options in a group feel distinct — rewrite if labels are interchangeable |
+| **MUST NOT** | Imply a “right answer” in copy unless one genuinely exists |
+| **MUST NOT** | Overlap subtitles across cards — options may be too similar |
+| **SHOULD** | Include a catch-all option (e.g. Other) when the set must feel exhaustive |
+| **SHOULD** | Keep subtitles to one or two lines — split or redesign if more is needed |
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | `<a>` for links; `<div role="button">` for default in-page actions; router component defines its own semantics |
+| Name | From visible text in the default slot — ensure a concise title is present |
+| Keyboard | Pseudo-button: **Tab** to focus, **Enter** / **Space** activate; links: native link keys |
+| Focus | Visible focus ring on `:focus-visible` — don’t remove `outline` in product CSS |
+| Disabled | `aria-disabled="true"`, `tabindex="-1"`, click/key activation blocked |
+| Large target | Entire card is the hit area — don’t nest separate interactive controls inside |
+| External links | Meaningful link text in the slot; `rel="noopener"` when opening new tabs |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { RouterLink } from 'vue-router'
+import { VJoyButtonCard, VJoyWrapper, VJoyIcon, VJoyLabel } from '@maltjoy/core-vue'
+
+function openWizard() {
+  // navigate or open flow
+}
+</script>
+
+<template>
+  <!-- In-page action (pseudo-button) -->
+  <VJoyButtonCard @click="openWizard">
+    <strong>Freelance profile</strong>
+    <span class="joy-d-block">Complete your profile</span>
+  </VJoyButtonCard>
+
+  <!-- External link -->
+  <VJoyButtonCard
+    href="https://www.malt.fr/help"
+    target="_blank"
+    rel="noopener"
+  >
+    <strong>Help center</strong>
+    <span class="joy-d-block">Browse guides and FAQs</span>
+  </VJoyButtonCard>
+
+  <!-- Router link -->
+  <VJoyButtonCard :type="RouterLink" to="/onboarding/company">
+    <VJoyIcon name="building" />
+    <strong>Company account</strong>
+    <span class="joy-d-block">Invite your team</span>
+  </VJoyButtonCard>
+
+  <!-- Centered tile -->
+  <VJoyButtonCard align="center" href="/onboarding/freelance">
+    <img src="/illustrations/freelance.svg" width="80" alt="" />
+    <strong class="joy-mt-2">Freelance profile</strong>
+    <span class="joy-d-block">Complete your profile</span>
+  </VJoyButtonCard>
+
+  <!-- Group layout -->
+  <VJoyWrapper direction="column" row-gap="4">
+    <VJoyLabel>What type of account are you creating?</VJoyLabel>
+    <VJoyWrapper direction="row" column-gap="4" wrap="wrap">
+      <VJoyButtonCard href="/onboarding/freelance">
+        <strong>Freelance</strong>
+        <span class="joy-d-block">Work as an independent.</span>
+      </VJoyButtonCard>
+      <VJoyButtonCard href="/onboarding/company">
+        <strong>Company</strong>
+        <span class="joy-d-block">Hire and manage projects.</span>
+      </VJoyButtonCard>
+    </VJoyWrapper>
+  </VJoyWrapper>
+
+  <!-- Disabled -->
+  <VJoyButtonCard disabled href="/unavailable">
+    <strong>Enterprise</strong>
+    <span class="joy-d-block">Contact sales to enable.</span>
+  </VJoyButtonCard>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit imports if components are already global. Decorative images should use `alt=""`; meaningful images need descriptive `alt` text.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyButton` | Short labeled actions with variants and loading |
+| `VJoyIconButton` | Icon-only actions |
+| `VJoyLink` | Inline text navigation |
+| `VJoyRadio` / `VJoyRadioGroup` | Exactly one choice in a form (`theme="outline"` for card-like radios) |
+| `VJoyCheckboxCard` / `VJoyCheckboxGroup` | Multi-select card options |
+| `VJoyWrapper` | Grid or flex layout for card groups |
+| `VJoyLabel` | Group question or legend above cards |
+| `VJoyText` / `VJoyIcon` | Typography and icons inside the slot |
+
+---
+
+## For agents
+
+Maps to `agentDocumentBlocks` in [`JoyButtonCard.dsds.json`](./JoyButtonCard.dsds.json). Humans can skip this section.
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Rich CTA / navigation tile | `VJoyButtonCard` | Custom bordered `div` + `@click` |
+| Short verb label (Save, Cancel) | `VJoyButton` | `VJoyButtonCard` with one word |
+| Exclusive form choice | `VJoyRadio` `theme="outline"` | `VJoyButtonCard` + fake selected state |
+| Multi-select cards | `VJoyCheckboxCard` | `VJoyButtonCard` |
+| Icon-only | `VJoyIconButton` | Card with only an icon |
+| SPA route | `VJoyButtonCard` `:type="RouterLink"` + `to` | `div` + manual router push only |
+
+### Hard rules
+
+1. **MUST** call `joy_get_component_info("VJoyButtonCard")` or read `JoyButtonCard.types.ts` before generating props.  
+2. **MUST** put title and supporting copy in the **default slot** — there is no `label` prop.  
+3. **MUST** use `href` or router `to` for navigation; `@click` for pseudo-button actions.  
+4. **MUST NOT** invent props — no `variant`, `size`, `selected`, `loading`, or `label`.  
+5. **MUST NOT** override `.joy-button-card` border, padding, radius, or background.  
+6. **MUST NOT** nest buttons or links inside the card.  
+7. **SHOULD** use `align="center"` for icon-above-title tiles.  
+8. **SHOULD** explain `disabled` in visible nearby text.
+
+### Checklist
+
+- [ ] Correct component (`VJoyButtonCard` or named alternative)
+- [ ] Props from MCP / types only (`disabled`, `href`, `type`, `align`)
+- [ ] Default slot has accessible primary label text
+- [ ] Navigation uses `href` or `RouterLink`; actions use `@click` on pseudo-button
+- [ ] No invented selected/loading/variant API
+- [ ] No custom `.joy-button-card` chrome CSS
+- [ ] No nested interactive controls inside the card
+- [ ] Group cards are distinct; optional `VJoyLabel` for context
+- [ ] Disabled state explained when user-visible
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyButtonCard.dsds.json`](./JoyButtonCard.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy / rendering modes | `anatomy` |
+| Alignment / no variants | `variants` |
+| Sizes (no size API) | `design-specifications` |
+| 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 |