@elytracms/studio 0.0.42 → 0.0.43

package/dist/components/cms/discard-draft.d.ts

@@ -30,3 +30,21 @@ export declare function discardDraftStatus(input: {
     collection: CollectionDef;
     draft: CmsDocument;
 }): DiscardDraftStatus;
+/**
+ * EC-325 — the flush-before-restore ordering "Discard changes" must follow,
+ * mirroring the IDENTICAL `if (dirty) save()` step the Versions pane's
+ * (`versions-pane.tsx`'s `handleRestore`) and the Compare view's
+ * (`version-compare.tsx`'s `restore`) own restores already take before theirs.
+ * `documents.restore` (`packages/core/src/operations/documents.ts`) snapshots
+ * whatever is currently PERSISTED as its own "pre-restore" version — never the
+ * client's in-memory draft — so an edit still sitting in the autosave debounce
+ * window when Discard fires would otherwise never reach the server and be
+ * silently unrecoverable once the draft is reverted. The underlying
+ * save/restore commands are serialized by the shared operations queue
+ * (EC-225), so the un-awaited `save()` here still lands before `restore` reads
+ * the persisted document.
+ */
+export declare function flushDirtyDraft(input: {
+    dirty: boolean;
+    save: () => void;
+}): void;

package/dist/components/cms/discard-draft.js

@@ -10,4 +10,22 @@ export function discardDraftStatus(input) {
         ? 'up-to-date'
         : 'ready';
 }
+/**
+ * EC-325 — the flush-before-restore ordering "Discard changes" must follow,
+ * mirroring the IDENTICAL `if (dirty) save()` step the Versions pane's
+ * (`versions-pane.tsx`'s `handleRestore`) and the Compare view's
+ * (`version-compare.tsx`'s `restore`) own restores already take before theirs.
+ * `documents.restore` (`packages/core/src/operations/documents.ts`) snapshots
+ * whatever is currently PERSISTED as its own "pre-restore" version — never the
+ * client's in-memory draft — so an edit still sitting in the autosave debounce
+ * window when Discard fires would otherwise never reach the server and be
+ * silently unrecoverable once the draft is reverted. The underlying
+ * save/restore commands are serialized by the shared operations queue
+ * (EC-225), so the un-awaited `save()` here still lands before `restore` reads
+ * the persisted document.
+ */
+export function flushDirtyDraft(input) {
+    if (input.dirty)
+        input.save();
+}
 //# sourceMappingURL=discard-draft.js.map

package/dist/components/cms/discard-draft.js.map

@@ -1 +1 @@
-{"version":3,"file":"discard-draft.js","sourceRoot":"","sources":["../../../src/components/cms/discard-draft.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAA;AAuBhE,MAAM,UAAU,kBAAkB,CAAC,KAWlC;IACC,IAAI,CAAC,KAAK,CAAC,UAAU,IAAI,CAAC,KAAK,CAAC,SAAS;QAAE,OAAO,QAAQ,CAAA;IAC1D,IAAI,KAAK,CAAC,YAAY;QAAE,OAAO,gBAAgB,CAAA;IAC/C,IAAI,KAAK,CAAC,iBAAiB,KAAK,SAAS;QAAE,OAAO,SAAS,CAAA;IAC3D,OAAO,sBAAsB,CAAC,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,iBAAiB,EAAE,KAAK,CAAC,KAAK,CAAC;QACnF,CAAC,CAAC,YAAY;QACd,CAAC,CAAC,OAAO,CAAA;AACb,CAAC","sourcesContent":["import { documentsSemanticEqual } from '@elytracms/core/content'\nimport type { CmsDocument, CollectionDef } from '@elytracms/core/cms-core'\n\n/**\n * EC-316 — the \"Discard changes\" header action's enablement, as one pure\n * decision. Discarding reverts the draft to exactly the published content (via\n * the EC-298 restore machinery), so it is offered iff there is a published\n * version to revert TO and the draft actually differs from it:\n *\n * - `hidden`        — the rail can't discard at all (no publish/versions\n *                     capability) or the document isn't published: there is no\n *                     published content to revert to, so no menu item.\n * - `view-read-only`— viewing the Published snapshot (EC-226): the draft isn't\n *                     the active view, so the item is disabled with a hint.\n * - `loading`       — the version history hasn't resolved yet; disabled.\n * - `up-to-date`    — the draft SEMANTICALLY equals the published snapshot\n *                     (`documentsSemanticEqual`, the SAME comparator the\n *                     Versions pane's publish gate uses, EC-298 — so the two\n *                     surfaces never contradict); nothing to discard, disabled.\n * - `ready`         — a published version exists and the draft differs: enabled.\n */\nexport type DiscardDraftStatus = 'hidden' | 'view-read-only' | 'loading' | 'up-to-date' | 'ready'\n\nexport function discardDraftStatus(input: {\n  /** The rail can publish AND has version history (both required to discard). */\n  canDiscard: boolean\n  /** The document IS published (version pointer set). */\n  published: boolean\n  /** The editor is viewing the read-only Published snapshot (EC-226). */\n  viewReadOnly: boolean\n  /** The pinned published version's snapshot; `undefined` while loading / none pinned. */\n  publishedSnapshot: CmsDocument | undefined\n  collection: CollectionDef\n  draft: CmsDocument\n}): DiscardDraftStatus {\n  if (!input.canDiscard || !input.published) return 'hidden'\n  if (input.viewReadOnly) return 'view-read-only'\n  if (input.publishedSnapshot === undefined) return 'loading'\n  return documentsSemanticEqual(input.collection, input.publishedSnapshot, input.draft)\n    ? 'up-to-date'\n    : 'ready'\n}\n"]}
+{"version":3,"file":"discard-draft.js","sourceRoot":"","sources":["../../../src/components/cms/discard-draft.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAA;AAuBhE,MAAM,UAAU,kBAAkB,CAAC,KAWlC;IACC,IAAI,CAAC,KAAK,CAAC,UAAU,IAAI,CAAC,KAAK,CAAC,SAAS;QAAE,OAAO,QAAQ,CAAA;IAC1D,IAAI,KAAK,CAAC,YAAY;QAAE,OAAO,gBAAgB,CAAA;IAC/C,IAAI,KAAK,CAAC,iBAAiB,KAAK,SAAS;QAAE,OAAO,SAAS,CAAA;IAC3D,OAAO,sBAAsB,CAAC,KAAK,CAAC,UAAU,EAAE,KAAK,CAAC,iBAAiB,EAAE,KAAK,CAAC,KAAK,CAAC;QACnF,CAAC,CAAC,YAAY;QACd,CAAC,CAAC,OAAO,CAAA;AACb,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,eAAe,CAAC,KAA2C;IACzE,IAAI,KAAK,CAAC,KAAK;QAAE,KAAK,CAAC,IAAI,EAAE,CAAA;AAC/B,CAAC","sourcesContent":["import { documentsSemanticEqual } from '@elytracms/core/content'\nimport type { CmsDocument, CollectionDef } from '@elytracms/core/cms-core'\n\n/**\n * EC-316 — the \"Discard changes\" header action's enablement, as one pure\n * decision. Discarding reverts the draft to exactly the published content (via\n * the EC-298 restore machinery), so it is offered iff there is a published\n * version to revert TO and the draft actually differs from it:\n *\n * - `hidden`        — the rail can't discard at all (no publish/versions\n *                     capability) or the document isn't published: there is no\n *                     published content to revert to, so no menu item.\n * - `view-read-only`— viewing the Published snapshot (EC-226): the draft isn't\n *                     the active view, so the item is disabled with a hint.\n * - `loading`       — the version history hasn't resolved yet; disabled.\n * - `up-to-date`    — the draft SEMANTICALLY equals the published snapshot\n *                     (`documentsSemanticEqual`, the SAME comparator the\n *                     Versions pane's publish gate uses, EC-298 — so the two\n *                     surfaces never contradict); nothing to discard, disabled.\n * - `ready`         — a published version exists and the draft differs: enabled.\n */\nexport type DiscardDraftStatus = 'hidden' | 'view-read-only' | 'loading' | 'up-to-date' | 'ready'\n\nexport function discardDraftStatus(input: {\n  /** The rail can publish AND has version history (both required to discard). */\n  canDiscard: boolean\n  /** The document IS published (version pointer set). */\n  published: boolean\n  /** The editor is viewing the read-only Published snapshot (EC-226). */\n  viewReadOnly: boolean\n  /** The pinned published version's snapshot; `undefined` while loading / none pinned. */\n  publishedSnapshot: CmsDocument | undefined\n  collection: CollectionDef\n  draft: CmsDocument\n}): DiscardDraftStatus {\n  if (!input.canDiscard || !input.published) return 'hidden'\n  if (input.viewReadOnly) return 'view-read-only'\n  if (input.publishedSnapshot === undefined) return 'loading'\n  return documentsSemanticEqual(input.collection, input.publishedSnapshot, input.draft)\n    ? 'up-to-date'\n    : 'ready'\n}\n\n/**\n * EC-325 — the flush-before-restore ordering \"Discard changes\" must follow,\n * mirroring the IDENTICAL `if (dirty) save()` step the Versions pane's\n * (`versions-pane.tsx`'s `handleRestore`) and the Compare view's\n * (`version-compare.tsx`'s `restore`) own restores already take before theirs.\n * `documents.restore` (`packages/core/src/operations/documents.ts`) snapshots\n * whatever is currently PERSISTED as its own \"pre-restore\" version — never the\n * client's in-memory draft — so an edit still sitting in the autosave debounce\n * window when Discard fires would otherwise never reach the server and be\n * silently unrecoverable once the draft is reverted. The underlying\n * save/restore commands are serialized by the shared operations queue\n * (EC-225), so the un-awaited `save()` here still lands before `restore` reads\n * the persisted document.\n */\nexport function flushDirtyDraft(input: { dirty: boolean; save: () => void }): void {\n  if (input.dirty) input.save()\n}\n"]}

package/dist/components/cms/document-editor-context.d.ts

@@ -60,11 +60,12 @@ export interface DocumentEditorContextValue {
     /** Leave compare mode, back to editing. */
     exitCompare: () => void;
 }
+declare const useDocumentEditor: () => DocumentEditorContextValue;
 export declare function DocumentEditorProvider({ value, children, }: {
     value: DocumentEditorContextValue;
     children: ReactNode;
 }): import("react").JSX.Element;
-export declare function useDocumentEditor(): DocumentEditorContextValue;
+export { useDocumentEditor };
 /**
  * The open document's editing context, or null when there is none (e.g. a
  * relation picker opened from a table cell rather than the detail editor). Lets a

package/dist/components/cms/document-editor-context.js

@@ -1,16 +1,11 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { createContext, useContext } from 'react';
-const DocumentEditorContext = createContext(null);
+import { useContext } from 'react';
+import { createRequiredContext } from '@elytracms/studio/lib/required-context';
+const { Context: DocumentEditorContext, useRequired: useDocumentEditor } = createRequiredContext('DocumentEditor');
 export function DocumentEditorProvider({ value, children, }) {
     return _jsx(DocumentEditorContext.Provider, { value: value, children: children });
 }
-export function useDocumentEditor() {
-    const value = useContext(DocumentEditorContext);
-    if (!value) {
-        throw new Error('useDocumentEditor must be used within a <DocumentEditorProvider>.');
-    }
-    return value;
-}
+export { useDocumentEditor };
 /**
  * The open document's editing context, or null when there is none (e.g. a
  * relation picker opened from a table cell rather than the detail editor). Lets a

package/dist/components/cms/document-editor-context.js.map

@@ -1 +1 @@
-{"version":3,"file":"document-editor-context.js","sourceRoot":"","sources":["../../../src/components/cms/document-editor-context.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAA;AAkEjD,MAAM,qBAAqB,GAAG,aAAa,CAAoC,IAAI,CAAC,CAAA;AAEpF,MAAM,UAAU,sBAAsB,CAAC,EACrC,KAAK,EACL,QAAQ,GAIT;IACC,OAAO,KAAC,qBAAqB,CAAC,QAAQ,IAAC,KAAK,EAAE,KAAK,YAAG,QAAQ,GAAkC,CAAA;AAClG,CAAC;AAED,MAAM,UAAU,iBAAiB;IAC/B,MAAM,KAAK,GAAG,UAAU,CAAC,qBAAqB,CAAC,CAAA;IAC/C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,mEAAmE,CAAC,CAAA;IACtF,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB;IACvC,OAAO,UAAU,CAAC,qBAAqB,CAAC,CAAA;AAC1C,CAAC","sourcesContent":["import { createContext, useContext } from 'react'\nimport type { ReactNode } from 'react'\nimport type { CmsDocument, CollectionDef, DocumentRef } from '@elytracms/core/cms-core'\n\n/**\n * EC-224 — the open document's editing context, provided by the detail editor\n * and consumed by document-level inspector panes (the `Versions` pane).\n *\n * It exists because the Versions pane is rendered in two places — directly in\n * the form view's sidebar, and inside the canvas view's own sidebar (deep in the\n * scoped `BuilderProvider` subtree). A context lets the pane reach the open\n * document's ref + live draft + actions from either mount point, without\n * threading props through the canvas field editor.\n */\n/**\n * EC-298 version-compare selection: which two snapshots the compare view diffs.\n * `base` is a recorded version number (the older side); `target` is either\n * another recorded version or the live working draft.\n */\nexport interface CompareState {\n  base: number\n  target: number | 'draft'\n}\n\nexport interface DocumentEditorContextValue {\n  /** The project being edited (undefined in fixture/playground sessions). */\n  projectId: string | undefined\n  collection: CollectionDef\n  docRef: DocumentRef\n  /** The editor's live (possibly unsaved) draft buffer. */\n  draft: CmsDocument\n  /** Does the draft buffer diverge from the saved document? */\n  dirty: boolean\n  /** Does the draft have error-severity validation issues (blocks publish)? */\n  hasErrors: boolean\n  /**\n   * Is the editor in the read-only Published view (EC-226)? Document-level panes\n   * must disable their mutating actions (publish/restore) while it is true.\n   */\n  viewReadOnly: boolean\n  /** Persist the current draft buffer (the editor's Save). */\n  save: () => void\n  /**\n   * Replace the editor's draft buffer — used after a version restore swaps the\n   * working draft for an older snapshot, so the open form/canvas reflect it.\n   */\n  replaceDraft: (doc: CmsDocument) => void\n  /**\n   * EC-298 — the open version comparison, or null when none. The Compare tab is a\n   * sticky content tab: this selection persists while the user tabs between the\n   * diff and the real fields, and is cleared only by closing the tab (its ✕).\n   */\n  compare: CompareState | null\n  /** Is the Compare tab the currently VISIBLE view? Drives the Versions pane's\n   *  base-picker mode — the pane navigates only while the diff is on screen. */\n  compareActive: boolean\n  /** Open (or refocus) the Compare tab with `base` vs the current draft. */\n  startCompare: (base: number) => void\n  /** Change which recorded version is the (older) base side. */\n  setCompareBase: (base: number) => void\n  /** Change what the base is compared against (a version, or the live draft). */\n  setCompareTarget: (target: number | 'draft') => void\n  /** Leave compare mode, back to editing. */\n  exitCompare: () => void\n}\n\nconst DocumentEditorContext = createContext<DocumentEditorContextValue | null>(null)\n\nexport function DocumentEditorProvider({\n  value,\n  children,\n}: {\n  value: DocumentEditorContextValue\n  children: ReactNode\n}) {\n  return <DocumentEditorContext.Provider value={value}>{children}</DocumentEditorContext.Provider>\n}\n\nexport function useDocumentEditor(): DocumentEditorContextValue {\n  const value = useContext(DocumentEditorContext)\n  if (!value) {\n    throw new Error('useDocumentEditor must be used within a <DocumentEditorProvider>.')\n  }\n  return value\n}\n\n/**\n * The open document's editing context, or null when there is none (e.g. a\n * relation picker opened from a table cell rather than the detail editor). Lets a\n * control opt into doc-aware behavior — like the EC-218 parent cycle guard —\n * without requiring the provider.\n */\nexport function useOptionalDocumentEditor(): DocumentEditorContextValue | null {\n  return useContext(DocumentEditorContext)\n}\n"]}
+{"version":3,"file":"document-editor-context.js","sourceRoot":"","sources":["../../../src/components/cms/document-editor-context.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,OAAO,CAAA;AAGlC,OAAO,EAAE,qBAAqB,EAAE,MAAM,wCAAwC,CAAA;AAgE9E,MAAM,EAAE,OAAO,EAAE,qBAAqB,EAAE,WAAW,EAAE,iBAAiB,EAAE,GACtE,qBAAqB,CAA6B,gBAAgB,CAAC,CAAA;AAErE,MAAM,UAAU,sBAAsB,CAAC,EACrC,KAAK,EACL,QAAQ,GAIT;IACC,OAAO,KAAC,qBAAqB,CAAC,QAAQ,IAAC,KAAK,EAAE,KAAK,YAAG,QAAQ,GAAkC,CAAA;AAClG,CAAC;AAED,OAAO,EAAE,iBAAiB,EAAE,CAAA;AAE5B;;;;;GAKG;AACH,MAAM,UAAU,yBAAyB;IACvC,OAAO,UAAU,CAAC,qBAAqB,CAAC,CAAA;AAC1C,CAAC","sourcesContent":["import { useContext } from 'react'\nimport type { ReactNode } from 'react'\nimport type { CmsDocument, CollectionDef, DocumentRef } from '@elytracms/core/cms-core'\nimport { createRequiredContext } from '@elytracms/studio/lib/required-context'\n\n/**\n * EC-224 — the open document's editing context, provided by the detail editor\n * and consumed by document-level inspector panes (the `Versions` pane).\n *\n * It exists because the Versions pane is rendered in two places — directly in\n * the form view's sidebar, and inside the canvas view's own sidebar (deep in the\n * scoped `BuilderProvider` subtree). A context lets the pane reach the open\n * document's ref + live draft + actions from either mount point, without\n * threading props through the canvas field editor.\n */\n/**\n * EC-298 version-compare selection: which two snapshots the compare view diffs.\n * `base` is a recorded version number (the older side); `target` is either\n * another recorded version or the live working draft.\n */\nexport interface CompareState {\n  base: number\n  target: number | 'draft'\n}\n\nexport interface DocumentEditorContextValue {\n  /** The project being edited (undefined in fixture/playground sessions). */\n  projectId: string | undefined\n  collection: CollectionDef\n  docRef: DocumentRef\n  /** The editor's live (possibly unsaved) draft buffer. */\n  draft: CmsDocument\n  /** Does the draft buffer diverge from the saved document? */\n  dirty: boolean\n  /** Does the draft have error-severity validation issues (blocks publish)? */\n  hasErrors: boolean\n  /**\n   * Is the editor in the read-only Published view (EC-226)? Document-level panes\n   * must disable their mutating actions (publish/restore) while it is true.\n   */\n  viewReadOnly: boolean\n  /** Persist the current draft buffer (the editor's Save). */\n  save: () => void\n  /**\n   * Replace the editor's draft buffer — used after a version restore swaps the\n   * working draft for an older snapshot, so the open form/canvas reflect it.\n   */\n  replaceDraft: (doc: CmsDocument) => void\n  /**\n   * EC-298 — the open version comparison, or null when none. The Compare tab is a\n   * sticky content tab: this selection persists while the user tabs between the\n   * diff and the real fields, and is cleared only by closing the tab (its ✕).\n   */\n  compare: CompareState | null\n  /** Is the Compare tab the currently VISIBLE view? Drives the Versions pane's\n   *  base-picker mode — the pane navigates only while the diff is on screen. */\n  compareActive: boolean\n  /** Open (or refocus) the Compare tab with `base` vs the current draft. */\n  startCompare: (base: number) => void\n  /** Change which recorded version is the (older) base side. */\n  setCompareBase: (base: number) => void\n  /** Change what the base is compared against (a version, or the live draft). */\n  setCompareTarget: (target: number | 'draft') => void\n  /** Leave compare mode, back to editing. */\n  exitCompare: () => void\n}\n\nconst { Context: DocumentEditorContext, useRequired: useDocumentEditor } =\n  createRequiredContext<DocumentEditorContextValue>('DocumentEditor')\n\nexport function DocumentEditorProvider({\n  value,\n  children,\n}: {\n  value: DocumentEditorContextValue\n  children: ReactNode\n}) {\n  return <DocumentEditorContext.Provider value={value}>{children}</DocumentEditorContext.Provider>\n}\n\nexport { useDocumentEditor }\n\n/**\n * The open document's editing context, or null when there is none (e.g. a\n * relation picker opened from a table cell rather than the detail editor). Lets a\n * control opt into doc-aware behavior — like the EC-218 parent cycle guard —\n * without requiring the provider.\n */\nexport function useOptionalDocumentEditor(): DocumentEditorContextValue | null {\n  return useContext(DocumentEditorContext)\n}\n"]}

package/dist/components/cms/document-ref-utils.d.ts

@@ -0,0 +1,33 @@
+import type { CmsDocument, DocumentRef } from '@elytracms/core/cms-core';
+/**
+ * By-ref document array helpers (EC-326) — a shared idiom over
+ * `@elytracms/core/cms-core`'s `documentRefEquals`, replacing ~12 hand-inlined
+ * `d.collection === x.collection && d.id === x.id` predicates across
+ * `cms-store.tsx`, `bulk-actions.ts`, and `cell-edit.ts`.
+ *
+ * Two real shapes exist over a document array and must stay distinct:
+ * - {@link replaceDoc}/{@link removeDoc} are pure, no-op-if-absent (an edit or
+ *   delete of a document that's already gone from the session is a silent
+ *   no-op, never an append).
+ * - {@link upsertDoc} is replace-or-append — `saveDocument` and
+ *   `importDocuments` rely on the append branch to create new documents; a
+ *   naive `replaceDoc` there would silently stop those flows from ever adding
+ *   a document to the session.
+ */
+/** Does `doc` identify the same document as `ref` (collection + id, EC-017)? */
+export declare function matchesRef(doc: DocumentRef, ref: DocumentRef): boolean;
+/**
+ * Replace the document matching `next`'s ref with `next`. A no-op (returns
+ * `docs` unchanged) if no document with that ref exists — pure map-replace,
+ * never appends.
+ */
+export declare function replaceDoc(docs: readonly CmsDocument[], next: CmsDocument): CmsDocument[];
+/** Remove the document identified by `ref`, if present. A no-op otherwise. */
+export declare function removeDoc(docs: readonly CmsDocument[], ref: DocumentRef): CmsDocument[];
+/**
+ * Replace the document matching `next`'s ref with `next`, or append it when
+ * no match exists (upsert) — the shape `saveDocument` and the accepted-batch
+ * fold of `importDocuments` need, so a create/import flow always lands the
+ * document even on a session with no prior entry for that ref.
+ */
+export declare function upsertDoc(docs: readonly CmsDocument[], next: CmsDocument): CmsDocument[];

package/dist/components/cms/document-ref-utils.js

@@ -0,0 +1,47 @@
+import { documentRefEquals } from '@elytracms/core/cms-core';
+/**
+ * By-ref document array helpers (EC-326) — a shared idiom over
+ * `@elytracms/core/cms-core`'s `documentRefEquals`, replacing ~12 hand-inlined
+ * `d.collection === x.collection && d.id === x.id` predicates across
+ * `cms-store.tsx`, `bulk-actions.ts`, and `cell-edit.ts`.
+ *
+ * Two real shapes exist over a document array and must stay distinct:
+ * - {@link replaceDoc}/{@link removeDoc} are pure, no-op-if-absent (an edit or
+ *   delete of a document that's already gone from the session is a silent
+ *   no-op, never an append).
+ * - {@link upsertDoc} is replace-or-append — `saveDocument` and
+ *   `importDocuments` rely on the append branch to create new documents; a
+ *   naive `replaceDoc` there would silently stop those flows from ever adding
+ *   a document to the session.
+ */
+/** Does `doc` identify the same document as `ref` (collection + id, EC-017)? */
+export function matchesRef(doc, ref) {
+    return documentRefEquals(doc, ref);
+}
+/**
+ * Replace the document matching `next`'s ref with `next`. A no-op (returns
+ * `docs` unchanged) if no document with that ref exists — pure map-replace,
+ * never appends.
+ */
+export function replaceDoc(docs, next) {
+    return docs.map((d) => (matchesRef(d, next) ? next : d));
+}
+/** Remove the document identified by `ref`, if present. A no-op otherwise. */
+export function removeDoc(docs, ref) {
+    return docs.filter((d) => !matchesRef(d, ref));
+}
+/**
+ * Replace the document matching `next`'s ref with `next`, or append it when
+ * no match exists (upsert) — the shape `saveDocument` and the accepted-batch
+ * fold of `importDocuments` need, so a create/import flow always lands the
+ * document even on a session with no prior entry for that ref.
+ */
+export function upsertDoc(docs, next) {
+    const i = docs.findIndex((d) => matchesRef(d, next));
+    if (i < 0)
+        return [...docs, next];
+    const out = [...docs];
+    out[i] = next;
+    return out;
+}
+//# sourceMappingURL=document-ref-utils.js.map

package/dist/components/cms/document-ref-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-ref-utils.js","sourceRoot":"","sources":["../../../src/components/cms/document-ref-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAG5D;;;;;;;;;;;;;;GAcG;AAEH,gFAAgF;AAChF,MAAM,UAAU,UAAU,CAAC,GAAgB,EAAE,GAAgB;IAC3D,OAAO,iBAAiB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;AACpC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,IAA4B,EAAE,IAAiB;IACxE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;AAC1D,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,SAAS,CAAC,IAA4B,EAAE,GAAgB;IACtE,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAA;AAChD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,IAA4B,EAAE,IAAiB;IACvE,MAAM,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAA;IACpD,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,CAAC,GAAG,IAAI,EAAE,IAAI,CAAC,CAAA;IACjC,MAAM,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,CAAA;IACrB,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAA;IACb,OAAO,GAAG,CAAA;AACZ,CAAC","sourcesContent":["import { documentRefEquals } from '@elytracms/core/cms-core'\nimport type { CmsDocument, DocumentRef } from '@elytracms/core/cms-core'\n\n/**\n * By-ref document array helpers (EC-326) — a shared idiom over\n * `@elytracms/core/cms-core`'s `documentRefEquals`, replacing ~12 hand-inlined\n * `d.collection === x.collection && d.id === x.id` predicates across\n * `cms-store.tsx`, `bulk-actions.ts`, and `cell-edit.ts`.\n *\n * Two real shapes exist over a document array and must stay distinct:\n * - {@link replaceDoc}/{@link removeDoc} are pure, no-op-if-absent (an edit or\n *   delete of a document that's already gone from the session is a silent\n *   no-op, never an append).\n * - {@link upsertDoc} is replace-or-append — `saveDocument` and\n *   `importDocuments` rely on the append branch to create new documents; a\n *   naive `replaceDoc` there would silently stop those flows from ever adding\n *   a document to the session.\n */\n\n/** Does `doc` identify the same document as `ref` (collection + id, EC-017)? */\nexport function matchesRef(doc: DocumentRef, ref: DocumentRef): boolean {\n  return documentRefEquals(doc, ref)\n}\n\n/**\n * Replace the document matching `next`'s ref with `next`. A no-op (returns\n * `docs` unchanged) if no document with that ref exists — pure map-replace,\n * never appends.\n */\nexport function replaceDoc(docs: readonly CmsDocument[], next: CmsDocument): CmsDocument[] {\n  return docs.map((d) => (matchesRef(d, next) ? next : d))\n}\n\n/** Remove the document identified by `ref`, if present. A no-op otherwise. */\nexport function removeDoc(docs: readonly CmsDocument[], ref: DocumentRef): CmsDocument[] {\n  return docs.filter((d) => !matchesRef(d, ref))\n}\n\n/**\n * Replace the document matching `next`'s ref with `next`, or append it when\n * no match exists (upsert) — the shape `saveDocument` and the accepted-batch\n * fold of `importDocuments` need, so a create/import flow always lands the\n * document even on a session with no prior entry for that ref.\n */\nexport function upsertDoc(docs: readonly CmsDocument[], next: CmsDocument): CmsDocument[] {\n  const i = docs.findIndex((d) => matchesRef(d, next))\n  if (i < 0) return [...docs, next]\n  const out = [...docs]\n  out[i] = next\n  return out\n}\n"]}

package/dist/components/cms/field-control.js

@@ -13,7 +13,7 @@ import { useOptionalAssets } from '../assets/assets-store';
 import { AssetThumb, FocalCropPreviews, FocalPointPicker, useAssetRecord } from '../assets/asset-thumb';
 import { newlyAddedAssetIds } from '../assets/focal-point';
 import { assetMetaFieldsOf, pruneMeta } from '../assets/asset-metadata';
-import { fieldLabel } from './cms-store';
+import { fieldLabel } from './cms-labels';
 import { useCollectionView } from '../collection-view/collection-view-context';
 import { useFieldDensity } from './field-density';
 import { useOptionalDocumentEditor } from './document-editor-context';