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

package/dist/index.d.ts

@@ -1,14 +1,13 @@
-import { HAI3Config, HAI3AppBuilder, HAI3App, ScreensetsConfig, HAI3Plugin, ChangeThemePayload, ShowPopupPayload, NavigateToScreenPayload, NavigateToScreensetPayload, SetLanguagePayload, Presets, ThemeRegistry, RouteRegistry } from './types.js';
-export { HAI3Store, LegacyTheme, PluginFactory, PluginLifecycle, PluginProvides, Preset, ThemeApplyFn, ThemeConfig } from './types.js';
+import { HAI3Config, HAI3AppBuilder, ThemesConfig, Presets, HAI3Plugin, HAI3App, ScreensetsConfig, ChangeThemePayload, ShowPopupPayload, NavigateToScreenPayload, NavigateToScreensetPayload, NavigationConfig, SetLanguagePayload, ThemeRegistry, RouteRegistry } from './types.js';
+export { HAI3Store, PluginFactory, PluginLifecycle, PluginProvides, Preset, ThemeApplyFn, ThemeConfig, UikitTheme } from './types.js';
 import { ScreensetRegistry } from '@hai3/screensets';
 export { LayoutDomain, MenuItemConfig, MenuScreenItem, ScreenConfig, ScreenId, ScreenLoader, ScreensetCategory, ScreensetDefinition as ScreensetConfig, ScreensetDefinition, ScreensetId, ScreensetRegistry, ScreensetRegistry as ScreensetRegistryContract, createScreensetRegistry, screensetRegistry } from '@hai3/screensets';
 import * as _hai3_state from '@hai3/state';
-import { AppDispatch } from '@hai3/state';
 export { AppDispatch, EffectInitializer, EventHandler, EventPayloadMap, ReducerPayload, RootState, SliceObject, Subscription, createSlice, createStore, eventBus, getStore, hasSlice, registerSlice } from '@hai3/state';
 import * as redux from 'redux';
 import * as _reduxjs_toolkit from '@reduxjs/toolkit';
 import { Reducer } from '@reduxjs/toolkit';
-export { ApiProtocol, ApiService, ApiServiceConfig, ApiServicesMap, BaseApiService, JsonCompatible, JsonObject, JsonPrimitive, JsonValue, MockMap, MockPlugin, RestProtocol, RestProtocolConfig, SseProtocol, SseProtocolConfig, apiRegistry } from '@hai3/api';
+export { ApiPlugin, ApiPluginBase, ApiPluginErrorContext, ApiProtocol, ApiRequestContext, ApiResponseContext, ApiServiceConfig, BaseApiService, BasePluginHooks, EventSourceLike, JsonCompatible, JsonObject, JsonPrimitive, JsonValue, MOCK_PLUGIN, MockEventSource, MockMap, PluginClass, ProtocolClass, ProtocolPluginType, RestMockConfig, RestMockPlugin, RestPlugin, RestPluginHooks, RestPluginWithConfig, RestProtocol, RestProtocolConfig, RestRequestContext, RestResponseContext, RestShortCircuitResponse, ShortCircuitResponse, SseConnectContext, SseMockConfig, SseMockEvent, SseMockPlugin, SsePlugin, SsePluginHooks, SsePluginWithConfig, SseProtocol, SseProtocolConfig, SseShortCircuitResponse, apiRegistry, isMockPlugin, isRestShortCircuit, isShortCircuit, isSseShortCircuit } from '@hai3/api';
 export { I18nConfig, I18nRegistryImpl as I18nRegistry, I18nRegistryImpl, I18nRegistry as I18nRegistryType, Language, LanguageDisplayMode, LanguageMetadata, SUPPORTED_LANGUAGES, TextDirection, TranslationDictionary, TranslationLoader, TranslationMap, createI18nRegistry, getLanguageMetadata, i18nRegistry } from '@hai3/i18n';
 
 /**
@@ -36,6 +35,68 @@ export { I18nConfig, I18nRegistryImpl as I18nRegistry, I18nRegistryImpl, I18nReg
  */
 declare function createHAI3(config?: HAI3Config): HAI3AppBuilder;
 
+/**
+ * Presets - Pre-configured plugin combinations
+ *
+ * Framework Layer: L2
+ */
+
+/**
+ * Full preset configuration.
+ */
+interface FullPresetConfig {
+    /** Configuration for themes plugin */
+    themes?: ThemesConfig;
+}
+/**
+ * Full preset - All plugins for the complete HAI3 experience.
+ * This is the default for `hai3 create` projects.
+ *
+ * Includes:
+ * - screensets (screenset registry, screen slice)
+ * - themes (theme registry, changeTheme action)
+ * - layout (all layout domain slices and effects)
+ * - navigation (navigateToScreen, navigateToScreenset actions)
+ * - routing (route registry auto-synced from screensets)
+ * - i18n (i18n registry, setLanguage action)
+ * - effects (effect coordination)
+ * - mock (mock mode control for API services)
+ *
+ * @param config - Optional preset configuration
+ *
+ * @example
+ * ```typescript
+ * import { applyTheme } from '@hai3/uikit';
+ *
+ * const app = createHAI3()
+ *   .use(full({ themes: { applyFn: applyTheme } }))
+ *   .build();
+ * ```
+ */
+declare function full(config?: FullPresetConfig): HAI3Plugin[];
+/**
+ * Minimal preset - Screensets + themes only.
+ * For users who want basic HAI3 patterns without full layout management.
+ *
+ * Includes:
+ * - screensets (screenset registry, screen slice)
+ * - themes (theme registry, changeTheme action)
+ */
+declare function minimal(): HAI3Plugin[];
+/**
+ * Headless preset - Screensets only.
+ * For external platform integration where you only need screenset orchestration.
+ * The external platform provides its own menu, header, navigation, etc.
+ *
+ * Includes:
+ * - screensets (screenset registry, screen slice)
+ */
+declare function headless(): HAI3Plugin[];
+/**
+ * Presets collection
+ */
+declare const presets: Presets;
+
 /**
  * createHAI3App - Convenience function for full HAI3 application
  *
@@ -44,6 +105,12 @@ declare function createHAI3(config?: HAI3Config): HAI3AppBuilder;
  * Framework Layer: L2
  */
 
+/**
+ * Combined configuration for createHAI3App.
+ * Includes both HAI3 core config and full preset config.
+ */
+interface HAI3AppConfig extends HAI3Config, FullPresetConfig {
+}
 /**
  * Create a fully configured HAI3 application.
  *
@@ -58,11 +125,15 @@ declare function createHAI3(config?: HAI3Config): HAI3AppBuilder;
  * // Default - uses full() preset
  * const app = createHAI3App();
  *
+ * // With theme apply function
+ * import { applyTheme } from '@hai3/uikit';
+ * const app = createHAI3App({ themes: { applyFn: applyTheme } });
+ *
  * // With configuration
  * const app = createHAI3App({ devMode: true });
  * ```
  */
-declare function createHAI3App(config?: HAI3Config): HAI3App;
+declare function createHAI3App(config?: HAI3AppConfig): HAI3App;
 
 /**
  * Screensets Plugin - Provides screenset registry and screen slice
@@ -106,19 +177,22 @@ declare module '@hai3/state' {
 /**
  * Themes plugin factory.
  *
+ * @param config - Optional themes configuration
  * @returns Themes plugin
  *
  * @example
  * ```typescript
+ * import { applyTheme } from '@hai3/uikit';
+ *
  * const app = createHAI3()
  *   .use(screensets())
- *   .use(themes())
+ *   .use(themes({ applyFn: applyTheme }))
  *   .build();
  *
  * app.actions.changeTheme({ themeId: 'dark' });
  * ```
  */
-declare function themes(): HAI3Plugin;
+declare function themes(config?: ThemesConfig): HAI3Plugin;
 
 /**
  * Layout Plugin - Provides all layout domain slices and effects
@@ -176,19 +250,20 @@ declare module '@hai3/state' {
 /**
  * Navigation plugin factory.
  *
+ * @param config - Optional navigation configuration
  * @returns Navigation plugin
  *
  * @example
  * ```typescript
  * const app = createHAI3()
  *   .use(screensets())
- *   .use(navigation())
+ *   .use(navigation({ base: '/app' }))
  *   .build();
  *
  * app.actions.navigateToScreen({ screensetId: 'demo', screenId: 'home' });
  * ```
  */
-declare function navigation(): HAI3Plugin;
+declare function navigation(config?: NavigationConfig): HAI3Plugin;
 
 /**
  * Routing Plugin - Provides route registry auto-synced from screensets
@@ -266,47 +341,47 @@ declare function i18n(): HAI3Plugin;
 declare function effects(): HAI3Plugin;
 
 /**
- * Presets - Pre-configured plugin combinations
+ * Mock Plugin - Centralized mock mode control
  *
  * Framework Layer: L2
+ *
+ * Automatically registers mockSlice and initializes mock effects.
+ * Apps don't need to manually call registerSlice(mockSlice) or initMockEffects().
  */
 
 /**
- * Full preset - All plugins for the complete HAI3 experience.
- * This is the default for `hai3 create` projects.
- *
- * Includes:
- * - screensets (screenset registry, screen slice)
- * - themes (theme registry, changeTheme action)
- * - layout (all layout domain slices and effects)
- * - navigation (navigateToScreen, navigateToScreenset actions)
- * - routing (route registry auto-synced from screensets)
- * - i18n (i18n registry, setLanguage action)
- * - effects (effect coordination)
+ * Mock plugin configuration
  */
-declare function full(): HAI3Plugin[];
+interface MockPluginConfig {
+    /**
+     * Enable mock mode by default.
+     * When true, mock plugins are activated immediately on app init.
+     * @default true (enabled in dev mode by default)
+     */
+    enabledByDefault?: boolean;
+}
 /**
- * Minimal preset - Screensets + themes only.
- * For users who want basic HAI3 patterns without full layout management.
+ * Mock plugin factory.
  *
- * Includes:
- * - screensets (screenset registry, screen slice)
- * - themes (theme registry, changeTheme action)
- */
-declare function minimal(): HAI3Plugin[];
-/**
- * Headless preset - Screensets only.
- * For external platform integration where you only need screenset orchestration.
- * The external platform provides its own menu, header, navigation, etc.
+ * Provides centralized mock mode control for API services.
+ * Automatically registers the mock slice and initializes mock effects.
+ * In dev mode, mock mode is enabled by default.
  *
- * Includes:
- * - screensets (screenset registry, screen slice)
- */
-declare function headless(): HAI3Plugin[];
-/**
- * Presets collection
+ * @param config - Optional plugin configuration
+ * @returns Mock plugin
+ *
+ * @example
+ * ```typescript
+ * const app = createHAI3()
+ *   .use(effects())
+ *   .use(mock())  // Automatic mock mode support (enabled in dev)
+ *   .build();
+ *
+ * // Toggle mock mode via actions
+ * app.actions.toggleMockMode(true);
+ * ```
  */
-declare const presets: Presets;
+declare function mock(config?: MockPluginConfig): HAI3Plugin;
 
 /**
  * Theme Registry - Manages theme registration and application
@@ -316,8 +391,10 @@ declare const presets: Presets;
 
 /**
  * Create a new theme registry instance.
+ *
+ * @param config - Optional configuration for the theme registry
  */
-declare function createThemeRegistry(): ThemeRegistry;
+declare function createThemeRegistry(config?: ThemesConfig): ThemeRegistry;
 
 /**
  * Route Registry - Manages routes auto-synced from screensets
@@ -566,6 +643,15 @@ declare const tenantActions: {
 
 declare const _default: redux.Reducer<TenantState>;
 
+interface MockState {
+    enabled: boolean;
+}
+declare const setMockEnabled: _reduxjs_toolkit.ActionCreatorWithPayload<boolean, "mock/setMockEnabled">;
+declare const mockSlice: _hai3_state.SliceObject<MockState>;
+declare const mockActions: {
+    setMockEnabled: _reduxjs_toolkit.ActionCreatorWithPayload<boolean, "mock/setMockEnabled">;
+};
+
 declare const LAYOUT_SLICE_NAME: "layout";
 declare const TENANT_SLICE_NAME: "app/tenant";
 /** Explicit type for layout domain reducers to avoid incorrect dts generation */
@@ -648,49 +734,52 @@ declare function clearTenantAction(): void;
 declare function setTenantLoadingState(loading: boolean): void;
 
 /**
- * Backward Compatibility Exports
- *
- * These exports provide backward compatibility with @hai3/uicore API.
- * They are singletons that mirror the old API.
+ * Mock Effects
  *
- * NOTE: These are exported for migration convenience but may be deprecated
- * in future major versions. Prefer using the plugin architecture.
+ * Listens for mock mode toggle events and manages mock plugin lifecycle.
+ * Event-driven architecture: UI emits events, effects handle plugin activation/deactivation.
  */
-
-declare const ACCOUNTS_DOMAIN: "accounts";
-
+/** Mock event names */
+declare const MockEvents: {
+    readonly Toggle: "mock/toggle";
+};
+/** Payload for mock toggle event */
+interface MockTogglePayload {
+    enabled: boolean;
+}
+declare module '@hai3/state' {
+    interface EventPayloadMap {
+        'mock/toggle': MockTogglePayload;
+    }
+}
 /**
- * Global theme registry singleton
- *
- * @deprecated Prefer using app.themeRegistry from createHAI3App()
+ * Initialize mock mode effects
+ * Call this once during app bootstrap to start listening for mock toggle events.
  */
-declare const themeRegistry: ThemeRegistry;
+declare function initMockEffects(): () => void;
 /**
- * Global route registry singleton
+ * Toggle mock mode on/off.
+ * Emits event that mockEffects handles.
  *
- * @deprecated Prefer using app.routeRegistry from createHAI3App()
+ * @example
+ * ```typescript
+ * import { toggleMockMode } from '@hai3/framework';
+ * toggleMockMode(true);  // Enable mock mode
+ * toggleMockMode(false); // Disable mock mode
+ * ```
  */
-declare const routeRegistry: RouteRegistry;
+declare function toggleMockMode(enabled: boolean): void;
+
 /**
- * Navigate to a screen by ID.
- * Simply updates the active screen in the store.
- *
- * NOTE: This is a simplified backward-compatible function.
- * For full navigation including screenset switching, use:
- * - useNavigation().navigateToScreen(screensetId, screenId) hook
- * - or app.actions.navigateToScreen({ screensetId, screenId })
+ * Backward Compatibility Exports
  *
- * @param screenId Screen ID to navigate to
- * @deprecated Use useNavigation() hook or app.actions.navigateToScreen()
- */
-declare const navigateToScreen: (screenId: string) => void;
-/**
- * Fetch current user from API
- * Returns a thunk action that fetches user data.
+ * These exports provide backward compatibility with @hai3/uicore API.
+ * They are singletons that mirror the old API.
  *
- * @deprecated Prefer using api services directly in actions
+ * NOTE: These are exported for migration convenience but may be deprecated
+ * in future major versions. Prefer using the plugin architecture.
  */
-declare const fetchCurrentUser: () => (_dispatch: AppDispatch) => void;
+declare const ACCOUNTS_DOMAIN: "accounts";
 
 /**
  * Migration Helpers - Utilities for migrating from @hai3/uicore
@@ -827,16 +916,5 @@ declare function hasLegacyUicoreState(state: unknown): state is LegacyRootState;
  * Check if a state object has the new layout structure
  */
 declare function hasNewLayoutState(state: unknown): state is RootStateWithLayout;
-/**
- * Legacy selectors placeholder
- *
- * @deprecated Named selectors are removed. Use useAppSelector hook from @hai3/react
- * with inline state access: `useAppSelector((state) => state.layout.menu)`
- *
- * Migration guide:
- * - Before: `const menu = useSelector(selectMenu);`
- * - After:  `const menu = useAppSelector((state: RootState) => state.layout.menu);`
- */
-declare const legacySelectors: {};
 
-export { ACCOUNTS_DOMAIN, ChangeThemePayload, type FooterConfig, type FooterState, HAI3App, HAI3AppBuilder, HAI3Config, HAI3Plugin, type HeaderConfig, type HeaderState, type HeaderUser, LAYOUT_SLICE_NAME, type LayoutDomainReducers, type LayoutDomainState, type LayoutState, type LegacyRootState, type LegacyUicoreState, type MenuItem, type MenuState, NavigateToScreenPayload, NavigateToScreensetPayload, type OverlayConfig, type OverlayState, type PopupConfig, type PopupSliceState, type PopupState, Presets, type RootStateWithLayout, RouteRegistry, STATE_PATH_MAPPING, type ScreenState, ScreensetsConfig, type Selector, SetLanguagePayload, ShowPopupPayload, type SidebarPosition, type SidebarState, TENANT_SLICE_NAME, type Tenant, type TenantChangedPayload, type TenantClearedPayload, TenantEvents, type TenantState, ThemeRegistry, changeTenant, clearActiveScreen, clearTenant, clearTenantAction, clearUser, closeAllPopups, closePopup, closeTopPopup, createHAI3, createHAI3App, createLegacySelector, createRouteRegistry, createThemeRegistry, effects, fetchCurrentUser, footerActions, footerSlice, full, getLayoutDomainState, hasLegacyUicoreState, hasNewLayoutState, headerActions, headerSlice, headless, hideOverlay, i18n, initTenantEffects, isDeprecationWarningsEnabled, layout, layoutDomainReducers, layoutReducer, legacySelectors, menuActions, menuSlice, minimal, navigateTo, navigateToScreen, navigation, openPopup, overlayActions, overlaySlice, popupActions, popupSlice, presets, routeRegistry, routing, screenActions, screenSlice, screensets, setActiveScreen, setDeprecationWarnings, setFooterConfig, setFooterVisible, setLoading as setHeaderLoading, setMenuCollapsed, setMenuConfig, setMenuItems, setMenuVisible, setOverlayVisible, setScreenLoading, setSidebarCollapsed, setSidebarConfig, setSidebarContent, setSidebarPosition, setSidebarTitle, setSidebarVisible, setSidebarWidth, setTenant, setTenantLoading, setTenantLoadingState, setUser, showOverlay, sidebarActions, sidebarSlice, tenantActions, _default as tenantReducer, tenantSlice, themeRegistry, themes, toggleMenu, toggleSidebar };
+export { ACCOUNTS_DOMAIN, ChangeThemePayload, type FooterConfig, type FooterState, type FullPresetConfig, HAI3App, HAI3AppBuilder, type HAI3AppConfig, HAI3Config, HAI3Plugin, type HeaderConfig, type HeaderState, type HeaderUser, LAYOUT_SLICE_NAME, type LayoutDomainReducers, type LayoutDomainState, type LayoutState, type LegacyRootState, type LegacyUicoreState, type MenuItem, type MenuState, MockEvents, type MockPluginConfig, type MockState, type MockTogglePayload, NavigateToScreenPayload, NavigateToScreensetPayload, type OverlayConfig, type OverlayState, type PopupConfig, type PopupSliceState, type PopupState, Presets, type RootStateWithLayout, RouteRegistry, STATE_PATH_MAPPING, type ScreenState, ScreensetsConfig, type Selector, SetLanguagePayload, ShowPopupPayload, type SidebarPosition, type SidebarState, TENANT_SLICE_NAME, type Tenant, type TenantChangedPayload, type TenantClearedPayload, TenantEvents, type TenantState, ThemeRegistry, ThemesConfig, changeTenant, clearActiveScreen, clearTenant, clearTenantAction, clearUser, closeAllPopups, closePopup, closeTopPopup, createHAI3, createHAI3App, createLegacySelector, createRouteRegistry, createThemeRegistry, effects, footerActions, footerSlice, full, getLayoutDomainState, hasLegacyUicoreState, hasNewLayoutState, headerActions, headerSlice, headless, hideOverlay, i18n, initMockEffects, initTenantEffects, isDeprecationWarningsEnabled, layout, layoutDomainReducers, layoutReducer, menuActions, menuSlice, minimal, mock, mockActions, mockSlice, navigateTo, navigation, openPopup, overlayActions, overlaySlice, popupActions, popupSlice, presets, routing, screenActions, screenSlice, screensets, setActiveScreen, setDeprecationWarnings, setFooterConfig, setFooterVisible, setLoading as setHeaderLoading, setMenuCollapsed, setMenuConfig, setMenuItems, setMenuVisible, setMockEnabled, setOverlayVisible, setScreenLoading, setSidebarCollapsed, setSidebarConfig, setSidebarContent, setSidebarPosition, setSidebarTitle, setSidebarVisible, setSidebarWidth, setTenant, setTenantLoading, setTenantLoadingState, setUser, showOverlay, sidebarActions, sidebarSlice, tenantActions, _default as tenantReducer, tenantSlice, themes, toggleMenu, toggleMockMode, toggleSidebar };