@hai3/framework 0.2.0-alpha.1 → 0.2.0-alpha.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (12) hide show
  1. package/CLAUDE.md +31 -2
  2. package/commands/hai3-quick-ref.md +1 -3
  3. package/dist/index.cjs +300 -190
  4. package/dist/index.cjs.map +1 -1
  5. package/dist/index.d.cts +160 -83
  6. package/dist/index.d.ts +160 -83
  7. package/dist/index.js +289 -175
  8. package/dist/index.js.map +1 -1
  9. package/dist/types.cjs.map +1 -1
  10. package/dist/types.d.cts +31 -15
  11. package/dist/types.d.ts +31 -15
  12. package/package.json +4 -1
package/dist/types.cjs.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"sources":["../src/types.ts"],"sourcesContent":["/**\n * @hai3/framework - Type Definitions\n *\n * Core types for HAI3 framework with plugin architecture.\n * Integrates all SDK packages into a cohesive framework.\n */\n\n// ============================================================================\n// Type Imports from SDK Packages\n// ============================================================================\n\n// From @hai3/state\nimport type {\n HAI3Store as StoreType,\n EffectInitializer,\n} from '@hai3/state';\n\nimport type { Reducer } from '@reduxjs/toolkit';\n\n// From @hai3/screensets\nimport type { ScreensetRegistry } from '@hai3/screensets';\n\n// From @hai3/api\nimport type { ApiRegistry } from '@hai3/api';\n\n// From @hai3/i18n\nimport type { I18nRegistry } from '@hai3/i18n';\n\n// Re-export HAI3Store from @hai3/store for framework consumers\nexport type HAI3Store = StoreType;\n\n// ============================================================================\n// HAI3 Configuration\n// ============================================================================\n\n/**\n * HAI3 Application Configuration\n * Configuration options for creating a HAI3 application.\n */\nexport interface HAI3Config {\n /** Application name */\n name?: string;\n /** Enable development mode */\n devMode?: boolean;\n /** Enable strict mode (throws on errors) */\n strictMode?: boolean;\n /**\n * Auto-navigate to first screenset on mount.\n * When false, stays on \"/\" until navigateToScreen/navigateToScreenset is called.\n * @default true\n */\n autoNavigate?: boolean;\n /**\n * Base path for navigation. Example: '/console' makes routes /console/*.\n * @default '/'\n */\n base?: string;\n}\n\n// ============================================================================\n// Internal Slice Types\n// ============================================================================\n\n/**\n * Registerable Slice Interface\n * Minimal interface for slices that can be registered with the framework.\n * Used for heterogeneous slice collections where different state types are mixed.\n *\n * This is an internal framework type - plugins provide slices matching this structure.\n * The Reducer type uses RTK's default, avoiding explicit `any` in HAI3 code.\n */\nexport interface RegisterableSlice {\n /** Slice name - becomes the state key */\n readonly name: string;\n /** Slice reducer function */\n readonly reducer: Reducer;\n /** Slice action creators (optional for registration) */\n readonly actions?: Record<string, unknown>;\n}\n\n// ============================================================================\n// Plugin System Types\n// ============================================================================\n\n/**\n * HAI3 Actions Interface\n * Central registry of all actions available in the application.\n *\n * Built-in actions are defined here. Consumers can extend this interface\n * via module augmentation to add custom actions:\n *\n * @example\n * ```typescript\n * declare module '@hai3/framework' {\n * interface HAI3Actions {\n * myCustomAction: (payload: MyPayload) => void;\n * }\n * }\n * ```\n *\n * Design: Interface (not type) enables TypeScript declaration merging.\n */\nexport interface HAI3Actions {\n // ==========================================================================\n // Navigation actions (from navigation plugin)\n // ==========================================================================\n navigateToScreen: (payload: NavigateToScreenPayload) => void;\n navigateToScreenset: (payload: NavigateToScreensetPayload) => void;\n\n // ==========================================================================\n // Theme actions (from themes plugin)\n // ==========================================================================\n changeTheme: (payload: ChangeThemePayload) => void;\n\n // ==========================================================================\n // I18n actions (from i18n plugin)\n // ==========================================================================\n setLanguage: (payload: SetLanguagePayload) => void;\n\n // ==========================================================================\n // Layout actions (from layout plugin)\n // ==========================================================================\n showPopup: (payload: ShowPopupPayload) => void;\n hidePopup: () => void;\n showOverlay: (payload: { id: string }) => void;\n hideOverlay: () => void;\n toggleMenuCollapsed: (payload: { collapsed: boolean }) => void;\n toggleSidebarCollapsed: (payload: { collapsed: boolean }) => void;\n setHeaderVisible: (payload: boolean) => void;\n setFooterVisible: (payload: boolean) => void;\n setMenuCollapsed: (payload: boolean) => void;\n setSidebarCollapsed: (payload: boolean) => void;\n\n // ==========================================================================\n // Screenset actions (from screensets plugin)\n // ==========================================================================\n setActiveScreen: (payload: string) => void;\n setScreenLoading: (payload: boolean) => void;\n}\n\n/**\n * Plugin Provides Interface\n * What a plugin contributes to the application.\n */\nexport interface PluginProvides {\n /** Registry contributions */\n registries?: Record<string, unknown>;\n /** Redux slices to register */\n slices?: RegisterableSlice[];\n /** Effect initializers to register */\n effects?: EffectInitializer[];\n /** Actions provided by the plugin (subset of HAI3Actions) */\n actions?: Partial<HAI3Actions>;\n}\n\n/**\n * Plugin Lifecycle Interface\n * Lifecycle hooks for plugin initialization.\n */\nexport interface PluginLifecycle {\n /**\n * Called when plugin is registered (before app starts).\n *\n * @param app - The app builder instance\n * @param config - Plugin configuration\n */\n onRegister?(app: HAI3AppBuilder, config: unknown): void;\n\n /**\n * Called after all plugins registered, before app starts.\n *\n * @param app - The built app instance\n */\n onInit?(app: HAI3App): void | Promise<void>;\n\n /**\n * Called when app is destroyed.\n *\n * @param app - The app instance\n */\n onDestroy?(app: HAI3App): void;\n}\n\n/**\n * HAI3 Plugin Interface\n * All plugins implement this contract.\n * Follows Liskov Substitution Principle - any plugin can be used interchangeably.\n *\n * @template TConfig - Plugin configuration type\n *\n * @example\n * ```typescript\n * const screensetsPlugin: HAI3Plugin = {\n * name: 'screensets',\n * dependencies: [],\n * provides: {\n * registries: { screensetRegistry: createScreensetRegistry() },\n * slices: [screenSlice],\n * },\n * onInit(app) {\n * discoverScreensets(app.screensetRegistry);\n * },\n * };\n * ```\n */\nexport interface HAI3Plugin<TConfig = unknown> extends PluginLifecycle {\n /** Unique plugin identifier */\n name: string;\n\n /** Other plugins this plugin requires */\n dependencies?: string[];\n\n /** What this plugin provides to the app */\n provides?: PluginProvides;\n\n /** Plugin configuration type marker (used for type inference) */\n _configType?: TConfig;\n}\n\n/**\n * Plugin Factory Function\n * Factory function that creates a plugin with optional configuration.\n *\n * @template TConfig - Plugin configuration type\n */\nexport type PluginFactory<TConfig = unknown> = (config?: TConfig) => HAI3Plugin<TConfig>;\n\n// ============================================================================\n// App Builder Interface\n// ============================================================================\n\n/**\n * HAI3 App Builder Interface\n * Fluent builder for composing HAI3 applications with plugins.\n *\n * @example\n * ```typescript\n * const app = createHAI3()\n * .use(screensets())\n * .use(themes())\n * .use(layout())\n * .build();\n * ```\n */\nexport interface HAI3AppBuilder {\n /**\n * Add a plugin to the application.\n *\n * @param plugin - Plugin instance or factory\n * @returns Builder for chaining\n */\n use(plugin: HAI3Plugin | PluginFactory): HAI3AppBuilder;\n\n /**\n * Add multiple plugins at once.\n *\n * @param plugins - Array of plugins or factories\n * @returns Builder for chaining\n */\n useAll(plugins: Array<HAI3Plugin | PluginFactory>): HAI3AppBuilder;\n\n /**\n * Build the application.\n * Resolves dependencies, initializes plugins, and returns the app.\n *\n * @returns The built HAI3 application\n */\n build(): HAI3App;\n}\n\n// ============================================================================\n// Built App Interface\n// ============================================================================\n\n// Re-export ScreensetRegistry from SDK - do NOT duplicate the interface\nexport type { ScreensetRegistry } from '@hai3/screensets';\n\n/**\n * Theme Configuration\n * Configuration for a theme.\n */\nexport interface ThemeConfig {\n /** Theme ID */\n id: string;\n /** Theme name */\n name: string;\n /** CSS custom properties */\n variables: Record<string, string>;\n /** Whether this is the default theme */\n default?: boolean;\n}\n\n/**\n * Legacy Theme type (from @hai3/uikit)\n * Used for backward compatibility with old register(id, theme) pattern.\n * Using 'unknown' as the base type to accept any theme structure.\n */\nexport type LegacyTheme = unknown;\n\n/**\n * Theme apply function type\n * Generic to accept any theme type from UI kit implementations.\n * @internal - uses generic function signature for compatibility with various theme implementations\n */\nexport interface ThemeApplyFn {\n (theme: unknown, themeName?: string): void;\n}\n\n/**\n * Theme Registry Interface\n * Registry for managing themes.\n */\nexport interface ThemeRegistry {\n /**\n * Register a theme.\n * Supports both new API (config only) and legacy API (id + theme).\n *\n * @param configOrId - ThemeConfig or theme ID (for legacy API)\n * @param legacyTheme - Legacy Theme object (optional, for backward compatibility)\n */\n register(configOrId: ThemeConfig | string, legacyTheme?: LegacyTheme): void;\n\n /**\n * Set the apply function (legacy API).\n * @deprecated Use the built-in apply or provide applyFn at construction.\n */\n setApplyFunction(applyFn: ThemeApplyFn): void;\n\n /** Get theme by ID */\n get(id: string): ThemeConfig | undefined;\n /** Get all themes */\n getAll(): ThemeConfig[];\n /** Apply a theme */\n apply(id: string): void;\n /** Get current theme */\n getCurrent(): ThemeConfig | undefined;\n\n /**\n * Subscribe to theme changes.\n * @param callback - Called when theme changes\n * @returns Unsubscribe function\n */\n subscribe(callback: () => void): () => void;\n\n /**\n * Get current version number.\n * Used by React for re-rendering on theme changes.\n */\n getVersion(): number;\n}\n\n/**\n * Route Registry Interface\n * Registry for managing routes (auto-synced from screensets).\n */\nexport interface RouteRegistry {\n /** Check if a screen exists by screenId only (globally unique) */\n hasScreenById(screenId: string): boolean;\n /** Check if a screen exists (legacy, requires both IDs) */\n hasScreen(screensetId: string, screenId: string): boolean;\n /** Get screenset ID for a given screen ID (reverse lookup) */\n getScreensetForScreen(screenId: string): string | undefined;\n /** Get screen loader by screenId only */\n getScreenById(screenId: string): (() => Promise<{ default: React.ComponentType }>) | undefined;\n /** Get screen loader (legacy, requires both IDs) */\n getScreen(screensetId: string, screenId: string): (() => Promise<{ default: React.ComponentType }>) | undefined;\n /** Get all routes */\n getAll(): Array<{ screensetId: string; screenId: string }>;\n}\n\n/**\n * HAI3 App Interface\n * The built application with all features available.\n *\n * @example\n * ```typescript\n * const app = createHAI3App();\n *\n * // Access registries\n * const screensets = app.screensetRegistry.getAll();\n *\n * // Access store\n * const state = app.store.getState();\n *\n * // Access actions\n * app.actions.navigateToScreen({ screensetId: 'demo', screenId: 'home' });\n * ```\n */\nexport interface HAI3App {\n /** Application configuration */\n config: HAI3Config;\n\n /** Redux store */\n store: HAI3Store;\n\n /** Screenset registry */\n screensetRegistry: ScreensetRegistry;\n\n /** Theme registry */\n themeRegistry: ThemeRegistry;\n\n /** Route registry */\n routeRegistry: RouteRegistry;\n\n /** API registry */\n apiRegistry: ApiRegistry;\n\n /** I18n registry */\n i18nRegistry: I18nRegistry;\n\n /** All registered actions (type-safe via HAI3Actions interface) */\n actions: HAI3Actions;\n\n /** Destroy the application and cleanup resources */\n destroy(): void;\n}\n\n// ============================================================================\n// Create HAI3 App Function Signature\n// ============================================================================\n\n/**\n * Create HAI3 App Function Signature\n * Creates a fully configured HAI3 application using the full preset.\n *\n * @param config - Optional configuration\n * @returns The built HAI3 application\n *\n * @example\n * ```typescript\n * // Default - uses full() preset\n * const app = createHAI3App();\n *\n * // With configuration\n * const app = createHAI3App({ devMode: true });\n * ```\n */\nexport type CreateHAI3App = (config?: HAI3Config) => HAI3App;\n\n/**\n * Create HAI3 Function Signature\n * Creates a HAI3 app builder for custom plugin composition.\n *\n * @returns App builder for plugin composition\n *\n * @example\n * ```typescript\n * const app = createHAI3()\n * .use(screensets())\n * .use(themes())\n * .build();\n * ```\n */\nexport type CreateHAI3 = () => HAI3AppBuilder;\n\n// ============================================================================\n// Preset Types\n// ============================================================================\n\n/**\n * Preset Type\n * A preset is a function that returns an array of plugins.\n *\n * @example\n * ```typescript\n * const minimal: Preset = () => [\n * screensets({ autoDiscover: true }),\n * themes(),\n * ];\n * ```\n */\nexport type Preset = () => HAI3Plugin[];\n\n/**\n * Presets Collection\n * Available presets for different use cases.\n */\nexport interface Presets {\n /** All plugins - default for hai3 create */\n full: Preset;\n /** Screensets + themes only */\n minimal: Preset;\n /** Screensets only - for external platform integration */\n headless: Preset;\n}\n\n// ============================================================================\n// Plugin Configurations\n// ============================================================================\n\n/**\n * Navigation Plugin Configuration\n * Configuration options for the navigation plugin.\n */\nexport interface NavigationConfig {\n /**\n * Base path for navigation. Overrides app.config.base if set.\n */\n base?: string;\n}\n\n/**\n * Screensets Plugin Configuration\n * Configuration options for the screensets plugin.\n */\nexport interface ScreensetsConfig {\n /** Auto-discover screensets via glob */\n autoDiscover?: boolean;\n /** Glob pattern for screenset discovery */\n globPattern?: string;\n}\n\n// ============================================================================\n// Navigation Action Payloads\n// ============================================================================\n\n/**\n * Navigate to Screen Payload\n */\nexport interface NavigateToScreenPayload {\n screensetId: string;\n screenId: string;\n}\n\n/**\n * Navigate to Screenset Payload\n */\nexport interface NavigateToScreensetPayload {\n screensetId: string;\n}\n\n/**\n * Show Popup Payload\n */\nexport interface ShowPopupPayload {\n id: string;\n title?: string;\n content?: () => Promise<{ default: React.ComponentType }>;\n size?: 'sm' | 'md' | 'lg' | 'xl' | 'full';\n}\n\n/**\n * Change Theme Payload\n */\nexport interface ChangeThemePayload {\n themeId: string;\n}\n\n/**\n * Set Language Payload\n */\nexport interface SetLanguagePayload {\n language: string;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}
1
+ {"version":3,"sources":["../src/types.ts"],"sourcesContent":["/**\n * @hai3/framework - Type Definitions\n *\n * Core types for HAI3 framework with plugin architecture.\n * Integrates all SDK packages into a cohesive framework.\n */\n\n// ============================================================================\n// Type Imports from SDK Packages\n// ============================================================================\n\n// From @hai3/state\nimport type {\n HAI3Store as StoreType,\n EffectInitializer,\n} from '@hai3/state';\n\nimport type { Reducer } from '@reduxjs/toolkit';\n\n// From @hai3/screensets\nimport type { ScreensetRegistry } from '@hai3/screensets';\n\n// From @hai3/api\nimport type { ApiRegistry } from '@hai3/api';\n\n// From @hai3/i18n\nimport type { I18nRegistry } from '@hai3/i18n';\n\n// Re-export HAI3Store from @hai3/store for framework consumers\nexport type HAI3Store = StoreType;\n\n// ============================================================================\n// HAI3 Configuration\n// ============================================================================\n\n/**\n * HAI3 Application Configuration\n * Configuration options for creating a HAI3 application.\n */\nexport interface HAI3Config {\n /** Application name */\n name?: string;\n /** Enable development mode */\n devMode?: boolean;\n /** Enable strict mode (throws on errors) */\n strictMode?: boolean;\n /**\n * Auto-navigate to first screenset on mount.\n * When false, stays on \"/\" until navigateToScreen/navigateToScreenset is called.\n * @default true\n */\n autoNavigate?: boolean;\n /**\n * Base path for navigation. Example: '/console' makes routes /console/*.\n * @default '/'\n */\n base?: string;\n}\n\n// ============================================================================\n// Internal Slice Types\n// ============================================================================\n\n/**\n * Registerable Slice Interface\n * Minimal interface for slices that can be registered with the framework.\n * Used for heterogeneous slice collections where different state types are mixed.\n *\n * This is an internal framework type - plugins provide slices matching this structure.\n * The Reducer type uses RTK's default, avoiding explicit `any` in HAI3 code.\n */\nexport interface RegisterableSlice {\n /** Slice name - becomes the state key */\n readonly name: string;\n /** Slice reducer function */\n readonly reducer: Reducer;\n /** Slice action creators (optional for registration) */\n readonly actions?: Record<string, unknown>;\n}\n\n// ============================================================================\n// Plugin System Types\n// ============================================================================\n\n/**\n * HAI3 Actions Interface\n * Central registry of all actions available in the application.\n *\n * Built-in actions are defined here. Consumers can extend this interface\n * via module augmentation to add custom actions:\n *\n * @example\n * ```typescript\n * declare module '@hai3/framework' {\n * interface HAI3Actions {\n * myCustomAction: (payload: MyPayload) => void;\n * }\n * }\n * ```\n *\n * Design: Interface (not type) enables TypeScript declaration merging.\n */\nexport interface HAI3Actions {\n // ==========================================================================\n // Navigation actions (from navigation plugin)\n // ==========================================================================\n navigateToScreen: (payload: NavigateToScreenPayload) => void;\n navigateToScreenset: (payload: NavigateToScreensetPayload) => void;\n\n // ==========================================================================\n // Theme actions (from themes plugin)\n // ==========================================================================\n changeTheme: (payload: ChangeThemePayload) => void;\n\n // ==========================================================================\n // I18n actions (from i18n plugin)\n // ==========================================================================\n setLanguage: (payload: SetLanguagePayload) => void;\n\n // ==========================================================================\n // Layout actions (from layout plugin)\n // ==========================================================================\n showPopup: (payload: ShowPopupPayload) => void;\n hidePopup: () => void;\n showOverlay: (payload: { id: string }) => void;\n hideOverlay: () => void;\n toggleMenuCollapsed: (payload: { collapsed: boolean }) => void;\n toggleSidebarCollapsed: (payload: { collapsed: boolean }) => void;\n setHeaderVisible: (payload: boolean) => void;\n setFooterVisible: (payload: boolean) => void;\n setMenuCollapsed: (payload: boolean) => void;\n setSidebarCollapsed: (payload: boolean) => void;\n\n // ==========================================================================\n // Screenset actions (from screensets plugin)\n // ==========================================================================\n setActiveScreen: (payload: string) => void;\n setScreenLoading: (payload: boolean) => void;\n\n // ==========================================================================\n // Mock actions (from mock plugin)\n // ==========================================================================\n toggleMockMode: (enabled: boolean) => void;\n}\n\n/**\n * Plugin Provides Interface\n * What a plugin contributes to the application.\n */\nexport interface PluginProvides {\n /** Registry contributions */\n registries?: Record<string, unknown>;\n /** Redux slices to register */\n slices?: RegisterableSlice[];\n /** Effect initializers to register */\n effects?: EffectInitializer[];\n /** Actions provided by the plugin (subset of HAI3Actions) */\n actions?: Partial<HAI3Actions>;\n}\n\n/**\n * Plugin Lifecycle Interface\n * Lifecycle hooks for plugin initialization.\n */\nexport interface PluginLifecycle {\n /**\n * Called when plugin is registered (before app starts).\n *\n * @param app - The app builder instance\n * @param config - Plugin configuration\n */\n onRegister?(app: HAI3AppBuilder, config: unknown): void;\n\n /**\n * Called after all plugins registered, before app starts.\n *\n * @param app - The built app instance\n */\n onInit?(app: HAI3App): void | Promise<void>;\n\n /**\n * Called when app is destroyed.\n *\n * @param app - The app instance\n */\n onDestroy?(app: HAI3App): void;\n}\n\n/**\n * HAI3 Plugin Interface\n * All plugins implement this contract.\n * Follows Liskov Substitution Principle - any plugin can be used interchangeably.\n *\n * @template TConfig - Plugin configuration type\n *\n * @example\n * ```typescript\n * const screensetsPlugin: HAI3Plugin = {\n * name: 'screensets',\n * dependencies: [],\n * provides: {\n * registries: { screensetRegistry: createScreensetRegistry() },\n * slices: [screenSlice],\n * },\n * onInit(app) {\n * discoverScreensets(app.screensetRegistry);\n * },\n * };\n * ```\n */\nexport interface HAI3Plugin<TConfig = unknown> extends PluginLifecycle {\n /** Unique plugin identifier */\n name: string;\n\n /** Other plugins this plugin requires */\n dependencies?: string[];\n\n /** What this plugin provides to the app */\n provides?: PluginProvides;\n\n /** Plugin configuration type marker (used for type inference) */\n _configType?: TConfig;\n}\n\n/**\n * Plugin Factory Function\n * Factory function that creates a plugin with optional configuration.\n *\n * @template TConfig - Plugin configuration type\n */\nexport type PluginFactory<TConfig = unknown> = (config?: TConfig) => HAI3Plugin<TConfig>;\n\n// ============================================================================\n// App Builder Interface\n// ============================================================================\n\n/**\n * HAI3 App Builder Interface\n * Fluent builder for composing HAI3 applications with plugins.\n *\n * @example\n * ```typescript\n * const app = createHAI3()\n * .use(screensets())\n * .use(themes())\n * .use(layout())\n * .build();\n * ```\n */\nexport interface HAI3AppBuilder {\n /**\n * Add a plugin to the application.\n *\n * @param plugin - Plugin instance or factory\n * @returns Builder for chaining\n */\n use(plugin: HAI3Plugin | PluginFactory): HAI3AppBuilder;\n\n /**\n * Add multiple plugins at once.\n *\n * @param plugins - Array of plugins or factories\n * @returns Builder for chaining\n */\n useAll(plugins: Array<HAI3Plugin | PluginFactory>): HAI3AppBuilder;\n\n /**\n * Build the application.\n * Resolves dependencies, initializes plugins, and returns the app.\n *\n * @returns The built HAI3 application\n */\n build(): HAI3App;\n}\n\n// ============================================================================\n// Built App Interface\n// ============================================================================\n\n// Re-export ScreensetRegistry from SDK - do NOT duplicate the interface\nexport type { ScreensetRegistry } from '@hai3/screensets';\n\n/**\n * Theme Configuration\n * Configuration for a theme.\n */\nexport interface ThemeConfig {\n /** Theme ID */\n id: string;\n /** Theme name */\n name: string;\n /** CSS custom properties */\n variables: Record<string, string>;\n /** Whether this is the default theme */\n default?: boolean;\n}\n\n/**\n * UIKit Theme type (from @hai3/uikit)\n * Used for themes that require custom apply functions (e.g., @hai3/uikit's applyTheme).\n * Using 'unknown' as the base type to accept any theme structure.\n */\nexport type UikitTheme = unknown;\n\n/**\n * Theme apply function type\n * Generic to accept any theme type from UI kit implementations.\n * @internal - uses generic function signature for compatibility with various theme implementations\n */\nexport interface ThemeApplyFn {\n (theme: unknown, themeName?: string): void;\n}\n\n/**\n * Theme Registry Interface\n * Registry for managing themes.\n */\nexport interface ThemeRegistry {\n /**\n * Register a theme.\n * Supports both config-based API and UIKit theme API.\n *\n * @param configOrId - ThemeConfig or theme ID (for UIKit themes)\n * @param uikitTheme - UIKit Theme object (optional, for @hai3/uikit themes)\n */\n register(configOrId: ThemeConfig | string, uikitTheme?: UikitTheme): void;\n\n /** Get theme by ID */\n get(id: string): ThemeConfig | undefined;\n /** Get all themes */\n getAll(): ThemeConfig[];\n /** Apply a theme */\n apply(id: string): void;\n /** Get current theme */\n getCurrent(): ThemeConfig | undefined;\n\n /**\n * Subscribe to theme changes.\n * @param callback - Called when theme changes\n * @returns Unsubscribe function\n */\n subscribe(callback: () => void): () => void;\n\n /**\n * Get current version number.\n * Used by React for re-rendering on theme changes.\n */\n getVersion(): number;\n}\n\n/**\n * Route Registry Interface\n * Registry for managing routes (auto-synced from screensets).\n */\nexport interface RouteRegistry {\n /** Check if a screen exists by screenId only (globally unique) */\n hasScreenById(screenId: string): boolean;\n /** Check if a screen exists by both screensetId and screenId (explicit lookup when screenset context is known) */\n hasScreen(screensetId: string, screenId: string): boolean;\n /** Get screenset ID for a given screen ID (reverse lookup) */\n getScreensetForScreen(screenId: string): string | undefined;\n /** Get screen loader by screenId only */\n getScreenById(screenId: string): (() => Promise<{ default: React.ComponentType }>) | undefined;\n /** Get screen loader by both screensetId and screenId (explicit lookup when screenset context is known) */\n getScreen(screensetId: string, screenId: string): (() => Promise<{ default: React.ComponentType }>) | undefined;\n /** Get all routes */\n getAll(): Array<{ screensetId: string; screenId: string }>;\n}\n\n/**\n * HAI3 App Interface\n * The built application with all features available.\n *\n * @example\n * ```typescript\n * const app = createHAI3App();\n *\n * // Access registries\n * const screensets = app.screensetRegistry.getAll();\n *\n * // Access store\n * const state = app.store.getState();\n *\n * // Access actions\n * app.actions.navigateToScreen({ screensetId: 'demo', screenId: 'home' });\n * ```\n */\nexport interface HAI3App {\n /** Application configuration */\n config: HAI3Config;\n\n /** Redux store */\n store: HAI3Store;\n\n /** Screenset registry */\n screensetRegistry: ScreensetRegistry;\n\n /** Theme registry */\n themeRegistry: ThemeRegistry;\n\n /** Route registry */\n routeRegistry: RouteRegistry;\n\n /** API registry */\n apiRegistry: ApiRegistry;\n\n /** I18n registry */\n i18nRegistry: I18nRegistry;\n\n /** All registered actions (type-safe via HAI3Actions interface) */\n actions: HAI3Actions;\n\n /** Destroy the application and cleanup resources */\n destroy(): void;\n}\n\n// ============================================================================\n// Create HAI3 App Function Signature\n// ============================================================================\n\n/**\n * Create HAI3 App Function Signature\n * Creates a fully configured HAI3 application using the full preset.\n *\n * @param config - Optional configuration\n * @returns The built HAI3 application\n *\n * @example\n * ```typescript\n * // Default - uses full() preset\n * const app = createHAI3App();\n *\n * // With configuration\n * const app = createHAI3App({ devMode: true });\n * ```\n */\nexport type CreateHAI3App = (config?: HAI3Config) => HAI3App;\n\n/**\n * Create HAI3 Function Signature\n * Creates a HAI3 app builder for custom plugin composition.\n *\n * @returns App builder for plugin composition\n *\n * @example\n * ```typescript\n * const app = createHAI3()\n * .use(screensets())\n * .use(themes())\n * .build();\n * ```\n */\nexport type CreateHAI3 = () => HAI3AppBuilder;\n\n// ============================================================================\n// Preset Types\n// ============================================================================\n\n/**\n * Preset Type\n * A preset is a function that returns an array of plugins.\n *\n * @example\n * ```typescript\n * const minimal: Preset = () => [\n * screensets({ autoDiscover: true }),\n * themes(),\n * ];\n * ```\n */\nexport type Preset = () => HAI3Plugin[];\n\n/**\n * Presets Collection\n * Available presets for different use cases.\n */\nexport interface Presets {\n /** All plugins - default for hai3 create */\n full: Preset;\n /** Screensets + themes only */\n minimal: Preset;\n /** Screensets only - for external platform integration */\n headless: Preset;\n}\n\n// ============================================================================\n// Plugin Configurations\n// ============================================================================\n\n/**\n * Navigation Plugin Configuration\n * Configuration options for the navigation plugin.\n */\nexport interface NavigationConfig {\n /**\n * Base path for navigation. Overrides app.config.base if set.\n */\n base?: string;\n}\n\n/**\n * Screensets Plugin Configuration\n * Configuration options for the screensets plugin.\n */\nexport interface ScreensetsConfig {\n /** Auto-discover screensets via glob */\n autoDiscover?: boolean;\n /** Glob pattern for screenset discovery */\n globPattern?: string;\n}\n\n/**\n * Themes Plugin Configuration\n * Configuration options for the themes plugin.\n */\nexport interface ThemesConfig {\n /**\n * Custom apply function for UIKit themes.\n * Called when a theme is applied to execute theme-specific logic.\n *\n * @example\n * ```typescript\n * import { applyTheme } from '@hai3/uikit';\n *\n * const app = createHAI3()\n * .use(themes({ applyFn: applyTheme }))\n * .build();\n * ```\n */\n applyFn?: ThemeApplyFn;\n}\n\n// ============================================================================\n// Navigation Action Payloads\n// ============================================================================\n\n/**\n * Navigate to Screen Payload\n */\nexport interface NavigateToScreenPayload {\n screensetId: string;\n screenId: string;\n}\n\n/**\n * Navigate to Screenset Payload\n */\nexport interface NavigateToScreensetPayload {\n screensetId: string;\n}\n\n/**\n * Show Popup Payload\n */\nexport interface ShowPopupPayload {\n id: string;\n title?: string;\n content?: () => Promise<{ default: React.ComponentType }>;\n size?: 'sm' | 'md' | 'lg' | 'xl' | 'full';\n}\n\n/**\n * Change Theme Payload\n */\nexport interface ChangeThemePayload {\n themeId: string;\n}\n\n/**\n * Set Language Payload\n */\nexport interface SetLanguagePayload {\n language: string;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}
package/dist/types.d.cts CHANGED
@@ -93,6 +93,7 @@ interface HAI3Actions {
93
93
  setSidebarCollapsed: (payload: boolean) => void;
94
94
  setActiveScreen: (payload: string) => void;
95
95
  setScreenLoading: (payload: boolean) => void;
96
+ toggleMockMode: (enabled: boolean) => void;
96
97
  }
97
98
  /**
98
99
  * Plugin Provides Interface
@@ -224,11 +225,11 @@ interface ThemeConfig {
224
225
  default?: boolean;
225
226
  }
226
227
  /**
227
- * Legacy Theme type (from @hai3/uikit)
228
- * Used for backward compatibility with old register(id, theme) pattern.
228
+ * UIKit Theme type (from @hai3/uikit)
229
+ * Used for themes that require custom apply functions (e.g., @hai3/uikit's applyTheme).
229
230
  * Using 'unknown' as the base type to accept any theme structure.
230
231
  */
231
- type LegacyTheme = unknown;
232
+ type UikitTheme = unknown;
232
233
  /**
233
234
  * Theme apply function type
234
235
  * Generic to accept any theme type from UI kit implementations.
@@ -244,17 +245,12 @@ interface ThemeApplyFn {
244
245
  interface ThemeRegistry {
245
246
  /**
246
247
  * Register a theme.
247
- * Supports both new API (config only) and legacy API (id + theme).
248
+ * Supports both config-based API and UIKit theme API.
248
249
  *
249
- * @param configOrId - ThemeConfig or theme ID (for legacy API)
250
- * @param legacyTheme - Legacy Theme object (optional, for backward compatibility)
250
+ * @param configOrId - ThemeConfig or theme ID (for UIKit themes)
251
+ * @param uikitTheme - UIKit Theme object (optional, for @hai3/uikit themes)
251
252
  */
252
- register(configOrId: ThemeConfig | string, legacyTheme?: LegacyTheme): void;
253
- /**
254
- * Set the apply function (legacy API).
255
- * @deprecated Use the built-in apply or provide applyFn at construction.
256
- */
257
- setApplyFunction(applyFn: ThemeApplyFn): void;
253
+ register(configOrId: ThemeConfig | string, uikitTheme?: UikitTheme): void;
258
254
  /** Get theme by ID */
259
255
  get(id: string): ThemeConfig | undefined;
260
256
  /** Get all themes */
@@ -282,7 +278,7 @@ interface ThemeRegistry {
282
278
  interface RouteRegistry {
283
279
  /** Check if a screen exists by screenId only (globally unique) */
284
280
  hasScreenById(screenId: string): boolean;
285
- /** Check if a screen exists (legacy, requires both IDs) */
281
+ /** Check if a screen exists by both screensetId and screenId (explicit lookup when screenset context is known) */
286
282
  hasScreen(screensetId: string, screenId: string): boolean;
287
283
  /** Get screenset ID for a given screen ID (reverse lookup) */
288
284
  getScreensetForScreen(screenId: string): string | undefined;
@@ -290,7 +286,7 @@ interface RouteRegistry {
290
286
  getScreenById(screenId: string): (() => Promise<{
291
287
  default: React.ComponentType;
292
288
  }>) | undefined;
293
- /** Get screen loader (legacy, requires both IDs) */
289
+ /** Get screen loader by both screensetId and screenId (explicit lookup when screenset context is known) */
294
290
  getScreen(screensetId: string, screenId: string): (() => Promise<{
295
291
  default: React.ComponentType;
296
292
  }>) | undefined;
@@ -415,6 +411,26 @@ interface ScreensetsConfig {
415
411
  /** Glob pattern for screenset discovery */
416
412
  globPattern?: string;
417
413
  }
414
+ /**
415
+ * Themes Plugin Configuration
416
+ * Configuration options for the themes plugin.
417
+ */
418
+ interface ThemesConfig {
419
+ /**
420
+ * Custom apply function for UIKit themes.
421
+ * Called when a theme is applied to execute theme-specific logic.
422
+ *
423
+ * @example
424
+ * ```typescript
425
+ * import { applyTheme } from '@hai3/uikit';
426
+ *
427
+ * const app = createHAI3()
428
+ * .use(themes({ applyFn: applyTheme }))
429
+ * .build();
430
+ * ```
431
+ */
432
+ applyFn?: ThemeApplyFn;
433
+ }
418
434
  /**
419
435
  * Navigate to Screen Payload
420
436
  */
@@ -452,4 +468,4 @@ interface SetLanguagePayload {
452
468
  language: string;
453
469
  }
454
470
 
455
- export type { ChangeThemePayload, CreateHAI3, CreateHAI3App, HAI3Actions, HAI3App, HAI3AppBuilder, HAI3Config, HAI3Plugin, HAI3Store, LegacyTheme, NavigateToScreenPayload, NavigateToScreensetPayload, NavigationConfig, PluginFactory, PluginLifecycle, PluginProvides, Preset, Presets, RegisterableSlice, RouteRegistry, ScreensetsConfig, SetLanguagePayload, ShowPopupPayload, ThemeApplyFn, ThemeConfig, ThemeRegistry };
471
+ export type { ChangeThemePayload, CreateHAI3, CreateHAI3App, HAI3Actions, HAI3App, HAI3AppBuilder, HAI3Config, HAI3Plugin, HAI3Store, NavigateToScreenPayload, NavigateToScreensetPayload, NavigationConfig, PluginFactory, PluginLifecycle, PluginProvides, Preset, Presets, RegisterableSlice, RouteRegistry, ScreensetsConfig, SetLanguagePayload, ShowPopupPayload, ThemeApplyFn, ThemeConfig, ThemeRegistry, ThemesConfig, UikitTheme };
package/dist/types.d.ts CHANGED
@@ -93,6 +93,7 @@ interface HAI3Actions {
93
93
  setSidebarCollapsed: (payload: boolean) => void;
94
94
  setActiveScreen: (payload: string) => void;
95
95
  setScreenLoading: (payload: boolean) => void;
96
+ toggleMockMode: (enabled: boolean) => void;
96
97
  }
97
98
  /**
98
99
  * Plugin Provides Interface
@@ -224,11 +225,11 @@ interface ThemeConfig {
224
225
  default?: boolean;
225
226
  }
226
227
  /**
227
- * Legacy Theme type (from @hai3/uikit)
228
- * Used for backward compatibility with old register(id, theme) pattern.
228
+ * UIKit Theme type (from @hai3/uikit)
229
+ * Used for themes that require custom apply functions (e.g., @hai3/uikit's applyTheme).
229
230
  * Using 'unknown' as the base type to accept any theme structure.
230
231
  */
231
- type LegacyTheme = unknown;
232
+ type UikitTheme = unknown;
232
233
  /**
233
234
  * Theme apply function type
234
235
  * Generic to accept any theme type from UI kit implementations.
@@ -244,17 +245,12 @@ interface ThemeApplyFn {
244
245
  interface ThemeRegistry {
245
246
  /**
246
247
  * Register a theme.
247
- * Supports both new API (config only) and legacy API (id + theme).
248
+ * Supports both config-based API and UIKit theme API.
248
249
  *
249
- * @param configOrId - ThemeConfig or theme ID (for legacy API)
250
- * @param legacyTheme - Legacy Theme object (optional, for backward compatibility)
250
+ * @param configOrId - ThemeConfig or theme ID (for UIKit themes)
251
+ * @param uikitTheme - UIKit Theme object (optional, for @hai3/uikit themes)
251
252
  */
252
- register(configOrId: ThemeConfig | string, legacyTheme?: LegacyTheme): void;
253
- /**
254
- * Set the apply function (legacy API).
255
- * @deprecated Use the built-in apply or provide applyFn at construction.
256
- */
257
- setApplyFunction(applyFn: ThemeApplyFn): void;
253
+ register(configOrId: ThemeConfig | string, uikitTheme?: UikitTheme): void;
258
254
  /** Get theme by ID */
259
255
  get(id: string): ThemeConfig | undefined;
260
256
  /** Get all themes */
@@ -282,7 +278,7 @@ interface ThemeRegistry {
282
278
  interface RouteRegistry {
283
279
  /** Check if a screen exists by screenId only (globally unique) */
284
280
  hasScreenById(screenId: string): boolean;
285
- /** Check if a screen exists (legacy, requires both IDs) */
281
+ /** Check if a screen exists by both screensetId and screenId (explicit lookup when screenset context is known) */
286
282
  hasScreen(screensetId: string, screenId: string): boolean;
287
283
  /** Get screenset ID for a given screen ID (reverse lookup) */
288
284
  getScreensetForScreen(screenId: string): string | undefined;
@@ -290,7 +286,7 @@ interface RouteRegistry {
290
286
  getScreenById(screenId: string): (() => Promise<{
291
287
  default: React.ComponentType;
292
288
  }>) | undefined;
293
- /** Get screen loader (legacy, requires both IDs) */
289
+ /** Get screen loader by both screensetId and screenId (explicit lookup when screenset context is known) */
294
290
  getScreen(screensetId: string, screenId: string): (() => Promise<{
295
291
  default: React.ComponentType;
296
292
  }>) | undefined;
@@ -415,6 +411,26 @@ interface ScreensetsConfig {
415
411
  /** Glob pattern for screenset discovery */
416
412
  globPattern?: string;
417
413
  }
414
+ /**
415
+ * Themes Plugin Configuration
416
+ * Configuration options for the themes plugin.
417
+ */
418
+ interface ThemesConfig {
419
+ /**
420
+ * Custom apply function for UIKit themes.
421
+ * Called when a theme is applied to execute theme-specific logic.
422
+ *
423
+ * @example
424
+ * ```typescript
425
+ * import { applyTheme } from '@hai3/uikit';
426
+ *
427
+ * const app = createHAI3()
428
+ * .use(themes({ applyFn: applyTheme }))
429
+ * .build();
430
+ * ```
431
+ */
432
+ applyFn?: ThemeApplyFn;
433
+ }
418
434
  /**
419
435
  * Navigate to Screen Payload
420
436
  */
@@ -452,4 +468,4 @@ interface SetLanguagePayload {
452
468
  language: string;
453
469
  }
454
470
 
455
- export type { ChangeThemePayload, CreateHAI3, CreateHAI3App, HAI3Actions, HAI3App, HAI3AppBuilder, HAI3Config, HAI3Plugin, HAI3Store, LegacyTheme, NavigateToScreenPayload, NavigateToScreensetPayload, NavigationConfig, PluginFactory, PluginLifecycle, PluginProvides, Preset, Presets, RegisterableSlice, RouteRegistry, ScreensetsConfig, SetLanguagePayload, ShowPopupPayload, ThemeApplyFn, ThemeConfig, ThemeRegistry };
471
+ export type { ChangeThemePayload, CreateHAI3, CreateHAI3App, HAI3Actions, HAI3App, HAI3AppBuilder, HAI3Config, HAI3Plugin, HAI3Store, NavigateToScreenPayload, NavigateToScreensetPayload, NavigationConfig, PluginFactory, PluginLifecycle, PluginProvides, Preset, Presets, RegisterableSlice, RouteRegistry, ScreensetsConfig, SetLanguagePayload, ShowPopupPayload, ThemeApplyFn, ThemeConfig, ThemeRegistry, ThemesConfig, UikitTheme };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hai3/framework",
3
- "version": "0.2.0-alpha.1",
3
+ "version": "0.2.0-alpha.2",
4
4
  "description": "HAI3 framework integrating all SDK packages with plugin architecture",
5
5
  "type": "module",
6
6
  "main": "./dist/index.cjs",
@@ -53,6 +53,9 @@
53
53
  "optional": false
54
54
  }
55
55
  },
56
+ "publishConfig": {
57
+ "access": "public"
58
+ },
56
59
  "keywords": [
57
60
  "hai3",
58
61
  "framework",