poetry-charts 0.0.2

data/app/javascript/poetry/charts/motion/flip.js

@@ -0,0 +1,169 @@
+import { sectorPath } from "@poetry/charts/motion/sector"
+
+// The FLIP geometry machinery (shared by the motion and live tiers):
+// snapshot a chart's animatable geometry, pair it against the
+// current DOM, and tween old -> new. Paths morph by pairwise numeric lerp
+// behind a structure fingerprint, sectors by param lerp through the same
+// sectorPath port, dots by cx/cy. Both endpoints are always
+// server-computed (or kernel-computed) states - the only math here is
+// a + (b - a) * t.
+
+const MORPH_SLOTS = [
+  "chart-area",
+  "chart-area-stroke",
+  "chart-line",
+  "chart-bar",
+  "chart-radar",
+  "chart-pie-sector",
+  "chart-radial-bar",
+  "chart-dot",
+]
+/** Selector matching every animatable mark the FLIP machinery drives. */
+export const MORPH_SELECTOR = MORPH_SLOTS.map((slot) => `[data-slot="${slot}"]`).join(", ")
+
+const NUMBER = /-?(?:\d+\.?\d*|\.\d+)(?:e[-+]?\d+)?/gi
+
+/**
+ * d -> { skeleton, numbers }: the non-numeric shape (command letters
+ * and separators) plus the numbers in order. Equal skeletons morph; arc
+ * flags are structural constants inside the skeleton's A-segments and
+ * stay put under lerp because equal skeletons imply equal flags.
+ *
+ * @param {string} d
+ * @returns {{ skeleton: string, numbers: number[] }}
+ */
+export function parsePath(d) {
+  const numbers = []
+  const skeleton = d.replace(NUMBER, (match) => {
+    numbers.push(Number(match))
+    return "#"
+  })
+  return { skeleton, numbers }
+}
+
+/**
+ * Rebuilds a d string from a skeleton and numbers (2-decimal rounding).
+ *
+ * @param {string} skeleton
+ * @param {number[]} numbers
+ * @returns {string}
+ */
+export function buildPath(skeleton, numbers) {
+  let i = 0
+  return skeleton.replace(/#/g, () => String(Math.round(numbers[i++] * 100) / 100))
+}
+
+/**
+ * Yields [key, element] for every animatable element, keyed by slot +
+ * series key + per-bucket sequence (dots carry no index; document order
+ * is stable).
+ *
+ * @param {SVGElement} svg
+ * @returns {Generator<[string, Element]>}
+ */
+export function* keyedElements(svg) {
+  const counters = new Map()
+  for (const el of svg.querySelectorAll(MORPH_SELECTOR)) {
+    const base = `${el.dataset.slot}|${el.dataset.key ?? ""}`
+    const n = counters.get(base) ?? 0
+    counters.set(base, n + 1)
+    yield [`${base}|${n}`, el]
+  }
+}
+
+/**
+ * Snapshots the animatable geometry (sector params, path d, or dot
+ * cx/cy), keyed for pairing.
+ *
+ * @param {SVGElement} svg
+ * @returns {Map<string, Object>}
+ */
+export function captureGeometry(svg) {
+  const entries = new Map()
+  for (const [key, el] of keyedElements(svg)) {
+    if (el.dataset.motionSector) {
+      entries.set(key, { sector: el.dataset.motionSector.split(" ").map(Number) })
+    } else if (el.hasAttribute("d")) {
+      entries.set(key, { d: el.getAttribute("d") })
+    } else if (el.hasAttribute("cx")) {
+      entries.set(key, { cx: Number(el.getAttribute("cx")), cy: Number(el.getAttribute("cy")) })
+    }
+  }
+  return entries
+}
+
+/**
+ * Pairs every animatable element with its captured predecessor. Null =
+ * structure changed (missing key, skeleton mismatch, kind mismatch) -
+ * the caller falls back to its non-morph path.
+ *
+ * @param {SVGElement} svg
+ * @param {Map<string, Object>} previous - from `captureGeometry`
+ * @returns {Array<Object> | null} tween jobs, or null
+ */
+export function matchJobs(svg, previous) {
+  const jobs = []
+  for (const [key, el] of keyedElements(svg)) {
+    const before = previous.get(key)
+    if (!before) return null
+
+    if (el.dataset.motionSector && before.sector) {
+      const to = el.dataset.motionSector.split(" ").map(Number)
+      if (to.length !== before.sector.length) return null
+      jobs.push({ el, sector: true, from: before.sector, to, final: el.getAttribute("d") })
+    } else if (el.hasAttribute("d") && before.d != null) {
+      const from = parsePath(before.d)
+      const to = parsePath(el.getAttribute("d"))
+      if (from.skeleton !== to.skeleton) return null
+      jobs.push({ el, skeleton: to.skeleton, from: from.numbers, to: to.numbers, final: el.getAttribute("d") })
+    } else if (el.hasAttribute("cx") && before.cx != null) {
+      jobs.push({
+        el,
+        from: [before.cx, before.cy],
+        to: [Number(el.getAttribute("cx")), Number(el.getAttribute("cy"))],
+        finalCx: el.getAttribute("cx"),
+        finalCy: el.getAttribute("cy"),
+      })
+    } else {
+      return null
+    }
+  }
+  return jobs.length ? jobs : null
+}
+
+/**
+ * Writes one interpolated frame of every job onto the DOM.
+ *
+ * @param {Array<Object>} jobs
+ * @param {number} eased - 0..1
+ */
+export function applyJobs(jobs, eased) {
+  for (const job of jobs) {
+    if (job.sector) {
+      const p = job.from.map((from, i) => from + (job.to[i] - from) * eased)
+      job.el.setAttribute("d", sectorPath(p[0], p[1], p[2], p[3], p[4], p[5]))
+    } else if (job.skeleton) {
+      const numbers = job.from.map((from, i) => from + (job.to[i] - from) * eased)
+      job.el.setAttribute("d", buildPath(job.skeleton, numbers))
+    } else {
+      job.el.setAttribute("cx", String(job.from[0] + (job.to[0] - job.from[0]) * eased))
+      job.el.setAttribute("cy", String(job.from[1] + (job.to[1] - job.from[1]) * eased))
+    }
+  }
+}
+
+/**
+ * The final frame restores the exact target strings (server- or
+ * kernel-rendered), never a lerp artifact.
+ *
+ * @param {Array<Object>} jobs
+ */
+export function finishJobs(jobs) {
+  for (const job of jobs) {
+    if (job.final != null) job.el.setAttribute("d", job.final)
+    else {
+      job.el.setAttribute("cx", job.finalCx)
+      job.el.setAttribute("cy", job.finalCy)
+    }
+  }
+}

data/app/javascript/poetry/charts/motion/sector.js

@@ -0,0 +1,62 @@
+// The sector path, ported from lib/poetry/charts/polar.rb so both
+// sides emit identical path strings. Angles are degrees
+// counterclockwise from 3 o'clock, negated into SVG's y-down plane; the
+// delta clamps at 359.999 so a full circle's endpoints never coincide.
+// 4-decimal formatting matches the Ruby fmt (native JS stringification IS
+// the reference Geometry.js_number emulates), so mid-sweep paths and the
+// server's plain paths are byte-compatible.
+
+const RADIAN = Math.PI / 180
+
+const sign = (value) => (value === 0 ? 0 : value < 0 ? -1 : 1)
+const fmt = (value) => String(Math.round(value * 1e4) / 1e4)
+
+/**
+ * Degrees-and-radius to SVG coordinates (the y-down plane).
+ *
+ * @param {number} cx
+ * @param {number} cy
+ * @param {number} radius
+ * @param {number} angle - degrees counterclockwise from 3 o'clock
+ * @returns {[number, number]} [x, y]
+ */
+export function polarToCartesian(cx, cy, radius, angle) {
+  return [cx + Math.cos(-RADIAN * angle) * radius, cy + Math.sin(-RADIAN * angle) * radius]
+}
+
+/**
+ * The annular-sector path for a pie/radial slice; inner radius 0 closes
+ * to the center instead of an inner arc.
+ *
+ * @param {number} cx
+ * @param {number} cy
+ * @param {number} innerRadius
+ * @param {number} outerRadius
+ * @param {number} startAngle - degrees
+ * @param {number} endAngle
+ * @returns {string} the d attribute
+ */
+export function sectorPath(cx, cy, innerRadius, outerRadius, startAngle, endAngle) {
+  const delta = sign(endAngle - startAngle) * Math.min(Math.abs(endAngle - startAngle), 359.999)
+  const tempEnd = startAngle + delta
+  const large = Math.abs(delta) > 180 ? 1 : 0
+
+  const [ox0, oy0] = polarToCartesian(cx, cy, outerRadius, startAngle)
+  const [ox1, oy1] = polarToCartesian(cx, cy, outerRadius, tempEnd)
+
+  let path = `M${fmt(ox0)},${fmt(oy0)}` +
+    `A${fmt(outerRadius)},${fmt(outerRadius)},0,` +
+    `${large},${startAngle > tempEnd ? 1 : 0},${fmt(ox1)},${fmt(oy1)}`
+
+  if (innerRadius > 0) {
+    const [ix0, iy0] = polarToCartesian(cx, cy, innerRadius, startAngle)
+    const [ix1, iy1] = polarToCartesian(cx, cy, innerRadius, tempEnd)
+    path += `L${fmt(ix1)},${fmt(iy1)}` +
+      `A${fmt(innerRadius)},${fmt(innerRadius)},0,` +
+      `${large},${startAngle <= tempEnd ? 1 : 0},${fmt(ix0)},${fmt(iy0)}Z`
+  } else {
+    path += `L${fmt(cx)},${fmt(cy)}Z`
+  }
+
+  return path
+}

data/app/javascript/poetry/charts/motion/tween.js

@@ -0,0 +1,105 @@
+// The tween kernel: one rAF loop, the CSS-named cubic-bezier
+// easings, cancelable. An animation runtime scoped to poetry's
+// doctrine - the client only interpolates between server-computed
+// states, so the whole kernel is eased time.
+
+/**
+ * A CSS cubic-bezier timing function: Newton-Raphson with a bisection
+ * fallback - the standard solver (the same approach WebKit ships).
+ *
+ * @param {number} x1
+ * @param {number} y1
+ * @param {number} x2
+ * @param {number} y2
+ * @returns {(x: number) => number} eased progress for linear progress
+ */
+export function cubicBezier(x1, y1, x2, y2) {
+  const ax = 3 * x1 - 3 * x2 + 1
+  const bx = 3 * x2 - 6 * x1
+  const cx = 3 * x1
+  const ay = 3 * y1 - 3 * y2 + 1
+  const by = 3 * y2 - 6 * y1
+  const cy = 3 * y1
+
+  const sampleX = (t) => ((ax * t + bx) * t + cx) * t
+  const sampleY = (t) => ((ay * t + by) * t + cy) * t
+  const sampleDX = (t) => (3 * ax * t + 2 * bx) * t + cx
+
+  const solveT = (x) => {
+    let t = x
+    for (let i = 0; i < 8; i++) {
+      const dx = sampleX(t) - x
+      if (Math.abs(dx) < 1e-6) return t
+      const d = sampleDX(t)
+      if (Math.abs(d) < 1e-6) break
+      t -= dx / d
+    }
+    let lo = 0
+    let hi = 1
+    t = x
+    while (lo < hi) {
+      const dx = sampleX(t) - x
+      if (Math.abs(dx) < 1e-6) return t
+      if (dx > 0) hi = t
+      else lo = t
+      t = (lo + hi) / 2
+    }
+    return t
+  }
+
+  return (x) => {
+    if (x <= 0) return 0
+    if (x >= 1) return 1
+    return sampleY(solveT(x))
+  }
+}
+
+/** The CSS-named easing functions. */
+export const EASINGS = {
+  linear: (t) => t,
+  ease: cubicBezier(0.25, 0.1, 0.25, 1),
+  "ease-in": cubicBezier(0.42, 0, 1, 1),
+  "ease-out": cubicBezier(0, 0, 0.58, 1),
+  "ease-in-out": cubicBezier(0.42, 0, 0.58, 1),
+}
+
+/**
+ * Runs one rAF tween. onFrame receives (eased, linear); the final frame
+ * is exactly (1, 1). A non-positive duration fires the final frame
+ * synchronously.
+ *
+ * @param {Object} options
+ * @param {number} options.duration - ms
+ * @param {number} [options.delay=0] - ms before the first eased frame
+ * @param {string | Function} [options.easing="ease"] - an EASINGS name
+ *   or a timing function
+ * @param {(eased: number, linear: number) => void} options.onFrame
+ * @param {() => void} [options.onFinish]
+ * @returns {() => void} cancel()
+ */
+export function tween({ duration, delay = 0, easing = "ease", onFrame, onFinish }) {
+  const fn = typeof easing === "function" ? easing : (EASINGS[easing] ?? EASINGS.ease)
+
+  if (!(duration > 0)) {
+    onFrame(1, 1)
+    onFinish?.()
+    return () => {}
+  }
+
+  let raf
+  let start
+  const step = (now) => {
+    start ??= now
+    const elapsed = now - start - delay
+    if (elapsed < 0) {
+      raf = requestAnimationFrame(step)
+      return
+    }
+    const t = Math.min(1, elapsed / duration)
+    onFrame(fn(t), t)
+    if (t < 1) raf = requestAnimationFrame(step)
+    else onFinish?.()
+  }
+  raf = requestAnimationFrame(step)
+  return () => cancelAnimationFrame(raf)
+}

data/app/javascript/poetry/charts/motion_controller.js

@@ -0,0 +1,230 @@
+import { Controller } from "@hotwired/stimulus"
+import { tween } from "@poetry/charts/motion/tween"
+import { sectorPath } from "@poetry/charts/motion/sector"
+import { captureGeometry, matchJobs, applyJobs, finishJobs } from "@poetry/charts/motion/flip"
+
+// The chart motion engine: the JS half of the entrance tier plus
+// the cross-render morph. Cartesian + radar entrances are pure CSS (the
+// motion stylesheet); this controller adds what CSS cannot do - the polar
+// fan-out and the FLIP morph between server renders - and stamps a
+// data-motion lifecycle attribute ("entrance" / "morph" -> "settled") on
+// the SVG so tests and hosts can observe the engine.
+//
+// ENTRANCE. The fan-out is a step accumulator: every sector's
+// angular width interpolates 0 -> final
+// simultaneously, re-accumulated end-to-end each frame from the group's
+// first startAngle, with the FINAL-geometry gaps preserved as constant
+// padding. Sectors carry their server-computed params in
+// data-motion-sector and their sweep group in data-motion-group (pie: one
+// group per ring; radial: one per band). Mid-sweep paths are plain
+// sectors; the exact server d (corner rounding included) is restored on
+// the final frame.
+//
+// MORPH. Charts with a stable id keep their last geometry in a
+// module registry when they disconnect; when a same-id chart connects
+// within the freshness window (any same-context DOM swap - Turbo Drive /
+// Frames / Streams / morph), the new render starts FROM the old geometry
+// and tweens to its own via the shared FLIP machinery (motion/flip.js -
+// the live tier rides the same module). Any structure change
+// aborts the morph and the normal entrance replays instead - added or
+// removed data never morphs.
+//
+// prefers-reduced-motion (or animate: false) settles immediately - the
+// server-rendered chart is already the finished state.
+
+const MORPH_WINDOW_MS = 5000
+
+// chartId -> { at, entries } across controller lifetimes (module-scoped:
+// the old render's controller writes it on disconnect, the new render's
+// reads it on connect - same JS context, so Turbo swaps carry it over).
+const registry = new Map()
+
+export default class ChartMotionController extends Controller {
+  // The events this controller dispatches (manifest surface;
+  // events_declaration.test.js enforces the list stays honest).
+  static events = ["poetry--charts--motion:settled"]
+
+  #onBeforeRender = null
+  #onTurboMorph = null
+
+  /**
+   * Resolves the SVG, wires the Turbo page-morph hooks (the body
+   * comment holds the blank-entrance rule), and starts the entrance or
+   * morph.
+   */
+  connect() {
+    this.svg = this.element.querySelector('[data-slot="chart-svg"]')
+    if (!this.svg) return
+    this.chartId = this.element.closest("[data-chart]")?.dataset.chart
+
+    // A Turbo PAGE morph preserves this element (no disconnect/connect),
+    // yet replaces the SVG - without these hooks the fresh render replays
+    // the CSS entrance from blank (the area chart's scaleX(0) frame).
+    // Capture geometry before the morph, then rejoin the normal flow.
+    this.#onBeforeRender = (event) => {
+      if (event.detail?.renderMethod !== "morph") return
+      if (this.chartId && this.svg?.isConnected) {
+        registry.set(this.chartId, { at: performance.now(), entries: captureGeometry(this.svg) })
+      }
+    }
+    this.#onTurboMorph = () => this.#restartAfterTurboMorph()
+    document.addEventListener("turbo:before-render", this.#onBeforeRender)
+    document.addEventListener("turbo:morph", this.#onTurboMorph)
+
+    this.#start()
+  }
+
+  #start() {
+    if (!this.svg.hasAttribute("data-animate") || this.#reducedMotion()) {
+      this.#settle()
+      return
+    }
+
+    if (this.#morphFromRegistry()) return
+
+    const sectors = [...this.svg.querySelectorAll("[data-motion-sector]")]
+    if (sectors.length) this.#sweep(sectors)
+    else this.#watchCssEntrance()
+  }
+
+  #restartAfterTurboMorph() {
+    const svg = this.element.querySelector('[data-slot="chart-svg"]')
+    if (!svg) return
+
+    this.cancel?.()
+    this.cancel = null
+    this.svg = svg
+    this.#start()
+  }
+
+  /**
+   * Unwires the Turbo hooks, abandons any tween, and parks the current
+   * geometry in the registry for a same-id successor.
+   */
+  disconnect() {
+    document.removeEventListener("turbo:before-render", this.#onBeforeRender)
+    document.removeEventListener("turbo:morph", this.#onTurboMorph)
+    this.cancel?.()
+    this.cancel = null
+    if (this.chartId && this.svg) {
+      registry.set(this.chartId, { at: performance.now(), entries: captureGeometry(this.svg) })
+    }
+  }
+
+  // -- the cross-render morph -----------------------------------------------
+
+  #morphFromRegistry() {
+    if (!this.chartId) return false
+    const previous = registry.get(this.chartId)
+    if (!previous) return false
+    registry.delete(this.chartId)
+    if (performance.now() - previous.at > MORPH_WINDOW_MS) return false
+
+    const jobs = matchJobs(this.svg, previous.entries)
+    if (!jobs) return false
+
+    // Stamped before the first paint of the new render, so the morph-kill
+    // CSS rule suppresses the entrance animations that would otherwise
+    // start on the fresh elements.
+    this.svg.setAttribute("data-motion", "morph")
+    applyJobs(jobs, 0) // FLIP: the new render starts at the OLD geometry
+
+    this.cancel = tween({
+      duration: this.#number("--poetry-motion-duration", 1500),
+      easing: this.#styleVar("--poetry-motion-easing") ?? "ease",
+      onFrame: (eased) => applyJobs(jobs, eased),
+      onFinish: () => {
+        finishJobs(jobs)
+        this.#settle()
+      },
+    })
+    return true
+  }
+
+  // -- the polar fan-out ------------------------------------------------
+
+  #sweep(elements) {
+    const groups = new Map()
+    for (const el of elements) {
+      const [cx, cy, inner, outer, start, end] = el.dataset.motionSector.split(" ").map(Number)
+      const key = el.dataset.motionGroup ?? "all"
+      if (!groups.has(key)) groups.set(key, [])
+      groups.get(key).push({ el, cx, cy, inner, outer, start, end, final: el.getAttribute("d") })
+    }
+
+    // Hold the entrance state through animation_begin - the delay
+    // shows the entrance state, not the finished chart.
+    this.svg.setAttribute("data-motion", "entrance")
+    const frame = (eased) => {
+      for (const sectors of groups.values()) {
+        let cursor = sectors[0].start
+        let previousEnd = sectors[0].start
+        for (const s of sectors) {
+          const pad = s.start - previousEnd
+          const delta = (s.end - s.start) * eased
+          const from = cursor + pad
+          s.el.setAttribute("d", sectorPath(s.cx, s.cy, s.inner, s.outer, from, from + delta))
+          previousEnd = s.end
+          cursor = from + delta
+        }
+      }
+    }
+    frame(0)
+
+    this.cancel = tween({
+      duration: this.#number("--poetry-motion-duration", 1500),
+      delay: this.#number("--poetry-motion-delay", 0),
+      easing: this.#styleVar("--poetry-motion-easing") ?? "ease",
+      onFrame: frame,
+      onFinish: () => {
+        for (const sectors of groups.values()) {
+          for (const s of sectors) s.el.setAttribute("d", s.final)
+        }
+        this.#settle()
+      },
+    })
+  }
+
+  // -- the CSS entrance observer ------------------------------------------
+
+  #watchCssEntrance() {
+    if (typeof this.svg.getAnimations !== "function") {
+      this.#settle()
+      return
+    }
+    const animations = this.svg
+      .getAnimations({ subtree: true })
+      .filter((a) => a.animationName?.startsWith("poetry-chart"))
+    if (!animations.length) {
+      this.#settle()
+      return
+    }
+    this.svg.setAttribute("data-motion", "entrance")
+    Promise.allSettled(animations.map((a) => a.finished)).then(() => {
+      if (this.svg.isConnected) this.#settle()
+    })
+  }
+
+  // -- shared ---------------------------------------------------------------
+
+  #settle() {
+    this.svg.setAttribute("data-motion", "settled")
+    this.dispatch("settled")
+  }
+
+  // The --poetry-motion-* knobs ride the SVG's inline style - our own wire
+  // format, so parse the attribute (jsdom-safe, the tooltip's viewBox lesson).
+  #styleVar(name) {
+    const match = (this.svg.getAttribute("style") ?? "").match(new RegExp(`${name}:\\s*([^;]+)`))
+    return match ? match[1].trim() : null
+  }
+
+  #number(name, fallback) {
+    const value = parseFloat(this.#styleVar(name))
+    return Number.isFinite(value) ? value : fallback
+  }
+
+  #reducedMotion() {
+    return typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches
+  }
+}