@revisium/schema-toolkit-ui 0.6.8 → 0.6.9

package/README.md

@@ -284,6 +284,54 @@ core.applyViewState(s)  // restore view settings
 core.dispose()          // cleanup
 ```
 
+## Hooks
+
+### `useContentEditable`
+
+A controlled `contenteditable` hook that manages DOM synchronization, cursor position, and keyboard shortcuts.
+
+```tsx
+import { useContentEditable } from '@revisium/schema-toolkit-ui';
+
+const editableProps = useContentEditable({
+  value,
+  onChange: (v) => setValue(v),
+  onBlur: () => { /* called after DOM is synced */ },
+  onFocus: () => {},
+  onEnter: () => { /* Enter key pressed with non-empty value */ },
+  onEscape: () => { /* Escape key pressed */ },
+  restrict: /^[a-z0-9-]$/, // optional — block disallowed keys
+  autoFocus: true,          // optional — focus on mount
+  focusTrigger: n,          // optional — increment to focus programmatically
+});
+
+return <div data-testid="editable" {...editableProps} />;
+```
+
+#### How it works
+
+`dangerouslySetInnerHTML` sets the initial DOM content. After that React does not overwrite the DOM on re-renders (standard contenteditable contract). The hook handles synchronization explicitly:
+
+| Event | Behaviour |
+|-------|-----------|
+| User types | `onChange(value)` called on every `input` event. Cursor position is preserved across re-renders. |
+| `value` prop changes while **not focused** | DOM updated immediately via `textContent`. |
+| `value` prop changes while **focused** | DOM is left untouched so the user can keep typing without interruption. |
+| `blur` | If `value` diverged from DOM (e.g. external revert happened while focused), DOM is synced to `value` before `onBlur` is called. |
+| `Enter` | `blur()` called then `onEnter()` (only when `value` is non-empty). |
+| `Escape` | `blur()` called then `onEscape()`. |
+
+#### Controlled revert pattern
+
+Because DOM sync on blur is guaranteed, a revert triggered while the element is focused will correctly reset the displayed text when the user leaves the field:
+
+```tsx
+// External state revert while user is typing:
+//   value prop → 'original'
+//   DOM         → 'user typed...'  (untouched during focus)
+//   on blur    → DOM is reset to 'original' ✓
+```
+
 ### Cleanup
 
 Call `vm.dispose()` (or `core.dispose()` for `TableEditorCore`) when the editor is unmounted.

package/dist/index.cjs

@@ -2550,6 +2550,11 @@ function useContentEditable(options) {
 	const prevFocusTriggerRef = (0, react.useRef)(focusTrigger);
 	const optionsRef = (0, react.useRef)(options);
 	optionsRef.current = options;
+	const isFocusedRef = (0, react.useRef)(false);
+	(0, react.useEffect)(() => {
+		const el = elementRef.current;
+		if (el && !isFocusedRef.current && el.textContent !== value) el.textContent = value;
+	}, [value]);
 	const ref = (0, react.useCallback)((node) => {
 		elementRef.current = node;
 	}, []);
@@ -2592,10 +2597,14 @@ function useContentEditable(options) {
 		optionsRef.current.onChange?.(val);
 	}, []);
 	const handleBlur = (0, react.useCallback)(() => {
+		isFocusedRef.current = false;
+		const el = elementRef.current;
+		if (el && el.textContent !== optionsRef.current.value) el.textContent = optionsRef.current.value;
 		optionsRef.current.onBlur?.();
 		cursorPosition.current = null;
 	}, []);
 	const handleFocus = (0, react.useCallback)(() => {
+		isFocusedRef.current = true;
 		optionsRef.current.onFocus?.();
 	}, []);
 	const handleKeyDown = (0, react.useCallback)((event) => {
@@ -11117,6 +11126,9 @@ function clearPendingContextMenu() {
 function setPendingContextMenu(value) {
 	pendingContextMenu = value;
 }
+function hasPendingContextMenu() {
+	return pendingContextMenu !== null;
+}
 const cellMenuRegistry = /* @__PURE__ */ new WeakMap();
 function useCellContextMenu(cell, cellRef, deferredEdit) {
 	const [menuAnchor, setMenuAnchor] = (0, react.useState)(null);
@@ -11373,7 +11385,7 @@ const CellWrapper = (0, mobx_react_lite.observer)(({ cell, children, onDoubleCli
 	const handleMouseDown = (0, react.useCallback)((e) => {
 		if (e.detail === 2 && state !== "readonly" && state !== "readonlyFocused") e.preventDefault();
 		if (e.button === 2) {
-			openContextMenuAt(e.clientX, e.clientY);
+			if (!hasPendingContextMenu()) openContextMenuAt(e.clientX, e.clientY);
 			return;
 		}
 		if (!e.shiftKey && e.button === 0 && state !== "editing") {