@womp/kookie-ui 0.26.2 → 0.27.0

package/src/components/shell.css

@@ -30,6 +30,8 @@
   --shell-inset-gap: var(--space-3);
   /* Written inline by the Root while a Rail shows; stated here so a nested Shell never inherits its parent's. */
   --shell-rail-offset: 0px;
+  /* How far the stuck header reaches down the screen while the page scrolls. Stated here so a nested Shell never inherits its parent's. */
+  --kui-shell-page-top: 0px;
 
   display: grid;
   grid-template-areas:
@@ -58,6 +60,14 @@
   }
 }
 
+/*
+ * A contained Shell fills its parent instead of the window. An explicit `height` is written
+ * inline and wins over this.
+ */
+.kui-ShellRoot[data-contained] {
+  height: 100%;
+}
+
 /* While an overlay is live the page holds still. Counted across Shells by the Root. */
 :root[data-kui-shell-lock] {
   overflow: hidden;
@@ -115,6 +125,8 @@
   --kui-pane-band-end: initial;
   --kui-shell-position: initial;
   --kui-shell-z: initial;
+  --kui-shell-pin: initial;
+  --kui-shell-pin-top: initial;
   --kui-shell-row: initial;
   --kui-shell-col: initial;
   --kui-shell-surface: initial;
@@ -470,6 +482,8 @@
 .kui-ShellRail[data-presentation='overlay'] ~ .kui-ShellPanel[data-presentation-follows] {
   --kui-shell-position: absolute;
   --kui-shell-z: 6;
+  --kui-shell-pin: fixed;
+  --kui-shell-pin-top: 0px;
   --kui-shell-row: 1 / -1;
   --kui-shell-col: 1 / -1;
   --kui-shell-surface: var(--color-surface);
@@ -484,6 +498,8 @@
 .kui-ShellRail[data-presentation='stacked'] ~ .kui-ShellPanel[data-presentation-follows] {
   --kui-shell-position: absolute;
   --kui-shell-z: 3;
+  --kui-shell-pin: fixed;
+  --kui-shell-pin-top: initial;
   --kui-shell-row: 2 / 3;
   --kui-shell-col: 1 / -1;
   --kui-shell-surface: var(--color-surface);
@@ -503,6 +519,8 @@
 .kui-ShellRail[data-presentation-initial='fixed'] ~ .kui-ShellPanel[data-presentation-follows] {
   --kui-shell-position: initial;
   --kui-shell-z: initial;
+  --kui-shell-pin: initial;
+  --kui-shell-pin-top: initial;
   --kui-shell-row: initial;
   --kui-shell-col: initial;
   --kui-shell-surface: initial;
@@ -517,6 +535,8 @@
 .kui-ShellRail[data-presentation-initial='overlay'] ~ .kui-ShellPanel[data-presentation-follows] {
   --kui-shell-position: absolute;
   --kui-shell-z: 6;
+  --kui-shell-pin: fixed;
+  --kui-shell-pin-top: 0px;
   --kui-shell-row: 1 / -1;
   --kui-shell-col: 1 / -1;
   --kui-shell-surface: var(--color-surface);
@@ -531,6 +551,8 @@
 .kui-ShellRail[data-presentation-initial='stacked'] ~ .kui-ShellPanel[data-presentation-follows] {
   --kui-shell-position: absolute;
   --kui-shell-z: 3;
+  --kui-shell-pin: fixed;
+  --kui-shell-pin-top: initial;
   --kui-shell-row: 2 / 3;
   --kui-shell-col: 1 / -1;
   --kui-shell-surface: var(--color-surface);
@@ -558,6 +580,8 @@
   .kui-ShellRail[data-presentation-xs='fixed'] ~ .kui-ShellPanel[data-presentation-follows] {
     --kui-shell-position: initial;
     --kui-shell-z: initial;
+    --kui-shell-pin: initial;
+    --kui-shell-pin-top: initial;
     --kui-shell-row: initial;
     --kui-shell-col: initial;
     --kui-shell-surface: initial;
@@ -572,6 +596,8 @@
   .kui-ShellRail[data-presentation-xs='overlay'] ~ .kui-ShellPanel[data-presentation-follows] {
     --kui-shell-position: absolute;
     --kui-shell-z: 6;
+    --kui-shell-pin: fixed;
+    --kui-shell-pin-top: 0px;
     --kui-shell-row: 1 / -1;
     --kui-shell-col: 1 / -1;
     --kui-shell-surface: var(--color-surface);
@@ -586,6 +612,8 @@
   .kui-ShellRail[data-presentation-xs='stacked'] ~ .kui-ShellPanel[data-presentation-follows] {
     --kui-shell-position: absolute;
     --kui-shell-z: 3;
+    --kui-shell-pin: fixed;
+    --kui-shell-pin-top: initial;
     --kui-shell-row: 2 / 3;
     --kui-shell-col: 1 / -1;
     --kui-shell-surface: var(--color-surface);
@@ -614,6 +642,8 @@
   .kui-ShellRail[data-presentation-sm='fixed'] ~ .kui-ShellPanel[data-presentation-follows] {
     --kui-shell-position: initial;
     --kui-shell-z: initial;
+    --kui-shell-pin: initial;
+    --kui-shell-pin-top: initial;
     --kui-shell-row: initial;
     --kui-shell-col: initial;
     --kui-shell-surface: initial;
@@ -628,6 +658,8 @@
   .kui-ShellRail[data-presentation-sm='overlay'] ~ .kui-ShellPanel[data-presentation-follows] {
     --kui-shell-position: absolute;
     --kui-shell-z: 6;
+    --kui-shell-pin: fixed;
+    --kui-shell-pin-top: 0px;
     --kui-shell-row: 1 / -1;
     --kui-shell-col: 1 / -1;
     --kui-shell-surface: var(--color-surface);
@@ -642,6 +674,8 @@
   .kui-ShellRail[data-presentation-sm='stacked'] ~ .kui-ShellPanel[data-presentation-follows] {
     --kui-shell-position: absolute;
     --kui-shell-z: 3;
+    --kui-shell-pin: fixed;
+    --kui-shell-pin-top: initial;
     --kui-shell-row: 2 / 3;
     --kui-shell-col: 1 / -1;
     --kui-shell-surface: var(--color-surface);
@@ -670,6 +704,8 @@
   .kui-ShellRail[data-presentation-md='fixed'] ~ .kui-ShellPanel[data-presentation-follows] {
     --kui-shell-position: initial;
     --kui-shell-z: initial;
+    --kui-shell-pin: initial;
+    --kui-shell-pin-top: initial;
     --kui-shell-row: initial;
     --kui-shell-col: initial;
     --kui-shell-surface: initial;
@@ -684,6 +720,8 @@
   .kui-ShellRail[data-presentation-md='overlay'] ~ .kui-ShellPanel[data-presentation-follows] {
     --kui-shell-position: absolute;
     --kui-shell-z: 6;
+    --kui-shell-pin: fixed;
+    --kui-shell-pin-top: 0px;
     --kui-shell-row: 1 / -1;
     --kui-shell-col: 1 / -1;
     --kui-shell-surface: var(--color-surface);
@@ -698,6 +736,8 @@
   .kui-ShellRail[data-presentation-md='stacked'] ~ .kui-ShellPanel[data-presentation-follows] {
     --kui-shell-position: absolute;
     --kui-shell-z: 3;
+    --kui-shell-pin: fixed;
+    --kui-shell-pin-top: initial;
     --kui-shell-row: 2 / 3;
     --kui-shell-col: 1 / -1;
     --kui-shell-surface: var(--color-surface);
@@ -726,6 +766,8 @@
   .kui-ShellRail[data-presentation-lg='fixed'] ~ .kui-ShellPanel[data-presentation-follows] {
     --kui-shell-position: initial;
     --kui-shell-z: initial;
+    --kui-shell-pin: initial;
+    --kui-shell-pin-top: initial;
     --kui-shell-row: initial;
     --kui-shell-col: initial;
     --kui-shell-surface: initial;
@@ -740,6 +782,8 @@
   .kui-ShellRail[data-presentation-lg='overlay'] ~ .kui-ShellPanel[data-presentation-follows] {
     --kui-shell-position: absolute;
     --kui-shell-z: 6;
+    --kui-shell-pin: fixed;
+    --kui-shell-pin-top: 0px;
     --kui-shell-row: 1 / -1;
     --kui-shell-col: 1 / -1;
     --kui-shell-surface: var(--color-surface);
@@ -754,6 +798,8 @@
   .kui-ShellRail[data-presentation-lg='stacked'] ~ .kui-ShellPanel[data-presentation-follows] {
     --kui-shell-position: absolute;
     --kui-shell-z: 3;
+    --kui-shell-pin: fixed;
+    --kui-shell-pin-top: initial;
     --kui-shell-row: 2 / 3;
     --kui-shell-col: 1 / -1;
     --kui-shell-surface: var(--color-surface);
@@ -782,6 +828,8 @@
   .kui-ShellRail[data-presentation-xl='fixed'] ~ .kui-ShellPanel[data-presentation-follows] {
     --kui-shell-position: initial;
     --kui-shell-z: initial;
+    --kui-shell-pin: initial;
+    --kui-shell-pin-top: initial;
     --kui-shell-row: initial;
     --kui-shell-col: initial;
     --kui-shell-surface: initial;
@@ -796,6 +844,8 @@
   .kui-ShellRail[data-presentation-xl='overlay'] ~ .kui-ShellPanel[data-presentation-follows] {
     --kui-shell-position: absolute;
     --kui-shell-z: 6;
+    --kui-shell-pin: fixed;
+    --kui-shell-pin-top: 0px;
     --kui-shell-row: 1 / -1;
     --kui-shell-col: 1 / -1;
     --kui-shell-surface: var(--color-surface);
@@ -810,6 +860,8 @@
   .kui-ShellRail[data-presentation-xl='stacked'] ~ .kui-ShellPanel[data-presentation-follows] {
     --kui-shell-position: absolute;
     --kui-shell-z: 3;
+    --kui-shell-pin: fixed;
+    --kui-shell-pin-top: initial;
     --kui-shell-row: 2 / 3;
     --kui-shell-col: 1 / -1;
     --kui-shell-surface: var(--color-surface);
@@ -844,6 +896,8 @@
 .kui-ShellRail ~ .kui-ShellPanel[data-presentation-follows][data-peek][data-state] {
   --kui-shell-position: absolute;
   --kui-shell-z: 4;
+  --kui-shell-pin: fixed;
+  --kui-shell-pin-top: initial;
   --kui-shell-row: 2 / 3;
   --kui-shell-col: 1 / -1;
   --kui-shell-surface: var(--color-surface);
@@ -946,6 +1000,153 @@
   margin-block-start: 0;
 }
 
+/* ── On a phone, the page scrolls (0.27.0) ────────────────────────────────── */
+
+/*
+ * Ported from kookie-ui-v2's Shell. A mobile browser hides its toolbars only when the document
+ * scrolls; no scroller inside the page reaches them. So on a narrow window with a coarse pointer
+ * a window Shell (`data-window`: no `contained`, no `height`) grows with its content and the
+ * document scrolls instead of the content pane. Everything that stayed put while the pane
+ * scrolled stays put while the page scrolls: the header and the content's pinned rows stick, and
+ * the drawers and the scrim attach to the screen.
+ *
+ * Narrow is below the `sm` breakpoint, where v1's panes leave the overlay posture by default.
+ * `_internal/shell-page-scroll.ts` holds the same query for the few things only script can do,
+ * and a test holds the two equal.
+ *
+ * Content that cannot wrap is clipped at the screen's edge rather than widening the page: it
+ * needs its own horizontal scroller, as a code block has.
+ */
+@media (max-width: 767.98px) and (pointer: coarse) {
+  /* `clip`, not `hidden`: a hidden box is a scroll container, and it would catch every sticky row. */
+  .kui-ShellRoot[data-window] {
+    height: auto;
+    min-height: 100vh;
+    overflow: clip;
+  }
+
+  @supports (height: 100dvh) {
+    .kui-ShellRoot[data-window] {
+      min-height: 100dvh;
+    }
+  }
+
+  /* The header's height, for the rows that stick beneath it. The Root writes `--kui-shell-header-h`
+     when a Shell.Header is not the default 64px. */
+  .kui-ShellRoot[data-window]:has(> .kui-ShellHeader) {
+    --kui-shell-page-top: var(--kui-shell-header-h, 64px);
+  }
+
+  .kui-ShellRoot[data-window] > .kui-ShellHeader {
+    position: sticky;
+    top: 0;
+  }
+
+  /*
+   * The content stops scrolling. Isolated, so nothing the app layers inside it climbs over a
+   * sticky row and takes its taps. A focused control or a linked heading scrolls into view
+   * beneath the stuck rows rather than under them.
+   */
+  .kui-ShellRoot[data-window] > .kui-ShellContent {
+    overflow: clip;
+    isolation: isolate;
+  }
+
+  .kui-ShellRoot[data-window] > .kui-ShellContent :where(*) {
+    scroll-margin-block: calc(var(--kui-shell-page-top) + var(--kui-content-float-start, 0px)) var(--kui-content-float-end, 0px);
+  }
+
+  /* The floating rows' reach, as the content's Shell.Scroll works it out above. */
+  .kui-ShellRoot[data-window] > .kui-ShellContent:has(> .kui-ShellPaneHeader[data-float]) {
+    --kui-content-float-start: calc(max(var(--kui-pane-row-start), var(--kui-pane-band-start, 0px)) + 2 * var(--kui-pane-pad-start));
+  }
+
+  .kui-ShellRoot[data-window] > .kui-ShellContent:has(> .kui-ShellPaneFooter[data-float]) {
+    --kui-content-float-end: calc(max(var(--kui-pane-row-end), var(--kui-pane-band-end, 0px)) + 2 * var(--kui-pane-pad-end));
+  }
+
+  /*
+   * Shell.Scroll in the content stops scrolling too and grows with what it holds. The viewport's
+   * overflow is written inline by Radix, hence `!important`. Its scrollbar and fade go: the
+   * document's own scrollbar is the one a phone shows, and a mask with nothing to scroll could
+   * only cut the page's edge.
+   */
+  .kui-ShellRoot[data-window] > .kui-ShellContent > .kui-ShellScroll {
+    flex: none;
+    height: auto;
+    overflow: clip;
+  }
+
+  .kui-ShellRoot[data-window] > .kui-ShellContent > .kui-ShellScroll > .kui-ScrollAreaViewport {
+    height: auto;
+    overflow: visible !important;
+    mask-image: none;
+  }
+
+  .kui-ShellRoot[data-window] > .kui-ShellContent > .kui-ShellScroll > .kui-ScrollAreaScrollbar {
+    display: none;
+  }
+
+  /*
+   * The floating rows stick, and still float. Sticky is in flow, so a negative margin gives back
+   * the room the row takes and the page starts where it starts in the frame. `order` because a
+   * row sticks where it sits, and a footer must sit after the page.
+   */
+  .kui-ShellRoot[data-window] > .kui-ShellContent:has(> .kui-ShellScroll) > .kui-ShellPaneHeader[data-float] {
+    position: sticky;
+    top: var(--kui-shell-page-top);
+    order: -1;
+    margin-bottom: calc(-1 * var(--kui-content-float-start, 0px));
+  }
+
+  .kui-ShellRoot[data-window] > .kui-ShellContent:has(> .kui-ShellScroll) > .kui-ShellPaneFooter[data-float] {
+    position: sticky;
+    bottom: 0;
+    order: 1;
+    margin-top: calc(-1 * var(--kui-content-float-end, 0px));
+  }
+
+  /* A pinned sibling of the Scroll pins to the screen: one before it to the top, beneath the
+     header, one after it to the bottom. */
+  .kui-ShellRoot[data-window] > .kui-ShellContent > :not(.kui-ShellScroll, [data-float]):has(~ .kui-ShellScroll) {
+    position: sticky;
+    top: var(--kui-shell-page-top);
+    z-index: 1;
+  }
+
+  .kui-ShellRoot[data-window] > .kui-ShellContent > .kui-ShellScroll ~ :not([data-float]) {
+    position: sticky;
+    bottom: 0;
+    z-index: 1;
+  }
+
+  /*
+   * The panes. A pane over the page (overlay, stacked, peek) attaches to the screen: its posture
+   * writes `--kui-shell-pin: fixed`. A pane in flow sticks beneath the header, a screen tall, and
+   * the bottom pane sticks to the screen's bottom. An overlay covers the header
+   * (`--kui-shell-pin-top: 0px`); the rest start beneath it.
+   */
+  .kui-ShellRoot[data-window] > :is(.kui-ShellRail, .kui-ShellPanel, .kui-ShellSidebar, .kui-ShellInspector) {
+    position: var(--kui-shell-pin, sticky);
+    top: var(--kui-shell-pin-top, var(--kui-shell-page-top));
+    block-size: calc(100vh - var(--kui-shell-pin-top, var(--kui-shell-page-top)));
+  }
+
+  @supports (height: 100dvh) {
+    .kui-ShellRoot[data-window] > :is(.kui-ShellRail, .kui-ShellPanel, .kui-ShellSidebar, .kui-ShellInspector) {
+      block-size: calc(100dvh - var(--kui-shell-pin-top, var(--kui-shell-page-top)));
+    }
+  }
+
+  .kui-ShellRoot[data-window] > .kui-ShellBottom {
+    position: var(--kui-shell-pin, sticky);
+  }
+
+  .kui-ShellRoot[data-window] > .kui-ShellScrim {
+    position: fixed;
+  }
+}
+
 /* ── Resize handle ─────────────────────────────────────────────────────────── */
 
 /* A transparent hit area straddling the pane's edge. */

package/src/components/shell.tsx

@@ -23,7 +23,7 @@
 import * as React from 'react';
 import classNames from 'classnames';
 import { Slot } from 'radix-ui';
-import { useComposedRefs } from 'radix-ui/internal';
+import { useComposedRefs, useLayoutEffect } from 'radix-ui/internal';
 import { PaneResizeContext } from './_internal/shell-resize.js';
 import { PaneHandle, PanelHandle } from './_internal/shell-handles.js';
 import { Sidebar } from './_internal/shell-sidebar.js';
@@ -52,7 +52,8 @@ import { useShell, useSidebarMode } from './shell.context.js';
 import { useResponsivePresentation } from './shell.hooks.js';
 import { readBreakpoint } from '../hooks/use-breakpoint.js';
 import { useThemeSize } from '../hooks/theme-size.js';
-import { PaneChromeScope, PaneFooter, PaneHeader, Scroll, ShellContentContext, ShellSizeContext } from './_internal/pane-chrome.js';
+import { PaneChromeScope, PaneFooter, PaneHeader, Scroll, ShellContentContext, ShellSizeContext, ShellWindowContext } from './_internal/pane-chrome.js';
+import { onPageScrollMediaChange, pageScrollMatches } from './_internal/shell-page-scroll.js';
 import type { PaneSize, PaneHeaderProps, PaneFooterProps, ScrollProps } from './_internal/pane-chrome.js';
 import { PaneBandSizeContext } from './_internal/pane-band-context.js';
 import type { Breakpoint, CSSPropertiesWithVars, PaneBaseProps, PaneMode, PaneName, PaneTarget, ResponsivePresentation, SidebarMode } from './shell.types.js';
@@ -61,7 +62,18 @@ import type { Breakpoint, CSSPropertiesWithVars, PaneBaseProps, PaneMode, PaneNa
 
 export interface ShellRootProps extends React.ComponentPropsWithoutRef<'div'> {
   children: React.ReactNode;
+  /**
+   * The Shell's height. `full` (the default) is the window's height; on a narrow touch screen the
+   * page scrolls instead of the content, so the browser can hide its toolbars. `auto` grows with
+   * the content. Any other value is the Shell's own height, and makes it contained.
+   */
   height?: 'full' | 'auto' | string | number;
+  /**
+   * Makes the Shell fill its parent instead of the window, and always scroll inside itself. Its
+   * overlays cover only its own box and leave the page free to scroll. Use it for a Shell in a
+   * card, a demo or a canvas. An explicit `height` implies it.
+   */
+  contained?: boolean;
   /** The index the panes' chrome takes: `Shell.PaneHeader`, `Shell.Scroll`, `Shell.PaneFooter` and the Sidebar rows in them. Defaults to the nearest Theme's size (3 when the Theme is 4), else `2`. */
   size?: PaneSize;
 }
@@ -105,7 +117,18 @@ type LivePane = { name: PaneName; id: string; el: HTMLElement };
 /** Shell.Root's own range; a Theme size above it maps to 3. */
 const shellSizePropDef = { values: ['1', '2', '3'] as const };
 
-const Root = React.forwardRef<HTMLDivElement, ShellRootProps>(({ className, children, height = 'full', size: sizeProp, style, onKeyDown, onFocus, ...props }, ref) => {
+/** Lets a Shell.Header tell the Root its height, for the rows that stick beneath it while the page scrolls. */
+const ShellHeaderHeightContext = React.createContext<((height: number | undefined) => void) | null>(null);
+
+/** The Shell.Header's default height, which the stylesheet assumes until a Header says otherwise. */
+const DEFAULT_HEADER_HEIGHT = 64;
+
+/** The content's scroller while the frame scrolls: the Shell.Scroll's viewport, or the content itself. */
+function frameScroller(rootEl: HTMLElement): HTMLElement | null {
+  return rootEl.querySelector<HTMLElement>(':scope > .kui-ShellContent > .kui-ShellScroll > .kui-ScrollAreaViewport') ?? rootEl.querySelector<HTMLElement>(':scope > .kui-ShellContent');
+}
+
+const Root = React.forwardRef<HTMLDivElement, ShellRootProps>(({ className, children, height = 'full', contained: containedProp, size: sizeProp, style, onKeyDown, onFocus, ...props }, ref) => {
   // No size of its own: the nearest Theme's, mapped into 1-3.
   const size = useThemeSize(sizeProp, shellSizePropDef);
   const [store] = React.useState(createShellStore);
@@ -148,10 +171,72 @@ const Root = React.forwardRef<HTMLDivElement, ShellRootProps>(({ className, chil
   );
   const liveCount = [...store.entries.values()].filter((entry) => entry.overlayLive && entry.el).length;
 
-  // A Shell given a height of its own sits inside a page, and its overlays
-  // cover only its box: it holds no page lock. `full` is the page, and
-  // `auto` grows with its content, so its overlays are placed on the window.
-  const contained = height !== 'full' && height !== 'auto';
+  // A contained Shell sits inside a page, and its overlays cover only its box:
+  // it holds no page lock. A height of its own implies it. `full` is the
+  // window, and `auto` grows with its content, so its overlays are placed on
+  // the window. Only a `full` Shell lets the page scroll on a phone.
+  const contained = containedProp === true || (height !== 'full' && height !== 'auto');
+  const windowShell = !contained && height === 'full';
+
+  const [headerHeight, setHeaderHeight] = React.useState<number | undefined>(undefined);
+
+  /*
+   * The reading position crosses with the scroller. When a touch window
+   * crosses the narrow boundary (a phone rotating, an iPad entering Split
+   * View), the scroller changes between the content and the page, and the new
+   * one starts at the top. The offset is remembered on `scroll` from whichever
+   * scroller is live, because by the time the change is reported the old one
+   * has already been laid out again and clamped. Only the live scroller is
+   * heard. The clamp itself is reported as a scroll in the same frame as the
+   * resize and before the media change, so scrolls are not heard from a resize
+   * until that frame's animation callbacks.
+   */
+  React.useEffect(() => {
+    if (!windowShell) return;
+    const rootEl = rootRef.current;
+    const win = rootEl?.ownerDocument.defaultView;
+    if (!rootEl || !win || typeof win.matchMedia !== 'function') return;
+    let pageScrolls = pageScrollMatches();
+    let offset = pageScrolls ? win.scrollY : (frameScroller(rootEl)?.scrollTop ?? 0);
+    let frame = 0;
+    let resizing = 0;
+    const onResize = () => {
+      if (resizing) cancelAnimationFrame(resizing);
+      resizing = requestAnimationFrame(() => {
+        resizing = 0;
+      });
+    };
+    const fromPage = () => {
+      if (pageScrolls && !resizing) offset = win.scrollY;
+    };
+    const fromFrame = (event: Event) => {
+      if (!pageScrolls && !resizing && event.target instanceof HTMLElement && event.target === frameScroller(rootEl)) offset = event.target.scrollTop;
+    };
+    win.addEventListener('resize', onResize);
+    win.addEventListener('scroll', fromPage, { passive: true });
+    rootEl.addEventListener('scroll', fromFrame, { passive: true, capture: true });
+    const stop = onPageScrollMediaChange((matches) => {
+      pageScrolls = matches;
+      const carried = offset;
+      if (frame) cancelAnimationFrame(frame);
+      frame = requestAnimationFrame(() => {
+        frame = 0;
+        if (matches) win.scrollTo(0, carried);
+        else {
+          const el = frameScroller(rootEl);
+          if (el) el.scrollTop = carried;
+        }
+      });
+    });
+    return () => {
+      if (frame) cancelAnimationFrame(frame);
+      if (resizing) cancelAnimationFrame(resizing);
+      win.removeEventListener('resize', onResize);
+      win.removeEventListener('scroll', fromPage);
+      rootEl.removeEventListener('scroll', fromFrame, { capture: true });
+      stop();
+    };
+  }, [windowShell]);
 
   /*
    * Containment is the Root's, not the pane's. Only the Root can see every live
@@ -371,6 +456,8 @@ const Root = React.forwardRef<HTMLDivElement, ShellRootProps>(({ className, chil
     <ShellStoreContext.Provider value={store}>
       <ShellSizeContext.Provider value={size}>
       <ShellContentContext.Provider value={false}>
+      <ShellWindowContext.Provider value={windowShell}>
+      <ShellHeaderHeightContext.Provider value={setHeaderHeight}>
       <ShellInsetContext.Provider value={insetContext}>
       {/* A Shell inside a portalled surface's Theme starts with no band, like any other. */}
       <PaneBandSizeContext.Provider value={undefined}>
@@ -381,12 +468,19 @@ const Root = React.forwardRef<HTMLDivElement, ShellRootProps>(({ className, chil
           {...props}
           ref={composedRef}
           className={classNames('kui-ShellRoot', className)}
-          data-height={height === 'auto' ? 'auto' : undefined}
+          data-height={height === 'auto' && !contained ? 'auto' : undefined}
+          data-contained={contained || undefined}
+          data-window={windowShell || undefined}
           data-has-inset={insetPanes.size > 0 || undefined}
           data-overlay-live={liveCount > 0 || undefined}
           onKeyDown={handleKeyDown}
           onFocus={handleFocus}
-          style={{ ...heightStyle, ...(railOffset ? ({ '--shell-rail-offset': railOffset } as CSSPropertiesWithVars) : {}), ...style }}
+          style={{
+            ...heightStyle,
+            ...(railOffset ? ({ '--shell-rail-offset': railOffset } as CSSPropertiesWithVars) : {}),
+            ...(headerHeight !== undefined ? ({ '--kui-shell-header-h': `${headerHeight}px` } as CSSPropertiesWithVars) : {}),
+            ...style,
+          }}
         >
           {children}
           {/* Root-owned and always mounted. The stylesheet shows it while an
@@ -396,6 +490,8 @@ const Root = React.forwardRef<HTMLDivElement, ShellRootProps>(({ className, chil
         </div>
       </PaneBandSizeContext.Provider>
       </ShellInsetContext.Provider>
+      </ShellHeaderHeightContext.Provider>
+      </ShellWindowContext.Provider>
       </ShellContentContext.Provider>
       </ShellSizeContext.Provider>
     </ShellStoreContext.Provider>
@@ -409,19 +505,29 @@ interface ShellHeaderProps extends React.ComponentPropsWithoutRef<'header'> {
   height?: number;
 }
 
-const Header = React.forwardRef<HTMLElement, ShellHeaderProps>(({ className, height = 64, style, ...props }, ref) => (
-  <header
-    {...props}
-    ref={ref}
-    className={classNames('kui-ShellHeader', className)}
-    style={
-      {
-        ...style,
-        '--shell-header-height': `${height}px`,
-      } as CSSPropertiesWithVars
-    }
-  />
-));
+const Header = React.forwardRef<HTMLElement, ShellHeaderProps>(({ className, height = DEFAULT_HEADER_HEIGHT, style, ...props }, ref) => {
+  // Rows that stick beneath the header while the page scrolls need its height. The stylesheet
+  // assumes the default, so only another height is told to the Root.
+  const setHeaderHeight = React.useContext(ShellHeaderHeightContext);
+  useLayoutEffect(() => {
+    if (!setHeaderHeight) return;
+    setHeaderHeight(height === DEFAULT_HEADER_HEIGHT ? undefined : height);
+    return () => setHeaderHeight(undefined);
+  }, [setHeaderHeight, height]);
+  return (
+    <header
+      {...props}
+      ref={ref}
+      className={classNames('kui-ShellHeader', className)}
+      style={
+        {
+          ...style,
+          '--shell-header-height': `${height}px`,
+        } as CSSPropertiesWithVars
+      }
+    />
+  );
+});
 Header.displayName = 'Shell.Header';
 
 /* ── Left (deprecated) ─────────────────────────────────────────────────────── */

package/src/components/spinner.css

@@ -98,8 +98,23 @@
   }
 }
 
+/* A Spinner with children is one tree, loading or not. At rest it steps out of layout. */
+.kui-SpinnerHost:where(:not([data-loading])) {
+  display: contents;
+}
+
+.kui-SpinnerHost:where([data-loading]) {
+  position: relative;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.kui-SpinnerChildren {
+  display: contents;
+}
+
 /* Children of a Spinner keep their space but are not shown while it spins. A class, not an inline style. */
 .kui-SpinnerHiddenChildren {
-  display: contents;
   visibility: hidden;
 }

package/src/components/spinner.tsx

@@ -19,7 +19,8 @@ const Spinner = React.forwardRef<SpinnerElement, SpinnerProps>((props, forwarded
     spinnerPropDefs
   );
 
-  if (!loading) return children;
+  // Without children a Spinner is only the wheel, shown while loading.
+  if (children === undefined && !loading) return null;
 
   // Decorative unless named: a named spinner is a status message, an unnamed one is hidden.
   const named =
@@ -50,22 +51,22 @@ const Spinner = React.forwardRef<SpinnerElement, SpinnerProps>((props, forwarded
 
   if (children === undefined) return spinner;
 
+  // With children, one tree whether loading or not, so starting or stopping never remounts them
+  // (their state, focus and refs survive). At rest the host is `display: contents`; while loading
+  // it centres the wheel over the children, which keep their space but are hidden.
   return (
-    <Flex asChild position="relative" align="center" justify="center">
-      <span aria-busy="true">
-        {/**
-         * `display: contents` removes the content from the accessibility tree in some browsers,
-         * so we force remove it with `aria-hidden`
-         */}
-        <span aria-hidden className="kui-SpinnerHiddenChildren">
-          {children}
-        </span>
-
+    <span className="kui-SpinnerHost" data-loading={loading || undefined} aria-busy={loading || undefined}>
+      {/* `display: contents` removes the content from the accessibility tree in some browsers, so
+          while loading it is removed with `aria-hidden` too. */}
+      <span aria-hidden={loading || undefined} className={classNames('kui-SpinnerChildren', loading && 'kui-SpinnerHiddenChildren')}>
+        {children}
+      </span>
+      {loading ? (
         <Flex asChild align="center" justify="center" position="absolute" inset="0">
           <span>{spinner}</span>
         </Flex>
-      </span>
-    </Flex>
+      ) : null}
+    </span>
   );
 });
 Spinner.displayName = 'Spinner';

package/src/components/text-area.css

@@ -464,8 +464,13 @@
  *                                                                                                 *
  ***************************************************************************************************/
 
-/* With an error message, one box holds the field and the message below it. */
-.kui-TextAreaWrapper {
+/* With an error message, one box holds the field and the message below it. Without one the
+   wrapper steps out of layout, and the field is the box. */
+.kui-TextAreaWrapper:where(:not([data-message])) {
+  display: contents;
+}
+
+.kui-TextAreaWrapper:where([data-message]) {
   display: flex;
   flex-direction: column;
   min-width: 0;