javascript/ionic-framework
1
0
Fork 0
mirror of https://github.com/ionic-team/ionic-framework.git synced 2025-11-08 07:41:51 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat: add ionic theme architecture (#29132)

Browse Source 
Issue number: Internal

---------

<!-- Please do not submit updates to dependencies unless it fixes an
issue. -->

<!-- Please try to limit your pull request to one type (bugfix, feature,
etc). Submit multiple pull requests if needed. -->

## What is the current behavior?
<!-- Please describe the current behavior that you are modifying. -->

## What is the new behavior?
<!-- Please describe the behavior or changes that are being added by
this PR. -->

Adds the base architecture to add a new theme configuration to Ionic
Framework components.
- Components can now specify an additional stylesheet for the `ionic`
theme.
- Developers can specify the `theme` and `mode` independently to control
look and feel of a component.

Test infrastructure has been updated to add support for testing the
theme configuration with Playwright.
- Existing `themes` test configuration has been renamed to `palettes`

This PR is just the initial effort to decouple Ionic's architecture to
separate look and feel and allow our dev team to start introducing the
new component appearance to the UI. There will be additional changes
required to completely add support for the Ionic theme. These changes
are targeted against the `next` branch and are not expected to be used
in a production environment at this time.

## Does this introduce a breaking change?

- [ ] Yes
- [x] No

<!--
  If this introduces a breaking change:
1. Describe the impact and migration path for existing applications
below.
  2. Update the BREAKING.md file with the breaking change.
3. Add "BREAKING CHANGE: [...]" to the commit description when merging.
See
https://github.com/ionic-team/ionic-framework/blob/main/.github/CONTRIBUTING.md#footer
for more information.
-->


## Other information

<!-- Any other information that is important to this PR such as
screenshots of how the component looks before and after the change. -->

---------

Co-authored-by: Maria Hutt <thetaPC@users.noreply.github.com>
Co-authored-by: Brandy Carney <brandyscarney@users.noreply.github.com>
This commit is contained in:
Sean Perkins
2024-03-18 15:45:01 -04:00
committed by GitHub
parent 76b48a6c77
commit 284eb8ecaf
119 changed files with 2966 additions and 1072 deletions
Download Patch File Download Diff File Expand all files Collapse all files

207
core/src/global/ionic-global.ts
View File

@ -1,16 +1,134 @@
import { getMode, setMode, setPlatformHelpers } from '@stencil/core';
import { getMode, setMode, setPlatformHelpers, getElement } from '@stencil/core';
import { printIonWarning } from '@utils/logging';
import type { IonicConfig, Mode } from '../interface';
import type { IonicConfig, Mode, Theme } from '../interface';
import { isPlatform, setupPlatforms } from '../utils/platform';
import { config, configFromSession, configFromURL, saveConfig } from './config';
// TODO(FW-2832): types
let defaultMode: Mode;
let defaultTheme: Theme = 'md';
export const getIonMode = (ref?: any): Mode => {
return (ref && getMode(ref)) || defaultMode;
/**
* Prints a warning message to the developer to inform them of
* an invalid configuration of mode and theme.
* @param mode The invalid mode configuration.
* @param theme The invalid theme configuration.
*/
const printInvalidModeWarning = (mode: Mode, theme: Theme, ref?: any) => {
printIonWarning(
`Invalid mode and theme combination provided: mode: ${mode}, theme: ${theme}. Fallback mode ${getDefaultModeForTheme(
theme
)} will be used.`,
ref
);
};
/**
* Validates if a mode is accepted for a theme configuration.
* @param mode The mode to validate.
* @param theme The theme the mode is being used with.
* @returns `true` if the mode is valid for the theme, `false` if invalid.
*/
export const isModeValidForTheme = (mode: Mode, theme: Theme) => {
if (mode === 'md') {
return theme === 'md' || theme === 'ionic';
} else if (mode === 'ios') {
return theme === 'ios' || theme === 'ionic';
}
return false;
};
/**
* Returns the default mode for a specified theme.
* @param theme The theme to return a default mode for.
* @returns The default mode, either `ios` or `md`.
*/
const getDefaultModeForTheme = (theme: Theme): Mode => {
if (theme === 'ios') {
return 'ios';
}
return 'md';
};
/**
* Returns the default theme for a specified mode.
* @param mode The mode to return a default theme for.
* @returns The default theme.
*/
const getDefaultThemeForMode = (mode: Mode): Theme => {
if (mode === 'ios') {
return 'ios';
}
return 'md';
};
const isModeSupported = (elmMode: string) => ['ios', 'md'].includes(elmMode);
const isThemeSupported = (theme: string) => ['ios', 'md', 'ionic'].includes(theme);
const isIonicElement = (elm: HTMLElement) => elm.tagName?.startsWith('ION-');
/**
* Returns the mode value of the element reference or the closest
* parent with a valid mode.
* @param ref The element reference to look up the mode for.
* @param theme Optionally can provide the theme to avoid an additional look-up.
* @returns The mode value for the element reference.
*/
export const getIonMode = (ref?: any, theme = getIonTheme(ref)): Mode => {
if (ref?.mode && isModeValidForTheme(ref?.mode, theme)) {
/**
* If the reference already has a mode configuration,
* use it instead of performing a look-up.
*/
return ref.mode;
} else {
const el = getElement(ref);
const mode = (el.closest('[mode]')?.getAttribute('mode') as Mode) || defaultMode;
if (isModeValidForTheme(mode, theme)) {
/**
* The mode configuration is supported for the configured theme.
*/
return mode;
} else {
printInvalidModeWarning(mode, theme, ref);
}
}
return getDefaultModeForTheme(theme);
};
/**
* Returns the theme value of the element reference or the closest
* parent with a valid theme.
*
* @param ref The element reference to look up the theme for.
* @returns The theme value for the element reference, defaults to
* the default theme if it cannot be determined.
*/
export const getIonTheme = (ref?: any): Theme => {
const theme: Theme = ref && getMode<Theme>(ref);
if (theme) {
return theme;
}
/**
* If the theme cannot be detected, then fallback to using
* the `mode` attribute to determine the style sheets to use.
*/
const el = getElement(ref);
const mode = ref?.mode ?? (el.closest('[mode]')?.getAttribute('mode') as Mode);
if (mode) {
return getDefaultThemeForMode(mode);
}
/**
* If a mode is not detected, then fallback to using the
* default theme.
*/
return defaultTheme;
};
export const initialize = (userConfig: IonicConfig = {}) => {
@ -52,39 +170,90 @@ export const initialize = (userConfig: IonicConfig = {}) => {
// Setup platforms
setupPlatforms(win);
// first see if the mode was set as an attribute on <html>
// which could have been set by the user, or by pre-rendering
// otherwise get the mode via config settings, and fallback to md
Ionic.config = config;
/**
* Check if the mode was set as an attribute on <html>
* which could have been set by the user, or by pre-rendering
* otherwise get the mode via config settings, and fallback to md.
*/
Ionic.mode = defaultMode = config.get(
'mode',
doc.documentElement.getAttribute('mode') || (isPlatform(win, 'ios') ? 'ios' : 'md')
);
/**
* Check if the theme was set as an attribute on <html>
* which could have been set by the user, or by pre-rendering
* otherwise get the theme via config settings, and fallback to md.
*/
Ionic.theme = defaultTheme = config.get(
'theme',
doc.documentElement.getAttribute('theme') || getDefaultThemeForMode(defaultMode)
);
if (!isModeValidForTheme(defaultMode, defaultTheme)) {
printInvalidModeWarning(defaultMode, defaultTheme, configObj);
defaultMode = getDefaultModeForTheme(defaultTheme);
}
config.set('mode', defaultMode);
doc.documentElement.setAttribute('mode', defaultMode);
doc.documentElement.classList.add(defaultMode);
config.set('theme', defaultTheme);
doc.documentElement.setAttribute('theme', defaultTheme);
doc.documentElement.classList.add(defaultTheme);
if (config.getBoolean('_testing')) {
config.set('animated', false);
}
const isIonicElement = (elm: any) => elm.tagName?.startsWith('ION-');
const isAllowedIonicModeValue = (elmMode: string) => ['ios', 'md'].includes(elmMode);
setMode((elm: any) => {
/**
* Iterate over all the element nodes, to both validate and
* set the "mode" that is used for determining the styles to
* apply to the element.
*
* setMode refers to Stencil's internal metadata for "mode",
* which is used to set the correct styleUrl for the component.
*
* If the "theme" attribute or property is set, then use it
* to determine the style sheets to use.
*
* If the "mode" attribute or property is set, then use it
* to determine the style sheets to use. This is fallback
* behavior for applications that are not setting the "theme".
*/
while (elm) {
const elmMode = (elm as any).mode || elm.getAttribute('mode');
if (elmMode) {
if (isAllowedIonicModeValue(elmMode)) {
return elmMode;
const theme = (elm as any).theme || elm.getAttribute('theme');
if (theme) {
if (isThemeSupported(theme)) {
return theme;
} else if (isIonicElement(elm)) {
console.warn('Invalid ionic mode: "' + elmMode + '", expected: "ios" or "md"');
printIonWarning(`Invalid theme: "${theme}". Supported themes include: "ios" or "md".`);
}
}
/**
* If a theme is not detected, then fallback to using the
* `mode` attribute to determine the style sheets to use.
*/
const elmMode = (elm as any).mode || elm.getAttribute('mode');
if (elmMode) {
if (isModeSupported(elmMode)) {
return elmMode;
} else if (isIonicElement(elm)) {
printIonWarning(`Invalid mode: "${elmMode}". Ionic modes can be only "ios" or "md"`);
}
}
elm = elm.parentElement;
}
return defaultMode;
return defaultTheme;
});
};