@nxgt/material 3.15.0 → 3.16.0

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

@@ -81,6 +81,9 @@ phone's menu sheet pad clear of `env(safe-area-inset-*)`, as classes; see the
 | `menuOpen` / `onMenuOpenChange` | `boolean` / `(open: boolean) => void` | — | control the phone's menu sheet; it still closes by itself when a link in it is followed or the location changes (see the [app shell guide](../guides/app-shell.md#activitylayout)) |
 | `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 |
+| `width` | `'full' \| 'form' \| 'reading'` | `'full'` | `ActivityContent`: caps the main column at 48rem (`'form'`) or 72ch (`'reading'`), the side panel right beside it |
+| `aside`, `asideLabel` / `asideLabelledBy` | `ReactNode`, `string` | — | `ActivityContent`: a side panel, a named `complementary` landmark, beside the content from 1280px (CSS only), stacked below; sticky under the app bar |
+| `asideSide` / `asideWidth` / `asideFrom` / `asideSticky` / `asideStack` | `'start' \| 'end'` / `'sm' \| 'md' \| 'lg' \| string` / `'lg' \| 'xl' \| '2xl'` / `boolean` / `'before' \| 'after'` | `'end'` / `'md'` / `'xl'` / `true` / `'after'` | `ActivityContent`: the panel's side, width (16, 20, 24rem), breakpoint, stickiness and stacking order (see the [app shell guide](../guides/app-shell.md#a-side-panel-and-a-readable-width)) |
 | `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 \| false` | — | `ActivityLayout`: an exception to the theme's background (drawn by default; Lavande's is the built-in gradient and blobs); `false` draws a plain page. A node is a decorative background behind the frame: 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) |

package/docs/guides/app-shell.md

@@ -799,6 +799,15 @@ export function BoardShell({ items }: { items: MenuItem[] }) {
 | `hideHeader` | `boolean` | `false` | No header card |
 | `titleAs` | `'h1'` … `'h6'` \| `'div'` | `'h1'` | The title's element: the screen's heading, `'h2'` under a heading of yours, `'div'` for none |
 | `inset` | `boolean` | `false` | Pads the content 1rem on each side. Off, it lines up with the app bar and the cards |
+| `width` | `'full'` \| `'form'` \| `'reading'` | `'full'` | Caps the main column: `'form'` 48rem, `'reading'` 72ch. The header card keeps the full width |
+| `aside` | `ReactNode` | — | A side panel: beside the content from `asideFrom`, stacked below it |
+| `asideLabel` / `asideLabelledBy` | `string` | — | The panel's accessible name (`aria-label`), or the id of a heading inside it (`aria-labelledby`). One of them is needed |
+| `asideSide` | `'start'` \| `'end'` | `'end'` | Which side of the content the panel sits on, wide |
+| `asideWidth` | `'sm'` \| `'md'` \| `'lg'` \| a CSS length | `'md'` | 16, 20 or 24rem; `'md'` reads the `--nxgt-aside-width` token (20rem) |
+| `asideFrom` | `'lg'` \| `'xl'` \| `'2xl'` | `'xl'` | The viewport width (1024, 1280 or 1536px) from which the panel is beside the content |
+| `asideSticky` | `boolean` | `true` | Keeps the panel under the app bar while the page scrolls; it scrolls inside itself when taller than the window |
+| `asideStack` | `'before'` \| `'after'` | `'after'` | Where the panel goes below `asideFrom`, in the DOM and on screen |
+| `asideClassName` | `string` | — | Classes for the panel |
 
 ```tsx
 import { ActivityContent, Button } from '@nxgt/material/components';
@@ -819,6 +828,49 @@ export function InvoicesPage() {
 The header card wraps: on a narrow screen the actions go under the title
 instead of squeezing it, and a long title wraps rather than scrolling.
 
+### A side panel and a readable width
+
+A record's alerts and key facts, a dashboard's counts, a form's help: pass them
+as `aside`. From `asideFrom` (`'xl'`, a 1280px window) the panel sits beside the
+main column and sticks under the app bar; below it, the panel stacks after the
+content (`asideStack="before"` puts it first). The switch is CSS only: the
+server's HTML and a phone's first paint are already right, and no JavaScript
+decides the layout.
+
+```tsx
+<ActivityContent
+  title="New visit"
+  width="form"
+  aside={<DuplicateHints />}
+  asideLabel="Possible duplicates"
+>
+  <VisitForm />
+</ActivityContent>
+```
+
+- **Landmark.** The panel is an `<aside>`, a `complementary` landmark: name it
+  with `asideLabel`, or with `asideLabelledBy` (the id of its heading). Its
+  content is the panel's own; give it one `h2` when it has a heading.
+- **Sticky, in every scroll mode.** With `scroll="document"` the panel sticks
+  under the app bar (the bar's gutter, its `--nxgt-header-height` and 0.5rem);
+  with `scroll="container"` it sticks to the top of the content region. It is as
+  tall as the window at most and scrolls inside itself, and becomes focusable
+  (`tabindex="0"`) only while it does, so a keyboard reaches what overflows. A
+  `scroll="document"` page needs no `overflow` on any ancestor of the screen
+  (see [the troubleshooting entry](../troubleshooting.md#the-side-panel-does-not-stick)).
+- **A capped column sits beside its panel.** `width="form"` or `"reading"` caps
+  the main column and the pair stays start-aligned: at 1920px the panel is 1rem
+  from the fields, not at the window's far edge. The header card above keeps
+  the full width. `width` also works without a panel.
+- **The breakpoint is the window's.** `asideFrom` follows the viewport, not the
+  content column, which the sidebar and the gutters narrow a little: pick `'lg'`
+  for a panel on a smaller window, `'2xl'` to keep it stacked on all but the
+  widest.
+- **A size container.** With a panel, the main column is an `@container`, so a
+  `ResponsiveGrid` inside it follows the column's width.
+- **Width token.** `--nxgt-aside-width` changes `asideWidth="md"` (20rem) app-wide;
+  any CSS length goes in `asideWidth` for one screen.
+
 ## Breadcrumbs
 
 `AppBreadcrumb` (rendered by `ActivityLayout`) starts with a home icon linking

package/docs/guides/theming.md

@@ -625,6 +625,7 @@ centre line from `md` (48rem) up:
 | Token | Default | Reads |
 | --- | --- | --- |
 | `--nxgt-header-height` | `4rem` | the app bar (all widths) and the rail's header (`md` and up) |
+| `--nxgt-aside-width` | `20rem` | an `ActivityContent` side panel with `asideWidth="md"` (the default) |
 
 ```css
 :root {

package/docs/troubleshooting.md

@@ -1338,6 +1338,30 @@ top (`align="start"`).
 <ActivityLayout items={items} align="center">…</ActivityLayout>
 ```
 
+### The side panel does not stick
+
+**When:** an `ActivityContent` `aside` scrolls away with the page instead of
+staying under the app bar, or it is not beside the content at 1280px.
+**Why:** `position: sticky` sticks inside its nearest scrolling ancestor, and
+any ancestor with an `overflow` other than `visible` (`overflow-hidden`,
+`overflow-auto`, `overflow-clip`; a `PaneLayout`'s root has `overflow-hidden`)
+becomes that scroller, which does not scroll, so the panel never moves. A
+wrapper of yours around the screen, or an `ActivityLayout` with
+`scroll="container"` where you meant `"document"`, does the same. Below
+`asideFrom` (1280px by default) the panel is stacked and not sticky on
+purpose, and the breakpoint is the window's width, not the column's.
+**Fix:** take the `overflow` off every ancestor between `ActivityLayout` and
+`ActivityContent`, or move it onto an element inside the screen; use
+`scroll="document"` (the default). Find the culprit in the console:
+
+```js
+for (let el = document.querySelector('[data-slot="activity-content-aside"]').parentElement; el; el = el.parentElement)
+  if (getComputedStyle(el).overflowY !== 'visible') console.log(el);
+```
+
+With `scroll="container"` the region itself is the scroller, and the panel
+sticks to its top: that is expected.
+
 ### axe reports `target-size` on a control under a form's sticky actions
 
 **When:** since the form's actions stick to the bottom (see above), axe's

package/package.json

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