@tambo-ai/react 0.68.0 → 0.69.1

package/dist/providers/tambo-context-attachment-provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"tambo-context-attachment-provider.js","sourceRoot":"","sources":["../../src/providers/tambo-context-attachment-provider.tsx"],"names":[],"mappings":"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","sourcesContent":["\"use client\";\n\nimport type { Suggestion } from \"@tambo-ai/typescript-sdk/resources/beta/threads/suggestions\";\nimport React, {\n  createContext,\n  useCallback,\n  useContext,\n  useEffect,\n  useMemo,\n  useRef,\n  useState,\n} from \"react\";\nimport { useTamboContextHelpers } from \"./tambo-context-helpers-provider\";\n\n/**\n * Represents a context attachment that can be displayed in MessageInputContexts.\n * Context attachments appear as badges above the message input and provide additional\n * information to the AI about what to focus on.\n * @property {string} name - Display name shown in the badge\n * @property {React.ReactNode} [icon] - Optional icon to display in the badge\n * @property {Record<string, unknown>} [metadata] - Additional data passed to the AI\n * @example\n * ```tsx\n * const context: ContextAttachment = {\n *   name: \"Button.tsx\",\n *   icon: <FileIcon />,\n *   metadata: { filePath: \"/src/components/Button.tsx\" }\n * };\n * ```\n */\nexport interface ContextAttachment {\n  id: string;\n  name: string;\n  icon?: React.ReactNode;\n  metadata?: Record<string, unknown>;\n}\n\n/**\n * Represents the data structure returned by a context helper\n */\nexport type ContextHelperData = Record<string, unknown>;\n\n/**\n * Context state interface for managing context attachments and custom suggestions.\n * @property {ContextAttachment[]} attachments - Array of active context attachments (badges above message input)\n * @property {(context: Omit<ContextAttachment, \"id\">) => void} addContextAttachment - Add a new context attachment\n * @property {(id: string) => void} removeContextAttachment - Remove a context attachment by ID\n * @property {() => void} clearContextAttachments - Remove all context attachments - This is used to clear the context when the user submits a message\n * @property {Suggestion[] | null} customSuggestions - Custom suggestions to display instead of auto-generated ones\n * @property {(suggestions: Suggestion[] | null) => void} setCustomSuggestions - Set or clear custom suggestions\n */\nexport interface ContextAttachmentState {\n  attachments: ContextAttachment[];\n  addContextAttachment: (context: Omit<ContextAttachment, \"id\">) => void;\n  removeContextAttachment: (id: string) => void;\n  clearContextAttachments: () => void;\n  customSuggestions: Suggestion[] | null;\n  setCustomSuggestions: (suggestions: Suggestion[] | null) => void;\n}\n\nconst ContextAttachmentContext = createContext<ContextAttachmentState | null>(\n  null,\n);\n\n/**\n * Props for the TamboContextAttachmentProvider.\n * @property {(context: ContextAttachment) => Promise<ContextHelperData> | ContextHelperData} [getContextHelperData] - Optional function to customize the data sent to the AI for each context. If not provided, uses a default structure with the context name and instruction.\n * @example\n * ```tsx\n * <TamboContextAttachmentProvider\n *   getContextHelperData={(context) => ({\n *     selectedFile: {\n *       name: context.name,\n *       path: context.metadata?.filePath,\n *       instruction: \"Focus on this file\"\n *     }\n *   })}\n * >\n *   {children}\n * </TamboContextAttachmentProvider>\n * ```\n */\nexport interface TamboContextAttachmentProviderProps {\n  children?: React.ReactNode;\n  getContextHelperData?: (\n    context: ContextAttachment,\n  ) => Promise<ContextHelperData> | ContextHelperData;\n}\n\n/**\n * Provider that enables context attachment features and custom suggestions in MessageInput.\n * **When to use:**\n * - **Included by default** in TamboProvider - no need to wrap separately\n * - Use `useTamboContextAttachment()` hook to manage context attachments\n * **What it does:**\n * - Manages context items that appear as badges above MessageInput\n * - Syncs context data with Tambo's AI for better responses\n * - Manages custom suggestions that replace auto-generated suggestions\n * - Allows components to add/remove contexts via `useTamboContextAttachment()`\n * - Allows components to set custom suggestions via `setCustomSuggestions()`\n * @param props - The props for the TamboContextAttachmentProvider\n * @param props.children - The children to wrap\n * @param props.getContextHelperData - The function to get the context helper data\n * @returns The TamboContextAttachmentProvider component\n * @example\n * Basic usage - already included in TamboProvider\n * ```tsx\n * <TamboProvider apiKey=\"...\">\n *   <App />\n * </TamboProvider>\n * ```\n * @example\n * Using TamboProvider with custom context data\n * ```tsx\n * <TamboProvider\n *   apiKey=\"...\"\n *   getContextHelperData={(context) => ({\n *     selectedComponent: {\n *       name: context.name,\n *       filePath: context.metadata?.path,\n *       instruction: \"Edit this component\"\n *     }\n *   })}\n * >\n *   <App />\n * </TamboProvider>\n * ```\n */\nexport function TamboContextAttachmentProvider({\n  children,\n  getContextHelperData,\n}: TamboContextAttachmentProviderProps) {\n  const [attachments, setAttachments] = useState<ContextAttachment[]>([]);\n  const [customSuggestions, setCustomSuggestions] = useState<\n    Suggestion[] | null\n  >(null);\n  const { addContextHelper, removeContextHelper } = useTamboContextHelpers();\n\n  // Track which context helpers have been registered to avoid duplicates\n  const registeredIdsRef = useRef<Set<string>>(new Set());\n  const prevGetContextHelperDataRef = useRef<typeof getContextHelperData>();\n\n  // Sync context helpers with attachments using useEffect\n  useEffect(() => {\n    const currentIds = attachments.map((a) => a.id);\n    const registeredIds = registeredIdsRef.current;\n\n    // Remove context helpers that are no longer in attachments\n    registeredIds.forEach((id) => {\n      if (!currentIds.includes(id)) {\n        removeContextHelper(id);\n        registeredIds.delete(id);\n      }\n    });\n\n    const getDataChanged =\n      prevGetContextHelperDataRef.current !== getContextHelperData;\n\n    // Add or replace context helpers for attachments\n    attachments.forEach((context) => {\n      if (getDataChanged || !registeredIds.has(context.id)) {\n        addContextHelper(context.id, async (): Promise<ContextHelperData> => {\n          if (getContextHelperData) {\n            return await getContextHelperData(context);\n          }\n          return {\n            selectedComponent: {\n              name: context.name,\n              instruction:\n                \"This is a Tambo interactable component that is currently selected and visible on the dashboard. You can read its current props and state, and update it by modifying its props. If multiple components are attached, you can interact with and modify any of them. Use the auto-registered interactable component tools (like get_interactable_component_by_id and update_interactable_component_<id>) to view and update the component's state.\",\n              ...(context.metadata ?? {}),\n            },\n          };\n        });\n        registeredIds.add(context.id);\n      }\n    });\n\n    prevGetContextHelperDataRef.current = getContextHelperData;\n  }, [\n    attachments,\n    addContextHelper,\n    removeContextHelper,\n    getContextHelperData,\n  ]);\n\n  // Cleanup: remove all context helpers on unmount\n  useEffect(() => {\n    const registeredIds = registeredIdsRef.current;\n    return () => {\n      registeredIds.forEach((id) => {\n        removeContextHelper(id);\n      });\n      registeredIds.clear();\n    };\n  }, [removeContextHelper]);\n\n  const addContextAttachment = useCallback(\n    (context: Omit<ContextAttachment, \"id\">) => {\n      setAttachments((prev) => {\n        if (prev.some((c) => c.name === context.name)) return prev;\n\n        if (typeof crypto === \"undefined\" || !(\"randomUUID\" in crypto)) {\n          throw new Error(\n            \"crypto.randomUUID() is not available. This usually happens when using an IP address instead of 'localhost' in development. Use 'localhost' or a secure context (HTTPS) to enable crypto APIs.\",\n          );\n        }\n\n        const newId = crypto.randomUUID();\n        const newContext = { ...context, id: newId };\n        return [...prev, newContext];\n      });\n    },\n    [],\n  );\n\n  // This is used to remove a context when the user clicks the remove button\n  const removeContextAttachment = useCallback((id: string) => {\n    setAttachments((prev) => prev.filter((c) => c.id !== id));\n  }, []);\n\n  // This is used to clear the context when the user submits a message\n  const clearContextAttachments = useCallback(() => {\n    setAttachments([]);\n  }, []);\n\n  const value = useMemo(\n    () => ({\n      attachments,\n      addContextAttachment,\n      removeContextAttachment,\n      clearContextAttachments,\n      customSuggestions,\n      setCustomSuggestions,\n    }),\n    [\n      attachments,\n      addContextAttachment,\n      removeContextAttachment,\n      clearContextAttachments,\n      customSuggestions,\n    ],\n  );\n\n  return (\n    <ContextAttachmentContext.Provider value={value}>\n      {children}\n    </ContextAttachmentContext.Provider>\n  );\n}\n\n/**\n * Hook to access context attachment state and methods.\n * **Must be used within a `TamboProvider`** - throws an error otherwise.\n * @throws {Error} If used outside of TamboProvider\n * @returns The context attachment state and methods\n * @example\n * ```tsx\n * const contextAttachment = useTamboContextAttachment();\n *\n * // Add a context\n * contextAttachment.addContextAttachment({\n *   name: \"Button.tsx\",\n *   icon: <FileIcon />,\n *   metadata: { path: \"/src/Button.tsx\" }\n * });\n *\n * // Remove a context\n * contextAttachment.removeContextAttachment(contextId);\n *\n * // Set custom suggestions\n * contextAttachment.setCustomSuggestions([{ id: \"1\", title: \"Add Feature\" }]);\n * ```\n */\nexport function useTamboContextAttachment() {\n  const context = useContext(ContextAttachmentContext);\n  if (!context) {\n    throw new Error(\n      \"useTamboContextAttachment must be used within a TamboContextAttachmentProvider\",\n    );\n  }\n  return context;\n}\n"]}
+{"version":3,"file":"tambo-context-attachment-provider.js","sourceRoot":"","sources":["../../src/providers/tambo-context-attachment-provider.tsx"],"names":[],"mappings":"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","sourcesContent":["\"use client\";\n\nimport React, {\n  createContext,\n  useCallback,\n  useContext,\n  useEffect,\n  useMemo,\n  useState,\n} from \"react\";\nimport { useTamboContextHelpers } from \"./tambo-context-helpers-provider\";\n\n/**\n * Represents a context attachment that will be sent with the next user message.\n * These are automatically registered as context helpers and will be included in\n * the additionalContext when the next message is sent.\n * @property {string} id - Unique identifier for this context attachment\n * @property {string} [displayName] - Optional display name for UI rendering\n * @property {string} context - The context value that will be used in additionalContext\n * @property {string} [type] - Optional type identifier for grouping/rendering multiple contexts of the same type\n */\nexport interface ContextAttachment {\n  id: string;\n  displayName?: string;\n  context: string;\n  type?: string;\n}\n\n/**\n * Context state interface for managing context attachments.\n * @property {ContextAttachment[]} attachments - Array of active context attachments\n * @property {(contextAttachment: Omit<ContextAttachment, \"id\">) => ContextAttachment} addContextAttachment - Add a new context attachment, returns the attachment\n * @property {(id: string) => void} removeContextAttachment - Remove a context attachment by ID\n * @property {() => void} clearContextAttachments - Remove all context attachments\n */\nexport interface ContextAttachmentState {\n  attachments: ContextAttachment[];\n  addContextAttachment: (\n    contextAttachment: Omit<ContextAttachment, \"id\">,\n  ) => ContextAttachment;\n  removeContextAttachment: (id: string) => void;\n  clearContextAttachments: () => void;\n}\n\nconst ContextAttachmentContext = createContext<ContextAttachmentState | null>(\n  null,\n);\n\nexport interface TamboContextAttachmentProviderProps {\n  children?: React.ReactNode;\n}\n\nconst CONTEXT_ATTACHMENTS_HELPER_KEY = \"contextAttachments\";\n\n/**\n * Provider that manages context attachments for the next user message.\n * - **Included by default** in TamboProvider - no need to wrap separately\n * - Use `useTamboContextAttachment()` hook to manage context attachments\n * **What it does:**\n * - Stores context attachments that will be sent with the next message\n * - Automatically registers/deregisters context helpers for each attachment\n * - Context helpers are automatically collected during message submission\n * - Context attachments are cleared after message submission (one-time use)\n *\n * **Note:** Context attachments are automatically included in additionalContext when\n * the next message is sent. They are cleared after submission.\n * @param props - The props for the TamboContextAttachmentProvider\n * @param props.children - The children to wrap\n * @returns The TamboContextAttachmentProvider component\n */\nexport function TamboContextAttachmentProvider({\n  children,\n}: TamboContextAttachmentProviderProps) {\n  const { addContextHelper, removeContextHelper } = useTamboContextHelpers();\n  const [attachments, setAttachments] = useState<ContextAttachment[]>([]);\n\n  useEffect(() => {\n    addContextHelper(CONTEXT_ATTACHMENTS_HELPER_KEY, () => {\n      if (attachments.length === 0) {\n        return null;\n      }\n\n      return attachments.map((attachment) => ({\n        id: attachment.id,\n        displayName: attachment.displayName,\n        context: attachment.context,\n        type: attachment.type,\n      }));\n    });\n\n    return () => {\n      removeContextHelper(CONTEXT_ATTACHMENTS_HELPER_KEY);\n    };\n  }, [attachments, addContextHelper, removeContextHelper]);\n\n  /**\n   * Adds a new context attachment that will be included with the next user message.\n   * The attachment is automatically registered as part of the merged context helper.\n   * @param contextAttachment - The context attachment input (context, optional displayName, optional type)\n   * @returns The created ContextAttachment object with a unique ID\n   * @example\n   * ```tsx\n   * const attachment = addContextAttachment({\n   *   context: \"The contents of File.txt\",\n   *   displayName: \"File.txt\",\n   *   type: \"file\"\n   * });\n   * ```\n   */\n  const addContextAttachment = useCallback(\n    (contextAttachment: Omit<ContextAttachment, \"id\">): ContextAttachment => {\n      const id = crypto.randomUUID();\n      const attachment: ContextAttachment = {\n        id,\n        displayName: contextAttachment.displayName,\n        context: contextAttachment.context,\n        type: contextAttachment.type,\n      };\n      setAttachments((prev) => [...prev, attachment]);\n\n      return attachment;\n    },\n    [],\n  );\n\n  /**\n   * Removes a context attachment by its ID.\n   */\n  const removeContextAttachment = useCallback((id: string) => {\n    setAttachments((prev) => prev.filter((c) => c.id !== id));\n  }, []);\n\n  /**\n   * Removes all context attachments at once.\n   */\n  const clearContextAttachments = useCallback(() => {\n    setAttachments([]);\n  }, []);\n\n  const value = useMemo(\n    () => ({\n      attachments,\n      addContextAttachment,\n      removeContextAttachment,\n      clearContextAttachments,\n    }),\n    [\n      attachments,\n      addContextAttachment,\n      removeContextAttachment,\n      clearContextAttachments,\n    ],\n  );\n\n  return (\n    <ContextAttachmentContext.Provider value={value}>\n      {children}\n    </ContextAttachmentContext.Provider>\n  );\n}\n\n/**\n * Hook to access context attachment state and methods.\n * **Must be used within a `TamboProvider`** - throws an error otherwise.\n * @throws {Error} If used outside of TamboProvider\n * @returns The context attachment state and methods\n * @example\n * ```tsx\n * const { addContextAttachment, attachments, clearContextAttachments } = useTamboContextAttachment();\n *\n * // Add a context attachment for the next message\n * const attachment = addContextAttachment({\n *   context: \"The contents of File.txt\",\n *   displayName: \"File.txt\", // optional\n *   type: \"file\" // optional\n * });\n *\n * // Remove a context attachment\n * removeContextAttachment(attachment.id);\n *\n * // Clear all context attachments\n * clearContextAttachments();\n * ```\n */\nexport function useTamboContextAttachment() {\n  const context = useContext(ContextAttachmentContext);\n  if (!context) {\n    throw new Error(\n      \"useTamboContextAttachment must be used within a TamboContextAttachmentProvider\",\n    );\n  }\n  return context;\n}\n"]}