@ojiepermana/angular 22.1.10 → 22.1.12

package/types/ojiepermana-angular-theme-styles.d.ts

@@ -1 +1,319 @@
-export * from '@ojiepermana/angular-theme/styles';
+import * as i0 from '@angular/core';
+import { Signal, WritableSignal, InjectionToken, EnvironmentProviders } from '@angular/core';
+
+/**
+ * One place for the "a preference that lives in localStorage and shows up as an
+ * attribute on `<html>`" pattern that every theme axis needs.
+ *
+ * Each axis service used to hand-roll the same four private methods (`storage`,
+ * `readStorage`, `persist`, plus an effect writing the attribute) around a
+ * `signal`. That is the whole body of the simpler services, so a fix to any of
+ * it had to be made five times.
+ *
+ * The storage half itself lives in `@ojiepermana/angular/component/utils/core`,
+ * because `navigation` needs it too and navigation must not depend on this
+ * package.
+ */
+/**
+ * A persisted value, without the DOM half.
+ *
+ * Useful on its own for a preference that is not an attribute: the brand axis
+ * stores an object and paints custom properties instead.
+ *
+ * Two timing details the theme services depend on:
+ *
+ *  - the stored value is read SYNCHRONOUSLY here, not in an effect, because
+ *    every service exposes its state to consumers that read it during the same
+ *    change detection pass;
+ *  - the effect writes on its FIRST run, so storage holds the resolved default
+ *    immediately after construction even when nothing was stored.
+ */
+declare function persistedSignal<T>(options: {
+    readonly key: string;
+    /** Turn the raw stored string (or `null`) into a value. Must always succeed. */
+    readonly parse: (raw: string | null) => T;
+    /** Serialize for storage. Returning `null` REMOVES the key. */
+    readonly serialize: (value: T) => string | null;
+    /** Defaults to `inject(DOCUMENT, { optional: true })`. */
+    readonly documentRef?: Document | null;
+}): WritableSignal<T>;
+/**
+ * Mirror a reactive string onto one or more `<html>` attributes. A `null` value
+ * removes them.
+ */
+declare function htmlAttributeEffect(options: {
+    readonly attribute: string | readonly string[];
+    readonly source: () => string | null;
+    readonly documentRef?: Document | null;
+}): void;
+/** Mirror reactive inline custom properties onto `<html>`. A `null` value removes one. */
+declare function htmlStylePropertyEffect(options: {
+    readonly source: () => Readonly<Record<string, string | null>>;
+    readonly documentRef?: Document | null;
+}): void;
+interface PersistedHtmlAttribute<T extends string> {
+    /** The persisted value. Correct immediately, before any effect has run. */
+    readonly value: Signal<T>;
+    /** What actually reaches the DOM. Same as {@link value} unless `resolveAttributeValue` is given. */
+    readonly attributeValue: Signal<string>;
+    set(next: T): void;
+}
+interface PersistedHtmlAttributeOptions<T extends string> {
+    /** localStorage key. */
+    readonly key: string;
+    /** The `<html>` attribute, or several when one value drives more than one. */
+    readonly attribute: string | readonly string[];
+    /**
+     * Union guard plus fallback. Applied to the stored string AND to `initial`,
+     * which is what the services do today: a junk stored value and a junk
+     * configured default both land on the same known-good value.
+     */
+    readonly normalize: (value: string | null | undefined) => T;
+    /**
+     * The configured default, already resolved by the caller. It is a caller
+     * concern because one axis derives it from another option, and this helper
+     * must not know that.
+     */
+    readonly initial?: string | null | undefined;
+    /**
+     * What to WRITE when it differs from what is PERSISTED. Called inside the
+     * effect, so reading a signal here is tracked: that is how a `'system'` mode
+     * keeps following the operating system while still persisting `'system'`.
+     */
+    readonly resolveAttributeValue?: (value: T) => string;
+    readonly documentRef?: Document | null;
+}
+/**
+ * A persisted preference that also shows up as an attribute on `<html>`.
+ *
+ * The stored value wins over the configured default, which is the rule every
+ * axis already followed.
+ */
+declare function persistedHtmlAttributeSignal<T extends string>(options: PersistedHtmlAttributeOptions<T>): PersistedHtmlAttribute<T>;
+/**
+ * `(prefers-color-scheme: dark)` as a signal, torn down with the injection
+ * context that created it.
+ *
+ * Lives here because it is the other half of the same story: an axis whose
+ * PERSISTED value is `'system'` still has to write a concrete `light` or `dark`
+ * to the DOM, and this is what makes that reactive.
+ */
+declare function prefersDarkSignal(documentRef?: Document | null): Signal<boolean>;
+
+/** Resolved brand color. Both fields are HSL triplets `H S% L%`. */
+interface ThemeBrand {
+    readonly color: string;
+    readonly foreground: string;
+}
+/**
+ * Consumer-configurable brand color. Writes `--brand`, `--brand-foreground`, the
+ * derived `--brand-pattern-hs` hue/saturation source, and a `--brand-ring-light`
+ * / `--brand-ring-dark` pair as inline custom properties on `<html>` so solid
+ * brand utilities, the focus ring, and the soft Layout pattern tiers can resolve
+ * without CSS relative-color syntax.
+ *
+ * Default comes from `provideUiTheme({ brand })`; `setBrand()` overrides at
+ * runtime and persists. When unset, `--brand` falls back to `var(--primary)`.
+ */
+declare class ThemeBrandService {
+    private readonly options;
+    /**
+     * Storage half shared with the other axes; the DOM half is custom, because the
+     * brand paints a set of inline custom properties rather than setting an
+     * attribute. `serialize` returning `null` is what clears the stored key.
+     */
+    private readonly brandState;
+    readonly brand: i0.Signal<ThemeBrand | null>;
+    constructor();
+    /**
+     * Set the brand color. `color`/`foreground` are HSL triplets (e.g.
+     * `'221 83% 53%'`); a hex color is converted, since that is what a native
+     * picker hands back. The fill is kept exactly as chosen — `--brand-foreground`
+     * is moved until text on it clears 4.5 to 1, and the focus ring is solved
+     * separately per mode, so a pale brand can never leave the ring invisible.
+     */
+    setBrand(color: string, foreground?: string): void;
+    /** Clear the consumer brand → `--brand` falls back to `var(--primary)`. */
+    clearBrand(): void;
+    private normalizeOption;
+    /** The custom properties the brand paints. `null` removes one. */
+    private brandProperties;
+    /** Stored brands are JSON. Anything unparsable reads as "no stored brand". */
+    private parseStored;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ThemeBrandService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ThemeBrandService>;
+}
+
+declare const THEME_MODES: readonly ["light", "dark", "system"];
+declare const RESOLVED_THEME_MODES: readonly ["light", "dark"];
+/**
+ * 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`.
+ */
+declare const THEME_COLORS: readonly ["base", "red", "orange", "amber", "yellow", "lime", "green", "emerald", "teal", "cyan", "sky", "blue", "indigo", "violet", "purple", "fuchsia", "pink", "rose", "brand"];
+/**
+ * Neutral families (axis `theme-neutral`). `base` = core theme neutrals and lets
+ * Layout patterns follow the accent. Non-base values override both the gray
+ * family and Layout's decorative pattern hue, while composing with any accent.
+ */
+declare const THEME_NEUTRALS: readonly ["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. Every preset takes Tailwind's stock value for that name — `none` 0,
+ * `xs` 0.125rem, `sm` 0.25rem, `md` 0.375rem (the default), `xl` 0.75rem — and
+ * `full` is the pill extreme.
+ */
+declare const THEME_RADII: readonly ["none", "xs", "sm", "md", "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).
+ */
+declare const THEME_SPACES: readonly ["compact", "normal"];
+type ThemeMode = (typeof THEME_MODES)[number];
+type ResolvedThemeMode = (typeof RESOLVED_THEME_MODES)[number];
+type ThemeColor = (typeof THEME_COLORS)[number];
+type ThemeNeutral = (typeof THEME_NEUTRALS)[number];
+type ThemeRadius = (typeof THEME_RADII)[number];
+type ThemeSpace = (typeof THEME_SPACES)[number];
+declare const DEFAULT_THEME_MODE: ThemeMode;
+declare const DEFAULT_THEME_COLOR: ThemeColor;
+declare const DEFAULT_THEME_NEUTRAL: ThemeNeutral;
+declare const DEFAULT_THEME_RADIUS: ThemeRadius;
+declare const DEFAULT_THEME_SPACE: ThemeSpace;
+declare const THEME_MODE_STORAGE_KEY = "theme-mode";
+declare const THEME_COLOR_STORAGE_KEY = "theme-color";
+declare const THEME_NEUTRAL_STORAGE_KEY = "theme-neutral";
+declare const THEME_BRAND_STORAGE_KEY = "theme-brand";
+declare const THEME_RADIUS_STORAGE_KEY = "theme-radius";
+declare const THEME_SPACE_STORAGE_KEY = "theme-space";
+declare function isThemeMode(value: string | null | undefined): value is ThemeMode;
+declare function isResolvedThemeMode(value: string | null | undefined): value is ResolvedThemeMode;
+declare function isThemeColor(value: string | null | undefined): value is ThemeColor;
+declare function isThemeNeutral(value: string | null | undefined): value is ThemeNeutral;
+declare function isThemeRadius(value: string | null | undefined): value is ThemeRadius;
+declare function isThemeSpace(value: string | null | undefined): value is ThemeSpace;
+declare function normalizeThemeMode(value: string | null | undefined): ThemeMode;
+declare function normalizeThemeColor(value: string | null | undefined): ThemeColor;
+declare function normalizeThemeNeutral(value: string | null | undefined): ThemeNeutral;
+declare function normalizeThemeRadius(value: string | null | undefined): ThemeRadius;
+declare function normalizeThemeSpace(value: string | null | undefined): ThemeSpace;
+
+/**
+ * Drives the two FluxUI-style color axes:
+ *  - accent  → `<html theme-color>`   (full tinted palette per color)
+ *  - neutral → `<html theme-neutral>` (gray family + Layout pattern hue)
+ *
+ * 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.
+ */
+declare class ThemeColorService {
+    private readonly options;
+    private readonly colorAxis;
+    private readonly neutralAxis;
+    readonly color: i0.Signal<"red" | "green" | "blue" | "base" | "orange" | "amber" | "yellow" | "lime" | "emerald" | "teal" | "cyan" | "sky" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "brand">;
+    readonly neutral: i0.Signal<"base" | "slate" | "gray" | "zinc" | "neutral" | "stone" | "mauve" | "olive" | "mist" | "taupe">;
+    setColor(color: ThemeColor): void;
+    setNeutral(neutral: ThemeNeutral): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ThemeColorService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ThemeColorService>;
+}
+
+/**
+ * Color mode axis. Writes both `<html theme-mode>` and `<html data-mode>`.
+ *
+ * The persisted value and the written value differ here, which is the whole
+ * point of the axis: `'system'` is what gets stored, while `light` or `dark` is
+ * what reaches the DOM, and it keeps following the operating system live.
+ */
+declare class ThemeModeService {
+    private readonly options;
+    private readonly systemPrefersDark;
+    private readonly axis;
+    readonly mode: i0.Signal<"light" | "dark" | "system">;
+    readonly resolvedMode: i0.Signal<"light" | "dark">;
+    readonly isDark: i0.Signal<boolean>;
+    setMode(mode: ThemeMode): void;
+    toggle(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ThemeModeService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ThemeModeService>;
+}
+
+/**
+ * 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).
+ */
+declare class ThemeRadiusService {
+    private readonly options;
+    private readonly axis;
+    readonly radius: i0.Signal<"none" | "xs" | "sm" | "md" | "xl" | "full">;
+    /** Active preset in px @ 16px root. */
+    readonly radiusPx: i0.Signal<number>;
+    setRadius(radius: ThemeRadius): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ThemeRadiusService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ThemeRadiusService>;
+}
+
+/**
+ * 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).
+ */
+declare class ThemeSpaceService {
+    private readonly options;
+    private readonly axis;
+    readonly space: i0.Signal<"compact" | "normal">;
+    setSpace(space: ThemeSpace): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ThemeSpaceService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ThemeSpaceService>;
+}
+
+interface ThemeIconOptions {
+    /**
+     * Load the Material Symbols icon font from Google Fonts at startup.
+     *
+     * Default: `false` (opt-in). Left off, `provideUiTheme()` makes no external
+     * network request — better for privacy, offline, and strict CSP. Set to
+     * `true` to fetch `https://fonts.googleapis.com/css2`, or self-host the font
+     * and import it in your own stylesheet instead.
+     */
+    readonly materialSymbols?: boolean;
+}
+/** Consumer brand color. HSL triplets `H S% L%` consumed by `hsl(var(--brand))`. */
+interface ThemeBrandOptions {
+    /** Brand color, e.g. `'221 83% 53%'`. */
+    readonly color: string;
+    /** Foreground on solid brand fills. Defaults to white. */
+    readonly foreground?: string;
+}
+interface ThemeOptions {
+    readonly mode?: ThemeMode;
+    /** Initial accent palette (`theme-color`). Persisted choice wins over this. */
+    readonly color?: ThemeColor;
+    /** Initial neutral family (`theme-neutral`). Persisted choice wins over this. */
+    readonly neutral?: ThemeNeutral;
+    /** Initial corner radius preset (`theme-radius`). Persisted choice wins over this. */
+    readonly radius?: ThemeRadius;
+    /** Initial spacing density preset (`theme-space`). Persisted choice wins over this. */
+    readonly space?: ThemeSpace;
+    /**
+     * Consumer brand color → `--brand` / `bg-brand`, and the `brand` accent preset.
+     * Pass an HSL triplet string, or `{ color, foreground }`. Persisted/runtime
+     * changes (ThemeBrandService.setBrand) win over this default.
+     */
+    readonly brand?: string | ThemeBrandOptions;
+    readonly icons?: ThemeIconOptions;
+}
+declare const THEME_OPTIONS: InjectionToken<Readonly<ThemeOptions>>;
+
+declare function provideUiTheme(options?: ThemeOptions): EnvironmentProviders;
+
+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, htmlAttributeEffect, htmlStylePropertyEffect, isResolvedThemeMode, isThemeColor, isThemeMode, isThemeNeutral, isThemeRadius, isThemeSpace, normalizeThemeColor, normalizeThemeMode, normalizeThemeNeutral, normalizeThemeRadius, normalizeThemeSpace, persistedHtmlAttributeSignal, persistedSignal, prefersDarkSignal, provideUiTheme };
+export type { PersistedHtmlAttribute, PersistedHtmlAttributeOptions, ResolvedThemeMode, ThemeBrand, ThemeBrandOptions, ThemeColor, ThemeIconOptions, ThemeMode, ThemeNeutral, ThemeOptions, ThemeRadius, ThemeSpace };

package/types/ojiepermana-angular-theme.d.ts

@@ -1 +1,2 @@
-export * from '@ojiepermana/angular-theme';
+
+export { };

package/types/ojiepermana-angular.d.ts

@@ -1,5 +1,5 @@
-export * from '@ojiepermana/angular-chart';
-export * from '@ojiepermana/angular-component';
-export * from '@ojiepermana/angular-navigation';
-export * from '@ojiepermana/angular-sdk';
-export * from '@ojiepermana/angular-theme';
+export * from '@ojiepermana/angular/chart';
+export * from '@ojiepermana/angular/component';
+export * from '@ojiepermana/angular/navigation';
+export * from '@ojiepermana/angular/sdk';
+export * from '@ojiepermana/angular/theme';