@aglyn/shared-ui-theme

The Material UI theming layer the Aglyn packages share: a responsive theme factory, the console and site default themes, a provider that renders a site's stored theme document as a MUI theme with light and dark schemes, Emotion cache helpers, and WCAG contrast utilities. It is mainly a dependency of the renderer, Besigner and the other @aglyn/shared-ui-* packages; the utilities are usable in any MUI app.

Published to npm from the Aglyn monorepo. Versions follow semantic versioning.

Install

npm install @aglyn/shared-ui-theme

Peer dependencies: react, @mui/material, @mui/system, @mui/utils, @mui/types and @mui/styles. @emotion/react and @emotion/cache are regular dependencies.

What's in it

From the root entry:

• Theme factory. createResponsiveTheme({ themeOptions, responsiveFontSizesOptions? }) runs createTheme, derives shades for the extra palette colors, repairs derived shades that miss AA contrast, derives each palette color's hover shades (hover, the fill a hovered contained Button or Fab takes under its own contrastText, and hoverText, the hovered text/outlined label), and applies responsiveFontSizes across every breakpoint. createResponsiveCssVarTheme(light, dark, options?) combines two themes into one CSS-variables theme switched by class.
• MUI module augmentation. Importing the package extends MUI's types with the palette additions these themes use (tertiary, surface, tint, and hover / hoverText on every palette color), extra typography variants such as displayXl, and the matching component color overrides. It also re-exports a selection of MUI types and helpers (Theme, ThemeOptions, SxProps, darkScrollbar, visuallyHidden).
• Default themes. consoleThemeLight / consoleThemeDark / consoleThemeCssVar / getConsoleTheme(mode) and tenantThemeLight / tenantThemeDark, with their ThemeOptions (consoleOptions, tenantOptions and the dark variants). siteFallbackTheme(host, scheme) and siteBaseOptions(host, scheme) pick between them for a host.
• Host theme. A HostTheme (the type lives in @aglyn/shared-data-types) is a site's theme customization as plain data. hostThemeToThemeOptions(theme, scheme) converts it to ThemeOptions; sanitizeHostTheme, mergeThemeOptions, hasHostTheme and getGoogleFontsUrl support it. HostThemeProvider renders children under it, taking theme, a required fallback theme or [light, dark] pair, baseOptions, and initialMode / initialDeviceMode so a server render can choose the scheme before hydration.
• Self-hosted fonts. util/self-hosted-fonts reads a Google Fonts CSS2 stylesheet into @font-face rules (parseGoogleFontFaces), writes them back with every file on the site's own /api/fonts route (selfHostedFontFaceCss), and picks the one or two faces worth preloading (selfHostedFontPreloads). The tenant fetches and serves; this half is pure.
• Light/dark mode. createWithThemeProvider({ theme }) returns a higher-order component that provides the theme and mode state; useThemeMode() reads and toggles it. The choice is stored in the theme-color-mode cookie (COOKIE_THEME_KEY).
• Emotion. createEmotionCache, CacheProvider, createLayeredEmotionCache, createWithEmotionClientCache, and the constants EMOTION_CACHE_KEY, APP_EMOTION_CACHE_OPTIONS, MUI_CSS_LAYER_NAME.
• Contrast. contrastRatio, relativeLuminance, meetsContrast, accessibleShade, accentTextColor, accentFillColor, accentHoverFillColor, accentHoverTextColor, hoverFillShade, inkContrast, auditPaletteContrast, with AA_TEXT_CONTRAST (4.5) and AA_NON_TEXT_CONTRAST (3).
• Small helpers. mergeSxProps / useMergeSxProps, generateComponentClassKeys, FontFamily, buildFontFamilyList.

By subpath only: util/theme-editor-fields and util/theme-editor-defaults (the field vocabulary and readers/writers a theme editor uses over a HostTheme), util/theme-mode-cookie, util/color-scheme-hint and util/scheme-route-segment (server-side resolution of the visitor's scheme).

Usage

import {
  contrastRatio,
  createResponsiveTheme,
  createWithThemeProvider,
} from '@aglyn/shared-ui-theme'

const light = createResponsiveTheme({
  themeOptions: { palette: { primary: { main: '#1565c0' } } },
})
const dark = createResponsiveTheme({
  themeOptions: { palette: { mode: 'dark', primary: { main: '#90caf9' } } },
})

const withTheme = createWithThemeProvider({ theme: [light, dark] })

export const App = withTheme(function App() {
  return <main>Hello</main>
})

contrastRatio('#ffffff', '#1565c0') // a number; 4.5 or more passes AA for text

import { parseThemeModeCookie } from '@aglyn/shared-ui-theme/util/theme-mode-cookie'

How it fits

A shared UI package. It depends on @aglyn/shared-data-types, @aglyn/shared-util-tools and @aglyn/shared-util-vendor. @aglyn/shared-ui-jsx, @aglyn/shared-ui-jsx-forms, @aglyn/shared-ui-next, the node renderer and Besigner build on it. Shared packages are generic: they import only other shared packages and hold no plugin's domain.

License

Apache-2.0. Source: https://github.com/aglyn/aglyn/tree/main/libs/shared/ui/theme