@oxy.so/bloom 2.10.0 → 2.12.0

package/lib/module/app-shell/AppShell.js

@@ -1,47 +1,65 @@
 "use strict";
 
-import React, { memo, useEffect, useMemo } from 'react';
-import { Platform, Pressable, ScrollView, View, useWindowDimensions } from 'react-native';
+import React, { memo, useEffect, useMemo, useRef, useState } from 'react';
+import { Platform, Pressable, ScrollView, View } from 'react-native';
 import Animated, { Easing, useAnimatedStyle, useReducedMotion, useSharedValue, withTiming } from 'react-native-reanimated';
 import { resolveButtonRamps, mixColor } from "../button/shared.js";
+import { ContentPanel } from '../content-panel';
 import { useControllableState } from "../hooks/use-controllable-state.js";
 import { Backdrop, OverlayRoot } from "../overlay/index.js";
 import { Portal } from '../portal';
 import { Sidebar } from "../sidebar/index.js";
 import { BREAKPOINTS } from "../styles/breakpoints.js";
-import { WEB_OVERFLOW_CLIP, WEB_POSITION_FIXED, WEB_POSITION_STICKY, WEB_VIEWPORT_HEIGHT, webViewportHeightMinus } from "../styles/web-view-style.js";
+import { WEB_OVERFLOW_CLIP, WEB_POSITION_FIXED } from "../styles/web-view-style.js";
 import { useTheme } from "../theme/use-theme.js";
+import { AppShellBottomBar, AppShellFloatingAction, AppShellTopBar, useShellInsets } from "./AppShellBars.js";
 import { AppShellHeader } from "./AppShellHeader.js";
+import { AppShellSplitPanes } from "./AppShellSplit.js";
+import { APP_SHELL_DEFAULTS as D, breakpointPx } from "./constants.js";
 import { AppShellProvider } from "./context.js";
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { resolveScrollMode, rootFrame, stickyRail } from "./layout.js";
+import { useShellWidth } from "./use-shell-width.js";
+
 /**
- * The page frame: a starter shell and a dashboard shell, combined into one
- * component.
+ * The page frame — one engine, four shapes (`variant`).
  *
  *   root       row, background-full; one screen tall at least (document
- *              scroll), exactly (`fixed`), or its parent's height (`container`)
- *   lg and up  the sidebar in flow (from `sm` for `variant: 'rail'`, whose
- *              drawer below `sm` opens the panel); `overlay` pads the whole frame 12 with a
- *              16 gap, `reveal` sits the rail 12 from the top-left
- *   main       scrolls — on web the DOCUMENT (see `scroll`), elsewhere its own
- *              ScrollView; the content column is centred, max 1300, gap 10:
- *              header (breadcrumb + title row), then the content (gap 16,
- *              16 below). `overlay` insets the column 12 from the top at `sm`,
- *              `reveal` pads the page 12 (24 on top at `sm`)
+ *              scroll), exactly (`fixed`), or its parent's height (`container`).
+ *              It MEASURES ITSELF (`useShellWidth`) and every breakpoint below
+ *              is read off that width, not off the window, so a shell embedded
+ *              in a preview pane lays out for the pane.
+ *   nav        the sidebar in flow from `navFrom` (`lg` for the panel, `sm` for
+ *              a rail, `sm` whenever `navExpandedFrom` swaps the two); below it
+ *              the same props drive the drawer. `overlay` pads the whole frame
+ *              by `gutter`, `reveal` sits the rail 12 from the top-left
+ *   page       `dashboard` one fluid column capped at `contentMaxWidth`;
+ *              `feed`/`focus` a `contentWidth` reading column centred in what
+ *              the nav leaves; `split` a column of header over three panes
  *   aside      optional right column, `asideWidth` (320) wide from `asideFrom`
  *              (xl), pinned like the rail; below it stacked after the content
- *   below lg   the header grows a hamburger (also with no title — see
- *              `useAppShell` / `AppShellMenuButton`). `overlay` opens the rail as a
- *              drawer (12 inset) over a 40% black backdrop; `reveal` slides
- *              the page 272 right and rounds it to 32 while the rail, flat
- *              beneath it, scales up from 0.94 and fades in (325ms,
+ *   slots      `topBar` above the columns, `bottomBar` pinned to the bottom
+ *              with the safe-area inset, `floatingAction` above that bar —
+ *              each measured, so the content reserves exactly their height
+ *   below nav  the header grows a hamburger (also with no title — see
+ *              `useAppShell` / `AppShellMenuButton`). `overlay` opens the rail
+ *              as a drawer (12 inset) over a 40% black backdrop; `reveal`
+ *              slides the page 272 right and rounds it to 32 while the rail,
+ *              flat beneath it, scales up from 0.94 and fades in (325ms,
  *              cubic-bezier(0.42, 0, 0.58, 1)); pressing the page (a 10% black
  *              / 5% white veil) closes it
+ *
+ * WHY THERE ARE NO TRICKS IN HERE, and none left for a consumer: every region
+ * is a flex child of one row, sized by `flexBasis`/`maxWidth` and shrinkable, so
+ * nothing is positioned by hand and nothing can overflow the frame. The only
+ * `position` values in the family are the sticky nav/aside and the bar slots'
+ * own anchor — all inside the shell. No negative margin, no `100vw`, no
+ * window-width hook, anywhere.
  */
-
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 const REVEAL_EASE = Easing.bezier(0.42, 0, 0.58, 1);
 const REVEAL_MS = 325;
 const REVEAL_OFFSET = 272;
+
 /**
  * The page's scroller. `document`: a plain box, the page grows the document.
  * `fixed`: a plain box that fills the frame's height and never scrolls — the
@@ -51,14 +69,17 @@ function Scroller({
   mode,
   style,
   contentStyle,
+  testID,
   children
 }) {
   if (mode === 'document') return /*#__PURE__*/_jsx(View, {
+    testID: testID,
     style: [style, contentStyle],
     children: children
   });
   if (mode === 'fixed') {
     return /*#__PURE__*/_jsx(View, {
+      testID: testID,
       style: [{
         flex: 1,
         minHeight: 0
@@ -67,6 +88,7 @@ function Scroller({
     });
   }
   return /*#__PURE__*/_jsx(ScrollView, {
+    testID: testID,
     style: [{
       flex: 1
     }, style],
@@ -75,6 +97,7 @@ function Scroller({
   });
 }
 const AppShellComponent = ({
+  variant = 'dashboard',
   sidebar,
   drawer = 'overlay',
   title,
@@ -82,11 +105,36 @@ const AppShellComponent = ({
   actions,
   header,
   aside,
-  asideWidth = 320,
-  asideFrom = 'xl',
+  asideWidth = D.asideWidth,
+  asideFrom = D.asideFrom,
   asideCollapse = 'stack',
   children,
-  contentMaxWidth = 1300,
+  contentMaxWidth = D.contentMaxWidth,
+  contentWidth = D.contentWidth,
+  gutter: gutterProp,
+  navFrom,
+  navExpandedFrom,
+  panel = false,
+  framedFrom,
+  list,
+  info,
+  pane = 'list',
+  listWidth = D.listWidth,
+  listMinWidth = D.listMinWidth,
+  listMaxWidth = D.listMaxWidth,
+  onListWidthChange,
+  infoWidth = D.infoWidth,
+  splitFrom = D.splitFrom,
+  infoFrom = D.infoFrom,
+  resizable = true,
+  resizeLabel = 'Resize panes',
+  paneScroll = true,
+  topBar,
+  topBarVisibility = 'compact',
+  bottomBar,
+  bottomBarVisibility = 'compact',
+  floatingAction,
+  floatingActionPlacement = 'end',
   overlay,
   drawerOpen,
   onDrawerOpenChange,
@@ -96,30 +144,63 @@ const AppShellComponent = ({
 }) => {
   const theme = useTheme();
   const {
-    width
-  } = useWindowDimensions();
-  // Native has no document: `document` falls back to `container` there.
-  const mode = scroll === 'document' && Platform.OS !== 'web' ? 'container' : scroll;
+    width,
+    onLayout
+  } = useShellWidth();
+  const insets = useShellInsets();
+  const mode = resolveScrollMode(variant, scroll);
   const doc = mode === 'document';
   const fixed = mode === 'fixed';
   const small = width >= BREAKPOINTS.sm;
-  // The rail is narrow enough to stay in flow from `sm`; the panel needs `lg`.
-  const rail = sidebar?.variant === 'rail';
-  const wide = rail ? small : width >= BREAKPOINTS.lg;
-  const asideBeside = aside != null && width >= BREAKPOINTS[asideFrom];
-  const asideStacked = aside != null && !asideBeside && asideCollapse === 'stack';
+
+  // `dashboard` keeps the 12/16 pair it shipped with; one number drives both
+  // for every other shape.
+  const gutter = gutterProp ?? (variant === 'dashboard' ? D.dashboardGutter : D.gutter);
+  const columnGap = variant === 'dashboard' ? D.dashboardColumnGap : gutter;
+
+  // The nav: `navExpandedFrom` decides which sidebar variant is drawn, and the
+  // variant decides how early it can sit in flow (a rail is narrow enough at
+  // `sm`; the panel needs `lg`). `navFrom` overrides the tier outright.
+  const navVariant = navExpandedFrom ? width >= breakpointPx(navExpandedFrom) ? 'panel' : 'rail' : sidebar?.variant;
+  const navTier = navFrom ?? (navExpandedFrom || navVariant === 'rail' ? 'sm' : 'lg');
+  const wide = width >= breakpointPx(navTier);
+  // `focus` is the one shape with no navigation at all.
+  const hasNav = variant !== 'focus' && sidebar != null;
+  const navInFlow = hasNav && wide;
+  const flowSidebar = sidebar ? {
+    ...sidebar,
+    variant: navVariant
+  } : undefined;
   // The drawer always opens the full panel, whatever the in-flow variant.
   const drawerSidebar = sidebar ? {
     ...sidebar,
     variant: 'panel'
   } : undefined;
+
+  /**
+   * `reveal` slides the WHOLE PAGE 272px sideways to uncover the rail, which is
+   * a statement about a page that is one column. A centred reading column would
+   * slide out of its own centring, and a split's panes would each leave their
+   * divider behind — so the other three shapes always get the overlay drawer.
+   */
+  const drawerStyle = variant === 'dashboard' ? drawer : 'overlay';
+  const centred = variant === 'feed' || variant === 'focus';
+  const canvas = variant === 'canvas';
+  // `focus` is a single column by definition and `split` has its `info` pane
+  // instead, so neither takes an aside in EITHER position — beside or stacked.
+  const hasAside = aside != null && variant !== 'focus' && variant !== 'split';
+  const asideBeside = hasAside && width >= breakpointPx(asideFrom);
+  // A canvas has no scrolling column to stack an aside into — the screen IS the
+  // canvas — so below `asideFrom` the aside is dropped whatever `asideCollapse`
+  // says, rather than being rendered where nothing can reach it.
+  const asideStacked = hasAside && !asideBeside && asideCollapse === 'stack' && !canvas;
   const reducedMotion = useReducedMotion();
   const [open, setOpen] = useControllableState({
     value: drawerOpen,
     defaultValue: false,
     onChange: onDrawerOpenChange
   });
-  const drawerAvailable = !!sidebar && !wide;
+  const drawerAvailable = hasNav && !wide;
   const isOpen = open && drawerAvailable;
   const shell = useMemo(() => ({
     drawerAvailable,
@@ -128,44 +209,94 @@ const AppShellComponent = ({
     closeDrawer: () => setOpen(false),
     toggleDrawer: () => setOpen(!isOpen)
   }), [drawerAvailable, isOpen, setOpen]);
+
+  /**
+   * Closing the drawer hands focus back to whatever opened it.
+   *
+   * The drawer is a PORTAL, so when it closes the focused node leaves the
+   * document and the browser drops focus to `<body>` — a keyboard user is
+   * returned to the top of the page, and a screen reader announces nothing.
+   * Remembering `activeElement` at open time is what makes "Escape" land back
+   * on the hamburger. It reads the opener rather than a ref to Bloom's own
+   * button so a page that opens the drawer from its own control
+   * (`useAppShell().openDrawer`) gets the same behaviour.
+   *
+   * WEB ONLY, and the native gap is recorded rather than faked: the equivalent
+   * there is `useRestoreAccessibilityFocus`, which needs a ref to the trigger,
+   * and `Button` forwards none. See `docs/app-shell.mdx`.
+   */
+  const opener = useRef(null);
+  useEffect(() => {
+    if (Platform.OS !== 'web' || typeof document === 'undefined') return;
+    if (isOpen) {
+      opener.current = document.activeElement;
+      return;
+    }
+    const previous = opener.current;
+    opener.current = null;
+    if (previous && typeof previous.focus === 'function' && document.contains(previous)) previous.focus();
+  }, [isOpen]);
   const {
     neutral: n
   } = resolveButtonRamps(theme);
   const background = theme.isDark ? mixColor(n[900], n[950], 0.4) : theme.colors.card;
-  const reveal = useSharedValue(isOpen ? 1 : 0);
-  useEffect(() => {
-    const target = isOpen && drawer === 'reveal' ? 1 : 0;
-    reveal.value = reducedMotion ? target : withTiming(target, {
-      duration: REVEAL_MS,
-      easing: REVEAL_EASE
-    });
-  }, [isOpen, drawer, reducedMotion, reveal]);
-  const railStyle = useAnimatedStyle(() => ({
-    opacity: reveal.value,
-    transform: [{
-      scale: 0.94 + 0.06 * reveal.value
-    }]
-  }), [reveal]);
-  const pageStyle = useAnimatedStyle(() => ({
-    transform: [{
-      translateX: REVEAL_OFFSET * reveal.value
-    }],
-    borderRadius: 32 * reveal.value
-  }), [reveal]);
-  const veilStyle = useAnimatedStyle(() => ({
-    opacity: reveal.value
-  }), [reveal]);
+
+  // ---- pinned slots -------------------------------------------------------
+  // `compact` is the phone case the slot exists for: the bar appears exactly
+  // where the nav became a drawer.
+  const barActive = visibility => visibility === 'always' || !navInFlow;
+  const showTopBar = topBar != null && barActive(topBarVisibility);
+  const showBottomBar = bottomBar != null && barActive(bottomBarVisibility);
+  const showFloatingAction = floatingAction != null;
+  const [bottomBarHeight, setBottomBarHeight] = useState(0);
+  const [floatingActionHeight, setFloatingActionHeight] = useState(0);
+  // Both slots are MEASURED rather than assumed: a bar's height is its
+  // content's, and a guess is what leaves the last row of a feed under it.
+  const bottomEdge = showBottomBar ? bottomBarHeight : insets.bottom;
+  const contentReserve = showBottomBar || showFloatingAction ? bottomEdge + (showFloatingAction ? floatingActionHeight + gutter : 0) : 0;
+  const bars = /*#__PURE__*/_jsxs(_Fragment, {
+    children: [showBottomBar ? /*#__PURE__*/_jsx(AppShellBottomBar, {
+      doc: doc,
+      onHeightChange: setBottomBarHeight,
+      testID: testID ? `${testID}-bottom-bar` : undefined,
+      children: bottomBar
+    }) : null, showFloatingAction ? /*#__PURE__*/_jsx(AppShellFloatingAction, {
+      doc: doc,
+      offset: bottomEdge + gutter,
+      gutter: gutter,
+      placement: floatingActionPlacement,
+      onHeightChange: setFloatingActionHeight,
+      testID: testID ? `${testID}-floating-action` : undefined,
+      children: floatingAction
+    }) : null]
+  });
+  const topBarNode = showTopBar ? /*#__PURE__*/_jsx(AppShellTopBar, {
+    doc: doc,
+    testID: testID ? `${testID}-top-bar` : undefined,
+    children: topBar
+  }) : null;
 
   // The default header renders whenever it has something to show — a menu
   // button alone counts, so a page without a title can still open the drawer.
-  const headerNode = header ?? (title != null || breadcrumb != null || actions != null || drawerAvailable ? /*#__PURE__*/_jsx(AppShellHeader, {
+  //
+  // Unless there is a `topBar`: that bar is where a phone's navigation control
+  // belongs, so the header does not add a SECOND hamburger under it. (Put an
+  // `AppShellMenuButton` in the bar; it renders itself only when there is a
+  // drawer to open.)
+  const menuInHeader = drawerAvailable && !showTopBar;
+  // `header={null}` is an ANSWER, not an absence: the page says it wants no
+  // header at all (it draws its own bar, or its own nav control). `??` would
+  // have taken `null` as "nothing given" and drawn the default one under the
+  // page's own — which is how a second hamburger appeared on a phone.
+  const headerNode = header !== undefined ? header : title != null || breadcrumb != null || actions != null || menuInHeader ? /*#__PURE__*/_jsx(AppShellHeader, {
     title: title,
     breadcrumb: breadcrumb,
     actions: actions,
     menuOpen: isOpen,
-    onMenuPress: drawerAvailable ? shell.toggleDrawer : undefined,
+    showMenu: menuInHeader,
+    onMenuPress: menuInHeader ? shell.toggleDrawer : undefined,
     testID: testID ? `${testID}-header` : undefined
-  }) : null);
+  }) : null;
   const fill = fixed ? {
     flex: 1,
     minHeight: 0
@@ -198,7 +329,7 @@ const AppShellComponent = ({
       width: asideWidth,
       flexShrink: 0
     }, doc ? {
-      ...stickyRail(12),
+      ...stickyRail(gutter),
       width: asideWidth
     } : {
       alignSelf: 'stretch'
@@ -214,29 +345,57 @@ const AppShellComponent = ({
       children: aside
     })
   }) : null;
-  const frame = doc ? documentRoot : fixed ? fixedRoot : containerRoot;
-  if (drawer === 'reveal') {
+  const frame = rootFrame(mode);
+
+  // ---- the reveal drawer (dashboard's whole-page slide) -------------------
+  const reveal = useSharedValue(isOpen ? 1 : 0);
+  useEffect(() => {
+    const target = isOpen && drawerStyle === 'reveal' ? 1 : 0;
+    reveal.value = reducedMotion ? target : withTiming(target, {
+      duration: REVEAL_MS,
+      easing: REVEAL_EASE
+    });
+  }, [isOpen, drawerStyle, reducedMotion, reveal]);
+  const railStyle = useAnimatedStyle(() => ({
+    opacity: reveal.value,
+    transform: [{
+      scale: 0.94 + 0.06 * reveal.value
+    }]
+  }), [reveal]);
+  const pageStyle = useAnimatedStyle(() => ({
+    transform: [{
+      translateX: REVEAL_OFFSET * reveal.value
+    }],
+    borderRadius: 32 * reveal.value
+  }), [reveal]);
+  const veilStyle = useAnimatedStyle(() => ({
+    opacity: reveal.value
+  }), [reveal]);
+  if (drawerStyle === 'reveal') {
     return /*#__PURE__*/_jsx(AppShellProvider, {
       value: shell,
       children: /*#__PURE__*/_jsxs(View, {
         testID: testID,
+        onLayout: onLayout,
         style: [frame, doc ? {
           overflow: WEB_OVERFLOW_CLIP
         } : null, {
           flexDirection: 'row',
           backgroundColor: background
         }, style],
-        children: [sidebar && wide ? /*#__PURE__*/_jsx(View, {
-          style: [{
+        children: [navInFlow && flowSidebar ? /*#__PURE__*/_jsx(View, {
+          style: [flowSidebar.surface === 'docked' ? {
+            flexShrink: 0
+          } : {
             paddingTop: 12,
             paddingBottom: 12,
             paddingLeft: 12,
             flexShrink: 0
           }, doc ? stickyRail(0) : null],
           children: /*#__PURE__*/_jsx(Sidebar, {
-            ...sidebar
+            ...flowSidebar
           })
-        }) : null, sidebar && !wide ? /*#__PURE__*/_jsx(View, {
+        }) : null, drawerAvailable && drawerSidebar ? /*#__PURE__*/_jsx(View, {
           "aria-hidden": !isOpen,
           pointerEvents: isOpen ? 'auto' : 'none'
           // Fixed on web in document mode: the rail waits beneath the VIEWPORT,
@@ -261,7 +420,7 @@ const AppShellComponent = ({
             children: /*#__PURE__*/_jsx(Sidebar, {
               ...drawerSidebar,
               mobile: true,
-              flat: true,
+              surface: "plain",
               onClose: () => setOpen(false)
             })
           })
@@ -275,14 +434,25 @@ const AppShellComponent = ({
           }, wide ? null : pageStyle],
           children: [/*#__PURE__*/_jsx(Scroller, {
             mode: mode,
+            testID: testID ? `${testID}-page` : undefined,
             style: {
               flex: doc ? undefined : 1,
               flexGrow: 1,
               flexShrink: 1,
               flexBasis: 0,
               minWidth: 0
-            },
-            contentStyle: {
+            }
+            // `padding: 12` is a SHORTHAND, and react-native-web ranks its CSS
+            // shorthand against `padding-bottom` by sheet order rather than by
+            // the array's — so the reserve is spelled in longhands instead of
+            // layered over the shorthand, and only when there is one.
+            ,
+            contentStyle: contentReserve ? {
+              paddingLeft: 12,
+              paddingRight: 12,
+              paddingTop: small ? 24 : 12,
+              paddingBottom: 12 + contentReserve
+            } : {
               padding: 12,
               paddingTop: small ? 24 : 12
             },
@@ -312,118 +482,347 @@ const AppShellComponent = ({
               testID: testID ? `${testID}-veil` : undefined
             })
           }) : null]
-        }), overlay]
+        }), overlay, bars]
       })
     });
   }
-  return /*#__PURE__*/_jsx(AppShellProvider, {
-    value: shell,
-    children: /*#__PURE__*/_jsxs(View, {
-      testID: testID,
-      style: [frame, {
-        flexDirection: 'row',
-        gap: 16,
-        padding: 12,
-        backgroundColor: background
-      }, style],
-      children: [sidebar && wide ? doc ? /*#__PURE__*/_jsx(View, {
-        style: stickyRail(12),
-        children: /*#__PURE__*/_jsx(Sidebar, {
-          ...sidebar
-        })
-      }) : /*#__PURE__*/_jsx(Sidebar, {
-        ...sidebar
-      }) : null, sidebar && isOpen ? /*#__PURE__*/_jsx(Portal, {
-        children: /*#__PURE__*/_jsxs(OverlayRoot, {
-          children: [/*#__PURE__*/_jsx(Backdrop, {
-            onPress: () => setOpen(false),
-            blurIntensity: 0,
-            dimOpacity: 0.4,
-            accessibilityLabel: "Close navigation"
-          }), /*#__PURE__*/_jsx(View, {
-            pointerEvents: "box-none",
+
+  // A `panel` only FILLS when the shell was ASKED to bound it — `fixed` or
+  // `container`. With document scroll the page itself is the scroller and there
+  // is no height to fill, so the panel keeps growing with its content (and the
+  // frame is its own box, which is what stops it drifting under scroll).
+  //
+  // The test is the PROP, not the resolved mode: native resolves `document` to
+  // `container` because it has no document, and a page that asked for document
+  // scroll still wants its header to travel with the content there.
+  const panelFills = panel === true && scroll !== 'document' && mode !== 'document';
+
+  // ---- the page region, per variant ---------------------------------------
+  /** `feed` / `focus`: a fixed reading column, centred in what the nav leaves. */
+  const centredBody = /*#__PURE__*/_jsxs(View, {
+    style: [{
+      flexGrow: 1,
+      flexShrink: 1,
+      flexBasis: 0,
+      minWidth: 0,
+      flexDirection: 'row',
+      justifyContent: 'center',
+      gap: columnGap,
+      // Document scroll: each column carries its own height (the centre
+      // grows the page, the aside is sticky). Bounded: they stretch.
+      alignItems: doc ? 'flex-start' : 'stretch'
+    }, fill],
+    children: [/*#__PURE__*/_jsx(View, {
+      testID: testID ? `${testID}-content` : undefined,
+      style: [
+      // `flexBasis` is the reading width and `flexShrink: 1` is what keeps a
+      // 600px column inside a 360px phone — a `width` would overflow.
+      {
+        flexGrow: 0,
+        flexShrink: 1,
+        flexBasis: contentWidth,
+        maxWidth: contentWidth,
+        minWidth: 0
+      }, doc ? null : {
+        alignSelf: 'stretch'
+      }],
+      children: panelFills ?
+      /*#__PURE__*/
+      // A panel in a BOUNDED shell is the height of the screen and scrolls
+      // its own content: that is what makes it read as a panel — it reaches
+      // the bottom and closes there, like the rail beside it — instead of
+      // an open-ended column whose bottom edge is somewhere past the fold.
+      // The header is pinned inside it and only the routed content moves.
+      _jsx(ContentPanel, {
+        framedFrom: framedFrom,
+        fill: true
+        // The panel's box already IS the visible area here, so the frame is
+        // that box — no viewport maths, nothing to line up.
+        ,
+        overlaySizing: "panel",
+        surfaceStyle: {
+          flexGrow: 1,
+          flexShrink: 1,
+          flexBasis: 'auto',
+          minHeight: 0
+        },
+        contentStyle: {
+          flexGrow: 1,
+          flexShrink: 1,
+          flexBasis: 'auto',
+          minHeight: 0
+        },
+        children: /*#__PURE__*/_jsxs(View, {
+          style: {
+            flex: 1,
+            minHeight: 0,
+            padding: gutter,
+            gap: 16
+          },
+          children: [headerNode, /*#__PURE__*/_jsx(ScrollView, {
+            testID: testID ? `${testID}-page` : undefined,
             style: {
-              position: 'absolute',
-              top: 0,
-              bottom: 0,
-              left: 0,
-              flexDirection: 'row',
-              padding: 12
+              flex: 1,
+              minHeight: 0
             },
-            children: /*#__PURE__*/_jsx(View, {
-              pointerEvents: "auto",
-              style: {
-                height: '100%'
-              },
-              children: /*#__PURE__*/_jsx(Sidebar, {
-                ...drawerSidebar,
-                mobile: true,
-                onClose: () => setOpen(false)
-              })
-            })
+            contentContainerStyle: {
+              gap: 16,
+              paddingBottom: contentReserve
+            },
+            children: children
           })]
         })
-      }) : null, /*#__PURE__*/_jsx(Scroller, {
+      }) : /*#__PURE__*/_jsxs(Scroller, {
         mode: mode,
-        style: {
-          flex: 1,
-          minWidth: 0,
-          backgroundColor: background
-        },
+        testID: testID ? `${testID}-page` : undefined,
+        style: {},
         contentStyle: {
-          paddingTop: small ? 12 : 0
+          paddingBottom: contentReserve
         },
-        children: column
-      }), asideColumn({}), overlay]
-    })
+        children: [panel ? /*#__PURE__*/_jsx(ContentPanel, {
+          framedFrom: framedFrom
+          // The sticky frame is pinned at the shell's OWN gutter, which is
+          // exactly where the panel starts. Left at the 8px default it
+          // would sit 8px above the panel's real top edge and snap down on
+          // the first scroll — the panel appearing to breathe.
+          ,
+          overlayInset: gutter
+          // The panel's own `flex-1` (basis 0) would collapse to nothing in
+          // a document-flow column, which has no free space to distribute.
+          ,
+          surfaceStyle: {
+            flexGrow: 1,
+            flexShrink: 1,
+            flexBasis: 'auto'
+          },
+          contentStyle: {
+            flexGrow: 1,
+            flexShrink: 1,
+            flexBasis: 'auto'
+          },
+          children: /*#__PURE__*/_jsxs(View, {
+            style: [{
+              gap: 16,
+              padding: gutter
+            }, fill],
+            children: [headerNode, children]
+          })
+        }) : /*#__PURE__*/_jsxs(View, {
+          style: [{
+            gap: 16
+          }, fill],
+          children: [headerNode, children]
+        }), asideStacked ? /*#__PURE__*/_jsx(View, {
+          testID: testID ? `${testID}-aside` : undefined,
+          children: aside
+        }) : null]
+      })
+    }), asideColumn({})]
+  });
+  const splitWide = width >= breakpointPx(splitFrom);
+  // Below the breakpoint exactly one pane renders — the one `pane` names, or
+  // the detail pane when that one was never given any content.
+  const solePane = pane === 'list' && list == null || pane === 'info' && info == null ? 'detail' : pane;
+  const splitBody = /*#__PURE__*/_jsxs(View, {
+    style: {
+      flexGrow: 1,
+      flexShrink: 1,
+      flexBasis: 0,
+      minWidth: 0,
+      minHeight: 0
+    },
+    children: [headerNode ? /*#__PURE__*/_jsx(View, {
+      style: {
+        paddingBottom: gutter
+      },
+      children: headerNode
+    }) : null, /*#__PURE__*/_jsx(View, {
+      style: {
+        flexGrow: 1,
+        flexShrink: 1,
+        minHeight: 0,
+        borderRadius: 16,
+        borderWidth: 1,
+        borderColor: theme.colors.border,
+        backgroundColor: theme.colors.card,
+        overflow: 'hidden'
+      },
+      children: /*#__PURE__*/_jsx(AppShellSplitPanes, {
+        list: list,
+        detail: children,
+        info: info,
+        showList: splitWide ? list != null : solePane === 'list',
+        showDetail: splitWide ? true : solePane === 'detail',
+        showInfo: splitWide ? info != null && width >= breakpointPx(infoFrom) : solePane === 'info',
+        listWidth: listWidth,
+        listMinWidth: listMinWidth,
+        listMaxWidth: listMaxWidth,
+        onListWidthChange: onListWidthChange,
+        infoWidth: infoWidth,
+        resizable: resizable,
+        paneScroll: paneScroll,
+        resizeLabel: resizeLabel,
+        testID: testID
+      })
+    })]
+  });
+  const dashboardBody = /*#__PURE__*/_jsxs(_Fragment, {
+    children: [/*#__PURE__*/_jsx(Scroller, {
+      mode: mode,
+      testID: testID ? `${testID}-page` : undefined,
+      style: {
+        flex: 1,
+        minWidth: 0,
+        backgroundColor: background
+      },
+      contentStyle: {
+        paddingTop: small ? 12 : 0,
+        paddingBottom: contentReserve
+      },
+      children: column
+    }), asideColumn({})]
   });
-};
 
-/**
- * Document mode: the frame is at least one viewport tall and grows with the
- * page, so the browser scrolls the document (scroll restoration, the address
- * bar collapsing, anchor links, `window.scrollTo`) exactly as it does for a
- * `ContentPanel` page. Nothing here may be a scroll container — no `hidden`
- * overflow — or the sticky rail would stick to a box that never scrolls.
- */
-const documentRoot = {
-  flexGrow: 1,
-  minHeight: WEB_VIEWPORT_HEIGHT
-};
-// (Under `reveal` the document root also takes `overflow: clip`: the page slides
-// 272 right, and `clip` keeps that from widening the document with a horizontal
-// scrollbar without becoming a scroll container.)
+  /**
+   * `canvas`: the content IS the screen. One area, edge to edge — no reading
+   * column, no max width, no padding — with the header (if any) above it in
+   * flow, because a toolbar over a map belongs to the map. The `topBar`,
+   * `bottomBar`, `floatingAction` and `overlay` slots float over it as they do
+   * everywhere else, which is how a canvas gets its chrome without the canvas
+   * giving up its area.
+   *
+   * The shell's own padding moves OUT of the row and onto the regions here
+   * (below), so the nav is still a card with a gutter around it while the
+   * canvas runs to the window's edge. No negative margins: each region states
+   * its own inset.
+   */
+  const canvasBody = /*#__PURE__*/_jsxs(_Fragment, {
+    children: [/*#__PURE__*/_jsxs(View, {
+      testID: testID ? `${testID}-page` : undefined,
+      style: {
+        flex: 1,
+        minWidth: 0,
+        minHeight: 0,
+        backgroundColor: background
+      },
+      children: [headerNode, /*#__PURE__*/_jsx(View, {
+        style: {
+          flex: 1,
+          minHeight: 0,
+          minWidth: 0
+        },
+        children: children
+      })]
+    }), asideColumn(canvas ? {
+      padding: gutter,
+      paddingLeft: 0
+    } : {})]
+  });
+  const body = variant === 'split' ? splitBody : canvas ? canvasBody : centred ? centredBody : dashboardBody;
 
-/** Container mode: fill the parent, scroll inside. */
-const containerRoot = {
-  flex: 1,
-  height: '100%',
-  overflow: 'hidden'
-};
+  // A DOCKED nav is flush to the window: it takes the shell's whole height and
+  // its own hairline is the separator, so the shell gives up its left and
+  // vertical padding around that column rather than framing it like a card.
+  const dockedNav = navInFlow && flowSidebar?.surface === 'docked';
+  const navRegion = navInFlow && flowSidebar ? doc ? /*#__PURE__*/_jsx(View, {
+    style: stickyRail(dockedNav ? 0 : gutter),
+    children: /*#__PURE__*/_jsx(Sidebar, {
+      ...flowSidebar
+    })
+  }) : canvas && !dockedNav ?
+  /*#__PURE__*/
+  // The canvas row has no padding of its own, so the nav states its.
+  _jsx(View, {
+    style: {
+      padding: gutter,
+      paddingRight: 0,
+      flexShrink: 0
+    },
+    children: /*#__PURE__*/_jsx(Sidebar, {
+      ...flowSidebar
+    })
+  }) : /*#__PURE__*/_jsx(Sidebar, {
+    ...flowSidebar
+  }) : null;
+  const drawerRegion = drawerAvailable && isOpen && drawerSidebar ? /*#__PURE__*/_jsx(Portal, {
+    children: /*#__PURE__*/_jsxs(OverlayRoot, {
+      children: [/*#__PURE__*/_jsx(Backdrop, {
+        onPress: () => setOpen(false),
+        blurIntensity: 0,
+        dimOpacity: 0.4,
+        accessibilityLabel: "Close navigation"
+      }), /*#__PURE__*/_jsx(View, {
+        pointerEvents: "box-none",
+        style: {
+          position: 'absolute',
+          top: 0,
+          bottom: 0,
+          left: 0,
+          flexDirection: 'row',
+          padding: 12
+        },
+        children: /*#__PURE__*/_jsx(View, {
+          pointerEvents: "auto",
+          style: {
+            height: '100%'
+          },
+          children: /*#__PURE__*/_jsx(Sidebar, {
+            ...drawerSidebar,
+            mobile: true,
+            onClose: () => setOpen(false)
+          })
+        })
+      })]
+    })
+  }) : null;
+  const rowStyle = {
+    flexDirection: 'row',
+    gap: dockedNav || canvas ? 0 : columnGap,
+    // A canvas runs to the window's edge, so the row keeps no padding at all
+    // and each region carries its own (the nav below, the aside in `canvasBody`).
+    padding: canvas ? 0 : gutter,
+    ...(dockedNav ? {
+      paddingLeft: 0,
+      paddingTop: 0,
+      paddingBottom: 0
+    } : null),
+    backgroundColor: background
+  };
 
-/**
- * Fixed mode: exactly one screen — `100dvh` on web, the parent on native — and
- * nothing scrolls; the content fills the height left under the header.
- */
-const fixedRoot = Platform.OS === 'web' ? {
-  height: WEB_VIEWPORT_HEIGHT,
-  overflow: 'hidden'
-} : {
-  flex: 1,
-  height: '100%',
-  overflow: 'hidden'
+  // The top bar is a SIBLING above the columns, so it spans the shell edge to
+  // edge without escaping the frame's padding. Without one the root stays the
+  // row it has always been, so nothing about an existing shell moves.
+  if (topBarNode) {
+    return /*#__PURE__*/_jsx(AppShellProvider, {
+      value: shell,
+      children: /*#__PURE__*/_jsxs(View, {
+        testID: testID,
+        onLayout: onLayout,
+        style: [frame, {
+          flexDirection: 'column',
+          backgroundColor: background
+        }, style],
+        children: [topBarNode, /*#__PURE__*/_jsxs(View, {
+          style: [rowStyle, {
+            flexGrow: 1,
+            flexShrink: 1,
+            minHeight: 0
+          }],
+          children: [navRegion, drawerRegion, body]
+        }), overlay, bars]
+      })
+    });
+  }
+  return /*#__PURE__*/_jsx(AppShellProvider, {
+    value: shell,
+    children: /*#__PURE__*/_jsxs(View, {
+      testID: testID,
+      onLayout: onLayout,
+      style: [frame, rowStyle, style],
+      children: [navRegion, drawerRegion, body, overlay, bars]
+    })
+  });
 };
-
-/** The in-flow rail, pinned to the viewport while the document scrolls under it. */
-function stickyRail(inset) {
-  return {
-    position: WEB_POSITION_STICKY,
-    top: inset,
-    height: webViewportHeightMinus(inset * 2),
-    alignSelf: 'flex-start',
-    flexShrink: 0
-  };
-}
 export const AppShell = /*#__PURE__*/memo(AppShellComponent);
 AppShell.displayName = 'AppShell';
 //# sourceMappingURL=AppShell.js.map