@bluealba/platform-cli 1.0.1 → 1.1.0

package/docs/architecture/shell.mdx

@@ -0,0 +1,885 @@
+---
+title: Platform Shell
+description: The PAE Shell UI - the main platform layout, navigation, and micro-frontend orchestration system
+---
+
+import { Card, CardGrid, Aside, Tabs, TabItem } from '@astrojs/starlight/components';
+
+The **Platform Shell** (`@bluealba/pae-shell-ui`) is the foundational micro-frontend that provides the core UI structure and layout for the Blue Alba Platform. It orchestrates all other micro-frontends, manages navigation, and provides the consistent user experience across all applications.
+
+## Overview
+
+The Shell serves as the container and orchestrator for the entire platform UI:
+
+<CardGrid stagger>
+  <Card title="Micro-frontend Orchestration" icon="puzzle">
+    Dynamically loads and mounts application UIs using single-spa
+  </Card>
+
+  <Card title="Navigation & Layout" icon="random">
+    Provides navbar, application selector, menu, and content areas
+  </Card>
+
+  <Card title="Authentication State" icon="approve-check">
+    Manages user session and authentication status
+  </Card>
+
+  <Card title="Tenant Management" icon="seti:folder">
+    Handles tenant selection and context switching
+  </Card>
+
+  <Card title="Customizable Design" icon="setting">
+    Supports extensive customization via props, CSS, and extension points
+  </Card>
+
+  <Card title="Responsive Layout" icon="seti:html">
+    Mobile and desktop friendly with collapsible menus
+  </Card>
+</CardGrid>
+
+---
+
+## Layout & Components
+
+The Shell provides a comprehensive layout with several key elements:
+
+### Main Layout Structure
+
+```
+┌───────────────────────────────────────────────────────────────┐
+│                        Platform Shell                          │
+│                                                                │
+│  ┌────┐  ┌─────────────────────────────────────────────────┐ │
+│  │    │  │                                                  │ │
+│  │    │  │         Application Content Area                 │ │
+│  │ N  │  │                                                  │ │
+│  │ a  │  │   (Micro-frontends mount here)                   │ │
+│  │ v  │  │                                                  │ │
+│  │ b  │  │   #pae-shell-ui-content                          │ │
+│  │ a  │  │                                                  │ │
+│  │ r  │  │                                                  │ │
+│  │    │  │                                                  │ │
+│  │    │  │                                                  │ │
+│  └────┘  └─────────────────────────────────────────────────┘ │
+│                                                                │
+└───────────────────────────────────────────────────────────────┘
+```
+
+### Key Components
+
+<Tabs>
+  <TabItem label="Splash Screen">
+    **Initial Loading Screen**
+
+    Displayed while the platform initializes:
+    - Platform logo
+    - Loading animation
+    - Customizable platform name
+    - Brand colors
+
+    **Customization**:
+    - Can be replaced via Extension Point: `SplashScreen`
+    - Logo can be customized via `SplashLogo` extension point
+    - Platform name set via `platformName` custom prop
+  </TabItem>
+
+  <TabItem label="Navbar">
+    **Main Navigation Bar**
+
+    Located on the left side, contains:
+    - **Platform Logo**: Branding and home navigation
+    - **Application Selector**: Switch between applications
+    - **Application Menu**: Current app's navigation menu
+    - **Tools Section**: Dynamically generated from modules with type `tool` (e.g., Admin UI, Documentation). Also includes theme selector, user avatar, and tenant selector.
+    - **User Section**: Profile, logout, impersonation
+
+    **States**:
+    - Expanded (default)
+    - Collapsed (icons only)
+    - Hidden (full-screen content)
+  </TabItem>
+
+  <TabItem label="Application Selector">
+    **Application Switcher**
+
+    Displays available applications:
+    - Application icons
+    - Visual indication of current app
+    - Quick switching between apps
+    - Respects user permissions
+
+    **Customization**:
+    - Replaceable via `ApplicationSelector` extension point
+    - Icon order configurable via custom props
+    - Custom icons per application
+  </TabItem>
+
+  <TabItem label="Application Menu">
+    **Current Application Menu**
+
+    Shows navigation for the active application:
+    - Hierarchical menu structure
+    - Icons for menu items
+    - Active route highlighting
+    - Operation-based visibility
+
+    **Types**:
+    - Inline (default): Menu beside content
+    - Floating: Menu overlays content
+    - Collapsible: Can be hidden/shown
+  </TabItem>
+
+  <TabItem label="User Section">
+    **Logged-in User Controls**
+
+    Bottom of navbar:
+    - User avatar/icon
+    - User name and email
+    - Logout button
+    - Impersonation controls (for admins)
+    - Profile settings
+
+    **Features**:
+    - User impersonation for support/debugging
+    - Recent impersonations list
+    - Tenant switching (multi-tenant users)
+  </TabItem>
+</Tabs>
+
+### Versions Dialog
+
+Access comprehensive platform version information:
+
+**Keyboard Shortcut**: `Ctrl+Opt+Shift+I` (Mac) or `Ctrl+Alt+Shift+I` (Windows/Linux)
+
+**Displays**:
+- Platform Shell version
+- All registered modules and versions
+- Current application modules
+- Build information
+- Environment details
+
+<Aside type="tip">
+  The versions dialog is useful for support and debugging to quickly identify which versions are deployed.
+</Aside>
+
+---
+
+## Customization Methods
+
+The Shell can be customized in three primary ways:
+
+### 1. Custom Props (Configuration)
+
+The most straightforward customization method using JSON configuration in the bootstrap:
+
+```json
+{
+  "name": "@bluealba/pae-shell-ui",
+  "config": {
+    "platformName": "My Company Platform",
+    "isMenuCollapsible": true,
+    "isMenuFloating": false,
+    "canToggleNavbarState": true,
+    "showOpenMenuButton": false,
+    "shouldNavigateToLastActiveRoute": true,
+    "cssCustomizationLoadingDelay": 1000,
+    "maxRecentImpersonations": 5,
+    "showAllApplicationsInVersionDialog": false,
+    "navbar": {
+      "menus": {
+        "applications": [
+          {
+            "type": "app",
+            "name": "crm",
+            "iconUrl": "/assets/crm-icon.svg"
+          }
+        ],
+        "tools": [
+          {
+            "type": "extension-point",
+            "name": "toggle-theme"
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+**Available Props**:
+
+<Tabs>
+  <TabItem label="Branding">
+    ```typescript
+    {
+      // Platform name shown in splash screen and UI
+      platformName: string;
+    }
+    ```
+  </TabItem>
+
+  <TabItem label="Menu Behavior">
+    ```typescript
+    {
+      // Allow menu to collapse to icons only
+      isMenuCollapsible: boolean;
+
+      // Menu floats over content vs inline
+      isMenuFloating: boolean;
+
+      // Show button to open/close menu
+      showOpenMenuButton: boolean;
+    }
+    ```
+  </TabItem>
+
+  <TabItem label="Navbar Control">
+    ```typescript
+    {
+      // Allow navbar to be expanded/collapsed/hidden
+      canToggleNavbarState: boolean;
+    }
+    ```
+  </TabItem>
+
+  <TabItem label="Navigation">
+    ```typescript
+    {
+      // Remember last accessed route and auto-navigate
+      shouldNavigateToLastActiveRoute: boolean;
+    }
+    ```
+  </TabItem>
+
+  <TabItem label="Advanced">
+    ```typescript
+    {
+      // Delay before loading CSS customizations
+      cssCustomizationLoadingDelay: number;
+
+      // Number of recent impersonations to remember
+      maxRecentImpersonations: number;
+
+      // Show all apps or just current app in versions dialog
+      showAllApplicationsInVersionDialog: boolean;
+    }
+    ```
+  </TabItem>
+</Tabs>
+
+### 2. CSS Customization
+
+Override platform styles using CSS variables and custom stylesheets:
+
+**Platform CSS Variables**:
+
+The Shell defines global CSS variables for consistent theming:
+
+```css
+:root {
+  /* Primary Color (RGB components) */
+  --platform-color-primary-red: 64;
+  --platform-color-primary-green: 57;
+  --platform-color-primary-blue: 22;
+
+  /* Secondary Color */
+  --platform-color-secondary: #ED8525;
+
+  /* Layout Colors */
+  --platform-color-white: #fff;
+  --platform-color-dark: #101828;
+  --platform-background-primary-color: #fff;
+  --platform-background-secondary-color: #f9fafb;
+  --platform-lines: #e4e7ec;
+
+  /* Text */
+  --platform-text-primary-color: #565656;
+  --platform-text-secondary-color: #818181;
+  --platform-text-base-font-family: Poppins, sans-serif;
+  --platform-text-base-font-size: 12px;
+
+  /* And many more... */
+}
+```
+
+**Custom CSS File**:
+
+Create a customization micro-frontend that loads after the shell:
+
+```typescript
+// In your customization UI module
+import './custom-platform-styles.css';
+
+// custom-platform-styles.css
+:root {
+  --platform-color-primary-red: 0;
+  --platform-color-primary-green: 102;
+  --platform-color-primary-blue: 204;
+  --platform-color-secondary: #FF6600;
+  --platform-text-base-font-family: 'Open Sans', sans-serif;
+}
+```
+
+**Configuration**:
+
+Ensure that you configure the customization module as a special module with the “isPlatformCustomization” attribute.
+
+```json
+{
+  "name": "@org/shell-customization-ui",
+  "ui": {
+      "route": "/",
+      "bundleFile": "customizations-ui.js",
+      "isPlatformCustomization": true
+  }
+}
+```
+
+<Aside type="tip" title="CSS Variable Explorer">
+  The PAE Sandbox product includes a CSS Variable Explorer that lets you visualize and experiment with all available CSS variables in real-time.
+</Aside>
+
+### 3. Extension Points
+
+Replace entire components with your own React components:
+
+**Available Extension Points**:
+
+```typescript
+const ExtensionPoints = {
+  // Top-level elements (global styles, etc.)
+  SHELL_TOP_ELEMENTS: "ShellTopElements",
+
+  // Splash screen
+  SPLASH_SCREEN: "SplashScreen",
+  SPLASH_LOGO: "SplashLogo",
+
+  // Navbar
+  NAVBAR_PORTAL_LOGO: "NavbarPortalLogo",
+  EXPANDED_NAVBAR_PORTAL_LOGO: "ExpandedNavbarPortalLogo",
+  NAVBAR_CONTENT: "NavbarContent",
+  NAVBAR_TOOLS: "NavbarTools",
+  NAVBAR_TOGGLE_STATE_BUTTON: "NavbarToggleStateButton",
+
+  // Application selector
+  APPLICATIONS_SELECTOR: "ApplicationSelector",
+
+  // Menu
+  CURRENT_APPLICATION_MENU: "CurrentApplicationMenu",
+  CURRENT_APPLICATION_MENU_CONTENT: "CurrentApplicationMenuContent",
+  OPEN_MENU_BUTTON: "OpenMenuButton",
+  CLOSE_MENU_BUTTON: "CloseMenuButton",
+
+  // User section
+  LOGGED_IN_USER_SECTION: "LoggedInUserSection",
+  LOGGED_IN_USER_AVATAR: "LoggedInUser",
+
+  // Admin
+  ADMIN_APPLICATION_ICON: "AdminApplication",
+
+  // Versions dialog
+  VERSIONS_LOGO: "VersionsLogo",
+};
+```
+
+**Usage Example**:
+
+```typescript
+import { ExtendExtensionPoint } from '@bluealba-public/pae-ui-react-core';
+import MyCustomLogo from './MyCustomLogo';
+
+function MyCustomizationUI() {
+  return (
+    <>
+      <ExtendExtensionPoint
+        module="@bluealba/pae-shell-ui"
+        point="NavbarPortalLogo"
+      >
+        <MyCustomLogo />
+      </ExtendExtensionPoint>
+
+      <ExtendExtensionPoint
+        module="@bluealba/pae-shell-ui"
+        point="SplashScreen"
+      >
+        <MyCustomSplashScreen />
+      </ExtendExtensionPoint>
+    </>
+  );
+}
+```
+
+<Aside type="note">
+  See the [UI Extension Points](/architecture/ui-extension-points/) documentation for detailed information on the extension point mechanism.
+</Aside>
+
+---
+
+## Navbar Menu Configuration
+
+The navbar can be extensively customized through the `navbar.menus` settings in the `shell` module:
+
+### Applications Menu
+
+Top section of the navbar showing available applications:
+
+```json
+{
+  "navbar": {
+    "menus": {
+      "applications": [
+        {
+          "type": "app",
+          "name": "crm",
+          "iconUrl": "/assets/crm-icon.svg"
+        },
+        {
+          "type": "app",
+          "name": "inventory"
+        },
+        {
+          "type": "link",
+          "caption": "Documentation",
+          "url": "https://docs.mycompany.com",
+          "target": "_blank",
+          "iconUrl": "/assets/docs-icon.svg"
+        }
+      ]
+    }
+  }
+}
+```
+
+**Menu Item Types**:
+
+<Tabs>
+  <TabItem label="Application">
+    **Application Reference**
+
+    ```typescript
+    {
+      type: "app";
+      name: string;        // Application name from catalog
+      iconUrl?: string;    // Optional custom icon URL
+    }
+    ```
+
+    Links to a registered platform application.
+  </TabItem>
+
+  <TabItem label="Link">
+    **External Link**
+
+    ```typescript
+    {
+      type: "link";
+      caption: string;     // Display text
+      url: string;         // Destination URL
+      target?: "_self" | "_blank";
+      iconUrl?: string;    // Optional icon URL
+    }
+    ```
+
+    Opens an external URL (documentation, help center, etc.).
+  </TabItem>
+
+  <TabItem label="Extension Point">
+    **Dynamic Extension Point**
+
+    ```typescript
+    {
+      type: "extension-point";
+      name: string;        // Extension point identifier
+    }
+    ```
+
+    Placeholder for dynamic content from other UIs (e.g., theme toggle button).
+  </TabItem>
+</Tabs>
+
+### Tools Menu
+
+Bottom section of the navbar (above user section):
+
+```json
+{
+  "navbar": {
+    "menus": {
+      "tools": [
+        {
+          "type": "extension-point",
+          "name": "toggle-theme"
+        },
+        {
+          "type": "app",
+          "name": "platform-admin"
+        }
+      ]
+    }
+  }
+}
+```
+
+**Behavior**:
+- If `applications` array has fewer items than available apps, remaining apps are automatically added at the end
+- If an app referenced in config doesn't exist or user lacks access, it's silently skipped
+- Extension points with no implementations are not rendered
+
+---
+
+## Menu Behaviors
+
+### Collapsible Menu
+
+Control whether the application menu can be collapsed:
+
+```json
+{
+  "isMenuCollapsible": true
+}
+```
+
+**When true**:
+- Menu can be collapsed to icon-only view
+- Saves horizontal space
+- Menu button allows expand/collapse
+
+**When false** (default):
+- Menu is always fully expanded
+- No collapse functionality
+
+### Floating Menu
+
+Control whether the menu overlays content:
+
+```json
+{
+  "isMenuFloating": true
+}
+```
+
+**When true**:
+- Menu floats over application content
+- Content uses full width
+- Automatically makes menu collapsible
+- Good for content-heavy applications
+
+**When false** (default):
+- Menu is inline with content
+- Content area is narrower
+- Traditional side-by-side layout
+
+### Navbar Toggle
+
+Allow users to expand/collapse/hide the entire navbar:
+
+```json
+{
+  "canToggleNavbarState": true
+}
+```
+
+**When true**:
+- Adds toggle buttons to control navbar visibility
+- Users can completely hide navbar for full-screen content
+- Three states: expanded, collapsed, hidden
+
+---
+
+## Application Menu Contract
+
+Each application UI must export its menu structure for the Shell to render:
+
+### Menu Export
+
+```typescript
+// In your application's main.tsx
+export { default as icon } from './Icon';
+export { default as menu } from './menu';
+```
+
+### Icon Component
+
+```typescript
+// Icon.tsx
+const AppIcon = () => (
+  <svg width="24" height="24" viewBox="0 0 24 24">
+    {/* Your app icon SVG */}
+  </svg>
+);
+
+export default AppIcon;
+```
+
+### Menu Structure
+
+```typescript
+// menu.ts
+import { ApplicationMenu } from '@bluealba-public/pae-ui-react-core';
+
+const menu: ApplicationMenu = [
+  {
+    label: 'Main Section',
+    items: [
+      {
+        label: 'Dashboard',
+        path: '/dashboard',
+        Icon: <DashboardIcon />,
+      },
+      {
+        label: 'Customers',
+        path: '/customers',
+        Icon: <CustomersIcon />,
+        operations: ['crm.customers.read'],
+      },
+    ],
+  },
+  {
+    label: 'Admin',
+    items: [
+      {
+        label: 'Settings',
+        path: '/settings',
+        Icon: <SettingsIcon />,
+        operations: ['crm.settings.write'],
+      },
+    ],
+  },
+];
+
+export default menu;
+```
+
+**Menu Type Definition**:
+
+```typescript
+type ApplicationMenuItem = {
+  label: string;
+  path?: string;
+  Icon?: React.ReactNode;
+  operations?: string[];      // Required operations for visibility
+  items?: ApplicationMenuItem[];
+};
+
+type ApplicationMenu = ApplicationMenuItem[];
+```
+
+### Authorization-Based Visibility
+
+Menu items can be restricted based on operations:
+
+```typescript
+{
+  label: 'Delete Customers',
+  path: '/customers/delete',
+  operations: ['crm.customers.delete'],
+}
+```
+
+**Behavior**:
+- If user lacks required operations, item is hidden
+- If all items in a section are hidden, the section is hidden
+- Empty sections are not rendered
+
+---
+
+## Application Lifecycle
+
+The Shell manages the lifecycle of application UIs:
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ 1. User navigates to application route                  │
+│    Example: /crm                                         │
+└────────────────────┬────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│ 2. Shell queries catalog for application                │
+│    Finds @mycompany/crm-ui module                       │
+└────────────────────┬────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│ 3. Shell loads application bundle                       │
+│    Fetches /crm-ui/mycompany-crm-ui.js                  │
+└────────────────────┬────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│ 4. single-spa mounts application                        │
+│    At selector: #pae-shell-ui-content                   │
+└────────────────────┬────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│ 5. Application UI renders                               │
+│    Application is now active and interactive            │
+└────────────────────┬────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│ 6. Shell updates navbar                                 │
+│    Shows application icon as active                     │
+│    Renders application menu                             │
+└─────────────────────────────────────────────────────────┘
+```
+
+**Unmounting**:
+
+When user navigates away:
+1. single-spa calls application's `unmount` function
+2. Application cleans up (removes listeners, timers, etc.)
+3. Application UI is removed from DOM
+4. Shell updates navbar for new application
+
+---
+
+## Best Practices
+
+<CardGrid>
+  <Card title="Customize via Props First" icon="setting">
+    Use custom props for configuration before resorting to CSS or extension points
+  </Card>
+
+  <Card title="Respect CSS Variables" icon="seti:css">
+    When styling applications, use platform CSS variables for consistency
+  </Card>
+
+  <Card title="Export Menu & Icon" icon="puzzle">
+    Always export menu and icon from application UIs to integrate with Shell
+  </Card>
+
+  <Card title="Use Operation-Based Visibility" icon="shield">
+    Leverage the operations array to hide unauthorized menu items
+  </Card>
+
+  <Card title="Test Menu Collapsing" icon="approve-check">
+    Ensure your app works with both expanded and collapsed menu states
+  </Card>
+
+  <Card title="Minimal Extension Points" icon="random">
+    Only replace extension points when absolutely necessary
+  </Card>
+</CardGrid>
+
+---
+
+## Common Customization Scenarios
+
+### Custom Branding
+
+```json
+{
+  "platformName": "Acme Corp Platform",
+  "navbar": {
+    "menus": {
+      "applications": [
+        {
+          "type": "app",
+          "name": "platform-admin",
+          "iconUrl": "/assets/custom-admin-icon.svg"
+        }
+      ]
+    }
+  }
+}
+```
+
+Plus CSS customization:
+```css
+:root {
+  --platform-color-primary-red: 220;
+  --platform-color-primary-green: 38;
+  --platform-color-primary-blue: 38;
+  --platform-text-base-font-family: 'Roboto', sans-serif;
+}
+```
+
+### Floating Collapsible Menu
+
+```json
+{
+  "isMenuCollapsible": true,
+  "isMenuFloating": true,
+  "showOpenMenuButton": true
+}
+```
+
+### Full Navbar Control
+
+```json
+{
+  "canToggleNavbarState": true,
+  "isMenuCollapsible": true
+}
+```
+
+### Custom Theme Toggle
+
+```json
+{
+  "navbar": {
+    "menus": {
+      "tools": [
+        {
+          "type": "extension-point",
+          "name": "theme-toggle"
+        }
+      ]
+    }
+  }
+}
+```
+
+Then in a UI module:
+```typescript
+<ExtendExtensionPoint
+  module="@bluealba/pae-shell-ui"
+  point="theme-toggle"
+>
+  <ThemeToggleButton />
+</ExtendExtensionPoint>
+```
+
+---
+
+## Troubleshooting
+
+### Application Not Appearing in Navbar
+
+**Check**:
+1. Application is registered in catalog
+2. User has access to the application
+3. Module is deployed and accessible
+
+### Menu Not Showing
+
+**Check**:
+1. Application exports `menu` in `main.tsx`
+2. Menu items have required operations user possesses
+3. Menu structure is valid
+
+### Custom Icon Not Displaying
+
+**Check**:
+1. Icon URL is correct and accessible
+2. Icon file is in the correct format (SVG, PNG)
+3. Icon file is being served by the application's web server
+4. URL path is absolute or correctly relative
+
+### Extension Point Not Working
+
+**Check**:
+1. Extension point name matches exactly
+2. Component is properly exported
+3. No console errors
+
+---
+
+## Next Steps
+
+- **[UI Extension Points](/_/docs/architecture/ui-extension-points/)** - Deep dive into extension point mechanism
+- **[Bootstrap](/_/docs/architecture/bootstrap/)** - Configuring Shell via bootstrap
+- **[Multi-Tenancy](/_/docs/architecture/multi-tenancy/)** - Tenant-specific Shell customization