foldkit-richtext 0.1.0 → 0.3.0

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.
package/dist/index.d.mts CHANGED
@@ -1120,6 +1120,44 @@ export declare const locateBlock: (document: Document, node: NodeId) => {
1120
1120
  } | undefined;
1121
1121
  /** The run with this identity, wherever it sits. */
1122
1122
  export declare const locateRun: (document: Document, node: NodeId) => LocatedRun | undefined;
1123
+ /**
1124
+ * Whether a reader would see nothing: no blocks, or a lone paragraph or heading whose runs
1125
+ * hold no text. What an editor shows its placeholder for; a lone empty list or code block is
1126
+ * content a writer made, so it is not blank.
1127
+ */
1128
+ export declare const isBlank: (document: Document) => boolean;
1129
+ /**
1130
+ * The text of the block a position addresses, up to that position, in run order.
1131
+ * A menu reads this: what a query is typed into is the block's text between its
1132
+ * start and the caret, and a query never spans blocks. Affinity is not consulted — a
1133
+ * prefix ends between characters whatever side the caret leans to — an offset past a
1134
+ * run's end clamps to it, a negative one reads as none of it, and a position that
1135
+ * resolves to nothing gives an empty string.
1136
+ */
1137
+ export declare const textBefore: (document: Document, position: Position) => string;
1138
+ /**
1139
+ * Whichever end of a range comes first in the document, whatever direction it was made in,
1140
+ * or `undefined` when either end does not resolve. What replaces a range starts here, so a
1141
+ * read of the text before an edit reads from this end rather than the anchor.
1142
+ */
1143
+ export declare const rangeStart: (document: Document, range: Extract<Selection, {
1144
+ readonly type: "Range";
1145
+ }>) => Position | undefined;
1146
+ /**
1147
+ * The position a block's text offset addresses, or `undefined` when it is negative or past
1148
+ * the end. The inverse of `textBefore` for one block: a rule, a search match, or any producer
1149
+ * working in a block's own text needs it to say where what it found is.
1150
+ */
1151
+ export declare const positionInBlock: (block: Block, offset: number) => Position | undefined;
1152
+ /**
1153
+ * The range covering the `length` characters before `position` in its block, or
1154
+ * `undefined` when the position does not resolve, `length` is not positive, or fewer
1155
+ * characters precede it. The inverse of `textBefore`: an input rule or a menu deletes
1156
+ * what it matched with this range, so removing the match and acting on it commit as one
1157
+ * action (§124 §5). Endpoints land at run boundaries with `after` affinity, which is
1158
+ * where a caret that typed that character would sit.
1159
+ */
1160
+ export declare const textRangeBefore: (document: Document, position: Position, length: number) => Selection | undefined;
1123
1161
  /** A mark this vocabulary does not define, kept verbatim on its text run. */
1124
1162
  interface UnknownMark {
1125
1163
  readonly node: NodeId;
@@ -1535,6 +1573,16 @@ export declare const inspect: (document: Document) => {
1535
1573
  textLength: number;
1536
1574
  depth: number;
1537
1575
  };
1576
+ /**
1577
+ * What a reader would count: words and user-perceived characters, as `Intl.Segmenter` splits
1578
+ * them in the default locale, so a word in a script without spaces still counts. Runs are
1579
+ * joined within a block, so a word that changes mark midway is one word, and blocks never
1580
+ * join, so the last word of one block and the first of the next are two.
1581
+ */
1582
+ export declare const count: (document: Document) => {
1583
+ words: number;
1584
+ characters: number;
1585
+ };
1538
1586
  //#endregion
1539
1587
  //#region src/marks.d.ts
1540
1588
  /** Which edges a mark continues across when typing at a run boundary. */
@@ -1575,6 +1623,8 @@ export declare const shippedMarks: ReadonlyArray<MarkDef>;
1575
1623
  interface MarkRegistry {
1576
1624
  readonly expansionOf: (name: string) => MarkExpansion;
1577
1625
  readonly declares: (name: string) => boolean;
1626
+ /** Whether an edit may add this mark: its name is declared and its props decode. */
1627
+ readonly accepts: (mark: RunMark) => boolean;
1578
1628
  }
1579
1629
  export declare const markRegistry: (definitions: ReadonlyArray<MarkDef>) => MarkRegistry;
1580
1630
  /** The policy of the shipped vocabulary. */
@@ -1965,6 +2015,161 @@ export declare const serializeSlice: (slice: Slice) => string;
1965
2015
  /** Decodes a slice, or undefined when the payload is not one this version wrote. */
1966
2016
  export declare const deserializeSlice: (input: unknown) => Slice | undefined;
1967
2017
  //#endregion
2018
+ //#region src/kit.d.ts
2019
+ /** Whether a kind's runs may carry formatting marks; `all` unless declared otherwise. */
2020
+ type MarksPolicy = 'all' | 'none';
2021
+ /**
2022
+ * Block content that accepts only the named kinds, so a `List` can declare that its
2023
+ * children are `ListItem`s and `validate` can report one that is not (§13, §125).
2024
+ */
2025
+ interface BlockConstraint {
2026
+ readonly mode: typeof blockContent;
2027
+ readonly of: ReadonlyArray<string>;
2028
+ }
2029
+ /** Declares that a node holds nested blocks, only of the named kinds. */
2030
+ export declare const blocksOf: (...kinds: ReadonlyArray<string>) => BlockConstraint;
2031
+ /** A kind's declared content: a mode, or block content restricted to named kinds. */
2032
+ type ChildrenDeclaration = ContentMode | BlockConstraint;
2033
+ /**
2034
+ * The node shapes this version can declare: a `block` is one of the built-in
2035
+ * text blocks, an `atom` is an addressable node holding nothing (with optional
2036
+ * props), and an application `node` holds runs or nested blocks plus props its own
2037
+ * schema validates (§13).
2038
+ */
2039
+ type NodeDefinition = {
2040
+ readonly name: string;
2041
+ readonly kind: 'block';
2042
+ readonly children: 'text';
2043
+ } | {
2044
+ readonly name: string;
2045
+ readonly kind: 'atom';
2046
+ readonly children: 'none';
2047
+ /** An atom's props decode at this boundary too, so an `Image` carries a source. */
2048
+ readonly props?: PropsSchema | undefined;
2049
+ } | {
2050
+ readonly name: string;
2051
+ readonly kind: 'node';
2052
+ /** `textContent` holds runs; `blockContent` or `blocksOf(…)` holds nested blocks. */
2053
+ readonly children: ChildrenDeclaration;
2054
+ /** `none` forbids marks on this kind's runs, as a `CodeBlock` needs. */
2055
+ readonly marks: MarksPolicy;
2056
+ /** Validates a `Node` block's `props` at this boundary, not in the codec. */
2057
+ readonly props?: PropsSchema | undefined;
2058
+ /**
2059
+ * A boundary a lift never crosses: a table cell's content stays in the cell, where a
2060
+ * quote's or a list item's would be lifted out.
2061
+ */
2062
+ readonly isolating?: boolean | undefined;
2063
+ /** Props a copy split off this node starts with, over the original's (§135). */
2064
+ readonly splitProps?: NodeBlock['props'] | undefined;
2065
+ /**
2066
+ * The kinds this one may stand in (§149); absent, any that holds it. A kind that names
2067
+ * them never stands at the top level, as a `ListItem` stands only in a `List`.
2068
+ */
2069
+ readonly within?: ReadonlyArray<string> | undefined;
2070
+ };
2071
+ /**
2072
+ * A declared application node, with the caller's name, prop schema, and content
2073
+ * mode kept in the type: the erasure to `any` happens only where heterogeneous
2074
+ * definitions are collected, not at the authoring call.
2075
+ */
2076
+ interface NodeDefinitionOf<Name extends string, Props extends PropsSchema | undefined, Children extends ChildrenDeclaration = typeof textContent> {
2077
+ readonly name: Name;
2078
+ readonly kind: 'node';
2079
+ readonly children: Children;
2080
+ readonly marks: MarksPolicy;
2081
+ readonly props: Props;
2082
+ readonly isolating: boolean;
2083
+ readonly splitProps: NodeBlock['props'] | undefined;
2084
+ readonly within: ReadonlyArray<string> | undefined;
2085
+ }
2086
+ /** Declares a block node kind: a top-level node containing text runs. */
2087
+ export declare const block: (name: string) => NodeDefinition;
2088
+ /**
2089
+ * Declares an atom: an addressable node with no text content. Its optional props
2090
+ * decode at the same boundary as a `node`'s, so an `Image` is an atom carrying a
2091
+ * source rather than a run holder.
2092
+ */
2093
+ export declare const atom: (name: string, options?: {
2094
+ readonly Props?: PropsSchema | undefined;
2095
+ }) => NodeDefinition;
2096
+ /**
2097
+ * Declares an application node kind: a `Node` block whose props this schema
2098
+ * validates and whose content the `children` declaration states — a mode, or block
2099
+ * content restricted to the kinds `blocksOf` names. `marks: 'none'` forbids marks on
2100
+ * its runs. The document codec keeps those props as JSON; the Kit is where an
2101
+ * application's types meet them.
2102
+ */
2103
+ export declare const node: <const Name extends string, Props extends PropsSchema | undefined = undefined, Children extends ChildrenDeclaration = typeof textContent>(name: Name, options?: {
2104
+ readonly Props?: Props;
2105
+ readonly children?: Children;
2106
+ readonly marks?: MarksPolicy;
2107
+ /** A boundary a lift never crosses, as a table cell is. */
2108
+ readonly isolating?: boolean;
2109
+ /**
2110
+ * Props a copy split off this node starts with, laid over the original's: Enter in a
2111
+ * checked task item starts an unchecked one.
2112
+ */
2113
+ readonly splitProps?: Props extends PropsSchema ? Partial<Schema.Schema.Type<Props>> : NodeBlock["props"];
2114
+ /** The kinds this one may stand in; it then never stands at the top level (§149). */
2115
+ readonly within?: ReadonlyArray<string>;
2116
+ }) => NodeDefinitionOf<Name, Props, Children>;
2117
+ /**
2118
+ * The vocabulary one editor accepts: which node kinds and marks are available.
2119
+ * A Kit is a definition, never document state, and it never holds renderers or
2120
+ * executable code. Transforms and metadata arrive later.
2121
+ */
2122
+ interface Kit {
2123
+ readonly nodes: ReadonlyArray<NodeDefinition>;
2124
+ /** Mark definitions, not just names: a Kit carries each mark's boundary policy. */
2125
+ readonly marks: ReadonlyArray<MarkDef>;
2126
+ }
2127
+ export declare const kit: (definition: {
2128
+ readonly nodes: ReadonlyArray<NodeDefinition>;
2129
+ readonly marks: ReadonlyArray<MarkDef>;
2130
+ }) => Kit;
2131
+ interface Diagnostic {
2132
+ readonly code: 'UnknownNode' | 'UnsupportedNode' | 'UnknownMark' | 'InvalidProps' | 'MismatchedDefinition' | 'UnexpectedChild' | 'MisplacedNode' | 'ForbiddenMark';
2133
+ readonly message: string;
2134
+ readonly node?: NodeId;
2135
+ readonly detail?: string;
2136
+ }
2137
+ /**
2138
+ * A block's semantic kind: an application node's declared kind, a preserved node's
2139
+ * original type, or a built-in block's own type. This is what a `blocksOf`
2140
+ * constraint names, and what a `NodeRegistry` is looked up by.
2141
+ */
2142
+ export declare const blockKind: (block: Block) => string;
2143
+ /** Structural summary of a Kit, for tooling and tests. */
2144
+ export declare const inspectKit: (definition: Kit) => {
2145
+ blocks: number;
2146
+ atoms: number;
2147
+ nodes: number;
2148
+ marks: number;
2149
+ };
2150
+ /**
2151
+ * The node vocabulary an edit may target, the way `MarkRegistry` is the mark
2152
+ * vocabulary a mark edit consults. `run` reads a kind's declaration from it to refuse
2153
+ * an edit a constraint forbids (§117, §125); `apply` still takes none, so a durable
2154
+ * transaction never depends on a vocabulary that may have moved.
2155
+ */
2156
+ interface NodeRegistry {
2157
+ /** The declaration for a block kind, or undefined when this vocabulary has none. */
2158
+ readonly definitionFor: (kind: string) => NodeDefinition | undefined;
2159
+ }
2160
+ /** Builds the registry an edit consults. A later declaration for a name wins, as a Map does. */
2161
+ export declare const nodeRegistry: (definitions: ReadonlyArray<NodeDefinition>) => NodeRegistry;
2162
+ /**
2163
+ * Checks a document against a Kit's vocabulary without changing it, walking
2164
+ * nested blocks so a container's children are checked too. Reports preserved
2165
+ * unknown blocks, known blocks the Kit does not declare, declarations that
2166
+ * disagree with how the document holds a block, application nodes whose props
2167
+ * their schema refuses, and marks outside the Kit or whose props their definition
2168
+ * refuses. Content diagnostics never strip or repair the document; callers decide
2169
+ * whether to block publishing or surface a placeholder.
2170
+ */
2171
+ export declare const validate: (document: Document, definition: Kit) => ReadonlyArray<Diagnostic>;
2172
+ //#endregion
1968
2173
  //#region src/transform.d.ts
1969
2174
  /**
1970
2175
  * Transforms normalize or derive semantic structure after edits (§23). A
@@ -2004,9 +2209,9 @@ interface Transform {
2004
2209
  export declare const unchanged: (document: Document) => TransformReport;
2005
2210
  /**
2006
2211
  * Merges adjacent runs whose mark sets match, within the blocks the transaction
2007
- * touched. Merging strictly reduces the run count, so one pass reaches a stable
2008
- * state and a second pass finds nothing: the rule is idempotent, and only equal
2009
- * mark sets merge, so an unknown mark never drops.
2212
+ * touched, at any depth. Merging strictly reduces the run count, so one pass reaches
2213
+ * a stable state and a second pass finds nothing: the rule is idempotent, and only
2214
+ * equal mark sets merge, so an unknown mark never drops.
2010
2215
  */
2011
2216
  export declare const mergeAdjacentRuns: Transform;
2012
2217
  /** The transforms every transaction runs, in order, unless a caller says otherwise. */
@@ -2015,6 +2220,34 @@ export declare const defaultTransforms: ReadonlyArray<Transform>;
2015
2220
  //#region src/transaction.d.ts
2016
2221
  /** How many normalization passes a transaction may spend before it gives up. */
2017
2222
  export declare const MAX_NORMALIZATION_PASSES = 10;
2223
+ /**
2224
+ * What a text block retypes to: a paragraph, or a heading at a level. Its runs are
2225
+ * its own and survive the change; only the block's type does not.
2226
+ */
2227
+ export declare const TextBlock: Schema.Union<readonly [Schema.Struct<{
2228
+ readonly type: Schema.Literal<"Paragraph">;
2229
+ }>, Schema.Struct<{
2230
+ readonly type: Schema.Literal<"Heading">;
2231
+ readonly level: Schema.Literals<readonly [1, 2, 3, 4, 5, 6]>;
2232
+ }>]>;
2233
+ export type TextBlock = typeof TextBlock.Type;
2234
+ /**
2235
+ * What a block becomes, under its own identity and with its own content: a block that holds
2236
+ * text becomes a paragraph, a heading, or an application node kind that holds text, such as a
2237
+ * code block, keeping its runs; a node that holds blocks becomes another node kind, keeping
2238
+ * its nested blocks, as a list item becomes a task.
2239
+ */
2240
+ export declare const RetypeTarget: Schema.Union<readonly [Schema.Struct<{
2241
+ readonly type: Schema.Literal<"Paragraph">;
2242
+ }>, Schema.Struct<{
2243
+ readonly type: Schema.Literal<"Heading">;
2244
+ readonly level: Schema.Literals<readonly [1, 2, 3, 4, 5, 6]>;
2245
+ }>, Schema.Struct<{
2246
+ readonly type: Schema.Literal<"Node">;
2247
+ readonly kind: Schema.NonEmptyString;
2248
+ readonly props: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
2249
+ }>]>;
2250
+ export type RetypeTarget = typeof RetypeTarget.Type;
2018
2251
  export declare const Operation: Schema.Union<readonly [Schema.Struct<{
2019
2252
  readonly type: Schema.Literal<"InsertText">;
2020
2253
  readonly at: Schema.Struct<{
@@ -2075,9 +2308,22 @@ export declare const Operation: Schema.Union<readonly [Schema.Struct<{
2075
2308
  /** The block list to move into: a node block's, or the document's when absent. */
2076
2309
  readonly parent: Schema.optionalKey<Schema.brand<Schema.NonEmptyString, "foldkit-richtext/NodeId">>;
2077
2310
  }>, Schema.Struct<{
2078
- readonly type: Schema.Literal<"SetNodeProps">;
2311
+ readonly type: Schema.Literal<"RetypeBlock">;
2079
2312
  readonly node: Schema.brand<Schema.NonEmptyString, "foldkit-richtext/NodeId">;
2080
- readonly level: Schema.Literals<readonly [1, 2, 3, 4, 5, 6]>;
2313
+ readonly to: Schema.Union<readonly [Schema.Struct<{
2314
+ readonly type: Schema.Literal<"Paragraph">;
2315
+ }>, Schema.Struct<{
2316
+ readonly type: Schema.Literal<"Heading">;
2317
+ readonly level: Schema.Literals<readonly [1, 2, 3, 4, 5, 6]>;
2318
+ }>, Schema.Struct<{
2319
+ readonly type: Schema.Literal<"Node">;
2320
+ readonly kind: Schema.NonEmptyString;
2321
+ readonly props: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
2322
+ }>]>;
2323
+ }>, Schema.Struct<{
2324
+ readonly type: Schema.Literal<"SetProps">;
2325
+ readonly node: Schema.brand<Schema.NonEmptyString, "foldkit-richtext/NodeId">;
2326
+ readonly props: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
2081
2327
  }>, Schema.Struct<{
2082
2328
  readonly type: Schema.Literal<"InsertNode">;
2083
2329
  readonly block: Schema.Union<readonly [Schema.Struct<{
@@ -2483,9 +2729,22 @@ export declare const Transaction: Schema.$Array<Schema.Union<readonly [Schema.St
2483
2729
  /** The block list to move into: a node block's, or the document's when absent. */
2484
2730
  readonly parent: Schema.optionalKey<Schema.brand<Schema.NonEmptyString, "foldkit-richtext/NodeId">>;
2485
2731
  }>, Schema.Struct<{
2486
- readonly type: Schema.Literal<"SetNodeProps">;
2732
+ readonly type: Schema.Literal<"RetypeBlock">;
2487
2733
  readonly node: Schema.brand<Schema.NonEmptyString, "foldkit-richtext/NodeId">;
2488
- readonly level: Schema.Literals<readonly [1, 2, 3, 4, 5, 6]>;
2734
+ readonly to: Schema.Union<readonly [Schema.Struct<{
2735
+ readonly type: Schema.Literal<"Paragraph">;
2736
+ }>, Schema.Struct<{
2737
+ readonly type: Schema.Literal<"Heading">;
2738
+ readonly level: Schema.Literals<readonly [1, 2, 3, 4, 5, 6]>;
2739
+ }>, Schema.Struct<{
2740
+ readonly type: Schema.Literal<"Node">;
2741
+ readonly kind: Schema.NonEmptyString;
2742
+ readonly props: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
2743
+ }>]>;
2744
+ }>, Schema.Struct<{
2745
+ readonly type: Schema.Literal<"SetProps">;
2746
+ readonly node: Schema.brand<Schema.NonEmptyString, "foldkit-richtext/NodeId">;
2747
+ readonly props: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
2489
2748
  }>, Schema.Struct<{
2490
2749
  readonly type: Schema.Literal<"InsertNode">;
2491
2750
  readonly block: Schema.Union<readonly [Schema.Struct<{
@@ -2865,8 +3124,12 @@ export declare const Edit: {
2865
3124
  moveBlock: (node: TextTarget, to: number, parent?: TextTarget) => Extract<Operation, {
2866
3125
  readonly type: "MoveNode";
2867
3126
  }>;
2868
- setNodeProps: (node: TextTarget, level: 1 | 2 | 3 | 4 | 5 | 6) => Extract<Operation, {
2869
- readonly type: "SetNodeProps";
3127
+ retypeBlock: (node: TextTarget, to: RetypeTarget) => Extract<Operation, {
3128
+ readonly type: "RetypeBlock";
3129
+ }>;
3130
+ /** Sets the named props of a node block; props it does not name keep their values. */
3131
+ setProps: (node: TextTarget, props: Schema.JsonObject) => Extract<Operation, {
3132
+ readonly type: "SetProps";
2870
3133
  }>;
2871
3134
  insertBlock: (block: Block, at: number, parent?: TextTarget) => Extract<Operation, {
2872
3135
  readonly type: "InsertNode";
@@ -2929,9 +3192,15 @@ type TransactionResult = {
2929
3192
  readonly state: EditorState;
2930
3193
  readonly changeSet: ChangeSet;
2931
3194
  readonly positionMap: ReadonlyArray<PositionStep | SplitStep | RelocateStep | CollapseStep>;
3195
+ /**
3196
+ * The transactions that produced `state`, in order, each normalized before the next:
3197
+ * folding `apply` over them from the input state yields `state` again. A command can
3198
+ * need more than one, and an action has at least one per command.
3199
+ */
3200
+ readonly transactions: ReadonlyArray<Transaction>;
2932
3201
  } | {
2933
3202
  readonly ok: false;
2934
- readonly error: 'InvalidInput' | 'MissingText' | 'MissingNode' | 'InvalidRange' | 'InvalidSelection' | 'InvalidParent' | 'UnstableNormalization';
3203
+ readonly error: 'InvalidInput' | 'MissingText' | 'MissingNode' | 'InvalidRange' | 'InvalidSelection' | 'InvalidParent' | 'ForbiddenMark' | 'UnexpectedChild' | 'UnstableNormalization';
2935
3204
  };
2936
3205
  /**
2937
3206
  * Pure, atomic text transaction. Rejection returns no partially edited state.
@@ -2961,13 +3230,105 @@ type Command = {
2961
3230
  } | {
2962
3231
  readonly type: 'ToggleMark';
2963
3232
  readonly mark: string | MarkValue;
3233
+ } |
3234
+ /**
3235
+ * Puts exactly this mark on every run the selection covers, replacing a same-named mark
3236
+ * whose props differ: how a link gets a new `href`. A caret acts on the extent of the
3237
+ * mark around it (`markExtent`), and does nothing outside one.
3238
+ */
3239
+ {
3240
+ readonly type: 'SetMark';
3241
+ readonly mark: string | MarkValue;
3242
+ } |
3243
+ /** Takes the named mark off every run the selection covers; a caret, off its extent. */
3244
+ {
3245
+ readonly type: 'ClearMark';
3246
+ readonly mark: string;
2964
3247
  } | {
2965
3248
  readonly type: 'SetSelection';
2966
3249
  readonly selection: Selection | null;
2967
3250
  } | {
2968
3251
  readonly type: 'Paste';
2969
3252
  readonly slice: Slice;
3253
+ } |
3254
+ /** Retypes the block the selection starts in: a paragraph, or a heading. */
3255
+ {
3256
+ readonly type: 'RetypeBlock';
3257
+ readonly to: TextBlock;
3258
+ } |
3259
+ /**
3260
+ * Wraps the block the selection starts in, in new containers listed outermost first: a
3261
+ * `Quote`, or a `List` holding a `ListItem`. The block keeps its identity and its runs,
3262
+ * so the caret stays where it was. Given a vocabulary, a list wrap right after a list of the
3263
+ * same kind and props adds the block to it as a new item.
3264
+ */
3265
+ {
3266
+ readonly type: 'WrapBlock';
3267
+ readonly containers: ReadonlyArray<Container>;
3268
+ } |
3269
+ /**
3270
+ * Retypes the text block the selection starts in to a node kind that holds text, such as a
3271
+ * `CodeBlock`. The block and its runs keep their identities, text, and marks.
3272
+ */
3273
+ {
3274
+ readonly type: 'ConvertBlock';
3275
+ readonly to: Container;
3276
+ } |
3277
+ /**
3278
+ * Retypes the container the selection starts in (the node block holding its block, such as
3279
+ * a list item) to another node kind, where it stands: its identity and every block it holds
3280
+ * are kept, so edits made inside it meanwhile survive. Only from the container's first block,
3281
+ * which is where a marker for the container is typed. Given a vocabulary, the new kind must
3282
+ * hold blocks, hold each block the container holds, and stand where the container does.
3283
+ */
3284
+ {
3285
+ readonly type: 'RetypeContainer';
3286
+ readonly to: Container;
3287
+ } |
3288
+ /**
3289
+ * Lifts the block the selection starts in out of its container, the inverse of a wrap:
3290
+ * repeated while the new parent's declaration refuses it, so a list item's paragraph leaves
3291
+ * both the item and the list. The block keeps its identity, and the caret with it.
3292
+ */
3293
+ {
3294
+ readonly type: 'LiftBlock';
3295
+ } |
3296
+ /**
3297
+ * Moves a block, and everything it holds, before or after another block, in its own container
3298
+ * or another one the vocabulary lets it stand in (§149). It addresses blocks rather than the
3299
+ * selection, so a handle or a key can move the block it stands for; identities are kept, and
3300
+ * the selection with them. A container the move leaves empty is deleted.
3301
+ */
3302
+ {
3303
+ readonly type: 'MoveBlock';
3304
+ readonly node: NodeId;
3305
+ readonly to: Beside;
3306
+ } |
3307
+ /**
3308
+ * Sets the named props of a node block, such as a task item's `checked`, keeping the rest.
3309
+ * It addresses the block by identity, as `MoveBlock` does, so a checkbox sends it for its
3310
+ * own item. Given a vocabulary, props that decode as the kind's must still decode after.
3311
+ */
3312
+ {
3313
+ readonly type: 'SetProps';
3314
+ readonly node: NodeId;
3315
+ readonly props: Schema.JsonObject;
2970
3316
  };
3317
+ /** Where `MoveBlock` puts a block: before or after a sibling, named by identity. */
3318
+ export declare const Beside: Schema.Union<readonly [Schema.Struct<{
3319
+ readonly before: Schema.brand<Schema.NonEmptyString, "foldkit-richtext/NodeId">;
3320
+ readonly after: Schema.optionalKey<Schema.Never>;
3321
+ }>, Schema.Struct<{
3322
+ readonly after: Schema.brand<Schema.NonEmptyString, "foldkit-richtext/NodeId">;
3323
+ readonly before: Schema.optionalKey<Schema.Never>;
3324
+ }>]>;
3325
+ export type Beside = typeof Beside.Type;
3326
+ /** A container a block is wrapped in: a node kind, and the props it starts with. */
3327
+ export declare const Container: Schema.Struct<{
3328
+ readonly kind: Schema.NonEmptyString;
3329
+ readonly props: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
3330
+ }>;
3331
+ export type Container = typeof Container.Type;
2971
3332
  /** Caller-owned identity source. Live edits mint; replay applies transactions. */
2972
3333
  interface CommandIds {
2973
3334
  readonly mint: () => string;
@@ -2975,7 +3336,11 @@ interface CommandIds {
2975
3336
  /** What a command needs beyond state and identity, such as a Kit's mark policy. */
2976
3337
  interface RunOptions {
2977
3338
  readonly marks?: MarkRegistry | undefined;
3339
+ /** The node vocabulary, so an edit a constraint forbids is refused here (§125). */
3340
+ readonly nodes?: NodeRegistry | undefined;
2978
3341
  }
3342
+ /** Whether a selection covers text: a range that is not a caret. What a mark or a link applies to. */
3343
+ export declare const coversText: (selection: Selection | null) => boolean;
2979
3344
  /**
2980
3345
  * The marks every run the selection covers carries: the ones a toggle would
2981
3346
  * remove, which is what an "active" toolbar button means. A caret reports its
@@ -2985,12 +3350,99 @@ interface RunOptions {
2985
3350
  * nothing here changes anything.
2986
3351
  */
2987
3352
  export declare const marksInRange: (document: Document, selection: Selection | null) => ReadonlySet<string>;
3353
+ /** A mark around a caret, and the range of runs it spans. */
3354
+ interface MarkExtent {
3355
+ readonly mark: RunMark;
3356
+ readonly selection: Extract<Selection, {
3357
+ readonly type: 'Range';
3358
+ }>;
3359
+ }
3360
+ /**
3361
+ * The named mark on the run a position is in, and the adjacent runs of its block carrying
3362
+ * the same mark with the same props: the whole link a caret sits in, which is what a link
3363
+ * editor shows and what `SetMark` and `ClearMark` act on at a caret. Undefined when that
3364
+ * run does not carry the mark. A read, like `marksInRange`.
3365
+ */
3366
+ export declare const markExtent: (document: Document, position: Position, name: string) => MarkExtent | undefined;
3367
+ /**
3368
+ * The text style of the block a selection starts in, in the shape `RetypeBlock` takes, so a
3369
+ * style picker compares what it would send with what is there. Undefined for a node
3370
+ * selection, one that resolves to nothing, or a block a retype does not reach, such as a code
3371
+ * block.
3372
+ */
3373
+ export declare const textBlockAt: (document: Document, selection: Selection | null) => TextBlock | undefined;
3374
+ /**
3375
+ * The blocks `node` may move beside, in document order (§149): the blocks of every container it
3376
+ * may move into, which is what a drag offers. Empty when the document does not hold it.
3377
+ */
3378
+ export declare const moveTargets: (document: Document, node: NodeId, nodes?: NodeRegistry) => ReadonlyArray<NodeId>;
3379
+ /**
3380
+ * The blocks a selection starts in, outermost first: a caret in a list item's paragraph gives
3381
+ * the list, the item, and the paragraph. What a block handle picks from, and a breadcrumb draws.
3382
+ * Empty when the selection is null or resolves to nothing.
3383
+ */
3384
+ export declare const blocksAt: (document: Document, selection: Selection | null) => ReadonlyArray<Block>;
2988
3385
  /**
2989
3386
  * Resolves one intent into a transaction and applies it atomically. Commands
2990
3387
  * describe intent; the returned `positionMap` and `ChangeSet` describe the
2991
3388
  * document effect, and rejection returns no partially edited state.
2992
3389
  */
2993
3390
  export declare const run: (state: EditorState, command: Command, ids: CommandIds, options?: RunOptions) => TransactionResult;
3391
+ /** An ordered list of commands that commit as one action (§124 §5). */
3392
+ type Action = ReadonlyArray<Command>;
3393
+ /**
3394
+ * A composed action's invalidation summary is the union of its commands': an identity
3395
+ * one command retired and a later one restored appears in both sets, and a patch reads
3396
+ * that as "remove it, then render it", so it never under-invalidates.
3397
+ */
3398
+ export declare const unionChangeSet: (left: ChangeSet, right: ChangeSet) => ChangeSet;
3399
+ /**
3400
+ * Resolves commands in order and commits them as one action: one resulting state, one
3401
+ * composed ChangeSet, and one identity stream, so a caller can treat "remove the query,
3402
+ * then apply the choice" as a single transition. It stops at the first refusal and
3403
+ * returns that command's error; state is a value, so nothing partial escapes.
3404
+ */
3405
+ export declare const runAction: (state: EditorState, commands: Action, ids: CommandIds, options?: RunOptions) => TransactionResult;
3406
+ //#endregion
3407
+ //#region src/input.d.ts
3408
+ /** What a rule makes of the text before the caret, and what to do about it. */
3409
+ interface InputMatch {
3410
+ /** How many characters of that text the rule consumed; the caller deletes them. */
3411
+ readonly remove: number;
3412
+ readonly commands: Action;
3413
+ }
3414
+ /**
3415
+ * A rule over the text before the caret. `match` is a pure read: it sees the text and the
3416
+ * kinds of the node blocks around the caret's block, innermost first (`['ListItem',
3417
+ * 'List']` inside a bulleted item), and nothing else, so a rule cannot depend on a
3418
+ * selection, a clock, or the Model.
3419
+ */
3420
+ interface InputRule {
3421
+ readonly name: string;
3422
+ readonly match: (textBefore: string, within: ReadonlyArray<string>) => InputMatch | undefined;
3423
+ }
3424
+ /** One edit to read a rule against, named so two strings cannot be handed over swapped. */
3425
+ interface InputContext {
3426
+ /** The caret's block text before the caret, before this insertion. */
3427
+ readonly textBefore: string;
3428
+ /** What was just typed. */
3429
+ readonly text: string;
3430
+ /** The insertion itself, which a matching rule then acts on. */
3431
+ readonly insertion: Command;
3432
+ /** The kinds of the node blocks around the caret's block, innermost first. Default none. */
3433
+ readonly within?: ReadonlyArray<string>;
3434
+ }
3435
+ /**
3436
+ * The commands that insert the text and then let the first matching rule act on it: the
3437
+ * insertion, one backward delete per character the rule consumed, and the rule's commands.
3438
+ * Consumption is by deleting backwards rather than by a range, because a range would have
3439
+ * to be computed against a state the insertion has not produced yet — the deletes resolve
3440
+ * as each one runs. A rule that does not match yields the insertion alone.
3441
+ *
3442
+ * A rule that claims to consume more than it was shown throws: those deletes would run past
3443
+ * the block's start and join it to the one before, which no rule means.
3444
+ */
3445
+ export declare const applyInputRules: (rules: ReadonlyArray<InputRule>, input: InputContext) => Action;
2994
3446
  //#endregion
2995
3447
  //#region src/history.d.ts
2996
3448
  /**
@@ -3758,6 +4210,12 @@ interface ElementRendering {
3758
4210
  readonly tag: string;
3759
4211
  /** Values are escaped when written; a name that would end the markup is refused. */
3760
4212
  readonly attributes: Readonly<Record<string, string>>;
4213
+ /**
4214
+ * An element the nested blocks go inside, where HTML's parser would insert one anyway: a
4215
+ * `table`'s rows go in a `tbody`. Without it, markup sent from a server parses to a tree
4216
+ * the renderer did not write, and Foldkit refuses to serialize it.
4217
+ */
4218
+ readonly inner?: string | undefined;
3761
4219
  }
3762
4220
  /**
3763
4221
  * A rendering entry: fixed data, or computed from the value being rendered, which
@@ -3782,6 +4240,15 @@ export declare const rendering: (definition?: {
3782
4240
  }) => Rendering;
3783
4241
  /** The behaviour without a renderer: shipped tags for shipped marks, names otherwise. */
3784
4242
  export declare const noRendering: Rendering;
4243
+ /**
4244
+ * A registry built over another: an entry named here wins, and every name the base
4245
+ * renders keeps its entry, so an application extends a vocabulary like the standard one
4246
+ * without restating it.
4247
+ */
4248
+ export declare const renderingOver: (base: Rendering, definition?: {
4249
+ readonly marks?: Readonly<Record<string, RenderingEntry<RunMark>>>;
4250
+ readonly nodes?: Readonly<Record<string, RenderingEntry<NodeBlock>>>;
4251
+ }) => Rendering;
3785
4252
  /** What a run's marks nest in, and which names nest nowhere. */
3786
4253
  interface RunRendering {
3787
4254
  /** Elements to wrap the run's text in, innermost first. */
@@ -3825,90 +4292,148 @@ export declare const toText: (blocks: BlockList) => string;
3825
4292
  export declare const documentToHtml: (document: Document, renderer?: Rendering) => string;
3826
4293
  export declare const documentToText: (document: Document) => string;
3827
4294
  //#endregion
3828
- //#region src/kit.d.ts
4295
+ //#region src/decoration.d.ts
3829
4296
  /**
3830
- * The node shapes this version can declare: a `block` is one of the built-in
3831
- * text blocks, an `atom` is an addressable node holding nothing, and an
3832
- * application `node` holds runs or nested blocks plus props its own schema
3833
- * validates (§13).
4297
+ * One decoration over a document range. `kind` is a fixed word the presentation is
4298
+ * chosen by (`search`, `syntax`, `cursor`, …); `data` is the renderer's own payload,
4299
+ * which the core never reads.
3834
4300
  */
3835
- type NodeDefinition = {
3836
- readonly name: string;
3837
- readonly kind: 'block';
3838
- readonly children: 'text';
3839
- } | {
3840
- readonly name: string;
3841
- readonly kind: 'atom';
3842
- readonly children: 'none';
3843
- } | {
3844
- readonly name: string;
3845
- readonly kind: 'node';
3846
- /** `textContent` holds runs; `blockContent` holds nested blocks, as a list needs. */
3847
- readonly children: ContentMode;
3848
- /** Validates a `Node` block's `props` at this boundary, not in the codec. */
3849
- readonly props?: PropsSchema | undefined;
3850
- };
4301
+ interface Decoration<Data = unknown> {
4302
+ readonly from: Position;
4303
+ readonly to: Position;
4304
+ readonly kind: string;
4305
+ readonly data?: Data;
4306
+ }
4307
+ /** A set of decorations is a value, computed for one render and then discarded. */
4308
+ type DecorationSet<Data = unknown> = ReadonlyArray<Decoration<Data>>;
4309
+ /** A decoration's sub-range inside one run, in that run's own offsets. */
4310
+ interface DecorationSpan<Data = unknown> {
4311
+ readonly from: number;
4312
+ readonly to: number;
4313
+ readonly decoration: Decoration<Data>;
4314
+ }
3851
4315
  /**
3852
- * A declared application node, with the caller's name, prop schema, and content
3853
- * mode kept in the type: the erasure to `any` happens only where heterogeneous
3854
- * definitions are collected, not at the authoring call.
4316
+ * The decorations covering each run, as offsets into it, in document order. A decoration
4317
+ * that crosses runs is cut at each run's edge, so a renderer never has to reason about
4318
+ * document order; a decoration whose endpoints do not resolve is skipped rather than
4319
+ * guessed at, the way every other read treats a position it cannot resolve, and a
4320
+ * direction is honoured rather than required to run forwards.
4321
+ *
4322
+ * The runs are indexed once, so a decoration costs the runs it covers: a hundred search
4323
+ * matches over a long document is one walk, not a hundred.
3855
4324
  */
3856
- interface NodeDefinitionOf<Name extends string, Props extends PropsSchema | undefined, Children extends ContentMode = typeof textContent> {
3857
- readonly name: Name;
3858
- readonly kind: 'node';
3859
- readonly children: Children;
3860
- readonly props: Props;
4325
+ export declare const decorationsIn: <Data>(document: Document, set: DecorationSet<Data>) => ReadonlyMap<NodeId, ReadonlyArray<DecorationSpan<Data>>>;
4326
+ /** A stretch of one run's text, and the decorations covering all of it. */
4327
+ interface RunPiece<Data = unknown> {
4328
+ readonly text: string;
4329
+ readonly decorations: ReadonlyArray<Decoration<Data>>;
3861
4330
  }
3862
- /** Declares a block node kind: a top-level node containing text runs. */
3863
- export declare const block: (name: string) => NodeDefinition;
3864
- /** Declares an atom: an addressable node with no text content. */
3865
- export declare const atom: (name: string) => NodeDefinition;
3866
4331
  /**
3867
- * Declares an application node kind: a `Node` block whose props this schema
3868
- * validates and whose content the `children` mode declares. The document codec
3869
- * keeps those props as JSON; the Kit is where an application's types meet them.
4332
+ * A run's text cut at every edge of the spans over it, each piece with the decorations
4333
+ * that cover it — what every interpreter draws, so each draws the same pieces. An empty run,
4334
+ * or one no span touches, is one undecorated piece: an interpreter still has to render
4335
+ * somewhere for a caret to sit, and nothing can be drawn over no text.
3870
4336
  */
3871
- export declare const node: <const Name extends string, Props extends PropsSchema | undefined = undefined, Children extends ContentMode = typeof textContent>(name: Name, options?: {
3872
- readonly Props?: Props;
3873
- readonly children?: Children;
3874
- }) => NodeDefinitionOf<Name, Props, Children>;
4337
+ export declare const runPieces: <Data>(text: string, spans: ReadonlyArray<DecorationSpan<Data>>) => ReadonlyArray<RunPiece<Data>>;
4338
+ //#endregion
4339
+ //#region src/search.d.ts
4340
+ /** The kind a search decoration carries, which is what a stylesheet reaches it by. */
4341
+ export declare const SEARCH_DECORATION = "search";
4342
+ /** Every occurrence of `query` in the document, as decorations a renderer can draw. */
4343
+ export declare const searchDecorations: (document: Document, query: string) => DecorationSet;
4344
+ //#endregion
4345
+ //#region src/code.d.ts
3875
4346
  /**
3876
- * The vocabulary one editor accepts: which node kinds and marks are available.
3877
- * A Kit is a definition, never document state, and it never holds renderers or
3878
- * executable code. Transforms and metadata arrive later.
4347
+ * One token in a code block's text, as offsets into that text. `kind` becomes the
4348
+ * decoration's kind, so it is what a stylesheet reaches the token by — a grammar names its
4349
+ * kinds `syntax-string`, `syntax-number`, and so on (§129).
3879
4350
  */
3880
- interface Kit {
3881
- readonly nodes: ReadonlyArray<NodeDefinition>;
3882
- /** Mark definitions, not just names: a Kit carries each mark's boundary policy. */
3883
- readonly marks: ReadonlyArray<MarkDef>;
4351
+ interface CodeToken {
4352
+ readonly from: number;
4353
+ readonly to: number;
4354
+ readonly kind: string;
3884
4355
  }
3885
- export declare const kit: (definition: {
3886
- readonly nodes: ReadonlyArray<NodeDefinition>;
3887
- readonly marks: ReadonlyArray<MarkDef>;
3888
- }) => Kit;
3889
- interface Diagnostic {
3890
- readonly code: 'UnknownNode' | 'UnsupportedNode' | 'UnknownMark' | 'InvalidProps' | 'MismatchedDefinition';
3891
- readonly message: string;
3892
- readonly node?: NodeId;
3893
- readonly detail?: string;
4356
+ /** A pure read of one code block's text. A tokenizer that needs to load first is Shiki's case. */
4357
+ type CodeTokenizer = (text: string) => ReadonlyArray<CodeToken>;
4358
+ /**
4359
+ * Every token the given tokenizers find in the document's `CodeBlock`s, as decorations. A
4360
+ * block is tokenized by the tokenizer registered for its `language` prop; one with no
4361
+ * language, or one nothing is registered for, yields nothing. The registry is a `Map`
4362
+ * because the language is read from the document, and a plain object would answer a
4363
+ * language named `constructor` from its prototype.
4364
+ *
4365
+ * A token outside its block's text, one that covers nothing, or one at a fractional offset
4366
+ * throws with the language that produced it: it is a tokenizer's bug, and a decoration guessed from it would
4367
+ * highlight the wrong text.
4368
+ */
4369
+ export declare const codeDecorations: (document: Document, tokenizers: ReadonlyMap<string, CodeTokenizer>) => DecorationSet;
4370
+ //#endregion
4371
+ //#region src/url.d.ts
4372
+ /**
4373
+ * The URL policy every importer shares (§70, §124 §10). A link's `href` and an image's `src`
4374
+ * arrive from pasted HTML or Markdown, which is untrusted, and the standard rendering writes
4375
+ * them into attributes, so each passes here before it can become a prop, and again before
4376
+ * the standard rendering writes it.
4377
+ */
4378
+ /**
4379
+ * A URL safe to carry into props, or `undefined` when it is not. Control characters are
4380
+ * removed first, because `java\tscript:` and a leading NUL are how a scheme check is
4381
+ * usually walked past; then a URL that names a scheme outside the allowlist is refused,
4382
+ * and one with no scheme — a relative path, a fragment, a protocol-relative URL — is
4383
+ * kept. The value is never interpreted, only copied, so what a policy leaves through is
4384
+ * still the application's to trust.
4385
+ */
4386
+ export declare const safeUrl: (value: string | null) => string | undefined;
4387
+ //#endregion
4388
+ //#region src/standard.d.ts
4389
+ /**
4390
+ * A struck-through span. It expands `after`, so typing at its edge continues it, as
4391
+ * bold and italic do.
4392
+ */
4393
+ export declare const Strikethrough: MarkDef<undefined>;
4394
+ /**
4395
+ * A hyperlink. Its `href` is a prop rather than a mark name, which is what lets the
4396
+ * serializer render a real `<a href>` (§121); it expands `none`, because text typed
4397
+ * after a link is new text, not a continuation of the link.
4398
+ */
4399
+ export declare const Link: MarkDef<Schema.Struct<{
4400
+ readonly href: Schema.String;
4401
+ }>>;
4402
+ /** The link a selection starts in: its `href`, and the range of runs it spans. */
4403
+ interface LinkAt {
4404
+ /** The stored `href`, or `''` when the stored one is not a string. */
4405
+ readonly href: string;
4406
+ readonly selection: Extract<Selection, {
4407
+ readonly type: 'Range';
4408
+ }>;
3894
4409
  }
3895
- /** Structural summary of a Kit, for tooling and tests. */
3896
- export declare const inspectKit: (definition: Kit) => {
3897
- blocks: number;
3898
- atoms: number;
3899
- nodes: number;
3900
- marks: number;
3901
- };
3902
4410
  /**
3903
- * Checks a document against a Kit's vocabulary without changing it, walking
3904
- * nested blocks so a container's children are checked too. Reports preserved
3905
- * unknown blocks, known blocks the Kit does not declare, declarations that
3906
- * disagree with how the document holds a block, application nodes whose props
3907
- * their schema refuses, and marks outside the Kit or whose props their definition
3908
- * refuses. Content diagnostics never strip or repair the document; callers decide
3909
- * whether to block publishing or surface a placeholder.
4411
+ * The link a selection starts in, which is what a link editor opens on: at a caret, the
4412
+ * link around it; over a range, the link its start is in. Undefined outside a link, and for
4413
+ * a node selection, which covers blocks rather than text.
3910
4414
  */
3911
- export declare const validate: (document: Document, definition: Kit) => ReadonlyArray<Diagnostic>;
4415
+ export declare const linkAt: (document: Document, selection: Selection | null) => LinkAt | undefined;
4416
+ /** Every mark the standard vocabulary names, in menu order. */
4417
+ export declare const standardMarks: ReadonlyArray<MarkDef>;
4418
+ /**
4419
+ * The standard node kinds. Constraints are what make a kind more than a name: a
4420
+ * `List` accepts only `ListItem`s and a `Table` only `TableRow`s, so `validate`
4421
+ * reports a document that says otherwise (§125); a `CodeBlock` carries text with no
4422
+ * formatting, and its `language` is a prop, not a mark.
4423
+ */
4424
+ export declare const standardNodes: ReadonlyArray<NodeDefinition>;
4425
+ /**
4426
+ * How the standard vocabulary renders (§121): the element each kind is, with the props
4427
+ * that belong in attributes read from the block, so a `Link` is an `<a href>`, an `Image`
4428
+ * carries its source, and a `List` is an `<ol>` or a `<ul>`. The shipped marks already
4429
+ * nest in `strong`/`em`/`code`; this adds the two that do not. An application composes it
4430
+ * with `renderingOver` and names its own kinds beside it:
4431
+ *
4432
+ * ```ts
4433
+ * renderingOver(RichText.standardRendering, { nodes: { Callout: { tag: 'aside' } } })
4434
+ * ```
4435
+ */
4436
+ export declare const standardRendering: Rendering;
3912
4437
  //#endregion
3913
4438
  //#region src/migration.d.ts
3914
4439
  /**
@@ -3963,6 +4488,345 @@ export declare const migrate: (document: Document, migrations: ReadonlyArray<Mig
3963
4488
  export declare const promoteUnknown: (name: string, from: string, to: string, Props: Schema.Codec<any, any, never>, children?: ContentMode) => Migration;
3964
4489
  /** A node block's props as the codec stores them: plain JSON, nothing more. */
3965
4490
  export declare const nodeProps: (block: NodeBlock) => Readonly<Record<string, unknown>>;
4491
+ declare namespace replicated_d_exports {
4492
+ export { AnchoredPosition, AnchoredSelection, BlockShape, CharRange, CharRef, ReplicatedId, ReplicatedOp, ReplicatedState, anchor, applyOps, coalesce, empty, fromDocument, invert, project, resolve, translate };
4493
+ }
4494
+ /**
4495
+ * A document shared by several replicas, where every character has an identity that
4496
+ * outlives the edits around it.
4497
+ *
4498
+ * The editor keeps working on a plain `Document`: `project` derives one from this state.
4499
+ * An edit runs as an ordinary command against that projection, `translate` restates the
4500
+ * transactions it applied as `ReplicatedOp`s that name characters and blocks rather than
4501
+ * offsets and indices, and `applyOps` folds those ops into the state. Replicas converge
4502
+ * because a server gives every op one order and `applyOps` is a deterministic, total
4503
+ * function of the state and the ops: it never throws.
4504
+ */
4505
+ /**
4506
+ * An identity this state minted: segments joined by `:`, at least two of them. The colon
4507
+ * keeps an id from ever naming an `Object.prototype` key, which is why the block record is
4508
+ * indexed directly, and the absent `.` is what separates an id from a character reference
4509
+ * built on it.
4510
+ */
4511
+ declare const ReplicatedId: Schema.brand<Schema.String, "foldkit-richtext/ReplicatedId">;
4512
+ type ReplicatedId = typeof ReplicatedId.Type;
4513
+ /** A character: the insert that created it, and its index within that insert's text. */
4514
+ declare const CharRef: Schema.brand<Schema.String, "foldkit-richtext/CharRef">;
4515
+ type CharRef = typeof CharRef.Type;
4516
+ /** Characters `from` up to, not including, `to` of one insert. */
4517
+ declare const CharRange: Schema.Struct<{
4518
+ readonly id: Schema.brand<Schema.String, "foldkit-richtext/ReplicatedId">;
4519
+ readonly from: Schema.Number;
4520
+ readonly to: Schema.Number;
4521
+ }>;
4522
+ type CharRange = typeof CharRange.Type;
4523
+ /** What a block is, apart from its content and place. */
4524
+ declare const BlockShape: Schema.Union<readonly [Schema.Struct<{
4525
+ readonly type: Schema.Literal<"Paragraph">;
4526
+ }>, Schema.Struct<{
4527
+ readonly type: Schema.Literal<"Heading">;
4528
+ readonly level: Schema.Literals<readonly [1, 2, 3, 4, 5, 6]>;
4529
+ }>, Schema.Struct<{
4530
+ readonly type: Schema.Literal<"Node">;
4531
+ readonly kind: Schema.NonEmptyString;
4532
+ readonly props: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
4533
+ /** What the node holds: runs, nested blocks, or nothing (an atom such as an image). */
4534
+ readonly holds: Schema.Literals<readonly ["text", "blocks", "none"]>;
4535
+ }>, Schema.Struct<{
4536
+ readonly type: Schema.Literal<"Unknown">;
4537
+ readonly originalType: Schema.NonEmptyString;
4538
+ readonly props: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
4539
+ }>]>;
4540
+ type BlockShape = typeof BlockShape.Type;
4541
+ declare const ReplicatedState: Schema.Struct<{
4542
+ readonly version: Schema.Literal<1>;
4543
+ readonly root: Schema.$Array<Schema.brand<Schema.String, "foldkit-richtext/ReplicatedId">>;
4544
+ readonly blocks: Schema.$Record<Schema.brand<Schema.String, "foldkit-richtext/ReplicatedId">, Schema.Struct<{
4545
+ readonly shape: Schema.Union<readonly [Schema.Struct<{
4546
+ readonly type: Schema.Literal<"Paragraph">;
4547
+ }>, Schema.Struct<{
4548
+ readonly type: Schema.Literal<"Heading">;
4549
+ readonly level: Schema.Literals<readonly [1, 2, 3, 4, 5, 6]>;
4550
+ }>, Schema.Struct<{
4551
+ readonly type: Schema.Literal<"Node">;
4552
+ readonly kind: Schema.NonEmptyString;
4553
+ readonly props: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
4554
+ /** What the node holds: runs, nested blocks, or nothing (an atom such as an image). */
4555
+ readonly holds: Schema.Literals<readonly ["text", "blocks", "none"]>;
4556
+ }>, Schema.Struct<{
4557
+ readonly type: Schema.Literal<"Unknown">;
4558
+ readonly originalType: Schema.NonEmptyString;
4559
+ readonly props: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
4560
+ }>]>;
4561
+ readonly parent: Schema.NullOr<Schema.brand<Schema.String, "foldkit-richtext/ReplicatedId">>;
4562
+ readonly spans: Schema.$Array<Schema.Struct<{
4563
+ readonly id: Schema.brand<Schema.String, "foldkit-richtext/ReplicatedId">;
4564
+ readonly offset: Schema.Number;
4565
+ readonly text: Schema.NonEmptyString;
4566
+ readonly marks: Schema.$Array<Schema.Union<readonly [Schema.NonEmptyString, Schema.Struct<{
4567
+ readonly name: Schema.NonEmptyString;
4568
+ readonly props: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
4569
+ }>]>>;
4570
+ readonly deleted: Schema.Boolean;
4571
+ /** Deleted when a `Collect` ran, so the next one removes it. */
4572
+ readonly swept: Schema.optionalKey<Schema.Boolean>;
4573
+ /**
4574
+ * The last character of a collected stretch, kept only so its insert's indexes are never
4575
+ * reused. It is never shown again, not even by an undo.
4576
+ */
4577
+ readonly kept: Schema.optionalKey<Schema.Literal<true>>;
4578
+ }>>;
4579
+ /** Nested blocks in order, deleted ones included, so a sibling anchor still resolves. */
4580
+ readonly children: Schema.$Array<Schema.brand<Schema.String, "foldkit-richtext/ReplicatedId">>;
4581
+ readonly deleted: Schema.Boolean;
4582
+ /** Deleted when a `Collect` ran, so the next one removes the text it holds. */
4583
+ readonly swept: Schema.optionalKey<Schema.Boolean>;
4584
+ /** Where a joined block's start now is: after this character of `into`, or its start. */
4585
+ readonly joined: Schema.optionalKey<Schema.Struct<{
4586
+ readonly into: Schema.brand<Schema.String, "foldkit-richtext/ReplicatedId">;
4587
+ readonly after: Schema.NullOr<Schema.brand<Schema.String, "foldkit-richtext/CharRef">>;
4588
+ }>>;
4589
+ }>>;
4590
+ }>;
4591
+ type ReplicatedState = typeof ReplicatedState.Type;
4592
+ /**
4593
+ * One change, naming what it touches by identity. Inserts and splits anchor after a
4594
+ * character, or at a block's start when `after` is null; block ops anchor after a sibling,
4595
+ * or at the start of the container when `after` is null.
4596
+ */
4597
+ declare const ReplicatedOp: Schema.Union<readonly [Schema.Struct<{
4598
+ readonly type: Schema.Literal<"Insert">;
4599
+ readonly id: Schema.brand<Schema.String, "foldkit-richtext/ReplicatedId">;
4600
+ /** The block the anchor was in when the op was made: where a lost anchor falls back to. */
4601
+ readonly block: Schema.brand<Schema.String, "foldkit-richtext/ReplicatedId">;
4602
+ readonly after: Schema.NullOr<Schema.brand<Schema.String, "foldkit-richtext/CharRef">>;
4603
+ readonly text: Schema.NonEmptyString;
4604
+ readonly marks: Schema.$Array<Schema.Union<readonly [Schema.NonEmptyString, Schema.Struct<{
4605
+ readonly name: Schema.NonEmptyString;
4606
+ readonly props: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
4607
+ }>]>>;
4608
+ /**
4609
+ * The index of its first character, when it continues an insert of the same id rather
4610
+ * than starting one: `id.from` onwards. Absent means 0.
4611
+ */
4612
+ readonly from: Schema.optionalKey<Schema.Number>;
4613
+ }>, Schema.Struct<{
4614
+ readonly type: Schema.Literal<"Delete">;
4615
+ readonly ranges: Schema.$Array<Schema.Struct<{
4616
+ readonly id: Schema.brand<Schema.String, "foldkit-richtext/ReplicatedId">;
4617
+ readonly from: Schema.Number;
4618
+ readonly to: Schema.Number;
4619
+ }>>;
4620
+ }>, Schema.Struct<{
4621
+ readonly type: Schema.Literal<"Mark">;
4622
+ readonly ranges: Schema.$Array<Schema.Struct<{
4623
+ readonly id: Schema.brand<Schema.String, "foldkit-richtext/ReplicatedId">;
4624
+ readonly from: Schema.Number;
4625
+ readonly to: Schema.Number;
4626
+ }>>;
4627
+ readonly mark: Schema.Union<readonly [Schema.NonEmptyString, Schema.Struct<{
4628
+ readonly name: Schema.NonEmptyString;
4629
+ readonly props: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
4630
+ }>]>;
4631
+ }>, Schema.Struct<{
4632
+ readonly type: Schema.Literal<"Unmark">;
4633
+ readonly ranges: Schema.$Array<Schema.Struct<{
4634
+ readonly id: Schema.brand<Schema.String, "foldkit-richtext/ReplicatedId">;
4635
+ readonly from: Schema.Number;
4636
+ readonly to: Schema.Number;
4637
+ }>>;
4638
+ readonly name: Schema.NonEmptyString;
4639
+ }>, Schema.Struct<{
4640
+ readonly type: Schema.Literal<"InsertBlock">;
4641
+ readonly id: Schema.brand<Schema.String, "foldkit-richtext/ReplicatedId">;
4642
+ readonly shape: Schema.Union<readonly [Schema.Struct<{
4643
+ readonly type: Schema.Literal<"Paragraph">;
4644
+ }>, Schema.Struct<{
4645
+ readonly type: Schema.Literal<"Heading">;
4646
+ readonly level: Schema.Literals<readonly [1, 2, 3, 4, 5, 6]>;
4647
+ }>, Schema.Struct<{
4648
+ readonly type: Schema.Literal<"Node">;
4649
+ readonly kind: Schema.NonEmptyString;
4650
+ readonly props: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
4651
+ /** What the node holds: runs, nested blocks, or nothing (an atom such as an image). */
4652
+ readonly holds: Schema.Literals<readonly ["text", "blocks", "none"]>;
4653
+ }>, Schema.Struct<{
4654
+ readonly type: Schema.Literal<"Unknown">;
4655
+ readonly originalType: Schema.NonEmptyString;
4656
+ readonly props: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
4657
+ }>]>;
4658
+ readonly parent: Schema.NullOr<Schema.brand<Schema.String, "foldkit-richtext/ReplicatedId">>;
4659
+ readonly after: Schema.NullOr<Schema.brand<Schema.String, "foldkit-richtext/ReplicatedId">>;
4660
+ }>, Schema.Struct<{
4661
+ readonly type: Schema.Literal<"DeleteBlock">;
4662
+ readonly id: Schema.brand<Schema.String, "foldkit-richtext/ReplicatedId">;
4663
+ }>, Schema.Struct<{
4664
+ readonly type: Schema.Literal<"MoveBlock">;
4665
+ readonly id: Schema.brand<Schema.String, "foldkit-richtext/ReplicatedId">;
4666
+ readonly parent: Schema.NullOr<Schema.brand<Schema.String, "foldkit-richtext/ReplicatedId">>;
4667
+ readonly after: Schema.NullOr<Schema.brand<Schema.String, "foldkit-richtext/ReplicatedId">>;
4668
+ }>, Schema.Struct<{
4669
+ readonly type: Schema.Literal<"Split">;
4670
+ readonly block: Schema.brand<Schema.String, "foldkit-richtext/ReplicatedId">;
4671
+ readonly after: Schema.NullOr<Schema.brand<Schema.String, "foldkit-richtext/CharRef">>;
4672
+ readonly into: Schema.brand<Schema.String, "foldkit-richtext/ReplicatedId">;
4673
+ }>, Schema.Struct<{
4674
+ readonly type: Schema.Literal<"Join">;
4675
+ readonly into: Schema.brand<Schema.String, "foldkit-richtext/ReplicatedId">;
4676
+ readonly removed: Schema.brand<Schema.String, "foldkit-richtext/ReplicatedId">;
4677
+ /**
4678
+ * The last character of `into` when the op was made, or null when it had none: the
4679
+ * removed block's text goes right after it, wherever it has gone since, so a join still
4680
+ * lands where it was made after `into` is split or joined itself.
4681
+ */
4682
+ readonly after: Schema.NullOr<Schema.brand<Schema.String, "foldkit-richtext/CharRef">>;
4683
+ /**
4684
+ * `'end'` puts the text at the end of the block holding `after` (of `into` when null) as
4685
+ * that block is when the join applies, so text typed at its end since stays before it.
4686
+ * Only undo makes it: rejoining halves someone has typed into since.
4687
+ */
4688
+ readonly at: Schema.optionalKey<Schema.Literal<"end">>;
4689
+ }>, Schema.Struct<{
4690
+ readonly type: Schema.Literal<"Retype">;
4691
+ readonly id: Schema.brand<Schema.String, "foldkit-richtext/ReplicatedId">;
4692
+ readonly to: Schema.Union<readonly [Schema.Struct<{
4693
+ readonly type: Schema.Literal<"Paragraph">;
4694
+ }>, Schema.Struct<{
4695
+ readonly type: Schema.Literal<"Heading">;
4696
+ readonly level: Schema.Literals<readonly [1, 2, 3, 4, 5, 6]>;
4697
+ }>, Schema.Struct<{
4698
+ readonly type: Schema.Literal<"Node">;
4699
+ readonly kind: Schema.NonEmptyString;
4700
+ readonly props: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
4701
+ }>]>;
4702
+ }>, Schema.Struct<{
4703
+ readonly type: Schema.Literal<"SetProps">;
4704
+ readonly id: Schema.brand<Schema.String, "foldkit-richtext/ReplicatedId">;
4705
+ readonly props: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
4706
+ }>, Schema.Struct<{
4707
+ readonly type: Schema.Literal<"Undelete">;
4708
+ readonly ranges: Schema.$Array<Schema.Struct<{
4709
+ readonly id: Schema.brand<Schema.String, "foldkit-richtext/ReplicatedId">;
4710
+ readonly from: Schema.Number;
4711
+ readonly to: Schema.Number;
4712
+ }>>;
4713
+ }>, Schema.Struct<{
4714
+ readonly type: Schema.Literal<"UndeleteBlock">;
4715
+ readonly id: Schema.brand<Schema.String, "foldkit-richtext/ReplicatedId">;
4716
+ }>, Schema.Struct<{
4717
+ readonly type: Schema.Literal<"Unjoin">;
4718
+ /** The block a join removed, restored where it stood. */
4719
+ readonly id: Schema.brand<Schema.String, "foldkit-richtext/ReplicatedId">;
4720
+ /** The characters it held, taken back from wherever they are now. */
4721
+ readonly ranges: Schema.$Array<Schema.Struct<{
4722
+ readonly id: Schema.brand<Schema.String, "foldkit-richtext/ReplicatedId">;
4723
+ readonly from: Schema.Number;
4724
+ readonly to: Schema.Number;
4725
+ }>>;
4726
+ /** The nested blocks it held, taken back from the container they were joined into. */
4727
+ readonly children: Schema.$Array<Schema.brand<Schema.String, "foldkit-richtext/ReplicatedId">>;
4728
+ }>, Schema.Struct<{
4729
+ readonly type: Schema.Literal<"Collect">;
4730
+ }>]>;
4731
+ type ReplicatedOp = typeof ReplicatedOp.Type;
4732
+ declare const empty: ReplicatedState;
4733
+ /**
4734
+ * Folds ops into the state in order. Total: an op whose target is gone, whose ids are
4735
+ * already taken, or that would make the tree cyclic changes nothing, and an insert or split
4736
+ * anchored on a character that is gone (never arrived, or collected) lands at the end of the
4737
+ * block it names, or of the block that one was joined into. It trusts the
4738
+ * state to be one these functions made (the ops are the untrusted input): a state decoded
4739
+ * from elsewhere is not checked for a block listed twice or a cycle of parents.
4740
+ *
4741
+ * The same ops on the same state give back the same state object, so the edit that made
4742
+ * the ops and the durable Message that replays them agree on identity, and whatever is
4743
+ * derived from it (`project`, an editor host's key) is derived once. The ops array is
4744
+ * remembered by identity, so do not change one after applying it.
4745
+ */
4746
+ declare const applyOps: (state: ReplicatedState, ops: ReadonlyArray<ReplicatedOp>) => ReplicatedState;
4747
+ /**
4748
+ * The same ops with each insert that continues the one right before it folded into that one:
4749
+ * a run of typing `translate` carried on as one insert becomes one op again. For ops
4750
+ * `translate` made, which never reuse a character, applying the result shows what applying
4751
+ * `ops` does.
4752
+ */
4753
+ declare const coalesce: (ops: ReadonlyArray<ReplicatedOp>) => ReadonlyArray<ReplicatedOp>;
4754
+ /**
4755
+ * The ops that undo `ops`, made against `state`, the state `ops` were applied to. Applied
4756
+ * after `ops` and after whatever else has happened since, they take back what `ops` did
4757
+ * and leave the rest alone. Characters it inserted are deleted, and characters it deleted
4758
+ * come back. Marks, block types and props return to what they were, a split is joined and
4759
+ * a join split out, and a moved block goes back beside the sibling it followed. A prop it
4760
+ * added where there was none stays, since `SetProps` cannot delete one. Inverting the
4761
+ * result gives the ops that redo it.
4762
+ */
4763
+ declare const invert: (state: ReplicatedState, ops: ReadonlyArray<ReplicatedOp>) => ReadonlyArray<ReplicatedOp>;
4764
+ /** The document a state shows: visible blocks and characters, with runs merged by marks. */
4765
+ declare const project: (state: ReplicatedState) => Document;
4766
+ /**
4767
+ * A state that shows `document`, with every block and character given a new identity
4768
+ * under `key`, which must be unique among the keys this state's ops are minted under.
4769
+ */
4770
+ declare const fromDocument: (document: Document, key: string) => ReplicatedState;
4771
+ /** A caret or selection end held by what it sits after, so it survives others' edits. */
4772
+ declare const AnchoredPosition: Schema.Struct<{
4773
+ readonly block: Schema.brand<Schema.String, "foldkit-richtext/ReplicatedId">;
4774
+ /** The character just before the position, or null at the block's start. */
4775
+ readonly after: Schema.NullOr<Schema.brand<Schema.String, "foldkit-richtext/CharRef">>;
4776
+ readonly affinity: Schema.Literals<readonly ["before", "after"]>;
4777
+ }>;
4778
+ type AnchoredPosition = typeof AnchoredPosition.Type;
4779
+ declare const AnchoredSelection: Schema.Union<readonly [Schema.Struct<{
4780
+ readonly type: Schema.Literal<"Range">;
4781
+ readonly anchor: Schema.Struct<{
4782
+ readonly block: Schema.brand<Schema.String, "foldkit-richtext/ReplicatedId">;
4783
+ /** The character just before the position, or null at the block's start. */
4784
+ readonly after: Schema.NullOr<Schema.brand<Schema.String, "foldkit-richtext/CharRef">>;
4785
+ readonly affinity: Schema.Literals<readonly ["before", "after"]>;
4786
+ }>;
4787
+ readonly focus: Schema.Struct<{
4788
+ readonly block: Schema.brand<Schema.String, "foldkit-richtext/ReplicatedId">;
4789
+ /** The character just before the position, or null at the block's start. */
4790
+ readonly after: Schema.NullOr<Schema.brand<Schema.String, "foldkit-richtext/CharRef">>;
4791
+ readonly affinity: Schema.Literals<readonly ["before", "after"]>;
4792
+ }>;
4793
+ }>, Schema.Struct<{
4794
+ readonly type: Schema.Literal<"Node">;
4795
+ readonly node: Schema.brand<Schema.String, "foldkit-richtext/ReplicatedId">;
4796
+ }>]>;
4797
+ type AnchoredSelection = typeof AnchoredSelection.Type;
4798
+ /**
4799
+ * Restates an edit's transactions as ops against `state`, which the edit ran on the
4800
+ * projection of. `key` must be unique to this edit among everything the state has seen: it
4801
+ * names the edit's new characters and blocks. Also anchors the edit's resulting selection.
4802
+ * Throws if the transactions do not apply to the projection, which is a caller's bug. The
4803
+ * transactions are replayed with `apply`'s default transforms, as `RichText.run` applies
4804
+ * them; an edit normalized by other transforms does not translate.
4805
+ *
4806
+ * Text typed right after the last character of an insert `continues` accepts carries on that
4807
+ * insert (`from` its next index) instead of starting one, so `coalesce` can fold a run of
4808
+ * typing into one op. Accept only inserts this replica minted: two replicas continuing one
4809
+ * insert at once would both claim its next characters, and the later would be dropped.
4810
+ */
4811
+ declare const translate: (state: ReplicatedState, result: Pick<Extract<TransactionResult, {
4812
+ readonly ok: true;
4813
+ }>, "transactions" | "state">, key: string, options?: {
4814
+ readonly continues?: (id: ReplicatedId) => boolean;
4815
+ }) => {
4816
+ readonly ops: ReadonlyArray<ReplicatedOp>;
4817
+ readonly selection: AnchoredSelection | null;
4818
+ };
4819
+ /**
4820
+ * Anchors a selection on the projection of `state`, so it can be resolved again after
4821
+ * other replicas' ops change the text around it.
4822
+ */
4823
+ declare const anchor: (state: ReplicatedState, selection: Selection | null) => AnchoredSelection | null;
4824
+ /**
4825
+ * The selection an anchored one names in the projection of `state`. A position whose
4826
+ * character was deleted moves back to the nearest character still shown; one whose block
4827
+ * is gone resolves to nothing, and so does the selection.
4828
+ */
4829
+ declare const resolve: (state: ReplicatedState, selection: AnchoredSelection | null) => Selection | null;
3966
4830
  //#endregion
3967
- export type { BlockList, BlockPath, ChangeSet, CollapseStep, Command, CommandIds, CommitOptions, ContentMode, Diagnostic, ElementRendering, Kit, LocatedRun, MarkDef, MarkExpansion, MarkRegistry, Migration, MigrationApplied, MigrationReport, NodeDefinition, NodeDefinitionOf, NodeReference, PositionStep, RelocateStep, Rendering, RenderingEntry, Restore, RunOptions, RunPlace, RunRendering, SplitStep, TextTarget, TransactionResult, Transform, TransformContext, TransformReport, UnknownMark, UnknownNode };
4831
+ export { type Action, type BlockConstraint, type BlockList, type BlockPath, type ChangeSet, type ChildrenDeclaration, type CodeToken, type CodeTokenizer, type CollapseStep, type Command, type CommandIds, type CommitOptions, type ContentMode, type Decoration, type DecorationSet, type DecorationSpan, type Diagnostic, type ElementRendering, type InputContext, type InputMatch, type InputRule, type Kit, type LinkAt, type LocatedRun, type MarkDef, type MarkExpansion, type MarkExtent, type MarkRegistry, type MarksPolicy, type Migration, type MigrationApplied, type MigrationReport, type NodeDefinition, type NodeDefinitionOf, type NodeReference, type NodeRegistry, type PositionStep, type RelocateStep, type Rendering, type RenderingEntry, replicated_d_exports as Replicated, type Restore, type RunOptions, type RunPiece, type RunPlace, type RunRendering, type SplitStep, type TextTarget, type TransactionResult, type Transform, type TransformContext, type TransformReport, type UnknownMark, type UnknownNode };
3968
4832
  //# sourceMappingURL=index.d.mts.map