@ripple-ui/svelte 0.0.0-stage → 0.8.2

package/dist/widgets/data/heatmap-scale.js

@@ -0,0 +1,260 @@
+// widgets/data/heatmap-scale.ts: the pure half of the heatmap widget. `sanitize`
+// turns the model's cells into a row-major grid the view can trust, `scale`
+// assigns every value a colour class and builds the legend, and the rest sizes
+// cells, thins x labels and formats numbers. Heatmap.svelte draws the result as
+// a CSS grid of DOM cells. Nothing here touches the DOM; text widths come in as
+// a `Measure` so jsdom tests run without fonts.
+//
+// Sanitize: x/y go through plain(), so `**West**` is West and 2026 is
+// the column "2026". Explicit xLabels/yLabels set the order; categories found
+// only in cells are appended in first-seen order, never dropped or piled onto
+// index 0. A value goes through finite(); null, "n/a" or a missing value keeps
+// the position as "no data". The last numeric entry for a position wins. An
+// entry with no x or no y is counted in `skipped`; a non-object drops silently.
+//
+// Colour: sequential data (all >= 0 or all <= 0) gets five classes on equal bins
+// by magnitude; when the smallest magnitude is 0, zero is its own neutral class
+// and the five cover (0, max]. Data crossing zero gets seven classes symmetric
+// around 0 (edges at E/7, 3E/7, 5E/7 of E = max |v|), the negative arm warm.
+// HEAT is the percent of the hue mixed into --ripple-surface in light; HEAT_DARK
+// is the hue's alpha over whatever ground the card paints in dark, so cells and
+// the zero swatch climb from the same ground. status-text.test.ts measures them
+// against both inks, the card and the page ground, and keeps zero below step 1
+// and every ramp in order, so change them only with that test.
+//
+// Labels: x labels thin to every Nth column, N grown until the shown labels fit
+// whole (or a 120px box), and each sits centred on its own column, clamped to
+// the grid and to its left neighbour. Display figures use a true minus sign;
+// in cells, when any value is a fraction under 10, figures under 10 get a fixed
+// 2 decimals (`fixed2`). Legend ends and the readout never pad: 1, not 1.00.
+import { finite, num, plain } from '../data-kit/format.js';
+import { safeArray } from '../../utils/safe-props.js';
+export const HEAT = [32, 48, 64, 79, 94];
+export const HEAT_DARK = [28, 46, 62, 78, 94];
+/** HEAT indexes used by the three diverging classes on each arm. */
+export const DIV_STEPS = [0, 2, 4];
+/** Minimum x label pitch in px. */
+export const PITCH = 28;
+/** Widest x label box before a label ellipsizes instead of thinning further. */
+export const WIDE = 120;
+/** Least space between two x labels in px. */
+const LABEL_GAP = 6;
+/** Footnote line height in px (theme.css --lh-footnote). */
+export const LINE = 13;
+/** Least row height that holds an in-cell value: one footnote line, 4px above and below. */
+export const VALUE_H = LINE + 8;
+export const DEFAULT_HEIGHT = 280;
+/** Ordered, de-duplicated labels: explicit first, then first-seen extras. */
+function axis(explicit, seen) {
+    const out = new Set();
+    for (const l of safeArray(explicit)) {
+        const s = plain(l);
+        if (s)
+            out.add(s);
+    }
+    for (const s of seen)
+        out.add(s);
+    return [...out];
+}
+export function sanitize(cells, xLabels, yLabels) {
+    const seenX = [];
+    const seenY = [];
+    const entries = [];
+    let skipped = 0;
+    for (const e of safeArray(cells, { widget: 'heatmap', key: 'cells' })) {
+        if (!e || typeof e !== 'object')
+            continue;
+        const o = e;
+        const x = plain(o.x);
+        const y = plain(o.y);
+        if (!x || !y) {
+            skipped++;
+            continue;
+        }
+        seenX.push(x);
+        seenY.push(y);
+        entries.push({ x, y, v: finite(o.value) });
+    }
+    const xs = axis(xLabels, seenX);
+    const ys = axis(yLabels, seenY);
+    const xi = new Map(xs.map((s, i) => [s, i]));
+    const yi = new Map(ys.map((s, i) => [s, i]));
+    const values = ys.map(() => xs.map(() => undefined));
+    for (const { x, y, v } of entries)
+        if (v !== undefined)
+            values[yi.get(y)][xi.get(x)] = v;
+    return { xs, ys, values, skipped };
+}
+/** Every finite value with its position, in reading order. */
+export function spots(g) {
+    const out = [];
+    g.values.forEach((row, r) => row.forEach((v, c) => v !== undefined && out.push({ r, c, v })));
+    return out;
+}
+/** Lowest and highest value; ties go to the first in reading order. */
+export function extremes(g) {
+    const all = spots(g);
+    if (!all.length)
+        return undefined;
+    let lo = all[0];
+    let hi = all[0];
+    for (const s of all) {
+        if (s.v < lo.v)
+            lo = s;
+        if (s.v > hi.v)
+            hi = s;
+    }
+    return { lo, hi };
+}
+/** A display figure with a true minus sign (U+2212) in place of the hyphen. */
+export const minus = (s) => s.replace('-', '\u2212');
+/** Whether figures under 10 print a fixed 2 decimals: some value there is a fraction. */
+export function fixed2(g) {
+    return spots(g).some((s) => Math.abs(s.v) < 10 && !Number.isInteger(s.v));
+}
+/**
+ * Display figures: 2 decimals under 10 (in cells fixed with `fixed`, so a
+ * column of 0.30 and 1.00 lines up), 1 above, compact past 9,999, true minus.
+ * Legend ends and the readout pass no `fixed`, so an integer reads 1.
+ */
+export function fmt(v, fixed = false) {
+    if (fixed && Math.abs(v) < 10)
+        return minus(v.toFixed(2));
+    if (Number.isInteger(v))
+        return minus(Math.abs(v) > 9999 ? num(v, { compact: true }) : num(v, { digits: 0 }));
+    return minus(num(v, { digits: Math.abs(v) < 10 ? 2 : 1 }));
+}
+/** Full precision with a hyphen, for the hidden table; the readout wraps it in `minus`. */
+export function full(v) {
+    return num(v, { digits: 6 });
+}
+export function scale(g) {
+    const vals = spots(g).map((s) => s.v);
+    if (!vals.length)
+        return undefined;
+    const min = Math.min(...vals);
+    const max = Math.max(...vals);
+    const f = (v) => fmt(v);
+    if (min < 0 && max > 0) {
+        const E = Math.max(-min, max);
+        const tone = (v) => {
+            const a = Math.abs(v) / E;
+            if (a < 1 / 7)
+                return { arm: 'zero', step: 0 };
+            const k = a < 3 / 7 ? 0 : a < 5 / 7 ? 1 : 2;
+            return { arm: v < 0 ? 'warm' : 'accent', step: DIV_STEPS[k] };
+        };
+        const arm = (a) => DIV_STEPS.map((step) => ({ arm: a, step }));
+        return {
+            mode: 'div',
+            tone,
+            swatches: [...arm('warm').toReversed(), { arm: 'zero', step: 0, mark: '0' }, ...arm('accent')],
+            low: f(-E),
+            high: f(E)
+        };
+    }
+    // Sequential by magnitude, so all-negative data darkens away from zero too.
+    const neg = max <= 0 && min < 0;
+    const m = (v) => (neg ? -v : v);
+    const lo = neg ? -max : min;
+    const hi = neg ? -min : max;
+    const zero = lo === 0;
+    const tone = (v) => {
+        const a = m(v);
+        if (hi === lo)
+            return a === 0 ? { arm: 'zero', step: 0 } : { arm: 'accent', step: 2 };
+        if (zero)
+            return a === 0 ? { arm: 'zero', step: 0 } : { arm: 'accent', step: Math.min(4, Math.ceil((a / hi) * 5) - 1) };
+        return { arm: 'accent', step: Math.min(4, Math.floor(((a - lo) / (hi - lo)) * 5)) };
+    };
+    const ramp = HEAT.map((_, step) => ({ arm: 'accent', step }));
+    const sign = (n) => f(neg ? -n : n);
+    if (hi === lo)
+        return { mode: 'seq', tone, swatches: [tone(min)], low: sign(lo), high: '' };
+    return { mode: 'seq', tone, swatches: zero ? [{ arm: 'zero', step: 0 }, ...ramp] : ramp, low: sign(lo), high: sign(hi) };
+}
+/** `height` as a max body height: a number or "<n>px", clamped to [120, 640]. */
+export function maxHeight(v) {
+    const n = typeof v === 'string' ? finite(v.trim().replace(/px$/i, '')) : finite(v);
+    return n === undefined || n <= 0 ? DEFAULT_HEIGHT : Math.min(640, Math.max(120, n));
+}
+/** Preferred cell height: square under 12px (4px floor), else [12, 44]; 28px with values (fitHeight may shrink it to VALUE_H). */
+export function cellHeight(colW, withValues = false) {
+    const h = colW < 12 ? Math.max(4, colW) : Math.min(44, colW);
+    return withValues ? Math.max(28, h) : h;
+}
+/** 2px gaps, 1px once columns are under 10px wide. */
+export const gapFor = (colW) => (colW > 0 && colW < 10 ? 1 : 2);
+/**
+ * Which x labels show and where. Every Nth from the first, N the smallest that
+ * gives a PITCH px pitch, then grown (while two labels remain) until every shown
+ * label fits its N columns whole or the box reaches WIDE px. Each label box is
+ * `w` px wide, centred on its column (`dx` from that column's left edge), held
+ * inside the grid (`lead` px of y label column to the left) and 6px clear of
+ * the label before it. N also grows while that squeezes a label; past the
+ * limits a squeezed box ellipsizes. Unmeasured (colW 0): every label, laid out
+ * by CSS.
+ */
+export function thin(labels, colW, measure, lead = 0) {
+    const nc = labels.length;
+    if (colW <= 0)
+        return labels.map((_, i) => ({ i, w: 0, dx: 0 }));
+    const gap = gapFor(colW);
+    const pitch = colW + gap;
+    const room = (n) => n * pitch - gap;
+    const end = nc * pitch - gap;
+    // Lays out every Nth label; `squeezed` when one lost width to the grid edge or a neighbour.
+    const layout = (n) => {
+        const out = [];
+        let floor = -lead;
+        let squeezed = false;
+        for (let i = 0; i < nc; i += n) {
+            const want = Math.min(room(n), measure ? measure(labels[i]) + 4 : room(n));
+            const x = Math.max(floor, Math.min(i * pitch + colW / 2 - want / 2, end - want));
+            const w = Math.min(want, end - x);
+            if (w < want)
+                squeezed = true;
+            out.push({ i, w, dx: x - i * pitch });
+            floor = x + w + LABEL_GAP;
+        }
+        return { out, squeezed };
+    };
+    let n = Math.max(1, Math.ceil((PITCH + gap) / pitch));
+    if (measure) {
+        const need = (m) => Math.max(0, ...labels.filter((_, i) => i % m === 0).map(measure)) + 6;
+        while (n < Math.ceil(nc / 2) && (room(n) < Math.min(WIDE, need(n)) || layout(n).squeezed))
+            n++;
+    }
+    return layout(n).out;
+}
+/**
+ * Rows shrink toward a floor (VALUE_H with values, else 12px or the cell width)
+ * so the grid fits `room` px under the label row before the body scrolls.
+ */
+export function fitHeight(h, withValues, rows, gap, room) {
+    if (rows <= 0 || room <= 0)
+        return h;
+    const floor = withValues ? VALUE_H : Math.min(h, 12);
+    return Math.max(floor, Math.min(h, Math.floor((room + gap) / rows - gap)));
+}
+/** Whether `rows` fit `room` px at the VALUE_H in-cell value floor; if not, values drop so rows can shrink. */
+export function valueRowsFit(rows, gap, room) {
+    return room <= 0 || rows * (VALUE_H + gap) <= room + gap;
+}
+/** Y labels show every Nth row once the row pitch is under a label line, so N rows hold one line. */
+export function rowStep(cellH, gap) {
+    return cellH + gap >= LINE ? 1 : Math.ceil(LINE / (cellH + gap));
+}
+/**
+ * Whether in-cell values draw: `show` false never, true or auto when every
+ * value fits its cell with 4px padding (auto also needs 40px by 28px cells).
+ * All or nothing: one value that does not fit means none draw.
+ */
+export function valuesFit(g, colW, show, measure) {
+    if (show === false || colW <= 0 || !measure)
+        return false;
+    if (show !== true && (colW < 40 || cellHeight(colW, true) < 28))
+        return false;
+    const fixed = fixed2(g);
+    return spots(g).every((s) => measure(fmt(s.v, fixed)) <= colW - 8);
+}

package/dist/widgets/data/index.d.ts

@@ -0,0 +1,17 @@
+export { default as Table } from './Table.svelte';
+export { default as Chart } from './Chart.svelte';
+export { default as VirtualList } from './VirtualList.svelte';
+export { default as Tree } from './Tree.svelte';
+export { default as Kanban } from './Kanban.svelte';
+export { default as DataGrid } from './DataGrid.svelte';
+export { default as Sparkline } from './Sparkline.svelte';
+export { default as Gauge } from './Gauge.svelte';
+export { default as Funnel } from './Funnel.svelte';
+export { default as Heatmap } from './Heatmap.svelte';
+export { default as Sankey } from './Sankey.svelte';
+export { default as Treemap } from './Treemap.svelte';
+export { default as GanttChart } from './GanttChart.svelte';
+export { default as TreeTable } from './TreeTable.svelte';
+export { default as Calendar } from './Calendar.svelte';
+export { default as Map } from './Map.svelte';
+export { default as Seismograph } from './Seismograph.svelte';

package/dist/widgets/data/index.js

@@ -0,0 +1,18 @@
+export { default as Table } from './Table.svelte';
+export { default as Chart } from './Chart.svelte';
+export { default as VirtualList } from './VirtualList.svelte';
+export { default as Tree } from './Tree.svelte';
+export { default as Kanban } from './Kanban.svelte';
+export { default as DataGrid } from './DataGrid.svelte';
+export { default as Sparkline } from './Sparkline.svelte';
+export { default as Gauge } from './Gauge.svelte';
+export { default as Funnel } from './Funnel.svelte';
+export { default as Heatmap } from './Heatmap.svelte';
+export { default as Sankey } from './Sankey.svelte';
+export { default as Treemap } from './Treemap.svelte';
+export { default as GanttChart } from './GanttChart.svelte';
+export { default as TreeTable } from './TreeTable.svelte';
+export { default as Calendar } from './Calendar.svelte';
+export { default as Map } from './Map.svelte';
+// Console telemetry pack (feat/console-telemetry-widgets, 2026-06-13)
+export { default as Seismograph } from './Seismograph.svelte';

package/dist/widgets/data/kanban-board.d.ts

@@ -0,0 +1,39 @@
+export type KanbanColumn = {
+    id?: unknown;
+    title?: unknown;
+    color?: unknown;
+    accentClass?: unknown;
+};
+export type KanbanCard = Record<string, unknown>;
+export interface LaneItem {
+    card: KanbanCard;
+    /** Position in the original `value` array. */
+    index: number;
+}
+export interface Lane {
+    /** Unique render key. */
+    key: string;
+    /** The id a card moved here gets; undefined for `Other` (not a move target). */
+    id: string | undefined;
+    title: string;
+    other: boolean;
+    /** CSS colour for the dot, already tamed; undefined means no inline colour. */
+    dot: string | undefined;
+    /** Class for the dot (showcase `accentClass`). */
+    dotClass: string | undefined;
+    items: LaneItem[];
+}
+/** One lane id, case and separator blind. */
+export declare function norm(v: string): string;
+/** A lane title from a raw id: first letter upper-cased, `-`/`_` shown as spaces. */
+export declare function titleFromId(v: string): string;
+/** Display text from a string or finite number; anything else is ''. */
+export declare function text(v: unknown): string;
+/** The card's title through titleKey, then title/name/label/text; '' when none. */
+export declare function cardTitle(card: KanbanCard, titleKey: string): string;
+/** A lane colour as a CSS value: status words map to tokens, other valid colours are mixed toward the surface. */
+export declare function dotColour(v: unknown): string | undefined;
+/** Group cards into lanes (see the invariants above). */
+export declare function buildBoard(columns: unknown, cards: unknown, columnKey: string): Lane[];
+/** A new card array with only card `index` moved to lane `to`. */
+export declare function moveCard(cards: KanbanCard[], index: number, columnKey: string, to: string): KanbanCard[];

package/dist/widgets/data/kanban-board.js

@@ -0,0 +1,118 @@
+// widgets/data/kanban-board.ts: the pure half of the kanban widget. It turns
+// model-written columns and cards into lanes, reads card text, tames a lane
+// colour and performs a move. Nothing here throws or reads the DOM at module
+// top level, so it runs the same under SSR, jsdom and the browser.
+//
+// Invariants:
+// - Every card lands in exactly one lane. A card whose status matches no lane
+//   (or has none) goes to a trailing `Other` lane that exists only when it has
+//   cards. Lane counts always sum to the number of cards.
+// - Cards are identified by their index in `value`, never by `id`, so two
+//   cards sharing an id move independently.
+// - Status matching is case- and separator-blind: "In Progress",
+//   "in_progress" and "in-progress" are one lane.
+import { finite, plain } from '../data-kit/format.js';
+/** One lane id, case and separator blind. */
+export function norm(v) {
+    return v
+        .trim()
+        .toLowerCase()
+        .replace(/[\s_-]+/g, '-');
+}
+/** A lane title from a raw id: first letter upper-cased, `-`/`_` shown as spaces. */
+export function titleFromId(v) {
+    const s = v.replace(/[-_]+/g, ' ').trim();
+    return s.charAt(0).toUpperCase() + s.slice(1);
+}
+/** Display text from a string or finite number; anything else is ''. */
+export function text(v) {
+    if (typeof v === 'string')
+        return plain(v);
+    if (typeof v === 'number')
+        return finite(v) === undefined ? '' : String(v);
+    return '';
+}
+const TITLE_FALLBACKS = ['title', 'name', 'label', 'text'];
+/** The card's title through titleKey, then title/name/label/text; '' when none. */
+export function cardTitle(card, titleKey) {
+    for (const k of [titleKey, ...TITLE_FALLBACKS]) {
+        const t = text(card?.[k]);
+        if (t)
+            return t;
+    }
+    return '';
+}
+const STATUS_DOTS = {
+    green: 'success',
+    success: 'success',
+    done: 'success',
+    amber: 'warning',
+    yellow: 'warning',
+    orange: 'warning',
+    warning: 'warning',
+    red: 'error',
+    error: 'error',
+    danger: 'error',
+    blue: 'info',
+    info: 'info'
+};
+const NEUTRAL = new Set(['gray', 'grey', 'neutral']);
+const CSS_COLOUR = /^(#[0-9a-f]{3,8}|(rgba?|hsla?|hwb|lab|lch|oklab|oklch)\([\d\s.,%/+-]+\)|[a-z]{3,24})$/i;
+/** A lane colour as a CSS value: status words map to tokens, other valid colours are mixed toward the surface. */
+export function dotColour(v) {
+    if (typeof v !== 'string')
+        return undefined;
+    const c = v.trim();
+    const key = c.toLowerCase();
+    if (STATUS_DOTS[key])
+        return `var(--ripple-${STATUS_DOTS[key]})`;
+    if (NEUTRAL.has(key))
+        return 'var(--ripple-muted-foreground)';
+    if (!CSS_COLOUR.test(c))
+        return undefined;
+    if (typeof CSS !== 'undefined' && typeof CSS.supports === 'function' && !CSS.supports('color', c))
+        return undefined;
+    return `color-mix(in oklab, ${c} 75%, var(--ripple-surface))`;
+}
+function lane(key, id, title, col) {
+    const dotClass = typeof col?.accentClass === 'string' && col.accentClass.trim() ? col.accentClass : undefined;
+    return { key, id, title, other: false, dot: dotColour(col?.color), dotClass, items: [] };
+}
+/** Group cards into lanes (see the invariants above). */
+export function buildBoard(columns, cards, columnKey) {
+    const cols = (Array.isArray(columns) ? columns : []).filter((c) => c != null && typeof c === 'object' && !Array.isArray(c));
+    const list = Array.isArray(cards) ? cards : [];
+    const lanes = [];
+    const byId = new Map();
+    const derive = cols.length === 0;
+    cols.forEach((c, i) => {
+        const raw = typeof c.id === 'string' || typeof c.id === 'number' ? String(c.id) : '';
+        const title = text(c.title) || titleFromId(raw) || `Lane ${i + 1}`;
+        const l = lane(`c${i}`, raw, title, c);
+        lanes.push(l);
+        const n = norm(raw);
+        if (n && !byId.has(n))
+            byId.set(n, l);
+    });
+    const other = { ...lane('other', undefined, 'Other'), other: true };
+    list.forEach((card, index) => {
+        const c = (card != null && typeof card === 'object' ? card : {});
+        const raw = c[columnKey];
+        const status = typeof raw === 'string' || typeof raw === 'number' ? String(raw) : '';
+        const n = norm(status);
+        let target = n ? byId.get(n) : undefined;
+        if (!target && derive && n) {
+            target = lane(`d${lanes.length}`, status.trim(), titleFromId(status) || status);
+            lanes.push(target);
+            byId.set(n, target);
+        }
+        (target ?? other).items.push({ card: c, index });
+    });
+    if (other.items.length)
+        lanes.push(other);
+    return lanes;
+}
+/** A new card array with only card `index` moved to lane `to`. */
+export function moveCard(cards, index, columnKey, to) {
+    return cards.map((c, i) => (i === index ? { ...c, [columnKey]: to } : c));
+}

package/dist/widgets/data/map-labels.d.ts

@@ -0,0 +1,18 @@
+export type Side = 'below' | 'right' | 'left' | 'above';
+export interface Rect {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** A route segment in container pixels: x1, y1, x2, y2. */
+export type Seg = [number, number, number, number];
+/** The chip's box for a side, `gap` px from the pin centre (px, py). */
+export declare function labelRect(side: Side, px: number, py: number, w: number, h: number, gap: number): Rect;
+/** Does the segment pass through the rectangle (Liang-Barsky clip). */
+export declare function crosses([x1, y1, x2, y2]: Seg, r: Rect): boolean;
+/** The best side for a w x h chip on the pin at (px, py) in a frame of fw x fh. */
+export declare function pickSide(px: number, py: number, w: number, h: number, gap: number, frame: {
+    w: number;
+    h: number;
+}, blocked: readonly Rect[], segs: readonly Seg[]): Side;

package/dist/widgets/data/map-labels.js

@@ -0,0 +1,74 @@
+// widgets/data/map-labels.ts: which side of its pin a map label chip sits on.
+// Pure pixel geometry, so Map.svelte only measures and paints. A chip tries
+// below, right, left, above (in that order of preference) and takes the side
+// that keeps it inside the frame, off the Leaflet controls and other chips,
+// and off the drawn routes. Any clipping or covering loses to crossing a
+// route; ties keep the earlier side.
+const ORDER = ['below', 'right', 'left', 'above'];
+/** The chip's box for a side, `gap` px from the pin centre (px, py). */
+export function labelRect(side, px, py, w, h, gap) {
+    if (side === 'below')
+        return { x: px - w / 2, y: py + gap, w, h };
+    if (side === 'above')
+        return { x: px - w / 2, y: py - gap - h, w, h };
+    if (side === 'right')
+        return { x: px + gap, y: py - h / 2, w, h };
+    return { x: px - gap - w, y: py - h / 2, w, h };
+}
+function overlap(a, b) {
+    const w = Math.min(a.x + a.w, b.x + b.w) - Math.max(a.x, b.x);
+    const h = Math.min(a.y + a.h, b.y + b.h) - Math.max(a.y, b.y);
+    return w > 0 && h > 0 ? w * h : 0;
+}
+/** Does the segment pass through the rectangle (Liang-Barsky clip). */
+export function crosses([x1, y1, x2, y2], r) {
+    const dx = x2 - x1;
+    const dy = y2 - y1;
+    const p = [-dx, dx, -dy, dy];
+    const q = [x1 - r.x, r.x + r.w - x1, y1 - r.y, r.y + r.h - y1];
+    let t0 = 0;
+    let t1 = 1;
+    for (let i = 0; i < 4; i++) {
+        if (p[i] === 0) {
+            if (q[i] < 0)
+                return false;
+            continue;
+        }
+        const t = q[i] / p[i];
+        if (p[i] < 0) {
+            if (t > t1)
+                return false;
+            if (t > t0)
+                t0 = t;
+        }
+        else {
+            if (t < t0)
+                return false;
+            if (t < t1)
+                t1 = t;
+        }
+    }
+    return true;
+}
+/** The best side for a w x h chip on the pin at (px, py) in a frame of fw x fh. */
+export function pickSide(px, py, w, h, gap, frame, blocked, segs) {
+    const box = { x: 0, y: 0, w: frame.w, h: frame.h };
+    let best = 'below';
+    let bestScore = Infinity;
+    for (const side of ORDER) {
+        const r = labelRect(side, px, py, w, h, gap);
+        // Any clipped or covered pixel costs a whole chip, so it always loses
+        // to crossing a route (half a chip); more of it costs more.
+        const cost = (px2) => (px2 > 0 ? w * h + 4 * px2 : 0);
+        let score = cost(w * h - overlap(r, box));
+        for (const b of blocked)
+            score += cost(overlap(r, b));
+        if (segs.some((s) => crosses(s, r)))
+            score += (w * h) / 2;
+        if (score < bestScore) {
+            best = side;
+            bestScore = score;
+        }
+    }
+    return best;
+}

package/dist/widgets/data/sankey-layout.d.ts

@@ -0,0 +1,120 @@
+/** Band tint in % of the accent over the card: rest, by theme; focused; dimmed factor. */
+export declare const BAND: {
+    readonly light: 33;
+    readonly dark: 32;
+};
+export declare const LIT = 90;
+/** Remainder stub: % of the card's ink over the card, by theme (dark needs more to show). */
+export declare const STUB_INK: {
+    readonly light: 18;
+    readonly dark: 26;
+};
+/** The scroll fade's height; a plot that overflows its max by no more than this grows instead. */
+export declare const FADE = 24;
+export declare const DIM = 0.5;
+export declare const WIDE_MIN = 480;
+export declare const SSR_WIDTH = 640;
+export declare const LINE = 15;
+export declare const PAD_X = 6;
+export declare const H2: number;
+export declare const H1: number;
+export type Graph = {
+    nodes: {
+        name: string;
+    }[];
+    links: {
+        s: number;
+        t: number;
+        value: number;
+    }[];
+    dropped: {
+        value: number;
+        loop: number;
+        end: number;
+    };
+    unlinked: string[];
+};
+/** A positive flow from a number or a numeric string ("1,200"), else undefined. */
+export declare function flowValue(v: unknown): number | undefined;
+export declare function sanitize(rawNodes: unknown, rawLinks: unknown): Graph;
+export type Stats = {
+    inn: number[];
+    out: number[];
+    value: number[];
+    rem: number[];
+    total: number;
+    starts: number[];
+    ends: {
+        i: number;
+        value: number;
+    }[];
+    largestEnd: number;
+};
+export declare function stats(g: Graph): Stats;
+/** Figures on the plot: compact at 10,000 and up, grouped below. */
+export declare const fmt: (v: number) => string;
+/** Figures in the readout and accessible names: always whole. */
+export declare const full: (v: number) => string;
+export declare function pct(v: number, of: number): string;
+export declare function summary(g: Graph, st: Stats): string;
+export declare const nodeReadout: (g: Graph, st: Stats, i: number) => string;
+export declare const nodeName: (g: Graph, st: Stats, i: number) => string;
+export declare function linkReadout(g: Graph, st: Stats, k: number): string;
+export declare function restReadout(g: Graph, st: Stats): string;
+export declare function footnote(g: Graph): string;
+/** Max plot height: a number or numeric string, clamped to 160-720; else 320. */
+export declare function parseHeight(v: unknown): number;
+export declare function parseCurve(v: unknown): number;
+export type Rect = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+export type LNode = Rect & {
+    i: number;
+};
+export type LLink = {
+    k: number;
+    s: number;
+    t: number;
+    d: string;
+};
+export type LStub = {
+    i: number;
+    d: string;
+    box: Rect;
+};
+export type Label = Rect & {
+    key: string;
+    kind: 'node' | 'stub';
+    i: number;
+    /** 0 hidden, 1 one line, 2 name over figure, 3 name over value over percent. */
+    lines: 0 | 1 | 2 | 3;
+    align: 'start' | 'end';
+    /** The name as drawn ('' when a protected label keeps only its figure), or the remainder text. */
+    text: string;
+    /** The figure as drawn: `85 · 71%`, else `85`, else compact; never empty on a shown node label. */
+    fig: string;
+};
+export type Layout = {
+    vertical: boolean;
+    W: number;
+    H: number;
+    nodes: LNode[];
+    links: LLink[];
+    stubs: LStub[];
+    labels: Label[];
+};
+export type Measure = (text: string, bold?: boolean) => number;
+/** Text width at the callout size before (or without) a real measure: SSR and jsdom. */
+export declare const guess: Measure;
+/** Node label figure: `value · percent of the start total` (start nodes: the value alone). */
+export declare function nodeFigure(st: Stats, i: number): string;
+export declare function layout(g: Graph, st: Stats, o: {
+    width: number;
+    maxH: number;
+    vertical: boolean;
+    curve: number;
+    measure?: Measure;
+}): Layout;