// ~/src/siteplane/components/radial-bar-chart/radial-bar-chart.tsx "use client"; import * as React from "react"; import { useFormatLocale, useSiteplaneMessages, } from "../../system/locale/messages-context"; import { cn } from "../../system/utils/cn"; import { slotClass } from "../../system/utils/slot-class"; import { ChartEmptyState } from "../chart/chart-cartesian"; import { CHART_DEFAULT_LOCALE, chartFigureFormatter, chartLabels, chartNumberFormatter, } from "../chart/chart-format"; import { useChartInteraction } from "../chart/chart-interaction"; import { ChartLegend } from "../chart/chart-legend"; import { chartEmptyColor, chartPaletteColors } from "../chart/chart-palette"; import { chartCirclePath, ringCenterFit } from "../chart/chart-ring"; import { ChartTooltip, chartTooltipText } from "../chart/chart-tooltip"; import type { ChartLabels, ChartPalette } from "../chart/chart-types"; import { MotionNumber, useTweenedRows } from "../motion"; import { RADIAL_BAR_CHART_SIZES, RADIAL_LARGE_CAPTION_HOLE, barAnchor, barDash, radialCenterLine, radialCenterSteps, radialLayout, radialShare, ringAtPoint, type RadialBarChartSize, type RadialCenterStep, } from "./radial-geometry"; export type { RadialBarChartSize } from "./radial-geometry"; export type RadialBarChartDatum = { id: string; label: string; /** The value of the bar, drawn as its share of the chart's `max`. */ value: number; /** A CSS colour or token. The chart's `palette` gives one for its place when omitted. */ color?: string; }; export type RadialBarChartProps = { /** * The bars, one ring each, from the outer ring inwards: the first bar is the * outer ring and takes the first colour of the palette. */ data: readonly RadialBarChartDatum[]; /** The accessible name of the chart. */ label: string; /** * The id of an element that describes the chart, read after what the chart * gives assistive technology itself. */ "aria-describedby"?: string; /** * The value of a full ring: every bar is drawn as its share of it, from 12 * o'clock clockwise. A value beyond it fills the ring, and one below 0 leaves * it empty; the tooltip names the value itself. 100 by default. */ max?: number; /** * The diameter of the outer ring, a size name (`xs` 176 px, `sm` 220 px, `md` * 264 px, `lg` 308 px) or a number of px. The default is `sm`. */ size?: number | RadialBarChartSize; /** * `brand` (the default) shades the brand colour from strong to light, spread * over the number of bars (up to eight), the outer ring strongest; * `categorical` gives each bar its own chart colour, `--chart-1` to * `--chart-8` in order. Both start over from the ninth bar. A bar that names * its `color` keeps it. */ palette?: ChartPalette; /** Writes a value in the tooltip and in what screen readers read for each bar. A number in the format of `locale` by default. */ formatValue?: (value: number) => string; /** The locale of the numbers: the SiteplaneLocaleProvider's unless set, en-US without one. */ locale?: string; /** Shown in the hole when there is no bar to draw. */ emptyLabel?: string; /** * Replaces words that the chart gives screen readers, merged with the * English defaults: its role description and the keyboard hint. */ labels?: Partial | undefined; /** * Content of your own in the hole, in place of `centerValue` and * `centerLabel`. It is laid out in the square around the hole and cut off at * the hole's edge, so it never covers a ring. It lies over the chart without * taking the pointer and is not part of the chart's accessible name. */ center?: React.ReactNode; /** * A figure in the hole, such as a share or a total, which the chart fits into * the hole: in the largest text step the hole offers, from 48 px for a hole * of 240 px down to 20 px for one of 96 px, or a smaller step it fits in, and * in compact notation, such as 1.2M, when it does not fit in full. Screen * readers read it in full. It rolls to a new value. */ centerValue?: number; /** A caption above `centerValue`, such as Active users: one line of muted text, 14 px in a hole of 150 px or more and 12 px in a smaller one, that ends in an ellipsis when the hole is too narrow for it. */ centerLabel?: string; /** How `centerValue` is written, as Intl.NumberFormat options in `locale`, such as a percentage. The chart adds compact notation when the figure needs it. */ centerFormat?: Intl.NumberFormatOptions; /** * Lists the bars below the rings, each with its colour. On when there is more * than one bar. Without it screen readers still read each bar and its value, * as the description of the chart. */ legend?: boolean; /** * Rolls the value in the tooltip to the next bar's, digit by digit * (MotionNumber), as the other charts' `rollingNumbers` does. Off by * default: it changes at once. `centerValue` rolls either way. */ rollingNumbers?: boolean; className?: string; }; // The text classes of the steps of a figure in the hole, written whole for // Tailwind: the size of each step on the height of its line. const figureStepClassName: Record = { 12: "text-xs leading-4.5", 14: "text-sm leading-5", 16: "text-base leading-6", 20: "text-xl leading-7.5", 24: "text-2xl leading-8", 30: "text-3xl leading-9.5", 36: "text-4xl leading-11", 48: "text-5xl leading-15", }; // The figure keeps all its digits in the three largest steps its hole offers; // below them it is written compact first, as in the Pie Chart. const fullSteps = 3; /** * A figure in the hole, with an optional caption above it: in the largest step * the hole offers that it fits in, in full or in compact notation, which the * chart picks from its size and the text alone (`ringCenterFit`), so that the * server and the client agree. A compact figure is read in full. The caption * stays on one line and ends in an ellipsis where the hole narrows (rulebook * K5). */ function RadialCenterFigure({ caption, format, holeRadius, locale, value, }: { caption: string | undefined; format: Intl.NumberFormatOptions | undefined; holeRadius: number; locale: string; value: number; }): React.ReactElement { const full = chartFigureFormatter(locale, format)(value); const short = chartFigureFormatter(locale, format, true)(value); const largeCaption = holeRadius * 2 >= RADIAL_LARGE_CAPTION_HOLE; const fit = ringCenterFit({ caption, captionHeight: largeCaption ? 20 : 18, compact: short, figureHeight: radialCenterLine, full, fullSteps, holeRadius, steps: radialCenterSteps(holeRadius * 2), }); const text = fit.compact ? short : full; return ( <> {caption ? ( {caption} ) : null} {text === full ? ( ) : ( <> {full} ); } // A bar as the chart keeps it: its own value and the colour it keeps even // while it shrinks away after it has left the data. type RadialRow = RadialBarChartDatum & { color: string }; /** * Bars that each fill a ring of their own by their share of `max`, from 12 * o'clock clockwise, concentric from the outer ring inwards over a neutral * track, with round ends: one bar for a progress circle, several for an * activity gauge. The hole takes a figure with a caption above it, a legend * below lists the bars, and a tooltip trails beside the bar under the pointer; * the chart is one focus stop whose arrow keys step from ring to ring. No bar * fades while another is active: the bars are shades of one hue. New data * glides in: a bar is told by its id, grows from nothing, glides to a new value * and shrinks away in its ring when it leaves. */ export function RadialBarChart({ data, label, "aria-describedby": describedBy, max = 100, size: sizeProp = "sm", palette = "brand", formatValue: givenFormat, locale: localeProp, emptyLabel: emptyLabelProp, labels, center, centerValue, centerLabel, centerFormat, legend = data.length > 1, rollingNumbers = false, className, }: RadialBarChartProps): React.ReactElement { const messages = useSiteplaneMessages("chart"); const emptyLabel = emptyLabelProp ?? messages.noData; // The chart's own locale, else the provider's, else en-US. const locale = useFormatLocale(localeProp, CHART_DEFAULT_LOCALE); const chart = React.useRef(null); const size = Math.max( 0, typeof sizeProp === "number" ? sizeProp : RADIAL_BAR_CHART_SIZES[sizeProp], ); const words = chartLabels(labels, messages); // Numbers as the other charts write them: in the format of the locale. const formatValue = givenFormat ?? chartNumberFormatter(locale); const full = Number.isFinite(max) && max > 0 ? max : 100; const colors = chartPaletteColors(palette, data.length); const rows: RadialRow[] = data.map((item, index) => ({ ...item, color: item.color ?? colors[index]!, value: Number.isFinite(item.value) ? item.value : 0, })); // The bars as they are drawn now, as shares of a full ring: when the data // changes each bar glides to its new share, a new bar grows from nothing and // a bar that is gone shrinks away in its ring before the rings close up. At // rest this is the data itself. const bars = useTweenedRows(rows, (row) => radialShare(row.value, full), { container: chart, }); const empty = rows.length === 0; // Every bar has a ring while it is drawn, one that is leaving included; a // chart with no bars keeps one empty ring. const layout = radialLayout(size, Math.max(1, bars.length)); const middle = size / 2; // The bar under a point, from its distance to the centre. One lookup for the // whole chart keeps the active bar steady while the pointer crosses from one // ring to the next. const barAt = (clientX: number, clientY: number): string | null => { const box = chart.current?.getBoundingClientRect(); if (!box || !box.width || empty) return null; const scale = size / box.width; const ring = ringAtPoint( layout, (clientX - box.x - box.width / 2) * scale, (clientY - box.y - box.height / 2) * scale, ); const bar = bars[ring]; return bar && !bar.leaving ? bar.key : null; }; // The chart core keeps the active bar, the pointer, the tap that pins, the // arrow keys and the tooltip; the rings only say which bar is under a point. const interaction = useChartInteraction({ itemAt: barAt, keys: rows.map((row) => row.id), }); const selected = interaction.activeKey === null ? undefined : rows.find((row) => row.id === interaction.activeKey); // The card sits beside the middle of the bar, on its ring. const anchorFor = (key: string) => { const index = bars.findIndex((bar) => bar.key === key); const ring = layout.rings[index]; const box = chart.current?.getBoundingClientRect(); if (index < 0 || !ring || !box) return null; const point = barAnchor(bars[index]!.value, ring, size); return { x: box.x + box.width * point.x, y: box.y + box.height * point.y, }; }; // What the chart says about its bars to assistive technology when it takes // focus: its empty label when there is none, and without a legend each bar // and its value, which the legend reads out otherwise. const showLegend = legend && !empty; const description = empty ? emptyLabel : showLegend ? undefined : // A full stop ends it, so that the keyboard hint after it is heard // as a sentence of its own. `${rows.map((row) => `${row.label}: ${formatValue(row.value)}`).join("; ")}.`; const hasFigure = centerValue !== undefined && Number.isFinite(centerValue); // The hole, as a share of the box from each edge: the square around it. const holeInset = size > 0 ? (0.5 - layout.holeRadius / size) * 100 : 50; return ( // The figure holds the rings and the legend. The focus stop inside is the // chart for assistive technology, named by the label alone.
{rollingNumbers ? ( ) : ( formatValue(selected.value) )}
{selected.label}
) } describedBy={describedBy} description={description} interaction={interaction} keyboardHint={words.keyboardHint} label={label} roleDescription={words.roleDescription} style={{ height: size, width: size }} > {/* The rings are a picture that the focus stop describes, so they are hidden from assistive technology. No SVG titles: the browser would show its own tooltip next to the chart's. Each ring is first its track, the whole circle in the neutral of an empty share, and then its bar over it. */} {/* The empty label is the charts' own empty state, in HTML over the rings, so that it keeps its 14 px at any size of the chart. */} {empty && } {/* The centre is HTML over the rings, in the square around the hole, cut off at its round edge, so that nothing in it covers a ring. It sits inside the focus stop, whose name is the label alone, and never takes the pointer, so the lookup sees every point. */} {!empty && (center != null || hasFigure) && (
{center ?? ( )}
)}
{showLegend && ( ({ color: row.color, key: row.id, label: row.label, value: formatValue(row.value), }))} layout="row" /> )}
); } // ~/src/siteplane/components/radial-bar-chart/radial-geometry.ts /* * The geometry of the Radial Bar Chart: concentric rings, one bar on each, drawn * in a box as many px across as the chart. A bar fills its ring from 12 o'clock * clockwise by its share of the chart's `max`, and its round ends stay inside * that share, so a bar of 40 % covers 40 % of the circle. The rings, the * pointer, the tooltip and the figure in the hole all read the same layout. */ /** * The named sizes of the chart, by the diameter of its outer ring: 176, 220, * 264 and 308 px, a lone ring of 80, 100, 120 and 140 px radius at its centre * line with a 16 to 28 px bar. */ export type RadialBarChartSize = "xs" | "sm" | "md" | "lg"; export const RADIAL_BAR_CHART_SIZES: Readonly< Record > = { xs: 176, sm: 220, md: 264, lg: 308, }; /** One ring of the chart: the radius of its centre line and its thickness, in px. */ export type RadialRing = { radius: number; width: number }; /** Where the rings of a chart sit, from the outer ring inwards. */ export type RadialLayout = { /** The side of the box, in px: the diameter of the outer ring. */ size: number; rings: RadialRing[]; /** The space between two rings, in px. */ gap: number; /** The radius of the hole inside the inner ring, in px. */ holeRadius: number; }; /** * The rings of a chart `size` px across with `count` bars, from the outer ring * inwards. A lone ring is an eleventh of the size thick, 16, 20, 24 and 28 px * at `xs` to `lg`; each further ring thins them all, to a seventeenth of the * size for three (10, 13, 16 and 18 px), so that the hole keeps room for its * figure. Rings stand a quarter of their thickness apart. Both are whole px, * at least 1 px, so every ring paints as thick as the others. */ export function radialLayout(size: number, count: number): RadialLayout { const box = Math.max(0, size); const rings = Math.max(1, Math.floor(count)); const width = Math.max(1, Math.round(box / (11 + 3 * (rings - 1)))); const gap = Math.max(1, Math.round(width / 4)); const outer = box / 2; return { gap, holeRadius: Math.max(0, outer - rings * width - (rings - 1) * gap), rings: Array.from({ length: rings }, (_, index) => ({ radius: outer - index * (width + gap) - width / 2, width, })), size: box, }; } /** * The ring under a point, by its distance from the centre: the ring and half the * gap on either side of it, so that the pointer finds a ring between two rings. * The point is an offset from the centre in px of the box. -1 for none: in the * hole or outside the chart. */ export function ringAtPoint( layout: RadialLayout, dx: number, dy: number, ): number { const distance = Math.hypot(dx, dy); return layout.rings.findIndex( (ring) => Math.abs(distance - ring.radius) <= ring.width / 2 + layout.gap / 2, ); } /** A share of a ring, 0 to 1, from a value and the value of a full ring: a value beyond either end is held to it. */ export function radialShare(value: number, max: number): number { if (!Number.isFinite(value) || !(max > 0)) return 0; return Math.min(1, Math.max(0, value / max)); } // The smallest dash drawn, in percent of the circle: a bar too short for its // round ends is a dot, which a browser draws for a dash of some length only. const dotDash = 0.001; /** * The dash of a bar along its ring's circle (drawn with `pathLength` 100 and * round ends): where it starts and how long it is, in percent of the circle. * The round ends reach half the ring's thickness beyond the dash, so the dash * is shortened by them and starts half of one in, and the bar covers its share * exactly; a bar shorter than its two ends is a dot in the middle of its share. * Null for a bar with nothing in it. */ export function barDash( share: number, ring: RadialRing, ): { dasharray: string; dashoffset: number } | null { const percent = Math.min(1, Math.max(0, share)) * 100; if (!(percent > 0) || !(ring.radius > 0)) return null; const ends = (ring.width / (2 * Math.PI * ring.radius)) * 100; const length = Math.max(dotDash, percent - ends); const round = (value: number) => Math.round(value * 1000) / 1000; return { dasharray: `${round(length)} ${round(100 - length)}`, dashoffset: round(-Math.min(ends, percent) / 2) || 0, }; } /** * Where the tooltip of a bar sits, as fractions of the box: the middle of the * bar on its ring's centre line, or 12 o'clock on its ring for a bar with * nothing in it. */ export function barAnchor( share: number, ring: RadialRing, size: number, ): { x: number; y: number } { if (!(size > 0)) return { x: 0.5, y: 0.5 }; const angle = Math.min(1, Math.max(0, share)) * Math.PI; return { x: 0.5 + (ring.radius * Math.sin(angle)) / size, y: 0.5 - (ring.radius * Math.cos(angle)) / size, }; } /** * The text steps of a figure in the hole, in px, from the largest, with the * height of its line and the least hole, in px across, that takes it as its * largest step: a lone ring at `xs` to `lg` leaves a hole of 144, 180, 216 and * 252 px for a figure of 24, 30, 36 and 48 px, and three rings at `xs` leave * 104 px for 20 px. */ export const RADIAL_CENTER_STEPS = [ { hole: 240, line: 60, size: 48 }, { hole: 200, line: 44, size: 36 }, { hole: 150, line: 38, size: 30 }, { hole: 128, line: 32, size: 24 }, { hole: 96, line: 30, size: 20 }, { hole: 0, line: 24, size: 16 }, { hole: 0, line: 20, size: 14 }, { hole: 0, line: 18, size: 12 }, ] as const; export type RadialCenterStep = (typeof RADIAL_CENTER_STEPS)[number]["size"]; /** The least hole, in px across, whose caption is 14 px on a 20 px line; a smaller one's is 12 px on 18. */ export const RADIAL_LARGE_CAPTION_HOLE = 150; /** The steps a hole of `diameter` px offers its figure: its largest step and every smaller one. */ export function radialCenterSteps(diameter: number): RadialCenterStep[] { const first = RADIAL_CENTER_STEPS.findIndex((step) => diameter >= step.hole); return RADIAL_CENTER_STEPS.slice(Math.max(0, first)).map((step) => step.size); } /** The height of a figure's line at a step, in px. */ export function radialCenterLine(size: number): number { return RADIAL_CENTER_STEPS.find((step) => step.size === size)?.line ?? size; } // ~/src/siteplane/components/radial-bar-chart/index.ts export * from "./radial-bar-chart";