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.
- package/README.md +174 -11
- 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 +5 -2
- package/dist/core/index.js +3 -1
- package/dist/core/issues.d.ts +7 -0
- package/dist/core/issues.js +9 -0
- package/dist/core/meta.d.ts +7 -0
- package/dist/core/meta.js +67 -0
- 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 +115 -20
- package/dist/core/registry.d.ts +7 -0
- package/dist/core/registry.js +25 -5
- package/dist/core/runtime.d.ts +7 -0
- package/dist/core/types.d.ts +12 -2
- package/dist/core/validate.js +24 -6
- package/dist/editor/AttributeFieldControl.svelte +141 -0
- package/dist/editor/AttributeFieldControl.svelte.d.ts +12 -0
- package/dist/editor/BlockAttributesPanel.svelte +74 -162
- package/dist/editor/BlockAttributesPanel.svelte.d.ts +9 -1
- package/dist/editor/BlockMenu.svelte +24 -35
- package/dist/editor/BlockMenu.svelte.d.ts +5 -19
- package/dist/editor/DocumentMetaPanel.svelte +69 -0
- package/dist/editor/DocumentMetaPanel.svelte.d.ts +10 -0
- package/dist/editor/Editor.svelte +131 -263
- package/dist/editor/Editor.svelte.d.ts +6 -2
- package/dist/editor/LinkAttributesPanel.svelte +32 -19
- package/dist/editor/RichTextAttributeEditor.svelte +81 -141
- package/dist/editor/RichTextAttributeEditor.svelte.d.ts +2 -1
- package/dist/editor/Toolbar.svelte +42 -10
- 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.d.ts +2 -0
- package/dist/editor/bindEditor.js +108 -27
- 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 +7 -1
- package/dist/editor/index.js +5 -1
- package/dist/editor/linkController.d.ts +19 -0
- package/dist/editor/linkController.js +72 -0
- package/dist/editor/metaController.d.ts +19 -0
- package/dist/editor/metaController.js +71 -0
- package/dist/editor/toolbarFeatures.d.ts +12 -0
- package/dist/editor/toolbarFeatures.js +36 -0
- package/dist/render/Renderer.svelte +13 -4
- package/dist/render/Renderer.svelte.d.ts +2 -0
- package/dist/render/RichContent.svelte +2 -2
- package/dist/render/RichNode.svelte +18 -9
- package/dist/render/RichText.svelte +2 -1
- 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.d.ts +2 -1
- package/dist/shared/content.js +9 -3
- package/dist/shared/document.d.ts +1 -0
- 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/styles/base.css +418 -0
- package/dist/styles/chrome.css +3 -0
- package/dist/styles/controls.css +306 -0
- package/dist/styles/index.css +2 -0
- package/dist/styles/prose.css +115 -0
- package/dist/styles/tokens.css +77 -0
- 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 +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
|

|
|
10
10
|

|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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`:
|
|
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
|
-
|
|
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
|
@@ -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,
|
|
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';
|
package/dist/core/index.js
CHANGED
|
@@ -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,
|
|
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
|
+
}
|