brix-runtime-sdk-api-web 1.0.0

package/src/types/index.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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 Type Definition Unified Export
+ * @description Re-exports all type definitions from categorized files
+ * @module @brix/runtime-sdk-api-web/types
+ * @version 3.2.0
+ *
+ * [v3.2 Refactoring Notes]
+ * Split the original 1000+ lines of code from index.ts into the following modules:
+ * - capability.ts: Capability system types
+ * - plugin.ts: Plugin system types
+ * - navigation.ts: Navigation system types
+ * - state.ts: State management types
+ * - event.ts: Event system types
+ * - module.ts: Module system types
+ * - http.ts: HTTP client capability types
+ * - auth.ts: Authentication capability types
+ * - config.ts: Configuration capability types
+ * - common.ts: Common utility types and API response types
+ *
+ * [Design Principles]
+ * - Each file has a single responsibility
+ * - Enables on-demand imports
+ * - Easy to maintain and extend
+ */
+export * from './capability';
+export * from './plugin';
+export * from './navigation';
+export * from './state';
+export * from './event';
+export * from './module';
+export * from './http';
+export * from './auth';
+export * from './config';
+export * from './common';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH,cAAc,cAAc,CAAC;AAK7B,cAAc,UAAU,CAAC;AAKzB,cAAc,cAAc,CAAC;AAK7B,cAAc,SAAS,CAAC;AAKxB,cAAc,SAAS,CAAC;AAKxB,cAAc,UAAU,CAAC;AAKzB,cAAc,QAAQ,CAAC;AAKvB,cAAc,QAAQ,CAAC;AAKvB,cAAc,UAAU,CAAC;AAKzB,cAAc,UAAU,CAAC"}

package/src/types/index.ts

@@ -0,0 +1,120 @@
+/**
+ * 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 Type Definitions Unified Export
+ * @description Re-export all type definitions from categorized files
+ * @module @brix/runtime-sdk-api-web/types
+ * @version 3.2.0
+ *
+ * [v3.2 Refactoring Notes]
+ * Split the original 1000+ lines in index.ts into the following modules:
+ * - capability.ts: Capability system types
+ * - plugin.ts: Plugin system types
+ * - navigation.ts: Navigation system types
+ * - state.ts: State management types
+ * - event.ts: Event system types
+ * - module.ts: Module system types
+ * - http.ts: HTTP client capability types
+ * - auth.ts: Authentication capability types
+ * - config.ts: Configuration capability types
+ * - common.ts: Common utility types and API response types
+ *
+ * [v3.2.0 Phase 1 Contract Layer Fix]
+ * Added the following capability interface type files:
+ * - i18n.ts: Internationalization capability types (I18nCapability)
+ * - theme.ts: Theme capability types (ThemeCapability)
+ * - layout.ts: Layout capability types (LayoutCapability)
+ *
+ * [Design Principles]
+ * - Each file has a single responsibility
+ * - Facilitates on-demand imports
+ * - Easy to maintain and extend
+ */
+
+// =========================================
+// Capability System Types
+// =========================================
+export * from './capability';
+
+// =========================================
+// Plugin System Types
+// =========================================
+export * from './plugin';
+
+// =========================================
+// Navigation System Types
+// =========================================
+export * from './navigation';
+
+// =========================================
+// State Management Types
+// =========================================
+export * from './state';
+
+// =========================================
+// Event System Types
+// =========================================
+export * from './event';
+
+// =========================================
+// Module System Types
+// =========================================
+export * from './module';
+
+// =========================================
+// HTTP Client Capability Types
+// =========================================
+export * from './http';
+
+// =========================================
+// Authentication Capability Types
+// =========================================
+export * from './auth';
+
+// =========================================
+// Configuration Capability Types
+// =========================================
+export * from './config';
+
+// =========================================
+// Common Utility Types
+// =========================================
+export * from './common';
+
+// =========================================
+// Internationalization Capability Types (v3.2.0 added)
+// =========================================
+export * from './i18n';
+
+// =========================================
+// Theme Capability Types (v3.2.0 added)
+// =========================================
+export * from './theme';
+
+// =========================================
+// Layout Capability Types (v3.2.0 added)
+// =========================================
+export * from './layout';
+
+// =========================================
+// UI Adapter Capability Types (v3.2.0 Phase 1 UI Adapter)
+// =========================================
+export * from './ui';
+
+// =========================================
+// Plugin Loader Capability Types (v3.2.0 D6 Fix)
+// =========================================
+export * from './plugin-loader-capability';

package/src/types/layout.ts

@@ -0,0 +1,394 @@
+/**
+ * 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
+// =========================================
+
+/**
+ * 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
+// =========================================
+
+/**
+ * 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
+// =========================================
+
+/**
+ * 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
+// =========================================
+
+/**
+ * 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
+// =========================================
+
+/**
+ * Layout Capability Type Identifier
+ */
+export const LayoutCapabilityType = Symbol.for('LayoutCapability');
+
+/**
+ * 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 {
+  // =========================================
+  // State Retrieval
+  // =========================================
+
+  /**
+   * 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;
+
+  // =========================================
+  // Fullscreen Control
+  // =========================================
+
+  /**
+   * Request Enter Fullscreen Mode
+   *
+   * @returns Whether successful
+   */
+  requestFullscreen(): Promise<boolean>;
+
+  /**
+   * Request Exit Fullscreen Mode
+   *
+   * @returns Whether successful
+   */
+  requestExitFullscreen(): Promise<boolean>;
+
+  // =========================================
+  // Sidebar Control
+  // =========================================
+
+  /**
+   * 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>;
+
+  // =========================================
+  // Header/Footer Control
+  // =========================================
+
+  /**
+   * 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>;
+
+  // =========================================
+  // Comprehensive Layout Control
+  // =========================================
+
+  /**
+   * 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>;
+
+  // =========================================
+  // Responsive Information
+  // =========================================
+
+  /**
+   * Get Current Breakpoint
+   *
+   * @returns Breakpoint name
+   */
+  getBreakpoint?(): 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl';
+
+  /**
+   * Check if Mobile View
+   *
+   * @returns Whether mobile
+   */
+  isMobileView?(): boolean;
+
+  // =========================================
+  // Event Subscription
+  // =========================================
+
+  /**
+   * Subscribe to Layout Change Event
+   *
+   * @param handler Event handler
+   * @returns Unsubscribe function
+   */
+  onLayoutChange?(handler: LayoutChangeHandler): Unsubscribe;
+}

package/src/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;
+    /** List of dependent modules */
+    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/src/types/module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["module.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,YAAY;IACZ,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,WAAW;IACX,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,WAAW;IACX,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,WAAW;IACX,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,SAAS;IACT,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa;IACb,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CAClC;AAMD;;GAEG;AACH,oBAAY,WAAW;IACrB,UAAU;IACV,QAAQ,aAAa;IACrB,UAAU;IACV,OAAO,YAAY;IACnB,UAAU;IACV,MAAM,WAAW;IACjB,UAAU;IACV,MAAM,WAAW;IACjB,WAAW;IACX,KAAK,UAAU;CAChB;AAMD;;GAEG;AACH,oBAAY,oBAAoB;IAC9B,UAAU;IACV,WAAW,gBAAgB;IAC3B,UAAU;IACV,UAAU,eAAe;IACzB,UAAU;IACV,eAAe,oBAAoB;IACnC,UAAU;IACV,cAAc,mBAAmB;IACjC,UAAU;IACV,iBAAiB,sBAAsB;IACvC,UAAU;IACV,gBAAgB,qBAAqB;IACrC,SAAS;IACT,KAAK,UAAU;CAChB"}