@vizejs/ui 0.387.0 → 0.388.0

package/dist/history-BDgNOjcV.mjs

@@ -0,0 +1,304 @@
+import { getCurrentScope, onScopeDispose, shallowReadonly, shallowRef } from "vue";
+//#region src/families/interaction/history/history-stack.ts
+const optionDiagnostic$1 = "VIZE_UI_HISTORY_OPTION";
+function resolveHistoryOptions(options) {
+	const limit = options.limit ?? 1e3;
+	if (!Number.isInteger(limit) || limit < 1) throw new TypeError(`${optionDiagnostic$1}: limit must be an integer >= 1`);
+	const coalesceWindow = options.coalesceWindow ?? 1e3;
+	if (typeof coalesceWindow !== "number" || !Number.isFinite(coalesceWindow) || coalesceWindow < 0) throw new TypeError(`${optionDiagnostic$1}: coalesceWindow must be a finite number >= 0`);
+	const now = options.now ?? Date.now;
+	if (typeof now !== "function") throw new TypeError(`${optionDiagnostic$1}: now must be a function`);
+	return Object.freeze({
+		limit,
+		coalesceWindow,
+		now
+	});
+}
+function readOptionalString(value, name) {
+	if (value === void 0) return null;
+	if (typeof value !== "string") throw new TypeError(`${optionDiagnostic$1}: ${name} must be a string`);
+	return value;
+}
+function toRecord(entry, at) {
+	if (typeof entry.undo !== "function" || typeof entry.redo !== "function") throw new TypeError(`${optionDiagnostic$1}: entries need undo and redo functions`);
+	return {
+		undo: entry.undo,
+		redo: entry.redo,
+		label: readOptionalString(entry.label, "label"),
+		coalesceKey: readOptionalString(entry.coalesceKey, "coalesceKey"),
+		at
+	};
+}
+function toSnapshotEntry(options) {
+	if (typeof options.apply !== "function") throw new TypeError(`${optionDiagnostic$1}: apply must be a function`);
+	const isEqual = options.isEqual ?? Object.is;
+	if (typeof isEqual !== "function") throw new TypeError(`${optionDiagnostic$1}: isEqual must be a function`);
+	readOptionalString(options.label, "label");
+	readOptionalString(options.coalesceKey, "coalesceKey");
+	if (isEqual(options.before, options.after)) return null;
+	const { before, after, apply } = options;
+	return {
+		undo: () => apply(before),
+		redo: () => apply(after),
+		...options.label !== void 0 ? { label: options.label } : {},
+		...options.coalesceKey !== void 0 ? { coalesceKey: options.coalesceKey } : {}
+	};
+}
+/**
+* Merge `record` into `top` when both carry the same coalescing key and the
+* push arrived inside the coalescing window. The merged step keeps the first
+* undo, adopts the latest redo, and restarts the window.
+*/
+function tryCoalesce(top, record, coalesceWindow) {
+	if (top === void 0 || top.coalesceKey === null || top.coalesceKey !== record.coalesceKey || record.at - top.at > coalesceWindow) return false;
+	top.redo = record.redo;
+	top.label = record.label ?? top.label;
+	top.at = record.at;
+	return true;
+}
+/** Fold staged transaction records into one composite step. */
+function foldRecords(records, label, at) {
+	const steps = [...records];
+	return {
+		undo: () => {
+			for (let index = steps.length - 1; index >= 0; index -= 1) steps[index].undo();
+		},
+		redo: () => {
+			for (const step of steps) step.redo();
+		},
+		label,
+		coalesceKey: null,
+		at
+	};
+}
+//#endregion
+//#region src/families/interaction/history/history-editable.ts
+const optionDiagnostic = "VIZE_UI_HISTORY_EDITABLE";
+/**
+* Create an in-place editing session that records one history step per edit.
+*
+* `begin` captures the pre-edit value, `update` writes live values without
+* touching history, and `commit` pushes a single snapshot step covering the
+* whole session; `cancel` restores the captured value instead. This keeps
+* per-keystroke writes out of the timeline so field edits undo as one unit.
+*/
+function createEditableTransaction(options) {
+	if (typeof options.history?.pushSnapshot !== "function") throw new TypeError(`${optionDiagnostic}: history must be a HistoryController`);
+	if (typeof options.read !== "function" || typeof options.write !== "function") throw new TypeError(`${optionDiagnostic}: read and write must be functions`);
+	for (const name of ["label", "coalesceKey"]) if (options[name] !== void 0 && typeof options[name] !== "string") throw new TypeError(`${optionDiagnostic}: ${name} must be a string`);
+	const isEqual = options.isEqual ?? Object.is;
+	if (typeof isEqual !== "function") throw new TypeError(`${optionDiagnostic}: isEqual must be a function`);
+	const isEditing = shallowRef(false);
+	let before;
+	const begin = () => {
+		if (isEditing.value) return;
+		before = options.read();
+		isEditing.value = true;
+	};
+	return Object.freeze({
+		isEditing: shallowReadonly(isEditing),
+		begin,
+		update: (value) => {
+			begin();
+			options.write(value);
+		},
+		commit: () => {
+			if (!isEditing.value) return false;
+			isEditing.value = false;
+			const after = options.read();
+			const captured = before;
+			before = void 0;
+			if (isEqual(captured, after)) return false;
+			options.history.pushSnapshot({
+				before: captured,
+				after,
+				apply: options.write,
+				isEqual,
+				...options.label !== void 0 ? { label: options.label } : {},
+				...options.coalesceKey !== void 0 ? { coalesceKey: options.coalesceKey } : {}
+			});
+			return true;
+		},
+		cancel: () => {
+			if (!isEditing.value) return false;
+			isEditing.value = false;
+			const captured = before;
+			before = void 0;
+			options.write(captured);
+			return true;
+		}
+	});
+}
+//#endregion
+//#region src/families/interaction/history/history.ts
+const disposedDiagnostic = "VIZE_UI_HISTORY_DISPOSED";
+const setupDiagnostic = "VIZE_UI_HISTORY_SETUP";
+const transactionDiagnostic = "VIZE_UI_HISTORY_TRANSACTION";
+/**
+* Create an undo/redo timeline with coalescing, transactions, and snapshots.
+*
+* Entries describe changes that are already applied; the controller only
+* replays them. It owns no DOM or timers, so it is safe to create during
+* server rendering. Pushes that happen while the controller is restoring
+* state are discarded so reactive mirrors cannot corrupt the timeline. Call
+* {@link HistoryController.dispose} when using this factory outside a Vue
+* effect scope.
+*/
+function createHistory(options = {}) {
+	const resolved = resolveHistoryOptions(options);
+	const undoStack = [];
+	const redoStack = [];
+	const staged = [];
+	const transactions = [];
+	const canUndo = shallowRef(false);
+	const canRedo = shallowRef(false);
+	const undoDepth = shallowRef(0);
+	const redoDepth = shallowRef(0);
+	const undoLabel = shallowRef(null);
+	const redoLabel = shallowRef(null);
+	const isRestoring = shallowRef(false);
+	let disposed = false;
+	const assertActive = () => {
+		if (disposed) throw new Error(`${disposedDiagnostic}: the history has been disposed`);
+	};
+	const assertNoTransaction = (operation) => {
+		if (transactions.length > 0) throw new Error(`${transactionDiagnostic}: cannot ${operation} while a transaction is open`);
+	};
+	const sync = () => {
+		canUndo.value = undoStack.length > 0;
+		canRedo.value = redoStack.length > 0;
+		undoDepth.value = undoStack.length;
+		redoDepth.value = redoStack.length;
+		undoLabel.value = undoStack.at(-1)?.label ?? null;
+		redoLabel.value = redoStack.at(-1)?.label ?? null;
+	};
+	const commitRecord = (record) => {
+		redoStack.length = 0;
+		if (!tryCoalesce(undoStack.at(-1), record, resolved.coalesceWindow)) {
+			undoStack.push(record);
+			if (undoStack.length > resolved.limit) undoStack.shift();
+		}
+		sync();
+	};
+	const push = (entry) => {
+		assertActive();
+		const record = toRecord(entry, resolved.now());
+		if (isRestoring.value) return;
+		if (transactions.length > 0) {
+			staged.push(record);
+			return;
+		}
+		commitRecord(record);
+	};
+	const replay = (from, to, action) => {
+		assertActive();
+		assertNoTransaction(action);
+		const record = from.pop();
+		if (record === void 0) return false;
+		isRestoring.value = true;
+		try {
+			record[action]();
+		} finally {
+			isRestoring.value = false;
+			sync();
+		}
+		to.push(record);
+		sync();
+		return true;
+	};
+	const beginTransaction = (label) => {
+		assertActive();
+		if (label !== void 0 && typeof label !== "string") throw new TypeError(`${transactionDiagnostic}: label must be a string`);
+		const frame = {
+			label: label ?? null,
+			startIndex: staged.length
+		};
+		transactions.push(frame);
+		let settled = false;
+		const assertOpen = () => {
+			assertActive();
+			if (settled || transactions.at(-1) !== frame) throw new Error(`${transactionDiagnostic}: transactions settle once, innermost first`);
+			settled = true;
+			transactions.pop();
+		};
+		return Object.freeze({
+			commit: () => {
+				assertOpen();
+				if (transactions.length > 0) return;
+				const records = staged.splice(0);
+				if (records.length === 0) return;
+				if (records.length === 1 && frame.label === null) {
+					commitRecord(records[0]);
+					return;
+				}
+				commitRecord(foldRecords(records, frame.label, resolved.now()));
+			},
+			rollback: () => {
+				assertOpen();
+				const records = staged.splice(frame.startIndex);
+				isRestoring.value = true;
+				try {
+					for (let index = records.length - 1; index >= 0; index -= 1) records[index].undo();
+				} finally {
+					isRestoring.value = false;
+				}
+			}
+		});
+	};
+	return Object.freeze({
+		canUndo: shallowReadonly(canUndo),
+		canRedo: shallowReadonly(canRedo),
+		undoDepth: shallowReadonly(undoDepth),
+		redoDepth: shallowReadonly(redoDepth),
+		undoLabel: shallowReadonly(undoLabel),
+		redoLabel: shallowReadonly(redoLabel),
+		isRestoring: shallowReadonly(isRestoring),
+		push,
+		pushSnapshot: (snapshot) => {
+			assertActive();
+			const entry = toSnapshotEntry(snapshot);
+			if (entry !== null) push(entry);
+		},
+		undo: () => replay(undoStack, redoStack, "undo"),
+		redo: () => replay(redoStack, undoStack, "redo"),
+		beginTransaction,
+		transaction: (label, work) => {
+			if (typeof work !== "function") throw new TypeError(`${transactionDiagnostic}: work must be a function`);
+			const frame = beginTransaction(label);
+			let result;
+			try {
+				result = work();
+			} catch (error) {
+				frame.rollback();
+				throw error;
+			}
+			frame.commit();
+			return result;
+		},
+		clear: () => {
+			assertActive();
+			assertNoTransaction("clear");
+			undoStack.length = 0;
+			redoStack.length = 0;
+			sync();
+		},
+		dispose: () => {
+			if (disposed) return;
+			disposed = true;
+			undoStack.length = 0;
+			redoStack.length = 0;
+			staged.length = 0;
+			transactions.length = 0;
+			sync();
+		}
+	});
+}
+/** Create a history controller disposed with the current Vue effect scope. */
+function useHistory(options = {}) {
+	if (!getCurrentScope()) throw new Error(`${setupDiagnostic}: use inside component setup or an active effect scope`);
+	const history = createHistory(options);
+	onScopeDispose(history.dispose);
+	return history;
+}
+//#endregion
+export { useHistory as n, createEditableTransaction as r, createHistory as t };

package/dist/history-BkcOSOWb.d.mts

@@ -0,0 +1,157 @@
+import { ShallowRef } from "vue";
+
+//#region src/families/interaction/history/history-types.d.ts
+/** One undoable unit of work whose effects are already applied. */
+interface HistoryEntry {
+  /** Reverse the applied change. */
+  readonly undo: () => void;
+  /** Re-apply the change after it was undone. */
+  readonly redo: () => void;
+  /** Human-readable label for Undo/Redo menu items. */
+  readonly label?: string;
+  /**
+   * Adjacent pushes carrying the same key merge into one step while they
+   * arrive within the coalescing window and nothing was undone in between.
+   */
+  readonly coalesceKey?: string;
+}
+/** Value-based entry description used by `HistoryController.pushSnapshot`. */
+interface HistorySnapshotOptions<Value> {
+  /** State before the change. */
+  readonly before: Value;
+  /** State after the change. */
+  readonly after: Value;
+  /** Writer invoked with `before` on undo and `after` on redo. */
+  readonly apply: (value: Value) => void;
+  /** Human-readable label for Undo/Redo menu items. */
+  readonly label?: string;
+  /** Coalescing key; see {@link HistoryEntry.coalesceKey}. */
+  readonly coalesceKey?: string;
+  /**
+   * Equality used to drop no-op snapshots.
+   *
+   * @default Object.is
+   */
+  readonly isEqual?: (left: Value, right: Value) => boolean;
+}
+/** Open transaction handle returned by `HistoryController.beginTransaction`. */
+interface HistoryTransaction {
+  /** Fold everything staged since `beginTransaction` into one step. */
+  readonly commit: () => void;
+  /** Undo and discard everything staged since `beginTransaction`. */
+  readonly rollback: () => void;
+}
+/** Options for `createHistory` and `useHistory`. */
+interface HistoryOptions {
+  /**
+   * Maximum retained undo steps; the oldest step is dropped beyond it.
+   *
+   * @default 1000
+   */
+  readonly limit?: number;
+  /**
+   * Milliseconds within which same-key pushes coalesce into one step.
+   *
+   * @default 1000
+   */
+  readonly coalesceWindow?: number;
+  /**
+   * Monotonic clock used for coalescing decisions, injectable for tests.
+   *
+   * @default Date.now
+   */
+  readonly now?: () => number;
+}
+/** Undo/redo timeline with coalescing, transactions, and snapshots. */
+interface HistoryController {
+  /** Whether at least one step can be undone. */
+  readonly canUndo: Readonly<ShallowRef<boolean>>;
+  /** Whether at least one step can be redone. */
+  readonly canRedo: Readonly<ShallowRef<boolean>>;
+  /** Number of undoable steps. */
+  readonly undoDepth: Readonly<ShallowRef<number>>;
+  /** Number of redoable steps. */
+  readonly redoDepth: Readonly<ShallowRef<number>>;
+  /** Label of the next undo step, or `null`. */
+  readonly undoLabel: Readonly<ShallowRef<string | null>>;
+  /** Label of the next redo step, or `null`. */
+  readonly redoLabel: Readonly<ShallowRef<string | null>>;
+  /** True while an undo or redo is re-applying state. */
+  readonly isRestoring: Readonly<ShallowRef<boolean>>;
+  /** Record one already-applied entry, coalescing when eligible. */
+  readonly push: (entry: HistoryEntry) => void;
+  /** Record one already-applied value change, dropping no-op snapshots. */
+  readonly pushSnapshot: <Value>(options: HistorySnapshotOptions<Value>) => void;
+  /** Undo one step and report whether one existed. */
+  readonly undo: () => boolean;
+  /** Redo one step and report whether one existed. */
+  readonly redo: () => boolean;
+  /** Open a transaction that folds staged pushes into one step. */
+  readonly beginTransaction: (label?: string) => HistoryTransaction;
+  /** Run `work` inside a transaction, rolling back when it throws. */
+  readonly transaction: <Result>(label: string | undefined, work: () => Result) => Result;
+  /** Drop both timelines without touching application state. */
+  readonly clear: () => void;
+  /** Clear the timeline and make imperative calls terminal. */
+  readonly dispose: () => void;
+}
+/** Options for `createEditableTransaction`. */
+interface EditableTransactionOptions<Value> {
+  /** History timeline that receives one step per committed edit. */
+  readonly history: HistoryController;
+  /** Read the current value from the editor. */
+  readonly read: () => Value;
+  /** Write a value back into the editor. */
+  readonly write: (value: Value) => void;
+  /** Label recorded on committed steps. */
+  readonly label?: string;
+  /** Coalescing key recorded on committed steps. */
+  readonly coalesceKey?: string;
+  /**
+   * Equality used to drop unchanged commits.
+   *
+   * @default Object.is
+   */
+  readonly isEqual?: (left: Value, right: Value) => boolean;
+}
+/** In-place editing session that commits one history step per edit. */
+interface EditableTransaction<Value> {
+  /** True between `begin` and the next `commit` or `cancel`. */
+  readonly isEditing: Readonly<ShallowRef<boolean>>;
+  /** Capture the pre-edit value. Idempotent while editing. */
+  readonly begin: () => void;
+  /** Write a live value, beginning the session when necessary. */
+  readonly update: (value: Value) => void;
+  /** Push one step for the whole session; report whether one was pushed. */
+  readonly commit: () => boolean;
+  /** Restore the pre-edit value; report whether a session was open. */
+  readonly cancel: () => boolean;
+}
+//#endregion
+//#region src/families/interaction/history/history-editable.d.ts
+/**
+ * Create an in-place editing session that records one history step per edit.
+ *
+ * `begin` captures the pre-edit value, `update` writes live values without
+ * touching history, and `commit` pushes a single snapshot step covering the
+ * whole session; `cancel` restores the captured value instead. This keeps
+ * per-keystroke writes out of the timeline so field edits undo as one unit.
+ */
+declare function createEditableTransaction<Value>(options: EditableTransactionOptions<Value>): EditableTransaction<Value>;
+//#endregion
+//#region src/families/interaction/history/history.d.ts
+/**
+ * Create an undo/redo timeline with coalescing, transactions, and snapshots.
+ *
+ * Entries describe changes that are already applied; the controller only
+ * replays them. It owns no DOM or timers, so it is safe to create during
+ * server rendering. Pushes that happen while the controller is restoring
+ * state are discarded so reactive mirrors cannot corrupt the timeline. Call
+ * {@link HistoryController.dispose} when using this factory outside a Vue
+ * effect scope.
+ */
+declare function createHistory(options?: HistoryOptions): HistoryController;
+/** Create a history controller disposed with the current Vue effect scope. */
+declare function useHistory(options?: HistoryOptions): HistoryController;
+//#endregion
+export { EditableTransactionOptions as a, HistoryOptions as c, EditableTransaction as i, HistorySnapshotOptions as l, useHistory as n, HistoryController as o, createEditableTransaction as r, HistoryEntry as s, createHistory as t, HistoryTransaction as u };

package/dist/history.d.mts

@@ -0,0 +1,2 @@
+import { a as EditableTransactionOptions, c as HistoryOptions, i as EditableTransaction, l as HistorySnapshotOptions, n as useHistory, o as HistoryController, r as createEditableTransaction, s as HistoryEntry, t as createHistory, u as HistoryTransaction } from "./history-BkcOSOWb.mjs";
+export { type EditableTransaction, type EditableTransactionOptions, type HistoryController, type HistoryEntry, type HistoryOptions, type HistorySnapshotOptions, type HistoryTransaction, createEditableTransaction, createHistory, useHistory };

package/dist/history.mjs

@@ -0,0 +1,2 @@
+import { n as useHistory, r as createEditableTransaction, t as createHistory } from "./history-BDgNOjcV.mjs";
+export { createEditableTransaction, createHistory, useHistory };

package/dist/{hover-BXwwbSaO.d.mts → hover-ZiPRiZkb.d.mts}

@@ -1,6 +1,6 @@
 import { MaybeRefOrGetter, ShallowRef } from "vue";
 
-//#region src/hover-types.d.ts
+//#region src/families/interaction/hover/hover-types.d.ts
 /** Pointing-device families that have a meaningful hover state. */
 type HoverPointerType = "mouse" | "pen";
 /** Lifecycle notification emitted by a hover controller. */
@@ -71,7 +71,7 @@ interface HoverController {
   readonly dispose: () => void;
 }
 //#endregion
-//#region src/hover.d.ts
+//#region src/families/interaction/hover/hover.d.ts
 /** Create an SSR-safe mouse and pen hover normalizer for one host. */
 declare function createHover(options?: HoverOptions): HoverController;
 /** Create a hover normalizer disposed with the current Vue effect scope. */

package/dist/hover.d.mts

@@ -1,2 +1,2 @@
-import { a as HoverEventType, c as HoverProps, i as HoverEvent, n as useHover, o as HoverOptions, r as HoverController, s as HoverPointerType, t as createHover } from "./hover-BXwwbSaO.mjs";
+import { a as HoverEventType, c as HoverProps, i as HoverEvent, n as useHover, o as HoverOptions, r as HoverController, s as HoverPointerType, t as createHover } from "./hover-ZiPRiZkb.mjs";
 export { type HoverController, type HoverEvent, type HoverEventType, type HoverOptions, type HoverPointerType, type HoverProps, createHover, useHover };

package/dist/hover.mjs

@@ -1,5 +1,5 @@
 import { getCurrentScope, onScopeDispose, shallowReadonly, shallowRef, toValue } from "vue";
-//#region src/hover.ts
+//#region src/families/interaction/hover/hover.ts
 const invalidOptionDiagnostic = "VIZE_UI_HOVER_OPTION";
 const disposedDiagnostic = "VIZE_UI_HOVER_DISPOSED";
 const setupDiagnostic = "VIZE_UI_HOVER_SETUP";