Subchapter 18.68

Chart Scrub Readout

rules/chart-scrub-readout.mdMarkdown10 KBView on GitHub

The chart is already ON screen — this rule interrogates it. A vertical tracking line rides the scrub position, a marker dot follows the series, and a live tooltip reads out date: value per position, values flickering past like an odometer. It’s the “this data is real — look closer” beat: the scrub proves the chart is an instrument, not a picture.

Boundary with its neighbors: stat-bars-and-fills.md owns the chart’s ARRIVAL; counting-dynamic-scale.md owns a single number swelling in place. This rule assumes the graphic already exists and adds a read head moving across it. The three chain naturally: the line draws in (svg-path-draw / stat-bars), this rule scrubs it, and the landing value hands off to a count-up lockup.

How It Works

Chart Scrub Readout · Hyperframes Animation · heygen-com/hyperframes · Skills Docs

<!-- inside a standard scene clip. Size the SVG so viewBox units === CSS pixels:
     one coordinate space serves the polyline, tracking line, marker, AND the HTML tooltip. -->
<div class="chart-wrap">
  <!-- position: relative — the tooltip transforms against this box -->
  <svg class="chart" viewBox="0 0 CHART_W CHART_H" width="CHART_W" height="CHART_H">
    <polyline id="series-a" class="series" fill="none" />
    <line id="track-line" y1="0" y2="CHART_H" stroke-dasharray="6 6" />
    <circle id="marker" r="MARKER_R" />
  </svg>
  <div class="tooltip" id="tooltip">
    <span id="tip-date">{firstDate}</span>
    <span id="tip-value">{firstValue}</span>
  </div>
</div>

.tooltip {
  position: absolute;
  top: 0;
  left: 0;
  min-width: TIP_MIN_WIDTH; /* fixed — the box must not resize as values change length */
}
#tip-value {
  font-variant-numeric: tabular-nums; /* MANDATORY — digits flicker past; widths must not */
}

// Data baked at setup — literal values.
const DATA = [
  { d: "{date1}", v: V1 },
  // ... N points, chronological ...
];

// Pure mapping functions — geometry derives from DATA once.
const PAD = CHART_PAD;
const PLOT_W = CHART_W - PAD * 2;
const PLOT_H = CHART_H - PAD * 2;
const vals = DATA.map((p) => p.v);
const V_MIN = Math.min(...vals);
const V_MAX = Math.max(...vals);
const X = (i) => PAD + (i / (DATA.length - 1)) * PLOT_W;
const Y = (v) => PAD + PLOT_H * (1 - (v - V_MIN) / (V_MAX - V_MIN));

document
  .getElementById("series-a")
  .setAttribute("points", DATA.map((p, i) => `${X(i)},${Y(p.v)}`).join(" "));

const line = document.getElementById("track-line");
const marker = document.getElementById("marker");
const tooltip = document.getElementById("tooltip");
const tipDate = document.getElementById("tip-date");
const tipValue = document.getElementById("tip-value");

// Tooltip pops in as the scrub begins — a small fromTo scale/opacity spring at SCRUB_AT.

// ONE driver — line, marker, and tooltip are all projections of p.
const scrub = { p: 0 };
let lastIdx = -1;
tl.to(
  scrub,
  {
    p: 1,
    duration: SCRUB_DUR,
    ease: SCRUB_EASE,
    onUpdate: () => {
      const f = scrub.p * (DATA.length - 1); // fractional index
      const i = Math.min(DATA.length - 2, Math.floor(f));
      const t = f - i;
      const x = X(i) + (X(i + 1) - X(i)) * t;
      const y = Y(DATA[i].v) + (Y(DATA[i + 1].v) - Y(DATA[i].v)) * t;

      // Transforms glide every frame (cheap, deterministic)
      line.setAttribute("x1", x);
      line.setAttribute("x2", x);
      marker.setAttribute("cx", x);
      marker.setAttribute("cy", y);
      tooltip.style.transform = `translate(${x + TIP_DX}px, ${y - TIP_DY}px)`;

      // Text steps only when the nearest data point changes
      const idx = Math.round(f);
      if (idx !== lastIdx) {
        tipDate.textContent = DATA[idx].d;
        tipValue.textContent = `${DATA[idx].v.toLocaleString()} {unitLabel}`;
        lastIdx = idx;
      }
    },
  },
  SCRUB_AT,
);
// End hold: the driver finishes before the scene does — the landed value reads.

token	range / default	notes
N (data points)	10–40	<10 reads as a slideshow; >40 blurs into texture. The flicker is the point — only first and final values must be legible
SCRUB_DUR	1.5–3s	shorter = confident sweep; longer = inspection. Leave ≥0.8s of scene after the driver ends so the landed value holds
SCRUB_EASE	`power1.inOut` default	`"none"` playhead form; `power3.out` peak stop. Never `back.out` — a read head that overshoots and re-reads looks broken
CROSS_P	0.55–0.75	earlier and A never establishes; later and B’s readout has no time to live
TIP_DX / TIP_DY	16–48px, up-and-right	flip the sign near the chart’s right edge so the tooltip never exits the frame
MARKER_R / stroke width	r 6–12 / 4–8px	the marker must dominate the line it rides
TIP_MIN_WIDTH	≥ longest `date: value` state	without it the box breathes as digits change

Chart Scrub Readout

How It Works

Chart Scrub Readout

How It Works

Recipe

Variations

Values

Critical Constraints

See also