feat(platform-browser): add CssVarNamespacer

dgp1130 · dgp1130 · commit 53771f20bd70 · 2026-03-02T16:50:06.000-08:00
Adds the CssVarNamespacer utility service for prefixing CSS variables with MicA namespace dynamically.
diff --git a/goldens/public-api/platform-browser/index.api.md b/goldens/public-api/platform-browser/index.api.md
@@ -54,6 +54,15 @@ export class By {
 // @public
 export function createApplication(options?: ApplicationConfig, context?: BootstrapContext): Promise<ApplicationRef>;
 
+// @public
+export class CssVarNamespacer {
+    namespace(name: string): string;
+    // (undocumented)
+    static ɵfac: i0.ɵɵFactoryDeclaration<CssVarNamespacer, never>;
+    // (undocumented)
+    static ɵprov: i0.ɵɵInjectableDeclaration<CssVarNamespacer>;
+}
+
 // @public
 export function disableDebugTools(): void;
 
diff --git a/packages/platform-browser/src/dom/css_var_namespacer.ts b/packages/platform-browser/src/dom/css_var_namespacer.ts
@@ -0,0 +1,47 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import {inject, Injectable} from '@angular/core';
+import {CSS_VAR_NAMESPACE} from './dom_renderer';
+
+/**
+ * A service that can be used to manually namespace CSS variable names at runtime.
+ * This is useful when reading or setting CSS variables dynamically in JavaScript that
+ * were transformed by the compiler during the build.
+ *
+ * @publicApi
+ */
+@Injectable({providedIn: 'root'})
+export class CssVarNamespacer {
+  private readonly namespacePrefix = inject(CSS_VAR_NAMESPACE, {optional: true}) ?? '';
+
+  /**
+   * Prepends the namespace prefix to a CSS variable name.
+   *
+   * @param name The CSS variable name to namespace, including the leading `--`.
+   * @returns The namespaced CSS variable name, including the leading `--`. Returns the input
+   *     unchanged if no namespace is configured.
+   */
+  namespace(name: string): string {
+    // Validate that the whole `--foo` variable is passed in.
+    if (typeof ngDevMode === 'undefined' || ngDevMode) {
+      if (!name.startsWith('--')) {
+        throw new Error(
+          `CSS variable names passed to \`CssVarNamespacer\` must start with '--', got: '${name}'`,
+        );
+      }
+    }
+
+    // We want to support libraries which might be used by applications which do and don't
+    // namespace variables. Therefore the library always needs to use `CssVarNamespacer`, even
+    // though the application may not actually be namespacing anything.
+    if (!this.namespacePrefix) return name;
+
+    return `--${this.namespacePrefix}${name.substring('--'.length)}`;
+  }
+}
diff --git a/packages/platform-browser/src/platform-browser.ts b/packages/platform-browser/src/platform-browser.ts
@@ -17,6 +17,7 @@ export {
 export {Meta, MetaDefinition} from './browser/meta';
 export {Title} from './browser/title';
 export {disableDebugTools, enableDebugTools} from './browser/tools/tools';
+export {CssVarNamespacer} from './dom/css_var_namespacer';
 export {By} from './dom/debug/by';
 export {REMOVE_STYLES_ON_COMPONENT_DESTROY} from './dom/dom_renderer';
 export {EVENT_MANAGER_PLUGINS, EventManager} from './dom/events/event_manager';
diff --git a/packages/platform-browser/test/dom/css_var_namespacer_spec.ts b/packages/platform-browser/test/dom/css_var_namespacer_spec.ts
@@ -0,0 +1,43 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import {TestBed} from '@angular/core/testing';
+import {CssVarNamespacer} from '../../src/dom/css_var_namespacer';
+import {provideCssVarNamespacing} from '../../src/dom/dom_renderer';
+
+describe('CssVarNamespacer', () => {
+  it('should namespace variables when `CSS_VAR_NAMESPACE` is provided', () => {
+    TestBed.configureTestingModule({
+      providers: [CssVarNamespacer, provideCssVarNamespacing('test-app_')],
+    });
+
+    const namespacer = TestBed.inject(CssVarNamespacer);
+
+    expect(namespacer.namespace('--my-var')).toBe('--test-app_my-var');
+  });
+
+  it('should not namespace variables when `CSS_VAR_NAMESPACE` is not provided', () => {
+    TestBed.configureTestingModule({
+      providers: [CssVarNamespacer],
+    });
+
+    const namespacer = TestBed.inject(CssVarNamespacer);
+
+    expect(namespacer.namespace('--my-var')).toBe('--my-var');
+  });
+
+  it('throws an error when a variable is passed in without the leading `--`', () => {
+    TestBed.configureTestingModule({
+      providers: [CssVarNamespacer],
+    });
+
+    const namespacer = TestBed.inject(CssVarNamespacer);
+
+    expect(() => namespacer.namespace('my-var')).toThrowError(/must start with '--'/);
+  });
+});
