@sybilion/uilib 1.3.36 → 1.3.38

package/src/docs/pages/ChatSlashCommandsPage.tsx

@@ -8,6 +8,7 @@ import {
   type SlashCommandItem,
 } from '#uilib/components/ui/Chat';
 import { PageContentSection } from '#uilib/components/ui/Page';
+import type { SlashItemCommandContext } from '#uilib/tiptap/slash-mention/types';
 import { ScrollRef } from '@homecode/ui';
 
 import { AppPageHeader } from '../components/AppPageHeader/AppPageHeader';
@@ -15,18 +16,23 @@ import { DocsHeaderActions } from '../docsHeaderActions';
 
 const NO_QUICK_REPLY_KEYS: ReadonlySet<string> = new Set();
 
+const DOCS_SAMPLE_COMMAND_ID = 'sample-command';
+
 /** Sample items so the docs demo still shows a `/` palette (`DEFAULT_CHAT_SLASH_ITEMS` is empty). */
 const DOCS_SAMPLE_SLASH_ITEMS: SlashCommandItem[] = [
   {
-    id: 'sample-command',
-    label: 'sample-command',
+    id: DOCS_SAMPLE_COMMAND_ID,
+    label: DOCS_SAMPLE_COMMAND_ID,
     description:
-      'Demo only — define `slashCommandItems` in your app to list real commands.',
+      'Demo handler — clears composer and runs `onSlashItemCommand` (no mention insert).',
   },
 ];
 
+const SAMPLE_COMMAND_REPLY_TEXT =
+  'Sample command ran via `onSlashItemCommand` — composer cleared, no mention inserted.';
+
 const ASSISTANT_REPLY_TEXT =
-  'Demo reply. Picked slash text is `/sample-command` via TipTap Mention (plain-text round-trip with renderText).';
+  'Demo reply for a normal message. Slash picks with a custom handler skip mention insert.';
 
 function makeMessage(role: MessageRole, text: string): Message {
   return {
@@ -56,11 +62,34 @@ export default function ChatSlashCommandsPage() {
     messages.length > 0 &&
     messages[messages.length - 1]?.role === MessageRole.USER;
 
+  const runSampleCommand = useCallback(() => {
+    setMessages(prev => [
+      ...prev,
+      makeMessage(MessageRole.ASSISTANT, SAMPLE_COMMAND_REPLY_TEXT),
+    ]);
+  }, []);
+
+  const onSlashItemCommand = useCallback(
+    ({ item }: SlashItemCommandContext) => {
+      if (item.id !== DOCS_SAMPLE_COMMAND_ID) {
+        return false;
+      }
+      queueMicrotask(() => runSampleCommand());
+      return true;
+    },
+    [runSampleCommand],
+  );
+
   const onSubmit = useCallback(
     (raw: string) => {
       const text = raw.trim();
       if (!text || isLoading) return;
 
+      if (text === `/${DOCS_SAMPLE_COMMAND_ID}`) {
+        runSampleCommand();
+        return;
+      }
+
       setMessages(prev => [...prev, makeMessage(MessageRole.USER, text)]);
       setIsLoading(true);
 
@@ -76,7 +105,7 @@ export default function ChatSlashCommandsPage() {
         setIsLoading(false);
       }, 900);
     },
-    [isLoading],
+    [isLoading, runSampleCommand],
   );
 
   return (
@@ -84,8 +113,10 @@ export default function ChatSlashCommandsPage() {
       <AppPageHeader
         breadcrumbs={[{ label: 'Chat' }, { label: 'Chat slash commands' }]}
         title="Chat slash commands"
-        subheader={`Slash palette uses TipTap Mention with "/" as the trigger. Library default item list is empty — pass slashCommandItems from the app (this page uses a sample item for the demo).`}
-        actions={<DocsHeaderActions />}
+        subheader={`Slash palette uses TipTap Mention with "/" as the trigger. Pass slashCommandItems from the app; optional onSlashItemCommand can clear the composer and run an action instead of inserting a mention.`}
+        actions={
+          <DocsHeaderActions slashCommandItems={DOCS_SAMPLE_SLASH_ITEMS} />
+        }
       />
       <PageContentSection>
         <p style={{ marginBottom: 16, fontSize: 14, lineHeight: 1.5 }}>
@@ -95,7 +126,9 @@ export default function ChatSlashCommandsPage() {
           </Link>{' '}
           shell below: scrolling history, empty state, disclaimer, composer.
           Type <kbd className="font-mono">/</kbd> at line start or after a
-          space; pick with arrows + Enter or click, then send.
+          space; pick <kbd className="font-mono">sample-command</kbd> to run the
+          custom handler, or send{' '}
+          <kbd className="font-mono">/sample-command</kbd> with Enter.
         </p>
         <ChatChrome
           showResizeHandle={false}
@@ -109,13 +142,8 @@ export default function ChatSlashCommandsPage() {
           isLoading={isLoading}
           scriptContinueLabel={undefined}
           onScriptContinue={undefined}
-          showBranchActionsRow={false}
           showSyntheticBranchButtons={false}
           unusedBranchKeys={[]}
-          isScriptComplete={false}
-          onGenerateDashboard={undefined}
-          generatingDashboard={false}
-          onGenerateDashboardClick={() => {}}
           showInlinePresets={false}
           isLastMessageFromUser={isLastMessageFromUser}
           scrollRef={scrollRef}
@@ -123,11 +151,12 @@ export default function ChatSlashCommandsPage() {
           onPromptSubmit={onSubmit}
           onChatDeleted={() => {}}
           slashCommandItems={DOCS_SAMPLE_SLASH_ITEMS}
+          onSlashItemCommand={onSlashItemCommand}
           promptPlaceholder='Ask something or type "/" for demo commands…'
           emptyState={{
             title: 'Try a slash command',
             description:
-              'This demo mounts one sample slash item. Production: pass slashCommandItems to ChatChrome so `/` opens your palette.',
+              'Pick sample-command from the palette or send /sample-command — onSlashItemCommand clears the composer and runs the demo action.',
             additionalContent: (
               <p>Optional empty-state slot via additionalContent.</p>
             ),

package/src/docs/pages/ChatUserCsvAttachmentPage.tsx

@@ -148,13 +148,8 @@ export default function ChatUserCsvAttachmentPage() {
           isLoading={isLoading}
           scriptContinueLabel={undefined}
           onScriptContinue={undefined}
-          showBranchActionsRow={false}
           showSyntheticBranchButtons={false}
           unusedBranchKeys={[]}
-          isScriptComplete={false}
-          onGenerateDashboard={undefined}
-          generatingDashboard={false}
-          onGenerateDashboardClick={() => {}}
           showInlinePresets={false}
           isLastMessageFromUser={isLastMessageFromUser}
           scrollRef={scrollRef}

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

@@ -14,10 +14,42 @@ import { filterSlashItems } from './defaultChatSlashItems';
 import type {
   CreateSlashMentionExtensionOptions,
   SlashCommandItem,
+  SlashSuggestionPlacement,
 } from './types';
 
+const SUGGESTION_GAP_PX = 4;
+
+function placeSlashSuggestionPopup(
+  popupElement: HTMLElement,
+  clientRect: DOMRect | null | undefined,
+  placement: SlashSuggestionPlacement,
+): void {
+  if (!clientRect) return;
+
+  const el = popupElement;
+  const popupHeight = el.getBoundingClientRect().height;
+  const spaceBelow = window.innerHeight - clientRect.bottom - SUGGESTION_GAP_PX;
+  const spaceAbove = clientRect.top - SUGGESTION_GAP_PX;
+
+  let showAbove = placement === 'above';
+  if (placement === 'auto') {
+    showAbove = spaceBelow < popupHeight && spaceAbove >= spaceBelow;
+  }
+
+  const top = showAbove
+    ? Math.max(
+        SUGGESTION_GAP_PX,
+        clientRect.top - popupHeight - SUGGESTION_GAP_PX,
+      )
+    : clientRect.bottom + SUGGESTION_GAP_PX;
+
+  el.style.left = `${clientRect.left}px`;
+  el.style.top = `${top}px`;
+}
+
 export function slashMentionSuggestionRender(
   uiRef: MutableRefObject<SlashSuggestionListHandle | null>,
+  placement: SlashSuggestionPlacement = 'below',
 ): {
   onStart?: (
     props: SuggestionProps<SlashCommandItem, SlashCommandItem>,
@@ -45,11 +77,11 @@ export function slashMentionSuggestionRender(
     >,
   ) => {
     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`;
+    placeSlashSuggestionPopup(
+      popup.element,
+      props.clientRect?.() ?? null,
+      placement,
+    );
   };
 
   return {
@@ -69,6 +101,7 @@ export function slashMentionSuggestionRender(
       popup.element.style.zIndex = '10002';
       document.body.append(popup.element);
       place(props);
+      requestAnimationFrame(() => place(props));
     },
     onUpdate: props => {
       if (!popup) return;
@@ -78,6 +111,7 @@ export function slashMentionSuggestionRender(
         listHandleRef: uiRef,
       });
       place(props);
+      requestAnimationFrame(() => place(props));
     },
     onExit: () => {
       popup?.destroy();
@@ -90,6 +124,28 @@ export function slashMentionSuggestionRender(
   };
 }
 
+function clearSlashTriggerEditor(
+  editor: Editor,
+  range: { from: number; to: number },
+): void {
+  if (editor.isDestroyed) return;
+  try {
+    editor.chain().focus().deleteRange(range).clearContent().run();
+  } catch {
+    // Editor view may be tearing down during suggestion exit.
+  }
+}
+
+function collapseEditorSelectionEnd(editor: Editor): void {
+  if (editor.isDestroyed) return;
+  try {
+    editor.view?.dom?.ownerDocument?.defaultView
+      ?.getSelection?.()
+      ?.collapseToEnd();
+  } catch {
+    // view.dom throws when editor is not mounted
+  }
+}
 function insertDefaultMention(
   editor: Editor,
   range: { from: number; to: number },
@@ -149,6 +205,7 @@ export function createSlashMentionExtension({
   slashChar = '/',
   pluginKey,
   onItemCommand,
+  suggestionPlacement = 'below',
   onSuggestionUiActiveChange,
 }: CreateSlashMentionExtensionConfiguredOptions) {
   const uiRef: MutableRefObject<SlashSuggestionListHandle | null> = {
@@ -188,18 +245,15 @@ export function createSlashMentionExtension({
       command: ({ editor, range, props }) => {
         const item = props as SlashCommandItem;
         if (onItemCommand?.({ editor, range, item }) === true) {
-          queueMicrotask(() => {
-            editor.view.dom.ownerDocument?.defaultView
-              ?.getSelection?.()
-              ?.collapseToEnd();
-          });
+          clearSlashTriggerEditor(editor, range);
+          queueMicrotask(() => collapseEditorSelectionEnd(editor));
           return null;
         }
         insertDefaultMention(editor, range, item, slashChar);
         return null;
       },
       render: () => {
-        const menu = slashMentionSuggestionRender(uiRef);
+        const menu = slashMentionSuggestionRender(uiRef, suggestionPlacement);
         return {
           ...menu,
           onStart: props => {

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

@@ -2,6 +2,7 @@ export type {
   SlashCommandItem,
   SlashOnItemCommand,
   SlashItemCommandContext,
+  SlashSuggestionPlacement,
   CreateSlashMentionExtensionOptions,
 } from './types';
 export {

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

@@ -13,10 +13,14 @@ export type SlashItemCommandContext = {
 };
 
 /**
- * If provided, run before default mention insertion. Return true to skip inserting a mention node.
+ * If provided, run when a slash item is picked. Return true to skip mention insert
+ * (extension clears the trigger text from the composer).
  */
 export type SlashOnItemCommand = (ctx: SlashItemCommandContext) => boolean;
 
+/** Where the slash palette opens relative to the caret. */
+export type SlashSuggestionPlacement = 'below' | 'above' | 'auto';
+
 export type CreateSlashMentionExtensionOptions = {
   /** Items shown in the slash menu (filtered by query after `/`). */
   items: SlashCommandItem[];
@@ -26,4 +30,9 @@ export type CreateSlashMentionExtensionOptions = {
   pluginKey?: import('@tiptap/pm/state').PluginKey;
   /** Custom handler (e.g. insert a block node instead of a mention). */
   onItemCommand?: SlashOnItemCommand;
+  /**
+   * Palette position vs caret. Default `below`.
+   * Use `above` for bottom-anchored composers (chat prompt); `auto` flips by viewport space.
+   */
+  suggestionPlacement?: SlashSuggestionPlacement;
 };