@adminiumjs/charts 0.1.0-rc.1

package/dist/geometry/candles.d.ts

@@ -0,0 +1,39 @@
+export interface Candle {
+    t: string;
+    o: number;
+    h: number;
+    l: number;
+    c: number;
+}
+export interface CandleRect {
+    index: number;
+    /** Candle center x (wick line). */
+    centerX: number;
+    /** Body rect. */
+    x: number;
+    width: number;
+    bodyY: number;
+    bodyHeight: number;
+    /** Wick endpoints (pixel y). */
+    highY: number;
+    lowY: number;
+    /** Close ≥ open → rising (pos tone); else falling (danger tone). */
+    up: boolean;
+}
+export interface CandleLayout {
+    rects: CandleRect[];
+    /** Value → pixel y (price axis). */
+    yFor: (value: number) => number;
+    /** Nice price ticks (ascending). */
+    yTicks: number[];
+}
+export interface CandleLayoutOptions {
+    /** Fraction of each slot the body occupies (0–1, default 0.6). */
+    bodyRatio?: number;
+    tickCount?: number;
+    /** Minimum body height so doji candles stay visible (px, default 1). */
+    minBody?: number;
+}
+/** Index-ordered candle rects + a shared price y-scale over [low…high]. */
+export declare function layoutCandles(candles: readonly Candle[], width: number, height: number, options?: CandleLayoutOptions): CandleLayout;
+//# sourceMappingURL=candles.d.ts.map

package/dist/geometry/candles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"candles.d.ts","sourceRoot":"","sources":["../../src/geometry/candles.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,MAAM;IACrB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,iBAAiB;IACjB,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,EAAE,EAAE,OAAO,CAAC;CACb;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,oCAAoC;IACpC,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IAChC,oCAAoC;IACpC,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,2EAA2E;AAC3E,wBAAgB,aAAa,CAC3B,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,mBAAwB,GAChC,YAAY,CAkCd"}

package/dist/geometry/candles.js

@@ -0,0 +1,42 @@
+/**
+ * OHLC candlestick geometry (`chart-candlestick`, research/widget-registry.md
+ * §2). Pure + DOM-free. The price axis is a fixed LTR-island convention
+ * (04 §7.4 exceptions: candlestick price axis never mirrors), so this layout
+ * takes no `rtl` flag — candles are index-ordered left→right regardless of
+ * page direction.
+ */
+import { extent, niceTicks } from '../utils/stats.js';
+/** Index-ordered candle rects + a shared price y-scale over [low…high]. */
+export function layoutCandles(candles, width, height, options = {}) {
+    const { bodyRatio = 0.6, tickCount = 4, minBody = 1 } = options;
+    const prices = candles.flatMap((candle) => [candle.h, candle.l, candle.o, candle.c]);
+    const [minPrice, maxPrice] = extent(prices) ?? [0, 1];
+    const yTicks = minPrice === maxPrice ? [minPrice, minPrice + 1] : niceTicks(minPrice, maxPrice, tickCount);
+    const domainLo = yTicks[0] ?? minPrice;
+    const domainHi = yTicks.at(-1) ?? maxPrice;
+    const span = domainHi - domainLo || 1;
+    const yFor = (value) => height - ((value - domainLo) / span) * height;
+    const slot = candles.length > 0 ? width / candles.length : width;
+    const bodyWidth = Math.max(1, slot * bodyRatio);
+    const rects = candles.map((candle, index) => {
+        const centerX = slot * (index + 0.5);
+        const openY = yFor(candle.o);
+        const closeY = yFor(candle.c);
+        const up = candle.c >= candle.o;
+        const top = Math.min(openY, closeY);
+        const bodyHeight = Math.max(minBody, Math.abs(closeY - openY));
+        return {
+            index,
+            centerX,
+            x: centerX - bodyWidth / 2,
+            width: bodyWidth,
+            bodyY: top,
+            bodyHeight,
+            highY: yFor(candle.h),
+            lowY: yFor(candle.l),
+            up,
+        };
+    });
+    return { rects, yFor, yTicks };
+}
+//# sourceMappingURL=candles.js.map

package/dist/geometry/candles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"candles.js","sourceRoot":"","sources":["../../src/geometry/candles.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AA0CtD,2EAA2E;AAC3E,MAAM,UAAU,aAAa,CAC3B,OAA0B,EAC1B,KAAa,EACb,MAAc,EACd,UAA+B,EAAE;IAEjC,MAAM,EAAE,SAAS,GAAG,GAAG,EAAE,SAAS,GAAG,CAAC,EAAE,OAAO,GAAG,CAAC,EAAE,GAAG,OAAO,CAAC;IAChE,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IACrF,MAAM,CAAC,QAAQ,EAAE,QAAQ,CAAC,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACtD,MAAM,MAAM,GAAG,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;IAC3G,MAAM,QAAQ,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,QAAQ,CAAC;IACvC,MAAM,QAAQ,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,QAAQ,CAAC;IAC3C,MAAM,IAAI,GAAG,QAAQ,GAAG,QAAQ,IAAI,CAAC,CAAC;IACtC,MAAM,IAAI,GAAG,CAAC,KAAa,EAAE,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,GAAG,QAAQ,CAAC,GAAG,IAAI,CAAC,GAAG,MAAM,CAAC;IAE9E,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC;IACjE,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,GAAG,SAAS,CAAC,CAAC;IAEhD,MAAM,KAAK,GAAiB,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE;QACxD,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,KAAK,GAAG,GAAG,CAAC,CAAC;QACrC,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QAC7B,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QAC9B,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC;QAChC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QACpC,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC;QAC/D,OAAO;YACL,KAAK;YACL,OAAO;YACP,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,CAAC;YAC1B,KAAK,EAAE,SAAS;YAChB,KAAK,EAAE,GAAG;YACV,UAAU;YACV,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;YACrB,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;YACpB,EAAE;SACH,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AACjC,CAAC"}

package/dist/geometry/chord.d.ts

@@ -0,0 +1,53 @@
+export interface ChordNodeInput {
+    id: string;
+    label: string;
+}
+export interface ChordArc {
+    id: string;
+    label: string;
+    startAngle: number;
+    endAngle: number;
+    midAngle: number;
+    /** Total weight incident to this node. */
+    total: number;
+    path: string;
+    colorVar: string;
+}
+export interface ChordRibbon {
+    from: string;
+    to: string;
+    weight: number;
+    path: string;
+    colorVar: string;
+}
+export interface ChordLayout {
+    arcs: ChordArc[];
+    ribbons: ChordRibbon[];
+    radius: number;
+    center: {
+        x: number;
+        y: number;
+    };
+}
+export interface ChordOptions {
+    size: number;
+    /** Arc band thickness in px (default 12). */
+    thickness?: number;
+    /** Angular padding between node arcs, radians (default 0.04). */
+    padAngle?: number;
+    rtl?: boolean;
+}
+/**
+ * Chord layout for `nodes` and a symmetric `weights` matrix
+ * (weights[i][j] = volume between node i and node j; the diagonal is ignored).
+ * Nodes with zero total weight still receive a minimal arc so the ring stays
+ * stable. Returns empty layout for <2 nodes or a non-positive size.
+ */
+export declare function chordLayout(nodes: readonly ChordNodeInput[], weights: readonly (readonly number[])[], options: ChordOptions): ChordLayout;
+/** Build a symmetric adjacency matrix from flows links keyed by node id. */
+export declare function adjacencyMatrix(nodeIds: readonly string[], links: readonly {
+    from: string;
+    to: string;
+    weight: number;
+}[]): number[][];
+//# sourceMappingURL=chord.d.ts.map

package/dist/geometry/chord.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chord.d.ts","sourceRoot":"","sources":["../../src/geometry/chord.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,QAAQ,EAAE,CAAC;IACjB,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAClC;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAWD;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,SAAS,cAAc,EAAE,EAChC,OAAO,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,EACvC,OAAO,EAAE,YAAY,GACpB,WAAW,CAuEb;AAED,4EAA4E;AAC5E,wBAAgB,eAAe,CAC7B,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,KAAK,EAAE,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAAE,GAC7D,MAAM,EAAE,EAAE,CAeZ"}

package/dist/geometry/chord.js

@@ -0,0 +1,111 @@
+/**
+ * Pure chord geometry (`chart-chord`, research/widget-registry.md §2): nodes on
+ * a ring sized by total pairwise volume, connected by quadratic-bezier ribbons
+ * whose thickness encodes pair weight. Built from a symmetric flows adjacency
+ * matrix. DOM-free + deterministic — the same ribbon paths render in Node and
+ * the browser (04 §7.1). Circular layouts step clockwise (LTR) or CCW (RTL) so
+ * node order mirrors per §7.4.
+ */
+import { arc } from 'd3-shape';
+const TAU = Math.PI * 2;
+function vizColor(index) {
+    return `var(--viz-${(index % 8) + 1})`;
+}
+function pointOnCircle(cx, cy, radius, angle) {
+    // Angles measured from 12 o'clock, clockwise.
+    return { x: cx + Math.sin(angle) * radius, y: cy - Math.cos(angle) * radius };
+}
+/**
+ * Chord layout for `nodes` and a symmetric `weights` matrix
+ * (weights[i][j] = volume between node i and node j; the diagonal is ignored).
+ * Nodes with zero total weight still receive a minimal arc so the ring stays
+ * stable. Returns empty layout for <2 nodes or a non-positive size.
+ */
+export function chordLayout(nodes, weights, options) {
+    const { size, thickness = 12, padAngle = 0.04, rtl = false } = options;
+    const n = nodes.length;
+    const radius = Math.max(0, size / 2);
+    const center = { x: radius, y: radius };
+    if (n < 2 || radius <= 0)
+        return { arcs: [], ribbons: [], radius, center };
+    const innerRing = radius - thickness;
+    const totals = nodes.map((_, i) => {
+        let sum = 0;
+        for (let j = 0; j < n; j += 1) {
+            if (i === j)
+                continue;
+            const w = weights[i]?.[j];
+            if (Number.isFinite(w) && w > 0)
+                sum += w;
+        }
+        return sum;
+    });
+    const grandTotal = totals.reduce((s, v) => s + v, 0);
+    const totalPad = padAngle * n;
+    const usable = Math.max(0, TAU - totalPad);
+    // Equal split fallback when there is no weight at all.
+    const share = (value) => (grandTotal > 0 ? (value / grandTotal) * usable : usable / n);
+    const arcGen = arc()
+        .innerRadius(innerRing)
+        .outerRadius(radius);
+    const arcs = [];
+    let angle = 0;
+    const direction = rtl ? -1 : 1;
+    for (let i = 0; i < n; i += 1) {
+        const span = share(totals[i]);
+        const start = angle + padAngle / 2;
+        const end = start + span;
+        angle = end + padAngle / 2;
+        const node = nodes[i];
+        // d3 arc angles are clockwise from 12 o'clock; apply direction for RTL.
+        const a0 = direction === 1 ? start : TAU - end;
+        const a1 = direction === 1 ? end : TAU - start;
+        arcs.push({
+            id: node.id,
+            label: node.label,
+            startAngle: a0,
+            endAngle: a1,
+            midAngle: (a0 + a1) / 2,
+            total: totals[i],
+            path: arcGen({ startAngle: a0, endAngle: a1 }) ?? '',
+            colorVar: vizColor(i),
+        });
+    }
+    const byId = new Map(arcs.map((a) => [a.id, a]));
+    const ribbons = [];
+    for (let i = 0; i < n; i += 1) {
+        for (let j = i + 1; j < n; j += 1) {
+            const w = weights[i]?.[j];
+            if (!Number.isFinite(w) || w <= 0)
+                continue;
+            const a = arcs[i];
+            const b = arcs[j];
+            const p1 = pointOnCircle(center.x, center.y, innerRing, a.midAngle);
+            const p2 = pointOnCircle(center.x, center.y, innerRing, b.midAngle);
+            // Quadratic bezier bowed toward the ring center.
+            const path = `M${p1.x.toFixed(3)},${p1.y.toFixed(3)}Q${center.x.toFixed(3)},${center.y.toFixed(3)} ${p2.x.toFixed(3)},${p2.y.toFixed(3)}`;
+            ribbons.push({ from: nodes[i].id, to: nodes[j].id, weight: w, path, colorVar: byId.get(a.id).colorVar });
+        }
+    }
+    return { arcs, ribbons, radius, center };
+}
+/** Build a symmetric adjacency matrix from flows links keyed by node id. */
+export function adjacencyMatrix(nodeIds, links) {
+    const index = new Map(nodeIds.map((id, i) => [id, i]));
+    const matrix = nodeIds.map(() => nodeIds.map(() => 0));
+    for (const link of links) {
+        const i = index.get(link.from);
+        const j = index.get(link.to);
+        if (i === undefined || j === undefined || i === j)
+            continue;
+        const rowI = matrix[i];
+        const rowJ = matrix[j];
+        if (rowI === undefined || rowJ === undefined)
+            continue;
+        const w = Number.isFinite(link.weight) ? Math.max(0, link.weight) : 0;
+        rowI[j] = (rowI[j] ?? 0) + w;
+        rowJ[i] = (rowJ[i] ?? 0) + w;
+    }
+    return matrix;
+}
+//# sourceMappingURL=chord.js.map

package/dist/geometry/chord.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chord.js","sourceRoot":"","sources":["../../src/geometry/chord.ts"],"names":[],"mappings":"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"}

package/dist/geometry/choropleth.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Canonical 50-state + DC US tile grid (row, col) on an 8×11 board — a plausible
+ * geographic arrangement for the tilegram layout. Codes are USPS two-letter.
+ */
+export declare const US_TILEGRAM: Readonly<Record<string, readonly [number, number]>>;
+export interface RegionPoint {
+    code?: string | undefined;
+    name?: string | undefined;
+    values: Record<string, number>;
+}
+export interface ChoroplethTile {
+    code: string;
+    name: string;
+    row: number;
+    col: number;
+    x: number;
+    y: number;
+    size: number;
+    value: number;
+    level: number;
+    colorVar: string;
+    textLight: boolean;
+}
+export interface ChoroplethLayout {
+    tiles: ChoroplethTile[];
+    levels: number;
+    maxValue: number;
+    width: number;
+    height: number;
+}
+export type ChoroplethLayoutKind = 'us-tilegram' | 'grid';
+export interface ChoroplethOptions {
+    layout?: ChoroplethLayoutKind;
+    /** Value key read from each point's `values` map. */
+    metric: string;
+    cellSize?: number;
+    gap?: number;
+    /** Columns for the compact `grid` layout (default 6). */
+    columns?: number;
+    /** Intensity levels incl. 0 (default 5). */
+    levels?: number;
+    rtl?: boolean;
+}
+/** Tint region tiles by the selected metric. */
+export declare function choroplethLayout(points: readonly RegionPoint[], options: ChoroplethOptions): ChoroplethLayout;
+/**
+ * Whether any point carries a region code the US tilegram can actually place.
+ *
+ * The `us-tilegram` layout is a geographic island: it plots only the 50 states +
+ * DC it knows and silently drops every other code (the placement loop above). So
+ * a payload of non-US codes — or of coordinate-only points that carry no `code`
+ * at all — produces ZERO tiles there, leaving just the low→high legend: a legend
+ * for a map that is not on the page. Callers use this to fall back to the
+ * code-agnostic `grid` layout (which lays every point out in reading order,
+ * regardless of code) rather than render an empty board.
+ */
+export declare function hasUsTilegramTiles(points: readonly RegionPoint[]): boolean;
+//# sourceMappingURL=choropleth.d.ts.map

package/dist/geometry/choropleth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"choropleth.d.ts","sourceRoot":"","sources":["../../src/geometry/choropleth.ts"],"names":[],"mappings":"AAaA;;;GAGG;AACH,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAS3E,CAAC;AAKF,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,oBAAoB,GAAG,aAAa,GAAG,MAAM,CAAC;AAE1D,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,gDAAgD;AAChD,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,SAAS,WAAW,EAAE,EAC9B,OAAO,EAAE,iBAAiB,GACzB,gBAAgB,CAoElB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,GAAG,OAAO,CAE1E"}

package/dist/geometry/choropleth.js

@@ -0,0 +1,101 @@
+/**
+ * Pure tilegram / grid-choropleth geometry (research/widget-registry.md §2
+ * `chart-choropleth-grid`): region tiles tinted by value, label text flipping
+ * to the on-accent color on dark tiles, low→high legend. DOM-free and
+ * deterministic (workplan/04 §7.1).
+ *
+ * RTL policy (04 §7.4): the US tilegram is a geographic LTR island (its tiles
+ * never mirror, like `map-bubble`); the compact `grid` layout is a categorical
+ * flow and mirrors its columns under `rtl`. Legends/tooltips mirror at the
+ * widget layer via logical CSS.
+ */
+import { heatLevel, heatTextLight, rampColorVar } from './heat.js';
+/**
+ * Canonical 50-state + DC US tile grid (row, col) on an 8×11 board — a plausible
+ * geographic arrangement for the tilegram layout. Codes are USPS two-letter.
+ */
+export const US_TILEGRAM = {
+    AK: [0, 0], ME: [0, 10],
+    VT: [1, 9], NH: [1, 10],
+    WA: [2, 0], ID: [2, 1], MT: [2, 2], ND: [2, 3], MN: [2, 4], IL: [2, 5], WI: [2, 6], MI: [2, 7], NY: [2, 9], MA: [2, 10],
+    OR: [3, 0], NV: [3, 1], WY: [3, 2], SD: [3, 3], IA: [3, 4], IN: [3, 5], OH: [3, 6], PA: [3, 7], NJ: [3, 8], CT: [3, 9], RI: [3, 10],
+    CA: [4, 0], UT: [4, 1], CO: [4, 2], NE: [4, 3], MO: [4, 4], KY: [4, 5], WV: [4, 6], VA: [4, 7], MD: [4, 8], DE: [4, 9],
+    AZ: [5, 1], NM: [5, 2], KS: [5, 3], AR: [5, 4], TN: [5, 5], NC: [5, 6], SC: [5, 7], DC: [5, 8],
+    OK: [6, 3], LA: [6, 4], MS: [6, 5], AL: [6, 6], GA: [6, 7],
+    HI: [7, 0], TX: [7, 3], FL: [7, 8],
+};
+const US_TILEGRAM_COLS = 11;
+const US_TILEGRAM_ROWS = 8;
+/** Tint region tiles by the selected metric. */
+export function choroplethLayout(points, options) {
+    const { layout = 'us-tilegram', metric, cellSize = 34, gap = 4, columns = 6, levels = 5, rtl = false, } = options;
+    const step = cellSize + gap;
+    const valueOf = (p) => {
+        const v = p.values[metric];
+        return typeof v === 'number' && Number.isFinite(v) ? v : 0;
+    };
+    const maxValue = points.reduce((max, p) => Math.max(max, valueOf(p)), 0);
+    let placed;
+    let cols;
+    let rows;
+    if (layout === 'us-tilegram') {
+        cols = US_TILEGRAM_COLS;
+        rows = US_TILEGRAM_ROWS;
+        placed = [];
+        for (const point of points) {
+            const code = (point.code ?? '').toUpperCase();
+            const cell = US_TILEGRAM[code];
+            if (cell === undefined)
+                continue; // unknown code — geographic island only plots known tiles
+            placed.push({ point, row: cell[0], col: cell[1] });
+        }
+    }
+    else {
+        cols = Math.max(1, columns);
+        rows = Math.max(1, Math.ceil(points.length / cols));
+        placed = points.map((point, i) => ({ point, row: Math.floor(i / cols), col: i % cols }));
+    }
+    // Geographic tilegram never mirrors; the categorical grid mirrors columns.
+    const mirror = rtl && layout === 'grid';
+    const colX = (col) => (mirror ? cols - 1 - col : col) * step;
+    const tiles = placed.map(({ point, row, col }) => {
+        const value = valueOf(point);
+        const level = heatLevel(value, maxValue, levels);
+        const code = (point.code ?? '').toUpperCase();
+        return {
+            code,
+            name: point.name ?? code,
+            row,
+            col,
+            x: colX(col),
+            y: row * step,
+            size: cellSize,
+            value,
+            level,
+            colorVar: rampColorVar(level, levels),
+            textLight: heatTextLight(level, levels),
+        };
+    });
+    return {
+        tiles,
+        levels,
+        maxValue,
+        width: cols > 0 ? cols * step - gap : 0,
+        height: rows > 0 ? rows * step - gap : 0,
+    };
+}
+/**
+ * Whether any point carries a region code the US tilegram can actually place.
+ *
+ * The `us-tilegram` layout is a geographic island: it plots only the 50 states +
+ * DC it knows and silently drops every other code (the placement loop above). So
+ * a payload of non-US codes — or of coordinate-only points that carry no `code`
+ * at all — produces ZERO tiles there, leaving just the low→high legend: a legend
+ * for a map that is not on the page. Callers use this to fall back to the
+ * code-agnostic `grid` layout (which lays every point out in reading order,
+ * regardless of code) rather than render an empty board.
+ */
+export function hasUsTilegramTiles(points) {
+    return points.some((point) => US_TILEGRAM[(point.code ?? '').toUpperCase()] !== undefined);
+}
+//# sourceMappingURL=choropleth.js.map

package/dist/geometry/choropleth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"choropleth.js","sourceRoot":"","sources":["../../src/geometry/choropleth.ts"],"names":[],"mappings":"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"}

package/dist/geometry/cohort.d.ts

@@ -0,0 +1,54 @@
+export interface CohortCell {
+    row: number;
+    col: number;
+    x: number;
+    y: number;
+    size: number;
+    /** Cell value (e.g. retention %); null renders the triangular gap. */
+    value: number | null;
+    /** Sequential ramp level; -1 for null gaps. */
+    level: number;
+    /** Ramp color var(), or 'none' for null gaps. */
+    colorVar: string;
+    /** Whether the value label should use the on-accent color. */
+    textLight: boolean;
+}
+export interface CohortAxisLabel {
+    index: number;
+    /** Center coordinate along the axis (x for columns, y for rows). */
+    pos: number;
+    label: string;
+}
+export interface CohortLayout {
+    cells: CohortCell[];
+    rowLabels: CohortAxisLabel[];
+    colLabels: CohortAxisLabel[];
+    /** Total plotted width/height (grid + gutters/header). */
+    width: number;
+    height: number;
+    /** Inline-start x of the cohort label gutter text anchor edge. */
+    rowLabelX: number;
+    /** Text anchor for the cohort (row) labels given the direction. */
+    rowLabelAnchor: 'start' | 'end';
+}
+export interface CohortOptions {
+    cellSize?: number;
+    gap?: number;
+    /** Width reserved for cohort (row) labels. */
+    rowLabelWidth?: number;
+    /** Height reserved for the period (column) header. */
+    colLabelHeight?: number;
+    rtl?: boolean;
+    /** Value at/above which label text flips to the on-accent color. Default 55. */
+    flipThreshold?: number;
+    /** Number of ramp levels (incl. 0). Default 7 → viz-ramp-1..6. */
+    levels?: number;
+    /** Value that maps to the darkest ramp step. Default 100 (percent scale). */
+    maxValue?: number;
+}
+/**
+ * Lay out a (possibly triangular) cohort matrix. `cells[r][c]` is the value at
+ * cohort `r`, period `c`; `null`/`undefined` cells are transparent gaps.
+ */
+export declare function cohortLayout(rowKeys: readonly string[], colKeys: readonly string[], cells: readonly (readonly (number | null)[])[], options?: CohortOptions): CohortLayout;
+//# sourceMappingURL=cohort.d.ts.map

package/dist/geometry/cohort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cohort.d.ts","sourceRoot":"","sources":["../../src/geometry/cohort.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,0DAA0D;IAC1D,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,cAAc,EAAE,OAAO,GAAG,KAAK,CAAC;CACjC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sDAAsD;IACtD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,gFAAgF;IAChF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,KAAK,EAAE,SAAS,CAAC,SAAS,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC,EAAE,EAC9C,OAAO,GAAE,aAAkB,GAC1B,YAAY,CAkEd"}

package/dist/geometry/cohort.js

@@ -0,0 +1,70 @@
+/**
+ * Pure cohort-retention matrix geometry (research/widget-registry.md §2
+ * `chart-cohort-matrix`): cohort rows × period columns, accent alpha by value,
+ * triangular nulls transparent, label text flips to the on-accent color past a
+ * threshold (~55%). DOM-free and deterministic (workplan/04 §7.1) so the same
+ * SVG path/positions render in Node and the browser (acceptance #10).
+ *
+ * RTL policy (04 §7.4): the period columns are a horizontal categorical scale,
+ * so they mirror under `rtl` (rightmost = M0) with the cohort label gutter on
+ * the inline-start (physical right) side; the vertical cohort rows never move.
+ */
+import { heatLevel, rampColorVar } from './heat.js';
+/**
+ * Lay out a (possibly triangular) cohort matrix. `cells[r][c]` is the value at
+ * cohort `r`, period `c`; `null`/`undefined` cells are transparent gaps.
+ */
+export function cohortLayout(rowKeys, colKeys, cells, options = {}) {
+    const { cellSize = 40, gap = 3, rowLabelWidth = 72, colLabelHeight = 20, rtl = false, flipThreshold = 55, levels = 7, maxValue = 100, } = options;
+    const step = cellSize + gap;
+    const cols = colKeys.length;
+    const rows = rowKeys.length;
+    const gridWidth = cols > 0 ? cols * step - gap : 0;
+    const gridHeight = rows > 0 ? rows * step - gap : 0;
+    const width = rowLabelWidth + gridWidth;
+    const height = colLabelHeight + gridHeight;
+    // Column x within the grid area; mirrors the categorical order in RTL. The
+    // cohort label gutter sits on the inline-start (left in LTR, right in RTL).
+    const gridOriginX = rtl ? 0 : rowLabelWidth;
+    const colX = (col) => gridOriginX + (rtl ? cols - 1 - col : col) * step;
+    const out = [];
+    for (let r = 0; r < rows; r += 1) {
+        const rowCells = cells[r] ?? [];
+        for (let c = 0; c < cols; c += 1) {
+            const raw = rowCells[c];
+            const value = typeof raw === 'number' && Number.isFinite(raw) ? raw : null;
+            const level = value === null ? -1 : heatLevel(value, maxValue, levels);
+            out.push({
+                row: r,
+                col: c,
+                x: colX(c),
+                y: colLabelHeight + r * step,
+                size: cellSize,
+                value,
+                level,
+                colorVar: value === null ? 'none' : rampColorVar(level, levels),
+                textLight: value !== null && value >= flipThreshold,
+            });
+        }
+    }
+    const colLabels = colKeys.map((label, c) => ({
+        index: c,
+        pos: colX(c) + cellSize / 2,
+        label,
+    }));
+    const rowLabels = rowKeys.map((label, r) => ({
+        index: r,
+        pos: colLabelHeight + r * step + cellSize / 2,
+        label,
+    }));
+    return {
+        cells: out,
+        rowLabels,
+        colLabels,
+        width,
+        height,
+        rowLabelX: rtl ? gridWidth + 8 : rowLabelWidth - 8,
+        rowLabelAnchor: rtl ? 'start' : 'end',
+    };
+}
+//# sourceMappingURL=cohort.js.map

package/dist/geometry/cohort.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cohort.js","sourceRoot":"","sources":["../../src/geometry/cohort.ts"],"names":[],"mappings":"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"}