@howells/hairline 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,109 @@
+import type { ReactNode, KeyboardEvent, PointerEvent, RefObject } from "react";
+/**
+ * Width of an element, kept current with a ResizeObserver. The first width is
+ * read during layout, so a chart is drawn at its final size in the first
+ * painted frame rather than one frame later, which would shift the page.
+ *
+ * `initial` is the width before the first measure (0: draw nothing yet). It
+ * is also what the server renders, so a responsive chart given an
+ * `initialWidth` has real marks in its first HTML. `enabled: false` is fixed
+ * mode: the width stays `initial` and nothing is observed.
+ */
+export declare const useMeasure: <T extends HTMLElement>(initial?: number, enabled?: boolean) => readonly [RefObject<T | null>, number];
+/** Flips to true once the element scrolls into view; drives the entry animation. */
+export declare const useReveal: (ref: RefObject<HTMLElement | null>) => boolean;
+/** The reader's live preference, or null until the client snapshot is available. */
+export declare const useMotionPreference: () => boolean | null;
+/** Assume reduced motion until hydration supplies the reader's preference. */
+export declare const useReducedMotion: () => boolean;
+/**
+ * Separates one React root's SVG ids from another's. React's `useId` is only
+ * unique within a root, so charts rendered in separate roots on one page give
+ * each root its own prefix. Every chart inside it prefixes all its ids.
+ */
+export declare const IdScope: (props: {
+    children?: ReactNode;
+    prefix: string;
+}) => import("react").FunctionComponentElement<import("react").ProviderProps<string>>;
+/**
+ * The one source of SVG ids (patterns, clips, masks, gradients): React's
+ * `useId`, made safe for url(#id) references, led by the surrounding
+ * `IdScope` prefix. Every chart derives its ids from this.
+ */
+export declare const useSvgId: (prefix: string) => string;
+export type Animate = "mount" | "off" | "scroll";
+interface EntryOptions {
+    animate?: Animate;
+    onReady?: () => void;
+    replayKey?: number | string;
+}
+type Phase = "hidden" | "shown" | "still";
+/**
+ * The entry animation and the ready signal for a Plot.
+ *
+ * `phase` is the class state: "hidden" until revealed (on scroll, or at once
+ * for animate="mount"), then "shown"; "still" when nothing animates (animate
+ * "off", or the reader prefers reduced motion), so the chart is simply drawn.
+ * The server and the first client render always agree: hidden, or still for
+ * "off"; the reader's motion preference is only known after hydration. Until
+ * then the stylesheet already draws the plot under reduced motion (nothing is
+ * hidden there), and `ready` follows hydration.
+ *
+ * `ready` turns true once the entry has finished (at once when still);
+ * `onReady` is called at that moment. A new `replayKey` starts a new cycle:
+ * the plot is hidden again and the entry replays in place.
+ */
+export declare const useEntry: (ref: RefObject<HTMLElement | null>, options: EntryOptions) => {
+    readonly phase: Phase;
+    readonly ready: boolean;
+};
+/** Shared hover time, so small multiples scrub together. */
+export interface Sync {
+    setTime: (t: number | null) => void;
+    time: number | null;
+}
+/**
+ * One cursor index per chart. Hover or arrow keys move it; leaving restores
+ * the resting index. Marks left of the cursor read as "past", right as "future".
+ */
+export declare const useScrub: (restIndex: number, dates: Date[], sync?: Sync) => {
+    bind: (positions: number[]) => {
+        onBlur: () => void;
+        onKeyDown: (e: KeyboardEvent<SVGSVGElement>) => void;
+        onPointerLeave: () => void;
+        onPointerMove: (e: PointerEvent<SVGSVGElement>) => void;
+        style: {
+            touchAction: "pan-y";
+        };
+        tabIndex: number;
+    };
+    index: number;
+    isHovering: boolean;
+};
+/** The hovered record and where its tooltip is anchored. */
+export interface HoverAt<K> {
+    key: K;
+    x: number;
+    y: number;
+}
+/**
+ * The one hover state: a record key (an index, an id) plus a tooltip anchor.
+ * `dim(key)` is true for every record but the hovered one, and only while
+ * something is hovered. `enter(key, x, y)` makes the pointer handler for a
+ * record, `showAt(key)` the `(x, y)` callback for a mark that finds its own
+ * anchor; `set` takes a key or null, as a nearest-point search returns.
+ * Re-showing the same record at the same spot does not re-render.
+ */
+export declare const useHover: <K>() => {
+    at: HoverAt<K> | null;
+    clear: () => void;
+    dim: (key: K) => boolean;
+    enter: (key: K, x?: number, y?: number) => () => void;
+    key: K | null;
+    set: (key: K | null, x?: number, y?: number) => void;
+    show: (key: K, x?: number, y?: number) => void;
+    showAt: (key: K) => (x: number, y: number) => void;
+};
+/** What useHover returns, for parts that take a chart's hover. */
+export type Hover<K> = ReturnType<typeof useHover<K>>;
+export {};

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

@@ -0,0 +1,26 @@
+import type { SVGProps } from "react";
+type GroupProps = SVGProps<SVGGElement> & {
+    /** Another record is hovered: drop this one back. */
+    dim: boolean;
+};
+/**
+ * A hoverable record's group. It always carries the opacity transition, so
+ * it eases both ways, and drops to the shared dim level while another
+ * record is hovered.
+ */
+export declare const DimGroup: ({ className, dim, ...rest }: GroupProps) => import("react").JSX.Element;
+/** An invisible rect that widens a record's hover target. */
+export declare const HitRect: ({ className, ...rest }: Omit<SVGProps<SVGRectElement>, "fill">) => import("react").JSX.Element;
+/** An invisible disc that widens a point's hover target. */
+export declare const HitCircle: ({ className, ...rest }: Omit<SVGProps<SVGCircleElement>, "fill">) => import("react").JSX.Element;
+/** An invisible path (a wedge, a sector) that widens a record's hover target. */
+export declare const HitPath: ({ className, ...rest }: Omit<SVGProps<SVGPathElement>, "fill">) => import("react").JSX.Element;
+/**
+ * The tooltip's one sentence: the record's name in bold, then its facts,
+ * each after a middle dot.
+ */
+export declare const TipText: (props: {
+    facts?: readonly string[];
+    lead: string;
+}) => import("react").JSX.Element;
+export {};

package/lib/types/charts/lupi/arc-matrix.d.ts

@@ -0,0 +1,18 @@
+import type { NoteProps } from "../../schema/options.js";
+import type { ArcMatrixData } from "./arc-matrix.data.js";
+interface ArcMatrixProps extends NoteProps {
+    data?: ArcMatrixData;
+    height?: number;
+    format?: (v: number) => string;
+    /** Words after the value in the tooltip, e.g. "of new woodland". */
+    noun?: string;
+    /** How many top cells to label; the largest is inked. Default 3. */
+    top?: number;
+}
+/**
+ * L4 New woodland. Category × category with a magnitude. Each row bows like a
+ * horizon; the bubble at each crossing has area proportional to the value.
+ * The top few cells are labelled; only the largest is inked.
+ */
+export declare const ArcMatrix: (props: ArcMatrixProps) => import("react").JSX.Element;
+export {};

package/lib/types/charts/lupi/arc-matrix.data.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Hectares of new woodland planted each year in the four countries of the UK,
+ * 2014/15 to 2025/26.
+ *
+ * Source: Forest Research, Provisional Woodland Statistics 2026 (Official
+ * Statistics, published 25 June 2026, updated 16 July 2026), workbook
+ * pws_2026-06-25.ods, sheet "Data_for_Figure_3" (area of new planting, UK,
+ * thousands of hectares, years ending 31 March): Crown copyright, Open
+ * Government Licence v3.0.
+ * https://cdn.forestresearch.gov.uk/2026/07/pws_2026-06-25.ods
+ * (publication page: https://www.forestresearch.gov.uk/tools-and-resources/statistics/publications/woodland-statistics/)
+ * Fetched 2026-10-15 (saved to reference/raw/L4/).
+ *
+ * Transform: the rows for years ending March 2015 to March 2026 are read, so
+ * "2014/15" is the year ending 31 March 2015. Each figure, in thousands of
+ * hectares to two decimals, is multiplied by 1,000 to give hectares. Rows are
+ * ordered by their twelve-year total: Scotland 106.4 thousand ha, England
+ * 33.2, Wales 5.8, Northern Ireland 3.7. The workbook marks 2023/24 as
+ * revised ([r]); the figures are used as published.
+ * Script: reference/scripts/L4/emit.py.
+ */
+export interface ArcMatrixData {
+    rows: string[];
+    cols: string[];
+    /** values[row][col] */
+    values: number[][];
+}
+export declare const arcMatrixDemo: ArcMatrixData;

package/lib/types/charts/lupi/ballot-tally.d.ts

@@ -0,0 +1,19 @@
+import type { NoteProps } from "../../schema/options.js";
+import type { TallyDatum } from "./ballot-tally.data.js";
+interface BallotTallyProps extends NoteProps {
+    data?: TallyDatum[];
+    /** The whole sample, for the tooltip: "44 of 100 went". */
+    total?: number;
+    height?: number;
+    format?: (v: number) => string;
+    /** Index of the row drawn in the hero colour. Defaults to the largest. */
+    highlight?: number;
+}
+/**
+ * L15 Days out. Multi-select answers as rulers: every person who went is
+ * one tall 1px tick at one whole-pixel pitch, standing on a faint shared
+ * ruler (longer every ten) that runs to the next ten above the largest
+ * value, so the rows compare at the widest scale. Rows are independent.
+ */
+export declare const BallotTally: (props: BallotTallyProps) => import("react").JSX.Element;
+export {};

package/lib/types/charts/lupi/ballot-tally.data.d.ts

@@ -0,0 +1,28 @@
+/**
+ * L15 Days out: how many people in the European Union went to each kind of
+ * outing in the previous twelve months. Each person could have done any or
+ * all of them, so the four rows are independent.
+ *
+ * Source: Eurostat, ilc_scp03 "Persons participating in cultural or sport
+ * activities in the last 12 months by sex, age, educational attainment,
+ * activity type and frequency" (EU-SILC 2015 ad hoc module).
+ * Dataset: https://ec.europa.eu/eurostat/databrowser/view/ilc_scp03/
+ * Query: https://ec.europa.eu/eurostat/api/dissemination/statistics/1.0/data/ilc_scp03?format=JSON&lang=en&geo=EU27_2020&sex=T&age=Y_GE16&isced11=TOTAL&frequenc=GE1
+ * Fetched 2026-10-15. Eurostat data are reusable with attribution (Commission
+ * Decision 2011/833/EU).
+ *
+ * Transform: geo EU27_2020, 2015 (the only year with an EU aggregate), both
+ * sexes, aged 16 or over, all education levels, frequency "At least once",
+ * unit percentage. The four activity rows are copied (Cinema 44.4, Live
+ * performances 40.7, Cultural sites 40.9, Sports events 29.6) and rounded to
+ * whole numbers per hundred. The combined "cultural activities" row (62.7) is
+ * left out because it overlaps the first three.
+ * Script: reference/scripts/L15/outings.py.
+ */
+/** One option on a multi-select ballot and how many of the sample ticked it. */
+export interface TallyDatum {
+    label: string;
+    value: number;
+}
+/** Of every hundred people aged 16 or over in the EU, those who went, 2015. */
+export declare const ballotTallyDemo: TallyDatum[];

package/lib/types/charts/lupi/barcode-lollipop.d.ts

@@ -0,0 +1,19 @@
+import type { NoteProps } from "../../schema/options.js";
+import type { BarcodeDatum } from "./barcode-lollipop.data.js";
+interface BarcodeLollipopProps extends NoteProps {
+    data?: BarcodeDatum[];
+    height?: number;
+    format?: (v: number) => string;
+    /** Ignored: the margin paragraph is no longer drawn. */
+    aside?: string;
+    /** How many top days to label. Default 3. */
+    top?: number;
+}
+/**
+ * L3 Autumn tides. A vertical hairline for every day (the barcode), a
+ * lollipop dot at each day's high water with a stem down to its low water, so
+ * the stem is the day's range and the fortnightly spring and neap swell shows
+ * in the stem lengths. The highest high waters are labelled.
+ */
+export declare const BarcodeLollipop: (props: BarcodeLollipopProps) => import("react").JSX.Element;
+export {};

package/lib/types/charts/lupi/barcode-lollipop.data.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Autumn 2026 high and low water at Eastport, Maine, a day at a time.
+ *
+ * Source: NOAA CO-OPS tide predictions (Center for Operational Oceanographic
+ * Products and Services), station 8410140 (Eastport), the coming autumn: 1
+ * October to 31 December 2026, 92 days. Query:
+ * https://api.tidesandcurrents.noaa.gov/api/prod/datagetter?product=predictions&application=hairline&begin_date=20261001&end_date=20261231&datum=MLLW&station=8410140&time_zone=lst&units=metric&interval=hilo&format=json
+ * The station ID was looked up in NOAA's station list:
+ * https://api.tidesandcurrents.noaa.gov/mdapi/prod/webapi/stations.json?type=tidepredictions
+ * Fetched 2026-10-15. Heights are predictions in metres above MLLW (mean lower
+ * low water), so a low can read below zero.
+ *
+ * Transform: the file lists every high ("H") and low ("L") tide with its time
+ * in local standard time ("lst", no daylight saving). Each calendar day takes
+ * its highest "H" height as `value` and its lowest "L" height as `low`, so
+ * the stem is that day's range. Nothing else changes: the heights are the
+ * file's own, with trailing zeros dropped. All 92 days have a high and a low.
+ */
+export interface BarcodeDatum {
+    date: Date;
+    /** The day's high water, in metres above MLLW. */
+    value: number;
+    /** Where the stem ends: the day's low water. Defaults to 90% of the value. */
+    low?: number;
+}
+export declare const barcodeLollipopDemo: BarcodeDatum[];

package/lib/types/charts/lupi/brand-spectrum.d.ts

@@ -0,0 +1,28 @@
+import type { NoteProps } from "../../schema/options.js";
+import type { SpectrumRow } from "./brand-spectrum.data.js";
+interface BrandSpectrumProps extends NoteProps {
+    data?: SpectrumRow[];
+    /** Names for the `others` positions, in order. */
+    competitors?: string[];
+    /** Name for the inked position. */
+    us?: string;
+    /** The gap bar's name in the key. Defaults to "Gap to their mean". */
+    gapLabel?: string;
+    height?: number;
+    /**
+     * A position in words, for the tooltip and the accessible label. Defaults
+     * to how far it leans toward a pole ("74% toward Authority"); pass this
+     * when the poles are measured values and the reading is a value too.
+     */
+    describe?: (row: SpectrumRow, position: number) => string;
+    /** The drawing's accessible title. */
+    title?: string;
+}
+/**
+ * L7 Four summits. Bipolar scales where both ends are valid: one row per
+ * pair of opposing poles, each rail a seven-stop ruler. One hill (ink dot)
+ * and the others (hollow 1px rings, named on hover) sit along it, and a short
+ * hatched bar draws the gap from the first to the others' mean.
+ */
+export declare const BrandSpectrum: (props: BrandSpectrumProps) => import("react").JSX.Element;
+export {};

package/lib/types/charts/lupi/brand-spectrum.data.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Ben Nevis against Snowdon, Scafell Pike and Slieve Donard, on six measures
+ * of a hill.
+ *
+ * Source: The Database of British and Irish Hills v18.6 (Creative Commons
+ * Attribution 4.0; cite as "The Database of British and Irish Hills v18.6",
+ * www.hill-bagging.co.uk/dobih), file hillcsv.zip, DoBIH_v18_6.csv, 21,576
+ * hills: https://www.hill-bagging.co.uk/dobih-downloads/hillcsv.zip
+ * (licence and downloads page: https://www.hill-bagging.co.uk/dobih/downloads/).
+ * Fetched 2026-10-15 (saved to reference/raw/L7/).
+ *
+ * Transform: the four hills are rows 278 (Ben Nevis), 1963 (Snowdon - Yr
+ * Wyddfa), 2359 (Scafell Pike) and 20016 (Slieve Donard). Each position is
+ * (value - lowest in the file) / (highest - lowest) over all 21,576 hills,
+ * to two decimals, so 0 is the least and 1 the most of any hill in the
+ * database. Measures, left pole to right pole: Metres (Low to High, 2 to
+ * 1,344.53); Drop (Minor to Prominent, 0 to 1,344.5 m); Col height (Low col
+ * to High col, 0 to 1,275.9 m); Latitude (Southern to Northern, 49.17 to
+ * 60.86); Longitude (Western to Eastern, -10.65 to 1.74); Lists (Few lists to
+ * Many lists, the number of classifications in the "Classification" column,
+ * 1 to 13). Script: reference/scripts/L7/hills.py.
+ */
+export interface SpectrumRow {
+    left: string;
+    right: string;
+    /** The inked hill's position, 0 = fully left pole, 1 = fully right pole. */
+    us: number;
+    /** One position per other hill, in the order of the `competitors` prop. */
+    others: number[];
+}
+/** The three other hills, in the order of each row's `others`. */
+export declare const brandSpectrumCompetitors: string[];
+/** Where each hill sits on six measures, across all the hills in the database. */
+export declare const brandSpectrumDemo: SpectrumRow[];

package/lib/types/charts/lupi/bubble-almanac.d.ts

@@ -0,0 +1,22 @@
+import type { NoteProps } from "../../schema/options.js";
+import type { AlmanacCell, AlmanacEvent, AlmanacNote } from "./bubble-almanac.data.js";
+interface BubbleAlmanacProps extends NoteProps {
+    data?: AlmanacCell[];
+    /** Ignored: margin notes are no longer drawn. */
+    notes?: AlmanacNote[];
+    /** Ignored: the events footer is no longer drawn. */
+    events?: AlmanacEvent[];
+    /** Cells to print values on, as "Category-Year". */
+    labelled?: string[];
+    height?: number;
+    format?: (v: number) => string;
+    noun?: string;
+}
+/**
+ * L9 Coffee growers. Category × year with an amount and a status: veiled
+ * circles (area = amount) that build up where years overlap, a solid core
+ * sized by the yield and a ring dotted at pitch 3 round the
+ * flagged. The largest cell is the hero, filled with a fine halftone screen.
+ */
+export declare const BubbleAlmanac: (props: BubbleAlmanacProps) => import("react").JSX.Element;
+export {};

package/lib/types/charts/lupi/bubble-almanac.data.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Twelve coffee-growing countries over nine years, 2016 to 2024: tonnes of
+ * green coffee produced (size), the yield per hectare (the dark core) and
+ * whether that year's crop fell from the year before (a dotted ring).
+ *
+ * Source: FAO, FAOSTAT "Crops and livestock products" (QCL), bulk file
+ * Production_Crops_Livestock_E_All_Data_(Normalized).csv, item "Coffee,
+ * green", elements Production (tonnes) and Yield (kg/ha), CC BY 4.0:
+ * https://bulks-faostat.fao.org/production/Production_Crops_Livestock_E_All_Data_(Normalized).zip
+ * (catalogue: https://www.fao.org/faostat/en/#data/QCL).
+ * Fetched 2026-10-15 (saved to reference/raw/L9/).
+ *
+ * Transform: the twelve countries with the largest 2024 production, leaving
+ * out regional and income-group aggregates. `value` is Production in millions
+ * of tonnes to three decimals; `core` is Yield in tonnes per hectare (kg/ha
+ * divided by 1,000) to two decimals; `flag` is true when the year's production
+ * is below the previous year's (2015 is read for 2016). "Central African
+ * Republic" is shortened to "Central African Rep." to fit the column head. A country-year with
+ * no figure is left out. FAOSTAT revises past years, so a refetch can differ.
+ * Script: reference/scripts/L9/coffee.py and emit.py.
+ */
+export interface AlmanacCell {
+    category: string;
+    year: number;
+    /** Size of the circle: millions of tonnes produced. */
+    value: number;
+    /** Drawn as the dark core: yield, tonnes per hectare. */
+    core: number;
+    /** Drawn as a dotted ring: production fell on the year before. */
+    flag?: boolean;
+}
+export interface AlmanacNote {
+    category: string;
+    year: number;
+    text: string;
+    /** Offset of the note text from the bubble centre, in px. */
+    dx: number;
+    dy: number;
+}
+export interface AlmanacEvent {
+    label: string;
+    text: string;
+}
+export declare const bubbleAlmanacDemo: AlmanacCell[];
+export declare const bubbleAlmanacLabelled: never[];

package/lib/types/charts/lupi/calendar-heat.d.ts

@@ -0,0 +1,19 @@
+import type { NoteProps } from "../../schema/options.js";
+import type { DayDatum } from "./calendar-heat.data.js";
+interface CalendarHeatProps extends NoteProps {
+    data?: DayDatum[];
+    /** Plural noun for the count, e.g. "births". */
+    unit?: string;
+    /** Ignored: the busiest-day callout text is no longer drawn. */
+    annotation?: string;
+    /** Upper bound on the overall height; the cells shrink to fit. */
+    height?: number;
+}
+/**
+ * L17 A year of births. A year as an engraved almanac: week columns × weekday
+ * rows in stacked bands of months, each day a square halftone whose dot
+ * steps with its count (quieter on weekends, an empty box for none), each
+ * month ringed by a stepped 1px contour, the busiest day crosshatched in ink.
+ */
+export declare const CalendarHeat: (props: CalendarHeatProps) => import("react").JSX.Element;
+export {};

package/lib/types/charts/lupi/calendar-heat.data.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Live births by date of birth, every day of 2016, England and Wales.
+ *
+ * Source: Office for National Statistics, "Number of live births by date,
+ * 1995 to 2016, in England and Wales" (ad hoc request 009036).
+ * Page: https://www.ons.gov.uk/aboutus/transparencyandgovernance/freedomofinformationfoi/dailybirthsdata
+ * File: https://www.ons.gov.uk/file?uri=/peoplepopulationandcommunity/birthsdeathsandmarriages/livebirths/adhocs/009036numberoflivebirthsbydate1995to2016inenglandandwales/adhocbirthsbydate1995to2016.xls
+ * Fetched 2026-10-15.
+ *
+ * Transform: sheet "Data", column "2016", rows 01/01 to 31/12 (366 rows,
+ * including 29/02), copied unchanged and grouped by month below. Code adds
+ * the ISO date of each value; no count is altered.
+ */
+/** One calendar day (ISO date) and its count. */
+export interface DayDatum {
+    date: string;
+    value: number;
+}
+/** The births in England and Wales on every day of 2016. */
+export declare const calendarHeatDemo: DayDatum[];

package/lib/types/charts/lupi/cluster-field.d.ts

@@ -0,0 +1,21 @@
+import type { NoteProps } from "../../schema/options.js";
+import type { ClusterField as ClusterFieldData } from "./cluster-field.data.js";
+interface ClusterFieldProps extends NoteProps {
+    data?: ClusterFieldData;
+    /** Noun for one member, e.g. "variety". */
+    noun?: string;
+    /** Plural of `noun`, e.g. "varieties". */
+    nouns?: string;
+    /** Unit of a member's size, e.g. "ha". */
+    sizeNoun?: string;
+    /** Defaults to a height that fits the poster at the measured width. */
+    height?: number;
+}
+/**
+ * L6 Grape families. A core-plus-satellites network: a big core
+ * cluster with radial spokes, satellite islands around hollow hubs, and pale
+ * arcs between them. Spokes sit at an even angular pitch around each hub.
+ * Hovering a cluster names it, with its members and their total size.
+ */
+export declare const ClusterField: (props: ClusterFieldProps) => import("react").JSX.Element;
+export {};

package/lib/types/charts/lupi/cluster-field.data.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Wine grape varieties grouped by the parent they descend from, each dot a
+ * variety sized by its hectares of vineyard worldwide in 2023; the paths are
+ * varieties that descend from two of the families.
+ *
+ * Sources:
+ * - Areas: Kym Anderson and Signe Nelgen, University of Adelaide, "Which
+ *   winegrape varieties are grown where?", database of winegrape bearing areas
+ *   by variety, 2000 to 2023, sheet "World ranking 2023" (area2023, hectares):
+ *   https://economics.adelaide.edu.au/wine-economics/databases
+ *   (file varieties_2000_to_2023.xlsx, saved to reference/raw/L6/).
+ * - Parentage: the Vitis International Variety Catalogue (VIVC), the
+ *   passport page of each variety and of every ancestor, "Prime name of
+ *   parent 1" and "parent 2": https://www.vivc.de/index.php?r=passport%2Fview&id=<VIVC number>
+ *   (saved to reference/raw/L6/vivc/). VIVC numbers were looked up by name
+ *   through Wikidata property P3904 (https://query.wikidata.org/); only the
+ *   number is taken from Wikidata, never a parent.
+ * Fetched 2026-10-15.
+ *
+ * Transform (scripts in reference/scripts/L6/): take the 90 varieties with
+ * the largest 2023 area, dropping the "other" rows; follow each one's VIVC
+ * parents back to the founders. Five founders are used, the ones with the most
+ * descendants among the 90: Savagnin blanc, Heunisch weiss, Hebén, Muscat
+ * blanc (VIVC "Muscat a petits grains blancs") and Cabernet franc. A variety
+ * joins the family of the founder nearest to it in generations (ties go to
+ * the earlier of the five in that order); a variety that also descends from
+ * a second founder draws a path between the two families. Varieties with no
+ * recorded pedigree, or none from these founders, are left out. Areas are
+ * rounded to whole hectares; each family's members are sorted by size.
+ * Members: Savagnin blanc has Sauvignon Blanc, Pinot Noir, Chenin Blanc,
+ * Verdejo, Grüner Veltliner, Mencía and Castelão; Heunisch weiss has
+ * Chardonnay, Riesling, Colombard, Aligoté, Isabella, Müller-Thurgau,
+ * Blaufränkisch, Fetească Regală, Moldova and Zweigelt; Hebén has
+ * Tempranillo, Airén, Macabeo, Fernão Pires, Xarello and Parellada; Muscat
+ * blanc has Muscat of Alexandria, Cereza, Muscat Ottonel, Criolla Grande,
+ * Pedro Giménez, Grillo, Bianca and Torrontés Riojano; Cabernet franc has
+ * Cabernet Sauvignon, Merlot and Marselan.
+ */
+export interface ClusterDatum {
+    id: string;
+    label: string;
+    /** One size per member (e.g. hectares); sizes the member dot by area. */
+    members: number[];
+    /** Hub position in frame units; the frame is cropped to the hubs and scaled to the width. */
+    at?: [number, number];
+}
+export interface ClusterField {
+    clusters: ClusterDatum[];
+    /** Paths between cluster ids: a member descending from both. */
+    links: [string, string][];
+}
+export declare const clusterFieldDemo: ClusterField;

package/lib/types/charts/lupi/dot-cascade.d.ts

@@ -0,0 +1,22 @@
+import type { NoteProps } from "../../schema/options.js";
+import type { DotCascadeDatum } from "./dot-cascade.data.js";
+interface DotCascadeProps extends NoteProps {
+    data?: DotCascadeDatum[];
+    /** Puzzles per tick. */
+    unit?: number;
+    /** Sort ascending (the staircase). Default true. */
+    sort?: boolean;
+    height?: number;
+    format?: (v: number) => string;
+    /** Words after the value in the tooltip, e.g. "puzzles". */
+    noun?: string;
+    /** Label of the column drawn in ink. Defaults to the last (largest). */
+    highlight?: string;
+}
+/**
+ * L2 Named mates. Ranked counts as columns of 1px unit ticks (one tick =
+ * `unit` puzzles) at one even pitch, rising off a slanted floor, so the
+ * ranking reads as a staircase. A 2px cap tops each column, its value above.
+ */
+export declare const DotCascade: (props: DotCascadeProps) => import("react").JSX.Element;
+export {};

package/lib/types/charts/lupi/dot-cascade.data.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The twelve most common named checkmates among Lichess's puzzles.
+ *
+ * Source: the Lichess open database of puzzles (CC0),
+ * https://database.lichess.org/lichess_db_puzzle.csv.zst, 6,157,341 rated
+ * puzzles, last updated 2026-10-05 by the site. Fetched 2026-10-15 (saved to
+ * reference/raw/L2/).
+ *
+ * Transform: each puzzle carries a space-separated list of themes. Every
+ * theme is counted once per puzzle that carries it. Of the themes that name a
+ * mating pattern (those ending "Mate", leaving out the "mateIn1" to "mateIn5"
+ * depth themes), the twelve with the most puzzles are kept: backRankMate,
+ * pillsburysMate, operaMate, smotheredMate, epauletteMate, cornerMate,
+ * hookMate, swallowstailMate, triangleMate, arabianMate, anastasiaMate and
+ * morphysMate. `value` is the count of puzzles. A puzzle can carry more than
+ * one theme, so the counts overlap. Scripts: reference/scripts/L2/themes.py
+ * and emit.py.
+ */
+export interface DotCascadeDatum {
+    label: string;
+    value: number;
+}
+/** Puzzles carrying each named mate. */
+export declare const dotCascadeDemo: DotCascadeDatum[];

package/lib/types/charts/lupi/dotty-matrix.d.ts

@@ -0,0 +1,17 @@
+import type { NoteProps } from "../../schema/options.js";
+import type { DottyGroup } from "./dotty-matrix.data.js";
+interface DottyMatrixProps extends NoteProps {
+    data?: DottyGroup[];
+    height?: number;
+    format?: (v: number) => string;
+    /** Name of grid cell `k` (0-based) for the tooltip, e.g. "Jan 2023". */
+    cellLabel?: (k: number) => string;
+    /** Unit after the value, e.g. "years gained". */
+    noun?: string;
+}
+/**
+ * L8 Years gained. Groups × grid × amount: each group is an isometric plane
+ * of dots (area = amount) on a fine stipple screen, stacked in space with the most important on top.
+ */
+export declare const DottyMatrix: (props: DottyMatrixProps) => import("react").JSX.Element;
+export {};

package/lib/types/charts/lupi/dotty-matrix.data.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Years of life expectancy gained by men at birth since 1980-82, in each of
+ * the 36 three-year periods from 1987-89 to 2022-24, in the four countries of
+ * the UK, the biggest gain first.
+ *
+ * Source: ONS national life tables, one reference workbook per country, each a
+ * sheet per three-year period with "ex" (period expectation of life) by age
+ * for males and females (OGL):
+ * https://www.ons.gov.uk/peoplepopulationandcommunity/birthsdeathsandmarriages/lifeexpectancies/datasets/nationallifetablesenglandreferencetables
+ * and the same path ending nationallifetableswalesreferencetables,
+ * nationallifetablesscotlandreferencetables and
+ * nationallifetablesnorthernirelandreferencetables (files nlte, nltw, nlts and
+ * nltni 198020223.xlsx, published 10 December 2025).
+ * Fetched 2026-10-15 (saved to reference/raw/L8/).
+ *
+ * Transform: in each country's workbook, the male "ex" at age 0 is read from
+ * every period sheet. `values` is that figure minus the same country's
+ * figure for 1980-82 (England 71.08, Wales 70.52, Scotland 69.11, Northern
+ * Ireland 69.15), to two decimals, so a dot's area is the gain. Periods run
+ * oldest first, six to a row of the plane. The periods overlap (each shares
+ * two years with the next). The dip in 2020-22 is the pandemic. Groups are
+ * ordered by the gain in 2022-24. Script: reference/scripts/L8/extract.py.
+ */
+export interface DottyGroup {
+    label: string;
+    /** grid × grid values, row-major (e.g. 36 periods for a 6 × 6 plane). */
+    values: number[];
+}
+/** The period of cell `k` (0 is 1987-89): "1987–89". */
+export declare const dottyPeriodLabel: (k: number) => string;
+/** Years gained by men at birth since 1980-82, by country and period. */
+export declare const dottyMatrixDemo: DottyGroup[];

package/lib/types/charts/lupi/hourglass-stream.d.ts

@@ -0,0 +1,18 @@
+import type { NoteProps } from "../../schema/options.js";
+import type { StageDatum } from "./hourglass-stream.data.js";
+interface HourglassStreamProps extends NoteProps {
+    data?: StageDatum[];
+    height?: number;
+    format?: (v: number) => string;
+    /** Index of the stage drawn in the hero colour. Defaults to the last. */
+    highlight?: number;
+}
+/**
+ * L13 Library earnings. A funnel poured top to bottom: each stage is a
+ * barcode strip of evenly pitched bars whose width is the count at that
+ * stage, ordered fans of hairline threads pour from one strip to the next,
+ * and the share that gets through each step sits in the left margin, its
+ * leader running into that step's fan.
+ */
+export declare const HourglassStream: (props: HourglassStreamProps) => import("react").JSX.Element;
+export {};