@cosmicdrift/kumiko-renderer 0.388.0 → 0.390.0

package/dist/web/widgets/stacked-area-model.d.ts

@@ -0,0 +1,11 @@
+import type { StackedAreaGeometry } from "./stacked-area-geometry.ts";
+import type { ResolvedStackedAreaProps } from "./stacked-area-props.ts";
+import type { useStackedAreaTooltip } from "./use-stacked-area-tooltip.ts";
+import type { useStackedAreaWindow } from "./use-stacked-area-window.ts";
+export type StackedAreaModel = {
+    readonly props: ResolvedStackedAreaProps;
+    readonly clipId: string;
+    readonly win: ReturnType<typeof useStackedAreaWindow>;
+    readonly tooltip: ReturnType<typeof useStackedAreaTooltip>;
+    readonly geometry: StackedAreaGeometry;
+};

package/dist/web/widgets/stacked-area-model.js

@@ -0,0 +1 @@
+export {};

package/dist/web/widgets/stacked-area-plot.d.ts

@@ -0,0 +1,3 @@
+import type { ReactNode } from "react";
+import type { StackedAreaModel } from "./stacked-area-model.ts";
+export declare function renderStackedAreaPlot(m: StackedAreaModel): ReactNode;

package/dist/web/widgets/stacked-area-plot.js

@@ -0,0 +1,51 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "../lib/cn.js";
+import { percent } from "./chart-data.js";
+import { MarkerPins } from "./chart-markers.js";
+import { AXIS_TIERS } from "./stacked-area-geometry.js";
+import { renderPlotSvg } from "./stacked-area-svg.js";
+import { renderTooltipOverlay } from "./stacked-area-tooltip.js";
+const MARKER_LABEL_FLIP_FRACTION = 0.97;
+function bucketLabelTransform(index, count) {
+    if (index === 0)
+        return "";
+    return index === count - 1 ? "-translate-x-full" : "-translate-x-1/2";
+}
+// Markers sharing a timestamp become one label ("A, B") in the first one's color.
+function groupMarkerLabels(markers) {
+    const groups = new Map();
+    for (const marker of [...markers].sort((a, b) => a.atMs - b.atMs)) {
+        groups.set(marker.atMs, [...(groups.get(marker.atMs) ?? []), marker]);
+    }
+    return [...groups.entries()].map(([atMs, members]) => ({
+        atMs,
+        text: members.map((m) => m.label).join(", "),
+        color: members[0]?.color ?? "var(--color-foreground)",
+    }));
+}
+function renderTodayLabel(m, todayFraction) {
+    return (_jsx("span", { "data-testid": "chart-today-label", className: "absolute -top-4 -translate-x-1/2 text-[11px] text-foreground", style: { left: percent(todayFraction) }, children: m.props.todayLabel }));
+}
+function renderScrollableAxis(m) {
+    const { times, fractionOf, formatBucket } = m.win;
+    return (_jsx("div", { "data-testid": "chart-bucket-labels", className: "relative mt-1 h-4 text-[11px] text-muted-foreground", children: times.map((atMs, i) => (_jsx("span", { className: cn("absolute whitespace-nowrap", bucketLabelTransform(i, times.length)), style: { left: percent(fractionOf(atMs)) }, children: formatBucket(atMs) }, atMs))) }));
+}
+function renderTickedAxis(m) {
+    const { fractionOf, formatBucket, windowStartMs, windowEndMs, tierTicks } = m.win;
+    return (_jsxs("div", { className: "relative mt-1 h-4 text-[11px] text-muted-foreground", children: [_jsx("span", { className: "absolute left-0 whitespace-nowrap", children: formatBucket(windowStartMs) }), _jsx("span", { className: "absolute right-0 whitespace-nowrap", children: formatBucket(windowEndMs) }), AXIS_TIERS.map((tier, tierIndex) => (_jsx("div", { className: cn("absolute inset-0", tier.visibilityClass), children: (tierTicks[tierIndex] ?? []).map((tickMs) => (_jsx("span", { "data-testid": "chart-axis-tick", className: "absolute -translate-x-1/2 whitespace-nowrap", style: { left: percent(fractionOf(tickMs)) }, children: formatBucket(tickMs) }, tickMs))) }, tier.maxLabels)))] }));
+}
+function renderMarkerLabels(m) {
+    return groupMarkerLabels(m.win.markers ?? []).map((group) => {
+        const fraction = m.win.fractionOf(group.atMs);
+        const flipped = fraction > MARKER_LABEL_FLIP_FRACTION;
+        return (_jsx("div", { className: cn("pointer-events-none absolute top-0 hidden @2xl:block", flipped ? "-translate-x-full pr-1" : "pl-1"), style: { left: percent(fraction) }, children: _jsx("span", { "data-testid": "chart-marker-label", className: "block max-h-44 rotate-180 overflow-hidden text-ellipsis whitespace-nowrap text-[11px] leading-none [writing-mode:vertical-rl] @2xl:max-h-60", style: { color: group.color }, children: group.text }) }, group.atMs));
+    });
+}
+function renderMarkerPins(m, markers) {
+    const { markerLegend, markerLabels } = m.props;
+    return (_jsx(MarkerPins, { markers: markers, windowStartMs: m.win.windowStartMs, windowEndMs: m.win.windowEndMs, numbered: markerLegend === "list" || markerLabels, formatMarkerTime: m.win.formatMarkerTimeInWindow, ...(markerLabels && { className: "@2xl:hidden" }) }));
+}
+export function renderStackedAreaPlot(m) {
+    const { todayFraction, markers } = m.win;
+    return (_jsxs(_Fragment, { children: [todayFraction !== undefined && renderTodayLabel(m, todayFraction), renderPlotSvg(m), m.props.scrollable ? renderScrollableAxis(m) : renderTickedAxis(m), renderTooltipOverlay(m), m.props.markerLabels && renderMarkerLabels(m), markers !== undefined && markers.length > 0 && renderMarkerPins(m, markers)] }));
+}

package/dist/web/widgets/stacked-area-props.d.ts

@@ -0,0 +1,83 @@
+import type { ReactNode } from "react";
+import type { ChartLine, ChartMarker, ChartSeries, ColorMap, ToneMap } from "./chart-data.ts";
+import type { StackedAreaDateFormat, StackedAreaInitialWindow, StackedAreaRanges, StackedAreaWindowSelection } from "./chart-window.ts";
+export type StackedAreaChartProps = {
+    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;
+};
+/** formatAxisValue defaults to the resolved formatValue, so the destructuring order matters. */
+export declare function resolveStackedAreaProps({ lines, brush, brushLabels, formatValue, formatAxisValue, markerLegend, markerLabels, scrollable, showLegendTotals, ...rest }: StackedAreaChartProps): {
+    series: readonly ChartSeries[];
+    windowStartMs: number;
+    windowEndMs: number;
+    todayMs?: number;
+    tones?: ToneMap;
+    colors?: ColorMap;
+    markers?: readonly ChartMarker[];
+    ranges?: StackedAreaRanges;
+    initialWindow?: StackedAreaInitialWindow;
+    windowSelection?: StackedAreaWindowSelection;
+    onWindowSelectionChange?: (selection: StackedAreaWindowSelection) => void;
+    ariaLabel: string;
+    todayLabel: string;
+    formatBucketLabel: (atMs: number, format: StackedAreaDateFormat) => string;
+    formatMarkerTime?: (atMs: number, format: StackedAreaDateFormat) => string;
+    dateFormat?: StackedAreaDateFormat;
+    timeZone?: string;
+    emptyContent?: ReactNode;
+    testId?: string;
+    lines: readonly ChartLine[];
+    brush: boolean;
+    brushLabels: {
+        readonly start: string;
+        readonly end: string;
+    };
+    formatValue: (value: number) => string;
+    formatAxisValue: (value: number) => string;
+    markerLegend: "legend" | "list";
+    markerLabels: boolean;
+    scrollable: boolean;
+    showLegendTotals: boolean;
+};
+export type ResolvedStackedAreaProps = ReturnType<typeof resolveStackedAreaProps>;

package/dist/web/widgets/stacked-area-props.js

@@ -0,0 +1,16 @@
+const DEFAULT_BRUSH_LABELS = { start: "Window start", end: "Window end" };
+/** formatAxisValue defaults to the resolved formatValue, so the destructuring order matters. */
+export function resolveStackedAreaProps({ lines = [], brush = false, brushLabels = DEFAULT_BRUSH_LABELS, formatValue = String, formatAxisValue = formatValue, markerLegend = "list", markerLabels = false, scrollable = false, showLegendTotals = true, ...rest }) {
+    return {
+        ...rest,
+        lines,
+        brush,
+        brushLabels,
+        formatValue,
+        formatAxisValue,
+        markerLegend,
+        markerLabels,
+        scrollable,
+        showLegendTotals,
+    };
+}

package/dist/web/widgets/stacked-area-svg.d.ts

@@ -0,0 +1,3 @@
+import type { ReactNode } from "react";
+import type { StackedAreaModel } from "./stacked-area-model.ts";
+export declare function renderPlotSvg(m: StackedAreaModel): ReactNode;

package/dist/web/widgets/stacked-area-svg.js

@@ -0,0 +1,38 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "../lib/cn.js";
+import { SINGLE_POINT_RADIUS } from "./chart-data.js";
+import { PLOT_HEIGHT, PLOT_WIDTH, STACKED_AREA_PLOT_HEIGHT_CLASS, } from "./stacked-area-geometry.js";
+const bandGradientId = (m, index) => `${m.clipId}-band-${index}`;
+function todayXOf(m) {
+    return (m.win.todayFraction ?? 1) * PLOT_WIDTH;
+}
+function renderBands(m, fillOpacity, edgeOpacity) {
+    return m.geometry.bands.map((band, bi) => band.dot === undefined ? (_jsxs("g", { children: [_jsx("path", { d: band.d, fill: `url(#${bandGradientId(m, bi)})`, fillOpacity: fillOpacity, stroke: "none" }), _jsx("path", { "data-testid": `chart-band-edge-${band.key}`, d: band.edge, fill: "none", stroke: band.color, strokeOpacity: edgeOpacity, strokeWidth: 1.5, vectorEffect: "non-scaling-stroke" })] }, band.key)) : (_jsx("circle", { "data-testid": "stacked-area-single-point", cx: PLOT_WIDTH / 2, cy: band.dot, r: SINGLE_POINT_RADIUS, fill: band.color, fillOpacity: fillOpacity }, band.key)));
+}
+function renderDefs(m) {
+    const todayX = todayXOf(m);
+    return (_jsxs("defs", { children: [m.geometry.bands.map((band, bi) => (_jsxs("linearGradient", { id: bandGradientId(m, bi), x1: "0", x2: "0", y1: "0", y2: "1", children: [_jsx("stop", { offset: "0%", stopColor: band.color, stopOpacity: 1 }), _jsx("stop", { offset: "100%", stopColor: band.color, stopOpacity: 0.35 })] }, band.key))), _jsx("clipPath", { id: `${m.clipId}-past`, children: _jsx("rect", { x: 0, y: 0, width: todayX, height: PLOT_HEIGHT }) }), _jsx("clipPath", { id: `${m.clipId}-future`, children: _jsx("rect", { x: todayX, y: 0, width: PLOT_WIDTH - todayX, height: PLOT_HEIGHT }) })] }));
+}
+function renderGridLines(m) {
+    const { yOf, yTickValues } = m.geometry;
+    return yTickValues.map((tickValue) => (_jsx("line", { "data-testid": "chart-grid-line", x1: 0, x2: PLOT_WIDTH, y1: yOf(tickValue), y2: yOf(tickValue), stroke: "var(--color-border)", strokeWidth: 1, strokeDasharray: "3 3", vectorEffect: "non-scaling-stroke" }, tickValue)));
+}
+function renderMarkerGuides(m) {
+    return m.geometry.coloredMarkers.map((marker) => {
+        const x = m.win.fractionOf(marker.atMs) * PLOT_WIDTH;
+        return (_jsx("line", { "data-testid": "chart-marker-guide", x1: x, x2: x, y1: 0, y2: PLOT_HEIGHT, stroke: marker.color, strokeWidth: 1, strokeDasharray: "2 3", vectorEffect: "non-scaling-stroke" }, marker.key));
+    });
+}
+function renderLinePaths(m) {
+    return m.geometry.linePaths.map((line) => (_jsx("path", { "data-testid": `chart-line-${line.key}`, d: line.d, fill: "none", stroke: line.color, strokeWidth: 2, strokeDasharray: line.dashed ? "6 4" : undefined, vectorEffect: "non-scaling-stroke" }, line.key)));
+}
+function renderTodayLine(m) {
+    const todayX = todayXOf(m);
+    return (_jsx("line", { "data-testid": "chart-today-line", x1: todayX, x2: todayX, y1: 0, y2: PLOT_HEIGHT, stroke: "var(--color-foreground)", strokeWidth: 1, strokeDasharray: "3 3", vectorEffect: "non-scaling-stroke" }));
+}
+export function renderPlotSvg(m) {
+    const { clipId } = m;
+    const hasToday = m.win.todayFraction !== undefined;
+    const ariaLabel = m.props.ariaLabel;
+    return (_jsxs("svg", { viewBox: `0 0 ${PLOT_WIDTH} ${PLOT_HEIGHT}`, preserveAspectRatio: "none", className: cn("block w-full", STACKED_AREA_PLOT_HEIGHT_CLASS), role: "img", "aria-label": ariaLabel, children: [_jsx("title", { children: ariaLabel }), renderDefs(m), renderGridLines(m), _jsx("g", { clipPath: `url(#${clipId}-past)`, children: renderBands(m, 0.55, 0.9) }), hasToday && (_jsx("g", { "data-testid": "chart-forecast-region", clipPath: `url(#${clipId}-future)`, children: renderBands(m, 0.25, 0.5) })), renderMarkerGuides(m), renderLinePaths(m), hasToday && renderTodayLine(m)] }));
+}

package/dist/web/widgets/stacked-area-tooltip.d.ts

@@ -0,0 +1,3 @@
+import type { ReactNode } from "react";
+import type { StackedAreaModel } from "./stacked-area-model.ts";
+export declare function renderTooltipOverlay(m: StackedAreaModel): ReactNode;

package/dist/web/widgets/stacked-area-tooltip.js

@@ -0,0 +1,86 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "../lib/cn.js";
+import { chartColor, percent, valueAt } from "./chart-data.js";
+import { bucketIndexAtFraction } from "./chart-window.js";
+import { STACKED_AREA_PLOT_HEIGHT_CLASS } from "./stacked-area-geometry.js";
+const TOOLTIP_WIDTH_REM = 14;
+const TOOLTIP_OFFSET_PX = 8;
+// A swipe over the plot (scrolling the page or the chart) must not open the card.
+const TOOLTIP_TAP_MAX_MOVEMENT_PX = 8;
+function buildTooltipRows(m, tooltipAtMs) {
+    const { tones, colors } = m.props;
+    const { series, lines } = m.win;
+    const { linePaths } = m.geometry;
+    return [
+        ...series.map((s, i) => ({
+            key: s.key,
+            label: s.label,
+            color: chartColor(s.key, i, tones, colors),
+            swatch: "area",
+            value: valueAt(s, tooltipAtMs),
+        })),
+        ...lines.flatMap((line, li) => {
+            const value = line.points.find((p) => p.atMs === tooltipAtMs)?.value;
+            return value === null || value === undefined
+                ? []
+                : [
+                    {
+                        key: line.key,
+                        label: line.label,
+                        color: linePaths[li]?.color ?? "var(--color-foreground)",
+                        swatch: line.dashed === true ? "dashed-line" : "line",
+                        value,
+                    },
+                ];
+        }),
+    ];
+}
+function renderTooltipSwatch(row) {
+    if (row.swatch === "area") {
+        return (_jsx("span", { "aria-hidden": "true", className: "size-2 shrink-0 rounded-[2px]", style: { backgroundColor: row.color } }));
+    }
+    return (_jsx("span", { "aria-hidden": "true", className: "w-3 shrink-0 border-t-2", style: {
+            borderColor: row.color,
+            borderTopStyle: row.swatch === "dashed-line" ? "dashed" : "solid",
+        } }));
+}
+function renderTooltipCard(m, tooltipAtMs) {
+    const tooltipFraction = m.win.fractionOf(tooltipAtMs);
+    const tooltipOnLeft = tooltipFraction > 0.5;
+    const tooltipEdge = `${percent(tooltipFraction)} ${tooltipOnLeft ? "-" : "+"} ${TOOLTIP_OFFSET_PX}px`;
+    const tooltipLeft = tooltipOnLeft
+        ? `max(0px, calc(${tooltipEdge} - ${TOOLTIP_WIDTH_REM}rem))`
+        : `max(0px, min(calc(${tooltipEdge}), calc(100% - ${TOOLTIP_WIDTH_REM}rem)))`;
+    return (_jsxs(_Fragment, { children: [_jsx("div", { "aria-hidden": "true", className: "pointer-events-none absolute inset-y-0 w-px bg-foreground/40", style: { left: percent(tooltipFraction) } }), _jsxs("div", { "data-testid": "chart-tooltip", "data-side": tooltipOnLeft ? "left" : "right", className: "pointer-events-none absolute top-2 rounded-md border bg-popover p-2 text-xs text-popover-foreground shadow-sm", style: { left: tooltipLeft, width: `min(${TOOLTIP_WIDTH_REM}rem, 100%)` }, children: [_jsx("div", { className: "mb-1 font-medium", children: m.win.formatBucket(tooltipAtMs) }), buildTooltipRows(m, tooltipAtMs).map((row) => (_jsxs("div", { className: "flex items-center gap-1.5", children: [renderTooltipSwatch(row), _jsx("span", { className: "min-w-0 truncate text-muted-foreground", children: row.label }), _jsx("span", { className: "ml-auto tabular-nums", children: m.props.formatAxisValue(row.value) })] }, row.key)))] })] }));
+}
+function bucketAtMsUnderPointer(m, event) {
+    const { times, visibleWindow } = m.win;
+    const rect = event.currentTarget.getBoundingClientRect();
+    return (times[bucketIndexAtFraction(times, visibleWindow, rect.width === 0 ? 0 : (event.clientX - rect.left) / rect.width)] ?? null);
+}
+export function renderTooltipOverlay(m) {
+    const { tooltipAtMs, setSelectedTooltipAtMs, tooltipOverlayRef, touchStartRef } = m.tooltip;
+    return (_jsx("div", { ref: tooltipOverlayRef, "data-testid": "chart-tooltip-overlay", className: cn("absolute inset-x-0 top-0", STACKED_AREA_PLOT_HEIGHT_CLASS), onPointerMove: (event) => {
+            if (event.pointerType === "mouse")
+                setSelectedTooltipAtMs(bucketAtMsUnderPointer(m, event));
+        }, onPointerLeave: (event) => {
+            if (event.pointerType === "mouse")
+                setSelectedTooltipAtMs(null);
+        }, onPointerDown: (event) => {
+            if (event.pointerType === "mouse")
+                return;
+            touchStartRef.current = { x: event.clientX, y: event.clientY };
+        }, onPointerCancel: () => {
+            touchStartRef.current = null;
+        }, onPointerUp: (event) => {
+            const start = touchStartRef.current;
+            touchStartRef.current = null;
+            if (event.pointerType === "mouse" || start === null)
+                return;
+            const moved = Math.hypot(event.clientX - start.x, event.clientY - start.y);
+            if (moved >= TOOLTIP_TAP_MAX_MOVEMENT_PX)
+                return;
+            const next = bucketAtMsUnderPointer(m, event);
+            setSelectedTooltipAtMs((current) => (current === next ? null : next));
+        }, children: tooltipAtMs !== undefined && renderTooltipCard(m, tooltipAtMs) }));
+}

package/dist/web/widgets/use-drawer-resize.d.ts

@@ -0,0 +1,22 @@
+import { type KeyboardEvent } from "react";
+import { usePointerDrag } from "./use-pointer-drag.ts";
+export type DrawerResizeConfig = {
+    readonly defaultWidthPx?: number;
+    readonly minWidthPx?: number;
+    readonly maxWidthPx?: number;
+};
+export type DrawerResizeState = {
+    readonly minWidthPx: number;
+    readonly resizedWidthPx: number;
+    readonly setResizedWidthPx: (update: number | ((current: number) => number)) => void;
+    readonly maximized: boolean;
+    readonly setMaximized: (update: boolean | ((current: boolean) => boolean)) => void;
+    readonly effectiveWidthPx: number;
+    readonly effectiveMaxWidthPx: () => number;
+};
+export declare function useDrawerResizeState(resize: DrawerResizeConfig | undefined): DrawerResizeState;
+export type DrawerResizeHandle = {
+    readonly handleDrag: ReturnType<typeof usePointerDrag>;
+    readonly onHandleKeyDown: (event: KeyboardEvent<HTMLDivElement>) => void;
+};
+export declare function useDrawerResizeHandle(side: "left" | "right" | "top" | "bottom", resize: DrawerResizeState): DrawerResizeHandle;

package/dist/web/widgets/use-drawer-resize.js

@@ -0,0 +1,52 @@
+import { useState } from "react";
+import { clamp } from "../lib/clamp.js";
+import { defaultWidthFromViewport, MAX_WIDTH_PX, MIN_WIDTH_PX } from "./drawer-sizing.js";
+import { arrowKeyDelta, usePointerDrag } from "./use-pointer-drag.js";
+export function useDrawerResizeState(resize) {
+    const minWidthPx = resize?.minWidthPx ?? MIN_WIDTH_PX;
+    const maxWidthPx = resize?.maxWidthPx ?? MAX_WIDTH_PX;
+    const effectiveMaxWidthPx = () => typeof window === "undefined"
+        ? maxWidthPx
+        : Math.min(maxWidthPx, Math.round(window.innerWidth * 0.9));
+    const [resizedWidthPx, setResizedWidthPx] = useState(() => clamp(resize?.defaultWidthPx ?? defaultWidthFromViewport(), minWidthPx, effectiveMaxWidthPx()));
+    const [maximized, setMaximized] = useState(false);
+    const effectiveWidthPx = maximized ? effectiveMaxWidthPx() : resizedWidthPx;
+    return {
+        minWidthPx,
+        resizedWidthPx,
+        setResizedWidthPx,
+        maximized,
+        setMaximized,
+        effectiveWidthPx,
+        effectiveMaxWidthPx,
+    };
+}
+export function useDrawerResizeHandle(side, resize) {
+    const { minWidthPx, setResizedWidthPx, maximized, setMaximized, effectiveWidthPx } = resize;
+    const { effectiveMaxWidthPx } = resize;
+    const handleDrag = usePointerDrag({
+        onStart: () => {
+            setMaximized(false);
+            return { startWidth: effectiveWidthPx };
+        },
+        onMove: ({ startWidth }, { dx }) => {
+            const signedDelta = side === "right" ? -dx : dx;
+            setResizedWidthPx(clamp(startWidth + signedDelta, minWidthPx, effectiveMaxWidthPx()));
+        },
+    });
+    const onHandleKeyDown = (event) => {
+        const keyDelta = arrowKeyDelta(event);
+        // skip: only horizontal arrow keys resize the drawer
+        if (keyDelta === undefined || keyDelta.dx === 0)
+            return;
+        event.preventDefault();
+        setMaximized(false);
+        const delta = side === "right" ? -keyDelta.dx : keyDelta.dx;
+        // Seed from the currently visible width, not the stale `resizedWidthPx`
+        // state — while maximized, it still holds the pre-maximize value, so a
+        // key press would otherwise jump the drawer back to that old size
+        // instead of resizing relative to what's on screen.
+        setResizedWidthPx((current) => clamp((maximized ? effectiveWidthPx : current) + delta, minWidthPx, effectiveMaxWidthPx()));
+    };
+    return { handleDrag, onHandleKeyDown };
+}

package/dist/web/widgets/use-stacked-area-tooltip.d.ts

@@ -0,0 +1,9 @@
+export declare function useStackedAreaTooltip(times: readonly number[]): {
+    tooltipAtMs: number | undefined;
+    setSelectedTooltipAtMs: import("react").Dispatch<import("react").SetStateAction<number | null>>;
+    tooltipOverlayRef: import("react").RefObject<HTMLDivElement | null>;
+    touchStartRef: import("react").RefObject<{
+        readonly x: number;
+        readonly y: number;
+    } | null>;
+};

package/dist/web/widgets/use-stacked-area-tooltip.js

@@ -0,0 +1,34 @@
+import { useEffect, useRef, useState } from "react";
+export function useStackedAreaTooltip(times) {
+    const [selectedTooltipAtMs, setSelectedTooltipAtMs] = useState(null);
+    // Stored as a time, not an index: a shifted window must not retarget the card to another bucket.
+    const tooltipAtMs = selectedTooltipAtMs !== null && times.includes(selectedTooltipAtMs)
+        ? selectedTooltipAtMs
+        : undefined;
+    const tooltipOverlayRef = useRef(null);
+    const touchStartRef = useRef(null);
+    const isTooltipOpen = tooltipAtMs !== undefined;
+    useEffect(() => {
+        // skip: no tooltip card open, nothing to dismiss
+        if (!isTooltipOpen)
+            return;
+        const closeOnEscape = (event) => {
+            if (event.key === "Escape")
+                setSelectedTooltipAtMs(null);
+        };
+        const closeOnOutsidePointerDown = (event) => {
+            const overlay = tooltipOverlayRef.current;
+            // skip: pointer landed inside the overlay, taps there select a bucket instead
+            if (overlay !== null && event.target instanceof Node && overlay.contains(event.target))
+                return;
+            setSelectedTooltipAtMs(null);
+        };
+        document.addEventListener("keydown", closeOnEscape);
+        document.addEventListener("pointerdown", closeOnOutsidePointerDown);
+        return () => {
+            document.removeEventListener("keydown", closeOnEscape);
+            document.removeEventListener("pointerdown", closeOnOutsidePointerDown);
+        };
+    }, [isTooltipOpen]);
+    return { tooltipAtMs, setSelectedTooltipAtMs, tooltipOverlayRef, touchStartRef };
+}

package/dist/web/widgets/use-stacked-area-window.d.ts

@@ -0,0 +1,20 @@
+import { type ChartWindow, type StackedAreaWindowSelection } from "./chart-window.ts";
+import type { ResolvedStackedAreaProps } from "./stacked-area-props.ts";
+export declare function useStackedAreaWindow(props: ResolvedStackedAreaProps): {
+    isControlled: boolean;
+    selection: StackedAreaWindowSelection | undefined;
+    changeSelection: (next: StackedAreaWindowSelection) => void;
+    allTimes: readonly number[];
+    visibleWindow: ChartWindow;
+    windowStartMs: number;
+    windowEndMs: number;
+    formatBucket: (atMs: number) => string;
+    tierTicks: (readonly number[])[];
+    formatMarkerTimeInWindow: ((atMs: number) => string) | undefined;
+    series: readonly import("./chart-data.ts").ChartSeries[];
+    lines: readonly import("./chart-data.ts").ChartLine[];
+    markers: readonly import("./chart-data.ts").ChartMarker[] | undefined;
+    times: readonly number[];
+    fractionOf: (atMs: number) => number;
+    todayFraction: number | undefined;
+};

package/dist/web/widgets/use-stacked-area-window.js

@@ -0,0 +1,76 @@
+import { useMemo, useState } from "react";
+import { bucketTimes } from "./chart-data.js";
+import { initialWindowSelection, pointsWithin, resolveStackedAreaWindow, stackedAreaAxisTicks, stackedAreaDateFormatFor, } from "./chart-window.js";
+import { AXIS_TIERS } from "./stacked-area-geometry.js";
+function resolveVisibleWindow(props, selection, allTimes) {
+    const { ranges, brush, todayMs } = props;
+    const fullWindow = { startMs: props.windowStartMs, endMs: props.windowEndMs };
+    const isWindowing = ranges !== undefined || brush || selection !== undefined;
+    if (!isWindowing)
+        return fullWindow;
+    return resolveStackedAreaWindow({
+        selection,
+        ranges,
+        brush,
+        todayMs,
+        bucketTimes: allTimes,
+        fullWindow,
+    });
+}
+function restrictToWindow(props, visibleWindow) {
+    const { series: allSeries, lines: allLines, markers: allMarkers } = props;
+    const isNarrowed = visibleWindow.startMs !== props.windowStartMs || visibleWindow.endMs !== props.windowEndMs;
+    if (!isNarrowed)
+        return { series: allSeries, lines: allLines, markers: allMarkers };
+    return {
+        series: allSeries.map((s) => ({ ...s, points: pointsWithin(s.points, visibleWindow) })),
+        lines: allLines.map((line) => ({ ...line, points: pointsWithin(line.points, visibleWindow) })),
+        markers: allMarkers !== undefined ? pointsWithin(allMarkers, visibleWindow) : allMarkers,
+    };
+}
+export function useStackedAreaWindow(props) {
+    const { ranges, initialWindow, windowSelection, onWindowSelectionChange } = props;
+    const { dateFormat, timeZone, formatBucketLabel, formatMarkerTime, todayMs } = props;
+    const [internalSelection, setInternalSelection] = useState(initialWindowSelection(ranges, initialWindow));
+    const isControlled = onWindowSelectionChange !== undefined;
+    const selection = isControlled ? windowSelection : internalSelection;
+    const changeSelection = (next) => {
+        if (isControlled)
+            onWindowSelectionChange(next);
+        else
+            setInternalSelection(next);
+    };
+    const allTimes = bucketTimes([...props.series, ...props.lines]);
+    const visibleWindow = resolveVisibleWindow(props, selection, allTimes);
+    const windowStartMs = visibleWindow.startMs;
+    const windowEndMs = visibleWindow.endMs;
+    const effectiveDateFormat = dateFormat ?? stackedAreaDateFormatFor(visibleWindow);
+    const formatBucket = (atMs) => formatBucketLabel(atMs, effectiveDateFormat);
+    const tierTicks = useMemo(() => AXIS_TIERS.map((tier) => stackedAreaAxisTicks({ startMs: windowStartMs, endMs: windowEndMs }, tier.maxLabels, effectiveDateFormat, timeZone)), [windowStartMs, windowEndMs, effectiveDateFormat, timeZone]);
+    const formatMarkerTimeInWindow = formatMarkerTime === undefined
+        ? undefined
+        : (atMs) => formatMarkerTime(atMs, effectiveDateFormat);
+    const { series, lines, markers } = restrictToWindow(props, visibleWindow);
+    const times = bucketTimes([...series, ...lines]);
+    const span = Math.max(1, windowEndMs - windowStartMs);
+    const fractionOf = (atMs) => Math.max(0, Math.min(1, (atMs - windowStartMs) / span));
+    const todayFraction = todayMs !== undefined ? fractionOf(todayMs) : undefined;
+    return {
+        isControlled,
+        selection,
+        changeSelection,
+        allTimes,
+        visibleWindow,
+        windowStartMs,
+        windowEndMs,
+        formatBucket,
+        tierTicks,
+        formatMarkerTimeInWindow,
+        series,
+        lines,
+        markers,
+        times,
+        fractionOf,
+        todayFraction,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.388.0",
+  "version": "0.390.0",
   "description": "React renderer for Kumiko screens. The root export holds the platform-agnostic logic (primitives contract, hooks, KumikoScreen, navigation and SSE abstractions); ./headless the DOM-free UI logic, ./live the HTTP dispatcher, ./web the browser bindings (HTML primitives, history navigation, EventSource live events, createKumikoApp).",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -48,8 +48,8 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.388.0",
-    "@cosmicdrift/kumiko-types": "0.388.0",
+    "@cosmicdrift/kumiko-framework": "0.390.0",
+    "@cosmicdrift/kumiko-types": "0.390.0",
     "@radix-ui/react-dialog": "^1.1.15",
     "@radix-ui/react-dropdown-menu": "^2.1.16",
     "@radix-ui/react-label": "^2.1.8",
@@ -59,10 +59,10 @@
     "@radix-ui/react-slot": "^1.2.4",
     "@radix-ui/react-toast": "^1.2.15",
     "@radix-ui/react-tooltip": "^1.2.8",
-    "@tiptap/core": "^3.30.5",
-    "@tiptap/pm": "^3.30.5",
-    "@tiptap/react": "^3.30.5",
-    "@tiptap/starter-kit": "^3.30.5",
+    "@tiptap/core": "^3.31.3",
+    "@tiptap/pm": "^3.31.3",
+    "@tiptap/react": "^3.31.3",
+    "@tiptap/starter-kit": "^3.31.3",
     "@types/qrcode": "^1.5.5",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
@@ -92,8 +92,8 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-locale-de": "0.388.0",
-    "@cosmicdrift/kumiko-testing": "0.388.0",
+    "@cosmicdrift/kumiko-locale-de": "0.390.0",
+    "@cosmicdrift/kumiko-testing": "0.390.0",
     "@tailwindcss/cli": "^4.3.0",
     "@testing-library/react": "^16.3.2",
     "@testing-library/user-event": "^14.6.1",