sunpeak 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,571 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ButtonHTMLAttributes, HTMLAttributes, ReactNode, SetStateAction } from 'react';
+
+interface ButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'onClick'> {
+    /**
+     * Whether to use primary styling (accent color) or secondary (outlined)
+     * @default false
+     */
+    isPrimary?: boolean;
+    /**
+     * Click handler (required)
+     */
+    onClick: () => void;
+    /**
+     * Button label
+     */
+    children: React.ReactNode;
+}
+/**
+ * Button - A button component that follows platform design guidelines.
+ * Requires an action handler. Use isPrimary to toggle between primary and secondary styles.
+ *
+ * Design specs:
+ * - Primary (isPrimary=true): Accent color background, white text
+ * - Secondary (isPrimary=false): Transparent background with border
+ * - Both: 14px medium font, rounded corners, hover/active states
+ */
+declare const Button: ({ isPrimary, onClick, children, className, type, ...props }: ButtonProps) => react_jsx_runtime.JSX.Element;
+
+interface GenAIProps extends HTMLAttributes<HTMLDivElement> {
+    /**
+     * Maximum width in pixels
+     * @default 800
+     */
+    maxWidth?: number;
+}
+interface GenAIRenderProps {
+    /**
+     * Maximum height from platform (in pixels)
+     */
+    maxHeight: number | null;
+    /**
+     * Color scheme from platform
+     */
+    colorScheme: 'light' | 'dark' | null;
+}
+/**
+ * GenAI - Create platform-aware genAI Apps with automatic theming and constraints.
+ *
+ * @example
+ * ```tsx
+ * export const MyApp = GenAI(() => (
+ *   <div>My content</div>
+ * ));
+ * ```
+ */
+declare function GenAI(renderFn: (props: GenAIRenderProps) => ReactNode): {
+    (props?: GenAIProps): react_jsx_runtime.JSX.Element;
+    displayName: string;
+};
+
+interface CardProps extends Omit<GenAIProps, 'children'>, HTMLAttributes<HTMLDivElement> {
+    /**
+     * Card content
+     */
+    children?: ReactNode;
+    /**
+     * Image to display at the top of the card
+     */
+    image: string;
+    /**
+     * Alt text for the image
+     */
+    imageAlt: string;
+    /**
+     * Maximum width for the image in pixels
+     */
+    imageMaxWidth: number;
+    /**
+     * Maximum height for the image in pixels
+     */
+    imageMaxHeight: number;
+    /**
+     * Optional header text (title)
+     */
+    header?: ReactNode;
+    /**
+     * Optional metadata text (e.g., rating, category)
+     */
+    metadata?: ReactNode;
+    /**
+     * First action button (0-1)
+     */
+    button1?: ButtonProps;
+    /**
+     * Second action button (0-1)
+     */
+    button2?: ButtonProps;
+    /**
+     * Card variant
+     */
+    variant?: 'default' | 'bordered' | 'elevated';
+}
+/**
+ * Card - A responsive card component that adapts to display mode.
+ *
+ * In inline mode:
+ * - Width: 220px (fixed for carousel consistency)
+ * - Compact layout optimized for horizontal scrolling
+ * - Clickable to request fullscreen mode
+ *
+ * In fullscreen mode:
+ * - Full width layout
+ * - Expanded content display
+ * - More breathing room for content
+ *
+ * Design specs:
+ * - Image: aspect-square with 24px border radius
+ * - Typography: 16px medium for header, 12px for metadata, 14px for description
+ * - Spacing: 12px between sections
+ * - Max 2 actions in footer (design guideline)
+ */
+declare const Card: ({ children, image, imageAlt, imageMaxWidth, imageMaxHeight, header, metadata, button1, button2, variant, maxWidth, className, onClick, id, ...props }: CardProps) => react_jsx_runtime.JSX.Element;
+
+interface CarouselProps extends Omit<GenAIProps, 'children'>, HTMLAttributes<HTMLDivElement> {
+    /**
+     * Carousel items (typically Card components)
+     */
+    children: ReactNode;
+    /**
+     * Gap between items in pixels
+     * @default 16
+     */
+    gap?: number;
+    /**
+     * Show navigation arrows
+     * @default true
+     */
+    showArrows?: boolean;
+    /**
+     * Show edge gradients to indicate more content
+     * @default true
+     */
+    showEdgeGradients?: boolean;
+}
+/**
+ * Carousel - A carousel component for displaying multiple cards side-by-side.
+ * Follows OpenAI ChatGPT Apps SDK design guidelines.
+ *
+ * Design specs:
+ * - 3-8 items recommended (design guideline)
+ * - 16px gap between items
+ * - 32px circular navigation buttons with shadow
+ * - Edge gradients with fade effect
+ * - Padding: 20px vertical
+ * - Draggable with mouse for smooth scrolling
+ */
+declare const Carousel: ({ children, gap, maxWidth, showArrows, showEdgeGradients, className, ...props }: CarouselProps) => react_jsx_runtime.JSX.Element;
+
+type UnknownObject$1 = Record<string, unknown>;
+type Theme$1 = 'light' | 'dark';
+type SafeAreaInsets$1 = {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+};
+type SafeArea$1 = {
+    insets: SafeAreaInsets$1;
+};
+type DeviceType$1 = 'mobile' | 'tablet' | 'desktop' | 'unknown';
+type UserAgent$1 = {
+    device: {
+        type: DeviceType$1;
+    };
+    capabilities: {
+        hover: boolean;
+        touch: boolean;
+    };
+};
+/** Display mode */
+type DisplayMode$1 = 'pip' | 'inline' | 'fullscreen';
+type RequestDisplayMode$1 = (args: {
+    mode: DisplayMode$1;
+}) => Promise<{
+    /**
+     * The granted display mode. The host may reject the request.
+     * For mobile, PiP is always coerced to fullscreen.
+     */
+    mode: DisplayMode$1;
+}>;
+type CallToolResponse$1 = {
+    result: string;
+};
+/** Calling APIs */
+type CallTool$1 = (name: string, args: Record<string, unknown>) => Promise<CallToolResponse$1>;
+type ChatGPTGlobals<ToolInput = UnknownObject$1, ToolOutput = UnknownObject$1, ToolResponseMetadata = UnknownObject$1, WidgetState = UnknownObject$1> = {
+    colorScheme: Theme$1;
+    userAgent: UserAgent$1;
+    locale: string;
+    maxHeight: number;
+    displayMode: DisplayMode$1;
+    safeArea: SafeArea$1;
+    toolInput: ToolInput;
+    toolOutput: ToolOutput | null;
+    toolResponseMetadata: ToolResponseMetadata | null;
+    widgetState: WidgetState | null;
+    setWidgetState: (state: WidgetState) => Promise<void>;
+};
+type API = {
+    callTool: CallTool$1;
+    sendFollowUpMessage: (args: {
+        prompt: string;
+    }) => Promise<void>;
+    openExternal(payload: {
+        href: string;
+    }): void;
+    requestDisplayMode: RequestDisplayMode$1;
+};
+/** Extra events */
+declare const SET_GLOBALS_EVENT_TYPE = "chatgpt:set_globals";
+declare class SetGlobalsEvent extends CustomEvent<{
+    globals: Partial<ChatGPTGlobals>;
+}> {
+    readonly type = "chatgpt:set_globals";
+}
+/**
+ * Global openai object injected by the web sandbox for communicating with ChatGPT host page.
+ */
+declare global {
+    interface Window {
+        openai?: API & ChatGPTGlobals;
+    }
+    interface WindowEventMap {
+        [SET_GLOBALS_EVENT_TYPE]: SetGlobalsEvent;
+    }
+}
+
+/**
+ * Platform-agnostic types for genAI App SDKs
+ *
+ * These types define a common interface that can be implemented
+ * by different platforms (ChatGPT, Gemini, Claude, etc.)
+ */
+type UnknownObject = Record<string, unknown>;
+type Theme = 'light' | 'dark';
+type SafeAreaInsets = {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+};
+type SafeArea = {
+    insets: SafeAreaInsets;
+};
+type DeviceType = 'mobile' | 'tablet' | 'desktop' | 'unknown';
+type UserAgent = {
+    device: {
+        type: DeviceType;
+    };
+    capabilities: {
+        hover: boolean;
+        touch: boolean;
+    };
+};
+/** Display mode for the app */
+type DisplayMode = 'pip' | 'inline' | 'fullscreen';
+type RequestDisplayMode = (args: {
+    mode: DisplayMode;
+}) => Promise<{
+    mode: DisplayMode;
+}>;
+type CallToolResponse = {
+    result: string;
+};
+type CallTool = (name: string, args: Record<string, unknown>) => Promise<CallToolResponse>;
+/**
+ * Platform-agnostic global state interface
+ *
+ * All genAI platforms should implement this interface to work with Sunpeak components.
+ */
+type PlatformGlobals<ToolInput = UnknownObject, ToolOutput = UnknownObject, ToolResponseMetadata = UnknownObject, WidgetState = UnknownObject> = {
+    colorScheme: Theme;
+    userAgent: UserAgent;
+    locale: string;
+    maxHeight: number;
+    displayMode: DisplayMode;
+    safeArea: SafeArea;
+    toolInput: ToolInput;
+    toolOutput: ToolOutput | null;
+    toolResponseMetadata: ToolResponseMetadata | null;
+    widgetState: WidgetState | null;
+    setWidgetState: (state: WidgetState) => Promise<void>;
+};
+/**
+ * Platform API methods
+ */
+type PlatformAPI = {
+    callTool: CallTool;
+    sendFollowUpMessage: (args: {
+        prompt: string;
+    }) => Promise<void>;
+    openExternal(payload: {
+        href: string;
+    }): void;
+    requestDisplayMode: RequestDisplayMode;
+};
+/**
+ * Platform adapter interface
+ *
+ * Implement this interface to add support for a new genAI platform.
+ */
+interface PlatformAdapter {
+    /**
+     * Platform identifier (e.g., 'chatgpt', 'gemini', 'claude')
+     */
+    readonly name: string;
+    /**
+     * Check if this platform is available in the current environment
+     */
+    isAvailable(): boolean;
+    /**
+     * Get a specific global value
+     */
+    getGlobal<K extends keyof PlatformGlobals>(key: K): PlatformGlobals[K] | null;
+    /**
+     * Get all platform globals
+     */
+    getGlobals(): (PlatformAPI & PlatformGlobals) | null;
+    /**
+     * Subscribe to changes in platform globals
+     * Returns an unsubscribe function
+     */
+    subscribe(callback: () => void): () => void;
+}
+/**
+ * Platform registry to track supported platforms
+ */
+type PlatformType = 'chatgpt' | 'gemini' | 'claude' | 'custom';
+
+interface ChatGPTSimulatorProps {
+    /**
+     * The component to render in the ChatGPT message
+     * Can be a function that receives the selected App UI
+     */
+    children: ReactNode | ((uiSimulation: string) => ReactNode);
+    /**
+     * Initial display mode
+     */
+    displayMode?: DisplayMode$1;
+    /**
+     * Initial color scheme
+     */
+    colorScheme?: Theme$1;
+    /**
+     * Initial tool input
+     */
+    toolInput?: Record<string, unknown>;
+    /**
+     * Initial tool output
+     */
+    toolOutput?: Record<string, unknown> | null;
+    /**
+     * Initial widget state
+     */
+    widgetState?: Record<string, unknown> | null;
+    /**
+     * User message to display above the component
+     */
+    userMessage?: string;
+    /**
+     * Show simulator controls
+     */
+    showControls?: boolean;
+    /**
+     * App UIs for the App UI selector
+     */
+    uiSimulations?: string[];
+    /**
+     * Initial App UI
+     */
+    initialUISimulation?: string;
+}
+/**
+ * ChatGPT Simulator Component
+ *
+ * Emulates the ChatGPT environment for testing components locally.
+ * Provides window.openai API and renders components in a ChatGPT-like UI.
+ */
+declare function ChatGPTSimulator({ children, displayMode: initialDisplayMode, colorScheme: initialColorScheme, toolInput, toolOutput, widgetState: initialWidgetState, userMessage, showControls, uiSimulations, initialUISimulation, }: ChatGPTSimulatorProps): react_jsx_runtime.JSX.Element;
+
+interface PlatformProviderProps {
+    /**
+     * The platform adapter to use. If not provided, will auto-detect.
+     */
+    adapter?: PlatformAdapter;
+    /**
+     * Platform name to use (e.g., 'chatgpt', 'gemini'). If not provided, will auto-detect.
+     */
+    platform?: string;
+    children: ReactNode;
+}
+/**
+ * Platform Provider
+ *
+ * Wrap your app with this provider to specify which genAI platform to use.
+ * If no platform is specified, it will auto-detect the available platform.
+ *
+ * @example
+ * ```tsx
+ * import { PlatformProvider } from 'sunpeak';
+ *
+ * // Auto-detect platform
+ * <PlatformProvider>
+ *   <App />
+ * </PlatformProvider>
+ *
+ * // Explicitly use ChatGPT
+ * <PlatformProvider platform="chatgpt">
+ *   <App />
+ * </PlatformProvider>
+ * ```
+ */
+declare function PlatformProvider({ adapter, platform, children }: PlatformProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access the current platform adapter
+ *
+ * Returns null if no platform is available or detected.
+ */
+declare function usePlatform(): PlatformAdapter | null;
+
+declare class ChatGPTPlatformAdapter implements PlatformAdapter {
+    readonly name = "chatgpt";
+    isAvailable(): boolean;
+    getGlobal<K extends keyof PlatformGlobals>(key: K): PlatformGlobals[K] | null;
+    getGlobals(): ({
+        callTool: CallTool$1;
+        sendFollowUpMessage: (args: {
+            prompt: string;
+        }) => Promise<void>;
+        openExternal(payload: {
+            href: string;
+        }): void;
+        requestDisplayMode: RequestDisplayMode$1;
+    } & ChatGPTGlobals<UnknownObject$1, UnknownObject$1, UnknownObject$1, UnknownObject$1>) | null;
+    subscribe(callback: () => void): () => void;
+}
+/**
+ * Singleton instance of the ChatGPT platform adapter
+ */
+declare const chatgptPlatform: ChatGPTPlatformAdapter;
+
+/**
+ * Platform Registry
+ *
+ * Manages multiple platform adapters and auto-detects the active platform.
+ */
+
+interface PlatformRegistry {
+    /**
+     * Register a platform adapter
+     */
+    register(adapter: PlatformAdapter): void;
+    /**
+     * Get a specific platform adapter by name
+     */
+    get(name: string): PlatformAdapter | null;
+    /**
+     * Auto-detect and return the active platform
+     * Returns the first available platform in the registry
+     */
+    detect(): PlatformAdapter | null;
+    /**
+     * Get all registered platforms
+     */
+    getAll(): PlatformAdapter[];
+}
+/**
+ * Create a new platform registry
+ */
+declare function createPlatformRegistry(): PlatformRegistry;
+
+/**
+ * Hook to access platform global state in a platform-agnostic way.
+ * Works with any genAI platform (ChatGPT, Gemini, Claude, etc.)
+ *
+ * Uses React's useSyncExternalStore to efficiently subscribe to changes.
+ *
+ * @param key - The key of the global state to access
+ * @returns The value of the global state, or null if not available
+ *
+ * @example
+ * ```tsx
+ * function MyWidget() {
+ *   const colorScheme = usePlatformGlobal('colorScheme');
+ *   const displayMode = usePlatformGlobal('displayMode');
+ *
+ *   return <div className={colorScheme === 'dark' ? 'dark' : 'light'}>...</div>;
+ * }
+ * ```
+ */
+declare function usePlatformGlobal<K extends keyof PlatformGlobals>(key: K): PlatformGlobals[K] | null;
+
+/**
+ * Hook to get the current display mode from the active genAI platform.
+ * Display modes include: 'inline', 'fullscreen', and 'pip' (picture-in-picture).
+ *
+ * Works with any supported genAI platform (ChatGPT, Gemini, Claude, etc.)
+ *
+ * @returns The current display mode, or null if not in a supported environment
+ */
+declare const useDisplayMode: () => DisplayMode$1 | null;
+
+/**
+ * Hook to get the maximum height constraint from the active genAI platform.
+ * Useful for ensuring your widget doesn't exceed the available space.
+ *
+ * Works with any supported genAI platform (ChatGPT, Gemini, Claude, etc.)
+ *
+ * @returns The maximum height in pixels, or null if not available
+ */
+declare const useMaxHeight: () => number | null;
+
+/**
+ * Hook to request a specific display mode from the platform
+ *
+ * @example
+ * ```tsx
+ * const requestDisplayMode = useRequestDisplayMode();
+ *
+ * const handleClick = async () => {
+ *   await requestDisplayMode({ mode: 'fullscreen' });
+ * };
+ * ```
+ */
+declare function useRequestDisplayMode(): RequestDisplayMode$1;
+
+/**
+ * Hook to get the current color scheme from the active genAI platform.
+ * Color scheme can be 'light' or 'dark'.
+ *
+ * Works with any supported genAI platform (ChatGPT, Gemini, Claude, etc.)
+ *
+ * @returns The current color scheme, or null if not in a supported environment
+ */
+declare const useColorScheme: () => Theme$1 | null;
+
+/**
+ * Hook to get widget props (tool output) from the active genAI platform.
+ * This contains the data returned by your server's tool.
+ *
+ * Works with any supported genAI platform (ChatGPT, Gemini, Claude, etc.)
+ *
+ * @param defaultState - Default state to use if no props are available
+ * @returns The widget props from the tool output
+ */
+declare function useWidgetProps<T extends Record<string, unknown>>(defaultState?: T | (() => T)): T;
+
+/**
+ * Hook to manage widget state that persists in the active genAI platform.
+ * Similar to useState, but syncs with the platform host page.
+ *
+ * Works with any supported genAI platform (ChatGPT, Gemini, Claude, etc.)
+ *
+ * @param defaultState - Default state value or function to generate it
+ * @returns A tuple of [state, setState] similar to useState
+ */
+declare function useWidgetState<T extends UnknownObject$1>(defaultState: T | (() => T)): readonly [T, (state: SetStateAction<T>) => void];
+declare function useWidgetState<T extends UnknownObject$1>(defaultState?: T | (() => T | null) | null): readonly [T | null, (state: SetStateAction<T | null>) => void];
+
+export { Button, type ButtonProps, type CallTool$1 as CallTool, type CallToolResponse$1 as CallToolResponse, Card, type CardProps, Carousel, type CarouselProps, type ChatGPTGlobals, ChatGPTSimulator, type ChatGPTSimulatorProps, type DeviceType$1 as DeviceType, type DisplayMode$1 as DisplayMode, GenAI, type GenAIProps, type GenAIRenderProps, type PlatformAPI, type PlatformAdapter, type PlatformGlobals, PlatformProvider, type PlatformProviderProps, type PlatformRegistry, type PlatformType, type RequestDisplayMode$1 as RequestDisplayMode, type SafeArea$1 as SafeArea, type SafeAreaInsets$1 as SafeAreaInsets, type Theme$1 as Theme, type UnknownObject$1 as UnknownObject, type UserAgent$1 as UserAgent, chatgptPlatform, createPlatformRegistry, useColorScheme, useDisplayMode, useMaxHeight, usePlatform, usePlatformGlobal, useRequestDisplayMode, useWidgetProps, useWidgetState };