@dloizides/ui-nav 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -1,45 +1,90 @@
-# Changelog
-
-## 1.3.0
-
-Give the `NavBar` the v1 `.gn-links` look + a full accessibility pass (and extend the
-same a11y bar to `Sidebar`/`Topbar`).
-
-**Look & hover (NavBar).** Each link is a rounded-pill target with the v1 hover
-affordance — muted at rest, and on HOVER the text brightens to full contrast while a
-subtle rounded-pill background appears; the ACTIVE link is a solid accent pill. All
-theme-driven (rest = `textSecondary`, hover text = `text`, hover bg = `surfaceElevated`,
-active/ring = `palette.primary`). Hover/focus are web-only (`onHoverIn/Out`, `onFocus/Blur`
-via `Pressable`); native stays at the rest style. The hover cross-fade is cheap CSS and is
-disabled under `prefers-reduced-motion: reduce` (new `useReducedMotion`). Backwards
-compatible — the hover pill is the default (aml-v2 is the only `NavBar` consumer) and the
-brand/right slots, responsive hamburger collapse, and `containerStyle` width behaviour are
-unchanged.
-
-**Accessibility.** NavBar toggle now carries `aria-controls` pointing at the collapsible
-links region (id via `nativeID`), keeps `aria-expanded`, and gains a themed keyboard focus
-ring; links keep `aria-current="page"` + `role="link"` and gain a focus ring; link/toggle
-touch targets are now ≥44×44. `Sidebar` leaves gain `aria-current="page"` + a focus ring;
-`Topbar` action buttons gain a focus ring (new internal `FocusableTouchable`). Focus rings
-never remove the outline without a themed replacement.
-
-## 1.2.0
-
-Add `NavBar` — a config-driven **horizontal top navigation bar**, the top-bar
-counterpart to `Sidebar`. It renders the same caller-supplied `NavItem[]` as inline
-links across the top (brand left slot + inline links + free-form right slot), with
-an active-link highlight (`aria-current="page"`) and a responsive collapse to a
-hamburger toggle below a configurable breakpoint (`collapseBelow`, default `760`) —
-mirroring the v1 AML console `.global-nav`. Theme-driven (UiProvider colours),
-`role="navigation"` landmark, keyboard-operable links. Purely additive: `Sidebar`,
-`Topbar`, `AppShell`, and the role-gating helpers are unchanged. New `NAV_TEST_IDS`
-entries `navBarToggle` / `navBarLinks`.
-
-## 1.0.0
-
-Initial release. `Sidebar` (leaf + expandable items, active-route highlight, header/footer
-slots), `Topbar` (logo/language/notification/user/account/logout slots), and the
-`accessibleNavItems` / `roleRoutesToNavItems` role-gating helpers (reusing
-`resolveAccessibleRoutes` from `@dloizides/auth-web`). Chrome + metrics ported verbatim from
-the byte-identical erevna-web / katalogos-web nav twins; every colour reads from the
-`@dloizides/ui-feedback` UiProvider theme.
+# Changelog
+
+## 1.5.0
+
+Make the `AppShell` back-office `sidebar` layout **responsive** — a mobile drawer.
+
+The `sidebar` slot (1.4.0) always rendered a persistent fixed-width left rail in a
+`flexDirection:'row'` body with no width breakpoint, so below ~768px the content column
+starved (headings wrapped a character per line, inputs truncated) — the merchant admin was
+unusable on a phone. Now `AppShell` reads `useWindowDimensions`:
+
+- **Desktop (≥768px): IDENTICAL to 1.4.0** — the persistent rail + row layout, untouched.
+  Purely additive; no consuming product's desktop layout changes.
+- **Below 768px:** the rail is not rendered beside the content; instead a **hamburger**
+  (in the header) opens the same `Sidebar` as an overlay **drawer** (a tap-to-close scrim +
+  a left panel) and the content takes the full width. The drawer closes on a scrim tap and
+  on a nav-item press (web: a bubbled click on a `role="button"` / link inside the panel).
+
+Accessibility: the hamburger has a testID + `accessibilityLabel` + `accessibilityHint` and a
+themed focus ring; the drawer panel is `role="dialog"` `aria-modal`; the scrim is a labelled
+button. New optional prop `mobileMenu?: Partial<DrawerLabels>` supplies pre-localized
+open/close labels (English defaults otherwise — this package has no i18n). New testID
+suffixes: `-menu-toggle`, `-drawer`, `-drawer-scrim`.
+
+**Backwards compatible.** No breaking prop changes — consumers pass the same `sidebar` slot.
+Omit `sidebar` and the tree is byte-identical to 1.4.0 (erevna / katalogos / kefi untouched).
+Only a `sidebar` consumer on a narrow viewport sees the drawer. Pinned by tests asserting the
+rail is present on desktop and absent (hamburger present) on a narrow viewport.
+
+## 1.4.0
+
+Add an optional **`sidebar`** slot to `AppShell` — the back-office layout.
+
+`AppShell` could only stack vertically (header → nav strip → banner → scrolling content),
+so a product with a persistent LEFT RAIL (Agora's merchant admin: products / categories /
+coupons / settings) had to hand-compose `Topbar` + `Sidebar` + a `ScrollView` row and give
+up the shell's auth gate and loading/error/forbidden state cards. Supplying `sidebar` now
+lays the body out as a ROW — the rail on the left, the width-disciplined scrolling content
+column on the right — while every existing feature (gate, state cards, `width`,
+`chromeAlignment`) keeps working.
+
+The new region is exposed as `` `${testID}${APP_SHELL_SUFFIX.sidebar}` `` (`-sidebar`).
+
+**Backwards compatible.** Omit `sidebar` and the render tree is byte-identical to 1.3.0 —
+erevna / katalogos / kefi / aml-v2 are untouched. Pinned by a test asserting no `-sidebar`
+region exists when the slot is omitted.
+
+## 1.3.0
+
+Give the `NavBar` the v1 `.gn-links` look + a full accessibility pass (and extend the
+same a11y bar to `Sidebar`/`Topbar`).
+
+**Look & hover (NavBar).** Each link is a rounded-pill target with the v1 hover
+affordance — muted at rest, and on HOVER the text brightens to full contrast while a
+subtle rounded-pill background appears; the ACTIVE link is a solid accent pill. All
+theme-driven (rest = `textSecondary`, hover text = `text`, hover bg = `surfaceElevated`,
+active/ring = `palette.primary`). Hover/focus are web-only (`onHoverIn/Out`, `onFocus/Blur`
+via `Pressable`); native stays at the rest style. The hover cross-fade is cheap CSS and is
+disabled under `prefers-reduced-motion: reduce` (new `useReducedMotion`). Backwards
+compatible — the hover pill is the default (aml-v2 is the only `NavBar` consumer) and the
+brand/right slots, responsive hamburger collapse, and `containerStyle` width behaviour are
+unchanged.
+
+**Accessibility.** NavBar toggle now carries `aria-controls` pointing at the collapsible
+links region (id via `nativeID`), keeps `aria-expanded`, and gains a themed keyboard focus
+ring; links keep `aria-current="page"` + `role="link"` and gain a focus ring; link/toggle
+touch targets are now ≥44×44. `Sidebar` leaves gain `aria-current="page"` + a focus ring;
+`Topbar` action buttons gain a focus ring (new internal `FocusableTouchable`). Focus rings
+never remove the outline without a themed replacement.
+
+## 1.2.0
+
+Add `NavBar` — a config-driven **horizontal top navigation bar**, the top-bar
+counterpart to `Sidebar`. It renders the same caller-supplied `NavItem[]` as inline
+links across the top (brand left slot + inline links + free-form right slot), with
+an active-link highlight (`aria-current="page"`) and a responsive collapse to a
+hamburger toggle below a configurable breakpoint (`collapseBelow`, default `760`) —
+mirroring the v1 AML console `.global-nav`. Theme-driven (UiProvider colours),
+`role="navigation"` landmark, keyboard-operable links. Purely additive: `Sidebar`,
+`Topbar`, `AppShell`, and the role-gating helpers are unchanged. New `NAV_TEST_IDS`
+entries `navBarToggle` / `navBarLinks`.
+
+## 1.0.0
+
+Initial release. `Sidebar` (leaf + expandable items, active-route highlight, header/footer
+slots), `Topbar` (logo/language/notification/user/account/logout slots), and the
+`accessibleNavItems` / `roleRoutesToNavItems` role-gating helpers (reusing
+`resolveAccessibleRoutes` from `@dloizides/auth-web`). Chrome + metrics ported verbatim from
+the byte-identical erevna-web / katalogos-web nav twins; every colour reads from the
+`@dloizides/ui-feedback` UiProvider theme.

package/dist/index.d.mts

@@ -195,6 +195,33 @@ interface NavBarProps {
 }
 declare const NavBar: ({ items, pathname, onNavigate, regionLabel, navigateHint, brand, right, menuLabel, menuHint, renderMenuIcon, collapseBelow, containerStyle, }: NavBarProps) => React.ReactElement;
 
+/**
+ * MobileDrawer — the below-the-breakpoint face of `AppShell`'s back-office
+ * `sidebar` layout. On a narrow viewport (<768px) the persistent left rail would
+ * starve the content column, so instead of the rail we render a hamburger toggle
+ * (`MenuToggle`) in the header and slide the same `Sidebar` in as an overlay
+ * drawer (a scrim + a left panel). The drawer closes on a scrim tap and on any
+ * nav-item press inside the panel (web: a bubbled click on a `role="button"` /
+ * link element). Desktop is untouched — AppShell never mounts this above 768px.
+ *
+ * Contract discipline (same as the rest of `@dloizides/ui-nav`): NO FM / router /
+ * store imports. Labels are pre-localized strings (English defaults, overridable
+ * by the consumer via `AppShell`'s `mobileMenu` prop); every colour is read from
+ * the `@dloizides/ui-feedback` UiProvider theme.
+ */
+
+/** Pre-localized labels for the drawer's hamburger + scrim. */
+interface DrawerLabels {
+    /** Accessible name of the hamburger that opens the drawer. */
+    openLabel: string;
+    /** Accessible hint of the hamburger that opens the drawer. */
+    openHint: string;
+    /** Accessible name of the scrim (tap to close). */
+    closeLabel: string;
+    /** Accessible hint of the scrim (tap to close). */
+    closeHint: string;
+}
+
 /** Content-width policy: a capped column, optionally wider past a viewport breakpoint, or full-bleed. */
 type AppShellWidth = {
     max: number;
@@ -218,6 +245,13 @@ declare function useContentMaxWidth(width: AppShellWidth): number | 'full';
  * (pending spinner / redirect-when-unauthenticated) and page state cards
  * (loading / error / forbidden).
  *
+ * A BACK-OFFICE variant is supported via the optional `sidebar` slot (added for
+ * Agora's merchant admin): supply a `<Sidebar>` and the body below the header /
+ * nav / banner becomes a ROW — a persistent left rail beside the scrolling
+ * content column — instead of the default single vertical stack. Omit `sidebar`
+ * and the render tree is byte-identical to before, so every existing consumer
+ * (erevna / katalogos / kefi) is untouched.
+ *
  * Contract discipline (same as the rest of `@dloizides/ui-nav`): NO FM, router,
  * or store imports. The app passes wired elements, pre-localized strings, and
  * callbacks; every colour is routed through the `@dloizides/ui-feedback` theme.
@@ -233,6 +267,23 @@ interface AppShellProps {
     header: React.ReactNode;
     /** Per-app nav region (kefi coral pills / erevna sidebar+drawer). */
     nav?: React.ReactNode;
+    /**
+     * Optional persistent LEFT RAIL (a `<Sidebar>`), for back-office surfaces. When
+     * supplied, the region below header/nav/banner lays out as a row: the rail on the
+     * left, the scrolling content column on the right. Omit for the default vertical
+     * stack — the tree is then byte-identical to the pre-`sidebar` AppShell.
+     *
+     * Responsive: at/under ~768px the persistent rail is REPLACED by a hamburger (in
+     * the header) that opens the same `sidebar` as an overlay drawer, so the content
+     * takes the full width. Desktop (≥768px) is unchanged. No effect without `sidebar`.
+     */
+    sidebar?: React.ReactNode;
+    /**
+     * Pre-localized labels for the mobile nav drawer (only used in the `sidebar`
+     * layout, below the breakpoint): the hamburger's open label/hint and the scrim's
+     * close label/hint. Optional — English defaults apply. NO i18n in this package.
+     */
+    mobileMenu?: Partial<DrawerLabels>;
     /** Banner slot (e.g. verification-pending). */
     banner?: React.ReactNode;
     /** Content-width policy. Defaults to full-bleed. */
@@ -261,7 +312,7 @@ interface AppShellProps {
     testID: string;
     children: React.ReactNode;
 }
-declare const AppShell: ({ header, nav, banner, width, contentPadding, chromeAlignment, gate, state, testID, children, }: AppShellProps) => React.ReactElement | null;
+declare const AppShell: ({ header, nav, sidebar, mobileMenu, banner, width, contentPadding, chromeAlignment, gate, state, testID, children, }: AppShellProps) => React.ReactElement | null;
 
 /**
  * Default testIDs for `@dloizides/ui-nav`. Kept as a small central map (mirrors
@@ -289,6 +340,14 @@ declare const APP_SHELL_SUFFIX: {
     readonly content: "-content";
     readonly header: "-header";
     readonly nav: "-nav";
+    /** The persistent left rail of the back-office layout (only when `sidebar` is supplied). */
+    readonly sidebar: "-sidebar";
+    /** Mobile hamburger that opens the nav drawer (back-office layout, below the breakpoint). */
+    readonly menuToggle: "-menu-toggle";
+    /** The mobile nav drawer panel (holds the `sidebar` slot when opened on a narrow viewport). */
+    readonly drawer: "-drawer";
+    /** The mobile nav drawer scrim (tap to close). */
+    readonly scrim: "-drawer-scrim";
     readonly banner: "-banner";
     readonly pending: "-pending";
     readonly loading: "-loading";

package/dist/index.d.ts

@@ -195,6 +195,33 @@ interface NavBarProps {
 }
 declare const NavBar: ({ items, pathname, onNavigate, regionLabel, navigateHint, brand, right, menuLabel, menuHint, renderMenuIcon, collapseBelow, containerStyle, }: NavBarProps) => React.ReactElement;
 
+/**
+ * MobileDrawer — the below-the-breakpoint face of `AppShell`'s back-office
+ * `sidebar` layout. On a narrow viewport (<768px) the persistent left rail would
+ * starve the content column, so instead of the rail we render a hamburger toggle
+ * (`MenuToggle`) in the header and slide the same `Sidebar` in as an overlay
+ * drawer (a scrim + a left panel). The drawer closes on a scrim tap and on any
+ * nav-item press inside the panel (web: a bubbled click on a `role="button"` /
+ * link element). Desktop is untouched — AppShell never mounts this above 768px.
+ *
+ * Contract discipline (same as the rest of `@dloizides/ui-nav`): NO FM / router /
+ * store imports. Labels are pre-localized strings (English defaults, overridable
+ * by the consumer via `AppShell`'s `mobileMenu` prop); every colour is read from
+ * the `@dloizides/ui-feedback` UiProvider theme.
+ */
+
+/** Pre-localized labels for the drawer's hamburger + scrim. */
+interface DrawerLabels {
+    /** Accessible name of the hamburger that opens the drawer. */
+    openLabel: string;
+    /** Accessible hint of the hamburger that opens the drawer. */
+    openHint: string;
+    /** Accessible name of the scrim (tap to close). */
+    closeLabel: string;
+    /** Accessible hint of the scrim (tap to close). */
+    closeHint: string;
+}
+
 /** Content-width policy: a capped column, optionally wider past a viewport breakpoint, or full-bleed. */
 type AppShellWidth = {
     max: number;
@@ -218,6 +245,13 @@ declare function useContentMaxWidth(width: AppShellWidth): number | 'full';
  * (pending spinner / redirect-when-unauthenticated) and page state cards
  * (loading / error / forbidden).
  *
+ * A BACK-OFFICE variant is supported via the optional `sidebar` slot (added for
+ * Agora's merchant admin): supply a `<Sidebar>` and the body below the header /
+ * nav / banner becomes a ROW — a persistent left rail beside the scrolling
+ * content column — instead of the default single vertical stack. Omit `sidebar`
+ * and the render tree is byte-identical to before, so every existing consumer
+ * (erevna / katalogos / kefi) is untouched.
+ *
  * Contract discipline (same as the rest of `@dloizides/ui-nav`): NO FM, router,
  * or store imports. The app passes wired elements, pre-localized strings, and
  * callbacks; every colour is routed through the `@dloizides/ui-feedback` theme.
@@ -233,6 +267,23 @@ interface AppShellProps {
     header: React.ReactNode;
     /** Per-app nav region (kefi coral pills / erevna sidebar+drawer). */
     nav?: React.ReactNode;
+    /**
+     * Optional persistent LEFT RAIL (a `<Sidebar>`), for back-office surfaces. When
+     * supplied, the region below header/nav/banner lays out as a row: the rail on the
+     * left, the scrolling content column on the right. Omit for the default vertical
+     * stack — the tree is then byte-identical to the pre-`sidebar` AppShell.
+     *
+     * Responsive: at/under ~768px the persistent rail is REPLACED by a hamburger (in
+     * the header) that opens the same `sidebar` as an overlay drawer, so the content
+     * takes the full width. Desktop (≥768px) is unchanged. No effect without `sidebar`.
+     */
+    sidebar?: React.ReactNode;
+    /**
+     * Pre-localized labels for the mobile nav drawer (only used in the `sidebar`
+     * layout, below the breakpoint): the hamburger's open label/hint and the scrim's
+     * close label/hint. Optional — English defaults apply. NO i18n in this package.
+     */
+    mobileMenu?: Partial<DrawerLabels>;
     /** Banner slot (e.g. verification-pending). */
     banner?: React.ReactNode;
     /** Content-width policy. Defaults to full-bleed. */
@@ -261,7 +312,7 @@ interface AppShellProps {
     testID: string;
     children: React.ReactNode;
 }
-declare const AppShell: ({ header, nav, banner, width, contentPadding, chromeAlignment, gate, state, testID, children, }: AppShellProps) => React.ReactElement | null;
+declare const AppShell: ({ header, nav, sidebar, mobileMenu, banner, width, contentPadding, chromeAlignment, gate, state, testID, children, }: AppShellProps) => React.ReactElement | null;
 
 /**
  * Default testIDs for `@dloizides/ui-nav`. Kept as a small central map (mirrors
@@ -289,6 +340,14 @@ declare const APP_SHELL_SUFFIX: {
     readonly content: "-content";
     readonly header: "-header";
     readonly nav: "-nav";
+    /** The persistent left rail of the back-office layout (only when `sidebar` is supplied). */
+    readonly sidebar: "-sidebar";
+    /** Mobile hamburger that opens the nav drawer (back-office layout, below the breakpoint). */
+    readonly menuToggle: "-menu-toggle";
+    /** The mobile nav drawer panel (holds the `sidebar` slot when opened on a narrow viewport). */
+    readonly drawer: "-drawer";
+    /** The mobile nav drawer scrim (tap to close). */
+    readonly scrim: "-drawer-scrim";
     readonly banner: "-banner";
     readonly pending: "-pending";
     readonly loading: "-loading";

package/dist/index.js

@@ -346,6 +346,14 @@ var APP_SHELL_SUFFIX = {
   content: "-content",
   header: "-header",
   nav: "-nav",
+  /** The persistent left rail of the back-office layout (only when `sidebar` is supplied). */
+  sidebar: "-sidebar",
+  /** Mobile hamburger that opens the nav drawer (back-office layout, below the breakpoint). */
+  menuToggle: "-menu-toggle",
+  /** The mobile nav drawer panel (holds the `sidebar` slot when opened on a narrow viewport). */
+  drawer: "-drawer",
+  /** The mobile nav drawer scrim (tap to close). */
+  scrim: "-drawer-scrim",
   banner: "-banner",
   pending: "-pending",
   loading: "-loading",
@@ -669,6 +677,82 @@ var NavBar = ({
     }
   );
 };
+var MOBILE_BREAKPOINT = 768;
+var SCRIM_COLOR = "rgba(0, 0, 0, 0.5)";
+var MENU_GLYPH2 = "\u2630";
+var MENU_MIN_TARGET = 44;
+var MENU_GLYPH_FONT_SIZE = 20;
+var MENU_TOGGLE_PADDING = 12;
+var DRAWER_Z_INDEX = 50;
+var NAV_ACTIVATABLE_SELECTOR = 'a, [role="button"], [role="link"]';
+var DEFAULT_DRAWER_LABELS = {
+  openLabel: "Menu",
+  openHint: "Open the navigation menu",
+  closeLabel: "Close menu",
+  closeHint: "Close the navigation menu"
+};
+var styles = reactNative.StyleSheet.create({
+  overlay: { ...reactNative.StyleSheet.absoluteFillObject, zIndex: DRAWER_Z_INDEX },
+  scrim: { ...reactNative.StyleSheet.absoluteFillObject, backgroundColor: SCRIM_COLOR },
+  panel: { position: "absolute", top: 0, bottom: 0, left: 0 },
+  menuToggle: {
+    minWidth: MENU_MIN_TARGET,
+    minHeight: MENU_MIN_TARGET,
+    alignItems: "center",
+    justifyContent: "center",
+    paddingHorizontal: MENU_TOGGLE_PADDING
+  },
+  menuToggleGlyph: { fontSize: MENU_GLYPH_FONT_SIZE, fontWeight: "700" }
+});
+var MenuToggle = ({ label, hint, onOpen, testID }) => {
+  const { theme } = uiFeedback.useUi();
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    FocusableTouchable,
+    {
+      accessibilityHint: hint,
+      accessibilityLabel: label,
+      ringColor: theme.palette.primary["500"],
+      style: styles.menuToggle,
+      testID,
+      onPress: onOpen,
+      children: /* @__PURE__ */ jsxRuntime.jsx(reactNative.Text, { style: [styles.menuToggleGlyph, { color: theme.colors.text }], children: MENU_GLYPH2 })
+    }
+  );
+};
+var MobileDrawer = ({
+  sidebar,
+  labels,
+  onClose,
+  drawerTestID,
+  scrimTestID
+}) => {
+  const panelRef = react.useRef(null);
+  react.useEffect(() => {
+    const node = panelRef.current;
+    if (node === null || typeof node.addEventListener !== "function") return void 0;
+    const handleClick = (event) => {
+      const target = event.target;
+      const onNavItem = target !== null && target.closest(NAV_ACTIVATABLE_SELECTOR) !== null;
+      if (onNavItem) onClose();
+    };
+    node.addEventListener("click", handleClick);
+    return () => node.removeEventListener("click", handleClick);
+  }, [onClose]);
+  return /* @__PURE__ */ jsxRuntime.jsxs(reactNative.View, { style: styles.overlay, children: [
+    /* @__PURE__ */ jsxRuntime.jsx(
+      reactNative.Pressable,
+      {
+        accessibilityHint: labels.closeHint,
+        accessibilityLabel: labels.closeLabel,
+        accessibilityRole: "button",
+        style: styles.scrim,
+        testID: scrimTestID,
+        onPress: onClose
+      }
+    ),
+    /* @__PURE__ */ jsxRuntime.jsx(reactNative.View, { ref: panelRef, "aria-modal": true, role: "dialog", style: styles.panel, testID: drawerTestID, children: sidebar })
+  ] });
+};
 function resolveContentMaxWidth(width, viewport) {
   if (width === "full") return "full";
   const wideMinViewport = width.wideMinViewport ?? Number.POSITIVE_INFINITY;
@@ -686,11 +770,16 @@ var CARD_BORDER_WIDTH = 1;
 var CARD_TITLE_FONT_SIZE = 16;
 var CARD_MESSAGE_FONT_SIZE = 14;
 var CARD_TITLE_MARGIN_BOTTOM = 8;
-var styles = reactNative.StyleSheet.create({
+var styles2 = reactNative.StyleSheet.create({
   root: { flex: 1 },
   centerFill: { flex: 1, justifyContent: "center", alignItems: "center" },
   scroll: { flex: 1 },
   scrollContent: { flexGrow: 1 },
+  // Mobile back-office header: the hamburger sits inline before the header slot.
+  headerRow: { flexDirection: "row", alignItems: "center" },
+  headerFill: { flex: 1 },
+  // Back-office layout: a persistent left rail beside the scrolling content column.
+  bodyRow: { flex: 1, flexDirection: "row" },
   columnFull: { flex: 1 },
   columnCapped: { flex: 1, width: "100%", alignSelf: "center" },
   // Non-flex variant used to cap the nav strip's inner content to the content
@@ -714,11 +803,11 @@ function MessageCard({
   return /* @__PURE__ */ jsxRuntime.jsxs(
     reactNative.View,
     {
-      style: [styles.card, { backgroundColor: colors.surface, borderColor: accentColor }],
+      style: [styles2.card, { backgroundColor: colors.surface, borderColor: accentColor }],
       testID,
       children: [
-        /* @__PURE__ */ jsxRuntime.jsx(reactNative.Text, { style: [styles.cardTitle, { color: accentColor }], children: message.titleText }),
-        /* @__PURE__ */ jsxRuntime.jsx(reactNative.Text, { style: [styles.cardMessage, { color: colors.textSecondary }], children: message.messageText })
+        /* @__PURE__ */ jsxRuntime.jsx(reactNative.Text, { style: [styles2.cardTitle, { color: accentColor }], children: message.titleText }),
+        /* @__PURE__ */ jsxRuntime.jsx(reactNative.Text, { style: [styles2.cardMessage, { color: colors.textSecondary }], children: message.messageText })
       ]
     }
   );
@@ -732,12 +821,14 @@ function useContentBody(state, children, testID) {
   if (state?.error)
     return /* @__PURE__ */ jsxRuntime.jsx(MessageCard, { accentColor: errorColor, message: state.error, testID: `${testID}${APP_SHELL_SUFFIX.error}` });
   if (state?.loading === true)
-    return /* @__PURE__ */ jsxRuntime.jsx(reactNative.View, { style: styles.centerFill, testID: `${testID}${APP_SHELL_SUFFIX.loading}`, children: /* @__PURE__ */ jsxRuntime.jsx(reactNative.ActivityIndicator, { color: primary, size: "large" }) });
+    return /* @__PURE__ */ jsxRuntime.jsx(reactNative.View, { style: styles2.centerFill, testID: `${testID}${APP_SHELL_SUFFIX.loading}`, children: /* @__PURE__ */ jsxRuntime.jsx(reactNative.ActivityIndicator, { color: primary, size: "large" }) });
   return children;
 }
 var AppShell = ({
   header,
   nav,
+  sidebar,
+  mobileMenu,
   banner,
   width = "full",
   contentPadding = DEFAULT_CONTENT_PADDING,
@@ -751,28 +842,65 @@ var AppShell = ({
   const primary = theme.palette.primary["500"];
   const maxWidth = useContentMaxWidth(width);
   const body = useContentBody(state, children, testID);
+  const { width: viewportWidth } = reactNative.useWindowDimensions();
+  const isNarrow = viewportWidth < MOBILE_BREAKPOINT;
+  const useDrawer = sidebar !== void 0 && isNarrow;
+  const [drawerOpen, setDrawerOpen] = react.useState(false);
+  const openDrawer = react.useCallback(() => setDrawerOpen(true), []);
+  const closeDrawer = react.useCallback(() => setDrawerOpen(false), []);
+  react.useEffect(() => {
+    if (!isNarrow && drawerOpen) setDrawerOpen(false);
+  }, [isNarrow, drawerOpen]);
+  const drawerLabels = { ...DEFAULT_DRAWER_LABELS, ...mobileMenu };
   const isUnauthenticated = gate !== void 0 && !gate.pending && !gate.authenticated;
   react.useEffect(() => {
     if (isUnauthenticated && gate !== void 0) gate.onRedirect();
   }, [isUnauthenticated, gate]);
   if (gate?.pending === true)
-    return /* @__PURE__ */ jsxRuntime.jsx(reactNative.View, { style: [styles.root, styles.centerFill, { backgroundColor: theme.colors.background }], testID: `${testID}${APP_SHELL_SUFFIX.pending}`, children: /* @__PURE__ */ jsxRuntime.jsx(reactNative.ActivityIndicator, { color: primary, size: "large" }) });
+    return /* @__PURE__ */ jsxRuntime.jsx(reactNative.View, { style: [styles2.root, styles2.centerFill, { backgroundColor: theme.colors.background }], testID: `${testID}${APP_SHELL_SUFFIX.pending}`, children: /* @__PURE__ */ jsxRuntime.jsx(reactNative.ActivityIndicator, { color: primary, size: "large" }) });
   if (isUnauthenticated) return null;
-  const columnStyle = maxWidth === "full" ? styles.columnFull : [styles.columnCapped, { maxWidth }];
-  const navInnerStyle = chromeAlignment === "content" && maxWidth !== "full" ? [styles.chromeCapped, { maxWidth, paddingHorizontal: contentPadding }] : void 0;
-  return /* @__PURE__ */ jsxRuntime.jsxs(reactNative.View, { style: [styles.root, { backgroundColor: theme.colors.background }], testID, children: [
-    /* @__PURE__ */ jsxRuntime.jsx(reactNative.View, { testID: `${testID}${APP_SHELL_SUFFIX.header}`, children: header }),
+  const columnStyle = maxWidth === "full" ? styles2.columnFull : [styles2.columnCapped, { maxWidth }];
+  const navInnerStyle = chromeAlignment === "content" && maxWidth !== "full" ? [styles2.chromeCapped, { maxWidth, paddingHorizontal: contentPadding }] : void 0;
+  const scroller = /* @__PURE__ */ jsxRuntime.jsx(
+    reactNative.ScrollView,
+    {
+      contentContainerStyle: [styles2.scrollContent, { padding: contentPadding }],
+      style: styles2.scroll,
+      testID: `${testID}${APP_SHELL_SUFFIX.content}`,
+      children: /* @__PURE__ */ jsxRuntime.jsx(reactNative.View, { style: columnStyle, children: body })
+    }
+  );
+  const headerRegion = useDrawer ? /* @__PURE__ */ jsxRuntime.jsxs(reactNative.View, { style: styles2.headerRow, testID: `${testID}${APP_SHELL_SUFFIX.header}`, children: [
+    /* @__PURE__ */ jsxRuntime.jsx(
+      MenuToggle,
+      {
+        hint: drawerLabels.openHint,
+        label: drawerLabels.openLabel,
+        testID: `${testID}${APP_SHELL_SUFFIX.menuToggle}`,
+        onOpen: openDrawer
+      }
+    ),
+    /* @__PURE__ */ jsxRuntime.jsx(reactNative.View, { style: styles2.headerFill, children: header })
+  ] }) : /* @__PURE__ */ jsxRuntime.jsx(reactNative.View, { testID: `${testID}${APP_SHELL_SUFFIX.header}`, children: header });
+  const showRail = sidebar !== void 0 && !isNarrow;
+  return /* @__PURE__ */ jsxRuntime.jsxs(reactNative.View, { style: [styles2.root, { backgroundColor: theme.colors.background }], testID, children: [
+    headerRegion,
     nav !== void 0 ? /* @__PURE__ */ jsxRuntime.jsx(reactNative.View, { testID: `${testID}${APP_SHELL_SUFFIX.nav}`, children: navInnerStyle !== void 0 ? /* @__PURE__ */ jsxRuntime.jsx(reactNative.View, { style: navInnerStyle, children: nav }) : nav }) : null,
     banner !== void 0 ? /* @__PURE__ */ jsxRuntime.jsx(reactNative.View, { testID: `${testID}${APP_SHELL_SUFFIX.banner}`, children: banner }) : null,
-    /* @__PURE__ */ jsxRuntime.jsx(
-      reactNative.ScrollView,
+    showRail ? /* @__PURE__ */ jsxRuntime.jsxs(reactNative.View, { style: styles2.bodyRow, children: [
+      /* @__PURE__ */ jsxRuntime.jsx(reactNative.View, { testID: `${testID}${APP_SHELL_SUFFIX.sidebar}`, children: sidebar }),
+      scroller
+    ] }) : scroller,
+    useDrawer && drawerOpen ? /* @__PURE__ */ jsxRuntime.jsx(
+      MobileDrawer,
       {
-        contentContainerStyle: [styles.scrollContent, { padding: contentPadding }],
-        style: styles.scroll,
-        testID: `${testID}${APP_SHELL_SUFFIX.content}`,
-        children: /* @__PURE__ */ jsxRuntime.jsx(reactNative.View, { style: columnStyle, children: body })
+        drawerTestID: `${testID}${APP_SHELL_SUFFIX.drawer}`,
+        labels: drawerLabels,
+        scrimTestID: `${testID}${APP_SHELL_SUFFIX.scrim}`,
+        sidebar,
+        onClose: closeDrawer
       }
-    )
+    ) : null
   ] });
 };
 function roleRoutesToNavItems(routes, translate) {