@nxgt/material-vue 0.21.0 → 0.22.0

package/docs/components/feedback-and-status.md

@@ -0,0 +1,643 @@
+# Feedback & status
+
+Components that tell the user what is happening: inline messages, blocking
+confirmations, progress, loading placeholders, toasts and a notification
+centre. Everything is imported from `@nxgt/material-vue/components`.
+
+| | Component | What it does |
+| --- | --- | --- |
+| <img src="../previews/feedback-status-alert.webp" width="96" alt=""> | [Alert](#alert) | Callout with icon, title and description in seven tones |
+| <img src="../previews/feedback-status-banner.webp" width="96" alt=""> | [Banner](#banner) | Dismissible banner with an action |
+| <img src="../previews/feedback-status-alertdialog.webp" width="96" alt=""> | [AlertDialog](#alertdialog) | Parts for a blocking confirmation dialog |
+| <img src="../previews/feedback-status-confirmdialog.webp" width="96" alt=""> | [ConfirmDialog](#confirmdialog) | Confirm / cancel dialog, `ConfirmationDialog`, `CustomAlertDialog` |
+| <img src="../previews/feedback-status-customdialog.webp" width="96" alt=""> | [CustomDialog](#customdialog) | Ready-made dialog with trigger, icon, title, body and footer |
+| <img src="../previews/feedback-status-emptystate.webp" width="96" alt=""> | [EmptyState](#emptystate) | Icon, title, description and action, with presets |
+| <img src="../previews/feedback-status-progress.webp" width="96" alt=""> | [Progress](#progress) | Linear bar, circular ring and labelled progress field |
+| <img src="../previews/feedback-status-scrollprogress.webp" width="96" alt=""> | [ScrollProgress](#scrollprogress) | Hairline tracking the window or a scrollable element |
+| <img src="../previews/feedback-status-spinner.webp" width="96" alt=""> | [Spinner](#spinner) | Loading spinner in several styles and colours |
+| <img src="../previews/feedback-status-toast.webp" width="96" alt=""> | [Toast](#toast) | Sonner toasts with icon, action and semantic presets |
+| <img src="../previews/feedback-status-skeleton.webp" width="96" alt=""> | [Skeleton](#skeleton) | Loading placeholder and ready-made shapes |
+| <img src="../previews/feedback-status-hydrateloading.webp" width="96" alt=""> | [HydrateLoading](#hydrateloading) | Full-area spinner shown while hydrating |
+| <img src="../previews/feedback-status-notifications.webp" width="96" alt=""> | [Notifications](#notifications) | Notification centre as a bell popover or an inline panel |
+
+## Alert
+
+![Alert](../previews/feedback-status-alert.webp)
+
+Callout with icon, title and description in seven tones.
+
+```vue
+<script setup lang="ts">
+import { Alert } from '@nxgt/material-vue/components';
+import { CircleAlert } from '@lucide/vue';
+</script>
+
+<template>
+  <Alert
+    variant="warning"
+    title="Check the address"
+    description="The postcode does not match the city."
+  >
+    <template #icon><CircleAlert /></template>
+  </Alert>
+</template>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `variant` | `'primary' \| 'secondary' \| 'success' \| 'info' \| 'warning' \| 'error' \| 'foreground'` | `'primary'` | left border, tint and icon colour |
+| `#icon` slot | — | — | shown before the text; no default icon |
+| `title` / `#title` | `string` / slot | — | bold first line |
+| `description` / `#description` | `string` / slot | — | muted body text |
+
+The default slot is rendered under the description.
+
+**Storybook:** `Feedback & status/Alert` · **React:** `Alert`
+
+---
+
+## Banner
+
+![Banner](../previews/feedback-status-banner.webp)
+
+Dismissible info / success / warning / error banner with an action.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Banner, Button } from '@nxgt/material-vue/components';
+
+const open = ref(true);
+</script>
+
+<template>
+  <Banner
+    v-if="open"
+    tone="warning"
+    title="Payment method expires soon"
+    description="Update the card on file to avoid a service interruption."
+    dismissible
+    @dismiss="open = false"
+  >
+    <template #action>
+      <Button variant="outlined" color="warning">Update</Button>
+    </template>
+  </Banner>
+</template>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `tone` | `'info' \| 'success' \| 'warning' \| 'error'` | `'info'` | colours and the default icon |
+| `#icon` slot | — | the tone's icon | replaces the default icon |
+| `#action` slot | — | — | rendered at the end of the banner |
+| `dismissible` | `boolean` | `false` | shows a close button that emits `dismiss`; the banner does not hide itself |
+
+Where React shows the close button when `onDismiss` is passed, Vue asks for
+`dismissible` and `@dismiss`. The banner has `role="status"`. It stays mounted
+until you stop rendering it.
+
+**Emits:** `dismiss` — no payload.
+**Storybook:** `Feedback & status/Banner` · **React:** `Banner`
+
+---
+
+## AlertDialog
+
+![AlertDialog](../previews/feedback-status-alertdialog.webp)
+
+Parts for a blocking confirmation dialog.
+
+```vue
+<script setup lang="ts">
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+  Button,
+} from '@nxgt/material-vue/components';
+
+function update() {}
+</script>
+
+<template>
+  <AlertDialog>
+    <AlertDialogTrigger as-child>
+      <Button variant="outlined">Update</Button>
+    </AlertDialogTrigger>
+    <AlertDialogContent>
+      <AlertDialogHeader>
+        <AlertDialogTitle>New software update available</AlertDialogTitle>
+        <AlertDialogDescription>
+          Update to the latest version to continue using the app.
+        </AlertDialogDescription>
+      </AlertDialogHeader>
+      <AlertDialogFooter>
+        <AlertDialogCancel>Later</AlertDialogCancel>
+        <AlertDialogAction @click="update">Update now</AlertDialogAction>
+      </AlertDialogFooter>
+    </AlertDialogContent>
+  </AlertDialog>
+</template>
+```
+
+Parts: `AlertDialog`, `AlertDialogTrigger`, `AlertDialogContent`,
+`AlertDialogHeader`, `AlertDialogTitle`, `AlertDialogDescription`,
+`AlertDialogFooter`, `AlertDialogAction`, `AlertDialogCancel`.
+`AlertDialogAction` takes the `Button` `variant` and `color`;
+`AlertDialogCancel` is always `outlined`. `default-open` and `v-model:open` go
+on `AlertDialog`. Vue exports no `AlertDialogOverlay` / `AlertDialogPortal`:
+the content brings both.
+On open, `AlertDialogContent` focuses `AlertDialogCancel`, the least
+destructive action (its first control when there is no Cancel, the content
+when there is none); an `@open-auto-focus` that calls `event.preventDefault()`
+keeps focus where it was. After that opt-out the Cancel takes no focus until the next
+task: focus it from a `setTimeout`, not in the handler.
+
+**Emits:** `update:open` on `AlertDialog` — `boolean`.
+**Storybook:** `Feedback & status/AlertDialog` · **React:** `AlertDialog` (same parts)
+
+---
+
+## ConfirmDialog
+
+![ConfirmDialog](../previews/feedback-status-confirmdialog.webp)
+
+Controlled confirm / cancel dialog. `ConfirmationDialog` brings its own
+trigger and icon; `CustomAlertDialog` is the free-form alert-dialog variant.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Button, ConfirmDialog } from '@nxgt/material-vue/components';
+
+const open = ref(false);
+
+async function remove() {
+  const response = await fetch('/api/projects/42', { method: 'DELETE' });
+  if (!response.ok) throw new Error('The project could not be deleted.');
+}
+</script>
+
+<template>
+  <Button color="error" @click="open = true">Delete</Button>
+  <ConfirmDialog
+    v-model:open="open"
+    variant="destructive"
+    title="Delete project?"
+    description="This cannot be undone."
+    confirm-label="Delete"
+    @confirm="remove"
+  />
+</template>
+```
+
+| Prop (`ConfirmDialog`) | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `v-model:open` | `boolean` | — (required) | controlled only |
+| `title` / `description` | `string` | — (required) | the dialog text |
+| `@confirm` (prop `on-confirm`) | `() => void \| Promise<void>` | — | awaited with the dialog open and both buttons disabled; closes on success; on a throw or rejection the dialog stays open and shows the error's message, or the translated `material.confirm-dialog.failed` ("The action failed.") when it has none |
+| `variant` | `'default' \| 'destructive'` | `'default'` | `destructive` paints the confirm button `error` |
+| `loading` | `boolean` | `false` | disables both buttons and shows the translated `material.confirm-dialog.processing` label, as a pending `@confirm` does |
+| `confirm-label` / `cancel-label` | `string` | "Confirm" / "Cancel", translated (`material.confirm-dialog.confirm` / `.cancel`) | button text |
+
+`on-confirm` is a function prop, so `@confirm="fn"` binds it as before and its
+promise is awaited; a plain `@confirm="open = false"` keeps working. The error
+clears when the dialog opens again.
+
+![ConfirmationDialog](../previews/feedback-status-confirmationdialog.webp)
+
+`ConfirmationDialog` has its own trigger slot and open state and a tonal icon:
+
+```vue
+<script setup lang="ts">
+import { Button, ConfirmationDialog } from '@nxgt/material-vue/components';
+
+function archive() {}
+</script>
+
+<template>
+  <ConfirmationDialog
+    title="Archive order"
+    description="The customer is told the order was archived."
+    confirm-text="Archive"
+    @confirm="archive"
+  >
+    <template #trigger>
+      <Button variant="outlined">Archive</Button>
+    </template>
+  </ConfirmationDialog>
+</template>
+```
+
+| Prop (`ConfirmationDialog`) | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `#trigger` slot | — | — | becomes the dialog trigger (`as-child`, no extra button): pass one element, such as a `Button` |
+| `v-model:open` | `boolean` | uncontrolled | open state; without it the dialog keeps its own |
+| `@confirm` | `() => void` | — | emitted on confirm; the dialog then closes |
+| `color` | `IconButton` colour | `'warning'` | icon and both buttons |
+| `variant` | `IconButton` variant | `'tonal'` | the icon's button style |
+| `#icon` slot | — | info icon, in a decorative `aria-hidden` badge | replaces the badge: keep yours decorative (`<IconButton as="span" aria-hidden="true">`), not a button that does nothing |
+| `confirm-text` / `cancel-text` | `string` | "Confirm" / "Cancel", translated (`material.confirm-dialog.confirm` / `.cancel`) | button text |
+
+Vue's `ConfirmationDialog` has no `formOptions`: to collect values before
+confirming, put a form in its default slot or use `CustomDialog`.
+
+![CustomAlertDialog](../previews/feedback-status-customalertdialog.webp)
+
+`CustomAlertDialog` is the alert-dialog twin of [CustomDialog](#customdialog):
+same `#trigger`, `#icon`, `title`, `description`, `#footer` and default slot,
+but built on `AlertDialog`, so it does not close on an outside click. Put
+`AlertDialogCancel` / `AlertDialogAction` in its `#footer`. Its trigger is
+`as-child`, so a `Button` goes straight in.
+
+**Storybook:** `Feedback & status/ConfirmDialog`, `Feedback & status/ConfirmationDialog`,
+`Feedback & status/CustomAlertDialog` · **React:** `ConfirmDialog`, `ConfirmationDialog`, `CustomAlertDialog`
+
+---
+
+## CustomDialog
+
+![CustomDialog](../previews/feedback-status-customdialog.webp)
+
+Ready-made dialog with trigger, icon, title, body and footer.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Button, CustomDialog, IconButton } from '@nxgt/material-vue/components';
+import { Atom } from '@lucide/vue';
+
+const open = ref(false);
+function send() {
+  open.value = false;
+}
+</script>
+
+<template>
+  <Button variant="outlined" @click="open = true">Invite</Button>
+  <CustomDialog
+    v-model:open="open"
+    title="Invite a teammate"
+    description="They get access to this workspace."
+  >
+    <template #icon>
+      <!-- Decoration: a <span> hidden from screen readers, not a button. -->
+      <IconButton as="span" variant="tonal" aria-hidden="true"><Atom /></IconButton>
+    </template>
+    <p class="text-sm text-muted-foreground">Invites expire after 7 days.</p>
+    <template #footer>
+      <Button @click="send">Send invite</Button>
+    </template>
+  </CustomDialog>
+</template>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `#trigger` slot | — | — | becomes the dialog trigger (`as-child`, no extra button): pass one element, such as a `Button` |
+| `#icon` slot | — | — | above the title |
+| `title` / `description` | `string` (or `#title` / `#description`) | — | hidden when empty |
+| `#footer` slot | — | — | after a separator; omitted when empty |
+| `v-model:open` / `default-open` | `boolean` | uncontrolled | control it from outside |
+
+The dialog also shows `DialogContent`'s own top-right X.
+
+Instead of controlling it, let the `#trigger` slot open it. Its content is the
+trigger itself (`as-child`), so put a single element there, not text:
+
+```vue
+<script setup lang="ts">
+import { Button, CustomDialog } from '@nxgt/material-vue/components';
+</script>
+
+<template>
+  <CustomDialog title="Invite a teammate">
+    <template #trigger>
+      <Button variant="outlined">Invite</Button>
+    </template>
+    <p class="text-sm text-muted-foreground">Invites expire after 7 days.</p>
+  </CustomDialog>
+</template>
+```
+
+In 0.21.0 and earlier the slot was wrapped in a `<button>`, so a `Button`
+there rendered a button inside a button; code that passed plain text or a bare
+icon for that reason now needs an element such as a `Button` or `IconButton`.
+
+**Emits:** `update:open` — `boolean`.
+**Storybook:** `Feedback & status/CustomDialog` · **React:** `CustomDialog`
+
+---
+
+## EmptyState
+
+![EmptyState](../previews/feedback-status-emptystate.webp)
+
+Icon in a tinted well, title, description and action; not-found,
+unauthorized, generic, empty, offline, search and maintenance presets.
+
+```vue
+<script setup lang="ts">
+import { Button, EmptyState } from '@nxgt/material-vue/components';
+
+function clearFilters() {}
+</script>
+
+<template>
+  <EmptyState variant="search">
+    <template #action>
+      <Button variant="outlined" @click="clearFilters">Clear filters</Button>
+    </template>
+  </EmptyState>
+</template>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `variant` | `'not-found' \| 'unauthorized' \| 'generic' \| 'empty' \| 'offline' \| 'search' \| 'maintenance'` | `'generic'` | preset icon, well colour, title and description |
+| `#icon` slot | — | the preset's | replaces the icon |
+| `title` / `description` | `string` (or `#title` / `#description`) | the preset's (translated) | replace the preset text |
+| `#action` slot | — | — | shown under the text |
+
+**Storybook:** `Feedback & status/EmptyState` · **React:** `EmptyState`
+
+---
+
+## Progress
+
+![Progress](../previews/feedback-status-progress.webp)
+
+Linear bar, circular ring with a label, and a labelled progress field.
+
+```vue
+<script setup lang="ts">
+import { CircularProgress, Progress, ProgressField } from '@nxgt/material-vue/components';
+</script>
+
+<template>
+  <Progress :model-value="42" />
+  <ProgressField label="Upload" :value="42" helper-text="Sending documents…" />
+  <CircularProgress :value="72" show-label :render-label="(value) => `${value}%`" />
+</template>
+```
+
+![CircularProgress](../previews/feedback-status-circularprogress.webp)
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `model-value` (`Progress`) | `number` 0–100 | `0` | fill of the bar |
+| `pulse` (`Progress`) | `boolean` | `true` | pulses the indicator |
+| `value` / `max` (`ProgressField`) | `number` | `0` / `100` | percentage shown and filled |
+| `label` / `helper-text` (`ProgressField`) | `string` | — | above and below the bar |
+| `variant` (`CircularProgress`) | `'primary' \| 'secondary' \| 'success' \| 'info' \| 'warning' \| 'error' \| 'default'` | `'primary'` | ring colour |
+| `size` (`CircularProgress`) | `number` | `100` | diameter in px |
+| `show-label` / `render-label` | `boolean` / `(value) => number \| string` | — | text in the centre |
+| `shape` (`CircularProgress`) | `'round' \| 'square'` | `'round'` | stroke line cap |
+
+The bar's value is `model-value` in Vue (Reka's progress), `value` in React.
+Types: `ProgressFieldProps`, `CircularProgressProps`.
+
+**Storybook:** `Feedback & status/Progress`, `Feedback & status/CircularProgress` · **React:** `Progress`, `CircularProgress`, `ProgressField`
+
+---
+
+## ScrollProgress
+
+![ScrollProgress](../previews/feedback-status-scrollprogress.webp)
+
+Hairline that tracks the window or a scrollable `target` (VueUse
+`useWindowScroll` / `useScroll`). `DocProgress` composes it.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { ScrollProgress } from '@nxgt/material-vue/components';
+
+const pane = ref<HTMLElement | null>(null);
+</script>
+
+<template>
+  <div class="relative h-80 overflow-hidden rounded border">
+    <ScrollProgress :target="pane" class="top-0 bottom-auto" />
+    <div ref="pane" class="h-full overflow-auto p-4">…</div>
+  </div>
+</template>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `target` | `HTMLElement \| null` | — (the window) | element whose scroll is tracked; pass the template ref |
+| `aria-label` | `string` | `'Scroll progress'` (`material.scroll-progress`, translated) | the `role="progressbar"`'s name; your value wins |
+
+Without `target` it follows the window: put it at the bottom of a sticky
+header (`<header class="sticky top-0 relative">…<ScrollProgress /></header>`).
+
+**Storybook:** `Feedback & status/ScrollProgress` · **React:** `ScrollProgress`
+
+---
+
+## Spinner
+
+![Spinner](../previews/feedback-status-spinner.webp)
+
+Loading spinner in several styles and colours.
+
+```vue
+<script setup lang="ts">
+import { Spinner } from '@nxgt/material-vue/components';
+</script>
+
+<template>
+  <Spinner variant="2" color="success" class="size-8" />
+</template>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `variant` | `'1' \| '2' \| '3' \| '4'` | `'1'` | ring style |
+| `color` | `'primary' \| 'secondary' \| 'success' \| 'info' \| 'warning' \| 'error' \| 'default' \| 'light'` | `'primary'` | ring colour |
+| `aria-label` (attribute) | `string` | `'Loading...'` (`material.spinner.loading`, translated) | accessible name of `variant="4"`, the only variant with one (`role="img"`); your value wins |
+
+Size it with `class` (`size-6`, `size-8`…).
+
+**Storybook:** `Feedback & status/Spinner` · **React:** `Spinner`
+
+---
+
+## Toast
+
+![Toast](../previews/feedback-status-toast.webp)
+
+Sonner toasts with icon and action. `toasts` provides `success` / `error` /
+`warning` / `info` / `loading` presets.
+
+```vue
+<script setup lang="ts">
+import { Button, Toaster, toast, toasts } from '@nxgt/material-vue/components';
+
+function send() {
+  toasts.success({ description: 'Invoice sent' });
+}
+
+function notify() {
+  toast({
+    title: 'New reply',
+    description: 'Alex answered your comment.',
+    action: { label: 'Open', onClick: () => {} },
+  });
+}
+
+async function upload() {
+  const id = toasts.loading({ title: 'Uploading…' });
+  // …
+  toasts.dismiss(id);
+}
+</script>
+
+<template>
+  <!-- once, near the root -->
+  <Toaster />
+  <Button @click="send">Send</Button>
+</template>
+```
+
+| Option | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `title` / `description` | `string` | preset title for `success`, `error`, `loading` | toast text |
+| `icon` | a VNode (`toast`) · icon name (`toasts.*`) | preset icon | leading icon |
+| `action` | `{ label, onClick? }` or `(dismiss) => VNode` | a translated "Close" for `success`, `info`, `error` | trailing button |
+| `options` | vue-sonner `ExternalToast` | `duration: 5000` for presets, `Infinity` for `loading` | passed to Sonner (`id`, `duration`, `position`…) |
+
+The toast id defaults to the title, so two toasts with the same title
+replace each other; pass `options: { id }` to show both. `Toaster` is
+vue-sonner's and takes its props (`position`, `expand`, `rich-colors`…);
+vue-sonner's stylesheet comes with this package's (`styles.css`, or the
+compiled stylesheet). `Toast` is the component each toast
+renders, and `sonnerToast` is vue-sonner's own `toast`, for anything the
+presets do not cover.
+
+**Storybook:** `Feedback & status/Toast` · **React:** `Toaster`, `toast`, `toasts`, `Toast`
+
+---
+
+## Skeleton
+
+![Skeleton](../previews/feedback-status-skeleton.webp)
+
+Loading placeholder and ready-made shapes.
+
+```vue
+<script setup lang="ts">
+import {
+  Skeleton,
+  SkeletonAvatar,
+  SkeletonCard,
+  SkeletonTable,
+  SkeletonText,
+} from '@nxgt/material-vue/components';
+</script>
+
+<template>
+  <Skeleton class="h-4 w-40" />
+  <SkeletonAvatar size="lg" />
+  <SkeletonText :lines="4" />
+  <SkeletonCard />
+  <SkeletonTable :rows="4" :columns="4" />
+</template>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `lines` (`SkeletonText`) | `number` | `3` | number of text bars |
+| `size` (`SkeletonAvatar`) | `'sm' \| 'md' \| 'lg'` | `'md'` | 24, 32 or 48 px |
+| `labelled` (`SkeletonText`, `SkeletonAvatar`) | `boolean` | `true` | `role="status"` with a translated label; `false` hides it from assistive tech |
+| `rows` / `columns` (`SkeletonTable`) | `number` | `5` / `4` | table shape |
+
+`Skeleton` itself is a pulsing block sized with `class`.
+
+**Storybook:** `Feedback & status/Skeleton` · **React:** `Skeleton` (same parts)
+
+---
+
+## HydrateLoading
+
+![HydrateLoading](../previews/feedback-status-hydrateloading.webp)
+
+Full-area spinner shown while hydrating.
+
+```vue
+<script setup lang="ts">
+import { HydrateLoading } from '@nxgt/material-vue/components';
+</script>
+
+<template>
+  <HydrateLoading>
+    <p class="mb-4 text-sm text-muted-foreground">Loading your workspace…</p>
+  </HydrateLoading>
+</template>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `#icon` slot | — | `<Spinner class="size-8" />` | replaces the spinner |
+| default slot | — | — | shown above the spinner |
+| `class` | `string` | — | the root fills the viewport (`size-lv`); override to box it |
+
+**Storybook:** `Feedback & status/HydrateLoading` · **React:** `HydrateLoading`
+
+---
+
+## Notifications
+
+![Notifications](../previews/feedback-status-notifications.webp)
+
+Notification centre as a bell popover with an unread count, or as an inline
+panel, with filters and read / dismiss.
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { Notifications, type NotificationItem } from '@nxgt/material-vue/components';
+
+const props = defineProps<{ initial: NotificationItem[] }>();
+const items = ref(props.initial);
+
+function read(id: string) {
+  items.value = items.value.map((item) => (item.id === id ? { ...item, read: true } : item));
+}
+function readAll() {
+  items.value = items.value.map((item) => ({ ...item, read: true }));
+}
+function dismiss(id: string) {
+  items.value = items.value.filter((item) => item.id !== id);
+}
+</script>
+
+<template>
+  <Notifications :items="items" @read="read" @read-all="readAll" @dismiss="dismiss" />
+</template>
+```
+
+| Prop | Type | Default | Effect |
+| --- | --- | --- | --- |
+| `items` | `NotificationItem[]` | — (required) | `id`, `title`, `description`, `tone`, `createdAt`, `read`, `href`, `category`… |
+| `variant` | `'popover' \| 'panel'` | `'popover'` | bell with a popover, or the list inline |
+| `@read` / `@read-all` / `@dismiss` | `(id: string) => void` / `() => void` / `(id: string) => void` | — | the component never mutates `items`; update them yourself. The read-all and dismiss buttons only show when their listener is bound |
+| `@item-click` | `(item: NotificationItem) => void` | — | click on a row |
+| `default-filter` / `filter` | `'all' \| 'unread'` | `'all'` | read filter, uncontrolled or controlled |
+| `default-category` / `category` | `string \| null` | — | category filter; tabs appear when items have categories |
+| `v-model:open` / `default-open` | `boolean` | — | popover state |
+| `toast-on-arrival` | `boolean` | `false` | shows a toast for each new item (needs a `Toaster`) |
+
+The listeners are callback props (`onRead`, `onReadAll`, `onDismiss`,
+`onItemClick`), so `@read` and `:on-read` are the same thing.
+
+**Emits:** `update:open` — `boolean`.
+**Storybook:** `Feedback & status/Notifications` · **React:** `Notifications`