@glyphui/ui 0.4.0 → 0.5.0

package/src/patterns/chart/scatter.tsx

@@ -0,0 +1,254 @@
+import { type ReactNode, useMemo } from 'react'
+import * as R from 'recharts'
+import { useControllableState } from '../../hooks/use-controllable-state'
+import {
+  axisTick,
+  axisWidth,
+  type CartesianChartProps,
+  type ChartAxisOptions,
+  type ChartReferenceArea,
+  type ChartReferenceLine,
+  overlays,
+} from './cartesian'
+import {
+  type ChartColorValue,
+  ChartFrame,
+  type ChartStateProps,
+  categoryColor,
+  defaultFormatter,
+  type Key,
+  toggleIn,
+  useChartAnimation,
+  useChartParts,
+} from './chart-parts'
+
+type Row = Record<string, unknown>
+
+export interface ScatterChartProps<T extends object> extends ChartStateProps {
+  data: readonly T[]
+  /** Field for the horizontal position. */
+  x: Key<T>
+  /** Field for the vertical position. */
+  y: Key<T>
+  /** Field for the point size. Turns the scatter into a bubble chart. */
+  size?: Key<T>
+  /** Field naming each point, shown in the tooltip. */
+  name?: Key<T>
+  /** Field that splits points into colored groups with a legend. */
+  groupBy?: Key<T>
+  title: string
+  description?: ReactNode
+  hideTitle?: boolean
+  /** Axis titles and tick formatters. Name the axes: a scatter has no other labels. */
+  xAxis?: ChartAxisOptions
+  yAxis?: ChartAxisOptions
+  /** Smallest and largest bubble area in pixels. Default `[40, 600]`. */
+  sizeRange?: readonly [number, number]
+  /** One color per group, in order. */
+  colors?: readonly ChartColorValue[]
+  /** Formats `size` in the tooltip. */
+  sizeFormatter?: (value: number) => string
+  referenceLines?: readonly ChartReferenceLine[]
+  referenceAreas?: readonly ChartReferenceArea[]
+  /** Plot height in pixels. Default 280. */
+  height?: number
+  showGrid?: boolean
+  showLegend?: boolean
+  hiddenGroups?: readonly string[]
+  onHiddenGroupsChange?: (hidden: string[]) => void
+  onPointClick?: (row: T) => void
+  className?: string
+}
+
+interface ScatterTooltipProps {
+  active?: boolean
+  payload?: readonly { payload?: Row }[]
+}
+
+/** How two measures relate, one dot per item. Add `size` for a third measure. */
+export function ScatterChart<T extends object>(props: ScatterChartProps<T>) {
+  const { data, x, y, size, name, groupBy, height = 280 } = props
+  const { s, slots } = useChartParts()
+  const animation = useChartAnimation()
+  const [hidden, setHidden] = useControllableState<readonly string[]>({
+    value: props.hiddenGroups,
+    defaultValue: [],
+    onChange: props.onHiddenGroupsChange as ((value: readonly string[]) => void) | undefined,
+  })
+  const xFormat =
+    (props.xAxis?.formatter as ((v: number) => string) | undefined) ?? defaultFormatter
+  const yFormat =
+    (props.yAxis?.formatter as ((v: number) => string) | undefined) ?? defaultFormatter
+  const sizeFormat = props.sizeFormatter ?? defaultFormatter
+  const groups = useMemo(() => {
+    const order: string[] = []
+    const byGroup = new Map<string, Row[]>()
+    for (const row of data as readonly Row[]) {
+      const key = groupBy ? String(row[groupBy]) : props.title
+      if (!byGroup.has(key)) {
+        byGroup.set(key, [])
+        order.push(key)
+      }
+      byGroup.get(key)!.push(row)
+    }
+    return order.map((key, i) => ({
+      key,
+      rows: byGroup.get(key)!,
+      color: categoryColor(props.colors?.[i], i),
+    }))
+  }, [data, groupBy, props.colors, props.title])
+
+  const columns = [
+    ...(name ? [String(name)] : []),
+    ...(groupBy ? [String(groupBy)] : []),
+    props.xAxis?.label ?? String(x),
+    props.yAxis?.label ?? String(y),
+    ...(size ? [String(size)] : []),
+  ]
+  const table = {
+    columns: name || groupBy ? columns : ['#', ...columns],
+    rows: (data as readonly Row[]).map((row, i) => [
+      ...(name ? [String(row[name])] : []),
+      ...(groupBy ? [String(row[groupBy])] : []),
+      ...(name || groupBy ? [] : [i + 1]),
+      xFormat(Number(row[x])),
+      yFormat(Number(row[y])),
+      ...(size ? [sizeFormat(Number(row[size]))] : []),
+    ]),
+  }
+  const legend =
+    (props.showLegend ?? groups.length > 1)
+      ? groups.map((group) => ({
+          key: group.key,
+          label: group.key,
+          color: group.color,
+          hidden: hidden.includes(group.key),
+        }))
+      : undefined
+  const cartesian = props as unknown as CartesianChartProps<T>
+
+  const content = ({ active, payload }: ScatterTooltipProps) => {
+    const row = payload?.[0]?.payload
+    if (!active || !row) return null
+    const lines: [string, string][] = [
+      [props.xAxis?.label ?? String(x), xFormat(Number(row[x]))],
+      [props.yAxis?.label ?? String(y), yFormat(Number(row[y]))],
+      ...(size ? [[String(size), sizeFormat(Number(row[size]))] as [string, string]] : []),
+    ]
+    return (
+      <div data-slot="chart-tooltip" className={s.tooltip({ class: slots.tooltip })}>
+        {(name || groupBy) && (
+          <p className={s.tooltipLabel({ class: slots.tooltipLabel })}>
+            {String(row[name ?? groupBy!])}
+          </p>
+        )}
+        {lines.map(([label, value]) => (
+          <div key={label} className={s.tooltipRow({ class: slots.tooltipRow })}>
+            <span className={s.tooltipName({ class: slots.tooltipName })}>{label}</span>
+            <span className={s.tooltipValue({ class: slots.tooltipValue })}>{value}</span>
+          </div>
+        ))}
+      </div>
+    )
+  }
+
+  return (
+    <ChartFrame
+      title={props.title}
+      description={props.description}
+      hideTitle={props.hideTitle}
+      className={props.className}
+      legend={legend}
+      onLegendToggle={
+        groups.length > 1 ? (key) => setHidden(toggleIn(hidden, key, groups.length)) : undefined
+      }
+      table={table}
+      height={height}
+      isEmpty={data.length === 0}
+      loading={props.loading}
+      error={props.error}
+      onRetry={props.onRetry}
+      empty={props.empty}
+    >
+      <R.ResponsiveContainer width="100%" height={height}>
+        <R.ScatterChart
+          accessibilityLayer={false}
+          margin={{ top: 8, right: 12, bottom: props.xAxis?.label ? 16 : 0, left: 0 }}
+        >
+          {(props.showGrid ?? true) && (
+            <R.CartesianGrid stroke="var(--glyph-border)" strokeDasharray="3 3" yAxisId="left" />
+          )}
+          <R.XAxis
+            type="number"
+            dataKey={x}
+            name={props.xAxis?.label ?? String(x)}
+            hide={props.xAxis?.hide}
+            tick={axisTick}
+            tickLine={false}
+            axisLine={false}
+            tickMargin={8}
+            tickFormatter={xFormat}
+            domain={(props.xAxis?.domain as [number, number] | undefined) ?? ['auto', 'auto']}
+            {...(props.xAxis?.label && {
+              label: {
+                value: props.xAxis.label,
+                position: 'insideBottom',
+                offset: -12,
+                ...axisTick,
+              },
+            })}
+          />
+          <R.YAxis
+            yAxisId="left"
+            type="number"
+            dataKey={y}
+            name={props.yAxis?.label ?? String(y)}
+            hide={props.yAxis?.hide}
+            tick={axisTick}
+            tickLine={false}
+            axisLine={false}
+            width={props.yAxis?.width ?? axisWidth(data, [y], yFormat, props.yAxis?.label ? 18 : 0)}
+            tickFormatter={yFormat}
+            domain={(props.yAxis?.domain as [number, number] | undefined) ?? ['auto', 'auto']}
+            {...(props.yAxis?.label && {
+              label: { value: props.yAxis.label, angle: -90, position: 'insideLeft', ...axisTick },
+            })}
+          />
+          {size && (
+            <R.ZAxis
+              type="number"
+              dataKey={size}
+              range={(props.sizeRange as [number, number] | undefined) ?? [40, 600]}
+            />
+          )}
+          <R.Tooltip
+            cursor={{ stroke: 'var(--glyph-border-strong)', strokeDasharray: '3 3' }}
+            isAnimationActive={false}
+            content={(p) => content(p as ScatterTooltipProps)}
+          />
+          {overlays({ ...cartesian, brush: false })}
+          {groups.map((group) => (
+            <R.Scatter
+              key={group.key}
+              yAxisId="left"
+              name={group.key}
+              data={group.rows}
+              fill={group.color}
+              fillOpacity={size ? 0.65 : 0.9}
+              stroke="var(--glyph-surface)"
+              strokeWidth={1.5}
+              hide={hidden.includes(group.key)}
+              {...(props.onPointClick && {
+                onClick: (point: { payload?: Row }) => {
+                  if (point.payload) props.onPointClick?.(point.payload as T)
+                },
+                style: { cursor: 'pointer' },
+              })}
+              {...animation}
+            />
+          ))}
+        </R.ScatterChart>
+      </R.ResponsiveContainer>
+    </ChartFrame>
+  )
+}

package/src/patterns/chart/sparkline.tsx

@@ -0,0 +1,111 @@
+import { useId } from 'react'
+import * as R from 'recharts'
+import { type ChartColorValue, resolveColor, useChartAnimation } from './chart-parts'
+
+export interface SparklineProps {
+  values: readonly number[]
+  /** Accessible description, e.g. "Revenue over the last 12 months, rising". */
+  title: string
+  color?: ChartColorValue
+  /** Height in pixels. Default 36. */
+  height?: number
+  /** `area` (default) fills under the line, `line` is just the stroke, `bar` draws columns. */
+  variant?: 'area' | 'line' | 'bar'
+  /** @deprecated Use `variant="line"` for no fill. */
+  area?: boolean
+  /** Mark the highest and lowest points. */
+  showMinMax?: boolean
+  className?: string
+}
+
+/** A tiny trend without axes, for stat cards and table cells. */
+export function Sparkline({
+  values,
+  title,
+  color,
+  height = 36,
+  variant,
+  area,
+  showMinMax = false,
+  className,
+}: SparklineProps) {
+  const id = useId().replace(/:/g, '')
+  const animation = useChartAnimation()
+  const stroke = resolveColor(color, 0)
+  const kind = variant ?? (area === false ? 'line' : 'area')
+  const data = values.map((v, i) => ({ i, v }))
+  const maxIndex = values.indexOf(Math.max(...values))
+  const minIndex = values.indexOf(Math.min(...values))
+  const margin = {
+    top: showMinMax ? 4 : 2,
+    right: showMinMax ? 4 : 2,
+    bottom: showMinMax ? 4 : 2,
+    left: showMinMax ? 4 : 2,
+  }
+
+  const marker = (props: { cx?: number; cy?: number; index?: number }) => {
+    const { cx, cy, index } = props
+    if (!showMinMax || cx === undefined || cy === undefined) return <g key={index} />
+    if (index !== maxIndex && index !== minIndex) return <g key={index} />
+    return (
+      <circle
+        key={index}
+        data-extreme={index === maxIndex ? 'max' : 'min'}
+        cx={cx}
+        cy={cy}
+        r={2.75}
+        fill={index === maxIndex ? stroke : 'var(--glyph-surface)'}
+        stroke={stroke}
+        strokeWidth={1.5}
+      />
+    )
+  }
+
+  return (
+    <div
+      role="img"
+      aria-label={title}
+      data-slot="sparkline"
+      data-variant={kind}
+      className={className}
+      style={{ height }}
+    >
+      <R.ResponsiveContainer width="100%" height="100%">
+        {kind === 'bar' ? (
+          <R.BarChart accessibilityLayer={false} data={data} margin={margin} barCategoryGap="18%">
+            <R.Bar dataKey="v" radius={[2, 2, 0, 0]} {...animation}>
+              {data.map((point) => (
+                <R.Cell
+                  key={point.i}
+                  fill={stroke}
+                  fillOpacity={
+                    showMinMax && (point.i === maxIndex || point.i === minIndex) ? 1 : 0.55
+                  }
+                />
+              ))}
+            </R.Bar>
+          </R.BarChart>
+        ) : (
+          <R.AreaChart accessibilityLayer={false} data={data} margin={margin}>
+            <defs>
+              <linearGradient id={id} x1="0" x2="0" y1="0" y2="1">
+                <stop offset="0%" stopColor={stroke} stopOpacity={kind === 'area' ? 0.25 : 0} />
+                <stop offset="100%" stopColor={stroke} stopOpacity={0} />
+              </linearGradient>
+            </defs>
+            <R.Area
+              dataKey="v"
+              type="monotone"
+              stroke={stroke}
+              strokeWidth={1.75}
+              fill={`url(#${id})`}
+              dot={marker}
+              activeDot={false}
+              {...animation}
+            />
+          </R.AreaChart>
+        )}
+      </R.ResponsiveContainer>
+    </div>
+  )
+}

package/src/patterns/chart/test-utils.tsx

@@ -0,0 +1,35 @@
+import { render } from '@testing-library/react'
+import { cloneElement, type ReactElement, type ReactNode } from 'react'
+import { GlyphProvider } from '../../provider/glyph-provider'
+
+/** Renders with motion off, so recharts draws final shapes immediately. */
+export function renderChart(ui: ReactElement) {
+  const wrapper = ({ children }: { children: ReactNode }) => (
+    <GlyphProvider storageKey={null} motion="none">
+      {children}
+    </GlyphProvider>
+  )
+  return render(ui, { wrapper })
+}
+
+/**
+ * jsdom has no layout, so recharts' ResponsiveContainer would draw nothing. Use as
+ * `vi.mock('recharts', (original) => import('./test-utils').then((m) => m.mockRecharts(original)))`.
+ */
+export async function mockRecharts(importOriginal: () => Promise<unknown>) {
+  const actual = (await importOriginal()) as typeof import('recharts')
+  return {
+    ...actual,
+    ResponsiveContainer: ({
+      children,
+      height,
+    }: {
+      children: ReactElement
+      height?: number | string
+    }) =>
+      cloneElement(children as ReactElement<{ width?: number; height?: number }>, {
+        width: 600,
+        height: typeof height === 'number' ? height : 300,
+      }),
+  }
+}

package/src/patterns/chart/treemap.tsx

@@ -0,0 +1,198 @@
+import type { ReactNode } from 'react'
+import * as R from 'recharts'
+import {
+  type ChartColorValue,
+  ChartFrame,
+  type ChartStateProps,
+  ChartTooltipCard,
+  categoryColor,
+  defaultFormatter,
+  type Key,
+  useChartAnimation,
+} from './chart-parts'
+
+type Row = Record<string, unknown>
+
+export interface TreemapProps<T extends object> extends ChartStateProps {
+  /** One row per rectangle. Rows sharing a `group` are colored and nested together. */
+  data: readonly T[]
+  /** Field naming each rectangle. */
+  category: Key<T>
+  /** Field holding each rectangle's size. */
+  value: Key<T>
+  /** Field grouping rectangles, e.g. a team or product line. Each group gets one color. */
+  group?: Key<T>
+  title: string
+  description?: ReactNode
+  hideTitle?: boolean
+  colors?: readonly ChartColorValue[]
+  valueFormatter?: (value: number) => string
+  /** Plot height in pixels. Default 280. */
+  height?: number
+  showLegend?: boolean
+  className?: string
+}
+
+interface TileNode {
+  name: string
+  size?: number
+  fill: string
+  children?: TileNode[]
+  [field: string]: unknown
+}
+
+interface TileProps {
+  x?: number
+  y?: number
+  width?: number
+  height?: number
+  depth?: number
+  name?: string
+  value?: number
+  fill?: string
+  children?: unknown
+  formatter: (value: number) => string
+}
+
+function Tile({
+  x = 0,
+  y = 0,
+  width = 0,
+  height = 0,
+  depth = 0,
+  name,
+  value,
+  fill,
+  children,
+  formatter,
+}: TileProps) {
+  // Groups are drawn by their children; only leaves are painted.
+  if (Array.isArray(children) && children.length > 0) return null
+  if (depth === 0) return null
+  const roomForName = width > 56 && height > 28
+  const roomForValue = width > 56 && height > 46
+  return (
+    <g>
+      <rect
+        x={x + 1}
+        y={y + 1}
+        width={Math.max(width - 2, 0)}
+        height={Math.max(height - 2, 0)}
+        rx={4}
+        fill={fill}
+        stroke="var(--glyph-surface)"
+        strokeWidth={2}
+      />
+      {roomForName && (
+        <text
+          x={x + 10}
+          y={y + 20}
+          fill="var(--glyph-surface)"
+          fontSize={12}
+          fontWeight={500}
+          style={{ pointerEvents: 'none' }}
+        >
+          {name}
+        </text>
+      )}
+      {roomForValue && value !== undefined && (
+        <text
+          x={x + 10}
+          y={y + 37}
+          fill="var(--glyph-surface)"
+          fillOpacity={0.85}
+          fontSize={11}
+          style={{ pointerEvents: 'none', fontVariantNumeric: 'tabular-nums' }}
+        >
+          {formatter(value)}
+        </text>
+      )}
+    </g>
+  )
+}
+
+/** Sizes of many parts of a whole, nested by group, e.g. spend by team and vendor. */
+export function Treemap<T extends object>(props: TreemapProps<T>) {
+  const { data, category, value, group, valueFormatter = defaultFormatter, height = 280 } = props
+  const animation = useChartAnimation()
+  const rows = data as readonly Row[]
+  const groupNames: string[] = []
+  if (group) {
+    for (const row of rows) {
+      const name = String(row[group])
+      if (!groupNames.includes(name)) groupNames.push(name)
+    }
+  }
+  const tree: TileNode[] = group
+    ? groupNames.map((name, i) => {
+        const fill = categoryColor(props.colors?.[i], i)
+        return {
+          name,
+          fill,
+          children: rows
+            .filter((row) => String(row[group]) === name)
+            .map((row) => ({ name: String(row[category]), size: Number(row[value]) || 0, fill })),
+        }
+      })
+    : rows.map((row, i) => ({
+        name: String(row[category]),
+        size: Number(row[value]) || 0,
+        fill: categoryColor(props.colors?.[i], i),
+      }))
+  const table = {
+    columns: [String(category), ...(group ? [String(group)] : []), String(value)],
+    rows: rows.map((row) => [
+      String(row[category]),
+      ...(group ? [String(row[group])] : []),
+      valueFormatter(Number(row[value])),
+    ]),
+  }
+  const legend =
+    group && (props.showLegend ?? true)
+      ? groupNames.map((name, i) => ({ key: name, label: name, color: tree[i]!.fill }))
+      : undefined
+  return (
+    <ChartFrame
+      title={props.title}
+      description={props.description}
+      hideTitle={props.hideTitle}
+      className={props.className}
+      legend={legend}
+      table={table}
+      height={height}
+      isEmpty={rows.length === 0}
+      loading={props.loading}
+      error={props.error}
+      onRetry={props.onRetry}
+      empty={props.empty}
+    >
+      <R.ResponsiveContainer width="100%" height={height}>
+        <R.Treemap
+          data={tree}
+          dataKey="size"
+          nameKey="name"
+          aspectRatio={4 / 3}
+          content={<Tile formatter={valueFormatter} />}
+          {...animation}
+        >
+          <R.Tooltip
+            isAnimationActive={false}
+            content={(p) => (
+              <ChartTooltipCard
+                active={p.active}
+                payload={(p.payload as never[] | undefined)?.map(
+                  (item: { payload?: Row; value?: unknown }) => ({
+                    name: String(item.payload?.name ?? ''),
+                    value: item.value,
+                    color: String(item.payload?.fill ?? ''),
+                  }),
+                )}
+                formatter={valueFormatter}
+              />
+            )}
+          />
+        </R.Treemap>
+      </R.ResponsiveContainer>
+    </ChartFrame>
+  )
+}

package/src/patterns/chart/use-element-width.ts

@@ -0,0 +1,20 @@
+import { useLayoutEffect, useRef, useState } from 'react'
+
+/**
+ * Measures an element's content width with a ResizeObserver. Until the first measurement
+ * (and in environments without layout, like tests) it reports `fallback`.
+ */
+export function useElementWidth<E extends HTMLElement>(fallback = 480) {
+  const ref = useRef<E>(null)
+  const [width, setWidth] = useState(0)
+  useLayoutEffect(() => {
+    const element = ref.current
+    if (!element) return
+    const measure = () => setWidth(Math.round(element.getBoundingClientRect().width))
+    measure()
+    const observer = new ResizeObserver(measure)
+    observer.observe(element)
+    return () => observer.disconnect()
+  }, [])
+  return [ref, width > 0 ? width : fallback] as const
+}

package/src/patterns/data-table/data-table.tsx

@@ -46,7 +46,7 @@ declare module '@tanstack/react-table' {
   }
 }
 
-export const dataTableStyles = tv({
+export const dataTableStyles = /* @__PURE__ */ tv({
   slots: {
     root: 'flex min-w-0 flex-col',
     toolbar: 'flex flex-wrap items-center gap-2',

package/src/patterns/form/form.tsx

@@ -170,7 +170,7 @@ export function FormSubmit({ form, onClick, ...props }: FormSubmitProps) {
   return <Button type="button" loading={isSubmitting} onClick={submitOutside} {...props} />
 }
 
-export const formErrorStyles = tv({
+export const formErrorStyles = /* @__PURE__ */ tv({
   slots: {
     base: 'flex items-start gap-2 rounded-md border border-danger/30 bg-danger/8 px-3 py-2.5 text-small text-danger-text',
     icon: 'mt-0.5 size-4 shrink-0',

package/src/provider/glyph-context.ts

@@ -1,4 +1,4 @@
-import type { Theme } from '@glyphui/tokens'
+import type { MotionLevel, Theme } from '@glyphui/tokens'
 import {
   createContext,
   type ElementType,
@@ -45,6 +45,8 @@ export interface GlyphContextValue {
   theme: Theme
   linkComponent: LinkComponent
   useIsActive: UseIsActive
+  /** Overrides the theme's motion level for the whole app. */
+  motion?: MotionLevel | undefined
 }
 
 export const GlyphContext = createContext<GlyphContextValue | null>(null)