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

package/dist/doc/VJoySnackbar/guideline.md

@@ -0,0 +1,402 @@
+---
+component: VJoySnackbar
+status: draft
+language: en
+dsds: JoySnackbar.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Snackbar
+
+Use **`pushVJoySnackbar`** when you need a brief, non-blocking status update after a user or system action — saved changes, a failed request, or a reversible outcome.
+
+Do **not** mount `<VJoySnackbar>` in templates. The service creates the overlay, wires the event bus, and handles stacking and teardown.
+
+| | |
+| --- | --- |
+| **Code** | `pushVJoySnackbar`, `createAllSnackbarsContainer` from `@maltjoy/core-vue` |
+| **Design** | [ZeroHeight — Snackbar](https://zeroheight.com/6bf479565/p/72e810-snackbar) |
+| **Storybook** | [VJoySnackbar docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-overlays-vjoysnackbar--docs) |
+| **DSDS (machine)** | [`JoySnackbar.dsds.json`](./JoySnackbar.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoySnackbar")` |
+
+---
+
+## When to use this component
+
+Show a snackbar for **short, contextual feedback** that does not block the current task — for example confirming that settings were saved, reporting a recoverable API error, or offering a single follow-up action (undo, retry, view details).
+
+Snackbars auto-dismiss after a timeout (default 5 seconds) unless you set `duration` to `"forever"` or the user closes them.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Inline, persistent helper or field-level error | `VJoyHighlight` |
+| Blocking confirmation or multi-step decision | `VJoyDialog` |
+| Page-level error that must stay until resolved | `VJoyHighlight` (error level) or page-level messaging — not a transient snackbar |
+| Long-form or multi-paragraph content | A dialog, drawer, or dedicated page section |
+| Custom fixed toast / banner markup | Still use `pushVJoySnackbar` + Joy tokens — don't reinvent overlay chrome |
+
+> **Not in the API:** `level="neutral"` is not supported (`TJoySnackbarLevels` excludes `neutral`). Use `info` for neutral informational feedback.
+
+---
+
+## How it works
+
+### Service flow
+
+1. **`SnackbarPlugin`** (installed with the app) calls `createAllSnackbarsContainer()` on the client, injecting a fixed host (`#joy-snackbar__container`) at the bottom of the viewport.
+2. **`pushVJoySnackbar({ props })`** creates a dedicated Vue app per instance, attaches a `mitt` event bus, mounts into a shell inside the host, and returns `{ snackbarEventBus, snackbarApp }`.
+3. On hide (timeout, close click, or manual destroy), the bus emits `snackbar:hide`, which unmounts the app and removes the shell.
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Level icon | Yes | `VJoyIcon` in a colored badge — mapped from `level` (`check-circle`, `warning-triangle`, `info-circle`) |
+| Header | No | Bold title (`header` prop) |
+| Message | Yes | Main copy (`message` prop); rendered with `v-html` so inline links are supported |
+| Action CTA | No | Text link styled CTA (`actionText`); emits `snackbar:action-click` on the bus |
+| Close control | No* | Icon button (cross) when `closable` is true — *default is true |
+| Level underline | Yes | 4px bottom bar colored by `level` token |
+
+### Default values
+
+- `level` defaults to **`success`**
+- `duration` defaults to **`5000`** (milliseconds)
+- `closable` defaults to **`true`**
+- `frozen` defaults to **`false`** (Storybook / docs only — skips enter/leave animation timing)
+
+Props, events, and exposed members: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Event bus
+
+Each instance gets its own bus (you do not pass `bus` yourself):
+
+| Event | When |
+| --- | --- |
+| `snackbar:show` | Emitted on mount |
+| `snackbar:hide` | Emitted after close animation (~300ms after `isOpen` becomes false) |
+| `snackbar:action-click` | Emitted when the user clicks `actionText` |
+
+Unregister listeners when the calling component unmounts.
+
+---
+
+## Variants
+
+In the API, visual emphasis is controlled by **`level`** (semantic severity), not a separate `variant` prop.
+
+### Success (`level="success"`)
+
+Use when an action completed as expected — saved profile, sent message, file uploaded.
+
+Avoid for errors or warnings; the green accent misleads.
+
+### Error (`level="error"`)
+
+Use for failed actions, API errors, or critical issues the user should notice.
+
+Avoid long explanations — keep the header/message short; link out for details if needed.
+
+### Warning (`level="warning"`)
+
+Use for non-blocking conditions the user should be aware of (quota almost reached, partial save).
+
+Avoid when the user must stop and fix something before continuing — prefer `VJoyHighlight` or inline validation.
+
+### Information (`level="info"`)
+
+Use for neutral contextual updates (background sync, tips).
+
+Avoid overusing info snackbars where static page content would suffice.
+
+### Not in the API: `neutral`
+
+Design docs sometimes reference a neutral tone. The code type is `Exclude<TLevels, 'neutral'>`. Do not emit `level="neutral"` — use `info`.
+
+---
+
+## Sizes
+
+The snackbar has a **single layout** — no `size` prop.
+
+| Constraint | Value (implementation) |
+| --- | --- |
+| Desktop width | **580px** fixed (`width: 580px` on `.joy-snackbar` and host container) |
+| Responsive max | `max-width: calc(100% - var(--joy-core-spacing-6) * 2)` |
+| Padding | `var(--joy-core-spacing-4)` (16px) |
+| Position | Fixed, bottom center of viewport (`bottom: 0`, horizontal center via `left`/`right`/`margin: auto`) |
+| Z-index | `var(--joy-core-z-index-snackbar)` |
+
+**Do not** hardcode `580px` or pixel heights in product CSS — the component owns layout. ZeroHeight mentions 375px mobile width; the implementation uses fluid max-width instead.
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Entering | Slides up from below (`showAnimation`, `--joy-transition-duration-long`) |
+| Visible | Message (and optional header, action, close) readable; auto-dismiss timer running when `duration` is a number |
+| Action hover | `actionText` underlines on hover |
+| Closing (user) | Close icon click → `isOpen` false → hide animation → `snackbar:hide` |
+| Closing (timeout) | After `duration` ms → hide animation → `snackbar:hide` ~300ms later |
+| Persistent | `duration: "forever"` — no auto-dismiss; user must close if `closable` |
+| Non-closable | `closable: false` — no close icon; rely on timeout or programmatic teardown |
+| Frozen (docs) | `frozen: true` — near-instant transitions for Storybook screenshots |
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### When to show
+
+- **SHOULD** use snackbars for **reversible or low-stakes** outcomes (saved, copied, added to favorites).
+- **SHOULD** prefer a snackbar over a dialog when no explicit user decision is required.
+- **MUST NOT** use snackbars for errors that block further progress on the page — use `VJoyHighlight` or inline errors instead.
+
+### Implementation
+
+- **MUST** call `pushVJoySnackbar` — never place `<VJoySnackbar>` in app templates.
+- **MUST** pass at least `props.message`.
+- **MUST** use only documented `level` values from MCP / `JoySnackbar.types.ts` (`success`, `error`, `warning`, `info`).
+- **MUST** use Joy tokens — no custom snackbar chrome CSS.
+- **MUST NOT** invent props (`variant`, `neutral`, `position`, …).
+- **MUST** unregister `snackbarEventBus` listeners on component destroy.
+- **SHOULD** set `closable: true` when `actionText` or inline links are present (design guideline for accessibility).
+
+### Stacking
+
+- Multiple calls to `pushVJoySnackbar` stack in the host container (newest shell appended).
+- `disableStacking` exists on `IJoynackbarServiceOptions` but is **not implemented** in the service — do not rely on it.
+
+### Do / don't
+
+| Do | Don't |
+| --- | --- |
+| `pushVJoySnackbar({ props: { message: '…' } })` | `<VJoySnackbar message="…" />` in templates |
+| Match `level` to message meaning | Default everything to `success` |
+| Short header + optional detail in `message` | Paragraphs of text |
+| `actionText` + bus listener for undo/retry | Multiple CTAs (only one `actionText` slot) |
+| `duration: "forever"` only when truly needed | Infinite snackbars for routine success toasts |
+
+---
+
+## Content
+
+Snackbars carry user-facing copy. Keep tone neutral and didactic.
+
+### Structure
+
+| Field | Role | Guidance |
+| --- | --- | --- |
+| `header` | Title (most visible) | Up to **5 words**; specific status, not generic labels |
+| `message` | Body / subtitle | 1–2 short sentences (~90 characters); supports HTML links |
+| `actionText` | Single CTA | Short, action-oriented verb phrase |
+
+### Header formula
+
+**Subject + status** — let the `level` icon and color carry severity:
+
+- ✅ Profile updated
+- ✅ Payment failed
+- ❌ Error
+- ❌ Something went wrong
+- ❌ Success
+- ❌ Congrats
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | Be specific — name what happened (`Invoice sent`, not `Done`) |
+| **MUST** | Keep headers ≤ 5 words |
+| **MUST NOT** | Generic titles (`Error`, `Success`, `Info`, `Congrats`) |
+| **MUST NOT** | Redundant adverbs (`successfully saved`) — the success level already signals outcome |
+| **SHOULD** | Use `message` only when it adds guidance or next steps |
+| **SHOULD** | For error feedback, title alone is often enough (per design guidelines) |
+| **SHOULD** | Sentence case for header and message |
+| **SHOULD NOT** | Repeat the header verbatim in `message` |
+
+### Action CTA (`actionText`)
+
+- **MUST** use a single, contextual verb (`Undo`, `Retry`, `View invoice`).
+- **MUST NOT** use vague dismissals (`Got it`, `Ok`, `I understand`) — use the close icon instead.
+- **SHOULD** use `actionText` for undo, retry, or navigation — not for merely acknowledging the toast.
+
+### Links in `message`
+
+Inline `<a>` tags are supported (`v-html`). Use `VJoyLink` styling patterns (bold, neutral-0 color in the snackbar context).
+
+- **SHOULD** pair links with `closable: true`.
+- **SHOULD** link to FAQ, help, or an in-app destination — not duplicate the `actionText` job.
+
+### Patterns
+
+**Save feedback** — `level: 'success'`, header names the object: `Brief saved`. Optional `message` only if you guide next steps.
+
+**Recoverable error** — `level: 'error'`, specific header: `Upload failed`. `actionText: 'Retry'` with `snackbar:action-click` handler.
+
+**Background info** — `level: 'info'`, short header; skip `actionText` unless there is a real follow-up.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Transient notification region — not a modal dialog |
+| Name | Meaning comes from `header` + `message` text; avoid icon-only meaning |
+| Keyboard | Close button is a native `<button>` and focusable when `closable` |
+| Focus | Transient auto-dismiss snackbars should not trap focus; when `actionText` or links are present, **SHOULD** keep `closable: true` so users can dismiss explicitly |
+| Motion | Enter/leave animations use `--joy-transition-duration-long`; respect `prefers-reduced-motion` at app level where implemented |
+| Links | Inline links in `message` must have discernible text; don't rely on color alone |
+| Timing | Default 5s may be short for long messages — increase `duration` proportionally to copy length |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { pushVJoySnackbar } from '@maltjoy/core-vue'
+
+function notifySaved() {
+  pushVJoySnackbar({
+    props: {
+      level: 'success',
+      header: 'Profile updated',
+      message: 'Your changes are live.',
+    },
+  })
+}
+
+function retryUpload() {
+  // your retry logic
+}
+
+function notifyErrorWithRetry() {
+  const { snackbarEventBus } = pushVJoySnackbar({
+    props: {
+      level: 'error',
+      header: 'Upload failed',
+      message: 'Check your connection and try again.',
+      actionText: 'Retry',
+    },
+  })
+
+  snackbarEventBus.on('snackbar:action-click', retryUpload)
+  snackbarEventBus.on('snackbar:hide', () => {
+    snackbarEventBus.off('snackbar:action-click', retryUpload)
+  })
+}
+
+function persistentInfo() {
+  pushVJoySnackbar({
+    props: {
+      level: 'info',
+      header: 'Sync in progress',
+      message: 'Large files may take a few minutes.',
+      duration: 'forever',
+      closable: true,
+    },
+  })
+}
+</script>
+```
+
+Custom mount (tests / Storybook only):
+
+```typescript
+import { createAllSnackbarsContainer, pushVJoySnackbar } from '@maltjoy/core-vue'
+
+createAllSnackbarsContainer({
+  appendTo: '#my-canvas',
+  defaultMountSelector: 'snackbar-host',
+})
+
+pushVJoySnackbar({
+  snackbarHostId: 'snackbar-host',
+  props: { message: 'Hello from a custom host' },
+})
+```
+
+In Nuxt (or apps with auto-import), omit the import if `pushVJoySnackbar` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyHighlight` | Inline, persistent contextual messages or field-level errors |
+| `VJoyDialog` | Blocking confirmations or multi-field input |
+| `VJoyLink` | Inline navigation patterns referenced inside `message` HTML |
+| `VJoyButton` | Primary actions on the page — not inside the snackbar API |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoySnackbar.dsds.json`](./JoySnackbar.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Brief post-action feedback | `pushVJoySnackbar({ props: { message } })` | `<VJoySnackbar>` in template |
+| Field / section error blocking work | `VJoyHighlight` | Snackbar with `level="error"` |
+| Confirm destructive action | `VJoyDialog` | Snackbar with only `actionText` |
+| Neutral info tone | `level: 'info'` | `level: 'neutral'` (invalid) |
+| Undo / retry | `actionText` + `snackbar:action-click` listener | Second button or invented slot |
+
+### Hard rules
+
+1. **MUST** call MCP (or read types) before generating props.
+2. **MUST** use `pushVJoySnackbar` — never render `<VJoySnackbar>` directly in product code.
+3. **MUST** include `props.message` (required).
+4. **MUST NOT** invent props (`variant`, `size`, `neutral`, `disableStacking` behavior, …).
+5. **MUST NOT** pass `bus` or `instanceNb` — the service sets them.
+6. **MUST NOT** override `.joy-snackbar` layout, colors, or animation in app CSS.
+7. **SHOULD** default `level` to `success` only for genuine success; match severity otherwise.
+8. **SHOULD** set `closable: true` when `actionText` or links are present.
+9. **SHOULD** clean up `snackbarEventBus.on` handlers in `onUnmounted`.
+
+### Checklist
+
+- [ ] `pushVJoySnackbar` (not template component)
+- [ ] `props.message` present
+- [ ] `level` from `success` \| `error` \| `warning` \| `info` only
+- [ ] No invented props / no custom snackbar chrome CSS
+- [ ] Event bus listeners removed on destroy
+- [ ] Header ≤ 5 words, not generic (`Error`, `Success`, …)
+- [ ] `actionText` is action-oriented (not `Ok` / `Got it`)
+- [ ] Inline errors that block the flow → `VJoyHighlight`, not snackbar
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoySnackbar.dsds.json`](./JoySnackbar.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy / service flow | `anatomy` |
+| Levels (`level`) | `variants` |
+| Layout constraints | `design-specifications` |
+| States | `states` |
+| Best practices / content rules | `guidelines` (+ `content`) |
+| Accessibility | `accessibility` |
+| Examples | `sections` |
+| For agents | `agentDocumentBlocks` |
+| Props detail | `api` in JSON + Joy MCP |
+| Service imports | `imports` in JSON (`pushVJoySnackbar`, `createAllSnackbarsContainer`) |

package/dist/doc/VJoySpinner/guideline.md

@@ -0,0 +1,168 @@
+---
+component: VJoySpinner
+status: draft
+language: en
+dsds: JoySpinner.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Spinner
+
+Use **`VJoySpinner`** when you need a compact, animated loading indicator — for example inside a button, a form field area, or a localized content block while data is being fetched or an action is in progress.
+
+It is a lightweight CSS-only spinner with two color presets (`teal`, `white`) for light and dark backgrounds. For full-page or section-blocking loaders with overlay and optional message, prefer **`VJoyScreenLoader`** or built-in **`loading`** on **`VJoyButton`** / **`VJoyIconButton`**.
+
+| | |
+| --- | --- |
+| **Code** | `VJoySpinner` from `@maltjoy/core-vue` |
+| **Design** | [Figma — Joy Core Design System](https://www.figma.com/design/jfndp2QBJGS9yeuWbeGuvD/) |
+| **Storybook** | [VJoySpinner docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-loader-vjoyspinner--docs) |
+| **DSDS (machine)** | [`JoySpinner.dsds.json`](./JoySpinner.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoySpinner")` |
+
+---
+
+## When to use this component
+
+Use a spinner when the user should see that work is **in progress** in a small, inline context — a button submitting a form, a card body waiting for API data, or a custom loader slot inside **`VJoyScreenLoader`**.
+
+Pick **`color="white"`** on filled or dark surfaces (primary/danger buttons, dark overlays). Use **`color="teal"`** (or omit `color`) on light backgrounds.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Button or icon button in a loading state | `VJoyButton` / `VJoyIconButton` with `loading` — spinner color is chosen automatically |
+| Full-page or section overlay with optional message | `VJoyScreenLoader` |
+| Placeholder layout while content shape is unknown | `VJoyBlockSkeleton`, `VJoyFormFieldSkeleton` |
+| Determinate progress (percentage or steps) | `VJoyProgressBar` |
+| Custom animated GIF / ad-hoc CSS spinner | Still use `VJoySpinner` + Joy tokens — don’t reinvent loader chrome |
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Root `.joy-spinner` | Yes | Single `div`; circular border animation |
+| Color modifier | No | `joy-spinner_white` when `color="white"`; default tokens when `color` is omitted or `teal` |
+
+No slots, events, or child elements. The component is purely presentational.
+
+### Default values
+
+- `color` is **optional** — when omitted, default Joy tokens apply (`secondary-50` / `secondary-10`, ~25px size)
+- Storybook defaults `color` to **`teal`**
+
+Sizing and fine-tuning use CSS custom properties on the root (or a positioned parent), not props:
+
+- `--spinner-size` — diameter (default **25px**)
+- `--spinner-default-color` — active arc color
+- `--spinner-default-bg-color` — track color
+
+Props and types: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Positioning
+
+The spinner uses **`position: absolute`** in its base styles. Place it inside a **relatively positioned** container with enough space for the spinner size, or override positioning in a parent wrapper (as **`VJoyScreenLoader`** does with `position: relative` on `.joy-spinner`).
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### When to show a spinner
+
+- **SHOULD** use **`VJoyButton` `loading`** instead of embedding `VJoySpinner` manually in buttons.
+- **SHOULD** pair inline spinners with **visible context** (button label, section heading, or `VJoyScreenLoader` content slot) so the wait state is understandable.
+- **MUST NOT** use a spinner as the only loading feedback on a full view — use **`VJoyScreenLoader`** or skeletons when the whole region is empty.
+
+### Implementation
+
+- **MUST** use only documented `color` values: **`teal`**, **`white`** (from MCP / `TJoySpinnerColors`).
+- **MUST** tune size via **`--spinner-size`** (and token-based color vars if needed) — not hardcoded width/height in product CSS.
+- **MUST NOT** invent props (`size`, `variant`, `label`, …).
+- **MUST NOT** override `.joy-spinner` border animation or colors with one-off app CSS — use `color` or documented CSS variables.
+- **SHOULD** set `color="white"` on dark or filled primary/danger surfaces; `teal` on light backgrounds.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `VJoyButton` `loading` for submit actions | Manual spinner + disabled button without `loading` |
+| `color="white"` on dark overlays / filled buttons | Teal spinner on dark blue button fill |
+| `--spinner-size` in a sized container | Fixed `px` spinner div with custom `@keyframes` |
+| `VJoyScreenLoader` for blocking section load | Lone spinner centered on an empty page with no message |
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Decorative motion only — **no** implicit `role="status"` or live region on `VJoySpinner` itself |
+| Name | **MUST** expose progress in a **parent** control or region: e.g. `aria-busy="true"` on the loading button, `aria-live` on `VJoyScreenLoader` content, or visible “Loading…” copy |
+| Keyboard | Spinner does not receive focus; ensure the trigger stays focusable or clearly disabled while loading |
+| Motion | Continuous rotation (~1.1s linear); respect `prefers-reduced-motion` at app level if you add global animation overrides |
+| Color | Don’t rely on motion alone — pair with text or `aria-busy` on the relevant widget |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { VJoySpinner } from '@maltjoy/core-vue'
+</script>
+
+<template>
+  <!-- Default — light background -->
+  <div style="position: relative; min-height: 48px">
+    <VJoySpinner />
+  </div>
+
+  <!-- Explicit teal on light surface -->
+  <div style="position: relative; min-height: 48px">
+    <VJoySpinner color="teal" />
+  </div>
+
+  <!-- White on dark / filled surface -->
+  <div
+    style="position: relative; min-height: 48px; background: var(--joy-color-secondary-50)"
+  >
+    <VJoySpinner color="white" />
+  </div>
+
+  <!-- Custom size via token (parent or :style on wrapper) -->
+  <div style="position: relative; min-height: 64px; --spinner-size: 40px">
+    <VJoySpinner color="teal" />
+  </div>
+</template>
+```
+
+Prefer **`VJoyButton loading`** over manual spinner placement in buttons:
+
+```vue
+<VJoyButton variant="main" label="Save" :loading="isSaving" />
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoySpinner` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyButton` / `VJoyIconButton` | Async action with built-in spinner via `loading` |
+| `VJoyScreenLoader` | Overlay or centered section loader with optional message |
+| `VJoyDropzone` | File upload processing (embeds spinner internally) |
+| `VJoyBlockSkeleton` / `VJoyFormFieldSkeleton` | Content-shaped placeholders instead of spinners |
+| `VJoyProgressBar` | Known or estimable completion progress |