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.
- package/README.md +75 -8
- package/dist/core/attributes.d.ts +7 -1
- package/dist/core/attributes.js +35 -16
- package/dist/core/defineBlock.js +36 -9
- package/dist/core/index.d.ts +3 -1
- package/dist/core/index.js +2 -1
- package/dist/core/issues.d.ts +7 -0
- package/dist/core/issues.js +9 -0
- package/dist/core/meta.js +2 -7
- package/dist/core/migrations.d.ts +30 -0
- package/dist/core/migrations.js +43 -0
- package/dist/core/normalize.d.ts +12 -1
- package/dist/core/normalize.js +110 -21
- package/dist/core/registry.d.ts +7 -0
- package/dist/core/registry.js +22 -4
- package/dist/core/runtime.d.ts +7 -0
- package/dist/core/types.d.ts +8 -2
- package/dist/core/validate.js +22 -6
- package/dist/editor/AttributeFieldControl.svelte +31 -3
- package/dist/editor/BlockAttributesPanel.svelte +35 -30
- package/dist/editor/BlockAttributesPanel.svelte.d.ts +9 -1
- package/dist/editor/Editor.svelte +5 -16
- package/dist/editor/RichTextAttributeEditor.svelte +75 -145
- package/dist/editor/RichTextAttributeEditor.svelte.d.ts +2 -1
- package/dist/editor/Toolbar.svelte +2 -3
- package/dist/editor/attributeTargets.d.ts +23 -0
- package/dist/editor/attributeTargets.js +21 -0
- package/dist/editor/attributesController.d.ts +7 -0
- package/dist/editor/attributesController.js +118 -229
- package/dist/editor/bindEditor.js +102 -26
- package/dist/editor/chooseAttribute.d.ts +26 -0
- package/dist/editor/chooseAttribute.js +10 -0
- package/dist/editor/containerChildOps.d.ts +33 -0
- package/dist/editor/containerChildOps.js +94 -0
- package/dist/editor/dropdownDismiss.d.ts +18 -0
- package/dist/editor/dropdownDismiss.js +46 -0
- package/dist/editor/index.d.ts +3 -1
- package/dist/editor/index.js +2 -1
- package/dist/editor/linkController.d.ts +19 -0
- package/dist/editor/linkController.js +72 -0
- package/dist/editor/toolbarFeatures.d.ts +12 -0
- package/dist/editor/toolbarFeatures.js +36 -0
- package/dist/render/Renderer.svelte +1 -1
- package/dist/render/RichContent.svelte +2 -2
- package/dist/render/RichNode.svelte +16 -2
- package/dist/render/sanitize.d.ts +6 -0
- package/dist/render/sanitize.js +20 -1
- package/dist/runtime/reactiveProps.svelte.d.ts +16 -0
- package/dist/runtime/reactiveProps.svelte.js +16 -0
- package/dist/runtime/svelte.d.ts +2 -1
- package/dist/runtime/svelte.js +26 -6
- package/dist/shared/EditorBlockFixture.svelte +24 -0
- package/dist/shared/EditorBlockFixture.svelte.d.ts +9 -0
- package/dist/shared/content.js +2 -1
- package/dist/shared/guards.d.ts +13 -0
- package/dist/shared/guards.js +16 -0
- package/dist/shared/richText.js +20 -4
- package/dist/shared/runtimeId.d.ts +8 -0
- package/dist/shared/runtimeId.js +8 -0
- package/dist/shared/tiptap.js +58 -23
- package/dist/web-components/UncialEditor.svelte +16 -1
- package/dist/web-components/UncialEditor.svelte.d.ts +5 -2
- package/dist/web-components/index.d.ts +39 -10
- package/dist/web-components/index.js +86 -36
- package/dist/web-components/reactiveProps.svelte.d.ts +10 -0
- package/dist/web-components/reactiveProps.svelte.js +13 -0
- 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
|
-
|
|
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
|
-
|
|
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`:
|
|
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
|
-
|
|
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;
|
package/dist/core/attributes.js
CHANGED
|
@@ -1,7 +1,5 @@
|
|
|
1
1
|
import { coerceRichTextDocument } from '../shared/richText.js';
|
|
2
|
-
|
|
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
|
-
|
|
14
|
-
|
|
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
|
-
|
|
50
|
-
|
|
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
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
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;
|
package/dist/core/defineBlock.js
CHANGED
|
@@ -1,14 +1,36 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
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 =
|
|
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
|
-
|
|
35
|
-
|
|
36
|
-
|
|
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) {
|
package/dist/core/index.d.ts
CHANGED
|
@@ -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,
|
|
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';
|
package/dist/core/index.js
CHANGED
|
@@ -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,
|
|
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
|
-
|
|
3
|
-
|
|
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
|
+
}
|
package/dist/core/normalize.d.ts
CHANGED
|
@@ -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
|
|
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;
|
package/dist/core/normalize.js
CHANGED
|
@@ -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
|
-
|
|
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 =
|
|
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
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
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:
|
|
19
|
-
attrs: normalizeBlockAttributes(block,
|
|
20
|
-
marks
|
|
21
|
-
content: block.content ?
|
|
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
|
-
...
|
|
26
|
-
|
|
27
|
-
|
|
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 =
|
|
33
|
-
|
|
34
|
-
|
|
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
|
|
38
|
-
|
|
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(
|
|
130
|
+
normalized.meta = normalizeMeta(working.meta, metaFields);
|
|
42
131
|
}
|
|
43
132
|
return normalized;
|
|
44
133
|
}
|
package/dist/core/registry.d.ts
CHANGED
|
@@ -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;
|