@portabletext/editor 7.3.4 → 7.5.0

package/lib/_chunks-dts/behavior.types.action.d.ts

@@ -78,12 +78,12 @@ type IndexTuple = [number | '', number | ''];
  * - An IndexTuple (range selection)
  * @public
  */
-type PathSegment$1 = string | number | KeyedSegment | IndexTuple;
+type PathSegment = string | number | KeyedSegment | IndexTuple;
 /**
  * A path is an array of path segments that describes a location in a document.
  * @public
  */
-type Path = PathSegment$1[];
+type Path = PathSegment[];
 /**
  * A path to a block in the value.
  *
@@ -102,22 +102,6 @@ type AnnotationPath = Path;
  * @public
  */
 type ChildPath = Path;
-/**
- * A path segment identifies a position in the document tree.
- *
- * - `KeyedSegment` (`{_key: string}`) identifies a node by its key
- * - `string` identifies a child field name (e.g. 'children', 'rows', 'cells')
- * - `number` identifies a position in an array (used for empty container inserts
- *   and rendering indexed paths)
- * - `IndexTuple` (`[number | '', number | '']`) represents a range selection
- */
-type PathSegment = KeyedSegment | string | number | IndexTuple;
-/**
- * A `Path` is a list of segments that describe a node's exact position in
- * the document tree. Segments alternate between keyed node references and
- * field names: `[{_key: 'b1'}, 'children', {_key: 's1'}]`.
- */
-type Path$1 = PathSegment[];
 /**
  * @alpha
  *
@@ -142,7 +126,7 @@ type ContainerRenderProps = {
   children: ReactElement;
   focused: boolean;
   node: PortableTextObject;
-  path: Path$1;
+  path: Path;
   readOnly: boolean;
   selected: boolean;
   /**
@@ -176,7 +160,7 @@ type SpanRenderProps = {
   children: ReactElement;
   focused: boolean;
   node: PortableTextSpan;
-  path: Path$1;
+  path: Path;
   readOnly: boolean;
   selected: boolean;
   /**
@@ -203,7 +187,7 @@ type BlockObjectRenderProps = {
   children: ReactElement;
   focused: boolean;
   node: PortableTextObject;
-  path: Path$1;
+  path: Path;
   readOnly: boolean;
   selected: boolean;
   /**
@@ -230,7 +214,7 @@ type InlineObjectRenderProps = {
   children: ReactElement;
   focused: boolean;
   node: PortableTextObject;
-  path: Path$1;
+  path: Path;
   readOnly: boolean;
   selected: boolean;
   /**
@@ -324,7 +308,7 @@ type TextBlockRenderProps = {
   children: ReactElement;
   focused: boolean;
   node: PortableTextTextBlock;
-  path: Path$1;
+  path: Path;
   readOnly: boolean;
   selected: boolean;
   /**
@@ -437,7 +421,7 @@ declare function defineContainer<const TType$1 extends string>(config: {
     children: ReactElement;
     focused: boolean;
     node: ContainerNodeForType<TType$1>;
-    path: Path$1;
+    path: Path;
     readOnly: boolean;
     selected: boolean;
     renderDefault: (props: ContainerRenderProps) => ReactElement;
@@ -727,7 +711,7 @@ type TraversalSnapshot = {
     containers: Containers;
     value: Array<Node$1>;
   };
-  blockIndexMap: Map<string, number>;
+  blockIndexMap: ReadonlyMap<string, number>;
 };
 /**
  * Walk the editor value following `path` and return the
@@ -756,7 +740,7 @@ type TraversalSnapshot = {
  *
  * @alpha
  */
-declare function resolveContainerAt(containers: Containers, value: ReadonlyArray<Node$1>, path: Path$1): RegisteredContainer | RegisteredPositional | undefined;
+declare function resolveContainerAt(containers: Containers, value: ReadonlyArray<Node$1>, path: Path): RegisteredContainer | RegisteredPositional | undefined;
 /**
  * @public
  * @deprecated Use `useEditor()` instead
@@ -1456,7 +1440,7 @@ type TextDirection = 'forward' | 'backward';
  * only refer to `Text` nodes.
  */
 interface Point {
-  path: Path$1;
+  path: Path;
   offset: number;
 }
 /**
@@ -1468,48 +1452,69 @@ interface Range {
   anchor: Point;
   focus: Point;
 }
+/**
+ * Insert a node before or after the sibling at `path`.
+ *
+ * @beta
+ */
 type InsertOperation = {
   type: 'insert';
-  path: Path$1;
+  path: Path;
   node: Node$1;
   position: 'before' | 'after';
   inverse?: UnsetOperationData;
 };
+/**
+ * Insert `text` into the span at `path`, at `offset`.
+ *
+ * @beta
+ */
 type InsertTextOperation = {
   type: 'insert.text';
-  path: Path$1;
+  path: Path;
   offset: number;
   text: string;
 };
+/**
+ * Remove `text` from the span at `path`, starting at `offset`.
+ *
+ * @beta
+ */
 type RemoveTextOperation = {
   type: 'remove.text';
-  path: Path$1;
+  path: Path;
   offset: number;
   text: string;
 };
 /**
  * Data for a `set` inverse (no nested inverse field).
+ *
+ * @beta
  */
 type SetOperationData = {
   type: 'set';
-  path: Path$1;
+  path: Path;
   value: unknown;
 };
 /**
  * Data for an `insert` inverse (no nested inverse field).
+ *
+ * @beta
  */
 type InsertOperationData = {
   type: 'insert';
-  path: Path$1;
+  path: Path;
   node: Node$1;
   position: 'before' | 'after';
 };
 /**
  * Data for an `unset` inverse (no nested inverse field).
+ *
+ * @beta
  */
 type UnsetOperationData = {
   type: 'unset';
-  path: Path$1;
+  path: Path;
 };
 /**
  * Set a property on a node. The path is `[...nodePath, propertyName]`.
@@ -1517,10 +1522,12 @@ type UnsetOperationData = {
  * When `inverse` is provided, the operation can be undone. Remote operations
  * (applied via `withRemoteChanges`) skip the history plugin and do not need
  * inverse data.
+ *
+ * @beta
  */
 type SetOperation = {
   type: 'set';
-  path: Path$1;
+  path: Path;
   value: unknown;
   inverse?: SetOperationData | UnsetOperationData;
 };
@@ -1530,10 +1537,15 @@ type SetOperation = {
  * Property removal: path is `[...nodePath, propertyName]` (last segment is a string).
  * Node removal: path is `[...parentPath, arrayFieldName, {_key: nodeKey}]`
  * (last segment is a keyed segment pointing to the node to remove).
+ *
+ * The `inverse` of a node removal carries the removed node; the operation
+ * itself only carries its path.
+ *
+ * @beta
  */
 type UnsetOperation = {
   type: 'unset';
-  path: Path$1;
+  path: Path;
   inverse?: SetOperationData | InsertOperationData;
 };
 type SetSelectionOperation = {
@@ -1549,12 +1561,26 @@ type SetSelectionOperation = {
   properties: Range;
   newProperties: null;
 };
-type Operation = InsertOperation | SetOperation | UnsetOperation | SetSelectionOperation | InsertTextOperation | RemoveTextOperation;
+/**
+ * A low-level operation applied by the editor engine. Every change to the
+ * editor (local edits, remote patches, value sync, normalization fixes,
+ * undo/redo) is expressed as a sequence of these operations.
+ *
+ * The vocabulary is closed: the dot-named operations (`insert.text`,
+ * `remove.text`) are not namespaces that grow members.
+ *
+ * `inverse` is present when the engine needs the operation to be
+ * reversible (local structural operations) and carries what is needed to
+ * reverse it. Operations applied from remote patches do not carry it.
+ *
+ * @beta
+ */
+type EngineOperation = InsertOperation | SetOperation | UnsetOperation | SetSelectionOperation | InsertTextOperation | RemoveTextOperation;
 type DecoratedRange = Range & {
   rangeDecoration: RangeDecoration;
 };
 /**
- * The operation channel is the single place to observe every `Operation` the
+ * The operation channel is the single place to observe every `EngineOperation` the
  * engine applies.
  *
  * Guarantees:
@@ -1575,7 +1601,7 @@ type OperationEvent = {
    * populated and inserted nodes may be re-keyed — so `after` listeners
    * observe the final operation.
    */
-  operation: Operation;
+  operation: EngineOperation;
   /**
    * `editor.snapshot.context.value` captured at apply entry. Operations
    * replace the value array instead of mutating it, so this reference keeps
@@ -1613,19 +1639,19 @@ type OperationListener = (event: OperationEvent) => void;
  * `Point` or `Range`. This eliminates the need for developers to manage
  * converting between the different interfaces in their own code base.
  */
-type Location = Path$1 | Point | Range;
+type Location = Path | Point | Range;
 /**
  * `PathRef` objects keep a specific path in a document synced over time as new
  * operations are applied to the editor. You can access their `current` property
  * at any time for the up-to-date path value.
  */
 interface PathRef {
-  current: Path$1 | null;
+  current: Path | null;
   affinity: 'forward' | 'backward' | null;
-  unref(): Path$1 | null;
+  unref(): Path | null;
 }
 interface PathRefInterface {
-  transform: (ref: PathRef, op: Operation) => void;
+  transform: (ref: PathRef, op: EngineOperation) => void;
 }
 declare const PathRef: PathRefInterface;
 /**
@@ -1639,7 +1665,7 @@ interface PointRef {
   unref(): Point | null;
 }
 interface PointRefInterface {
-  transform: (ref: PointRef, op: Operation) => void;
+  transform: (ref: PointRef, op: EngineOperation) => void;
 }
 declare const PointRef: PointRefInterface;
 /**
@@ -1657,24 +1683,24 @@ interface RangeRef {
  * by plugins that wish to add their own helpers and implement new behaviors.
  */
 interface BaseEditor {
-  operations: Operation[];
+  operations: EngineOperation[];
   operationListeners: {
     before: Array<OperationListener>;
     after: Array<OperationListener>;
   };
-  dirtyPaths: Path$1[];
+  dirtyPaths: Path[];
   dirtyPathKeys: Set<string>;
   flushing: boolean;
   normalizing: boolean;
   pathRefs: Set<PathRef>;
   pointRefs: Set<PointRef>;
   rangeRefs: Set<RangeRef>;
-  apply: (operation: Operation) => void;
-  normalizeNode: (entry: [Editor$1 | Node$1, Path$1], options?: {
-    operation?: Operation;
+  apply: (operation: EngineOperation) => void;
+  normalizeNode: (entry: [Editor$1 | Node$1, Path], options?: {
+    operation?: EngineOperation;
   }) => void;
   onChange: (options?: {
-    operation?: Operation;
+    operation?: EngineOperation;
   }) => void;
   shouldNormalize: ({
     iteration,
@@ -1683,8 +1709,8 @@ interface BaseEditor {
   }: {
     iteration: number;
     initialDirtyPathsLength: number;
-    dirtyPaths: Path$1[];
-    operation?: Operation;
+    dirtyPaths: Path[];
+    operation?: EngineOperation;
   }) => boolean;
   select: (target: Location) => void;
   setSelection: (props: Partial<Range>) => void;
@@ -1697,7 +1723,7 @@ type StringDiff = {
 };
 type TextDiff = {
   id: number;
-  path: Path$1;
+  path: Path;
   diff: StringDiff;
 };
 /**
@@ -1736,7 +1762,7 @@ interface DOMEditor extends BaseEditor {
   composing: boolean;
   userSelection: RangeRef | null;
   onContextChange: ((options?: {
-    operation?: Operation;
+    operation?: EngineOperation;
   }) => void) | null;
   scheduleFlush: (() => void) | null;
   pendingDiffs: TextDiff[];
@@ -1824,7 +1850,7 @@ interface DOMEditorInterface {
 }
 declare const DOMEditor: DOMEditorInterface;
 type HistoryItem = {
-  operations: Operation[];
+  operations: EngineOperation[];
   timestamp: Date;
 };
 interface History {
@@ -1905,7 +1931,7 @@ type EditorContext = {
  */
 type EditorSnapshot = {
   context: EditorContext;
-  blockIndexMap: Map<string, number>;
+  blockIndexMap: ReadonlyMap<string, number>;
   /**
    * @beta
    * Subject to change
@@ -1955,6 +1981,39 @@ type Behavior<TBehaviorEventType extends '*' | `${BehaviorEventTypeNamespace}.*`
  *
  */
 declare function defineBehavior<TPayload extends Record<string, unknown>, TBehaviorEventType extends '*' | `${BehaviorEventTypeNamespace}.*` | BehaviorEvent['type'] = CustomBehaviorEvent['type'], TGuardResponse = true>(behavior: Behavior<TBehaviorEventType, TGuardResponse, ResolveBehaviorEvent<TBehaviorEventType, TPayload>>): Behavior;
+/**
+ * The document-changing operations emitted through
+ * `editor.on('operation', ...)`. Every change to the editor (local edits,
+ * remote patches, value sync, normalization fixes, undo/redo) is expressed
+ * as a sequence of these five operations.
+ *
+ * The vocabulary is closed: there are exactly five, listed explicitly so
+ * that a new engine operation never becomes public surface by default, and
+ * the dot-named ones (`insert.text`, `remove.text`) are not namespaces that
+ * grow members.
+ *
+ * Selection movements are not emitted on this stream; subscribe to the
+ * `selection` event instead.
+ *
+ * Operation objects are the engine's own, passed by reference: treat them
+ * as read-only and copy anything you retain beyond the listener call.
+ *
+ * Delivery order: normalization fix operations are delivered adjacent to
+ * the operation that triggered them, but whether a fix arrives before or
+ * after its trigger depends on how the trigger was applied (a fix
+ * re-enters the engine's apply, so an unbatched trigger delivers the fix
+ * first; batched applies deliver fixes after the batch). Do not assume
+ * delivery order equals application order under normalization: seed
+ * derived state from `editor.getSnapshot()` and recompute on change
+ * rather than replaying deltas blindly.
+ *
+ * `inverse`, when present, reflects what the engine itself needs to make
+ * the operation reversible. Its presence follows the engine's history
+ * policy and is not a stable per-operation contract.
+ *
+ * @beta
+ */
+type Operation = InsertOperation | InsertTextOperation | RemoveTextOperation | SetOperation | UnsetOperation;
 /**
  * @public
  */
@@ -1980,7 +2039,29 @@ type EditorEmittedEvent = {
    * @deprecated Will be removed in the next major version
    */
   type: 'loading';
-} | MutationEvent | PatchEvent | {
+} | MutationEvent | {
+  /**
+   * @beta
+   * Emitted synchronously for every document-changing operation the
+   * engine applies (`set.selection` is excluded; the `selection` event
+   * serves selection observers), including operations from initial
+   * value sync and normalization, unlike `patch` and `mutation`
+   * events, which are held back until the editor is dirty. Do not
+   * dispatch editor events from a listener; read current state via
+   * `editor.getSnapshot()`.
+   *
+   * The `operation` object is the engine's own, passed by reference:
+   * treat it as read-only and copy anything you retain. Normalization
+   * fix operations are delivered adjacent to the operation that
+   * triggered them, but not in a guaranteed order; see the
+   * {@link Operation} docs for the delivery-order contract. Subscribers
+   * attached after setup receive only subsequent operations: seed
+   * derived state from `editor.getSnapshot()` when subscribing, then
+   * apply deltas.
+   */
+  type: 'operation';
+  operation: Operation;
+} | PatchEvent | {
   type: 'read only';
 } | {
   type: 'ready';
@@ -2389,6 +2470,9 @@ declare const editorMachine: xstate31.StateMachine<{
   value: Array<PortableTextBlock> | undefined;
 } | {
   type: "loading";
+} | {
+  type: "operation";
+  operation: Operation;
 } | {
   type: "read only";
 } | {
@@ -3183,5 +3267,5 @@ type BehaviorActionSet<TBehaviorEvent, TGuardResponse> = (payload: {
   event: TBehaviorEvent;
   dom: EditorDom;
 }, guardResponse: TGuardResponse) => Array<BehaviorAction>;
-export { EditorSnapshot as $, SpanRenderProps as $t, PortableTextTextBlock$1 as A, PortableTextEditor as At, EditorSelector as B, RegisteredSpan as Bt, ListDefinition as C, RenderListItemFunction as Ct, PortableTextChild$1 as D, PortableTextEditable as Dt, PortableTextBlock$1 as E, ScrollSelectionIntoViewFunction as Et, BlockOffset as F, Containers as Ft, EditorConfig as G, ContainerRender as Gt, EditorProvider as H, BlockObjectRender as Ht, useEditor as I, RegisteredBlockObject as It, MutationEvent as J, InlineObjectRender as Jt, EditorEvent as K, ContainerRenderProps as Kt, defaultKeyGenerator as L, RegisteredContainer as Lt, StyleDefinition as M, TraversalSnapshot as Mt, StyleSchemaType$1 as N, Node$1 as Nt, PortableTextObject$1 as O, PortableTextEditableProps as Ot, defineSchema as P, EditorSchema as Pt, EditorContext as Q, SpanRender as Qt, usePortableTextEditorSelection as R, RegisteredInlineObject as Rt, InlineObjectSchemaType$1 as S, RenderEditableFunction as St, Patch$1 as T, RenderStyleFunction as Tt, EditorProviderProps as U, BlockObjectRenderProps as Ut, useEditorSelector as V, BlockObject as Vt, Editor as W, Container as Wt, defineBehavior as X, RegistrableNode as Xt, Behavior as Y, InlineObjectRenderProps as Yt, BehaviorGuard as Z, Span as Zt, BlockObjectSchemaType$1 as _, RangeDecorationOnMovedDetails as _t, forward as a, defineInlineObject as an, BlockRenderProps as at, FieldDefinition$1 as b, RenderChildFunction as bt, CustomBehaviorEvent as c, Path$1 as cn, EditorSelection as ct, SyntheticBehaviorEvent as d, ChildPath as dn, OnCopyFn as dt, TextBlock as en, AddedAnnotationPaths as et, PatchesEvent as f, KeyedSegment as fn, OnPasteFn as ft, BlockObjectDefinition as g, RangeDecoration as gt, BaseDefinition as h, PasteData as ht, execute as i, defineContainer as in, BlockListItemRenderProps as it, SchemaDefinition$1 as j, resolveContainerAt as jt, PortableTextSpan$1 as k, HotkeyOptions as kt, InsertPlacement as l, AnnotationPath as ln, EditorSelectionPoint as lt, AnnotationSchemaType$1 as m, OnPasteResultOrPromise as mt, BehaviorActionSet as n, TextBlockRenderProps as nn, BlockChildRenderProps as nt, raise as o, defineSpan as on, BlockStyleRenderProps as ot, AnnotationDefinition as p, Path as pn, OnPasteResult as pt, EditorEmittedEvent as q, InlineObject as qt, effect as r, defineBlockObject as rn, BlockDecoratorRenderProps as rt, BehaviorEvent as s, defineTextBlock as sn, EditableAPIDeleteOptions as st, BehaviorAction as t, TextBlockRender as tn, BlockAnnotationRenderProps as tt, NativeBehaviorEvent as u, BlockPath as un, InvalidValueResolution as ut, DecoratorDefinition as v, RenderAnnotationFunction as vt, ListSchemaType$1 as w, RenderPlaceholderFunction as wt, InlineObjectDefinition as x, RenderDecoratorFunction as xt, DecoratorSchemaType$1 as y, RenderBlockFunction as yt, usePortableTextEditor as z, RegisteredPositional as zt };
+export { EditorContext as $, SpanRender as $t, PortableTextTextBlock$1 as A, HotkeyOptions as At, EditorSelector as B, RegisteredPositional as Bt, ListDefinition as C, RenderEditableFunction as Ct, PortableTextChild$1 as D, ScrollSelectionIntoViewFunction as Dt, PortableTextBlock$1 as E, RenderStyleFunction as Et, BlockOffset as F, EditorSchema as Ft, EditorConfig as G, Container as Gt, EditorProvider as H, BlockObject as Ht, useEditor as I, Containers as It, MutationEvent as J, InlineObject as Jt, EditorEvent as K, ContainerRender as Kt, defaultKeyGenerator as L, RegisteredBlockObject as Lt, StyleDefinition as M, resolveContainerAt as Mt, StyleSchemaType$1 as N, TraversalSnapshot as Nt, PortableTextObject$1 as O, PortableTextEditable as Ot, defineSchema as P, Node$1 as Pt, BehaviorGuard as Q, Span as Qt, usePortableTextEditorSelection as R, RegisteredContainer as Rt, InlineObjectSchemaType$1 as S, RenderDecoratorFunction as St, Patch$1 as T, RenderPlaceholderFunction as Tt, EditorProviderProps as U, BlockObjectRender as Ut, useEditorSelector as V, RegisteredSpan as Vt, Editor as W, BlockObjectRenderProps as Wt, Behavior as X, InlineObjectRenderProps as Xt, Operation as Y, InlineObjectRender as Yt, defineBehavior as Z, RegistrableNode as Zt, BlockObjectSchemaType$1 as _, RangeDecoration as _t, forward as a, defineContainer as an, BlockListItemRenderProps as at, FieldDefinition$1 as b, RenderBlockFunction as bt, CustomBehaviorEvent as c, defineTextBlock as cn, EditableAPIDeleteOptions as ct, SyntheticBehaviorEvent as d, ChildPath as dn, InvalidValueResolution as dt, SpanRenderProps as en, EditorSnapshot as et, PatchesEvent as f, KeyedSegment as fn, OnCopyFn as ft, BlockObjectDefinition as g, PasteData as gt, BaseDefinition as h, OnPasteResultOrPromise as ht, execute as i, defineBlockObject as in, BlockDecoratorRenderProps as it, SchemaDefinition$1 as j, PortableTextEditor as jt, PortableTextSpan$1 as k, PortableTextEditableProps as kt, InsertPlacement as l, AnnotationPath as ln, EditorSelection as lt, AnnotationSchemaType$1 as m, OnPasteResult as mt, BehaviorActionSet as n, TextBlockRender as nn, BlockAnnotationRenderProps as nt, raise as o, defineInlineObject as on, BlockRenderProps as ot, AnnotationDefinition as p, Path as pn, OnPasteFn as pt, EditorEmittedEvent as q, ContainerRenderProps as qt, effect as r, TextBlockRenderProps as rn, BlockChildRenderProps as rt, BehaviorEvent as s, defineSpan as sn, BlockStyleRenderProps as st, BehaviorAction as t, TextBlock as tn, AddedAnnotationPaths as tt, NativeBehaviorEvent as u, BlockPath as un, EditorSelectionPoint as ut, DecoratorDefinition as v, RangeDecorationOnMovedDetails as vt, ListSchemaType$1 as w, RenderListItemFunction as wt, InlineObjectDefinition as x, RenderChildFunction as xt, DecoratorSchemaType$1 as y, RenderAnnotationFunction as yt, usePortableTextEditor as z, RegisteredInlineObject as zt };
 //# sourceMappingURL=behavior.types.action.d.ts.map