@ojiepermana/angular-theme 22.0.27

package/page/README.md

@@ -0,0 +1,239 @@
+# @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.
+
+## Components
+
+- `Page`
+- `PageHeader`
+- `PageContent`
+- `PageDashboard`
+- `PageFooter`
+- `PageSide`
+- `PageSideToggle`
+
+`PageSideToggle` menerima projected content untuk label atau ikon kustom. Jika tidak ada projected content, komponen akan memakai ikon fallback bawaan.
+`PageDashboard` mengikuti perilaku layout dan scroll yang sama dengan `PageContent`, tetapi disediakan sebagai slot semantik untuk dashboard, board, dan surface analitik.
+
+## 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`.                                                        |
+| `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. |
+| `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`. |
+
+`Page` juga menambahkan atribut host `data-page-variant`, `data-page-height`, `data-page-scroll`, `data-page-position`, `data-page-side-mode`, dan `data-page-side-open` untuk styling atau inspeksi.
+
+## 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'` | `'sticky'` | Override mode side untuk instance tersebut.                                                     |
+| `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.                 |
+| `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. |
+
+## 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`
+
+## 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
+
+```html
+<Page variant="stacked">
+  <PageHeader>
+    <h1>Executive dashboard</h1>
+  </PageHeader>
+
+  <PageDashboard>
+    <p>Gunakan slot ini ketika area utama secara semantik adalah dashboard atau board analitik.</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>
+```

package/styles/README.md

@@ -0,0 +1,28 @@
+# Theme
+
+`@ojiepermana/angular-theme/styles` menyediakan provider untuk mode, season, dan preload aset tema global.
+
+```ts
+import { provideUiTheme } from '@ojiepermana/angular-theme/styles';
+
+export const appConfig = {
+  providers: [
+    provideUiTheme({
+      mode: 'light',
+      season: 'base',
+    }),
+  ],
+};
+```
+
+## API Notes
+
+- `mode` mem-bootstrap `ThemeModeService` dan default mode yang disimpan di storage.
+- `season` mem-bootstrap `ThemeSeasonService` dan default season yang disimpan di storage.
+- `icons.materialSymbols` mengontrol preload stylesheet Material Symbols pada bootstrap aplikasi.
+
+## Default Behavior
+
+- Material Symbols di-preload secara default saat `provideUiTheme()` dijalankan.
+- Untuk menonaktifkan preload global, set `icons.materialSymbols` ke `false`.
+- Komponen dari `@ojiepermana/angular-component/icon` tetap punya fallback lazy-load bila provider tema tidak dipakai.

package/styles/css/index.css

@@ -0,0 +1,9 @@
+/*
+ * Default theme stylesheet: base tokens/components only.
+ *
+ * CSS musiman TIDAK lagi di-bundle di sini (±36 kB). Musim aktif dimuat
+ * runtime oleh ThemeSeasonService bila `seasonalCssUrl` dikonfigurasi pada
+ * provideUiTheme(), atau impor manual './seasonal/<season>/package.css'
+ * (semua musim sekaligus: './seasonal/index.css').
+ */
+@import './seasonal/base/package.css';

package/styles/css/seasonal/base/components.css

@@ -0,0 +1,129 @@
+/**
+ * Global component-facing styles that should react to the active theme.
+ */
+@layer base {
+  * {
+    border-color: hsl(var(--border));
+    outline-color: hsl(var(--ring) / var(--opacity-50));
+  }
+
+  html,
+  body {
+    min-height: 100%;
+  }
+
+  html {
+    background: hsl(var(--background));
+  }
+
+  body {
+    background: hsl(var(--background));
+    color: hsl(var(--foreground));
+    font-family: var(--font-sans);
+    font-size: var(--text-base);
+    line-height: var(--text-base--line-height);
+    letter-spacing: var(--letter-spacing);
+    transition:
+      background-color var(--duration-normal) var(--ease-standard),
+      color var(--duration-normal) var(--ease-standard),
+      border-color var(--duration-normal) var(--ease-standard),
+      box-shadow var(--duration-normal) var(--ease-standard),
+      outline-color var(--duration-normal) var(--ease-standard);
+  }
+
+  button,
+  input,
+  select,
+  textarea {
+    font: inherit;
+  }
+
+  html,
+  body,
+  * {
+    scrollbar-width: thin;
+    scrollbar-color: hsl(var(--scrollbar-thumb)) hsl(var(--scrollbar-track));
+  }
+
+  *::-webkit-scrollbar {
+    width: var(--scrollbar-size);
+    height: var(--scrollbar-size);
+  }
+
+  *::-webkit-scrollbar-track {
+    background: hsl(var(--scrollbar-track));
+  }
+
+  *::-webkit-scrollbar-thumb {
+    background: hsl(var(--scrollbar-thumb));
+    border: 2px solid transparent;
+    background-clip: padding-box;
+    border-radius: var(--scrollbar-radius);
+  }
+
+  *::-webkit-scrollbar-thumb:hover {
+    background: hsl(var(--scrollbar-thumb-hover));
+    background-clip: padding-box;
+  }
+
+  ::selection {
+    background: hsl(var(--primary) / var(--opacity-24));
+    color: hsl(var(--foreground));
+  }
+
+  @media (forced-colors: active) {
+    html,
+    body,
+    * {
+      scrollbar-width: auto;
+      scrollbar-color: auto;
+    }
+
+    *::-webkit-scrollbar-thumb {
+      background: CanvasText;
+      border-color: transparent;
+    }
+  }
+}
+
+@layer components {
+  .nav-text {
+    font-family: var(--nav-font-family, var(--font-sans));
+    font-size: var(--nav-text-size, var(--text-base));
+    line-height: var(--nav-text-line-height, var(--text-base--line-height));
+  }
+
+  .nav-hover-surface {
+    @apply relative isolate hover:text-accent-foreground;
+  }
+
+  .nav-hover-surface::before {
+    content: '';
+    border-radius: inherit;
+    @apply pointer-events-none absolute inset-y-0 left-2 right-2 z-0 bg-transparent transition-colors;
+  }
+
+  .nav-hover-surface:hover::before {
+    @apply bg-accent;
+  }
+
+  .nav-hover-surface > * {
+    @apply relative z-10;
+  }
+
+  .nav-heading {
+    font-family: var(--nav-heading-font-family, var(--nav-font-family, var(--font-sans)));
+    font-size: var(--nav-heading-size, var(--text-sm));
+    line-height: var(--nav-heading-line-height, var(--text-sm--line-height));
+    font-weight: var(--nav-heading-weight, 600);
+    letter-spacing: var(--nav-heading-letter-spacing, 0.12em);
+    text-transform: uppercase;
+  }
+
+  .nav-badge {
+    font-family: var(--nav-badge-font-family, var(--nav-font-family, var(--font-sans)));
+    font-size: var(--nav-badge-size, var(--text-sm));
+    line-height: var(--nav-badge-line-height, var(--text-sm--line-height));
+    font-weight: var(--nav-badge-weight, 500);
+  }
+}

package/styles/css/seasonal/base/package.css

@@ -0,0 +1,6 @@
+/**
+ * Internal grouped base theme stylesheet.
+ */
+@import './theme.css';
+@import './tokens.css';
+@import './components.css';

package/styles/css/seasonal/base/tailwind.css

@@ -0,0 +1,144 @@
+/**
+ * Tailwind v4 theme mapping for @ojiepermana/angular-theme/styles.
+ *
+ * Requires Tailwind CSS ^4.3.0.
+ *
+ * Usage (styles.css):
+ *   @import '@ojiepermana/angular-theme/styles/styles';
+ *   @import 'tailwindcss';
+ *   @import '@ojiepermana/angular-theme/styles/tailwind/theme.css';
+ *
+ * Maps the 3-layer HSL CSS variables onto Tailwind v4 design tokens so
+ * utilities like `bg-primary`, `text-foreground`, `rounded-md`, and
+ * `shadow-lg` resolve to the active theme automatically.
+ */
+@custom-variant dark (&:where([data-mode='dark'], [data-mode='dark'] *, .dark, .dark *));
+
+@theme inline {
+  --color-highlight: hsl(var(--highlight) / 0.7);
+  --color-border: hsl(var(--border));
+  --color-input: hsl(var(--input));
+  --color-ring: hsl(var(--ring));
+  --color-background: hsl(var(--background));
+  --color-surface: hsl(var(--surface, var(--muted)));
+  --color-surface-foreground: hsl(var(--surface-foreground, var(--foreground)));
+  --color-foreground: hsl(var(--foreground));
+
+  --color-primary: hsl(var(--primary));
+  --color-primary-foreground: hsl(var(--primary-foreground));
+
+  --color-secondary: hsl(var(--secondary));
+  --color-secondary-foreground: hsl(var(--secondary-foreground));
+
+  --color-destructive: hsl(var(--destructive));
+  --color-destructive-foreground: hsl(var(--destructive-foreground));
+
+  --color-success: hsl(var(--success));
+  --color-success-foreground: hsl(var(--success-foreground));
+
+  --color-warning: hsl(var(--warning));
+  --color-warning-foreground: hsl(var(--warning-foreground));
+
+  --color-info: hsl(var(--info));
+  --color-info-foreground: hsl(var(--info-foreground));
+
+  --color-muted: hsl(var(--muted));
+  --color-muted-foreground: hsl(var(--muted-foreground));
+
+  --color-accent: hsl(var(--accent));
+  --color-accent-foreground: hsl(var(--accent-foreground));
+
+  --color-popover: hsl(var(--popover));
+  --color-popover-foreground: hsl(var(--popover-foreground));
+
+  --color-card: hsl(var(--card));
+  --color-card-foreground: hsl(var(--card-foreground));
+
+  --color-chart-1: hsl(var(--chart-1));
+  --color-chart-2: hsl(var(--chart-2));
+  --color-chart-3: hsl(var(--chart-3));
+  --color-chart-4: hsl(var(--chart-4));
+  --color-chart-5: hsl(var(--chart-5));
+
+  --color-sidebar: hsl(var(--sidebar));
+  --color-sidebar-foreground: hsl(var(--sidebar-foreground));
+  --color-sidebar-primary: hsl(var(--sidebar-primary));
+  --color-sidebar-primary-foreground: hsl(var(--sidebar-primary-foreground));
+  --color-sidebar-accent: hsl(var(--sidebar-accent));
+  --color-sidebar-accent-foreground: hsl(var(--sidebar-accent-foreground));
+  --color-sidebar-border: hsl(var(--sidebar-border));
+  --color-sidebar-ring: hsl(var(--sidebar-ring));
+
+  --radius: var(--radius-base);
+  --radius-xs: calc(var(--radius-base) * 0.4);
+  --radius-sm: calc(var(--radius-base) * 0.6);
+  --radius-md: calc(var(--radius-base) * 0.8);
+  --radius-lg: var(--radius-base);
+  --radius-xl: calc(var(--radius-base) * 1.4);
+  --radius-2xl: calc(var(--radius-base) * 1.8);
+  --radius-3xl: calc(var(--radius-base) * 2.2);
+  --radius-4xl: calc(var(--radius-base) * 2.6);
+
+  --shadow-xs: var(--theme-shadow-xs);
+  --shadow-sm: var(--theme-shadow-sm);
+  --shadow: var(--theme-shadow);
+  --shadow-md: var(--theme-shadow-md);
+  --shadow-lg: var(--theme-shadow-lg);
+  --shadow-xl: var(--theme-shadow-xl);
+
+  --text-2xs: var(--font-size-2xs);
+  --text-2xs--line-height: var(--line-height-2xs);
+  --text-2xs-plus: var(--font-size-2xs-plus);
+  --text-2xs-plus--line-height: var(--line-height-2xs-plus);
+  --text-xs: var(--font-size-xs);
+  --text-xs--line-height: var(--line-height-tight);
+  --text-sm: var(--font-size-sm);
+  --text-sm--line-height: var(--line-height-snug);
+  --text-base: var(--font-size-md);
+  --text-base--line-height: var(--line-height-normal);
+  --text-lg: var(--font-size-lg);
+  --text-lg--line-height: var(--line-height-normal);
+  --text-xl: var(--font-size-xl);
+  --text-xl--line-height: var(--line-height-snug);
+  --text-2xl: var(--font-size-2xl);
+  --text-2xl--line-height: var(--line-height-snug);
+  --text-3xl: var(--font-size-3xl);
+  --text-3xl--line-height: var(--line-height-tight);
+  --text-4xl: var(--font-size-4xl);
+  --text-4xl--line-height: var(--line-height-tight);
+  --text-5xl: calc(var(--font-size-base) * 3);
+  --text-5xl--line-height: 1;
+  --text-6xl: calc(var(--font-size-base) * 3.75);
+  --text-6xl--line-height: 1;
+  --text-7xl: calc(var(--font-size-base) * 4.5);
+  --text-7xl--line-height: 1;
+  --text-8xl: calc(var(--font-size-base) * 6);
+  --text-8xl--line-height: 1;
+  --text-9xl: calc(var(--font-size-base) * 8);
+  --text-9xl--line-height: 1;
+
+  --leading-tight: var(--line-height-tight);
+  --leading-snug: var(--line-height-snug);
+  --leading-normal: var(--line-height-normal);
+  --leading-relaxed: var(--line-height-relaxed);
+  --leading-loose: var(--line-height-loose);
+
+  --spacing-control-xs: var(--control-height-xs);
+  --spacing-control-sm: var(--control-height-sm);
+  --spacing-control-md: var(--control-height-md);
+  --spacing-control-lg: var(--control-height-lg);
+  --spacing-control-xl: var(--control-height-xl);
+
+  --spacing-container-sm: var(--container-sm);
+  --spacing-container-md: var(--container-md);
+  --spacing-container-lg: var(--container-lg);
+  --spacing-container-xl: var(--container-xl);
+  --spacing-container-2xl: var(--container-2xl);
+
+  --font-sans: var(--theme-font-sans);
+  --font-mono: var(--theme-font-mono);
+}
+
+@utility rounded-base {
+  border-radius: var(--rounded-base);
+}