@stesura/react-wordgard 0.1.0 → 0.2.1

package/dist/ReactWordgard.js

@@ -1,7 +1,5 @@
-// Adapted from react-prosemirror's ReactEditorView, to fit Wordgard: it
-// extends Wordgard instead of EditorView and, where ReactEditorView replaces
-// the docView ProseMirror's constructor builds, has the base constructor build
-// a tile tree React renders.
+// Adapted from react-prosemirror's ReactEditorView, to fit Wordgard: it extends Wordgard, and its
+// base constructor builds a tile tree React renders, where ReactEditorView replaces the docView.
 import { Wordgard } from "wordgard/editor";
 import { GardState } from "wordgard/state";
 import { editorOf } from "./contexts/EditorContext.js";

package/dist/components/ChildNodeViews.js

@@ -1,7 +1,5 @@
-// Named after react-prosemirror's ChildNodeViews, rewritten for Wordgard: draws
-// what iterDeco lays out: nodes, text, mark wrappers, Wordgard's hack nodes and
-// React widgets. Native widgets aren't React's: ReactDocTile puts their DOM in
-// place after the commit.
+// Named after react-prosemirror's ChildNodeViews, rewritten for Wordgard: draws what iterDeco lays
+// out. Native widgets aren't React's: ReactDocTile puts their DOM in place after the commit.
 import React, { memo } from "react";
 import { cellOf } from "../contexts/RenderStoreContext.js";
 import { isReactWidget } from "../decorations/ReactWidgetType.js";

package/dist/components/DecorationRoot.d.ts

@@ -1,7 +1,13 @@
 import { type AllHTMLAttributes, type ReactNode } from "react";
+/** `DecorationRoot`'s props: its root's attributes, and its children. */
 export type DecorationRootProps = AllHTMLAttributes<HTMLElement> & {
     children?: ReactNode;
 };
+/**
+ * The root element of a React shape, wrapper, mark or widget: the tag the decoration says, with
+ * Wordgard's attributes merged with the props. See [React
+ * decorations](https://github.com/stesura/react-wordgard#react-decorations).
+ */
 export declare const DecorationRoot: import("react").ForwardRefExoticComponent<AllHTMLAttributes<HTMLElement> & {
     children?: ReactNode;
 } & import("react").RefAttributes<Element>>;

package/dist/components/DecorationRoot.js

@@ -1,11 +1,14 @@
-// A React shape's, wrapper's or mark's root, drawn for its component: the tag
-// its Elt says, Wordgard's attributes and the root's ref, so the component
-// can't get them wrong. The component's own props win, but `className` joins
-// Wordgard's and `style` merges, its keys winning. Not in react-prosemirror.
+// Not in react-prosemirror. The component's own props win, but `className` joins Wordgard's and
+// `style` merges, its keys winning.
 import { createElement, forwardRef, useContext, useMemo, } from "react";
 import { DecorationRootContext } from "../contexts/DecorationRootContext.js";
 import { cssToStyle, htmlAttrsToReactProps } from "../helpers/props.js";
 import { mergeRefs, toCallbackRef } from "../helpers/refs.js";
+/**
+ * The root element of a React shape, wrapper, mark or widget: the tag the decoration says, with
+ * Wordgard's attributes merged with the props. See [React
+ * decorations](https://github.com/stesura/react-wordgard#react-decorations).
+ */
 export const DecorationRoot = forwardRef(({ className, style, ...props }, ref) => {
     const root = useContext(DecorationRootContext);
     const rootRef = root?.ref;

package/dist/components/ErrorBoundary.js

@@ -1,8 +1,6 @@
-// Not in react-prosemirror: catches an error thrown while React renders the
-// document, for ReactDocTile to throw it from the update. React 18 rethrows it
-// from flushSync, React 19 reports it as uncaught and commits nothing, and the
-// tiles can't be built over what didn't commit. A class: React has no hook for
-// this.
+// Not in react-prosemirror: catches a render error for ReactDocTile to throw from the update. React
+// 18 rethrows it from flushSync, React 19 reports it and commits nothing. A class: React has no
+// hook for this.
 import { Component } from "react";
 export class ErrorBoundary extends Component {
     state = { failed: false };

package/dist/components/SeparatorHackView.js

@@ -1,5 +1,4 @@
 // Named after react-prosemirror's SeparatorHackView, rewritten for Wordgard: the
-// `<img class="wg-buffer">` Wordgard puts at the start and end of an inline plot
-// (`Widget.img`), which gives the cursor somewhere to go.
+// `<img class="wg-buffer">` (`Widget.img`) at the ends of an inline plot.
 import React from "react";
 export const SeparatorHackView = () => React.createElement("img", { className: "wg-buffer" });

package/dist/components/ShapeView.js

@@ -1,7 +1,5 @@
-// Named after react-prosemirror's ReactNodeView, for Wordgard: draws a React
-// shape's component, with the node's content as its children. ReactDocTile
-// builds the tiles over what it commits; the component's own commits are
-// sorted out of Wordgard's DOM observer (`sortRecords`).
+// Named after react-prosemirror's ReactNodeView, for Wordgard: draws a React shape's component. Its
+// own commits are sorted out of Wordgard's DOM observer (`sortRecords`).
 import React, { useMemo, useState } from "react";
 import { DecorationContext, createDecorationHandlers, decorationRoot, } from "../contexts/DecorationContext.js";
 import { atomRef, createShapeHandle, drawShape, nodePos, shapeAttributes, } from "../decorations/ReactShapeType.js";

package/dist/components/TextNodeView.js

@@ -1,5 +1,4 @@
-// Named after react-prosemirror's TextNodeView, rewritten for Wordgard: a text
-// leaf renders as a bare text node, its tile is built after the commit
-// (ReactDocTile). Skipped while its text is the same.
+// Named after react-prosemirror's TextNodeView, rewritten for Wordgard: a bare text node, whose
+// tile ReactDocTile builds after the commit.
 import { memo } from "react";
 export const TextNodeView = memo(({ text }) => text);

package/dist/components/TrailingHackView.js

@@ -1,5 +1,4 @@
-// Named after react-prosemirror's TrailingHackView, rewritten for Wordgard: the
-// `<br>` Wordgard's own renderer adds to a textblock that needs one
-// (`Widget.br`).
+// Named after react-prosemirror's TrailingHackView, rewritten for Wordgard: the `<br>` a textblock
+// may need (`Widget.br`).
 import React from "react";
 export const TrailingHackView = () => React.createElement("br", null);

package/dist/components/WidgetView.js

@@ -1,8 +1,5 @@
-// Named after react-prosemirror's WidgetView, rewritten for Wordgard: draws a
-// React widget's component, whose root element becomes the widget's DOM.
-// ReactDocTile builds its tile after the commit, so there's no view
-// description to register here. Skipped while the widget is `eq`, so the
-// component keeps its DOM, as Wordgard keeps an equal widget's.
+// Named after react-prosemirror's WidgetView, rewritten for Wordgard. Skipped while the widget is
+// `eq`, so the component keeps its DOM, as Wordgard keeps an equal widget's.
 import React, { memo, useMemo, useRef, useState } from "react";
 import { DecorationContext, createDecorationHandlers, decorationRoot, } from "../contexts/DecorationContext.js";
 import { DecorationRootContext } from "../contexts/DecorationRootContext.js";

package/dist/components/WordgardDoc.d.ts

@@ -1,4 +1,9 @@
 import React, { type HTMLAttributes } from "react";
 type Props = Omit<HTMLAttributes<HTMLDivElement>, "children">;
+/**
+ * Puts the editor in the page, inside a `div` taking the props, and renders the document through a
+ * portal, in your React tree. It goes under its `<WordgardEditor>`, inside any other components,
+ * with other children before or after it. One per editor: a second throws.
+ */
 export declare const WordgardDoc: (props: Props) => React.JSX.Element;
 export {};

package/dist/components/WordgardDoc.js

@@ -1,9 +1,6 @@
-// Named after react-prosemirror's ProseMirrorDoc, rewritten for Wordgard:
-// puts the editor's element in the page, inside a `div` taking the props, and
-// renders its document through a portal into Wordgard's content element, so
-// the document shares the app's React tree and contexts. The portal commits
-// first and builds the tiles; attaching the element then connects the editor,
-// as Wordgard's own editor is built before it's connected.
+// Named after react-prosemirror's ProseMirrorDoc, rewritten for Wordgard. The portal commits first
+// and builds the tiles; attaching the element then connects the editor, as Wordgard's own editor is
+// built before it's connected.
 import React, { useCallback, useInsertionEffect, useLayoutEffect, useSyncExternalStore, } from "react";
 import { createPortal } from "react-dom";
 import { editorOf, useEditorContext } from "../contexts/EditorContext.js";
@@ -19,6 +16,11 @@ const DocPortal = ({ wg }) => {
     useLayoutEffect(() => portal.mount(), [portal]);
     return createPortal(element, wg.contentDOM);
 };
+/**
+ * Puts the editor in the page, inside a `div` taking the props, and renders the document through a
+ * portal, in your React tree. It goes under its `<WordgardEditor>`, inside any other components,
+ * with other children before or after it. One per editor: a second throws.
+ */
 export const WordgardDoc = (props) => {
     const { wg } = useEditorContext();
     const attach = useCallback((dom) => {

package/dist/components/WordgardEditor.d.ts

@@ -3,5 +3,13 @@ import type { Wordgard } from "wordgard/editor";
 type Props = Omit<Wordgard.Spec, "parent"> & {
     children?: ReactNode;
 };
+/**
+ * Creates a Wordgard editor from the spec (`doc`, `config`, `selection`, `state`, `scrollTo`) and
+ * provides it to its children. It draws no DOM of its own. The spec is read once, on mount: from
+ * then on the editor owns its state (see [Accessing the state outside the
+ * editor](https://github.com/stesura/react-wordgard#accessing-the-state-outside-the-editor)). In
+ * React's StrictMode (development only), it creates its editor twice and drops one, which is never
+ * put in the page.
+ */
 export declare const WordgardEditor: ({ children, ...spec }: Props) => React.JSX.Element;
 export {};

package/dist/components/WordgardEditor.js

@@ -1,12 +1,16 @@
-// Named after react-prosemirror's ProseMirror component, rewritten for
-// Wordgard: creates the editor and provides it to what it holds, WordgardDoc
-// and the app's own components (menus, hooks). The spec is read once, as
-// react-prosemirror's `defaultState`: Wordgard's editor owns its state, so
-// changes go through `dispatch`, and configuration through Wordgard's
-// compartments or `GardState.appendConfig`.
+// Named after react-prosemirror's ProseMirror component, rewritten for Wordgard. The spec is read
+// once, as react-prosemirror's `defaultState`: Wordgard's editor owns its state.
 import React, { useState } from "react";
 import { ReactWordgard } from "../ReactWordgard.js";
 import { EditorContext, editorOf } from "../contexts/EditorContext.js";
+/**
+ * Creates a Wordgard editor from the spec (`doc`, `config`, `selection`, `state`, `scrollTo`) and
+ * provides it to its children. It draws no DOM of its own. The spec is read once, on mount: from
+ * then on the editor owns its state (see [Accessing the state outside the
+ * editor](https://github.com/stesura/react-wordgard#accessing-the-state-outside-the-editor)). In
+ * React's StrictMode (development only), it creates its editor twice and drops one, which is never
+ * put in the page.
+ */
 export const WordgardEditor = ({ children, ...spec }) => {
     const [editor] = useState(() => editorOf(ReactWordgard.host(spec)));
     return React.createElement(EditorContext.Provider, { value: editor }, children);

package/dist/components/WordgardScope.d.ts

@@ -0,0 +1,14 @@
+import React, { type ReactNode } from "react";
+import type { Wordgard } from "wordgard/editor";
+type Props = {
+    wg: Wordgard;
+    children?: ReactNode;
+};
+/**
+ * Gives the components it holds `wg`, an editor a `WordgardEditor` made elsewhere, in place of the
+ * one around them: for a toolbar acting on whichever of a page's editors has focus. The hooks under
+ * it follow when `wg` changes: selectors subscribe to the new editor's state, callbacks and
+ * listeners get it, effects run again. Any other editor throws.
+ */
+export declare const WordgardScope: ({ wg, children }: Props) => React.JSX.Element;
+export {};

package/dist/components/WordgardScope.js

@@ -0,0 +1,14 @@
+import React from "react";
+import { EditorContext, findEditor } from "../contexts/EditorContext.js";
+/**
+ * Gives the components it holds `wg`, an editor a `WordgardEditor` made elsewhere, in place of the
+ * one around them: for a toolbar acting on whichever of a page's editors has focus. The hooks under
+ * it follow when `wg` changes: selectors subscribe to the new editor's state, callbacks and
+ * listeners get it, effects run again. Any other editor throws.
+ */
+export const WordgardScope = ({ wg, children }) => {
+    const editor = findEditor(wg);
+    if (!editor)
+        throw new Error("WordgardScope takes an editor a WordgardEditor made");
+    return React.createElement(EditorContext.Provider, { value: editor }, children);
+};

package/dist/components/WrapperView.js

@@ -1,7 +1,4 @@
-// Draws a React wrapper's component, with what it wraps (the node's shape, or
-// the element its `target` picks) as its children. Like ShapeView, it has no
-// effects: ReactDocTile builds the tiles over what it commits, and the
-// component's own commits are sorted out of Wordgard's DOM observer.
+// Like ShapeView, no effects: ReactDocTile builds the tiles over what it commits.
 import React, { useMemo, useState } from "react";
 import { DecorationContext, createDecorationHandlers, decorationRoot, } from "../contexts/DecorationContext.js";
 import { createWrapperHandle, nodePos, shapeAttributes } from "../decorations/ReactShapeType.js";

package/dist/components/marks/MarkView.js

@@ -1,9 +1,6 @@
-// Named after react-prosemirror's MarkView, rewritten for Wordgard: draws a
-// wrapper, either an element-shaped mark or the span holding a text run's
-// attribute-shaped marks, or a React mark's component. It draws what it holds
-// from its views, so it can be skipped while they keep their shape (iterDeco
-// keeps a wrapper's unchanged views; a node that changed gets its view from
-// its cell).
+// Named after react-prosemirror's MarkView, rewritten for Wordgard: an element-shaped mark, the
+// span of a text run's attribute-shaped marks, or a React mark. Memoised: iterDeco keeps a
+// wrapper's unchanged views.
 import React, { createElement, memo } from "react";
 import { shapeOf } from "../../decorations/iterDeco.js";
 import { attrsToRecord, htmlAttrsToReactProps } from "../../helpers/index.js";

package/dist/components/marks/ReactMarkView.js

@@ -1,7 +1,5 @@
-// Named after react-prosemirror's ReactMarkView, rewritten for Wordgard: draws
-// a React mark's component around the marked content. As ShapeView, it has no
-// effects: ReactDocTile builds the tiles over what it commits, and the
-// component's own commits are sorted out of Wordgard's DOM observer.
+// Named after react-prosemirror's ReactMarkView, rewritten for Wordgard. Like ShapeView, no
+// effects: ReactDocTile builds the tiles over what it commits.
 import React, { useMemo, useState } from "react";
 import { DecorationContext, createDecorationHandlers, decorationRoot, } from "../../contexts/DecorationContext.js";
 import { drawMark } from "../../decorations/ReactMarkType.js";

package/dist/components/nodes/DefaultNodeView.js

@@ -1,10 +1,6 @@
-// Named after react-prosemirror's DefaultNodeView, rewritten for Wordgard: a
-// node renders as the shape Wordgard's decorations give it (its
-// buildNodeShape), with the plot's content in the hole. In Wordgard every node
-// type has a shape, so there's no missing `toDOM` to check for. Widgets, as a
-// node's shape or inside it, are drawn by their component when they're React
-// widgets, else draw nothing: ReactDocTile puts their DOM in place. React
-// shapes and wrappers in the shape are drawn by ShapeView and WrapperView.
+// Named after react-prosemirror's DefaultNodeView, rewritten for Wordgard: a node renders as its
+// decorated shape (buildNodeShape). Every Wordgard node type has a shape, so there's no missing
+// `toDOM` to check for. Native widgets draw nothing: ReactDocTile puts their DOM in place.
 import React, { Component, createElement } from "react";
 import { Attributes, Elt } from "wordgard/doc";
 import { isReactShape, shapeAttributes } from "../../decorations/ReactShapeType.js";

package/dist/components/nodes/DocNodeView.js

@@ -1,6 +1,5 @@
-// Named after react-prosemirror's DocNodeView, rewritten for Wordgard: the
-// document's content renders straight into Wordgard's content element, which
-// is React's container.
+// Named after react-prosemirror's DocNodeView, rewritten for Wordgard: renders straight into
+// Wordgard's content element, React's container.
 import React from "react";
 import { ChildNodeViews } from "../ChildNodeViews.js";
 export const DocNodeView = ({ views }) => React.createElement(ChildNodeViews, { views: views });

package/dist/composition.js

@@ -1,9 +1,7 @@
-// How the React view keeps a composition alive through Wordgard's flush, as
-// Wordgard's ContentUpdate.composition does (src/editor/tile.ts in its repo):
-// the browser's text node stays as it is, in a tile of its own. React must not
-// write to it: when React drew it, React keeps rendering the value it last
-// committed there, in the wrappers it committed around it; when the browser
-// made it (or an element around it), React draws nothing in its place.
+// Keeps a composition alive through Wordgard's flush, as Wordgard's ContentUpdate.composition does:
+// the browser's text node stays, in a tile of its own, and React must not write to it. When React
+// drew it, React keeps rendering what it last committed there; when the browser made it, React
+// draws nothing in its place.
 import { Attributes, Elt } from "wordgard/doc";
 import { cursorWrappers, } from "./decorations/iterDeco.js";
 import { markOfTile, markTiles } from "./decorations/ReactMarkType.js";

package/dist/contexts/DecorationContext.js

@@ -1,8 +1,5 @@
-// The React decoration (shape, wrapper, mark or widget) a component is drawn
-// in, for the hooks react-prosemirror's node views use: its position, whether
-// its node is selected, and the handlers its components register. It takes
-// the place of react-prosemirror's GetPosContext, SelectNodeContext,
-// StopEventContext and IgnoreMutationContext.
+// The React decoration a component is drawn in, for the decoration hooks. Replaces
+// react-prosemirror's GetPosContext, SelectNodeContext, StopEventContext and IgnoreMutationContext.
 import { createContext, useContext } from "react";
 export const DecorationContext = createContext(null);
 export const useDecorationContext = (hook) => {

package/dist/contexts/DecorationRootContext.js

@@ -1,6 +1,4 @@
-// What DecorationRoot draws: the root a React shape's, wrapper's or mark's Elt
-// says, with Wordgard's attributes and the root's ref. Not in
-// react-prosemirror, whose node views draw their root themselves: Wordgard
-// fixes the root's tag before React draws.
+// Not in react-prosemirror, whose node views draw their root: Wordgard fixes the root's tag before
+// React draws.
 import { createContext } from "react";
 export const DecorationRootContext = createContext(null);

package/dist/contexts/EditorContext.d.ts

@@ -21,6 +21,7 @@ type Editor = EditorContextValue & {
     flushing: boolean;
 };
 export declare const editorOf: (wg: Wordgard) => Editor;
+export declare const findEditor: (wg: Wordgard) => EditorContextValue | undefined;
 export declare const EditorContext: import("react").Context<EditorContextValue | null>;
 export declare const useEditorContext: () => EditorContextValue;
 export {};

package/dist/contexts/EditorContext.js

@@ -1,6 +1,4 @@
-// Named after react-prosemirror's EditorContext, rewritten for Wordgard: the
-// editor, the state as of its last flush (react-prosemirror's state store),
-// and what the hooks register to run around its flush. One value per editor,
+// Named after react-prosemirror's EditorContext, rewritten for Wordgard. One value per editor,
 // which never changes, so memoised components aren't scanned for it.
 import { createContext, useContext } from "react";
 import { flushSync } from "react-dom";
@@ -78,6 +76,8 @@ export const editorOf = (wg) => {
     editors.set(wg, editor);
     return editor;
 };
+// The editor's value when react-wordgard drives it (WordgardEditor made it).
+export const findEditor = (wg) => editors.get(wg);
 export const EditorContext = createContext(null);
 export const useEditorContext = () => {
     const context = useContext(EditorContext);

package/dist/contexts/RenderStoreContext.js

@@ -1,8 +1,6 @@
-// Named after our react-prosemirror fork's RenderStoreContext, rewritten for
-// Wordgard: what the view computes for rendering, held in one object per
-// content element and provided once, so its context value never changes and
-// memoised node views are never scanned for it. ReactDocTile writes it inside
-// Wordgard's flush, before React renders.
+// Named after our react-prosemirror fork's RenderStoreContext, rewritten for Wordgard: one object
+// per content element, which ReactDocTile writes inside the flush. Its value never changes, so
+// memoised node views aren't scanned for it.
 import { createContext, useContext } from "react";
 const cells = new WeakMap();
 export const cellOf = (view) => {

package/dist/contexts/editorEvents.js

@@ -1,9 +1,6 @@
-// The DOM events useEditorEventListener can listen to, and the handlers
-// ReactWordgard installs for them. Wordgard has a handler per event type, so
-// the types are fixed when the editor is created. Adding a handler makes
-// Wordgard's listener for the type non-passive: the events that block
-// scrolling (touch, wheel) aren't among them, nor the most frequent ones
-// (mousemove, pointer events), each of which would then walk the tiles.
+// The DOM events useEditorEventListener can listen to. Wordgard fixes its handlers' event types at
+// creation, and a handler makes its listener non-passive: scroll-blocking events (touch, wheel) and
+// frequent ones (mousemove, pointer events) are left out.
 import { Wordgard } from "wordgard/editor";
 import { GardState } from "wordgard/state";
 export const editorEvents = [

package/dist/decorations/ReactMarkType.d.ts

@@ -1,6 +1,9 @@
 import { type AllHTMLAttributes, type ComponentType, type HTMLProps, type ReactElement, type ReactNode, type RefAttributes, type RefCallback } from "react";
 import type { Elt, Mark } from "wordgard/doc";
 import type { Tile } from "../wordgardInternals.js";
+/**
+ * A React mark's props, for each run of an equal mark: `markProps.mark` is the document's mark.
+ */
 export type MarkComponentProps<E extends Element = HTMLElement> = AllHTMLAttributes<HTMLElement> & {
     markProps: {
         mark: Mark;
@@ -9,7 +12,12 @@ export type MarkComponentProps<E extends Element = HTMLElement> = AllHTMLAttribu
     };
     children: ReactNode;
 } & RefAttributes<E>;
+/** `createMarkShape`'s options. */
 export type MarkShapeOptions = {
+    /**
+     * The component's root element, `span` by default, which plain Wordgard draws. It can't come from
+     * the mark type: a mark type's own `shape` is written before the type exists.
+     */
     element?: string;
 };
 type DrawProps = {
@@ -22,6 +30,9 @@ type MarkShape = {
     element: string;
     attributes: Record<string, string>;
 };
+/**
+ * A mark's shape, for `Decoration.Mark.shape(MarkType, shape)` or a mark type's own `shape`.
+ */
 export declare const createMarkShape: <E extends Element = HTMLElement>(component: ComponentType<MarkComponentProps<E>>, { element }?: MarkShapeOptions) => MarkShape;
 export declare const isReactMark: (elt: Elt<unknown>) => boolean;
 export declare const drawMark: (elt: Elt<unknown>, props: DrawProps) => ReactElement<any, string | import("react").JSXElementConstructor<any>>;

package/dist/decorations/ReactMarkType.js

@@ -1,10 +1,6 @@
-// Named after ReactWidgetType: a React mark is a mark's element shape (for
-// `Decoration.Mark.shape`, or a mark type's own spec), the element plain
-// Wordgard draws, registered as drawn by a component, which renders the
-// marked content as `children`. Wordgard's mark shapes are declarative, so the
-// registration is the reserved attribute React shapes use, which the element
-// Wordgard makes from the shape keeps. The props follow react-prosemirror's
-// MarkComponentProps.
+// Named after ReactWidgetType. A React mark is a mark's element shape, registered as drawn by a
+// component through the reserved attribute React shapes use: Wordgard's mark shapes are
+// declarative. The props follow react-prosemirror's MarkComponentProps.
 import { createElement, } from "react";
 import { takesRef } from "../helpers/refs.js";
 import { idOf, reserved } from "./ReactShapeType.js";
@@ -12,6 +8,9 @@ import { idOf, reserved } from "./ReactShapeType.js";
 const draws = new Map();
 // By component, then root element, as React shapes are.
 const marks = new WeakMap();
+/**
+ * A mark's shape, for `Decoration.Mark.shape(MarkType, shape)` or a mark type's own `shape`.
+ */
 export const createMarkShape = (component, { element = "span" } = {}) => {
     let registered = marks.get(component);
     if (!registered) {

package/dist/decorations/ReactShapeType.d.ts

@@ -1,5 +1,12 @@
 import { type AllHTMLAttributes, type ComponentType, type HTMLProps, type ReactElement, type ReactNode, type RefAttributes, type RefCallback } from "react";
 import { type Node as DocNode, Elt } from "wordgard/doc";
+/**
+ * A React shape's props: `nodeProps`, the content as `children`, and Wordgard's attributes and
+ * `ref` for its root. The content goes in the `contentDOMRef` element, else in the root; in an
+ * atom, `children` is empty and a `contentDOMRef` throws. With `<DecorationRoot>` as the root, the
+ * attributes and `ref` are taken care of; a root drawn by hand spreads them onto itself (see [A
+ * root drawn by hand](https://github.com/stesura/react-wordgard#a-root-drawn-by-hand)).
+ */
 export type ShapeComponentProps<E extends Element = HTMLElement> = AllHTMLAttributes<HTMLElement> & {
     nodeProps: {
         node: DocNode;
@@ -8,6 +15,11 @@ export type ShapeComponentProps<E extends Element = HTMLElement> = AllHTMLAttrib
     };
     children: ReactNode;
 } & RefAttributes<E>;
+/**
+ * What `createShape` returns: for `Decoration.Tag.shape`, a node's shape, its root the node type's
+ * own outer element, an atom where the type's shape is. `of` gives the shape with `element` for its
+ * root: for `Decoration.Point.shape`, or a root other than the type's.
+ */
 export type ReactShape = ((tag: DocNode.Tag) => Elt) & {
     of: (element: string, options?: {
         atom?: boolean;
@@ -20,6 +32,10 @@ type DrawProps = {
     children: ReactNode;
     ref: RefCallback<Element>;
 };
+/**
+ * A node's shape, for `Decoration.Tag.shape(NodeType, shape)`. `shape.of(element)` is the shape
+ * with another root element, also for `Decoration.Point.shape`.
+ */
 export declare const createShape: <E extends Element = HTMLElement>(component: ComponentType<ShapeComponentProps<E>>) => ReactShape;
 export declare const idOf: (elt: Elt<unknown>) => string | null;
 export declare const isReactShape: (elt: Elt<unknown>) => boolean;

package/dist/decorations/ReactShapeType.js

@@ -1,14 +1,8 @@
-// Named after ReactWidgetType: a React shape is a real Wordgard `Elt`, the
-// shape plain Wordgard draws, registered as drawn by a component, which renders
-// the content as `children`. Wordgard resolves decorations on the Elt before
-// React renders (`target` selectors match its tag), so its tag is known up
-// front: `createShape` gives `Decoration.Tag.shape` a function of the tag, which
-// takes it from the tag's node type, per node (a heading's level). Without a
-// hole, as for the type's own shape, it draws an atom. Wordgard copies an Elt
-// when it adds attributes or wraps it, so the registration is a reserved
-// attribute, which every copy keeps; React never renders it. The props follow
-// react-prosemirror's node views (`nodeProps`, `contentDOMRef`, a forwarded
-// ref), named after the decoration: Wordgard has no node views.
+// Named after ReactWidgetType. A React shape is a real Wordgard `Elt`, registered as drawn by a
+// component through a reserved attribute, which every copy Wordgard makes of it keeps and React
+// never renders. Its tag is fixed before React renders (`target` selectors match it), so
+// `createShape` gives `Decoration.Tag.shape` a function of the tag. The props follow
+// react-prosemirror's node views (`nodeProps`, `contentDOMRef`, a forwarded ref).
 import { createElement, } from "react";
 import { Attributes, Elt } from "wordgard/doc";
 import { ignoresMutation } from "../contexts/DecorationContext.js";
@@ -18,6 +12,10 @@ const draws = new Map();
 // By component: calling createShape again with one gives the same shape, so
 // Wordgard sees no configuration change and the registry doesn't grow.
 const shapes = new WeakMap();
+/**
+ * A node's shape, for `Decoration.Tag.shape(NodeType, shape)`. `shape.of(element)` is the shape
+ * with another root element, also for `Decoration.Point.shape`.
+ */
 export const createShape = (component) => {
     const found = shapes.get(component);
     if (found)

package/dist/decorations/ReactWidgetType.d.ts

@@ -1,13 +1,23 @@
 import { type AllHTMLAttributes, type ComponentType, type HTMLProps, type ReactElement, type RefAttributes, type RefCallback } from "react";
 import { Attributes, Elt } from "wordgard/doc";
 import { Widget } from "wordgard/editor";
+/**
+ * A React widget's props: its `value`, and, for a widget drawing a node, the node's attributes for
+ * its root.
+ */
 export type WidgetComponentProps<Param, E extends Element = HTMLElement> = Omit<AllHTMLAttributes<HTMLElement>, "value"> & {
     value: Param;
 } & RefAttributes<E>;
+/** `createWidgetType`'s spec: Wordgard's widget spec, with a component in place of `render`. */
 export type WidgetTypeSpec<Param, E extends Element = HTMLElement> = Omit<Widget.Spec<Param>, "render"> & {
     component: ComponentType<WidgetComponentProps<Param, E>>;
+    /**
+     * The root `DecorationRoot` draws in the component, `span` by default. Wordgard doesn't look at a
+     * widget's element, so it's the component's choice.
+     */
     element?: string;
 };
+/** A widget type whose widgets, `type.of(value)`, the component draws. */
 export declare const createWidgetType: <Param, E extends Element = HTMLElement>(spec: WidgetTypeSpec<Param, E>) => Widget.Type<Param>;
 export declare const createWidgetTypeWithRender: <Param, E extends Element = HTMLElement>(spec: WidgetTypeSpec<Param, E> & Pick<Widget.Spec<Param>, "render">) => Widget.Type<Param>;
 export declare const isReactWidget: (widget: Widget) => boolean;

package/dist/decorations/ReactWidgetType.js

@@ -1,11 +1,8 @@
-// Named after react-prosemirror's ReactWidgetType, rewritten for Wordgard: a
-// React widget type is a real Wordgard widget type, made by Widget.define with
-// the same spec, drawn by its component in the editor's own React tree. As
-// in react-prosemirror, the component forwards its ref to its root element,
-// which becomes the widget's DOM. Wordgard ignores what the component changes
-// inside that element, so it may re-render on its own, but not swap the
-// element itself: the parent's tile would put the old one back. An editable
-// one the user edits keeps the edit, where Wordgard would redraw it.
+// Named after react-prosemirror's ReactWidgetType, rewritten for Wordgard: a real Wordgard widget
+// type (Widget.define, same spec), drawn by its component in the editor's React tree. Its root,
+// which the component forwards its ref to, is the widget's DOM: the component may re-render inside
+// it, but not swap it, or the parent's tile puts the old one back. An editable one the user edits
+// keeps the edit, where Wordgard would redraw it.
 import { createElement, } from "react";
 import { Attributes, Elt } from "wordgard/doc";
 import { Widget } from "wordgard/editor";
@@ -16,6 +13,7 @@ const components = new WeakMap();
 // Widget.define needs a `render`, which ReactWordgard never calls: only plain
 // Wordgard, given a React widget, draws this.
 const placeholder = () => document.createElement("span");
+/** A widget type whose widgets, `type.of(value)`, the component draws. */
 export const createWidgetType = (spec) => createWidgetTypeWithRender({ ...spec, render: placeholder });
 // For the tests comparing ReactWordgard with plain Wordgard, which draws
 // `render`.

package/dist/decorations/ReactWrapperType.d.ts

@@ -1,5 +1,8 @@
 import { type AllHTMLAttributes, type ComponentType, type HTMLProps, type ReactElement, type ReactNode, type RefAttributes, type RefCallback } from "react";
 import { type Node as DocNode, Elt } from "wordgard/doc";
+/**
+ * A React wrapper's props: as a shape's, without `contentDOMRef`. `children` is what it wraps.
+ */
 export type WrapperComponentProps<E extends Element = HTMLElement> = AllHTMLAttributes<HTMLElement> & {
     nodeProps: {
         node: DocNode;
@@ -7,7 +10,12 @@ export type WrapperComponentProps<E extends Element = HTMLElement> = AllHTMLAttr
     };
     children: ReactNode;
 } & RefAttributes<E>;
+/** `createWrapper`'s options. */
 export type WrapperOptions = {
+    /**
+     * The component's root element, `div` by default: `target` selectors match it, and plain Wordgard
+     * draws it. `span` around an inline node.
+     */
     element?: string;
 };
 type DrawProps = {
@@ -16,6 +24,7 @@ type DrawProps = {
     children: ReactNode;
     ref: RefCallback<Element>;
 };
+/** A wrapper, for `Decoration.Tag.wrapper` and `Decoration.Point.wrapper`. */
 export declare const createWrapper: <E extends Element = HTMLElement>(component: ComponentType<WrapperComponentProps<E>>, { element }?: WrapperOptions) => Elt;
 export declare const isReactWrapper: (elt: Elt<unknown>) => boolean;
 export declare const drawWrapper: (elt: Elt<unknown>, props: DrawProps) => ReactElement<any, string | import("react").JSXElementConstructor<any>>;