@sybilion/uilib 1.3.33 → 1.3.36

package/src/tiptap/slash-mention/createSlashMentionExtension.ts

@@ -0,0 +1,217 @@
+import type { MutableRefObject } from 'react';
+
+import { type Editor, mergeAttributes } from '@tiptap/core';
+import Mention from '@tiptap/extension-mention';
+import type { EditorState } from '@tiptap/pm/state';
+import { ReactRenderer } from '@tiptap/react';
+import type { SuggestionProps } from '@tiptap/suggestion';
+
+import {
+  SlashSuggestionList,
+  type SlashSuggestionListHandle,
+} from './SlashSuggestionList';
+import { filterSlashItems } from './defaultChatSlashItems';
+import type {
+  CreateSlashMentionExtensionOptions,
+  SlashCommandItem,
+} from './types';
+
+export function slashMentionSuggestionRender(
+  uiRef: MutableRefObject<SlashSuggestionListHandle | null>,
+): {
+  onStart?: (
+    props: SuggestionProps<SlashCommandItem, SlashCommandItem>,
+  ) => void;
+  onUpdate?: (
+    props: SuggestionProps<SlashCommandItem, SlashCommandItem>,
+  ) => void;
+  onExit?: (props: SuggestionProps<SlashCommandItem, SlashCommandItem>) => void;
+  onKeyDown?: (p: {
+    view: unknown;
+    event: KeyboardEvent;
+    range: { from: number; to: number };
+  }) => boolean;
+} {
+  let popup: ReactRenderer<{
+    items: SlashCommandItem[];
+    command: (item: SlashCommandItem) => void;
+    listHandleRef: MutableRefObject<SlashSuggestionListHandle | null>;
+  }> | null = null;
+
+  const place = (
+    props: Pick<
+      SuggestionProps<SlashCommandItem, SlashCommandItem>,
+      'clientRect'
+    >,
+  ) => {
+    if (!popup?.element) return;
+    const rect = props.clientRect?.();
+    if (!rect) return;
+    const el = popup.element;
+    el.style.left = `${rect.left}px`;
+    el.style.top = `${rect.bottom + 4}px`;
+  };
+
+  return {
+    onStart: props => {
+      uiRef.current = null;
+      popup?.destroy?.();
+      popup = new ReactRenderer(SlashSuggestionList, {
+        editor: props.editor,
+        props: {
+          items: props.items,
+          command: props.command,
+          listHandleRef: uiRef,
+        },
+      });
+      popup.element.style.position = 'fixed';
+      popup.element.style.margin = '0';
+      popup.element.style.zIndex = '10002';
+      document.body.append(popup.element);
+      place(props);
+    },
+    onUpdate: props => {
+      if (!popup) return;
+      popup.updateProps({
+        items: props.items,
+        command: props.command,
+        listHandleRef: uiRef,
+      });
+      place(props);
+    },
+    onExit: () => {
+      popup?.destroy();
+      popup?.element?.remove?.();
+      popup = null;
+      uiRef.current = null;
+    },
+    onKeyDown: ({ event }) =>
+      uiRef.current?.onKeyboardEvent(event as KeyboardEvent) ?? false,
+  };
+}
+
+function insertDefaultMention(
+  editor: Editor,
+  range: { from: number; to: number },
+  props: SlashCommandItem,
+  slashChar: string,
+): void {
+  const nodeAfter = editor.view.state.selection.$to.nodeAfter;
+  const extend = nodeAfter?.text?.startsWith(' ') ? 1 : 0;
+  const adjusted = extend ? { ...range, to: range.to + extend } : range;
+
+  editor
+    .chain()
+    .focus()
+    .insertContentAt(adjusted, [
+      {
+        type: 'mention',
+        attrs: {
+          id: props.id,
+          label: props.label,
+          mentionSuggestionChar: slashChar,
+        },
+      },
+      { type: 'text', text: ' ' },
+    ])
+    .run();
+
+  queueMicrotask(() => {
+    editor.view.dom.ownerDocument?.defaultView
+      ?.getSelection?.()
+      ?.collapseToEnd();
+  });
+}
+
+function allowSlashTrigger({
+  state,
+  range,
+}: {
+  editor: Editor;
+  state: EditorState;
+  range: { from: number; to: number };
+}) {
+  const type = state.schema.nodes['mention'];
+  const $from = state.doc.resolve(range.from);
+  if (!type || !$from.parent.type.contentMatch.matchType(type)) return false;
+  if ($from.parentOffset === 0) return true;
+  const before = state.doc.textBetween(range.from - 1, range.from);
+  return /\s/.test(before);
+}
+
+export type CreateSlashMentionExtensionConfiguredOptions =
+  CreateSlashMentionExtensionOptions & {
+    onSuggestionUiActiveChange?: (active: boolean) => void;
+  };
+
+export function createSlashMentionExtension({
+  items: resolvedItems,
+  slashChar = '/',
+  pluginKey,
+  onItemCommand,
+  onSuggestionUiActiveChange,
+}: CreateSlashMentionExtensionConfiguredOptions) {
+  const uiRef: MutableRefObject<SlashSuggestionListHandle | null> = {
+    current: null,
+  };
+
+  return Mention.configure({
+    renderText({ node }) {
+      return `/${node.attrs.id as string}`;
+    },
+    renderHTML({ options, node, suggestion }) {
+      const suggestionChar = suggestion?.char ?? slashChar;
+      const id =
+        typeof node.attrs.id === 'string'
+          ? node.attrs.id
+          : String(node.attrs.id ?? '');
+      return [
+        'span',
+        mergeAttributes(
+          {
+            'data-type': 'mention',
+            'data-slash-command': id,
+            class: 'slash-mention',
+          },
+          options.HTMLAttributes,
+        ),
+        `${suggestionChar}${id}`,
+      ];
+    },
+    suggestion: {
+      char: slashChar,
+      pluginKey,
+      allowedPrefixes: [' ', '\n', '\t', '\r'],
+      allow: props => allowSlashTrigger(props),
+      items: ({ query }) =>
+        Promise.resolve(filterSlashItems(resolvedItems, query)),
+      command: ({ editor, range, props }) => {
+        const item = props as SlashCommandItem;
+        if (onItemCommand?.({ editor, range, item }) === true) {
+          queueMicrotask(() => {
+            editor.view.dom.ownerDocument?.defaultView
+              ?.getSelection?.()
+              ?.collapseToEnd();
+          });
+          return null;
+        }
+        insertDefaultMention(editor, range, item, slashChar);
+        return null;
+      },
+      render: () => {
+        const menu = slashMentionSuggestionRender(uiRef);
+        return {
+          ...menu,
+          onStart: props => {
+            onSuggestionUiActiveChange?.(true);
+            menu.onStart?.(props);
+          },
+          onExit: props => {
+            menu.onExit?.(props);
+            onSuggestionUiActiveChange?.(false);
+          },
+        };
+      },
+    },
+  });
+}

package/src/tiptap/slash-mention/defaultChatSlashItems.ts

@@ -0,0 +1,18 @@
+import type { SlashCommandItem } from './types';
+
+/** Empty default: pass `slashCommandItems` from the app to enable `/` palette. */
+export const DEFAULT_CHAT_SLASH_ITEMS: SlashCommandItem[] = [];
+
+export function filterSlashItems(
+  items: SlashCommandItem[],
+  query: string,
+): SlashCommandItem[] {
+  const q = query.trim().toLowerCase();
+  if (!q) return items;
+  return items.filter(
+    item =>
+      item.id.toLowerCase().includes(q) ||
+      item.label.toLowerCase().includes(q) ||
+      (item.description?.toLowerCase().includes(q) ?? false),
+  );
+}

package/src/tiptap/slash-mention/index.ts

@@ -0,0 +1,16 @@
+export type {
+  SlashCommandItem,
+  SlashOnItemCommand,
+  SlashItemCommandContext,
+  CreateSlashMentionExtensionOptions,
+} from './types';
+export {
+  DEFAULT_CHAT_SLASH_ITEMS,
+  filterSlashItems,
+} from './defaultChatSlashItems';
+export {
+  createSlashMentionExtension,
+  slashMentionSuggestionRender,
+} from './createSlashMentionExtension';
+export type { CreateSlashMentionExtensionConfiguredOptions } from './createSlashMentionExtension';
+export type { SlashSuggestionListHandle } from './SlashSuggestionList';

package/src/tiptap/slash-mention/types.ts

@@ -0,0 +1,29 @@
+import type { Editor, Range } from '@tiptap/core';
+
+export type SlashCommandItem = {
+  id: string;
+  label: string;
+  description?: string;
+};
+
+export type SlashItemCommandContext = {
+  editor: Editor;
+  range: Range;
+  item: SlashCommandItem;
+};
+
+/**
+ * If provided, run before default mention insertion. Return true to skip inserting a mention node.
+ */
+export type SlashOnItemCommand = (ctx: SlashItemCommandContext) => boolean;
+
+export type CreateSlashMentionExtensionOptions = {
+  /** Items shown in the slash menu (filtered by query after `/`). */
+  items: SlashCommandItem[];
+  /** Trigger character; use `/` for slash commands. */
+  slashChar?: string;
+  /** Optional custom plugin key when multiple slash editors exist. */
+  pluginKey?: import('@tiptap/pm/state').PluginKey;
+  /** Custom handler (e.g. insert a block node instead of a mention). */
+  onItemCommand?: SlashOnItemCommand;
+};