@10x-media/undo-redo 0.1.0-beta.0

package/dist/client/useUndoRedo.js

@@ -0,0 +1,259 @@
+"use client";
+import { createPathMatcher } from "../history/pathPatterns.js";
+import { buildRestoreState, canRedo, canUndo, createHistory, isAtSavedState, markSaved, pushSnapshot } from "../history/historyCore.js";
+import { DEFAULT_SHORTCUTS } from "../plugin/options.js";
+import { buildFieldSchemaMap, collectIgnorePatterns } from "../schema/fieldSchema.js";
+import { createVolatileMatcher } from "../history/volatileValues.js";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useAllFormFields, useConfig, useDocumentInfo, useForm, useFormInitializing, useFormModified } from "@payloadcms/ui";
+import { useHotkeys } from "react-hotkeys-hook";
+//#region src/client/useUndoRedo.ts
+/** Shared so a document without a resolvable schema keeps a stable identity. */
+const EMPTY_SCHEMA = /* @__PURE__ */ new Map();
+/**
+* Undo/redo for the surrounding Payload form: a client-side history of
+* form-state snapshots, independent of Payload's document versions, with
+* nothing read from or written to the server until the user saves.
+*
+* Backs `<UndoRedoControls />` and is exported so a host can build its own
+* controls instead (pair it with `autoMount: false`). Must be called from
+* inside a document edit form; outside one it finds no fields and stays
+* disabled.
+*
+* One history per call. Two instances on the same form keep two independent
+* stacks and each captures the other's restores as fresh edits, so mount either
+* ours or yours, not both.
+*/
+const useUndoRedo = ({ captureDebounce = 400, debug = false, ignoreFieldTypes, ignorePaths, maxHistory = 50, shortcuts } = {}) => {
+	const [fields, dispatchFields] = useAllFormFields();
+	const { formRef, setModified } = useForm();
+	const initializing = useFormInitializing();
+	const modified = useFormModified();
+	const { getEntityConfig, config } = useConfig();
+	const { collectionSlug, globalSlug } = useDocumentInfo();
+	/**
+	* Ignore patterns from the config, plus the ones derived from the document's
+	* own schema: fields the host opted out through `admin.custom`, and every
+	* field of an excluded type. The schema is the only place a mounted
+	* component can learn field types, since form state omits them unless
+	* `buildFormState` was called with `includeSchema`, which the edit view never
+	* does.
+	*/
+	const entity = useMemo(() => collectionSlug ? getEntityConfig({ collectionSlug }) : globalSlug ? getEntityConfig({ globalSlug }) : null, [
+		collectionSlug,
+		getEntityConfig,
+		globalSlug
+	]);
+	/**
+	* Autosave persists every edit continuously, so "differs from what is
+	* persisted" is not a state the editor can meaningfully be in: the baseline
+	* would move on every autosave, and an undo would immediately trigger one and
+	* move it again. Tracking it there produces a saved marker that chases the
+	* user around instead of telling them anything, so the whole baseline
+	* mechanism is skipped and restores simply report the form as modified.
+	*/
+	const tracksSavedState = useMemo(() => {
+		const drafts = entity?.versions?.drafts;
+		return !(typeof drafts === "object" && drafts !== null ? drafts.autosave : false);
+	}, [entity]);
+	const schema = useMemo(() => entity ? buildFieldSchemaMap(entity.fields, { blocksMap: config.blocksMap }) : EMPTY_SCHEMA, [config.blocksMap, entity]);
+	const isIgnored = useMemo(() => createPathMatcher([...ignorePaths ?? [], ...collectIgnorePatterns(schema, ignoreFieldTypes)]), [
+		ignoreFieldTypes,
+		ignorePaths,
+		schema
+	]);
+	const isVolatile = useMemo(() => createVolatileMatcher(schema), [schema]);
+	const historyRef = useRef(null);
+	if (historyRef.current === null) historyRef.current = createHistory({
+		isIgnored,
+		isVolatile,
+		maxHistory
+	});
+	const history = historyRef.current;
+	history.options = {
+		isIgnored,
+		isVolatile,
+		maxHistory
+	};
+	const fieldsRef = useRef(null);
+	const [flags, setFlags] = useState({
+		redo: false,
+		undo: false
+	});
+	/**
+	* Forces consumers to re-read the mutable history object, which is a ref and
+	* therefore invisible to React. Only bumped under `debug`, so the default
+	* build keeps re-rendering purely on the undo/redo flags.
+	*/
+	const [revision, setRevision] = useState(0);
+	fieldsRef.current = fields;
+	const bumpRevision = useCallback(() => {
+		if (debug) setRevision((n) => n + 1);
+	}, [debug]);
+	const refreshFlags = useCallback(() => {
+		const next = {
+			redo: canRedo(history),
+			undo: canUndo(history)
+		};
+		setFlags((prev) => prev.undo === next.undo && prev.redo === next.redo ? prev : next);
+	}, [history]);
+	useEffect(() => {
+		const win = window;
+		win.__payloadUndoHistory = history;
+		return () => {
+			delete win.__payloadUndoHistory;
+		};
+	}, [history]);
+	useEffect(() => {
+		if (initializing || !fields || Object.keys(fields).length === 0) return;
+		const timer = setTimeout(() => {
+			const latest = fieldsRef.current;
+			if (!latest) return;
+			if (pushSnapshot(history, latest)) bumpRevision();
+			refreshFlags();
+		}, captureDebounce);
+		return () => clearTimeout(timer);
+	}, [
+		captureDebounce,
+		fields,
+		history,
+		initializing,
+		refreshFlags,
+		bumpRevision
+	]);
+	/**
+	* Set when this instance is the one clearing `modified`, which happens when a
+	* restore lands back on the saved state.
+	*
+	* The baseline is already correct in that case, by definition: the restore
+	* only reports clean because the entry it landed on matches the baseline.
+	* Re-recording it there reads live form state while the server merge that
+	* follows REPLACE_STATE is still in flight, so the baseline lands on a state
+	* that matches no entry, and moves again once the merge settles.
+	*/
+	const clearedByRestoreRef = useRef(false);
+	/**
+	* Re-baseline on every point Payload itself considers the form clean: a
+	* successful save or autosave, a reset, and the initial load. Reading
+	* Payload's own flag rather than watching for a save keeps the baseline
+	* correct for all of them without re-deriving what "saved" means.
+	*
+	* This records a baseline and deliberately does not touch the stack. Pushing
+	* here would run the redo-tail truncation in pushSnapshot, and since redoing
+	* onto the saved state makes the form clean, it would destroy the very branch
+	* redo had just stepped into.
+	*/
+	useEffect(() => {
+		if (!tracksSavedState) return;
+		if (modified) {
+			clearedByRestoreRef.current = false;
+			return;
+		}
+		if (initializing || !fieldsRef.current) return;
+		if (clearedByRestoreRef.current) {
+			clearedByRestoreRef.current = false;
+			return;
+		}
+		markSaved(history, fieldsRef.current);
+		bumpRevision();
+	}, [
+		bumpRevision,
+		history,
+		initializing,
+		modified,
+		tracksSavedState
+	]);
+	/**
+	* Restore the entry that `resolveTarget` picks. The target is resolved from
+	* the index *after* capturing pending edits, not before: capturing can move
+	* the index, and a relative step must be relative to where the user is.
+	*/
+	const applyRestore = useCallback((resolveTarget) => {
+		const current = fieldsRef.current;
+		if (!current) return;
+		pushSnapshot(history, current);
+		const target = resolveTarget(history.index);
+		const entry = history.stack[target];
+		if (!entry) {
+			refreshFlags();
+			bumpRevision();
+			return;
+		}
+		dispatchFields({
+			type: "REPLACE_STATE",
+			state: buildRestoreState(entry, current, isIgnored),
+			optimize: false
+		});
+		history.index = target;
+		const clean = tracksSavedState && isAtSavedState(history);
+		clearedByRestoreRef.current = clean;
+		setModified(!clean);
+		refreshFlags();
+		bumpRevision();
+	}, [
+		bumpRevision,
+		dispatchFields,
+		history,
+		isIgnored,
+		refreshFlags,
+		setModified,
+		tracksSavedState
+	]);
+	const restore = useCallback((direction) => applyRestore((index) => index + direction), [applyRestore]);
+	const undo = useCallback(() => restore(-1), [restore]);
+	const redo = useCallback(() => restore(1), [restore]);
+	const jumpTo = useCallback((index) => applyRestore(() => index), [applyRestore]);
+	/**
+	* Several edit forms can be mounted at once (document drawers). Only the
+	* instance belonging to the form the event happened in reacts; for events
+	* outside any form, the topmost open drawer wins.
+	*
+	* The form element comes from Payload's own form context rather than from a
+	* DOM ref of our own, so the rule holds wherever a host renders its controls,
+	* including outside the element it is scoping.
+	*
+	* Text-editing surfaces need no check here: react-hotkeys-hook skips form
+	* tags and contenteditable by default, which is exactly the rule we want,
+	* since native inputs own the browser's text undo and Lexical owns its own.
+	*/
+	const isForAnotherForm = useCallback((e) => {
+		const ourForm = formRef?.current;
+		const target = e.target instanceof HTMLElement ? e.target : null;
+		if (target && ourForm?.contains(target)) return false;
+		const targetForm = target?.closest("form");
+		if (targetForm) return targetForm !== ourForm;
+		const openDrawers = document.querySelectorAll(".drawer--is-open");
+		const topDrawer = openDrawers[openDrawers.length - 1];
+		return Boolean(topDrawer && ourForm && !topDrawer.contains(ourForm));
+	}, [formRef]);
+	const chords = useMemo(() => {
+		if (shortcuts === false) return null;
+		return {
+			redo: shortcuts?.redo ?? [...DEFAULT_SHORTCUTS.redo],
+			undo: shortcuts?.undo ?? [...DEFAULT_SHORTCUTS.undo]
+		};
+	}, [shortcuts]);
+	const hotkeyOptions = useMemo(() => ({
+		enabled: chords !== null,
+		ignoreEventWhen: isForAnotherForm,
+		preventDefault: true
+	}), [chords, isForAnotherForm]);
+	useHotkeys(chords?.undo ?? [], undo, hotkeyOptions, [undo]);
+	useHotkeys(chords?.redo ?? [], redo, hotkeyOptions, [redo]);
+	return {
+		canRedo: flags.redo,
+		canUndo: flags.undo,
+		chords,
+		fields,
+		history,
+		jumpTo,
+		redo,
+		revision,
+		tracksSavedState,
+		undo
+	};
+};
+//#endregion
+export { useUndoRedo };
+
+//# sourceMappingURL=useUndoRedo.js.map

package/dist/client/useUndoRedo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useUndoRedo.js","names":[],"sources":["../../src/client/useUndoRedo.ts"],"sourcesContent":["'use client'\nimport {\n\tuseAllFormFields,\n\tuseConfig,\n\tuseDocumentInfo,\n\tuseForm,\n\tuseFormInitializing,\n\tuseFormModified,\n} from '@payloadcms/ui'\nimport type { FormState } from 'payload'\nimport { useCallback, useEffect, useMemo, useRef, useState } from 'react'\nimport { useHotkeys } from 'react-hotkeys-hook'\n\nimport {\n\tbuildRestoreState,\n\tcanRedo,\n\tcanUndo,\n\tcreateHistory,\n\tisAtSavedState,\n\tMAX_HISTORY_ENTRIES,\n\tmarkSaved,\n\tpushSnapshot,\n\ttype UndoHistory,\n} from '../history/historyCore'\nimport { createPathMatcher } from '../history/pathPatterns'\nimport { createVolatileMatcher } from '../history/volatileValues'\nimport {\n\ttype ControlsClientProps,\n\tDEFAULT_CAPTURE_DEBOUNCE_MS,\n\tDEFAULT_SHORTCUTS,\n} from '../plugin/options'\nimport {\n\tbuildFieldSchemaMap,\n\tcollectIgnorePatterns,\n\ttype FieldSchemaMap,\n} from '../schema/fieldSchema'\n\n/** Shared so a document without a resolvable schema keeps a stable identity. */\nconst EMPTY_SCHEMA: FieldSchemaMap = new Map()\n\n/**\n * Every setting is optional so the hook stays usable when a host calls it by\n * hand rather than through the plugin, which always passes a fully resolved set.\n */\nexport type UseUndoRedoOptions = Partial<ControlsClientProps>\n\n/** The chords actually bound, or null when keyboard handling is off. */\nexport interface BoundChords {\n\tundo: string[]\n\tredo: string[]\n}\n\nexport interface UseUndoRedoResult {\n\t/** True when there is an earlier entry to step back to. */\n\tcanUndo: boolean\n\t/** True when there is a later entry to step forward to. */\n\tcanRedo: boolean\n\tundo: () => void\n\tredo: () => void\n\t/** Restore the entry at `index` in `history.stack`. Out-of-range indexes no-op. */\n\tjumpTo: (index: number) => void\n\t/** Live form state, as `useAllFormFields` reports it. */\n\tfields: FormState\n\t/**\n\t * The mutable history object backing this instance.\n\t *\n\t * Exposed so a custom control can mount `<HistoryDebugOverlay />` or inspect\n\t * the stack. It is an internal structure, not a stable contract: treat it as\n\t * read-only and expect its shape to change in a minor release.\n\t */\n\thistory: UndoHistory\n\t/**\n\t * Counter bumped on every capture and restore. Only moves when `debug` is on,\n\t * since it exists to pull the mutable history into React's render cycle for\n\t * the inspector and nothing else needs the re-renders.\n\t */\n\trevision: number\n\t/** False under autosave, where the saved baseline is deliberately not tracked. */\n\ttracksSavedState: boolean\n\t/** Resolved keyboard chords, for labelling. Null when `shortcuts` is false. */\n\tchords: BoundChords | null\n}\n\n/**\n * Undo/redo for the surrounding Payload form: a client-side history of\n * form-state snapshots, independent of Payload's document versions, with\n * nothing read from or written to the server until the user saves.\n *\n * Backs `<UndoRedoControls />` and is exported so a host can build its own\n * controls instead (pair it with `autoMount: false`). Must be called from\n * inside a document edit form; outside one it finds no fields and stays\n * disabled.\n *\n * One history per call. Two instances on the same form keep two independent\n * stacks and each captures the other's restores as fresh edits, so mount either\n * ours or yours, not both.\n */\nexport const useUndoRedo = ({\n\tcaptureDebounce = DEFAULT_CAPTURE_DEBOUNCE_MS,\n\tdebug = false,\n\tignoreFieldTypes,\n\tignorePaths,\n\tmaxHistory = MAX_HISTORY_ENTRIES,\n\tshortcuts,\n}: UseUndoRedoOptions = {}): UseUndoRedoResult => {\n\tconst [fields, dispatchFields] = useAllFormFields()\n\tconst { formRef, setModified } = useForm()\n\tconst initializing = useFormInitializing()\n\tconst modified = useFormModified()\n\tconst { getEntityConfig, config } = useConfig()\n\tconst { collectionSlug, globalSlug } = useDocumentInfo()\n\n\t/**\n\t * Ignore patterns from the config, plus the ones derived from the document's\n\t * own schema: fields the host opted out through `admin.custom`, and every\n\t * field of an excluded type. The schema is the only place a mounted\n\t * component can learn field types, since form state omits them unless\n\t * `buildFormState` was called with `includeSchema`, which the edit view never\n\t * does.\n\t */\n\tconst entity = useMemo(\n\t\t() =>\n\t\t\tcollectionSlug\n\t\t\t\t? getEntityConfig({ collectionSlug })\n\t\t\t\t: globalSlug\n\t\t\t\t\t? getEntityConfig({ globalSlug })\n\t\t\t\t\t: null,\n\t\t[collectionSlug, getEntityConfig, globalSlug]\n\t)\n\n\t/**\n\t * Autosave persists every edit continuously, so \"differs from what is\n\t * persisted\" is not a state the editor can meaningfully be in: the baseline\n\t * would move on every autosave, and an undo would immediately trigger one and\n\t * move it again. Tracking it there produces a saved marker that chases the\n\t * user around instead of telling them anything, so the whole baseline\n\t * mechanism is skipped and restores simply report the form as modified.\n\t */\n\tconst tracksSavedState = useMemo(() => {\n\t\tconst drafts = entity?.versions?.drafts\n\t\tconst autosave = typeof drafts === 'object' && drafts !== null ? drafts.autosave : false\n\t\treturn !autosave\n\t}, [entity])\n\n\tconst schema = useMemo(\n\t\t() =>\n\t\t\tentity ? buildFieldSchemaMap(entity.fields, { blocksMap: config.blocksMap }) : EMPTY_SCHEMA,\n\t\t[config.blocksMap, entity]\n\t)\n\n\tconst isIgnored = useMemo(\n\t\t() =>\n\t\t\tcreatePathMatcher([\n\t\t\t\t...(ignorePaths ?? []),\n\t\t\t\t...collectIgnorePatterns(schema, ignoreFieldTypes),\n\t\t\t]),\n\t\t[ignoreFieldTypes, ignorePaths, schema]\n\t)\n\n\tconst isVolatile = useMemo(() => createVolatileMatcher(schema), [schema])\n\n\tconst historyRef = useRef<UndoHistory | null>(null)\n\tif (historyRef.current === null) {\n\t\thistoryRef.current = createHistory({ isIgnored, isVolatile, maxHistory })\n\t}\n\tconst history = historyRef.current\n\t// Kept in sync rather than rebuilt, so changing a setting cannot silently\n\t// drop the entries the editor has already accumulated. Assigned during render\n\t// on purpose: an effect would leave a restore triggered between render and\n\t// commit reading the settings the user has just replaced.\n\thistory.options = { isIgnored, isVolatile, maxHistory }\n\n\tconst fieldsRef = useRef<FormState | null>(null)\n\tconst [flags, setFlags] = useState({ redo: false, undo: false })\n\t/**\n\t * Forces consumers to re-read the mutable history object, which is a ref and\n\t * therefore invisible to React. Only bumped under `debug`, so the default\n\t * build keeps re-rendering purely on the undo/redo flags.\n\t */\n\tconst [revision, setRevision] = useState(0)\n\n\tfieldsRef.current = fields\n\n\tconst bumpRevision = useCallback(() => {\n\t\tif (debug) setRevision((n) => n + 1)\n\t}, [debug])\n\n\tconst refreshFlags = useCallback(() => {\n\t\tconst next = { redo: canRedo(history), undo: canUndo(history) }\n\t\tsetFlags((prev) => (prev.undo === next.undo && prev.redo === next.redo ? prev : next))\n\t}, [history])\n\n\t// Debug/e2e handle: lets tests inspect the history without reaching into React.\n\tuseEffect(() => {\n\t\tconst win = window as Window & { __payloadUndoHistory?: UndoHistory }\n\t\twin.__payloadUndoHistory = history\n\t\treturn () => {\n\t\t\tdelete win.__payloadUndoHistory\n\t\t}\n\t}, [history])\n\n\tuseEffect(() => {\n\t\tif (initializing || !fields || Object.keys(fields).length === 0) return\n\t\tconst timer = setTimeout(() => {\n\t\t\tconst latest = fieldsRef.current\n\t\t\tif (!latest) return\n\t\t\tif (pushSnapshot(history, latest)) bumpRevision()\n\t\t\trefreshFlags()\n\t\t}, captureDebounce)\n\t\treturn () => clearTimeout(timer)\n\t}, [captureDebounce, fields, history, initializing, refreshFlags, bumpRevision])\n\n\t/**\n\t * Set when this instance is the one clearing `modified`, which happens when a\n\t * restore lands back on the saved state.\n\t *\n\t * The baseline is already correct in that case, by definition: the restore\n\t * only reports clean because the entry it landed on matches the baseline.\n\t * Re-recording it there reads live form state while the server merge that\n\t * follows REPLACE_STATE is still in flight, so the baseline lands on a state\n\t * that matches no entry, and moves again once the merge settles.\n\t */\n\tconst clearedByRestoreRef = useRef(false)\n\n\t/**\n\t * Re-baseline on every point Payload itself considers the form clean: a\n\t * successful save or autosave, a reset, and the initial load. Reading\n\t * Payload's own flag rather than watching for a save keeps the baseline\n\t * correct for all of them without re-deriving what \"saved\" means.\n\t *\n\t * This records a baseline and deliberately does not touch the stack. Pushing\n\t * here would run the redo-tail truncation in pushSnapshot, and since redoing\n\t * onto the saved state makes the form clean, it would destroy the very branch\n\t * redo had just stepped into.\n\t */\n\tuseEffect(() => {\n\t\tif (!tracksSavedState) return\n\t\tif (modified) {\n\t\t\tclearedByRestoreRef.current = false\n\t\t\treturn\n\t\t}\n\t\tif (initializing || !fieldsRef.current) return\n\t\tif (clearedByRestoreRef.current) {\n\t\t\tclearedByRestoreRef.current = false\n\t\t\treturn\n\t\t}\n\t\tmarkSaved(history, fieldsRef.current)\n\t\tbumpRevision()\n\t}, [bumpRevision, history, initializing, modified, tracksSavedState])\n\n\t/**\n\t * Restore the entry that `resolveTarget` picks. The target is resolved from\n\t * the index *after* capturing pending edits, not before: capturing can move\n\t * the index, and a relative step must be relative to where the user is.\n\t */\n\tconst applyRestore = useCallback(\n\t\t(resolveTarget: (indexAfterCapture: number) => number) => {\n\t\t\tconst current = fieldsRef.current\n\t\t\tif (!current) return\n\t\t\t// Capture pending (not yet debounced) edits first so undo steps back\n\t\t\t// from what the user actually sees, not from the last capture. Echoes\n\t\t\t// of a previous restore dedupe against the current entry and no-op.\n\t\t\tpushSnapshot(history, current)\n\t\t\tconst target = resolveTarget(history.index)\n\t\t\tconst entry = history.stack[target]\n\t\t\tif (!entry) {\n\t\t\t\trefreshFlags()\n\t\t\t\tbumpRevision()\n\t\t\t\treturn\n\t\t\t}\n\t\t\tdispatchFields({\n\t\t\t\ttype: 'REPLACE_STATE',\n\t\t\t\tstate: buildRestoreState(entry, current, isIgnored),\n\t\t\t\toptimize: false,\n\t\t\t})\n\t\t\thistory.index = target\n\t\t\t// Modified drives the \"leave without saving\" prompt and the save\n\t\t\t// button, so it has to answer \"does the form differ from what is\n\t\t\t// persisted\", not \"did something just happen\". Landing back on the\n\t\t\t// saved entry is a return to clean; anywhere else is a real change,\n\t\t\t// and marking it also makes the debounced onChange revalidate the\n\t\t\t// restored state on the server so save and autosave pick it up.\n\t\t\tconst clean = tracksSavedState && isAtSavedState(history)\n\t\t\tclearedByRestoreRef.current = clean\n\t\t\tsetModified(!clean)\n\t\t\trefreshFlags()\n\t\t\tbumpRevision()\n\t\t},\n\t\t[bumpRevision, dispatchFields, history, isIgnored, refreshFlags, setModified, tracksSavedState]\n\t)\n\n\tconst restore = useCallback(\n\t\t(direction: -1 | 1) => applyRestore((index) => index + direction),\n\t\t[applyRestore]\n\t)\n\n\tconst undo = useCallback(() => restore(-1), [restore])\n\tconst redo = useCallback(() => restore(1), [restore])\n\tconst jumpTo = useCallback((index: number) => applyRestore(() => index), [applyRestore])\n\n\t/**\n\t * Several edit forms can be mounted at once (document drawers). Only the\n\t * instance belonging to the form the event happened in reacts; for events\n\t * outside any form, the topmost open drawer wins.\n\t *\n\t * The form element comes from Payload's own form context rather than from a\n\t * DOM ref of our own, so the rule holds wherever a host renders its controls,\n\t * including outside the element it is scoping.\n\t *\n\t * Text-editing surfaces need no check here: react-hotkeys-hook skips form\n\t * tags and contenteditable by default, which is exactly the rule we want,\n\t * since native inputs own the browser's text undo and Lexical owns its own.\n\t */\n\tconst isForAnotherForm = useCallback(\n\t\t(e: KeyboardEvent): boolean => {\n\t\t\tconst ourForm = formRef?.current\n\t\t\tconst target = e.target instanceof HTMLElement ? e.target : null\n\t\t\tif (target && ourForm?.contains(target)) return false\n\t\t\tconst targetForm = target?.closest('form')\n\t\t\tif (targetForm) return targetForm !== ourForm\n\t\t\tconst openDrawers = document.querySelectorAll('.drawer--is-open')\n\t\t\tconst topDrawer = openDrawers[openDrawers.length - 1]\n\t\t\treturn Boolean(topDrawer && ourForm && !topDrawer.contains(ourForm))\n\t\t},\n\t\t[formRef]\n\t)\n\n\tconst chords = useMemo(() => {\n\t\tif (shortcuts === false) return null\n\t\treturn {\n\t\t\tredo: shortcuts?.redo ?? [...DEFAULT_SHORTCUTS.redo],\n\t\t\tundo: shortcuts?.undo ?? [...DEFAULT_SHORTCUTS.undo],\n\t\t}\n\t}, [shortcuts])\n\n\tconst hotkeyOptions = useMemo(\n\t\t() => ({\n\t\t\tenabled: chords !== null,\n\t\t\tignoreEventWhen: isForAnotherForm,\n\t\t\tpreventDefault: true,\n\t\t}),\n\t\t[chords, isForAnotherForm]\n\t)\n\n\tuseHotkeys(chords?.undo ?? [], undo, hotkeyOptions, [undo])\n\n\tuseHotkeys(chords?.redo ?? [], redo, hotkeyOptions, [redo])\n\n\treturn {\n\t\tcanRedo: flags.redo,\n\t\tcanUndo: flags.undo,\n\t\tchords,\n\t\tfields,\n\t\thistory,\n\t\tjumpTo,\n\t\tredo,\n\t\trevision,\n\t\ttracksSavedState,\n\t\tundo,\n\t}\n}\n"],"mappings":"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"}

package/dist/exports/client.d.ts

@@ -0,0 +1,4 @@
+import { HistoryDebugOverlay, HistoryDebugOverlayProps } from "../client/HistoryDebugOverlay.js";
+import { UndoRedoControls, UndoRedoControlsProps } from "../client/UndoRedoControls.js";
+import { BoundChords, UseUndoRedoOptions, UseUndoRedoResult, useUndoRedo } from "../client/useUndoRedo.js";
+export { type BoundChords, HistoryDebugOverlay, type HistoryDebugOverlayProps, UndoRedoControls, type UndoRedoControlsProps, type UseUndoRedoOptions, type UseUndoRedoResult, useUndoRedo };

package/dist/exports/client.js

@@ -0,0 +1,5 @@
+"use client";
+import { HistoryDebugOverlay } from "../client/HistoryDebugOverlay.js";
+import { useUndoRedo } from "../client/useUndoRedo.js";
+import { UndoRedoControls } from "../client/UndoRedoControls.js";
+export { HistoryDebugOverlay, UndoRedoControls, useUndoRedo };

package/dist/exports/i18n.d.ts

@@ -0,0 +1,3 @@
+import { TranslationKey, keys } from "../translations/keys.js";
+import { TranslationsOption, translations } from "../translations/index.js";
+export { type TranslationKey, type TranslationsOption, type TranslationKey as UndoRedoTranslationKeys, keys, translations };

package/dist/exports/i18n.js

@@ -0,0 +1,3 @@
+import { keys } from "../translations/keys.js";
+import { translations } from "../translations/index.js";
+export { keys, translations };

package/dist/exports/types.d.ts

@@ -0,0 +1,5 @@
+import { ComparableDiff, ComparableField, ComparableState, HistoryEntry, UndoHistory } from "../history/historyCore.js";
+import { ControlsClientProps, DocScope, ResolvedDocOptions, ShortcutKeys, UndoRedoDocOptions, UndoRedoPluginOptions } from "../plugin/options.js";
+import { UndoRedoFieldConfig } from "../schema/fieldConfig.js";
+import { FieldSchemaEntry, FieldSchemaMap, WalkableBlock, WalkableField, WalkableTab } from "../schema/fieldSchema.js";
+export type { ComparableDiff, ComparableField, ComparableState, ControlsClientProps, DocScope, FieldSchemaEntry, FieldSchemaMap, HistoryEntry, ResolvedDocOptions, ShortcutKeys, UndoHistory, UndoRedoDocOptions, UndoRedoFieldConfig, UndoRedoPluginOptions, WalkableBlock, WalkableField, WalkableTab };

package/dist/exports/types.js

@@ -0,0 +1 @@
+export {};

package/dist/history/historyCore.d.ts

@@ -0,0 +1,85 @@
+import { PathMatcher } from "./pathPatterns.js";
+import { FormState } from "payload";
+
+//#region src/history/historyCore.d.ts
+interface ComparableField {
+  /** Absent for array and blocks fields, whose `value` carries no information (see extractComparableField). */
+  value?: unknown;
+  /** Row ids in order, which captures array/blocks row additions, deletions and moves. */
+  rowIds?: (string | undefined)[];
+}
+/** The slice of form state that counts as a user-visible edit. */
+type ComparableState = Record<string, ComparableField>;
+interface HistoryEntry {
+  /**
+   * Monotonic id, stable across the stack shifting when the cap evicts the
+   * oldest entries. Positional indexes are not stable for that reason, so
+   * anything keyed per entry (React keys, debug UI expansion) uses this.
+   */
+  id: number;
+  fields: FormState;
+  comparable: ComparableState;
+}
+/**
+ * True for a field whose current value the history cannot put back.
+ *
+ * Payload's JSON field is the case this exists for. While its text does not
+ * parse, the field writes the raw editor text into form state as a string, and
+ * the editor is then rendered from `JSON.stringify(value)`, so dispatching that
+ * string back would show it double-encoded rather than as the text the editor
+ * had. No value we could dispatch reproduces broken text, so rather than record
+ * a state it cannot honour, a capture carries the last value it can (see
+ * pushSnapshot).
+ */
+type VolatileMatcher = (path: string, field: FormState[string]) => boolean;
+/**
+ * Per-history settings. They live on the history object rather than being
+ * threaded through every call so that a snapshot and the restore built from it
+ * can never disagree about which paths are in scope.
+ */
+interface HistoryOptions {
+  /** Paths excluded from capture and from restore. */
+  isIgnored: PathMatcher;
+  /** Paths whose live value is captured as the previous entry's instead. */
+  isVolatile: VolatileMatcher;
+  /** Entries kept before the oldest is evicted. */
+  maxHistory: number;
+}
+interface UndoHistory {
+  stack: HistoryEntry[];
+  /** Index of the entry representing the current form state. */
+  index: number;
+  /**
+   * The comparable state of the persisted document, or null before anything has
+   * been saved or loaded.
+   *
+   * This is what makes the "leave without saving" prompt truthful in both
+   * directions. Undoing back to the *first* entry is not the same as being
+   * unsaved: after a save, the baseline moves to wherever the document was
+   * saved from, and stepping back past that point is a real unsaved change even
+   * though the form looks like it did on load.
+   *
+   * Held as a value rather than an index on purpose. An index has to be
+   * renumbered when the cap evicts entries and invalidated when a new edit
+   * drops the redo tail, and recording one meant pushing a snapshot at save
+   * time, which truncated the redo tail through the very branch redo was about
+   * to walk into. A value needs none of that bookkeeping and lets the baseline
+   * be recorded without touching the stack at all.
+   */
+  savedComparable: ComparableState | null;
+  options: HistoryOptions;
+}
+/** A single path-level change between two comparable states. */
+interface ComparableDiff {
+  path: string;
+  from: unknown;
+  to: unknown;
+  /** Set only when the path carries array/blocks rows and those rows changed. */
+  fromRowIds?: (string | undefined)[];
+  toRowIds?: (string | undefined)[];
+  /** Whether the path itself appeared or disappeared between the two states. */
+  presence?: 'added' | 'removed';
+}
+//#endregion
+export { ComparableDiff, ComparableField, ComparableState, HistoryEntry, UndoHistory };
+//# sourceMappingURL=historyCore.d.ts.map