@sigrun/tui 0.4.1 → 0.5.0

package/dist/blocks/chat-transport.js

@@ -0,0 +1,116 @@
+/**
+ * The TUI's chat-block transport (UI-blocks U5 Task 4, spec §8.2): the
+ * shared `SurfaceTransport` contract over the chat-block routes
+ * (`/v1/conversations/:id/blocks/:entryId`, `…/data?since=`, `POST
+ * …/actions`) — the port of the webui's `chatTransport.ts`, addressed
+ * by (conversationId, entryId) instead of (slug, id, params).
+ *
+ * Unlike the TUI's ext transport there is no `X-Sigrun-Stream` watcher
+ * registration: chat change events are conversation-scoped (the events
+ * route delivers them to every stream whose principal sees the
+ * conversation), so `setStreamId` does not exist here. The launcher's
+ * events loop hands the conversation-scoped frames to
+ * {@link ChatSurfaceHub.dispatch}.
+ */
+import { SigrunApiError } from "../api.js";
+/** The base path of one chat block (`/data` and `/actions` hang off it). */
+function blockPath(options) {
+    return `/v1/conversations/${options.conversationId}/blocks/${encodeURIComponent(options.entryId)}`;
+}
+/** Create the TUI's chat-block transport. */
+export function createChatTransport(options) {
+    const doFetch = options.fetch ??
+        ((input, init) => globalThis.fetch(input, init));
+    const baseUrl = options.baseUrl.replace(/\/+$/, "");
+    const listeners = new Set();
+    const headers = () => ({
+        accept: "application/json",
+        ...(options.user === undefined || options.user.trim() === ""
+            ? {}
+            : { "x-sigrun-user": options.user.trim() }),
+        ...(options.token === undefined || options.token.trim() === ""
+            ? {}
+            : { authorization: `Bearer ${options.token.trim()}` }),
+    });
+    const get = async (path) => {
+        const response = await doFetch(`${baseUrl}${path}`, {
+            method: "GET",
+            headers: headers(),
+        });
+        if (!response.ok) {
+            throw new SigrunApiError("GET", path, response.status, await response.json().catch(() => undefined));
+        }
+        return (await response.json());
+    };
+    return {
+        load() {
+            return get(blockPath(options));
+        },
+        fetchData(since) {
+            const base = `${blockPath(options)}/data`;
+            return get(since === undefined ? base : `${base}?since=${String(since)}`);
+        },
+        async act(body) {
+            const response = await doFetch(`${baseUrl}${blockPath(options)}/actions`, {
+                method: "POST",
+                headers: { ...headers(), "content-type": "application/json" },
+                body: JSON.stringify(body),
+            });
+            return (await response.json());
+        },
+        upload() {
+            // Chat trees forbid upload fields (spec §8.2); reject loudly.
+            return Promise.reject(new Error("chat blocks carry no upload fields"));
+        },
+        image() {
+            return Promise.reject(new Error("chat block image route ships with U7"));
+        },
+        onChanged(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+    };
+}
+/**
+ * The TUI's chat-block change router: `attach` creates a transport whose
+ * `onChanged` subscribes into this hub under (conversationId, entryId);
+ * `dispatch` fans a conversation-scoped `surface.changed` frame out to
+ * the matching subscriptions only.
+ */
+export class ChatSurfaceHub {
+    #subscriptions = new Set();
+    /** Create a transport whose `onChanged` subscribes into this hub. */
+    attach(options) {
+        const base = createChatTransport(options);
+        const hub = this;
+        return {
+            load: () => base.load(),
+            fetchData: (since) => base.fetchData(since),
+            act: (body) => base.act(body),
+            upload: (body) => base.upload(body),
+            image: (src, opts) => base.image(src, opts),
+            onChanged(listener) {
+                const subscription = {
+                    conversationId: options.conversationId,
+                    entryId: options.entryId,
+                    listener,
+                };
+                hub.#subscriptions.add(subscription);
+                return () => {
+                    hub.#subscriptions.delete(subscription);
+                };
+            },
+        };
+    }
+    /** Fire every subscription matching the event's (conversationId, entryId). */
+    dispatch(event) {
+        for (const subscription of this.#subscriptions) {
+            if (subscription.conversationId === event.conversationId &&
+                subscription.entryId === event.entryId) {
+                subscription.listener({ rev: event.rev, treeRev: event.treeRev ?? 0 });
+            }
+        }
+    }
+}

package/dist/blocks/collection/calendar.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The `calendar` display (UI-blocks U2 Task 4, spec §5.5 + §12.3 +
+ * §12.4): a month grid at regular/wide (day-rows — the same v1 shape
+ * as U1's grid, not a weekday-aligned matrix); compact shows the
+ * agenda (§12.3), as does `time.range: "agenda"` at any width.
+ *
+ * Keyboard (§12.4): `[`/`]` shift the visible month, `t` returns to
+ * today — all view-only, nothing dispatches. `m` on an event picks it
+ * up; arrows move it by DAY; Enter drops, dispatching `onMove` with
+ * `{itemId, to: {start, end}}` — the duration preserved by shifting
+ * start AND end by the day delta (the same payload as U1's pointer
+ * drop). Esc cancels.
+ *
+ * The v1 TUI calendar has no pointer create/resize gestures (`onCreate`
+ * and `onResize` stay U1-pointer-only affordances; noted in the task
+ * report).
+ */
+import type { Component } from "@earendil-works/pi-tui";
+import type { CollectionBlock } from "@sigrun/shared/blocks";
+import type { BlockCtx } from "../context.js";
+/** The calendar display. */
+export declare class CalendarComponent implements Component {
+    #private;
+    constructor(block: CollectionBlock, ctx: BlockCtx);
+    render(width: number): string[];
+    handleInput(data: string): void;
+    invalidate(): void;
+}

package/dist/blocks/collection/calendar.js

@@ -0,0 +1,232 @@
+/**
+ * The `calendar` display (UI-blocks U2 Task 4, spec §5.5 + §12.3 +
+ * §12.4): a month grid at regular/wide (day-rows — the same v1 shape
+ * as U1's grid, not a weekday-aligned matrix); compact shows the
+ * agenda (§12.3), as does `time.range: "agenda"` at any width.
+ *
+ * Keyboard (§12.4): `[`/`]` shift the visible month, `t` returns to
+ * today — all view-only, nothing dispatches. `m` on an event picks it
+ * up; arrows move it by DAY; Enter drops, dispatching `onMove` with
+ * `{itemId, to: {start, end}}` — the duration preserved by shifting
+ * start AND end by the day delta (the same payload as U1's pointer
+ * drop). Esc cancels.
+ *
+ * The v1 TUI calendar has no pointer create/resize gestures (`onCreate`
+ * and `onResize` stay U1-pointer-only affordances; noted in the task
+ * report).
+ */
+import { truncate, widthClassOf } from "../width.js";
+import { cardLines } from "./card.js";
+import { CollectionState, collectionItems, dispatchActivate, sortItems, } from "./shared.js";
+/** The day key (YYYY-MM-DD) an ISO timestamp falls on. */
+function dayKey(iso) {
+    return iso.slice(0, 10);
+}
+/** Shift a day key by `days`. */
+function shiftDay(key, days) {
+    const date = new Date(`${key}T00:00:00Z`);
+    date.setUTCDate(date.getUTCDate() + days);
+    return date.toISOString().slice(0, 10);
+}
+/** Shift an ISO instant by whole days, keeping its clock time. */
+function shiftInstant(iso, days) {
+    const date = new Date(iso);
+    date.setUTCDate(date.getUTCDate() + days);
+    return date.toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+/** Today's month key (view-range default; fake timers drive tests). */
+function currentMonth() {
+    return new Date().toISOString().slice(0, 7);
+}
+/** Shift a month key by `months`. */
+function shiftMonth(key, months) {
+    const [yearRaw, monthRaw] = key.split("-");
+    const year = Number(yearRaw);
+    const month = Number(monthRaw) - 1 + months;
+    return new Date(Date.UTC(year, month, 1)).toISOString().slice(0, 7);
+}
+/** The days a month grid renders (1st through the month's end). */
+function daysInMonth(month) {
+    const [yearRaw, monthRaw] = month.split("-");
+    const year = Number(yearRaw);
+    const m = Number(monthRaw);
+    const days = [];
+    const date = new Date(Date.UTC(year, m - 1, 1));
+    while (date.getUTCMonth() === m - 1) {
+        days.push(date.toISOString().slice(0, 10));
+        date.setUTCDate(date.getUTCDate() + 1);
+    }
+    return days;
+}
+/** An item's start/end ISO strings under the block's `time` config. */
+function itemRange(block, item) {
+    const time = block.time;
+    if (time === undefined)
+        return undefined;
+    if (typeof item !== "object" || item === null || Array.isArray(item))
+        return undefined;
+    const record = item;
+    const start = record[time.start];
+    if (typeof start !== "string")
+        return undefined;
+    const end = time.end === undefined ? undefined : record[time.end];
+    return { start, end: typeof end === "string" ? end : undefined };
+}
+/** The calendar display. */
+export class CalendarComponent {
+    #block;
+    #ctx;
+    #state = new CollectionState();
+    #tick = 0;
+    /** The visible month (view-only; `[`/`]`/`t` shift it). */
+    #month = currentMonth();
+    /** The agenda cursor (a flat item index over the agenda order). */
+    #cursor = 0;
+    /** The picked-up event (calendar moves use a day placement, not the
+     *  lanes' group/index placement — the session wrapper tracks it). */
+    #held;
+    constructor(block, ctx) {
+        this.#block = block;
+        this.#ctx = ctx;
+    }
+    /** Every item with a parseable time range, in start order. */
+    #events() {
+        const rows = [];
+        for (const row of sortItems(collectionItems(this.#block, this.#ctx), this.#block.sort)) {
+            const range = itemRange(this.#block, row.item);
+            if (range === undefined)
+                continue;
+            rows.push({ row, start: range.start, end: range.end });
+        }
+        rows.sort((a, b) => a.start.localeCompare(b.start));
+        return rows;
+    }
+    render(width) {
+        this.#tick += 1;
+        const compact = widthClassOf(width) === "compact" || this.#block.time?.range === "agenda";
+        const events = this.#events();
+        if (compact)
+            return this.#agenda(width, events);
+        return this.#monthGrid(width, events);
+    }
+    /** The agenda: items sorted by start, one row each. */
+    #agenda(width, events) {
+        const lines = [this.#ctx.theme.dim(truncate(this.#month, width))];
+        events.forEach((event, index) => {
+            const cursor = index === this.#cursor ? "> " : "  ";
+            const held = this.#held?.itemId === event.row.id;
+            const mark = held ? (this.#ctx.unicode ? "✋ " : "* ") : "";
+            const card = cardLines(this.#block.item, event.row.item, this.#ctx, width - cursor.length - mark.length - 12, 0, this.#tick);
+            const when = `${event.start.slice(0, 10)} `;
+            const [first, ...rest] = card;
+            lines.push(truncate(`${cursor}${mark}${when}${first ?? ""}`, width));
+            for (const line of rest) {
+                lines.push(truncate(`${cursor}${" ".repeat(mark.length + when.length)}${line}`, width));
+            }
+        });
+        return lines;
+    }
+    /** The month grid: one row per day, events under their day. */
+    #monthGrid(width, events) {
+        const byDay = new Map();
+        for (const event of events) {
+            const day = dayKey(event.start);
+            const list = byDay.get(day) ?? [];
+            list.push(event);
+            byDay.set(day, list);
+        }
+        const lines = [this.#ctx.theme.bold(truncate(this.#month, width))];
+        for (const day of daysInMonth(this.#month)) {
+            const todays = byDay.get(day) ?? [];
+            const heldHere = this.#held !== undefined && this.#held.at === day;
+            const marker = heldHere ? (this.#ctx.unicode ? " ⌄" : " v") : "";
+            lines.push(truncate(`${day.slice(8)}${marker}`, width));
+            for (const event of todays) {
+                const held = this.#held?.itemId === event.row.id;
+                const mark = held ? (this.#ctx.unicode ? "✋ " : "* ") : "";
+                const card = cardLines(this.#block.item, event.row.item, this.#ctx, width - 2 - mark.length, 0, this.#tick);
+                const [first, ...rest] = card;
+                lines.push(truncate(`  ${mark}${first ?? ""}`, width));
+                for (const line of rest) {
+                    lines.push(truncate(`  ${" ".repeat(mark.length)}${line}`, width));
+                }
+            }
+        }
+        return lines;
+    }
+    handleInput(data) {
+        // Range keys are always view-only (§12.4).
+        if (data === "[") {
+            this.#month = shiftMonth(this.#month, -1);
+            return;
+        }
+        if (data === "]") {
+            this.#month = shiftMonth(this.#month, 1);
+            return;
+        }
+        if (data === "t") {
+            this.#month = currentMonth();
+            return;
+        }
+        const events = this.#events();
+        // A pick-up in flight: arrows move the event by DAY.
+        const held = this.#held;
+        if (held !== undefined) {
+            if (data === "\x1b") {
+                this.#held = undefined;
+                return;
+            }
+            let delta = 0;
+            if (data === "\x1b[C" || data === "\x1b[B")
+                delta = 1;
+            if (data === "\x1b[D" || data === "\x1b[A")
+                delta = -1;
+            if (delta !== 0) {
+                this.#held = { ...held, at: shiftDay(held.at, delta) };
+                return;
+            }
+            if (data === "\r") {
+                this.#held = undefined;
+                const days = (Date.parse(`${held.at}T00:00:00Z`) -
+                    Date.parse(`${dayKey(held.start)}T00:00:00Z`)) /
+                    86_400_000;
+                if (days === 0)
+                    return;
+                const onMove = this.#block.onMove;
+                if (onMove === undefined)
+                    return;
+                const start = shiftInstant(held.start, days);
+                const end = held.end === undefined ? undefined : shiftInstant(held.end, days);
+                const to = end === undefined ? { start } : { start, end };
+                this.#ctx.dispatch({ type: "move", name: onMove }, { itemId: held.itemId, to });
+            }
+            return;
+        }
+        if (this.#cursor >= events.length)
+            this.#cursor = Math.max(0, events.length - 1);
+        const current = events[this.#cursor];
+        if (data === "\x1b[B") {
+            this.#cursor = Math.min(events.length - 1, this.#cursor + 1);
+            return;
+        }
+        if (data === "\x1b[A") {
+            this.#cursor = Math.max(0, this.#cursor - 1);
+            return;
+        }
+        if (data === "m" && current !== undefined && this.#block.onMove !== undefined) {
+            this.#held = {
+                itemId: current.row.id,
+                start: current.start,
+                end: current.end,
+                at: dayKey(current.start),
+            };
+            return;
+        }
+        if (data === "\r" && current !== undefined) {
+            dispatchActivate(this.#block, this.#ctx, current.row);
+        }
+    }
+    invalidate() {
+        // State (range, cursor, the pick-up) survives re-renders.
+    }
+}

package/dist/blocks/collection/card.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The card template (UI-blocks spec §5.5.1) as terminal lines: a FIXED
+ * line layout, every slot optional except `title`, each slot resolved
+ * against the item (`./` pointers).
+ *
+ * Layout, top to bottom:
+ *  1. eyebrow line (dimmed small text)
+ *  2. title line: icon glyph, tone marker, title (title carries the
+ *     tone's colour through TuiTheme)
+ *  3. subtitle (one line)
+ *  4. body, wrapped and clamped to 4 lines (spec: lists and lanes clamp;
+ *     the TUI clamps in every display — a 100-cell grid card cannot
+ *     afford a full body either, and `detail` panes are Task 4's)
+ *  5. badges + meta on ONE line (badges first, then meta facts)
+ *  6. metrics, one per line (`label: value`, `formatValue` formatted)
+ *  7. status: spinner frame (when `spinner` binds true) + tone marker +
+ *     label — the frame ticks per render (`spinnerFrame`)
+ *  8. deps as `after: id, id, …`
+ *
+ * The card `tone` marker also leads the title; with no tone binding the
+ * marker is the neutral one so lines align.
+ */
+import type { Card, JsonValue } from "@sigrun/shared/blocks";
+import { type BlockCtx } from "../context.js";
+/** The body clamp (spec §5.5.1: 4 lines in lists and lanes). */
+export declare const CARD_BODY_LINES = 4;
+/** The spinner frame for render `tick` (a render-indexed clock: the TUI
+ * has no card-local timers, so a spinning status advances as renders
+ * arrive — the same convention ambient rows use). */
+export declare function spinnerFrame(tick: number, ascii: boolean): string;
+/**
+ * The card's lines for `item` at `width`, indented `indent` cells.
+ * `tick` indexes the spinner frame (the owning component's render
+ * count). Lines are display-width truncated, never wider than the pane.
+ */
+export declare function cardLines(card: Card, item: JsonValue, ctx: BlockCtx, width: number, indent: number, tick: number): string[];

package/dist/blocks/collection/card.js

@@ -0,0 +1,128 @@
+/**
+ * The card template (UI-blocks spec §5.5.1) as terminal lines: a FIXED
+ * line layout, every slot optional except `title`, each slot resolved
+ * against the item (`./` pointers).
+ *
+ * Layout, top to bottom:
+ *  1. eyebrow line (dimmed small text)
+ *  2. title line: icon glyph, tone marker, title (title carries the
+ *     tone's colour through TuiTheme)
+ *  3. subtitle (one line)
+ *  4. body, wrapped and clamped to 4 lines (spec: lists and lanes clamp;
+ *     the TUI clamps in every display — a 100-cell grid card cannot
+ *     afford a full body either, and `detail` panes are Task 4's)
+ *  5. badges + meta on ONE line (badges first, then meta facts)
+ *  6. metrics, one per line (`label: value`, `formatValue` formatted)
+ *  7. status: spinner frame (when `spinner` binds true) + tone marker +
+ *     label — the frame ticks per render (`spinnerFrame`)
+ *  8. deps as `after: id, id, …`
+ *
+ * The card `tone` marker also leads the title; with no tone binding the
+ * marker is the neutral one so lines align.
+ */
+import { formatValue } from "@sigrun/shared/blocks";
+import { bindRaw, bindText, bindTone } from "../context.js";
+import { iconGlyph } from "../icons.js";
+import { toneFg, toneMarker } from "../tones.js";
+import { truncate, wrapPlain } from "../width.js";
+/** The body clamp (spec §5.5.1: 4 lines in lists and lanes). */
+export const CARD_BODY_LINES = 4;
+/** The braille spinner frames (ASCII: the classic four-bar cycle). */
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const SPINNER_FRAMES_ASCII = ["*", "+", "x", "+"];
+/** The spinner frame for render `tick` (a render-indexed clock: the TUI
+ * has no card-local timers, so a spinning status advances as renders
+ * arrive — the same convention ambient rows use). */
+export function spinnerFrame(tick, ascii) {
+    const frames = ascii ? SPINNER_FRAMES_ASCII : SPINNER_FRAMES;
+    return frames[tick % frames.length] ?? frames[0] ?? "*";
+}
+/** One meta entry resolved to its display text ("" = omit). */
+function metaText(entry, ctx, item) {
+    if ("person" in entry) {
+        // The extension supplies the display name; `user` is the handle
+        // and is not shown (spec §5.5.1).
+        return bindText(entry.person.name, ctx);
+    }
+    if ("time" in entry) {
+        const at = bindRaw(entry.time, ctx);
+        return at === undefined ? "" : formatValue(at, entry.format, ctx.locale, ctx.timeZone);
+    }
+    return bindText(entry.text, ctx);
+}
+/**
+ * The card's lines for `item` at `width`, indented `indent` cells.
+ * `tick` indexes the spinner frame (the owning component's render
+ * count). Lines are display-width truncated, never wider than the pane.
+ */
+export function cardLines(card, item, ctx, width, indent, tick) {
+    const pad = " ".repeat(indent);
+    const inner = Math.max(1, width - indent);
+    const itemCtx = { ...ctx, item };
+    const lines = [];
+    const clamp = (line) => truncate(line, inner);
+    // 1. eyebrow
+    const eyebrow = bindText(card.eyebrow, itemCtx);
+    if (eyebrow !== "")
+        lines.push(pad + clamp(ctx.theme.dim(eyebrow)));
+    // 2. title: icon, tone marker, toned title text.
+    const tone = bindTone(card.tone, itemCtx);
+    const title = bindText(card.title, itemCtx);
+    const icon = card.icon === undefined ? "" : `${iconGlyph(bindText(card.icon, itemCtx), !ctx.unicode)} `;
+    const marker = `${toneMarker(tone, !ctx.unicode)} `;
+    lines.push(pad + clamp(`${icon}${marker}${toneFg(ctx.theme, tone)(title)}`));
+    // 3. subtitle
+    const subtitle = bindText(card.subtitle, itemCtx);
+    if (subtitle !== "")
+        lines.push(pad + clamp(subtitle));
+    // 4. body, clamped to CARD_BODY_LINES.
+    const body = bindText(card.body, itemCtx);
+    if (body !== "") {
+        for (const line of wrapPlain(body, inner).slice(0, CARD_BODY_LINES)) {
+            lines.push(pad + line);
+        }
+    }
+    // 5. badges + meta, one line.
+    const parts = [];
+    for (const badge of card.badges ?? []) {
+        const text = bindText(badge.text, itemCtx);
+        if (text === "")
+            continue;
+        const badgeTone = bindTone(badge.tone, itemCtx);
+        parts.push(`[${toneFg(ctx.theme, badgeTone)(text)}]`);
+    }
+    const metaParts = (card.meta ?? [])
+        .map((entry) => metaText(entry, itemCtx, item))
+        .filter((text) => text !== "");
+    if (metaParts.length > 0)
+        parts.push(metaParts.join(" · "));
+    if (parts.length > 0)
+        lines.push(pad + clamp(parts.join(" ")));
+    // 6. metrics, one per line.
+    for (const metric of card.metrics ?? []) {
+        const label = bindText(metric.label, itemCtx);
+        const value = bindRaw(metric.value, itemCtx);
+        if (label === "" || value === undefined)
+            continue;
+        lines.push(pad + clamp(`${label}: ${formatValue(value, metric.format, ctx.locale, ctx.timeZone)}`));
+    }
+    // 7. status (spinner frame + tone marker + label).
+    if (card.status !== undefined) {
+        const label = bindText(card.status.label, itemCtx);
+        if (label !== "") {
+            const statusTone = bindTone(card.status.tone, itemCtx);
+            const spin = bindRaw(card.status.spinner, itemCtx) === true;
+            const frame = spin ? `${spinnerFrame(Math.max(0, tick - 1), !ctx.unicode)} ` : "";
+            const statusMarker = `${toneMarker(statusTone, !ctx.unicode)} `;
+            lines.push(pad + clamp(`${frame}${statusMarker}${toneFg(ctx.theme, statusTone)(label)}`));
+        }
+    }
+    // 8. deps ("after: …").
+    const depsRaw = bindRaw(card.deps, itemCtx);
+    if (Array.isArray(depsRaw)) {
+        const deps = depsRaw.filter((dep) => typeof dep === "string");
+        if (deps.length > 0)
+            lines.push(pad + clamp(`after: ${deps.join(", ")}`));
+    }
+    return lines;
+}

package/dist/blocks/collection/collection.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The `collection` block (UI-blocks spec §5.5): the display dispatch.
+ * Task 3 owns `list`/`table`/`grid`; Task 4 owns `lanes`/`calendar`.
+ */
+import type { Component } from "@earendil-works/pi-tui";
+import type { CollectionBlock } from "@sigrun/shared/blocks";
+import type { BlockCtx } from "../context.js";
+/** The display dispatch. */
+export declare function renderCollection(block: CollectionBlock, ctx: BlockCtx): Component | undefined;

package/dist/blocks/collection/collection.js

@@ -0,0 +1,26 @@
+/**
+ * The `collection` block (UI-blocks spec §5.5): the display dispatch.
+ * Task 3 owns `list`/`table`/`grid`; Task 4 owns `lanes`/`calendar`.
+ */
+import { CalendarComponent } from "./calendar.js";
+import { GridComponent } from "./grid.js";
+import { LanesComponent } from "./lanes.js";
+import { ListComponent } from "./list.js";
+import { TableComponent } from "./table.js";
+/** The display dispatch. */
+export function renderCollection(block, ctx) {
+    switch (block.display) {
+        case "list":
+            return new ListComponent(block, ctx);
+        case "table":
+            return new TableComponent(block, ctx);
+        case "grid":
+            return new GridComponent(block, ctx);
+        case "lanes":
+            return new LanesComponent(block, ctx);
+        case "calendar":
+            return new CalendarComponent(block, ctx);
+        default:
+            return undefined;
+    }
+}

package/dist/blocks/collection/grid.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The `grid` display (UI-blocks spec §5.5 + §12.3): cards in as many
+ * columns as fit — `floor(width / token)` with the token from the item
+ * template's `image` presence (`m` = 45 cells with an image, `s` = 30
+ * without; §5.5's minItemWidth). `overflow: "scroll"` stays one
+ * horizontal row (the row clips at the pane edge; there is no second
+ * row). At compact width the fallback is one column (§12.3).
+ */
+import type { Component } from "@earendil-works/pi-tui";
+import type { CollectionBlock } from "@sigrun/shared/blocks";
+import { type BlockCtx } from "../context.js";
+/** `grid`: floor(width / token) card columns. */
+export declare class GridComponent implements Component {
+    #private;
+    constructor(block: CollectionBlock, ctx: BlockCtx);
+    render(width: number): string[];
+    invalidate(): void;
+}

package/dist/blocks/collection/grid.js

@@ -0,0 +1,72 @@
+/**
+ * The `grid` display (UI-blocks spec §5.5 + §12.3): cards in as many
+ * columns as fit — `floor(width / token)` with the token from the item
+ * template's `image` presence (`m` = 45 cells with an image, `s` = 30
+ * without; §5.5's minItemWidth). `overflow: "scroll"` stays one
+ * horizontal row (the row clips at the pane edge; there is no second
+ * row). At compact width the fallback is one column (§12.3).
+ */
+import { pad, truncate, widthClassOf } from "../width.js";
+import { cardLines } from "./card.js";
+import { collectionItems, sortItems } from "./shared.js";
+/** `grid`: floor(width / token) card columns. */
+export class GridComponent {
+    #block;
+    #ctx;
+    #tick = 0;
+    constructor(block, ctx) {
+        this.#block = block;
+        this.#ctx = ctx;
+    }
+    #rows() {
+        return sortItems(collectionItems(this.#block, this.#ctx), this.#block.sort);
+    }
+    render(width) {
+        this.#tick += 1;
+        const rows = this.#rows();
+        const itemWidth = this.#block.item.image === undefined ? 30 : 45; // s / m token (§5.2)
+        let columns = Math.max(1, Math.floor(width / itemWidth));
+        if (this.#block.overflow === "scroll") {
+            // One row, clipped at the pane edge.
+            columns = Math.max(1, columns);
+            return this.#renderRow(rows, width, itemWidth).slice(0, this.#rowHeight(rows, itemWidth, width));
+        }
+        if (widthClassOf(width) === "compact")
+            columns = 1;
+        const lines = [];
+        for (let start = 0; start < rows.length; start += columns) {
+            lines.push(...this.#renderRow(rows.slice(start, start + columns), width, itemWidth));
+        }
+        return lines;
+    }
+    /** The tallest card of a row, in lines. */
+    #rowHeight(rows, itemWidth, width) {
+        let height = 0;
+        for (const row of rows) {
+            height = Math.max(height, cardLines(this.#block.item, row.item, this.#ctx, itemWidth - 2, 0, this.#tick).length);
+        }
+        void width;
+        return height;
+    }
+    /** One grid row: the cards side by side, each padded to `itemWidth`. */
+    #renderRow(rows, width, itemWidth) {
+        const perCard = rows.map((row) => cardLines(this.#block.item, row.item, this.#ctx, itemWidth - 2, 0, this.#tick));
+        const height = perCard.reduce((max, card) => Math.max(max, card.length), 0);
+        const lines = [];
+        for (let line = 0; line < height; line++) {
+            const cells = perCard.map((card) => pad(card[line] ?? "", itemWidth - 2));
+            const joined = cells.join("  ");
+            const text = joined.trimEnd() === "" ? "" : joined;
+            if (text === "") {
+                lines.push("");
+            }
+            else {
+                lines.push(truncate(text.replace(/\s+$/, ""), width));
+            }
+        }
+        return lines;
+    }
+    invalidate() {
+        // The grid holds no view state beyond the spinner tick.
+    }
+}