dsh-plugin-show-me-data 0.1.0

package/src/client/store.js

@@ -0,0 +1,219 @@
+/**
+ * The panel's module-level store (docs/05 §2).
+ *
+ * State lives here rather than in component state because the overlay entry can
+ * be remounted at any time: facts must belong to whoever can also close them. The
+ * store is a plain observable with a tiny subscription API, which makes it
+ * testable without React.
+ *
+ * @module client/store
+ */
+
+/** The initial state. A single object keeps snapshots comparable by identity. */
+export const INITIAL_STATE = {
+  open: false,
+  tab: 'today',
+  range: '1Y',
+  groups: ['US', 'CN', 'GLOBAL', 'CUSTOM'],
+  status: 'idle',
+  lastUpdatedAt: undefined,
+  error: undefined,
+  overview: undefined,
+  detail: undefined,
+  detailLoading: false,
+  // Bar size for OHLC sources: 'day' | 'week' | 'month'.
+  barSize: 'day',
+  ai: { mode: 'deterministic', text: '', streaming: false, result: undefined, error: undefined },
+  discussing: false,
+  discussingId: undefined,
+  discussError: undefined,
+  discussSession: undefined,
+  discussAnswer: undefined,
+  discussPending: false,
+  /** The question this discussion's turn asked, and whether the panel asked it. */
+  discussQuestion: undefined,
+  discussAutoQuestion: false,
+  /** Multi-select: indicator ids picked for one combined analysis. */
+  selected: [],
+  selectionLoading: false,
+  watchlist: [],
+  // Filled from '/settings' + '/health' when the settings tab opens; the panel
+  // shows a loading line until then rather than invented defaults.
+  settings: { sources: [] },
+  health: undefined,
+  /** Connection-test state for the settings screen. */
+  testing: false,
+  testingId: undefined,
+  testResult: undefined,
+  unreachable: false,
+}
+
+/**
+ * Create a store.
+ *
+ * @param {object} [initial] - initial state overrides.
+ * @returns {object} store handle.
+ */
+export function createStore(initial = {}) {
+  let state = { ...INITIAL_STATE, ...initial }
+  /** @type {Set<(state: object, prev: object) => void>} */
+  const listeners = new Set()
+
+  /**
+   * Subscribe to state changes.
+   *
+   * @param {(state: object, prev: object) => void} listener - listener.
+   * @returns {() => void} unsubscribe.
+   */
+  function subscribe(listener) {
+    listeners.add(listener)
+    return () => listeners.delete(listener)
+  }
+
+  /**
+   * Read the current state (stable identity between changes).
+   *
+   * @returns {object} state.
+   */
+  function getState() {
+    return state
+  }
+
+  /**
+   * Apply a patch (object or updater) and notify listeners.
+   *
+   * @param {object|((state: object) => object)} patch - patch.
+   * @returns {object} the new state.
+   */
+  function setState(patch) {
+    const prev = state
+    const next = typeof patch === 'function' ? patch(state) : patch
+    if (next === undefined || next === null) return state
+    // A no-op patch must not notify: components would re-render for nothing.
+    const changed = Object.keys(next).some((key) => next[key] !== state[key])
+    if (!changed) return state
+    state = { ...state, ...next }
+    for (const listener of listeners) listener(state, prev)
+    return state
+  }
+
+  return { getState, setState, subscribe, reset: () => setState({ ...INITIAL_STATE }) }
+}
+
+/**
+ * Merge a fresh overview payload into the state.
+ *
+ * @param {object} state - current state.
+ * @param {object} payload - '/overview' response.
+ * @returns {object} state patch.
+ */
+export function applyOverview(state, payload) {
+  return {
+    status: 'ready',
+    overview: payload,
+    lastUpdatedAt: payload.generatedAt,
+    error: undefined,
+    unreachable: false,
+  }
+}
+
+/**
+ * Merge a fresh detail payload into the state.
+ *
+ * @param {object} state - current state.
+ * @param {object} payload - '/series' response.
+ * @returns {object} state patch.
+ */
+export function applyDetail(state, payload) {
+  return { detail: payload, detailLoading: false, error: undefined }
+}
+
+/**
+ * Forget everything that belonged to the *previous* indicator's answer.
+ *
+ * The AI block, the question box and a discussion are all about one indicator.
+ * Keeping them when the reader selects another card showed one indicator's
+ * answer (and its "open in a new session" note) under a different indicator's
+ * numbers, which reads as the panel answering the wrong question.
+ *
+ * @param {object} state - current state.
+ * @param {string|undefined} indicatorId - the indicator now selected.
+ * @returns {object} state patch.
+ */
+export function applyIndicatorChange(state, indicatorId) {
+  if (state.detail?.indicatorId === indicatorId) return {}
+  return {
+    indicatorId,
+    ai: { ...INITIAL_STATE.ai },
+    discussing: false,
+    discussingId: undefined,
+    discussError: undefined,
+    discussSession: undefined,
+    discussAnswer: undefined,
+    discussPending: false,
+    discussQuestion: undefined,
+    discussAutoQuestion: false,
+  }
+}
+
+/**
+ * Merge an SSE text chunk into the streaming answer.
+ *
+ * @param {object} state - current state.
+ * @param {string} chunk - text chunk.
+ * @returns {object} state patch.
+ */
+export function applyAiText(state, chunk) {
+  return { ai: { ...state.ai, streaming: true, text: `${state.ai.text}${chunk}` } }
+}
+
+/**
+ * Merge a finished AI result.
+ *
+ * @param {object} state - current state.
+ * @param {object} result - validated 'AiResult'.
+ * @returns {object} state patch.
+ */
+export function applyAiResult(state, result) {
+  return {
+    ai: {
+      ...state.ai,
+      streaming: false,
+      result,
+      text: result?.markdown ?? state.ai.text,
+      mode: result?.mode ?? state.ai.mode,
+      error: undefined,
+    },
+  }
+}
+
+/**
+ * Record a failed request.
+ *
+ * @param {object} state - current state.
+ * @param {object} error - structured error.
+ * @param {{ unreachable?: boolean }} [options] - options.
+ * @returns {object} state patch.
+ */
+export function applyError(state, error, { unreachable = false } = {}) {
+  return {
+    status: unreachable ? 'unreachable' : 'error',
+    error,
+    unreachable,
+    detailLoading: false,
+  // Bar size for OHLC sources: 'day' | 'week' | 'month'.
+  barSize: 'day',
+    ai: { ...state.ai, streaming: false, error: undefined },
+  }
+}
+
+/**
+ * Whether the panel should show its "some sources failed" banner.
+ *
+ * @param {object} state - state.
+ * @returns {boolean} banner visibility.
+ */
+export function shouldShowDegradedBanner(state) {
+  if (state.overview === undefined) return false
+  return state.overview.degraded === true || (state.overview.errors ?? []).length > 0
+}

package/src/core/ai/prompts.js

@@ -0,0 +1,213 @@
+/**
+ * Prompt construction — four pure functions (docs/06 §2).
+ *
+ * The rules the model is given are deliberately strict because the panel must
+ * never present an unsourced number: only '<data>' values may be cited, every
+ * conclusion carries '[id@date, value]', and insufficient data is a valid answer.
+ *
+ * @module core/ai/prompts
+ */
+
+/** Default output budget for every prompt. */
+export const MAX_CHARS = 1200
+
+/** Default section budget. */
+export const MAX_SECTIONS = 6
+
+/** The shared system prompt (docs/06 §2.1). */
+export const SYSTEM_PROMPT = `你是宏观数据分析助手。你的唯一数据来源是下面 <data> 块中提供的观测值。
+
+硬性规则：
+1. 只能引用 <data> 中出现过的指标 ID、日期与数值。禁止引入 <data> 之外的数据、事件或新闻。
+2. 每个结论句后面用 [指标ID@日期, 值] 的形式标注依据。
+3. 如果 <data> 不足以回答问题，直接说明"数据不足"并列出缺少什么，不要推测。
+4. 区分事实与解释：先用一句话陈述数据事实，再给出可能解释，并明确标注为"可能"。
+5. 不做点位预测，不给买卖建议，不使用"必然/一定/肯定"等绝对措辞。
+6. 单位与口径必须与 <data> 一致（% 就是 %，不要写成小数）。
+7. 输出中文，Markdown，最多 {maxSections} 个要点，总长不超过 {maxChars} 字。`
+
+/**
+ * Render the system prompt with its budgets filled in.
+ *
+ * @param {{ maxChars?: number, maxSections?: number }} [options] - budgets.
+ * @returns {string} system prompt.
+ */
+export function systemPrompt({ maxChars = MAX_CHARS, maxSections = MAX_SECTIONS } = {}) {
+  return SYSTEM_PROMPT.replace('{maxSections}', String(maxSections)).replace('{maxChars}', String(maxChars))
+}
+
+/**
+ * Wrap the digest in its '<data>' block. An empty digest says so explicitly, so
+ * the model cannot read an empty block as "no constraints".
+ *
+ * @param {string} digest - digest text.
+ * @returns {string} data block.
+ */
+export function dataBlock(digest) {
+  const body = typeof digest === 'string' && digest.trim() !== '' ? digest.trim() : '（无数据：本次没有任何可用的指标观测）'
+  return `<data>\n${body}\n</data>`
+}
+
+/**
+ * The scenario prompts, as pure functions of structured input.
+ *
+ * @param {object} input - scenario input.
+ * @param {string} [input.digest] - '<data>' content.
+ * @param {string} [input.indicatorId] - indicator for 'explain'.
+ * @param {string} [input.label] - indicator label for 'explain'.
+ * @param {{ from: string, to: string }} [input.range] - range.
+ * @param {string} [input.question] - user question for 'answer'.
+ * @param {string} [input.scope] - scope label for 'overview'.
+ * @param {string} [input.request] - natural-language request for 'propose'.
+ * @param {string[]} [input.violations] - validator feedback for a retry.
+ * @param {string[]} [input.supportedAdapters] - adapters 'propose' may use.
+ * @returns {{ system: string, user: string }} messages.
+ */
+export function buildExplainPrompt({ digest, indicatorId, label, range, violations }) {
+  const lines = []
+  lines.push(dataBlock(digest))
+  lines.push('')
+  lines.push(`任务：解析指标 ${indicatorId ?? '(未指定)'}${label === undefined ? '' : `（${label}）`}`)
+  if (range !== undefined) lines.push(`时间范围：${range.from} .. ${range.to}`)
+  lines.push('输出 5 段：① 这个指标是什么（口径、单位、频率）② 本期读数意味着什么 ③ 与历史对比（分位/极值/趋势）④ 可能影响的资产或政策（标注"可能"）⑤ 反向风险。')
+  lines.push(...retryLines(violations))
+  return { system: systemPrompt(), user: lines.join('\n') }
+}
+
+/**
+ * @param {object} input - scenario input.
+ * @returns {{ system: string, user: string }} messages.
+ */
+export function buildSummaryPrompt({ digest, range, violations }) {
+  const lines = []
+  lines.push(dataBlock(digest))
+  lines.push('')
+  lines.push('任务：给出一段「时段总结」。')
+  if (range !== undefined) lines.push(`时间范围：${range.from} .. ${range.to}`)
+  lines.push('输出 4 段，每段 1–3 条：① 关键变化 ② 相互印证 ③ 背离与矛盾 ④ 下一个该盯的数据。')
+  lines.push(...retryLines(violations))
+  return { system: systemPrompt(), user: lines.join('\n') }
+}
+
+/**
+ * The whole-panel analysis prompt: "what is going on", not "what does this mean".
+ *
+ * It names the scope and the counts so the model can say "本组 12 个指标中 3 个
+ * 触发规则" instead of guessing at coverage, and it asks for cross-indicator
+ * structure — corroboration, divergence, and what to watch — because a summary
+ * that only restates each series adds nothing to the panel the reader already sees.
+ *
+ * @param {object} input - scenario input.
+ * @param {string} input.digest - '<data>' content.
+ * @param {string} [input.scope] - human scope label ('美国', '全部指标', …).
+ * @param {{ from: string, to: string }} [input.range] - range.
+ * @param {number} [input.indicatorCount] - observables in scope.
+ * @param {number} [input.noteworthyCount] - attention rules triggered in scope.
+ * @param {string[]} [input.violations] - feedback from the previous attempt.
+ * @returns {{ system: string, user: string }} messages.
+ */
+export function buildOverviewPrompt({ digest, scope, range, indicatorCount, noteworthyCount, violations }) {
+  const lines = []
+  lines.push(dataBlock(digest))
+  lines.push('')
+  lines.push(`任务：给出「${scope ?? '整体'}」的总体分析。`)
+  if (range !== undefined) lines.push(`时间范围：${range.from} .. ${range.to}`)
+  if (Number.isFinite(indicatorCount)) lines.push(`本范围指标数：${indicatorCount}`)
+  if (Number.isFinite(noteworthyCount)) lines.push(`其中触发关注规则：${noteworthyCount}`)
+  lines.push('输出 5 段，每段 1–3 条，全部基于 <data>：')
+  lines.push('① 总体态势：这段区间内哪些指标在动、方向是否一致，先用事实句概括。')
+  lines.push('② 关键变化：列出变化幅度最大或触发规则的指标，每条带 [指标ID@日期, 值]。')
+  lines.push('③ 相互印证：哪些指标互相支持同一结论。')
+  lines.push('④ 背离与矛盾：哪些指标方向相反或口径不一致，需要同时看。')
+  lines.push('⑤ 下一个该盯的数据：指出本范围里最重要的待更新项及其滞后天数。')
+  lines.push('不要逐个复述指标定义；读者已经能看到面板上的单项数据。')
+  lines.push(...retryLines(violations))
+  return { system: systemPrompt(), user: lines.join('\n') }
+}
+
+/**
+ * @param {object} input - scenario input.
+ * @returns {{ system: string, user: string }} messages.
+ */
+export function buildAnswerPrompt({ digest, question, range, violations }) {
+  const lines = []
+  lines.push(dataBlock(digest))
+  lines.push('')
+  lines.push(`用户问题：${typeof question === 'string' && question.trim() !== '' ? question.trim() : '（未提供问题）'}`)
+  if (range !== undefined) lines.push(`可用时间范围：${range.from} .. ${range.to}`)
+  lines.push('输出结构：结论文（≤3 句）→ 依据列表（每条带 [指标ID@日期, 值]）→ 数据边界说明（哪些问题数据无法回答）。')
+  lines.push('只回答被问到的内容；问题超出 <data> 覆盖范围时，直接回答"数据不足"并说明缺什么。')
+  lines.push(...retryLines(violations))
+  return { system: systemPrompt(), user: lines.join('\n') }
+}
+
+/**
+ * 'propose' is a structured task: JSON out, no free text (docs/06 §4).
+ *
+ * @param {object} input - scenario input.
+ * @returns {{ system: string, user: string }} messages.
+ */
+export function buildProposePrompt({ request, supportedAdapters = [], knownIds = [], violations }) {
+  const lines = []
+  lines.push('任务：把用户的自然语言需求解析成指标定义候选，只输出 JSON。')
+  lines.push(`用户需求：${typeof request === 'string' && request.trim() !== '' ? request.trim() : '（空）'}`)
+  lines.push('')
+  lines.push('只能使用下列已注册数据源适配器，且 seriesRef 必须是你确知存在的标识：')
+  for (const adapter of supportedAdapters) lines.push(`- ${adapter}`)
+  lines.push('')
+  if (knownIds.length > 0) lines.push(`已存在（会判为冲突）：${knownIds.slice(0, 40).join(', ')}`)
+  lines.push('')
+  lines.push('输出 JSON：{ "candidates": [ { "id", "label": {"zh","en"}, "unit", "freq", "group", "importance", "source": {"adapter","seriesRef","params"}, "display": {"transform","decimals","polarity"}, "confidence", "rationale" } ], "unsupported": [ { "request", "reason", "alternatives": [] } ] }')
+  lines.push('规则：不确定的 seriesRef 一律放进 unsupported 并说明原因，绝对不要猜一个看起来合理的 ID。')
+  lines.push(...retryLines(violations))
+  return { system: systemPrompt({ maxSections: 1, maxChars: 4000 }), user: lines.join('\n') }
+}
+
+/**
+ * Feedback appended when the validator rejected a previous answer.
+ *
+ * @param {string[]|undefined} violations - violations from 'app/ai-validate.js'.
+ * @returns {string[]} lines (empty when there were none).
+ */
+function retryLines(violations) {
+  if (!Array.isArray(violations) || violations.length === 0) return []
+  return [
+    '',
+    '上一次输出未通过溯源校验，请重写。问题清单：',
+    ...violations.slice(0, 10).map((entry) => `- ${entry}`),
+    '要求：只保留能在 <data> 中找到依据的结论，无法溯源的数字与断言一律删除。',
+  ]
+}
+
+/**
+ * The question a discussion asks when the reader clicks the button without
+ * typing one.
+ *
+ * A discussion opened with *only* context never runs a turn: the message waits in
+ * the session inbox for a turn that nothing starts, the session opens empty, and
+ * the panel — polling for an answer that cannot exist — reports "会话已结束但没有
+ * 文本回答（可能是模型未配置或请求失败）". The reader clicked a button labelled
+ * 「讨论」, so the honest behaviour is to ask something; the panel shows which
+ * question it asked, and the reader can continue in the session from there.
+ *
+ * @param {{ subject?: 'indicator'|'group'|'noteworthy', label?: string }} [options] - subject.
+ * @returns {string} the opening question.
+ */
+export function buildDefaultQuestion({ subject = 'indicator', label } = {}) {
+  const name = typeof label === 'string' && label.trim() !== '' ? label.trim() : '这些数据'
+  if (subject === 'group') {
+    return `请基于上下文中的面板数据回答：${name}目前整体处于什么状态？最值得关注的变化有哪些？它们之间如何相互印证或背离？接下来该盯哪些数据？`
+  }
+  if (subject === 'noteworthy') {
+    return `这条「值得关注」为什么会被触发？请基于上下文中的面板数据说明 ${name} 当前的含义，以及接下来该盯什么。`
+  }
+  return `请基于上下文中的面板数据回答：${name}当前处于什么位置？最近的变化说明了什么？接下来该盯哪些相关数据？`
+}
+
+/** The four scenario builders, keyed by operation. */
+export const PROMPT_BUILDERS = {
+  explain: buildExplainPrompt,
+  summarize: buildSummaryPrompt,
+  answer: buildAnswerPrompt,
+  propose: buildProposePrompt,
+}

package/src/core/chart/axis.js

@@ -0,0 +1,133 @@
+/**
+ * Axis label geometry (docs/05 §4.1).
+ *
+ * @module core/chart/axis
+ */
+import { box } from './line.js'
+import { linearScale, niceTicks } from './scale.js'
+
+/**
+ * Build y-axis tick labels.
+ *
+ * @param {{ min: number, max: number }} yDomain - y domain.
+ * @param {{ width: number, height: number, padding?: number, paddingX?: number, paddingY?: number, ticks?: number, decimals?: number, suffix?: string }} geometry - chart geometry.
+ * @returns {Array<{ y: number, value: number, label: string }>} tick entries.
+ */
+export function buildYAxis(yDomain, geometry) {
+  const { innerH, padY } = box({ width: geometry.width ?? 1, height: geometry.height, padding: geometry.padding, paddingX: geometry.paddingX, paddingY: geometry.paddingY })
+  const decimals = geometry.decimals ?? 2
+  const suffix = geometry.suffix ?? ''
+  // No explicit count → derive "nice" 1/2/5×10ⁿ ticks from the domain; an
+  // explicit count → evenly spaced ticks inside the given domain.
+  const values = geometry.ticks === undefined
+    ? niceTicks(yDomain.min, yDomain.max, 5).ticks.filter((t) => t >= yDomain.min && t <= yDomain.max)
+    : buildEvenTicks(yDomain, geometry.ticks)
+  const y = linearScale({ domain: [yDomain.min, yDomain.max], range: [padY + innerH, padY] })
+  return values.map((value) => ({
+    y: Number(y(value).toFixed(2)),
+    value,
+    label: `${Number(value.toFixed(decimals))}${suffix}`,
+  }))
+}
+
+/**
+ * Evenly spaced ticks across a domain (used when the caller fixes the count).
+ *
+ * @param {{ min: number, max: number }} domain - domain.
+ * @param {number} count - tick count.
+ * @returns {number[]} tick values.
+ */
+function buildEvenTicks(domain, count) {
+  if (count <= 1) return [domain.min]
+  const step = (domain.max - domain.min) / (count - 1)
+  return Array.from({ length: count }, (_, i) => Number((domain.min + step * i).toFixed(12)))
+}
+
+/**
+ * Build x-axis tick labels from date strings.
+ *
+ * @param {string[]} dates - ascending 'YYYY-MM-DD' values.
+ * @param {{ width: number, padding?: number, paddingX?: number, count?: number }} geometry - chart geometry.
+ * @returns {Array<{ x: number, label: string, t: string }>} tick entries.
+ */
+export function buildXAxis(dates, geometry) {
+  if (!Array.isArray(dates) || dates.length === 0) return []
+  const { innerW, padX } = box({ width: geometry.width, height: 1, padding: geometry.padding, paddingX: geometry.paddingX })
+  const wanted = Math.min(geometry.count ?? 4, dates.length)
+  const step = dates.length <= wanted ? 1 : (dates.length - 1) / (wanted - 1)
+  const picked = []
+  for (let i = 0; i < wanted; i += 1) picked.push(Math.round(i * step))
+  const unique = [...new Set(picked)].filter((i) => i >= 0 && i < dates.length)
+  const span = Math.max(1, dates.length - 1)
+  return unique.map((index) => ({
+    x: Number((padX + (index / span) * innerW).toFixed(2)),
+    label: formatAxisDate(dates[index]),
+    t: dates[index],
+  }))
+}
+
+/**
+ * Short axis date: 'MM-DD' inside one year, 'YYYY-MM' across years.
+ *
+ * @param {string} date - 'YYYY-MM-DD'.
+ * @returns {string} axis label.
+ */
+export function formatAxisDate(date) {
+  return `${date.slice(5, 7)}-${date.slice(8, 10)}`
+}
+
+/**
+ * Axis date label that stays unambiguous across a multi-year window.
+ *
+ * A daily chart spanning years labelled only 'MM-DD' reads as repeating dates,
+ * so the month is enough inside one year and the year is shown once the window
+ * crosses a boundary (docs/05 §4.2).
+ *
+ * @param {string} date - 'YYYY-MM-DD'.
+ * @param {{ crossesYears?: boolean }} [options] - options.
+ * @returns {string} axis label.
+ */
+export function formatSpanDate(date, options = {}) {
+  return options.crossesYears === true ? `${date.slice(0, 4)}-${date.slice(5, 7)}` : formatAxisDate(date)
+}
+
+/**
+ * X ticks for a time series drawn with the shared plot box.
+ *
+ * Placed by index rather than by value, because the chart is index-spaced (a
+ * weekend must not open a gap), and it always keeps the first and last point so
+ * the axis states the window it covers.
+ *
+ * @param {string[]} dates - ascending 'YYYY-MM-DD' values.
+ * @param {{ width: number, height?: number, paddingX?: number, paddingY?: number, padding?: number, count?: number }} geometry - chart geometry.
+ * @returns {Array<{ x: number, label: string, t: string, anchor: 'start'|'middle'|'end' }>} ticks.
+ */
+export function buildTimeAxis(dates, geometry) {
+  if (!Array.isArray(dates) || dates.length === 0) return []
+  const { padX, innerW } = box({
+    width: geometry.width,
+    height: geometry.height ?? 1,
+    padding: geometry.padding,
+    paddingX: geometry.paddingX,
+    paddingY: geometry.paddingY,
+    padLeft: geometry.padLeft,
+    padRight: geometry.padRight,
+    padX: geometry.padX,
+    innerW: geometry.innerW,
+  })
+  const wanted = Math.min(Math.max(2, geometry.count ?? 5), dates.length)
+  const crossesYears = dates[0].slice(0, 4) !== dates[dates.length - 1].slice(0, 4)
+  const span = dates.length - 1
+  const picked = new Set([0, span])
+  for (let i = 1; i < wanted - 1; i += 1) picked.add(Math.round((i / (wanted - 1)) * span))
+  return [...picked]
+    .sort((a, b) => a - b)
+    .map((index) => ({
+      index,
+      x: Number((padX + (span === 0 ? innerW / 2 : (index / span) * innerW)).toFixed(2)),
+      t: dates[index],
+      label: formatSpanDate(dates[index], { crossesYears }),
+      // Edge labels are anchored inward so they never run off the plot.
+      anchor: index === 0 ? 'start' : index === span ? 'end' : 'middle',
+    }))
+}

package/src/core/chart/bar.js

@@ -0,0 +1,58 @@
+/**
+ * Bar-chart rectangles and axis geometry (docs/05 §4.1).
+ *
+ * @module core/chart/bar
+ */
+import { box } from './line.js'
+import { extent, linearScale } from './scale.js'
+
+/**
+ * Build bar rectangles for a column chart. Bars are anchored to the zero line
+ * when the domain crosses zero, so positive and negative values read correctly.
+ *
+ * @param {Array<{ t: string, v: number }>} points - ascending points.
+ * @param {{ width: number, height: number, padding?: number, paddingX?: number, paddingY?: number, yDomain?: { min: number, max: number }, gap?: number }} geometry - chart geometry.
+ * @returns {Array<{ x: number, y: number, w: number, h: number, t: string, v: number }>} rectangles.
+ */
+export function buildBarRects(points, geometry) {
+  if (!Array.isArray(points) || points.length === 0) return []
+  const { innerW, innerH, padX, padY } = box(geometry)
+  const finite = points.filter((p) => Number.isFinite(p?.v))
+  if (finite.length === 0) return []
+
+  const dataExtent = extent(finite.map((p) => p.v))
+  const yDomain = geometry.yDomain ?? { min: Math.min(0, dataExtent.min), max: Math.max(0, dataExtent.max) }
+  const y = linearScale({ domain: [yDomain.min, yDomain.max], range: [padY + innerH, padY] })
+  const gap = geometry.gap ?? 1
+  const slot = innerW / finite.length
+  const width = Math.max(1, slot - gap)
+  const zeroY = y(0)
+
+  return finite.map((point, index) => {
+    const valueY = y(point.v)
+    const top = Math.min(zeroY, valueY)
+    const height = Math.max(1, Math.abs(valueY - zeroY))
+    return {
+      x: Number((padX + index * slot + gap / 2).toFixed(2)),
+      y: Number(top.toFixed(2)),
+      w: Number(width.toFixed(2)),
+      h: Number(height.toFixed(2)),
+      t: point.t,
+      v: point.v,
+    }
+  })
+}
+
+/**
+ * The y coordinate of the zero line, or 'null' when zero is outside the domain.
+ *
+ * @param {{ min: number, max: number }} yDomain - y domain.
+ * @param {{ height: number, padding?: number, paddingY?: number }} geometry - chart geometry.
+ * @returns {number|null} zero-line y coordinate.
+ */
+export function buildZeroLine(yDomain, geometry) {
+  const { innerH, padY } = box({ width: 1, height: geometry.height, padding: geometry.padding, paddingY: geometry.paddingY })
+  if (!(yDomain.min <= 0 && yDomain.max >= 0)) return null
+  const y = linearScale({ domain: [yDomain.min, yDomain.max], range: [padY + innerH, padY] })
+  return Number(y(0).toFixed(2))
+}