@stesura/vue-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 ADDED
@@ -0,0 +1,15 @@
1
+ ## 0.4.0 (2026-11-19)
2
+
3
+ ### New features
4
+
5
+ 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.
6
+
7
+ `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.
8
+
9
+ `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.
10
+
11
+ `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.
12
+
13
+ `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.
14
+
15
+ `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
- # Temporary Holding Version
1
+ # vue-wordgard
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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.