@portabletext/markdown 2.1.0 → 2.2.0

package/README.md

@@ -56,6 +56,18 @@ const markdown = portableTextToMarkdown([
 # Hello **world**
 ```
 
+**Edit through Markdown without losing keys**
+
+```ts
+import {applyMarkdownEdit, portableTextToMarkdown} from '@portabletext/markdown'
+
+const markdown = portableTextToMarkdown(stored)
+const editedMarkdown = markdown.replace('tomorow', 'tomorrow')
+const edited = applyMarkdownEdit(stored, editedMarkdown)
+// same content as parsing editedMarkdown, with the stored `_key`s
+// kept the way the same edit in an editor would have kept them
+```
+
 ## Supported features
 
 | Feature          | Markdown → Portable Text | Portable Text → Markdown |
@@ -87,7 +99,7 @@ Converting Markdown to Portable Text and back isn't a lossless mirror:
 2. The normalized Markdown is a fixpoint for plain text and the [Supported features](#supported-features) table: parsing it and serializing again reproduces it byte-for-byte.
 3. MD→PT survival is schema-driven: a construct whose type the schema doesn't declare keeps its content and drops the structure that named it.
 4. PT structures with no Markdown form degrade predictably on PT→MD (extra table header rows flatten into the body, deep or level-skipping lists collapse to relative nesting, unknown marks pass their text through unformatted). Unknown object types round-trip instead: block-level as a ` ```json:object ` fence, inline as a `json:object`-tagged code span, both carrying the value as JSON. A fence or span whose body isn't a JSON object with a `_type` is ordinary code.
-5. Identity does not round-trip for text blocks: keys are regenerated on every parse, and adjacent spans with identical marks merge into one. Unknown objects keep their `_key`.
+5. Identity does not round-trip for text blocks: keys are regenerated on every parse, and adjacent spans with identical marks merge into one. Unknown objects keep their `_key`. [`applyMarkdownEdit`](#applymarkdownedit) restores stored keys after an edit.
 6. A hard break and a `\n` in a span's text are exclusive counterparts in both directions: a `\n` always renders as hard-break syntax on the way out, and hard-break syntax always becomes `\n` on the way in, never the space a soft wrap joins with.
 
 The named exceptions to the fixpoint claim: an explicit-scheme URL or email keeps its text but gains a `link` mark on reparse, and a fuzzy `www.` form does too unless it carries markdown-significant punctuation; a hard break inside a heading splits into a second block on reparse, since an ATX heading is single-line; leading or trailing whitespace that CommonMark's own block parsing trims isn't part of the fixpoint; a `code` object with the reserved language `json:object` loses that language on serialization; and span text ending in `json:object` directly before a code-marked span holding a typed JSON object binds into an inline object on reparse.
@@ -537,7 +549,7 @@ The conversion is driven by **Renderers**: functions that render Portable Text e
 
 Unknown types render as JSON code blocks by default; unknown styles, list items, and marks pass through their children.
 
-The default type renderers are collision-safe: because the serializer dispatches on the `_type` name alone, `code`, `html`, `image`, `callout`, and `table` fall back to the `unknownType` renderer (a JSON code block) when a value doesn't match the shape their renderer expects (say, your own differently-shaped `code` type); `horizontal-rule` has no shape to check and always renders `---`. Register your own `types.<name>` renderer to override how any of them serialize, or to handle a same-named type of a different shape.
+The default type renderers are collision-safe: because the serializer dispatches on the `_type` name alone, `code`, `html`, `image`, `callout`, and `table` fall back to the `unknownType` renderer (a JSON code block) when a value doesn't match the shape their renderer expects (say, your own differently-shaped `code` type); `horizontal-rule` has no shape to check and always renders `---`. `image` also falls back when `src` is a string a Markdown parser would refuse (a `javascript:`/`vbscript:`/`file:` URI, or a `data:` URI outside `png`/`gif`/`jpeg`/`webp`), so the value survives as a `json:object` fence instead of reparsing as literal text. Register your own `types.<name>` renderer to override how any of them serialize, or to handle a same-named type of a different shape.
 
 > **Note:** The `underline` renderer is included for Portable Text that uses it, but there's no standard Markdown syntax for underline, so it renders as HTML.
 
@@ -668,7 +680,41 @@ portableTextToMarkdown(blocks, {
 
 By default, unknown types render as `json:object` fences or tagged code spans that round-trip (see [Round-trip behavior](#round-trip-behavior)), and unknown marks/styles pass through their children unchanged.
 
-You can also customize hard break rendering:
+#### Gating default renderers on a schema
+
+Going to convert the markdown back with `markdownToPortableText`? Pass the same `schema` to both, and nothing the schema can't rebuild becomes markdown that gets destroyed on the way back: undeclared types travel as `json:object` fences that reparse to the same value.
+
+```ts
+import {compileSchema, defineSchema} from '@portabletext/schema'
+
+const schema = compileSchema(
+  defineSchema({
+    blockObjects: [
+      {
+        name: 'code',
+        fields: [
+          {name: 'code', type: 'string'},
+          {name: 'language', type: 'string'},
+        ],
+      },
+    ],
+  }),
+)
+
+portableTextToMarkdown(blocks, {schema})
+```
+
+A default renderer (`callout`, `code`, `horizontal-rule`, `html`, `image`, `table`) runs only when the schema declares that type at the position the node appears in: `blockObjects` for a block, `inlineObjects` for an inline object. An `image` declared in only one of the two still falls back to `unknownType` at the other position.
+
+The gate reads type names, never field values: declaring a type doesn't validate anything, and a value's fields play no part in which renderer runs. Fields matter on the parse side instead: `markdownToPortableText` filters a construct down to its declared fields, so declare each type with the fields its values carry, or the markdown forms this gate lets through come back rebuilt without them.
+
+An undeclared type falls back to `unknownType`, whose default output is the same `json:object` fence or tagged code span described above, so it round-trips at block and inline positions. Inside a table cell the `json:object` form is the inline code span (a GFM cell is one line, and a fence would be squashed), so an undeclared object in a cell survives too; declared types whose markdown form spans multiple lines (a code block in a cell) still flatten on reparse. Renderers you register in `types` bypass the gate entirely, whether or not the schema declares them.
+
+Without a `schema`, every default renderer stays active.
+
+#### Hard breaks
+
+Customize how a hard break (a `\n` inside a span's text) renders:
 
 ```ts
 portableTextToMarkdown(blocks, {
@@ -697,6 +743,102 @@ portableTextToMarkdown(blocks, {
 })
 ```
 
+### `applyMarkdownEdit`
+
+Parsing markdown mints fresh `_key`s for text blocks (see [Round-trip behavior](#round-trip-behavior)), so converting a document to markdown, editing one word, and converting back returns what looks like a full rewrite: comment anchors detach, history churns, and granular patching is impossible. `applyMarkdownEdit` converts edited markdown back to Portable Text and restores stored `_key`s the way the same edit in an editor would have kept them:
+
+```ts
+import {applyMarkdownEdit, portableTextToMarkdown} from '@portabletext/markdown'
+
+const stored = [
+  {
+    _type: 'block',
+    _key: 'b1',
+    style: 'normal',
+    children: [{_type: 'span', _key: 's1', text: 'Ships tomorow.', marks: []}],
+    markDefs: [],
+  },
+]
+
+const markdown = portableTextToMarkdown(stored)
+// markdown === 'Ships tomorow.'; an agent (or anything else) fixes the typo
+const edited = applyMarkdownEdit(stored, 'Ships tomorrow.')
+```
+
+`edited`:
+
+```json
+[
+  {
+    "_type": "block",
+    "_key": "b1",
+    "style": "normal",
+    "children": [
+      {"_type": "span", "_key": "s1", "text": "Ships tomorrow.", "marks": []}
+    ],
+    "markDefs": []
+  }
+]
+```
+
+Keys follow the edit the way they would in an editor, and when the evidence is unclear, a block gets a fresh key rather than a wrong one. The result is a value, not patches; output keys are always unique among siblings; the inputs are never mutated.
+
+#### What keeps its key
+
+- Unchanged and moved blocks. Repeated content pairs in order.
+- A block rewritten in place, like typing over it. Style changes count as rewrites, and an edited table cell keeps the whole table's keys.
+- A split keeps the key on the first non-empty fragment, like pressing enter; a merge keeps the first block's key, like pressing backspace. A soft-wrap join is a merge.
+- A typo fix lands as a text change on the same span, and editing a link's URL keeps its annotation key. Two identical annotations in one block (the same link twice, say) pair in order, like any repeated content.
+- A `json:object` payload keeps the `_key` it carries, unless the payload matches stored content, which keeps the stored key: editing markdown cannot re-key existing content.
+
+#### What gets restored
+
+Markdown cannot carry everything a block stores, so an adopted block gets back what the edit could not have touched:
+
+- A field the dialect cannot express, like a text block's `alignment`, including a whole custom object-array field the dialect drops. A field markdown does express, like `language` on a code block, follows the edit.
+- A custom style, list kind, or decorator markdown has no syntax for.
+- An empty or whitespace-only paragraph, which has no markdown form at all (blank lines are the block separator): it is restored next to its surviving neighbor, and deleted along with that neighbor if the neighbor goes. This covers top-level blocks; an empty paragraph nested inside a table cell or callout content is not restored. An empty heading or list item has a visible markdown form (`## `, `- `) and round-trips like any other block.
+- A block the edit did not touch comes back exactly as stored, span structure and unmappable marks included: an adjacent pair of spans that only differ by a decorator markdown has no syntax for keeps its split rather than merging into the one span a plain parse would produce.
+
+#### When keys reset
+
+- Ambiguity: when an insertion or deletion makes a match unclear, a block keeps its key only on clear evidence; everything else gets a new key, and short blocks near the change are the usual casualties.
+- Indistinguishable edits: replacing a block with unrelated content in the same position keeps its key (the end state is identical to a rewrite), and a whole-document rewrite that keeps the block count pairs blocks in order. That last one is deliberate: a translation keeps every anchor by position, which is the behavior translate flows need. The cost is that a reorder-plus-edit with balanced counts mispairs the same way, block-level and sibling-level alike.
+- Caps: on very large ambiguous edits, evidence gathering is size- and time-capped and degrades to fresh keys rather than waiting, so near the caps, which keys survive can vary with machine speed.
+- Refusal: a stored value that cannot survive its own serialize→parse round trip resets the whole document to the plain conversion, every key fresh except the ones `json:object` payloads carry.
+
+#### Options
+
+The options bag mirrors the two converters, plus a top-level `schema`: `deserialize` takes the rest of `markdownToPortableText`'s options and `serialize` takes the rest of `portableTextToMarkdown`'s. `schema` is taken once and governs both directions, because restoring keys depends on the two serializations agreeing. Pass the same `serialize` options that produced the markdown that was edited. The `deserialize` options apply to the stored value as well as the edited markdown, with two exceptions: new keys come from `deserialize.keyGenerator` (or the built-in generator), and `onDegradation` reports only on the edited markdown.
+
+#### Observing reconciliation
+
+Pass `onReconciliation` to see what happened to every key. The callback fires exactly once per call, synchronously, right before the function returns:
+
+```ts
+applyMarkdownEdit(stored, editedMarkdown, {
+  onReconciliation: (report) => {
+    if (report.keyMatching === 'skipped') {
+      // report.reason is 'round-trip-mismatch' (the stored value cannot
+      // survive its own serialize→parse round trip) or
+      // 'document-too-large'. The returned value is the plain
+      // conversion, every key fresh except the ones `json:object`
+      // payloads carry
+      return
+    }
+    report.preservedKeys // stored keys that survived, with a basis and a path
+    report.keyFallbacks // regions that got fresh keys instead of a guess
+    report.renamedKeys // keys rewritten to keep siblings unique
+  },
+})
+```
+
+Every `key` and `path` in the report matches the returned value exactly, and a path segment is a string field name, a number array index, or `{_key}` for a keyed element, the same convention as editor paths. Which keys survived, the paths, `renamedKeys`, and `keyMatching` are facts of that invocation, safe to branch on. A preserved key's `basis` names the matching method (`'content-unchanged'`, `'content-moved'`, `'content-split'`, `'content-merged'`, `'same-position'`, `'similar-content'`) and is advisory: near the evidence caps it can vary with machine speed, so never branch on it. A node absent from `preservedKeys` was not restored from the stored value, whether its key is fresh or carried by a `json:object` payload. The exported `ReconciliationReport` and `ReconciliationKeyPath` types are `@beta`.
+
+#### Concurrent edits
+
+Reconciling an unchanged serialization returns the stored value byte for byte for the content the edit did not touch, keys, span structure, and unmappable marks included; content the edit did touch still comes back canonicalized, with its keys restored where reconciliation can trace them. `applyMarkdownEdit` does not merge concurrent edits: reconcile against the exact value that produced the markdown, and before writing the result back, check that the stored field still equals that value. If it changed while the markdown was being edited, the edit describes a document that no longer exists, and writing it would silently overwrite the newer changes: serialize the current value and redo the edit instead.
+
 ## License
 
 MIT © [Sanity.io](https://www.sanity.io/)