foldkit-richtext 0.2.0 → 0.4.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/README.md CHANGED
@@ -114,8 +114,8 @@ RichText.run(state, { type: 'RetypeBlock', to: { type: 'Heading', level: 2 } },
114
114
 
115
115
  `InsertText`, `DeleteBackward`, `DeleteForward`, `SplitBlock`, `ToggleMark`, `SetMark`,
116
116
  `ClearMark`, `SetSelection`, `Paste`, and the block commands below (`RetypeBlock`,
117
- `WrapBlock`, `ConvertBlock`, `RetypeContainer`, `LiftBlock`) read the current selection; `MoveBlock` and `SetProps` name their
118
- blocks instead. Each resolves to transactions applied as one step, usually one (Enter over
117
+ `WrapBlock`, `ConvertBlock`, `RetypeContainer`, `LiftBlock`) read the current selection; `MoveBlock`,
118
+ `SetProps`, `InsertBlock` and `DeleteBlock` name their blocks instead. Each resolves to transactions applied as one step, usually one (Enter over
119
119
  a range in a list item is two: the delete, then the split); the returned `ChangeSet` and
120
120
  `positionMap` describe the effect, and `transactions` holds what was applied, in order, an
121
121
  empty one for a command that changed nothing. Nothing mints
@@ -141,7 +141,7 @@ interface InputRule {
141
141
  match: (
142
142
  textBefore: string,
143
143
  within: ReadonlyArray<string>,
144
- ) => { remove: number; commands: Action } | undefined
144
+ ) => { remove: number; commands: Action; storedMarks?: ReadonlyArray<string> } | undefined
145
145
  }
146
146
  ```
147
147
 
@@ -158,6 +158,10 @@ claims to consume more than the text it was shown throws, because those deletes
158
158
  past the block's start and join it to the one before. `textBefore` for a selection that is
159
159
  a range is read from `rangeStart(document, range)` — the end that comes first, whichever
160
160
  way the range was made — since that is where what is typed over it lands.
161
+ `resolveInputRules` returns the same action with the matching rule's `storedMarks`: the marks
162
+ the text typed next carries, which an editor keeps, so `**bold**` closed as typed ends its bold
163
+ rather than letting the bold run continue. A delete removes a whole grapheme, so `remove` counts
164
+ graphemes.
161
165
 
162
166
  `RetypeBlock` changes the type of the block the selection starts in — `Paragraph`, or
163
167
  a `Heading` at a level — and keeps that block's runs, so identities and the caret
@@ -225,12 +229,53 @@ vocabulary, props that decode as the kind declares them must still decode after,
225
229
  command is refused with `InvalidInput`, as it is for a block that is not a node. Props that
226
230
  already fail (a key an older version wrote, which cannot be deleted) can still be changed.
227
231
 
232
+ `InsertBlock` puts a block, with everything it holds, beside another:
233
+ `{ type: 'InsertBlock', block, to: { after: other } }`. Its identities are minted afresh, so
234
+ the same block value can be inserted twice (a handle's Duplicate sends the block it stands for).
235
+ Without `to` it goes beside the caret's block: before it when that block is empty, so a slash
236
+ command typed on a blank line leaves the line below to type on, and after it otherwise. The
237
+ caret moves to the start of its first text, when it has any. With a vocabulary, the container
238
+ has to hold the kind and the kind has to stand there, as for a move (`UnexpectedChild`).
239
+
240
+ `DeleteBlock` deletes a block and everything it holds: `{ type: 'DeleteBlock', node }`. A
241
+ container it leaves empty goes with it, as a move's does. A caret inside it moves to the start of
242
+ the text after it, or the end of the text before; a document it would empty gets an empty
243
+ paragraph, so there is always somewhere to type.
244
+
245
+ A table is edited as a grid from the cell the caret is in (`tableAt(document, selection)` reads
246
+ which: the table, its rows, the row and the column). `InsertRow` and `InsertColumn` (`{ where:
247
+ 'before' | 'after' }`) add a row as wide as the widest, or a cell beside the caret's in every row,
248
+ at the end of a row too short for that column; `DeleteRow` and `DeleteColumn` remove them, a row a
249
+ column empties with it, and the last row or column takes the table. The caret goes to the new
250
+ cell, or to its neighbour. Each is one transaction, so one undo step, and each is refused outside
251
+ a table (`InvalidSelection`).
252
+
253
+ `Indent` and `Outdent` are Tab and Shift+Tab. In a kind declared `indents` (code) they add or
254
+ remove a level of indentation (`INDENT`, two spaces): at the caret, or at the start of every line
255
+ a range covers; Enter there starts the new line as indented as the one it broke. In a table cell
256
+ they move the caret to the next or previous cell, and Tab in the last cell adds a row. In a list
257
+ item, Tab nests it under the item before it (in the list that item ends with, or a new one of its
258
+ own kind), and Shift+Tab moves a nested item out to follow its parent item, or takes a top-level
259
+ item out of its list; the first item has nothing to nest under and stays. The innermost wins: code
260
+ in a cell indents, a list in a cell nests. Anywhere else they are refused, and `takesTab(document, selection, nodes)` says so
261
+ beforehand, which is how an editor leaves Tab to move focus there.
262
+
228
263
  `DeleteBackward` at the start of a container's first block used to do nothing, having no
229
264
  sibling to join. With a vocabulary it now lifts the block, which is how Backspace undoes a
230
265
  `> ` or `- ` typed at a block's start. Without a vocabulary, in a table cell, and forwards, the
231
266
  edge still does nothing. At the start of a kind the vocabulary declares as holding text, such
232
267
  as a `CodeBlock`, Backspace retypes it to a paragraph instead of joining it to the block
233
- above, which undoes a fence the way a lift undoes a list marker.
268
+ above, which undoes a fence the way a lift undoes a list marker. A heading does the same with
269
+ or without a vocabulary, undoing its `# `; a second press joins it.
270
+
271
+ Beside a block it cannot be joined with, Backspace and Delete reach the nearest line on that
272
+ side. Inside a list or a quote that is its last or first line, which the line at the caret
273
+ joins, as clearing the empty range between them would; Delete at the end of a list item's last
274
+ line reaches the next item's in the same way. A table cell or code cannot take the line, so
275
+ there Backspace only moves the caret in, and Delete beside a line with text does nothing. An
276
+ empty line goes, the caret stepping into its neighbour, rather than taking a line out of a
277
+ list. An image or a divider reached this way is selected. Each was refused (`InvalidRange`),
278
+ which left an empty line after a table that nothing could remove.
234
279
 
235
280
  `SplitBlock` at the end of a heading starts a paragraph under it, since what follows a title is
236
281
  text; in the middle of one, both halves stay headings. Over a selection, the range's end
@@ -259,7 +304,8 @@ decides what the caret carries and passes it back on the next `InsertText`.
259
304
 
260
305
  A toggle can take a link off but cannot change where it points. `SetMark` puts exactly
261
306
  the given mark on every run a range covers, replacing the props of a same-named mark,
262
- and `ClearMark` takes a mark off by name. At a caret both act on the mark's extent
307
+ and `ClearMark` takes a mark off by name, or, given a mark value, off only the runs carrying
308
+ exactly that value (one discussion's highlight, leaving another's inside it). At a caret both act on the mark's extent
263
309
  around it, so an editor changes or removes the link the caret sits in without selecting
264
310
  it first; outside a mark they do nothing. `markExtent(document, position, name)` is that
265
311
  extent as a read: the mark, and the range of adjacent runs carrying it with the same
@@ -345,7 +391,10 @@ The shipped policy is `Bold`/`Italic` → `after`, `Code` → `none`, and a mark
345
391
  registry declares → `both` (so preservation never retargets an unknown mark
346
392
  away). `resolveInsertion` retargets a boundary insertion when the current run
347
393
  carries marks that forbid the edge and the neighbor carries exactly the marks
348
- that remain; a registry changes which marks those are, not the rule. Declared
394
+ that remain, in nested blocks as at the top level; a registry changes which marks
395
+ those are, not the rule. At a block's outer edge there is no neighbor, so text typed
396
+ there with no stored marks gets a run of its own carrying only the marks that
397
+ extend: typing after a link or inline code that ends a paragraph leaves it. Declared
349
398
  names are also what `run` may add, so a Kit's marks are usable by name or value.
350
399
 
351
400
  `validate(document, kit)` is the publishing gate: it reports `UnknownMark` for a
@@ -380,7 +429,7 @@ RichText.validate(document, ArticleKit)
380
429
  ```
381
430
 
382
431
  `children` defaults to `RichText.textContent`, so a node holds runs; `blockContent`
383
- says it holds nested blocks (§116). `RichText.block(name)` declares one of the
432
+ says it holds nested blocks. `RichText.block(name)` declares one of the
384
433
  built-in blocks and `RichText.atom(name)` declares a kind holding nothing, so an
385
434
  atom is exactly an application node with no content. `validate` walks nested blocks
386
435
  and reports `MismatchedDefinition` when a declaration and the document disagree
@@ -394,7 +443,7 @@ clipboard slices, history, and the interpreters all work on it unchanged — a
394
443
  split keeps its kind and props on both halves. `data-node="Kind"` is the default
395
444
  rendering in HTML and in the view until a Kit renderer replaces it.
396
445
 
397
- A node block may also accept **nested blocks** in `blocks` (§116), which is how a
446
+ A node block may also accept **nested blocks** in `blocks`, which is how a
398
447
  List holds ListItems. The HTML serializer renders them inside the node's element
399
448
  and `toText` gives one line per text block; the read-only view and the editable
400
449
  adapter do the same, so a list keeps its items in every interpreter. HTML import
@@ -515,8 +564,7 @@ asserted.
515
564
 
516
565
  ## Migrations
517
566
 
518
- Migrations move semantic data forward when a deployment changes its vocabulary
519
- (§73) — a preserved node that is now implemented, a prop renamed, a kind
567
+ Migrations move semantic data forward when a deployment changes its vocabulary — a preserved node that is now implemented, a prop renamed, a kind
520
568
  replaced:
521
569
 
522
570
  ```ts
@@ -576,7 +624,7 @@ framework-free. Nothing parses HTML back into authority without that walk.
576
624
 
577
625
  Three interpreters need to know which element a declared mark or node kind
578
626
  produces — this serializer, the read-only view, and the editable DOM interpreter —
579
- and they must not answer that three different ways (design §121). `rendering(...)`
627
+ and they must not answer that three different ways. `rendering(...)`
580
628
  is that answer: a vocabulary built *over* a Kit, never inside one, holding per-name
581
629
  entries that are either fixed data or a function of the mark or block.
582
630
 
@@ -618,7 +666,7 @@ interpreter share this one answer.
618
666
  ## Decorations
619
667
 
620
668
  A decoration is derived, ephemeral presentation over a document range — a search match, a
621
- lint warning, a remote cursor, a syntax token — and never document content (§64):
669
+ lint warning, a remote cursor, a syntax token — and never document content:
622
670
 
623
671
  ```ts
624
672
  const matches: RichText.DecorationSet = [{ from: at(0), to: at(7), kind: 'search' }]
@@ -634,13 +682,42 @@ shares — a decoration crossing runs is cut at each run's edge, an endpoint tha
634
682
  resolve skips the decoration, a backwards range is honoured, and one run's spans come back
635
683
  in text order.
636
684
 
637
- A producer comes with it. `searchDecorations(document, query)` returns every occurrence of a
638
- query as a decoration of kind `search` (`SEARCH_DECORATION`), changing nothing: one
639
- decoration per occurrence, a match across two runs kept whole, and no match across two blocks,
640
- because what a document has between blocks is structure rather than text. `positionInBlock(block,
685
+ A producer comes with it. `findMatches(document, query, { caseSensitive })` lists every
686
+ occurrence (its block, its offset there, and its ends as positions), case not counting unless
687
+ asked: a match across two runs kept whole, and no match across two blocks, because what a
688
+ document has between blocks is structure rather than text. `searchDecorations(document, query,
689
+ { caseSensitive, current })` draws them as decorations of kind `search` (`SEARCH_DECORATION`),
690
+ the one at index `current` as `search-current`, changing nothing. `Replace` (`{ query,
691
+ replacement, caseSensitive, at }`) replaces the match at `at`, or every match without it, as one
692
+ transaction, reading each match again where the replacements after it left the text. `positionInBlock(block,
641
693
  offset)` is the read it shares with `textRangeBefore` — the position a block's own text offset
642
694
  addresses — and the one any producer of ranges needs.
643
695
 
696
+ The outline is a read of the same kind. `outlineOf(document)` lists the headings that have text,
697
+ in document order and inside containers too, as `{ node, level, text }`; `sectionAt(document,
698
+ selection)` is the heading of the section the selection starts in, the last such heading at or
699
+ before its block, and undefined before the first. A table of contents draws the one and marks the
700
+ other.
701
+
702
+ Footnotes are opt-in vocabulary: add `FootnoteRef` to the kit's marks and `FootnoteDefinition` to
703
+ its nodes. A reference is the `FootnoteRef` mark (`{ label }`) on the run that shows the label, so
704
+ it moves and undoes with the text; a definition is a block of blocks with the same label, so its
705
+ note is ordinary editable text. The label is all that ties them. `footnotesOf(document)` lists
706
+ every footnote by first reference, as `{ label, definition, references, text }`, then the
707
+ definitions nothing refers to; `footnoteAt(document, selection)` is the label of the reference the
708
+ caret is in. `InsertFootnote` (`{ text? }`) puts a reference showing `nextFootnoteLabel` at the
709
+ caret, its definition after the last block, and the caret in the note; `RenameFootnote` (`{ from,
710
+ to }`) relabels the definition and every reference, refusing a label another footnote has.
711
+
712
+ Media beside `Image` is opt-in the same way: `mediaNodes` declares `Video` and `Audio` (`{ src,
713
+ title? }`, a video also `width?`) and `Attachment` (`{ src, name, size?, type? }`), and
714
+ `mediaRendering`, laid under a rendering with `renderingOver`, draws them as `video` and `audio`
715
+ with the browser's controls and an attachment as a download link showing its name and size.
716
+ `mediaBlock(file)` is the block for a file a reader added, by its type. Where the file lives is
717
+ the application's. A source must pass the URL policy, or be a `data:` URL of the kind's own
718
+ family (`video/…`, `audio/…`); an attachment's may be any `data:` type that cannot run as a page
719
+ (not HTML, SVG or XML), since it is only downloaded.
720
+
644
721
  Code highlighting is the second producer. A `CodeBlock` holds its `language` and plain text,
645
722
  and a `CodeTokenizer` — a pure `(text) => ReadonlyArray<{ from, to, kind }>` over that text —
646
723
  says what is in it; `codeDecorations(document, tokenizers)` runs the tokenizer registered for
@@ -649,7 +726,7 @@ token. The registry is a `Map` keyed by language, and a block whose language not
649
726
  registered for yields nothing. A token outside its block's text, covering nothing, or at a
650
727
  fractional offset throws, naming the language: a tokenizer's bug should not become a
651
728
  highlight over the wrong text. The grammars themselves are not here — they are
652
- format-specific, and belong to `foldkit-richtext-code` (§130).
729
+ format-specific, and belong to `foldkit-richtext-code`.
653
730
 
654
731
  ```ts
655
732
  const numbers: RichText.CodeTokenizer = text =>
@@ -683,12 +760,16 @@ Identities always come from the caller, like every other identity a live edit
683
760
  mints.
684
761
 
685
762
  Paste is a command (`{ type: 'Paste', slice }`): it remints every identity, then
686
- places the content relative to the caret — above the block at its start, below
687
- it at its end, and mid-block by splitting the block and landing the content
688
- between the halves, so text after the caret stays below what was pasted. A range
689
- selection is replaced first, and the caret lands at the end of the pasted text
690
- (or at the start of what follows when the pasted content has none). The DOM
691
- clipboard events that carry these payloads are not wired yet.
763
+ splits the caret's block and lands the content between the halves. The first
764
+ pasted block joins the text before the caret and the last joins the text after
765
+ it, when each can be one block with it, so a copied word or line lands inside the
766
+ sentence and several lines keep the sentence's two ends. A block that cannot join
767
+ (an image, a table, a list) stands between the halves, and a half left empty goes,
768
+ except the line after a pasted image or table, which is where writing goes on.
769
+ Into a kind whose text keeps line breaks (code), the paste is its plain text. A
770
+ range selection is replaced first, and the caret lands at the end of the pasted
771
+ text. `foldkit-richtext-dom` reads the clipboard into a slice (its own payload,
772
+ then HTML, then plain text) and sends this command.
692
773
 
693
774
  ## Undo history
694
775
 
@@ -750,14 +831,44 @@ its element — a `List` an `ol` or `ul`, an `Image` an `img` with its `src`, a
750
831
  application adds its own kinds beside the standard ones. A `TableRow` that is the header
751
832
  renders `data-header`, and a `Table`'s rows go in a `tbody` (the entry's `inner`), because an
752
833
  HTML parser inserts one around bare rows, and markup sent from a server has to parse to the tree
753
- that was rendered. A link's `href` and an image's `src` pass `safeUrl` again as they are
834
+ that was rendered. An entry's `adornments` are elements drawn inside the block before its content
835
+ that are not content: a task's checkbox, a figure's picture and caption, a callout's icon. They
836
+ carry `data-adornment`, hold no position, and an HTML import drops them; one with `toggles: 'open'`
837
+ flips that boolean prop when clicked, through the editor's `ChangedProps`, and one with an `action`
838
+ (`'copy'`) is reported to the application with its block, for something that is not an edit:
839
+
840
+ ```ts
841
+ RichText.renderingOver(RichText.standardRendering, {
842
+ nodes: {
843
+ TaskItem: block => ({
844
+ tag: 'li',
845
+ attributes: {},
846
+ adornments: [
847
+ {
848
+ tag: 'input',
849
+ attributes: { type: 'checkbox', ...(block.props.checked === true ? { checked: '' } : {}) },
850
+ toggles: 'checked',
851
+ },
852
+ ],
853
+ }),
854
+ },
855
+ })
856
+ ```
857
+ A standard `Image` also carries an optional `caption`, a `width` in CSS
858
+ pixels, and an `align` (`start`, `center`, `end`); the standard rendering draws the `img`
859
+ alone, and a rendering that draws a figure reads the rest. A link's `href` and an image's `src` pass `safeUrl` again as they are
754
860
  rendered, and one it refuses is left out, so a `javascript:` URL that reached the document
755
861
  by decoding, sync, or `SetMark` rather than import is drawn inert.
756
862
 
757
863
  A kind can state rules stricter than its content mode. `blocksOf(...kinds)` accepts only
758
864
  those block kinds, `marks: 'none'` forbids marks on the kind's own runs, `isolating: true`
759
865
  makes the kind a boundary a lift never crosses, as a table cell is, `splitProps` names
760
- props an item split off one of this kind starts with (typed from the kind's `Props`), and `within` names the kinds it may stand
866
+ props an item split off one of this kind starts with (typed from the kind's `Props`), `lineBreaks:
867
+ true` makes Enter a newline in the kind's text rather than a split (Enter on an empty last line
868
+ leaves it for a paragraph after; the standard `CodeBlock` declares it, and so may a callout of
869
+ several lines), `indents: true` makes Tab indent its lines and Enter keep a line's indentation, as
870
+ code does (`CodeBlock` declares both; without it, Tab still leaves the editor), and `within`
871
+ names the kinds it may stand
761
872
  in, so a `ListItem` stands only in a `List` and never at the top level:
762
873
 
763
874
  ```ts
@@ -907,7 +1018,7 @@ text is added after them; block identities are stable for a block's whole life.
907
1018
  - Empty documents, empty blocks, and empty text runs are valid. No normalization
908
1019
  creates nodes or merges text runs yet.
909
1020
  - A `Node` block may carry nested blocks in `blocks`, and its presence is what
910
- says the kind accepts them (§116): a List holds ListItems, a Quote paragraphs.
1021
+ says the kind accepts them: a List holds ListItems, a Quote paragraphs.
911
1022
  Nested content decodes, round-trips byte-equal, is counted by `inspect` and the
912
1023
  decode limits, survives a deploy that lost its kind, and a selection or
913
1024
  reference inside it resolves. Commands reach a run wherever it sits, so typing,
@@ -916,9 +1027,22 @@ text is added after them; block identities are stable for a block's whole life.
916
1027
  interpreter renders one, with the HTML importer reading a container back.
917
1028
  Structural placement works at depth too: a split keeps its halves in the block's
918
1029
  own container, siblings join within theirs, and a move or insert takes an
919
- optional `parent` to enter or leave a container. What is still refused with
920
- `InvalidParent` is a range that would have to merge across containers, and a
921
- parent that cannot hold blocks.
1030
+ optional `parent` to enter or leave a container. A range across containers or
1031
+ kinds of block (a selection from a list into the paragraph after it, or the
1032
+ whole document) is cleared as an editor clears one: the ends lose what it
1033
+ covers, every block wholly between goes, the far end comes up beside the near
1034
+ one and joins it when the two can be one (where the near end's container
1035
+ takes its kind), and containers left empty go. A range that leaves a table
1036
+ cell only loses its text. Typing, Enter or a paste over such a range clears it
1037
+ first. What is still refused with `InvalidParent` is a parent that cannot hold
1038
+ blocks.
1039
+ - An atom (an image, a divider) has no text for a caret, so it is selected whole.
1040
+ Backspace at the start of the block after it, or Delete at the end of the block
1041
+ before it, selects it, taking away the line the caret was on when that line is
1042
+ empty; a second press deletes it, and the caret lands where it was. Over a node
1043
+ selection, Enter opens an empty paragraph after the block, and typing replaces
1044
+ the block with a paragraph of what was typed. `isAtom(nodes, block)` is the test:
1045
+ the vocabulary's `atom` declaration, or, without one, a node holding nothing.
922
1046
  - `InsertText` targets one run and inherits that run's marks. When the command
923
1047
  carries `marks`, the inserted span is split out of its run and given exactly
924
1048
  that set instead — that is how a caller's stored marks reach the document.
@@ -976,7 +1100,8 @@ text is added after them; block identities are stable for a block's whole life.
976
1100
  - Marks carry boundary expansion (`Bold`/`Italic`: `after`, `Code`: `none`).
977
1101
  `resolveInsertion(document, position)` retargets edge insertions whose marks
978
1102
  forbid the edge to the neighbor carrying exactly the remaining marks; mixed
979
- edges stay put rather than swapping formatting. Unknown marks default to
1103
+ edges stay put rather than swapping formatting. At a block's outer edge, the
1104
+ typed text takes its own run with only the marks that extend there. Unknown marks default to
980
1105
  expanding both ways so preservation never retargets them away.
981
1106
  - Every transaction ends by running its transforms (by default
982
1107
  `mergeAdjacentRuns`): adjacent same-mark runs within touched blocks merge, the
@@ -1027,5 +1152,3 @@ so a container is checked again whenever anything inside it changes, and indexes
1027
1152
  text runs. Edits copy the affected arrays and preserve untouched nodes. The
1028
1153
  performance section records the measured cases, the collaborative path included
1029
1154
  (`bench/replicated.bench.ts`).
1030
-
1031
- See the [design and phase status](../../docs/design/richtext-DESIGN.md#101-phase-1--pure-semantics-and-integration-feasibility).