@stesura/react-wordgard 0.0.0-stage → 0.2.0

package/dist/helpers/refs.d.ts

@@ -0,0 +1,6 @@
+import { type ForwardedRef, type RefCallback } from "react";
+type DOMRef = (dom: Element | null) => void;
+export declare const mergeRefs: (...refs: (DOMRef | undefined)[]) => DOMRef;
+export declare const toCallbackRef: <T>(ref: ForwardedRef<T>) => RefCallback<T> | undefined;
+export declare const takesRef: (component: unknown) => boolean;
+export {};

package/dist/helpers/refs.js

@@ -0,0 +1,20 @@
+import { version } from "react";
+// A React decoration's root ref, with what else must know its root: the
+// React wrapper around it, its hooks' handlers.
+export const mergeRefs = (...refs) => (dom) => {
+    for (const ref of refs)
+        ref?.(dom);
+};
+// A forwarded ref as a callback, for mergeRefs.
+export const toCallbackRef = (ref) => typeof ref == "function"
+    ? ref
+    : ref
+        ? (value) => {
+            ref.current = value;
+        }
+        : undefined;
+// Whether React gives `component` a ref: React 19 passes it as a prop, React
+// 18 only to a forwardRef (an object) and warns for a function component,
+// which needs none with DecorationRoot.
+const refAsProp = Number(version.split(".")[0]) >= 19;
+export const takesRef = (component) => refAsProp || typeof component != "function";

package/dist/hooks/useEditorEffect.d.ts

@@ -0,0 +1,10 @@
+import { type DependencyList } from "react";
+import type { Wordgard } from "wordgard/editor";
+/**
+ * Runs `effect` once the editor's DOM is up to date: after the flush under way or pending, else in
+ * a microtask, never inside React's commit. It may read layout and dispatch; what it sets shows a
+ * frame later. For focus, follow-up dispatches and menus. The dependencies work as React's. Don't
+ * read the editor's layout from a plain React effect: it can run inside Wordgard's update, before
+ * the editor's view of the new DOM exists.
+ */
+export declare const useEditorEffect: (effect: (wg: Wordgard) => void | (() => void), dependencies?: DependencyList) => void;

package/dist/hooks/useEditorEffect.js

@@ -0,0 +1,28 @@
+// Named after react-prosemirror's useEditorEffect, rewritten for Wordgard.
+import { useLayoutEffect } from "react";
+import { useEditorContext } from "../contexts/EditorContext.js";
+/**
+ * Runs `effect` once the editor's DOM is up to date: after the flush under way or pending, else in
+ * a microtask, never inside React's commit. It may read layout and dispatch; what it sets shows a
+ * frame later. For focus, follow-up dispatches and menus. The dependencies work as React's. Don't
+ * read the editor's layout from a plain React effect: it can run inside Wordgard's update, before
+ * the editor's view of the new DOM exists.
+ */
+export const useEditorEffect = (effect, dependencies) => {
+    const { wg, afterFlush, cancel } = useEditorContext();
+    useLayoutEffect(() => {
+        let cleanup;
+        const run = () => {
+            cleanup = effect(wg);
+        };
+        afterFlush(run);
+        return () => {
+            cancel(run);
+            if (typeof cleanup == "function")
+                cleanup();
+        };
+        // The caller's dependencies, as with React's own effects, and the editor:
+        // a WordgardScope can change it.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, dependencies && [wg, ...dependencies]);
+};

package/dist/hooks/useEditorEventCallback.d.ts

@@ -0,0 +1,8 @@
+import type { Wordgard } from "wordgard/editor";
+/**
+ * A stable function calling the latest `callback` with the editor first, for event handlers. There,
+ * `wg.state` is the latest state, dispatches not yet drawn included. See the `SaveButton` in
+ * [Accessing the state outside the
+ * editor](https://github.com/stesura/react-wordgard#accessing-the-state-outside-the-editor).
+ */
+export declare const useEditorEventCallback: <Args extends unknown[], Result>(callback: (wg: Wordgard, ...args: Args) => Result) => (...args: Args) => Result;

package/dist/hooks/useEditorEventCallback.js

@@ -0,0 +1,17 @@
+// Named after react-prosemirror's useEditorEventCallback, rewritten for Wordgard.
+import { useCallback, useLayoutEffect, useRef } from "react";
+import { useEditorContext } from "../contexts/EditorContext.js";
+/**
+ * A stable function calling the latest `callback` with the editor first, for event handlers. There,
+ * `wg.state` is the latest state, dispatches not yet drawn included. See the `SaveButton` in
+ * [Accessing the state outside the
+ * editor](https://github.com/stesura/react-wordgard#accessing-the-state-outside-the-editor).
+ */
+export const useEditorEventCallback = (callback) => {
+    const { wg } = useEditorContext();
+    const latest = useRef(callback);
+    useLayoutEffect(() => {
+        latest.current = callback;
+    });
+    return useCallback((...args) => latest.current(wg, ...args), [wg]);
+};

package/dist/hooks/useEditorEventListener.d.ts

@@ -0,0 +1,10 @@
+import type { Wordgard } from "wordgard/editor";
+import { type EditorEvent } from "../contexts/editorEvents.js";
+/**
+ * Listens to the editor's DOM events of `type`, before Wordgard's handlers and keymaps. Returning
+ * `true` handles the event: Wordgard calls `preventDefault` and skips its own handling. The event
+ * types are listed under [Limits](https://github.com/stesura/react-wordgard#limits). Key events
+ * during a composition don't come; handling `input`, `beforeinput` or a composition event skips
+ * Wordgard's own handling of it, so leave typing to Wordgard.
+ */
+export declare const useEditorEventListener: <Type extends EditorEvent>(type: Type, handler: (wg: Wordgard, event: HTMLElementEventMap[Type]) => boolean | void) => void;

package/dist/hooks/useEditorEventListener.js

@@ -0,0 +1,26 @@
+// Named after react-prosemirror's useEditorEventListener, rewritten for Wordgard: ReactWordgard
+// installs a `prec.highest` Wordgard.domEventHandler per type, first in an editor made from
+// `config`, after the state's own in one made from a `state`. The latest registered runs first, as
+// in react-prosemirror.
+import { useLayoutEffect } from "react";
+import { useEditorContext } from "../contexts/EditorContext.js";
+import { listenersOf } from "../contexts/editorEvents.js";
+import { useEditorEventCallback } from "./useEditorEventCallback.js";
+/**
+ * Listens to the editor's DOM events of `type`, before Wordgard's handlers and keymaps. Returning
+ * `true` handles the event: Wordgard calls `preventDefault` and skips its own handling. The event
+ * types are listed under [Limits](https://github.com/stesura/react-wordgard#limits). Key events
+ * during a composition don't come; handling `input`, `beforeinput` or a composition event skips
+ * Wordgard's own handling of it, so leave typing to Wordgard.
+ */
+export const useEditorEventListener = (type, handler) => {
+    const { wg } = useEditorContext();
+    const listener = useEditorEventCallback(handler);
+    useLayoutEffect(() => {
+        const listeners = listenersOf(wg, type);
+        listeners.unshift(listener);
+        return () => {
+            listeners.splice(listeners.indexOf(listener), 1);
+        };
+    }, [wg, type, listener]);
+};

package/dist/hooks/useEditorLayoutEffect.d.ts

@@ -0,0 +1,15 @@
+import type { Wordgard } from "wordgard/editor";
+/** The `read` and `write` pair `useEditorLayoutEffect` takes. */
+export type EditorLayoutEffect<T> = {
+    read: (wg: Wordgard) => T | undefined;
+    write: (value: T, wg: Wordgard) => void;
+};
+/**
+ * Runs inside every editor update, without re-rendering: `read` in Wordgard's read phase, then
+ * `write` with its value in the write phase, on the same paint as the document. For what moves with
+ * the text (markers in the margin, pagination). It can't dispatch: Wordgard throws during its
+ * update. A `read` returning `undefined` skips its write, and when no read asks for a write, none
+ * is scheduled, which spares Wordgard measuring again. Reads run in the order the effects were
+ * registered.
+ */
+export declare const useEditorLayoutEffect: <T>(measure: EditorLayoutEffect<T>) => void;

package/dist/hooks/useEditorLayoutEffect.js

@@ -0,0 +1,34 @@
+// The other half of react-prosemirror's useEditorEffect, which ran inside React's commit. Here
+// React commits inside Wordgard's flush: useEditorEffect runs after it, this hook in it, through
+// Wordgard's scheduleDOMRead and scheduleDOMWrite. A write resizing the content makes Wordgard
+// measure again within the flush, so pagination settles there. Writes into the document's own DOM
+// are foreign edits to Wordgard: write inside widgets, outside the editor, or through decorations.
+import { useLayoutEffect, useRef } from "react";
+import { useEditorContext } from "../contexts/EditorContext.js";
+/**
+ * Runs inside every editor update, without re-rendering: `read` in Wordgard's read phase, then
+ * `write` with its value in the write phase, on the same paint as the document. For what moves with
+ * the text (markers in the margin, pagination). It can't dispatch: Wordgard throws during its
+ * update. A `read` returning `undefined` skips its write, and when no read asks for a write, none
+ * is scheduled, which spares Wordgard measuring again. Reads run in the order the effects were
+ * registered.
+ */
+export const useEditorLayoutEffect = (measure) => {
+    const { wg, measures, requestMeasure } = useEditorContext();
+    const latest = useRef(measure);
+    useLayoutEffect(() => {
+        latest.current = measure;
+    });
+    useLayoutEffect(() => {
+        const entry = () => {
+            const { read, write } = latest.current;
+            const value = read(wg);
+            return value === undefined ? null : () => write(value, wg);
+        };
+        measures.add(entry);
+        requestMeasure();
+        return () => {
+            measures.delete(entry);
+        };
+    }, [wg, measures, requestMeasure]);
+};

package/dist/hooks/useEditorState.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The state as of the editor's last flush, rendered in the same React commit as the document. The
+ * component re-renders on every flush: for a part of the state, use `useEditorStateSelector`; in a
+ * handler, `wg.state` is the latest.
+ */
+export declare const useEditorState: () => import("wordgard/state").GardState;

package/dist/hooks/useEditorState.js

@@ -0,0 +1,12 @@
+// Named after react-prosemirror's useEditorState, rewritten for Wordgard.
+import { useSyncExternalStore } from "react";
+import { useEditorContext } from "../contexts/EditorContext.js";
+/**
+ * The state as of the editor's last flush, rendered in the same React commit as the document. The
+ * component re-renders on every flush: for a part of the state, use `useEditorStateSelector`; in a
+ * handler, `wg.state` is the latest.
+ */
+export const useEditorState = () => {
+    const { store } = useEditorContext();
+    return useSyncExternalStore(store.subscribe, store.getState);
+};

package/dist/hooks/useEditorStateSelector.d.ts

@@ -0,0 +1,7 @@
+import type { GardState } from "wordgard/state";
+/**
+ * A part of the last flush's state, like Redux's `useSelector`: the component re-renders only when
+ * the result changes, by `Object.is` or by `isEqual`. A selector building a new object or array
+ * each time re-renders on every flush unless you pass `isEqual`.
+ */
+export declare const useEditorStateSelector: <Result>(selector: (state: GardState) => Result, isEqual?: (a: Result, b: Result) => boolean) => Result;

package/dist/hooks/useEditorStateSelector.js

@@ -0,0 +1,11 @@
+import { useSyncExternalStoreWithSelector } from "use-sync-external-store/with-selector";
+import { useEditorContext } from "../contexts/EditorContext.js";
+/**
+ * A part of the last flush's state, like Redux's `useSelector`: the component re-renders only when
+ * the result changes, by `Object.is` or by `isEqual`. A selector building a new object or array
+ * each time re-renders on every flush unless you pass `isEqual`.
+ */
+export const useEditorStateSelector = (selector, isEqual) => {
+    const { store } = useEditorContext();
+    return useSyncExternalStoreWithSelector(store.subscribe, store.getState, store.getState, selector, isEqual);
+};

package/dist/hooks/useIgnoreMutation.d.ts

@@ -0,0 +1,6 @@
+import type { Wordgard } from "wordgard/editor";
+/**
+ * Wordgard doesn't read the DOM mutations `ignore` returns `true` for, typing aside (Wordgard takes
+ * it from `beforeinput`). Mutations in chrome and React widgets never reach Wordgard anyway.
+ */
+export declare const useIgnoreMutation: (ignore: (wg: Wordgard, mutation: MutationRecord) => boolean) => void;

package/dist/hooks/useIgnoreMutation.js

@@ -0,0 +1,19 @@
+// Named after react-prosemirror's useIgnoreMutation, rewritten for Wordgard. Chrome mutations are
+// dropped before, by `sortRecords`.
+import { useLayoutEffect } from "react";
+import { useDecorationContext } from "../contexts/DecorationContext.js";
+import { useEditorEventCallback } from "./useEditorEventCallback.js";
+/**
+ * Wordgard doesn't read the DOM mutations `ignore` returns `true` for, typing aside (Wordgard takes
+ * it from `beforeinput`). Mutations in chrome and React widgets never reach Wordgard anyway.
+ */
+export const useIgnoreMutation = (ignore) => {
+    const { handlers } = useDecorationContext("useIgnoreMutation");
+    const callback = useEditorEventCallback(ignore);
+    useLayoutEffect(() => {
+        handlers.ignoreMutation.add(callback);
+        return () => {
+            handlers.ignoreMutation.delete(callback);
+        };
+    }, [handlers, callback]);
+};

package/dist/hooks/useIsNodeSelected.d.ts

@@ -0,0 +1,2 @@
+/** Whether the node the decoration draws is the editor's node selection. */
+export declare const useIsNodeSelected: () => boolean;

package/dist/hooks/useIsNodeSelected.js

@@ -0,0 +1,5 @@
+// Named after react-prosemirror's useIsNodeSelected, rewritten for Wordgard: read from the
+// `wg-selected-node` class Wordgard draws, so the component renders with it, without an effect.
+import { useDecorationContext } from "../contexts/DecorationContext.js";
+/** Whether the node the decoration draws is the editor's node selection. */
+export const useIsNodeSelected = () => useDecorationContext("useIsNodeSelected").selected;

package/dist/hooks/useMergedDOMRefs.d.ts

@@ -0,0 +1,6 @@
+import { type Ref, type RefCallback } from "react";
+/**
+ * One ref setting several, as for a root that's also the content element (`ref` and
+ * `contentDOMRef`).
+ */
+export declare const useMergedDOMRefs: <Value>(...refs: (Ref<Value> | undefined)[]) => RefCallback<Value>;

package/dist/hooks/useMergedDOMRefs.js

@@ -0,0 +1,18 @@
+// Adapted from react-prosemirror's useMergedDOMRefs (src/refs.ts there), without its typecast.
+import { useCallback } from "react";
+/**
+ * One ref setting several, as for a root that's also the content element (`ref` and
+ * `contentDOMRef`).
+ */
+export const useMergedDOMRefs = (...refs) => useCallback((value) => {
+    for (const ref of refs) {
+        if (typeof ref == "function")
+            ref(value);
+        else if (ref)
+            Object.assign(ref, { current: value });
+    }
+}, 
+// The refs themselves, as react-prosemirror's: a new callback when one
+// changes, so React gives it the element.
+// eslint-disable-next-line react-hooks/exhaustive-deps, react-hooks/use-memo
+refs);

package/dist/hooks/useNodePos.d.ts

@@ -0,0 +1,4 @@
+/**
+ * A function giving the position of what the decoration draws, to call in handlers and effects.
+ */
+export declare const useNodePos: () => () => number;

package/dist/hooks/useNodePos.js

@@ -0,0 +1,7 @@
+// Named after react-prosemirror's useNodePos, rewritten for Wordgard: read from the decoration's
+// tile. A function rather than the position: during render, the tile may not be built yet.
+import { useDecorationContext } from "../contexts/DecorationContext.js";
+/**
+ * A function giving the position of what the decoration draws, to call in handlers and effects.
+ */
+export const useNodePos = () => useDecorationContext("useNodePos").handlers.getPos;

package/dist/hooks/useSelectNode.d.ts

@@ -0,0 +1,6 @@
+import type { Wordgard } from "wordgard/editor";
+/**
+ * Calls `selectNode` when the node becomes the node selection, and `deselectNode` when it stops
+ * being it, once the editor's DOM is up to date (as `useEditorEffect`).
+ */
+export declare const useSelectNode: (selectNode: (wg: Wordgard) => void, deselectNode?: (wg: Wordgard) => void) => void;

package/dist/hooks/useSelectNode.js

@@ -0,0 +1,25 @@
+// Named after react-prosemirror's useSelectNode, rewritten for Wordgard.
+import { useRef } from "react";
+import { useEditorEffect } from "./useEditorEffect.js";
+import { useEditorEventCallback } from "./useEditorEventCallback.js";
+import { useIsNodeSelected } from "./useIsNodeSelected.js";
+const noop = () => { };
+/**
+ * Calls `selectNode` when the node becomes the node selection, and `deselectNode` when it stops
+ * being it, once the editor's DOM is up to date (as `useEditorEffect`).
+ */
+export const useSelectNode = (selectNode, deselectNode = noop) => {
+    const selected = useIsNodeSelected();
+    const select = useEditorEventCallback(selectNode);
+    const deselect = useEditorEventCallback(deselectNode);
+    const was = useRef(false);
+    useEditorEffect(() => {
+        if (selected == was.current)
+            return;
+        was.current = selected;
+        if (selected)
+            select();
+        else
+            deselect();
+    }, [selected, select, deselect]);
+};

package/dist/hooks/useStopEvent.d.ts

@@ -0,0 +1,8 @@
+import type { Wordgard } from "wordgard/editor";
+/**
+ * Asked for events in the decoration's chrome (its root and the elements around its content
+ * element, unless the root is the content element) and in React widgets; never for those in its
+ * content. For an event it stops, Wordgard's handlers and keymaps are skipped and the browser's
+ * default goes ahead: for a control in the chrome, such as an input.
+ */
+export declare const useStopEvent: (stopEvent: (wg: Wordgard, event: Event) => boolean) => void;

package/dist/hooks/useStopEvent.js

@@ -0,0 +1,21 @@
+// Named after react-prosemirror's useStopEvent, rewritten for Wordgard: consulted through widget
+// types' `propagateEvent`, and through the decoration's own elements' tiles (tile.ts `ownTile`).
+import { useLayoutEffect } from "react";
+import { useDecorationContext } from "../contexts/DecorationContext.js";
+import { useEditorEventCallback } from "./useEditorEventCallback.js";
+/**
+ * Asked for events in the decoration's chrome (its root and the elements around its content
+ * element, unless the root is the content element) and in React widgets; never for those in its
+ * content. For an event it stops, Wordgard's handlers and keymaps are skipped and the browser's
+ * default goes ahead: for a control in the chrome, such as an input.
+ */
+export const useStopEvent = (stopEvent) => {
+    const { handlers } = useDecorationContext("useStopEvent");
+    const stop = useEditorEventCallback(stopEvent);
+    useLayoutEffect(() => {
+        handlers.stopEvent.add(stop);
+        return () => {
+            handlers.stopEvent.delete(stop);
+        };
+    }, [handlers, stop]);
+};

package/dist/hooks/useWordgard.d.ts

@@ -0,0 +1,2 @@
+/** The editor. */
+export declare const useWordgard: () => import("wordgard/editor").Wordgard;

package/dist/hooks/useWordgard.js

@@ -0,0 +1,3 @@
+import { useEditorContext } from "../contexts/EditorContext.js";
+/** The editor. */
+export const useWordgard = () => useEditorContext().wg;

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+export { DecorationRoot, type DecorationRootProps } from "./components/DecorationRoot.js";
+export { WordgardDoc } from "./components/WordgardDoc.js";
+export { WordgardEditor } from "./components/WordgardEditor.js";
+export { WordgardScope } from "./components/WordgardScope.js";
+export { type MarkComponentProps, type MarkShapeOptions, createMarkShape, } from "./decorations/ReactMarkType.js";
+export { type ReactShape, type ShapeComponentProps, createShape, } from "./decorations/ReactShapeType.js";
+export { type WidgetTypeSpec, type WidgetComponentProps, createWidgetType, } from "./decorations/ReactWidgetType.js";
+export { type WrapperOptions, type WrapperComponentProps, createWrapper, } from "./decorations/ReactWrapperType.js";
+export { useEditorEffect } from "./hooks/useEditorEffect.js";
+export { useEditorEventCallback } from "./hooks/useEditorEventCallback.js";
+export { useEditorEventListener } from "./hooks/useEditorEventListener.js";
+export { type EditorLayoutEffect, useEditorLayoutEffect } from "./hooks/useEditorLayoutEffect.js";
+export { useEditorState } from "./hooks/useEditorState.js";
+export { useEditorStateSelector } from "./hooks/useEditorStateSelector.js";
+export { useIgnoreMutation } from "./hooks/useIgnoreMutation.js";
+export { useIsNodeSelected } from "./hooks/useIsNodeSelected.js";
+export { useMergedDOMRefs } from "./hooks/useMergedDOMRefs.js";
+export { useNodePos } from "./hooks/useNodePos.js";
+export { useSelectNode } from "./hooks/useSelectNode.js";
+export { useStopEvent } from "./hooks/useStopEvent.js";
+export { useWordgard } from "./hooks/useWordgard.js";

package/dist/index.js

@@ -0,0 +1,21 @@
+export { DecorationRoot } from "./components/DecorationRoot.js";
+export { WordgardDoc } from "./components/WordgardDoc.js";
+export { WordgardEditor } from "./components/WordgardEditor.js";
+export { WordgardScope } from "./components/WordgardScope.js";
+export { createMarkShape, } from "./decorations/ReactMarkType.js";
+export { createShape, } from "./decorations/ReactShapeType.js";
+export { createWidgetType, } from "./decorations/ReactWidgetType.js";
+export { createWrapper, } from "./decorations/ReactWrapperType.js";
+export { useEditorEffect } from "./hooks/useEditorEffect.js";
+export { useEditorEventCallback } from "./hooks/useEditorEventCallback.js";
+export { useEditorEventListener } from "./hooks/useEditorEventListener.js";
+export { useEditorLayoutEffect } from "./hooks/useEditorLayoutEffect.js";
+export { useEditorState } from "./hooks/useEditorState.js";
+export { useEditorStateSelector } from "./hooks/useEditorStateSelector.js";
+export { useIgnoreMutation } from "./hooks/useIgnoreMutation.js";
+export { useIsNodeSelected } from "./hooks/useIsNodeSelected.js";
+export { useMergedDOMRefs } from "./hooks/useMergedDOMRefs.js";
+export { useNodePos } from "./hooks/useNodePos.js";
+export { useSelectNode } from "./hooks/useSelectNode.js";
+export { useStopEvent } from "./hooks/useStopEvent.js";
+export { useWordgard } from "./hooks/useWordgard.js";

package/dist/reactKeys.d.ts

@@ -0,0 +1,39 @@
+import type { Plot } from "wordgard/doc";
+import type { Widget } from "wordgard/editor";
+import type { ChildView } from "./decorations/iterDeco.js";
+export type ReactKeys = WeakMap<Plot, readonly string[]>;
+export declare const createNodeKey: () => string;
+export declare const addFreshKeys: (keys: ReactKeys, plot: Plot) => void;
+export declare const mapKeys: (keys: ReactKeys, oldDoc: Plot, newDoc: Plot, changes: readonly number[]) => WeakMap<Plot, Plot>;
+export declare const childViewKeys: (views: readonly ChildView[]) => ({
+    view: {
+        type: "widget";
+        widget: Widget;
+        side: number;
+        key?: string;
+        offset?: number;
+    };
+    key: string;
+} | {
+    view: import("./decorations/iterDeco.js").NodeView | {
+        type: "text";
+        text: string;
+    } | {
+        type: "wrapper";
+        elt: import("./wordgardInternals.js").DecoElt;
+        spanning: boolean;
+        children: ChildView[];
+        key?: string;
+        mark?: import("wordgard/doc").Mark;
+    } | {
+        type: "buffer";
+        side: -1 | 1;
+    } | {
+        type: "composition";
+        key: string;
+        rendered: string | null;
+    } | {
+        type: "trailingHack";
+    };
+    key: string;
+})[];