@nuxtseo/design-system 0.0.0-stage → 0.1.0

package/app/components/container/UiCard.vue

@@ -0,0 +1,204 @@
+<script setup lang="ts">
+import type { VNodeChild } from 'vue'
+import type { EjectChat, EjectLink, EjectMcp } from '../element/eject-menu'
+import { useElementSize } from '@vueuse/core'
+import { computed, useTemplateRef } from 'vue'
+import { UiEjectMenu } from '#components'
+import { useSquircleFallback } from '../../composables/useSquircleFallback'
+import { squircleSvgPath } from '../../utils/squircle'
+
+const {
+  size = 'md',
+  emphasis = false,
+  flush = false,
+  titleTag = 'h3',
+  chat,
+  mcp,
+  schema,
+} = defineProps<{
+  title?: string
+  /** Match the card title to its page section depth. */
+  titleTag?: 'h2' | 'h3' | 'h4'
+  description?: string
+  divided?: boolean
+  /** 'default' = solid bg-elevated (forms, settings). 'subtle' = translucent bg (data displays, lists). */
+  variant?: 'default' | 'subtle'
+  /** 'xs' = tight (inline/nested). 'sm' = compact (lists, dense tables). 'md' = default. 'lg' = spacious (hero/feature cards). */
+  size?: 'xs' | 'sm' | 'md' | 'lg'
+  /**
+   * The single sanctioned in-page contrast move: lift + primary-tinted top
+   * bevel (--elevation-emphasis) that survives the dashboard's raised→flat
+   * remap. Budget: at most ONE per page — two emphasis cards means neither is.
+   */
+  emphasis?: boolean
+  /**
+   * Drop the body padding so rows sit flush to the card edges and their
+   * dividers span the full width. The rows own their inset instead — match the
+   * header with `px-4 sm:px-(--density-card-padding)` so the two line up.
+   */
+  flush?: boolean
+  /**
+   * Card-grain eject affordance: renders a `<UiEjectMenu>` in the header so the
+   * card's own data can be opened in AI chat (or copied as code) without a
+   * floating page-level button. The card title supplies the context that a
+   * generic "Ask AI" button lacked, so the seed reads as scoped to this card.
+   * Pass `chat` with `entity` + `filter` (siteId) + `autoSend: true` to open the
+   * in-place ProChatPanel and fire the seed immediately. Only renders in the
+   * auto-header (title/actions driven); cards using a custom `#header` slot place
+   * the menu themselves.
+   */
+  chat?: EjectChat
+  mcp?: EjectMcp
+  schema?: EjectLink
+}>()
+
+const slots = defineSlots<{
+  default?: () => VNodeChild
+  header?: () => VNodeChild
+  actions?: () => VNodeChild
+}>()
+
+const hasEject = computed(() => !!(chat || mcp || schema))
+
+// The default (md) size reads the --density-card-padding knob at sm+ so card
+// density tunes centrally per context (:root / .dashboard-theme). The explicit
+// sizes (xs/sm/lg) are local intent and stay fixed.
+const headerClass = {
+  xs: 'px-2.5 py-2',
+  sm: 'px-3 sm:px-4 py-3',
+  md: 'px-4 sm:px-(--density-card-padding) py-4',
+  lg: 'px-6 sm:px-8 py-5',
+}[size]
+
+const bodyClass = {
+  xs: 'p-2.5',
+  sm: 'p-3 sm:p-4',
+  md: 'p-4 sm:p-(--density-card-padding)',
+  lg: 'p-6 sm:p-8',
+}[size]
+
+const bodyDividedClass = {
+  xs: 'divide-y divide-[var(--ui-border)] [&>*]:p-2.5',
+  sm: 'divide-y divide-[var(--ui-border)] [&>*]:p-3 [&>*]:sm:p-4',
+  md: 'divide-y divide-[var(--ui-border)] [&>*]:p-4 [&>*]:sm:p-(--density-card-padding)',
+  lg: 'divide-y divide-[var(--ui-border)] [&>*]:p-6 [&>*]:sm:p-8',
+}[size]
+
+// Size stays driven by the card's `size` prop (not the theme-resizing role
+// tokens); only the weight routes through the .font-strong token so it tunes
+// centrally with the rest of the type system.
+const titleClass = {
+  xs: 'text-xs font-strong text-default',
+  sm: 'text-sm font-strong text-default',
+  md: 'font-strong text-default',
+  lg: 'text-lg font-strong text-default',
+}[size]
+
+// Figma-squircle corners. Chrome gets the native `corner-shape: squircle`
+// (global.css), so `rounded-xl` (0.75rem ≈ 12px) is both the SSR shape and the
+// final shape — no JS, no morph. Safari/Firefox fall back to a generated
+// clip-path (clips bg + content to the squircle) plus an SVG hairline overlay
+// whose stroke is `var(--ui-border)`, so it follows the curve and tracks the
+// theme for free. The CSS border is hidden in that case so the clip can't
+// slice it.
+const RADIUS = 12
+const cardRef = useTemplateRef<HTMLElement>('card')
+const { width, height } = useElementSize(cardRef)
+const { enabled: squircle } = useSquircleFallback()
+
+const path = computed(() => squircle.value
+  ? squircleSvgPath(width.value, height.value, { radius: RADIUS, smoothing: 0.6 })
+  : '')
+// Emphasis shadow rides the inner card. In squircle-fallback browsers the
+// clip-path swallows the ambient drop shadow (inset bevel survives the clip) —
+// acceptable degradation; Chrome renders the full preset.
+const cardStyle = computed(() => {
+  const style: Record<string, string> = {}
+  if (path.value) {
+    style.clipPath = `path("${path.value}")`
+    style.borderColor = 'transparent'
+  }
+  if (emphasis)
+    style.boxShadow = 'var(--elevation-emphasis)'
+  return Object.keys(style).length ? style : undefined
+})
+</script>
+
+<template>
+  <div class="relative flex flex-col">
+    <div
+      ref="card"
+      data-ui-card
+      class="group/card relative overflow-hidden rounded-xl border flex flex-col flex-1"
+      :class="[
+        emphasis ? 'border-primary-400/25' : 'border-default',
+        emphasis
+          ? 'bg-[var(--ui-bg-elevated)]/50'
+          : variant === 'subtle' ? 'bg-[var(--ui-bg-elevated)]/5' : 'bg-[var(--ui-bg-elevated)]/35',
+      ]"
+      :style="cardStyle"
+    >
+      <!-- Header slot -->
+      <div v-if="slots.header" class="relative border-b border-default shrink-0" :class="headerClass">
+        <slot name="header" />
+      </div>
+      <!-- Auto header from title/description -->
+      <div v-else-if="title || slots.actions || hasEject" class="relative border-b border-default shrink-0 flex flex-col items-stretch gap-3 sm:flex-row sm:items-start sm:justify-between" :class="headerClass">
+        <div class="min-w-0">
+          <component :is="titleTag" v-if="title" class="break-words" :class="[titleClass]">
+            {{ title }}
+          </component>
+          <p v-if="description" class="text-sm text-muted mt-1">
+            {{ description }}
+          </p>
+        </div>
+        <div v-if="slots.actions || hasEject" class="flex flex-wrap items-center justify-end gap-1 sm:shrink-0">
+          <slot name="actions" />
+          <UiEjectMenu
+            v-if="hasEject"
+            :chat="chat"
+            :mcp="mcp"
+            :schema="schema"
+            class="-mr-1"
+          />
+        </div>
+      </div>
+
+      <!-- A custom #header owns its own actions row, so the eject can't sit in
+           it. When chat/eject props are set alongside #header, surface a
+           hover-revealed ⋯ in the card's top-right corner instead (same affordance
+           as UiEjectOverlay). Always-visible on touch / for keyboard users. -->
+      <div
+        v-if="hasEject && slots.header"
+        class="absolute top-2.5 right-2.5 z-10 opacity-0 transition-opacity group-hover/card:opacity-100 focus-within:opacity-100 [@media(hover:none)]:opacity-100"
+      >
+        <UiEjectMenu :chat="chat" :mcp="mcp" :schema="schema" />
+      </div>
+
+      <div
+        data-card-body class="relative flex-1 flex flex-col"
+        :class="[flush ? '' : divided ? bodyDividedClass : bodyClass]"
+      >
+        <slot />
+      </div>
+    </div>
+
+    <!-- Squircle hairline border (fallback browsers only). Stroke reads the
+         live token so it tracks the theme; non-scaling so it stays 1px. -->
+    <svg
+      v-if="path"
+      class="pointer-events-none absolute inset-0 size-full"
+      :viewBox="`0 0 ${width} ${height}`"
+      preserveAspectRatio="none"
+      aria-hidden="true"
+    >
+      <path
+        :d="path"
+        fill="none"
+        stroke-width="1"
+        vector-effect="non-scaling-stroke"
+        style="stroke: var(--ui-border)"
+      />
+    </svg>
+  </div>
+</template>

package/app/components/container/UiDisclosure.vue

@@ -0,0 +1,43 @@
+<script setup lang="ts">
+import { UiChip, UiIcon } from '#components'
+// The sanctioned overflow destination for tertiary content (DESIGN.md
+// Composition rules): a quiet native <details> row that keeps detail off the
+// page until asked for. Native element = free keyboard/AT semantics and
+// explicit body visibility keeps modal focus inside its visible controls.
+//
+// Expand/collapse animates via `.ui-disclosure::details-content` +
+// interpolate-size in global.css (Chromium); Firefox/Safari toggle instantly.
+// Reduced-motion disables the transition in the global block.
+//
+// Deliberately icon-light: the chevron is the only glyph. No leading icon
+// container, no eyebrow — the label is a noun + count, not a CTA.
+
+const { label, count } = defineProps<{
+  /** Quiet row label — a noun beats a verb ("Sitemaps", not "Show sitemaps"). */
+  label: string
+  /** Optional count so the collapsed row still reports scale. */
+  count?: number | string
+}>()
+
+const open = defineModel<boolean>('open', { default: false })
+
+function onToggle(e: Event) {
+  open.value = (e as ToggleEvent).newState === 'open'
+}
+</script>
+
+<template>
+  <details class="ui-disclosure group" :open="open" @toggle="onToggle">
+    <summary class="flex items-center gap-2 cursor-pointer select-none list-none [&::-webkit-details-marker]:hidden min-h-11 sm:min-h-0 py-1 -mx-1 px-1 rounded-md focus-visible:ring-2 focus-visible:ring-primary outline-none">
+      <UiIcon name="chevron-right" class="size-3.5 text-dimmed transition-transform duration-150 group-open:rotate-90" aria-hidden="true" />
+      <span class="text-sm font-strong text-muted group-hover:text-default transition-colors">{{ label }}</span>
+      <UiChip v-if="count !== undefined" purpose="count">
+        {{ count }}
+      </UiChip>
+      <slot name="actions" />
+    </summary>
+    <div v-show="open" class="pt-3">
+      <slot />
+    </div>
+  </details>
+</template>

package/app/components/container/UiEmptyState.vue

@@ -0,0 +1,102 @@
+<script setup lang="ts">
+import type { UiIcon as UiIconName } from '../../shared/ui-icons'
+import { m } from 'motion-v'
+import { computed } from 'vue'
+import { UiAtmosphere, UiIcon } from '#components'
+import { useEntranceMotion } from '../../composables/useEntranceMotion'
+import { entrancePresets } from '../../shared/motion'
+
+const {
+  compact,
+  wide,
+  headingTag,
+  animated = true,
+} = defineProps<{
+  icon: UiIconName
+  title: string
+  description?: string
+  /**
+   * Where the data comes from once the feature runs (e.g. "From Search Console,
+   * refreshed daily."). Full variant only; ignored when `compact`. Renders as a
+   * small dimmed line under the description. First-use anatomy: title sells the
+   * value, description says why or how, source names the data, one CTA in the slot.
+   */
+  source?: string
+  compact?: boolean
+  /**
+   * Widen the default slot for a short setup form. The slot spans the full
+   * width up to `max-w-2xl` and its text is left-aligned, so fields do not
+   * inherit the centering. The submit CTA stays left-aligned under the last
+   * field, where the eye ends after filling the form. Full variant only.
+   */
+  wide?: boolean
+  /**
+   * Title element. Full variant defaults to `h3`. Compact defaults to `p`,
+   * because most compact states sit inside a card that already has a heading;
+   * pass a level when the compact state stands in for a section's content.
+   */
+  headingTag?: 'h1' | 'h2' | 'h3'
+  /** Disable JS entrance motion on SSR-sensitive public routes. */
+  animated?: boolean
+  /**
+   * Opt-in greydient atmosphere for genuine pre-data / front-door empty states
+   * (a preset name). Full variant only — leave unset for in-dashboard empties so
+   * data surfaces stay silent. Renders behind the content via <UiAtmosphere>.
+   */
+  atmosphere?: 'front-door' | 'error' | 'ai' | 'preview' | 'share'
+}>()
+
+const rootComponent = computed(() => animated ? m.div : 'div')
+const titleTag = computed(() => headingTag ?? (compact ? 'p' : 'h3'))
+const rootMotion = useEntranceMotion(entrancePresets.fadeUp, () => animated)
+</script>
+
+<template>
+  <component
+    :is="rootComponent"
+    data-testid="empty-state"
+    :class="compact
+      ? 'flex flex-col items-center justify-center h-[220px] rounded-lg border border-dashed border-default bg-muted'
+      : ['text-center px-4 py-10 sm:py-16 sm:min-h-[400px] flex flex-col items-center justify-center', atmosphere ? 'relative isolate overflow-hidden' : '']"
+    v-bind="rootMotion"
+  >
+    <!-- Compact: inline empty state for cards/lists -->
+    <template v-if="compact">
+      <UiIcon :name="icon" class="size-8 text-dimmed mb-2" aria-hidden="true" />
+      <component :is="titleTag" class="text-sm font-medium text-default">
+        {{ title }}
+      </component>
+      <p v-if="description" class="text-xs text-muted mt-1 max-w-sm text-center px-4">
+        {{ description }}
+      </p>
+      <div v-if="$slots.default" class="mt-3 [&_button]:min-h-11 [&_a]:min-h-11 sm:[&_button]:min-h-0 sm:[&_a]:min-h-0">
+        <slot />
+      </div>
+    </template>
+
+    <!-- Full: centered page-level empty state -->
+    <template v-else>
+      <!-- z-index:-1 + isolate keeps it behind content without wrapping anything. -->
+      <UiAtmosphere v-if="atmosphere" :preset="atmosphere" style="z-index: -1" />
+      <div class="inline-flex items-center justify-center size-14 rounded-2xl bg-elevated border border-default mb-4">
+        <UiIcon :name="icon" class="size-7 text-muted" aria-hidden="true" />
+      </div>
+      <component :is="titleTag" class="text-lg font-medium text-default mb-1 max-w-md text-balance">
+        {{ title }}
+      </component>
+      <p v-if="description" class="text-sm text-muted max-w-md mx-auto leading-relaxed text-pretty">
+        {{ description }}
+      </p>
+      <p v-if="source" class="text-xs text-dimmed mt-2 max-w-md mx-auto text-pretty">
+        {{ source }}
+      </p>
+      <div
+        class="mt-6 [&_button]:min-h-11 [&_a]:min-h-11 sm:[&_button]:min-h-0 sm:[&_a]:min-h-0"
+        :class="wide && 'w-full max-w-2xl text-left'"
+      >
+        <slot />
+      </div>
+      <slot name="footer" />
+    </template>
+  </component>
+</template>

package/app/components/container/UiErrorState.vue

@@ -0,0 +1,61 @@
+<script setup lang="ts">
+import type { ErrorStateSource } from '../../shared/error-state'
+import { computed } from 'vue'
+import { UiAlert, UiButton } from '#components'
+import { resolveErrorState } from '../../shared/error-state'
+
+const { error } = defineProps<{
+  /**
+   * Why the region failed, and where the words come from.
+   *
+   * Build it with `wireError(caught)` for a caught value, `errorCopy(...)` for
+   * a sentence a person wrote, or `rateLimited(...)` for a parsed quota
+   * refusal. A caught error has no renderable string here: `wireError` types it
+   * `unknown`, so the template reads only its HTTP status code and states copy
+   * this component owns. The old `string | { message: string }` prop rendered
+   * the caught message, which quotes the request URL.
+   */
+  error: ErrorStateSource | null
+  /** Optional retry handler. When set (and no #action slot), renders a "Try again" button. */
+  onRetry?: () => void
+}>()
+
+defineSlots<{
+  /** Replaces the retry button and the generic next-step line. */
+  action?: () => unknown
+}>()
+
+// `Date.now()` is read once per resolve, the same as the old inline reset
+// maths. The reset hint counts down only when something else re-renders.
+const view = computed(() => error ? resolveErrorState(error, Date.now()) : null)
+</script>
+
+<template>
+  <UiAlert
+    v-if="view"
+    :status="view.tone"
+    :icon="view.icon"
+    :title="view.title"
+    class="mb-8"
+  >
+    <p v-if="view.detail" class="mt-1">
+      {{ view.detail }}
+    </p>
+    <p
+      v-if="view.nextStep && (view.nextStep._tag === 'timing' || !$slots.action)"
+      class="text-muted/80 mt-1"
+    >
+      {{ view.nextStep.text }}
+    </p>
+    <slot name="action" />
+    <UiButton
+      v-if="onRetry && view.retryable && !$slots.action"
+      purpose="secondary"
+      size="xs"
+      icon="refresh"
+      label="Try again"
+      class="mt-2"
+      @click="onRetry()"
+    />
+  </UiAlert>
+</template>

package/app/components/container/UiLoadingState.vue

@@ -0,0 +1,20 @@
+<script setup lang="ts">
+import { UiSkeleton } from '#components'
+
+defineProps<{
+  rows?: number
+}>()
+</script>
+
+<template>
+  <div class="space-y-3" role="status" aria-live="polite" aria-busy="true">
+    <span class="sr-only">Loading…</span>
+    <div v-for="i in rows ?? 3" :key="i" class="flex items-center gap-3">
+      <UiSkeleton type="circle" :base="32" :index="i" />
+      <div class="flex-1 space-y-1.5">
+        <UiSkeleton :base="100" :range="60" :index="i" />
+        <UiSkeleton :base="140" :range="80" :index="i + 10" />
+      </div>
+    </div>
+  </div>
+</template>

package/app/components/container/UiPageHeader.vue

@@ -0,0 +1,95 @@
+<script setup lang="ts">
+import type { UiIcon as UiIconName } from '../../shared/ui-icons'
+import { NuxtLink, UiIcon } from '#components'
+
+// Page header: context crumb + title + trailing actions row, with optional
+// breadcrumb links above (admin detail pages). Extracted after six sibling
+// pages converged on the same shape.
+
+interface Crumb {
+  label: string
+  to?: string
+}
+
+// `description` is intentionally accepted-but-unrendered: page headers no longer
+// show a subtitle. Kept in the type so existing callers don't break.
+const { crumbs = [], title, icon, flush = false, border = true, stackActionsOnMobile = false } = defineProps<{
+  crumbs?: Crumb[]
+  title: string
+  icon?: UiIconName
+  description?: string
+  /** Skip pro-container (max-width + horizontal padding). Use in non-pro shells where padding is owned by the layout. */
+  flush?: boolean
+  /** Bottom hairline. Turn off for headers with a sub-nav tab strip beneath (the tabs own the separator). */
+  border?: boolean
+  /** Give dense detail-page actions their own row below the title on mobile. */
+  stackActionsOnMobile?: boolean
+}>()
+</script>
+
+<template>
+  <header :class="[flush ? '' : 'pro-container', border ? 'border-b border-default' : '']">
+    <div class="flex items-start gap-4 pt-2">
+      <div
+        class="flex items-start justify-between min-w-0 w-full gap-3"
+        :class="stackActionsOnMobile ? 'flex-col sm:flex-row' : 'flex-row'"
+      >
+        <div class="min-w-0 flex-1">
+          <nav v-if="crumbs.length" aria-label="Breadcrumb" class="flex items-center gap-2 text-xs text-dimmed mb-1">
+            <template v-for="(crumb, i) in crumbs" :key="crumb.to ?? crumb.label">
+              <NuxtLink v-if="crumb.to" :to="crumb.to" class="hover:text-default">
+                {{ crumb.label }}
+              </NuxtLink>
+              <span
+                v-else
+                class="text-muted truncate"
+                :aria-current="i === crumbs.length - 1 ? 'page' : undefined"
+              >
+                {{ crumb.label }}
+              </span>
+              <UiIcon
+                v-if="i < crumbs.length - 1"
+                name="chevron-right"
+                class="size-3"
+                aria-hidden="true"
+              />
+            </template>
+          </nav>
+          <!-- Title row. `#leading` (the mobile nav button) sits before both
+               lines. `#crumb` is the context segment (site/group switcher):
+               from `sm` it shares the title's row at title scale ("Nuxt SEO /
+               Overview"); below `sm` the header stacks, with the crumb as a
+               small muted line above the title. The crumb component owns its
+               trailing slash (it may render nothing, e.g. while the site list
+               resolves, and a dangling separator reads broken). Kept outside
+               the h1 so the heading text stays clean. When the row overflows,
+               the crumb truncates first: the title barely shrinks until the
+               crumb reaches its minimum width. -->
+          <div class="flex min-w-0 items-center gap-2">
+            <slot name="leading" />
+            <div class="flex min-w-0 flex-1 flex-col sm:flex-row sm:items-center gap-x-2">
+              <div v-if="$slots.crumb" class="flex min-w-0 items-center gap-x-2 sm:shrink">
+                <slot name="crumb" />
+              </div>
+              <div class="flex min-w-0 items-center gap-2 sm:shrink-[0.001]">
+                <h1 class="text-title text-default flex items-center gap-2 min-w-0">
+                  <slot name="icon">
+                    <UiIcon v-if="icon" :name="icon" class="size-4 text-dimmed shrink-0" aria-hidden="true" />
+                  </slot>
+                  <span class="truncate">{{ title }}</span>
+                </h1>
+                <slot name="title-trailing" />
+              </div>
+            </div>
+          </div>
+        </div>
+        <div
+          class="flex items-center gap-3 flex-wrap shrink-0"
+          :class="stackActionsOnMobile ? 'w-full justify-start sm:w-auto sm:justify-end' : 'justify-end'"
+        >
+          <slot name="actions" />
+        </div>
+      </div>
+    </div>
+  </header>
+</template>

package/app/components/container/UiPopover.vue

@@ -0,0 +1,102 @@
+<script setup lang="ts">
+import type { PopoverProps } from '@nuxt/ui'
+import type { VNode } from 'vue'
+import { computed, useSlots, watch } from 'vue'
+import { UPopover } from '#components'
+
+type UiPopoverProps = Omit<PopoverProps, 'open' | 'defaultOpen' | 'portal' | 'ui'> & {
+  /** Prevent opening while retaining the trigger in the page flow. */
+  disabled?: boolean
+  /** The content remains portalled; callers may target a specific portal host. */
+  portal?: true | string | HTMLElement
+  /** Optional semantic role applied to the owned panel wrapper. */
+  role?: string
+  /** Stable id for associating the panel with its trigger. */
+  panelId?: string
+  ui?: PopoverProps['ui']
+}
+
+const props = withDefaults(defineProps<UiPopoverProps>(), {
+  dismissible: true,
+  portal: true,
+})
+const emit = defineEmits<{
+  'close:prevent': []
+}>()
+defineSlots<{
+  default?: (props: { disabled: boolean, open: boolean }) => VNode[]
+  panel?: (props: { close?: () => void }) => VNode[]
+  anchor?: (props: { close?: () => void }) => VNode[]
+}>()
+
+const slots = useSlots()
+const open = defineModel<boolean>('open', { default: false })
+const guardedOpen = computed({
+  get: () => props.disabled ? false : open.value,
+  set: (nextOpen: boolean) => {
+    if (props.disabled && nextOpen)
+      return
+    open.value = nextOpen
+  },
+})
+
+watch(() => props.disabled, (disabled) => {
+  if (disabled)
+    open.value = false
+})
+
+// Keep the application popover contract resilient by default. UPopover remains
+// the accessible implementation detail; callers cannot disable its portal and
+// every panel gets collision padding plus the shared overlay chrome.
+const forwardedProps = computed(() => {
+  const { disabled: _disabled, panelId: _panelId, role: _role, ui: _ui, ...forwarded } = props
+  return {
+    ...forwarded,
+    mode: props.mode ?? 'click',
+    openDelay: props.openDelay ?? 0,
+    closeDelay: props.closeDelay ?? 0,
+    dismissible: props.dismissible ?? true,
+    portal: props.portal ?? true,
+    content: {
+      side: 'bottom' as const,
+      sideOffset: 8,
+      collisionPadding: 8,
+      ...props.content,
+    },
+  }
+})
+
+const mergedUi = computed<PopoverProps['ui']>(() => {
+  const userContent = props.ui?.content
+  return {
+    ...props.ui,
+    content: typeof userContent === 'function'
+      ? (defaults: string) => ['ui-popover-content', userContent(defaults)]
+      : ['ui-popover-content', userContent],
+  }
+})
+</script>
+
+<template>
+  <UPopover
+    v-bind="forwardedProps"
+    v-model:open="guardedOpen"
+    :ui="mergedUi"
+    @close:prevent="emit('close:prevent')"
+  >
+    <template v-if="slots.default" #default="slotProps">
+      <slot v-bind="slotProps" :disabled="props.disabled ?? false" />
+    </template>
+
+    <template v-if="slots.anchor" #anchor="slotProps">
+      <slot name="anchor" v-bind="slotProps" />
+    </template>
+
+    <template #content="slotProps">
+      <div v-if="props.role || props.panelId" :id="props.panelId" data-ui="UiPopover" :role="props.role">
+        <slot name="panel" v-bind="slotProps" />
+      </div>
+      <slot v-else name="panel" v-bind="slotProps" />
+    </template>
+  </UPopover>
+</template>

package/app/components/container/UiSampleDataOverlay.vue

@@ -0,0 +1,47 @@
+<script setup lang="ts">
+import { UiAtmosphere, UiButton, UiIcon } from '#components'
+
+defineProps<{
+  message?: string
+  description?: string
+  ctaLabel?: string
+  ctaTo?: string
+}>()
+</script>
+
+<template>
+  <div class="relative">
+    <!-- Faded sample content. `inert` removes it from focus order AND the
+         accessibility tree together — `aria-hidden` alone leaves any focusable
+         children tabbable while hidden (a WCAG 4.1.2 violation). -->
+    <div class="opacity-25 select-none" inert>
+      <slot />
+    </div>
+
+    <!-- Overlay -->
+    <div class="absolute inset-0 flex flex-col items-center justify-center bg-gradient-to-b from-[var(--ui-bg)]/70 via-[var(--ui-bg)]/95 to-[var(--ui-bg)]/75 backdrop-blur-[1px]">
+      <!-- The pre-data preview read as data glimpsed through fog. -->
+      <UiAtmosphere preset="preview" />
+      <div class="relative w-full max-w-md rounded-lg border border-default bg-default/90 px-5 py-4 text-center shadow-lg ring-1 ring-black/5 dark:ring-white/5">
+        <div class="mb-3 inline-flex size-10 items-center justify-center rounded-lg border border-default bg-elevated">
+          <UiIcon name="google" class="size-5 text-muted" aria-hidden="true" />
+        </div>
+        <p class="mb-1 text-sm font-semibold text-highlighted">
+          {{ message || 'Preview' }}
+        </p>
+        <p class="mx-auto mb-4 max-w-sm text-sm leading-relaxed text-default">
+          {{ description || 'Connect Google Search Console to see your real data.' }}
+        </p>
+        <UiButton
+          v-if="ctaTo"
+          :to="ctaTo"
+          size="sm"
+          purpose="secondary"
+          icon="plug"
+        >
+          {{ ctaLabel || 'Connect GSC' }}
+        </UiButton>
+      </div>
+    </div>
+  </div>
+</template>