@nxgt/material 3.7.5 → 3.8.0

package/docs/guides/backgrounds.md

@@ -45,19 +45,20 @@ import '@nxgt/material/backgrounds.css';
 
 | Prop | Values | Default |
 | --- | --- | --- |
-| `preset` | `gradient`, `grain`, `mesh`, `aurora`, `spotlight`, `bokeh`, `rays`, `halo`, `plasma`, `glass`, `ripples`, `blobs`, `paper`, `linen`, `concrete`, `marble`, `isometric`, `blueprint`, `dots`, `stripes`, `low-poly`, `topography`, `waves`, `hexagons`, `circuit`, `graph-paper`, `checker`, `diagonal-checker`, `chevrons`, `shapes`, `confetti-grid`, `constellation`, `halftone`, `truchet`, `floating`, `scatter-icons`, `school`, `night-sky`, `bubbles`, `leaves`, `science`, `music`, `travel`, `sport` (`AVAILABLE_BACKGROUND_PRESETS`, the ids this library draws); any other id draws the gradient and warns outside production | `gradient` |
+| `preset` | `gradient`, `grain`, `mesh`, `aurora`, `spotlight`, `bokeh`, `rays`, `halo`, `plasma`, `glass`, `ripples`, `blobs`, `paper`, `linen`, `concrete`, `marble`, `isometric`, `blueprint`, `dots`, `stripes`, `low-poly`, `topography`, `waves`, `hexagons`, `circuit`, `graph-paper`, `checker`, `diagonal-checker`, `chevrons`, `shapes`, `confetti-grid`, `constellation`, `halftone`, `truchet`, `floating`, `scatter-icons`, `school`, `night-sky`, `bubbles`, `leaves`, `science`, `music`, `travel`, `sport`, `moon` (`AVAILABLE_BACKGROUND_PRESETS`, the ids this library draws); any other id draws the gradient and warns outside production | `gradient` |
 | `tone`, `intensity` | as above | `primary`, `default` |
 | `animated` | `boolean`: drifts the layers, see Motion | `false` |
 | `grain` | `boolean`: film noise over the preset; needs `grain.css` | `false` |
 | `seed` | `number`: moves a seeded preset's geometry and the grain | `0` |
 | `motif` | a `MotifOptions` object (`shapes`, `density`, `size`, `rotate`, `shapeFill`, `opacitySpread`), see [Motif presets](#motif-presets) | all fields optional |
+| `moon` | a `MoonOptions` object for `preset="moon"`: `position` (`{ x, y }`, fractions of the container), `phase`, `halo`; see [Moon](#moon) | `{ position: { x: 0.8, y: 0.2 }, phase: 0.78, halo: 2.6 }` |
 | `fill` | `viewport` (the viewport's size) or `container` (its parent's size: the parent needs a definite height) | `viewport` |
 
-`BACKGROUND_PRESETS` is the table of all 44 presets with their family and
+`BACKGROUND_PRESETS` is the table of all 45 presets with their family and
 kind; `AVAILABLE_BACKGROUND_PRESETS` lists the ids this library draws (all
-44; `SHIPPED_BACKGROUND_PRESETS` is the common floor every library draws).
+45; `SHIPPED_BACKGROUND_PRESETS` is the common floor every library draws).
 
-<img src="../previews/backgrounds-matrix.webp" width="640" alt="The 44 presets, each in a card with its name">
+<img src="../previews/backgrounds-matrix.webp" width="640" alt="The presets, each in a card with its name">
 
 The root states `preset`, `tone`, `intensity`, `animated`, `grain` and `fill` as
 `data-*` attributes (`data-animated` and `data-grain` are empty attributes), and
@@ -257,7 +258,18 @@ Each is about 14 to 16 KB of markup at the defaults and 24 to 28 KB at `density:
 classes (a pace `p1..p3`, a delay `l1..l4`), so it needs no inline style under a strict CSP, and it stops under
 `prefers-reduced-motion` or while the page is hidden. CSS: `backgrounds/illustrated.css` (shared, imported by each
 preset's file) plus `school.css`, `night-sky.css`, `bubbles.css`, `leaves.css`, `science.css`, `music.css`,
-`travel.css` and `sport.css`; one alone works. React only: `@nxgt/material-vue` does not draw them.
+`travel.css` and `sport.css`; one alone works. React only: `@nxgt/material-vue` does not draw them. (`moon.css` is below.)
+
+### Moon
+
+`moon` is a thin crescent at the top right in a wide halo of the tertiary colour, among nine sparse stars: calmer than
+`constellation`, and the background of the Blue moon theme. The moon is drawn in the tone's second colour (silver
+in dark, a lighter multiplied crescent in light), the halo in its third and the stars in its first and second, so `tone="mixed"` is the intended look. It
+follows `intensity` (`subtle` is a faint watermark, `vivid` the strongest; the stars and the moon keep off the middle of the frame, where the content sits), and reads `size` (the moon's radius) and `density`
+(5, 9 or 15 stars) from `motif`. With `animated` the stars twinkle (8 s a leg), and nothing moves under
+`prefers-reduced-motion` or while the page is hidden. About 3 KB of markup. The moon stays the same size (80 px, half that in a container under 640 px wide) and sits at 80% across and 20% down, whatever the container's shape. CSS: `backgrounds/moon.css` (it imports
+`scene.css`); one alone works. React only: `@nxgt/material-vue` does not draw it. The moon's `position`, `phase` and
+`halo` come from the `moon` prop (`<Background preset="moon" moon={{ position: { x: 0.2, y: 0.25 }, phase: 0.6 }} />`).
 
 ## Dark mode
 
@@ -296,10 +308,34 @@ you can select on:
 The gradient ends on `--nxgt-bg-cp`, not `--nxgt-bg-c2`: to recolour it, set
 `--nxgt-bg-cp` too.
 
+## Defaults from the theme
+
+The `Background` of `@nxgt/material/backgrounds` takes what you leave out
+(`preset`, `tone`, `intensity`, `seed`, `motif`, `grain`, `animated`) from the
+nearest theme (`NxgtThemeProvider` or an `NxgtTheme` zone, see
+[the provider and zones](./theming.md#the-provider-and-zones)), then from the
+defaults above. A prop you pass always wins; the others still come from the theme.
+
+```tsx
+import { NxgtTheme, ocean } from '@nxgt/material/themes';
+import { Background } from '@nxgt/material/backgrounds';
+
+<NxgtTheme theme={ocean}>
+  <Background />                       {/* Ocean's waves, tone and intensity */}
+  <Background preset="dots" />         {/* dots, with Ocean's tone and intensity */}
+</NxgtTheme>
+```
+
+Outside any theme nothing changes. The preset's stylesheet is still yours to
+import. The `/components` `Background` is the gradient alone and does not read
+the theme.
+
 ## Behind the app shell
 
-`ActivityLayout` takes a preset as its `backdrop`, replacing the gradient and
-its blobs: `backdrop={<Background preset="shapes" motif={{ shapes: MOTIF_SHAPES_ALL }} />}`.
+`ActivityLayout` draws the theme's background by default (Lavande's is the
+built-in gradient and its blobs). Its `backdrop` prop is the exception: a node
+such as `backdrop={<Background preset="shapes" motif={{ shapes: MOTIF_SHAPES_ALL }} />}`
+replaces it for one screen, and `backdrop={false}` removes it.
 See [Use a background preset behind the shell](./app-shell.md#use-a-background-preset-behind-the-shell).
 
 ## Recolour the blobs

package/docs/guides/i18n.md

@@ -252,7 +252,7 @@ single value's input, when nothing names the slider, `material.slider.value`
 `ComboboxField` (`showClear`), "Clear" / "Effacer" (`material.combobox.clear`),
 their chevron, "Show the options" / "Afficher les options"
 (`material.combobox.toggle`),
-the `LocationPreview` trigger
+the `ThemePicker`'s group and mode names (`material.theme-picker.label` "Theme" / "Thème", `material.theme-picker.mode` "Mode"; the Light, Dark and System names are `ThemeToggle`'s own), the `LocationPreview` trigger
 (`material.map.preview` / `preview-named`), and the delete buttons of the
 `Contacts` / `OpeningHours` rows. `FacetGroup`'s toggle is named "Level, 2 selected" / "Level, 2 sélectionnés" (`material.facet-group.name`, over `{title}` and `{count}`: plain in English, an ICU plural in French) and its Clear button "Clear Level" / "Effacer Level" (`material.facet-group.clear-label`, with the visible `material.facet-group.clear`). `AccountMenu`'s avatar button is named "Account menu, {name}" / "Menu du compte, {name}" (`material.account-menu.trigger`, over `{name}`) and its last item reads "Sign out" / "Se déconnecter" (`material.account-menu.sign-out`), unless you pass `signOutLabel`; with `themeChoice` its "Theme" group reads "Theme" / "Thème", "Light" / "Clair", "Dark" / "Sombre", "System" / "Système" (`material.account-menu.theme.label`, `light`, `dark`, `system`). `LocalizedTextFields`' reset button is named "Reset {language} to the default" / "Rétablir la valeur par défaut ({language})" (`material.localized-text-fields.reset`), its tooltip reads "Default: {value}" (`reset-tooltip`) and its polite status "{language}: back to the default" (`reset-done`). Its "Other languages" trigger reads "Other languages ({count})" / "Autres langues ({count})" (`others-count`; `others` names the folded rows' group), and while closed over errors it is described by "{count} errors" / "{count} erreurs" (`others-errors`, an ICU plural over `{count}`). The language names come from `material.language.<code>` (English and French ship), then `Intl.DisplayNames`. `PrintDocument`'s page numbers
 read `material.print.page-of` ("Page {page} of {pages}", "Page {page} sur

package/docs/guides/themes.md

@@ -0,0 +1,103 @@
+# Themes for your app: define, generate, check
+
+An app theme is a `defineTheme()` module. A build step turns it into a stylesheet
+(`<name>.css`) and a `.d.ts` that you commit; there is no style injection at
+runtime, so a strict Content Security Policy needs nothing extra. Two tools do the
+build step: the `themes` option of the [Vite plugin](vite-plugin.md#themes), and the
+`nxgt-theme` command for builds without Vite and for CI.
+
+See also [Theming](theming.md) for the tokens a theme sets.
+
+## Define a theme
+
+```ts
+// src/themes/ecole.ts
+import { defineTheme, ocean } from '@nxgt/material/themes';
+
+export default defineTheme({
+  name: 'ecole',
+  label: 'École',
+  extends: ocean,
+  colors: { primary: '#0b7a75' },
+  tones: { maths: '#0b7a75', art: { light: '#a33', dark: '#f99' } },
+});
+```
+
+A module exports its themes as the default export (one theme or an array) or as
+named exports. The seeds, `extends`, `tones`, `fonts`, `radius` and `tokens` are
+documented in [`@nxgt/material-core`'s themes page](https://cdn.jsdelivr.net/npm/@nxgt/material-core@0/docs/theme.md).
+
+## Generate the files
+
+With Vite:
+
+```ts
+// vite.config.ts
+import { nxgtMaterial } from '@nxgt/material/vite';
+import tailwindcss from '@tailwindcss/vite';
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss(),
+    ...nxgtMaterial({ themes: { entries: 'src/themes/*.ts' } }),
+  ],
+});
+```
+
+Or from a shell:
+
+```sh
+nxgt-theme build "src/themes/*.ts" --out src/themes/generated
+```
+
+Both write `src/themes/generated/ecole.css` and `nxgt-themes.d.ts`, and only when
+the bytes changed. **Commit them.** Import the stylesheet after the library's:
+
+```css
+@import "@nxgt/material/styles.css";
+@import "./themes/generated/ecole.css"; /* after styles.css */
+```
+
+`nxgt-themes.d.ts` merges your tone names into `AppTones` and your theme names into
+`NxgtThemes`, so `useTheme().themeName`, `ThemeName` (from `@nxgt/material/hooks`) and the `data-tone` values are typed with
+them. Include it in your `tsconfig`.
+
+## The CLI
+
+```
+nxgt-theme build <entries…> [--out src/themes/generated] [--no-types] [--strict] [--module @nxgt/material]
+nxgt-theme check <entries…> [--out …] [--no-types] [--module …]
+nxgt-theme inspect <entry> [--name x]
+```
+
+- `build` writes the files. Warnings go to stderr; `--strict` makes them exit 1.
+- `check` writes nothing. It exits 1 when a generated file is stale or missing, or when a
+  contrast pair fails (an override that broke one). Run it in CI to catch a
+  theme edited without a rebuild:
+
+  ```yaml
+  - run: npx nxgt-theme check "src/themes/*.ts" --out src/themes/generated
+  ```
+
+- `inspect` prints every token and the contrast table, light and dark.
+
+Entries are `.js` or `.mjs` files, or `.ts` / `.mts` files through Node's own type
+stripping (Node 22.18 or newer, no loader to install). Type stripping handles
+erasable syntax only: write the theme as a plain object, with no `enum`,
+`namespace` or parameter property. The command ships in `@nxgt/material` and in
+`@nxgt/material-core`; with pnpm or bun only the bin of a direct dependency is
+linked, so call it through `@nxgt/material`.
+
+## Warnings
+
+- A token override that breaks a documented contrast pair, with its ratio.
+- **A tone declared in one theme and missing from another**: in the other theme the
+  name falls back to the inherited value. Declare it in every theme that should differ.
+- The palette generator's own notices (a lightness moved for AA, a chroma lowered,
+  a hue near a status colour).
+
+With the plugin they go to Vite's logger, or fail the build with
+`onWarning: 'error'`.