@frontmcp/ui 0.5.0 → 0.6.0

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

@@ -0,0 +1,284 @@
+/**
+ * @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>;
+//# sourceMappingURL=tools.d.ts.map

package/esm/react/hooks/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../../src/react/hooks/tools.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AASH;;GAEG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC,GAAG,OAAO;IACpC,uBAAuB;IACvB,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;IACf,8CAA8C;IAC9C,OAAO,EAAE,OAAO,CAAC;IACjB,8BAA8B;IAC9B,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,qDAAqD;IACrD,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,uDAAuD;IACvD,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,4CAA4C;IAC5C,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IACpC,yCAAyC;IACzC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,CAAC,MAAM,SAAS,MAAM,EAAE,OAAO,IAAI;IAC9D,gCAAgC;IAChC,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IACzC,yBAAyB;IACzB,SAAS,CAAC,OAAO,CAAC;IAClB,oCAAoC;IACpC,MAAM,IAAI;CACX,CAAC;AAMF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,IAAI,CAYnF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,aAAa,CAAC,CAAC,GAAG,OAAO,KAAK,CAAC,GAAG,IAAI,CA0BrD;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,GAAG,OAAO,KAAK,CAAC,GAAG,IAAI,CAgB5D;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,wBAAgB,WAAW,CAAC,MAAM,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,EAC5F,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,kBAAuB,GAC/B,iBAAiB,CAAC,MAAM,EAAE,OAAO,CAAC,CAgFpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC3D,OAAO,EAAE,CAAC,GACT;KACA,CAAC,IAAI,MAAM,CAAC,GAAG;QACd,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;QAC1D,IAAI,EAAE,OAAO,CAAC;QACd,OAAO,EAAE,OAAO,CAAC;QACjB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;QACpB,KAAK,EAAE,MAAM,IAAI,CAAC;KACnB;CACF,CAuFA;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,IAAI;IAChC,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC;IAClC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE;CACzD,CA6BA;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,IAAI,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAc5D"}

package/esm/react/index.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @file index.ts
+ * @description React components and hooks for FrontMCP UI.
+ *
+ * These are pure React components that can be used:
+ * 1. As regular React components in your app
+ * 2. To generate static HTML via render functions
+ * 3. With hooks to access the MCP bridge
+ *
+ * @example React usage
+ * ```tsx
+ * import { Card, Badge, Button, Alert } from '@frontmcp/ui/react';
+ *
+ * function App() {
+ *   return (
+ *     <Card title="Welcome" variant="elevated">
+ *       <Badge variant="success">New</Badge>
+ *       <p>Card content here</p>
+ *       <Button variant="primary">Click Me</Button>
+ *     </Card>
+ *   );
+ * }
+ * ```
+ *
+ * @example Static HTML generation
+ * ```typescript
+ * import { renderCard, renderBadge } from '@frontmcp/ui/react';
+ *
+ * const cardHtml = await renderCard({
+ *   title: 'Welcome',
+ *   variant: 'elevated',
+ *   children: '<p>Content</p>',
+ * });
+ * ```
+ *
+ * @example Using hooks with the MCP bridge
+ * ```tsx
+ * import {
+ *   McpBridgeProvider,
+ *   useMcpBridge,
+ *   useToolInput,
+ *   useCallTool,
+ *   useTheme,
+ * } from '@frontmcp/ui/react';
+ *
+ * function App() {
+ *   return (
+ *     <McpBridgeProvider>
+ *       <WeatherWidget />
+ *     </McpBridgeProvider>
+ *   );
+ * }
+ *
+ * function WeatherWidget() {
+ *   const input = useToolInput<{ location: string }>();
+ *   const theme = useTheme();
+ *   const [getWeather, { data, loading }] = useCallTool('get_weather');
+ *
+ *   return (
+ *     <Card title={`Weather for ${input?.location}`} variant={theme === 'dark' ? 'elevated' : 'default'}>
+ *       {loading ? 'Loading...' : data?.temperature}
+ *     </Card>
+ *   );
+ * }
+ * ```
+ *
+ * @module @frontmcp/ui/react
+ */
+export { Card, renderCard, renderCardSync } from './Card';
+export { Badge, renderBadge, renderBadgeSync } from './Badge';
+export { Button, renderButton, renderButtonSync } from './Button';
+export { Alert, renderAlert, renderAlertSync } from './Alert';
+export { McpBridgeProvider, useMcpBridgeContext, useMcpBridge, useTheme, useDisplayMode, useHostContext, useCapability, useToolInput, useToolOutput, useStructuredContent, useCallTool, useToolCalls, useSendMessage, useOpenLink, type McpBridgeContextValue, type McpBridgeProviderProps, type ToolState, type UseCallToolOptions, type UseCallToolReturn, } from './hooks';
+export type { CardProps, CardRenderProps, CardVariant, CardSize } from './Card';
+export type { BadgeProps, BadgeRenderProps, BadgeVariant, BadgeSize } from './Badge';
+export type { ButtonProps, ButtonRenderProps, ButtonVariant, ButtonSize } from './Button';
+export type { AlertProps, AlertRenderProps, AlertVariant } from './Alert';
+export type { FmcpCard, FmcpBadge, FmcpButton, FmcpAlert } from './types';
+export type { CardOptions, BadgeOptions, ButtonOptions, AlertOptions } from './types';
+export { renderChildrenToString, isBrowser, isServer } from './utils';
+//# sourceMappingURL=index.d.ts.map

package/esm/react/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/react/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AAGH,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAC1D,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC9D,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAClE,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAG9D,OAAO,EAEL,iBAAiB,EAEjB,mBAAmB,EACnB,YAAY,EACZ,QAAQ,EACR,cAAc,EACd,cAAc,EACd,aAAa,EAEb,YAAY,EACZ,aAAa,EACb,oBAAoB,EACpB,WAAW,EACX,YAAY,EACZ,cAAc,EACd,WAAW,EAEX,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,SAAS,EACd,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,GACvB,MAAM,SAAS,CAAC;AAGjB,YAAY,EAAE,SAAS,EAAE,eAAe,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAChF,YAAY,EAAE,UAAU,EAAE,gBAAgB,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACrF,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC1F,YAAY,EAAE,UAAU,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAM1E,YAAY,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAG1E,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAGtF,OAAO,EAAE,sBAAsB,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC"}