@fusion.dev/helix-editor 0.220.0 → 0.222.0

package/README.md

@@ -1,50 +1,151 @@
 # @fusion.dev/helix-editor
 
-Connects Helix's `Code Editor` to CodeMirror 6, themed from your tokens:
-highlighting in your theme's syntax colors, line numbers, folding, bracket
-matching and history, diagnostics underlined in their tone with their line
-numbers drawn in it, and the editor's own find bar finding and replacing in
-CodeMirror.
+Connects the Helix `Editor` frame to ProseMirror: a schema whose blocks each
+keep an id, the editing plugins, and a document drawn in your tokens.
 
 ```sh
-bun add @fusion.dev/helix @fusion.dev/helix-editor
+bun add @fusion.dev/helix @fusion.dev/helix-editor prosemirror-model prosemirror-state prosemirror-view
 ```
 
-The element is on the [Code Editor reference](https://fusion.dev/helix/components/code-editor).
-On its own it is a text field in the code face; connected, CodeMirror draws it.
-For a few lines of code in a form, `Code Input` needs no engine.
+The element is on the [Editor reference](https://fusion.dev/helix/components/editor),
+with its toolbar, its keys, and its parts.
+
+```html
+<helix-editor label="Release notes" placeholder="Write the release notes">
+  <div data-prose><h2>Release notes</h2><p>Write documents in your theme.</p></div>
+</helix-editor>
+```
 
 ```js
-import '@fusion.dev/helix/code-editor'
-import { connectEditor } from '@fusion.dev/helix-editor'
+import '@fusion.dev/helix/editor'
+import { connectEditor, editorPlugins, editorSchema } from '@fusion.dev/helix-editor'
+import { DOMParser } from 'prosemirror-model'
+import { EditorState } from 'prosemirror-state'
+import { EditorView } from 'prosemirror-view'
+
+const frame = document.querySelector('helix-editor')
+const content = frame.querySelector('[data-prose]')
+const schema = editorSchema()
 
-const editor = document.querySelector('helix-code-editor')
-const disconnect = connectEditor(editor)
+const view = new EditorView(
+  { mount: content },
+  {
+    state: EditorState.create({
+      doc: DOMParser.fromSchema(schema).parse(content),
+      plugins: editorPlugins(schema),
+    }),
+  },
+)
+const connection = connectEditor(frame, view)
 
-editor.language = 'ts'
-editor.diagnostics = [{ from: 79, to: 83, message: 'Cannot find name totl.' }]
-editor.addEventListener('input', () => save(editor.value))
+// Later, when the editor goes away:
+connection.disconnect()
+view.destroy()
 ```
 
-The value, the form, validation, and the events stay the element's: an edit in
-CodeMirror goes through the element's `requestValue`, so a listener refusing
-`helix-before-change` refuses the keystroke, and `input` follows each edit.
+**The document is your element, inside the frame.** ProseMirror draws in it,
+so the browser's input methods, spellcheck, and right-to-left text work as they
+do in any field, and a server can send the document's HTML there to be read
+before any script loads. `data-prose` on it has the base layer draw its blocks
+from the first paint. `connectEditor` adds the rules ProseMirror needs to
+the page, so you load no stylesheet of ProseMirror's.
+
+**ProseMirror is a peer dependency.** ProseMirror's packages check each
+other's classes, so a page has one copy of `prosemirror-model`,
+`prosemirror-state`, `prosemirror-transform`, and `prosemirror-view`, and this
+package uses yours.
+
+## What it exports
+
+| Export | What |
+|---|---|
+| `connectEditor(frame, view, options)` | Connects a frame to a view, and returns a connection with `disconnect()` |
+| `editorSchema(options)` | The schema: Helix's blocks and marks, with your own added through `nodes` and `marks` |
+| `editorPlugins(schema, options)` | The keys, Markdown typed at the start of a line, history, the drop and gap cursors, `blockIds`, `editorFind`, and `editorFrame` |
+| `blockIds(options)` | Keeps every block's id its own |
+| `findBlock(doc, id)` | Where a block stands, by its id |
+| `withBlockId(spec)` | A block of your own that keeps an id as Helix's do |
+| `toolCommands(schema, overrides)` | The command each toolbar tool runs |
+| `formatsOf(state, commands)` | What the toolbar shows for a state |
+| `setLink(schema, href)` | Links the selection, or with an empty address takes its link off |
+| `safeHref(href)` | The address a link may have, or an empty string for one that could run something |
+| `editorFrame()` | The plugin the frame speaks to the view through, which `editorPlugins` includes |
+| `editorFind()` | The find bar's search in the document, which `editorPlugins` includes |
+| `findIn(view, query, direction)`, `replaceIn(view, query, all)`, `endFind(view)` | What the frame's find bar runs: find and select a match, replace, and take the marks away |
+| `matchesIn(doc, query)`, `findResultOf(state)` | Where a query matches in a document, and where an open search stands |
+| `editorNodes`, `editorMarks` | Helix's node and mark specs |
+| `EDITOR_CSS`, `adoptEditorSheet(root)` | The rules `connectEditor` adds to the page |
+
+| Option | Of | What it does |
+|---|---|---|
+| `commands` | `connectEditor`, `editorPlugins` | Runs your commands in place of Helix's, by tool, such as undo and redo from y-prosemirror |
+| `history` | `editorPlugins` | `false` leaves the undo history to another plugin |
+| `markdown` | `editorPlugins` | `false` turns off `# `, `- `, `1. `, `> `, and three backticks at the start of a line |
+| `marks`, `nodes` | `editorSchema` | Marks and nodes of your own, or one of Helix's replaced by its name |
+| `generate` | `blockIds` | Makes a new id. Twelve letters and digits by default |
+
+## Blocks and their ids
+
+The schema keeps ProseMirror's own names: `paragraph`, `heading`,
+`blockquote`, `code_block`, `horizontal_rule`, `bullet_list`, `ordered_list`,
+`list_item`, and `hard_break`, with the marks `link`, `em`, `strong`, `strike`,
+and `code`. Markdown reads into it and writes out of it through
+`prosemirror-markdown` as it is.
+
+Every block carries an `id`, written to `data-block-id` in HTML. `blockIds`
+gives an id to a block that has none, and the second of two blocks sharing one
+a new one, as a split or a paste leaves them. `findBlock(doc, id)` finds a
+block again, for a comment anchored to it or an edit an agent makes to it.
+
+A paragraph and a heading are drawn with `dir="auto"`, so each runs in the
+direction of its own first letters, and a code block left to right.
 
-## Languages
+## Find
 
-`language` takes `css`, `html`, `js`, `jsx`, `json`, `md`, `py`, `rs`, `sh`,
-`ts` and `tsx`, and the names they go by, such as `typescript`, `markdown`,
-`python` and `rust`. Each grammar loads the first time an editor asks for it.
-Any other name is plain text.
+The frame's find bar searches the document through `connectEditor`: every
+match is marked, the selected one is scrolled into view, and Replace and
+Replace all change the document in one step of the undo history. A match never
+runs from one block into the next. While the bar is open, a change to the
+document finds again, and the bar says the new count. A read-only document is
+searched, and nothing in it is replaced.
 
-## More of CodeMirror
+## Collaboration
 
-`connectEditor(editor, { extensions })` adds CodeMirror extensions after
-Helix's own, such as completions or a language server client. To connect
-CodeMirror under your own control, set the element's `engine` to
-`codeMirrorEngine(options)`, or to an engine of your own that answers `mount`.
+The page makes the editor's state, so a binding such as y-prosemirror is
+plugins the page adds. Its own history replaces ProseMirror's:
+
+```js
+import { redoCommand, undoCommand, yCursorPlugin, ySyncPlugin, yUndoPlugin } from 'y-prosemirror'
+
+const commands = { redo: redoCommand, undo: undoCommand }
+const state = EditorState.create({
+  schema,
+  plugins: [
+    ySyncPlugin(fragment),
+    yCursorPlugin(awareness),
+    yUndoPlugin(),
+    ...editorPlugins(schema, { commands, history: false }),
+  ],
+})
+connectEditor(frame, new EditorView({ mount: content }, { state }), { commands })
+```
+
+**A command is also asked without `dispatch`**, after every change, to know
+whether its button can be pressed, so it has to change nothing then. That is
+why the example takes y-prosemirror's `undoCommand` and `redoCommand`: its
+`undo` and `redo` undo whenever they are called.
+
+Block ids are attributes of the blocks, so the binding merges them with the
+rest of the document.
+
+## Working on it
+
+```sh
+bun run --filter @fusion.dev/helix-editor build
+bun run --filter @fusion.dev/helix-editor test
+```
 
-## Keyboard
+The specs run ProseMirror's own view, under `bun test` and in a browser with
+`bun run specs:browser editor`, where an input method's composition reaches it.
 
-Tab indents, and Escape then Tab leaves the editor. Command+F, or Control+F on
-Windows and Linux, opens the editor's find bar, and Command+Z undoes.
+MIT

package/dist/block-ids/block-ids.d.ts

@@ -0,0 +1,36 @@
+import type { Node } from 'prosemirror-model';
+import { Plugin, PluginKey } from 'prosemirror-state';
+/**
+ * A new block id: twelve letters and digits, from the platform's random
+ * source.
+ *
+ * **`getRandomValues` and not `randomUUID`**, which a page served over plain
+ * HTTP from anywhere but `localhost` does not have.
+ */
+export declare const newBlockId: () => string;
+/** The key the block id plugin is found under. */
+export declare const blockIdsKey: PluginKey<any>;
+/** What `blockIds` takes. */
+export interface BlockIdsOptions {
+    /** Makes a new id. `newBlockId` by default. */
+    generate?: (() => string) | undefined;
+}
+/**
+ * Keeps every block's id its own: a block with none is given one, and where
+ * a split or a paste leaves two blocks sharing an id, the second is given a
+ * new one, so the first, the block that was there, keeps it.
+ *
+ * Ids are given in the same step as the edit that called for them, so undo
+ * takes both back together. A document loaded without ids is given them as
+ * the view mounts, outside history, so undo never takes them away.
+ *
+ * **Under collaboration each writer gives ids for its own edits.** Ids are
+ * attributes of the blocks, which a binding such as y-prosemirror merges as it
+ * merges the rest, so every copy settles on the same id for a block.
+ */
+export declare const blockIds: (options?: BlockIdsOptions) => Plugin;
+/** Where a block stands in the document, by its id, or nothing where no block has it. */
+export declare const findBlock: (doc: Node, id: string) => {
+    node: Node;
+    pos: number;
+} | undefined;

package/dist/block-ids/block-ids.js

@@ -0,0 +1,66 @@
+import { Plugin, PluginKey } from 'prosemirror-state';
+const ALPHABET = 'abcdefghijklmnopqrstuvwxyz0123456789';
+const LENGTH = 12;
+export const newBlockId = () => {
+    const bytes = crypto.getRandomValues(new Uint8Array(LENGTH));
+    let id = '';
+    for (const byte of bytes) {
+        id += ALPHABET[byte % ALPHABET.length];
+    }
+    return id;
+};
+const keepsId = (node) => 'id' in (node.type.spec.attrs ?? {});
+const fixIds = (state, generate) => {
+    const seen = new Set();
+    let tr = null;
+    state.doc.descendants((node, pos) => {
+        if (keepsId(node)) {
+            const id = node.attrs.id;
+            if (typeof id !== 'string' || id === '' || seen.has(id)) {
+                let next = generate();
+                while (seen.has(next)) {
+                    next = generate();
+                }
+                seen.add(next);
+                tr ??= state.tr;
+                tr.setNodeAttribute(pos, 'id', next);
+            }
+            else {
+                seen.add(id);
+            }
+        }
+        return !node.isTextblock;
+    });
+    return tr;
+};
+export const blockIdsKey = new PluginKey('helix-block-ids');
+export const blockIds = (options = {}) => {
+    const generate = options.generate ?? newBlockId;
+    return new Plugin({
+        appendTransaction: (transactions, _before, state) => transactions.some((tr) => tr.docChanged) ? fixIds(state, generate) : null,
+        key: blockIdsKey,
+        view: (view) => {
+            queueMicrotask(() => {
+                const tr = view.isDestroyed ? null : fixIds(view.state, generate);
+                if (tr) {
+                    view.dispatch(tr.setMeta('addToHistory', false));
+                }
+            });
+            return {};
+        },
+    });
+};
+export const findBlock = (doc, id) => {
+    let found;
+    doc.descendants((node, pos) => {
+        if (found) {
+            return false;
+        }
+        if (keepsId(node) && node.attrs.id === id) {
+            found = { node, pos };
+            return false;
+        }
+        return !node.isTextblock;
+    });
+    return found;
+};

package/dist/connect-editor/connect-editor.d.ts

@@ -0,0 +1,65 @@
+import { type Command, Plugin, PluginKey } from 'prosemirror-state';
+import { type EditorView } from 'prosemirror-view';
+import { type EditorTool } from '../tools/tools.js';
+/** What the frame tells a renderer, as the frame's settings stand. */
+interface Settings {
+    label: string;
+    placeholder: string;
+    readOnly: boolean;
+}
+/** What the bridge holds: the frame's settings, and whether a frame is connected. */
+interface Bridge extends Settings {
+    connected: boolean;
+}
+/** The key the frame's plugin is found under. */
+export declare const editorFrameKey: PluginKey<Bridge>;
+/**
+ * The plugin the frame speaks to the view through: it names the document for
+ * a screen reader, makes it read-only, shows the placeholder, and hears every
+ * update. `editorPlugins` includes it, so connecting changes nothing about
+ * the view's plugins.
+ *
+ * **Included from the start where it can be**, because adding a plugin later
+ * remakes every plugin's view, and a collaboration binding draws the whole
+ * document again when its view is remade. `connectEditor` adds it only to a
+ * view whose plugins were chosen without it.
+ *
+ * Every document carries `data-prose`, which the base layer draws its blocks
+ * by. A document is a `textbox` that takes several lines while a frame is
+ * connected, named by the frame's `label`.
+ */
+export declare const editorFrame: () => Plugin<Bridge>;
+/** What a connection takes beyond the frame and the view. */
+export interface ConnectEditorOptions {
+    /**
+     * The commands to run in place of Helix's, by tool, such as undo and redo
+     * where y-prosemirror keeps the history. Pass the same to `editorPlugins`,
+     * so the keys run them too.
+     *
+     * Each is also asked with no `dispatch` after every change, to know whether
+     * its button can be pressed, and has to change nothing then: y-prosemirror's
+     * `undoCommand` and `redoCommand`, and never its `undo` and `redo`, which
+     * undo whenever they are called.
+     */
+    commands?: Partial<Record<EditorTool, Command>> | undefined;
+}
+/** A connection, which is ended rather than left to leak. */
+export interface EditorConnection {
+    /** Stops answering the frame, detaches the view from it, and puts back what connecting changed. */
+    disconnect(): void;
+}
+/**
+ * Connects an Editor frame to a ProseMirror view.
+ *
+ * The frame's toolbar runs its tools in the view and shows what holds at the
+ * selection; the frame's find bar searches the document, and replaces in it
+ * unless it is read-only; the frame's `label`, `placeholder`, and `readonly`
+ * reach the document; and the editor's rules are added to the page, so the
+ * document is drawn in your tokens.
+ *
+ * The frame is `helix-editor` or `helix-headless-editor`, and the view's
+ * schema is `editorSchema()` or one of your own: a tool whose node or mark
+ * the schema lacks is left off the toolbar.
+ */
+export declare const connectEditor: (frame: HTMLElement, view: EditorView, options?: ConnectEditorOptions) => EditorConnection;
+export {};

package/dist/connect-editor/connect-editor.js

@@ -0,0 +1,142 @@
+import { Plugin, PluginKey } from 'prosemirror-state';
+import { Decoration, DecorationSet } from 'prosemirror-view';
+import { editorFind, editorFindKey, endFind, findIn, findResultOf, replaceIn, } from '../find/find.js';
+import { adoptEditorSheet } from '../sheet/editor-sheet.js';
+import { EDITOR_TOOLS, formatsOf, setLink, toolCommands, } from '../tools/tools.js';
+const isFrame = (element) => typeof element.attach === 'function';
+const UNCONNECTED = { connected: false, label: '', placeholder: '', readOnly: false };
+export const editorFrameKey = new PluginKey('helix-editor-frame');
+const listeners = new WeakMap();
+const placeholderOf = (state, text) => {
+    const { doc } = state;
+    const first = doc.firstChild;
+    if (text === '' || doc.childCount !== 1 || !first?.isTextblock || first.content.size > 0) {
+        return DecorationSet.empty;
+    }
+    return DecorationSet.create(doc, [
+        Decoration.node(0, first.nodeSize, {
+            class: 'helix-editor-placeholder',
+            'data-placeholder': text,
+        }),
+    ]);
+};
+export const editorFrame = () => new Plugin({
+    key: editorFrameKey,
+    props: {
+        attributes: (state) => {
+            const bridge = editorFrameKey.getState(state) ?? UNCONNECTED;
+            if (!bridge.connected) {
+                return { 'data-prose': '' };
+            }
+            return {
+                ...(bridge.label ? { 'aria-label': bridge.label } : {}),
+                'aria-multiline': 'true',
+                ...(bridge.placeholder ? { 'aria-placeholder': bridge.placeholder } : {}),
+                ...(bridge.readOnly ? { 'aria-readonly': 'true' } : {}),
+                'data-prose': '',
+                role: 'textbox',
+            };
+        },
+        decorations: (state) => {
+            const bridge = editorFrameKey.getState(state);
+            return bridge?.connected ? placeholderOf(state, bridge.placeholder) : DecorationSet.empty;
+        },
+        editable: (state) => !editorFrameKey.getState(state)?.readOnly,
+    },
+    state: {
+        apply: (tr, bridge) => tr.getMeta(editorFrameKey) ?? bridge,
+        init: () => UNCONNECTED,
+    },
+    view: () => ({
+        update: (view) => listeners.get(view)?.(view.state),
+    }),
+});
+export const connectEditor = (frame, view, options = {}) => {
+    if (!isFrame(frame)) {
+        throw new Error(`connectEditor: <${frame.localName}> is not an editor frame. Import @fusion.dev/helix/editor, and connect once the element is defined.`);
+    }
+    const { schema } = view.state;
+    const commands = toolCommands(schema, options.commands);
+    const runs = EDITOR_TOOLS.filter((tool) => tool === 'link' ? schema.marks.link !== undefined : commands[tool] !== undefined);
+    const added = [
+        ...(editorFrameKey.get(view.state) ? [] : [editorFrame()]),
+        ...(editorFindKey.get(view.state) ? [] : [editorFind()]),
+    ];
+    if (added.length > 0) {
+        view.updateState(view.state.reconfigure({ plugins: [...view.state.plugins, ...added] }));
+    }
+    adoptEditorSheet(view.root);
+    let sink;
+    let told = '';
+    let toldFound = '';
+    let answering = false;
+    const tell = (state) => {
+        const formats = formatsOf(state, commands);
+        const said = JSON.stringify(formats);
+        if (sink && said !== told) {
+            told = said;
+            sink.formats(formats);
+        }
+        const found = findResultOf(state);
+        const where = found ? `${found.count} ${found.index}` : '';
+        if (sink && found && where !== toldFound && !answering) {
+            sink.found(found);
+        }
+        toldFound = where;
+    };
+    const answer = (search) => {
+        answering = true;
+        try {
+            return search();
+        }
+        finally {
+            answering = false;
+        }
+    };
+    listeners.set(view, tell);
+    sink = frame.attach({
+        find: (query, direction) => answer(() => findIn(view, query, direction)),
+        findEnd: () => {
+            if (!view.isDestroyed) {
+                endFind(view);
+            }
+        },
+        focus: () => view.focus(),
+        replace: (query, all) => answer(() => replaceIn(view, query, all)),
+        run: (tool, value) => {
+            if (view.isDestroyed) {
+                return false;
+            }
+            const command = tool === 'link' ? setLink(schema, value ?? '') : commands[tool];
+            return command ? command(view.state, view.dispatch, view) : false;
+        },
+        settings: (settings) => {
+            if (!view.isDestroyed) {
+                view.dispatch(view.state.tr
+                    .setMeta(editorFrameKey, { connected: true, ...settings })
+                    .setMeta('addToHistory', false));
+            }
+        },
+        tools: () => runs,
+    });
+    tell(view.state);
+    return {
+        disconnect: () => {
+            sink?.detach();
+            sink = undefined;
+            listeners.delete(view);
+            if (view.isDestroyed) {
+                return;
+            }
+            endFind(view);
+            if (added.length > 0) {
+                view.updateState(view.state.reconfigure({
+                    plugins: view.state.plugins.filter((plugin) => !added.includes(plugin)),
+                }));
+            }
+            if (editorFrameKey.get(view.state)) {
+                view.dispatch(view.state.tr.setMeta(editorFrameKey, UNCONNECTED).setMeta('addToHistory', false));
+            }
+        },
+    };
+};

package/dist/find/find.d.ts

@@ -0,0 +1,74 @@
+import type { Node } from 'prosemirror-model';
+import { type EditorState, Plugin, PluginKey } from 'prosemirror-state';
+import { type EditorView } from 'prosemirror-view';
+/**
+ * What the frame's find bar asks for. The headless tier's `FindQuery`, held
+ * to this by a spec, so this package depends on no tier.
+ */
+export interface EditorFindQuery {
+    /** Whether case has to match, so "Error" does not find "error". */
+    caseSensitive: boolean;
+    /** Whether `search` is a regular expression, in JavaScript's syntax. */
+    regex: boolean;
+    /** What Replace puts in place of a match. */
+    replace: string;
+    /** What the reader typed. */
+    search: string;
+    /** Whether a match has to be a whole word. */
+    wholeWord: boolean;
+}
+/** Where a search stands: how many matches, and which is selected, counting from 0, or -1 for none. */
+export interface EditorFindResult {
+    count: number;
+    index: number;
+}
+/** Which match a search selects: from the selection, the next one, or the previous one. */
+export type EditorFindDirection = 'first' | 'next' | 'previous';
+/** One match, as positions in the document. */
+interface Match {
+    from: number;
+    to: number;
+}
+/** What the find plugin holds: the search, every match, and the selected one. */
+interface Found {
+    current: number;
+    matches: readonly Match[];
+    query: EditorFindQuery | undefined;
+}
+/** The key the find plugin is found under. */
+export declare const editorFindKey: PluginKey<Found>;
+/**
+ * Every match of `query` in the document, block by block, so a match never
+ * runs from one block into the next, nor across a hard break.
+ */
+export declare const matchesIn: (doc: Node, query: EditorFindQuery) => Match[];
+/**
+ * The find bar's search in the document: every match marked, as
+ * `helix-find-match`, and the selected one as `helix-find-current`, which the
+ * connector's sheet paints as the base layer paints Find's highlights.
+ * `editorPlugins` includes it.
+ *
+ * While a search is open, a change to the document finds again, staying on
+ * the match the selected one became.
+ */
+export declare const editorFind: () => Plugin<Found>;
+/** Where the search in a state stands, or nothing while none is open. */
+export declare const findResultOf: (state: EditorState) => EditorFindResult | undefined;
+/**
+ * Finds `query` in the view's document, marks every match, and selects one:
+ * with `first`, the first from the selection's start, which stays on a
+ * selected match while the reader types; with `next`, the first from its
+ * end; with `previous`, the last before its start. Each wraps around the
+ * ends. The selected match is scrolled into view.
+ */
+export declare const findIn: (view: EditorView, query: EditorFindQuery, direction: EditorFindDirection) => EditorFindResult;
+/** Takes the marks a search drew away, and leaves the selection where it is. */
+export declare const endFind: (view: EditorView) => void;
+/**
+ * Replaces the selected match, or every match with `all`, in one step of the
+ * undo history, and then selects the next match. Where the selection is no
+ * match, it selects the next one and replaces nothing. A regular expression's
+ * groups reach the replacement as `$1`, as they do in JavaScript.
+ */
+export declare const replaceIn: (view: EditorView, query: EditorFindQuery, all: boolean) => EditorFindResult;
+export {};