@oxy.so/bloom 2.10.0 → 2.11.0

package/src/app-shell/AppShellBars.tsx

@@ -0,0 +1,162 @@
+/**
+ * The three pinned slots — `topBar`, `bottomBar` and `floatingAction` — and the
+ * one rule they exist to enforce: NOTHING a consumer writes should have to
+ * position itself.
+ *
+ * Every app that has drawn a phone tab bar or a compose button over a page has
+ * written the same four lines: `position: fixed`, a hardcoded `bottom`, a
+ * safe-area inset copied from somewhere, and a negative margin to escape
+ * whatever padding the page had. All four are wrong in at least one place — a
+ * fixed bar is wrong inside an embedded shell, a hardcoded bottom is wrong on a
+ * notched phone, and a negative margin is wrong the moment the page's padding
+ * changes. The shell knows all four answers, so it answers them here and the
+ * consumer passes plain content.
+ *
+ * The anchoring itself forks, and has to:
+ *
+ * - WEB + document scroll — `position: fixed`. The document is what scrolls, so
+ *   the only box that stays put is the viewport.
+ * - everything else (web `container`/`fixed`, and all of native) — absolute
+ *   inside the shell's own frame, which IS the bounded box. Native has no
+ *   `fixed`; Yoga ignores it silently, which would leave a native bar scrolling
+ *   away with no error to explain it.
+ *
+ * Each wrapper is `pointerEvents="box-none"` as a PROP (a style entry is
+ * dropped): the bar's own content takes presses, the empty space around it does
+ * not, so a full-width FAB wrapper never swallows a tap on the content behind
+ * it.
+ */
+import React, { memo, useContext } from 'react';
+import { View, type LayoutChangeEvent } from 'react-native';
+import { SafeAreaInsetsContext } from 'react-native-safe-area-context';
+
+import { WEB_POSITION_FIXED, WEB_POSITION_STICKY, type WebCssStyle } from '../styles/web-view-style';
+import { Z_INDEX } from '../styles/z-index';
+
+/** The safe-area insets, or zeros outside a `SafeAreaProvider`. */
+export function useShellInsets(): { top: number; bottom: number } {
+  // `useContext(SafeAreaInsetsContext)` rather than `useSafeAreaInsets()`: the
+  // hook THROWS outside a provider, and `AppShell` is mounted at an app's root,
+  // where making a previously-optional provider mandatory would be a breaking
+  // change for every consumer that never had a bar to inset.
+  const insets = useContext(SafeAreaInsetsContext);
+  return { top: insets?.top ?? 0, bottom: insets?.bottom ?? 0 };
+}
+
+/** Pinned to the bottom of the viewport (document scroll) or of the frame. */
+function anchorBottom(doc: boolean): WebCssStyle {
+  return {
+    position: doc ? WEB_POSITION_FIXED : 'absolute',
+    left: 0,
+    right: 0,
+    bottom: 0,
+    zIndex: Z_INDEX.floating,
+  };
+}
+
+export interface AppShellBottomBarProps {
+  children: React.ReactNode;
+  /** Document scroll: pin to the viewport rather than to the frame. */
+  doc: boolean;
+  /** Reports the bar's measured height so the page can reserve it. */
+  onHeightChange: (height: number) => void;
+  testID?: string;
+}
+
+/**
+ * The bottom bar: edge to edge, with the bottom safe-area inset applied as
+ * PADDING so the bar's own background still paints under the home indicator
+ * instead of leaving a stripe of page showing through.
+ */
+const AppShellBottomBarComponent: React.FC<AppShellBottomBarProps> = ({
+  children,
+  doc,
+  onHeightChange,
+  testID,
+}) => {
+  const insets = useShellInsets();
+  return (
+    <View
+      testID={testID}
+      pointerEvents="box-none"
+      onLayout={(event: LayoutChangeEvent) => onHeightChange(Math.round(event.nativeEvent.layout.height))}
+      style={[anchorBottom(doc), { paddingBottom: insets.bottom }]}
+    >
+      {children}
+    </View>
+  );
+};
+export const AppShellBottomBar = memo(AppShellBottomBarComponent);
+AppShellBottomBar.displayName = 'AppShellBottomBar';
+
+export interface AppShellFloatingActionProps {
+  children: React.ReactNode;
+  doc: boolean;
+  /** Distance from the bottom of the viewport/frame: the bar's height plus the gutter. */
+  offset: number;
+  gutter: number;
+  placement: 'start' | 'end';
+  onHeightChange: (height: number) => void;
+  testID?: string;
+}
+
+/**
+ * The compose/FAB corner. The wrapper spans the full width and ALIGNS its child
+ * rather than being positioned by one side, so `placement` is a one-word change
+ * and the button never needs to know its own width.
+ */
+const AppShellFloatingActionComponent: React.FC<AppShellFloatingActionProps> = ({
+  children,
+  doc,
+  offset,
+  gutter,
+  placement,
+  onHeightChange,
+  testID,
+}) => (
+  <View
+    testID={testID}
+    pointerEvents="box-none"
+    onLayout={(event: LayoutChangeEvent) => onHeightChange(Math.round(event.nativeEvent.layout.height))}
+    style={[
+      anchorBottom(doc),
+      {
+        bottom: offset,
+        paddingLeft: gutter,
+        paddingRight: gutter,
+        alignItems: placement === 'end' ? 'flex-end' : 'flex-start',
+      },
+    ]}
+  >
+    {children}
+  </View>
+);
+export const AppShellFloatingAction = memo(AppShellFloatingActionComponent);
+AppShellFloatingAction.displayName = 'AppShellFloatingAction';
+
+export interface AppShellTopBarProps {
+  children: React.ReactNode;
+  doc: boolean;
+  testID?: string;
+}
+
+/**
+ * The phone header. It is a sibling ABOVE the shell's columns, not a child of
+ * the content, so it spans the shell edge to edge without a negative margin —
+ * which is the whole reason it is a slot instead of something the page draws.
+ *
+ * `sticky` in document mode (it belongs to the page, so it may be scrolled past
+ * only as far as `top: 0`); in `container`/`fixed` and on native it is simply
+ * outside the scroller, which pins it by construction.
+ */
+const AppShellTopBarComponent: React.FC<AppShellTopBarProps> = ({ children, doc, testID }) => {
+  const insets = useShellInsets();
+  const pinned: WebCssStyle = doc ? { position: WEB_POSITION_STICKY, top: 0 } : {};
+  return (
+    <View testID={testID} style={[{ zIndex: Z_INDEX.floating, paddingTop: insets.top }, pinned]}>
+      {children}
+    </View>
+  );
+};
+export const AppShellTopBar = memo(AppShellTopBarComponent);
+AppShellTopBar.displayName = 'AppShellTopBar';

package/src/app-shell/AppShellHeader.tsx

@@ -24,12 +24,17 @@ const AppShellHeaderComponent: React.FC<AppShellHeaderProps> = ({
   actions,
   onMenuPress,
   menuOpen = false,
+  showMenu: showMenuProp,
   style,
   testID,
 }) => {
   const theme = useTheme();
+  // Standalone, the header has no shell to ask, so it falls back to the window
+  // being narrower than `lg`. Inside an `AppShell` it is TOLD, from the shell's
+  // own measured width and `navFrom` — the header must not second-guess a
+  // decision the shell already made against a different number.
   const { width } = useWindowDimensions();
-  const showMenu = onMenuPress != null && width < BREAKPOINTS.lg;
+  const showMenu = onMenuPress != null && (showMenuProp ?? width < BREAKPOINTS.lg);
 
   return (
     <View role="banner" testID={testID} style={[{ width: '100%', gap: 8 }, style]}>

package/src/app-shell/AppShellSplit.tsx

@@ -0,0 +1,176 @@
+/**
+ * The `split` variant's panes: a list, a detail and an optional info pane, each
+ * scrolling on its own, with a draggable divider between the first two.
+ *
+ * Why the panes scroll and the page does not: three columns that each keep
+ * their own position is a bounded-box layout by definition. There is one
+ * document, so at most one region can scroll it — a "split" that scrolled the
+ * document would move all three columns together, which is the layout it exists
+ * to avoid. `resolveScrollMode` therefore gives `split` a one-screen frame.
+ *
+ * The divider is `AiChatResizeHandle`, the grip `ai-chat` already ships: a 20px
+ * strip straddling the pane's edge with a grip that follows the pointer,
+ * pointer-capture dragging on web, a `PanResponder` on native, and arrow-key
+ * nudges when `onNudge` is given. Writing a second one would have meant a second
+ * set of the same three bugs.
+ */
+import React, { memo, useCallback, useRef, useState } from 'react';
+import { ScrollView, View } from 'react-native';
+
+import { AiChatResizeHandle } from '../ai-chat/AiChatShell';
+import { Z_INDEX } from '../styles/z-index';
+import { useTheme } from '../theme/use-theme';
+
+export interface AppShellSplitPanesProps {
+  list?: React.ReactNode;
+  detail?: React.ReactNode;
+  info?: React.ReactNode;
+  /** Which panes have room right now. */
+  showList: boolean;
+  showDetail: boolean;
+  showInfo: boolean;
+  /** The list pane's resting width; a drag moves it within min/max. */
+  listWidth: number;
+  listMinWidth: number;
+  listMaxWidth: number;
+  onListWidthChange?: (width: number) => void;
+  infoWidth: number;
+  resizable: boolean;
+  /** The shell wraps each pane in its own `ScrollView` unless the page owns one. */
+  paneScroll: boolean;
+  resizeLabel: string;
+  testID?: string;
+}
+
+/** One pane: a bounded column that scrolls its own overflow. */
+function Pane({
+  children,
+  scroll,
+  style,
+  testID,
+}: {
+  children: React.ReactNode;
+  scroll: boolean;
+  style: React.ComponentProps<typeof View>['style'];
+  testID?: string;
+}) {
+  return (
+    <View testID={testID} style={[{ minWidth: 0, alignSelf: 'stretch' }, style]}>
+      {scroll ? (
+        <ScrollView style={{ flex: 1 }} contentContainerStyle={{ flexGrow: 1 }}>
+          {children}
+        </ScrollView>
+      ) : (
+        <View style={{ flex: 1, minHeight: 0 }}>{children}</View>
+      )}
+    </View>
+  );
+}
+
+const AppShellSplitPanesComponent: React.FC<AppShellSplitPanesProps> = ({
+  list,
+  detail,
+  info,
+  showList,
+  showDetail,
+  showInfo,
+  listWidth,
+  listMinWidth,
+  listMaxWidth,
+  onListWidthChange,
+  infoWidth,
+  resizable,
+  paneScroll,
+  resizeLabel,
+  testID,
+}) => {
+  const theme = useTheme();
+  const [width, setWidth] = useState(listWidth);
+  const widthAtDragStart = useRef(listWidth);
+
+  const clamp = useCallback(
+    (next: number) => Math.min(listMaxWidth, Math.max(listMinWidth, next)),
+    [listMaxWidth, listMinWidth],
+  );
+  const commit = useCallback(
+    (next: number) => {
+      const clamped = clamp(next);
+      setWidth(clamped);
+      onListWidthChange?.(clamped);
+    },
+    [clamp, onListWidthChange],
+  );
+  const onResizeStart = useCallback(() => {
+    widthAtDragStart.current = width;
+  }, [width]);
+  const onResize = useCallback((dx: number) => commit(widthAtDragStart.current + dx), [commit]);
+  const onNudge = useCallback((dx: number) => commit(width + dx), [commit, width]);
+
+  /**
+   * The divider carries the z-index, NOT the grip inside it.
+   *
+   * react-native-web gives every `View` `position: relative; z-index: 0`, which
+   * makes each one a stacking context — so the grip's own `z-index: 10` only
+   * ranks it inside the divider, and the detail pane (a later sibling at the
+   * same level) painted over the 10px of grip that straddles it. Measured: a
+   * hit test at the divider's centre returned the pane, and the drag never
+   * started. Raising the DIVIDER lifts the whole context over both panes.
+   */
+  const divider = {
+    width: 1,
+    alignSelf: 'stretch' as const,
+    zIndex: Z_INDEX.floating,
+    backgroundColor: theme.colors.border,
+  };
+  // Only the panes that are actually drawn count: alone, a pane fills the row.
+  const solo = [showList, showDetail, showInfo].filter(Boolean).length === 1;
+
+  return (
+    <View style={{ flexGrow: 1, flexShrink: 1, minWidth: 0, flexDirection: 'row' }}>
+      {showList ? (
+        <Pane
+          testID={testID ? `${testID}-pane-list` : undefined}
+          scroll={paneScroll}
+          style={solo ? { flexGrow: 1, flexShrink: 1, flexBasis: 0 } : { width, flexShrink: 0 }}
+        >
+          {list}
+        </Pane>
+      ) : null}
+      {showList && !solo ? (
+        <View style={divider}>
+          {resizable ? (
+            <AiChatResizeHandle
+              label={resizeLabel}
+              onResizeStart={onResizeStart}
+              onResize={onResize}
+              onNudge={onNudge}
+              testID={testID ? `${testID}-divider` : undefined}
+            />
+          ) : null}
+        </View>
+      ) : null}
+      {showDetail ? (
+        <Pane
+          testID={testID ? `${testID}-pane-detail` : undefined}
+          scroll={paneScroll}
+          style={{ flexGrow: 1, flexShrink: 1, flexBasis: 0 }}
+        >
+          {detail}
+        </Pane>
+      ) : null}
+      {showInfo && !solo ? <View style={divider} /> : null}
+      {showInfo ? (
+        <Pane
+          testID={testID ? `${testID}-pane-info` : undefined}
+          scroll={paneScroll}
+          style={solo ? { flexGrow: 1, flexShrink: 1, flexBasis: 0 } : { width: infoWidth, flexShrink: 0 }}
+        >
+          {info}
+        </Pane>
+      ) : null}
+    </View>
+  );
+};
+
+export const AppShellSplitPanes = memo(AppShellSplitPanesComponent);
+AppShellSplitPanes.displayName = 'AppShellSplitPanes';

package/src/app-shell/constants.ts

@@ -0,0 +1,65 @@
+import { BREAKPOINTS } from '../styles/breakpoints';
+import type { AppShellBreakpoint } from './types';
+/**
+ * `AppShell`'s measured defaults, in one place so a story, a test and the docs
+ * can name the same number instead of each repeating a literal.
+ *
+ * Every one of these is a PROP. The reason they have defaults at all is that a
+ * consumer should never have to reach for a window-width hook, a negative
+ * margin or a hardcoded pixel value to get a normal app layout — the shell
+ * already knows the shape it is drawing.
+ */
+export const APP_SHELL_DEFAULTS = {
+  /**
+   * `dashboard`: the cap on the content column. The dashboard column is
+   * FLUID — it fills the page region and stops growing here — so this is a
+   * maximum, not a width.
+   */
+  contentMaxWidth: 1300,
+  /**
+   * `feed` / `focus`: the reading column's width. 600 is the width a single
+   * column of `body-regular` (15/22) holds at roughly 75 characters, which is
+   * the measure long-form text stays readable at; wider columns lose the line
+   * and narrower ones break too often.
+   */
+  contentWidth: 600,
+  /** The second column's width, `dashboard` and `feed` alike. */
+  asideWidth: 320,
+  /**
+   * The aside needs its own width PLUS the content column PLUS the nav before
+   * it earns a place: 272 (panel) + 600 + 320 + three gutters is 1216, so `xl`
+   * (1280) is the first tier where the three columns fit without squeezing the
+   * content.
+   */
+  asideFrom: 'xl',
+  /**
+   * The gap between the shell's edge and its regions, and between the regions.
+   *
+   * `dashboard` keeps the pair it shipped with — 12 of padding and a 16 column
+   * gap — because changing either moves every existing page by four pixels.
+   * The other variants use ONE number for both, which is why `gutter` defaults
+   * differently per variant rather than being a single constant.
+   */
+  dashboardGutter: 12,
+  dashboardColumnGap: 16,
+  gutter: 16,
+  /** `split`: the list pane's resting width, and the range a drag may reach. */
+  listWidth: 360,
+  listMinWidth: 280,
+  listMaxWidth: 520,
+  /** `split`: the third (info) pane. */
+  infoWidth: 320,
+  /**
+   * `split`: two panes from `md` (768) — 360 of list still leaves 384 of
+   * detail, which is a phone's worth of reading width; below it a second pane
+   * would be too narrow to be a pane rather than a sliver.
+   */
+  splitFrom: 'md',
+  /** `split`: the third pane needs the same headroom the aside does. */
+  infoFrom: 'xl',
+} as const;
+
+/** A named tier or a literal width, in pixels. */
+export function breakpointPx(value: AppShellBreakpoint): number {
+  return typeof value === 'number' ? value : BREAKPOINTS[value];
+}

package/src/app-shell/index.ts

@@ -1,13 +1,19 @@
 export { AppShell } from './AppShell';
 export { AppShellHeader } from './AppShellHeader';
 export { AppShellMenuButton } from './AppShellMenuButton';
+export { APP_SHELL_DEFAULTS } from './constants';
 export { useAppShell } from './context';
 export type { AppShellContextValue } from './context';
 export { NotificationBell } from './NotificationBell';
 export { ProOfferCard } from './ProOfferCard';
 
 export type {
+  AppShellBarVisibility,
+  AppShellBreakpoint,
   AppShellDrawer,
+  AppShellPane,
+  AppShellScroll,
+  AppShellVariant,
   AppShellHeaderProps,
   AppShellMenuButtonProps,
   AppShellProps,

package/src/app-shell/layout.ts

@@ -0,0 +1,72 @@
+/**
+ * `AppShell`'s frames: the four boxes a shell can be, and the two ways a region
+ * pins itself inside one. Kept apart from the component so the variants share
+ * ONE set of rules rather than each re-deriving them.
+ */
+import { Platform } from 'react-native';
+
+import {
+  WEB_POSITION_STICKY,
+  WEB_VIEWPORT_HEIGHT,
+  webViewportHeightMinus,
+  type WebCssStyle,
+} from '../styles/web-view-style';
+import type { AppShellScroll, AppShellVariant } from './types';
+
+export type ScrollMode = 'document' | 'container' | 'fixed';
+
+/**
+ * Which frame a shell actually gets.
+ *
+ * Native has no document, so `document` falls back to `container` there.
+ * `split` is the other reduction: its panes each own their scrolling, which is
+ * only expressible inside a bounded box — a document-scrolling split would have
+ * one pane growing the page and the others pinned to nothing. So `split`
+ * resolves `document` to `fixed` (one screen) and honours `container` as-is.
+ */
+export function resolveScrollMode(variant: AppShellVariant, scroll: AppShellScroll): ScrollMode {
+  if (variant === 'split') return scroll === 'container' ? 'container' : 'fixed';
+  if (scroll === 'document' && Platform.OS !== 'web') return 'container';
+  return scroll;
+}
+
+/**
+ * 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.
+ */
+export const documentRoot: WebCssStyle = { flexGrow: 1, minHeight: WEB_VIEWPORT_HEIGHT };
+
+/** Container mode: fill the parent, scroll inside. */
+export const containerRoot: WebCssStyle = { flex: 1, height: '100%', overflow: 'hidden' };
+
+/**
+ * Fixed mode: exactly one screen — `100dvh` on web, the parent on native — and
+ * nothing scrolls; the content fills the height left under the header.
+ */
+export const fixedRoot: WebCssStyle =
+  Platform.OS === 'web'
+    ? { height: WEB_VIEWPORT_HEIGHT, overflow: 'hidden' }
+    : { flex: 1, height: '100%', overflow: 'hidden' };
+
+export function rootFrame(mode: ScrollMode): WebCssStyle {
+  return mode === 'document' ? documentRoot : mode === 'fixed' ? fixedRoot : containerRoot;
+}
+
+/**
+ * A region pinned to the viewport while the document scrolls under it — the nav
+ * rail and the aside. `sticky` rather than `fixed` so the region keeps its place
+ * in the row: a fixed column is out of flow, and the content beside it would
+ * slide underneath.
+ */
+export function stickyRail(inset: number): WebCssStyle {
+  return {
+    position: WEB_POSITION_STICKY,
+    top: inset,
+    height: webViewportHeightMinus(inset * 2),
+    alignSelf: 'flex-start',
+    flexShrink: 0,
+  };
+}