@flusys/ng-layout 1.1.1-beta → 1.2.0-rc.1

package/README.md

@@ -1,657 +1,101 @@
-# @flusys/ng-layout Package Guide
+# @flusys/ng-layout
 
-## Overview
+Application shell for the FLUSYS Angular platform — topbar, sidebar, menu, and signal-based layout state management.
 
-`@flusys/ng-layout` provides the application shell, menu system, theme management, and layout components for FLUSYS applications. This package creates the visual structure and navigation framework.
+[![npm version](https://img.shields.io/npm/v/@flusys/ng-layout.svg)](https://www.npmjs.com/package/@flusys/ng-layout)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**Key Principle:** ng-layout depends on ng-core and ng-shared, but remains independent of feature packages like ng-auth.
-
-## Package Information
-
-- **Package:** `@flusys/ng-layout`
-- **Dependencies:** ng-core, ng-shared
-- **Dependents:** flusysng
-- **Build Command:** `npm run build:ng-layout`
-
-## Features
-
-### 1. App Layout Components
-
-#### AppLayout
-
-Main layout wrapper with signal-based state management.
+---
 
-```typescript
-import { AppLayout } from '@flusys/ng-layout';
+## Installation
 
-@Component({
-  selector: 'app-root',
-  standalone: true,
-  imports: [AppLayout],
-  template: `
-    <app-layout>
-      <router-outlet />
-    </app-layout>
-  `
-})
-export class AppComponent {}
+```bash
+npm install @flusys/ng-layout @flusys/ng-core @flusys/ng-shared
 ```
 
-**What it includes:**
-- AppTopbar (header with logo, user menu)
-- AppSidebar (collapsible navigation menu)
-- Main content area with `<router-outlet>`
-- AppFooter
-
-**Layout modes:**
-- **Static** - Sidebar always visible on desktop, overlay on mobile
-- **Overlay** - Sidebar overlays content when opened
-
-#### AppTopbar
-
-Application header with branding and user actions. Used automatically by AppLayout.
-
-**Features:**
-- Company name display (from `LAYOUT_AUTH_STATE` or fallback to "Flusys")
-- Menu toggle button (calls `layoutService.onMenuToggle()`)
-- Dark mode toggle button
-- Theme/color palette configurator (AppConfigurator via pStyleClass)
-- App launcher grid (if apps configured via `LayoutService.setApps()`)
-- Company/Branch selector (if `enableCompanyFeature` is true)
-- User profile dropdown (AppProfile)
-
-#### AppSidebar
-
-Collapsible navigation sidebar. Contains AppMenu.
-
-**Features:**
-- Multi-level menu via AppMenu
-- Collapsible/expandable
-- Active route highlighting
-- Icons with labels
-- Smooth CSS animations
-
-#### AppMenu
-
-Menu container that renders `LayoutService.menu` signal (permission-filtered).
-
-#### AppMenuitem
-
-Recursive menu item component using attribute selector `[app-menuitem]`.
-
-**Features:**
-- Nested children with toggle animation
-- Router link active detection with smart path matching
-- Menu state synchronization via `layoutService.menuSource$`
-- Smooth submenu collapse/expand via CSS transitions (no `@angular/animations`)
-
-#### AppFooter
-
-Displays company name (from `LAYOUT_AUTH_STATE`) or app name fallback.
-
-#### AppProfile
-
-User profile dropdown in topbar.
-
-**Features:**
-- User info display (picture, name, email)
-- Profile route link
-- Copy SignUp Link button (generates link with company slug)
-- Logout button with toast feedback
-- Uses `LAYOUT_AUTH_API` and `LAYOUT_AUTH_STATE` tokens (optional injection)
-
-#### AppCompanyBranchSelector
-
-Company and branch switcher in topbar. Shown when company feature is enabled.
-
-**Features:**
-- Button shows current company name and branch name
-- Popover with company/branch dropdowns
-- Auto-selects branch if only one available
-- Loading states and error handling
-- Uses `LAYOUT_AUTH_API` for data fetching and switching
-- Signal-based reactivity for button enable/disable state
-
-**User Workflow:**
-1. Click company/branch button in topbar
-2. Popover opens with company dropdown
-3. Select company → Branches load
-4. Select branch (required if branches exist)
-5. Click "Switch" → Backend API call → JWT updated → Navigate to dashboard
-
-**Configuration requires:**
-1. Auth service enabled in environment (`services.auth.enabled: true`)
-2. Auth adapters provided in `app.config.ts`
-
-#### AppLauncher
+---
 
-App launcher grid in topbar for quick access to related applications.
+## 1. Set Up the Layout Route
 
-**Features:**
-- 3-column grid of app icons with names
-- External links (open in new tabs)
-- Icon support: PrimeNG, Material, or image URLs
-- Permission filtering via `permissionLogic`
-- Only visible when `layoutService.hasApps()` is true
+Use `AppLayout` as the parent route component. All authenticated pages become children.
 
-**Configuration:**
 ```typescript
-import { ILauncherApp } from '@flusys/ng-layout';
+// app.routes.ts
+import { Routes } from '@angular/router';
+import { AppLayout } from '@flusys/ng-layout';
 
-const apps: ILauncherApp[] = [
+export const routes: Routes = [
   {
-    id: 'docs',
-    name: 'Docs',
-    iconType: 1,  // 1=primeng, 2=material, 3=image
-    icon: 'pi pi-book',
-    url: 'https://docs.example.com',
+    path: '',
+    component: AppLayout,
+    children: [
+      { path: 'dashboard', loadComponent: () => import('./pages/dashboard.component') },
+      { path: 'products',  loadComponent: () => import('./pages/product-list.component') },
+    ],
   },
   {
-    id: 'analytics',
-    name: 'Analytics',
-    iconType: 1,
-    icon: 'pi pi-chart-bar',
-    url: 'https://analytics.example.com',
-    permissionLogic: { type: 'action', actionId: 'analytics.view' },
+    path: 'auth',
+    loadChildren: () => import('./pages/auth/auth.routes'),
   },
 ];
-
-// In app initialization:
-layoutService.setApps(apps);
 ```
 
-#### AppConfigurator
-
-Theme customizer dropdown. Opened from topbar via pStyleClass.
-
-**Features:**
-- Primary color selector (16 colors + noir)
-- Surface color selector (9 colors)
-- Preset selector (Aura, Lara, Nora)
-- Menu mode selector (static/overlay)
-- Dynamic theme application via PrimeUI themes API
-
-#### AppFloatingConfigurator
-
-Fixed-position floating button for theme customization. Provides quick access to dark mode toggle and color palette.
-
-### 2. LayoutService
+---
 
-Signal-based service for managing layout state. Singleton (`providedIn: 'root'`).
+## 2. LayoutService — Reading and Updating Layout State
 
 ```typescript
 import { LayoutService } from '@flusys/ng-layout';
 
-@Component({...})
-export class AppComponent {
-  private readonly layoutService = inject(LayoutService);
-}
-```
+@Component({ ... })
+export class MyComponent {
+  private readonly layout = inject(LayoutService);
 
-**Signals:**
+  // Read signals
+  readonly isDark    = this.layout.isDarkTheme;  // Signal<boolean>
+  readonly isTopbar  = this.layout.isTopbar;     // Signal<boolean>
+  readonly isOverlay = this.layout.isOverlay;    // Signal<boolean>
+  readonly menu      = this.layout.menu;         // Signal<IMenuItem[]> — permission-filtered
 
-| Signal | Type | Description |
-|--------|------|-------------|
-| `layoutConfig` | `Signal<LayoutConfig>` | Theme/preset/menuMode configuration |
-| `layoutState` | `Signal<LayoutState>` | UI state (menu active, sidebar visible) |
-| `transitionComplete` | `Signal<boolean>` | Dark mode transition state |
-| `userProfile` | `Signal<UserProfile \| null>` | Current user display data |
-| `companyProfile` | `Signal<CompanyProfile \| null>` | Current company display data |
-| `appName` | `Signal<string>` | App name for fallback display |
-| `menu` | `Computed<IMenuItem[]>` | Permission-filtered menu items |
-| `apps` | `Computed<ILauncherApp[]>` | Permission-filtered launcher apps |
-
-**Computed Signals:**
-
-| Signal | Type | Description |
-|--------|------|-------------|
-| `isDarkTheme` | `Computed<boolean>` | Whether dark theme is active |
-| `isSidebarActive` | `Computed<boolean>` | Whether sidebar/menu is visible |
-| `isOverlay` | `Computed<boolean>` | Whether menu mode is overlay |
-| `getPrimary` | `Computed<string>` | Current primary color |
-| `getSurface` | `Computed<string \| null>` | Current surface color |
-| `userName` | `Computed<string>` | User name or "User" fallback |
-| `userEmail` | `Computed<string>` | User email |
-| `userProfilePictureUrl` | `Computed<string \| null>` | Profile picture URL |
-| `companyName` | `Computed<string>` | Company name or appName fallback |
-| `companyLogoUrl` | `Computed<string \| null>` | Company logo URL |
-| `isAuthenticated` | `Computed<boolean>` | Whether user profile exists |
-| `hasApps` | `Computed<boolean>` | Whether filtered apps exist |
-
-**Methods:**
-
-| Method | Description |
-|--------|-------------|
-| `onMenuToggle()` | Toggle menu visibility (handles static/overlay/mobile) |
-| `onConfigUpdate()` | Emit config change event |
-| `onMenuStateChange(event)` | Emit menu item state change |
-| `reset()` | Reset menu state |
-| `setUserProfile(profile)` | Set user profile for layout display |
-| `setCompanyProfile(profile)` | Set company profile for layout display |
-| `setMenu(items)` | Set raw menu items (auto-filtered by permissions) |
-| `clearMenu()` | Clear menu items |
-| `setApps(apps)` | Set launcher apps (auto-filtered by permissions) |
-| `clearApps()` | Clear launcher apps |
-| `toggleDarkMode(config?)` | Toggle dark mode CSS class |
-| `isDesktop()` | Check if viewport > 991px |
-| `isMobile()` | Check if viewport <= 991px |
-
-**RxJS Observables:**
-
-| Observable | Description |
-|------------|-------------|
-| `menuSource$` | Menu state change events |
-| `resetSource$` | Menu reset events |
-| `configUpdate$` | Config change events |
-| `overlayOpen$` | Menu overlay opened |
-
-#### Configuration Persistence
-
-Layout configuration is automatically persisted to localStorage and restored on app bootstrap.
-
-**localStorage Key:** `flusys.layout.config`
-
-**Persisted Configuration (LayoutConfig):**
-```typescript
-interface LayoutConfig {
-  preset?: string;           // "Aura" | "Lara" | "Nora"
-  primary?: string;          // "emerald" | "green" | "blue" | etc.
-  surface?: string | null;   // "slate" | "gray" | "zinc" | etc. | null
-  darkTheme?: boolean;
-  menuMode?: 'static' | 'overlay';
-}
-```
-
-**Behavior:**
-- Changes saved automatically via Angular `effect()` when config changes
-- Configuration restored on page refresh (merged with defaults)
-- SSR-safe (`isPlatformBrowser` check)
-- Invalid preset falls back to "Aura", invalid menuMode falls back to "static"
-- Corrupted JSON is cleared and defaults are used
-- Version mismatches trigger automatic clearing
-
-**Clearing Saved Configuration:**
-```typescript
-import { LayoutPersistenceService } from '@flusys/ng-layout';
-
-inject(LayoutPersistenceService).clear();
-```
-
-### 3. Theme Management
-
-Built-in theme support with light/dark modes using PrimeUI themes.
-
-**Dark mode toggle** uses the View Transition API (with fallback):
-```typescript
-// AppTopbar toggles dark mode by updating layoutConfig signal:
-this.layoutService.layoutConfig.update((state) => ({
-  ...state,
-  darkTheme: !state.darkTheme,
-}));
-```
-
-**Host binding** for root component:
-```typescript
-@Component({
-  host: { '[class.app-dark]': 'layoutService.isDarkTheme()' }
-})
-export class AppComponent {
-  readonly layoutService = inject(LayoutService);
 }
 ```
 
-**Pre-defined Themes:**
-
-| Theme | Base | Primary Color |
-|-------|------|---------------|
-| `GreenTheme` | Material | `#01712c` |
-| `NavyBlueTheme` | Material | `#3535cd` |
-
-```typescript
-import { GreenTheme, NavyBlueTheme } from '@flusys/ng-layout';
-```
-
-### 4. Auth Integration
-
-Layout components use injection tokens to access auth data without depending on ng-auth.
+To push user/company profile into the topbar (done automatically by `ng-auth`'s bridge service):
 
-#### LAYOUT_AUTH_STATE Token
-
-Provides current user/company/branch state to layout components.
-
-```typescript
-interface ILayoutAuthState {
-  readonly currentCompanyInfo: Signal<ICompanyInfo | null>;
-  readonly currentBranchInfo: Signal<IBranchInfo | null>;
-  readonly loginUserData: Signal<IUserInfo | null>;
-}
-```
-
-#### LAYOUT_AUTH_API Token
-
-Provides auth actions (logout, company switching) to layout components.
-
-```typescript
-interface ILayoutAuthApi {
-  logOut(): Observable<any>;
-  navigateLogin(withUrl?: boolean): void;
-  switchCompany(companyId: string, branchId: string): Observable<any>;
-  getUserCompanies(): Observable<ICompanyInfo[]>;
-  getCompanyBranches(companyId: string): Observable<IBranchInfo[]>;
-}
-```
-
-#### Providing Auth Tokens
-
-```typescript
-// app.config.ts
-import { LAYOUT_AUTH_STATE, LAYOUT_AUTH_API } from '@flusys/ng-layout';
-import { AuthLayoutStateAdapter, AuthLayoutApiAdapter } from '@flusys/ng-auth';
-
-providers: [
-  { provide: LAYOUT_AUTH_STATE, useExisting: AuthLayoutStateAdapter },
-  { provide: LAYOUT_AUTH_API, useExisting: AuthLayoutApiAdapter },
-]
-```
-
-Components inject tokens with `{ optional: true }` and degrade gracefully when auth is not provided.
-
-### 5. Permission-Based Menu Filtering
-
-Menu items and launcher apps are automatically filtered based on user permissions using `permissionLogic`.
-
-**How it works:**
-1. Raw menu items set via `layoutService.setMenu(items)`
-2. `LayoutService.menu` is a `computed()` that filters via `filterMenuByPermissions()`
-3. Permission evaluation uses `evaluateLogicNode()` from ng-shared
-4. Same pattern applies to apps via `filterAppsByPermissions()`
-
-**ILogicNode Types:**
-```typescript
-interface ILogicNode {
-  id: string;
-  type: 'group' | 'action' | 'role';
-  operator?: 'AND' | 'OR';     // Required when type is 'group'
-  actionId?: string;            // Required when type is 'action'
-  roleId?: string;              // Required when type is 'role'
-  children?: ILogicNode[];      // Required when type is 'group'
-}
-```
-
-**Best Practice:** Use logic nodes (parent menu items without `routerLink`) with `permissionLogic` as permission gates for entire branches:
-
-```typescript
-// Logic node gates all children
-{
-  id: 'administration',
-  label: 'Administration',
-  icon: 'pi pi-cog',
-  permissionLogic: { id: 'admin-check', type: 'action', actionId: 'admin.access' },
-  children: [
-    { id: 'users', label: 'Users', routerLink: ['/admin/users'] },
-    { id: 'settings', label: 'Settings', routerLink: ['/admin/settings'] },
-  ],
-}
-```
-
-**Complex permission examples:**
-```typescript
-// OR - user needs ANY permission
-permissionLogic: {
-  id: 'reports-check',
-  type: 'group',
-  operator: 'OR',
-  children: [
-    { id: '1', type: 'action', actionId: 'reports.view' },
-    { id: '2', type: 'role', roleId: 'manager-role-id' },
-  ],
-}
-
-// AND - user needs ALL permissions
-permissionLogic: {
-  id: 'admin-check',
-  type: 'group',
-  operator: 'AND',
-  children: [
-    { id: '1', type: 'action', actionId: 'admin.access' },
-    { id: '2', type: 'role', roleId: 'superuser-role-id' },
-  ],
-}
-```
-
-## Installation
-
-Build ng-layout after ng-core and ng-shared:
-
-```bash
-npm run build:ng-core
-npm run build:ng-shared
-npm run build:ng-layout
-# Or build all libraries:
-npm run build:libs
-```
-
-## Usage Examples
-
-### Basic Layout Setup
-
-```typescript
-// app.component.ts
-import { Component, inject } from '@angular/core';
-import { RouterOutlet } from '@angular/router';
-import { AppLayout, LayoutService } from '@flusys/ng-layout';
-
-@Component({
-  selector: 'app-root',
-  standalone: true,
-  imports: [RouterOutlet, AppLayout],
-  template: `
-    <app-layout>
-      <router-outlet />
-    </app-layout>
-  `,
-  host: { '[class.app-dark]': 'layoutService.isDarkTheme()' },
-})
-export class AppComponent {
-  readonly layoutService = inject(LayoutService);
-}
-```
-
-### Menu Configuration
-
-```typescript
-import { LayoutService, IMenuItem } from '@flusys/ng-layout';
-
-const menuItems: IMenuItem[] = [
-  {
-    label: 'Dashboard',
-    icon: 'pi pi-home',
-    routerLink: ['/dashboard'],
-  },
-  {
-    label: 'Management',
-    icon: 'pi pi-cog',
-    children: [
-      { label: 'Users', icon: 'pi pi-users', routerLink: ['/users'] },
-      { label: 'Roles', icon: 'pi pi-shield', routerLink: ['/roles'] },
-    ],
-  },
-  { separator: true },
-  {
-    label: 'Settings',
-    icon: 'pi pi-cog',
-    routerLink: ['/settings'],
-  },
-];
+---
 
-layoutService.setMenu(menuItems);
-```
+## 3. Integration Tokens — Auth, Notifications, Language
 
-### Auth Integration
+Connect feature packages to the layout via injection tokens. Register them in `app.config.ts`.
 
 ```typescript
-// app.config.ts
-import { LAYOUT_AUTH_STATE, LAYOUT_AUTH_API } from '@flusys/ng-layout';
-import { AuthLayoutStateAdapter, AuthLayoutApiAdapter } from '@flusys/ng-auth';
+import { provideAuthLayoutIntegration } from '@flusys/ng-auth';
+import { provideNotificationProviders }  from '@flusys/ng-notification';
+import { provideLocalization }           from '@flusys/ng-localization';
 
 export const appConfig: ApplicationConfig = {
   providers: [
-    { provide: LAYOUT_AUTH_STATE, useExisting: AuthLayoutStateAdapter },
-    { provide: LAYOUT_AUTH_API, useExisting: AuthLayoutApiAdapter },
+    ...provideAuthLayoutIntegration(), // topbar user profile + logout
+    ...provideNotificationProviders(), // topbar notification bell
+    ...provideLocalization({ ... }),   // topbar language selector
   ],
 };
 ```
 
-### Dynamic Menu from Backend
+The layout reads these tokens to render topbar slots without directly importing feature packages.
 
-```typescript
-import { LayoutService } from '@flusys/ng-layout';
-import { MenuApiService } from './services/menu-api.service';
-
-@Component({...})
-export class AppComponent implements OnInit {
-  private readonly layoutService = inject(LayoutService);
-  private readonly menuApi = inject(MenuApiService);
-
-  async ngOnInit() {
-    const response = await firstValueFrom(this.menuApi.getUserMenu());
-    if (response.success) {
-      this.layoutService.setMenu(response.data);
-    }
-  }
-}
-```
-
-## Best Practices
-
-### Layout Structure
-- Use `AppLayout` as root layout component
-- Set menu items via `layoutService.setMenu()` during app initialization
-- Use `LayoutService` for all layout state changes
-- Don't manipulate DOM directly for layout changes
-
-### Menu Management
-- Load menus dynamically from backend (IAM module)
-- Group related items under parent menu items with `permissionLogic`
-- Use PrimeIcons for consistency
-- Use `children` property for nested items (not `items`)
-
-### Auth Integration
-- Use injection tokens (`LAYOUT_AUTH_STATE`, `LAYOUT_AUTH_API`)
-- Don't import ng-auth directly in ng-layout
-- Provide adapters at app level in `app.config.ts`
-- Layout works without auth (graceful degradation)
-
-### Theme Management
-- Use CSS animations, not `@angular/animations`
-- Apply `app-dark` class to root element via host binding
-- Theme preferences persist automatically to localStorage
-- Test both light and dark themes for contrast
-
-### Responsive Design
-- Use Tailwind for responsive utilities
-- Layout automatically handles responsive behavior (static → overlay on mobile)
-- Menu closes on navigation and outside clicks
-
-## Common Issues
-
-### Menu Not Showing
-
-Ensure menu items are set via `LayoutService.setMenu()`:
-```typescript
-this.layoutService.setMenu([/* items */]);
-```
+---
 
-### Auth Info Not in Topbar
+## 4. Clear Persisted Layout
 
-Provide `LAYOUT_AUTH_STATE` in `app.config.ts`:
 ```typescript
-{ provide: LAYOUT_AUTH_STATE, useExisting: AuthLayoutStateAdapter }
-```
-
-### Theme Not Applying
+import { LayoutPersistenceService } from '@flusys/ng-layout';
 
-Add host binding to root component:
-```typescript
-@Component({
-  host: { '[class.app-dark]': 'layoutService.isDarkTheme()' }
-})
+inject(LayoutPersistenceService).clear(); // removes flusys.layout.config from localStorage
 ```
 
-### Sidebar Not Responsive
-
-Layout automatically handles responsive behavior. Ensure you're using the `AppLayout` component, not a custom layout.
-
-## API Reference
-
-### Components
-
-| Component | Selector | Description |
-|-----------|----------|-------------|
-| `AppLayout` | `app-layout` | Main layout wrapper |
-| `AppTopbar` | `app-topbar` | Application header |
-| `AppSidebar` | `app-sidebar` | Navigation sidebar |
-| `AppMenu` | `app-menu` | Menu container |
-| `AppMenuitem` | `[app-menuitem]` | Recursive menu item |
-| `AppFooter` | `app-footer` | Footer |
-| `AppProfile` | `app-profile` | User profile dropdown |
-| `AppCompanyBranchSelector` | `app-company-branch-selector` | Company/branch switcher |
-| `AppLauncher` | `app-launcher` | App launcher grid |
-| `AppConfigurator` | `app-configurator` | Theme customizer |
-| `AppFloatingConfigurator` | `app-floating-configurator` | Floating theme button |
-
-### Services
-
-| Service | Description |
-|---------|-------------|
-| `LayoutService` | Signal-based layout state management |
-| `LayoutPersistenceService` | localStorage persistence with validation |
-
-### Injection Tokens
-
-| Token | Interface | Description |
-|-------|-----------|-------------|
-| `LAYOUT_AUTH_STATE` | `ILayoutAuthState` | Auth state signals |
-| `LAYOUT_AUTH_API` | `ILayoutAuthApi` | Auth actions |
-
-### Interfaces
-
-| Interface | Description |
-|-----------|-------------|
-| `IMenuItem` | Menu item configuration |
-| `ILauncherApp` | App launcher item configuration |
-| `ILayoutAuthState` | Auth state for layout |
-| `ILayoutAuthApi` | Auth actions for layout |
-| `ICompanyInfo` | Company information |
-| `IBranchInfo` | Branch information |
-| `IUserInfo` | User information |
-| `LayoutConfig` | Theme/preset configuration |
-| `LayoutState` | UI state (menu active, etc.) |
-| `UserProfile` | User display data |
-| `CompanyProfile` | Company display data |
-| `MenuChangeEvent` | Menu state change event |
-
-### Utility Functions
-
-| Function | Description |
-|----------|-------------|
-| `filterMenuByPermissions(items, permissions)` | Filter menu items by permission logic |
-| `filterAppsByPermissions(apps, permissions)` | Filter launcher apps by permission logic |
-
-### Pre-defined Themes
-
-| Export | Base Preset | Primary Color |
-|--------|-------------|---------------|
-| `GreenTheme` | Material | `#01712c` |
-| `NavyBlueTheme` | Material | `#3535cd` |
-
-## See Also
-
-- **[CORE-GUIDE.md](./CORE-GUIDE.md)** - Configuration, interceptors
-- **[SHARED-GUIDE.md](./SHARED-GUIDE.md)** - Shared components, provider interfaces
-- **[AUTH-GUIDE.md](./AUTH-GUIDE.md)** - Authentication integration, adapters
-
 ---
 
-**Last Updated:** 2026-02-16
-**Angular Version:** 21
+## License
+
+MIT © FLUSYS