@calliopelabs/ui 0.14.0 → 0.18.0

package/dist/workbench/keys.js

@@ -0,0 +1,105 @@
+/**
+ * Keyboard chords as strings: `"Mod+K"`, `"Mod+Shift+A"`, `"Alt+ArrowLeft"`,
+ * `"F2"`. `Mod` is Command on a Mac and Control elsewhere, so one binding
+ * serves both. Pure: parsing, matching and display, no listeners.
+ */
+const MODIFIERS = new Set(["mod", "ctrl", "control", "meta", "cmd", "alt", "option", "shift"]);
+export function parseShortcut(shortcut) {
+    const chord = {
+        key: "",
+        mod: false,
+        ctrl: false,
+        meta: false,
+        alt: false,
+        shift: false,
+    };
+    // "Mod++" binds the plus key: the last part is the key, even when empty.
+    const plus = shortcut === "+" || shortcut.endsWith("++");
+    const parts = (plus ? shortcut.slice(0, -1) : shortcut).split("+");
+    const last = parts.pop() ?? "";
+    const raw = plus ? "+" : last;
+    for (const part of parts) {
+        const p = part.trim().toLowerCase();
+        if (!MODIFIERS.has(p))
+            throw new Error(`Unknown modifier "${part}" in "${shortcut}"`);
+        if (p === "mod")
+            chord.mod = true;
+        else if (p === "ctrl" || p === "control")
+            chord.ctrl = true;
+        else if (p === "meta" || p === "cmd")
+            chord.meta = true;
+        else if (p === "alt" || p === "option")
+            chord.alt = true;
+        else
+            chord.shift = true;
+    }
+    const key = raw.trim() || raw;
+    chord.key = key.length === 1 ? key.toLowerCase() : key;
+    return chord;
+}
+export function isMacPlatform() {
+    if (typeof navigator === "undefined")
+        return false;
+    const nav = navigator;
+    return /mac|iphone|ipad/i.test(nav.userAgentData?.platform ?? nav.platform ?? "");
+}
+/** The key a physical code stands for, so Alt and Shift layouts still match letters and digits. */
+function keyFromCode(code) {
+    const m = /^(?:Key([A-Z])|Digit(\d))$/.exec(code);
+    if (!m)
+        return null;
+    return (m[1] ?? m[2] ?? "").toLowerCase();
+}
+export function matchesShortcut(event, shortcut, isMac = isMacPlatform()) {
+    const chord = typeof shortcut === "string" ? parseShortcut(shortcut) : shortcut;
+    const wantCtrl = chord.ctrl || (chord.mod && !isMac);
+    const wantMeta = chord.meta || (chord.mod && isMac);
+    if (event.ctrlKey !== wantCtrl || event.metaKey !== wantMeta || event.altKey !== chord.alt) {
+        return false;
+    }
+    const key = event.key.length === 1 ? event.key.toLowerCase() : event.key;
+    // A shifted symbol ("?" for Shift+/) carries its shift in the key itself.
+    if (event.shiftKey !== chord.shift &&
+        !(key === chord.key && key.length === 1 && !/[a-z0-9]/.test(key))) {
+        return false;
+    }
+    return key === chord.key || keyFromCode(event.code) === chord.key;
+}
+const MAC_GLYPH = {
+    mod: "⌘",
+    meta: "⌘",
+    ctrl: "⌃",
+    alt: "⌥",
+    shift: "⇧",
+};
+const KEY_NAME = {
+    ArrowUp: "↑",
+    ArrowDown: "↓",
+    ArrowLeft: "←",
+    ArrowRight: "→",
+    Enter: "Enter",
+    Escape: "Esc",
+    Backspace: "Backspace",
+    Delete: "Del",
+    " ": "Space",
+};
+/** The keys of a chord as they are drawn: `["⌘", "K"]` on a Mac, `["Ctrl", "K"]` elsewhere. */
+export function shortcutKeys(shortcut, isMac = isMacPlatform()) {
+    const chord = parseShortcut(shortcut);
+    const keys = [];
+    const add = (name, label) => keys.push(isMac ? (MAC_GLYPH[name] ?? label) : label);
+    if (chord.ctrl || (chord.mod && !isMac))
+        add("ctrl", "Ctrl");
+    if (chord.alt)
+        add("alt", "Alt");
+    if (chord.shift)
+        add("shift", "Shift");
+    if (chord.meta || (chord.mod && isMac))
+        add("meta", "Meta");
+    keys.push(KEY_NAME[chord.key] ?? (chord.key.length === 1 ? chord.key.toUpperCase() : chord.key));
+    return keys;
+}
+/** One string for a menu or a tooltip: `"⌘K"` on a Mac, `"Ctrl+K"` elsewhere. */
+export function formatShortcut(shortcut, isMac = isMacPlatform()) {
+    return shortcutKeys(shortcut, isMac).join(isMac ? "" : "+");
+}

package/dist/workbench/model.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The file browser's data: plain values the host maps its own listing onto.
+ * Pure (no "use client"), so a server can sort or build fixtures with it.
+ */
+export type FileKind = "file" | "directory";
+/** One entry of a listing. `path` is its identity: unique, `/`-separated, no leading slash. */
+export interface FileItem {
+    path: string;
+    name: string;
+    kind: FileKind;
+    /** Bytes. Absent or null for directories and unknown sizes. */
+    size?: number | null;
+    /** ISO 8601 or a Date. */
+    modified?: string | Date | null;
+    mimeType?: string | null;
+}
+export type FileSortKey = "name" | "size" | "modified" | "kind";
+export interface FileSort {
+    key: FileSortKey;
+    dir: "asc" | "desc";
+}
+export type FileView = "list" | "grid";
+/** Where an upload stands. */
+export type UploadState = "queued" | "uploading" | "done" | "error" | "canceled";
+/**
+ * A directory's children as the host knows them. Absent from the map means
+ * "never asked for": the tree calls `onLoad` when it first opens.
+ */
+export type FileBranch = {
+    state: "loading";
+} | {
+    state: "error";
+    message?: string;
+} | {
+    state: "ready";
+    items: readonly FileItem[];
+};
+/** The parent directory of a path; the root is "". */
+export declare function parentPath(path: string): string;
+/** A path under a directory; the root is "". */
+export declare function joinPath(dir: string, name: string): string;
+/** True when `path` is `ancestor` or lies under it. */
+export declare function isWithin(path: string, ancestor: string): boolean;
+/** The lower-case extension without the dot, or "" (".bashrc" has none). */
+export declare function fileExtension(name: string): string;
+/** The breadcrumb trail of a path: the root, then each directory down to it. */
+export declare function pathSegments(path: string): {
+    name: string;
+    path: string;
+}[];
+/**
+ * Whether moving `sources` into `target` does anything sensible: never into
+ * itself or its own subtree, and a move into the folder it is already in is
+ * a no-op. Copies (`copy`) may land in the same folder.
+ */
+export declare function canDrop(sources: readonly string[], target: string, copy?: boolean): boolean;
+/**
+ * A listing in display order: directories first, then by the key, ties and
+ * missing values by name. Natural order, so "file10" follows "file9".
+ */
+export declare function sortFiles(items: readonly FileItem[], sort: FileSort): FileItem[];
+/** Bytes for people: 0 B, 912 B, 1.5 KB, 23 MB (1024-based, as file managers show). */
+export declare function formatBytes(bytes: number, locale?: string): string;
+/** What a preview can show for a file, from its name and MIME type. */
+export type PreviewKind = "csv" | "json" | "image" | "markdown" | "text" | "binary";
+export declare function previewKindFor(name: string, mimeType?: string | null): PreviewKind;
+/**
+ * Parses CSV (RFC 4180: quoted fields, doubled quotes, newlines inside
+ * quotes) or, with `delimiter: "\t"`, TSV. Returns rows of strings; the
+ * caller decides whether the first row is a header.
+ */
+export declare function parseDelimited(text: string, delimiter?: string): string[][];

package/dist/workbench/model.js

@@ -0,0 +1,214 @@
+/**
+ * The file browser's data: plain values the host maps its own listing onto.
+ * Pure (no "use client"), so a server can sort or build fixtures with it.
+ */
+/** The parent directory of a path; the root is "". */
+export function parentPath(path) {
+    const i = path.lastIndexOf("/");
+    return i < 0 ? "" : path.slice(0, i);
+}
+/** A path under a directory; the root is "". */
+export function joinPath(dir, name) {
+    return dir ? `${dir}/${name}` : name;
+}
+/** True when `path` is `ancestor` or lies under it. */
+export function isWithin(path, ancestor) {
+    return ancestor === "" || path === ancestor || path.startsWith(`${ancestor}/`);
+}
+/** The lower-case extension without the dot, or "" (".bashrc" has none). */
+export function fileExtension(name) {
+    const i = name.lastIndexOf(".");
+    return i > 0 ? name.slice(i + 1).toLowerCase() : "";
+}
+/** The breadcrumb trail of a path: the root, then each directory down to it. */
+export function pathSegments(path) {
+    const parts = path.split("/").filter(Boolean);
+    return parts.map((name, i) => ({ name, path: parts.slice(0, i + 1).join("/") }));
+}
+/**
+ * Whether moving `sources` into `target` does anything sensible: never into
+ * itself or its own subtree, and a move into the folder it is already in is
+ * a no-op. Copies (`copy`) may land in the same folder.
+ */
+export function canDrop(sources, target, copy = false) {
+    return (sources.length > 0 &&
+        sources.every((src) => !(target === src || target.startsWith(`${src}/`)) && (copy || parentPath(src) !== target)));
+}
+const collator = new Intl.Collator(undefined, { numeric: true, sensitivity: "base" });
+function time(value) {
+    if (value == null)
+        return null;
+    const t = value instanceof Date ? value.getTime() : Date.parse(value);
+    return Number.isNaN(t) ? null : t;
+}
+/**
+ * A listing in display order: directories first, then by the key, ties and
+ * missing values by name. Natural order, so "file10" follows "file9".
+ */
+export function sortFiles(items, sort) {
+    const sign = sort.dir === "asc" ? 1 : -1;
+    const byName = (a, b) => collator.compare(a.name, b.name);
+    const compare = (a, b) => {
+        switch (sort.key) {
+            case "size": {
+                const x = a.size ?? null;
+                const y = b.size ?? null;
+                if (x === y)
+                    return 0;
+                if (x === null)
+                    return 1;
+                if (y === null)
+                    return -1;
+                return (x - y) * sign;
+            }
+            case "modified": {
+                const x = time(a.modified);
+                const y = time(b.modified);
+                if (x === y)
+                    return 0;
+                if (x === null)
+                    return 1;
+                if (y === null)
+                    return -1;
+                return (x - y) * sign;
+            }
+            case "kind":
+                return collator.compare(fileExtension(a.name), fileExtension(b.name)) * sign;
+            case "name":
+                return byName(a, b) * sign;
+        }
+    };
+    return [...items].sort((a, b) => {
+        if (a.kind !== b.kind)
+            return a.kind === "directory" ? -1 : 1;
+        return compare(a, b) || byName(a, b);
+    });
+}
+/** Bytes for people: 0 B, 912 B, 1.5 KB, 23 MB (1024-based, as file managers show). */
+export function formatBytes(bytes, locale) {
+    if (!Number.isFinite(bytes) || bytes < 0)
+        return "";
+    const units = ["B", "KB", "MB", "GB", "TB", "PB"];
+    let value = bytes;
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit++;
+    }
+    const digits = unit === 0 || value >= 10 ? 0 : 1;
+    return `${value.toLocaleString(locale, { maximumFractionDigits: digits })} ${units[unit]}`;
+}
+const TEXT_EXTENSIONS = new Set([
+    "txt",
+    "log",
+    "py",
+    "js",
+    "jsx",
+    "ts",
+    "tsx",
+    "mjs",
+    "cjs",
+    "rs",
+    "go",
+    "java",
+    "kt",
+    "rb",
+    "sh",
+    "bash",
+    "zsh",
+    "sql",
+    "html",
+    "css",
+    "scss",
+    "xml",
+    "yaml",
+    "yml",
+    "toml",
+    "ini",
+    "cfg",
+    "conf",
+    "env",
+    "r",
+    "c",
+    "h",
+    "cpp",
+    "hpp",
+    "cs",
+    "php",
+    "swift",
+    "lua",
+    "dockerfile",
+    "tf",
+]);
+const IMAGE_EXTENSIONS = new Set([
+    "png",
+    "jpg",
+    "jpeg",
+    "gif",
+    "svg",
+    "webp",
+    "avif",
+    "bmp",
+    "ico",
+]);
+export function previewKindFor(name, mimeType) {
+    const ext = fileExtension(name);
+    if (ext === "csv" || ext === "tsv" || mimeType === "text/csv")
+        return "csv";
+    if (ext === "json" || ext === "jsonl" || ext === "ipynb" || mimeType === "application/json")
+        return "json";
+    if (IMAGE_EXTENSIONS.has(ext) || mimeType?.startsWith("image/"))
+        return "image";
+    if (ext === "md" || ext === "markdown" || mimeType === "text/markdown")
+        return "markdown";
+    if (TEXT_EXTENSIONS.has(ext) || mimeType?.startsWith("text/"))
+        return "text";
+    return "binary";
+}
+/**
+ * Parses CSV (RFC 4180: quoted fields, doubled quotes, newlines inside
+ * quotes) or, with `delimiter: "\t"`, TSV. Returns rows of strings; the
+ * caller decides whether the first row is a header.
+ */
+export function parseDelimited(text, delimiter = ",") {
+    const rows = [];
+    let row = [];
+    let field = "";
+    let quoted = false;
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i];
+        if (quoted) {
+            if (c === '"') {
+                if (text[i + 1] === '"') {
+                    field += '"';
+                    i++;
+                }
+                else
+                    quoted = false;
+            }
+            else
+                field += c;
+        }
+        else if (c === '"' && field === "")
+            quoted = true;
+        else if (c === delimiter) {
+            row.push(field);
+            field = "";
+        }
+        else if (c === "\n" || c === "\r") {
+            if (c === "\r" && text[i + 1] === "\n")
+                i++;
+            row.push(field);
+            rows.push(row);
+            row = [];
+            field = "";
+        }
+        else
+            field += c;
+    }
+    if (field !== "" || row.length > 0) {
+        row.push(field);
+        rows.push(row);
+    }
+    return rows;
+}

package/dist/workbench/palette.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The command palette's matching: pure, so a host can rank its own lists
+ * with the same rules the palette uses.
+ */
+/**
+ * How well `query` matches `text` as a subsequence, higher is better, or -1
+ * when it does not match. Consecutive characters, word starts and an exact
+ * prefix score more, so "nq" ranks "New Query" above "Run query".
+ */
+export declare function fuzzyScore(text: string, query: string): number;
+export interface PaletteMatchable {
+    label: string;
+    keywords?: string;
+    group?: string;
+}
+/** The items that match, best first; ties keep the given order. */
+export declare function rankItems<T extends PaletteMatchable>(items: readonly T[], query: string): T[];

package/dist/workbench/palette.js

@@ -0,0 +1,45 @@
+/**
+ * The command palette's matching: pure, so a host can rank its own lists
+ * with the same rules the palette uses.
+ */
+/**
+ * How well `query` matches `text` as a subsequence, higher is better, or -1
+ * when it does not match. Consecutive characters, word starts and an exact
+ * prefix score more, so "nq" ranks "New Query" above "Run query".
+ */
+export function fuzzyScore(text, query) {
+    const q = query.trim().toLowerCase();
+    if (q === "")
+        return 0;
+    const t = text.toLowerCase();
+    if (t.startsWith(q))
+        return 1000 - t.length;
+    let score = 0;
+    let ti = 0;
+    let streak = 0;
+    for (const ch of q) {
+        if (ch === " ")
+            continue;
+        const found = t.indexOf(ch, ti);
+        if (found === -1)
+            return -1;
+        const wordStart = found === 0 || /[\s\-_./:]/.test(t[found - 1] ?? "");
+        streak = found === ti ? streak + 1 : 0;
+        score += 1 + streak * 3 + (wordStart ? 8 : 0) - Math.min(found - ti, 10) * 0.1;
+        ti = found + 1;
+    }
+    return score;
+}
+/** The items that match, best first; ties keep the given order. */
+export function rankItems(items, query) {
+    if (query.trim() === "")
+        return [...items];
+    return items
+        .map((item, index) => {
+        const score = Math.max(fuzzyScore(item.label, query), item.keywords ? fuzzyScore(item.keywords, query) - 1 : -1);
+        return { item, index, score };
+    })
+        .filter((r) => r.score >= 0)
+        .sort((a, b) => b.score - a.score || a.index - b.index)
+        .map((r) => r.item);
+}

package/dist/workbench/pending.d.ts

@@ -0,0 +1,92 @@
+import { type ColumnType, type GridRow } from "./grid-model.js";
+export type PendingState = "modified" | "added" | "deleted";
+/** One row that differs from what the host holds. */
+export interface PendingRow {
+    state: PendingState;
+    /** The row as it was read; empty for an inserted row. */
+    original: GridRow;
+    /** The row as it will be written. */
+    values: GridRow;
+}
+export interface PendingChanges {
+    readonly rows: ReadonlyMap<number, PendingRow>;
+    /** Rows inserted so far, for the next insert's key. */
+    readonly inserted: number;
+}
+export declare const NO_CHANGES: PendingChanges;
+/**
+ * Sets one cell. `source` is the row as read (unused for an inserted row).
+ * An edit back to the original value drops the row's entry.
+ */
+export declare function editCell(changes: PendingChanges, key: number, column: string, value: unknown, source: GridRow | undefined): PendingChanges;
+/** Inserts a row of NULLs, or a copy of `from` (duplicate). Returns the new row's key. */
+export declare function addRow(changes: PendingChanges, columns: readonly string[], from?: GridRow): {
+    changes: PendingChanges;
+    key: number;
+};
+/** Marks rows deleted; an inserted row is simply dropped. */
+export declare function deleteRows(changes: PendingChanges, keys: Iterable<number>, sourceOf: (key: number) => GridRow | undefined): PendingChanges;
+/** Forgets every change to one row (an inserted row disappears). */
+export declare function revertRow(changes: PendingChanges, key: number): PendingChanges;
+/** The value a cell shows: the pending value when there is one. */
+export declare function pendingValue(changes: PendingChanges, key: number, column: string, source: GridRow | undefined): unknown;
+/** True when the cell will be written: every cell of an inserted row, the edited cells of a modified one. */
+export declare function isCellChanged(changes: PendingChanges, key: number, column: string): boolean;
+/** The keys of the inserted rows, in the order they were added. */
+export declare function insertedKeys(changes: PendingChanges): number[];
+export interface PendingCounts {
+    inserts: number;
+    updates: number;
+    deletes: number;
+    total: number;
+}
+export declare function pendingCounts(changes: PendingChanges): PendingCounts;
+/** One statement's worth of a commit. `key` is the grid's row key, for reporting a failure back. */
+export interface ChangeSetInsert {
+    key: number;
+    /** The cells the person filled; an untouched NULL is left to the column's default. */
+    values: Record<string, unknown>;
+}
+export interface ChangeSetUpdate {
+    key: number;
+    /** The primary key values the row was read under. */
+    primaryKey: Record<string, unknown>;
+    /** The changed cells only. */
+    values: Record<string, unknown>;
+    /** The old values of exactly those cells, for an optimistic-concurrency check (JSON and binary cells left out). */
+    expected: Record<string, unknown>;
+}
+export interface ChangeSetDelete {
+    key: number;
+    primaryKey: Record<string, unknown>;
+}
+/** What a commit hands the host. */
+export interface ChangeSet {
+    inserts: ChangeSetInsert[];
+    updates: ChangeSetUpdate[];
+    deletes: ChangeSetDelete[];
+}
+/**
+ * The pending changes as a batch to write. Updates and deletes are keyed on
+ * `primaryKeys`; without one they cannot name a row, and the grid only
+ * offers inserts.
+ */
+export declare function toChangeSet(changes: PendingChanges, options: {
+    columns: readonly string[];
+    primaryKeys: readonly string[];
+}): ChangeSet;
+/**
+ * A change set as SQL statements, for a host that runs SQL rather than an
+ * apply endpoint: INSERT, UPDATE ... WHERE <primary key>, DELETE ... WHERE
+ * <primary key>. Literals are quoted by `sqlLiteral`; dialect differences
+ * beyond ANSI quoting are the host's.
+ */
+export declare function changeSetToSql(changeSet: ChangeSet, options: {
+    table: string;
+}): string[];
+/**
+ * What a typed cell means: empty or "NULL" is NULL; a number or boolean
+ * column (by its type, or the original value's) keeps its type when the
+ * text parses as one.
+ */
+export declare function parseCellInput(text: string, original: unknown, type?: ColumnType): unknown;