Skip to main content

@lexical/y

Classes​

YBinding​

Defined in: packages/lexical-y/src/internal/Binding.ts:422

Experimental

A Yjs 14 binding for one editor and one shared root.

Every container (the root, and every node stored as its own Y.Node) holds one sequence of text, child nodes and line markers; see the package README for the layout.

Warnings (read only states, recoveries, the opt-in self-check) go to the editor's onWarn, typed by their code (see YWarning and isYWarning), once a remote change has been applied in full: never from inside a Yjs observer or transaction. A handler that throws does not affect syncing.

Constructors​

Constructor​

new YBinding(editor, doc, options?): YBinding

Defined in: packages/lexical-y/src/internal/Binding.ts:629

Experimental

Parameters​
editor​

LexicalEditor

doc​

Doc

options?​

YBindingOptions = {}

Returns​

YBinding

Accessors​

doc​
Get Signature​

get doc(): Doc

Defined in: packages/lexical-y/src/internal/Binding.ts:602

Experimental

The shared document.

Returns​

Doc

editor​
Get Signature​

get editor(): LexicalEditor

Defined in: packages/lexical-y/src/internal/Binding.ts:597

Experimental

The bound editor.

Returns​

LexicalEditor

pins​
Get Signature​

get pins(): ReadonlyMap<string, { by?: readonly string[]; kind: StorageKind; }>

Defined in: packages/lexical-y/src/internal/Binding.ts:617

Experimental

Storage kinds the document records per node type (see the README).

Returns​

ReadonlyMap<string, { by?: readonly string[]; kind: StorageKind; }>

root​
Get Signature​

get root(): YNode

Defined in: packages/lexical-y/src/internal/Binding.ts:607

Experimental

The shared root this binding reads and writes.

Returns​

YNode

status​
Get Signature​

get status(): YBindingStatus

Defined in: packages/lexical-y/src/internal/Binding.ts:612

Experimental

See YBindingStatus; onStatus reports changes.

Returns​

YBindingStatus

undoManager​
Get Signature​

get undoManager(): UndoManager | null

Defined in: packages/lexical-y/src/internal/Binding.ts:625

Experimental

The collaborative undo manager; null when undo is disabled.

Returns​

UndoManager | null

Methods​

$resolveCursor()​

$resolveCursor(cursor): { anchor: PointType; focus: PointType; } | null

Defined in: packages/lexical-y/src/internal/Binding.ts:4180

Experimental

Resolve a cursor to Lexical points (call inside a read or update).

Parameters​
cursor​

YCursor

Returns​

{ anchor: PointType; focus: PointType; } | null

dispose()​

dispose(): void

Defined in: packages/lexical-y/src/internal/Binding.ts:852

Experimental

Disconnect from the document and the editor (start returns this).

Returns​

void

getCursor()​

getCursor(): YCursor | null

Defined in: packages/lexical-y/src/internal/Binding.ts:4018

Experimental

The local selection as relative positions (JSON), or null.

Returns​

YCursor | null

initialize()​

initialize(): void

Defined in: packages/lexical-y/src/internal/Binding.ts:891

Experimental

Call after the provider's first sync. An empty root is marked with this layout and gets the editor's current content, unless an older layout's root (root, root-v2) has content: such a document is read only, and must be converted instead (a binding with convert: true writes the layout root next to the old one). Anything else is read.

The initial content (including an update still pending, such as editor.update(seed) right before this call) is not part of the undo history. Into a pristine top-level root (one that has never held an item or an attribute), it is written once, under a client id derived from those exact bytes (see seedUpdate), applied to the document as they are and read back like any document, so that two clients initializing the same document with the same content at once write the same items (one copy), and one id never holds two payloads; anywhere else, with this client's own id.

Returns​

void

redo()​

redo(): boolean

Defined in: packages/lexical-y/src/internal/Binding.ts:3765

Experimental

Redo what undo undid; see undo.

Returns​

boolean

start()​

start(): () => void

Defined in: packages/lexical-y/src/internal/Binding.ts:649

Experimental

Start listening; read the document if it is already initialized.

Returns​

() => void

undo()​

undo(): boolean

Defined in: packages/lexical-y/src/internal/Binding.ts:3760

Experimental

Undo this client's last change in the document (collaborative undo). Returns whether there was one; false while the binding is not active.

Returns​

boolean

Interfaces​

YBindingOptions​

Defined in: packages/lexical-y/src/internal/Binding.ts:267

Experimental

Options of YBinding (and YCollabExtension).

Properties​

captureTimeout?​

optional captureTimeout?: number | null

Defined in: packages/lexical-y/src/internal/Binding.ts:271

Experimental

Undo capture timeout in ms (default 500); null disables undo.

clientIDRange?​

optional clientIDRange?: ClientIDRange

Defined in: packages/lexical-y/src/internal/Binding.ts:306

Experimental

The range of the document's client ids: 'uint53' (default, Yjs 14's ids, left as they are) or 'uint32' (kept in 32 bits, for servers on yrs before 0.28; see ClientIDRange).

convert?​

optional convert?: boolean

Defined in: packages/lexical-y/src/internal/Binding.ts:300

Experimental

Initialize even when an older layout's root has content: for a converter writing the layout root of an existing document.

onStatus?​

optional onStatus?: (status) => void

Defined in: packages/lexical-y/src/internal/Binding.ts:277

Experimental

Called when status changes, once the binding's work is done and Yjs is idle (like warnings, never inside a Yjs observer or transaction). Several changes in one such step report the last.

Parameters​
status​

YBindingStatus

Returns​

void

root?​

optional root?: YNode<any>

Defined in: packages/lexical-y/src/internal/Binding.ts:269

Experimental

The shared root to bind; defaults to doc.get('lexical-y').

selfCheck?​

optional selfCheck?: boolean

Defined in: packages/lexical-y/src/internal/Binding.ts:288

Experimental

Read every line a local write touched back from Yjs and compare it with the editor; mismatches are reported to the editor's onWarn (see SELF_CHECK_WARNING). Structural changes (and remote changes) also compare a fresh read of the whole container: every time for containers of up to 256 lines and nodes, and with probability 256 / size for bigger ones, so the expected cost of an edit stays bounded. Default: off. A debugging aid: turn it on in tests and development builds to catch binding bugs.

selfCheckSample?​

optional selfCheckSample?: number

Defined in: packages/lexical-y/src/internal/Binding.ts:295

Experimental

The fraction of changes the self-check samples (default 1): of local writes, and of remote changes, where a sampled check that finds the editor differing from the shared content also reads those containers again (see selfCheck).

YCollabConfig​

Defined in: packages/lexical-y/src/internal/YExtension.ts:38

Experimental

The configuration of YCollabExtension.

Properties​

captureTimeout​

captureTimeout: number | null

Defined in: packages/lexical-y/src/internal/YExtension.ts:50

Experimental

Undo capture timeout in ms; null disables collaborative undo.

clientIDRange​

clientIDRange: ClientIDRange

Defined in: packages/lexical-y/src/internal/YExtension.ts:52

Experimental

See YBindingOptions.clientIDRange (default 'uint53').

convert​

convert: boolean

Defined in: packages/lexical-y/src/internal/YExtension.ts:61

Experimental

See YBindingOptions.convert (default false).

doc​

doc: Doc | null

Defined in: packages/lexical-y/src/internal/YExtension.ts:40

Experimental

The shared document. Required.

root​

root: YNode<any> | null

Defined in: packages/lexical-y/src/internal/YExtension.ts:42

Experimental

The shared root; defaults to doc.get('lexical-y').

selfCheck​

selfCheck: boolean | null

Defined in: packages/lexical-y/src/internal/YExtension.ts:57

Experimental

See YBindingOptions.selfCheck; null keeps the default (off). Warnings go to the editor's onWarn.

selfCheckSample​

selfCheckSample: number | null

Defined in: packages/lexical-y/src/internal/YExtension.ts:59

Experimental

See YBindingOptions.selfCheckSample; null keeps the default (1).

synced​

synced: boolean

Defined in: packages/lexical-y/src/internal/YExtension.ts:48

Experimental

Initialize as soon as the extension registers: use it when the document is already synced (a headless writer, a converter, tests). Otherwise call binding.initialize() after the provider's first sync.

YCursor​

Defined in: packages/lexical-y/src/internal/Binding.ts:313

Experimental

A selection as Yjs relative positions, from YBinding#getCursor (for an awareness-based cursor UI).

Properties​

anchor​

anchor: unknown

Defined in: packages/lexical-y/src/internal/Binding.ts:314

Experimental

focus​

focus: unknown

Defined in: packages/lexical-y/src/internal/Binding.ts:315

Experimental

YRecoveredReadData​

Defined in: packages/lexical-y/src/internal/Warnings.ts:188

Experimental

data of a RECOVERED_READ_WARNING: a remote change ('remote-change') or a read of the binding's own ('reread') threw error, and the editor was rebuilt from the document.

Properties​

error​

readonly error: unknown

Defined in: packages/lexical-y/src/internal/Warnings.ts:190

Experimental

reason​

readonly reason: "remote-change" | "reread"

Defined in: packages/lexical-y/src/internal/Warnings.ts:189

Experimental

YRecoveredWriteData​

Defined in: packages/lexical-y/src/internal/Warnings.ts:197

Experimental

data of a RECOVERED_WRITE_WARNING: writing a local change threw error, and the document was rewritten from the editor.

Properties​

error​

readonly error: unknown

Defined in: packages/lexical-y/src/internal/Warnings.ts:199

Experimental

reason​

readonly reason: "local-change"

Defined in: packages/lexical-y/src/internal/Warnings.ts:198

Experimental

YSelfCheckData​

Defined in: packages/lexical-y/src/internal/Warnings.ts:178

Experimental

data of a SELF_CHECK_WARNING: the self-check found the editor and the document disagree after a local change ('local') or a remote one ('remote', read again in full).

Properties​

problems​

readonly problems: readonly string[]

Defined in: packages/lexical-y/src/internal/Warnings.ts:180

Experimental

reason​

readonly reason: "local" | "remote"

Defined in: packages/lexical-y/src/internal/Warnings.ts:179

Experimental

YStoredAs​

Defined in: packages/lexical-y/src/internal/Warnings.ts:115

Experimental

How the document stores a node type, or how a class would.

Properties​

by?​

readonly optional by?: readonly string[]

Defined in: packages/lexical-y/src/internal/Warnings.ts:118

Experimental

A group's or format's identity: the fields it merges by.

kind​

readonly kind: "format" | "nested" | "line" | "group"

Defined in: packages/lexical-y/src/internal/Warnings.ts:116

Experimental

YUnknownNodeTypesData​

Defined in: packages/lexical-y/src/internal/Warnings.ts:147

Experimental

data of an UNKNOWN_NODE_TYPES_WARNING (the binding is read only): types the editor does not register ('unregistered'), or slots the document holds that are not a block node ('malformed-slot': the slot's key, or the type of the inline node in it).

Properties​

reason​

readonly reason: "unregistered" | "malformed-slot"

Defined in: packages/lexical-y/src/internal/Warnings.ts:148

Experimental

types​

readonly types: readonly string[]

Defined in: packages/lexical-y/src/internal/Warnings.ts:149

Experimental

YUnsupportedConfigData​

Defined in: packages/lexical-y/src/internal/Warnings.ts:168

Experimental

data of an UNSUPPORTED_CONFIG_WARNING (nothing is written and the binding is read only): options ('<extension>.<option>') are set to a value the binding cannot write with.

Properties​

options​

readonly options: readonly string[]

Defined in: packages/lexical-y/src/internal/Warnings.ts:170

Experimental

reason​

readonly reason: "repair-transforms"

Defined in: packages/lexical-y/src/internal/Warnings.ts:169

Experimental

YUnsupportedSlotsData​

Defined in: packages/lexical-y/src/internal/Warnings.ts:158

Experimental

data of an UNSUPPORTED_SLOTS_WARNING (the change is not written and the binding is read only): types hold named slots on a node stored as a line, a format or a group ('stored-host'), or on the root ('root').

Properties​

reason​

readonly reason: "root" | "stored-host"

Defined in: packages/lexical-y/src/internal/Warnings.ts:159

Experimental

types​

readonly types: readonly string[]

Defined in: packages/lexical-y/src/internal/Warnings.ts:160

Experimental

YUnsyncedValueData​

Defined in: packages/lexical-y/src/internal/Warnings.ts:253

Experimental

data of an UNSYNCED_VALUE_WARNING: property ('<type>.<field>' or 'NodeState <key>') holds a value that is not plain JSON, so it is not synchronized.

Properties​

property​

readonly property: string

Defined in: packages/lexical-y/src/internal/Warnings.ts:255

Experimental

reason​

readonly reason: "not-json"

Defined in: packages/lexical-y/src/internal/Warnings.ts:254

Experimental

Type Aliases​

ClientIDRange​

ClientIDRange = "uint53" | "uint32"

Defined in: packages/lexical-y/src/internal/ClientID.ts:25

Experimental

The range of the client ids a document writes with.

  • 'uint53': Yjs 14's default (random 53-bit ids).
  • 'uint32': ids that fit in 32 bits, for servers that read client ids as 32-bit numbers (yrs before 0.28, e.g. y-crdt relays on 0.23): with a 53-bit id, such a server stores the author's content under a truncated id, and the author receives its own content back as another client's on reconnect, duplicating the document.

StorageKind​

StorageKind = "line" | "format" | "group" | "nested"

Defined in: packages/lexical-y/src/internal/Schema.ts:268

Experimental

How @lexical/y stores an element type; see describeStorage.

YBindingStatus​

YBindingStatus = "pending" | "active" | "readonly"

Defined in: packages/lexical-y/src/internal/Binding.ts:254

Experimental

The state of a YBinding.

YNestedFallbackData​

YNestedFallbackData = { method: string; reason: "merge-override"; type: string; } | { properties: readonly string[]; reason: "undeclared-properties"; type: string; } | { reason: Exclude<YNestedFallbackReason, "merge-override" | "undeclared-properties">; type: string; }

Defined in: packages/lexical-y/src/internal/Warnings.ts:229

Experimental

data of a NESTED_FALLBACK_WARNING.

YNestedFallbackReason​

YNestedFallbackReason = "merge-override" | "inline-slots" | "inline-incomplete-schema" | "type-name" | "merge-incomplete-schema" | "merge-slots" | "group-children" | "group-state-merge" | "group-incomplete-schema" | "undeclared-properties"

Defined in: packages/lexical-y/src/internal/Warnings.ts:206

Experimental

Why a class type whose declarations make it a line, a format or a group is stored as a nested node.

YStorageMismatchData​

YStorageMismatchData = { found: unknown; key: string; reason: "malformed"; type: string; } | { declared: YStoredAs; reason: "declaration-changed"; stored: YStoredAs; type: string; }

Defined in: packages/lexical-y/src/internal/Warnings.ts:125

Experimental

data of a STORAGE_MISMATCH_WARNING (the binding is read only), one per node type.

Union Members​

Type Literal​

{ found: unknown; key: string; reason: "malformed"; type: string; }

The record at key for type is not a storage record.

Type Literal​

{ declared: YStoredAs; reason: "declaration-changed"; stored: YStoredAs; type: string; }

The class of type cannot be stored as the document stores it.

YUnsupportedLayoutData​

YUnsupportedLayoutData = { found: number; reason: "newer"; supported: number; } | { found: unknown; key: string; reason: "malformed"; supported: number; } | { reason: "missing" | "removed"; supported: number; } | { reason: "legacy-roots"; roots: readonly string[]; supported: number; }

Defined in: packages/lexical-y/src/internal/Warnings.ts:88

Experimental

data of an UNSUPPORTED_LAYOUT_WARNING (the binding is read only). supported: the newest layout this version reads (it reads 1 to supported).

Union Members​

Type Literal​

{ found: number; reason: "newer"; supported: number; }

The layout record names a newer layout, found.

Type Literal​

{ found: unknown; key: string; reason: "malformed"; supported: number; }

The record at key is not a layout record; found is its value.

Type Literal​

{ reason: "missing" | "removed"; supported: number; }

The root has content but no layout record ('missing'), or the record was removed while the binding was writing ('removed').

Type Literal​

{ reason: "legacy-roots"; roots: readonly string[]; supported: number; }

Older layouts' roots, roots, hold content.

YWarning​

YWarning = { [C in YWarningCode]: LexicalWarning & { code: C; data: YWarningData<C> } }[YWarningCode]

Defined in: packages/lexical-y/src/internal/Warnings.ts:280

Experimental

A warning the binding passes to the editor's onWarn: a LexicalWarning whose code decides the type of its data (narrow it with isYWarning, then switch over code, and over data.reason).

YWarningCode​

YWarningCode = typeof UNSUPPORTED_LAYOUT_WARNING | typeof UNKNOWN_NODE_TYPES_WARNING | typeof STORAGE_MISMATCH_WARNING | typeof SELF_CHECK_WARNING | typeof RECOVERED_READ_WARNING | typeof RECOVERED_WRITE_WARNING | typeof NESTED_FALLBACK_WARNING | typeof UNSYNCED_VALUE_WARNING | typeof UNSUPPORTED_SLOTS_WARNING | typeof UNSUPPORTED_CONFIG_WARNING

Defined in: packages/lexical-y/src/internal/Warnings.ts:71

Experimental

The codes of the LexicalWarnings the binding passes to the editor's onWarn. Codes are public API: a code is never renamed, and never reused for another condition; new codes may be added in any release.

YWarningData​

YWarningData<C> = YWarningDataByCode[C]

Defined in: packages/lexical-y/src/internal/Warnings.ts:273

Experimental

The data of the warnings with code C.

Type Parameters​

C​

C extends YWarningCode

Variables​

DEFAULT_ROOT_NAME​

const DEFAULT_ROOT_NAME: "lexical-y" = 'lexical-y'

Defined in: packages/lexical-y/src/internal/constants.ts:17

Experimental

The default name of the shared root, which @lexical/yjs clients never write to (they use root and root-v2).

LAYOUT_VERSION​

const LAYOUT_VERSION: 2 = 2

Defined in: packages/lexical-y/src/internal/constants.ts:35

Experimental

The newest layout version this binding reads and writes. A new document records version 1; the first member entry of a set-valued NodeState written into a document also records 2 (clients that only read version 1 then open it read only instead of missing the members).

NESTED_FALLBACK_WARNING​

const NESTED_FALLBACK_WARNING: "@lexical/y/nested-fallback" = '@lexical/y/nested-fallback'

Defined in: packages/lexical-y/src/internal/Warnings.ts:49

Experimental

A class whose declarations make it a line, a format or a group is stored as a nested node. Once per class and reason. data: YNestedFallbackData.

RECOVERED_READ_WARNING​

const RECOVERED_READ_WARNING: "@lexical/y/recovered-read" = '@lexical/y/recovered-read'

Defined in: packages/lexical-y/src/internal/Warnings.ts:38

Experimental

A change could not be read: the editor was rebuilt from the document. data: YRecoveredReadData.

RECOVERED_WRITE_WARNING​

const RECOVERED_WRITE_WARNING: "@lexical/y/recovered-write" = '@lexical/y/recovered-write'

Defined in: packages/lexical-y/src/internal/Warnings.ts:43

Experimental

A local change could not be written: the document was rewritten from the editor. data: YRecoveredWriteData.

SELF_CHECK_WARNING​

const SELF_CHECK_WARNING: "@lexical/y/self-check" = '@lexical/y/self-check'

Defined in: packages/lexical-y/src/internal/Warnings.ts:33

Experimental

The self-check (selfCheck, off by default) found the editor and the document disagree. data: YSelfCheckData.

STORAGE_MISMATCH_WARNING​

const STORAGE_MISMATCH_WARNING: "@lexical/y/storage-mismatch" = '@lexical/y/storage-mismatch'

Defined in: packages/lexical-y/src/internal/Warnings.ts:28

Experimental

The document stores a node type in a way its class cannot be stored: read only. data: YStorageMismatchData.

UNKNOWN_NODE_TYPES_WARNING​

const UNKNOWN_NODE_TYPES_WARNING: "@lexical/y/unknown-node-types" = '@lexical/y/unknown-node-types'

Defined in: packages/lexical-y/src/internal/Warnings.ts:23

Experimental

The document has node types the editor cannot build: read only. data: YUnknownNodeTypesData.

UNSUPPORTED_CONFIG_WARNING​

const UNSUPPORTED_CONFIG_WARNING: "@lexical/y/unsupported-config" = '@lexical/y/unsupported-config'

Defined in: packages/lexical-y/src/internal/Warnings.ts:64

Experimental

The editor is configured in a way the binding cannot write with: nothing is written, read only. data: YUnsupportedConfigData.

UNSUPPORTED_LAYOUT_WARNING​

const UNSUPPORTED_LAYOUT_WARNING: "@lexical/y/unsupported-layout" = '@lexical/y/unsupported-layout'

Defined in: packages/lexical-y/src/internal/Warnings.ts:18

Experimental

The document's layout is one this version cannot read or write: read only. data: YUnsupportedLayoutData.

UNSUPPORTED_SLOTS_WARNING​

const UNSUPPORTED_SLOTS_WARNING: "@lexical/y/unsupported-slots" = '@lexical/y/unsupported-slots'

Defined in: packages/lexical-y/src/internal/Warnings.ts:59

Experimental

A node holds named slots where the document cannot store them: not written, read only. data: YUnsupportedSlotsData.

UNSYNCED_VALUE_WARNING​

const UNSYNCED_VALUE_WARNING: "@lexical/y/unsynced-value" = '@lexical/y/unsynced-value'

Defined in: packages/lexical-y/src/internal/Warnings.ts:54

Experimental

A node property or NodeState value is not plain JSON, so it is not synchronized. Once per property. data: YUnsyncedValueData.

YCollabExtension​

const YCollabExtension: LexicalExtension<YCollabConfig, "@lexical/y/Collab", { binding: YBinding; status: ReadonlySignal<YBindingStatus>; }, unknown>

Defined in: packages/lexical-y/src/internal/YExtension.ts:71

Experimental

Binds the editor to a Yjs 14 document with the block-marker layout, and provides collaborative undo (UNDO_COMMAND / REDO_COMMAND, CAN_UNDO_COMMAND / CAN_REDO_COMMAND). Its output has the binding and a status signal ('pending' until the layout record is read, then 'active' or 'readonly'). It conflicts with the history extensions.

Functions​

describeStorage()​

describeStorage(editor, binding?): Record<string, StorageKind | "text">

Defined in: packages/lexical-y/src/internal/Describe.ts:30

Experimental

How @lexical/y stores each node type: 'line', 'format', 'group' or 'nested' for elements (derived from the classes' $config() declarations, or the kind a document recorded when binding is given), 'text' for text and line breaks, 'nested' for decorators. The root is left out.

Parameters​

editor​

LexicalEditor

binding?​
pins​

ReadonlyMap<string, { kind: StorageKind; }>

Returns​

Record<string, StorageKind | "text">

isYWarning()​

isYWarning(error): error is YWarning

Defined in: packages/lexical-y/src/internal/Warnings.ts:304

Experimental

Whether error (what the editor's onWarn receives) is a warning of the binding's, typed by its code.

Parameters​

error​

unknown

Returns​

error is YWarning