@howells/hairline 0.0.0-stage → 0.1.0

package/lib/tokens.css

@@ -0,0 +1,306 @@
+/*
+ * Palettes. Charts never use hex values: only the semantic variables below.
+ *
+ *   --hl-paper            page and card surface
+ *   --hl-ink              strongest mark and headline colour
+ *   --hl-text / --hl-muted / --hl-faint   text hierarchy
+ *   --hl-grid / --hl-rule    hairlines: the faint grid and quiet rules
+ *   --hl-l0 … --hl-l6        importance ladder, most important first ("lightness is data")
+ *   --hl-hero             the one highlighted element per chart
+ *   --hl-alert            thresholds, regressions, over-budget
+ *   --hl-cat-1 … --hl-cat-4  categorical series
+ *   --hl-heat-1 … --hl-heat-5  sequential ramp, low → high
+ *
+ * Every name is --hl- prefixed and scoped under a Hairline root (.hl-root);
+ * the library sets nothing on :root, so it never collides with a host's own
+ * variables. A host themes a root with deriveTheme (@howells/hairline/theme)
+ * or by overriding these on its own rule. Three house modes are set by
+ * data-palette on the root: paper, pink and dark. `.surface-dark` (the dark
+ * cell) remaps the same names, so a chart inverts without knowing it is on a
+ * dark card.
+ */
+
+.hl-root,
+.hl-root[data-palette="paper"] {
+  /* Paper: patternmode's paper and ink; the ramp steps evenly between them in OKLCH. */
+  --hl-paper: #fbfbf9;
+  --hl-ink: #1d1d1b;
+  --hl-text: #1d1d1b;
+  --hl-muted: #727068;
+  --hl-faint: #9f9e9a;
+  --hl-grid: #eeece7;
+  --hl-rule: #e3e1dc;
+
+  --hl-l0: #1d1d1b;
+  --hl-l1: #41403c;
+  --hl-l2: #5f5e5a;
+  --hl-l3: #7e7d79;
+  --hl-l4: #9f9e9a;
+  --hl-l5: #bfbeb9;
+  --hl-l6: #dad9d5;
+
+  --hl-hero: #1d1d1b;
+  --hl-alert: #c05951;
+
+  --hl-cat-1: var(--hl-l0);
+  --hl-cat-2: var(--hl-l2);
+  --hl-cat-3: var(--hl-l4);
+  --hl-cat-4: var(--hl-l6);
+
+  --hl-heat-1: #dad9d5;
+  --hl-heat-2: #9f9e9a;
+  --hl-heat-3: #7e7d79;
+  --hl-heat-4: #41403c;
+  --hl-heat-5: #1d1d1b;
+
+  /* The paper's grain: noise in the ink's colour at a whisper of opacity. */
+  --hl-grain: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='160' height='160'%3E%3Cfilter id='g'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.85' numOctaves='2' stitchTiles='stitch'/%3E%3CfeColorMatrix values='0 0 0 0 0.000 0 0 0 0 0.000 0 0 0 0 0.000 0 0 0 0.045 0'/%3E%3C/filter%3E%3Crect width='100%' height='100%' filter='url%28%23g%29'/%3E%3C/svg%3E");
+
+  --hl-dk-paper: #1d1d1b;
+  --hl-dk-ink: #fbfbf9;
+  --hl-dk-muted: #9f9e9a;
+  --hl-dk-faint: #5f5e5a;
+  --hl-dk-grid: #34332f;
+  --hl-dk-rule: #2b2a27;
+  --hl-dk-l0: #fbfbf9;
+  --hl-dk-l1: #dad9d5;
+  --hl-dk-l2: #bfbeb9;
+  --hl-dk-l3: #9f9e9a;
+  --hl-dk-l4: #7e7d79;
+  --hl-dk-l5: #5f5e5a;
+  --hl-dk-l6: #41403c;
+  --hl-dk-hero: #fbfbf9;
+  --hl-dk-grain: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='160' height='160'%3E%3Cfilter id='g'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.85' numOctaves='2' stitchTiles='stitch'/%3E%3CfeColorMatrix values='0 0 0 0 1.000 0 0 0 0 0.980 0 0 0 0 0.941 0 0 0 0.036 0'/%3E%3C/filter%3E%3Crect width='100%' height='100%' filter='url%28%23g%29'/%3E%3C/svg%3E");
+}
+
+.hl-root[data-palette="pink"] {
+  /* Pink: a dusty, dusky broadsheet pink (a greyed rose, deeper than any trademark salmon), with a warm ink ramp drawn toward its hue. */
+  --hl-paper: #f1dfdc;
+  --hl-ink: #27201e;
+  --hl-text: #27201e;
+  --hl-muted: #6c605e;
+  --hl-faint: #a59895;
+  --hl-grid: #e4d3cf;
+  --hl-rule: #dccbc7;
+
+  --hl-l0: #27201e;
+  --hl-l1: #443b39;
+  --hl-l2: #635856;
+  --hl-l3: #837775;
+  --hl-l4: #a59895;
+  --hl-l5: #c4b5b2;
+  --hl-l6: #dccbc8;
+
+  --hl-hero: #27201e;
+  --hl-alert: #9c433e;
+
+  --hl-cat-1: var(--hl-l0);
+  --hl-cat-2: var(--hl-l2);
+  --hl-cat-3: var(--hl-l4);
+  --hl-cat-4: var(--hl-l6);
+
+  --hl-heat-1: #dccbc8;
+  --hl-heat-2: #a59895;
+  --hl-heat-3: #837775;
+  --hl-heat-4: #443b39;
+  --hl-heat-5: #27201e;
+
+  /* The paper's grain: noise in the ink's colour at a whisper of opacity. */
+  --hl-grain: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='160' height='160'%3E%3Cfilter id='g'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.85' numOctaves='2' stitchTiles='stitch'/%3E%3CfeColorMatrix values='0 0 0 0 0.275 0 0 0 0 0.137 0 0 0 0 0.098 0 0 0 0.05 0'/%3E%3C/filter%3E%3Crect width='100%' height='100%' filter='url%28%23g%29'/%3E%3C/svg%3E");
+
+  --hl-dk-paper: #1d1d1b;
+  --hl-dk-ink: #fbfbf9;
+  --hl-dk-muted: #9f9e9a;
+  --hl-dk-faint: #5f5e5a;
+  --hl-dk-grid: #34332f;
+  --hl-dk-rule: #2b2a27;
+  --hl-dk-l0: #fbfbf9;
+  --hl-dk-l1: #dad9d5;
+  --hl-dk-l2: #bfbeb9;
+  --hl-dk-l3: #9f9e9a;
+  --hl-dk-l4: #7e7d79;
+  --hl-dk-l5: #5f5e5a;
+  --hl-dk-l6: #41403c;
+  --hl-dk-hero: #fbfbf9;
+  --hl-dk-grain: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='160' height='160'%3E%3Cfilter id='g'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.85' numOctaves='2' stitchTiles='stitch'/%3E%3CfeColorMatrix values='0 0 0 0 1.000 0 0 0 0 0.980 0 0 0 0 0.941 0 0 0 0.036 0'/%3E%3C/filter%3E%3Crect width='100%' height='100%' filter='url%28%23g%29'/%3E%3C/svg%3E");
+}
+
+.hl-root[data-palette="dark"] {
+  /* Dark: a warm near-black page; contrast rebuilt, not inverted. Light ink leads, the ramp descends toward the page. */
+  --hl-paper: #181715;
+  --hl-ink: #f0eeeb;
+  --hl-text: #f0eeeb;
+  --hl-muted: #888683;
+  --hl-faint: #686663;
+  --hl-grid: #242321;
+  --hl-rule: #2c2b29;
+
+  --hl-l0: #f0eeeb;
+  --hl-l1: #cccac7;
+  --hl-l2: #a9a7a4;
+  --hl-l3: #888683;
+  --hl-l4: #686663;
+  --hl-l5: #4c4a47;
+  --hl-l6: #373533;
+
+  /* A shade below the text ink, so large solid heroes glow rather than glare. */
+  --hl-hero: #d8d6d2;
+  --hl-alert: #d87a6e;
+
+  --hl-cat-1: var(--hl-l0);
+  --hl-cat-2: var(--hl-l2);
+  --hl-cat-3: var(--hl-l4);
+  --hl-cat-4: var(--hl-l6);
+
+  --hl-heat-1: #373533;
+  --hl-heat-2: #686663;
+  --hl-heat-3: #888683;
+  --hl-heat-4: #cccac7;
+  --hl-heat-5: #f0eeeb;
+
+  /* The paper's grain: noise in the ink's colour at a whisper of opacity. */
+  --hl-grain: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='160' height='160'%3E%3Cfilter id='g'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.85' numOctaves='2' stitchTiles='stitch'/%3E%3CfeColorMatrix values='0 0 0 0 1.000 0 0 0 0 0.980 0 0 0 0 0.941 0 0 0 0.036 0'/%3E%3C/filter%3E%3Crect width='100%' height='100%' filter='url%28%23g%29'/%3E%3C/svg%3E");
+  --hl-dk-grain: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='160' height='160'%3E%3Cfilter id='g'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.85' numOctaves='2' stitchTiles='stitch'/%3E%3CfeColorMatrix values='0 0 0 0 1.000 0 0 0 0 0.980 0 0 0 0 0.941 0 0 0 0.036 0'/%3E%3C/filter%3E%3Crect width='100%' height='100%' filter='url%28%23g%29'/%3E%3C/svg%3E");
+
+  /* The one dark cell sits a step deeper than the dark page. */
+  --hl-dk-paper: #0e0d0b;
+  --hl-dk-ink: #f0eeeb;
+  --hl-dk-muted: #888683;
+  --hl-dk-faint: #4c4a47;
+  --hl-dk-grid: #1f1e1c;
+  --hl-dk-rule: #262523;
+  --hl-dk-l0: #f0eeeb;
+  --hl-dk-l1: #cccac7;
+  --hl-dk-l2: #a9a7a4;
+  --hl-dk-l3: #888683;
+  --hl-dk-l4: #686663;
+  --hl-dk-l5: #4c4a47;
+  --hl-dk-l6: #373533;
+  --hl-dk-hero: #d8d6d2;
+}
+
+/* Dark cards: same names, inverted values. */
+.hl-root .surface-dark,
+.hl-root.surface-dark {
+  --hl-paper: var(--hl-dk-paper);
+  --hl-ink: var(--hl-dk-ink);
+  --hl-text: var(--hl-dk-ink);
+  --hl-muted: var(--hl-dk-muted);
+  --hl-faint: var(--hl-dk-faint);
+  --hl-grid: var(--hl-dk-grid);
+  --hl-rule: var(--hl-dk-rule);
+  --hl-l0: var(--hl-dk-l0);
+  --hl-l1: var(--hl-dk-l1);
+  --hl-l2: var(--hl-dk-l2);
+  --hl-l3: var(--hl-dk-l3);
+  --hl-l4: var(--hl-dk-l4);
+  --hl-l5: var(--hl-dk-l5);
+  --hl-l6: var(--hl-dk-l6);
+  --hl-hero: var(--hl-dk-hero);
+  --hl-cat-1: var(--hl-dk-l0);
+  --hl-cat-2: var(--hl-dk-l2);
+  --hl-cat-3: var(--hl-dk-l4);
+  --hl-cat-4: var(--hl-dk-l6);
+  --hl-grain: var(--hl-dk-grain);
+  background: var(--hl-grain), var(--hl-paper);
+  color: var(--hl-text);
+}
+
+/* Derived tones, valid in every palette (and on dark cards). */
+.hl-root,
+.hl-root .surface-dark,
+.hl-root.surface-dark {
+  --hl-alert-soft: color-mix(in oklab, var(--hl-alert) 22%, transparent);
+  --hl-alert-faded: color-mix(in oklab, var(--hl-alert) 45%, var(--hl-paper));
+  --hl-alert-rule: color-mix(in oklab, var(--hl-alert) 55%, var(--hl-paper));
+  --hl-hero-soft: color-mix(in oklab, var(--hl-hero) 25%, var(--hl-paper));
+  --hl-panel: color-mix(in oklab, var(--hl-paper) 96%, var(--hl-ink));
+}
+
+/*
+ * Dashboard boards (the dense, scrubbable style). They sit on the same paper
+ * as every other chart and read the palette's own text, muted, faint, grid
+ * and rule. Series tones are steps on the ramp: past, the cursor's month
+ * (active) and future.
+ */
+.hl-root .surface-board,
+.hl-root.surface-board {
+  --hl-bg: var(--hl-paper);
+  --hl-board-panel: var(--hl-paper);
+
+  /*
+   * Series tones: the fill taxonomy's tones only (src/charts/fills.ts): hero,
+   * l2, l3, l4, l5 and alert. No mixes, no alpha, no l0, l1 or l6.
+   */
+  --hl-s1: var(--hl-l2);
+  --hl-s1-active: var(--hl-hero);
+  --hl-s1-future: var(--hl-l4);
+  --hl-s2: var(--hl-l4);
+  --hl-s2-active: var(--hl-l3);
+  --hl-s2-future: var(--hl-l5);
+  --hl-s3: var(--hl-l5);
+  --hl-s3-active: var(--hl-l4);
+  --hl-s3-future: var(--hl-l5);
+
+  --hl-line1: var(--hl-hero);
+  --hl-line1-future: var(--hl-l4);
+  --hl-line2: var(--hl-l3);
+  --hl-line2-future: var(--hl-l5);
+
+  --hl-area1: var(--hl-l5);
+  --hl-area2: var(--hl-l5);
+  --hl-area3: var(--hl-l5);
+  --hl-band-past: var(--hl-l5);
+  --hl-band-future: var(--hl-l5);
+
+  /* Red marks one exceptional thing per chart: one solid alert tone. */
+  --hl-red: var(--hl-alert);
+  --hl-red-past: var(--hl-alert);
+  --hl-red-future: var(--hl-alert);
+  --hl-red-soft: var(--hl-alert);
+  --hl-red-rule: var(--hl-alert);
+
+  --hl-board-bar: var(--hl-l3);
+  --hl-board-label-2: var(--hl-l3);
+  --hl-board-swatch-3: var(--hl-l4);
+  --hl-board-link: var(--hl-l5);
+  --hl-board-link-hot: var(--hl-l4);
+  --hl-board-hot: var(--hl-alert);
+  --hl-board-heat-1: var(--hl-l5);
+  --hl-board-heat-2: var(--hl-l4);
+  --hl-board-heat-3: var(--hl-l3);
+  --hl-board-heat-4: var(--hl-l2);
+  --hl-board-heat-5: var(--hl-hero);
+
+  --hl-panel: var(--hl-board-panel);
+  background: var(--hl-grain), var(--hl-bg);
+  color: var(--hl-text);
+}
+
+/*
+ * Motion. Every chart moves with these and nothing else; charts/motion.ts
+ * mirrors them for the few charts animated from script.
+ */
+.hl-root {
+  /* Arrivals: bars, dots and labels appearing in place (ease-out-quint). */
+  --hl-ease-enter: cubic-bezier(0.23, 1, 0.32, 1);
+  /* Crossing the chart: lines drawing on, wipes, marks moving (ease-in-out-quart). */
+  --hl-ease-travel: cubic-bezier(0.77, 0, 0.175, 1);
+  /* Tone changes: hover dims, highlights, palettes. */
+  --hl-ease-tone: ease;
+
+  --hl-duration-hover: 150ms; /* dims and highlights under the pointer */
+  --hl-duration-change: 400ms; /* data or palette changing in place */
+  --hl-duration-enter: 600ms; /* dots and text arriving */
+  --hl-duration-grow: 800ms; /* bars and areas rising from their baseline */
+  --hl-duration-long: 1200ms; /* lines drawing on, marks crossing a chart */
+
+  /* Labels and furniture trail the marks they describe. */
+  --hl-fade-lag: 150ms;
+
+  /* Steps between neighbours in a group, by how many there are. */
+  --hl-stagger-dense: 8ms; /* hundreds: cells, ticks, dots */
+  --hl-stagger-fine: 16ms; /* dozens */
+  --hl-stagger-mark: 40ms; /* a handful of bars or points */
+  --hl-stagger-series: 80ms; /* a few series, rows or phases */
+}

package/lib/types/charts/axes.d.ts

@@ -0,0 +1,14 @@
+export interface Margin {
+    bottom: number;
+    left: number;
+    right: number;
+    top: number;
+}
+export interface TickMark {
+    label: string;
+    x: number;
+}
+/** Where a mark sits relative to the scrub cursor. */
+export declare const phase: (i: number, cursor: number) => "active" | "future" | "past";
+/** Snap a coordinate to the pixel grid for crisp 1px lines. */
+export declare const crisp: (v: number) => number;

package/lib/types/charts/basics/candlestick.d.ts

@@ -0,0 +1,22 @@
+import type { NoteProps } from "../../schema/options.js";
+import type { CandleDatum } from "./candlestick.data.js";
+interface CandlestickProps extends NoteProps {
+    data?: CandleDatum[];
+    /** Formats prices on the value axis. Defaults to the house money format. */
+    format?: (v: number) => string;
+    /**
+     * Formats an exact price: the labelled highest high and lowest low, the
+     * tooltip and the description. Defaults to dollars and cents, which an
+     * exact price needs and the whole-dollar money format would round away.
+     */
+    formatPrice?: (v: number) => string;
+    height?: number;
+}
+/**
+ * F17 Daily price. Open-high-low-close per period: the body runs open to
+ * close (hollow = closed up, hatched = closed down), the wick is the full
+ * reach. Every candle is one grey; the latest is in ink. The highest high and
+ * lowest low carry their price.
+ */
+export declare const Candlestick: (props: CandlestickProps) => import("react").JSX.Element;
+export {};

package/lib/types/charts/basics/candlestick.data.d.ts

@@ -0,0 +1,10 @@
+/** One trading day. */
+export interface CandleDatum {
+    close: number;
+    date: Date;
+    high: number;
+    low: number;
+    open: number;
+}
+/** A made-up price, daily, 24 August to 2 October 2026 (see above). */
+export declare const candlestickDemo: CandleDatum[];

package/lib/types/charts/basics/daily-empty.d.ts

@@ -0,0 +1,7 @@
+/** What a daily chart draws when there is nothing to draw: a quiet axis. */
+export declare const DailyEmpty: ({ floor, height, name, width, }: {
+    floor: number;
+    height: number;
+    name?: string;
+    width: number;
+}) => import("react").JSX.Element;

package/lib/types/charts/basics/daily-readings.d.ts

@@ -0,0 +1,38 @@
+import type { DailyDatum } from "../../schema/daily.js";
+/**
+ * One reading as the daily charts draw it: the date parsed, the key it is
+ * addressed by, and a value that is null for a gap (null, NaN or infinite).
+ */
+export interface Reading {
+    date: Date;
+    key: string;
+    value: number | null;
+}
+/**
+ * The payload as readings in date order (the sort is stable, so readings on
+ * one day keep their order). A date that does not parse is dropped; a value
+ * that is not a finite number becomes a gap.
+ */
+export declare const readingsOf: (data: DailyDatum[]) => Reading[];
+/** Every reading as table rows: its date and value, a gap saying so. */
+export declare const readingRows: (readings: Reading[], fmtDate: (d: Date) => string, format: (v: number) => string) => string[][];
+/** The indexes of the readings that have a value. */
+export declare const liveOf: (readings: Reading[]) => number[];
+/** The readings, with the indexes of those that have a value: they travel together. */
+export interface Series {
+    live: number[];
+    readings: Reading[];
+}
+/** The readings as a `Series`. */
+export declare const seriesOf: (readings: Reading[]) => Series;
+/** React keys: each reading's key, numbered by position so repeats stay unique. */
+export declare const reactKeyOf: (reading: Reading, index: number) => string;
+/** The value at `index`, which the caller knows is live. */
+export declare const valueAt: (readings: Reading[], index: number) => number;
+/**
+ * The reading to draw in ink: the live one whose key is `emphasis`, else
+ * `fallback`. A key that names a gap or no reading emphasises none (-1).
+ */
+export declare const heroOf: (readings: Reading[], live: number[], emphasis: string | undefined, fallback: number) => number;
+/** A reading that has a value: the line and area break where it is false. */
+export declare const isLive: (reading: Reading) => boolean;

package/lib/types/charts/basics/dot-heat.d.ts

@@ -0,0 +1,19 @@
+import type { NoteProps } from "../../schema/options.js";
+import type { DotHeatData } from "./dot-heat.data.js";
+interface DotHeatProps extends NoteProps {
+    data?: DotHeatData;
+    format?: (v: number) => string;
+    height?: number;
+    /** [row, column] of the cell to ring; defaults to the largest. */
+    highlight?: readonly [number, number];
+    /** Label every nth column on the axis. */
+    labelEvery?: number;
+}
+/**
+ * F10 Hour of birth. One dot per cell, its area and tone stretched across
+ * the span from the smallest value to the largest (tone in thirds); the peak is the one dot in ink, inside an evenly dotted ring.
+ * Empty cells keep a pinpoint so silence stays visible. The tooltip sits
+ * above the grid, over the hovered column, clear of every dot.
+ */
+export declare const DotHeat: (props: DotHeatProps) => import("react").JSX.Element;
+export {};

package/lib/types/charts/basics/dot-heat.data.d.ts

@@ -0,0 +1,28 @@
+/** A rows × columns grid of values, e.g. weekday × hour. */
+export interface DotHeatData {
+    columns: string[];
+    rows: string[];
+    values: number[][];
+}
+/**
+ * Share of US births by weekday and hour of delivery, 2013.
+ *
+ * Source: CDC/NCHS, Data Brief 200, "When Are Babies Born: Morning, Noon, or
+ * Night? Birth Certificate Data for 2013". The brief's data table (Figure 1)
+ * only splits Monday to Friday from the weekend, so the hour by weekday
+ * counts come from the file behind it, the 2013 natality public use file
+ * (Nat2013us.zip, record fields DOB_TT time of birth and DOB_WK weekday).
+ * Brief: https://www.cdc.gov/nchs/products/databriefs/db200.htm
+ * Table: https://www.cdc.gov/nchs/data/databriefs/db200_table.pdf
+ * File: https://ftp.cdc.gov/pub/Health_Statistics/NCHS/Datasets/DVS/natality/Nat2013us.zip
+ * Fetched 2026-10-15.
+ *
+ * Transform: the records with a stated time of birth (the 41 states and the
+ * District of Columbia on the 2003 certificate; DOB_TT 9999 or blank is
+ * dropped, leaving 3,563,505 of 3,940,764 records) are counted by DOB_WK and
+ * the hour of DOB_TT. Each weekday's 24 counts are divided by that weekday's
+ * total and given as a per cent to one decimal place.
+ * Check: pooling Monday to Friday, and Saturday with Sunday, reproduces the
+ * brief's table at 8 a.m. (6.7 and 4.6) and noon (6.3 and 5.0).
+ */
+export declare const dotHeatDemo: DotHeatData;

package/lib/types/charts/basics/dumbbell-queue.d.ts

@@ -0,0 +1,15 @@
+import type { DumbbellQueueProps } from "../../schema/dumbbell-queue.js";
+/**
+ * Props are the `dumbbellQueueSchema` payload (src/schema/dumbbell-queue.ts);
+ * `data` is required and never defaults to demo data. Give `width` and
+ * `height` for a fixed-size chart that is complete on the first (server)
+ * render. Bad input is tolerated: a row with a value that is not a finite
+ * number is skipped, negatives extend the axis below zero, equal ends draw
+ * no rungs, duplicate labels each get a row (give them `id`s to tell them
+ * apart), and no data draws a quiet empty axis.
+ *
+ * F12 Before and after. Hollow dot = before, solid dot = after, and the gap
+ * between them holds one 2px rung per unit of change, so it can be counted.
+ * The biggest change is in ink; a row that changed the alert way (a rise by default) rungs in the alert colour.
+ */
+export declare const DumbbellQueue: (props: DumbbellQueueProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;

package/lib/types/charts/basics/hairline-area.d.ts

@@ -0,0 +1,18 @@
+import type { HairlineAreaProps } from "../../schema/hairline-area.js";
+/**
+ * F3 Daily area. The area under the line is an engraved stipple, one 1px dot
+ * per 4px cell, with a 2px stem every seventh day (every month over a year). The peak stands in ink,
+ * labelled, with its label kept inside the frame when it is the first day;
+ * hovering a day raises its stem.
+ *
+ * Props are the `hairlineAreaSchema` payload (src/schema/hairline-area.ts);
+ * `data` is required and never defaults to demo data; dates are ISO strings.
+ * Give `width` and `height` for a fixed-size chart that is complete on the
+ * first (server) render. Bad input is tolerated: readings are drawn in date
+ * order, spaced evenly; a reading whose value is null, NaN or infinite is a
+ * gap, with the area and line broken there; one reading draws a lone dot;
+ * negatives are drawn below the zero line; no readings (or only gaps) draw a
+ * quiet empty axis; `emphasis` is a reading's `id` or date, and one that names
+ * no live reading emphasises none.
+ */
+export declare const HairlineArea: (props: HairlineAreaProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;

package/lib/types/charts/basics/hairline-line.d.ts

@@ -0,0 +1,18 @@
+import type { HairlineLineProps } from "../../schema/hairline-line.js";
+/**
+ * F2 Daily line. One dot per reading on a grey line, placed by its date so a
+ * missing day leaves a gap. Weekend days are hollow rings on an evenly dotted
+ * stem to the floor; the peak (or, with `extreme="trough"`, the lowest) is in
+ * ink on a solid ink stem, with its value. The latest day carries its value
+ * quietly.
+ *
+ * Props are the `hairlineLineSchema` payload (src/schema/hairline-line.ts);
+ * `data` is required and never defaults to demo data; dates are ISO strings.
+ * Give `width` and `height` for a fixed-size chart that is complete on the
+ * first (server) render. Bad input is tolerated: readings are drawn in date
+ * order; a reading whose value is null, NaN or infinite is a gap, with no dot
+ * and a break in the line; one reading draws a lone dot; no readings (or only
+ * gaps) draw a quiet empty axis; `emphasis` is a reading's `id` or date, and
+ * one that names no live reading emphasises none.
+ */
+export declare const HairlineLine: (props: HairlineLineProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;

package/lib/types/charts/basics/nested-treemap.d.ts

@@ -0,0 +1,18 @@
+import type { TreemapGroup } from "./nested-treemap.data.js";
+interface NestedTreemapProps {
+    data?: TreemapGroup[];
+    /** Formats a leaf's value, bare: the chart's name carries the unit. */
+    format?: (v: number) => string;
+    height?: number;
+    /** Leaf to draw in the hero colour, as "Group/Leaf" or a leaf name. Defaults to the largest leaf. */
+    highlight?: string;
+}
+/**
+ * F13 Treemap. Two levels: each parent is a title band with its share, its
+ * children tile the space under it with area = value. Each parent's tiles
+ * share one engraving (stipple, hatch or rules) on paper inside a 1px rule,
+ * so area carries the comparison and texture the family; the largest leaf is
+ * ink.
+ */
+export declare const NestedTreemap: (props: NestedTreemapProps) => import("react").JSX.Element;
+export {};

package/lib/types/charts/basics/nested-treemap.data.d.ts

@@ -0,0 +1,30 @@
+export interface TreemapLeaf {
+    name: string;
+    value: number;
+}
+export interface TreemapGroup {
+    children: TreemapLeaf[];
+    name: string;
+}
+/**
+ * F13 Milk by use. Where the United Kingdom's milk went in 2025: the milk
+ * dairies put into each product, in millions of litres, grouped by kind of
+ * product. Cheddar takes 3,372 of the 12,515 drawn, drinking milk 6,035.
+ *
+ * Source: Defra, "Milk utilisation by dairies in England and Wales", Milk
+ * availability, usage and production dataset (Milkutil_dataset_20261001.ods,
+ * sheet UK_Annual; Open Government Licence v3.0).
+ *   https://www.gov.uk/government/statistics/milk-utilisation-by-dairies-in-england-and-wales
+ *   https://assets.publishing.service.gov.uk/media/6abd090155bc01d752a7f14d/Milkutil_dataset_20261001.ods
+ * Fetched 2026-10-15.
+ *
+ * Transform: the last row of UK_Annual, which is 2025 (its year cell is stored
+ * as the date 2025-07-17); the twelve months of 2025 in UK_Monthly sum to the
+ * same liquid milk and cheddar figures, to 0.1. Columns "Disposals of milk
+ * for ..." in million litres, rounded to whole numbers. Territorials are "other
+ * long life" plus "short life" territorial cheese. Butter is in million cream
+ * litres, as the file gives it. Left out: milk powders (suppressed in the file
+ * as [x]) and the file's catch-all "other products" (1,987 million litres).
+ * Scripts: reference/scripts/F13/gen.py.
+ */
+export declare const nestedTreemapDemo: TreemapGroup[];

package/lib/types/charts/basics/paired-rungs.d.ts

@@ -0,0 +1,21 @@
+import type { NoteProps } from "../../schema/options.js";
+import type { PairDatum } from "./paired-rungs.data.js";
+interface PairedRungsProps extends NoteProps {
+    data?: PairDatum[];
+    /** Units per rung. */
+    unit?: number;
+    height?: number;
+    format?: (v: number) => string;
+    /** Period names for the tooltip, earlier first. */
+    periods?: [string, string];
+    /** Index of the category whose current ladder is drawn in the hero colour. */
+    highlight?: number;
+}
+/**
+ * F6 Getting to work. Per category, the earlier period is a quiet column of
+ * hatch on paper inside a 1px rule, and the current period a stack of grey
+ * 2px rungs (one per unit, every fifth darker). Only the leader's current
+ * stack is in ink; a two-swatch key names the periods.
+ */
+export declare const PairedRungs: (props: PairedRungsProps) => import("react").JSX.Element;
+export {};

package/lib/types/charts/basics/paired-rungs.data.d.ts

@@ -0,0 +1,43 @@
+/** One category measured in two periods. */
+export interface PairDatum {
+    current: number;
+    label: string;
+    previous: number;
+}
+/**
+ * How people in England and Wales usually travel to work, as a percentage of
+ * residents in employment: Census Day 2011 (previous) against Census Day 2021
+ * (current).
+ *
+ * Source: Office for National Statistics, Census 2021 TS061 "Method used to
+ * travel to work" (2001 specification) and Census 2011 QS703EW "Method of
+ * Travel to Work (2001 specification)", both via Nomis (Open Government Licence).
+ *   2021: https://www.nomisweb.co.uk/api/v01/dataset/NM_2078_1.data.csv?geography=2092957703&c2021_ttwmeth_12=0...11&measures=20100
+ *   2011: https://www.nomisweb.co.uk/api/v01/dataset/NM_576_1.data.csv?geography=2092957703&cell=0...12&measures=20100
+ *   Quality note: https://www.ons.gov.uk/employmentandlabourmarket/peopleinwork/employmentandemployeetypes/methodologies/traveltoworkqualityinformationforcensus2021
+ * Fetched 2026-10-15. Geography: England and Wales (K04000001).
+ *
+ * Why QS703EW and not QS701EW: both TS061 and QS703EW use the 2001
+ * specification, in which someone whose workplace is their home counts as
+ * "Work mainly at or from home" even if they also drive (for example to visit
+ * clients). QS701EW (2011 specification) ranks the travel method first and
+ * gives about 1.42 million home workers in 2011 against 2.72 million in
+ * QS703EW, so it is not comparable with TS061. ONS publishes the same headline
+ * for the compatible pair: 10.3% in 2011 and 31.2% in 2021.
+ *
+ * Base population: 2021 is residents aged 16 and over in employment the week
+ * before the census (27,773,666). 2011 is residents aged 16 to 74 (41,126,540)
+ * less the "Not in employment" cell (14,600,204), which leaves 26,526,336 in
+ * employment. The age ceiling differs slightly, so shares are shown, not counts.
+ *
+ * Transform: per category, 100 * cell / employed base for each census, rounded
+ * to one decimal place. Categories kept: "Driving a car or van" (Driving),
+ * "Work mainly at or from home" (At home), "On foot", "Bus, minibus or coach"
+ * (Bus) and "Train"; the rest are dropped, so the five do not sum to 100.
+ *
+ * Caveat: Census Day 2021 (21 March 2021) fell in a national lockdown with
+ * about 5.6 million people on furlough, so the home-working jump is partly a
+ * snapshot of the pandemic. ONS: "census travel to work data are a mixture of
+ * pandemic and pre-pandemic travel behaviours".
+ */
+export declare const pairedRungsDemo: PairDatum[];

package/lib/types/charts/basics/plumb-scatter.d.ts

@@ -0,0 +1,14 @@
+import type { PlumbScatterProps } from "../../schema/plumb-scatter.js";
+/**
+ * F8 Stem scatter. Up to twenty points, each on a stem to the floor so x can
+ * be read where the stem lands: dotted at pitch 3, solid ink for the hero.
+ * The highest point is the hero; the highest and lowest are named.
+ *
+ * Props are the `plumbScatterSchema` payload (src/schema/plumb-scatter.ts);
+ * `data` is required and never defaults to demo data. Give `width` and
+ * `height` for a fixed-size chart that is complete on the first (server)
+ * render. Bad input is tolerated: a point with a coordinate that is not a
+ * finite number is skipped, coincident points each get a dot, negatives are
+ * drawn on the axes, and no data draws a quiet empty axis.
+ */
+export declare const PlumbScatter: (props: PlumbScatterProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;

package/lib/types/charts/basics/rung-bars.d.ts

@@ -0,0 +1,16 @@
+import type { RungBarsProps } from "../../schema/rung-bars.js";
+/**
+ * F1 Counted bars. Each bar is a carved column of solid 2px rungs at one
+ * pitch, one per unit, every tenth long and dark like the marks on a rule,
+ * casting an engraved hatch shadow behind and to its right. The largest bar
+ * is in ink and its shadow is crosshatched.
+ *
+ * Props are the `rungBarsSchema` payload (src/schema/rung-bars.ts); `data` is
+ * required and never defaults to demo data. Give `width` and `height` for a
+ * fixed-size chart that is complete on the first (server) render. Bad input
+ * is tolerated: a datum whose value is not a finite number is skipped,
+ * a negative value stands as an empty column with its figure, duplicate
+ * labels each get a bar (give them `id`s to tell them apart), and no data
+ * draws a quiet empty axis.
+ */
+export declare const RungBars: (props: RungBarsProps) => import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;