@sybilion/uilib 1.3.32 → 1.3.35

package/src/docs/registry.ts

@@ -109,6 +109,12 @@ export const DOC_REGISTRY: DocEntry[] = [
     section: 'Chat',
     load: () => import('./pages/ChatPage'),
   },
+  {
+    slug: 'chat-slash-commands',
+    title: 'Chat slash commands',
+    section: 'Chat',
+    load: () => import('./pages/ChatSlashCommandsPage'),
+  },
   {
     slug: 'chat-user-csv-attachment',
     title: 'Chat user CSV attachment',

package/src/index.ts

@@ -11,6 +11,7 @@ export { DEFAULT_THEME_ACTIVE_COLOR } from './docs/lib/theme';
 export * from './sybilion-auth';
 export * from './types/sybilionDatasetSnapshots';
 export * from './contexts/chat-context';
+export * from './tiptap/slash-mention';
 export * from './types/chat-api.types';
 export * from './components/ui/AnalysesSelector';
 export * from './components/ui/AnalysisLineIcon';

package/src/tiptap/slash-mention/SlashSuggestionList.styl

@@ -0,0 +1,48 @@
+@import 'lib/theme.styl';
+
+.root
+  display flex
+  flex-direction column
+  min-width 220px
+  max-width min(340px, 90vw)
+  max-height min(260px, 40vh)
+  overflow-y auto
+  padding var(--p-1)
+  margin 0
+  list-style none
+  background var(--popover, var(--card))
+  color var(--foreground)
+  border 1px solid var(--border)
+  border-radius var(--radius-lg, 8px)
+  box-shadow 0 8px 24px rgba(0, 0, 0, 0.12)
+  font-size var(--text-sm)
+
+  :global(.dark) &
+    box-shadow 0 8px 24px rgba(0, 0, 0, 0.5)
+
+.item
+  display flex
+  flex-direction column
+  align-items flex-start
+  width 100%
+  padding var(--p-1) var(--p-2)
+  margin 0
+  border none
+  border-radius var(--radius-md, 6px)
+  background transparent
+  color inherit
+  text-align left
+  cursor pointer
+
+  &:hover
+    background var(--muted)
+
+.itemHighlighted
+  background var(--muted)
+
+.itemLabel
+  font-weight 600
+
+.itemDesc
+  font-size var(--text-xs)
+  color var(--muted-foreground)

package/src/tiptap/slash-mention/SlashSuggestionList.styl.d.ts

@@ -0,0 +1,11 @@
+// This file is automatically generated.
+// Please do not change this file!
+interface CssExports {
+  'item': string;
+  'itemDesc': string;
+  'itemHighlighted': string;
+  'itemLabel': string;
+  'root': string;
+}
+export const cssExports: CssExports;
+export default cssExports;

package/src/tiptap/slash-mention/SlashSuggestionList.tsx

@@ -0,0 +1,109 @@
+import cn from 'classnames';
+import type { RefObject } from 'react';
+import { useCallback, useEffect, useImperativeHandle, useState } from 'react';
+
+import S from './SlashSuggestionList.styl';
+import type { SlashCommandItem } from './types';
+
+export type SlashSuggestionListHandle = {
+  onKeyboardEvent: (event: KeyboardEvent) => boolean;
+};
+
+type SlashSuggestionListInnerProps = {
+  items: SlashCommandItem[];
+  command: (item: SlashCommandItem) => void;
+  listHandleRef: RefObject<SlashSuggestionListHandle | null>;
+};
+
+function SlashSuggestionListInner({
+  items,
+  command,
+  listHandleRef,
+}: SlashSuggestionListInnerProps) {
+  const [selected, setSelected] = useState(0);
+
+  useEffect(() => {
+    setSelected(s => Math.min(s, Math.max(items.length - 1, 0)));
+  }, [items.length]);
+
+  const safeSel = Math.min(selected, Math.max(items.length - 1, 0));
+
+  const onPick = useCallback(
+    (index: number) => {
+      const item = items[index];
+      if (!item) return;
+      command(item);
+    },
+    [command, items],
+  );
+
+  const onKeyboardEvent = useCallback(
+    (event: KeyboardEvent): boolean => {
+      if (items.length === 0) return false;
+      if (event.key === 'ArrowDown') {
+        event.preventDefault();
+        setSelected(s => Math.min(s + 1, items.length - 1));
+        return true;
+      }
+      if (event.key === 'ArrowUp') {
+        event.preventDefault();
+        setSelected(s => Math.max(s - 1, 0));
+        return true;
+      }
+      if (event.key === 'Enter') {
+        event.preventDefault();
+        const max = Math.max(items.length - 1, 0);
+        const idx = Math.min(selected, max);
+        const item = items[idx];
+        if (item) command(item);
+        return true;
+      }
+      return false;
+    },
+    [command, items, selected],
+  );
+
+  useImperativeHandle(listHandleRef, () => ({ onKeyboardEvent }), [
+    onKeyboardEvent,
+  ]);
+
+  return (
+    <div className={S.root} role="listbox" aria-label="Slash commands">
+      {items.map((item, idx) => (
+        <button
+          key={`${item.id}-${idx}`}
+          type="button"
+          role="option"
+          aria-selected={idx === safeSel}
+          className={cn(S.item, idx === safeSel && S.itemHighlighted)}
+          onMouseDown={e => e.preventDefault()}
+          onMouseEnter={() => setSelected(idx)}
+          onClick={() => onPick(idx)}
+        >
+          <span className={S.itemLabel}>/{item.label}</span>
+          {item.description ? (
+            <span className={S.itemDesc}>{item.description}</span>
+          ) : null}
+        </button>
+      ))}
+    </div>
+  );
+}
+
+/** Props forwarded from Tiptap suggestion renderer + our wiring. */
+export type SlashSuggestionListProps = {
+  items: SlashCommandItem[];
+  command: (item: SlashCommandItem) => void;
+  listHandleRef: RefObject<SlashSuggestionListHandle | null>;
+};
+
+export function SlashSuggestionList(props: SlashSuggestionListProps) {
+  if (props.items.length === 0) return null;
+  return (
+    <SlashSuggestionListInner
+      items={props.items}
+      command={props.command}
+      listHandleRef={props.listHandleRef}
+    />
+  );
+}

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;
+};