@oxy.so/bloom 4.0.0 → 4.2.0

package/src/app-shell/AppShellEngine.tsx

@@ -1,5 +1,7 @@
+import { StyledView } from '../styles/styled-primitives';
+import { SurfaceLevelProvider } from '../styles/surface-levels';
 import React, { memo, useEffect, useMemo, useRef, useState } from 'react';
-import { Platform, Pressable, ScrollView, View } from 'react-native';
+import { Platform, Pressable, ScrollView, View, useWindowDimensions } from 'react-native';
 import Animated, {
   Easing,
   useAnimatedStyle,
@@ -8,13 +10,14 @@ import Animated, {
   withTiming,
 } from 'react-native-reanimated';
 
-import { ContentPanel } from '../content-panel';
+import type { ContentPanelProps } from '../content-panel/types';
+import type { BloomColorScopeProps } from '../theme/color-scope/ColorScope';
 import { useControllableState } from '../hooks/use-controllable-state';
 import { Backdrop, OverlayRoot } from '../overlay';
 import { Portal } from '../portal';
 import { Sidebar } from '../sidebar';
 import { BREAKPOINTS } from '../styles/breakpoints';
-import { WEB_OVERFLOW_CLIP, WEB_POSITION_FIXED, type WebCssStyle } from '../styles/web-view-style';
+import { webViewportHeightMinus, WEB_OVERFLOW_CLIP, WEB_POSITION_FIXED, WEB_POSITION_STICKY, type WebCssStyle } from '../styles/web-view-style';
 import { useTheme } from '../theme/use-theme';
 import { AppShellBottomBar, AppShellFloatingAction, AppShellTopBar, useShellInsets } from './AppShellBars';
 import { AppShellHeader } from './AppShellHeader';
@@ -94,8 +97,15 @@ function Scroller({
   );
 }
 
+export function createAppShellEngine(
+  ContentPanel: React.ComponentType<ContentPanelProps>,
+  BloomColorScope: React.ComponentType<Pick<BloomColorScopeProps, 'colorPreset' | 'asChild' | 'children'>>,
+) {
 const AppShellComponent: React.FC<AppShellEngineProps> = ({
   variant = 'dashboard',
+  navigationAlign = 'edge',
+  navigationGap,
+  asideGap,
   sidebar,
   drawer = 'overlay',
   title,
@@ -113,6 +123,7 @@ const AppShellComponent: React.FC<AppShellEngineProps> = ({
   navFrom,
   navExpandedFrom,
   panel = false,
+  panelColorPreset,
   framedFrom,
   list,
   info,
@@ -131,6 +142,7 @@ const AppShellComponent: React.FC<AppShellEngineProps> = ({
   topBarVisibility = 'compact',
   bottomBar,
   bottomBarVisibility = 'compact',
+  reserveBottomBarSpace = true,
   floatingAction,
   floatingActionPlacement = 'end',
   overlay,
@@ -141,6 +153,8 @@ const AppShellComponent: React.FC<AppShellEngineProps> = ({
   testID,
 }) => {
   const theme = useTheme();
+  const { height: viewportHeight } = useWindowDimensions();
+  const [asideHeight, setAsideHeight] = useState(0);
   const { width, onLayout } = useShellWidth();
   const insets = useShellInsets();
   const mode = resolveScrollMode(variant, scroll);
@@ -166,17 +180,18 @@ const AppShellComponent: React.FC<AppShellEngineProps> = ({
   // `focus` is the one shape with no navigation at all.
   const hasNav = variant !== 'focus' && sidebar != null;
   const navInFlow = hasNav && wide;
+  // One responsive owner: a shell panel follows its in-flow navigation unless
+  // the caller explicitly requests an independent framing breakpoint.
+  const managedPanel = panel === true && hasNav && framedFrom === undefined;
+  const compactPanel = managedPanel && !navInFlow;
+  const panelFramed = managedPanel ? navInFlow : undefined;
   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' as const } : 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';
+  // A feed may reveal its navigation while compact; its desktop column layout
+  // remains on the normal path below.
+  const drawerStyle = variant === 'dashboard' || variant === 'feed' ? 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
@@ -197,6 +212,19 @@ const AppShellComponent: React.FC<AppShellEngineProps> = ({
   const drawerAvailable = hasNav && !wide;
   const isOpen = open && drawerAvailable;
 
+  useEffect(() => {
+    if (Platform.OS !== 'web' || !isOpen || drawerStyle !== 'reveal') return;
+    const dismiss = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') { event.preventDefault(); setOpen(false); }
+    };
+    document.addEventListener('keydown', dismiss);
+    return () => document.removeEventListener('keydown', dismiss);
+  }, [isOpen, drawerStyle, setOpen]);
+
+  const revealAvailable = drawerStyle === 'reveal' && drawerAvailable;
+  const feedRevealAvailable = variant === 'feed' && revealAvailable;
+  const feedRevealed = feedRevealAvailable && isOpen;
+
   const shell = useMemo(
     () => ({
       drawerAvailable,
@@ -244,6 +272,7 @@ const AppShellComponent: React.FC<AppShellEngineProps> = ({
   const showTopBar = topBar != null && barActive(topBarVisibility);
   const showBottomBar = bottomBar != null && barActive(bottomBarVisibility);
   const showFloatingAction = floatingAction != null;
+  const [topBarHeight, setTopBarHeight] = useState(0);
   const [bottomBarHeight, setBottomBarHeight] = useState(0);
   const [floatingActionHeight, setFloatingActionHeight] = useState(0);
   // Both slots are MEASURED rather than assumed: a bar's height is its
@@ -251,14 +280,14 @@ const AppShellComponent: React.FC<AppShellEngineProps> = ({
   const bottomEdge = showBottomBar ? bottomBarHeight : insets.bottom;
   const contentReserve =
     showBottomBar || showFloatingAction
-      ? bottomEdge + (showFloatingAction ? floatingActionHeight + gutter : 0)
+      ? (reserveBottomBarSpace ? bottomEdge : 0) + (showFloatingAction ? floatingActionHeight + gutter : 0)
       : 0;
 
   const bars = (
-    <>
+    <SurfaceLevelProvider level={compactPanel ? 1 : 0} fill={compactPanel ? theme.colors.card : background}>
       {showBottomBar ? (
         <AppShellBottomBar
-          doc={doc}
+          doc={doc && !revealAvailable}
           onHeightChange={setBottomBarHeight}
           testID={testID ? `${testID}-bottom-bar` : undefined}
         >
@@ -267,7 +296,7 @@ const AppShellComponent: React.FC<AppShellEngineProps> = ({
       ) : null}
       {showFloatingAction ? (
         <AppShellFloatingAction
-          doc={doc}
+          doc={doc && !revealAvailable}
           offset={bottomEdge + gutter}
           gutter={gutter}
           placement={floatingActionPlacement}
@@ -277,11 +306,11 @@ const AppShellComponent: React.FC<AppShellEngineProps> = ({
           {floatingAction}
         </AppShellFloatingAction>
       ) : null}
-    </>
+    </SurfaceLevelProvider>
   );
 
   const topBarNode = showTopBar ? (
-    <AppShellTopBar doc={doc} testID={testID ? `${testID}-top-bar` : undefined}>
+    <AppShellTopBar doc={doc} onHeightChange={setTopBarHeight} testID={testID ? `${testID}-top-bar` : undefined}>
       {topBar}
     </AppShellTopBar>
   ) : null;
@@ -329,21 +358,23 @@ const AppShellComponent: React.FC<AppShellEngineProps> = ({
     </View>
   );
 
-  // Beside the content: sticky and self-scrolling with document scroll, a
-  // full-height scroller otherwise.
+  // Document asides grow naturally. A tall aside first travels with the page
+  // until its bottom is visible, then sticks; wheel events keep scrolling the
+  // document rather than getting trapped in a second scroll container.
   const asideColumn = (inset: WebCssStyle) =>
     asideBeside ? (
       <View
         testID={testID ? `${testID}-aside` : undefined}
+        onLayout={event => setAsideHeight(event.nativeEvent.layout.height)}
         style={[
           { width: asideWidth, flexShrink: 0 },
-          doc ? { ...stickyRail(gutter), width: asideWidth } : { alignSelf: 'stretch' },
+          doc ? { position: WEB_POSITION_STICKY, top: Math.min(gutter, viewportHeight - asideHeight - gutter), alignSelf: 'flex-start' } : { alignSelf: 'stretch' },
           inset,
         ]}
       >
-        <ScrollView style={{ flex: 1 }} contentContainerStyle={{ flexGrow: 1 }} showsVerticalScrollIndicator={false}>
+        {doc ? aside : <ScrollView style={{ flex: 1 }} contentContainerStyle={{ flexGrow: 1 }} showsVerticalScrollIndicator={false}>
           {aside}
-        </ScrollView>
+        </ScrollView>}
       </View>
     ) : null;
 
@@ -355,17 +386,33 @@ const AppShellComponent: React.FC<AppShellEngineProps> = ({
     const target = isOpen && drawerStyle === 'reveal' ? 1 : 0;
     reveal.value = reducedMotion ? target : withTiming(target, { duration: REVEAL_MS, easing: REVEAL_EASE });
   }, [isOpen, drawerStyle, reducedMotion, reveal]);
+  const feedPageStyle = useAnimatedStyle(() => ({
+    transform: reveal.value === 0 ? [] : [{ translateX: (REVEAL_OFFSET + 12) * reveal.value }],
+  }), [reveal]);
+
+  const feedChromeTransition: WebCssStyle = Platform.OS === 'web'
+    ? { '--bloom-panel-inset-duration': reducedMotion ? '0ms' : `${REVEAL_MS}ms` } : {};
+  const feedInsetsStyle = useAnimatedStyle(() => ({
+    paddingTop: 12 * reveal.value,
+    paddingBottom: 12 * reveal.value,
+  }), [reveal]);
+  const feedBarsStyle = useAnimatedStyle(() => ({
+    top: 12 * reveal.value,
+    bottom: 12 * reveal.value,
+    borderRadius: 28 * reveal.value,
+  }), [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 }),
+    () => ({ transform: reveal.value === 0 ? [] : [{ translateX: REVEAL_OFFSET * reveal.value }], borderRadius: 32 * reveal.value }),
     [reveal],
   );
   const veilStyle = useAnimatedStyle(() => ({ opacity: reveal.value }), [reveal]);
 
-  if (drawerStyle === 'reveal') {
+  if (drawerStyle === 'reveal' && variant === 'dashboard') {
     return (
       <AppShellProvider value={shell}>
         <View
@@ -447,7 +494,15 @@ const AppShellComponent: React.FC<AppShellEngineProps> = ({
             ) : null}
           </Animated.View>
           {overlay}
-          {bars}
+          {drawerAvailable ? (
+            <Animated.View
+              testID={testID ? `${testID}-reveal-bars` : undefined}
+              pointerEvents={isOpen ? 'none' : 'box-none'}
+              style={[{ position: doc ? WEB_POSITION_FIXED : 'absolute', top: 0, bottom: 0, left: 0, right: 0, overflow: 'hidden' }, pageStyle]}
+            >
+              {bars}
+            </Animated.View>
+          ) : bars}
         </View>
       </AppShellProvider>
     );
@@ -465,6 +520,13 @@ const AppShellComponent: React.FC<AppShellEngineProps> = ({
 
   // ---- the page region, per variant ---------------------------------------
   /** `feed` / `focus`: a fixed reading column, centred in what the nav leaves. */
+  const contentAligned = navigationAlign === 'content' && centred;
+  // Plain navigation belongs to the viewport; only the reading surfaces are inset.
+  const documentPanelInset = feedRevealed ? 12 : compactPanel ? 0 : gutter;
+  const externalTopHeight = showTopBar ? topBarHeight : 0;
+  const plainDocumentFrame = doc && contentAligned && flowSidebar?.surface === 'plain' && !topBarNode;
+  const readingGap = Math.max(0, asideGap ?? columnGap);
+  const readingGroupWidth = contentWidth + (asideBeside ? asideWidth + readingGap : 0);
   const centredBody = (
     <View
       style={[
@@ -475,10 +537,12 @@ const AppShellComponent: React.FC<AppShellEngineProps> = ({
           minWidth: 0,
           flexDirection: 'row',
           justifyContent: 'center',
-          gap: columnGap,
+          gap: readingGap,
           // 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',
+          ...(contentAligned ? { flexGrow: compactPanel ? 1 : 0, flexBasis: compactPanel ? 'auto' : readingGroupWidth, maxWidth: compactPanel ? undefined : readingGroupWidth } : {}),
+          ...(plainDocumentFrame ? { paddingTop: compactPanel ? 0 : gutter, paddingBottom: compactPanel ? 0 : gutter } : {}),
         },
         fill,
       ]}
@@ -488,17 +552,17 @@ const AppShellComponent: React.FC<AppShellEngineProps> = ({
         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 },
+          { flexGrow: compactPanel ? 1 : 0, flexShrink: 1, flexBasis: compactPanel ? 'auto' : contentWidth, maxWidth: compactPanel ? undefined : contentWidth, minWidth: 0 },
           doc ? null : { alignSelf: 'stretch' },
         ]}
       >
         {panelFills ? (
-          // 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.
+          // A bounded panel fills the screen. Container mode scrolls its body;
+          // fixed mode leaves scrolling to the child navigator/list.
+          <BloomColorScope colorPreset={panelColorPreset} asChild>
           <ContentPanel
+            maskColor={background}
+            framed={panelFramed}
             framedFrom={framedFrom}
             fill
             // The panel's box already IS the visible area here, so the frame is
@@ -507,49 +571,56 @@ const AppShellComponent: React.FC<AppShellEngineProps> = ({
             surfaceStyle={{ flexGrow: 1, flexShrink: 1, flexBasis: 'auto', minHeight: 0 }}
             contentStyle={{ flexGrow: 1, flexShrink: 1, flexBasis: 'auto', minHeight: 0 }}
           >
-            <View style={{ flex: 1, minHeight: 0, padding: gutter, gap: 16 }}>
+            <View style={{ flex: 1, minHeight: 0 }}>
               {headerNode}
-              <ScrollView
+              <Scroller
+                mode={mode}
                 testID={testID ? `${testID}-page` : undefined}
                 style={{ flex: 1, minHeight: 0 }}
-                contentContainerStyle={{ gap: 16, paddingBottom: contentReserve }}
+                // A fixed page owns its list and edge clearance. Padding its
+                // navigator here would charge the same occupied edge twice.
+                contentStyle={mode === 'fixed' ? {} : { paddingBottom: contentReserve }}
               >
                 {children}
-              </ScrollView>
+              </Scroller>
             </View>
           </ContentPanel>
+          </BloomColorScope>
         ) : (
         <Scroller
           mode={mode}
           testID={testID ? `${testID}-page` : undefined}
           style={{}}
-          contentStyle={{ paddingBottom: contentReserve }}
+          contentStyle={{ paddingBottom: panel ? 0 : contentReserve }}
         >
+          <BloomColorScope colorPreset={panelColorPreset} asChild>
           {panel ? (
             <ContentPanel
+            maskColor={background}
+              framed={feedRevealed || panelFramed}
+              chrome={feedRevealed ? "none" : undefined}
               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}
+              overlayInset={{ top: externalTopHeight + documentPanelInset, bottom: documentPanelInset }}
               // 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' }}
+              surfaceStyle={{ flexGrow: 1, flexShrink: 1, flexBasis: 'auto',
+                // The viewport frame must have a painted surface even when the
+                // page is short. A minimum still lets long documents grow.
+                minHeight: webViewportHeightMinus(externalTopHeight + documentPanelInset * 2) }}
               contentStyle={{ flexGrow: 1, flexShrink: 1, flexBasis: 'auto' }}
             >
-              {/*
-                The panel's content is inset by the gutter. Without it the page
-                sits ON the frame: a radius-28 corner CLIPS whatever is in it
-                (the heading loses its first letter) and every card butts
-                against the border with no edge of its own. So `contentWidth` is
-                the COLUMN's width and the reading measure inside a panel is
-                that minus two gutters.
-              */}
-              <View style={[{ gap: 16, padding: gutter }, fill]}>
-                {headerNode}
+              {/* Header chrome spans the panel. Its own title/action insets
+                  belong to PageHeader; the screen owns all body padding. */}
+              {headerNode}
+              <View style={[{ paddingBottom: contentReserve }, fill]}>
                 {children}
               </View>
+              {feedRevealed && <StyledView pointerEvents="none" className="absolute inset-0 z-20"
+                style={{ backgroundColor: theme.isDark ? 'rgba(255, 255, 255, 0.05)' : 'rgba(0, 0, 0, 0.1)' }} />}
             </ContentPanel>
           ) : (
             <View style={[{ gap: 16 }, fill]}>
@@ -557,6 +628,7 @@ const AppShellComponent: React.FC<AppShellEngineProps> = ({
               {children}
             </View>
           )}
+          </BloomColorScope>
           {asideStacked ? <View testID={testID ? `${testID}-aside` : undefined}>{aside}</View> : null}
         </Scroller>
         )}
@@ -661,7 +733,7 @@ const AppShellComponent: React.FC<AppShellEngineProps> = ({
   const navRegion =
     navInFlow && flowSidebar ? (
       doc ? (
-        <View style={stickyRail(dockedNav ? 0 : gutter)}>
+        <View testID={testID ? `${testID}-navigation` : undefined} style={stickyRail(dockedNav || plainDocumentFrame ? 0 : gutter)}>
           <Sidebar {...flowSidebar} />
         </View>
       ) : canvas && !dockedNav ? (
@@ -698,14 +770,52 @@ const AppShellComponent: React.FC<AppShellEngineProps> = ({
 
   const rowStyle: WebCssStyle = {
     flexDirection: 'row',
-    gap: dockedNav || canvas ? 0 : columnGap,
+    ...(contentAligned ? { justifyContent: 'center' } : {}),
+    gap: dockedNav || canvas ? 0 : Math.max(0, navigationGap ?? 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,
+    padding: canvas || plainDocumentFrame ? 0 : gutter,
     ...(dockedNav ? { paddingLeft: 0, paddingTop: 0, paddingBottom: 0 } : null),
     backgroundColor: background,
   };
 
+  if (variant === 'feed' && drawerStyle === 'reveal' && drawerAvailable) {
+    return (
+      <AppShellProvider value={shell}>
+        <View testID={testID} onLayout={onLayout}
+          style={[frame, { overflow: doc ? WEB_OVERFLOW_CLIP : 'hidden', backgroundColor: background }, style]}>
+          <View aria-hidden={!isOpen} pointerEvents={isOpen ? 'auto' : 'none'}
+            style={{ position: doc ? WEB_POSITION_FIXED : 'absolute', top: 0, bottom: 0, left: 0, width: 272, paddingTop: 12, paddingBottom: 12, paddingLeft: 6 }}>
+            <Animated.View style={[{ height: '100%', width: 260, transformOrigin: 'left center' }, railStyle]}>
+              {drawerSidebar && <Sidebar {...drawerSidebar} mobile surface="plain" onClose={() => setOpen(false)} />}
+            </Animated.View>
+          </View>
+          <Animated.View testID={testID ? `${testID}-reveal-page` : undefined}
+            style={[{ flexGrow: 1, minWidth: 0, overflow: doc ? WEB_OVERFLOW_CLIP : 'hidden', backgroundColor: background }, feedChromeTransition, feedPageStyle, feedInsetsStyle]}>
+            {topBarNode}
+            <StyledView className={doc ? undefined : "flex-1 min-h-0"}>
+              <View style={[rowStyle, { flexGrow: 1, minWidth: 0 }]}>{body}</View>
+            </StyledView>
+            <Animated.View pointerEvents={isOpen ? 'auto' : 'none'}
+              style={[{ position: 'absolute', top: 0, left: 0, right: 0, bottom: 0 }, veilStyle]}>
+              <Pressable role="button" accessibilityLabel="Close navigation" focusable={isOpen}
+                onPress={() => setOpen(false)} testID={testID ? `${testID}-veil` : undefined}
+                style={{ flex: 1 }} />
+            </Animated.View>
+          </Animated.View>
+          <Animated.View pointerEvents={isOpen ? 'none' : 'box-none'}
+            testID={testID ? `${testID}-reveal-bars` : undefined}
+            style={[{ position: doc ? WEB_POSITION_FIXED : 'absolute', left: 0, right: 0, overflow: 'hidden' }, feedPageStyle, feedBarsStyle]}>
+            {bars}
+            {isOpen && <StyledView pointerEvents="none" className="absolute bottom-0 left-0 right-0"
+              style={{ height: contentReserve, backgroundColor: theme.isDark ? 'rgba(255, 255, 255, 0.05)' : 'rgba(0, 0, 0, 0.1)' }} />}
+          </Animated.View>
+          {overlay}
+        </View>
+      </AppShellProvider>
+    );
+  }
+
   // 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.
@@ -743,5 +853,8 @@ const AppShellComponent: React.FC<AppShellEngineProps> = ({
   );
 };
 
-export const AppShellEngine = memo(AppShellComponent);
+const AppShellEngine = memo(AppShellComponent);
 AppShellEngine.displayName = 'AppShellEngine';
+
+return AppShellEngine;
+}

package/src/app-shell/index.ts

@@ -1,7 +1,9 @@
 import { createAppShell } from './AppShell';
 import { BottomBar } from '../bottom-bar';
 import { Fab } from '../fab';
-export const AppShell = createAppShell(BottomBar, Fab);
+import { ContentPanel } from '../content-panel';
+import { BloomColorScope } from '../theme/color-scope';
+export const AppShell = createAppShell(BottomBar, Fab, ContentPanel, BloomColorScope);
 export { AppShellHeader } from './AppShellHeader';
 export { AppShellMenuButton } from './AppShellMenuButton';
 export { APP_SHELL_DEFAULTS } from './constants';

package/src/app-shell/index.web.ts

@@ -6,7 +6,9 @@
 import { createAppShell } from './AppShell';
 import { BottomBar } from '../bottom-bar/index.web';
 import { Fab } from '../fab/index.web';
-export const AppShell = createAppShell(BottomBar, Fab);
+import { ContentPanel } from '../content-panel/index.web';
+import { BloomColorScope } from '../theme/color-scope/index.web';
+export const AppShell = createAppShell(BottomBar, Fab, ContentPanel, BloomColorScope);
 export { AppShellHeader } from './AppShellHeader';
 export { AppShellMenuButton } from './AppShellMenuButton';
 export { APP_SHELL_DEFAULTS } from './constants';

package/src/app-shell/types.ts

@@ -1,3 +1,4 @@
+import type { AppColorName } from '../theme/color-presets';
 import type { ReactNode } from 'react';
 import type { StyleProp, ViewStyle } from 'react-native';
 
@@ -78,8 +79,8 @@ export interface AppShellEngineProps {
   sidebar?: Omit<SidebarProps, 'mobile' | 'onClose'>;
   /**
    * How the rail arrives below `navFrom`. `reveal` slides the WHOLE page
-   * sideways, which only reads on a one-column page — so it applies to
-   * `variant: 'dashboard'` and the other three always take the overlay drawer.
+   * sideways for dashboard and compact feed layouts. Feed desktop columns
+   * retain their normal layout. Other variants use the overlay drawer.
    */
   drawer?: AppShellDrawer;
   /**
@@ -107,7 +108,8 @@ export interface AppShellEngineProps {
    * A second column on the right of the page (a detail panel, activity, a
    * chat). In flow from `asideFrom`; below it, stacked under the content or
    * hidden (`asideCollapse`). Pinned like the sidebar — with document scroll
-   * it is sticky and scrolls its own overflow.
+   * it stays in document flow and sticks after tall content reaches its lower edge.
+   * Container/fixed modes retain an independently scrolling aside.
    */
   aside?: ReactNode;
   /** The aside column's width. Defaults to 320. */
@@ -152,6 +154,12 @@ export interface AppShellEngineProps {
    * screen: the column shrinks to the space it has rather than overflowing.
    */
   contentWidth?: number;
+  /** edge keeps navigation at the shell edge; content centers it with the reading column and aside. */
+  navigationAlign?: 'edge' | 'content';
+  /** Gap between the in-flow navigation and content. Defaults to the column gap. */
+  navigationGap?: number;
+  /** feed/focus: gap between the reading column and aside. Defaults to the column gap. */
+  asideGap?: number;
   /**
    * The space between the shell's edge and its regions. Default 12 for
    * `dashboard` (which also keeps its historical 16 column gap, so existing
@@ -178,12 +186,13 @@ export interface AppShellEngineProps {
    * `feed`: wrap the centre column in a `ContentPanel`, so the page background
    * reads as a gutter around a framed surface. The shell renders the panel —
    * a page that renders its own inside this one trips `ContentPanel`'s nesting
-   * guard. The panel's content is inset by `gutter`, so `contentWidth` stays
-   * the COLUMN's width and the reading measure inside it is that minus two
-   * gutters.
+   * guard. Screens own their content padding; the shell adds no horizontal inset.
    */
   panel?: boolean;
-  /** Forwarded to that `ContentPanel`: the width it starts being framed at. */
+  /** Theme only the central reading column; navigation, aside and framing retain the app theme. */
+  panelColorPreset?: AppColorName;
+  /** Optional independent framing breakpoint. By default a shell with navigation
+   * frames its panel exactly while the sidebar/rail is in flow. */
   framedFrom?: ContentPanelFramedBreakpoint;
 
   // -- split -----------------------------------------------------------------
@@ -238,6 +247,11 @@ export interface AppShellEngineProps {
    * last item is never hidden behind it.
    */
   bottomBar?: ReactNode;
+  /** Reserve the measured bar height in document/container content (default true).
+   * False keeps the bar over fullscreen content whose own scroller accounts for
+   * the occupied bottom edge. The bar still publishes its real edge occupancy.
+   * Fixed mode always leaves clearance to its child navigator/list. */
+  reserveBottomBarSpace?: boolean;
   /** `compact` (default): only while the nav is a drawer. */
   bottomBarVisibility?: AppShellBarVisibility;
   /** The compose/FAB corner — above the bottom bar when there is one. */
@@ -329,7 +343,8 @@ export interface AppShellNavigationProps {
   navigationMaterial?: 'solid' | 'translucent';
   /** Bottom action follows scroll collapse by hiding (default), or remains visible. */
   bottomActionBehavior?: 'hide' | 'visible';
-  /** external: the child list owns scrolling; avoids nested virtualized lists. */
+  /** Web defaults to document; native to auto. Explicit auto owns a ScrollView.
+   * external: the child list owns scrolling; avoids nested virtualized lists. */
   scroll?: AppShellScroll | 'auto' | 'external';
   /** Sidebar configuration, including card (detached, default) or docked surface. Also applies with navigation. */
   sidebar?: Omit<SidebarProps, 'mobile' | 'onClose'>;

package/src/bottom-bar/BottomBarBase.tsx

@@ -1,9 +1,11 @@
-import { useRef, useState, type ComponentType } from 'react';
+import { useContext, useRef, useState, type ComponentType } from 'react';
 import { View, ScrollView, Keyboard, Platform } from 'react-native';
 import { useEffect } from 'react';
 import Animated, { useAnimatedReaction, useAnimatedStyle, interpolate, runOnJS, useReducedMotion } from 'react-native-reanimated';
 import { useSafeAreaInsets } from 'react-native-safe-area-context';
+import { BottomBarSlotContext } from '../layout/bottom-bar-slot';
 import { useClaimBottomEdge } from '../layout/bottom-edge';
+import { FAB_METRICS } from '../fab/constants';
 import { windowEdgeGap } from '../layout/edge';
 import { useMinimizeState } from '../tab-bar/context';
 import { EXPANDED_HEIGHT, MINIMIZED_HEIGHT, BLUR_BLEED, MAX_EXPANDED_ITEM_WIDTH, ROW_PAD_H } from '../tab-bar/shared';
@@ -16,8 +18,8 @@ interface Props extends BottomBarProps {
   Item: ComponentType<TabBarButtonProps>;
   Blur: ComponentType<ProgressiveBlurProps>;
 }
-export function BottomBarBase({ Navigation, Item, Blur, items, value, onValueChange, action,
-  actionBehavior = 'hide', material = 'translucent', minimizeProgress, blur = true, maxWidth = 560, style, testID }: Props) {
+export function BottomBarBase({ Navigation, Item, Blur, items, value, onValueChange, activeProgress, onValueLongPress, action,
+  actionPlacement = 'auto', actionBehavior = 'hide', material = 'translucent', minimizeProgress, blur = true, maxWidth = 560, style, testID }: Props) {
   const insets = useSafeAreaInsets();
   const minimize = useMinimizeState();
   const progress = minimizeProgress ?? minimize.progress;
@@ -26,9 +28,12 @@ export function BottomBarBase({ Navigation, Item, Blur, items, value, onValueCha
   const [actionHidden, setActionHidden] = useState(() => hideAction && progress.value > 0.01);
   const actionRef = useRef<View>(null);
   const [actionWidth, setActionWidth] = useState<number | null>(null);
+  const [actionHeight, setActionHeight] = useState<number>(FAB_METRICS.md.diameter);
   const [rowWidth, setRowWidth] = useState(0);
-  const actionSpace = action ? (actionWidth ?? 56) + 10 : 0;
-  const navigationWidth = Math.max(0, Math.min(rowWidth - 24 - actionSpace, items.length * MAX_EXPANDED_ITEM_WIDTH + ROW_PAD_H * 2));
+  const actionSpace = action ? (actionWidth ?? FAB_METRICS.md.diameter) + 10 : 0;
+  const above = Boolean(action && items.length && (actionPlacement === 'above' || (actionPlacement === 'auto' && rowWidth > 0 && rowWidth - 24 - actionSpace < items.length * 56 + ROW_PAD_H * 2)));
+  const footprint = EXPANDED_HEIGHT + (above ? actionHeight + 10 : Math.max(0, action ? actionHeight - EXPANDED_HEIGHT : 0));
+  const navigationWidth = Math.max(0, Math.min(rowWidth - 24 - (above ? 0 : actionSpace), items.length * MAX_EXPANDED_ITEM_WIDTH + ROW_PAD_H * 2));
   // Only interaction eligibility crosses to JS; all motion stays on the shared UI signal.
   useAnimatedReaction(() => hideAction && progress.value > 0.01, (hidden, previous) => {
     if (hidden !== previous) runOnJS(setActionHidden)(hidden);
@@ -41,14 +46,15 @@ export function BottomBarBase({ Navigation, Item, Blur, items, value, onValueCha
     node.inert = actionHidden;
   }, [actionHidden]);
   const [keyboardVisible, setKeyboardVisible] = useState(false);
-  const bottom = windowEdgeGap(insets.bottom);
+  const suppliedBottomInset = useContext(BottomBarSlotContext);
+  const bottom = Math.max(0, windowEdgeGap(insets.bottom) - (suppliedBottomInset ?? 0));
   useEffect(() => {
     if (Platform.OS === 'web') return;
     const show = Keyboard.addListener('keyboardDidShow', () => setKeyboardVisible(true));
     const hide = Keyboard.addListener('keyboardDidHide', () => setKeyboardVisible(false));
     return () => { show.remove(); hide.remove(); };
   }, []);
-  useClaimBottomEdge(keyboardVisible ? 0 : bottom + EXPANDED_HEIGHT);
+  useClaimBottomEdge(keyboardVisible || suppliedBottomInset !== undefined ? 0 : bottom + footprint);
   const rowStyle = useAnimatedStyle(() => ({
     height: interpolate(reducedMotion ? Number(progress.value > 0.01) : progress.value, [0, 1], [EXPANDED_HEIGHT, MINIMIZED_HEIGHT], 'clamp'),
   }), [progress, reducedMotion]);
@@ -56,24 +62,25 @@ export function BottomBarBase({ Navigation, Item, Blur, items, value, onValueCha
     const amount = hideAction ? Math.min(1, Math.max(0, reducedMotion ? Number(progress.value > 0.01) : progress.value)) : 0;
     return {
       ...(actionWidth == null ? {} : { width: actionWidth * (1 - amount) }),
-      marginLeft: items.length ? 10 * (1 - amount) : 0,
+      marginLeft: items.length && !above ? 10 * (1 - amount) : 0,
       opacity: 1 - amount,
       transform: [{ scale: 1 - amount * 0.15 }],
     };
-  }, [progress, hideAction, reducedMotion, actionWidth, items.length]);
+  }, [progress, hideAction, reducedMotion, actionWidth, items.length, above]);
   if (keyboardVisible || (!items.length && !action)) return null;
-  return <View testID={testID} pointerEvents="box-none" style={[{ height: bottom + EXPANDED_HEIGHT, justifyContent: 'flex-end' }, style]}>
-    {blur && material === 'translucent' && <Blur direction="bottom" style={{ position: 'absolute', left: 0, right: 0, bottom: 0, height: bottom + EXPANDED_HEIGHT + BLUR_BLEED }} />}
-    <Animated.View onLayout={event => setRowWidth(event.nativeEvent.layout.width)} pointerEvents="box-none" style={[{ justifyContent: items.length ? 'center' : 'flex-end', alignSelf: 'center', width: '100%', maxWidth, paddingLeft: 12, paddingRight: 12, marginBottom: bottom, flexDirection: 'row', alignItems: 'flex-end' }, rowStyle]}>
+  return <View testID={testID} pointerEvents="box-none" style={[{ height: bottom + footprint, justifyContent: 'flex-end' }, style]}>
+    {blur && material === 'translucent' && <Blur direction="bottom" style={{ position: 'absolute', left: 0, right: 0, bottom: 0, height: bottom + footprint + BLUR_BLEED }} />}
+    <Animated.View testID={testID ? `${testID}-row` : undefined} onLayout={event => setRowWidth(event.nativeEvent.layout.width)} pointerEvents="box-none" style={[{ justifyContent: items.length ? 'center' : 'flex-end', alignSelf: 'center', width: '100%', maxWidth, paddingLeft: 12, paddingRight: 12, marginBottom: bottom, flexDirection: 'row', alignItems: 'center' }, rowStyle]}>
       {items.length > 0 && <View testID={testID ? `${testID}-navigation` : undefined} style={{ width: navigationWidth, minWidth: 0 }}><ScrollView horizontal showsHorizontalScrollIndicator={false} contentContainerStyle={{ minWidth: '100%' }}><View style={{ width: Math.max(navigationWidth, items.length * 44 + 8) }}><Navigation scrollable={navigationWidth > 0 && navigationWidth < items.length * 44 + 8} embedded blur={false} material={material} minimizeProgress={progress}
+        activeProgress={activeProgress} onIndexLongPress={onValueLongPress ? index => { if (items[index]) onValueLongPress(items[index].name); } : undefined}
         activeIndex={items.findIndex(item => item.name === value)} onIndexChange={index => { if (items[index]) onValueChange(items[index].name); }}>
         {items.map((item, index) => <Item key={item.name} item={item} index={index} />)}
       </Navigation></View></ScrollView></View>}
       {action && <Animated.View ref={actionRef} pointerEvents={actionHidden ? 'none' : 'auto'}
         accessibilityElementsHidden={actionHidden} importantForAccessibility={actionHidden ? 'no-hide-descendants' : 'auto'}
         aria-hidden={actionHidden} testID={testID ? `${testID}-action` : undefined}
-        style={[{ flexShrink: 0, alignItems: 'flex-start', justifyContent: 'center' }, actionStyle]}>
-        <View onLayout={event => setActionWidth(event.nativeEvent.layout.width)} style={{ flexShrink: 0, ...(actionWidth == null ? {} : { width: actionWidth }) }}>{action}</View>
+        style={[{ flexShrink: 0, alignItems: 'flex-start', justifyContent: 'center' }, above ? { position: 'absolute', right: 12, bottom: '100%', marginBottom: 10 } : undefined, actionStyle]}>
+        <View testID={testID ? `${testID}-action-content` : undefined} onLayout={event => { setActionWidth(event.nativeEvent.layout.width); setActionHeight(event.nativeEvent.layout.height); }} style={{ flexShrink: 0, ...(actionWidth == null ? {} : { width: actionWidth }) }}>{action}</View>
       </Animated.View>}
     </Animated.View>
   </View>;