@dloizides/ui-nav 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # 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.

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;
@@ -245,8 +272,18 @@ interface AppShellProps {
      * 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. */
@@ -275,7 +312,7 @@ interface AppShellProps {
     testID: string;
     children: React.ReactNode;
 }
-declare const AppShell: ({ header, nav, sidebar, 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
@@ -305,6 +342,12 @@ declare const APP_SHELL_SUFFIX: {
     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;
@@ -245,8 +272,18 @@ interface AppShellProps {
      * 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. */
@@ -275,7 +312,7 @@ interface AppShellProps {
     testID: string;
     children: React.ReactNode;
 }
-declare const AppShell: ({ header, nav, sidebar, 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
@@ -305,6 +342,12 @@ declare const APP_SHELL_SUFFIX: {
     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

@@ -348,6 +348,12 @@ var APP_SHELL_SUFFIX = {
   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",
@@ -671,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;
@@ -688,11 +770,14 @@ 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 },
@@ -718,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 })
       ]
     }
   );
@@ -736,13 +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,
@@ -756,32 +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;
+  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: [styles.scrollContent, { padding: contentPadding }],
-      style: styles.scroll,
+      contentContainerStyle: [styles2.scrollContent, { padding: contentPadding }],
+      style: styles2.scroll,
       testID: `${testID}${APP_SHELL_SUFFIX.content}`,
       children: /* @__PURE__ */ jsxRuntime.jsx(reactNative.View, { style: columnStyle, children: body })
     }
   );
-  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 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,
-    sidebar !== void 0 ? /* @__PURE__ */ jsxRuntime.jsxs(reactNative.View, { style: styles.bodyRow, children: [
+    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
+    ] }) : scroller,
+    useDrawer && drawerOpen ? /* @__PURE__ */ jsxRuntime.jsx(
+      MobileDrawer,
+      {
+        drawerTestID: `${testID}${APP_SHELL_SUFFIX.drawer}`,
+        labels: drawerLabels,
+        scrimTestID: `${testID}${APP_SHELL_SUFFIX.scrim}`,
+        sidebar,
+        onClose: closeDrawer
+      }
+    ) : null
   ] });
 };
 function roleRoutesToNavItems(routes, translate) {