@joewinke/jatui 0.36.3 → 0.38.0

package/dist/artifact-blocks/blocks/chart/ChartBlock.svelte.d.ts

@@ -0,0 +1,59 @@
+/**
+   * ChartBlock — SVG line / bar / area / scatter renderer (block type "chart").
+   *
+   * Hand-rolled SVG, no chart dependency: scales, ticks and stacking live in
+   * ./schema.ts (pure, unit-tested); this file is the render layer.
+   *
+   * Dataviz discipline (the ruby-kim-soak rules):
+   *   - recessive grid (base-content/10, horizontal only),
+   *   - honest axes (value axis always includes 0 for bar/area — an explicit
+   *     yMin/yMax can extend the domain but never truncate it),
+   *   - identity never by color alone (series name in the legend chips, in the
+   *     direct end-labels, in the tooltip, and in the data-table fallback).
+   *
+   * Colors are tokens only: series strokes come from the `--chart-series-1..6`
+   * contract (src/lib/theme-bridge/layerchart.css, mapped to DaisyUI palette
+   * tokens) — this wrapper carries the `lc-root-container` class so those vars
+   * resolve, with `var(--color-primary)` as the fallback.
+   */
+import type { BlockProps } from "../../types.js";
+declare const ChartBlock: import("svelte").Component<BlockProps<{
+    chartType: "area" | "line" | "bar" | "scatter";
+    xType: "number" | "time" | "category";
+    series: {
+        label: string;
+        axis: "left" | "right";
+        points: {
+            x: string | number;
+            y: number;
+        }[];
+    }[];
+    stacked: boolean;
+    goalLines: {
+        value: number;
+        axis: "left" | "right";
+        label?: string | undefined;
+    }[];
+    annotations: {
+        kind: "range" | "point";
+        x: string | number;
+        label: string;
+        x2?: string | number | undefined;
+        y?: number | undefined;
+    }[];
+    yFormat: "raw" | "compact" | "currency" | "percent";
+    currency: string;
+    showLegend: boolean;
+    endLabels: boolean;
+    height: number;
+    title?: string | undefined;
+    subtitle?: string | undefined;
+    xLabel?: string | undefined;
+    yLabel?: string | undefined;
+    y2Label?: string | undefined;
+    yMin?: number | undefined;
+    yMax?: number | undefined;
+    dataKey?: string | undefined;
+}>, {}, "">;
+type ChartBlock = ReturnType<typeof ChartBlock>;
+export default ChartBlock;

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

@@ -0,0 +1,9 @@
+/**
+ * Chart block definition (block type "chart").
+ * Contract: src/lib/artifact-blocks/CONTRACT.md — registry.ts discovers this
+ * folder; nothing else registers a block.
+ */
+import type { ArtifactBlockDef } from "../../types.js";
+import { type ChartParams } from "./schema.js";
+declare const def: ArtifactBlockDef<ChartParams>;
+export default def;

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

@@ -0,0 +1,70 @@
+import { chartSchema } from "./schema.js";
+import ChartBlock from "./ChartBlock.svelte";
+const def = {
+    type: "chart",
+    title: "Chart",
+    description: "Line, bar (grouped/stacked), area or scatter chart from series data. " +
+        "xType 'time' reads x as ISO dates ('2026-01-15', or epoch ms) for trends; " +
+        "xType 'number' for numeric relationships; xType 'category' reads x as labels " +
+        "in the order you list them (bars want few distinct x values). Each series is " +
+        "{label, points:[{x,y}]} — values must be finite numbers; caps 20 series and " +
+        "5000 points total. All series share one value axis; set series.axis='right' " +
+        "ONLY when a second unit genuinely differs (e.g. visitors vs revenue) and name " +
+        "it with y2Label. goalLines draw dashed horizontal targets; annotations mark a " +
+        "point (vertical line + label, optional dot) or a range (shaded band + label); " +
+        "annotation x uses the same x format as the points. stacked (bar/area only) " +
+        "sums series cumulatively. Honest axes: bar/area always include 0 — yMin/yMax " +
+        "can extend the domain but never truncate it (line/scatter may zoom). Series " +
+        "identity is carried by text (legend + direct end-labels), never color alone. " +
+        "An accessible data table is built in (screen readers get it always; sighted " +
+        "readers via 'View data') — don't pair a chart with a duplicate data table. " +
+        "Tip: keep series at 8 or fewer so direct end-labels fit; use yFormat " +
+        "('compact' for big counts, 'percent'/'currency' with currency) for readable ticks.",
+    schema: chartSchema,
+    component: ChartBlock,
+    // mos-8fvt9: the section's Listen + comment sit on the heading row.
+    hostsTools: (p) => Boolean(p.title),
+    example: {
+        chartType: "line",
+        title: "Monthly revenue",
+        subtitle: "Actual vs cost",
+        xType: "time",
+        xLabel: "Month",
+        yLabel: "Revenue",
+        yFormat: "currency",
+        series: [
+            {
+                label: "Revenue",
+                points: [
+                    { x: "2026-07-01", y: 8200 },
+                    { x: "2026-08-01", y: 9100 },
+                    { x: "2026-09-01", y: 10400 },
+                    { x: "2026-10-01", y: 9980 },
+                    { x: "2026-11-01", y: 12300 },
+                ],
+            },
+            {
+                label: "Cost",
+                points: [
+                    { x: "2026-07-01", y: 5100 },
+                    { x: "2026-08-01", y: 5300 },
+                    { x: "2026-09-01", y: 5750 },
+                    { x: "2026-10-01", y: 6100 },
+                    { x: "2026-11-01", y: 6350 },
+                ],
+            },
+        ],
+        goalLines: [{ value: 12000, label: "Target" }],
+        annotations: [
+            { kind: "point", x: "2026-09-01", y: 10400, label: "Price change" },
+        ],
+        yFormat: "currency",
+        currency: "USD",
+        showLegend: true,
+        endLabels: true,
+        height: 280,
+        stacked: false,
+    },
+    dataParam: "dataKey",
+};
+export default def;

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

@@ -0,0 +1,171 @@
+/**
+ * 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";
+declare const X_TYPES: readonly ["time", "category", "number"];
+/** Series count past which direct end-labels stop being readable. */
+export declare const END_LABEL_SERIES_LIMIT = 8;
+export declare const chartSchema: z.ZodObject<{
+    chartType: z.ZodDefault<z.ZodEnum<{
+        area: "area";
+        line: "line";
+        bar: "bar";
+        scatter: "scatter";
+    }>>;
+    title: z.ZodOptional<z.ZodString>;
+    subtitle: z.ZodOptional<z.ZodString>;
+    xLabel: z.ZodOptional<z.ZodString>;
+    yLabel: z.ZodOptional<z.ZodString>;
+    y2Label: z.ZodOptional<z.ZodString>;
+    xType: z.ZodDefault<z.ZodEnum<{
+        number: "number";
+        time: "time";
+        category: "category";
+    }>>;
+    series: z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        axis: z.ZodDefault<z.ZodEnum<{
+            left: "left";
+            right: "right";
+        }>>;
+        points: z.ZodArray<z.ZodObject<{
+            x: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+            y: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    stacked: z.ZodDefault<z.ZodBoolean>;
+    goalLines: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        value: z.ZodNumber;
+        label: z.ZodOptional<z.ZodString>;
+        axis: z.ZodDefault<z.ZodEnum<{
+            left: "left";
+            right: "right";
+        }>>;
+    }, z.core.$strip>>>;
+    annotations: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            range: "range";
+            point: "point";
+        }>;
+        x: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+        x2: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        y: z.ZodOptional<z.ZodNumber>;
+        label: z.ZodString;
+    }, z.core.$strip>>>;
+    yFormat: z.ZodDefault<z.ZodEnum<{
+        raw: "raw";
+        compact: "compact";
+        currency: "currency";
+        percent: "percent";
+    }>>;
+    currency: z.ZodDefault<z.ZodString>;
+    showLegend: z.ZodDefault<z.ZodBoolean>;
+    endLabels: z.ZodDefault<z.ZodBoolean>;
+    height: z.ZodDefault<z.ZodNumber>;
+    yMin: z.ZodOptional<z.ZodNumber>;
+    yMax: z.ZodOptional<z.ZodNumber>;
+    dataKey: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ChartParams = z.infer<typeof chartSchema>;
+export type ChartSeriesInput = ChartParams["series"][number];
+export type ChartGoalLine = ChartParams["goalLines"][number];
+export type ChartAnnotation = ChartParams["annotations"][number];
+/** 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 declare function parseTimeX(x: string | number): number;
+export interface NormalizedPoint {
+    xNum: number;
+    y: number;
+}
+export interface NormalizedSeries {
+    label: string;
+    axis: "left" | "right";
+    points: NormalizedPoint[];
+}
+export interface NormalizedChart {
+    xType: (typeof X_TYPES)[number];
+    /** Category labels in first-appearance order (category mode). */
+    categories: string[];
+    /** Sorted unique x positions across all series. */
+    xNums: number[];
+    series: NormalizedSeries[];
+    /** Any series on a second (right) value axis. */
+    dual: boolean;
+}
+/**
+ * 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 declare function normalizeChart(params: ChartParams): NormalizedChart;
+/** d3-style "nice" linear ticks: a round step whose multiples enclose
+ * [min, max]. Returns the ticks and the enclosing domain. */
+export declare function linearTicks(min: number, max: number, count?: number): {
+    ticks: number[];
+    domain: [number, number];
+};
+/** 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 declare function valueDomain(values: number[], chartType: ChartParams["chartType"], opts?: {
+    yMin?: number;
+    yMax?: number;
+}): [number, number];
+/** 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 declare function timeTicks(minMs: number, maxMs: number, target?: number): number[];
+/** 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 declare function timeTickFormat(minMs: number, maxMs: number): (ms: number) => string;
+/** 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 declare function formatYValue(v: number, fmt: ChartParams["yFormat"], currency: string): string;
+/** Compact axis ticks stay round ("2k", "2M") — maximumFractionDigits 0. */
+export declare function formatYTick(v: number, fmt: ChartParams["yFormat"], currency: string): string;
+/** 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 declare function formatTableValue(v: number, fmt: ChartParams["yFormat"], currency: string): string;
+/** Index of the value closest to `target` (the crosshair's x pick). */
+export declare function nearestIndex(values: number[], target: number): number;
+/** 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 declare function stackByX(series: NormalizedPoint[][]): {
+    xNum: number;
+    y0: number;
+    y1: number;
+}[][];
+/** 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 declare function layoutEndLabels(items: {
+    label: string;
+    y: number;
+}[], top: number, bottom: number, gap?: number): number[];
+/** 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 declare function valueMap(points: NormalizedPoint[]): Map<number, number>;
+/** One row per shared x; series values aligned by x (null = not present). */
+export declare function dataTableRows(chart: NormalizedChart): {
+    x: number;
+    xLabel: string;
+    values: (number | null)[];
+}[];
+export {};