@nuxtseo/design-system 0.0.0-stage → 0.1.1

package/app/components/element/UiLogoPro.vue

@@ -0,0 +1,25 @@
+<script setup lang="ts">
+import { UiBrandMark, UiProLettering } from '#components'
+
+const { variant = 'default' } = defineProps<{
+  variant?: 'default' | 'auth'
+}>()
+
+const wordSize = { default: 18, auth: 24 } as const
+</script>
+
+<template>
+  <span
+    data-ui="UiLogoPro"
+    :data-variant="variant"
+    class="inline-flex shrink-0 items-center whitespace-nowrap text-highlighted"
+    :class="variant === 'auth' ? 'gap-2.5' : 'gap-2'"
+  >
+    <UiBrandMark product="pro" :size="variant === 'auth' ? 32 : 28" />
+    <span
+      class="font-display tracking-[-0.03em]"
+      :style="{ fontSize: `${wordSize[variant]}px` }"
+    ><span class="font-medium">Nuxt</span> <span class="font-bold">SEO</span></span>
+    <UiProLettering :size="wordSize[variant]" />
+  </span>
+</template>

package/app/components/element/UiLogoUmami.vue

@@ -0,0 +1,12 @@
+<script setup lang="ts">
+// Official Umami brand mark, brand colour #13B0F5 baked into the asset (single-colour
+// mark — there is no multicolour version). Inline SVG so the colour survives, vs an
+// icon set that would monotone it to currentColor. Sizing/aria fall through from the
+// parent (e.g. class="size-6").
+</script>
+
+<template>
+  <svg viewBox="0 0 24 24" fill="#13B0F5" xmlns="http://www.w3.org/2000/svg">
+    <path d="M2.203 8.611H.857a.845.845 0 0 0-.841.841v.858a13.31 13.31 0 0 0-.016.6c0 6.627 5.373 12 12 12 6.527 0 11.837-5.212 11.996-11.701 0-.025.004-.05.004-.075V9.452a.845.845 0 0 0-.841-.841h-1.346c-1.159-4.329-5.112-7.521-9.805-7.521-4.692 0-8.645 3.192-9.805 7.521Zm18.444 0H3.37c1.127-3.702 4.57-6.399 8.638-6.399 4.069 0 7.512 2.697 8.639 6.399Z" />
+  </svg>
+</template>

package/app/components/element/UiNavIcon.vue

@@ -0,0 +1,107 @@
+<script lang="ts" setup>
+import type { UiIcon as UiIconName } from '../../shared/ui-icons'
+import { computed } from 'vue'
+import { UiIcon } from '#components'
+/**
+ * Nav icon container used in sidebar navigation and status rows.
+ * Default is primary-tinted. Semantic variants (success/warning/error/info)
+ * use low-alpha skewed tints of the semantic color tokens.
+ *
+ * The `default` variant is alive: idle it stays restrained (dimmed glyph,
+ * faint tint), then leans into the brand color as a pop on hover (reacts to a
+ * `group/navitem` ancestor) and on `active`. The glyph springs up a touch and
+ * the box lifts, so the icon reads as the focal point of its row rather than a
+ * flat chip. Semantic variants are static status tints and don't react.
+ *
+ * Renders through `UiIcon`, so it speaks the curated icon vocabulary
+ * (semantic names like `chart`, `lock`) while still accepting raw `i-*` ids.
+ *
+ * `neutral` is the monochrome identity treatment: a flat neutral box + muted
+ * glyph, no brand tint and no hover pop. Use it when the icon is resting
+ * identity (e.g. a trigger-kind glyph) and the colour budget belongs to the
+ * row's status (a dot/badge), not the icon. Differentiate kinds by glyph shape,
+ * never by colour.
+ */
+type Variant = 'default' | 'neutral' | 'success' | 'warning' | 'error' | 'info' | 'experimental'
+
+const { icon, locked = false, loading = false, active = false, variant = 'default', size = 'md' } = defineProps<{
+  icon: UiIconName
+  locked?: boolean
+  /** Swap the glyph for a spinner — e.g. a nav item whose data is syncing. */
+  loading?: boolean
+  /** Marks the icon's row as active — deepens the tint, lifts the glyph to primary, adds a soft halo. */
+  active?: boolean
+  variant?: Variant
+  /** `md` (size-6 — nav/status rows) · `sm` (size-5) · `xs` (size-4 — dense list rows). */
+  size?: 'xs' | 'sm' | 'md'
+}>()
+
+const boxSize = size === 'xs' ? 'size-4' : size === 'sm' ? 'size-5' : 'size-6'
+const glyphSize = size === 'xs' ? 'size-2.5' : size === 'sm' ? 'size-3' : 'size-3.5'
+
+const variantBoxClasses: Record<Variant, string> = {
+  neutral: 'border border-default bg-elevated',
+  success: 'border bg-success/5 border-success/20',
+  warning: 'border bg-warning/5 border-warning/20',
+  error: 'border bg-error/5 border-error/20',
+  info: 'border bg-info/5 border-info/20',
+  experimental: 'bg-[var(--ui-bg-elevated)]/60',
+} as Record<Variant, string>
+
+const variantIconClasses: Record<Variant, string> = {
+  neutral: 'text-muted',
+  success: 'text-success/80',
+  warning: 'text-warning/80',
+  error: 'text-error/80',
+  info: 'text-info/80',
+  experimental: 'text-dimmed',
+} as Record<Variant, string>
+
+// The default variant is state-driven; precedence is active > hover > idle so
+// nothing fights over `!important`. Hover is CSS-only (group/navitem ancestor).
+const boxClass = computed(() => {
+  if (variant !== 'default')
+    return variantBoxClasses[variant]
+  if (active)
+    return 'border bg-gradient-to-b from-primary-300/30 to-primary-300/12 border-primary/35 ring-2 ring-primary/15 dark:from-primary-900/40 dark:to-primary-900/15'
+  return 'border bg-gradient-to-b from-primary-300/15 to-primary-300/5 border-primary-300/15 dark:from-primary-900/20 dark:to-primary-900/5 dark:border-primary-950/15 group-hover/navitem:-translate-y-px group-hover/navitem:from-primary-300/25 group-hover/navitem:to-primary-300/10 group-hover/navitem:border-primary-300/30 dark:group-hover/navitem:from-primary-900/30 dark:group-hover/navitem:to-primary-900/10'
+})
+
+const iconClass = computed(() => {
+  if (variant !== 'default')
+    return variantIconClasses[variant]
+  if (active)
+    return 'text-primary scale-110'
+  return 'text-dimmed group-hover/navitem:text-primary group-hover/navitem:scale-115'
+})
+</script>
+
+<template>
+  <!--
+    `<span>`, not `<div>`. Callers place this glyph tile INLINE — riding next
+    to a category label inside a `<p>` (`UiIssueRow`'s "full" type line) or
+    beside text in a nav row. A `<div>` is flow content and cannot legally sit
+    inside `<p>`'s phrasing-content model: the browser's HTML parser force-
+    closes the `<p>` (and everything open inside it) the instant it meets the
+    div start tag, silently hoisting this tile OUT to become a sibling of the
+    paragraph instead of its child. That reshapes the server-rendered DOM into
+    something Vue's client vdom never expected — a REAL SSR/hydration
+    mismatch (not a dev-only artefact; it's an HTML parsing rule, identical in
+    production), cascading into 6-7 "Hydration node/children mismatch"
+    warnings per row, on every `UiIssueRow` (site board + portfolio queue).
+    `inline-flex` keeps the exact same internal flex layout; as a flex ITEM
+    inside a parent flexbox, `span`/`div` behave identically either way, so
+    this is a pure content-model fix with no visual change.
+  -->
+  <span
+    class="inline-flex items-center justify-center rounded-md transition-[transform,background-color,border-color,box-shadow] duration-200 ease-[var(--ease-spring)]"
+    :class="[boxSize, boxClass]"
+  >
+    <UiIcon
+      :name="loading ? 'loading' : locked ? 'lock' : icon"
+      class="shrink-0 transition-[transform,color] duration-200 ease-[var(--ease-spring)]"
+      :class="[glyphSize, iconClass, { 'animate-spin': loading }]"
+      aria-hidden="true"
+    />
+  </span>
+</template>

package/app/components/element/UiNavList.vue

@@ -0,0 +1,156 @@
+<script setup lang="ts" generic="T extends UiNavLink">
+import type { VNodeChild } from 'vue'
+import type { UiNavLink } from '../../shared/nav'
+import { useRoute } from 'nuxt/app'
+import { NuxtLink, UiIcon, UiNavIcon, UiTooltip } from '#components'
+
+const { links, activeMode = 'exact', label, variant = 'default', tone = 'muted' } = defineProps<{
+  links: T[]
+  /** Sidebar rows use plain icons. Release labels belong in the page header. */
+  variant?: 'default' | 'sidebar'
+  tone?: 'default' | 'muted'
+  activeMode?: 'exact' | 'prefix'
+  /**
+   * Accessible name for this `<nav>` landmark. Pass a distinct value when more
+   * than one nav list renders on a page (e.g. grouped sidebars) so the landmarks
+   * stay unique for screen readers.
+   */
+  label?: string
+}>()
+
+defineSlots<{
+  /** Custom leading visual per item (e.g. a favicon). Replaces `UiNavIcon`. */
+  icon?: (props: { link: T, active: boolean }) => VNodeChild
+  /** Trailing per-row action (e.g. a hover menu). Rendered as a sibling of the
+   *  link, not nested inside the anchor, so interactive triggers stay valid. */
+  action?: (props: { link: T }) => VNodeChild
+}>()
+
+const route = useRoute()
+
+function isActive(link: T) {
+  if (link.active)
+    return link.active(route.path)
+  if (activeMode === 'prefix')
+    return route.path === link.to || route.path.startsWith(`${link.to}/`)
+  return route.path === link.to
+}
+</script>
+
+<template>
+  <nav class="space-y-0.5" :aria-label="label">
+    <div
+      v-for="link in links"
+      :key="link.to"
+      class="relative group/navitem"
+    >
+      <NuxtLink
+        :to="link.disabled ? undefined : link.to"
+        :prefetch="link.disabled ? undefined : link.prefetch"
+        :aria-disabled="link.disabled || undefined"
+        :aria-current="isActive(link) && !link.disabled ? 'page' : undefined"
+        :tabindex="link.disabled ? -1 : undefined"
+        class="flex items-center gap-1.5 px-1 py-1 min-h-11 lg:min-h-0 rounded text-sm transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary"
+        :class="[
+          link.disabled
+            ? 'text-dimmed cursor-not-allowed'
+            : isActive(link)
+              ? 'bg-elevated text-highlighted'
+              : link.textTone === 'highlighted'
+                ? 'text-highlighted hover:text-highlighted hover:bg-elevated'
+                : tone === 'default'
+                  ? 'text-default hover:text-highlighted hover:bg-elevated'
+                  : 'text-muted hover:text-default hover:bg-elevated',
+          variant === 'sidebar' && !link.disabled && !isActive(link) && (tone === 'default' || link.textTone === 'highlighted')
+            ? 'dark:text-toned dark:hover:text-highlighted'
+            : undefined,
+        ]"
+        :style="isActive(link) && !link.disabled ? { boxShadow: 'var(--elevation-raised)', backgroundImage: 'var(--surface-raised)' } : undefined"
+        :title="link.title"
+      >
+        <slot v-if="$slots.icon" name="icon" :link="link" :active="isActive(link)" />
+        <UiIcon
+          v-else-if="link.icon && variant === 'sidebar'"
+          :name="link.icon"
+          class="size-4 shrink-0"
+          aria-hidden="true"
+        />
+        <UiNavIcon
+          v-else-if="link.icon"
+          :icon="link.icon"
+          :active="isActive(link)"
+        />
+        <span class="min-w-0 truncate">{{ link.label }}</span>
+        <span
+          v-if="link.badge"
+          class="ml-auto text-mini font-medium px-1.5 py-0.5 rounded-md"
+          :class="link.badgeColor === 'warning'
+            ? 'text-warning bg-warning/10'
+            : link.badgeColor === 'neutral'
+              ? 'text-muted bg-elevated ring-1 ring-default'
+              : 'text-primary bg-primary/10'"
+        >
+          {{ link.badge }}
+        </span>
+        <!--
+          A row whose feature is not connected yet owes the user a chore, not an
+          alert. It renders as an unfilled outline chip carrying the verb, so it
+          names the action without a tooltip and stays quieter than the filled
+          `badge` above (a real worklist count) sitting in the same slot.
+        -->
+        <UiTooltip
+          v-else-if="link.setup"
+          :text="link.setup.tooltip"
+        >
+          <span
+            class="ml-auto shrink-0 text-mini font-medium px-1.5 py-px rounded border border-dashed transition-colors"
+            :class="link.setup.tone === 'warning'
+              ? 'text-warning border-warning/30 group-hover/navitem:border-warning/50'
+              : 'text-muted border-default group-hover/navitem:text-default group-hover/navitem:border-accented'"
+          >
+            <!--
+              The verb alone is ambiguous out of row context, so the accessible
+              name carries the same full state the tooltip shows. `text-dimmed`
+              is banned here: this chip is an affordance, not tertiary metadata,
+              and it fails AA in dark mode.
+            -->
+            <span aria-hidden="true">{{ link.setup.verb }}</span>
+            <span class="sr-only">{{ link.setup.tooltip }}</span>
+          </span>
+        </UiTooltip>
+        <UiTooltip
+          v-else-if="link.pending"
+          :text="link.pendingTooltip || 'Waiting for data'"
+        >
+          <span
+            class="ml-auto flex items-center"
+            role="img"
+            :aria-label="link.pendingTooltip || 'Waiting for data'"
+          >
+            <span class="size-1.5 rounded-full bg-current text-warning motion-safe:animate-pulse" aria-hidden="true" />
+          </span>
+        </UiTooltip>
+        <!--
+          Stability is a word, not a glyph: a flask beside three rows told the
+          reader nothing without hovering each one. Same dashed outline chip
+          as `setup` above, in the muted tone, so the sidebar carries one chip
+          grammar (a verb to act on, or a tier to know about).
+        -->
+        <UiTooltip
+          v-else-if="link.stability && variant !== 'sidebar'"
+          :text="link.stability.tooltip"
+        >
+          <span class="ml-auto shrink-0 text-mini font-medium px-1.5 py-px rounded border border-dashed border-default text-muted transition-colors group-hover/navitem:text-default group-hover/navitem:border-accented">
+            {{ link.stability.tooltip }}
+          </span>
+        </UiTooltip>
+      </NuxtLink>
+      <div
+        v-if="$slots.action"
+        class="absolute right-1 top-1/2 -translate-y-1/2"
+      >
+        <slot name="action" :link="link" />
+      </div>
+    </div>
+  </nav>
+</template>

package/app/components/element/UiOnboardingAnswers.vue

@@ -0,0 +1,127 @@
+<script setup lang="ts">
+import type { OnboardingAnswersCopy, OnboardingAnswersDraft } from './onboarding-answers'
+import type { OnboardingIntent } from './onboarding-intents'
+import { computed, useId } from 'vue'
+import { UiIcon, UTextarea } from '#components'
+import {
+  ONBOARDING_ANSWERS_COPY,
+  ONBOARDING_OTHER_MAX_LENGTH,
+  ONBOARDING_ROLES,
+  ONBOARDING_SEO_EXPERIENCE,
+  ONBOARDING_SITE_COUNTS,
+} from './onboarding-answers'
+import { ONBOARDING_INTENTS } from './onboarding-intents'
+
+// The onboarding "About you" questions on one screen: three single-choice chip
+// rows, the multi-choice goals, and an optional free-text box. Every question
+// is optional, and a second tap on a picked chip clears it. Presentation only:
+// the live teams/create wizard and the brand-kit showcase both v-model the
+// draft and decide when to save it.
+//
+// The goals list and the copy name the product, so a site that extends this
+// layer passes its own `intents` and any `copy` keys it rewords. The option
+// ids are shared and stored, so they never change.
+const {
+  intents = ONBOARDING_INTENTS,
+  copy: copyOverrides = {},
+} = defineProps<{
+  intents?: readonly OnboardingIntent[]
+  copy?: Partial<OnboardingAnswersCopy>
+}>()
+const copy = computed<OnboardingAnswersCopy>(() => ({ ...ONBOARDING_ANSWERS_COPY, ...copyOverrides }))
+const answers = defineModel<OnboardingAnswersDraft>({ required: true })
+
+const id = useId()
+const otherId = `${id}-other`
+
+const singleQuestions = computed(() => [
+  { key: 'role', question: copy.value.roleQuestion, options: ONBOARDING_ROLES },
+  { key: 'siteCount', question: copy.value.siteCountQuestion, options: ONBOARDING_SITE_COUNTS },
+  { key: 'seoExperience', question: copy.value.seoExperienceQuestion, options: ONBOARDING_SEO_EXPERIENCE },
+] as const)
+
+type SingleKey = 'role' | 'siteCount' | 'seoExperience'
+
+function pick(key: SingleKey, value: string) {
+  answers.value = { ...answers.value, [key]: answers.value[key] === value ? undefined : value }
+}
+
+function toggleIntent(intent: string) {
+  const intents = answers.value.intents.includes(intent)
+    ? answers.value.intents.filter(existing => existing !== intent)
+    : [...answers.value.intents, intent]
+  answers.value = { ...answers.value, intents }
+}
+
+function setOther(other: string) {
+  answers.value = { ...answers.value, other }
+}
+
+const chipClass = 'inline-flex min-h-11 sm:min-h-9 cursor-pointer items-center gap-1.5 rounded-full border px-3.5 text-sm font-medium outline-none transition-[background-color,border-color,color] focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-2 focus-visible:ring-offset-default active:translate-y-px'
+const selectedClass = 'border-primary bg-primary/10 text-highlighted ring-1 ring-primary/40'
+const restClass = 'border-accented bg-default/80 text-default hover:border-primary/60 hover:bg-elevated'
+</script>
+
+<template>
+  <div class="space-y-6">
+    <fieldset v-for="item in singleQuestions" :key="item.key" class="space-y-2.5">
+      <legend class="text-sm font-medium text-highlighted">
+        {{ item.question }}
+      </legend>
+      <div class="flex flex-wrap gap-2">
+        <button
+          v-for="option in item.options"
+          :key="option.id"
+          type="button"
+          :aria-pressed="answers[item.key] === option.id"
+          :class="[chipClass, answers[item.key] === option.id ? selectedClass : restClass]"
+          @click="pick(item.key, option.id)"
+        >
+          {{ option.label }}
+        </button>
+      </div>
+    </fieldset>
+
+    <fieldset class="space-y-2.5">
+      <legend class="text-sm font-medium text-highlighted">
+        {{ copy.intentsQuestion }}
+      </legend>
+      <p class="text-xs text-muted">
+        {{ copy.intentsHint }}
+      </p>
+      <div class="flex flex-wrap gap-2">
+        <button
+          v-for="intent in intents"
+          :key="intent.id"
+          type="button"
+          :aria-pressed="answers.intents.includes(intent.id)"
+          :class="[chipClass, answers.intents.includes(intent.id) ? selectedClass : restClass]"
+          @click="toggleIntent(intent.id)"
+        >
+          <UiIcon
+            :name="answers.intents.includes(intent.id) ? 'check' : intent.icon"
+            class="size-4 shrink-0"
+            :class="answers.intents.includes(intent.id) ? 'text-primary' : 'text-muted'"
+            aria-hidden="true"
+          />
+          {{ intent.label }}
+        </button>
+      </div>
+      <div class="space-y-1.5 pt-1">
+        <label :for="otherId" class="text-xs text-muted">
+          {{ copy.otherLabel }}
+        </label>
+        <UTextarea
+          :id="otherId"
+          :model-value="answers.other"
+          :maxlength="ONBOARDING_OTHER_MAX_LENGTH"
+          :rows="2"
+          autoresize
+          :placeholder="copy.otherPlaceholder"
+          class="w-full"
+          @update:model-value="setOther(String($event ?? ''))"
+        />
+      </div>
+    </fieldset>
+  </div>
+</template>

package/app/components/element/UiOverflowCount.vue

@@ -0,0 +1,31 @@
+<script setup lang="ts">
+import { UiChip, UiTooltip } from '#components'
+/**
+ * UiOverflowCount — the "+N" pill for "primary values shown + N hidden peers"
+ * fields (e.g. a domain header with 5 more aliases). Neutral count chip, no
+ * glyph (overflow primitives stay icon-light); the optional tooltip lists the
+ * hidden values. Renders nothing when count <= 0.
+ *
+ * NOT for "N more rows below" list tails (those are a disclosure or a nav link).
+ */
+
+const { count, items, size = 'xs' } = defineProps<{
+  count: number
+  /** The hidden values, listed in a tooltip. */
+  items?: string[]
+  size?: 'xs' | 'sm'
+}>()
+</script>
+
+<template>
+  <template v-if="count > 0">
+    <UiTooltip v-if="items?.length" :text="items.join(', ')">
+      <UiChip purpose="count" :size="size" tabular>
+        +{{ count }}
+      </UiChip>
+    </UiTooltip>
+    <UiChip v-else purpose="count" :size="size" tabular>
+      +{{ count }}
+    </UiChip>
+  </template>
+</template>

package/app/components/element/UiProBadge.vue

@@ -0,0 +1,19 @@
+<script setup lang="ts">
+const { size = 'sm' } = defineProps<{
+  size?: 'sm' | 'md'
+}>()
+
+const sizeClasses = {
+  sm: 'px-1.5 py-0.5 text-[9px] tracking-[0.16em]',
+  md: 'px-1.5 py-1 text-[10px] tracking-[0.16em]',
+} as const
+</script>
+
+<template>
+  <span
+    class="inline-flex shrink-0 items-center justify-center rounded-md bg-pro-500/10 font-bold uppercase leading-none text-pro-600 ring-1 ring-inset ring-pro-500/20 dark:text-pro-400"
+    :class="sizeClasses[size]"
+  >
+    Pro
+  </span>
+</template>

package/app/components/element/UiProgressCircle.vue

@@ -0,0 +1,79 @@
+<script lang="ts" setup>
+import { computed } from 'vue'
+import { clamp } from '../../utils/number'
+
+/**
+ * UiProgressCircle
+ *
+ * Shows a circular progres
+ */
+interface Props {
+  percent?: number | string
+  size?: number | string
+  strokeSize?: number | string
+  lighter?: boolean
+  /** Accessible name for the progressbar (e.g. "Indexing progress"). */
+  label?: string
+}
+
+const { percent = 0, size = 36, strokeSize = 4, lighter, label } = defineProps<Props>()
+
+const style = computed(() => ({
+  width: `${size}px`,
+  height: `${size}px`,
+}))
+
+const svg = computed(() => ({
+  'viewBox': `0 0 ${size} ${size}`,
+  'stroke-width': strokeSize,
+  'fill': 'none',
+}))
+
+const circle = computed(() => {
+  const r = Number(size) / 2
+  return {
+    cx: r,
+    cy: r,
+    r: Math.max(1, r - Number(strokeSize) / 2),
+  }
+})
+
+const offset = computed(() => clamp(100 - Number(percent), 0, 100))
+
+const bg = computed(() => {
+  return lighter
+    ? 'stroke-[var(--ui-bg-accented)]'
+    : 'stroke-[var(--ui-border)]'
+})
+</script>
+
+<template>
+  <div
+    data-ui="UiProgressCircle"
+    :style="style"
+    class="relative shrink-0"
+    role="progressbar"
+    :aria-label="label || `${Number(percent)}% complete`"
+    :aria-valuenow="Number(percent)"
+    :aria-valuemin="0"
+    :aria-valuemax="100"
+    :aria-valuetext="`${Number(percent)}%`"
+  >
+    <svg
+      v-bind="svg"
+      :class="bg"
+      class="absolute inset-0 w-full h-full"
+    >
+      <circle v-bind="circle" />
+    </svg>
+    <svg
+      v-bind="svg"
+      :stroke-dashoffset="offset"
+      :stroke-dasharray="100"
+      stroke-linecap="butt"
+      class="absolute inset-0 w-full h-full -rotate-90 stroke-primary-300"
+    >
+      <circle v-bind="circle" pathLength="100" />
+    </svg>
+  </div>
+</template>

package/app/components/element/UiProgressPercent.vue

@@ -0,0 +1,35 @@
+<script lang="ts" setup>
+import { computed } from 'vue'
+import { UiTooltip, UProgress } from '#components'
+// A %-of-total viz bar — brand-colored by default. Constrained to the
+// SemanticStatus set + `primary` (the design-system palette); the older
+// `secondary`/`tertiary`/`pro` Nuxt UI aliases were never used by a caller.
+type ProgressColor = 'primary' | 'success' | 'warning' | 'error' | 'info' | 'neutral'
+
+const { total, value, tooltip, color = 'primary' } = defineProps<{
+  total?: string | number
+  value: string | number
+  tooltip?: string
+  color?: ProgressColor
+}>()
+
+const percentage = computed(() => {
+  return (Number(value) / Number(total || 100)) * 100
+})
+</script>
+
+<template>
+  <UiTooltip :text="tooltip || `${percentage.toFixed(1)}% of clicks`" trigger-as="child">
+    <div class="min-w-0 w-full">
+      <slot />
+      <UProgress
+        :model-value="percentage || 0"
+        :color="color"
+        :aria-label="tooltip || `${percentage.toFixed(1)}% of clicks`"
+        class="opacity-90"
+        size="xs"
+        v-bind="$attrs"
+      />
+    </div>
+  </UiTooltip>
+</template>

package/app/components/element/UiRelativeTime.vue

@@ -0,0 +1,58 @@
+<script setup lang="ts">
+import { computed, onMounted, ref } from 'vue'
+import { DISPLAY_LOCALE, formatTimeAgo, toTimestampDate } from '../../composables/formatting'
+
+// Hydration-safe relative time. A bare relative string (e.g. "5m ago") is
+// derived from Date.now(), so it differs between the server render and client
+// hydration and trips a mismatch. This renders the *absolute* date during SSR
+// and the first client paint (identical on both), then swaps to the live
+// relative string after mount. The absolute date is always available in `title`.
+const { date, fallback = '—', format = 'narrow' } = defineProps<{
+  /** Unix seconds or milliseconds (number), an ISO/date string, or a Date. */
+  date: number | string | Date | null | undefined
+  /** Shown when `date` is null/invalid. */
+  fallback?: string
+  /** `narrow` ("in 3d") for dense cells; `long` ("in 3 days") where the value stands alone. */
+  format?: 'narrow' | 'long'
+}>()
+
+// The server's timezone and the browser's can differ. Render in UTC through
+// hydration, then switch the title to the viewer's timezone after mount
+// alongside the relative display text. The locale stays pinned throughout.
+const hydrationAbsoluteFormat = new Intl.DateTimeFormat(DISPLAY_LOCALE, {
+  dateStyle: 'medium',
+  timeStyle: 'short',
+  timeZone: 'UTC',
+})
+const localAbsoluteFormat = new Intl.DateTimeFormat(DISPLAY_LOCALE, { dateStyle: 'medium', timeStyle: 'short' })
+
+const parsed = computed(() => {
+  if (date == null)
+    return null
+  const d = toTimestampDate(date)
+  return Number.isNaN(d.getTime()) ? null : d
+})
+
+const mounted = ref(false)
+onMounted(() => {
+  mounted.value = true
+})
+
+const absolute = computed(() => {
+  if (!parsed.value)
+    return ''
+  return (mounted.value ? localAbsoluteFormat : hydrationAbsoluteFormat).format(parsed.value)
+})
+const display = computed(() => {
+  if (!parsed.value)
+    return fallback
+  // `formatTimeAgo` (and thus Date.now()) is only read after mount — never on
+  // the server — so SSR and first-paint HTML stay identical.
+  return mounted.value ? (formatTimeAgo(date, format) ?? absolute.value) : absolute.value
+})
+</script>
+
+<template>
+  <time v-if="parsed" :datetime="parsed.toISOString()" :title="absolute">{{ display }}</time>
+  <span v-else>{{ fallback }}</span>
+</template>

package/app/components/element/UiScrollFade.vue

@@ -0,0 +1,16 @@
+<script setup lang="ts">
+</script>
+
+<template>
+  <div class="relative overflow-y-auto">
+    <div
+      aria-hidden="true"
+      class="sticky top-0 z-[5] h-5 -mb-5 pointer-events-none bg-gradient-to-b from-default to-transparent [overflow-anchor:none]"
+    />
+    <slot />
+    <div
+      aria-hidden="true"
+      class="sticky bottom-0 z-[5] h-5 -mt-5 pointer-events-none bg-gradient-to-t from-default to-transparent [overflow-anchor:none]"
+    />
+  </div>
+</template>