@joewinke/jatui 0.36.3 → 0.38.0

package/dist/artifact-blocks/blocks/chart/schema.js

@@ -0,0 +1,498 @@
+/**
+ * Chart block — params schema, normalization and geometry helpers.
+ *
+ * Pure functions only (no DOM) so `block.test.ts` can exercise the math and
+ * `ChartBlock.svelte` stays a thin renderer. Colors NEVER appear here — the
+ * renderer addresses the `--chart-series-N` token contract from
+ * `src/lib/theme-bridge/layerchart.css` (which maps them to DaisyUI palette
+ * tokens), so every tenant theme reskins the chart for free.
+ *
+ * Untrusted input rules (CONTRACT.md): text params are length-capped strings,
+ * numbers are finite, arrays are capped. Series/point caps exist so one
+ * artifact can't ship a 50MB SVG: 20 series, 5000 points total.
+ */
+import { z } from "zod";
+const CHART_TYPES = ["line", "bar", "area", "scatter"];
+const X_TYPES = ["time", "category", "number"];
+const Y_FORMATS = ["raw", "compact", "percent", "currency"];
+const MAX_SERIES = 20;
+const MAX_POINTS_TOTAL = 5000;
+const MAX_POINTS_PER_SERIES = 2500;
+/** Series count past which direct end-labels stop being readable. */
+export const END_LABEL_SERIES_LIMIT = 8;
+const xValueSchema = z.union([z.string().max(80), z.number().finite()]);
+export const chartSchema = z
+    .object({
+    /** Mark kind. Stacking applies to bar/area only. */
+    chartType: z.enum(CHART_TYPES).default("line"),
+    title: z.string().max(200).optional(),
+    subtitle: z.string().max(300).optional(),
+    xLabel: z.string().max(80).optional(),
+    yLabel: z.string().max(80).optional(),
+    y2Label: z.string().max(80).optional(),
+    /** How to read each point's x. Category = as-given order. */
+    xType: z.enum(X_TYPES).default("category"),
+    series: z
+        .array(z.object({
+        label: z.string().min(1).max(80),
+        /**
+         * Dual axis: only when the two units differ (e.g. visitors vs
+         * revenue). Identity stays in the legend/end-label text either way.
+         */
+        axis: z.enum(["left", "right"]).default("left"),
+        points: z
+            .array(z.object({
+            /** time: ISO date(-time) or epoch ms · category: label · number: value */
+            x: xValueSchema,
+            y: z.number().finite(),
+        }))
+            .min(1)
+            .max(MAX_POINTS_PER_SERIES),
+    }))
+        .min(1)
+        .max(MAX_SERIES),
+    /** Stack bar/area series (cumulative per axis group). */
+    stacked: z.boolean().default(false),
+    /** Horizontal dashed target/threshold lines (from the value axis). */
+    goalLines: z
+        .array(z.object({
+        value: z.number().finite(),
+        label: z.string().max(80).optional(),
+        axis: z.enum(["left", "right"]).default("left"),
+    }))
+        .max(10)
+        .default([]),
+    /** Vertical markers: a full-height line (point) or shaded band (range). */
+    annotations: z
+        .array(z.object({
+        kind: z.enum(["point", "range"]),
+        x: xValueSchema,
+        /** range only: the end of the band. */
+        x2: xValueSchema.optional(),
+        /** point only: dot position on the value axis (line still drawn). */
+        y: z.number().finite().optional(),
+        label: z.string().min(1).max(120),
+    }))
+        .max(20)
+        .default([]),
+    /** Value-axis tick/tooltip formatting (raw/compact/percent/currency). */
+    yFormat: z.enum(Y_FORMATS).default("raw"),
+    /** ISO 4217 code used when yFormat is "currency". */
+    currency: z
+        .string()
+        .regex(/^[A-Za-z]{3}$/)
+        .default("USD"),
+    showLegend: z.boolean().default(true),
+    /** Direct series labels at the last point (auto-off past 8 series). */
+    endLabels: z.boolean().default(true),
+    height: z.number().int().min(160).max(800).default(280),
+    /**
+     * Value-axis domain overrides. bar/area NEVER truncate at 0: an explicit
+     * yMin/yMax can only extend the domain, never lift it off zero.
+     */
+    yMin: z.number().finite().optional(),
+    yMax: z.number().finite().optional(),
+    /** Phase-3 live data: key into ctx.data whose value replaces params. */
+    dataKey: z.string().max(80).optional(),
+})
+    .superRefine((params, ctx) => {
+    const total = params.series.reduce((n, s) => n + s.points.length, 0);
+    if (total > MAX_POINTS_TOTAL)
+        ctx.addIssue({
+            code: "custom",
+            path: ["series"],
+            message: `at most ${MAX_POINTS_TOTAL} points across all series (got ${total})`,
+        });
+    if (params.stacked &&
+        (params.chartType === "line" || params.chartType === "scatter"))
+        ctx.addIssue({
+            code: "custom",
+            path: ["stacked"],
+            message: "stacked applies to bar and area charts only",
+        });
+});
+// ── X parsing/normalization ────────────────────────────────────────────────
+/** ISO date-only strings are parsed as LOCAL midnight so a viewer's
+ * timezone can't shift which day a tick names (a UTC parse + local format
+ * renders "Jan 4" for the 5th west of Greenwich). Full ISO timestamps and
+ * epoch milliseconds parse normally. */
+export function parseTimeX(x) {
+    if (typeof x === "number")
+        return x;
+    const m = /^(\d{4})-(\d{2})(?:-(\d{2}))?$/.exec(x.trim());
+    if (m) {
+        const d = new Date(Number(m[1]), Number(m[2]) - 1, m[3] ? Number(m[3]) : 1);
+        const ms = d.getTime();
+        return Number.isFinite(ms) ? ms : NaN;
+    }
+    const ms = new Date(x).getTime();
+    return Number.isFinite(ms) ? ms : NaN;
+}
+function parseXNum(raw, xType) {
+    if (xType === "time")
+        return parseTimeX(raw);
+    if (xType === "number") {
+        const n = typeof raw === "number" ? raw : Number.parseFloat(raw);
+        return Number.isFinite(n) ? n : NaN;
+    }
+    // category — handled by the caller (needs the label→index map)
+    return NaN;
+}
+/**
+ * Normalize params for rendering: parse x per axis type, drop unparseable
+ * points, sort each series by x, and dedupe repeated x values keeping the
+ * LAST write (an agent re-sending a corrected value reads as an update).
+ */
+export function normalizeChart(params) {
+    const categories = [];
+    const catIndex = new Map();
+    const series = params.series.map((s) => {
+        const parsed = [];
+        for (const p of s.points) {
+            let xNum;
+            if (params.xType === "category") {
+                const label = String(p.x);
+                let idx = catIndex.get(label);
+                if (idx === undefined) {
+                    idx = categories.length;
+                    catIndex.set(label, idx);
+                    categories.push(label);
+                }
+                xNum = idx;
+            }
+            else {
+                xNum = parseXNum(p.x, params.xType);
+            }
+            if (Number.isFinite(xNum))
+                parsed.push({ xNum, y: p.y });
+        }
+        parsed.sort((a, b) => a.xNum - b.xNum);
+        const points = [];
+        for (const p of parsed) {
+            const prev = points.at(-1);
+            if (prev && prev.xNum === p.xNum)
+                prev.y = p.y;
+            else
+                points.push(p);
+        }
+        return { label: s.label, axis: s.axis, points };
+    });
+    const xNumSet = new Set();
+    for (const s of series)
+        for (const p of s.points)
+            xNumSet.add(p.xNum);
+    const xNums = [...xNumSet].sort((a, b) => a - b);
+    return {
+        xType: params.xType,
+        categories,
+        xNums,
+        series,
+        dual: params.series.some((s) => s.axis === "right"),
+    };
+}
+// ── Value domain + ticks ──────────────────────────────────────────────────
+/** d3-style "nice" linear ticks: a round step whose multiples enclose
+ * [min, max]. Returns the ticks and the enclosing domain. */
+export function linearTicks(min, max, count = 5) {
+    if (!Number.isFinite(min) || !Number.isFinite(max))
+        return { ticks: [], domain: [0, 1] };
+    if (min === max) {
+        if (min === 0)
+            return { ticks: [0, 1], domain: [0, 1] };
+        const pad = Math.abs(min) * 0.1;
+        min -= pad;
+        max += pad;
+    }
+    const rough = (max - min) / Math.max(1, count);
+    const mag = 10 ** Math.floor(Math.log10(rough));
+    const norm = rough / mag;
+    const step = (norm > 5 ? 10 : norm > 2 ? 5 : norm > 1 ? 2 : 1) * mag;
+    const lo = Math.floor(min / step) * step;
+    const hi = Math.ceil(max / step) * step;
+    const ticks = [];
+    for (let v = lo; v <= hi && ticks.length < 400; v += step)
+        ticks.push(Math.round(v * 1e10) / 1e10);
+    return { ticks, domain: [lo, hi] };
+}
+/** Value-axis domain for a chart. `valueAxis` marks charts that encode
+ * magnitude (bar/area): their domain always includes 0 — an explicit
+ * yMin/yMax may extend it downward/upward but never truncate. */
+export function valueDomain(values, chartType, opts = {}) {
+    const finite = values.filter((v) => Number.isFinite(v));
+    const dataMin = finite.length ? Math.min(...finite) : 0;
+    const dataMax = finite.length ? Math.max(...finite) : 1;
+    let min;
+    let max;
+    if (chartType === "bar" || chartType === "area") {
+        min = Math.min(0, dataMin, opts.yMin ?? Number.POSITIVE_INFINITY);
+        max = Math.max(0, dataMax, opts.yMax ?? Number.NEGATIVE_INFINITY);
+    }
+    else {
+        min = Math.min(opts.yMin ?? dataMin, dataMin);
+        max = Math.max(opts.yMax ?? dataMax, dataMax);
+    }
+    if (min === max) {
+        if (min === 0)
+            return [0, 1];
+        const pad = Math.abs(min) * 0.1;
+        min -= pad;
+        max += pad;
+    }
+    return [min, max];
+}
+const TIME_STEPS = [
+    { unit: "hour", step: 1, approxMs: 3.6e6 },
+    { unit: "hour", step: 3, approxMs: 3 * 3.6e6 },
+    { unit: "hour", step: 6, approxMs: 6 * 3.6e6 },
+    { unit: "hour", step: 12, approxMs: 12 * 3.6e6 },
+    { unit: "day", step: 1, approxMs: 86.4e6 },
+    { unit: "day", step: 2, approxMs: 2 * 86.4e6 },
+    { unit: "week", step: 1, approxMs: 7 * 86.4e6 },
+    { unit: "month", step: 1, approxMs: 30.4 * 86.4e6 },
+    { unit: "month", step: 3, approxMs: 3 * 30.4 * 86.4e6 },
+    { unit: "year", step: 1, approxMs: 365.25 * 86.4e6 },
+    { unit: "year", step: 2, approxMs: 2 * 365.25 * 86.4e6 },
+    { unit: "year", step: 5, approxMs: 5 * 365.25 * 86.4e6 },
+];
+// Local-time calendar math on native Date (what dayjs did in MOS — jatui
+// carries no date library). Weeks start on Sunday, as dayjs' default locale.
+function floorToStep(ms, unit, step) {
+    const d = new Date(ms);
+    switch (unit) {
+        case "hour":
+            d.setMinutes(0, 0, 0);
+            d.setHours(d.getHours() - (d.getHours() % step));
+            return d.getTime();
+        case "day":
+            d.setHours(0, 0, 0, 0);
+            return d.getTime();
+        case "week":
+            d.setHours(0, 0, 0, 0);
+            d.setDate(d.getDate() - d.getDay());
+            return d.getTime();
+        case "month":
+            d.setHours(0, 0, 0, 0);
+            d.setDate(1);
+            d.setMonth(d.getMonth() - (d.getMonth() % step));
+            return d.getTime();
+        case "year":
+            d.setHours(0, 0, 0, 0);
+            d.setMonth(0, 1);
+            d.setFullYear(d.getFullYear() - (d.getFullYear() % step));
+            return d.getTime();
+    }
+}
+/** Advance a tick by `step` units. Hours are absolute (DST-proof spacing);
+ * days, weeks, months and years are calendar steps from an already-floored
+ * tick, so a month step never lands on a clamped day-of-month. */
+function addStep(ms, unit, step) {
+    if (unit === "hour")
+        return ms + step * 3.6e6;
+    const d = new Date(ms);
+    if (unit === "day")
+        d.setDate(d.getDate() + step);
+    else if (unit === "week")
+        d.setDate(d.getDate() + 7 * step);
+    else if (unit === "month")
+        d.setMonth(d.getMonth() + step);
+    else
+        d.setFullYear(d.getFullYear() + step);
+    return d.getTime();
+}
+/** Calendar-aware tick positions for a time axis: ~`target` ticks, snapped
+ * to real hour/day/week/month/year boundaries (never "Jan 31 15:37").
+ * Picks the step whose tick count is CLOSEST to the target — "first step
+ * above the ideal" jumps from a week to a month the moment a span crosses
+ * 7·target days, collapsing 7 good ticks into 2. */
+export function timeTicks(minMs, maxMs, target = 6) {
+    if (!Number.isFinite(minMs) || !Number.isFinite(maxMs))
+        return [];
+    const span = Math.max(1, maxMs - minMs);
+    let pick = TIME_STEPS[TIME_STEPS.length - 1];
+    let bestErr = Infinity;
+    for (const s of TIME_STEPS) {
+        const err = Math.abs(span / s.approxMs - target);
+        if (err < bestErr) {
+            bestErr = err;
+            pick = s;
+        }
+    }
+    let t = floorToStep(minMs, pick.unit, pick.step);
+    const out = [];
+    while (t <= maxMs && out.length < 60) {
+        if (t >= minMs)
+            out.push(t);
+        t = addStep(t, pick.unit, pick.step);
+        if (!Number.isFinite(t))
+            break;
+    }
+    return out.length ? out : [minMs, maxMs];
+}
+/** A tick formatter that says what the span needs (no redundant year in a
+ * same-year span; hours get their date so a 3-day hourly chart reads). */
+export function timeTickFormat(minMs, maxMs) {
+    const spanDays = (maxMs - minMs) / 86.4e6;
+    const fmt = (opts) => new Intl.DateTimeFormat("en-US", opts).format;
+    if (spanDays < 1)
+        return fmt({ month: "short", day: "numeric", hour: "numeric" });
+    const crossesYear = new Date(minMs).getFullYear() !== new Date(maxMs).getFullYear();
+    if (spanDays <= 92)
+        return fmt({ month: "short", day: "numeric" });
+    if (spanDays <= 730)
+        return fmt(crossesYear
+            ? { month: "short", year: "numeric" }
+            : { month: "short", day: "numeric" });
+    return fmt({ year: "numeric" });
+}
+// ── Formatting ────────────────────────────────────────────────────────────
+/** Fixed en-US so a chart reads identically for every viewer and every
+ * snapshot/test; the locale is a formatting choice, not user data. */
+export function formatYValue(v, fmt, currency) {
+    if (!Number.isFinite(v))
+        return "n/a";
+    switch (fmt) {
+        case "compact":
+            return new Intl.NumberFormat("en-US", {
+                notation: "compact",
+                maximumFractionDigits: 1,
+            }).format(v);
+        case "percent":
+            return `${new Intl.NumberFormat("en-US", { maximumFractionDigits: 1 }).format(v)}%`;
+        case "currency":
+            return new Intl.NumberFormat("en-US", {
+                style: "currency",
+                currency,
+                notation: Math.abs(v) >= 10000 ? "compact" : "standard",
+                maximumFractionDigits: Math.abs(v) >= 10000 ? 1 : 2,
+            }).format(v);
+        default:
+            return new Intl.NumberFormat("en-US", {
+                maximumFractionDigits: 2,
+            }).format(v);
+    }
+}
+/** Compact axis ticks stay round ("2k", "2M") — maximumFractionDigits 0. */
+export function formatYTick(v, fmt, currency) {
+    if (fmt === "raw")
+        return Math.abs(v) >= 10000
+            ? new Intl.NumberFormat("en-US", {
+                notation: "compact",
+                maximumFractionDigits: 1,
+            }).format(v)
+            : new Intl.NumberFormat("en-US", { maximumFractionDigits: 2 }).format(v);
+    if (fmt === "currency" && Math.abs(v) >= 10000)
+        return new Intl.NumberFormat("en-US", {
+            style: "currency",
+            currency,
+            notation: "compact",
+            maximumFractionDigits: 1,
+        }).format(v);
+    return formatYValue(v, fmt, currency);
+}
+/** The data-table fallback always shows FULL precision — it exists to give
+ * exact values (screen readers, copy/paste); compact notation belongs to the
+ * chart marks and tooltip. */
+export function formatTableValue(v, fmt, currency) {
+    if (!Number.isFinite(v))
+        return "n/a";
+    if (fmt === "currency")
+        return new Intl.NumberFormat("en-US", {
+            style: "currency",
+            currency,
+            maximumFractionDigits: 2,
+        }).format(v);
+    if (fmt === "percent")
+        return `${new Intl.NumberFormat("en-US", { maximumFractionDigits: 2 }).format(v)}%`;
+    return new Intl.NumberFormat("en-US", { maximumFractionDigits: 2 }).format(v);
+}
+// ── Interaction geometry ──────────────────────────────────────────────────
+/** Index of the value closest to `target` (the crosshair's x pick). */
+export function nearestIndex(values, target) {
+    if (!values.length)
+        return -1;
+    let best = 0;
+    for (let i = 1; i < values.length; i++)
+        if (Math.abs(values[i] - target) < Math.abs(values[best] - target))
+            best = i;
+    return best;
+}
+/** Stack series into cumulative [y0, y1] segments per shared x. Missing
+ * points contribute 0 (later series still stack in their lane). Points at
+ * the same x within one series are summed (dedupe already keeps the last,
+ * so this only fires when an agent stacks pre-aggregated data). */
+export function stackByX(series) {
+    const n = series.length;
+    const byX = new Map();
+    series.forEach((pts, si) => {
+        for (const p of pts) {
+            let row = byX.get(p.xNum);
+            if (!row) {
+                row = new Array(n).fill(undefined);
+                byX.set(p.xNum, row);
+            }
+            row[si] = (row[si] ?? 0) + p.y;
+        }
+    });
+    const xNums = [...byX.keys()].sort((a, b) => a - b);
+    return series.map((_, si) => {
+        const segs = [];
+        for (const xNum of xNums) {
+            const row = byX.get(xNum);
+            const present = row?.[si] !== undefined;
+            if (!present)
+                continue;
+            let acc = 0;
+            for (let j = 0; j < si; j++)
+                acc += row?.[j] ?? 0;
+            segs.push({ xNum, y0: acc, y1: acc + (row?.[si] ?? 0) });
+        }
+        return segs;
+    });
+}
+// ── End-label collision layout ────────────────────────────────────────────
+/** Push apart y positions so series labels at line ends never overlap:
+ * forward pass pushes down, backward pass pulls the overflow back up.
+ * Positions are clamped inside [top, bottom]. */
+export function layoutEndLabels(items, top, bottom, gap = 13) {
+    const order = items.map((it, i) => ({ i, y: it.y })).sort((a, b) => a.y - b.y);
+    const half = gap / 2;
+    const placed = new Array(items.length).fill(0);
+    let prev = -Infinity;
+    for (const o of order) {
+        const y = Math.min(Math.max(o.y, top + half), bottom - half);
+        placed[o.i] = Math.max(y, prev + gap);
+        prev = placed[o.i];
+    }
+    let next = Infinity;
+    for (let k = order.length - 1; k >= 0; k--) {
+        const o = order[k];
+        placed[o.i] = Math.min(placed[o.i], next - gap, bottom - half);
+        next = placed[o.i];
+    }
+    return placed.map((y) => Math.min(Math.max(y, top + half), bottom - half));
+}
+// ── A11y table rows ───────────────────────────────────────────────────────
+/** Per-series x → y lookup (O(points) build; the render loop hits it per
+ * slot, so a `.find()` per cell would be quadratic on 5000-point charts). */
+export function valueMap(points) {
+    const m = new Map();
+    for (const p of points)
+        m.set(p.xNum, p.y);
+    return m;
+}
+/** One row per shared x; series values aligned by x (null = not present). */
+export function dataTableRows(chart) {
+    const maps = chart.series.map((s) => valueMap(s.points));
+    return chart.xNums.map((xNum) => ({
+        x: xNum,
+        xLabel: chart.xType === "category"
+            ? (chart.categories[xNum] ?? String(xNum))
+            : chart.xType === "time"
+                ? new Intl.DateTimeFormat("en-US", {
+                    dateStyle: "medium",
+                    timeStyle: "short",
+                }).format(xNum)
+                : String(xNum),
+        values: maps.map((m) => m.get(xNum) ?? null),
+    }));
+}

package/dist/artifact-blocks/blocks/chart/thumb.d.ts

@@ -0,0 +1,2 @@
+import { type ThumbPalette } from "../../thumb-kit.js";
+export declare function drawChartThumb(raw: unknown, palette: ThumbPalette): string | null;