@ojiepermana/angular 22.1.11 → 22.1.12

package/theme/page/README.md

@@ -0,0 +1,453 @@
+# @ojiepermana/angular/theme/page
+
+Primitive page shell untuk layout halaman dengan pendekatan nested component.
+
+Dokumentasi ini mengikuti API publik terbaru dari `@ojiepermana/angular/theme/page`, termasuk mode `height`, slot `PageDashboard`, controlled side state, dan override untuk side rail.
+
+## Entry points
+
+Barrel kompatibilitas `@ojiepermana/angular/theme/page` tetap mengekspor seluruh API lama.
+Untuk bundle yang lebih terarah, gunakan secondary entrypoint berikut:
+
+```ts
+import { PageStateService, type PageVariant } from '@ojiepermana/angular/theme/page/core';
+import { PageComponent } from '@ojiepermana/angular/theme/page/root';
+import { PageHeaderComponent, PageContentComponent } from '@ojiepermana/angular/theme/page/slots';
+import {
+  PageFilterComponent,
+  PageFilterToggleComponent,
+} from '@ojiepermana/angular/theme/page/filter';
+import { PageSideComponent, PageSideToggleComponent } from '@ojiepermana/angular/theme/page/side';
+```
+
+Semua entrypoint bersifat additive; import lama dari `/page` tetap valid.
+
+## Components
+
+- `Page`
+- `PageHeader`
+- `PageContent`
+- `PageDashboard`
+- `PageFooter`
+- `PageSide`
+- `PageSideToggle`
+- `PageFilter`
+- `PageFilterToggle`
+
+`PageSideToggle` menerima projected content untuk label atau ikon kustom. Jika tidak ada projected content, komponen akan memakai ikon fallback bawaan.
+`PageHeader` dan `PageFooter` memakai `--section-border-opacity`, token separator yang sama dengan header/footer Navigation, sehingga garis section konsisten tanpa mengubah border frame utama Layout.
+`PageDashboard` mengikuti perilaku layout dan scroll yang sama dengan `PageContent`, tetapi disediakan sebagai slot semantik untuk dashboard, board, dan surface analitik.
+`PageFilter` adalah slot filter yang bisa diletakkan **stacked** (bar di antara `PageHeader` dan `PageContent`) atau **side** (kolom di samping `PageContent`). `PageFilterToggle` mengontrol `PageFilter` saat memakai mode `drawer`/`overlay`.
+
+## Root API
+
+### `Page`
+
+| Input               | Type                                | Default                 | Keterangan                                                                                                          |
+| ------------------- | ----------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `variant`           | `'stacked' \| 'side'`               | `'stacked'`             | Menentukan struktur utama page shell.                                                                               |
+| `scroll`            | `'content' \| 'page'`               | `'content'`             | Menentukan apakah body slot scroll sendiri atau seluruh root `Page` scroll bersama.                                 |
+| `height`            | `'auto' \| 'fix'`                   | `'auto'`                | Mengontrol tinggi `PageHeader` dan `PageFooter`.                                                                    |
+| `appearance`        | `'flat' \| 'border-rail'`           | `'flat'`                | Appearance visual yang dibagi dengan layout/navigation; menyeragamkan border header/footer (`border-b`/`border-t`). |
+| `position`          | `'left' \| 'right'`                 | `'left'`                | Posisi default untuk `PageSide` jika side tidak memberi override sendiri.                                           |
+| `sideMode`          | `'sticky' \| 'drawer' \| 'overlay'` | `'sticky'`              | Mode default untuk `PageSide` jika side tidak memberi override sendiri.                                             |
+| `sideWidth`         | `string`                            | `'16rem'`               | Lebar default side rail; dipakai juga untuk drawer dan overlay.                                                     |
+| `sideOpen`          | `boolean \| null`                   | `null`                  | Saat `null`, state side tidak dikontrol dari parent. Saat `true/false`, komponen masuk controlled mode.             |
+| `filterOpen`        | `boolean \| null`                   | `null`                  | Controlled state untuk `PageFilter` drawer/overlay. `null` = uncontrolled (dikelola toggle/backdrop/Esc).           |
+| `overlayCloseLabel` | `string`                            | `'Close overlay panel'` | Accessible name for the backdrop button that dismisses an open overlay panel.                                       |
+| `class`             | `string`                            | `''`                    | Class tambahan pada host `Page`.                                                                                    |
+
+| Output             | Payload   | Keterangan                                                                                        |
+| ------------------ | --------- | ------------------------------------------------------------------------------------------------- |
+| `sideOpenChange`   | `boolean` | Emit setiap ada permintaan buka/tutup side, baik dari toggle, backdrop, maupun tombol `Esc`.      |
+| `filterOpenChange` | `boolean` | Emit setiap ada permintaan buka/tutup filter (drawer/overlay), baik dari toggle, backdrop, `Esc`. |
+
+`Page` juga menambahkan atribut host `data-page-variant`, `data-page-height`, `data-page-scroll`, `data-page-appearance`, `data-page-position`, `data-page-side-mode`, dan `data-page-side-open` untuk styling atau inspeksi. Saat `PageFilter` aktif, ditambahkan pula `data-page-filter-placement`, `data-page-filter-mode`, dan `data-page-filter-open`.
+
+### Apps launcher (layout `empty`)
+
+Saat `Page` dirender di dalam layout `empty`, sebuah tombol icon-only tanpa border (ikon `apps`) muncul **otomatis** di pojok kanan-atas dan membuka **main navigation** (`id="main"`) sebagai flyout. Penempatannya menyesuaikan struktur `Page`:
+
+- Ada `PageHeader` → tombol menyatu di kanan header.
+- Tanpa `PageHeader` (mis. hanya `PageDashboard`) → tombol mengambang di atas konten.
+
+Tombol hanya muncul ketika layout aktif `empty` dan nav target punya data. Di layout lain (`vertical`/`horizontal`/`fluid`) tombol tidak dirender karena navigasi utama sudah terlihat.
+
+| Input          | Type      | Default             | Keterangan                                                   |
+| -------------- | --------- | ------------------- | ------------------------------------------------------------ |
+| `appsLauncher` | `boolean` | `true`              | Aktif/nonaktifkan apps-launcher pada layout `empty`.         |
+| `appsNavId`    | `string`  | `'main'`            | Id navigasi yang disurface oleh apps-launcher.               |
+| `appsIcon`     | `string`  | `'apps'`            | Nama ikon Material untuk tombol.                             |
+| `appsLabel`    | `string`  | `'Open navigation'` | Label/aria-label tombol icon-only (untuk aksesibilitas AXE). |
+
+```html
+<!-- Dashboard tanpa header: tombol apps mengambang di kanan-atas saat layout empty. -->
+<Page variant="stacked">
+  <PageDashboard>
+    <p>Konten dashboard.</p>
+  </PageDashboard>
+</Page>
+```
+
+## Slot API
+
+### Body slots
+
+| Component       | Input           | Default | Keterangan                                                                             |
+| --------------- | --------------- | ------- | -------------------------------------------------------------------------------------- |
+| `PageHeader`    | `class: string` | `''`    | Slot header dengan border bawah. Saat `height="fix"`, tinggi dipaksa `h-12`.           |
+| `PageContent`   | `class: string` | `''`    | Body slot utama. Mengikuti mode `scroll` dari root `Page`.                             |
+| `PageDashboard` | `class: string` | `''`    | Setara dengan `PageContent`, tetapi untuk kebutuhan dashboard/board/analytics surface. |
+| `PageFooter`    | `class: string` | `''`    | Slot footer dengan border atas. Saat `height="fix"`, tinggi dipaksa `h-12`.            |
+
+### `PageSide`
+
+| Input        | Type                                        | Default        | Keterangan                                                                                             |
+| ------------ | ------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------ |
+| `mode`       | `'sticky' \| 'drawer' \| 'overlay' \| null` | `null`         | Override mode side untuk instance tersebut. Jika `null`, memakai `sideMode` dari root `Page`.          |
+| `position`   | `'left' \| 'right' \| null`                 | `null`         | Override posisi side untuk instance tersebut. Jika `null`, memakai nilai dari root `Page`.             |
+| `width`      | `string \| null`                            | `null`         | Override lebar side untuk instance tersebut. Jika `null`, memakai `sideWidth` dari root `Page`.        |
+| `closeOnEsc` | `boolean`                                   | `true`         | Berlaku untuk `drawer` dan `overlay`; menutup side ketika tombol `Esc` ditekan.                        |
+| `ariaLabel`  | `string`                                    | `'Side panel'` | Nama aksesibilitas panel saat `drawer`/`overlay` (dipasang sebagai `aria-label` pada `role="dialog"`). |
+| `class`      | `string`                                    | `''`           | Class tambahan pada host `PageSide`.                                                                   |
+
+### `PageSideToggle`
+
+| Input / Output | Type      | Default              | Keterangan                                                  |
+| -------------- | --------- | -------------------- | ----------------------------------------------------------- |
+| `ariaLabel`    | `string`  | `'Toggle page side'` | Label aksesibilitas untuk tombol toggle.                    |
+| `class`        | `string`  | `''`                 | Class tambahan pada host toggle.                            |
+| `toggled`      | `boolean` | -                    | Emit nilai open state terbaru setelah tombol toggle diklik. |
+
+### `PageFilter`
+
+| Input         | Type                                | Default     | Keterangan                                                                                                              |
+| ------------- | ----------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `placement`   | `'stacked' \| 'side'`               | `'stacked'` | `stacked` = bar di antara `PageHeader` dan `PageContent`; `side` = kolom di samping `PageContent`.                      |
+| `mode`        | `'sticky' \| 'drawer' \| 'overlay'` | `'sticky'`  | Hanya berlaku untuk `placement="side"`. `placement="stacked"` selalu `sticky`.                                          |
+| `position`    | `'left' \| 'right' \| null`         | `null`      | Posisi kolom saat `side`. Jika `null`, memakai default (`left`).                                                        |
+| `width`       | `string \| null`                    | `null`      | Lebar kolom saat `side`. Jika `null`, memakai `18rem`.                                                                  |
+| `closeOnEsc`  | `boolean`                           | `true`      | Berlaku untuk `drawer`/`overlay`; menutup filter ketika tombol `Esc` ditekan.                                           |
+| `collapsible` | `boolean`                           | `false`     | Khusus `placement="stacked"`: bar bisa dibuka/tutup lewat `PageFilterToggle`, default tertutup. Diabaikan untuk `side`. |
+| `ariaLabel`   | `string`                            | `'Filters'` | Nama aksesibilitas panel saat `drawer`/`overlay` (dipasang sebagai `aria-label` pada `role="dialog"`).                  |
+| `class`       | `string`                            | `''`        | Class tambahan pada host `PageFilter`.                                                                                  |
+
+`PageFilter` menambahkan atribut host `data-page-slot="filter"`, `data-page-filter-placement`, `data-page-filter-mode`, `data-page-filter-open`, dan `data-page-position`.
+
+Aksesibilitas: pada mode `drawer`/`overlay`, panel menjadi `role="dialog"` (dengan `aria-modal`
+khusus `overlay`), fokus dipindahkan ke panel saat terbuka dan dikembalikan ke pemicu saat
+tertutup, dan saat tertutup panel diberi `inert` sehingga isinya keluar dari tab order.
+`overlay` juga men-trap fokus, membuat background Page inert, dan mengunci scroll document;
+`drawer` sengaja tetap non-modal. `PageSide` memakai pola yang sama. Menekan `Esc` (atau
+mengklik backdrop overlay) menutup panel mengambang yang sedang terbuka.
+
+### `PageFilterToggle`
+
+| Input / Output | Type      | Default                | Keterangan                                                  |
+| -------------- | --------- | ---------------------- | ----------------------------------------------------------- |
+| `ariaLabel`    | `string`  | `'Toggle page filter'` | Label aksesibilitas untuk tombol toggle filter.             |
+| `class`        | `string`  | `''`                   | Class tambahan pada host toggle.                            |
+| `toggled`      | `boolean` | -                      | Emit nilai open state terbaru setelah tombol toggle diklik. |
+
+## Variants
+
+- `stacked`
+- `side`
+
+## Scroll Modes
+
+- `content` (default): `PageContent` atau `PageDashboard` menjadi area scroll. Pada variant `side`, `PageSide` dan body slot yang dipakai sama-sama stretch ke parent dan masing-masing punya scroll sendiri.
+- `page`: seluruh isi `Page` menjadi area scroll. Header, content, footer, dan pada variant `side` juga `PageSide` akan mengikuti tinggi content induk tanpa scroll internal.
+
+## Height Modes
+
+- `auto` (default): tinggi `PageHeader` dan `PageFooter` mengikuti isi.
+- `fix`: `PageHeader` dan `PageFooter` dipaksa `h-12` dan `overflow-hidden`, sehingga isi yang melebihi tinggi tersebut akan terpotong.
+
+Dalam mode `fix`, pastikan isi header/footer memang dirancang sebagai rail ringkas. Konten yang lebih tinggi dari `h-12` tidak akan ikut menambah tinggi slot.
+
+## Behavior Summary
+
+| Variant   | `scroll="content"`                                                                                            | `scroll="page"`                                                               |
+| --------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `stacked` | `PageContent` atau `PageDashboard` stretch ke tinggi yang tersedia dan menjadi area scroll                    | seluruh `Page` scroll bersama; header, content, footer ikut satu kanvas       |
+| `side`    | `PageSide` dan body slot (`PageContent`/`PageDashboard`) sama-sama stretch ke parent dan punya scroll sendiri | `PageSide` dan body slot mengikuti tinggi content induk tanpa scroll internal |
+
+## Header And Footer Height
+
+Saat memakai `height="fix"`, slot berikut tidak boleh melebihi tinggi tetap yang disediakan:
+
+- `PageHeader`: `h-12` dengan `overflow-hidden`
+- `PageFooter`: `h-12` dengan `overflow-hidden`
+
+## Side Modes
+
+- `sticky`
+- `drawer`
+- `overlay`
+
+## Filter Placement
+
+`PageFilter` punya dua placement yang orthogonal terhadap `variant` `Page`:
+
+- `stacked` (default): filter menjadi bar selebar content di antara `PageHeader` dan `PageContent`. Filter mendorong content ke bawah; pada `scroll="content"`, content mengisi tinggi sisa dan scroll sendiri (filter `shrink-0`). Pada `scroll="page"`, bar dipin (`sticky top-0`) agar tetap terjangkau saat page scroll.
+- `side`: filter menjadi kolom di samping content. Mode `sticky` mendorong content ke samping (push); mode `drawer`/`overlay` mengambang di atas content dan dikontrol via `PageFilterToggle`, backdrop, atau tombol `Esc`.
+
+Karena independen dari `variant`, side filter bisa hidup berdampingan dengan `PageSide` — `PageSide` tetap menjadi rail terluar dan `PageFilter` menjadi kolom yang lebih dekat ke content (`[PageSide | PageFilter | PageContent]`).
+
+## Examples
+
+### Stacked with content scroll
+
+```html
+<Page variant="stacked">
+  <PageHeader>
+    <h1>Executive summary</h1>
+  </PageHeader>
+
+  <PageContent>
+    <p>Secara default, slot content yang menjadi area scroll.</p>
+  </PageContent>
+
+  <PageFooter>
+    <button type="button">Save</button>
+  </PageFooter>
+</Page>
+```
+
+### Stacked dashboard surface
+
+`PageDashboard` berdiri sendiri — tidak memerlukan `PageHeader` maupun `PageFooter`. Gunakan slot ini ketika area utama secara semantik adalah dashboard atau board analitik.
+
+```html
+<Page variant="stacked">
+  <PageDashboard>
+    <p>Gunakan slot ini ketika area utama secara semantik adalah dashboard atau board analitik.</p>
+  </PageDashboard>
+</Page>
+```
+
+`PageHeader` dan `PageFooter` tetap opsional bila memang dibutuhkan:
+
+```html
+<Page variant="stacked">
+  <PageHeader>
+    <h1>Executive dashboard</h1>
+  </PageHeader>
+
+  <PageDashboard>
+    <p>Dashboard dengan header dan footer eksplisit.</p>
+  </PageDashboard>
+
+  <PageFooter>
+    <button type="button">Open insight</button>
+  </PageFooter>
+</Page>
+```
+
+### Stacked with fixed header and footer height
+
+```html
+<Page variant="stacked" height="fix">
+  <PageHeader>
+    <div class="h-20">Bagian ini akan terpotong ke tinggi h-12.</div>
+  </PageHeader>
+
+  <PageContent>
+    <p>Content tetap mengikuti mode scroll yang aktif.</p>
+  </PageContent>
+
+  <PageFooter>
+    <div class="h-20">Footer juga tidak boleh melebihi h-12.</div>
+  </PageFooter>
+</Page>
+```
+
+### Stacked with page scroll
+
+```html
+<Page variant="stacked" scroll="page">
+  <PageHeader>
+    <h1>Executive summary</h1>
+  </PageHeader>
+
+  <PageContent>
+    <p>Semua area di dalam page ikut scroll bersama.</p>
+  </PageContent>
+
+  <PageFooter>
+    <button type="button">Save</button>
+  </PageFooter>
+</Page>
+```
+
+### Side with content scroll
+
+```html
+<Page variant="side" position="left" scroll="content">
+  <PageHeader>
+    <PageSideToggle ariaLabel="Toggle side">
+      <span>Open filters</span>
+    </PageSideToggle>
+    <h1>Page title</h1>
+  </PageHeader>
+
+  <PageSide mode="sticky">
+    <p>Side rail scroll sendiri.</p>
+  </PageSide>
+
+  <PageContent>
+    <p>Main content juga scroll sendiri.</p>
+  </PageContent>
+</Page>
+```
+
+### Side with page scroll
+
+```html
+<Page variant="side" position="left" scroll="page">
+  <PageHeader>
+    <h1>Executive detail</h1>
+  </PageHeader>
+
+  <PageSide mode="sticky">
+    <p>Side mengikuti tinggi content induk.</p>
+  </PageSide>
+
+  <PageContent>
+    <p>Root `Page` yang menjadi area scroll tunggal.</p>
+  </PageContent>
+</Page>
+```
+
+### Controlled side state
+
+```html
+<Page
+  variant="side"
+  sideMode="drawer"
+  [sideOpen]="filtersOpen()"
+  (sideOpenChange)="filtersOpen.set($event)"
+>
+  <PageHeader>
+    <PageSideToggle ariaLabel="Toggle filters">
+      <span>Filters</span>
+    </PageSideToggle>
+    <h1>Pipeline board</h1>
+  </PageHeader>
+
+  <PageSide>
+    <p>Drawer ini mengikuti state dari parent.</p>
+  </PageSide>
+
+  <PageDashboard>
+    <p>Dashboard tetap memakai body behavior yang sama seperti page-content.</p>
+  </PageDashboard>
+</Page>
+```
+
+### Stacked filter (bar antara header dan content)
+
+```html
+<Page variant="stacked">
+  <PageHeader>
+    <h1>Orders</h1>
+  </PageHeader>
+
+  <PageFilter placement="stacked">
+    <input type="search" aria-label="Cari order" placeholder="Cari…" />
+    <button type="button">Status</button>
+    <button type="button">Tanggal</button>
+  </PageFilter>
+
+  <PageContent>
+    <p>Content mengisi tinggi sisa dan scroll sendiri di bawah bar filter.</p>
+  </PageContent>
+</Page>
+```
+
+### Collapsible stacked filter
+
+```html
+<Page variant="stacked">
+  <PageHeader>
+    <PageFilterToggle ariaLabel="Toggle filters">
+      <span>Filters</span>
+    </PageFilterToggle>
+    <h1>Orders</h1>
+  </PageHeader>
+
+  <!-- Default tertutup; toggle membuka/menutup bar. -->
+  <PageFilter placement="stacked" collapsible>
+    <input type="search" aria-label="Cari order" placeholder="Cari…" />
+    <button type="button">Status</button>
+  </PageFilter>
+
+  <PageContent>
+    <p>Saat filter tertutup, content mengisi kembali ruang bar.</p>
+  </PageContent>
+</Page>
+```
+
+### Side filter (sticky push)
+
+```html
+<Page variant="stacked">
+  <PageHeader>
+    <h1>Catalog</h1>
+  </PageHeader>
+
+  <PageFilter placement="side" mode="sticky" position="left" width="18rem">
+    <p>Facet filter; mendorong content ke samping.</p>
+  </PageFilter>
+
+  <PageContent>
+    <p>Hasil produk.</p>
+  </PageContent>
+</Page>
+```
+
+### Side filter (controlled drawer)
+
+```html
+<Page [filterOpen]="filterOpen()" (filterOpenChange)="filterOpen.set($event)">
+  <PageHeader>
+    <PageFilterToggle ariaLabel="Toggle filter">
+      <span>Filter</span>
+    </PageFilterToggle>
+    <h1>Catalog</h1>
+  </PageHeader>
+
+  <PageFilter placement="side" mode="drawer" position="right">
+    <p>Drawer filter mengikuti state dari parent.</p>
+  </PageFilter>
+
+  <PageContent>
+    <p>Hasil produk.</p>
+  </PageContent>
+</Page>
+```
+
+### Filter dan side rail berdampingan
+
+`PageSide` (rail terluar) dan `PageFilter` (`placement="side"`) bisa aktif bersamaan: `[PageSide | PageFilter | PageContent]`.
+
+```html
+<Page variant="side" position="left">
+  <PageHeader>
+    <h1>Workspace</h1>
+  </PageHeader>
+
+  <PageSide mode="sticky">
+    <p>Navigasi.</p>
+  </PageSide>
+
+  <PageFilter placement="side" position="left">
+    <p>Filter.</p>
+  </PageFilter>
+
+  <PageContent>
+    <p>Content.</p>
+  </PageContent>
+</Page>
+```