@demokit-ai/react 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -1,480 +1,43 @@
-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
+ * @demokit-ai/react
  *
- * The provider supports two modes:
- * 1. **Local mode**: Provide `fixtures` prop with pattern handlers
- * 2. **Remote mode**: Provide `apiKey` to fetch from DemoKit Cloud
+ * React bindings for DemoKit - provider, hooks, and components.
  *
- * @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
+ * import { DemoKitProvider, useDemoMode, DemoModeBanner } from '@demokit-ai/react'
  *
- * @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}>
+ *       <DemoModeBanner />
  *       <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
+ * // In any component
  * 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 };
+ * @packageDocumentation
+ */
+export { DemoKitProvider } from './provider';
+export { createRemoteSource } from './config';
+export { useDemoMode, useIsDemoMode, useIsHydrated, useDemoSession } from './hooks';
+export { useDemoGuard } from './guard';
+export { DemoModeBanner } from './banner';
+export { DemoModeToggle } from './toggle';
+export { PoweredByBadge } from './powered-by';
+export { DemoModeContext } from './context';
+export type { DemoKitProviderProps, DemoModeContextValue, DemoModeBannerProps, } from './types';
+export type { UseDemoGuardOptions, DemoGuardReturn } from './guard';
+export type { DemoModeToggleProps } from './toggle';
+export type { PoweredByBadgeProps } from './powered-by';
+export type { FixtureMap, FixtureHandler, RequestContext, SessionState, RemoteConfig, DetectionConfig, MutationInterceptedContext, } from '@demokit-ai/core';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAG5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAG7C,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AACnF,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAGtC,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAG7C,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAG3C,YAAY,EACV,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,SAAS,CAAA;AAGhB,YAAY,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAGnE,YAAY,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAA;AACnD,YAAY,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAGvD,YAAY,EACV,UAAU,EACV,cAAc,EACd,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,0BAA0B,GAC3B,MAAM,kBAAkB,CAAA"}

package/dist/index.js

@@ -17,11 +17,7 @@ function DemoKitProvider({
   children,
   fixtures,
   // Remote config
-  apiKey,
-  cloudUrl,
-  timeout,
-  retry,
-  maxRetries,
+  source,
   onRemoteLoad,
   onRemoteError,
   loadingFallback = null,
@@ -30,11 +26,16 @@ function DemoKitProvider({
   storageKey = "demokit-mode",
   initialEnabled = false,
   onDemoModeChange,
-  baseUrl
+  baseUrl,
+  // Detection & guards
+  detection,
+  canDisable,
+  onMutationIntercepted
 }) {
   const [isDemoMode, setIsDemoMode] = useState(initialEnabled);
   const [isHydrated, setIsHydrated] = useState(false);
-  const [isLoading, setIsLoading] = useState(!!apiKey);
+  const [isPublicDemo, setIsPublicDemo] = useState(false);
+  const [isLoading, setIsLoading] = useState(!!source?.apiKey);
   const [remoteError, setRemoteError] = useState(null);
   const [remoteVersion, setRemoteVersion] = useState(null);
   const interceptorRef = useRef(null);
@@ -49,6 +50,9 @@ function DemoKitProvider({
         storageKey,
         initialEnabled,
         baseUrl,
+        detection,
+        canDisable,
+        onMutationIntercepted,
         onEnable: () => {
           setIsDemoMode(true);
           onDemoModeChange?.(true);
@@ -60,21 +64,22 @@ function DemoKitProvider({
       });
       const storedState = interceptorRef.current.isEnabled();
       setIsDemoMode(storedState);
+      setIsPublicDemo(interceptorRef.current.isPublicDemo());
       setIsHydrated(true);
     },
-    [storageKey, initialEnabled, baseUrl, onDemoModeChange]
+    [storageKey, initialEnabled, baseUrl, onDemoModeChange, detection, canDisable, onMutationIntercepted]
   );
   const fetchAndSetup = useCallback(async () => {
-    if (!apiKey) return;
+    if (!source?.apiKey) return;
     setIsLoading(true);
     setRemoteError(null);
     try {
       const response = await fetchCloudFixtures({
-        apiKey,
-        cloudUrl,
-        timeout,
-        retry,
-        maxRetries,
+        apiKey: source.apiKey,
+        apiUrl: source.apiUrl,
+        timeout: source.timeout,
+        retry: source.retry,
+        maxRetries: source.maxRetries,
         onLoad: onRemoteLoad,
         onError: onRemoteError
       });
@@ -95,11 +100,7 @@ function DemoKitProvider({
       setIsLoading(false);
     }
   }, [
-    apiKey,
-    cloudUrl,
-    timeout,
-    retry,
-    maxRetries,
+    source,
     fixtures,
     onRemoteLoad,
     onRemoteError,
@@ -111,7 +112,7 @@ function DemoKitProvider({
       return;
     }
     initializedRef.current = true;
-    if (apiKey) {
+    if (source?.apiKey) {
       fetchAndSetup();
     } else if (fixtures) {
       setupInterceptor(fixtures);
@@ -127,18 +128,18 @@ function DemoKitProvider({
   }, []);
   useEffect(() => {
     if (!isHydrated || isLoading) return;
-    if (apiKey && remoteFixturesRef.current) {
+    if (source?.apiKey && remoteFixturesRef.current) {
       const merged = { ...remoteFixturesRef.current, ...fixtures };
       interceptorRef.current?.setFixtures(merged);
     } else if (fixtures) {
       interceptorRef.current?.setFixtures(fixtures);
     }
-  }, [fixtures, isHydrated, isLoading, apiKey]);
+  }, [fixtures, isHydrated, isLoading, source]);
   const enable = useCallback(() => {
     interceptorRef.current?.enable();
   }, []);
   const disable = useCallback(() => {
-    interceptorRef.current?.disable();
+    return interceptorRef.current?.disable() ?? true;
   }, []);
   const toggle = useCallback(() => {
     interceptorRef.current?.toggle();
@@ -157,16 +158,17 @@ function DemoKitProvider({
     return interceptorRef.current?.getSession() ?? null;
   }, []);
   const refetch = useCallback(async () => {
-    if (!apiKey) {
-      console.warn("[DemoKit] refetch() called but no apiKey provided");
+    if (!source?.apiKey) {
+      console.warn("[DemoKit] refetch() called but no source provided");
       return;
     }
     await refetchFnRef.current?.();
-  }, [apiKey]);
+  }, [source]);
   const value = useMemo(
     () => ({
       isDemoMode,
       isHydrated,
+      isPublicDemo,
       isLoading,
       remoteError,
       remoteVersion,
@@ -181,6 +183,7 @@ function DemoKitProvider({
     [
       isDemoMode,
       isHydrated,
+      isPublicDemo,
       isLoading,
       remoteError,
       remoteVersion,
@@ -193,7 +196,7 @@ function DemoKitProvider({
       refetch
     ]
   );
-  if (isLoading && apiKey) {
+  if (isLoading && source?.apiKey) {
     return /* @__PURE__ */ jsx(DemoModeContext.Provider, { value, children: loadingFallback });
   }
   if (remoteError && errorFallback) {
@@ -203,6 +206,16 @@ function DemoKitProvider({
   return /* @__PURE__ */ jsx(DemoModeContext.Provider, { value, children });
 }
 
+// src/config.ts
+function createRemoteSource(config) {
+  return {
+    timeout: 1e4,
+    retry: true,
+    maxRetries: 3,
+    ...config
+  };
+}
+
 // src/hooks.ts
 import { useContext } from "react";
 function useDemoMode() {
@@ -224,6 +237,29 @@ function useDemoSession() {
   return useDemoMode().getSession();
 }
 
+// src/guard.ts
+import { useCallback as useCallback2 } from "react";
+function useDemoGuard(options = {}) {
+  const { isDemoMode } = useDemoMode();
+  const { onBlocked } = options;
+  const guardMutation = useCallback2(
+    (action, actionName) => {
+      if (isDemoMode) {
+        const message = actionName ? `${actionName} (simulated in demo mode)` : "Action simulated in demo mode";
+        onBlocked?.(message);
+        return false;
+      }
+      action();
+      return true;
+    },
+    [isDemoMode, onBlocked]
+  );
+  return {
+    guardMutation,
+    isDemoMode
+  };
+}
+
 // src/powered-by.tsx
 import { jsx as jsx2, jsxs } from "react/jsx-runtime";
 function ExternalLinkIcon({ size }) {
@@ -625,6 +661,8 @@ export {
   DemoModeContext,
   DemoModeToggle,
   PoweredByBadge,
+  createRemoteSource,
+  useDemoGuard,
   useDemoMode,
   useDemoSession,
   useIsDemoMode,