@pancake-apps/web 0.0.1

package/dist/react/index.d.ts

@@ -0,0 +1,536 @@
+import * as React from 'react';
+import React__default, { ReactNode, ComponentType } from 'react';
+
+/**
+ * Host context provided by MCP or OpenAI hosts
+ */
+interface HostContext {
+    /** Current theme */
+    theme: 'light' | 'dark';
+    /** Current display mode */
+    displayMode: 'inline' | 'fullscreen' | 'pip';
+    /** Available display modes */
+    availableDisplayModes: string[];
+    /** Viewport dimensions */
+    viewport: {
+        width: number;
+        height: number;
+    };
+    /** User's locale (e.g., 'en-US') */
+    locale: string;
+    /** User's timezone */
+    timeZone: string;
+    /** Platform type */
+    platform: 'desktop' | 'mobile' | 'web';
+    /** Current view identifier (if applicable) */
+    view?: string;
+    /** Safe area insets for mobile */
+    safeAreaInsets?: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+}
+/**
+ * View parameters passed to the UI
+ */
+interface ViewParams<TInputs = unknown, TData = unknown> {
+    /** Input parameters passed to the view */
+    inputs: TInputs;
+    /** Data returned by the view handler */
+    data: TData;
+}
+/**
+ * Protocol types
+ */
+type Protocol = 'mcp' | 'openai' | 'mock';
+
+/**
+ * Protocol adapter interface.
+ * Abstracts communication with the host (MCP or OpenAI).
+ */
+interface ProtocolAdapter {
+    /** Protocol name */
+    readonly protocol: 'mcp' | 'openai' | 'mock';
+    /** Whether the adapter is connected */
+    isConnected(): boolean;
+    /** Connect to the host */
+    connect(): Promise<void>;
+    /** Disconnect from the host */
+    disconnect(): Promise<void>;
+    /** Get the current host context */
+    getHostContext(): HostContext;
+    /** Subscribe to host context changes */
+    onHostContextChange(handler: (ctx: HostContext) => void): () => void;
+    /** Get the current view parameters (inputs + data) */
+    getViewParams(): ViewParams;
+    /** Get the current tool input (what the model sent) */
+    getToolInput(): Record<string, unknown> | undefined;
+    /** Get the current tool output (what the handler returned) */
+    getToolOutput(): Record<string, unknown> | undefined;
+    /** Subscribe to tool input changes */
+    onToolInput(handler: (input: unknown) => void): () => void;
+    /** Subscribe to tool output changes */
+    onToolOutput(handler: (output: unknown) => void): () => void;
+    /** Call a tool on the server */
+    callTool(name: string, args: Record<string, unknown>): Promise<unknown>;
+    /** Send a message to the model */
+    sendMessage(content: {
+        type: string;
+        text: string;
+    }): Promise<void>;
+    /** Open a link in the host */
+    openLink(url: string): Promise<void>;
+    /** Request a display mode change */
+    requestDisplayMode(mode: 'inline' | 'fullscreen' | 'pip'): Promise<{
+        mode: string;
+    }>;
+    /** Request to close the UI */
+    requestClose(): void;
+    /** Get the current view state */
+    getState<T>(): T | null;
+    /** Set the view state */
+    setState<T>(state: T): void;
+    /** Subscribe to tool cancellation */
+    onToolCancelled(handler: (reason?: string) => void): () => void;
+    /** Subscribe to teardown */
+    onTeardown(handler: (reason?: string) => void): () => void;
+    /** Log a message */
+    log(level: 'debug' | 'info' | 'warn' | 'error', data: unknown): void;
+    /** Notify the host of a size change */
+    sendSizeChanged(params: {
+        width: number;
+        height: number;
+    }): Promise<void>;
+}
+
+/**
+ * Options for creating a Pancake client
+ */
+interface PancakeClientOptions {
+    /** Force a specific protocol adapter */
+    forceAdapter?: Protocol;
+    /** Enable auto-resize (default: true) */
+    autoResize?: boolean;
+    /** Initial tool input (for mock adapter) */
+    toolInput?: Record<string, unknown>;
+    /** Initial tool output (for mock adapter) */
+    toolOutput?: Record<string, unknown>;
+    /** Initial host context (for mock adapter) */
+    hostContext?: Partial<HostContext>;
+}
+/**
+ * Pancake client that wraps a protocol adapter.
+ */
+declare class PancakeClient {
+    private adapter;
+    private constructor();
+    /**
+     * Create and connect a Pancake client.
+     */
+    static create(options?: PancakeClientOptions): Promise<PancakeClient>;
+    /**
+     * Create a Pancake client with a pre-configured adapter.
+     */
+    static fromAdapter(adapter: ProtocolAdapter): PancakeClient;
+    /**
+     * Get the underlying protocol adapter.
+     */
+    getAdapter(): ProtocolAdapter;
+    /**
+     * Get the current protocol.
+     */
+    get protocol(): Protocol;
+    /**
+     * Check if the client is connected.
+     */
+    isConnected(): boolean;
+    /**
+     * Get the current host context.
+     */
+    getHostContext(): HostContext;
+    /**
+     * Subscribe to host context changes.
+     */
+    onHostContextChange(handler: (ctx: HostContext) => void): () => void;
+    /**
+     * Get the current view parameters.
+     */
+    getViewParams(): ViewParams;
+    /**
+     * Get the current tool input.
+     */
+    getToolInput(): Record<string, unknown> | undefined;
+    /**
+     * Get the current tool output.
+     */
+    getToolOutput(): Record<string, unknown> | undefined;
+    /**
+     * Subscribe to tool input changes.
+     */
+    onToolInput(handler: (input: unknown) => void): () => void;
+    /**
+     * Subscribe to tool output changes.
+     */
+    onToolOutput(handler: (output: unknown) => void): () => void;
+    /**
+     * Call a tool on the server.
+     */
+    callTool<T = unknown>(name: string, args?: Record<string, unknown>): Promise<T>;
+    /**
+     * Navigate to a view (calls view:name tool).
+     */
+    navigateToView(viewName: string, params?: Record<string, unknown>): Promise<void>;
+    /**
+     * Dispatch an action (calls action:name tool).
+     */
+    dispatch<T = unknown>(actionName: string, params?: Record<string, unknown>): Promise<T>;
+    /**
+     * Get data from a data fetcher (calls data:name tool).
+     */
+    getData<T = unknown>(dataName: string, params?: Record<string, unknown>): Promise<T>;
+    /**
+     * Send a message to the model.
+     */
+    say(message: string): Promise<void>;
+    /**
+     * Open a link in the host.
+     */
+    openLink(url: string): Promise<void>;
+    /**
+     * Request a display mode change.
+     */
+    requestDisplayMode(mode: 'inline' | 'fullscreen' | 'pip'): Promise<{
+        mode: string;
+    }>;
+    /**
+     * Request to close the UI.
+     */
+    requestClose(): void;
+    /**
+     * Get the current view state.
+     */
+    getState<T>(): T | null;
+    /**
+     * Set the view state.
+     */
+    setState<T>(state: T): void;
+    /**
+     * Subscribe to tool cancellation.
+     */
+    onToolCancelled(handler: (reason?: string) => void): () => void;
+    /**
+     * Subscribe to teardown.
+     */
+    onTeardown(handler: (reason?: string) => void): () => void;
+    /**
+     * Log a message.
+     */
+    log(level: 'debug' | 'info' | 'warn' | 'error', data: unknown): void;
+    /**
+     * Notify the host of a size change.
+     */
+    sendSizeChanged(params: {
+        width: number;
+        height: number;
+    }): Promise<void>;
+}
+
+/**
+ * Props for the PancakeProvider
+ */
+interface PancakeProviderProps {
+    children: ReactNode;
+    /** Pre-created client (optional) */
+    client?: PancakeClient;
+    /** Force a specific protocol adapter */
+    forceAdapter?: Protocol;
+    /** Enable auto-resize (default: true) */
+    autoResize?: boolean;
+    /** Initial host context (for testing) */
+    hostContext?: Partial<HostContext>;
+    /** Loading fallback UI */
+    fallback?: ReactNode;
+    /** Error fallback component */
+    errorFallback?: ComponentType<{
+        error: Error;
+        reset: () => void;
+    }>;
+}
+/**
+ * Provider component that initializes and provides the Pancake client.
+ *
+ * @example
+ * ```tsx
+ * import { PancakeProvider } from '@pancake-apps/web/react';
+ *
+ * function App() {
+ *   return (
+ *     <PancakeProvider>
+ *       <MyView />
+ *     </PancakeProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function PancakeProvider({ children, client: providedClient, forceAdapter, autoResize, hostContext, fallback, errorFallback: ErrorFallback, }: PancakeProviderProps): React__default.ReactElement;
+
+/**
+ * Context value for the Pancake provider
+ */
+interface PancakeContextValue {
+    client: PancakeClient | null;
+    isConnecting: boolean;
+    error: Error | null;
+}
+/**
+ * React context for Pancake client
+ */
+declare const PancakeContext: React.Context<PancakeContextValue | null>;
+/**
+ * Get the Pancake context (internal use)
+ */
+declare function usePancakeContext(): PancakeContextValue;
+/**
+ * Get the Pancake client (throws if not connected)
+ */
+declare function usePancakeClient(): PancakeClient;
+
+/**
+ * Hook for managing view state.
+ *
+ * State is persisted in ChatGPT, volatile in MCP.
+ * Uses React-style updater function pattern.
+ *
+ * @example
+ * ```tsx
+ * function Counter() {
+ *   const [count, setCount] = useViewState(0);
+ *
+ *   return (
+ *     <div>
+ *       <p>Count: {count}</p>
+ *       <button onClick={() => setCount(c => c + 1)}>+</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useViewState<T>(defaultValue: T): [T, (newState: T | ((prev: T) => T)) => void];
+
+/**
+ * Hook for accessing the full host context.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const host = useHost();
+ *
+ *   return (
+ *     <div>
+ *       <p>Theme: {host.theme}</p>
+ *       <p>Platform: {host.platform}</p>
+ *       <p>Locale: {host.locale}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useHost(): HostContext;
+
+/**
+ * Hook for accessing the current theme.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const theme = useTheme();
+ *
+ *   return (
+ *     <div data-theme={theme}>
+ *       <p>Current theme: {theme}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useTheme(): 'light' | 'dark';
+
+/**
+ * Return type for useDisplayMode hook
+ */
+interface DisplayModeHook {
+    /** Current display mode */
+    mode: 'inline' | 'fullscreen' | 'pip';
+    /** Available display modes */
+    availableModes: string[];
+    /** Request a display mode change */
+    requestMode: (mode: 'inline' | 'fullscreen' | 'pip') => Promise<void>;
+}
+/**
+ * Hook for managing display mode.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { mode, availableModes, requestMode } = useDisplayMode();
+ *
+ *   return (
+ *     <div>
+ *       <p>Current mode: {mode}</p>
+ *       {availableModes.includes('fullscreen') && (
+ *         <button onClick={() => requestMode('fullscreen')}>
+ *           Go Fullscreen
+ *         </button>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useDisplayMode(): DisplayModeHook;
+
+/**
+ * Return type for useNavigation hook
+ */
+interface NavigationHook {
+    /** Navigate to a view (triggers view:name tool call) */
+    navigate: (viewName: string, params?: Record<string, unknown>) => Promise<void>;
+    /** Send a message to the model */
+    say: (message: string) => Promise<void>;
+}
+/**
+ * Hook for navigation and communication with the model.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { navigate, say } = useNavigation();
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => navigate('dashboard', { userId: '123' })}>
+ *         Go to Dashboard
+ *       </button>
+ *       <button onClick={() => say('Show me more details')}>
+ *         Ask for More
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useNavigation(): NavigationHook;
+
+/**
+ * Hook for accessing the current action input.
+ *
+ * This is useful for action UIs that need to display
+ * or process the input sent by the model.
+ *
+ * @example
+ * ```tsx
+ * function ActionConfirmation() {
+ *   const input = useActionInput<{ itemId: string; action: string }>();
+ *
+ *   if (!input) return <div>No input</div>;
+ *
+ *   return (
+ *     <div>
+ *       <p>Action: {input.action}</p>
+ *       <p>Item: {input.itemId}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useActionInput<T = Record<string, unknown>>(): T | undefined;
+
+/**
+ * Hook for accessing view parameters (inputs + data).
+ *
+ * @example
+ * ```tsx
+ * function MyView() {
+ *   const { inputs, data } = useViewParams<
+ *     { userId: string },
+ *     { user: { name: string; email: string } }
+ *   >();
+ *
+ *   return (
+ *     <div>
+ *       <p>User ID: {inputs.userId}</p>
+ *       <p>Name: {data.user.name}</p>
+ *       <p>Email: {data.user.email}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useViewParams<TInputs = unknown, TData = unknown>(): ViewParams<TInputs, TData>;
+
+/**
+ * Return type for useAction hook
+ */
+interface ActionHook {
+    /** Dispatch an action (calls action:name tool) */
+    dispatch: <T = unknown>(actionName: string, params?: Record<string, unknown>) => Promise<T>;
+}
+/**
+ * Hook for dispatching actions (write operations).
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { dispatch } = useAction();
+ *
+ *   const handleSubmit = async () => {
+ *     const result = await dispatch<{ success: boolean }>('createUser', {
+ *       name: 'John',
+ *       email: 'john@example.com',
+ *     });
+ *     console.log('Created:', result.success);
+ *   };
+ *
+ *   return <button onClick={handleSubmit}>Create User</button>;
+ * }
+ * ```
+ */
+declare function useAction(): ActionHook;
+
+/**
+ * Return type for useData hook
+ */
+interface DataHook {
+    /** Fetch data from a data endpoint (calls data:name tool) */
+    getData: <T = unknown>(dataName: string, params?: Record<string, unknown>) => Promise<T>;
+}
+/**
+ * Hook for fetching data (read operations).
+ *
+ * @example
+ * ```tsx
+ * function UserList() {
+ *   const { getData } = useData();
+ *   const [users, setUsers] = useState<User[]>([]);
+ *
+ *   const loadUsers = async () => {
+ *     const data = await getData<User[]>('listUsers', { limit: 10 });
+ *     setUsers(data);
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={loadUsers}>Load Users</button>
+ *       <ul>
+ *         {users.map(u => <li key={u.id}>{u.name}</li>)}
+ *       </ul>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useData(): DataHook;
+
+export { type ActionHook, type DataHook, type DisplayModeHook, type HostContext, type NavigationHook, PancakeContext, type PancakeContextValue, PancakeProvider, type PancakeProviderProps, type Protocol, type ViewParams, useAction, useActionInput, useData, useDisplayMode, useHost, useNavigation, usePancakeClient, usePancakeContext, useTheme, useViewParams, useViewState };