@gram-ai/elements 1.21.3 → 1.22.0

package/src/components/assistant-ui/tool-mention-autocomplete.tsx

@@ -0,0 +1,253 @@
+import { FC, useCallback, useEffect, useRef, useState } from 'react'
+import { Wrench } from 'lucide-react'
+import * as m from 'motion/react-m'
+
+import { cn } from '@/lib/utils'
+import { useDensity } from '@/hooks/useDensity'
+import { useRadius } from '@/hooks/useRadius'
+import { EASE_OUT_QUINT } from '@/lib/easing'
+import {
+  MentionableTool,
+  detectMentionContext,
+  filterToolsByQuery,
+  insertToolMention,
+} from '@/lib/tool-mentions'
+
+export interface ToolMentionAutocompleteProps {
+  tools: MentionableTool[]
+  value: string
+  cursorPosition: number
+  onValueChange: (value: string, cursorPosition: number) => void
+  textareaRef: React.RefObject<HTMLTextAreaElement | null>
+  className?: string
+}
+
+export const ToolMentionAutocomplete: FC<ToolMentionAutocompleteProps> = ({
+  tools,
+  value,
+  cursorPosition,
+  onValueChange,
+  textareaRef,
+  className,
+}) => {
+  const [selectedIndex, setSelectedIndex] = useState(0)
+  const [isVisible, setIsVisible] = useState(false)
+  const [filteredTools, setFilteredTools] = useState<MentionableTool[]>([])
+  const [mentionContext, setMentionContext] = useState<{
+    atPosition: number
+    query: string
+  } | null>(null)
+
+  const containerRef = useRef<HTMLDivElement>(null)
+  const d = useDensity()
+  const r = useRadius()
+
+  useEffect(() => {
+    const context = detectMentionContext(value, cursorPosition)
+
+    if (context.isInMention && tools.length > 0) {
+      const filtered = filterToolsByQuery(tools, context.query)
+      setFilteredTools(filtered)
+      setIsVisible(filtered.length > 0)
+      setMentionContext({
+        atPosition: context.atPosition,
+        query: context.query,
+      })
+      setSelectedIndex(0)
+    } else {
+      setIsVisible(false)
+      setMentionContext(null)
+    }
+  }, [value, cursorPosition, tools])
+
+  const selectTool = useCallback(
+    (tool: MentionableTool) => {
+      if (!mentionContext) return
+
+      const result = insertToolMention(
+        value,
+        tool.name,
+        mentionContext.atPosition,
+        cursorPosition
+      )
+
+      onValueChange(result.text, result.cursorPosition)
+      setIsVisible(false)
+    },
+    [mentionContext, value, cursorPosition, onValueChange, textareaRef]
+  )
+
+  useEffect(() => {
+    if (!isVisible) return
+
+    const handleKeyDown = (e: KeyboardEvent) => {
+      switch (e.key) {
+        case 'ArrowDown':
+          e.preventDefault()
+          e.stopPropagation()
+          setSelectedIndex((prev) => (prev + 1) % filteredTools.length)
+          break
+        case 'ArrowUp':
+          e.preventDefault()
+          e.stopPropagation()
+          setSelectedIndex(
+            (prev) => (prev - 1 + filteredTools.length) % filteredTools.length
+          )
+          break
+        case 'Enter':
+        case 'Tab':
+          e.preventDefault()
+          e.stopPropagation()
+          if (filteredTools[selectedIndex]) {
+            selectTool(filteredTools[selectedIndex])
+          }
+          break
+        case 'Escape':
+          e.preventDefault()
+          e.stopPropagation()
+          setIsVisible(false)
+          break
+      }
+    }
+
+    const textarea = textareaRef.current
+    if (textarea) {
+      textarea.addEventListener('keydown', handleKeyDown, { capture: true })
+      return () =>
+        textarea.removeEventListener('keydown', handleKeyDown, {
+          capture: true,
+        })
+    }
+  }, [isVisible, filteredTools, selectedIndex, selectTool, textareaRef])
+
+  // Scroll selected item into view
+  useEffect(() => {
+    if (!isVisible) return
+    const container = containerRef.current
+    if (!container) return
+
+    const selectedItem = container.querySelector(
+      `[data-index="${selectedIndex}"]`
+    ) as HTMLElement
+    if (selectedItem) {
+      selectedItem.scrollIntoView({ block: 'nearest' })
+    }
+  }, [selectedIndex, isVisible])
+
+  useEffect(() => {
+    if (!isVisible) return
+
+    const handleClickOutside = (e: MouseEvent) => {
+      if (
+        containerRef.current &&
+        !containerRef.current.contains(e.target as Node) &&
+        textareaRef.current &&
+        !textareaRef.current.contains(e.target as Node)
+      ) {
+        setIsVisible(false)
+      }
+    }
+
+    document.addEventListener('mousedown', handleClickOutside)
+    return () => document.removeEventListener('mousedown', handleClickOutside)
+  }, [isVisible, textareaRef])
+
+  // When autocomplete is visible, modify composer styles and position autocomplete to match composer width
+  useEffect(() => {
+    const textarea = textareaRef.current
+    if (!textarea) return
+
+    const composer = textarea.closest('.aui-composer-root') as HTMLElement
+    if (!composer) return
+
+    const updateStyles = () => {
+      const autocomplete = containerRef.current
+      if (!autocomplete) return
+
+      if (isVisible) {
+        // Modify composer to connect with autocomplete
+        composer.style.borderTopColor = 'var(--ring)'
+        composer.style.borderTopLeftRadius = '0'
+        composer.style.borderTopRightRadius = '0'
+
+        // Position autocomplete to match composer width
+        const composerRect = composer.getBoundingClientRect()
+        const autocompleteParent = autocomplete.offsetParent as HTMLElement
+        if (autocompleteParent) {
+          const parentRect = autocompleteParent.getBoundingClientRect()
+          autocomplete.style.left = `${composerRect.left - parentRect.left}px`
+          autocomplete.style.right = 'auto'
+          autocomplete.style.width = `${composerRect.width}px`
+        }
+      }
+    }
+
+    if (isVisible) {
+      // Use requestAnimationFrame to ensure DOM is updated
+      requestAnimationFrame(updateStyles)
+    } else {
+      composer.style.borderTopColor = ''
+      composer.style.borderTopLeftRadius = ''
+      composer.style.borderTopRightRadius = ''
+    }
+
+    return () => {
+      composer.style.borderTopColor = ''
+      composer.style.borderTopLeftRadius = ''
+      composer.style.borderTopRightRadius = ''
+    }
+  }, [isVisible, textareaRef])
+
+  if (!isVisible || filteredTools.length === 0) {
+    return null
+  }
+
+  return (
+    <m.div
+      ref={containerRef}
+      initial={{ opacity: 0, y: 8 }}
+      animate={{ opacity: 1, y: 0 }}
+      exit={{ opacity: 0, y: 8 }}
+      transition={{ duration: 0.15, ease: EASE_OUT_QUINT }}
+      className={cn(
+        'aui-tool-mention-autocomplete border-ring bg-background absolute bottom-full z-50 max-h-[220px] overflow-clip overflow-y-auto overscroll-contain rounded-br-none! rounded-bl-none! border border-b-0 shadow-xs',
+        r('xl'),
+        className
+      )}
+    >
+      <div className="flex flex-col gap-1">
+        {filteredTools.map((tool, index) => (
+          <button
+            key={tool.id}
+            type="button"
+            data-index={index}
+            className={cn(
+              'aui-tool-mention-item flex w-full items-center gap-2 text-left transition-colors',
+              d('p-sm'),
+              'hover:bg-accent hover:text-accent-foreground',
+              index === selectedIndex && 'bg-accent text-accent-foreground'
+            )}
+            onClick={(e) => {
+              e.preventDefault()
+              e.stopPropagation()
+              selectTool(tool)
+            }}
+            onMouseEnter={() => setSelectedIndex(index)}
+          >
+            <Wrench className="mt-0.5 size-4 flex-shrink-0 opacity-50" />
+            <div className="min-w-0 flex-1">
+              <div className="text-sm font-medium">{tool.name}</div>
+              {tool.description && (
+                <div className="text-muted-foreground line-clamp-2 text-xs">
+                  {tool.description}
+                </div>
+              )}
+            </div>
+          </button>
+        ))}
+      </div>
+    </m.div>
+  )
+}
+
+export default ToolMentionAutocomplete

package/src/components/ui/tool-ui.tsx

@@ -322,7 +322,7 @@ function ToolUISection({
     <div data-slot="tool-ui-section" className="border-border border-t">
       <button
         onClick={() => setIsExpanded(!isExpanded)}
-        className="hover:bg-accent/50 flex w-full cursor-pointer items-center justify-between px-4 py-2.5 text-left transition-colors"
+        className="hover:bg-accent/50 flex w-full cursor-pointer items-center justify-between px-5 py-2.5 text-left transition-colors"
       >
         <span className="text-muted-foreground text-sm">{title}</span>
         <div className="flex items-center gap-1">

package/src/contexts/ElementsProvider.tsx

@@ -349,8 +349,9 @@ const ElementsProviderWithApproval = ({
       isOpen: isOpen ?? false,
       setIsOpen,
       plugins,
+      mcpTools,
     }),
-    [config, model, isExpanded, isOpen, plugins]
+    [config, model, isExpanded, isOpen, plugins, mcpTools]
   )
 
   const frontendTools = config.tools?.frontendTools ?? {}

package/src/hooks/useToolMentions.ts

@@ -0,0 +1,93 @@
+import { useCallback, useMemo, useRef, useState } from 'react'
+import { useAssistantApi, useAssistantState } from '@assistant-ui/react'
+import {
+  MentionableTool,
+  parseMentionedTools,
+  removeToolMention,
+  toolSetToMentionableTools,
+} from '@/lib/tool-mentions'
+
+export interface UseToolMentionsOptions {
+  tools: Record<string, unknown> | undefined
+  enabled?: boolean
+}
+
+export interface UseToolMentionsReturn {
+  mentionableTools: MentionableTool[]
+  mentionedToolIds: string[]
+  value: string
+  cursorPosition: number
+  textareaRef: React.RefObject<HTMLTextAreaElement | null>
+  updateCursorPosition: () => void
+  handleAutocompleteChange: (value: string, cursorPosition: number) => void
+  removeMention: (toolId: string) => void
+  isActive: boolean
+}
+
+export function useToolMentions({
+  tools,
+  enabled = true,
+}: UseToolMentionsOptions): UseToolMentionsReturn {
+  const [cursorPosition, setCursorPosition] = useState(0)
+  const textareaRef = useRef<HTMLTextAreaElement | null>(null)
+  const api = useAssistantApi()
+  const composerText = useAssistantState(({ composer }) => composer.text)
+
+  const mentionableTools = useMemo(
+    () => toolSetToMentionableTools(tools),
+    [tools]
+  )
+
+  const mentionedToolIds = useMemo(
+    () => (enabled ? parseMentionedTools(composerText, tools) : []),
+    [composerText, tools, enabled]
+  )
+
+  const updateCursorPosition = useCallback(() => {
+    const textarea = textareaRef.current
+    if (textarea) {
+      setCursorPosition(textarea.selectionStart)
+    }
+  }, [])
+
+  const handleAutocompleteChange = useCallback(
+    (newValue: string, newCursorPosition: number) => {
+      api.composer().setText(newValue)
+      setCursorPosition(newCursorPosition)
+
+      setTimeout(() => {
+        const textarea = textareaRef.current
+        if (textarea) {
+          textarea.focus()
+          textarea.setSelectionRange(newCursorPosition, newCursorPosition)
+        }
+      }, 0)
+    },
+    [api]
+  )
+
+  const removeMention = useCallback(
+    (toolId: string) => {
+      const tool = mentionableTools.find((t) => t.id === toolId)
+      if (tool) {
+        const newValue = removeToolMention(composerText, tool.name)
+        api.composer().setText(newValue)
+      }
+    },
+    [composerText, mentionableTools, api]
+  )
+
+  const isActive = enabled && mentionableTools.length > 0
+
+  return {
+    mentionableTools,
+    mentionedToolIds,
+    value: composerText,
+    cursorPosition,
+    textareaRef,
+    updateCursorPosition,
+    handleAutocompleteChange,
+    removeMention,
+    isActive,
+  }
+}

package/src/index.ts

@@ -43,6 +43,7 @@ export type {
   SidecarConfig,
   Suggestion,
   ThemeConfig,
+  ToolMentionsConfig,
   ToolsConfig,
   Variant,
   VARIANTS,

package/src/lib/tool-mentions.ts

@@ -0,0 +1,106 @@
+export type ToolRecord = Record<string, unknown> | undefined
+
+export interface MentionableTool {
+  id: string
+  name: string
+  description?: string
+}
+
+export interface MentionContext {
+  isInMention: boolean
+  query: string
+  atPosition: number
+}
+
+const MENTION_PATTERN = /@(\w+)/g
+
+export function toolSetToMentionableTools(
+  tools: ToolRecord
+): MentionableTool[] {
+  if (!tools) return []
+
+  return Object.entries(tools).map(([name, tool]) => ({
+    id: name,
+    name,
+    description:
+      typeof tool === 'object' && tool !== null && 'description' in tool
+        ? String((tool as { description?: unknown }).description ?? '')
+        : undefined,
+  }))
+}
+
+export function parseMentionedTools(text: string, tools: ToolRecord): string[] {
+  if (!tools || !text) return []
+
+  const toolNames = Object.keys(tools)
+  const mentions: string[] = []
+  let match: RegExpExecArray | null
+
+  MENTION_PATTERN.lastIndex = 0
+  while ((match = MENTION_PATTERN.exec(text)) !== null) {
+    mentions.push(match[1].toLowerCase())
+  }
+
+  const matchedToolIds = toolNames.filter((name) =>
+    mentions.includes(name.toLowerCase())
+  )
+
+  return [...new Set(matchedToolIds)]
+}
+
+export function detectMentionContext(
+  text: string,
+  cursorPosition: number
+): MentionContext {
+  const textBeforeCursor = text.slice(0, cursorPosition)
+  const lastAtSymbol = textBeforeCursor.lastIndexOf('@')
+
+  if (lastAtSymbol === -1) {
+    return { isInMention: false, query: '', atPosition: -1 }
+  }
+
+  const textAfterAt = textBeforeCursor.slice(lastAtSymbol + 1)
+
+  if (textAfterAt.includes(' ') || textAfterAt.includes('\n')) {
+    return { isInMention: false, query: '', atPosition: -1 }
+  }
+
+  return {
+    isInMention: true,
+    query: textAfterAt.toLowerCase(),
+    atPosition: lastAtSymbol,
+  }
+}
+
+export function filterToolsByQuery(
+  tools: MentionableTool[],
+  query: string
+): MentionableTool[] {
+  if (!query) return tools
+
+  const queryLower = query.toLowerCase()
+
+  return tools.filter((tool) => {
+    const nameMatch = tool.name.toLowerCase().includes(queryLower)
+    const descMatch = tool.description?.toLowerCase().includes(queryLower)
+    return nameMatch || descMatch
+  })
+}
+
+export function insertToolMention(
+  text: string,
+  toolName: string,
+  atPosition: number,
+  cursorPosition: number
+): { text: string; cursorPosition: number } {
+  const beforeMention = text.slice(0, atPosition)
+  const afterCursor = text.slice(cursorPosition)
+  const newText = `${beforeMention}@${toolName} ${afterCursor}`
+  const newCursorPosition = atPosition + toolName.length + 2
+  return { text: newText, cursorPosition: newCursorPosition }
+}
+
+export function removeToolMention(text: string, toolName: string): string {
+  const pattern = new RegExp(`@${toolName}\\s?`, 'gi')
+  return text.replace(pattern, '')
+}

package/src/types/index.ts

@@ -754,6 +754,13 @@ export interface ComposerConfig {
    * @default true
    */
   attachments?: boolean | AttachmentsConfig
+
+  /**
+   * Configuration for @tool mentions in the composer.
+   * Set to `false` to disable, `true` for defaults, or an object for fine-grained control.
+   * @default true
+   */
+  toolMentions?: boolean | ToolMentionsConfig
 }
 
 /**
@@ -781,6 +788,14 @@ export interface AttachmentsConfig {
   maxSize?: number
 }
 
+export interface ToolMentionsConfig {
+  /** @default true */
+  enabled?: boolean
+  /** @default 10 */
+  maxSuggestions?: number
+  placeholder?: string
+}
+
 export interface SidecarConfig extends ExpandableConfig {
   /**
    * The title displayed in the sidecar header.
@@ -829,4 +844,5 @@ export type ElementsContextType = {
   isOpen: boolean
   setIsOpen: (isOpen: boolean) => void
   plugins: Plugin[]
+  mcpTools: Record<string, unknown> | undefined
 }