How to create custom commands

[duhaime]

I'm trying to create a custom command that inserts an HR into the editor. I thought I'd start with this command because it's already written in milkdown, so once I get that working I can customize the command to implement my desired behavior.

Here's my fiddle. When a user clicks on the "hr" text, I'd like to run commandContext.call(InsertHr), but instead I get a stacktrace 'Context "cmdKey" not found, do you forget to inject it?'

Note that the command call works just fine if one uses commandContext.call(commands.InsertHr).

How can I make this command succeed?

Edit: I've just found the guide on this topic, but this guide only tells us how to delegate to prosemirror commands. Prosemirror, though, has a much richer syntax for commands that involve interacting with the state and dispatch, just as internal milkdown commands do.

Are there any guides on how to create custom commands using that richer internal syntax? Do commands need to be presented to milkdown through the plugin interface?

[duhaime]

After exploring this a bit, I've learned there are at least three ways to run commands. The first set of commands are exported by prosemirror-commands:

import * as prosemirrorCommands from "prosemirror-commands";

The next set of commands are exported by @milkdown/preset-commonmark:

import { commands as milkdownCommands } from "@milkdown/preset-commonmark";

The final set of commands are completely custom and let one use prosemirror's state and dispatch interfaces to create a custom command.

There are examples of all three commands below:

import React, { useState } from "react";

import {
  Editor,
  rootCtx,
  commandsCtx,
  defaultValueCtx,
  schemaCtx,
  createCmd,
  createCmdKey,
  CommandsReady,
} from "@milkdown/core";
import { AtomList, createNode } from '@milkdown/utils';
import { ReactEditor, useEditor } from "@milkdown/react";
import { commonmark } from "@milkdown/preset-commonmark";
import { InputRule, Selection } from "@milkdown/prose";
import { commands as milkdownCommands } from "@milkdown/preset-commonmark";
import * as prosemirrorCommands from "prosemirror-commands";
import { listener, listenerCtx } from "@milkdown/plugin-listener";
import { nord } from "@milkdown/theme-nord";
import { emoji } from "@milkdown/plugin-emoji";

/**
 * Approach for delegating to prosemirrorCommands (imported above)
 **/

export const CustomCommand = createCmdKey();
const myPlugin = () => async (ctx) => {
  await ctx.wait(CommandsReady);
  const commandManager = ctx.get(commandsCtx);
  const schema = ctx.get(schemaCtx);
  commandManager.create(CustomCommand, () =>
    // run a prosemirror command
    prosemirrorCommands.wrapIn(schema.nodes.blockquote)
  );
};

/**
 * Approach for delegating prosemirror commands with full state & dispatch interface
 **/

const id = 'hr';
const InsertHr = createCmdKey('InsertHr');
const hr = createNode((utils) => {
  const style = utils.getStyle(
    (themeTool, { css }) => css`
      height: ${themeTool.size.lineWidth};
      background-color: ${themeTool.palette('line')};
      border-width: 0;
    `,
  );
  return {
    id,
    schema: () => ({
      group: 'block',
      parseDOM: [{ tag: 'hr' }],
      toDOM: (node) => ['hr', { class: utils.getClassName(node.attrs, id, style) }],
      parseMarkdown: {
        match: ({ type }) => type === 'thematicBreak',
        runner: (state, _, type) => {
          state.addNode(type);
        },
      },
      toMarkdown: {
        match: (node) => node.type.name === id,
        runner: (state) => {
          state.addNode('thematicBreak');
        },
      },
    }),
    inputRules: (type) => [
      new InputRule(/^(?:---|___\s|\*\*\*\s)$/, (state, match, start, end) => {
        const { tr } = state;

        if (match[0]) {
          tr.replaceWith(start - 1, end, type.create());
        }

        return tr;
      }),
    ],
    commands: (type, ctx) => [
      createCmd(InsertHr, () => (state, dispatch) => {
        if (!dispatch) return true;
        const { tr, selection } = state;
        const from = selection.from;
        const node = type.create();
        if (!node) {
          return true;
        }
        const _tr = tr.replaceSelectionWith(node).insert(from, ctx.get(schemaCtx).node('paragraph'));
        const sel = Selection.findFrom(_tr.doc.resolve(from), 1, true);
        if (!sel) {
          return true;
        }
        dispatch(_tr.setSelection(sel).scrollIntoView());
        return true;
      }),
    ],
  };
});

const nodes = [
  hr(),
]

const customNodes = AtomList.create([...nodes])

const customCommands = {
  InsertHr
}

/**
 * Main app
 **/

export default function App() {
  const [ctx, setCtx] = useState(null);
  const editor = useEditor((root) =>
    Editor.make()
      .config((ctx) => {
        ctx.set(rootCtx, root);
        ctx.set(defaultValueCtx, "# Milkdown :heartpulse: React");
        ctx.get(listenerCtx).mounted(() => {
          setCtx(ctx);
        });
      })
      .use(nord)
      .use(commonmark)
      .use(listener)
      .use(emoji)
      .use(customNodes)
      .use(myPlugin)
  );
  return (
    <div className="App">
      <Menu ctx={ctx} />
      <ReactEditor editor={editor} />
    </div>
  );
}

const Menu = ({ ctx }) => {
  if (!ctx) return null;
  return (
    <div id="menu">
      <div
        onClick={() => {
          ctx.get(commandsCtx).call(CustomCommand);
        }}
      >
        run command a
      </div>
      <div
        onClick={() => {
          ctx.get(commandsCtx).call(customCommands.InsertHr);
        }}
      >
        run command b
      </div>
      <div onClick={() => {
        ctx.get(commandsCtx).call(milkdownCommands.InsertImage,
            "https://via.placeholder.com/450x300")
      }}>
        run command c
      </div>
    </div>
  );
};

[Saul-Mirone]

I'll improve the document about this. It's very simple under the hood. Generally speaking, the milkdown command wraps the prosemirror command. You can always use prosemirror command to create milkdown command. And once created. The milkdown command can be called just with a key (call) or key name(callByName). And milkdown will provide the state, dispatch and view for it.

[duhaime]

More documentation is always great!