commons-shared-web-ui 0.0.55 → 0.0.56

package/documentation/side-nav-documentation.md

@@ -1,169 +0,0 @@
-# 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.