@oxy.so/bloom 2.10.0 → 2.12.0

package/lib/typescript/module/app-shell/AppShellBars.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 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 from 'react';
+/** The safe-area insets, or zeros outside a `SafeAreaProvider`. */
+export declare function useShellInsets(): {
+    top: number;
+    bottom: number;
+};
+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;
+}
+export declare const AppShellBottomBar: React.NamedExoticComponent<AppShellBottomBarProps>;
+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;
+}
+export declare const AppShellFloatingAction: React.NamedExoticComponent<AppShellFloatingActionProps>;
+export interface AppShellTopBarProps {
+    children: React.ReactNode;
+    doc: boolean;
+    testID?: string;
+}
+export declare const AppShellTopBar: React.NamedExoticComponent<AppShellTopBarProps>;
+//# sourceMappingURL=AppShellBars.d.ts.map

package/lib/typescript/module/app-shell/AppShellBars.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AppShellBars.d.ts","sourceRoot":"","sources":["../../../../src/app-shell/AppShellBars.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,KAA2B,MAAM,OAAO,CAAC;AAOhD,mEAAmE;AACnE,wBAAgB,cAAc,IAAI;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAOhE;AAaD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,qEAAqE;IACrE,GAAG,EAAE,OAAO,CAAC;IACb,oEAAoE;IACpE,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAyBD,eAAO,MAAM,iBAAiB,oDAAmC,CAAC;AAGlE,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,GAAG,EAAE,OAAO,CAAC;IACb,wFAAwF;IACxF,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,OAAO,GAAG,KAAK,CAAC;IAC3B,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAiCD,eAAO,MAAM,sBAAsB,yDAAwC,CAAC;AAG5E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B,GAAG,EAAE,OAAO,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAoBD,eAAO,MAAM,cAAc,iDAAgC,CAAC"}

package/lib/typescript/module/app-shell/AppShellHeader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AppShellHeader.d.ts","sourceRoot":"","sources":["../../../../src/app-shell/AppShellHeader.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAe,MAAM,OAAO,CAAC;AAQpC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAiFnD,eAAO,MAAM,cAAc,iDAAgC,CAAC"}
+{"version":3,"file":"AppShellHeader.d.ts","sourceRoot":"","sources":["../../../../src/app-shell/AppShellHeader.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAe,MAAM,OAAO,CAAC;AAQpC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAsFnD,eAAO,MAAM,cAAc,iDAAgC,CAAC"}

package/lib/typescript/module/app-shell/AppShellSplit.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 from 'react';
+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;
+}
+export declare const AppShellSplitPanes: React.NamedExoticComponent<AppShellSplitPanesProps>;
+//# sourceMappingURL=AppShellSplit.d.ts.map

package/lib/typescript/module/app-shell/AppShellSplit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AppShellSplit.d.ts","sourceRoot":"","sources":["../../../../src/app-shell/AppShellSplit.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAA8C,MAAM,OAAO,CAAC;AAOnE,MAAM,WAAW,uBAAuB;IACtC,IAAI,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IACvB,MAAM,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IACzB,IAAI,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IACvB,uCAAuC;IACvC,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,qEAAqE;IACrE,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;IACnB,kFAAkF;IAClF,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAoID,eAAO,MAAM,kBAAkB,qDAAoC,CAAC"}

package/lib/typescript/module/app-shell/constants.d.ts

@@ -0,0 +1,62 @@
+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 declare 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.
+     */
+    readonly 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.
+     */
+    readonly contentWidth: 600;
+    /** The second column's width, `dashboard` and `feed` alike. */
+    readonly 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.
+     */
+    readonly 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.
+     */
+    readonly dashboardGutter: 12;
+    readonly dashboardColumnGap: 16;
+    readonly gutter: 16;
+    /** `split`: the list pane's resting width, and the range a drag may reach. */
+    readonly listWidth: 360;
+    readonly listMinWidth: 280;
+    readonly listMaxWidth: 520;
+    /** `split`: the third (info) pane. */
+    readonly 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.
+     */
+    readonly splitFrom: "md";
+    /** `split`: the third pane needs the same headroom the aside does. */
+    readonly infoFrom: "xl";
+};
+/** A named tier or a literal width, in pixels. */
+export declare function breakpointPx(value: AppShellBreakpoint): number;
+//# sourceMappingURL=constants.d.ts.map

package/lib/typescript/module/app-shell/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../../src/app-shell/constants.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAClD;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB;IAC7B;;;;OAIG;;IAEH;;;;;OAKG;;IAEH,+DAA+D;;IAE/D;;;;;OAKG;;IAEH;;;;;;;OAOG;;;;IAIH,8EAA8E;;;;IAI9E,sCAAsC;;IAEtC;;;;OAIG;;IAEH,sEAAsE;;CAE9D,CAAC;AAEX,kDAAkD;AAClD,wBAAgB,YAAY,CAAC,KAAK,EAAE,kBAAkB,GAAG,MAAM,CAE9D"}

package/lib/typescript/module/app-shell/index.d.ts

@@ -1,9 +1,10 @@
 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 { AppShellDrawer, AppShellHeaderProps, AppShellMenuButtonProps, AppShellProps, NotificationBellProps, ProOfferCardProps, } from './types';
+export type { AppShellBarVisibility, AppShellBreakpoint, AppShellDrawer, AppShellPane, AppShellScroll, AppShellVariant, AppShellHeaderProps, AppShellMenuButtonProps, AppShellProps, NotificationBellProps, ProOfferCardProps, } from './types';
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/module/app-shell/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/app-shell/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,YAAY,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,YAAY,EACV,cAAc,EACd,mBAAmB,EACnB,uBAAuB,EACvB,aAAa,EACb,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/app-shell/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,YAAY,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,YAAY,EACV,qBAAqB,EACrB,kBAAkB,EAClB,cAAc,EACd,YAAY,EACZ,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,uBAAuB,EACvB,aAAa,EACb,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,SAAS,CAAC"}

package/lib/typescript/module/app-shell/layout.d.ts

@@ -0,0 +1,38 @@
+import { 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` and `canvas` are the other reductions: a split's 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), and a canvas is the viewport itself. Both resolve `document` to
+ * `fixed` (one screen) and honour `container` as-is.
+ */
+export declare function resolveScrollMode(variant: AppShellVariant, scroll: AppShellScroll): ScrollMode;
+/**
+ * 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 declare const documentRoot: WebCssStyle;
+/** Container mode: fill the parent, scroll inside. */
+export declare const containerRoot: WebCssStyle;
+/**
+ * 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 declare const fixedRoot: WebCssStyle;
+export declare function rootFrame(mode: ScrollMode): WebCssStyle;
+/**
+ * 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 declare function stickyRail(inset: number): WebCssStyle;
+//# sourceMappingURL=layout.d.ts.map

package/lib/typescript/module/app-shell/layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../../../src/app-shell/layout.ts"],"names":[],"mappings":"AAOA,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/D,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,WAAW,GAAG,OAAO,CAAC;AAE5D;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE,cAAc,GAAG,UAAU,CAQ9F;AAED;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,EAAE,WAA6D,CAAC;AAEzF,sDAAsD;AACtD,eAAO,MAAM,aAAa,EAAE,WAA6D,CAAC;AAE1F;;;GAGG;AACH,eAAO,MAAM,SAAS,EAAE,WAG6B,CAAC;AAEtD,wBAAgB,SAAS,CAAC,IAAI,EAAE,UAAU,GAAG,WAAW,CAEvD;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAQrD"}

package/lib/typescript/module/app-shell/types.d.ts

@@ -1,5 +1,6 @@
 import type { ReactNode } from 'react';
 import type { StyleProp, ViewStyle } from 'react-native';
+import type { ContentPanelFramedBreakpoint } from '../content-panel/types';
 import type { NotificationCenterItem, NotificationCenterTab } from '../notification-center/types';
 import type { SidebarProps } from '../sidebar/types';
 /**
@@ -10,13 +11,68 @@ import type { SidebarProps } from '../sidebar/types';
  *              rounds its corner to 32 as the rail scales in from 0.94
  */
 export type AppShellDrawer = 'overlay' | 'reveal';
+/**
+ * The layout SHAPE, all drawn by the same engine — the same nav, the same
+ * drawer, the same pinned regions, the same slots.
+ *
+ * - `dashboard` (default) — nav, then one fluid content column capped at
+ *   `contentMaxWidth`, with an optional `aside`. The shape this shell shipped
+ *   with; unchanged in every measurement.
+ * - `feed` — nav, then the routed content CENTRED in a reading column of
+ *   `contentWidth`, with the optional `aside` beside it and the pair centred in
+ *   what the nav leaves. Wrap the column in a `ContentPanel` with `panel` and
+ *   the page background reads as a gutter around it.
+ * - `split` — a list pane, a detail pane and an optional info pane, each
+ *   scrolling on its own, with a draggable divider. One screen, never a
+ *   document scroll (see `scroll`). Below `splitFrom` exactly one pane renders,
+ *   chosen by `pane`.
+ * - `focus` — a single centred column of `contentWidth` and NO nav: sign-in,
+ *   onboarding, a reader. It keeps the header, `topBar`, `bottomBar` and
+ *   `floatingAction` slots, so a sign-up flow still gets its footer CTA.
+ * - `canvas` — the content is the SCREEN: one edge-to-edge area with no reading
+ *   column, no max width and no padding, exactly one viewport tall, and the
+ *   chrome floats over it. A map, a board, an editor, a photo viewer. Each
+ *   region keeps its own inset (the nav is still a card with a gutter around
+ *   it) so only the canvas runs to the edge. Like `split`, it never scrolls the
+ *   document — the canvas owns its own panning and zooming.
+ */
+export type AppShellVariant = 'dashboard' | 'feed' | 'split' | 'focus' | 'canvas';
+/** Which single pane a `split` shell shows below `splitFrom`. */
+export type AppShellPane = 'list' | 'detail' | 'info';
+/** A tier from `BREAKPOINTS`, the one source of truth for widths. */
+/**
+ * Where a region changes shape: one of Bloom's named tiers, or a WIDTH IN
+ * PIXELS for an app whose own layout does not land on them — a feed whose side
+ * column earns its place at 990, a rail that goes in flow at 500. The named
+ * tiers stay the default vocabulary; a number is the escape hatch, resolved by
+ * `breakpointPx`.
+ */
+export type AppShellBreakpoint = 'sm' | 'md' | 'lg' | 'xl' | number;
+/** What scrolls the page. See `AppShellProps['scroll']`. */
+export type AppShellScroll = 'document' | 'container' | 'fixed';
+/**
+ * When a bar slot is drawn: `compact` (the default) only while the nav is a
+ * drawer — the phone case the slot exists for — or `always`, for a bar that is
+ * part of the app at every width (a player, a status strip).
+ */
+export type AppShellBarVisibility = 'compact' | 'always';
 export interface AppShellProps {
+    /**
+     * The layout shape. Defaults to `dashboard` — the behaviour this component
+     * had before variants existed, down to the pixel.
+     */
+    variant?: AppShellVariant;
     /**
      * The rail. Rendered in flow at `lg` and up (`sm` and up with
      * `variant: 'rail'`); below it, the same props drive the drawer (`mobile`,
      * and `flat` for `reveal`), always as the panel.
      */
-    sidebar?: Omit<SidebarProps, 'mobile' | 'onClose' | 'flat'>;
+    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.
+     */
     drawer?: AppShellDrawer;
     /**
      * Heading over the content. Optional: without it (and without `breadcrumb` /
@@ -32,6 +88,11 @@ export interface AppShellProps {
     /**
      * Replaces the whole header. Put an `AppShellMenuButton` in it to keep the
      * drawer reachable on narrow screens.
+     *
+     * `null` means NO header — the shell draws nothing at all, not even the
+     * menu button it would otherwise render for a drawer, because the page has
+     * said it owns that corner. Leave the prop off (or `undefined`) to get the
+     * default header.
      */
     header?: ReactNode;
     /**
@@ -44,8 +105,12 @@ export interface AppShellProps {
     /** The aside column's width. Defaults to 320. */
     asideWidth?: number;
     /** The breakpoint the aside sits beside the content from. Defaults to `xl` (1280). */
-    asideFrom?: 'md' | 'lg' | 'xl';
-    /** Below `asideFrom`: `stack` (default) renders it after the content, `hidden` drops it. */
+    asideFrom?: AppShellBreakpoint;
+    /**
+     * Below `asideFrom`: `stack` (default) renders it after the content, `hidden`
+     * drops it. `canvas` always drops it — the screen is the canvas, so there is
+     * no column underneath to stack into.
+     */
     asideCollapse?: 'stack' | 'hidden';
     children?: ReactNode;
     /** The content column's max width. Defaults to 1300. */
@@ -70,7 +135,99 @@ export interface AppShellProps {
      *   so the page owns its own scrolling — a chat, a map, a board. On web the
      *   frame is `100dvh`; on native it fills its parent.
      */
-    scroll?: 'document' | 'container' | 'fixed';
+    scroll?: AppShellScroll;
+    /**
+     * `feed` / `focus`: the reading column's width. Default 600 — the measure a
+     * single column of body text stays readable at. It is a MAXIMUM on a narrow
+     * screen: the column shrinks to the space it has rather than overflowing.
+     */
+    contentWidth?: 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
+     * pages do not move) and 16 for the other variants, where one number drives
+     * both.
+     */
+    gutter?: number;
+    /**
+     * The width the nav sits in FLOW from; below it the same nav is a drawer.
+     * Defaults to the tier the sidebar's own variant implies — `sm` for a rail
+     * (80px fits early), `lg` for the full panel — and to `sm` whenever
+     * `navExpandedFrom` is set, because below that tier the nav IS a rail.
+     */
+    navFrom?: AppShellBreakpoint;
+    /**
+     * Icons below, labels from here up: the shell swaps `sidebar.variant` between
+     * `rail` and `panel` at this width. Unset (the default) the sidebar keeps
+     * whatever variant it was given at every width.
+     */
+    navExpandedFrom?: AppShellBreakpoint;
+    /**
+     * `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.
+     */
+    panel?: boolean;
+    /** Forwarded to that `ContentPanel`: the width it starts being framed at. */
+    framedFrom?: ContentPanelFramedBreakpoint;
+    /** `split`: the first pane. `children` is the detail pane beside it. */
+    list?: ReactNode;
+    /** `split`: an optional third pane, from `infoFrom`. */
+    info?: ReactNode;
+    /** `split`: which single pane renders below `splitFrom`. Default `list`. */
+    pane?: AppShellPane;
+    /** `split`: the list pane's resting width (360); a drag moves it in range. */
+    listWidth?: number;
+    /** `split`: the range a drag may reach. Defaults 280 and 520. */
+    listMinWidth?: number;
+    listMaxWidth?: number;
+    /** `split`: reports the width a drag settled on. */
+    onListWidthChange?: (width: number) => void;
+    /** `split`: the info pane's width. Default 320. */
+    infoWidth?: number;
+    /** `split`: the width two panes fit from. Default `md` (768). */
+    splitFrom?: AppShellBreakpoint;
+    /** `split`: the width the third pane fits from. Default `xl` (1280). */
+    infoFrom?: AppShellBreakpoint;
+    /** `split`: whether the divider drags. Default `true`. */
+    resizable?: boolean;
+    /** `split`: names the divider. Default `"Resize panes"`. */
+    resizeLabel?: string;
+    /**
+     * `split`: the shell gives each pane its own `ScrollView` (default). Turn it
+     * off when the pane's own content scrolls — a `FlatList`, a virtualizer —
+     * rather than nesting two scrollers.
+     */
+    paneScroll?: boolean;
+    /**
+     * The phone header: a sibling ABOVE the shell's columns, spanning it edge to
+     * edge, pinned to the top (sticky with document scroll). Nothing a consumer
+     * writes needs `position: fixed` or a negative margin to be a top bar.
+     *
+     * `header` is the in-column page heading and is unaffected; a shell may have
+     * both. NOT drawn under `drawer="reveal"`: that drawer slides the whole page
+     * 272px sideways, and a bar pinned to the frame would stay behind while the
+     * page it belongs to left it — so `reveal` keeps its in-column `header`.
+     */
+    topBar?: ReactNode;
+    /** `compact` (default): only while the nav is a drawer. */
+    topBarVisibility?: AppShellBarVisibility;
+    /**
+     * The bottom bar: pinned to the bottom of the viewport (or of the frame when
+     * the shell does not own the page), with the bottom safe-area inset applied
+     * as its own padding. The content column reserves its MEASURED height, so the
+     * last item is never hidden behind it.
+     */
+    bottomBar?: ReactNode;
+    /** `compact` (default): only while the nav is a drawer. */
+    bottomBarVisibility?: AppShellBarVisibility;
+    /** The compose/FAB corner — above the bottom bar when there is one. */
+    floatingAction?: ReactNode;
+    /** Which corner. Default `end` (the right in a left-to-right layout). */
+    floatingActionPlacement?: 'start' | 'end';
     style?: StyleProp<ViewStyle>;
     testID?: string;
 }
@@ -89,6 +246,12 @@ export interface AppShellHeaderProps {
     onMenuPress?: () => void;
     /** Swaps the hamburger for a close glyph while the drawer is open. */
     menuOpen?: boolean;
+    /**
+     * Whether the hamburger has anything to open. `AppShell` passes its own
+     * answer, taken from the shell's MEASURED width and `navFrom`; standalone the
+     * header falls back to the window being narrower than `lg`.
+     */
+    showMenu?: boolean;
     style?: StyleProp<ViewStyle>;
     testID?: string;
 }

package/lib/typescript/module/app-shell/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/app-shell/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/app-shell/types.ts"],"names":[],"mappings":"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"}

package/lib/typescript/module/app-shell/use-shell-width.d.ts

@@ -0,0 +1,25 @@
+import type { LayoutChangeEvent } from 'react-native';
+/**
+ * The width `AppShell` lays itself out from: its OWN measured box, falling back
+ * to the window until the first layout arrives.
+ *
+ * The shell is usually the page, so the two agree — but not always. A shell
+ * mounted in a preview pane, in one half of a split view, or inside a desktop
+ * app's own chrome is narrower than the window, and a window-width decision
+ * puts three columns into a 480px box. Measuring the shell is the only reading
+ * that is right in both cases.
+ *
+ * The fallback is the window rather than `0` on purpose: the first paint would
+ * otherwise be a phone layout for every shell, and the correction would be a
+ * visible reflow on every page load. A shell that spans the page therefore
+ * renders correctly on frame one, and only an embedded one pays a single
+ * layout pass.
+ *
+ * (`useContainerWidth` lives in `listing-details/` today. If it moves to
+ * `src/hooks/use-container-width.ts` this import is the only line to change.)
+ */
+export declare function useShellWidth(): {
+    width: number;
+    onLayout: (event: LayoutChangeEvent) => void;
+};
+//# sourceMappingURL=use-shell-width.d.ts.map

package/lib/typescript/module/app-shell/use-shell-width.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-shell-width.d.ts","sourceRoot":"","sources":["../../../../src/app-shell/use-shell-width.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAKtD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,IAAI;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAA;CAAE,CAI/F"}

package/lib/typescript/module/avatar/Avatar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Avatar.d.ts","sourceRoot":"","sources":["../../../../src/avatar/Avatar.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA0C,MAAM,OAAO,CAAC;AAsB/D,OAAO,KAAK,EAAE,WAAW,EAAqC,MAAM,SAAS,CAAC;AAga9E,eAAO,MAAM,MAAM,yCAAwB,CAAC"}
+{"version":3,"file":"Avatar.d.ts","sourceRoot":"","sources":["../../../../src/avatar/Avatar.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA0C,MAAM,OAAO,CAAC;AAuB/D,OAAO,KAAK,EAAE,WAAW,EAAqC,MAAM,SAAS,CAAC;AA+Z9E,eAAO,MAAM,MAAM,yCAAwB,CAAC"}

package/lib/typescript/module/avatar/initials.d.ts

@@ -10,14 +10,23 @@ import type { AvatarColor, AvatarSizeToken } from './types';
  *   md     32   headline-semibold (16/22)
  *   lg     36   18/24 semibold
  *
- *   tint      disc                 initials
- *   neutral   neutral-300          text-secondary (neutral-500)
+ *   tint      disc                 initials (preferred stop)
+ *   neutral   neutral-300          neutral-500      ← the neutral ramp
  *             (dark: neutral-800)
  *   blue      blue-300             blue-900         ← theme `primary`
  *   lime      lime-200             lime-700         ← theme `success`
  *   pink      pink-200             pink-500         ← theme `negative`
  *
- * The hue tints are not repainted in dark mode.
+ * The hue tints are not repainted in dark mode — the DISC is the same colour in
+ * both, so only the letter has to move, and {@link legibleStop} moves it.
+ *
+ * The preferred stop is a preference, not the answer. A tint's ramp is rebuilt
+ * around a THEME role whose lightness moves with the mode, so a stop pair chosen
+ * in light can collapse in dark: `pink` measured **1.24:1** there
+ * (`#ffb4ab` on `#ecd8d6`) because dark `negative` is a bright red and the 500
+ * stop went pale, `lime` 4.29:1 and `neutral` 3.19:1 — and the name hash sends
+ * a quarter of all fallback avatars to the worst of them. The disc keeps its
+ * hue; the letter walks outward along its own ramp until it clears AA.
  */
 export declare const AVATAR_SIZES: Record<AvatarSizeToken, number>;
 /** A numeric size, or a rung resolved to its pixels. */

package/lib/typescript/module/avatar/initials.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"initials.d.ts","sourceRoot":"","sources":["../../../../src/avatar/initials.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAM9C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE5D;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,eAAe,EAAE,MAAM,CAKxD,CAAC;AAEF,wDAAwD;AACxD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,GAAG,MAAM,CAGpF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAW1D;AA8BD,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,4EAA4E;AAC5E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,GAAG,UAAU,CAuB9E;AAID,mDAAmD;AACnD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAM3D;AAED,gEAAgE;AAChE,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAK/C"}
+{"version":3,"file":"initials.d.ts","sourceRoot":"","sources":["../../../../src/avatar/initials.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAe9C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,eAAe,EAAE,MAAM,CAKxD,CAAC;AAEF,wDAAwD;AACxD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,GAAG,MAAM,CAGpF;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAW1D;AA8BD,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AA6BD,4EAA4E;AAC5E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,GAAG,UAAU,CAwB9E;AAID,mDAAmD;AACnD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAM3D;AAED,gEAAgE;AAChE,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAK/C"}

package/lib/typescript/module/badge/Badge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Badge.d.ts","sourceRoot":"","sources":["../../../../src/badge/Badge.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAwB,MAAM,OAAO,CAAC;AAS7C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AA2K1C,eAAO,MAAM,KAAK,wCAAuB,CAAC"}
+{"version":3,"file":"Badge.d.ts","sourceRoot":"","sources":["../../../../src/badge/Badge.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAwB,MAAM,OAAO,CAAC;AAS7C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAgN1C,eAAO,MAAM,KAAK,wCAAuB,CAAC"}

package/lib/typescript/module/badge/index.d.ts

@@ -1,3 +1,5 @@
 export { Badge } from './Badge';
-export type { BadgeProps, BadgeSize, BadgePlacement } from './types';
+export { BADGE_GEOMETRY, resolveBadgePaint } from './shared';
+export type { BadgeGeometry, BadgePaint } from './shared';
+export type { BadgeProps, BadgeSize, BadgeVariant, BadgeIcon, BadgePlacement } from './types';
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/module/badge/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/badge/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/badge/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC7D,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC1D,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC"}

package/lib/typescript/module/badge/shared.d.ts

@@ -0,0 +1,71 @@
+import { type AccentTone } from '../theme/accent-colors';
+import type { Theme } from '../theme/types';
+import type { TypeScaleVariant } from '../typography/scale';
+import type { BadgeSize, BadgeVariant } from './types';
+/**
+ * `Badge`'s rungs and paint, pure so a gate can walk the whole preset x mode
+ * matrix without rendering.
+ *
+ * TWO FAMILIES OF RUNG, and the difference is not decoration:
+ *
+ *   COUNTER   small / medium / large — sized to a DIGIT. `minWidth` equals the
+ *             height so "3" stays a circle rather than a pill narrower than it
+ *             is tall, and the pill never shrinks: it is a fixed token in the
+ *             row it sits in.
+ *   LABEL     `label-small` / `label-medium` — sized to a WORD, with the side
+ *             padding a word needs (8 / 10 rather than 4) and a leading icon
+ *             slot. These SHRINK and truncate, because a two-word status in a
+ *             narrow card must yield before the card's title does.
+ *
+ * The label rungs are where the housing badges live — `OfferingBadge` and the
+ * listing status pill are presets over them rather than two more copies of this
+ * geometry.
+ *
+ *                   height  padding-x  icon  gap  text
+ *   small           17      4          10    2    caption-2-semibold
+ *   medium          18      4          11    2    caption-1-semibold  ← default
+ *   large           24      6          14    4    body-semibold
+ *   label-small     20      8          12    4    caption-1-semibold
+ *   label-medium    24      10         14    4    body-2-semibold
+ */
+export interface BadgeGeometry {
+    height: number;
+    type: TypeScaleVariant;
+    /** Side padding. An icon tucks the LEADING side in by 2, optically. */
+    paddingHorizontal: number;
+    /** The leading icon's box. */
+    icon: number;
+    /** Between the icon and the label. */
+    gap: number;
+    /** Standalone status dot: tint halo around a solid centre. */
+    dotSize: number;
+    halo: number;
+    core: number;
+    /**
+     * `true` for the rungs sized to a word: they shrink and truncate. `false` for
+     * the counter rungs, which pin `minWidth` to the height and never shrink.
+     */
+    word: boolean;
+}
+export declare const BADGE_GEOMETRY: Readonly<Record<BadgeSize, BadgeGeometry>>;
+export interface BadgePaint {
+    background: string;
+    /** Label AND icon. One colour: a badge's icon is a glyph of its label, not a second accent. */
+    foreground: string;
+    border: string;
+    /** `bloomShadowStyle` step, or `null` for a flat badge. */
+    shadow: 's' | null;
+}
+/**
+ * The surface, label and border for one tone at one loudness.
+ *
+ *   solid/subtle/outlined   the shared accent recipe, unchanged — the pairs the
+ *                           colour policy gates at AA, so nothing is derived here
+ *   onMedia                 a neutral-50 pill with a neutral-900 label and
+ *                           shadow-s, THE SAME IN BOTH MODES and ignoring `tone`:
+ *                           the photograph under it does not change with the
+ *                           theme, so a badge that followed the mode would go
+ *                           dark-on-dark over half the images in the library
+ */
+export declare function resolveBadgePaint(theme: Theme, tone: AccentTone, variant: BadgeVariant): BadgePaint;
+//# sourceMappingURL=shared.d.ts.map