@particle-academy/fancy-cms-ui 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -14,6 +14,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-10-23
+
+### Added
+
+- `Editor` accepts controlled `value`, native-operation `onOp` and `disabled`
+  props for server-owned shared documents. Local edits propose changes; only
+  the next host value changes the controlled document. Incoming values preserve
+  the selected handle and never echo through either callback. Local snapshot
+  Undo/Redo is disabled in controlled mode to protect other writers' work.
+  - Inspector fields keep a local draft, so typing survives server latency,
+    including while `disabled` pauses structural edits and submissions. Drafts
+    commit after 250 ms idle or on blur, one acknowledgement at a time, and
+    wait for IME composition to finish.
+  - When another writer changes the field being drafted, a save is rejected or
+    never acknowledged, or the node is removed, the draft is kept and the
+    inspector offers **Use server value** / **Keep draft**. Text is never
+    silently lost or overwritten.
+  - The host contract (compare-and-set, serialization, pending, unmount) is in
+    the README. Nothing changes for an uncontrolled `Editor`.
+
+### Fixed
+
+- An uncontrolled `Editor` mounted under React StrictMode no longer emits an
+  initial `onChange` before any edit.
+
+### Security
+
+- **vitest 4.1.12 in development** (was 4.1.11), clearing GHSA-qxg6-89mg-rqv8
+  and GHSA-xp26-3454-mjgp in `@vitest/mocker`. Test tooling only: nothing in
+  the published package changes, so **nothing to do** as a consumer.
+
 ## [0.9.0] - 2026-10-23
 
 Released together with `particle-academy/fancy-cms` 0.5.0, whose PHP renderer

package/README.md

@@ -72,6 +72,52 @@ Lean subpath entries also exist: `@particle-academy/fancy-cms-ui/react`
 the inline `EditablePage` — the one component that additionally requires the
 optional `@particle-academy/react-fancy` peer).
 
+### A server-owned document
+
+Use `value` when a server or another writer owns the document. The canvas shows
+accepted host state. Inspector fields keep local drafts so typing continues
+without reverting while a save is pending. A field proposes a native `PageOp`
+through `onOp` and a reduced document through `onChange` after 250 ms without
+typing, or on blur. IME composition finishes before submission. Choose one
+callback to submit writes; the other can observe proposals. Incoming values do
+not echo themselves through these callbacks and preserve the selected handle.
+
+```tsx
+import { Editor, type PageDoc, type PageOp } from "@particle-academy/fancy-cms-ui";
+
+function SharedAuthor({ doc, pending, submit }: {
+  doc: PageDoc;
+  pending: boolean;
+  submit: (op: PageOp) => void;
+}) {
+  return <Editor value={doc} onOp={submit} disabled={pending} />;
+}
+```
+
+The host validates and authorizes each operation, pins it to the current server
+revision, and supplies accepted state through `value`. Keep `pending` true while
+a write is being accepted, and clear it after publishing the accepted or
+rejected server state. `disabled` blocks structural edits and draft submission;
+controlled inspector fields remain editable. Additional typing stays buffered
+until the prior field value is acknowledged. Inspector proposals are serialized
+even if the host omits `disabled`; the host must still serialize and revision-pin
+all writes. An operation-only host can omit `onChange`.
+
+Incoming state updates other fields immediately. If it changes a drafted field,
+the draft stays visible with a conflict. Choose **Use server value** to discard
+it or **Keep draft** to submit it against the current state. The editor never
+silently retries a conflict. Clearing `pending` without accepting the field,
+or receiving no acknowledgement for 10 seconds, also retains the draft and
+surfaces a decision. Node removal retains copyable draft text without recreating
+the node. Keep this editor mounted while drafts or writes are outstanding;
+navigation/unmount is owned by the host.
+
+Controlled editors disable local snapshot Undo/Redo, since restoring an old
+snapshot could overwrite another writer. The `defaultValue` mode retains local
+history and reports document changes through `onChange`. Choose one ownership
+mode for an editor's lifetime. In uncontrolled mode, `disabled` blocks property
+edits as well.
+
 ### Styling
 
 There is **no stylesheet to import**. Authored page styles are compiled by the

package/dist/{chunk-BVMSHUQF.js → chunk-G7ULXTKI.js}

@@ -1,5 +1,5 @@
 import { migrateDoc, reduce, CmsPage, rootIds, childrenOf, lastRootId, emptyDoc } from './chunk-IRG5IKKO.js';
-import { useReducer, useCallback, useMemo, useRef, useState, useLayoutEffect, Fragment, useId, useEffect } from 'react';
+import { useReducer, useCallback, useMemo, useRef, useState, useLayoutEffect, Fragment, useId, useEffect, useSyncExternalStore } from 'react';
 import { jsxs, jsx, Fragment as Fragment$1 } from 'react/jsx-runtime';
 import { fractionalKey } from '@particle-academy/fancy-doc-commons';
 
@@ -243,16 +243,42 @@ var input = {
   font: "inherit",
   fontSize: 13
 };
-function Inspector({ doc, selection, apply }) {
+function Inspector({ doc, selection, apply, drafts }) {
   const uid = useId();
   const fieldId = (key) => `${uid}-${key}`;
   const node = selection ? doc.nodes[selection] : null;
   if (!node) {
     return /* @__PURE__ */ jsx("div", { style: { padding: 16, color: "var(--fcms-muted)", fontFamily: "system-ui, sans-serif", fontSize: 13 }, children: "Select an element to edit." });
   }
-  const s = node.style.base;
-  const setStyle = (patch) => apply({ t: "set_style", id: node.id, breakpoint: "base", patch });
-  const setProp = (key, value) => apply({ t: "set_node_props", id: node.id, patch: { [key]: value } });
+  const nodeId = node.id;
+  const bind = (name, read, op, numeric = false) => {
+    const key = JSON.stringify([nodeId, name]);
+    const field = {
+      key,
+      label: `${nodeId} / ${name}`,
+      op,
+      read: (next) => {
+        const item = next.nodes[nodeId];
+        return item ? read(item) : void 0;
+      },
+      canonical: numeric ? (raw) => String(Number(raw) || 0) : (raw) => raw
+    };
+    const accepted = read(node);
+    return {
+      value: drafts ? drafts.value(key, accepted) : accepted,
+      onChange: (event) => {
+        if (drafts) drafts.change(field, event.target.value);
+        else apply(op(event.target.value));
+      },
+      onFocus: () => drafts?.focus(key),
+      onBlur: () => drafts?.blur(key),
+      onCompositionStart: () => drafts?.composition(key, true),
+      onCompositionEnd: () => drafts?.composition(key, false)
+    };
+  };
+  const prop = (key) => bind(key, (item) => typeof item.props[key] === "string" ? item.props[key] : "", (raw) => ({ t: "set_node_props", id: nodeId, patch: { [key]: raw } }));
+  const style = (key) => bind(key, (item) => item.style.base[key] ?? "", (raw) => ({ t: "set_style", id: nodeId, breakpoint: "base", patch: { [key]: raw } }));
+  const length = (key) => bind(key, (item) => item.style.base[key]?.value?.toString() ?? "", (raw) => ({ t: "set_style", id: nodeId, breakpoint: "base", patch: { [key]: { value: Number(raw) || 0, unit: "px" } } }), true);
   return /* @__PURE__ */ jsxs("div", { style: { overflow: "auto", padding: 16, fontFamily: "system-ui, sans-serif", height: "100%", boxSizing: "border-box" }, children: [
     /* @__PURE__ */ jsx("div", { style: { fontSize: 13, fontWeight: 600, color: "var(--fcms-fg)" }, children: node.type }),
     /* @__PURE__ */ jsx("div", { style: { fontSize: 11, color: "var(--fcms-muted)", marginBottom: 8 }, children: node.id }),
@@ -264,8 +290,7 @@ function Inspector({ doc, selection, apply }) {
           id: fieldId("content"),
           "data-cms-field": "content",
           style: { ...input, minHeight: 64, resize: "vertical" },
-          value: typeof node.props.content === "string" ? node.props.content : "",
-          onChange: (e) => setProp("content", e.target.value)
+          ...prop("content")
         }
       )
     ] }) : null,
@@ -277,8 +302,7 @@ function Inspector({ doc, selection, apply }) {
           id: fieldId("src"),
           "data-cms-field": "src",
           style: input,
-          value: typeof node.props.src === "string" ? node.props.src : "",
-          onChange: (e) => setProp("src", e.target.value)
+          ...prop("src")
         }
       )
     ] }) : null,
@@ -290,8 +314,7 @@ function Inspector({ doc, selection, apply }) {
         "data-cms-field": "background",
         style: input,
         placeholder: "#ffffff | gradient | url(\u2026)",
-        value: s.background ?? "",
-        onChange: (e) => setStyle({ background: e.target.value })
+        ...style("background")
       }
     ),
     /* @__PURE__ */ jsx("label", { style: label, htmlFor: fieldId("color"), children: "Text color" }),
@@ -302,8 +325,7 @@ function Inspector({ doc, selection, apply }) {
         "data-cms-field": "color",
         style: input,
         placeholder: "#0f172a",
-        value: s.color ?? "",
-        onChange: (e) => setStyle({ color: e.target.value })
+        ...style("color")
       }
     ),
     /* @__PURE__ */ jsx("label", { style: label, htmlFor: fieldId("fontSize"), children: "Font size (px)" }),
@@ -314,8 +336,7 @@ function Inspector({ doc, selection, apply }) {
         "data-cms-field": "fontSize",
         type: "number",
         style: input,
-        value: s.fontSize?.value ?? "",
-        onChange: (e) => setStyle({ fontSize: { value: Number(e.target.value) || 0, unit: "px" } })
+        ...length("fontSize")
       }
     ),
     /* @__PURE__ */ jsx("label", { style: label, htmlFor: fieldId("padding"), children: "Padding (px)" }),
@@ -326,8 +347,7 @@ function Inspector({ doc, selection, apply }) {
         "data-cms-field": "padding",
         type: "number",
         style: input,
-        value: s.padding?.value ?? "",
-        onChange: (e) => setStyle({ padding: { value: Number(e.target.value) || 0, unit: "px" } })
+        ...length("padding")
       }
     ),
     /* @__PURE__ */ jsx("label", { style: label, htmlFor: fieldId("opacity"), children: "Opacity" }),
@@ -341,8 +361,7 @@ function Inspector({ doc, selection, apply }) {
         min: "0",
         max: "1",
         style: input,
-        value: s.opacity ?? "",
-        onChange: (e) => setStyle({ opacity: Number(e.target.value) })
+        ...bind("opacity", (item) => item.style.base.opacity?.toString() ?? "", (raw) => ({ t: "set_style", id: nodeId, breakpoint: "base", patch: { opacity: Number(raw) } }), true)
       }
     )
   ] });
@@ -427,18 +446,219 @@ function useLatestRef(value) {
   });
   return ref;
 }
-function Editor({ defaultValue, onChange, registry, data }) {
+
+// src/editor/InspectorDrafts.ts
+var InspectorDrafts = class {
+  constructor(doc) {
+    this.doc = doc;
+    this.drafts = /* @__PURE__ */ new Map();
+    this.composing = /* @__PURE__ */ new Set();
+    this.focused = null;
+    this.flight = null;
+    this.listeners = /* @__PURE__ */ new Set();
+    this.version = 0;
+    this.disabled = false;
+    this.emit = () => false;
+    this.subscribe = (listener) => {
+      this.listeners.add(listener);
+      return () => {
+        this.listeners.delete(listener);
+      };
+    };
+    this.snapshot = () => this.version;
+  }
+  get busy() {
+    return this.flight !== null || [...this.drafts.values()].some((draft) => draft.dirty || draft.conflict !== null);
+  }
+  get conflicts() {
+    return [...this.drafts.values()].filter((draft) => draft.conflict !== null).map((draft) => ({
+      key: draft.field.key,
+      label: draft.field.label,
+      message: draft.conflict,
+      missing: draft.field.read(this.doc) === void 0
+    }));
+  }
+  value(key, accepted) {
+    return this.drafts.get(key)?.raw ?? accepted;
+  }
+  configure(doc, disabled, emit) {
+    const settled = this.disabled && !disabled;
+    this.doc = doc;
+    this.disabled = disabled;
+    this.emit = emit;
+    let changed = false;
+    for (const [key, draft] of this.drafts) {
+      const accepted = draft.field.read(doc);
+      if (this.flight?.draft === draft && accepted === this.flight.expected) {
+        this.clearFlight();
+        draft.base = accepted;
+        draft.dirty = draft.field.canonical(draft.raw) !== accepted;
+        if (!draft.dirty && !draft.focused) this.drafts.delete(key);
+        changed = true;
+      } else if (accepted !== draft.base) {
+        this.conflict(draft, accepted === void 0 ? "The edited element was removed. Your draft is retained." : "The server changed this field. Your draft is retained.");
+        draft.base = accepted;
+        changed = true;
+      } else if (settled && this.flight?.draft === draft) {
+        this.conflict(draft, "The save was not accepted. Your draft is retained.");
+        changed = true;
+      }
+    }
+    if (changed) this.notify();
+    this.arm();
+  }
+  focus(key) {
+    this.focused = key;
+    const draft = this.drafts.get(key);
+    if (draft) draft.focused = true;
+  }
+  change(field, raw) {
+    let draft = this.drafts.get(field.key);
+    if (!draft) {
+      draft = { field, raw, base: field.read(this.doc), focused: this.focused === field.key, dirty: true, conflict: null, readyAt: Date.now() + 250 };
+      this.drafts.set(field.key, draft);
+    } else {
+      draft.field = field;
+      draft.raw = raw;
+      draft.readyAt = Date.now() + 250;
+    }
+    draft.dirty = field.canonical(raw) !== draft.base;
+    this.notify();
+    this.arm();
+  }
+  blur(key) {
+    if (this.focused === key) this.focused = null;
+    const draft = this.drafts.get(key);
+    if (draft) {
+      draft.focused = false;
+      draft.readyAt = Date.now();
+      if (!draft.dirty && !draft.conflict && this.flight?.draft !== draft) this.drafts.delete(key);
+      this.notify();
+      this.pump();
+    }
+  }
+  composition(key, active) {
+    if (active) this.composing.add(key);
+    else this.composing.delete(key);
+    const draft = this.drafts.get(key);
+    if (draft) draft.readyAt = Date.now() + 250;
+    this.arm();
+  }
+  resolve(key, keep) {
+    if (this.disabled) return;
+    const draft = this.drafts.get(key);
+    if (!draft) return;
+    if (this.flight?.draft === draft) this.clearFlight();
+    if (!keep) this.drafts.delete(key);
+    else {
+      const accepted = draft.field.read(this.doc);
+      if (accepted === void 0) return;
+      draft.base = accepted;
+      draft.conflict = null;
+      draft.dirty = draft.field.canonical(draft.raw) !== accepted;
+      draft.readyAt = Date.now();
+      if (!draft.dirty && !draft.focused) this.drafts.delete(key);
+    }
+    this.notify();
+    this.pump();
+  }
+  dispose() {
+    clearTimeout(this.timer);
+    clearTimeout(this.ackTimer);
+  }
+  notify() {
+    this.version++;
+    for (const listener of this.listeners) listener();
+  }
+  clearFlight() {
+    this.flight = null;
+    clearTimeout(this.ackTimer);
+    this.ackTimer = void 0;
+  }
+  conflict(draft, message) {
+    draft.conflict = message;
+    if (this.flight?.draft === draft) this.clearFlight();
+  }
+  arm() {
+    clearTimeout(this.timer);
+    this.timer = void 0;
+    if (this.disabled || this.flight || this.conflicts.length > 0) return;
+    const ready = [...this.drafts.values()].filter((draft) => draft.dirty && !this.composing.has(draft.field.key));
+    if (ready.length) this.timer = setTimeout(() => this.pump(), Math.max(0, Math.min(...ready.map((draft) => draft.readyAt)) - Date.now()));
+  }
+  pump() {
+    if (this.disabled || this.flight || this.conflicts.length > 0) return;
+    const draft = [...this.drafts.values()].find((item) => item.dirty && item.readyAt <= Date.now() && !this.composing.has(item.field.key));
+    if (!draft) {
+      this.arm();
+      return;
+    }
+    this.flight = { draft, expected: draft.field.canonical(draft.raw) };
+    this.ackTimer = setTimeout(() => {
+      this.conflict(draft, "The save has not been acknowledged. Your draft is retained.");
+      this.notify();
+    }, 1e4);
+    try {
+      if (!this.emit(draft.field.op(draft.raw))) this.conflict(draft, "This edit could not be submitted. Your draft is retained.");
+    } catch {
+      this.conflict(draft, "This edit could not be submitted. Your draft is retained.");
+    }
+    this.notify();
+  }
+};
+function Editor({ value, defaultValue, onChange, onOp, disabled = false, registry, data }) {
   const initial = useMemo(() => defaultValue ?? emptyDoc("untitled"), [defaultValue]);
-  const ed = useEditor(initial);
-  const first = useRef(true);
+  const local = useEditor(initial);
+  const controlled = value !== void 0;
+  const localDoc = useLatestRef(local.state.doc);
+  const lastNotified = useRef(local.state.doc);
+  const onOpRef = useLatestRef(onOp);
+  const [drafts] = useState(() => new InspectorDrafts(value ?? initial));
+  useSyncExternalStore(drafts.subscribe, drafts.snapshot, drafts.snapshot);
   const onChangeRef = useLatestRef(onChange);
   useEffect(() => {
-    if (first.current) {
-      first.current = false;
-      return;
+    if (controlled || lastNotified.current === local.state.doc) return;
+    lastNotified.current = local.state.doc;
+    onChangeRef.current?.(local.state.doc);
+  }, [controlled, local.state.doc, onChangeRef]);
+  const apply = (op) => {
+    if (disabled) return false;
+    const source = value ?? localDoc.current;
+    const next = reduce(source, op);
+    if (next === source) return false;
+    if (!controlled) {
+      localDoc.current = next;
+      local.apply(op);
     }
-    onChangeRef.current?.(ed.state.doc);
-  }, [ed.state.doc, onChangeRef]);
+    onOpRef.current?.(op);
+    if (controlled) onChangeRef.current?.(next);
+    return true;
+  };
+  useEffect(() => {
+    if (controlled) drafts.configure(value, disabled, apply);
+  });
+  useEffect(() => () => drafts.dispose(), [drafts]);
+  const structuralDisabled = disabled || controlled && drafts.busy;
+  const ed = {
+    ...local,
+    state: { ...local.state, doc: value ?? local.state.doc },
+    apply: (op) => {
+      if (!structuralDisabled) apply(op);
+    },
+    // Snapshot history belongs to the local document. Replaying it into a
+    // server-owned value could overwrite another writer's accepted work.
+    undo: () => {
+      if (!controlled && !disabled) local.undo();
+    },
+    redo: () => {
+      if (!controlled && !disabled) local.redo();
+    },
+    replace: (next) => {
+      if (!controlled && !disabled) local.replace(next);
+    },
+    canUndo: !controlled && !disabled && local.canUndo,
+    canRedo: !controlled && !disabled && local.canRedo
+  };
   const shell = {
     display: "grid",
     gridTemplateColumns: "220px 1fr 300px",
@@ -450,9 +670,9 @@ function Editor({ defaultValue, onChange, registry, data }) {
     borderRadius: 12,
     overflow: "hidden"
   };
-  return /* @__PURE__ */ jsxs("div", { className: "fancy-cms-editor", style: shell, children: [
+  return /* @__PURE__ */ jsxs("div", { className: "fancy-cms-editor", style: shell, "aria-busy": structuralDisabled || void 0, children: [
     /* @__PURE__ */ jsx("style", { children: CHROME_CSS }),
-    /* @__PURE__ */ jsxs("div", { style: { borderRight: "1px solid var(--fcms-border)", display: "flex", flexDirection: "column", minHeight: 0 }, children: [
+    /* @__PURE__ */ jsx("fieldset", { disabled: structuralDisabled, "aria-label": "Page structure controls", style: { display: "contents", border: 0, padding: 0, margin: 0 }, children: /* @__PURE__ */ jsxs("div", { style: { borderRight: "1px solid var(--fcms-border)", display: "flex", flexDirection: "column", minHeight: 0 }, children: [
       /* @__PURE__ */ jsx(Toolbar, { ed }),
       /* @__PURE__ */ jsx(
         LayersPanel,
@@ -463,9 +683,22 @@ function Editor({ defaultValue, onChange, registry, data }) {
           onMove: (id, parent, order) => ed.apply({ t: "move_node", id, parent, order })
         }
       )
-    ] }),
+    ] }) }),
     /* @__PURE__ */ jsx(Canvas, { doc: ed.state.doc, selection: ed.state.selection, onSelect: ed.select, apply: ed.apply, registry, data }),
-    /* @__PURE__ */ jsx("div", { style: { borderLeft: "1px solid var(--fcms-border)", minHeight: 0 }, children: /* @__PURE__ */ jsx(Inspector, { doc: ed.state.doc, selection: ed.state.selection, apply: ed.apply }) })
+    /* @__PURE__ */ jsxs("div", { style: { borderLeft: "1px solid var(--fcms-border)", minHeight: 0, overflow: "auto" }, children: [
+      controlled && drafts.conflicts.map((conflict) => /* @__PURE__ */ jsxs("div", { role: "alert", "data-cms-draft-conflict": conflict.key, style: { padding: 12, fontFamily: "system-ui,sans-serif", fontSize: 13 }, children: [
+        /* @__PURE__ */ jsxs("p", { children: [
+          conflict.label,
+          ": ",
+          conflict.message
+        ] }),
+        /* @__PURE__ */ jsx("pre", { "data-cms-retained-draft": "", style: { whiteSpace: "pre-wrap", overflowWrap: "anywhere" }, children: drafts.value(conflict.key, "") }),
+        /* @__PURE__ */ jsx("button", { type: "button", disabled, onClick: () => drafts.resolve(conflict.key, false), children: "Use server value" }),
+        " ",
+        /* @__PURE__ */ jsx("button", { type: "button", disabled: disabled || conflict.missing, onClick: () => drafts.resolve(conflict.key, true), children: "Keep draft" })
+      ] }, conflict.key)),
+      /* @__PURE__ */ jsx("fieldset", { disabled: !controlled && disabled, "aria-label": "Page property controls", style: { border: 0, padding: 0, margin: 0, minWidth: 0, height: "100%" }, children: /* @__PURE__ */ jsx(Inspector, { doc: ed.state.doc, selection: ed.state.selection, apply: ed.apply, drafts: controlled ? drafts : void 0 }) })
+    ] })
   ] });
 }
 function Toolbar({ ed }) {
@@ -576,5 +809,5 @@ var LIGHT_VARS = "color-scheme:light;--fcms-bg:#ffffff;--fcms-fg:#0f172a;--fcms-
 var CHROME_CSS = `.fancy-cms-editor{--fcms-accent:#8b5cf6;${LIGHT_VARS}}@media (prefers-color-scheme:dark){.fancy-cms-editor{${DARK_VARS}}}:where(.light,[data-theme="light"]) .fancy-cms-editor{${LIGHT_VARS}}:where(.dark,[data-theme="dark"]) .fancy-cms-editor{${DARK_VARS}}`;
 
 export { ADD_DEFAULTS, ADD_MENU, CONTAINER_TYPES, Canvas, Editor, Inspector, LayersPanel, buildInsertOp, editorReduce, initEditor, resolveInsertParent, useEditor, useLatestRef };
-//# sourceMappingURL=chunk-BVMSHUQF.js.map
-//# sourceMappingURL=chunk-BVMSHUQF.js.map
+//# sourceMappingURL=chunk-G7ULXTKI.js.map
+//# sourceMappingURL=chunk-G7ULXTKI.js.map