dsh-plugin-show-me-data 0.1.0

package/lib/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/lib/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/lib/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))}…`
+}