@aglyn/shared-ui-theme 1.0.0-beta.143 → 1.0.0-beta.144

package/README.md

@@ -1,7 +1,63 @@
 # @aglyn/shared-ui-theme
 
-This library was generated with [Nx](https://nx.dev).
+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.
 
-## Running unit tests
+> Beta. Published from the Aglyn monorepo under the `beta` dist-tag; APIs can change between beta releases.
 
-Run `nx test shared-ui-theme` to execute the unit tests via [Jest](https://jestjs.io).
+## Install
+
+    npm install @aglyn/shared-ui-theme@beta
+
+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, 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`), 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.
+- **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`, `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
+
+```tsx
+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
+```
+
+```ts
+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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aglyn/shared-ui-theme",
-  "version": "1.0.0-beta.143",
+  "version": "1.0.0-beta.144",
   "license": "Apache-2.0",
   "homepage": "https://aglyn.com",
   "repository": {
@@ -25,9 +25,9 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@aglyn/shared-data-types": "1.0.0-beta.143",
-    "@aglyn/shared-util-tools": "1.0.0-beta.143",
-    "@aglyn/shared-util-vendor": "1.0.0-beta.143",
+    "@aglyn/shared-data-types": "1.0.0-beta.144",
+    "@aglyn/shared-util-tools": "1.0.0-beta.144",
+    "@aglyn/shared-util-vendor": "1.0.0-beta.144",
     "@emotion/cache": "^11.14.0",
     "@emotion/react": "11.14.0",
     "@swc/helpers": "0.5.23",