@nxgt/material 3.26.1 → 3.27.0

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

@@ -207,7 +207,7 @@ import { AuthCard, Button, EmailField, LanguageSwitcher, PasswordField } from '@
 | `banner` | `ReactNode` | — | above that row (an update notice) |
 | `footer` | `ReactNode` | — | under the card |
 | `backdrop` | `ReactNode \| false` | the theme's background | what is drawn behind the page: a `Background` preset or any node; `false` for none. Without a theme provider nothing is drawn |
-| `keepClear` | `boolean` | `true` | glyphs (shapes or icons) of the backdrop that would meet the brand row, the card or the page's surfaces, text or controls are dropped (never moved); `false` lets them run under the card |
+| `keepClear` | `boolean \| 'gaps'` | `true` | glyphs (shapes or icons) of the backdrop that would meet the brand row, the card or the page's surfaces, text or controls are dropped (never moved); `false` lets them run under the card; `'gaps'` also keeps a glyph that fits in a gap of 24px or more between two surfaces |
 
 ```tsx
 import { Background } from '@nxgt/material/backgrounds';

package/docs/guides/app-shell.md

@@ -210,6 +210,7 @@ partitionMenu(items);                              // { content, footer }
 | `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 \| false` | — | An exception to the theme's background (the page ground, [`--ground`](#the-page-ground), is painted either way), which the layout draws by default (Lavande's: the built-in gradient and blobs). A node replaces it for this screen: usually a `Background` preset from `@nxgt/material/backgrounds` (see [Use a background preset behind the shell](#use-a-background-preset-behind-the-shell)); `false` draws no background, a plain page |
+| `keepClear` | `boolean \| 'gaps'` | `true` | how the backdrop's glyphs keep clear of the page: `true` drops every glyph within 8px of a surface, a text or a control; `'gaps'` also keeps a glyph that fits in a gap of 24px or more between two surfaces; `false` keeps nothing clear (the edge and the header band still are). See [Keep the backdrop clear of the content](#keep-the-backdrop-clear-of-the-content) |
 
 On a page with `viewport-fit=cover` (an installed PWA drawing under a
 notch and the home indicator), the shell pads clear of
@@ -646,6 +647,43 @@ export function Shell({ items }: { items: MenuItem[] }) {
 - The `--nxgt-bg-blob-1..3` variables recolour the built-in blobs only; the
   `blobs` preset reads them too.
 
+## Keep the backdrop clear of the content
+
+Behind the shell a glyph of the backdrop (a shape or an icon) is dropped, never
+moved, when its box meets the page's content. `keepClear` sets how strict that
+is:
+
+| `keepClear` | Result |
+| --- | --- |
+| `true` (default) | a glyph within 8px of a surface (a card, a stat card, a list, a table), a text or a control is dropped |
+| `'gaps'` | the same for text, controls and the inside of a surface, but a glyph may stay between two surfaces when its whole box fits in a gap of 24px or more (4px to spare from each card) |
+| `false` | the content is not measured; only the layer's edge and the header band drop a glyph |
+
+On a dense page (stat cards, a list, a grid of cards 24 to 32px apart) `true`
+leaves almost no glyph. `'gaps'` is opt-in and keeps the glyphs small enough
+for the gutters, so use it on such a page. It adds little on a page with wide
+open areas, where `true` already draws them. It never keeps a glyph that sits
+on a card, on text or on a control, and it measures the same way as `true`:
+boxes are read first, then written in one frame, with the 150 ms fade. A
+floating (`animated`) scene keeps its drift margin, so it rarely fits a gutter.
+
+```tsx
+import { ActivityLayout } from '@nxgt/material/components';
+import { Background, MOTIF_SHAPES_ALL } from '@nxgt/material/backgrounds';
+
+<ActivityLayout
+  items={items}
+  backdrop={<Background preset="shapes" motif={{ shapes: MOTIF_SHAPES_ALL }} />}
+  keepClear="gaps"
+>
+  <Outlet />
+</ActivityLayout>
+```
+
+`AuthCard` takes the same prop (`keepClear="gaps"`). Its card and brand row
+are kept whole, so there it only adds glyphs between the page's other
+surfaces, such as a banner.
+
 ## Route transitions
 
 `ActivityLayout` wraps its content region (`data-slot="activity-content-region"`)

package/docs/guides/backgrounds.md

@@ -548,6 +548,11 @@ good.
   away. It runs again on resize and when the content changes.
 - The open areas keep their glyphs; the space behind and between cards is empty. `keepClear={false}` on an `AuthCard`
   lets the glyphs run under the card.
+- **`keepClear="gaps"`** (on `ActivityLayout` and `AuthCard`, opt-in; `true` stays the default) lets a glyph stay between
+  two surfaces when its whole box fits in a gap of 24 px or more, with 4 px to spare from each. It is still dropped when
+  it meets a text, a control or the inside of a surface. Use it on a dense page (stat cards, a list and a grid of cards
+  24 to 32 px apart), where `true` leaves almost nothing. A glyph wider than the gap is dropped as before. See
+  [Keep the backdrop clear of the content](./app-shell.md#keep-the-backdrop-clear-of-the-content).
 - See [The theme's background](./app-shell.md#the-themes-background) for the shell and `AuthCard` in
   [navigation and layout](../components/navigation-and-layout.md#authcard) for the sign-in page.
 

package/docs/troubleshooting.md

@@ -722,9 +722,20 @@ list) hold shapes.
 backdrop layer). Since 3.22 a glyph whose box meets a surface, a text or a
 control, within 8px, is dropped whole (the keep-clear pass), so a gap narrower
 than a glyph shows none.
-**Fix:** none needed, it is the documented behaviour (see [the drop rule](./guides/backgrounds.md) in
-the backgrounds guide). To see more shapes, leave open space in the page, or draw
-the backdrop in a layout that has no content over it.
+**Fix:** it is the documented behaviour (see [the drop rule](./guides/backgrounds.md) in
+the backgrounds guide). On a dense page, opt in to `keepClear="gaps"` on the
+`ActivityLayout` (or `AuthCard`): a glyph then stays when its box fits in a gap of
+24px or more between two surfaces, and is still dropped over text, a control or a
+card. A glyph wider than the gap is dropped as before. Or leave open space in the page.
+
+```tsx
+import { ActivityLayout } from '@nxgt/material/components';
+import { Background } from '@nxgt/material/backgrounds';
+
+<ActivityLayout items={items} backdrop={<Background preset="shapes" />} keepClear="gaps">
+  <Outlet />
+</ActivityLayout>
+```
 
 ### The page and the cards look the same
 

package/package.json

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