@glyphui/ui 0.2.0 → 0.4.0

package/src/patterns/chart/chart-parts.tsx

@@ -0,0 +1,179 @@
+import { type ReactNode, useId } from 'react'
+import { useComponentConfig } from '../../hooks/use-component-config'
+import { chartStyles } from './chart.styles'
+
+/** Theme colors a series can use by name. Any CSS color also works. */
+export type ChartColor =
+  | 'chart-1'
+  | 'chart-2'
+  | 'chart-3'
+  | 'chart-4'
+  | 'chart-5'
+  | 'primary'
+  | 'info'
+  | 'success'
+  | 'warning'
+  | 'danger'
+  | 'foreground'
+  | 'muted-foreground'
+
+/** Series without a color use the theme's chart palette, in order. */
+const palette: ChartColor[] = ['chart-1', 'chart-2', 'chart-3', 'chart-4', 'chart-5']
+
+export function resolveColor(color: string | undefined, index: number): string {
+  const value = color ?? palette[index % palette.length]!
+  return /^[a-z][a-z\d-]*$/.test(value) ? `var(--color-${value})` : value
+}
+
+export const defaultFormatter = (value: number) =>
+  typeof value === 'number' ? value.toLocaleString() : String(value)
+
+export function useChartParts() {
+  const [, slots] = useComponentConfig('Chart', {})
+  return { s: chartStyles(), slots }
+}
+
+export interface LegendEntry {
+  label: ReactNode
+  color: string
+}
+
+export function ChartLegend({ items }: { items: LegendEntry[] }) {
+  const { s, slots } = useChartParts()
+  return (
+    <ul data-slot="chart-legend" className={s.legend({ class: slots.legend })} aria-hidden="true">
+      {items.map((item, i) => (
+        <li key={i} className={s.legendItem({ class: slots.legendItem })}>
+          <span className={s.swatch({ class: slots.swatch })} style={{ background: item.color }} />
+          {item.label}
+        </li>
+      ))}
+    </ul>
+  )
+}
+
+interface TooltipPayloadItem {
+  name?: string | number
+  value?: unknown
+  color?: string
+  dataKey?: unknown
+  payload?: Record<string, unknown> & { fill?: string }
+}
+
+export function ChartTooltipCard({
+  active,
+  payload,
+  label,
+  formatter,
+  labelFormatter,
+}: {
+  active?: boolean
+  payload?: readonly TooltipPayloadItem[]
+  label?: ReactNode
+  formatter: (value: number) => string
+  labelFormatter?: ((label: ReactNode) => ReactNode) | undefined
+}) {
+  const { s, slots } = useChartParts()
+  if (!active || !payload?.length) return null
+  return (
+    <div data-slot="chart-tooltip" className={s.tooltip({ class: slots.tooltip })}>
+      {label !== undefined && label !== '' && (
+        <p className={s.tooltipLabel({ class: slots.tooltipLabel })}>
+          {labelFormatter ? labelFormatter(label) : label}
+        </p>
+      )}
+      {payload.map((item, i) => (
+        <div key={i} className={s.tooltipRow({ class: slots.tooltipRow })}>
+          <span
+            className={s.swatch({ class: slots.swatch })}
+            style={{ background: item.color ?? item.payload?.fill }}
+          />
+          <span className={s.tooltipName({ class: slots.tooltipName })}>
+            {String(item.name ?? '')}
+          </span>
+          <span className={s.tooltipValue({ class: slots.tooltipValue })}>
+            {formatter(Number(item.value))}
+          </span>
+        </div>
+      ))}
+    </div>
+  )
+}
+
+export interface ChartFrameProps {
+  /** Accessible name of the chart. Shown above it unless `hideTitle` is set. */
+  title: string
+  description?: ReactNode
+  hideTitle?: boolean
+  className?: string
+  legend?: LegendEntry[] | undefined
+  /** Columns and rows for the screen-reader table that mirrors the chart. */
+  table: { columns: string[]; rows: (string | number)[][] }
+  children: ReactNode
+}
+
+/**
+ * Wraps every chart in a `<figure>` with a caption and a visually hidden data table,
+ * so screen-reader users get the numbers the chart shows.
+ */
+export function ChartFrame({
+  title,
+  description,
+  hideTitle,
+  className,
+  legend,
+  table,
+  children,
+}: ChartFrameProps) {
+  const { s, slots } = useChartParts()
+  const titleId = useId()
+  return (
+    <figure
+      data-slot="chart"
+      aria-labelledby={titleId}
+      className={s.root({ class: [slots.root, className] })}
+    >
+      <figcaption className={hideTitle ? s.srOnly() : s.caption({ class: slots.caption })}>
+        <span id={titleId} className={s.title({ class: slots.title })}>
+          {title}
+        </span>
+        {description && (
+          <span className={s.description({ class: slots.description })}>{description}</span>
+        )}
+      </figcaption>
+      {/* Screen readers get the data table below. Charts pass `accessibilityLayer={false}`
+          so recharts adds no focusable nodes inside this hidden plot. */}
+      <div className={s.plot({ class: slots.plot })} aria-hidden="true">
+        {children}
+      </div>
+      {legend && legend.length > 1 && <ChartLegend items={legend} />}
+      <table className={s.srOnly()}>
+        <caption>{title}</caption>
+        <thead>
+          <tr>
+            {table.columns.map((column) => (
+              <th key={column} scope="col">
+                {column}
+              </th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          {table.rows.map((row, i) => (
+            <tr key={i}>
+              {row.map((cell, j) =>
+                j === 0 ? (
+                  <th key={j} scope="row">
+                    {cell}
+                  </th>
+                ) : (
+                  <td key={j}>{cell}</td>
+                ),
+              )}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </figure>
+  )
+}

package/src/patterns/chart/chart.styles.ts

@@ -0,0 +1,35 @@
+import type { StylesEntry } from '../../utils/registry'
+import { themedBorder } from '../../utils/styles'
+import { tv, type VariantProps } from '../../utils/tv'
+
+export const chartStyles = tv({
+  slots: {
+    root: 'm-0 grid min-w-0 gap-3',
+    caption: 'grid gap-0.5',
+    title: 'text-small font-medium text-foreground',
+    description: 'text-caption text-muted-foreground',
+    plot: 'min-w-0 [&_.recharts-surface]:overflow-visible [&_.recharts-text]:fill-muted-foreground',
+    legend: 'flex flex-wrap items-center gap-x-4 gap-y-1 text-caption text-muted-foreground',
+    legendItem: 'inline-flex items-center gap-1.5',
+    swatch: 'size-2.5 shrink-0 rounded-[2px]',
+    tooltip: [
+      'grid min-w-36 gap-1.5 rounded-md border-border bg-raised px-3 py-2 text-caption text-foreground shadow-lg',
+      themedBorder,
+    ],
+    tooltipLabel: 'font-medium text-foreground',
+    tooltipRow: 'flex items-center gap-2',
+    tooltipName: 'flex-1 text-muted-foreground',
+    tooltipValue: 'font-mono font-medium tabular-nums text-foreground',
+    center:
+      'pointer-events-none absolute inset-0 flex flex-col items-center justify-center text-center',
+    srOnly: 'sr-only',
+  },
+})
+
+export type ChartVariants = VariantProps<typeof chartStyles>
+
+declare module '@glyphui/tokens' {
+  interface GlyphComponentRegistry {
+    Chart: StylesEntry<typeof chartStyles>
+  }
+}

package/src/patterns/chart/chart.tsx

@@ -0,0 +1,386 @@
+import { type ReactNode, useId } from 'react'
+import * as R from 'recharts'
+import {
+  type ChartColor,
+  ChartFrame,
+  ChartTooltipCard,
+  defaultFormatter,
+  resolveColor,
+  useChartParts,
+} from './chart-parts'
+
+export type { ChartColor }
+
+type Key<T> = Extract<keyof T, string>
+
+export interface ChartSeries<T> {
+  /** Field of each data row holding this series' value. */
+  key: Key<T>
+  /** Name shown in the legend, tooltip and accessible table. Defaults to `key`. */
+  label?: string
+  /** A theme color name (`primary`, `info`, ...) or any CSS color. Defaults follow the theme palette. */
+  color?: ChartColor | (string & {})
+}
+
+export interface CartesianChartProps<T extends object> {
+  data: readonly T[]
+  /** Field used for the x axis, e.g. `"month"`. */
+  index: Key<T>
+  series: readonly ChartSeries<T>[]
+  /** Accessible name; also shown as the caption unless `hideTitle` is set. */
+  title: string
+  description?: ReactNode
+  hideTitle?: boolean
+  /** Formats values on the y axis, in tooltips and in the accessible table. */
+  valueFormatter?: (value: number) => string
+  /** Plot height in pixels. Default 240. */
+  height?: number
+  showGrid?: boolean
+  /** Defaults to true when there is more than one series. */
+  showLegend?: boolean
+  showYAxis?: boolean
+  className?: string
+}
+
+const axisTick = { fill: 'var(--color-muted-foreground)', fontSize: 12 }
+
+function useCartesian<T extends object>(props: CartesianChartProps<T>) {
+  const { data, index, series, title, valueFormatter = defaultFormatter } = props
+  const resolved = series.map((item, i) => ({
+    ...item,
+    label: item.label ?? item.key,
+    stroke: resolveColor(item.color, i),
+  }))
+  const table = {
+    columns: [String(index), ...resolved.map((item) => item.label)],
+    rows: data.map((row) => [
+      String((row as Record<string, unknown>)[index]),
+      ...resolved.map((item) => valueFormatter(Number((row as Record<string, unknown>)[item.key]))),
+    ]),
+  }
+  const legend =
+    (props.showLegend ?? series.length > 1)
+      ? resolved.map((item) => ({ label: item.label, color: item.stroke }))
+      : undefined
+  return { resolved, table, legend, valueFormatter, title }
+}
+
+function frameProps<T extends object>(props: CartesianChartProps<T>) {
+  return {
+    title: props.title,
+    description: props.description,
+    hideTitle: props.hideTitle,
+    className: props.className,
+  }
+}
+
+function Axes({
+  index,
+  showGrid = true,
+  showYAxis = true,
+  valueFormatter,
+}: {
+  index: string
+  showGrid?: boolean | undefined
+  showYAxis?: boolean | undefined
+  valueFormatter: (value: number) => string
+}) {
+  return (
+    <>
+      {showGrid && (
+        <R.CartesianGrid vertical={false} stroke="var(--color-border)" strokeDasharray="3 3" />
+      )}
+      <R.XAxis
+        dataKey={index}
+        tick={axisTick}
+        tickLine={false}
+        axisLine={false}
+        tickMargin={8}
+        minTickGap={16}
+      />
+      {showYAxis && (
+        <R.YAxis
+          tick={axisTick}
+          tickLine={false}
+          axisLine={false}
+          width={48}
+          tickFormatter={valueFormatter}
+        />
+      )}
+    </>
+  )
+}
+
+function tooltip(valueFormatter: (value: number) => string, cursor: object | boolean) {
+  return (
+    <R.Tooltip
+      cursor={cursor}
+      content={(p) => (
+        <ChartTooltipCard
+          active={p.active}
+          payload={p.payload as never}
+          label={p.label as ReactNode}
+          formatter={valueFormatter}
+        />
+      )}
+    />
+  )
+}
+
+/** Trends over time, one line per series. */
+export function LineChart<T extends object>(
+  props: CartesianChartProps<T> & { curve?: 'monotone' | 'linear' },
+) {
+  const { resolved, table, legend, valueFormatter } = useCartesian(props)
+  return (
+    <ChartFrame {...frameProps(props)} legend={legend} table={table}>
+      <R.ResponsiveContainer width="100%" height={props.height ?? 240}>
+        <R.LineChart
+          accessibilityLayer={false}
+          data={props.data as T[]}
+          margin={{ top: 8, right: 8, bottom: 0, left: 0 }}
+        >
+          <Axes
+            index={props.index}
+            showGrid={props.showGrid}
+            showYAxis={props.showYAxis}
+            valueFormatter={valueFormatter}
+          />
+          {tooltip(valueFormatter, { stroke: 'var(--color-border-strong)' })}
+          {resolved.map((item) => (
+            <R.Line
+              key={item.key}
+              dataKey={item.key}
+              name={item.label}
+              type={props.curve ?? 'monotone'}
+              stroke={item.stroke}
+              strokeWidth={2}
+              dot={false}
+              activeDot={{ r: 4, strokeWidth: 0 }}
+              isAnimationActive={false}
+            />
+          ))}
+        </R.LineChart>
+      </R.ResponsiveContainer>
+    </ChartFrame>
+  )
+}
+
+/** Trends with filled areas. `stacked` shows how series add up to a total. */
+export function AreaChart<T extends object>(props: CartesianChartProps<T> & { stacked?: boolean }) {
+  const { resolved, table, legend, valueFormatter } = useCartesian(props)
+  const id = useId().replace(/:/g, '')
+  return (
+    <ChartFrame {...frameProps(props)} legend={legend} table={table}>
+      <R.ResponsiveContainer width="100%" height={props.height ?? 240}>
+        <R.AreaChart
+          accessibilityLayer={false}
+          data={props.data as T[]}
+          margin={{ top: 8, right: 8, bottom: 0, left: 0 }}
+        >
+          <defs>
+            {resolved.map((item, i) => (
+              <linearGradient key={item.key} id={`${id}-${i}`} x1="0" x2="0" y1="0" y2="1">
+                <stop offset="0%" stopColor={item.stroke} stopOpacity={0.3} />
+                <stop offset="100%" stopColor={item.stroke} stopOpacity={0} />
+              </linearGradient>
+            ))}
+          </defs>
+          <Axes
+            index={props.index}
+            showGrid={props.showGrid}
+            showYAxis={props.showYAxis}
+            valueFormatter={valueFormatter}
+          />
+          {tooltip(valueFormatter, { stroke: 'var(--color-border-strong)' })}
+          {resolved.map((item, i) => (
+            <R.Area
+              key={item.key}
+              dataKey={item.key}
+              name={item.label}
+              type="monotone"
+              stroke={item.stroke}
+              strokeWidth={2}
+              fill={`url(#${id}-${i})`}
+              {...(props.stacked && { stackId: 'stack' })}
+              isAnimationActive={false}
+            />
+          ))}
+        </R.AreaChart>
+      </R.ResponsiveContainer>
+    </ChartFrame>
+  )
+}
+
+/** Compare values across categories. `stacked` puts series on top of each other. */
+export function BarChart<T extends object>(
+  props: CartesianChartProps<T> & {
+    stacked?: boolean /** Corner radius of bar tops. Default 3. */
+    barRadius?: number
+  },
+) {
+  const { resolved, table, legend, valueFormatter } = useCartesian(props)
+  const radius = props.barRadius ?? 3
+  return (
+    <ChartFrame {...frameProps(props)} legend={legend} table={table}>
+      <R.ResponsiveContainer width="100%" height={props.height ?? 240}>
+        <R.BarChart
+          accessibilityLayer={false}
+          data={props.data as T[]}
+          margin={{ top: 8, right: 8, bottom: 0, left: 0 }}
+        >
+          <Axes
+            index={props.index}
+            showGrid={props.showGrid}
+            showYAxis={props.showYAxis}
+            valueFormatter={valueFormatter}
+          />
+          {tooltip(valueFormatter, { fill: 'var(--color-muted)', opacity: 0.6 })}
+          {resolved.map((item, i) => (
+            <R.Bar
+              key={item.key}
+              dataKey={item.key}
+              name={item.label}
+              fill={item.stroke}
+              radius={props.stacked && i < resolved.length - 1 ? 0 : [radius, radius, 0, 0]}
+              {...(props.stacked && { stackId: 'stack' })}
+              isAnimationActive={false}
+            />
+          ))}
+        </R.BarChart>
+      </R.ResponsiveContainer>
+    </ChartFrame>
+  )
+}
+
+export interface DonutChartProps<T extends object> {
+  data: readonly T[]
+  /** Field naming each slice. */
+  category: Key<T>
+  /** Field holding each slice's value. */
+  value: Key<T>
+  title: string
+  description?: ReactNode
+  hideTitle?: boolean
+  /** One color per slice, in order. Defaults follow the theme palette. */
+  colors?: readonly (ChartColor | (string & {}))[]
+  /** Content in the hole, e.g. the total. */
+  centerLabel?: ReactNode
+  valueFormatter?: (value: number) => string
+  /** Diameter in pixels. Default 200. */
+  size?: number
+  showLegend?: boolean
+  className?: string
+}
+
+/** Parts of a whole. Best with five or fewer slices. */
+export function DonutChart<T extends object>(props: DonutChartProps<T>) {
+  const { data, category, value, valueFormatter = defaultFormatter, size = 200 } = props
+  const { s, slots } = useChartParts()
+  const rows = data.map((row) => row as Record<string, unknown>)
+  const colors = rows.map((_, i) => resolveColor(props.colors?.[i], i))
+  const table = {
+    columns: [String(category), String(value)],
+    rows: rows.map((row) => [String(row[category]), valueFormatter(Number(row[value]))]),
+  }
+  const legend =
+    (props.showLegend ?? true)
+      ? rows.map((row, i) => ({ label: String(row[category]), color: colors[i]! }))
+      : undefined
+  return (
+    <ChartFrame
+      title={props.title}
+      description={props.description}
+      hideTitle={props.hideTitle}
+      className={props.className}
+      legend={legend}
+      table={table}
+    >
+      <div className="relative mx-auto" style={{ width: size, height: size }}>
+        <R.ResponsiveContainer width="100%" height="100%">
+          <R.PieChart accessibilityLayer={false}>
+            {tooltip(valueFormatter, false)}
+            <R.Pie
+              rootTabIndex={-1}
+              data={rows}
+              dataKey={value}
+              nameKey={category}
+              innerRadius="68%"
+              outerRadius="100%"
+              paddingAngle={2}
+              stroke="var(--color-surface)"
+              strokeWidth={2}
+              isAnimationActive={false}
+            >
+              {rows.map((_, i) => (
+                <R.Cell key={i} fill={colors[i]} />
+              ))}
+            </R.Pie>
+          </R.PieChart>
+        </R.ResponsiveContainer>
+        {props.centerLabel && (
+          <div className={s.center({ class: slots.center })}>{props.centerLabel}</div>
+        )}
+      </div>
+    </ChartFrame>
+  )
+}
+
+export interface SparklineProps {
+  values: readonly number[]
+  /** Accessible description, e.g. "Revenue over the last 12 months, rising". */
+  title: string
+  color?: ChartColor | (string & {})
+  /** Height in pixels. Default 36. */
+  height?: number
+  /** Fill the area under the line. */
+  area?: boolean
+  className?: string
+}
+
+/** A tiny trend line without axes, for stat cards and table cells. */
+export function Sparkline({
+  values,
+  title,
+  color,
+  height = 36,
+  area = true,
+  className,
+}: SparklineProps) {
+  const id = useId().replace(/:/g, '')
+  const stroke = resolveColor(color, 0)
+  const data = values.map((v, i) => ({ i, v }))
+  return (
+    <div
+      role="img"
+      aria-label={title}
+      data-slot="sparkline"
+      className={className}
+      style={{ height }}
+    >
+      <R.ResponsiveContainer width="100%" height="100%">
+        <R.AreaChart
+          accessibilityLayer={false}
+          data={data}
+          margin={{ top: 2, right: 2, bottom: 2, left: 2 }}
+        >
+          <defs>
+            <linearGradient id={id} x1="0" x2="0" y1="0" y2="1">
+              <stop offset="0%" stopColor={stroke} stopOpacity={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})`}
+            isAnimationActive={false}
+            dot={false}
+          />
+        </R.AreaChart>
+      </R.ResponsiveContainer>
+    </div>
+  )
+}

package/src/patterns/chart/index.ts

@@ -0,0 +1,13 @@
+export {
+  AreaChart,
+  BarChart,
+  type CartesianChartProps,
+  type ChartColor,
+  type ChartSeries,
+  DonutChart,
+  type DonutChartProps,
+  LineChart,
+  Sparkline,
+  type SparklineProps,
+} from './chart'
+export { type ChartVariants, chartStyles } from './chart.styles'