@nuxtseo/design-system 0.0.0-stage → 0.1.1

package/app/utils/export-download.ts

@@ -0,0 +1,100 @@
+/**
+ * CSV and JSON exports for data lists and tables (ADR-0076).
+ * VISION principle 7 (independence): every data list ships a way out. One
+ * serialiser for every surface, so no page re-inlines its own `toCsv`.
+ *
+ * The serialisers are pure. Only `downloadCsv` and `downloadJson` touch the DOM.
+ */
+
+/** One exported column: the header a spreadsheet shows, and the cell value. */
+export interface ExportColumn<T> {
+  /** The JSON key. Falls back to `header`. */
+  readonly key?: string
+  readonly header: string
+  readonly value: (row: T) => unknown
+}
+
+/**
+ * A spreadsheet runs a cell that starts with one of these as a formula, so a
+ * row value such as `=HYPERLINK(...)` from a crawled page would execute on open.
+ * Tab and carriage return start a formula in some spreadsheets too (OWASP CSV
+ * injection).
+ */
+const FORMULA_PREFIX = /^[=+\-@\t\r]/
+
+function cellText(value: unknown): string {
+  if (value === null || value === undefined)
+    return ''
+  if (value instanceof Date)
+    return Number.isNaN(value.getTime()) ? '' : value.toISOString()
+  if (typeof value === 'object')
+    return JSON.stringify(value)
+  return String(value)
+}
+
+/**
+ * One quoted CSV cell. A text cell that starts with a formula character gets a
+ * leading apostrophe, so the spreadsheet shows it as text. A finite number
+ * stays a number, so `-12` still sorts and sums as a number.
+ */
+export function csvCell(value: unknown): string {
+  const text = cellText(value)
+  const isNumber = typeof value === 'number' && Number.isFinite(value)
+  const safe = !isNumber && FORMULA_PREFIX.test(text) ? `'${text}` : text
+  return `"${safe.replace(/"/g, '""')}"`
+}
+
+/**
+ * Serialise rows to CSV over the given ordered columns. The first line holds the
+ * headers. Lines end with CRLF (RFC 4180). Pure.
+ */
+export function tableToCsv<T>(rows: readonly T[], columns: readonly ExportColumn<T>[]): string {
+  const lines = [
+    columns.map(column => csvCell(column.header)).join(','),
+    ...rows.map(row => columns.map(column => csvCell(column.value(row))).join(',')),
+  ]
+  return `${lines.join('\r\n')}\r\n`
+}
+
+/** Serialise rows to records keyed by each column's key, else its header. Pure. */
+export function tableToRecords<T>(rows: readonly T[], columns: readonly ExportColumn<T>[]): Record<string, unknown>[] {
+  return rows.map(row => Object.fromEntries(columns.map(column => [column.key ?? column.header, column.value(row)])))
+}
+
+/** Columns from row keys, for rows whose keys are already their headers. */
+export function keyColumns<T>(keys: readonly (keyof T & string)[]): ExportColumn<T>[] {
+  return keys.map(key => ({ header: key, value: row => row[key] }))
+}
+
+/** Serialise rows to CSV over the given ordered keys. Pure. */
+export function rowsToCsv<T>(rows: readonly T[], keys: readonly (keyof T & string)[]): string {
+  return tableToCsv(rows, keyColumns(keys))
+}
+
+function triggerDownload(filename: string, content: string, mime: string): void {
+  const blob = new Blob([content], { type: mime })
+  const url = URL.createObjectURL(blob)
+  const a = document.createElement('a')
+  a.href = url
+  a.download = filename
+  a.click()
+  URL.revokeObjectURL(url)
+}
+
+/**
+ * Download CSV text. The byte order mark makes Excel read the file as UTF-8,
+ * so a non-ASCII query or URL keeps its characters.
+ */
+export function downloadCsvText(filename: string, csv: string): void {
+  triggerDownload(filename, `\uFEFF${csv}`, 'text/csv;charset=utf-8')
+}
+
+/** Serialise rows to CSV over the given ordered keys and download it. */
+export function downloadCsv<T>(filename: string, rows: readonly T[], keys: readonly (keyof T & string)[]): void {
+  downloadCsvText(filename, rowsToCsv(rows, keys))
+}
+
+/** Serialise any value to pretty JSON and download it. */
+export function downloadJson(filename: string, data: unknown): void {
+  triggerDownload(filename, JSON.stringify(data, null, 2), 'application/json')
+}

package/app/utils/favicon-fallback.ts

@@ -0,0 +1,12 @@
+export function faviconProxyPath(domain: string): string {
+  return `/api/favicon?domain=${encodeURIComponent(domain)}&fallback=blank`
+}
+
+export function faviconFallbackInitial(fallbackLabel: string, domain: string): string {
+  const source = fallbackLabel.trim() || domain.replace(/^www\./, '')
+  return (source[0] ?? '?').toUpperCase()
+}
+
+export function isBlankFaviconSize(width: number, height: number): boolean {
+  return width === 1 && height === 1
+}

package/app/utils/icon-color.ts

@@ -0,0 +1,105 @@
+import { tryUseNuxtApp, useAppConfig } from 'nuxt/app'
+
+export type IconColor
+  = | 'neutral'
+    | 'primary'
+    | 'pro'
+    | 'success'
+    | 'warning'
+    | 'error'
+    | 'info'
+    | 'red'
+    | 'orange'
+    | 'amber'
+    | 'yellow'
+    | 'green'
+    | 'emerald'
+    | 'teal'
+    | 'blue'
+    | 'cyan'
+    | 'sky'
+    | 'indigo'
+    | 'violet'
+    | 'purple'
+    | 'pink'
+    | 'rose'
+    | 'gray'
+    | 'slate'
+
+/** The container fill and glyph colour classes one icon colour role paints. */
+export interface IconColorClasses {
+  bg: string
+  text: string
+}
+
+/** A role name to its classes. A site adds or remaps roles in app.config. */
+export type IconColorRoles = Readonly<Record<string, IconColorClasses>>
+
+/**
+ * The layer's icon colour roles. A site adds a role, or remaps one, under
+ * `designSystem.iconColors` in its app.config. Tailwind only emits classes it
+ * finds as literals in scanned source, so the site writes them there in full.
+ */
+export const ICON_COLOR_ROLES: Readonly<Record<IconColor, IconColorClasses>> = {
+  neutral: { bg: 'bg-accented', text: 'text-muted' },
+  primary: { bg: 'bg-primary/10', text: 'text-primary' },
+  pro: { bg: 'bg-pro/10', text: 'text-pro' },
+  success: { bg: 'bg-success/10', text: 'text-success' },
+  warning: { bg: 'bg-warning/10', text: 'text-warning' },
+  error: { bg: 'bg-error/10', text: 'text-error' },
+  info: { bg: 'bg-info/10', text: 'text-info' },
+  red: { bg: 'bg-red-500/10', text: 'text-red-500' },
+  orange: { bg: 'bg-orange-500/10', text: 'text-orange-500' },
+  amber: { bg: 'bg-amber-500/10', text: 'text-amber-500' },
+  yellow: { bg: 'bg-yellow-500/10', text: 'text-yellow-500' },
+  green: { bg: 'bg-green-500/10', text: 'text-green-500' },
+  emerald: { bg: 'bg-emerald-500/10', text: 'text-emerald-500' },
+  teal: { bg: 'bg-teal-500/10', text: 'text-teal-500' },
+  blue: { bg: 'bg-blue-500/10', text: 'text-blue-500' },
+  cyan: { bg: 'bg-cyan-500/10', text: 'text-cyan-500' },
+  sky: { bg: 'bg-sky-500/10', text: 'text-sky-500' },
+  indigo: { bg: 'bg-indigo-500/10', text: 'text-indigo-500' },
+  violet: { bg: 'bg-violet-500/10', text: 'text-violet-500' },
+  purple: { bg: 'bg-purple-500/10', text: 'text-purple-500' },
+  pink: { bg: 'bg-pink-500/10', text: 'text-pink-500' },
+  rose: { bg: 'bg-rose-500/10', text: 'text-rose-500' },
+  // 'gray' is a semantic alias for 'neutral': raw `gray-*` Tailwind utilities
+  // render Tailwind's stock cold gray, not the app's warm-slate neutral ramp
+  // (global.css re-derives `--color-slate-*`, not `--color-gray-*`), so this
+  // reuses the same semantic tokens as 'neutral' rather than the raw hue.
+  gray: { bg: 'bg-accented', text: 'text-muted' },
+  slate: { bg: 'bg-slate-500/10', text: 'text-slate-500' },
+}
+
+/**
+ * Pure lookup: the classes for `color` in `roles`. An unknown or empty role
+ * paints `neutral`.
+ */
+export function resolveIconColor(color: IconColor | string | null | undefined, roles: IconColorRoles = ICON_COLOR_ROLES): IconColorClasses {
+  const neutral = roles.neutral ?? ICON_COLOR_ROLES.neutral
+  if (!color)
+    return neutral
+  return roles[color] ?? neutral
+}
+
+/** The app.config roles, or none outside a Nuxt app. */
+function siteIconColorRoles(): IconColorRoles | undefined {
+  if (!tryUseNuxtApp())
+    return undefined
+  return useAppConfig().designSystem?.iconColors as IconColorRoles | undefined
+}
+
+/**
+ * The classes for an icon colour role, including roles the site adds in
+ * app.config. Call it from component setup or render, where the Nuxt app is
+ * available. Each call reads app.config live, site role first, then layer
+ * role. A merged copy cached per config object went stale when a role was
+ * added to that same object after the first lookup.
+ */
+export function getIconColor(color: IconColor | string | null | undefined): IconColorClasses {
+  const site = siteIconColorRoles()
+  const neutral = site?.neutral ?? ICON_COLOR_ROLES.neutral
+  if (!color)
+    return neutral
+  return site?.[color] ?? (ICON_COLOR_ROLES as IconColorRoles)[color] ?? neutral
+}

package/app/utils/number.ts

@@ -0,0 +1,74 @@
+/**
+ * Calculate percentage change between two values.
+ * Returns 0 if prev is 0 (avoids division by zero).
+ *
+ * Not clamped: a clamp here read 2 → 60 clicks as "+999%", and it hid the
+ * change from UiTrend, whose own clamp shows "10x+" above 999 with the exact
+ * value in its title. Clamping is presentation, so it stays in UiTrend.
+ */
+export function percentChange(current: number, prev: number): number {
+  if (!prev)
+    return 0
+  // Divide by the size of the base, so a rise from -10 to -5 reads as +50%,
+  // not -50%. Signed series (the desktop-minus-mobile gap) have negative bases.
+  return Math.round(((current - prev) / Math.abs(prev)) * 100) || 0
+}
+
+/**
+ * Clamp a number between min and max values:
+ *
+ * @example clamp(-5, 1, 5) // 1
+ * @example clamp(10, 1, 5) // 5
+ *
+ * Or clamp an index to valid array indices:
+ *
+ * @example clamp(-5, [1, 2, 3, 4, 5]) // 0
+ * @example clamp(10, [1, 2, 3, 4, 5]) // 4
+ */
+export function clamp(value: number, arr: readonly unknown[]): number
+export function clamp(value: number, min: number, max: number): number
+export function clamp(value: number, a: number | readonly unknown[], b?: number): number {
+  if (isReadonlyArray(a))
+    return Math.min(Math.max(value, 0), a.length - 1)
+  const min = a
+  const max = b ?? min
+  return Math.min(Math.max(value, min), max)
+}
+
+function isReadonlyArray(value: number | readonly unknown[]): value is readonly unknown[] {
+  return Array.isArray(value)
+}
+
+/**
+ * Whole-number percentages of `values` that sum to exactly 100 (largest
+ * remainder). Rounding each share on its own made a column read 99% or 101%.
+ * All zero (or empty) gives all zero.
+ */
+export function roundedShares(values: readonly number[]): number[] {
+  const total = values.reduce((sum, v) => sum + Math.max(0, v), 0)
+  if (total <= 0)
+    return values.map(() => 0)
+  const exact = values.map(v => Math.max(0, v) / total * 100)
+  const floors = exact.map(Math.floor)
+  let left = 100 - floors.reduce((sum, v) => sum + v, 0)
+  const order = exact.map((v, i) => ({ i, frac: v - floors[i]! })).sort((a, b) => b.frac - a.frac || a.i - b.i)
+  for (const { i } of order) {
+    if (left <= 0)
+      break
+    floors[i]!++
+    left--
+  }
+  return floors
+}
+
+/**
+ * A rounded share as a label. A non-zero slice never reads "0%", and a slice
+ * beside other non-zero slices never reads "100%".
+ */
+export function roundedShareLabel(rounded: number, value: number, othersNonZero: boolean): string {
+  if (value > 0 && rounded === 0)
+    return '<1%'
+  if (rounded === 100 && othersNonZero)
+    return '>99%'
+  return `${rounded}%`
+}

package/app/utils/render-link.ts

@@ -0,0 +1,14 @@
+import type { NuxtLinkProps } from 'nuxt/app'
+import type { AnchorHTMLAttributes, VNode } from 'vue'
+import type { NavigationDestination } from '../shared/navigation'
+import { createVNode } from 'vue'
+import { NuxtLink } from '#components'
+
+type LinkProps = Omit<NuxtLinkProps, 'to' | 'href'>
+  & Omit<AnchorHTMLAttributes, keyof NuxtLinkProps>
+  & { to?: NavigationDestination, href?: NavigationDestination }
+
+// Check the destination before Vue expands the component's complete prop map.
+export function renderLink(props: LinkProps, children: (() => unknown) | Record<string, () => unknown>): VNode {
+  return createVNode(NuxtLink, props, typeof children === 'function' ? { default: children } : children)
+}

package/app/utils/slot-text.ts

@@ -0,0 +1,18 @@
+/**
+ * Shared options for the design-system slot text roll.
+ *
+ * Kept as a local type so components can expose tuning without depending on the
+ * external `slot-text` package or carrying its DOM controller runtime.
+ */
+export interface SlotTextOptions {
+  direction?: 'up' | 'down'
+  stagger?: number
+  duration?: number
+  exitOffset?: number
+  easing?: string
+  bounce?: number
+  color?: string | ((index: number, total: number) => string)
+  colorFade?: number
+  skipUnchanged?: boolean
+  interrupt?: boolean
+}

package/app/utils/squircle.ts

@@ -0,0 +1,154 @@
+/**
+ * Figma-style squircle (smooth-corner) SVG path generation.
+ *
+ * Vendored and trimmed from Lisse (`@lisse/core`, MIT © Jace), which in turn
+ * implements Figma's smoothing algorithm via MartinRGB's approximation:
+ *   https://www.figma.com/blog/desperately-seeking-squircles/
+ *   https://github.com/MartinRGB/Figma_Squircles_Approximation
+ *
+ * We only need the uniform-radius squircle curve (not arc / superellipse /
+ * clothoid, nor per-corner config), so this is the squircle path math only.
+ * Used as the Safari/Firefox fallback for the native CSS `corner-shape:
+ * squircle` progressive enhancement (see global.css + UiCard).
+ */
+
+export interface SquircleOptions {
+  /** Corner radius in px. */
+  radius: number
+  /** 0 (sharp) → 1 (max). Default 0.6 (Figma's value). */
+  smoothing?: number
+  /** Keep the smoothing even when the corner is space-constrained. Default true. */
+  preserveSmoothing?: boolean
+}
+
+interface CornerPathParams {
+  a: number
+  b: number
+  c: number
+  d: number
+  p: number
+  arcSectionLength: number
+  cornerRadius: number
+}
+
+const toRadians = (deg: number) => (deg * Math.PI) / 180
+const f = (n: number) => n.toFixed(4)
+
+/** Tagged template that formats interpolated numbers to 4 decimal places. */
+function rounded(strings: TemplateStringsArray, ...values: number[]): string {
+  let out = strings[0] ?? ''
+  for (let i = 0; i < values.length; i++) {
+    const value = values[i]
+    out += `${value === undefined ? '' : value.toFixed(4)}${strings[i + 1] ?? ''}`
+  }
+  return out
+}
+
+const adjacentsByCorner = {
+  topLeft: [{ corner: 'topRight', side: 'top' }, { corner: 'bottomLeft', side: 'left' }],
+  topRight: [{ corner: 'topLeft', side: 'top' }, { corner: 'bottomRight', side: 'right' }],
+  bottomLeft: [{ corner: 'bottomRight', side: 'bottom' }, { corner: 'topLeft', side: 'left' }],
+  bottomRight: [{ corner: 'bottomLeft', side: 'bottom' }, { corner: 'topRight', side: 'right' }],
+} as const
+
+type Corner = keyof typeof adjacentsByCorner
+
+/**
+ * Distribute available space among corners, clamping radii so they can't
+ * exceed the rectangle. Larger corners get priority. With a uniform radius
+ * this only matters on small/thin elements.
+ */
+function distributeAndNormalize(radius: number, width: number, height: number) {
+  const radii: Record<Corner, number> = { topLeft: radius, topRight: radius, bottomLeft: radius, bottomRight: radius }
+  const budgets: Record<Corner, number> = { topLeft: -1, topRight: -1, bottomLeft: -1, bottomRight: -1 }
+
+  ;(Object.entries(radii) as [Corner, number][])
+    .sort(([, r1], [, r2]) => r2 - r1)
+    .forEach(([corner, r]) => {
+      const budget = Math.min(...adjacentsByCorner[corner].map((adj) => {
+        const adjRadius = radii[adj.corner]
+        if (r === 0 && adjRadius === 0)
+          return 0
+        const adjBudget = budgets[adj.corner]
+        const sideLength = adj.side === 'top' || adj.side === 'bottom' ? width : height
+        return adjBudget >= 0 ? sideLength - adjBudget : (r / (r + adjRadius)) * sideLength
+      }))
+      budgets[corner] = budget
+      radii[corner] = Math.min(r, budget)
+    })
+
+  return { radii, budgets }
+}
+
+/** Bézier-curve parameters for one corner (Figma squircle). */
+function getPathParamsForCorner(cornerRadius: number, cornerSmoothing: number, preserveSmoothing: boolean, budget: number): CornerPathParams {
+  if (cornerRadius <= 0)
+    return { a: 0, b: 0, c: 0, d: 0, p: 0, arcSectionLength: 0, cornerRadius: 0 }
+
+  let p = (1 + cornerSmoothing) * cornerRadius
+  if (!preserveSmoothing) {
+    const maxSmoothing = budget / cornerRadius - 1
+    cornerSmoothing = Math.min(cornerSmoothing, maxSmoothing)
+    p = Math.min(p, budget)
+  }
+
+  const arcMeasure = 90 * (1 - cornerSmoothing)
+  const arcSectionLength = Math.sin(toRadians(arcMeasure / 2)) * cornerRadius * Math.sqrt(2)
+  const angleAlpha = (90 - arcMeasure) / 2
+  const p3ToP4Distance = cornerRadius * Math.tan(toRadians(angleAlpha / 2))
+  const angleBeta = 45 * cornerSmoothing
+  const c = p3ToP4Distance * Math.cos(toRadians(angleBeta))
+  const d = c * Math.tan(toRadians(angleBeta))
+
+  let b = (p - arcSectionLength - c - d) / 3
+  let a = 2 * b
+  if (preserveSmoothing && p > budget) {
+    const p1ToP3MaxDistance = budget - d - arcSectionLength - c
+    const minA = p1ToP3MaxDistance / 6
+    const maxB = p1ToP3MaxDistance - minA
+    b = Math.min(b, maxB)
+    a = p1ToP3MaxDistance - b
+    p = Math.min(p, budget)
+  }
+
+  return { a, b, c, d, p, arcSectionLength, cornerRadius }
+}
+
+function drawTopRight({ cornerRadius, a, b, c, d, arcSectionLength }: CornerPathParams) {
+  return cornerRadius
+    ? rounded`c ${a} 0 ${a + b} 0 ${a + b + c} ${d} a ${cornerRadius} ${cornerRadius} 0 0 1 ${arcSectionLength} ${arcSectionLength} c ${d} ${c} ${d} ${b + c} ${d} ${a + b + c}`
+    : ''
+}
+function drawBottomRight({ cornerRadius, a, b, c, d, arcSectionLength }: CornerPathParams) {
+  return cornerRadius
+    ? rounded`c 0 ${a} 0 ${a + b} ${-d} ${a + b + c} a ${cornerRadius} ${cornerRadius} 0 0 1 ${-arcSectionLength} ${arcSectionLength} c ${-c} ${d} ${-(b + c)} ${d} ${-(a + b + c)} ${d}`
+    : ''
+}
+function drawBottomLeft({ cornerRadius, a, b, c, d, arcSectionLength }: CornerPathParams) {
+  return cornerRadius
+    ? rounded`c ${-a} 0 ${-(a + b)} 0 ${-(a + b + c)} ${-d} a ${cornerRadius} ${cornerRadius} 0 0 1 ${-arcSectionLength} ${-arcSectionLength} c ${-d} ${-c} ${-d} ${-(b + c)} ${-d} ${-(a + b + c)}`
+    : ''
+}
+function drawTopLeft({ cornerRadius, a, b, c, d, arcSectionLength }: CornerPathParams) {
+  return cornerRadius
+    ? rounded`c 0 ${-a} 0 ${-(a + b)} ${d} ${-(a + b + c)} a ${cornerRadius} ${cornerRadius} 0 0 1 ${arcSectionLength} ${-arcSectionLength} c ${c} ${-d} ${b + c} ${-d} ${a + b + c} ${-d}`
+    : ''
+}
+
+/** SVG path `d` string for a smooth-cornered rectangle, traversed clockwise from the top-left. */
+export function squircleSvgPath(width: number, height: number, { radius, smoothing = 0.6, preserveSmoothing = true }: SquircleOptions): string {
+  if (width <= 0 || height <= 0)
+    return ''
+  const { radii, budgets } = distributeAndNormalize(radius, width, height)
+  const params = (c: Corner) => getPathParamsForCorner(radii[c], smoothing, preserveSmoothing, budgets[c])
+  const tl = params('topLeft')
+  const tr = params('topRight')
+  const br = params('bottomRight')
+  const bl = params('bottomLeft')
+
+  return `M ${f(tl.p)} 0`
+    + ` L ${f(width - tr.p)} 0 ${drawTopRight(tr)}`
+    + ` L ${f(width)} ${f(br.p)} L ${f(width)} ${f(height - br.p)} ${drawBottomRight(br)}`
+    + ` L ${f(width - bl.p)} ${f(height)} L ${f(bl.p)} ${f(height)} ${drawBottomLeft(bl)}`
+    + ` L 0 ${f(height - tl.p)} L 0 ${f(tl.p)} ${drawTopLeft(tl)} Z`
+}

package/app/utils/topEntityStack.ts

@@ -0,0 +1,197 @@
+// Shared "top N + Other" stacked-trend bucketing — pure, dependency-free logic
+// backing `UiTopEntityStackChart`. Used for the search-console Queries / Pages
+// / Countries trend charts (manual-review-2026-08): pick the top N entities by
+// total value over the range, zero-fill each against the full date axis (an
+// entity absent on a given day reads as a zero band, never a gap), roll
+// everything else into a single "Other" band, and coarsen the date axis into
+// a bounded number of buckets so a wide range doesn't render one bar per day.
+//
+// "Other" has two modes:
+//  - `totals` supplied (the caller only fetched the top-K candidates, not the
+//    full entity universe): Other = total - sum(top N). This is the common
+//    case — GSC queries/pages have far more than 5 distinct values.
+//  - `totals` omitted (the caller supplied every candidate, e.g. a bounded
+//    dimension like country): Other = sum of every candidate beyond top N.
+
+import type { ChartAnnotation } from './chartAnnotations'
+import { toChartDayKey } from './chartAnnotations'
+
+const EPSILON = 1e-9
+
+export interface TopEntityDayRow {
+  /** ISO `YYYY-MM-DD` day. */
+  date: string
+  /** Stable entity identity (query text, page path, country code). */
+  key: string
+  /** Display label. Defaults to `key` when omitted at the call site. */
+  label: string
+  /** Metric value for this entity on this day (already the selected metric). */
+  value: number
+}
+
+export interface TopEntityStackBucket {
+  /** First day folded into this bucket. */
+  start: string
+  /** Last day folded into this bucket. */
+  end: string
+}
+
+export interface TopEntityStackSeries {
+  key: string
+  label: string
+  /** One value per bucket, aligned to `result.buckets`. */
+  values: number[]
+  isOther: boolean
+}
+
+export interface TopEntityStackResult {
+  buckets: TopEntityStackBucket[]
+  series: TopEntityStackSeries[]
+}
+
+export interface BucketTopEntitiesOptions {
+  /** Full canonical date axis, ascending, no gaps — the zero-fill target. */
+  dates: string[]
+  /** Sparse per-entity-per-day rows. A missing (entity, date) pair is 0. */
+  rows: TopEntityDayRow[]
+  /** How many entities stay explicit. Default 5. */
+  topN?: number
+  /** Site/aggregate total per date, aligned to `dates`. Drives Other = total - topN. */
+  totals?: number[]
+  /** Cap on rendered date buckets (adjacent days are summed together). Default 10. */
+  maxBuckets?: number
+  otherLabel?: string
+  /** Drop a candidate entirely before ranking/rolling it into Other — e.g. `isSearchOperatorQuery`. */
+  excludeKey?: (key: string) => boolean
+}
+
+export function bucketTopEntities(opts: BucketTopEntitiesOptions): TopEntityStackResult {
+  const { dates, rows, topN = 5, totals, maxBuckets = 10, otherLabel = 'All Others', excludeKey } = opts
+  if (!dates.length)
+    return { buckets: [], series: [] }
+
+  const dateIndex = new Map(dates.map((d, i) => [d, i]))
+  const filteredRows = excludeKey ? rows.filter(r => !excludeKey(r.key)) : rows
+
+  const byKey = new Map<string, { label: string, values: number[] }>()
+  for (const row of filteredRows) {
+    const idx = dateIndex.get(row.date)
+    if (idx == null)
+      continue
+    let entry = byKey.get(row.key)
+    if (!entry) {
+      entry = { label: row.label || row.key, values: Array.from({ length: dates.length }).fill(0) as number[] }
+      byKey.set(row.key, entry)
+    }
+    entry.values[idx] = (entry.values[idx] ?? 0) + row.value
+  }
+
+  const ranked = Array.from(byKey.entries(), ([key, entry]) => ({
+    key,
+    label: entry.label,
+    values: entry.values,
+    total: entry.values.reduce((sum, v) => sum + v, 0),
+  }))
+    .sort((a, b) => b.total - a.total || a.key.localeCompare(b.key))
+
+  const top = ranked.slice(0, topN)
+  const rest = ranked.slice(topN)
+
+  const otherValues = dates.map((_, i) => {
+    if (totals) {
+      const topSum = top.reduce((sum, s) => sum + (s.values[i] ?? 0), 0)
+      return Math.max(0, (totals[i] ?? 0) - topSum)
+    }
+    return rest.reduce((sum, s) => sum + (s.values[i] ?? 0), 0)
+  })
+  const hasOther = otherValues.some(v => v > EPSILON)
+
+  const daily: TopEntityStackSeries[] = top.map(s => ({
+    key: s.key,
+    label: s.label,
+    values: s.values,
+    isOther: false,
+  }))
+  if (hasOther) {
+    daily.push({
+      key: '__other__',
+      label: otherLabel,
+      values: otherValues,
+      isOther: true,
+    })
+  }
+
+  // Coarsen the date axis: fold contiguous day-groups into one bucket per
+  // series (summed), bounded to `maxBuckets`. Buckets align on the newest day,
+  // so the OLDEST bucket takes the remainder (as UiSparkColumns does). Aligned
+  // on the oldest day, the newest bar held the leftover 1 to 2 days and, in
+  // `scale="absolute"`, read as a collapse in the latest period.
+  const bucketCount = Math.max(1, Math.min(maxBuckets, dates.length))
+  const groupSize = Math.ceil(dates.length / bucketCount)
+  const buckets: TopEntityStackBucket[] = []
+  const bucketedSeries: TopEntityStackSeries[] = daily.map(s => ({ ...s, values: [] }))
+  const remainder = dates.length % groupSize
+
+  for (let start = 0; start < dates.length; start = start === 0 && remainder ? remainder : start + groupSize) {
+    const end = start === 0 && remainder ? remainder : Math.min(start + groupSize, dates.length)
+    buckets.push({ start: dates[start]!, end: dates[end - 1]! })
+    daily.forEach((s, si) => {
+      let sum = 0
+      for (let i = start; i < end; i++) sum += s.values[i] ?? 0
+      bucketedSeries[si]!.values.push(sum)
+    })
+  }
+
+  return { buckets, series: bucketedSeries }
+}
+
+export interface TopEntityStackRow {
+  i: number
+  values: number[]
+  shares: number[]
+  total: number
+}
+
+/** Preserve counts for details and express each plotted bucket as a percentage. */
+export function topEntityStackRows({ buckets, series }: TopEntityStackResult): TopEntityStackRow[] {
+  return buckets.map((_, i) => {
+    const values = series.map(s => s.values[i] ?? 0)
+    const total = values.reduce((sum, value) => sum + value, 0)
+    return { i, values, shares: values.map(value => total > 0 ? value / total * 100 : 0), total }
+  })
+}
+
+/**
+ * Anchor day annotations onto the bucket index axis. An annotation lands on
+ * the bucket whose `start <= day <= end`; one outside every bucket, or with
+ * no day, drops out. Matching only a bucket's START day silently dropped
+ * about 8 of every 9 annotations on a 90-day range.
+ */
+export function anchorAnnotationsToBuckets(
+  annotations: readonly ChartAnnotation[] | undefined,
+  buckets: readonly TopEntityStackBucket[],
+): ChartAnnotation[] {
+  if (!annotations?.length || !buckets.length)
+    return []
+  return annotations.flatMap((annotation) => {
+    const day = toChartDayKey(annotation.x)
+    if (!day)
+      return []
+    const i = buckets.findIndex(bucket => bucket.start <= day && day <= bucket.end)
+    return i === -1 ? [] : [{ ...annotation, x: i, dayKey: day }]
+  })
+}
+
+/** Project the full reporting-day axis onto the chart's bucket domain. */
+export function topEntityStackTimeline(buckets: TopEntityStackBucket[]): { dates: string[], positions: number[] } {
+  const dates: string[] = []
+  for (const bucket of buckets) {
+    const start = Date.parse(`${bucket.start}T00:00:00Z`)
+    const end = Date.parse(`${bucket.end}T00:00:00Z`)
+    for (let day = start; day <= end; day += 86_400_000)
+      dates.push(new Date(day).toISOString().slice(0, 10))
+  }
+  // Match the Overview's first-to-last-day axis, including a shorter first bucket.
+  const positions = dates.map((_, i) => dates.length === 1 ? 0 : i / (dates.length - 1) * buckets.length - 0.5)
+  return { dates, positions }
+}