feat(themes): add support for modular themes and custom themes (#30651)

brandyscarney · brandyscarney · commit 1aa7c35da19b · 2025-09-25T15:39:40.000-04:00
Issue number: internal

---------

## What is the new behavior?
- Moves `openURL` out of the `theme` utils because it makes more sense
in `helpers`
- Adds support for the default `default.tokens.ts` design tokens file
- Adds support for custom theme set globally and on a component 

## Does this introduce a breaking change?

- [ ] Yes
- [x] No

## Other information

Requires additional changes in order to test.

---------

Co-authored-by: Brandy Smith &lt;6577830+brandyscarney@users.noreply.github.com&gt;
diff --git a/core/src/components/back-button/back-button.tsx b/core/src/components/back-button/back-button.tsx
@@ -3,8 +3,8 @@ import type { ComponentInterface } from '@stencil/core';
 import { Component, Element, Host, Prop, h } from '@stencil/core';
 import type { ButtonInterface } from '@utils/element-interface';
 import type { Attributes } from '@utils/helpers';
-import { inheritAriaAttributes } from '@utils/helpers';
-import { createColorClasses, hostContext, openURL } from '@utils/theme';
+import { inheritAriaAttributes, openURL } from '@utils/helpers';
+import { createColorClasses, hostContext } from '@utils/theme';
 import { arrowBackSharp, chevronBack } from 'ionicons/icons';
 
 import { config } from '../../global/config';
diff --git a/core/src/components/breadcrumb/breadcrumb.tsx b/core/src/components/breadcrumb/breadcrumb.tsx
@@ -3,8 +3,8 @@ import dotsThreeRegular from '@phosphor-icons/core/assets/regular/dots-three.svg
 import type { ComponentInterface, EventEmitter } from '@stencil/core';
 import { Component, Element, Event, Host, Prop, h } from '@stencil/core';
 import type { Attributes } from '@utils/helpers';
-import { inheritAriaAttributes } from '@utils/helpers';
-import { createColorClasses, hostContext, openURL } from '@utils/theme';
+import { inheritAriaAttributes, openURL } from '@utils/helpers';
+import { createColorClasses, hostContext } from '@utils/theme';
 import { chevronForwardOutline, ellipsisHorizontal } from 'ionicons/icons';
 
 import { config } from '../../global/config';
diff --git a/core/src/components/button/button.tsx b/core/src/components/button/button.tsx
@@ -2,9 +2,9 @@ import type { ComponentInterface, EventEmitter } from '@stencil/core';
 import { Component, Element, Event, Host, Prop, Watch, State, forceUpdate, h } from '@stencil/core';
 import type { AnchorInterface, ButtonInterface } from '@utils/element-interface';
 import type { Attributes } from '@utils/helpers';
-import { inheritAriaAttributes, hasShadowDom } from '@utils/helpers';
+import { inheritAriaAttributes, hasShadowDom, openURL } from '@utils/helpers';
 import { printIonWarning } from '@utils/logging';
-import { createColorClasses, hostContext, openURL } from '@utils/theme';
+import { createColorClasses, hostContext } from '@utils/theme';
 
 import { getIonTheme, getIonMode } from '../../global/ionic-global';
 import type { AnimationBuilder, Color } from '../../interface';
diff --git a/core/src/components/card/card.tsx b/core/src/components/card/card.tsx
@@ -2,8 +2,8 @@ import type { ComponentInterface } from '@stencil/core';
 import { Element, Component, Host, Prop, h } from '@stencil/core';
 import type { AnchorInterface, ButtonInterface } from '@utils/element-interface';
 import type { Attributes } from '@utils/helpers';
-import { inheritAttributes } from '@utils/helpers';
-import { createColorClasses, openURL } from '@utils/theme';
+import { inheritAttributes, openURL } from '@utils/helpers';
+import { createColorClasses } from '@utils/theme';
 
 import { getIonTheme } from '../../global/ionic-global';
 import type { AnimationBuilder, Color, Theme } from '../../interface';
diff --git a/core/src/components/fab-button/fab-button.tsx b/core/src/components/fab-button/fab-button.tsx
@@ -2,9 +2,9 @@ import xRegular from '@phosphor-icons/core/assets/regular/x.svg';
 import type { ComponentInterface, EventEmitter } from '@stencil/core';
 import { Component, Element, Event, Host, Prop, h } from '@stencil/core';
 import type { AnchorInterface, ButtonInterface } from '@utils/element-interface';
-import { inheritAriaAttributes } from '@utils/helpers';
+import { inheritAriaAttributes, openURL } from '@utils/helpers';
 import type { Attributes } from '@utils/helpers';
-import { createColorClasses, hostContext, openURL } from '@utils/theme';
+import { createColorClasses, hostContext } from '@utils/theme';
 import { close } from 'ionicons/icons';
 
 import { config } from '../../global/config';
diff --git a/core/src/components/item/item.tsx b/core/src/components/item/item.tsx
@@ -3,8 +3,8 @@ import type { ComponentInterface } from '@stencil/core';
 import { Component, Element, Host, Listen, Prop, State, Watch, forceUpdate, h } from '@stencil/core';
 import type { AnchorInterface, ButtonInterface } from '@utils/element-interface';
 import type { Attributes } from '@utils/helpers';
-import { inheritAttributes, raf } from '@utils/helpers';
-import { createColorClasses, hostContext, openURL } from '@utils/theme';
+import { inheritAttributes, raf, openURL } from '@utils/helpers';
+import { createColorClasses, hostContext } from '@utils/theme';
 import { chevronForward } from 'ionicons/icons';
 
 import { config } from '../../global/config';
diff --git a/core/src/components/router-link/router-link.tsx b/core/src/components/router-link/router-link.tsx
@@ -1,6 +1,7 @@
 import type { ComponentInterface } from '@stencil/core';
 import { Component, Host, Prop, h } from '@stencil/core';
-import { createColorClasses, openURL } from '@utils/theme';
+import { openURL } from '@utils/helpers';
+import { createColorClasses } from '@utils/theme';
 
 import { getIonTheme } from '../../global/ionic-global';
 import type { AnimationBuilder, Color } from '../../interface';
diff --git a/core/src/global/ionic-global.ts b/core/src/global/ionic-global.ts
@@ -1,7 +1,10 @@
 import { Build, getMode, setMode, getElement } from '@stencil/core';
 import { printIonWarning } from '@utils/logging';
+import { applyGlobalTheme } from '@utils/theme';
 
 import type { IonicConfig, Mode, Theme } from '../interface';
+import { defaultTheme as baseTheme } from '../themes/base/default.tokens';
+import type { Theme as BaseTheme } from '../themes/base/default.tokens';
 import { shouldUseCloseWatcher } from '../utils/hardware-back-button';
 import { isPlatform, setupPlatforms } from '../utils/platform';
 
@@ -225,6 +228,16 @@ export const initialize = (userConfig: IonicConfig = {}) => {
   doc.documentElement.setAttribute('theme', defaultTheme);
   doc.documentElement.classList.add(defaultTheme);
 
+  const customTheme: BaseTheme | undefined = configObj.customTheme;
+
+  // Apply base theme, or combine with custom theme if provided
+  if (customTheme) {
+    const combinedTheme = applyGlobalTheme(baseTheme, customTheme);
+    config.set('customTheme', combinedTheme);
+  } else {
+    applyGlobalTheme(baseTheme);
+  }
+
   if (config.getBoolean('_testing')) {
     config.set('animated', false);
   }
diff --git a/core/src/index.ts b/core/src/index.ts
@@ -7,12 +7,11 @@ export { mdTransitionAnimation } from './utils/transition/md.transition';
 export { getTimeGivenProgression } from './utils/animation/cubic-bezier';
 export { createGesture } from './utils/gesture';
 export { initialize } from './global/ionic-global';
-export { componentOnReady } from './utils/helpers';
+export { componentOnReady, openURL } from './utils/helpers';
 export { LogLevel } from './utils/logging';
 export { isPlatform, Platforms, PlatformConfig, getPlatforms } from './utils/platform';
 export { IonicSafeString } from './utils/sanitization';
 export { IonicConfig, getMode, setupConfig } from './utils/config';
-export { openURL } from './utils/theme';
 export {
   LIFECYCLE_WILL_ENTER,
   LIFECYCLE_DID_ENTER,
diff --git a/core/src/themes/base/default.tokens.ts b/core/src/themes/base/default.tokens.ts
@@ -0,0 +1,10 @@
+export const defaultTheme = {
+  palette: {
+    light: {},
+    dark: {
+      enabled: 'system',
+    },
+  },
+};
+
+export type Theme = typeof defaultTheme;
diff --git a/core/src/utils/config.ts b/core/src/utils/config.ts
@@ -364,6 +364,9 @@ export interface IonicConfig {
   scrollAssist?: boolean;
   hideCaretOnScroll?: boolean;
 
+  // Theme configs
+  customTheme?: any;
+
   // INTERNAL configs
   // TODO(FW-2832): types
   persistConfig?: boolean;
diff --git a/core/src/utils/helpers.spec.ts b/core/src/utils/helpers.spec.ts
@@ -1,4 +1,4 @@
-import { inheritAriaAttributes } from './helpers';
+import { deepMerge, inheritAriaAttributes } from './helpers';
 
 describe('inheritAriaAttributes', () => {
   it('should inherit aria attributes', () => {
@@ -40,3 +40,26 @@ describe('inheritAriaAttributes', () => {
     });
   });
 });
+
+describe('deepMerge', () => {
+  it('should merge objects', () => {
+    const target = { a: 1, b: 2 };
+    const source = { b: 3, c: 4 };
+    const result = deepMerge(target, source);
+    expect(result).toEqual({ a: 1, b: 3, c: 4 });
+  });
+
+  it('should merge objects when target is undefined', () => {
+    const target = undefined;
+    const source = { a: 1, b: 2 };
+    const result = deepMerge(target, source);
+    expect(result).toEqual({ a: 1, b: 2 });
+  });
+
+  it('should merge objects when source is undefined', () => {
+    const target = { a: 1, b: 2 };
+    const source = undefined;
+    const result = deepMerge(target, source);
+    expect(result).toEqual({ a: 1, b: 2 });
+  });
+});
diff --git a/core/src/utils/helpers.ts b/core/src/utils/helpers.ts
@@ -3,7 +3,9 @@ import { focusElements } from '@utils/focus-visible';
 import { printIonError } from '@utils/logging';
 
 import type { Side } from '../components/menu/menu-interface';
+import type { RouterDirection } from '../components/router/utils/interface';
 import { config } from '../global/config';
+import type { AnimationBuilder } from '../interface';
 
 // TODO(FW-2832): types
 
@@ -434,3 +436,42 @@ export const shallowEqualStringMap = (
 export const isSafeNumber = (input: unknown): input is number => {
   return typeof input === 'number' && !isNaN(input) && isFinite(input);
 };
+
+const SCHEME = /^[a-z][a-z0-9+\-.]*:/;
+
+export const openURL = async (
+  url: string | undefined | null,
+  ev: Event | undefined | null,
+  direction: RouterDirection,
+  animation?: AnimationBuilder
+): Promise<boolean> => {
+  if (url != null && url[0] !== '#' && !SCHEME.test(url)) {
+    const router = document.querySelector('ion-router');
+    if (router) {
+      if (ev != null) {
+        ev.preventDefault();
+      }
+      return router.push(url, direction, animation);
+    }
+  }
+  return false;
+};
+
+/**
+ * Deep merges two objects, with source properties overriding target properties
+ * @param target The target object to merge into
+ * @param source The source object to merge from
+ * @returns The merged object
+ */
+export const deepMerge = (target: any, source: any): any => {
+  const result = { ...target };
+
+  for (const key in source) {
+    if (source[key] && typeof source[key] === 'object' && !Array.isArray(source[key])) {
+      result[key] = deepMerge(result[key] ?? {}, source[key]);
+    } else {
+      result[key] = source[key];
+    }
+  }
+  return result;
+};
diff --git a/core/src/utils/theme.spec.ts b/core/src/utils/theme.spec.ts
diff --git a/core/src/utils/theme.ts b/core/src/utils/theme.ts
