dsh-plugin-show-me-data 0.1.0

package/src/core/chart/candle.js

@@ -0,0 +1,216 @@
+/**
+ * Candlestick geometry and hover snapping (docs/05 §4).
+ *
+ * The panel draws its own SVG, so a candle is four numbers turned into two
+ * screen-space primitives: a thin high-low wick and a body spanning open to
+ * close. Everything here is a pure function of points and geometry, which keeps
+ * the interactive chart testable without a browser.
+ *
+ * Colour is deliberately *not* decided here: the caller owns polarity, and the
+ * only rule this layer encodes is the arithmetic — a candle is up when the close
+ * is at or above the open.
+ *
+ * @module core/chart/candle
+ */
+
+import { ohlcOf } from '../stats/series.js'
+import { box } from './line.js'
+import { clamp, extent, linearScale, niceTicks } from './scale.js'
+
+/** Default share of one x-step a candle body may occupy. */
+export const BODY_RATIO = 0.7
+
+/**
+ * Widest a candle body may be drawn, in px.
+ *
+ * With few points the step is enormous, and a one-step-wide bar reads as a
+ * block rather than a bar; capping the width keeps three points looking like
+ * three candles.
+ */
+export const MAX_BODY_PX = 16
+
+/**
+ * The value domain a chart should cover.
+ *
+ * A candlestick view must span the wicks, not only the closes: using the close
+ * extent would clip highs and lows at the top and bottom of the plot.
+ *
+ * @param {Array<{ t: string, v: number, o?: number, h?: number, l?: number }>} points - ascending points.
+ * @param {{ useExtremes?: boolean }} [options] - options.
+ * @returns {{ min: number, max: number }|undefined} domain, or 'undefined' when nothing is finite.
+ */
+export function valueDomain(points, options = {}) {
+  const values = []
+  for (const point of points ?? []) {
+    if (!Number.isFinite(point?.v)) continue
+    const bar = options.useExtremes === true ? ohlcOf(point) : undefined
+    values.push(bar === undefined ? point.v : bar.h, bar === undefined ? point.v : bar.l)
+  }
+  return extent(values)
+}
+
+/**
+ * Build candle geometry for a point list.
+ *
+ * Every entry carries the numbers the renderer needs and nothing else: `up` is
+ * the arithmetic fact (close >= open) that the caller maps to a colour, and
+ * `hollow` marks a bar whose body is too short to fill, which is how a flat
+ * session still shows as a visible tick rather than disappearing.
+ *
+ * @param {Array<{ t: string, v: number, o?: number, h?: number, l?: number }>} points - ascending points.
+ * @param {{ width: number, height: number, padding?: number, paddingX?: number, paddingY?: number, yDomain?: { min: number, max: number }, bodyRatio?: number, maxBody?: number, minBody?: number }} geometry - chart geometry.
+ * @returns {Array<{ t: string, x: number, yHigh: number, yLow: number, yOpen: number, yClose: number, bodyTop: number, bodyH: number, up: boolean, hollow: boolean, point: object }>} candles.
+ */
+export function buildCandles(points, geometry) {
+  const list = points ?? []
+  const bars = list.filter((point) => ohlcOf(point) !== undefined)
+  if (bars.length === 0) return []
+  const { innerW, padX, padY, innerH } = box({ ...geometry, height: geometry.height })
+  const domain = geometry.yDomain ?? valueDomain(list, { useExtremes: true })
+  if (domain === undefined) return []
+  const y = linearScale({ domain: [domain.min, domain.max], range: [padY + innerH, padY] })
+  const step = list.length > 1 ? innerW / (list.length - 1) : innerW
+  const bodyW = Math.max(1, Math.min(geometry.maxBody ?? MAX_BODY_PX, step * (geometry.bodyRatio ?? BODY_RATIO)))
+  const minBody = geometry.minBody ?? 1
+  return list.map((point, index) => {
+    const bar = ohlcOf(point)
+    if (bar === undefined) return undefined
+    const x = padX + (list.length > 1 ? (index / (list.length - 1)) * innerW : innerW / 2)
+    const yOpen = y(bar.o)
+    const yClose = y(point.v)
+    const yHigh = y(bar.h)
+    const yLow = y(bar.l)
+    const bodyTop = Math.min(yOpen, yClose)
+    const bodyH = Math.abs(yClose - yOpen)
+    return {
+      t: point.t,
+      x: Number(x.toFixed(2)),
+      bodyW: Number(bodyW.toFixed(2)),
+      yHigh: Number(yHigh.toFixed(2)),
+      yLow: Number(yLow.toFixed(2)),
+      yOpen: Number(yOpen.toFixed(2)),
+      yClose: Number(yClose.toFixed(2)),
+      bodyTop: Number(bodyTop.toFixed(2)),
+      bodyH: Number(Math.max(minBody, bodyH).toFixed(2)),
+      up: point.v >= bar.o,
+      hollow: bodyH < minBody,
+      point,
+    }
+  }).filter(Boolean)
+}
+
+/**
+ * Snap a pointer position to the nearest data index.
+ *
+ * Charts are read by pointing at a shape, so the hover target is the nearest
+ * *point*, never the exact pixel: this is what makes a 250-bar chart usable with
+ * a mouse and what a touch device needs to hit anything at all.
+ *
+ * @param {number} pointerX - pointer x in svg coordinates.
+ * @param {number} count - number of points.
+ * @param {{ width: number, padding?: number, paddingX?: number }} geometry - chart geometry.
+ * @returns {number} nearest index, or -1 when there is nothing to snap to.
+ */
+export function nearestIndex(pointerX, count, geometry) {
+  if (!Number.isFinite(pointerX) || !(count > 0)) return -1
+  const { padX, innerW } = box({ ...geometry, height: geometry.height ?? 1 })
+  if (count === 1) return 0
+  const ratio = clamp((pointerX - padX) / innerW, 0, 1)
+  return Math.round(ratio * (count - 1))
+}
+
+/**
+ * The x coordinate of one index inside the plotting box.
+ *
+ * @param {number} index - point index.
+ * @param {number} count - number of points.
+ * @param {{ width: number, padding?: number, paddingX?: number }} geometry - chart geometry.
+ * @returns {number} x in svg coordinates.
+ */
+export function indexToX(index, count, geometry) {
+  const { padX, innerW } = box({ ...geometry, height: geometry.height ?? 1 })
+  if (count <= 1) return padX + innerW / 2
+  return Number((padX + (index / (count - 1)) * innerW).toFixed(2))
+}
+
+/**
+ * Build the crosshair and its labels for one hovered index.
+ *
+ * @param {object} input - input.
+ * @param {Array<{ t: string, v: number, o?: number, h?: number, l?: number }>} input.points - ascending points.
+ * @param {number} input.index - hovered index.
+ * @param {{ width: number, height: number, padding?: number, paddingX?: number, paddingY?: number, yDomain?: { min: number, max: number } }} input.geometry - chart geometry.
+ * @returns {{ x: number, y: number, index: number, point: object, bar: object|undefined, anchoredLeft: boolean }|undefined} crosshair state.
+ */
+export function buildCrosshair({ points, index, geometry }) {
+  const list = points ?? []
+  if (index < 0 || index >= list.length) return undefined
+  const point = list[index]
+  const { innerW, padX, padY, innerH } = box({ ...geometry, height: geometry.height ?? 1 })
+  const bar = ohlcOf(point)
+  const domain = geometry.yDomain ?? valueDomain(list, { useExtremes: bar !== undefined })
+  const y = linearScale({ domain: domain === undefined ? [0, 1] : [domain.min, domain.max], range: [padY + innerH, padY] })
+  const x = indexToX(index, list.length, geometry)
+  return {
+    index,
+    x,
+    y: Number(y(point.v).toFixed(2)),
+    point,
+    bar,
+    // The tooltip flips side near the right edge so it never runs out of frame.
+    anchoredLeft: x > padX + innerW * 0.62,
+  }
+}
+
+/**
+ * Horizontal reference lines worth drawing for a series.
+ *
+ * A reader compares the latest reading against the window, so the mean and the
+ * two extremes are the lines that carry information. Each one is emitted only
+ * when it is finite, and identical values collapse: a two-point series has a
+ * mean but a flat one has extremes equal to the last value, which would stack
+ * three labels on one pixel.
+ *
+ * @param {{ min?: number, max?: number, mean?: number }} [stats] - series statistics.
+ * @param {{ min: number, max: number }} domain - drawn domain.
+ * @param {{ plot: { x: number, y: number, w: number, h: number } }} layout - resolved plot box.
+ * @returns {Array<{ kind: string, label: string, value: number, y: number, x1: number, x2: number }>} reference lines.
+ */
+export function buildReferenceLines(stats, domain, layout) {
+  if (stats === undefined || domain === undefined || layout?.plot === undefined) return []
+  const { x, w, y: top, h } = layout.plot
+  const y = linearScale({ domain: [domain.min, domain.max], range: [top + h, top] })
+  const candidates = [
+    { kind: 'max', value: stats.max, label: '高' },
+    { kind: 'mean', value: stats.mean, label: '均' },
+    { kind: 'min', value: stats.min, label: '低' },
+  ]
+  const out = []
+  const seen = new Set()
+  for (const candidate of candidates) {
+    if (!Number.isFinite(candidate.value)) continue
+    const key = candidate.value.toFixed(6)
+    if (seen.has(key)) continue
+    seen.add(key)
+    out.push({
+      kind: candidate.kind,
+      label: candidate.label,
+      value: candidate.value,
+      y: Number(y(candidate.value).toFixed(2)),
+      x1: x,
+      x2: x + w,
+    })
+  }
+  return out
+}
+
+/**
+ * A readable tick list for the value axis.
+ *
+ * @param {{ min: number, max: number }} domain - data domain.
+ * @param {number} [count] - desired ticks.
+ * @returns {{ min: number, max: number, ticks: number[] }} nice domain and ticks.
+ */
+export function valueAxis(domain, count = 5) {
+  return niceTicks(domain.min, domain.max, count)
+}

package/src/core/chart/line.js

@@ -0,0 +1,186 @@
+/**
+ * Line, area and sparkline path builders (docs/05 §4.1).
+ *
+ * @module core/chart/line
+ */
+import { extent, linearScale, thin } from './scale.js'
+
+/**
+ * @typedef {Object} ChartGeometry
+ * @property {number} width - svg width in px.
+ * @property {number} height - svg height in px.
+ * @property {number} [padding] - uniform inset, or use 'paddingX'/'paddingY'.
+ * @property {number} [paddingX] - horizontal inset.
+ * @property {number} [paddingY] - vertical inset.
+ * @property {number} [padLeft] - left inset (wins over 'paddingX').
+ * @property {number} [padRight] - right inset (the value axis lives here).
+ * @property {number} [padTop] - top inset.
+ * @property {number} [padBottom] - bottom inset (the time axis lives here).
+ * @property {number} [innerW] - explicit inner width, for index-based builders.
+ * @property {number} [innerH] - explicit inner height.
+ * @property {number} [padX] - explicit left inset (already resolved).
+ * @property {{ min: number, max: number }} [yDomain] - explicit y domain.
+ * @property {number} [maxPoints] - point budget before thinning.
+ */
+
+/**
+ * Resolve padding and plotting box from the geometry spec.
+ *
+ * @param {ChartGeometry} geometry - chart geometry.
+ * @returns {{ width: number, height: number, padX: number, padY: number, innerW: number, innerH: number }} box.
+ */
+export function box(geometry) {
+  const { width, height } = geometry
+  if (!(width > 0) || !(height > 0)) {
+    throw new Error(`chart geometry requires positive width/height (got ${width}x${height})`)
+  }
+  // Asymmetric gutters matter: the value axis is read on the right and the time
+  // axis along the bottom, so a uniform inset either clips labels or wastes the
+  // left edge. Explicit 'padX'/'padY'/'innerW'/'innerH' still win, because the
+  // chart component resolves the plot box once and passes it down.
+  const padX = geometry.padX ?? geometry.padLeft ?? geometry.paddingX ?? geometry.padding ?? 0
+  const padY = geometry.padY ?? geometry.padTop ?? geometry.paddingY ?? geometry.padding ?? 0
+  const padRight = geometry.padRight ?? geometry.paddingX ?? geometry.padding ?? padX
+  const padBottom = geometry.padBottom ?? geometry.paddingY ?? geometry.padding ?? padY
+  return {
+    width,
+    height,
+    padX,
+    padY,
+    padRight,
+    padBottom,
+    innerW: geometry.innerW ?? Math.max(1, width - padX - padRight),
+    innerH: geometry.innerH ?? Math.max(1, height - padY - padBottom),
+  }
+}
+
+/**
+ * Format a path coordinate: two decimals is sub-pixel on any display and keeps
+ * the generated path strings small.
+ *
+ * @param {number} value - coordinate.
+ * @returns {string} formatted coordinate.
+ */
+function coord(value) {
+  const rounded = Math.round(value * 100) / 100
+  return String(Object.is(rounded, -0) ? 0 : rounded)
+}
+
+/**
+ * Build the list of straight (non-NaN) runs in a point list. A 'NaN' value is a
+ * genuine break — the series is drawn as two sub-paths, never bridged
+ * (docs/05 §4.1).
+ *
+ * @param {Array<{ t: string, v: number }>} points - ascending points.
+ * @returns {Array<Array<{ t: string, v: number }>>} runs.
+ */
+export function runs(points) {
+  const out = []
+  let current = []
+  for (const point of points) {
+    if (Number.isFinite(point?.v)) {
+      current.push(point)
+    } else if (current.length > 0) {
+      out.push(current)
+      current = []
+    }
+  }
+  if (current.length > 0) out.push(current)
+  return out
+}
+
+/**
+ * Build an SVG path for a line chart.
+ *
+ * - '[]' → ''''
+ * - one point → ''M x y'' (a move only; no 'L')
+ * - a flat series → a horizontal line at the vertical centre
+ *
+ * @param {Array<{ t: string, v: number }>} points - ascending points.
+ * @param {ChartGeometry} geometry - chart geometry.
+ * @returns {string} SVG path data.
+ */
+export function buildLinePath(points, geometry) {
+  if (!Array.isArray(points) || points.length === 0) return ''
+  const { innerW, innerH, padX, padY } = box(geometry)
+  if (!points.some((p) => Number.isFinite(p?.v))) return ''
+
+  const budget = geometry.maxPoints ?? Number.POSITIVE_INFINITY
+  // The x axis is always proportional to the *declared* index span, so a `NaN`
+  // hole keeps its width instead of compressing the visible series. Thinning
+  // (only for huge series) collapses missing entries, which is acceptable at
+  // that scale.
+  const thinFirst = points.map((p, index) => ({ t: p.t, v: Number.isFinite(p?.v) ? p.v : Number.NaN, i: index }))
+  const drawn = Number.isFinite(budget) && points.length > budget
+    ? thin(thinFirst, budget)
+    : thinFirst
+  const finite = thinFirst.filter((p) => Number.isFinite(p.v))
+  if (finite.length === 0) return ''
+  const xSpan = Math.max(1, points.length - 1)
+  const x = (index) => padX + (index / xSpan) * innerW
+
+  const domain = extent(finite.map((p) => p.v))
+  const yDomain = geometry.yDomain ?? domain
+  const y = linearScale({ domain: [yDomain.min, yDomain.max], range: [padY + innerH, padY] })
+
+  const parts = []
+  for (const run of runs(drawn)) {
+    run.forEach((point, runIndex) => {
+      const command = runIndex === 0 ? 'M' : 'L'
+      parts.push(`${command}${coord(x(point.i))} ${coord(y(point.v))}`)
+    })
+  }
+  return parts.join('')
+}
+
+/**
+ * Build a closed area path: the line plus a drop to the baseline.
+ *
+ * @param {Array<{ t: string, v: number }>} points - ascending points.
+ * @param {ChartGeometry} geometry - chart geometry.
+ * @returns {string} SVG path data ('''' when there is nothing to draw).
+ */
+export function buildAreaPath(points, geometry) {
+  const line = buildLinePath(points, geometry)
+  if (line === '') return ''
+  const { innerH, padY } = box(geometry)
+  const baseline = padY + innerH
+  const coordinates = line.match(/[ML]([\d.-]+) ([\d.-]+)/g) ?? []
+  if (coordinates.length === 0) return ''
+  const first = coordinates[0].slice(1).split(' ')[0]
+  const last = coordinates[coordinates.length - 1].slice(1).split(' ')[0]
+  return `${line}L${last} ${coord(baseline)}L${first} ${coord(baseline)}Z`
+}
+
+/**
+ * Build a sparkline path (no axes, no grid). A single point yields '''' so the
+ * card can draw a dot instead of a degenerate path — frozen by tests.
+ *
+ * @param {number[]} values - values, oldest first.
+ * @param {{ width: number, height: number, padding?: number }} geometry - sparkline geometry.
+ * @returns {string} SVG path data.
+ */
+export function buildSparkline(values, geometry) {
+  if (!Array.isArray(values) || values.length < 2) return ''
+  const points = values.map((v, i) => ({ t: String(i), v }))
+  return buildLinePath(points, { width: geometry.width, height: geometry.height, padding: geometry.padding ?? 1 })
+}
+
+/**
+ * Build the SVG markup for a sparkline, including the end-point dot. Returns
+ * '''' when there is nothing to draw, which the card renders as a placeholder.
+ *
+ * @param {number[]} values - values, oldest first.
+ * @param {{ width: number, height: number, padding?: number, dotRadius?: number }} geometry - sparkline geometry.
+ * @returns {{ path: string, dot: { cx: number, cy: number, r: number }|null }} path and end dot.
+ */
+export function buildSparklineShape(values, geometry) {
+  const path = buildSparkline(values, geometry)
+  if (path === '') return { path: '', dot: null }
+  const matches = [...path.matchAll(/[ML]([\d.-]+) ([\d.-]+)/g)]
+  const last = matches[matches.length - 1]
+  return {
+    path,
+    dot: { cx: Number(last[1]), cy: Number(last[2]), r: geometry.dotRadius ?? 1.5 },
+  }
+}

package/src/core/chart/scale.js

@@ -0,0 +1,132 @@
+/**
+ * SVG path geometry for the panel's charts (docs/05 §4.1).
+ *
+ * Everything here is a pure function of numbers to strings/arrays, so the charts
+ * are unit-testable without a browser — that is the whole reason the panel draws
+ * its own SVG instead of pulling in a chart library (docs/02 §1.1).
+ *
+ * @module core/chart/scale
+ */
+
+/**
+ * Clamp a number into a closed range.
+ *
+ * @param {number} value - candidate.
+ * @param {number} min - lower bound.
+ * @param {number} max - upper bound.
+ * @returns {number} clamped value.
+ */
+export function clamp(value, min, max) {
+  return Math.min(Math.max(value, min), max)
+}
+
+/**
+ * Build a linear scale from a data domain to a pixel range.
+ *
+ * A degenerate domain ('min === max', or any non-finite bound) maps every value
+ * to the middle of the range instead of dividing by zero — the branch that turns
+ * a flat series into 'NaN' paths (docs/08 §2 defect 5).
+ *
+ * @param {{ domain: [number, number], range: [number, number] }} spec - scale spec.
+ * @returns {(value: number) => number} scale function.
+ */
+export function linearScale({ domain, range }) {
+  const [d0, d1] = domain
+  const [r0, r1] = range
+  if (!Number.isFinite(d0) || !Number.isFinite(d1) || d0 === d1) {
+    const middle = (r0 + r1) / 2
+    return () => middle
+  }
+  const factor = (r1 - r0) / (d1 - d0)
+  return (value) => r0 + (value - d0) * factor
+}
+
+/**
+ * Extend a domain to the nearest "nice" bounds and pick evenly spaced ticks
+ * built from 1/2/5 × 10ⁿ steps (docs/05 §4.1).
+ *
+ * @param {number} min - data minimum.
+ * @param {number} max - data maximum.
+ * @param {number} [count] - desired tick count (approximate).
+ * @returns {{ min: number, max: number, ticks: number[] }} nice domain and ticks.
+ */
+export function niceTicks(min, max, count = 5) {
+  if (!Number.isFinite(min) || !Number.isFinite(max)) {
+    return { min: 0, max: 1, ticks: [0, 0.5, 1] }
+  }
+  if (min === max) {
+    const pad = Math.abs(min) > 0 ? Math.abs(min) * 0.1 : 1
+    const lo = min - pad
+    const hi = max + pad
+    return { min: lo, max: hi, ticks: [lo, (lo + hi) / 2, hi] }
+  }
+  const steps = Math.max(1, Math.floor(count))
+  const rawStep = (max - min) / steps
+  const magnitude = 10 ** Math.floor(Math.log10(rawStep))
+  const normalized = rawStep / magnitude
+  const niceStep = (normalized <= 1 ? 1 : normalized <= 2 ? 2 : normalized <= 5 ? 5 : 10) * magnitude
+  const lo = Math.floor(min / niceStep) * niceStep
+  const hi = Math.ceil(max / niceStep) * niceStep
+  const ticks = []
+  for (let value = lo; value <= hi + niceStep / 2; value += niceStep) {
+    // Round away accumulated float noise (0.30000000000000004 → 0.3).
+    ticks.push(Number(value.toFixed(12)))
+  }
+  return { min: lo, max: hi, ticks }
+}
+
+/**
+ * Min/max of a numeric list, ignoring non-finite entries.
+ *
+ * @param {number[]} values - candidate values.
+ * @returns {{ min: number, max: number }|undefined} extent, or 'undefined' when nothing is finite.
+ */
+export function extent(values) {
+  let min = Number.POSITIVE_INFINITY
+  let max = Number.NEGATIVE_INFINITY
+  let seen = false
+  for (const value of values) {
+    if (!Number.isFinite(value)) continue
+    seen = true
+    if (value < min) min = value
+    if (value > max) max = value
+  }
+  return seen ? { min, max } : undefined
+}
+
+/**
+ * Reduce a series to at most two points per pixel column, preserving the first
+ * and last points plus each bucket's extremes so the shape is not flattened
+ * (docs/05 §4.1: 10k points must not produce 10k path segments).
+ *
+ * @param {Array<{ t: string, v: number }>} points - ascending points.
+ * @param {number} maxPoints - budget.
+ * @returns {Array<{ t: string, v: number }>} thinned points.
+ */
+export function thin(points, maxPoints) {
+  if (points.length <= maxPoints) return points
+  const finite = points.filter((p) => Number.isFinite(p.v))
+  if (finite.length <= maxPoints) return points
+  const bucketCount = Math.max(1, Math.floor(maxPoints / 2))
+  const bucketSize = finite.length / bucketCount
+  const out = []
+  for (let bucket = 0; bucket < bucketCount; bucket += 1) {
+    const start = Math.floor(bucket * bucketSize)
+    const end = Math.min(finite.length, Math.floor((bucket + 1) * bucketSize))
+    if (end <= start) continue
+    let lowest = finite[start]
+    let highest = finite[start]
+    for (let i = start; i < end; i += 1) {
+      if (finite[i].v < lowest.v) lowest = finite[i]
+      if (finite[i].v > highest.v) highest = finite[i]
+    }
+    const pair = lowest.t <= highest.t ? [lowest, highest] : [highest, lowest]
+    for (const point of pair) {
+      if (out.length === 0 || out[out.length - 1].t !== point.t) out.push(point)
+    }
+  }
+  // Always keep the true endpoints so the line spans the full width.
+  const last = finite[finite.length - 1]
+  if (out.length === 0 || out[out.length - 1].t !== last.t) out.push(last)
+  return out
+}

package/src/core/format.js

@@ -0,0 +1,143 @@
+/**
+ * Formatting shared by the panel and (for the digest) the host — pure functions,
+ * no DOM, no locale API (docs/05 §4.3, §6).
+ *
+ * @module core/format
+ */
+
+/** Semantic colour keys the panel maps to theme tokens. */
+export const COLORS = ['up', 'down', 'neutral', 'warn', 'error']
+
+/**
+ * Format a number for display: fixed decimals, grouped thousands, explicit
+ * sign where a sign carries meaning.
+ *
+ * @param {number|undefined} value - value.
+ * @param {{ decimals?: number, signed?: boolean, compact?: boolean }} [options] - formatting options.
+ * @returns {string} display text (''—'' when absent).
+ */
+export function formatValue(value, { decimals = 2, signed = false, compact = false } = {}) {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return '—'
+  const fixed = value.toFixed(Math.max(0, Math.min(8, decimals)))
+  const [intPart, fraction] = fixed.split('.')
+  const negative = intPart.startsWith('-')
+  const digits = negative ? intPart.slice(1) : intPart
+  let grouped = digits
+  if (compact && digits.length > 9) {
+    const billions = Number(digits) / 1e9
+    grouped = `${billions.toFixed(1)}B`
+    return `${negative ? '-' : signed ? '+' : ''}${grouped}`
+  }
+  if (digits.length > 3) grouped = digits.replace(/\B(?=(\d{3})+(?!\d))/g, ',')
+  const sign = negative ? '-' : signed ? '+' : ''
+  return fraction === undefined ? `${sign}${grouped}` : `${sign}${grouped}.${fraction}`
+}
+
+/**
+ * Format a change with a direction arrow, for card deltas.
+ *
+ * @param {number|undefined} changeAbs - absolute change.
+ * @param {number|undefined} changePct - percentage change.
+ * @param {string} unit - unit suffix.
+ * @param {number} [decimals] - decimals for the absolute change.
+ * @returns {string} display text.
+ */
+export function formatChange(changeAbs, changePct, unit, decimals = 2) {
+  if (typeof changeAbs !== 'number' || !Number.isFinite(changeAbs)) return '—'
+  const arrow = changeAbs > 0 ? '▲' : changeAbs < 0 ? '▼' : '·'
+  const absolute = formatValue(changeAbs, { decimals, signed: true })
+  const percent = typeof changePct === 'number' && Number.isFinite(changePct) ? ` (${formatValue(changePct, { decimals: 1, signed: true })}%)` : ''
+  return `${arrow} ${absolute}${unit === '' ? '' : unit}${percent}`
+}
+
+/**
+ * Compact relative time for "last updated" labels.
+ *
+ * @param {number} minutes - age in minutes.
+ * @returns {string} display text.
+ */
+export function formatAge(minutes) {
+  if (!Number.isFinite(minutes) || minutes < 0) return '未知时间'
+  if (minutes < 1) return '刚刚'
+  if (minutes < 60) return `${Math.round(minutes)} 分钟前`
+  if (minutes < 60 * 24) return `${Math.round(minutes / 60)} 小时前`
+  const days = Math.round(minutes / (60 * 24))
+  return days === 1 ? '昨天' : `${days} 天前`
+}
+
+/**
+ * Whether a change should read as good, bad or neutral — decided by the
+ * indicator's 'polarity', never by the sign of the number alone
+ * (docs/05 §4.3: rising CPI is not "red" the way rising unemployment is).
+ *
+ * @param {number|undefined} change - signed change.
+ * @param {'up-is-good'|'down-is-good'|'neutral'} [polarity] - catalog polarity.
+ * @returns {'up'|'down'|'neutral'} colour key.
+ */
+export function changeColor(change, polarity = 'neutral') {
+  if (typeof change !== 'number' || !Number.isFinite(change) || change === 0) return 'neutral'
+  if (polarity === 'neutral') return 'neutral'
+  const good = polarity === 'up-is-good' ? change > 0 : change < 0
+  return good ? 'up' : 'down'
+}
+
+/**
+ * Status dot semantics (docs/03 §1.7).
+ *
+ * @param {'fresh'|'stale'|'error'|'missing'} status - metric status.
+ * @returns {{ color: 'up'|'warn'|'error'|'neutral', label: string }} dot description.
+ */
+export function statusDot(status) {
+  switch (status) {
+    case 'fresh':
+      return { color: 'up', label: '数据最新' }
+    case 'stale':
+      return { color: 'warn', label: '数据可能陈旧' }
+    case 'error':
+      return { color: 'error', label: '数据源暂不可用' }
+    default:
+      return { color: 'neutral', label: '本范围内无数据' }
+  }
+}
+
+/**
+ * Format a calendar date for display.
+ *
+ * @param {string|undefined} date - 'YYYY-MM-DD'.
+ * @param {{ withYear?: boolean }} [options] - options.
+ * @returns {string} display text.
+ */
+export function formatDate(date, { withYear = true } = {}) {
+  if (typeof date !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(date)) return '—'
+  return withYear ? date : date.slice(5)
+}
+
+/**
+ * Build the tooltip text for one card, used by the 'title' attribute and by the
+ * accessible label.
+ *
+ * @param {object} metric - metric card.
+ * @returns {string} tooltip.
+ */
+export function metricTooltip(metric) {
+  const parts = [
+    `${metric.label?.zh ?? metric.indicatorId}（${metric.indicatorId}）`,
+    `最新：${formatValue(metric.latest, { decimals: metric.display?.decimals ?? 2 })}${metric.unit ?? ''} @ ${formatDate(metric.latestAt)}`,
+  ]
+  if (metric.notes?.zh) parts.push(metric.notes.zh)
+  if (metric.sourceRef?.label) parts.push(`来源：${metric.sourceRef.label}`)
+  parts.push(`状态：${statusDot(metric.status).label}`)
+  return parts.join('\n')
+}
+
+/**
+ * Truncate text for a compact label, keeping the tail visible with an ellipsis.
+ *
+ * @param {string} text - input.
+ * @param {number} max - maximum characters.
+ * @returns {string} truncated text.
+ */
+export function truncate(text, max) {
+  const value = String(text ?? '')
+  return value.length <= max ? value : `${value.slice(0, Math.max(1, max - 1))}…`
+}