@stesura/svelte-wordgard 0.0.0-stage → 0.4.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/CHANGELOG.md +11 -0
- package/LICENSE.txt +21 -0
- package/README.md +403 -2
- package/THIRD_PARTY_LICENSES.txt +55 -0
- package/dist/SvelteDocTile.d.ts +15 -0
- package/dist/SvelteDocTile.js +227 -0
- package/dist/SvelteWordgard.d.ts +9 -0
- package/dist/SvelteWordgard.js +13 -0
- package/dist/components/ChildNodeViews.d.ts +57 -0
- package/dist/components/ChildNodeViews.js +159 -0
- package/dist/components/Decoration.svelte +20 -0
- package/dist/components/Decoration.svelte.d.ts +12 -0
- package/dist/components/DecorationRoot.svelte +35 -0
- package/dist/components/DecorationRoot.svelte.d.ts +10 -0
- package/dist/components/DecorationView.d.ts +16 -0
- package/dist/components/DecorationView.js +51 -0
- package/dist/components/NodeWrapperView.d.ts +15 -0
- package/dist/components/NodeWrapperView.js +103 -0
- package/dist/components/SeparatorHackView.d.ts +2 -0
- package/dist/components/SeparatorHackView.js +6 -0
- package/dist/components/ShapeView.d.ts +17 -0
- package/dist/components/ShapeView.js +94 -0
- package/dist/components/TextNodeView.d.ts +2 -0
- package/dist/components/TextNodeView.js +8 -0
- package/dist/components/TrailingHackView.d.ts +2 -0
- package/dist/components/TrailingHackView.js +4 -0
- package/dist/components/WidgetView.d.ts +9 -0
- package/dist/components/WidgetView.js +56 -0
- package/dist/components/WordgardDoc.svelte +40 -0
- package/dist/components/WordgardDoc.svelte.d.ts +3 -0
- package/dist/components/WordgardEditor.svelte +33 -0
- package/dist/components/WordgardEditor.svelte.d.ts +8 -0
- package/dist/components/WrappedNode.svelte +18 -0
- package/dist/components/WrappedNode.svelte.d.ts +3 -0
- package/dist/components/WrapperView.d.ts +12 -0
- package/dist/components/WrapperView.js +80 -0
- package/dist/components/marks/MarkView.d.ts +7 -0
- package/dist/components/marks/MarkView.js +16 -0
- package/dist/components/marks/SvelteMarkView.d.ts +4 -0
- package/dist/components/marks/SvelteMarkView.js +72 -0
- package/dist/components/nodes/DefaultNodeView.d.ts +24 -0
- package/dist/components/nodes/DefaultNodeView.js +201 -0
- package/dist/components/nodes/DocNodeView.d.ts +3 -0
- package/dist/components/nodes/DocNodeView.js +6 -0
- package/dist/contexts/DecorationContext.d.ts +13 -0
- package/dist/contexts/DecorationContext.js +12 -0
- package/dist/contexts/EditorContext.d.ts +5 -0
- package/dist/contexts/EditorContext.js +15 -0
- package/dist/contexts/WrappedContext.d.ts +6 -0
- package/dist/contexts/WrappedContext.js +10 -0
- package/dist/decorations/SvelteMarkType.d.ts +28 -0
- package/dist/decorations/SvelteMarkType.js +19 -0
- package/dist/decorations/SvelteNodeWrapper.d.ts +26 -0
- package/dist/decorations/SvelteNodeWrapper.js +12 -0
- package/dist/decorations/SvelteShapeType.d.ts +30 -0
- package/dist/decorations/SvelteShapeType.js +24 -0
- package/dist/decorations/SvelteWidgetType.d.ts +24 -0
- package/dist/decorations/SvelteWidgetType.js +20 -0
- package/dist/decorations/SvelteWrapperType.d.ts +27 -0
- package/dist/decorations/SvelteWrapperType.js +19 -0
- package/dist/helpers/box.svelte.d.ts +4 -0
- package/dist/helpers/box.svelte.js +11 -0
- package/dist/helpers/dom.d.ts +4 -0
- package/dist/helpers/dom.js +68 -0
- package/dist/helpers/mountRoot.d.ts +28 -0
- package/dist/helpers/mountRoot.js +156 -0
- package/dist/helpers/publish.d.ts +3 -0
- package/dist/helpers/publish.js +12 -0
- package/dist/helpers/slot.d.ts +11 -0
- package/dist/helpers/slot.js +67 -0
- package/dist/hooks/useEditorEffect.svelte.d.ts +10 -0
- package/dist/hooks/useEditorEffect.svelte.js +30 -0
- package/dist/hooks/useEditorEventListener.d.ts +10 -0
- package/dist/hooks/useEditorEventListener.js +24 -0
- package/dist/hooks/useEditorField.svelte.d.ts +20 -0
- package/dist/hooks/useEditorField.svelte.js +51 -0
- package/dist/hooks/useEditorLayoutEffect.d.ts +15 -0
- package/dist/hooks/useEditorLayoutEffect.js +24 -0
- package/dist/hooks/useEditorState.svelte.d.ts +5 -0
- package/dist/hooks/useEditorState.svelte.js +20 -0
- package/dist/hooks/useIgnoreMutation.d.ts +6 -0
- package/dist/hooks/useIgnoreMutation.js +18 -0
- package/dist/hooks/useIsNodeSelected.d.ts +4 -0
- package/dist/hooks/useIsNodeSelected.js +5 -0
- package/dist/hooks/useNodePos.d.ts +5 -0
- package/dist/hooks/useNodePos.js +7 -0
- package/dist/hooks/useSelectNode.svelte.d.ts +6 -0
- package/dist/hooks/useSelectNode.svelte.js +28 -0
- package/dist/hooks/useStopEvent.d.ts +8 -0
- package/dist/hooks/useStopEvent.js +21 -0
- package/dist/hooks/useWordgard.d.ts +2 -0
- package/dist/hooks/useWordgard.js +4 -0
- package/dist/index.d.ts +21 -0
- package/dist/index.js +21 -0
- package/dist/words.d.ts +2 -0
- package/dist/words.js +10 -0
- package/package.json +60 -4
- package/skills/svelte-wordgard/SKILL.md +437 -0
- package/skills/svelte-wordgard/references/wordgard.md +192 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
## 0.4.0 (2026-11-19)
|
|
2
|
+
|
|
3
|
+
### New features
|
|
4
|
+
|
|
5
|
+
First release: svelte-wordgard draws Wordgard's document with its own DOM renderer, and any decoration that takes a shape, a wrapper or a widget, or a mark's shape, can be a Svelte 5 component.
|
|
6
|
+
|
|
7
|
+
`WordgardEditor` and `WordgardDoc` host the editor in a Svelte app, and unmounting `WordgardDoc` unmounts the document's components; the hooks (`useWordgard`, `useEditorState`, `useEditorField`, `useEditorFieldEntry`, `useEditorEffect`, `useEditorLayoutEffect`, `useEditorEventListener`) read and change it from components, those outside the document getting the state once the editor's update is done.
|
|
8
|
+
|
|
9
|
+
On the server (SvelteKit's first render), `WordgardEditor` creates no editor and draws nothing: its children are drawn in the browser, as the page hydrates.
|
|
10
|
+
|
|
11
|
+
`createShape`, `createWrapper`, `createMarkShape`, `createWidgetType` and `nodeWrapper` make Svelte components decorations, mounted with the contexts of the component whose `contentDOMRef` or `wrappedDOMRef` element holds them; `DecorationRoot` draws a root of the decoration's own tag, `WrappedNode` is a node wrapper's root, its attributes going on the node's root element, and `useNodePos`, `useIsNodeSelected`, `useSelectNode`, `useStopEvent` and `useIgnoreMutation` work inside them.
|
package/LICENSE.txt
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Edoardo Caratti
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,404 @@
|
|
|
1
|
-
#
|
|
1
|
+
# svelte-wordgard
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
> **Under construction.** svelte-wordgard isn't ready for production yet, and its API may still
|
|
4
|
+
> change.
|
|
5
|
+
|
|
6
|
+
svelte-wordgard stays on 0.x for as long as Wordgard does: it reaches into Wordgard's internals, and
|
|
7
|
+
relies on Svelte's behaviour where no contract covers it, so it can't be more stable than either.
|
|
8
|
+
|
|
9
|
+
A Svelte view for [Wordgard](https://www.wordgard.net): any decoration that takes a shape, a wrapper
|
|
10
|
+
or a widget can be a Svelte 5 component, mounted with your app's contexts. Wordgard keeps doing the
|
|
11
|
+
rest (input, selection, composition), and the API stays Wordgard's.
|
|
12
|
+
|
|
13
|
+
A Svelte decoration marks its content element with an attachment, reads your app's contexts and
|
|
14
|
+
stores, and can re-render on its own without breaking the editor.
|
|
15
|
+
|
|
16
|
+
It is [react-wordgard](https://github.com/stesura/react-wordgard/tree/master/packages/react) for
|
|
17
|
+
Svelte, over the same core. Its README goes deeper into Wordgard's side (shapes or wrappers, sharing
|
|
18
|
+
the model with a server, changing a node without remounting it); all of that holds here.
|
|
19
|
+
|
|
20
|
+
## Contents
|
|
21
|
+
|
|
22
|
+
- [Install](#install)
|
|
23
|
+
- [Usage](#usage)
|
|
24
|
+
- [Reading and changing the editor](#reading-and-changing-the-editor)
|
|
25
|
+
- [Svelte decorations](#svelte-decorations)
|
|
26
|
+
- [The component's contract](#the-components-contract)
|
|
27
|
+
- [Timing](#timing)
|
|
28
|
+
- [Server rendering](#server-rendering)
|
|
29
|
+
- [Limits](#limits)
|
|
30
|
+
- [API](#api)
|
|
31
|
+
- [Coming from react-wordgard](#coming-from-react-wordgard)
|
|
32
|
+
- [AI coding agents](#ai-coding-agents)
|
|
33
|
+
- [Licence](#licence)
|
|
34
|
+
|
|
35
|
+
## Install
|
|
36
|
+
|
|
37
|
+
```sh
|
|
38
|
+
npm install @stesura/svelte-wordgard wordgard svelte
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
- `wordgard` 0.7.0 exactly: svelte-wordgard uses Wordgard's internals, which any release can change.
|
|
42
|
+
- `svelte` 5.57, from 5.57.3: svelte-wordgard relies on how Svelte places its anchors, flushes and
|
|
43
|
+
mounts, which no contract covers and even a patch release can change.
|
|
44
|
+
- Only one copy of `wordgard` in your app: `npm ls wordgard` should list one version. With two, the
|
|
45
|
+
editor won't work.
|
|
46
|
+
- svelte-wordgard brings its core, `@stesura/wordgard-view`, at the same version: don't install or
|
|
47
|
+
import it yourself.
|
|
48
|
+
- It ships `.svelte` files, compiled by your app's Svelte: a SvelteKit or Vite app with
|
|
49
|
+
`@sveltejs/vite-plugin-svelte` takes them as they are.
|
|
50
|
+
- With TypeScript, `"skipLibCheck": true` in your `tsconfig.json`: Wordgard's own typings don't
|
|
51
|
+
type-check ([#120](https://code.haverbeke.berlin/wordgard/wordgard/issues/120)).
|
|
52
|
+
|
|
53
|
+
## Usage
|
|
54
|
+
|
|
55
|
+
```svelte
|
|
56
|
+
<!-- Editor.svelte -->
|
|
57
|
+
<script lang="ts">
|
|
58
|
+
import { Decoration, Wordgard } from "wordgard/editor";
|
|
59
|
+
import { basicSchema, image } from "wordgard/schema";
|
|
60
|
+
import { Image } from "wordgard/types";
|
|
61
|
+
import { WordgardDoc, WordgardEditor, createShape } from "@stesura/svelte-wordgard";
|
|
62
|
+
|
|
63
|
+
import ImageView from "./ImageView.svelte";
|
|
64
|
+
import WordCount from "./WordCount.svelte";
|
|
65
|
+
|
|
66
|
+
const config = [
|
|
67
|
+
basicSchema(),
|
|
68
|
+
image(),
|
|
69
|
+
Decoration.Tag.shape(Image, createShape(ImageView)),
|
|
70
|
+
Wordgard.label("Document"),
|
|
71
|
+
];
|
|
72
|
+
</script>
|
|
73
|
+
|
|
74
|
+
<WordgardEditor
|
|
75
|
+
doc={'<p>Hello <strong>world</strong> <img src="/cat.png" alt="A cat"></p>'}
|
|
76
|
+
{config}
|
|
77
|
+
>
|
|
78
|
+
<WordCount />
|
|
79
|
+
<WordgardDoc class="editor" />
|
|
80
|
+
</WordgardEditor>
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
```svelte
|
|
84
|
+
<!-- ImageView.svelte: the node type's element, an <img>. Wordgard's attributes (`src`, `alt`, the
|
|
85
|
+
selected node's class) come as props, spread on the root. -->
|
|
86
|
+
<script lang="ts">
|
|
87
|
+
import type { ShapeComponentProps } from "@stesura/svelte-wordgard";
|
|
88
|
+
|
|
89
|
+
let { nodeProps, contentDOMRef, ...rest }: ShapeComponentProps = $props();
|
|
90
|
+
let hover = $state(false);
|
|
91
|
+
</script>
|
|
92
|
+
|
|
93
|
+
<img
|
|
94
|
+
{...rest}
|
|
95
|
+
style:outline={hover ? "2px solid" : undefined}
|
|
96
|
+
onmouseenter={() => (hover = true)}
|
|
97
|
+
onmouseleave={() => (hover = false)}
|
|
98
|
+
/>
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
```svelte
|
|
102
|
+
<!-- WordCount.svelte -->
|
|
103
|
+
<script lang="ts">
|
|
104
|
+
import { useEditorState } from "@stesura/svelte-wordgard";
|
|
105
|
+
|
|
106
|
+
const editorState = useEditorState();
|
|
107
|
+
const words = $derived(editorState.current.doc.textContent().split(/\s+/).filter(Boolean).length);
|
|
108
|
+
</script>
|
|
109
|
+
|
|
110
|
+
<output>{words} words</output>
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
`<WordgardEditor>` creates the editor from its props (`doc`, `config`, `selection`, `state`), **read
|
|
114
|
+
once**: the editor owns its state, and you change it with `wg.dispatch(…)`, its configuration with
|
|
115
|
+
Wordgard's compartments. `<WordgardDoc>` puts it in the page, in a `div` taking its attributes; one
|
|
116
|
+
per editor. `WordgardEditor` draws no element: wrap as much of the page in it as needs the editor.
|
|
117
|
+
|
|
118
|
+
Svelte refuses a variable named `state` beside the `$state` rune: name the editor's state otherwise
|
|
119
|
+
(`editorState`).
|
|
120
|
+
|
|
121
|
+
### Reading and changing the editor
|
|
122
|
+
|
|
123
|
+
Under `WordgardEditor`, inside the document or beside it:
|
|
124
|
+
|
|
125
|
+
- `useWordgard()`: the editor. Commands run through `Command.dispatch(wg, command)`, changes
|
|
126
|
+
through `wg.dispatch({ changes, selection })`; `wg.state` is the latest state, dispatches not yet
|
|
127
|
+
drawn included.
|
|
128
|
+
- `useEditorState()`: the state as of the editor's last update (the one the DOM shows), in
|
|
129
|
+
`current`. Derive from it with `$derived`.
|
|
130
|
+
- `useEditorField(field, select?, isEqual?)`: a state field's value, or a part of it, in `current`;
|
|
131
|
+
nothing runs on an update that leaves the field unchanged. `useEditorFieldEntry(field, key)`: one
|
|
132
|
+
entry of a field holding a `Map`.
|
|
133
|
+
- `useEditorEffect((wg) => cleanup?, source?)`: runs once the editor's DOM is up to date, after it
|
|
134
|
+
mounts and again when what `source` (a function) reads changes. What the effect itself reads isn't
|
|
135
|
+
tracked. It may read layout and dispatch: for focus, menus, follow-up dispatches.
|
|
136
|
+
- `useEditorLayoutEffect({ read, write })`: inside every update, `read` in Wordgard's read phase and
|
|
137
|
+
`write` in its write phase, on the same paint, without rendering; it can't dispatch. For what
|
|
138
|
+
moves with the text (margin markers, pagination).
|
|
139
|
+
- `useEditorEventListener(type, (wg, event) => handled)`: the editor's DOM events, before
|
|
140
|
+
Wordgard's handlers and keymaps; returning `true` handles the event. Keyboard, input, mouse
|
|
141
|
+
(not `mousemove`), focus, clipboard and drag-and-drop events.
|
|
142
|
+
|
|
143
|
+
```svelte
|
|
144
|
+
<!-- BoldButton.svelte -->
|
|
145
|
+
<script lang="ts">
|
|
146
|
+
import { Command, toggleStrong } from "wordgard/command";
|
|
147
|
+
import { useEditorState, useWordgard } from "@stesura/svelte-wordgard";
|
|
148
|
+
|
|
149
|
+
const wg = useWordgard();
|
|
150
|
+
const editorState = useEditorState();
|
|
151
|
+
const empty = $derived(editorState.current.selection.empty);
|
|
152
|
+
</script>
|
|
153
|
+
|
|
154
|
+
<button
|
|
155
|
+
disabled={empty}
|
|
156
|
+
onmousedown={(event) => {
|
|
157
|
+
event.preventDefault();
|
|
158
|
+
Command.dispatch(wg, toggleStrong);
|
|
159
|
+
}}
|
|
160
|
+
>
|
|
161
|
+
Bold
|
|
162
|
+
</button>
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
Menus and popovers: position them with your library (Floating UI) from `wg.coordsAtPos(pos)` in
|
|
166
|
+
`useEditorEffect`, shown or hidden from a `$derived` over the state. To react to changes without
|
|
167
|
+
rendering (autosave), add a `Wordgard.updateListener.of((update) => …)` to `config`. Components
|
|
168
|
+
outside `WordgardEditor` can't use the hooks: lift `WordgardEditor`, or share the editor through a
|
|
169
|
+
store from `useEditorEffect` and use it directly.
|
|
170
|
+
|
|
171
|
+
### Svelte decorations
|
|
172
|
+
|
|
173
|
+
Each factory takes a component, is **called at module level**, and returns a Wordgard value for
|
|
174
|
+
`config`:
|
|
175
|
+
|
|
176
|
+
| Need | Factory | Passed to |
|
|
177
|
+
| --------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------- |
|
|
178
|
+
| A node, with content or an atom (callout, image, mention) | `createShape(component)` | `Decoration.Tag.shape(Type, shape)`; `shape.of(element, { atom? })` for `Point.shape` |
|
|
179
|
+
| An element around a node or part of its shape | `createWrapper(component, { element })` | `Decoration.Tag.wrapper(Type, wrapper, { target? })`, `Decoration.Point.wrapper` |
|
|
180
|
+
| A mark's element (link, comment highlight) | `createMarkShape(component, { element })` | `Decoration.Mark.shape(MarkType, shape)` |
|
|
181
|
+
| A widget at a position or beside a node (badge, mention) | `createWidgetType({ component, … })` | `Decoration.Point.widget(Type.of(value))`, `Decoration.Tag.widget`, `Tag.shape` |
|
|
182
|
+
| Data for a node's shape, with no element | `nodeWrapper(Type, component)` | `config` directly: it is an extension |
|
|
183
|
+
|
|
184
|
+
```svelte
|
|
185
|
+
<!-- Callout.svelte: a shape holding blocks, chrome before its content. DecorationRoot draws the
|
|
186
|
+
node type's element. -->
|
|
187
|
+
<script lang="ts">
|
|
188
|
+
import { DecorationRoot, type ShapeComponentProps } from "@stesura/svelte-wordgard";
|
|
189
|
+
|
|
190
|
+
let { nodeProps, contentDOMRef, ...rest }: ShapeComponentProps = $props();
|
|
191
|
+
</script>
|
|
192
|
+
|
|
193
|
+
<DecorationRoot {...rest}>
|
|
194
|
+
<span aria-hidden="true">!</span>
|
|
195
|
+
<div {@attach contentDOMRef}></div>
|
|
196
|
+
</DecorationRoot>
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
```svelte
|
|
200
|
+
<!-- LinkMark.svelte: a mark, its root the content element. -->
|
|
201
|
+
<script lang="ts">
|
|
202
|
+
import { DecorationRoot, type MarkComponentProps } from "@stesura/svelte-wordgard";
|
|
203
|
+
|
|
204
|
+
let { markProps, contentDOMRef, ...rest }: MarkComponentProps = $props();
|
|
205
|
+
</script>
|
|
206
|
+
|
|
207
|
+
<DecorationRoot {...rest} content={contentDOMRef} href={String(markProps.mark.value)} />
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
```svelte
|
|
211
|
+
<!-- Resizer.svelte: a wrapper, with a handle beside what it wraps. What it wraps goes first in
|
|
212
|
+
the element wrappedDOMRef marks. -->
|
|
213
|
+
<script lang="ts">
|
|
214
|
+
import { type WrapperComponentProps, useStopEvent } from "@stesura/svelte-wordgard";
|
|
215
|
+
|
|
216
|
+
let { nodeProps, wrappedDOMRef, class: className, ...rest }: WrapperComponentProps = $props();
|
|
217
|
+
useStopEvent(() => true);
|
|
218
|
+
</script>
|
|
219
|
+
|
|
220
|
+
<span
|
|
221
|
+
{...rest}
|
|
222
|
+
class={[typeof className == "string" && className, "resizer"]}
|
|
223
|
+
{@attach wrappedDOMRef}
|
|
224
|
+
>
|
|
225
|
+
<span class="resize-handle" aria-hidden="true"></span>
|
|
226
|
+
</span>
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
```svelte
|
|
230
|
+
<!-- Badge.svelte: a widget. -->
|
|
231
|
+
<script lang="ts">
|
|
232
|
+
import type { WidgetComponentProps } from "@stesura/svelte-wordgard";
|
|
233
|
+
|
|
234
|
+
let { value, ...rest }: WidgetComponentProps<string> = $props();
|
|
235
|
+
</script>
|
|
236
|
+
|
|
237
|
+
<span {...rest} class="badge" aria-hidden="true">{value}</span>
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
```ts
|
|
241
|
+
// view.ts
|
|
242
|
+
import { Decoration } from "wordgard/editor";
|
|
243
|
+
import { Blockquote, Image, Link, Paragraph } from "wordgard/types";
|
|
244
|
+
import {
|
|
245
|
+
createMarkShape,
|
|
246
|
+
createShape,
|
|
247
|
+
createWidgetType,
|
|
248
|
+
createWrapper,
|
|
249
|
+
} from "@stesura/svelte-wordgard";
|
|
250
|
+
|
|
251
|
+
import Badge from "./Badge.svelte";
|
|
252
|
+
import Callout from "./Callout.svelte";
|
|
253
|
+
import LinkMark from "./LinkMark.svelte";
|
|
254
|
+
import Resizer from "./Resizer.svelte";
|
|
255
|
+
|
|
256
|
+
const BadgeWidget = createWidgetType<string>({ component: Badge });
|
|
257
|
+
|
|
258
|
+
export const view = [
|
|
259
|
+
Decoration.Tag.shape(Blockquote, createShape(Callout)),
|
|
260
|
+
Decoration.Mark.shape(Link, createMarkShape(LinkMark, { element: "a" })),
|
|
261
|
+
// An image is inline: a span around it.
|
|
262
|
+
Decoration.Tag.wrapper(Image, createWrapper(Resizer, { element: "span" })),
|
|
263
|
+
Decoration.Tag.widget(Paragraph, "start", BadgeWidget.of("¶")),
|
|
264
|
+
];
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
Keep the model (node and mark types, schema elements, fields, commands) in a module without Svelte,
|
|
268
|
+
which a server can import, and the Svelte decorations in a client module adding decorations only.
|
|
269
|
+
|
|
270
|
+
`nodeWrapper(Type, component)` puts a component around every node of a type, drawing no element:
|
|
271
|
+
its root is `<WrappedNode />`, standing for the node's drawing, and the attributes you give it go
|
|
272
|
+
on the node's root element (`class` joined, Svelte's class arrays and objects read, handlers
|
|
273
|
+
dropped). It hands the node's Svelte shape data through `setContext`, and re-renders from its own
|
|
274
|
+
state without drawing the node again. Changing the wrappers in the configuration draws the whole
|
|
275
|
+
document again.
|
|
276
|
+
|
|
277
|
+
Inside a decoration's component: `useNodePos()` (a function giving its position, for handlers and
|
|
278
|
+
effects), `useIsNodeSelected()` (in `current`), `useSelectNode(select, deselect?)`,
|
|
279
|
+
`useStopEvent((wg, event) => stop)` for events in its chrome (its controls), and
|
|
280
|
+
`useIgnoreMutation((wg, record) => ignore)`.
|
|
281
|
+
|
|
282
|
+
### The component's contract
|
|
283
|
+
|
|
284
|
+
Each Svelte decoration is a root of its own (`mount`), placed in the document by svelte-wordgard,
|
|
285
|
+
which draws everything else itself: nothing Svelte puts beside a root (its anchors, a block's
|
|
286
|
+
comment) may land among the document's nodes.
|
|
287
|
+
|
|
288
|
+
- **One root, the element the decoration says, and its props spread on it.** For a shape, the node
|
|
289
|
+
type's own outer element, per node (`h1` to `h6` for a heading); for `createWrapper`,
|
|
290
|
+
`createMarkShape` and `.of(element)`, their `element` (`div` for wrappers, `span` for marks); for
|
|
291
|
+
a widget, any element. Wordgard applies decorations to that element before Svelte draws, so the
|
|
292
|
+
component can't choose it. Spread the props it doesn't use on the root (`{...rest}`): they are
|
|
293
|
+
Wordgard's attributes (the node type's, the selection's `wg-selected-node`, tag and mark
|
|
294
|
+
attributes). Nothing falls through by itself: a `class` of your own joins theirs
|
|
295
|
+
(`class={[typeof className == "string" && className, "mine"]}`), or replaces it.
|
|
296
|
+
- **`<DecorationRoot {...rest}>`** draws that root, its tag the decoration's (a heading's level,
|
|
297
|
+
per node), and follows when it changes.
|
|
298
|
+
- **At the top, one element, or one block (`{#if}`, `{#key}`) around one
|
|
299
|
+
element, with nothing beside it in that block.** A root sharing a block with a sibling
|
|
300
|
+
(`<p></p>{#if open}…{/if}`, or inside one `{#key}`) breaks the editor when the block draws it
|
|
301
|
+
again: Svelte then removes the document's nodes after the root. A component may replace its root
|
|
302
|
+
from its own state (an `{#if}` switching between two elements).
|
|
303
|
+
- **The content goes in an empty element marked `{@attach contentDOMRef}`**, which holds only the
|
|
304
|
+
content; without one, the root holds it, and what's drawn there gets the decoration's contexts,
|
|
305
|
+
not the component's. `<DecorationRoot content={contentDOMRef}>` makes the
|
|
306
|
+
root the content element. Never `{@render children()}` or text there: Svelte's anchors would
|
|
307
|
+
land among the content's nodes.
|
|
308
|
+
- **What a wrapper wraps goes first in the element marked `{@attach wrappedDOMRef}`.**
|
|
309
|
+
- Everything else the component draws is **chrome**: made uneditable, never read as content, free
|
|
310
|
+
to change. In a textblock or a mark, the content element holds only the content; chrome beside a
|
|
311
|
+
paragraph's text is a widget at its `"start"` or `"end"`. In a node holding blocks, chrome sits
|
|
312
|
+
around the content element, in elements of its own.
|
|
313
|
+
- Chrome inherits the editor's `white-space: pre-wrap`, which draws the space Svelte keeps between
|
|
314
|
+
elements on separate lines: a blank line between a title bar and the content element. Give the
|
|
315
|
+
root `white-space: normal` and the content element `white-space: pre-wrap`.
|
|
316
|
+
- A component may move its content element (`contentDOMRef` on another element, from its own
|
|
317
|
+
state): the content's DOM moves into it.
|
|
318
|
+
- Node parameters: `nodeProps.node.tag.param` for a node with content, `node.param` for a leaf;
|
|
319
|
+
data an action changes in place is a mark on the tag (`node.tag.mark(Type)`), changed with
|
|
320
|
+
`wg.dispatch({ changes: { from: pos, add: Type.of(value) } })`, which keeps the component mounted.
|
|
321
|
+
|
|
322
|
+
### Timing
|
|
323
|
+
|
|
324
|
+
Wordgard updates the DOM in its flush, on the next frame, and svelte-wordgard draws the document
|
|
325
|
+
inside it, committing Svelte's pending work there (`flushSync`).
|
|
326
|
+
|
|
327
|
+
- **Don't read the editor's layout (`coordsAtPos`) or force its update from a component's script,
|
|
328
|
+
template, `$derived`, `$effect` or attachment**: the update is refused there and drawn on the
|
|
329
|
+
next frame. Use `useEditorEffect`, `useEditorLayoutEffect` or an event handler.
|
|
330
|
+
- `useNodePos()`'s function throws before the decoration's tiles exist: call it from handlers and
|
|
331
|
+
`useEditorEffect`.
|
|
332
|
+
- Components outside the document get a new state once the editor's update is done, their effects
|
|
333
|
+
outside Wordgard's flush, where they may dispatch.
|
|
334
|
+
- An error a component in the document throws, in its setup or in a later update of its own, is
|
|
335
|
+
logged; the next update draws the document again.
|
|
336
|
+
- Svelte's async mode (`experimental.async`) is supported (tested in Svelte's development build).
|
|
337
|
+
A component suspending (`await`) in the document isn't.
|
|
338
|
+
|
|
339
|
+
### Server rendering
|
|
340
|
+
|
|
341
|
+
For a SvelteKit page that is only the editor, turn server rendering off for its route
|
|
342
|
+
(`export const ssr = false` in `+page.ts`): nothing then runs on the server.
|
|
343
|
+
|
|
344
|
+
A page that keeps server rendering (an editor under an article, a comment box) needs nothing either:
|
|
345
|
+
on the server, `WordgardEditor` creates no editor and draws nothing, since Wordgard needs the DOM,
|
|
346
|
+
to read its document's HTML too. Its children are drawn in the browser, as the page hydrates. Its
|
|
347
|
+
props are still built on the server: give the document as `doc` (HTML), or load it with
|
|
348
|
+
`schema.docFromJSON`; a `GardState.create({ doc: html })` in the page's script throws there. To keep
|
|
349
|
+
the editor's place meanwhile, draw a placeholder beside it with `{#if !browser}` (from
|
|
350
|
+
`$app/environment`).
|
|
351
|
+
|
|
352
|
+
### Limits
|
|
353
|
+
|
|
354
|
+
- A Svelte wrapper can't wrap text, or a node a native widget draws (draw it with a Svelte widget).
|
|
355
|
+
- A root leaving with an outro transition is still in the document when its replacement comes:
|
|
356
|
+
the editor reports the component as drawing two roots.
|
|
357
|
+
- Each Svelte decoration is a root of its own: mounting thousands at once (bolding a long document
|
|
358
|
+
with a Svelte mark shape) costs about 30 µs each.
|
|
359
|
+
|
|
360
|
+
## API
|
|
361
|
+
|
|
362
|
+
Everything is exported from `@stesura/svelte-wordgard`.
|
|
363
|
+
|
|
364
|
+
- Components: `WordgardEditor`, `WordgardDoc`, `DecorationRoot`, `WrappedNode`.
|
|
365
|
+
- Factories: `createShape`, `createWrapper`, `createMarkShape`, `createWidgetType`, `nodeWrapper`.
|
|
366
|
+
- Editor hooks, under `WordgardEditor`: `useWordgard`, `useEditorState`, `useEditorField`,
|
|
367
|
+
`useEditorFieldEntry`, `useEditorEffect`, `useEditorLayoutEffect`, `useEditorEventListener`.
|
|
368
|
+
- Decoration hooks, in a decoration's component: `useNodePos`, `useIsNodeSelected`,
|
|
369
|
+
`useSelectNode`, `useStopEvent`, `useIgnoreMutation`.
|
|
370
|
+
- Props types: `ShapeComponentProps`, `WrapperComponentProps`, `MarkComponentProps`,
|
|
371
|
+
`WidgetComponentProps`, `NodeWrapperComponentProps`.
|
|
372
|
+
- `SvelteWordgard.create(spec)`: an editor drawn by svelte-wordgard outside a component tree
|
|
373
|
+
(tests, benchmarks). In a Svelte app, use `WordgardEditor`.
|
|
374
|
+
|
|
375
|
+
The hooks' and components' signatures and details are in their typings (`dist/index.d.ts`).
|
|
376
|
+
|
|
377
|
+
## Coming from react-wordgard
|
|
378
|
+
|
|
379
|
+
| react-wordgard | svelte-wordgard |
|
|
380
|
+
| -------------------------------------------------------------------- | --------------------------------------------------------------------- |
|
|
381
|
+
| `{children}` in `contentDOMRef`'s element | an empty element with `{@attach contentDOMRef}` |
|
|
382
|
+
| A wrapper's `{children}` | an element with `{@attach wrappedDOMRef}`, what's wrapped first in it |
|
|
383
|
+
| `{...props}` and `ref` on a root drawn by hand | `{...rest}` on the root: no ref, the root is found |
|
|
384
|
+
| `useEditorStateSelector(selector)` | `$derived(selector(useEditorState().current))` |
|
|
385
|
+
| `useEditorEventCallback(callback)` | a plain function using `useWordgard()` |
|
|
386
|
+
| `useEditorEffect(effect, deps)` | `useEditorEffect(effect, source)`, `source` a function |
|
|
387
|
+
| `NodeRootProps` in a node wrapper | attributes on its `<WrappedNode />` |
|
|
388
|
+
| `useIsNodeSelected()` returning a boolean | `useIsNodeSelected()` returning an object with `current` |
|
|
389
|
+
| `WordgardScope`, `useMergedDOMRefs`, `staticCopy`, `isTrailingBreak` | none |
|
|
390
|
+
|
|
391
|
+
## AI coding agents
|
|
392
|
+
|
|
393
|
+
The package ships a skill for building editors with svelte-wordgard: `skills/svelte-wordgard/` (in
|
|
394
|
+
`node_modules/@stesura/svelte-wordgard/`). Copy that folder into your project's `.claude/skills/`,
|
|
395
|
+
or point your agent to its `SKILL.md`.
|
|
396
|
+
|
|
397
|
+
## Licence
|
|
398
|
+
|
|
399
|
+
MIT, © 2026 Edoardo Caratti, see [LICENSE.txt](LICENSE.txt).
|
|
400
|
+
|
|
401
|
+
Includes code from react-prosemirror (© Handle with Care Collective and The New York Times
|
|
402
|
+
Company), through react-wordgard; its notices are in
|
|
403
|
+
[THIRD_PARTY_LICENSES.txt](THIRD_PARTY_LICENSES.txt). Its core, `@stesura/wordgard-view`, also
|
|
404
|
+
includes code from Wordgard (© Marijn Haverbeke).
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
svelte-wordgard includes code from the projects below. Their copyright and
|
|
2
|
+
license notices are reproduced here, as their licenses require.
|
|
3
|
+
|
|
4
|
+
|
|
5
|
+
================================================================================
|
|
6
|
+
react-prosemirror
|
|
7
|
+
https://github.com/handlewithcarecollective/react-prosemirror
|
|
8
|
+
================================================================================
|
|
9
|
+
|
|
10
|
+
svelte-wordgard is adapted from react-wordgard, which is derived from
|
|
11
|
+
react-prosemirror, maintained by Handle with Care Collective and originally
|
|
12
|
+
created at The New York Times Company.
|
|
13
|
+
|
|
14
|
+
react-prosemirror was released under the Apache License 2.0 until 2026-10-02
|
|
15
|
+
(commit 1827d3a) and under the MIT License since then. Both notices follow.
|
|
16
|
+
|
|
17
|
+
--- MIT License (since 2026-10-02) ---------------------------------------------
|
|
18
|
+
|
|
19
|
+
MIT License
|
|
20
|
+
|
|
21
|
+
Copyright (c) 2026 Handle with Care Collective
|
|
22
|
+
|
|
23
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
24
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
25
|
+
in the Software without restriction, including without limitation the rights
|
|
26
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
27
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
28
|
+
furnished to do so, subject to the following conditions:
|
|
29
|
+
|
|
30
|
+
The above copyright notice and this permission notice shall be included in all
|
|
31
|
+
copies or substantial portions of the Software.
|
|
32
|
+
|
|
33
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
34
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
35
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
36
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
37
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
38
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
39
|
+
SOFTWARE.
|
|
40
|
+
|
|
41
|
+
--- Apache License 2.0 (until 2026-10-02) --------------------------------------
|
|
42
|
+
|
|
43
|
+
Copyright (c) 2022 The New York Times Company
|
|
44
|
+
Copyright (c) 2025 Handle with Care Collective
|
|
45
|
+
|
|
46
|
+
Licensed under the Apache License, Version 2.0 (the "License"); you may not use
|
|
47
|
+
this library except in compliance with the License. You may obtain a copy of the
|
|
48
|
+
License at
|
|
49
|
+
|
|
50
|
+
www.apache.org/licenses/LICENSE-2.0
|
|
51
|
+
|
|
52
|
+
Unless required by applicable law or agreed to in writing, software distributed
|
|
53
|
+
under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
|
|
54
|
+
CONDITIONS OF ANY KIND, either express or implied. See the License for the
|
|
55
|
+
specific language governing permissions and limitations under the License.
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
import type { Wordgard } from "wordgard/editor";
|
|
2
|
+
import type { GardState } from "wordgard/state";
|
|
3
|
+
import { RenderedDocTile } from "@stesura/wordgard-view";
|
|
4
|
+
import { type DrawContext } from "./components/ChildNodeViews.js";
|
|
5
|
+
type HostedDoc = {
|
|
6
|
+
readonly claim: () => () => void;
|
|
7
|
+
readonly attach: (contexts: Map<unknown, unknown>, place: () => void) => () => void;
|
|
8
|
+
};
|
|
9
|
+
export declare const svelteDoc: (dom: Element) => HostedDoc;
|
|
10
|
+
export declare const drawings: WeakMap<Element, () => DrawContext>;
|
|
11
|
+
export declare class SvelteDocTile extends RenderedDocTile {
|
|
12
|
+
static create: (state: GardState, dom: Element, wg: Wordgard) => RenderedDocTile;
|
|
13
|
+
static host: (state: GardState, dom: Element, wg: Wordgard, mount: () => void) => RenderedDocTile;
|
|
14
|
+
}
|
|
15
|
+
export {};
|