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

package/dist/doc/VJoyBlockSkeleton/guideline.md

@@ -0,0 +1,150 @@
+---
+component: VJoyBlockSkeleton
+status: draft
+language: en
+dsds: JoyBlockSkeleton.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Block skeleton
+
+Use **`VJoyBlockSkeleton`** when you need a **generic rectangular or circular placeholder** while content is loading — for example image areas, text blocks, cards, or avatar circles.
+
+Set `width` and `height` to approximate the final layout, use `circle` for round placeholders, and compose multiple instances inside `VJoyWrapper` for responsive skeleton rows and columns.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyBlockSkeleton` from `@maltjoy/core-vue` |
+| **Design** | [Figma — Joy components](https://www.figma.com/design/jfndp2QBJGS9yeuWbeGuvD/) |
+| **Storybook** | [VJoyBlockSkeleton docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-skeletons-vjoyblockskeleton--docs) |
+| **DSDS (machine)** | [`JoyBlockSkeleton.dsds.json`](./JoyBlockSkeleton.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyBlockSkeleton")` |
+
+---
+
+## When to use this component
+
+Use a block skeleton to show **layout-preserving placeholders** while async data or media loads. Typical jobs: card thumbnails, profile header blocks, list row shapes, or any free-form area where the final content is not a standard form field.
+
+The shimmer animation signals activity without blocking interaction elsewhere on the page.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Form label + input-shaped placeholder | `VJoyFormFieldSkeleton` |
+| Button or inline processing indicator | `VJoySpinner` |
+| Full-page or section-blocking load | `VJoyScreenLoader` |
+| Custom `<div>` with ad-hoc gray boxes and CSS animation | Still use `VJoyBlockSkeleton` + Joy tokens — don't reinvent skeleton chrome |
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Block container | Yes | Single `<div>` with class `joy-block-skeleton` |
+| Shimmer surface | Yes | Neutral gradient background with `shine` animation (1.5s loop) |
+| Circle modifier | No | Class `joy-block-skeleton--circle` when `circle` is true (`border-radius: 50%`) |
+
+There are **no slots, events, or exposed methods** — sizing and shape are controlled only through props.
+
+### Default values
+
+- `circle` defaults to **`false`** (rounded rectangle via `--joy-core-radius-1`)
+- `width` defaults to **unset** — block stretches to **`width: 100%`** of its container
+- `height` defaults to **`30px`** via internal `--block-skeleton-height` when not passed as a prop
+
+Props: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Sizing and layout
+
+- **`width`** — applied as inline `max-width` (any CSS unit: `px`, `%`, `rem`, …).
+- **`height`** — applied as inline `height` (overrides the 30px default).
+- **`circle`** — renders a circle; **set both `width` and `height` to the same value** (e.g. `60px`) so the shape is round.
+- **`VJoyWrapper`** — when used inside a wrapper, the component auto-applies `flex: 1 0` (or `flex: 1 0 {width}` when `width` is set) so skeletons share horizontal space evenly.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Layout and shape
+
+- **SHOULD** match skeleton dimensions to the expected loaded content to reduce layout shift.
+- **MUST** set explicit `width` and `height` when using `circle` — equal values for a true circle.
+- **SHOULD** compose multiple block skeletons inside `VJoyWrapper` for rows, columns, and mixed-width layouts.
+- **SHOULD** prefer `VJoyFormFieldSkeleton` when the placeholder should look like a form field (label + input proportions).
+
+### Implementation
+
+- **MUST** use only documented props from MCP (`circle`, `width`, `height`).
+- **MUST** use Joy tokens — no custom `.joy-block-skeleton` chrome overrides in product CSS.
+- **MUST NOT** invent props (`size`, `variant`, `color`, …).
+- **MUST NOT** use block skeletons as interactive elements or click targets.
+
+### Do / don't
+
+| Do | Don't |
+| --- | --- |
+| Size blocks to mirror final content | One generic skeleton for every layout |
+| `circle` + equal `width` / `height` for avatars | `circle` without fixed dimensions |
+| `VJoyFormFieldSkeleton` for form-shaped placeholders | Block skeletons mimicking every input size |
+| `VJoyWrapper` for multi-block layouts | Manual flex CSS duplicating wrapper behavior |
+
+---
+
+## Accessibility
+
+`VJoyBlockSkeleton` is **decorative loading chrome** — it is not interactive and does not convey status to assistive technology on its own.
+
+| Behavior | Expectation |
+| --- | --- |
+| `aria-hidden` | Always **`true`** — skeleton is hidden from the accessibility tree |
+| Role | No semantic role; purely visual placeholder |
+| Keyboard / focus | Not focusable — no tab stop |
+| Loading announcement | **MUST** be handled by the parent region (e.g. `aria-busy="true"` on the loading container, or a visible loading label) — the skeleton alone does not announce "loading" |
+| Motion | Continuous shimmer animation — respect `prefers-reduced-motion` at the app level if product policy requires it |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { VJoyBlockSkeleton, VJoyWrapper } from '@maltjoy/core-vue'
+</script>
+
+<template>
+  <!-- Single content block -->
+  <VJoyBlockSkeleton width="100%" height="100px" />
+
+  <!-- Avatar placeholder -->
+  <VJoyBlockSkeleton circle width="60px" height="60px" />
+
+  <!-- Row of mixed-width blocks -->
+  <VJoyWrapper>
+    <VJoyBlockSkeleton height="48px" />
+    <VJoyBlockSkeleton width="120px" height="48px" />
+  </VJoyWrapper>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyBlockSkeleton` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyFormFieldSkeleton` | Placeholder shaped like a form field (with `size` presets) |
+| `VJoyWrapper` | Flex layout for groups of skeletons or mixed content |
+| `VJoySpinner` | Inline or button loading indicator |
+| `VJoyScreenLoader` | Full-screen or overlay loading state |
+| `VJoyAvatar` | Loaded avatar to replace a circular block skeleton |

package/dist/doc/VJoyBottomSheet/guideline.md

@@ -0,0 +1,345 @@
+---
+component: VJoyBottomSheet
+status: draft
+language: en
+dsds: JoyBottomSheet.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Bottom Sheet
+
+Use **`VJoyBottomSheet`** when you need a mobile-first modal surface that slides up from the bottom — action menus, contextual choices, or focused content that must be dismissed before returning to the page behind it.
+
+It teleports to `body` by default, supports drag-to-dismiss on the header handle, click-outside dismiss, customizable content and footer slots, and imperative `show()` / `hide()` via a template ref. Use **`VJoyBottomSheetTrigger`** when a declarative open trigger is simpler than wiring refs yourself.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyBottomSheet` from `@maltjoy/core-vue` |
+| **Design** | [ZeroHeight — Bottom Sheet](https://zeroheight.com/6bf479565/) |
+| **Storybook** | [VJoyBottomSheet docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-overlays-vjoybottomsheet--docs) |
+| **DSDS (machine)** | [`JoyBottomSheet.dsds.json`](./JoyBottomSheet.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyBottomSheet")` |
+
+---
+
+## When to use this component
+
+Use a bottom sheet when the user must focus on a short set of options or actions on **mobile or narrow viewports** — for example choosing a filter, confirming a lightweight decision, or presenting supplementary content without leaving the current screen.
+
+Bottom sheets block interaction with the underlying page (overlay + scroll lock) and should be dismissed explicitly, via the default close CTA, drag-down, or click outside.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Centered modal on desktop (confirmations, forms, announcements) | `VJoyDialog` |
+| Edge panel with long or exploratory content | `VJoyDrawer` |
+| Dropdown / action list anchored to a control | `VJoyDropdown` or `VJoyMenu` |
+| Brief non-blocking feedback after an action | `pushVJoySnackbar` |
+| Inline expandable section on the same page | Page layout or `VJoyAccordion` — not a bottom sheet |
+| Custom fixed panel with ad-hoc CSS | Still use `VJoyBottomSheet` + Joy tokens — don't reinvent overlay chrome |
+
+> **Docs only:** `frozen` keeps the sheet open and skips animation timing (Storybook). Do not use in production.
+
+> **Custom footer:** when you replace the default `bottom-sheet-cta` slot, you **must** call `hide()` yourself on dismiss actions — the sheet will not close automatically and `bottom-sheet:close` will not fire until `hide()` runs.
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Overlay | Yes | Semi-transparent backdrop (`joy-bottom-sheet-overlay`); click outside container dismisses |
+| Container (`joy-bottom-sheet-container`) | Yes | White card sliding from bottom; top radius 20px; elevation shadow |
+| Header (`joy-bottom-sheet_header`) | Yes | Drag handle bar; touch/mouse drag-to-dismiss target |
+| Content (`bottom-sheet-content` slot) | Yes (content) | Main body; scrolls when taller than ~60vh |
+| Footer (`bottom-sheet-cta` slot) | No* | Default full-width `VJoyButton` close CTA (*provided by default) |
+
+### Default values
+
+- `open` defaults to **`false`**
+- `closeLabel` defaults to **`"Close"`**
+- `teleport` defaults to **`"body"`**
+- `preventBodyScroll` defaults to **`true`** (locks page scroll while open)
+- `frozen` defaults to **`false`**
+
+Props, events, slots, and exposed methods: use Joy MCP (`joy_get_component_info`) or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Open / close lifecycle
+
+1. **Open** — set `open` to `true`, or call `show()` on the exposed ref. Body scroll is prevented when `preventBodyScroll` is true.
+2. **Dismiss** — default close CTA, drag header down past **75px**, or click outside the container. All paths call `hide()` unless `frozen` is true.
+3. **Close event** — `bottom-sheet:close` fires after the **300ms** leave animation completes and the sheet is removed from the DOM.
+4. **Controlled mode** — `open` prop is watched; setting it to `false` triggers the same hide animation as imperative `hide()`.
+
+`show()` and `hide()` are synchronous. There is no `bottom-sheet:open` event.
+
+### Drag-to-dismiss
+
+The header handle listens for mouse and touch events. While dragging, the container follows the pointer (`translateY`). Releasing after more than **75px** downward travel dismisses the sheet; smaller movements snap back.
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Closed | Not rendered (`v-if="isOpen"`); no overlay |
+| Opening | Slide-up animation (300ms) |
+| Open | Overlay visible; body scroll locked (default); interact with content and footer |
+| Dragging | Container follows finger/cursor; transition disabled on container |
+| Closing | Slide-down animation (300ms); `bottom-sheet:close` fires after timer |
+| Frozen (`frozen`) | Open state locked — `hide()` is a no-op (docs / Storybook) |
+| Scrollable content | Body scrolls inside content area when taller than `max-height: 60vh` |
+
+Prefer wiring async work on custom footer buttons with `loading` on `VJoyButton` instead of leaving the sheet in an ambiguous half-open state.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Hierarchy and placement
+
+- **SHOULD** reserve bottom sheets for **mobile-first** or narrow layouts; prefer `VJoyDialog` for desktop modal decisions.
+- **SHOULD** use one bottom sheet per focused task — don't stack unrelated sheets.
+- **MUST NOT** use a bottom sheet for content that fits inline on the page.
+
+### Implementation
+
+- **MUST** open and close via `show()` / `hide()`, the `open` prop, or `VJoyBottomSheetTrigger` — there is no automatic hide CSS in product code.
+- **MUST** use only documented props (MCP / component source).
+- **MUST** teleport to `body` in production (`teleport` default).
+- **MUST** wire `hide()` on every dismiss path when using a custom `bottom-sheet-cta` slot.
+- **MUST NOT** invent props (`size`, `variant`, `title`, …).
+- **MUST NOT** override `.joy-bottom-sheet` chrome (overlay, radius, shadow, z-index) with app CSS.
+- **MUST NOT** use `frozen` outside Storybook or docs.
+
+### Interaction
+
+- **SHOULD** keep content concise — long forms belong in `VJoyDrawer` or a full page.
+- **SHOULD** listen to `bottom-sheet:close` to reset local state or sync parent `open` when using imperative open.
+- **SHOULD** add `data-click-outside-ignore` on inner controls when click-outside dismiss would break a nested popover (honours `OnClickOutside` ignore list).
+- **SHOULD NOT** rely on drag-to-dismiss as the only dismiss path — always provide a visible close or cancel action in the footer.
+
+### Do / don't
+
+| Do | Don't |
+| --- | --- |
+| `VJoyBottomSheetTrigger` for simple open buttons | Reimplement overlay + slide animation |
+| Default close CTA for single-action dismiss | Custom footer with no `hide()` wiring |
+| `ref` + `show()` for programmatic open | Expect the sheet to auto-close without calling `hide()` |
+| Scrollable content inside the slot | Unbounded content that exceeds viewport without internal scroll |
+| `preventBodyScroll` in production (default) | Disable scroll lock without a deliberate reason |
+| Localized `closeLabel` | Leave default `"Close"` in non-English UI |
+
+---
+
+## Content
+
+Bottom sheets present focused choices or short copy. Keep header area minimal (drag handle only) — put titles and descriptions in `bottom-sheet-content`.
+
+### Footer CTA rules
+
+Follow `VJoyButton` content rules. Bottom-sheet-specific expectations:
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | Primary action names the outcome — ✅ `Apply filters`, `Save changes` |
+| **MUST** | Dismiss CTA is neutral — ✅ `Close`, `Cancel` |
+| **MUST** | Custom slot buttons call `hide()` when they dismiss |
+| **MUST NOT** | Vague confirm — ❌ `OK`, `Yes` without clear context in the body |
+| **SHOULD** | ≤ 25 characters per button label; wrap, don't truncate |
+| **SHOULD** | Pair `main` / `primary` confirm with `secondary` or `ghost` cancel when both appear |
+| **SHOULD** | Translate `closeLabel` when UI language ≠ English |
+
+### Body copy
+
+- **SHOULD** lead with a short title or question in the content slot.
+- **SHOULD** keep lists and action grids scannable — one primary path per sheet.
+- **MUST NOT** bury the only dismiss action below long scroll-only content without a sticky footer alternative.
+
+### Patterns
+
+**Action menu** — Short list of choices in content; default `Close` in footer or a single confirm CTA that calls `hide()` after the action.
+
+**Light confirm** — One or two sentences in content; footer with `Cancel` + outcome-named confirm (`Delete item`). Wire confirm to persist, then `hide()`.
+
+**Custom dual CTA** — Use `bottom-sheet-cta` with `VJoyWrapper` (see Storybook `CustomizeCTA`); **must** call `hide()` on cancel and after successful confirm.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | No `role="dialog"` or `aria-modal` in the component today — **apps SHOULD** add dialog semantics and focus management when the sheet is business-critical |
+| Name | Provide a visible heading in `bottom-sheet-content`; associate with `aria-labelledby` if you add dialog role |
+| Keyboard | No built-in **Escape** dismiss — provide footer actions; consider app-level Escape handler if required |
+| Focus | Move focus into the sheet on open and restore on close when implementing custom flows |
+| Scroll | Page scroll locked while open (`preventBodyScroll` default) |
+| Drag handle | Visual affordance only — **must not** be the only dismiss path |
+| Close control | Default footer `VJoyButton` has an accessible name from `closeLabel` |
+| Motion | 300ms slide animations; respect `prefers-reduced-motion` at app level if required |
+
+Target: **WCAG 2.2 AA** where the product requires it. Treat focus trap and dialog role as **product responsibilities** until the component adds them natively.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import {
+  VJoyBottomSheet,
+  VJoyBottomSheetTrigger,
+  VJoyButton,
+  VJoyWrapper,
+} from '@maltjoy/core-vue'
+
+const bottomSheet = ref<InstanceType<typeof VJoyBottomSheet>>()
+const triggeredSheet = ref<InstanceType<typeof VJoyBottomSheet>>()
+const customSheet = ref<InstanceType<typeof VJoyBottomSheet>>()
+const isOpen = ref(false)
+
+function onClosed() {
+  // sync parent state, analytics, etc.
+}
+</script>
+
+<template>
+  <!-- Imperative open via ref -->
+  <VJoyBottomSheet
+    ref="bottomSheet"
+    close-label="Close"
+    @bottom-sheet:close="onClosed"
+  >
+    <template #bottom-sheet-content>
+      <h2>Sort results</h2>
+      <p>Choose how listings are ordered.</p>
+      <!-- options -->
+    </template>
+  </VJoyBottomSheet>
+
+  <VJoyButton variant="primary" label="Open sort" @click="bottomSheet?.show()" />
+
+  <!-- Declarative trigger -->
+  <VJoyBottomSheet ref="triggeredSheet">
+    <template #bottom-sheet-content>
+      <p>Opened via VJoyBottomSheetTrigger.</p>
+    </template>
+  </VJoyBottomSheet>
+
+  <VJoyBottomSheetTrigger :bottom-sheet="triggeredSheet">
+    <VJoyButton variant="secondary" label="Show options" />
+  </VJoyBottomSheetTrigger>
+
+  <!-- Controlled open prop -->
+  <VJoyBottomSheet :open="isOpen" @bottom-sheet:close="isOpen = false">
+    <template #bottom-sheet-content>
+      <p>Controlled by parent state.</p>
+    </template>
+  </VJoyBottomSheet>
+
+  <!-- Custom footer — you must call hide() -->
+  <VJoyBottomSheet ref="customSheet">
+    <template #bottom-sheet-content>
+      <p>Discard unsaved changes?</p>
+    </template>
+    <template #bottom-sheet-cta>
+      <VJoyWrapper justify="flex-end">
+        <VJoyButton variant="ghost" size="small" label="Cancel" @click="customSheet?.hide()" />
+        <VJoyButton variant="main" size="small" label="Discard" @click="customSheet?.hide()" />
+      </VJoyWrapper>
+    </template>
+  </VJoyBottomSheet>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit imports if `VJoyBottomSheet`, `VJoyBottomSheetTrigger`, and `VJoyButton` are already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyBottomSheetTrigger` | Declarative open trigger wrapping any activator |
+| `VJoyDialog` | Centered modal on desktop; richer header/footer patterns |
+| `VJoyDrawer` | Edge panel; long or exploratory content |
+| `VJoyButton` | Default close CTA and custom footer actions |
+| `VJoyWrapper` | Layout for multiple footer CTAs |
+| `VJoyDropdown` / `VJoyMenu` | Anchored menus without full-screen overlay |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyBottomSheet.dsds.json`](./JoyBottomSheet.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Mobile modal choices / short focused content | `VJoyBottomSheet` | Custom `position: fixed` slide panel |
+| Desktop modal confirm / form | `VJoyDialog` | `VJoyBottomSheet` on wide desktop-only flows |
+| Simple open from a button | `VJoyBottomSheet` + `VJoyBottomSheetTrigger` | Inline overlay markup |
+| Long filters or details panel | `VJoyDrawer` | Bottom sheet with unbounded scroll |
+| Custom footer actions | `bottom-sheet-cta` slot + `hide()` | Default slot expecting auto-close |
+| Keep sheet visible in Storybook | `frozen` | `frozen` in product code |
+
+### Hard rules
+
+1. **MUST** call MCP (`joy_get_component_info`) before generating props.
+2. **MUST** populate `bottom-sheet-content` for every sheet.
+3. **MUST** call `hide()` on every custom footer dismiss / confirm path.
+4. **MUST** use `show()` / `hide()` or `open` — the sheet does not self-close from CSS alone.
+5. **MUST NOT** invent props (`size`, `variant`, `title`, …).
+6. **MUST NOT** use `frozen` in product code.
+7. **MUST NOT** override `.joy-bottom-sheet` overlay, shadow, radius, or z-index in app CSS.
+8. **SHOULD** prefer `VJoyDialog` when the surface is desktop-primary.
+9. **SHOULD** set localized `closeLabel` when UI language ≠ English.
+10. **SHOULD** listen to `bottom-sheet:close` to sync parent `open` state.
+
+### Slot checklist
+
+- [ ] `bottom-sheet-content` — main body present
+- [ ] `bottom-sheet-cta` — only when customizing footer (+ manual `hide()` on dismiss)
+- [ ] Default close CTA — omit custom slot when a single dismiss button is enough
+
+### Generation checklist
+
+- [ ] Correct component (`VJoyBottomSheet` or named alternative)
+- [ ] Props from MCP only (`closeLabel`, `open`, `preventBodyScroll`, `teleport`, `frozen`)
+- [ ] No invented props / no custom bottom-sheet chrome CSS
+- [ ] Open path defined (`show()`, `open`, or `VJoyBottomSheetTrigger`)
+- [ ] Close path defined (default CTA, drag, click-outside, or custom `hide()`)
+- [ ] Custom footer wires `hide()` on every dismiss action
+- [ ] `closeLabel` localized when needed
+- [ ] `frozen` not set in product code
+- [ ] Content fits mobile; long forms → `VJoyDrawer` / `VJoyDialog`
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyBottomSheet.dsds.json`](./JoyBottomSheet.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy | `anatomy` |
+| 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 (`--joy-core-z-index-dialog`, spacing tokens) |

package/dist/doc/VJoyBottomSheetTrigger/guideline.md

@@ -0,0 +1,156 @@
+---
+component: VJoyBottomSheetTrigger
+status: draft
+language: en
+dsds: JoyBottomSheetTrigger.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Bottom sheet trigger
+
+Use **`VJoyBottomSheetTrigger`** when you need a declarative click target that opens a linked **`VJoyBottomSheet`** — for example a button or link in a mobile funnel that reveals sheet content.
+
+The component has no visual chrome: it renders the default slot as-is, emits `click`, then calls `show()` on the `bottomSheet` ref you pass in.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyBottomSheetTrigger` 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** | [VJoyBottomSheet docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-overlays-vjoybottomsheet--docs) (subcomponent) |
+| **DSDS (machine)** | [`JoyBottomSheetTrigger.dsds.json`](./JoyBottomSheetTrigger.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyBottomSheetTrigger")` |
+
+---
+
+## When to use this component
+
+Use a bottom sheet trigger when a user action in the page should open a specific `VJoyBottomSheet` instance and you prefer a declarative wrapper over calling `bottomSheetRef.value?.show()` in a manual `@click` handler.
+
+Typical pattern: declare a template ref on `VJoyBottomSheet`, pass that ref to `bottomSheet`, and put the activator (`VJoyButton`, native `<button>`, etc.) in the default slot. The trigger handles ref timing so `show()` runs once the sheet instance is mounted.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Open the sheet from code (on mount, after an API call, from a route guard) | `bottomSheetRef.value?.show()` on the `VJoyBottomSheet` ref |
+| A centered modal that blocks the full viewport | `VJoyDialog` + `VJoyDialogTrigger` |
+| A side panel sliding from the edge | `VJoyDrawer` + `VJoyDrawerTrigger` |
+| Tooltip-style contextual help | `VJoyTooltip` |
+| Custom overlay markup / ad-hoc open logic | Still use `VJoyBottomSheetTrigger` or `show()` — don’t reinvent overlay wiring |
+
+---
+
+## How it works
+
+`VJoyBottomSheetTrigger` is a **behavioral wrapper** only. On click it emits `click`, then calls `show()` on the linked bottom sheet. A computed `renderedBottomSheet` tracks the prop so the ref is used even when parent and sheet mount in the same tick.
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Trigger wrapper | Yes | Root logic — no styled DOM of its own |
+| Default slot (trigger) | Yes | One or more activator nodes (e.g. `VJoyButton`, `<button>`) |
+| `bottomSheet` binding | Yes | Template ref to the target `VJoyBottomSheet` instance |
+
+### Default values
+
+- `bottomSheet` is **required** — bind the `VJoyBottomSheet` template ref (may be `null` until mounted; the component retries via `renderedBottomSheet`)
+
+Props, events, and slots: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Composition
+
+- **MUST** place `VJoyBottomSheet` in the same parent (or an ancestor that shares the ref) as `VJoyBottomSheetTrigger`.
+- **MUST** pass the sheet’s template ref to `bottomSheet` (`:bottom-sheet="bottomSheetRef"` in templates).
+- **SHOULD** put an accessible control in the default slot — `VJoyButton` with a `label`, or a native `<button type="button">` with visible text.
+- **SHOULD** listen to `@click` on the trigger when the parent needs side effects before or alongside opening the sheet.
+- **SHOULD** call `bottomSheetRef.value?.show()` directly when there is no user-facing activator.
+
+### Implementation
+
+- **MUST** use only documented props (`bottomSheet`) from MCP / types.
+- **MUST NOT** invent props (`open`, `variant`, `disabled`, …).
+- **MUST NOT** add custom CSS on the trigger wrapper — style the slot content instead.
+- **MUST NOT** use this component without a paired `VJoyBottomSheet` instance.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `VJoyBottomSheet` ref + trigger in the same view | Orphan trigger with no sheet ref |
+| `VJoyButton` or `<button type="button">` in the default slot | `<div @click>` as the only activator |
+| `@click` for parent-side logic | Rely on the trigger to close the sheet |
+| Imperative `show()` when there is no click target | Force a trigger wrapper for programmatic-only open |
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans. The trigger adds no semantics of its own — accessibility comes from the default slot.
+
+| Behavior | Expectation |
+| --- | --- |
+| Role | No dedicated role on the wrapper; the slot content supplies it (`button`, `a`, etc.) |
+| Name | Activator must have an accessible name (`label` on `VJoyButton`, visible text, or `aria-label`) |
+| Keyboard | Activator must be keyboard-operable (native button/link or Joy button components) |
+| Focus | Focus stays on the trigger until the sheet opens; ensure sheet content is reachable after open (handled by `VJoyBottomSheet`) |
+| Touch | Use on mobile-first surfaces where bottom sheets are the primary overlay pattern |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import {
+  VJoyBottomSheet,
+  VJoyBottomSheetTrigger,
+  VJoyButton,
+} from '@maltjoy/core-vue'
+
+const bottomSheetRef = ref<InstanceType<typeof VJoyBottomSheet> | null>(null)
+</script>
+
+<template>
+  <VJoyBottomSheetTrigger :bottom-sheet="bottomSheetRef" @click="/* optional */">
+    <VJoyButton label="Show options" variant="main" />
+  </VJoyBottomSheetTrigger>
+
+  <VJoyBottomSheet ref="bottomSheetRef">
+    <template #bottom-sheet-content>
+      Sheet content here
+    </template>
+  </VJoyBottomSheet>
+</template>
+```
+
+Native button activator (matches test and funnel demos):
+
+```vue
+<VJoyBottomSheetTrigger :bottom-sheet="bottomSheetRef">
+  <button type="button">Open bottom sheet</button>
+</VJoyBottomSheetTrigger>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyBottomSheetTrigger` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyBottomSheet` | The mobile sheet overlay opened by this trigger |
+| `VJoyDialogTrigger` | Same declarative pattern for `VJoyDialog` |
+| `VJoyDrawerTrigger` | Same declarative pattern for `VJoyDrawer` |
+| `VJoyButton` | Typical labeled trigger in the default slot |
+| `VJoyDialog` | Desktop or centered modal instead of a bottom sheet |