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

package/dist/doc/VJoyPagination/guideline.md

@@ -0,0 +1,355 @@
+---
+component: VJoyPagination
+status: draft
+language: en
+dsds: JoyPagination.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Pagination
+
+Use **`VJoyPagination`** when someone needs to move through **pages of results** — for example a searchable list, a data table, or any collection split into fixed-size chunks.
+
+The component renders previous/next controls, numbered page buttons, and automatic ellipsis gaps for large page counts. Bind `v-model:current-page` in the parent and load the matching slice of data when the page changes. Use slots when prev/next or page cells must be real links (`RouterLink`, `NuxtLink`, `<a>`).
+
+| | |
+| --- | --- |
+| **Code** | `VJoyPagination` from `@maltjoy/core-vue` |
+| **Design** | [ZeroHeight — Pagination](https://zeroheight.com/6bf479565/p/952103) |
+| **Storybook** | [VJoyPagination docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-navigation-vjoypagination--docs) |
+| **DSDS (machine)** | [`JoyPagination.dsds.json`](./JoyPagination.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyPagination")` |
+
+---
+
+## When to use this component
+
+Use pagination when content is **split into discrete pages** and users should jump to a specific page or step forward/back one page at a time.
+
+It fits server-driven lists (API returns `totalPages`), client-paginated tables, and any surface where the full dataset is too large to show at once. The component handles which page numbers to display and when to show ellipsis separators — you supply `currentPage`, `totalPages`, and react to page changes.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Carousel or slideshow position dots | `VJoyIndicators` |
+| Linear multi-step workflow with progress | `VJoyStepper` |
+| “Load more” / endless feed | Load-more button or infinite scroll |
+| Primary app navigation between sections | `VJoyTabs`, `VJoyMenu`, or route-level nav |
+| Changing how many items appear per page | Page-size control alongside pagination (not built into this component) |
+| Custom pagination markup / ad-hoc CSS | Still use `VJoyPagination` + Joy tokens |
+
+---
+
+## How it works
+
+`VJoyPagination` is a controlled component: the parent owns `currentPage` and updates it when `update:current-page` fires (or via `v-model:current-page`). Page buttons are `<button type="button">` by default; prev/next use `VJoyIconButton` chevrons (`PaginationIcon`).
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Navigation root | Yes | `<nav role="navigation">` with optional `aria-label` from `labelPagination` |
+| Previous control | Yes | Chevron left (`pagination-prev` slot or default `PaginationIcon`) |
+| Page list | Yes | Numbered page controls; always includes page **1** and the **last** page when `totalPages > 1` |
+| Ellipsis separators | No | CSS `…` when the visible window skips pages (`.joy-pagination__separator`) |
+| Next control | Yes | Chevron right (`pagination-next` slot or default `PaginationIcon`) |
+| Current page marker | Yes | `.current` class + `aria-current="true"` on the active page button |
+
+### Page window algorithm
+
+When `totalPages` is **6 or more**, the component shows at most **six** page entries (first page, last page, and up to four in between). The window recenters around `currentPage` and adds ellipsis when page **1** or the last page is not adjacent to the next visible number.
+
+When `totalPages` is **2–5**, all intermediate pages render with no ellipsis. When `totalPages` is **1**, only page `1` appears (prev/next stay visible but prev/next clicks do not emit at the boundaries).
+
+### Default values
+
+- `currentPage` defaults to **`1`**
+- `totalPages` defaults to **`1`**
+- `labelPagination`, `labelPrev`, and `labelNext` are **optional** — set them for accessibility and i18n
+
+Props, events, and slots: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Controlled usage
+
+```vue
+<VJoyPagination
+  v-model:current-page="page"
+  :total-pages="totalPages"
+  label-pagination="Results pages"
+  label-prev="Previous page"
+  label-next="Next page"
+/>
+```
+
+Fetch or slice data in the parent when `page` changes. The component does **not** fetch data or compute `totalPages` for you.
+
+---
+
+## Variants
+
+`VJoyPagination` has **no variant or emphasis prop**. Visual treatment is fixed: neutral page numbers, teal hover, filled circle on the current page, ghost chevron icon buttons for prev/next.
+
+Do not simulate “primary / compact pagination” with custom CSS — use the component as shipped.
+
+---
+
+## Sizes
+
+`VJoyPagination` has **no size prop**. Page cells and icon buttons use a fixed **36px** circular hit target and `--joy-font-size-primary-650` typography inside the component stylesheet.
+
+Control density with layout around the nav — **do not hardcode `36px` widths or circle radii** in product CSS. Prev/next icons use `VJoyIconButton` at `size="xsmall"` internally.
+
+---
+
+## States
+
+| State | What the user sees / can do |
+| --- | --- |
+| Default page | Neutral number; clickable |
+| Current page | Filled secondary background, white label; `aria-current="true"` |
+| Hover / focus | Teal hover background on page buttons and chevrons; focus ring via `--joy-form-field-focus-shadow` |
+| Previous at page 1 | Prev icon button `disabled`; clicks on the prev region do not emit |
+| Next at last page | Next icon button `disabled`; clicks on the next region do not emit |
+| Ellipsis gap | `…` pseudo-element after page 1 and/or before the last page when numbers are skipped |
+| Single page (`totalPages === 1`) | Only page `1` in the list; boundary guards still apply |
+| Slotted prev/next | Custom link content; component still blocks emit when already at first/last page |
+
+There is **no loading or disabled API** on the whole control. Disable interaction at the page level (e.g. while fetching) in the parent if needed.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Data / selection
+
+- **MUST** bind `currentPage` with `v-model:current-page` (or `:current-page` + `@update:current-page`).
+- **MUST** pass `totalPages` from real data — never invent a page count.
+- **MUST** keep `currentPage` within `1 … totalPages` when `totalPages` shrinks (reset in the parent).
+- **SHOULD** place pagination **below** the list or table it controls, centered or aligned per layout.
+- **SHOULD NOT** show pagination when `totalPages <= 1` unless the layout requires a consistent chrome slot.
+
+### Implementation
+
+- **MUST** use only documented props: `currentPage`, `totalPages`, `labelPagination`, `labelPrev`, `labelNext`.
+- **MUST** style with Joy tokens — no custom `.joy-pagination` chrome overrides.
+- **MUST NOT** invent props. The Stencil `joy-pagination` web component exposes `linkPrev`, `linkNext`, `heapPrev`, and `heapNext` — **these are not on `VJoyPagination`**. Use slots for links in Vue.
+- **SHOULD** use default buttons for SPA page changes; use `pagination-prev`, `pagination-next`, and `page` slots only when links must carry `href`, tracking attributes, or router components.
+- **SHOULD** keep page numbers **1-based**, matching the component API.
+
+### Interaction
+
+- **MUST** reload or slice content when `update:current-page` fires.
+- **MUST** provide `labelPagination`, `labelPrev`, and `labelNext` in production UIs (localized).
+- **SHOULD** scroll the list into view or move focus to the list heading after a page change when it helps orientation.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `v-model:current-page` + computed `totalPages` | Uncontrolled page state scattered in child components |
+| Localized `labelPrev` / `labelNext` | Icon-only chevrons with no accessible name |
+| Slots for `RouterLink` / `NuxtLink` when URLs matter | `@click` router pushes on default buttons when a link is required |
+| Hide pagination when there is only one page | Pagination with `totalPages={0}` or negative values |
+| Let the component compute the page window | Hand-rolling ellipsis logic beside Joy pagination |
+
+---
+
+## Content
+
+Pagination copy is minimal but **required for accessibility**: names for the nav landmark and the prev/next controls. Page cells show **numbers only** — do not embed words inside page buttons.
+
+### Label guidance
+
+| Prop | Purpose | Example (EN) |
+| --- | --- | --- |
+| `labelPagination` | `aria-label` on the `<nav>` | `Results pages`, `Search results pagination` |
+| `labelPrev` | `title` + `aria-label` on previous control | `Previous page` |
+| `labelNext` | `title` + `aria-label` on next control | `Next page` |
+
+### Writing rules
+
+| Strength | Rule |
+| --- | --- |
+| **MUST** | Localize all three labels for non-English locales |
+| **MUST** | Describe the control action — ✅ `Previous page` · ❌ `Back` (ambiguous) |
+| **MUST NOT** | Put “Page” text inside every number button — the number alone is the label |
+| **SHOULD** | Keep `labelPagination` short and specific to the list (`Invoice pagination`) |
+| **SHOULD** | Use sentence case in English |
+| **SHOULD** (FR) | Use natural phrasing — _Page précédente_, _Page suivante_, _Pagination des résultats_ |
+
+### Patterns
+
+**Tables** — Pair with a results summary above (`Showing 1–20 of 142`). Pagination labels name the control, not the row range.
+
+**Search** — Reset `currentPage` to `1` when filters or query change.
+
+**Router-driven pages** — Use the `page` slot so each number is a real link; keep `currentPage` in sync with the route in the parent.
+
+---
+
+## Accessibility
+
+Behaviors (what must happen), not slogans.
+
+| Behavior | Expectation |
+| --- | --- |
+| Landmark | Root is `<nav role="navigation">`; set `labelPagination` so the region has an accessible name |
+| Page buttons | Native `<button type="button">` with visible page number; current page has `aria-current="true"` |
+| Prev / next | Default path uses `VJoyIconButton` with `label` / `title` from `labelPrev` / `labelNext` |
+| Disabled boundaries | Prev disabled on page 1; next disabled on last page; emit blocked even when slots replace icons |
+| Keyboard | Page buttons activate with **Enter** / **Space**; icon buttons follow `VJoyIconButton` keyboard behavior |
+| Focus | Preserve visible focus rings — component uses `--joy-form-field-focus-shadow` on `:focus` |
+| Slotted links | When using `RouterLink` or `<a>`, ensure each link has a clear name (page number or chevron + `aria-label` on the control) |
+
+Target: **WCAG 2.2 AA** where the product requires it.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { ref, watch } from 'vue'
+import { VJoyPagination } from '@maltjoy/core-vue'
+
+const currentPage = ref(1)
+const totalPages = ref(12)
+
+watch(currentPage, (page) => {
+  // fetch or slice data for `page`
+})
+</script>
+
+<template>
+  <!-- Controlled SPA pagination -->
+  <VJoyPagination
+    v-model:current-page="currentPage"
+    :total-pages="totalPages"
+    label-pagination="Results pages"
+    label-prev="Previous page"
+    label-next="Next page"
+  />
+
+  <!-- Router links via slots (Nuxt: use NuxtLink) -->
+  <VJoyPagination
+    v-model:current-page="currentPage"
+    :total-pages="totalPages"
+    label-prev="Previous page"
+    label-next="Next page"
+  >
+    <template #pagination-prev>
+      <RouterLink :to="{ query: { page: currentPage - 1 } }">
+        <VJoyIcon size="xxsmall" name="chevron-left" />
+      </RouterLink>
+    </template>
+
+    <template #page="{ page }">
+      <RouterLink :to="{ query: { page: page.page } }">
+        {{ page.page }}
+      </RouterLink>
+    </template>
+
+    <template #pagination-next>
+      <RouterLink :to="{ query: { page: currentPage + 1 } }">
+        <VJoyIcon size="xxsmall" name="chevron-right" />
+      </RouterLink>
+    </template>
+  </VJoyPagination>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyPagination` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyIconButton` | Prev/next chevrons (used internally via `PaginationIcon`) |
+| `VJoyIcon` | Chevron icons inside custom `pagination-prev` / `pagination-next` slots |
+| `VJoyIndicators` | Dot indicators for carousels or step position — not paged lists |
+| `VJoyTabs` | Switching peer sections on one surface — not sequential pages of one list |
+| `VJoyButton` | “Load more” or actions beside pagination |
+
+---
+
+## For agents
+
+Optional for readers; **required** for vibe-coding quality. Maps to `agentDocumentBlocks` in [`JoyPagination.dsds.json`](./JoyPagination.dsds.json).
+
+### Pick the right component
+
+| If the intent is… | Emit… | Do not emit… |
+| --- | --- | --- |
+| Paginated list / table pages | `VJoyPagination` | Hand-built page number buttons |
+| Carousel slide index | `VJoyIndicators` | `VJoyPagination` |
+| Multi-step form wizard | `VJoyStepper` | `VJoyPagination` |
+| URL-based page links in Vue | `VJoyPagination` + `page` / prev / next slots | Stencil `link-prev` / `link-next` props (not in Vue API) |
+| Infinite scroll feed | Load-more pattern | `VJoyPagination` with `totalPages={1}` hack |
+
+### Hard rules
+
+1. **MUST** read `VJoyPagination.vue`, Storybook, or Joy MCP list entry before generating props — `joy_get_component_info("VJoyPagination")` may be unavailable in some MCP builds; fall back to source.
+2. **MUST** bind `v-model:current-page` (or equivalent controlled pair) and pass `:total-pages`.
+3. **MUST** use only these props: `currentPage`, `totalPages`, `labelPagination`, `labelPrev`, `labelNext`.
+4. **MUST** listen for `@update:current-page` and update list data in the parent.
+5. **MUST NOT** emit Stencil-only props (`linkPrev`, `linkNext`, `heapPrev`, `heapNext`) on `VJoyPagination`.
+6. **MUST NOT** override `.joy-pagination` sizes, colors, or ellipsis spacing with product CSS.
+7. **MUST** set `labelPagination`, `labelPrev`, and `labelNext` for accessible names.
+8. **SHOULD** omit the component when `totalPages <= 1`.
+9. **SHOULD** use slots only when links or extra attributes are required.
+
+### Valid API (from `VJoyPagination.vue`)
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| `currentPage` | `number` | `1` |
+| `totalPages` | `number` | `1` |
+| `labelPagination` | `string` | — |
+| `labelPrev` | `string` | — |
+| `labelNext` | `string` | — |
+
+| Event | Payload |
+| --- | --- |
+| `update:current-page` | `number` (1-based page index) |
+
+| Slot | Scope |
+| --- | --- |
+| `pagination-prev` | — |
+| `pagination-next` | — |
+| `page` | `{ page: number }` |
+
+### Checklist
+
+- [ ] `VJoyPagination` (not `joy-pagination` web component) for Vue apps
+- [ ] `v-model:current-page` + `:total-pages` from real data
+- [ ] `labelPagination`, `labelPrev`, `labelNext` set and localized
+- [ ] Parent handles `update:current-page` / data fetch
+- [ ] No invented props; no Stencil `link-*` / `heap-*` props
+- [ ] No custom `.joy-pagination` chrome CSS
+- [ ] Slots used only when router links or extra attrs are needed
+- [ ] Hidden or omitted when `totalPages <= 1` (unless layout requires it)
+
+---
+
+## DSDS mapping
+
+This Markdown mirrors [`JoyPagination.dsds.json`](./JoyPagination.dsds.json) (DSDS **0.15.2**).
+
+| Section here | DSDS block |
+| --- | --- |
+| When to use / not | `use-cases` |
+| Anatomy / page window | `anatomy` |
+| Variants / sizes | `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 |
+| Fixed cell sizing | `design-specifications` in JSON |

package/dist/doc/VJoyPanel/guideline.md

@@ -0,0 +1,238 @@
+---
+component: VJoyPanel
+status: draft
+language: en
+dsds: JoyPanel.dsds.json
+dsdsVersion: "0.15.2"
+---
+
+# Panel
+
+Use **`VJoyPanel`** when content should sit inside a bordered card-like container with an optional header (title, subtitle, actions), a main body, and optional footer CTAs.
+
+It is a layout primitive: slot-driven structure, Joy spacing tokens, responsive padding, a loading overlay, and an `ai` border variant for AI-related surfaces. Nest **`VJoyPanelSection`** inside `panel-body` when the body needs titled sub-blocks.
+
+| | |
+| --- | --- |
+| **Code** | `VJoyPanel` from `@maltjoy/core-vue` |
+| **Design** | [ZeroHeight — Panel](https://zeroheight.com/6bf479565/p/3095627-panel) |
+| **Storybook** | [VJoyPanel docs](https://doc.malt.tech/joy-storybook/?path=/docs/components-layout-vjoypanel--docs) |
+| **DSDS (machine)** | [`JoyPanel.dsds.json`](./JoyPanel.dsds.json) |
+| **Live API** | `joy_get_component_info("VJoyPanel")` |
+
+---
+
+## When to use this component
+
+Use a panel to group related content on a page or inside a wider layout — settings blocks, summary cards, form sections with a title and confirm/cancel row, or dashboard tiles that need a consistent border and padding.
+
+Put the primary copy and controls in `panel-body`. Use `panel-title` / `panel-subtitle` for the section heading, `panel-title-action` for header utilities (edit, overflow menu), and `panel-action` for bottom-aligned CTAs (often a `VJoyWrapper` of buttons).
+
+Set `loading` when the panel’s content is fetching or saving; optional `panel-loader-content` customizes the overlay message.
+
+### When not to use this component
+
+| Need | Use instead |
+| --- | --- |
+| Full-page chrome (header, sidebar, back link, page loader) | `VJoyTemplate` |
+| Multi-step funnel layout | `VJoyFunnel` |
+| Modal or drawer with open/close lifecycle | `VJoyDialog` / `VJoyDrawer` |
+| Generic flex row/column without card chrome | `VJoyWrapper` |
+| Inline highlight / alert banner (no card frame) | `VJoyHighlight` |
+| Custom `<div>` + border-radius CSS for the same job | Still use `VJoyPanel` + Joy tokens |
+
+---
+
+## How it works
+
+### Anatomy
+
+| Part | Required? | What it is |
+| --- | --- | --- |
+| Root `<section>` | Yes | `joy-panel`; receives `flex` inline style when set |
+| Header | No* | Rendered when any header slot is present (`panel-title`, `panel-subtitle`, `panel-title-action`, `panel-title-icon`) |
+| Title row | No | `panel-title` (+ optional `panel-title-icon` before it); typography from `titleSize` |
+| Title action | No | `panel-title-action` — top-right header utilities |
+| Subtitle | No | `panel-subtitle` — full-width under the title row |
+| Body | Yes** | `panel-body` — main content area |
+| Footer | No | `panel-action` — typically CTAs with top spacing |
+| Loading overlay | No | `VJoyScreenLoader` when `loading` is true; blurs header/body/footer |
+| Loader message | No | `panel-loader-content` slot inside the overlay |
+
+\*Header omitted when no header slots are provided.  
+\*\*The slot is always available; omit content only when the panel is intentionally empty (e.g. skeleton parent).
+
+### Default values
+
+- `padding` defaults to **`medium`** (`small` | `medium` | `large`)
+- `variant` defaults to **`default`** (`default` | `ai`)
+- `titleSize` defaults to **`large`** (`small` | `large`)
+- `loading` defaults to **`false`**
+- `loadingColor` defaults to **`light`** (`light` | `dark`)
+- `noMargin` defaults to **`false`**
+- Bottom margin is also suppressed automatically when the panel is a direct child of **`VJoyWrapper`** (injected context)
+
+Props and slots: use Joy MCP or Storybook — this page focuses on **when** and **how**, not a full API dump.
+
+### Composition notes
+
+- Use semantic heading levels inside `panel-title` (e.g. `<h2>`) — the panel does not render a heading element for you.
+- Stack **`VJoyPanelSection`** components in `panel-body` for repeated titled blocks; spacing between sections is handled by panel CSS.
+- For footer actions, align buttons with **`VJoyWrapper`** (`justify="flex-end"` is common).
+- Set `variant="ai"` only for AI-feature surfaces; it changes the border token to `--joy-color-ai-primary-30`.
+
+---
+
+## Best practices
+
+Rules use RFC 2119 strength (**MUST** / **SHOULD** / **MUST NOT** / **SHOULD NOT**).
+
+### Structure
+
+- **SHOULD** provide `panel-title` when the panel needs a visible section name; pair with `panel-subtitle` for supporting context.
+- **SHOULD** reserve `panel-action` for primary/secondary actions tied to the panel content — not global page actions.
+- **SHOULD** use `VJoyPanelSection` inside `panel-body` when the body has multiple titled subsections.
+- **SHOULD** set `loading` during async refresh of the panel’s own data, not for whole-page navigation.
+
+### Implementation
+
+- **MUST** use only documented props and enums from MCP / component types (`padding`, `variant`, `titleSize`, `loading`, `loadingColor`, `noMargin`, `flex`).
+- **MUST** use Joy tokens — no custom panel border, radius, or background in product CSS.
+- **MUST NOT** invent props (`size`, `theme`, `elevation`, …).
+- **MUST NOT** override `.joy-panel` padding, border, or `--panel-bottom-margin` with hardcoded pixel values.
+- **SHOULD** set `noMargin` (or place the panel in `VJoyWrapper`) when stacking panels in a flex column — avoid double vertical spacing.
+- **SHOULD** use `titleSize="small"` for nested or secondary panels; keep `large` for primary section titles.
+
+### Do / don’t
+
+| Do | Don’t |
+| --- | --- |
+| `panel-title` + `panel-body` + optional `panel-action` | Empty bordered box with no title or body purpose |
+| `VJoyPanelSection` for multi-block bodies | Manual `<hr>` + ad-hoc margins between blocks |
+| `variant="ai"` on AI surfaces only | `ai` variant for generic marketing cards |
+| `loading` + `panel-loader-content` for panel-scoped fetch | Full-page loader for a small inline refresh |
+| `VJoyWrapper` in `panel-action` for button alignment | Absolutely positioned footer buttons |
+
+---
+
+## Accessibility
+
+`VJoyPanel` renders a **`<section>`** landmark. It does not supply headings or labels — those come from slot content.
+
+| Behavior | Expectation |
+| --- | --- |
+| Landmark | Root is `<section>` — use when the panel is a distinct document region |
+| Naming | Put a real heading in `panel-title` (`<h2>`–`<h4>` matching page outline) so the section has an accessible name |
+| Subtitle | `panel-subtitle` is plain content — associate visually with the title; don’t rely on it alone for critical instructions |
+| Header actions | Controls in `panel-title-action` need their own accessible names (`label` on `VJoyIconButton`, visible text on links) |
+| Footer actions | Use `VJoyButton` / `VJoyLink` with clear labels; order primary action consistently (often last in LTR layouts) |
+| Loading | `loading` blurs content and shows an overlay — ensure `panel-loader-content` (or loader default) is readable; avoid trapping keyboard focus inside a non-modal panel overlay |
+| Focus | The panel wrapper is not focusable; focus moves to interactive children in slots |
+
+Target: **WCAG 2.2 AA** where the product requires it — meet requirements through proper headings, button labels, and loading feedback in slot content.
+
+---
+
+## Examples
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import {
+  VJoyPanel,
+  VJoyPanelSection,
+  VJoyButton,
+  VJoyWrapper,
+  VJoyIcon,
+} from '@maltjoy/core-vue'
+
+const saving = ref(false)
+
+async function save() {
+  saving.value = true
+  // await api.save()
+  saving.value = false
+}
+</script>
+
+<template>
+  <!-- Standard panel with header, body, footer -->
+  <VJoyPanel>
+    <template #panel-title>
+      <h2>Notification preferences</h2>
+    </template>
+    <template #panel-subtitle>
+      Choose how we contact you about project updates.
+    </template>
+    <template #panel-body>
+      <!-- form fields, lists, etc. -->
+    </template>
+    <template #panel-action>
+      <VJoyWrapper justify="flex-end">
+        <VJoyButton variant="ghost" size="xxsmall" label="Cancel" />
+        <VJoyButton variant="main" size="xxsmall" label="Save" @click="save" />
+      </VJoyWrapper>
+    </template>
+  </VJoyPanel>
+
+  <!-- Title icon + header action -->
+  <VJoyPanel title-size="small">
+    <template #panel-title-icon>
+      <VJoyIcon name="star" size="medium" />
+    </template>
+    <template #panel-title>
+      <h3>Featured</h3>
+    </template>
+    <template #panel-title-action>
+      <VJoyButton variant="ghost" size="xxsmall" label="Edit" />
+    </template>
+    <template #panel-body>
+      <p>Summary content…</p>
+    </template>
+  </VJoyPanel>
+
+  <!-- Nested sections + loading -->
+  <VJoyPanel :loading="saving" padding="large">
+    <template #panel-title>
+      <h2>Billing details</h2>
+    </template>
+    <template #panel-body>
+      <VJoyPanelSection>
+        <template #panel-section-title>Payment method</template>
+        <template #panel-section-content>…</template>
+      </VJoyPanelSection>
+      <VJoyPanelSection>
+        <template #panel-section-title>Invoice address</template>
+        <template #panel-section-content>…</template>
+      </VJoyPanelSection>
+    </template>
+    <template #panel-loader-content>Updating billing…</template>
+  </VJoyPanel>
+
+  <!-- AI variant -->
+  <VJoyPanel variant="ai">
+    <template #panel-title>
+      <h2>AI suggestions</h2>
+    </template>
+    <template #panel-body>
+      <p>Generated recommendations…</p>
+    </template>
+  </VJoyPanel>
+</template>
+```
+
+In Nuxt (or apps with auto-import), omit the import if `VJoyPanel` is already global.
+
+---
+
+## Related
+
+| Component | Use when |
+| --- | --- |
+| `VJoyPanelSection` | Titled sub-blocks inside `panel-body` |
+| `VJoyWrapper` | Flex layout for footer buttons or stacked panels (auto `no-margin`) |
+| `VJoyTemplate` | Full page layout with header, content, and sidebar slots |
+| `VJoyDialog` / `VJoyDrawer` | Focus-trapped overlay with its own header/footer patterns |
+| `VJoyHighlight` | Inline status or info banner without card chrome |
+| `VJoyScreenLoader` | Standalone overlay (panel embeds it when `loading` is true) |
+| `VJoyButton` | Primary/secondary actions in `panel-action` or `panel-title-action` |