brix-runtime-sdk-api-web 1.0.0

package/dist/types/types/layout.d.ts

@@ -0,0 +1,301 @@
+/**
+ * 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 Layout Capability Type Definitions
+ * @description Defines core types for the layout system, including sidebar, header, fullscreen, and other layout controls
+ * @module @brix/runtime-sdk-api-web/types/layout
+ * @version 3.2.0
+ *
+ * [v3.2.0 Added]
+ * Phase 1 contract layer fix: Promoted the LayoutCapability interface from shell-web to runtime-sdk-api-web.
+ *
+ * [Design Principles]
+ * - Layout is entirely controlled by the Host
+ * - Plugins can only "request" layout behavior, Host decides whether to respond
+ * - All requests go through governance policy checks
+ *
+ * [Architectural Constraints]
+ * ❌ Directly manipulating document.body is prohibited
+ * ❌ Creating global Portals to body is prohibited
+ * ❌ Modifying global CSS (like overflow) is prohibited
+ * ✅ Request layout changes through LayoutCapability or useLayout hook
+ */
+import type { Unsubscribe } from './event';
+/**
+ * Layout Mode
+ *
+ * - 'console': Console layout (with sidebar and header)
+ * - 'portal': Portal layout (simplified header, no sidebar)
+ * - 'minimal': Minimal layout (content area only)
+ */
+export type LayoutMode = 'console' | 'portal' | 'minimal';
+/**
+ * Layout State (Capability Contract)
+ *
+ * <p>Describes the complete state of the current layout.</p>
+ * <p>This is the readonly capability state exposed to plugins via LayoutCapability.</p>
+ *
+ * [Note: Canonical Definition]
+ * This is the canonical LayoutState for the runtime capability layer.
+ * Shell layers may define their own simplified LayoutState with mutable fields
+ * for local UI component state (e.g., shinwa-platform-shell-web/AppLayout.tsx).
+ * Those are intentionally different as they serve different architectural layers.
+ */
+export interface LayoutState {
+    /** Whether in Fullscreen Mode */
+    readonly fullscreen: boolean;
+    /** Whether Sidebar is Visible */
+    readonly sidebarVisible: boolean;
+    /** Whether Sidebar is Collapsed */
+    readonly sidebarCollapsed: boolean;
+    /** Whether Header is Visible */
+    readonly headerVisible: boolean;
+    /** Whether Footer is Visible */
+    readonly footerVisible: boolean;
+    /** Current Layout Mode */
+    readonly layoutMode: LayoutMode;
+    /** Current Breakpoint */
+    readonly breakpoint: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl';
+    /** Whether in Mobile View */
+    readonly isMobile: boolean;
+    /** Sidebar Width (expanded state) */
+    readonly sidebarWidth: number;
+    /** Sidebar Width (collapsed state) */
+    readonly sidebarCollapsedWidth: number;
+    /** Header Height */
+    readonly headerHeight: number;
+    /** Content Area Available Width */
+    readonly contentWidth?: number;
+    /** Content Area Available Height */
+    readonly contentHeight?: number;
+}
+/**
+ * Layout Request Result
+ *
+ * <p>Describes the execution result of a layout change request.</p>
+ */
+export interface LayoutRequestResult {
+    /**
+     * Whether the Request Succeeded
+     */
+    readonly success: boolean;
+    /**
+     * Failure Reason
+     *
+     * - 'policy_denied': Governance policy denied
+     * - 'not_supported': Current layout mode does not support this operation
+     * - 'already_applied': Already in the target state
+     */
+    readonly reason?: 'policy_denied' | 'not_supported' | 'already_applied';
+    /**
+     * Detailed Message
+     */
+    readonly message?: string;
+}
+/**
+ * Layout Change Event
+ *
+ * <p>Triggered when layout state changes.</p>
+ */
+export interface LayoutChangeEvent {
+    /** Change Type */
+    readonly type: 'fullscreen' | 'sidebar' | 'header' | 'footer' | 'breakpoint' | 'mode';
+    /** New State */
+    readonly state: LayoutState;
+    /** Previous State */
+    readonly previousState: LayoutState;
+    /** Change Source */
+    readonly source: 'user' | 'plugin' | 'system';
+    /** Plugin ID that initiated the change (if source is plugin) */
+    readonly pluginId?: string;
+    /** Change Timestamp */
+    readonly timestamp: number;
+}
+/**
+ * Layout Change Handler
+ */
+export type LayoutChangeHandler = (event: LayoutChangeEvent) => void;
+/**
+ * Layout Capability Type Identifier
+ */
+export declare const LayoutCapabilityType: unique symbol;
+/**
+ * Layout Capability Contract
+ *
+ * <p>Provides layout control capability for plugins, including fullscreen, sidebar, header, etc.</p>
+ *
+ * <h3>Design Principles</h3>
+ * <ul>
+ *   <li>Layout is entirely controlled by the Host</li>
+ *   <li>Plugins can only "request" layout behavior, Host decides whether to respond</li>
+ *   <li>All requests go through governance policy checks</li>
+ * </ul>
+ *
+ * <h3>Usage Example</h3>
+ * ```typescript
+ * const layout = context.getCapability<LayoutCapability>(LayoutCapabilityType);
+ *
+ * // Request fullscreen
+ * const success = await layout.requestFullscreen();
+ *
+ * // Get current state
+ * const state = layout.getState();
+ * if (state.isMobile) {
+ *   // Mobile handling...
+ * }
+ *
+ * // Subscribe to layout changes
+ * const unsubscribe = layout.onLayoutChange((event) => {
+ *   console.log(`Layout change: ${event.type}`);
+ * });
+ * ```
+ *
+ * @since 3.2.0
+ */
+export interface LayoutCapability {
+    /**
+     * Get Current Layout State
+     *
+     * @returns Layout state object
+     */
+    getState(): LayoutState;
+    /**
+     * Check if Fullscreen
+     *
+     * @returns Whether in fullscreen mode
+     */
+    isFullscreen(): boolean;
+    /**
+     * Check if Sidebar is Visible
+     *
+     * @returns Whether visible
+     */
+    isSidebarVisible(): boolean;
+    /**
+     * Check if Sidebar is Collapsed
+     *
+     * @returns Whether collapsed
+     */
+    isSidebarCollapsed(): boolean;
+    /**
+     * Request Enter Fullscreen Mode
+     *
+     * @returns Whether successful
+     */
+    requestFullscreen(): Promise<boolean>;
+    /**
+     * Request Exit Fullscreen Mode
+     *
+     * @returns Whether successful
+     */
+    requestExitFullscreen(): Promise<boolean>;
+    /**
+     * Request Hide Sidebar
+     *
+     * @returns Whether successful
+     */
+    requestHideSidebar(): Promise<boolean>;
+    /**
+     * Request Show Sidebar
+     *
+     * @returns Whether successful
+     */
+    requestShowSidebar(): Promise<boolean>;
+    /**
+     * Request Collapse Sidebar
+     *
+     * @returns Whether successful
+     */
+    requestCollapseSidebar?(): Promise<boolean>;
+    /**
+     * Request Expand Sidebar
+     *
+     * @returns Whether successful
+     */
+    requestExpandSidebar?(): Promise<boolean>;
+    /**
+     * Request Toggle Sidebar Collapse State
+     *
+     * @returns Whether successful
+     */
+    requestToggleSidebar?(): Promise<boolean>;
+    /**
+     * Request Hide Header
+     *
+     * @returns Whether successful
+     */
+    requestHideHeader?(): Promise<boolean>;
+    /**
+     * Request Show Header
+     *
+     * @returns Whether successful
+     */
+    requestShowHeader?(): Promise<boolean>;
+    /**
+     * Request Hide Footer
+     *
+     * @returns Whether successful
+     */
+    requestHideFooter?(): Promise<boolean>;
+    /**
+     * Request Show Footer
+     *
+     * @returns Whether successful
+     */
+    requestShowFooter?(): Promise<boolean>;
+    /**
+     * Request Layout Change
+     *
+     * <p>Can change multiple layout parameters simultaneously.</p>
+     *
+     * @param changes Layout change parameters
+     * @returns Request result
+     */
+    requestLayoutChange?(changes: Partial<{
+        fullscreen: boolean;
+        sidebarVisible: boolean;
+        sidebarCollapsed: boolean;
+        headerVisible: boolean;
+        footerVisible: boolean;
+    }>): Promise<LayoutRequestResult>;
+    /**
+     * Switch Layout Mode
+     *
+     * @param mode Target layout mode
+     * @returns Whether successful
+     */
+    setLayoutMode?(mode: LayoutMode): Promise<boolean>;
+    /**
+     * Get Current Breakpoint
+     *
+     * @returns Breakpoint name
+     */
+    getBreakpoint?(): 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl';
+    /**
+     * Check if Mobile View
+     *
+     * @returns Whether mobile
+     */
+    isMobileView?(): boolean;
+    /**
+     * Subscribe to Layout Change Event
+     *
+     * @param handler Event handler
+     * @returns Unsubscribe function
+     */
+    onLayoutChange?(handler: LayoutChangeHandler): Unsubscribe;
+}
+//# sourceMappingURL=layout.d.ts.map

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

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

package/dist/types/types/module.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 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 Module-Related Type Definitions
+ * @description Defines core types for the module system, including module metadata, state, lifecycle events, etc.
+ * @module @brix/runtime-sdk-api-web/types/module
+ * @version 3.2.0
+ *
+ * [v3.2 Changes]
+ * Extracted from index.ts into a standalone type file.
+ */
+/**
+ * Module Metadata
+ *
+ * <p>Describes basic information about a module.</p>
+ */
+export interface ModuleMetadata {
+    /** Module ID */
+    readonly moduleId: string;
+    /** Module Name */
+    readonly name: string;
+    /** Module Version */
+    readonly version: string;
+    /** Module Description */
+    readonly description?: string;
+    /** Author */
+    readonly author?: string;
+    /** Dependent Module List */
+    readonly dependencies?: string[];
+}
+/**
+ * Module State Enum
+ */
+export declare enum ModuleState {
+    /** Unloaded */
+    UNLOADED = "UNLOADED",
+    /** Loading */
+    LOADING = "LOADING",
+    /** Loaded */
+    LOADED = "LOADED",
+    /** Active */
+    ACTIVE = "ACTIVE",
+    /** Error State */
+    ERROR = "ERROR"
+}
+/**
+ * Module Lifecycle Event Enum
+ */
+export declare enum ModuleLifecycleEvent {
+    /** Before Load */
+    BEFORE_LOAD = "BEFORE_LOAD",
+    /** After Load */
+    AFTER_LOAD = "AFTER_LOAD",
+    /** Before Activate */
+    BEFORE_ACTIVATE = "BEFORE_ACTIVATE",
+    /** After Activate */
+    AFTER_ACTIVATE = "AFTER_ACTIVATE",
+    /** Before Deactivate */
+    BEFORE_DEACTIVATE = "BEFORE_DEACTIVATE",
+    /** After Deactivate */
+    AFTER_DEACTIVATE = "AFTER_DEACTIVATE",
+    /** Error */
+    ERROR = "ERROR"
+}
+//# sourceMappingURL=module.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../../../src/types/module.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH;;;;;;;;GAQG;AAMH;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,gBAAgB;IAChB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,kBAAkB;IAClB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qBAAqB;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yBAAyB;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,aAAa;IACb,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,4BAA4B;IAC5B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CAClC;AAMD;;GAEG;AACH,oBAAY,WAAW;IACrB,eAAe;IACf,QAAQ,aAAa;IACrB,cAAc;IACd,OAAO,YAAY;IACnB,aAAa;IACb,MAAM,WAAW;IACjB,aAAa;IACb,MAAM,WAAW;IACjB,kBAAkB;IAClB,KAAK,UAAU;CAChB;AAMD;;GAEG;AACH,oBAAY,oBAAoB;IAC9B,kBAAkB;IAClB,WAAW,gBAAgB;IAC3B,iBAAiB;IACjB,UAAU,eAAe;IACzB,sBAAsB;IACtB,eAAe,oBAAoB;IACnC,qBAAqB;IACrB,cAAc,mBAAmB;IACjC,wBAAwB;IACxB,iBAAiB,sBAAsB;IACvC,uBAAuB;IACvB,gBAAgB,qBAAqB;IACrC,YAAY;IACZ,KAAK,UAAU;CAChB"}

package/dist/types/types/navigation.d.ts

@@ -0,0 +1,295 @@
+/**
+ * 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 Navigation-Related Type Definitions
+ * @description Defines core types for the navigation system, including navigation options, route change listening, etc.
+ * @module @brix/runtime-sdk-api-web/types/navigation
+ * @version 3.2.0
+ *
+ * [v3.2 Changes]
+ * Extracted from index.ts into a standalone type file, and promoted common contracts from infra-adapter-router-web.
+ *
+ * [v3.2.0 Phase 1 Additions]
+ * - Added NavigateResult: Navigation result type
+ * - Added WebNavigateOptions: Web navigation options
+ * - Added PageChangeEvent: Page change event
+ * - Added PageChangeHandler: Page change handler
+ *
+ * [Design Principles]
+ * - Define common navigation contracts, router adapters implement specific logic
+ * - Support declarative navigation (PageId) and imperative navigation (Path)
+ */
+import type { Unsubscribe } from './event';
+/**
+ * Navigation Options
+ *
+ * <p>Configuration options controlling navigation behavior.</p>
+ */
+export interface NavigateOptions {
+    /**
+     * Whether to Replace Current History Entry
+     *
+     * <p>When true, the new page replaces the current page's position in the history stack.</p>
+     */
+    replace?: boolean;
+    /**
+     * Route State
+     *
+     * <p>State data passed to the target page.</p>
+     */
+    state?: Record<string, unknown>;
+}
+/**
+ * Web Navigation Options
+ *
+ * <p>Compared to basic NavigateOptions, provides richer navigation control.</p>
+ *
+ * @since 3.2.0
+ */
+export interface WebNavigateOptions extends NavigateOptions {
+    /**
+     * Whether to Open in New Window
+     *
+     * @default false
+     */
+    openInNewWindow?: boolean;
+    /**
+     * Skip Governance Policy Check
+     *
+     * <p>For Host internal use only, plugins setting this has no effect.</p>
+     *
+     * @internal
+     */
+    skipGovernance?: boolean;
+}
+/**
+ * Navigation Result
+ *
+ * <p>Describes the execution result of a navigation request. In governance mode,
+ * navigation initiated by plugins is a "request" not a "command", Host may reject navigation.</p>
+ *
+ * @since 3.2.0
+ */
+export interface NavigateResult {
+    /**
+     * Whether Navigation Succeeded
+     */
+    readonly success: boolean;
+    /**
+     * Failure Reason (only has value when success=false)
+     *
+     * - 'permission_denied': Insufficient permissions
+     * - 'feature_disabled': Feature is disabled
+     * - 'page_not_found': Page does not exist
+     * - 'host_rejected': Host rejected navigation
+     * - 'navigation_blocked': Navigation was blocked (e.g., unsaved form)
+     */
+    readonly reason?: 'permission_denied' | 'feature_disabled' | 'page_not_found' | 'host_rejected' | 'navigation_blocked';
+    /**
+     * Detailed Error Message
+     */
+    readonly message?: string;
+}
+/**
+ * Page Change Event
+ *
+ * <p>Describes page switch details for page monitoring and analytics.</p>
+ *
+ * @since 3.2.0
+ */
+export interface PageChangeEvent {
+    /**
+     * Current Page ID
+     *
+     * <p>Format: {pluginId}:{pageName}, e.g., 'booking:detail'.</p>
+     */
+    readonly pageId: string;
+    /**
+     * Page Parameters
+     *
+     * <p>Parameter object passed to the target page.</p>
+     */
+    readonly params?: Record<string, unknown>;
+    /**
+     * Source Page ID (if any)
+     */
+    readonly fromPageId?: string;
+    /**
+     * Navigation Type
+     *
+     * - 'push': Forward navigation (clicking link/button)
+     * - 'pop': Back navigation (browser back)
+     * - 'replace': Replace navigation
+     */
+    readonly navigationType: 'push' | 'pop' | 'replace';
+}
+/**
+ * Page Change Handler
+ *
+ * @since 3.2.0
+ */
+export type PageChangeHandler = (event: PageChangeEvent) => void;
+/**
+ * Navigation Capability Type Identifier
+ */
+export declare const NavigationCapabilityType: unique symbol;
+/**
+ * Navigation Capability Contract
+ *
+ * <p>Provides page navigation capability for plugins, replacing direct use of react-router.</p>
+ *
+ * <h3>Design Principles</h3>
+ * <ul>
+ *   <li>Plugins only perceive PageId, not URL</li>
+ *   <li>All navigation is a "request", Host can reject</li>
+ *   <li>Governance policies support permission checks, plugin isolation, Feature Flags</li>
+ * </ul>
+ *
+ * <h3>Basic Usage (Imperative Navigation)</h3>
+ * ```typescript
+ * const nav = context.getCapability<NavigationCapability>(NavigationCapabilityType);
+ * nav.navigate('/booking/list');
+ * nav.goBack();
+ * ```
+ *
+ * <h3>Advanced Usage (Request-Based Navigation)</h3>
+ * ```typescript
+ * const nav = context.getCapability<NavigationCapability>(NavigationCapabilityType);
+ *
+ * // Request navigation to page (may be rejected)
+ * const result = await nav.requestNavigate('booking:detail', { id: '123' });
+ * if (!result.success) {
+ *   console.error('Navigation failed:', result.reason, result.message);
+ * }
+ *
+ * // Subscribe to page changes
+ * const unsubscribe = nav.onPageChange((event) => {
+ *   console.log('Page changed:', event.pageId);
+ * });
+ * ```
+ *
+ * @since 3.0.0
+ */
+export interface NavigationCapability {
+    /**
+     * Navigate to Specified Path
+     *
+     * <p>Imperative navigation, executed directly. For controlled navigation, use requestNavigate.</p>
+     *
+     * @param path Target path
+     * @param options Navigation options
+     */
+    navigate(path: string, options?: NavigateOptions): void;
+    /**
+     * Go Back to Previous Page
+     */
+    goBack(): void;
+    /**
+     * Get Current Path
+     *
+     * @returns Current URL path
+     */
+    getCurrentPath(): string;
+    /**
+     * Request Navigation to Specified Page
+     *
+     * <p>This is a "request" not a "command", Host can reject navigation based on governance policies.</p>
+     *
+     * @param pageId Target page ID (format: {pluginId}:{pageName})
+     * @param params Page parameters
+     * @param options Navigation options
+     * @returns Navigation result
+     *
+     * @since 3.2.0
+     */
+    requestNavigate?(pageId: string, params?: Record<string, unknown>, options?: WebNavigateOptions): Promise<NavigateResult>;
+    /**
+     * Check If Navigation to Specified Page Is Possible
+     *
+     * <p>Pre-check, does not execute actual navigation.</p>
+     *
+     * @param pageId Target page ID
+     * @returns Whether navigation is possible
+     *
+     * @since 3.2.0
+     */
+    canNavigate?(pageId: string): boolean;
+    /**
+     * Get Current Page ID
+     *
+     * @returns Current page ID, returns empty string if unrecognized
+     *
+     * @since 3.2.0
+     */
+    getCurrentPageId?(): string;
+    /**
+     * Get Current Page Parameters
+     *
+     * @typeParam T Parameter type
+     * @returns Page parameter object
+     *
+     * @since 3.2.0
+     */
+    getPageParams?<T extends Record<string, unknown> = Record<string, unknown>>(): T;
+    /**
+     * Request Go Back to Previous Page
+     *
+     * @returns Navigation result
+     *
+     * @since 3.2.0
+     */
+    requestGoBack?(): Promise<NavigateResult>;
+    /**
+     * Subscribe to Page Change Events
+     *
+     * @param handler Page change handler
+     * @returns Unsubscribe function
+     *
+     * @since 3.2.0
+     */
+    onPageChange?(handler: PageChangeHandler): Unsubscribe;
+}
+/**
+ * Navigation Options (Compatibility Alias)
+ */
+export type NavigationOptions = NavigateOptions;
+/**
+ * Route Change Listener
+ *
+ * <p>Used to listen for route change events.</p>
+ */
+export type RouteChangeListener = (path: string) => void;
+/**
+ * Router Capability Type Identifier (Compatibility Alias)
+ *
+ * @deprecated Please use NavigationCapabilityType.
+ *             This alias will be removed in v4.0.0.
+ *
+ * @since 3.0.0
+ * @see NavigationCapabilityType
+ */
+export declare const RouterCapabilityType: symbol;
+/**
+ * Router Capability (Compatibility Alias)
+ *
+ * @deprecated Please use NavigationCapability.
+ *             This alias will be removed in v4.0.0.
+ *
+ * @since 3.0.0
+ * @see NavigationCapability
+ */
+export type RouterCapability = NavigationCapability;
+//# sourceMappingURL=navigation.d.ts.map

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

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