@ikonai/sdk-react-ui 0.0.34 → 0.0.37

package/app/connection-state-renderer.d.ts

@@ -0,0 +1,56 @@
+import { ConnectionState, IkonClient } from '../../../sdk/src/index.ts';
+import { ReactNode } from 'react';
+import { IkonUiRegistry } from '../ikon-ui-registry';
+import { IkonUiStoreEntry } from '../surface';
+/**
+ * Props passed to the renderConnected callback.
+ */
+export interface ConnectedRenderProps {
+    stores: ReadonlyMap<string, IkonUiStoreEntry>;
+    registry: IkonUiRegistry;
+    client: IkonClient | null;
+    onAction: (actionId: string, payload: unknown) => void;
+    isReconnecting: boolean;
+}
+/**
+ * Props for the ConnectionStateRenderer component.
+ */
+export interface ConnectionStateRendererProps {
+    connectionState: ConnectionState;
+    error: string | null;
+    isReady: boolean;
+    stores: ReadonlyMap<string, IkonUiStoreEntry> | undefined;
+    registry: IkonUiRegistry | null;
+    client: IkonClient | null;
+    onAction: (actionId: string, payload: unknown) => void;
+    /**
+     * Render when idle (not yet started connecting).
+     */
+    renderIdle: () => ReactNode;
+    /**
+     * Render when connecting (initial connection attempt).
+     */
+    renderConnecting: () => ReactNode;
+    /**
+     * Render when connection is taking longer than expected.
+     */
+    renderConnectingSlow: () => ReactNode;
+    /**
+     * Render the main UI when connected.
+     * The isReconnecting flag indicates if currently reconnecting (overlay can be shown on top).
+     */
+    renderConnected: (props: ConnectedRenderProps) => ReactNode;
+    /**
+     * Render when connection is offline.
+     */
+    renderOffline: () => ReactNode;
+    /**
+     * Render when connection failed with error.
+     */
+    renderError: (error: string | null) => ReactNode;
+}
+/**
+ * Headless component that handles connection state logic.
+ * User provides all render callbacks - no default UI.
+ */
+export declare function ConnectionStateRenderer({ connectionState, error, isReady, stores, registry, client, onAction, renderIdle, renderConnecting, renderConnectingSlow, renderConnected, renderOffline, renderError, }: ConnectionStateRendererProps): ReactNode;

package/app/index.d.ts

@@ -0,0 +1,2 @@
+export { ConnectionStateRenderer, type ConnectedRenderProps, type ConnectionStateRendererProps } from './connection-state-renderer';
+export { useIkonApp, type IkonUiModuleRegistration, type LocalServerConfig, type UseIkonAppOptions, type UseIkonAppResult } from './use-ikon-app';

package/app/use-ikon-app.d.ts

@@ -0,0 +1,134 @@
+import { AudioConfig, ConnectionState, DebugConfig, IkonClient, MediaSessionConfig, TimeoutConfig, VideoConfig } from '../../../sdk/src/index.ts';
+import { RefObject } from 'react';
+import { AuthConfig } from '../auth/types';
+import { IkonUiRegistry } from '../ikon-ui-registry';
+import { IkonUi } from '../ikon-ui';
+import { IkonUiStoreEntry } from '../surface';
+/**
+ * Configuration for local server mode.
+ */
+export interface LocalServerConfig {
+    enabled: boolean;
+    host?: string;
+    httpsPort?: number;
+}
+/**
+ * Module registration function type.
+ */
+export type IkonUiModuleRegistration = (registry: IkonUiRegistry) => void;
+/**
+ * Options for the useIkonApp hook.
+ */
+export interface UseIkonAppOptions {
+    /**
+     * Authentication configuration. Pass null to disable auth.
+     */
+    authConfig: AuthConfig | null;
+    /**
+     * Local server configuration. If not provided, cloud mode is assumed.
+     */
+    localServer?: LocalServerConfig;
+    /**
+     * UI modules to register. Simpler alternative to registerModules callback.
+     * @example
+     * modules: [registerRadixModule]
+     */
+    modules?: IkonUiModuleRegistration[];
+    /**
+     * Register additional UI modules before loading.
+     * Use this for advanced scenarios; for simple cases prefer `modules`.
+     */
+    registerModules?: (registry: IkonUiRegistry) => void;
+    /**
+     * Callback when connected and joined.
+     */
+    onJoined?: (sessionId: string | undefined) => void;
+    /**
+     * Callback when connection state changes.
+     */
+    onConnectionStateChange?: (state: ConnectionState) => void;
+    /**
+     * Callback when an error occurs.
+     */
+    onError?: (error: Error) => void;
+    /**
+     * Whether to update the URL with the session ID after joining.
+     * Default: true
+     */
+    updateUrlOnJoin?: boolean;
+    /**
+     * Timeout configuration passed to IkonClient.
+     * If not provided, SDK defaults are used.
+     */
+    timeouts?: TimeoutConfig;
+    /**
+     * Audio playback configuration passed to IkonClient.
+     * If not provided, SDK defaults are used.
+     */
+    audio?: AudioConfig;
+    /**
+     * Video playback configuration passed to IkonClient.
+     * If not provided, SDK defaults are used.
+     */
+    video?: VideoConfig;
+    /**
+     * Media Session metadata for OS-level media controls (lock screen, notifications).
+     * Shared across audio and video playback.
+     */
+    mediaSession?: MediaSessionConfig;
+    /**
+     * Debug configuration passed to IkonClient.
+     * If not provided, SDK defaults are used.
+     */
+    debug?: DebugConfig;
+}
+/**
+ * Result returned by the useIkonApp hook.
+ */
+export interface UseIkonAppResult {
+    /**
+     * Current connection state.
+     */
+    connectionState: ConnectionState;
+    /**
+     * Current error message, if any.
+     */
+    error: string | null;
+    /**
+     * UI stores for rendering.
+     */
+    stores: ReadonlyMap<string, IkonUiStoreEntry> | undefined;
+    /**
+     * Current IkonClient instance, or null if not connected.
+     */
+    client: IkonClient | null;
+    /**
+     * Current IkonUiRegistry instance, or null if not initialized.
+     */
+    registry: IkonUiRegistry | null;
+    /**
+     * Reference to the IkonClient instance (for use in callbacks).
+     */
+    clientRef: RefObject<IkonClient | null>;
+    /**
+     * Reference to the IkonUi instance.
+     */
+    uiRef: RefObject<IkonUi | null>;
+    /**
+     * Reference to the IkonUiRegistry instance (for use in callbacks).
+     */
+    registryRef: RefObject<IkonUiRegistry | null>;
+    /**
+     * Action handler for UI interactions.
+     */
+    onAction: (actionId: string, payload: unknown) => void;
+    /**
+     * Whether the connection is ready to render UI.
+     */
+    isReady: boolean;
+}
+/**
+ * High-level hook that manages the entire Ikon connection lifecycle.
+ * Encapsulates client creation, auth scenarios, UI registry setup, and state management.
+ */
+export declare function useIkonApp(options: UseIkonAppOptions): UseIkonAppResult;

package/auth/auth-context.d.ts

@@ -0,0 +1,21 @@
+import { ReactNode } from 'react';
+import { AuthConfig, AuthContextValue } from './types';
+export interface AuthProviderProps {
+    children: ReactNode;
+    config: AuthConfig;
+}
+/**
+ * Authentication provider that manages auth state and provides auth methods.
+ * This is a headless provider - it manages state only, no UI rendering.
+ */
+export declare function AuthProvider({ children, config }: AuthProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Hook to access the auth context.
+ * Throws if used outside of AuthProvider.
+ */
+export declare function useAuth(): AuthContextValue;
+/**
+ * Hook to optionally access auth context.
+ * Returns null if used outside of AuthProvider (doesn't throw).
+ */
+export declare function useAuthOptional(): AuthContextValue | null;

package/auth/auth-service.d.ts

@@ -0,0 +1,43 @@
+import { AuthSession, LoginMethod } from './types';
+/**
+ * Result of parsing an OAuth callback from the URL.
+ */
+export interface OAuthCallbackResult {
+    token: string;
+    provider: LoginMethod;
+}
+/**
+ * Authenticate anonymously with the Ikon auth service.
+ * Returns a session with a token for anonymous users.
+ */
+export declare function authenticateAnonymous(spaceId: string, authUrl: string): Promise<AuthSession>;
+/**
+ * Options for sending a magic link email.
+ */
+export interface SendMagicLinkOptions {
+    email: string;
+    spaceId: string;
+    authUrl: string;
+    returnUrl?: string;
+}
+/**
+ * Send a magic link email for passwordless authentication.
+ */
+export declare function sendMagicLink(options: SendMagicLinkOptions): Promise<void>;
+/**
+ * Parse OAuth callback parameters from the current URL.
+ * Returns the token and provider if present, or null if not an OAuth callback.
+ */
+export declare function parseOAuthCallback(): OAuthCallbackResult | null;
+/**
+ * Get the error from an OAuth callback if present.
+ */
+export declare function parseOAuthError(): string | null;
+/**
+ * Clear OAuth-related parameters from the URL.
+ */
+export declare function clearOAuthParams(): void;
+/**
+ * Build an OAuth redirect URL for the given provider.
+ */
+export declare function buildOAuthRedirectUrl(provider: LoginMethod, spaceId: string, authUrl: string, returnUrl?: string): string;

package/auth/index.d.ts

@@ -0,0 +1,5 @@
+export type { AuthConfig, AuthContextValue, AuthSession, AuthState, AuthUser, LoginMethod } from './types';
+export { clearAuthSession, loadAuthSession, saveAuthSession, sessionToUser } from './storage';
+export { authenticateAnonymous, buildOAuthRedirectUrl, clearOAuthParams, parseOAuthCallback, parseOAuthError, sendMagicLink, type OAuthCallbackResult, type SendMagicLinkOptions } from './auth-service';
+export { AuthProvider, useAuth, useAuthOptional, type AuthProviderProps } from './auth-context';
+export { useAuthGuard, type UseAuthGuardOptions, type UseAuthGuardResult } from './use-auth-guard';

package/auth/storage.d.ts

@@ -0,0 +1,18 @@
+import { AuthSession, AuthUser } from './types';
+/**
+ * Save the authenticated user session to localStorage.
+ */
+export declare function saveAuthSession(session: AuthSession): void;
+/**
+ * Load the authenticated user session from localStorage.
+ * Returns null if no session exists or if the session has expired.
+ */
+export declare function loadAuthSession(): AuthSession | null;
+/**
+ * Clear the authenticated user session from localStorage.
+ */
+export declare function clearAuthSession(): void;
+/**
+ * Convert AuthSession to AuthUser.
+ */
+export declare function sessionToUser(session: AuthSession): AuthUser;

package/auth/types.d.ts

@@ -0,0 +1,49 @@
+/**
+ * All supported login methods.
+ */
+export type LoginMethod = 'google' | 'facebook' | 'apple' | 'microsoft' | 'linkedin' | 'github' | 'email' | 'guest';
+/**
+ * Authenticated user information.
+ */
+export interface AuthUser {
+    id: string;
+    provider: LoginMethod | 'anonymous';
+    token: string;
+    authenticatedAt: number;
+}
+/**
+ * Authentication state.
+ */
+export interface AuthState {
+    isAuthenticated: boolean;
+    isLoading: boolean;
+    user: AuthUser | null;
+    error: string | null;
+}
+/**
+ * Authentication configuration.
+ */
+export interface AuthConfig {
+    enabled: boolean;
+    methods: LoginMethod[];
+    spaceId: string;
+    /** Optional custom auth URL. If not provided, derived from environment. */
+    authUrl?: string;
+}
+/**
+ * Stored session data in localStorage.
+ */
+export interface AuthSession {
+    token: string;
+    provider: LoginMethod | 'anonymous';
+    authenticatedAt: number;
+}
+/**
+ * Auth context value returned by useAuth hook.
+ */
+export interface AuthContextValue {
+    state: AuthState;
+    login: (method: LoginMethod) => void;
+    logout: () => void;
+    getToken: () => string | null;
+}

package/auth/use-auth-guard.d.ts

@@ -0,0 +1,35 @@
+import { AuthConfig } from './types';
+export interface UseAuthGuardOptions {
+    /**
+     * Auth configuration with enabled methods.
+     */
+    config: AuthConfig;
+    /**
+     * URL parameter name that triggers automatic guest login.
+     * If the URL contains this parameter with a truthy value, guest login is triggered automatically.
+     */
+    guestUrlParam?: string;
+}
+export interface UseAuthGuardResult {
+    /**
+     * Whether the protected content should be rendered.
+     */
+    shouldRenderChildren: boolean;
+    /**
+     * Whether auth state is still being checked.
+     */
+    isCheckingAuth: boolean;
+    /**
+     * Whether the user is authenticated.
+     */
+    isAuthenticated: boolean;
+    /**
+     * Current auth error, if any.
+     */
+    error: string | null;
+}
+/**
+ * Headless hook for route protection logic.
+ * Returns state that can be used to conditionally render auth UI or protected content.
+ */
+export declare function useAuthGuard(options: UseAuthGuardOptions): UseAuthGuardResult;

package/hooks/index.d.ts

@@ -0,0 +1 @@
+export { useLazyFont } from './use-lazy-font';

package/hooks/use-lazy-font.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Hook for lazy loading fonts. The font is only loaded when the returned function is called.
+ * Useful for loading fonts only when certain UI elements (like error overlays) are displayed.
+ *
+ * @param fontUrl - The URL of the font stylesheet (e.g., Google Fonts URL)
+ * @returns A function that loads the font when called. Safe to call multiple times - font only loads once.
+ *
+ * @example
+ * ```tsx
+ * const loadFont = useLazyFont('https://fonts.googleapis.com/css2?family=Space+Grotesk&display=swap');
+ *
+ * function ErrorOverlay() {
+ *   loadFont(); // Font loads only when this component renders
+ *   return <div>Error occurred</div>;
+ * }
+ * ```
+ */
+export declare function useLazyFont(fontUrl: string): () => void;

package/i18n/i18n.d.ts

@@ -0,0 +1,16 @@
+import { ReactNode } from 'react';
+type TranslationsMap<T> = Record<string, T>;
+export interface I18nContextValue<T> {
+    t: <K extends keyof T>(key: K, params?: Record<string, string>) => string;
+    locale: string;
+    translations: T;
+}
+export interface I18nProviderProps<T> {
+    children: ReactNode;
+    translations: TranslationsMap<T>;
+    defaultLanguage?: string;
+    detectLanguage?: boolean;
+}
+export declare function I18nProvider<T extends object>({ children, translations, defaultLanguage, detectLanguage, }: I18nProviderProps<T>): import("react/jsx-runtime").JSX.Element;
+export declare function useI18n<T extends object>(): I18nContextValue<T>;
+export {};

package/i18n/index.d.ts

@@ -0,0 +1 @@
+export { I18nProvider, useI18n, type I18nContextValue, type I18nProviderProps } from './i18n';

package/index.d.ts

@@ -1,12 +1,16 @@
 export { IkonUi, type IkonUIConfig } from './ikon-ui';
-export { IkonUiRegistry, createIkonUiRegistry, type IkonUiComponentResolver, type IkonUiModuleLoader, type IkonUiModuleLoaderResult, } from './ikon-ui-registry';
-export { IkonUiSurface, IKON_UI_STREAM_CATEGORY, isIkonUiCategoryMatch, type IkonUiCategory, type IkonUiStoreEntry, } from './surface';
+export { IkonUiRegistry, createIkonUiRegistry, type IkonUiComponentResolver, type IkonUiModuleLoader, type IkonUiModuleLoaderResult } from './ikon-ui-registry';
+export { IkonUiSurface, IKON_UI_STREAM_CATEGORY, isIkonUiCategoryMatch, type IkonUiCategory, type IkonUiStoreEntry } from './surface';
 export { useIkonStyles, type IkonUiStyleSource } from './use-ikon-styles';
 export { useIkonUiStores } from './use-ikon-ui-stores';
-export { parseIkonUiInitPayload, normalizeIkonUiModuleList, readIkonUiModules, readIkonUiModulesFromSources, areIkonUiModuleListsEqual, type IkonUiInitInstruction, type IkonUiInitModulePayload, type IkonUiModuleList, } from './modules';
-export { IKON_UI_BASE_MODULE, createBaseResolvers, loadBaseModule, registerBaseModule, } from './base/base-module';
-export { IKON_UI_MEDIA_MODULE, IKON_UI_VIDEO_CANVAS_TYPE, IKON_UI_VIDEO_URL_PLAYER_TYPE, createMediaResolvers, loadMediaModule, registerMediaModule, } from './media/media-module';
-export { UiRenderer, type UiRendererProps, UiComponentRegistry, createComponentLibrary, useUiStore, useUiNode, renderChildren, } from './renderer';
-export type { UiComponentRenderer, UiComponentLibrary, UiNode, UiRenderContext, UiComponentRendererProps, ParsedUiUpdate, UiSnapshot, UiFullSnapshot, UiDiffSnapshot, UiNodeDiff, TextDelta, UiNodeProps, UiUpdateType, UiStoreSnapshot, UiOptimisticPatchState, } from './renderer';
+export { parseIkonUiInitPayload, normalizeIkonUiModuleList, readIkonUiModules, readIkonUiModulesFromSources, areIkonUiModuleListsEqual, type IkonUiInitInstruction, type IkonUiInitModulePayload, type IkonUiModuleList } from './modules';
+export { IKON_UI_BASE_MODULE, createBaseResolvers, loadBaseModule, registerBaseModule } from './base/base-module';
+export { IKON_UI_MEDIA_MODULE, IKON_UI_VIDEO_CANVAS_TYPE, IKON_UI_VIDEO_URL_PLAYER_TYPE, createMediaResolvers, loadMediaModule, registerMediaModule } from './media/media-module';
+export { UiRenderer, type UiRendererProps, UiComponentRegistry, createComponentLibrary, useUiStore, useUiNode, renderChildren } from './renderer';
+export type { UiComponentRenderer, UiComponentLibrary, UiNode, UiRenderContext, UiComponentRendererProps, ParsedUiUpdate, UiSnapshot, UiFullSnapshot, UiDiffSnapshot, UiNodeDiff, TextDelta, UiNodeProps, UiUpdateType, UiStoreSnapshot, UiOptimisticPatchState } from './renderer';
 export { UiStreamStore, type UiStylePayload } from '../../sdk-ui/src/index.ts';
 export { renderMotionLetters } from './shared/render-motion-letters';
+export { type AuthConfig, type AuthContextValue, type AuthSession, type AuthState, type AuthUser, type LoginMethod, clearAuthSession, loadAuthSession, saveAuthSession, sessionToUser, authenticateAnonymous, buildOAuthRedirectUrl, clearOAuthParams, parseOAuthCallback, parseOAuthError, sendMagicLink, type OAuthCallbackResult, type SendMagicLinkOptions, AuthProvider, useAuth, useAuthOptional, type AuthProviderProps, useAuthGuard, type UseAuthGuardOptions, type UseAuthGuardResult, } from './auth';
+export { ConnectionStateRenderer, type ConnectedRenderProps, type ConnectionStateRendererProps, useIkonApp, type IkonUiModuleRegistration, type LocalServerConfig, type UseIkonAppOptions, type UseIkonAppResult, } from './app';
+export { useLazyFont } from './hooks';
+export { I18nProvider, useI18n, type I18nContextValue, type I18nProviderProps } from './i18n';