uncial 0.0.7 → 1.0.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 (67) hide show
  1. package/README.md +75 -8
  2. package/dist/core/attributes.d.ts +7 -1
  3. package/dist/core/attributes.js +35 -16
  4. package/dist/core/defineBlock.js +36 -9
  5. package/dist/core/index.d.ts +3 -1
  6. package/dist/core/index.js +2 -1
  7. package/dist/core/issues.d.ts +7 -0
  8. package/dist/core/issues.js +9 -0
  9. package/dist/core/meta.js +2 -7
  10. package/dist/core/migrations.d.ts +30 -0
  11. package/dist/core/migrations.js +43 -0
  12. package/dist/core/normalize.d.ts +12 -1
  13. package/dist/core/normalize.js +110 -21
  14. package/dist/core/registry.d.ts +7 -0
  15. package/dist/core/registry.js +22 -4
  16. package/dist/core/runtime.d.ts +7 -0
  17. package/dist/core/types.d.ts +8 -2
  18. package/dist/core/validate.js +22 -6
  19. package/dist/editor/AttributeFieldControl.svelte +31 -3
  20. package/dist/editor/BlockAttributesPanel.svelte +35 -30
  21. package/dist/editor/BlockAttributesPanel.svelte.d.ts +9 -1
  22. package/dist/editor/Editor.svelte +5 -16
  23. package/dist/editor/RichTextAttributeEditor.svelte +75 -145
  24. package/dist/editor/RichTextAttributeEditor.svelte.d.ts +2 -1
  25. package/dist/editor/Toolbar.svelte +2 -3
  26. package/dist/editor/attributeTargets.d.ts +23 -0
  27. package/dist/editor/attributeTargets.js +21 -0
  28. package/dist/editor/attributesController.d.ts +7 -0
  29. package/dist/editor/attributesController.js +118 -229
  30. package/dist/editor/bindEditor.js +102 -26
  31. package/dist/editor/chooseAttribute.d.ts +26 -0
  32. package/dist/editor/chooseAttribute.js +10 -0
  33. package/dist/editor/containerChildOps.d.ts +33 -0
  34. package/dist/editor/containerChildOps.js +94 -0
  35. package/dist/editor/dropdownDismiss.d.ts +18 -0
  36. package/dist/editor/dropdownDismiss.js +46 -0
  37. package/dist/editor/index.d.ts +3 -1
  38. package/dist/editor/index.js +2 -1
  39. package/dist/editor/linkController.d.ts +19 -0
  40. package/dist/editor/linkController.js +72 -0
  41. package/dist/editor/toolbarFeatures.d.ts +12 -0
  42. package/dist/editor/toolbarFeatures.js +36 -0
  43. package/dist/render/Renderer.svelte +1 -1
  44. package/dist/render/RichContent.svelte +2 -2
  45. package/dist/render/RichNode.svelte +16 -2
  46. package/dist/render/sanitize.d.ts +6 -0
  47. package/dist/render/sanitize.js +20 -1
  48. package/dist/runtime/reactiveProps.svelte.d.ts +16 -0
  49. package/dist/runtime/reactiveProps.svelte.js +16 -0
  50. package/dist/runtime/svelte.d.ts +2 -1
  51. package/dist/runtime/svelte.js +26 -6
  52. package/dist/shared/EditorBlockFixture.svelte +24 -0
  53. package/dist/shared/EditorBlockFixture.svelte.d.ts +9 -0
  54. package/dist/shared/content.js +2 -1
  55. package/dist/shared/guards.d.ts +13 -0
  56. package/dist/shared/guards.js +16 -0
  57. package/dist/shared/richText.js +20 -4
  58. package/dist/shared/runtimeId.d.ts +8 -0
  59. package/dist/shared/runtimeId.js +8 -0
  60. package/dist/shared/tiptap.js +58 -23
  61. package/dist/web-components/UncialEditor.svelte +16 -1
  62. package/dist/web-components/UncialEditor.svelte.d.ts +5 -2
  63. package/dist/web-components/index.d.ts +39 -10
  64. package/dist/web-components/index.js +86 -36
  65. package/dist/web-components/reactiveProps.svelte.d.ts +10 -0
  66. package/dist/web-components/reactiveProps.svelte.js +13 -0
  67. package/package.json +1 -1
package/README.md CHANGED
@@ -73,9 +73,7 @@ Then register and use that component as an Uncial block:
73
73
  label: 'Promo Card',
74
74
  attributes: {
75
75
  title: '',
76
- featured: false,
77
- priority: 0,
78
- metadata: { default: { theme: 'sand' }, input: 'json' }
76
+ body: { default: '', input: 'textarea' }
79
77
  },
80
78
  component: PromoCard
81
79
  });
@@ -110,17 +108,56 @@ Object.assign(renderer, { blocks, schema, content: document });
110
108
 
111
109
  const editor = document.querySelector('uncial-editor');
112
110
  Object.assign(editor, { blocks, schema, json: document, attributesController });
111
+
112
+ // Document metadata mirrors the document body: set `metaFields` to render the
113
+ // metadata editor and read/write `meta` for the current values.
114
+ Object.assign(editor, { metaFields, meta: document.meta });
113
115
  ```
114
116
 
115
117
  ```html
116
118
  <uncial-editor></uncial-editor> <uncial-renderer></uncial-renderer>
117
119
  ```
118
120
 
121
+ Property assignments update the mounted component in place. Setting `editor.json = nextDocument` syncs the existing Tiptap editor through `setContent` instead of recreating it, so focus, selection, and undo history survive external document updates.
122
+
123
+ > **Configuration is via JS properties, not HTML attributes — by design.** The
124
+ > element inputs (`blocks`, `schema`, `json`, `meta`, `metaFields`, `extensions`,
125
+ > controllers, …) are structured objects, functions, and Svelte components that
126
+ > do not round-trip through string HTML attributes, so `<uncial-editor json="…">`
127
+ > is intentionally **not** observed. The one exception is `stylesheet` (a plain
128
+ > URL string), which is reflected as an attribute (see below). Set everything else
129
+ > as a property (`el.json = …`) after the element is in the DOM.
130
+
131
+ ### Styling the shadow root
132
+
133
+ Both elements render into an open shadow root, so page-level stylesheets do not reach them. Pass one or more whitespace-separated stylesheet URLs through the `stylesheet` attribute (or matching DOM property); each URL is rendered as a `<link rel="stylesheet">` inside the shadow root:
134
+
135
+ ```html
136
+ <uncial-editor stylesheet="https://unpkg.com/uncial/dist/styles/index.css"></uncial-editor>
137
+ ```
138
+
139
+ With a bundler such as Vite, resolve the packaged CSS to a URL:
140
+
141
+ ```ts
142
+ import uncialStylesHref from 'uncial/styles?url';
143
+
144
+ const editor = document.querySelector('uncial-editor');
145
+ editor.stylesheet = uncialStylesHref;
146
+ ```
147
+
148
+ A URL-based hook is used because the package ships its default CSS as plain files (`uncial/styles`, `uncial/styles/chrome`, ...) that any bundler, CDN, or asset pipeline can serve, and the `@import` chains inside them resolve relative to the linked URL — something constructed stylesheets (`adoptedStyleSheets`) do not support. Because the shadow root is open, advanced hosts can still inject constructed stylesheets themselves via `element.shadowRoot.adoptedStyleSheets`. The `--uncial-*` custom properties inherit across the shadow boundary, so token-based theming on a wrapper element keeps working (see [Styling and customization](#styling-and-customization)).
149
+
150
+ ### Events
151
+
119
152
  Validation callbacks are emitted as bubbling, composed DOM events. Editor document updates are emitted as `uncial-change` because non-Svelte hosts cannot use `bind:json`:
120
153
 
121
154
  ```ts
122
155
  editor.addEventListener('uncial-change', (event) => {
123
- document = event.detail;
156
+ document = event.detail; // the normalized document JSON; editor.json reflects the same value
157
+ });
158
+
159
+ editor.addEventListener('uncial-meta-change', (event) => {
160
+ meta = event.detail; // the committed document metadata; editor.meta reflects the same value
124
161
  });
125
162
 
126
163
  renderer.addEventListener('uncial-issue', (event) => {
@@ -128,6 +165,8 @@ renderer.addEventListener('uncial-issue', (event) => {
128
165
  });
129
166
  ```
130
167
 
168
+ `uncial-change` fires for edits made inside the editor, and at most once after an external `editor.json` assignment (only when normalization changes the incoming document, for example by stamping a version). Feeding a previously emitted document back into `editor.json` is a no-op, so hosts can mirror the value into their own state without creating an update loop. `uncial-meta-change` fires when document metadata is committed through the metadata editor and mirrors the value onto `editor.meta`, exactly as `uncial-change` does for `editor.json`. `uncial-issue` fires on both elements whenever normalization or validation reports a problem.
169
+
131
170
  For SSR frameworks, import `uncial/web-components` on the client only. Svelte blocks still render through the Svelte renderer for SSR; non-Svelte block runtimes should provide their own full-document renderer rather than relying on mixed component islands.
132
171
 
133
172
  ## Runtime plugins
@@ -284,27 +323,35 @@ Use `component` when the same Svelte component should render in both the editor
284
323
  const hero = defineSvelteBlock({
285
324
  id: 'hero',
286
325
  label: 'Hero',
326
+ description: 'Full-width intro banner', // optional; shown in the insert menu
287
327
  attributes: {
288
328
  title: '',
289
329
  subtitle: { default: '', input: 'textarea' },
290
330
  featured: false,
291
331
  priority: 1,
332
+ align: { default: 'left', options: ['left', 'center', 'right'] },
292
333
  settings: { default: { align: 'left' }, input: 'json' }
293
334
  },
294
335
  component: Hero
295
336
  });
296
337
  ```
297
338
 
298
- Attribute specs support:
339
+ A bare value (`title: ''`) is shorthand for `{ default: '' }`. The full attribute
340
+ spec supports:
299
341
 
300
342
  - `default`: required default value
301
343
  - `required`: require a value at validation time
302
344
  - `validate`: custom validation predicate
303
345
  - `parse`: custom coercion from editor or serialized input
304
346
  - `serialize`: custom serialization for HTML persistence
305
- - `input`: one of `text`, `textarea`, `number`, `checkbox`, or `json`
347
+ - `input`: editor control hint — `text`, `textarea`, `number`, `checkbox`, `json`, `select`, `richtext`, or `hidden`. When omitted it is inferred from the default value (and from `options`, which implies `select`).
348
+ - `options`: allowed values for `select` inputs, either plain values or `{ value, label, description }` objects
349
+ - `richText`: for `richtext` inputs, a `{ features, placeholder }` object controlling the nested rich-text feature allowlist
306
350
  - `placeholder`: optional editor placeholder
307
351
 
352
+ Blocks themselves also accept an optional `description` and `icon` (an icon name,
353
+ inline markup, or a Svelte component) that surface in the editor's insert menu.
354
+
308
355
  Blocks can also opt into child content:
309
356
 
310
357
  ```ts
@@ -368,8 +415,7 @@ Use `validateDocument(...)` directly or pass `onIssue` into `Editor` or `Rendere
368
415
  {schema}
369
416
  bind:json={document}
370
417
  onIssue={(issue) => console.warn(issue.code, issue.path)}
371
- /
372
- >
418
+ />
373
419
  ```
374
420
 
375
421
  ## Rendering and security
@@ -379,6 +425,27 @@ Use `validateDocument(...)` directly or pass `onIssue` into `Editor` or `Rendere
379
425
  - Links are sanitized to allow only `http`, `https`, `mailto`, `tel`, relative paths, and hash links
380
426
  - Custom block components and `html.render` hooks are trusted application code; sanitize any raw HTML or navigation attributes they emit
381
427
 
428
+ ## SSR usage
429
+
430
+ The renderer is safe to import in a server bundle. Import from the granular entry points so
431
+ the editor mount stack (Tiptap, `BlockNodeView`, `mount()`/`unmount()`) never reaches your
432
+ server:
433
+
434
+ ```ts
435
+ import { Renderer } from 'uncial/render';
436
+ import { defineSvelteBlock, createBlockRegistry, createSchema } from 'uncial/core';
437
+ ```
438
+
439
+ `uncial/render` and `uncial/core` are free of browser-only editor machinery — a regression
440
+ test walks the `render/` import graph and fails if an editor/runtime import creeps back in.
441
+
442
+ The package root barrel (`import … from 'uncial'`) re-exports `uncial/editor` as well, so
443
+ importing from the root **does** pull the editor graph into your bundle. For SSR, prefer the
444
+ `uncial/render` + `uncial/core` entry points over the root barrel.
445
+
446
+ > TODO: a future major may drop `./editor` from the root barrel so `import 'uncial'` is
447
+ > SSR-lean by default. Until then, use the granular entry points on the server.
448
+
382
449
  ## Development
383
450
 
384
451
  ```sh
@@ -8,4 +8,10 @@ export declare function serializeAttributeValue<T>(spec: AttributeSpec<T>, value
8
8
  export declare function serializeBlockAttributes(block: AttributeDefinition, attrs: Record<string, unknown>): string;
9
9
  export declare function toAttributeDraftValue(spec: AttributeSpec<unknown>, value: unknown): unknown;
10
10
  export declare function toAttributeDraftValues(block: AttributeDefinition, attrs: Record<string, unknown>): Record<string, unknown>;
11
- export declare function parseBlockDraftAttributes(block: AttributeDefinition, draftAttrs: Record<string, unknown>): Record<string, unknown>;
11
+ /**
12
+ * @deprecated Alias of {@link normalizeBlockAttributes}. Parsing draft (form)
13
+ * attribute values back into stored values is exactly attribute normalization:
14
+ * both coerce every declared attribute through `coerceAttributeValue`. Kept as a
15
+ * named export for the editor's attributes controller and existing callers.
16
+ */
17
+ export declare const parseBlockDraftAttributes: typeof normalizeBlockAttributes;
@@ -1,7 +1,5 @@
1
1
  import { coerceRichTextDocument } from '../shared/richText.js';
2
- function isPlainObject(value) {
3
- return typeof value === 'object' && value !== null && !Array.isArray(value);
4
- }
2
+ import { isPlainObject, isAttributeOption } from '../shared/guards.js';
5
3
  function parseJsonValue(raw) {
6
4
  try {
7
5
  return JSON.parse(raw);
@@ -10,8 +8,17 @@ function parseJsonValue(raw) {
10
8
  return undefined;
11
9
  }
12
10
  }
13
- function isAttributeOption(value) {
14
- return typeof value === 'object' && value !== null && !Array.isArray(value) && 'value' in value;
11
+ /**
12
+ * Returns a fresh copy of an attribute default before handing it out, so two
13
+ * block instances that both fall back to an object/array default never share one
14
+ * mutable reference (mutating one block's attrs would otherwise leak into every
15
+ * other block using the same spec). Primitive defaults are returned as-is.
16
+ */
17
+ function cloneDefault(value) {
18
+ if (value !== null && typeof value === 'object') {
19
+ return structuredClone(value);
20
+ }
21
+ return value;
15
22
  }
16
23
  export function normalizeAttributeOptions(spec) {
17
24
  if (!spec.options || spec.options.length === 0)
@@ -46,12 +53,23 @@ export function inferAttributeInputKind(spec) {
46
53
  return 'text';
47
54
  }
48
55
  export function coerceAttributeValue(spec, value) {
49
- if (value === undefined || value === null || value === '') {
50
- return spec.default;
56
+ // Only `undefined`/`null` are "missing" and fall back to the default. An empty
57
+ // string is a real value (e.g. a text attribute cleared by the author), so it
58
+ // must NOT be treated as missing — otherwise string attrs could never be
59
+ // cleared back to "". Each type branch below still rejects "" where it cannot
60
+ // be coerced (number/boolean/array/object) and falls back to the default there.
61
+ //
62
+ // Deliberately NOT run here: `spec.validate`. Dropping a value that fails a
63
+ // semantic validator back to the default would be silent data loss and would
64
+ // defeat the editor's out-of-range-value preservation (the select control's
65
+ // "(current)" option). Semantic validity is reported separately by
66
+ // `validateDocument` (INVALID_ATTR), which is the channel that surfaces it.
67
+ if (value === undefined || value === null) {
68
+ return cloneDefault(spec.default);
51
69
  }
52
70
  if (spec.parse) {
53
71
  const parsed = spec.parse(value);
54
- return parsed === undefined ? spec.default : parsed;
72
+ return parsed === undefined ? cloneDefault(spec.default) : parsed;
55
73
  }
56
74
  const fallback = spec.default;
57
75
  if (spec.input === 'richtext') {
@@ -90,7 +108,7 @@ export function coerceAttributeValue(spec, value) {
90
108
  if (Array.isArray(parsed))
91
109
  return parsed;
92
110
  }
93
- return fallback;
111
+ return cloneDefault(fallback);
94
112
  }
95
113
  if (isPlainObject(fallback)) {
96
114
  if (isPlainObject(value))
@@ -100,7 +118,7 @@ export function coerceAttributeValue(spec, value) {
100
118
  if (isPlainObject(parsed))
101
119
  return parsed;
102
120
  }
103
- return fallback;
121
+ return cloneDefault(fallback);
104
122
  }
105
123
  return value;
106
124
  }
@@ -141,9 +159,10 @@ export function toAttributeDraftValues(block, attrs) {
141
159
  toAttributeDraftValue(spec, attrs[name])
142
160
  ]));
143
161
  }
144
- export function parseBlockDraftAttributes(block, draftAttrs) {
145
- return Object.fromEntries(Object.entries(block.attributes).map(([name, spec]) => [
146
- name,
147
- coerceAttributeValue(spec, draftAttrs[name])
148
- ]));
149
- }
162
+ /**
163
+ * @deprecated Alias of {@link normalizeBlockAttributes}. Parsing draft (form)
164
+ * attribute values back into stored values is exactly attribute normalization:
165
+ * both coerce every declared attribute through `coerceAttributeValue`. Kept as a
166
+ * named export for the editor's attributes controller and existing callers.
167
+ */
168
+ export const parseBlockDraftAttributes = normalizeBlockAttributes;
@@ -1,14 +1,36 @@
1
- function isAttributeSpec(value) {
2
- return typeof value === 'object' && value !== null && 'default' in value;
3
- }
4
- function isAttributeOption(value) {
5
- return typeof value === 'object' && value !== null && !Array.isArray(value) && 'value' in value;
1
+ import { isAttributeOption, isPlainObject } from '../shared/guards.js';
2
+ // The keys that mark an object as an AttributeSpec *configuration* rather than a
3
+ // shorthand object default. An object carrying any of these is treated as a
4
+ // config object; to use an object literal AS the default value, wrap it
5
+ // explicitly: `{ default: { ... } }`.
6
+ const CONFIG_KEYS = [
7
+ 'default',
8
+ 'required',
9
+ 'validate',
10
+ 'parse',
11
+ 'serialize',
12
+ 'input',
13
+ 'placeholder',
14
+ 'options',
15
+ 'richText'
16
+ ];
17
+ /**
18
+ * Distinguishes a spec/config object (`{ default, input, ... }`) from a bare
19
+ * object used directly as the default value. Any plain object carrying a known
20
+ * config key is a config; everything else is a shorthand default. This makes a
21
+ * config object that forgot its `default` detectable (see {@link validateConfig})
22
+ * instead of being silently misparsed as an object-valued default.
23
+ */
24
+ function looksLikeConfig(value) {
25
+ return isPlainObject(value) && CONFIG_KEYS.some((key) => key in value);
6
26
  }
7
27
  function optionValues(options) {
8
28
  return options.map((option) => (isAttributeOption(option) ? option.value : option));
9
29
  }
10
30
  function normalizeAttribute(value) {
11
- const spec = isAttributeSpec(value) ? { ...value } : { default: value };
31
+ const spec = looksLikeConfig(value)
32
+ ? { ...value }
33
+ : { default: value };
12
34
  if (spec.options && spec.options.length > 0 && !spec.validate) {
13
35
  const allowed = optionValues(spec.options);
14
36
  spec.validate = (candidate) => allowed.includes(candidate);
@@ -31,9 +53,14 @@ function validateConfig(config) {
31
53
  throw new Error(`Block "${config.id}" must have a non-empty label`);
32
54
  }
33
55
  for (const [name, attr] of Object.entries(config.attributes)) {
34
- const normalized = normalizeAttribute(attr);
35
- if (!('default' in normalized)) {
36
- throw new Error(`Attribute "${name}" in block "${config.id}" must define a default value`);
56
+ // A plain object that carries config keys but no `default` is a config
57
+ // object that forgot its default (previously misparsed as an object-valued
58
+ // default, making this check unreachable). Objects with no config keys are
59
+ // valid shorthand object defaults and pass through.
60
+ if (looksLikeConfig(attr) && !('default' in attr)) {
61
+ throw new Error(`Attribute "${name}" in block "${config.id}" is a configuration object but does not ` +
62
+ `define a "default" value. If you meant an object as the default value, wrap it ` +
63
+ `explicitly as { default: { ... } }.`);
37
64
  }
38
65
  }
39
66
  if (config.content && config.behaviors?.inline) {
@@ -2,7 +2,9 @@ export { defineRuntimeBlock } from './defineBlock.js';
2
2
  export { coerceAttributeValue, inferAttributeInputKind, normalizeAttributeOptions, normalizeBlockAttributes, parseBlockDraftAttributes, serializeBlockAttributes, toAttributeDraftValues } from './attributes.js';
3
3
  export { normalizeMeta, parseMetaDraftValues, serializeMeta, toMetaDraftValues, validateMeta } from './meta.js';
4
4
  export { createBlockRegistry, createSchema, resolveRegistry } from './registry.js';
5
- export { CURRENT_DOCUMENT_VERSION, normalizeDocument } from './normalize.js';
5
+ export { CURRENT_DOCUMENT_VERSION, registerDocumentMigration, runDocumentMigrations } from './migrations.js';
6
+ export type { DocumentMigration } from './migrations.js';
7
+ export { normalizeDocument } from './normalize.js';
6
8
  export { validateDocument } from './validate.js';
7
9
  export type { BlockEditorMountHandle, BlockEditorMountOptions, BlockRuntimePlugin, NormalizedBlockComponentDefinition } from './runtime.js';
8
10
  export { coerceRichTextDocument, emptyRichTextDocument, hasRichTextContent, isRichTextDocument, richTextDocument, resolveRichTextFeatures } from '../shared/richText.js';
@@ -2,6 +2,7 @@ export { defineRuntimeBlock } from './defineBlock.js';
2
2
  export { coerceAttributeValue, inferAttributeInputKind, normalizeAttributeOptions, normalizeBlockAttributes, parseBlockDraftAttributes, serializeBlockAttributes, toAttributeDraftValues } from './attributes.js';
3
3
  export { normalizeMeta, parseMetaDraftValues, serializeMeta, toMetaDraftValues, validateMeta } from './meta.js';
4
4
  export { createBlockRegistry, createSchema, resolveRegistry } from './registry.js';
5
- export { CURRENT_DOCUMENT_VERSION, normalizeDocument } from './normalize.js';
5
+ export { CURRENT_DOCUMENT_VERSION, registerDocumentMigration, runDocumentMigrations } from './migrations.js';
6
+ export { normalizeDocument } from './normalize.js';
6
7
  export { validateDocument } from './validate.js';
7
8
  export { coerceRichTextDocument, emptyRichTextDocument, hasRichTextContent, isRichTextDocument, richTextDocument, resolveRichTextFeatures } from '../shared/richText.js';
@@ -0,0 +1,7 @@
1
+ import type { ValidateDocumentOptions, ValidationIssue } from './types.js';
2
+ /**
3
+ * Appends a validation issue to the running list and forwards it to the optional
4
+ * `onIssue` sink. Previously duplicated byte-for-byte in `validate.ts` and
5
+ * `meta.ts`; kept as one shared internal helper.
6
+ */
7
+ export declare function pushIssue(issues: ValidationIssue[], options: ValidateDocumentOptions | undefined, issue: ValidationIssue): void;
@@ -0,0 +1,9 @@
1
+ /**
2
+ * Appends a validation issue to the running list and forwards it to the optional
3
+ * `onIssue` sink. Previously duplicated byte-for-byte in `validate.ts` and
4
+ * `meta.ts`; kept as one shared internal helper.
5
+ */
6
+ export function pushIssue(issues, options, issue) {
7
+ issues.push(issue);
8
+ options?.onIssue?.(issue);
9
+ }
package/dist/core/meta.js CHANGED
@@ -1,11 +1,6 @@
1
1
  import { coerceAttributeValue, serializeAttributeValue, toAttributeDraftValue } from './attributes.js';
2
- function isRecord(value) {
3
- return typeof value === 'object' && value !== null && !Array.isArray(value);
4
- }
5
- function pushIssue(issues, options, issue) {
6
- issues.push(issue);
7
- options?.onIssue?.(issue);
8
- }
2
+ import { pushIssue } from './issues.js';
3
+ import { isPlainObject as isRecord } from '../shared/guards.js';
9
4
  export function normalizeMeta(meta, metaFields) {
10
5
  const source = isRecord(meta) ? meta : {};
11
6
  return Object.fromEntries(Array.from(metaFields, ([name, spec]) => [name, coerceAttributeValue(spec, source[name])]));
@@ -0,0 +1,30 @@
1
+ import type { PMDoc } from '../shared/document.js';
2
+ /**
3
+ * The document version stamped onto documents produced by `normalizeDocument`.
4
+ * Bump this when the persisted document shape changes, and register a
5
+ * migration for each intermediate version so older documents can be upgraded.
6
+ */
7
+ export declare const CURRENT_DOCUMENT_VERSION = 1;
8
+ export interface DocumentMigration {
9
+ /** The document version this migration upgrades from (to `from + 1`). */
10
+ from: number;
11
+ /** Upgrades a document from version `from` to version `from + 1`. */
12
+ migrate: (document: PMDoc) => PMDoc;
13
+ }
14
+ /**
15
+ * Registers a migration that upgrades documents from version `from` to
16
+ * `from + 1`. Returns a disposer that removes the registration (useful for
17
+ * tests and hot-reload scenarios).
18
+ */
19
+ export declare function registerDocumentMigration(migration: DocumentMigration): () => void;
20
+ /**
21
+ * Runs registered migrations stepwise from `fromVersion` up to `toVersion`
22
+ * (defaults to CURRENT_DOCUMENT_VERSION). Versions without a registered
23
+ * migration are passed through unchanged. The `version` field is not
24
+ * stamped here; callers such as `normalizeDocument` stamp the result.
25
+ *
26
+ * Only the registered migration versions inside `[fromVersion, toVersion)`
27
+ * are visited (in ascending order), so hostile version ranges from untrusted
28
+ * documents cannot make this loop over billions of integers.
29
+ */
30
+ export declare function runDocumentMigrations(document: PMDoc, fromVersion: number, toVersion?: number): PMDoc;
@@ -0,0 +1,43 @@
1
+ /**
2
+ * The document version stamped onto documents produced by `normalizeDocument`.
3
+ * Bump this when the persisted document shape changes, and register a
4
+ * migration for each intermediate version so older documents can be upgraded.
5
+ */
6
+ export const CURRENT_DOCUMENT_VERSION = 1;
7
+ const migrations = new Map();
8
+ /**
9
+ * Registers a migration that upgrades documents from version `from` to
10
+ * `from + 1`. Returns a disposer that removes the registration (useful for
11
+ * tests and hot-reload scenarios).
12
+ */
13
+ export function registerDocumentMigration(migration) {
14
+ if (!Number.isInteger(migration.from)) {
15
+ throw new Error(`Document migration "from" must be an integer, got ${migration.from}`);
16
+ }
17
+ migrations.set(migration.from, migration.migrate);
18
+ return () => {
19
+ if (migrations.get(migration.from) === migration.migrate) {
20
+ migrations.delete(migration.from);
21
+ }
22
+ };
23
+ }
24
+ /**
25
+ * Runs registered migrations stepwise from `fromVersion` up to `toVersion`
26
+ * (defaults to CURRENT_DOCUMENT_VERSION). Versions without a registered
27
+ * migration are passed through unchanged. The `version` field is not
28
+ * stamped here; callers such as `normalizeDocument` stamp the result.
29
+ *
30
+ * Only the registered migration versions inside `[fromVersion, toVersion)`
31
+ * are visited (in ascending order), so hostile version ranges from untrusted
32
+ * documents cannot make this loop over billions of integers.
33
+ */
34
+ export function runDocumentMigrations(document, fromVersion, toVersion = CURRENT_DOCUMENT_VERSION) {
35
+ const applicable = [...migrations.entries()]
36
+ .filter(([version]) => version >= fromVersion && version < toVersion)
37
+ .sort(([a], [b]) => a - b);
38
+ let migrated = document;
39
+ for (const [, migrate] of applicable) {
40
+ migrated = migrate(migrated);
41
+ }
42
+ return migrated;
43
+ }
@@ -1,5 +1,16 @@
1
1
  import type { PMDoc } from '../shared/document.js';
2
2
  import type { ContentSchema } from './types.js';
3
3
  import { resolveRegistry } from './registry.js';
4
- export declare const CURRENT_DOCUMENT_VERSION = 1;
4
+ export { CURRENT_DOCUMENT_VERSION } from './migrations.js';
5
+ /**
6
+ * Sanitizes the structural shape of a raw document (object nodes with string
7
+ * types, valid text nodes, array content/marks, object attrs — no schema or
8
+ * block-attribute normalization) and runs the registered migrations on the
9
+ * result, so migration callbacks never receive hostile shapes. A throwing
10
+ * migration never propagates: on throw the sanitized-but-unmigrated document
11
+ * is returned so normalization can proceed.
12
+ *
13
+ * Exported for tests; hosts run migrations via `normalizeDocument`.
14
+ */
15
+ export declare function migrateDocument(source: Partial<PMDoc>, fromVersion: number, toVersion?: number): PMDoc;
5
16
  export declare function normalizeDocument(document: Partial<PMDoc> | null | undefined, blocks: Parameters<typeof resolveRegistry>[0], schema?: ContentSchema): PMDoc;
@@ -1,44 +1,133 @@
1
- import { resolveRegistry } from './registry.js';
1
+ import { createSchema, resolveRegistry } from './registry.js';
2
2
  import { normalizeBlockAttributes } from './attributes.js';
3
3
  import { normalizeMeta } from './meta.js';
4
- export const CURRENT_DOCUMENT_VERSION = 1;
4
+ import { CURRENT_DOCUMENT_VERSION, runDocumentMigrations } from './migrations.js';
5
+ import { isPlainObject } from '../shared/guards.js';
6
+ export { CURRENT_DOCUMENT_VERSION } from './migrations.js';
7
+ function hasStringType(value) {
8
+ return isPlainObject(value) && typeof value.type === 'string';
9
+ }
5
10
  function normalizeMarks(marks, schema) {
6
- if (!marks)
11
+ if (!Array.isArray(marks))
7
12
  return undefined;
8
- const normalized = marks.filter((mark) => Boolean(mark?.type) && (!schema || schema.allowedMarks.has(mark.type)));
13
+ const normalized = [];
14
+ for (const mark of marks) {
15
+ if (!hasStringType(mark))
16
+ continue;
17
+ if (schema && !schema.allowedMarks.has(mark.type))
18
+ continue;
19
+ const candidate = mark;
20
+ if (candidate.attrs !== undefined && !isPlainObject(candidate.attrs)) {
21
+ const { attrs: _attrs, ...rest } = candidate;
22
+ void _attrs;
23
+ normalized.push(rest);
24
+ continue;
25
+ }
26
+ normalized.push(candidate);
27
+ }
9
28
  return normalized.length ? normalized : undefined;
10
29
  }
30
+ function normalizeContent(content, registryBlocks, schema) {
31
+ if (!Array.isArray(content))
32
+ return undefined;
33
+ const normalized = [];
34
+ for (const child of content) {
35
+ const node = normalizeNode(child, registryBlocks, schema);
36
+ if (node)
37
+ normalized.push(node);
38
+ }
39
+ return normalized;
40
+ }
11
41
  function normalizeNode(node, registryBlocks, schema) {
12
- const block = registryBlocks.get(node.type);
13
- const normalizedContent = Array.isArray(node.content)
14
- ? node.content.map((child) => normalizeNode(child, registryBlocks, schema))
15
- : undefined;
42
+ if (!hasStringType(node)) {
43
+ return undefined;
44
+ }
45
+ const candidate = node;
46
+ // ProseMirror rejects text nodes whose `text` is missing or non-string
47
+ // ("Invalid text node in JSON") and empty-string text nodes ("Empty text
48
+ // nodes are not allowed"); either error makes Tiptap silently replace the
49
+ // entire document with empty content, so drop such nodes here.
50
+ if (candidate.type === 'text' &&
51
+ (typeof candidate.text !== 'string' || candidate.text.length === 0)) {
52
+ return undefined;
53
+ }
54
+ const attrs = isPlainObject(candidate.attrs) ? candidate.attrs : undefined;
55
+ const marks = normalizeMarks(candidate.marks, schema);
56
+ const content = normalizeContent(candidate.content, registryBlocks, schema);
57
+ const block = registryBlocks.get(candidate.type);
16
58
  if (block) {
17
59
  return {
18
- type: node.type,
19
- attrs: normalizeBlockAttributes(block, node.attrs ?? {}),
20
- marks: normalizeMarks(node.marks, schema),
21
- content: block.content ? normalizedContent : undefined
60
+ type: candidate.type,
61
+ attrs: normalizeBlockAttributes(block, attrs ?? {}),
62
+ marks,
63
+ content: block.content ? content : undefined
22
64
  };
23
65
  }
24
66
  return {
25
- ...node,
26
- marks: normalizeMarks(node.marks, schema),
27
- content: normalizedContent
67
+ ...candidate,
68
+ attrs,
69
+ marks,
70
+ content
71
+ };
72
+ }
73
+ const NO_REGISTRY_BLOCKS = new Map();
74
+ /**
75
+ * Sanitizes the structural shape of a raw document (object nodes with string
76
+ * types, valid text nodes, array content/marks, object attrs — no schema or
77
+ * block-attribute normalization) and runs the registered migrations on the
78
+ * result, so migration callbacks never receive hostile shapes. A throwing
79
+ * migration never propagates: on throw the sanitized-but-unmigrated document
80
+ * is returned so normalization can proceed.
81
+ *
82
+ * Exported for tests; hosts run migrations via `normalizeDocument`.
83
+ */
84
+ export function migrateDocument(source, fromVersion, toVersion) {
85
+ const sanitized = {
86
+ type: 'doc',
87
+ content: normalizeContent(source.content, NO_REGISTRY_BLOCKS) ?? []
28
88
  };
89
+ if (isPlainObject(source.meta)) {
90
+ sanitized.meta = source.meta;
91
+ }
92
+ try {
93
+ return runDocumentMigrations(sanitized, fromVersion, toVersion);
94
+ }
95
+ catch {
96
+ return sanitized;
97
+ }
29
98
  }
30
99
  export function normalizeDocument(document, blocks, schema) {
31
100
  const registry = resolveRegistry(blocks);
32
- const registryBlocks = new Map(registry.blocks.map((block) => [block.id, block]));
33
- const content = Array.isArray(document?.content) ? document.content : [];
34
- const metaFields = schema?.metaFields ?? new Map();
101
+ const registryBlocks = registry.byId;
102
+ // When the host passes no schema, fall back to the registry's default
103
+ // schema (default allowed-mark set) so arbitrary mark types are still
104
+ // filtered out — unknown marks crash ProseMirror's nodeFromJSON, which
105
+ // makes Tiptap replace the whole document with empty content.
106
+ const effectiveSchema = schema ?? createSchema(registry);
107
+ const source = isPlainObject(document) ? document : {};
108
+ const rawVersion = source.version;
109
+ // Only treat the stored version as meaningful when it is a positive safe
110
+ // integer; hostile or bogus values (negative, zero, fractional, NaN,
111
+ // Infinity, beyond MAX_SAFE_INTEGER) are handled like a missing version.
112
+ // This also keeps attacker-supplied versions from producing huge
113
+ // migration ranges.
114
+ const sourceVersion = typeof rawVersion === 'number' && Number.isSafeInteger(rawVersion) && rawVersion >= 1
115
+ ? rawVersion
116
+ : 1;
117
+ let working = source;
118
+ if (sourceVersion < CURRENT_DOCUMENT_VERSION) {
119
+ working = migrateDocument(source, sourceVersion);
120
+ }
121
+ const metaFields = effectiveSchema.metaFields;
35
122
  const normalized = {
36
123
  type: 'doc',
37
- version: CURRENT_DOCUMENT_VERSION,
38
- content: content.map((node) => normalizeNode(node, registryBlocks, schema))
124
+ // Never silently downgrade documents from a newer version; hosts are
125
+ // notified via validateDocument's UNSUPPORTED_VERSION issue.
126
+ version: sourceVersion > CURRENT_DOCUMENT_VERSION ? sourceVersion : CURRENT_DOCUMENT_VERSION,
127
+ content: normalizeContent(working.content, registryBlocks, effectiveSchema) ?? []
39
128
  };
40
129
  if (metaFields.size > 0) {
41
- normalized.meta = normalizeMeta(document?.meta, metaFields);
130
+ normalized.meta = normalizeMeta(working.meta, metaFields);
42
131
  }
43
132
  return normalized;
44
133
  }
@@ -1,4 +1,11 @@
1
1
  import type { BlockDefinition, BlockRegistry, ContentSchema, CreateSchemaOptions } from './types.js';
2
+ /**
3
+ * The default mark universe a schema allows when the host does not pass an
4
+ * explicit `allowedMarks`. This is the single source of truth for the default
5
+ * marks — the editor's base extensions (`shared/tiptap.ts`) consume it too, so
6
+ * the fallback schema and the fallback extension set never drift apart.
7
+ */
8
+ export declare const DEFAULT_MARKS: readonly ["bold", "italic", "strike", "code", "link"];
2
9
  export declare function createBlockRegistry(blocks: BlockDefinition[]): BlockRegistry;
3
10
  export declare function createSchema(registry: BlockRegistry, options?: CreateSchemaOptions): ContentSchema;
4
11
  export declare function resolveRegistry(blocks: BlockRegistry | BlockDefinition[]): BlockRegistry;