@fundar/data-chart-telling 0.0.64 → 1.1.0

package/dist/layout/scales/EdgeTicks.d.ts

@@ -0,0 +1,39 @@
+import type { AxisChannelName } from '../../types/layout/mapping';
+import type { AxisScale, EdgeTicksOptions } from '../../types/layout/scales';
+/** What {@link EdgeTicks.build} measures an axis with. */
+export type EdgeTicksInput = {
+    /** The axis measured: labels sit side by side along x, stacked along y. */
+    axis: AxisChannelName;
+    /** The axis' numeric values; their extent is the axis' domain. */
+    values: number[];
+    /** The axis' length in pixels. */
+    span: number;
+    /** The pixels between ticks the axis aims for, and the fewest ticks it takes. */
+    spacing: number;
+    min: number;
+    /** The tick labels' font size, in pixels. */
+    fontSize: number;
+    options: EdgeTicksOptions;
+};
+/**
+ * The ticks of a continuous axis: its nice ticks plus the data's first and
+ * last values, so a reader sees where the data starts and ends. When an edge
+ * tick lands too close to the nice tick next to it for both labels to fit,
+ * `options.collision` decides which gives way, or widens the axis instead.
+ */
+export declare class EdgeTicks {
+    /** The share of the font size one label character takes, on average. */
+    static readonly CHARACTER_WIDTH = 0.6;
+    /** The pixels left between two neighbouring labels. */
+    static readonly LABEL_GAP = 6;
+    /** A plot's `scales.<axis>.edgeTicks` over the configuration's `axis.edgeTicks.<axis>`. */
+    static resolve(option: AxisScale['edgeTicks'], configured: EdgeTicksOptions): EdgeTicksOptions;
+    /**
+     * The axis' ticks, and the domain it widens to when `'extend'` resolved a
+     * collision. `undefined` when edge ticks are off or the values span nothing.
+     */
+    static build({ axis, values, span, spacing, min, fontSize, options }: EdgeTicksInput): {
+        ticks: number[];
+        domain?: [number, number];
+    } | undefined;
+}

package/dist/layout/scales/EdgeTicks.js

@@ -0,0 +1,82 @@
+import { NiceTicks } from './NiceTicks';
+/**
+ * The ticks of a continuous axis: its nice ticks plus the data's first and
+ * last values, so a reader sees where the data starts and ends. When an edge
+ * tick lands too close to the nice tick next to it for both labels to fit,
+ * `options.collision` decides which gives way, or widens the axis instead.
+ */
+export class EdgeTicks {
+    /** The share of the font size one label character takes, on average. */
+    static CHARACTER_WIDTH = 0.6;
+    /** The pixels left between two neighbouring labels. */
+    static LABEL_GAP = 6;
+    /** A plot's `scales.<axis>.edgeTicks` over the configuration's `axis.edgeTicks.<axis>`. */
+    static resolve(option, configured) {
+        if (option === undefined)
+            return configured;
+        if (typeof option === 'boolean')
+            return { ...configured, enabled: option };
+        return { enabled: true, collision: option.collision ?? configured.collision };
+    }
+    /**
+     * The axis' ticks, and the domain it widens to when `'extend'` resolved a
+     * collision. `undefined` when edge ticks are off or the values span nothing.
+     */
+    static build({ axis, values, span, spacing, min, fontSize, options }) {
+        if (!options.enabled || values.length < 2)
+            return undefined;
+        const lo = Math.min(...values);
+        const hi = Math.max(...values);
+        if (!(hi > lo))
+            return undefined;
+        const count = NiceTicks.count(span, spacing, min);
+        // Whole-number values (years, counts) never get ticks between them.
+        const step = values.every(Number.isInteger)
+            ? Math.max(1, NiceTicks.step(lo, hi, count))
+            : NiceTicks.step(lo, hi, count);
+        const nice = NiceTicks.inRange(lo, hi, step);
+        if (!nice.length)
+            return { ticks: [lo, hi] };
+        const eps = step * 1e-6;
+        const pixels = (value) => ((value - lo) / (hi - lo)) * span;
+        // Side by side, two labels need half of each one's width; stacked, one line's height.
+        const labelWidth = (value) => String(value).length * fontSize * EdgeTicks.CHARACTER_WIDTH;
+        const room = (edge, neighbour) => axis === 'x' ? (labelWidth(edge) + labelWidth(neighbour)) / 2 : fontSize;
+        const crowds = (edge, neighbour) => Math.abs(pixels(edge) - pixels(neighbour)) < room(edge, neighbour) + EdgeTicks.LABEL_GAP;
+        const inner = [...nice];
+        const before = [];
+        const after = [];
+        let domainLo = lo;
+        let domainHi = hi;
+        const first = nice[0];
+        if (first - lo > eps) {
+            if (!crowds(lo, first))
+                before.push(lo);
+            else if (options.collision === 'drop-nice') {
+                before.push(lo);
+                inner.shift();
+            }
+            else if (options.collision === 'extend') {
+                domainLo = first - step;
+                before.push(domainLo);
+            }
+        }
+        const last = nice[nice.length - 1];
+        if (hi - last > eps) {
+            if (!crowds(hi, last))
+                after.push(hi);
+            else if (options.collision === 'drop-nice') {
+                after.push(hi);
+                if (inner[inner.length - 1] === last)
+                    inner.pop();
+            }
+            else if (options.collision === 'extend') {
+                domainHi = last + step;
+                after.push(domainHi);
+            }
+        }
+        const ticks = [...before, ...inner, ...after];
+        const widened = domainLo !== lo || domainHi !== hi;
+        return widened ? { ticks, domain: [domainLo, domainHi] } : { ticks };
+    }
+}

package/dist/layout/scales/NiceTicks.d.ts

@@ -0,0 +1,40 @@
+import type { AxisChannelName } from '../../types/layout/mapping';
+/**
+ * "Nice" (1/2/5×10ⁿ) tick steps and the domains they round to, compatible with
+ * d3-array's and reimplemented here to avoid depending on internals svelteplot
+ * itself pulls in (not one of our declared dependencies) - see
+ * https://d3js.org/d3-array/ticks.
+ */
+export declare class NiceTicks {
+    /**
+     * How far past a tick, as a share of the tick step, a domain still ends on
+     * it. Plain `Math.ceil`/`Math.floor` (what d3's `nice()` uses) has no
+     * tolerance: parts that add up to `100`, but come out `100.00000000000001`
+     * after summing or `100.2` after each was rounded at the source, round a
+     * full step further (`100` → `120`). 5% of the step catches that noise and
+     * lets a mark pass the last tick by a few pixels at most.
+     */
+    static readonly TOLERANCE = 0.05;
+    /** The pixels between ticks an axis aims for, along x and along y. */
+    static readonly SPACING: {
+        readonly x: 80;
+        readonly y: 50;
+    };
+    /** The step between nice ticks for an approximate `count` over `[start, stop]`. */
+    static step(start: number, stop: number, count: number): number;
+    /** Multiples of `step` covering `[start, stop]`, inclusive of either endpoint when it lands exactly on one. */
+    static inRange(start: number, stop: number, step: number): number[];
+    /** How many ticks fit `span` pixels at one per `spacing`, and at least `min`. */
+    static count(span: number, spacing: number, min: number): number;
+    /**
+     * `[lo, hi]` widened outward to the nearest nice step for about `count`
+     * ticks, like d3's `scale.nice(count)` - except a value within
+     * `tolerance × step` past a tick stays on it (see {@link NiceTicks.TOLERANCE}).
+     */
+    static domain(lo: number, hi: number, count?: number, tolerance?: number): [number, number];
+    /** {@link NiceTicks.domain} with as many ticks as fit `axis` in a plot of this size. */
+    static fit(size: {
+        width: number;
+        height: number;
+    }, axis: AxisChannelName, lo: number, hi: number, tolerance?: number): [number, number];
+}

package/dist/layout/scales/NiceTicks.js

@@ -0,0 +1,72 @@
+import { Margins } from '../margins/Margins';
+/**
+ * "Nice" (1/2/5×10ⁿ) tick steps and the domains they round to, compatible with
+ * d3-array's and reimplemented here to avoid depending on internals svelteplot
+ * itself pulls in (not one of our declared dependencies) - see
+ * https://d3js.org/d3-array/ticks.
+ */
+export class NiceTicks {
+    /**
+     * How far past a tick, as a share of the tick step, a domain still ends on
+     * it. Plain `Math.ceil`/`Math.floor` (what d3's `nice()` uses) has no
+     * tolerance: parts that add up to `100`, but come out `100.00000000000001`
+     * after summing or `100.2` after each was rounded at the source, round a
+     * full step further (`100` → `120`). 5% of the step catches that noise and
+     * lets a mark pass the last tick by a few pixels at most.
+     */
+    static TOLERANCE = 0.05;
+    /** The pixels between ticks an axis aims for, along x and along y. */
+    static SPACING = { x: 80, y: 50 };
+    /** The step between nice ticks for an approximate `count` over `[start, stop]`. */
+    static step(start, stop, count) {
+        const e10 = Math.sqrt(50);
+        const e5 = Math.sqrt(10);
+        const e2 = Math.sqrt(2);
+        const step0 = Math.abs(stop - start) / Math.max(0, count);
+        let step1 = 10 ** Math.floor(Math.log10(step0));
+        const error = step0 / step1;
+        if (error >= e10)
+            step1 *= 10;
+        else if (error >= e5)
+            step1 *= 5;
+        else if (error >= e2)
+            step1 *= 2;
+        return step1;
+    }
+    /** Multiples of `step` covering `[start, stop]`, inclusive of either endpoint when it lands exactly on one. */
+    static inRange(start, stop, step) {
+        if (!(step > 0) || !Number.isFinite(step))
+            return [];
+        const lo = Math.ceil(start / step);
+        const hi = Math.floor(stop / step);
+        const out = [];
+        for (let i = lo; i <= hi; i++)
+            out.push(i * step);
+        return out;
+    }
+    /** How many ticks fit `span` pixels at one per `spacing`, and at least `min`. */
+    static count(span, spacing, min) {
+        return Math.max(min, Math.round(span / spacing));
+    }
+    /**
+     * `[lo, hi]` widened outward to the nearest nice step for about `count`
+     * ticks, like d3's `scale.nice(count)` - except a value within
+     * `tolerance × step` past a tick stays on it (see {@link NiceTicks.TOLERANCE}).
+     */
+    static domain(lo, hi, count = 5, tolerance = NiceTicks.TOLERANCE) {
+        if (!(hi > lo))
+            return [lo, hi];
+        const step = NiceTicks.step(lo, hi, count);
+        const slack = step * tolerance;
+        const niceLo = Math.floor((lo + slack) / step) * step;
+        const niceHi = Math.ceil((hi - slack) / step) * step;
+        // `|| 0` turns a `-0` (a bound at zero, rounded toward it) into `0`, which an axis writes without a sign.
+        return [niceLo || 0, niceHi || 0];
+    }
+    /** {@link NiceTicks.domain} with as many ticks as fit `axis` in a plot of this size. */
+    static fit(size, axis, lo, hi, tolerance) {
+        const box = Margins.AXIS_ESTIMATE.contentBox(size.width, size.height);
+        const span = axis === 'x' ? box.width : box.height;
+        return NiceTicks.domain(lo, hi, NiceTicks.count(span, NiceTicks.SPACING[axis], 2), tolerance);
+    }
+}