@medway-ui/notes-core 0.1.0

package/src/schema/slashCommand.ts

@@ -0,0 +1,181 @@
+import { Extension, type Editor, type Range } from '@tiptap/core';
+import { PluginKey } from '@tiptap/pm/state';
+import Suggestion, {
+  exitSuggestion,
+  type SuggestionProps,
+} from '@tiptap/suggestion';
+
+import type {
+  EditorCaretRect,
+  SlashCommandId,
+  SlashMenuState,
+} from '../editor/vocabulary.js';
+import { filterSlashCommands } from '../editor/slashCommands.js';
+
+const SlashPluginKey = new PluginKey('medwaySlashCommand');
+
+type SlashProps = SuggestionProps<SlashCommandId, SlashCommandId>;
+
+const EMPTY: SlashMenuState = {
+  active: false,
+  query: '',
+  commandIds: [],
+  caret: null,
+};
+
+const toCaretRect = (props: SlashProps): EditorCaretRect | null => {
+  const rect =
+    props.clientRect?.() ?? props.decorationNode?.getBoundingClientRect();
+  if (!rect) return null;
+
+  return { x: rect.left, y: rect.top, width: rect.width, height: rect.height };
+};
+
+const applyCommand = (editor: Editor, range: Range, id: SlashCommandId) => {
+  // Deleting the typed range and applying the block happen in one chain so a
+  // single undo takes the student back to the text they typed.
+  const chain = editor.chain().focus().deleteRange(range);
+
+  switch (id) {
+    case 'paragraph':
+      chain.setParagraph().run();
+      return;
+    case 'heading1':
+      chain.setNode('heading', { level: 1 }).run();
+      return;
+    case 'heading2':
+      chain.setNode('heading', { level: 2 }).run();
+      return;
+    case 'heading3':
+      chain.setNode('heading', { level: 3 }).run();
+      return;
+    case 'bulletList':
+      chain.toggleBulletList().run();
+      return;
+    case 'orderedList':
+      chain.toggleOrderedList().run();
+      return;
+    case 'taskList':
+      chain.toggleTaskList().run();
+      return;
+    case 'blockquote':
+      chain.setBlockquote().run();
+      return;
+    case 'codeBlock':
+      chain.setCodeBlock().run();
+      return;
+    case 'horizontalRule':
+      chain.setHorizontalRule().run();
+      return;
+    case 'image':
+      // Only clears the typed `/query`: picking and uploading a file is host
+      // UI (`NoteEditor`'s `onImageUpload`), which inserts the node itself.
+      chain.run();
+      return;
+    default: {
+      // Exhaustiveness check: a new `SlashCommandId` without a case above stops
+      // this file compiling. Still a runtime no-op rather than a throw — `id`
+      // crosses the WebView bridge, so an out-of-contract value should degrade
+      // gracefully instead of crashing the editor.
+      const _exhaustive: never = id;
+      void _exhaustive;
+      chain.run();
+    }
+  }
+};
+
+export type SlashCommandController = {
+  /** Add this to the extension list — see `buildExtensions`. */
+  extension: Extension;
+  /** Runs the command the host picked, if the menu is still open. */
+  run: (commandId: SlashCommandId) => boolean;
+  dismiss: (editor: Editor) => void;
+  /** Re-publishes the caret position, e.g. after the document scrolls. */
+  refreshCaret: () => void;
+};
+
+/**
+ * The `/` menu's detection half: owns only *when* `/` is active, *what* was
+ * typed, *where* the caret is, and the range to replace. The host draws the
+ * menu and answers with `run`, which removes the typed `/query` in the same
+ * transaction as the command it applies.
+ */
+export const createSlashCommand = (
+  onChange: (state: SlashMenuState) => void
+): SlashCommandController => {
+  let active: SlashProps | null = null;
+
+  const publish = (props: SlashProps | null) => {
+    if (!props) {
+      onChange(EMPTY);
+      return;
+    }
+
+    onChange({
+      active: true,
+      query: props.query,
+      commandIds: props.items,
+      caret: toCaretRect(props),
+    });
+  };
+
+  const extension = Extension.create({
+    name: 'medwaySlashCommand',
+
+    addProseMirrorPlugins() {
+      return [
+        Suggestion<SlashCommandId, SlashCommandId>({
+          editor: this.editor,
+          pluginKey: SlashPluginKey,
+          char: '/',
+          decorationClass: 'medway-slash',
+          // A `/` inside a code block is code, not a command.
+          allow: ({ state, range }) =>
+            state.doc.resolve(range.from).parent.type.name !== 'codeBlock',
+          items: ({ query }) => filterSlashCommands(query),
+          command: ({ editor, range, props }) =>
+            applyCommand(editor, range, props),
+          render: () => ({
+            onStart: (props) => {
+              active = props;
+              publish(props);
+            },
+            onUpdate: (props) => {
+              active = props;
+              publish(props);
+            },
+            onExit: () => {
+              active = null;
+              publish(null);
+            },
+            onKeyDown: ({ event }) => {
+              if (event.key !== 'Escape') return false;
+
+              active = null;
+              publish(null);
+              return true;
+            },
+          }),
+        }),
+      ];
+    },
+  });
+
+  return {
+    extension,
+    run: (commandId) => {
+      if (!active || !active.items.includes(commandId)) return false;
+
+      active.command(commandId);
+      return true;
+    },
+    dismiss: (editor) => {
+      if (!active) return;
+
+      exitSuggestion(editor.view, SlashPluginKey);
+    },
+    refreshCaret: () => {
+      if (active) publish(active);
+    },
+  };
+};