brix-runtime-sdk-api-web 1.0.0

package/src/types/plugin.ts

@@ -0,0 +1,344 @@
+/**
+ * Copyright 2026 Brix Platform Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * @file Plugin-Related Type Definitions
+ * @description Defines core types for the plugin system, including manifest, instance, lifecycle, etc.
+ * @module @brix/runtime-sdk-api-web/types/plugin
+ * @version 3.2.1
+ *
+ * [v3.2.1 Changes]
+ * - Removed React dependency, using framework-agnostic ComponentType definition (v3.0.4 architectural constraint fix)
+ *
+ * [v3.2 Changes]
+ * Extracted from index.ts into a standalone type file, and promoted common contracts from infra-adapters.
+ *
+ * [Design Principles]
+ * - Define common plugin contracts, adapters (MF/Iframe/Native) can extend
+ * - Use generics to support different manifest and instance types
+ * - Framework-agnostic: no dependency on React/Vue/Angular or other UI frameworks
+ */
+
+import type { CapabilityRegistry } from './capability';
+
+/**
+ * Framework-Agnostic Component Type
+ * 
+ * <p>v3.0.4 architectural constraint fix: contract layer does not depend on any UI framework.
+ * Actual component types are defined by specific adapters or React binding layer.</p>
+ * 
+ * <p>Usage:</p>
+ * <ul>
+ *   <li>In React projects, use type definitions from @brix/runtime-sdk-react</li>
+ *   <li>In Vue projects, use type definitions from @brix/runtime-sdk-vue</li>
+ *   <li>In framework-agnostic scenarios, use unknown and handle at runtime</li>
+ * </ul>
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ComponentType = unknown;
+
+// =========================================
+// Plugin Status
+// =========================================
+
+/**
+ * Plugin Status
+ *
+ * <p>Describes the current state of a plugin in its lifecycle.</p>
+ */
+export type PluginStatus =
+  | 'registered'    // Registered
+  | 'loading'       // Loading
+  | 'loaded'        // Loaded
+  | 'activating'    // Activating
+  | 'active'        // Active
+  | 'deactivating'  // Deactivating
+  | 'inactive'      // Inactive
+  | 'error';        // Error state
+
+// =========================================
+// Plugin Manifest (Common Base Contract)
+// =========================================
+
+/**
+ * Plugin Manifest Base Interface
+ *
+ * <p>All adapter manifests (MF, Iframe, Native) must extend this interface.</p>
+ */
+export interface PluginManifest {
+  /** Plugin unique identifier */
+  readonly id: string;
+  /** Plugin name */
+  readonly name: string;
+  /** Plugin version */
+  readonly version: string;
+  /** Whether enabled */
+  readonly enabled?: boolean;
+}
+
+/**
+ * Plugin Metadata
+ *
+ * <p>Describes detailed information about a plugin, including required capabilities, published/subscribed events, etc.</p>
+ */
+export interface PluginMetadata {
+  /** Version */
+  readonly version: string;
+  /** Name */
+  readonly name: string;
+  /** Description */
+  readonly description?: string;
+  /** List of required capabilities */
+  readonly requiredCapabilities?: string[];
+  /** List of published events */
+  readonly publishedEvents?: string[];
+  /** List of subscribed events */
+  readonly subscribedEvents?: string[];
+}
+
+// =========================================
+// Plugin Instance (Common Base Contract)
+// =========================================
+
+/**
+ * Plugin Instance Base Interface
+ *
+ * <p>All adapter instances must extend this interface.</p>
+ *
+ * @template M Manifest type
+ */
+export interface PluginInstance<M extends PluginManifest = PluginManifest> {
+  /** Plugin ID */
+  readonly id: string;
+  /** Corresponding manifest */
+  readonly manifest: M;
+  /** Current status */
+  status: string;
+  /** Error information */
+  readonly error?: Error;
+}
+
+// =========================================
+// Plugin Loader (Common Contract)
+// =========================================
+
+/**
+ * Plugin Loader Interface
+ *
+ * <p>All adapters (MFPluginLoader, IframePluginLoader, NativePluginLoader)
+ * must implement this interface.</p>
+ *
+ * @template M Manifest type
+ * @template I Instance type
+ */
+export interface PluginLoader<
+  M extends PluginManifest = PluginManifest,
+  I extends PluginInstance<M> = PluginInstance<M>
+> {
+  /** Load a single plugin */
+  load(manifest: M): Promise<I>;
+  /** Unload plugin */
+  unload(pluginId: string): void;
+  /** Preload multiple plugins */
+  preload?(manifests: M[]): Promise<void>;
+  /** Get loaded plugins list */
+  getLoaded(): I[];
+  /** Check if plugin is loaded */
+  isLoaded(pluginId: string): boolean;
+}
+
+// =========================================
+// Plugin Load Error
+// =========================================
+
+/**
+ * Plugin Load Error
+ *
+ * <p>Encapsulates errors that occur during plugin loading, includes error phase information.</p>
+ */
+export class PluginLoadError extends Error {
+  constructor(
+    message: string,
+    public readonly pluginId: string,
+    public readonly phase: 'script' | 'init' | 'module' | 'component' | 'iframe' | 'bridge',
+    public readonly cause?: Error
+  ) {
+    super(message);
+    this.name = 'PluginLoadError';
+  }
+}
+
+// =========================================
+// Plugin Dependency Declaration
+// =========================================
+
+/**
+ * Plugin Dependency Declaration
+ *
+ * <p>Describes plugin dependencies on other plugins, used for manifest parsing and dependency validation.</p>
+ */
+export interface PluginDependency {
+  /** Dependency plugin name */
+  readonly name: string;
+  /** Dependency version */
+  readonly version: string;
+  /** Maven GroupId */
+  readonly groupId: string;
+  /** Maven ArtifactId (auto-generated: {name}-core) */
+  readonly artifactId: string;
+}
+
+// =========================================
+// Plugin Entry Configuration
+// =========================================
+
+/**
+ * Plugin Entry Configuration
+ *
+ * <p>Defines the loading entry point and basic information for a plugin.</p>
+ */
+export interface PluginEntry {
+  /** Plugin unique identifier */
+  readonly id: string;
+
+  /** Plugin name */
+  readonly name: string;
+
+  /** Plugin version */
+  readonly version: string;
+
+  /** Plugin loader function */
+  readonly loader: () => Promise<PluginLifecycle>;
+
+  /** List of dependent plugin IDs */
+  readonly dependencies?: string[];
+
+  /** Plugin configuration */
+  readonly config?: Record<string, unknown>;
+}
+
+// =========================================
+// Plugin Lifecycle
+// =========================================
+
+/**
+ * Plugin Lifecycle Interface
+ *
+ * <p>Defines callback methods for plugin activation and deactivation.</p>
+ */
+export interface PluginLifecycle {
+  /**
+   * Called When Plugin Activates
+   *
+   * <p>Initialize plugin resources, register capabilities, contribute routes, etc. in this method.</p>
+   *
+   * @param context Plugin context
+   */
+  activate(context: PluginContext): void | Promise<void>;
+
+  /**
+   * Called When Plugin Deactivates
+   *
+   * <p>Clean up plugin resources, unsubscribe, etc. in this method.</p>
+   */
+  deactivate?(): void | Promise<void>;
+}
+
+// =========================================
+// Plugin Context
+// =========================================
+
+/**
+ * Plugin Context
+ *
+ * <p>Runtime context provided to plugins, containing capability registry and contribution methods.</p>
+ */
+export interface PluginContext {
+  /** Plugin ID */
+  readonly pluginId: string;
+
+  /** Capability registry */
+  readonly registry: CapabilityRegistry;
+
+  /** Contribute routes */
+  contributeRoutes?(routes: RouteContribution[]): void;
+
+  /** Contribute menus */
+  contributeMenus?(menus: MenuContribution[]): void;
+}
+
+// =========================================
+// Route Contribution
+// =========================================
+
+/**
+ * Route Contribution
+ *
+ * <p>Route configuration contributed by plugins to the Host.</p>
+ */
+export interface RouteContribution {
+  /** Route path */
+  path: string;
+
+  /** Route component */
+  component: ComponentType;
+
+  /** Exact match */
+  exact?: boolean;
+}
+
+// =========================================
+// Menu Contribution
+// =========================================
+
+/**
+ * Menu Contribution
+ *
+ * <p>Menu configuration contributed by plugins to the Host.</p>
+ */
+export interface MenuContribution {
+  /** Menu ID */
+  id: string;
+
+  /** Menu label */
+  label: string;
+
+  /** Menu icon */
+  icon?: string;
+
+  /** Menu path */
+  path?: string;
+
+  /** Sub-menus */
+  children?: MenuContribution[];
+}
+
+// =========================================
+// Route Page Configuration (Adapter Contract)
+// =========================================
+
+/**
+ * Route Page Configuration
+ *
+ * <p>Page registration format used by adapters.</p>
+ */
+export interface PageConfig {
+  /** Page ID (format: pluginId:pageName) */
+  readonly pageId: string;
+  /** URL path */
+  readonly path: string;
+  /** Page component */
+  readonly component: ComponentType;
+}

package/src/types/state.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Copyright 2026 Brix Platform Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * @file State-Related Type Definitions
+ * @description Defines core types for the state management system, including state change events, listeners, etc.
+ * @module @brix/runtime-sdk-api-web/types/state
+ * @version 3.2.0
+ *
+ * [v3.2 Changes]
+ * Extracted from index.ts into a standalone type file, and promoted common contracts from infra-adapter-state-web.
+ *
+ * [Design Principles]
+ * - Define common state management contracts, state adapters implement specific storage logic
+ * - Support namespace isolation (each plugin has independent state space)
+ * - Support state change subscription
+ */
+/**
+ * Plugin State Storage Structure
+ *
+ * <p>Top level partitioned by plugin ID, each plugin has independent state namespace.</p>
+ *
+ * <h3>Namespace Isolation Mechanism</h3>
+ * <ul>
+ *   <li>booking plugin: state.booking.*</li>
+ *   <li>identity plugin: state.identity.*</li>
+ * </ul>
+ * <p>Plugin A cannot directly read/write Plugin B's state.</p>
+ */
+export interface PluginStoreState {
+    /** State partitioned by plugin ID */
+    [pluginId: string]: Record<string, unknown>;
+}
+/**
+ * State Change Event
+ *
+ * <p>Describes details of state changes, used for observability and debugging.</p>
+ */
+export interface StateChangeEvent {
+    /** Plugin ID */
+    readonly pluginId: string;
+    /** State key */
+    readonly key: string;
+    /** Old value */
+    readonly oldValue: unknown;
+    /** New value */
+    readonly newValue: unknown;
+    /** Timestamp */
+    readonly timestamp?: number;
+}
+/**
+ * State Change Listener
+ */
+export type StateChangeListener = (event: StateChangeEvent) => void;
+/**
+ * Plugin State Capability Type Identifier
+ */
+export declare const PluginStateCapabilityType: unique symbol;
+/**
+ * Plugin State Capability Contract
+ *
+ * <p>Provides isolated state management capability for plugins, replacing direct use of localStorage/sessionStorage/zustand.</p>
+ *
+ * <h3>Usage Example</h3>
+ * ```typescript
+ * const state = context.getCapability<PluginStateCapability>(PluginStateCapabilityType);
+ * state.setState('selectedDate', new Date());
+ * const date = state.getState<Date>('selectedDate');
+ *
+ * // Subscribe to state changes
+ * const unsubscribe = state.subscribe('selectedDate', (value) => {
+ *   console.log('Date changed:', value);
+ * });
+ * ```
+ *
+ * <h3>Architectural Notes</h3>
+ * <ul>
+ *   <li>Each plugin's state is in an independent namespace</li>
+ *   <li>Cross-plugin state sharing through EventBus</li>
+ *   <li>Direct access to other plugins' state is prohibited</li>
+ * </ul>
+ */
+export interface PluginStateCapability {
+    /**
+     * Get State Value
+     *
+     * @param key State key
+     * @returns State value, returns undefined if not exists (supports sync/async)
+     */
+    getState<T>(key: string): T | undefined | Promise<T | undefined>;
+    /**
+     * Set State Value
+     *
+     * @param key State key
+     * @param value State value
+     */
+    setState<T>(key: string, value: T): void;
+    /**
+     * Subscribe to State Changes
+     *
+     * @param key State key
+     * @param listener Change listener
+     * @returns Unsubscribe function
+     */
+    subscribe<T>(key: string, listener: (value: T) => void): () => void;
+}
+//# sourceMappingURL=state.d.ts.map

package/src/types/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,gBAAgB;IAC/B,mBAAmB;IACnB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC7C;AAMD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,YAAY;IACZ,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,UAAU;IACV,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,SAAS;IACT,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,SAAS;IACT,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,UAAU;IACV,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;AAMpE;;GAEG;AACH,eAAO,MAAM,yBAAyB,eAAsC,CAAC;AAE7E;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;OAKG;IACH,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAEjE;;;;;OAKG;IACH,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IAEzC;;;;;;OAMG;IACH,SAAS,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CACrE"}