@joewinke/jatui 0.37.0 → 0.38.0

package/dist/artifact-blocks/blocks/table/TableBlock.svelte

@@ -0,0 +1,490 @@
+<script lang="ts">
+  /**
+   * TableBlock — jatui DataTable renderer (block type "table").
+   *
+   * Typed columns (text/number/percent/currency/date/badge/link), sort,
+   * filter box, pagination (50/page), sticky header, CSV download and
+   * conditional good/warn/bad tone per cell.
+   *
+   * Numeric columns (number/percent/currency) are right-aligned with tabular
+   * numerals, header included. Their tone is a small coloured dot beside a
+   * PLAIN number (campaign-blocks Gate A, J3): a column of solid red/amber/
+   * green chips was the loudest thing on the page. The tone is also spelled
+   * out for screen readers and in the dot's title. Badge-type columns keep
+   * SOLID chips for toned values (DESIGN.md: solid is the only chip variant
+   * that clears AA on every tone) and the quiet ghost chip otherwise.
+   *
+   * Column widths (mos-8cbma): `resolveColumnLayout` sorts each column into
+   * shrink (badge/number/date/link and short text: content width, never
+   * wraps) or flex (long text: wraps, shares the remaining width by weight,
+   * floored at a min width). The percentages ride CSS vars onto the header
+   * cells (`th:nth-child`) because DataTable takes only a class per header.
+   * More than 4 columns breaks out of the reading column (`wide`); when the
+   * table still overflows, the scroller shows an edge fade + a hint.
+   *
+   * Params are parsed through the schema here (defaults + corrupt-params →
+   * empty state), same contract as ChartBlock.
+   */
+  import { DataTable, type ColumnDef, type SortingState } from "../../../components/table/index.js"
+  import type { CellContext } from "@tanstack/table-core"
+  import type { Snippet } from "svelte"
+  import type { BlockProps } from "../../types.js"
+  import {
+    tableSchema,
+    toneForCell,
+    TONE_CLASS,
+    formatCell,
+    sortValue,
+    filterRows,
+    toCsv,
+    downloadCsv,
+    isSafeUrl,
+    resolveColumnLayout,
+    isWide,
+    NUMERIC_TYPES,
+    type ColumnLayout,
+    type ColumnSpec,
+    type TableParams,
+    type CellValue,
+  } from "./schema.js"
+  import SectionTools from "../../SectionTools.svelte"
+
+  let { params: rawParams, ctx }: BlockProps<TableParams> = $props()
+
+  /** Parsed params (defaults filled); corrupt params → empty state. */
+  const EMPTY_PARAMS: TableParams = {
+    columns: [],
+    rows: [],
+    pageSize: 50,
+    filterable: true,
+    maxHeightPx: 420,
+    currency: "USD",
+    csv: true,
+  }
+  const parsed = $derived(tableSchema.safeParse(rawParams))
+  const params = $derived(parsed.success ? parsed.data : EMPTY_PARAMS)
+
+  type Row = Record<string, CellValue>
+
+  const layout = $derived(resolveColumnLayout(params.columns, params.rows))
+  const layoutByKey = $derived(
+    new Map(params.columns.map((c, i) => [c.key, layout[i]])),
+  )
+  const wide = $derived(isWide(params))
+  /** Per-column header width as CSS vars (consumed by th:nth-child rules). */
+  const widthVars = $derived(
+    layout
+      .map(
+        (l: ColumnLayout, i) =>
+          `--tbw-${i + 1}: ${l.mode === "flex" ? `${l.pct}%` : "1px"}`,
+      )
+      .join("; "),
+  )
+  function flexMin(key: string): string | undefined {
+    const l = layoutByKey.get(key)
+    return l?.mode === "flex" ? `${l.minRem}rem` : undefined
+  }
+
+  // Horizontal overflow is the last resort; when it happens, say so.
+  let figureEl = $state<HTMLElement>()
+  let overflowX = $state(false)
+  let atEnd = $state(false)
+  $effect(() => {
+    void params.columns.length
+    const sc = figureEl?.querySelector<HTMLElement>(
+      ".dt-scroller, .overflow-x-auto",
+    )
+    if (!sc) return
+    const measure = () => {
+      overflowX = sc.scrollWidth > sc.clientWidth + 1
+      atEnd = sc.scrollLeft + sc.clientWidth >= sc.scrollWidth - 1
+    }
+    measure()
+    sc.addEventListener("scroll", measure, { passive: true })
+    const ro =
+      typeof ResizeObserver === "function" ? new ResizeObserver(measure) : null
+    ro?.observe(sc)
+    const tbl = sc.querySelector("table")
+    if (tbl) ro?.observe(tbl)
+    return () => {
+      sc.removeEventListener("scroll", measure)
+      ro?.disconnect()
+    }
+  })
+
+  let q = $state("")
+  let sorting = $state<SortingState>([])
+
+  const filtered = $derived.by(() => {
+    if (!q.trim()) return params.rows
+    return filterRows(params.rows, params.columns, q, params.currency)
+  })
+
+  // CSV exports what the viewer sees: filtered, in the current sort, display
+  // formatting (the table is the source of truth for the reader).
+  const csvRows = $derived.by(() => {
+    const sorted = applySort(filtered)
+    return sorted.map((r) =>
+      params.columns.map((c) =>
+        formatCell(r[c.key] ?? null, c, params.currency),
+      ),
+    )
+  })
+  function applySort(rows: Row[]): Row[] {
+    if (!sorting.length) return rows
+    const [{ id, desc }] = sorting
+    const col = params.columns.find((c) => c.key === id)
+    if (!col) return rows
+    const sorted = [...rows].sort((a, b) => {
+      const av = sortValue(a[col.key] ?? null, col.type)
+      const bv = sortValue(b[col.key] ?? null, col.type)
+      if (av < bv) return -1
+      if (av > bv) return 1
+      return 0
+    })
+    return desc ? sorted.reverse() : sorted
+  }
+  function exportCsv() {
+    const name = (params.title ?? "data")
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      .slice(0, 60)
+    downloadCsv(
+      `${name || "data"}.csv`,
+      toCsv(
+        params.columns.map((c) => c.label),
+        csvRows,
+      ),
+    )
+  }
+
+  /** Dot colour + spoken word per tone (numeric cells). */
+  const TONE_DOT = {
+    good: "bg-success",
+    warn: "bg-warning",
+    bad: "bg-error",
+  } as const
+  const TONE_WORD = { good: "good", warn: "watch", bad: "bad" } as const
+
+  function isNumeric(id: string): boolean {
+    const c = params.columns.find((col) => col.key === id)
+    return !!c && NUMERIC_TYPES.includes(c.type)
+  }
+  /** Shrink-column headers never wrap (the label sets the floor width);
+   * flex-column headers may wrap rather than widen a text column; numeric
+   * headers align with their right-aligned values. */
+  function headerProps(id: string) {
+    const flex = layoutByKey.get(id)?.mode === "flex"
+    return {
+      class: `${flex ? "" : "whitespace-nowrap"}${isNumeric(id) ? " text-right" : ""}`,
+    }
+  }
+
+  // ── Column defs for the DataTable ────────────────────────────────────────
+  function metaOf(c: ColumnSpec): { col: ColumnSpec } {
+    return { col: c }
+  }
+  type CellCtx = CellContext<Row, unknown>
+  function colOf(context: CellCtx): ColumnSpec {
+    return (context.column.columnDef.meta as { col: ColumnSpec }).col
+  }
+  function cellFor(type: ColumnSpec["type"]): Snippet<[CellCtx]> {
+    switch (type) {
+      case "number":
+      case "percent":
+      case "currency":
+        return numCell
+      case "date":
+        return dateCell
+      case "badge":
+        return badgeCell
+      case "link":
+        return linkCell
+      default:
+        return textCell
+    }
+  }
+
+  const columns = $derived(
+    params.columns.map((c) => {
+      const col = c
+      const def: ColumnDef<Row, unknown> = {
+        id: col.key,
+        header: col.label,
+        accessorFn: (r) => sortValue(r[col.key] ?? null, col.type),
+        meta: metaOf(col),
+        cell: () => cellFor(col.type),
+      }
+      return def
+    }),
+  )
+</script>
+
+{#snippet textCell(context: CellCtx)}
+  {@const col = colOf(context)}
+  {@const v = context.row.original[col.key] ?? null}
+  {@const min = flexMin(col.key)}
+  <span
+    class="{v === null || v === '' ? 'text-base-content/50' : ''} {params
+      .columns[0]?.key === col.key
+      ? 'font-medium'
+      : ''} {min ? 'block break-words' : 'whitespace-nowrap'}"
+    style:min-width={min}
+  >
+    {formatCell(v, col, params.currency)}
+  </span>
+{/snippet}
+
+{#snippet numCell(context: CellCtx)}
+  {@const col = colOf(context)}
+  {@const v = context.row.original[col.key] ?? null}
+  {@const tone = toneForCell(col, v)}
+  {@const label = formatCell(v, col, params.currency)}
+  <span
+    class="flex items-center justify-end gap-1.5 whitespace-nowrap tabular-nums"
+    data-tone={tone ?? undefined}
+  >
+    {#if tone}
+      <span
+        class="size-2 shrink-0 rounded-full {TONE_DOT[tone]}"
+        title={TONE_WORD[tone]}
+        aria-hidden="true"
+      ></span>
+    {/if}
+    <span class={v === null ? "text-base-content/50" : ""}>{label}</span>
+    {#if tone}<span class="sr-only">({TONE_WORD[tone]})</span>{/if}
+  </span>
+{/snippet}
+
+{#snippet dateCell(context: CellCtx)}
+  {@const col = colOf(context)}
+  {@const v = context.row.original[col.key] ?? null}
+  <span class="whitespace-nowrap tabular-nums">
+    {formatCell(v, col, params.currency)}
+  </span>
+{/snippet}
+
+{#snippet badgeCell(context: CellCtx)}
+  {@const col = colOf(context)}
+  {@const v = context.row.original[col.key] ?? null}
+  {@const tone = toneForCell(col, v)}
+  {#if v === null || v === ""}
+    <span class="text-base-content/50">n/a</span>
+  {:else if tone}
+    <span class="badge badge-sm whitespace-nowrap {TONE_CLASS[tone]}"
+      >{formatCell(v, col, params.currency)}</span
+    >
+  {:else}
+    <span class="badge badge-sm badge-ghost whitespace-nowrap"
+      >{formatCell(v, col, params.currency)}</span
+    >
+  {/if}
+{/snippet}
+
+{#snippet linkCell(context: CellCtx)}
+  {@const col = colOf(context)}
+  {@const row = context.row.original}
+  {@const raw = col.hrefKey ? row[col.hrefKey] : row[col.key]}
+  {@const url = typeof raw === "string" && isSafeUrl(raw) ? raw : null}
+  {#if url && /^https:\/\//i.test(url)}
+    <a
+      class="link link-hover font-medium whitespace-nowrap"
+      href={url}
+      target="_blank"
+      rel="noopener noreferrer"
+      >{formatCell(row[col.key] ?? null, col, params.currency)}<span
+        class="sr-only"
+      >
+        (opens in a new tab)</span
+      ></a
+    >
+  {:else if url}
+    <a class="link link-hover font-medium whitespace-nowrap" href={url}
+      >{formatCell(row[col.key] ?? null, col, params.currency)}</a
+    >
+  {:else}
+    <span class="text-base-content/50"
+      >{formatCell(row[col.key] ?? null, col, params.currency)}</span
+    >
+  {/if}
+{/snippet}
+
+<figure
+  bind:this={figureEl}
+  class="tb-root @container w-full"
+  class:tb-wide={wide}
+  data-block-type="table"
+  data-wide={wide ? "" : undefined}
+  style={widthVars}
+>
+  <figcaption class="mb-2 flex flex-wrap items-center gap-x-3 gap-y-2">
+    <div class="flex min-w-0 flex-1 items-center gap-2 @md:flex-none">
+      {#if params.title}
+        <h2 class="text-sm font-semibold text-base-content">{params.title}</h2>
+      {/if}
+      <span class="text-xs tabular-nums text-base-content/70">
+        {filtered.length} row{filtered.length === 1 ? "" : "s"}
+      </span>
+      {#if params.title}
+        <SectionTools {ctx} inline />
+      {/if}
+    </div>
+    <div class="flex w-full items-center gap-2 @md:ml-auto @md:w-auto">
+      {#if params.filterable}
+        <input
+          type="search"
+          class="input input-sm input-bordered min-w-0 flex-1 @md:w-56 @md:flex-none"
+          aria-label="Filter rows"
+          placeholder="Filter rows"
+          bind:value={q}
+        />
+      {/if}
+      {#if params.csv}
+        <button
+          type="button"
+          class="btn btn-ghost btn-sm shrink-0 gap-1.5"
+          onclick={exportCsv}
+        >
+          <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.25" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 15V3" /><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" /><path d="m7 10 5 5 5-5" /></svg>
+          Download CSV
+        </button>
+      {/if}
+    </div>
+  </figcaption>
+
+  {#if params.columns.length === 0 || params.rows.length === 0}
+    <p
+      class="rounded-box border border-dashed border-base-content/15 px-4 py-6 text-center text-sm text-base-content/70"
+    >
+      No data yet.
+    </p>
+  {:else}
+    <div class="relative">
+      <DataTable
+        data={filtered}
+        {columns}
+        sortable
+        bind:sorting
+        paginated
+        pageSize={params.pageSize}
+        stickyHeader
+        maxHeight={`${params.maxHeightPx}px`}
+        variant="plain"
+        {headerProps}
+      >
+        {#snippet empty()}
+          <div class="p-4 text-sm text-base-content/70">
+            No rows match "{q.trim()}".
+            <button
+              type="button"
+              class="link link-hover ml-1"
+              onclick={() => (q = "")}>Clear the filter</button
+            >
+          </div>
+        {/snippet}
+      </DataTable>
+      {#if overflowX && !atEnd}
+        <div
+          class="pointer-events-none absolute inset-y-0 right-0 w-8 bg-gradient-to-l from-base-100 to-transparent"
+          aria-hidden="true"
+        ></div>
+      {/if}
+    </div>
+    {#if overflowX}
+      <p class="mt-1 text-xs text-base-content/70" data-scroll-hint>
+        Scroll sideways for more columns
+        <span aria-hidden="true">&rarr;</span>
+      </p>
+    {/if}
+  {/if}
+</figure>
+
+<style>
+  /* Wide layout: break out of the artifact page's reading column, centred
+     on it, capped at 80rem and kept 1.5rem inside the page view
+     (--artifact-page-w is that view's measured width, not the viewport's,
+     so an admin sidebar host stays correct). Only that page opts in;
+     pinned/embedded hosts keep the block in its column. Never narrower than
+     the column it sits in. */
+  :global([data-artifact-page]) .tb-wide {
+    --tb-w: max(100%, min(var(--artifact-page-w, 100%) - 3rem, 80rem));
+    width: var(--tb-w);
+    margin-inline: calc((100% - var(--tb-w)) / 2);
+  }
+  /* Column widths from resolveColumnLayout (shrink = 1px + nowrap content,
+     flex = its share in %). DataTable only takes a class per header, so the
+     values arrive as --tbw-N vars on the figure. MAX_COLUMNS = 24. */
+  .tb-root :global(thead th:nth-child(1)) {
+    width: var(--tbw-1);
+  }
+  .tb-root :global(thead th:nth-child(2)) {
+    width: var(--tbw-2);
+  }
+  .tb-root :global(thead th:nth-child(3)) {
+    width: var(--tbw-3);
+  }
+  .tb-root :global(thead th:nth-child(4)) {
+    width: var(--tbw-4);
+  }
+  .tb-root :global(thead th:nth-child(5)) {
+    width: var(--tbw-5);
+  }
+  .tb-root :global(thead th:nth-child(6)) {
+    width: var(--tbw-6);
+  }
+  .tb-root :global(thead th:nth-child(7)) {
+    width: var(--tbw-7);
+  }
+  .tb-root :global(thead th:nth-child(8)) {
+    width: var(--tbw-8);
+  }
+  .tb-root :global(thead th:nth-child(9)) {
+    width: var(--tbw-9);
+  }
+  .tb-root :global(thead th:nth-child(10)) {
+    width: var(--tbw-10);
+  }
+  .tb-root :global(thead th:nth-child(11)) {
+    width: var(--tbw-11);
+  }
+  .tb-root :global(thead th:nth-child(12)) {
+    width: var(--tbw-12);
+  }
+  .tb-root :global(thead th:nth-child(13)) {
+    width: var(--tbw-13);
+  }
+  .tb-root :global(thead th:nth-child(14)) {
+    width: var(--tbw-14);
+  }
+  .tb-root :global(thead th:nth-child(15)) {
+    width: var(--tbw-15);
+  }
+  .tb-root :global(thead th:nth-child(16)) {
+    width: var(--tbw-16);
+  }
+  .tb-root :global(thead th:nth-child(17)) {
+    width: var(--tbw-17);
+  }
+  .tb-root :global(thead th:nth-child(18)) {
+    width: var(--tbw-18);
+  }
+  .tb-root :global(thead th:nth-child(19)) {
+    width: var(--tbw-19);
+  }
+  .tb-root :global(thead th:nth-child(20)) {
+    width: var(--tbw-20);
+  }
+  .tb-root :global(thead th:nth-child(21)) {
+    width: var(--tbw-21);
+  }
+  .tb-root :global(thead th:nth-child(22)) {
+    width: var(--tbw-22);
+  }
+  .tb-root :global(thead th:nth-child(23)) {
+    width: var(--tbw-23);
+  }
+  .tb-root :global(thead th:nth-child(24)) {
+    width: var(--tbw-24);
+  }
+</style>

package/dist/artifact-blocks/blocks/table/TableBlock.svelte.d.ts

@@ -0,0 +1,28 @@
+import type { BlockProps } from "../../types.js";
+declare const TableBlock: import("svelte").Component<BlockProps<{
+    columns: {
+        key: string;
+        label: string;
+        type: "number" | "date" | "link" | "text" | "badge" | "currency" | "percent";
+        direction: "highIsGood" | "lowIsGood";
+        good?: number | undefined;
+        warn?: number | undefined;
+        tones?: {
+            value: string;
+            tone: "warn" | "good" | "bad";
+        }[] | undefined;
+        hrefKey?: string | undefined;
+        width?: number | "auto" | "md" | "lg" | "xs" | "sm" | undefined;
+    }[];
+    rows: Record<string, string | number | boolean | null>[];
+    pageSize: number;
+    filterable: boolean;
+    maxHeightPx: number;
+    currency: string;
+    csv: boolean;
+    title?: string | undefined;
+    wide?: boolean | undefined;
+    dataKey?: string | undefined;
+}>, {}, "">;
+type TableBlock = ReturnType<typeof TableBlock>;
+export default TableBlock;

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

@@ -0,0 +1,9 @@
+/**
+ * Table block definition (block type "table").
+ * 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 TableParams } from "./schema.js";
+declare const def: ArtifactBlockDef<TableParams>;
+export default def;

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

@@ -0,0 +1,100 @@
+import { isWide, tableSchema } from "./schema.js";
+import TableBlock from "./TableBlock.svelte";
+const def = {
+    type: "table",
+    title: "Table",
+    description: "Sortable, filterable, paginated data table (jatui DataTable) for records " +
+        "and detail — the companion to the chart block (a chart for shape, a table " +
+        "for exact values; don't pair them to show the SAME series twice). columns: " +
+        "{key, label, type} where type is text | number | percent | currency | date | " +
+        "badge | link — number/percent/currency align right and sort numerically, date " +
+        "accepts ISO dates ('2026-01-15', or epoch ms), badge renders a chip (optionally " +
+        "toned via tones: [{value, tone}]), link renders an anchor from the cell value " +
+        "or the row's hrefKey field (https:// or root-relative ONLY — anything else " +
+        "renders as plain text). Conditional tone: give a numeric column good/warn " +
+        "thresholds plus direction (highIsGood default) and cells past them render as " +
+        "solid good/warn/bad chips — e.g. {good: 90, warn: 70} on highIsGood, or " +
+        "{good: 2, warn: 5, direction: 'lowIsGood'} for latency. Rows are objects keyed " +
+        "by column key; caps 5000 rows × 24 columns, page size max 200 (default 50). " +
+        "Sorting, the filter box (substring over display values), sticky header and the " +
+        "CSV download (exports the filtered rows in the current sort) are built in. " +
+        "percent values are 0-100 (81.5 renders 81.5%), not 0-1 fractions. " +
+        "Column widths: badge/number/date/link columns and short text (<= 28 chars) " +
+        "shrink to their content and never wrap; long text columns wrap and share the " +
+        "remaining width by length. Override per column with width: 'xs' | 'sm' | 'md' | " +
+        "'lg' (wrapping text, growing share) | 'auto' (shrink to content) | a number " +
+        "(fr weight 0.5-12). A table with more than 4 columns widens past the page's " +
+        "reading column (set wide: false to keep it in the column, true to force it). " +
+        "Tip: put the identifying column first and keep labels short — the header sticks " +
+        "while 50 rows scroll.",
+    schema: tableSchema,
+    component: TableBlock,
+    // mos-8fvt9: the section's Listen + comment sit on the heading row.
+    hostsTools: (p) => Boolean(p.title),
+    // The wide breakout (isWide — `wide` param, else >4 columns) is ALSO the
+    // renderer's cue to break out the per-block comment trigger above this
+    // block, so the pill aligns with the table's actual right edge (mos-51g8l).
+    wide: isWide,
+    example: {
+        title: "Invoice aging",
+        currency: "USD",
+        columns: [
+            { key: "invoice", label: "Invoice", type: "link", hrefKey: "url" },
+            { key: "customer", label: "Customer", type: "text" },
+            { key: "amount", label: "Amount", type: "currency" },
+            { key: "due", label: "Due", type: "date" },
+            {
+                key: "days",
+                label: "Days overdue",
+                type: "number",
+                direction: "lowIsGood",
+                good: 5,
+                warn: 30,
+            },
+            {
+                key: "status",
+                label: "Status",
+                type: "badge",
+                tones: [
+                    { value: "overdue", tone: "bad" },
+                    { value: "current", tone: "good" },
+                ],
+            },
+        ],
+        rows: [
+            {
+                invoice: "INV-1042",
+                customer: "Northwind Tractors",
+                amount: 12450.5,
+                due: "2026-09-14",
+                days: 42,
+                status: "overdue",
+                url: "/admin/billing/invoices/INV-1042",
+            },
+            {
+                invoice: "INV-1043",
+                customer: "Blue Harbor Cafe",
+                amount: 830,
+                due: "2026-10-02",
+                days: 6,
+                status: "current",
+                url: "/admin/billing/invoices/INV-1043",
+            },
+            {
+                invoice: "INV-1044",
+                customer: "Ridgeline Dental",
+                amount: 2210,
+                due: "2026-10-11",
+                days: 0,
+                status: "sent",
+                url: "/admin/billing/invoices/INV-1044",
+            },
+        ],
+        pageSize: 50,
+        filterable: true,
+        maxHeightPx: 420,
+        csv: true,
+    },
+    dataParam: "dataKey",
+};
+export default def;