@hai3/framework 0.2.0-alpha.0

package/dist/types.d.ts

@@ -0,0 +1,440 @@
+import { HAI3Store as HAI3Store$1, EffectInitializer } from '@hai3/state';
+import { Reducer } from '@reduxjs/toolkit';
+import { ScreensetRegistry } from '@hai3/screensets';
+export { ScreensetRegistry } from '@hai3/screensets';
+import { ApiRegistry } from '@hai3/api';
+import { I18nRegistry } from '@hai3/i18n';
+
+/**
+ * @hai3/framework - Type Definitions
+ *
+ * Core types for HAI3 framework with plugin architecture.
+ * Integrates all SDK packages into a cohesive framework.
+ */
+
+type HAI3Store = HAI3Store$1;
+/**
+ * HAI3 Application Configuration
+ * Configuration options for creating a HAI3 application.
+ */
+interface HAI3Config {
+    /** Application name */
+    name?: string;
+    /** Enable development mode */
+    devMode?: boolean;
+    /** Enable strict mode (throws on errors) */
+    strictMode?: boolean;
+    /**
+     * Auto-navigate to first screenset on mount.
+     * When false, stays on "/" until navigateToScreen/navigateToScreenset is called.
+     * @default true
+     */
+    autoNavigate?: boolean;
+}
+/**
+ * Registerable Slice Interface
+ * Minimal interface for slices that can be registered with the framework.
+ * Used for heterogeneous slice collections where different state types are mixed.
+ *
+ * This is an internal framework type - plugins provide slices matching this structure.
+ * The Reducer type uses RTK's default, avoiding explicit `any` in HAI3 code.
+ */
+interface RegisterableSlice {
+    /** Slice name - becomes the state key */
+    readonly name: string;
+    /** Slice reducer function */
+    readonly reducer: Reducer;
+    /** Slice action creators (optional for registration) */
+    readonly actions?: Record<string, unknown>;
+}
+/**
+ * HAI3 Actions Interface
+ * Central registry of all actions available in the application.
+ *
+ * Built-in actions are defined here. Consumers can extend this interface
+ * via module augmentation to add custom actions:
+ *
+ * @example
+ * ```typescript
+ * declare module '@hai3/framework' {
+ *   interface HAI3Actions {
+ *     myCustomAction: (payload: MyPayload) => void;
+ *   }
+ * }
+ * ```
+ *
+ * Design: Interface (not type) enables TypeScript declaration merging.
+ */
+interface HAI3Actions {
+    navigateToScreen: (payload: NavigateToScreenPayload) => void;
+    navigateToScreenset: (payload: NavigateToScreensetPayload) => void;
+    changeTheme: (payload: ChangeThemePayload) => void;
+    setLanguage: (payload: SetLanguagePayload) => void;
+    showPopup: (payload: ShowPopupPayload) => void;
+    hidePopup: () => void;
+    showOverlay: (payload: {
+        id: string;
+    }) => void;
+    hideOverlay: () => void;
+    toggleMenuCollapsed: (payload: {
+        collapsed: boolean;
+    }) => void;
+    toggleSidebarCollapsed: (payload: {
+        collapsed: boolean;
+    }) => void;
+    setHeaderVisible: (payload: boolean) => void;
+    setFooterVisible: (payload: boolean) => void;
+    setMenuCollapsed: (payload: boolean) => void;
+    setSidebarCollapsed: (payload: boolean) => void;
+    setActiveScreen: (payload: string) => void;
+    setScreenLoading: (payload: boolean) => void;
+}
+/**
+ * Plugin Provides Interface
+ * What a plugin contributes to the application.
+ */
+interface PluginProvides {
+    /** Registry contributions */
+    registries?: Record<string, unknown>;
+    /** Redux slices to register */
+    slices?: RegisterableSlice[];
+    /** Effect initializers to register */
+    effects?: EffectInitializer[];
+    /** Actions provided by the plugin (subset of HAI3Actions) */
+    actions?: Partial<HAI3Actions>;
+}
+/**
+ * Plugin Lifecycle Interface
+ * Lifecycle hooks for plugin initialization.
+ */
+interface PluginLifecycle {
+    /**
+     * Called when plugin is registered (before app starts).
+     *
+     * @param app - The app builder instance
+     * @param config - Plugin configuration
+     */
+    onRegister?(app: HAI3AppBuilder, config: unknown): void;
+    /**
+     * Called after all plugins registered, before app starts.
+     *
+     * @param app - The built app instance
+     */
+    onInit?(app: HAI3App): void | Promise<void>;
+    /**
+     * Called when app is destroyed.
+     *
+     * @param app - The app instance
+     */
+    onDestroy?(app: HAI3App): void;
+}
+/**
+ * HAI3 Plugin Interface
+ * All plugins implement this contract.
+ * Follows Liskov Substitution Principle - any plugin can be used interchangeably.
+ *
+ * @template TConfig - Plugin configuration type
+ *
+ * @example
+ * ```typescript
+ * const screensetsPlugin: HAI3Plugin = {
+ *   name: 'screensets',
+ *   dependencies: [],
+ *   provides: {
+ *     registries: { screensetRegistry: createScreensetRegistry() },
+ *     slices: [screenSlice],
+ *   },
+ *   onInit(app) {
+ *     discoverScreensets(app.screensetRegistry);
+ *   },
+ * };
+ * ```
+ */
+interface HAI3Plugin<TConfig = unknown> extends PluginLifecycle {
+    /** Unique plugin identifier */
+    name: string;
+    /** Other plugins this plugin requires */
+    dependencies?: string[];
+    /** What this plugin provides to the app */
+    provides?: PluginProvides;
+    /** Plugin configuration type marker (used for type inference) */
+    _configType?: TConfig;
+}
+/**
+ * Plugin Factory Function
+ * Factory function that creates a plugin with optional configuration.
+ *
+ * @template TConfig - Plugin configuration type
+ */
+type PluginFactory<TConfig = unknown> = (config?: TConfig) => HAI3Plugin<TConfig>;
+/**
+ * HAI3 App Builder Interface
+ * Fluent builder for composing HAI3 applications with plugins.
+ *
+ * @example
+ * ```typescript
+ * const app = createHAI3()
+ *   .use(screensets())
+ *   .use(themes())
+ *   .use(layout())
+ *   .build();
+ * ```
+ */
+interface HAI3AppBuilder {
+    /**
+     * Add a plugin to the application.
+     *
+     * @param plugin - Plugin instance or factory
+     * @returns Builder for chaining
+     */
+    use(plugin: HAI3Plugin | PluginFactory): HAI3AppBuilder;
+    /**
+     * Add multiple plugins at once.
+     *
+     * @param plugins - Array of plugins or factories
+     * @returns Builder for chaining
+     */
+    useAll(plugins: Array<HAI3Plugin | PluginFactory>): HAI3AppBuilder;
+    /**
+     * Build the application.
+     * Resolves dependencies, initializes plugins, and returns the app.
+     *
+     * @returns The built HAI3 application
+     */
+    build(): HAI3App;
+}
+
+/**
+ * Theme Configuration
+ * Configuration for a theme.
+ */
+interface ThemeConfig {
+    /** Theme ID */
+    id: string;
+    /** Theme name */
+    name: string;
+    /** CSS custom properties */
+    variables: Record<string, string>;
+    /** Whether this is the default theme */
+    default?: boolean;
+}
+/**
+ * Legacy Theme type (from @hai3/uikit)
+ * Used for backward compatibility with old register(id, theme) pattern.
+ * Using 'unknown' as the base type to accept any theme structure.
+ */
+type LegacyTheme = unknown;
+/**
+ * Theme apply function type
+ * Generic to accept any theme type from UI kit implementations.
+ * @internal - uses generic function signature for compatibility with various theme implementations
+ */
+interface ThemeApplyFn {
+    (theme: unknown, themeName?: string): void;
+}
+/**
+ * Theme Registry Interface
+ * Registry for managing themes.
+ */
+interface ThemeRegistry {
+    /**
+     * Register a theme.
+     * Supports both new API (config only) and legacy API (id + theme).
+     *
+     * @param configOrId - ThemeConfig or theme ID (for legacy API)
+     * @param legacyTheme - Legacy Theme object (optional, for backward compatibility)
+     */
+    register(configOrId: ThemeConfig | string, legacyTheme?: LegacyTheme): void;
+    /**
+     * Set the apply function (legacy API).
+     * @deprecated Use the built-in apply or provide applyFn at construction.
+     */
+    setApplyFunction(applyFn: ThemeApplyFn): void;
+    /** Get theme by ID */
+    get(id: string): ThemeConfig | undefined;
+    /** Get all themes */
+    getAll(): ThemeConfig[];
+    /** Apply a theme */
+    apply(id: string): void;
+    /** Get current theme */
+    getCurrent(): ThemeConfig | undefined;
+    /**
+     * Subscribe to theme changes.
+     * @param callback - Called when theme changes
+     * @returns Unsubscribe function
+     */
+    subscribe(callback: () => void): () => void;
+    /**
+     * Get current version number.
+     * Used by React for re-rendering on theme changes.
+     */
+    getVersion(): number;
+}
+/**
+ * Route Registry Interface
+ * Registry for managing routes (auto-synced from screensets).
+ */
+interface RouteRegistry {
+    /** Check if a screen exists by screenId only (globally unique) */
+    hasScreenById(screenId: string): boolean;
+    /** Check if a screen exists (legacy, requires both IDs) */
+    hasScreen(screensetId: string, screenId: string): boolean;
+    /** Get screenset ID for a given screen ID (reverse lookup) */
+    getScreensetForScreen(screenId: string): string | undefined;
+    /** Get screen loader by screenId only */
+    getScreenById(screenId: string): (() => Promise<{
+        default: React.ComponentType;
+    }>) | undefined;
+    /** Get screen loader (legacy, requires both IDs) */
+    getScreen(screensetId: string, screenId: string): (() => Promise<{
+        default: React.ComponentType;
+    }>) | undefined;
+    /** Get all routes */
+    getAll(): Array<{
+        screensetId: string;
+        screenId: string;
+    }>;
+}
+/**
+ * HAI3 App Interface
+ * The built application with all features available.
+ *
+ * @example
+ * ```typescript
+ * const app = createHAI3App();
+ *
+ * // Access registries
+ * const screensets = app.screensetRegistry.getAll();
+ *
+ * // Access store
+ * const state = app.store.getState();
+ *
+ * // Access actions
+ * app.actions.navigateToScreen({ screensetId: 'demo', screenId: 'home' });
+ * ```
+ */
+interface HAI3App {
+    /** Application configuration */
+    config: HAI3Config;
+    /** Redux store */
+    store: HAI3Store;
+    /** Screenset registry */
+    screensetRegistry: ScreensetRegistry;
+    /** Theme registry */
+    themeRegistry: ThemeRegistry;
+    /** Route registry */
+    routeRegistry: RouteRegistry;
+    /** API registry */
+    apiRegistry: ApiRegistry;
+    /** I18n registry */
+    i18nRegistry: I18nRegistry;
+    /** All registered actions (type-safe via HAI3Actions interface) */
+    actions: HAI3Actions;
+    /** Destroy the application and cleanup resources */
+    destroy(): void;
+}
+/**
+ * Create HAI3 App Function Signature
+ * Creates a fully configured HAI3 application using the full preset.
+ *
+ * @param config - Optional configuration
+ * @returns The built HAI3 application
+ *
+ * @example
+ * ```typescript
+ * // Default - uses full() preset
+ * const app = createHAI3App();
+ *
+ * // With configuration
+ * const app = createHAI3App({ devMode: true });
+ * ```
+ */
+type CreateHAI3App = (config?: HAI3Config) => HAI3App;
+/**
+ * Create HAI3 Function Signature
+ * Creates a HAI3 app builder for custom plugin composition.
+ *
+ * @returns App builder for plugin composition
+ *
+ * @example
+ * ```typescript
+ * const app = createHAI3()
+ *   .use(screensets())
+ *   .use(themes())
+ *   .build();
+ * ```
+ */
+type CreateHAI3 = () => HAI3AppBuilder;
+/**
+ * Preset Type
+ * A preset is a function that returns an array of plugins.
+ *
+ * @example
+ * ```typescript
+ * const minimal: Preset = () => [
+ *   screensets({ autoDiscover: true }),
+ *   themes(),
+ * ];
+ * ```
+ */
+type Preset = () => HAI3Plugin[];
+/**
+ * Presets Collection
+ * Available presets for different use cases.
+ */
+interface Presets {
+    /** All plugins - default for hai3 create */
+    full: Preset;
+    /** Screensets + themes only */
+    minimal: Preset;
+    /** Screensets only - for external platform integration */
+    headless: Preset;
+}
+/**
+ * Screensets Plugin Configuration
+ * Configuration options for the screensets plugin.
+ */
+interface ScreensetsConfig {
+    /** Auto-discover screensets via glob */
+    autoDiscover?: boolean;
+    /** Glob pattern for screenset discovery */
+    globPattern?: string;
+}
+/**
+ * Navigate to Screen Payload
+ */
+interface NavigateToScreenPayload {
+    screensetId: string;
+    screenId: string;
+}
+/**
+ * Navigate to Screenset Payload
+ */
+interface NavigateToScreensetPayload {
+    screensetId: string;
+}
+/**
+ * Show Popup Payload
+ */
+interface ShowPopupPayload {
+    id: string;
+    title?: string;
+    content?: () => Promise<{
+        default: React.ComponentType;
+    }>;
+    size?: 'sm' | 'md' | 'lg' | 'xl' | 'full';
+}
+/**
+ * Change Theme Payload
+ */
+interface ChangeThemePayload {
+    themeId: string;
+}
+/**
+ * Set Language Payload
+ */
+interface SetLanguagePayload {
+    language: string;
+}
+
+export type { ChangeThemePayload, CreateHAI3, CreateHAI3App, HAI3Actions, HAI3App, HAI3AppBuilder, HAI3Config, HAI3Plugin, HAI3Store, LegacyTheme, NavigateToScreenPayload, NavigateToScreensetPayload, PluginFactory, PluginLifecycle, PluginProvides, Preset, Presets, RegisterableSlice, RouteRegistry, ScreensetsConfig, SetLanguagePayload, ShowPopupPayload, ThemeApplyFn, ThemeConfig, ThemeRegistry };

package/dist/types.js

@@ -0,0 +1 @@
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/llms.txt

@@ -0,0 +1,52 @@
+# @hai3/framework
+
+> Plugin-based application framework for HAI3 SDK. Orchestrates SDK packages into cohesive applications.
+
+Part of the HAI3 Framework Layer (L2) - depends on all SDK packages (@hai3/state, @hai3/screensets, @hai3/api, @hai3/i18n) and @hai3/uicore for layout state management.
+
+## Core API
+
+- [createHAI3](https://hai3.dev/docs/framework/create): App builder with plugin composition
+- [createHAI3App](https://hai3.dev/docs/framework/app): Convenience function (full preset)
+- [presets](https://hai3.dev/docs/framework/presets): Pre-configured plugin combinations (full, minimal, headless)
+
+## Available Plugins
+
+| Plugin | Provides |
+|--------|----------|
+| `screensets()` | screensetRegistry, screen slice |
+| `themes()` | themeRegistry, changeTheme action |
+| `layout()` | header, footer, menu, sidebar, popup, overlay slices |
+| `navigation()` | navigateToScreen, navigateToScreenset actions |
+| `routing()` | routeRegistry, URL sync |
+| `i18n()` | i18nRegistry, setLanguage action |
+| `effects()` | Core effect coordination |
+
+## Quick Start
+
+```typescript
+import { createHAI3, screensets, themes, layout, navigation, i18n } from '@hai3/framework';
+
+// Compose plugins
+const app = createHAI3()
+  .use(screensets())
+  .use(themes())
+  .use(layout())
+  .use(navigation())
+  .use(i18n())
+  .build();
+
+// Or use preset (equivalent to above)
+import { createHAI3App } from '@hai3/framework';
+const app = createHAI3App();
+
+// Access registries and actions
+app.screensetRegistry.getAll();
+app.actions.navigateToScreen({ screensetId: 'demo', screenId: 'home' });
+app.actions.changeTheme({ themeId: 'dark' });
+```
+
+## Optional
+
+- [Custom Plugins](https://hai3.dev/docs/framework/plugins): Creating custom plugins
+- [Migration Guide](https://hai3.dev/docs/framework/migration): Migrating from @hai3/uicore

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@hai3/framework",
+  "version": "0.2.0-alpha.0",
+  "description": "HAI3 framework integrating all SDK packages with plugin architecture",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js",
+      "require": "./dist/types.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "CLAUDE.md",
+    "llms.txt",
+    "commands"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.2"
+  },
+  "peerDependencies": {
+    "@hai3/state": "*",
+    "@hai3/screensets": "*",
+    "@hai3/api": "*",
+    "@hai3/i18n": "*"
+  },
+  "peerDependenciesMeta": {
+    "@hai3/state": { "optional": false },
+    "@hai3/screensets": { "optional": false },
+    "@hai3/api": { "optional": false },
+    "@hai3/i18n": { "optional": false }
+  },
+  "keywords": [
+    "hai3",
+    "framework",
+    "plugin",
+    "screenset",
+    "typescript"
+  ],
+  "author": "HAI3",
+  "license": "Apache-2.0"
+}