@misoto22/design 0.3.1 → 0.6.0

package/dist/charts/lib/sonify-control.d.ts

@@ -0,0 +1,163 @@
+import * as react from 'react';
+import { FC } from 'react';
+import { ChartConfig } from './chart.js';
+import { SonifyOptions, SonifyPoint, SonifySeries, SonifyState } from './sonify.js';
+import 'recharts';
+
+/**
+ * A chart's rows, flattened into what the engine plays.
+ *
+ * Anything that is not a finite number becomes a gap rather than a zero. A
+ * missing month is not a month with no visitors, and sounding it as the bottom
+ * of the range would invent a crash that never happened.
+ *
+ * A series whose `label` is not text falls back to its key: the label is spoken,
+ * and an icon cannot be.
+ */
+declare function chartSonifySeries(rows: Record<string, unknown>[], config: ChartConfig, xDataKey?: string, keys?: string[]): SonifySeries[];
+interface UseSonifyOptions extends SonifyOptions {
+    /**
+     * What the run is called. Spoken once, when the last note has finished, so a
+     * listener knows the silence is the end rather than a stall.
+     */
+    name?: string;
+    /**
+     * Fires as each point sounds, and with `null` between series.
+     *
+     * The hook already tracks this for you (`activePoint`); this is for a call
+     * site that wants to drive something else — a reference line on the plot, a
+     * row highlight in a table beside it.
+     */
+    onPointChange?: (point: SonifyPoint | null) => void;
+}
+interface UseSonifyResult {
+    state: SonifyState;
+    isPlaying: boolean;
+    /** False where the browser has no Web Audio. Resolved after mount, never during render. */
+    isSupported: boolean;
+    /** The point sounding right now, or `null` between series and at rest. */
+    activePoint: SonifyPoint | null;
+    /** The latest text for a live region — a series' range, or the end of the run. */
+    announcement: string;
+    /** Starts, or resumes. Call it from an event handler and nowhere else. */
+    play: () => void;
+    pause: () => void;
+    stop: () => void;
+    /** Play when idle or paused, pause when playing — what one button needs. */
+    toggle: () => void;
+    /** How long the whole run takes, in milliseconds. */
+    durationMs: number;
+}
+/**
+ * Plays a set of series as pitch over time, and reports what is sounding.
+ *
+ * The controller is rebuilt whenever the data or the tuning changes and the
+ * previous one is destroyed with it, so a brush drag or an unmount cancels
+ * every pending timer and releases the audio hardware. No `AudioContext` is
+ * constructed until the first `play()`.
+ *
+ * @example
+ * const series = useMemo(() => chartSonifySeries(rows, config, 'month'), [rows, config])
+ * const { toggle, isPlaying, announcement } = useSonify(series, { name: 'Visitors per month' })
+ *
+ * return (
+ *   <>
+ *     <button type="button" onClick={toggle}>{isPlaying ? 'Pause' : 'Play'}</button>
+ *     <span role="status" aria-live="polite" className="sr-only">{announcement}</span>
+ *   </>
+ * )
+ */
+declare function useSonify(series: SonifySeries[], options?: UseSonifyOptions): UseSonifyResult;
+/** Where the control sits above the plot. */
+type SonifyAlign = 'start' | 'end';
+interface SonifyProps extends SonifyOptions {
+    /**
+     * Which series play, in order. Defaults to every series in the chart's
+     * config.
+     *
+     * Worth narrowing on a chart with four series: sequential playback means four
+     * runs, and a listener rarely wants all of them.
+     */
+    keys?: string[];
+    /** Where the control sits above the plot. */
+    align?: SonifyAlign;
+    /** Overrides the control's visible label. */
+    label?: string;
+    /**
+     * Fires as each point sounds, and with `null` between series — for a call
+     * site that wants to mark the point on the plot itself.
+     */
+    onPointChange?: (point: SonifyPoint | null) => void;
+    /** Merged onto the control row, last. */
+    className?: string;
+}
+/**
+ * Plays this chart's values as sound.
+ *
+ * A slot: it renders nothing, and the chart root reads its props — the same
+ * shape as `<Chart.Values>`. Composing it is what adds the control above the
+ * plot, so a chart that does not ask for sonification ships none of it.
+ *
+ * Reach for it on the charts where a run of values over an axis IS the reading:
+ * a line, an area, a bar series over time. It is not offered on a pie or a
+ * treemap, where there is no order for the notes to be in.
+ *
+ * @example
+ * <LineChart title="Visitors per month" config={config} data={data} xDataKey="month">
+ *   <LineChart.Sonify />
+ *   <LineChart.XAxis dataKey="month" />
+ *   <LineChart.Line dataKey="desktop" />
+ * </LineChart>
+ */
+declare const Sonify: FC<SonifyProps>;
+/**
+ * What a chart root calls to turn its composed `<Chart.Sonify />` slot and its
+ * on-screen rows into playable series.
+ *
+ * The memo is keyed on the VALUE of the slot's `keys`, not on its identity: a
+ * slot's props object is rebuilt on every parent render, so an identity
+ * dependency would replace the controller — and cancel whatever was playing —
+ * every time anything else on the page moved.
+ *
+ * Rows are the rows on screen, brush included. Sonifying the full data behind a
+ * brushed range would say something the picture does not.
+ *
+ * `rows` and `config` are compared by identity, as everywhere else in the
+ * package: a chart handed a freshly built `config` object on every render
+ * rebuilds its run each time, which stops playback. Define both outside the
+ * render, which is what every example here does.
+ */
+declare function useChartSonifySeries(slot: SonifyProps | null, rows: Record<string, unknown>[], config: ChartConfig, xDataKey?: string): SonifySeries[];
+interface ChartSonifyButtonProps extends SonifyProps {
+    /** The figure's name. Spoken as part of the control's accessible name. */
+    title: string;
+    /** The series to play, already flattened — see `chartSonifySeries`. */
+    series: SonifySeries[];
+}
+/**
+ * The control that starts a chart's sonification.
+ *
+ * A real `<button>`, because this is the whole point of the feature: an audio
+ * reading that a keyboard cannot reach is not an accessibility feature. The
+ * visible label is the verb only — "Play", "Pause" — and the rest of the
+ * accessible name is visually hidden, so the name still contains the visible
+ * text verbatim (WCAG 2.5.3) while a screen reader hears which figure it
+ * belongs to.
+ *
+ * No `aria-pressed`. A toggle button announces as "pressed"/"not pressed",
+ * which for a transport control contradicts the label it is sitting on —
+ * "Pause, toggle button, pressed" leaves the listener to work out whether the
+ * chart is playing. A label that names the next action says it once.
+ *
+ * The live region carries the RANGE announcement before each series, not a line
+ * per point: a fourteen-point run would interrupt itself fourteen times and the
+ * listener would hear none of the tones. The per-point readout beside the
+ * button is `aria-hidden` for the same reason — it is there for a sighted
+ * reader following along.
+ *
+ * @example
+ * <ChartSonifyButton title="Visitors per month" series={series} />
+ */
+declare function ChartSonifyButton({ title, series, align, label, className, keys: _keys, onPointChange, formatValue, ...options }: ChartSonifyButtonProps): react.JSX.Element;
+
+export { ChartSonifyButton, type ChartSonifyButtonProps, Sonify, type SonifyAlign, type SonifyProps, type UseSonifyOptions, type UseSonifyResult, chartSonifySeries, Sonify as default, useChartSonifySeries, useSonify };

package/dist/charts/lib/sonify-control.js

@@ -0,0 +1,172 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { Pause, Play, Square } from "lucide-react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { cn } from "../../lib/cn.js";
+import { Button } from "../../components/Button/Button.js";
+import { defaultTick } from "./format.js";
+import {
+  createSonification,
+  hasAudioSupport
+} from "./sonify.js";
+function categoryText(value) {
+  if (typeof value === "number") return value.toLocaleString();
+  if (typeof value === "string" || typeof value === "boolean") return String(value);
+  return "";
+}
+function chartSonifySeries(rows, config, xDataKey, keys) {
+  const wanted = keys ?? Object.keys(config);
+  const categories = xDataKey ? rows.map((row) => categoryText(row[xDataKey])) : void 0;
+  return wanted.filter((key) => key in config).map((key) => {
+    const label = config[key]?.label;
+    return {
+      key,
+      label: typeof label === "string" || typeof label === "number" ? String(label) : key,
+      values: rows.map((row) => {
+        const value = row[key];
+        return typeof value === "number" && Number.isFinite(value) ? value : null;
+      }),
+      categories
+    };
+  });
+}
+function useSonify(series, options = {}) {
+  const {
+    name,
+    onPointChange,
+    noteMs,
+    gapMs,
+    leadInMs,
+    rootFrequency,
+    semitones,
+    wave,
+    volume,
+    formatValue = defaultTick
+  } = options;
+  const [state, setState] = useState("idle");
+  const [activePoint, setActivePoint] = useState(null);
+  const [announcement, setAnnouncement] = useState("");
+  const [isSupported, setIsSupported] = useState(true);
+  const pointChange = useRef(onPointChange);
+  useEffect(() => {
+    pointChange.current = onPointChange;
+  }, [onPointChange]);
+  useEffect(() => {
+    setIsSupported(hasAudioSupport());
+  }, []);
+  const controller = useMemo(
+    () => createSonification({
+      series,
+      options: { noteMs, gapMs, leadInMs, rootFrequency, semitones, wave, volume, formatValue },
+      onPoint: (point) => {
+        setActivePoint(point);
+        pointChange.current?.(point);
+      },
+      onAnnounce: setAnnouncement,
+      onStateChange: setState,
+      onEnd: () => setAnnouncement(name ? `End of ${name}.` : "End of chart.")
+    }),
+    [series, noteMs, gapMs, leadInMs, rootFrequency, semitones, wave, volume, formatValue, name]
+  );
+  useEffect(() => {
+    setState("idle");
+    setActivePoint(null);
+    return () => controller.destroy();
+  }, [controller]);
+  const play = useCallback(() => controller.play(), [controller]);
+  const pause = useCallback(() => controller.pause(), [controller]);
+  const stop = useCallback(() => {
+    controller.stop();
+    setAnnouncement("");
+  }, [controller]);
+  const toggle = useCallback(() => {
+    if (controller.state === "playing") controller.pause();
+    else controller.play();
+  }, [controller]);
+  return {
+    state,
+    isPlaying: state === "playing",
+    isSupported,
+    activePoint,
+    announcement,
+    play,
+    pause,
+    stop,
+    toggle,
+    durationMs: controller.durationMs
+  };
+}
+const ALIGN = {
+  start: "justify-start",
+  end: "justify-end"
+};
+const Sonify = () => null;
+const NO_SERIES = [];
+const KEY_SEPARATOR = "\0";
+function useChartSonifySeries(slot, rows, config, xDataKey) {
+  const hasSlot = slot !== null;
+  const keys = slot?.keys?.join(KEY_SEPARATOR);
+  return useMemo(
+    () => hasSlot ? chartSonifySeries(rows, config, xDataKey, keys?.split(KEY_SEPARATOR)) : NO_SERIES,
+    [hasSlot, keys, rows, config, xDataKey]
+  );
+}
+function ChartSonifyButton({
+  title,
+  series,
+  align = "end",
+  label,
+  className,
+  keys: _keys,
+  onPointChange,
+  formatValue = defaultTick,
+  ...options
+}) {
+  const { state, isPlaying, isSupported, activePoint, announcement, stop, toggle } = useSonify(
+    series,
+    { ...options, formatValue, name: title, onPointChange }
+  );
+  const hasPoints = series.some((entry) => entry.values.some((value) => value !== null));
+  const isDisabled = !isSupported || !hasPoints;
+  const Icon = isPlaying ? Pause : Play;
+  const reason = !isSupported ? " \u2014 audio is not available in this browser" : !hasPoints ? " \u2014 nothing to play" : "";
+  return /* @__PURE__ */ jsxs("div", { className: cn("mb-2 flex items-center gap-2", ALIGN[align], className), children: [
+    activePoint && // Visual only. The live region is deliberately not told about every
+    // point; see the component note above.
+    /* @__PURE__ */ jsxs("span", { "aria-hidden": true, className: "mono-meta truncate text-(--ink-3-aa)", children: [
+      activePoint.category ?? `#${activePoint.index + 1}`,
+      activePoint.value !== null && ` \xB7 ${formatValue(activePoint.value)}`
+    ] }),
+    state !== "idle" && /* @__PURE__ */ jsxs(Button, { variant: "ghost", size: "md", onClick: stop, children: [
+      /* @__PURE__ */ jsx(Square, { size: 14, strokeWidth: 1.5, "aria-hidden": true }),
+      "Stop",
+      /* @__PURE__ */ jsxs("span", { className: "sr-only", children: [
+        " playing ",
+        title,
+        " as sound"
+      ] })
+    ] }),
+    /* @__PURE__ */ jsxs(Button, { variant: "secondary", size: "md", onClick: toggle, disabled: isDisabled, children: [
+      /* @__PURE__ */ jsx(Icon, { size: 14, strokeWidth: 1.5, "aria-hidden": true }),
+      label ?? (isPlaying ? "Pause" : "Play"),
+      /* @__PURE__ */ jsxs("span", { className: "sr-only", children: [
+        " ",
+        isPlaying ? "playing" : "this chart",
+        " as sound: ",
+        title,
+        reason
+      ] })
+    ] }),
+    /* @__PURE__ */ jsx("span", { role: "status", "aria-live": "polite", className: "sr-only", children: announcement })
+  ] });
+}
+var sonify_control_default = Sonify;
+export {
+  ChartSonifyButton,
+  Sonify,
+  chartSonifySeries,
+  sonify_control_default as default,
+  useChartSonifySeries,
+  useSonify
+};
+//# sourceMappingURL=sonify-control.js.map

package/dist/charts/lib/sonify-control.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/charts/lib/sonify-control.tsx"],"sourcesContent":["'use client'\n\nimport { Pause, Play, Square } from 'lucide-react'\nimport { useCallback, useEffect, useMemo, useRef, useState, type FC } from 'react'\nimport { cn } from '../../lib/cn'\nimport { Button } from '../../components/Button/Button'\nimport type { ChartConfig } from './chart'\nimport { defaultTick } from './format'\nimport {\n  createSonification,\n  hasAudioSupport,\n  type SonifyOptions,\n  type SonifyPoint,\n  type SonifySeries,\n  type SonifyState,\n} from './sonify'\n\n/**\n * The React surface over `sonify.ts` — a hook, a control, and the slot a chart\n * composes.\n *\n * Everything here obeys the one rule the engine is built around: **sound only\n * ever starts from an explicit user action.** There is no effect that plays, no\n * `autoPlay` prop, and no dependency change that can begin a run. That is not\n * the same conversation as `prefers-reduced-motion` — sound is not motion, and\n * reading a motion preference as \"no audio either\" would silence the readers\n * this feature exists for.\n */\n\n/** A cell as speakable text. Speech has no use for an object. */\nfunction categoryText(value: unknown): string {\n  if (typeof value === 'number') return value.toLocaleString()\n  if (typeof value === 'string' || typeof value === 'boolean') return String(value)\n  return ''\n}\n\n/**\n * A chart's rows, flattened into what the engine plays.\n *\n * Anything that is not a finite number becomes a gap rather than a zero. A\n * missing month is not a month with no visitors, and sounding it as the bottom\n * of the range would invent a crash that never happened.\n *\n * A series whose `label` is not text falls back to its key: the label is spoken,\n * and an icon cannot be.\n */\nexport function chartSonifySeries(\n  rows: Record<string, unknown>[],\n  config: ChartConfig,\n  xDataKey?: string,\n  keys?: string[],\n): SonifySeries[] {\n  const wanted = keys ?? Object.keys(config)\n  const categories = xDataKey ? rows.map((row) => categoryText(row[xDataKey])) : undefined\n\n  return wanted\n    .filter((key) => key in config)\n    .map((key) => {\n      const label = config[key]?.label\n      return {\n        key,\n        label: typeof label === 'string' || typeof label === 'number' ? String(label) : key,\n        values: rows.map((row) => {\n          const value = row[key]\n          return typeof value === 'number' && Number.isFinite(value) ? value : null\n        }),\n        categories,\n      }\n    })\n}\n\nexport interface UseSonifyOptions extends SonifyOptions {\n  /**\n   * What the run is called. Spoken once, when the last note has finished, so a\n   * listener knows the silence is the end rather than a stall.\n   */\n  name?: string\n  /**\n   * Fires as each point sounds, and with `null` between series.\n   *\n   * The hook already tracks this for you (`activePoint`); this is for a call\n   * site that wants to drive something else — a reference line on the plot, a\n   * row highlight in a table beside it.\n   */\n  onPointChange?: (point: SonifyPoint | null) => void\n}\n\nexport interface UseSonifyResult {\n  state: SonifyState\n  isPlaying: boolean\n  /** False where the browser has no Web Audio. Resolved after mount, never during render. */\n  isSupported: boolean\n  /** The point sounding right now, or `null` between series and at rest. */\n  activePoint: SonifyPoint | null\n  /** The latest text for a live region — a series' range, or the end of the run. */\n  announcement: string\n  /** Starts, or resumes. Call it from an event handler and nowhere else. */\n  play: () => void\n  pause: () => void\n  stop: () => void\n  /** Play when idle or paused, pause when playing — what one button needs. */\n  toggle: () => void\n  /** How long the whole run takes, in milliseconds. */\n  durationMs: number\n}\n\n/**\n * Plays a set of series as pitch over time, and reports what is sounding.\n *\n * The controller is rebuilt whenever the data or the tuning changes and the\n * previous one is destroyed with it, so a brush drag or an unmount cancels\n * every pending timer and releases the audio hardware. No `AudioContext` is\n * constructed until the first `play()`.\n *\n * @example\n * const series = useMemo(() => chartSonifySeries(rows, config, 'month'), [rows, config])\n * const { toggle, isPlaying, announcement } = useSonify(series, { name: 'Visitors per month' })\n *\n * return (\n *   <>\n *     <button type=\"button\" onClick={toggle}>{isPlaying ? 'Pause' : 'Play'}</button>\n *     <span role=\"status\" aria-live=\"polite\" className=\"sr-only\">{announcement}</span>\n *   </>\n * )\n */\nexport function useSonify(series: SonifySeries[], options: UseSonifyOptions = {}): UseSonifyResult {\n  const {\n    name,\n    onPointChange,\n    noteMs,\n    gapMs,\n    leadInMs,\n    rootFrequency,\n    semitones,\n    wave,\n    volume,\n    formatValue = defaultTick,\n  } = options\n\n  const [state, setState] = useState<SonifyState>('idle')\n  const [activePoint, setActivePoint] = useState<SonifyPoint | null>(null)\n  const [announcement, setAnnouncement] = useState('')\n  // Starts optimistic so the server and the first client render agree; the\n  // effect below is the only place the browser is asked.\n  const [isSupported, setIsSupported] = useState(true)\n\n  // Held in a ref rather than in the memo's dependencies: a call site that\n  // passes an inline arrow would otherwise rebuild the controller — and cancel\n  // the run — on every render.\n  const pointChange = useRef(onPointChange)\n  useEffect(() => {\n    pointChange.current = onPointChange\n  }, [onPointChange])\n\n  useEffect(() => {\n    setIsSupported(hasAudioSupport())\n  }, [])\n\n  const controller = useMemo(\n    () =>\n      createSonification({\n        series,\n        options: { noteMs, gapMs, leadInMs, rootFrequency, semitones, wave, volume, formatValue },\n        onPoint: (point) => {\n          setActivePoint(point)\n          pointChange.current?.(point)\n        },\n        onAnnounce: setAnnouncement,\n        onStateChange: setState,\n        onEnd: () => setAnnouncement(name ? `End of ${name}.` : 'End of chart.'),\n      }),\n    [series, noteMs, gapMs, leadInMs, rootFrequency, semitones, wave, volume, formatValue, name],\n  )\n\n  useEffect(() => {\n    setState('idle')\n    setActivePoint(null)\n    // Runs when the data changes as well as on unmount, which is what stops a\n    // brushed-away run from playing on against rows that are no longer drawn.\n    return () => controller.destroy()\n  }, [controller])\n\n  const play = useCallback(() => controller.play(), [controller])\n  const pause = useCallback(() => controller.pause(), [controller])\n  const stop = useCallback(() => {\n    controller.stop()\n    setAnnouncement('')\n  }, [controller])\n\n  const toggle = useCallback(() => {\n    if (controller.state === 'playing') controller.pause()\n    else controller.play()\n  }, [controller])\n\n  return {\n    state,\n    isPlaying: state === 'playing',\n    isSupported,\n    activePoint,\n    announcement,\n    play,\n    pause,\n    stop,\n    toggle,\n    durationMs: controller.durationMs,\n  }\n}\n\n/** Where the control sits above the plot. */\nexport type SonifyAlign = 'start' | 'end'\n\nconst ALIGN: Record<SonifyAlign, string> = {\n  start: 'justify-start',\n  end: 'justify-end',\n}\n\nexport interface SonifyProps extends SonifyOptions {\n  /**\n   * Which series play, in order. Defaults to every series in the chart's\n   * config.\n   *\n   * Worth narrowing on a chart with four series: sequential playback means four\n   * runs, and a listener rarely wants all of them.\n   */\n  keys?: string[]\n  /** Where the control sits above the plot. */\n  align?: SonifyAlign\n  /** Overrides the control's visible label. */\n  label?: string\n  /**\n   * Fires as each point sounds, and with `null` between series — for a call\n   * site that wants to mark the point on the plot itself.\n   */\n  onPointChange?: (point: SonifyPoint | null) => void\n  /** Merged onto the control row, last. */\n  className?: string\n}\n\n/**\n * Plays this chart's values as sound.\n *\n * A slot: it renders nothing, and the chart root reads its props — the same\n * shape as `<Chart.Values>`. Composing it is what adds the control above the\n * plot, so a chart that does not ask for sonification ships none of it.\n *\n * Reach for it on the charts where a run of values over an axis IS the reading:\n * a line, an area, a bar series over time. It is not offered on a pie or a\n * treemap, where there is no order for the notes to be in.\n *\n * @example\n * <LineChart title=\"Visitors per month\" config={config} data={data} xDataKey=\"month\">\n *   <LineChart.Sonify />\n *   <LineChart.XAxis dataKey=\"month\" />\n *   <LineChart.Line dataKey=\"desktop\" />\n * </LineChart>\n */\nexport const Sonify: FC<SonifyProps> = () => null\n\n/** Shared so an absent slot always yields the same array, not a new empty one. */\nconst NO_SERIES: SonifySeries[] = []\n\n/** Separator for the memo key below. Never appears in a series key. */\nconst KEY_SEPARATOR = '\\u0000'\n\n/**\n * What a chart root calls to turn its composed `<Chart.Sonify />` slot and its\n * on-screen rows into playable series.\n *\n * The memo is keyed on the VALUE of the slot's `keys`, not on its identity: a\n * slot's props object is rebuilt on every parent render, so an identity\n * dependency would replace the controller — and cancel whatever was playing —\n * every time anything else on the page moved.\n *\n * Rows are the rows on screen, brush included. Sonifying the full data behind a\n * brushed range would say something the picture does not.\n *\n * `rows` and `config` are compared by identity, as everywhere else in the\n * package: a chart handed a freshly built `config` object on every render\n * rebuilds its run each time, which stops playback. Define both outside the\n * render, which is what every example here does.\n */\nexport function useChartSonifySeries(\n  slot: SonifyProps | null,\n  rows: Record<string, unknown>[],\n  config: ChartConfig,\n  xDataKey?: string,\n): SonifySeries[] {\n  const hasSlot = slot !== null\n  const keys = slot?.keys?.join(KEY_SEPARATOR)\n\n  return useMemo(\n    () =>\n      hasSlot\n        ? chartSonifySeries(rows, config, xDataKey, keys?.split(KEY_SEPARATOR))\n        : NO_SERIES,\n    [hasSlot, keys, rows, config, xDataKey],\n  )\n}\n\nexport interface ChartSonifyButtonProps extends SonifyProps {\n  /** The figure's name. Spoken as part of the control's accessible name. */\n  title: string\n  /** The series to play, already flattened — see `chartSonifySeries`. */\n  series: SonifySeries[]\n}\n\n/**\n * The control that starts a chart's sonification.\n *\n * A real `<button>`, because this is the whole point of the feature: an audio\n * reading that a keyboard cannot reach is not an accessibility feature. The\n * visible label is the verb only — \"Play\", \"Pause\" — and the rest of the\n * accessible name is visually hidden, so the name still contains the visible\n * text verbatim (WCAG 2.5.3) while a screen reader hears which figure it\n * belongs to.\n *\n * No `aria-pressed`. A toggle button announces as \"pressed\"/\"not pressed\",\n * which for a transport control contradicts the label it is sitting on —\n * \"Pause, toggle button, pressed\" leaves the listener to work out whether the\n * chart is playing. A label that names the next action says it once.\n *\n * The live region carries the RANGE announcement before each series, not a line\n * per point: a fourteen-point run would interrupt itself fourteen times and the\n * listener would hear none of the tones. The per-point readout beside the\n * button is `aria-hidden` for the same reason — it is there for a sighted\n * reader following along.\n *\n * @example\n * <ChartSonifyButton title=\"Visitors per month\" series={series} />\n */\nexport function ChartSonifyButton({\n  title,\n  series,\n  align = 'end',\n  label,\n  className,\n  keys: _keys,\n  onPointChange,\n  formatValue = defaultTick,\n  ...options\n}: ChartSonifyButtonProps) {\n  const { state, isPlaying, isSupported, activePoint, announcement, stop, toggle } = useSonify(\n    series,\n    { ...options, formatValue, name: title, onPointChange },\n  )\n\n  const hasPoints = series.some((entry) => entry.values.some((value) => value !== null))\n  const isDisabled = !isSupported || !hasPoints\n  const Icon = isPlaying ? Pause : Play\n\n  const reason = !isSupported\n    ? ' — audio is not available in this browser'\n    : !hasPoints\n      ? ' — nothing to play'\n      : ''\n\n  return (\n    <div className={cn('mb-2 flex items-center gap-2', ALIGN[align], className)}>\n      {activePoint && (\n        // Visual only. The live region is deliberately not told about every\n        // point; see the component note above.\n        <span aria-hidden className=\"mono-meta truncate text-(--ink-3-aa)\">\n          {activePoint.category ?? `#${activePoint.index + 1}`}\n          {activePoint.value !== null && ` · ${formatValue(activePoint.value)}`}\n        </span>\n      )}\n\n      {state !== 'idle' && (\n        <Button variant=\"ghost\" size=\"md\" onClick={stop}>\n          <Square size={14} strokeWidth={1.5} aria-hidden />\n          Stop\n          <span className=\"sr-only\"> playing {title} as sound</span>\n        </Button>\n      )}\n\n      <Button variant=\"secondary\" size=\"md\" onClick={toggle} disabled={isDisabled}>\n        <Icon size={14} strokeWidth={1.5} aria-hidden />\n        {label ?? (isPlaying ? 'Pause' : 'Play')}\n        <span className=\"sr-only\">\n          {' '}\n          {isPlaying ? 'playing' : 'this chart'} as sound: {title}\n          {reason}\n        </span>\n      </Button>\n\n      <span role=\"status\" aria-live=\"polite\" className=\"sr-only\">\n        {announcement}\n      </span>\n    </div>\n  )\n}\n\nexport default Sonify\n"],"mappings":"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","names":[]}

package/dist/charts/lib/sonify.d.ts

@@ -0,0 +1,248 @@
+/**
+ * A chart's values as pitch over time — the reading a listener gets instead of
+ * the picture.
+ *
+ * The hidden data table (see `figure.tsx`) hands a screen-reader user every
+ * number, which is access but not a SHAPE: fourteen figures read one at a time
+ * do not tell anyone that the line dips in March and never recovers. A run of
+ * tones does, in three seconds, and it is the one thing a chart can offer that
+ * a table cannot. Highcharts is the only mainstream library that ships it; this
+ * is that idea, without the dependency.
+ *
+ * Nothing here touches `window` or constructs an `AudioContext` at module load.
+ * The context is created on the first `play()`, which is the only moment a
+ * browser will allow it — every engine blocks audio until a user gesture, and a
+ * context built at import time arrives permanently `suspended`.
+ *
+ * **This never starts on its own.** `prefers-reduced-motion` is not the setting
+ * that governs it — sound is not motion, and gating audio behind a motion
+ * preference would both silence readers who want it and imply that readers who
+ * do not want motion also do not want sound. The correct rule is simpler and
+ * absolute: audio begins from an explicit user action, and from nothing else.
+ * There is deliberately no `autoPlay` option to pass.
+ */
+/** Whether the run is sounding, held, or not started. */
+type SonifyState = 'idle' | 'playing' | 'paused';
+/**
+ * The oscillator behind every note.
+ *
+ * `triangle` is the default because the two obvious choices are both worse: a
+ * `sine` has no harmonics above its fundamental, so on a laptop speaker — which
+ * reproduces almost nothing under 200 Hz — the bottom of the range simply
+ * vanishes, and a listener hears silence where the data is lowest. A `square`
+ * is the opposite problem: all odd harmonics at full strength is fatiguing
+ * inside ten notes and genuinely unpleasant across sixty. A triangle carries
+ * enough harmonic content to survive a small speaker and stay comfortable.
+ */
+type SonifyWave = 'sine' | 'triangle' | 'square' | 'sawtooth';
+/** The value range the pitch scale is stretched across. */
+interface SonifyDomain {
+    min: number;
+    max: number;
+}
+/** One series, flattened to what sound needs: its values, in order. */
+interface SonifySeries {
+    /** The series key, so a caller can tie a point back to its own data. */
+    key: string;
+    /** What the series is called, spoken before its run of tones. */
+    label: string;
+    /** One entry per point. `null` is a gap — it holds its slot in silence. */
+    values: (number | null)[];
+    /** The category axis, if there is one. Used to say where the run starts and ends. */
+    categories?: string[];
+}
+/** The point sounding right now, for a caller that wants to highlight it. */
+interface SonifyPoint {
+    seriesKey: string;
+    seriesLabel: string;
+    /** Position within its own series. */
+    index: number;
+    /** The category this point sits at, when the chart has a category axis. */
+    category?: string;
+    /** `null` for a gap in the data, which sounds as a rest. */
+    value: number | null;
+}
+interface SonifyOptions {
+    /** How long each point holds the floor. Below ~90ms the run stops being readable. */
+    noteMs?: number;
+    /** Silence after a series, before the next one is announced. */
+    gapMs?: number;
+    /**
+     * The pause between an announcement and the first note it describes.
+     *
+     * Not decoration: a screen reader needs the floor to itself to read the range
+     * out, and a tone starting on top of it means the listener gets neither.
+     */
+    leadInMs?: number;
+    /** The pitch the lowest value sounds at, in Hz. */
+    rootFrequency?: number;
+    /** How far above the root the highest value sits, in semitones. */
+    semitones?: number;
+    wave?: SonifyWave;
+    /** Peak gain per note, 0–1. Deliberately quiet; a chart is not a media player. */
+    volume?: number;
+    /**
+     * How a number is spoken in an announcement. Defaults to the axis's own
+     * formatting.
+     *
+     * Define it outside the render or memoise it. It is part of what the run
+     * says, so a new function identity rebuilds the run — and a rebuilt run is a
+     * stopped one.
+     */
+    formatValue?: (value: number) => string;
+}
+/**
+ * The defaults, and why each is the number it is.
+ *
+ * `rootFrequency` 220 Hz (A3) with a `semitones` span of 24 puts the whole
+ * range between A3 and A5. Below roughly 200 Hz a laptop or phone speaker
+ * reproduces very little, and above about 1 kHz sustained tones start to read
+ * as an alarm; two octaves inside that window is the widest span that stays
+ * comfortable at both ends. Two octaves is also about where pitch DISCRIMINATION
+ * stops improving — stretching to four does not let anyone read the numbers off
+ * more precisely, it just makes the top shrill.
+ */
+declare const SONIFY_DEFAULTS: {
+    readonly noteMs: 220;
+    readonly gapMs: 700;
+    readonly leadInMs: 1200;
+    readonly rootFrequency: 220;
+    readonly semitones: 24;
+    readonly wave: "triangle";
+    readonly volume: 0.18;
+};
+/**
+ * A value's pitch, on a semitone scale rather than a linear sweep of hertz.
+ *
+ * This is the single most important decision in the file. Pitch perception is
+ * logarithmic: the ear hears a RATIO, not a difference. 220 Hz to 440 Hz is one
+ * octave and so is 440 Hz to 880 Hz, even though the second gap is twice as
+ * many hertz. Map values linearly onto hertz and the consequence is immediate —
+ * the bottom half of the data spreads across most of the perceived range while
+ * the top half compresses into a few near-identical tones, so a rise from 900
+ * to 1000 sounds like nothing and a rise from 10 to 110 sounds enormous. The
+ * chart lied.
+ *
+ * Mapping the value range onto a fixed span of SEMITONES fixes it: equal steps
+ * in the data become equal musical intervals, which is what a listener actually
+ * compares. The map is linear-in-value and exponential-in-frequency, so it is
+ * the audio equivalent of a linear axis — not a log axis, which would be a
+ * different claim about the data.
+ *
+ * A flat series (`min === max`) sounds at the middle of the range rather than at
+ * the floor: flat data is not low data, and a run of bottom notes reads as one.
+ *
+ * @example
+ * valueToFrequency(50, { min: 0, max: 100 }) // 220 * 2 ** 1 = 440 Hz, one octave up
+ */
+declare function valueToFrequency(value: number, domain: SonifyDomain, pitch?: Pick<SonifyOptions, 'rootFrequency' | 'semitones'>): number;
+/**
+ * The value range every series is measured against, or `null` when nothing is
+ * finite.
+ *
+ * Shared across all series on purpose. These charts draw their series against
+ * ONE value axis, so they have to sound against one pitch axis too — normalising
+ * each series to its own extremes would make a flat series that never leaves 2%
+ * sound exactly like the one that swings across the whole plot, which is the
+ * opposite of what the picture says.
+ */
+declare function sonifyDomain(series: SonifySeries[]): SonifyDomain | null;
+/**
+ * What is said before a series plays.
+ *
+ * A run of tones with no frame of reference is unreadable — the listener hears
+ * a contour and has no idea whether it spans four units or four million, or how
+ * many points went by. Naming the count, the span of the category axis and the
+ * two extremes costs one sentence and turns the melody into a measurement. The
+ * direction of the mapping is stated too, because "higher is more" is a
+ * convention, not a fact the sound carries.
+ */
+declare function describeSeries(series: SonifySeries, formatValue?: (value: number) => string): string;
+/** One thing that happens at one moment: something said, or a note sounded. */
+type SonifyStep = {
+    kind: 'announce';
+    atMs: number;
+    text: string;
+} | {
+    kind: 'note';
+    atMs: number;
+    point: SonifyPoint;
+    frequency: number | null;
+};
+/**
+ * The whole run, laid out on a timeline before a single sound is made.
+ *
+ * Built as data rather than driven by a loop with a timer inside it, because
+ * this is the part worth testing: the maths that decides when each note lands
+ * is checkable without a speaker, and pause/resume becomes "walk the same array
+ * from a different index" rather than a second, subtly different code path.
+ *
+ * Several series play **in sequence, each introduced by name**, rather than
+ * simultaneously with one panned to each ear. Hard panning is the more
+ * impressive demo and the wrong choice: it assumes a stereo output and two
+ * usable ears, so a mono speaker, a single hearing aid, or unilateral hearing
+ * loss collapses both series into one interleaved melody the listener cannot
+ * unpick — and it caps the feature at two series, when four is ordinary. Played
+ * in sequence, the worst case is that the run takes longer, which is a cost the
+ * listener can see coming and a caller can shorten with `noteMs`.
+ */
+declare function sonifyTimeline(series: SonifySeries[], options?: SonifyOptions): SonifyStep[];
+/** How long the whole run takes, in milliseconds. */
+declare function sonifyDuration(series: SonifySeries[], options?: SonifyOptions): number;
+/**
+ * Whether this environment can make a sound at all.
+ *
+ * Safe on a server: it reads `window` from inside a function, so importing this
+ * module during a server render touches nothing.
+ */
+declare function hasAudioSupport(): boolean;
+interface SonifyHandlers {
+    /** The point currently sounding, so a chart can mark it. `null` between series. */
+    onPoint?: (point: SonifyPoint | null) => void;
+    /** Text meant for a live region — the range announcement before each series. */
+    onAnnounce?: (text: string) => void;
+    onStateChange?: (state: SonifyState) => void;
+    /** Fires once the last note has sounded, not when it was scheduled. */
+    onEnd?: () => void;
+}
+interface SonifyInput extends SonifyHandlers {
+    series: SonifySeries[];
+    options?: SonifyOptions;
+}
+interface SonifyController {
+    /**
+     * Starts, or resumes from where a pause left off.
+     *
+     * MUST be called from a user gesture. That is a browser rule, not a
+     * preference — and it is also the accessibility rule this feature is built
+     * on, so there is no way to reach this except from something the reader did.
+     */
+    play: () => void;
+    /** Holds position. The current note is faded out rather than cut. */
+    pause: () => void;
+    /** Stops and rewinds to the beginning. */
+    stop: () => void;
+    /** Stops and releases the audio hardware. Call on unmount. */
+    destroy: () => void;
+    readonly state: SonifyState;
+    /** The whole run, in milliseconds. */
+    readonly durationMs: number;
+}
+/**
+ * A run of one chart's series, ready to play.
+ *
+ * Constructing one allocates nothing but an array — no `AudioContext`, no
+ * timer, no node. That matters because a chart builds its controller during
+ * render, where creating a context would both break a server render and burn
+ * one of the browser's limited context slots on a chart nobody listens to.
+ *
+ * @example
+ * const run = createSonification({
+ *   series: [{ key: 'desktop', label: 'Desktop', values: [186, 305, 237], categories: ['Jan', 'Feb', 'Mar'] }],
+ *   onPoint: (point) => setActive(point),
+ * })
+ * button.addEventListener('click', () => run.play())
+ */
+declare function createSonification({ series, options, onPoint, onAnnounce, onStateChange, onEnd, }: SonifyInput): SonifyController;
+
+export { SONIFY_DEFAULTS, type SonifyController, type SonifyDomain, type SonifyHandlers, type SonifyInput, type SonifyOptions, type SonifyPoint, type SonifySeries, type SonifyState, type SonifyStep, type SonifyWave, createSonification, describeSeries, hasAudioSupport, sonifyDomain, sonifyDuration, sonifyTimeline, valueToFrequency };