@syncropel/editor

The interactive authoring surface for Syncropel — the authoring-side complement to @syncropel/renderer. Where the renderer reads (projections → UI), the editor writes (a document → records).

A document is text interleaved with typed pills. Each pill carries the shape { kind, fields }; the document serializes losslessly to EmitSpec[] and the host emits it as records — the kind and field values are data, not branches, so there is no per-type code.

Layering

@syncropel/projections   the surface-agnostic authoring vocabulary (EmitSpec, the
                         node types, the reference grammar) — shared by every surface
        │
        ▼
@syncropel/editor        the web (React + ProseMirror) renderer of that vocabulary —
                         this package. It owns its ProseMirror engine; React is a peer.

Other authoring surfaces are sibling renderers of the same @syncropel/projections grammar — they consume the shared vocabulary rather than forking this package.

Install

npm install @syncropel/editor react react-dom

react and react-dom (>= 18) are peer dependencies. Import the stylesheet once:

import '@syncropel/editor/editor.css';

Usage

import { usePillEditor, pillToEmitSpec } from '@syncropel/editor';
import '@syncropel/editor/editor.css';

function Composer() {
  const editor = usePillEditor({
    onChange: ({ pills, text }) => {
      // pills serialize to EmitSpec[] — the host emits them with its own client
      const specs = pills.map(pillToEmitSpec);
      void specs;
      void text;
    },
  });
  return <div ref={editor.mountRef} />;
}

The editor is headless: the host attaches mountRef, inserts pills via the returned API, and emits the serialized pills itself through its own Syncropel client and mutation lifecycle. The editor never owns the connection.

API surface

• usePillEditor(options) — the React hook. Manages the ProseMirror EditorView lifecycle and serializes the document to { pills, text } on every change.
• pillToEmitSpec(pill) — the generic serializer: { kind, fields } → EmitSpec.
• schema, PillView, docToPills, docToText, docToMessage — the lower-level ProseMirror primitives.
• DEMO_KIND_REGISTRY, setKindRegistry, getKindRegistry, buildRegistry — the kind registry that drives the picker and the typed-pill templates. A deployment supplies its own registry (built from an instance's advertised body kinds via buildRegistry) with setKindRegistry; the bundled demo registry is the fallback.
• createSuggestPlugin, setNodeSource, setCommandSource, TRIGGERS — the suggestion engine for the @ / [[ / # / / triggers; a host injects live data sources for threads and commands.
• proposeStructure — turns a free-form note into a set of typed fields.
• validateField — calm, non-blocking field validation for param hints.

License

Apache-2.0 © Syncropic, Inc.