@nxgt/material 3.7.2 → 3.7.4

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

@@ -81,7 +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 content column; the chrome and lists stay opaque over it, coloured by `--nxgt-backdrop-chrome` and `--nxgt-backdrop-surface`. See [Use a background preset behind the shell](../guides/app-shell.md#use-a-background-preset-behind-the-shell) |
+| `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 as wide as the content column and one viewport high, fixed in the viewport while the content scrolls; the chrome (app bar, breadcrumb, tabs strip) is lightly translucent and frosted over it (80%, 87% for the sidebar, breadcrumb and tabs strip, 92% and no blur under `prefers-reduced-transparency` or without `backdrop-filter`), and the lists, tables and cards stay opaque; `--nxgt-backdrop-chrome` sets the chrome's fill and `--nxgt-backdrop-surface` the lists'. 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

@@ -513,26 +513,29 @@ export function Shell({ items }: { items: MenuItem[] }) {
   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 the content column.** The node is wrapped in a layer
-  (`[data-slot="activity-layout-backdrop"]`) that fills the column beside the
+  (`[data-slot="activity-layout-backdrop"]`) that spans the column's width beside the
   sidebar, under the app bar, the breadcrumb 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 column.** 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 column grows with the content, and so does the preset.
-- **The shapes stay in the free content area.** Under a `backdrop`, every
-  surface of the chrome is opaque, so no shape runs behind a text, an icon or a
-  control: the sidebar (over its full height), the app bar, the breadcrumb (a
-  pill as wide as its crumbs), the tabs strip, the lists and tables (band and
-  rows), the segmented `ToggleGroup`, the list bar and the phone tiles. Nothing
-  changes without a `backdrop`. Two tokens set the colours, on the layout (a
-  `className` such as `[--nxgt-backdrop-chrome:var(--muted)]`) or on any
-  ancestor:
+  not to `100lvw × 100lvh`, so you need no `className` or `fill`. The layer is
+  as wide as the column and one viewport high, and stays in the viewport while
+  the content scrolls over it, in `scroll="document"` (the page scrolls) and in
+  `scroll="container"` alike.
+- **The chrome is lightly translucent and frosted.** Under a `backdrop`, the
+  app bar, the breadcrumb (a pill as wide as its crumbs) and the tabs strip
+  show a shape faintly through their fill, over a 6px blur that keeps it from
+  competing with a text. The lists and tables (band and rows), the segmented
+  `ToggleGroup`, the list bar, the phone tiles and the cards stay opaque, so no
+  shape runs behind a row. The sidebar is frosted too (87%), but the layer is
+  only in the content column, so no shape is drawn behind it. Nothing changes
+  without a `backdrop`. Two tokens set the colours, on the layout (a `className`
+  such as `[--nxgt-backdrop-chrome:var(--muted)]`) or on any ancestor:
 
   | Token | Paints | Default |
   | --- | --- | --- |
-  | `--nxgt-backdrop-chrome` | sidebar, app bar, breadcrumb, tabs strip | `var(--background)` |
-  | `--nxgt-backdrop-surface` | lists and tables (`DataTable`, `ServerTable`) | `var(--card)` |
+  | `--nxgt-backdrop-chrome` | sidebar, app bar, breadcrumb, tabs strip | `--background` at 80% (app bar) or 87% (sidebar, breadcrumb, tabs strip), over a 6px blur |
+  | `--nxgt-backdrop-surface` | lists and tables (`DataTable`, `ServerTable`) | `var(--card)`, opaque |
 
   ```tsx
   <ActivityLayout
@@ -541,12 +544,19 @@ export function Shell({ items }: { items: MenuItem[] }) {
   >
   ```
 
-  Give a colour, not a translucent one: a see-through surface lets the shapes
-  run behind the text again. Tone the preset down with its `intensity`
-  (`subtle`) rather than restyling the frame. The backdrop shows only inside
-  the content column (its layer is in the column, rounded like the frame): the
-  frame's padding, the gap beside the sidebar and the strip above the app bar
-  are the chrome colour, so no shape is cut at the edges.
+  The 87% is the least that keeps the sidebar's, the breadcrumb's and the tabs'
+  text at 4.5:1 over the darkest shape of the `shapes` preset in the light
+  theme (the app bar's text and every icon and the tab indicator pass at 80%,
+  by a wide margin in the dark theme). Under
+  `@media (prefers-reduced-transparency: reduce)`, and where `backdrop-filter`
+  is unsupported, the blur is off and the fill is 92%. `--nxgt-backdrop-chrome`
+  replaces the fill whole, so a colour you give is not translucent unless you
+  make it so; a see-through colour lets the shapes run behind the text, so check
+  its contrast over the preset you use. Tone the preset down with its
+  `intensity` (`subtle`) rather than restyling the frame. The backdrop shows
+  only inside the content column (its layer is in the column, rounded like the
+  frame): the frame's padding, the gap beside the sidebar and the strip above
+  the app bar are the chrome colour, so no shape is cut at the edges.
 - **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.

package/docs/troubleshooting.md

@@ -1324,19 +1324,14 @@ import { Background } from '@nxgt/material/backgrounds';
 import '@nxgt/material/backgrounds.css';
 ```
 
-### Shapes of an `ActivityLayout` `backdrop` run behind the text of the chrome or a list
+### Shapes of an `ActivityLayout` `backdrop` show through the chrome, or run behind the text of a list
 
-**When:** with `backdrop`, a breadcrumb, a tabs strip, a table or the sidebar
-shows the shapes through it, or you set a translucent colour and they come back.
-**Why:** under `data-backdrop` those surfaces take `--nxgt-backdrop-chrome` (default
-`var(--background)`) and `--nxgt-backdrop-surface` (default `var(--card)`); before
-3.7.2 they had no surface or a translucent one, and a custom `className` with its
-own `bg-*` on a list wins over the token.
-**Fix:** update `@nxgt/material`, and give the tokens opaque colours; drop a
-`bg-*/NN` class from the list's `className`.
+**When:** with `backdrop`, the app bar, the breadcrumb, the tabs strip or the sidebar shows the shapes faintly through it; or a table or list shows them behind its rows, or a colour of your own made them come back.
+**Why:** the chrome is deliberately lightly translucent and frosted: under `data-backdrop` it takes `--nxgt-backdrop-chrome` (default `--background` at 80% for the app bar, 87% for the sidebar, breadcrumb and tabs strip, over a 6px blur; 92% and no blur under `prefers-reduced-transparency` or without `backdrop-filter`). The lists take `--nxgt-backdrop-surface` (default `var(--card)`, opaque); a custom `className` with its own `bg-*` on a list wins over the token, and before 3.7.2 lists had no surface or a translucent one.
+**Fix:** for a solid chrome, set `--nxgt-backdrop-chrome` to an opaque colour. A translucent colour of your own needs a contrast check over the preset you use. For a list, update `@nxgt/material`, set `--nxgt-backdrop-surface` to an opaque colour and drop a `bg-*/NN` class from its `className`.
 
 ```tsx
-<ActivityLayout backdrop={<Background preset="shapes" />} className="[--nxgt-backdrop-surface:var(--background)]" />
+<ActivityLayout backdrop={<Background preset="shapes" />} className="[--nxgt-backdrop-chrome:var(--background)] [--nxgt-backdrop-surface:var(--background)]" />
 ```
 
 ### A ResponsiveButton no longer shows its tooltip next to its visible label

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

@@ -9,13 +9,18 @@
  * frame's padding and gaps take the chrome fill, so the shapes show nowhere
  * else.
  *
- * The shapes show in the free content area only: every surface of the chrome and
- * of the lists is opaque, so none runs behind a text, an icon or a control. Two
- * tokens, set on the layout (or any ancestor), tune them:
+ * 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,
+ * the sidebar, the breadcrumb and the tabs strip, whose text needs it to keep
+ * WCAG AA over the darkest shape in the light theme) over a 6px blur
+ * (--nxgt-backdrop-blur), so a shape shows faintly behind them, too blurred to
+ * compete with a text. The lists, tables and cards stay opaque. Under `prefers-reduced-transparency:
+ * reduce`, or where `backdrop-filter` is unsupported, the blur is off and the
+ * fill is 92% (both). Two tokens, set on the layout (or any ancestor), tune them:
  *   --nxgt-backdrop-chrome   the sidebar, the app bar, the breadcrumb, the tabs
- *                            strip (default: var(--background))
+ *                            strip (default: the background at 80% / 92%)
  *   --nxgt-backdrop-surface  the lists and tables, their band and rows
- *                            (default: var(--card))
+ *                            (default: var(--card), opaque)
  * The sidebar, the app bar and the tables take theirs from a class whose
  * fallback is their usual surface, through `--nxgt-backdrop-fill-*`: a utility
  * class outranks any rule in a layer, so a rule here could not set them. */
@@ -35,11 +40,69 @@
 		height: 100%;
 	}
 
+	/* The layer is sticky, not absolute: it keeps the column's left and right
+	 * edges and stays in the viewport, from the app bar's top to the frame's
+	 * bottom padding, while the page (scroll="document") or the content region
+	 * (scroll="container") scrolls over it. It is the column's first child, so
+	 * a negative bottom margin (its height, and the column's 0.5rem gap) takes
+	 * it out of the flow: the app bar keeps its place. The offsets are the
+	 * frame's own padding and the app bar's sticky top. */
+	[data-slot="activity-layout-backdrop"] {
+		--nxgt-backdrop-top: max(0.5rem, env(safe-area-inset-top));
+		--nxgt-backdrop-height: calc(
+			100dvh -
+			var(--nxgt-backdrop-top) -
+			max(0.5rem, env(safe-area-inset-bottom)) -
+			var(--nxgt-media-dock, 0px)
+		);
+		position: sticky;
+		top: var(--nxgt-backdrop-top);
+		height: var(--nxgt-backdrop-height);
+		margin-bottom: calc(-1 * var(--nxgt-backdrop-height) - 0.5rem);
+	}
+
 	[data-slot="activity-layout"][data-backdrop] {
-		--nxgt-backdrop-fill-chrome: var(--nxgt-backdrop-chrome, var(--background));
+		--nxgt-backdrop-chrome-alpha: 80%;
+		--nxgt-backdrop-nav-alpha: 87%;
+		--nxgt-backdrop-blur: 6px;
+		--nxgt-backdrop-fill-chrome: var(
+			--nxgt-backdrop-chrome,
+			color-mix(
+				in oklab,
+				var(--background) var(--nxgt-backdrop-chrome-alpha),
+				transparent
+			)
+		);
+		--nxgt-backdrop-fill-nav: var(
+			--nxgt-backdrop-chrome,
+			color-mix(
+				in oklab,
+				var(--background) var(--nxgt-backdrop-nav-alpha),
+				transparent
+			)
+		);
 		--nxgt-backdrop-fill-surface: var(--nxgt-backdrop-surface, var(--card));
 	}
 
+	/* No blur to lean on: a more opaque fill instead. */
+	@supports not (
+			(backdrop-filter: blur(1px)) or
+			(-webkit-backdrop-filter: blur(1px))
+		) {
+		[data-slot="activity-layout"][data-backdrop] {
+			--nxgt-backdrop-chrome-alpha: 92%;
+			--nxgt-backdrop-nav-alpha: 92%;
+			--nxgt-backdrop-blur: 0px;
+		}
+	}
+	@media (prefers-reduced-transparency: reduce) {
+		[data-slot="activity-layout"][data-backdrop] {
+			--nxgt-backdrop-chrome-alpha: 92%;
+			--nxgt-backdrop-nav-alpha: 92%;
+			--nxgt-backdrop-blur: 0px;
+		}
+	}
+
 	/* The breadcrumb trail: a pill under the app bar, as wide as its crumbs. */
 	[data-slot="activity-layout"][data-backdrop]
 		[data-slot="activity-layout-frame"]
@@ -50,7 +113,9 @@
 		padding-block: 0.25rem;
 		padding-inline-end: 0.75rem;
 		border-radius: 999px;
-		background: var(--nxgt-backdrop-fill-chrome);
+		background: var(--nxgt-backdrop-fill-nav);
+		-webkit-backdrop-filter: blur(var(--nxgt-backdrop-blur));
+		backdrop-filter: blur(var(--nxgt-backdrop-blur));
 	}
 
 	/* Tabs: the strip is a band, its top corners rounded. (The segmented look
@@ -58,6 +123,8 @@
 	[data-slot="activity-layout"][data-backdrop] [data-slot="tabs-list"] {
 		border-start-start-radius: var(--radius);
 		border-start-end-radius: var(--radius);
-		background: var(--nxgt-backdrop-fill-chrome);
+		background: var(--nxgt-backdrop-fill-nav);
+		-webkit-backdrop-filter: blur(var(--nxgt-backdrop-blur));
+		backdrop-filter: blur(var(--nxgt-backdrop-blur));
 	}
 }

package/package.json

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