@nxgt/material 3.4.0 → 3.5.0

package/docs/components/navigation-and-layout.md

@@ -81,6 +81,7 @@ phone's menu sheet pad clear of `env(safe-area-inset-*)`, as classes; see the
 | `titleAs` | `'h1'` … `'h6'` \| `'div'` | `'h1'` | `ActivityContent`: the title's heading level |
 | `inset` | `boolean` | `false` | `ActivityContent`: pads the content 1rem on each side. Off, it lines up with the app bar and the cards |
 | `align` | `'start' \| 'center'` | `'start'` | `ActivityLayout`, `AppSidebar`: the collapsed rail's entries sit right under the brand, or `'center'` for centred in the height below it |
+| `backdrop` | `ReactNode` | — | `ActivityLayout`: a decorative background behind the frame, in place of the gradient and its blobs: a `Background` preset from `@nxgt/material/backgrounds`. Rendered in an `inert`, `aria-hidden` layer that fills the layout. See [Use a background preset behind the shell](../guides/app-shell.md#use-a-background-preset-behind-the-shell) |
 | `routeTransition` | `boolean \| Omit<ViewTransitionProps, 'children' \| 'ref'>` | `true` | `ActivityLayout`: React's `<ViewTransition>` around the content region, so a navigation cross-fades it. `false` renders none (your app has its own boundary); an object passes `default` / `update` classes, `name`, callbacks through. See [Route transitions](../guides/app-shell.md#route-transitions) |
 
 The active entry is the longest match across the whole menu, segment-aware.

package/docs/guides/app-shell.md

@@ -191,6 +191,7 @@ partitionMenu(items);                              // { content, footer }
 | `align` | `'start' \| 'center'` | `'start'` | Where the collapsed rail's entries sit: right under the brand, or centred in the height below it |
 | `menuOpen` | `boolean` | — | Controls the phone's menu sheet: open while `true`. Leave it out and the layout manages the sheet. Only a phone shows the sheet |
 | `onMenuOpenChange` | `(open: boolean) => void` | — | Called for every change of the sheet: the menu button, Escape, the close button, a followed link, a new location |
+| `backdrop` | `ReactNode` | — | A decorative background drawn behind the frame in place of the built-in gradient and blobs: usually a `Background` preset from `@nxgt/material/backgrounds` (see [Use a background preset behind the shell](#use-a-background-preset-behind-the-shell)) |
 
 On a page with `viewport-fit=cover` (an installed PWA drawing under a
 notch and the home indicator), the shell pads clear of
@@ -483,6 +484,52 @@ while the sheet is open, so leave ids out of it. A link in `brand` (a home
 link around the logo) is the sheet's first focusable element, so it takes
 the focus when the sheet opens.
 
+## Use a background preset behind the shell
+
+The shell draws the gradient with three blurred blobs behind its frame. To use
+one of the 44 presets of `@nxgt/material/backgrounds` instead, pass it as
+`backdrop`:
+
+```tsx
+import { Outlet } from 'react-router';
+import { ActivityLayout, type MenuItem } from '@nxgt/material/components';
+import { Background, MOTIF_SHAPES_ALL } from '@nxgt/material/backgrounds';
+import '@nxgt/material/backgrounds.css'; // or one preset's backgrounds/<preset>.css
+
+export function Shell({ items }: { items: MenuItem[] }) {
+  return (
+    <ActivityLayout
+      items={items}
+      backdrop={<Background preset="shapes" motif={{ shapes: MOTIF_SHAPES_ALL }} />}
+    >
+      <Outlet />
+    </ActivityLayout>
+  );
+}
+```
+
+- **It replaces the gradient.** While `backdrop` is given the layout's root
+  carries `data-backdrop`, and the built-in gradient (its tint and three blobs) is not drawn (plain
+  CSS, no inline `style`). Without it the markup and the look are what they
+  were; `null`, `undefined` and `false` count as none.
+- **It sits behind everything.** The node is wrapped in a layer
+  (`[data-slot="activity-layout-backdrop"]`) that fills the layout, under the
+  sidebar, the header and the content. The layer is `inert`, `aria-hidden="true"`
+  and takes no pointer, so the preset is decoration only: put nothing
+  interactive in it.
+- **It fills the layout.** A `Background` in the layer is sized to the layer,
+  not to `100lvw × 100lvh`, so you need no `className` or `fill`. In
+  `scroll="document"` the layout grows with the content, and so does the preset.
+- **Readable by design.** The frame keeps `bg-background-paper` and the sidebar
+  and header their `bg-background/40`, so the content reads over a busy preset.
+  Tone it down with the preset's `intensity` (`subtle`) rather than by
+  restyling the frame.
+- **The stylesheet is yours to import.** `@nxgt/material/backgrounds` is a
+  separate entry, so `ActivityLayout` never pulls it in: import it where you
+  build the `backdrop`, and its `backgrounds.css` once.
+- The `--nxgt-bg-blob-1..3` variables recolour the built-in blobs only; the
+  `blobs` preset reads them too.
+
 ## Route transitions
 
 `ActivityLayout` wraps its content region (`data-slot="activity-content-region"`)

package/docs/guides/backgrounds.md

@@ -296,12 +296,18 @@ you can select on:
 The gradient ends on `--nxgt-bg-cp`, not `--nxgt-bg-c2`: to recolour it, set
 `--nxgt-bg-cp` too.
 
+## 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 }} />}`.
+See [Use a background preset behind the shell](./app-shell.md#use-a-background-preset-behind-the-shell).
+
 ## Recolour the blobs
 
 The gradient's three blobs have a public API: `--nxgt-bg-blob-1`, `--nxgt-bg-blob-2` and `--nxgt-bg-blob-3`.
 Each takes any colour. Unset, a blob keeps the tone's gradient, so adding the
 variables changes nothing until you set one. The `blobs` preset reads the same variables. `ActivityLayout` draws the same
-blobs, so set them on `[data-slot="activity-layout"]`:
+blobs (unless it has a `backdrop`), so set them on `[data-slot="activity-layout"]`:
 
 ```css
 [data-slot="activity-layout"] {

package/docs/troubleshooting.md

@@ -58,6 +58,7 @@ words in your error.
 - [My activity content lost its side padding, or the rail's entries moved up](#my-activity-content-lost-its-side-padding-or-the-rails-entries-moved-up)
 - [axe reports `target-size` on a control under a form's sticky actions](#axe-reports-target-size-on-a-control-under-a-forms-sticky-actions)
 - [`color-contrast` fails over the background blobs on phone](#color-contrast-fails-over-the-background-blobs-on-phone)
+- [`ActivityLayout`'s `backdrop` shows nothing, or the blobs are still there](#activitylayouts-backdrop-shows-nothing-or-the-blobs-are-still-there)
 - [Shaped Gallery tiles are plain rounded squares](#shaped-gallery-tiles-are-plain-rounded-squares)
 - [A component with my own tone (Shape, Fab, Avatar, StatCard, a metric card) shows no colour, or `tone` is a type error](#a-component-with-my-own-tone-shape-fab-avatar-statcard-a-metric-card-shows-no-colour-or-tone-is-a-type-error)
 - [A test expects the old `bg-muted` Avatar fallback, or a filled fallback shows a grey ring](#a-test-expects-the-old-bg-muted-avatar-fallback-or-a-filled-fallback-shows-a-grey-ring)
@@ -1254,6 +1255,23 @@ reports "needs review", not a failure), and delete the `[data-layer]` rules:
 }
 ```
 
+### `ActivityLayout`'s `backdrop` shows nothing, or the blobs are still there
+
+**When:** `<ActivityLayout backdrop={<Background preset="shapes" />}>` draws
+no shapes, or draws the gradient's blobs behind them.
+**Why:** the presets' CSS is not in `styles.css`, it is its own opt-in file, so
+without it the preset's layers have no look. The blobs are hidden by CSS keyed
+on `data-backdrop` in `styles.css`; they stay when the `Background` you pass
+comes from `@nxgt/material/components` (the gradient alone) and so draws its own
+blobs, or when the page loads a copy of `styles.css` older than 3.5.
+**Fix:** import `Background` from `@nxgt/material/backgrounds`, import
+`@nxgt/material/backgrounds.css` once, and keep `@nxgt/material` current.
+
+```tsx
+import { Background } from '@nxgt/material/backgrounds';
+import '@nxgt/material/backgrounds.css';
+```
+
 ### A ResponsiveButton no longer shows its tooltip next to its visible label
 
 **When:** a `ResponsiveButton` with a `tooltip` on a desktop width (768 px and up, or `expanded`), where the tooltip used to appear beside the label.

package/lib/components/components.css

@@ -56,6 +56,7 @@
 @import "./ui/actions/button-group/button-group.css";
 /* ActivityLayout: the route transition (cross-fade, none under reduced motion). */
 @import "./ui/layout/app-shell/route-transition.css";
+@import "./ui/layout/app-shell/activity-backdrop.css";
 /* DataTable cards and tiles: the item shell (hairline, tint, start bar, columns by the list's width). */
 @import "./ui/collections/data-table/data-table-items.css";
 @import "./ui/collections/data-table/data-table-items-compact.css";

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

@@ -0,0 +1,24 @@
+/* ActivityLayout's `backdrop` prop: a node (a `Background` preset from
+ * `@nxgt/material/backgrounds`) drawn behind the frame instead of the built-in
+ * gradient. `data-backdrop` is on the layout's root only while one is given, so
+ * without it nothing here matches and the gradient is unchanged.
+ *
+ * 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 positioned by classes in activity-layout.tsx. */
+@layer components {
+	/* The gradient's own tint and blobs give way to the backdrop. */
+	[data-slot="activity-layout"][data-backdrop] {
+		background-image: none;
+	}
+	[data-slot="activity-layout"][data-backdrop] > [data-layer] {
+		display: none;
+	}
+
+	/* A preset fills the layer: the layer's size, not `100lvw x 100lvh`, which
+	 * counts the scrollbar and a phone's toolbar. */
+	[data-slot="activity-layout-backdrop"] > [data-background] {
+		width: 100%;
+		height: 100%;
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/material",
-	"version": "3.4.0",
+	"version": "3.5.0",
 	"license": "MIT",
 	"bugs": {
 		"email": "stevegires@gmail.com"