@x-tech-laboratories/x-libs 0.4.0 → 0.7.0

package/dist/electron/window.d.ts

@@ -0,0 +1,96 @@
+export interface Rectangle {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface BrowserWindowOptionsLike {
+    title: string;
+    icon?: string;
+    x?: number;
+    y?: number;
+    width: number;
+    height: number;
+    minWidth?: number;
+    minHeight?: number;
+    show: boolean;
+    backgroundColor: string;
+    titleBarStyle?: "default" | "hidden" | "hiddenInset";
+    webPreferences: {
+        preload?: string;
+        sandbox: boolean;
+        contextIsolation: boolean;
+        nodeIntegration: boolean;
+        backgroundThrottling: boolean;
+    };
+}
+export interface NavigationEventLike {
+    preventDefault(): void;
+}
+export interface BrowserWindowLike {
+    webContents: {
+        setWindowOpenHandler(handler: (details: {
+            url: string;
+        }) => {
+            action: "deny";
+        }): void;
+        on(event: "will-navigate", listener: (event: NavigationEventLike, url: string) => void): unknown;
+    };
+    on(event: string, listener: () => void): unknown;
+    once(event: string, listener: () => void): unknown;
+    show(): void;
+    maximize(): void;
+    isMaximized(): boolean;
+    getNormalBounds(): Rectangle;
+    setBackgroundColor(color: string): void;
+    loadURL(url: string): Promise<void>;
+    loadFile(path: string): Promise<void>;
+}
+export interface NativeThemeLike {
+    shouldUseDarkColors: boolean;
+    on(event: "updated", listener: () => void): unknown;
+    removeListener(event: "updated", listener: () => void): unknown;
+}
+export interface ShellLike {
+    openExternal(url: string): Promise<void>;
+}
+export interface ScreenLike {
+    getAllDisplays(): {
+        workArea: Rectangle;
+    }[];
+}
+export interface Size {
+    width: number;
+    height: number;
+}
+export interface WindowOptions {
+    title: string;
+    icon?: string;
+    preload?: string;
+    dev_url?: string;
+    file: string;
+    default_size: Size;
+    min_size?: Size;
+    state_file?: string;
+    native_theme: NativeThemeLike;
+    shell: ShellLike;
+    screen?: ScreenLike;
+    background?: {
+        light: string;
+        dark: string;
+    };
+    sandbox?: boolean;
+    background_throttling?: boolean;
+    title_bar_style?: "default" | "hidden" | "hiddenInset";
+    before_write?: (path: string) => void;
+    save_delay_ms?: number;
+}
+export interface WindowState {
+    bounds: Rectangle;
+    is_maximized: boolean;
+}
+export declare function read_window_state(state_file: string): WindowState | null;
+export declare function write_window_state(state_file: string, state: WindowState): void;
+export declare function is_external_link(url: string): boolean;
+export declare function is_app_page(url: string, options: Pick<WindowOptions, "dev_url" | "file">): boolean;
+export declare function create_window<Window extends BrowserWindowLike>(BrowserWindow: new (options: BrowserWindowOptionsLike) => Window, options: WindowOptions): Window;

package/dist/electron/window.js

@@ -0,0 +1,128 @@
+// An Electron app's main window: links and pages of other sites open in the browser, the background follows the system theme, and its size and place are remembered.
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { pathToFileURL } from "node:url";
+const DEFAULT_BACKGROUND = { light: "#f5f6f8", dark: "#0f1115" };
+const DEFAULT_SAVE_DELAY_MS = 500;
+// ── State file ───────────────────────────────────────────────────────────────
+// A missing, unreadable or malformed file reads as no saved state.
+export function read_window_state(state_file) {
+    try {
+        const state = JSON.parse(readFileSync(state_file, "utf8"));
+        const bounds = state.bounds;
+        const is_whole = (value) => Number.isInteger(value);
+        if (!bounds || ![bounds.x, bounds.y, bounds.width, bounds.height].every(is_whole) || bounds.width <= 0 || bounds.height <= 0)
+            return null;
+        return { bounds, is_maximized: state.is_maximized === true };
+    }
+    catch {
+        return null;
+    }
+}
+// Writes beside the file and renames over it, so a crash mid-write never leaves half a file.
+export function write_window_state(state_file, state) {
+    mkdirSync(dirname(state_file), { recursive: true });
+    const temporary_file = `${state_file}.tmp`;
+    writeFileSync(temporary_file, JSON.stringify(state));
+    renameSync(temporary_file, state_file);
+}
+function overlaps(first, second) {
+    return first.x < second.x + second.width && second.x < first.x + first.width && first.y < second.y + second.height && second.y < first.y + first.height;
+}
+// ── Links ────────────────────────────────────────────────────────────────────
+const EXTERNAL_SCHEMES = new Set(["http:", "https:", "mailto:"]);
+// Only web and mail links reach the browser, never a file or another app's scheme.
+export function is_external_link(url) {
+    try {
+        return EXTERNAL_SCHEMES.has(new URL(url).protocol);
+    }
+    catch {
+        return false;
+    }
+}
+// True for the app's own pages: the dev server's origin, or files beside the built page.
+export function is_app_page(url, options) {
+    try {
+        const target = new URL(url);
+        if (options.dev_url)
+            return target.origin === new URL(options.dev_url).origin;
+        const page_folder = new URL(".", pathToFileURL(options.file)).href;
+        return target.protocol === "file:" && target.href.startsWith(page_folder);
+    }
+    catch {
+        return false;
+    }
+}
+function open_outside(shell, url) {
+    if (is_external_link(url))
+        void shell.openExternal(url);
+}
+// ── Window ───────────────────────────────────────────────────────────────────
+export function create_window(BrowserWindow, options) {
+    const background = options.background ?? DEFAULT_BACKGROUND;
+    const background_color = () => options.native_theme.shouldUseDarkColors ? background.dark : background.light;
+    const saved = options.state_file ? read_window_state(options.state_file) : null;
+    const on_a_screen = saved && (!options.screen || options.screen.getAllDisplays().some((display) => overlaps(saved.bounds, display.workArea)));
+    const size = saved?.bounds ?? options.default_size;
+    const window = new BrowserWindow({
+        title: options.title,
+        icon: options.icon,
+        ...(on_a_screen ? { x: saved.bounds.x, y: saved.bounds.y } : {}),
+        width: size.width,
+        height: size.height,
+        minWidth: options.min_size?.width,
+        minHeight: options.min_size?.height,
+        show: false,
+        backgroundColor: background_color(),
+        ...(options.title_bar_style ? { titleBarStyle: options.title_bar_style } : {}),
+        webPreferences: { preload: options.preload, sandbox: options.sandbox ?? false, contextIsolation: true, nodeIntegration: false, backgroundThrottling: options.background_throttling ?? true },
+    });
+    window.once("ready-to-show", () => {
+        if (saved?.is_maximized)
+            window.maximize();
+        window.show();
+    });
+    window.webContents.setWindowOpenHandler(({ url }) => {
+        open_outside(options.shell, url);
+        return { action: "deny" };
+    });
+    // A link that would load another site in the window opens in the browser instead.
+    window.webContents.on("will-navigate", (event, url) => {
+        if (is_app_page(url, options))
+            return;
+        event.preventDefault();
+        open_outside(options.shell, url);
+    });
+    const follow_theme = () => window.setBackgroundColor(background_color());
+    options.native_theme.on("updated", follow_theme);
+    window.on("closed", () => options.native_theme.removeListener("updated", follow_theme));
+    if (options.state_file)
+        remember_state(window, options.state_file, options.save_delay_ms ?? DEFAULT_SAVE_DELAY_MS, options.before_write);
+    if (options.dev_url)
+        void window.loadURL(options.dev_url);
+    else
+        void window.loadFile(options.file);
+    return window;
+}
+// Saves a moment after the last move or resize, and at once when the window closes.
+function remember_state(window, state_file, save_delay_ms, before_write) {
+    let timer;
+    const save_now = () => {
+        clearTimeout(timer);
+        timer = undefined;
+        try {
+            before_write?.(state_file);
+            write_window_state(state_file, { bounds: window.getNormalBounds(), is_maximized: window.isMaximized() });
+        }
+        catch {
+            // A refused or failed save keeps the last one, and the window carries on.
+        }
+    };
+    const save_soon = () => {
+        clearTimeout(timer);
+        timer = setTimeout(save_now, save_delay_ms);
+    };
+    for (const event of ["resize", "move", "maximize", "unmaximize"])
+        window.on(event, save_soon);
+    window.on("close", save_now);
+}

package/dist/log.d.ts

@@ -0,0 +1,30 @@
+export type Level = "critical" | "error" | "warn" | "info" | "debug";
+export declare const levels: Level[];
+export declare const default_level: Level;
+export interface LevelSpec {
+    default: Level;
+    scopes: Record<string, Level>;
+}
+export declare function parse_level_spec(spec: string | undefined, fallback?: Level): LevelSpec;
+export declare function level_for(spec: LevelSpec, scope: string): Level;
+export declare function is_enabled(spec: LevelSpec, scope: string, level: Level): boolean;
+export interface LogRecord {
+    at: number;
+    level: Level;
+    scope: string;
+    message: string;
+    data?: unknown;
+}
+export type LogSink = (record: LogRecord) => void;
+export declare function format_record(record: LogRecord): string;
+export interface Logger {
+    critical(message: string, data?: unknown): void;
+    error(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    info(message: string, data?: unknown): void;
+    debug(message: string, data?: unknown): void;
+    enabled(level: Level): boolean;
+    child(scope: string): Logger;
+}
+export type SpecSource = LevelSpec | (() => LevelSpec);
+export declare function create_logger(scope: string, spec: SpecSource, sink: LogSink): Logger;

package/dist/log.js

@@ -0,0 +1,79 @@
+// Logging by scope and level, such as "warn,play:debug", where a mistake in the setting never silences logging.
+const level_order = { critical: 0, error: 1, warn: 2, info: 3, debug: 4 };
+export const levels = Object.keys(level_order);
+const level_aliases = {
+    crit: "critical", critical: "critical",
+    err: "error", error: "error",
+    warn: "warn", warning: "warn",
+    info: "info",
+    debug: "debug", verbose: "debug", trace: "debug",
+};
+export const default_level = "info";
+// ── Parsing ──────────────────────────────────────────────────────────────────
+// A bare level sets the default and "scope:level" one scope; entries it cannot read are skipped.
+export function parse_level_spec(spec, fallback = default_level) {
+    const parsed = { default: fallback, scopes: {} };
+    if (!spec)
+        return parsed;
+    for (const raw_part of spec.split(",")) {
+        const part = raw_part.trim().toLowerCase();
+        if (part === "")
+            continue;
+        // Scopes hold colons of their own, so the level follows the last one.
+        const colon = part.lastIndexOf(":");
+        if (colon === -1) {
+            const level = level_aliases[part];
+            if (level)
+                parsed.default = level;
+            continue;
+        }
+        const scope = part.slice(0, colon).trim();
+        const level = level_aliases[part.slice(colon + 1).trim()];
+        if (!level || scope === "")
+            continue;
+        if (scope === "*")
+            parsed.default = level;
+        else
+            parsed.scopes[scope] = level;
+    }
+    return parsed;
+}
+export function level_for(spec, scope) {
+    return spec.scopes[scope] ?? spec.default;
+}
+export function is_enabled(spec, scope, level) {
+    return level_order[level] <= level_order[level_for(spec, scope)];
+}
+const two_digits = (count) => String(count).padStart(2, "0");
+// A line in fixed columns, such as "10:33:35.123 WARN     play      message {"detail":1}".
+export function format_record(record) {
+    const date = new Date(record.at);
+    const time = `${two_digits(date.getHours())}:${two_digits(date.getMinutes())}:${two_digits(date.getSeconds())}.${String(date.getMilliseconds()).padStart(3, "0")}`;
+    let line = `${time} ${record.level.toUpperCase().padEnd(8)} ${record.scope.padEnd(9)} ${record.message}`;
+    if (record.data !== undefined) {
+        try {
+            line += ` ${JSON.stringify(record.data)}`;
+        }
+        catch {
+            line += " [unserializable]";
+        }
+    }
+    return line;
+}
+const resolve_spec = (source) => typeof source === "function" ? source() : source;
+export function create_logger(scope, spec, sink) {
+    const emit = (level, message, data) => {
+        if (!is_enabled(resolve_spec(spec), scope, level))
+            return;
+        sink({ at: Date.now(), level, scope, message, data });
+    };
+    return {
+        critical: (message, data) => emit("critical", message, data),
+        error: (message, data) => emit("error", message, data),
+        warn: (message, data) => emit("warn", message, data),
+        info: (message, data) => emit("info", message, data),
+        debug: (message, data) => emit("debug", message, data),
+        enabled: (level) => is_enabled(resolve_spec(spec), scope, level),
+        child: (child_scope) => create_logger(`${scope}:${child_scope}`, spec, sink),
+    };
+}

package/dist/server/backup_files.d.ts

@@ -0,0 +1,3 @@
+import type { BackupNaming, BackupStore } from "../backups.ts";
+export declare function backup_path(folder: string, naming: BackupNaming, name: string): string;
+export declare function file_backup_store(folder: () => string, naming: BackupNaming, copy_to: (path: string) => void): BackupStore;

package/dist/server/backup_files.js

@@ -0,0 +1,25 @@
+// Backups kept as files in a folder on disk, for an app's main process or server.
+import { mkdirSync, readdirSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+// The path of a backup in the folder, refusing any name the naming did not write.
+export function backup_path(folder, naming, name) {
+    if (!naming.pattern.test(name))
+        throw new Error(`not a backup name: ${name}`);
+    return join(folder, name);
+}
+// A folder of backup files, made when first used; copy_to writes the app's data to the path it is given, such as through SQLite's own backup.
+export function file_backup_store(folder, naming, copy_to) {
+    const path_of = (name) => backup_path(folder(), naming, name);
+    return {
+        list: () => {
+            mkdirSync(folder(), { recursive: true });
+            return readdirSync(folder()).filter((name) => naming.pattern.test(name)).map((name) => ({ name, size_bytes: statSync(path_of(name)).size }));
+        },
+        take: (name) => {
+            mkdirSync(folder(), { recursive: true });
+            copy_to(path_of(name));
+            return statSync(path_of(name)).size;
+        },
+        remove: (name) => rmSync(path_of(name)),
+    };
+}

package/dist/web/drag.d.ts

@@ -0,0 +1,3 @@
+export declare function set_drag_badge(event: {
+    dataTransfer: DataTransfer | null;
+}, label: string, class_name?: string): void;

package/dist/web/drag.js

@@ -0,0 +1,13 @@
+// What a drag shows under the pointer.
+// Shows a small badge such as "3 tasks" under the pointer as the drag image, in place of a picture of the grabbed row.
+export function set_drag_badge(event, label, class_name = "drag-badge") {
+    if (!event.dataTransfer)
+        return;
+    const badge = document.createElement("div");
+    badge.className = class_name;
+    badge.textContent = label;
+    document.body.append(badge);
+    event.dataTransfer.setDragImage(badge, -12, -12);
+    // The browser takes its picture of the badge during this event, so it can go once the event is over.
+    setTimeout(() => badge.remove(), 0);
+}

package/dist/web/format.d.ts

@@ -8,3 +8,4 @@ export declare function size(count: number | null | undefined): string;
 export declare function size_change(count: number | null | undefined): string;
 export declare function count_change(value: number | null | undefined): string;
 export declare function plural(count: number, word: string): string;
+export declare function compact_count(count: number): string;

package/dist/web/format.js

@@ -75,3 +75,8 @@ export function count_change(value) {
 export function plural(count, word) {
     return `${count.toLocaleString()} ${word}${plurals.select(count) === "one" ? "" : "s"}`;
 }
+const compact = new Intl.NumberFormat("en", { notation: "compact", maximumFractionDigits: 1 });
+// A count in a few characters, such as "1.4M", "150K" or "950".
+export function compact_count(count) {
+    return compact.format(count);
+}

package/dist/web/menus.d.ts

@@ -6,8 +6,12 @@ export interface MenuItem {
     danger?: boolean;
     separator_before?: boolean;
     checked?: boolean;
+    radio?: boolean;
+    keep_open?: boolean;
 }
 export declare function on_screen_position(x: number, y: number, width: number, height: number, room_width?: number, room_height?: number): {
     left: number;
     top: number;
 };
+export declare function item_after_key(key: string, current: number, count: number): number | null;
+export declare function item_starting_with(labels: readonly string[], typed: string, current: number): number | null;

package/dist/web/menus.js

@@ -1,4 +1,4 @@
-// What a menu item holds, and where a menu opened at a point goes so it stays on screen.
+// What a menu item holds, where a menu opened at a point goes so it stays on screen, and which item a key moves to.
 const edge_gap = 4;
 // Flipped to the point's other side near an edge, or pushed back from the edge when neither side has room.
 export function on_screen_position(x, y, width, height, room_width = window.innerWidth, room_height = window.innerHeight) {
@@ -11,3 +11,30 @@ export function on_screen_position(x, y, width, height, room_width = window.inne
     };
     return { left: place(x, width, room_width), top: place(y, height, room_height) };
 }
+// ── Keys ─────────────────────────────────────────────────────────────────────
+// The item an arrow, Home or End key moves to from the current one, wrapping round, or null for any other key.
+export function item_after_key(key, current, count) {
+    if (count === 0)
+        return null;
+    switch (key) {
+        case "ArrowDown": return current < 0 ? 0 : (current + 1) % count;
+        case "ArrowUp": return current < 0 ? count - 1 : (current - 1 + count) % count;
+        case "Home": return 0;
+        case "End": return count - 1;
+        default: return null;
+    }
+}
+// The first item after the current one whose label starts with the typed text, or null when none does.
+export function item_starting_with(labels, typed, current) {
+    const wanted = typed.toLocaleLowerCase();
+    // A repeated first letter steps on through the items that start with it.
+    const repeated = wanted.length > 1 && [...wanted].every((letter) => letter === wanted[0]);
+    const prefix = repeated ? wanted[0] : wanted;
+    const start = repeated || wanted.length === 1 ? current + 1 : Math.max(current, 0);
+    for (let offset = 0; offset < labels.length; offset += 1) {
+        const index = (start + offset) % labels.length;
+        if (labels[index].trim().toLocaleLowerCase().startsWith(prefix))
+            return index;
+    }
+    return null;
+}

package/dist/web/prefs.d.ts

@@ -0,0 +1,12 @@
+export interface StorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+export type Validator<Value> = (value: unknown) => value is Value;
+export declare function browser_storage(): StorageLike | undefined;
+export declare function read_pref<Value>(storage: StorageLike | undefined, key: string, initial: Value, validate?: Validator<Value>): Value;
+export declare function write_pref(storage: StorageLike | undefined, key: string, value: unknown): void;
+export declare function one_of<Value extends string>(...allowed: readonly Value[]): Validator<Value>;
+export declare function is_boolean(value: unknown): value is boolean;
+export declare function is_number_in(min: number, max: number): Validator<number>;

package/dist/web/prefs.js

@@ -0,0 +1,62 @@
+// Remembered view settings: a stored value that is corrupt, from an older version or of the wrong shape reads as the default.
+// This browser's localStorage, or nothing where there is none or it may not be touched.
+export function browser_storage() {
+    try {
+        return typeof localStorage === "undefined" ? undefined : localStorage;
+    }
+    catch {
+        return undefined;
+    }
+}
+// ── Reading and writing ──────────────────────────────────────────────────────
+// The stored value, or the initial one whenever the stored one cannot be used.
+export function read_pref(storage, key, initial, validate) {
+    if (!storage)
+        return initial;
+    let raw;
+    try {
+        raw = storage.getItem(key);
+    }
+    catch {
+        return initial;
+    }
+    if (raw === null)
+        return initial;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return initial;
+    }
+    if (validate)
+        return validate(parsed) ? parsed : initial;
+    // Without a validator the stored value must at least have the initial value's shape.
+    if (parsed === null || initial === null)
+        return parsed ?? initial;
+    if (Array.isArray(initial) !== Array.isArray(parsed))
+        return initial;
+    if (typeof parsed !== typeof initial)
+        return initial;
+    return parsed;
+}
+export function write_pref(storage, key, value) {
+    if (!storage)
+        return;
+    try {
+        storage.setItem(key, JSON.stringify(value));
+    }
+    catch {
+        // A full or disabled storage keeps the setting until the page closes.
+    }
+}
+// ── Validators ───────────────────────────────────────────────────────────────
+export function one_of(...allowed) {
+    return (value) => typeof value === "string" && allowed.includes(value);
+}
+export function is_boolean(value) {
+    return typeof value === "boolean";
+}
+export function is_number_in(min, max) {
+    return (value) => typeof value === "number" && Number.isFinite(value) && value >= min && value <= max;
+}

package/dist/web/{preact → react}/badges.d.ts

@@ -1,26 +1,26 @@
-import type { ComponentChildren } from "preact";
+import type { ReactNode } from "react";
 export type Tone = "good" | "warn" | "bad" | "info" | "none";
 export declare function Badge({ tone, title, children }: {
     tone?: Tone;
     title?: string;
-    children: ComponentChildren;
-}): import("preact").JSX.Element;
+    children: ReactNode;
+}): import("react").JSX.Element;
 export declare function StateBadge<State extends string>({ labels, state, title }: {
     labels: Record<State, [text: string, tone: Tone]>;
     state: State;
     title?: string;
-}): import("preact").JSX.Element;
+}): import("react").JSX.Element;
 export declare function Chip({ title, on_click, class_name, children }: {
     title?: string;
     on_click?: () => void;
     class_name?: string;
-    children: ComponentChildren;
-}): import("preact").JSX.Element;
+    children: ReactNode;
+}): import("react").JSX.Element;
 export declare function Chips({ inline, children }: {
     inline?: boolean;
-    children: ComponentChildren;
-}): import("preact").JSX.Element;
+    children: ReactNode;
+}): import("react").JSX.Element;
 export declare function Verdict({ ok, label }: {
     ok: boolean | null | undefined;
     label: string;
-}): import("preact").JSX.Element;
+}): import("react").JSX.Element;

package/dist/web/{preact → react}/badges.js

@@ -1,7 +1,7 @@
-import { jsx as _jsx, jsxs as _jsxs } from "preact/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // ── Badges ───────────────────────────────────────────────────────────────────
 export function Badge({ tone = "none", title, children }) {
-    return _jsx("span", { class: `badge tone-${tone}`, title: title, children: children });
+    return _jsx("span", { className: `badge tone-${tone}`, title: title, children: children });
 }
 // A badge for one of a fixed set of states, each named by its text and tone.
 export function StateBadge({ labels, state, title }) {
@@ -13,16 +13,16 @@ export function StateBadge({ labels, state, title }) {
 export function Chip({ title, on_click, class_name, children }) {
     const chip_class = class_name ? `chip ${class_name}` : "chip";
     return on_click
-        ? _jsx("button", { type: "button", class: chip_class, title: title, onClick: on_click, children: children })
-        : _jsx("span", { class: chip_class, title: title, children: children });
+        ? _jsx("button", { type: "button", className: chip_class, title: title, onClick: on_click, children: children })
+        : _jsx("span", { className: chip_class, title: title, children: children });
 }
 // A row of chips or badges, with less space between them when they sit inside a line of text.
 export function Chips({ inline = false, children }) {
-    return _jsx("span", { class: inline ? "chips inline-chips" : "chips", children: children });
+    return _jsx("span", { className: inline ? "chips inline-chips" : "chips", children: children });
 }
 // ── Verdicts ─────────────────────────────────────────────────────────────────
 // A pass, fail or not-yet verdict, such as "checks: pass".
 export function Verdict({ ok, label }) {
     const known = ok !== null && ok !== undefined;
-    return _jsxs("span", { class: `verdict tone-${known ? (ok ? "good" : "bad") : "none"}`, children: [label, ": ", known ? (ok ? "pass" : "fail") : "no verdict"] });
+    return _jsxs("span", { className: `verdict tone-${known ? (ok ? "good" : "bad") : "none"}`, children: [label, ": ", known ? (ok ? "pass" : "fail") : "no verdict"] });
 }