@nuxtseo/design-system 0.0.0-stage → 0.1.0

package/app/composables/semanticColors.ts

@@ -0,0 +1,80 @@
+/**
+ * Centralized semantic color system for the Pro dashboard.
+ *
+ * Three concerns:
+ * 1. **Status colors** — success/error/warning/info/neutral for health, connection, validation states
+ * 2. **Threshold colors** — good/needs-attention/poor for CWV, indexing %, etc.
+ * 3. **Trend colors** — positive (green) / negative (red) / neutral for change values
+ *
+ * Metric visualization colors (clicks=blue, impressions=purple, etc.) are intentionally
+ * NOT included here — those are data-viz concerns, not semantic.
+ */
+
+export type SemanticStatus = 'success' | 'error' | 'warning' | 'info' | 'neutral'
+export type HealthStatus = 'healthy' | 'attention' | 'issues' | 'unknown'
+
+export interface SemanticColorSet {
+  text: string
+  bg: string
+  dot: string
+  border: string
+  hex: string
+}
+
+/** Full class sets for each semantic status */
+export const semanticColors: Record<SemanticStatus, SemanticColorSet> = {
+  success: { text: 'text-success', bg: 'bg-success/10', dot: 'bg-success', border: 'border-success/20', hex: '#22c55e' },
+  error: { text: 'text-error', bg: 'bg-error/10', dot: 'bg-error', border: 'border-error/20', hex: '#ef4444' },
+  warning: { text: 'text-warning', bg: 'bg-warning/10', dot: 'bg-warning', border: 'border-warning/20', hex: '#eab308' },
+  info: { text: 'text-info', bg: 'bg-info/10', dot: 'bg-info', border: 'border-info/20', hex: '#3b82f6' },
+  // hex defaults to a violet-tinted grey (hue ~292) matching the de-chromatized
+  // neutral ramp, not stock cold blue-slate, so chart neutrals sit with the
+  // surface greys instead of reading cool against them. A site that extends the
+  // layer sets `--ui-viz-neutral`. It is a CSS colour: mix it with `color-mix()`,
+  // never parse it as hex. Light mode reads a darker `--_viz-neutral`, so
+  // neutral marks clear 3:1 on white (css/global.css).
+  neutral: { text: 'text-muted', bg: 'bg-accented', dot: 'bg-[var(--ui-border)]', border: 'border-default', hex: 'var(--ui-viz-neutral, var(--_viz-neutral, #9e9aa6))' },
+}
+
+/** Map dashboard health status to semantic status */
+export function healthToSemantic(health: HealthStatus | null): SemanticStatus {
+  switch (health) {
+    case 'healthy': return 'success'
+    case 'attention': return 'warning'
+    case 'issues': return 'error'
+    default: return 'neutral'
+  }
+}
+
+/** Map a numeric value against good/poor thresholds to semantic status */
+export function thresholdToSemantic(value: number, good: number, poor: number): SemanticStatus {
+  if (value <= good)
+    return 'success'
+  if (value <= poor)
+    return 'warning'
+  return 'error'
+}
+
+/** Map a trend direction to semantic status — positive=success, negative=error, zero=neutral */
+export function trendToSemantic(value: number): SemanticStatus {
+  if (value > 0)
+    return 'success'
+  if (value < 0)
+    return 'error'
+  return 'neutral'
+}
+
+/** Shorthand: get the full color set for a health status */
+export function healthColors(health: HealthStatus | null): SemanticColorSet {
+  return semanticColors[healthToSemantic(health)]
+}
+
+/** Shorthand: get the full color set for a threshold value */
+export function thresholdColors(value: number, good: number, poor: number): SemanticColorSet {
+  return semanticColors[thresholdToSemantic(value, good, poor)]
+}
+
+/** Shorthand: get hex color for a threshold value (for chart rendering) */
+export function thresholdHex(value: number, good: number, poor: number): string {
+  return thresholdColors(value, good, poor).hex
+}

package/app/composables/useActivityOverlay.ts

@@ -0,0 +1,55 @@
+import { useState } from 'nuxt/app'
+
+/**
+ * useActivityOverlay — the layer-agnostic trigger for the activity detail
+ * overlay (2026-08). Every "Recent Activity" row, on every surface, opens the
+ * SAME detail surface through this channel.
+ *
+ * The defect it exists to kill: an activity row knows exactly which entity it
+ * is about (a referring domain, a mention URL, a scanned page), and its
+ * destination threw that identity away and dropped the reader on a list. A row
+ * about `t128n.dev` landed on the whole backlink profile; a mention row had no
+ * destination at all. One overlay, one contract, so the class dies rather than
+ * one instance of it.
+ *
+ * Why it lives in design-system, not in a pro-* layer: ADR-0042 forbids feature
+ * layers importing each other's runtime, and the writers span pro-timeline,
+ * pro-dataforseo and `apps/pro`. So the trigger is a generic `useState` channel
+ * here (which every layer may import) and `apps/pro` owns the host
+ * (`ProActivityOverlayHost`) that reads this state and renders the real change
+ * brief. Same seam shape as `useIssueOverlay`; the entry travels opaquely
+ * (`unknown`) so design-system never learns the ChangeEntry shape.
+ *
+ * A row must only write here when it holds real evidence. An empty overlay is
+ * worse than a row that says nothing.
+ */
+
+export interface ActivityOverlayRequest {
+  /** The activity entry (opaque here; the host casts it to `ChangeEntry`). */
+  entry: unknown
+  /** The site the activity belongs to — the brief is site-scoped. */
+  siteId: string
+  /**
+   * The owning site record, when the caller already holds one. Opaque for the
+   * same reason `entry` is. Omitted callers fall back to the session lookup.
+   */
+  site?: unknown
+  /** When the owning site was last assessed — the brief's "as of" anchor. */
+  assessedAt?: string | null
+  /** Bumped per open so the host re-triggers even for the same entry. */
+  nonce: number
+}
+
+/** The shared overlay channel — read by the host, written by `open`. */
+export function useActivityOverlayState() {
+  return useState<ActivityOverlayRequest | null>('pro:activity-overlay', () => null)
+}
+
+export function useActivityOverlay() {
+  const state = useActivityOverlayState()
+  return {
+    open(req: { entry: unknown, siteId: string, site?: unknown, assessedAt?: string | null }) {
+      state.value = { ...req, nonce: (state.value?.nonce ?? 0) + 1 }
+    },
+  }
+}

package/app/composables/useAppShellNav.ts

@@ -0,0 +1,21 @@
+import type { InjectionKey } from 'vue'
+import { inject, provide } from 'vue'
+
+// Shell drawer control shared down the tree. UiAppShell provides it; a
+// descendant page header (saas `ProPageHeader`) injects it to render the
+// hamburger inline with the page title below `lg` (shell `inlineMobileNav`).
+// Null outside a shell: consumers hide their hamburger when it is absent,
+// so a header rendered standalone keeps working.
+export interface UiAppShellNav {
+  openNav: () => void
+}
+
+const key: InjectionKey<UiAppShellNav> = Symbol('ui-app-shell-nav')
+
+export function provideUiAppShellNav(nav: UiAppShellNav) {
+  provide(key, nav)
+}
+
+export function useUiAppShellNav(): UiAppShellNav | null {
+  return inject(key, null)
+}

package/app/composables/useChartBrush.ts

@@ -0,0 +1,221 @@
+import type { MaybeRefOrGetter, Ref } from 'vue'
+import { useResizeObserver } from '@vueuse/core'
+import { computed, onUnmounted, ref, toValue } from 'vue'
+
+// Provider-agnostic drag-to-select-range interaction for time-series charts.
+// Extracted from ProCardGsc's pointer-drag logic (the brush half — hover/tooltip
+// springs stay with the consuming card) so the Web Analytics chart reuses the
+// same scrubbing UX without copying ~120 lines. The consumer binds `wrapRef` to
+// the chart wrapper, draws the selection rect from `selectionLeft`/`selectionWidth`,
+// and gets a committed `{ startIdx, endIdx, startDate, endDate }` via `onCommit`.
+
+export interface ChartBrushRange {
+  startIdx: number
+  endIdx: number
+  startDate: string
+  endDate: string
+}
+
+export interface UseChartBrushOptions {
+  /** Reactive ISO date strings, one per data point — drives idx ↔ date lookups. */
+  dates: MaybeRefOrGetter<string[]>
+  /** Called when a drag completes spanning more than one point. */
+  onCommit: (range: ChartBrushRange) => void
+}
+
+export interface UseChartBrush {
+  wrapRef: Ref<HTMLElement | null>
+  chartWidth: Ref<number>
+  isDragging: Ref<boolean>
+  dragRange: Ref<ChartBrushRange | null>
+  selectionLeft: Ref<number>
+  selectionWidth: Ref<number>
+  onPointerDown: (e: PointerEvent) => void
+  refreshChartRect: () => void
+  cancel: () => void
+}
+
+const DRAG_THRESHOLD_PX = 5
+
+// Suppress page text-selection for the duration of a brush drag — a fast drag
+// otherwise selects surrounding copy (the "disable text selection during drag"
+// rule). Restored when the drag ends/cancels.
+function setSelectSuppressed(on: boolean) {
+  if (typeof document === 'undefined')
+    return
+  const s = document.documentElement.style
+  s.setProperty('user-select', on ? 'none' : '')
+  s.setProperty('-webkit-user-select', on ? 'none' : '')
+}
+
+export function useChartBrush(opts: UseChartBrushOptions): UseChartBrush {
+  const wrapRef = ref<HTMLElement | null>(null)
+  // Cached geometry — avoids synchronous layout reads on every pointermove.
+  const chartWidth = ref(0)
+  let chartRectLeft = 0
+
+  const isDragging = ref(false)
+  const dragRange = ref<ChartBrushRange | null>(null)
+
+  useResizeObserver(wrapRef, ([entry]) => {
+    if (!entry)
+      return
+    // Width comes straight off contentRect (no layout read). `chartRectLeft` is
+    // refreshed via getBoundingClientRect() on pointerdown (refreshChartRect),
+    // so reading it here too would just be a redundant synchronous reflow.
+    chartWidth.value = entry.contentRect.width
+  })
+
+  function refreshChartRect() {
+    const el = wrapRef.value
+    if (!el)
+      return
+    const rect = el.getBoundingClientRect()
+    chartRectLeft = rect.left
+    chartWidth.value = rect.width
+  }
+
+  function pixelToIdx(px: number): number {
+    const len = toValue(opts.dates).length
+    const width = chartWidth.value
+    if (len < 2 || width <= 0)
+      return 0
+    return Math.max(0, Math.min(len - 1, Math.round((px / width) * (len - 1))))
+  }
+
+  function idxToPixel(idx: number): number {
+    const len = toValue(opts.dates).length
+    const width = chartWidth.value
+    if (len < 2 || width <= 0)
+      return 0
+    return (idx / (len - 1)) * width
+  }
+
+  function idxToDate(idx: number): string {
+    const rows = toValue(opts.dates)
+    const clamped = Math.max(0, Math.min(rows.length - 1, idx))
+    return rows[clamped] ?? ''
+  }
+
+  const selectionLeft = computed(() => dragRange.value ? idxToPixel(dragRange.value.startIdx) : 0)
+  const selectionWidth = computed(() => {
+    if (!dragRange.value)
+      return 0
+    return Math.max(0, idxToPixel(dragRange.value.endIdx) - idxToPixel(dragRange.value.startIdx))
+  })
+
+  let dragStartX = 0
+  let dragStartIdx = 0
+  let removeWindowListeners: (() => void) | null = null
+
+  function cancel() {
+    removeWindowListeners?.()
+    removeWindowListeners = null
+    isDragging.value = false
+    dragRange.value = null
+  }
+
+  function onPointerDown(e: PointerEvent) {
+    if (e.button !== 0)
+      return
+    if (!wrapRef.value)
+      return
+    // A second touch or pointer must replace the active session. Otherwise its
+    // cleanup closure overwrites the first one and leaves global listeners alive.
+    cancel()
+    // Single BCR read on drag start — covers scroll/offset drift since last observer tick.
+    refreshChartRect()
+    dragStartX = e.clientX - chartRectLeft
+    dragStartIdx = pixelToIdx(dragStartX)
+    const startY = e.clientY
+    const pointerId = e.pointerId
+
+    // rAF-coalesce moves: a fast drag fires pointermove many times per frame,
+    // but we only need one reactive `dragRange` write (and one overlay render)
+    // per frame. Listener is passive — we never preventDefault on move.
+    let moveRaf: number | null = null
+    let pendingX = 0
+    const onMove = (ev: PointerEvent) => {
+      if (ev.pointerId !== pointerId)
+        return
+      pendingX = ev.clientX - chartRectLeft
+      // Vertical touch intent belongs to page scrolling, even with horizontal drift.
+      if (e.pointerType === 'touch' && !isDragging.value && Math.abs(ev.clientY - startY) >= DRAG_THRESHOLD_PX
+        && Math.abs(ev.clientY - startY) >= Math.abs(pendingX - dragStartX)) {
+        cancel()
+        return
+      }
+      if (moveRaf != null)
+        return
+      moveRaf = requestAnimationFrame(() => {
+        moveRaf = null
+        const currentX = pendingX
+        if (!isDragging.value) {
+          if (Math.abs(currentX - dragStartX) < DRAG_THRESHOLD_PX)
+            return
+          isDragging.value = true
+          setSelectSuppressed(true)
+        }
+        dragRange.value = rangeTo(currentX)
+      })
+    }
+
+    function rangeTo(x: number): ChartBrushRange {
+      const currentIdx = pixelToIdx(x)
+      const startIdx = Math.min(dragStartIdx, currentIdx)
+      const endIdx = Math.max(dragStartIdx, currentIdx)
+      return { startIdx, endIdx, startDate: idxToDate(startIdx), endDate: idxToDate(endIdx) }
+    }
+
+    const onUp = (ev: PointerEvent) => {
+      if (ev.pointerId !== pointerId)
+        return
+      removeWindowListeners?.()
+      removeWindowListeners = null
+      // Read the range from the release point. The rAF that writes
+      // `dragRange` is cancelled above, so a flick that ends inside one frame
+      // had no range and never committed.
+      const upX = ev.clientX - chartRectLeft
+      const range = Math.abs(upX - dragStartX) >= DRAG_THRESHOLD_PX ? rangeTo(upX) : null
+      isDragging.value = false
+      dragRange.value = null
+      if (range && range.endIdx > range.startIdx)
+        opts.onCommit(range)
+    }
+
+    const onCancel = (ev: PointerEvent) => {
+      if (ev.pointerId === pointerId)
+        cancel()
+    }
+
+    window.addEventListener('pointermove', onMove, { passive: true })
+    window.addEventListener('pointerup', onUp)
+    window.addEventListener('pointercancel', onCancel)
+    window.addEventListener('wheel', cancel, { passive: true })
+    window.addEventListener('scroll', cancel, { passive: true, capture: true })
+    removeWindowListeners = () => {
+      if (moveRaf != null)
+        cancelAnimationFrame(moveRaf)
+      setSelectSuppressed(false)
+      window.removeEventListener('pointermove', onMove)
+      window.removeEventListener('pointerup', onUp)
+      window.removeEventListener('pointercancel', onCancel)
+      window.removeEventListener('wheel', cancel)
+      window.removeEventListener('scroll', cancel, { capture: true })
+    }
+  }
+
+  onUnmounted(() => removeWindowListeners?.())
+
+  return {
+    wrapRef,
+    chartWidth,
+    isDragging,
+    dragRange,
+    selectionLeft,
+    selectionWidth,
+    onPointerDown,
+    refreshChartRect,
+    cancel,
+  }
+}

package/app/composables/useChartHover.ts

@@ -0,0 +1,153 @@
+import type { MotionValue } from 'motion-v'
+import type { Ref } from 'vue'
+import { useMotionValue, useSpring } from 'motion-v'
+import { onScopeDispose, ref, shallowRef } from 'vue'
+
+// Hover/tooltip half of a time-series chart's pointer UX. Sibling to
+// useChartBrush — both cards (Gsc, Analytics) had near-identical tooltip
+// state + spring-tracked card positioning. Pass in the brush's `isDragging`
+// to suppress the tooltip during a drag (the selection overlay owns the
+// visual then).
+//
+// Positioning model: the tooltip anchors to the *cursor* (not the chart edge)
+// via spring-tracked `cardX` + `cursorY`. The `placement` ref says whether
+// the tooltip sits above or below the cursor; consumers translate the
+// rendered element accordingly. Above-cursor is the default; flips to below
+// when the cursor is too close to the chart's top edge to fit the tooltip.
+
+export interface UseChartHoverOptions {
+  /** Chart wrapper element — used for BCR reads. */
+  wrapRef: Ref<HTMLElement | null>
+  /** Reactive chart width in px — usually from useChartBrush. */
+  chartWidth: Ref<number>
+  /** When true, onTooltip clears state instead of setting it. */
+  isDragging?: Ref<boolean>
+  /** Tooltip card width in px (used to keep the card on-screen). */
+  tooltipWidth?: number
+  /** Approximate tooltip height — used to decide when to flip above ↔ below. */
+  tooltipHeightEst?: number
+  /** Padding from the chart edges in px. */
+  edgePad?: number
+  /** Vertical gap between cursor and tooltip edge. */
+  cursorGap?: number
+  /** Spring config for the floating card (softer — glides). */
+  cardSpring?: { stiffness: number, damping: number, mass: number }
+}
+
+export interface UseChartHover<T, E = void> {
+  tooltipData: Ref<T | null>
+  tooltipPrev: Ref<T | null>
+  tooltipExtra: Ref<E | null>
+  /** Spring-tracked cursor x (centre of tooltip). */
+  cardSpring: MotionValue<number>
+  /** Spring-tracked cursor y (anchor point of tooltip). */
+  cursorYSpring: MotionValue<number>
+  /** Which side of the cursor the tooltip sits on. Reactive. */
+  placement: Ref<'above' | 'below'>
+  onTooltip: (data: T | null, prev: T | null, extra?: E) => void
+  onChartMove: (e: MouseEvent) => void
+  clear: () => void
+}
+
+const DEFAULT_SPRING = { stiffness: 380, damping: 38, mass: 0.5 }
+
+export function useChartHover<T, E = void>(opts: UseChartHoverOptions): UseChartHover<T, E> {
+  const tooltipWidth = opts.tooltipWidth ?? 220
+  const tooltipHeightEst = opts.tooltipHeightEst ?? 56
+  const edgePad = opts.edgePad ?? 8
+  const cursorGap = opts.cursorGap ?? 14
+  // Approx axis row height; tooltip avoids sitting on top of axis tick labels.
+  const AXIS_ROW = 36
+
+  // shallowRef: these hold whole datum objects swapped wholesale on hover —
+  // deep reactivity would be wasted tracking on every pointer move.
+  const tooltipData = shallowRef<T | null>(null)
+  const tooltipPrev = shallowRef<T | null>(null)
+  const tooltipExtra = shallowRef<E | null>(null)
+
+  function clear() {
+    tooltipData.value = null
+    tooltipPrev.value = null
+    tooltipExtra.value = null
+  }
+
+  function onTooltip(data: T | null, prev: T | null, extra?: E) {
+    if (opts.isDragging?.value) {
+      clear()
+      return
+    }
+    tooltipData.value = data
+    tooltipPrev.value = prev
+    tooltipExtra.value = (extra ?? null) as E | null
+  }
+
+  const cardX = useMotionValue(0)
+  const cursorY = useMotionValue(0)
+  // Honour prefers-reduced-motion: skip the glide spring and track the cursor
+  // position directly so the tooltip jumps instead of easing.
+  const prefersReduced = import.meta.client
+    && window.matchMedia?.('(prefers-reduced-motion: reduce)').matches === true
+  const cardSpring = prefersReduced ? cardX : useSpring(cardX, opts.cardSpring ?? DEFAULT_SPRING)
+  const cursorYSpring = prefersReduced ? cursorY : useSpring(cursorY, opts.cardSpring ?? DEFAULT_SPRING)
+  // Default 'above' (tooltip floats above cursor). Flips to 'below' when the
+  // cursor is too close to the top edge to fit the tooltip without clipping.
+  const placement = ref<'above' | 'below'>('above')
+
+  // rAF-batch the mousemove handler so we do at most one motion update per frame.
+  let rafId: number | null = null
+  let pendingClientX = 0
+  let pendingClientY = 0
+  function onChartMove(e: MouseEvent) {
+    pendingClientX = e.clientX
+    pendingClientY = e.clientY
+    if (rafId != null)
+      return
+    rafId = requestAnimationFrame(() => {
+      rafId = null
+      const width = opts.chartWidth.value
+      if (width <= 0)
+        return
+      const rect = opts.wrapRef.value?.getBoundingClientRect()
+      const cursorXpx = pendingClientX - (rect?.left ?? 0)
+      const cursorYpx = pendingClientY - (rect?.top ?? 0)
+      // Clamp x so the tooltip's left/right edges stay within the chart.
+      const halfW = tooltipWidth / 2
+      const clampedX = Math.max(halfW + edgePad, Math.min(width - halfW - edgePad, cursorXpx))
+      cardX.set(clampedX)
+      cursorY.set(cursorYpx)
+
+      // Decide placement. Prefer above (tooltip floats over the data). Flip
+      // to below when too close to the top edge to fit the full tooltip.
+      // Also flip back to above when cursor would push the tooltip into the
+      // axis-tick row at the bottom.
+      const height = rect?.height ?? 0
+      const fitsAbove = cursorYpx - cursorGap - tooltipHeightEst >= edgePad
+      const fitsBelow = cursorYpx + cursorGap + tooltipHeightEst <= height - AXIS_ROW
+      if (placement.value === 'above' && !fitsAbove && fitsBelow)
+        placement.value = 'below'
+      else if (placement.value === 'below' && fitsAbove && !fitsBelow)
+        placement.value = 'above'
+      else if (placement.value === 'below' && fitsAbove)
+        placement.value = 'above'
+    })
+  }
+
+  // Cancel any frame still queued when the consuming component tears down, so
+  // the callback never reads a stale `wrapRef` element after unmount.
+  onScopeDispose(() => {
+    if (rafId != null)
+      cancelAnimationFrame(rafId)
+  })
+
+  return {
+    tooltipData,
+    tooltipPrev,
+    tooltipExtra,
+    cardSpring,
+    cursorYSpring,
+    placement,
+    onTooltip,
+    onChartMove,
+    clear,
+  }
+}