@nuxtseo/design-system 0.0.0-stage → 0.1.1

package/app/composables/dataVizColors.ts

@@ -0,0 +1,350 @@
+import type { SemanticUiIcon } from '../../shared/icons'
+import { semanticColors } from './semanticColors'
+
+/**
+ * Data-viz palette — chart-only colours, distinct from semantic status colours.
+ *
+ * Brand seam. Every identity slot reads a `--ui-viz-<slot>` custom property,
+ * so a site that extends this layer recolours a chart from its own CSS:
+ *
+ *   :root { --ui-viz-clicks: var(--ui-primary); }
+ *
+ * The `hex` field is `var(--ui-viz-<slot>, <hex>)`: SVG paint attributes,
+ * inline styles and `color-mix()` all resolve it, on the server and in the
+ * browser, so no JS colour read is needed. It is a CSS colour, not a hex
+ * literal: never parse it, mix it with `color-mix()` instead. The `bg`,
+ * `text` and `dot` classes are `*-viz-<slot>` utilities, declared in
+ * `css/global.css` over the same property, with this site's Tailwind hue as
+ * the fallback. Unset, every slot renders exactly the colour it did before.
+ * Named hue presets (`presetVizColors.blue`) stay literal: they are explicit
+ * hue requests, not identities.
+ *
+ * Three concerns:
+ *  1. Metric identity — each GSC / CWV metric has a fixed colour so multi-series
+ *     charts are readable at a glance (clicks = blue, impressions = purple, …).
+ *  2. Category palettes — ordered swatches for series with no inherent identity
+ *     (top pages, country donut, device split).
+ *  3. Threshold / brand splits — colours that carry meaning (brand vs non-brand
+ *     traffic, indexing success vs error).
+ *
+ * Colour MUST encode information; never decorate. Routed through `vizColorMap`
+ * so legend chips and sparklines share one lookup.
+ */
+
+export interface VizColor {
+  bg: string
+  hex: string
+  text: string
+  dot: string
+}
+
+/**
+ * `dot` is the solid identity colour (legend dots, sparkline strokes); `bg` is its
+ * translucent fill variant for proportion bars / badge backgrounds so the value sitting
+ * on top stays readable. Standard `bg-{hue}-{shade}` and `bg-viz-{slot}` tokens get a `/15` fill; tokens that
+ * already carry an opacity modifier or use a semantic name (e.g. `bg-accented`) pass through.
+ *
+ * The `/15` variants are built at runtime, so Tailwind's content scanner never sees them
+ * as literals — they must be safelisted (see `vizFillSafelist` below) or the bar renders
+ * transparent.
+ */
+function viz(dot: string, hex: string, text: string): VizColor {
+  const bg = /^bg-(?:[a-z]+-\d+|viz-[a-z0-9-]+)$/.test(dot) ? `${dot}/15` : dot
+  return { bg, hex, text, dot }
+}
+
+/**
+ * Tailwind JIT safelist. Every `bg-<hue>-<shade>/15` fill `viz()` can emit must appear
+ * here as a literal so Tailwind's source scanner generates the CSS (clicks/impressions
+ * worked only because `periodVizColors` happened to spell them out). Keep in sync with
+ * the `viz()` inputs below — a missing entry makes that metric's proportion bar invisible.
+ */
+export const vizFillSafelist = [
+  // Named hue presets.
+  'bg-blue-500/15',
+  'bg-purple-500/15',
+  'bg-emerald-500/15',
+  'bg-orange-500/15',
+  'bg-cyan-500/15',
+  'bg-amber-500/15',
+  'bg-red-500/15',
+  // Identity slots.
+  'bg-viz-clicks/15',
+  'bg-viz-impressions/15',
+  'bg-viz-ctr/15',
+  'bg-viz-position/15',
+  'bg-viz-sessions/15',
+  'bg-viz-users/15',
+  'bg-viz-pageviews/15',
+  'bg-viz-lcp/15',
+  'bg-viz-inp/15',
+  'bg-viz-cls/15',
+  'bg-viz-device-desktop/15',
+  'bg-viz-device-mobile/15',
+  'bg-viz-device-tablet/15',
+  'bg-viz-brand/15',
+  'bg-viz-non-brand/15',
+  'bg-viz-rank-1/15',
+  'bg-viz-rank-2/15',
+  'bg-viz-rank-3/15',
+  'bg-viz-rank-4/15',
+  'bg-viz-rank-5/15',
+  'bg-viz-rank-6/15',
+  'bg-viz-rank-7/15',
+  'bg-viz-rank-8/15',
+  'bg-viz-rank-9/15',
+  'bg-viz-rank-10/15',
+  'bg-viz-resource-document/15',
+  'bg-viz-resource-script/15',
+  'bg-viz-resource-stylesheet/15',
+  'bg-viz-resource-image/15',
+  'bg-viz-resource-font/15',
+] as const
+
+/**
+ * The softer neutral chart grey, for "Other" residual slots and the deep
+ * position tiers. 75% alpha keeps it apart from the full neutral and still
+ * clears 3:1 against the page in both modes (WCAG 1.4.11); the old 50% measured
+ * 1.6:1 on white and 2.5:1 on dark. `color-mix` keeps it a CSS colour, so it
+ * follows `--ui-viz-neutral`.
+ */
+const neutralHalf = `color-mix(in srgb, ${semanticColors.neutral.hex} 75%, transparent)`
+
+/**
+ * GSC metric identity — pinned so every clicks chart reads blue, every
+ *  impressions chart reads purple, regardless of consumer.
+ */
+export const gscMetricColors = {
+  clicks: viz('bg-viz-clicks', 'var(--ui-viz-clicks, #3b82f6)', 'text-viz-clicks'),
+  impressions: viz('bg-viz-impressions', 'var(--ui-viz-impressions, #a855f7)', 'text-viz-impressions'),
+  ctr: viz('bg-viz-ctr', 'var(--ui-viz-ctr, var(--_viz-ctr, #10b981))', 'text-viz-ctr'),
+  position: viz('bg-viz-position', 'var(--ui-viz-position, var(--_viz-position, #f97316))', 'text-viz-position'),
+} as const satisfies Record<string, VizColor>
+
+/**
+ * Web Analytics metric identity (ADR-0032). Paired with `text` / `dot` tailwind
+ * classes because the consumers (`ProCardAnalytics`) bind these via `:class`,
+ * whereas the chart line/area colours live inline next to the SVG gradients
+ * in `ProGraphAnalytics`.
+ */
+export const analyticsMetricColors = {
+  sessions: viz('bg-viz-sessions', 'var(--ui-viz-sessions, #3b82f6)', 'text-viz-sessions'),
+  users: viz('bg-viz-users', 'var(--ui-viz-users, var(--_viz-users, #06b6d4))', 'text-viz-users'),
+  pageviews: viz('bg-viz-pageviews', 'var(--ui-viz-pageviews, #a855f7)', 'text-viz-pageviews'),
+} as const satisfies Record<string, VizColor>
+
+/**
+ * Core Web Vitals metric identity. `tbt` (synthetic lab) shares INP's amber —
+ *  it occupies the same responsiveness slot when the source is Lighthouse.
+ */
+export const cwvMetricColors = {
+  lcp: viz('bg-viz-lcp', 'var(--ui-viz-lcp, #3b82f6)', 'text-viz-lcp'),
+  inp: viz('bg-viz-inp', 'var(--ui-viz-inp, var(--_viz-inp, #f59e0b))', 'text-viz-inp'),
+  tbt: viz('bg-viz-inp', 'var(--ui-viz-inp, var(--_viz-inp, #f59e0b))', 'text-viz-inp'),
+  cls: viz('bg-viz-cls', 'var(--ui-viz-cls, #a855f7)', 'text-viz-cls'),
+} as const satisfies Record<string, VizColor>
+
+/**
+ * Period-comparison palette — current period vs comparison (prev/YoY) shown in
+ * the date-range picker, sparklines, and any "vs" pill. Pinned so all comparison
+ * surfaces share one hue.
+ */
+export const periodVizColors = {
+  // The text shade is per mode (css/global.css). The 400 shades measure under
+  // 3:1 on a light page, so light mode reads the 600 shade, which passes AA.
+  current: viz('bg-viz-current/15', 'var(--ui-viz-current, #3b82f6)', 'text-viz-current'),
+  comparison: viz('bg-viz-comparison/15', 'var(--ui-viz-comparison, #a855f7)', 'text-viz-comparison'),
+} as const satisfies Record<string, VizColor>
+
+/**
+ * Success and warning as chart marks. The semantic hexes (green 500 2.3:1,
+ * yellow 500 1.9:1 on white) fall under the 3:1 a mark needs (WCAG 1.4.11),
+ * so light mode reads a deeper `--_viz-success` / `--_viz-warning` from
+ * css/global.css. Kept apart from `semanticColors` because some callers parse
+ * those hexes.
+ */
+const chartSuccess = `var(--_viz-success, ${semanticColors.success.hex})`
+const chartWarning = `var(--_viz-warning, ${semanticColors.warning.hex})`
+
+/** Indexing status — bridges semantic status into the chart palette. */
+export const indexingVizColors = {
+  indexed: { bg: 'bg-success', hex: chartSuccess, text: 'text-success', dot: 'bg-success' },
+  notIndexed: { bg: 'bg-warning', hex: chartWarning, text: 'text-warning', dot: 'bg-warning' },
+  excluded: { bg: 'bg-warning', hex: chartWarning, text: 'text-warning', dot: 'bg-warning' },
+  errors: { bg: 'bg-error', hex: semanticColors.error.hex, text: 'text-error', dot: 'bg-error' },
+  error: { bg: 'bg-error', hex: semanticColors.error.hex, text: 'text-error', dot: 'bg-error' },
+  crawled: { bg: 'bg-info', hex: semanticColors.info.hex, text: 'text-info', dot: 'bg-info' },
+} as const satisfies Record<string, VizColor>
+
+/**
+ * Position-distribution tiers — premier (1–3) reads warning-amber so the eye
+ *  goes there; second-page / beyond fade into muted neutrals. `beyond`/`deep`
+ *  carry the softer neutral (`neutralHalf`, as in the "other" slots below), so a
+ *  stacked chart can still tell the two neutral tiers apart.
+ */
+export const positionDistColors = {
+  premier: { bg: 'bg-warning', hex: chartWarning, text: 'text-warning', dot: 'bg-warning' },
+  pageOne: { bg: 'bg-info', hex: semanticColors.info.hex, text: 'text-info', dot: 'bg-info' },
+  secondPage: { bg: 'bg-muted', hex: semanticColors.neutral.hex, text: 'text-muted', dot: 'bg-muted' },
+  beyond: { bg: 'bg-elevated', hex: neutralHalf, text: 'text-muted', dot: 'bg-elevated' },
+  top3: { bg: 'bg-warning', hex: chartWarning, text: 'text-warning', dot: 'bg-warning' },
+  page1: { bg: 'bg-info', hex: semanticColors.info.hex, text: 'text-info', dot: 'bg-info' },
+  page2: { bg: 'bg-muted', hex: semanticColors.neutral.hex, text: 'text-muted', dot: 'bg-muted' },
+  deep: { bg: 'bg-elevated', hex: neutralHalf, text: 'text-muted', dot: 'bg-elevated' },
+} as const satisfies Record<string, VizColor>
+
+/**
+ * Device split — desktop / mobile / tablet. Lighter shoulder hues so three
+ *  values can sit beside each other without one dominating.
+ */
+export const gscDeviceColors = {
+  desktop: viz('bg-viz-device-desktop', 'var(--ui-viz-device-desktop, var(--_viz-device-desktop, #60a5fa))', 'text-viz-device-desktop'),
+  mobile: viz('bg-viz-device-mobile', 'var(--ui-viz-device-mobile, var(--_viz-device-mobile, #4ade80))', 'text-viz-device-mobile'),
+  tablet: viz('bg-viz-device-tablet', 'var(--ui-viz-device-tablet, var(--_viz-device-tablet, #fbbf24))', 'text-viz-device-tablet'),
+} as const satisfies Record<string, VizColor>
+
+/**
+ * Brand vs non-brand traffic split. Violet pulls toward brand identity, emerald
+ *  reads as "earned" non-brand traffic.
+ */
+export const gscBrandSplitColors = {
+  brand: viz('bg-viz-brand', 'var(--ui-viz-brand, #8b5cf6)', 'text-viz-brand'),
+  nonBrand: viz('bg-viz-non-brand', 'var(--ui-viz-non-brand, var(--_viz-non-brand, #10b981))', 'text-viz-non-brand'),
+} as const satisfies Record<'brand' | 'nonBrand', VizColor>
+
+/**
+ * Top-entity stacked trend (`UiTopEntityStackChart`): 10 identity hues, ranked
+ * by entity rank, plus the neutral "Other" residual in the last slot. Every
+ * current caller tracks the top 5; the spare hues keep a wider caller safe. The
+ * first five hues are the ones `gscTopPagesColors` uses, so a page and a query
+ * of the same rank read alike.
+ */
+export const gscTopEntityColors: VizColor[] = [
+  viz('bg-viz-rank-1', 'var(--ui-viz-rank-1, #3b82f6)', 'text-viz-rank-1'),
+  viz('bg-viz-rank-2', 'var(--ui-viz-rank-2, #a855f7)', 'text-viz-rank-2'),
+  viz('bg-viz-rank-3', 'var(--ui-viz-rank-3, var(--_viz-rank-3, #34d399))', 'text-viz-rank-3'),
+  viz('bg-viz-rank-4', 'var(--ui-viz-rank-4, var(--_viz-rank-4, #f97316))', 'text-viz-rank-4'),
+  viz('bg-viz-rank-5', 'var(--ui-viz-rank-5, var(--_viz-rank-5, #06b6d4))', 'text-viz-rank-5'),
+  viz('bg-viz-rank-6', 'var(--ui-viz-rank-6, #ec4899)', 'text-viz-rank-6'),
+  viz('bg-viz-rank-7', 'var(--ui-viz-rank-7, var(--_viz-rank-7, #fbbf24))', 'text-viz-rank-7'),
+  viz('bg-viz-rank-8', 'var(--ui-viz-rank-8, #818cf8)', 'text-viz-rank-8'),
+  viz('bg-viz-rank-9', 'var(--ui-viz-rank-9, var(--_viz-rank-9, #2dd4bf))', 'text-viz-rank-9'),
+  viz('bg-viz-rank-10', 'var(--ui-viz-rank-10, var(--_viz-rank-10, #fb7185))', 'text-viz-rank-10'),
+  viz('bg-accented', neutralHalf, 'text-muted'),
+]
+
+/**
+ * Lighthouse request waterfall: one identity hue per resource type. Hues stay
+ * off the status set (green, amber, red), so a script bar never reads as a
+ * warning. Anything unlisted draws as `Other`.
+ */
+export const lighthouseResourceVizColors = {
+  Document: viz('bg-viz-resource-document', 'var(--ui-viz-resource-document, #3b82f6)', 'text-viz-resource-document'),
+  Script: viz('bg-viz-resource-script', 'var(--ui-viz-resource-script, var(--_viz-resource-script, #f97316))', 'text-viz-resource-script'),
+  Stylesheet: viz('bg-viz-resource-stylesheet', 'var(--ui-viz-resource-stylesheet, #a855f7)', 'text-viz-resource-stylesheet'),
+  Image: viz('bg-viz-resource-image', 'var(--ui-viz-resource-image, var(--_viz-resource-image, #06b6d4))', 'text-viz-resource-image'),
+  Font: viz('bg-viz-resource-font', 'var(--ui-viz-resource-font, #ec4899)', 'text-viz-resource-font'),
+  Other: viz('bg-accented', neutralHalf, 'text-muted'),
+} as const satisfies Record<string, VizColor>
+
+/** Generic five-slot categorical palette for compact composition charts. */
+export const categoricalVizColors: string[] = [
+  'var(--ui-viz-category-1, var(--_viz-category-1, #60a5fa))',
+  'var(--ui-viz-category-2, var(--_viz-category-2, #4ade80))',
+  'var(--ui-viz-category-3, var(--_viz-category-3, #fbbf24))',
+  'var(--ui-viz-category-4, var(--_viz-category-4, #f87171))',
+  'var(--ui-viz-category-5, var(--_viz-category-5, #a78bfa))',
+]
+/** Country donut uses the shared categorical palette. */
+export const gscCountryDonutColors = categoricalVizColors
+
+/** Top-pages stacked area (6 slots: 5 pages + "other"). */
+export const gscTopPagesColors: VizColor[] = [
+  ...gscTopEntityColors.slice(0, 5),
+  viz('bg-accented', neutralHalf, 'text-muted'),
+]
+
+/**
+ * Generic preset swatches — for charts with no metric/category mapping (e.g.
+ *  `<UiSparkline color="blue">`). Use a metric/category map first when one fits.
+ *
+ * `long-tail` / `high-volume` / `quick-wins` are keyword-research categories
+ *  consumed by `ProToolsKeywordTable`; aliased onto preset hues so they share
+ *  the same look as the underlying chart colour.
+ */
+export const presetVizColors = {
+  'blue': viz('bg-blue-500', '#3b82f6', 'text-blue-500'),
+  'green': viz('bg-emerald-500', '#10b981', 'text-emerald-500'),
+  'purple': viz('bg-purple-500', '#a855f7', 'text-purple-500'),
+  'orange': viz('bg-orange-500', '#f97316', 'text-orange-500'),
+  'red': viz('bg-red-500', '#ef4444', 'text-red-500'),
+  'cyan': viz('bg-cyan-500', '#06b6d4', 'text-cyan-500'),
+  'amber': viz('bg-amber-500', '#f59e0b', 'text-amber-500'),
+  'neutral': viz('bg-accented', semanticColors.neutral.hex, 'text-muted'),
+  'long-tail': viz('bg-cyan-500', '#06b6d4', 'text-cyan-500'),
+  'high-volume': viz('bg-emerald-500', '#10b981', 'text-emerald-500'),
+  'quick-wins': viz('bg-amber-500', '#f59e0b', 'text-amber-500'),
+} as const satisfies Record<string, VizColor>
+
+/**
+ * One lookup for legends, sparklines, and dot chips. Metric / category names
+ *  resolve to their identity colour; preset names fall through.
+ */
+export const vizColorMap: Record<string, VizColor> = {
+  ...presetVizColors,
+  clicks: gscMetricColors.clicks,
+  impressions: gscMetricColors.impressions,
+  ctr: gscMetricColors.ctr,
+  position: gscMetricColors.position,
+  lcp: cwvMetricColors.lcp,
+  inp: cwvMetricColors.inp,
+  cls: cwvMetricColors.cls,
+  brand: gscBrandSplitColors.brand,
+  nonBrand: gscBrandSplitColors.nonBrand,
+}
+
+/**
+ * Lookup helpers. Both function-callable (`vizBgColor("clicks")`) AND
+ * key-indexable (`vizBgColor.blue`) so legend mapping and inline class
+ * binding can share one import.
+ */
+function makeLookup(field: keyof VizColor) {
+  const fallback = presetVizColors.neutral[field]
+  return Object.assign(
+    (name: string | null | undefined) => (name ? (vizColorMap[name]?.[field] ?? fallback) : fallback),
+    Object.fromEntries(Object.entries(vizColorMap).map(([k, v]) => [k, v[field]])),
+  ) as ((name: string | null | undefined) => string) & Record<string, string>
+}
+
+export const vizBgColor = makeLookup('bg')
+export const vizDotColor = makeLookup('hex')
+export const vizTextColor = makeLookup('text')
+
+/**
+ * Metric identity glyph: one semantic icon per metric, wherever the metric is
+ * named (toolbar chips, card stats, table headers). Pairs with the colour maps
+ * above. Upstream option lists (`GSC_COLUMN_OPTIONS` from `@gscdump/sdk`) carry
+ * raw iconify ids, so consumers resolve the glyph here by key instead.
+ */
+export const metricIcons = {
+  clicks: 'mouse-pointer',
+  impressions: 'view',
+  ctr: 'percent',
+  position: 'hash',
+  queries: 'search',
+  pages: 'file',
+  sessions: 'users',
+  users: 'user',
+  pageviews: 'view',
+  lcp: 'timer',
+  inp: 'mouse-pointer',
+  cls: 'move',
+  indexed: 'link',
+  unindexed: 'caution',
+  errors: 'warning',
+} as const satisfies Record<string, SemanticUiIcon>
+
+/** Metric glyph by key, or `undefined` for a metric without an identity icon. */
+export function metricIcon(key: string): SemanticUiIcon | undefined {
+  return (metricIcons as Record<string, SemanticUiIcon>)[key]
+}

package/app/composables/formatting.ts

@@ -0,0 +1,252 @@
+import type { ComputedRef, MaybeRef, Ref } from 'vue'
+import { computed, isRef } from 'vue'
+import { percentChange } from '../utils/number'
+import { semanticColors } from './semanticColors'
+
+// `Intl.*` constructors are expensive; hoist to module scope so per-cell
+// formatters across large tables reuse one instance instead of allocating
+// a new one on every call.
+// The app is English-only, so pin display formatting to one locale. Letting
+// Node and the browser choose independently produced different compact suffixes
+// (`1.2K` during SSR, `1.2k` in Chrome) and guaranteed hydration mismatches.
+// Every display formatter in the layer reads this constant. A bare
+// `toLocaleString()` or `Intl.*(undefined)` is lint-banned in the layer, because
+// it reads the runtime locale and the server and the browser disagree.
+export const DISPLAY_LOCALE = 'en-US'
+const compactNumberFormat = new Intl.NumberFormat(DISPLAY_LOCALE, { notation: 'compact', maximumFractionDigits: 1 })
+// `narrowSymbol` keeps the "$" glyph (prices are USD) while still localising
+// grouping/decimal separators, rather than degrading to the "USD" code in
+// locales that disambiguate the dollar sign (e.g. en-AU).
+const compactUsdFormat = new Intl.NumberFormat(DISPLAY_LOCALE, { style: 'currency', currency: 'USD', currencyDisplay: 'narrowSymbol', notation: 'compact', maximumFractionDigits: 1 })
+const usdFormat = new Intl.NumberFormat(DISPLAY_LOCALE, { style: 'currency', currency: 'USD', currencyDisplay: 'narrowSymbol' })
+const sitemapDateFormat = new Intl.DateTimeFormat(DISPLAY_LOCALE, { month: 'short', day: 'numeric', year: 'numeric' })
+const relativeTimeFormatNarrow = new Intl.RelativeTimeFormat(DISPLAY_LOCALE, { numeric: 'auto', style: 'narrow' })
+const relativeTimeFormatLong = new Intl.RelativeTimeFormat(DISPLAY_LOCALE, { numeric: 'auto', style: 'long' })
+const signedPercentFormat = new Intl.NumberFormat(DISPLAY_LOCALE, { style: 'percent', signDisplay: 'exceptZero', minimumFractionDigits: 1, maximumFractionDigits: 1 })
+const ctrPercentFormat = new Intl.NumberFormat(DISPLAY_LOCALE, { style: 'percent', minimumFractionDigits: 1, maximumFractionDigits: 1 })
+const positionFormat = new Intl.NumberFormat(DISPLAY_LOCALE, { minimumFractionDigits: 1, maximumFractionDigits: 1 })
+const groupedNumberFormat = new Intl.NumberFormat(DISPLAY_LOCALE, { maximumFractionDigits: 3 })
+
+/** A plain grouped number (`12,345.6`): the default chart and table formatter. */
+export function formatGroupedNumber(n: number): string {
+  return groupedNumberFormat.format(n)
+}
+
+/**
+ * Pure trend percentage between two values.
+ * For metrics where lower is better (e.g. position), pass `invert: true`.
+ * Returns 0 when prev is 0/null/undefined to avoid Infinity.
+ */
+export function calcTrendPercent(current: number, prev: number, invert = false): number {
+  const pct = percentChange(current, prev)
+  return (invert ? -pct : pct) || 0
+}
+
+/**
+ * A missing value (`null`, `undefined`, `''`, or anything that is not a finite
+ * number) reads as a dash. `Number(null)` is 0 and `Number(undefined)` is NaN,
+ * so coercing first printed "0" or "NaN" for a value that was never measured.
+ */
+export function useProHumanFriendlyNumber(number: Ref<string | number | null | undefined>, decimals?: number): ComputedRef<string>
+export function useProHumanFriendlyNumber(number: string | number | null | undefined, decimals?: number): string
+export function useProHumanFriendlyNumber(number: MaybeRef<string | number | null | undefined>, decimals?: number) {
+  const format = (raw: string | number | null | undefined) => {
+    if (raw == null || (typeof raw === 'string' && raw.trim() === ''))
+      return '—'
+    const n = Number(raw)
+    if (!Number.isFinite(n))
+      return '—'
+    // Intl holds the digit count. Rounding through `toFixed` dropped a trailing
+    // zero, so one column printed `20` beside `6.2`, and the compact format cut
+    // a second decimal.
+    if (typeof decimals !== 'undefined') {
+      return new Intl.NumberFormat(DISPLAY_LOCALE, {
+        notation: 'compact',
+        minimumFractionDigits: decimals,
+        maximumFractionDigits: decimals,
+      }).format(n)
+    }
+    return compactNumberFormat.format(n)
+  }
+  if (isRef(number))
+    return computed(() => format(number.value))
+  return format(number)
+}
+
+export const useHumanFriendlyNumber = useProHumanFriendlyNumber
+
+/**
+ * A timestamp as a Date. A raw `number` may be unix SECONDS (our
+ * `mode:'timestamp'` columns) or unix MILLISECONDS (the raw-`integer` audit
+ * columns: billingEvents, adminEvents, loginEvents, runtimeErrors; ADR-0082).
+ * Magnitude decides: seconds for any plausible date are < 1e11, ms are >= 1e12.
+ * Every component that takes a numeric timestamp reads it through here, so the
+ * label and the relative text always name the same instant.
+ */
+export function toTimestampDate(timestamp: number | string | Date): Date {
+  if (typeof timestamp === 'number')
+    return new Date(timestamp < 1e11 ? timestamp * 1000 : timestamp)
+  return new Date(timestamp)
+}
+
+/**
+ * Relative distance from now, signed. `narrow` ("in 3d", "5m ago") is the
+ * default for dense cells; `long` ("in 3 days") reads as a sentence where the
+ * value stands alone, such as a scheduled send.
+ */
+export function formatTimeAgo(timestamp: number | string | Date | null | undefined, style: 'narrow' | 'long' = 'narrow') {
+  if (!timestamp)
+    return null
+  const relativeTimeFormat = style === 'long' ? relativeTimeFormatLong : relativeTimeFormatNarrow
+  const date = toTimestampDate(timestamp)
+  // Result is relative to the current time, so it differs between SSR and
+  // client render — callers showing this in initial HTML should wrap it in
+  // <ClientOnly> to avoid a hydration mismatch.
+  // Signed distance, so a FUTURE date reads forward ("in 6 days"). It used to
+  // subtract one way only, so every future date fell through `minutes < 1` and
+  // rendered as "just now" — a 7-day invitation expiry announced itself as
+  // already expiring.
+  const diff = Date.now() - date.getTime()
+  const ahead = diff < 0
+  const distance = Math.abs(diff)
+  const minutes = Math.floor(distance / 60000)
+  const hours = Math.floor(distance / 3600000)
+  const days = Math.floor(distance / 86400000)
+  const signed = (n: number) => ahead ? n : -n
+  if (minutes < 1)
+    return 'just now'
+  if (minutes < 60)
+    return relativeTimeFormat.format(signed(minutes), 'minute')
+  if (hours < 24)
+    return relativeTimeFormat.format(signed(hours), 'hour')
+  if (days < 30)
+    return relativeTimeFormat.format(signed(days), 'day')
+  const months = Math.floor(days / 30)
+  if (months < 12)
+    return relativeTimeFormat.format(signed(months), 'month')
+  // `days / 30` reaches 12 at day 360 while `days / 365` is still 0, so days
+  // 360 to 364 printed "this yr.". Past the month range it is at least a year.
+  return relativeTimeFormat.format(signed(Math.max(1, Math.floor(days / 365))), 'year')
+}
+
+export function formatNumber(n: number | null | undefined): string {
+  if (n == null)
+    return '—'
+  return compactNumberFormat.format(n)
+}
+
+export function formatCurrency(n: number | null | undefined): string {
+  if (n == null)
+    return '—'
+  return compactUsdFormat.format(n)
+}
+
+// `n` is a percentage-point value (e.g. 5 → "+5.0%"), so divide before the
+// percent formatter (which multiplies by 100).
+export function formatPercent(n: number): string {
+  return signedPercentFormat.format(n / 100)
+}
+
+export function formatCurrencyFromCents(cents: number | null | undefined): string {
+  if (cents == null)
+    return '—'
+  return usdFormat.format(cents / 100)
+}
+
+// GSC metric formatter (replaces duplicated fmtMetric across SC pages)
+export function fmtGscMetric(val: number, metric: string): string {
+  if (metric === 'ctr')
+    return ctrPercentFormat.format(val)
+  if (metric === 'position')
+    return positionFormat.format(val)
+  return formatNumber(val)
+}
+
+// Color utilities
+export function getDifficultyColor(d: number | null): string {
+  if (d == null)
+    return 'bg-accented text-muted'
+  if (d <= 30)
+    return 'bg-success/10 text-success'
+  if (d <= 60)
+    return 'bg-warning/10 text-warning'
+  return 'bg-error/10 text-error'
+}
+
+export function getDifficultyInfo(kd: number | null): { label: string, color: string, bg: string, description: string } {
+  if (kd === null)
+    return { label: '—', color: 'text-muted', bg: 'bg-accented', description: 'No difficulty data' }
+  if (kd <= 20)
+    return { label: 'Easy', color: 'text-success', bg: 'bg-success/15', description: 'Low competition – great opportunity' }
+  if (kd <= 40)
+    return { label: 'Low', color: 'text-success', bg: 'bg-success/15', description: 'Achievable with quality content' }
+  if (kd <= 60)
+    return { label: 'Medium', color: 'text-warning', bg: 'bg-warning/15', description: 'Needs strong content + backlinks' }
+  if (kd <= 80)
+    return { label: 'Hard', color: 'text-warning', bg: 'bg-warning/15', description: 'Requires niche authority' }
+  return { label: 'Very Hard', color: 'text-error', bg: 'bg-error/15', description: 'Dominated by major sites' }
+}
+
+export function getDomainRankColor(rank: number | null | undefined): string {
+  if (!rank)
+    return 'text-muted'
+  if (rank >= 70)
+    return 'text-success'
+  if (rank >= 40)
+    return 'text-warning'
+  return 'text-error'
+}
+
+export function trendColor(change: number | null): string {
+  if (!change)
+    return semanticColors.neutral.hex
+  return change > 0 ? semanticColors.success.hex : semanticColors.error.hex
+}
+
+// URL/path helpers
+export function getPath(url: string): string {
+  if (!url?.startsWith('http'))
+    return url || '/'
+  return new URL(url).pathname || '/'
+}
+
+export function getSitemapName(path: string): string {
+  try {
+    return new URL(path).pathname || path
+  }
+  catch {
+    return path
+  }
+}
+
+export function formatSitemapDate(dateStr: string | null | undefined): string {
+  if (!dateStr)
+    return 'Never'
+  return sitemapDateFormat.format(new Date(dateStr))
+}
+
+// --- Reporting-day buckets (GSC/analytics daily rows keyed "YYYY-MM-DD") ---
+// These are calendar-day LABELS owned by the data source (GSC buckets in Pacific
+// Time), not instants. We never shift them into the viewer's timezone — doing so
+// is the off-by-one-day bug. Parse in a fixed UTC frame so the round-trip is
+// identity, and ALWAYS format with `timeZone: 'UTC'` so the label never drifts.
+// See ADR-0082. The `Z`/UTC here is a neutral frame for an opaque label, not a
+// claim that the data is UTC.
+const reportingDayFormat = new Intl.DateTimeFormat(DISPLAY_LOCALE, { month: 'short', day: 'numeric', timeZone: 'UTC' })
+
+/** Parse a "YYYY-MM-DD" reporting-day label into a stable, viewer-independent Date. */
+export function parseReportingDay(iso: string): Date {
+  return new Date(`${iso}T00:00:00Z`)
+}
+
+/**
+ * Format a "YYYY-MM-DD" reporting-day label. Defaults to "Jun 24"; pass `opts` for
+ * other shapes — `timeZone: 'UTC'` is forced so the label can't drift per viewer.
+ */
+export function formatReportingDay(iso: string | null | undefined, opts?: Intl.DateTimeFormatOptions): string {
+  if (!iso)
+    return '—'
+  if (opts)
+    return new Intl.DateTimeFormat(DISPLAY_LOCALE, { ...opts, timeZone: 'UTC' }).format(parseReportingDay(iso))
+  return reportingDayFormat.format(parseReportingDay(iso))
+}