@demokit-ai/react 0.3.0 → 0.4.0

package/dist/index.d.cts

@@ -1,480 +0,0 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
-import * as _demokit_ai_core from '@demokit-ai/core';
-import { FixtureMap, CloudFixtureResponse, SessionState } from '@demokit-ai/core';
-export { FixtureHandler, FixtureMap, RequestContext, SessionState } from '@demokit-ai/core';
-import * as react from 'react';
-import { ReactNode, CSSProperties } from 'react';
-
-/**
- * Props for the DemoKitProvider component
- *
- * The provider supports two modes:
- * 1. **Local mode**: Provide `fixtures` prop with pattern handlers
- * 2. **Remote mode**: Provide `apiKey` to fetch from DemoKit Cloud
- *
- * @example Local mode
- * ```tsx
- * <DemoKitProvider fixtures={{ 'GET /api/users': () => [] }}>
- *   <App />
- * </DemoKitProvider>
- * ```
- *
- * @example Remote mode (zero-config)
- * ```tsx
- * <DemoKitProvider apiKey="dk_live_xxx">
- *   <App />
- * </DemoKitProvider>
- * ```
- *
- * @example Remote mode with local overrides
- * ```tsx
- * <DemoKitProvider
- *   apiKey="dk_live_xxx"
- *   fixtures={{ 'POST /api/users': ({ body }) => ({ id: 'custom', ...body }) }}
- * >
- *   <App />
- * </DemoKitProvider>
- * ```
- */
-interface DemoKitProviderProps {
-    /**
-     * Child components to render
-     */
-    children: ReactNode;
-    /**
-     * Map of URL patterns to fixture handlers (local mode)
-     * In remote mode, these act as overrides for cloud fixtures
-     */
-    fixtures?: FixtureMap;
-    /**
-     * DemoKit Cloud API key for remote mode
-     * Format: dk_live_xxxx
-     *
-     * When provided, fixtures are fetched from DemoKit Cloud.
-     * Any `fixtures` prop values will override the cloud fixtures.
-     */
-    apiKey?: string;
-    /**
-     * DemoKit Cloud API URL
-     * @default 'https://api.demokit.cloud'
-     */
-    cloudUrl?: string;
-    /**
-     * Timeout for cloud API requests in milliseconds
-     * @default 10000
-     */
-    timeout?: number;
-    /**
-     * Whether to retry on fetch failure
-     * @default true
-     */
-    retry?: boolean;
-    /**
-     * Maximum number of retries for cloud fetch
-     * @default 3
-     */
-    maxRetries?: number;
-    /**
-     * Callback when remote fixtures are successfully loaded
-     */
-    onRemoteLoad?: (response: CloudFixtureResponse) => void;
-    /**
-     * Callback when remote fetch fails
-     */
-    onRemoteError?: (error: Error) => void;
-    /**
-     * Content to render while loading remote fixtures
-     * @default null (renders nothing while loading)
-     */
-    loadingFallback?: ReactNode;
-    /**
-     * Content to render when remote fetch fails
-     * If not provided, children are rendered (with local fixtures only if provided)
-     */
-    errorFallback?: ReactNode | ((error: Error) => ReactNode);
-    /**
-     * localStorage key for persisting demo mode state
-     * @default 'demokit-mode'
-     */
-    storageKey?: string;
-    /**
-     * Whether demo mode should be initially enabled
-     * If not provided, will read from localStorage
-     * @default false
-     */
-    initialEnabled?: boolean;
-    /**
-     * Callback invoked when demo mode state changes
-     */
-    onDemoModeChange?: (enabled: boolean) => void;
-    /**
-     * Base URL to use for relative URL parsing
-     * @default 'http://localhost'
-     */
-    baseUrl?: string;
-}
-/**
- * Value provided by the DemoMode context
- */
-interface DemoModeContextValue {
-    /**
-     * Whether demo mode is currently enabled
-     */
-    isDemoMode: boolean;
-    /**
-     * Whether the component has hydrated (for SSR safety)
-     * Always check this before rendering demo-dependent UI
-     */
-    isHydrated: boolean;
-    /**
-     * Whether remote fixtures are currently being loaded
-     * Only relevant when apiKey is provided
-     */
-    isLoading: boolean;
-    /**
-     * Error that occurred during remote fetch
-     * Only set when apiKey is provided and fetch fails
-     */
-    remoteError: Error | null;
-    /**
-     * Version identifier from the loaded cloud fixtures
-     * Useful for cache invalidation and debugging
-     */
-    remoteVersion: string | null;
-    /**
-     * Enable demo mode
-     */
-    enable(): void;
-    /**
-     * Disable demo mode
-     */
-    disable(): void;
-    /**
-     * Toggle demo mode and return the new state
-     */
-    toggle(): void;
-    /**
-     * Set demo mode to a specific state
-     */
-    setDemoMode(enabled: boolean): void;
-    /**
-     * Reset the session state, clearing all stored data
-     * Call this to manually reset the demo session without page refresh
-     */
-    resetSession(): void;
-    /**
-     * Get the current session state instance
-     * Useful for inspecting or manipulating session state directly
-     * Returns null if the interceptor hasn't been initialized yet
-     */
-    getSession(): SessionState | null;
-    /**
-     * Refetch fixtures from DemoKit Cloud
-     * Only works when apiKey is provided
-     * Returns a promise that resolves when the fetch completes
-     */
-    refetch(): Promise<void>;
-}
-/**
- * Props for the DemoModeBanner component
- */
-interface DemoModeBannerProps {
-    /**
-     * Additional CSS class name
-     */
-    className?: string;
-    /**
-     * Label for the exit button
-     * @default 'Exit Demo Mode'
-     */
-    exitLabel?: string;
-    /**
-     * Label shown when demo mode is active
-     * @default 'Demo Mode Active'
-     */
-    demoLabel?: string;
-    /**
-     * Description shown in the banner
-     * @default 'Changes are simulated and not saved'
-     */
-    description?: string;
-    /**
-     * Whether to show the eye icon
-     * @default true
-     */
-    showIcon?: boolean;
-    /**
-     * Show "Powered by DemoKit" branding
-     * Note: For OSS users, this is always true regardless of the prop value.
-     * Only paid DemoKit Cloud users can hide the branding.
-     * @default true
-     */
-    showPoweredBy?: boolean;
-    /**
-     * URL for the "Powered by" link
-     * @default 'https://demokit.ai'
-     */
-    poweredByUrl?: string;
-    /**
-     * Custom styles for the banner container
-     */
-    style?: React.CSSProperties;
-    /**
-     * Callback when exit button is clicked
-     * If not provided, will call disable() from context
-     */
-    onExit?: () => void;
-}
-
-/**
- * Provider component that enables demo mode functionality
- *
- * Wraps your app to provide demo mode state and controls.
- * Handles SSR hydration safely and persists state to localStorage.
- *
- * Supports two modes:
- * 1. **Local mode**: Pass `fixtures` prop with pattern handlers
- * 2. **Remote mode**: Pass `apiKey` to fetch from DemoKit Cloud
- *
- * @example Local mode
- * ```tsx
- * const fixtures = {
- *   'GET /api/users': () => [{ id: '1', name: 'Demo User' }],
- *   'GET /api/users/:id': ({ params }) => ({ id: params.id, name: 'Demo User' }),
- * }
- *
- * function App() {
- *   return (
- *     <DemoKitProvider fixtures={fixtures}>
- *       <YourApp />
- *     </DemoKitProvider>
- *   )
- * }
- * ```
- *
- * @example Remote mode (zero-config)
- * ```tsx
- * function App() {
- *   return (
- *     <DemoKitProvider
- *       apiKey="dk_live_xxx"
- *       loadingFallback={<LoadingSpinner />}
- *     >
- *       <YourApp />
- *     </DemoKitProvider>
- *   )
- * }
- * ```
- */
-declare function DemoKitProvider({ children, fixtures, apiKey, cloudUrl, timeout, retry, maxRetries, onRemoteLoad, onRemoteError, loadingFallback, errorFallback, storageKey, initialEnabled, onDemoModeChange, baseUrl, }: DemoKitProviderProps): react_jsx_runtime.JSX.Element;
-
-/**
- * Hook to access demo mode state and controls
- *
- * @returns Demo mode context value with state and control methods
- * @throws Error if used outside of DemoKitProvider
- *
- * @example
- * function MyComponent() {
- *   const { isDemoMode, isHydrated, toggle } = useDemoMode()
- *
- *   // Wait for hydration before rendering demo-dependent UI
- *   if (!isHydrated) {
- *     return <Loading />
- *   }
- *
- *   return (
- *     <div>
- *       <p>Demo mode: {isDemoMode ? 'ON' : 'OFF'}</p>
- *       <button onClick={toggle}>Toggle</button>
- *     </div>
- *   )
- * }
- */
-declare function useDemoMode(): DemoModeContextValue;
-/**
- * Hook to check if demo mode is enabled
- * Shorthand for useDemoMode().isDemoMode
- *
- * @returns Whether demo mode is enabled
- */
-declare function useIsDemoMode(): boolean;
-/**
- * Hook to check if the component has hydrated
- * Shorthand for useDemoMode().isHydrated
- *
- * @returns Whether the component has hydrated
- */
-declare function useIsHydrated(): boolean;
-/**
- * Hook to access the session state
- * Shorthand for useDemoMode().getSession()
- *
- * @returns The session state, or null if not yet initialized
- *
- * @example
- * function MyComponent() {
- *   const session = useDemoSession()
- *
- *   const cart = session?.get<CartItem[]>('cart') || []
- *   const addToCart = (item: CartItem) => {
- *     session?.set('cart', [...cart, item])
- *   }
- *
- *   return <CartView items={cart} onAdd={addToCart} />
- * }
- */
-declare function useDemoSession(): _demokit_ai_core.SessionState | null;
-
-/**
- * A ready-to-use banner component that shows when demo mode is active
- *
- * Displays a prominent amber banner with a label, description, and exit button.
- * Automatically hides when demo mode is disabled or before hydration.
- *
- * @example
- * function App() {
- *   return (
- *     <DemoKitProvider fixtures={fixtures}>
- *       <DemoModeBanner />
- *       <YourApp />
- *     </DemoKitProvider>
- *   )
- * }
- *
- * @example Custom labels
- * <DemoModeBanner
- *   demoLabel="Preview Mode"
- *   description="You're viewing sample data"
- *   exitLabel="Exit Preview"
- * />
- */
-declare function DemoModeBanner({ className, exitLabel, demoLabel, description, showIcon, showPoweredBy, poweredByUrl, style, onExit, }: DemoModeBannerProps): react_jsx_runtime.JSX.Element | null;
-
-/**
- * Props for the DemoModeToggle component
- */
-interface DemoModeToggleProps {
-    /**
-     * Show "Demo Mode" label next to the toggle
-     * @default true
-     */
-    showLabel?: boolean;
-    /**
-     * Label text to display
-     * @default 'Demo Mode'
-     */
-    label?: string;
-    /**
-     * Show "Powered by DemoKit" branding
-     * Note: For OSS users, this is always true regardless of the prop value.
-     * Only paid DemoKit Cloud users can hide the branding.
-     * @default true
-     */
-    showPoweredBy?: boolean;
-    /**
-     * URL for the "Powered by" link
-     * @default 'https://demokit.ai'
-     */
-    poweredByUrl?: string;
-    /**
-     * Position of the toggle
-     * - 'inline': Renders where placed in the component tree
-     * - 'floating': Fixed position, can be moved around
-     * - 'corner': Fixed to bottom-right corner
-     * @default 'inline'
-     */
-    position?: 'inline' | 'floating' | 'corner';
-    /**
-     * Size of the toggle
-     * @default 'md'
-     */
-    size?: 'sm' | 'md' | 'lg';
-    /**
-     * Additional CSS class name
-     */
-    className?: string;
-    /**
-     * Custom styles
-     */
-    style?: CSSProperties;
-    /**
-     * Callback when toggle state changes
-     */
-    onChange?: (enabled: boolean) => void;
-}
-/**
- * A toggle switch component for enabling/disabling demo mode
- *
- * Supports inline placement or fixed positioning (floating/corner).
- * Includes optional "Powered by DemoKit" branding that is always shown for OSS users.
- *
- * @example Basic inline usage
- * <DemoModeToggle />
- *
- * @example Corner position (floating)
- * <DemoModeToggle position="corner" />
- *
- * @example Without label
- * <DemoModeToggle showLabel={false} />
- *
- * @example With custom label and callback
- * <DemoModeToggle
- *   label="Preview Mode"
- *   onChange={(enabled) => console.log('Demo mode:', enabled)}
- * />
- */
-declare function DemoModeToggle({ showLabel, label, showPoweredBy, poweredByUrl, position, size, className, style, onChange, }: DemoModeToggleProps): react_jsx_runtime.JSX.Element | null;
-
-/**
- * Props for the PoweredByBadge component
- */
-interface PoweredByBadgeProps {
-    /**
-     * URL to link to when clicked
-     * @default 'https://demokit.ai'
-     */
-    url?: string;
-    /**
-     * Visual variant for light/dark backgrounds
-     * @default 'auto'
-     */
-    variant?: 'light' | 'dark' | 'auto';
-    /**
-     * Size of the badge
-     * @default 'sm'
-     */
-    size?: 'xs' | 'sm' | 'md';
-    /**
-     * Additional CSS class name
-     */
-    className?: string;
-    /**
-     * Custom styles
-     */
-    style?: CSSProperties;
-}
-/**
- * A "Powered by DemoKit" badge that links to demokit.ai
- *
- * This badge is shown by default for OSS users and cannot be hidden
- * without a valid DemoKit Cloud paid plan.
- *
- * @example
- * <PoweredByBadge />
- *
- * @example With dark theme
- * <PoweredByBadge variant="dark" />
- *
- * @example Small size
- * <PoweredByBadge size="xs" />
- */
-declare function PoweredByBadge({ url, variant, size, className, style, }: PoweredByBadgeProps): react_jsx_runtime.JSX.Element;
-
-/**
- * React context for demo mode state
- * @internal
- */
-declare const DemoModeContext: react.Context<DemoModeContextValue | undefined>;
-
-export { DemoKitProvider, type DemoKitProviderProps, DemoModeBanner, type DemoModeBannerProps, DemoModeContext, type DemoModeContextValue, DemoModeToggle, type DemoModeToggleProps, PoweredByBadge, type PoweredByBadgeProps, useDemoMode, useDemoSession, useIsDemoMode, useIsHydrated };