@bluealba/platform-cli 1.0.1 → 1.1.0

package/docs/architecture/ui-extension-points.mdx

@@ -0,0 +1,781 @@
+---
+title: UI Extension Points
+description: The extension point mechanism for customizing and extending micro-frontend components in the Blue Alba Platform
+---
+
+import { Card, CardGrid, Aside, Tabs, TabItem } from '@astrojs/starlight/components';
+
+**UI Extension Points** provide a powerful mechanism for micro-frontends to declare customizable extension points that can be replaced or extended by other micro-frontends. This enables deep customization of the platform UI without modifying core code.
+
+## Overview
+
+Extension points solve a key challenge in micro-frontend architectures: **how to allow one micro-frontend to customize or extend components defined in another micro-frontend**.
+
+<CardGrid stagger>
+  <Card title="Declarative Extension" icon="puzzle">
+    Modules declare extension points where others can plug in custom components
+  </Card>
+
+  <Card title="React Component Replacement" icon="seti:react">
+    Replace entire React components with your own implementations
+  </Card>
+
+  <Card title="Dynamic Extension" icon="random">
+    Extensions are registered/unregistered following React component lifecycle
+  </Card>
+
+  <Card title="Scoped by Module" icon="seti:folder">
+    Extension points are namespaced by module to avoid collisions
+  </Card>
+
+  <Card title="Fallback Support" icon="approve-check">
+    Default components render when no extension is provided
+  </Card>
+
+  <Card title="Type-Safe" icon="seti:typescript">
+    Full TypeScript support with typed props
+  </Card>
+</CardGrid>
+
+---
+
+## Core Concepts
+
+### Extension Point
+
+An **extension point** is a placeholder in a micro-frontend where other modules can inject custom components.
+
+**Example**: The Shell declares an `ApplicationSelector` extension point allowing products to customize how applications are displayed in the navbar.
+
+### Extension
+
+An **extension** is a React component that replaces or enhances an extension point.
+
+**Example**: A product creates a custom `ApplicationSelector` component with a different layout and extends the Shell's extension point.
+
+---
+
+## Declaring Extension Points
+
+Modules can declare extension points in two ways:
+
+### 1. Inline Extension Point Component
+
+Use the `<ExtensionPoint>` component to create a placeholder within JSX:
+
+```typescript
+import { ExtensionPoint } from '@bluealba-public/pae-ui-react-core';
+
+const MyComponent = () => {
+  return (
+    <div>
+      <h1>Welcome</h1>
+      <ExtensionPoint name="Greeting" />
+    </div>
+  );
+};
+```
+
+**With Default Content**:
+
+```typescript
+const MyComponent = () => {
+  return (
+    <div>
+      <h1>Welcome</h1>
+      <ExtensionPoint name="Greeting">
+        <span>Hello, World!</span>
+      </ExtensionPoint>
+    </div>
+  );
+};
+```
+
+**Scoping**:
+
+The extension point is automatically scoped to the current module:
+- Module: `@mycompany/my-ui`
+- Extension point name: `Greeting`
+- **Full name**: `@mycompany/my-ui::Greeting`
+
+### 2. Component as Extension Point (HOC)
+
+Use the `extensionPoint()` higher-order component to make an entire component replaceable:
+
+```typescript
+import { extensionPoint } from '@bluealba-public/pae-ui-react-core';
+
+const MenuApplicationSelector: React.FC = () => {
+  return (
+    <div className="app-selector">
+      {/* Application selector implementation */}
+    </div>
+  );
+};
+
+// Make this component an extension point
+MenuApplicationSelector.displayName = 'ApplicationSelector';
+export default extensionPoint(MenuApplicationSelector);
+```
+
+**Behavior**:
+- If no extension is provided, `MenuApplicationSelector` renders normally
+- If an extension is registered, `MenuApplicationSelector` is completely replaced
+- The `displayName` becomes the extension point name
+
+---
+
+## Extending Extension Points
+
+Other modules can extend these points in two ways:
+
+### 1. Using ExtendExtensionPoint Component
+
+The simplest way to extend an extension point:
+
+```typescript
+import { ExtendExtensionPoint } from '@bluealba-public/pae-ui-react-core';
+import MyCustomSelector from './MyCustomSelector';
+
+function MyCustomizationUI() {
+  return (
+    <ExtendExtensionPoint
+      module="@bluealba/pae-shell-ui"
+      point="ApplicationSelector"
+    >
+      <MyCustomSelector />
+    </ExtendExtensionPoint>
+  );
+}
+```
+
+**Inline Content**:
+
+```typescript
+<ExtendExtensionPoint
+  module="@bluealba/pae-shell-ui"
+  point="ApplicationSelector"
+>
+  <div className="custom-selector">
+    <h3>My Custom App Selector</h3>
+    {/* Custom implementation */}
+  </div>
+</ExtendExtensionPoint>
+```
+
+### 2. Using useExtendExtensionPoint Hook
+
+For more programmatic control:
+
+```typescript
+import { useExtendExtensionPoint } from '@bluealba-public/pae-ui-react-core';
+import MyCustomSelector from './MyCustomSelector';
+
+const MyCustomizationUI = () => {
+  // Register the extension
+  useExtendExtensionPoint(
+    '@bluealba/pae-shell-ui',
+    'ApplicationSelector',
+    MyCustomSelector
+  );
+
+  return (
+    <div>
+      {/* Rest of your component */}
+    </div>
+  );
+};
+```
+
+**Conditional Extension**:
+
+```typescript
+const MyCustomizationUI = () => {
+  const [enableCustomSelector, setEnableCustomSelector] = useState(true);
+
+  // Only extend when condition is true
+  useExtendExtensionPoint(
+    '@bluealba/pae-shell-ui',
+    'ApplicationSelector',
+    enableCustomSelector ? MyCustomSelector : null
+  );
+
+  return (
+    <div>
+      <button onClick={() => setEnableCustomSelector(!enableCustomSelector)}>
+        Toggle Custom Selector
+      </button>
+    </div>
+  );
+};
+```
+
+---
+
+## Extension Lifecycle
+
+Extensions follow the React component lifecycle:
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ 1. Extension Component Mounts                           │
+│    <ExtendExtensionPoint> component renders             │
+└────────────────────┬────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│ 2. Extension Registers                                  │
+│    Extension point registry updated                     │
+│    Original component replaced (if using HOC)           │
+└────────────────────┬────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│ 3. Extension Renders                                    │
+│    Custom component displays in place of original       │
+└────────────────────┬────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│ 4. Extension Component Unmounts                         │
+│    <ExtendExtensionPoint> unmounts (route change, etc.) │
+└────────────────────┬────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│ 5. Extension Unregisters                                │
+│    Extension point registry updated                     │
+│    Original component restored (if using HOC)           │
+└─────────────────────────────────────────────────────────┘
+```
+
+**Key Point**: Extensions are **dynamic**. When the extending component unmounts, the extension is automatically removed and the original component restored.
+
+---
+
+## Common Use Cases
+
+### Customize Platform Shell
+
+Replace Shell components with branded alternatives:
+
+<Tabs>
+  <TabItem label="Custom Logo">
+    ```typescript
+    import { ExtendExtensionPoint } from '@bluealba-public/pae-ui-react-core';
+    import CompanyLogo from './CompanyLogo';
+
+    <ExtendExtensionPoint
+      module="@bluealba/pae-shell-ui"
+      point="NavbarPortalLogo"
+    >
+      <CompanyLogo />
+    </ExtendExtensionPoint>
+    ```
+  </TabItem>
+
+  <TabItem label="Custom Splash Screen">
+    ```typescript
+    import { ExtendExtensionPoint } from '@bluealba-public/pae-ui-react-core';
+    import CustomSplash from './CustomSplash';
+
+    <ExtendExtensionPoint
+      module="@bluealba/pae-shell-ui"
+      point="SplashScreen"
+    >
+      <CustomSplash />
+    </ExtendExtensionPoint>
+    ```
+  </TabItem>
+
+  <TabItem label="Custom Application Selector">
+    ```typescript
+    import { ExtendExtensionPoint } from '@bluealba-public/pae-ui-react-core';
+    import GridAppSelector from './GridAppSelector';
+
+    <ExtendExtensionPoint
+      module="@bluealba/pae-shell-ui"
+      point="ApplicationSelector"
+    >
+      <GridAppSelector />
+    </ExtendExtensionPoint>
+    ```
+  </TabItem>
+</Tabs>
+
+### Add Navbar Tools
+
+Inject custom tools into the Shell navbar:
+
+```typescript
+import { ExtendExtensionPoint } from '@bluealba-public/pae-ui-react-core';
+import ThemeToggleButton from './ThemeToggleButton';
+
+function MyFeatureUI() {
+  return (
+    <ExtendExtensionPoint
+      module="@bluealba/pae-shell-ui"
+      point="NavbarTools"
+    >
+      <ThemeToggleButton />
+    </ExtendExtensionPoint>
+  );
+}
+```
+
+### Extend Application Components
+
+Applications can also define extension points:
+
+```typescript
+// In @mycompany/crm-ui
+import { ExtensionPoint } from '@bluealba-public/pae-ui-react-core';
+
+export const CustomerDetailView = () => {
+  return (
+    <div>
+      <h2>Customer Details</h2>
+      {/* Standard fields */}
+
+      <ExtensionPoint name="CustomerDetailActions">
+        <button>Email Customer</button>
+      </ExtensionPoint>
+    </div>
+  );
+};
+```
+
+Then another module extends it:
+
+```typescript
+// In @mycompany/crm-advanced-features-ui
+import { ExtendExtensionPoint } from '@bluealba-public/pae-ui-react-core';
+
+<ExtendExtensionPoint
+  module="@mycompany/crm-ui"
+  point="CustomerDetailActions"
+>
+  <div>
+    <button>Email Customer</button>
+    <button>Schedule Call</button>
+    <button>Create Task</button>
+  </div>
+</ExtendExtensionPoint>
+```
+
+---
+
+## Passing Props to Extensions
+
+Extension points can pass props to extending components:
+
+### Declaring with Props
+
+```typescript
+import { ExtensionPoint } from '@bluealba-public/pae-ui-react-core';
+
+interface GreetingProps {
+  userName: string;
+  isAdmin: boolean;
+}
+
+const MyComponent = ({ userName, isAdmin }: { userName: string; isAdmin: boolean }) => {
+  return (
+    <div>
+      <ExtensionPoint<GreetingProps>
+        name="Greeting"
+        userName={userName}
+        isAdmin={isAdmin}
+      >
+        <span>Hello, {userName}!</span>
+      </ExtensionPoint>
+    </div>
+  );
+};
+```
+
+### Receiving Props in Extension
+
+```typescript
+interface GreetingProps {
+  userName: string;
+  isAdmin: boolean;
+}
+
+const CustomGreeting: React.FC<GreetingProps> = ({ userName, isAdmin }) => {
+  return (
+    <div className="custom-greeting">
+      <h2>Welcome, {userName}!</h2>
+      {isAdmin && <span className="badge">Admin</span>}
+    </div>
+  );
+};
+
+// Extend with typed component
+<ExtendExtensionPoint
+  module="@mycompany/my-ui"
+  point="Greeting"
+>
+  <CustomGreeting userName="" isAdmin={false} />
+</ExtendExtensionPoint>
+```
+
+---
+
+## Multiple Extensions
+
+Only **one extension** can be active per extension point at a time:
+
+**Last Registered Wins**:
+
+```typescript
+// Module A extends the point
+<ExtendExtensionPoint module="shell" point="Logo">
+  <LogoA />
+</ExtendExtensionPoint>
+
+// Module B also extends the same point (loaded after A)
+<ExtendExtensionPoint module="shell" point="Logo">
+  <LogoB />  {/* This one will be used */}
+</ExtendExtensionPoint>
+```
+
+**Control with Module Load Order**:
+
+Ensure the module with the desired extension loads last by using `dependsOn`:
+
+```json
+{
+  "name": "@bluealba/pae-shell-ui",
+  "dependsOn": [
+    "@mycompany/platform-customization-ui"
+  ]
+}
+```
+
+This ensures `platform-customization-ui` loads first and its extensions can be overridden by Shell if needed.
+
+---
+
+## Best Practices
+
+<CardGrid>
+  <Card title="Use Descriptive Names" icon="pencil">
+    Choose clear, descriptive names for extension points that indicate their purpose
+  </Card>
+
+  <Card title="Provide Fallback Content" icon="approve-check">
+    Always include default content for extension points
+  </Card>
+
+  <Card title="Document Extension Points" icon="document">
+    Document available extension points, their props, and usage examples
+  </Card>
+
+  <Card title="Type Your Props" icon="seti:typescript">
+    Use TypeScript interfaces for extension point props
+  </Card>
+
+  <Card title="Respect Lifecycles" icon="seti:clock">
+    Understand that extensions are dynamic and can mount/unmount
+  </Card>
+
+  <Card title="Avoid Deep Nesting" icon="warning">
+    Don't create chains of extensions extending extensions
+  </Card>
+</CardGrid>
+
+---
+
+## Platform Shell Extension Points
+
+The Shell provides these commonly-used extension points:
+
+<Tabs>
+  <TabItem label="Branding">
+    ```typescript
+    // Platform logo in navbar
+    NAVBAR_PORTAL_LOGO: "NavbarPortalLogo"
+    EXPANDED_NAVBAR_PORTAL_LOGO: "ExpandedNavbarPortalLogo"
+
+    // Splash screen
+    SPLASH_SCREEN: "SplashScreen"
+    SPLASH_LOGO: "SplashLogo"
+
+    // Versions dialog
+    VERSIONS_LOGO: "VersionsLogo"
+    ```
+  </TabItem>
+
+  <TabItem label="Navigation">
+    ```typescript
+    // Application selector
+    APPLICATIONS_SELECTOR: "ApplicationSelector"
+
+    // Application menu
+    CURRENT_APPLICATION_MENU: "CurrentApplicationMenu"
+    CURRENT_APPLICATION_MENU_CONTENT: "CurrentApplicationMenuContent"
+
+    // Menu buttons
+    OPEN_MENU_BUTTON: "OpenMenuButton"
+    CLOSE_MENU_BUTTON: "CloseMenuButton"
+    ```
+  </TabItem>
+
+  <TabItem label="Navbar">
+    ```typescript
+    // Navbar sections
+    NAVBAR_CONTENT: "NavbarContent"
+    NAVBAR_TOOLS: "NavbarTools"
+
+    // Navbar controls
+    NAVBAR_TOGGLE_STATE_BUTTON: "NavbarToggleStateButton"
+
+    // Admin
+    ADMIN_APPLICATION_ICON: "AdminApplication"
+    ```
+  </TabItem>
+
+  <TabItem label="User">
+    ```typescript
+    // User section
+    LOGGED_IN_USER_SECTION: "LoggedInUserSection"
+    LOGGED_IN_USER_AVATAR: "LoggedInUser"
+    ```
+  </TabItem>
+
+  <TabItem label="Top-Level">
+    ```typescript
+    // Top-level placeholder for global styles, etc.
+    SHELL_TOP_ELEMENTS: "ShellTopElements"
+    ```
+  </TabItem>
+</Tabs>
+
+See the [Shell Architecture](/architecture/shell/) documentation for detailed information on each extension point.
+
+---
+
+## Example: Theme Toggle Extension
+
+Complete example of adding a theme toggle to the navbar:
+
+### 1. Create the Component
+
+```typescript
+// ThemeToggleButton.tsx
+import React, { useState } from 'react';
+
+const ThemeToggleButton: React.FC = () => {
+  const [isDark, setIsDark] = useState(false);
+
+  const toggleTheme = () => {
+    setIsDark(!isDark);
+    document.documentElement.setAttribute('data-theme', isDark ? 'light' : 'dark');
+  };
+
+  return (
+    <button
+      onClick={toggleTheme}
+      className="theme-toggle"
+      title={isDark ? 'Switch to Light Mode' : 'Switch to Dark Mode'}
+    >
+      {isDark ? '☀️' : '🌙'}
+    </button>
+  );
+};
+
+export default ThemeToggleButton;
+```
+
+### 2. Register the Extension
+
+```typescript
+// In your customization UI module's root component
+import { ExtendExtensionPoint } from '@bluealba-public/pae-ui-react-core';
+import ThemeToggleButton from './ThemeToggleButton';
+
+function PlatformCustomizationUI() {
+  return (
+    <ExtendExtensionPoint
+      module="@bluealba/pae-shell-ui"
+      point="NavbarTools"
+    >
+      <ThemeToggleButton />
+    </ExtendExtensionPoint>
+  );
+}
+
+export default PlatformCustomizationUI;
+```
+
+### 3. Configure Bootstrap
+
+Ensure your customization module loads:
+
+```json
+{
+  "name": "@mycompany/platform-customization-ui",
+  "type": "app",
+  "baseUrl": "/platform-customization-ui",
+  "service": {
+    "host": "platform-customization-ui",
+    "port": 80
+  },
+  "ui": {
+    "route": "/",
+    "mountAtSelector": "body",
+    "bundleFile": "platform-customization-ui.js",
+    "isPlatformCustomization": true
+  },
+  "dependsOn": []
+}
+```
+
+**Key**: Set `isPlatformCustomization: true` to ensure early loading.
+
+---
+
+## Troubleshooting
+
+### Extension Not Applying
+
+**Check**:
+1. Module declaring extension point is loaded
+2. Module providing extension is loaded
+3. Extension module loads after the module it's extending
+4. Extension point name matches exactly (case-sensitive)
+5. Module name matches exactly
+
+**Debug**:
+```typescript
+// Add logging to verify registration
+useExtendExtensionPoint(
+  '@bluealba/pae-shell-ui',
+  'NavbarTools',
+  () => {
+    console.log('NavbarTools extension registered');
+    return <ThemeToggleButton />;
+  }
+);
+```
+
+### Extension Disappears
+
+**Cause**: The component registering the extension unmounted.
+
+**Solution**: Ensure the component registering the extension remains mounted. For persistent extensions, register them in a root-level component that doesn't unmount.
+
+### Multiple Extensions Conflict
+
+**Cause**: Multiple modules extending the same point.
+
+**Solution**:
+- Use module load order to control priority
+- Consolidate extensions into a single module
+- Create separate extension points for different features
+
+### TypeScript Type Errors
+
+**Cause**: Props mismatch between extension point and extension component.
+
+**Solution**:
+- Export prop types from the module declaring the extension point
+- Import and use these types in your extension component
+
+```typescript
+// In module declaring extension point
+export interface NavbarToolsProps {
+  isCollapsed: boolean;
+}
+
+// In extending module
+import { NavbarToolsProps } from '@bluealba/pae-shell-ui';
+
+const MyTool: React.FC<NavbarToolsProps> = ({ isCollapsed }) => {
+  // Implementation
+};
+```
+
+---
+
+## Advanced Patterns
+
+### Conditional Extension
+
+Only extend under certain conditions:
+
+```typescript
+const ConditionalExtension = () => {
+  const { user } = useAuth();
+  const { features } = useTenantConfig();
+
+  if (user.isAdmin && features.customTheme) {
+    return (
+      <ExtendExtensionPoint
+        module="@bluealba/pae-shell-ui"
+        point="NavbarTools"
+      >
+        <ThemeToggleButton />
+      </ExtendExtensionPoint>
+    );
+  }
+
+  return null;
+};
+```
+
+### Composing Extensions
+
+Create a component that extends multiple points:
+
+```typescript
+const PlatformCustomizations = () => {
+  return (
+    <>
+      <ExtendExtensionPoint module="shell" point="NavbarPortalLogo">
+        <CompanyLogo />
+      </ExtendExtensionPoint>
+
+      <ExtendExtensionPoint module="shell" point="SplashScreen">
+        <CompanySplash />
+      </ExtendExtensionPoint>
+
+      <ExtendExtensionPoint module="shell" point="NavbarTools">
+        <ThemeToggle />
+      </ExtendExtensionPoint>
+    </>
+  );
+};
+```
+
+### Wrapping Original Component
+
+Extend while preserving original behavior:
+
+```typescript
+import { useExtensionPoint } from '@bluealba-public/pae-ui-react-core';
+
+const EnhancedApplicationSelector = () => {
+  // Get the original component
+  const OriginalSelector = useExtensionPoint(
+    '@bluealba/pae-shell-ui',
+    'ApplicationSelector'
+  );
+
+  return (
+    <div className="enhanced-selector">
+      <div className="banner">Featured Apps</div>
+      <OriginalSelector />
+    </div>
+  );
+};
+```
+
+---
+
+## Next Steps
+
+- **[Shell Architecture](/_/docs/architecture/shell/)** - Available Shell extension points
+- **[Bootstrap](/_/docs/architecture/bootstrap/)** - Configuring module load order
+- **[Getting Started with UI Development](/_/docs/development/ui-development/)** - Creating micro-frontends