@leanmcp/ui 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,604 @@
+import React, { ReactNode, ButtonHTMLAttributes, HTMLAttributes, InputHTMLAttributes } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { McpUiAppCapabilities, App, McpUiHostContext } from '@modelcontextprotocol/ext-apps';
+export { App, McpUiAppCapabilities, McpUiHostContext, McpUiToolInputNotification, McpUiToolInputPartialNotification, McpUiToolResultNotification } from '@modelcontextprotocol/ext-apps';
+import { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { ChartData, ChartType as ChartType$1, ChartOptions } from 'chart.js';
+
+/**
+ * @UIApp Decorator
+ *
+ * Links an MCP tool to a React UI component.
+ * When applied to a tool method, it:
+ * 1. Adds _meta.ui/resourceUri to the tool definition
+ * 2. Auto-registers a resource that renders the component to HTML
+ *
+ * This decorator is designed to work with @leanmcp/core decorators.
+ */
+
+/**
+ * Options for @UIApp decorator
+ */
+interface UIAppOptions {
+    /** React component to render for this tool's UI */
+    component: React.ComponentType<any>;
+    /** Custom resource URI (auto-generated if not provided) */
+    uri?: string;
+    /** HTML document title */
+    title?: string;
+    /** Additional CSS styles */
+    styles?: string;
+}
+/**
+ * Decorator that links a tool to a UI component.
+ *
+ * When the tool is called, the host will fetch the UI resource
+ * which returns the component rendered as HTML.
+ *
+ * @example
+ * ```typescript
+ * import { Tool } from '@leanmcp/core';
+ * import { UIApp } from '@leanmcp/ui';
+ * import { WeatherCard } from './WeatherCard';
+ *
+ * class WeatherService {
+ *   @Tool({ description: 'Get weather for a city' })
+ *   @UIApp({ component: WeatherCard })
+ *   async getWeather(args: { city: string }) {
+ *     return { city: args.city, temp: 22 };
+ *   }
+ * }
+ * ```
+ */
+declare function UIApp(options: UIAppOptions): MethodDecorator;
+/**
+ * Helper to get UIApp metadata from a method
+ */
+declare function getUIAppMetadata(target: Function): UIAppOptions | undefined;
+/**
+ * Helper to get the resource URI from a method
+ */
+declare function getUIAppUri(target: Function): string | undefined;
+
+/**
+ * App information (same as ext-apps Implementation)
+ */
+interface AppInfo {
+    name: string;
+    version: string;
+}
+/**
+ * Options for App behavior
+ */
+interface AppOptions {
+    /**
+     * Automatically report size changes to the host using ResizeObserver.
+     * @default true
+     */
+    autoResize?: boolean;
+}
+/**
+ * MCP App context value - available via useMcpApp()
+ */
+interface McpAppContextValue {
+    /** The ext-apps App instance */
+    app: App | null;
+    /** Whether connected to host */
+    isConnected: boolean;
+    /** Connection error, if any */
+    error: Error | null;
+    /** Host context (theme, viewport, etc.) */
+    hostContext: McpUiHostContext;
+    /** Tool input arguments received from host */
+    toolInput: Record<string, unknown> | null;
+    /** Partial tool input (streaming) */
+    toolInputPartial: Record<string, unknown> | null;
+    /** Tool result received from host */
+    toolResult: CallToolResult | null;
+    /** Call a server tool */
+    callTool: (name: string, args?: Record<string, unknown>) => Promise<CallToolResult>;
+    /** Send a message to the host chat */
+    sendMessage: (text: string) => Promise<void>;
+    /** Send a log message */
+    sendLog: (level: 'debug' | 'info' | 'warning' | 'error', data: unknown) => Promise<void>;
+    /** Open a link in the host */
+    openLink: (url: string) => Promise<void>;
+}
+interface AppProviderProps {
+    /** App name and version */
+    appInfo: AppInfo;
+    /** App capabilities (tools, experimental features) */
+    capabilities?: McpUiAppCapabilities;
+    /** App options (autoResize, etc.) */
+    options?: AppOptions;
+    /** React children */
+    children: ReactNode;
+}
+/**
+ * AppProvider - Root context for MCP Apps
+ *
+ * Provides connection management and hooks for MCP App components.
+ * Uses PostMessage transport for iframe communication.
+ *
+ * @example
+ * ```tsx
+ * function MyApp() {
+ *   return (
+ *     <AppProvider
+ *       appInfo={{ name: "MyApp", version: "1.0.0" }}
+ *       capabilities={{ tools: { listChanged: true } }}
+ *       options={{ autoResize: true }}
+ *     >
+ *       <MyContent />
+ *     </AppProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function AppProvider({ appInfo, capabilities, options, children }: AppProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access the MCP App context
+ * Returns SSR-safe defaults when no provider is available (during server rendering)
+ */
+declare function useMcpApp(): McpAppContextValue;
+
+interface UseToolResult<T = unknown> {
+    /** Call the tool with arguments */
+    call: (args?: Record<string, unknown>) => Promise<T>;
+    /** Whether the tool is currently being called */
+    loading: boolean;
+    /** The result of the last tool call */
+    result: T | null;
+    /** Error from the last tool call */
+    error: Error | null;
+    /** Reset the result and error state */
+    reset: () => void;
+}
+/**
+ * Hook for calling an MCP tool with loading and error state
+ *
+ * @example
+ * ```tsx
+ * function WeatherWidget() {
+ *   const { call, loading, result, error } = useTool<WeatherData>('get-weather');
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => call({ city: 'London' })} disabled={loading}>
+ *         {loading ? 'Loading...' : 'Get Weather'}
+ *       </button>
+ *       {result && <div>Temperature: {result.temperature}°C</div>}
+ *       {error && <div>Error: {error.message}</div>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useTool<T = unknown>(toolName: string): UseToolResult<T>;
+
+interface UseToolResultReturn<T = unknown> {
+    /** The tool result, typed as T */
+    result: T | null;
+    /** Raw CallToolResult from MCP */
+    rawResult: CallToolResult | null;
+    /** Whether a result has been received */
+    hasResult: boolean;
+    /** Extract text content from result */
+    textContent: string | null;
+}
+/**
+ * Hook to access tool result from host
+ *
+ * @example
+ * ```tsx
+ * function WeatherCard() {
+ *   const { result } = useToolResult<{ city: string; temp: number }>();
+ *
+ *   if (!result) return <div>Loading...</div>;
+ *
+ *   return <div>{result.city}: {result.temp}°C</div>;
+ * }
+ * ```
+ */
+declare function useToolResult<T = unknown>(): UseToolResultReturn<T>;
+
+interface UseToolInputReturn<T = Record<string, unknown>> {
+    /** The tool input arguments, typed as T */
+    input: T | null;
+    /** Whether input has been received */
+    hasInput: boolean;
+}
+/**
+ * Hook to access tool input arguments from host
+ *
+ * @example
+ * ```tsx
+ * function WeatherCard() {
+ *   const { input } = useToolInput<{ city: string }>();
+ *
+ *   if (!input) return <div>Loading...</div>;
+ *
+ *   return <div>Weather for: {input.city}</div>;
+ * }
+ * ```
+ */
+declare function useToolInput<T = Record<string, unknown>>(): UseToolInputReturn<T>;
+
+interface UseToolInputPartialReturn {
+    /** Partial arguments currently available */
+    partialArgs: Record<string, unknown> | null;
+    /** Whether partial args are being received */
+    isStreaming: boolean;
+}
+/**
+ * Hook to access streaming partial tool input
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { partialArgs, isStreaming } = useToolInputPartial();
+ *
+ *   if (isStreaming) {
+ *     return <div>Receiving: {JSON.stringify(partialArgs)}</div>;
+ *   }
+ *   return <div>Ready for input</div>;
+ * }
+ * ```
+ */
+declare function useToolInputPartial(): UseToolInputPartialReturn;
+
+interface UseHostContextReturn {
+    /** Current theme: 'light' or 'dark' */
+    theme: 'light' | 'dark';
+    /** Display mode: 'inline', 'fullscreen', 'pip' */
+    displayMode: 'inline' | 'fullscreen' | 'pip';
+    /** Viewport dimensions */
+    viewport: {
+        width: number;
+        height: number;
+    } | null;
+    /** User locale (e.g., 'en-US') */
+    locale: string | null;
+    /** User timezone (e.g., 'America/New_York') */
+    timeZone: string | null;
+    /** Platform type */
+    platform: 'web' | 'desktop' | 'mobile' | null;
+    /** Full raw context */
+    rawContext: McpUiHostContext;
+}
+/**
+ * Hook to access host context
+ *
+ * @example
+ * ```tsx
+ * function ThemedCard() {
+ *   const { theme, locale } = useHostContext();
+ *
+ *   return (
+ *     <div className={theme === 'dark' ? 'dark-mode' : 'light-mode'}>
+ *       Locale: {locale}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useHostContext(): UseHostContextReturn;
+
+interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    /** Button variant */
+    variant?: 'primary' | 'secondary' | 'ghost' | 'destructive' | 'outline';
+    /** Button size */
+    size?: 'sm' | 'md' | 'lg' | 'icon';
+    /** Loading state */
+    loading?: boolean;
+    /** Render as child component (Radix Slot) */
+    asChild?: boolean;
+    /** Left icon */
+    leftIcon?: ReactNode;
+    /** Right icon */
+    rightIcon?: ReactNode;
+}
+/**
+ * Button component with multiple variants and loading state
+ *
+ * @example
+ * ```tsx
+ * <Button variant="primary" onClick={handleClick}>
+ *   Click Me
+ * </Button>
+ *
+ * <Button variant="ghost" loading>
+ *   Loading...
+ * </Button>
+ * ```
+ */
+declare const Button: React.ForwardRefExoticComponent<ButtonProps & React.RefAttributes<HTMLButtonElement>>;
+
+interface ActionButtonProps extends Omit<ButtonProps, 'onClick' | 'loading' | 'onError'> {
+    /** Tool name to call */
+    toolName: string;
+    /** Arguments to pass to the tool */
+    toolArgs?: Record<string, unknown>;
+    /** Callback when tool call succeeds */
+    onToolSuccess?: (result: unknown) => void;
+    /** Callback when tool call fails */
+    onToolError?: (error: Error) => void;
+    /** Show result inline after success */
+    showResult?: boolean;
+    /** Custom result renderer */
+    renderResult?: (result: unknown) => ReactNode;
+}
+/**
+ * ActionButton - Button that calls an MCP tool with loading state
+ *
+ * @example
+ * ```tsx
+ * <ActionButton
+ *   toolName="get-weather"
+ *   toolArgs={{ city: 'London' }}
+ *   onToolSuccess={(data) => console.log(data)}
+ * >
+ *   Get Weather
+ * </ActionButton>
+ * ```
+ */
+declare function ActionButton({ toolName, toolArgs, onToolSuccess, onToolError, showResult, renderResult, children, ...buttonProps }: ActionButtonProps): react_jsx_runtime.JSX.Element;
+
+interface ToolFormField {
+    /** Field name (matches tool input schema) */
+    name: string;
+    /** Display label */
+    label: string;
+    /** Input type */
+    type?: 'text' | 'number' | 'email' | 'password' | 'textarea';
+    /** Placeholder text */
+    placeholder?: string;
+    /** Default value */
+    defaultValue?: string | number;
+    /** Required field */
+    required?: boolean;
+    /** Helper text */
+    helperText?: string;
+}
+interface ToolFormProps {
+    /** Tool name to call on submit */
+    toolName: string;
+    /** Form fields */
+    fields: ToolFormField[];
+    /** Submit button text */
+    submitText?: string;
+    /** Callback when tool call succeeds */
+    onSuccess?: (result: unknown) => void;
+    /** Callback when tool call fails */
+    onError?: (error: Error) => void;
+    /** Show result after success */
+    showResult?: boolean;
+    /** Additional class name */
+    className?: string;
+}
+/**
+ * ToolForm - Auto-generates a form that submits to an MCP tool
+ *
+ * @example
+ * ```tsx
+ * <ToolForm
+ *   toolName="create-user"
+ *   fields={[
+ *     { name: 'name', label: 'Name', required: true },
+ *     { name: 'email', label: 'Email', type: 'email', required: true },
+ *   ]}
+ *   submitText="Create User"
+ *   onSuccess={(user) => console.log('Created:', user)}
+ * />
+ * ```
+ */
+declare function ToolForm({ toolName, fields, submitText, onSuccess, onError, showResult, className, }: ToolFormProps): react_jsx_runtime.JSX.Element;
+
+interface CardProps extends HTMLAttributes<HTMLDivElement> {
+    /** Card variant */
+    variant?: 'default' | 'outline' | 'elevated';
+    /** Padding size */
+    padding?: 'none' | 'sm' | 'md' | 'lg';
+    /** Make card interactive (hover effects) */
+    interactive?: boolean;
+}
+/**
+ * Card container component
+ */
+declare const Card: React.ForwardRefExoticComponent<CardProps & React.RefAttributes<HTMLDivElement>>;
+interface CardHeaderProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
+    /** Header title */
+    title?: ReactNode;
+    /** Header description */
+    description?: ReactNode;
+    /** Right-side action */
+    action?: ReactNode;
+}
+declare const CardHeader: React.ForwardRefExoticComponent<CardHeaderProps & React.RefAttributes<HTMLDivElement>>;
+interface CardContentProps extends HTMLAttributes<HTMLDivElement> {
+}
+declare const CardContent: React.ForwardRefExoticComponent<CardContentProps & React.RefAttributes<HTMLDivElement>>;
+interface CardFooterProps extends HTMLAttributes<HTMLDivElement> {
+}
+declare const CardFooter: React.ForwardRefExoticComponent<CardFooterProps & React.RefAttributes<HTMLDivElement>>;
+
+interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size'> {
+    /** Input label */
+    label?: string;
+    /** Helper text */
+    helperText?: string;
+    /** Error message */
+    error?: string;
+    /** Input size */
+    size?: 'sm' | 'md' | 'lg';
+    /** Left icon or element */
+    leftElement?: ReactNode;
+    /** Right icon or element */
+    rightElement?: ReactNode;
+    /** Full width */
+    fullWidth?: boolean;
+}
+/**
+ * Input component with label, validation, and icon support
+ *
+ * @example
+ * ```tsx
+ * <Input
+ *   label="Email"
+ *   type="email"
+ *   placeholder="Enter your email"
+ *   error={errors.email}
+ * />
+ * ```
+ */
+declare const Input: React.ForwardRefExoticComponent<InputProps & React.RefAttributes<HTMLInputElement>>;
+
+interface DataGridColumn<T> {
+    /** Column key (accessor) */
+    key: keyof T | string;
+    /** Column header */
+    header: string;
+    /** Custom cell renderer */
+    cell?: (value: unknown, row: T) => ReactNode;
+    /** Enable sorting */
+    sortable?: boolean;
+    /** Column width */
+    width?: number | string;
+}
+interface DataGridProps<T extends Record<string, unknown>> {
+    /** Data array */
+    data: T[];
+    /** Column definitions */
+    columns: DataGridColumn<T>[];
+    /** Enable global search */
+    searchable?: boolean;
+    /** Search placeholder */
+    searchPlaceholder?: string;
+    /** Row click handler */
+    onRowClick?: (row: T) => void;
+    /** Loading state */
+    loading?: boolean;
+    /** Empty state message */
+    emptyMessage?: string;
+    /** Additional class name */
+    className?: string;
+}
+/**
+ * DataGrid - Sortable, filterable data table for tool results
+ *
+ * @example
+ * ```tsx
+ * const { result } = useTool<{ items: Item[] }>('get-items');
+ *
+ * <DataGrid
+ *   data={result?.items ?? []}
+ *   columns={[
+ *     { key: 'name', header: 'Name', sortable: true },
+ *     { key: 'price', header: 'Price', cell: (v) => `$${v}` },
+ *   ]}
+ *   searchable
+ * />
+ * ```
+ */
+declare function DataGrid<T extends Record<string, unknown>>({ data, columns, searchable, searchPlaceholder, onRowClick, loading, emptyMessage, className, }: DataGridProps<T>): react_jsx_runtime.JSX.Element;
+
+type ChartType = 'line' | 'bar' | 'pie' | 'doughnut';
+interface ChartProps {
+    /** Chart type */
+    type: ChartType;
+    /** Chart data */
+    data: ChartData<ChartType$1>;
+    /** Chart options */
+    options?: ChartOptions<ChartType$1>;
+    /** Chart height */
+    height?: number | string;
+    /** Chart width */
+    width?: number | string;
+    /** Additional class name */
+    className?: string;
+}
+/**
+ * Chart component for data visualization
+ *
+ * @example
+ * ```tsx
+ * const { result } = useTool<{ prices: number[], labels: string[] }>('get-stock-data');
+ *
+ * <Chart
+ *   type="line"
+ *   data={{
+ *     labels: result?.labels ?? [],
+ *     datasets: [{
+ *       label: 'Price',
+ *       data: result?.prices ?? [],
+ *       borderColor: '#6366f1',
+ *       tension: 0.4,
+ *     }],
+ *   }}
+ *   height={300}
+ * />
+ * ```
+ */
+declare function Chart({ type, data, options, height, width, className, }: ChartProps): react_jsx_runtime.JSX.Element;
+
+interface AppShellProps extends HTMLAttributes<HTMLDivElement> {
+    /** Header content */
+    header?: ReactNode;
+    /** Sidebar content */
+    sidebar?: ReactNode;
+    /** Footer content */
+    footer?: ReactNode;
+    /** Sidebar position */
+    sidebarPosition?: 'left' | 'right';
+    /** Sidebar width */
+    sidebarWidth?: number | string;
+    /** Enable auto-resize to content */
+    autoResize?: boolean;
+    /** Padding */
+    padding?: 'none' | 'sm' | 'md' | 'lg';
+}
+/**
+ * AppShell - Root layout container for MCP Apps
+ *
+ * Provides header, sidebar, main content, and footer areas with auto-resize support.
+ *
+ * @example
+ * ```tsx
+ * <AppShell
+ *   header={<h1>My App</h1>}
+ *   sidebar={<Navigation />}
+ *   autoResize
+ * >
+ *   <MainContent />
+ * </AppShell>
+ * ```
+ */
+declare function AppShell({ header, sidebar, footer, sidebarPosition, sidebarWidth, autoResize, padding, className, children, ...props }: AppShellProps): react_jsx_runtime.JSX.Element;
+
+interface CodeBlockProps {
+    /** Code content */
+    code: string;
+    /** Programming language */
+    language?: string;
+    /** Show line numbers */
+    showLineNumbers?: boolean;
+    /** Enable copy button */
+    copyable?: boolean;
+    /** Additional class name */
+    className?: string;
+}
+/**
+ * CodeBlock - Syntax highlighted code display
+ *
+ * @example
+ * ```tsx
+ * <CodeBlock
+ *   code={`const greeting = "Hello, World!";`}
+ *   language="javascript"
+ *   copyable
+ * />
+ * ```
+ */
+declare function CodeBlock({ code, language, showLineNumbers, copyable, className, }: CodeBlockProps): react_jsx_runtime.JSX.Element;
+
+export { ActionButton, type ActionButtonProps, type AppInfo, type AppOptions, AppProvider, type AppProviderProps, AppShell, type AppShellProps, Button, type ButtonProps, Card, CardContent, type CardContentProps, CardFooter, type CardFooterProps, CardHeader, type CardHeaderProps, type CardProps, Chart, type ChartProps, type ChartType, CodeBlock, type CodeBlockProps, DataGrid, type DataGridColumn, type DataGridProps, Input, type InputProps, type McpAppContextValue, ToolForm, type ToolFormField, type ToolFormProps, UIApp, type UIAppOptions, type UseHostContextReturn, type UseToolInputPartialReturn, type UseToolInputReturn, type UseToolResult, type UseToolResultReturn, getUIAppMetadata, getUIAppUri, useHostContext, useMcpApp, useTool, useToolInput, useToolInputPartial, useToolResult };