@nuxtseo/design-system 0.0.0-stage → 0.1.0

package/app/components/data/UiChartDataReveal.vue

@@ -0,0 +1,81 @@
+<script setup lang="ts">
+import type { VNodeChild } from 'vue'
+import { nextTick, ref, useId } from 'vue'
+
+/**
+ * UiChartDataReveal
+ *
+ * The keyboard path to a chart's values. Chart readouts (crosshair, point and
+ * band tooltips) open on pointer hover only, and each chart already carries its
+ * data as a screen-reader table. This wraps that table: it stays visually
+ * hidden, and a "Show data table" button appears on keyboard focus and lays the
+ * same table over the chart. Escape or the button hides it again. Pointer users
+ * see no change.
+ *
+ * The host chart root must be `position: relative`; the open table covers it.
+ */
+
+defineSlots<{ default?: () => VNodeChild }>()
+
+const shown = ref(false)
+const panelId = useId()
+const toggle = ref<HTMLButtonElement>()
+
+async function hide(): Promise<void> {
+  shown.value = false
+  await nextTick()
+  toggle.value?.focus()
+}
+</script>
+
+<template>
+  <button
+    ref="toggle"
+    type="button"
+    data-ui="UiChartDataReveal"
+    class="ui-chart-data-reveal__toggle rounded-md bg-default px-2 py-1 focus-visible:px-2 focus-visible:py-1 text-xs font-medium text-default ring-1 ring-default focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary"
+    :class="shown ? 'absolute top-1 right-1 z-30' : 'sr-only focus-visible:not-sr-only focus-visible:absolute focus-visible:top-1 focus-visible:right-1 focus-visible:z-30'"
+    :aria-expanded="shown"
+    :aria-controls="panelId"
+    @click="shown ? hide() : shown = true"
+    @keydown.esc="shown && hide()"
+  >
+    {{ shown ? 'Hide data table' : 'Show data table' }}
+  </button>
+  <div
+    :id="panelId"
+    :class="shown ? 'ui-chart-data-reveal__panel absolute inset-0 z-20 overflow-auto rounded-md bg-default p-2 pt-9 ring-1 ring-default' : 'sr-only'"
+    @keydown.esc.stop="shown && hide()"
+  >
+    <slot />
+  </div>
+</template>
+
+<style scoped>
+.ui-chart-data-reveal__panel :deep(table) {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 0.75rem;
+  font-variant-numeric: tabular-nums;
+}
+
+.ui-chart-data-reveal__panel :deep(caption) {
+  padding-bottom: 0.25rem;
+  text-align: left;
+  font-weight: 600;
+  color: var(--ui-text-highlighted);
+}
+
+.ui-chart-data-reveal__panel :deep(th),
+.ui-chart-data-reveal__panel :deep(td) {
+  padding: 0.25rem 0.5rem;
+  border-bottom: 1px solid var(--ui-border);
+  text-align: left;
+  white-space: nowrap;
+}
+
+.ui-chart-data-reveal__panel :deep(thead th) {
+  color: var(--ui-text-muted);
+  font-weight: 500;
+}
+</style>

package/app/components/data/UiChartFrame.vue

@@ -0,0 +1,123 @@
+<script lang="ts" setup>
+import type { MotionValue } from 'motion-v'
+import type { ChartBrushRange } from '../../composables/useChartBrush'
+import type { ChartAnnotation, ChartAnnotationOptions } from '../../utils/chartAnnotations'
+import { computed, ref } from 'vue'
+import { ClientOnly, UiChartAnnotations, UiChartBrushOverlay, UiChartTooltip } from '#components'
+import { ANNOTATION_TONE_CLASS, annotationsOnDay } from '../../utils/chartAnnotations'
+
+// Bundles the chart's hover tooltip + brush selection overlay into one tag, and
+// (opt-in) the annotation marker overlay + same-day annotations inside the
+// tooltip. Card owns the wrap div + ref binding (the brush composable's `wrapRef`
+// doesn't survive being passed through a child); this just consolidates the
+// overlay calls + their prop wiring.
+//
+// Tooltip anchors to the cursor (spring-tracked) — see UiChartTooltip. Markers
+// render via UiChartAnnotations (shared with non-frame charts); both require the
+// host wrap to be `position: relative` with zero horizontal margin (wrap width
+// == plot x-span) so the CSS left-percentage maps to the right screen position.
+
+const props = defineProps<{
+  // --- brush state (useChartBrush) ---
+  dragRange: ChartBrushRange | null
+  selectionLeft: number
+  selectionWidth: number
+  // --- hover state (useChartHover) ---
+  tooltipVisible: boolean
+  cardSpring: MotionValue<number>
+  cursorYSpring: MotionValue<number>
+  placement?: 'above' | 'below'
+  /** Label shown on the leading row of the tooltip (typically the hovered date). */
+  hoverLabel: string
+  /**
+   * Optional event annotations rendered as thin vertical marker lines + a dot at
+   * the bottom of the plot area. Default [] — no change to existing charts (opt-in).
+   * Requires `xDomain` to resolve pixel positions. When `xDomain` is absent,
+   * annotations are silently skipped.
+   */
+  annotations?: ChartAnnotation[]
+  /** Marker presentation shared by single and stacked annotation popovers. */
+  annotationOptions?: ChartAnnotationOptions
+  /**
+   * The visible x range [min, max] of the chart. Pass Date objects, ISO strings,
+   * or epoch-ms numbers. Used to convert each annotation's `x` value to a CSS
+   * left-percentage. Required when `annotations` are provided.
+   */
+  xDomain?: [Date | string | number, Date | string | number]
+  /**
+   * The currently-hovered x value (the day the crosshair is on). When it lands on
+   * a day that carries annotations, those annotations are surfaced inside the
+   * hover tooltip (a tone dot + label) so the marker isn't a hover-only native
+   * title. Pass the hovered datum's date; omit to keep annotations marker-only.
+   */
+  hoverX?: Date | string | number | null
+}>()
+
+const emit = defineEmits<{
+  /** Forwarded from the marker overlay: a user-editable annotation was activated. */
+  annotationEdit: [annotation: ChartAnnotation]
+}>()
+
+const annotationInteracting = ref(false)
+
+/** Annotations on the hovered day — surfaced inside the tooltip (dot + label). */
+const tooltipAnnotations = computed(() =>
+  annotationsOnDay(props.annotations ?? [], props.hoverX).map((ann, id) => ({
+    id,
+    label: ann.label,
+    description: ann.description,
+    toneClass: ANNOTATION_TONE_CLASS[ann.tone ?? 'neutral'],
+  })),
+)
+</script>
+
+<template>
+  <ClientOnly>
+    <UiChartTooltip
+      :x="cardSpring"
+      :y="cursorYSpring"
+      :visible="tooltipVisible && !annotationInteracting"
+      :placement="placement"
+      :label="hoverLabel"
+    >
+      <template v-if="$slots['tooltip-header']" #header>
+        <slot name="tooltip-header" />
+      </template>
+      <slot name="tooltip-rows" />
+      <!-- Annotations on the hovered day: a tone dot + label, separated from the
+           metric rows. Dot carries the semantic tone, label stays neutral text
+           (color-budget: colored dot + neutral text). -->
+      <div v-if="tooltipAnnotations.length" class="mt-1.5 pt-1.5 border-t border-default space-y-1">
+        <div v-for="ann in tooltipAnnotations" :key="ann.id" class="grid grid-cols-[auto_minmax(0,1fr)] gap-x-1.5">
+          <span :class="ann.toneClass" class="size-1.5 rounded-full shrink-0 mt-1" aria-hidden="true" />
+          <div class="min-w-0">
+            <p class="text-sm font-medium text-default truncate">
+              {{ ann.label }}
+            </p>
+            <p v-if="ann.description" class="text-sm text-muted mt-0.5">
+              {{ ann.description }}
+            </p>
+          </div>
+        </div>
+      </div>
+      <template v-if="$slots['tooltip-footer']" #footer>
+        <slot name="tooltip-footer" />
+      </template>
+    </UiChartTooltip>
+
+    <UiChartBrushOverlay
+      :drag-range="dragRange"
+      :selection-left="selectionLeft"
+      :selection-width="selectionWidth"
+    />
+
+    <!-- Annotation markers (thin vertical lines + dots) — shared overlay. -->
+    <UiChartAnnotations
+      :annotations="annotations"
+      :x-domain="xDomain"
+      :options="annotationOptions"
+      @edit="emit('annotationEdit', $event)"
+      @interaction-change="annotationInteracting = $event"
+    />
+  </ClientOnly>
+</template>

package/app/components/data/UiChartTooltip.vue

@@ -0,0 +1,81 @@
+<script lang="ts" setup>
+import type { MotionValue } from 'motion-v'
+import { AnimatePresence, motion, useReducedMotion } from 'motion-v'
+import { computed } from 'vue'
+// Single floating readout for time-series chart hover. Anchored to the cursor
+// position (spring-tracked x + y), sitting either above or below depending on
+// available room. Uses the shared overlay chrome (`.ui-popover-content` +
+// `bg-default`) so it reads as a solid raised card in both light/dark — the
+// metric rows consumers pass in use the standard text tokens (text-muted /
+// text-default / text-dimmed), which only stay legible on a non-inverted
+// surface. No companion crosshair pill, no chart-edge pinning.
+//
+// Position decomposition:
+//   - Outer motion.div: spring-tracked translate to cursor (x, y) in chart
+//     coordinates. Acts as the anchor point.
+//   - Inner div: applies `-translate-x-1/2` (centre horizontally on cursor)
+//     plus `-translate-y-full -mt-3` (anchor bottom edge above cursor) or
+//     `mt-3` (anchor top edge below cursor) based on `placement`.
+//
+// Slots:
+//   #header  — optional badge row (e.g. GSC's "Estimated")
+//   default  — metric rows (each card decides layout)
+//   #footer  — optional comparison-date strip
+
+defineProps<{
+  x: MotionValue<number>
+  y: MotionValue<number>
+  visible: boolean
+  /** Date label always rendered on the leading row. */
+  label: string
+  /** Which side of the cursor the tooltip sits on. */
+  placement?: 'above' | 'below'
+}>()
+
+// Reduced motion: drop the scale pop + placement-translate easing; the tooltip
+// fades only (sibling chart overlays gate the same way).
+const reduced = useReducedMotion()
+const enter = computed(() => (reduced.value ? { opacity: 1 } : { opacity: 1, scale: 1 }))
+const initial = computed(() => (reduced.value ? { opacity: 0 } : { opacity: 0, scale: 0.96 }))
+</script>
+
+<template>
+  <AnimatePresence>
+    <motion.div
+      v-if="visible"
+      key="chart-tooltip"
+      :initial="initial"
+      :animate="enter"
+      :exit="initial"
+      :transition="{ duration: 0.12, ease: [0.22, 1, 0.36, 1] }"
+      :style="{ x, y }"
+      class="absolute top-0 left-0 z-10 pointer-events-none"
+    >
+      <div
+        class="ui-popover-content min-w-[120px] max-w-[280px] rounded-md bg-default text-default ring ring-default -translate-x-1/2 transition-transform duration-150 ease-out motion-reduce:transition-none" :class="[
+          (placement ?? 'above') === 'above' ? '-translate-y-full -mt-3' : 'mt-3',
+        ]"
+      >
+        <div
+          v-if="$slots.header"
+          class="px-2 pt-1.5 pb-1 border-b border-muted flex items-center gap-2"
+        >
+          <slot name="header" />
+        </div>
+        <div class="px-2 py-1 flex items-center gap-2 whitespace-nowrap">
+          <span class="text-mini font-medium tabular-nums text-muted">{{ label }}</span>
+          <div v-if="$slots.default" class="h-3 w-px bg-[var(--ui-border)]" />
+          <div class="flex-1 flex flex-col gap-px text-mini">
+            <slot />
+          </div>
+        </div>
+        <div
+          v-if="$slots.footer"
+          class="px-2 pt-1 pb-1.5 border-t border-muted flex items-center justify-between gap-2 text-mini"
+        >
+          <slot name="footer" />
+        </div>
+      </div>
+    </motion.div>
+  </AnimatePresence>
+</template>

package/app/components/data/UiCoverageNote.vue

@@ -0,0 +1,90 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { NuxtLink, UiIcon } from '#components'
+/**
+ * UiCoverageNote — the quiet "N of M known · View all" evidence-coverage line
+ * that sits under a typed evidence browser. Mirrors pro-actions's
+ * `collectionCoverageSchema` (`layers/pro/actions/shared/contracts/action-evidence.ts`)
+ * structurally, per the `UiActionTitle`/`ActionTitleSegment` "keep in sync"
+ * precedent (ADR-0042: design-system MAY know the shape, never the runtime
+ * that builds it — importing the pro-layer's zod schema here would invert the
+ * layer graph).
+ *
+ * Color budget: this is a caption, not a status. It never tints its value —
+ * only a single fixed neutral dot (the `UiFactsGrid` status-dot rhythm,
+ * without the semantic color) marks it as a coverage caption at a glance.
+ */
+
+/** Keep in sync with pro-actions's `CollectionCoverage` (`action-evidence.ts`). */
+export type CollectionCoverage
+  = | { _tag: 'complete', knownTotal: number }
+    | { _tag: 'partial', reportedTotal: number, knownTotal: number, limitation: string }
+    | { _tag: 'count-only', reportedTotal: number, limitation: string }
+    | { _tag: 'unknown', knownTotal: number, limitation: string }
+    | { _tag: 'unavailable', limitation: string }
+
+const { coverage, to } = defineProps<{
+  coverage: CollectionCoverage
+  /** Deep link for the "View all" tail. Canonical copy — never re-worded per call site. */
+  to?: string
+}>()
+
+// Split copy into a leading numeral (numerals-display) + trailing words, so
+// "7 of 9 known" reads with figures set apart from prose the same way every
+// other numeric fact does. `complete`/`unavailable` have no leading count
+// worth isolating (either it's redundant with the check glyph, or there's
+// nothing counted yet) and render as plain text.
+const parts = computed((): { lead?: string, rest: string } => {
+  switch (coverage._tag) {
+    case 'complete':
+      return { rest: `All ${coverage.knownTotal} known` }
+    case 'partial':
+      return { lead: `${coverage.knownTotal} of ${coverage.reportedTotal}`, rest: 'known' }
+    case 'count-only':
+      return { lead: `${coverage.reportedTotal}`, rest: 'total, not yet itemized' }
+    case 'unknown':
+      return { lead: `${coverage.knownTotal}`, rest: 'known, total not yet counted' }
+    case 'unavailable':
+      return { rest: 'Evidence still compiling' }
+    default:
+      return { rest: '' }
+  }
+})
+
+// `partial` is the one state where evidence is actively still growing — the
+// dot earns a single settle-once pulse to say "still counting" without
+// nagging on every re-render. Every other tag is a steady-state read.
+const isGrowing = computed(() => coverage._tag === 'partial')
+const isComplete = computed(() => coverage._tag === 'complete')
+</script>
+
+<template>
+  <p class="flex items-center gap-1.5 text-xs text-muted" data-ui="UiCoverageNote">
+    <UiIcon
+      v-if="isComplete"
+      name="check"
+      class="size-3 shrink-0 text-dimmed"
+      aria-hidden="true"
+    />
+    <span
+      v-else
+      class="size-1 shrink-0 rounded-full bg-[var(--ui-border)]"
+      :class="isGrowing && 'coverage-dot-pulse-once'"
+      aria-hidden="true"
+    />
+    <span>
+      <span v-if="parts.lead" class="numerals-display text-default">{{ parts.lead }}</span>
+      <template v-if="parts.lead">{{ ' ' }}</template>{{ parts.rest }}
+    </span>
+    <template v-if="to">
+      <span class="text-dimmed" aria-hidden="true"> · </span>
+      <component
+        :is="NuxtLink"
+        :to="to"
+        class="text-muted underline-offset-2 hover:text-default hover:underline"
+      >
+        View all
+      </component>
+    </template>
+  </p>
+</template>

package/app/components/data/UiCwvSparkline.vue

@@ -0,0 +1,188 @@
+<script setup lang="ts">
+import { motion, stagger, useReducedMotion } from 'motion-v'
+import { computed } from 'vue'
+import { indexingVizColors } from '../../composables/dataVizColors'
+
+// Mini, dependency-free echo of CwvMetricChart: faint good/ni/poor stacked bars
+// across time, meant as an ambient background for a KPI tile (the Core Web
+// Vitals card). It is decorative — the exact composition does not need to be
+// precise — so when no per-period histogram is supplied it synthesises a
+// plausible series from the overall `status`. Sibling to UiSparkline.
+
+interface Band { good: number, ni: number, poor: number }
+
+interface Props {
+  /** Per-period composition (good/ni/poor percentages, 0–100). When set, the svg is named with the latest period's shares; when absent, the synthesised bars are hidden from assistive tech. */
+  data?: Band[]
+  /** Drives the synthesised series + bar emphasis when `data` is absent. */
+  status?: 'pass' | 'ni' | 'fail' | null
+  width?: number | string
+  height?: number | string
+  /** Number of bars when synthesising. */
+  bars?: number
+  /** SVG preserveAspectRatio — "none" stretches to fill a container. */
+  preserveAspectRatio?: string
+  /** Base opacity for the bars. Kept moderate so the card value stays dominant
+      while the composition reads clearly. */
+  opacity?: number
+  /** Hover state, fed from a parent (e.g. the enclosing UiStat card). On hover
+      the bars rise to full height one by one. */
+  hovered?: boolean
+}
+
+const {
+  data,
+  status = null,
+  width = '100%',
+  height = '100%',
+  bars = 22,
+  preserveAspectRatio = 'none',
+  opacity = 0.6,
+  hovered = false,
+} = defineProps<Props>()
+
+// Respect reduced-motion: skip the staggered hover rise entirely.
+const reduced = useReducedMotion()
+
+// On hover the bars settle up to full height in sequence; at rest they sit a
+// touch compressed. scaleY anchored at each bar's base keeps the good/ni/poor
+// proportions intact while the whole column rises.
+const container = {
+  rest: {},
+  hover: { transition: { delayChildren: stagger(0.05, { ease: 'easeInOut' }) } },
+}
+// A smooth spring with a single gentle overshoot — fluid wave up the bars
+// rather than a jittery bounce.
+const barVariants = {
+  rest: { scaleY: 0.72, opacity: 0.85 },
+  hover: {
+    scaleY: 1,
+    opacity: 1,
+    transition: { type: 'spring' as const, stiffness: 190, damping: 16, mass: 0.8 },
+  },
+}
+
+const vbW = 120
+const vbH = 40
+
+// Deterministic wobble (no Math.random — keeps SSR + reloads stable).
+function wobble(i: number, amp: number) {
+  return (Math.sin(i * 1.3) * 0.5 + Math.sin(i * 0.5) * 0.3 + Math.cos(i * 2.7) * 0.2) * amp
+}
+
+const series = computed<Band[]>(() => {
+  if (data?.length)
+    return data
+  // Synthesise a plausible composition trend from the status.
+  const base: Band = status === 'pass'
+    ? { good: 78, ni: 16, poor: 6 }
+    : status === 'fail'
+      ? { good: 36, ni: 30, poor: 34 }
+      : { good: 56, ni: 31, poor: 13 } // ni / unknown
+  return Array.from({ length: bars }, (_, i) => {
+    const poor = Math.max(2, base.poor + wobble(i, 8))
+    const ni = Math.max(4, base.ni + wobble(i + 7, 6))
+    const good = Math.max(0, 100 - poor - ni)
+    return { good, ni, poor }
+  })
+})
+
+// The chart fills, not the raw semantic hexes: light mode steps success and
+// warning down so the bars clear 3:1 on white (dataVizColors.ts).
+function withAlpha(color: string, a: number): string {
+  return `color-mix(in srgb, ${color} ${Math.round(a * 10000) / 100}%, transparent)`
+}
+
+const colors = computed(() => ({
+  good: withAlpha(indexingVizColors.indexed.hex, opacity),
+  ni: withAlpha(indexingVizColors.notIndexed.hex, opacity),
+  poor: withAlpha(indexingVizColors.error.hex, opacity),
+}))
+
+// A synthesised series is decorative: it echoes `status`, not measured data,
+// so it stays out of the accessibility tree. Measured data names the latest
+// period's shares, so the composition does not rest on colour alone.
+const pct = (n: number, total: number) => `${Math.round(n / total * 100)}%`
+const ariaLabel = computed(() => {
+  const last = data?.at(-1)
+  if (!last)
+    return undefined
+  const total = last.good + last.ni + last.poor || 1
+  return `Core Web Vitals, latest period: ${pct(last.good, total)} good, ${pct(last.ni, total)} needs improvement, ${pct(last.poor, total)} poor`
+})
+
+interface Seg { y: number, h: number, fill: string }
+interface Bar { x: number, w: number, segs: Seg[] }
+
+const barColumns = computed<Bar[]>(() => {
+  const s = series.value
+  if (!s.length)
+    return []
+  const gap = 0.25
+  const slot = vbW / s.length
+  const w = Math.max(0.5, slot * (1 - gap))
+  return s.map((band, i) => {
+    const total = band.good + band.ni + band.poor || 1
+    const x = i * slot + (slot - w) / 2
+    // Stack from the bottom: good → ni → poor (poor sits on top, like CrUX).
+    let yTop = vbH
+    const stack: [number, string][] = [
+      [band.good / total, colors.value.good],
+      [band.ni / total, colors.value.ni],
+      [band.poor / total, colors.value.poor],
+    ]
+    const segs: Seg[] = stack.map(([frac, fill]) => {
+      const h = frac * vbH
+      yTop -= h
+      return { y: yTop, h, fill }
+    })
+    return { x, w, segs }
+  })
+})
+</script>
+
+<template>
+  <svg
+    data-ui="UiCwvSparkline"
+    :width="width"
+    :height="height"
+    :viewBox="`0 0 ${vbW} ${vbH}`"
+    :preserveAspectRatio="preserveAspectRatio"
+    :role="ariaLabel ? 'img' : undefined"
+    :aria-label="ariaLabel"
+    :aria-hidden="ariaLabel ? undefined : 'true'"
+  >
+    <!-- tabindex -1: motion-v binds focus listeners for its gesture support,
+         and Chromium makes any SVG element with a focus listener a Tab stop.
+         These groups carry no name or action. -->
+    <motion.g
+      :variants="container"
+      initial="rest"
+      :animate="hovered && !reduced ? 'hover' : 'rest'"
+      tabindex="-1"
+    >
+      <motion.g
+        v-for="(bar, i) in barColumns"
+        :key="i"
+        :variants="barVariants"
+        :style="{ transformBox: 'fill-box', transformOrigin: 'bottom' }"
+        tabindex="-1"
+      >
+        <!-- The page-coloured edge splits good, needs improvement and poor,
+             so the bands read apart without relying on hue. -->
+        <rect
+          v-for="(seg, j) in bar.segs"
+          :key="j"
+          :x="bar.x"
+          :y="seg.y"
+          :width="bar.w"
+          :height="seg.h"
+          :fill="seg.fill"
+          stroke="var(--ui-bg)"
+          stroke-width="0.6"
+          vector-effect="non-scaling-stroke"
+        />
+      </motion.g>
+    </motion.g>
+  </svg>
+</template>