wiki-formant 0.47.1 → 0.48.0

package/README.md

@@ -820,6 +820,17 @@ straight between closes and a count's is curved.
 `mean` for a count, so the week in progress keeps its level instead of reading
 as a collapse. A single range draws no range buttons and shows every point.
 `bucketChart` and `chartSteps` are exported for a chart drawn elsewhere.
+
+`markers` are events, `{ time, label }`, each drawn as an arrow on the last
+point at or before it, so one mid-week lands on its week and two on one point
+share it (`placeMarkers` does the placing). `step` opens on a step where the
+range can make it, and `onView` hears the range and step on mount and on every
+change, for a page that keeps them in its URL:
+
+```tsx
+<TimeChart series={days} label="Transactions" aggregate="mean" fromZero
+  markers={[{ time: haltAt, label: 'Halt' }]} step="month" onView={v => keep(v)} />
+```
 `base.css` pins the buttons (`.chart-controls button[aria-pressed]`) to the
 canvas's top-left corner, rules a line between groups and dims a disabled step;
 the site's stylesheet gives them and the box a look.

package/dist/chart.d.ts

@@ -18,6 +18,16 @@ export type ChartResolution = 'hour' | '4h' | 'day';
 export type ChartStep = 'day' | 'week' | 'month';
 /** Points by resolution, from `from` (Unix seconds, 0 for all time), oldest first. */
 export type ChartLoader = (resolution: ChartResolution, from: number) => Promise<readonly ChartPoint[]>;
+/** Something that happened at a time, in Unix seconds, drawn on the point that holds it. */
+export type ChartMarker = {
+    time: number;
+    label: string;
+};
+/** The range and step a reader has picked, for a page that keeps them in its URL. */
+export type ChartView = {
+    range: ChartRange;
+    step: ChartStep | null;
+};
 /** Every range, shortest first. A chart fed daily points offers the ones from 30D up. */
 export declare const CHART_RANGES: readonly ChartRange[];
 /** A step is offered once it makes four points, and the default is the finest that makes 200 or fewer. */
@@ -32,6 +42,12 @@ export declare function chartSteps(span: number): {
  * not read as a collapse. Volume is summed.
  */
 export declare function bucketChart(points: readonly ChartPoint[], step: ChartStep, aggregate: 'last' | 'mean'): ChartPoint[];
+/**
+ * Markers on the points drawn: each on the last point at or before it, so one
+ * mid-week sits on its week. Markers on one point share it, labels joined; one
+ * before the first point or after the last point's step is left off.
+ */
+export declare function placeMarkers(markers: readonly ChartMarker[], shown: readonly ChartPoint[], step: ChartStep | null): ChartMarker[];
 /** Compact from a thousand up, four significant figures below. */
 export declare const formatChartValue: (n: number) => string;
 export interface TimeChartProps {
@@ -58,6 +74,12 @@ export interface TimeChartProps {
      * window links, which load another digest rather than slice this one.
      */
     controls?: ReactNode;
+    /** Events drawn on the points that hold them. */
+    markers?: readonly ChartMarker[];
+    /** The step shown first, where the range can make it. */
+    step?: ChartStep;
+    /** Called with the range and step on mount and on every change. */
+    onView?: (view: ChartView) => void;
     className?: string;
 }
 /**
@@ -65,4 +87,4 @@ export interface TimeChartProps {
  * `.chart-controls button[aria-pressed]`, and a site's stylesheet gives them
  * and the box their look; the line and fill are the canvas box's `color`.
  */
-export declare function TimeChart({ series, label, ranges, range: initial, aggregate, fromZero, format, candles: initialCandles, height, controls, className, }: TimeChartProps): import("react").JSX.Element;
+export declare function TimeChart({ series, label, ranges, range: initial, aggregate, fromZero, format, candles: initialCandles, height, controls, markers, step: initialStep, onView, className, }: TimeChartProps): import("react").JSX.Element;

package/dist/chart.js

@@ -8,7 +8,8 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // loaded on mount, so the page paints without it. Every colour is the canvas
 // box's own `color`, its axis `--chart-axis`, and a candle `--chart-up` or
 // `--chart-down`, each if set. A count's line is curved; a price's is straight,
-// since a curve between two closes draws prices nobody paid.
+// since a curve between two closes draws prices nobody paid. Events are markers
+// on the point they fall in, so a spike carries the reason for it.
 import { useEffect, useMemo, useRef, useState } from 'react';
 const DAY = 86_400;
 const RANGE = {
@@ -74,6 +75,29 @@ export function bucketChart(points, step, aggregate) {
     }
     return out;
 }
+/**
+ * Markers on the points drawn: each on the last point at or before it, so one
+ * mid-week sits on its week. Markers on one point share it, labels joined; one
+ * before the first point or after the last point's step is left off.
+ */
+export function placeMarkers(markers, shown, step) {
+    const first = shown[0];
+    const last = shown.at(-1);
+    if (!first || !last)
+        return [];
+    const end = last.time + (step ? STEP[step].span : DAY);
+    const placed = new Map();
+    for (const m of [...markers].sort((a, b) => a.time - b.time)) {
+        if (m.time < first.time || m.time >= end)
+            continue;
+        let i = shown.length - 1;
+        while (i > 0 && shown[i].time > m.time)
+            i--;
+        const time = shown[i].time;
+        placed.set(time, [...(placed.get(time) ?? []), m.label]);
+    }
+    return [...placed].map(([time, labels]) => ({ time, label: labels.join(' · ') }));
+}
 const isCandle = (p) => p.open !== undefined && p.high !== undefined && p.low !== undefined;
 const compact = new Intl.NumberFormat('en', { notation: 'compact', maximumFractionDigits: 2 });
 const precise = new Intl.NumberFormat('en', { maximumSignificantDigits: 4 });
@@ -102,14 +126,16 @@ const fromZeroScale = (base) => {
  * `.chart-controls button[aria-pressed]`, and a site's stylesheet gives them
  * and the box their look; the line and fill are the canvas box's `color`.
  */
-export function TimeChart({ series, label, ranges = typeof series === 'function' ? CHART_RANGES : DAILY_RANGES, range: initial = ranges.includes('30d') ? '30d' : ranges[0], aggregate = 'last', fromZero = false, format = formatChartValue, candles: initialCandles = false, height, controls, className, }) {
+export function TimeChart({ series, label, ranges = typeof series === 'function' ? CHART_RANGES : DAILY_RANGES, range: initial = ranges.includes('30d') ? '30d' : ranges[0], aggregate = 'last', fromZero = false, format = formatChartValue, candles: initialCandles = false, height, controls, markers, step: initialStep, onView, className, }) {
     const box = useRef(null);
     const chart = useRef(null);
     const formatRef = useRef(format);
     formatRef.current = format;
+    const onViewRef = useRef(onView);
+    onViewRef.current = onView;
     const [ready, setReady] = useState(false);
     const [range, setRange] = useState(initial);
-    const [step, setStep] = useState(null);
+    const [step, setStep] = useState(initialStep ?? null);
     const [candles, setCandles] = useState(initialCandles);
     const [loaded, setLoaded] = useState(null);
     const resolution = RANGE[range].resolution;
@@ -118,7 +144,7 @@ export function TimeChart({ series, label, ranges = typeof series === 'function'
         if (!el)
             return;
         let disposed = false;
-        import('lightweight-charts').then(({ createChart, AreaSeries, CandlestickSeries, HistogramSeries, ColorType, CrosshairMode, LineStyle, LineType }) => {
+        import('lightweight-charts').then(({ createChart, createSeriesMarkers, AreaSeries, CandlestickSeries, HistogramSeries, ColorType, CrosshairMode, LineStyle, LineType }) => {
             if (disposed)
                 return;
             const style = getComputedStyle(el);
@@ -177,7 +203,11 @@ export function TimeChart({ series, label, ranges = typeof series === 'function'
                 api.panes()[1]?.setStretchFactor(1);
                 return volume;
             };
-            chart.current = { api, area, candle, volume: null, addVolume, up, down };
+            chart.current = {
+                api, area, candle, volume: null, addVolume, up, down, ink,
+                areaMarkers: createSeriesMarkers(area, []),
+                candleMarkers: createSeriesMarkers(candle, []),
+            };
             setReady(true);
         });
         return () => {
@@ -259,8 +289,21 @@ export function TimeChart({ series, label, ranges = typeof series === 'function'
             const rising = p.value >= (p.open ?? shown[i - 1]?.value ?? p.value);
             return { time: time(p), value: p.volume ?? 0, color: (rising ? c.up : c.down).replace(/[\d.]+\)$/, '0.5)') };
         }));
+        const drawn = placeMarkers(markers ?? [], shown, view?.step ?? null).map(m => ({
+            time: time(m),
+            position: 'aboveBar',
+            shape: 'arrowDown',
+            color: c.ink,
+            text: m.label,
+        }));
+        c.areaMarkers.setMarkers(asCandles ? [] : drawn);
+        c.candleMarkers.setMarkers(asCandles ? drawn : []);
         c.api.timeScale().fitContent();
-    }, [ready, source, view, candles]);
+    }, [ready, source, view, candles, markers]);
+    const shownStep = view?.step ?? null;
+    useEffect(() => {
+        onViewRef.current?.({ range, step: shownStep });
+    }, [range, shownStep]);
     // The steps always show where a range is drawn by day, so the buttons do not jump about; one
     // the range cannot make (any, under 24H and 7D) is disabled.
     const daily = ranges.some(r => RANGE[r].resolution === 'day');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-formant",
-  "version": "0.47.1",
+  "version": "0.48.0",
   "description": "The portable half of a wiki: derived taxonomy and facet controls, a version-negotiating MCP transport, markdown twins, block rendering, a rich-text editor engine, conditional-GET plumbing, and the headers and CSP every origin sends.",
   "type": "module",
   "license": "MIT",