@djangocfg/ui-tools 2.1.430 → 2.1.432

package/src/tools/visual/charts/SmoothLine/README.md

@@ -0,0 +1,97 @@
+# SmoothLine
+
+Animated sibling of [`Sparkline`](../Sparkline/README.md). Same pure-SVG family
+(fixed viewBox, `preserveAspectRatio="none"`, `vectorEffect="non-scaling-stroke"`),
+but with **two** kinds of smoothness:
+
+1. **Curve smoothness (the line SHAPE).** The line is drawn as a flowing
+   **Catmull-Rom → cubic-bezier curve** through the points (`M … C …`), not a
+   jagged `M … L …` polyline — so it flows in gentle curves instead of kinking
+   at each data point. Controlled by `tension` (default `0.5`; `0` degenerates
+   to straight `L` segments — the disable path for charts that want SHARP
+   geometry like an ECG QRS spike). This is pure geometry: the curve is rebuilt
+   from the points each frame, so it both flows AND glides.
+2. **Streaming smoothness (the MOTION).** With `scroll` on, the trace slides
+   left at **constant velocity** like a hospital monitor (the professional
+   D3/Smoothie model) instead of snapping the `d` each tick. We animate exactly
+   ONE thing — a `translateX` on the scroll group — and the position is a pure
+   function of the **wall clock**, so it is frame-rate independent and never
+   eased. The path `d` is rebuilt **once per data change** from the true values
+   (no per-frame Y-tween), and the newest point is appended **off-screen** behind
+   a one-interval `delay` buffer + `clipPath`, so the visible window only ever
+   scrolls into view — it never changes shape instantly.
+
+   **The velocity is driven by the MEASURED data cadence, not a hardcoded
+   `tweenMs`.** The engine records each datum's arrival time and EMAs the deltas
+   into a smoothed interval; the slide velocity is `slotWidth / measuredInterval`.
+   That is what makes a **jittery 1 Hz feed** (the Go stats ticker + Wails event
+   bus add ±100-200 ms) still glide at a steady speed: a late sample lets the
+   phase glide *past* one slot into the buffer (no freeze-then-snap), and the
+   leftover phase is carried across the commit seam (no per-tick teleport).
+   `tweenMs` is now only the **seed/clamp** for the very first slides before any
+   delta is measured — the engine adapts to the true rate within a couple ticks.
+
+```tsx
+import { SmoothLine } from '@djangocfg/ui-tools/smooth-line';
+
+// stats charts tick ≈ 1 Hz
+<SmoothLine values={rtt} color="info" tweenMs={1000} area />
+
+// token bridge — inherit a text-* className tint (cmdop's text-chart-3)
+<span className="text-chart-3">
+  <SmoothLine values={rtt} color="currentColor" />
+</span>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `values` | `readonly number[]` | — | Series, oldest-first. Empty → flat baseline. |
+| `color` | `SmoothLineColor` | `'primary'` | Semantic token, or `'currentColor'` to inherit a `text-*` tint. |
+| `width` | `number` | `240` | viewBox width (SVG stretches to its container). |
+| `height` | `number` | `40` | viewBox height (px). |
+| `strokeWidth` | `number` | `1.5` | Line stroke. |
+| `area` | `boolean` | `false` | Alpha area fill under the line. |
+| `tweenMs` | `number` | `1000` | **Seed** cadence (ms) for the scroll velocity + the clamp band — NOT a fixed slide speed. The engine measures the real inter-sample interval and drives the velocity off that. Pass the rough expected cadence (stats ≈ 1000, quality ≈ 30000). |
+| `scroll` | `boolean` | `false` | Continuous constant-velocity left-scroll for live windowed charts. |
+| `delay` | `boolean` | `true` | Hold the right edge back one interval (buffer the newest point off-screen) so it scrolls in cleanly instead of "grow then snap". Requires `scroll`. |
+| `tension` | `number` | `0.5` | Curve smoothness (the line SHAPE). `0` → straight `L` segments; `0.5` → flowing curve; `1` → loosest. |
+| `ariaLabel` | `string` | — | Accessible label. |
+
+### Curve smoothing — for host-bespoke charts
+
+The Catmull-Rom → bezier converter is exported so host charts that build their
+own geometry (cmdop's TrafficChart mirror areas) can get the same flowing curve:
+
+```ts
+import { smoothLinePath, smoothSegments } from '@djangocfg/ui-tools/smooth-line';
+
+// full path through points (line stroke)
+const d = smoothLinePath(points, 0.5, { width, height });
+// just the C-segments (so an area fill can reuse the exact same curve)
+const body = smoothSegments(points, 0.5, { width, height });
+```
+
+The **ECG keeps its bespoke SHARP builder** (sharp QRS pulses) and does NOT use
+this — a cardiogram needs sharp pulses, not rounded blobs. It reuses only the
+glide+scroll engine (`useSmoothSeries`), not the curve smoothing.
+
+## `useSmoothSeries`
+
+The rAF engine is exported as a hook so host-bespoke charts (e.g. cmdop's ECG,
+which keeps its own QRS geometry) can reuse the same glide + scroll driver:
+
+```tsx
+const { pathRef, scrollRef, staticPath } = useSmoothSeries({
+  values, tweenMs: 1000, scroll: true, width: 240, buildPath: buildMyGeometry,
+});
+```
+
+`buildPath` receives the true values **once per data change** (not per frame) and
+returns the `d` string; only the scroll transform updates per frame. The velocity
+is self-measured from the data cadence (see above), so hosts don't need an exact
+`tweenMs`. Guards (reduced-motion fallback to instant, pause on `document.hidden`)
+are built in; `staticPath` is the initial / reduced-motion render value.
+
+Storybook: `apps/storybook/stories/ui-tools/visual/SmoothLine.stories.tsx`

package/src/tools/visual/charts/SmoothLine/SmoothLine.tsx

@@ -0,0 +1,177 @@
+// SmoothLine — the streaming sibling of Sparkline, now drawn on a CANVAS.
+//
+// The trace SCROLLS left at constant velocity via the `useSmoothSeries`
+// wall-clock canvas engine: every rAF frame the whole monotone-cubic curve is
+// redrawn at its scrolled X (one writer, one clock), so there is no SVG-era
+// path/transform desync — the jump-then-catch-up is gone by construction.
+//
+// Geometry stays ours: the draw callback strokes a monotone-cubic (Fritsch–
+// Carlson / d3 `curveMonotoneX`) polyline through the data points, with an
+// optional area fill closed to the baseline. `tension={0}` degenerates to sharp
+// straight segments.
+//
+// Color via the token bridge, resolved ONCE per theme change (not per frame):
+//   • a semantic token (`'primary' | 'success' | …`) → `useThemeColor()` → hex.
+//   • `'currentColor'` → the canvas inherits an ancestor's CSS `color` (a `text-*`
+//     className tint, e.g. cmdop's `text-chart-*`); we read the resolved color off
+//     the canvas element via `getComputedStyle(canvas).color` and pass it to
+//     `ctx.strokeStyle`. Re-resolved on theme change (the resolved-theme dep on
+//     `useThemeColor`'s own re-render path drives a redraw).
+//
+// Requires <UiProviders> mounted by the host app (no nested providers here).
+
+'use client';
+
+import * as React from 'react';
+import { cn } from '@djangocfg/ui-core/lib';
+import { useThemeColor } from '@djangocfg/ui-core/styles/palette';
+import { useResolvedTheme } from '@djangocfg/ui-core/hooks';
+import type { SmoothLineProps } from './types';
+import { useSmoothSeries, type DrawFn } from './useSmoothSeries';
+import { DEFAULT_TENSION, type Pt, traceSmoothSegments } from './smoothPath';
+
+/**
+ * Map oldest-first values to logical points (shared by the line + area draws).
+ *
+ * The Y-domain (min/max) is computed from the drawn values. Because the engine
+ * draws from a FIXED committed set between ticks (no per-frame Y-tween), the
+ * domain is stable across the whole scroll — the curve never rubber-bands.
+ */
+function valuePoints(
+  values: readonly number[],
+  width: number,
+  height: number,
+): Pt[] {
+  const max = Math.max(...values, 1);
+  const min = Math.min(...values, 0);
+  const span = max - min || 1;
+  const stepX = values.length > 1 ? width / (values.length - 1) : width;
+  return values.map((v, i) => ({
+    x: i * stepX,
+    y: height - ((v - min) / span) * (height - 2) - 1,
+  }));
+}
+
+export function SmoothLine({
+  values,
+  color = 'primary',
+  width = 240,
+  height = 40,
+  strokeWidth = 1.5,
+  area = false,
+  tweenMs = 1000,
+  scroll = false,
+  delay = true,
+  tension = DEFAULT_TENSION,
+  ariaLabel,
+  className,
+  ...rest
+}: SmoothLineProps) {
+  const isBridge = color === 'currentColor';
+  // Semantic token → hex; bridge mode reads the canvas's inherited CSS color.
+  const themeColor = useThemeColor(isBridge ? 'primary' : color);
+  // Re-resolve the bridge color when the theme flips (dark/light).
+  const resolvedTheme = useResolvedTheme();
+
+  // With the right-edge lag, the drawn set drops the freshest point so the right
+  // edge is always a known point; the engine's scroll reveals the off-edge value.
+  const useLag = scroll && delay && values.length > 2;
+  const drawn = React.useMemo(
+    () => (useLag ? [...values].slice(0, -1) : [...values]),
+    // values identity changes per tick; the joined key gates recompute.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [values.join(','), useLag],
+  );
+
+  // The per-frame canvas draw: monotone-cubic stroke (+ optional area), at the
+  // scrolled X. Rebuilt when the committed values / geometry / color change — so
+  // there is no per-frame Y-tween, only the scroll moves.
+  const draw = React.useCallback<DrawFn>(
+    (ctx, frame) => {
+      // Resolve the stroke/fill color ONCE per draw (not a per-point cost). In
+      // bridge mode read the inherited CSS color off the canvas; else the token.
+      let stroke = themeColor;
+      if (isBridge && ctx.canvas) {
+        const c = getComputedStyle(ctx.canvas).color;
+        if (c) stroke = c;
+      }
+
+      const w = frame.width;
+      const h = frame.height;
+      const sx = frame.scrollX;
+
+      if (drawn.length === 0) {
+        const mid = h / 2;
+        ctx.beginPath();
+        ctx.moveTo(0, mid);
+        ctx.lineTo(w, mid);
+        ctx.strokeStyle = stroke;
+        ctx.lineWidth = strokeWidth;
+        ctx.stroke();
+        return;
+      }
+
+      const pts = valuePoints(drawn, w, h).map((p) => ({
+        x: p.x + sx,
+        y: p.y,
+      }));
+
+      // Area fill first (under the stroke), hugging the same curve down to the
+      // baseline. Opacity 0.12 matches the old SVG fill.
+      if (area) {
+        ctx.beginPath();
+        ctx.moveTo(pts[0].x, h);
+        ctx.lineTo(pts[0].x, pts[0].y);
+        traceSmoothSegments(ctx, pts, tension);
+        ctx.lineTo(pts[pts.length - 1].x, h);
+        ctx.closePath();
+        ctx.globalAlpha = 0.12;
+        ctx.fillStyle = stroke;
+        ctx.fill();
+        ctx.globalAlpha = 1;
+      }
+
+      // Stroke the line over the fill.
+      ctx.beginPath();
+      ctx.moveTo(pts[0].x, pts[0].y);
+      traceSmoothSegments(ctx, pts, tension);
+      ctx.strokeStyle = stroke;
+      ctx.lineWidth = strokeWidth;
+      ctx.lineJoin = 'round';
+      ctx.lineCap = 'round';
+      ctx.stroke();
+    },
+    // resolvedTheme re-runs the bridge color read on a theme flip.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [drawn, area, tension, strokeWidth, themeColor, isBridge, resolvedTheme],
+  );
+
+  const { canvasRef } = useSmoothSeries({
+    values,
+    tweenMs,
+    scroll,
+    delay,
+    width,
+    height,
+    draw,
+  });
+
+  return (
+    <div
+      data-slot="smooth-line"
+      data-color={color}
+      className={cn('block w-full', className)}
+      style={isBridge ? undefined : { color: themeColor }}
+      {...rest}
+    >
+      <canvas
+        ref={canvasRef}
+        className="block w-full"
+        style={{ height, color: isBridge ? undefined : themeColor }}
+        role="img"
+        aria-label={ariaLabel}
+        aria-hidden={ariaLabel ? undefined : true}
+      />
+    </div>
+  );
+}

package/src/tools/visual/charts/SmoothLine/index.ts

@@ -0,0 +1,21 @@
+export { SmoothLine } from './SmoothLine';
+export {
+  useSmoothSeries,
+  useReducedMotion,
+  type DrawFn,
+  type DrawContext,
+  type SmoothSeriesConfig,
+  type SmoothSeriesHandles,
+} from './useSmoothSeries';
+export {
+  DEFAULT_TENSION,
+  smoothLinePath,
+  smoothSegments,
+  traceSmoothSegments,
+  type Pt,
+} from './smoothPath';
+export type {
+  SmoothLineProps,
+  SmoothLineColor,
+  SmoothSeriesOptions,
+} from './types';

package/src/tools/visual/charts/SmoothLine/lazy.tsx

@@ -0,0 +1,23 @@
+'use client';
+
+import { createLazyComponent } from '../../../../common/lazy-wrapper';
+import type { SmoothLineProps } from './types';
+
+export const LazySmoothLine = createLazyComponent<SmoothLineProps>(
+  () => import('./SmoothLine').then((mod) => ({ default: mod.SmoothLine })),
+  {
+    displayName: 'LazySmoothLine',
+    fallback: (
+      <span
+        data-slot="smooth-line-skeleton"
+        className="block h-10 w-full animate-pulse rounded bg-muted"
+      />
+    ),
+  },
+);
+
+export type {
+  SmoothLineProps,
+  SmoothLineColor,
+  SmoothSeriesOptions,
+} from './types';

package/src/tools/visual/charts/SmoothLine/smoothPath.ts

@@ -0,0 +1,209 @@
+// smoothPath — turn a polyline of points into a flowing SMOOTH curve.
+//
+// The straight-segment builders (`M x,y L x,y L x,y …`) draw the line as a
+// jagged polyline: every data point is a sharp angle. This converts the same
+// points into a MONOTONE-CUBIC spline (Fritsch–Carlson, == d3's curveMonotoneX)
+// emitted as cubic-bezier segments (`M x,y C c1 c2 p …`), so the line flows in
+// gentle curves through every point instead of kinking at each one.
+//
+// Why monotone-cubic and NOT Catmull-Rom (the previous curve):
+//   Catmull-Rom makes pretty curves but "often produces inappropriate OVERSHOOTS
+//   even for monotone data points" — it can shoot above a local max or below a
+//   local min, i.e. it WOBBLES between points and invents values the data never
+//   had. On a streaming chart those overshoots MOVE as the trailing control
+//   points change, adding shimmer on top of the scroll. Monotone-cubic
+//   (Fritsch–Carlson) guarantees "no overshoots beyond the given data points" —
+//   the interpolant stays within the data's own bounds, so the curve can never
+//   wobble or overshoot. It is the standard choice for data charts precisely
+//   because it doesn't fabricate between-point values. See
+//   en.wikipedia.org/wiki/Monotone_cubic_interpolation and d3-shape
+//   `curveMonotoneX`.
+//
+// The algorithm (2-pass Fritsch–Carlson):
+//   pass 1 — secant slopes between consecutive points, then a 3-point tangent at
+//            each interior point (the Catmull-Rom-ish average);
+//   pass 2 — clamp each tangent so it cannot exceed 3× the adjacent secant,
+//            which is exactly what enforces monotonicity (kills overshoot).
+//   The bezier control handles are then placed one third of the x-gap along each
+//   point's tangent — the standard Hermite→bezier conversion.
+//
+// Pure geometry: this is NOT animation. The streaming engine scrolls the whole
+// `<g>`; this builds the curve once per data change from the true points.
+// `tension` still exists for API compat (and `0` is the SHARP disable path), but
+// it no longer scales overshoot — monotone tangents need no tension knob.
+
+/** A point in viewBox space. */
+export interface Pt {
+  x: number;
+  y: number;
+}
+
+/**
+ * Default smoothing tension. Retained for API compatibility — any value > 0
+ * selects the monotone-cubic curve (which has no tension parameter of its own);
+ * `0` degenerates to straight `L` segments for charts that need sharp corners
+ * (ECG QRS spikes, which keep their own bespoke builder rather than this one).
+ */
+export const DEFAULT_TENSION = 0.5;
+
+/**
+ * Build a smooth `d` path through `points` using monotone-cubic → cubic bezier.
+ *
+ * @param points  anchor points, in draw order. The curve passes through each.
+ * @param tension `0` → straight (`L`) segments; any value > 0 → monotone curve.
+ * @param _bounds viewBox extent (kept for signature compat; monotone-cubic does
+ *                not overshoot, so no clamp is needed).
+ * @returns the full `M…`-prefixed path. For the BODY only (no leading `M`), use
+ *          {@link smoothSegments}.
+ */
+export function smoothLinePath(
+  points: readonly Pt[],
+  tension: number,
+  _bounds?: { width: number; height: number },
+): string {
+  if (points.length === 0) return '';
+  const head = `${points[0].x.toFixed(2)},${points[0].y.toFixed(2)}`;
+  if (points.length === 1) return `M${head}`;
+  return `M${head} ${smoothSegments(points, tension)}`;
+}
+
+/**
+ * The curve BODY (no leading `M`) — the `C …`/`L …` segments that connect the
+ * points. Split out so the area builder can reuse the exact same curve between
+ * its own `M0,baseline` open and `L…baseline Z` close (the fill must hug the
+ * same flowing line as the stroke, not a straight re-trace).
+ *
+ * @param tension `0` → straight `L` segments (disable path); > 0 → monotone.
+ * @param _bounds ignored (monotone-cubic does not overshoot) — kept for compat.
+ */
+export function smoothSegments(
+  points: readonly Pt[],
+  tension: number,
+  _bounds?: { width: number; height: number },
+): string {
+  if (points.length < 2) return '';
+
+  // tension <= 0 → straight polyline (the disable path; SHARP geometry).
+  if (tension <= 0) {
+    return points
+      .slice(1)
+      .map((p) => `L${p.x.toFixed(2)},${p.y.toFixed(2)}`)
+      .join(' ');
+  }
+
+  const m = monotoneTangents(points);
+  const out: string[] = [];
+
+  for (let i = 0; i < points.length - 1; i += 1) {
+    const p1 = points[i];
+    const p2 = points[i + 1];
+    const dx = (p2.x - p1.x) / 3;
+    // Hermite → cubic bezier: handles sit one third of the x-gap along each
+    // endpoint's tangent. Monotone tangents guarantee no overshoot, so no clamp.
+    const c1x = p1.x + dx;
+    const c1y = p1.y + dx * m[i];
+    const c2x = p2.x - dx;
+    const c2y = p2.y - dx * m[i + 1];
+    out.push(
+      `C${c1x.toFixed(2)},${c1y.toFixed(2)} ${c2x.toFixed(2)},${c2y.toFixed(2)} ${p2.x.toFixed(2)},${p2.y.toFixed(2)}`,
+    );
+  }
+
+  return out.join(' ');
+}
+
+/**
+ * Trace a monotone-cubic curve through `points` onto a Canvas2D context using the
+ * SAME Fritsch–Carlson tangents as {@link smoothSegments} — the canvas analogue
+ * of emitting the `C …`/`L …` body, via `bezierCurveTo`/`lineTo`. The caller owns
+ * `beginPath()` and the opening `moveTo` (so the area filler can open at the
+ * baseline and close after); this only appends the curve through the points.
+ *
+ * @param tension `0` → straight `lineTo` segments (the SHARP disable path); any
+ *                value > 0 → the monotone curve.
+ */
+export function traceSmoothSegments(
+  ctx: CanvasRenderingContext2D,
+  points: readonly Pt[],
+  tension: number,
+): void {
+  if (points.length < 2) return;
+
+  // tension <= 0 → straight polyline (the disable path; SHARP geometry).
+  if (tension <= 0) {
+    for (let i = 1; i < points.length; i += 1) {
+      ctx.lineTo(points[i].x, points[i].y);
+    }
+    return;
+  }
+
+  const m = monotoneTangents(points);
+  for (let i = 0; i < points.length - 1; i += 1) {
+    const p1 = points[i];
+    const p2 = points[i + 1];
+    const dx = (p2.x - p1.x) / 3;
+    // Hermite → cubic bezier: handles sit one third of the x-gap along each
+    // endpoint's tangent. Monotone tangents guarantee no overshoot, so no clamp.
+    ctx.bezierCurveTo(
+      p1.x + dx,
+      p1.y + dx * m[i],
+      p2.x - dx,
+      p2.y - dx * m[i + 1],
+      p2.x,
+      p2.y,
+    );
+  }
+}
+
+/**
+ * Fritsch–Carlson monotone tangents (the slope dy/dx at each point). Two passes:
+ * a 3-point initial tangent, then a clamp that enforces monotonicity so the
+ * resulting cubic cannot overshoot the data between points. Mirrors d3-shape's
+ * `curveMonotoneX`.
+ */
+function monotoneTangents(points: readonly Pt[]): number[] {
+  const n = points.length;
+  const tangents = new Array<number>(n).fill(0);
+  if (n < 2) return tangents;
+
+  // Secant slopes between consecutive points.
+  const secants = new Array<number>(n - 1);
+  for (let i = 0; i < n - 1; i += 1) {
+    const dx = points[i + 1].x - points[i].x;
+    secants[i] = dx === 0 ? 0 : (points[i + 1].y - points[i].y) / dx;
+  }
+
+  // Pass 1 — endpoint tangents = adjacent secant; interior = average of the two
+  // neighbouring secants (the 3-point tangent).
+  tangents[0] = secants[0];
+  tangents[n - 1] = secants[n - 2];
+  for (let i = 1; i < n - 1; i += 1) {
+    tangents[i] = (secants[i - 1] + secants[i]) / 2;
+  }
+
+  // Pass 2 — clamp tangents to enforce monotonicity (Fritsch–Carlson). Where a
+  // secant is flat, pin both surrounding tangents to 0 (a local extreme stays
+  // flat). Otherwise scale the tangent so (α, β) lie in the monotone circle of
+  // radius 3, which is what kills overshoot.
+  for (let i = 0; i < n - 1; i += 1) {
+    const s = secants[i];
+    if (s === 0) {
+      tangents[i] = 0;
+      tangents[i + 1] = 0;
+      continue;
+    }
+    const a = tangents[i] / s;
+    const b = tangents[i + 1] / s;
+    // If a tangent points the "wrong" way relative to the secant, flatten it.
+    if (a < 0) tangents[i] = 0;
+    if (b < 0) tangents[i + 1] = 0;
+    const h = a * a + b * b;
+    if (h > 9) {
+      const t = 3 / Math.sqrt(h);
+      tangents[i] = t * a * s;
+      tangents[i + 1] = t * b * s;
+    }
+  }
+
+  return tangents;
+}

package/src/tools/visual/charts/SmoothLine/types.ts

@@ -0,0 +1,98 @@
+// SmoothLine — streaming sibling of Sparkline.
+//
+// Drawn on a CANVAS: a single wall-clock rAF loop redraws the whole line each
+// frame at its scrolled X (one writer, one clock — the Smoothie/uPlot model), so
+// the trace SCROLLS left at constant velocity with no SVG-era path/transform
+// desync. Theme-color via the same token bridge as Sparkline.
+
+import type * as React from 'react';
+
+/**
+ * Color source for the stroke / area fill.
+ *
+ *  - A semantic token (`'primary' | 'success' | …`) resolves at runtime via
+ *    `useThemeColor()` from `@djangocfg/ui-core/styles/palette`.
+ *  - The literal `'currentColor'` is the **token bridge**: the SVG inherits the
+ *    CSS `color` of an ancestor, so a host can tint via a `text-*` className
+ *    (e.g. cmdop's `text-chart-3`) without going through the semantic set.
+ */
+export type SmoothLineColor =
+  | 'primary'
+  | 'success'
+  | 'warning'
+  | 'destructive'
+  | 'info'
+  | 'currentColor';
+
+/**
+ * Options for {@link useSmoothSeries} (canvas engine). The seed cadence, the
+ * scroll toggle, and the right-edge delay.
+ */
+export interface SmoothSeriesOptions {
+  /**
+   * Seed cadence (ms) — the first-frame guess + clamp band for the MEASURED
+   * scroll velocity, NOT a fixed slide speed. The engine EMAs the real
+   * inter-sample interval and drives the scroll off that, so a jittery feed still
+   * glides steadily. Stats charts tick ≈ 1000; the quality series (~30 s cadence)
+   * wants a longer window. @default 1000
+   */
+  tweenMs?: number;
+  /**
+   * Continuous left-scroll: the canvas redraws the whole trace each frame at its
+   * wall-clock-scrolled X (a hospital-monitor slide) instead of teleporting. Set
+   * for live windowed charts (ECG / traffic). @default false
+   */
+  scroll?: boolean;
+  /**
+   * Hold the right edge back by one interval (Smoothie / chartjs-streaming
+   * `delay`) so the newest point is known before it scrolls into view — a
+   * continuous right edge instead of "grow then snap". The off-edge point is
+   * clipped for free by the per-frame `clearRect`. Requires `scroll`.
+   * @default true
+   */
+  delay?: boolean;
+}
+
+export interface SmoothLineProps
+  extends Omit<React.ComponentProps<'div'>, 'children'> {
+  /** Series values, oldest-first. Empty renders a flat baseline. */
+  values: readonly number[];
+  /**
+   * Color token. A semantic token resolves via `useThemeColor()`; `'currentColor'`
+   * inherits the ancestor `text-*` tint (the cmdop bridge). @default 'primary'
+   */
+  color?: SmoothLineColor;
+  /** Logical chart width (CSS px). The canvas stretches to its container. @default 240 */
+  width?: number;
+  /** Logical chart height in CSS px. @default 40 */
+  height?: number;
+  /** Line stroke width. @default 1.5 */
+  strokeWidth?: number;
+  /** Render an alpha area fill under the line. @default false */
+  area?: boolean;
+  /** Wall-clock interval per slot (ms) — the scroll cadence. @default 1000 */
+  tweenMs?: number;
+  /** Continuous constant-velocity left-scroll for live windowed data. @default false */
+  scroll?: boolean;
+  /** One-interval right-edge lag (requires `scroll`). @default true */
+  delay?: boolean;
+  /**
+   * Curve smoothness (the line SHAPE, not the motion). The line is drawn as a
+   * MONOTONE-CUBIC curve (Fritsch–Carlson / d3 `curveMonotoneX`) through the
+   * points so it flows in gentle curves WITHOUT overshooting or inventing values
+   * between data points.
+   *
+   *  - `0`   → straight `L` segments (the angular sparkline look) — the disable
+   *    path for charts that need SHARP geometry (e.g. ECG QRS spikes, which
+   *    keep their own bespoke builder rather than this generic one).
+   *  - any value > 0 → the monotone flowing curve (the default). Monotone-cubic
+   *    has no tension parameter of its own, so values above 0 all select the
+   *    same non-overshooting curve.
+   *
+   * This is pure geometry: the curve is rebuilt from the true points once per
+   * data change, then the whole trace scrolls. @default 0.5
+   */
+  tension?: number;
+  /** Optional accessible label. */
+  ariaLabel?: string;
+}