@digithings-ai/ui 0.0.0-stage → 0.1.0

package/src/components/finance-tearsheet/demo-data.ts

@@ -0,0 +1,177 @@
+/**
+ * DEMO DATA ONLY (#1463) — one deterministic backtest for the
+ * finance-tearsheet reference specimens: a three-year daily OHLC walk, a
+ * long/short trade log marked on it (last leg open), and the
+ * mark-to-market equity / underwater curves those trades imply. Same LCG
+ * doctrine as the finance-charts demos: stable across renders and runtimes,
+ * and the components take data via required props precisely so demo numbers
+ * can never ship by omission.
+ */
+import type {
+  TearsheetOhlcBar,
+  TearsheetSeriesPoint,
+  TearsheetTrade,
+  TradeReturnBar,
+} from "./types";
+
+/** Deterministic LCG in [0, 1) — stable across renders and runtimes. */
+function lcg(seed: number): () => number {
+  let s = seed;
+  return () => {
+    s = (s * 1103515245 + 12345) & 0x7fffffff;
+    return s / 0x7fffffff;
+  };
+}
+
+function isoOffset(startUtc: Date, days: number): string {
+  const date = new Date(startUtc);
+  date.setUTCDate(startUtc.getUTCDate() + days);
+  return date.toISOString().slice(0, 10);
+}
+
+const N_BARS = 780;
+const START = new Date(Date.UTC(2023, 0, 2));
+
+function ohlcDemo(): TearsheetOhlcBar[] {
+  const rnd = lcg(1463);
+  const bars: TearsheetOhlcBar[] = [];
+  let price = 68;
+  for (let i = 0; i < N_BARS; i++) {
+    // Regime-y drift: slow sine bias + noise, so trends exist for trades to ride.
+    const bias = Math.sin(i / 90) * 0.008 + 0.0008;
+    const o = price;
+    const c = Math.max(9, o * (1 + bias + (rnd() - 0.5) * 0.045));
+    const h = Math.max(o, c) * (1 + rnd() * 0.014);
+    const l = Math.min(o, c) * (1 - rnd() * 0.014);
+    bars.push({ t: isoOffset(START, i), o, h, l, c });
+    price = c;
+  }
+  return bars;
+}
+
+interface DemoBuild {
+  bars: TearsheetOhlcBar[];
+  trades: TearsheetTrade[];
+  equity: TearsheetSeriesPoint[];
+  drawdown: TearsheetSeriesPoint[];
+  tradeReturnBars: TradeReturnBar[];
+}
+
+function build(): DemoBuild {
+  const bars = ohlcDemo();
+  const rnd = lcg(97031);
+  const trades: TearsheetTrade[] = [];
+
+  // Round trips over the bar walk: hold 12–60 bars, sit out 3–18, flip
+  // direction with the local regime. The final leg stays open (marked to the
+  // last close) so the open-trade grammar shows everywhere it exists.
+  let i = 5;
+  let n = 1;
+  let equityMark = 100_000;
+  while (i < N_BARS - 70) {
+    const hold = 12 + Math.floor(rnd() * 48);
+    const exitIdx = Math.min(N_BARS - 2, i + hold);
+    const direction: "long" | "short" = Math.sin(i / 90) + (rnd() - 0.5) * 0.6 > 0 ? "long" : "short";
+    const entry = bars[i].c;
+    const exit = bars[exitIdx].c;
+    const pnlPct = direction === "long" ? (exit / entry - 1) * 100 : (entry / exit - 1) * 100;
+    const qty = Math.round((equityMark / entry) * 100) / 100;
+    const pnl = equityMark * (pnlPct / 100);
+    equityMark += pnl;
+    trades.push({
+      n,
+      direction,
+      entry_label: direction === "long" ? "breakout" : "fade",
+      entry_date: bars[i].t,
+      entry_price: entry,
+      exit_date: bars[exitIdx].t,
+      exit_price: exit,
+      qty,
+      pnl,
+      pnl_pct: pnlPct,
+      equity_after: equityMark,
+      exit_reason: rnd() > 0.5 ? "signal" : "stop",
+      max_runup_pct: Math.abs(pnlPct) * (1 + rnd() * 0.4),
+      max_drawdown_pct: -Math.abs(pnlPct) * rnd() * 0.6,
+    });
+    n += 1;
+    i = exitIdx + 3 + Math.floor(rnd() * 15);
+  }
+
+  // Open leg: enters near the end, marks to the last close.
+  const lastBar = bars[N_BARS - 1];
+  const openIdx = N_BARS - 40;
+  const openEntry = bars[openIdx].c;
+  const openPct = (lastBar.c / openEntry - 1) * 100;
+  trades.push({
+    n,
+    direction: "long",
+    entry_label: "breakout",
+    entry_date: bars[openIdx].t,
+    entry_price: openEntry,
+    exit_date: "",
+    exit_price: lastBar.c,
+    qty: Math.round((equityMark / openEntry) * 100) / 100,
+    pnl: equityMark * (openPct / 100),
+    pnl_pct: openPct,
+    equity_after: equityMark,
+    exit_reason: "open",
+    max_runup_pct: Math.max(0, openPct) * 1.2,
+    max_drawdown_pct: Math.min(0, openPct) * 0.8,
+  });
+
+  // Mark-to-market equity: ride each trade's direction bar to bar, flat
+  // between trades — the curve the KPIs, matrix, and drawdown derive from.
+  const equity: TearsheetSeriesPoint[] = [];
+  const drawdown: TearsheetSeriesPoint[] = [];
+  let eq = 100_000;
+  let peak = eq;
+  let t = 0;
+  for (let b = 0; b < N_BARS; b++) {
+    const bar = bars[b];
+    let active: TearsheetTrade | undefined;
+    while (t < trades.length && bar.t >= trades[t].entry_date) {
+      const exitT = trades[t].exit_date || lastBar.t;
+      if (bar.t <= exitT) {
+        active = trades[t];
+        break;
+      }
+      t += 1;
+    }
+    if (b > 0 && active) {
+      const barRet = bars[b].c / bars[b - 1].c - 1;
+      eq *= 1 + (active.direction === "long" ? barRet : -barRet);
+    }
+    peak = Math.max(peak, eq);
+    equity.push({ t: bar.t, v: eq });
+    drawdown.push({ t: bar.t, v: Math.round((eq / peak - 1) * 1000) / 10 });
+  }
+
+  const closed = trades.filter((tr) => tr.exit_reason !== "open");
+  const open = trades[trades.length - 1];
+  const tradeReturnBars: TradeReturnBar[] = closed.map((tr) => ({
+    t: tr.exit_date,
+    pct: tr.pnl_pct,
+    open: false,
+    trade: tr,
+  }));
+  tradeReturnBars.push({ t: lastBar.t, pct: open.pnl_pct, open: true, trade: open });
+
+  return { bars, trades, equity, drawdown, tradeReturnBars };
+}
+
+const BUILT = build();
+
+/** The demo backtest the reference tearsheet specimens compose. */
+export const TEARSHEET_DEMO = {
+  symbol: "DGQ-USD",
+  periodStart: BUILT.bars[0].t,
+  periodEnd: BUILT.bars[BUILT.bars.length - 1].t,
+  /** Shared x-span for the synced charts. */
+  fullSpan: [BUILT.bars[0].t, BUILT.bars[BUILT.bars.length - 1].t] as [string, string],
+  bars: BUILT.bars,
+  trades: BUILT.trades,
+  equity: BUILT.equity,
+  drawdown: BUILT.drawdown,
+  tradeReturnBars: BUILT.tradeReturnBars,
+};

package/src/components/finance-tearsheet/format.ts

@@ -0,0 +1,41 @@
+/**
+ * Number formatting shared by the finance-tearsheet charts, tables, and card
+ * KPIs (#1463) — verbatim from
+ * apps/digiquant-web/components/tearsheet/format.ts so promoted surfaces
+ * render figure-for-figure identical.
+ */
+
+/** Compact axis/KPI formatting so huge compounded figures never overflow. */
+export function fmtCompact(v: number | null | undefined): string {
+  if (v === null || v === undefined || Number.isNaN(v)) return "";
+  const a = Math.abs(v);
+  if (a >= 1e9) return (v / 1e9).toFixed(a >= 1e10 ? 0 : 1) + "B";
+  if (a >= 1e6) return (v / 1e6).toFixed(a >= 1e7 ? 0 : 1) + "M";
+  if (a >= 1e3) return (v / 1e3).toFixed(a >= 1e4 ? 0 : 1) + "K";
+  if (a >= 1) return v.toFixed(0);
+  if (a === 0) return "0";
+  return v.toFixed(2);
+}
+
+export function fmtPct(v: number | null | undefined): string {
+  if (v === null || v === undefined) return "n/a";
+  if (Math.abs(v) >= 10000) return fmtCompact(v) + "%";
+  return v.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 }) + "%";
+}
+
+export function fmtMoney(v: number | null | undefined): string {
+  if (v === null || v === undefined) return "n/a";
+  if (Math.abs(v) >= 100000) return fmtCompact(v);
+  return v.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 });
+}
+
+export function fmtNum(v: number | null | undefined, d = 0): string {
+  if (v === null || v === undefined) return "n/a";
+  return v.toLocaleString("en-US", { minimumFractionDigits: d, maximumFractionDigits: d });
+}
+
+/** Money tone class for a signed value: `.is-pos` / `.is-neg` / none at 0. */
+export function toneClass(v: number | null | undefined): string {
+  if (v === null || v === undefined) return "";
+  return v > 0 ? "is-pos" : v < 0 ? "is-neg" : "";
+}

package/src/components/finance-tearsheet/index.ts

@@ -0,0 +1,120 @@
+/**
+ * finance-tearsheet family barrel (#1463) — the print-grade SVG tearsheet
+ * grammar reverse-promoted from apps/digiquant-web/components/tearsheet/.
+ * Everything here participates in the PDF export (flushSync + window.print
+ * over ONE render tree), so the charts are pure SVG — the canvas
+ * finance-charts / finance-composites families are the screen-only DASHBOARD
+ * grammar. The split ruling lives in packages/ui/CHARTS.md.
+ *
+ * Wiring (consuming app):
+ *   globals.css   @import "@digithings-ai/ui/styles/finance-tearsheet.css";
+ *                 (plainly — the sheet manages its own layering)
+ *                 @source "<path-to>/packages/ui/src/components/finance-tearsheet";
+ * Data derivation (series clipping, pivot stats, trade sorting, CAGR et al.)
+ * stays app-owned — components take render-ready props.
+ */
+
+export {
+  CandlestickChart,
+  TimeSeries,
+  MultiTimeSeries,
+  RiskBandStrip,
+  AllocationStepChart,
+  SignedBars,
+  ContributionReturnChart,
+  TradeReturnChart,
+  SegToggle,
+  ChartLegend,
+  ChartResetButton,
+  LOOKBACK_OPTIONS,
+  MIN_VIEW,
+  clampView,
+  viewWindowForPreset,
+  viewWindowLastYear,
+  matchLookbackPreset,
+  viewsNear,
+  sliceByView,
+  type CandlestickChartProps,
+  type TimeSeriesProps,
+  type MultiTimeSeriesProps,
+  type OverlaySeries,
+  type RiskBandStripProps,
+  type AllocationStepChartProps,
+  type AllocationFillMarker,
+  type SignedBarsProps,
+  type ContributionReturnChartProps,
+  type ContributionReturnPoint,
+  type TradeReturnChartProps,
+  type ChartScale,
+  type ChartTone,
+  type OverlayTone,
+  type ReferenceTone,
+  type ReferenceLineSpec,
+  type ReferenceBandSpec,
+  type ReferenceMarkerSpec,
+  type ChartReferences,
+  type ChartLegendKind,
+  type ViewWindow,
+  type LookbackPreset,
+} from "./charts";
+export { RISK_BANDS, riskBandLabel, dcaRateCopy, type RiskBand } from "./risk-bands";
+export { ReturnsMatrix, type ReturnsPeriod, type MatrixMetric } from "./ReturnsMatrix";
+export { KpiStrip, Kpi, type KpiStripProps, type KpiProps } from "./KpiStrip";
+export {
+  TradeLogTable,
+  DirectionPill,
+  type TradeLogTableProps,
+  type TradeLogColumn,
+  type TradeLogRow,
+} from "./TradeLogTable";
+export {
+  TearsheetCard,
+  TearsheetCardKpis,
+  TearsheetCardKpi,
+  type TearsheetCardProps,
+} from "./TearsheetCard";
+export { LiveBadge, type LiveBadgeProps } from "./LiveBadge";
+export { PRINT_FULL_VIEW, runTearsheetPrint } from "./print";
+export {
+  isOpenTrade,
+  type TearsheetSeriesPoint,
+  type TearsheetOhlcBar,
+  type TearsheetTrade,
+  type TradeReturnBar,
+} from "./types";
+export { fmtCompact, fmtPct, fmtMoney, fmtNum, toneClass } from "./format";
+export { dailyReturnsFromEquity, annualizedVolPct } from "./stats";
+export {
+  computeLivePerformanceKpis,
+  computeLiveVsMarkPct,
+  dayReturnAnchorNav,
+  derivePriceAsOfDate,
+  inceptionSignAgreesWithBase100,
+  informationRatioFromDaily,
+  olsBeta,
+  overlappingDailyReturns,
+  navHistoryForLiveOverlap,
+  relativeMetricsFromReturnSeries,
+  sinceInceptionPctFromNav,
+  MIN_OVERLAP_DAYS,
+  type LiveKpiPosition,
+  type LiveKpiNavPoint,
+  type LiveKpiBenchmarkPoint,
+  type LivePerformanceKpis,
+  type LivePerformanceKpisInput,
+  // Moved to @digithings-ai/perf-math so framework-free consumers (contract, the R5
+  // Worker bundle) never pull React. Re-exported here so existing imports from
+  // `@digithings-ai/ui` keep working.
+} from "@digithings-ai/perf-math/live-performance-kpis";
+export { TEARSHEET_DEMO } from "./demo-data";
+export { StrategyTearsheet } from "./StrategyTearsheet";
+export {
+  buildStrategyTearsheet,
+  seriesOrNull,
+  seriesSparkline,
+  sheetCagr,
+  type StrategySheetBar,
+  type StrategySheetMetric,
+  type StrategySheetModel,
+  type StrategySheetPoint,
+} from "./strategy-sheet-model";

package/src/components/finance-tearsheet/print.ts

@@ -0,0 +1,52 @@
+"use client";
+/**
+ * The tearsheet PDF pipeline (#1463) — promoted from
+ * apps/digiquant-web/components/tearsheet/print-tearsheet.ts. "Download
+ * PDF" is a shipped feature of this family and the reason it is pure SVG:
+ * the same chart component instances re-render synchronously at full span
+ * (PRINT_FULL_VIEW, linear scale) before the system print dialog opens, so
+ * screen and print share ONE render tree. Canvas engines are disqualified
+ * on any surface that participates in this export.
+ */
+import { flushSync } from "react-dom";
+import type { ViewWindow } from "./charts";
+
+/** Full backtest window — used when rendering charts for PDF export. */
+export const PRINT_FULL_VIEW: ViewWindow = { lo: 0, hi: 1 };
+
+/**
+ * Prepare the DOM + React state, invoke the system print dialog, then restore.
+ * Uses flushSync so charts re-render at full span before the print layout
+ * runs. Pins the light theme for paper output (the print grammar in
+ * styles/finance-tearsheet.css pins the light tokens as literals) and tags
+ * `html.ts-printing` for print-only rules.
+ */
+export function runTearsheetPrint(opts: {
+  /** document.title while the dialog is open (names the exported PDF). */
+  documentTitle: string;
+  /** The consumer's `printing` state setter — charts read it to swap to
+   *  PRINT_FULL_VIEW / linear scale. */
+  setPrinting: (printing: boolean) => void;
+}): void {
+  const html = document.documentElement;
+  const prevTheme = html.getAttribute("data-theme");
+  const prevTitle = document.title;
+
+  html.setAttribute("data-theme", "light");
+  html.classList.add("ts-printing");
+  document.title = opts.documentTitle;
+
+  flushSync(() => opts.setPrinting(true));
+  try {
+    window.print();
+  } finally {
+    html.classList.remove("ts-printing");
+    if (prevTheme === null) {
+      html.removeAttribute("data-theme");
+    } else {
+      html.setAttribute("data-theme", prevTheme);
+    }
+    document.title = prevTitle;
+    flushSync(() => opts.setPrinting(false));
+  }
+}

package/src/components/finance-tearsheet/risk-bands.ts

@@ -0,0 +1,48 @@
+/**
+ * Composite-risk bands for DCA / SDCA tearsheets (#3172).
+ *
+ * The artifact's scale is 0–100 (cheap → rich). Labels match the published
+ * SDCA bands: Fire sale / Accumulate / Value / Above mid / Hot / Bubble.
+ * 95–100 is Bubble (the spec's 95–99 band plus the closed top of the scale).
+ */
+
+export interface RiskBand {
+  /** Inclusive lower bound. */
+  lo: number;
+  /** Exclusive upper bound, except the last band which includes 100. */
+  hi: number;
+  id: "fire" | "acc" | "value" | "mid" | "hot" | "bubble";
+  label: string;
+}
+
+export const RISK_BANDS: readonly RiskBand[] = [
+  { lo: 0, hi: 10, id: "fire", label: "Fire sale" },
+  { lo: 10, hi: 25, id: "acc", label: "Accumulate" },
+  { lo: 25, hi: 50, id: "value", label: "Value" },
+  { lo: 50, hi: 75, id: "mid", label: "Above mid" },
+  { lo: 75, hi: 95, id: "hot", label: "Hot" },
+  { lo: 95, hi: 100, id: "bubble", label: "Bubble" },
+] as const;
+
+/** Band copy for a composite risk in [0, 100]. Null/NaN → null. */
+export function riskBandLabel(risk: number | null | undefined): string | null {
+  if (risk === null || risk === undefined || Number.isNaN(risk)) return null;
+  for (const band of RISK_BANDS) {
+    if (risk < band.hi) return band.label;
+  }
+  return "Bubble";
+}
+
+/** Today's-rate sentence for a DCA current signal. */
+export function dcaRateCopy(dailyRatePct: number | null | undefined): string | null {
+  if (dailyRatePct === null || dailyRatePct === undefined || Number.isNaN(dailyRatePct)) {
+    return null;
+  }
+  const abs = Math.abs(dailyRatePct).toLocaleString("en-US", {
+    minimumFractionDigits: 1,
+    maximumFractionDigits: 1,
+  });
+  if (dailyRatePct > 0) return `buying ${abs}% of remaining cash today`;
+  if (dailyRatePct < 0) return `selling ${abs}% of remaining holdings today`;
+  return "holding, no trade today";
+}

package/src/components/finance-tearsheet/stats.ts

@@ -0,0 +1,35 @@
+/**
+ * The two derived statistics the ReturnsMatrix volatility metric needs
+ * (#1463), verbatim from apps/digiquant-web/components/tearsheet/stats.ts.
+ * The full derived-stats library (CAGR, Sharpe/Sortino/Omega, annual rows …)
+ * is app-owned data wiring and stays with the consumers.
+ */
+
+/** Daily simple returns from a mark-to-market equity curve. */
+export function dailyReturnsFromEquity(points: { v: number }[]): number[] {
+  const rets: number[] = [];
+  for (let i = 1; i < points.length; i++) {
+    const prev = points[i - 1].v;
+    if (prev > 0) rets.push(points[i].v / prev - 1);
+  }
+  return rets;
+}
+
+function mean(xs: number[]): number {
+  return xs.length ? xs.reduce((a, b) => a + b, 0) / xs.length : 0;
+}
+
+function sampleStd(xs: number[]): number {
+  if (xs.length < 2) return 0;
+  const m = mean(xs);
+  const v = xs.reduce((a, x) => a + (x - m) ** 2, 0) / (xs.length - 1);
+  return Math.sqrt(v);
+}
+
+const TRADING_DAYS = 252;
+
+/** Annualized volatility (%) from daily returns. */
+export function annualizedVolPct(returns: number[]): number | null {
+  if (returns.length < 2) return null;
+  return sampleStd(returns) * Math.sqrt(TRADING_DAYS) * 100;
+}