@lantos1618/better-ui 0.2.3 → 0.4.0

package/dist/react/index.d.mts

@@ -0,0 +1,91 @@
+import { T as Tool, c as ToolContext } from '../tool-Ca2x-VNK.mjs';
+import 'zod';
+import 'react';
+
+interface UseToolOptions {
+    /** Auto-execute on mount or when input changes */
+    auto?: boolean;
+    /** Custom context overrides */
+    context?: Partial<ToolContext>;
+    /** Callback on success */
+    onSuccess?: (data: unknown) => void;
+    /** Callback on error */
+    onError?: (error: Error) => void;
+}
+interface UseToolResult<TInput, TOutput> {
+    /** The result data */
+    data: TOutput | null;
+    /** Loading state */
+    loading: boolean;
+    /** Error if any */
+    error: Error | null;
+    /** Execute the tool manually */
+    execute: (input?: TInput) => Promise<TOutput | null>;
+    /** Reset state */
+    reset: () => void;
+    /** Whether the tool has been executed at least once */
+    executed: boolean;
+}
+/**
+ * React hook for executing tools
+ *
+ * @example
+ * // Manual execution
+ * const { data, loading, execute } = useTool(weather);
+ * <button onClick={() => execute({ city: 'London' })}>Get Weather</button>
+ *
+ * @example
+ * // Auto execution when input changes
+ * const { data, loading } = useTool(weather, { city }, { auto: true });
+ *
+ * @example
+ * // With callbacks
+ * const { execute } = useTool(weather, undefined, {
+ *   onSuccess: (data) => console.log('Got weather:', data),
+ *   onError: (error) => console.error('Failed:', error),
+ * });
+ */
+declare function useTool<TInput, TOutput>(tool: Tool<TInput, TOutput>, initialInput?: TInput, options?: UseToolOptions): UseToolResult<TInput, TOutput>;
+/**
+ * React hook for executing multiple tools
+ *
+ * This hook properly manages state for multiple tools using a single useState,
+ * avoiding the hooks-in-loop anti-pattern.
+ *
+ * @example
+ * // Define tools outside component or memoize with useMemo
+ * const myTools = { weather, search };
+ *
+ * function MyComponent() {
+ *   const tools = useTools(myTools);
+ *   await tools.weather.execute({ city: 'London' });
+ *   await tools.search.execute({ query: 'restaurants' });
+ * }
+ */
+declare function useTools<T extends Record<string, Tool>>(tools: T, options?: UseToolOptions): {
+    [K in keyof T]: UseToolResult<T[K] extends Tool<infer I, any> ? I : never, T[K] extends Tool<any, infer O> ? O : never>;
+};
+
+interface UseToolStreamResult<TInput, TOutput> {
+    /** Progressive partial data (shallow-merged from stream callbacks) */
+    data: Partial<TOutput> | null;
+    /** Complete validated data when streaming finishes */
+    finalData: TOutput | null;
+    /** True while receiving partial streaming updates */
+    streaming: boolean;
+    /** True before first stream chunk arrives */
+    loading: boolean;
+    /** Error if any */
+    error: Error | null;
+    /** Execute the tool with streaming */
+    execute: (input: TInput) => Promise<TOutput | null>;
+    /** Reset all state */
+    reset: () => void;
+}
+declare function useToolStream<TInput, TOutput>(tool: Tool<TInput, TOutput>, options?: {
+    context?: Partial<ToolContext>;
+    onSuccess?: (data: TOutput) => void;
+    onError?: (error: Error) => void;
+}): UseToolStreamResult<TInput, TOutput>;
+
+export { type UseToolOptions, type UseToolResult, type UseToolStreamResult, useTool, useToolStream, useTools };

package/dist/react/index.d.ts

@@ -0,0 +1,91 @@
+import { T as Tool, c as ToolContext } from '../tool-Ca2x-VNK.js';
+import 'zod';
+import 'react';
+
+interface UseToolOptions {
+    /** Auto-execute on mount or when input changes */
+    auto?: boolean;
+    /** Custom context overrides */
+    context?: Partial<ToolContext>;
+    /** Callback on success */
+    onSuccess?: (data: unknown) => void;
+    /** Callback on error */
+    onError?: (error: Error) => void;
+}
+interface UseToolResult<TInput, TOutput> {
+    /** The result data */
+    data: TOutput | null;
+    /** Loading state */
+    loading: boolean;
+    /** Error if any */
+    error: Error | null;
+    /** Execute the tool manually */
+    execute: (input?: TInput) => Promise<TOutput | null>;
+    /** Reset state */
+    reset: () => void;
+    /** Whether the tool has been executed at least once */
+    executed: boolean;
+}
+/**
+ * React hook for executing tools
+ *
+ * @example
+ * // Manual execution
+ * const { data, loading, execute } = useTool(weather);
+ * <button onClick={() => execute({ city: 'London' })}>Get Weather</button>
+ *
+ * @example
+ * // Auto execution when input changes
+ * const { data, loading } = useTool(weather, { city }, { auto: true });
+ *
+ * @example
+ * // With callbacks
+ * const { execute } = useTool(weather, undefined, {
+ *   onSuccess: (data) => console.log('Got weather:', data),
+ *   onError: (error) => console.error('Failed:', error),
+ * });
+ */
+declare function useTool<TInput, TOutput>(tool: Tool<TInput, TOutput>, initialInput?: TInput, options?: UseToolOptions): UseToolResult<TInput, TOutput>;
+/**
+ * React hook for executing multiple tools
+ *
+ * This hook properly manages state for multiple tools using a single useState,
+ * avoiding the hooks-in-loop anti-pattern.
+ *
+ * @example
+ * // Define tools outside component or memoize with useMemo
+ * const myTools = { weather, search };
+ *
+ * function MyComponent() {
+ *   const tools = useTools(myTools);
+ *   await tools.weather.execute({ city: 'London' });
+ *   await tools.search.execute({ query: 'restaurants' });
+ * }
+ */
+declare function useTools<T extends Record<string, Tool>>(tools: T, options?: UseToolOptions): {
+    [K in keyof T]: UseToolResult<T[K] extends Tool<infer I, any> ? I : never, T[K] extends Tool<any, infer O> ? O : never>;
+};
+
+interface UseToolStreamResult<TInput, TOutput> {
+    /** Progressive partial data (shallow-merged from stream callbacks) */
+    data: Partial<TOutput> | null;
+    /** Complete validated data when streaming finishes */
+    finalData: TOutput | null;
+    /** True while receiving partial streaming updates */
+    streaming: boolean;
+    /** True before first stream chunk arrives */
+    loading: boolean;
+    /** Error if any */
+    error: Error | null;
+    /** Execute the tool with streaming */
+    execute: (input: TInput) => Promise<TOutput | null>;
+    /** Reset all state */
+    reset: () => void;
+}
+declare function useToolStream<TInput, TOutput>(tool: Tool<TInput, TOutput>, options?: {
+    context?: Partial<ToolContext>;
+    onSuccess?: (data: TOutput) => void;
+    onError?: (error: Error) => void;
+}): UseToolStreamResult<TInput, TOutput>;
+
+export { type UseToolOptions, type UseToolResult, type UseToolStreamResult, useTool, useToolStream, useTools };

package/dist/react/index.js

@@ -0,0 +1,284 @@
+"use strict";
+"use client";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/react/index.ts
+var react_exports = {};
+__export(react_exports, {
+  useTool: () => useTool,
+  useToolStream: () => useToolStream,
+  useTools: () => useTools
+});
+module.exports = __toCommonJS(react_exports);
+
+// src/react/useTool.ts
+var import_react = require("react");
+function useTool(tool, initialInput, options = {}) {
+  const [data, setData] = (0, import_react.useState)(null);
+  const [loading, setLoading] = (0, import_react.useState)(false);
+  const [error, setError] = (0, import_react.useState)(null);
+  const [executed, setExecuted] = (0, import_react.useState)(false);
+  const inputRef = (0, import_react.useRef)(initialInput);
+  const optionsRef = (0, import_react.useRef)(options);
+  optionsRef.current = options;
+  const executionIdRef = (0, import_react.useRef)(0);
+  const pendingCountRef = (0, import_react.useRef)(0);
+  const execute = (0, import_react.useCallback)(
+    async (input) => {
+      const finalInput = input ?? inputRef.current;
+      if (finalInput === void 0) {
+        const err = new Error("No input provided to tool");
+        setError(err);
+        optionsRef.current.onError?.(err);
+        return null;
+      }
+      const currentExecutionId = ++executionIdRef.current;
+      pendingCountRef.current++;
+      setLoading(true);
+      setError(null);
+      try {
+        const context = {
+          cache: /* @__PURE__ */ new Map(),
+          fetch: globalThis.fetch?.bind(globalThis),
+          isServer: false,
+          ...optionsRef.current.context
+        };
+        const result = await tool.run(finalInput, context);
+        if (currentExecutionId === executionIdRef.current) {
+          setData(result);
+          setExecuted(true);
+          optionsRef.current.onSuccess?.(result);
+        }
+        return result;
+      } catch (err) {
+        const error2 = err instanceof Error ? err : new Error(String(err));
+        if (currentExecutionId === executionIdRef.current) {
+          setError(error2);
+          optionsRef.current.onError?.(error2);
+        }
+        return null;
+      } finally {
+        pendingCountRef.current--;
+        if (pendingCountRef.current === 0) {
+          setLoading(false);
+        }
+      }
+    },
+    [tool]
+  );
+  const reset = (0, import_react.useCallback)(() => {
+    setData(null);
+    setError(null);
+    setLoading(false);
+    setExecuted(false);
+  }, []);
+  (0, import_react.useEffect)(() => {
+    if (options.auto && initialInput !== void 0) {
+      inputRef.current = initialInput;
+      execute(initialInput);
+    }
+  }, [options.auto, initialInput, execute]);
+  return {
+    data,
+    loading,
+    error,
+    execute,
+    reset,
+    executed
+  };
+}
+function useTools(tools, options = {}) {
+  const toolsRef = (0, import_react.useRef)(tools);
+  const optionsRef = (0, import_react.useRef)(options);
+  optionsRef.current = options;
+  if (process.env.NODE_ENV !== "production") {
+    const prevKeys = Object.keys(toolsRef.current);
+    const currKeys = Object.keys(tools);
+    if (prevKeys.length !== currKeys.length || !currKeys.every((k) => prevKeys.includes(k))) {
+      console.warn(
+        "useTools: The tools object keys changed between renders. This may cause unexpected behavior. Define tools outside the component or memoize with useMemo."
+      );
+    }
+    toolsRef.current = tools;
+  }
+  const [state, setState] = (0, import_react.useState)(() => {
+    const initial = {};
+    for (const name of Object.keys(tools)) {
+      initial[name] = {
+        data: null,
+        loading: false,
+        error: null,
+        executed: false
+      };
+    }
+    return initial;
+  });
+  const createExecute = (0, import_react.useCallback)(
+    (toolName, tool) => {
+      return async (input) => {
+        if (input === void 0) {
+          const err = new Error("No input provided to tool");
+          setState((prev) => ({
+            ...prev,
+            [toolName]: { ...prev[toolName], error: err }
+          }));
+          optionsRef.current.onError?.(err);
+          return null;
+        }
+        setState((prev) => ({
+          ...prev,
+          [toolName]: { ...prev[toolName], loading: true, error: null }
+        }));
+        try {
+          const context = {
+            cache: /* @__PURE__ */ new Map(),
+            fetch: globalThis.fetch?.bind(globalThis),
+            isServer: false,
+            ...optionsRef.current.context
+          };
+          const result = await tool.run(input, context);
+          setState((prev) => ({
+            ...prev,
+            [toolName]: {
+              data: result,
+              loading: false,
+              error: null,
+              executed: true
+            }
+          }));
+          optionsRef.current.onSuccess?.(result);
+          return result;
+        } catch (err) {
+          const error = err instanceof Error ? err : new Error(String(err));
+          setState((prev) => ({
+            ...prev,
+            [toolName]: { ...prev[toolName], loading: false, error }
+          }));
+          optionsRef.current.onError?.(error);
+          return null;
+        }
+      };
+    },
+    []
+  );
+  const createReset = (0, import_react.useCallback)((toolName) => {
+    return () => {
+      setState((prev) => ({
+        ...prev,
+        [toolName]: {
+          data: null,
+          loading: false,
+          error: null,
+          executed: false
+        }
+      }));
+    };
+  }, []);
+  const results = {};
+  for (const [name, tool] of Object.entries(tools)) {
+    const toolName = name;
+    const toolState = state[toolName];
+    results[toolName] = {
+      data: toolState?.data ?? null,
+      loading: toolState?.loading ?? false,
+      error: toolState?.error ?? null,
+      executed: toolState?.executed ?? false,
+      execute: createExecute(toolName, tool),
+      reset: createReset(toolName)
+      // Per-key type safety is enforced by the function's return type annotation.
+    };
+  }
+  return results;
+}
+
+// src/react/useToolStream.ts
+var import_react2 = require("react");
+function useToolStream(tool, options = {}) {
+  const [data, setData] = (0, import_react2.useState)(null);
+  const [finalData, setFinalData] = (0, import_react2.useState)(null);
+  const [streaming, setStreaming] = (0, import_react2.useState)(false);
+  const [loading, setLoading] = (0, import_react2.useState)(false);
+  const [error, setError] = (0, import_react2.useState)(null);
+  const executionIdRef = (0, import_react2.useRef)(0);
+  const optionsRef = (0, import_react2.useRef)(options);
+  optionsRef.current = options;
+  const execute = (0, import_react2.useCallback)(
+    async (input) => {
+      const currentId = ++executionIdRef.current;
+      setLoading(true);
+      setStreaming(false);
+      setError(null);
+      setData(null);
+      setFinalData(null);
+      try {
+        let accumulated = {};
+        let result = null;
+        let firstChunkReceived = false;
+        for await (const chunk of tool.runStream(input, {
+          isServer: false,
+          ...optionsRef.current.context
+        })) {
+          if (currentId !== executionIdRef.current) return null;
+          if (chunk.done) {
+            result = chunk.partial;
+            setFinalData(result);
+            setData(result);
+            setStreaming(false);
+            setLoading(false);
+            optionsRef.current.onSuccess?.(result);
+          } else {
+            if (!firstChunkReceived) {
+              firstChunkReceived = true;
+              setStreaming(true);
+              setLoading(false);
+            }
+            accumulated = { ...accumulated, ...chunk.partial };
+            setData({ ...accumulated });
+          }
+        }
+        setLoading(false);
+        setStreaming(false);
+        return result;
+      } catch (err) {
+        if (currentId !== executionIdRef.current) return null;
+        const e = err instanceof Error ? err : new Error(String(err));
+        setError(e);
+        setLoading(false);
+        setStreaming(false);
+        optionsRef.current.onError?.(e);
+        return null;
+      }
+    },
+    [tool]
+  );
+  const reset = (0, import_react2.useCallback)(() => {
+    setData(null);
+    setFinalData(null);
+    setStreaming(false);
+    setLoading(false);
+    setError(null);
+  }, []);
+  return { data, finalData, streaming, loading, error, execute, reset };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useTool,
+  useToolStream,
+  useTools
+});