@portabletext/editor 6.6.4 → 7.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/lib/_chunks-dts/behavior.types.action.d.ts +683 -512
  2. package/lib/_chunks-dts/behavior.types.action.d.ts.map +1 -1
  3. package/lib/_chunks-dts/resolve-containers.d.ts +688 -0
  4. package/lib/_chunks-dts/resolve-containers.d.ts.map +1 -0
  5. package/lib/_chunks-es/get-ancestor.js +192 -0
  6. package/lib/_chunks-es/get-ancestor.js.map +1 -0
  7. package/lib/_chunks-es/get-first-child.js +130 -0
  8. package/lib/_chunks-es/get-first-child.js.map +1 -0
  9. package/lib/_chunks-es/get-path-sub-schema.js +266 -0
  10. package/lib/_chunks-es/get-path-sub-schema.js.map +1 -0
  11. package/lib/_chunks-es/selector.is-at-the-start-of-block.js +1021 -0
  12. package/lib/_chunks-es/selector.is-at-the-start-of-block.js.map +1 -0
  13. package/lib/_chunks-es/use-editor.js +4 -13
  14. package/lib/_chunks-es/use-editor.js.map +1 -1
  15. package/lib/_chunks-es/util.is-empty-text-block.js +15 -0
  16. package/lib/_chunks-es/util.is-empty-text-block.js.map +1 -0
  17. package/lib/_chunks-es/util.slice-blocks.js +347 -198
  18. package/lib/_chunks-es/util.slice-blocks.js.map +1 -1
  19. package/lib/behaviors/index.d.ts +2 -1
  20. package/lib/index.d.ts +3 -2
  21. package/lib/index.js +5457 -5611
  22. package/lib/index.js.map +1 -1
  23. package/lib/plugins/index.d.ts +18 -2
  24. package/lib/plugins/index.d.ts.map +1 -1
  25. package/lib/plugins/index.js +18 -2
  26. package/lib/plugins/index.js.map +1 -1
  27. package/lib/selectors/index.d.ts +220 -5
  28. package/lib/selectors/index.d.ts.map +1 -1
  29. package/lib/selectors/index.js +62 -71
  30. package/lib/selectors/index.js.map +1 -1
  31. package/lib/traversal/index.d.ts +235 -0
  32. package/lib/traversal/index.d.ts.map +1 -0
  33. package/lib/traversal/index.js +30 -0
  34. package/lib/traversal/index.js.map +1 -0
  35. package/lib/utils/index.d.ts +11 -57
  36. package/lib/utils/index.d.ts.map +1 -1
  37. package/lib/utils/index.js +36 -107
  38. package/lib/utils/index.js.map +1 -1
  39. package/package.json +19 -17
  40. package/lib/_chunks-es/selector.is-selecting-entire-blocks.js +0 -806
  41. package/lib/_chunks-es/selector.is-selecting-entire-blocks.js.map +0 -1
  42. package/lib/_chunks-es/util.slice-text-block.js +0 -60
  43. package/lib/_chunks-es/util.slice-text-block.js.map +0 -1
@@ -0,0 +1,688 @@
1
+ import { FieldDefinition, OfDefinition, PortableTextObject, PortableTextSpan, PortableTextTextBlock, Schema } from "@portabletext/schema";
2
+ import { ReactElement } from "react";
3
+ /**
4
+ * A segment in a path that identifies an element by its `_key` property.
5
+ * @public
6
+ */
7
+ interface KeyedSegment {
8
+ _key: string;
9
+ }
10
+ /**
11
+ * A tuple representing a range selection, e.g., `[0, 5]` or `['', 3]`.
12
+ * @public
13
+ */
14
+ type IndexTuple = [number | '', number | ''];
15
+ /**
16
+ * A single segment in a path. Can be:
17
+ * - A string (property name)
18
+ * - A number (array index)
19
+ * - A KeyedSegment (object with `_key`)
20
+ * - An IndexTuple (range selection)
21
+ * @public
22
+ */
23
+ type PathSegment$1 = string | number | KeyedSegment | IndexTuple;
24
+ /**
25
+ * A path is an array of path segments that describes a location in a document.
26
+ * @public
27
+ */
28
+ type Path$1 = PathSegment$1[];
29
+ /**
30
+ * A path to a block in the value.
31
+ *
32
+ * @public
33
+ */
34
+ type BlockPath = Path$1;
35
+ /**
36
+ * A path to an annotation markDef on a block.
37
+ *
38
+ * @public
39
+ */
40
+ type AnnotationPath = Path$1;
41
+ /**
42
+ * A path to a child of a text block.
43
+ *
44
+ * @public
45
+ */
46
+ type ChildPath = Path$1;
47
+ /**
48
+ * A path segment identifies a position in the document tree.
49
+ *
50
+ * - `KeyedSegment` (`{_key: string}`) identifies a node by its key
51
+ * - `string` identifies a child field name (e.g. 'children', 'rows', 'cells')
52
+ * - `number` identifies a position in an array (used for empty container inserts
53
+ * and rendering indexed paths)
54
+ * - `IndexTuple` (`[number | '', number | '']`) represents a range selection
55
+ */
56
+ type PathSegment = KeyedSegment | string | number | IndexTuple;
57
+ /**
58
+ * A `Path` is a list of segments that describe a node's exact position in
59
+ * the document tree. Segments alternate between keyed node references and
60
+ * field names: `[{_key: 'b1'}, 'children', {_key: 's1'}]`.
61
+ */
62
+ type Path = PathSegment[];
63
+ /**
64
+ * @alpha
65
+ *
66
+ * Narrow the container node type by the registered `_type`. Containers
67
+ * always render portable text objects: `'span'` is always a leaf and
68
+ * `'block'` is always a text block; both are excluded.
69
+ */
70
+ type ContainerNodeForType<TType extends string> = TType extends 'span' | 'block' ? never : PortableTextObject;
71
+ /**
72
+ * @alpha
73
+ *
74
+ * A container's render function receives a node and renders an element
75
+ * that wraps its editable children. The render is positional: it fires for
76
+ * nodes of `type` whose parent permits this container at `arrayField`.
77
+ *
78
+ * `node` is `PortableTextObject` because containers cannot register the
79
+ * built-in `'span'` or `'block'` types (those are leaves and text blocks
80
+ * respectively).
81
+ */
82
+ type ContainerRenderProps = {
83
+ attributes: Record<string, unknown>;
84
+ children: ReactElement;
85
+ focused: boolean;
86
+ node: PortableTextObject;
87
+ path: Path;
88
+ readOnly: boolean;
89
+ selected: boolean;
90
+ /**
91
+ * Render this position with the engine's default wrapper. Call from
92
+ * inside a custom render to fall back to or wrap the default:
93
+ *
94
+ * ```ts
95
+ * render: ({renderDefault, ...rest}) => renderDefault(rest)
96
+ * ```
97
+ *
98
+ * The default is the engine's minimal wrapper. It does not chain
99
+ * back to a globally-registered render: PTE has one user layer plus
100
+ * positional overrides, and the engine default is the canonical
101
+ * fallback at any position.
102
+ */
103
+ renderDefault: (props: ContainerRenderProps) => ReactElement;
104
+ };
105
+ type ContainerRender = (props: ContainerRenderProps) => ReactElement;
106
+ /**
107
+ * @alpha
108
+ *
109
+ * A span's render function. Receives a portable text span node and
110
+ * wraps it. `children` carries the styled text already decorated by
111
+ * `renderDecorator`/`renderAnnotation`/range decorations.
112
+ */
113
+ type SpanRenderProps = {
114
+ attributes: Record<string, unknown>;
115
+ children: ReactElement;
116
+ focused: boolean;
117
+ node: PortableTextSpan;
118
+ path: Path;
119
+ readOnly: boolean;
120
+ selected: boolean;
121
+ /**
122
+ * Render this position with the engine's default wrapper.
123
+ * See {@link ContainerRenderProps.renderDefault}.
124
+ */
125
+ renderDefault: (props: SpanRenderProps) => ReactElement;
126
+ };
127
+ type SpanRender = (props: SpanRenderProps) => ReactElement;
128
+ /**
129
+ * @alpha
130
+ *
131
+ * A block object's render function. Receives a non-editable block-level
132
+ * portable text object. `children` carries an engine-emitted void
133
+ * spacer that the browser uses to anchor the caret next to the
134
+ * element. Dropping `children` makes the caret unable to land on the
135
+ * element.
136
+ */
137
+ type BlockObjectRenderProps = {
138
+ attributes: Record<string, unknown>;
139
+ children: ReactElement;
140
+ focused: boolean;
141
+ node: PortableTextObject;
142
+ path: Path;
143
+ readOnly: boolean;
144
+ selected: boolean;
145
+ /**
146
+ * Render this position with the engine's default wrapper.
147
+ * See {@link ContainerRenderProps.renderDefault}.
148
+ */
149
+ renderDefault: (props: BlockObjectRenderProps) => ReactElement;
150
+ };
151
+ type BlockObjectRender = (props: BlockObjectRenderProps) => ReactElement;
152
+ /**
153
+ * @alpha
154
+ *
155
+ * An inline object's render function. Receives a non-editable inline
156
+ * portable text object. `children` carries an engine-emitted void
157
+ * spacer that the browser uses to anchor the caret next to the
158
+ * element. Dropping `children` makes the caret unable to land on the
159
+ * element.
160
+ */
161
+ type InlineObjectRenderProps = {
162
+ attributes: Record<string, unknown>;
163
+ children: ReactElement;
164
+ focused: boolean;
165
+ node: PortableTextObject;
166
+ path: Path;
167
+ readOnly: boolean;
168
+ selected: boolean;
169
+ /**
170
+ * Render this position with the engine's default wrapper.
171
+ * See {@link ContainerRenderProps.renderDefault}.
172
+ */
173
+ renderDefault: (props: InlineObjectRenderProps) => ReactElement;
174
+ };
175
+ type InlineObjectRender = (props: InlineObjectRenderProps) => ReactElement;
176
+ /**
177
+ * @alpha
178
+ *
179
+ * A container registration. Identifies a block object `_type` whose value
180
+ * holds editable children in `arrayField`. The optional `of` array carries
181
+ * nested registrations that override how immediate children of this
182
+ * container render at this lexical scope.
183
+ *
184
+ * `of` overrides apply ONE level down only. Children at deeper levels fall
185
+ * through to global registrations.
186
+ *
187
+ * The `kind` field is injected by `defineContainer` and discriminates
188
+ * containers from other registration kinds at runtime.
189
+ */
190
+ type Container = {
191
+ kind: 'container';
192
+ type: string;
193
+ arrayField: string;
194
+ /**
195
+ * Outer render. Two modes:
196
+ * - omitted: fall through to global registered render (or engine default)
197
+ * - function: use this render. The function receives a `renderDefault`
198
+ * prop that returns the engine default when called.
199
+ */
200
+ render?: ContainerRender;
201
+ /**
202
+ * Block-level positional overrides. Inline-content kinds (`Span`,
203
+ * `InlineObject`) belong in `TextBlock.of`, not here.
204
+ */
205
+ of?: ReadonlyArray<Container | TextBlock | BlockObject>;
206
+ };
207
+ /**
208
+ * @alpha
209
+ *
210
+ * A text block registration. The text block `_type` is `'block'` at the
211
+ * top level. Positional overrides nested in a container's `of` array can
212
+ * register a different `_type` to render at that lexical scope.
213
+ *
214
+ * `defineTextBlock` opts the text block into the new render pipeline.
215
+ * The consumer's `render` callback owns the outer wrapper entirely:
216
+ * the engine emits `data-pt-*` attributes only - no `pt-*` CSS classes,
217
+ * no legacy `data-block-*` attributes - and the block-level
218
+ * `renderStyle`/`renderListItem`/`renderBlock` props on
219
+ * `<PortableTextEditable>` do not compose under this registration.
220
+ *
221
+ * Span-level render props - `renderDecorator`, `renderAnnotation`,
222
+ * `renderPlaceholder`, and range decorations - keep working. They fire
223
+ * on the spans inside `children` regardless of which text block outer
224
+ * wrapper renders them.
225
+ */
226
+ type TextBlock = {
227
+ kind: 'textBlock';
228
+ type: string;
229
+ /**
230
+ * Outer render. Two modes:
231
+ * - omitted: fall through to global registered render (or engine default)
232
+ * - function: use this render. The function receives a `renderDefault`
233
+ * prop that returns the engine default when called.
234
+ */
235
+ render?: TextBlockRender;
236
+ /**
237
+ * Inline-content positional overrides. A `Span` or `InlineObject`
238
+ * placed here scopes the inline render to this text block (or any
239
+ * text block of this `type` if registered at the top level).
240
+ */
241
+ of?: ReadonlyArray<Span | InlineObject>;
242
+ };
243
+ /**
244
+ * @alpha
245
+ *
246
+ * Text block render function. `children` carries the rendered spans -
247
+ * `renderDecorator`, `renderAnnotation`, `renderPlaceholder`, and range
248
+ * decorations have already fired at the leaf level. The render's job
249
+ * is the outer wrapper element and any block-level composition (style,
250
+ * list-item) the consumer wants.
251
+ */
252
+ type TextBlockRenderProps = {
253
+ attributes: Record<string, unknown>;
254
+ children: ReactElement;
255
+ focused: boolean;
256
+ node: PortableTextTextBlock;
257
+ path: Path;
258
+ readOnly: boolean;
259
+ selected: boolean;
260
+ /**
261
+ * Render this position with the engine's default wrapper.
262
+ * See {@link ContainerRenderProps.renderDefault}.
263
+ */
264
+ renderDefault: (props: TextBlockRenderProps) => ReactElement;
265
+ };
266
+ type TextBlockRender = (props: TextBlockRenderProps) => ReactElement;
267
+ /**
268
+ * @alpha
269
+ *
270
+ * A span registration. The span `_type` is `'span'` at the top level.
271
+ * Positional overrides nested in a container's `of` array can register
272
+ * a different `_type` for a span-like inline at that lexical scope
273
+ * (e.g. a `code-span` inside a `code-block`).
274
+ */
275
+ type Span = {
276
+ kind: 'span';
277
+ type: string;
278
+ /**
279
+ * Outer render. Two modes:
280
+ * - omitted: fall through to global registered render (or engine default)
281
+ * - function: use this render. The function receives a `renderDefault`
282
+ * prop that returns the engine default when called.
283
+ */
284
+ render?: SpanRender;
285
+ };
286
+ /**
287
+ * @alpha
288
+ *
289
+ * A non-editable block-level object registration. Identifies a `_type`
290
+ * whose value renders as a block-level void node (image, embed, etc.).
291
+ */
292
+ type BlockObject = {
293
+ kind: 'blockObject';
294
+ type: string;
295
+ /**
296
+ * Outer render. Two modes:
297
+ * - omitted: fall through to global registered render (or engine default)
298
+ * - function: use this render. The function receives a `renderDefault`
299
+ * prop that returns the engine default when called.
300
+ */
301
+ render?: BlockObjectRender;
302
+ };
303
+ /**
304
+ * @alpha
305
+ *
306
+ * A non-editable inline object registration. Identifies a `_type` whose
307
+ * value renders as an inline void node (mention, inline image, etc.).
308
+ */
309
+ type InlineObject = {
310
+ kind: 'inlineObject';
311
+ type: string;
312
+ /**
313
+ * Outer render. Two modes:
314
+ * - omitted: fall through to global registered render (or engine default)
315
+ * - function: use this render. The function receives a `renderDefault`
316
+ * prop that returns the engine default when called.
317
+ */
318
+ render?: InlineObjectRender;
319
+ };
320
+ /**
321
+ * @alpha
322
+ *
323
+ * The discriminated union of every registration accepted by
324
+ * `editor.registerNode` and the `<NodePlugin>` component.
325
+ */
326
+ type RegistrableNode = Container | TextBlock | Span | BlockObject | InlineObject;
327
+ /**
328
+ * @alpha
329
+ *
330
+ * Define a container renderer. The returned registration is mounted via
331
+ * the `<NodePlugin>` component at the top level, or nested inside
332
+ * another container's `of` array as a positional override.
333
+ *
334
+ * `type` cannot be `'span'` (use {@link defineSpan}) nor `'block'` (use
335
+ * {@link defineTextBlock}). The text block is not a container.
336
+ *
337
+ * The `node` argument of `render` narrows to a portable text object.
338
+ *
339
+ * @example
340
+ * ```ts
341
+ * defineContainer({
342
+ * type: 'table',
343
+ * arrayField: 'rows',
344
+ * render: ({children}) => (
345
+ * <table>{children}</table>
346
+ * ),
347
+ * of: [
348
+ * defineContainer({
349
+ * type: 'row',
350
+ * arrayField: 'cells',
351
+ * render: ({children}) => (
352
+ * <tr>{children}</tr>
353
+ * ),
354
+ * }),
355
+ * ],
356
+ * })
357
+ * ```
358
+ */
359
+ declare function defineContainer<const TType extends string>(config: {
360
+ type: TType extends 'span' ? "Error: defineContainer({type: 'span'}) is forbidden -- 'span' is always a span, use defineSpan" : TType extends 'block' ? "Error: defineContainer({type: 'block'}) is forbidden -- 'block' is always a text block, use defineTextBlock" : TType;
361
+ arrayField: string;
362
+ render?: (props: {
363
+ attributes: Record<string, unknown>;
364
+ children: ReactElement;
365
+ focused: boolean;
366
+ node: ContainerNodeForType<TType>;
367
+ path: Path;
368
+ readOnly: boolean;
369
+ selected: boolean;
370
+ renderDefault: (props: ContainerRenderProps) => ReactElement;
371
+ }) => ReactElement;
372
+ of?: ReadonlyArray<Container | TextBlock | BlockObject>;
373
+ }): Container;
374
+ /**
375
+ * @alpha
376
+ *
377
+ * Define a span renderer. The returned registration is mounted via the
378
+ * `<NodePlugin>` component at the top level, or nested inside a
379
+ * container's `of` array as a positional override.
380
+ *
381
+ * `type` is required even though there is only one top-level span type
382
+ * (`'span'`) today. Keeping `type` required leaves the door open for
383
+ * positional overrides of span-like inlines (e.g. a `code-span` inside
384
+ * a `code-block` container).
385
+ *
386
+ * @example
387
+ * ```ts
388
+ * defineSpan({
389
+ * type: 'span',
390
+ * render: ({attributes, children}) => (
391
+ * <span {...attributes}>{children}</span>
392
+ * ),
393
+ * })
394
+ * ```
395
+ */
396
+ declare function defineSpan<const TType extends string>(config: {
397
+ type: TType extends 'block' ? "Error: defineSpan({type: 'block'}) is forbidden -- 'block' is always a text block, use defineTextBlock" : TType;
398
+ render?: SpanRender;
399
+ }): Span;
400
+ /**
401
+ * @alpha
402
+ *
403
+ * Define a non-editable block-level object renderer for a `_type`
404
+ * declared in the schema's `blockObjects` array.
405
+ *
406
+ * The render must always render `children` somewhere inside the outer
407
+ * element. `children` carries an engine-emitted void spacer the browser
408
+ * uses to anchor the caret next to the element. Dropping `children`
409
+ * makes the caret unable to land on the element.
410
+ *
411
+ * @example
412
+ * ```ts
413
+ * defineBlockObject({
414
+ * type: 'image',
415
+ * render: ({attributes, children, node}) => (
416
+ * <div {...attributes}>
417
+ * {children}
418
+ * <img src={(node as {src?: string}).src} />
419
+ * </div>
420
+ * ),
421
+ * })
422
+ * ```
423
+ */
424
+ declare function defineBlockObject<const TType extends string>(config: {
425
+ type: TType extends 'block' ? "Error: defineBlockObject({type: 'block'}) is forbidden -- 'block' is always a text block, use defineTextBlock" : TType extends 'span' ? "Error: defineBlockObject({type: 'span'}) is forbidden -- 'span' is always a span, use defineSpan" : TType;
426
+ render?: BlockObjectRender;
427
+ }): BlockObject;
428
+ /**
429
+ * @alpha
430
+ *
431
+ * Define a non-editable inline object renderer for a `_type` declared
432
+ * in the schema's `inlineObjects` array.
433
+ *
434
+ * The render must always render `children` somewhere inside the outer
435
+ * element. `children` carries an engine-emitted void spacer the browser
436
+ * uses to anchor the caret next to the element. Dropping `children`
437
+ * makes the caret unable to land on the element.
438
+ *
439
+ * @example
440
+ * ```ts
441
+ * defineInlineObject({
442
+ * type: 'mention',
443
+ * render: ({attributes, children, node}) => (
444
+ * <span {...attributes}>
445
+ * {children}
446
+ * @{(node as {username?: string}).username}
447
+ * </span>
448
+ * ),
449
+ * })
450
+ * ```
451
+ */
452
+ declare function defineInlineObject<const TType extends string>(config: {
453
+ type: TType extends 'block' ? "Error: defineInlineObject({type: 'block'}) is forbidden -- 'block' is always a text block, use defineTextBlock" : TType extends 'span' ? "Error: defineInlineObject({type: 'span'}) is forbidden -- 'span' is always a span, use defineSpan" : TType;
454
+ render?: InlineObjectRender;
455
+ }): InlineObject;
456
+ /**
457
+ * @alpha
458
+ *
459
+ * Define a text block renderer. The returned registration is mounted
460
+ * via the `<NodePlugin>` component, or nested inside a container's
461
+ * `of` array as a positional override.
462
+ *
463
+ * `type` is required even though the top-level text block type is
464
+ * always `'block'`. Keeping `type` required leaves the door open for
465
+ * positional overrides of text-block-like elements (e.g. a `code-line`
466
+ * inside a `code-block` container).
467
+ *
468
+ * @example
469
+ * ```ts
470
+ * defineTextBlock({
471
+ * type: 'block',
472
+ * render: ({attributes, children}) => (
473
+ * <p {...attributes}>{children}</p>
474
+ * ),
475
+ * })
476
+ * ```
477
+ */
478
+ declare function defineTextBlock<const TType extends string>(config: {
479
+ type: TType extends 'span' ? "Error: defineTextBlock({type: 'span'}) is forbidden -- 'span' is always a span, use defineSpan" : TType;
480
+ render?: TextBlockRender;
481
+ of?: ReadonlyArray<Span | InlineObject>;
482
+ }): TextBlock;
483
+ /**
484
+ * @internal
485
+ *
486
+ * Resolved span config.
487
+ */
488
+ type SpanConfig = {
489
+ span: Span;
490
+ };
491
+ /**
492
+ * @internal
493
+ *
494
+ * Resolved block-object config.
495
+ */
496
+ type BlockObjectConfig = {
497
+ blockObject: BlockObject;
498
+ };
499
+ /**
500
+ * @internal
501
+ *
502
+ * Resolved inline-object config.
503
+ */
504
+ type InlineObjectConfig = {
505
+ inlineObject: InlineObject;
506
+ };
507
+ /**
508
+ * @internal
509
+ *
510
+ * Resolved container config carrying the pre-resolved `field` for the
511
+ * activation position. Dispatch reads pre-resolved data without
512
+ * re-walking the schema.
513
+ */
514
+ type ContainerConfig = {
515
+ container: Container;
516
+ field: ChildArrayField;
517
+ of?: ReadonlyArray<ContainerConfig | BlockObjectConfig | TextBlockConfig>;
518
+ };
519
+ /**
520
+ * @internal
521
+ *
522
+ * Resolved text block config. The optional `of` carries resolved
523
+ * inline-content positional overrides (spans, inline-objects) for
524
+ * children rendered inside this text block.
525
+ */
526
+ type TextBlockConfig = {
527
+ textBlock: TextBlock;
528
+ of?: ReadonlyArray<SpanConfig | InlineObjectConfig>;
529
+ };
530
+ type ChildArrayField = FieldDefinition & {
531
+ type: 'array';
532
+ of: ReadonlyArray<OfDefinition>;
533
+ };
534
+ /**
535
+ * Public view of a registered editable container, surfaced on
536
+ * {@link EditorContext.containers}.
537
+ *
538
+ * Two array properties named `of` live on the same entry with
539
+ * different semantics:
540
+ *
541
+ * - `field.of` is the SCHEMA-DECLARED list of types this container's
542
+ * child field accepts (from `@portabletext/schema`'s
543
+ * `OfDefinition`). Tells you what the schema permits as children.
544
+ * - `of` (top-level on `RegisteredContainer`) is the list of
545
+ * POSITIONAL CHILD REGISTRATIONS - nested
546
+ * {@link RegisteredContainer} or {@link RegisteredPositional}
547
+ * entries - that override the global registration when the engine
548
+ * descends into this parent. Tells you which child renderings are
549
+ * scoped to this parent.
550
+ *
551
+ * The full container registration (including the render callback)
552
+ * lives on the editor's internal {@link ResolvedContainers} map and
553
+ * is not exposed on the public context.
554
+ *
555
+ * Two top-level entries with the same `_type` cannot coexist - the
556
+ * register handler warns on duplicates. But the SAME `_type`
557
+ * registered in two different parents' `of` arrays is supported as
558
+ * a feature; `resolveContainerAt` walks the positional tree using
559
+ * the path to return the entry that applies at a given position.
560
+ *
561
+ * @alpha
562
+ */
563
+ type RegisteredContainer = {
564
+ kind: 'container';
565
+ type: string;
566
+ field: ChildArrayField;
567
+ of?: ReadonlyArray<RegisteredContainer | RegisteredPositional>;
568
+ };
569
+ /**
570
+ * Public view of a registered span, surfaced inside a containing
571
+ * {@link RegisteredContainer}'s `of` array as a positional
572
+ * registration. The render function is engine-internal.
573
+ *
574
+ * @alpha
575
+ */
576
+ type RegisteredSpan = {
577
+ kind: 'span';
578
+ type: string;
579
+ };
580
+ /**
581
+ * Public view of a registered block object, surfaced inside a
582
+ * containing {@link RegisteredContainer}'s `of` array as a positional
583
+ * registration. The render function is engine-internal.
584
+ *
585
+ * @alpha
586
+ */
587
+ type RegisteredBlockObject = {
588
+ kind: 'blockObject';
589
+ type: string;
590
+ };
591
+ /**
592
+ * Public view of a registered inline object, surfaced inside a
593
+ * containing {@link RegisteredContainer}'s `of` array as a positional
594
+ * registration. The render function is engine-internal.
595
+ *
596
+ * @alpha
597
+ */
598
+ type RegisteredInlineObject = {
599
+ kind: 'inlineObject';
600
+ type: string;
601
+ };
602
+ /**
603
+ * Union of non-container positional registrations that may appear in
604
+ * a {@link RegisteredContainer}'s `of` array. Text-block registrations
605
+ * are NOT included here; they surface on `EditorContext.textBlocks`,
606
+ * not on the containers tree.
607
+ *
608
+ * @alpha
609
+ */
610
+ type RegisteredPositional = RegisteredSpan | RegisteredBlockObject | RegisteredInlineObject;
611
+ /**
612
+ * Map of registered editable containers carried on `EditorContext`.
613
+ *
614
+ * Keyed by bare block-object `_type` (e.g. `'callout'`, `'table'`).
615
+ * Each entry is a rich {@link RegisteredContainer} carrying its
616
+ * `field` plus any positional `of` registrations.
617
+ *
618
+ * The map preserves positional structure: a `_type` declared inside
619
+ * a parent's `of` array surfaces as a nested entry on that parent's
620
+ * `of`, NOT as a separate top-level entry. Path-driven resolution
621
+ * (see `resolveContainerAt`) reaches positional entries by walking
622
+ * the tree.
623
+ *
624
+ * Top-level entries are global fallbacks: when path-driven descent
625
+ * does not find a positional override, the resolver falls back to the
626
+ * top-level entry for the type if one is registered.
627
+ *
628
+ * @alpha
629
+ */
630
+ type Containers = ReadonlyMap<string, RegisteredContainer>;
631
+ /**
632
+ * Engine-internal map carrying the fully-resolved container
633
+ * configurations - including render functions and positional `of`
634
+ * overrides. Lives on `editor.containers` and is consulted by render
635
+ * dispatch and engine-internal helpers.
636
+ *
637
+ * Not exposed on {@link EditorContext}.
638
+ */
639
+ type ResolvedContainers = Map<string, ContainerConfig>;
640
+ /**
641
+ * @public
642
+ */
643
+ type EditorSchema = Schema;
644
+ type Node = PortableTextTextBlock | PortableTextObject | PortableTextSpan;
645
+ /**
646
+ * Snapshot-shaped input for traversal utilities.
647
+ *
648
+ * Mirrors the shape of `EditorSnapshot`: ambient state lives under
649
+ * `context`, the `blockIndexMap` perf cache sits as a sibling.
650
+ */
651
+ type TraversalSnapshot = {
652
+ context: {
653
+ schema: EditorSchema;
654
+ containers: Containers;
655
+ value: Array<Node>;
656
+ };
657
+ blockIndexMap: Map<string, number>;
658
+ };
659
+ /**
660
+ * Walk the editor value following `path` and return the
661
+ * {@link RegisteredContainer} or {@link RegisteredPositional} that applies
662
+ * at `path`'s target position.
663
+ *
664
+ * Resolution rules at each step:
665
+ *
666
+ * 1. **Positional override.** If the current parent declares the
667
+ * child's `_type` in its `of`, the positional entry wins.
668
+ * Used to resolve same-`_type` registered under different
669
+ * parents with different `field` values.
670
+ *
671
+ * 2. **Global fallback.** If the parent has no positional override,
672
+ * fall back to the top-level entry for `_type` in
673
+ * `containers`.
674
+ *
675
+ * 3. **Chain validity.** If any ancestor along the path has no
676
+ * resolved container entry (unregistered or not reachable as a
677
+ * container at its position), return `undefined`.
678
+ *
679
+ * Returns `undefined` when the target's `_type` is not registered
680
+ * at this position. Returns a {@link RegisteredPositional} when the target
681
+ * resolves to a leaf in a positional `of` (terminal node with no
682
+ * editable children).
683
+ *
684
+ * @alpha
685
+ */
686
+ declare function resolveContainerAt(containers: Containers, value: ReadonlyArray<Node>, path: Path): RegisteredContainer | RegisteredPositional | undefined;
687
+ export { ChildPath as A, defineContainer as C, Path as D, defineTextBlock as E, Path$1 as M, AnnotationPath as O, defineBlockObject as S, defineSpan as T, RegistrableNode as _, Containers as a, TextBlock as b, RegisteredInlineObject as c, ResolvedContainers as d, BlockObject as f, InlineObjectConfig as g, InlineObject as h, EditorSchema as i, KeyedSegment as j, BlockPath as k, RegisteredPositional as l, Container as m, TraversalSnapshot as n, RegisteredBlockObject as o, BlockObjectConfig as p, Node as r, RegisteredContainer as s, resolveContainerAt as t, RegisteredSpan as u, Span as v, defineInlineObject as w, TextBlockConfig as x, SpanConfig as y };
688
+ //# sourceMappingURL=resolve-containers.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"resolve-containers.d.ts","names":[],"sources":["../../src/types/paths.ts","../../src/slate/interfaces/path.ts","../../src/renderers/renderer.types.ts","../../src/schema/container-types.ts","../../src/editor/editor-schema.ts","../../src/slate/interfaces/node.ts","../../src/node-traversal/traversal-snapshot.ts","../../src/schema/resolve-container-at.ts"],"sourcesContent":[],"mappings":"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"}