@donotdev/core 0.0.18 → 0.0.20

package/next/index.d.ts

@@ -1,763 +1,4 @@
 import * as React from 'react';
-import { ReactNode } from 'react';
-
-// packages/core/types/src/auth/constants.ts
-
-
-
-// =============================================================================
-// User Role Constants
-// =============================================================================
-
-/**
- * Standard user role names
- * Apps can override these by providing their own role constants
- *
- * @version 0.0.1
- * @since 0.0.1
- * @author AMBROISE PARK Consulting
- */
-declare const USER_ROLES = {
-  GUEST: 'guest',
-  USER: 'user',
-  ADMIN: 'admin',
-  SUPER: 'super',
-} as const;
-
-/**
- * Type for user role names
- * Apps can extend this with their own custom roles
- *
- * @version 0.0.1
- * @since 0.0.1
- * @author AMBROISE PARK Consulting
- */
-type UserRole = (typeof USER_ROLES)[keyof typeof USER_ROLES] | string;
-
-// =============================================================================
-// Subscription Tier Constants
-// =============================================================================
-
-/**
- * Standard subscription tier names
- * Apps can override these by providing their own tier constants
- *
- * @version 0.0.1
- * @since 0.0.1
- * @author AMBROISE PARK Consulting
- */
-declare const SUBSCRIPTION_TIERS = {
-  FREE: 'free',
-  PRO: 'pro',
-  PREMIUM: 'premium',
-} as const;
-
-/**
- * Type for subscription tier names
- * Apps can extend this with their own custom tiers
- *
- * @version 0.0.1
- * @since 0.0.1
- * @author AMBROISE PARK Consulting
- */
-type SubscriptionTier =
-  | (typeof SUBSCRIPTION_TIERS)[keyof typeof SUBSCRIPTION_TIERS]
-  | string;
-
-// packages/core/types/src/common/index.ts
-
-
-
-// =============================================================================
-// PLATFORM CONSTANTS
-// =============================================================================
-
-/**
- * Supported platform identifiers
- * @constant
- */
-declare const PLATFORMS = {
-  VITE: 'vite',
-  NEXTJS: 'nextjs',
-  UNKNOWN: 'unknown',
-} as const;
-
-/**
- * Platform type derived from PLATFORMS constant
- */
-type Platform = (typeof PLATFORMS)[keyof typeof PLATFORMS];
-
-// =============================================================================
-// ENVIRONMENT CONSTANTS
-// =============================================================================
-
-/**
- * Supported environment modes
- * @constant
- */
-declare const ENVIRONMENTS = {
-  DEVELOPMENT: 'development',
-  PRODUCTION: 'production',
-  TEST: 'test',
-} as const;
-
-/**
- * Environment mode type derived from ENVIRONMENTS constant
- */
-type EnvironmentMode = (typeof ENVIRONMENTS)[keyof typeof ENVIRONMENTS];
-
-// =============================================================================
-// CONTEXT CONSTANTS
-// =============================================================================
-
-/**
- * Supported execution contexts
- * @constant
- */
-declare const CONTEXTS = {
-  CLIENT: 'client',
-  SERVER: 'server',
-  BUILD: 'build',
-} as const;
-
-/**
- * Context type derived from CONTEXTS constant
- */
-type Context = (typeof CONTEXTS)[keyof typeof CONTEXTS];
-
-// =============================================================================
-// STORAGE CONSTANTS
-// =============================================================================
-
-/**
- * Supported storage backend types
- * @constant
- */
-declare const STORAGE_TYPES = {
-  LOCAL: 'localStorage',
-  SESSION: 'sessionStorage',
-  INDEXED_DB: 'indexedDB',
-  MEMORY: 'memory',
-} as const;
-
-/**
- * Storage type derived from STORAGE_TYPES constant
- */
-type StorageType = (typeof STORAGE_TYPES)[keyof typeof STORAGE_TYPES];
-
-// =============================================================================
-// PWA CONSTANTS
-// =============================================================================
-
-/**
- * PWA display modes
- * @constant
- */
-declare const PWA_DISPLAY_MODES = {
-  STANDALONE: 'standalone',
-  FULLSCREEN: 'fullscreen',
-  MINIMAL_UI: 'minimal-ui',
-  BROWSER: 'browser',
-} as const;
-
-/**
- * PWA display mode type derived from PWA_DISPLAY_MODES constant
- */
-type PWADisplayMode =
-  (typeof PWA_DISPLAY_MODES)[keyof typeof PWA_DISPLAY_MODES];
-
-/**
- * PWA asset types
- * @constant
- */
-declare const PWA_ASSET_TYPES = {
-  MANIFEST: 'manifest',
-  SERVICE_WORKER: 'service-worker',
-  ICON: 'icon',
-} as const;
-
-/**
- * PWA asset type derived from PWA_ASSET_TYPES constant
- */
-type PWAAssetType =
-  (typeof PWA_ASSET_TYPES)[keyof typeof PWA_ASSET_TYPES];
-
-// =============================================================================
-// ROUTE DISCOVERY CONSTANTS
-// =============================================================================
-
-/**
- * Route discovery sources
- * @constant
- */
-declare const ROUTE_SOURCES = {
-  AUTO: 'auto-discovery',
-  MANUAL: 'manual',
-  HYBRID: 'hybrid',
-} as const;
-
-/**
- * Route source type derived from ROUTE_SOURCES constant
- */
-type RouteSource = (typeof ROUTE_SOURCES)[keyof typeof ROUTE_SOURCES];
-
-// =============================================================================
-// AUTHENTICATION TYPES
-// =============================================================================
-
-/**
- * Page-level authentication requirements
- * @description Used in PageMeta and NavigationRoute for route-level auth
- */
-type PageAuth =
-  | boolean
-  | {
-      /** Whether authentication is required */
-      required?: boolean;
-      /** Required user role */
-      role?: UserRole;
-      /** Required subscription tier */
-      tier?: SubscriptionTier;
-      /** Custom validation function */
-      validate?: (role: string, tier: string) => boolean;
-    };
-
-// =============================================================================
-// PAGE METADATA TYPES
-// =============================================================================
-
-/**
- * Page metadata interface for route discovery and configuration
- *
- * @remarks
- * **ALL PROPERTIES ARE OPTIONAL** - Framework provides smart defaults:
- *
- * - `auth`: false (public) by default - YOU must specify auth requirements explicitly
- * - `title`: Auto-extracted from filename (ShowcasePage → "Showcase")
- * - `entity`: Auto-extracted from path (pages/showcase/ → "showcase")
- * - `action`: Auto-extracted from filename patterns (ListPage → "list", FormPage → "form")
- * - `route`: Only needed for custom paths or dynamic routes like :id, :slug
- *
- * @example Simple page (no meta needed):
- * ```tsx
- * export function HomePage() {
- *   return <PageContainer>...</PageContainer>;
- * }
- * // Framework provides: auth=false, title from home.title, entity=home
- * ```
- *
- * @example Dynamic route (string format - explicit path):
- * ```tsx
- * export const meta: PageMeta = {
- *   route: '/blog/:slug'  // Creates /blog/:slug
- * };
- * // Framework provides: auth=false, title from blog.title, entity=blog
- * ```
- *
- * @example Dynamic route (object format - auto-generates base path):
- * ```tsx
- * export const meta: PageMeta = {
- *   route: { params: ['id'] }  // Creates /myRoute/:id (base path from file location)
- * };
- * // For file at pages/myRoute/DetailPage.tsx → route becomes /myRoute/:id
- * ```
- *
- * @example Auth-required (developer must be explicit):
- * ```tsx
- * export const meta: PageMeta = {
- *   auth: { required: true }  // YOU decide what needs auth
- * };
- * ```
- */
-interface PageMeta {
-  /** Authentication requirements for this route */
-  auth?: PageAuth;
-
-  /** Route configuration - just define the exact path you want */
-  route?: string | { params?: string[] };
-
-  /** Page title (optional - framework auto-extracts from filename if not provided) */
-  title?: string;
-
-  /**
-   * Translation/SEO namespace for this page
-   * @description Used for meta tags and translations
-   */
-  namespace?: string;
-
-  /**
-   * Icon for navigation (optional - framework provides smart defaults)
-   * @description **ONLY lucide-react JSX components** - extracted as component name string at build time for tree-shaking.
-   *
-   * **RESTRICTIONS:**
-   * - ✅ Only: `<Rocket />`, `<ShoppingCart />`, `<Home />` (lucide-react JSX components)
-   * - ❌ NOT: Emojis (`"🚀"`), strings (`"Rocket"`), or custom ReactNode
-   *
-   * **Why?** This is for build-time extraction and tree-shaking. The component name is extracted and stored as a string.
-   *
-   * **For flexible icons** (emojis, strings, custom components), use the `Icon` component directly in your JSX, not in PageMeta.
-   *
-   * @example
-   * ```tsx
-   * import { Rocket } from 'lucide-react';
-   * export const meta: PageMeta = {
-   *   icon: <Rocket />  // ✅ Correct - lucide-react component
-   * };
-   * ```
-   *
-   * @example
-   * ```tsx
-   * // ❌ WRONG - Don't use emojis or strings in PageMeta
-   * export const meta: PageMeta = {
-   *   icon: "🚀"  // ❌ Not supported in PageMeta
-   * };
-   * ```
-   */
-  icon?: ReactNode;
-
-  /**
-   * Hide from navigation menu (default: false - shows in navigation)
-   * @description Set to true to exclude this route from navigation menus
-   * @default false
-   * @example
-   * ```tsx
-   * export const meta: PageMeta = {
-   *   hideFromMenu: true // Won't appear in HeaderNavigation, Sidebar, etc.
-   * };
-   * ```
-   */
-  hideFromMenu?: boolean;
-}
-
-/**
- * Route metadata (discovery-generated)
- * @description Complete route metadata including auto-discovered fields from RouteDiscovery
- *
- * This extends PageMeta with fields that are automatically discovered from file paths:
- * - `entity`: Auto-extracted from path (pages/showcase/ → "showcase")
- * - `action`: Auto-extracted from filename patterns (ListPage → "list", FormPage → "form")
- *
- * These fields are always present in discovered routes but cannot be set in PageMeta.
- *
- * @version 0.0.1
- * @since 0.0.1
- * @author AMBROISE PARK Consulting
- */
-interface RouteMeta extends PageMeta {
-  /** Entity/domain grouping - auto-discovered from file path (not user-configurable) */
-  entity?: string;
-  /** Action type for route categorization - auto-discovered from filename patterns (not user-configurable) */
-  action?: string | null;
-  /** File path where route was discovered */
-  file?: string;
-}
-
-// =============================================================================
-// PLUGIN CONFIGURATION TYPES
-// =============================================================================
-
-/**
- * i18n Plugin Configuration
- * @description Configuration for internationalization system
- */
-interface I18nPluginConfig {
-  /** Mapping of language → namespace → loader function */
-  mapping: Record<string, Record<string, () => Promise<any>>>;
-  /** List of available language codes */
-  languages: string[];
-  /** List of eagerly loaded namespace identifiers */
-  eager: string[];
-  /** Fallback language code */
-  fallback: string;
-  /** Preloaded translation content (optional) */
-  content?: Record<string, Record<string, any>>;
-  /** Storage configuration */
-  storage: {
-    /** Storage backend type */
-    type: StorageType;
-    /** Storage key prefix */
-    prefix: string;
-    /** Time-to-live in seconds */
-    ttl: number;
-    /** Whether to encrypt stored data */
-    encryption: boolean;
-    /** Maximum storage size in bytes */
-    maxSize: number;
-  };
-  /** Performance configuration */
-  performance: {
-    /** Maximum cache size */
-    cacheSize: number;
-    /** Error cache TTL in seconds */
-    errorCacheTTL: number;
-  };
-  /** Discovery manifest metadata */
-  manifest: {
-    /** Total number of translation files */
-    totalFiles: number;
-    /** Total number of namespaces */
-    totalNamespaces: number;
-    /** Total number of languages */
-    totalLanguages: number;
-    /** Number of eagerly loaded namespaces */
-    eagerNamespaces: number;
-    /** ISO timestamp of generation */
-    generatedAt: string;
-  };
-  /** Whether debug mode is enabled */
-  debug: boolean;
-}
-
-/**
- * Routes Plugin Configuration
- * @description Complete route configuration populated by discovery system
- */
-interface RoutesPluginConfig {
-  /**
-   * Array of discovered routes
-   * @description All routes discovered by the route discovery system
-   */
-  mapping: Array<{
-    /**
-     * URL path for the route (platform-agnostic)
-     * @description The URL path that users see in their browser
-     * @example '/showcase/layouts', '/users/:id', '/dashboard'
-     */
-    path: string;
-
-    /**
-     * Lazy component reference (Vite-specific)
-     * @description React.lazy() component for code splitting
-     * @example lazy(() => import("/src/pages/showcase/LayoutsPage"))
-     */
-    component: any;
-
-    /**
-     * Absolute file system path (Next.js-specific)
-     * @description The absolute path to the component file
-     * @example '/src/pages/showcase/LayoutsPage.tsx'
-     */
-    importPath: string;
-
-    /**
-     * Export name for named exports
-     * @example 'HomePage', 'AboutPage'
-     */
-    exportName?: string;
-
-    /**
-     * Authentication configuration (platform-agnostic)
-     * @description Defines whether the route requires authentication
-     */
-    auth: PageAuth;
-
-    /**
-     * Route metadata (platform-agnostic)
-     * @description Additional information about the route, including auto-discovered fields
-     */
-    meta: RouteMeta;
-  }>;
-
-  /**
-   * Discovery metadata and statistics
-   * @description Information about the route discovery process
-   */
-  manifest: {
-    /** Total number of discovered routes */
-    totalRoutes: number;
-    /** Number of routes requiring authentication */
-    authRequired: number;
-    /** Number of public routes */
-    publicRoutes: number;
-    /** Source of routes (auto-discovery vs manual) */
-    source: RouteSource;
-    /** ISO timestamp when routes were generated */
-    generatedAt: string;
-  };
-}
-
-/**
- * Themes Plugin Configuration
- * @description Configuration for theme discovery and management
- */
-interface ThemesPluginConfig {
-  /** Mapping of theme names to theme configurations */
-  mapping: Record<string, any>;
-  /** Array of discovered themes */
-  discovered: Array<{
-    /** Theme identifier */
-    name: string;
-    /** Human-readable theme name */
-    displayName: string;
-    /** Whether this is a dark theme */
-    isDark: boolean;
-    /** Theme metadata */
-    meta: {
-      /** Icon identifier */
-      icon: string;
-      /** Theme description */
-      description?: string;
-      /** Theme category */
-      category?: string;
-      /** Theme author */
-      author?: string;
-      /** Additional metadata */
-      [key: string]: any;
-    };
-    /** Source file path */
-    source: string;
-    /** Whether theme is essential (cannot be disabled) */
-    essential: boolean;
-  }>;
-  /** CSS custom property variables */
-  variables: Record<string, string>;
-  /** Utility class mappings */
-  utilities: Record<string, Record<string, string>>;
-  /** Discovery manifest metadata */
-  manifest: {
-    /** Total number of discovered themes */
-    totalThemes: number;
-    /** Total number of CSS variables */
-    totalVariables: number;
-    /** Total number of utility classes */
-    totalUtilities: number;
-    /** ISO timestamp of generation */
-    generatedAt: string;
-  };
-}
-
-/**
- * Assets Plugin Configuration
- * @description Configuration for static asset management
- */
-interface AssetsPluginConfig {
-  /** Mapping of asset paths to asset metadata */
-  mapping: Record<string, any>;
-  /** SVG content of logo.svg for inline rendering with CSS variable theming */
-  logoSvgContent?: string | null;
-  /** Discovery manifest metadata */
-  manifest: {
-    /** Total number of discovered assets */
-    totalAssets: number;
-    /** ISO timestamp of generation */
-    generatedAt: string;
-  };
-}
-
-/**
- * PWA Plugin Configuration
- * @description Configuration for Progressive Web App features
- */
-interface PWAPluginConfig {
-  /** Array of PWA assets */
-  assets: Array<{
-    /** Type of PWA asset */
-    type: PWAAssetType;
-    /** Asset file path */
-    path: string;
-    /** Asset file size in bytes */
-    size?: number;
-    /** Asset content (for inline assets) */
-    content?: any;
-    /** Asset format (for images) */
-    format?: string;
-    /** Asset purpose (for icons) */
-    purpose?: string;
-  }>;
-  /** PWA manifest configuration */
-  manifest: {
-    /** Application name */
-    name: string;
-    /** Short application name */
-    short_name: string;
-    /** Application description */
-    description: string;
-    /** Start URL */
-    start_url: string;
-    /** Display mode */
-    display: PWADisplayMode;
-    /** Background color */
-    background_color: string;
-    /** Theme color */
-    theme_color: string;
-    /** Array of app icons */
-    icons: Array<{
-      /** Icon source path */
-      src: string;
-      /** Icon sizes (e.g., '192x192') */
-      sizes: string;
-      /** Icon MIME type */
-      type: string;
-      /** Icon purpose (e.g., 'any', 'maskable') */
-      purpose: string;
-    }>;
-  };
-  /** Discovery manifest metadata */
-  manifestInfo: {
-    /** Total number of PWA assets */
-    totalAssets: number;
-    /** Total number of icons */
-    totalIcons: number;
-    /** Whether service worker is present */
-    hasServiceWorker: boolean;
-    /** ISO timestamp of generation */
-    generatedAt: string;
-  };
-}
-
-/**
- * Features Plugin Configuration
- * @description Configuration for feature discovery and enablement
- *
- * @remarks
- * This interface defines the structure for feature discovery data that is populated
- * at build time and made available at runtime for feature availability checking.
- *
- * @example
- * ```typescript
- * // Generated by feature discovery system
- * const featuresConfig: FeaturesPluginConfig = {
- *   available: ['auth', 'billing', 'i18n', 'oauth'],
- *   enabled: ['auth', 'i18n'],
- *   overridden: false
- * };
- * ```
- */
-interface FeaturesPluginConfig {
-  /**
-   * List of all available features discovered in packages/features/
-   * @example ['auth', 'billing', 'i18n', 'oauth']
-   */
-  available: string[];
-}
-
-// =============================================================================
-// FRAMEWORK CONFIGURATION
-// =============================================================================
-
-/**
- * Complete DoNotDev framework configuration structure
- * @description Single source of truth for all framework configuration
- *
- * @remarks
- * All discovery plugins add their data to this unified config.
- * Available at runtime via globalThis._DNDEV_CONFIG_ or window._DNDEV_CONFIG_
- */
-interface DndevFrameworkConfig {
-  /** Framework platform (Vite or Next.js) */
-  platform: Platform;
-  /** Current environment mode */
-  mode: EnvironmentMode;
-  /** Framework version */
-  version: string;
-  /** Execution context */
-  context: Context;
-  /** Unix timestamp of config generation */
-  timestamp: number;
-  /** i18n plugin configuration (optional) */
-  i18n?: I18nPluginConfig;
-  /** Routes plugin configuration (optional) */
-  routes?: RoutesPluginConfig;
-  /** Themes plugin configuration (optional) */
-  themes?: ThemesPluginConfig;
-  /** Assets plugin configuration (optional) */
-  assets?: AssetsPluginConfig;
-  /** PWA plugin configuration (optional) */
-  pwa?: PWAPluginConfig;
-  /** Features plugin configuration (optional) */
-  features?: FeaturesPluginConfig;
-  /** Environment variables (VITE_* variables from .env files) */
-  env?: Record<string, string>;
-}
-
-// =============================================================================
-// GLOBAL AUGMENTATIONS
-// =============================================================================
-
-declare global {
-  interface Window {
-    /**
-     * Single source of truth for all DoNotDev framework configuration
-     * @description Set by platform detection and populated by discovery plugins
-     */
-    _DNDEV_CONFIG_?: DndevFrameworkConfig;
-
-    /**
-     * Global store registry for singleton Zustand stores
-     * @description Ensures single instance across code-split chunks
-     */
-    _DNDEV_STORES_?: Record<string, any>;
-
-    /** PapaParse CSV parser library (external) */
-    Papa?: {
-      parse: (input: string | File, config?: any) => any;
-      unparse: (data: any[], config?: any) => string;
-    };
-
-    /** Sentry error tracking library (external) */
-    Sentry?: {
-      captureException: (error: unknown) => void;
-      withScope: (callback: (scope: any) => void) => void;
-      getClient: () => { close: () => Promise<boolean> } | undefined;
-    };
-
-    /**
-     * Google APIs (Maps, One Tap, etc.)
-     * @description Unified type for all Google services
-     */
-    google?: {
-      /** Google Maps API */
-      maps?: {
-        places?: {
-          AutocompleteService: new () => any;
-          PlacesService: new (element: HTMLElement) => any;
-          PlacesServiceStatus: {
-            OK: string;
-          };
-        };
-        [key: string]: any;
-      };
-      /** Google Identity Services (One Tap) */
-      accounts?: {
-        id?: {
-          initialize: (config: any) => void;
-          prompt: (callback?: (notification: any) => void) => void;
-          cancel?: () => void;
-          disableAutoSelect?: () => void;
-        };
-      };
-      [key: string]: any;
-    };
-
-    /** FedCM Identity Credential API */
-    IdentityCredential?: any;
-  }
-
-  namespace NodeJS {
-    interface ProcessEnv {
-      /** Serialized framework config for Node.js environment */
-      _DNDEV_CONFIG_?: string;
-    }
-  }
-
-  namespace globalThis {
-    /** Framework configuration (same as window._DNDEV_CONFIG_) */
-    var _DNDEV_CONFIG_: DndevFrameworkConfig | undefined;
-    /** Store registry (same as window._DNDEV_STORES_) */
-    var _DNDEV_STORES_: Record<string, any> | undefined;
-
-    // Third-party framework globals (not owned by DoNotDev)
-    var __vite_plugin_react_preamble_installed__: boolean | undefined;
-    var __vite_hmr_port: number | undefined;
-    var __NEXT_DATA__: any | undefined;
-    var __REACT_QUERY_CLIENT__: any | undefined;
-    var __REACT_QUERY_PROVIDER__: any | undefined;
-    var __DNDEV_DEBUG: boolean | undefined;
-    var __FIREBASE_DEMO_MODE__: boolean | undefined;
-    // gc is already defined by Node.js globals - removed to avoid TS 5.9+ conflict
-    var getAvailableThemes: (() => string[]) | undefined;
-  }
-}
 
 type $MergeBy<T, K> = Omit<T, keyof K> & K;
 
@@ -931,9 +172,6 @@ interface AppMetadata {
   /** Short application name for mobile/compact displays (defaults to name if not set) */
   shortName?: string;
 
-  /** Application URL (base URL for production, defaults to localhost in development) */
-  url?: string;
-
   /** Application description */
   description?: string;
 
@@ -1079,7 +317,7 @@ interface AuthConfig {
 interface SEOConfig {
   /** Enable automatic SEO (default: true) */
   enabled?: boolean;
-  /** Base URL for SEO files (robots.txt, sitemap.xml) - defaults to appConfig.app.url (set at build time) */
+  /** Base URL for SEO files (robots.txt, sitemap.xml) - reads from VITE_APP_URL/NEXT_PUBLIC_APP_URL env var */
   baseUrl?: string;
   /** Site name for SEO - defaults to APP_NAME from app.ts */
   siteName?: string;
@@ -1421,11 +659,11 @@ interface PWAOptions {
     runtimeCaching?: Array<{
       urlPattern: RegExp | ((options: { request: Request }) => boolean);
       handler:
-        | 'CacheFirst'
-        | 'NetworkFirst'
-        | 'StaleWhileRevalidate'
-        | 'NetworkOnly'
-        | 'CacheOnly';
+      | 'CacheFirst'
+      | 'NetworkFirst'
+      | 'StaleWhileRevalidate'
+      | 'NetworkOnly'
+      | 'CacheOnly';
       options?: Record<string, any>;
     }>;
     /** Navigation fallback URL (default: '/') */
@@ -1441,15 +679,15 @@ interface PWAOptions {
     >;
     /** Background sync configuration for offline actions */
     backgroundSync?:
-      | {
-          /** Queue name for background sync (default: 'background-sync-queue') */
-          queueName?: string;
-          /** Maximum retention time in minutes (default: 24 * 60) */
-          maxRetentionTime?: number;
-          /** URL pattern for background sync routes (default: matches /api/ routes) */
-          urlPattern?: RegExp | ((options: { request: Request }) => boolean);
-        }
-      | false;
+    | {
+      /** Queue name for background sync (default: 'background-sync-queue') */
+      queueName?: string;
+      /** Maximum retention time in minutes (default: 24 * 60) */
+      maxRetentionTime?: number;
+      /** URL pattern for background sync routes (default: matches /api/ routes) */
+      urlPattern?: RegExp | ((options: { request: Request }) => boolean);
+    }
+    | false;
     [key: string]: any; // Allow other workbox options
   };
 }