@portabletext/editor 7.10.19 → 7.12.0

package/lib/{behavior.types.action-CYtiRDck.d.ts → behavior.types.action-DH6ujvaH.d.ts}

@@ -1,5 +1,5 @@
 import React$1, { BaseSyntheticEvent, ClipboardEvent as ClipboardEvent$1, FocusEvent, JSX, PropsWithChildren, ReactElement, RefObject, TextareaHTMLAttributes } from "react";
-import { AnnotationDefinition, AnnotationSchemaType, AnnotationSchemaType as AnnotationSchemaType$1, BaseDefinition, BlockObjectDefinition, BlockObjectSchemaType, BlockObjectSchemaType as BlockObjectSchemaType$1, DecoratorDefinition, DecoratorSchemaType, DecoratorSchemaType as DecoratorSchemaType$1, FieldDefinition, FieldDefinition as FieldDefinition$1, InlineObjectDefinition, InlineObjectSchemaType, InlineObjectSchemaType as InlineObjectSchemaType$1, ListDefinition, ListSchemaType, ListSchemaType as ListSchemaType$1, OfDefinition, PortableTextBlock, PortableTextBlock as PortableTextBlock$1, PortableTextChild, PortableTextChild as PortableTextChild$1, PortableTextObject, PortableTextObject as PortableTextObject$1, PortableTextSpan, PortableTextSpan as PortableTextSpan$1, PortableTextTextBlock, PortableTextTextBlock as PortableTextTextBlock$1, Schema, SchemaDefinition, SchemaDefinition as SchemaDefinition$1, StyleDefinition, StyleSchemaType, StyleSchemaType as StyleSchemaType$1, TypedObject, defineSchema } from "@portabletext/schema";
+import { AnnotationDefinition, AnnotationSchemaType, AnnotationSchemaType as AnnotationSchemaType$1, BaseDefinition, BlockObjectDefinition, BlockObjectSchemaType, BlockObjectSchemaType as BlockObjectSchemaType$1, DecoratorDefinition, DecoratorSchemaType, DecoratorSchemaType as DecoratorSchemaType$1, FieldDefinition, FieldDefinition as FieldDefinition$1, InlineObjectDefinition, InlineObjectSchemaType, InlineObjectSchemaType as InlineObjectSchemaType$1, ListDefinition, ListSchemaType, ListSchemaType as ListSchemaType$1, OfDefinition, OfDefinition as OfDefinition$1, PortableTextBlock, PortableTextBlock as PortableTextBlock$1, PortableTextChild, PortableTextChild as PortableTextChild$1, PortableTextObject, PortableTextObject as PortableTextObject$1, PortableTextSpan, PortableTextSpan as PortableTextSpan$1, PortableTextTextBlock, PortableTextTextBlock as PortableTextTextBlock$1, Schema, SchemaDefinition, SchemaDefinition as SchemaDefinition$1, StyleDefinition, StyleSchemaType, StyleSchemaType as StyleSchemaType$1, TypedObject, defineSchema } from "@portabletext/schema";
 import { ActorRefFrom } from "xstate";
 import { Patch, Patch as Patch$1 } from "@portabletext/patches";
 type MIMEType = `${string}/${string}`;
@@ -94,15 +94,7 @@ type AnnotationPath = Path;
  */
 type ChildPath = Path;
 /**
- * @alpha
- *
- * Narrow the container node type by the registered `_type`. Containers
- * always render portable text objects: `'span'` is always a leaf and
- * `'block'` is always a text block; both are excluded.
- */
-type ContainerNodeForType<TType extends string> = TType extends 'span' | 'block' ? never : PortableTextObject;
-/**
- * @alpha
+ * @public
  *
  * A container's render function receives a node and renders an element
  * that wraps its editable children. The render is positional: it fires for
@@ -125,7 +117,7 @@ type ContainerRenderProps = {
    * inside a custom render to fall back to or wrap the default:
    *
    * ```ts
-   * render: ({renderDefault, ...rest}) => renderDefault(rest)
+   * render: (props) => props.renderDefault(props)
    * ```
    *
    * The default is the engine's minimal wrapper. It does not chain
@@ -136,15 +128,18 @@ type ContainerRenderProps = {
   renderDefault: (props: ContainerRenderProps) => ReactElement;
 };
 /**
- * @alpha
+ * @public
  */
 type ContainerRender = (props: ContainerRenderProps) => ReactElement;
 /**
- * @alpha
+ * @public
  *
  * A span's render function. Receives a portable text span node and
  * wraps it. `children` carries the styled text already decorated by
- * `renderDecorator`/`renderAnnotation`/range decorations.
+ * the decorator/annotation renders (registered via `defineDecorator`/
+ * `defineAnnotation`, or the legacy `renderDecorator`/`renderAnnotation`
+ * props). Range decorations wrap this render's output from the
+ * outside, so they are not part of `children`.
  */
 type SpanRenderProps = {
   attributes: Record<string, unknown>;
@@ -161,11 +156,88 @@ type SpanRenderProps = {
   renderDefault: (props: SpanRenderProps) => ReactElement;
 };
 /**
- * @alpha
+ * @public
  */
 type SpanRender = (props: SpanRenderProps) => ReactElement;
 /**
- * @alpha
+ * @public
+ *
+ * A decorator's render function. Receives the decorator name and
+ * wraps the styled text it applies to. Range and selection decorations
+ * can split one span into several leaves, so this fires once per
+ * decorator on each leaf, not once per span, nested in the span's
+ * `marks` order alongside any decorators still rendered by the legacy
+ * `renderDecorator` prop.
+ *
+ * The render is a plain function call, not a component: do not call
+ * hooks in it. When you need hooks, return an element of your own
+ * component: `render: (props) => <MyDecorator {...props} />`.
+ */
+type DecoratorRenderProps = {
+  children: ReactElement;
+  /**
+   * The decorator name, e.g. `'strong'`. A `'*'` render
+   * discriminates on this.
+   */
+  decorator: string;
+  focused: boolean;
+  /**
+   * Path of the span carrying the decorator.
+   */
+  path: Path;
+  readOnly: boolean;
+  selected: boolean;
+  /**
+   * Render this position with the engine's default wrapper.
+   * See {@link ContainerRenderProps.renderDefault}. The default is
+   * identity: the engine applies no decorator markup of its own.
+   */
+  renderDefault: (props: DecoratorRenderProps) => ReactElement;
+};
+/**
+ * @public
+ */
+type DecoratorRender = (props: DecoratorRenderProps) => ReactElement;
+/**
+ * @public
+ *
+ * An annotation's render function. Receives the annotation's `markDef`
+ * object and wraps the styled text it applies to. The engine anchors
+ * the text in a `<span>` outside this render regardless of whether a
+ * render is registered, kept for structural parity with the legacy
+ * `renderAnnotation` path (which hands that anchor to consumers as
+ * `editorElementRef`); this render's job is the styling wrapper only.
+ *
+ * The render is a plain function call, not a component: do not call
+ * hooks in it. When you need hooks, return an element of your own
+ * component: `render: (props) => <MyAnnotation {...props} />`.
+ */
+type AnnotationRenderProps = {
+  /**
+   * The annotation's `markDef` object: `{_key, _type, ...fields}`.
+   * Named `annotation`, not `node`, because `path` addresses the span
+   * leaf carrying the annotation; the markDef itself lives in the block's
+   * `markDefs` array.
+   */
+  annotation: PortableTextObject;
+  children: ReactElement;
+  focused: boolean;
+  path: Path;
+  readOnly: boolean;
+  selected: boolean;
+  /**
+   * Render this position with the engine's default wrapper.
+   * See {@link ContainerRenderProps.renderDefault}. The default is
+   * identity: the engine applies no annotation markup of its own.
+   */
+  renderDefault: (props: AnnotationRenderProps) => ReactElement;
+};
+/**
+ * @public
+ */
+type AnnotationRender = (props: AnnotationRenderProps) => ReactElement;
+/**
+ * @public
  *
  * A block object's render function. Receives a non-editable block-level
  * portable text object. `children` carries an engine-emitted void
@@ -188,11 +260,11 @@ type BlockObjectRenderProps = {
   renderDefault: (props: BlockObjectRenderProps) => ReactElement;
 };
 /**
- * @alpha
+ * @public
  */
 type BlockObjectRender = (props: BlockObjectRenderProps) => ReactElement;
 /**
- * @alpha
+ * @public
  *
  * An inline object's render function. Receives a non-editable inline
  * portable text object. `children` carries an engine-emitted void
@@ -215,11 +287,11 @@ type InlineObjectRenderProps = {
   renderDefault: (props: InlineObjectRenderProps) => ReactElement;
 };
 /**
- * @alpha
+ * @public
  */
 type InlineObjectRender = (props: InlineObjectRenderProps) => ReactElement;
 /**
- * @alpha
+ * @public
  *
  * A container registration. Identifies a block object `_type` whose value
  * holds editable children in `arrayField`. The optional `of` array carries
@@ -250,7 +322,7 @@ type Container = {
   of?: ReadonlyArray<Container | TextBlock | BlockObject>;
 };
 /**
- * @alpha
+ * @public
  *
  * A text block registration. The text block `_type` is `'block'` at the
  * top level. Positional overrides nested in a container's `of` array can
@@ -282,11 +354,16 @@ type TextBlock = {
    * Inline-content positional overrides. A `Span` or `InlineObject`
    * placed here scopes the inline render to this text block (or any
    * text block of this `type` if registered at the top level).
+   * `Decorator` and `Annotation` entries scope those renders the
+   * same way: the decorator or annotation renders through this entry
+   * inside the text block, and through the global registration (or
+   * the legacy `renderDecorator`/`renderAnnotation` prop) everywhere
+   * else.
    */
-  of?: ReadonlyArray<Span | InlineObject>;
+  of?: ReadonlyArray<Span | InlineObject | Decorator | Annotation>;
 };
 /**
- * @alpha
+ * @public
  *
  * Text block render function. `children` carries the rendered spans -
  * `renderDecorator`, `renderAnnotation`, `renderPlaceholder`, and range
@@ -309,11 +386,11 @@ type TextBlockRenderProps = {
   renderDefault: (props: TextBlockRenderProps) => ReactElement;
 };
 /**
- * @alpha
+ * @public
  */
 type TextBlockRender = (props: TextBlockRenderProps) => ReactElement;
 /**
- * @alpha
+ * @public
  *
  * A span registration. The span `_type` is `'span'` at the top level.
  * Positional overrides nested in a container's `of` array can register
@@ -332,7 +409,44 @@ type Span = {
   render?: SpanRender;
 };
 /**
- * @alpha
+ * @public
+ *
+ * A decorator registration. `type` is a decorator name declared in
+ * the schema's `decorators` array, or `'*'` to match every decorator.
+ */
+type Decorator = {
+  kind: 'decorator';
+  type: string;
+  /**
+   * Outer render. Two modes:
+   * - omitted: fall through to global registered render (or identity,
+   *   the engine default, if no global registration exists)
+   * - function: use this render. The function receives a `renderDefault`
+   *   prop that returns identity when called.
+   */
+  render?: DecoratorRender;
+};
+/**
+ * @public
+ *
+ * An annotation registration. `type` is an annotation `_type` declared
+ * in the schema's `annotations` array, or `'*'` to match every
+ * annotation type.
+ */
+type Annotation = {
+  kind: 'annotation';
+  type: string;
+  /**
+   * Outer render. Two modes:
+   * - omitted: fall through to global registered render (or identity,
+   *   the engine default, if no global registration exists)
+   * - function: use this render. The function receives a `renderDefault`
+   *   prop that returns identity when called.
+   */
+  render?: AnnotationRender;
+};
+/**
+ * @public
  *
  * A non-editable block-level object registration. Identifies a `_type`
  * whose value renders as a block-level void node (image, embed, etc.).
@@ -349,7 +463,7 @@ type BlockObject = {
   render?: BlockObjectRender;
 };
 /**
- * @alpha
+ * @public
  *
  * A non-editable inline object registration. Identifies a `_type` whose
  * value renders as an inline void node (mention, inline image, etc.).
@@ -366,14 +480,14 @@ type InlineObject = {
   render?: InlineObjectRender;
 };
 /**
- * @alpha
+ * @public
  *
  * The discriminated union of every registration accepted by
  * `editor.registerNode` and the `<NodePlugin>` component.
  */
-type RegistrableNode = Container | TextBlock | Span | BlockObject | InlineObject;
+type RegistrableNode = Container | TextBlock | Span | BlockObject | InlineObject | Decorator | Annotation;
 /**
- * @alpha
+ * @public
  *
  * Define a container renderer. The returned registration is mounted via
  * the `<NodePlugin>` component at the top level, or nested inside
@@ -411,7 +525,7 @@ declare function defineContainer<const TType extends string>(config: {
     attributes: Record<string, unknown>;
     children: ReactElement;
     focused: boolean;
-    node: ContainerNodeForType<TType>;
+    node: TType extends 'span' | 'block' ? never : PortableTextObject;
     path: Path;
     readOnly: boolean;
     selected: boolean;
@@ -420,7 +534,7 @@ declare function defineContainer<const TType extends string>(config: {
   of?: ReadonlyArray<Container | TextBlock | BlockObject>;
 }): Container;
 /**
- * @alpha
+ * @public
  *
  * Define a span renderer. The returned registration is mounted via the
  * `<NodePlugin>` component at the top level, or nested inside a
@@ -446,7 +560,57 @@ declare function defineSpan<const TType extends string>(config: {
   render?: SpanRender;
 }): Span;
 /**
- * @alpha
+ * @public
+ *
+ * Define a decorator renderer for a decorator name declared in the
+ * schema's `decorators` array, or `'*'` to match every decorator.
+ * The returned registration is mounted via the `<NodePlugin>`
+ * component.
+ *
+ * Decorator names live in a different namespace than node
+ * `_type`s, so `type` has no forbidden values here (unlike
+ * `defineSpan`/`defineTextBlock`).
+ *
+ * @example
+ * ```ts
+ * defineDecorator({
+ *   type: 'strong',
+ *   render: ({children}) => <strong>{children}</strong>,
+ * })
+ * ```
+ */
+declare function defineDecorator(config: {
+  type: string;
+  render?: DecoratorRender;
+}): Decorator;
+/**
+ * @public
+ *
+ * Define an annotation renderer for a `_type` declared in the
+ * schema's `annotations` array, or `'*'` to match every annotation
+ * type. The returned registration is mounted via the `<NodePlugin>`
+ * component.
+ *
+ * Annotation `_type`s live in a different namespace than node
+ * `_type`s, so `type` has no forbidden values here (unlike
+ * `defineInlineObject`/`defineBlockObject`).
+ *
+ * @example
+ * ```ts
+ * defineAnnotation({
+ *   type: 'link',
+ *   render: ({annotation, children}) => (
+ *     <a href={(annotation as {href?: string}).href}>{children}</a>
+ *   ),
+ * })
+ * ```
+ */
+declare function defineAnnotation(config: {
+  type: string;
+  render?: AnnotationRender;
+}): Annotation;
+/**
+ * @public
  *
  * Define a non-editable block-level object renderer for a `_type`
  * declared in the schema's `blockObjects` array.
@@ -474,7 +638,7 @@ declare function defineBlockObject<const TType extends string>(config: {
   render?: BlockObjectRender;
 }): BlockObject;
 /**
- * @alpha
+ * @public
  *
  * Define a non-editable inline object renderer for a `_type` declared
  * in the schema's `inlineObjects` array.
@@ -502,7 +666,7 @@ declare function defineInlineObject<const TType extends string>(config: {
   render?: InlineObjectRender;
 }): InlineObject;
 /**
- * @alpha
+ * @public
  *
  * Define a text block renderer. The returned registration is mounted
  * via the `<NodePlugin>` component, or nested inside a container's
@@ -526,7 +690,7 @@ declare function defineInlineObject<const TType extends string>(config: {
 declare function defineTextBlock<const TType extends string>(config: {
   type: TType extends 'span' ? "Error: defineTextBlock({type: 'span'}) is forbidden -- 'span' is always a span, use defineSpan" : TType;
   render?: TextBlockRender;
-  of?: ReadonlyArray<Span | InlineObject>;
+  of?: ReadonlyArray<Span | InlineObject | Decorator | Annotation>;
 }): TextBlock;
 /**
  * @internal
@@ -536,6 +700,22 @@ declare function defineTextBlock<const TType extends string>(config: {
 type SpanConfig = {
   span: Span;
 };
+/**
+ * @internal
+ *
+ * Resolved decorator config.
+ */
+type DecoratorConfig = {
+  decorator: Decorator;
+};
+/**
+ * @internal
+ *
+ * Resolved annotation config.
+ */
+type AnnotationConfig = {
+  annotation: Annotation;
+};
 /**
  * @internal
  *
@@ -568,16 +748,13 @@ type ContainerConfig = {
  * @internal
  *
  * Resolved text block config. The optional `of` carries resolved
- * inline-content positional overrides (spans, inline-objects) for
- * children rendered inside this text block.
+ * inline-content positional overrides (spans, inline-objects, and
+ * per-decorator and per-annotation overrides) for children rendered
+ * inside this text block.
  */
 type TextBlockConfig = {
   textBlock: TextBlock;
-  of?: ReadonlyArray<SpanConfig | InlineObjectConfig>;
-};
-type ChildArrayField = FieldDefinition & {
-  type: 'array';
-  of: ReadonlyArray<OfDefinition>;
+  of?: ReadonlyArray<SpanConfig | InlineObjectConfig | DecoratorConfig | AnnotationConfig>;
 };
 /**
  * Public view of a registered editable container, surfaced on
@@ -597,8 +774,8 @@ type ChildArrayField = FieldDefinition & {
  *   scoped to this parent.
  *
  * The full container registration (including the render callback)
- * lives on the editor's internal {@link ResolvedContainers} map and
- * is not exposed on the public context.
+ * lives on an engine-internal map and is not exposed on the public
+ * context.
  *
  * Two top-level entries with the same `_type` cannot coexist - the
  * register handler warns on duplicates. But the SAME `_type`
@@ -606,20 +783,24 @@ type ChildArrayField = FieldDefinition & {
  * a feature; `resolveContainerAt` walks the positional tree using
  * the path to return the entry that applies at a given position.
  *
- * @alpha
+ * @public
  */
 type RegisteredContainer = {
   kind: 'container';
   type: string;
-  field: ChildArrayField;
+  field: FieldDefinition & {
+    type: 'array';
+    of: ReadonlyArray<OfDefinition>;
+  };
   of?: ReadonlyArray<RegisteredContainer | RegisteredPositional>;
 };
+type ChildArrayField = RegisteredContainer['field'];
 /**
  * Public view of a registered span, surfaced inside a containing
  * {@link RegisteredContainer}'s `of` array as a positional
  * registration. The render function is engine-internal.
  *
- * @alpha
+ * @public
  */
 type RegisteredSpan = {
   kind: 'span';
@@ -630,7 +811,7 @@ type RegisteredSpan = {
  * containing {@link RegisteredContainer}'s `of` array as a positional
  * registration. The render function is engine-internal.
  *
- * @alpha
+ * @public
  */
 type RegisteredBlockObject = {
   kind: 'blockObject';
@@ -641,7 +822,7 @@ type RegisteredBlockObject = {
  * containing {@link RegisteredContainer}'s `of` array as a positional
  * registration. The render function is engine-internal.
  *
- * @alpha
+ * @public
  */
 type RegisteredInlineObject = {
   kind: 'inlineObject';
@@ -650,10 +831,9 @@ type RegisteredInlineObject = {
 /**
  * Union of non-container positional registrations that may appear in
  * a {@link RegisteredContainer}'s `of` array. Text-block registrations
- * are NOT included here; they surface on `EditorContext.textBlocks`,
- * not on the containers tree.
+ * are NOT included here and do not appear on the containers tree.
  *
- * @alpha
+ * @public
  */
 type RegisteredPositional = RegisteredSpan | RegisteredBlockObject | RegisteredInlineObject;
 /**
@@ -673,7 +853,7 @@ type RegisteredPositional = RegisteredSpan | RegisteredBlockObject | RegisteredI
  * does not find a positional override, the resolver falls back to the
  * top-level entry for the type if one is registered.
  *
- * @alpha
+ * @public
  */
 type Containers = ReadonlyMap<string, RegisteredContainer>;
 /**
@@ -1137,12 +1317,45 @@ type PortableTextEditableProps = Omit<TextareaHTMLAttributes<HTMLDivElement>, 'o
   onPaste?: OnPasteFn;
   onCopy?: OnCopyFn;
   rangeDecorations?: RangeDecoration[];
+  /**
+   * @deprecated Register your annotations with `defineAnnotation`
+   * mounted through `NodePlugin` instead. See the migration guide:
+   * https://www.portabletext.org/editor/guides/migrate-render-props/
+   */
   renderAnnotation?: RenderAnnotationFunction;
+  /**
+   * @deprecated Register your block objects and text blocks with
+   * `defineBlockObject` / `defineTextBlock` mounted through `NodePlugin`
+   * instead. See the migration guide:
+   * https://www.portabletext.org/editor/guides/migrate-render-props/
+   */
   renderBlock?: RenderBlockFunction;
+  /**
+   * @deprecated Register your inline objects and spans with
+   * `defineInlineObject` / `defineSpan` mounted through `NodePlugin`
+   * instead. See the migration guide:
+   * https://www.portabletext.org/editor/guides/migrate-render-props/
+   */
   renderChild?: RenderChildFunction;
+  /**
+   * @deprecated Register your decorators with `defineDecorator` mounted
+   * through `NodePlugin` instead. See the migration guide:
+   * https://www.portabletext.org/editor/guides/migrate-render-props/
+   */
   renderDecorator?: RenderDecoratorFunction;
+  /**
+   * @deprecated Render list items with `defineTextBlock` mounted through
+   * `NodePlugin`, with list numbering from
+   * `@portabletext/plugin-list-index`. See the migration guide:
+   * https://www.portabletext.org/editor/guides/migrate-render-props/
+   */
   renderListItem?: RenderListItemFunction;
   renderPlaceholder?: RenderPlaceholderFunction;
+  /**
+   * @deprecated Render text-block styles with `defineTextBlock` mounted
+   * through `NodePlugin` instead. See the migration guide:
+   * https://www.portabletext.org/editor/guides/migrate-render-props/
+   */
   renderStyle?: RenderStyleFunction;
   scrollSelectionIntoView?: ScrollSelectionIntoViewFunction;
   selection?: EditorSelection;
@@ -1169,7 +1382,12 @@ type PortableTextEditableProps = Omit<TextareaHTMLAttributes<HTMLDivElement>, 'o
  * @group Components
  */
 declare const PortableTextEditable: import("react").ForwardRefExoticComponent<Omit<PortableTextEditableProps, "ref"> & import("react").RefAttributes<Omit<HTMLDivElement, "as" | "onPaste" | "onBeforeInput">>>;
-/** @beta */
+/**
+ * @beta
+ * @deprecated `EditableAPIDeleteOptions` is deprecated together with the
+ * `PortableTextEditor.delete` static. Send a `delete` behavior event (with
+ * an optional `unit`) or a `delete.block` event via `editor.send` instead.
+ */
 interface EditableAPIDeleteOptions {
   mode?: 'blocks' | 'children' | 'selected';
 }
@@ -1190,7 +1408,7 @@ type AddedAnnotationPaths = {
    */
   spanPath: Path;
 };
-/** @beta */
+/** @internal */
 interface EditableAPI {
   activeAnnotations: () => PortableTextObject[];
   isAnnotationActive: (annotationType: PortableTextObject['_type']) => boolean;
@@ -1251,7 +1469,7 @@ type EditorSelection = {
 } | null;
 /**
  * The editor has invalid data in the value that can be resolved by the user
- * @beta */
+ * @public */
 type InvalidValueResolution = {
   autoResolve?: boolean;
   patches: Patch[];
@@ -1296,7 +1514,14 @@ interface PasteData {
 type OnPasteFn = (data: PasteData) => OnPasteResultOrPromise;
 /** @beta */
 type OnCopyFn = (event: ClipboardEvent$1<HTMLDivElement | HTMLSpanElement>) => undefined | unknown;
-/** @beta */
+/**
+ * @beta
+ * @deprecated `BlockRenderProps` is deprecated together with the
+ * `renderBlock` render prop it serves. Type against
+ * `BlockObjectRenderProps` / `TextBlockRenderProps` from the node
+ * registration API instead. See the migration guide:
+ * https://www.portabletext.org/editor/guides/migrate-render-props/
+ */
 interface BlockRenderProps {
   children: ReactElement<any>;
   editorElementRef: RefObject<HTMLElement | null>;
@@ -1309,7 +1534,14 @@ interface BlockRenderProps {
   schemaType: BlockObjectSchemaType;
   value: PortableTextBlock;
 }
-/** @beta */
+/**
+ * @beta
+ * @deprecated `BlockChildRenderProps` is deprecated together with the
+ * `renderChild` render prop it serves. Type against
+ * `InlineObjectRenderProps` / `SpanRenderProps` from the node
+ * registration API instead. See the migration guide:
+ * https://www.portabletext.org/editor/guides/migrate-render-props/
+ */
 interface BlockChildRenderProps {
   annotations: PortableTextObject[];
   children: ReactElement<any>;
@@ -1320,7 +1552,14 @@ interface BlockChildRenderProps {
   schemaType: InlineObjectSchemaType;
   value: PortableTextChild;
 }
-/** @beta */
+/**
+ * @beta
+ * @deprecated `BlockAnnotationRenderProps` is deprecated together with the
+ * `renderAnnotation` render prop it serves. Type against
+ * `AnnotationRenderProps` from the node registration API instead. See the
+ * migration guide:
+ * https://www.portabletext.org/editor/guides/migrate-render-props/
+ */
 interface BlockAnnotationRenderProps {
   block: PortableTextBlock;
   children: ReactElement<any>;
@@ -1331,7 +1570,14 @@ interface BlockAnnotationRenderProps {
   selected: boolean;
   value: PortableTextObject;
 }
-/** @beta */
+/**
+ * @beta
+ * @deprecated `BlockDecoratorRenderProps` is deprecated together with the
+ * `renderDecorator` render prop it serves. Type against
+ * `DecoratorRenderProps` from the node registration API instead. See the
+ * migration guide:
+ * https://www.portabletext.org/editor/guides/migrate-render-props/
+ */
 interface BlockDecoratorRenderProps {
   children: ReactElement<any>;
   editorElementRef: RefObject<HTMLElement | null>;
@@ -1341,7 +1587,14 @@ interface BlockDecoratorRenderProps {
   selected: boolean;
   value: string;
 }
-/** @beta */
+/**
+ * @beta
+ * @deprecated `BlockListItemRenderProps` is deprecated together with the
+ * `renderListItem` render prop it serves. Render list items with
+ * `defineTextBlock` mounted through `NodePlugin` instead. See the
+ * migration guide:
+ * https://www.portabletext.org/editor/guides/migrate-render-props/
+ */
 interface BlockListItemRenderProps {
   block: PortableTextTextBlock;
   children: ReactElement<any>;
@@ -1353,19 +1606,51 @@ interface BlockListItemRenderProps {
   selected: boolean;
   value: string;
 }
-/** @beta */
+/**
+ * @beta
+ * @deprecated The `renderBlock` render prop is deprecated. Register your
+ * block objects and text blocks with `defineBlockObject` /
+ * `defineTextBlock` mounted through `NodePlugin` instead. See the
+ * migration guide:
+ * https://www.portabletext.org/editor/guides/migrate-render-props/
+ */
 type RenderBlockFunction = (props: BlockRenderProps) => JSX.Element;
-/** @beta */
+/**
+ * @beta
+ * @deprecated The `renderChild` render prop is deprecated. Register your
+ * inline objects and spans with `defineInlineObject` / `defineSpan`
+ * mounted through `NodePlugin` instead. See the migration guide:
+ * https://www.portabletext.org/editor/guides/migrate-render-props/
+ */
 type RenderChildFunction = (props: BlockChildRenderProps) => JSX.Element;
-/** @beta */
+/** @public */
 type RenderEditableFunction = (props: PortableTextEditableProps) => JSX.Element;
-/** @beta */
+/**
+ * @beta
+ * @deprecated The `renderAnnotation` render prop is deprecated. Register
+ * your annotations with `defineAnnotation` mounted through `NodePlugin`
+ * instead. See the migration guide:
+ * https://www.portabletext.org/editor/guides/migrate-render-props/
+ */
 type RenderAnnotationFunction = (props: BlockAnnotationRenderProps) => JSX.Element;
-/** @beta */
+/** @public */
 type RenderPlaceholderFunction = () => React.ReactNode;
-/** @beta */
+/**
+ * @beta
+ * @deprecated The `renderStyle` render prop is deprecated. Render
+ * text-block styles with `defineTextBlock` mounted through `NodePlugin`
+ * instead. See the migration guide:
+ * https://www.portabletext.org/editor/guides/migrate-render-props/
+ */
 type RenderStyleFunction = (props: BlockStyleRenderProps) => JSX.Element;
-/** @beta */
+/**
+ * @beta
+ * @deprecated `BlockStyleRenderProps` is deprecated together with the
+ * `renderStyle` render prop it serves. Render text-block styles with
+ * `defineTextBlock` mounted through `NodePlugin` instead. See the
+ * migration guide:
+ * https://www.portabletext.org/editor/guides/migrate-render-props/
+ */
 interface BlockStyleRenderProps {
   block: PortableTextTextBlock;
   children: ReactElement<any>;
@@ -1376,32 +1661,45 @@ interface BlockStyleRenderProps {
   schemaType: StyleSchemaType;
   value: string;
 }
-/** @beta */
+/**
+ * @beta
+ * @deprecated The `renderListItem` render prop is deprecated. Render list
+ * items with `defineTextBlock` mounted through `NodePlugin`, with list
+ * numbering from `@portabletext/plugin-list-index`. See the migration
+ * guide:
+ * https://www.portabletext.org/editor/guides/migrate-render-props/
+ */
 type RenderListItemFunction = (props: BlockListItemRenderProps) => JSX.Element;
-/** @beta */
+/**
+ * @beta
+ * @deprecated The `renderDecorator` render prop is deprecated. Register
+ * your decorators with `defineDecorator` mounted through `NodePlugin`
+ * instead. See the migration guide:
+ * https://www.portabletext.org/editor/guides/migrate-render-props/
+ */
 type RenderDecoratorFunction = (props: BlockDecoratorRenderProps) => JSX.Element;
-/** @beta */
+/** @public */
 type ScrollSelectionIntoViewFunction = (editor: PortableTextEditor, domRange: globalThis.Range) => void;
 /**
- * Parameters for the callback that will be called for a RangeDecoration's onMoved.
- * @alpha */
+ * Details passed to a `RangeDecoration`'s `onMoved` callback.
+ * @public */
 interface RangeDecorationOnMovedDetails {
   rangeDecoration: RangeDecoration;
   newSelection: EditorSelection;
   origin: 'remote' | 'local';
 }
 /**
- * A range decoration is a UI affordance that wraps a given selection range in the editor
- * with a custom component. This can be used to highlight search results,
- * mark validation errors on specific words, draw user presence and similar.
- * @alpha */
+ * A UI affordance that wraps a selection range in the editor with a custom
+ * component, for example to highlight search results, mark validation
+ * errors on specific words, or draw user presence.
+ * @public */
 interface RangeDecoration {
   /**
-   * A component for rendering the range decoration.
-   * The component will receive the children (text) of the range decoration as its children.
+   * The component that renders the range decoration. It receives the
+   * decorated text as its children.
    *
    * @example
-   * ```ts
+   * ```tsx
    * (rangeComponentProps: PropsWithChildren) => (
    *    <SearchResultHighlight>
    *      {rangeComponentProps.children}
@@ -1411,15 +1709,17 @@ interface RangeDecoration {
    */
   component: (props: PropsWithChildren) => ReactElement<any>;
   /**
-   * The editor content selection range
+   * The editor content selection range to decorate.
    */
   selection: EditorSelection;
   /**
-   * A optional callback that will be called when the range decoration potentially moves according to user edits.
+   * Called when edits move the decorated range. The details carry the new
+   * selection (`null` when the range is lost) and whether the edit was
+   * `local` or `remote`.
    */
   onMoved?: (details: RangeDecorationOnMovedDetails) => void;
   /**
-   * A custom payload that can be set on the range decoration
+   * A custom payload that can be set on the range decoration.
    */
   payload?: Record<string, unknown>;
 }
@@ -1854,7 +2154,9 @@ interface PortableTextEditorEngine extends DOMEditor {
   _key: 'editor';
   _type: 'editor';
   containers: ResolvedContainers;
+  annotations: Map<string, AnnotationConfig>;
   blockObjects: Map<string, BlockObjectConfig>;
+  decorators: Map<string, DecoratorConfig>;
   inlineObjects: Map<string, InlineObjectConfig>;
   spans: Map<string, SpanConfig>;
   textBlocks: Map<string, TextBlockConfig>;
@@ -1959,7 +2261,7 @@ type EditorContext = {
    * `resolveContainerAt(containers, value, path)` for position-aware
    * resolution that handles both top-level and positional entries.
    *
-   * @alpha
+   * @public
    */
   containers: Containers;
 };
@@ -1976,7 +2278,7 @@ type EditorSnapshot = {
   decoratorState: Record<string, boolean | undefined>;
 };
 /**
- * @beta
+ * @public
  */
 type BehaviorGuard<TBehaviorEvent, TGuardResponse> = (payload: {
   snapshot: EditorSnapshot;
@@ -1984,7 +2286,7 @@ type BehaviorGuard<TBehaviorEvent, TGuardResponse> = (payload: {
   dom: EditorDom;
 }) => TGuardResponse | false;
 /**
- * @beta
+ * @public
  */
 type Behavior<TBehaviorEventType extends '*' | `${BehaviorEventTypeNamespace}.*` | BehaviorEvent['type'] = '*' | `${BehaviorEventTypeNamespace}.*` | BehaviorEvent['type'], TGuardResponse = true, TBehaviorEvent extends ResolveBehaviorEvent<TBehaviorEventType> = ResolveBehaviorEvent<TBehaviorEventType>> = {
   /**
@@ -2004,7 +2306,7 @@ type Behavior<TBehaviorEventType extends '*' | `${BehaviorEventTypeNamespace}.*`
   actions: Array<BehaviorActionSet<TBehaviorEvent, TGuardResponse>>;
 };
 /**
- * @beta
+ * @public
  *
  * @example
  *
@@ -2134,9 +2436,6 @@ type PatchEvent = {
  * @public
  */
 type EditorConfig = {
-  /**
-   * @beta
-   */
   keyGenerator?: () => string;
   readOnly?: boolean;
   initialValue?: Array<PortableTextBlock>;
@@ -2176,7 +2475,7 @@ type Editor = {
   dom: EditorDom;
   getSnapshot: () => EditorSnapshot;
   /**
-   * @beta
+   * @public
    */
   registerBehavior: (config: {
     behavior: Behavior;
@@ -2184,10 +2483,11 @@ type Editor = {
   /**
    * Register a node renderer. The `node` argument is the result of one
    * of the `defineX` factories (`defineContainer`, `defineTextBlock`,
-   * `defineSpan`, `defineBlockObject`, `defineInlineObject`). Returns
-   * a function that unregisters the node when called.
+   * `defineSpan`, `defineBlockObject`, `defineInlineObject`,
+   * `defineDecorator`, `defineAnnotation`). Returns a function that
+   * unregisters the node when called.
    *
-   * @alpha
+   * @public
    */
   registerNode: (config: {
     node: RegistrableNode;
@@ -2333,7 +2633,7 @@ declare const defaultKeyGenerator: () => string;
  */
 declare function useEditor(): Editor;
 /**
- * @beta
+ * @public
  */
 type BlockOffset = {
   path: BlockPath;
@@ -2652,7 +2952,7 @@ type SpanWithOptionalKey = Omit<PortableTextSpan, '_key'> & {
 };
 type ChildWithOptionalKey = SpanWithOptionalKey | ObjectBlockWithOptionalKey;
 /**
- * @beta
+ * @public
  */
 type BehaviorEvent = SyntheticBehaviorEvent | NativeBehaviorEvent | CustomBehaviorEvent;
 type BehaviorEventTypeNamespace = SyntheticBehaviorEventNamespace | NativeBehaviorEventNamespace | CustomBehaviorEventNamespace;
@@ -2683,7 +2983,7 @@ declare const syntheticBehaviorEventTypes: readonly ["annotation.add", "annotati
 type SyntheticBehaviorEventType = (typeof syntheticBehaviorEventTypes)[number] | (typeof abstractBehaviorEventTypes)[number];
 type SyntheticBehaviorEventNamespace = ExtractNamespace<SyntheticBehaviorEventType>;
 /**
- * @beta
+ * @public
  */
 type SyntheticBehaviorEvent = {
   type: StrictExtract<SyntheticBehaviorEventType, 'annotation.add'>;
@@ -2893,7 +3193,7 @@ type SyntheticBehaviorEvent = {
   at: Path;
 } | AbstractBehaviorEvent;
 /**
- * @beta
+ * @public
  */
 type InsertPlacement = 'auto' | 'after' | 'before';
 /**************************************
@@ -3043,7 +3343,7 @@ declare const nativeBehaviorEventTypes: readonly ["clipboard.copy", "clipboard.c
 type NativeBehaviorEventType = (typeof nativeBehaviorEventTypes)[number];
 type NativeBehaviorEventNamespace = ExtractNamespace<NativeBehaviorEventType>;
 /**
- * @beta
+ * @public
  */
 type NativeBehaviorEvent = ClipboardBehaviorEvent | DragBehaviorEvent | InputBehaviorEvent | KeyboardBehaviorEvent | MouseBehaviorEvent;
 type ClipboardBehaviorEvent = {
@@ -3143,7 +3443,7 @@ type MouseBehaviorEvent = {
 type CustomBehaviorEventNamespace = 'custom';
 type CustomBehaviorEventType<TNamespace extends CustomBehaviorEventNamespace, TType extends string = ''> = TType extends '' ? `${TNamespace}` : `${TNamespace}.${TType}`;
 /**
- * @beta
+ * @public
  */
 type CustomBehaviorEvent<TPayload extends Record<string, unknown> = Record<string, unknown>, TType extends string = string, TInternalType extends CustomBehaviorEventType<'custom', TType> = CustomBehaviorEventType<'custom', TType>> = {
   type: TInternalType;
@@ -3189,7 +3489,7 @@ type EditorDom = {
   }) => void;
 };
 /**
- * @beta
+ * @public
  */
 type BehaviorAction = {
   type: 'execute';
@@ -3243,7 +3543,7 @@ type BehaviorAction = {
  * })
  * ```
  *
- * @beta
+ * @public
  */
 declare function execute(event: SyntheticBehaviorEvent): PickFromUnion<BehaviorAction, 'type', 'execute'>;
 /**
@@ -3281,7 +3581,7 @@ declare function execute(event: SyntheticBehaviorEvent): PickFromUnion<BehaviorA
  * })
  * ```
  *
- * @beta
+ * @public
  */
 declare function forward(event: NativeBehaviorEvent | SyntheticBehaviorEvent | CustomBehaviorEvent): PickFromUnion<BehaviorAction, 'type', 'forward'>;
 /**
@@ -3315,7 +3615,7 @@ declare function forward(event: NativeBehaviorEvent | SyntheticBehaviorEvent | C
  * })
  * ```
  *
- * @beta
+ * @public
  */
 declare function raise$1(event: SyntheticBehaviorEvent | CustomBehaviorEvent): PickFromUnion<BehaviorAction, 'type', 'raise'>;
 /**
@@ -3358,16 +3658,16 @@ declare function raise$1(event: SyntheticBehaviorEvent | CustomBehaviorEvent): P
  * })
  * ```
  *
- * @beta
+ * @public
  */
 declare function effect(effect: PickFromUnion<BehaviorAction, 'type', 'effect'>['effect']): PickFromUnion<BehaviorAction, 'type', 'effect'>;
 /**
- * @beta
+ * @public
  */
 type BehaviorActionSet<TBehaviorEvent, TGuardResponse> = (payload: {
   snapshot: EditorSnapshot;
   event: TBehaviorEvent;
   dom: EditorDom;
 }, guardResponse: TGuardResponse) => Array<BehaviorAction>;
-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, PathSegment as mn, OnPasteResult as mt, BehaviorActionSet as n, TextBlockRender as nn, BlockAnnotationRenderProps as nt, raise$1 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-CYtiRDck.d.ts.map
+export { BehaviorGuard as $, DecoratorRender as $t, PortableTextSpan$1 as A, PortableTextEditableProps as At, usePortableTextEditor as B, RegisteredInlineObject as Bt, ListDefinition as C, PathSegment as Cn, RenderDecoratorFunction as Ct, PortableTextBlock$1 as D, RenderStyleFunction as Dt, Patch$1 as E, RenderPlaceholderFunction as Et, defineSchema as F, Node$1 as Ft, Editor as G, AnnotationRenderProps as Gt, useEditorSelector as H, RegisteredSpan as Ht, BlockOffset as I, EditorSchema as It, EditorEmittedEvent as J, BlockObjectRenderProps as Jt, EditorConfig as K, BlockObject as Kt, useEditor as L, Containers as Lt, SchemaDefinition$1 as M, PortableTextEditor as Mt, StyleDefinition as N, resolveContainerAt as Nt, PortableTextChild$1 as O, ScrollSelectionIntoViewFunction as Ot, StyleSchemaType$1 as P, TraversalSnapshot as Pt, defineBehavior as Q, Decorator as Qt, defaultKeyGenerator as R, RegisteredBlockObject as Rt, InlineObjectSchemaType$1 as S, Path as Sn, RenderChildFunction as St, OfDefinition$1 as T, RenderListItemFunction as Tt, EditorProvider as U, Annotation as Ut, EditorSelector as V, RegisteredPositional as Vt, EditorProviderProps as W, AnnotationRender as Wt, Operation as X, ContainerRender as Xt, MutationEvent as Y, Container as Yt, Behavior as Z, ContainerRenderProps as Zt, BlockObjectSchemaType$1 as _, defineTextBlock as _n, PasteData as _t, forward as a, Span as an, BlockDecoratorRenderProps as at, FieldDefinition$1 as b, ChildPath as bn, RenderAnnotationFunction as bt, CustomBehaviorEvent as c, TextBlock as cn, BlockStyleRenderProps as ct, SyntheticBehaviorEvent as d, defineAnnotation as dn, EditorSelectionPoint as dt, DecoratorRenderProps as en, EditorContext as et, PatchesEvent as f, defineBlockObject as fn, InvalidValueResolution as ft, BlockObjectDefinition as g, defineSpan as gn, OnPasteResultOrPromise as gt, BaseDefinition as h, defineInlineObject as hn, OnPasteResult as ht, execute as i, RegistrableNode as in, BlockChildRenderProps as it, PortableTextTextBlock$1 as j, HotkeyOptions as jt, PortableTextObject$1 as k, PortableTextEditable as kt, InsertPlacement as l, TextBlockRender as ln, EditableAPIDeleteOptions as lt, AnnotationSchemaType$1 as m, defineDecorator as mn, OnPasteFn as mt, BehaviorActionSet as n, InlineObjectRender as nn, AddedAnnotationPaths as nt, raise$1 as o, SpanRender as on, BlockListItemRenderProps as ot, AnnotationDefinition as p, defineContainer as pn, OnCopyFn as pt, EditorEvent as q, BlockObjectRender as qt, effect as r, InlineObjectRenderProps as rn, BlockAnnotationRenderProps as rt, BehaviorEvent as s, SpanRenderProps as sn, BlockRenderProps as st, BehaviorAction as t, InlineObject as tn, EditorSnapshot as tt, NativeBehaviorEvent as u, TextBlockRenderProps as un, EditorSelection as ut, DecoratorDefinition as v, AnnotationPath as vn, RangeDecoration as vt, ListSchemaType$1 as w, RenderEditableFunction as wt, InlineObjectDefinition as x, KeyedSegment as xn, RenderBlockFunction as xt, DecoratorSchemaType$1 as y, BlockPath as yn, RangeDecorationOnMovedDetails as yt, usePortableTextEditorSelection as z, RegisteredContainer as zt };
+//# sourceMappingURL=behavior.types.action-DH6ujvaH.d.ts.map