uncial 0.0.6 → 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 (88) hide show
  1. package/README.md +174 -11
  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 +5 -2
  6. package/dist/core/index.js +3 -1
  7. package/dist/core/issues.d.ts +7 -0
  8. package/dist/core/issues.js +9 -0
  9. package/dist/core/meta.d.ts +7 -0
  10. package/dist/core/meta.js +67 -0
  11. package/dist/core/migrations.d.ts +30 -0
  12. package/dist/core/migrations.js +43 -0
  13. package/dist/core/normalize.d.ts +12 -1
  14. package/dist/core/normalize.js +115 -20
  15. package/dist/core/registry.d.ts +7 -0
  16. package/dist/core/registry.js +25 -5
  17. package/dist/core/runtime.d.ts +7 -0
  18. package/dist/core/types.d.ts +12 -2
  19. package/dist/core/validate.js +24 -6
  20. package/dist/editor/AttributeFieldControl.svelte +141 -0
  21. package/dist/editor/AttributeFieldControl.svelte.d.ts +12 -0
  22. package/dist/editor/BlockAttributesPanel.svelte +74 -162
  23. package/dist/editor/BlockAttributesPanel.svelte.d.ts +9 -1
  24. package/dist/editor/BlockMenu.svelte +24 -35
  25. package/dist/editor/BlockMenu.svelte.d.ts +5 -19
  26. package/dist/editor/DocumentMetaPanel.svelte +69 -0
  27. package/dist/editor/DocumentMetaPanel.svelte.d.ts +10 -0
  28. package/dist/editor/Editor.svelte +131 -263
  29. package/dist/editor/Editor.svelte.d.ts +6 -2
  30. package/dist/editor/LinkAttributesPanel.svelte +32 -19
  31. package/dist/editor/RichTextAttributeEditor.svelte +81 -141
  32. package/dist/editor/RichTextAttributeEditor.svelte.d.ts +2 -1
  33. package/dist/editor/Toolbar.svelte +42 -10
  34. package/dist/editor/attributeTargets.d.ts +23 -0
  35. package/dist/editor/attributeTargets.js +21 -0
  36. package/dist/editor/attributesController.d.ts +7 -0
  37. package/dist/editor/attributesController.js +118 -229
  38. package/dist/editor/bindEditor.d.ts +2 -0
  39. package/dist/editor/bindEditor.js +108 -27
  40. package/dist/editor/chooseAttribute.d.ts +26 -0
  41. package/dist/editor/chooseAttribute.js +10 -0
  42. package/dist/editor/containerChildOps.d.ts +33 -0
  43. package/dist/editor/containerChildOps.js +94 -0
  44. package/dist/editor/dropdownDismiss.d.ts +18 -0
  45. package/dist/editor/dropdownDismiss.js +46 -0
  46. package/dist/editor/index.d.ts +7 -1
  47. package/dist/editor/index.js +5 -1
  48. package/dist/editor/linkController.d.ts +19 -0
  49. package/dist/editor/linkController.js +72 -0
  50. package/dist/editor/metaController.d.ts +19 -0
  51. package/dist/editor/metaController.js +71 -0
  52. package/dist/editor/toolbarFeatures.d.ts +12 -0
  53. package/dist/editor/toolbarFeatures.js +36 -0
  54. package/dist/render/Renderer.svelte +13 -4
  55. package/dist/render/Renderer.svelte.d.ts +2 -0
  56. package/dist/render/RichContent.svelte +2 -2
  57. package/dist/render/RichNode.svelte +18 -9
  58. package/dist/render/RichText.svelte +2 -1
  59. package/dist/render/sanitize.d.ts +6 -0
  60. package/dist/render/sanitize.js +20 -1
  61. package/dist/runtime/reactiveProps.svelte.d.ts +16 -0
  62. package/dist/runtime/reactiveProps.svelte.js +16 -0
  63. package/dist/runtime/svelte.d.ts +2 -1
  64. package/dist/runtime/svelte.js +26 -6
  65. package/dist/shared/EditorBlockFixture.svelte +24 -0
  66. package/dist/shared/EditorBlockFixture.svelte.d.ts +9 -0
  67. package/dist/shared/content.d.ts +2 -1
  68. package/dist/shared/content.js +9 -3
  69. package/dist/shared/document.d.ts +1 -0
  70. package/dist/shared/guards.d.ts +13 -0
  71. package/dist/shared/guards.js +16 -0
  72. package/dist/shared/richText.js +20 -4
  73. package/dist/shared/runtimeId.d.ts +8 -0
  74. package/dist/shared/runtimeId.js +8 -0
  75. package/dist/shared/tiptap.js +58 -23
  76. package/dist/styles/base.css +418 -0
  77. package/dist/styles/chrome.css +3 -0
  78. package/dist/styles/controls.css +306 -0
  79. package/dist/styles/index.css +2 -0
  80. package/dist/styles/prose.css +115 -0
  81. package/dist/styles/tokens.css +77 -0
  82. package/dist/web-components/UncialEditor.svelte +16 -1
  83. package/dist/web-components/UncialEditor.svelte.d.ts +5 -2
  84. package/dist/web-components/index.d.ts +39 -10
  85. package/dist/web-components/index.js +86 -36
  86. package/dist/web-components/reactiveProps.svelte.d.ts +10 -0
  87. package/dist/web-components/reactiveProps.svelte.js +13 -0
  88. package/package.json +7 -1
package/README.md CHANGED
@@ -8,6 +8,7 @@ Custom blocks can stay atomic or declare one default child content region for ne
8
8
 
9
9
  ![screenshot of the Uncial richtext and block editorwith a callout component selected](.github/images/basic%20editor.png)
10
10
  ![screen recording demonstrating editing main page text and custom components](.github/images/basic%20text%20and%20component%20editing.gif)
11
+
11
12
  ## What ships today
12
13
 
13
14
  - Shared block definitions for editor and renderer
@@ -56,6 +57,7 @@ Then register and use that component as an Uncial block:
56
57
 
57
58
  ```svelte
58
59
  <script lang="ts">
60
+ import 'uncial/styles';
59
61
  import {
60
62
  Editor,
61
63
  Renderer,
@@ -71,9 +73,7 @@ Then register and use that component as an Uncial block:
71
73
  label: 'Promo Card',
72
74
  attributes: {
73
75
  title: '',
74
- featured: false,
75
- priority: 0,
76
- metadata: { default: { theme: 'sand' }, input: 'json' }
76
+ body: { default: '', input: 'textarea' }
77
77
  },
78
78
  component: PromoCard
79
79
  });
@@ -108,18 +108,56 @@ Object.assign(renderer, { blocks, schema, content: document });
108
108
 
109
109
  const editor = document.querySelector('uncial-editor');
110
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 });
111
115
  ```
112
116
 
113
117
  ```html
114
- <uncial-editor></uncial-editor>
115
- <uncial-renderer></uncial-renderer>
118
+ <uncial-editor></uncial-editor> <uncial-renderer></uncial-renderer>
119
+ ```
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;
116
146
  ```
117
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
+
118
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`:
119
153
 
120
154
  ```ts
121
155
  editor.addEventListener('uncial-change', (event) => {
122
- 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
123
161
  });
124
162
 
125
163
  renderer.addEventListener('uncial-issue', (event) => {
@@ -127,6 +165,8 @@ renderer.addEventListener('uncial-issue', (event) => {
127
165
  });
128
166
  ```
129
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
+
130
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.
131
171
 
132
172
  ## Runtime plugins
@@ -148,7 +188,102 @@ export function defineReactBlock(config) {
148
188
 
149
189
  ## Styling and customization
150
190
 
151
- The root `Editor` and `Renderer` exports ship with Uncial's starter shell and default component-scoped styling.
191
+ The root `Editor` and `Renderer` exports ship stable `uncial-*` classes and optional default CSS. Import the CSS layer you want once in your app:
192
+
193
+ ```ts
194
+ // Full default editor, renderer, controls, and rich text prose styles.
195
+ import 'uncial/styles';
196
+
197
+ // Editor chrome only. Use this if your app owns rich text typography.
198
+ import 'uncial/styles/chrome';
199
+ ```
200
+
201
+ Uncial does not require Tailwind or DaisyUI. The default styles are plain CSS and are driven by `--uncial-*` custom properties that you can scope to your app, page, or a wrapper around the editor:
202
+
203
+ ```css
204
+ .my-editor-theme {
205
+ --brand-primary: #8b5cf6;
206
+ --brand-surface: #101012;
207
+ --brand-border: #303039;
208
+ }
209
+
210
+ .my-editor-theme .uncial-editor-shell,
211
+ .my-editor-theme .uncial-renderer,
212
+ .my-editor-theme .uncial-attrs-panel,
213
+ .my-editor-theme .uncial-link-panel,
214
+ .my-editor-theme .uncial-richtext-wrapper,
215
+ .my-editor-theme .uncial-block-menu {
216
+ --uncial-color-surface: var(--brand-surface);
217
+ --uncial-color-surface-elevated: #19191d;
218
+ --uncial-color-border: var(--brand-border);
219
+ --uncial-color-text: #f4f4f5;
220
+ --uncial-color-primary: var(--brand-primary);
221
+ --uncial-color-primary-contrast: #ffffff;
222
+ --uncial-color-accent: #f59e0b;
223
+ --uncial-color-focus-ring: var(--brand-primary);
224
+ --uncial-color-code-bg: #171717;
225
+ --uncial-color-code-text: #fafafa;
226
+
227
+ --uncial-radius-sm: 0.375rem;
228
+ --uncial-radius-md: 0.625rem;
229
+ --uncial-radius-lg: 1rem;
230
+
231
+ --uncial-font-body: Inter, system-ui, sans-serif;
232
+ }
233
+ ```
234
+
235
+ Wrap the editor with that class:
236
+
237
+ ```svelte
238
+ <div class="my-editor-theme">
239
+ <Editor {blocks} {schema} bind:json={document} />
240
+ <Renderer content={document} {blocks} {schema} />
241
+ </div>
242
+ ```
243
+
244
+ Core token groups:
245
+
246
+ | Token | Purpose |
247
+ | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------ |
248
+ | `--uncial-color-bg`, `--uncial-color-surface`, `--uncial-color-surface-elevated` | Page/editor surfaces |
249
+ | `--uncial-color-border`, `--uncial-color-border-strong` | Borders and separators |
250
+ | `--uncial-color-text`, `--uncial-color-text-muted`, `--uncial-color-text-inverted` | Foreground colors |
251
+ | `--uncial-color-primary`, `--uncial-color-primary-contrast`, `--uncial-color-accent`, `--uncial-color-danger`, `--uncial-color-focus-ring` | Actions, links, errors, focus states |
252
+ | `--uncial-color-code-bg`, `--uncial-color-code-text` | Fenced code block colors |
253
+ | `--uncial-font-body`, `--uncial-font-display`, `--uncial-font-mono` | Typography families |
254
+ | `--uncial-font-size-base`, `--uncial-line-height`, `--uncial-font-weight-regular`, `--uncial-font-weight-strong` | Typography scale |
255
+ | `--uncial-radius-sm`, `--uncial-radius-md`, `--uncial-radius-lg` | Control and shell radii |
256
+ | `--uncial-space-1` through `--uncial-space-6` | Spacing scale |
257
+ | `--uncial-gutter-width`, `--uncial-gutter-width-sm`, `--uncial-toolbar-gap`, `--uncial-panel-width` | Editor structure |
258
+ | `--uncial-shadow-sm`, `--uncial-shadow-md`, `--uncial-transition` | Depth and motion |
259
+
260
+ Rich text output uses the stable `.uncial-rich-content` hook. To bring your own prose styles, import only the chrome layer and target that class:
261
+
262
+ ```ts
263
+ import 'uncial/styles/chrome';
264
+ ```
265
+
266
+ ```css
267
+ .article-editor .uncial-rich-content {
268
+ font: 400 1rem/1.7 var(--site-body-font);
269
+ color: var(--site-ink);
270
+ }
271
+
272
+ .article-editor .uncial-rich-content h2 {
273
+ font: 700 1.75rem/1.2 var(--site-display-font);
274
+ margin-block: 2rem 0.75rem;
275
+ }
276
+ ```
277
+
278
+ If you use Tailwind Typography, apply it to the same hook in your app stylesheet:
279
+
280
+ ```css
281
+ .article-editor .uncial-rich-content {
282
+ @apply prose prose-neutral max-w-none;
283
+ }
284
+ ```
285
+
286
+ Phosphor is the default icon set for Uncial controls. Icon override props are planned for a future theming tier.
152
287
 
153
288
  If you want to own the editor layout yourself, use `bindEditor(...)` on an element you control:
154
289
 
@@ -188,27 +323,35 @@ Use `component` when the same Svelte component should render in both the editor
188
323
  const hero = defineSvelteBlock({
189
324
  id: 'hero',
190
325
  label: 'Hero',
326
+ description: 'Full-width intro banner', // optional; shown in the insert menu
191
327
  attributes: {
192
328
  title: '',
193
329
  subtitle: { default: '', input: 'textarea' },
194
330
  featured: false,
195
331
  priority: 1,
332
+ align: { default: 'left', options: ['left', 'center', 'right'] },
196
333
  settings: { default: { align: 'left' }, input: 'json' }
197
334
  },
198
335
  component: Hero
199
336
  });
200
337
  ```
201
338
 
202
- Attribute specs support:
339
+ A bare value (`title: ''`) is shorthand for `{ default: '' }`. The full attribute
340
+ spec supports:
203
341
 
204
342
  - `default`: required default value
205
343
  - `required`: require a value at validation time
206
344
  - `validate`: custom validation predicate
207
345
  - `parse`: custom coercion from editor or serialized input
208
346
  - `serialize`: custom serialization for HTML persistence
209
- - `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
210
350
  - `placeholder`: optional editor placeholder
211
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
+
212
355
  Blocks can also opt into child content:
213
356
 
214
357
  ```ts
@@ -272,8 +415,7 @@ Use `validateDocument(...)` directly or pass `onIssue` into `Editor` or `Rendere
272
415
  {schema}
273
416
  bind:json={document}
274
417
  onIssue={(issue) => console.warn(issue.code, issue.path)}
275
- /
276
- >
418
+ />
277
419
  ```
278
420
 
279
421
  ## Rendering and security
@@ -283,6 +425,27 @@ Use `validateDocument(...)` directly or pass `onIssue` into `Editor` or `Rendere
283
425
  - Links are sanitized to allow only `http`, `https`, `mailto`, `tel`, relative paths, and hash links
284
426
  - Custom block components and `html.render` hooks are trusted application code; sanitize any raw HTML or navigation attributes they emit
285
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
+
286
449
  ## Development
287
450
 
288
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) {
@@ -1,8 +1,11 @@
1
1
  export { defineRuntimeBlock } from './defineBlock.js';
2
2
  export { coerceAttributeValue, inferAttributeInputKind, normalizeAttributeOptions, normalizeBlockAttributes, parseBlockDraftAttributes, serializeBlockAttributes, toAttributeDraftValues } from './attributes.js';
3
+ export { normalizeMeta, parseMetaDraftValues, serializeMeta, toMetaDraftValues, validateMeta } from './meta.js';
3
4
  export { createBlockRegistry, createSchema, resolveRegistry } from './registry.js';
4
- 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';
5
8
  export { validateDocument } from './validate.js';
6
9
  export type { BlockEditorMountHandle, BlockEditorMountOptions, BlockRuntimePlugin, NormalizedBlockComponentDefinition } from './runtime.js';
7
10
  export { coerceRichTextDocument, emptyRichTextDocument, hasRichTextContent, isRichTextDocument, richTextDocument, resolveRichTextFeatures } from '../shared/richText.js';
8
- export type { AttributeConfig, AttributeInputKind, AttributeOption, AttrParser, AttrSerializer, AttributeSpec, BlockAttributes, BlockBehavior, BlockComponentProps, BlockConfig, BlockContentDefinition, BlockContentKind, BlockDefinition, BlockIcon, BlockMetadata, BlockRegistry, ContentDocument, ContentSchema, CreateSchemaOptions, RichTextFeature, RichTextFeatureSelection, RuntimeBlockConfig, ValidateDocumentOptions, ValidationCode, ValidationIssue, ValidationResult } from './types.js';
11
+ export type { AttributeConfig, AttributeInputKind, AttributeOption, AttrParser, AttrSerializer, AttributeSpec, BlockAttributes, BlockBehavior, BlockComponentProps, BlockConfig, BlockContentDefinition, BlockContentKind, BlockDefinition, BlockIcon, BlockMetadata, BlockRegistry, ContentDocument, ContentSchema, CreateSchemaOptions, DocumentMetaSchema, MetaFieldSpec, RichTextFeature, RichTextFeatureSelection, RuntimeBlockConfig, ValidateDocumentOptions, ValidationCode, ValidationIssue, ValidationResult } from './types.js';
@@ -1,6 +1,8 @@
1
1
  export { defineRuntimeBlock } from './defineBlock.js';
2
2
  export { coerceAttributeValue, inferAttributeInputKind, normalizeAttributeOptions, normalizeBlockAttributes, parseBlockDraftAttributes, serializeBlockAttributes, toAttributeDraftValues } from './attributes.js';
3
+ export { normalizeMeta, parseMetaDraftValues, serializeMeta, toMetaDraftValues, validateMeta } from './meta.js';
3
4
  export { createBlockRegistry, createSchema, resolveRegistry } from './registry.js';
4
- export { CURRENT_DOCUMENT_VERSION, normalizeDocument } from './normalize.js';
5
+ export { CURRENT_DOCUMENT_VERSION, registerDocumentMigration, runDocumentMigrations } from './migrations.js';
6
+ export { normalizeDocument } from './normalize.js';
5
7
  export { validateDocument } from './validate.js';
6
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
+ }
@@ -0,0 +1,7 @@
1
+ import type { PMPath } from '../shared/document.js';
2
+ import type { AttributeSpec, ValidateDocumentOptions, ValidationIssue } from './types.js';
3
+ export declare function normalizeMeta(meta: unknown, metaFields: ReadonlyMap<string, AttributeSpec<unknown>>): Record<string, unknown>;
4
+ export declare function validateMeta(meta: unknown, metaFields: ReadonlyMap<string, AttributeSpec<unknown>>, issues: ValidationIssue[], options?: ValidateDocumentOptions, path?: PMPath): void;
5
+ export declare function toMetaDraftValues(metaFields: ReadonlyMap<string, AttributeSpec<unknown>>, meta?: Record<string, unknown>): Record<string, unknown>;
6
+ export declare function parseMetaDraftValues(metaFields: ReadonlyMap<string, AttributeSpec<unknown>>, draft: Record<string, unknown>): Record<string, unknown>;
7
+ export declare function serializeMeta(metaFields: ReadonlyMap<string, AttributeSpec<unknown>>, meta?: Record<string, unknown>): Record<string, unknown>;
@@ -0,0 +1,67 @@
1
+ import { coerceAttributeValue, serializeAttributeValue, toAttributeDraftValue } from './attributes.js';
2
+ import { pushIssue } from './issues.js';
3
+ import { isPlainObject as isRecord } from '../shared/guards.js';
4
+ export function normalizeMeta(meta, metaFields) {
5
+ const source = isRecord(meta) ? meta : {};
6
+ return Object.fromEntries(Array.from(metaFields, ([name, spec]) => [name, coerceAttributeValue(spec, source[name])]));
7
+ }
8
+ export function validateMeta(meta, metaFields, issues, options, path = ['meta']) {
9
+ const source = isRecord(meta) ? meta : {};
10
+ if (meta !== undefined && !isRecord(meta)) {
11
+ pushIssue(issues, options, {
12
+ code: 'INVALID_META',
13
+ path,
14
+ message: 'Document metadata must be an object',
15
+ severity: 'error',
16
+ details: { value: meta }
17
+ });
18
+ return;
19
+ }
20
+ for (const name of Object.keys(source)) {
21
+ if (!metaFields.has(name)) {
22
+ pushIssue(issues, options, {
23
+ code: 'UNKNOWN_META',
24
+ path: [...path, name],
25
+ message: `Unknown metadata field "${name}"`,
26
+ severity: 'warning',
27
+ details: { field: name }
28
+ });
29
+ }
30
+ }
31
+ for (const [name, spec] of metaFields) {
32
+ const value = source[name];
33
+ const missing = value === undefined || value === null || value === '';
34
+ if (missing && spec.required) {
35
+ pushIssue(issues, options, {
36
+ code: 'INVALID_META',
37
+ path: [...path, name],
38
+ message: `Required metadata field "${name}" is missing`,
39
+ severity: 'error'
40
+ });
41
+ continue;
42
+ }
43
+ if (missing)
44
+ continue;
45
+ if (spec.validate && !spec.validate(value)) {
46
+ pushIssue(issues, options, {
47
+ code: 'INVALID_META',
48
+ path: [...path, name],
49
+ message: `Metadata field "${name}" is invalid`,
50
+ severity: 'error',
51
+ details: { value }
52
+ });
53
+ }
54
+ }
55
+ }
56
+ export function toMetaDraftValues(metaFields, meta = {}) {
57
+ return Object.fromEntries(Array.from(metaFields, ([name, spec]) => [name, toAttributeDraftValue(spec, meta[name])]));
58
+ }
59
+ export function parseMetaDraftValues(metaFields, draft) {
60
+ return Object.fromEntries(Array.from(metaFields, ([name, spec]) => [name, coerceAttributeValue(spec, draft[name])]));
61
+ }
62
+ export function serializeMeta(metaFields, meta = {}) {
63
+ return Object.fromEntries(Array.from(metaFields, ([name, spec]) => [
64
+ name,
65
+ serializeAttributeValue(spec, coerceAttributeValue(spec, meta[name]))
66
+ ]));
67
+ }
@@ -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
+ }