@ojiepermana/angular 21.1.11 → 21.1.13

package/README.md

@@ -33,6 +33,19 @@ If you install the package with `npm install`, `bun add`, `pnpm add`, or `yarn
 add` directly, peer dependency installation falls back to the package
 manager's own behavior.
 
+## Navigation primitives
+
+`@ojiepermana/angular/navigation` exports the shared sidebar and topbar building blocks used by the demo shells. The vertical navigation selector is now `sidebar` and the projected sidebar slots use `sidebar-header` and `sidebar-footer`.
+
+```html
+<sidebar [ariaLabel]="'Primary'" [appearance]="'default'">
+  <div sidebar-header>Brand</div>
+  <div sidebar-footer>Footer actions</div>
+</sidebar>
+```
+
+Register items through `NavigationService.registerItems(...)`, or pass them directly with the `items` input when composing a local navigation tree.
+
 ## SDK generator in a consumer workspace
 
 After `@ojiepermana/angular` is installed, a consumer workspace can scaffold an

package/brand/etos/README.md

@@ -2,12 +2,15 @@
 
 Etos implementation lives under `projects/angular/brand/etos`. Published consumers should use `@ojiepermana/angular/etos`.
 
+This package is the Etos-specific layer on top of the shared Angular libraries. It owns the Etos brand defaults, shell composition, brand stylesheet, and Etos-only UI such as the profile/theme switcher.
+
 Use this folder for Etos-specific implementation:
 
-- `core/` contains Etos provider composition and brand defaults.
+- `core/` contains brand defaults and provider composition.
+- `component/` contains Etos-owned UI such as `EtosThemeSwitcherComponent`.
+- `shells/` contains `EtosLayoutComponent` and the Etos empty, horizontal, and vertical shells.
 - `themes/` contains Etos color, style, layout, and component-facing CSS.
-- `layouts/` contains Etos shell components.
-- `navigation/`, `components/`, `assets/`, and `docs/` can be added when Etos needs brand-specific behavior beyond shared primitives.
+- `navigation/`, `assets/`, and `docs/` can be added when Etos needs brand-specific behavior beyond shared primitives.
 
 Shared services, types, and primitives stay in the generic libraries:
 
@@ -15,96 +18,87 @@ Shared services, types, and primitives stay in the generic libraries:
 - `@ojiepermana/angular/layout`
 - `@ojiepermana/angular/navigation`
 
-## Package usage
+## Public entrypoint
 
 Published consumers should import Etos through the short public entrypoint:
 
 ```ts
 import {
-  type EtosBrandOptions,
-  EtosHorizontalLayoutComponent,
+  EtosLayoutComponent,
   EtosThemeSwitcherComponent,
-  EtosVerticalLayoutComponent,
   provideEtosBrand,
+  provideEtosLayout,
+  provideEtosTheme,
+  type EtosBrandOptions,
+  type EtosThemeSwitcherQuickAction,
+  type EtosThemeSwitcherUserInfo,
 } from '@ojiepermana/angular/etos';
-import { LayoutService } from '@ojiepermana/angular/layout';
+```
+
+`@ojiepermana/angular/etos` currently exports:
+
+- `provideEtosBrand()` to apply the Etos theme and layout defaults together and optionally register navigation items.
+- `provideEtosTheme()` to install only the Etos theme wrapper over the shared theme provider.
+- `provideEtosLayout()` to install only the Etos layout wrapper over the shared layout provider.
+- `EtosLayoutComponent` to render the Etos shell from the current layout mode.
+- `EtosThemeSwitcherComponent` and related types for the profile/preferences UI.
+
+## Provider setup
+
+Etos ships with these defaults:
+
+- Theme defaults to brand `etos` with light mode.
+- Layout defaults to `vertical` mode with `container` width.
+
+Recommended provider configuration:
+
+```ts
+import { ApplicationConfig, provideBrowserGlobalErrorListeners } from '@angular/core';
+import { provideRouter } from '@angular/router';
+import { type EtosBrandOptions, provideEtosBrand } from '@ojiepermana/angular/etos';
+
+import { AppNavigation } from './app.navigation';
+import { routes } from './app.routes';
 
 export const etosBrandConfig = {
   theme: {
     mode: 'light',
-    style: 'default',
   },
   layout: {
     mode: 'vertical',
-    width: 'fixed',
   },
+  navigation: AppNavigation,
 } satisfies EtosBrandOptions;
 
-export const appConfig = {
-  providers: [provideEtosBrand(etosBrandConfig)],
+export const appConfig: ApplicationConfig = {
+  providers: [provideBrowserGlobalErrorListeners(), provideRouter(routes), provideEtosBrand(etosBrandConfig)],
 };
 ```
 
-`provideEtosBrand()` applies the Etos brand tokens and wires the shared `ThemeService` and `LayoutService` defaults for the app.
+`provideEtosBrand()` accepts these Etos-specific options:
+
+- `theme` merges into the shared Material theme config while keeping the Etos brand tokens.
+- `layout` merges into the shared Material layout config while keeping the Etos layout defaults.
+- `navigation` registers navigation items during application startup.
+- `navigationId` targets a non-default navigation registry id when needed.
+- `materialDefaults` defaults to `true`; set it to `false` to skip `withMaterialDefaults()`.
+
+Use the granular providers when the consumer only needs one part of the Etos stack:
 
 ```ts
-@Component({
-  imports: [EtosHorizontalLayoutComponent, EtosThemeSwitcherComponent, EtosVerticalLayoutComponent],
-  template: `
-    @switch (layoutMode()) {
-      @case ('horizontal') {
-        <etos-horizontal-layout>
-          <div ui-layout-profile>
-            <etos-theme-switcher
-              [userInfo]="profileInfo"
-              [quickActions]="horizontalQuickActions"
-              [notificationShortcut]="horizontalNotificationShortcut" />
-          </div>
-        </etos-horizontal-layout>
-      }
-      @default {
-        <etos-vertical-layout>
-          <div ui-sidebar-footer class="flex items-center gap-3">
-            <etos-theme-switcher [userInfo]="profileInfo" [quickActions]="verticalQuickActions" popoverAlign="start" />
-
-            <div class="flex flex-col gap-px">
-              <span>Ojie Permana</span>
-              <span>Etos design system navigator</span>
-            </div>
-          </div>
-        </etos-vertical-layout>
-      }
-    }
-  `,
-})
-export class Pages {
-  protected readonly layoutMode = inject(LayoutService).mode;
-  protected readonly profileInfo = {
-    name: 'Ojie Permana',
-    subtitle: 'Etos design system navigator',
-    avatarSrc: '/avatar-ojie.svg',
-    avatarAlt: 'Portrait of Ojie Permana',
-  };
-  protected readonly horizontalQuickActions = [
-    { value: 'sign-out', label: 'Logout', icon: 'logout', tone: 'destructive' },
-  ];
-  protected readonly verticalQuickActions = [
-    { value: 'notifications', label: 'Notifications', icon: 'notifications' },
-    { value: 'sign-out', label: 'Logout', icon: 'logout', tone: 'destructive' },
-  ];
-  protected readonly horizontalNotificationShortcut = {
-    value: 'notifications',
-    icon: 'notifications',
-    ariaLabel: 'Open notifications for Ojie Permana',
-  };
-}
+import { ApplicationConfig } from '@angular/core';
+import { provideEtosLayout, provideEtosTheme } from '@ojiepermana/angular/etos';
+
+export const appConfig: ApplicationConfig = {
+  providers: [provideEtosTheme(), provideEtosLayout({ mode: 'horizontal', width: 'wide' })],
+};
 ```
 
 ## Using the brand theme
 
 The Etos brand theme has two parts:
 
-- TypeScript setup through `provideEtosBrand()` for theme and layout defaults.
+- TypeScript setup through one of the Etos providers.
 - CSS setup through the Etos stylesheet so the `theme-brand="etos"` tokens are available at runtime.
 
 App CSS should import the Etos package stylesheet before Tailwind:
@@ -115,68 +109,100 @@ App CSS should import the Etos package stylesheet before Tailwind:
 @import '@ojiepermana/angular/theme/tailwind/theme.css';
 ```
 
-Recommended provider configuration:
+## Using the layout shell
+
+`EtosLayoutComponent` is the exported shell component for Etos. It resolves `empty`, `horizontal`, or `vertical` from its `mode` input or from `LayoutService` when the input is omitted.
+
+This is the same composition pattern used by the Etos demo:
 
 ```ts
-import { type EtosBrandOptions, provideEtosBrand } from '@ojiepermana/angular/etos';
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { RouterLink } from '@angular/router';
+import {
+  EtosLayoutComponent,
+  type EtosThemeSwitcherQuickAction,
+  EtosThemeSwitcherComponent,
+  type EtosThemeSwitcherUserInfo,
+} from '@ojiepermana/angular/etos';
 
-export const etosBrandConfig = {
-  theme: {
-    mode: 'light',
-    style: 'default',
-  },
-  layout: {
-    mode: 'vertical',
-    width: 'fixed',
-  },
-} satisfies EtosBrandOptions;
+@Component({
+  selector: 'app-pages',
+  imports: [RouterLink, EtosLayoutComponent, EtosThemeSwitcherComponent],
+  template: `
+    <ng-template #layoutBrand>
+      <a routerLink="/" class="flex min-w-0 items-center gap-3 px-2 py-1.5 transition-colors">
+        <span class="text-sm font-semibold leading-none tracking-tight">Ojiepermana UI</span>
+      </a>
+    </ng-template>
+
+    <ng-template #layoutPanel>
+      <div class="flex h-full w-full min-w-0 items-center justify-start gap-3 px-2 py-0">
+        <etos-theme-switcher [userInfo]="profileInfo" [quickActions]="quickActions" />
+
+        <div class="min-w-0 flex flex-col gap-px">
+          <span class="truncate text-sm font-semibold leading-none text-foreground">{{ profileName }}</span>
+          <span class="truncate text-xs leading-none text-muted-foreground">{{ profileTitle }}</span>
+        </div>
+      </div>
+    </ng-template>
+
+    <etos-layout [layoutBrandTemplate]="layoutBrand" [layoutProfileTemplate]="layoutPanel" />
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class Pages {
+  protected readonly profileName = 'Ojie Permana';
+  protected readonly profileTitle = 'Etos design system navigator';
+  protected readonly profileInfo = {
+    name: this.profileName,
+    subtitle: this.profileTitle,
+    avatarSrc: '/avatar-ojie.svg',
+    avatarAlt: 'Portrait of Ojie Permana',
+  } satisfies EtosThemeSwitcherUserInfo;
 
-export const appConfig = {
-  providers: [provideEtosBrand(etosBrandConfig)],
-};
+  protected readonly quickActions = [
+    { value: 'notifications', label: 'Notifications', icon: 'notifications' },
+    { value: 'sign-out', label: 'Logout', icon: 'logout', tone: 'destructive' },
+  ] satisfies readonly EtosThemeSwitcherQuickAction[];
+}
 ```
 
-From there, switch between `EtosHorizontalLayoutComponent` and `EtosVerticalLayoutComponent` based on the current `LayoutService.mode()` value, as shown above.
+Layout inputs:
 
-## Using the theme switcher
+- `mode`: optional explicit override for the active layout mode.
+- `layoutBrandTemplate`: used in the horizontal brand area and as the default vertical sidebar header.
+- `layoutProfileTemplate`: used in the horizontal profile area and as the default vertical sidebar footer.
+- `sidebarHeaderTemplate`: optional vertical-only override for the sidebar header.
+- `sidebarFooterTemplate`: optional vertical-only override for the sidebar footer.
 
-`EtosThemeSwitcherComponent` is exported from `@ojiepermana/angular/etos` and can be mounted in either the horizontal topbar or the vertical sidebar footer.
+That fallback behavior means a single `layoutBrandTemplate` and `layoutProfileTemplate` pair is enough for most consumers, while vertical layouts can still diverge when needed.
 
-Common inputs:
+## Using the theme switcher
 
-- `userInfo`: object input for the user display data: `name`, `subtitle`, `avatarSrc`, and `avatarAlt`.
-- `quickActions`: required array of action items rendered in the popup footer.
-- `notificationShortcut`: object input for the standalone notification trigger shown beside the avatar in horizontal mode.
-- `popoverAlign` and `popoverSide`: override the popover anchor position.
-- `showNotificationShortcut`: legacy boolean shortcut for rendering the default notification button. Prefer `notificationShortcut` when the data should come from the parent.
+`EtosThemeSwitcherComponent` is exported from `@ojiepermana/angular/etos` and is intended to live inside the Etos shell profile area or any consumer-owned profile trigger.
 
-Horizontal usage:
+Common inputs and output:
 
-```html
-<div ui-layout-profile class="etos-profile-trigger gap-2 px-0 py-0">
-  <etos-theme-switcher
-    [userInfo]="profileInfo"
-    [quickActions]="horizontalQuickActions"
-    [notificationShortcut]="horizontalNotificationShortcut" />
-</div>
-```
+- `quickActions`: required array rendered in the popup footer. Pass `[]` if you only want the built-in theme and layout controls.
+- `userInfo`: object input for `name`, `subtitle`, `avatarSrc`, and `avatarAlt`.
+- `userName`, `userSubtitle`, `avatarSrc`, and `avatarAlt`: fallback inputs when `userInfo` is not supplied.
+- `notificationShortcut`: configures the standalone notification trigger shown beside the avatar.
+- `showNotificationShortcut`: legacy boolean shortcut for rendering the default notification button.
+- `popoverSide`, `popoverAlign`, and `popoverSideOffset`: explicit popover placement overrides.
+- `actionSelected`: emits the selected quick action or notification shortcut value.
 
-In this mode the trigger shows only the avatar or initials plus the standalone notification shortcut.
+The popup always exposes theme scheme, layout mode, and layout width controls. The quick action area is fully consumer-driven:
+
+- Provide the action values and labels you need in `quickActions`.
+- Handle actions such as logout in the app consumer through `(actionSelected)`.
+- When `notificationShortcut.value` matches one of the `quickActions` values, the matching popup item is removed to avoid duplication.
 
-Vertical usage:
+Popover defaults now follow the active layout automatically:
 
-```html
-<div ui-sidebar-footer class="flex h-full w-full min-w-0 items-center justify-start gap-3 px-0 py-0">
-  <etos-theme-switcher [userInfo]="profileInfo" [quickActions]="verticalQuickActions" popoverAlign="start" />
-
-  <div class="min-w-0 flex flex-col gap-px">
-    <span class="truncate text-sm font-semibold leading-none text-foreground">Ojie Permana</span>
-    <span class="truncate text-xs leading-none text-muted-foreground">Etos design system navigator</span>
-  </div>
-</div>
-```
+- Vertical layout defaults to `side="top"` and `align="start"`.
+- Horizontal and empty layouts default to `side="bottom"` and `align="end"`.
 
-Use `popoverAlign="start"` in the vertical sidebar so the popup opens toward the content area instead of clipping against the left viewport edge.
+Only pass `popoverSide`, `popoverAlign`, or `popoverSideOffset` when you need to override those defaults.
 
 Input shape examples:
 
@@ -188,30 +214,24 @@ profileInfo = {
   avatarAlt: 'Portrait of Ojie Permana',
 };
 
-horizontalNotificationShortcut = {
+notificationShortcut = {
   value: 'notifications',
   icon: 'notifications',
   ariaLabel: 'Open notifications for Ojie Permana',
 };
 
-verticalQuickActions = [
+quickActions = [
   { value: 'notifications', label: 'Notifications', icon: 'notifications' },
   { value: 'sign-out', label: 'Logout', icon: 'logout', tone: 'destructive' },
 ];
 ```
 
-The popup always exposes theme scheme, layout mode, and layout width controls. The quick action area is fully consumer-driven:
-
-- Provide the action values and labels you need in `quickActions`.
-- Handle actions such as logout in the app consumer through `(actionSelected)`.
-- When `notificationShortcut.value` matches one of the `quickActions` values, the matching popup item is removed to avoid duplication.
-
 Example consumer-owned action handling:
 
 ```html
 <etos-theme-switcher
   [userInfo]="profileInfo"
-  [quickActions]="verticalQuickActions"
+  [quickActions]="quickActions"
   (actionSelected)="onThemeSwitcherAction($event)" />
 ```
 
@@ -225,10 +245,10 @@ onThemeSwitcherAction(action: string): void {
 
 ## Workspace usage in this repository
 
-The Etos demo under `projects/demo/etos` already uses the short TypeScript entrypoint:
+The Etos demo under `projects/demo/etos` already uses the short TypeScript entrypoint for provider setup and shell composition:
 
-- `src/app/app.config.ts` imports `provideEtosBrand` from `@ojiepermana/angular/etos`.
-- `src/pages/pages.ts` imports `EtosHorizontalLayoutComponent`, `EtosVerticalLayoutComponent`, and `EtosThemeSwitcherComponent` from `@ojiepermana/angular/etos`.
+- `src/app/app.config.ts` imports `provideEtosBrand` and passes `navigation: AppNavigation`.
+- `src/pages/pages.ts` imports `EtosLayoutComponent` and `EtosThemeSwitcherComponent` and wires `layoutBrandTemplate` plus `layoutProfileTemplate`.
 
 For CSS, the workspace demo currently imports the Etos source stylesheet directly:
 

package/etos/styles/color.css

@@ -3,6 +3,27 @@
  */
 @layer tokens {
   [theme-brand='etos'] {
+    --brand: 0 0% 64%;
+    --brand-border-alpha: 0.7;
+    --brand-background-alpha: 0.7;
+
+    --background: 210 38% 98%;
+    --surface: 0 0% 89.8%;
+    --surface-foreground: 211 56% 12%;
+    --foreground: 211 56% 12%;
+
+    --card: 0 0% 100%;
+    --card-foreground: 211 56% 12%;
+
+    --popover: 0 0% 100%;
+    --popover-foreground: 211 56% 12%;
+
+    --muted: 211 34% 94%;
+    --muted-foreground: 211 24% 38%;
+
+    --border: 211 28% 82%;
+    --input: 211 28% 82%;
+
     --primary: 211 95% 29%;
     --primary-foreground: 0 0% 100%;
     --accent: 211 95% 96%;
@@ -13,9 +34,40 @@
   }
 
   [data-mode='dark'][theme-brand='etos'] {
+    --brand: 0 0% 64%;
+    --brand-border-alpha: 0.45;
+    --brand-background-alpha: 0.55;
+
+    --background: 211 38% 9%;
+    --surface: 211 22% 18%;
+    --surface-foreground: 210 40% 96%;
+    --foreground: 210 40% 96%;
+
+    --card: 211 34% 11%;
+    --card-foreground: 210 40% 96%;
+
+    --popover: 211 34% 11%;
+    --popover-foreground: 210 40% 96%;
+
+    --muted: 211 22% 18%;
+    --muted-foreground: 211 18% 70%;
+
+    --border: 211 24% 24%;
+    --input: 211 24% 24%;
+
     --accent: 211 58% 18%;
     --accent-foreground: 211 90% 84%;
     --secondary: 211 24% 18%;
     --secondary-foreground: 211 82% 84%;
   }
 }
+
+@layer utilities {
+  .border-brand {
+    border-color: hsl(var(--brand, var(--border)) / var(--brand-border-alpha, 0.7));
+  }
+
+  .bg-brand {
+    background-color: hsl(var(--brand, var(--border)) / var(--brand-background-alpha, 0.7));
+  }
+}

package/etos/styles/layout.css

@@ -19,168 +19,3 @@
     --etos-layout-frame-shadow: 0 0 0 1px hsl(var(--border));
   }
 }
-
-@layer components {
-  .etos-layout-host {
-    display: block;
-    height: 100dvh;
-    width: 100%;
-    overflow: hidden;
-    background: hsl(var(--background));
-    color: hsl(var(--foreground));
-  }
-
-  .etos-layout-host--fixed {
-    box-sizing: border-box;
-  }
-
-  .etos-layout-frame {
-    display: flex;
-    height: 100%;
-    width: 100%;
-    overflow: hidden;
-    background: hsl(var(--background));
-  }
-
-  .etos-layout-frame--horizontal {
-    flex-direction: column;
-  }
-
-  .etos-layout-main {
-    min-width: 0;
-    flex: 1 1 0%;
-    overflow: auto;
-  }
-
-  .etos-layout-main--fixed {
-    width: 100%;
-    max-width: var(--etos-layout-main-max-width);
-    margin-inline: auto;
-  }
-
-  .etos-layout-topbar {
-    width: 100%;
-    flex-shrink: 0;
-    border-bottom: var(--border-width) solid hsl(var(--border));
-  }
-
-  .etos-layout-topbar-slot {
-    display: flex;
-    min-width: 0;
-    align-items: center;
-  }
-
-  .etos-layout-topbar-slot--end {
-    justify-content: flex-end;
-  }
-
-  .etos-layout-empty-host {
-    display: flex;
-    min-height: 100dvh;
-    width: 100%;
-    align-items: center;
-    justify-content: center;
-    padding: var(--etos-layout-empty-padding);
-    background: hsl(var(--background));
-    color: hsl(var(--foreground));
-  }
-
-  .etos-layout-empty-main {
-    width: 100%;
-    max-width: var(--etos-layout-empty-max-width);
-  }
-
-  .etos-brand-link,
-  .etos-profile-trigger {
-    display: inline-flex;
-    align-items: center;
-    gap: 0.75rem;
-    min-height: 2.5rem;
-    padding: 0.375rem 0.5rem;
-    color: hsl(var(--foreground));
-    text-decoration: none;
-    transition:
-      color 160ms ease,
-      background-color 160ms ease;
-  }
-
-  .etos-brand-link:focus-visible,
-  .etos-profile-trigger:focus-visible {
-    outline: 2px solid hsl(var(--ring));
-    outline-offset: 2px;
-  }
-
-  .etos-brand-mark,
-  .etos-profile-mark {
-    display: inline-flex;
-    height: var(--etos-layout-brand-mark-size);
-    width: var(--etos-layout-brand-mark-size);
-    align-items: center;
-    justify-content: center;
-    border-radius: var(--radius-md);
-    background: hsl(var(--primary));
-    color: hsl(var(--primary-foreground));
-    font-size: 0.7rem;
-    font-weight: 700;
-    letter-spacing: 0.18em;
-    line-height: 1;
-  }
-
-  .etos-profile-mark {
-    border-radius: 999px;
-    letter-spacing: 0;
-  }
-
-  .etos-brand-copy {
-    display: none;
-    min-width: 0;
-    flex-direction: column;
-    gap: 0.125rem;
-  }
-
-  .etos-brand-name {
-    font-size: var(--text-sm);
-    font-weight: 700;
-    line-height: 1;
-  }
-
-  .etos-brand-subtitle,
-  .etos-profile-name {
-    font-size: var(--text-xs);
-    line-height: 1;
-    color: hsl(var(--muted-foreground));
-  }
-
-  .etos-profile-name {
-    display: none;
-    font-weight: 600;
-  }
-
-  @media (min-width: 40rem) {
-    .etos-brand-copy,
-    .etos-profile-name {
-      display: flex;
-    }
-  }
-
-  @media (min-width: 64rem) {
-    .etos-layout-host--fixed {
-      padding: var(--etos-layout-shell-padding);
-    }
-
-    .etos-layout-frame--vertical-fixed {
-      max-width: var(--etos-layout-vertical-shell-max-width);
-      margin-inline: auto;
-    }
-
-    .etos-layout-frame--fixed {
-      border: var(--border-width) solid hsl(var(--border));
-      border-radius: var(--etos-layout-frame-radius);
-      box-shadow: var(--etos-layout-frame-shadow);
-    }
-
-    .etos-layout-main--vertical-fixed {
-      margin-inline: 0;
-    }
-  }
-}