Editor cms adapter

Optional adapter between the editor primitive and a createcms collection client. Consumers with their own data layer can skip this entry.

import {
  useCmsDocument,
  useCmsFieldSources,
  useVariableSuggest,
  assetUrl,
} from '@createcms/react/editor/cms';

Usage

const doc = useCmsDocument({
  client: cmsClient.pages,
  rootId,
  branchId,
  message: () => commitMessageRef.current,
  templates: cmsClient.templates,
  collection: 'pages',
});

<pageEditor.Root
  key={doc.key}
  defaultValue={doc.tree}
  onSave={doc.save}
  onChange={doc.onChange}
>
  <Canvas.Root resolve={doc.resolve} />
</pageEditor.Root>;

Wire onChange={doc.onChange} so resolveTree sees unsaved edits. Pass key={doc.key} on Editor.Root so a reload resets the uncontrolled store.

Client shape

The hook duck-types four collection methods with the live proxy envelope: getBlockTree({ query }), getBranch({ query }), updateBlocks({ body }), and resolveTree({ body }). getBranch is required because getBlockTree does not return headCommitId.

The createcms client proxy mints a new object on every property access. Pass client once; the hook captures it in a ref on the first render.

Status

On conflict, call reload() to fetch the latest head or save({ force: true }) to overwrite without a head check.

Errors

error.fields is { blockId, key, message }[] for server-side TYPE_MISMATCH issues. Render it in editor chrome. Editor.FieldError still shows client-side validateField findings only.

Known error codes on CmsDocumentError.code:

Templates

When templates and collection are set, onAdd(blockType) calls getTemplateDefaults and returns the defaults object for merging into store.add / AddBlock.

Field sources

Registry controls for image, reference, link, and {{variable}} suggest call useCmsFieldSources(cmsClient) with the top-level createcms client (not a collection namespace such as cmsClient.pages).

const sources = useCmsFieldSources(cmsClient);
const suggest = useVariableSuggest(sources);

Pass client once; the hook captures it in a ref on the first render, same as useCmsDocument.

Return value

Proxy envelope

Live client calls use { query } / { body }, not flattened JSDoc examples:

sources.assets.list({ limit: 20, cursor });
cmsClient.media.listAssets({ query: { limit: 20, cursor } });

Cache

Per-hook, in-memory only: successful responses and in-flight promises are keyed by operation and arguments (stable JSON). Failed requests are not cached. assets.list and roots.list also populate id caches used by get.

assetUrl

Build the status-gated media URL for content and canvas (not the direct AssetListItem.url):

assetUrl(assetId, { format: 'webp', w: 800 });
// /api/cms/media/asset/<id>?format=webp&w=800

Labels

referenceLabel(collection, rootId, sources) and linkLabel(linkValue, sources) resolve display names from root properties (title, label, name, then slug, path, id). Internal link labels ignore fragment and query. Failed root lookups fall back to the raw id.

useVariableSuggest

Loads variables (paged, up to 1000 offset) and exposes a suggest object for Canvas.InlineText or form controls. Pattern: /\{\{(\w*)$/. getItems filters loaded keys by prefix; accept inserts {{key}}.

assets.useUpload() is a nested React hook: call it at component top level, not inside callbacks.

Types