@olenbetong/appframe-cli 4.3.1 → 4.4.0

package/src/editor/useCommand.ts

@@ -0,0 +1,191 @@
+import { useInput } from "ink";
+import { useCallback, useMemo, useRef } from "react";
+
+type KeyHandler = (input: string, key: Parameters<Parameters<typeof useInput>[0]>[1]) => void;
+
+type ShortcutDefinition = {
+	key: string | null;
+	ctrl: boolean;
+	meta: boolean;
+	shift: boolean;
+};
+
+type Shortcut = string | string[];
+
+const HOME_SEQUENCES = new Set(["\u001b[H", "\u001b[1~", "\u001bOH"]);
+const END_SEQUENCES = new Set(["\u001b[F", "\u001b[4~", "\u001bOF"]);
+const PAGE_UP_SEQUENCES = new Set(["\u001b[5~"]);
+const PAGE_DOWN_SEQUENCES = new Set(["\u001b[6~"]);
+
+const KEY_ALIASES: Record<string, string> = {
+	leftarrow: "left",
+	rightarrow: "right",
+	uparrow: "up",
+	downarrow: "down",
+	return: "enter",
+	enter: "enter",
+	esc: "escape",
+	spacebar: "space",
+	pagedown: "pagedown",
+	pageup: "pageup",
+};
+
+// Keys that are considered non-printable/navigation and for which we ignore extra modifiers
+// when matching (i.e., allow escape/home/end/pageup/pagedown/tab/enter/delete/backspace to
+// match even if the terminal sets stray meta/shift/ctrl flags).
+const RELAXED_KEYS = new Set([
+	"escape",
+	"left",
+	"right",
+	"up",
+	"down",
+	"home",
+	"end",
+	"pageup",
+	"pagedown",
+	"tab",
+	"enter",
+	"delete",
+	"backspace",
+]);
+
+function parseShortcut(shortcut: string): ShortcutDefinition {
+	let tokens = shortcut
+		.trim()
+		.toLowerCase()
+		.split("+")
+		.map((token) => token.trim())
+		.filter(Boolean);
+
+	let definition: ShortcutDefinition = {
+		key: null,
+		ctrl: false,
+		meta: false,
+		shift: false,
+	};
+
+	for (let token of tokens) {
+		if (token === "ctrl" || token === "control") {
+			definition.ctrl = true;
+			continue;
+		}
+		if (token === "meta" || token === "cmd" || token === "command") {
+			definition.meta = true;
+			continue;
+		}
+		if (token === "shift") {
+			definition.shift = true;
+			continue;
+		}
+
+		let alias = KEY_ALIASES[token];
+		definition.key = alias ?? token;
+	}
+
+	return definition;
+}
+
+function getInputKey(input: string, key: Parameters<KeyHandler>[1]): string | null {
+	if (key.escape) {
+		return "escape";
+	}
+	if (key.leftArrow) {
+		return "left";
+	}
+	if (key.rightArrow) {
+		return "right";
+	}
+	if (key.upArrow) {
+		return "up";
+	}
+	if (key.downArrow) {
+		return "down";
+	}
+	if (key.pageUp || PAGE_UP_SEQUENCES.has(input)) {
+		return "pageup";
+	}
+	if (key.pageDown || PAGE_DOWN_SEQUENCES.has(input)) {
+		return "pagedown";
+	}
+	if (key.return) {
+		return "enter";
+	}
+	if (key.delete) {
+		return "delete";
+	}
+	if (key.backspace) {
+		return "backspace";
+	}
+	if (key.tab) {
+		return "tab";
+	}
+	if (key.shift && !input) {
+		return null;
+	}
+	if (input === " ") {
+		return "space";
+	}
+	if (HOME_SEQUENCES.has(input) || ((key as { home?: boolean }).home ?? false)) {
+		return "home";
+	}
+	if (END_SEQUENCES.has(input) || ((key as { end?: boolean }).end ?? false)) {
+		return "end";
+	}
+	if (input) {
+		return input.toLowerCase();
+	}
+	return null;
+}
+
+function matchesShortcut(definition: ShortcutDefinition, input: string, key: Parameters<KeyHandler>[1]): boolean {
+	let actualKey = getInputKey(input, key);
+
+	// If the terminal reports a key we treat as non-printable/navigation,
+	// relax extra modifiers (only require those explicitly specified),
+	// but for printable keys we require an exact modifier match.
+	let relaxed = actualKey !== null && RELAXED_KEYS.has(actualKey);
+
+	// Require specified modifiers to be present
+	if (definition.ctrl && !key.ctrl) return false;
+	if (definition.meta && !key.meta) return false;
+	if (definition.shift && !key.shift) return false;
+
+	// For printable keys (non-relaxed), disallow extra modifiers
+	if (!relaxed) {
+		if (!definition.ctrl && key.ctrl) return false;
+		if (!definition.meta && key.meta) return false;
+		if (!definition.shift && key.shift) return false;
+	}
+
+	if (definition.key === null) {
+		// Modifiers-only shortcut: match only if we identified some key press
+		// (prevents bare modifier from triggering)
+		return actualKey !== null;
+	}
+	return actualKey === definition.key;
+}
+
+function normalizeShortcuts(shortcuts: Shortcut): ShortcutDefinition[] {
+	let entries = Array.isArray(shortcuts) ? shortcuts : [shortcuts];
+	return entries.map(parseShortcut);
+}
+
+export function useCommand(shortcut: Shortcut, handler: () => void | Promise<void>, enabled = true) {
+	let definitions = useMemo(() => normalizeShortcuts(shortcut), [shortcut]);
+	let callback = useRef(handler);
+	callback.current = handler;
+
+	let inputHandler: KeyHandler = useCallback(
+		(input, key) => {
+			for (let definition of definitions) {
+				if (matchesShortcut(definition, input, key)) {
+					callback.current();
+					return;
+				}
+			}
+		},
+		[definitions],
+	);
+
+	useInput(inputHandler, { isActive: enabled });
+}

package/src/editor/useScrollableText.ts

@@ -0,0 +1,48 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+
+import { useCommand } from "./useCommand.js";
+
+export type UseScrollableTextOptions = {
+	textLength: number;
+	viewportHeight: number;
+	signature: string;
+};
+
+export type UseScrollableTextResult = {
+	scrollOffset: number;
+	canScroll: boolean;
+	maxScrollOffset: number;
+	pageStep: number;
+};
+
+export function useScrollableText({
+	textLength,
+	viewportHeight,
+	signature,
+}: UseScrollableTextOptions): UseScrollableTextResult {
+	let [scrollOffset, setScrollOffset] = useState(0);
+
+	let lastSignatureRef = useRef(signature);
+	useEffect(() => {
+		if (lastSignatureRef.current !== signature) {
+			lastSignatureRef.current = signature;
+			setScrollOffset(0);
+		}
+	}, [signature]);
+
+	let maxScrollOffset = useMemo(() => Math.max((textLength || 1) - viewportHeight, 0), [textLength, viewportHeight]);
+
+	useEffect(() => {
+		setScrollOffset((offset) => Math.min(offset, maxScrollOffset));
+	}, [maxScrollOffset]);
+
+	let canScroll = textLength > viewportHeight && viewportHeight > 0;
+	let pageStep = useMemo(() => Math.max(viewportHeight - 1, 1), [viewportHeight]);
+
+	useCommand("up", () => setScrollOffset((offset) => Math.max(offset - 1, 0)), canScroll);
+	useCommand("down", () => setScrollOffset((offset) => Math.min(offset + 1, maxScrollOffset)), canScroll);
+	useCommand("pageup", () => setScrollOffset((offset) => Math.max(offset - pageStep, 0)), canScroll);
+	useCommand("pagedown", () => setScrollOffset((offset) => Math.min(offset + pageStep, maxScrollOffset)), canScroll);
+
+	return { scrollOffset, canScroll, maxScrollOffset, pageStep };
+}

package/src/editor/useTransactionEdits.ts

@@ -0,0 +1,183 @@
+import {
+	type Transaction,
+	type TransactionStatusCode,
+	type TransactionsRecord,
+	transactionStatuses,
+} from "@olenbetong/appframe-updater";
+import { useCallback, useEffect, useMemo, useState } from "react";
+
+import type { Server } from "../lib/Server.js";
+import type { TransactionsEditorRefreshOptions } from "./useTransactions.js";
+
+type UseTransactionEditsOptions = {
+	normalizedTransactions: Transaction[];
+	transactionRecordMap: Map<string, TransactionsRecord>;
+	selectedPrimKeys: Set<string>;
+	server: Server;
+	onActionMessage?: (message: string | null, color: "gray" | "red" | "yellow" | "green") => void;
+	refresh: (options?: TransactionsEditorRefreshOptions) => Promise<void> | void;
+};
+
+type UseTransactionEditsResult = {
+	pendingStatuses: Record<string, TransactionStatusCode>;
+	modifiedPrimKeys: Set<string>;
+	cycleStatus: (focusedPrimKey: string | null, options?: { exclusive?: boolean }) => void;
+	save: (options?: { primKey?: string | null }) => Promise<void>;
+	saving: boolean;
+};
+
+const STATUS_CYCLE = Object.freeze(
+	(Object.values(transactionStatuses) as TransactionStatusCode[]).sort((a, b) => a - b),
+);
+
+export function useTransactionEdits({
+	normalizedTransactions,
+	transactionRecordMap,
+	selectedPrimKeys,
+	server,
+	onActionMessage,
+	refresh,
+}: UseTransactionEditsOptions): UseTransactionEditsResult {
+	let [pendingStatuses, setPendingStatuses] = useState<Record<string, TransactionStatusCode>>({});
+	let [saving, setSaving] = useState(false);
+
+	let normalizedTransactionMap = useMemo(
+		() => new Map(normalizedTransactions.map((transaction) => [transaction.PrimKey, transaction])),
+		[normalizedTransactions],
+	);
+
+	let availablePrimKeys = useMemo(
+		() => new Set(normalizedTransactions.map((transaction) => transaction.PrimKey)),
+		[normalizedTransactions],
+	);
+
+	useEffect(() => {
+		setPendingStatuses((current) => {
+			let changed = false;
+			let next: Record<string, TransactionStatusCode> = {};
+			for (let [key, value] of Object.entries(current)) {
+				if (availablePrimKeys.has(key)) {
+					next[key] = value;
+				} else {
+					changed = true;
+				}
+			}
+			return changed ? next : current;
+		});
+	}, [availablePrimKeys]);
+
+	let modifiedPrimKeys = useMemo(() => {
+		let modified = new Set<string>();
+		for (let transaction of normalizedTransactions) {
+			let override = pendingStatuses[transaction.PrimKey];
+			if (override !== undefined && override !== transaction.Status) {
+				modified.add(transaction.PrimKey);
+			}
+		}
+		return modified;
+	}, [normalizedTransactions, pendingStatuses]);
+
+	let cycleStatus = useCallback(
+		(focusedPrimKey: string | null, options?: { exclusive?: boolean }) => {
+			let targets: string[] = [];
+			if (options?.exclusive) {
+				if (focusedPrimKey) {
+					targets = [focusedPrimKey];
+				}
+			} else if (selectedPrimKeys.size > 0) {
+				targets = Array.from(selectedPrimKeys);
+			} else if (focusedPrimKey) {
+				targets = [focusedPrimKey];
+			}
+
+			if (targets.length === 0) {
+				return;
+			}
+
+			setPendingStatuses((current) => {
+				let next = { ...current };
+				let changed = false;
+				for (let primKey of targets) {
+					let transaction = normalizedTransactionMap.get(primKey);
+					if (!transaction) {
+						continue;
+					}
+					let originalStatus = transaction.Status;
+					let currentStatus = current[primKey] ?? originalStatus;
+					let cycleIndex = STATUS_CYCLE.indexOf(currentStatus);
+					let nextStatus = STATUS_CYCLE[(cycleIndex + 1) % STATUS_CYCLE.length];
+					if (nextStatus === originalStatus) {
+						if (primKey in next) {
+							delete next[primKey];
+							changed = true;
+						}
+					} else if (next[primKey] !== nextStatus) {
+						next[primKey] = nextStatus;
+						changed = true;
+					}
+				}
+				return changed ? next : current;
+			});
+		},
+		[normalizedTransactionMap, selectedPrimKeys],
+	);
+
+	let save = useCallback(
+		async (options?: { primKey?: string | null }) => {
+			if (saving) {
+				return;
+			}
+			let restrictedPrimKeys = options?.primKey ? new Set([options.primKey]) : null;
+
+			let updates = Object.entries(pendingStatuses)
+				.filter(([primKey]) => !restrictedPrimKeys || restrictedPrimKeys.has(primKey))
+				.map(([primKey, status]) => {
+					let record = transactionRecordMap.get(primKey);
+					if (!record) {
+						return null;
+					}
+					if (status === record.Status) {
+						return null;
+					}
+					return { record, status };
+				})
+				.filter(Boolean) as Array<{ record: TransactionsRecord; status: number }>;
+
+			if (updates.length === 0) {
+				onActionMessage?.("No changes to save.", "gray");
+				return;
+			}
+
+			setSaving(true);
+			onActionMessage?.(`Saving ${updates.length} update${updates.length === 1 ? "" : "s"}…`, "yellow");
+			try {
+				await Promise.all(
+					updates.map(({ record, status }) => {
+						let payload = record.PrimKey
+							? { PrimKey: record.PrimKey, Status: status }
+							: { ID: record.ID, Status: status };
+						return server.dsTransactions.update(payload);
+					}),
+				);
+				onActionMessage?.(`Saved ${updates.length} update${updates.length === 1 ? "" : "s"}.`, "green");
+				setPendingStatuses((current) => {
+					let next = { ...current };
+					for (let { record } of updates) {
+						delete next[record.PrimKey];
+					}
+					return next;
+				});
+				let anchor = updates[0]?.record.PrimKey ?? null;
+				await refresh({ preserveViewport: true, anchorPrimKey: anchor });
+			} catch (caught) {
+				let message = caught instanceof Error ? caught.message : String(caught);
+				onActionMessage?.(`Failed to save changes: ${message}`, "red");
+			} finally {
+				setSaving(false);
+			}
+		},
+		[pendingStatuses, refresh, saving, server, transactionRecordMap, onActionMessage],
+	);
+
+	return { pendingStatuses, modifiedPrimKeys, cycleStatus, save, saving };
+}

package/src/editor/useTransactionText.ts

@@ -0,0 +1,153 @@
+import type { TransactionsRecord } from "@olenbetong/appframe-updater";
+import { useMemo } from "react";
+
+function formatPreviewValue(value: unknown) {
+	if (typeof value === "string") {
+		let lines = value.split(/\r?\n/);
+		return lines.length > 0 ? lines : [""];
+	}
+
+	if (value && typeof value === "object") {
+		try {
+			let serialized = JSON.stringify(value, null, 2);
+			if (serialized) {
+				return serialized.split("\n");
+			}
+		} catch {}
+	}
+
+	if (value === null) {
+		return ["null"];
+	}
+
+	return [String(value)];
+}
+
+function wrapLineForWidth(line: string, maxWidth: number) {
+	if (maxWidth <= 0) {
+		return [line];
+	}
+
+	let normalized = line.replaceAll("\t", "    ");
+	if (normalized.length <= maxWidth) {
+		return [normalized];
+	}
+
+	let segments: string[] = [];
+	let remaining = normalized;
+	while (remaining.length > maxWidth) {
+		let breakIndex = remaining.lastIndexOf(" ", maxWidth);
+		if (breakIndex <= 0) {
+			breakIndex = maxWidth;
+		}
+
+		let segment = remaining.slice(0, breakIndex).trimEnd();
+		segments.push(segment);
+		remaining = remaining.slice(breakIndex).replace(/^\s+/, "");
+	}
+
+	segments.push(remaining);
+	return segments;
+}
+
+function wrapLinesForWidth(lines: string[], maxWidth: number) {
+	if (lines.length === 0) {
+		return [""];
+	}
+
+	return lines.flatMap((line) => {
+		let wrapped = wrapLineForWidth(line, maxWidth);
+		return wrapped.length > 0 ? wrapped : [""];
+	});
+}
+
+function truncateKey(key: string, width: number) {
+	if (width <= 0) {
+		return "";
+	}
+
+	if (key.length <= width) {
+		return key.padEnd(width);
+	}
+
+	if (width === 1) {
+		return "…";
+	}
+
+	return `${key.slice(0, width - 1)}…`;
+}
+
+export type UseTransactionTextOptions = {
+	transaction: TransactionsRecord | undefined;
+	statusPreviewValue: string;
+	frameWidth: number;
+};
+
+export type UseTransactionTextResult = {
+	text: string[];
+	dialogWidth: number;
+};
+
+export function useTransactionText({
+	transaction,
+	statusPreviewValue,
+	frameWidth,
+}: UseTransactionTextOptions): UseTransactionTextResult {
+	return useMemo(() => {
+		let entries = transaction
+			? Object.entries(transaction)
+					.filter(([key]) => key !== "PrimKey")
+					.map(([key, value]) => ({
+						key,
+						lines: formatPreviewValue(key === "Status" ? statusPreviewValue : value),
+					}))
+			: [];
+
+		let maxKeyLength = entries.reduce((max, entry) => Math.max(max, entry.key.length), 0);
+		let rawKeyColumnWidth = Math.max(maxKeyLength, 1);
+		let availableDialogWidth = Math.max(frameWidth - 4, 1);
+		let dialogWidth = Math.min(Math.max(rawKeyColumnWidth + 80, 10), availableDialogWidth);
+		if (!Number.isFinite(dialogWidth) || dialogWidth <= 0) {
+			dialogWidth = 10;
+		}
+
+		let contentWidth = Math.max(dialogWidth - 4, 1);
+
+		let keyColumnWidth = entries.length > 0 ? Math.min(rawKeyColumnWidth, Math.max(contentWidth - 1, 0)) : 0;
+		if (keyColumnWidth < 0) {
+			keyColumnWidth = 0;
+		}
+
+		let separatorWidth = keyColumnWidth > 0 ? 1 : 0;
+		let valueColumnWidth = Math.max(contentWidth - keyColumnWidth - separatorWidth, 1);
+
+		let text: string[] = [];
+		if (entries.length === 0) {
+			return { text, dialogWidth };
+		}
+
+		let spacer = "";
+		let blankKey = keyColumnWidth > 0 ? " ".repeat(keyColumnWidth) : "";
+		let separator = separatorWidth > 0 ? " " : "";
+
+		entries.forEach((entry, entryIndex) => {
+			let valueLines = wrapLinesForWidth(entry.lines, valueColumnWidth);
+			if (valueLines.length === 0) {
+				valueLines = [""];
+			}
+
+			let formattedKey = truncateKey(entry.key, keyColumnWidth);
+			valueLines.forEach((line, lineIndex) => {
+				let keySegment = lineIndex === 0 ? formattedKey : blankKey;
+				let combined = keyColumnWidth > 0 ? `${keySegment}${separator}${line}` : line;
+				text.push(combined);
+			});
+
+			if (entryIndex < entries.length - 1) {
+				text.push(spacer);
+			}
+		});
+
+		return { text, dialogWidth };
+	}, [transaction, statusPreviewValue, frameWidth]);
+}

package/src/editor/useTransactions.ts

@@ -0,0 +1,75 @@
+import {
+	getTransactions,
+	type Transaction,
+	type TransactionFilter,
+	type TransactionsRecord,
+} from "@olenbetong/appframe-updater";
+import { useCallback, useEffect, useMemo, useState } from "react";
+
+import type { Server } from "../lib/Server.js";
+
+export type TransactionsEditorRefreshOptions = {
+	preserveViewport?: boolean;
+	anchorPrimKey?: string | null;
+};
+
+type UseTransactionsOptions = {
+	server: Server;
+	namespace: string | number;
+	filter?: TransactionFilter;
+};
+
+export function useTransactions({ filter, server, namespace }: UseTransactionsOptions) {
+	let [transactions, setTransactions] = useState<TransactionsRecord[]>([]);
+	let [loading, setLoading] = useState(false);
+	let [error, setError] = useState<Error | undefined>();
+
+	let refresh = useCallback(
+		async (_options: TransactionsEditorRefreshOptions = {}) => {
+			setLoading(true);
+			setError(undefined);
+			try {
+				let data = (await getTransactions(server.client, filter ?? "edit", namespace)) as TransactionsRecord[];
+				setTransactions(data);
+			} catch (caught) {
+				setError(caught as Error);
+			} finally {
+				setLoading(false);
+			}
+		},
+		[namespace, server, filter],
+	);
+
+	useEffect(() => {
+		setError(undefined);
+		refresh();
+	}, [refresh]);
+
+	let normalizedTransactions = useMemo<Transaction[]>(
+		() =>
+			transactions.map((transaction) => ({
+				ID: transaction.ID,
+				Namespace: transaction.Namespace,
+				Name: transaction.Name,
+				CreatedBy: transaction.CreatedBy ?? transaction.CreatedByName ?? transaction.LocalCreatedBy,
+				Status: transaction.Status,
+				LastError: transaction.LastError ?? undefined,
+				PrimKey: transaction.PrimKey,
+			})),
+		[transactions],
+	);
+
+	let transactionMap = useMemo(
+		() => new Map(transactions.map((transaction) => [transaction.PrimKey, transaction])),
+		[transactions],
+	);
+
+	return {
+		transactions,
+		loading,
+		error,
+		refresh,
+		normalizedTransactions,
+		transactionMap,
+	};
+}

package/src/editor/useTransactionsSelection.ts

@@ -0,0 +1,54 @@
+import type { TransactionsRecord } from "@olenbetong/appframe-updater";
+import { useCallback, useEffect, useState } from "react";
+
+type TransactionsLike = Pick<TransactionsRecord, "PrimKey">;
+
+type UseTransactionsSelectionResult = {
+	selectedPrimKeys: Set<string>;
+	toggleSelection: (primKey: string | null | undefined) => void;
+	resetSelection: () => void;
+};
+
+export function useTransactionsSelection(transactions: TransactionsLike[]): UseTransactionsSelectionResult {
+	let [selectedPrimKeys, setSelectedPrimKeys] = useState<Set<string>>(new Set());
+
+	useEffect(() => {
+		let availablePrimKeys = new Set(transactions.map((transaction) => transaction.PrimKey));
+		setSelectedPrimKeys((current) => {
+			if (current.size === 0) {
+				return current;
+			}
+			let next = new Set<string>();
+			let changed = false;
+			for (let key of current) {
+				if (availablePrimKeys.has(key)) {
+					next.add(key);
+				} else {
+					changed = true;
+				}
+			}
+			return changed ? next : current;
+		});
+	}, [transactions]);
+
+	let toggleSelection = useCallback((primKey: string | null | undefined) => {
+		if (!primKey) {
+			return;
+		}
+		setSelectedPrimKeys((current) => {
+			let next = new Set(current);
+			if (next.has(primKey)) {
+				next.delete(primKey);
+			} else {
+				next.add(primKey);
+			}
+			return next;
+		});
+	}, []);
+
+	let resetSelection = useCallback(() => {
+		setSelectedPrimKeys(new Set());
+	}, []);
+
+	return { selectedPrimKeys, toggleSelection, resetSelection };
+}