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

package/dist/doc/VJoyProductTour/guideline.md

@@ -0,0 +1,455 @@
+---
+component: VJoyProductTour
+status: draft
+language: en
+dsds: JoyProductTour.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Product tour
+
+Use **`VJoyProductTour`** when you need a coachmark anchored to a page element — spotlight a control, explain a new feature, and offer dismiss or next-step actions without leaving the current view.
+
+It teleports to `body`, positions itself with Floating UI around a `spotlightSelector` target, dims the page with an optional overlay, and exposes imperative `show()` / `hide()` methods. Pair with **`VJoyProductTourTrigger`** to open tours from buttons or to chain multi-step flows.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyProductTour`, `VJoyProductTourTrigger` from `@maltjoy/core-vue` |
+| **Design** | [ZeroHeight — Product tour](https://zeroheight.com/6bf479565/p/68fc9a-product-tour) |
+| **Storybook** | [VJoyProductTour docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-overlays-vjoyproducttour--docs) |
+| **DSDS (machine)** | [`JoyProductTour.dsds.json`](./JoyProductTour.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyProductTour")` |
+
+---
+
+## When to use this component
+
+Use a product tour when you want to **draw attention to a specific UI element** and give short, contextual guidance — for example announcing a new toolbar action, explaining a first-time workflow step, or walking someone through a recently shipped feature.
+
+The spotlight keeps the target visible while the card floats nearby. Footer CTAs support skip/dismiss and advancing to the next coachmark in a sequence (`step` / `steps` counter when `steps > 1`).
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Full-page onboarding with illustrations and a persistent walkthrough shell | `VJoyWalkthrough` |
+| Blocking decision, form, or confirmation | `VJoyDialog` |
+| Brief hover/focus hint on a single control | `VJoyTooltip` |
+| Transient feedback after an action | `pushVJoySnackbar` |
+| Custom coachmark / popover with ad-hoc CSS | Still use `VJoyProductTour` + Joy tokens — don't reinvent overlay chrome |
+
+> **SSR (Nuxt):** wrap `VJoyProductTour` in `<ClientOnly>` so positioning and spotlight math run only in the browser. Storybook documents this constraint.
+
+> **Not in the Vue API:** legacy Stencil `dismissed-by` (`all` \| `not-backdrop`) is **not** on `VJoyProductTour`. Backdrop click always dismisses when the overlay is enabled. Do not emit `dismissed-by`.
+
+---
+
+## How it works
+
+`VJoyProductTour` is a thin wrapper that **teleports** `VJoyProductTourInner` to `body`, forwards slots, and registers the instance in a shared store so only one tour is open at a time. Calling `show()` on a new instance hides any previously open tour.
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Teleport host | Yes | Renders the inner tour at `body` to escape stacking contexts |
+| Overlay | No* | Full-viewport dimmer (`joy-product-tour__overlay`); backdrop click dismisses — *skipped when `disableOverlay` is true |
+| Spotlight | Yes* | Highlight frame around the target element — *only when `show()` finds a matching `spotlightSelector` node in `document` |
+| Card (`joy-product-tour`) | Yes | White panel with elevation, padding, and max width |
+| Arrow | Yes | Rotated square positioned by Floating UI middleware |
+| Banner (`product-tour-banner`) | No | Full-width image strip above the title |
+| Preheader (`product-tour-preheader`) | No | Short meta row (e.g. `VJoyTag`); shares row with close control |
+| Close button | No* | Top-right `VJoyIconButton` when `closeButton` is true — *default true |
+| Header (`product-tour-header`) | Yes (content) | Tour title |
+| Icon | No | Optional leading `VJoyIcon` beside title + body |
+| Content (`product-tour-content`) | Yes (content) | Main explanatory copy |
+| Footer | No* | Shown only when `product-tour-dismiss` and/or `product-tour-next` is provided |
+| Dismiss CTA (`product-tour-dismiss`) | No | Left footer action; click bubbles to `hide()` |
+| Step counter | No | `step/steps` text when `steps > 1` and footer is visible |
+| Next CTA (`product-tour-next`) | No | Primary advance action — **does not** auto-hide; wire `hide()` or chain another tour |
+
+### Default values
+
+- `position` defaults to **`bottom`**
+- `open` defaults to **`false`** (set `true` to open on mount)
+- `steps` defaults to **`1`**
+- `step` defaults to **`1`**
+- `maxWidth` defaults to **`500`** (px; sets `--product-tour-width`)
+- `disableOverlay` defaults to **`false`**
+- `spotlightPadding` defaults to **`8`** (px around the highlighted element)
+- `closeButton` defaults to **`true`**
+- `spotlightSelector` is **required** — must be a valid `querySelector` string resolving to a single element
+
+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 component ref. `show()` only succeeds when `document.querySelector(spotlightSelector)` exists inside `document.body`. The store hides any other open tour, creates overlay + spotlight, and positions the card.
+2. **Dismiss** — close icon, `product-tour-dismiss` click (bubbling), or overlay click (when overlay is enabled). All call inner `hide()` and emit `product-tour:hide`.
+3. **Advance** — `product-tour-next` is manual: hide the current tour and open the next instance (often via `VJoyProductTourTrigger` pointing at another `VJoyProductTour` ref).
+4. **Programmatic hide** — `hide()` on the wrapper clears the store and closes UI. Pass `{ fireHideEvent: true }` to emit `product-tour:hide` from the wrapper when the inner tour already hid without bubbling the event.
+
+---
+
+## Variants
+
+`VJoyProductTour` has **no color or emphasis variant**. Choose **`position`** by where there is room around the highlighted element — Floating UI may **flip** to `bottom`, `top`, `left`, or `right` when the preferred side lacks space.
+
+### `bottom` (default)
+
+Use when the target sits in the upper half of the viewport or when content should read below the control.
+
+Avoid when the target is near the bottom edge — prefer `top`.
+
+### `top`
+
+Use when the target sits low on the page and the card should open upward.
+
+Avoid when the target is under a fixed header that would collide with the card.
+
+### `left` / `right`
+
+Use when vertical placement is tight and horizontal space is available beside the target.
+
+Avoid when the target is flush against the viewport edge on that side.
+
+### Overlay modes
+
+| Mode | Use when |
+| --- | --- |
+| Default overlay (`disableOverlay: false`) | Standard coachmarks — block interaction with the rest of the page |
+| No overlay (`disableOverlay: true`) | The highlighted element (or a parent stacking context) must stay interactive; the page remains fully clickable |
+
+---
+
+## Sizes
+
+`VJoyProductTour` has **no `size` prop**. Typography and spacing come from Joy tokens inside the component (`primary-650` header, `primary-300` body, `--joy-core-spacing-*`).
+
+| Control | Use when |
+| --- | --- |
+| Default `maxWidth` (500) | Most in-product coachmarks |
+| Custom `maxWidth` | Narrow side panels or wide banners that need more horizontal room |
+| `spotlightPadding` | Extra breathing room around irregular targets (icons, avatars) |
+
+**Don't** hardcode card width, shadow, or radius on `.joy-product-tour` in product CSS. Use `maxWidth` and Joy tokens.
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Closed (default) | Inner wrapper hidden (`v-show`); no overlay or spotlight |
+| Opening | Overlay + spotlight mount; card fades in; target `z-index` elevated |
+| Open | Card anchored to target; overlay blocks background clicks (unless disabled) |
+| Dismissing | Overlay/spotlight removed; target inline styles cleared; `product-tour:hide` fires |
+| Multi-step | Footer shows `step/steps` when `steps > 1` and footer slots exist |
+| No footer CTAs | No footer row — user relies on close icon and/or overlay dismiss |
+| `open` on mount | Tour registers in the store and shows immediately (client only) |
+| Missing target | `show()` is a no-op when the selector matches nothing |
+
+Only one tour instance is active globally — opening another tour hides the previous one.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### When to show a tour
+
+- **SHOULD** use product tours for **feature discovery** and **one-off education**, not for essential instructions the user cannot complete without.
+- **SHOULD** keep each step focused on **one target element** and one idea.
+- **SHOULD** let users dismiss at any time (close icon, dismiss CTA, or overlay).
+- **MUST NOT** stack multiple unrelated coachmarks without a clear step counter and next action.
+
+### Implementation
+
+- **MUST** provide a stable `spotlightSelector` that resolves to exactly one element in the DOM before calling `show()`.
+- **MUST** use only documented props and enums from MCP / `JoyProductTour.types.ts`.
+- **MUST** teleport via the component (default) — don't nest the tour inside overflow/stacking contexts.
+- **MUST** wrap usage in `<ClientOnly>` on SSR apps (Nuxt).
+- **MUST NOT** invent props (`variant`, `size`, `dismissed-by`, …).
+- **MUST NOT** override `.joy-product-tour` chrome (background, shadow, radius, z-index) in app CSS.
+- **SHOULD** declare the tour as a `ref<InstanceType<typeof VJoyProductTour>>()` when using triggers or imperative APIs.
+- **SHOULD** use `disableOverlay` only when a parent stacking context prevents correct dimming — document why for reviewers.
+
+### Footer and chaining
+
+- **MUST** wire `hide()` yourself on `product-tour-next` when advancing — the slot does not auto-close.
+- **SHOULD** use `VJoyProductTourTrigger` inside `product-tour-next` to open the next tour ref.
+- **SHOULD** provide `product-tour-dismiss` for skip / not-now paths in multi-step flows.
+- **SHOULD** set `steps` and `step` when the footer is visible and the flow has more than one coachmark.
+- **MUST NOT** show a step counter without footer CTAs — the counter only renders when a footer exists.
+
+### Interaction
+
+- **SHOULD** call `show()` after the target element is mounted (e.g. `onMounted`, route settled, data loaded).
+- **SHOULD** listen to `product-tour:hide` to persist "seen" state and avoid re-showing dismissed tours.
+- **SHOULD** use `hide({ fireHideEvent: true })` only when coordinating wrapper-level analytics without double emission.
+
+### Do / don't
+
+| Do | Don't |
+| --- | --- |
+| `ClientOnly` in Nuxt | Render tours during SSR |
+| Unique, stable CSS selectors | Fragile selectors (`:nth-child` on dynamic lists) |
+| `VJoyProductTourTrigger` for next step | Manual DOM queries to open the next card |
+| `disableOverlay` for stacking edge cases | Disable overlay by default to "simplify" |
+| `VJoyButton` in footer slots | Raw `<button>` with custom Joy-like CSS |
+| One idea per coachmark | Long paragraphs that belong in help docs |
+| Persist dismiss state | Re-open the same tour every visit |
+
+---
+
+## Content
+
+Product tours are promotional and educational — copy can be slightly more joyful than neutral form labels, but each step must still be scannable.
+
+### Title formula
+
+**Short benefit or feature name** — state what the user can now do, not internal codenames:
+
+- ✅ Share projects with your team
+- ✅ Filter by availability
+- ✅ New: AI job suggestions
+
+### Body copy
+
+- **SHOULD** keep body text to **1–3 short sentences**; link to help center for depth.
+- **SHOULD** describe the **action** the user can take on the highlighted control.
+- **MUST NOT** hide critical compliance or pricing information only inside a tour.
+
+### Footer CTA rules
+
+Follow `VJoyButton` content rules. Tour-specific expectations:
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | Dismiss CTA is neutral — ✅ `Not now`, `Skip`, `Maybe later` |
+| **MUST** | Primary next CTA names the outcome — ✅ `Got it`, `Show me`, `Next: filters` |
+| **MUST NOT** | Generic first/last-step CTAs — ❌ `OK`, `Continue` alone on step 1 or the final step |
+| **MUST NOT** | Guilt-trip dismiss — ❌ `No thanks`, `I don't care` |
+| **SHOULD** | Match title wording in the primary CTA when advancing |
+| **SHOULD** | Use `VJoyTag` in `product-tour-preheader` for `New`, `Beta`, etc. |
+| **SHOULD** | Joyful tone on tours — still one clear primary action per step |
+
+### Patterns
+
+**Single coachmark** — Title + one sentence; optional `Got it` in `product-tour-next` or rely on close + overlay dismiss. Footer optional.
+
+**Multi-step chain** — One `VJoyProductTour` per target; set `step` / `steps`; `product-tour-dismiss` = skip tour; `product-tour-next` + `VJoyProductTourTrigger` opens the next ref. Hide current tour before or when opening the next.
+
+**Feature launch** — Optional `product-tour-banner` image; `icon` (e.g. `sparkles`) when it reinforces "new"; keep image `max-width: 100%` (default deep styles handle block images).
+
+**Localized apps** — Translate all slot content. The built-in close `label` is `"Close"` (English) on `VJoyIconButton` — override via `closeButton={false}` and provide your own control if locale ≠ English.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | Card wrapper uses `role="tooltip"` — treat copy as descriptive context for the highlighted control |
+| Name | Title from `product-tour-header`; body from `product-tour-content` |
+| Close control | `VJoyIconButton` with `label="Close"` when `closeButton` is true |
+| Keyboard | Footer CTAs are real `VJoyButton` / native buttons — must be keyboard activatable |
+| Focus | Ensure the highlighted target remains reachable; don't trap focus inside the card unless product UX explicitly requires it |
+| Overlay | Backdrop click dismisses — provide an equivalent keyboard dismiss path via close or dismiss CTA |
+| Motion | Spotlight fade-in uses `--joy-transition-duration-default`; respect `prefers-reduced-motion` at app level if required |
+| Single tour | Global store prevents multiple simultaneous coachmarks reducing cognitive load |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { onMounted, ref } from 'vue'
+import {
+  VJoyProductTour,
+  VJoyProductTourTrigger,
+  VJoyButton,
+  VJoyTag,
+} from '@maltjoy/core-vue'
+
+const stepOne = ref<InstanceType<typeof VJoyProductTour>>()
+const stepTwo = ref<InstanceType<typeof VJoyProductTour>>()
+
+onMounted(() => {
+  // Optional: auto-open first step when target exists
+  stepOne.value?.show()
+})
+
+function onTourHide() {
+  // Persist "seen" in storage / API
+}
+</script>
+
+<template>
+  <!-- Target on the page -->
+  <button type="button" class="highlight-filters">Filters</button>
+
+  <!-- Step 1 of 2 -->
+  <ClientOnly>
+    <VJoyProductTour
+      ref="stepOne"
+      spotlight-selector=".highlight-filters"
+      :step="1"
+      :steps="2"
+      position="right"
+      icon="sparkles"
+      @product-tour:hide="onTourHide"
+    >
+      <template #product-tour-preheader>
+        <VJoyTag label="New" variant="special" size="xsmall" />
+      </template>
+      <template #product-tour-header>Find freelancers faster</template>
+      <template #product-tour-content>
+        Use filters to narrow results by skills, rate, and availability.
+      </template>
+      <template #product-tour-dismiss>
+        <VJoyButton variant="ghost" size="small" label="Not now" />
+      </template>
+      <template #product-tour-next>
+        <VJoyProductTourTrigger :product-tour="stepTwo">
+          <VJoyButton
+            variant="main"
+            size="small"
+            label="Next: shortlist"
+            @click="stepOne?.hide()"
+          />
+        </VJoyProductTourTrigger>
+      </template>
+    </VJoyProductTour>
+
+    <!-- Step 2 -->
+    <VJoyProductTour
+      ref="stepTwo"
+      spotlight-selector=".highlight-shortlist"
+      :step="2"
+      :steps="2"
+      position="bottom"
+    >
+      <template #product-tour-header>Save your favorites</template>
+      <template #product-tour-content>
+        Add profiles to your shortlist to compare and contact later.
+      </template>
+      <template #product-tour-next>
+        <VJoyButton
+          variant="main"
+          size="small"
+          label="Got it"
+          @click="stepTwo?.hide()"
+        />
+      </template>
+    </VJoyProductTour>
+  </ClientOnly>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit imports if components are already global. Keep `<ClientOnly>` around teleported tours.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyProductTourTrigger` | Declarative activator that calls `show()` on a tour ref |
+| `VJoyWalkthrough` | Full onboarding modal with progress, not element anchoring |
+| `VJoyDialog` | Blocking decisions or forms |
+| `VJoyTooltip` | Lightweight hover/focus hints |
+| `VJoyButton` | Footer dismiss / next CTAs |
+| `VJoyIconButton` | Built-in close control |
+| `VJoyTag` | Preheader badges (`New`, `Beta`) |
+| `VJoyIcon` | Optional leading icon in content |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyProductTour.dsds.json`](./JoyProductTour.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Coachmark on a specific DOM element | `VJoyProductTour` | `VJoyDialog` centered on screen |
+| Full onboarding walkthrough shell | `VJoyWalkthrough` | `VJoyProductTour` without a target |
+| Hover hint on one control | `VJoyTooltip` | `VJoyProductTour` |
+| Open tour from a button | `VJoyProductTour` + `VJoyProductTourTrigger` | `@click` that toggles custom popover CSS |
+| Multi-step anchored tour | Multiple `VJoyProductTour` refs + triggers | One tour with changing `spotlightSelector` without hide/show |
+| Nuxt / SSR app | `<ClientOnly>` + `VJoyProductTour` | Bare tour in server-rendered template |
+
+### Hard rules
+
+1. **MUST** call `joy_get_component_info("VJoyProductTour")` and/or `joy_get_component_types("VJoyProductTour")` (or read `JoyProductTour.types.ts`) before generating props.
+2. **MUST** set `spotlight-selector` (required) to a valid CSS selector string.
+3. **MUST** wrap tours in `<ClientOnly>` when the app uses SSR (Nuxt).
+4. **MUST** call `hide()` on the current tour when advancing via `product-tour-next`.
+5. **MUST NOT** invent props (`variant`, `size`, `dismissed-by`, …).
+6. **MUST NOT** override `.joy-product-tour` / `.joy-product-tour__overlay` z-index, shadow, or background in app CSS.
+7. **SHOULD** use `ref<InstanceType<typeof VJoyProductTour>>()` for imperative `show()` / `hide()`.
+8. **SHOULD** provide `product-tour-dismiss` and/or close button for dismiss paths.
+9. **SHOULD** set `step` and `steps` when footer CTAs exist and the flow has multiple coachmarks.
+
+### Valid enums (from `JoyProductTour.types.ts`)
+
+| Prop | Values |
+| --- | --- |
+| `position` | `left`, `right`, `top`, `bottom` |
+| `icon` | Any `TJoyIconsNames` value (see Joy Icon docs / MCP) |
+| `closeButton` | `true`, `false` |
+| `open` | `true`, `false` |
+| `disableOverlay` | `true`, `false` |
+| `spotlightSelector` | Non-empty CSS selector string (required) |
+| `maxWidth`, `spotlightPadding`, `step`, `steps` | Numbers |
+
+### Slot checklist
+
+- [ ] `product-tour-header` — title present
+- [ ] `product-tour-content` — main copy present
+- [ ] `product-tour-preheader` — only for tags / short meta
+- [ ] `product-tour-banner` — only when an image adds context
+- [ ] `product-tour-dismiss` — skip / not-now in multi-step flows
+- [ ] `product-tour-next` — primary advance (+ manual `hide()` or chained trigger)
+
+### Generation checklist
+
+- [ ] Correct component (`VJoyProductTour` or named alternative)
+- [ ] Props / enums from MCP or types only
+- [ ] `spotlight-selector` targets an element that exists before `show()`
+- [ ] `<ClientOnly>` when SSR
+- [ ] No invented props / no custom tour chrome CSS
+- [ ] Dismiss path defined (close, dismiss slot, and/or overlay)
+- [ ] `product-tour-next` wires `hide()` when chaining
+- [ ] Footer CTAs use `VJoyButton` with outcome-based labels
+- [ ] `step` / `steps` set when `steps > 1` and footer is used
+- [ ] `product-tour:hide` handled to persist seen state
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyProductTour.dsds.json`](./JoyProductTour.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy | `anatomy` |
+| Variants (position / overlay) | `variants` |
+| Sizes (`maxWidth`, padding) | `variants` / `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 |
+| Token sizing | `design-specifications` in JSON (`--product-tour-width`, z-index tokens) |

package/dist/doc/VJoyProductTour/metadata.json

@@ -194,7 +194,7 @@
     },
     {
       "name": "hide",
-      "type": "(options?: { fireHideEvent: boolean; }) => void",
+      "type": "(options?: { fireHideEvent?: boolean | undefined; } | undefined) => void",
       "isMethod": true
     }
   ],

package/dist/doc/VJoyProductTourTrigger/guideline.md

@@ -0,0 +1,167 @@
+---
+component: VJoyProductTourTrigger
+status: draft
+language: en
+dsds: JoyProductTourTrigger.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Product tour trigger
+
+Use **`VJoyProductTourTrigger`** when a control in the page should open a linked **`VJoyProductTour`** — for example a “Show me around” button or a “Next” action inside a tour step.
+
+The trigger renders whatever you place in its default slot (usually `VJoyButton`), emits `click`, then calls `show()` on the `productTour` ref. Same composition pattern as `VJoyDialogTrigger` and `VJoyDrawerTrigger`.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyProductTourTrigger` from `@maltjoy/core-vue` |
+| **Design** | [Figma — Joy Core Design System](https://www.figma.com/design/jfndp2QBJGS9yeuWbeGuvD/) |
+| **Storybook** | [VJoyProductTour docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-overlays-vjoyproducttour--docs) (subcomponent) |
+| **DSDS (machine)** | [`JoyProductTourTrigger.dsds.json`](./JoyProductTourTrigger.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyProductTourTrigger")` |
+
+---
+
+## When to use this component
+
+Use this trigger when opening a product tour should stay **declative** — wrap the activator, pass the tour’s template ref, and let the component wire the click handler.
+
+Typical jobs: a page-level “Start tour” button, or a “Next” CTA inside `product-tour-next` that opens the following `VJoyProductTour` instance.
+
+Declare `VJoyProductTour` with `ref` and pass that ref to `:product-tour`. The trigger uses a computed ref so `show()` runs once the tour component is mounted, even if the ref is briefly `undefined` during setup.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Open the tour from code (route guard, timer, feature flag) | `productTourRef.show()` on the `VJoyProductTour` ref |
+| Configure tour content, spotlight, or steps | `VJoyProductTour` props and slots — not the trigger |
+| Collapsible in-page walkthrough with built-in chrome | `VJoyWalkthrough` (+ its trigger) |
+| Short hover hint on one control | `VJoyTooltip` |
+| Legacy Stencil `product-tour` string ID / `step` / `target` attrs | Vue API: component **ref** via `:product-tour` — those attrs are not on `VJoyProductTourTrigger` |
+| Custom click wrapper with ad-hoc markup | Still use `VJoyProductTourTrigger` + Joy trigger components |
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Trigger host | Yes | Renders each root vnode from the default slot and listens for `click` |
+| Default slot | Yes | The activator UI — most often `VJoyButton` |
+| `productTour` prop | No* | Template ref to `VJoyProductTour`; when set, `show()` is called after `click` |
+
+\*Omitting or leaving `productTour` unset still emits `click` without throwing; the tour simply does not open.
+
+### Default values
+
+- `productTour` defaults to **`undefined`** (no tour opened until a ref is passed)
+- No `variant`, `size`, or styling props — appearance comes entirely from the default slot
+
+Props and events: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Click flow
+
+1. User activates the slotted control.
+2. `VJoyProductTourTrigger` emits **`click`**.
+3. If `productTour` resolves to a mounted instance, it calls **`show()`** on that ref (which registers the tour in the product-tour store and displays the overlay).
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Implementation
+
+- **MUST** declare `VJoyProductTour` with a template `ref` and pass it to `:product-tour`.
+- **MUST** use only documented props from MCP / component types (`productTour` only).
+- **MUST NOT** invent legacy Stencil props (`step`, `target`, string `product-tour` id).
+- **SHOULD** put a `VJoyButton` (or other focusable control) in the default slot — the trigger adds no chrome of its own.
+- **SHOULD** wrap `VJoyProductTour` usage in **`ClientOnly`** in SSR apps (Nuxt) to avoid positioning issues — see `VJoyProductTour` Storybook notes.
+- **MAY** listen to `@click` for analytics or side effects before the tour opens.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `ref` on `VJoyProductTour` + `:product-tour="tourRef"` | String tour id from the old Stencil API |
+| `VJoyButton` in the default slot | Expect the trigger to ship its own button styles |
+| `productTourRef.show()` when opening imperatively | Empty wrapper when a plain `@click` on your button is enough |
+| Nest a trigger in `product-tour-next` for chained tours | Use for non-tour overlays (`VJoyDialog`, `VJoyDrawer`) |
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | No role on the wrapper — the slotted control defines semantics (`button`, `a`, …) |
+| Name | **MUST** give the slot trigger an accessible name (`label` on `VJoyButton`, visible text, or `aria-label`) |
+| Keyboard | **MUST** use a keyboard-activatable slotted control; native `<button>` or `VJoyButton` is preferred |
+| Focus | Opening the tour does not move focus by itself — ensure tour content manages focus when shown (`VJoyProductTour`) |
+| Click-only divs | **MUST NOT** use non-interactive elements as the sole activator without keyboard support |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { VJoyProductTour, VJoyProductTourTrigger, VJoyButton } from '@maltjoy/core-vue'
+
+const productTour = ref<InstanceType<typeof VJoyProductTour>>()
+const productTour2 = ref<InstanceType<typeof VJoyProductTour>>()
+</script>
+
+<template>
+  <VJoyProductTourTrigger :product-tour="productTour">
+    <VJoyButton label="Show product tour" variant="main" />
+  </VJoyProductTourTrigger>
+
+  <VJoyProductTour
+    ref="productTour"
+    spotlight-selector=".highlight-target"
+    :step="1"
+    :steps="2"
+  >
+    <template #product-tour-header>New feature</template>
+    <template #product-tour-content>Short explanation of what changed.</template>
+    <template #product-tour-next>
+      <VJoyProductTourTrigger :product-tour="productTour2">
+        <VJoyButton label="Next" variant="main" size="small" />
+      </VJoyProductTourTrigger>
+    </template>
+  </VJoyProductTour>
+
+  <VJoyProductTour ref="productTour2" spotlight-selector=".other-target" :step="2" :steps="2">
+    <template #product-tour-header>Step two</template>
+    <template #product-tour-content>Continue the tour here.</template>
+  </VJoyProductTour>
+
+  <span class="highlight-target">Feature to highlight</span>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if components are already global. Wrap `VJoyProductTour` in `<ClientOnly>` when using SSR.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyProductTour` | Spotlight overlay, steps, banner, and dismiss/next slots |
+| `VJoyDialogTrigger` | Same ref-based trigger pattern for dialogs |
+| `VJoyDrawerTrigger` | Same pattern for drawers |
+| `VJoyBottomSheetTrigger` | Same pattern for bottom sheets |
+| `VJoyWalkthrough` | Collapsible guided tour with built-in trigger chrome |
+| `VJoyButton` | Default activator inside the trigger slot |
+| `VJoyTooltip` | Brief contextual help — not a product tour |