@nuxtseo/design-system 0.0.0-stage → 0.1.0

package/app/components/element/UiTooltipGrid.vue

@@ -0,0 +1,457 @@
+<script setup lang="ts" generic="T = unknown, R extends number | string = number">
+import { defaultWindow, useEventListener, useMounted, useMutationObserver } from '@vueuse/core'
+import { nextTick, ref, shallowRef, useId, useTemplateRef, watch, watchPostEffect } from 'vue'
+/**
+ * UiTooltipGrid
+ *
+ * One shared tooltip + pointer-event delegation on a wrapper element.
+ *
+ * Use this for heatmaps / dense grids where mounting one TooltipRoot per cell
+ * is wasteful (state churn, focus-ring conflicts, "safe-polygon" flicker
+ * between adjacent triggers). Industry precedent: GitHub contribution graph,
+ * Observable Plot, Recharts, Grafana panels — all use a single tooltip
+ * element repositioned to whichever cell is under the cursor.
+ *
+ * Cells inside the slot must carry data attributes:
+ *   data-tooltip-row="0"                (or a string id, e.g. "site|clicks")
+ *   data-tooltip-col="3"
+ *   data-tooltip-value="42"            (optional, forwarded to resolve())
+ *
+ * Positioning uses `position: fixed` + manual `getBoundingClientRect` math
+ * with viewport clamping. No external deps; flips automatically on the
+ * preferred side when there isn't room.
+ */
+
+interface ResolvedTooltip {
+  title?: string
+  /**
+   * Detail rows. The first row becomes the hero value (oversized monospace
+   * number + uppercase label). Remaining rows render as key/value pairs.
+   */
+  details?: { label: string, value?: string, color?: 'default' | 'muted' | 'success' | 'error' | 'warning' }[]
+  /** Semantic level — drives the accent bar color and header dot. */
+  level?: 'success' | 'warning' | 'error' | 'info' | 'neutral'
+}
+
+interface Props {
+  /**
+   * Called per cell to compute tooltip content. Return null/undefined to hide.
+   * `row` is a number when `data-tooltip-row` is numeric, else the string id.
+   */
+  resolve: (cell: { row: R, col: number, value: T, el: HTMLElement }) => ResolvedTooltip | null | undefined
+  /** Selector identifying a cell inside the wrapper. */
+  selector?: string
+  side?: 'top' | 'bottom' | 'left' | 'right'
+  sideOffset?: number
+  /** Override max-width for the tooltip body. */
+  maxWidth?: string
+}
+
+const {
+  resolve,
+  selector = '[data-tooltip-row]',
+  side = 'top',
+  sideOffset = 6,
+  maxWidth = '250px',
+} = defineProps<Props>()
+
+const wrapperEl = useTemplateRef<HTMLElement>('wrapperEl')
+const tooltipEl = useTemplateRef<HTMLElement>('tooltipEl')
+const mounted = useMounted()
+const tooltipId = useId()
+const data = shallowRef<ResolvedTooltip | null>(null)
+const open = ref(false)
+
+// The hovered cell is reactive so a refresh can re-resolve or close it. Hot
+// pointer state below stays off Vue's reactivity system: a pointermove onto
+// the same cell triggers no render.
+const currentTarget = shallowRef<HTMLElement | null>(null)
+let tipWidth = 0
+let tipHeight = 0
+let rafPending = false
+
+function addDescription(target: HTMLElement) {
+  const descriptions = new Set(target.getAttribute('aria-describedby')?.split(/\s+/).filter(Boolean) ?? [])
+  descriptions.add(tooltipId)
+  target.setAttribute('aria-describedby', [...descriptions].join(' '))
+}
+
+function removeDescription(target: HTMLElement) {
+  const descriptions = target.getAttribute('aria-describedby')?.split(/\s+/).filter(id => id && id !== tooltipId) ?? []
+  if (descriptions.length)
+    target.setAttribute('aria-describedby', descriptions.join(' '))
+  else
+    target.removeAttribute('aria-describedby')
+}
+
+function applyTransform(refRect: DOMRect) {
+  if (!tooltipEl.value || !tipWidth || !tipHeight)
+    return
+  const vw = window.innerWidth
+  const vh = window.innerHeight
+  const pad = 8
+  const offset = sideOffset
+
+  let top = 0
+  let left = 0
+  if (side === 'top') {
+    top = refRect.top - tipHeight - offset
+    left = refRect.left + refRect.width / 2 - tipWidth / 2
+  }
+  else if (side === 'bottom') {
+    top = refRect.bottom + offset
+    left = refRect.left + refRect.width / 2 - tipWidth / 2
+  }
+  else if (side === 'left') {
+    top = refRect.top + refRect.height / 2 - tipHeight / 2
+    left = refRect.left - tipWidth - offset
+  }
+  else {
+    top = refRect.top + refRect.height / 2 - tipHeight / 2
+    left = refRect.right + offset
+  }
+
+  if (side === 'top' && top < pad)
+    top = refRect.bottom + offset
+  else if (side === 'bottom' && top + tipHeight > vh - pad)
+    top = refRect.top - tipHeight - offset
+
+  if (left < pad)
+    left = pad
+  if (left + tipWidth > vw - pad)
+    left = vw - tipWidth - pad
+  if (top < pad)
+    top = pad
+  if (top + tipHeight > vh - pad)
+    top = vh - tipHeight - pad
+
+  // Direct DOM write — bypasses Vue reactivity and uses GPU-composite-only transform.
+  tooltipEl.value.style.transform = `translate3d(${Math.round(left)}px, ${Math.round(top)}px, 0)`
+}
+
+function measureTip() {
+  if (!tooltipEl.value)
+    return
+  const r = tooltipEl.value.getBoundingClientRect()
+  tipWidth = r.width
+  tipHeight = r.height
+}
+
+function scheduleReposition() {
+  if (rafPending)
+    return
+  rafPending = true
+  requestAnimationFrame(() => {
+    rafPending = false
+    if (!currentTarget.value)
+      return
+    applyTransform(currentTarget.value.getBoundingClientRect())
+  })
+}
+
+// A row attribute that `Number()` reads is a row index, as it always was.
+// Anything else is a string row id, e.g. "site|clicks".
+function parseRow(raw: string | undefined): number | string | undefined {
+  if (raw === undefined)
+    return undefined
+  const n = Number(raw)
+  return Number.isNaN(n) ? raw : n
+}
+
+function activate(target: HTMLElement) {
+  const row = parseRow(target.dataset.tooltipRow)
+  const col = Number(target.dataset.tooltipCol)
+  if (row === undefined || Number.isNaN(col))
+    return false
+  const raw = target.dataset.tooltipValue
+  let value: unknown
+  if (raw === undefined) {
+    value = undefined
+  }
+  else {
+    const n = Number(raw)
+    value = (Number.isFinite(n) && raw.trim() !== '') ? n : raw
+  }
+  const resolved = resolve({ row: row as R, col, value: value as T, el: target })
+  if (!resolved)
+    return false
+
+  const wasOpen = open.value
+  // Stamp active state on the new cell, clear it on the previous one.
+  if (currentTarget.value && currentTarget.value !== target) {
+    currentTarget.value.removeAttribute('data-tooltip-active')
+    removeDescription(currentTarget.value)
+  }
+  target.setAttribute('data-tooltip-active', 'true')
+  addDescription(target)
+
+  currentTarget.value = target
+  data.value = resolved
+  if (!wasOpen) {
+    // Suppress the transform transition on the very first show so the
+    // tooltip doesn't fly in from (0,0). We measure, place, then re-enable.
+    tooltipEl.value?.setAttribute('data-first-show', 'true')
+    open.value = true
+  }
+
+  // After content renders, measure once then place. For subsequent swaps
+  // (same content shape, mostly) we can skip remeasure and just translate.
+  nextTick(() => {
+    if (!wasOpen)
+      measureTip()
+    if (currentTarget.value)
+      applyTransform(currentTarget.value.getBoundingClientRect())
+    if (!wasOpen) {
+      // Re-enable transform transition on the next frame so subsequent
+      // cell-to-cell swaps glide smoothly.
+      requestAnimationFrame(() => {
+        tooltipEl.value?.removeAttribute('data-first-show')
+      })
+    }
+  })
+  return true
+}
+
+function deactivate() {
+  if (!open.value && !currentTarget.value)
+    return
+  open.value = false
+  if (currentTarget.value) {
+    currentTarget.value.removeAttribute('data-tooltip-active')
+    removeDescription(currentTarget.value)
+  }
+  currentTarget.value = null
+}
+
+function handlePointerMove(e: PointerEvent) {
+  const target = (e.target as HTMLElement | null)?.closest(selector) as HTMLElement | null
+  if (!target) {
+    deactivate()
+    return
+  }
+  if (target === currentTarget.value)
+    return
+  if (!activate(target))
+    deactivate()
+}
+
+function handlePointerLeave() {
+  deactivate()
+}
+
+function handleFocusIn(e: FocusEvent) {
+  const target = (e.target as HTMLElement | null)?.closest(selector) as HTMLElement | null
+  if (!target)
+    return
+  activate(target)
+}
+
+function handleFocusOut() {
+  deactivate()
+}
+
+function handleKey(e: KeyboardEvent) {
+  if (e.key === 'Escape' && open.value)
+    deactivate()
+}
+
+// Keep glued on scroll/resize while open. rAF-batched.
+function onScrollOrResize() {
+  if (currentTarget.value)
+    scheduleReposition()
+}
+
+// When content swaps the body height may change — re-measure on next data tick.
+watch(data, () => {
+  if (!open.value)
+    return
+  nextTick(() => {
+    measureTip()
+    if (currentTarget.value)
+      applyTransform(currentTarget.value.getBoundingClientRect())
+  })
+})
+
+function refreshActive() {
+  const target = currentTarget.value
+  if (target && (target.isConnected === false || !activate(target)))
+    deactivate()
+}
+
+// A refresh can remove a cell while its resolver still returns content.
+useMutationObserver(wrapperEl, () => {
+  const target = currentTarget.value
+  if (target && (target.isConnected === false || !wrapperEl.value?.contains(target)))
+    deactivate()
+}, { childList: true, subtree: true })
+
+// Refresh resolved content when its reactive inputs or the active cell change.
+watchPostEffect(refreshActive)
+useMutationObserver(currentTarget, refreshActive, {
+  attributes: true,
+  attributeFilter: ['data-tooltip-row', 'data-tooltip-col', 'data-tooltip-value'],
+})
+
+useEventListener(defaultWindow, 'scroll', onScrollOrResize, { passive: true, capture: true })
+useEventListener(defaultWindow, 'resize', onScrollOrResize, { passive: true })
+</script>
+
+<template>
+  <div
+    ref="wrapperEl"
+    class="contents"
+    @pointermove="handlePointerMove"
+    @pointerleave="handlePointerLeave"
+    @focusin="handleFocusIn"
+    @focusout="handleFocusOut"
+    @keydown="handleKey"
+  >
+    <slot />
+    <Teleport v-if="mounted" to="body">
+      <div
+        v-show="open && data"
+        :id="tooltipId"
+        ref="tooltipEl"
+        role="tooltip"
+        class="ui-tooltip-grid-content"
+        :data-open="open"
+        :aria-hidden="!open"
+      >
+        <div
+          v-if="data"
+          class="text-left font-normal leading-normal flex items-stretch"
+          :style="{ maxWidth }"
+          :data-level="data.level || 'neutral'"
+          data-ui="UiTooltipGrid"
+        >
+          <!-- Vertical accent bar — semantic-coded -->
+          <span class="ui-tooltip-grid-accent" aria-hidden="true" />
+          <div class="flex-1 min-w-0 pl-2.5">
+            <!-- Header: status dot + uppercase title -->
+            <div v-if="data.title" class="flex items-center gap-1.5 mb-1.5">
+              <span class="ui-tooltip-grid-dot" aria-hidden="true" />
+              <span class="text-label">
+                {{ data.title }}
+              </span>
+            </div>
+            <template v-if="data.details?.length">
+              <!-- Hero value: first detail row, oversized monospace -->
+              <div class="flex items-baseline gap-1.5 mb-0.5">
+                <span
+                  class="font-mono tabular-nums font-semibold text-base leading-none"
+                  :class="{
+                    'text-success': data.details[0]!.color === 'success',
+                    'text-error': data.details[0]!.color === 'error',
+                    'text-warning': data.details[0]!.color === 'warning',
+                  }"
+                >{{ data.details[0]!.value ?? '—' }}</span>
+                <span class="text-label">{{ data.details[0]!.label }}</span>
+              </div>
+              <!-- Secondary rows: stacked key/value -->
+              <div v-if="data.details.length > 1" class="mt-2 pt-2 border-t border-default space-y-0.5">
+                <div
+                  v-for="(d, i) in data.details.slice(1)"
+                  :key="i"
+                  class="flex items-center justify-between gap-4 text-mini"
+                >
+                  <span class="text-muted">{{ d.label }}</span>
+                  <span
+                    v-if="d.value"
+                    class="font-mono tabular-nums"
+                    :class="{
+                      'text-success': d.color === 'success',
+                      'text-error': d.color === 'error',
+                      'text-warning': d.color === 'warning',
+                      'text-muted': d.color === 'muted',
+                      'text-default': !d.color || d.color === 'default',
+                    }"
+                  >{{ d.value }}</span>
+                </div>
+              </div>
+            </template>
+          </div>
+        </div>
+      </div>
+    </Teleport>
+  </div>
+</template>
+
+<style>
+.ui-tooltip-grid-content {
+  position: fixed;
+  top: 0;
+  left: 0;
+  z-index: 50;
+  background-color: var(--ui-bg-elevated);
+  /* Popover-tier chrome — shares the exact tokens UiTooltip uses. */
+  background-image: var(--surface-raised);
+  box-shadow: var(--elevation-popover);
+  color: var(--ui-text);
+  border: 1px solid var(--ui-border);
+  border-radius: 0.5rem;
+  padding: 0.625rem 0.75rem;
+  pointer-events: none;
+  letter-spacing: -0.005em;
+  -webkit-font-smoothing: antialiased;
+  will-change: transform, opacity;
+  /* GPU-composite-only transition — no layout, no paint. */
+  transition: transform 160ms cubic-bezier(0.22, 1, 0.36, 1), opacity 120ms ease-out;
+  opacity: 0;
+}
+
+/* Suppress transform transition on the very first reveal so the tooltip
+   doesn't fly in from (0,0). The opacity fade still plays. */
+.ui-tooltip-grid-content[data-first-show="true"] {
+  transition: opacity 120ms ease-out;
+}
+
+.ui-tooltip-grid-content[data-open="true"] {
+  opacity: 1;
+}
+
+/* ─── Body ─── */
+.ui-tooltip-grid-accent {
+  flex: 0 0 2px;
+  align-self: stretch;
+  border-radius: 999px;
+  background: var(--accent, var(--ui-text));
+  opacity: 0.55;
+}
+
+[data-ui="UiTooltipGrid"][data-level="success"] { --accent: var(--color-success-500); }
+[data-ui="UiTooltipGrid"][data-level="warning"] { --accent: var(--color-warning-500); }
+[data-ui="UiTooltipGrid"][data-level="error"]   { --accent: var(--color-error-500); }
+[data-ui="UiTooltipGrid"][data-level="info"]    { --accent: var(--color-info-500); }
+[data-ui="UiTooltipGrid"][data-level="neutral"] { --accent: var(--ui-text); }
+
+.ui-tooltip-grid-dot {
+  width: 0.375rem;
+  height: 0.375rem;
+  border-radius: 999px;
+  background: var(--accent, var(--ui-text));
+  box-shadow: 0 0 0 2px color-mix(in srgb, var(--accent, var(--ui-text)) 25%, transparent);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .ui-tooltip-grid-content {
+    transition: opacity 80ms linear;
+  }
+}
+
+/* ─── Active cell state — applied to whichever cell is currently hovered ─── */
+[data-tooltip-active="true"] {
+  position: relative;
+  z-index: 1;
+  outline: 1.5px solid var(--ui-border-accented);
+  outline-offset: 1px;
+  transform: scale(1.08);
+  transition: transform 120ms cubic-bezier(0.22, 1, 0.36, 1), outline-color 100ms ease-out;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-tooltip-active="true"] {
+    transform: none;
+    transition: outline-color 100ms ease-out;
+  }
+}
+</style>

package/app/components/element/UiTrend.vue

@@ -0,0 +1,184 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { UiIcon } from '#components'
+import { clamp } from '../../utils/number'
+
+const {
+  value = 0,
+  size = 'xs',
+  iconOnly = false,
+  format = 'number',
+  showSign = false,
+  inverted = false,
+  colored = false,
+  isNew = false,
+  isLost = false,
+  autoLost = true,
+  clamp: shouldClamp = true,
+  precision = 1,
+} = defineProps<{
+  value?: number | string
+  size?: keyof typeof sizes
+  iconOnly?: boolean
+  /** 'points' names an absolute rate difference; 'percent' names a relative change. */
+  format?: 'number' | 'percent' | 'points'
+  /** Show +/- sign before value (auto-enabled for percent and points formats) */
+  showSign?: boolean
+  /** Invert color logic — positive value shows red, negative shows green (e.g. position where lower is better) */
+  inverted?: boolean
+  /**
+   * Trend color budget (DESIGN.md Composition): colored success/error trends
+   * belong to the hero zone only. Default renders neutral (sign + value);
+   * hero components (UiMetricsRow, UiMetricStat, hero cards) opt in.
+   */
+  colored?: boolean
+  /** Show a "NEW" badge instead of trend value */
+  isNew?: boolean
+  /** Show a "LOST" badge instead of trend value */
+  isLost?: boolean
+  /**
+   * Show "LOST" when a percent change reaches -100%. Default: true. Set false
+   * for a rate metric, where falling to zero is a value, not a lost row.
+   */
+  autoLost?: boolean
+  /**
+   * Clamp a percent change past ±999 to a fun label, with the full value in the
+   * title. Only `format="percent"` clamps: +1,500 clicks is a count, not a
+   * "10x+" ratio. Set false to always show the full value. Default: true
+   */
+  clamp?: boolean
+  /** Max decimal places for non-integer values. Use 'auto' to scale precision based on magnitude (1dp ≥10, 2dp ≥1, 3dp ≥0.1, 4dp smaller). Default: 1 */
+  precision?: number | 'auto'
+}>()
+
+const sizes = {
+  '2xs': 'text-mini',
+  'xs': 'text-xs',
+  'sm': 'text-sm',
+  'md': 'text-base',
+  'lg': 'text-lg',
+  'xl': 'text-xl',
+} as const
+
+const numericValue = computed(() => typeof value === 'string' ? Number.parseFloat(value) : value)
+
+// Auto-detect "lost" state: percent format and value <= -100 means went to zero
+const detectedLost = computed(() => autoLost && !isNew && !isLost && !inverted && format === 'percent' && numericValue.value <= -100)
+
+// The sign of the value as DISPLAYED. A change that rounds to zero at the
+// display precision (0.04% at 1dp) is no change: a green "+0.0%" claimed one.
+const trend = computed<-1 | 0 | 1>(() => {
+  const v = numericValue.value
+  if (!Number.isFinite(v) || Number(formatNum(Math.abs(v))) === 0)
+    return 0
+  return v > 0 ? 1 : -1
+})
+
+const clampsValue = computed(() => shouldClamp && format === 'percent')
+
+const trendColor = computed(() => {
+  const t = trend.value
+  if (t === 0 || !colored)
+    return 'text-muted'
+  const positive = inverted ? t === -1 : t === 1
+  return positive ? 'text-success' : 'text-error'
+})
+
+const isClamped = computed(() => {
+  if (!clampsValue.value)
+    return false
+  const raw = typeof value === 'string' ? Number.parseFloat(value) : value
+  return Math.abs(raw) > 999
+})
+
+function resolveDecimals(abs: number): number {
+  if (precision !== 'auto')
+    return precision
+  if (abs >= 10)
+    return 1
+  if (abs >= 1)
+    return 2
+  if (abs >= 0.1)
+    return 3
+  return 4
+}
+
+function formatNum(n: number): string {
+  if (n % 1 === 0)
+    return String(n)
+  const fixed = n.toFixed(resolveDecimals(Math.abs(n)))
+  return precision === 'auto' ? fixed.replace(/\.?0+$/, '') || '0' : fixed
+}
+
+const fullValue = computed(() => {
+  const raw = typeof value === 'string' ? Number.parseFloat(value) : value
+  const signed = showSign || format !== 'number'
+  const sign = signed && raw > 0 ? '+' : signed && raw < 0 ? '-' : ''
+  const abs = Math.abs(raw)
+  const suffix = format === 'percent' ? '%' : format === 'points' ? ' percentage points' : ''
+  return `${sign}${formatNum(abs)}${suffix}`
+})
+
+const displayValue = computed(() => {
+  const raw = typeof value === 'string' ? Number.parseFloat(value) : value
+  const v = clampsValue.value ? clamp(raw, -999, 999) : raw
+  const abs = Math.abs(v)
+  const signed = showSign || format !== 'number'
+  const sign = signed && v > 0 ? '+' : signed && v < 0 ? '-' : ''
+  const num = signed ? abs : v
+  const suffix = format === 'percent' ? '%' : format === 'points' ? ' points' : ''
+  return `${sign}${formatNum(num)}${suffix}`
+})
+
+const trendIcon = computed(() =>
+  trend.value === 1 ? 'arrow-up-right' : 'arrow-down-right',
+)
+
+const classes = computed(() => {
+  return [
+    trendColor.value,
+    sizes[size as keyof typeof sizes],
+  ]
+})
+</script>
+
+<template>
+  <!-- NEW badge mode -->
+  <span v-if="isNew" data-ui="UiTrend" class="inline-flex items-center font-medium uppercase px-1.5 py-0.5 rounded bg-success/10 text-success" :class="sizes[size as keyof typeof sizes]">
+    New
+  </span>
+  <!-- LOST badge mode (explicit or auto-detected from -100% change) -->
+  <span v-else-if="isLost || detectedLost" data-ui="UiTrend" class="inline-flex items-center font-medium uppercase px-1.5 py-0.5 rounded bg-error/10 text-error" :class="sizes[size as keyof typeof sizes]">
+    Lost
+  </span>
+  <!-- Zero trend — show dash -->
+  <span v-else-if="trend === 0" data-ui="UiTrend" class="text-dimmed" :class="sizes[size as keyof typeof sizes]" role="img" aria-label="No change">—</span>
+  <!-- Clamped trend — fun tag with tooltip for real value -->
+  <span
+    v-else-if="isClamped"
+    data-ui="UiTrend"
+    class="inline-flex items-center whitespace-nowrap leading-none font-semibold tracking-tight px-1.5 py-0.5 ml-1 rounded cursor-default"
+    :class="[classes, colored ? (trend === 1 ? 'bg-success/10' : 'bg-error/10') : 'bg-muted']"
+    :title="fullValue"
+  >
+    {{ trend === 1 ? '10x+' : 'oof' }}
+  </span>
+  <!-- Standard trend mode -->
+  <span
+    v-else
+    data-ui="UiTrend"
+    class="inline-flex gap-px items-center whitespace-nowrap leading-none tabular-nums font-semibold tracking-tight ml-1"
+    :class="classes"
+    :title="format === 'points' ? fullValue : undefined"
+    :role="iconOnly || format === 'points' ? 'img' : undefined"
+    :aria-label="iconOnly ? `${trend === 1 ? 'Up' : 'Down'} ${fullValue}` : format === 'points' ? fullValue : undefined"
+  >
+    <UiIcon
+      v-if="iconOnly"
+      :name="trendIcon"
+      class="size-3 shrink-0"
+      aria-hidden="true"
+    />
+    <template v-else>{{ displayValue }}</template>
+  </span>
+</template>