@scalewing/react 1.38.0 → 1.39.0

package/dist/line-chart-input.d.ts

@@ -0,0 +1,39 @@
+import { type ChartStrokeTone } from './css/chart-tones.js';
+import { type LineChartCurve } from './line-chart-path.js';
+/** A value on a date (`YYYY-MM-DD`). */
+export type LineChartPoint = {
+    x: string;
+    y: number;
+};
+/** A downward triangle on the line at one of its points' dates, with words. */
+export type LineChartMarker = {
+    x: string;
+    label: string;
+    tone: ChartStrokeTone;
+};
+/** A period to box, from its first date to its last. */
+export type LineChartPeriod = {
+    from: string;
+    to: string;
+};
+export type LineChartInput = {
+    label: string;
+    valueLabel?: string;
+    points: readonly LineChartPoint[];
+    curve: LineChartCurve;
+    tone: ChartStrokeTone;
+    markers: readonly LineChartMarker[];
+    markersLabel?: string;
+    ticks?: readonly string[];
+    highlight?: LineChartPeriod;
+};
+/** A date's day count, or a refusal naming what it was. */
+export declare function lineChartDay(what: string, value: string): number;
+/**
+ * Refuses what a line chart cannot draw, with a `RangeError`: empty words,
+ * a date that is not `YYYY-MM-DD`, points out of date order, a value that
+ * is not finite, an unknown curve or tone, a marker off the points' dates
+ * or markers without `markersLabel`, a tick outside the points' dates, and
+ * a period that ends before it starts.
+ */
+export declare function assertLineChartInput(input: LineChartInput): void;

package/dist/line-chart-input.js

@@ -0,0 +1,70 @@
+import { dayNumber } from './chart-dates.js';
+import { chartStrokeTones } from './css/chart-tones.js';
+import { isOneOf } from './is-one-of.js';
+import { lineChartCurves } from './line-chart-path.js';
+function refuse(message) {
+    throw new RangeError(`LineChart ${message}`);
+}
+function assertWords(what, value) {
+    if (typeof value !== 'string' || value.trim() === '')
+        refuse(`${what} must not be empty`);
+}
+/** A date's day count, or a refusal naming what it was. */
+export function lineChartDay(what, value) {
+    const day = typeof value === 'string' ? dayNumber(value) : null;
+    if (day === null)
+        refuse(`${what} must be a YYYY-MM-DD date: ${String(value)}`);
+    return day;
+}
+function assertTone(what, tone) {
+    if (!isOneOf(chartStrokeTones, tone))
+        refuse(`${what} must be one of ${chartStrokeTones.join(', ')}; received ${String(tone)}`);
+}
+/**
+ * Refuses what a line chart cannot draw, with a `RangeError`: empty words,
+ * a date that is not `YYYY-MM-DD`, points out of date order, a value that
+ * is not finite, an unknown curve or tone, a marker off the points' dates
+ * or markers without `markersLabel`, a tick outside the points' dates, and
+ * a period that ends before it starts.
+ */
+export function assertLineChartInput(input) {
+    assertWords('label', input.label);
+    if (input.valueLabel !== undefined)
+        assertWords('valueLabel', input.valueLabel);
+    if (!isOneOf(lineChartCurves, input.curve))
+        refuse(`curve must be one of ${lineChartCurves.join(', ')}; received ${String(input.curve)}`);
+    assertTone('tone', input.tone);
+    let previous = -Infinity;
+    for (const point of input.points) {
+        const day = lineChartDay('point x', point.x);
+        if (day < previous)
+            refuse(`points must be in date order: ${point.x} comes after a later date`);
+        previous = day;
+        if (typeof point.y !== 'number' || !Number.isFinite(point.y))
+            refuse(`point y must be a finite number: ${String(point.y)}`);
+    }
+    const dates = new Set(input.points.map((point) => point.x));
+    if (input.markers.length > 0)
+        assertWords('markersLabel', input.markersLabel);
+    for (const marker of input.markers) {
+        if (!dates.has(marker.x))
+            refuse(`marker x must be one of the points' dates: ${String(marker.x)}`);
+        assertWords('marker label', marker.label);
+        assertTone('marker tone', marker.tone);
+    }
+    const first = input.points[0]?.x;
+    const last = input.points.at(-1)?.x;
+    for (const tick of input.ticks ?? []) {
+        const day = lineChartDay('tick', tick);
+        if (first === undefined ||
+            day < lineChartDay('point x', first) ||
+            day > lineChartDay('point x', last))
+            refuse(`tick must fall within the points' dates: ${tick}`);
+    }
+    if (input.highlight) {
+        const from = lineChartDay('highlight from', input.highlight.from);
+        const to = lineChartDay('highlight to', input.highlight.to);
+        if (to < from)
+            refuse('highlight must not end before it starts');
+    }
+}

package/dist/line-chart-layout.d.ts

@@ -0,0 +1,68 @@
+import { type ChartPlot, type ChartTick } from './chart-axis.js';
+import { type PlacedMarker } from './line-chart-markers.js';
+import { type ChartPoint, type LineChartCurve } from './line-chart-path.js';
+export type LineChartLayoutInput = {
+    width: number;
+    /** The points as day counts, in date order. */
+    points: readonly {
+        day: number;
+        y: number;
+    }[];
+    curve: LineChartCurve;
+    area: boolean;
+    /** Each marker's day (one of the points') and words. */
+    markers: readonly {
+        day: number;
+        label: string;
+    }[];
+    /** The days to label on the time axis, and their words. */
+    ticks: readonly {
+        day: number;
+        text: string;
+    }[];
+    /** The boxed period's first and last days. */
+    highlight: {
+        from: number;
+        to: number;
+    } | null;
+    /** The words at the line's last value, or none. */
+    endLabel: string | null;
+    formatTick: (value: number) => string;
+};
+export type LineChartLayout = {
+    width: number;
+    height: number;
+    compact: boolean;
+    plot: ChartPlot;
+    ticks: ChartTick[];
+    path: ChartPoint[];
+    area: ChartPoint[];
+    last: ChartPoint | null;
+    end: {
+        x: number;
+        y: number;
+        text: string;
+    } | null;
+    dateLabels: {
+        day: number;
+        x: number;
+        y: number;
+        text: string;
+    }[];
+    highlight: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
+    markers: PlacedMarker[];
+};
+/**
+ * Lays a line chart out at a width: its value axis on the left (through
+ * zero), the line through its points by date (straight or in steps), the
+ * area under it, its last value beside the plot's end, the time axis's
+ * labels (fewer when they would meet), the boxed period, and each marker's
+ * triangle and words. A compact chart (under `chartCompactWidth`) has a
+ * shorter plot.
+ */
+export declare function lineChartLayout(input: LineChartLayoutInput): LineChartLayout;

package/dist/line-chart-layout.js

@@ -0,0 +1,99 @@
+import { endGutter, labelGutter, labelInside, periodBox, valueTicks, valueY, } from './chart-axis.js';
+import { chartCompactWidth, chartGap, chartPlotHeight, chartTextWidth, chartType, } from './chart-metrics.js';
+import { chartScale, extentThroughZero } from './chart-scale.js';
+import { placeMarkers } from './line-chart-markers.js';
+import { closingIndexes } from './line-chart-points.js';
+import { areaPath, linePath, } from './line-chart-path.js';
+/**
+ * The time axis's labels: each asked-for day at its place, kept inside the
+ * chart, and thinned from the last back so no two meet.
+ */
+function dateLabels(ticks, x, width, y) {
+    const kept = [];
+    const sorted = [...ticks].sort((a, b) => b.day - a.day);
+    for (const tick of sorted) {
+        const centre = labelInside(x(tick.day), tick.text, width);
+        const half = chartTextWidth(tick.text) / 2;
+        const next = kept[0];
+        if (next &&
+            centre + half + chartGap * 2 > next.x - chartTextWidth(next.text) / 2)
+            continue;
+        kept.unshift({ day: tick.day, x: centre, y, text: tick.text });
+    }
+    return kept;
+}
+/**
+ * Lays a line chart out at a width: its value axis on the left (through
+ * zero), the line through its points by date (straight or in steps), the
+ * area under it, its last value beside the plot's end, the time axis's
+ * labels (fewer when they would meet), the boxed period, and each marker's
+ * triangle and words. A compact chart (under `chartCompactWidth`) has a
+ * shorter plot.
+ */
+export function lineChartLayout(input) {
+    const { width, points } = input;
+    const compact = width < chartCompactWidth;
+    const scale = chartScale(extentThroughZero(points.map((p) => p.y)));
+    const left = labelGutter(scale.ticks.map(input.formatTick));
+    const right = Math.max(left + 1, width -
+        endGutter({ width, left, axisWords: [], endLabel: input.endLabel })
+            .gutter);
+    const top = chartGap + chartType.lineHeight / 2;
+    const plot = {
+        left,
+        right,
+        top,
+        bottom: top + chartPlotHeight(compact),
+    };
+    const first = points[0]?.day ?? 0;
+    const span = (points.at(-1)?.day ?? first) - first;
+    const dayWidth = span > 0 ? (right - left) / span : right - left;
+    const x = (day) => span > 0 ? left + (day - first) * dayWidth : (left + right) / 2;
+    const placed = points.map((p) => ({
+        x: x(p.day),
+        y: valueY(p.y, scale, plot),
+    }));
+    const path = linePath(placed, input.curve);
+    const last = placed.at(-1) ?? null;
+    // A marker sits on its day's last point, the day's closing value.
+    const closing = closingIndexes(points.map((p) => p.day));
+    const markerPoints = input.markers.map((marker) => ({
+        x: x(marker.day),
+        y: placed[closing.get(marker.day) ?? -1]?.y ?? plot.bottom,
+        label: marker.label,
+    }));
+    return {
+        width,
+        height: plot.bottom + chartGap + chartType.lineHeight,
+        compact,
+        plot,
+        ticks: valueTicks(scale, plot, input.formatTick),
+        path,
+        area: input.area ? areaPath(path, valueY(0, scale, plot)) : [],
+        last,
+        end: last && input.endLabel
+            ? { x: right + chartGap, y: last.y, text: input.endLabel }
+            : null,
+        dateLabels: dateLabels(input.ticks, x, width, plot.bottom + chartGap + chartType.fontSize),
+        highlight: points.length > 0
+            ? highlightBox(input.highlight, first, span, x, dayWidth, plot)
+            : null,
+        markers: placeMarkers(markerPoints, plot),
+    };
+}
+/**
+ * The boxed period: its days, half a day past each end, clipped to the
+ * plot. On a chart of one date it is the whole plot when the period holds
+ * that date and nothing otherwise.
+ */
+function highlightBox(period, first, span, x, dayWidth, plot) {
+    if (!period)
+        return null;
+    if (span === 0 && (period.from > first || period.to < first))
+        return null;
+    const from = Math.max(x(period.from) - dayWidth / 2, plot.left);
+    const to = Math.min(x(period.to) + dayWidth / 2, plot.right);
+    if (to < from)
+        return null;
+    return periodBox(from, to - from, plot, 0);
+}

package/dist/line-chart-markers.d.ts

@@ -0,0 +1,29 @@
+import { type ChartPlot } from './chart-axis.js';
+/**
+ * A marker on a line: a downward triangle at its date with its words,
+ * below the line where they fit inside the plot, above it otherwise. Its
+ * words are left out where they would meet an earlier marker's.
+ */
+export type PlacedMarker = {
+    /** Its place in the chart's `markers`. */
+    order: number;
+    x: number;
+    /** The triangle's corners, as SVG points. */
+    triangle: string;
+    /** Its words' centre, moved in so they stay over the plot. */
+    labelX: number;
+    labelY: number;
+    label: string;
+    labelShown: boolean;
+};
+/**
+ * Places each marker at the line's height on its date: the triangle a
+ * small inset under the line, its words under it (moved in to stay over
+ * the plot), or both above the line when the words would pass the plot's
+ * bottom.
+ */
+export declare function placeMarkers(markers: readonly {
+    x: number;
+    y: number;
+    label: string;
+}[], plot: ChartPlot): PlacedMarker[];

package/dist/line-chart-markers.js

@@ -0,0 +1,57 @@
+import { chartInset, chartMarkerSize, chartTextWidth, chartType, } from './chart-metrics.js';
+function meets(a, b) {
+    return (a.left < b.right && b.left < a.right && a.top < b.bottom && b.top < a.bottom);
+}
+/**
+ * A centre for words `width` wide that keeps them over the plot, clear of
+ * the value axis's words and the last value beside it; centred on the plot
+ * when they are wider than it.
+ */
+function overPlot(x, width, plot) {
+    const low = plot.left + width / 2;
+    const high = plot.right - width / 2;
+    if (low > high)
+        return (plot.left + plot.right) / 2;
+    return Math.min(Math.max(x, low), high);
+}
+/**
+ * Places each marker at the line's height on its date: the triangle a
+ * small inset under the line, its words under it (moved in to stay over
+ * the plot), or both above the line when the words would pass the plot's
+ * bottom.
+ */
+export function placeMarkers(markers, plot) {
+    const half = chartMarkerSize / 2;
+    const shown = [];
+    return markers.map((marker, order) => {
+        const below = marker.y + chartInset + chartMarkerSize + chartType.lineHeight <=
+            plot.bottom;
+        const top = below
+            ? marker.y + chartInset
+            : marker.y - chartInset - chartMarkerSize;
+        const bottom = top + chartMarkerSize;
+        const labelY = below
+            ? bottom + chartType.fontSize
+            : top - (chartType.lineHeight - chartType.fontSize);
+        const width = chartTextWidth(marker.label);
+        const labelX = overPlot(marker.x, width, plot);
+        const box = {
+            left: labelX - width / 2,
+            right: labelX + width / 2,
+            top: labelY - chartType.fontSize,
+            bottom: labelY + (chartType.lineHeight - chartType.fontSize),
+        };
+        const labelShown = !shown.some((taken) => meets(taken, box));
+        if (labelShown)
+            shown.push(box);
+        return {
+            order,
+            x: marker.x,
+            labelX,
+            triangle: `${marker.x - half},${top} ${marker.x + half},${top} ${marker.x},${bottom}`,
+            labelY,
+            label: marker.label,
+            labelShown,
+        };
+    });
+}

package/dist/line-chart-path.d.ts

@@ -0,0 +1,18 @@
+/** How a line runs between its points. */
+export declare const lineChartCurves: readonly ["linear", "step"];
+export type LineChartCurve = (typeof lineChartCurves)[number];
+/** A point in the chart's pixels. */
+export type ChartPoint = {
+    x: number;
+    y: number;
+};
+/**
+ * The vertices a line is drawn through. `linear` joins each point to the
+ * next; `step` holds each value until the next point's date, then moves
+ * straight up or down to it, as a balance that changes on a day does.
+ */
+export declare function linePath(points: readonly ChartPoint[], curve: LineChartCurve): ChartPoint[];
+/** The area under a line's path, closed along the zero line. */
+export declare function areaPath(path: readonly ChartPoint[], zeroY: number): ChartPoint[];
+/** Vertices as an SVG `points` list. */
+export declare function svgPoints(path: readonly ChartPoint[]): string;

package/dist/line-chart-path.js

@@ -0,0 +1,33 @@
+/** How a line runs between its points. */
+export const lineChartCurves = ['linear', 'step'];
+/**
+ * The vertices a line is drawn through. `linear` joins each point to the
+ * next; `step` holds each value until the next point's date, then moves
+ * straight up or down to it, as a balance that changes on a day does.
+ */
+export function linePath(points, curve) {
+    if (curve === 'linear')
+        return [...points];
+    const path = [];
+    points.forEach((point, index) => {
+        const previous = points[index - 1];
+        if (previous)
+            path.push({ x: point.x, y: previous.y });
+        path.push(point);
+    });
+    return path;
+}
+/** The area under a line's path, closed along the zero line. */
+export function areaPath(path, zeroY) {
+    if (path.length === 0)
+        return [];
+    return [
+        { x: path[0].x, y: zeroY },
+        ...path,
+        { x: path.at(-1).x, y: zeroY },
+    ];
+}
+/** Vertices as an SVG `points` list. */
+export function svgPoints(path) {
+    return path.map((point) => `${point.x},${point.y}`).join(' ');
+}

package/dist/line-chart-points.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Each date's closing point: the index of the last point on it. A balance
+ * can change twice on one day; the day's markers and figures belong to its
+ * closing value.
+ */
+export declare function closingIndexes<Day>(days: readonly Day[]): Map<Day, number>;

package/dist/line-chart-points.js

@@ -0,0 +1,8 @@
+/**
+ * Each date's closing point: the index of the last point on it. A balance
+ * can change twice on one day; the day's markers and figures belong to its
+ * closing value.
+ */
+export function closingIndexes(days) {
+    return new Map(days.map((day, index) => [day, index]));
+}

package/dist/line-chart-table.d.ts

@@ -0,0 +1,15 @@
+import { type ChartTableRow } from './chart-table-rows.js';
+import { type LineChartMarker, type LineChartPeriod, type LineChartPoint } from './line-chart-input.js';
+/**
+ * A line chart's hidden table rows: one per point, headed by its date in
+ * the consumer's words, holding its value and (when the chart has markers)
+ * the words of the markers on its date, in the date's closing row only;
+ * the rows inside the boxed period are current.
+ */
+export declare function lineChartRows({ formatDate, formatValue, highlight, markers, points, }: {
+    points: readonly LineChartPoint[];
+    markers: readonly LineChartMarker[];
+    highlight: LineChartPeriod | undefined;
+    formatDate: (date: string) => string;
+    formatValue: (value: number) => string;
+}): ChartTableRow[];

package/dist/line-chart-table.js

@@ -0,0 +1,29 @@
+import { closingIndexes } from './line-chart-points.js';
+/**
+ * A line chart's hidden table rows: one per point, headed by its date in
+ * the consumer's words, holding its value and (when the chart has markers)
+ * the words of the markers on its date, in the date's closing row only;
+ * the rows inside the boxed period are current.
+ */
+export function lineChartRows({ formatDate, formatValue, highlight, markers, points, }) {
+    const closing = closingIndexes(points.map((point) => point.x));
+    return points.map((point, index) => {
+        const cells = [formatValue(point.y)];
+        if (markers.length > 0)
+            cells.push(closing.get(point.x) === index
+                ? markers
+                    .filter((marker) => marker.x === point.x)
+                    .map((marker) => marker.label)
+                    .join(', ')
+                : '');
+        return {
+            key: `${point.x}-${index}`,
+            header: formatDate(point.x),
+            cells,
+            // YYYY-MM-DD dates compare in date order as text.
+            current: highlight !== undefined &&
+                point.x >= highlight.from &&
+                point.x <= highlight.to,
+        };
+    });
+}