@flusys/ng-layout 6.3.0 → 6.4.0

package/README.md

@@ -1,6 +1,6 @@
 # @flusys/ng-layout
 
-Application shell for the FLUSYS Angular platform — topbar, sidebar, menu, and signal-based layout state management.
+Application shell for the FLUSYS Angular platform — topbar, sidebar, menu, and signal-based layout state management. Ships two interchangeable layout skins (**classic** and **modern**) that share the same services, menu and topbar components.
 
 [![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)
@@ -21,21 +21,21 @@ Use `AppLayout` as the parent route component. All authenticated pages become ch
 
 ```typescript
 // app.routes.ts
-import { Routes } from '@angular/router';
-import { AppLayout } from '@flusys/ng-layout';
+import { Routes } from "@angular/router";
+import { AppLayout } from "@flusys/ng-layout";
 
 export const routes: Routes = [
   {
-    path: '',
+    path: "",
     component: AppLayout,
     children: [
-      { path: 'dashboard', loadComponent: () => import('./pages/dashboard.component') },
-      { path: 'products',  loadComponent: () => import('./pages/product-list.component') },
+      { path: "dashboard", loadComponent: () => import("./pages/dashboard.component") },
+      { path: "products", loadComponent: () => import("./pages/product-list.component") },
     ],
   },
   {
-    path: 'auth',
-    loadChildren: () => import('./pages/auth/auth.routes'),
+    path: "auth",
+    loadChildren: () => import("./pages/auth/auth.routes"),
   },
 ];
 ```
@@ -64,7 +64,146 @@ To push user/company profile into the topbar (done automatically by `ng-auth`'s
 
 ---
 
-## 3. Integration Tokens — Auth, Notifications, Language
+## 3. Layout Skins
+
+`AppLayout` renders the skin selected by `LayoutConfig.layoutTheme`. Both skins share every
+service and topbar component — only the shell markup and styling differ, so switching costs
+nothing but a config value.
+
+| Skin      | Shell                                                                              | Menu modes              |
+| --------- | ---------------------------------------------------------------------------------- | ----------------------- |
+| `classic` | Fixed topbar across the top, sidebar below it, page content in the remaining space | static, overlay, topbar |
+| `modern`  | Gradient canvas, transparent sidebar, page content in an elevated rounded card     | static, overlay         |
+
+Set the default in `APP_CONFIG`:
+
+```typescript
+export const environment: IAppConfig = {
+  layoutConfig: {
+    layoutTheme: "modern", // 'classic' (default) | 'modern'
+    menuMode: "static",
+  },
+  // ...
+};
+```
+
+Users can switch skins at runtime from the theme configurator; the choice is persisted with the
+rest of the layout config unless `isMemorable: false`. Read it back through the service:
+
+```typescript
+readonly theme     = this.layout.layoutTheme;     // Signal<'classic' | 'modern'>
+readonly isModern  = this.layout.isModernLayout;  // Signal<boolean>
+```
+
+`menuMode: 'topbar'` renders a horizontal nav, which only the classic skin provides — the modern
+skin falls back to its static sidebar.
+
+Every skin renders exactly one menu toggle, and `LayoutService.onMenuToggle()` decides what it
+acts on from the current mode and viewport:
+
+| Mode                | What the toggle does                                          |
+| ------------------- | ------------------------------------------------------------- |
+| any mode, mobile    | Opens/closes the sidebar drawer over a mask                   |
+| `static`, desktop   | Collapses/restores the sidebar in place                       |
+| `overlay`, desktop  | Slides the sidebar in/out over the content                    |
+| `topbar`, desktop   | Shows/hides the horizontal nav row (`topbarMenuVisible`)      |
+
+### Source layout
+
+```
+components/
+  app.layout.ts            # skin switcher — the component you route to
+  shared/                  # used by every skin
+    layout-shell.base.ts   # shared open/close, outside-click and body-scroll behaviour
+    app.brand-logo.ts      # logo + company name home link
+    app.menu.ts            # menu tree, configurator, footer
+    top-bar/
+      app.topbar-actions.ts  # the whole trailing action rail (search, theme, widgets)
+  layouts/classic/         # classic shell — bar, brand block, horizontal nav, sidebar
+  layouts/modern/          # modern shell — bar, brand block, page title, sidebar
+
+assets/layout/
+  base/                    # tokens, core, typography, forms, brand, topbar, menu, footer, rtl, utils
+  classic/                 # classic skin styling
+  modern/                  # modern skin styling
+```
+
+A skin owns only the parts that actually differ. The brand block, the topbar action rail and
+the menu tree are one component and one stylesheet each, shared by every skin; `base/_topbar.scss`
+and `base/_menu.scss` hold their structure and read the tokens below, and a skin retunes them by
+overriding a token on its own shell class rather than restating the rules.
+
+Every colour in both skins resolves from the active `@flusys/ng-ui` theme variables, so preset,
+primary, surface and dark-mode changes repaint the shell automatically.
+
+### Preset-driven chrome
+
+A `@flusys/ng-ui` preset (Aura / Lara / Nora) publishes structural tokens alongside its colours,
+and both skins read them — so switching preset restyles the shell, not just the components inside
+it. The classic skin uses them directly; the modern skin clamps each one into its own range with
+`min()` / `max()`, so its card and rows stay softer than a classic sidebar's while a square preset
+still squares them.
+
+| Preset token                        | Classic                            | Modern                                                                  |
+| ----------------------------------- | ---------------------------------- | ----------------------------------------------------------------------- |
+| `--f-card-border-radius`            | components inside the page         | `--layout-modern-radius` — the content card, its topbar and its content  |
+| `--f-menuitem-active-radius`        | active menu row radius             | `--layout-modern-item-radius` — capped at the skin's own `0.625rem`      |
+| `--f-menuitem-active-border-width`  | accent bar on the active row       | same accent bar, drawn in the row's own ink                             |
+| `--f-topbar-border-width`           | topbar bottom border               | `--layout-modern-topbar-border-width` — floored at a hairline           |
+| `--f-topbar-shadow`                 | topbar shadow                      | topbar shadow                                                            |
+| `--f-sidebar-border-width`          | sidebar trailing border            | `--layout-modern-divider-width` — the sidebar footer's divider          |
+| `--f-sidebar-radius` / `-shadow`    | sidebar corner and shadow          | — (this skin's sidebar is transparent on the canvas)                    |
+| `--f-border-radius-lg`              | components inside the page         | `--layout-modern-control-radius` — the drawer's collapse button         |
+
+Every length a preset publishes carries a unit (`0px`, never `0`), because a bare `0` is a
+`<number>` inside `min()` / `max()` / `calc()` and would invalidate the whole expression.
+
+A neutral primary — the `noir` swatch, and Nora's signature colour — resolves the primary ramp to
+the surface greys, which would leave the modern skin's canvas too pale for the white ink on top.
+`applyPrimaryPalette` marks the root with `f-primary-noir` for exactly this case (CSS cannot branch
+on a custom property's value), and the skin anchors its canvas in the dark end of the ramp instead.
+
+### Shell geometry tokens
+
+Both skins size themselves from one set of CSS variables declared in
+`assets/layout/base/variables/_common.scss` — nothing hardcodes a width, height or z-index, so
+overriding a token in your own stylesheet resizes the shell in both skins at once.
+
+| Token                          | Default                  | Used for                                                                                                   |
+| ------------------------------ | ------------------------ | ---------------------------------------------------------------------------------------------------------- |
+| `--layout-viewport-height`     | `100dvh`                 | Full-height shells — a fixed sidebar always fills exactly 100%                                             |
+| `--layout-topbar-height`       | `4rem`                   | Topbar height, sidebar offset, content padding, dropdown top                                               |
+| `--layout-topbar-inline-padding` | `--layout-content-padding` | Topbar gutters, and where the compact widget menu hangs from                                             |
+| `--layout-topbar-actions-gap`  | `1rem`                   | Space between the action rail's groups                                                                     |
+| `--layout-topbar-group-gap`    | `1rem`                   | Space inside a group (theme controls, widget menu)                                                         |
+| `--layout-topbar-action-size`  | `2.5rem`                 | Diameter of a round topbar action button                                                                   |
+| `--layout-topbar-action-icon-size` | `1.25rem`            | Icon size inside those buttons                                                                             |
+| `--layout-sidebar-width`       | `19rem`                  | Sidebar width and the content margin that clears it                                                        |
+| `--layout-content-padding`     | `2rem`                   | Page gutters                                                                                               |
+| `--layout-shell-topbar-bottom` | `--layout-topbar-height` | Where the topbar ends — shared widgets pin full-width overlays here (the modern skin adds its card margin) |
+| `--layout-content-viewport-height` | `viewport − topbar-bottom` | The space left under the topbar — the classic sidebar, pinned below the topbar, fills exactly this |
+| `--layout-topbar-z`            | `997`                    | Stacking order: topbar under mask under sidebar                                                            |
+| `--layout-mask-z`              | `998`                    |                                                                                                            |
+| `--layout-sidebar-z`           | `999`                    |                                                                                                            |
+
+```css
+:root {
+  --layout-sidebar-width: 18rem; /* narrower sidebar, everything else follows */
+}
+```
+
+The modern skin overrides the topbar tokens on `.layout-modern` (a taller bar, tighter gaps,
+smaller icons) and adds its own `--layout-modern-*` tokens for the pieces that have no shared
+equivalent — gradient canvas, card radius, its narrower sidebar. Everything else it inherits.
+
+Both skins' shells are written with CSS logical properties, so RTL needs no mirrored copy of the
+layout rules; `classic/_rtl.scss` and `modern/_rtl.scss` only flip the drawer `transform`, which
+has no logical equivalent, and `base/_rtl.scss` carries the component-library corrections that
+are not tied to a skin.
+
+---
+
+## 4. Integration Tokens — Auth, Notifications, Language
 
 Connect feature packages to the layout via injection tokens. Register them in `app.config.ts`.
 
@@ -86,10 +225,10 @@ The layout reads these tokens to render topbar slots without directly importing
 
 ---
 
-## 4. Clear Persisted Layout
+## 5. Clear Persisted Layout
 
 ```typescript
-import { LayoutPersistenceService } from '@flusys/ng-layout';
+import { LayoutPersistenceService } from "@flusys/ng-layout";
 
 inject(LayoutPersistenceService).clear(); // removes flusys.layout.config from localStorage
 ```

package/assets/layout/base/_brand.scss

@@ -0,0 +1,44 @@
+@use 'mixins' as *;
+
+// Shared <app-brand-logo> markup. The host is `display: contents`, so the anchor
+// below is the flex item of whichever bar renders it. Every skin gets the same
+// treatment — a full-size mark next to a slightly oversized name, which still reads
+// as the brand on its own when no logo is configured.
+.layout-brand-logo {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
+  min-width: 0;
+  flex-shrink: 0;
+  color: var(--text-color);
+  border-radius: var(--content-border-radius);
+  font-size: 1.5rem;
+  font-weight: 500;
+
+  .logo-image {
+    height: 2.5rem;
+    width: auto;
+    max-width: 3rem;
+    object-fit: contain;
+    flex-shrink: 0;
+  }
+
+  // The name is the first thing to give up room on a narrow bar; skins that keep a
+  // full-width brand row (the modern drawer) reveal it again.
+  span {
+    display: none;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  &:focus-visible {
+    @include focused();
+  }
+}
+
+@media (min-width: 640px) {
+  .layout-brand-logo span {
+    display: inline;
+  }
+}

package/assets/layout/{_core.scss → base/_core.scss}

@@ -20,7 +20,14 @@ a {
 }
 
 .layout-wrapper {
-    min-height: 100vh;
+    min-height: var(--layout-viewport-height);
+}
+
+/* Set by LayoutShellBase while a mobile drawer is open — shared by every skin. */
+@media (max-width: 991px) {
+    .blocked-scroll {
+        overflow: hidden;
+    }
 }
 
 @keyframes scalein {

package/assets/layout/{_footer.scss → base/_footer.scss}

@@ -4,7 +4,7 @@
     justify-content: center;
     padding: 1rem 0;
     gap: 0.5rem;
-    border-top: 1px solid var(--surface-border);
+    border-top: var(--f-border-width, 1px) solid var(--surface-border);
 
     .logo-image {
       height: 2rem;

package/assets/layout/{_forms.scss → base/_forms.scss}

@@ -5,12 +5,12 @@
 /* Native select element */
 select.ui-select {
   width: 100%;
-  padding: 0.5rem 2.5rem 0.5rem 0.75rem;
+  padding: var(--f-field-padding-y, 0.5rem) 2.5rem var(--f-field-padding-y, 0.5rem) var(--f-field-padding-x, 0.75rem);
   font-size: 1rem;
   font-family: inherit;
   background: var(--f-form-field-background, #ffffff);
-  border: 1px solid var(--f-form-field-border-color, #d1d5db);
-  border-radius: var(--f-border-radius-md, 6px);
+  border: var(--f-border-width, 1px) solid var(--f-form-field-border-color, #d1d5db);
+  border-radius: var(--f-field-border-radius, 6px);
   color: var(--f-text-color, #374151);
   transition: border-color 0.2s, box-shadow 0.2s;
   appearance: none;

package/assets/layout/base/_menu.scss

@@ -0,0 +1,52 @@
+// Structure of the shared <app-menu> markup — list reset and row layout. Every skin
+// renders this same tree, so only the look (colours, padding, indentation) belongs in
+// a skin file.
+// Written with logical properties throughout, which is what keeps the menu correct
+// in RTL without a mirrored copy of these rules.
+.layout-menu {
+  margin: 0;
+  padding: 0;
+  list-style-type: none;
+
+  a {
+    user-select: none;
+  }
+
+  ul {
+    margin: 0;
+    padding: 0;
+    list-style-type: none;
+
+    a {
+      display: flex;
+      align-items: center;
+      position: relative;
+      outline: 0 none;
+      color: var(--text-color);
+      cursor: pointer;
+      transition:
+        background-color var(--element-transition-duration),
+        box-shadow var(--element-transition-duration);
+
+      .layout-menuitem-icon {
+        margin-inline-end: 0.5rem;
+      }
+
+      .layout-submenu-toggler {
+        font-size: 75%;
+        margin-inline-start: auto;
+        transition: transform var(--element-transition-duration);
+      }
+    }
+  }
+}
+
+// An expanded submenu flips its chevron. Shared by every skin whose menu is a
+// vertical list — a new skin joins the selector list. The classic horizontal nav is
+// deliberately left out: it opens submenus on hover and its chevron points sideways.
+.layout-sidebar .layout-menu,
+.layout-modern-sidebar .layout-menu {
+  li.active-menuitem > a .layout-submenu-toggler {
+    transform: rotate(-180deg);
+  }
+}

package/assets/layout/base/_rtl.scss

@@ -0,0 +1,230 @@
+// RTL corrections that are not tied to a layout skin — component library widgets and
+// the utility classes pages use directly. Anything the shell itself needs is written
+// with logical properties instead, so it mirrors without a rule here.
+html[dir='rtl'] {
+  // Flip navigation arrows
+  .pi-chevron-left::before {
+    content: '\e901'; // pi-chevron-right icon code
+  }
+
+  .pi-chevron-right::before {
+    content: '\e900'; // pi-chevron-left icon code
+  }
+
+  // Calendar grid direction
+  .calendar-month .grid,
+  .calendar-week .grid,
+  .calendar-day {
+    direction: rtl;
+  }
+
+  // Calendar day - time column should align left in RTL (visually on right side)
+  .calendar-day .pr-2 {
+    padding-right: 0 !important;
+    padding-left: 0.5rem !important;
+  }
+
+  .calendar-day .border-r {
+    border-right: none !important;
+    border-left: var(--f-border-width, 1px) solid var(--surface-border) !important;
+  }
+
+  // Form labels and inputs
+  .p-float-label > label {
+    left: auto;
+    right: 0.75rem;
+  }
+
+  // Checkbox/radio alignment
+  .p-checkbox,
+  .p-radiobutton {
+    margin-right: 0;
+    margin-left: 0.5rem;
+  }
+
+  // Button icons
+  .p-button-icon-left {
+    margin-right: 0;
+    margin-left: 0.5rem;
+  }
+
+  .p-button-icon-right {
+    margin-left: 0;
+    margin-right: 0.5rem;
+  }
+
+  // Table - full RTL support
+  .p-datatable {
+    direction: rtl;
+
+    .p-datatable-thead > tr > th,
+    .p-datatable-tbody > tr > td {
+      text-align: right;
+    }
+
+    // Actions column (usually last) should be left-aligned
+    .p-datatable-thead > tr > th:last-child,
+    .p-datatable-tbody > tr > td:last-child {
+      text-align: left;
+    }
+
+    // Paginator - rotate navigation icons
+    .p-paginator {
+      .p-paginator-first,
+      .p-paginator-prev,
+      .p-paginator-next,
+      .p-paginator-last {
+        transform: rotate(180deg);
+      }
+    }
+  }
+
+  // Toast positioning
+  .p-toast {
+    &.p-toast-top-right,
+    &.p-toast-bottom-right {
+      right: auto;
+      left: 20px;
+    }
+
+    &.p-toast-top-left,
+    &.p-toast-bottom-left {
+      left: auto;
+      right: 20px;
+    }
+  }
+
+  // Breadcrumb separator - rotate arrow
+  .p-breadcrumb .p-menuitem-separator {
+    transform: rotate(180deg);
+  }
+
+  // Steps
+  .p-steps .p-steps-item::before {
+    left: auto;
+    right: 50%;
+  }
+
+  // Dialog - swap margins only
+  .p-dialog .p-dialog-header-icons {
+    margin-left: 0;
+    margin-right: auto;
+  }
+
+  // Sidebar panel
+  .p-sidebar-left {
+    left: auto !important;
+    right: 0 !important;
+  }
+
+  .p-sidebar-right {
+    right: auto !important;
+    left: 0 !important;
+  }
+
+  // Card actions - swap margin
+  .card-actions {
+    margin-left: 0;
+    margin-right: auto;
+  }
+
+  // Tag/Badge positioning
+  .p-tag,
+  .p-badge {
+    margin-left: 0;
+    margin-right: 0.5rem;
+  }
+
+  // Menu items with icons - swap icon margin for RTL
+  .p-menuitem-link .p-menuitem-icon {
+    margin-right: 0;
+    margin-left: 0.5rem;
+  }
+
+  // Accordion - swap toggle icon margin
+  .p-accordion .p-accordion-toggle-icon {
+    margin-left: 0;
+    margin-right: auto;
+  }
+
+  // Tree/TreeTable - swap toggler margin
+  .p-tree .p-tree-toggler,
+  .p-treetable .p-treetable-toggler {
+    margin-right: 0;
+    margin-left: 0.5rem;
+  }
+
+  // Text alignment
+  .text-left {
+    text-align: right !important;
+  }
+
+  .text-right {
+    text-align: left !important;
+  }
+
+  // Border utilities
+  .border-l {
+    border-left: none !important;
+    border-right: var(--f-border-width, 1px) solid var(--surface-border) !important;
+  }
+
+  .border-r {
+    border-right: none !important;
+    border-left: var(--f-border-width, 1px) solid var(--surface-border) !important;
+  }
+
+  // Margin/padding utilities
+  .ml-auto {
+    margin-left: 0 !important;
+    margin-right: auto !important;
+  }
+
+  .mr-auto {
+    margin-right: 0 !important;
+    margin-left: auto !important;
+  }
+
+  .ml-2 {
+    margin-left: 0 !important;
+    margin-right: 0.5rem !important;
+  }
+
+  .mr-2 {
+    margin-right: 0 !important;
+    margin-left: 0.5rem !important;
+  }
+
+  .pl-2 {
+    padding-left: 0 !important;
+    padding-right: 0.5rem !important;
+  }
+
+  .pr-2 {
+    padding-right: 0 !important;
+    padding-left: 0.5rem !important;
+  }
+
+  // Justify content
+  .justify-start {
+    justify-content: flex-end !important;
+  }
+
+  .justify-end {
+    justify-content: flex-start !important;
+  }
+
+  // Items alignment in flex
+  .items-start {
+    align-items: flex-start;
+  }
+
+  // Scroll container
+  .overflow-x-auto {
+    direction: rtl;
+
+    > * {
+      direction: rtl;
+    }
+  }
+}