@nuxtseo/design-system 0.1.0 → 0.1.2

package/app/components/element/UiSkeleton.vue

@@ -10,6 +10,7 @@ defineOptions({ inheritAttrs: false })
 const {
   type = 'text',
   lines = 1,
+  count = 1,
   index = 0,
   base = 160,
   range = 80,
@@ -20,10 +21,16 @@ const {
    * decide the box — use it whenever the placeholder must match a known layout
    * (a `w-full` row, a fixed-width label). The self-sizing types write an inline
    * `width`/`height`, which silently beats any `w-*`/`h-*` class passed in.
+   *
+   * The presets draw a whole page-level loading shape: `table-row` (a name
+   * column and three value columns), `stat` (stat blocks in a grid), `chart`
+   * (16 bars), and `card` (two-column cards). `count` sets how many.
    */
-  type?: 'text' | 'bar' | 'circle' | 'block'
+  type?: 'text' | 'bar' | 'circle' | 'block' | 'table-row' | 'stat' | 'chart' | 'card'
   /** Number of skeleton lines (text type only) */
   lines?: number
+  /** Number of rows, stat blocks, or cards (presets only). The chart always draws 16 bars. */
+  count?: number
   /** Seed index for deterministic width/height variation */
   index?: number
   /** Base size in px — text: width, bar: height percent, circle: diameter */
@@ -94,6 +101,48 @@ function barHeight(i: number): string {
     class="ui-skeleton rounded-full"
     :style="{ width: `${base}px`, height: `${base}px` }"
   />
+
+  <!-- Preset: table rows, a name column then three value columns -->
+  <div v-else-if="type === 'table-row'" aria-hidden="true" v-bind="attrs" class="space-y-2">
+    <div
+      v-for="i in count"
+      :key="i"
+      class="grid grid-cols-[minmax(120px,2fr)_repeat(3,minmax(56px,1fr))] items-center gap-3"
+    >
+      <div class="ui-skeleton rounded h-3 max-w-full" :style="{ width: textWidth(i) }" />
+      <div class="ui-skeleton rounded h-3 w-full" />
+      <div class="ui-skeleton rounded h-3 w-2/3 justify-self-end" />
+      <div class="ui-skeleton rounded h-3 w-1/2 justify-self-end" />
+    </div>
+  </div>
+
+  <!-- Preset: stat blocks -->
+  <div v-else-if="type === 'stat'" aria-hidden="true" v-bind="attrs" class="grid gap-3 sm:grid-cols-2 lg:grid-cols-4">
+    <div v-for="i in count" :key="i" class="space-y-2 rounded-lg border border-default bg-muted p-3">
+      <div class="ui-skeleton rounded h-3 w-20" />
+      <div class="ui-skeleton rounded h-6 max-w-full" :style="{ width: textWidth(i + 10) }" />
+      <div class="ui-skeleton rounded h-3 w-24" />
+    </div>
+  </div>
+
+  <!-- Preset: a bar chart -->
+  <div v-else-if="type === 'chart'" aria-hidden="true" v-bind="attrs" class="flex h-56 items-end gap-2">
+    <div
+      v-for="i in 16"
+      :key="i"
+      class="ui-skeleton rounded flex-1"
+      :style="{ height: barHeight(i) }"
+    />
+  </div>
+
+  <!-- Preset: cards -->
+  <div v-else-if="type === 'card'" aria-hidden="true" v-bind="attrs" class="grid gap-3 sm:grid-cols-2">
+    <div v-for="i in count" :key="i" class="space-y-3 rounded-lg border border-default bg-muted p-4">
+      <div class="ui-skeleton rounded h-4 max-w-full" :style="{ width: textWidth(i) }" />
+      <div class="ui-skeleton rounded h-3 w-full" />
+      <div class="ui-skeleton rounded h-3 w-2/3" />
+    </div>
+  </div>
 </template>
 
 <!--

package/app/components/element/UiTooltip.vue

@@ -87,6 +87,12 @@ function captureChildTrigger(event: Event): void {
     childTriggerElement.value = event.currentTarget
 }
 
+// One object, not two `@` listeners: gscdump.com's TypeScript 7.1 native
+// typecheck rejected `@pointermove` and `@focus` on reka's `TooltipTrigger`.
+// Listeners bound through `v-bind` fall through to the rendered root the same
+// way.
+const childTriggerListeners = { onPointermove: captureChildTrigger, onFocus: captureChildTrigger }
+
 // Span trigger. Reka listens for `focus` on the trigger itself, and focus does
 // not bubble, so a focusable child (a button, a link, a tabindex cell) never
 // opened the tooltip and the description landed on the span. Listen for
@@ -231,8 +237,7 @@ export const sizes = {
         v-if="$slots.default && triggerAs === 'child'"
         :reference="childTriggerElement"
         as-child
-        @pointermove="captureChildTrigger"
-        @focus="captureChildTrigger"
+        v-bind="childTriggerListeners"
       >
         <slot />
       </TooltipTrigger>

package/app/components/element/UiTrend.vue

@@ -1,6 +1,7 @@
 <script setup lang="ts">
 import { computed } from 'vue'
 import { UiIcon } from '#components'
+import { readDesignSystemConfig } from '../../composables/design-system-config'
 import { clamp } from '../../utils/number'
 
 const {
@@ -10,7 +11,7 @@ const {
   format = 'number',
   showSign = false,
   inverted = false,
-  colored = false,
+  colored = undefined,
   isNew = false,
   isLost = false,
   autoLost = true,
@@ -29,7 +30,8 @@ const {
   /**
    * Trend color budget (DESIGN.md Composition): colored success/error trends
    * belong to the hero zone only. Default renders neutral (sign + value);
-   * hero components (UiMetricsRow, UiMetricStat, hero cards) opt in.
+   * hero components (UiMetricsRow, UiMetricStat, hero cards) opt in. A site
+   * that colours every trend sets `designSystem.trend.colored` in app.config.
    */
   colored?: boolean
   /** Show a "NEW" badge instead of trend value */
@@ -51,15 +53,21 @@ const {
   precision?: number | 'auto'
 }>()
 
+// `2xs` and `xs` read the type seam (`--ui-trend-2xs-size`, `--ui-trend-xs-size`).
 const sizes = {
-  '2xs': 'text-mini',
-  'xs': 'text-xs',
+  '2xs': 'ui-trend-2xs',
+  'xs': 'ui-trend-xs',
   'sm': 'text-sm',
   'md': 'text-base',
   'lg': 'text-lg',
   'xl': 'text-xl',
 } as const
 
+// An unset prop takes the site's default. Nuxt SEO's app.config sets none, so
+// its trends stay neutral (DESIGN.md, trend colour budget).
+const siteColored = readDesignSystemConfig().trend?.colored ?? false
+const isColored = computed(() => colored ?? siteColored)
+
 const numericValue = computed(() => typeof value === 'string' ? Number.parseFloat(value) : value)
 
 // Auto-detect "lost" state: percent format and value <= -100 means went to zero
@@ -78,7 +86,7 @@ const clampsValue = computed(() => shouldClamp && format === 'percent')
 
 const trendColor = computed(() => {
   const t = trend.value
-  if (t === 0 || !colored)
+  if (t === 0 || !isColored.value)
     return 'text-muted'
   const positive = inverted ? t === -1 : t === 1
   return positive ? 'text-success' : 'text-error'
@@ -144,11 +152,11 @@ const classes = computed(() => {
 
 <template>
   <!-- NEW badge mode -->
-  <span v-if="isNew" data-ui="UiTrend" class="inline-flex items-center font-medium uppercase px-1.5 py-0.5 rounded bg-success/10 text-success" :class="sizes[size as keyof typeof sizes]">
+  <span v-if="isNew" data-ui="UiTrend" class="inline-flex items-center font-medium [text-transform:var(--ui-trend-badge-case,uppercase)] px-1.5 py-0.5 rounded bg-success/10 text-success" :class="sizes[size as keyof typeof sizes]">
     New
   </span>
   <!-- LOST badge mode (explicit or auto-detected from -100% change) -->
-  <span v-else-if="isLost || detectedLost" data-ui="UiTrend" class="inline-flex items-center font-medium uppercase px-1.5 py-0.5 rounded bg-error/10 text-error" :class="sizes[size as keyof typeof sizes]">
+  <span v-else-if="isLost || detectedLost" data-ui="UiTrend" class="inline-flex items-center font-medium [text-transform:var(--ui-trend-badge-case,uppercase)] px-1.5 py-0.5 rounded bg-error/10 text-error" :class="sizes[size as keyof typeof sizes]">
     Lost
   </span>
   <!-- Zero trend — show dash -->
@@ -158,7 +166,7 @@ const classes = computed(() => {
     v-else-if="isClamped"
     data-ui="UiTrend"
     class="inline-flex items-center whitespace-nowrap leading-none font-semibold tracking-tight px-1.5 py-0.5 ml-1 rounded cursor-default"
-    :class="[classes, colored ? (trend === 1 ? 'bg-success/10' : 'bg-error/10') : 'bg-muted']"
+    :class="[classes, isColored ? (trend === 1 ? 'bg-success/10' : 'bg-error/10') : 'bg-muted']"
     :title="fullValue"
   >
     {{ trend === 1 ? '10x+' : 'oof' }}

package/app/components/element/onboarding-answers.ts

@@ -44,6 +44,31 @@ export const ONBOARDING_QUESTIONS = {
   intents: 'What do you want to do with Nuxt SEO Pro?',
 } as const
 
+/**
+ * Every string `UiOnboardingAnswers` renders besides the option labels. COPY.md
+ * (Onboarding About you) owns the defaults. A site that extends the layer
+ * passes its own through the component's `copy` prop, one key or all of them.
+ */
+export interface OnboardingAnswersCopy {
+  roleQuestion: string
+  siteCountQuestion: string
+  seoExperienceQuestion: string
+  intentsQuestion: string
+  intentsHint: string
+  otherLabel: string
+  otherPlaceholder: string
+}
+
+export const ONBOARDING_ANSWERS_COPY: Readonly<OnboardingAnswersCopy> = {
+  roleQuestion: ONBOARDING_QUESTIONS.role,
+  siteCountQuestion: ONBOARDING_QUESTIONS.siteCount,
+  seoExperienceQuestion: ONBOARDING_QUESTIONS.seoExperience,
+  intentsQuestion: ONBOARDING_QUESTIONS.intents,
+  intentsHint: 'Pick any that fit.',
+  otherLabel: 'Anything else? Optional.',
+  otherPlaceholder: 'Tell us what you\'re after',
+}
+
 /** Label lookup for stored ids. An unknown id renders as itself. */
 export function onboardingAnswerLabel(options: readonly { id: string, label: string }[], id: string): string {
   return options.find(option => option.id === id)?.label ?? id

package/app/composables/design-system-config.ts

@@ -0,0 +1,29 @@
+import type { FailureCopy, FailureCopyOverrides } from '../shared/failure-copy'
+import { tryUseNuxtApp, useAppConfig } from 'nuxt/app'
+import { resolveFailureCopy } from '../shared/failure-copy'
+
+/**
+ * The runtime brand seams a site sets under `designSystem` in app.config.
+ * README (Brand seams) documents each key. Unset keys keep Nuxt SEO's
+ * behaviour, so the layer's own app.config sets none of them.
+ */
+export interface DesignSystemAppConfig {
+  /** `UiTrend`'s `colored` when a caller passes none. Default false. */
+  readonly trend?: { readonly colored?: boolean }
+  /** `UiAtmosphere`'s grain and `bloom` mask when a caller passes none. Default off. */
+  readonly atmosphere?: { readonly grain?: boolean, readonly bloomMask?: boolean }
+  /** Rewords the failure copy (`FailureCopyOverrides`). */
+  readonly failureCopy?: FailureCopyOverrides
+}
+
+/** The site's `designSystem` app.config, or none outside a Nuxt app. Call it in setup. */
+export function readDesignSystemConfig(): DesignSystemAppConfig {
+  if (!tryUseNuxtApp())
+    return {}
+  return (useAppConfig().designSystem ?? {}) as DesignSystemAppConfig
+}
+
+/** The failure copy with the site's overrides applied. Call it in setup. */
+export function readFailureCopy(): FailureCopy {
+  return resolveFailureCopy(readDesignSystemConfig().failureCopy)
+}

package/app/composables/useConfirm.ts

@@ -1,3 +1,4 @@
+import type { VNodeChild } from 'vue'
 import { useOverlay } from '#imports'
 import UiConfirmDialog from '../components/element/UiConfirmDialog.vue'
 
@@ -13,6 +14,27 @@ export interface ConfirmOptions {
   readonly confirmLabel: string
   readonly cancelLabel?: string
   readonly tone?: ConfirmTone
+  /** Rich content under the description: `() => h('p', [h('strong', site.name), ' stops syncing.'])`. */
+  readonly body?: () => VNodeChild
+  /**
+   * The work to run on confirm. The dialog shows its loading state until the
+   * action settles, then closes. A rejected action rejects the returned
+   * promise with the same error.
+   */
+  readonly action?: () => Promise<unknown>
+}
+
+/** How the dialog closed. Nuxt UI's overlay hands it to `useConfirm()`. */
+export type ConfirmResult
+  = | { readonly _tag: 'Confirmed' }
+    | { readonly _tag: 'Cancelled' }
+    | { readonly _tag: 'ActionFailed', readonly error: unknown }
+
+/** Escape and a click outside close the overlay with no result. */
+function toAnswer(result: ConfirmResult | undefined): boolean {
+  if (result?._tag === 'ActionFailed')
+    throw result.error
+  return result?._tag === 'Confirmed'
 }
 
 /**
@@ -25,8 +47,14 @@ export interface ConfirmOptions {
  * ```
  *
  * Resolves `true` only for the confirm button. Cancel, Escape, and a click
- * outside resolve `false`. Call it in `setup`; the returned function may run
- * any time later. Needs `<UApp>`, which mounts Nuxt UI's overlay provider.
+ * outside resolve `false`. Pass `action` to run the work inside the dialog:
+ *
+ * ```ts
+ * await confirm({ title: 'Remove Site?', confirmLabel: 'Remove', action: () => removeSite(id) })
+ * ```
+ *
+ * Call it in `setup`; the returned function may run any time later. Needs
+ * `<UApp>`, which mounts Nuxt UI's overlay provider.
  */
 export function useConfirm(): (options: ConfirmOptions) => Promise<boolean> {
   const overlay = useOverlay()
@@ -34,5 +62,5 @@ export function useConfirm(): (options: ConfirmOptions) => Promise<boolean> {
   // a page that asks many times holds no dialog it is not showing.
   return options => overlay.create(UiConfirmDialog, { destroyOnClose: true })
     .open({ ...options })
-    .then(result => result === true)
+    .then(result => toAnswer(result as ConfirmResult | undefined))
 }

package/app/plugins/favicon.ts

@@ -1,29 +1,15 @@
 import { defineNuxtPlugin, useAppConfig, useHead } from 'nuxt/app'
 import { useColorMode } from '#imports'
+import { appFaviconLinks } from '../utils/app-favicon'
 
+// Emits the favicon and touch icon links that app.config's `favicon` names,
+// and swaps them with the colour mode. The layer ships no brand images, so an
+// app that sets no `favicon` gets no links from here.
 export default defineNuxtPlugin(() => {
   const { favicon } = useAppConfig()
   const colorMode = useColorMode()
 
-  useHead(() => {
-    const dark = colorMode.value === 'dark'
-
-    return {
-      link: [
-        {
-          id: 'favicon',
-          rel: 'icon',
-          type: 'image/png',
-          sizes: '32x32',
-          href: dark ? favicon.dark : favicon.light,
-        },
-        {
-          id: 'apple-touch-icon',
-          rel: 'apple-touch-icon',
-          sizes: '180x180',
-          href: dark ? favicon.appleTouchDark : favicon.appleTouchLight,
-        },
-      ],
-    }
-  })
+  useHead(() => ({
+    link: appFaviconLinks(favicon, colorMode.value === 'dark'),
+  }))
 })

package/app/shared/error-state.ts

@@ -1,5 +1,7 @@
+import type { FailureCopy } from './failure-copy'
 import type { UiIcon } from './ui-icons'
-import { toWidgetFailure, WIDGET_FAILURE_COPY } from './widget-failure'
+import { FAILURE_COPY } from './failure-copy'
+import { toWidgetFailure } from './widget-failure'
 
 /**
  * What `UiErrorState` is allowed to say, and where the words came from.
@@ -87,8 +89,6 @@ export interface ErrorStateView {
   readonly retryable: boolean
 }
 
-const GENERIC_NEXT_STEP = 'Try again in a moment. If it keeps happening, contact support.'
-
 function resetHint(source: { resetAt?: Date, retryAfter?: number }, now: number): string | null {
   if (source.retryAfter)
     return `Try again in ${source.retryAfter} seconds`
@@ -108,16 +108,17 @@ function resetHint(source: { resetAt?: Date, retryAfter?: number }, now: number)
 
 /**
  * Turn a source into the words on screen. Pure: pass the clock in, so the
- * reset hint is testable and the component owns no time.
+ * reset hint is testable and the component owns no time. Pass `copy` to use a
+ * site's reworded failures (`readFailureCopy()`).
  */
-export function resolveErrorState(source: ErrorStateSource, now: number): ErrorStateView {
+export function resolveErrorState(source: ErrorStateSource, now: number, copy: FailureCopy = FAILURE_COPY): ErrorStateView {
   if (source._tag === 'copy') {
     return {
       tone: 'error',
       icon: 'caution',
       title: source.title,
       detail: source.detail ?? null,
-      nextStep: { _tag: 'generic', text: GENERIC_NEXT_STEP },
+      nextStep: { _tag: 'generic', text: copy.nextStep },
       retryable: true,
     }
   }
@@ -127,24 +128,24 @@ export function resolveErrorState(source: ErrorStateSource, now: number): ErrorS
     return {
       tone: 'warning',
       icon: 'clock',
-      title: WIDGET_FAILURE_COPY['rate-limited'].title,
+      title: copy.failures['rate-limited'].title,
       detail: source.detail,
       nextStep: hint
         ? { _tag: 'timing', text: hint }
-        : { _tag: 'generic', text: WIDGET_FAILURE_COPY['rate-limited'].body },
+        : { _tag: 'generic', text: copy.failures['rate-limited'].body },
       retryable: true,
     }
   }
 
   const failure = toWidgetFailure(source.error)
-  const copy = WIDGET_FAILURE_COPY[failure._tag]
+  const failureCopy = copy.failures[failure._tag]
   const limited = failure._tag === 'rate-limited'
   return {
     tone: limited ? 'warning' : 'error',
     icon: limited ? 'clock' : 'caution',
-    title: copy.title,
-    detail: copy.body,
+    title: failureCopy.title,
+    detail: failureCopy.body,
     nextStep: null,
-    retryable: copy.retryable,
+    retryable: failureCopy.retryable,
   }
 }

package/app/shared/failure-copy.ts

@@ -0,0 +1,53 @@
+import type { WidgetFailureCopy, WidgetFailureTag } from './widget-failure'
+import { WIDGET_FAILURE_COPY } from './widget-failure'
+
+/**
+ * Every string the failure surfaces render: `UiWidgetState`, `UiDataList` and
+ * `UiErrorState`. COPY.md (Shared primitive assets) owns the defaults. A site
+ * that extends the layer rewords them through `designSystem.failureCopy` in its
+ * app.config. Whether a failure is retryable is behaviour, so no override
+ * reaches it.
+ */
+export interface FailureCopy {
+  readonly failures: Readonly<Record<WidgetFailureTag, WidgetFailureCopy>>
+  /** The retry button on `UiWidgetState` and `UiDataList`. */
+  readonly retryLabel: string
+  /** The retry button on `UiErrorState`. */
+  readonly errorStateRetryLabel: string
+  /** The next-step line `UiErrorState` shows under copy a caller wrote. */
+  readonly nextStep: string
+}
+
+/** What a site may reword. Each key it leaves out keeps the default. */
+export interface FailureCopyOverrides {
+  readonly failures?: { readonly [K in WidgetFailureTag]?: Partial<Pick<WidgetFailureCopy, 'title' | 'body'>> }
+  readonly retryLabel?: string
+  readonly errorStateRetryLabel?: string
+  readonly nextStep?: string
+}
+
+export const FAILURE_COPY: FailureCopy = {
+  failures: WIDGET_FAILURE_COPY,
+  retryLabel: 'Retry',
+  errorStateRetryLabel: 'Try again',
+  nextStep: 'Try again in a moment. If it keeps happening, contact support.',
+}
+
+const FAILURE_TAGS = Object.keys(WIDGET_FAILURE_COPY) as WidgetFailureTag[]
+
+/** Lay a site's overrides over the defaults. Pure, so a test passes its own. */
+export function resolveFailureCopy(overrides: FailureCopyOverrides | undefined): FailureCopy {
+  if (!overrides)
+    return FAILURE_COPY
+  const failures = Object.fromEntries(FAILURE_TAGS.map((tag) => {
+    const base = FAILURE_COPY.failures[tag]
+    const own = overrides.failures?.[tag]
+    return [tag, { title: own?.title ?? base.title, body: own?.body ?? base.body, retryable: base.retryable }]
+  })) as Record<WidgetFailureTag, WidgetFailureCopy>
+  return {
+    failures,
+    retryLabel: overrides.retryLabel ?? FAILURE_COPY.retryLabel,
+    errorStateRetryLabel: overrides.errorStateRetryLabel ?? FAILURE_COPY.errorStateRetryLabel,
+    nextStep: overrides.nextStep ?? FAILURE_COPY.nextStep,
+  }
+}

package/app/shared/stat.ts

@@ -0,0 +1,65 @@
+import type { SlotTextOptions } from '../utils/slot-text'
+import type { UiIcon as UiIconName } from './ui-icons'
+
+// `UiStat`'s props. They live in this module, not the SFC, so a consumer can
+// name them in its own `defineProps`: the Vue SFC compiler resolves a type
+// from a package `.ts` file and not from a package `.vue` file.
+
+type Datum = Record<string, number | string>
+
+export interface UiStatProps {
+  // link
+  to?: string
+
+  // label
+  icon?: UiIconName
+  title?: string
+  tooltip?: string
+  tooltipDescription?: string
+
+  // value
+  value?: string | number | null
+  suffix?: string
+  valueClass?: string
+  format?: (n: number) => string
+
+  // trend
+  trend?: number | null
+  /**
+   * Formats the trend magnitude. The value `format` never applies: the trend is
+   * a percent or a delta, so a currency formatter printed "+$12.5%".
+   */
+  trendFormat?: (n: number) => string
+  trendSuffix?: string
+  trendLabel?: string
+  invertTrend?: boolean
+  /**
+   * Trend color budget (DESIGN.md Composition): colored success/error trends
+   * belong to the hero zone only. Default renders neutral; `UiStats
+   * variant="cards"` (the hero pattern) opts its stats in automatically.
+   */
+  trendColored?: boolean
+
+  // sparkline
+  sparkline?: Datum[]
+
+  // sizing
+  size?: 'sm' | 'md' | 'lg'
+  /** Keep report-visible labels and deltas at the 14px readable tier. */
+  readableLabels?: boolean
+
+  // state
+  loading?: boolean
+
+  /**
+   * Rolls compact metric values when they change. Defaults on for numeric-ish
+   * values; pass false for dense/realtime surfaces or object options to tune.
+   */
+  animatedValue?: boolean | SlotTextOptions
+
+  // threshold alerting
+  status?: 'crisis' | 'warning' | 'good'
+
+  // render the value area inside a card, keeping the header outside
+  card?: boolean
+}

package/app/shared/table.ts

@@ -1,4 +1,4 @@
-import type { ColumnDef } from '@tanstack/table-core'
+import type { Cell, ColumnDef, Row, RowSelectionState } from '@tanstack/table-core'
 import {
   columnFilteringFeature,
   columnOrderingFeature,
@@ -103,3 +103,76 @@ export const uiTableVisibleFromClass: Record<UiTableVisibleFrom, string> = {
   'xl': 'hidden xl:table-cell',
   '2xl': 'hidden 2xl:table-cell',
 }
+
+/**
+ * `UiTable`'s props. They live in this module, not the SFC, so a consumer that
+ * wraps the table can name them in its own `defineProps`. The Vue SFC compiler
+ * resolves a type from a package `.ts` file; it cannot resolve one from a
+ * package `.vue` file.
+ */
+export interface UiTableProps<T extends object> {
+  data: T[]
+  columns: UiTableColumn<T>[]
+  selected?: RowSelectionState
+  controlledSelection?: boolean
+  rowHover?: boolean
+  rowClickable?: boolean
+  enableSorting?: boolean
+  /** Caller owns sort state; UiTable emits @sortColumn and bypasses client-side sorting. */
+  manualSorting?: boolean
+  pageSize?: number
+  ignoreHeader?: boolean
+  size?: UiTableSize
+  loading?: boolean
+  loadingRows?: number
+  rowId?: UiTableRowId<T>
+  manualPagination?: boolean
+  disablePagination?: boolean
+  total?: number
+  /** Accessible name for the table. Rendered as a visually-hidden <caption>. */
+  label: string
+  /** Draw the canonical rounded table surface. */
+  bordered?: boolean
+  /** Pagination density. Compact renders previous, page position, and next only. */
+  paginationPreset?: 'default' | 'compact'
+  /** Fill the caller's available height and keep pagination pinned to the bottom. */
+  fill?: boolean
+  /** Extra classes applied per data row — e.g. a selection highlight. */
+  rowClass?: (row: T) => string
+  /** Row id presented as the active item in a click-through table. */
+  activeRowId?: string
+  /** Row id to open when the table first receives deep-linked evidence. */
+  initialExpandedRowId?: string
+  /**
+   * Show Export CSV and Export JSON, saving to this file name without the
+   * extension. The export holds every filtered and sorted row, not one page.
+   * Ignored with `manualPagination`: mount `UiTableExport` with every row.
+   */
+  exportFilename?: string
+}
+
+/** What a `#<column id>-cell` slot receives: the TanStack row and cell, and the cell's value. */
+export interface UiTableCellSlotProps<T extends object> {
+  row: Row<UiTableFeatures, T>
+  cell: Cell<UiTableFeatures, T, unknown>
+  value: unknown
+}
+
+/**
+ * `UiTable`'s slots. A `#<column id>-cell` slot draws that column's cells and
+ * wins over the column's `cell` renderer. A column with no slot keeps its
+ * renderer. `#empty` replaces the zero-rows line.
+ */
+export type UiTableSlots<T extends object> = {
+  [K in `${string}-cell`]?: (props: UiTableCellSlotProps<T>) => unknown
+} & {
+  'empty'?: () => unknown
+  'expanded-component'?: (props: { row: T }) => unknown
+  'actions'?: (props: { row: T }) => unknown
+  'tfoot'?: () => unknown
+}
+
+/** The slot name that draws one column's cells. */
+export function uiTableCellSlotName(columnId: string): `${string}-cell` {
+  return `${columnId}-cell`
+}

package/app/shared/toast.ts

@@ -0,0 +1,52 @@
+import type { Component } from 'vue'
+import type { SemanticStatus } from '../composables/semanticColors'
+
+// `UiToast` and `UiToaster` props. They live in this module, not the SFCs, so
+// a consumer can name them in its own `defineProps`: the Vue SFC compiler
+// resolves a type from a package `.ts` file and not from a package `.vue` file.
+
+export interface ToastAction {
+  label: string
+  icon?: string
+  to?: string
+  onClick?: (e: MouseEvent) => void
+  /** Visual emphasis. `primary` = filled, `neutral` = quiet. */
+  color?: 'primary' | 'neutral'
+}
+
+export interface UiToastProps {
+  /** Heading text (string or a render component). */
+  title?: string | Component
+  /** Body text (string or a render component). */
+  description?: string | Component
+  /** Semantic status — drives accent + default icon. Wins over `color`. */
+  status?: SemanticStatus
+  /** Nuxt UI color compatibility for existing `toast.add({ color })` call sites. */
+  color?: 'primary' | 'secondary' | 'success' | 'info' | 'warning' | 'error' | 'neutral'
+  /** Icon override. Defaults to the status icon. */
+  icon?: string
+  /** Inline action buttons. */
+  actions?: ToastAction[]
+  /**
+   * Bug-report handler. When set, failure toasts (error/warning) that carry no
+   * action of their own get a "Report bug" button. Wired by the app (the
+   * design system must not reach for the feedback drawer itself).
+   */
+  reportBug?: (toast: { title?: string, description?: string }) => void
+  /** Show the close button. */
+  close?: boolean
+  /** Auto-dismiss progress 0..1 (remaining), or false to hide the bar. */
+  progress?: number | false
+  /** Collapsed back card — fade content so the deck reads as peeking cards. */
+  peek?: boolean
+}
+
+export interface UiToasterProps {
+  position?: 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right'
+  /** Max cards rendered in the deck (older ones collapse into a "+N" pill). */
+  max?: number
+  /** Default auto-dismiss in ms; a per-toast `duration` overrides. 0 = sticky. */
+  duration?: number
+  /** Passed to every card: adds "Report bug" to failure toasts. See UiToast. */
+  reportBug?: UiToastProps['reportBug']
+}

package/app/shared/widget-failure.ts

@@ -121,6 +121,7 @@ export function toWidgetFailure(error: unknown): WidgetFailure {
   return { _tag: 'unknown' }
 }
 
-export function widgetFailureCopy(error: unknown): WidgetFailureCopy {
-  return WIDGET_FAILURE_COPY[toWidgetFailure(error)._tag]
+/** The copy for a caught value. Pass `copy` to use a site's reworded failures. */
+export function widgetFailureCopy(error: unknown, copy: Readonly<Record<WidgetFailureTag, WidgetFailureCopy>> = WIDGET_FAILURE_COPY): WidgetFailureCopy {
+  return copy[toWidgetFailure(error)._tag]
 }