@flusys/ng-layout 4.0.2 → 4.1.1

package/README.md

@@ -1,745 +1,518 @@
-# @flusys/ng-layout Package Guide
+# @flusys/ng-layout
 
-## Overview
-
-`@flusys/ng-layout` provides the application shell, menu system, theme management, and layout components for FLUSYS applications.
-
-**Key Principle:** ng-layout depends on ng-core and ng-shared, but remains independent of feature packages like ng-auth via injection tokens.
+> Application shell and layout system for the FLUSYS Angular platform — topbar, sidebar, menu, configurator, and layout state management.
 
-## Package Information
+[![npm version](https://img.shields.io/npm/v/@flusys/ng-layout.svg)](https://www.npmjs.com/package/@flusys/ng-layout)
+[![Angular](https://img.shields.io/badge/Angular-21-red.svg)](https://angular.io)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org)
+[![PrimeNG](https://img.shields.io/badge/PrimeNG-18+-blue.svg)](https://primeng.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 
-| Property | Value |
-|----------|-------|
-| Package | `@flusys/ng-layout` |
-| Version | 4.0.2 |
-| Dependencies | ng-core, ng-shared |
-| Build | `npm run build:ng-layout` |
-
-## Architecture
+---
 
-```
-ng-layout/
-├── components/
-│   ├── app.layout.ts              # Main layout wrapper
-│   ├── app.topbar.ts              # Application header
-│   ├── app.sidebar.ts             # Sidebar wrapper
-│   ├── app.menu.ts                # Menu container
-│   ├── app.menuitem.ts            # Recursive menu item
-│   ├── app.footer.ts              # Footer component
-│   ├── app.configurator.ts        # Theme customizer
-│   ├── app.floatingconfigurator.ts
-│   └── top-bar/
-│       ├── app.profile.ts
-│       ├── app.launcher.ts
-│       └── app.company-branch-selector.ts
-├── interfaces/
-│   ├── layout-auth.interface.ts   # Auth integration tokens
-│   └── view-transitions.ts
-├── services/
-│   ├── layout.service.ts          # Layout state management
-│   └── layout-persistence.service.ts
-├── theme/
-│   ├── green-theme.ts
-│   └── navy-blue-theme.ts
-└── utils/
-    ├── menu-filter.util.ts
-    └── apps-filter.util.ts
-```
+## Table of Contents
+
+- [Overview](#overview)
+- [Features](#features)
+- [Compatibility](#compatibility)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Layout Configuration](#layout-configuration)
+  - [LayoutConfig](#layoutconfig)
+  - [Menu Modes](#menu-modes)
+  - [Themes & Colors](#themes--colors)
+- [Injection Tokens](#injection-tokens)
+- [LayoutService](#layoutservice)
+- [LayoutState](#layoutstate)
+- [Components](#components)
+  - [AppLayoutComponent](#applayoutcomponent)
+  - [AppTopbarComponent](#apptopbarcomponent)
+  - [AppSidebarComponent](#appsidebarcomponent)
+  - [AppMenuComponent](#appmenucomponent)
+  - [AppMenuitemComponent](#appmenuitemcomponent)
+  - [AppCompanyBranchSelectorComponent](#appcompanybranchselectorcomponent)
+  - [AppConfiguratorComponent](#appconfiguratorscomponent)
+- [Configuration Persistence](#configuration-persistence)
+- [Integration Tokens](#integration-tokens)
+- [Troubleshooting](#troubleshooting)
+- [License](#license)
 
 ---
 
-## Components
+## Overview
 
-### AppLayout
+`@flusys/ng-layout` provides the complete application shell for FLUSYS apps. It includes the topbar, sidebar, menu system, and layout configurator panel — all powered by Angular 21 signals and PrimeNG.
 
-Main layout wrapper with signal-based state management.
+The layout integrates with auth, notification, and localization packages through injection token interfaces, maintaining clean package independence via the Provider Interface Pattern.
 
-```typescript
-import { AppLayout, LayoutService } from '@flusys/ng-layout';
-
-@Component({
-  selector: 'app-root',
-  imports: [AppLayout],
-  template: `<app-layout><router-outlet /></app-layout>`,
-  host: { '[class.app-dark]': 'layoutService.isDarkTheme()' },
-})
-export class AppComponent {
-  readonly layoutService = inject(LayoutService);
-}
-```
+---
 
-**Includes:** AppTopbar, AppSidebar, main content area, AppFooter, layout mask overlay
+## Features
 
-**Layout Modes:**
-- **Static** - Sidebar always visible on desktop, overlay on mobile
-- **Overlay** - Sidebar overlays content when opened
-- **Topbar** - Horizontal menu bar at the top for desktop, sidebar on mobile
+- ✅ Three menu modes: `static`, `overlay`, `topbar`
+- ✅ Signal-based layout state management (`LayoutService`)
+- ✅ Layout persistence (theme, color, mode saved to localStorage)
+- ✅ Company/branch selector in sidebar
+- ✅ Topbar user profile dropdown with avatar
+- ✅ Notification bell integration via injection token
+- ✅ Language selector integration via injection token
+- ✅ Responsive mobile layout
+- ✅ Fully configurable color palettes and themes
+- ✅ Zoneless-compatible
 
-**Dynamic CSS Classes:**
-| Class | Condition |
-|-------|-----------|
-| `layout-static` | Static menu mode |
-| `layout-overlay` | Overlay menu mode |
-| `layout-static-inactive` | Static menu collapsed on desktop |
-| `layout-overlay-active` | Overlay menu open |
-| `layout-mobile-active` | Mobile menu open |
+---
 
-**Behavior:**
-- Subscribes to `layoutService.overlayOpen$` for outside click handling
-- Auto-hides menu on route navigation
-- Blocks body scroll when mobile menu is active
+## Compatibility
 
-### AppTopbar
+| Package | Version |
+|---------|---------|
+| Angular | 21+ |
+| @flusys/ng-core | 4.x |
+| @flusys/ng-shared | 4.x |
+| PrimeNG | 18+ |
+| Tailwind CSS | 3+ |
 
-Application header with branding and user actions. Supports different layouts via `menuMode`.
+---
 
-**Static/Overlay Modes:**
-```
-┌─────────────────────────────────────────────────────────────────┐
-│ [≡] CompanyName          [☀/🌙] [🎨] [...] [Apps] [🏢] [👤]    │
-└─────────────────────────────────────────────────────────────────┘
-```
+## Installation
 
-**Topbar Mode (Desktop):**
-```
-┌───────────────────────────────────────────────────────────────────────────────┐
-│ CompanyName  [Dashboard] [Admin] [IAM] [Storage]  [☀/🌙] [🎨] [Apps] [🏢] [👤]│
-└───────────────────────────────────────────────────────────────────────────────┘
+```bash
+npm install @flusys/ng-layout @flusys/ng-core @flusys/ng-shared
 ```
 
-| Element | Description |
-|---------|-------------|
-| `[≡]` | Menu toggle (Static/Overlay on mobile, Topbar on desktop) |
-| CompanyName | From `layoutService.companyName` → links to `/` |
-| Menu Items | In topbar mode, rendered horizontally on desktop |
-| `[☀/🌙]` | Dark mode toggle |
-| `[🎨]` | AppConfigurator panel |
-| `[...]` | Mobile menu (hidden on desktop) |
-| `[Apps]` | AppLauncher (if `layoutService.hasApps()`) |
-| `[🏢]` | AppCompanyBranchSelector (if company feature enabled) |
-| `[👤]` | AppProfile dropdown |
-
-**Behavior:**
-- **Topbar on desktop:** Renders menu items horizontally with hover-triggered submenus
-- **Topbar on mobile:** Falls back to vertical sidebar menu
-- **Static/Overlay:** Standard sidebar behavior (unchanged)
-
-### AppMenu & AppMenuitem
-
-Menu container renders permission-filtered items from `layoutService.menu`.
-
-**AppMenuitem Signal Inputs:**
-| Input | Type | Description |
-|-------|------|-------------|
-| `item` | `IMenuItem` | Required menu item data |
-| `index` | `number` | Required index in parent |
-| `parentKey` | `string` | Optional parent key (default: `''`) |
-
-**Router Link Active Options:**
-- Root path (`/`) uses `'exact'` matching
-- Other paths use `'subset'` matching for child route support
-
-**CSS Transitions (no @angular/animations):**
-```css
-:host ul {
-  transition: max-height 400ms cubic-bezier(0.86, 0, 0.07, 1);
-}
-:host ul.submenu-collapsed { max-height: 0; }
-:host ul.submenu-expanded { max-height: 1000px; }
-```
-
-**Topbar Mode Behavior:**
-- `@if (layoutService.isTopbar())` - Conditional rendering for topbar-specific UI
-- `onMouseEnter()` - Triggers submenu display on hover (topbar only)
-- Parent link positioning tracked via `@viewChild('parentLink')` for submenu alignment
-- Submenu visibility controlled by `submenu-expanded` / `submenu-collapsed` classes
-- Submenus only expand/collapse in sidebar mode (`!layoutService.isTopbar()`)
-
 ---
 
-## Topbar Mode (v4.0.1)
+## Quick Start
 
-Horizontal navigation bar at the top of the page, replacing traditional sidebar on desktop.
+### 1. Set Up App Layout Route
 
-### Features
+```typescript
+// app.routes.ts
+import { Routes } from '@angular/router';
+import { AppLayoutComponent } from '@flusys/ng-layout';
 
-- **Desktop:** Horizontal menu items with hover-triggered submenus
-- **Mobile:** Falls back to traditional vertical sidebar
-- **Responsive:** Auto-switches between topbar and sidebar based on viewport
-- **Submenus:** Positioned below parent items, auto-adjusted to viewport
-- **Persistence:** Menu visibility state persists in `layoutService.layoutState().topbarMenuVisible`
+export const routes: Routes = [
+  {
+    path: '',
+    component: AppLayoutComponent,
+    children: [
+      {
+        path: 'dashboard',
+        loadComponent: () => import('./pages/dashboard/dashboard.component'),
+      },
+      {
+        path: 'products',
+        loadComponent: () => import('./pages/products/product-list.component'),
+      },
+    ],
+  },
+  {
+    path: 'auth',
+    loadChildren: () => import('./pages/auth/auth.routes'),
+  },
+];
+```
 
-### Layout Behavior
+### 2. Define Menu Configuration
 
-**Desktop (Topbar Mode):**
-- Menu items rendered horizontally next to company name
-- Hovering over items with children shows submenu
-- No sidebar visible
-- Menu toggle only appears on mobile
+```typescript
+// app-menu.config.ts
+import { IMenuItem } from '@flusys/ng-layout';
 
-**Mobile (Topbar Mode):**
-- Menu items rendered in vertical sidebar (same as overlay mode)
-- Topbar shows menu toggle button
-- Sidebar overlays content when open
+export const APP_MENU: IMenuItem[] = [
+  {
+    labelKey: 'menu.dashboard',
+    label: 'Dashboard',
+    icon: 'pi pi-home',
+    routerLink: ['/dashboard'],
+  },
+  {
+    labelKey: 'menu.products',
+    label: 'Products',
+    icon: 'pi pi-box',
+    items: [
+      {
+        labelKey: 'menu.products.list',
+        label: 'All Products',
+        routerLink: ['/products'],
+      },
+      {
+        labelKey: 'menu.products.create',
+        label: 'Add Product',
+        routerLink: ['/products/create'],
+      },
+    ],
+  },
+];
+```
 
-### Configuration
+### 3. Provide Layout Configuration
 
 ```typescript
-// Set menu mode to topbar
-layoutService.updateLayoutConfig({ menuMode: 'topbar' });
-
-// Or persist via LayoutPersistenceService
-layoutPersistenceService.save({
-  preset: 'Aura',
-  primary: 'blue',
-  menuMode: 'topbar',
-  darkTheme: false,
-});
+// app.config.ts
+import { ApplicationConfig } from '@angular/core';
+import { APP_CONFIG } from '@flusys/ng-core';
+import { LAYOUT_MENU, LAYOUT_CONFIG } from '@flusys/ng-layout';
+import { APP_MENU } from './app-menu.config';
+import { environment } from './environments/environment';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    { provide: APP_CONFIG, useValue: environment },
+    { provide: LAYOUT_MENU, useValue: APP_MENU },
+    {
+      provide: LAYOUT_CONFIG,
+      useValue: {
+        menuMode: 'static',
+        theme: 'lara-light-blue',
+        colorScheme: 'light',
+      },
+    },
+  ],
+};
 ```
 
-### Styling
-
-Topbar styles are defined in `assets/layout/_topbar_nav.scss`:
-
-- `.layout-topbar-nav-horizontal` - Main horizontal nav container
-- `.layout-topbar-nav-hidden` - Hide nav on mobile (Tailwind: `hidden`)
-- Submenu positioning with `position: absolute`
-- Chevron icon for topbar (vs angle-down for sidebar)
-- Hover effects with opacity and visibility transitions
-
-### AppMenuitem Changes for Topbar
-
-When in topbar mode:
-- Submenu toggler icon changes to `pi-chevron-right` (vs `pi-angle-down`)
-- Parent links show `cursor: default` instead of pointer
-- Submenus positioned absolutely with auto-adjustment logic
-- Hover-triggered submenu display (vs click-triggered in sidebar)
-
 ---
 
-### AppFooter
+## Layout Configuration
 
-Displays branding from `LayoutService`: `appName`, `authorName`, `authorUrl`
+### LayoutConfig
 
-### AppProfile
-
-User profile dropdown in topbar.
+```typescript
+interface LayoutConfig {
+  /** Menu display mode */
+  menuMode: 'static' | 'overlay' | 'topbar';
 
-**Features:**
-- User info (picture, name, email) with text truncation
-- Profile link → `/profile`
-- Copy SignUp Link → `{origin}/auth/register?companySlug={slug}` (hidden if sign-up disabled)
-- Logout with toast feedback
+  /** PrimeNG theme name */
+  theme: string;
 
-**Computed Signals:**
-| Signal | Source | Fallback |
-|--------|--------|----------|
-| `userName` | `authState.loginUserData()?.name` | `'Guest'` |
-| `userEmail` | `authState.loginUserData()?.email` | `''` |
-| `profilePicture` | `layoutService.userProfilePictureUrl()` | `''` |
-| `signUpEnabled` | `APP_CONFIG` via `isSignUpEnabled()` helper | `false` |
+  /** Color scheme */
+  colorScheme: 'light' | 'dark' | 'dim';
 
-**Sign-up Link Visibility:**
-- Only shown when `APP_CONFIG.services.auth.features.signUp === true`
-- Controlled via `signUpEnabled()` computed signal
-- Uses `isSignUpEnabled()` helper from `@flusys/ng-core`
+  /** Ripple effect */
+  ripple?: boolean;
 
-### AppCompanyBranchSelector
+  /** Scale factor (12-16) */
+  scale?: number;
 
-Company/branch switcher in topbar. Shown when company feature is enabled.
+  /** Menu theme */
+  menuTheme?: 'light' | 'dark' | 'colored';
 
-**State Signals:**
-| Signal | Description |
-|--------|-------------|
-| `companies` | Available companies list |
-| `branches` | Branches for selected company |
-| `selectedCompanyId` / `selectedBranchId` | Current selection |
-| `isLoadingCompanies` / `isLoadingBranches` | Loading states |
-| `isSwitching` | Switch operation in progress |
-| `canSwitch` | Computed: enabled when selection differs from current |
+  /** Card border style */
+  inputStyle?: 'outlined' | 'filled';
+}
+```
 
-**Workflow:**
-1. Click button → Panel opens, companies load
-2. Select company → Branches load (auto-select if single branch)
-3. Select branch → Click "Switch" → API call → JWT updated → Redirect
+### Menu Modes
 
-### AppLauncher
+#### Static Mode (Default)
 
-App launcher grid for quick access to external applications.
+Sidebar is always visible on desktop. Collapses to icons on tablet.
 
 ```typescript
-const apps: ILauncherApp[] = [
-  {
-    id: 'docs',
-    name: 'Docs',
-    iconType: IconTypeEnum.PrimeNg,
-    icon: 'pi pi-book',
-    url: 'https://docs.example.com',
-    permissionLogic: { id: 'docs', type: 'action', actionId: 'docs.view' }, // optional
-  },
-];
-layoutService.setApps(apps);
+{ provide: LAYOUT_CONFIG, useValue: { menuMode: 'static' } }
 ```
 
-**Features:**
-- Responsive grid: `grid-cols-2 sm:grid-cols-3`
-- External links (new tab)
-- Permission filtering via `permissionLogic`
-- Only visible when `layoutService.hasApps()` is true
-
-### AppConfigurator
-
-Theme customizer dropdown.
+#### Overlay Mode
 
-**Options:**
-| Setting | Values |
-|---------|--------|
-| Primary colors | `emerald`, `green`, `lime`, `orange`, `amber`, `yellow`, `teal`, `cyan`, `sky`, `blue`, `indigo`, `violet`, `purple`, `fuchsia`, `pink`, `rose`, `noir` |
-| Surface colors | `slate`, `gray`, `zinc`, `neutral`, `stone`, `soho`, `viva`, `ocean` |
-| Presets | `Aura` (default), `Lara`, `Nora` |
-| Menu mode | `static`, `overlay`, `topbar` |
+Sidebar slides over content. Click outside to close.
 
-Uses `$t()`, `updatePreset()`, `updateSurfacePalette()` from `@primeuix/themes`.
+```typescript
+{ provide: LAYOUT_CONFIG, useValue: { menuMode: 'overlay' } }
+```
 
-### AppFloatingConfigurator
+#### Topbar Mode (v4.0.1+)
 
-Fixed-position floating buttons for pages without AppLayout (e.g., auth pages).
+Desktop renders horizontal navigation bar. Mobile falls back to vertical sidebar.
 
 ```typescript
-@Component({
-  imports: [AppFloatingConfigurator],
-  template: `<app-floating-configurator /><div class="login-form">...</div>`
-})
-export class LoginComponent {}
+{ provide: LAYOUT_CONFIG, useValue: { menuMode: 'topbar' } }
 ```
 
-Position: `top-4 md:top-8 right-2 md:right-8 z-50`
+Submenu items appear on hover in topbar mode with automatic positioning.
 
----
+### Themes & Colors
 
-## Services
+Built-in themes (PrimeNG):
 
-### LayoutService
+| Theme | Description |
+|-------|-------------|
+| `lara-light-blue` | Default — light blue |
+| `lara-dark-blue` | Dark blue |
+| `lara-light-indigo` | Light indigo |
+| `lara-dark-indigo` | Dark indigo |
+| `lara-light-purple` | Light purple |
+| `lara-dark-purple` | Dark purple |
+| `lara-light-teal` | Light teal |
+| `lara-dark-teal` | Dark teal |
 
-Signal-based singleton service for layout state management.
+---
 
-#### Interfaces
+## Injection Tokens
 
-```typescript
-interface LayoutConfig {
-  preset?: string;           // "Aura" | "Lara" | "Nora"
-  primary?: string;          // "emerald" | "green" | etc.
-  surface?: string | null;   // "slate" | "gray" | etc.
-  darkTheme?: boolean;
-  menuMode?: 'static' | 'overlay' | 'topbar';
-}
+| Token | Type | Description |
+|-------|------|-------------|
+| `LAYOUT_CONFIG` | `InjectionToken<LayoutConfig>` | Initial layout configuration |
+| `LAYOUT_MENU` | `InjectionToken<IMenuItem[]>` | Application menu items |
+| `LAYOUT_AUTH_STATE` | `InjectionToken<ILayoutAuthState>` | Auth state bridge (from ng-auth) |
+| `LAYOUT_AUTH_API` | `InjectionToken<ILayoutAuthApi>` | Auth API bridge (from ng-auth) |
+| `LAYOUT_NOTIFICATION_BELL` | `InjectionToken<INotificationBellProvider>` | Notification bell (from ng-notification) |
+| `LAYOUT_LANGUAGE_SELECTOR` | `InjectionToken<ILanguageSelectorProvider>` | Language selector (from ng-localization) |
 
-interface LayoutState {
-  staticMenuDesktopInactive?: boolean;
-  overlayMenuActive?: boolean;
-  staticMenuMobileActive?: boolean;
-  menuHoverActive?: boolean;
-  topbarMenuVisible?: boolean;  // For topbar mode on desktop
-}
+---
 
-interface UserProfile { id: string; name: string; email: string; profilePictureUrl?: string | null; }
-interface CompanyProfile { id: string; name: string; slug: string; logoUrl?: string | null; }
-```
+## LayoutService
+
+Central signal-based service for layout state management.
 
-#### Signals
-
-**State Signals (readonly):**
-| Signal | Type |
-|--------|------|
-| `layoutConfig` | `Signal<LayoutConfig>` |
-| `layoutState` | `Signal<LayoutState>` |
-| `transitionComplete` | `Signal<boolean>` |
-| `userProfile` | `Signal<UserProfile \| null>` |
-| `companyProfile` | `Signal<CompanyProfile \| null>` |
-
-**Static Values (from APP_CONFIG):**
-| Property | Fallback |
-|----------|----------|
-| `appName` | `DEFAULT_APP_NAME` |
-| `authorName` | `DEFAULT_AUTHOR.name` |
-| `authorUrl` | `DEFAULT_AUTHOR.url` |
-
-**Computed Signals:**
-| Signal | Description |
-|--------|-------------|
-| `menu` | Permission-filtered menu items |
-| `apps` | Permission-filtered launcher apps |
-| `hasApps` | Whether apps exist |
-| `isDarkTheme` | Dark theme active |
-| `isSidebarActive` | Sidebar visible |
-| `isStatic` | Static menu mode |
-| `isOverlay` | Overlay menu mode |
-| `isTopbar` | Topbar menu mode (horizontal nav on desktop) |
-| `getPrimary` / `getSurface` | Current colors |
-| `userName` / `userEmail` | User info (with fallbacks) |
-| `userProfilePictureUrl` / `companyLogoUrl` | Image URLs |
-| `companyName` | Company name or appName fallback |
-| `isAuthenticated` | User profile exists |
-
-#### Methods
-
-| Method | Description |
-|--------|-------------|
-| `onMenuToggle()` | Toggle menu (handles static/overlay/mobile) |
-| `onMenuStateChange(event)` | Emit menu state change |
-| `reset()` | Reset menu state |
-| `isDesktop()` / `isMobile()` | Viewport checks (SSR-safe) |
-| `updateLayoutConfig(config)` | Partial config update |
-| `updateLayoutState(state)` | Partial state update |
-| `toggleDarkMode(config?)` | Toggle `app-dark` class |
-| `setUserProfile(profile)` | Set user profile |
-| `setCompanyProfile(profile)` | Set company profile |
-| `setMenu(items)` / `clearMenu()` | Menu management |
-| `setApps(apps)` / `clearApps()` | Apps management |
-
-#### RxJS Observables
-
-| Observable | Purpose |
-|------------|---------|
-| `menuSource$` | Menu state change events |
-| `resetSource$` | Menu reset events |
-| `configUpdate$` | Config change events |
-| `overlayOpen$` | Menu overlay opened |
-
-#### Dark Mode Transition
-
-Uses View Transitions API with fallback:
 ```typescript
-toggleDarkMode(config?: LayoutConfig): void {
-  const isDark = (config ?? this._layoutConfig()).darkTheme;
-  this.document.documentElement.classList.toggle('app-dark', isDark);
+import { LayoutService } from '@flusys/ng-layout';
+
+@Component({ ... })
+export class MyComponent {
+  private layoutService = inject(LayoutService);
+
+  // Computed signals (read-only)
+  isStatic = this.layoutService.isStatic();       // boolean
+  isOverlay = this.layoutService.isOverlay();     // boolean
+  isTopbar = this.layoutService.isTopbar();       // boolean
+  isMobile = this.layoutService.isMobile();       // boolean
+  isMenuOpen = this.layoutService.isMenuOpen();   // boolean
+
+  // Actions
+  toggleMenu(): void {
+    this.layoutService.toggleMenu();
+  }
+
+  setTheme(theme: string): void {
+    this.layoutService.setTheme(theme);
+  }
+
+  setMenuMode(mode: 'static' | 'overlay' | 'topbar'): void {
+    this.layoutService.setMenuMode(mode);
+  }
 }
 ```
 
-### LayoutPersistenceService
-
-Persists layout configuration to localStorage.
+**LayoutService API:**
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `config` | `Signal<LayoutConfig>` | Current layout configuration |
+| `state` | `Signal<LayoutState>` | Current layout state |
+| `isStatic()` | `Signal<boolean>` | True if menu mode is static |
+| `isOverlay()` | `Signal<boolean>` | True if menu mode is overlay |
+| `isTopbar()` | `Signal<boolean>` | True if menu mode is topbar |
+| `isMobile()` | `Signal<boolean>` | True on mobile viewport |
+| `isMenuOpen()` | `Signal<boolean>` | True if sidebar is open |
+| `toggleMenu()` | `void` | Toggle sidebar open/close |
+| `hideMenu()` | `void` | Force sidebar closed |
+| `setTheme(theme)` | `void` | Change PrimeNG theme |
+| `setMenuMode(mode)` | `void` | Change menu mode |
+| `setColorScheme(scheme)` | `void` | Change color scheme |
 
-| Method | Description |
-|--------|-------------|
-| `load()` | Load and validate saved config |
-| `save(config)` | Save config with version |
-| `clear()` | Remove saved config |
+---
 
-**localStorage Key:** `flusys.layout.config`
+## LayoutState
 
-**Validation:**
-- Invalid preset → `'Aura'`
-- Invalid menuMode → `'static'` (valid: `'static'`, `'overlay'`, `'topbar'`)
-- Non-boolean darkTheme → `false`
-- Version mismatch or invalid JSON → Clear and return null
+Reactive state object managed by `LayoutService`:
 
----
+```typescript
+interface LayoutState {
+  /** Sidebar open on mobile */
+  staticMenuMobileActive: boolean;
 
-## Auth Integration
+  /** Overlay sidebar open */
+  overlayMenuActive: boolean;
 
-Layout components use injection tokens for auth data without direct ng-auth dependency.
+  /** Desktop sidebar collapsed */
+  staticMenuDesktopInactive: boolean;
 
-### Tokens
+  /** Right-click menu visible */
+  menuHoverActive: boolean;
 
-```typescript
-// LAYOUT_AUTH_STATE - Provides current user/company/branch state
-interface ILayoutAuthState {
-  currentCompanyInfo: Signal<ICompanyInfo | null>;
-  currentBranchInfo: Signal<IBranchInfo | null>;
-  loginUserData: Signal<IUserInfo | null>;
-}
+  /** Config panel open */
+  configSidebarVisible: boolean;
 
-// LAYOUT_AUTH_API - Provides auth actions
-interface ILayoutAuthApi {
-  logOut(): Observable<any>;
-  navigateLogin(withUrl?: boolean): void;
-  switchCompany(companyId: string, branchId: string): Observable<any>;
-  getUserCompanies(): Observable<ICompanyInfo[]>;
-  getCompanyBranches(companyId: string): Observable<IBranchInfo[]>;
+  /** Topbar nav visible (topbar mode) */
+  topbarMenuVisible: boolean;
 }
 ```
 
-**Related:** `ICompanyInfo` (id, name, slug, imageId), `IBranchInfo` (id, name, slug, imageId?), `IUserInfo` (id, name, email, profilePicture?)
+---
 
-### Configuration
+## Components
+
+### AppLayoutComponent
+
+Root layout component. Use this as the parent route component.
 
 ```typescript
-// app.config.ts
-import { LAYOUT_AUTH_STATE, LAYOUT_AUTH_API } from '@flusys/ng-layout';
-import { AuthLayoutStateAdapter, AuthLayoutApiAdapter } from '@flusys/ng-auth';
+import { AppLayoutComponent } from '@flusys/ng-layout';
 
-providers: [
-  { provide: LAYOUT_AUTH_STATE, useExisting: AuthLayoutStateAdapter },
-  { provide: LAYOUT_AUTH_API, useExisting: AuthLayoutApiAdapter },
-]
+// In routes:
+{ path: '', component: AppLayoutComponent, children: [...] }
 ```
 
-Components inject with `{ optional: true }` for graceful degradation without auth.
+Renders:
+- `AppTopbarComponent` (header)
+- `AppSidebarComponent` (left navigation)
+- `<router-outlet>` (page content)
+- `AppConfiguratorComponent` (floating settings panel)
 
----
+### AppTopbarComponent
 
-## Permission-Based Filtering
+Application header bar with:
+- Logo / app name
+- Menu toggle button (mobile)
+- User profile dropdown (avatar, name, logout)
+- Sign-up link (conditionally shown based on `isSignUpEnabled()`)
+- Notification bell slot (via `LAYOUT_NOTIFICATION_BELL` token)
+- Language selector slot (via `LAYOUT_LANGUAGE_SELECTOR` token)
 
-Menu items and launcher apps are automatically filtered via `permissionLogic`.
+### AppSidebarComponent
 
-### How It Works
+Left navigation panel containing:
+- `AppMenuComponent` (navigation items)
+- `AppCompanyBranchSelectorComponent` (if company selection enabled)
 
-1. Set raw items via `layoutService.setMenu(items)` or `setApps(apps)`
-2. `LayoutService.menu` / `apps` are computed signals that filter via utilities
-3. Uses `evaluateLogicNode()` from ng-shared
+### AppMenuComponent
 
-### Interfaces
+Renders the menu tree from `LAYOUT_MENU` token. Supports:
+- Nested submenus (unlimited depth)
+- Active route highlighting
+- Translation keys via `labelKey`
+- Icons via PrimeIcons
 
-```typescript
-interface IMenuItem {
-  id?: string; label?: string; icon?: string; iconType?: number;
-  routerLink?: string[]; children?: IMenuItem[]; separator?: boolean;
-  permissionLogic?: ILogicNode | null;
-}
+### AppMenuitemComponent
 
-interface ILogicNode {
-  id: string;
-  type: 'group' | 'action' | 'role';
-  operator?: 'AND' | 'OR';     // For 'group'
-  actionId?: string;            // For 'action'
-  roleId?: string;              // For 'role'
-  children?: ILogicNode[];      // For 'group'
-}
-```
+Individual menu item component. Handles:
+- Route navigation
+- Submenu expand/collapse
+- Topbar hover positioning
+- `routerLinkActiveOptions`
 
-### Examples
+### AppCompanyBranchSelectorComponent
 
-```typescript
-// Single action check
-permissionLogic: { id: '1', type: 'action', actionId: 'admin.access' }
-
-// OR - user needs ANY permission
-permissionLogic: {
-  id: '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: 'check', type: 'group', operator: 'AND',
-  children: [
-    { id: '1', type: 'action', actionId: 'admin.access' },
-    { id: '2', type: 'role', roleId: 'superuser-role-id' },
-  ],
-}
-```
+Dropdown selectors for company and branch. Shown in sidebar when `services.auth.features.companySelection` is enabled.
 
-### Filtering Behavior
+### AppConfiguratorComponent
 
-- **Separators** pass through without permission checks
-- **Parent items** with no visible children are hidden
-- **Children** filtered recursively
+Floating right-side panel for live layout customization:
+- Theme picker
+- Color scheme toggle (light/dark/dim)
+- Menu mode selector (static/overlay/topbar)
+- Scale slider
 
 ---
 
-## Pre-defined Themes
+## Configuration Persistence
 
-Custom Material-based themes using `definePreset`:
-
-| Theme | Primary Color | Hover Color |
-|-------|---------------|-------------|
-| `GreenTheme` | `#01712c` | `#119744` |
-| `NavyBlueTheme` | `#3535cd` | `#0707a9` |
+`LayoutPersistenceService` automatically saves and restores layout preferences to `localStorage`:
 
 ```typescript
-import { GreenTheme, NavyBlueTheme } from '@flusys/ng-layout';
+// Automatically persisted keys:
+// - flusys.layout.theme
+// - flusys.layout.colorScheme
+// - flusys.layout.menuMode
+// - flusys.layout.scale
+// - flusys.layout.ripple
 ```
 
----
-
-## Usage Examples
-
-### Basic Setup
+No manual setup required — persistence is active whenever `LayoutService` is injected. To clear persisted settings:
 
 ```typescript
-@Component({
-  imports: [AppLayout],
-  template: `<app-layout><router-outlet /></app-layout>`,
-  host: { '[class.app-dark]': 'layoutService.isDarkTheme()' },
-})
-export class AppComponent {
-  readonly layoutService = inject(LayoutService);
-}
+import { LayoutPersistenceService } from '@flusys/ng-layout';
+
+this.persistenceService.clear();
 ```
 
-### Menu Configuration
+---
 
-**Centralized Config File (v4.0.1):**
+## Integration Tokens
+
+### Auth Integration (from ng-auth)
 
 ```typescript
-// app-menu.config.ts
-import { IMenuItem } from '@flusys/ng-layout';
+import { provideAuthLayoutIntegration } from '@flusys/ng-auth';
 
-export const APP_MENU: IMenuItem[] = [
-  {
-    id: 'dashboard',
-    labelKey: 'menu.dashboard',
-    icon: 'pi pi-home',
-    iconType: 1,
-    routerLink: ['/'],
-  },
-  {
-    id: 'admin',
-    labelKey: 'menu.administration',
-    icon: 'pi pi-cog',
-    iconType: 1,
-    permissionLogic: { id: 'admin', type: 'action', actionId: 'admin.access' },
-    children: [
-      {
-        id: 'users',
-        labelKey: 'menu.users',
-        icon: 'pi pi-users',
-        iconType: 1,
-        routerLink: ['/admin/users'],
-      },
-    ],
-  },
-];
+// app.config.ts providers:
+...provideAuthLayoutIntegration()
+// Provides: LAYOUT_AUTH_STATE, LAYOUT_AUTH_API
 ```
 
-**Benefits:**
-- Centralized menu definition in config file
-- Uses `labelKey` for localization (not hardcoded labels)
-- Easier to maintain and share across multiple layouts
-- Supports nested children and permission logic
-
-**Usage in App:**
+**`LAYOUT_AUTH_STATE`** interface:
 ```typescript
-import { APP_MENU } from './config/app-menu.config.ts';
-import { LayoutService } from '@flusys/ng-layout';
-
-layoutService.setMenu(APP_MENU);
+interface ILayoutAuthState {
+  user: Signal<ICurrentUser | null>;
+  company: Signal<ICompany | null>;
+  branch: Signal<IBranch | null>;
+  isAuthenticated: Signal<boolean>;
+  profilePictureUrl: Signal<string | null>;
+  companyLogoUrl: Signal<string | null>;
+}
 ```
 
-### Profile Setup
-
+**`LAYOUT_AUTH_API`** interface:
 ```typescript
-// After login
-layoutService.setUserProfile({
-  id: 'user-123',
-  name: 'John Doe',
-  email: 'john@example.com',
-  profilePictureUrl: 'https://example.com/avatar.jpg',
-});
-
-layoutService.setCompanyProfile({
-  id: 'company-456',
-  name: 'Acme Corp',
-  slug: 'acme-corp',
-  logoUrl: 'https://example.com/logo.png',
-});
-
-// On logout
-layoutService.setUserProfile(null);
-layoutService.setCompanyProfile(null);
+interface ILayoutAuthApi {
+  logout(): Observable<void>;
+  selectCompany(companyId: string, branchId: string): Observable<void>;
+}
 ```
 
----
-
-## Best Practices
-
-### Signal Patterns
+### Notification Bell Integration (from ng-notification)
 
-Use private writable + public readonly pattern:
 ```typescript
-private readonly _isActive = signal(false);
-readonly isActive = this._isActive.asReadonly();
+import { provideNotificationProviders } from '@flusys/ng-notification';
 
-// Update via private signal
-this._isActive.set(true);
-this._isActive.update(v => !v);
+...provideNotificationProviders()
+// Provides: LAYOUT_NOTIFICATION_BELL
 ```
 
-### Responsive Widths
+### Language Selector Integration (from ng-localization)
 
-| Component | Pattern |
-|-----------|---------|
-| AppConfigurator | `w-[calc(100vw-2rem)] sm:w-72 max-w-72` |
-| AppProfile | `w-[calc(100vw-2rem)] sm:w-auto sm:min-w-[280px] max-w-[320px]` |
-| AppCompanyBranchSelector | `w-[calc(100vw-2rem)] sm:w-auto sm:min-w-[300px] max-w-[360px]` |
-| AppLauncher | `w-[calc(100vw-2rem)] sm:w-auto sm:min-w-[280px] max-w-[320px]` |
-
-### Dark Mode CSS Variables
+```typescript
+import { provideLocalization } from '@flusys/ng-localization';
 
-```css
-background-color: var(--surface-overlay);  /* Panels */
-bg-emphasis                                 /* Hover states */
-text-color / text-muted-color              /* Text */
-border-surface                              /* Borders */
-bg-primary / text-primary-contrast         /* Primary */
+...provideLocalization()
+// Provides: LAYOUT_LANGUAGE_SELECTOR
 ```
 
 ---
 
-## Common Issues
+## Troubleshooting
 
-| Issue | Solution |
-|-------|----------|
-| Menu not showing | Call `layoutService.setMenu([...])` |
-| Auth info missing | Provide `LAYOUT_AUTH_STATE` token |
-| Theme not applying | Add `host: { '[class.app-dark]': 'layoutService.isDarkTheme()' }` |
-| Menu items hidden | Check `permissionLogic` and user permissions |
-| Profile picture missing | Include `profilePictureUrl` in `setUserProfile()` |
-| Company feature missing | Enable `services.auth.enabled: true` and provide both auth tokens |
+**Sidebar doesn't open on mobile**
 
----
+Ensure `AppLayoutComponent` is the parent route component, not just imported as a standalone component in a non-route context.
 
-## API Reference
+**Menu items don't highlight active route**
 
-### Components
+Add `routerLinkActiveOptions: { exact: true }` to leaf menu items and `{ exact: false }` to parent items:
 
-| Component | Selector |
-|-----------|----------|
-| `AppLayout` | `app-layout` |
-| `AppTopbar` | `app-topbar` |
-| `AppSidebar` | `app-sidebar` |
-| `AppMenu` | `app-menu` |
-| `AppMenuitem` | `[app-menuitem]` |
-| `AppFooter` | `app-footer` |
-| `AppProfile` | `app-profile` |
-| `AppCompanyBranchSelector` | `app-company-branch-selector` |
-| `AppLauncher` | `app-launcher` |
-| `AppConfigurator` | `app-configurator` |
-| `AppFloatingConfigurator` | `app-floating-configurator` |
+```typescript
+{
+  labelKey: 'menu.dashboard',
+  routerLink: ['/dashboard'],
+  routerLinkActiveOptions: { exact: true },
+}
+```
 
-### Services
+**Topbar submenus appear behind other elements**
 
-| Service | Description |
-|---------|-------------|
-| `LayoutService` | Signal-based layout state management |
-| `LayoutPersistenceService` | localStorage persistence |
+Set a higher `z-index` on `.topbar-submenu` in your global styles, or ensure no parent has `overflow: hidden`.
 
-### Tokens
+**Theme not changing**
 
-| Token | Interface |
-|-------|-----------|
-| `LAYOUT_AUTH_STATE` | `ILayoutAuthState` |
-| `LAYOUT_AUTH_API` | `ILayoutAuthApi` |
+Check that `LayoutPersistenceService` is provided (it's automatic when `LayoutService` is used). If the theme is cached, call `persistenceService.clear()` once.
 
-### Utilities
+**`No provider for LAYOUT_AUTH_STATE`**
 
-| Function | Description |
-|----------|-------------|
-| `filterMenuByPermissions()` | Filter menu items by permission logic |
-| `filterAppsByPermissions()` | Filter launcher apps by permission logic |
+You must call `provideAuthLayoutIntegration()` in `app.config.ts` after enabling `ng-auth`.
 
 ---
 
-## 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
-
----
+## License
 
-**Last Updated:** 2026-02-25 | **Version:** 3.0.1 | **Angular:** 21
+MIT © FLUSYS