@fundar/data-chart-telling 0.0.64 → 1.1.0

package/dist/layout/legend/SymbolSection.svelte

@@ -0,0 +1,31 @@
+<script lang="ts">
+	import DiscreteSection from './DiscreteSection.svelte';
+	import type {
+		DiscreteLegendSection,
+		LegendItemsLayout,
+		SymbolLegendSection
+	} from '../../types/layout/legend';
+
+	/**
+	 * A shape scale: each category next to its shape, drawn as a discrete
+	 * section's items - all in one color, and never toggling, since they name
+	 * categories rather than series.
+	 */
+	let {
+		section,
+		defaultItemsLayout
+	}: { section: SymbolLegendSection; defaultItemsLayout?: LegendItemsLayout } = $props();
+
+	const discrete = $derived<DiscreteLegendSection>({
+		type: 'discrete',
+		columns: section.columns,
+		layout: section.layout,
+		items: section.items.map((item) => ({
+			...item,
+			color: section.color ?? 'currentColor',
+			filled: section.filled ?? true
+		}))
+	});
+</script>
+
+<DiscreteSection section={discrete} {defaultItemsLayout} />

package/dist/layout/legend/SymbolSection.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { LegendItemsLayout, SymbolLegendSection } from '../../types/layout/legend';
+type $$ComponentProps = {
+    section: SymbolLegendSection;
+    defaultItemsLayout?: LegendItemsLayout;
+};
+declare const SymbolSection: import("svelte").Component<$$ComponentProps, {}, "">;
+type SymbolSection = ReturnType<typeof SymbolSection>;
+export default SymbolSection;

package/dist/layout/margins/Box.d.ts

@@ -0,0 +1,84 @@
+import { Margins } from './Margins';
+import type { PlotStylesConfig } from '../../types/configuration/styling';
+import type { BoxAnchors, BoxFlip } from '../../types/layout/box';
+/**
+ * A rectangle in pixels: where something sits (`x`, `y`, its top-left) and
+ * how big it is. Anything a plot lays out - a label, a tooltip, the plot's
+ * own area - can be one, measured from the DOM ({@link Box.of}) or off it
+ * ({@link Box.ofText}). Immutable: every operation returns a new one.
+ */
+export declare class Box {
+    #private;
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+    constructor(x: number, y: number, width: number, height: number);
+    /** A box of `width` x `height` at the origin. */
+    static size(width: number, height: number): Box;
+    /** A box from any rect-like reading, e.g. an element's `getBBox()`. */
+    static of(rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }): Box;
+    /**
+     * The box one line of `text` takes at `fontSize` in the configuration's
+     * font (`'inherit'` measures as sans-serif), measured off the DOM, on a
+     * canvas. Empty during SSR.
+     */
+    static ofText(text: string, fontSize: number, cfg: Pick<PlotStylesConfig, 'font'>): Box;
+    get left(): number;
+    get top(): number;
+    get right(): number;
+    get bottom(): number;
+    /** Whether the box has no area. */
+    get empty(): boolean;
+    /** How far this box reaches out from its origin (the point it sits around), in whole pixels. */
+    get reach(): Margins;
+    /** This box grown by `px` on every side. */
+    pad(px: number): Box;
+    /**
+     * This box placed beside `point` on `anchor`'s side per axis: `gap` px
+     * before or after it, or centred on it.
+     */
+    beside(point: {
+        x: number;
+        y: number;
+    }, anchor: BoxAnchors, gap?: {
+        x?: number;
+        y?: number;
+    }): Box;
+    /** How far this box reaches past `bounds` on each side, in whole pixels; an empty box reaches nowhere. */
+    overflow(bounds: Box): Margins;
+    /**
+     * This box placed next to `point`, `gap` px away, on its preferred side
+     * per axis (`anchor`), inside `within` with an `edge` px clearance: a side
+     * it doesn't fit on gives way to the centred position, then to the
+     * opposite side, and as a last resort it is pushed back inside.
+     */
+    placeNear(point: {
+        x: number;
+        y: number;
+    }, anchor: BoxAnchors, within: Box, { gap, edge }?: {
+        gap?: number | undefined;
+        edge?: number | undefined;
+    }): Box;
+    /**
+     * Which side of `point` this box goes on, per axis, to stay inside
+     * `within`: its preferred side `gap` px away, else the opposite one; a
+     * centred box shifts back inside instead. Returns the side and the offset
+     * from the point - for a label anchored at the point, like a text's
+     * `textAnchor`/`lineAnchor` and `dx`/`dy`. Measure the box off the DOM
+     * ({@link Box.ofText}): a reading of the rendered label would feed back
+     * into the layout it is placed in.
+     */
+    flipNear(point: {
+        x: number;
+        y: number;
+    }, anchor: BoxAnchors, within: Box, gap: {
+        x: number;
+        y: number;
+    }): BoxFlip;
+}

package/dist/layout/margins/Box.js

@@ -0,0 +1,138 @@
+import { Margins } from './Margins';
+/**
+ * A rectangle in pixels: where something sits (`x`, `y`, its top-left) and
+ * how big it is. Anything a plot lays out - a label, a tooltip, the plot's
+ * own area - can be one, measured from the DOM ({@link Box.of}) or off it
+ * ({@link Box.ofText}). Immutable: every operation returns a new one.
+ */
+export class Box {
+    x;
+    y;
+    width;
+    height;
+    static #canvas;
+    constructor(x, y, width, height) {
+        this.x = x;
+        this.y = y;
+        this.width = width;
+        this.height = height;
+    }
+    /** A box of `width` x `height` at the origin. */
+    static size(width, height) {
+        return new Box(0, 0, width, height);
+    }
+    /** A box from any rect-like reading, e.g. an element's `getBBox()`. */
+    static of(rect) {
+        return new Box(rect.x, rect.y, rect.width, rect.height);
+    }
+    /**
+     * The box one line of `text` takes at `fontSize` in the configuration's
+     * font (`'inherit'` measures as sans-serif), measured off the DOM, on a
+     * canvas. Empty during SSR.
+     */
+    static ofText(text, fontSize, cfg) {
+        if (Box.#canvas === undefined) {
+            Box.#canvas =
+                typeof document === 'undefined' ? null : document.createElement('canvas').getContext('2d');
+        }
+        const family = cfg.font === 'inherit' ? 'sans-serif' : cfg.font;
+        const canvas = Box.#canvas;
+        if (canvas)
+            canvas.font = `${fontSize}px ${family}`;
+        return Box.size(canvas?.measureText(text).width ?? 0, fontSize * 1.2);
+    }
+    get left() {
+        return this.x;
+    }
+    get top() {
+        return this.y;
+    }
+    get right() {
+        return this.x + this.width;
+    }
+    get bottom() {
+        return this.y + this.height;
+    }
+    /** Whether the box has no area. */
+    get empty() {
+        return this.width === 0 && this.height === 0;
+    }
+    /** How far this box reaches out from its origin (the point it sits around), in whole pixels. */
+    get reach() {
+        return this.overflow(Box.size(0, 0));
+    }
+    /** This box grown by `px` on every side. */
+    pad(px) {
+        return new Box(this.x - px, this.y - px, this.width + 2 * px, this.height + 2 * px);
+    }
+    /**
+     * This box placed beside `point` on `anchor`'s side per axis: `gap` px
+     * before or after it, or centred on it.
+     */
+    beside(point, anchor, gap = {}) {
+        const start = (pos, size, side, space) => side === 'before' ? pos - space - size : side === 'after' ? pos + space : pos - size / 2;
+        return new Box(start(point.x, this.width, anchor.x, gap.x ?? 0), start(point.y, this.height, anchor.y, gap.y ?? 0), this.width, this.height);
+    }
+    /** How far this box reaches past `bounds` on each side, in whole pixels; an empty box reaches nowhere. */
+    overflow(bounds) {
+        if (this.empty)
+            return Margins.ZERO;
+        return new Margins(Math.ceil(Math.max(0, bounds.top - this.top)), Math.ceil(Math.max(0, this.right - bounds.right)), Math.ceil(Math.max(0, this.bottom - bounds.bottom)), Math.ceil(Math.max(0, bounds.left - this.left)));
+    }
+    /**
+     * This box placed next to `point`, `gap` px away, on its preferred side
+     * per axis (`anchor`), inside `within` with an `edge` px clearance: a side
+     * it doesn't fit on gives way to the centred position, then to the
+     * opposite side, and as a last resort it is pushed back inside.
+     */
+    placeNear(point, anchor, within, { gap = 10, edge = 6 } = {}) {
+        const along = (pos, size, from, to, preferred) => {
+            const startAt = (side) => side === 'before' ? pos - gap - size : side === 'after' ? pos + gap : pos - size / 2;
+            const order = preferred === 'before'
+                ? ['before', 'middle', 'after']
+                : preferred === 'after'
+                    ? ['after', 'middle', 'before']
+                    : ['middle'];
+            for (const side of order) {
+                const start = startAt(side);
+                if (start >= from + edge && start + size <= to - edge)
+                    return start;
+            }
+            const last = startAt(order[order.length - 1]);
+            return Math.min(Math.max(last, from + edge), Math.max(from + edge, to - size - edge));
+        };
+        return new Box(along(point.x, this.width, within.left, within.right, anchor.x), along(point.y, this.height, within.top, within.bottom, anchor.y), this.width, this.height);
+    }
+    /**
+     * Which side of `point` this box goes on, per axis, to stay inside
+     * `within`: its preferred side `gap` px away, else the opposite one; a
+     * centred box shifts back inside instead. Returns the side and the offset
+     * from the point - for a label anchored at the point, like a text's
+     * `textAnchor`/`lineAnchor` and `dx`/`dy`. Measure the box off the DOM
+     * ({@link Box.ofText}): a reading of the rendered label would feed back
+     * into the layout it is placed in.
+     */
+    flipNear(point, anchor, within, gap) {
+        const along = (pos, size, from, to, side, space) => {
+            if (side === 'after') {
+                return pos + space + size > to
+                    ? { side: 'before', offset: -space }
+                    : { side, offset: space };
+            }
+            if (side === 'before') {
+                return pos - space - size < from
+                    ? { side: 'after', offset: space }
+                    : { side, offset: -space };
+            }
+            const half = size / 2;
+            if (pos - half < from)
+                return { side, offset: from + half - pos };
+            if (pos + half > to)
+                return { side, offset: to - (pos + half) };
+            return { side, offset: 0 };
+        };
+        const x = along(point.x, this.width, within.left, within.right, anchor.x, gap.x);
+        const y = along(point.y, this.height, within.top, within.bottom, anchor.y, gap.y);
+        return { anchor: { x: x.side, y: y.side }, dx: x.offset, dy: y.offset };
+    }
+}

package/dist/layout/margins/Margins.d.ts

@@ -0,0 +1,37 @@
+import { Box } from './Box';
+import type { MarginConfig, MarginSide } from '../../types/plots/props';
+/** A box's four sides, in pixels. Immutable: every operation returns a new one. */
+export declare class Margins {
+    readonly top: number;
+    readonly right: number;
+    readonly bottom: number;
+    readonly left: number;
+    static readonly SIDES: readonly MarginSide[];
+    static readonly ZERO: Margins;
+    /** What an axis plot's `'auto'` side reads as before svelteplot sizes its axes. */
+    static readonly AXIS_ESTIMATE: Margins;
+    /** What a map's `'auto'` side reads as: a small uniform gap, like an `inset` marker's own. */
+    static readonly GEO_ESTIMATE: Margins;
+    constructor(top: number, right: number, bottom: number, left: number);
+    /** Some sides, the rest `0`. */
+    static of(sides: Partial<Record<MarginSide, number>>): Margins;
+    /** Every side `value`. */
+    static uniform(value: number): Margins;
+    /** Half of each dimension: how far something inside a `width` x `height` box may reach out. */
+    static half(width: number, height: number): Margins;
+    /** A margin config as numbers: a side that is `'auto'` or unset reads as `estimate`'s. */
+    static resolve(config: MarginConfig | undefined, estimate?: Margins): Margins;
+    /** Each side through `fn`. */
+    map(fn: (value: number, side: MarginSide) => number): Margins;
+    max(other: Margins): Margins;
+    min(other: Margins): Margins;
+    plus(other: Margins): Margins;
+    /** Whether every side is within `tolerance` px of `other`'s. */
+    equals(other: Margins | undefined, tolerance?: number): boolean;
+    /** Whether every side is `0` or less. */
+    get empty(): boolean;
+    /** The box these margins leave inside a `width` x `height` one. */
+    contentBox(width: number, height: number): Box;
+    /** The sides as a plain object - what svelteplot and `JSON` read. */
+    toJSON(): Record<MarginSide, number>;
+}

package/dist/layout/margins/Margins.js

@@ -0,0 +1,71 @@
+import { Box } from './Box';
+/** A box's four sides, in pixels. Immutable: every operation returns a new one. */
+export class Margins {
+    top;
+    right;
+    bottom;
+    left;
+    static SIDES = ['top', 'right', 'bottom', 'left'];
+    static ZERO = new Margins(0, 0, 0, 0);
+    /** What an axis plot's `'auto'` side reads as before svelteplot sizes its axes. */
+    static AXIS_ESTIMATE = new Margins(20, 20, 30, 40);
+    /** What a map's `'auto'` side reads as: a small uniform gap, like an `inset` marker's own. */
+    static GEO_ESTIMATE = new Margins(8, 8, 8, 8);
+    constructor(top, right, bottom, left) {
+        this.top = top;
+        this.right = right;
+        this.bottom = bottom;
+        this.left = left;
+    }
+    /** Some sides, the rest `0`. */
+    static of(sides) {
+        return new Margins(sides.top ?? 0, sides.right ?? 0, sides.bottom ?? 0, sides.left ?? 0);
+    }
+    /** Every side `value`. */
+    static uniform(value) {
+        return new Margins(value, value, value, value);
+    }
+    /** Half of each dimension: how far something inside a `width` x `height` box may reach out. */
+    static half(width, height) {
+        const w = Math.max(0, width / 2);
+        const h = Math.max(0, height / 2);
+        return new Margins(h, w, h, w);
+    }
+    /** A margin config as numbers: a side that is `'auto'` or unset reads as `estimate`'s. */
+    static resolve(config, estimate = Margins.AXIS_ESTIMATE) {
+        return estimate.map((fallback, side) => {
+            const value = config?.[side];
+            return typeof value === 'number' ? value : fallback;
+        });
+    }
+    /** Each side through `fn`. */
+    map(fn) {
+        return new Margins(fn(this.top, 'top'), fn(this.right, 'right'), fn(this.bottom, 'bottom'), fn(this.left, 'left'));
+    }
+    max(other) {
+        return this.map((value, side) => Math.max(value, other[side]));
+    }
+    min(other) {
+        return this.map((value, side) => Math.min(value, other[side]));
+    }
+    plus(other) {
+        return this.map((value, side) => value + other[side]);
+    }
+    /** Whether every side is within `tolerance` px of `other`'s. */
+    equals(other, tolerance = 0) {
+        return (other != null &&
+            Margins.SIDES.every((side) => Math.abs(this[side] - other[side]) <= tolerance));
+    }
+    /** Whether every side is `0` or less. */
+    get empty() {
+        return Margins.SIDES.every((side) => this[side] <= 0);
+    }
+    /** The box these margins leave inside a `width` x `height` one. */
+    contentBox(width, height) {
+        return new Box(this.left, this.top, Math.max(0, width - this.left - this.right), Math.max(0, height - this.top - this.bottom));
+    }
+    /** The sides as a plain object - what svelteplot and `JSON` read. */
+    toJSON() {
+        return { top: this.top, right: this.right, bottom: this.bottom, left: this.left };
+    }
+}

package/dist/layout/margins/PlotMargins.svelte.d.ts

@@ -0,0 +1,101 @@
+import { Margins } from './Margins';
+import { Box } from './Box';
+import type { MarginConfig } from '../../types/plots/props';
+import type { BoxAnchors, EdgeBox } from '../../types/layout/box';
+import type { AxisScale } from '../../types/layout/scales';
+import type { AxisChannelName } from '../../types/layout/mapping';
+/** What a plot's margins are built from, each read reactively. */
+export type PlotMarginsInputs = {
+    /** The theme's margins. */
+    theme: () => MarginConfig;
+    /** The author's `margins`: a side set here is theirs, and never grows. */
+    author: () => MarginConfig | undefined;
+    /** What an `'auto'` side reads as, for the plot's own numbers. */
+    estimate: () => Margins;
+    /**
+     * Boxes the plot expects around points on its edges - its labels, before
+     * they render: how far each reaches past its edges is where growth starts,
+     * so they fit from the first render.
+     */
+    reserve: () => EdgeBox[];
+    /** The plot's box: labels never reach out more than half of it. */
+    size: () => {
+        width: number;
+        height: number;
+    };
+    /** Growth resets to what `reserve` keeps whenever this changes (by identity). */
+    resetKey: () => unknown;
+    /** The plot's scales: an axis whose tick labels rotate (`tickRotate`) takes more or less room on its side. */
+    scales: () => Partial<Record<AxisChannelName, Pick<AxisScale, 'tickRotate'>>> | undefined;
+    /** The tick labels' font size. */
+    tickFontSize: () => number;
+    /** Receives the margins the labels settled on - the plot's bindable `margins`. */
+    settle?: (margins: MarginConfig) => void;
+};
+/**
+ * One plot's margins: the theme's, then the author's, then the room its
+ * labels reach out into (grown on every side the author left open), then the
+ * room rotated tick labels take or give back, and last the margins an aligned grid pinned on
+ * it. The plot's markers hand it what they draw to measure ({@link watch});
+ * it follows what svelteplot settles on ({@link follow}), for its grid. Its {@link box} and {@link contentBox} are the plot's box and
+ * area for any consumer, and {@link place} fits something of a given size
+ * next to a point inside the box.
+ *
+ * The margins the labels settled on go back out through `settle`; read back
+ * in as `author`, they hold as a minimum instead of fixing their sides.
+ * Create it during component init: it registers itself for the plot's
+ * markers ({@link PlotMargins.current}).
+ */
+export declare class PlotMargins {
+    #private;
+    constructor(inputs: PlotMarginsInputs);
+    /** The plot's margins, or `null` outside a plot. Call during component init. */
+    static current(): PlotMargins | null;
+    /**
+     * Measures `el`'s rendered box once its readings settle - again whenever
+     * the content box or `deps` change - and reports how far it reaches past
+     * the content box: to `onOverflow`, and, when `grow` holds, into the room
+     * the margins grow by. Call during component init.
+     */
+    watch(el: () => SVGGraphicsElement | undefined, options: {
+        grow?: () => boolean;
+        onOverflow?: (overflow: Margins) => void;
+        deps?: () => unknown;
+    }): void;
+    /** Grows the labels' room to fit what reached `overflow` px past the content box. */
+    reportOverflow(overflow: Margins): void;
+    /**
+     * Follows the margins svelteplot settles on - `plot` is its `usePlot()`,
+     * only readable inside its `<Plot>` - and reports them to the enclosing
+     * aligned grid cell, if any. Call during the init of a component inside it.
+     */
+    follow(plot: {
+        options: Record<string, unknown>;
+    }): void;
+    /** What svelteplot's `<Plot margin>` takes. */
+    readonly config: Partial<{
+        top: number | "auto";
+        right: number | "auto";
+        bottom: number | "auto";
+        left: number | "auto";
+    }>;
+    /** {@link config} as numbers, an `'auto'` side read as the plot's estimate. */
+    readonly numeric: Margins;
+    /** The plot's whole box, in pixels. */
+    readonly box: Box;
+    /** The plot's own area, in pixels: what its margins leave inside its box. */
+    readonly contentBox: Box;
+    /**
+     * Where something of `size` sits next to `point`, on its preferred side
+     * per axis, without leaving the plot's box - see {@link Box.placeNear}.
+     */
+    place(size: Box, point: {
+        x: number;
+        y: number;
+    }, anchor: BoxAnchors): Box;
+    /**
+     * Changes whenever the labels' margins move after mount, which svelteplot
+     * only takes on a remount. The same margins read back from `settle` keep it.
+     */
+    readonly remountKey: string;
+}