platformcommons-web-lib 1.0.0

package/documentation/side-nav-documentation.md

@@ -0,0 +1,169 @@
+# Side Navigation Component (`lib-side-nav`)
+
+## Overview
+The `lib-side-nav` component provides a reusable, configurable sidebar navigation drawer for micro-frontends (MFEs). It supports nested items, role-based access control (RBAC) filtering, dynamic label mapping for internationalization (i18n), and customizable themes.
+
+By handling data transformations like deep cloning and label mapping internally, the component ensures that consuming MFEs remain lightweight and declarative.
+
+## Input Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `[sections]` | `SideNavSection[]` | `[]` | Array of section configurations, each containing a heading and an array of `SideNavItem`s. |
+| `[userRoles]` | `string[]` | `undefined` | Array of roles for the current user. Used to filter out nav items that the user does not have access to. |
+| `[labels]` | `{ [key: string]: string }` | `undefined` | Key-value dictionary object used for dynamically translating item headings, labels, and tooltips. |
+| `[activeId]` | `string` | `undefined` | The `id` of the currently active navigation item to highlight. |
+| `[styleConfig]` | `SideNavStyleConfig` | `undefined` | Allows passing an object to override color rules. Alternatively, use CSS variables on `:root` or `:host`. |
+| `[(collapsed)]` | `boolean` | `false` | Controls whether the side nav is open or collapsed into an icons-only view. Supports two-way binding. |
+| `[width]` | `string` | `undefined` | Width of the expanded side nav. Overrides the `--cc-side-nav-width` CSS variable. |
+| `[collapsedWidth]` | `string` | `undefined` | Width of the collapsed side nav. Overrides `--cc-side-nav-collapsed-width` CSS variable. |
+| `[showCollapseToggle]` | `boolean` | `true` | Whether to display the collapse/expand toggle button. |
+| `[hideIconsWhenExpanded]` | `boolean` | `false` | If true, hides icons when the side nav is expanded, showing only text. |
+| `[showTooltips]` | `boolean` | `false` | Enables tooltips when the nav is expanded. Tooltips are **always shown automatically when collapsed** regardless of this value. |
+| `[tooltipPosition]` | `TooltipPosition` | `'right'` | Position of the tooltips relative to the items. |
+
+## Outputs
+
+| Output | Event Type | Description |
+|---|---|---|
+| `(itemClicked)` | `EventEmitter<SideNavItem>` | Emitted when a user clicks a nav item (that isn't disabled). |
+| `(collapsedChange)` | `EventEmitter<boolean>` | Emitted when the user toggles the collapse state. |
+
+## Expected JSON Configuration Format
+
+The input `sections` array should be built utilizing the following `SideNavSection` interface structure (usually fetched from a JSON file):
+
+```json
+{
+  "sections": [
+    {
+      "heading": "MAIN_NAVIGATION_HEADING_KEY",
+      "items": [
+        {
+          "id": "dashboard",
+          "labelKey": "DASHBOARD_LABEL_KEY",
+          "icon": "fa fa-home",
+          "route": "/dashboard",
+          "roles": ["admin", "user"]
+        },
+        {
+          "id": "settings",
+          "labelKey": "SETTINGS_LABEL_KEY",
+          "icon": "settings",
+          "route": "/settings",
+          "roles": ["admin"]
+        }
+      ]
+    }
+  ]
+}
+```
+
+*Note: The component will automatically translate `MAIN_NAVIGATION_HEADING_KEY`, `DASHBOARD_LABEL_KEY` etc. substituting them using the provided `[labels]` dictionary.*
+
+## Example Usage in an MFE
+
+```html
+<lib-side-nav 
+  [sections]="navSections" 
+  [labels]="labelsMap"
+  [activeId]="currentRouteId" 
+  [(collapsed)]="isNavCollapsed"
+  (itemClicked)="onNavClick($event)">
+</lib-side-nav>
+```
+
+```typescript
+export class ExampleHomeComponent implements OnInit {
+  navSections: SideNavSection[] = [];
+  labelsMap: any = {};
+  isNavCollapsed = false;
+  currentRouteId = 'dashboard';
+
+  constructor(private assetService: AssetService, private labelService: LabelService) {}
+
+  ngOnInit() {
+    // 1. Load labels
+    this.labelService.labels$.subscribe(labels => this.labelsMap = labels);
+    
+    // 2. Load the raw side-nav structure JSON; don't map labels manually!
+    this.assetService.getStaticContents('side-nav.json').subscribe(res => {
+      this.navSections = res.sections || [];
+    });
+  }
+
+  onNavClick(item: SideNavItem) {
+    if (item.route) {
+        // Navigate
+    }
+  }
+}
+```
+
+## CSS Variable Theming
+
+All visual tokens are exposed as CSS custom properties. Override them on `:root` or a parent selector, or pass them via `[styleConfig]`.
+
+### Container & Layout
+
+| CSS Variable | `styleConfig` key | Default | Description |
+|---|---|---|---|
+| `--cc-side-nav-bg` | `bg` | `#F9C80E0D` | Background colour of the nav |
+| `--cc-side-nav-width` | `width` | `220px` | Expanded width |
+| `--cc-side-nav-collapsed-width` | `collapsedWidth` | `56px` | Collapsed (icon-only) width |
+| `--cc-side-nav-font-family` | `fontFamily` | `'Poppins', sans-serif` | Font family for all text |
+
+### Items
+
+| CSS Variable | `styleConfig` key | Default | Description |
+|---|---|---|---|
+| `--cc-side-nav-item-color` | `itemColor` | `#5F6368` | Inactive item text/icon colour |
+| `--cc-side-nav-item-hover-bg` | `itemHoverBg` | `rgba(#E63E30, 0.05)` | Inactive item hover background |
+| `--cc-side-nav-active-bg` | `activeBg` | `#E63E30` | Active item background |
+| `--cc-side-nav-active-color` | `activeColor` | `#FFFFFF` | Active item text/icon colour |
+| `--cc-side-nav-active-hover-bg` | `activeHoverBg` | `#D4382B` | Active item hover background |
+| `--cc-side-nav-heading-color` | `headingColor` | `#3C4043` | Section heading colour |
+
+### Toggle Pill
+
+| CSS Variable | `styleConfig` key | Default | Description |
+|---|---|---|---|
+| `--cc-side-nav-toggle-bg` | `toggleBg` | `#ffffff` | Collapse/expand button background |
+| `--cc-side-nav-toggle-border-color` | `toggleBorderColor` | `rgba(0,0,0,0.1)` | Collapse/expand button border colour |
+
+### Tooltip
+
+Tooltips appear automatically when the nav is **collapsed**. When expanded, they only show if `[showTooltips]="true"` is set. The tooltip displays to the `right` of the icon with a left-pointing arrow caret.
+
+| CSS Variable | `styleConfig` key | Default | Description |
+|---|---|---|---|
+| `--cc-side-nav-tooltip-bg` | `tooltipBg` | `#1e1e2d` | Tooltip background (also used for the arrow caret colour) |
+| `--cc-side-nav-tooltip-color` | `tooltipColor` | `#FFFFFF` | Tooltip text colour |
+| `--cc-side-nav-tooltip-font-size` | — | `12px` | Tooltip font size |
+| `--cc-side-nav-tooltip-font-weight` | `tooltipFontWeight` | `500` | Tooltip font weight |
+| `--cc-side-nav-tooltip-letter-spacing` | `tooltipLetterSpacing` | `0.2px` | Tooltip letter spacing |
+| `--cc-side-nav-tooltip-padding` | — | `8px 14px` | Tooltip inner padding |
+| `--cc-side-nav-tooltip-border-radius` | — | `6px` | Tooltip border radius |
+| `--cc-side-nav-tooltip-shadow` | `tooltipShadow` | `0 4px 12px rgba(0,0,0,0.35)` | Tooltip box shadow |
+| `--cc-side-nav-tooltip-offset` | `tooltipOffset` | `20px` | Gap between the icon and the tooltip box |
+
+**Example — override via CSS:**
+```scss
+lib-side-nav {
+  --cc-side-nav-tooltip-bg: #2c2c3e;
+  --cc-side-nav-toggle-bg: #f5f5f5;
+}
+```
+
+**Example — override via `[styleConfig]`:**
+```html
+<lib-side-nav
+  [styleConfig]="{ tooltipBg: '#2c2c3e', toggleBg: '#f5f5f5' }"
+  ...>
+</lib-side-nav>
+```
+
+## Best Practices
+- **Do not map or clone data in the MFE**: Let `lib-side-nav` handle filtering by roles and transforming JSON data. You should pass the raw JSON array to `[sections]` and the translation dictionary to `[labels]`.
+- **Use CSS Variables for theming**: While `[styleConfig]` is provided, setting `--cc-side-nav-width` and other variables in an MFE's SCSS provides better design system scalability.
+- **Lazy Load Labels**: If the language is updated dynamically, simply pass a new `labels` ref to the component—it handles `ngOnChanges()` automatically and re-renders the translated text.