@tambo-ai/react 0.19.3 → 0.19.4

package/dist/hooks/use-component-state.js

@@ -49,26 +49,12 @@ function useTamboComponentState(keyName, initialValue, debounceTime = 500) {
     ]);
     // Create debounced save function for efficient server synchronization
     const debouncedServerWrite = (0, use_debounce_1.useDebouncedCallback)(async (newValue) => {
-        if (!message) {
-            console.warn(`Cannot update missing message ${messageId} for state key "${keyName}"`);
-            return;
-        }
         setIsPending(true);
         try {
-            const messageUpdate = {
-                ...message,
-                componentState: {
-                    ...message.componentState,
-                    [keyName]: newValue,
-                },
-            };
             const componentStateUpdate = {
                 state: { [keyName]: newValue },
             };
-            await Promise.all([
-                updateThreadMessage(messageId, messageUpdate, false),
-                client.beta.threads.messages.updateComponentState(threadId, messageId, componentStateUpdate),
-            ]);
+            await client.beta.threads.messages.updateComponentState(threadId, messageId, componentStateUpdate);
         }
         catch (err) {
             console.error(`Failed to save component state for key "${keyName}":`, err);
@@ -127,11 +113,19 @@ function useTamboComponentState(keyName, initialValue, debounceTime = 500) {
         // Only trigger server updates if we have a message
         if (message) {
             debouncedServerWrite(newValue);
+            const messageUpdate = {
+                ...message,
+                componentState: {
+                    ...message.componentState,
+                    [keyName]: newValue,
+                },
+            };
+            updateThreadMessage(messageId, messageUpdate, false);
         }
         else {
             console.warn(`Cannot update server for missing message ${messageId} with key "${keyName}"`);
         }
-    }, [debouncedServerWrite, message, messageId, keyName]);
+    }, [message, debouncedServerWrite, keyName, updateThreadMessage, messageId]);
     // Ensure pending changes are flushed on unmount
     (0, react_1.useEffect)(() => {
         return () => {

package/dist/hooks/use-component-state.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-component-state.js","sourceRoot":"","sources":["../../src/hooks/use-component-state.tsx"],"names":[],"mappings":"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","sourcesContent":["import { useCallback, useEffect, useState } from \"react\";\nimport { useDebouncedCallback } from \"use-debounce\";\nimport { useTamboClient, useTamboThread } from \"../providers\";\nimport {\n  useTamboCurrentMessage,\n  useTamboMessageContext,\n} from \"./use-current-message\";\n// Define metadata interface for better extensibility\ninterface ComponentStateMeta {\n  isPending: boolean;\n}\n\ntype StateUpdateResult<T> = [\n  currentState: T,\n  setState: (newState: T) => void,\n  meta: ComponentStateMeta,\n];\n\n/**\n * A React hook that provides state management and passes user updates to Tambo.\n * Benefits: Passes user changes to AI, and when threads are returned, state is preserved.\n * @param keyName - The unique key to identify this state within the message's componentState object\n * @param initialValue - Optional initial value for the state, used if no value exists in the message\n * @param debounceTime - Optional debounce time in milliseconds (default: 300ms) to limit API calls\n * @returns A tuple containing:\n *   - The current state value\n *   - A setter function to update the state (updates UI immediately, debounces server sync)\n *   - A metadata object with properties like isPending to track sync status\n * @example\n * // Basic usage\n * const [count, setCount, { isPending }] = useTamboComponentState(\"counter\", 0);\n *\n * // Usage with object state\n * const [formState, setFormState] = useTamboComponentState(\"myForm\", {\n *   name: \"\",\n *   email: \"\",\n *   message: \"\"\n * });\n *\n * // Handling form input\n * const handleChange = (e) => {\n *   setFormState({\n *     ...formState,\n *     [e.target.name]: e.target.value\n *   });\n * };\n */\nexport function useTamboComponentState<S = undefined>(\n  keyName: string,\n  initialValue?: S,\n  debounceTime?: number,\n): StateUpdateResult<S | undefined>;\nexport function useTamboComponentState<S>(\n  keyName: string,\n  initialValue: S,\n  debounceTime?: number,\n): StateUpdateResult<S>;\n// eslint-disable-next-line jsdoc/require-jsdoc\nexport function useTamboComponentState<S>(\n  keyName: string,\n  initialValue?: S,\n  debounceTime = 500,\n): StateUpdateResult<S> {\n  const { threadId, messageId } = useTamboMessageContext();\n  const { updateThreadMessage } = useTamboThread();\n  const client = useTamboClient();\n  const message = useTamboCurrentMessage();\n\n  // Initial value management\n  const [cachedInitialValue] = useState(() => initialValue);\n  // UI state management\n  const [localState, setLocalState] = useState<S | undefined>(\n    cachedInitialValue,\n  );\n  // Synchronization state\n  const [isPending, setIsPending] = useState(false);\n  // Track the last user-initiated value instead of a simple boolean flag\n  const [lastUserValue, setLastUserValue] = useState<S | null>(null);\n  const [haveInitialized, setHaveInitialized] = useState(false);\n\n  // Determine if we need to initialize state\n  const shouldInitialize =\n    !haveInitialized &&\n    message &&\n    cachedInitialValue !== undefined &&\n    (!message.componentState || !(keyName in message.componentState));\n\n  // Sync local state with message state on initial load and when message changes\n  useEffect(() => {\n    if (message?.componentState && keyName in message.componentState) {\n      const messageState = message.componentState[keyName] as S;\n\n      // Only update local state if we haven't had any user changes yet\n      if (lastUserValue === null) {\n        setLocalState(messageState);\n      }\n    }\n    // Otherwise fall back to initial value if we have one and no user changes\n    else if (\n      cachedInitialValue !== undefined &&\n      !localState &&\n      lastUserValue === null\n    ) {\n      setLocalState(cachedInitialValue);\n    }\n  }, [\n    keyName,\n    message?.componentState,\n    cachedInitialValue,\n    lastUserValue,\n    localState,\n  ]);\n\n  // Create debounced save function for efficient server synchronization\n  const debouncedServerWrite = useDebouncedCallback(async (newValue: S) => {\n    if (!message) {\n      console.warn(\n        `Cannot update missing message ${messageId} for state key \"${keyName}\"`,\n      );\n      return;\n    }\n\n    setIsPending(true);\n    try {\n      const messageUpdate = {\n        ...message,\n        componentState: {\n          ...message.componentState,\n          [keyName]: newValue,\n        },\n      };\n\n      const componentStateUpdate = {\n        state: { [keyName]: newValue },\n      };\n\n      await Promise.all([\n        updateThreadMessage(messageId, messageUpdate, false),\n        client.beta.threads.messages.updateComponentState(\n          threadId,\n          messageId,\n          componentStateUpdate,\n        ),\n      ]);\n    } catch (err) {\n      console.error(\n        `Failed to save component state for key \"${keyName}\":`,\n        err,\n      );\n    } finally {\n      setIsPending(false);\n    }\n  }, debounceTime);\n\n  // Initialize state on first render if needed\n  const initializeState = useCallback(async () => {\n    if (!message) {\n      console.warn(\n        `Cannot initialize state for missing message ${messageId} with key \"${keyName}\"`,\n      );\n      return;\n    }\n\n    try {\n      const messageUpdate = {\n        ...message,\n        componentState: {\n          ...message.componentState,\n          [keyName]: cachedInitialValue,\n        },\n      };\n\n      const componentStateUpdate = {\n        state: { [keyName]: cachedInitialValue },\n      };\n\n      await Promise.all([\n        updateThreadMessage(messageId, messageUpdate, false),\n        client.beta.threads.messages.updateComponentState(\n          threadId,\n          messageId,\n          componentStateUpdate,\n        ),\n      ]);\n    } catch (err) {\n      console.warn(\n        `Failed to initialize component state for key \"${keyName}\":`,\n        err,\n      );\n    }\n  }, [\n    cachedInitialValue,\n    client.beta.threads.messages,\n    keyName,\n    message,\n    messageId,\n    threadId,\n    updateThreadMessage,\n  ]);\n\n  // Send initial state when component mounts\n  useEffect(() => {\n    if (shouldInitialize) {\n      initializeState();\n      setHaveInitialized(true);\n    }\n  }, [initializeState, shouldInitialize]);\n\n  // setValue function for updating state\n  // Updates local state immediately and schedules debounced server sync\n  const setValue = useCallback(\n    (newValue: S) => {\n      // Track this as a user-initiated update\n      setLastUserValue(newValue);\n      setLocalState(newValue);\n\n      // Only trigger server updates if we have a message\n      if (message) {\n        debouncedServerWrite(newValue);\n      } else {\n        console.warn(\n          `Cannot update server for missing message ${messageId} with key \"${keyName}\"`,\n        );\n      }\n    },\n    [debouncedServerWrite, message, messageId, keyName],\n  );\n\n  // Ensure pending changes are flushed on unmount\n  useEffect(() => {\n    return () => {\n      debouncedServerWrite.flush();\n    };\n  }, [debouncedServerWrite]);\n\n  // Return the local state for immediate UI rendering\n  return [localState as S, setValue, { isPending }];\n}\n"]}
+{"version":3,"file":"use-component-state.js","sourceRoot":"","sources":["../../src/hooks/use-component-state.tsx"],"names":[],"mappings":"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","sourcesContent":["import { useCallback, useEffect, useState } from \"react\";\nimport { useDebouncedCallback } from \"use-debounce\";\nimport { useTamboClient, useTamboThread } from \"../providers\";\nimport {\n  useTamboCurrentMessage,\n  useTamboMessageContext,\n} from \"./use-current-message\";\n// Define metadata interface for better extensibility\ninterface ComponentStateMeta {\n  isPending: boolean;\n}\n\ntype StateUpdateResult<T> = [\n  currentState: T,\n  setState: (newState: T) => void,\n  meta: ComponentStateMeta,\n];\n\n/**\n * A React hook that provides state management and passes user updates to Tambo.\n * Benefits: Passes user changes to AI, and when threads are returned, state is preserved.\n * @param keyName - The unique key to identify this state within the message's componentState object\n * @param initialValue - Optional initial value for the state, used if no value exists in the message\n * @param debounceTime - Optional debounce time in milliseconds (default: 300ms) to limit API calls\n * @returns A tuple containing:\n *   - The current state value\n *   - A setter function to update the state (updates UI immediately, debounces server sync)\n *   - A metadata object with properties like isPending to track sync status\n * @example\n * // Basic usage\n * const [count, setCount, { isPending }] = useTamboComponentState(\"counter\", 0);\n *\n * // Usage with object state\n * const [formState, setFormState] = useTamboComponentState(\"myForm\", {\n *   name: \"\",\n *   email: \"\",\n *   message: \"\"\n * });\n *\n * // Handling form input\n * const handleChange = (e) => {\n *   setFormState({\n *     ...formState,\n *     [e.target.name]: e.target.value\n *   });\n * };\n */\nexport function useTamboComponentState<S = undefined>(\n  keyName: string,\n  initialValue?: S,\n  debounceTime?: number,\n): StateUpdateResult<S | undefined>;\nexport function useTamboComponentState<S>(\n  keyName: string,\n  initialValue: S,\n  debounceTime?: number,\n): StateUpdateResult<S>;\n// eslint-disable-next-line jsdoc/require-jsdoc\nexport function useTamboComponentState<S>(\n  keyName: string,\n  initialValue?: S,\n  debounceTime = 500,\n): StateUpdateResult<S> {\n  const { threadId, messageId } = useTamboMessageContext();\n  const { updateThreadMessage } = useTamboThread();\n  const client = useTamboClient();\n  const message = useTamboCurrentMessage();\n\n  // Initial value management\n  const [cachedInitialValue] = useState(() => initialValue);\n  // UI state management\n  const [localState, setLocalState] = useState<S | undefined>(\n    cachedInitialValue,\n  );\n  // Synchronization state\n  const [isPending, setIsPending] = useState(false);\n  // Track the last user-initiated value instead of a simple boolean flag\n  const [lastUserValue, setLastUserValue] = useState<S | null>(null);\n  const [haveInitialized, setHaveInitialized] = useState(false);\n\n  // Determine if we need to initialize state\n  const shouldInitialize =\n    !haveInitialized &&\n    message &&\n    cachedInitialValue !== undefined &&\n    (!message.componentState || !(keyName in message.componentState));\n\n  // Sync local state with message state on initial load and when message changes\n  useEffect(() => {\n    if (message?.componentState && keyName in message.componentState) {\n      const messageState = message.componentState[keyName] as S;\n\n      // Only update local state if we haven't had any user changes yet\n      if (lastUserValue === null) {\n        setLocalState(messageState);\n      }\n    }\n    // Otherwise fall back to initial value if we have one and no user changes\n    else if (\n      cachedInitialValue !== undefined &&\n      !localState &&\n      lastUserValue === null\n    ) {\n      setLocalState(cachedInitialValue);\n    }\n  }, [\n    keyName,\n    message?.componentState,\n    cachedInitialValue,\n    lastUserValue,\n    localState,\n  ]);\n\n  // Create debounced save function for efficient server synchronization\n  const debouncedServerWrite = useDebouncedCallback(async (newValue: S) => {\n    setIsPending(true);\n    try {\n      const componentStateUpdate = {\n        state: { [keyName]: newValue },\n      };\n\n      await client.beta.threads.messages.updateComponentState(\n        threadId,\n        messageId,\n        componentStateUpdate,\n      );\n    } catch (err) {\n      console.error(\n        `Failed to save component state for key \"${keyName}\":`,\n        err,\n      );\n    } finally {\n      setIsPending(false);\n    }\n  }, debounceTime);\n\n  // Initialize state on first render if needed\n  const initializeState = useCallback(async () => {\n    if (!message) {\n      console.warn(\n        `Cannot initialize state for missing message ${messageId} with key \"${keyName}\"`,\n      );\n      return;\n    }\n\n    try {\n      const messageUpdate = {\n        ...message,\n        componentState: {\n          ...message.componentState,\n          [keyName]: cachedInitialValue,\n        },\n      };\n\n      const componentStateUpdate = {\n        state: { [keyName]: cachedInitialValue },\n      };\n\n      await Promise.all([\n        updateThreadMessage(messageId, messageUpdate, false),\n        client.beta.threads.messages.updateComponentState(\n          threadId,\n          messageId,\n          componentStateUpdate,\n        ),\n      ]);\n    } catch (err) {\n      console.warn(\n        `Failed to initialize component state for key \"${keyName}\":`,\n        err,\n      );\n    }\n  }, [\n    cachedInitialValue,\n    client.beta.threads.messages,\n    keyName,\n    message,\n    messageId,\n    threadId,\n    updateThreadMessage,\n  ]);\n\n  // Send initial state when component mounts\n  useEffect(() => {\n    if (shouldInitialize) {\n      initializeState();\n      setHaveInitialized(true);\n    }\n  }, [initializeState, shouldInitialize]);\n\n  // setValue function for updating state\n  // Updates local state immediately and schedules debounced server sync\n  const setValue = useCallback(\n    (newValue: S) => {\n      // Track this as a user-initiated update\n      setLastUserValue(newValue);\n      setLocalState(newValue);\n\n      // Only trigger server updates if we have a message\n      if (message) {\n        debouncedServerWrite(newValue);\n        const messageUpdate = {\n          ...message,\n          componentState: {\n            ...message.componentState,\n            [keyName]: newValue,\n          },\n        };\n\n        updateThreadMessage(messageId, messageUpdate, false);\n      } else {\n        console.warn(\n          `Cannot update server for missing message ${messageId} with key \"${keyName}\"`,\n        );\n      }\n    },\n    [message, debouncedServerWrite, keyName, updateThreadMessage, messageId],\n  );\n\n  // Ensure pending changes are flushed on unmount\n  useEffect(() => {\n    return () => {\n      debouncedServerWrite.flush();\n    };\n  }, [debouncedServerWrite]);\n\n  // Return the local state for immediate UI rendering\n  return [localState as S, setValue, { isPending }];\n}\n"]}

package/esm/hooks/use-component-state.js

@@ -46,26 +46,12 @@ export function useTamboComponentState(keyName, initialValue, debounceTime = 500
     ]);
     // Create debounced save function for efficient server synchronization
     const debouncedServerWrite = useDebouncedCallback(async (newValue) => {
-        if (!message) {
-            console.warn(`Cannot update missing message ${messageId} for state key "${keyName}"`);
-            return;
-        }
         setIsPending(true);
         try {
-            const messageUpdate = {
-                ...message,
-                componentState: {
-                    ...message.componentState,
-                    [keyName]: newValue,
-                },
-            };
             const componentStateUpdate = {
                 state: { [keyName]: newValue },
             };
-            await Promise.all([
-                updateThreadMessage(messageId, messageUpdate, false),
-                client.beta.threads.messages.updateComponentState(threadId, messageId, componentStateUpdate),
-            ]);
+            await client.beta.threads.messages.updateComponentState(threadId, messageId, componentStateUpdate);
         }
         catch (err) {
             console.error(`Failed to save component state for key "${keyName}":`, err);
@@ -124,11 +110,19 @@ export function useTamboComponentState(keyName, initialValue, debounceTime = 500
         // Only trigger server updates if we have a message
         if (message) {
             debouncedServerWrite(newValue);
+            const messageUpdate = {
+                ...message,
+                componentState: {
+                    ...message.componentState,
+                    [keyName]: newValue,
+                },
+            };
+            updateThreadMessage(messageId, messageUpdate, false);
         }
         else {
             console.warn(`Cannot update server for missing message ${messageId} with key "${keyName}"`);
         }
-    }, [debouncedServerWrite, message, messageId, keyName]);
+    }, [message, debouncedServerWrite, keyName, updateThreadMessage, messageId]);
     // Ensure pending changes are flushed on unmount
     useEffect(() => {
         return () => {

package/esm/hooks/use-component-state.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-component-state.js","sourceRoot":"","sources":["../../src/hooks/use-component-state.tsx"],"names":[],"mappings":"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","sourcesContent":["import { useCallback, useEffect, useState } from \"react\";\nimport { useDebouncedCallback } from \"use-debounce\";\nimport { useTamboClient, useTamboThread } from \"../providers\";\nimport {\n  useTamboCurrentMessage,\n  useTamboMessageContext,\n} from \"./use-current-message\";\n// Define metadata interface for better extensibility\ninterface ComponentStateMeta {\n  isPending: boolean;\n}\n\ntype StateUpdateResult<T> = [\n  currentState: T,\n  setState: (newState: T) => void,\n  meta: ComponentStateMeta,\n];\n\n/**\n * A React hook that provides state management and passes user updates to Tambo.\n * Benefits: Passes user changes to AI, and when threads are returned, state is preserved.\n * @param keyName - The unique key to identify this state within the message's componentState object\n * @param initialValue - Optional initial value for the state, used if no value exists in the message\n * @param debounceTime - Optional debounce time in milliseconds (default: 300ms) to limit API calls\n * @returns A tuple containing:\n *   - The current state value\n *   - A setter function to update the state (updates UI immediately, debounces server sync)\n *   - A metadata object with properties like isPending to track sync status\n * @example\n * // Basic usage\n * const [count, setCount, { isPending }] = useTamboComponentState(\"counter\", 0);\n *\n * // Usage with object state\n * const [formState, setFormState] = useTamboComponentState(\"myForm\", {\n *   name: \"\",\n *   email: \"\",\n *   message: \"\"\n * });\n *\n * // Handling form input\n * const handleChange = (e) => {\n *   setFormState({\n *     ...formState,\n *     [e.target.name]: e.target.value\n *   });\n * };\n */\nexport function useTamboComponentState<S = undefined>(\n  keyName: string,\n  initialValue?: S,\n  debounceTime?: number,\n): StateUpdateResult<S | undefined>;\nexport function useTamboComponentState<S>(\n  keyName: string,\n  initialValue: S,\n  debounceTime?: number,\n): StateUpdateResult<S>;\n// eslint-disable-next-line jsdoc/require-jsdoc\nexport function useTamboComponentState<S>(\n  keyName: string,\n  initialValue?: S,\n  debounceTime = 500,\n): StateUpdateResult<S> {\n  const { threadId, messageId } = useTamboMessageContext();\n  const { updateThreadMessage } = useTamboThread();\n  const client = useTamboClient();\n  const message = useTamboCurrentMessage();\n\n  // Initial value management\n  const [cachedInitialValue] = useState(() => initialValue);\n  // UI state management\n  const [localState, setLocalState] = useState<S | undefined>(\n    cachedInitialValue,\n  );\n  // Synchronization state\n  const [isPending, setIsPending] = useState(false);\n  // Track the last user-initiated value instead of a simple boolean flag\n  const [lastUserValue, setLastUserValue] = useState<S | null>(null);\n  const [haveInitialized, setHaveInitialized] = useState(false);\n\n  // Determine if we need to initialize state\n  const shouldInitialize =\n    !haveInitialized &&\n    message &&\n    cachedInitialValue !== undefined &&\n    (!message.componentState || !(keyName in message.componentState));\n\n  // Sync local state with message state on initial load and when message changes\n  useEffect(() => {\n    if (message?.componentState && keyName in message.componentState) {\n      const messageState = message.componentState[keyName] as S;\n\n      // Only update local state if we haven't had any user changes yet\n      if (lastUserValue === null) {\n        setLocalState(messageState);\n      }\n    }\n    // Otherwise fall back to initial value if we have one and no user changes\n    else if (\n      cachedInitialValue !== undefined &&\n      !localState &&\n      lastUserValue === null\n    ) {\n      setLocalState(cachedInitialValue);\n    }\n  }, [\n    keyName,\n    message?.componentState,\n    cachedInitialValue,\n    lastUserValue,\n    localState,\n  ]);\n\n  // Create debounced save function for efficient server synchronization\n  const debouncedServerWrite = useDebouncedCallback(async (newValue: S) => {\n    if (!message) {\n      console.warn(\n        `Cannot update missing message ${messageId} for state key \"${keyName}\"`,\n      );\n      return;\n    }\n\n    setIsPending(true);\n    try {\n      const messageUpdate = {\n        ...message,\n        componentState: {\n          ...message.componentState,\n          [keyName]: newValue,\n        },\n      };\n\n      const componentStateUpdate = {\n        state: { [keyName]: newValue },\n      };\n\n      await Promise.all([\n        updateThreadMessage(messageId, messageUpdate, false),\n        client.beta.threads.messages.updateComponentState(\n          threadId,\n          messageId,\n          componentStateUpdate,\n        ),\n      ]);\n    } catch (err) {\n      console.error(\n        `Failed to save component state for key \"${keyName}\":`,\n        err,\n      );\n    } finally {\n      setIsPending(false);\n    }\n  }, debounceTime);\n\n  // Initialize state on first render if needed\n  const initializeState = useCallback(async () => {\n    if (!message) {\n      console.warn(\n        `Cannot initialize state for missing message ${messageId} with key \"${keyName}\"`,\n      );\n      return;\n    }\n\n    try {\n      const messageUpdate = {\n        ...message,\n        componentState: {\n          ...message.componentState,\n          [keyName]: cachedInitialValue,\n        },\n      };\n\n      const componentStateUpdate = {\n        state: { [keyName]: cachedInitialValue },\n      };\n\n      await Promise.all([\n        updateThreadMessage(messageId, messageUpdate, false),\n        client.beta.threads.messages.updateComponentState(\n          threadId,\n          messageId,\n          componentStateUpdate,\n        ),\n      ]);\n    } catch (err) {\n      console.warn(\n        `Failed to initialize component state for key \"${keyName}\":`,\n        err,\n      );\n    }\n  }, [\n    cachedInitialValue,\n    client.beta.threads.messages,\n    keyName,\n    message,\n    messageId,\n    threadId,\n    updateThreadMessage,\n  ]);\n\n  // Send initial state when component mounts\n  useEffect(() => {\n    if (shouldInitialize) {\n      initializeState();\n      setHaveInitialized(true);\n    }\n  }, [initializeState, shouldInitialize]);\n\n  // setValue function for updating state\n  // Updates local state immediately and schedules debounced server sync\n  const setValue = useCallback(\n    (newValue: S) => {\n      // Track this as a user-initiated update\n      setLastUserValue(newValue);\n      setLocalState(newValue);\n\n      // Only trigger server updates if we have a message\n      if (message) {\n        debouncedServerWrite(newValue);\n      } else {\n        console.warn(\n          `Cannot update server for missing message ${messageId} with key \"${keyName}\"`,\n        );\n      }\n    },\n    [debouncedServerWrite, message, messageId, keyName],\n  );\n\n  // Ensure pending changes are flushed on unmount\n  useEffect(() => {\n    return () => {\n      debouncedServerWrite.flush();\n    };\n  }, [debouncedServerWrite]);\n\n  // Return the local state for immediate UI rendering\n  return [localState as S, setValue, { isPending }];\n}\n"]}
+{"version":3,"file":"use-component-state.js","sourceRoot":"","sources":["../../src/hooks/use-component-state.tsx"],"names":[],"mappings":"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","sourcesContent":["import { useCallback, useEffect, useState } from \"react\";\nimport { useDebouncedCallback } from \"use-debounce\";\nimport { useTamboClient, useTamboThread } from \"../providers\";\nimport {\n  useTamboCurrentMessage,\n  useTamboMessageContext,\n} from \"./use-current-message\";\n// Define metadata interface for better extensibility\ninterface ComponentStateMeta {\n  isPending: boolean;\n}\n\ntype StateUpdateResult<T> = [\n  currentState: T,\n  setState: (newState: T) => void,\n  meta: ComponentStateMeta,\n];\n\n/**\n * A React hook that provides state management and passes user updates to Tambo.\n * Benefits: Passes user changes to AI, and when threads are returned, state is preserved.\n * @param keyName - The unique key to identify this state within the message's componentState object\n * @param initialValue - Optional initial value for the state, used if no value exists in the message\n * @param debounceTime - Optional debounce time in milliseconds (default: 300ms) to limit API calls\n * @returns A tuple containing:\n *   - The current state value\n *   - A setter function to update the state (updates UI immediately, debounces server sync)\n *   - A metadata object with properties like isPending to track sync status\n * @example\n * // Basic usage\n * const [count, setCount, { isPending }] = useTamboComponentState(\"counter\", 0);\n *\n * // Usage with object state\n * const [formState, setFormState] = useTamboComponentState(\"myForm\", {\n *   name: \"\",\n *   email: \"\",\n *   message: \"\"\n * });\n *\n * // Handling form input\n * const handleChange = (e) => {\n *   setFormState({\n *     ...formState,\n *     [e.target.name]: e.target.value\n *   });\n * };\n */\nexport function useTamboComponentState<S = undefined>(\n  keyName: string,\n  initialValue?: S,\n  debounceTime?: number,\n): StateUpdateResult<S | undefined>;\nexport function useTamboComponentState<S>(\n  keyName: string,\n  initialValue: S,\n  debounceTime?: number,\n): StateUpdateResult<S>;\n// eslint-disable-next-line jsdoc/require-jsdoc\nexport function useTamboComponentState<S>(\n  keyName: string,\n  initialValue?: S,\n  debounceTime = 500,\n): StateUpdateResult<S> {\n  const { threadId, messageId } = useTamboMessageContext();\n  const { updateThreadMessage } = useTamboThread();\n  const client = useTamboClient();\n  const message = useTamboCurrentMessage();\n\n  // Initial value management\n  const [cachedInitialValue] = useState(() => initialValue);\n  // UI state management\n  const [localState, setLocalState] = useState<S | undefined>(\n    cachedInitialValue,\n  );\n  // Synchronization state\n  const [isPending, setIsPending] = useState(false);\n  // Track the last user-initiated value instead of a simple boolean flag\n  const [lastUserValue, setLastUserValue] = useState<S | null>(null);\n  const [haveInitialized, setHaveInitialized] = useState(false);\n\n  // Determine if we need to initialize state\n  const shouldInitialize =\n    !haveInitialized &&\n    message &&\n    cachedInitialValue !== undefined &&\n    (!message.componentState || !(keyName in message.componentState));\n\n  // Sync local state with message state on initial load and when message changes\n  useEffect(() => {\n    if (message?.componentState && keyName in message.componentState) {\n      const messageState = message.componentState[keyName] as S;\n\n      // Only update local state if we haven't had any user changes yet\n      if (lastUserValue === null) {\n        setLocalState(messageState);\n      }\n    }\n    // Otherwise fall back to initial value if we have one and no user changes\n    else if (\n      cachedInitialValue !== undefined &&\n      !localState &&\n      lastUserValue === null\n    ) {\n      setLocalState(cachedInitialValue);\n    }\n  }, [\n    keyName,\n    message?.componentState,\n    cachedInitialValue,\n    lastUserValue,\n    localState,\n  ]);\n\n  // Create debounced save function for efficient server synchronization\n  const debouncedServerWrite = useDebouncedCallback(async (newValue: S) => {\n    setIsPending(true);\n    try {\n      const componentStateUpdate = {\n        state: { [keyName]: newValue },\n      };\n\n      await client.beta.threads.messages.updateComponentState(\n        threadId,\n        messageId,\n        componentStateUpdate,\n      );\n    } catch (err) {\n      console.error(\n        `Failed to save component state for key \"${keyName}\":`,\n        err,\n      );\n    } finally {\n      setIsPending(false);\n    }\n  }, debounceTime);\n\n  // Initialize state on first render if needed\n  const initializeState = useCallback(async () => {\n    if (!message) {\n      console.warn(\n        `Cannot initialize state for missing message ${messageId} with key \"${keyName}\"`,\n      );\n      return;\n    }\n\n    try {\n      const messageUpdate = {\n        ...message,\n        componentState: {\n          ...message.componentState,\n          [keyName]: cachedInitialValue,\n        },\n      };\n\n      const componentStateUpdate = {\n        state: { [keyName]: cachedInitialValue },\n      };\n\n      await Promise.all([\n        updateThreadMessage(messageId, messageUpdate, false),\n        client.beta.threads.messages.updateComponentState(\n          threadId,\n          messageId,\n          componentStateUpdate,\n        ),\n      ]);\n    } catch (err) {\n      console.warn(\n        `Failed to initialize component state for key \"${keyName}\":`,\n        err,\n      );\n    }\n  }, [\n    cachedInitialValue,\n    client.beta.threads.messages,\n    keyName,\n    message,\n    messageId,\n    threadId,\n    updateThreadMessage,\n  ]);\n\n  // Send initial state when component mounts\n  useEffect(() => {\n    if (shouldInitialize) {\n      initializeState();\n      setHaveInitialized(true);\n    }\n  }, [initializeState, shouldInitialize]);\n\n  // setValue function for updating state\n  // Updates local state immediately and schedules debounced server sync\n  const setValue = useCallback(\n    (newValue: S) => {\n      // Track this as a user-initiated update\n      setLastUserValue(newValue);\n      setLocalState(newValue);\n\n      // Only trigger server updates if we have a message\n      if (message) {\n        debouncedServerWrite(newValue);\n        const messageUpdate = {\n          ...message,\n          componentState: {\n            ...message.componentState,\n            [keyName]: newValue,\n          },\n        };\n\n        updateThreadMessage(messageId, messageUpdate, false);\n      } else {\n        console.warn(\n          `Cannot update server for missing message ${messageId} with key \"${keyName}\"`,\n        );\n      }\n    },\n    [message, debouncedServerWrite, keyName, updateThreadMessage, messageId],\n  );\n\n  // Ensure pending changes are flushed on unmount\n  useEffect(() => {\n    return () => {\n      debouncedServerWrite.flush();\n    };\n  }, [debouncedServerWrite]);\n\n  // Return the local state for immediate UI rendering\n  return [localState as S, setValue, { isPending }];\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tambo-ai/react",
-  "version": "0.19.3",
+  "version": "0.19.4",
   "description": "React client package for Tambo AI",
   "repository": {
     "type": "git",