@edsis/ui 0.0.2 → 0.0.3

package/layout/README.md

@@ -0,0 +1,454 @@
+# @edsis/ui/layout
+
+Primitive layout projection untuk menyusun shell UI dengan satu root `ui-layout`, satu variant layout (`vertical`, `horizontal`, atau `empty`), slot `ui-layout-nav`, dan area `ui-layout-content` yang menjadi scroll container utama.
+
+README ini mendokumentasikan seluruh API publik yang diekspor oleh package agar consumer bisa memahami kontrak komponen, type, service, dan perilaku layout tanpa perlu membaca source code.
+
+## Entry points
+
+`@edsis/ui/layout` adalah root entry point yang mengekspor seluruh primitive utama, `LayoutService`, seluruh type, constants, dan guards.
+
+```ts
+import {
+  LayoutService,
+  UiLayoutComponent,
+  UiLayoutContentComponent,
+  UiLayoutEmptyComponent,
+  UiLayoutHorizontalComponent,
+  UiLayoutNavComponent,
+  UiLayoutVerticalComponent,
+  type UiLayoutStyle,
+  type UiLayoutSurface,
+  type UiLayoutType,
+  type UiLayoutWidth,
+} from '@edsis/ui/layout';
+```
+
+Secondary entry point tetap tersedia bila consumer ingin import yang lebih eksplisit.
+
+```ts
+import { LayoutService } from '@edsis/ui/layout/services';
+import {
+  UI_LAYOUT_DEFAULT_STYLE,
+  UI_LAYOUT_DEFAULT_SURFACE,
+  UI_LAYOUT_DEFAULT_TYPE,
+  UI_LAYOUT_DEFAULT_WIDTH,
+  UI_LAYOUT_APPEARANCE_STORAGE_KEY,
+  UI_LAYOUT_STYLES,
+  UI_LAYOUT_SURFACE_STORAGE_KEY,
+  UI_LAYOUT_STYLE_STORAGE_KEY,
+  UI_LAYOUT_SURFACES,
+  UI_LAYOUT_TYPES,
+  UI_LAYOUT_TYPE_STORAGE_KEY,
+  UI_LAYOUT_WIDTHS,
+  UI_LAYOUT_WIDTH_STORAGE_KEY,
+  isUiLayoutSurface,
+  isUiLayoutStyle,
+  isUiLayoutType,
+  isUiLayoutWidth,
+  type UiLayoutContextValue,
+  type UiLayoutStyle,
+  type UiLayoutSurface,
+  type UiLayoutType,
+  type UiLayoutWidth,
+} from '@edsis/ui/layout/types';
+```
+
+Catatan:
+
+- Root entry point dan secondary entry point mengekspor symbol yang sama. Gunakan secondary entry point jika consumer ingin dependency path yang lebih eksplisit untuk `services` atau `types`.
+- Untuk kasus halaman yang membaca preferensi persisted, source of truth tetap berada di `LayoutService`.
+
+## Mental model
+
+Struktur yang direkomendasikan adalah sebagai berikut.
+
+```html
+<ui-layout>
+  <ui-layout-vertical | ui-layout-horizontal | ui-layout-empty>
+    <ui-layout-nav>...</ui-layout-nav>
+    <ui-layout-content>...</ui-layout-content>
+  </ui-layout-vertical | ui-layout-horizontal | ui-layout-empty>
+</ui-layout>
+```
+
+Aturan penggunaannya:
+
+- Gunakan tepat satu variant layout di dalam `ui-layout`.
+- Untuk layout `vertical` dan `horizontal`, urutan child yang umum adalah `ui-layout-nav` lalu `ui-layout-content`.
+- Untuk layout `empty`, biasanya cukup `ui-layout-content`.
+- `ui-layout-content` adalah area yang memiliki `overflow-auto`, jadi konten utama sebaiknya ditempatkan di sana.
+- Pada mode `vertical`, lebar nav mengikuti kontennya sendiri (`w-max`), bukan dipaksa oleh root layout.
+
+## Quick start
+
+### Vertical
+
+```html
+<ui-layout surface="grid" appearance="border-rail" width="full">
+  <ui-layout-vertical>
+    <ui-layout-nav ariaLabel="Primary navigation">
+      <aside class="flex h-full w-56 flex-col gap-4 bg-card/80 p-4">Navigation</aside>
+    </ui-layout-nav>
+
+    <ui-layout-content class="bg-background/80 p-6"> Content </ui-layout-content>
+  </ui-layout-vertical>
+</ui-layout>
+```
+
+### Horizontal
+
+```html
+<ui-layout surface="line-horizontal" appearance="flat" width="wide">
+  <ui-layout-horizontal>
+    <ui-layout-nav ariaLabel="Top navigation">
+      <header class="flex h-full items-center px-4">Navigation</header>
+    </ui-layout-nav>
+
+    <ui-layout-content class="p-6">Content</ui-layout-content>
+  </ui-layout-horizontal>
+</ui-layout>
+```
+
+### Empty
+
+```html
+<ui-layout surface="flat" appearance="flat" width="container">
+  <ui-layout-empty>
+    <ui-layout-content class="py-8"> Content </ui-layout-content>
+  </ui-layout-empty>
+</ui-layout>
+```
+
+## Pola page-level yang direkomendasikan
+
+Untuk halaman yang memiliki default sendiri tetapi tetap harus tunduk pada nilai local storage yang sudah tersimpan, pakai `LayoutService.registerDefaults(...)` sekali di level page, lalu bind root `ui-layout` ke signal service.
+
+```ts
+import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
+import {
+  LayoutService,
+  UiLayoutComponent,
+  UiLayoutContentComponent,
+  UiLayoutHorizontalComponent,
+  UiLayoutNavComponent,
+} from '@edsis/ui/layout';
+
+@Component({
+  selector: 'demo-board',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [UiLayoutComponent, UiLayoutHorizontalComponent, UiLayoutNavComponent, UiLayoutContentComponent],
+  template: `
+    <ui-layout [surface]="layout.surface()" [appearance]="layout.appearance()" [width]="layout.width()">
+      <ui-layout-horizontal>
+        <ui-layout-nav ariaLabel="Board navigation">...</ui-layout-nav>
+        <ui-layout-content>...</ui-layout-content>
+      </ui-layout-horizontal>
+    </ui-layout>
+  `,
+})
+export class DemoBoardComponent {
+  protected readonly layout = inject(LayoutService).registerDefaults({
+    surface: 'grid',
+    appearance: 'border-rail',
+    type: 'horizontal',
+    width: 'container',
+  });
+}
+```
+
+Dengan pola ini:
+
+- consumer cukup mendeklarasikan default sekali
+- nilai valid yang sudah ada di local storage tidak akan ditimpa
+- `layout.type()` bisa langsung dipakai untuk memilih variant `vertical`, `horizontal`, atau `empty`
+- root `ui-layout` selalu merender nilai final dari service, bukan hanya fallback dari template
+
+## API reference
+
+### `UiLayoutComponent`
+
+Root wrapper yang mengatur background surface, appearance frame, width mode, dan sinkronisasi fallback state ke `LayoutService`.
+
+Selector: `ui-layout`
+
+Inputs:
+
+| Input          | Type                    | Default  | Deskripsi                                                                                                                                                            |
+| -------------- | ----------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `surface`      | `UiLayoutSurface`       | `'flat'` | Menentukan fallback background root layout. Jika local storage `layout-surface` berisi nilai valid, nilai storage yang dipakai.                                      |
+| `appearance`   | `UiLayoutStyle or null` | `null`   | API template utama untuk menentukan fallback appearance frame. Jika input ini kosong, primitive mencoba alias `layout-style`, lalu fallback efektif akhirnya `flat`. |
+| `layout-style` | `UiLayoutStyle or null` | `null`   | Alias kompatibilitas untuk template lama. Tetap dibaca sebagai fallback, tetapi API yang direkomendasikan adalah `appearance`.                                       |
+| `width`        | `UiLayoutWidth`         | `'full'` | Menentukan fallback padding outer dan perilaku container frame. Jika local storage `layout-width` berisi nilai valid, nilai storage yang dipakai.                    |
+| `class`        | `string`                | `''`     | Menambahkan class pada host `ui-layout`.                                                                                                                             |
+
+Behavior:
+
+- Mendaftarkan default `surface`, `appearance`, dan `width` ke `LayoutService` hanya saat local storage belum memiliki nilai valid.
+- Nilai visual final selalu dibaca kembali dari `LayoutService`, sehingga stored preference menang atas fallback input.
+- Menambahkan atribut host `data-surface`, `data-layout-appearance`, `data-layout-style`, `data-layout-width`, dan `data-layout-type`.
+- Root tidak menyediakan input `type`. Type aktif dikendalikan oleh variant layout yang dirender, atau oleh consumer melalui `LayoutService.registerDefaults({ type })` sebelum template mengevaluasi `layout.type()`.
+- Selalu merender frame border.
+- Jika `appearance="border-rail"`, root menambah rail dekoratif di empat sudut frame dan memanjangkan garis sudut itu sampai tepi viewport.
+- Jika `width="container"`, frame dipusatkan mulai breakpoint `lg` dengan container behavior.
+
+### `UiLayoutVerticalComponent`
+
+Variant layout untuk shell dua kolom: nav di kiri, content di kanan.
+
+Selector: `ui-layout-vertical`
+
+Inputs:
+
+| Input   | Type     | Default | Deskripsi                                         |
+| ------- | -------- | ------- | ------------------------------------------------- |
+| `class` | `string` | `''`    | Menambahkan class pada host `ui-layout-vertical`. |
+
+Behavior:
+
+- Mengatur `LayoutService.type` menjadi `'vertical'`.
+- Menggunakan grid `grid-cols-[auto_minmax(0,1fr)]`.
+- Dalam mode `border-rail`, host dibuat `overflow-visible` agar rail nav/frame dapat mengekstensi keluar area frame.
+
+### `UiLayoutHorizontalComponent`
+
+Variant layout untuk shell bertumpuk vertikal: nav di atas, content mengisi sisa tinggi.
+
+Selector: `ui-layout-horizontal`
+
+Inputs:
+
+| Input   | Type     | Default | Deskripsi                                           |
+| ------- | -------- | ------- | --------------------------------------------------- |
+| `class` | `string` | `''`    | Menambahkan class pada host `ui-layout-horizontal`. |
+
+Behavior:
+
+- Mengatur `LayoutService.type` menjadi `'horizontal'`.
+- Menggunakan flex column untuk menyusun nav dan content.
+- Tidak merender rail nav vertikal khusus.
+
+### `UiLayoutEmptyComponent`
+
+Variant layout tanpa nav, dipakai untuk halaman yang hanya memiliki satu area konten.
+
+Selector: `ui-layout-empty`
+
+Inputs:
+
+| Input   | Type     | Default | Deskripsi                                      |
+| ------- | -------- | ------- | ---------------------------------------------- |
+| `class` | `string` | `''`    | Menambahkan class pada host `ui-layout-empty`. |
+
+Behavior:
+
+- Mengatur `LayoutService.type` menjadi `'empty'`.
+- Menyediakan wrapper penuh untuk satu area konten.
+- `ui-layout-nav` akan tersembunyi jika tetap dirender di mode ini.
+
+### `UiLayoutNavComponent`
+
+Wrapper untuk slot navigasi.
+
+Selector: `ui-layout-nav`
+
+Inputs:
+
+| Input       | Type     | Default               | Deskripsi                                        |
+| ----------- | -------- | --------------------- | ------------------------------------------------ |
+| `ariaLabel` | `string` | `'Layout navigation'` | Label aksesibilitas untuk landmark `navigation`. |
+| `class`     | `string` | `''`                  | Menambahkan class pada host `ui-layout-nav`.     |
+
+Behavior:
+
+- Host selalu memiliki `role="navigation"`.
+- Menambahkan atribut host `data-layout-type`, `data-layout-appearance`, dan `data-layout-style`.
+- Pada layout `horizontal`, nav menggunakan tinggi tetap `h-12`.
+- Pada layout `vertical`, nav menggunakan `w-max max-w-full`, sehingga lebar nav mengikuti isi child.
+- Pada layout `vertical` dengan `appearance="border-rail"`, komponen ini merender rail vertikal di sisi kanan nav, termasuk ekstensinya ke atas dan bawah viewport.
+- Pada layout `empty`, nav disembunyikan.
+
+Catatan penggunaan:
+
+- Untuk mode `border-rail`, jangan tambahkan `border-r` manual pada konten nav bila yang diinginkan adalah rail bawaan primitive.
+- Styling visual isi nav sebaiknya ditempatkan pada elemen child di dalam `ui-layout-nav`, bukan dengan mengandalkan border host.
+
+### `UiLayoutContentComponent`
+
+Wrapper untuk area konten utama yang scrollable.
+
+Selector: `ui-layout-content`
+
+Inputs:
+
+| Input   | Type     | Default | Deskripsi                                        |
+| ------- | -------- | ------- | ------------------------------------------------ |
+| `class` | `string` | `''`    | Menambahkan class pada host `ui-layout-content`. |
+
+Behavior:
+
+- Selalu menggunakan `overflow-auto`.
+- Pada layout `horizontal`, konten memakai `flex-1` agar mengisi sisa tinggi setelah nav.
+- Pada layout `vertical`, konten mengisi tinggi penuh kolom kanan.
+- Pada layout `empty`, konten memakai `h-full w-full`.
+- Jika `LayoutService.width()` adalah `'container'`, konten juga dipusatkan mulai `lg` dengan `lg:container lg:mx-auto`.
+
+## Surface API
+
+Nilai `surface` yang tersedia berasal dari `UI_LAYOUT_SURFACES`.
+
+| Nilai               | Efek visual                                                                |
+| ------------------- | -------------------------------------------------------------------------- |
+| `'flat'`            | Background polos `bg-background`.                                          |
+| `'grid'`            | Pola grid tipis dua arah.                                                  |
+| `'honeycome'`       | Pola radial rapat. Nama API dieja `honeycome` agar sesuai export saat ini. |
+| `'line-vertical'`   | Garis vertikal berulang.                                                   |
+| `'line-horizontal'` | Garis horizontal berulang.                                                 |
+
+## Appearance API
+
+Nilai `appearance` yang tersedia berasal dari `UI_LAYOUT_STYLES`.
+
+| Nilai           | Efek visual                                                                                                                                                              |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `'flat'`        | Frame tetap memiliki border 1px tanpa rail luar.                                                                                                                         |
+| `'border-rail'` | Frame memiliki border lebih tebal dan rail dekoratif pada sudut frame; untuk layout vertical, nav juga mendapat rail kanan yang mengekstensi ke atas dan bawah viewport. |
+
+Gunakan `appearance` di template Angular. Alias `layout-style` tetap tersedia untuk kompatibilitas template lama. Nilai persisted untuk appearance disimpan dengan key local storage `layout-appearance`.
+
+## Width API
+
+Nilai `width` yang tersedia berasal dari `UI_LAYOUT_WIDTHS`.
+
+| Nilai         | Perilaku                                                                                                                                                |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `'full'`      | Root menggunakan padding `p-4`, frame dan content tetap full width.                                                                                     |
+| `'wide'`      | Di bawah `lg` tampil seperti `full`, mulai `lg` memakai padding `p-12` di root.                                                                         |
+| `'container'` | Di bawah `lg` tampil seperti `full`, mulai `lg` root memakai `py-16` tanpa padding horizontal, lalu frame/content dipusatkan dengan container behavior. |
+
+Ringkasnya:
+
+- `wide` dan `container` sengaja collapse ke tampilan `full` di bawah breakpoint `lg`.
+- Perbedaan utama `container` muncul mulai `lg`, saat frame dan content tidak lagi full bleed secara horizontal.
+
+## `LayoutService`
+
+Service state kecil untuk menyimpan konteks layout aktif dan persistence ke local storage.
+
+Import:
+
+```ts
+import { LayoutService } from '@edsis/ui/layout/services';
+```
+
+Readonly signals:
+
+| Properti     | Type                      | Deskripsi                                           |
+| ------------ | ------------------------- | --------------------------------------------------- |
+| `surface`    | `Signal<UiLayoutSurface>` | Surface layout aktif.                               |
+| `type`       | `Signal<UiLayoutType>`    | Type layout aktif.                                  |
+| `appearance` | `Signal<UiLayoutStyle>`   | Appearance layout aktif.                            |
+| `style`      | `Signal<UiLayoutStyle>`   | Alias kompatibilitas untuk appearance layout aktif. |
+| `width`      | `Signal<UiLayoutWidth>`   | Width mode aktif.                                   |
+
+Methods:
+
+| Method                | Signature                                                      | Deskripsi                                                                                                                                                                                                 |
+| --------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `registerSurface`     | `(surface: UiLayoutSurface) => void`                           | Mendaftarkan fallback `layout-surface` ke local storage hanya jika storage belum memiliki nilai valid. Jika sudah ada nilai valid, service tetap memakai nilai yang tersimpan.                            |
+| `registerType`        | `(type: UiLayoutType) => void`                                 | Mendaftarkan fallback `layout-type` ke local storage hanya jika storage belum memiliki nilai valid. Jika sudah ada nilai valid, service tetap memakai nilai yang tersimpan.                               |
+| `registerAppearance`  | `(appearance: UiLayoutStyle) => void`                          | Mendaftarkan fallback `layout-appearance` ke local storage hanya jika storage belum memiliki nilai valid. Jika sudah ada nilai valid, service tetap memakai nilai yang tersimpan.                         |
+| `registerStyle`       | `(style: UiLayoutStyle) => void`                               | Alias kompatibilitas untuk `registerAppearance(...)`.                                                                                                                                                     |
+| `registerWidth`       | `(width: UiLayoutWidth) => void`                               | Mendaftarkan fallback `layout-width` ke local storage hanya jika storage belum memiliki nilai valid. Jika sudah ada nilai valid, service tetap memakai nilai yang tersimpan.                              |
+| `registerDefaults`    | `(defaults: { surface?, appearance?, type?, width? }) => this` | Mendaftarkan beberapa fallback sekaligus. Ini adalah API yang direkomendasikan untuk page-level default karena consumer cukup memanggil satu method dan tetap menghormati nilai storage yang sudah valid. |
+| `setSurface`          | `(surface: UiLayoutSurface) => void`                           | Menulis surface ke signal dan local storage.                                                                                                                                                              |
+| `setType`             | `(type: UiLayoutType) => void`                                 | Menulis type ke signal dan local storage.                                                                                                                                                                 |
+| `setAppearance`       | `(appearance: UiLayoutStyle) => void`                          | Menulis appearance ke signal dan local storage `layout-appearance`.                                                                                                                                       |
+| `setStyle`            | `(style: UiLayoutStyle) => void`                               | Alias kompatibilitas untuk `setAppearance(...)`.                                                                                                                                                          |
+| `setWidth`            | `(width: UiLayoutWidth) => void`                               | Menulis width ke signal dan local storage.                                                                                                                                                                |
+| `getStoredSurface`    | `() => UiLayoutSurface`                                        | Membaca surface yang valid dari storage atau default.                                                                                                                                                     |
+| `getStoredType`       | `() => UiLayoutType`                                           | Membaca type yang valid dari storage atau default.                                                                                                                                                        |
+| `getStoredAppearance` | `() => UiLayoutStyle`                                          | Membaca appearance yang valid dari storage atau default.                                                                                                                                                  |
+| `getStoredStyle`      | `() => UiLayoutStyle`                                          | Alias kompatibilitas untuk `getStoredAppearance()`.                                                                                                                                                       |
+| `getStoredWidth`      | `() => UiLayoutWidth`                                          | Membaca width yang valid dari storage atau default.                                                                                                                                                       |
+
+Persistence behavior:
+
+- Storage key: `layout-surface`, `layout-type`, `layout-appearance`, dan `layout-width`.
+- Default value: `flat`, `vertical`, `flat`, dan `full`.
+- `registerDefaults(...)` adalah API yang direkomendasikan untuk menetapkan default per halaman tanpa menimpa nilai valid yang sudah tersimpan sebelumnya.
+- Method `registerSurface(...)`, `registerType(...)`, `registerAppearance(...)`, dan `registerWidth(...)` tetap tersedia bila consumer memang perlu registrasi yang lebih granular.
+- Legacy storage key `layout-style` masih dibaca untuk kompatibilitas dan akan dibersihkan ketika appearance ditulis ulang ke `layout-appearance`.
+- Aman untuk SSR karena hanya mengakses `localStorage` saat runtime browser tersedia.
+
+Contoh penggunaan:
+
+```ts
+import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
+import { LayoutService } from '@edsis/ui/layout/services';
+
+@Component({
+  selector: 'demo-layout-toggle',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  template: `
+    <button type="button" (click)="layout.setAppearance('flat')">Flat</button>
+    <button type="button" (click)="layout.setAppearance('border-rail')">Border rail</button>
+  `,
+})
+export class DemoLayoutToggleComponent {
+  readonly layout = inject(LayoutService);
+}
+```
+
+## Types, constants, dan guards
+
+Seluruh symbol berikut diekspor dari `@edsis/ui/layout/types`.
+
+### Types
+
+| Symbol                 | Nilai                                                                                                     |
+| ---------------------- | --------------------------------------------------------------------------------------------------------- |
+| `UiLayoutType`         | `vertical`, `horizontal`, `empty`                                                                         |
+| `UiLayoutSurface`      | `flat`, `grid`, `honeycome`, `line-vertical`, `line-horizontal`                                           |
+| `UiLayoutStyle`        | `flat`, `border-rail`                                                                                     |
+| `UiLayoutWidth`        | `full`, `wide`, `container`                                                                               |
+| `UiLayoutContextValue` | Objekt berbentuk `{ surface, type, appearance, style, width }` yang masing-masing berupa readonly signal. |
+
+### Constants
+
+| Symbol                             | Nilai                                                               |
+| ---------------------------------- | ------------------------------------------------------------------- |
+| `UI_LAYOUT_TYPES`                  | `['vertical', 'horizontal', 'empty']`                               |
+| `UI_LAYOUT_SURFACES`               | `['flat', 'grid', 'honeycome', 'line-vertical', 'line-horizontal']` |
+| `UI_LAYOUT_STYLES`                 | `['flat', 'border-rail']`                                           |
+| `UI_LAYOUT_WIDTHS`                 | `['full', 'wide', 'container']`                                     |
+| `UI_LAYOUT_DEFAULT_SURFACE`        | `'flat'`                                                            |
+| `UI_LAYOUT_DEFAULT_TYPE`           | `'vertical'`                                                        |
+| `UI_LAYOUT_DEFAULT_STYLE`          | `'flat'`                                                            |
+| `UI_LAYOUT_DEFAULT_WIDTH`          | `'full'`                                                            |
+| `UI_LAYOUT_SURFACE_STORAGE_KEY`    | `'layout-surface'`                                                  |
+| `UI_LAYOUT_APPEARANCE_STORAGE_KEY` | `'layout-appearance'`                                               |
+| `UI_LAYOUT_TYPE_STORAGE_KEY`       | `'layout-type'`                                                     |
+| `UI_LAYOUT_STYLE_STORAGE_KEY`      | `'layout-style'` `(legacy compatibility key)`                       |
+| `UI_LAYOUT_WIDTH_STORAGE_KEY`      | `'layout-width'`                                                    |
+
+### Guards
+
+- `isUiLayoutSurface(value: string | null): value is UiLayoutSurface`
+  Memvalidasi string terhadap daftar surface yang didukung.
+- `isUiLayoutType(value: string | null): value is UiLayoutType`
+  Memvalidasi string terhadap daftar type yang didukung.
+- `isUiLayoutStyle(value: string | null): value is UiLayoutStyle`
+  Memvalidasi string terhadap daftar style yang didukung.
+- `isUiLayoutWidth(value: string | null): value is UiLayoutWidth`
+  Memvalidasi string terhadap daftar width yang didukung.
+
+## Consumer guidance
+
+- Gunakan `appearance` di template. `layout-style` dipertahankan hanya untuk kompatibilitas.
+- Untuk halaman yang punya default layout sendiri, utamakan `inject(LayoutService).registerDefaults({...})` sekali di level page daripada memanggil empat method `register...` terpisah.
+- Jika halaman harus merender variant berdasarkan preferensi yang tersimpan, pakai `layout.type()` sebagai sumber branching dan bind root `ui-layout` ke `layout.surface()`, `layout.appearance()`, dan `layout.width()`.
+- Tempatkan scroll page utama di `ui-layout-content`, bukan di root `ui-layout`.
+- Untuk `vertical + border-rail`, biarkan primitive yang merender rail kanan nav; hindari border manual yang menduplikasi garis itu.
+- Semua primitive menerima input `class`, jadi styling tambahan paling aman diberikan lewat class host atau child content.
+- Jika consumer perlu membaca state layout aktif dari komponen lain, inject `LayoutService` dan baca signal readonly-nya.

package/nav/README.md

@@ -0,0 +1,96 @@
+# Nav
+
+`@edsis/ui/nav` renders input-driven navigation with configurable appearances and instance-aware state.
+
+```ts
+import { UiNavComponent, UiNavFooterComponent, UiNavHeaderComponent, type UiNavItem } from '@edsis/ui/nav';
+import { NavService } from '@edsis/ui/nav/service';
+
+const items: UiNavItem[] = [
+  { id: 'dashboard', title: 'Dashboard', link: '/dashboard', icon: 'dashboard' },
+  {
+    id: 'reports',
+    title: 'Reports',
+    type: 'collapsible',
+    children: [{ id: 'monthly', title: 'Monthly', link: '/reports/monthly' }],
+  },
+];
+```
+
+```html
+<ui-nav id="erp-sidebar" [data]="items" orientation="vertical" appearance="sidebar" class="h-full">
+  <ui-nav-header class="px-1" [toggle]="true">
+    <div class="text-sm font-semibold">Workspace</div>
+  </ui-nav-header>
+
+  <ui-nav-footer class="p-3">
+    <button type="button">Sign out</button>
+  </ui-nav-footer>
+</ui-nav>
+
+<ui-nav id="erp-topbar" [data]="items" orientation="horizontal" appearance="navbar" />
+```
+
+## API Notes
+
+- `data` is the preferred source of navigation data.
+- `items` is still accepted as a compatibility alias while consumers migrate.
+- `orientation` accepts `vertical` or `horizontal`.
+- `appearance` depends on `orientation`:
+  - vertical: `sidebar` or `dockbar`
+  - horizontal: `navbar` or `flyout`
+- `id` identifies a navigation instance so multiple navs can keep distinct service state.
+- `position` accepts `left` or `right` for vertical navigation.
+- `collapsed` controls the icon-only sidebar state.
+- `dockbarMode` accepts `sticky` or `drawer` for vertical `dockbar`.
+- Angular Router is supported for internal links through `link`, `queryParams`, `fragment`, `exactMatch`, and `isActiveMatchOptions`.
+- External links can use `href` or `link` with `externalLink: true`.
+- `openedIds` owns collapsible state and supports two-way binding.
+- `itemSelected` emits for action, router, and external items.
+- `compact` is still supported as a compatibility alias for collapsed vertical sidebars.
+- `ui-nav-header` is optional, accepts Tailwind classes through `class`, and can render a built-in collapse toggle with `[toggle]="true"`.
+- `ui-nav-footer` is optional and accepts Tailwind classes through `class`.
+- `ui-nav-main` is rendered automatically by `ui-nav`, wraps the active navigation renderer, and owns the scrollable region between optional header and footer slots.
+
+## Nav Service
+
+`@edsis/ui/nav/service` exposes `NavService` as a singleton registry for navigation appearance and overlay state.
+
+```ts
+import { NavService } from '@edsis/ui/nav/service';
+
+const nav = inject(NavService);
+
+nav.setAppearance('erp-sidebar', 'dockbar');
+nav.setCollapsed('erp-sidebar', true);
+nav.toggleCollapsed('erp-sidebar');
+```
+
+Service defaults are stored in `localStorage` under:
+
+- `nav-vertical-appearance`
+- `nav-horizontal-appearance`
+
+Instance preferences are stored under:
+
+- `nav:{id}:orientation`
+- `nav:{id}:appearance`
+- `nav:{id}:position`
+- `nav:{id}:collapsed`
+- `nav:{id}:dockbar-mode`
+
+## Icons
+
+`ui-nav` does not load icon fonts or depend on an icon package. Pass an optional icon template when you need custom rendering.
+
+```html
+<ui-nav [items]="items">
+  <ng-template uiNavIcon let-icon>
+    <span class="material-symbols-outlined" aria-hidden="true">{{ icon }}</span>
+  </ng-template>
+</ui-nav>
+```
+
+## Boundaries
+
+This entry point must stay consumer-agnostic. Layout and theme composition belong to the consumer layer, while nav appearance defaults, instance registration, and overlay state now live inside `NavService`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edsis/ui",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/edsis/angular.git"
@@ -11,7 +11,8 @@
   },
   "peerDependencies": {
     "@angular/common": "^21.2.0",
-    "@angular/core": "^21.2.0"
+    "@angular/core": "^21.2.0",
+    "@angular/router": "^21.2.0"
   },
   "dependencies": {
     "@types/d3-array": "^3.2.2",
@@ -201,6 +202,18 @@
       "types": "./types/edsis-ui-label.d.ts",
       "default": "./fesm2022/edsis-ui-label.mjs"
     },
+    "./layout": {
+      "types": "./types/edsis-ui-layout.d.ts",
+      "default": "./fesm2022/edsis-ui-layout.mjs"
+    },
+    "./layout/services": {
+      "types": "./types/edsis-ui-layout-services.d.ts",
+      "default": "./fesm2022/edsis-ui-layout-services.mjs"
+    },
+    "./layout/types": {
+      "types": "./types/edsis-ui-layout-types.d.ts",
+      "default": "./fesm2022/edsis-ui-layout-types.mjs"
+    },
     "./menubar": {
       "types": "./types/edsis-ui-menubar.d.ts",
       "default": "./fesm2022/edsis-ui-menubar.mjs"
@@ -209,10 +222,22 @@
       "types": "./types/edsis-ui-native-select.d.ts",
       "default": "./fesm2022/edsis-ui-native-select.mjs"
     },
+    "./nav": {
+      "types": "./types/edsis-ui-nav.d.ts",
+      "default": "./fesm2022/edsis-ui-nav.mjs"
+    },
+    "./nav/service": {
+      "types": "./types/edsis-ui-nav-service.d.ts",
+      "default": "./fesm2022/edsis-ui-nav-service.mjs"
+    },
     "./navigation-menu": {
       "types": "./types/edsis-ui-navigation-menu.d.ts",
       "default": "./fesm2022/edsis-ui-navigation-menu.mjs"
     },
+    "./page": {
+      "types": "./types/edsis-ui-page.d.ts",
+      "default": "./fesm2022/edsis-ui-page.mjs"
+    },
     "./pagination": {
       "types": "./types/edsis-ui-pagination.d.ts",
       "default": "./fesm2022/edsis-ui-pagination.mjs"
@@ -281,6 +306,10 @@
       "types": "./types/edsis-ui-textarea.d.ts",
       "default": "./fesm2022/edsis-ui-textarea.mjs"
     },
+    "./theme": {
+      "types": "./types/edsis-ui-theme.d.ts",
+      "default": "./fesm2022/edsis-ui-theme.mjs"
+    },
     "./timeline": {
       "types": "./types/edsis-ui-timeline.d.ts",
       "default": "./fesm2022/edsis-ui-timeline.mjs"

package/page/README.md

@@ -0,0 +1,46 @@
+# @edsis/ui/page
+
+Primitive page shell untuk layout halaman dengan pendekatan nested component.
+
+## Components
+
+- `ui-page`
+- `ui-page-header`
+- `ui-page-content`
+- `ui-page-footer`
+- `ui-page-side`
+- `ui-page-side-toggle`
+
+`ui-page-side-toggle` menerima projected content untuk label atau ikon kustom. Jika tidak ada projected content, komponen akan memakai ikon fallback bawaan.
+
+## Variants
+
+- `stacked`
+- `side`
+
+## Side Modes
+
+- `sticky`
+- `drawer`
+- `overlay`
+
+## Example
+
+```html
+<ui-page variant="side" position="left">
+  <ui-page-header>
+    <ui-page-side-toggle ariaLabel="Toggle side">
+      <span>Open filters</span>
+    </ui-page-side-toggle>
+    <h1>Page title</h1>
+  </ui-page-header>
+
+  <ui-page-side mode="overlay">
+    <p>Filters</p>
+  </ui-page-side>
+
+  <ui-page-content>
+    <p>Main content</p>
+  </ui-page-content>
+</ui-page>
+```