portal-mojo 0.1.0

package/src/charts/index.ts

@@ -0,0 +1,28 @@
+// portal-mojo/charts — dependency-free SVG charts in the mission-control
+// design language. SeriesChart (line/bar/area, stacked bars, legend toggle,
+// crosshair tooltip) + MetricsChart (the /api/metrics/fetch control-bar
+// wrapper: granularity/range/type switching, custom-range dialog, stats +
+// view-data dialogs); MiniChart sparklines, the searchable MetricsMiniWidget
+// card, KPITile/KPIStrip, CircularProgress, PieChart, the chart stats math,
+// and the exportChartPng SVG→PNG serializer.
+export * from './SeriesChart';
+export * from './MetricsChart';
+export * from './MiniChart';
+export * from './MetricsMiniWidget';
+export * from './KPITile';
+export * from './KPIStrip';
+export * from './CircularProgress';
+export * from './PieChart';
+export * from './pie-math';
+export * from './chart-dialogs';
+export * from './exportChart';
+export * from './stats';
+export * from './worldmap/WorldMap';
+export * from './worldmap/countryCentroids';
+export * from './worldmap/geo';
+export * from './worldmap/worldmap-data';
+// Basemap geometry is reached through `useWorldLand()` ONLY. `world-land.ts` is
+// deliberately not re-exported here: a static re-export would pull ~143KB of
+// coordinates into every bundle that touches this barrel, which is exactly what
+// the lazy hook exists to avoid.
+export * from './worldmap/use-world-land';

package/src/charts/pie-math.ts

@@ -0,0 +1,127 @@
+// Pure pie geometry + parsing — no DOM, no React (headless-testable).
+// Split out of the PieChart port (web-mojo src/extensions/charts/PieChart.js
+// _parseData/_buildSegmentGeometry/_interpolateSegments + the golden-angle
+// generator, verbatim).
+import { toNumber } from './stats';
+
+export const GOLDEN_ANGLE = 137.508;
+
+/** Distinct hues forever: i × golden angle around the wheel (source verbatim). */
+export function goldenAngleColor(i: number): string {
+    return `hsl(${((i * GOLDEN_ANGLE) % 360).toFixed(0)}, 65%, 52%)`;
+}
+
+export interface PieDatum {
+    label: string;
+    value: number;
+    color?: string;
+}
+
+/** Chart.js-style input (shape 2). Only the first dataset is read. */
+export interface PieDatasetsInput {
+    labels: string[];
+    datasets: { data: number[]; backgroundColor?: string[] }[];
+}
+
+/** The three accepted shapes: array / Chart.js / object map. */
+export type PieInput = PieDatum[] | PieDatasetsInput | Record<string, number>;
+
+export interface ParsedSlice {
+    label: string;
+    value: number;
+    color: string | null;
+}
+
+/**
+ * Normalize any accepted input shape to [{label, value, color|null}].
+ * Unknown shapes warn and yield [] (never crash, never render nothing
+ * silently — the empty state says so).
+ */
+export function parsePieInput(input: unknown): ParsedSlice[] {
+    if (input == null) return [];
+    if (Array.isArray(input)) {
+        const arr: readonly unknown[] = input;
+        return arr.map((d) => {
+            const item = d as Partial<PieDatum> | null;
+            return {
+                label: String(item?.label ?? ''),
+                value: toNumber(item?.value),
+                color: item?.color ?? null,
+            };
+        });
+    }
+    if (typeof input === 'object') {
+        const asDs = input as Partial<PieDatasetsInput>;
+        if (Array.isArray(asDs.labels) && Array.isArray(asDs.datasets)) {
+            const first = asDs.datasets[0];
+            const bg = Array.isArray(first?.backgroundColor) ? first.backgroundColor : null;
+            return asDs.labels.map((label, i) => ({
+                label: String(label),
+                value: toNumber(first?.data?.[i]),
+                color: bg?.[i] ?? null,
+            }));
+        }
+        const entries = Object.entries(input as Record<string, unknown>);
+        if (entries.every(([, v]) => typeof v !== 'object' || v == null)) {
+            return entries.map(([label, v]) => ({ label, value: toNumber(v), color: null }));
+        }
+    }
+    console.warn('PieChart: unrecognized data shape — rendering empty state', input);
+    return [];
+}
+
+export interface PieSegment {
+    label: string;
+    value: number;
+    /** 0–100 share of the total (0 when the total is 0). */
+    pct: number;
+    color: string;
+    startAngle: number;
+    endAngle: number;
+}
+
+/** Radians, 12 o'clock start, clockwise — the source's geometry, verbatim. */
+export function buildPieGeometry(slices: readonly { label: string; value: number; pct: number; color: string }[]): PieSegment[] {
+    let angle = -Math.PI / 2;
+    return slices.map((s) => {
+        const arc = (s.pct / 100) * Math.PI * 2;
+        const seg: PieSegment = { ...s, startAngle: angle, endAngle: angle + arc };
+        angle += arc;
+        return seg;
+    });
+}
+
+/** Label-keyed interpolation: existing slices slide, new ones grow from a 0-arc. */
+export function interpolateSegments(prev: readonly PieSegment[], target: readonly PieSegment[], k: number): PieSegment[] {
+    const lerp = (a: number, b: number) => a + (b - a) * k;
+    const prevByLabel = new Map(prev.map((p) => [p.label, p]));
+    return target.map((t) => {
+        const p = prevByLabel.get(t.label);
+        if (!p) return { ...t, endAngle: lerp(t.startAngle, t.endAngle) };
+        return { ...t, startAngle: lerp(p.startAngle, t.startAngle), endAngle: lerp(p.endAngle, t.endAngle) };
+    });
+}
+
+/** SVG path for one segment (doughnut when innerR > 0). */
+export function arcPath(cx: number, cy: number, outerR: number, innerR: number, seg: PieSegment): string {
+    const { startAngle, endAngle } = seg;
+    const largeArc = endAngle - startAngle > Math.PI ? 1 : 0;
+    const x1o = cx + outerR * Math.cos(startAngle);
+    const y1o = cy + outerR * Math.sin(startAngle);
+    const x2o = cx + outerR * Math.cos(endAngle);
+    const y2o = cy + outerR * Math.sin(endAngle);
+    if (innerR > 0) {
+        const x1i = cx + innerR * Math.cos(endAngle);
+        const y1i = cy + innerR * Math.sin(endAngle);
+        const x2i = cx + innerR * Math.cos(startAngle);
+        const y2i = cy + innerR * Math.sin(startAngle);
+        return [
+            `M ${x1o} ${y1o}`,
+            `A ${outerR} ${outerR} 0 ${largeArc} 1 ${x2o} ${y2o}`,
+            `L ${x1i} ${y1i}`,
+            `A ${innerR} ${innerR} 0 ${largeArc} 0 ${x2i} ${y2i}`,
+            'Z',
+        ].join(' ');
+    }
+    return [`M ${cx} ${cy}`, `L ${x1o} ${y1o}`, `A ${outerR} ${outerR} 0 ${largeArc} 1 ${x2o} ${y2o}`, 'Z'].join(' ');
+}

package/src/charts/stats.ts

@@ -0,0 +1,265 @@
+// Pure chart math — no DOM, no React. Ported from the private helpers of
+// web-mojo's MetricsChart (_computeStats/_formatStatNumber/_downloadCsv/
+// setQuickRange) and MetricsMiniChartWidget (windowed trending), promoted to
+// typed exports so stats dialogs, KPI tiles and the mini widget share ONE
+// implementation (web-mojo carried two diverging copies of the stats math).
+
+export interface SeriesLike {
+    label: string;
+    data: number[];
+}
+
+export interface SeriesStat {
+    label: string;
+    count: number;
+    sum: number;
+    avg: number;
+    median: number;
+    min: number;
+    max: number;
+    latest: number;
+}
+
+/** Coerce a wire value to a number the way the source did (parseFloat || 0). */
+export function toNumber(v: unknown): number {
+    if (typeof v === 'number') return Number.isFinite(v) ? v : 0;
+    if (v == null || v === '') return 0;
+    const n = parseFloat(String(v));
+    return Number.isNaN(n) ? 0 : n;
+}
+
+/**
+ * Per-series summary stats. Empty datasets produce no entry (the caller
+ * renders its "No data" state); an empty series inside a non-empty set
+ * yields a zeroed row so the table stays aligned with the legend.
+ */
+export function computeSeriesStats(datasets: readonly SeriesLike[] | null | undefined): SeriesStat[] {
+    // (Array.isArray would widen the readonly array to any[] — a TS quirk.)
+    const list: readonly SeriesLike[] = datasets ?? [];
+    return list.map((d) => {
+        const values = (Array.isArray(d.data) ? d.data : []).map(toNumber);
+        if (values.length === 0) {
+            return { label: d.label ?? '', count: 0, sum: 0, avg: 0, median: 0, min: 0, max: 0, latest: 0 };
+        }
+        const sorted = [...values].sort((a, b) => a - b);
+        const sum = values.reduce((a, b) => a + b, 0);
+        const mid = Math.floor(sorted.length / 2);
+        const median = sorted.length % 2 === 0 ? (sorted[mid - 1]! + sorted[mid]!) / 2 : sorted[mid]!;
+        return {
+            label: d.label ?? '',
+            count: values.length,
+            sum,
+            avg: sum / values.length,
+            median,
+            min: sorted[0]!,
+            max: sorted[sorted.length - 1]!,
+            latest: values[values.length - 1]!,
+        };
+    });
+}
+
+/** '–' for nothing; integers plain; decimals to 2 places (source parity). */
+export function defaultStatFormat(n: number | null | undefined): string {
+    if (n == null || Number.isNaN(n)) return '–';
+    if (Number.isInteger(n)) return n.toLocaleString();
+    return Number(n).toLocaleString(undefined, { maximumFractionDigits: 2 });
+}
+
+/** "Hourly · 24 points" header noun per granularity (source map, verbatim). */
+export const GRANULARITY_NOUN: Record<string, string> = {
+    minutes: 'Per minute',
+    hours: 'Hourly',
+    days: 'Daily',
+    weeks: 'Weekly',
+    months: 'Monthly',
+    years: 'Yearly',
+};
+
+// ── CSV (source _downloadCsv, split so the string builder is testable) ──
+
+export function csvEscape(v: unknown): string {
+    let s = String(v ?? '');
+    // Spreadsheet applications treat these string prefixes as formulas even
+    // inside a valid CSV cell. Numeric negatives remain numeric by checking
+    // the original value before adding the neutralizing apostrophe.
+    if (typeof v === 'string' && /^[=+\-@\t\r]/.test(s)) s = `'${s}`;
+    return /[",\r\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
+}
+
+export function buildCsv(headers: readonly string[], rows: readonly (readonly unknown[])[]): string {
+    const lines = [headers.map(csvEscape).join(',')];
+    for (const row of rows) lines.push(row.map(csvEscape).join(','));
+    return lines.join('\n');
+}
+
+/** 'API Calls — prod' + today → 'api-calls-prod-2026-08-05.csv' (source slugging). */
+export function csvFilename(title: string | null | undefined, now: Date = new Date()): string {
+    const slug = String(title ?? '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '') || 'chart-data';
+    return `${slug}-${now.toISOString().slice(0, 10)}.csv`;
+}
+
+// ── Trend windows (MetricsMiniChartWidget.updateFromChartData, verbatim) ──
+
+export interface TrendOptions {
+    /** Window size hint; k = max(1, floor(trendRange / 2)) buckets per window. */
+    trendRange?: number | null;
+    /** Skip the trailing N buckets before comparing (partial-bucket guard). */
+    trendOffset?: number | null;
+    /** Compare against the window N buckets earlier instead of the adjacent one. */
+    prevTrendOffset?: number | null;
+}
+
+export interface Trend {
+    /** Sum over the current window. */
+    lastSum: number;
+    /** Sum over the comparison window. */
+    prevSum: number;
+    /** Percent change; prev 0 → +100 when rising, 0 when flat (source rule). */
+    percent: number;
+    up: boolean;
+}
+
+/**
+ * Windowed percent trend over a bucket series. Falls back to single-point
+ * comparison when the series is too short for two full windows; returns null
+ * when there is nothing to compare (0–1 usable points).
+ */
+export function computeTrend(values: readonly number[] | null | undefined, opts: TrendOptions = {}): Trend | null {
+    const nums = (values ?? []).map(toNumber);
+    if (nums.length === 0) return null;
+
+    const offset = Math.max(0, Math.trunc(opts.trendOffset ?? 0) || 0);
+    const endIndex = Math.max(0, nums.length - 1 - offset);
+    const prevOffset = Math.max(0, Math.trunc(opts.prevTrendOffset ?? 0) || 0);
+    const k = opts.trendRange != null && opts.trendRange >= 2 ? Math.max(1, Math.floor(opts.trendRange / 2)) : 1;
+
+    const sumRange = (s: number, e: number): number => {
+        let sum = 0;
+        for (let i = s; i <= e; i++) sum += nums[i] ?? 0;
+        return sum;
+    };
+
+    let lastSum = 0;
+    let prevSum = 0;
+    let hasTrend = false;
+
+    const lastEnd = endIndex;
+    const lastStart = lastEnd - (k - 1);
+    let prevStart: number;
+    let prevEnd: number;
+    if (prevOffset > 0) {
+        prevStart = lastStart - prevOffset;
+        prevEnd = lastEnd - prevOffset;
+    } else {
+        prevEnd = lastStart - 1;
+        prevStart = prevEnd - (k - 1);
+    }
+    if (lastStart >= 0 && prevStart >= 0) {
+        lastSum = sumRange(lastStart, lastEnd);
+        prevSum = sumRange(prevStart, prevEnd);
+        hasTrend = true;
+    }
+
+    if (!hasTrend) {
+        // Single-point fallback (source parity).
+        const prevIndex = endIndex - (prevOffset > 0 ? prevOffset : 1);
+        if (prevIndex < 0) return null;
+        lastSum = nums[endIndex] ?? 0;
+        prevSum = nums[prevIndex] ?? 0;
+    }
+
+    const percent = prevSum === 0 ? (lastSum > 0 ? 100 : 0) : ((lastSum - prevSum) / Math.abs(prevSum)) * 100;
+    return { lastSum, prevSum, percent, up: percent >= 0 };
+}
+
+/**
+ * Delta badge text + tone (KPITile._renderDelta, verbatim incl. the
+ * never-Infinity% rule): a finite deltaPct renders as a percent; otherwise a
+ * present absolute delta renders as a signed count; otherwise no badge.
+ * `direction` maps through `tone` ('bad' = rising is bad) to a display tone.
+ */
+export interface DeltaBadge {
+    text: string;
+    /** 'good' | 'bad' | 'flat' | 'neutral' — the CSS class family. */
+    tone: 'good' | 'bad' | 'flat' | 'neutral';
+}
+
+export function deltaBadge(
+    delta: number | null | undefined,
+    deltaPct: number | null | undefined,
+    tone: 'good' | 'bad' | null | undefined,
+): DeltaBadge | null {
+    let sign: '+' | '−' | '±';
+    let text: string;
+    if (deltaPct != null && Number.isFinite(deltaPct)) {
+        const rounded = Math.abs(deltaPct) >= 10 ? Math.round(deltaPct) : Math.round(deltaPct * 10) / 10;
+        sign = rounded > 0 ? '+' : rounded < 0 ? '−' : '±';
+        text = `${sign}${Math.abs(rounded)}%`;
+    } else if (delta != null && Number.isFinite(delta)) {
+        sign = delta > 0 ? '+' : delta < 0 ? '−' : '±';
+        text = `${sign}${Math.abs(delta)}`;
+    } else {
+        return null;
+    }
+    let badgeTone: DeltaBadge['tone'];
+    if (sign === '±') badgeTone = 'flat';
+    else if (tone === 'bad') badgeTone = sign === '+' ? 'bad' : 'good';
+    else if (tone === 'good') badgeTone = sign === '+' ? 'good' : 'bad';
+    else badgeTone = 'neutral';
+    return { text, tone: badgeTone };
+}
+
+// ── Date windows (MetricsChart.setQuickRange + custom-range support) ──
+
+/** Quick-range span in ms. Unknown values warn at the caller; '24h' shape. */
+export const QUICK_RANGE_MS: Record<string, number> = {
+    '1h': 3600e3,
+    '24h': 24 * 3600e3,
+    '7d': 7 * 864e5,
+    '30d': 30 * 864e5,
+};
+
+/** [start, end] ms epochs for a quick range anchored at `now` (source setQuickRange). */
+export function quickRangeWindow(range: string, now: number = Date.now()): { startMs: number; endMs: number } {
+    const span = QUICK_RANGE_MS[range] ?? QUICK_RANGE_MS['24h']!;
+    return { startMs: now - span, endMs: now };
+}
+
+/**
+ * Which granularities make sense for an arbitrary span — the custom-range
+ * twin of MetricsChart's per-quick-range gating (mirrors the backend's
+ * bucket sizes; a 6-month range at 'minutes' would be a quarter-million
+ * buckets).
+ */
+export function granularitiesForSpanMs(spanMs: number): string[] {
+    const h = spanMs / 3600e3;
+    if (h <= 2) return ['minutes'];
+    if (h <= 48) return ['minutes', 'hours'];
+    if (h <= 8 * 24) return ['hours', 'days'];
+    if (h <= 92 * 24) return ['days', 'weeks', 'months'];
+    return ['days', 'weeks', 'months'];
+}
+
+/**
+ * Canonical YYYY-MM-DD pair (DateRangePicker output) → inclusive epoch-SECOND
+ * bounds in the viewer's local time: start 00:00:00 through end 23:59:59.
+ * These are the `dt_start`/`dt_end` values /api/metrics/fetch takes (epoch
+ * seconds — the django-mojo datetime wire unit). Invalid input → null.
+ */
+export function ymdRangeToEpochSeconds(startYmd: string, endYmd: string): { dtStart: number; dtEnd: number } | null {
+    const parse = (s: string): [number, number, number] | null => {
+        const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(s);
+        if (!m) return null;
+        return [Number(m[1]), Number(m[2]), Number(m[3])];
+    };
+    const a = parse(startYmd);
+    const b = parse(endYmd);
+    if (!a || !b) return null;
+    const start = new Date(a[0], a[1] - 1, a[2], 0, 0, 0, 0).getTime();
+    const end = new Date(b[0], b[1] - 1, b[2] + 1, 0, 0, 0, 0).getTime() - 1000; // 23:59:59
+    if (Number.isNaN(start) || Number.isNaN(end) || end < start) return null;
+    return { dtStart: Math.floor(start / 1000), dtEnd: Math.floor(end / 1000) };
+}