@sybilion/uilib 1.3.36 → 1.3.37

package/dist/esm/components/ui/Chat/ChatPrompt/useChatPromptEditor.js

@@ -48,6 +48,7 @@ function useChatPromptEditor({ disabled, placeholder, slashCommandItems, prefill
         if (slashItemsStable.length > 0) {
             exts.push(createSlashMentionExtension({
                 items: slashItemsStable,
+                suggestionPlacement: 'above',
                 onSuggestionUiActiveChange: suggestionActiveUpdater,
             }));
         }

package/dist/esm/components/ui/Chat/ChatSheet/ChatSheet.js

@@ -4,7 +4,7 @@ import { Button } from '../../Button/Button.js';
 import { ChatChrome } from '../ChatChrome/ChatChrome.js';
 import { useChatPanelChromeModel } from './useChatPanelChromeModel.js';
 
-function ChatSheet({ triggerLabel = 'Open Chat', triggerAriaLabel, actionsRef, renderTrigger, presets, scopeId, onMessage, onScriptComplete, onGenerateDashboard, renderMessageChart, emptyState, allowedAttachments, allowPdfAttachments, onAttachmentsDropped, inline = false, }) {
+function ChatSheet({ triggerLabel = 'Open Chat', triggerAriaLabel, actionsRef, renderTrigger, presets, scopeId, onMessage, onScriptComplete, onGenerateDashboard, renderMessageChart, emptyState, allowedAttachments, allowPdfAttachments, onAttachmentsDropped, slashCommandItems, inline = false, }) {
     const model = useChatPanelChromeModel({
         embedAsPage: inline,
         presets,
@@ -17,6 +17,7 @@ function ChatSheet({ triggerLabel = 'Open Chat', triggerAriaLabel, actionsRef, r
         allowedAttachments,
         allowPdfAttachments,
         onAttachmentsDropped,
+        slashCommandItems,
     });
     if (actionsRef) {
         actionsRef.current = {

package/dist/esm/components/ui/Chat/ChatSheet/useChatPanelChromeModel.js

@@ -22,7 +22,7 @@ const CHAT_NAV_COLLAPSE_BREAKPOINT_PX = 1400;
 const CHAT_QUERY_PARAM = 'chat';
 const CHAT_OPEN_VALUE = 'open';
 const PROMPT_QUERY_PARAM = 'prompt';
-function useChatPanelChromeModel({ embedAsPage, presets, scopeId, onMessage, onScriptComplete, onGenerateDashboard, renderMessageChart, emptyState, allowedAttachments, allowPdfAttachments, onAttachmentsDropped, }) {
+function useChatPanelChromeModel({ embedAsPage, presets, scopeId, onMessage, onScriptComplete, onGenerateDashboard, renderMessageChart, emptyState, allowedAttachments, allowPdfAttachments, onAttachmentsDropped, slashCommandItems, }) {
     const effectiveScopeId = scopeId ?? NO_SCOPE_FALLBACK;
     const isMobile = useIsMobile();
     const { chatPanelContainer, isOpen: sidebarNavOpen, setOpen: setSidebarNavOpen, chatWidthPx, setChatWidthPx, getShellWidth, setChatPanelOpen, } = useSidebar();
@@ -786,6 +786,7 @@ function useChatPanelChromeModel({ embedAsPage, presets, scopeId, onMessage, onS
         allowedAttachments,
         allowPdfAttachments,
         onAttachmentsDropped,
+        slashCommandItems,
     };
     const toggleOpen = () => onOpenChange(!isOpen);
     return {

package/dist/esm/tiptap/slash-mention/createSlashMentionExtension.js

@@ -4,17 +4,30 @@ import { ReactRenderer } from '@tiptap/react';
 import { SlashSuggestionList } from './SlashSuggestionList.js';
 import { filterSlashItems } from './defaultChatSlashItems.js';
 
-function slashMentionSuggestionRender(uiRef) {
+const SUGGESTION_GAP_PX = 4;
+function placeSlashSuggestionPopup(popupElement, clientRect, placement) {
+    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`;
+}
+function slashMentionSuggestionRender(uiRef, placement = 'below') {
     let popup = null;
     const place = (props) => {
         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 {
         onStart: props => {
@@ -33,6 +46,7 @@ function slashMentionSuggestionRender(uiRef) {
             popup.element.style.zIndex = '10002';
             document.body.append(popup.element);
             place(props);
+            requestAnimationFrame(() => place(props));
         },
         onUpdate: props => {
             if (!popup)
@@ -43,6 +57,7 @@ function slashMentionSuggestionRender(uiRef) {
                 listHandleRef: uiRef,
             });
             place(props);
+            requestAnimationFrame(() => place(props));
         },
         onExit: () => {
             popup?.destroy();
@@ -88,7 +103,7 @@ function allowSlashTrigger({ state, range, }) {
     const before = state.doc.textBetween(range.from - 1, range.from);
     return /\s/.test(before);
 }
-function createSlashMentionExtension({ items: resolvedItems, slashChar = '/', pluginKey, onItemCommand, onSuggestionUiActiveChange, }) {
+function createSlashMentionExtension({ items: resolvedItems, slashChar = '/', pluginKey, onItemCommand, suggestionPlacement = 'below', onSuggestionUiActiveChange, }) {
     const uiRef = {
         current: null,
     };
@@ -131,7 +146,7 @@ function createSlashMentionExtension({ items: resolvedItems, slashChar = '/', pl
                 return null;
             },
             render: () => {
-                const menu = slashMentionSuggestionRender(uiRef);
+                const menu = slashMentionSuggestionRender(uiRef, suggestionPlacement);
                 return {
                     ...menu,
                     onStart: props => {

package/dist/esm/types/src/components/ui/Chat/ChatSheet/ChatSheet.d.ts

@@ -19,4 +19,4 @@ export interface ChatSheetProps extends Omit<UseChatPanelChromeModelInput, 'embe
      */
     inline?: boolean;
 }
-export declare function ChatSheet({ triggerLabel, triggerAriaLabel, actionsRef, renderTrigger, presets, scopeId, onMessage, onScriptComplete, onGenerateDashboard, renderMessageChart, emptyState, allowedAttachments, allowPdfAttachments, onAttachmentsDropped, inline, }: ChatSheetProps): import("react/jsx-runtime").JSX.Element;
+export declare function ChatSheet({ triggerLabel, triggerAriaLabel, actionsRef, renderTrigger, presets, scopeId, onMessage, onScriptComplete, onGenerateDashboard, renderMessageChart, emptyState, allowedAttachments, allowPdfAttachments, onAttachmentsDropped, slashCommandItems, inline, }: ChatSheetProps): import("react/jsx-runtime").JSX.Element;

package/dist/esm/types/src/components/ui/Chat/ChatSheet/useChatPanelChromeModel.d.ts

@@ -1,4 +1,5 @@
 import { ChatPreset, type ScriptCompletePayload } from '#uilib/components/ui/Chat/Chat.types';
+import type { SlashCommandItem } from '#uilib/tiptap/slash-mention/types';
 import type { ChatChromeProps } from '../ChatChrome';
 import type { ChatAttachmentDropItem } from '../ChatChrome/ChatChrome.types';
 import type { ChatEmptyStateConfig } from '../ChatEmptyState/ChatEmptyState.types';
@@ -22,6 +23,8 @@ export type UseChatPanelChromeModelInput = {
     /** When true, PDF drops are accepted and parsed to plain text. */
     allowPdfAttachments?: boolean;
     onAttachmentsDropped?: (items: ChatAttachmentDropItem[]) => void | Promise<void>;
+    /** Slash menu (`/`) in the composer; omit or pass empty to disable. */
+    slashCommandItems?: SlashCommandItem[];
 };
 export type UseChatPanelChromeModelResult = {
     chromeProps: ChatChromeProps;
@@ -31,4 +34,4 @@ export type UseChatPanelChromeModelResult = {
     newChat: () => void;
     chatPanelContainer: HTMLElement | null;
 };
-export declare function useChatPanelChromeModel({ embedAsPage, presets, scopeId, onMessage, onScriptComplete, onGenerateDashboard, renderMessageChart, emptyState, allowedAttachments, allowPdfAttachments, onAttachmentsDropped, }: UseChatPanelChromeModelInput): UseChatPanelChromeModelResult;
+export declare function useChatPanelChromeModel({ embedAsPage, presets, scopeId, onMessage, onScriptComplete, onGenerateDashboard, renderMessageChart, emptyState, allowedAttachments, allowPdfAttachments, onAttachmentsDropped, slashCommandItems, }: UseChatPanelChromeModelInput): UseChatPanelChromeModelResult;

package/dist/esm/types/src/docs/docsHeaderActions.d.ts

@@ -1 +1,2 @@
-export declare function DocsHeaderActions(): import("react/jsx-runtime").JSX.Element;
+import { ChatSheetProps } from '#uilib/components/ui/Chat';
+export declare function DocsHeaderActions(props: ChatSheetProps): import("react/jsx-runtime").JSX.Element;

package/dist/esm/types/src/tiptap/slash-mention/createSlashMentionExtension.d.ts

@@ -1,8 +1,8 @@
 import type { MutableRefObject } from 'react';
 import type { SuggestionProps } from '@tiptap/suggestion';
 import { type SlashSuggestionListHandle } from './SlashSuggestionList';
-import type { CreateSlashMentionExtensionOptions, SlashCommandItem } from './types';
-export declare function slashMentionSuggestionRender(uiRef: MutableRefObject<SlashSuggestionListHandle | null>): {
+import type { CreateSlashMentionExtensionOptions, SlashCommandItem, SlashSuggestionPlacement } from './types';
+export declare function slashMentionSuggestionRender(uiRef: MutableRefObject<SlashSuggestionListHandle | null>, placement?: SlashSuggestionPlacement): {
     onStart?: (props: SuggestionProps<SlashCommandItem, SlashCommandItem>) => void;
     onUpdate?: (props: SuggestionProps<SlashCommandItem, SlashCommandItem>) => void;
     onExit?: (props: SuggestionProps<SlashCommandItem, SlashCommandItem>) => void;
@@ -18,4 +18,4 @@ export declare function slashMentionSuggestionRender(uiRef: MutableRefObject<Sla
 export type CreateSlashMentionExtensionConfiguredOptions = CreateSlashMentionExtensionOptions & {
     onSuggestionUiActiveChange?: (active: boolean) => void;
 };
-export declare function createSlashMentionExtension({ items: resolvedItems, slashChar, pluginKey, onItemCommand, onSuggestionUiActiveChange, }: CreateSlashMentionExtensionConfiguredOptions): import("@tiptap/core").Node<import("@tiptap/extension-mention").MentionOptions<any, import("@tiptap/extension-mention").MentionNodeAttrs>, any>;
+export declare function createSlashMentionExtension({ items: resolvedItems, slashChar, pluginKey, onItemCommand, suggestionPlacement, onSuggestionUiActiveChange, }: CreateSlashMentionExtensionConfiguredOptions): import("@tiptap/core").Node<import("@tiptap/extension-mention").MentionOptions<any, import("@tiptap/extension-mention").MentionNodeAttrs>, any>;

package/dist/esm/types/src/tiptap/slash-mention/index.d.ts

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

package/dist/esm/types/src/tiptap/slash-mention/types.d.ts

@@ -13,6 +13,8 @@ export type SlashItemCommandContext = {
  * If provided, run before default mention insertion. Return true to skip inserting a mention node.
  */
 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[];
@@ -22,4 +24,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;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sybilion/uilib",
-  "version": "1.3.36",
+  "version": "1.3.37",
   "description": "Sybilion Design System — React UI components (Webpack + Stylus)",
   "publishConfig": {
     "access": "public",

package/src/components/ui/Chat/ChatPrompt/useChatPromptEditor.ts

@@ -94,6 +94,7 @@ export function useChatPromptEditor({
       exts.push(
         createSlashMentionExtension({
           items: slashItemsStable,
+          suggestionPlacement: 'above',
           onSuggestionUiActiveChange: suggestionActiveUpdater,
         }),
       );

package/src/components/ui/Chat/ChatSheet/ChatSheet.tsx

@@ -47,6 +47,7 @@ export function ChatSheet({
   allowedAttachments,
   allowPdfAttachments,
   onAttachmentsDropped,
+  slashCommandItems,
   inline = false,
 }: ChatSheetProps) {
   const model = useChatPanelChromeModel({
@@ -61,6 +62,7 @@ export function ChatSheet({
     allowedAttachments,
     allowPdfAttachments,
     onAttachmentsDropped,
+    slashCommandItems,
   });
 
   if (actionsRef) {

package/src/components/ui/Chat/ChatSheet/useChatPanelChromeModel.tsx

@@ -38,6 +38,7 @@ import useEvent from '#uilib/hooks/useEvent';
 import { useIsMobile } from '#uilib/hooks/useIsMobile';
 import { useQueryParams } from '#uilib/hooks/useQueryParams';
 import logger from '#uilib/lib/logger';
+import type { SlashCommandItem } from '#uilib/tiptap/slash-mention/types';
 import { mergePresetFreeformDefaults } from '#uilib/utils/chatPresetMerge';
 import { ScrollRef } from '@homecode/ui';
 
@@ -70,6 +71,8 @@ export type UseChatPanelChromeModelInput = {
   onAttachmentsDropped?: (
     items: ChatAttachmentDropItem[],
   ) => void | Promise<void>;
+  /** Slash menu (`/`) in the composer; omit or pass empty to disable. */
+  slashCommandItems?: SlashCommandItem[];
 };
 
 export type UseChatPanelChromeModelResult = {
@@ -118,6 +121,7 @@ export function useChatPanelChromeModel({
   allowedAttachments,
   allowPdfAttachments,
   onAttachmentsDropped,
+  slashCommandItems,
 }: UseChatPanelChromeModelInput): UseChatPanelChromeModelResult {
   const effectiveScopeId = scopeId ?? NO_SCOPE_FALLBACK;
   const isMobile = useIsMobile();
@@ -616,103 +620,107 @@ export function useChatPanelChromeModel({
     ],
   );
 
-  const submitPreset = useCallback(async (preset: ChatPreset) => {
-    const script = preset.script;
-    const scriptGraph = isPresetScriptGraph(script);
-    const hasLinearScript = Array.isArray(script) && script.length > 0;
-    const hasReplies = preset.replies && Object.keys(preset.replies).length > 0;
-    const isLocalDemo =
-      hasLinearScript ||
-      scriptGraph ||
-      Boolean(preset.answer?.trim()) ||
-      Boolean(hasReplies);
-
-    if (!isLocalDemo) {
-      if (!currentChatId) return;
-      endLocalDemoFlow(currentChatId);
-      await handlePromptSubmit(preset.text);
-      return;
-    }
+  const submitPreset = useCallback(
+    async (preset: ChatPreset) => {
+      const script = preset.script;
+      const scriptGraph = isPresetScriptGraph(script);
+      const hasLinearScript = Array.isArray(script) && script.length > 0;
+      const hasReplies =
+        preset.replies && Object.keys(preset.replies).length > 0;
+      const isLocalDemo =
+        hasLinearScript ||
+        scriptGraph ||
+        Boolean(preset.answer?.trim()) ||
+        Boolean(hasReplies);
+
+      if (!isLocalDemo) {
+        if (!currentChatId) return;
+        endLocalDemoFlow(currentChatId);
+        await handlePromptSubmit(preset.text);
+        return;
+      }
 
-    setLocalUiBusy(true);
-    try {
-      if (!currentChatId) return;
-      setScriptCompleteByChatId(prev => {
-        const next = { ...prev };
-        delete next[currentChatId];
-        return next;
-      });
-      addMessage(currentChatId, MessageRole.USER, preset.text);
-      await new Promise(resolve => setTimeout(resolve, 1000));
-      const firstAssistant = scriptGraph
-        ? script.initialMessage
-        : (preset.answer ?? '');
-      addMessage(currentChatId, MessageRole.ASSISTANT, firstAssistant);
-
-      setScriptByChatId(prev => {
-        const next = { ...prev };
-        if (hasLinearScript) {
-          next[currentChatId] = {
-            lines: script,
-            nextIndex: 0,
-            presetId: preset.id,
-          };
-        } else {
+      setLocalUiBusy(true);
+      try {
+        if (!currentChatId) return;
+        setScriptCompleteByChatId(prev => {
+          const next = { ...prev };
           delete next[currentChatId];
+          return next;
+        });
+        addMessage(currentChatId, MessageRole.USER, preset.text);
+        await new Promise(resolve => setTimeout(resolve, 1000));
+        const firstAssistant = scriptGraph
+          ? script.initialMessage
+          : (preset.answer ?? '');
+        addMessage(currentChatId, MessageRole.ASSISTANT, firstAssistant);
+
+        setScriptByChatId(prev => {
+          const next = { ...prev };
+          if (hasLinearScript) {
+            next[currentChatId] = {
+              lines: script,
+              nextIndex: 0,
+              presetId: preset.id,
+            };
+          } else {
+            delete next[currentChatId];
+          }
+          return next;
+        });
+        setQuickReplyBranchesByChat(prev => {
+          const next = { ...prev };
+          if (scriptGraph) {
+            next[currentChatId] = branchesFromPresetScriptGraph(script);
+          } else if (hasReplies && !hasLinearScript) {
+            next[currentChatId] = preset.replies!;
+          } else {
+            delete next[currentChatId];
+          }
+          return next;
+        });
+        if (scriptGraph || (hasReplies && !hasLinearScript)) {
+          setUsedScriptBranchKeysByChat(prev => ({
+            ...prev,
+            [currentChatId]: [],
+          }));
         }
-        return next;
-      });
-      setQuickReplyBranchesByChat(prev => {
-        const next = { ...prev };
         if (scriptGraph) {
-          next[currentChatId] = branchesFromPresetScriptGraph(script);
-        } else if (hasReplies && !hasLinearScript) {
-          next[currentChatId] = preset.replies!;
-        } else {
-          delete next[currentChatId];
-        }
-        return next;
-      });
-      if (scriptGraph || (hasReplies && !hasLinearScript)) {
-        setUsedScriptBranchKeysByChat(prev => ({
-          ...prev,
-          [currentChatId]: [],
-        }));
-      }
-      if (scriptGraph) {
-        const fromMerged = presetsWithFreeform.find(p => p.id === preset.id);
-        let freeformNext = {
-          ...(fromMerged?.freeformNext ?? {}),
-          ...(preset.freeformNext ?? {}),
-        };
-        if (Object.keys(freeformNext).length === 0) {
-          const ks = Object.keys(branchesFromPresetScriptGraph(script));
-          if (ks.length === 1) {
-            freeformNext = { initial: ks[0] };
+          const fromMerged = presetsWithFreeform.find(p => p.id === preset.id);
+          let freeformNext = {
+            ...(fromMerged?.freeformNext ?? {}),
+            ...(preset.freeformNext ?? {}),
+          };
+          if (Object.keys(freeformNext).length === 0) {
+            const ks = Object.keys(branchesFromPresetScriptGraph(script));
+            if (ks.length === 1) {
+              freeformNext = { initial: ks[0] };
+            }
           }
+          setIntakeByChatId(prev => ({
+            ...prev,
+            [currentChatId!]: {
+              presetId: preset.id,
+              freeformNext,
+              scriptStepId: 'initial',
+              answers: {},
+            },
+          }));
         }
-        setIntakeByChatId(prev => ({
-          ...prev,
-          [currentChatId!]: {
-            presetId: preset.id,
-            freeformNext,
-            scriptStepId: 'initial',
-            answers: {},
-          },
-        }));
+      } catch (error) {
+        logger.error('Error sending chat message:', error);
+      } finally {
+        setLocalUiBusy(false);
       }
-    } catch (error) {
-      logger.error('Error sending chat message:', error);
-    } finally {
-      setLocalUiBusy(false);
-    }
-  }, [
-    currentChatId,
-    endLocalDemoFlow,
-    handlePromptSubmit,
-    addMessage,
-    presetsWithFreeform,
-  ]);
+    },
+    [
+      currentChatId,
+      endLocalDemoFlow,
+      handlePromptSubmit,
+      addMessage,
+      presetsWithFreeform,
+    ],
+  );
 
   const resolvedEmptyState = useMemo((): ChatEmptyStateProps | undefined => {
     if (!emptyState) return undefined;
@@ -1040,6 +1048,7 @@ export function useChatPanelChromeModel({
     allowedAttachments,
     allowPdfAttachments,
     onAttachmentsDropped,
+    slashCommandItems,
   };
 
   const toggleOpen = () => onOpenChange(!isOpen);

package/src/docs/docsHeaderActions.tsx

@@ -1,9 +1,9 @@
-import { ChatSheet } from '#uilib/components/ui/Chat';
+import { ChatSheet, ChatSheetProps } from '#uilib/components/ui/Chat';
 import { MessageSquare } from 'lucide-react';
 
 import { DOCS_CHAT_SCOPE_ID } from './docsConstants';
 
-export function DocsHeaderActions() {
+export function DocsHeaderActions(props: ChatSheetProps) {
   return (
     <ChatSheet
       triggerLabel={
@@ -21,6 +21,7 @@ export function DocsHeaderActions() {
           <p>Optional empty-state slot via additionalContent.</p>
         ),
       }}
+      {...props}
     />
   );
 }

package/src/docs/pages/ChatSlashCommandsPage.tsx

@@ -85,7 +85,9 @@ export default function ChatSlashCommandsPage() {
         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 />}
+        actions={
+          <DocsHeaderActions slashCommandItems={DOCS_SAMPLE_SLASH_ITEMS} />
+        }
       />
       <PageContentSection>
         <p style={{ marginBottom: 16, fontSize: 14, lineHeight: 1.5 }}>

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();
@@ -149,6 +183,7 @@ export function createSlashMentionExtension({
   slashChar = '/',
   pluginKey,
   onItemCommand,
+  suggestionPlacement = 'below',
   onSuggestionUiActiveChange,
 }: CreateSlashMentionExtensionConfiguredOptions) {
   const uiRef: MutableRefObject<SlashSuggestionListHandle | null> = {
@@ -199,7 +234,7 @@ export function createSlashMentionExtension({
         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

@@ -17,6 +17,9 @@ export type SlashItemCommandContext = {
  */
 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 +29,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;
 };