@nxgt/material 3.23.0 → 3.24.1

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @nxgt/material
 
+## 3.24.1
+
+### Patch Changes
+
+- [#1623](https://github.com/softistx/nxgt-material/pull/1623) [`ea8e6d3`](https://github.com/softistx/nxgt-material/commit/ea8e6d39d41b8fa9a0c3ca6201fb983a647c87a0) Thanks [@SteveGT96](https://github.com/SteveGT96)! - Fix: `NativeSelect` shrank to the width of its selected option while the other fields (`TextField`, `SelectField`, `ComboboxField`) filled their column. It fills its container now, like them, in a form grid, a `FormSection`, a flex row and a phone column. `SelectField` and the `Select` trigger already filled it, and a long selected label ends in an ellipsis without widening the column; a story now measures all of them against a `TextField`, at 360 and 1440 px, light and dark. A `NativeSelect` that must stay compact (a toolbar, a page-size picker) takes a width class, such as `className="w-fit"` or `w-24`: the wrapper and the chevron follow it. See the troubleshooting entry.
+
+## 3.24.0
+
+### Minor Changes
+
+- [#1618](https://github.com/softistx/nxgt-material/pull/1618) [`a12222a`](https://github.com/softistx/nxgt-material/commit/a12222abd286b1fc2bccfa4e609f9c3fb8ecfeac) Thanks [@SteveGT96](https://github.com/SteveGT96)! - A tinted page ground under `ActivityLayout`, and the cards on `bg-card`. The page was flat (`--background`, the same colour as a card), so a card had no edge on it; now the page carries a quiet tint and the cards stand on it.
+  
+  **Visual change, by default. Screenshot baselines change** (every screen under `ActivityLayout`, light and dark).
+  
+  - New token `--ground` with the `bg-ground` utility (`--color-ground`). Light: `color-mix(in oklab, var(--primary) 7%, var(--background))`. Dark: `color-mix(in oklab, var(--primary) 6%, color-mix(in oklab, var(--background) 55%, black))`, darker than the page and the cards. The mixes are in `oklab` (never `oklch`, which skews the hue toward white). Every built-in theme and every `defineTheme` / `themeToCss` output writes it for light and dark (`@nxgt/material-core` 0.x: `ground` is a `ThemeToken`, checked for AA text), and a theme overrides it like any token.
+  - `ThreadLayout` paints `bg-ground` too (it has no app bar or sidebar, so no flat chrome to add).
+  - `ActivityLayout` paints `bg-ground` on its root, with or without a `backdrop`; the frame's `bg-background-paper` is gone. The sidebar and the app bar stay on `--background` (translucent over a backdrop, 90 % without one), **flat: no radius, no shadow**. The gutter mask above the app bar takes the ground.
+  - The `ActivityContent` header card is `bg-card` (it was `bg-background`). Cards keep `bg-card`, their hairline and soft shadow.
+  - The motif and icons presets' wash is one even, soft top-to-bottom gradient, with no corner hotspot.
+  
+  **Vue.** `@nxgt/material-vue` only receives the shared files (`theme-tokens.css` carries `--ground`, the motif wash is the even gradient); nothing new is implemented there (no `bg-ground` utility, no layout change); tracked in [#1620](https://github.com/softistx/nxgt-material/issues/1620).
+  
+  **Opt out.** `--ground: var(--background)` on the layout or an ancestor makes the page flat as before.
+  
+  **Migration.**
+  
+  - Drop app-level page backgrounds under the layout (`bg-background`, `bg-white`, `bg-muted` on a wrapper, `body` or a route), and app-level card shadows: the cards already carry a hairline and a soft shadow.
+  - Set no colours on a backdrop: its colours come from the theme.
+  - For a custom tint, set `--ground` (on `:root`, the layout or a zone), or a `tokens` override in `defineTheme`.
+  
+  Docs: the theming guide ("Page ground"), the app shell guide, troubleshooting ("The page and the cards look the same"), the README; the `nxgt-material` plugin's `build-a-theme` skill.
+
+### Patch Changes
+
+- Updated dependencies [[`a12222a`](https://github.com/softistx/nxgt-material/commit/a12222abd286b1fc2bccfa4e609f9c3fb8ecfeac)]:
+  - @nxgt/material-core@0.35.0
+
 ## 3.23.0
 
 ### Minor Changes

package/README.md

@@ -422,9 +422,9 @@ Each area a consumer starts from has its own page under `docs/guides/`.
 | --- | --- |
 | [Forms](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/forms.md) | wiring fields to React Hook Form and Zod, composite values (contacts, opening hours), config-driven `Field`, server errors, what each field emits |
 | [i18n](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/i18n.md) | adding your strings next to the package's, switching language, translated Zod messages, SSR without a text mismatch |
-| [App shell](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/app-shell.md) | laying out an app with `ActivityLayout` (route changes cross-fade by default, `routeTransition={false}` opts out; it draws the theme's background, `backdrop` is the exception and `backdrop={false}` a plain page), its `items` (rendered as links; `linkComponent` to pass your own), the brand (`logo`, `name`, and `context` for the phone sheet's tenant line), the header's title, a route's `handle.title` as the page's `h1` in the app bar (`AppShellHandle`, `PageTitle`; it labels `<main>`, and `usePageTitleFocus()` focuses it after a navigation), and `AccountMenu`, the active entry and breadcrumbs (needs a data router; `breadcrumbRoot` replaces the home icon with a text link, `breadcrumb={false}` hides the trail), the `<main>` landmark, the `h1` title, document scrolling, and a background preset behind the shell (`backdrop`) |
+| [App shell](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/app-shell.md) | laying out an app with `ActivityLayout` (route changes cross-fade by default, `routeTransition={false}` opts out; it draws the theme's background, `backdrop` is the exception and `backdrop={false}` a plain page), its `items` (rendered as links; `linkComponent` to pass your own), the brand (`logo`, `name`, and `context` for the phone sheet's tenant line), the header's title, a route's `handle.title` as the page's `h1` in the app bar (`AppShellHandle`, `PageTitle`; it labels `<main>`, and `usePageTitleFocus()` focuses it after a navigation), and `AccountMenu`, the active entry and breadcrumbs (needs a data router; `breadcrumbRoot` replaces the home icon with a text link, `breadcrumb={false}` hides the trail), the `<main>` landmark, the `h1` title, document scrolling, a background preset behind the shell (`backdrop`), and the tinted page ground the cards stand on (`--ground`, the opt-out) |
 | [Themes for your app](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/themes.md) | defining app themes, generating their stylesheets and types with the Vite plugin's `themes` option or the `nxgt-theme` command, the CI check |
-| [Theming](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/theming.md) | changing colours, radius or fonts, motion and corner tokens, dark mode, tones (the `data-tone` channel, app tones and the calm zone `data-density="calm"`), touch targets, using the compiled CSS without Tailwind |
+| [Theming](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/theming.md) | changing colours, radius or fonts, motion and corner tokens, the page ground (`--ground`, `bg-ground`: its light and dark values and the opt-out), dark mode, tones (the `data-tone` channel, app tones and the calm zone `data-density="calm"`), touch targets, using the compiled CSS without Tailwind |
 | [Printing](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/printing.md) | producing PDFs with `@nxgt/material/print` and getting the file in one call (download, new tab, preview, server `Response`) — its own entry since 2.0.0, with optional peers, a bundling trap on SSR servers, and the `next.config.ts` a Next.js route handler (and `output: 'standalone'`) needs |
 | [Maps](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/maps.md) | using `@nxgt/material/map` — browser-only, optional leaflet peers, `map.css` |
 | [Charts](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/charts.md) | drawing charts with `@nxgt/material/charts` (client-only): the twelve charts, shared props, legend, View data, `onPointClick`, zoom and phone scroll, right-to-left pages, keyboard and accessibility, theming the `--chart-*` tokens, and migrating from the Nivo charts, removed in 3.0 |
@@ -643,7 +643,7 @@ Not components: what the stylesheet gives any element.
 
 | Preview | Component | What it does | @nxgt/material-vue |
 | --- | --- | --- | --- |
-| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/navigation-layout-appshell.webp" width="120" alt="ActivityLayout"> | [`ActivityLayout`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/navigation-and-layout.md#activitylayout), `ActivityContent`, `AppSidebar`, `AppHeader`, `AppBreadcrumb`, `AppBreadcrumbItem`, `AppBreadcrumbSeparator` | App shell: sidebar built from `items`, a header with a mobile sheet, route breadcrumbs and a titled page; entries are real links, and `linkComponent` swaps the link; it draws the theme's background (Lavande's is the gradient), `backdrop` puts a `/backgrounds` preset behind it for one screen, and `backdrop={false}` draws a plain page. `ActivityContent` takes an `aside` side panel (beside the content from 1280px in CSS only, sticky under the app bar, a named `complementary` landmark, stacked below) and `width="form" \| "reading"` to cap the main column with the panel right beside it. See the [app shell guide](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/app-shell.md). | `ActivityLayout`, `ActivityContent`, `AppSidebar`, `AppHeader`, `AppBreadcrumb` |
+| <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/navigation-layout-appshell.webp" width="120" alt="ActivityLayout"> | [`ActivityLayout`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/navigation-and-layout.md#activitylayout), `ActivityContent`, `AppSidebar`, `AppHeader`, `AppBreadcrumb`, `AppBreadcrumbItem`, `AppBreadcrumbSeparator` | App shell: sidebar built from `items`, a header with a mobile sheet, route breadcrumbs and a titled page; entries are real links, and `linkComponent` swaps the link; it draws the theme's background (Lavande's is the gradient), `backdrop` puts a `/backgrounds` preset behind it for one screen, and `backdrop={false}` draws a plain page. It paints the tinted page ground (`--ground`, `bg-ground`) under the content, with the sidebar and the app bar flat on `--background` and the cards on `bg-card` (`--ground: var(--background)` opts out). `ActivityContent` takes an `aside` side panel (beside the content from 1280px in CSS only, sticky under the app bar, a named `complementary` landmark, stacked below) and `width="form" \| "reading"` to cap the main column with the panel right beside it. See the [app shell guide](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/app-shell.md). | `ActivityLayout`, `ActivityContent`, `AppSidebar`, `AppHeader`, `AppBreadcrumb` |
 | <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/navigation-layout-accountmenu.webp" width="120" alt="AccountMenu"> | [`AccountMenu`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/navigation-and-layout.md#accountmenu) | The app bar's avatar menu: named after the account, the name and e-mail, the app's links, then an optional Theme choice (`themeChoice`) and a destructive Sign out with a busy state. | `AccountMenu` |
 | <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/navigation-layout-authcard.webp" width="120" alt="AuthCard"> | [`AuthCard`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/navigation-and-layout.md#authcard) | The frame of a signed-out page: one `main`, a centred card whose title is the `h1` (focusable on an end state), a status or alert notice, a brand and toolbar row, safe-area padding, an optional backdrop (the theme's by default) that keeps clear of the card. | `AuthCard` |
 | <img src="https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/previews/navigation-layout-sidebar.webp" width="120" alt="Sidebar"> | [`Sidebar`](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/components/navigation-and-layout.md#sidebar), `SidebarHeader`, `SidebarContent`, `SidebarFooter`, `SidebarMenuItem`, `SidebarMenuLabel` | Collapsible navigation sidebar with icons, tooltips and active items. | `Sidebar` (same parts) |
@@ -763,6 +763,7 @@ The ones that cost the most time. Every error message, with its fix, is in
 | Toast or drawer unstyled | import `@nxgt/material/styles.css` (or `dist/material.css`) |
 | `<Icon>` is blank | serve `public/assets/icons/sprites/<style>.svg` |
 | `Background preset="icons"` draws its shapes but no icons, or `nxgt-backdrop-sprite` fails with `needs the icon packs your backdrops draw` | build the reduced sprite with the packs you draw (`npx nxgt-backdrop-sprite --pack school --out public/sprites/backdrop.svg --base /sprites/`) and pass the printed `backdropSprite` to `IconSpritesProvider`; or serve the per-style sheets ([blank backdrop](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/troubleshooting.md#backdrop-icons-are-blank-with-a-reduced-sprite), [missing packs](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/troubleshooting.md#backdropsprite-needs-the-icon-packs-your-backdrops-draw)) |
+| the page and the cards look the same under `ActivityLayout` | the page ground (`--ground`) is flat: remove the app's own page background under the layout, import `styles.css`, and drop any `--ground: var(--background)` ([troubleshooting](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/troubleshooting.md#the-page-and-the-cards-look-the-same)) |
 | `preset="icons"` looks different after 3.22, or its glyphs vanish near cards | the default is the calm mix (shapes and a few icons, one tint, medium density); for the old look pass `iconStyle="duotone-thin" iconMotif={{ layout: 'scatter', colors: 'classic' }}`; a glyph that meets a card, a list or text is dropped on purpose ([troubleshooting](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/troubleshooting.md#the-icons-backdrop-looks-different-after-322)) |
 | `window is not defined` at server boot | load `@nxgt/material/map` through `import()` + `clientOnly` ([maps](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/guides/maps.md#browser-only)) |
 | `Cannot find package '@nxgt/material-core'` at server boot | add `@nxgt/material-core` wherever `@nxgt/material` is in `ssr.noExternal` or `--external` ([troubleshooting](https://cdn.jsdelivr.net/npm/@nxgt/material@3/docs/troubleshooting.md#cannot-find-package-nxgtmaterial-core)) |

package/dist/backgrounds/css/motifs.css

@@ -7,7 +7,10 @@
 @import "./scene.css";
 
 @layer components {
-	/* The wash: two soft colour pools under the scene. */
+	/* The wash: one even, soft gradient over the whole layer, top to bottom, no
+	 * pool in a corner. It sits in the backdrop layer under the content column, so
+	 * it never repaints the sidebar or the app bar, and the page ground
+	 * (--ground) shows through it. */
 	:is(
 		[data-background="shapes"],
 		[data-background="confetti-grid"],
@@ -18,17 +21,15 @@
 	) > [data-layer="wash"] {
 		position: absolute;
 		inset: 0;
-		background:
-			radial-gradient(
-				ellipse 75% 65% at 30% 20%,
-				color-mix(in oklab, var(--nxgt-bg-c1) var(--nxgt-bg-a1), transparent),
-				transparent 72%
+		background: linear-gradient(
+			180deg in oklab,
+			color-mix(
+				in oklab,
+				var(--nxgt-bg-c1) calc(var(--nxgt-bg-a1) * 1.75),
+				transparent
 			),
-			radial-gradient(
-				ellipse 60% 60% at 85% 90%,
-				color-mix(in oklab, var(--nxgt-bg-c3) var(--nxgt-bg-a1), transparent),
-				transparent 70%
-			);
+			color-mix(in oklab, var(--nxgt-bg-c3) var(--nxgt-bg-a1), transparent)
+		);
 	}
 
 	/* The scene clips the float, which scales it past the frame. */

package/dist/backgrounds/css-react/icons.css

@@ -23,20 +23,19 @@
 @import "./icons-tint.css";
 
 @layer components {
+	/* The wash: one even, soft gradient over the layer (see css/motifs.css). */
 	[data-background="icons"] > [data-layer="wash"] {
 		position: absolute;
 		inset: 0;
-		background:
-			radial-gradient(
-				ellipse 75% 65% at 22% 18%,
-				color-mix(in oklab, var(--nxgt-bg-c1) var(--nxgt-bg-a1), transparent),
-				transparent 72%
+		background: linear-gradient(
+			180deg in oklab,
+			color-mix(
+				in oklab,
+				var(--nxgt-bg-c1) calc(var(--nxgt-bg-a1) * 1.75),
+				transparent
 			),
-			radial-gradient(
-				ellipse 60% 60% at 86% 90%,
-				color-mix(in oklab, var(--nxgt-bg-c3) var(--nxgt-bg-a1), transparent),
-				transparent 70%
-			);
+			color-mix(in oklab, var(--nxgt-bg-c3) var(--nxgt-bg-a1), transparent)
+		);
 	}
 
 	:is([data-background="icons"], [data-background="shapes"]) > [data-scene] {

package/dist/components/theme-tokens.css

@@ -5,6 +5,11 @@
 	--radius: 0.625rem;
 	--background: oklch(1 0 0);
 	--foreground: oklch(0.227 0.017 290);
+	/* The page ground under ActivityLayout (`bg-ground`): the primary at 7 % over the
+	   page, so the cards (--card, white) stand apart from it. Set here, not on
+	   `body`, so a zone that sets --primary or --background gets its own. A page
+	   keeps the flat look with `--ground: var(--background)`. */
+	--ground: color-mix(in oklab, var(--primary) 7%, var(--background));
 	--card: oklch(1 0 0);
 	--card-foreground: oklch(0.227 0.017 290);
 	--strix: oklch(45.91% 0.1864 310.75);
@@ -99,6 +104,13 @@
 [data-theme="dark"] {
 	--background: oklch(0.15 0.026 273);
 	--foreground: oklch(0.943 0.012 291.3);
+	/* Darker than --background so the cards (--card) stand apart: the page 55 %
+	   toward black, the primary at 6 % over it. */
+	--ground: color-mix(
+		in oklab,
+		var(--primary) 6%,
+		color-mix(in oklab, var(--background) 55%, black)
+	);
 	--card: oklch(0.19 0.019 289.4);
 	--card-foreground: oklch(0.943 0.012 291.3);
 	--popover: oklch(0.19 0.019 289.4);

package/dist/components/ui/layout/app-shell/activity-backdrop.css

@@ -6,8 +6,8 @@
  * Plain CSS, no inline `style`, in `@layer components` like the rest: an app's
  * utilities still win. The layer itself (`data-slot="activity-layout-backdrop"`)
  * is in the content column, positioned by classes in activity-layout.tsx: the
- * frame's padding and gaps take the chrome fill, so the shapes show nowhere
- * else.
+ * frame's padding and gaps show the page ground (--ground), so the shapes show
+ * nowhere else.
  *
  * The chrome is lightly translucent and frosted: about 80% of the background
  * colour (--nxgt-backdrop-chrome-alpha, the app bar) or 87% (--nxgt-backdrop-nav-alpha,
@@ -34,7 +34,7 @@
 		display: none;
 	}
 
-	/* The gutter mask without a backdrop (activity-layout.tsx) has the app bar's
+	/* The gutter mask without a backdrop (activity-layout.tsx) has the page ground's
 	 * translucent fill, which the page's top gutter never had: it fades in over
 	 * the first 8px of scroll, so at scroll top nothing changed. A browser
 	 * without scroll-driven animations shows it from the start. */
@@ -60,19 +60,6 @@
 		background-image: none;
 	}
 
-	/* scroll="document": the frame's chrome fill leaves its top gutter to the
-	 * gutter mask (activity-layout.tsx), a fixed strip with the same fill that
-	 * hides the scrolled page above the sticky app bar. Painting both would
-	 * stack two translucent fills there. */
-	[data-slot="activity-layout"][data-backdrop][data-scroll="document"]
-	[data-slot="activity-layout-frame"] {
-		background:
-			linear-gradient(
-				var(--nxgt-backdrop-fill-chrome),
-				var(--nxgt-backdrop-fill-chrome)
-			)
-			bottom / 100% calc(100% - var(--nxgt-backdrop-top)) no-repeat;
-	}
 	[data-slot="activity-layout"][data-backdrop] > [data-layer] {
 		display: none;
 	}