wiki-formant 0.36.0 → 0.37.0

package/README.md

@@ -753,9 +753,16 @@ monthly.
 
 // A loader: asked for 'hour' (24H), '4h' (7D) or 'day' from 0 (every longer
 // range), once each.
-<TimeChart series={load} label="Price" format={formatPrice} range="30d" />
+<TimeChart series={load} label="Price" format={formatPrice} range="30d" candles />
 ```
 
+A price point may carry `open`, `high` and `low` (its `value` is the close)
+and `volume`. Points that carry the candle get a Line/Candles toggle, opening on
+candles with `candles`; points that carry volume get a volume pane under the
+price, a fifth of the height. Candles take `--chart-up` and `--chart-down` from
+the canvas box, else its `color`. A week of candles opens on its first, closes
+on its last, spans the highest high and lowest low, and sums its volume.
+
 `aggregate` is how a week or month is made from its days: `last` for a price,
 `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.

package/dist/chart.d.ts

@@ -1,7 +1,14 @@
-/** One value at a time in Unix seconds, UTC. */
+/**
+ * One value at a time in Unix seconds, UTC. A price may carry the rest of its
+ * candle, `value` being the close, and the volume traded in it.
+ */
 export type ChartPoint = {
     time: number;
     value: number;
+    open?: number;
+    high?: number;
+    low?: number;
+    volume?: number;
 };
 export type ChartRange = '24h' | '7d' | '30d' | '90d' | '1y' | 'all';
 /** What a loader is asked for: hours for 24H, four hours for 7D, days for every longer range. */
@@ -19,8 +26,9 @@ export declare function chartSteps(span: number): {
 };
 /**
  * Points, oldest first, one per step. A price keeps the last value in each
- * step; a count takes the mean of its days, so the week in progress does not
- * read as a collapse.
+ * step, as a candle does its close: the first open, the highest high, the
+ * lowest low. A count takes the mean of its days, so the week in progress does
+ * not read as a collapse. Volume is summed.
  */
 export declare function bucketChart(points: readonly ChartPoint[], step: ChartStep, aggregate: 'last' | 'mean'): ChartPoint[];
 /** Compact from a thousand up, four significant figures below. */
@@ -40,13 +48,15 @@ export interface TimeChartProps {
     fromZero?: boolean;
     /** The value axis and crosshair label. Read on every draw, so it need not be stable. */
     format?: (n: number) => string;
+    /** Open on candles, where the points carry them. A Line/Candles toggle shows either way. */
+    candles?: boolean;
     /** In pixels. Otherwise the stylesheet's `--chart-height`, else 15rem. */
     height?: number;
     className?: string;
 }
 /**
- * A time series with its range and step buttons. The buttons are
+ * A time series with its range, step and style buttons. The buttons are
  * `.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, height, className, }: TimeChartProps): import("react").JSX.Element;
+export declare function TimeChart({ series, label, ranges, range: initial, aggregate, fromZero, format, candles: initialCandles, height, className, }: TimeChartProps): import("react").JSX.Element;

package/dist/chart.js

@@ -3,8 +3,11 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // chart.tsx — one time series as an area chart: the token, activity and visitor
 // charts on every site. Ranges run from 24 hours to all time, and a long range
 // steps by day, week or month, so three years do not draw as a thousand points.
-// `lightweight-charts` is loaded on mount, so the page paints without it. Every
-// colour is the canvas box's own `color`, and its axis `--chart-axis` if set.
+// A price that carries its open, high and low can be drawn as candles, and one
+// that carries volume gets a volume pane under it. `lightweight-charts` is
+// 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.
 import { useEffect, useMemo, useRef, useState } from 'react';
 const DAY = 86_400;
 const RANGE = {
@@ -41,23 +44,35 @@ function bucketStart(time, step) {
 }
 /**
  * Points, oldest first, one per step. A price keeps the last value in each
- * step; a count takes the mean of its days, so the week in progress does not
- * read as a collapse.
+ * step, as a candle does its close: the first open, the highest high, the
+ * lowest low. A count takes the mean of its days, so the week in progress does
+ * not read as a collapse. Volume is summed.
  */
 export function bucketChart(points, step, aggregate) {
     const out = [];
-    for (const { time, value } of points) {
-        const start = bucketStart(time, step);
+    let n = 0;
+    for (const p of points) {
+        const start = bucketStart(p.time, step);
         const last = out.at(-1);
-        if (last?.time !== start)
-            out.push({ time: start, value, n: 1 });
-        else if (aggregate === 'last')
-            last.value = value;
+        if (last?.time !== start) {
+            out.push({ ...p, time: start });
+            n = 1;
+            continue;
+        }
+        if (aggregate === 'last')
+            last.value = p.value;
         else
-            last.value += (value - last.value) / ++last.n;
+            last.value += (p.value - last.value) / ++n;
+        if (last.high !== undefined && p.high !== undefined)
+            last.high = Math.max(last.high, p.high);
+        if (last.low !== undefined && p.low !== undefined)
+            last.low = Math.min(last.low, p.low);
+        if (p.volume !== undefined)
+            last.volume = (last.volume ?? 0) + p.volume;
     }
-    return out.map(({ time, value }) => ({ time, value }));
+    return out;
 }
+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 });
 /** Compact from a thousand up, four significant figures below. */
@@ -81,11 +96,11 @@ const fromZeroScale = (base) => {
     return info;
 };
 /**
- * A time series with its range and step buttons. The buttons are
+ * A time series with its range, step and style buttons. The buttons are
  * `.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, height, 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, className, }) {
     const box = useRef(null);
     const chart = useRef(null);
     const formatRef = useRef(format);
@@ -93,6 +108,7 @@ export function TimeChart({ series, label, ranges = typeof series === 'function'
     const [ready, setReady] = useState(false);
     const [range, setRange] = useState(initial);
     const [step, setStep] = useState(null);
+    const [candles, setCandles] = useState(initialCandles);
     const [loaded, setLoaded] = useState(null);
     const resolution = RANGE[range].resolution;
     useEffect(() => {
@@ -100,12 +116,15 @@ export function TimeChart({ series, label, ranges = typeof series === 'function'
         if (!el)
             return;
         let disposed = false;
-        import('lightweight-charts').then(({ createChart, AreaSeries, ColorType, CrosshairMode, LineStyle, LineType }) => {
+        import('lightweight-charts').then(({ createChart, AreaSeries, CandlestickSeries, HistogramSeries, ColorType, CrosshairMode, LineStyle, LineType }) => {
             if (disposed)
                 return;
             const style = getComputedStyle(el);
             const axis = style.getPropertyValue('--chart-axis').trim();
             const ink = rgba(style.color);
+            const up = rgba(style.getPropertyValue('--chart-up').trim() || style.color);
+            const down = rgba(style.getPropertyValue('--chart-down').trim() || style.color, style.getPropertyValue('--chart-down').trim() ? 1 : 0.45);
+            const priceFormat = { type: 'custom', formatter: (n) => formatRef.current(n), minMove: 1e-12 };
             const guide = { color: rgba(style.color, 0.4), width: 1, style: LineStyle.Dotted, labelBackgroundColor: ink };
             const api = createChart(el, {
                 autoSize: true,
@@ -130,13 +149,30 @@ export function TimeChart({ series, label, ranges = typeof series === 'function'
                 lineType: LineType.Curved,
                 crosshairMarkerBackgroundColor: ink,
                 crosshairMarkerBorderColor: ink,
-                priceFormat: { type: 'custom', formatter: (n) => formatRef.current(n), minMove: 1e-12 },
+                priceFormat,
                 ...(fromZero && { autoscaleInfoProvider: fromZeroScale }),
             });
+            const candle = api.addSeries(CandlestickSeries, {
+                visible: false,
+                upColor: up,
+                downColor: down,
+                borderUpColor: up,
+                borderDownColor: down,
+                wickUpColor: up,
+                wickDownColor: down,
+                priceFormat,
+            });
             // The chart cannot be scrolled or zoomed, so every size it takes shows every point,
             // the first included: data drawn before autoSize has measured the box fits nothing.
             api.timeScale().subscribeSizeChange(() => api.timeScale().fitContent());
-            chart.current = { api, area };
+            // Volume takes a pane of its own under the price, a fifth of the height.
+            const addVolume = () => {
+                const volume = api.addSeries(HistogramSeries, { priceFormat: { type: 'volume' }, priceLineVisible: false, lastValueVisible: false }, 1);
+                api.panes()[0]?.setStretchFactor(4);
+                api.panes()[1]?.setStretchFactor(1);
+                return volume;
+            };
+            chart.current = { api, area, candle, volume: null, addVolume, up, down };
             setReady(true);
         });
         return () => {
@@ -175,20 +211,46 @@ export function TimeChart({ series, label, ranges = typeof series === 'function'
         const end = points.at(-1).time;
         const span = RANGE[range].span;
         const windowed = span === Infinity || ranges.length < 2 ? points : points.filter(p => p.time > Date.now() / 1000 - span);
+        const drawn = (shown, steps, step) => ({
+            shown,
+            steps,
+            step,
+            ohlc: aggregate === 'last' && shown.length > 0 && shown.every(isCandle),
+            volume: shown.some(p => p.volume !== undefined),
+        });
         if (resolution !== 'day' || !windowed.length)
-            return { shown: windowed, steps: [], step: null };
+            return drawn(windowed, [], null);
         const { steps, fallback } = chartSteps(end - windowed[0].time);
         const chosen = step && steps.includes(step) ? step : fallback;
-        return { shown: chosen === 'day' ? windowed : bucketChart(windowed, chosen, aggregate), steps, step: chosen };
+        return drawn(chosen === 'day' ? windowed : bucketChart(windowed, chosen, aggregate), steps, chosen);
     }, [points, range, ranges.length, resolution, step, aggregate]);
     // While a resolution loads, the last one stays under the skeleton; an empty or failed one clears it.
     useEffect(() => {
-        if (!ready || !chart.current || !source)
+        const c = chart.current;
+        if (!ready || !c || !source)
             return;
-        chart.current.api.applyOptions({ timeScale: { timeVisible: source.resolution !== 'day' } });
-        chart.current.area.setData((view?.shown ?? []).map(p => ({ time: p.time, value: p.value })));
-        chart.current.api.timeScale().fitContent();
-    }, [ready, source, view]);
+        const shown = view?.shown ?? [];
+        const asCandles = candles && !!view?.ohlc;
+        const time = (p) => p.time;
+        c.api.applyOptions({ timeScale: { timeVisible: source.resolution !== 'day' } });
+        c.area.applyOptions({ visible: !asCandles });
+        c.candle.applyOptions({ visible: asCandles });
+        c.area.setData(asCandles ? [] : shown.map(p => ({ time: time(p), value: p.value })));
+        c.candle.setData(asCandles ? shown.map(p => ({ time: time(p), open: p.open, high: p.high, low: p.low, close: p.value })) : []);
+        if (view?.volume && !c.volume)
+            c.volume = c.addVolume();
+        else if (!view?.volume && c.volume) {
+            c.api.removeSeries(c.volume);
+            c.volume = null;
+            if (c.api.panes().length > 1)
+                c.api.removePane(1);
+        }
+        c.volume?.setData(shown.map((p, i) => {
+            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)') };
+        }));
+        c.api.timeScale().fitContent();
+    }, [ready, source, view, candles]);
     const status = source && 'error' in source ? source.error : points && !view?.shown.length ? 'No data in this range' : null;
-    return (_jsxs("figure", { className: className ? `chart ${className}` : 'chart', children: [_jsx("div", { ref: box, className: "chart-canvas", role: "img", "aria-label": label, style: height ? { height } : undefined }), (!ready || (!points && !status)) && _jsx("div", { className: "chart-status skeleton", "aria-hidden": true }), status && _jsx("p", { className: "chart-status", children: status }), (ranges.length > 1 || (view && view.steps.length > 1)) && (_jsxs("div", { className: "chart-controls", children: [ranges.length > 1 && (_jsx("div", { role: "group", "aria-label": "Range", children: ranges.map(r => (_jsx("button", { type: "button", "aria-pressed": r === range, onClick: () => { setRange(r); setStep(null); }, children: RANGE[r].label }, r))) })), view && view.steps.length > 1 && (_jsx("div", { role: "group", "aria-label": "Step", children: view.steps.map(s => (_jsx("button", { type: "button", "aria-pressed": s === view.step, onClick: () => setStep(s), title: `One point per ${s}`, children: STEP[s].label }, s))) }))] }))] }));
+    return (_jsxs("figure", { className: className ? `chart ${className}` : 'chart', children: [_jsx("div", { ref: box, className: "chart-canvas", role: "img", "aria-label": label, style: height ? { height } : undefined }), (!ready || (!points && !status)) && _jsx("div", { className: "chart-status skeleton", "aria-hidden": true }), status && _jsx("p", { className: "chart-status", children: status }), (ranges.length > 1 || (view && (view.steps.length > 1 || view.ohlc))) && (_jsxs("div", { className: "chart-controls", children: [ranges.length > 1 && (_jsx("div", { role: "group", "aria-label": "Range", children: ranges.map(r => (_jsx("button", { type: "button", "aria-pressed": r === range, onClick: () => { setRange(r); setStep(null); }, children: RANGE[r].label }, r))) })), view && view.steps.length > 1 && (_jsx("div", { role: "group", "aria-label": "Step", children: view.steps.map(s => (_jsx("button", { type: "button", "aria-pressed": s === view.step, onClick: () => setStep(s), title: `One point per ${s}`, children: STEP[s].label }, s))) })), view?.ohlc && (_jsxs("div", { role: "group", "aria-label": "Style", children: [_jsx("button", { type: "button", "aria-pressed": !candles, onClick: () => setCandles(false), children: "Line" }), _jsx("button", { type: "button", "aria-pressed": candles, onClick: () => setCandles(true), children: "Candles" })] }))] }))] }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-formant",
-  "version": "0.36.0",
+  "version": "0.37.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",