@cosmicdrift/kumiko-renderer 0.388.0 → 0.390.0

package/dist/web/widgets/bounded-load-cache.js

@@ -1,31 +1,53 @@
-// Evicts the oldest entry once `max` is exceeded and disposes only that one,
-// so several documents on one page keep their own loading tasks alive. A
-// resolved value that `shouldKeep` rejects (a handled failure) is dropped so
-// the next mount retries.
 export function createBoundedLoadCache(max, dispose, shouldKeep = () => true) {
     const entries = new Map();
-    return (key, load) => {
-        const cached = entries.get(key);
-        if (cached !== undefined)
-            return cached;
-        const loading = load();
-        entries.set(key, loading);
-        // A failed load must not stick: the next mount retries instead of replaying the rejection.
-        const forget = () => {
-            if (entries.get(key) === loading)
-                entries.delete(key);
-        };
-        loading.then((value) => {
-            if (!shouldKeep(value))
-                forget();
-        }, forget);
-        if (entries.size > max) {
-            const [oldestKey, oldest] = entries.entries().next().value ?? [];
-            if (oldestKey !== undefined && oldest !== undefined) {
-                entries.delete(oldestKey);
-                void oldest.then(dispose);
-            }
+    const users = new Map();
+    const everRetained = new Set();
+    const evictIdle = (protectedKey) => {
+        for (const [key, entry] of entries) {
+            // skip: back within the bound, nothing more to evict
+            if (entries.size <= max)
+                return;
+            const idle = (users.get(key) ?? 0) === 0;
+            const settled = everRetained.has(key) || entries.size > max * 2;
+            if (key === protectedKey || !idle || !settled)
+                continue;
+            entries.delete(key);
+            everRetained.delete(key);
+            void entry.then(dispose);
         }
-        return loading;
+    };
+    return {
+        load: (key, load) => {
+            const cached = entries.get(key);
+            if (cached !== undefined)
+                return cached;
+            const loading = load();
+            entries.set(key, loading);
+            // A failed load must not stick: the next mount retries instead of replaying the rejection.
+            const forget = () => {
+                if (entries.get(key) === loading)
+                    entries.delete(key);
+            };
+            loading.then((value) => {
+                if (!shouldKeep(value))
+                    forget();
+            }, forget);
+            evictIdle(key);
+            return loading;
+        },
+        retain: (key) => {
+            users.set(key, (users.get(key) ?? 0) + 1);
+            everRetained.add(key);
+            return () => {
+                const remaining = (users.get(key) ?? 1) - 1;
+                if (remaining > 0) {
+                    users.set(key, remaining);
+                    // skip: other consumers still hold the entry
+                    return;
+                }
+                users.delete(key);
+                evictIdle();
+            };
+        },
     };
 }

package/dist/web/widgets/chart-data.d.ts

@@ -0,0 +1,35 @@
+export type TimeseriesPoint = {
+    readonly atMs: number;
+    /** null = outage/no value → falls to the baseline for a visible drop. */
+    readonly value: number | null;
+};
+export declare const SINGLE_POINT_RADIUS = 3;
+export declare function clampDotY(y: number, height: number): number;
+export type ChartTone = "positive" | "negative" | "active" | "neutral";
+export declare function chartToneColor(tone: ChartTone): string;
+export type ChartSeries = {
+    readonly key: string;
+    /** Translated by the caller. */
+    readonly label: string;
+    readonly points: readonly TimeseriesPoint[];
+};
+export type ChartMarker = {
+    readonly atMs: number;
+    readonly label: string;
+    /** Colors the pin and, on StackedAreaChart, draws a dashed guide line in the plot. */
+    readonly color?: string;
+    /** Translated by the caller. Groups markers into one legend entry when `markerLegend` is "legend". */
+    readonly legendLabel?: string;
+};
+/** Unstacked line drawn over a StackedAreaChart on the same y scale. */
+export type ChartLine = ChartSeries & {
+    readonly dashed?: boolean;
+};
+export type ToneMap = Readonly<Record<string, ChartTone>>;
+/** Key -> raw CSS color; wins over the tone map. */
+export type ColorMap = Readonly<Record<string, string>>;
+export declare function chartColor(key: string, index: number, tones: ToneMap | undefined, colors?: ColorMap): string;
+export declare function bucketTimes(series: readonly ChartSeries[]): readonly number[];
+export declare function valueAt(series: ChartSeries, atMs: number): number;
+export declare function seriesTotal(series: ChartSeries): number;
+export declare function percent(fraction: number): string;

package/dist/web/widgets/chart-data.js

@@ -0,0 +1,37 @@
+export const SINGLE_POINT_RADIUS = 3;
+export function clampDotY(y, height) {
+    return Math.max(SINGLE_POINT_RADIUS, Math.min(height - SINGLE_POINT_RADIUS, y));
+}
+const CHART_TONE_VAR = {
+    positive: "var(--color-status-ok)",
+    negative: "var(--color-status-bad)",
+    active: "var(--color-status-active)",
+    neutral: "var(--color-status-neutral)",
+};
+export function chartToneColor(tone) {
+    return CHART_TONE_VAR[tone];
+}
+const CHART_FALLBACK_TONES = ["active", "positive", "negative", "neutral"];
+export function chartColor(key, index, tones, colors) {
+    const color = colors?.[key];
+    if (color !== undefined)
+        return color;
+    const tone = tones?.[key] ?? CHART_FALLBACK_TONES[index % CHART_FALLBACK_TONES.length] ?? "active";
+    return CHART_TONE_VAR[tone];
+}
+export function bucketTimes(series) {
+    const times = new Set();
+    for (const s of series)
+        for (const p of s.points)
+            times.add(p.atMs);
+    return [...times].sort((a, b) => a - b);
+}
+export function valueAt(series, atMs) {
+    return series.points.find((p) => p.atMs === atMs)?.value ?? 0;
+}
+export function seriesTotal(series) {
+    return series.points.reduce((sum, p) => sum + (p.value ?? 0), 0);
+}
+export function percent(fraction) {
+    return `${(fraction * 100).toFixed(2)}%`;
+}

package/dist/web/widgets/chart-markers.d.ts

@@ -0,0 +1,26 @@
+import type { ReactNode } from "react";
+import { type ChartMarker } from "./chart-data.ts";
+export declare function assignPinRows(fractions: readonly number[]): readonly number[];
+export type KeyedMarker = ChartMarker & {
+    readonly key: string;
+};
+export declare function sortMarkers(markers: readonly ChartMarker[]): readonly KeyedMarker[];
+export declare function MarkerPins({ markers, windowStartMs, windowEndMs, numbered, formatMarkerTime, className, }: {
+    readonly className?: string;
+    readonly markers: readonly ChartMarker[];
+    readonly windowStartMs: number;
+    readonly windowEndMs: number;
+    /** false: plain colored dots whose tooltip carries label and time. */
+    readonly numbered?: boolean;
+    readonly formatMarkerTime?: (atMs: number) => string;
+}): ReactNode;
+export declare function markerLegendItems(markers: readonly ChartMarker[]): readonly {
+    readonly key: string;
+    readonly label: string;
+    readonly color: string;
+}[];
+export declare function MarkerLegend({ markers, formatMarkerTime, className, }: {
+    readonly className?: string;
+    readonly markers: readonly ChartMarker[];
+    readonly formatMarkerTime?: (atMs: number) => string;
+}): ReactNode;

package/dist/web/widgets/chart-markers.js

@@ -0,0 +1,64 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "../lib/cn.js";
+import { percent } from "./chart-data.js";
+// A 16px pin on a ~230px-wide plot (390px viewport) collides when markers sit
+// within ~7% of each other, so close pins are staggered into extra rows.
+const MARKER_PIN_MIN_GAP_FRACTION = 0.07;
+const MARKER_PIN_MAX_ROWS = 3;
+const MARKER_PIN_ROW_HEIGHT_PX = 18;
+export function assignPinRows(fractions) {
+    const lastFractionPerRow = [];
+    return fractions.map((fraction) => {
+        let row = lastFractionPerRow.findIndex((last) => fraction - last >= MARKER_PIN_MIN_GAP_FRACTION);
+        if (row === -1) {
+            row =
+                lastFractionPerRow.length < MARKER_PIN_MAX_ROWS
+                    ? lastFractionPerRow.length
+                    : MARKER_PIN_MAX_ROWS - 1;
+        }
+        lastFractionPerRow[row] = fraction;
+        return row;
+    });
+}
+// Two markers may share atMs and label, so the occurrence count keeps React keys unique.
+export function sortMarkers(markers) {
+    const seen = new Map();
+    return [...markers]
+        .sort((a, b) => a.atMs - b.atMs)
+        .map((marker) => {
+        const base = `${marker.atMs}-${marker.label}`;
+        const occurrence = seen.get(base) ?? 0;
+        seen.set(base, occurrence + 1);
+        return { ...marker, key: `${base}-${occurrence}` };
+    });
+}
+export function MarkerPins({ markers, windowStartMs, windowEndMs, numbered = true, formatMarkerTime, className, }) {
+    const span = Math.max(1, windowEndMs - windowStartMs);
+    const sorted = sortMarkers(markers);
+    const fractions = sorted.map((marker) => Math.max(0, Math.min(1, (marker.atMs - windowStartMs) / span)));
+    const rows = assignPinRows(fractions);
+    const rowCount = Math.max(1, ...rows.map((row) => row + 1));
+    return (_jsx("div", { "aria-hidden": "true", className: cn("relative mt-1", className), style: { height: rowCount * MARKER_PIN_ROW_HEIGHT_PX }, children: sorted.map((marker, i) => (_jsx("span", { "data-testid": "chart-marker-pin", title: numbered
+                ? undefined
+                : formatMarkerTime === undefined
+                    ? marker.label
+                    : `${marker.label} · ${formatMarkerTime(marker.atMs)}`, className: cn("absolute flex -translate-x-1/2 items-center justify-center rounded-full text-[10px] font-medium text-background", numbered ? "size-4" : "size-2", marker.color === undefined && "bg-foreground"), style: {
+                left: percent(fractions[i] ?? 0),
+                top: (rows[i] ?? 0) * MARKER_PIN_ROW_HEIGHT_PX + (numbered ? 0 : 4),
+                ...(marker.color !== undefined && { backgroundColor: marker.color }),
+            }, children: numbered ? i + 1 : null }, marker.key))) }));
+}
+export function markerLegendItems(markers) {
+    const items = new Map();
+    for (const marker of markers) {
+        const label = marker.legendLabel ?? marker.label;
+        const color = marker.color ?? "var(--color-foreground)";
+        const key = `marker-${label}-${color}`;
+        if (!items.has(key))
+            items.set(key, { key, label, color });
+    }
+    return [...items.values()];
+}
+export function MarkerLegend({ markers, formatMarkerTime, className, }) {
+    return (_jsx("ol", { className: cn("flex flex-col gap-1 text-xs text-muted-foreground", className), children: sortMarkers(markers).map((marker, i) => (_jsxs("li", { "data-testid": "chart-marker-item", className: "flex gap-2", children: [_jsx("span", { className: "w-4 shrink-0 text-center tabular-nums text-foreground", style: marker.color !== undefined ? { color: marker.color } : undefined, children: i + 1 }), _jsx("span", { children: marker.label }), formatMarkerTime !== undefined && (_jsx("span", { className: "ml-auto tabular-nums", children: formatMarkerTime(marker.atMs) }))] }, marker.key))) }));
+}

package/dist/web/widgets/chart-parts.d.ts

@@ -0,0 +1,20 @@
+import type { ReactNode } from "react";
+export declare function ChartLegend({ items, formatValue, }: {
+    readonly items: readonly {
+        readonly key: string;
+        /** Defaults to the key; set when the key is prefixed to avoid collisions. */
+        readonly testIdKey?: string;
+        readonly label: string;
+        readonly color: string;
+        /** Omitted: no sum next to the label. */
+        readonly total?: number;
+        readonly swatch?: "area" | "line" | "dashed-line";
+    }[];
+    readonly formatValue: (value: number) => string;
+}): ReactNode;
+export declare function evenYTickValues(max: number): readonly number[];
+export declare function YTicks({ values, formatValue, className, }: {
+    readonly values: readonly number[];
+    readonly formatValue: (value: number) => string;
+    readonly className?: string;
+}): ReactNode;

package/dist/web/widgets/chart-parts.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "../lib/cn.js";
+export function ChartLegend({ items, formatValue, }) {
+    return (_jsx("ul", { className: "flex flex-wrap gap-x-4 gap-y-1 text-xs text-muted-foreground", children: items.map((item) => (_jsxs("li", { "data-testid": `chart-legend-${item.testIdKey ?? item.key}`, className: "flex items-center gap-1.5", children: [item.swatch === undefined || item.swatch === "area" ? (_jsx("span", { "aria-hidden": "true", className: "size-2 rounded-[2px]", style: { backgroundColor: item.color } })) : (_jsx("span", { "aria-hidden": "true", className: "w-3 border-t-2", style: {
+                        borderColor: item.color,
+                        borderTopStyle: item.swatch === "dashed-line" ? "dashed" : "solid",
+                    } })), _jsx("span", { children: item.label }), item.total !== undefined && (_jsx("span", { className: "tabular-nums text-foreground", children: formatValue(item.total) }))] }, item.key))) }));
+}
+const Y_TICK_COUNT = 3;
+export function evenYTickValues(max) {
+    return Array.from({ length: Y_TICK_COUNT }, (_, i) => (max / (Y_TICK_COUNT - 1)) * i);
+}
+export function YTicks({ values, formatValue, className, }) {
+    return (_jsx("div", { "aria-hidden": "true", className: cn("flex flex-col-reverse justify-between text-right text-[11px] tabular-nums text-muted-foreground", className), children: values.map((value, i) => (_jsx("span", { children: formatValue(value) }, i))) }));
+}

package/dist/web/widgets/charts.d.ts

@@ -1,5 +1,5 @@
 import { type ReactNode } from "react";
-import { type StackedAreaDateFormat, type StackedAreaInitialWindow, type StackedAreaRanges, type StackedAreaWindowSelection } from "./chart-window.ts";
+import { type ChartMarker, type ChartSeries, type ColorMap, type TimeseriesPoint, type ToneMap } from "./chart-data.ts";
 import { type StatusTone } from "./status-badge.tsx";
 export type StatusBarEntry = {
     /** Stable key (z.B. ISO-Datum). */
@@ -31,11 +31,6 @@ export declare function smoothPath(pts: ReadonlyArray<{
     readonly x: number;
     readonly y: number;
 }>): string;
-export type TimeseriesPoint = {
-    readonly atMs: number;
-    /** null = outage/no value → falls to the baseline for a visible drop. */
-    readonly value: number | null;
-};
 export type TimeseriesYAxis = {
     /** Number of gridlines including the zero baseline (min 2). Tick values are
      *  rounded to 1/2/5 x 10^n steps and the y-scale reaches the top tick. */
@@ -97,26 +92,6 @@ export declare function TimeseriesChart({ points, windowStartMs, windowEndMs, to
     readonly emptyContent?: ReactNode;
     readonly testId?: string;
 }): ReactNode;
-export type ChartTone = "positive" | "negative" | "active" | "neutral";
-export declare function chartToneColor(tone: ChartTone): string;
-export type ChartSeries = {
-    readonly key: string;
-    /** Translated by the caller. */
-    readonly label: string;
-    readonly points: readonly TimeseriesPoint[];
-};
-export type ChartMarker = {
-    readonly atMs: number;
-    readonly label: string;
-    /** Colors the pin and, on StackedAreaChart, draws a dashed guide line in the plot. */
-    readonly color?: string;
-    /** Translated by the caller. Groups markers into one legend entry when `markerLegend` is "legend". */
-    readonly legendLabel?: string;
-};
-/** Unstacked line drawn over a StackedAreaChart on the same y scale. */
-export type ChartLine = ChartSeries & {
-    readonly dashed?: boolean;
-};
 export type SegmentBarRow = {
     readonly key: string;
     readonly label: string;
@@ -127,10 +102,6 @@ export type SegmentBarRow = {
         readonly value: number;
     }[];
 };
-type ToneMap = Readonly<Record<string, ChartTone>>;
-/** Key -> raw CSS color; wins over the tone map. */
-type ColorMap = Readonly<Record<string, string>>;
-export declare function assignPinRows(fractions: readonly number[]): readonly number[];
 /** Vertically stacked bars per bucket (x axis = bucket, not time).
  *  The last bucket carries `todayLabel` when it contains `windowEndMs` and
  *  has day granularity. */
@@ -158,51 +129,7 @@ export declare function SegmentBarChart({ rows, tones, colors, ariaLabel, format
     readonly formatValue?: (value: number) => string;
     readonly testId?: string;
 }): ReactNode;
-/** Stacked bands over time. Right of `todayMs` is the forecast: lighter
- *  fill plus a vertical "today" line. */
-export declare function StackedAreaChart({ series: allSeries, windowStartMs: fullWindowStartMs, windowEndMs: fullWindowEndMs, todayMs, tones, colors, markers: allMarkers, lines: allLines, ranges, initialWindow, brush, windowSelection, onWindowSelectionChange, brushLabels, ariaLabel, todayLabel, formatBucketLabel, formatValue, formatAxisValue, formatMarkerTime, dateFormat, timeZone, markerLegend, markerLabels, scrollable, showLegendTotals, emptyContent, testId, }: {
-    readonly series: readonly ChartSeries[];
-    readonly windowStartMs: number;
-    readonly windowEndMs: number;
-    readonly todayMs?: number;
-    readonly tones?: ToneMap;
-    readonly colors?: ColorMap;
-    readonly markers?: readonly ChartMarker[];
-    /** Drawn over the bands, not stacked. A `null` value breaks the line. */
-    readonly lines?: readonly ChartLine[];
-    /** Range presets anchored at today; uncontrolled, the widget renders the switch itself. */
-    readonly ranges?: StackedAreaRanges;
-    /** Uncontrolled start window; "from-today" ignores the default range and starts at today. */
-    readonly initialWindow?: StackedAreaInitialWindow;
-    /** Scrubber under the plot to drag the visible window; starts at today without `ranges`. */
-    readonly brush?: boolean;
-    readonly windowSelection?: StackedAreaWindowSelection;
-    /** Makes the window controlled: no own range switch, `windowSelection` is the only source. */
-    readonly onWindowSelectionChange?: (selection: StackedAreaWindowSelection) => void;
-    /** aria-labels of the two brush handles. */
-    readonly brushLabels?: {
-        readonly start: string;
-        readonly end: string;
-    };
-    readonly ariaLabel: string;
-    readonly todayLabel: string;
-    readonly formatBucketLabel: (atMs: number, format: StackedAreaDateFormat) => string;
-    readonly formatValue?: (value: number) => string;
-    /** y-axis tick labels only (legend and totals keep `formatValue`); defaults to `formatValue`. */
-    readonly formatAxisValue?: (value: number) => string;
-    readonly formatMarkerTime?: (atMs: number, format: StackedAreaDateFormat) => string;
-    /** Overrides the automatic format (month and year once the visible window spans 18 months). */
-    readonly dateFormat?: StackedAreaDateFormat;
-    /** Zone the x-axis ticks align to; must match the zone `formatBucketLabel` formats in. Default UTC. */
-    readonly timeZone?: string;
-    /** "legend": unnumbered pins with tooltip, one dashed legend entry per marker label and color. */
-    readonly markerLegend?: "list" | "legend";
-    /** Writes each marker label vertically next to its guide line on wide containers; narrow ones keep the pins. */
-    readonly markerLabels?: boolean;
-    /** Fixed width per bucket; the plot scrolls horizontally, y ticks stay put. */
-    readonly scrollable?: boolean;
-    readonly showLegendTotals?: boolean;
-    readonly emptyContent?: ReactNode;
-    readonly testId?: string;
-}): ReactNode;
-export {};
+export type { ChartLine, ChartMarker, ChartSeries, ChartTone, TimeseriesPoint, } from "./chart-data.ts";
+export { chartToneColor } from "./chart-data.ts";
+export { assignPinRows } from "./chart-markers.tsx";
+export { StackedAreaChart } from "./stacked-area-chart.tsx";