@ojiepermana/angular-theme 22.0.35 → 22.0.41

package/fesm2022/ojiepermana-angular-theme-styles.mjs

@@ -7,25 +7,103 @@ const THEME_OPTIONS = new InjectionToken('THEME_OPTIONS');
 
 const THEME_MODES = ['light', 'dark', 'system'];
 const RESOLVED_THEME_MODES = ['light', 'dark'];
-const THEME_SEASONS = ['base', 'imlek', 'ramadhan', 'ied', 'natal', 'new-year'];
+/**
+ * FluxUI-style accent palettes (axis `theme-color`). `base` = core theme (no
+ * override); `brand` = the consumer's `--brand` color. Others re-tint the full
+ * palette. Order mirrors the FluxUI accent picker (base…rose) + `brand`.
+ */
+const THEME_COLORS = [
+    'base',
+    'red',
+    'orange',
+    'amber',
+    'yellow',
+    'lime',
+    'green',
+    'emerald',
+    'teal',
+    'cyan',
+    'sky',
+    'blue',
+    'indigo',
+    'violet',
+    'purple',
+    'fuchsia',
+    'pink',
+    'rose',
+    'brand',
+];
+/**
+ * Neutral (gray) families (axis `theme-neutral`). `base` = core theme neutrals.
+ * Overrides only the gray family, composing with any accent.
+ */
+const THEME_NEUTRALS = [
+    'base',
+    'slate',
+    'gray',
+    'zinc',
+    'neutral',
+    'stone',
+    'mauve',
+    'olive',
+    'mist',
+    'taupe',
+];
+/**
+ * Corner radius presets (axis `theme-radius`). Each drives the single
+ * `--radius-base` knob; the whole `--radius-*` scale + `rounded-*` utilities
+ * follow. `md` = the 0.625rem default; `full` is the pill extreme.
+ */
+const THEME_RADII = ['none', 'sm', 'md', 'lg', 'xl', 'full'];
+/**
+ * Spacing density presets (axis `theme-space`). Each drives the single
+ * `--spacing-base` knob; every `p-*`/`m-*`/`gap-*`/`w-*`/`h-*` utility follows.
+ * `normal` = the 0.25rem default (no-op baseline).
+ */
+const THEME_SPACES = ['compact', 'normal', 'relaxed', 'spacious'];
 const DEFAULT_THEME_MODE = 'system';
-const DEFAULT_THEME_SEASON = 'base';
+const DEFAULT_THEME_COLOR = 'base';
+const DEFAULT_THEME_NEUTRAL = 'base';
+const DEFAULT_THEME_RADIUS = 'md';
+const DEFAULT_THEME_SPACE = 'normal';
 const THEME_MODE_STORAGE_KEY = 'theme-mode';
-const THEME_SEASON_STORAGE_KEY = 'theme-season';
+const THEME_COLOR_STORAGE_KEY = 'theme-color';
+const THEME_NEUTRAL_STORAGE_KEY = 'theme-neutral';
+const THEME_BRAND_STORAGE_KEY = 'theme-brand';
+const THEME_RADIUS_STORAGE_KEY = 'theme-radius';
+const THEME_SPACE_STORAGE_KEY = 'theme-space';
 function isThemeMode(value) {
     return typeof value === 'string' && THEME_MODES.includes(value);
 }
 function isResolvedThemeMode(value) {
     return typeof value === 'string' && RESOLVED_THEME_MODES.includes(value);
 }
-function isThemeSeason(value) {
-    return typeof value === 'string' && THEME_SEASONS.includes(value);
+function isThemeColor(value) {
+    return typeof value === 'string' && THEME_COLORS.includes(value);
+}
+function isThemeNeutral(value) {
+    return typeof value === 'string' && THEME_NEUTRALS.includes(value);
+}
+function isThemeRadius(value) {
+    return typeof value === 'string' && THEME_RADII.includes(value);
+}
+function isThemeSpace(value) {
+    return typeof value === 'string' && THEME_SPACES.includes(value);
 }
 function normalizeThemeMode(value) {
     return isThemeMode(value) ? value : DEFAULT_THEME_MODE;
 }
-function normalizeThemeSeason(value) {
-    return isThemeSeason(value) ? value : DEFAULT_THEME_SEASON;
+function normalizeThemeColor(value) {
+    return isThemeColor(value) ? value : DEFAULT_THEME_COLOR;
+}
+function normalizeThemeNeutral(value) {
+    return isThemeNeutral(value) ? value : DEFAULT_THEME_NEUTRAL;
+}
+function normalizeThemeRadius(value) {
+    return isThemeRadius(value) ? value : DEFAULT_THEME_RADIUS;
+}
+function normalizeThemeSpace(value) {
+    return isThemeSpace(value) ? value : DEFAULT_THEME_SPACE;
 }
 
 class ThemeModeService {
@@ -127,67 +205,170 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.3", ngImpor
             type: Service
         }], ctorParameters: () => [] });
 
-class ThemeSeasonService {
+const DEFAULT_BRAND_FOREGROUND = '0 0% 100%';
+/**
+ * Consumer-configurable brand color. Writes `--brand` / `--brand-foreground` as
+ * inline custom properties on `<html>` so `bg-brand` / `text-brand-foreground`
+ * and the `theme-color='brand'` accent preset resolve to it.
+ *
+ * Default comes from `provideUiTheme({ brand })`; `setBrand()` overrides at
+ * runtime and persists. When unset, `--brand` falls back to `var(--primary)`.
+ */
+class ThemeBrandService {
     documentRef = inject(DOCUMENT, { optional: true });
     options = inject(THEME_OPTIONS, { optional: true });
-    seasonState = signal(DEFAULT_THEME_SEASON, /* @ts-ignore */
-    ...(ngDevMode ? [{ debugName: "seasonState" }] : /* istanbul ignore next */ []));
-    season = this.seasonState.asReadonly();
+    brandState = signal(null, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "brandState" }] : /* istanbul ignore next */ []));
+    brand = this.brandState.asReadonly();
     constructor() {
         this.ensureDefaults();
         effect(() => {
-            const season = this.seasonState();
-            this.persistSeason(season);
-            this.applySeasonAttribute(season);
-            this.ensureSeasonStylesheet(season);
+            const brand = this.brandState();
+            this.persist(brand);
+            this.applyBrand(brand);
         });
     }
-    setSeason(season) {
-        this.seasonState.set(season);
+    /** Set the brand color. `color`/`foreground` are HSL triplets (e.g. `'221 83% 53%'`). */
+    setBrand(color, foreground = DEFAULT_BRAND_FOREGROUND) {
+        this.brandState.set({ color, foreground });
+    }
+    /** Clear the consumer brand → `--brand` falls back to `var(--primary)`. */
+    clearBrand() {
+        this.brandState.set(null);
     }
     ensureDefaults() {
-        const defaultSeason = normalizeThemeSeason(this.options?.season);
-        const storedSeason = this.readStorage(THEME_SEASON_STORAGE_KEY) ?? defaultSeason;
-        this.seasonState.set(normalizeThemeSeason(storedSeason));
+        const stored = this.readStoredBrand();
+        if (stored) {
+            this.brandState.set(stored);
+            return;
+        }
+        const fromOptions = this.normalizeOption(this.options?.brand);
+        if (fromOptions) {
+            this.brandState.set(fromOptions);
+        }
     }
-    persistSeason(season) {
-        this.writeStorage(THEME_SEASON_STORAGE_KEY, season);
+    normalizeOption(brand) {
+        if (!brand) {
+            return null;
+        }
+        if (typeof brand === 'string') {
+            return { color: brand, foreground: DEFAULT_BRAND_FOREGROUND };
+        }
+        return { color: brand.color, foreground: brand.foreground ?? DEFAULT_BRAND_FOREGROUND };
     }
-    applySeasonAttribute(season) {
+    applyBrand(brand) {
         const root = this.documentRef?.documentElement;
         if (!root) {
             return;
         }
-        root.setAttribute('theme-season', season);
-    }
-    /**
-     * Lazily loads the active season's stylesheet via `<link>` when the app
-     * configured `seasonalCssUrl`, so only base CSS ships in the main bundle.
-     */
-    ensureSeasonStylesheet(season) {
-        const doc = this.documentRef;
-        const resolveUrl = this.options?.seasonalCssUrl;
-        if (!doc || !resolveUrl) {
+        if (!brand) {
+            root.style.removeProperty('--brand');
+            root.style.removeProperty('--brand-foreground');
             return;
         }
-        const linkId = 'theme-season-styles';
-        const existing = doc.getElementById(linkId);
-        const url = season === 'base' ? null : resolveUrl(season);
-        if (!url) {
-            existing?.remove();
-            return;
+        root.style.setProperty('--brand', brand.color);
+        root.style.setProperty('--brand-foreground', brand.foreground);
+    }
+    storage() {
+        try {
+            return this.documentRef?.defaultView?.localStorage ?? null;
+        }
+        catch {
+            return null;
         }
-        if (existing) {
-            if (existing.getAttribute('href') !== url) {
-                existing.setAttribute('href', url);
+    }
+    readStoredBrand() {
+        try {
+            const raw = this.storage()?.getItem(THEME_BRAND_STORAGE_KEY);
+            if (!raw) {
+                return null;
             }
+            const parsed = JSON.parse(raw);
+            if (typeof parsed?.color === 'string') {
+                return {
+                    color: parsed.color,
+                    foreground: typeof parsed.foreground === 'string' ? parsed.foreground : DEFAULT_BRAND_FOREGROUND,
+                };
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+    persist(brand) {
+        try {
+            const storage = this.storage();
+            if (!storage) {
+                return;
+            }
+            if (!brand) {
+                storage.removeItem(THEME_BRAND_STORAGE_KEY);
+                return;
+            }
+            storage.setItem(THEME_BRAND_STORAGE_KEY, JSON.stringify(brand));
+        }
+        catch {
             return;
         }
-        const link = doc.createElement('link');
-        link.id = linkId;
-        link.rel = 'stylesheet';
-        link.href = url;
-        doc.head.appendChild(link);
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.3", ngImport: i0, type: ThemeBrandService, deps: [], target: i0.ɵɵFactoryTarget.Service });
+    static ɵprov = i0.ɵɵngDeclareService({ minVersion: "22.0.0", version: "22.0.3", ngImport: i0, type: ThemeBrandService });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.3", ngImport: i0, type: ThemeBrandService, decorators: [{
+            type: Service
+        }], ctorParameters: () => [] });
+
+/**
+ * Drives the two FluxUI-style color axes:
+ *  - accent  → `<html theme-color>`   (full tinted palette per color)
+ *  - neutral → `<html theme-neutral>` (gray family only)
+ *
+ * Both persist to localStorage and seed from `provideUiTheme({ color, neutral })`
+ * (a persisted choice wins over the configured default). `base` on either axis
+ * means "no override" — the core base theme applies.
+ */
+class ThemeColorService {
+    documentRef = inject(DOCUMENT, { optional: true });
+    options = inject(THEME_OPTIONS, { optional: true });
+    colorState = signal(DEFAULT_THEME_COLOR, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "colorState" }] : /* istanbul ignore next */ []));
+    neutralState = signal(DEFAULT_THEME_NEUTRAL, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "neutralState" }] : /* istanbul ignore next */ []));
+    color = this.colorState.asReadonly();
+    neutral = this.neutralState.asReadonly();
+    constructor() {
+        this.ensureDefaults();
+        effect(() => {
+            const color = this.colorState();
+            this.persist(THEME_COLOR_STORAGE_KEY, color);
+            this.applyAttribute('theme-color', color);
+        });
+        effect(() => {
+            const neutral = this.neutralState();
+            this.persist(THEME_NEUTRAL_STORAGE_KEY, neutral);
+            this.applyAttribute('theme-neutral', neutral);
+        });
+    }
+    setColor(color) {
+        this.colorState.set(color);
+    }
+    setNeutral(neutral) {
+        this.neutralState.set(neutral);
+    }
+    ensureDefaults() {
+        // A configured brand with no explicit accent defaults the accent to 'brand'
+        // so the consumer's brand color becomes the primary (FluxUI-style).
+        const configuredColor = this.options?.color ?? (this.options?.brand ? 'brand' : undefined);
+        const defaultColor = normalizeThemeColor(configuredColor);
+        const storedColor = this.readStorage(THEME_COLOR_STORAGE_KEY) ?? defaultColor;
+        this.colorState.set(normalizeThemeColor(storedColor));
+        const defaultNeutral = normalizeThemeNeutral(this.options?.neutral);
+        const storedNeutral = this.readStorage(THEME_NEUTRAL_STORAGE_KEY) ?? defaultNeutral;
+        this.neutralState.set(normalizeThemeNeutral(storedNeutral));
+    }
+    applyAttribute(attribute, value) {
+        this.documentRef?.documentElement?.setAttribute(attribute, value);
     }
     storage() {
         try {
@@ -205,7 +386,7 @@ class ThemeSeasonService {
             return null;
         }
     }
-    writeStorage(key, value) {
+    persist(key, value) {
         try {
             this.storage()?.setItem(key, value);
         }
@@ -213,10 +394,148 @@ class ThemeSeasonService {
             return;
         }
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.3", ngImport: i0, type: ThemeSeasonService, deps: [], target: i0.ɵɵFactoryTarget.Service });
-    static ɵprov = i0.ɵɵngDeclareService({ minVersion: "22.0.0", version: "22.0.3", ngImport: i0, type: ThemeSeasonService });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.3", ngImport: i0, type: ThemeColorService, deps: [], target: i0.ɵɵFactoryTarget.Service });
+    static ɵprov = i0.ɵɵngDeclareService({ minVersion: "22.0.0", version: "22.0.3", ngImport: i0, type: ThemeColorService });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.3", ngImport: i0, type: ThemeColorService, decorators: [{
+            type: Service
+        }], ctorParameters: () => [] });
+
+/**
+ * Corner radius axis. Writes `<html theme-radius>`; each preset CSS sets the
+ * single `--radius-base` knob so the whole `--radius-*` scale + `rounded-*`
+ * utilities rescale. Persists to localStorage and seeds from
+ * `provideUiTheme({ radius })` (a persisted choice wins over the default).
+ */
+class ThemeRadiusService {
+    documentRef = inject(DOCUMENT, { optional: true });
+    options = inject(THEME_OPTIONS, { optional: true });
+    radiusState = signal(DEFAULT_THEME_RADIUS, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "radiusState" }] : /* istanbul ignore next */ []));
+    radius = this.radiusState.asReadonly();
+    radiusPx = computed(() => {
+        switch (this.radius()) {
+            case 'none':
+                return 0;
+            case 'sm':
+                return 6;
+            case 'md':
+                return 10;
+            case 'lg':
+                return 14;
+            case 'xl':
+                return 20;
+            case 'full':
+                return 9999;
+            default:
+                return 10;
+        }
+    }, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "radiusPx" }] : /* istanbul ignore next */ []));
+    constructor() {
+        this.ensureDefaults();
+        effect(() => {
+            const radius = this.radiusState();
+            this.persist(radius);
+            this.documentRef?.documentElement?.setAttribute('theme-radius', radius);
+        });
+    }
+    setRadius(radius) {
+        this.radiusState.set(radius);
+    }
+    ensureDefaults() {
+        const fallback = normalizeThemeRadius(this.options?.radius);
+        const stored = this.readStorage() ?? fallback;
+        this.radiusState.set(normalizeThemeRadius(stored));
+    }
+    storage() {
+        try {
+            return this.documentRef?.defaultView?.localStorage ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    readStorage() {
+        try {
+            return this.storage()?.getItem(THEME_RADIUS_STORAGE_KEY) ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    persist(radius) {
+        try {
+            this.storage()?.setItem(THEME_RADIUS_STORAGE_KEY, radius);
+        }
+        catch {
+            return;
+        }
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.3", ngImport: i0, type: ThemeRadiusService, deps: [], target: i0.ɵɵFactoryTarget.Service });
+    static ɵprov = i0.ɵɵngDeclareService({ minVersion: "22.0.0", version: "22.0.3", ngImport: i0, type: ThemeRadiusService });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.3", ngImport: i0, type: ThemeRadiusService, decorators: [{
+            type: Service
+        }], ctorParameters: () => [] });
+
+/**
+ * Spacing density axis. Writes `<html theme-space>`; each preset CSS sets the
+ * single `--spacing-base` knob, which Tailwind's `--spacing` derives from, so
+ * every `p-*`/`m-*`/`gap-*`/`w-*`/`h-*` utility rescales. Persists to
+ * localStorage and seeds from `provideUiTheme({ space })` (a persisted choice
+ * wins over the default).
+ */
+class ThemeSpaceService {
+    documentRef = inject(DOCUMENT, { optional: true });
+    options = inject(THEME_OPTIONS, { optional: true });
+    spaceState = signal(DEFAULT_THEME_SPACE, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "spaceState" }] : /* istanbul ignore next */ []));
+    space = this.spaceState.asReadonly();
+    constructor() {
+        this.ensureDefaults();
+        effect(() => {
+            const space = this.spaceState();
+            this.persist(space);
+            this.documentRef?.documentElement?.setAttribute('theme-space', space);
+        });
+    }
+    setSpace(space) {
+        this.spaceState.set(space);
+    }
+    ensureDefaults() {
+        const fallback = normalizeThemeSpace(this.options?.space);
+        const stored = this.readStorage() ?? fallback;
+        this.spaceState.set(normalizeThemeSpace(stored));
+    }
+    storage() {
+        try {
+            return this.documentRef?.defaultView?.localStorage ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    readStorage() {
+        try {
+            return this.storage()?.getItem(THEME_SPACE_STORAGE_KEY) ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    persist(space) {
+        try {
+            this.storage()?.setItem(THEME_SPACE_STORAGE_KEY, space);
+        }
+        catch {
+            return;
+        }
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.3", ngImport: i0, type: ThemeSpaceService, deps: [], target: i0.ɵɵFactoryTarget.Service });
+    static ɵprov = i0.ɵɵngDeclareService({ minVersion: "22.0.0", version: "22.0.3", ngImport: i0, type: ThemeSpaceService });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.3", ngImport: i0, type: ThemeSeasonService, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.3", ngImport: i0, type: ThemeSpaceService, decorators: [{
             type: Service
         }], ctorParameters: () => [] });
 
@@ -235,7 +554,10 @@ function provideUiTheme(options = {}) {
                 inject(MaterialSymbolsService).ensureLoaded();
             }
             inject(ThemeModeService);
-            inject(ThemeSeasonService);
+            inject(ThemeColorService);
+            inject(ThemeBrandService);
+            inject(ThemeRadiusService);
+            inject(ThemeSpaceService);
         }),
     ]);
 }
@@ -244,4 +566,4 @@ function provideUiTheme(options = {}) {
  * Generated bundle index. Do not edit.
  */
 
-export { DEFAULT_THEME_MODE, DEFAULT_THEME_SEASON, RESOLVED_THEME_MODES, THEME_MODES, THEME_MODE_STORAGE_KEY, THEME_OPTIONS, THEME_SEASONS, THEME_SEASON_STORAGE_KEY, ThemeModeService, ThemeSeasonService, isResolvedThemeMode, isThemeMode, isThemeSeason, normalizeThemeMode, normalizeThemeSeason, provideUiTheme };
+export { DEFAULT_THEME_COLOR, DEFAULT_THEME_MODE, DEFAULT_THEME_NEUTRAL, DEFAULT_THEME_RADIUS, DEFAULT_THEME_SPACE, RESOLVED_THEME_MODES, THEME_BRAND_STORAGE_KEY, THEME_COLORS, THEME_COLOR_STORAGE_KEY, THEME_MODES, THEME_MODE_STORAGE_KEY, THEME_NEUTRALS, THEME_NEUTRAL_STORAGE_KEY, THEME_OPTIONS, THEME_RADII, THEME_RADIUS_STORAGE_KEY, THEME_SPACES, THEME_SPACE_STORAGE_KEY, ThemeBrandService, ThemeColorService, ThemeModeService, ThemeRadiusService, ThemeSpaceService, isResolvedThemeMode, isThemeColor, isThemeMode, isThemeNeutral, isThemeRadius, isThemeSpace, normalizeThemeColor, normalizeThemeMode, normalizeThemeNeutral, normalizeThemeRadius, normalizeThemeSpace, provideUiTheme };

package/layout/README.md

@@ -1,6 +1,6 @@
 # @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.
+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.
 
@@ -65,17 +65,17 @@ Struktur yang direkomendasikan adalah sebagai berikut.
 
 ```html
 <Layout>
-  <LayoutVertical | layout-horizontal | layout-empty | layout-fluid>
+  <LayoutVertical | LayoutHorizontal | LayoutEmpty | LayoutFluid>
     <LayoutNavigation>...</LayoutNavigation>
     <LayoutContent>...</LayoutContent>
-  </layout-vertical | layout-horizontal | layout-empty | layout-fluid>
+  </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 `layout-nav` lalu `LayoutContent`.
+- 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.
@@ -194,13 +194,14 @@ 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.                     |
-| `class`             | `string`                   | `''`     | Menambahkan class pada host `Layout`.                                                                                                                                 |
+| 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:
 
@@ -208,7 +209,7 @@ Behavior:
 - 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 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()`.
+- 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.
@@ -266,20 +267,21 @@ 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.
+- `LayoutNavigation` akan tersembunyi jika tetap dirender di mode ini.
 
 ### `LayoutNavigationComponent`
 
 Wrapper untuk slot navigasi.
 
-Selector: `layout-nav`
+Selector: `LayoutNavigation`
 
 Inputs:
 
-| Input       | Type     | Default               | Deskripsi                                        |
-| ----------- | -------- | --------------------- | ------------------------------------------------ |
-| `ariaLabel` | `string` | `'Layout navigation'` | Label aksesibilitas untuk landmark `navigation`. |
-| `class`     | `string` | `''`                  | Menambahkan class pada host `layout-nav`.        |
+| Input        | Type             | Default               | Deskripsi                                                                                                                                  |
+| ------------ | ---------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `ariaLabel`  | `string`         | `'Layout navigation'` | Label aksesibilitas untuk landmark `navigation`.                                                                                           |
+| `railOffset` | `string \| null` | `null`                | Override offset rail vertikal nav (mode `vertical + border-rail`). Jika `null`, mengikuti preview rail offset dari nav yang diproyeksikan. |
+| `class`      | `string`         | `''`                  | Menambahkan class pada host `LayoutNavigation`.                                                                                            |
 
 Behavior:
 
@@ -293,7 +295,7 @@ Behavior:
 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.
+- Styling visual isi nav sebaiknya ditempatkan pada elemen child di dalam `LayoutNavigation`, bukan dengan mengandalkan border host.
 
 ### `LayoutContentComponent`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ojiepermana/angular-theme",
-  "version": "22.0.35",
+  "version": "22.0.41",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/edsis/angular.git"
@@ -13,8 +13,8 @@
     "@angular/common": ">=22.0.0",
     "@angular/core": ">=22.0.0",
     "@angular/router": ">=22.0.0",
-    "@ojiepermana/angular-navigation": "^22.0.35",
-    "@ojiepermana/angular-component": "^22.0.35",
+    "@ojiepermana/angular-navigation": "^22.0.41",
+    "@ojiepermana/angular-component": "^22.0.41",
     "rxjs": ">=7.8.0"
   },
   "dependencies": {