@fundar/data-chart-telling 0.0.64 → 1.0.0

package/dist/layout/grid/Grid.svelte

@@ -0,0 +1,194 @@
+<script lang="ts">
+	import { GridPlan } from './GridPlan';
+	import { GridCellsRegistry } from './GridCellsRegistry.svelte';
+	import type { GridCellLayout } from '../../types/layout/grid';
+	import { Tags } from './Tags';
+	import { HoverState } from '../hover/HoverState.svelte';
+	import type { Snippet } from 'svelte';
+	import type { ComposerTags } from '../../types/layout/composer';
+
+	/**
+	 * The grid both facets and composers lay their panels out on. `GridCell`
+	 * children register into it and get a pixel box: a named `area`, an
+	 * explicit `row`/`col`, or the next free slot of `columns`; `widths` and
+	 * `heights` weigh the tracks. `header` reserves a label row above every
+	 * cell; `colLabels`/`rowLabels` add a strip above the columns and beside
+	 * the rows. With `align`, the grid waits for every cell's plot to report
+	 * its margins, then sizes tracks so every plot area lines up. `tags`
+	 * labels the cells in order, and `scoped` gives each its own hover scope -
+	 * how a `PlotComposer` marks its panels.
+	 */
+	let {
+		width,
+		height,
+		columns,
+		rows,
+		areas,
+		widths,
+		heights,
+		gap = 12,
+		header = 0,
+		align = false,
+		colLabels,
+		rowLabels,
+		strip = 24,
+		tags,
+		scoped = false,
+		children
+	}: {
+		width: number;
+		height: number;
+		columns?: number;
+		/** At least this many rows, even when the last ones stay empty. */
+		rows?: number;
+		areas?: string[];
+		widths?: number[];
+		heights?: number[];
+		gap?: number;
+		header?: number;
+		align?: boolean;
+		colLabels?: string[];
+		rowLabels?: string[];
+		strip?: number;
+		/** Labels every cell without its own, in the order they register - see {@link Tags}. */
+		tags?: ComposerTags;
+		/** Whether each cell gives what it draws its own hover-scope id, under the one in scope here. */
+		scoped?: boolean;
+		children: Snippet;
+	} = $props();
+
+	const parentScope = HoverState.scope();
+	const tagSequence = $derived(tags === undefined ? undefined : new Tags(tags));
+	// The cells below register here; each is tagged and scoped by its registration order.
+	const grid = new GridCellsRegistry({
+		layouts: () => layouts,
+		header: () => header,
+		aligned: () => align,
+		tag: (index) => tagSequence?.at(index),
+		scope: (index) => {
+			if (!scoped) return undefined;
+			const parent = parentScope();
+			return parent ? `${parent}/panel-${index}` : `panel-${index}`;
+		}
+	});
+	grid.provide();
+
+	const resolved = $derived(grid.requests);
+	const slotted = $derived(resolved.filter((cell) => !cell.inset));
+
+	const plan = $derived(new GridPlan(slotted, { areas, columns, rows }));
+
+	const colStrip = $derived(colLabels?.length ? strip : 0);
+	const rowStrip = $derived(rowLabels?.length ? strip : 0);
+	const innerWidth = $derived(width - (rowStrip ? rowStrip + gap : 0));
+	const innerHeight = $derived(height - (colStrip ? colStrip + gap : 0));
+
+	const tracks = $derived(
+		plan.tracks({
+			width: innerWidth,
+			height: innerHeight,
+			gap,
+			header,
+			widths,
+			heights,
+			margins: align ? slotted.map((cell) => grid.alignment.settled[cell.id]) : undefined
+		})
+	);
+
+	/** The px size of `count` tracks from `from`, gaps between them included. */
+	const spanSize = (sizes: number[], from: number, count: number) =>
+		sizes.slice(from, from + count).reduce((a, b) => a + b, 0) + (count - 1) * gap;
+
+	const rowOffset = $derived(colStrip ? 2 : 1);
+
+	const layouts = $derived.by(() => {
+		const out: Record<string, GridCellLayout> = {};
+		slotted.forEach((cell, i) => {
+			const span = plan.spans[i];
+			out[cell.id] = {
+				gridRow: `${span.row + rowOffset} / span ${span.rowSpan}`,
+				gridColumn: `${span.col + 1} / span ${span.colSpan}`,
+				box: tracks.boxes[i],
+				edges: plan.edges[i]
+			};
+		});
+		for (const cell of resolved) {
+			if (!cell.inset) continue;
+			const area = cell.area && areas ? areaBox(cell.area) : null;
+			const box = area ?? { width: innerWidth, height: innerHeight };
+			out[cell.id] = {
+				gridRow: area ? area.gridRow : undefined,
+				gridColumn: area ? area.gridColumn : undefined,
+				box: {
+					width: Math.max(0, Math.floor(box.width * (cell.inset.right - cell.inset.left))),
+					height: Math.max(
+						0,
+						Math.floor(box.height * (cell.inset.top - cell.inset.bottom)) - header
+					)
+				},
+				edges: { top: true, right: true, bottom: true, left: true }
+			};
+		}
+		return out;
+	});
+
+	/** A named area's px box and CSS placement, for an inset floating over it. */
+	function areaBox(name: string) {
+		const span = plan.areaSpan(name) ?? { row: 0, col: 0, rowSpan: 1, colSpan: 1 };
+		return {
+			width: spanSize(tracks.colWidths, span.col, span.colSpan),
+			height: spanSize(tracks.rowHeights, span.row, span.rowSpan),
+			gridRow: `${span.row + rowOffset} / span ${span.rowSpan}`,
+			gridColumn: `${span.col + 1} / span ${span.colSpan}`
+		};
+	}
+</script>
+
+<div
+	class="dct-grid"
+	style:width="{width}px"
+	style:height="{height}px"
+	style:gap="{gap}px"
+	style:grid-template-columns="{tracks.colWidths.map((w) => `${w}px`).join(' ')}{rowStrip
+		? ` ${rowStrip}px`
+		: ''}"
+	style:grid-template-rows="{colStrip ? `${colStrip}px ` : ''}{tracks.rowHeights
+		.map((h) => `${h}px`)
+		.join(' ')}"
+>
+	{#each colLabels ?? [] as label, c (c)}
+		<div class="dct-grid__strip dct-grid__strip--col" style:grid-row="1" style:grid-column={c + 1}>
+			{label}
+		</div>
+	{/each}
+	{#each rowLabels ?? [] as label, r (r)}
+		<div
+			class="dct-grid__strip dct-grid__strip--row"
+			style:grid-row={r + rowOffset}
+			style:grid-column={plan.columns + 1}
+		>
+			{label}
+		</div>
+	{/each}
+	{@render children()}
+</div>
+
+<style>
+	.dct-grid {
+		position: relative;
+		display: grid;
+	}
+	.dct-grid__strip {
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		font-size: 0.85rem;
+		font-weight: 600;
+		opacity: 0.9;
+		overflow: hidden;
+		white-space: nowrap;
+	}
+	.dct-grid__strip--row {
+		writing-mode: vertical-rl;
+	}
+</style>

package/dist/layout/grid/Grid.svelte.d.ts

@@ -0,0 +1,26 @@
+import type { Snippet } from 'svelte';
+import type { ComposerTags } from '../../types/layout/composer';
+type $$ComponentProps = {
+    width: number;
+    height: number;
+    columns?: number;
+    /** At least this many rows, even when the last ones stay empty. */
+    rows?: number;
+    areas?: string[];
+    widths?: number[];
+    heights?: number[];
+    gap?: number;
+    header?: number;
+    align?: boolean;
+    colLabels?: string[];
+    rowLabels?: string[];
+    strip?: number;
+    /** Labels every cell without its own, in the order they register - see {@link Tags}. */
+    tags?: ComposerTags;
+    /** Whether each cell gives what it draws its own hover-scope id, under the one in scope here. */
+    scoped?: boolean;
+    children: Snippet;
+};
+declare const Grid: import("svelte").Component<$$ComponentProps, {}, "">;
+type Grid = ReturnType<typeof Grid>;
+export default Grid;

package/dist/layout/grid/GridAlignment.svelte.d.ts

@@ -0,0 +1,31 @@
+import type { Margins } from '../margins/Margins';
+/**
+ * How an aligned `Grid` collects the margins its cells' plots settle on. A
+ * report is kept once it moves by more than 1px, and `settled` only follows
+ * once reports stop changing for `delay` ms - a plot reports placeholder
+ * margins before svelteplot sizes its axes, and pinning those would freeze them.
+ */
+export declare class GridAlignment {
+    #private;
+    readonly delay: number;
+    constructor(delay?: number);
+    /** Each cell's settled margins, by cell id. */
+    get settled(): Record<string, Margins>;
+    /** Records the margins `cell`'s plot settled on. */
+    report(cell: string, margins: Margins): void;
+}
+/**
+ * One grid cell's part in aligning its grid: where the plot inside reports
+ * the margins it settled on, and the margins the grid pinned on it.
+ */
+export declare class CellAlignment {
+    #private;
+    constructor(report: (margins: Margins) => void, pinned: () => Margins | undefined);
+    /** The enclosing cell's alignment, or `null` outside a grid cell. Call during component init. */
+    static current(): CellAlignment | null;
+    /** Hands this alignment to the plot below. Call during component init. */
+    provide(): void;
+    report(margins: Margins): void;
+    /** The margins the grid pinned on this cell, once it aligned. */
+    get pinned(): Margins | undefined;
+}

package/dist/layout/grid/GridAlignment.svelte.js

@@ -0,0 +1,56 @@
+import { getContext, setContext } from 'svelte';
+const CELL_ALIGNMENT_KEY = Symbol('dct-cell-alignment');
+/**
+ * How an aligned `Grid` collects the margins its cells' plots settle on. A
+ * report is kept once it moves by more than 1px, and `settled` only follows
+ * once reports stop changing for `delay` ms - a plot reports placeholder
+ * margins before svelteplot sizes its axes, and pinning those would freeze them.
+ */
+export class GridAlignment {
+    delay;
+    #live = {};
+    #timer;
+    #settled = $state.raw({});
+    constructor(delay = 150) {
+        this.delay = delay;
+    }
+    /** Each cell's settled margins, by cell id. */
+    get settled() {
+        return this.#settled;
+    }
+    /** Records the margins `cell`'s plot settled on. */
+    report(cell, margins) {
+        if (margins.equals(this.#live[cell], 1))
+            return;
+        this.#live = { ...this.#live, [cell]: margins };
+        clearTimeout(this.#timer);
+        this.#timer = setTimeout(() => (this.#settled = this.#live), this.delay);
+    }
+}
+/**
+ * One grid cell's part in aligning its grid: where the plot inside reports
+ * the margins it settled on, and the margins the grid pinned on it.
+ */
+export class CellAlignment {
+    #report;
+    #pinned;
+    constructor(report, pinned) {
+        this.#report = report;
+        this.#pinned = pinned;
+    }
+    /** The enclosing cell's alignment, or `null` outside a grid cell. Call during component init. */
+    static current() {
+        return getContext(CELL_ALIGNMENT_KEY) ?? null;
+    }
+    /** Hands this alignment to the plot below. Call during component init. */
+    provide() {
+        setContext(CELL_ALIGNMENT_KEY, this);
+    }
+    report(margins) {
+        this.#report(margins);
+    }
+    /** The margins the grid pinned on this cell, once it aligned. */
+    get pinned() {
+        return this.#pinned();
+    }
+}

package/dist/layout/grid/GridCell.svelte

@@ -0,0 +1,141 @@
+<script lang="ts">
+	import { onDestroy, onMount } from 'svelte';
+	import { GridCellsRegistry } from './GridCellsRegistry.svelte';
+	import { CellAlignment } from './GridAlignment.svelte';
+	import { HoverState } from '../hover/HoverState.svelte';
+	import type { GridCellSnippet, GridInset } from '../../types/layout/grid';
+	import type { HTMLAttributes } from 'svelte/elements';
+
+	/**
+	 * One cell of a `Grid`: takes the slot it asks for (a named `area`,
+	 * an explicit `row`/`col`, or the next free one) and hands its box to
+	 * `children`. With `inset`, it floats over its area instead of taking a
+	 * slot. `label` fills the grid's `header` row above the cell - centered
+	 * like a facet title, or flush left like a panel tag (the grid's own tag
+	 * for the cell, when it tags them). In an aligned grid, the plot inside
+	 * reports its margins and gets the grid's pinned ones. Anything a figure
+	 * can't be drawn as on its own - a legend, a note - goes in one.
+	 */
+	let {
+		area,
+		row,
+		col,
+		rowSpan,
+		colSpan,
+		inset,
+		label,
+		labelKind = 'title',
+		class: className,
+		children,
+		...rest
+	}: {
+		area?: string;
+		row?: number;
+		col?: number;
+		rowSpan?: number;
+		colSpan?: number;
+		inset?: GridInset;
+		label?: string;
+		labelKind?: 'title' | 'tag';
+		class?: string;
+		children: GridCellSnippet;
+	} & Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'class'> = $props();
+
+	const grid = GridCellsRegistry.current();
+	if (!grid) console.warn('GridCell: render it inside a `Grid`.');
+
+	const id = grid?.register(() => ({ area, row, col, rowSpan, colSpan, inset }));
+	onDestroy(() => {
+		if (id) grid?.unregister(id);
+	});
+
+	const layout = $derived(id ? grid?.layout(id) : undefined);
+	const header = $derived(grid?.header ?? 0);
+	// Without a label of its own, the cell reads as the grid's tag for it.
+	const tag = $derived(id ? grid?.tagOf(id) : undefined);
+	const shownLabel = $derived(label ?? tag);
+	const shownKind = $derived(label === undefined && tag !== undefined ? 'tag' : labelKind);
+
+	const scope = id ? grid?.scopeOf(id) : undefined;
+	if (scope !== undefined) HoverState.provideScope(() => scope);
+	// What the cell draws is placed: a figure below it takes no cell of its own.
+	GridCellsRegistry.leave();
+
+	new CellAlignment(
+		(margins) => {
+			if (id) grid?.report(id, margins);
+		},
+		() => layout?.box.margins
+	).provide();
+
+	// Draw only once every sibling registered, so the plot's first render already sees its final box and edges.
+	let ready = $state(false);
+	onMount(() => {
+		ready = true;
+	});
+</script>
+
+<div
+	{...rest}
+	class={['dct-grid-cell', className]}
+	class:dct-grid-cell--inset={inset}
+	style:grid-row={layout?.gridRow}
+	style:grid-column={layout?.gridColumn}
+	style:left={inset ? `${inset.left * 100}%` : undefined}
+	style:top={inset ? `${(1 - inset.top) * 100}%` : undefined}
+	style:width={inset ? `${(inset.right - inset.left) * 100}%` : undefined}
+	style:height={inset ? `${(inset.top - inset.bottom) * 100}%` : undefined}
+>
+	{#if header > 0}
+		<div
+			class="dct-grid-cell__label"
+			class:dct-grid-cell__label--tag={shownKind === 'tag'}
+			style:height="{header}px"
+		>
+			{shownLabel ?? ''}
+		</div>
+	{/if}
+	{#if ready && layout && layout.box.width > 0 && layout.box.height > 0}
+		{#key JSON.stringify(layout.box.margins ?? null)}
+			{@render children({
+				width: layout.box.width,
+				height: layout.box.height,
+				margins: layout.box.margins,
+				edges: layout.edges
+			})}
+		{/key}
+	{/if}
+</div>
+
+<style>
+	.dct-grid-cell {
+		display: flex;
+		flex-direction: column;
+		min-width: 0;
+		min-height: 0;
+		overflow: hidden;
+	}
+	.dct-grid-cell--inset {
+		position: absolute;
+		z-index: 1;
+		background: var(--dct-cell-inset-bg, var(--dct-bg, Canvas));
+	}
+	.dct-grid-cell__label {
+		flex: 0 0 auto;
+		overflow: hidden;
+		white-space: nowrap;
+		text-overflow: ellipsis;
+		font-size: 0.85rem;
+		font-weight: 600;
+		text-align: center;
+		opacity: 0.9;
+	}
+	.dct-grid-cell__label--tag {
+		font-family: var(--dct-title-font, inherit);
+		font-size: var(--dct-cell-tag-size, 1rem);
+		font-weight: var(--dct-cell-tag-weight, 600);
+		line-height: 1.2;
+		text-align: start;
+		opacity: 1;
+	}
+</style>

package/dist/layout/grid/GridCell.svelte.d.ts

@@ -0,0 +1,17 @@
+import type { GridCellSnippet, GridInset } from '../../types/layout/grid';
+import type { HTMLAttributes } from 'svelte/elements';
+type $$ComponentProps = {
+    area?: string;
+    row?: number;
+    col?: number;
+    rowSpan?: number;
+    colSpan?: number;
+    inset?: GridInset;
+    label?: string;
+    labelKind?: 'title' | 'tag';
+    class?: string;
+    children: GridCellSnippet;
+} & Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'class'>;
+declare const GridCell: import("svelte").Component<$$ComponentProps, {}, "">;
+type GridCell = ReturnType<typeof GridCell>;
+export default GridCell;

package/dist/layout/grid/GridCellsRegistry.svelte.d.ts

@@ -0,0 +1,52 @@
+import { GridAlignment } from './GridAlignment.svelte';
+import type { Margins } from '../margins/Margins';
+import type { GridCellLayout, GridCellRequest } from '../../types/layout/grid';
+/** What a grid tells its cells, each read reactively. */
+export type GridCellsRegistryInputs = {
+    /** Each cell's layout by id, once the grid placed it. */
+    layouts: () => Record<string, GridCellLayout>;
+    /** Height reserved above every cell for its label. */
+    header: () => number;
+    /** Whether the grid lines its cells' plot areas up. */
+    aligned: () => boolean;
+    /** The tag a cell's label falls back to, by its registration order. */
+    tag: (index: number) => string | undefined;
+    /** The hover-scope id a cell gives what it draws, by its registration order. */
+    scope: (index: number) => string | undefined;
+};
+/**
+ * The cells of one `Grid`: each `GridCell` below registers here, with what
+ * it asks for, and reads back its layout, its label's tag and its hover
+ * scope. In an aligned grid, the plot inside each cell reports the margins
+ * it settled on into {@link alignment}. Create it in the `Grid` during
+ * component init and {@link provide} it.
+ */
+export declare class GridCellsRegistry {
+    #private;
+    /** The margins the cells' plots settled on, which an aligned grid lines up. */
+    readonly alignment: GridAlignment;
+    constructor(inputs: GridCellsRegistryInputs);
+    /** The enclosing grid's cells, or `null` outside a grid. Call during component init. */
+    static current(): GridCellsRegistry | null;
+    /** Marks what a grid cell draws as already placed: a figure below it takes no cell of its own. */
+    static leave(): void;
+    /** Hands these cells to the `GridCell`s below. Call during component init. */
+    provide(): void;
+    /** Every registered cell's request, with its id, in registration order. */
+    get requests(): (GridCellRequest & {
+        id: string;
+    })[];
+    /** Registers a cell (its request read reactively), returning its id. */
+    register(request: () => GridCellRequest): string;
+    unregister(id: string): void;
+    /** The cell's layout, or `undefined` before the grid placed it. */
+    layout(id: string): GridCellLayout | undefined;
+    /** Records the margins a cell's plot settled on - only an aligned grid listens. */
+    report(id: string, margins: Margins): void;
+    /** Height reserved above every cell for its label. */
+    get header(): number;
+    /** The tag a cell's label falls back to, when the grid tags its cells in order. */
+    tagOf(id: string): string | undefined;
+    /** The hover-scope id a cell gives what it draws, when the grid scopes them. */
+    scopeOf(id: string): string | undefined;
+}

package/dist/layout/grid/GridCellsRegistry.svelte.js

@@ -0,0 +1,70 @@
+import { getContext, setContext } from 'svelte';
+import { GridAlignment } from './GridAlignment.svelte';
+const GRID_KEY = Symbol('dct-grid');
+/**
+ * The cells of one `Grid`: each `GridCell` below registers here, with what
+ * it asks for, and reads back its layout, its label's tag and its hover
+ * scope. In an aligned grid, the plot inside each cell reports the margins
+ * it settled on into {@link alignment}. Create it in the `Grid` during
+ * component init and {@link provide} it.
+ */
+export class GridCellsRegistry {
+    /** The margins the cells' plots settled on, which an aligned grid lines up. */
+    alignment = new GridAlignment();
+    #inputs;
+    #cells = $state([]);
+    #next = 0;
+    constructor(inputs) {
+        this.#inputs = inputs;
+    }
+    /** The enclosing grid's cells, or `null` outside a grid. Call during component init. */
+    static current() {
+        return getContext(GRID_KEY) ?? null;
+    }
+    /** Marks what a grid cell draws as already placed: a figure below it takes no cell of its own. */
+    static leave() {
+        setContext(GRID_KEY, null);
+    }
+    /** Hands these cells to the `GridCell`s below. Call during component init. */
+    provide() {
+        setContext(GRID_KEY, this);
+    }
+    /** Every registered cell's request, with its id, in registration order. */
+    get requests() {
+        return this.#cells.map((cell) => ({ id: cell.id, ...cell.request() }));
+    }
+    /** Registers a cell (its request read reactively), returning its id. */
+    register(request) {
+        const id = `cell-${this.#next++}`;
+        this.#cells.push({ id, request });
+        return id;
+    }
+    unregister(id) {
+        this.#cells = this.#cells.filter((cell) => cell.id !== id);
+    }
+    /** The cell's layout, or `undefined` before the grid placed it. */
+    layout(id) {
+        return this.#inputs.layouts()[id];
+    }
+    /** Records the margins a cell's plot settled on - only an aligned grid listens. */
+    report(id, margins) {
+        if (this.#inputs.aligned())
+            this.alignment.report(id, margins);
+    }
+    /** Height reserved above every cell for its label. */
+    get header() {
+        return this.#inputs.header();
+    }
+    /** The tag a cell's label falls back to, when the grid tags its cells in order. */
+    tagOf(id) {
+        return this.#inputs.tag(GridCellsRegistry.#indexOf(id));
+    }
+    /** The hover-scope id a cell gives what it draws, when the grid scopes them. */
+    scopeOf(id) {
+        return this.#inputs.scope(GridCellsRegistry.#indexOf(id));
+    }
+    /** A cell's 0-based registration order - insets included. */
+    static #indexOf(id) {
+        return Number(id.slice('cell-'.length));
+    }
+}

package/dist/layout/grid/GridPlan.d.ts

@@ -0,0 +1,49 @@
+import { Margins } from '../margins/Margins';
+import type { CellBox, CellEdges, GridCellSpec, GridSpan } from '../../types/layout/grid';
+/**
+ * Where a grid's cells sit, without Svelte: each cell's slot - a named
+ * `area`'s box in `areas`, an explicit `row`/`col` of its own, or, in order,
+ * the next slot nothing claimed (adding rows as needed) - the grid's size,
+ * which sides of each cell face no other cell, and the pixel tracks for a
+ * box ({@link GridPlan.tracks}). Without `areas`, `columns` defaults to the
+ * smallest square that fits every cell.
+ */
+export declare class GridPlan {
+    #private;
+    readonly rows: number;
+    readonly columns: number;
+    /** Each cell's slot, in the order the cells came. */
+    readonly spans: GridSpan[];
+    constructor(cells: GridCellSpec[], options?: {
+        areas?: string[];
+        columns?: number;
+        /** At least this many rows, even when the last ones stay empty. */
+        rows?: number;
+    });
+    /** Which sides of each cell face no other cell - where an `'outer'` axis draws. */
+    get edges(): CellEdges[];
+    /** The slot a named area covers, or `null` when it isn't in `areas`. */
+    areaSpan(name: string): GridSpan | null;
+    /**
+     * Pixel tracks for a `width` x `height` box and every cell's box. Each
+     * track's panel share follows its weight (`widths`, `heights`). With
+     * `margins` (one per cell, all reported), every column takes the widest
+     * left margin among cells starting in it and the widest right among cells
+     * ending in it - rows likewise - and those margins are pinned on the
+     * cells, so every plot area lines up with its row and column. `header` is
+     * the height each row spends above its cells (a label).
+     */
+    tracks(args: {
+        width: number;
+        height: number;
+        gap: number;
+        header?: number;
+        widths?: number[];
+        heights?: number[];
+        margins?: (Margins | undefined)[];
+    }): {
+        colWidths: number[];
+        rowHeights: number[];
+        boxes: CellBox[];
+    };
+}