@veluai/velu 0.1.0

package/runtime/velu-ui/components/Toc.jsx

@@ -0,0 +1,537 @@
+import React from 'react';
+import scrollIntoNearestView from '../lib/scrollIntoNearestView.js';
+
+const { useState, useRef, useEffect, useMemo } = React;
+
+/**
+ * Toc — "Comet Trail" table of contents (Claude Design v3 port).
+ *
+ * A bent SVG rail snakes through the (indented) items; a crimson comet head +
+ * persistent trail glides to the active section, with an additive hover comet.
+ * Faithful to the design's geometry/animation, but:
+ *  - tokenized: the design's hardcoded colors + its own light/dark THEMES
+ *    object are dropped; we use velu-ui tokens, so [data-theme] themes it
+ *    globally (DRY — no per-component theme object).
+ *  - SSR-safe: getTotalLength/getPointAtLength run only in client effects;
+ *    first render (server + client) is deterministic (no comet until pathLen
+ *    is measured), so hydration matches.
+ *  - presentational + router/scroll-agnostic: takes `items`, `activeId`,
+ *    `onSelect(id)` — exactly like Sidebar. The consumer owns scroll-spy +
+ *    smooth-scroll (a scroll container concern, not the component's).
+ *
+ * Note: this is intentionally NOT a Stack composition — rows are
+ * absolutely positioned on a coordinate grid so the SVG path anchors line up
+ * with row centers. That coordinate model IS the component; Stack (flow/gap)
+ * cannot express it. Legitimately not a primitive use.
+ *
+ * @typedef {Object} TocItem
+ * @property {string} id     section id (matches the page element id)
+ * @property {string} label
+ * @property {TocItem[]} [children]
+ *
+ * @param {{ items: TocItem[], activeId?: string, onSelect?: (id:string)=>void,
+ *   rowH?: number, padTop?: number, railLeft?: number, indent?: number,
+ *   gap?: number, tail?: number, fontSize?: number }} props
+ */
+
+const ACCENT = 'var(--accent-color)';
+// Faint guide rail (the design uses a lighter gray than structural borders);
+// derived from the border token so it still themes — no new token needed.
+const RAIL_BASE = 'color-mix(in srgb, var(--border-color) 45%, transparent)';
+const TEXT = 'var(--text-color)';
+const HALO = 'color-mix(in srgb, var(--accent-color) 22%, transparent)';
+const GLOW = 'color-mix(in srgb, var(--accent-color) 90%, transparent)';
+
+// Geometry is token-driven, never hardcoded. The SVG/comet math needs px
+// numbers, so the modular-scale tokens are resolved to px at runtime via a
+// probe element. Fallback = the default scale (s0=16, ratio=1.25) so SSR and
+// the first client render match (no hydration mismatch); the client effect
+// then re-reads the real tokens and auto-adapts if --s0/--ratio are themed.
+const S0 = 16;
+const RATIO = 1.25;
+const scaleStep = (n) => S0 * Math.pow(RATIO, n);
+const DIM_TOKENS = {
+  rowH: '--s3',
+  padTop: '--s-1',
+  railLeft: '--s-1',
+  indent: '--s-1',
+  fontPx: '--f-h6', // resolved type size; the comet artwork scales off this
+};
+const DIM_FALLBACK = {
+  rowH: scaleStep(3),
+  padTop: scaleStep(-1),
+  railLeft: scaleStep(-1),
+  indent: scaleStep(-1),
+  fontPx: 13, // --f-h6 clamp resolves ~12–14; 13 = the design's value
+};
+
+function useScaleDims() {
+  const [dims, setDims] = useState(DIM_FALLBACK);
+  useEffect(() => {
+    const probe = document.createElement('div');
+    probe.style.cssText =
+      'position:absolute;visibility:hidden;height:0;pointer-events:none';
+    document.body.appendChild(probe);
+    const px = (expr) => {
+      probe.style.width = expr;
+      return parseFloat(getComputedStyle(probe).width);
+    };
+    const next = {};
+    let ok = true;
+    for (const k in DIM_TOKENS) {
+      const v = px(`var(${DIM_TOKENS[k]})`);
+      if (!Number.isFinite(v) || v <= 0) {
+        ok = false;
+        break;
+      }
+      next[k] = v;
+    }
+    document.body.removeChild(probe);
+    if (ok) setDims(next);
+  }, []);
+  return dims;
+}
+
+function flatten(nodes, depth = 0, out = []) {
+  for (const n of nodes) {
+    out.push({
+      id: n.id,
+      label: n.label,
+      depth,
+      hasChildren: !!(n.children && n.children.length),
+    });
+    if (n.children) flatten(n.children, depth + 1, out);
+  }
+  return out;
+}
+
+// Always-smooth path: each horizontal change is one cubic bezier whose control
+// points sit at the vertical midpoint — rounded elbow regardless of row gap.
+function smoothPath(anchors) {
+  if (anchors.length === 0) return '';
+  let d = `M ${anchors[0].x} ${anchors[0].y}`;
+  for (let i = 1; i < anchors.length; i++) {
+    const p = anchors[i - 1];
+    const c = anchors[i];
+    if (c.x === p.x) d += ` L ${c.x} ${c.y}`;
+    else {
+      const m = (p.y + c.y) / 2;
+      d += ` C ${p.x} ${m}, ${c.x} ${m}, ${c.x} ${c.y}`;
+    }
+  }
+  return d;
+}
+
+const Row = React.forwardRef(function Row(
+  { item, idx, onEnter, onClick, hovered, active, rowH, indent, textStart, fontSize },
+  ref
+) {
+  return (
+    <div
+      ref={ref}
+      data-toc-active={active ? 'true' : undefined}
+      onMouseEnter={() => onEnter(idx)}
+      onClick={() => onClick(item.id)}
+      style={{
+        /* Natural document flow — rows stack normally so a wrapped row
+           PUSHES the rows below it down rather than overlapping them.
+           `minHeight: rowH` keeps single-line rows at the canonical
+           rhythm; multi-line rows take whatever vertical space they
+           need. The SVG rail's anchor y for each row is measured AFTER
+           layout (see useEffect in the parent) so the path stays
+           aligned with the (possibly grown) row centres. */
+        position: 'relative',
+        minHeight: rowH,
+        display: 'flex',
+        alignItems: 'flex-start',
+        paddingLeft: textStart + item.depth * indent,
+        fontSize,
+        color: hovered || active ? ACCENT : TEXT,
+        cursor: 'pointer',
+        transition: 'color 200ms ease',
+      }}
+    >
+      <span
+        style={{
+          /* Weight is depth-based ONLY — active state is distinguished
+             by colour (ACCENT) above, not by a 400→600 weight bump.
+             Reason: the bold version is wider, so a label sitting on
+             the edge of one line would flip its wrap state every time
+             it became active. That changed the measured row height,
+             which dragged the SVG anchors around, which made the
+             comet appear to wander mid-scroll. Stable weight → stable
+             heights → stable rail. */
+          fontWeight: item.depth === 0 ? 500 : 400,
+        }}
+      >
+        {item.label}
+      </span>
+    </div>
+  );
+});
+
+export default function Toc({
+  items = [],
+  activeId,
+  onSelect = () => {},
+  rowH: rowHProp,
+  padTop: padTopProp,
+  railLeft: railLeftProp,
+  indent: indentProp,
+  gap = 0,
+  tail: tailProp,
+  fontSize: fontSizeProp,
+  ...rest
+}) {
+  // Defaults derive from the modular-scale tokens (no hardcoded sizes);
+  // callers may still override per-prop.
+  const dims = useScaleDims();
+  const rowH = rowHProp ?? dims.rowH;
+  const padTop = padTopProp ?? dims.padTop;
+  const railLeft = railLeftProp ?? dims.railLeft;
+  const indent = indentProp ?? dims.indent;
+  const tail = tailProp ?? rowH * 6;
+  const fontSize = fontSizeProp ?? 'var(--f-h6)';
+
+  // Comet artwork scales with the type token (dims.fontPx ← --f-h6). These
+  // multipliers are proportions of that size, calibrated to reproduce the
+  // design exactly at the default (≈13px) — so no raw px literals, and the
+  // comet rescales if the type token is themed.
+  const fpx = dims.fontPx;
+  const cometCoreR = fpx * 0.17;
+  const cometHaloR = fpx * 0.42;
+  const cometGlow = fpx * 0.31; // px used in blur()/drop-shadow
+  const SEL_W = fpx * 0.123;
+  const SEL_TAPER = fpx * 0.108;
+  const HOV_W = fpx * 0.031;
+  const HOV_TAPER = fpx * 0.2;
+  const HOV_GLOW_W = fpx * 0.231;
+
+  const FLAT = useMemo(() => flatten(items), [items]);
+  const MAX_DEPTH = useMemo(
+    () => FLAT.reduce((m, i) => Math.max(m, i.depth), 0),
+    [FLAT]
+  );
+  const activeIdx = useMemo(() => {
+    const i = FLAT.findIndex((f) => f.id === activeId);
+    return i === -1 ? null : i;
+  }, [FLAT, activeId]);
+
+  const [hoverIdx, setHoverIdx] = useState(null);
+
+  // Root container ref — declared up here because the measurement
+  // effect below needs it, and a later effect (auto-scroll the active
+  // row into the parent scrollport) reuses the same ref.
+  const rootRef = useRef(null);
+
+  // Precomputed anchors — what we use at SSR + before client measurement
+  // happens. Once the rows render and we know their actual offsetTop /
+  // height (some may have wrapped), we overwrite `anchors` with the
+  // measured values so the SVG rail tracks the real row centres.
+  const initialAnchors = useMemo(
+    () =>
+      FLAT.map((item, idx) => ({
+        x: railLeft + item.depth * indent,
+        y: padTop + idx * rowH + rowH / 2,
+      })),
+    [FLAT, rowH, padTop, railLeft, indent]
+  );
+  const [anchors, setAnchors] = useState(initialAnchors);
+  const textStart = railLeft + MAX_DEPTH * indent + gap;
+  const fullPath = useMemo(() => smoothPath(anchors), [anchors]);
+
+  // Row refs (collected per render) + remeasure on resize + on relevant
+  // dep changes. Using a ResizeObserver on the root catches width
+  // changes (which can flip wrap state on borderline labels) and any
+  // content-driven height changes (e.g. weight 400 → 600 on active).
+  const rowRefs = useRef([]);
+  const setRowRef = (idx) => (el) => {
+    rowRefs.current[idx] = el;
+  };
+  useEffect(() => {
+    if (typeof window === 'undefined' || !rootRef.current) return;
+    const measure = () => {
+      const next = FLAT.map((item, idx) => {
+        const el = rowRefs.current[idx];
+        if (!el) return initialAnchors[idx];
+        const top = el.offsetTop;
+        const h = el.offsetHeight;
+        return {
+          x: railLeft + item.depth * indent,
+          y: top + h / 2,
+        };
+      });
+      // Short-circuit when nothing changed — same values, same array
+      // reference. Prevents the anchorDist useMemo downstream from
+      // recomputing and tearing down the comet animation mid-ease.
+      setAnchors((prev) => {
+        if (
+          prev.length === next.length &&
+          next.every(
+            (a, i) => prev[i] && prev[i].x === a.x && prev[i].y === a.y,
+          )
+        ) {
+          return prev;
+        }
+        return next;
+      });
+    };
+    measure();
+    const ro = new ResizeObserver(measure);
+    ro.observe(rootRef.current);
+    rowRefs.current.forEach((el) => el && ro.observe(el));
+    return () => ro.disconnect();
+    // NOTE: deliberately NO `activeId` / `activeIdx` here — those are
+    // selection state, not layout. Re-running the measurement on every
+    // scroll-spy update would create a new anchors-array reference even
+    // when nothing physical changed, which would restart the comet
+    // animation every frame (visible as comet jitter).
+  }, [FLAT, railLeft, indent, padTop, rowH, initialAnchors]);
+
+  const pathRef = useRef(null);
+  const [pathLen, setPathLen] = useState(0);
+
+  // Client-only: measure the path once it's in the DOM. (useEffect, not
+  // useLayoutEffect, to avoid the SSR warning; brief first-frame settle is ok.)
+  useEffect(() => {
+    if (pathRef.current) setPathLen(pathRef.current.getTotalLength());
+  }, [fullPath]);
+
+  const anchorDist = useMemo(() => {
+    if (!pathRef.current || !pathLen) return [];
+    const samples = 800;
+    const pts = [];
+    for (let i = 0; i <= samples; i++)
+      pts.push(pathRef.current.getPointAtLength((i / samples) * pathLen));
+    return anchors.map((a) => {
+      let bestI = 0;
+      let bestD = Infinity;
+      for (let i = 0; i < pts.length; i++) {
+        const dx = pts[i].x - a.x;
+        const dy = pts[i].y - a.y;
+        const d = dx * dx + dy * dy;
+        if (d < bestD) {
+          bestD = d;
+          bestI = i;
+        }
+      }
+      return (bestI / samples) * pathLen;
+    });
+  }, [anchors, pathLen]);
+
+  const [selHead, setSelHead] = useState(0);
+  const [selPt, setSelPt] = useState({ x: 0, y: 0 });
+  const [hovHead, setHovHead] = useState(0);
+  const [hovPt, setHovPt] = useState({ x: 0, y: 0 });
+
+  // Scroll-driven selection head glides to the active section.
+  useEffect(() => {
+    if (activeIdx == null || !anchorDist.length || !pathRef.current) return;
+    const dest = anchorDist[activeIdx];
+    let raf;
+    const start = selHead;
+    const t0 = performance.now();
+    const ease = (t) => 1 - Math.pow(1 - t, 3);
+    const tick = (now) => {
+      const t = Math.min(1, (now - t0) / 500);
+      const v = start + (dest - start) * ease(t);
+      setSelHead(v);
+      const pt = pathRef.current.getPointAtLength(v);
+      setSelPt({ x: pt.x, y: pt.y });
+      if (t < 1) raf = requestAnimationFrame(tick);
+    };
+    raf = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(raf);
+  }, [activeIdx, anchorDist]);
+
+  // Hover head animates independently; selection trail is never cleared.
+  useEffect(() => {
+    if (hoverIdx == null || !anchorDist.length || !pathRef.current) return;
+    const dest = anchorDist[hoverIdx];
+    let raf;
+    const start = hovHead || dest;
+    const t0 = performance.now();
+    const ease = (t) => 1 - Math.pow(1 - t, 3);
+    const tick = (now) => {
+      const t = Math.min(1, (now - t0) / 280);
+      const v = start + (dest - start) * ease(t);
+      setHovHead(v);
+      const pt = pathRef.current.getPointAtLength(v);
+      setHovPt({ x: pt.x, y: pt.y });
+      if (t < 1) raf = requestAnimationFrame(tick);
+    };
+    raf = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(raf);
+  }, [hoverIdx, anchorDist]);
+
+  const hovTailStart = Math.max(0, hovHead - tail);
+  const hovVisible = hovHead - hovTailStart;
+
+  const trail = (headVisible, tailStart, baseW, taper, baseA, aTaper, keyP) => {
+    const SEGMENTS = 28;
+    const OVERLAP = 0.5;
+    const segs = [];
+    for (let i = 0; i < SEGMENTS; i++) {
+      const t0 = i / SEGMENTS;
+      const t1 = (i + 1) / SEGMENTS;
+      const segStart = tailStart + headVisible * t0 - (i > 0 ? OVERLAP : 0);
+      const segEnd = tailStart + headVisible * t1;
+      const dashLen = Math.max(0, segEnd - segStart);
+      if (dashLen <= 0) continue;
+      const f = t1;
+      segs.push(
+        <path
+          key={`${keyP}${i}`}
+          d={fullPath}
+          fill="none"
+          strokeLinecap="round"
+          strokeDasharray={`${dashLen} ${pathLen}`}
+          strokeDashoffset={-segStart}
+          style={{
+            stroke: ACCENT,
+            strokeWidth: baseW + Math.pow(f, 1.6) * taper,
+            opacity: baseA + Math.pow(f, aTaper) * (0.95 - baseA),
+          }}
+        />
+      );
+    }
+    return <g>{segs}</g>;
+  };
+
+  // Keep the active row inside the parent scroll container's visible
+  // region — pulling it above the footer-eclipsed band, plus a small
+  // safety gap so the active row never sits flush against the footer.
+  //
+  // The bottom-of-visible-region is computed from a LIVE measurement of
+  // the footer's getBoundingClientRect (looked up via `[data-velu-footer]`)
+  // rather than from the parent's CSS scroll-padding-bottom. The CSS
+  // version is driven by React state that lags one commit behind the
+  // user's actual scroll position — at high scroll velocities the active
+  // row would otherwise creep under the footer between frames. Reading
+  // the footer rect synchronously in the scroll handler is always
+  // current with the user's input.
+  useEffect(() => {
+    if (activeIdx == null) return;
+    const BOTTOM_GAP = 32; // px clear between active row and footer top
+    const update = () => {
+      const el = rootRef.current?.querySelector('[data-toc-active="true"]');
+      if (!el) return;
+      const footer = document.querySelector('[data-velu-footer]');
+      let padBottom;
+      if (footer) {
+        const rect = footer.getBoundingClientRect();
+        const overlap = Math.max(0, window.innerHeight - rect.top);
+        padBottom = overlap + BOTTOM_GAP;
+      }
+      scrollIntoNearestView(
+        el,
+        padBottom !== undefined ? { padBottom } : undefined,
+      );
+    };
+    update();
+    window.addEventListener('scroll', update, { passive: true });
+    return () => window.removeEventListener('scroll', update);
+  }, [activeIdx]);
+
+  return (
+    <div
+      ref={rootRef}
+      onMouseLeave={() => setHoverIdx(null)}
+      style={{
+        /* Container is naturally sized by the row stack inside —
+           wrapped rows extend it. `position: relative` makes the
+           absolutely-positioned SVG layer size to this container, and
+           gives the rows a stable offsetParent for the measurement
+           effect above. padBlock = padTop on both ends matches the
+           previous coordinate model's gutter. */
+        position: 'relative',
+        paddingBlockStart: padTop,
+        paddingBlockEnd: padTop,
+      }}
+      {...rest}
+    >
+      <svg
+        width="100%"
+        height="100%"
+        style={{
+          position: 'absolute',
+          inset: 0,
+          pointerEvents: 'none',
+          overflow: 'visible',
+        }}
+      >
+        <path
+          ref={pathRef}
+          d={fullPath}
+          fill="none"
+          style={{ stroke: RAIL_BASE, strokeWidth: 'var(--border-width)' }}
+        />
+
+        {pathLen > 0 &&
+          activeIdx != null &&
+          trail(selHead, 0, SEL_W, SEL_TAPER, 0.95, 1, 's')}
+        {pathLen > 0 && activeIdx != null && (
+          <g>
+            <circle cx={selPt.x} cy={selPt.y} r={cometHaloR} style={{ fill: HALO }} />
+            <circle
+              cx={selPt.x}
+              cy={selPt.y}
+              r={cometCoreR}
+              style={{
+                fill: ACCENT,
+                filter: `drop-shadow(0 0 ${cometGlow}px ${GLOW})`,
+              }}
+            />
+          </g>
+        )}
+
+        {pathLen > 0 &&
+          hoverIdx != null &&
+          trail(hovVisible, hovTailStart, HOV_W, HOV_TAPER, 0.05, 1.3, 'h')}
+        {pathLen > 0 && hoverIdx != null && (
+          <path
+            d={fullPath}
+            fill="none"
+            strokeLinecap="round"
+            strokeDasharray={`${Math.min(hovVisible, tail * 0.5)} ${pathLen}`}
+            strokeDashoffset={-(hovHead - Math.min(hovVisible, tail * 0.5))}
+            style={{
+              stroke: ACCENT,
+              strokeWidth: HOV_GLOW_W,
+              filter: `blur(${cometGlow}px)`,
+              opacity: 0.45,
+            }}
+          />
+        )}
+        {pathLen > 0 && hoverIdx != null && (
+          <g>
+            <circle cx={hovPt.x} cy={hovPt.y} r={cometHaloR} style={{ fill: HALO }} />
+            <circle
+              cx={hovPt.x}
+              cy={hovPt.y}
+              r={cometCoreR}
+              style={{ fill: ACCENT, filter: `drop-shadow(0 0 ${cometGlow}px ${GLOW})` }}
+            />
+          </g>
+        )}
+      </svg>
+
+      {FLAT.map((item, idx) => (
+        <Row
+          key={item.id}
+          ref={setRowRef(idx)}
+          item={item}
+          idx={idx}
+          onEnter={setHoverIdx}
+          onClick={onSelect}
+          hovered={hoverIdx === idx}
+          active={activeIdx === idx}
+          rowH={rowH}
+          indent={indent}
+          textStart={textStart}
+          fontSize={fontSize}
+        />
+      ))}
+    </div>
+  );
+}