@joewinke/jatui 0.37.0 → 0.38.0

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

@@ -0,0 +1,143 @@
+/**
+ * Table block — params schema, cell formatting/tone logic and CSV builder.
+ *
+ * Pure functions only (no DOM) so `block.test.ts` can exercise them and
+ * `TableBlock.svelte` stays a thin render layer over jatui's DataTable.
+ *
+ * Untrusted input rules (CONTRACT.md): every string is length-capped and
+ * rendered as text (Svelte escapes it — never {@html}); link hrefs go
+ * through `isSafeUrl` (https or root-relative, never `//`-protocol-relative
+ * or any scheme). `urlSchema` NOTE: the core task (mos-bqeoa) will publish
+ * `src/lib/artifact-blocks/params.ts` with the canonical urlSchema — until it
+ * lands this folder carries this local copy and should switch to the shared
+ * one (tracked in the block task's review signal).
+ */
+import { z } from "zod";
+export declare const COLUMN_TYPES: readonly ["text", "number", "percent", "currency", "date", "badge", "link"];
+export type ColumnType = (typeof COLUMN_TYPES)[number];
+export declare const MAX_ROWS = 5000;
+export declare const MAX_COLUMNS = 24;
+export type CellValue = string | number | boolean | null;
+declare const columnSchema: z.ZodObject<{
+    key: z.ZodString;
+    label: z.ZodString;
+    type: z.ZodDefault<z.ZodEnum<{
+        number: "number";
+        date: "date";
+        link: "link";
+        text: "text";
+        badge: "badge";
+        currency: "currency";
+        percent: "percent";
+    }>>;
+    direction: z.ZodDefault<z.ZodEnum<{
+        highIsGood: "highIsGood";
+        lowIsGood: "lowIsGood";
+    }>>;
+    good: z.ZodOptional<z.ZodNumber>;
+    warn: z.ZodOptional<z.ZodNumber>;
+    tones: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        value: z.ZodString;
+        tone: z.ZodEnum<{
+            warn: "warn";
+            good: "good";
+            bad: "bad";
+        }>;
+    }, z.core.$strip>>>;
+    hrefKey: z.ZodOptional<z.ZodString>;
+    width: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+        auto: "auto";
+        md: "md";
+        lg: "lg";
+        xs: "xs";
+        sm: "sm";
+    }>, z.ZodNumber]>>;
+}, z.core.$strip>;
+export type ColumnSpec = z.infer<typeof columnSchema>;
+export declare const tableSchema: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    columns: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        label: z.ZodString;
+        type: z.ZodDefault<z.ZodEnum<{
+            number: "number";
+            date: "date";
+            link: "link";
+            text: "text";
+            badge: "badge";
+            currency: "currency";
+            percent: "percent";
+        }>>;
+        direction: z.ZodDefault<z.ZodEnum<{
+            highIsGood: "highIsGood";
+            lowIsGood: "lowIsGood";
+        }>>;
+        good: z.ZodOptional<z.ZodNumber>;
+        warn: z.ZodOptional<z.ZodNumber>;
+        tones: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            value: z.ZodString;
+            tone: z.ZodEnum<{
+                warn: "warn";
+                good: "good";
+                bad: "bad";
+            }>;
+        }, z.core.$strip>>>;
+        hrefKey: z.ZodOptional<z.ZodString>;
+        width: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+            auto: "auto";
+            md: "md";
+            lg: "lg";
+            xs: "xs";
+            sm: "sm";
+        }>, z.ZodNumber]>>;
+    }, z.core.$strip>>;
+    rows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>>;
+    pageSize: z.ZodDefault<z.ZodNumber>;
+    filterable: z.ZodDefault<z.ZodBoolean>;
+    maxHeightPx: z.ZodDefault<z.ZodNumber>;
+    currency: z.ZodDefault<z.ZodString>;
+    csv: z.ZodDefault<z.ZodBoolean>;
+    wide: z.ZodOptional<z.ZodBoolean>;
+    dataKey: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type TableParams = z.infer<typeof tableSchema>;
+/** https:// or root-relative only; `//host` (protocol-relative) is NOT safe
+ * because the browser fills the page's scheme — treat it as external junk. */
+export declare function isSafeUrl(u: unknown): boolean;
+export type Tone = "good" | "warn" | "bad";
+/** Solid tone chips only: per DESIGN.md's measured contrast table, soft and
+ * outline chip variants fail AA on several tones in light themes, while
+ * solid clears AA on every tone in both themes. */
+export declare const TONE_CLASS: Record<Tone, string>;
+export declare const NUMERIC_TYPES: readonly ColumnType[];
+/** Conditional tone for one cell against its column's thresholds. */
+export declare function toneForCell(col: ColumnSpec, value: CellValue): Tone | null;
+/** How one column claims horizontal space. `shrink` = content width, no
+ * wrapping. `flex` = wraps, gets `pct` of the width left after the shrink
+ * columns (the classic width:1px / width:N% table pattern), never narrower
+ * than `minRem`. */
+export type ColumnLayout = {
+    mode: "shrink";
+} | {
+    mode: "flex";
+    pct: number;
+    minRem: number;
+};
+/** Resolve every column's width (explicit hint first, then a default by
+ * column type and, for text, by the longest/average value in `rows`). */
+export declare function resolveColumnLayout(columns: ColumnSpec[], rows: Record<string, CellValue>[]): ColumnLayout[];
+/** Wide layout: explicit `wide`, else more than 4 columns. */
+export declare function isWide(params: Pick<TableParams, "wide" | "columns">): boolean;
+/** What a cell says (also what filtering and the CSV see). */
+export declare function formatCell(value: CellValue, col: ColumnSpec, currency: string): string;
+/** Sort key per column type: numbers/date numerically (missing = lowest),
+ * text case-insensitively. */
+export declare function sortValue(value: CellValue, type: ColumnType): string | number;
+/** Case-insensitive substring match across the DISPLAY value of every column. */
+export declare function filterRows(rows: Record<string, CellValue>[], columns: ColumnSpec[], query: string, currency: string): Record<string, CellValue>[];
+/** RFC-4180 CSV: quote fields containing comma/quote/newline; "" escapes ". */
+export declare function toCsv(headers: string[], rows: string[][]): string;
+/** Trigger a client-side download. No-ops (silently) where object URLs don't
+ * exist (SSR, jsdom) — tests assert on `toCsv` output instead. */
+export declare function downloadCsv(filename: string, csv: string): void;
+export {};

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

@@ -0,0 +1,278 @@
+/**
+ * Table block — params schema, cell formatting/tone logic and CSV builder.
+ *
+ * Pure functions only (no DOM) so `block.test.ts` can exercise them and
+ * `TableBlock.svelte` stays a thin render layer over jatui's DataTable.
+ *
+ * Untrusted input rules (CONTRACT.md): every string is length-capped and
+ * rendered as text (Svelte escapes it — never {@html}); link hrefs go
+ * through `isSafeUrl` (https or root-relative, never `//`-protocol-relative
+ * or any scheme). `urlSchema` NOTE: the core task (mos-bqeoa) will publish
+ * `src/lib/artifact-blocks/params.ts` with the canonical urlSchema — until it
+ * lands this folder carries this local copy and should switch to the shared
+ * one (tracked in the block task's review signal).
+ */
+import { z } from "zod";
+export const COLUMN_TYPES = [
+    "text",
+    "number",
+    "percent",
+    "currency",
+    "date",
+    "badge",
+    "link",
+];
+export const MAX_ROWS = 5000;
+export const MAX_COLUMNS = 24;
+/** Named column-width hints; `auto` shrinks the column to its content. */
+const WIDTH_HINTS = ["xs", "sm", "md", "lg", "auto"];
+const columnSchema = z.object({
+    key: z.string().min(1).max(80),
+    label: z.string().min(1).max(80),
+    type: z.enum(COLUMN_TYPES).default("text"),
+    /** Threshold tone direction (numeric columns): is a high value good? */
+    direction: z.enum(["highIsGood", "lowIsGood"]).default("highIsGood"),
+    /** Tone thresholds — both set: good/warn bands + bad remainder; only
+     * `warn`: at/past warn = warn, beyond = bad; only `good`: good or neutral. */
+    good: z.number().finite().optional(),
+    warn: z.number().finite().optional(),
+    /** badge columns: exact value → tone chips. */
+    tones: z
+        .array(z.object({
+        value: z.string().max(80),
+        tone: z.enum(["good", "warn", "bad"]),
+    }))
+        .max(50)
+        .optional(),
+    /** link columns: row key that holds the URL (default: the cell value). */
+    hrefKey: z.string().max(80).optional(),
+    /** Width hint: xs|sm|md|lg (text that wraps, growing share of the free
+     * width), auto (shrink to content, never wraps) or a number = fr weight
+     * (0.5-12). Omitted: badge/number/date/link columns and short text shrink
+     * to content; long text columns share the rest by length. */
+    width: z
+        .union([z.enum(WIDTH_HINTS), z.number().finite().min(0.5).max(12)])
+        .optional(),
+});
+export const tableSchema = z.object({
+    title: z.string().max(200).optional(),
+    columns: z.array(columnSchema).min(1).max(MAX_COLUMNS),
+    rows: z
+        .array(z.record(z.string(), z.union([
+        z.string().max(500),
+        z.number().finite(),
+        z.boolean(),
+        z.null(),
+    ])))
+        .min(1)
+        .max(MAX_ROWS),
+    /** Rows per page (pagination lives at 50 by default; hard cap 200). */
+    pageSize: z.number().int().min(5).max(200).default(50),
+    filterable: z.boolean().default(true),
+    /** Sticky header needs its own scroller — height in px (120–2000). */
+    maxHeightPx: z.number().int().min(120).max(2000).default(420),
+    /** ISO 4217 code used when a column type is "currency". */
+    currency: z
+        .string()
+        .regex(/^[A-Za-z]{3}$/)
+        .default("USD"),
+    /** Offer the CSV download button. */
+    csv: z.boolean().default(true),
+    /** Break out of the page's reading column to the full viewport width
+     * (capped). Default: on when the table has more than 4 columns. */
+    wide: z.boolean().optional(),
+    /** Phase-3 live data: key into ctx.data whose value replaces params. */
+    dataKey: z.string().max(80).optional(),
+});
+// ── URLs (local urlSchema until core params.ts lands) ─────────────────────
+/** https:// or root-relative only; `//host` (protocol-relative) is NOT safe
+ * because the browser fills the page's scheme — treat it as external junk. */
+export function isSafeUrl(u) {
+    if (typeof u !== "string" || u.length === 0 || u.length > 2048)
+        return false;
+    if (u.startsWith("//"))
+        return false;
+    if (u.startsWith("/"))
+        return true;
+    return /^https:\/\//.test(u);
+}
+/** Solid tone chips only: per DESIGN.md's measured contrast table, soft and
+ * outline chip variants fail AA on several tones in light themes, while
+ * solid clears AA on every tone in both themes. */
+export const TONE_CLASS = {
+    good: "badge-success",
+    warn: "badge-warning",
+    bad: "badge-error",
+};
+export const NUMERIC_TYPES = [
+    "number",
+    "percent",
+    "currency",
+];
+/** Conditional tone for one cell against its column's thresholds. */
+export function toneForCell(col, value) {
+    if (col.type === "badge") {
+        const hit = col.tones?.find((t) => t.value === String(value));
+        return hit?.tone ?? null;
+    }
+    if (!NUMERIC_TYPES.includes(col.type))
+        return null;
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return null;
+    const { good, warn, direction } = col;
+    const above = direction === "highIsGood";
+    if (good !== undefined && warn !== undefined) {
+        if (above)
+            return value >= good ? "good" : value >= warn ? "warn" : "bad";
+        return value <= good ? "good" : value <= warn ? "warn" : "bad";
+    }
+    if (good !== undefined)
+        return (above ? value >= good : value <= good) ? "good" : null;
+    if (warn !== undefined)
+        return (above ? value >= warn : value <= warn) ? "warn" : "bad";
+    return null;
+}
+const HINT_FLEX = {
+    xs: [1, 5],
+    sm: [2, 8],
+    md: [3, 11],
+    lg: [4, 14],
+};
+/** Text no longer than this stays on one line and sizes to content. */
+const SHORT_TEXT_CHARS = 28;
+/** Resolve every column's width (explicit hint first, then a default by
+ * column type and, for text, by the longest/average value in `rows`). */
+export function resolveColumnLayout(columns, rows) {
+    const weights = columns.map((c) => {
+        const w = c.width;
+        if (w === "auto")
+            return null;
+        if (typeof w === "number")
+            return [w, 8];
+        if (w)
+            return HINT_FLEX[w];
+        if (c.type !== "text")
+            return null;
+        let max = 0;
+        let total = 0;
+        for (const r of rows) {
+            const len = String(r[c.key] ?? "").length;
+            if (len > max)
+                max = len;
+            total += len;
+        }
+        if (max <= SHORT_TEXT_CHARS)
+            return null;
+        const avg = rows.length ? total / rows.length : 0;
+        return HINT_FLEX[avg < 40 ? "sm" : avg < 100 ? "md" : "lg"];
+    });
+    const sum = weights.reduce((a, w) => a + (w ? w[0] : 0), 0);
+    return weights.map((w) => w
+        ? {
+            mode: "flex",
+            pct: Math.round((w[0] / sum) * 1000) / 10,
+            minRem: w[1],
+        }
+        : { mode: "shrink" });
+}
+/** Wide layout: explicit `wide`, else more than 4 columns. */
+export function isWide(params) {
+    return params.wide ?? params.columns.length > 4;
+}
+// ── Display formatting ────────────────────────────────────────────────────
+function parseDateValue(value) {
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : null;
+    if (typeof value !== "string")
+        return null;
+    const m = /^(\d{4})-(\d{2})(?:-(\d{2}))?$/.exec(value.trim());
+    if (m) {
+        const d = new Date(Number(m[1]), Number(m[2]) - 1, m[3] ? Number(m[3]) : 1);
+        return Number.isFinite(d.getTime()) ? d.getTime() : null;
+    }
+    const ms = new Date(value).getTime();
+    return Number.isFinite(ms) ? ms : null;
+}
+/** What a cell says (also what filtering and the CSV see). */
+export function formatCell(value, col, currency) {
+    if (value === null || value === undefined || value === "")
+        return "n/a";
+    switch (col.type) {
+        case "number":
+            return typeof value === "number"
+                ? new Intl.NumberFormat("en-US", { maximumFractionDigits: 2 }).format(value)
+                : String(value);
+        case "percent":
+            return typeof value === "number"
+                ? `${new Intl.NumberFormat("en-US", { maximumFractionDigits: 2 }).format(value)}%`
+                : String(value);
+        case "currency":
+            return typeof value === "number"
+                ? new Intl.NumberFormat("en-US", {
+                    style: "currency",
+                    currency,
+                    maximumFractionDigits: 2,
+                }).format(value)
+                : String(value);
+        case "date": {
+            const ms = parseDateValue(value);
+            return ms === null
+                ? String(value)
+                : new Intl.DateTimeFormat("en-US", {
+                    year: "numeric",
+                    month: "short",
+                    day: "numeric",
+                }).format(ms);
+        }
+        default:
+            return String(value);
+    }
+}
+// ── Sort ──────────────────────────────────────────────────────────────────
+/** Sort key per column type: numbers/date numerically (missing = lowest),
+ * text case-insensitively. */
+export function sortValue(value, type) {
+    if (type === "date")
+        return parseDateValue(value) ?? Number.NEGATIVE_INFINITY;
+    if (NUMERIC_TYPES.includes(type))
+        return typeof value === "number" && Number.isFinite(value)
+            ? value
+            : Number.NEGATIVE_INFINITY;
+    return String(value ?? "").toLowerCase();
+}
+// ── Filtering ─────────────────────────────────────────────────────────────
+/** Case-insensitive substring match across the DISPLAY value of every column. */
+export function filterRows(rows, columns, query, currency) {
+    const needle = query.trim().toLowerCase();
+    if (!needle)
+        return rows;
+    return rows.filter((r) => columns.some((c) => formatCell(r[c.key] ?? null, c, currency)
+        .toLowerCase()
+        .includes(needle)));
+}
+// ── CSV ───────────────────────────────────────────────────────────────────
+/** RFC-4180 CSV: quote fields containing comma/quote/newline; "" escapes ". */
+export function toCsv(headers, rows) {
+    const esc = (v) => /[",\n\r]/.test(v) ? `"${v.replace(/"/g, '""')}"` : v;
+    return [headers, ...rows]
+        .map((r) => r.map((c) => esc(c ?? "")).join(","))
+        .join("\r\n");
+}
+/** Trigger a client-side download. No-ops (silently) where object URLs don't
+ * exist (SSR, jsdom) — tests assert on `toCsv` output instead. */
+export function downloadCsv(filename, csv) {
+    if (typeof document === "undefined")
+        return;
+    if (typeof URL.createObjectURL !== "function")
+        return;
+    // BOM so Excel opens UTF-8 correctly.
+    const blob = new Blob(["\uFEFF" + csv], { type: "text/csv;charset=utf-8" });
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement("a");
+    a.href = url;
+    a.download = filename;
+    document.body.appendChild(a);
+    a.click();
+    a.remove();
+    URL.revokeObjectURL(url);
+}