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

package/dist/doc/VJoyDialog/guideline.md

@@ -0,0 +1,425 @@
+---
+component: VJoyDialog
+status: draft
+language: en
+dsds: JoyDialog.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Dialog
+
+Use **`VJoyDialog`** when you need a modal overlay that interrupts the current task — confirmations, forms, multi-step flows, or focused messaging.
+
+It teleports to `body` by default, supports header/body/footer slots, optional banner imagery, confirm/cancel CTAs, and exposes async `show()` / `hide()` methods. Use **`VJoyDialogTrigger`** when a declarative open trigger is simpler than imperative refs.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyDialog` from `@maltjoy/core-vue` |
+| **Design** | [Figma — Joy Core Design System](https://www.figma.com/design/jfndp2QBJGS9yeuWbeGuvD/%F0%9F%9F%A0--Joy---Core-Design-System--official-) |
+| **Storybook** | [VJoyDialog docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-overlays-vjoydialog--docs) |
+| **DSDS (machine)** | [`JoyDialog.dsds.json`](./JoyDialog.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyDialog")` |
+
+---
+
+## When to use this component
+
+Use a dialog when the user must read, decide, or complete something before returning to the page behind it — for example confirming a destructive action, collecting a short form, or presenting a focused announcement.
+
+Dialogs block interaction with the underlying page (modal overlay) and should be dismissed explicitly or via a clear cancel path.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Slide-in panel from the edge (filters, details, long forms) | `VJoyDrawer` |
+| Lightweight contextual hint on hover/focus | `VJoyTooltip` |
+| Inline expandable section on the same page | `VJoyAccordion` or page layout — not a dialog |
+| Toast / transient feedback after an action | `VJoyToast` |
+| Custom modal markup with ad-hoc CSS | Still use `VJoyDialog` + Joy tokens — don't reinvent overlay chrome |
+
+> **Experimental:** `patternBrand` activates a centered brand layout with decorative shapes. Treat it as experimental until promoted; confirm with design before broad rollout.
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Overlay | Yes | Semi-transparent backdrop; click dismisses unless `patternConfirm` |
+| Container (`joy-dialog__inner`) | Yes | White card with elevation, padding, and max width |
+| Preheader (`dialog-preheader`) | No | Short meta above the title (e.g. tag, badge) |
+| Header (`dialog-header`) | Yes (content) | Dialog title — linked via `aria-labelledby` |
+| Subheader (`dialog-subheader`) | No | Supporting description below the title |
+| Close button | No* | Top-right `VJoyIconButton` (*hidden when `patternConfirm`) |
+| Body (`dialog-body`) | Yes (content) | Main content; scrolls when tall |
+| Footer | No | Cancel / confirm CTAs via props or slots |
+| Banner | No | Optional top image via `bannerSrc` |
+| Brand shapes | No | Decorative shapes when `patternBrand` is true |
+| Indicators (`dialog-indicators`) | No | Step dots for multi-dialog flows (`VJoyIndicators`) |
+
+### Default values
+
+- `size` defaults to **`default`** (580px container width; `large` → 780px)
+- `open` defaults to **`false`**
+- `teleport` defaults to **`body`**
+- `preventBodyScroll` defaults to **`true`** (locks page scroll while open)
+- `closeLabel` defaults to **`"Close dialog"`**
+- `buttonSize` defaults to **`medium`** (footer CTAs)
+- `bannerHeight` defaults to **`250`** (px, when `bannerSrc` is set)
+- `patternConfirm` defaults to **`false`**
+- `patternBrand` defaults to **`false`**
+
+Props, events, slots, and exposed methods: 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.
+
+### Open / close lifecycle
+
+1. **Open** — set `open` or call `show()` on the exposed ref. Body scroll is prevented when `preventBodyScroll` is true.
+2. **Dismiss** — close icon, backdrop click, Escape key, or cancel CTA (default wiring). All fire `dialog:hide` when the leave transition starts.
+3. **Confirm** — default confirm CTA emits `dialog:confirm` only; you still handle persistence and closing.
+4. **Unmount while open** — emits `dialog:before-unmount` and restores body scroll.
+
+`show()` and `hide()` are **async**. `hide({ fireHideEvent: false })` closes without emitting `dialog:hide`.
+
+---
+
+## Variants
+
+Dialogs don't have color variants. Choose layout **patterns** and **size** by context.
+
+### Default pattern
+
+Standard left-aligned header, optional subheader, scrollable body, footer CTAs right-aligned. Backdrop click, Escape, and close icon all dismiss.
+
+Use for most product dialogs — forms, confirmations, informational modals.
+
+### Confirm pattern (`patternConfirm`)
+
+Hides the close icon, disables backdrop dismiss, and ignores Escape. The user must choose a footer CTA (typically cancel or confirm).
+
+Use when accidental dismissal would lose work or cause harm — destructive confirms, irreversible choices, or incomplete required input.
+
+Avoid for low-stakes content where users expect quick escape (use the default pattern).
+
+### Brand pattern (`patternBrand`) — experimental
+
+Centered text layout with decorative primary-colored shapes. Works with `patternConfirm`. Shapes cannot be disabled.
+
+Use for brand moments, onboarding highlights, or marketing-style announcements approved by design.
+
+Avoid combining with `bannerSrc` — they are not meant to work together. If you use an image in the body, set an explicit `width` on the `<img>`.
+
+### Banner image (`bannerSrc`)
+
+Full-width image strip at the top of the dialog card.
+
+Use for visual context (illustration, hero image) that supports the title.
+
+Avoid when `patternBrand` is active. Prefer Joy DAM assets with known dimensions.
+
+### Not in the API: extra sizes
+
+Only `default` and `large` exist in `TJoyDialogSizes`. Do not invent `small` / `medium` dialog sizes. Use `size="large"` for wider content; width tokens live in `--dialog-width` (override via CSS custom property only when design approves).
+
+---
+
+## Sizes
+
+Container width is token-driven inside the component — **don't hardcode pixel widths** in apps.
+
+| Size | Use when |
+| --- | --- |
+| `default` | Standard dialogs (580px on desktop) |
+| `large` | Wider content — tables, two-column forms, rich media (780px on desktop) |
+
+On viewports ≤ 767px the dialog becomes full-screen. Footer CTAs stack vertically on very narrow widths (≤ 400px).
+
+Optional CSS overrides (use sparingly, with design approval):
+
+- `--dialog-width` — container width
+- `--dialog-padding` — inner padding (all sides)
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Closed | Not in DOM flow (`v-if="isOpen"`); no overlay |
+| Opening | Enter transition (scale + fade, 300ms) |
+| Open | Modal overlay; focusable body; dismiss via close / backdrop / Escape (unless `patternConfirm`) |
+| Closing | Leave transition (100ms); `dialog:hide` fires at start |
+| Closed (after transition) | Removed from DOM; `dialog:after-hide` fires; body scroll restored |
+| Confirm pattern | No close icon; backdrop not dismissible; Escape disabled |
+| Scrollable body | Long content scrolls inside body (`max-height` ~580px on desktop) |
+| Demo / docs | `demoMode` prevents hide (Storybook only — not for production) |
+
+Prefer `loading` on footer `VJoyButton` instances during async confirm work instead of silently disabling the dialog.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Hierarchy and placement
+
+- **SHOULD** use one dialog per decision — don't stack unrelated modals.
+- **SHOULD** use `dialog-indicators` + `VJoyIndicators` when navigating a sequence of related dialogs.
+- **MUST NOT** use a dialog for content that fits inline on the page.
+
+### Implementation
+
+- **MUST** use only documented props and enum values (MCP / `JoyDialog.types.ts`).
+- **MUST** teleport to `body` in production (`teleport` default) — `disableTeleport` is for tests/docs.
+- **MUST** wire `dialog:hide` (or call `hide()`) when using custom `dialog-cancel` / `dialog-confirm` slots.
+- **MUST NOT** invent props (`width`, `variant`, `theme`, …).
+- **MUST NOT** override `.joy-dialog` chrome (background, shadow, radius, overlay) with app CSS.
+- **MUST NOT** use `demoMode` outside Storybook.
+
+### Interaction
+
+- **MUST** provide a visible dismiss path in the default pattern (close icon and/or cancel CTA).
+- **SHOULD** use `patternConfirm` only when dismissal risk is real.
+- **SHOULD** call `show()` / `hide()` with `await` when chaining transitions or focus management.
+- **SHOULD** listen to `dialog:after-open` before moving focus into the first field.
+
+### Footer CTAs
+
+- **SHOULD** use `cancelText` / `confirmText` for simple cases (default `VJoyButton` wiring).
+- **SHOULD** use `dialog-cancel` / `dialog-confirm` slots when you need custom variants, icons, or sizes — and **MUST** call `hide()` yourself on cancel.
+- **SHOULD** use one `main` confirm CTA per dialog surface (see `VJoyButton` guidelines).
+
+### Do / don't
+
+| Do | Don't |
+| --- | --- |
+| `VJoyDialogTrigger` for simple open buttons | Reimplement overlay + z-index stack |
+| `patternConfirm` for destructive confirms | Default pattern with no cancel CTA |
+| Explicit `closeLabel` when locale ≠ English default | Leave default "Close dialog" in localized apps |
+| `size="large"` for wide tables/forms | Hardcode `width: 780px` on a wrapper |
+| `bannerSrc` **or** `patternBrand` | Both at once |
+| Set `width` on body images in brand pattern | Unsized images that blow layout |
+
+---
+
+## Content
+
+Dialogs carry the highest-stakes copy on a surface. Title, description, and CTAs must be scannable and action-oriented.
+
+### Title formula
+
+**Short noun phrase or question** — state the decision or topic, not the implementation:
+
+- ✅ Delete project brief?
+- ✅ Update billing address
+- ✅ New feature: AI suggestions
+
+**Subheader** — one sentence of context or consequence. Don't repeat the title.
+
+### Body copy
+
+- **SHOULD** keep body text concise; link out for long legal or help content.
+- **MUST** explain consequences before destructive confirms (what is deleted, whether it's reversible).
+- **SHOULD NOT** bury the primary action below long paragraphs.
+
+### Footer CTA rules
+
+Follow `VJoyButton` content rules. Dialog-specific expectations:
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | Confirm CTA names the outcome — ✅ `Delete project`, `Save changes` |
+| **MUST** | Cancel / dismiss CTA is neutral — ✅ `Cancel`, `Not now` |
+| **MUST NOT** | Vague confirm — ❌ `OK`, `Yes` (unless paired with an unmistakable title) |
+| **MUST NOT** | Guilt-trip cancel — ❌ `No thanks`, `I don't want to save` |
+| **SHOULD** | Destructive confirm repeats the object — ✅ `Delete 6 files` |
+| **SHOULD** | Match title wording between header and confirm CTA |
+| **SHOULD** | ≤ 25 characters per button label; wrap, don't truncate |
+
+### Patterns
+
+**Destructive confirm** — Title states the action; body states impact; `patternConfirm` with cancel + destructive-styled confirm (custom slot if needed). Example: title `Delete project brief?`, body `This cannot be undone.`, CTAs `Cancel` + `Delete project brief`.
+
+**Informational** — Title + short body; single `main` or `primary` confirm (`Got it`, `Continue`). Default dismiss paths are enough; `patternConfirm` usually unnecessary.
+
+**Multi-step** — Use `dialog-indicators` with `VJoyIndicators`; keep titles consistent per step; final step confirm names completion (`Finish setup`).
+
+**Brand / promo (experimental)** — Centered copy; joyful tone allowed; still one clear primary CTA. Images need explicit dimensions.
+
+**Localized apps** — Translate `closeLabel`, `cancelText`, `confirmText`, and all slot content. French copy may need articles/pronouns per `VJoyButton` FR guidance.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | `role="dialog"` with `aria-modal="true"` |
+| Name | Title in `dialog-header` referenced by `aria-labelledby` (`{id}-header`) |
+| Description | Subheader content in `#dialogDescription` when present |
+| Close control | `VJoyIconButton` with `closeLabel` (default: "Close dialog") |
+| Keyboard | **Escape** dismisses unless `patternConfirm` |
+| Focus | Body region is focusable (`tabindex="0"`); move focus into dialog on open when implementing custom flows |
+| Scroll | Page scroll locked while open (`preventBodyScroll`) |
+| Confirm pattern | User is not trapped without a labeled footer action |
+| Motion | Enter/leave transitions; respect `prefers-reduced-motion` at app level if required |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { VJoyDialog } from '@maltjoy/core-vue'
+
+const dialog = ref<InstanceType<typeof VJoyDialog>>()
+
+async function openDialog() {
+  await dialog.value?.show()
+}
+
+async function onConfirm() {
+  // persist, then close
+  await dialog.value?.hide()
+}
+</script>
+
+<template>
+  <!-- Basic dialog with prop-driven CTAs -->
+  <VJoyDialog
+    ref="dialog"
+    cancel-text="Cancel"
+    confirm-text="Save changes"
+    @dialog:confirm="onConfirm"
+    @dialog:hide="() => {}"
+  >
+    <template #dialog-header>Update profile</template>
+    <template #dialog-subheader>Changes apply to your public listing.</template>
+    <template #dialog-body>
+      <!-- form fields -->
+    </template>
+  </VJoyDialog>
+
+  <VJoyButton variant="primary" label="Edit profile" @click="openDialog" />
+
+  <!-- Confirm pattern (no accidental dismiss) -->
+  <VJoyDialog
+    pattern-confirm
+    cancel-text="Cancel"
+    confirm-text="Delete project"
+    @dialog:confirm="onConfirm"
+  >
+    <template #dialog-header>Delete project brief?</template>
+    <template #dialog-body>This action cannot be undone.</template>
+  </VJoyDialog>
+
+  <!-- Custom footer CTAs (you must call hide on cancel) -->
+  <VJoyDialog ref="customDialog">
+    <template #dialog-header>Custom actions</template>
+    <template #dialog-body>…</template>
+    <template #dialog-cancel>
+      <VJoyButton variant="ghost" label="Cancel" @click="customDialog?.hide()" />
+    </template>
+    <template #dialog-confirm>
+      <VJoyButton variant="main" label="Confirm" @click="onConfirm" />
+    </template>
+  </VJoyDialog>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit imports if `VJoyDialog` and `VJoyButton` are already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyDialogTrigger` | Declarative open trigger wrapping any activator |
+| `VJoyDrawer` | Edge panel; long or exploratory content |
+| `VJoyButton` | Footer CTAs (default or custom slots) |
+| `VJoyIconButton` | Close control (built-in) |
+| `VJoyIndicators` / `VJoyIndicator` | Multi-step dialog navigation |
+| `VJoyTag` | Preheader badges (e.g. "New", "Beta") |
+| `VJoyTitleBrand` | Brand-styled titles inside templates or dialogs |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyDialog.dsds.json`](./JoyDialog.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Modal decision / form / confirm | `VJoyDialog` | Custom `position: fixed` div |
+| Side panel / filters / details | `VJoyDrawer` | `VJoyDialog` with hacked full height |
+| Simple open from a button | `VJoyDialog` + `VJoyDialogTrigger` | Inline overlay markup |
+| Must prevent mis-click dismiss | `patternConfirm` | Default pattern without cancel |
+| Brand onboarding moment | `patternBrand` (experimental) | Custom decorative CSS shapes |
+| Hero image on top | `bannerSrc` | `patternBrand` + `bannerSrc` together |
+| Icon-only close | Built-in close `VJoyIconButton` | Raw button with `×` character |
+
+### Hard rules
+
+1. **MUST** call MCP (`joy_get_component_info`, `joy_get_component_types`) before generating props.
+2. **MUST** populate `dialog-header` (accessible name) for every dialog.
+3. **MUST** handle `hide()` when using `dialog-cancel` / `dialog-confirm` slots.
+4. **MUST** use `cancelText` / `confirmText` only when default `VJoyButton` wiring is enough.
+5. **MUST NOT** invent props, sizes, or variants (`size` is only `default` \| `large`).
+6. **MUST NOT** set `demoMode` in product code.
+7. **MUST NOT** combine `bannerSrc` with `patternBrand`.
+8. **MUST NOT** override `.joy-dialog` overlay, shadow, radius, or z-index in app CSS.
+9. **SHOULD** use `patternConfirm` for destructive or data-loss scenarios.
+10. **SHOULD** set localized `closeLabel` when UI language ≠ English.
+11. **SHOULD** `await` `show()` / `hide()` when coordinating focus or route changes.
+
+### Slot checklist
+
+- [ ] `dialog-header` — title present
+- [ ] `dialog-subheader` — only if extra context needed
+- [ ] `dialog-body` — main content
+- [ ] `dialog-preheader` — optional meta (tag)
+- [ ] `dialog-cancel` / `dialog-confirm` — only when customizing CTAs (+ manual `hide`)
+- [ ] `dialog-indicators` — only for multi-step flows
+
+### Generation checklist
+
+- [ ] Correct component (`VJoyDialog` or named alternative)
+- [ ] Props / enums from MCP only (`size`, `buttonSize`, booleans)
+- [ ] No invented props / no custom dialog chrome CSS
+- [ ] Dismiss path defined (default or `patternConfirm` + footer)
+- [ ] Confirm CTA label names the outcome (not bare `OK`)
+- [ ] Custom slots wire `hide()` on cancel
+- [ ] `closeLabel` localized when needed
+- [ ] `bannerSrc` xor `patternBrand` — never both
+- [ ] Images in brand pattern have explicit `width`
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyDialog.dsds.json`](./JoyDialog.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy | `anatomy` |
+| Variants / sizes / patterns | `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 (`--dialog-width`, spacing tokens) |

package/dist/doc/VJoyDialogTrigger/guideline.md

@@ -0,0 +1,186 @@
+---
+component: VJoyDialogTrigger
+status: draft
+language: en
+dsds: JoyDialogTrigger.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Dialog trigger
+
+Use **`VJoyDialogTrigger`** when a declarative click target should open an existing **`VJoyDialog`** — for example a button or icon control wired to a dialog ref without writing a custom `@click` handler.
+
+It renders the default slot as the activator, emits `click`, then calls the linked dialog’s async `show()` method. The trigger adds no visual chrome; styling and semantics come from the slotted control (commonly `VJoyButton` or `VJoyIconButton`).
+
+| | |
+| --- | --- |
+| **Code** | `VJoyDialogTrigger` from `@maltjoy/core-vue` |
+| **Design** | [Figma — Joy Core Design System](https://www.figma.com/design/jfndp2QBJGS9yeuWbeGuvD/%F0%9F%9F%A0--Joy---Core-Design-System--official-) |
+| **Storybook** | [VJoyDialog docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-overlays-vjoydialog--docs) (subcomponent) |
+| **DSDS (machine)** | [`JoyDialogTrigger.dsds.json`](./JoyDialogTrigger.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyDialogTrigger")` |
+
+---
+
+## When to use this component
+
+Use a dialog trigger when the user opens a modal from a visible control in the template — a labeled button, icon button, or link-style activator — and you already have a `VJoyDialog` with a template ref.
+
+Pair **`VJoyDialog`** (content, overlay, dismiss rules) with **`VJoyDialogTrigger`** (open wiring). The trigger keeps open logic declarative: pass the dialog ref via `:dialog`, put the activator in the default slot.
+
+You can place **multiple activators** in the default slot; each one opens the same dialog on click.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Open the dialog from code (route change, API callback, timer) | `await dialogRef.value?.show()` on the `VJoyDialog` ref |
+| Slide-in panel from the edge | `VJoyDrawer` + `VJoyDrawerTrigger` |
+| Mobile bottom sheet | `VJoyBottomSheet` + `VJoyBottomSheetTrigger` |
+| Lightweight hover hint | `VJoyTooltip` |
+| Custom modal markup with ad-hoc CSS | Still use `VJoyDialog` + `VJoyDialogTrigger` — don’t reinvent overlay chrome |
+
+> **Removed from API:** Legacy Stencil `joy-dialog-trigger` used a string `dialog` id and optional `step` for multi-step flows. **`VJoyDialogTrigger` takes a `VJoyDialog` template ref only** — no `step` prop. Control dialog content and indicators on `VJoyDialog` itself.
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Trigger wrapper | Yes | Headless Vue wrapper — no root DOM of its own beyond slotted nodes |
+| Default slot (activator) | Yes | One or more click targets (`VJoyButton`, `<button>`, `VJoyIconButton`, …) |
+| `dialog` prop | Yes | Template ref to the target `VJoyDialog` instance |
+| `click` event | No* | Fires on activator click, **before** `dialog.show()` (*optional listener) |
+
+On click, the component emits `click`, then awaits `renderedDialog.value?.show()`. A computed `renderedDialog` mirrors the `dialog` prop so the ref is read at click time — this avoids races when the dialog ref is still `null` on first mount.
+
+### Default values
+
+- `dialog` — **required** in practice; type is `InstanceType<typeof VJoyDialog> | null | undefined` until the ref is bound
+
+Props, events, and slots: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Composition pattern
+
+```vue
+<VJoyDialog ref="myDialog">…</VJoyDialog>
+
+<VJoyDialogTrigger :dialog="myDialog">
+  <VJoyButton variant="main" label="Open settings" />
+</VJoyDialogTrigger>
+```
+
+Declare `myDialog` as `ref<InstanceType<typeof VJoyDialog> | null>(null)`.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Structure
+
+- **SHOULD** use one `VJoyDialog` per overlay and pass its ref to `:dialog`.
+- **SHOULD** put a **focusable, named** control in the default slot (`VJoyButton`, `VJoyIconButton`, or native `<button>`).
+- **SHOULD** prefer `VJoyDialogTrigger` over inline `@click="dialogRef?.show()"` when the open action is a template-local button.
+- **MAY** render multiple activators in the default slot when several controls should open the same dialog.
+
+### Implementation
+
+- **MUST** pass the `VJoyDialog` template ref to `:dialog` — not a string id.
+- **MUST** use only documented props and events from component types / MCP.
+- **MUST NOT** invent props (`step`, `open`, `variant`, …).
+- **MUST NOT** add custom overlay or z-index CSS on the trigger — it has no visual surface.
+- **SHOULD** handle dialog content, confirm/cancel, and dismiss rules on `VJoyDialog` (see [`JoyDialog.DSDS.guideline.md`](../JoyDialog/JoyDialog.DSDS.guideline.md)).
+- **SHOULD** use imperative `show()` when opening is not tied to a slotted click target.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `VJoyButton` with clear label in the slot | Empty `<div @click>` without keyboard support |
+| `:dialog="dialogRef"` bound to `ref<InstanceType<typeof VJoyDialog>>` | String id from legacy Stencil API |
+| `VJoyDialog` for modal content and close behavior | Duplicate dialog markup next to the trigger |
+| `dialogRef.value?.show()` for programmatic open | `VJoyDialogTrigger` with no slotted activator |
+| Listen to `@click` for analytics before open | Rely on the trigger to close the dialog |
+
+---
+
+## Accessibility
+
+`VJoyDialogTrigger` is a **behavioral** wrapper. Accessible name, role, and keyboard support come from the **slotted activator**.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | No role on the wrapper — the slot child provides it (e.g. `button`) |
+| Name | Activator **MUST** have an accessible name (`label` on `VJoyButton` / `VJoyIconButton`, visible text, or `aria-label`) |
+| Keyboard | Activator **MUST** be focusable and activatable with **Enter** / **Space** when it is a button |
+| Focus after open | Focus management is handled by `VJoyDialog` when the overlay opens — not by the trigger |
+| Multiple triggers | Each activator needs its own accessible name |
+
+Target: **WCAG 2.2 AA** where the product requires it — meet requirements through the slotted control and `VJoyDialog` focus trap / dismiss behavior.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import {
+  VJoyDialog,
+  VJoyDialogTrigger,
+  VJoyButton,
+  VJoyIconButton,
+} from '@maltjoy/core-vue'
+
+const settingsDialog = ref<InstanceType<typeof VJoyDialog> | null>(null)
+
+function onTriggerClick() {
+  // Optional: analytics or guard logic — runs before show()
+}
+</script>
+
+<template>
+  <VJoyDialog ref="settingsDialog" cancel-text="Cancel" confirm-text="Save">
+    <template #dialog-header>Account settings</template>
+    <template #dialog-body>Update your preferences here.</template>
+  </VJoyDialog>
+
+  <!-- Primary button activator -->
+  <VJoyDialogTrigger :dialog="settingsDialog" @click="onTriggerClick">
+    <VJoyButton variant="main" label="Open settings" />
+  </VJoyDialogTrigger>
+
+  <!-- Multiple activators, same dialog -->
+  <VJoyDialogTrigger :dialog="settingsDialog">
+    <VJoyIconButton variant="ghost" icon="settings" label="Settings" />
+    <VJoyButton variant="secondary" label="Edit profile" />
+  </VJoyDialogTrigger>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyDialogTrigger` is already global.
+
+For programmatic open without a trigger component:
+
+```vue
+<button type="button" @click="settingsDialog?.show()">Open from code</button>
+```
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyDialog` | Modal content, overlay, dismiss rules, async `show()` / `hide()` |
+| `VJoyButton` | Default labeled activator in the trigger slot |
+| `VJoyIconButton` | Icon-only activator — pair with a meaningful `label` |
+| `VJoyDrawerTrigger` | Same declarative pattern for `VJoyDrawer` |
+| `VJoyBottomSheetTrigger` | Same pattern for `VJoyBottomSheet` |
+| `VJoyTooltip` | Supplementary hint on the activator, not a modal |
+| `VJoyDrawer` | Edge panel instead of centered modal |