@ojiepermana/angular-theme 22.0.27

package/layout/README.md

@@ -0,0 +1,471 @@
+# @ojiepermana/angular-theme/layout
+
+Primitive layout projection untuk menyusun shell UI dengan satu root `Layout`, satu variant layout (`vertical`, `horizontal`, `empty`, atau `fluid`), slot `layout-nav`, 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 LayoutStyle,
+  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_STYLE,
+  LAYOUT_DEFAULT_SURFACE,
+  LAYOUT_DEFAULT_TYPE,
+  LAYOUT_DEFAULT_WIDTH,
+  LAYOUT_APPEARANCE_STORAGE_KEY,
+  LAYOUT_STYLES,
+  LAYOUT_SURFACE_STORAGE_KEY,
+  LAYOUT_STYLE_STORAGE_KEY,
+  LAYOUT_SURFACES,
+  LAYOUT_TYPES,
+  LAYOUT_TYPE_STORAGE_KEY,
+  LAYOUT_WIDTHS,
+  LAYOUT_WIDTH_STORAGE_KEY,
+  isUiLayoutSurface,
+  isUiLayoutStyle,
+  isUiLayoutType,
+  isUiLayoutWidth,
+  type LayoutContextValue,
+  type LayoutStyle,
+  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 | layout-horizontal | layout-empty | layout-fluid>
+    <LayoutNavigation>...</LayoutNavigation>
+    <LayoutContent>...</LayoutContent>
+  </layout-vertical | layout-horizontal | layout-empty | layout-fluid>
+</Layout>
+```
+
+Aturan penggunaannya:
+
+- Gunakan tepat satu variant layout di dalam `Layout`.
+- Untuk layout `vertical` dan `horizontal`, urutan child yang umum adalah `layout-nav` 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`   | `LayoutStyle 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` | `LayoutStyle or null` | `null`   | Alias kompatibilitas untuk template lama. Tetap dibaca sebagai fallback, tetapi API yang direkomendasikan adalah `appearance`.                                       |
+| `width`        | `LayoutWidth`         | `'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 `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-style`, `data-layout-width`, dan `data-layout-type`.
+- Root tidak menyediakan input `type`. Type aktif dikendalikan oleh variant layout yang dirender sebagai override in-memory, 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.
+- `layout-nav` akan tersembunyi jika tetap dirender di mode ini.
+
+### `LayoutNavigationComponent`
+
+Wrapper untuk slot navigasi.
+
+Selector: `layout-nav`
+
+Inputs:
+
+| Input       | Type     | Default               | Deskripsi                                        |
+| ----------- | -------- | --------------------- | ------------------------------------------------ |
+| `ariaLabel` | `string` | `'Layout navigation'` | Label aksesibilitas untuk landmark `navigation`. |
+| `class`     | `string` | `''`                  | Menambahkan class pada host `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 `layout-nav`, 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`. |
+
+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 `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 `LAYOUT_STYLES`.
+
+| 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` 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 `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<LayoutStyle>`   | Appearance layout aktif.                            |
+| `style`      | `Signal<LayoutStyle>`   | Alias kompatibilitas untuk 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: LayoutStyle) => 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: LayoutStyle) => void`                                       | Alias kompatibilitas untuk `registerAppearance(...)`.                                                                                                                                                     |
+| `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: LayoutStyle, options?: { persist?: boolean }) => void` | Menulis appearance ke signal. Secara default juga menulis `layout-appearance`, tetapi consumer dapat memakai `persist: false` untuk override sementara.                                                   |
+| `setStyle`            | `(style: LayoutStyle, options?: { persist?: boolean }) => void`      | Alias kompatibilitas untuk `setAppearance(...)`, termasuk opsi `persist`.                                                                                                                                 |
+| `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` | `() => LayoutStyle`                                                  | Membaca appearance yang valid dari storage atau default.                                                                                                                                                  |
+| `getStoredStyle`      | `() => LayoutStyle`                                                  | Alias kompatibilitas untuk `getStoredAppearance()`.                                                                                                                                                       |
+| `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.
+- 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 '@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`, `honeycome`, `line-vertical`, `line-horizontal`                                           |
+| `LayoutStyle`        | `flat`, `border-rail`                                                                                     |
+| `LayoutWidth`        | `full`, `wide`, `container`, `fluid`                                                                      |
+| `LayoutContextValue` | Objekt berbentuk `{ surface, type, appearance, style, width }` yang masing-masing berupa readonly signal. |
+
+### Constants
+
+| Symbol                          | Nilai                                                               |
+| ------------------------------- | ------------------------------------------------------------------- |
+| `LAYOUT_TYPES`                  | `['vertical', 'horizontal', 'empty', 'fluid']`                      |
+| `LAYOUT_SURFACES`               | `['flat', 'grid', 'honeycome', 'line-vertical', 'line-horizontal']` |
+| `LAYOUT_STYLES`                 | `['flat', 'border-rail']`                                           |
+| `LAYOUT_WIDTHS`                 | `['full', 'wide', 'container', 'fluid']`                            |
+| `LAYOUT_DEFAULT_SURFACE`        | `'flat'`                                                            |
+| `LAYOUT_DEFAULT_TYPE`           | `'vertical'`                                                        |
+| `LAYOUT_DEFAULT_STYLE`          | `'flat'`                                                            |
+| `LAYOUT_DEFAULT_WIDTH`          | `'full'`                                                            |
+| `LAYOUT_SURFACE_STORAGE_KEY`    | `'layout-surface'`                                                  |
+| `LAYOUT_APPEARANCE_STORAGE_KEY` | `'layout-appearance'`                                               |
+| `LAYOUT_TYPE_STORAGE_KEY`       | `'layout-type'`                                                     |
+| `LAYOUT_STYLE_STORAGE_KEY`      | `'layout-style'` `(legacy compatibility key)`                       |
+| `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.
+- `isUiLayoutStyle(value: string | null): value is LayoutStyle`
+  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` 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 `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.

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@ojiepermana/angular-theme",
+  "version": "22.0.27",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/edsis/angular.git"
+  },
+  "homepage": "https://github.com/edsis/angular#readme",
+  "bugs": {
+    "url": "https://github.com/edsis/angular/issues"
+  },
+  "peerDependencies": {
+    "@angular/common": ">=22.0.0",
+    "@angular/core": ">=22.0.0",
+    "@angular/router": ">=22.0.0",
+    "@ojiepermana/angular-navigation": "^22.0.27",
+    "@ojiepermana/angular-component": "^22.0.27",
+    "rxjs": ">=7.8.0"
+  },
+  "dependencies": {
+    "tslib": "^2.8.1"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "sideEffects": false,
+  "module": "fesm2022/ojiepermana-angular-theme.mjs",
+  "typings": "types/ojiepermana-angular-theme.d.ts",
+  "exports": {
+    "./package.json": {
+      "default": "./package.json"
+    },
+    ".": {
+      "types": "./types/ojiepermana-angular-theme.d.ts",
+      "default": "./fesm2022/ojiepermana-angular-theme.mjs"
+    },
+    "./layout": {
+      "types": "./types/ojiepermana-angular-theme-layout.d.ts",
+      "default": "./fesm2022/ojiepermana-angular-theme-layout.mjs"
+    },
+    "./layout/services": {
+      "types": "./types/ojiepermana-angular-theme-layout-services.d.ts",
+      "default": "./fesm2022/ojiepermana-angular-theme-layout-services.mjs"
+    },
+    "./layout/types": {
+      "types": "./types/ojiepermana-angular-theme-layout-types.d.ts",
+      "default": "./fesm2022/ojiepermana-angular-theme-layout-types.mjs"
+    },
+    "./page": {
+      "types": "./types/ojiepermana-angular-theme-page.d.ts",
+      "default": "./fesm2022/ojiepermana-angular-theme-page.mjs"
+    },
+    "./styles": {
+      "types": "./types/ojiepermana-angular-theme-styles.d.ts",
+      "default": "./fesm2022/ojiepermana-angular-theme-styles.mjs"
+    }
+  },
+  "type": "module"
+}