@octanejs/visx 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017-2018 Harrison Shoff
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+# `@octanejs/visx`
+
+The complete current Airbnb Visx 4.x visualization toolkit for Octane. The
+package keeps the upstream aggregate API and exposes every public feature package
+as a subpath:
+
+```tsrx
+import { AxisBottom, AxisLeft } from '@octanejs/visx/axis';
+import { scaleBand, scaleLinear } from '@octanejs/visx/scale';
+import { Bar } from '@octanejs/visx/shape';
+
+export function Chart(props) {
+  const x = scaleBand({ domain: props.data.map((d) => d.name), range: [0, 320] });
+  const y = scaleLinear({ domain: [0, Math.max(...props.data.map((d) => d.value))], range: [180, 0] });
+  return (
+    <svg width={360} height={220} aria-label="Values by name">
+      <g transform="translate(30,10)">
+        {props.data.map((d) => (
+          <Bar key={d.name} x={x(d.name)} y={y(d.value)} width={x.bandwidth()} height={180 - y(d.value)} />
+        ))}
+        <AxisBottom top={180} scale={x} />
+        <AxisLeft scale={y} />
+      </g>
+    </svg>
+  );
+}
+```
+
+The root `@octanejs/visx` export matches upstream `@visx/visx` exactly. Atomic
+imports map mechanically: `@visx/xychart` becomes `@octanejs/visx/xychart`,
+`@visx/gradient` becomes `@octanejs/visx/gradient`, and so on. The current 4.x
+master additions are also available through `a11y`, `chart`, `kernel`, and
+`theme`, including the upstream `react`, `server`, and `floating` nested
+subpaths. In Octane, the upstream `/react` names remain compatibility entry-point
+names; their implementations use Octane.
+
+The package ships 49 public entry points: the aggregate root; all 40 feature
+roots (`a11y`, `annotation`, `axis`, `bounds`, `brush`, `chart`, `chord`,
+`clip-path`, `curve`, `delaunay`, `drag`, `event`, `geo`, `glyph`, `gradient`,
+`grid`, `group`, `heatmap`, `hierarchy`, `kernel`, `legend`, `marker`,
+`mock-data`, `network`, `pattern`, `point`, `react-spring`, `responsive`,
+`sankey`, `scale`, `shape`, `stats`, `text`, `theme`, `threshold`, `tooltip`,
+`voronoi`, `wordcloud`, `xychart`, and `zoom`); and the eight upstream nested
+paths `a11y/react`, `a11y/server`, `axis/react`, `scale/react`, `shape/react`,
+`theme/react`, `tooltip/floating`, and `voronoi/react`. All 258 React-owned
+component and hook modules are authored as TSRX; D3, math, data, and accessor
+utilities stay framework-neutral TypeScript.
+
+Octane uses native delegated DOM events, so handlers receive browser events
+rather than React synthetic events. Fixed-size visualizations render their real
+SVG during SSR and hydrate by adopting that DOM. Responsive components preserve
+their upstream initial-size controls and begin observing only after hydration.
+
+Browser-only upstream internals have deterministic first-render adapters. Text
+and annotation measurement use stable font-metric estimates, SplitLinePath uses
+a pure SVG path sampler instead of mounting a browser path, and wordclouds use
+collision-aware estimated glyph rectangles instead of canvas pixel masks. The
+`react-spring` entry point interpolates numeric values on animation frames
+without reproducing spring-physics timing, while Zoom uses native wheel,
+pointer, and touch listeners. These choices keep SSR and hydration stable;
+applications that depend on exact browser font metrics, pixel-exact d3-cloud
+packing, browser-specific path length rounding, or spring timing should account
+for the noted behavioral difference.
+
+The non-importable `@visx/demo` site and private `@visx/registry` tooling are not
+library surfaces. Upstream's `@visx/vendor` is CJS/ESM packaging infrastructure;
+this ESM-first port uses the same pinned D3 implementations directly.

package/UPSTREAM.md

@@ -0,0 +1,52 @@
+# Upstream Visx audit
+
+This port was audited against two immutable Airbnb Visx revisions:
+
+- release `v4.0.0` at `78839796081beb0370fc928cc922b21908bbabaf`, used as the
+  installed React runtime/type oracle;
+- current 4.x `master` at `485c0359664ee8e612992defb16e1f035ed40b23`, used to
+  pin the public additions awaiting the next registry release.
+
+## Public package inventory
+
+The Octane package exposes 49 entry points: its aggregate root, 40 feature
+roots, and eight nested paths. Each `@visx/<feature>` package maps to
+`@octanejs/visx/<feature>`; nested paths retain their upstream suffix.
+
+The 40 roots are `a11y`, `annotation`, `axis`, `bounds`, `brush`, `chart`,
+`chord`, `clip-path`, `curve`, `delaunay`, `drag`, `event`, `geo`, `glyph`,
+`gradient`, `grid`, `group`, `heatmap`, `hierarchy`, `kernel`, `legend`,
+`marker`, `mock-data`, `network`, `pattern`, `point`, `react-spring`,
+`responsive`, `sankey`, `scale`, `shape`, `stats`, `text`, `theme`,
+`threshold`, `tooltip`, `voronoi`, `wordcloud`, `xychart`, and `zoom`.
+
+The nested paths are `a11y/react`, `a11y/server`, `axis/react`, `scale/react`,
+`shape/react`, `theme/react`, `tooltip/floating`, and `voronoi/react`.
+
+The v4.0.0 aggregate has 31 namespaces. Current master adds `A11y`, `Chart`,
+`Kernel`, and `Theme` for an exact 35. Chord, Delaunay, ReactSpring, Sankey, and
+Stats remain direct-only upstream packages. Runtime tests compare every released
+namespace in both directions, pin the exact current-master keys, and reject both
+missing and extra exports. Compile-time assertions do the same for released
+types, with explicit assertions for the documented Octane ref/context/ID
+differences.
+
+## Source ownership
+
+Framework-neutral D3, math, data, scale, path, accessor, and formatting modules
+are retained as TypeScript and use the upstream D3 ESM packages directly. All
+258 React-owned component and hook modules are TSRX and pass Octane's client and
+server compiler modes. React runtime imports, `react-dom`, `react-use-measure`,
+`@react-spring/web`, and `@use-gesture/react` are absent from runtime source.
+
+## Non-library exclusions
+
+- `@visx/demo` is the non-importable Next.js documentation/gallery application.
+- `@visx/registry` is private release/registry tooling.
+- `@visx/vendor` is upstream's dual CJS/ESM D3 packaging layer. Octane is
+  ESM-first and imports the same pinned D3 modules directly.
+
+Those are the only exclusions. They expose no supported web React library API.
+Behavioral divergences required for deterministic SSR, native Octane events,
+refs-as-props, and animation/measurement adapters are recorded in
+[`status.json`](./status.json) and the package [`README.md`](./README.md).

package/package.json

@@ -0,0 +1,161 @@
+{
+  "name": "@octanejs/visx",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "description": "The complete Airbnb Visx 4 visualization toolkit ported to Octane, with native events and deterministic SSR/hydration.",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/visx"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "files": [
+    "src",
+    "LICENSE",
+    "README.md",
+    "UPSTREAM.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./a11y": "./src/a11y/index.ts",
+    "./a11y/react": "./src/a11y/react/index.ts",
+    "./a11y/server": "./src/a11y/server.ts",
+    "./annotation": "./src/annotation/index.ts",
+    "./axis": "./src/axis/index.ts",
+    "./axis/react": "./src/axis/react/index.ts",
+    "./bounds": "./src/bounds/index.ts",
+    "./brush": "./src/brush/index.ts",
+    "./chart": "./src/chart/index.ts",
+    "./chord": "./src/chord/index.ts",
+    "./clip-path": "./src/clip-path/index.ts",
+    "./curve": "./src/curve/index.ts",
+    "./delaunay": "./src/delaunay/index.ts",
+    "./drag": "./src/drag/index.ts",
+    "./event": "./src/event/index.ts",
+    "./geo": "./src/geo/index.ts",
+    "./glyph": "./src/glyph/index.ts",
+    "./gradient": "./src/gradient/index.ts",
+    "./grid": "./src/grid/index.ts",
+    "./group": "./src/group/index.ts",
+    "./heatmap": "./src/heatmap/index.ts",
+    "./hierarchy": "./src/hierarchy/index.ts",
+    "./kernel": "./src/kernel/index.ts",
+    "./legend": "./src/legend/index.ts",
+    "./marker": "./src/marker/index.ts",
+    "./mock-data": "./src/mock-data/index.ts",
+    "./network": "./src/network/index.ts",
+    "./pattern": "./src/pattern/index.ts",
+    "./point": "./src/point/index.ts",
+    "./react-spring": "./src/react-spring/index.ts",
+    "./responsive": "./src/responsive/index.ts",
+    "./sankey": "./src/sankey/index.ts",
+    "./scale": "./src/scale/index.ts",
+    "./scale/react": "./src/scale/react/index.ts",
+    "./shape": "./src/shape/index.ts",
+    "./shape/react": "./src/shape/react/index.ts",
+    "./stats": "./src/stats/index.ts",
+    "./text": "./src/text/index.ts",
+    "./theme": "./src/theme/index.ts",
+    "./theme/react": "./src/theme/react/index.ts",
+    "./threshold": "./src/threshold/index.ts",
+    "./tooltip": "./src/tooltip/index.ts",
+    "./tooltip/floating": "./src/tooltip/floating/index.ts",
+    "./voronoi": "./src/voronoi/index.ts",
+    "./voronoi/react": "./src/voronoi/react/index.ts",
+    "./wordcloud": "./src/wordcloud/index.ts",
+    "./xychart": "./src/xychart/index.ts",
+    "./zoom": "./src/zoom/index.ts"
+  },
+  "dependencies": {
+    "@floating-ui/dom": "^1.7.0",
+    "@types/d3-array": "3.0.3",
+    "@types/d3-chord": "^1.0.9",
+    "@types/d3-color": "3.1.0",
+    "@types/d3-delaunay": "6.0.1",
+    "@types/d3-format": "3.0.1",
+    "@types/d3-geo": "3.1.0",
+    "@types/d3-hierarchy": "^1.1.6",
+    "@types/d3-interpolate": "3.0.1",
+    "@types/d3-path": "3.1.1",
+    "@types/d3-random": "^2.2.0",
+    "@types/d3-sankey": "^0.12.4",
+    "@types/d3-scale": "4.0.2",
+    "@types/d3-shape": "3.1.7",
+    "@types/d3-time": "3.0.0",
+    "@types/d3-time-format": "2.1.0",
+    "@types/d3-voronoi": "^1.1.9",
+    "@types/geojson": "^7946.0.16",
+    "@types/react": "^19.0.0",
+    "@use-gesture/core": "10.3.1",
+    "classnames": "^2.3.1",
+    "d3-array": "3.2.1",
+    "d3-chord": "^1.0.4",
+    "d3-cloud": "^1.2.7",
+    "d3-color": "3.1.0",
+    "d3-delaunay": "6.0.2",
+    "d3-format": "3.1.0",
+    "d3-geo": "3.1.0",
+    "d3-hierarchy": "^1.1.4",
+    "d3-interpolate": "3.0.1",
+    "d3-interpolate-path": "2.2.1",
+    "d3-path": "3.1.0",
+    "d3-random": "^2.2.2",
+    "d3-sankey": "^0.12.3",
+    "d3-scale": "4.0.2",
+    "d3-shape": "3.2.0",
+    "d3-time": "3.1.0",
+    "d3-time-format": "4.1.0",
+    "d3-voronoi": "^1.1.2",
+    "internmap": "2.0.3",
+    "mitt": "^2.1.0",
+    "reduce-css-calc": "^1.3.0",
+    "svg-path-properties": "2.0.2",
+    "@octanejs/floating-ui": "0.1.5"
+  },
+  "peerDependencies": {
+    "octane": "0.1.6"
+  },
+  "devDependencies": {
+    "@juggle/resize-observer": "^3.4.0",
+    "@react-spring/web": "^10.0.0",
+    "@tsrx/react": "^0.2.37",
+    "@visx/chord": "4.0.0",
+    "@visx/annotation": "4.0.0",
+    "@visx/brush": "4.0.0",
+    "@visx/delaunay": "4.0.0",
+    "@visx/react-spring": "4.0.0",
+    "@visx/sankey": "4.0.0",
+    "@visx/stats": "4.0.0",
+    "@visx/tooltip": "4.0.0",
+    "@visx/visx": "4.0.0",
+    "@visx/xychart": "4.0.0",
+    "@visx/zoom": "4.0.0",
+    "@vitest/coverage-istanbul": "4.1.9",
+    "esbuild": "^0.28.1",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.9",
+    "octane": "0.1.6"
+  },
+  "scripts": {
+    "compile:check": "node scripts/check-tsrx-compile.mjs",
+    "types:generate": "node scripts/generate-tsrx-types.mjs",
+    "types:check": "node scripts/generate-tsrx-types.mjs --check && node scripts/check-public-types.mjs",
+    "test": "vitest run --root ../.. --project visx --project visx-ssr",
+    "test:coverage": "vitest run --root ../.. --project visx --project visx-ssr --coverage.enabled --coverage.provider=istanbul --coverage.include=packages/visx/src/** --coverage.reporter=text --coverage.thresholds.statements=99 --coverage.thresholds.lines=99 --coverage.thresholds.branches=15 --coverage.thresholds.functions=40"
+  }
+}

package/src/a11y/components/ChartA11yAnnouncer.tsrx

@@ -0,0 +1,40 @@
+import type { CSSProperties, ReactNode } from 'react';
+
+import { VISUALLY_HIDDEN_STYLE } from '../utils/table';
+
+export type ChartA11yLivePoliteness = 'polite' | 'assertive';
+
+export type ChartA11yAnnouncerProps = {
+	id?: string;
+	message?: ReactNode;
+	children?: ReactNode;
+	politeness?: ChartA11yLivePoliteness;
+	atomic?: boolean;
+	visible?: boolean;
+	className?: string;
+	style?: CSSProperties;
+};
+
+export function ChartA11yAnnouncer({
+	id,
+	message,
+	children,
+	politeness = 'polite',
+	atomic = true,
+	visible = false,
+	className,
+	style,
+}: ChartA11yAnnouncerProps) {
+	const liveRegionStyle = visible ? style : { ...VISUALLY_HIDDEN_STYLE, ...style };
+
+	return <div
+		id={id}
+		role={politeness === 'assertive' ? 'alert' : 'status'}
+		aria-live={politeness}
+		aria-atomic={atomic}
+		className={className}
+		style={liveRegionStyle}
+	>
+		{children ?? message}
+	</div>;
+}

package/src/a11y/components/ChartA11yAnnouncer.tsrx.d.ts

@@ -0,0 +1,14 @@
+// Generated by scripts/generate-tsrx-types.mjs.
+import type { CSSProperties, ReactNode } from 'react';
+export type ChartA11yLivePoliteness = 'polite' | 'assertive';
+export type ChartA11yAnnouncerProps = {
+    id?: string;
+    message?: ReactNode;
+    children?: ReactNode;
+    politeness?: ChartA11yLivePoliteness;
+    atomic?: boolean;
+    visible?: boolean;
+    className?: string;
+    style?: CSSProperties;
+};
+export declare function ChartA11yAnnouncer({ id, message, children, politeness, atomic, visible, className, style, }: ChartA11yAnnouncerProps): import("react").JSX.Element;

package/src/a11y/components/ChartA11yDataTable.tsrx

@@ -0,0 +1,40 @@
+import type { CSSProperties } from 'react';
+import { createElement } from 'octane';
+
+import type { ChartA11yConfig } from '../types';
+import { getChartA11yTable, VISUALLY_HIDDEN_STYLE } from '../utils/table';
+
+export type ChartA11yDataTableProps<Datum> = ChartA11yConfig<Datum> & {
+		visible?: boolean;
+		className?: string;
+		style?: CSSProperties;
+	};
+
+export function ChartA11yDataTable<Datum>({
+	visible = false,
+	className,
+	style,
+	...config
+}: ChartA11yDataTableProps<Datum>) {
+	const table = getChartA11yTable(config);
+	const tableStyle = visible ? style : { ...VISUALLY_HIDDEN_STYLE, ...style };
+	const headerCells = table.headers.map(
+		(header, index) => createElement('th', { key: `${header}-${index}`, scope: 'col' }, header),
+	);
+	const bodyRows = table.rows.map(
+		([xCell, ...yCells], rowIndex) => createElement(
+			'tr',
+			{ key: rowIndex },
+			createElement('th', { scope: 'row' }, xCell),
+			yCells.map((cell, cellIndex) => createElement('td', { key: cellIndex }, cell)),
+		),
+	);
+
+	return <table id={table.id} className={className} style={tableStyle}>
+		<caption>{table.caption}</caption>
+		<thead>
+			<tr>{headerCells}</tr>
+		</thead>
+		<tbody>{bodyRows}</tbody>
+	</table>;
+}

package/src/a11y/components/ChartA11yDataTable.tsrx.d.ts

@@ -0,0 +1,9 @@
+// Generated by scripts/generate-tsrx-types.mjs.
+import type { CSSProperties } from 'react';
+import type { ChartA11yConfig } from '../types';
+export type ChartA11yDataTableProps<Datum> = ChartA11yConfig<Datum> & {
+    visible?: boolean;
+    className?: string;
+    style?: CSSProperties;
+};
+export declare function ChartA11yDataTable<Datum>({ visible, className, style, ...config }: ChartA11yDataTableProps<Datum>): import("react").JSX.Element;

package/src/a11y/generators/ariaProps.ts

@@ -0,0 +1,79 @@
+import type { ChartA11yConfig, ChartA11yPointProps, ChartA11yProps } from '../types';
+import type { NormalizedChartA11ySeries } from '../utils/data';
+import { DEFAULT_POINT_DESCRIPTION_THRESHOLD, normalizeChartA11yData } from '../utils/data';
+import { formatPercent, formatXValue, formatYValue, getChartA11yId } from '../utils/format';
+
+const defaultChartType = 'chart';
+
+function getChartTypeLabel<Datum>({ chartType, locale }: ChartA11yConfig<Datum>) {
+	return (
+		(chartType && locale?.chartTypes?.[chartType]) ||
+		(chartType ? `${chartType} chart` : (locale?.chartRoleDescription ?? defaultChartType))
+	);
+}
+
+function getPointLabel<Datum>(
+	config: ChartA11yConfig<Datum>,
+	series: NormalizedChartA11ySeries<Datum>,
+	pointIndex: number,
+): string {
+	const datum = series.data[pointIndex];
+
+	if (datum == null) {
+		return '';
+	}
+
+	const x = formatXValue(config, datum, pointIndex, series.data);
+	const y = formatYValue(config, datum, pointIndex, series.data);
+
+	if (config.chartType === 'pie' || config.chartType === 'donut') {
+		const total = series.data.reduce(
+			(sum, nextDatum, index) => sum + config.y(nextDatum, index, series.data),
+			0,
+		);
+		const share = total === 0 ? 0 : (config.y(datum, pointIndex, series.data) / total) * 100;
+
+		return `${x}, ${y} (${formatPercent(share)})`;
+	}
+
+	return `${series.label}, ${x}, ${y}`;
+}
+
+export function getChartAriaProps<Datum>(config: ChartA11yConfig<Datum>): ChartA11yProps {
+	const normalized = normalizeChartA11yData(config);
+	const id = getChartA11yId(config);
+	const descriptionId = `${id}-description`;
+	const tableId = `${id}-table`;
+	const chartTypeLabel = getChartTypeLabel(config);
+	const pointDescriptionThreshold =
+		config.pointDescriptionThreshold ?? DEFAULT_POINT_DESCRIPTION_THRESHOLD;
+	const includePointProps = normalized.pointCount <= pointDescriptionThreshold;
+
+	return {
+		ids: {
+			rootId: id,
+			descriptionId,
+			tableId,
+		},
+		svg: {
+			role: 'graphics-document',
+			'aria-roledescription': chartTypeLabel,
+			'aria-label': config.title,
+			'aria-describedby': descriptionId,
+		},
+		series: normalized.series.map((series) => ({
+			role: 'graphics-object',
+			'aria-roledescription': config.locale?.seriesRoleDescription ?? 'series',
+			'aria-label': series.label,
+		})),
+		points: includePointProps
+			? normalized.series.map((series) =>
+					series.data.map<ChartA11yPointProps>((_, index) => ({
+						role: 'graphics-symbol',
+						'aria-roledescription': config.locale?.pointRoleDescription ?? 'data point',
+						'aria-label': getPointLabel(config, series, index),
+					})),
+				)
+			: normalized.series.map(() => []),
+	};
+}

package/src/a11y/generators/dataTableHTML.ts

@@ -0,0 +1,24 @@
+import type { ChartA11yConfig } from '../types';
+import { escapeHtml } from '../utils/format';
+import { getChartA11yTable, VISUALLY_HIDDEN_STYLE_STRING } from '../utils/table';
+
+export const VISUALLY_HIDDEN_TABLE_STYLE = VISUALLY_HIDDEN_STYLE_STRING;
+
+export function generateDataTableHTML<Datum>(config: ChartA11yConfig<Datum>): string {
+	const table = getChartA11yTable(config);
+	const headerHtml = table.headers
+		.map((header) => `<th scope="col">${escapeHtml(header)}</th>`)
+		.join('');
+	const rowHtml = table.rows
+		.map(
+			([xCell, ...yCells]) =>
+				`<tr><th scope="row">${escapeHtml(xCell)}</th>${yCells
+					.map((cell) => `<td>${escapeHtml(cell)}</td>`)
+					.join('')}</tr>`,
+		)
+		.join('');
+	const tableIdHtml = escapeHtml(table.id);
+	const captionHtml = escapeHtml(table.caption);
+
+	return `<table id="${tableIdHtml}" style="${VISUALLY_HIDDEN_TABLE_STYLE}"><caption>${captionHtml}</caption><thead><tr>${headerHtml}</tr></thead><tbody>${rowHtml}</tbody></table>`;
+}

package/src/a11y/generators/description.ts

@@ -0,0 +1,125 @@
+import type { ChartA11yConfig } from '../types';
+import { DEFAULT_POINT_DESCRIPTION_THRESHOLD, normalizeChartA11yData } from '../utils/data';
+import { formatPercent, formatXValue, formatYValue } from '../utils/format';
+
+type NumericPoint = {
+	x: string;
+	y: number;
+	yLabel: string;
+};
+
+function getChartTypeLabel<Datum>({ chartType, locale }: ChartA11yConfig<Datum>) {
+	return (
+		(chartType && locale?.chartTypes?.[chartType]) ||
+		(chartType ? `${chartType} chart` : (locale?.chartRoleDescription ?? 'Chart'))
+	);
+}
+
+function collectNumericPoints<Datum>(config: ChartA11yConfig<Datum>): NumericPoint[] {
+	return normalizeChartA11yData(config).series.flatMap((series) =>
+		series.data
+			.map((datum, index) => ({
+				x: formatXValue(config, datum, index, series.data),
+				y: config.y(datum, index, series.data),
+				yLabel: formatYValue(config, datum, index, series.data),
+			}))
+			.filter(({ y }) => Number.isFinite(y)),
+	);
+}
+
+function generateDenseDescription<Datum>(config: ChartA11yConfig<Datum>) {
+	const points = collectNumericPoints(config);
+
+	if (points.length === 0) {
+		return `${getChartTypeLabel(config)} "${config.title}" has no numeric values.`;
+	}
+
+	const { min, max, sum } = points.reduce(
+		(stats, { y }) => ({
+			min: Math.min(stats.min, y),
+			max: Math.max(stats.max, y),
+			sum: stats.sum + y,
+		}),
+		{ min: points[0].y, max: points[0].y, sum: 0 },
+	);
+	const mean = sum / points.length;
+
+	return `${getChartTypeLabel(config)} of ${config.title}. ${
+		points.length
+	} data points. Values range from ${config.formatY?.(min) ?? String(min)} to ${
+		config.formatY?.(max) ?? String(max)
+	} with an average of ${config.formatY?.(mean) ?? String(Math.round(mean * 100) / 100)}.`;
+}
+
+function generatePieDescription<Datum>(config: ChartA11yConfig<Datum>) {
+	const series = normalizeChartA11yData(config).series[0];
+
+	if (!series || series.data.length === 0) {
+		return `${getChartTypeLabel(config)} "${config.title}" has no segments.`;
+	}
+
+	const segments = series.data.map((datum, index) => ({
+		label: formatXValue(config, datum, index, series.data),
+		value: config.y(datum, index, series.data),
+		formattedValue: formatYValue(config, datum, index, series.data),
+	}));
+	const total = segments.reduce((sum, { value }) => sum + value, 0);
+	const sorted = [...segments].sort((a, b) => a.value - b.value);
+	const smallest = sorted[0];
+	const largest = sorted[sorted.length - 1];
+	const formatSegment = (segment: (typeof segments)[number]) => {
+		const share = total === 0 ? 0 : (segment.value / total) * 100;
+
+		return `${segment.label}, ${segment.formattedValue} (${formatPercent(share)})`;
+	};
+
+	return `${getChartTypeLabel(config)} of ${config.title}. ${
+		segments.length
+	} segments. Largest: ${formatSegment(largest)}. Smallest: ${formatSegment(smallest)}.`;
+}
+
+function generateSmallSeriesDescription<Datum>(config: ChartA11yConfig<Datum>) {
+	const points = collectNumericPoints(config);
+
+	if (points.length === 0) {
+		return `${getChartTypeLabel(config)} "${config.title}" has no numeric values.`;
+	}
+
+	const first = points[0];
+	const last = points[points.length - 1];
+	const min = points.reduce((lowest, point) => (point.y < lowest.y ? point : lowest), points[0]);
+	const max = points.reduce((highest, point) => (point.y > highest.y ? point : highest), points[0]);
+
+	return `${getChartTypeLabel(config)} of ${config.title} over ${
+		points.length
+	} data points. Values start at ${first.yLabel} for ${first.x}, end at ${last.yLabel} for ${
+		last.x
+	}, range from ${min.yLabel} at ${min.x} to ${max.yLabel} at ${max.x}.`;
+}
+
+export function generateChartDescription<Datum>(config: ChartA11yConfig<Datum>): string {
+	if (config.description) {
+		return config.description;
+	}
+
+	const normalized = normalizeChartA11yData(config);
+	const threshold = config.pointDescriptionThreshold ?? DEFAULT_POINT_DESCRIPTION_THRESHOLD;
+
+	if (normalized.pointCount === 0) {
+		return `${getChartTypeLabel(config)} "${config.title}" has no data.`;
+	}
+
+	if (config.chartType === 'pie' || config.chartType === 'donut') {
+		return generatePieDescription(config);
+	}
+
+	if (
+		normalized.pointCount > threshold ||
+		config.chartType === 'scatter' ||
+		config.chartType === 'heatmap'
+	) {
+		return generateDenseDescription(config);
+	}
+
+	return generateSmallSeriesDescription(config);
+}