@scalewing/react 1.37.0 → 1.39.0

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,
+        };
+    });
+}

package/dist/pagination-pages.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Checks a pager's place: `pageCount` a whole number from 1 and `page` a
+ * whole number from 1 to `pageCount`. Pages count from 1, as people read
+ * them. Anything else throws a `RangeError`.
+ */
+export declare function assertPaginationPages(page: number, pageCount: number): void;
+/** The page a step goes to, or `null` at the end it cannot pass. */
+export declare function paginationStep(page: number, pageCount: number, direction: 'previous' | 'next'): number | null;
+/** The steps' names, one per step, each a word or two (not blank). */
+export declare function assertPaginationLabels(labels: {
+    previous: string;
+    next: string;
+}): void;

package/dist/pagination-pages.js

@@ -0,0 +1,22 @@
+/**
+ * Checks a pager's place: `pageCount` a whole number from 1 and `page` a
+ * whole number from 1 to `pageCount`. Pages count from 1, as people read
+ * them. Anything else throws a `RangeError`.
+ */
+export function assertPaginationPages(page, pageCount) {
+    if (!Number.isInteger(pageCount) || pageCount < 1)
+        throw new RangeError(`Pagination pageCount must be a whole number from 1: ${String(pageCount)}`);
+    if (!Number.isInteger(page) || page < 1 || page > pageCount)
+        throw new RangeError(`Pagination page must be a whole number from 1 to ${pageCount}: ${String(page)}`);
+}
+/** The page a step goes to, or `null` at the end it cannot pass. */
+export function paginationStep(page, pageCount, direction) {
+    const target = direction === 'previous' ? page - 1 : page + 1;
+    return target < 1 || target > pageCount ? null : target;
+}
+/** The steps' names, one per step, each a word or two (not blank). */
+export function assertPaginationLabels(labels) {
+    for (const key of ['previous', 'next'])
+        if (typeof labels?.[key] !== 'string' || labels[key].trim() === '')
+            throw new RangeError(`Pagination labels.${key} must be a word or two`);
+}

package/dist/scroll-overflow.d.ts

@@ -3,7 +3,13 @@ export type ScrollOverflow = {
     start: boolean;
     end: boolean;
 };
+/** Which block edges of a scroll box have content scrolled out past them. */
+export type BlockScrollOverflow = {
+    top: boolean;
+    bottom: boolean;
+};
 export declare const noScrollOverflow: ScrollOverflow;
+export declare const noBlockScrollOverflow: BlockScrollOverflow;
 /**
  * Reads a box's horizontal overflow from its scroll metrics. `scrollLeft` is
  * 0 at the inline start and grows toward the end in a left-to-right box; in
@@ -11,4 +17,10 @@ export declare const noScrollOverflow: ScrollOverflow;
  * the distance travelled is its magnitude in both.
  */
 export declare function scrollOverflow(scrollLeft: number, scrollWidth: number, clientWidth: number): ScrollOverflow;
+/**
+ * Reads a box's vertical overflow from its scroll metrics: `scrollTop` is 0
+ * at the top and grows toward the bottom.
+ */
+export declare function blockScrollOverflow(scrollTop: number, scrollHeight: number, clientHeight: number): BlockScrollOverflow;
 export declare function sameScrollOverflow(a: ScrollOverflow, b: ScrollOverflow): boolean;
+export declare function sameBlockScrollOverflow(a: BlockScrollOverflow, b: BlockScrollOverflow): boolean;

package/dist/scroll-overflow.js

@@ -1,10 +1,25 @@
 export const noScrollOverflow = { start: false, end: false };
+export const noBlockScrollOverflow = {
+    top: false,
+    bottom: false,
+};
 /**
  * Sub-pixel layout can leave a box a fraction of a pixel wider than its
  * content, or a scroll position a fraction short of its end; within this
  * many pixels an edge counts as reached.
  */
 const edgeTolerance = 1;
+/**
+ * Whether one axis has content past its leading and its trailing edge, or
+ * `null` when the content fits that axis. `travelled` is how far the box
+ * has scrolled from its leading edge.
+ */
+function axisOverflow(travelled, scrollSize, clientSize) {
+    const hidden = scrollSize - clientSize;
+    if (hidden <= edgeTolerance)
+        return null;
+    return [travelled > edgeTolerance, travelled < hidden - edgeTolerance];
+}
 /**
  * Reads a box's horizontal overflow from its scroll metrics. `scrollLeft` is
  * 0 at the inline start and grows toward the end in a left-to-right box; in
@@ -12,15 +27,24 @@ const edgeTolerance = 1;
  * the distance travelled is its magnitude in both.
  */
 export function scrollOverflow(scrollLeft, scrollWidth, clientWidth) {
-    const hidden = scrollWidth - clientWidth;
-    if (hidden <= edgeTolerance)
+    const edges = axisOverflow(Math.abs(scrollLeft), scrollWidth, clientWidth);
+    if (edges === null)
         return noScrollOverflow;
-    const travelled = Math.abs(scrollLeft);
-    return {
-        start: travelled > edgeTolerance,
-        end: travelled < hidden - edgeTolerance,
-    };
+    return { start: edges[0], end: edges[1] };
+}
+/**
+ * Reads a box's vertical overflow from its scroll metrics: `scrollTop` is 0
+ * at the top and grows toward the bottom.
+ */
+export function blockScrollOverflow(scrollTop, scrollHeight, clientHeight) {
+    const edges = axisOverflow(scrollTop, scrollHeight, clientHeight);
+    if (edges === null)
+        return noBlockScrollOverflow;
+    return { top: edges[0], bottom: edges[1] };
 }
 export function sameScrollOverflow(a, b) {
     return a.start === b.start && a.end === b.end;
 }
+export function sameBlockScrollOverflow(a, b) {
+    return a.top === b.top && a.bottom === b.bottom;
+}