@flusys/ng-layout 4.1.1 → 5.0.0

package/README.md

@@ -1,76 +1,9 @@
 # @flusys/ng-layout
 
-> Application shell and layout system for the FLUSYS Angular platform — topbar, sidebar, menu, configurator, and layout state management.
+Application shell for the FLUSYS Angular platform — topbar, sidebar, menu, and signal-based layout state management.
 
 [![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)
-
----
-
-## 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)
-
----
-
-## Overview
-
-`@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.
-
-The layout integrates with auth, notification, and localization packages through injection token interfaces, maintaining clean package independence via the Provider Interface Pattern.
-
----
-
-## Features
-
-- ✅ 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
-
----
-
-## Compatibility
-
-| Package | Version |
-|---------|---------|
-| Angular | 21+ |
-| @flusys/ng-core | 4.x |
-| @flusys/ng-shared | 4.x |
-| PrimeNG | 18+ |
-| Tailwind CSS | 3+ |
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ---
 
@@ -82,28 +15,22 @@ npm install @flusys/ng-layout @flusys/ng-core @flusys/ng-shared
 
 ---
 
-## Quick Start
+## 1. Set Up the Layout Route
 
-### 1. Set Up App Layout Route
+Use `AppLayout` as the parent route component. All authenticated pages become children.
 
 ```typescript
 // app.routes.ts
 import { Routes } from '@angular/router';
-import { AppLayoutComponent } from '@flusys/ng-layout';
+import { AppLayout } from '@flusys/ng-layout';
 
 export const routes: Routes = [
   {
     path: '',
-    component: AppLayoutComponent,
+    component: AppLayout,
     children: [
-      {
-        path: 'dashboard',
-        loadComponent: () => import('./pages/dashboard/dashboard.component'),
-      },
-      {
-        path: 'products',
-        loadComponent: () => import('./pages/products/product-list.component'),
-      },
+      { path: 'dashboard', loadComponent: () => import('./pages/dashboard.component') },
+      { path: 'products',  loadComponent: () => import('./pages/product-list.component') },
     ],
   },
   {
@@ -113,406 +40,62 @@ export const routes: Routes = [
 ];
 ```
 
-### 2. Define Menu Configuration
-
-```typescript
-// app-menu.config.ts
-import { IMenuItem } from '@flusys/ng-layout';
-
-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'],
-      },
-    ],
-  },
-];
-```
-
-### 3. Provide Layout Configuration
-
-```typescript
-// 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',
-      },
-    },
-  ],
-};
-```
-
----
-
-## Layout Configuration
-
-### LayoutConfig
-
-```typescript
-interface LayoutConfig {
-  /** Menu display mode */
-  menuMode: 'static' | 'overlay' | 'topbar';
-
-  /** PrimeNG theme name */
-  theme: string;
-
-  /** Color scheme */
-  colorScheme: 'light' | 'dark' | 'dim';
-
-  /** Ripple effect */
-  ripple?: boolean;
-
-  /** Scale factor (12-16) */
-  scale?: number;
-
-  /** Menu theme */
-  menuTheme?: 'light' | 'dark' | 'colored';
-
-  /** Card border style */
-  inputStyle?: 'outlined' | 'filled';
-}
-```
-
-### Menu Modes
-
-#### Static Mode (Default)
-
-Sidebar is always visible on desktop. Collapses to icons on tablet.
-
-```typescript
-{ provide: LAYOUT_CONFIG, useValue: { menuMode: 'static' } }
-```
-
-#### Overlay Mode
-
-Sidebar slides over content. Click outside to close.
-
-```typescript
-{ provide: LAYOUT_CONFIG, useValue: { menuMode: 'overlay' } }
-```
-
-#### Topbar Mode (v4.0.1+)
-
-Desktop renders horizontal navigation bar. Mobile falls back to vertical sidebar.
-
-```typescript
-{ provide: LAYOUT_CONFIG, useValue: { menuMode: 'topbar' } }
-```
-
-Submenu items appear on hover in topbar mode with automatic positioning.
-
-### Themes & Colors
-
-Built-in themes (PrimeNG):
-
-| 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 |
-
----
-
-## Injection Tokens
-
-| 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) |
-
 ---
 
-## LayoutService
-
-Central signal-based service for layout state management.
+## 2. LayoutService — Reading and Updating Layout State
 
 ```typescript
 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();
-  }
+  private readonly layout = inject(LayoutService);
 
-  setTheme(theme: string): void {
-    this.layoutService.setTheme(theme);
-  }
+  // 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
 
-  setMenuMode(mode: 'static' | 'overlay' | 'topbar'): void {
-    this.layoutService.setMenuMode(mode);
-  }
 }
 ```
 
-**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 |
+To push user/company profile into the topbar (done automatically by `ng-auth`'s bridge service):
 
 ---
 
-## LayoutState
+## 3. Integration Tokens — Auth, Notifications, Language
 
-Reactive state object managed by `LayoutService`:
+Connect feature packages to the layout via injection tokens. Register them in `app.config.ts`.
 
 ```typescript
-interface LayoutState {
-  /** Sidebar open on mobile */
-  staticMenuMobileActive: boolean;
-
-  /** Overlay sidebar open */
-  overlayMenuActive: boolean;
-
-  /** Desktop sidebar collapsed */
-  staticMenuDesktopInactive: boolean;
-
-  /** Right-click menu visible */
-  menuHoverActive: boolean;
-
-  /** Config panel open */
-  configSidebarVisible: boolean;
-
-  /** Topbar nav visible (topbar mode) */
-  topbarMenuVisible: boolean;
-}
-```
-
----
-
-## Components
-
-### AppLayoutComponent
-
-Root layout component. Use this as the parent route component.
-
-```typescript
-import { AppLayoutComponent } from '@flusys/ng-layout';
+import { provideAuthLayoutIntegration } from '@flusys/ng-auth';
+import { provideNotificationProviders }  from '@flusys/ng-notification';
+import { provideLocalization }           from '@flusys/ng-localization';
 
-// In routes:
-{ path: '', component: AppLayoutComponent, children: [...] }
+export const appConfig: ApplicationConfig = {
+  providers: [
+    ...provideAuthLayoutIntegration(), // topbar user profile + logout
+    ...provideNotificationProviders(), // topbar notification bell
+    ...provideLocalization({ ... }),   // topbar language selector
+  ],
+};
 ```
 
-Renders:
-- `AppTopbarComponent` (header)
-- `AppSidebarComponent` (left navigation)
-- `<router-outlet>` (page content)
-- `AppConfiguratorComponent` (floating settings panel)
-
-### AppTopbarComponent
-
-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)
-
-### AppSidebarComponent
-
-Left navigation panel containing:
-- `AppMenuComponent` (navigation items)
-- `AppCompanyBranchSelectorComponent` (if company selection enabled)
-
-### AppMenuComponent
-
-Renders the menu tree from `LAYOUT_MENU` token. Supports:
-- Nested submenus (unlimited depth)
-- Active route highlighting
-- Translation keys via `labelKey`
-- Icons via PrimeIcons
-
-### AppMenuitemComponent
-
-Individual menu item component. Handles:
-- Route navigation
-- Submenu expand/collapse
-- Topbar hover positioning
-- `routerLinkActiveOptions`
-
-### AppCompanyBranchSelectorComponent
-
-Dropdown selectors for company and branch. Shown in sidebar when `services.auth.features.companySelection` is enabled.
-
-### AppConfiguratorComponent
-
-Floating right-side panel for live layout customization:
-- Theme picker
-- Color scheme toggle (light/dark/dim)
-- Menu mode selector (static/overlay/topbar)
-- Scale slider
+The layout reads these tokens to render topbar slots without directly importing feature packages.
 
 ---
 
-## Configuration Persistence
-
-`LayoutPersistenceService` automatically saves and restores layout preferences to `localStorage`:
-
-```typescript
-// Automatically persisted keys:
-// - flusys.layout.theme
-// - flusys.layout.colorScheme
-// - flusys.layout.menuMode
-// - flusys.layout.scale
-// - flusys.layout.ripple
-```
-
-No manual setup required — persistence is active whenever `LayoutService` is injected. To clear persisted settings:
+## 4. Clear Persisted Layout
 
 ```typescript
 import { LayoutPersistenceService } from '@flusys/ng-layout';
 
-this.persistenceService.clear();
+inject(LayoutPersistenceService).clear(); // removes flusys.layout.config from localStorage
 ```
 
 ---
 
-## Integration Tokens
-
-### Auth Integration (from ng-auth)
-
-```typescript
-import { provideAuthLayoutIntegration } from '@flusys/ng-auth';
-
-// app.config.ts providers:
-...provideAuthLayoutIntegration()
-// Provides: LAYOUT_AUTH_STATE, LAYOUT_AUTH_API
-```
-
-**`LAYOUT_AUTH_STATE`** interface:
-```typescript
-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>;
-}
-```
-
-**`LAYOUT_AUTH_API`** interface:
-```typescript
-interface ILayoutAuthApi {
-  logout(): Observable<void>;
-  selectCompany(companyId: string, branchId: string): Observable<void>;
-}
-```
-
-### Notification Bell Integration (from ng-notification)
-
-```typescript
-import { provideNotificationProviders } from '@flusys/ng-notification';
-
-...provideNotificationProviders()
-// Provides: LAYOUT_NOTIFICATION_BELL
-```
-
-### Language Selector Integration (from ng-localization)
-
-```typescript
-import { provideLocalization } from '@flusys/ng-localization';
-
-...provideLocalization()
-// Provides: LAYOUT_LANGUAGE_SELECTOR
-```
-
----
-
-## Troubleshooting
-
-**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.
-
-**Menu items don't highlight active route**
-
-Add `routerLinkActiveOptions: { exact: true }` to leaf menu items and `{ exact: false }` to parent items:
-
-```typescript
-{
-  labelKey: 'menu.dashboard',
-  routerLink: ['/dashboard'],
-  routerLinkActiveOptions: { exact: true },
-}
-```
-
-**Topbar submenus appear behind other elements**
-
-Set a higher `z-index` on `.topbar-submenu` in your global styles, or ensure no parent has `overflow: hidden`.
-
-**Theme not changing**
-
-Check that `LayoutPersistenceService` is provided (it's automatic when `LayoutService` is used). If the theme is cached, call `persistenceService.clear()` once.
-
-**`No provider for LAYOUT_AUTH_STATE`**
-
-You must call `provideAuthLayoutIntegration()` in `app.config.ts` after enabling `ng-auth`.
-
----
-
 ## License
 
 MIT © FLUSYS

package/assets/layout/_topbar_nav.scss

@@ -214,7 +214,7 @@ $submenu-icon-margin: 0.5rem;
   flex: 1 1 auto;
   padding: 0 1rem;
   overflow-x: auto;
-  overflow-y: visible;
+  overflow-y: hidden;
   -webkit-overflow-scrolling: touch;
   scrollbar-width: none;