@lovett/ui 0.0.11 → 0.2.0

package/src/ranked-bars.tsx

@@ -0,0 +1,386 @@
+/**
+ * RankedBars — the `Traffic Source` shape: a label/value row over a bordered
+ * horizontal track, one row per entity, sorted by value.
+ *
+ * Promoted in ADR-146 D5 (chart layer).
+ *
+ * CONSUMERS — measured 2026-09-06 (real `from '@lovett/ui'` imports under
+ * `apps/workspace/src`; the design-system gallery is a demo harness and does
+ * NOT count toward the ADR-008 D3 gate).
+ *   TODAY (1 — gate NOT MET):
+ *     • `components/ui/admin/analytics.tsx` — the "Where time goes" usage
+ *       shares; it replaced the local `UsageBar` fork in the same pass
+ *   PLANNED: a SEM-Spec term breakdown (`lenses/sem-spec/output/`) and a
+ *   Discovery traffic/source panel. It also supersedes the ranked-bar
+ *   specimen at `design-system/spec/shell-charts.tsx:134`, which is gallery
+ *   code and not a consumer. Tracked in
+ *   `docs/follow-ups/_pending/adr-146-consumer-gate.md`.
+ *
+ * WHY THE TRACK IS BORDERED
+ * -------------------------
+ * The extracted anatomy (`METORIC-ANALYTICS-SPEC.md` 6.5) is a 317×12
+ * pill-radius track — a near-white fill under a light-grey 1px stroke, with
+ * the value bar sitting inside it. That border is not decoration: it is the
+ * only thing that makes a 3% row
+ * readable. A borderless track at a low value is a bar of nothing on a fill
+ * that is nearly the panel colour, i.e. an invisible row that still occupies
+ * space. So the track always carries `1px rgb(var(--border))`, and the row
+ * reads as "small" rather than as "broken". This is the same
+ * structure-is-required rule as CLAUDE.md's data-display surface recipe: the
+ * surface stays opaque, the grey structure lives inside it.
+ *
+ * MONOCHROME BY DEFAULT (ADR-146 D7)
+ * ----------------------------------
+ * The fill is `rgb(var(--accent))` unless an item names a palette `slot`. A
+ * ranked list is one measure over one dimension, so colouring the rows by
+ * their own rank would spend the identity channel re-encoding what bar length
+ * already shows. Pass `slot` only when the rows are genuinely different
+ * entities that are also identified by colour somewhere else on the screen
+ * (a legend, a matching line chart) — and assign the slot from the item's
+ * stable `key`, never from its index after sorting or filtering, or removing
+ * one row repaints every survivor.
+ *
+ * ROW RHYTHM
+ * ----------
+ * Rows carry `--space-2` of block padding and a `1px rgb(var(--border))`
+ * divider from the second row on. That puts `--space-4` between adjacent rows
+ * with the divider centred in the gap — the spec's row rhythm, expressed as
+ * padding + a rule rather than as a `gap` plus a separately positioned line,
+ * so the divider cannot drift off-centre when a row wraps.
+ *
+ * Token discipline: every colour is `rgb(var(--token))`; series hues resolve
+ * through the frozen `SERIES` lookup in `lib/series.ts` (ADR-146 D8 — never a
+ * constructed `--series-${i}`). The track fill is `--muted`, which is the
+ * sanctioned use for that token (a small muted well), never a card surface.
+ * Every size, gap and radius is a token; the only raw number is the track
+ * height, which is a prop with the spec's 12px default and is applied as an
+ * inline `style` rather than as a template-literal Tailwind class.
+ *
+ * Empty / loading / error are NOT handled here. `ChartFrame` owns those three
+ * states in reserved space (ADR-146 D5, D10.7) and this primitive is drawn
+ * inside it; `items={[]}` renders an empty list rather than a collapsed white
+ * gap in a frame that already reserves the box. A caller using `RankedBars`
+ * bare owes its own empty state.
+ *
+ * Motion: the fill tweens its width with `--dur-base` / `--ease-out` under
+ * `motion-safe:`, so a data change settles rather than snaps and
+ * `prefers-reduced-motion` jumps straight to the final width. Never
+ * `--ease-spring` on a data change — overshoot reads as imprecise.
+ */
+
+import { cn } from './lib/utils'
+import { normalizeToMax } from './lib/chart'
+import { slotColor, type ChartSlot, type SeriesPalette } from './lib/series'
+
+/** How `RankedBars` orders its rows before folding. */
+export type RankedBarsSort = 'desc' | 'asc' | 'none'
+
+export interface RankedBarsItem {
+  /**
+   * Stable identity key. Also the React key and the `onSelect` payload, and
+   * the thing a `slot` should be derived from (ADR-146 D7 — colour follows
+   * the entity, never its rank).
+   */
+  key: string
+  /** The row label. Always rendered — identity is never colour alone. */
+  label: string
+  /**
+   * The measure. Non-finite values are read as `0`; negatives are clamped to
+   * an empty track (a bar cannot be shorter than nothing). A series that
+   * genuinely crosses zero is not a ranked-bar chart.
+   */
+  value: number
+  /**
+   * Optional palette slot. Omit for the monochrome accent default — see the
+   * header. `'other'` renders the neutral fold swatch.
+   */
+  slot?: ChartSlot | undefined
+  /**
+   * Pre-formatted value text. Format through `@lovett/ui/format` — this
+   * primitive never formats a number, it only sets it in `tabular-nums`.
+   * Falls back to `formatValue(value)`.
+   */
+  valueLabel?: string | undefined
+}
+
+export interface RankedBarsProps {
+  /** The rows. Order only matters when `sort` is `'none'`. */
+  items: readonly RankedBarsItem[]
+  /**
+   * Row order. Default `'desc'` — a ranked list is descending unless the
+   * caller says otherwise. `'none'` keeps `items` order verbatim.
+   */
+  sort?: RankedBarsSort
+  /**
+   * Keep the first `topN` rows after sorting and fold the remainder into a
+   * single summed row. Omit for no fold. A fold is how a long tail stays
+   * honest without generating a ninth hue (ADR-146 D2).
+   */
+  topN?: number
+  /** Label for the folded row. Default `'Other'`. */
+  otherLabel?: string
+  /** Identity key for the folded row. Default `'other'`. */
+  otherKey?: string
+  /**
+   * Fixed denominator for the fill widths — pass the true total when the
+   * track should read as share-of-total rather than share-of-largest. Omit to
+   * normalise against the largest displayed row (the usual ranked-bar
+   * reading). A non-positive or non-finite `max` yields empty tracks rather
+   * than a division by zero.
+   */
+  max?: number
+  /**
+   * Which palette an item's `slot` indexes into. `'scatter'` is the
+   * all-pairs, three-slot palette. Default `'default'`.
+   */
+  palette?: SeriesPalette
+  /**
+   * Formats a value that has no `valueLabel`, and the folded row's sum.
+   * Default `String`. **`formatPercent` takes percent units, not a 0-1
+   * fraction** (ADR-146 D11) — convert at the call site.
+   */
+  formatValue?: (value: number) => string
+  /** Track height in px. Default `12`, the extracted anatomy's value. */
+  trackHeight?: number
+  /**
+   * Reserved width of the value column, so a value growing from "9" to
+   * "11,227" cannot resize the row. Pass a token-derived length.
+   * Default `var(--space-12)`.
+   */
+  valueMinWidth?: string
+  /**
+   * Floor for the LABEL column. The label/value line is the same shape as
+   * `ChartLegend`'s row — a `flex-1 min-w-0` label beside a `shrink-0` value
+   * with a reserved width — which is the shape that let `DonutChart`'s legend
+   * crush its labels to `width: 0` at 390px. Measured 2026-09-06 the ranked
+   * rows themselves did NOT reproduce that (they are full-width, with no plot
+   * competing for the row), but the failure mode is one narrow container
+   * away, so the floor is applied here too.
+   *
+   * Bounded by `min(..., 100%)` so it can never widen the row past its
+   * container; the line wraps and the value drops below the label instead.
+   * Pass a token-derived length. Default `calc(var(--space-12) * 2)`.
+   */
+  labelMinWidth?: string
+  /** Draw the between-row dividers. Default `true`. */
+  dividers?: boolean
+  /**
+   * Makes each row a button, receiving the row's `key`. Omit for a static
+   * list — an inert row must not advertise an interaction it does not have.
+   */
+  onSelect?: (key: string) => void
+  /**
+   * The emphasized row. Every other row dims. Dimming is opacity only, so
+   * nothing reflows. `null` = the caller uses the emphasis model but nothing
+   * is chosen yet; **omitted entirely** = the caller does not use it at all,
+   * and the rows then carry no `aria-pressed` (an inert list of links must
+   * not announce itself as a set of unpressed toggles).
+   */
+  activeKey?: string | null | undefined
+  /** Accessible name for the list. Default `'Ranked values'`. */
+  label?: string
+  /** Optional className on the list container. */
+  className?: string
+}
+
+interface RankedRow {
+  key: string
+  label: string
+  value: number
+  slot: ChartSlot | undefined
+  valueLabel: string | undefined
+}
+
+/** Clamp a share to `0..1` without ever returning a non-finite number. */
+function share(value: number, max: number): number {
+  if (!Number.isFinite(max) || max <= 0) return 0
+  const fraction = value / max
+  if (!Number.isFinite(fraction) || fraction <= 0) return 0
+  return fraction >= 1 ? 1 : fraction
+}
+
+export function RankedBars({
+  items,
+  sort = 'desc',
+  topN,
+  otherLabel = 'Other',
+  otherKey = 'other',
+  max,
+  palette = 'default',
+  formatValue = String,
+  trackHeight = 12,
+  valueMinWidth = 'var(--space-12)',
+  labelMinWidth = 'calc(var(--space-12) * 2)',
+  dividers = true,
+  onSelect,
+  activeKey,
+  label = 'Ranked values',
+  className,
+}: RankedBarsProps) {
+  const interactive = onSelect !== undefined
+
+  // Absorb non-finite input here so nothing downstream has to. A NaN width
+  // is not a visual bug — it drops the element, silently, with every gate
+  // green.
+  const base: RankedRow[] = items.map((item) => ({
+    key: item.key,
+    label: item.label,
+    value: Number.isFinite(item.value) ? item.value : 0,
+    slot: item.slot,
+    valueLabel: item.valueLabel,
+  }))
+
+  const ordered =
+    sort === 'none'
+      ? base
+      : [...base].sort((a, b) => (sort === 'desc' ? b.value - a.value : a.value - b.value))
+
+  let rows = ordered
+  if (topN !== undefined && Number.isInteger(topN) && topN > 0 && ordered.length > topN) {
+    const rest = ordered.slice(topN)
+    const total = rest.reduce((sum, row) => sum + row.value, 0)
+    rows = [
+      ...ordered.slice(0, topN),
+      {
+        key: otherKey,
+        label: otherLabel,
+        value: total,
+        slot: 'other',
+        valueLabel: formatValue(total),
+      },
+    ]
+  }
+
+  const fractions =
+    max === undefined
+      ? normalizeToMax(rows.map((row) => row.value))
+      : rows.map((row) => share(row.value, max))
+
+  return (
+    <ul aria-label={label} className={cn('flex w-full flex-col', className)}>
+      {rows.map((row, index) => {
+        const fraction = fractions[index] ?? 0
+        const fill = row.slot === undefined ? 'rgb(var(--accent))' : slotColor(row.slot, palette)
+        const dimmed = activeKey !== null && activeKey !== undefined && activeKey !== row.key
+
+        const body = (
+          <>
+            {/* `flex-wrap` is what makes the label floor safe: when label and
+                value cannot both fit, the VALUE wraps to a second line and
+                the label keeps its width, rather than the label collapsing. */}
+            <div className="flex w-full flex-wrap items-baseline gap-3">
+              <span
+                className="min-w-0 flex-1 truncate text-left text-[14px] font-semibold"
+                style={{
+                  color: 'rgb(var(--foreground))',
+                  minWidth: `min(${labelMinWidth}, 100%)`,
+                }}
+                title={row.label}
+              >
+                {row.label}
+              </span>
+              <span
+                className="shrink-0 text-right text-[14px] font-semibold tabular-nums"
+                style={{
+                  color: 'rgb(var(--foreground))',
+                  minWidth: valueMinWidth,
+                  marginInlineStart: 'auto',
+                }}
+              >
+                {row.valueLabel ?? formatValue(row.value)}
+              </span>
+            </div>
+            <div
+              aria-hidden="true"
+              className="w-full overflow-hidden"
+              style={{
+                marginTop: 'var(--space-2)',
+                height: trackHeight,
+                background: 'rgb(var(--muted))',
+                border: '1px solid rgb(var(--border))',
+                borderRadius: 'var(--radius-full)',
+              }}
+            >
+              <div
+                className={cn(
+                  'h-full',
+                  // `motion-reduce:transition-none` is load-bearing, not belt
+                  // and braces. The duration below is inline and therefore
+                  // unconditional, and `transition-property`'s INITIAL value
+                  // is `all` — so under prefers-reduced-motion, where the
+                  // motion-safe class does not apply, the fill would inherit
+                  // `transition: all var(--dur-base)` and tween its width,
+                  // colour and opacity anyway. A reduce user would get MORE
+                  // motion than everyone else.
+                  'motion-safe:transition-[width,opacity] motion-reduce:transition-none',
+                )}
+                style={{
+                  width: `${fraction * 100}%`,
+                  background: fill,
+                  borderRadius: 'var(--radius-full)',
+                  // The mark carries most of the de-emphasis so the label
+                  // does not have to: 0.7 (row) x 0.55 (mark) = 0.385 on the
+                  // bar, while the text stays at 0.7 and above AA.
+                  opacity: dimmed ? 0.55 : 1,
+                  transitionDuration: 'var(--dur-base)',
+                  transitionTimingFunction: 'var(--ease-out)',
+                }}
+              />
+            </div>
+          </>
+        )
+
+        const rowClass = cn(
+          'flex w-full flex-col text-left',
+          // Same guard as the fill above, and applied to BOTH branches so a
+          // static list and an interactive one settle identically.
+          'motion-safe:transition-opacity motion-reduce:transition-none',
+        )
+        const rowStyle = {
+          paddingBlock: 'var(--space-2)',
+          // 0.55 here put 14px --foreground text at 4.21:1 on a light card —
+          // under AA. A de-emphasized row is not a disabled one, so it owes
+          // the same 4.5:1 as any other text.
+          opacity: dimmed ? 0.7 : 1,
+          transitionDuration: 'var(--dur-fast)',
+          transitionTimingFunction: 'var(--ease-out)',
+        }
+
+        return (
+          <li
+            key={row.key}
+            className="min-w-0"
+            style={{
+              borderTop:
+                dividers && index > 0 ? '1px solid rgb(var(--border))' : undefined,
+            }}
+          >
+            {interactive ? (
+              <button
+                type="button"
+                aria-pressed={activeKey === undefined ? undefined : activeKey === row.key}
+                onClick={() => onSelect(row.key)}
+                className={cn(
+                  rowClass,
+                  'cursor-pointer rounded-[var(--radius-xs)]',
+                  // A clickable row that only reacts on focus reads as inert.
+                  // The house hover tint, on the row rather than the mark, so
+                  // the hit target and the feedback are the same shape.
+                  'hover:bg-[rgb(var(--surface-overlay))]',
+                  'focus-visible:outline-none focus-visible:[box-shadow:var(--ring-focus)]',
+                )}
+                style={rowStyle}
+              >
+                {body}
+              </button>
+            ) : (
+              <div className={rowClass} style={rowStyle}>
+                {body}
+              </div>
+            )}
+          </li>
+        )
+      })}
+    </ul>
+  )
+}

package/src/segmented-pill.tsx

@@ -31,9 +31,32 @@
  * control.
  *
  * Icon-agnostic. Token-only styling.
+ *
+ * ## Why this is a `group`, not a `tablist`
+ *
+ * It was a `tablist` of `tab`s, each carrying
+ * `aria-controls={`${reactId}-panel-${item.id}`}` — ids that no consumer
+ * could ever render, because `reactId` was minted inside this component and
+ * never exposed. A grep of every call site (ad-intel filter bar, community
+ * post modal, tasks display menu, discovery research options, personas add
+ * modal, social CropCard, generate form/results/landing-page, budget
+ * flighting view chips, design-system demos) found no `role="tabpanel"`
+ * anywhere: none of them render tab panels, and none of them could have
+ * wired one up if they wanted to. Every `aria-controls` in the shipped DOM
+ * pointed at nothing, and a screen reader was being told "tab 2 of 3" about
+ * a sort order, a research depth, and a crop mode.
+ *
+ * `detail/segmented-choice.tsx` already makes this argument in full and
+ * lands on `role="group"` + `aria-pressed`; this is the same control with
+ * the same answer. A group of toggle buttons says what these actually are —
+ * one of N is chosen, nothing is revealed — and the model needs no ids at
+ * all, so it cannot rot into a dangling reference again.
+ *
+ * VISUALS ARE UNCHANGED. This is a role/state change only; every class,
+ * token and style below is byte-for-byte what the tablist rendered.
  */
 
-import { useId, type ReactNode } from 'react'
+import type { ReactNode } from 'react'
 import { cn } from './lib/utils'
 
 export interface SegmentedPillItem<Id extends string = string> {
@@ -49,8 +72,12 @@ export interface SegmentedPillProps<Id extends string = string> {
   items: SegmentedPillItem<Id>[]
   value: Id
   onChange: (next: Id) => void
-  /** Accessible label for the whole group (rendered as aria-label on
-   *  the `role="tablist"` container). */
+  /**
+   * Accessible name for the whole group, rendered as `aria-label` on the
+   * `role="group"` container. Optional for backwards compatibility with the
+   * call sites that predate it, but a group of toggle buttons with no name is
+   * an unnamed group — supply it.
+   */
   ariaLabel?: string
   /** Size variant — controls vertical padding + font. Default `md`.
    *  `xs` is for dense inline contexts (e.g. a sort toggle inside a tab bar). */
@@ -69,8 +96,6 @@ export function SegmentedPill<Id extends string = string>({
   stretch = true,
   className,
 }: SegmentedPillProps<Id>) {
-  const reactId = useId()
-
   const padY = size === 'xs' ? 'py-1' : size === 'sm' ? 'py-1.5' : 'py-2'
   const textSize = size === 'xs' ? 'text-[11px]' : size === 'sm' ? 'text-[12px]' : 'text-[13px]'
   const padX = size === 'xs' ? 'px-2.5' : 'px-3'
@@ -78,7 +103,7 @@ export function SegmentedPill<Id extends string = string>({
 
   return (
     <div
-      role="tablist"
+      role="group"
       aria-label={ariaLabel}
       className={cn(
         'flex items-center gap-1',
@@ -105,9 +130,7 @@ export function SegmentedPill<Id extends string = string>({
           <button
             key={item.id}
             type="button"
-            role="tab"
-            aria-selected={isActive}
-            aria-controls={`${reactId}-panel-${item.id}`}
+            aria-pressed={isActive}
             disabled={item.disabled}
             onClick={() => onChange(item.id)}
             aria-label={item.ariaLabel}