@fundar/data-chart-telling 0.0.63 → 1.0.0

package/dist/layout/facet/FacetLayout.svelte.d.ts

@@ -1,10 +1,16 @@
 import type { FacetColumns, FacetMode, FacetNavLayout, Responsive, FacetCellSnippet, FacetIndicatorSnippet, FacetNavSnippet } from '../../types/layout/facet';
 import type { Accessor } from '../../types/plots/data/common';
-import type { MarginConfig } from '../../types/plots/props';
 declare function $$render<TRow extends Record<string, unknown>>(): {
     props: {
         data: TRow[];
-        by: Accessor<TRow, unknown>;
+        /** One facet per value, wrapped into `columns`. */
+        by?: Accessor<TRow, unknown>;
+        /** One facet row per value - with `cols`, a matrix. */
+        rows?: Accessor<TRow, unknown>;
+        /** One facet column per value - with `rows`, a matrix. */
+        cols?: Accessor<TRow, unknown>;
+        rowValues?: string[];
+        colValues?: string[];
         columns?: FacetColumns;
         values?: string[];
         gap?: number;
@@ -18,7 +24,7 @@ declare function $$render<TRow extends Record<string, unknown>>(): {
         width: number;
         height: number;
         cell: FacetCellSnippet<TRow>;
-        marginsForFacet?: (rows: TRow[]) => MarginConfig;
+        align?: boolean;
     };
     exports: {};
     bindings: "";

package/dist/layout/facet/axes.d.ts

@@ -0,0 +1,16 @@
+import type { FacetConfig, FacetEdges } from '../../types/layout/facet';
+import type { AxisChannelName } from '../../types/layout/mapping';
+/** How a facet cell draws its x/y axes: hidden, or with its title running vertically. */
+export type FacetAxesDisplay = Partial<Record<AxisChannelName, {
+    axisDisplay?: 'none';
+    labelOrientation?: 'vertical';
+}>>;
+/**
+ * Each facet cell's axis display from `facet.axes`: with `'outer'`, an axis
+ * every facet shares draws only on the grid's bottom (x) or left (y) edge,
+ * and a drawn y axis' title runs vertically beside it. A free axis of a
+ * wrapped facet has its own domain in each cell, so it always draws.
+ */
+export declare function buildFacetAxesDisplay<TRow extends Record<string, unknown>>(facet: FacetConfig<TRow>): (place: {
+    edges: FacetEdges;
+}) => FacetAxesDisplay | undefined;

package/dist/layout/facet/axes.js

@@ -0,0 +1,25 @@
+import { isFacetWrap } from './config';
+/**
+ * Each facet cell's axis display from `facet.axes`: with `'outer'`, an axis
+ * every facet shares draws only on the grid's bottom (x) or left (y) edge,
+ * and a drawn y axis' title runs vertically beside it. A free axis of a
+ * wrapped facet has its own domain in each cell, so it always draws.
+ */
+export function buildFacetAxesDisplay(facet) {
+    if (facet.axes !== 'outer')
+        return () => undefined;
+    const mode = facet.scales ?? 'shared';
+    const wrap = isFacetWrap(facet);
+    const shared = (axis) => !(wrap && (mode === 'free' || mode === `free-${axis}`));
+    return ({ edges }) => {
+        const out = {};
+        for (const axis of ['x', 'y']) {
+            const hidden = shared(axis) && !(axis === 'x' ? edges.bottom : edges.left);
+            if (hidden)
+                out[axis] = { axisDisplay: 'none' };
+            else if (axis === 'y')
+                out[axis] = { labelOrientation: 'vertical' };
+        }
+        return Object.keys(out).length ? out : undefined;
+    };
+}

package/dist/layout/facet/config.d.ts

@@ -0,0 +1,32 @@
+import type { FacetConfig, FacetWrapConfig } from '../../types/layout/facet';
+import type { FacetPanel } from '../../types/phases/facet/phase';
+import type { Accessor } from '../../types/plots/data/common';
+/** Whether a facet config wraps one facet per `by` value, rather than laying out a `rows`/`cols` grid. */
+export declare function isFacetWrap<TRow extends Record<string, unknown>>(facet: FacetConfig<TRow>): facet is FacetWrapConfig<TRow>;
+/** One `rows` × `cols` grid cell's rows. */
+export type FacetGridGroup<TRow> = {
+    rows: TRow[];
+    row?: string;
+    col?: string;
+};
+/** The key a `rows`/`cols` grid files a cell under. */
+export declare function facetGridKey(row: string | undefined, col: string | undefined): string;
+/** Rows split into `rows` × `cols` grid cells, keyed by {@link facetGridKey}; an unset accessor leaves its value `undefined`. */
+export declare function buildFacetGridGroups<TRow extends Record<string, unknown>>(data: TRow[], rows: Accessor<TRow, unknown> | undefined, cols: Accessor<TRow, unknown> | undefined): Map<string, FacetGridGroup<TRow>>;
+/** A facet's key for one row: its `by` value, or its `rows`/`cols` values as a {@link facetGridKey}. */
+export declare function buildFacetKeyOf<TRow extends Record<string, unknown>>(facet: FacetConfig<TRow>): (row: TRow) => string;
+/**
+ * Every panel a facet lays out over `data`, in layout order, with its rows:
+ * one per `by` value (narrowed and ordered by `values`), or one per
+ * non-empty `rows` x `cols` combination, row by row (narrowed and ordered by
+ * `rowValues`/`colValues`).
+ */
+export declare function buildFacetPanels<TRow extends Record<string, unknown>>(facet: FacetConfig<TRow>, data: TRow[]): (FacetPanel & {
+    rows: TRow[];
+})[];
+/** The key of the panel a facet cell shows: its `by` value, or its `rows`/`cols` values as a {@link facetGridKey}. */
+export declare function buildFacetPlaceKey<TRow extends Record<string, unknown>>(facet: FacetConfig<TRow>, place: {
+    facetValue: string;
+    row?: string;
+    col?: string;
+}): string;

package/dist/layout/facet/config.js

@@ -0,0 +1,82 @@
+import { resolveAccessor } from '../../plots/utils/accessors';
+/** Whether a facet config wraps one facet per `by` value, rather than laying out a `rows`/`cols` grid. */
+export function isFacetWrap(facet) {
+    return facet.by !== undefined;
+}
+/** The key a `rows`/`cols` grid files a cell under. */
+export function facetGridKey(row, col) {
+    return `${row ?? ''}\u0000${col ?? ''}`;
+}
+/** Rows split into `rows` × `cols` grid cells, keyed by {@link facetGridKey}; an unset accessor leaves its value `undefined`. */
+export function buildFacetGridGroups(data, rows, cols) {
+    const getRow = rows === undefined ? null : resolveAccessor(rows);
+    const getCol = cols === undefined ? null : resolveAccessor(cols);
+    const out = new Map();
+    for (const d of data) {
+        const row = getRow ? String(getRow(d)) : undefined;
+        const col = getCol ? String(getCol(d)) : undefined;
+        const key = facetGridKey(row, col);
+        const group = out.get(key);
+        if (group)
+            group.rows.push(d);
+        else
+            out.set(key, { rows: [d], row, col });
+    }
+    return out;
+}
+/** A facet's key for one row: its `by` value, or its `rows`/`cols` values as a {@link facetGridKey}. */
+export function buildFacetKeyOf(facet) {
+    if (isFacetWrap(facet)) {
+        const get = resolveAccessor(facet.by);
+        return (row) => String(get(row));
+    }
+    const getRow = facet.rows === undefined ? null : resolveAccessor(facet.rows);
+    const getCol = facet.cols === undefined ? null : resolveAccessor(facet.cols);
+    return (row) => facetGridKey(getRow ? String(getRow(row)) : undefined, getCol ? String(getCol(row)) : undefined);
+}
+/**
+ * Every panel a facet lays out over `data`, in layout order, with its rows:
+ * one per `by` value (narrowed and ordered by `values`), or one per
+ * non-empty `rows` x `cols` combination, row by row (narrowed and ordered by
+ * `rowValues`/`colValues`).
+ */
+export function buildFacetPanels(facet, data) {
+    if (isFacetWrap(facet)) {
+        const get = resolveAccessor(facet.by);
+        const groups = new Map();
+        for (const row of data) {
+            const key = String(get(row));
+            const bucket = groups.get(key);
+            if (bucket)
+                bucket.push(row);
+            else
+                groups.set(key, [row]);
+        }
+        const keys = facet.values ? facet.values.filter((v) => groups.has(v)) : [...groups.keys()];
+        return keys.map((key) => ({ key, label: key, rows: groups.get(key) }));
+    }
+    const groups = buildFacetGridGroups(data, facet.rows, facet.cols);
+    const distinct = (pick, given) => given ?? [...new Set([...groups.values()].map((g) => g[pick]))];
+    const rowKeys = distinct('row', facet.rowValues);
+    const colKeys = distinct('col', facet.colValues);
+    return rowKeys.flatMap((row) => colKeys.flatMap((col) => {
+        const key = facetGridKey(row, col);
+        const group = groups.get(key);
+        if (!group?.rows.length)
+            return [];
+        const label = row !== undefined && col !== undefined ? `${row} · ${col}` : (row ?? col ?? '');
+        return [
+            {
+                key,
+                label,
+                rows: group.rows,
+                ...(row !== undefined ? { row } : {}),
+                ...(col !== undefined ? { col } : {})
+            }
+        ];
+    }));
+}
+/** The key of the panel a facet cell shows: its `by` value, or its `rows`/`cols` values as a {@link facetGridKey}. */
+export function buildFacetPlaceKey(facet, place) {
+    return isFacetWrap(facet) ? place.facetValue : facetGridKey(place.row, place.col);
+}

package/dist/layout/figure/Figure.svelte

@@ -0,0 +1,177 @@
+<script lang="ts">
+	import FigureChrome from './FigureChrome.svelte';
+	import GridCell from '../grid/GridCell.svelte';
+	import LegendLayout from '../legend/LegendLayout.svelte';
+	import TimelinePlayer from '../timeline/TimelinePlayer.svelte';
+	import TimelineRule from '../timeline/TimelineRule.svelte';
+	import { TimelineState } from '../timeline/TimelineState.svelte';
+	import { GridCellsRegistry } from '../grid/GridCellsRegistry.svelte';
+	import {
+		getConfiguration,
+		configToCssVars,
+		cssVarsStyle
+	} from '../../configuration/config.svelte';
+	import { HoverState } from '../hover/HoverState.svelte';
+	import { LegendState } from '../legend/LegendState.svelte';
+	import type { HoverStrategy } from '../../types/layout/hover';
+	import type { FigureBoxProps, PlotChromeConfig } from '../../types/plots/props';
+	import type { PlotBoxSnippet } from '../../types/layout/figure';
+	import type { LegendSection } from '../../types/layout/legend';
+
+	/**
+	 * One figure - a plot or a `PlotComposer` - and everything around what it
+	 * draws. Its box: drawn straight inside a `Grid` (a composer's), it takes a
+	 * cell of its own - its `area`, an `inset` over it, or the next free one -
+	 * and is that cell's size; anywhere else, its own `width` and `height`.
+	 * Its shared stores: the hover store, unless an enclosing figure already
+	 * shares one, and its {@link LegendState}. And its chrome (title, legend,
+	 * caption...) around `body`, which gets the box that's left - or `body`
+	 * alone in a themed box when there's no chrome.
+	 *
+	 * Its timeline - a rule or a player bar - is the chrome's `timeline` block.
+	 *
+	 * Its legend: unset or `true`, the one its plots read as - what they
+	 * register on its `LegendState`; `false`, none; a list of sections,
+	 * exactly those; `{ items, sections, series, color... }`, the automatic one
+	 * with those added and the sections of each channel adjusted. A figure inside another (a composer's panel) leaves an unset
+	 * legend to the outer one, which reads every panel's plots.
+	 */
+	let {
+		width,
+		height,
+		area,
+		inset,
+		title,
+		subtitle,
+		caption,
+		header,
+		footer,
+		legend,
+		order,
+		hoverStrategy,
+		hoverSync,
+		timelineState,
+		body
+	}: PlotChromeConfig &
+		FigureBoxProps & {
+			hoverStrategy: HoverStrategy;
+			hoverSync: boolean;
+			/** The figure's timeline, made and watched by its plot or composer: shared with everything inside, and drawn here as a player bar when it is one. */
+			timelineState?: TimelineState | null;
+			body: PlotBoxSnippet;
+		} = $props();
+
+	const cfg = $derived(getConfiguration());
+	const grid = GridCellsRegistry.current();
+
+	const ownHover = HoverState.current() ? null : HoverState.provide();
+	$effect(() => {
+		if (!ownHover) return;
+		ownHover.strategy = hoverStrategy;
+		ownHover.sync = hoverSync;
+	});
+
+	// svelte-ignore state_referenced_locally
+	if (timelineState) TimelineState.provide(timelineState);
+	/** Whether the chrome draws the timeline: a rule or a player bar - one with controls to draw. */
+	const timelineShown = $derived(
+		!!timelineState &&
+			timelineState.enabled &&
+			timelineState.shown &&
+			(timelineState.type === 'rule' || timelineState.controls.length > 0)
+	);
+	/** A vertical rule sits beside the plot, as if the chrome's `order` had `'(plot, timeline)'`. */
+	const timelineBesidePlot = $derived(
+		timelineShown && timelineState!.type === 'rule' && timelineState!.orientation === 'vertical'
+	);
+
+	// Read once at setup: a figure that shows a legend of its own scopes its toggles - and what its plots register - to itself.
+	const outer = LegendState.current();
+	// svelte-ignore state_referenced_locally
+	const ownLegend = (legend !== undefined && legend !== false) || !outer;
+	const legendState = ownLegend ? LegendState.provide() : outer!;
+
+	/** What the figure adds to its automatic legend, when `legend` is `{ items, sections }`. */
+	const extension = $derived(
+		legend && typeof legend === 'object' && !Array.isArray(legend) ? legend : undefined
+	);
+
+	/** What the legend shows: the author's sections, the ones its plots read as (with `extension`), or none. */
+	const legendMode = $derived(
+		Array.isArray(legend)
+			? 'explicit'
+			: legend === false || (legend === undefined && !ownLegend)
+				? 'none'
+				: 'auto'
+	);
+	const sections = $derived(
+		legendMode === 'explicit'
+			? legendState.colorize(legend as LegendSection[])
+			: legendMode === 'auto'
+				? legendState.sections(extension)
+				: []
+	);
+
+	/**
+	 * Whether the figure draws chrome around its plot. A figure with an
+	 * automatic legend always does: its plots register what they draw after
+	 * they mount, and the legend that fills in then mustn't remount them.
+	 */
+	const hasChrome = $derived(
+		Boolean(title || subtitle || caption || header || footer) ||
+			timelineShown ||
+			legendMode === 'auto' ||
+			(legendMode === 'explicit' && sections.length > 0)
+	);
+</script>
+
+{#snippet legendSnippet()}
+	<LegendLayout {sections} />
+{/snippet}
+
+{#snippet timelineSnippet()}
+	{#if timelineState && timelineState.type === 'rule'}
+		<TimelineRule timeline={timelineState} />
+	{:else if timelineState && timelineState.steps.length > 1}
+		<TimelinePlayer timeline={timelineState} />
+	{/if}
+{/snippet}
+
+{#snippet frame(w: number, h: number)}
+	{#if hasChrome}
+		<FigureChrome
+			width={w}
+			height={h}
+			{title}
+			{subtitle}
+			{caption}
+			{header}
+			{footer}
+			{order}
+			legend={sections.length > 0 ? legendSnippet : undefined}
+			timeline={timelineShown ? timelineSnippet : undefined}
+			{timelineBesidePlot}
+			plot={body}
+		/>
+	{:else}
+		<!-- No chrome means no container to stamp the `--dct-*` vars that facet and timeline chrome read. -->
+		<div
+			style={cssVarsStyle(configToCssVars(cfg))}
+			style:font-family="var(--dct-font, inherit)"
+			style:width="{w}px"
+			style:height="{h}px"
+		>
+			{@render body({ width: w, height: h })}
+		</div>
+	{/if}
+{/snippet}
+
+{#if grid}
+	<GridCell class="dct-grid-cell--figure" {area} {inset}>
+		{#snippet children(cell)}
+			{@render frame(cell.width, cell.height)}
+		{/snippet}
+	</GridCell>
+{:else}
+	{@render frame(width ?? 0, height ?? 0)}
+{/if}

package/dist/layout/figure/Figure.svelte.d.ts

@@ -0,0 +1,14 @@
+import { TimelineState } from '../timeline/TimelineState.svelte';
+import type { HoverStrategy } from '../../types/layout/hover';
+import type { FigureBoxProps, PlotChromeConfig } from '../../types/plots/props';
+import type { PlotBoxSnippet } from '../../types/layout/figure';
+type $$ComponentProps = PlotChromeConfig & FigureBoxProps & {
+    hoverStrategy: HoverStrategy;
+    hoverSync: boolean;
+    /** The figure's timeline, made and watched by its plot or composer: shared with everything inside, and drawn here as a player bar when it is one. */
+    timelineState?: TimelineState | null;
+    body: PlotBoxSnippet;
+};
+declare const Figure: import("svelte").Component<$$ComponentProps, {}, "">;
+type Figure = ReturnType<typeof Figure>;
+export default Figure;