@sigrun/shared 0.0.0-stage → 0.1.1

package/dist/blocks/lttb.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Largest-triangle-three-buckets downsampling (UI-blocks spec §5.4):
+ * the display-side downsample channels apply to line and area series
+ * (at most 2,000 points per series on the wire; a channel shows fewer).
+ *
+ * Pure: returns a fresh array of fresh tuples; never mutates `points`.
+ */
+/**
+ * Downsample `points` to at most `threshold` points, always keeping the
+ * first and the last point. The interior is bucketed into `threshold -
+ * 2` buckets; each bucket keeps the point forming the largest triangle
+ * with the previously selected point and the next bucket's average —
+ * which preserves visual shape (peaks and troughs) rather than
+ * sampling on a fixed interval.
+ */
+export declare function lttb(points: readonly (readonly [number, number])[], threshold: number): [number, number][];

package/dist/blocks/lttb.js

@@ -0,0 +1,67 @@
+/**
+ * Largest-triangle-three-buckets downsampling (UI-blocks spec §5.4):
+ * the display-side downsample channels apply to line and area series
+ * (at most 2,000 points per series on the wire; a channel shows fewer).
+ *
+ * Pure: returns a fresh array of fresh tuples; never mutates `points`.
+ */
+/**
+ * Downsample `points` to at most `threshold` points, always keeping the
+ * first and the last point. The interior is bucketed into `threshold -
+ * 2` buckets; each bucket keeps the point forming the largest triangle
+ * with the previously selected point and the next bucket's average —
+ * which preserves visual shape (peaks and troughs) rather than
+ * sampling on a fixed interval.
+ */
+export function lttb(points, threshold) {
+    const count = points.length;
+    if (count === 0 || threshold <= 0)
+        return [];
+    if (threshold === 1)
+        return [[points[0][0], points[0][1]]];
+    if (threshold === 2) {
+        return [
+            [points[0][0], points[0][1]],
+            [count === 1 ? points[0][0] : points[count - 1][0],
+                count === 1 ? points[0][1] : points[count - 1][1]],
+        ];
+    }
+    if (threshold >= count) {
+        return points.map((point) => [point[0], point[1]]);
+    }
+    const sampled = [[points[0][0], points[0][1]]];
+    const bucketSize = (count - 2) / (threshold - 2);
+    for (let bucket = 0; bucket < threshold - 2; bucket++) {
+        const start = Math.floor(1 + bucket * bucketSize);
+        const end = Math.min(Math.floor(1 + (bucket + 1) * bucketSize), count - 1);
+        // The average of the NEXT bucket's points — the third corner of
+        // every candidate triangle. The last bucket averages the final
+        // point's window [count-1, count).
+        const nextStart = end;
+        const nextEnd = Math.min(Math.floor(1 + (bucket + 2) * bucketSize), count);
+        let avgX = 0;
+        let avgY = 0;
+        for (let i = nextStart; i < nextEnd; i++) {
+            avgX += points[i][0];
+            avgY += points[i][1];
+        }
+        avgX /= nextEnd - nextStart;
+        avgY /= nextEnd - nextStart;
+        const previous = sampled[sampled.length - 1];
+        let bestArea = -1;
+        let bestIndex = start;
+        for (let i = start; i < end; i++) {
+            // Twice the signed area of the triangle (previous, candidate,
+            // average) — the factor is constant, so abs is enough to rank.
+            const area = Math.abs((previous[0] - avgX) * (points[i][1] - previous[1]) -
+                (previous[0] - points[i][0]) * (avgY - previous[1]));
+            if (area > bestArea) {
+                bestArea = area;
+                bestIndex = i;
+            }
+        }
+        sampled.push([points[bestIndex][0], points[bestIndex][1]]);
+    }
+    sampled.push([points[count - 1][0], points[count - 1][1]]);
+    return sampled;
+}

package/dist/blocks/ops.d.ts

@@ -0,0 +1,44 @@
+/**
+ * `applyOps` and `resolvePointer` (UI-blocks spec §4.2/§4.3): the single
+ * applier every surface's data updates go through, and the pointer
+ * reader bindings resolve with.
+ *
+ * Purity contract:
+ *
+ * - `applyOps` NEVER mutates its input — it clones along the touched
+ *   path only (copy-on-write), so a batch of ops over a large document
+ *   shares every untouched branch by reference with the input. The
+ *   property suite pins this (frozen inputs, snapshot equality).
+ * - Pointers are RFC 6901 with `~0` (`~`) and `~1` (`/`) escaping, plus
+ *   the one extension (spec §4.2): a pointer starting `./` resolves
+ *   against the passed `item` (a collection's item template), which
+ *   only `resolvePointer` takes — the DATA side never sees `./`.
+ * - A failing op throws `DataOpError` carrying the op's INDEX, so the
+ *   caller (U3/U5) can treat it as the full-refetch signal (spec §16).
+ */
+import type { JsonObject, JsonValue } from "../json.js";
+import type { DataOp } from "./types.js";
+/** An op that could not be applied; `opIndex` names which one failed. */
+export declare class DataOpError extends Error {
+    readonly opIndex: number;
+    constructor(opIndex: number, message: string);
+}
+/**
+ * Apply a batch of `DataOp`s (spec §4.3) to `data`, returning a NEW
+ * object. Pure: untouched branches are shared by reference with the
+ * input; the input is never mutated. Ops apply sequentially — an
+ * earlier op's write is visible to the next.
+ *
+ * Throws `DataOpError` (naming the op's index) on any op whose path
+ * does not exist, or whose target is not an array where one is required.
+ */
+export declare function applyOps(data: JsonObject, ops: readonly DataOp[]): JsonObject;
+/**
+ * Resolve an RFC 6901 `pointer` against `data`; a pointer starting
+ * `./` resolves against `item` instead (spec §4.2's one extension,
+ * used inside collection item templates). A missing path — including a
+ * path THROUGH a JSON null, and a malformed pointer (no `/` or `./`
+ * prefix) — is `undefined`, never an error: "a binding to a missing
+ * path renders as empty, never as an error".
+ */
+export declare function resolvePointer(data: JsonValue, pointer: string, item?: JsonValue): JsonValue | undefined;

package/dist/blocks/ops.js

@@ -0,0 +1,294 @@
+/**
+ * `applyOps` and `resolvePointer` (UI-blocks spec §4.2/§4.3): the single
+ * applier every surface's data updates go through, and the pointer
+ * reader bindings resolve with.
+ *
+ * Purity contract:
+ *
+ * - `applyOps` NEVER mutates its input — it clones along the touched
+ *   path only (copy-on-write), so a batch of ops over a large document
+ *   shares every untouched branch by reference with the input. The
+ *   property suite pins this (frozen inputs, snapshot equality).
+ * - Pointers are RFC 6901 with `~0` (`~`) and `~1` (`/`) escaping, plus
+ *   the one extension (spec §4.2): a pointer starting `./` resolves
+ *   against the passed `item` (a collection's item template), which
+ *   only `resolvePointer` takes — the DATA side never sees `./`.
+ * - A failing op throws `DataOpError` carrying the op's INDEX, so the
+ *   caller (U3/U5) can treat it as the full-refetch signal (spec §16).
+ */
+/** An op that could not be applied; `opIndex` names which one failed. */
+export class DataOpError extends Error {
+    opIndex;
+    constructor(opIndex, message) {
+        super(message);
+        this.name = "DataOpError";
+        this.opIndex = opIndex;
+    }
+}
+function isContainer(value) {
+    // `typeof null === "object"` — a JSON null is NOT a container; a path
+    // through it is a missing path (undefined), never a walk into it.
+    return Array.isArray(value) || (typeof value === "object" && value !== null);
+}
+/** Split an RFC 6901 pointer into unescaped reference tokens. */
+function pointerTokens(pointer) {
+    if (pointer === "")
+        return [];
+    if (!pointer.startsWith("/")) {
+        throw new Error(`invalid pointer: ${pointer}`);
+    }
+    return pointer
+        .slice(1)
+        .split("/")
+        .map((token) => token.replaceAll("~1", "/").replaceAll("~0", "~"));
+}
+/** Read `token` from a container; `undefined` when absent. */
+function readToken(container, token) {
+    if (Array.isArray(container)) {
+        if (!/^\d+$/.test(token))
+            return undefined;
+        const index = Number(token);
+        return index < container.length ? container[index] : undefined;
+    }
+    return Object.prototype.hasOwnProperty.call(container, token)
+        ? container[token]
+        : undefined;
+}
+/** Parse `key` as an array index valid INSIDE `array` (not for append). */
+function arrayIndex(array, key, pointer) {
+    if (!/^\d+$/.test(key)) {
+        throw new Error(`not an array index: ${pointer}`);
+    }
+    const index = Number(key);
+    if (index >= array.length) {
+        throw new Error(`index out of bounds: ${pointer}`);
+    }
+    return index;
+}
+/** Parse `key` as an array index valid for INSERTION (== length allowed). */
+function insertIndex(array, key, pointer) {
+    if (key === "-")
+        return array.length;
+    if (!/^\d+$/.test(key)) {
+        throw new Error(`not an array index: ${pointer}`);
+    }
+    const index = Number(key);
+    if (index > array.length) {
+        throw new Error(`index out of bounds: ${pointer}`);
+    }
+    return index;
+}
+/**
+ * READ-ONLY walk: resolve the tokens before the last and return the
+ * parent container plus the final token. Throws when any step is
+ * missing or not a container.
+ */
+function resolveParent(root, tokens, opIndex, pointer) {
+    let node = root;
+    for (let i = 0; i < tokens.length - 1; i++) {
+        if (!isContainer(node)) {
+            throw new DataOpError(opIndex, `path not found: ${pointer}`);
+        }
+        const next = readToken(node, tokens[i]);
+        if (next === undefined) {
+            throw new DataOpError(opIndex, `path not found: ${pointer}`);
+        }
+        node = next;
+    }
+    if (!isContainer(node)) {
+        throw new DataOpError(opIndex, `path not found: ${pointer}`);
+    }
+    return { parent: node, key: tokens[tokens.length - 1] };
+}
+/**
+ * Clone-on-write rewrite: copies every container along `tokens` from
+ * `data` down, hands the (fresh, cloned) final container to `mutate`,
+ * and returns the new root. The input is never touched; branches off
+ * the path are shared by reference with it.
+ */
+function withWrite(data, tokens, mutate) {
+    const rootClone = { ...data };
+    let node = rootClone;
+    for (let i = 0; i < tokens.length - 1; i++) {
+        const child = readToken(node, tokens[i]);
+        if (child === undefined || !isContainer(child)) {
+            throw new Error(`path not found: /${tokens.join("/")}`);
+        }
+        const childClone = Array.isArray(child)
+            ? [...child]
+            : { ...child };
+        if (Array.isArray(node)) {
+            node[Number(tokens[i])] = childClone;
+        }
+        else {
+            node[tokens[i]] = childClone;
+        }
+        node = childClone;
+    }
+    mutate(node, tokens[tokens.length - 1]);
+    return rootClone;
+}
+/**
+ * Apply a batch of `DataOp`s (spec §4.3) to `data`, returning a NEW
+ * object. Pure: untouched branches are shared by reference with the
+ * input; the input is never mutated. Ops apply sequentially — an
+ * earlier op's write is visible to the next.
+ *
+ * Throws `DataOpError` (naming the op's index) on any op whose path
+ * does not exist, or whose target is not an array where one is required.
+ */
+export function applyOps(data, ops) {
+    let current = data;
+    for (let opIndex = 0; opIndex < ops.length; opIndex++) {
+        const op = ops[opIndex];
+        try {
+            current = applyOne(current, op, opIndex);
+        }
+        catch (error) {
+            if (error instanceof DataOpError)
+                throw error;
+            throw new DataOpError(opIndex, `${op.op} ${"path" in op ? op.path : ""}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return current;
+}
+function applyOne(data, op, opIndex) {
+    switch (op.op) {
+        case "set":
+            return opSet(data, op.path, op.value, opIndex);
+        case "remove":
+            return opRemove(data, op.path, opIndex);
+        case "insert":
+            return opInsert(data, op.path, op.value, opIndex);
+        case "move":
+            return opMove(data, op.from, op.path, opIndex);
+    }
+}
+/** `set`: assign at `path` (an existing array slot, or a created object member). */
+function opSet(data, path, value, opIndex) {
+    const tokens = pointerTokens(path);
+    if (tokens.length === 0) {
+        throw new DataOpError(opIndex, "set at the root is not allowed");
+    }
+    const { parent, key } = resolveParent(data, tokens, opIndex, path);
+    if (Array.isArray(parent)) {
+        arrayIndex(parent, key, path); // validate before cloning
+    }
+    return withWrite(data, tokens, (container, finalKey) => {
+        if (Array.isArray(container)) {
+            container[arrayIndex(container, finalKey, path)] = value;
+        }
+        else {
+            container[finalKey] = value;
+        }
+    });
+}
+/** `remove`: delete the member at `path` (shifting array elements). */
+function opRemove(data, path, opIndex) {
+    const tokens = pointerTokens(path);
+    if (tokens.length === 0) {
+        throw new DataOpError(opIndex, "remove at the root is not allowed");
+    }
+    const { parent, key } = resolveParent(data, tokens, opIndex, path);
+    if (Array.isArray(parent)) {
+        arrayIndex(parent, key, path); // throws (→ opIndex) when out of bounds
+    }
+    else if (!Object.prototype.hasOwnProperty.call(parent, key)) {
+        throw new DataOpError(opIndex, `path not found: ${path}`);
+    }
+    return withWrite(data, tokens, (container, finalKey) => {
+        if (Array.isArray(container)) {
+            container.splice(arrayIndex(container, finalKey, path), 1);
+        }
+        else {
+            delete container[finalKey];
+        }
+    });
+}
+/** `insert`: insert `value` into the array at `path` (`-` appends). */
+function opInsert(data, path, value, opIndex) {
+    const tokens = pointerTokens(path);
+    if (tokens.length === 0) {
+        throw new DataOpError(opIndex, `not an array: ${path}`);
+    }
+    const { parent } = resolveParent(data, tokens, opIndex, path);
+    if (!Array.isArray(parent)) {
+        throw new DataOpError(opIndex, `not an array: ${path}`);
+    }
+    return withWrite(data, tokens, (container, finalKey) => {
+        if (Array.isArray(container)) {
+            container.splice(insertIndex(container, finalKey, path), 0, value);
+        }
+    });
+}
+/**
+ * `move`: remove the item at `from`, then insert it at `path` — a
+ * reorder within one array or a move across arrays (spec §4.3: it
+ * exists so reorders don't re-send the moved item). Both ends must be
+ * array slots; the destination index is resolved against the
+ * post-removal array.
+ */
+function opMove(data, from, path, opIndex) {
+    const fromTokens = pointerTokens(from);
+    const toTokens = pointerTokens(path);
+    if (fromTokens.length === 0 || toTokens.length === 0) {
+        throw new DataOpError(opIndex, "move at the root is not allowed");
+    }
+    const source = resolveParent(data, fromTokens, opIndex, from);
+    if (!Array.isArray(source.parent)) {
+        throw new DataOpError(opIndex, `not an array: ${from}`);
+    }
+    const value = readToken(source.parent, source.key);
+    if (value === undefined) {
+        throw new DataOpError(opIndex, `path not found: ${from}`);
+    }
+    // Remove first: a move into the same array sees post-removal indices.
+    const removed = withWrite(data, fromTokens, (container, finalKey) => {
+        if (Array.isArray(container)) {
+            container.splice(arrayIndex(container, finalKey, from), 1);
+        }
+    });
+    const to = resolveParent(removed, toTokens, opIndex, path);
+    if (!Array.isArray(to.parent)) {
+        throw new DataOpError(opIndex, `not an array: ${path}`);
+    }
+    return withWrite(removed, toTokens, (container, finalKey) => {
+        if (Array.isArray(container)) {
+            container.splice(insertIndex(container, finalKey, path), 0, value);
+        }
+    });
+}
+/**
+ * Resolve an RFC 6901 `pointer` against `data`; a pointer starting
+ * `./` resolves against `item` instead (spec §4.2's one extension,
+ * used inside collection item templates). A missing path — including a
+ * path THROUGH a JSON null, and a malformed pointer (no `/` or `./`
+ * prefix) — is `undefined`, never an error: "a binding to a missing
+ * path renders as empty, never as an error".
+ */
+export function resolvePointer(data, pointer, item) {
+    const base = pointer.startsWith("./") ? item : data;
+    if (base === undefined)
+        return undefined;
+    const rest = pointer.startsWith("./") ? pointer.slice(1) : pointer;
+    let tokens;
+    try {
+        tokens = pointerTokens(rest);
+    }
+    catch {
+        // A malformed binding renders empty — the render contract is
+        // undefined-never-throws (only `applyOps`, the server-side applier,
+        // reports bad pointers, as `DataOpError`).
+        return undefined;
+    }
+    let node = base;
+    for (const token of tokens) {
+        if (!isContainer(node))
+            return undefined;
+        const next = readToken(node, token);
+        if (next === undefined)
+            return undefined;
+        node = next;
+    }
+    return node;
+}

package/dist/blocks/text.d.ts

@@ -0,0 +1,43 @@
+/**
+ * `toText` (UI-blocks spec §14.3): the deterministic plain-text
+ * projection of a surface — headings, aligned tables, lists with
+ * checkboxes and numbers, lanes as sections, charts as one summary
+ * line per series. Used for the model's view of its own `show_blocks`
+ * call, the default `fallback` text, extension unit tests, logs and
+ * notifications.
+ *
+ * Determinism (spec §14.3): the same input, width and locale give the
+ * same bytes, so model context stays cacheable. Three rules make that
+ * hold:
+ *
+ * - object keys are visited in SCHEMA order, never insertion order —
+ *   card slots, log lines, tree nodes and table cells are read through
+ *   their named props, and anything rendered as JSON goes through
+ *   `formatValue`'s sorted-key serializer;
+ * - no clock reads in the render path: `TextOptions.timeZone` defaults
+ *   to UTC (a datetime projection is stable across hosts; pass a zone
+ *   to localize), and only the `relative` format consults `Date.now()`;
+ * - unknown blocks render their `fallback`, else
+ *   `[unsupported block: <type>]` (§4.4) — never a throw.
+ */
+import type { Tree } from "./types.js";
+import type { JsonObject } from "../json.js";
+/** Options for `toText`: the width to wrap at, and the `Intl` locale. */
+export interface TextOptions {
+    /** Wrap target in columns (the §14.3 snapshots use 80 and 160). */
+    width: number;
+    /** BCP-47 locale for every `Intl` format. */
+    locale: string;
+    /**
+     * Time zone for datetime renders. Defaults to UTC inside `toText`
+     * (byte-stable projections across hosts); pass one to localize.
+     */
+    timeZone?: string;
+}
+/**
+ * Render `tree` against `data` as plain text (spec §14.3).
+ * Deterministic per (input, width, locale): the same arguments give the
+ * same bytes. Unknown blocks render their `fallback`, else
+ * `[unsupported block: <type>]`.
+ */
+export declare function toText(tree: Tree, data: JsonObject, opts: TextOptions): string;