@sigrun/shared 0.1.0 → 0.1.1

package/dist/blocks/format.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `formatValue` (UI-blocks spec §5.3): the one value formatter behind
+ * `format` props — `stat`, `meter`, table columns, chart axes and card
+ * time slots. Pure `Intl` only; no imports outside `shared/src/`.
+ *
+ * Determinism (spec §14.3): the same input and locale give the same
+ * bytes. Everything here is derived from the arguments — no clock
+ * reads (the `relative` format takes the timestamp to describe, and
+ * `now` comes from `Date.now()` at the CALL SITE inside `toText`
+ * rendering... which is equally forbidden to wander). `relative` is
+ * therefore stable within a call and pinned by tests that pass a
+ * timestamp chosen so the unit boundary cannot flip mid-run.
+ */
+import type { JsonValue } from "../json.js";
+/**
+ * Render `value` in `format` for `locale` (spec §5.3's format list).
+ *
+ * - `undefined` format: numbers group digits; strings pass through;
+ *   `null` renders empty; booleans spell out; objects and arrays render
+ *   as JSON with SORTED keys (deterministic bytes regardless of the
+ *   key order the data arrived in).
+ * - `datetime`/`date`/`time` take epoch milliseconds or an ISO string,
+ *   rendered in `timeZone` when given (defaults to the locale's).
+ * - `relative` describes a timestamp relative to `Date.now()`; the unit
+ *   is chosen by the span, per `Intl.RelativeTimeFormat`.
+ * - An unknown format falls back to plain number formatting.
+ */
+export declare function formatValue(value: JsonValue, format: string | undefined, locale: string, timeZone?: string): string;

package/dist/blocks/format.js

@@ -0,0 +1,199 @@
+/**
+ * `formatValue` (UI-blocks spec §5.3): the one value formatter behind
+ * `format` props — `stat`, `meter`, table columns, chart axes and card
+ * time slots. Pure `Intl` only; no imports outside `shared/src/`.
+ *
+ * Determinism (spec §14.3): the same input and locale give the same
+ * bytes. Everything here is derived from the arguments — no clock
+ * reads (the `relative` format takes the timestamp to describe, and
+ * `now` comes from `Date.now()` at the CALL SITE inside `toText`
+ * rendering... which is equally forbidden to wander). `relative` is
+ * therefore stable within a call and pinned by tests that pass a
+ * timestamp chosen so the unit boundary cannot flip mid-run.
+ */
+/** The byte-scale units `bytes` walks up through (binary steps of 1024). */
+const BYTE_UNITS = ["B", "KB", "MB", "GB", "TB", "PB"];
+/** The duration steps `duration` walks down through, with their ms sizes. */
+const DURATION_STEPS = [
+    { unit: "d", ms: 86_400_000 },
+    { unit: "h", ms: 3_600_000 },
+    { unit: "m", ms: 60_000 },
+    { unit: "s", ms: 1_000 },
+    { unit: "ms", ms: 1 },
+];
+/** A locale-aware number formatter with at most `max` fraction digits. */
+function numberFormatter(locale, maximumFractionDigits) {
+    return new Intl.NumberFormat(locale, { maximumFractionDigits });
+}
+/**
+ * `bytes`: 1024-based scale with a `maximumFractionDigits: 1` number,
+ * e.g. `1536 → "1.5 KB"`, `512 → "512 B"`.
+ */
+function formatBytes(value, locale) {
+    let unit = 0;
+    let scaled = value;
+    while (Math.abs(scaled) >= 1024 && unit < BYTE_UNITS.length - 1) {
+        scaled /= 1024;
+        unit++;
+    }
+    return `${numberFormatter(locale, 1).format(scaled)} ${BYTE_UNITS[unit]}`;
+}
+/**
+ * `duration`: milliseconds in, the two most significant non-zero units
+ * out, e.g. `11520000 → "3h 12m"`, `1500 → "1s 500ms"`, `0 → "0s"`.
+ * Sub-second remainders are truncated (not rounded) so the last unit
+ * named is the one actually covered.
+ */
+function formatDuration(ms, locale) {
+    let rest = Math.trunc(ms);
+    const parts = [];
+    for (const step of DURATION_STEPS) {
+        if (parts.length === 2)
+            break;
+        if (rest >= step.ms || (parts.length > 0 && rest > 0)) {
+            const size = Math.floor(rest / step.ms);
+            parts.push(`${numberFormatter(locale, 0).format(size)}${step.unit}`);
+            rest -= size * step.ms;
+        }
+    }
+    if (parts.length === 0)
+        return `0s`;
+    return parts.join(" ");
+}
+/** Coerce a datetime-ish JSON value to epoch milliseconds, or `undefined`. */
+function epochMillis(value) {
+    if (typeof value === "number")
+        return value;
+    if (typeof value === "string") {
+        const parsed = Date.parse(value);
+        return Number.isNaN(parsed) ? undefined : parsed;
+    }
+    return undefined;
+}
+/**
+ * Render `value` in `format` for `locale` (spec §5.3's format list).
+ *
+ * - `undefined` format: numbers group digits; strings pass through;
+ *   `null` renders empty; booleans spell out; objects and arrays render
+ *   as JSON with SORTED keys (deterministic bytes regardless of the
+ *   key order the data arrived in).
+ * - `datetime`/`date`/`time` take epoch milliseconds or an ISO string,
+ *   rendered in `timeZone` when given (defaults to the locale's).
+ * - `relative` describes a timestamp relative to `Date.now()`; the unit
+ *   is chosen by the span, per `Intl.RelativeTimeFormat`.
+ * - An unknown format falls back to plain number formatting.
+ */
+export function formatValue(value, format, locale, timeZone) {
+    switch (format) {
+        case "number":
+        case undefined:
+            return plain(value, locale);
+        case "compact":
+            return typeof value === "number"
+                ? new Intl.NumberFormat(locale, {
+                    notation: "compact",
+                    maximumFractionDigits: 1,
+                }).format(value)
+                : plain(value, locale);
+        case "percent":
+            return typeof value === "number"
+                ? new Intl.NumberFormat(locale, {
+                    style: "percent",
+                    maximumFractionDigits: 1,
+                }).format(value)
+                : plain(value, locale);
+        case "bytes":
+            return typeof value === "number" ? formatBytes(value, locale) : plain(value, locale);
+        case "duration":
+            return typeof value === "number" ? formatDuration(value, locale) : plain(value, locale);
+        case "datetime":
+        case "date":
+        case "time": {
+            const at = epochMillis(value);
+            if (at === undefined)
+                return plain(value, locale);
+            const options = format === "datetime"
+                ? { dateStyle: "medium", timeStyle: "short" }
+                : format === "date"
+                    ? { dateStyle: "medium" }
+                    : { timeStyle: "medium" };
+            return new Intl.DateTimeFormat(locale, timeZone ? { ...options, timeZone } : options).format(at);
+        }
+        case "relative": {
+            const at = epochMillis(value);
+            if (at === undefined)
+                return plain(value, locale);
+            return relativeFrom(at, Date.now(), locale);
+        }
+        default:
+            if (format.startsWith("currency:")) {
+                const currency = format.slice("currency:".length);
+                if (typeof value !== "number")
+                    return plain(value, locale);
+                try {
+                    return new Intl.NumberFormat(locale, {
+                        style: "currency",
+                        currency,
+                    }).format(value);
+                }
+                catch {
+                    // An invalid ISO 4217 code (validation's job to catch
+                    // earlier) renders as a plain number, never a throw.
+                    return numberFormatter(locale, 2).format(value);
+                }
+            }
+            return plain(value, locale);
+    }
+}
+/** The no-format rendering: locale-numbered primitives, sorted-key JSON. */
+function plain(value, locale) {
+    if (value === null)
+        return "";
+    switch (typeof value) {
+        case "string":
+            return value;
+        case "number":
+            return new Intl.NumberFormat(locale, { maximumFractionDigits: 3 }).format(value);
+        case "boolean":
+            return value ? "true" : "false";
+        default:
+            return JSON.stringify(sortKeys(value));
+    }
+}
+/** Recursively copy `value` with every object's keys in sorted order. */
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (value !== null && typeof value === "object") {
+        const out = {};
+        for (const key of Object.keys(value).sort()) {
+            out[key] = sortKeys(value[key]);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * `"<span> ago"` for a timestamp: picks the unit whose threshold the
+ * span has crossed (`Intl.RelativeTimeFormat` conventions: seconds
+ * under a minute, minutes under an hour, hours under a day, days under
+ * a week, then weeks, months, years).
+ */
+function relativeFrom(at, now, locale) {
+    const spanSeconds = Math.round((at - now) / 1000);
+    const abs = Math.abs(spanSeconds);
+    const rtf = new Intl.RelativeTimeFormat(locale, { numeric: "auto" });
+    if (abs < 60)
+        return rtf.format(spanSeconds, "second");
+    if (abs < 3600)
+        return rtf.format(Math.round(spanSeconds / 60), "minute");
+    if (abs < 86_400)
+        return rtf.format(Math.round(spanSeconds / 3600), "hour");
+    if (abs < 7 * 86_400)
+        return rtf.format(Math.round(spanSeconds / 86_400), "day");
+    if (abs < 30 * 86_400)
+        return rtf.format(Math.round(spanSeconds / (7 * 86_400)), "week");
+    if (abs < 365 * 86_400)
+        return rtf.format(Math.round(spanSeconds / (30 * 86_400)), "month");
+    return rtf.format(Math.round(spanSeconds / (365 * 86_400)), "year");
+}

package/dist/blocks/icons.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The named icons (UI-blocks spec §10.2): a CLOSED set of 49 names.
+ *
+ * The webui draws them from a bundled subset of Lucide; the TUI maps
+ * each name to a Unicode glyph with an ASCII fallback. An unknown icon
+ * name fails validation (U0 Task 2) — `IconName` is the literal union,
+ * so a typo is a type error wherever the contract is used literally.
+ */
+/** The v1 icon set, exactly as spec §10.2 pins it. */
+export declare const ICON_NAMES: readonly ["add", "edit", "delete", "refresh", "search", "filter", "share", "copy", "link", "external", "more", "check", "close", "drag", "file", "folder", "calendar", "clock", "user", "users", "tag", "list", "board", "chart", "image", "book", "cart", "home", "bell", "lock", "key", "info", "warn", "error", "success", "pending", "running", "sun", "moon", "cloud", "cloud-sun", "cloud-rain", "cloud-snow", "cloud-lightning", "fog", "wind", "droplets", "thermometer", "umbrella"];
+/** One name from the closed set. */
+export type IconName = (typeof ICON_NAMES)[number];

package/dist/blocks/icons.js

@@ -0,0 +1,64 @@
+/**
+ * The named icons (UI-blocks spec §10.2): a CLOSED set of 49 names.
+ *
+ * The webui draws them from a bundled subset of Lucide; the TUI maps
+ * each name to a Unicode glyph with an ASCII fallback. An unknown icon
+ * name fails validation (U0 Task 2) — `IconName` is the literal union,
+ * so a typo is a type error wherever the contract is used literally.
+ */
+/** The v1 icon set, exactly as spec §10.2 pins it. */
+export const ICON_NAMES = [
+    // navigation and actions
+    "add",
+    "edit",
+    "delete",
+    "refresh",
+    "search",
+    "filter",
+    "share",
+    "copy",
+    "link",
+    "external",
+    "more",
+    "check",
+    "close",
+    "drag",
+    // objects
+    "file",
+    "folder",
+    "calendar",
+    "clock",
+    "user",
+    "users",
+    "tag",
+    "list",
+    "board",
+    "chart",
+    "image",
+    "book",
+    "cart",
+    "home",
+    "bell",
+    "lock",
+    "key",
+    // status
+    "info",
+    "warn",
+    "error",
+    "success",
+    "pending",
+    "running",
+    // weather
+    "sun",
+    "moon",
+    "cloud",
+    "cloud-sun",
+    "cloud-rain",
+    "cloud-snow",
+    "cloud-lightning",
+    "fog",
+    "wind",
+    "droplets",
+    "thermometer",
+    "umbrella",
+];

package/dist/blocks/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `@sigrun/shared/blocks` — the block-set foundation (UI-blocks U0).
+ *
+ * One entry point for the wire types (§4/§5/§6.1), the data-op applier
+ * (§4.3), the icon names (§10.2), display downsampling (§5.4), and the
+ * channel-facing surface transport. Consumed by the server, the webui
+ * and the TUI alike; re-exported for extensions through
+ * `@sigrun/sigrun/blocks` (U0 Task 4).
+ *
+ * The runtime half is deliberately tiny and dependency-free: the purity
+ * guard (`test/views-purity.test.ts`) holds every specifier inside
+ * `shared/src/`.
+ */
+export { BLOCK_SET_VERSION } from "./types.js";
+export { DataOpError, applyOps, resolvePointer } from "./ops.js";
+export { ICON_NAMES } from "./icons.js";
+export { lttb } from "./lttb.js";
+export { formatValue } from "./format.js";
+export { toText } from "./text.js";
+export type { Action, ActionButton, Bindable, Binding, Block, BlockBase, BulkAction, CalloutBlock, Card, CardBadge, CardMetric, CardMeta, CardStatus, ChartAxisX, ChartAxisY, ChartBlock, ChartSeries, ChartThreshold, ChoiceField, ChoiceOption, CollectionBlock, CollectionColumn, CollectionGroup, CollectionSort, CollectionTime, ColumnChild, ColumnsBlock, Confirm, CoreTarget, DataOp, DataOps, DataUpdate, DateField, DatePreset, DaterangeField, DatetimeField, DetailsBlock, DiffBlock, Field, FieldBase, FieldsBlock, FieldsRow, FileField, Format, FormBlock, GridBlock, GridChild, ImageBlock, ListField, LogBlock, LogLine, LongtextField, MarkdownBlock, MeterBlock, MeterThreshold, NumberField, PageBlock, PageEmpty, Placement, SectionBlock, SecretField, Size, StackBlock, StatBlock, TextField, ToggleField, Tone, Tree, TreeBlock, TreeNode, WidthCondition, } from "./types.js";
+export type { IconName } from "./icons.js";
+export type { TextOptions } from "./text.js";
+export type { SurfaceAccess, SurfaceActErr, SurfaceActOk, SurfaceActResult, SurfaceChangedEvent, SurfaceFetch, SurfaceLoad, SurfaceTransport, SurfaceUploadBody, } from "./transport.js";
+export type { JsonObject, JsonValue } from "../json.js";

package/dist/blocks/index.js

@@ -0,0 +1,20 @@
+/**
+ * `@sigrun/shared/blocks` — the block-set foundation (UI-blocks U0).
+ *
+ * One entry point for the wire types (§4/§5/§6.1), the data-op applier
+ * (§4.3), the icon names (§10.2), display downsampling (§5.4), and the
+ * channel-facing surface transport. Consumed by the server, the webui
+ * and the TUI alike; re-exported for extensions through
+ * `@sigrun/sigrun/blocks` (U0 Task 4).
+ *
+ * The runtime half is deliberately tiny and dependency-free: the purity
+ * guard (`test/views-purity.test.ts`) holds every specifier inside
+ * `shared/src/`.
+ */
+// ─── Runtime (pure, dependency-free) ──────────────────────────────────────
+export { BLOCK_SET_VERSION } from "./types.js";
+export { DataOpError, applyOps, resolvePointer } from "./ops.js";
+export { ICON_NAMES } from "./icons.js";
+export { lttb } from "./lttb.js";
+export { formatValue } from "./format.js";
+export { toText } from "./text.js";

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;