@skyux/theme 13.0.0-alpha.0 → 13.0.0-alpha.10

package/fesm2022/skyux-theme.mjs

@@ -1,5 +1,5 @@
 import * as i0 from '@angular/core';
-import { Injectable, Optional, Input, Directive, NgModule, inject, ChangeDetectorRef, HostBinding, DOCUMENT, NgZone, DestroyRef, makeEnvironmentProviders, provideAppInitializer, RendererFactory2 } from '@angular/core';
+import { Injectable, inject, DOCUMENT, Optional, Input, Directive, NgModule, ChangeDetectorRef, HostBinding, NgZone, DestroyRef, makeEnvironmentProviders, provideAppInitializer, RendererFactory2 } from '@angular/core';
 import { getIconManifest } from '@skyux/icons';
 import FontFaceObserver from 'fontfaceobserver';
 import { take, takeUntil } from 'rxjs/operators';
@@ -237,14 +237,25 @@ class SkyThemeBrand {
     /**
      * Creates a new theme brand.
      * @param name The name of the theme brand.
+     * @param version The version of the theme brand.
      * @param hostClass The class on the host element which child components should reference when
-     * adjusting for a specified theme brand. This defaults to `sky-theme-brand-<name>
+     * adjusting for a specified theme brand. This defaults to `sky-theme-brand-<name>`
+     * @param styleUrl The URL of the stylesheet to load for this brand
+     * @param sriHash The subresource integrity hash for the stylesheet
+     * @param title The title to display for this brand
+     * @param faviconUrl The URL of the favicon to use for this brand
+     * @param maskIcon The mask icon configuration for this brand
      */
-    constructor(name, version, hostClass) {
+    constructor(name, version, hostClass, styleUrl, sriHash, title, faviconUrl, maskIcon) {
         this.name = name;
         this.version = version;
+        this.styleUrl = styleUrl;
+        this.sriHash = sriHash;
+        this.title = title;
+        this.faviconUrl = faviconUrl;
+        this.maskIcon = maskIcon;
         this.hostClass = hostClass;
-        if (!/\d+\.\d+\.\d+(?:-(?:alpha|beta|rc)\.\d)*$/.test(version)) {
+        if (!/^(\d+|\d+\.\d+\.\d+)(?:-(?:alpha|beta|rc)\.\d+)*$/.test(version)) {
             throw new Error(`Invalid version format "${version}" for theme brand "${name}".`);
         }
     }
@@ -262,6 +273,21 @@ class SkyThemeBrand {
         if (this.hostClass !== defaultHostClass) {
             result.hostClass = this.hostClass;
         }
+        if (this.styleUrl) {
+            result.styleUrl = this.styleUrl;
+        }
+        if (this.sriHash) {
+            result.sriHash = this.sriHash;
+        }
+        if (this.title) {
+            result.title = this.title;
+        }
+        if (this.faviconUrl) {
+            result.faviconUrl = this.faviconUrl;
+        }
+        if (this.maskIcon) {
+            result.maskIcon = this.maskIcon;
+        }
         return result;
     }
     /**
@@ -269,13 +295,172 @@ class SkyThemeBrand {
      * Deserializes a JSON object to a SkyThemeBrand instance.
      */
     static deserialize(data) {
-        return new SkyThemeBrand(data.name, data.version, data.hostClass);
+        return new SkyThemeBrand(data.name, data.version, data.hostClass, data.styleUrl, data.sriHash, data.title, data.faviconUrl, data.maskIcon);
     }
     #buildDefaultHostClassName() {
         return `sky-theme-brand-${this.name}`;
     }
 }
 
+const BRAND_BLACKBAUD = 'blackbaud';
+// Commonly-used icon configurations. Appending these to the head element will
+// override any existing link elements with the same attribute values. When
+// they are removed, the previous favicon link elements will take effect again.
+const FAVICON_CONFIGS = [
+    { rel: 'apple-touch-icon', sizes: '180x180' },
+    { rel: 'icon', sizes: '32x32' },
+    { rel: 'icon', sizes: '16x16' },
+];
+/**
+ * @internal
+ * Provides methods for managing theme branding including brand registration,
+ * stylesheet management, and host class updates.
+ */
+class SkyThemeBrandService {
+    #document = inject(DOCUMENT);
+    #stylesheetEl;
+    #faviconEls = [];
+    #maskIconEl;
+    #registeredBrands = new Map();
+    /**
+     * Registers a brand for use in themes.
+     * @param brand The brand to register.
+     */
+    registerBrand(brand) {
+        this.#registeredBrands.set(brand.name, brand);
+    }
+    /**
+     * Unregisters a brand.
+     * @param name The name of the brand to unregister.
+     */
+    unregisterBrand(name) {
+        this.#registeredBrands.delete(name);
+    }
+    /**
+     * Updates all brand-related styling and classes for the host element.
+     * This consolidates brand stylesheet updates and host class management,
+     * and automatically resolves registered brands.
+     * @param hostEl The host element to update.
+     * @param renderer The renderer to use for DOM manipulation.
+     * @param brand The brand to apply (will be resolved if registered version exists).
+     * @param previousBrand The previous brand to clean up.
+     */
+    updateBrand(hostEl, renderer, brand, previousBrand) {
+        // Resolve to registered brand if available
+        if (brand) {
+            brand = this.#registeredBrands.get(brand.name) ?? brand;
+        }
+        const previousClass = previousBrand?.hostClass;
+        const currentClass = brand?.hostClass;
+        // Update host classes if they've changed
+        if (!previousClass || previousClass !== currentClass) {
+            this.#updateBrandHostClass(hostEl, renderer, previousClass, currentClass);
+            this.#updateBrandStylesheet(renderer, brand, previousBrand);
+        }
+        this.#updateFavicon(renderer, brand);
+    }
+    /**
+     * Destroys the brand service, cleaning up any brand stylesheets.
+     */
+    destroy() {
+        this.#removeBrandStylesheet();
+    }
+    #updateBrandStylesheet(renderer, currentBrand, previousBrand) {
+        if (previousBrand && previousBrand.name !== BRAND_BLACKBAUD) {
+            this.#removeBrandStylesheet();
+        }
+        if (currentBrand && currentBrand.name !== BRAND_BLACKBAUD) {
+            this.#addBrandStylesheet(renderer, currentBrand);
+        }
+    }
+    #updateBrandHostClass(hostEl, renderer, previousClass, currentClass) {
+        if (previousClass) {
+            renderer.removeClass(hostEl, previousClass);
+        }
+        if (currentClass && !previousClass) {
+            renderer.addClass(hostEl, 'sky-theme-brand-base');
+        }
+        else if (!currentClass && previousClass) {
+            renderer.removeClass(hostEl, 'sky-theme-brand-base');
+        }
+        if (currentClass) {
+            renderer.addClass(hostEl, currentClass);
+        }
+    }
+    #addBrandStylesheet(renderer, brand) {
+        if (brand.name !== BRAND_BLACKBAUD) {
+            // Use styleUrl if provided, otherwise build the default URL
+            const styleUrl = brand.styleUrl ||
+                `https://sky.blackbaudcdn.net/static/skyux-brand-${brand.name}/${brand.version}/assets/scss/${brand.name}.css`;
+            this.#stylesheetEl = renderer.createElement('link');
+            renderer.setAttribute(this.#stylesheetEl, 'rel', 'stylesheet');
+            renderer.setAttribute(this.#stylesheetEl, 'href', styleUrl);
+            if (brand.sriHash) {
+                renderer.setAttribute(this.#stylesheetEl, 'integrity', brand.sriHash);
+                renderer.setAttribute(this.#stylesheetEl, 'crossorigin', 'anonymous');
+            }
+            this.#appendToHead(renderer, this.#stylesheetEl);
+        }
+    }
+    #removeBrandStylesheet() {
+        if (this.#stylesheetEl) {
+            this.#stylesheetEl.remove();
+            this.#stylesheetEl = undefined;
+        }
+    }
+    #updateFavicon(renderer, brand) {
+        if (brand?.faviconUrl) {
+            const faviconUrl = brand.faviconUrl;
+            // Create favicon elements if they don't exist, or reuse existing ones
+            while (this.#faviconEls.length < FAVICON_CONFIGS.length) {
+                const faviconEl = renderer.createElement('link');
+                this.#faviconEls.push(faviconEl);
+                this.#appendToHead(renderer, faviconEl);
+            }
+            // Update each favicon element with its configuration
+            for (let i = 0; i < FAVICON_CONFIGS.length; i++) {
+                const config = FAVICON_CONFIGS[i];
+                const faviconEl = this.#faviconEls[i];
+                renderer.setAttribute(faviconEl, 'rel', config.rel);
+                renderer.setAttribute(faviconEl, 'sizes', config.sizes);
+                renderer.setAttribute(faviconEl, 'href', faviconUrl);
+            }
+        }
+        else {
+            // Remove all favicon elements when no favicon URL is provided
+            for (const faviconEl of this.#faviconEls) {
+                faviconEl.remove();
+            }
+            this.#faviconEls = [];
+        }
+        // Handle mask icon
+        if (brand?.maskIcon) {
+            if (!this.#maskIconEl) {
+                this.#maskIconEl = renderer.createElement('link');
+                this.#appendToHead(renderer, this.#maskIconEl);
+            }
+            renderer.setAttribute(this.#maskIconEl, 'rel', 'mask-icon');
+            renderer.setAttribute(this.#maskIconEl, 'href', brand.maskIcon.url);
+            renderer.setAttribute(this.#maskIconEl, 'color', brand.maskIcon.color);
+        }
+        else if (this.#maskIconEl) {
+            this.#maskIconEl.remove();
+            this.#maskIconEl = undefined;
+        }
+    }
+    #appendToHead(renderer, el) {
+        renderer.appendChild(this.#document.head, el);
+    }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.0.5", ngImport: i0, type: SkyThemeBrandService, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
+    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.0.5", ngImport: i0, type: SkyThemeBrandService, providedIn: 'root' }); }
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.0.5", ngImport: i0, type: SkyThemeBrandService, decorators: [{
+            type: Injectable,
+            args: [{
+                    providedIn: 'root',
+                }]
+        }] });
+
 /**
  * Specifies the theme and mode to be applied to a host element.
  */
@@ -335,6 +520,7 @@ function assertCurrentSettings(currentSettings) {
  * Provides methods for updating and handling changes to the current theme.
  */
 class SkyThemeService {
+    #brandSvc = inject(SkyThemeBrandService);
     /**
      * Notifies consumers when the current theme settings have changed.
      */
@@ -342,7 +528,6 @@ class SkyThemeService {
         return this.#_settingsObs;
     }
     #current;
-    #brandLinkElement;
     #hostEl;
     #renderer;
     #settings;
@@ -357,10 +542,17 @@ class SkyThemeService {
      * @param hostEl The host element under which themed components are rendered.
      * @param renderer A Renderer2 instance for updating the host element with theme changes.
      * @param theme The initial theme.
+     * @param registeredBrands An initial set of brands to register. Additional brands can
+     * be registered later via the registerBrand() method.
      */
-    init(hostEl, renderer, theme) {
+    init(hostEl, renderer, theme, registeredBrands) {
         this.#hostEl = hostEl;
         this.#renderer = renderer;
+        if (registeredBrands) {
+            for (const brand of registeredBrands) {
+                this.#brandSvc.registerBrand(brand);
+            }
+        }
         this.setTheme(theme);
     }
     /**
@@ -369,6 +561,7 @@ class SkyThemeService {
      */
     destroy() {
         this.#settings.complete();
+        this.#brandSvc.destroy();
         this.#hostEl = this.#renderer = undefined;
     }
     /**
@@ -387,7 +580,7 @@ class SkyThemeService {
     }
     /**
      * Updates the current theme brand.
-     * @param brand The new theme brand to apply.
+     * @param brand The new theme brand to apply, or undefined to clear the current brand.
      */
     setThemeBrand(brand) {
         this.#updateThemeProperty('brand', brand);
@@ -406,13 +599,28 @@ class SkyThemeService {
         this.#applyThemeClass(previous, settings, 'theme');
         this.#applyThemeClass(previous, settings, 'mode', 'supportedModes');
         this.#applyThemeClass(previous, settings, 'spacing', 'supportedSpacing');
-        this.#applyThemeClass(previous, settings, 'brand');
+        if (this.#hostEl) {
+            // Validate branding support
+            if (settings.brand && !settings.theme.supportsBranding) {
+                throw new Error('Branding is not supported for the given theme.');
+            }
+            this.#brandSvc.updateBrand(this.#hostEl, this.#getRenderer(), settings.brand ??
+                (settings.theme === SkyTheme.presets.modern
+                    ? new SkyThemeBrand('blackbaud', '1.0.0')
+                    : undefined), previous?.brand);
+        }
         this.#settings.next({
             currentSettings: settings,
             previousSettings: previous,
         });
         this.#current = settings;
     }
+    registerBrand(brand) {
+        this.#brandSvc.registerBrand(brand);
+    }
+    unregisterBrand(name) {
+        this.#brandSvc.unregisterBrand(name);
+    }
     #updateThemeProperty(property, value) {
         const current = this.#current;
         assertCurrentSettings(current);
@@ -427,7 +635,7 @@ class SkyThemeService {
                 break;
             default:
         }
-        if (supportedValues && !supportedValues.includes(value)) {
+        if (supportedValues && value && !supportedValues.includes(value)) {
             throw new Error(`The current theme does not support the specified ${property}.`);
         }
         const updatedSettings = {
@@ -444,60 +652,18 @@ class SkyThemeService {
         const previousClass = previous?.[prop]?.hostClass;
         const currentClass = currentSetting?.hostClass;
         if (!previousClass || previousClass !== currentClass) {
-            this.#updateHostClass(prop, previousClass, currentClass, currentSetting, current, supportedProp);
-            if (prop === 'brand') {
-                if (!current.theme.supportsBranding && currentSetting) {
-                    throw new Error('Branding is not supported for the given theme.');
-                }
-                this.#updateBrandStylesheet(current.brand, previous?.brand);
-            }
+            this.#updateHostClass(previousClass, currentClass, currentSetting, current, supportedProp);
         }
     }
-    #updateBrandStylesheet(currentBrand, previousBrand) {
-        if (currentBrand &&
-            currentBrand.name !== 'blackbaud' &&
-            previousBrand !== currentBrand) {
-            this.#addBrandStylesheet(currentBrand);
-        }
-        else {
-            this.#removeBrandStylesheet();
-        }
-    }
-    #updateHostClass(prop, previousClass, currentClass, currentSetting, current, supportedProp) {
+    #updateHostClass(previousClass, currentClass, currentSetting, current, supportedProp) {
         if (previousClass) {
             this.#removeHostClass(previousClass);
         }
-        if (prop === 'brand') {
-            if (currentClass && !previousClass) {
-                this.#addHostClass('sky-theme-brand-base');
-            }
-            else if (!currentClass && previousClass) {
-                this.#removeHostClass('sky-theme-brand-base');
-            }
-        }
         if (currentClass &&
             this.#isSupportedProperty(currentSetting, current, supportedProp)) {
             this.#addHostClass(currentClass);
         }
     }
-    #addBrandStylesheet(brand) {
-        if (brand.name !== 'blackbaud') {
-            const cssPath = `https://sky.blackbaudcdn.net/static/skyux-brand-${brand.name}/${brand.version}/assets/scss/${brand.name}.css`;
-            // Create a link element via Angular's renderer to avoid SSR troubles
-            this.#brandLinkElement = this.#getRenderer().createElement('link');
-            // Add the style to the head section
-            this.#getRenderer().appendChild(this.#hostEl, this.#brandLinkElement);
-            // Set type of the link item and path to the css file
-            this.#getRenderer().setProperty(this.#brandLinkElement, 'rel', 'stylesheet');
-            this.#getRenderer().setProperty(this.#brandLinkElement, 'href', cssPath);
-        }
-    }
-    #removeBrandStylesheet() {
-        if (this.#brandLinkElement) {
-            this.#getRenderer().removeChild(this.#hostEl, this.#brandLinkElement);
-            this.#brandLinkElement = undefined;
-        }
-    }
     #addHostClass(className) {
         this.#getRenderer().addClass(this.#hostEl, className);
     }
@@ -541,15 +707,8 @@ class SkyAppStyleLoader {
         else {
             themePromise = Promise.resolve();
         }
-        const fontAwesome = new FontFaceObserver('FontAwesome');
-        const skyuxIcons = new FontFaceObserver('skyux-icons');
         const blackbaudSans = new FontFaceObserver('BLKB Sans');
         return Promise.all([
-            // Specify a character for FontAwesome since some browsers will fail to detect
-            // when the font is loaded unless a known character with a different width
-            // than the default is not specified.
-            fontAwesome.load('\uf0fc', SkyAppStyleLoader.LOAD_TIMEOUT),
-            skyuxIcons.load('\ue999', SkyAppStyleLoader.LOAD_TIMEOUT),
             blackbaudSans.load(undefined, SkyAppStyleLoader.LOAD_TIMEOUT),
             themePromise,
         ])