brix-runtime-sdk-api-web 1.0.0

package/dist/types/types/plugin-loader-capability.d.ts

@@ -0,0 +1,142 @@
+/**
+ * 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 Loader Capability Interface
+ * @description Abstracts plugin loading/rendering capabilities for dependency injection
+ * @module @brix/runtime-sdk-api-web/types/plugin-loader-capability
+ * @version 3.2.0
+ *
+ * [v3.2.0 Added - D6 Fix]
+ * Phase 1 contract layer fix: Shell-web should not directly depend on infra-adapter-mf-web.
+ * This interface abstracts the plugin loading mechanism so that Shell components
+ * don't need to directly import specific loaders (MF, iframe, etc.).
+ *
+ * [Design Principles]
+ * - Shell layer accesses plugin loader through PluginLoaderCapability interface
+ * - Host is responsible for injecting the concrete implementation
+ * - Supports different plugin loader implementations (MF, iframe, native, etc.)
+ *
+ * [Architectural Constraints]
+ * ❌ Shell components directly importing specific loaders is prohibited
+ * ❌ Tight coupling with Module Federation is prohibited
+ * ✅ Obtain plugin loader through PluginLoaderCapability or usePluginLoader hook
+ */
+import type { ComponentType, ReactNode } from 'react';
+/**
+ * Props for RemoteComponent rendering
+ *
+ * <p>Standard interface for rendering remote plugin components.</p>
+ *
+ * @example
+ * ```tsx
+ * const props: RemoteComponentProps = {
+ *   remoteEntry: 'https://plugin-host.com/remoteEntry.js',
+ *   exposePath: './pages/UserList',
+ *   fallback: <Loading />,
+ *   errorFallback: <ErrorDisplay />,
+ * };
+ * ```
+ */
+export interface RemoteComponentProps {
+    /** Remote entry URL (Module Federation entry point) */
+    remoteEntry: string;
+    /** Exposed component path (e.g., './ComponentName') */
+    exposePath: string;
+    /** Loading fallback component */
+    fallback?: ReactNode;
+    /** Error fallback component */
+    errorFallback?: ReactNode;
+    /** Props to pass to the remote component */
+    props?: Record<string, unknown>;
+}
+/**
+ * Plugin Loader Capability Type Identifier
+ *
+ * <p>Used for registration and lookup in RuntimeContext.</p>
+ */
+export declare const PluginLoaderCapabilityType: unique symbol;
+/**
+ * Plugin Loader Capability Interface
+ *
+ * <p>Abstracts the plugin loading mechanism so that Shell components
+ * don't need to directly import specific loaders (MF, iframe, etc.).</p>
+ *
+ * <p>Host is responsible for injecting the concrete implementation
+ * (e.g., infra-adapter-mf-web's RemoteComponent).</p>
+ *
+ * @example Host Registration
+ * ```typescript
+ * // In host-shell assembly
+ * import { RemoteComponent } from '@brix/infra-adapter-mf-web';
+ *
+ * const pluginLoaderCapability: PluginLoaderCapability = {
+ *   RemoteComponent,
+ *   async preload(remoteEntries) {
+ *     // Implementation for preloading
+ *   },
+ * };
+ *
+ * capabilityRegistry.register(PluginLoaderCapabilityType, pluginLoaderCapability);
+ * ```
+ *
+ * @example Shell Usage
+ * ```tsx
+ * // In shell component
+ * const { RemoteComponent } = usePluginLoader();
+ *
+ * return (
+ *   <RemoteComponent
+ *     remoteEntry={plugin.remoteEntry}
+ *     exposePath="./Component"
+ *     fallback={<Loading />}
+ *   />
+ * );
+ * ```
+ */
+export interface PluginLoaderCapability {
+    /**
+     * RemoteComponent - React component for rendering remote plugins
+     *
+     * <p>Host injects the actual implementation (e.g., MF adapter's RemoteComponent)</p>
+     */
+    RemoteComponent: ComponentType<RemoteComponentProps>;
+    /**
+     * Preload plugin scripts (optional)
+     *
+     * <p>Pre-fetches remote entry scripts for faster subsequent loading.</p>
+     *
+     * @param remoteEntries - Array of remote entry URLs to preload
+     * @returns Promise that resolves when preloading is complete
+     *
+     * @example
+     * ```typescript
+     * await pluginLoader.preload?.([
+     *   'https://plugin-a.com/remoteEntry.js',
+     *   'https://plugin-b.com/remoteEntry.js',
+     * ]);
+     * ```
+     */
+    preload?(remoteEntries: string[]): Promise<void>;
+    /**
+     * Check if a remote module is available (optional)
+     *
+     * @param remoteEntry - Remote entry URL
+     * @param exposePath - Exposed component path
+     * @returns Whether the module is available
+     */
+    isModuleAvailable?(remoteEntry: string, exposePath: string): Promise<boolean>;
+}
+//# sourceMappingURL=plugin-loader-capability.d.ts.map

package/dist/types/types/plugin-loader-capability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-loader-capability.d.ts","sourceRoot":"","sources":["../../../src/types/plugin-loader-capability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAMtD;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,oBAAoB;IACnC,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IAEpB,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;IAEnB,iCAAiC;IACjC,QAAQ,CAAC,EAAE,SAAS,CAAC;IAErB,+BAA+B;IAC/B,aAAa,CAAC,EAAE,SAAS,CAAC;IAE1B,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAMD;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,eAAuC,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,eAAe,EAAE,aAAa,CAAC,oBAAoB,CAAC,CAAC;IAErD;;;;;;;;;;;;;;;OAeG;IACH,OAAO,CAAC,CAAC,aAAa,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjD;;;;;;OAMG;IACH,iBAAiB,CAAC,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC/E"}

package/dist/types/types/plugin.d.ts

@@ -0,0 +1,250 @@
+/**
+ * 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>
+ */
+export type ComponentType = unknown;
+/**
+ * Plugin Status
+ *
+ * <p>Describes the current state of a plugin in its lifecycle.</p>
+ */
+export type PluginStatus = 'registered' | 'loading' | 'loaded' | 'activating' | 'active' | 'deactivating' | 'inactive' | 'error';
+/**
+ * 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 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 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
+ *
+ * <p>Encapsulates errors that occur during plugin loading, includes error phase information.</p>
+ */
+export declare class PluginLoadError extends Error {
+    readonly pluginId: string;
+    readonly phase: 'script' | 'init' | 'module' | 'component' | 'iframe' | 'bridge';
+    readonly cause?: Error | undefined;
+    constructor(message: string, pluginId: string, phase: 'script' | 'init' | 'module' | 'component' | 'iframe' | 'bridge', cause?: Error | undefined);
+}
+/**
+ * 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
+ *
+ * <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 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
+ *
+ * <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
+ *
+ * <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
+ *
+ * <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
+ *
+ * <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;
+}
+//# sourceMappingURL=plugin.d.ts.map

package/dist/types/types/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../src/types/plugin.ts"],"names":[],"mappings":"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"}