@pecb-ui/components 1.1.12 → 1.1.13

package/README.md

@@ -416,6 +416,327 @@ pecb-course-content-panel {
 }
 ```
 
+### App Sidebar Component
+
+The **application shell rail** from the PECB Central Hub: product switcher, navigation tree with
+expandable branches, collapse-to-icons (with tooltips and flyouts), and the account block with its
+dropdown — Profile, Billing, a Language submenu, a Switch Roles submenu, Customer Service and
+Log Out.
+
+It is entirely data-driven: describe the navigation, listen for the events. It is a **new**
+component and does not touch the existing `pecb-sidebar`.
+
+```ts
+import { AppSidebarComponent } from "@pecb-ui/components";
+// or: import { AppSidebarComponent } from '@pecb-ui/components/navigation';
+```
+
+The host is a plain flex child that owns its own width, so the app shell is a flex row with no
+margins to keep in sync:
+
+```html
+<div style="display:flex; min-height:100vh">
+  <pecb-app-sidebar [logoSrc]="logo" [collapsedLogoSrc]="mark" [products]="products" [(activeProductId)]="productId" [items]="nav" [(activeItemId)]="activeId" [user]="user" [menu]="accountMenu" [(collapsed)]="collapsed" [(mobileOpen)]="drawerOpen" storageKey="pecb-sidebar" (navigate)="go($event)" (productChange)="switchProduct($event)" (menuItemClick)="onAccountAction($event)" (menuOptionChange)="onLanguageOrRole($event)" />
+  <main style="flex:1; min-width:0"><!-- page --></main>
+</div>
+```
+
+**Navigation belongs to the product.** Give each switcher entry its own `items` (or `groups`) and
+switching product swaps the entire tab set — the rail lands on that product's first tab and emits
+`navigate` for it. A hub product that is really just a launcher declares one Dashboard entry and
+shows nothing else; the real tabs appear only once the user switches into a product. Turn the
+landing off with `[autoSelectFirstItem]="false"`.
+
+```ts
+products: AppSidebarProduct[] = [
+  {
+    id: "hub",
+    label: "Central Hub",
+    description: "All PECB products",
+    featured: true,
+    items: [{ id: "hub-dashboard", label: "Dashboard", icon: "<svg …>" }],
+  },
+  {
+    id: "courses",
+    label: "Professional Courses",
+    section: "PECB Products",
+    items: [
+      { id: "pc-dashboard", label: "Dashboard" },
+      { id: "pc-browse", label: "Browse Courses" },
+      { id: "pc-exams", label: "Exams", badge: 2, children: [...] },
+    ],
+  },
+  { id: "executive", label: "Executive Education", section: "PECB Products", disabled: true, hint: "Coming soon" },
+];
+```
+
+A single-product shell skips all that and feeds the rail's own `items` / `groups` inputs; the
+switcher then only changes which application you are in. Navigation nests up to three levels either
+way — branches expand in place while the rail is expanded, and inside the flyout while it is
+collapsed:
+
+```ts
+const nav: AppSidebarNavItem[] = [
+  { id: "hub", label: "Central Hub", icon: "<svg …>" },
+  { id: "certs", label: "Certifications", icon: "<svg …>", badge: 3 },
+  {
+    id: "courses",
+    label: "Professional Courses",
+    icon: "<svg …>",
+    children: [
+      { id: "courses-mine", label: "My courses" },
+      {
+        id: "courses-catalog",
+        label: "Course catalog",
+        children: [
+          { id: "catalog-iso", label: "ISO standards" },
+          { id: "catalog-cyber", label: "Cybersecurity" },
+        ],
+      },
+    ],
+  },
+];
+```
+
+**The profile block is the role select.** It shows the user's name with their role beneath it, and
+opens the account dropdown. Mark a submenu `reflectsRole` — `DEFAULT_APP_SIDEBAR_MENU` already does
+on Switch Roles — and picking a role updates that line immediately, with no round-trip through the
+host application. `user.role` is the fallback when nothing reflects it.
+
+**The account dropdown ships ready-made.** `DEFAULT_APP_SIDEBAR_MENU` is the PECB menu in the order
+the Central Hub renders it — Profile, Switch Roles, Language, Billing & Payments, Customer Service
+and Log Out — icons included. Pass it straight in, or spread it to adjust a single entry:
+
+```ts
+import { DEFAULT_APP_SIDEBAR_MENU } from "@pecb-ui/components";
+
+accountMenu = DEFAULT_APP_SIDEBAR_MENU.map((item) => (item.id === "profile" ? { ...item, routerLink: "/me" } : item));
+```
+
+`DEFAULT_APP_SIDEBAR_LANGUAGES`, `DEFAULT_APP_SIDEBAR_ROLES` and `APP_SIDEBAR_MENU_ICONS` are
+exported alongside it for building your own variant.
+
+**Angular Router.** Any entry — navigation item, product or menu row — can carry `routerLink`
+(plus `queryParams`, `fragment`, `routerLinkActiveExact`) instead of `href`. Those entries render
+as router anchors and highlight through `routerLinkActive`, so the rail follows the URL including
+back/forward and deep links. `@angular/router` is an **optional** peer dependency: the router
+directives are only instantiated for entries that actually use them, so router-free applications
+are unaffected.
+
+```ts
+const nav: AppSidebarNavItem[] = [
+  { id: "hub", label: "Central Hub", routerLink: "/", routerLinkActiveExact: true },
+  { id: "course", label: "Course", routerLink: ["/courses", id], fragment: "top" },
+];
+```
+
+**Branding.** `logo` / `collapsedLogo` take inline SVG markup and `logoSrc` / `collapsedLogoSrc`
+take image URLs; markup wins when both are supplied. The expanded wordmark is pinned to
+`--pecb-app-sidebar-logo-height` (34px) and keeps its aspect ratio, so an `<img>` and an inline
+`<svg>` land on exactly the same box; the collapsed mark keeps its natural size, capped to the rail.
+
+**Localisation.** Nothing the shell renders is hard-coded. Every string it produces itself comes
+from the `labels` input, and the ready-made account menu is built per locale — so a language switch
+is a lookup, not a translation project. Six locales ship: **en · fr · es · de · ja · ko**.
+
+```ts
+import {
+  APP_SIDEBAR_TRANSLATIONS,
+  APP_HEADER_TRANSLATIONS,
+  appSidebarMenu,
+  type AppShellLocale,
+} from "@pecb-ui/components";
+
+locale = signal<AppShellLocale>("en");
+sidebarLabels = computed(() => APP_SIDEBAR_TRANSLATIONS[this.locale()]);
+headerLabels = computed(() => APP_HEADER_TRANSLATIONS[this.locale()]);
+menu = computed(() => appSidebarMenu(this.locale()));
+
+onOption(change: AppSidebarMenuOptionChange) {
+  // The language option ids *are* the locale keys.
+  if (change.item.id === "language") this.locale.set(change.option.id as AppShellLocale);
+}
+```
+
+`appSidebarLabels('fr-CA')` / `appHeaderLabels('es-MX')` accept region tags and fall back to English
+for anything unrecognised. For a language not shipped, pass your own object — `labels` takes a
+**partial** bundle merged over the defaults, so overriding one word does not mean restating the rest:
+
+```html
+<pecb-app-sidebar [labels]="{ collapse: 'Sluit zijbalk' }" />
+```
+
+Language names in the picker stay endonyms ("Deutsch", "日本語") — a language is named in itself,
+whatever the current locale. `DEFAULT_APP_SIDEBAR_MENU` and `DEFAULT_APP_SIDEBAR_ROLES` remain
+available as the English builds of `appSidebarMenu()` / `appSidebarRoles()`.
+
+**Stacking.** The rail defaults to `z-index: 30`, above the header's `20`, because the collapse
+handle overhangs the rail's right border by 13px straight across the header — it has to stay
+visible and clickable there. Retune both with `--pecb-app-sidebar-z` / `--pecb-app-header-z`, and
+keep the rail the higher of the two.
+
+**Inputs** — `logo`, `collapsedLogo`, `logoSrc`, `collapsedLogoSrc`, `logoHref`, `products`, `activeProductId` (two-way),
+`items`, `groups`, `activeItemId` (two-way), `user`, `menu`, `collapsible`, `collapsed` (two-way),
+`mobileOpen` (two-way), `mobileBreakpoint`, `width`, `collapsedWidth`, `autoCollapseSiblings`,
+`autoSelectFirstItem`, `showTooltips`, `storageKey`, `labels`.
+
+**Outputs** — `navigate`, `productChange`, `menuItemClick`, `menuOptionChange`, `userClick`.
+
+**Slots** — `[appSidebarHeader]`, `[appSidebarPromo]`, `[appSidebarFooter]`; all three are hidden
+while the rail is collapsed.
+
+**Responsive.** At or below `mobileBreakpoint` (880px by default) the rail becomes an off-canvas
+drawer with a scrim, a focus trap and body scroll-lock; the closed drawer is `inert`, so it is
+skipped by tab order and screen readers. Bind `mobileOpen` to a hamburger, or read the rail's own
+state to show one only when it is needed:
+
+```html
+<pecb-app-sidebar #rail … /> <button *ngIf="rail.isMobile()" (click)="rail.toggleMobile()">☰</button>
+```
+
+**Collapsed rail.** Labels give way to icons, hovering an icon shows a tooltip and a branch opens as
+a flyout beside the rail. Pass `storageKey` to remember the state in `localStorage`.
+
+**Performance.** `OnPush` with signals throughout, sanitised icon markup cached per string, and the
+menus, flyouts and tooltips share a handful of CDK overlays that only exist while open — so they are
+never clipped by the scroll container and always reposition inside the viewport.
+
+**Theming:**
+
+```css
+pecb-app-sidebar {
+  --pecb-app-sidebar-width: 270px; /* expanded rail width      */
+  --pecb-app-sidebar-collapsed-width: 84px; /* collapsed rail width     */
+  --pecb-app-sidebar-height: 100dvh; /* set 100% to embed it     */
+  --pecb-app-sidebar-logo-height: 34px; /* wordmark height          */
+  --pecb-app-sidebar-bg: #ffffff; /* surface                  */
+  --pecb-app-sidebar-border: #ececec; /* divider colour           */
+  --pecb-app-sidebar-active-bg: #212427; /* active item background   */
+  --pecb-app-sidebar-active-fg: #ffffff; /* active item foreground   */
+  --pecb-app-sidebar-accent: #a11e29; /* brand accent             */
+  --pecb-app-sidebar-z: 30; /* drawer stacking order    */
+}
+```
+
+### App Header Component
+
+The **application shell header** from the Central Hub — the bar above the page, beside
+`pecb-app-sidebar`. Page title, an optional status chip, a cluster of icon actions with corner
+badges, and the notification bell with its dropdown: unread tint, coloured icon tiles, a
+"view all" footer and an empty state.
+
+```ts
+import { AppHeaderComponent } from "@pecb-ui/components";
+```
+
+The two components pair without either knowing about the other — bind the hamburger to the rail's
+own drawer state, so they can never disagree:
+
+```html
+<div style="display:flex; min-height:100vh">
+  <pecb-app-sidebar #rail [items]="nav" [(mobileOpen)]="drawerOpen" />
+  <div style="flex:1; min-width:0">
+    <pecb-app-header heading="Central Hub" [chip]="{ label: 'Member' }" [actions]="actions" [notifications]="notifications" [showMenuButton]="rail.isMobile()" (menuClick)="rail.toggleMobile()" (actionClick)="onAction($event)" (notificationClick)="open($event)" (viewAllNotifications)="goToInbox()" />
+    <main><!-- page --></main>
+  </div>
+</div>
+```
+
+```ts
+const actions: AppHeaderAction[] = [
+  { id: "cart", icon: "<svg …>", label: "Cart", badge: cartCount }, // a 0 renders no badge
+  { id: "help", icon: "<svg …>", label: "Help centre", href: "https://help.pecb.com/", target: "_blank" },
+];
+
+const notifications: AppHeaderNotification[] = [
+  {
+    id: "renew",
+    title: "Your certificate expires in 25 days.",
+    meta: "Today · High priority",
+    read: false,
+    icon: "<svg …>",
+    iconBackground: "#fbeaea",
+    iconColor: "#a11e29",
+  },
+];
+```
+
+**Inputs** — `heading`, `chip`, `actions`, `showNotifications`, `notifications`,
+`notificationsLimit`, `notificationsOpen` (two-way), `showMenuButton`, `sticky`, `labels`.
+
+**Outputs** — `menuClick`, `actionClick`, `notificationClick`, `viewAllNotifications`.
+
+**Slots** — `[appHeaderTitle]` replaces the heading; `[appHeaderStart]` and `[appHeaderEnd]` add
+your own controls at either end of the bar.
+
+**Localisation** — same contract as the rail: `APP_HEADER_TRANSLATIONS[locale]` or
+`appHeaderLabels('fr-CA')`, or your own partial bundle. The unread badge's screen-reader text uses
+a `{n}` placeholder so each locale decides where the number sits — `'{n} ungelesen'` in German,
+`'未読 {n} 件'` in Japanese.
+
+The unread count is derived from the data, so the bell badge never drifts. The dropdown renders
+through the CDK overlay — never clipped by the header's stacking context, repositioned inside the
+viewport, closed by Escape or an outside click, with focus moved into it and returned on close.
+
+**Theming:**
+
+```css
+pecb-app-header {
+  --pecb-app-header-bg: #ffffff; /* surface            */
+  --pecb-app-header-border: #ececec; /* bottom rule        */
+  --pecb-app-header-accent: #a11e29; /* badges and links   */
+  --pecb-app-header-height: auto; /* minimum bar height */
+  --pecb-app-header-z: 20; /* sticky stacking    */
+}
+```
+
+### Content Container (`.pecb-container`)
+
+The one page-measure rule, applied everywhere content is shown. It reproduces the content wrapper
+from the PECB designs — `max-width: 1180px; margin: 0 auto; padding: 14px`, the gutter widening to
+16px below 880px — so every page in a project gets identical side spacing from a single class:
+
+```scss
+// styles.scss — ships with the package
+@use "@pecb-ui/components/styles/main";
+```
+
+```html
+<div class="pecb-container">…page content…</div>
+```
+
+One knob, settable on the element or any ancestor (any CSS length, or `none` for full bleed):
+
+```css
+:root {
+  --pecb-container-max-width: 1180px;
+}
+```
+
+SCSS consumers can include the same rule directly in a component:
+
+```scss
+@use "@pecb-ui/components/styles/abstracts/mixins" as *;
+
+.my-page {
+  @include content-container;
+}
+```
+
+### Project Layout Component
+
+The sidebar + header + content shell built on `pecb-sidebar`. Project your page into the
+`[layoutContent]` slot and it fills the content column — unchanged, full-bleed, exactly as existing
+consumers use it today. To give a page the centred measure, opt in with the container class:
+
+```html
+<pecb-project-layout pageTitle="Dashboard">
+  <div layoutContent>
+    <div class="pecb-container">…page content…</div>
+  </div>
+</pecb-project-layout>
+```
+
 ## Services
 
 ### NotificationService

package/fesm2022/pecb-ui-components-navigation.mjs

@@ -1,4 +1,4 @@
-export { AdminHeaderComponent, AdminHeaderFieldTemplateDirective, AffixComponent, AnchorComponent, BackToTopComponent, BreadcrumbsComponent, DEFAULT_LANGUAGES, HeaderActionsComponent, HeaderComponent, HeaderDividerComponent, HeaderLanguageComponent, HeaderSearchComponent, HeaderUserComponent, LanguageDropdownComponent, StepperComponent, TabComponent } from '@pecb-ui/components';
+export { APP_SIDEBAR_MENU_ICONS, AdminHeaderComponent, AdminHeaderFieldTemplateDirective, AffixComponent, AnchorComponent, AppHeaderComponent, AppSidebarComponent, BackToTopComponent, BreadcrumbsComponent, DEFAULT_APP_HEADER_LABELS, DEFAULT_APP_SIDEBAR_LABELS, DEFAULT_APP_SIDEBAR_LANGUAGES, DEFAULT_APP_SIDEBAR_MENU, DEFAULT_APP_SIDEBAR_ROLES, DEFAULT_LANGUAGES, HeaderActionsComponent, HeaderComponent, HeaderDividerComponent, HeaderLanguageComponent, HeaderSearchComponent, HeaderUserComponent, LanguageDropdownComponent, StepperComponent, TabComponent } from '@pecb-ui/components';
 
 /*
  * @pecb-ui/components/navigation — secondary entry point (audit F18).

package/fesm2022/pecb-ui-components-navigation.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"pecb-ui-components-navigation.mjs","sources":["../../../projects/ui-components/navigation/src/public-api.ts","../../../projects/ui-components/navigation/src/pecb-ui-components-navigation.ts"],"sourcesContent":["/*\n * @pecb-ui/components/navigation — secondary entry point (audit F18).\n *\n * Re-exports navigation components (header, breadcrumbs, tabs, stepper, anchor,\n * affix, back-to-top, language-dropdown) from the primary entry point:\n *\n *   import { BreadcrumbsComponent } from '@pecb-ui/components/navigation';\n *\n * Existing imports from '@pecb-ui/components' continue to work unchanged.\n */\nexport {\n  // Header + its subcomponents\n  HeaderComponent,\n  HeaderActionsComponent,\n  HeaderDividerComponent,\n  HeaderLanguageComponent,\n  HeaderSearchComponent,\n  HeaderUserComponent,\n  // Admin header\n  AdminHeaderComponent,\n  AdminHeaderFieldTemplateDirective,\n  // Breadcrumbs / anchors / affix\n  BreadcrumbsComponent,\n  AnchorComponent,\n  AffixComponent,\n  BackToTopComponent,\n  // Tabs / stepper\n  TabComponent,\n  StepperComponent,\n  // Language dropdown\n  LanguageDropdownComponent,\n  DEFAULT_LANGUAGES\n} from '@pecb-ui/components';\n\nexport type {\n  // Breadcrumbs\n  BreadcrumbSeparator,\n  // Anchor\n  AnchorDirection,\n  AnchorItem,\n  AnchorLevel,\n  // Affix\n  AffixPosition,\n  // Tab\n  TabSize,\n  TabStyle,\n  // Stepper\n  StepItem,\n  StepOrder,\n  StepState,\n  StepperDirection,\n  StepperSize,\n  StepperTailStyle,\n  StepperType,\n  // Header\n  HeaderActionButton,\n  HeaderLanguageOption,\n  HeaderSearchCategory,\n  // Admin header\n  AdminHeaderAction,\n  AdminHeaderActionType,\n  AdminHeaderBadgeVariant,\n  AdminHeaderField,\n  AdminHeaderFieldType,\n  AdminHeaderMetadata,\n  AdminHeaderMetadataType,\n  AdminHeaderProfile,\n  // Language dropdown\n  LanguageDisplayMode,\n  LanguageOption\n} from '@pecb-ui/components';\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './public-api';\n"],"names":[],"mappings":";;AAAA;;;;;;;;;AASG;;ACTH;;AAEG"}
+{"version":3,"file":"pecb-ui-components-navigation.mjs","sources":["../../../projects/ui-components/navigation/src/public-api.ts","../../../projects/ui-components/navigation/src/pecb-ui-components-navigation.ts"],"sourcesContent":["/*\n * @pecb-ui/components/navigation — secondary entry point (audit F18).\n *\n * Re-exports navigation components (header, breadcrumbs, tabs, stepper, anchor,\n * affix, back-to-top, language-dropdown) from the primary entry point:\n *\n *   import { BreadcrumbsComponent } from '@pecb-ui/components/navigation';\n *\n * Existing imports from '@pecb-ui/components' continue to work unchanged.\n */\nexport {\n  // Header + its subcomponents\n  HeaderComponent,\n  HeaderActionsComponent,\n  HeaderDividerComponent,\n  HeaderLanguageComponent,\n  HeaderSearchComponent,\n  HeaderUserComponent,\n  // Admin header\n  AdminHeaderComponent,\n  AdminHeaderFieldTemplateDirective,\n  // Breadcrumbs / anchors / affix\n  BreadcrumbsComponent,\n  AnchorComponent,\n  AffixComponent,\n  BackToTopComponent,\n  // Tabs / stepper\n  TabComponent,\n  StepperComponent,\n  // Language dropdown\n  LanguageDropdownComponent,\n  DEFAULT_LANGUAGES,\n  // Application shell sidebar + header\n  AppSidebarComponent,\n  AppHeaderComponent,\n  DEFAULT_APP_SIDEBAR_LABELS,\n  DEFAULT_APP_SIDEBAR_MENU,\n  DEFAULT_APP_SIDEBAR_LANGUAGES,\n  DEFAULT_APP_SIDEBAR_ROLES,\n  APP_SIDEBAR_MENU_ICONS,\n  DEFAULT_APP_HEADER_LABELS\n} from '@pecb-ui/components';\n\nexport type {\n  // Breadcrumbs\n  BreadcrumbSeparator,\n  // Anchor\n  AnchorDirection,\n  AnchorItem,\n  AnchorLevel,\n  // Affix\n  AffixPosition,\n  // Tab\n  TabSize,\n  TabStyle,\n  // Stepper\n  StepItem,\n  StepOrder,\n  StepState,\n  StepperDirection,\n  StepperSize,\n  StepperTailStyle,\n  StepperType,\n  // Header\n  HeaderActionButton,\n  HeaderLanguageOption,\n  HeaderSearchCategory,\n  // Admin header\n  AdminHeaderAction,\n  AdminHeaderActionType,\n  AdminHeaderBadgeVariant,\n  AdminHeaderField,\n  AdminHeaderFieldType,\n  AdminHeaderMetadata,\n  AdminHeaderMetadataType,\n  AdminHeaderProfile,\n  // Language dropdown\n  LanguageDisplayMode,\n  LanguageOption,\n  // Application shell sidebar\n  AppSidebarLabels,\n  AppSidebarMenuItem,\n  AppSidebarMenuOption,\n  AppSidebarMenuOptionChange,\n  AppSidebarNavGroup,\n  AppSidebarNavItem,\n  AppSidebarProduct,\n  AppSidebarRouterLink,\n  AppSidebarUser,\n  // Application shell header\n  AppHeaderAction,\n  AppHeaderChip,\n  AppHeaderChipTone,\n  AppHeaderLabels,\n  AppHeaderNotification\n} from '@pecb-ui/components';\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './public-api';\n"],"names":[],"mappings":";;AAAA;;;;;;;;;AASG;;ACTH;;AAEG"}