@demokit-ai/react 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -1,12 +1,40 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as _demokit_ai_core from '@demokit-ai/core';
-import { FixtureMap, SessionState } 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 } 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 {
     /**
@@ -14,9 +42,56 @@ interface DemoKitProviderProps {
      */
     children: ReactNode;
     /**
-     * Map of URL patterns to fixture handlers
+     * 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
      */
-    fixtures: FixtureMap;
+    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'
@@ -51,6 +126,21 @@ interface DemoModeContextValue {
      * 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
      */
@@ -78,6 +168,12 @@ interface DemoModeContextValue {
      * 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
@@ -107,6 +203,18 @@ interface DemoModeBannerProps {
      * @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
      */
@@ -124,7 +232,12 @@ interface DemoModeBannerProps {
  * Wraps your app to provide demo mode state and controls.
  * Handles SSR hydration safely and persists state to localStorage.
  *
- * @example
+ * 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' }),
@@ -132,16 +245,28 @@ interface DemoModeBannerProps {
  *
  * function App() {
  *   return (
+ *     <DemoKitProvider fixtures={fixtures}>
+ *       <YourApp />
+ *     </DemoKitProvider>
+ *   )
+ * }
+ * ```
+ *
+ * @example Remote mode (zero-config)
+ * ```tsx
+ * function App() {
+ *   return (
  *     <DemoKitProvider
- *       fixtures={fixtures}
- *       onDemoModeChange={(enabled) => console.log('Demo mode:', enabled)}
+ *       apiKey="dk_live_xxx"
+ *       loadingFallback={<LoadingSpinner />}
  *     >
  *       <YourApp />
  *     </DemoKitProvider>
  *   )
  * }
+ * ```
  */
-declare function DemoKitProvider({ children, fixtures, storageKey, initialEnabled, onDemoModeChange, baseUrl, }: DemoKitProviderProps): react_jsx_runtime.JSX.Element;
+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
@@ -224,7 +349,127 @@ declare function useDemoSession(): _demokit_ai_core.SessionState | null;
  *   exitLabel="Exit Preview"
  * />
  */
-declare function DemoModeBanner({ className, exitLabel, demoLabel, description, showIcon, style, onExit, }: DemoModeBannerProps): react_jsx_runtime.JSX.Element | null;
+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
@@ -232,4 +477,4 @@ declare function DemoModeBanner({ className, exitLabel, demoLabel, description,
  */
 declare const DemoModeContext: react.Context<DemoModeContextValue | undefined>;
 
-export { DemoKitProvider, type DemoKitProviderProps, DemoModeBanner, type DemoModeBannerProps, DemoModeContext, type DemoModeContextValue, useDemoMode, useDemoSession, useIsDemoMode, useIsHydrated };
+export { DemoKitProvider, type DemoKitProviderProps, DemoModeBanner, type DemoModeBannerProps, DemoModeContext, type DemoModeContextValue, DemoModeToggle, type DemoModeToggleProps, PoweredByBadge, type PoweredByBadgeProps, useDemoMode, useDemoSession, useIsDemoMode, useIsHydrated };