foldkit-richtext 0.7.0 → 0.9.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.
Files changed (2) hide show
  1. package/README.md +45 -15
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -53,6 +53,21 @@ then applies operations in array order. A later invalid operation rejects the
53
53
  whole transaction. No partially edited state is returned, and inputs are not
54
54
  mutated. `result.error` is a stable diagnostic code, without raw validation internals.
55
55
 
56
+ <!-- docs-check
57
+ import { Schema } from 'effect'
58
+ declare const state: RichText.EditorState
59
+ declare const command: RichText.Command
60
+ declare const transaction: RichText.Transaction
61
+ declare const removeTheMarker: RichText.Command
62
+ declare const retypeTheBlock: RichText.Command
63
+ declare const previousState: RichText.EditorState
64
+ declare const currentState: RichText.EditorState
65
+ declare const selection: RichText.Selection
66
+ declare const payload: string
67
+ declare const mint: () => string
68
+ const at = (offset: number) => Text.at(offset, 'after')
69
+ -->
70
+
56
71
  ## Named node references
57
72
 
58
73
  `Node.make('text-1')` declares a reusable identity. Its `.id` is a validated
@@ -81,7 +96,7 @@ Prefer `Edit.*` over hand-written literals; the builder fills `type` and the
81
96
  return type is narrowed to that variant:
82
97
 
83
98
  ```ts
84
- const result = RichText.apply(state, [
99
+ const edited = RichText.apply(state, [
85
100
  RichText.Edit.insertText(Text.at(5, 'after'), '!'),
86
101
  RichText.Edit.addMark(Text, 'Bold'),
87
102
  ])
@@ -141,7 +156,7 @@ interface InputRule {
141
156
  match: (
142
157
  textBefore: string,
143
158
  within: ReadonlyArray<string>,
144
- ) => { remove: number; commands: Action; storedMarks?: ReadonlyArray<string> } | undefined
159
+ ) => { remove: number; commands: RichText.Action; storedMarks?: ReadonlyArray<string> } | undefined
145
160
  }
146
161
  ```
147
162
 
@@ -413,7 +428,7 @@ application's schemas; a Kit's node definition validates them at that boundary,
413
428
  and it also declares what content the kind holds:
414
429
 
415
430
  ```ts
416
- const ArticleKit = RichText.kit({
431
+ const NodeKit = RichText.kit({
417
432
  nodes: [
418
433
  RichText.block('Paragraph'),
419
434
  RichText.node('Callout', { Props: Schema.Struct({ tone: Schema.Literals(['info', 'warning']) }) }),
@@ -423,7 +438,7 @@ const ArticleKit = RichText.kit({
423
438
  marks: [RichText.Bold],
424
439
  })
425
440
 
426
- RichText.validate(document, ArticleKit)
441
+ RichText.validate(document, NodeKit)
427
442
  // → [] | UnsupportedNode (kind not declared) | InvalidProps (schema refused them)
428
443
  // | MismatchedDefinition (declaration and document disagree)
429
444
  ```
@@ -462,7 +477,7 @@ Normalization runs as a registry of transforms. Each is a pure function of the
462
477
  document plus what the transaction touched, and returns the new document with
463
478
  the position steps and identity bookkeeping that go with it:
464
479
 
465
- ```ts
480
+ ```ts sketch
466
481
  const DropEmptyRuns: RichText.Transform = {
467
482
  name: 'dropEmptyRuns',
468
483
  apply: (document, { dirtyNodes }) => ({ document: next, steps, removedNodes, dirtyNodes, textChanged }),
@@ -568,10 +583,10 @@ Migrations move semantic data forward when a deployment changes its vocabulary
568
583
  replaced:
569
584
 
570
585
  ```ts
571
- const Callout = Schema.Struct({ tone: Schema.Literals(['info', 'warning', 'critical']) })
586
+ const CalloutProps = Schema.Struct({ tone: Schema.Literals(['info', 'warning', 'critical']) })
572
587
 
573
588
  RichText.migrate(document, [
574
- RichText.promoteUnknown('EmbedToCallout', 'Embed', 'Callout', Callout),
589
+ RichText.promoteUnknown('EmbedToCallout', 'Embed', 'Callout', CalloutProps),
575
590
  RichText.migration('DangerToCritical', 'Callout', block =>
576
591
  block.type === 'Node' && block.props.tone === 'danger'
577
592
  ? { ...block, props: { ...block.props, tone: 'critical' } }
@@ -745,9 +760,11 @@ its own identities:
745
760
 
746
761
  ```ts
747
762
  const slice = RichText.sliceOf(document, selection) // → Slice | undefined
748
- RichText.serializeSlice(slice) // → string for the clipboard
763
+ if (slice !== undefined) {
764
+ RichText.serializeSlice(slice) // → string for the clipboard
765
+ RichText.withFreshIds(slice, mint) // identities that cannot collide
766
+ }
749
767
  RichText.deserializeSlice(payload) // → Slice | undefined
750
- RichText.withFreshIds(slice, mint) // identities that cannot collide
751
768
  RichText.sliceFromText('plain\npaste', mint) // the text fallback
752
769
  ```
753
770
 
@@ -781,7 +798,7 @@ published content.
781
798
  let history = RichText.emptyHistory
782
799
  history = RichText.commit(history, previousState, { group: RichText.groupFor(command) })
783
800
  const back = RichText.undo(history, currentState) // → { history, state } | undefined
784
- const forward = RichText.redo(back.history, back.state)
801
+ const forward = back && RichText.redo(back.history, back.state)
785
802
  ```
786
803
 
787
804
  Grouping is explicit and clock-free: `groupFor` returns `'typing'` for text
@@ -804,18 +821,23 @@ A `Kit` declares the vocabulary one editor accepts — node kinds and marks —
804
821
  plain data, with no renderers or executable code:
805
822
 
806
823
  ```ts
807
- const ArticleKit = RichText.kit({
824
+ const BlogKit = RichText.kit({
808
825
  nodes: [RichText.block('Paragraph'), RichText.block('Heading'), RichText.atom('Image')],
809
826
  marks: [RichText.Bold, RichText.Italic],
810
827
  })
811
828
 
812
- RichText.validate(document, ArticleKit)
829
+ RichText.validate(document, BlogKit)
813
830
  // → [] when the document fits; otherwise a diagnostic the caller decides on
814
831
  ```
815
832
 
816
833
  `foldkit-richtext` also ships a standard vocabulary — the kinds and marks a document
817
834
  uses to mean what Markdown and HTML also mean:
818
835
 
836
+ <!-- docs-check
837
+ const Callout = RichText.node('Callout')
838
+ const Highlight = RichText.mark('Highlight', { expand: 'none' })
839
+ -->
840
+
819
841
  ```ts
820
842
  RichText.kit({
821
843
  nodes: [...RichText.standardNodes, Callout],
@@ -879,6 +901,10 @@ code does (`CodeBlock` declares both; without it, Tab still leaves the editor),
879
901
  names the kinds it may stand
880
902
  in, so a `ListItem` stands only in a `List` and never at the top level:
881
903
 
904
+ <!-- docs-check
905
+ const Language = Schema.Struct({ language: Schema.String })
906
+ -->
907
+
882
908
  ```ts
883
909
  RichText.node('List', { children: RichText.blocksOf('ListItem', 'TaskItem') })
884
910
  RichText.node('CodeBlock', { Props: Language, children: RichText.textContent, marks: 'none' })
@@ -898,6 +924,10 @@ an unexpected child, a forbidden mark, or a misplaced kind (a move, a wrap, or a
898
924
  is given the vocabulary — `nodes: RichText.nodeRegistry(kit.nodes)`, the node
899
925
  counterpart of the `marks` option:
900
926
 
927
+ <!-- docs-check
928
+ const kit = BlogKit
929
+ -->
930
+
901
931
  ```ts
902
932
  RichText.run(state, { type: 'ToggleMark', mark: 'Bold' }, ids, {
903
933
  nodes: RichText.nodeRegistry(kit.nodes),
@@ -945,13 +975,13 @@ const seed = RichText.decodeDocument({
945
975
  let shared = Replicated.fromDocument(seed, 'doc:seed')
946
976
  const shown = Replicated.project(shared)
947
977
  const caret = { node: shown.children[0]!.children[0]!.id, offset: 5, affinity: 'after' as const }
948
- const result = RichText.run(
978
+ const typed = RichText.run(
949
979
  { document: shown, selection: { type: 'Range', anchor: caret, focus: caret } },
950
980
  { type: 'InsertText', text: '!' },
951
981
  { mint: () => crypto.randomUUID() },
952
982
  )
953
- if (result.ok) {
954
- const { ops, selection } = Replicated.translate(shared, result, 'edit:1')
983
+ if (typed.ok) {
984
+ const { ops, selection } = Replicated.translate(shared, typed, 'edit:1')
955
985
  shared = Replicated.applyOps(shared, ops)
956
986
  const next = { document: Replicated.project(shared), selection: Replicated.resolve(shared, selection) }
957
987
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "foldkit-richtext",
3
- "version": "0.7.0",
3
+ "version": "0.9.0",
4
4
  "description": "Pure semantic documents and editing transactions for Foldkit.",
5
5
  "keywords": [
6
6
  "foldkit",
@@ -39,7 +39,7 @@
39
39
  "LICENSE"
40
40
  ],
41
41
  "dependencies": {
42
- "foldkit-media": "0.5.0"
42
+ "foldkit-media": "0.7.0"
43
43
  },
44
44
  "peerDependencies": {
45
45
  "effect": "^4.1.0"