@meshmakers/octo-ui 3.3.920 → 3.3.930

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meshmakers/octo-ui",
-  "version": "3.3.920",
+  "version": "3.3.930",
   "peerDependencies": {
     "@ngx-translate/core": "^17.0.0",
     "@angular/animations": "^21.0.6",
@@ -42,6 +42,14 @@
     ".": {
       "types": "./types/meshmakers-octo-ui.d.ts",
       "default": "./fesm2022/meshmakers-octo-ui.mjs"
+    },
+    "./branding": {
+      "types": "./types/meshmakers-octo-ui-branding.d.ts",
+      "default": "./fesm2022/meshmakers-octo-ui-branding.mjs"
+    },
+    "./branding-settings": {
+      "types": "./types/meshmakers-octo-ui-branding-settings.d.ts",
+      "default": "./fesm2022/meshmakers-octo-ui-branding-settings.mjs"
     }
   },
   "type": "module"

package/types/meshmakers-octo-ui-branding-settings.d.ts

@@ -0,0 +1,107 @@
+import * as _progress_kendo_svg_icons from '@progress/kendo-svg-icons';
+import * as _angular_core from '@angular/core';
+import { OnInit } from '@angular/core';
+import { FormGroup, FormControl } from '@angular/forms';
+import { Routes } from '@angular/router';
+
+/**
+ * Strings used by `SettingsPageComponent`. This is a **required** input on the
+ * component — there are too many keys to provide reasonable English defaults
+ * that would degrade gracefully. Host applications construct an instance from
+ * their own translation system (e.g. ngx-translate `instant()`) and pass it
+ * via `[messages]`.
+ *
+ * Suggested .resx key prefix: `Branding_Settings_*` (or `Settings_*` to match
+ * the existing maco-app keys).
+ */
+interface BrandingSettingsMessages {
+    sectionGeneral: string;
+    sectionLogos: string;
+    sectionLightTheme: string;
+    sectionDarkTheme: string;
+    enableDarkTheme: string;
+    appName: string;
+    appTitle: string;
+    logoHeader: string;
+    logoFooter: string;
+    logoFavicon: string;
+    logoRemove: string;
+    uploadLogo: string;
+    uploadFavicon: string;
+    colorPrimary: string;
+    colorSecondary: string;
+    colorTertiary: string;
+    colorNeutral: string;
+    colorBackground: string;
+    gradientHeader: string;
+    gradientFooter: string;
+    gradientStart: string;
+    gradientEnd: string;
+    required: string;
+    save: string;
+    resetDefaults: string;
+    saveSuccess: string;
+    saveError: string;
+    resetSuccess: string;
+    loadError: string;
+}
+
+type LogoSlotName = 'header' | 'footer' | 'favicon';
+declare class SettingsPageComponent implements OnInit {
+    readonly messages: _angular_core.InputSignal<BrandingSettingsMessages>;
+    private readonly fb;
+    private readonly branding;
+    private readonly messageService;
+    private readonly defaults;
+    protected readonly saveIcon: _progress_kendo_svg_icons.SVGIcon;
+    protected readonly undoIcon: _progress_kendo_svg_icons.SVGIcon;
+    protected readonly xIcon: _progress_kendo_svg_icons.SVGIcon;
+    protected readonly logoSlotNames: readonly LogoSlotName[];
+    protected readonly saving: _angular_core.WritableSignal<boolean>;
+    protected readonly settingsForm: FormGroup;
+    private readonly slotStates;
+    private readonly persistedUrls;
+    constructor();
+    protected darkThemeEnabled(): boolean;
+    ngOnInit(): Promise<void>;
+    private readonly dragOverSlot;
+    protected isDragOver(slot: LogoSlotName): boolean;
+    protected onLogoSelected(slot: LogoSlotName, event: Event): void;
+    protected onLogoDragOver(slot: LogoSlotName, event: DragEvent): void;
+    protected onLogoDragLeave(slot: LogoSlotName): void;
+    protected onLogoDropped(slot: LogoSlotName, event: DragEvent): void;
+    private applyLogoFile;
+    protected clearLogo(slot: LogoSlotName): void;
+    protected previewUrl(slot: LogoSlotName): string | null;
+    protected onSubmit(): Promise<void>;
+    protected onResetDefaults(): Promise<void>;
+    private hydrate;
+    private logoFileForSave;
+    private strValue;
+    private paletteFromForm;
+    protected colorCtrl(controlName: string): FormControl<string>;
+    /**
+     * Resolves a localized label for a given logo slot. The maco-app source used
+     * dynamic translate-key concatenation (`'Settings_Logo_' + slot | translate`);
+     * the library expresses the same idea by mapping slot names to fields on the
+     * `BrandingSettingsMessages` interface.
+     */
+    protected logoLabel(slot: LogoSlotName): string;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SettingsPageComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SettingsPageComponent, "mm-branding-settings", never, { "messages": { "alias": "messages"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Routes for the branding/settings UI. Mount under any path:
+ *
+ * ```ts
+ * { path: 'settings', canActivate: [adminGuard], children: BRANDING_ROUTES }
+ * ```
+ *
+ * The `SettingsPageComponent` is lazy-loaded on first navigation regardless of
+ * how the host wires this — `loadComponent` returns a dynamic import.
+ */
+declare const BRANDING_ROUTES: Routes;
+
+export { BRANDING_ROUTES, SettingsPageComponent };
+export type { BrandingSettingsMessages };

package/types/meshmakers-octo-ui-branding.d.ts

@@ -0,0 +1,285 @@
+import * as i0 from '@angular/core';
+import { InjectionToken, EnvironmentProviders, WritableSignal, Provider } from '@angular/core';
+import * as _progress_kendo_svg_icons from '@progress/kendo-svg-icons';
+import { TitleStrategy, RouterStateSnapshot } from '@angular/router';
+
+/** Two-stop linear gradient; applied at 90deg by the theme application layer. */
+interface ThemeGradient {
+    startColor: string;
+    endColor: string;
+}
+/** Palette consumed by the theme layer (Kendo + app CSS variables). */
+interface ThemePalette {
+    primaryColor: string;
+    secondaryColor: string;
+    tertiaryColor: string;
+    neutralColor: string;
+    backgroundColor: string;
+    headerGradient: ThemeGradient;
+    footerGradient: ThemeGradient;
+}
+
+/** Domain-level branding shape consumed by the UI. */
+interface BrandingData {
+    rtId: string | null;
+    appName: string;
+    appTitle: string;
+    headerLogoUrl: string | null;
+    footerLogoUrl: string | null;
+    faviconUrl: string | null;
+    lightTheme: ThemePalette;
+    /** When null, the tenant has disabled dark mode — switcher locks to light. */
+    darkTheme: ThemePalette | null;
+}
+/**
+ * Update descriptor for `BrandingDataSource.save`. File slots are tri-state:
+ * `File` replaces, `null` clears, `undefined` leaves the existing blob untouched.
+ */
+interface BrandingUpdate {
+    appName: string;
+    appTitle: string;
+    headerLogoFile: File | null | undefined;
+    footerLogoFile: File | null | undefined;
+    faviconFile: File | null | undefined;
+    lightTheme: ThemePalette;
+    darkTheme: ThemePalette | null;
+}
+
+/**
+ * Bundled fallback URLs used when the tenant did not upload a logo / favicon.
+ * Any field omitted means the corresponding component renders nothing (text-only
+ * header, no <link rel="icon">, etc.) instead of breaking with a 404.
+ */
+interface OctoBrandingFallbackAssets {
+    headerLogo?: string;
+    footerLogo?: string;
+    favicon?: string;
+}
+declare const OCTO_BRANDING_DEFAULTS: InjectionToken<BrandingData>;
+declare const OCTO_BRANDING_FALLBACK_ASSETS: InjectionToken<OctoBrandingFallbackAssets>;
+/**
+ * Library-shipped neutral fallback. Apps that don't supply their own defaults
+ * see a working but visually-neutral baseline ("configure me"), not a crash.
+ */
+declare const NEUTRAL_BRANDING_DEFAULTS: BrandingData;
+declare const NEUTRAL_FALLBACK_ASSETS: OctoBrandingFallbackAssets;
+
+interface OctoBrandingConfig {
+    /** Caller-supplied defaults; merged shallowly over `NEUTRAL_BRANDING_DEFAULTS`. */
+    defaults?: Partial<BrandingData>;
+    /** Bundled URLs used when the tenant has not uploaded a logo / favicon. */
+    fallbackAssets?: OctoBrandingFallbackAssets;
+    /**
+     * When `true` (default) the library binds {@link AppTitleService} as the
+     * application's `TitleStrategy`, so `document.title` automatically reflects
+     * `<branding.appTitle> | <route.breadcrumb>` on every navigation. Set to
+     * `false` if the host already provides its own `TitleStrategy`.
+     */
+    registerTitleStrategy?: boolean;
+}
+/**
+ * Registers branding tokens, defaults, fallback assets, and (by default) the
+ * `TitleStrategy` that drives `document.title` from the branding signal.
+ *
+ * Does **not** load the tenant's branding record. Loading must happen after
+ * authentication is settled (Apollo's URI bakes in the tenant ID at the time
+ * the first request fires; loading too early targets
+ * `/tenants/undefined/GraphQL`). The host shell typically does:
+ *
+ * ```ts
+ * inject(BrandingApplicationService); // start the apply effect
+ * effect(() => {
+ *   if (this.auth.isAuthenticated()) {
+ *     this.brandingDataSource.load();
+ *   }
+ * });
+ * ```
+ *
+ * `BrandingApplicationService` is `providedIn: 'root'`, so the host only has
+ * to inject it once to activate the apply effect.
+ */
+declare function provideOctoBranding(config?: OctoBrandingConfig): EnvironmentProviders;
+
+/**
+ * Industry-standard branding vocabulary controlling what a brand block renders.
+ * - 'signet'   — symbol/mark only (the image)
+ * - 'logotype' — wordmark only (the text)
+ * - 'logo'     — combined (image + text); falls back to text-only when image absent
+ */
+type BrandDisplay = 'signet' | 'logotype' | 'logo';
+
+interface ThemeSwitcherMessages {
+    toggleToDark: string;
+    toggleToLight: string;
+    /** Aria label when the tenant disabled dark mode (switcher is locked). */
+    unavailable: string;
+}
+declare const DEFAULT_THEME_SWITCHER_MESSAGES: ThemeSwitcherMessages;
+
+declare class ThemeSwitcherComponent {
+    readonly messages: i0.InputSignal<ThemeSwitcherMessages>;
+    private readonly themeService;
+    private readonly branding;
+    protected readonly isDark: i0.Signal<boolean>;
+    protected readonly available: i0.Signal<boolean>;
+    protected readonly ariaLabel: i0.Signal<string>;
+    protected readonly lightIcon: _progress_kendo_svg_icons.SVGIcon;
+    protected readonly darkIcon: _progress_kendo_svg_icons.SVGIcon;
+    protected onToggle(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ThemeSwitcherComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<ThemeSwitcherComponent, "mm-theme-switcher", never, { "messages": { "alias": "messages"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Per-tenant branding. Source of truth is the `SystemUIBranding`
+ * CK runtime entity (one record per tenant, `rtWellKnownName = 'Branding'`).
+ * Loaded via GraphQL, mirrored into a signal for consumers.
+ */
+declare class BrandingDataSource {
+    private readonly getBrandingGQL;
+    private readonly createBrandingGQL;
+    private readonly updateBrandingGQL;
+    private readonly defaults;
+    private readonly state;
+    readonly branding: i0.Signal<BrandingData>;
+    load(): Promise<void>;
+    save(update: BrandingUpdate): Promise<BrandingData>;
+    resetToDefaults(): Promise<void>;
+    private buildInput;
+    private runCreate;
+    private runUpdate;
+    private paletteToInput;
+    private mapFromServer;
+    private paletteFromServer;
+    /**
+     * Convert a byte array from a GraphQL `[Byte]` field into a data URL.
+     * Returns null for null/undefined/empty input. MIME type is detected from
+     * the first few bytes (magic numbers) so <img src> works without a
+     * server-provided content-type.
+     */
+    private bytesToDataUrl;
+    private detectImageMime;
+    private blobToDataUrl;
+    /**
+     * Three-value binary resolution for save():
+     * - `null` → caller wants the asset cleared; forward null to the server.
+     * - `undefined` → caller left the slot untouched; omit the field so the
+     *   server keeps the existing blob.
+     * - `File` → caller uploaded a new asset; serialize to byte array.
+     */
+    private prepareBinary;
+    static ɵfac: i0.ɵɵFactoryDeclaration<BrandingDataSource, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<BrandingDataSource>;
+}
+
+/**
+ * Light/dark mode toggle backed by `localStorage` + `<html data-theme="...">`.
+ * Pure mode toggle; palette generation lives in `BrandingApplicationService`.
+ */
+declare class ThemeService {
+    private readonly document;
+    private readonly renderer;
+    private readonly isDarkSignal;
+    readonly isDark: i0.Signal<boolean>;
+    constructor();
+    toggleTheme(): void;
+    setDark(isDark: boolean): void;
+    private applyTheme;
+    private getInitialThemeIsDark;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ThemeService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ThemeService>;
+}
+
+type ColorPaletteShades = Record<number, string>;
+/**
+ * Writes tenant branding (Kendo color vars, gradients, favicon, document
+ * title) inline on <html>. An effect re-applies the correct palette when
+ * either the theme mode or the branding data changes, so mode toggles after
+ * a save don't leave stale inline values behind.
+ */
+declare class BrandingApplicationService {
+    private document;
+    private themeService;
+    private brandingDataSource;
+    private fallbackAssets;
+    private static readonly BRANDED_VARS;
+    constructor();
+    apply(data: BrandingData, palette: ThemePalette): void;
+    applyThemeColors(palette: ThemePalette): void;
+    applyFavicon(faviconUrl: string | null): void;
+    private clearInlineBrandingVars;
+    private setIf;
+    private applyColorPalette;
+    private applyNeutralColors;
+    generatePalette(baseColor: string): ColorPaletteShades;
+    private hexToRgb;
+    private rgbToHsl;
+    private hslToHex;
+    private rgbToHex;
+    private getContrastColor;
+    static ɵfac: i0.ɵɵFactoryDeclaration<BrandingApplicationService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<BrandingApplicationService>;
+}
+
+/**
+ * Optional function the host supplies to translate a breadcrumb key from
+ * `route.data['breadcrumb']` into a localized string. The library has no i18n
+ * dependency; without a translator the breadcrumb key is rendered verbatim.
+ */
+type OctoTitleTranslator = (key: string) => string;
+declare const OCTO_TITLE_TRANSLATOR: InjectionToken<OctoTitleTranslator>;
+/**
+ * `TitleStrategy` that composes `<branding.appTitle> | <route.breadcrumb>`
+ * into `document.title` on every navigation, and re-applies on
+ * `BrandingDataSource.branding()` changes (e.g. after Settings save).
+ *
+ * Wire as the application's `TitleStrategy`:
+ * ```ts
+ * { provide: TitleStrategy, useExisting: AppTitleService }
+ * ```
+ *
+ * Optional translation of the breadcrumb key is supplied through
+ * {@link OCTO_TITLE_TRANSLATOR}; without it the key from `route.data` is used
+ * as-is.
+ *
+ * `BrandingDataSource` is resolved lazily via `injector.get()` rather than
+ * field-injected. The router constructs `TitleStrategy` eagerly during
+ * `APP_INITIALIZER`, before the host's tenant config has loaded. A direct
+ * field-inject of `BrandingDataSource` here would chain into Apollo's
+ * factory, which reads `tenantId` while it is still `undefined` and bakes
+ * `/tenants/undefined/GraphQL` into the request URI. Lazy resolution defers
+ * the chain to the first navigation, by which time config is loaded.
+ */
+declare class AppTitleService extends TitleStrategy {
+    private readonly title;
+    private readonly translator;
+    private readonly injector;
+    private lastRouterState?;
+    private brandingEffectInitialized;
+    updateTitle(routerState: RouterStateSnapshot): void;
+    private ensureBrandingSubscription;
+    private applyTitle;
+    private getDeepestBreadcrumb;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AppTitleService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AppTitleService>;
+}
+
+/**
+ * Framework-agnostic stub matching the runtime shape of `BrandingDataSource`.
+ * The async methods are plain functions; consumers wrap them in their own
+ * spy primitive (`jasmine.createSpy`, `jest.fn`, `vi.fn`) when they need
+ * call assertions. Casting `branding` back to `WritableSignal` lets specs
+ * drive state changes.
+ */
+interface BrandingDataSourceStub {
+    branding: WritableSignal<BrandingData>;
+    load: () => Promise<void>;
+    save: (u: BrandingUpdate) => Promise<BrandingData>;
+    resetToDefaults: () => Promise<void>;
+}
+declare function createBrandingStub(overrides?: Partial<BrandingData>): BrandingDataSourceStub;
+/** Convenience: returns a Provider that injects the stub as BrandingDataSource. */
+declare function provideBrandingTesting(stub?: BrandingDataSourceStub): Provider;
+
+export { AppTitleService, BrandingApplicationService, BrandingDataSource, DEFAULT_THEME_SWITCHER_MESSAGES, NEUTRAL_BRANDING_DEFAULTS, NEUTRAL_FALLBACK_ASSETS, OCTO_BRANDING_DEFAULTS, OCTO_BRANDING_FALLBACK_ASSETS, OCTO_TITLE_TRANSLATOR, ThemeService, ThemeSwitcherComponent, createBrandingStub, provideBrandingTesting, provideOctoBranding };
+export type { BrandDisplay, BrandingData, BrandingDataSourceStub, BrandingUpdate, OctoBrandingConfig, OctoBrandingFallbackAssets, OctoTitleTranslator, ThemeGradient, ThemePalette, ThemeSwitcherMessages };