@stesura/vue-wordgard 0.0.0-stage → 0.4.1
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 +21 -0
- package/LICENSE.txt +21 -0
- package/README.md +426 -2
- package/THIRD_PARTY_LICENSES.txt +55 -0
- package/dist/index.d.ts +265 -0
- package/dist/index.js +1285 -0
- package/package.json +57 -4
- package/skills/vue-wordgard/SKILL.md +409 -0
- package/skills/vue-wordgard/references/wordgard.md +192 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
## 0.4.1 (2026-11-19)
|
|
2
|
+
|
|
3
|
+
### Bug fixes
|
|
4
|
+
|
|
5
|
+
The published package no longer declares a source export condition pointing at files it doesn't ship.
|
|
6
|
+
|
|
7
|
+
## 0.4.0 (2026-11-19)
|
|
8
|
+
|
|
9
|
+
### New features
|
|
10
|
+
|
|
11
|
+
First release: vue-wordgard draws Wordgard's document with Vue 3.5, in the app's tree, and any decoration that takes a shape, a wrapper or a widget, or a mark's shape, can be a Vue component.
|
|
12
|
+
|
|
13
|
+
`WordgardEditor` and `WordgardDoc` host the editor in a Vue app; the composables (`useWordgard`, `useEditorState`, `useEditorField`, `useEditorFieldEntry`, `useEditorEffect`, `useEditorLayoutEffect`, `useEditorEventListener`) read and change it from components.
|
|
14
|
+
|
|
15
|
+
`createShape`, `createWrapper`, `createMarkShape`, `createWidgetType` and `nodeWrapper` make Vue components decorations; `DecorationRoot`, `NodeContent` and `WrappedNode` draw their root, their content and what they wrap, and `useNodePos`, `useIsNodeSelected`, `useSelectNode`, `useStopEvent` and `useIgnoreMutation` work inside them.
|
|
16
|
+
|
|
17
|
+
`WordgardScope` gives the components in its slot an editor made elsewhere, and the composables under it follow when it changes; `useWordgardRef` is the editor as a ref that follows it.
|
|
18
|
+
|
|
19
|
+
`WordgardEditor` works in a page rendered on the server: there, and while the page hydrates, it creates no editor and draws nothing, and its slot appears once the page has mounted.
|
|
20
|
+
|
|
21
|
+
`useMergedDOMRefs`, `staticCopy` and `isTrailingBreak` work as in react-wordgard.
|
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,427 @@
|
|
|
1
|
-
#
|
|
1
|
+
# vue-wordgard
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
> **Under construction.** vue-wordgard isn't ready for production yet, and its API may still
|
|
4
|
+
> change.
|
|
5
|
+
|
|
6
|
+
vue-wordgard stays on 0.x for as long as Wordgard does: it reaches into Wordgard's internals, and
|
|
7
|
+
into some of Vue's, so it can't be more stable than either.
|
|
8
|
+
|
|
9
|
+
A Vue view for [Wordgard](https://www.wordgard.net): Vue draws the Wordgard document in your app's
|
|
10
|
+
tree, and any decoration that takes a shape, a wrapper or a widget can be a Vue component. Wordgard
|
|
11
|
+
keeps doing the rest (input, selection, composition), and the API stays Wordgard's.
|
|
12
|
+
|
|
13
|
+
A Vue decoration draws its content with `<NodeContent>`, reads what your app provides and its
|
|
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
|
+
Vue, 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
|
+
- [Vue decorations](#vue-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/vue-wordgard wordgard vue
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
- `wordgard` 0.7.0 exactly: vue-wordgard uses Wordgard's internals, which any release can change.
|
|
42
|
+
- `vue` 3.5, from 3.5.45: vue-wordgard uses some of Vue's internals (`instance.update()`, a
|
|
43
|
+
container's `_vnode`, `vnode.memo`), which a minor 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
|
+
- vue-wordgard brings its core, `@stesura/wordgard-view`, at the same version: don't install or
|
|
47
|
+
import it yourself.
|
|
48
|
+
- With TypeScript, `"skipLibCheck": true` in your `tsconfig.json`: Wordgard's own typings don't
|
|
49
|
+
type-check ([#120](https://code.haverbeke.berlin/wordgard/wordgard/issues/120)).
|
|
50
|
+
- Keep Vue's Options API on (the default; `__VUE_OPTIONS_API__`): vue-wordgard has your components
|
|
51
|
+
in the document commit inside Wordgard's update through a mixin. Without it they commit after,
|
|
52
|
+
which works but costs an update.
|
|
53
|
+
|
|
54
|
+
## Usage
|
|
55
|
+
|
|
56
|
+
```vue
|
|
57
|
+
<!-- Editor.vue -->
|
|
58
|
+
<script setup lang="ts">
|
|
59
|
+
import { Decoration, Wordgard } from "wordgard/editor";
|
|
60
|
+
import { basicSchema, image } from "wordgard/schema";
|
|
61
|
+
import { Image } from "wordgard/types";
|
|
62
|
+
import { WordgardDoc, WordgardEditor, createShape } from "@stesura/vue-wordgard";
|
|
63
|
+
|
|
64
|
+
import ImageView from "./ImageView.vue";
|
|
65
|
+
import WordCount from "./WordCount.vue";
|
|
66
|
+
|
|
67
|
+
const config = [
|
|
68
|
+
basicSchema(),
|
|
69
|
+
image(),
|
|
70
|
+
Decoration.Tag.shape(Image, createShape(ImageView)),
|
|
71
|
+
Wordgard.label("Document"),
|
|
72
|
+
];
|
|
73
|
+
</script>
|
|
74
|
+
|
|
75
|
+
<template>
|
|
76
|
+
<WordgardEditor
|
|
77
|
+
doc='<p>Hello <strong>world</strong> <img src="/cat.png" alt="A cat"></p>'
|
|
78
|
+
:config="config"
|
|
79
|
+
>
|
|
80
|
+
<WordCount />
|
|
81
|
+
<WordgardDoc class="editor" />
|
|
82
|
+
</WordgardEditor>
|
|
83
|
+
</template>
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
```vue
|
|
87
|
+
<!-- ImageView.vue: the node type's element, an <img>. Its attributes (`src`, `alt`, the selected
|
|
88
|
+
node's class) fall through to the root. -->
|
|
89
|
+
<script setup lang="ts">
|
|
90
|
+
import { ref } from "vue";
|
|
91
|
+
import { DecorationRoot, type ShapeComponentProps } from "@stesura/vue-wordgard";
|
|
92
|
+
|
|
93
|
+
defineProps<ShapeComponentProps>();
|
|
94
|
+
const hover = ref(false);
|
|
95
|
+
</script>
|
|
96
|
+
|
|
97
|
+
<template>
|
|
98
|
+
<DecorationRoot
|
|
99
|
+
:style="hover ? { outline: '2px solid' } : undefined"
|
|
100
|
+
@mouseenter="hover = true"
|
|
101
|
+
@mouseleave="hover = false"
|
|
102
|
+
/>
|
|
103
|
+
</template>
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
```vue
|
|
107
|
+
<!-- WordCount.vue -->
|
|
108
|
+
<script setup lang="ts">
|
|
109
|
+
import { computed } from "vue";
|
|
110
|
+
import { useEditorState } from "@stesura/vue-wordgard";
|
|
111
|
+
|
|
112
|
+
const state = useEditorState();
|
|
113
|
+
const words = computed(() => state.value.doc.textContent().split(/\s+/).filter(Boolean).length);
|
|
114
|
+
</script>
|
|
115
|
+
|
|
116
|
+
<template>
|
|
117
|
+
<output>{{ words }} words</output>
|
|
118
|
+
</template>
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
`<WordgardEditor>` creates the editor from its props (`doc`, `config`, `selection`, `state`), **read
|
|
122
|
+
once**: the editor owns its state, and you change it with `wg.dispatch(…)`, its configuration with
|
|
123
|
+
Wordgard's compartments. `<WordgardDoc>` puts it in the page, in a `div` taking its attributes; one
|
|
124
|
+
per editor. `WordgardEditor` draws no element: wrap as much of the page in it as needs the editor.
|
|
125
|
+
|
|
126
|
+
### Reading and changing the editor
|
|
127
|
+
|
|
128
|
+
Under `WordgardEditor`, inside the document or beside it:
|
|
129
|
+
|
|
130
|
+
- `useWordgard()`: the editor. Commands run through `Command.dispatch(wg, command)`, changes
|
|
131
|
+
through `wg.dispatch({ changes, selection })`; `wg.state` is the latest state, dispatches not yet
|
|
132
|
+
drawn included.
|
|
133
|
+
- `useEditorState()`: a `shallowRef` of the state as of the editor's last update (the one the DOM
|
|
134
|
+
shows). Derive from it with `computed`.
|
|
135
|
+
- `useEditorField(field, select?, isEqual?)`: a `computed` of a state field's value, or a part of
|
|
136
|
+
it; nothing runs on an update that leaves the field unchanged. `useEditorFieldEntry(field, key)`:
|
|
137
|
+
one entry of a field holding a `Map`.
|
|
138
|
+
- `useEditorEffect((wg) => cleanup?, source?)`: runs once the editor's DOM is up to date, after it
|
|
139
|
+
mounts and again when `source` (what `watch` takes) changes. It may read layout and dispatch: for
|
|
140
|
+
focus, menus, follow-up dispatches.
|
|
141
|
+
- `useEditorLayoutEffect({ read, write })`: inside every update, `read` in Wordgard's read phase and
|
|
142
|
+
`write` in its write phase, on the same paint, without rendering; it can't dispatch. For what
|
|
143
|
+
moves with the text (margin markers, pagination).
|
|
144
|
+
- `useEditorEventListener(type, (wg, event) => handled)`: the editor's DOM events, before
|
|
145
|
+
Wordgard's handlers and keymaps; returning `true` handles the event. Keyboard, input, mouse
|
|
146
|
+
(not `mousemove`), focus, clipboard and drag-and-drop events.
|
|
147
|
+
|
|
148
|
+
```vue
|
|
149
|
+
<!-- BoldButton.vue -->
|
|
150
|
+
<script setup lang="ts">
|
|
151
|
+
import { computed } from "vue";
|
|
152
|
+
import { Command, toggleStrong } from "wordgard/command";
|
|
153
|
+
import { useEditorState, useWordgard } from "@stesura/vue-wordgard";
|
|
154
|
+
|
|
155
|
+
const wg = useWordgard();
|
|
156
|
+
const state = useEditorState();
|
|
157
|
+
const empty = computed(() => state.value.selection.empty);
|
|
158
|
+
const bold = () => Command.dispatch(wg, toggleStrong);
|
|
159
|
+
</script>
|
|
160
|
+
|
|
161
|
+
<template>
|
|
162
|
+
<button :disabled="empty" @mousedown.prevent="bold">Bold</button>
|
|
163
|
+
</template>
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
Menus and popovers: position them with your library (Floating UI) from `wg.coordsAtPos(pos)` in
|
|
167
|
+
`useEditorEffect`, shown or hidden from a `computed` over the state. To react to changes without
|
|
168
|
+
rendering (autosave), add a `Wordgard.updateListener.of((update) => …)` to `config`. Components
|
|
169
|
+
outside `WordgardEditor` can't use the composables: lift `WordgardEditor`, or share the editor
|
|
170
|
+
through a store from `useEditorEffect` and use it directly, or under a `WordgardScope`.
|
|
171
|
+
|
|
172
|
+
`<WordgardScope :wg="wg">` gives the components in its slot an editor a `WordgardEditor` made
|
|
173
|
+
elsewhere, in place of the one around them: a toolbar acting on whichever of a page's editors has
|
|
174
|
+
focus. The composables under it follow when `wg` changes: states and fields switch to the new
|
|
175
|
+
editor's in the same render, effects run again, listeners and layout effects move. Setup runs
|
|
176
|
+
once, so `useWordgard()` gives the editor as it was then; `useWordgardRef()` gives a ref that
|
|
177
|
+
follows (in development, a scope changing under a `useWordgard()` warns).
|
|
178
|
+
|
|
179
|
+
```vue
|
|
180
|
+
<!-- Toolbar.vue: `focused` is set from useEditorEventListener("focus", …) under each editor. -->
|
|
181
|
+
<script setup lang="ts">
|
|
182
|
+
import { WordgardScope } from "@stesura/vue-wordgard";
|
|
183
|
+
import { focused } from "./focus.js";
|
|
184
|
+
import BoldButton from "./BoldButton.vue";
|
|
185
|
+
</script>
|
|
186
|
+
|
|
187
|
+
<template>
|
|
188
|
+
<WordgardScope v-if="focused" :wg="focused">
|
|
189
|
+
<BoldButton />
|
|
190
|
+
</WordgardScope>
|
|
191
|
+
</template>
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
A `BoldButton` under a scope that changes reads the editor through `useWordgardRef()`
|
|
195
|
+
(`Command.dispatch(wg.value, toggleStrong)`).
|
|
196
|
+
|
|
197
|
+
### Vue decorations
|
|
198
|
+
|
|
199
|
+
Each factory takes a component, is **called at module level**, and returns a Wordgard value for
|
|
200
|
+
`config`:
|
|
201
|
+
|
|
202
|
+
| Need | Factory | Passed to |
|
|
203
|
+
| --------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------- |
|
|
204
|
+
| A node, with content or an atom (callout, image, mention) | `createShape(component)` | `Decoration.Tag.shape(Type, shape)`; `shape.of(element, { atom? })` for `Point.shape` |
|
|
205
|
+
| An element around a node or part of its shape | `createWrapper(component, { element })` | `Decoration.Tag.wrapper(Type, wrapper, { target? })`, `Decoration.Point.wrapper` |
|
|
206
|
+
| A mark's element (link, comment highlight) | `createMarkShape(component, { element })` | `Decoration.Mark.shape(MarkType, shape)` |
|
|
207
|
+
| A widget at a position or beside a node (badge, mention) | `createWidgetType({ component, … })` | `Decoration.Point.widget(Type.of(value))`, `Decoration.Tag.widget`, `Tag.shape` |
|
|
208
|
+
| Data for a node's shape, with no element | `nodeWrapper(Type, component)` | `config` directly: it is an extension |
|
|
209
|
+
|
|
210
|
+
```vue
|
|
211
|
+
<!-- Callout.vue: a shape holding blocks, chrome before its content. -->
|
|
212
|
+
<script setup lang="ts">
|
|
213
|
+
import { DecorationRoot, NodeContent, type ShapeComponentProps } from "@stesura/vue-wordgard";
|
|
214
|
+
|
|
215
|
+
defineProps<ShapeComponentProps>();
|
|
216
|
+
</script>
|
|
217
|
+
|
|
218
|
+
<template>
|
|
219
|
+
<DecorationRoot>
|
|
220
|
+
<span aria-hidden="true">!</span>
|
|
221
|
+
<NodeContent as="div" />
|
|
222
|
+
</DecorationRoot>
|
|
223
|
+
</template>
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
```vue
|
|
227
|
+
<!-- LinkMark.vue: a mark, its root the content element. -->
|
|
228
|
+
<script setup lang="ts">
|
|
229
|
+
import { DecorationRoot, type MarkComponentProps } from "@stesura/vue-wordgard";
|
|
230
|
+
|
|
231
|
+
defineProps<MarkComponentProps>();
|
|
232
|
+
</script>
|
|
233
|
+
|
|
234
|
+
<template>
|
|
235
|
+
<DecorationRoot content :href="String(markProps.mark.value)" />
|
|
236
|
+
</template>
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
```vue
|
|
240
|
+
<!-- Resizer.vue: a wrapper, with a handle beside what it wraps. -->
|
|
241
|
+
<script setup lang="ts">
|
|
242
|
+
import {
|
|
243
|
+
DecorationRoot,
|
|
244
|
+
WrappedNode,
|
|
245
|
+
type WrapperComponentProps,
|
|
246
|
+
useStopEvent,
|
|
247
|
+
} from "@stesura/vue-wordgard";
|
|
248
|
+
|
|
249
|
+
defineProps<WrapperComponentProps>();
|
|
250
|
+
useStopEvent(() => true);
|
|
251
|
+
</script>
|
|
252
|
+
|
|
253
|
+
<template>
|
|
254
|
+
<DecorationRoot class="resizer">
|
|
255
|
+
<WrappedNode />
|
|
256
|
+
<span class="resize-handle" aria-hidden="true" />
|
|
257
|
+
</DecorationRoot>
|
|
258
|
+
</template>
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
```vue
|
|
262
|
+
<!-- Badge.vue: a widget. -->
|
|
263
|
+
<script setup lang="ts">
|
|
264
|
+
import { DecorationRoot } from "@stesura/vue-wordgard";
|
|
265
|
+
|
|
266
|
+
defineProps<{ value: string }>();
|
|
267
|
+
</script>
|
|
268
|
+
|
|
269
|
+
<template>
|
|
270
|
+
<DecorationRoot class="badge" aria-hidden="true">{{ value }}</DecorationRoot>
|
|
271
|
+
</template>
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
```ts
|
|
275
|
+
// view.ts
|
|
276
|
+
import { Decoration } from "wordgard/editor";
|
|
277
|
+
import { Blockquote, Image, Link, Paragraph } from "wordgard/types";
|
|
278
|
+
import {
|
|
279
|
+
createMarkShape,
|
|
280
|
+
createShape,
|
|
281
|
+
createWidgetType,
|
|
282
|
+
createWrapper,
|
|
283
|
+
} from "@stesura/vue-wordgard";
|
|
284
|
+
|
|
285
|
+
import Badge from "./Badge.vue";
|
|
286
|
+
import Callout from "./Callout.vue";
|
|
287
|
+
import LinkMark from "./LinkMark.vue";
|
|
288
|
+
import Resizer from "./Resizer.vue";
|
|
289
|
+
|
|
290
|
+
const BadgeWidget = createWidgetType<string>({ component: Badge });
|
|
291
|
+
|
|
292
|
+
export const view = [
|
|
293
|
+
Decoration.Tag.shape(Blockquote, createShape(Callout)),
|
|
294
|
+
Decoration.Mark.shape(Link, createMarkShape(LinkMark, { element: "a" })),
|
|
295
|
+
// An image is inline: a span around it.
|
|
296
|
+
Decoration.Tag.wrapper(Image, createWrapper(Resizer, { element: "span" })),
|
|
297
|
+
Decoration.Tag.widget(Paragraph, "start", BadgeWidget.of("¶")),
|
|
298
|
+
];
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
Keep the model (node and mark types, schema elements, fields, commands) in a module without Vue,
|
|
302
|
+
which a server can import, and the Vue decorations in a client module adding decorations only.
|
|
303
|
+
|
|
304
|
+
`nodeWrapper(Type, component)` puts a component around every node of a type, rendering no element:
|
|
305
|
+
its root is `<WrappedNode />`, the node's drawing, and the attributes you give it fall through to
|
|
306
|
+
the node's root element. It hands the node's Vue shape data through `provide`, and re-renders from
|
|
307
|
+
its own state without drawing the node again. Changing the wrappers in the configuration draws the
|
|
308
|
+
whole document again.
|
|
309
|
+
|
|
310
|
+
Inside a decoration's component: `useNodePos()` (a function giving its position, for handlers and
|
|
311
|
+
effects), `useIsNodeSelected()` (a `ref`), `useSelectNode(select, deselect?)`,
|
|
312
|
+
`useStopEvent((wg, event) => stop)` for events in its chrome (its controls), and
|
|
313
|
+
`useIgnoreMutation((wg, record) => ignore)`.
|
|
314
|
+
|
|
315
|
+
### The component's contract
|
|
316
|
+
|
|
317
|
+
- **One root, the element the decoration says, kept.** For a shape, the node type's own outer
|
|
318
|
+
element, per node (`h1` to `h6` for a heading); for `createWrapper`, `createMarkShape` and
|
|
319
|
+
`.of(element)`, their `element` (`div` for wrappers, `span` for marks); for a widget, the type's
|
|
320
|
+
`element` (`span`), or any element. Wordgard applies decorations to that element before Vue
|
|
321
|
+
draws, so the component can't choose it. No `v-if`, `v-for` or `:key` on the root: replacing it
|
|
322
|
+
breaks the editor.
|
|
323
|
+
- **`<DecorationRoot>`** draws that root. Or draw the element yourself: Wordgard's attributes
|
|
324
|
+
(the node type's, the selection's `wg-selected-node`, tag and mark attributes) fall through to
|
|
325
|
+
any single root, classes joined and styles merged with yours, Wordgard's winning for the rest.
|
|
326
|
+
`inheritAttrs: false` drops them.
|
|
327
|
+
- **The content is `<NodeContent as="div" />`**, never a `<slot />`: a slot would put empty text
|
|
328
|
+
nodes beside the text, where Wordgard reads positions. `<DecorationRoot content />` makes the root
|
|
329
|
+
the content element; use it rather than switching between the two, which remounts the root.
|
|
330
|
+
Without either, the node draws as an atom (a leaf, or `.of(element, { atom: true })`).
|
|
331
|
+
- **What a wrapper wraps is `<WrappedNode />`**, once, its attributes falling through to the
|
|
332
|
+
wrapped element.
|
|
333
|
+
- Everything else the component draws is **chrome**: made uneditable, never read as content, free
|
|
334
|
+
to change. In a textblock or a mark, the content element holds only the content; chrome beside a
|
|
335
|
+
paragraph's text is a widget at its `"start"` or `"end"`. In a node holding blocks, chrome may sit
|
|
336
|
+
before or after the content, in `NodeContent`'s `before` and `after` slots.
|
|
337
|
+
- `v-if` and fragments leave comments and empty text nodes: `DecorationRoot`'s slot and
|
|
338
|
+
`NodeContent`'s slots drop them; a content element or a mark's elements holding one throws.
|
|
339
|
+
- Moving `<NodeContent>` or `<WrappedNode>` under another element remounts the content (a
|
|
340
|
+
selection or IME composition in it ends).
|
|
341
|
+
- Node parameters: `nodeProps.node.tag.param` for a node with content, `node.param` for a leaf;
|
|
342
|
+
data an action changes in place is a mark on the tag (`node.tag.mark(Type)`), changed with
|
|
343
|
+
`wg.dispatch({ changes: { from: pos, add: Type.of(value) } })`, which keeps the component mounted.
|
|
344
|
+
|
|
345
|
+
### Timing
|
|
346
|
+
|
|
347
|
+
Wordgard updates the DOM in its flush, on the next frame, and Vue draws the document inside it.
|
|
348
|
+
|
|
349
|
+
- **Don't read the editor's layout (`coordsAtPos`) or force its update from a component's setup,
|
|
350
|
+
render or hooks (`onMounted` included)**: the update is refused there and drawn on the next
|
|
351
|
+
frame. Use `useEditorEffect`, `useEditorLayoutEffect` or an event handler.
|
|
352
|
+
- A document component's `onMounted` runs before Wordgard's tiles exist: `useNodePos()`'s function
|
|
353
|
+
throws there; call it from handlers and `useEditorEffect`.
|
|
354
|
+
- Components outside the document render the state in Vue's next tick after the update, on the
|
|
355
|
+
same paint; a test reading them waits for `nextTick`. So do components in one editor's document
|
|
356
|
+
reading another editor (a sub-editor's chrome, a `WordgardScope`'s components): they render
|
|
357
|
+
after that editor's update, never inside it.
|
|
358
|
+
- An error a component in the document throws is logged; the next update draws the document again.
|
|
359
|
+
|
|
360
|
+
### Server rendering
|
|
361
|
+
|
|
362
|
+
A Nuxt page (or any server-rendered app) needs no `<ClientOnly>`: on the server, and while the
|
|
363
|
+
page hydrates, `WordgardEditor` creates no editor and draws nothing, since Wordgard needs the DOM.
|
|
364
|
+
Its slot appears once the page has mounted, on the update after it. Its props are still built on
|
|
365
|
+
the server: give the document as `doc` (HTML), or load it with `schema.docFromJSON`; a
|
|
366
|
+
`GardState.create({ doc: html })` in a component's setup throws there. In a page drawn in the
|
|
367
|
+
browser only, the editor is created at once, as before.
|
|
368
|
+
|
|
369
|
+
### Limits
|
|
370
|
+
|
|
371
|
+
- A Vue wrapper can't wrap text, or a node a native widget draws (draw it with a Vue widget).
|
|
372
|
+
- Functional components in the document commit after Wordgard's update, not inside it.
|
|
373
|
+
- Templates compiled in the browser need Vue's full build (`vue/dist/vue.esm-bundler.js`);
|
|
374
|
+
single-file components don't.
|
|
375
|
+
|
|
376
|
+
## API
|
|
377
|
+
|
|
378
|
+
Everything is exported from `@stesura/vue-wordgard`.
|
|
379
|
+
|
|
380
|
+
- Components: `WordgardEditor`, `WordgardDoc`, `WordgardScope`, `DecorationRoot`, `NodeContent`,
|
|
381
|
+
`WrappedNode`.
|
|
382
|
+
- Factories: `createShape`, `createWrapper`, `createMarkShape`, `createWidgetType`, `nodeWrapper`.
|
|
383
|
+
- Editor composables, under `WordgardEditor` or `WordgardScope`: `useWordgard`, `useWordgardRef`,
|
|
384
|
+
`useEditorState`, `useEditorField`, `useEditorFieldEntry`, `useEditorEffect`,
|
|
385
|
+
`useEditorLayoutEffect`, `useEditorEventListener`.
|
|
386
|
+
- Decoration composables, in a decoration's component: `useNodePos`, `useIsNodeSelected`,
|
|
387
|
+
`useSelectNode`, `useStopEvent`, `useIgnoreMutation`.
|
|
388
|
+
- Helpers: `useMergedDOMRefs(...refs)` (one function `:ref` setting several, each given the
|
|
389
|
+
element, a component's root element on a component), `staticCopy(dom)` (a copy of what an editor
|
|
390
|
+
drew, without its ids and editor attributes), `isTrailingBreak(dom)` (the `<br>` ending a
|
|
391
|
+
textblock, not a line break's).
|
|
392
|
+
- Props types: `ShapeComponentProps`, `WrapperComponentProps`, `MarkComponentProps`,
|
|
393
|
+
`WidgetComponentProps`, `NodeWrapperComponentProps`.
|
|
394
|
+
- `VueWordgard.create(spec)`: an editor drawn by Vue outside a component tree (tests, benchmarks).
|
|
395
|
+
In a Vue app, use `WordgardEditor`.
|
|
396
|
+
|
|
397
|
+
The composables' and components' signatures and details are in their typings
|
|
398
|
+
(`dist/index.d.ts`).
|
|
399
|
+
|
|
400
|
+
## Coming from react-wordgard
|
|
401
|
+
|
|
402
|
+
| react-wordgard | vue-wordgard |
|
|
403
|
+
| ---------------------------------------------------- | --------------------------------------------------------- |
|
|
404
|
+
| `{children}` in `contentDOMRef`'s element | `<NodeContent as="…" />`, or `<DecorationRoot content />` |
|
|
405
|
+
| A wrapper's `{children}` | `<WrappedNode />` |
|
|
406
|
+
| `{...props}` and `ref` on a root drawn by hand | nothing: attributes fall through, the root is found |
|
|
407
|
+
| `useEditorStateSelector(selector)` | `computed(() => selector(useEditorState().value))` |
|
|
408
|
+
| `useEditorEventCallback(callback)` | a plain function using `useWordgard()` |
|
|
409
|
+
| `useEditorEffect(effect, deps)` | `useEditorEffect(effect, source)` |
|
|
410
|
+
| `NodeRootProps` in a node wrapper | attributes on its `<WrappedNode />` |
|
|
411
|
+
| `useWordgard()` under a `WordgardScope` that changes | `useWordgardRef()` |
|
|
412
|
+
| `useIsNodeSelected()` returning a boolean | `useIsNodeSelected()` returning a `ref` |
|
|
413
|
+
|
|
414
|
+
## AI coding agents
|
|
415
|
+
|
|
416
|
+
The package ships a skill for building editors with vue-wordgard: `skills/vue-wordgard/` (in
|
|
417
|
+
`node_modules/@stesura/vue-wordgard/`). Copy that folder into your project's `.claude/skills/`, or
|
|
418
|
+
point your agent to its `SKILL.md`.
|
|
419
|
+
|
|
420
|
+
## Licence
|
|
421
|
+
|
|
422
|
+
MIT, © 2026 Edoardo Caratti, see [LICENSE.txt](LICENSE.txt).
|
|
423
|
+
|
|
424
|
+
Includes code from react-prosemirror (© Handle with Care Collective and The New York Times
|
|
425
|
+
Company), through react-wordgard; its notices are in
|
|
426
|
+
[THIRD_PARTY_LICENSES.txt](THIRD_PARTY_LICENSES.txt). Its core, `@stesura/wordgard-view`, also
|
|
427
|
+
includes code from Wordgard (© Marijn Haverbeke).
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
vue-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
|
+
vue-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.
|