@frontmcp/ui 0.5.0

package/src/react/hooks/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @file index.ts
+ * @description React hooks for FrontMCP bridge and tools.
+ *
+ * @example Provider setup
+ * ```tsx
+ * import { McpBridgeProvider } from '@frontmcp/ui/react';
+ *
+ * function App() {
+ *   return (
+ *     <McpBridgeProvider>
+ *       <MyWidget />
+ *     </McpBridgeProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example Using hooks
+ * ```tsx
+ * import {
+ *   useMcpBridge,
+ *   useToolInput,
+ *   useToolOutput,
+ *   useCallTool,
+ *   useTheme,
+ * } from '@frontmcp/ui/react';
+ *
+ * function MyWidget() {
+ *   const bridge = useMcpBridge();
+ *   const input = useToolInput<{ location: string }>();
+ *   const theme = useTheme();
+ *   const [callTool, { data, loading }] = useCallTool('my_tool');
+ *
+ *   return <div>...</div>;
+ * }
+ * ```
+ *
+ * @module @frontmcp/ui/react/hooks
+ */
+export { McpBridgeProvider, useMcpBridgeContext, useMcpBridge, useTheme, useDisplayMode, useHostContext, useCapability, type McpBridgeContextValue, type McpBridgeProviderProps, } from './context';
+export { useToolInput, useToolOutput, useStructuredContent, useCallTool, useToolCalls, useSendMessage, useOpenLink, type ToolState, type UseCallToolOptions, type UseCallToolReturn, } from './tools';

package/src/react/hooks/index.js

@@ -0,0 +1,61 @@
+"use strict";
+/**
+ * @file index.ts
+ * @description React hooks for FrontMCP bridge and tools.
+ *
+ * @example Provider setup
+ * ```tsx
+ * import { McpBridgeProvider } from '@frontmcp/ui/react';
+ *
+ * function App() {
+ *   return (
+ *     <McpBridgeProvider>
+ *       <MyWidget />
+ *     </McpBridgeProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example Using hooks
+ * ```tsx
+ * import {
+ *   useMcpBridge,
+ *   useToolInput,
+ *   useToolOutput,
+ *   useCallTool,
+ *   useTheme,
+ * } from '@frontmcp/ui/react';
+ *
+ * function MyWidget() {
+ *   const bridge = useMcpBridge();
+ *   const input = useToolInput<{ location: string }>();
+ *   const theme = useTheme();
+ *   const [callTool, { data, loading }] = useCallTool('my_tool');
+ *
+ *   return <div>...</div>;
+ * }
+ * ```
+ *
+ * @module @frontmcp/ui/react/hooks
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useOpenLink = exports.useSendMessage = exports.useToolCalls = exports.useCallTool = exports.useStructuredContent = exports.useToolOutput = exports.useToolInput = exports.useCapability = exports.useHostContext = exports.useDisplayMode = exports.useTheme = exports.useMcpBridge = exports.useMcpBridgeContext = exports.McpBridgeProvider = void 0;
+// Context and Provider
+var context_1 = require("./context");
+Object.defineProperty(exports, "McpBridgeProvider", { enumerable: true, get: function () { return context_1.McpBridgeProvider; } });
+Object.defineProperty(exports, "useMcpBridgeContext", { enumerable: true, get: function () { return context_1.useMcpBridgeContext; } });
+Object.defineProperty(exports, "useMcpBridge", { enumerable: true, get: function () { return context_1.useMcpBridge; } });
+Object.defineProperty(exports, "useTheme", { enumerable: true, get: function () { return context_1.useTheme; } });
+Object.defineProperty(exports, "useDisplayMode", { enumerable: true, get: function () { return context_1.useDisplayMode; } });
+Object.defineProperty(exports, "useHostContext", { enumerable: true, get: function () { return context_1.useHostContext; } });
+Object.defineProperty(exports, "useCapability", { enumerable: true, get: function () { return context_1.useCapability; } });
+// Tool Hooks
+var tools_1 = require("./tools");
+Object.defineProperty(exports, "useToolInput", { enumerable: true, get: function () { return tools_1.useToolInput; } });
+Object.defineProperty(exports, "useToolOutput", { enumerable: true, get: function () { return tools_1.useToolOutput; } });
+Object.defineProperty(exports, "useStructuredContent", { enumerable: true, get: function () { return tools_1.useStructuredContent; } });
+Object.defineProperty(exports, "useCallTool", { enumerable: true, get: function () { return tools_1.useCallTool; } });
+Object.defineProperty(exports, "useToolCalls", { enumerable: true, get: function () { return tools_1.useToolCalls; } });
+Object.defineProperty(exports, "useSendMessage", { enumerable: true, get: function () { return tools_1.useSendMessage; } });
+Object.defineProperty(exports, "useOpenLink", { enumerable: true, get: function () { return tools_1.useOpenLink; } });
+//# sourceMappingURL=index.js.map

package/src/react/hooks/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/react/hooks/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;;;AAEH,uBAAuB;AACvB,qCAUmB;AATjB,4GAAA,iBAAiB,OAAA;AACjB,8GAAA,mBAAmB,OAAA;AACnB,uGAAA,YAAY,OAAA;AACZ,mGAAA,QAAQ,OAAA;AACR,yGAAA,cAAc,OAAA;AACd,yGAAA,cAAc,OAAA;AACd,wGAAA,aAAa,OAAA;AAKf,aAAa;AACb,iCAWiB;AAVf,qGAAA,YAAY,OAAA;AACZ,sGAAA,aAAa,OAAA;AACb,6GAAA,oBAAoB,OAAA;AACpB,oGAAA,WAAW,OAAA;AACX,qGAAA,YAAY,OAAA;AACZ,uGAAA,cAAc,OAAA;AACd,oGAAA,WAAW,OAAA","sourcesContent":["/**\n * @file index.ts\n * @description React hooks for FrontMCP bridge and tools.\n *\n * @example Provider setup\n * ```tsx\n * import { McpBridgeProvider } from '@frontmcp/ui/react';\n *\n * function App() {\n *   return (\n *     <McpBridgeProvider>\n *       <MyWidget />\n *     </McpBridgeProvider>\n *   );\n * }\n * ```\n *\n * @example Using hooks\n * ```tsx\n * import {\n *   useMcpBridge,\n *   useToolInput,\n *   useToolOutput,\n *   useCallTool,\n *   useTheme,\n * } from '@frontmcp/ui/react';\n *\n * function MyWidget() {\n *   const bridge = useMcpBridge();\n *   const input = useToolInput<{ location: string }>();\n *   const theme = useTheme();\n *   const [callTool, { data, loading }] = useCallTool('my_tool');\n *\n *   return <div>...</div>;\n * }\n * ```\n *\n * @module @frontmcp/ui/react/hooks\n */\n\n// Context and Provider\nexport {\n  McpBridgeProvider,\n  useMcpBridgeContext,\n  useMcpBridge,\n  useTheme,\n  useDisplayMode,\n  useHostContext,\n  useCapability,\n  type McpBridgeContextValue,\n  type McpBridgeProviderProps,\n} from './context';\n\n// Tool Hooks\nexport {\n  useToolInput,\n  useToolOutput,\n  useStructuredContent,\n  useCallTool,\n  useToolCalls,\n  useSendMessage,\n  useOpenLink,\n  type ToolState,\n  type UseCallToolOptions,\n  type UseCallToolReturn,\n} from './tools';\n"]}

package/src/react/hooks/tools.d.ts

@@ -0,0 +1,283 @@
+/**
+ * @file tools.tsx
+ * @description React hooks for MCP tool interactions.
+ *
+ * Provides hooks for calling tools, accessing tool input/output,
+ * and managing tool execution state.
+ *
+ * @example
+ * ```tsx
+ * import { useCallTool, useToolInput, useToolOutput } from '@frontmcp/ui/react';
+ *
+ * function WeatherWidget() {
+ *   const input = useToolInput<{ location: string }>();
+ *   const output = useToolOutput<WeatherData>();
+ *   const [callWeather, { data, loading, error }] = useCallTool<WeatherData>('get_weather');
+ *
+ *   return (
+ *     <div>
+ *       <p>Location: {input?.location}</p>
+ *       <button onClick={() => callWeather({ location: 'NYC' })}>
+ *         Get Weather
+ *       </button>
+ *       {loading && <p>Loading...</p>}
+ *       {data && <p>Temperature: {data.temperature}</p>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @module @frontmcp/ui/react/hooks
+ */
+/**
+ * State for tool execution.
+ */
+export interface ToolState<T = unknown> {
+    /** Tool result data */
+    data: T | null;
+    /** Whether the tool is currently executing */
+    loading: boolean;
+    /** Execution error, if any */
+    error: Error | null;
+    /** Whether the tool has been called at least once */
+    called: boolean;
+}
+/**
+ * Options for useCallTool hook.
+ */
+export interface UseCallToolOptions {
+    /** Automatically reset state when tool name changes */
+    resetOnToolChange?: boolean;
+    /** Callback when tool execution succeeds */
+    onSuccess?: (data: unknown) => void;
+    /** Callback when tool execution fails */
+    onError?: (error: Error) => void;
+}
+/**
+ * Return type for useCallTool hook.
+ */
+export type UseCallToolReturn<TInput extends object, TOutput> = [
+    /** Function to call the tool */
+    (args: TInput) => Promise<TOutput | null>,
+    /** Current tool state */
+    ToolState<TOutput>,
+    /** Reset state to initial values */
+    () => void
+];
+/**
+ * Hook to get the current tool input arguments.
+ * Returns the arguments passed to the tool when it was invoked.
+ *
+ * @typeParam T - Expected shape of the tool input
+ *
+ * @example
+ * ```tsx
+ * interface WeatherInput {
+ *   location: string;
+ *   units?: 'celsius' | 'fahrenheit';
+ * }
+ *
+ * function WeatherWidget() {
+ *   const input = useToolInput<WeatherInput>();
+ *
+ *   return (
+ *     <div>
+ *       <h1>Weather for {input?.location}</h1>
+ *       <p>Units: {input?.units ?? 'celsius'}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useToolInput<T extends object = Record<string, unknown>>(): T | null;
+/**
+ * Hook to get the current tool output/result.
+ * Returns the result data from the tool execution.
+ *
+ * @typeParam T - Expected shape of the tool output
+ *
+ * @example
+ * ```tsx
+ * interface WeatherOutput {
+ *   temperature: number;
+ *   condition: string;
+ *   humidity: number;
+ * }
+ *
+ * function WeatherDisplay() {
+ *   const output = useToolOutput<WeatherOutput>();
+ *
+ *   if (!output) return <div>No data</div>;
+ *
+ *   return (
+ *     <div>
+ *       <p>Temperature: {output.temperature}°</p>
+ *       <p>Condition: {output.condition}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useToolOutput<T = unknown>(): T | null;
+/**
+ * Hook to get the structured content from the tool output.
+ * This is the parsed/structured version of the tool result.
+ *
+ * @typeParam T - Expected shape of the structured content
+ *
+ * @example
+ * ```tsx
+ * interface WeatherData {
+ *   forecast: Array<{ day: string; temp: number }>;
+ * }
+ *
+ * function ForecastDisplay() {
+ *   const content = useStructuredContent<WeatherData>();
+ *
+ *   return (
+ *     <ul>
+ *       {content?.forecast.map(day => (
+ *         <li key={day.day}>{day.day}: {day.temp}°</li>
+ *       ))}
+ *     </ul>
+ *   );
+ * }
+ * ```
+ */
+export declare function useStructuredContent<T = unknown>(): T | null;
+/**
+ * Hook to call an MCP tool with loading and error state management.
+ *
+ * Returns a tuple with:
+ * 1. The call function
+ * 2. State object (data, loading, error, called)
+ * 3. Reset function
+ *
+ * @typeParam TInput - Shape of the tool input arguments
+ * @typeParam TOutput - Expected shape of the tool output
+ *
+ * @example Basic usage
+ * ```tsx
+ * function WeatherButton() {
+ *   const [getWeather, { data, loading, error }] = useCallTool<
+ *     { location: string },
+ *     { temperature: number; condition: string }
+ *   >('get_weather');
+ *
+ *   return (
+ *     <div>
+ *       <button
+ *         onClick={() => getWeather({ location: 'San Francisco' })}
+ *         disabled={loading}
+ *       >
+ *         {loading ? 'Loading...' : 'Get Weather'}
+ *       </button>
+ *       {error && <p className="error">{error.message}</p>}
+ *       {data && <p>{data.temperature}° - {data.condition}</p>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example With callbacks
+ * ```tsx
+ * function WeatherWidget() {
+ *   const [getWeather, state, reset] = useCallTool('get_weather', {
+ *     onSuccess: (data) => console.log('Got weather:', data),
+ *     onError: (err) => console.error('Failed:', err),
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => getWeather({ location: 'NYC' })}>
+ *         Get Weather
+ *       </button>
+ *       <button onClick={reset}>Reset</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useCallTool<TInput extends object = Record<string, unknown>, TOutput = unknown>(toolName: string, options?: UseCallToolOptions): UseCallToolReturn<TInput, TOutput>;
+/**
+ * Hook to manage multiple tool calls.
+ * Useful when you need to track state for multiple tools.
+ *
+ * @example
+ * ```tsx
+ * function MultiToolWidget() {
+ *   const tools = useToolCalls({
+ *     weather: 'get_weather',
+ *     news: 'get_news',
+ *     stocks: 'get_stocks',
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => tools.weather.call({ location: 'NYC' })}>
+ *         Get Weather
+ *       </button>
+ *       <button onClick={() => tools.news.call({ topic: 'tech' })}>
+ *         Get News
+ *       </button>
+ *       {tools.weather.loading && <p>Loading weather...</p>}
+ *       {tools.news.data && <p>News: {tools.news.data.headline}</p>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useToolCalls<T extends Record<string, string>>(toolMap: T): {
+    [K in keyof T]: {
+        call: (args: Record<string, unknown>) => Promise<unknown>;
+        data: unknown;
+        loading: boolean;
+        error: Error | null;
+        reset: () => void;
+    };
+};
+/**
+ * Hook to send a message to the conversation.
+ * Returns a function and state for sending messages.
+ *
+ * @example
+ * ```tsx
+ * function ChatWidget() {
+ *   const [sendMessage, { loading, error, sent }] = useSendMessage();
+ *
+ *   return (
+ *     <button
+ *       onClick={() => sendMessage('Here is the weather update!')}
+ *       disabled={loading}
+ *     >
+ *       {loading ? 'Sending...' : 'Send Update'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export declare function useSendMessage(): [
+    (content: string) => Promise<void>,
+    {
+        loading: boolean;
+        error: Error | null;
+        sent: boolean;
+    }
+];
+/**
+ * Hook to open external links via the bridge.
+ *
+ * @example
+ * ```tsx
+ * function LinkButton() {
+ *   const openLink = useOpenLink();
+ *
+ *   return (
+ *     <button onClick={() => openLink('https://example.com')}>
+ *       Open Website
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export declare function useOpenLink(): (url: string) => Promise<void>;