@ojiepermana/angular 22.1.10 → 22.1.12

package/theme/layout/README.md

@@ -0,0 +1,539 @@
+# @ojiepermana/angular/theme/layout
+
+Primitive layout projection untuk menyusun shell UI dengan satu root `Layout`, satu variant layout (`vertical`, `horizontal`, `empty`, atau `fluid`), slot `LayoutNavigation`, dan area `LayoutContent` 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
+
+`@ojiepermana/angular/theme/layout` adalah root entry point yang mengekspor seluruh primitive utama, `LayoutService`, seluruh type, constants, dan guards.
+
+```ts
+import {
+  LayoutService,
+  LayoutComponent,
+  LayoutContentComponent,
+  LayoutEmptyComponent,
+  LayoutFluidComponent,
+  LayoutHorizontalComponent,
+  LayoutNavigationComponent,
+  LayoutVerticalComponent,
+  type LayoutAppearance,
+  type LayoutSurface,
+  type LayoutType,
+  type LayoutWidth,
+} from '@ojiepermana/angular/theme/layout';
+```
+
+Secondary entry point tetap tersedia bila consumer ingin import yang lebih eksplisit.
+
+```ts
+import { LayoutService } from '@ojiepermana/angular/theme/layout/services';
+import {
+  LAYOUT_DEFAULT_APPEARANCE,
+  LAYOUT_DEFAULT_SURFACE,
+  LAYOUT_DEFAULT_TYPE,
+  LAYOUT_DEFAULT_WIDTH,
+  LAYOUT_APPEARANCE_STORAGE_KEY,
+  LAYOUT_APPEARANCES,
+  LAYOUT_SURFACE_STORAGE_KEY,
+  LAYOUT_SURFACES,
+  LAYOUT_TYPES,
+  LAYOUT_TYPE_STORAGE_KEY,
+  LAYOUT_WIDTHS,
+  LAYOUT_WIDTH_STORAGE_KEY,
+  isUiLayoutSurface,
+  isUiLayoutAppearance,
+  isUiLayoutType,
+  isUiLayoutWidth,
+  type LayoutContextValue,
+  type LayoutAppearance,
+  type LayoutSurface,
+  type LayoutType,
+  type LayoutWidth,
+} from '@ojiepermana/angular/theme/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
+<Layout>
+  <LayoutVertical | LayoutHorizontal | LayoutEmpty | LayoutFluid>
+    <LayoutNavigation>...</LayoutNavigation>
+    <LayoutContent>...</LayoutContent>
+  </LayoutVertical | LayoutHorizontal | LayoutEmpty | LayoutFluid>
+</Layout>
+```
+
+Aturan penggunaannya:
+
+- Gunakan tepat satu variant layout di dalam `Layout`.
+- Untuk layout `vertical` dan `horizontal`, urutan child yang umum adalah `LayoutNavigation` lalu `LayoutContent`.
+- Untuk layout `empty`, biasanya cukup `LayoutContent`.
+- Untuk layout `fluid`, child dapat berupa konten page tunggal yang ingin dipusatkan terhadap frame.
+- `LayoutContent` 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
+<Layout surface="grid" appearance="border-rail" width="full">
+  <LayoutVertical>
+    <LayoutNavigation ariaLabel="Primary navigation">
+      <aside class="flex h-full w-56 flex-col gap-4 bg-card/80 p-4">Navigation</aside>
+    </LayoutNavigation>
+
+    <LayoutContent class="bg-background/80 p-6"> Content </LayoutContent>
+  </LayoutVertical>
+</Layout>
+```
+
+### Horizontal
+
+```html
+<Layout surface="line-horizontal" appearance="flat" width="wide">
+  <LayoutHorizontal>
+    <LayoutNavigation ariaLabel="Top navigation">
+      <header class="flex h-full items-center px-4">Navigation</header>
+    </LayoutNavigation>
+
+    <LayoutContent class="p-6">Content</LayoutContent>
+  </LayoutHorizontal>
+</Layout>
+```
+
+### Empty
+
+```html
+<Layout surface="flat" appearance="flat" width="container">
+  <LayoutEmpty>
+    <LayoutContent class="py-8"> Content </LayoutContent>
+  </LayoutEmpty>
+</Layout>
+```
+
+### Fluid
+
+```html
+<Layout surface="grid" appearance="border-rail" width="fluid">
+  <LayoutFluid>
+    <section class="w-full max-w-xl border border-border bg-card/90 p-6">Content</section>
+  </LayoutFluid>
+</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 `Layout` ke signal service.
+
+```ts
+import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
+import {
+  LayoutService,
+  LayoutComponent,
+  LayoutContentComponent,
+  LayoutHorizontalComponent,
+  LayoutNavigationComponent,
+} from '@ojiepermana/angular/theme/layout';
+
+@Component({
+  selector: 'demo-board',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [
+    LayoutComponent,
+    LayoutHorizontalComponent,
+    LayoutNavigationComponent,
+    LayoutContentComponent,
+  ],
+  template: `
+    <Layout
+      [surface]="layout.surface()"
+      [appearance]="layout.appearance()"
+      [width]="layout.width()"
+    >
+      <LayoutHorizontal>
+        <LayoutNavigation ariaLabel="Board navigation">...</LayoutNavigation>
+        <LayoutContent>...</LayoutContent>
+      </LayoutHorizontal>
+    </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 `Layout` selalu merender nilai final dari service, bukan hanya fallback dari template
+
+## API reference
+
+### `LayoutComponent`
+
+Root wrapper yang mengatur background surface, appearance frame, width mode, dan sinkronisasi fallback state ke `LayoutService`.
+
+Selector: `Layout`
+
+Inputs:
+
+| Input               | Type                       | Default  | Deskripsi                                                                                                                                                                                   |
+| ------------------- | -------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `surface`           | `LayoutSurface`            | `'flat'` | Menentukan fallback background root layout. Jika local storage `layout-surface` berisi nilai valid, nilai storage yang dipakai.                                                             |
+| `appearance`        | `LayoutAppearance or null` | `null`   | API template untuk menentukan fallback appearance frame. Jika input ini kosong, primitive mencoba alias `layout-appearance`, lalu fallback efektif akhirnya `flat`.                         |
+| `layout-appearance` | `LayoutAppearance or null` | `null`   | Alias simetris dengan `nav-appearance` pada navigation (kosakata sama `flat \| border-rail`). Memberi `appearance` yang sama ke shell & nav membuat keduanya seragam.                       |
+| `width`             | `LayoutWidth`              | `'full'` | Menentukan fallback padding outer dan perilaku container frame. Jika local storage `layout-width` berisi nilai valid, nilai storage yang dipakai.                                           |
+| `layout-type`       | `LayoutType or null`       | `null`   | Override eksplisit type aktif (`vertical \| horizontal \| empty \| fluid`). Jika di-set, menjadi sumber kebenaran type dan menimpa variant `Layout*`. Jika `null`, variant yang menetapkan. |
+| `class`             | `string`                   | `''`     | Menambahkan class pada host `Layout`.                                                                                                                                                       |
+
+Behavior:
+
+- Jika consumer memberi input manual `surface`, `appearance`, atau `width`, nilai itu dipakai sebagai override in-memory untuk instance aktif tanpa menulis `localStorage`.
+- Jika input manual kosong, primitive 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 child primitive tetap membaca state yang sama selama instance aktif.
+- Menambahkan atribut host `data-surface`, `data-layout-appearance`, `data-layout-width`, dan `data-layout-type`.
+- Root menyediakan input opsional `layout-type`. Bila di-set, input ini menjadi sumber kebenaran type aktif dan menimpa variant layout yang dirender (override in-memory tanpa menulis `localStorage`). Bila `null`, 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, rail inset horizontal, dan rail vertikal sekunder di luar sisi kiri-kanan frame sehingga frame terlihat seperti memiliki double rail.
+- Jika `width="container"`, frame dipusatkan mulai breakpoint `lg` dengan container behavior.
+- Jika `width="fluid"` dan variant aktif adalah `LayoutFluid`, frame akan shrink mengikuti tinggi dan lebar konten lalu dipusatkan terhadap viewport.
+
+### `LayoutVerticalComponent`
+
+Variant layout untuk shell dua kolom: nav di kiri, content di kanan.
+
+Selector: `LayoutVertical`
+
+Inputs:
+
+| Input   | Type     | Default | Deskripsi                                     |
+| ------- | -------- | ------- | --------------------------------------------- |
+| `class` | `string` | `''`    | Menambahkan class pada host `LayoutVertical`. |
+
+Behavior:
+
+- Mengatur `LayoutService.type` menjadi `'vertical'` hanya untuk state aktif dan tidak menulis `localStorage`.
+- 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.
+
+### `LayoutHorizontalComponent`
+
+Variant layout untuk shell bertumpuk vertikal: nav di atas, content mengisi sisa tinggi.
+
+Selector: `LayoutHorizontal`
+
+Inputs:
+
+| Input   | Type     | Default | Deskripsi                                       |
+| ------- | -------- | ------- | ----------------------------------------------- |
+| `class` | `string` | `''`    | Menambahkan class pada host `LayoutHorizontal`. |
+
+Behavior:
+
+- Mengatur `LayoutService.type` menjadi `'horizontal'` hanya untuk state aktif dan tidak menulis `localStorage`.
+- Menggunakan flex column untuk menyusun nav dan content.
+- Tidak merender rail nav vertikal khusus.
+
+### `LayoutEmptyComponent`
+
+Variant layout tanpa nav, dipakai untuk halaman yang hanya memiliki satu area konten.
+
+Selector: `LayoutEmpty`
+
+Inputs:
+
+| Input   | Type     | Default | Deskripsi                                  |
+| ------- | -------- | ------- | ------------------------------------------ |
+| `class` | `string` | `''`    | Menambahkan class pada host `LayoutEmpty`. |
+
+Behavior:
+
+- Mengatur `LayoutService.type` menjadi `'empty'` hanya untuk state aktif dan tidak menulis `localStorage`.
+- Menyediakan wrapper penuh untuk satu area konten.
+- `LayoutNavigation` akan tersembunyi jika tetap dirender di mode ini.
+
+### `LayoutNavigationComponent`
+
+Wrapper untuk slot navigasi.
+
+Selector: `LayoutNavigation`
+
+Inputs:
+
+| Input       | Type      | Default               | Deskripsi                                                                                    |
+| ----------- | --------- | --------------------- | -------------------------------------------------------------------------------------------- |
+| `ariaLabel` | `string`  | `'Layout navigation'` | Label aksesibilitas untuk landmark `navigation`.                                             |
+| `landmark`  | `boolean` | `true`                | Set `false` bila child `<Navigation>` sudah menjadi satu-satunya landmark navigasi semantik. |
+| `class`     | `string`  | `''`                  | Menambahkan class pada host `LayoutNavigation`.                                              |
+
+Behavior:
+
+- Host memiliki `role="navigation"` dan `aria-label` hanya saat `landmark=true`.
+- Menambahkan atribut host `data-layout-type` dan `data-layout-appearance`.
+- 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 `LayoutNavigation`, bukan dengan mengandalkan border host.
+
+### `LayoutContentComponent`
+
+Wrapper untuk area konten utama yang scrollable.
+
+Selector: `LayoutContent`
+
+Inputs:
+
+| Input                 | Type      | Default          | Deskripsi                                                                   |
+| --------------------- | --------- | ---------------- | --------------------------------------------------------------------------- |
+| `class`               | `string`  | `''`             | Menambahkan class pada host `LayoutContent`.                                |
+| `content-id`          | `string`  | `'main-content'` | Id landmark utama dan target skip link.                                     |
+| `focus-on-navigation` | `boolean` | `false`          | Jika aktif, fokuskan landmark utama setelah Angular Router `NavigationEnd`. |
+
+Behavior:
+
+- Selalu menggunakan `overflow-auto`.
+- Selalu menjadi satu landmark `role="main"` dengan `tabindex="-1"` agar dapat difokuskan
+  secara programatik tanpa menambahkannya ke urutan Tab normal.
+- 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`.
+
+### `LayoutWrapperDefault`
+
+Wrapper siap pakai menambahkan skip link, memastikan child `<Navigation>` menjadi satu-satunya
+landmark `Primary navigation`, dan menyediakan drawer navigasi berbasis `Sheet` di bawah 640px.
+State drawer mobile memakai `id="main-mobile"` (tidak dipersist) dan `data-id="main"` agar data
+apps-launcher tetap konsisten tanpa berbagi state desktop.
+
+| Input/model              | Type      | Default                  | Deskripsi                                            |
+| ------------------------ | --------- | ------------------------ | ---------------------------------------------------- |
+| `content-id`             | `string`  | `'main-content'`         | Id landmark utama dan target skip link.              |
+| `skip-link-label`        | `string`  | `'Skip to main content'` | Label skip link yang dapat dilokalkan.               |
+| `focus-on-navigation`    | `boolean` | `false`                  | Meneruskan focus-on-route-change ke `LayoutContent`. |
+| `mobile-nav-open`        | `boolean` | `false`                  | Model two-way untuk state Sheet mobile.              |
+| `mobile-nav-label`       | `string`  | `'Open navigation'`      | Accessible name tombol dan dialog mobile.            |
+| `close-mobile-nav-label` | `string`  | `'Close navigation'`     | Accessible name tombol close Sheet mobile.           |
+
+| Output     | Type   | Deskripsi                                                    |
+| ---------- | ------ | ------------------------------------------------------------ |
+| `(logout)` | `void` | Pengguna menekan logout pada footer navigation. Lihat bawah. |
+
+`(logout)` diteruskan dari setiap nav type yang menampilkan identitas user
+(`sidebar`, `dockbar`, `navbar`, `flyout`) termasuk drawer mobile, jadi consumer
+cukup mengikat satu output. Dockbar memancarkan dari tombol rail maupun tombol
+aside footer. Layout `empty` dan `fluid` bersifat brand-only, jadi tidak merender
+kontrol logout sama sekali.
+
+Library tidak memanggil endpoint dan tidak melakukan navigasi: endpoint, penanganan
+cookie, dan target redirect berbeda tiap aplikasi, jadi efeknya milik consumer.
+
+```html
+<LayoutWrapperDefault [data]="nav" [brand]="brand" [user]="user" (logout)="signOut()">
+  <router-outlet />
+</LayoutWrapperDefault>
+```
+
+Consumer yang tidak mengikat `(logout)` tetap merender tanpa error; tombolnya
+sekadar tidak melakukan apa pun.
+
+Saat viewport kembali ke desktop, Sheet ditutup otomatis. Pemilihan item mobile juga menutup
+Sheet dan mengembalikan fokus melalui primitive Sheet.
+
+`nav-type="desktop"` adalah mode shell content-focused khusus. Nilai ini hanya
+valid ketika shell berada pada mode `desktop` dan `layout-type="horizontal"`.
+Pada kombinasi tersebut, `desktop` adalah satu-satunya nav type yang valid;
+consumer settings harus menormalkan `navbar` atau `flyout` menjadi `desktop`.
+Wrapper mempertahankan `LayoutHorizontal` agar frame desktop tetap konsisten,
+tetapi menyembunyikan `LayoutNavigation` dan app bar mobile, sama seperti
+perilaku navigasi pada layout `empty`.
+
+## Surface API
+
+Nilai `surface` yang tersedia berasal dari `LAYOUT_SURFACES`.
+
+Semua pattern memakai tiga tier semantik: LINE, HIGHLIGHT, dan NODE. Saat
+`theme-neutral='base'`, hue pattern mengikuti accent aktif. Pada seluruh neutral
+lainnya, pattern mengikuti keluarga neutral tersebut. Tonal anchor dan opacity
+tetap dipisahkan agar tekstur terlihat tetapi tidak bersaing dengan konten. Chrome
+yang memang accent tetap berada di luar aturan pattern: rail dan frame
+`border-rail`, serta frame khusus `grid-line`. Frame flat lainnya tetap memakai
+neutral `--border`.
+
+| Nilai               | Efek visual                                                                                                                                                                                                                                                                                                                          |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `'flat'`            | Background polos `bg-layout-canvas`, tanpa pattern.                                                                                                                                                                                                                                                                                  |
+| `'grid'`            | Pola grid tipis dua arah; warna garis memakai tier LINE melalui `--layout-grid-color`.                                                                                                                                                                                                                                               |
+| `'grid-line'`       | Mosaik kotak: grid tipis + kotak highlight memakai tier HIGHLIGHT melalui `--layout-grid-highlight-color`. Memaksa sudut frame kotak (`rounded-none`) + border frame Accent. Pada appearance `border-rail`, garis rail + border frame (tebal `--layout-rail-width` = 1px) tetap Accent pada opacity `--layout-rail-opacity` = 0.666. |
+| `'honeycomb'`       | Outline honeycomb tipis memakai tier LINE yang sama dengan grid.                                                                                                                                                                                                                                                                     |
+| `'matrix'`          | Field biner (0/1) acak tipis memakai tier NODE melalui `--layout-matrix-color`; edge glow memakai tier yang sama dengan opacity terpisah.                                                                                                                                                                                            |
+| `'circuit'`         | Tekstur PCB dua lapisan: trace memakai tier LINE (`--layout-circuit-trace-color`) dan node/pad memakai tier NODE (`--layout-circuit-node-color`).                                                                                                                                                                                    |
+| `'line-vertical'`   | Garis vertikal berulang memakai tier LINE pada opacity single-axis.                                                                                                                                                                                                                                                                  |
+| `'line-horizontal'` | Garis horizontal berulang memakai tier LINE pada opacity single-axis.                                                                                                                                                                                                                                                                |
+
+## Appearance API
+
+Nilai `appearance` yang tersedia berasal dari `LAYOUT_APPEARANCES`.
+
+| Nilai           | Efek visual                                                                                                                                                                                                                                                               |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `'flat'`        | Frame tetap memiliki border 1px tanpa rail luar.                                                                                                                                                                                                                          |
+| `'border-rail'` | Frame memiliki border lebih tebal, rail dekoratif pada sudut frame, rail inset horizontal, serta rail vertikal sekunder di luar sisi kiri-kanan untuk efek double rail; untuk layout vertical, nav juga mendapat rail kanan yang mengekstensi ke atas dan bawah viewport. |
+
+Gunakan `appearance` atau alias `layout-appearance` (simetris dengan `nav-appearance` di navigation; kosakata sama `flat | border-rail`) di template Angular. Nilai persisted untuk appearance disimpan dengan key local storage `layout-appearance`.
+
+## Width API
+
+Nilai `width` yang tersedia berasal dari `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.               |
+| `'fluid'`     | Dipakai untuk `LayoutFluid`: root dan rail menjadi kanvas centering, frame shrink mengikuti ukuran konten, lalu tetap dibatasi `max-width` dan `max-height` viewport. |
+
+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.
+- `fluid` ditujukan untuk halaman tunggal seperti auth, splash, atau status page yang membutuhkan frame auto-centered di kedua sumbu.
+
+## `LayoutService`
+
+Service state kecil untuk menyimpan konteks layout aktif dan persistence ke local storage.
+
+Import:
+
+```ts
+import { LayoutService } from '@ojiepermana/angular/theme/layout/services';
+```
+
+Readonly signals:
+
+| Properti     | Type                       | Deskripsi                |
+| ------------ | -------------------------- | ------------------------ |
+| `surface`    | `Signal<LayoutSurface>`    | Surface layout aktif.    |
+| `type`       | `Signal<LayoutType>`       | Type layout aktif.       |
+| `appearance` | `Signal<LayoutAppearance>` | Appearance layout aktif. |
+| `width`      | `Signal<LayoutWidth>`      | Width mode aktif.        |
+
+Methods:
+
+| Method                | Signature                                                                 | Deskripsi                                                                                                                                                                                                 |
+| --------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `registerSurface`     | `(surface: LayoutSurface) => 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: LayoutType) => 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: LayoutAppearance) => 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.                         |
+| `registerWidth`       | `(width: LayoutWidth) => 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: LayoutSurface, options?: { persist?: boolean }) => void`       | Menulis surface ke signal. Secara default juga menulis `localStorage`, tetapi consumer dapat memakai `persist: false` untuk override sementara.                                                           |
+| `setType`             | `(type: LayoutType, options?: { persist?: boolean }) => void`             | Menulis type ke signal. Secara default juga menulis `localStorage`, tetapi consumer dapat memakai `persist: false` untuk override sementara.                                                              |
+| `setAppearance`       | `(appearance: LayoutAppearance, options?: { persist?: boolean }) => void` | Menulis appearance ke signal. Secara default juga menulis `layout-appearance`, tetapi consumer dapat memakai `persist: false` untuk override sementara.                                                   |
+| `setWidth`            | `(width: LayoutWidth, options?: { persist?: boolean }) => void`           | Menulis width ke signal. Secara default juga menulis `localStorage`, tetapi consumer dapat memakai `persist: false` untuk override sementara.                                                             |
+| `getStoredSurface`    | `() => LayoutSurface`                                                     | Membaca surface yang valid dari storage atau default.                                                                                                                                                     |
+| `getStoredType`       | `() => LayoutType`                                                        | Membaca type yang valid dari storage atau default.                                                                                                                                                        |
+| `getStoredAppearance` | `() => LayoutAppearance`                                                  | Membaca appearance yang valid dari storage atau default.                                                                                                                                                  |
+| `getStoredWidth`      | `() => LayoutWidth`                                                       | 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.
+- Manual template input pada `Layout` dan variant layout yang dirender consumer hanya mengubah state aktif; keduanya tidak lagi menulis `localStorage`.
+- Method `registerSurface(...)`, `registerType(...)`, `registerAppearance(...)`, dan `registerWidth(...)` tetap tersedia bila consumer memang perlu registrasi yang lebih granular.
+- Aman untuk SSR karena hanya mengakses `localStorage` saat runtime browser tersedia.
+
+Contoh penggunaan:
+
+```ts
+import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
+import { LayoutService } from '@ojiepermana/angular/theme/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 `@ojiepermana/angular/theme/layout/types`.
+
+### Types
+
+| Symbol               | Nilai                                                                                              |
+| -------------------- | -------------------------------------------------------------------------------------------------- |
+| `LayoutType`         | `vertical`, `horizontal`, `empty`, `fluid`                                                         |
+| `LayoutSurface`      | `flat`, `grid`, `grid-line`, `honeycomb`, `matrix`, `circuit`, `line-vertical`, `line-horizontal`  |
+| `LayoutAppearance`   | `flat`, `border-rail`                                                                              |
+| `LayoutWidth`        | `full`, `wide`, `container`, `fluid`                                                               |
+| `LayoutContextValue` | Objekt berbentuk `{ surface, type, appearance, width }` yang masing-masing berupa readonly signal. |
+
+### Constants
+
+| Symbol                          | Nilai                                                                                                 |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `LAYOUT_TYPES`                  | `['vertical', 'horizontal', 'empty', 'fluid']`                                                        |
+| `LAYOUT_SURFACES`               | `['flat', 'grid', 'grid-line', 'honeycomb', 'matrix', 'circuit', 'line-vertical', 'line-horizontal']` |
+| `LAYOUT_APPEARANCES`            | `['flat', 'border-rail']`                                                                             |
+| `LAYOUT_WIDTHS`                 | `['full', 'wide', 'container', 'fluid']`                                                              |
+| `LAYOUT_DEFAULT_SURFACE`        | `'flat'`                                                                                              |
+| `LAYOUT_DEFAULT_TYPE`           | `'vertical'`                                                                                          |
+| `LAYOUT_DEFAULT_APPEARANCE`     | `'flat'`                                                                                              |
+| `LAYOUT_DEFAULT_WIDTH`          | `'full'`                                                                                              |
+| `LAYOUT_SURFACE_STORAGE_KEY`    | `'layout-surface'`                                                                                    |
+| `LAYOUT_APPEARANCE_STORAGE_KEY` | `'layout-appearance'`                                                                                 |
+| `LAYOUT_TYPE_STORAGE_KEY`       | `'layout-type'`                                                                                       |
+| `LAYOUT_WIDTH_STORAGE_KEY`      | `'layout-width'`                                                                                      |
+
+### Guards
+
+- `isUiLayoutSurface(value: string | null): value is LayoutSurface`
+  Memvalidasi string terhadap daftar surface yang didukung.
+- `isUiLayoutType(value: string | null): value is LayoutType`
+  Memvalidasi string terhadap daftar type yang didukung.
+- `isUiLayoutAppearance(value: string | null): value is LayoutAppearance`
+  Memvalidasi string terhadap daftar style yang didukung.
+- `isUiLayoutWidth(value: string | null): value is LayoutWidth`
+  Memvalidasi string terhadap daftar width yang didukung.
+
+## Consumer guidance
+
+- Gunakan `appearance` atau alias `layout-appearance` di template (kosakata sama dengan `nav-appearance` pada navigation).
+- 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 `Layout` ke `layout.surface()`, `layout.appearance()`, dan `layout.width()`.
+- Tempatkan scroll page utama di `LayoutContent`, bukan di root `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.