@refraction-ui/astro 0.18.1 → 0.20.0

package/dist/line-chart/line-chart.ts

@@ -0,0 +1,215 @@
+export interface LineChartSeries {
+  /** Stable key for the series. */
+  id: string
+  /** Legend / tooltip name. */
+  name: string
+  /**
+   * Any CSS colour (a token `hsl(var(--…))` or a data colour). Defaults to the
+   * theme's chart palette (`--chart-1` … `--chart-5`) by series position.
+   */
+  color?: string
+  /** One value per label, in label order. */
+  data: number[]
+}
+
+export interface LineChartPadding {
+  top: number
+  right: number
+  bottom: number
+  left: number
+}
+
+export interface LineChartOptions {
+  series: LineChartSeries[]
+  labels: string[]
+  /** viewBox width — the SVG scales to its container's width. */
+  width: number
+  /** viewBox height. */
+  height: number
+  padding?: Partial<LineChartPadding>
+  /** Target number of gridline intervals on the y-axis (the nice scale may use fewer). */
+  tickCount?: number
+  /** Headroom multiplier above the largest value. */
+  headroom?: number
+  /**
+   * Show every n-th x label (the last label is always shown). Defaults to
+   * thinning so labels are at least ~48 viewBox units apart.
+   */
+  labelEvery?: number
+}
+
+export interface LineChartTick {
+  value: number
+  y: number
+}
+
+export interface LineChartXLabel {
+  index: number
+  label: string
+  x: number
+}
+
+export interface LineChartPath {
+  id: string
+  /** Resolved stroke colour. */
+  color: string
+  /** The stroke path. */
+  line: string
+  /** The line closed down to the zero baseline, for an area fill. */
+  area: string
+}
+
+export interface LineChartColumn {
+  index: number
+  x: number
+  width: number
+}
+
+export interface LineChartGeometry {
+  width: number
+  height: number
+  padding: LineChartPadding
+  /** Top of the shared y-scale. */
+  max: number
+  ticks: LineChartTick[]
+  xLabels: LineChartXLabel[]
+  paths: LineChartPath[]
+  /** One hover/focus column per category. */
+  columns: LineChartColumn[]
+  x: (index: number) => number
+  y: (value: number) => number
+  /** Top and bottom of the plot area, for a crosshair. */
+  plotTop: number
+  plotBottom: number
+}
+
+export const DEFAULT_LINE_CHART_PADDING: LineChartPadding = {
+  top: 14,
+  right: 14,
+  bottom: 24,
+  left: 40,
+}
+
+export const DEFAULT_LINE_CHART_WIDTH = 760
+export const DEFAULT_LINE_CHART_HEIGHT = 230
+const DEFAULT_TICK_COUNT = 4
+const DEFAULT_HEADROOM = 1.08
+/** Minimum horizontal room per x label when thinning automatically. */
+const MIN_LABEL_SPACING = 48
+/** Number of `--chart-N` tokens the theme defines. */
+const CHART_TOKEN_COUNT = 5
+
+/** The theme chart colour for the series at `index` (wraps around). */
+export function lineChartColor(index: number): string {
+  return `hsl(var(--chart-${(index % CHART_TOKEN_COUNT) + 1}))`
+}
+
+const NICE_STEPS = [1, 2, 5, 10]
+
+/**
+ * A "nice" y-scale: a 1-2-5 × 10^k step so there are at most `tickCount`
+ * intervals up to `rawMax`, and the max rounded up to a whole step. Tick
+ * values are therefore round numbers by construction (0, 2000, 4000, …) —
+ * never 5999.9999 — so any tick formatter prints clean labels.
+ */
+export function niceScale(rawMax: number, tickCount: number): { max: number; step: number; ticks: number[] } {
+  const intervals = Math.max(1, Math.floor(tickCount))
+  if (!(rawMax > 0)) return { max: 1, step: 1 / intervals, ticks: Array.from({ length: intervals + 1 }, (_, i) => i / intervals) }
+  const target = rawMax / intervals
+  const magnitude = 10 ** Math.floor(Math.log10(target))
+  const step = NICE_STEPS.map((m) => m * magnitude).find((candidate) => candidate >= target) ?? 10 * magnitude
+  const count = Math.ceil(rawMax / step - 1e-9)
+  // Strip binary floating-point noise (e.g. 0.1 * 3) to the step's precision.
+  const decimals = Math.max(0, -Math.floor(Math.log10(step)))
+  const clean = (value: number) => Number(value.toFixed(decimals))
+  const ticks = Array.from({ length: count + 1 }, (_, i) => clean(i * step))
+  return { max: ticks[ticks.length - 1], step: clean(step), ticks }
+}
+
+function pathFrom(points: Array<[number, number]>): string {
+  return points.map(([px, py], i) => (i ? 'L' : 'M') + px.toFixed(1) + ' ' + py.toFixed(1)).join(' ')
+}
+
+/**
+ * Pure geometry for a responsive multi-series line chart. Every series shares
+ * ONE y-scale (zero baseline to the largest value plus headroom), so series are
+ * comparable. Coordinates are in viewBox units; the SVG scales to its container.
+ */
+export function computeLineChart(options: LineChartOptions): LineChartGeometry {
+  const {
+    series,
+    labels,
+    width,
+    height,
+    tickCount = DEFAULT_TICK_COUNT,
+    headroom = DEFAULT_HEADROOM,
+  } = options
+  const padding = { ...DEFAULT_LINE_CHART_PADDING, ...options.padding }
+  const n = labels.length
+  const values = series.flatMap((s) => s.data)
+  const peak = values.length ? Math.max(...values) : 0
+  const scale = niceScale(peak > 0 ? peak * headroom : 0, tickCount)
+  const max = scale.max
+  const plotW = width - padding.left - padding.right
+  const plotTop = padding.top
+  const plotBottom = height - padding.bottom
+  const plotH = plotBottom - plotTop
+
+  const labelEvery =
+    options.labelEvery ??
+    Math.max(1, Math.ceil(n / Math.max(1, Math.floor(plotW / MIN_LABEL_SPACING))))
+
+  const x = (index: number) => padding.left + (n > 1 ? (index / (n - 1)) * plotW : plotW / 2)
+  const y = (value: number) => plotTop + (1 - value / max) * plotH
+
+  const ticks: LineChartTick[] = scale.ticks.map((value) => ({ value, y: y(value) }))
+
+  const xLabels: LineChartXLabel[] = labels
+    .map((label, index) => ({ index, label, x: x(index) }))
+    .filter(({ index }) => index % labelEvery === 0 || index === n - 1)
+
+  const paths: LineChartPath[] = series.map((s, si) => {
+    const points = s.data.map((v, i): [number, number] => [x(i), y(v)])
+    const line = pathFrom(points)
+    const first = points.length ? points[0][0] : x(0)
+    const last = points.length ? points[points.length - 1][0] : x(0)
+    const base = y(0).toFixed(1)
+    const area = `${line} L ${last.toFixed(1)} ${base} L ${first.toFixed(1)} ${base} Z`
+    return { id: s.id, color: s.color ?? lineChartColor(si), line, area }
+  })
+
+  const colW = n > 1 ? plotW / (n - 1) : plotW
+  const columns: LineChartColumn[] = labels.map((_, index) => ({
+    index,
+    x: x(index) - colW / 2,
+    width: colW,
+  }))
+
+  return { width, height, padding, max, ticks, xLabels, paths, columns, x, y, plotTop, plotBottom }
+}
+
+/** Where a tooltip for `index` sits horizontally, as a percent of the chart width. */
+export function tooltipLeftPercent(geometry: LineChartGeometry, index: number): number {
+  return (geometry.x(index) / geometry.width) * 100
+}
+
+/**
+ * The category index a keyboard key moves to from `current` (null = nothing
+ * active yet). Returns `current` unchanged for keys the chart doesn't handle.
+ */
+export function nextLineChartIndex(current: number | null, key: string, count: number): number | null {
+  if (count === 0) return null
+  const last = count - 1
+  switch (key) {
+    case 'ArrowRight':
+      return current == null ? 0 : Math.min(current + 1, last)
+    case 'ArrowLeft':
+      return current == null ? last : Math.max(current - 1, 0)
+    case 'Home':
+      return 0
+    case 'End':
+      return last
+    default:
+      return current
+  }
+}

package/dist/logger/faro-engine.ts

@@ -74,11 +74,11 @@ async function loadFaroTransport(
     // Indirected so bundlers keep these as runtime-optional dynamic imports.
     const sdkName = '@grafana/faro-web-sdk'
     const tracingName = '@grafana/faro-web-tracing'
-    const sdk = (await import(/* @vite-ignore */ sdkName)) as {
+    const sdk = (await import(/* webpackIgnore: true */ /* @vite-ignore */ sdkName)) as {
       initializeFaro: (cfg: unknown) => unknown
       getWebInstrumentations: () => unknown[]
     }
-    const tracing = (await import(/* @vite-ignore */ tracingName)) as {
+    const tracing = (await import(/* webpackIgnore: true */ /* @vite-ignore */ tracingName)) as {
       TracingInstrumentation: new () => unknown
     }
 

package/dist/native-select/index.ts

@@ -0,0 +1,6 @@
+export { nativeSelectChevronPath, type NativeSelectSize } from './native-select.js'
+export {
+  nativeSelectWrapperClass,
+  nativeSelectVariants,
+  nativeSelectIconClass,
+} from './native-select.styles.js'

package/dist/native-select/native-select.styles.ts

@@ -0,0 +1,30 @@
+import { cva } from '../shared/index.ts'
+
+/** Wrapper that positions the chevron over the select. */
+export const nativeSelectWrapperClass = 'relative inline-flex min-w-0 items-center'
+
+/**
+ * The `<select>`: the platform's own listbox (mobile pickers, type-to-select,
+ * form submission, `change` events) with the input look. Size-owned utilities
+ * live only in the size variants so `size` always wins.
+ */
+export const nativeSelectVariants = cva({
+  base:
+    'w-full cursor-pointer appearance-none rounded-md border border-input bg-background text-foreground shadow-sm ' +
+    'ring-offset-background focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring ' +
+    'disabled:cursor-not-allowed disabled:opacity-50',
+  variants: {
+    size: {
+      sm: 'h-8 pl-2.5 pr-8 text-xs',
+      default: 'h-9 pl-3 pr-9 text-sm',
+      lg: 'h-10 pl-3 pr-10 text-base',
+    },
+  },
+  defaultVariants: {
+    size: 'default',
+  },
+})
+
+/** The chevron: decorative, and never eats the click meant for the select. */
+export const nativeSelectIconClass =
+  'pointer-events-none absolute right-2.5 h-4 w-4 shrink-0 text-muted-foreground'

package/dist/native-select/native-select.ts

@@ -0,0 +1,5 @@
+/** Visual size of a NativeSelect. */
+export type NativeSelectSize = 'sm' | 'default' | 'lg'
+
+/** The chevron's path (a down chevron), so adapters ship no icon dependency. */
+export const nativeSelectChevronPath = 'm6 9 6 6 6-6'

package/dist/page-header/index.ts

@@ -0,0 +1,15 @@
+export {
+  createPageHeader,
+  type PageHeaderTitleLevel,
+  type PageHeaderProps,
+  type PageHeaderAPI,
+} from './page-header.js'
+
+export {
+  pageHeaderClass,
+  pageHeaderTextClass,
+  pageHeaderKickerClass,
+  pageHeaderTitleClass,
+  pageHeaderDescriptionClass,
+  pageHeaderActionsClass,
+} from './page-header.styles.js'

package/dist/page-header/page-header.styles.ts

@@ -0,0 +1,21 @@
+/**
+ * Root: text cluster on the leading edge, actions on the trailing edge; wraps
+ * on narrow screens. Carries no outer margin — the page layout spaces it.
+ */
+export const pageHeaderClass = 'flex flex-wrap items-start justify-between gap-4'
+
+/** Text cluster (kicker, title, description). */
+export const pageHeaderTextClass = 'flex min-w-0 flex-1 flex-col gap-1'
+
+/** Small uppercase eyebrow above the title. */
+export const pageHeaderKickerClass =
+  'break-words text-[11px] uppercase tracking-wider text-muted-foreground'
+
+/** Title — app-sized, not a marketing display size. */
+export const pageHeaderTitleClass = 'break-words text-xl font-semibold text-foreground'
+
+/** Supporting copy under the title, capped at a readable measure. */
+export const pageHeaderDescriptionClass = 'max-w-prose text-sm text-muted-foreground'
+
+/** Trailing actions row. */
+export const pageHeaderActionsClass = 'flex flex-none flex-wrap items-center gap-2'

package/dist/page-header/page-header.ts

@@ -0,0 +1,27 @@
+/** Heading element used for the page title. */
+export type PageHeaderTitleLevel = 'h1' | 'h2' | 'h3'
+
+export interface PageHeaderProps {
+  /** Whether an actions slot will be rendered. */
+  hasActions?: boolean
+}
+
+export interface PageHeaderAPI {
+  /** Data attributes for styling hooks. */
+  dataAttributes: Record<string, string>
+}
+
+/**
+ * Build the framework-agnostic data attributes for a PageHeader — the heading
+ * cluster at the top of an application page (kicker, title, description and a
+ * trailing actions row). Unlike SectionHead (a centred marketing heading) it is
+ * sized for dense app chrome and never centres.
+ */
+export function createPageHeader(props: PageHeaderProps = {}): PageHeaderAPI {
+  return {
+    dataAttributes: {
+      'data-slot': 'page-header',
+      'data-has-actions': props.hasActions ? 'true' : 'false',
+    },
+  }
+}

package/dist/progress-display/progress-display.styles.ts

@@ -58,7 +58,7 @@ export const badgeItemVariants = cva({
 })
 
 export const progressBarVariants = cva({
-  base: 'h-2 w-full overflow-hidden rounded-full bg-secondary',
+  base: 'w-full overflow-hidden rounded-full bg-secondary',
   variants: {
     size: {
       sm: 'h-1',

package/dist/select/index.ts

@@ -8,6 +8,8 @@ export {
 export {
   selectTriggerVariants,
   selectContentVariants,
+  selectRootClass,
+  selectValueClass,
   selectItemVariants,
   selectTokens,
 } from './select.styles.js'

package/dist/select/select.styles.ts

@@ -12,7 +12,7 @@ export const selectTokens: TokenContract = {
 }
 
 export const selectTriggerVariants = cva({
-  base: 'flex h-9 w-full items-center justify-between rounded-md border border-input bg-transparent px-3 py-2 text-sm shadow-sm ring-offset-background placeholder:text-muted-foreground focus:outline-none focus:ring-1 focus:ring-ring disabled:cursor-not-allowed disabled:opacity-50',
+  base: 'flex w-full items-center justify-between rounded-md border border-input bg-transparent px-3 py-2 shadow-sm ring-offset-background placeholder:text-muted-foreground focus:outline-none focus:ring-1 focus:ring-ring disabled:cursor-not-allowed disabled:opacity-50',
   variants: {
     size: {
       sm: 'h-8 text-xs',
@@ -26,10 +26,10 @@ export const selectTriggerVariants = cva({
 })
 
 export const selectContentVariants = cva({
-  base: 'relative z-50 max-h-96 min-w-[8rem] overflow-hidden rounded-md border bg-popover text-popover-foreground shadow-md animate-in fade-in-0 zoom-in-95',
+  base: 'absolute left-0 top-full z-50 mt-1 max-h-96 w-full min-w-[8rem] overflow-y-auto rounded-md border bg-popover text-popover-foreground shadow-md animate-in fade-in-0 zoom-in-95',
   variants: {
     position: {
-      popper: 'translate-y-1',
+      popper: '',
       'item-aligned': '',
     },
   },
@@ -50,3 +50,9 @@ export const selectItemVariants = cva({
     selected: 'false',
   },
 })
+
+/** Positioning context: the listbox floats under the trigger. */
+export const selectRootClass = 'relative'
+
+/** The selected label inside the trigger; truncates, dims the placeholder. */
+export const selectValueClass = 'truncate text-left data-[placeholder]:text-muted-foreground'

package/dist/select/select.ts

@@ -14,6 +14,12 @@ export interface SelectProps {
   disabled?: boolean
   open?: boolean
   name?: string
+  /**
+   * Element ids to link trigger and listbox. Adapters should pass ids that
+   * are stable across renders (e.g. React `useId`); when omitted, fresh ids
+   * are generated on every call.
+   */
+  ids?: { trigger: string; content: string }
 }
 
 export interface SelectAPI {
@@ -63,14 +69,16 @@ export function createSelect(props: SelectProps = {}): SelectAPI {
   const isInteractive = !disabled
   const selectedOption = options.find((o) => o.value === value)
 
-  const triggerId = generateId('select-trigger')
-  const contentId = generateId('select-content')
+  const triggerId = props.ids?.trigger ?? generateId('select-trigger')
+  const contentId = props.ids?.content ?? generateId('select-content')
 
+  // No aria-labelledby on the trigger: pointing a combobox at itself would
+  // override a caller's aria-label / <label for> and leave the accessible
+  // name as the displayed value.
   const triggerAriaProps: Partial<AccessibilityProps> = {
     role: 'combobox',
     'aria-expanded': open,
     'aria-controls': contentId,
-    'aria-labelledby': triggerId,
   }
   if (disabled) {
     triggerAriaProps['aria-disabled'] = true

package/dist/separator/index.ts

@@ -8,5 +8,7 @@ export {
 export {
   separatorVariants,
   separatorLineClass,
+  separatorSubtleLineClass,
   separatorLabelClass,
+  type SeparatorTone,
 } from './separator.styles.js'

package/dist/separator/separator.styles.ts

@@ -12,8 +12,16 @@ export const separatorVariants = cva({
   base: '',
   variants: {
     orientation: {
-      horizontal: 'h-px w-full bg-border',
-      vertical: 'w-px h-full bg-border',
+      horizontal: 'h-px w-full',
+      vertical: 'w-px h-full',
+    },
+    // Line color (issue #485). `default` is the standard border token;
+    // `subtle` uses the hairline `border-subtle` token for a lighter rule.
+    // Keeping the color here (not in `orientation`) keeps every existing call
+    // pixel-identical while adding the subtle option.
+    tone: {
+      default: 'bg-border',
+      subtle: 'bg-border-subtle',
     },
     labeled: {
       true: 'flex items-center',
@@ -22,13 +30,20 @@ export const separatorVariants = cva({
   },
   defaultVariants: {
     orientation: 'horizontal',
+    tone: 'default',
     labeled: 'false',
   },
 })
 
+/** Line tone for the separator rule and labeled-divider flanks. */
+export type SeparatorTone = 'default' | 'subtle'
+
 /** Class for each flanking line in the labeled-divider variant. */
 export const separatorLineClass = 'h-px flex-1 bg-border'
 
+/** Hairline variant of {@link separatorLineClass} (issue #485). */
+export const separatorSubtleLineClass = 'h-px flex-1 bg-border-subtle'
+
 /** Class for the centered label in the labeled-divider variant. */
 export const separatorLabelClass =
   'px-3 text-xs uppercase tracking-wide text-muted-foreground'

package/dist/shared/cn.ts

@@ -3,9 +3,12 @@
  * Handles conditional classes, arrays, and falsy values.
  * No external dependencies (no clsx, no tailwind-merge).
  *
- * For Tailwind class conflict resolution (e.g., 'p-2 p-4' → 'p-4'),
- * consumers can use @refraction-ui/tailwind-config which provides
- * a tw-merge-aware variant of this function.
+ * It does NOT resolve Tailwind conflicts: `cn('p-2', 'p-4')` keeps both and
+ * the stylesheet order decides. Components therefore keep size-owned
+ * utilities (height, text size, padding) out of their cva `base` and only in
+ * the matching variant, so a variant prop always wins; a consumer `className`
+ * that must beat a component utility can use Tailwind's `!` important
+ * modifier (e.g. `!h-7`).
  */
 
 type ClassValue = string | number | boolean | undefined | null | ClassValue[]

package/dist/slide-viewer/slide-viewer.styles.ts

@@ -45,6 +45,8 @@ export { slideViewerProgressBarVariants as progressBarVariants }
 export const slideTypeBadgeVariants = cva({
   base: 'inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-medium',
   variants: {
+    // Slide-type accents are a content-category palette (lesson/quiz/exercise…),
+    // not status tones — deliberately not routed through the theme tokens.
     type: {
       lesson: 'bg-blue-100 text-blue-800',
       quiz: 'bg-purple-100 text-purple-800',

package/dist/stat-grid/index.ts

@@ -1,12 +1,21 @@
 export {
   createStatGrid,
   statColumns,
+  statColumnsKey,
   type StatItem,
+  type StatTone,
+  type StatGridVariant,
+  type StatGridLayout,
+  type StatGridColumns,
   type StatGridAPI,
 } from './stat-grid.js'
 
 export {
   statGridVariants,
+  statItemVariants,
+  statValueVariants,
+  statLabelVariants,
+  statDescriptionClass,
   statItemClass,
   statValueClass,
   statLabelClass,

package/dist/stat-grid/stat-grid.styles.ts

@@ -1,25 +1,92 @@
 import { cva } from '../shared/index.ts'
 
-/** Grid container that lays out stat items. */
+/**
+ * Grid container. Column counts are responsive (one column on a phone, more
+ * as the width allows) — never a fixed inline template that cannot reflow.
+ * `auto` fits as many ~12rem items per row as the width allows.
+ */
 export const statGridVariants = cva({
-  base: 'grid gap-8',
+  base: 'grid',
   variants: {
     columns: {
       '1': 'grid-cols-1',
-      '2': 'grid-cols-2',
-      '3': 'grid-cols-3',
+      '2': 'grid-cols-1 sm:grid-cols-2',
+      '3': 'grid-cols-1 sm:grid-cols-2 lg:grid-cols-3',
+      '4': 'grid-cols-1 sm:grid-cols-2 lg:grid-cols-4',
+      auto: 'grid-cols-[repeat(auto-fill,minmax(12rem,1fr))]',
+    },
+    variant: {
+      plain: 'gap-8',
+      card: 'gap-3',
     },
   },
   defaultVariants: {
     columns: '3',
+    variant: 'plain',
   },
 })
 
 /** Individual stat item container (role="listitem"). */
+export const statItemVariants = cva({
+  base: 'flex min-w-0 flex-col',
+  variants: {
+    variant: {
+      plain: '',
+      card: 'gap-1 rounded-lg border border-border bg-card p-4 text-card-foreground',
+    },
+  },
+  defaultVariants: {
+    variant: 'plain',
+  },
+})
+
+/** @deprecated Use `statItemVariants()`; kept for existing imports. */
 export const statItemClass = 'flex flex-col'
 
-/** The large bold value of the stat. */
+/** The value of a stat, by variant and tone. */
+export const statValueVariants = cva({
+  base: 'font-bold tabular-nums',
+  variants: {
+    variant: {
+      plain: 'text-xl sm:text-2xl',
+      card: 'text-2xl leading-tight',
+    },
+    tone: {
+      default: '',
+      positive: 'text-success',
+      negative: 'text-destructive',
+      caution: 'text-warning',
+    },
+  },
+  compoundVariants: [
+    { variant: 'plain', tone: 'default', class: 'text-primary' },
+    { variant: 'card', tone: 'default', class: 'text-foreground' },
+  ],
+  defaultVariants: {
+    variant: 'plain',
+    tone: 'default',
+  },
+})
+
+/** @deprecated Use `statValueVariants()`; kept for existing imports. */
 export const statValueClass = 'text-xl sm:text-2xl font-bold text-primary'
 
-/** The descriptive label below the value. */
+/** The descriptive label. Above the value it reads as a small caption. */
+export const statLabelVariants = cva({
+  base: 'text-muted-foreground',
+  variants: {
+    layout: {
+      'value-first': 'mt-1 text-sm leading-snug',
+      'label-first': 'text-xs uppercase tracking-wide',
+    },
+  },
+  defaultVariants: {
+    layout: 'value-first',
+  },
+})
+
+/** @deprecated Use `statLabelVariants()`; kept for existing imports. */
 export const statLabelClass = 'mt-1 text-sm text-muted-foreground leading-snug'
+
+/** Optional line under a stat explaining how it was computed. */
+export const statDescriptionClass = 'text-xs leading-snug text-muted-foreground'

package/dist/stat-grid/stat-grid.ts

@@ -1,9 +1,24 @@
+/** Semantic colour of a stat's value. */
+export type StatTone = 'default' | 'positive' | 'negative' | 'caution'
+/** `plain` = marketing callouts; `card` = bordered dashboard KPI cards. */
+export type StatGridVariant = 'plain' | 'card'
+/** Whether the label sits under the value (callout) or above it (KPI). */
+export type StatGridLayout = 'value-first' | 'label-first'
+/** Column count: a fixed maximum that reflows down on narrow screens, or `auto`. */
+export type StatGridColumns = 1 | 2 | 3 | 4 | 'auto'
+
 /** A single stat callout displayed in the grid. */
 export type StatItem = {
   /** The primary value displayed prominently (e.g. "10k+", "$4.2M"). */
   value: string
-  /** The descriptive label shown below the value. */
+  /** The descriptive label. */
   label: string
+  /** Stable key; defaults to the index. */
+  id?: string
+  /** Optional line explaining the figure (how it was computed, a delta). */
+  description?: string
+  /** Colour of the value. Defaults to `default`. */
+  tone?: StatTone
 }
 
 export interface StatGridAPI {
@@ -20,11 +35,16 @@ export interface StatGridAPI {
  * - 2 items → 2 columns
  * - 3 or more items → capped at `max` (default 3)
  */
-export function statColumns(count: number, max = 3): number {
-  if (count <= 0) return 1
-  if (count === 1) return 1
+export function statColumns(count: number, max = 3): 1 | 2 | 3 | 4 {
+  if (count <= 1) return 1
   if (count === 2) return 2
-  return Math.min(count, max)
+  return Math.min(count, max, 4) as 3 | 4
+}
+
+/** The cva key for a column setting (clamped to the supported 1–4). */
+export function statColumnsKey(columns: StatGridColumns): '1' | '2' | '3' | '4' | 'auto' {
+  if (columns === 'auto') return 'auto'
+  return String(Math.min(Math.max(Math.round(columns), 1), 4)) as '1' | '2' | '3' | '4'
 }
 
 /**