@tempoxyz/ds 0.2.5 → 0.3.0

package/src/web/components/BarChart.tsx

@@ -0,0 +1,427 @@
+import type { ComponentPropsWithRef, ReactNode } from 'react'
+import { useSyncExternalStore } from 'react'
+import * as Recharts from 'recharts'
+import type * as zyzz from 'zyzz'
+import { style, variants } from '../zyzz.config.js'
+
+const reducedMotion = '(prefers-reduced-motion: reduce)'
+
+/**
+ * A stacked bar chart of values over time, such as the spend of each agent per day, built on
+ * Recharts. Each `series` stacks in its own color, in order from the baseline. A value axis with
+ * three ticks leads the plot, the `index` labels the bars below it, and a legend names each series
+ * under the chart. Hovering a bar, or moving to it with the arrow keys, shows a `BarChart.Tooltip`
+ * with the value of each series.
+ *
+ * - Name the chart with `aria-label`, or with `aria-labelledby` pointing at its heading.
+ * - Give each series a color that stays the same wherever it appears, such as an agent's brand color.
+ * - Format values with `format`, which the axis, the tooltip, and the total share.
+ * - Offer the same values as a `Table` when people need to read each one.
+ *
+ * @example
+ * <BarChart
+ *   aria-label="Spend by agent"
+ *   data={[{ claude: 1.2, codex: 0.4, day: 'Oct 1' }]}
+ *   format={(value) => `$${value}`}
+ *   index="day"
+ *   series={[
+ *     { color: '#d97757', key: 'claude', label: 'Claude' },
+ *     { color: '#10a37f', key: 'codex', label: 'Codex' },
+ *   ]}
+ * />
+ *
+ * @see {@link https://recharts.github.io/en-US/api/BarChart/ | Recharts BarChart}
+ * @see {@link https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html | WCAG 2.2 Non-text Content}
+ * @see {@link https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html | WCAG 2.2 Use of Color}
+ */
+export function BarChart<const datum extends BarChart.Datum>(props: BarChart.Props<datum>) {
+  const {
+    className,
+    data,
+    format = String,
+    height = 198,
+    index,
+    series,
+    ticks,
+    vars,
+    ...attributes
+  } = props
+  const reduced = useReducedMotion()
+  const value = (entry: datum, key: string) => Number(entry[key] ?? 0)
+  // Recharts infers its data type from a key of the generic datum and cannot resolve it, so the
+  // axis and the bars read their keys as strings.
+  const category: string = index
+  const peak = Math.max(
+    0,
+    ...data.map((entry) => series.reduce((sum, item) => sum + value(entry, item.key), 0)),
+  )
+  const step = niceStep(peak / 2)
+
+  return (
+    <div role="figure" {...attributes} {...styles.root({ className, style: props.style, vars })}>
+      <Recharts.BarChart
+        accessibilityLayer
+        barCategoryGap={3}
+        data={[...data]}
+        height={height}
+        margin={{ bottom: 0, left: 0, right: 0, top: 0 }}
+        responsive
+        width="100%"
+      >
+        <Recharts.CartesianGrid strokeDasharray="2 4" vertical={false} />
+        <Recharts.YAxis
+          axisLine={false}
+          // Three even ticks round the scale up from the tallest bar.
+          domain={[0, step * 2]}
+          tickFormatter={(tick: number) => format(tick)}
+          tickLine={false}
+          tickMargin={10}
+          tickSize={0}
+          ticks={[0, step, Number((step * 2).toPrecision(12))]}
+          width={54}
+        />
+        <Recharts.XAxis
+          axisLine={false}
+          dataKey={category}
+          height={28}
+          tickLine={false}
+          tickMargin={12}
+          tickSize={0}
+          {...(ticks ? { interval: 0, ticks: [...ticks] } : { interval: 'preserveStartEnd' })}
+        />
+        <Recharts.Tooltip
+          content={(content) => {
+            // Each payload entry carries the datum of the hovered bar, which two bars can share
+            // a label with.
+            const entry: datum | undefined = content.payload?.[0]?.payload
+            if (!content.active || !entry) return null
+
+            const items = series.map((item) => ({
+              color: item.color,
+              label: item.label,
+              value: format(value(entry, item.key)),
+            }))
+            const total = series.reduce((sum, item) => sum + value(entry, item.key), 0)
+            return <Tooltip items={items} label={String(content.label)} total={format(total)} />
+          }}
+          cursor={styles.cursor()}
+          isAnimationActive={false}
+        />
+        {/* A day without spend keeps a 2px stub at the baseline, under the bars of the others. */}
+        <Recharts.Bar
+          dataKey={() => 0}
+          isAnimationActive={false}
+          legendType="none"
+          minPointSize={2}
+          shape={(shape: Recharts.BarShapeProps) => (
+            <rect
+              {...styles.stub()}
+              height={2}
+              width={shape.width}
+              x={shape.x}
+              y={(shape.y ?? 0) + (shape.height ?? 0) - 2}
+            />
+          )}
+          stackId="total"
+          tooltipType="none"
+        />
+        {series.map((item: BarChart.Series) => (
+          <Recharts.Bar
+            animationDuration={300}
+            animationEasing="ease-out"
+            dataKey={item.key}
+            fill={item.color}
+            isAnimationActive={!reduced}
+            key={item.key}
+            name={item.label}
+            shape={segment}
+            stackId="total"
+          />
+        ))}
+      </Recharts.BarChart>
+      <div {...styles.legend()}>
+        {series.map((item) => (
+          <span key={item.key} {...styles.entry()}>
+            <span
+              aria-hidden="true"
+              {...styles.swatch({ style: { backgroundColor: item.color } })}
+            />
+            {item.label}
+          </span>
+        ))}
+      </div>
+    </div>
+  )
+}
+
+export namespace BarChart {
+  /** One bar: the value of each series, and the label of the bar under `index`. */
+  export type Datum = Record<string, number | string>
+
+  export type Props<datum extends Datum = Datum> = Omit<ComponentPropsWithRef<'div'>, 'children'> &
+    zyzz.Props.Variants<typeof styles.root> & {
+      /**
+       * One entry per bar, in order along the axis. Each series value is zero or more, since the
+       * series stack up from a zero baseline and the value axis starts at zero.
+       */
+      data: readonly datum[]
+      /**
+       * Formats a value for the axis, the tooltip, and the total, such as `(value) => `$${value}``.
+       *
+       * @default String
+       */
+      format?: ((value: number) => string) | undefined
+      /**
+       * Height in px of the plot and the axis under it. The legend adds 28px.
+       *
+       * @default 198
+       */
+      height?: number | undefined
+      /** Key of the label of each bar, such as `day`. */
+      index: keyof datum & string
+      /**
+       * The stacked series, from the baseline up, which the legend lists in the same order. Each
+       * key names a field with a number in every datum.
+       */
+      series: readonly Series<NumericKey<datum>>[]
+      /** Labels under the axis, such as every seventh day. Recharts picks them when absent. */
+      ticks?: readonly string[] | undefined
+    }
+
+  /** The keys of a datum whose values are numbers, or every key of a datum typed by `Datum`. */
+  export type NumericKey<datum extends Datum> = string extends keyof datum
+    ? string
+    : { [key in keyof datum]: datum[key] extends number ? key : never }[keyof datum] & string
+
+  /** One stacked series. */
+  export type Series<key extends string = string> = {
+    /** Fill of the series, such as the brand color of an agent. */
+    color: string
+    /** Key of the series' value in each datum. */
+    key: key
+    /** Name of the series in the legend and the tooltip. */
+    label: string
+  }
+
+  /**
+   * The card that names a bar and lists the value of each series in it, which the chart shows on
+   * hover. Render it alone to show the values of a bar elsewhere.
+   */
+  export function Tooltip(props: Tooltip.Props) {
+    const { className, items, label, total, vars, ...attributes } = props
+
+    return (
+      <div {...attributes} {...styles.tooltip({ className, style: props.style, vars })}>
+        <div {...styles.header()}>
+          <span>{label}</span>
+          {total !== undefined && <span>{total}</span>}
+        </div>
+        <ul {...styles.rows()}>
+          {items.map((item, position) => (
+            <li key={position} {...styles.row()}>
+              <span
+                aria-hidden="true"
+                {...styles.swatch({ style: { backgroundColor: item.color } })}
+              />
+              <span {...styles.series()}>{item.label}</span>
+              <span {...styles.value()}>{item.value}</span>
+            </li>
+          ))}
+        </ul>
+      </div>
+    )
+  }
+
+  export namespace Tooltip {
+    /** One series in the tooltip. */
+    export type Item = {
+      /** Color of the series, as its bars fill. */
+      color: string
+      /** Name of the series. */
+      label: ReactNode
+      /** Formatted value of the series in the bar. */
+      value: ReactNode
+    }
+
+    export type Props = Omit<ComponentPropsWithRef<'div'>, 'children'> &
+      zyzz.Props.Variants<typeof styles.tooltip> & {
+        /** The series in the bar, from the baseline up. */
+        items: readonly Item[]
+        /** Label of the bar, such as its day. */
+        label: ReactNode
+        /** Formatted total of the bar, at the end of the header. Absent, the header shows the label alone. */
+        total?: ReactNode | undefined
+      }
+  }
+}
+
+/**
+ * Returns the smallest step of 1, 2, 2.5, or 5 times a power of ten that is at least `target`. An
+ * empty chart steps by 0.5, so its scale reaches 1.
+ */
+function niceStep(target: number) {
+  if (!(target > 0)) return 0.5
+
+  const power = 10 ** Math.floor(Math.log10(target))
+  const factor = [1, 2, 2.5, 5, 10].find((entry) => entry * power >= target) ?? 10
+  return Number((factor * power).toPrecision(12))
+}
+
+/** The bar of a tooltip-less series stacks 1px below the one above it, so segments stay apart. */
+function segment(shape: Recharts.BarShapeProps) {
+  const height = Math.max((shape.height ?? 0) - 1, 0)
+
+  return (
+    <rect
+      fill={shape.fill}
+      height={height}
+      width={shape.width}
+      x={shape.x}
+      y={(shape.y ?? 0) + (shape.height ?? 0) - height}
+    />
+  )
+}
+
+/** Whether the reader asks for reduced motion, which skips the bars' growth on load. */
+function useReducedMotion() {
+  return useSyncExternalStore(
+    (notify) => {
+      const query = window.matchMedia(reducedMotion)
+      query.addEventListener('change', notify)
+      return () => query.removeEventListener('change', notify)
+    },
+    () => window.matchMedia(reducedMotion).matches,
+    () => true,
+  )
+}
+
+const Tooltip = BarChart.Tooltip
+
+namespace styles {
+  export const cursor = style({ fill: 'container.regular' }, { id: 'tds/web/bar-chart/cursor' })
+
+  export const entry = style(
+    { alignItems: 'center', columnGap: '6', display: 'inline-flex', whiteSpace: 'nowrap' },
+    { id: 'tds/web/bar-chart/entry' },
+  )
+
+  export const header = style(
+    {
+      color: 'content.primary',
+      columnGap: '12',
+      display: 'flex',
+      justifyContent: 'space-between',
+      typography: 'body.b3Strong',
+    },
+    { id: 'tds/web/bar-chart/header' },
+  )
+
+  // The legend sits 12px under the axis labels, 16px between its entries.
+  export const legend = style(
+    {
+      color: 'content.secondary',
+      columnGap: '16',
+      display: 'flex',
+      flexWrap: 'wrap',
+      marginBlockStart: '12',
+      rowGap: '4',
+      typography: 'body.b3',
+    },
+    { id: 'tds/web/bar-chart/legend' },
+  )
+
+  // Recharts draws the grid and the axis labels in SVG, so their paint comes from these selectors.
+  // An SVG text paints with `fill`, and takes `color` too so that `currentColor` matches it.
+  export const root = variants(
+    {
+      base: {
+        display: 'flex',
+        flexDirection: 'column',
+        minWidth: '0',
+        selectors: {
+          '& .recharts-cartesian-axis-tick-value': {
+            color: 'content.tertiary',
+            fill: 'currentColor !custom',
+            typography: 'body.b3',
+          },
+          '& .recharts-cartesian-grid-horizontal line': { stroke: 'line.secondary' },
+          '& .recharts-surface': { outline: 'none !custom', overflow: 'visible' },
+          '& .recharts-wrapper:focus-visible': {
+            borderRadius: '3xs',
+            outlineColor: 'border.focus',
+            outlineOffset: '2',
+            outlineStyle: 'solid !custom',
+            outlineWidth: '2',
+          },
+        },
+      },
+    },
+    { id: 'tds/web/bar-chart' },
+  )
+
+  export const row = style(
+    { alignItems: 'center', columnGap: '8', display: 'flex' },
+    { id: 'tds/web/bar-chart/row' },
+  )
+
+  export const rows = style(
+    {
+      display: 'flex',
+      flexDirection: 'column',
+      listStyle: 'none',
+      margin: '0',
+      marginBlockStart: '8',
+      padding: '0',
+      rowGap: '4',
+    },
+    { id: 'tds/web/bar-chart/rows' },
+  )
+
+  export const series = style(
+    {
+      color: 'content.secondary',
+      flexGrow: '1 !custom',
+      minWidth: '0',
+      overflow: 'hidden',
+      textOverflow: 'ellipsis',
+      whiteSpace: 'nowrap',
+    },
+    { id: 'tds/web/bar-chart/series' },
+  )
+
+  export const stub = style({ fill: 'container.strong' }, { id: 'tds/web/bar-chart/stub' })
+
+  // A swatch keeps a 2px corner, which no radius token sets.
+  export const swatch = style(
+    {
+      borderRadius: 'calc(0.125rem * var(--tds-corner-scale, 1)) !custom',
+      flexShrink: '0 !custom',
+      height: '8',
+      width: '8',
+    },
+    { id: 'tds/web/bar-chart/swatch' },
+  )
+
+  // Figma pads the 16px corner of the tooltip by 12px, below the radius, which keeps its rows dense.
+  export const tooltip = variants(
+    {
+      base: {
+        backgroundColor: 'background.elevated',
+        borderRadius: 'sm',
+        boxShadow: 'regular',
+        boxSizing: 'border-box',
+        color: 'content.primary',
+        padding: '12',
+        pointerEvents: 'none',
+        typography: 'body.b3',
+        width: '200',
+      },
+    },
+    { id: 'tds/web/bar-chart/tooltip' },
+  )
+
+  export const value = style(
+    { color: 'content.primary', flexShrink: '0 !custom' },
+    { id: 'tds/web/bar-chart/value' },
+  )
+}

package/src/web/components/Breadcrumbs.tsx

@@ -98,8 +98,8 @@ namespace styles {
   export const link = variants(
     {
       base: {
-        borderRadius: '6',
-        color: 'gray.900',
+        borderRadius: '2xs',
+        color: 'content.secondary',
         outlineColor: 'transparent !custom',
         outlineOffset: '0',
         outlineStyle: 'solid !custom',
@@ -109,15 +109,15 @@ namespace styles {
         transitionProperty: 'color, outline-color, outline-offset',
         transitionTimingFunction: 'snappy',
         // Weight overrides the typography token, so it stays after it.
-        typography: 'copy.14',
+        typography: 'body.b2',
         selectors: {
-          '&:focus-visible': { outlineColor: 'blue.700', outlineOffset: '2' },
-          '&:hover:is(a)': { color: 'foreground' },
+          '&:focus-visible': { outlineColor: 'border.focus', outlineOffset: '2' },
+          '&:hover:is(a)': { color: 'content.primary' },
         },
         '@media (prefers-reduced-motion: reduce)': { transitionProperty: 'color, outline-color' },
       },
       defaultVariants: { current: false },
-      variants: { current: { false: {}, true: { color: 'foreground' } } },
+      variants: { current: { false: {}, true: { color: 'content.primary' } } },
     },
     { id: 'tds/web/breadcrumbs/link' },
   )
@@ -141,7 +141,7 @@ namespace styles {
   export const separator = style(
     {
       alignItems: 'center',
-      color: 'gray.700',
+      color: 'content.tertiary',
       display: 'inline-flex',
       fontSize: '16',
     },