@dloizides/ui-nav 1.27.0 → 1.28.0

package/dist/index.mjs

@@ -897,7 +897,8 @@ var APP_SHELL_SUFFIX = {
   pending: "-pending",
   loading: "-loading",
   error: "-error",
-  forbidden: "-forbidden"
+  forbidden: "-forbidden",
+  band: "-backdrop-band"
 };
 var FocusableTouchable = ({
   onPress,
@@ -1536,13 +1537,53 @@ var Nav = (props) => {
   }
   return /* @__PURE__ */ jsx(NavBar, { ...props });
 };
+var RAIL_FULL_BREAKPOINT = LAYOUT_COLLAPSE_BREAKPOINT;
+var DEFAULT_COLLAPSED_RAIL_MAX = 1024;
+function resolveRailMode({ viewport, hasSidebar, hasCollapsed, range }) {
+  if (!hasSidebar) return "none";
+  if (hasCollapsed) {
+    if (viewport >= range.max) return "full";
+    if (viewport >= range.min) return "collapsed";
+    return "drawer";
+  }
+  return viewport >= RAIL_FULL_BREAKPOINT ? "full" : "drawer";
+}
+var styles3 = StyleSheet.create({
+  band: { left: 0, position: "absolute", right: 0, top: 0 }
+});
+function readBackdrop(theme) {
+  return theme.backdrop;
+}
+function rootStyle(backdrop, fallback) {
+  if (backdrop === void 0) return { backgroundColor: fallback };
+  const base = { backgroundColor: backdrop.color };
+  if (!IS_WEB || backdrop.image === null) return base;
+  const web = { backgroundImage: backdrop.image, backgroundSize: backdrop.imageSize ?? "auto" };
+  return { ...base, ...web };
+}
+function resolveShellBackdrop(theme, viewport, contentPadding, testID) {
+  const backdrop = readBackdrop(theme);
+  const band = backdrop?.band ?? null;
+  const root = rootStyle(backdrop, theme.colors.background);
+  if (band === null) return { root, chrome: void 0, chromeText: theme.colors.text, band: null };
+  const overlap = viewport < RAIL_FULL_BREAKPOINT ? band.overlap.compact : band.overlap.wide;
+  const element = /* @__PURE__ */ jsx(
+    View,
+    {
+      pointerEvents: "none",
+      style: [styles3.band, { backgroundColor: band.color, height: contentPadding + overlap }],
+      testID: `${testID}${APP_SHELL_SUFFIX.band}`
+    }
+  );
+  return { root, chrome: { backgroundColor: band.color }, chromeText: band.text, band: element };
+}
 var CARD_PADDING = 20;
 var CARD_BORDER_RADIUS = 12;
 var CARD_BORDER_WIDTH = 1;
 var CARD_TITLE_FONT_SIZE = 16;
 var CARD_MESSAGE_FONT_SIZE = 14;
 var CARD_TITLE_MARGIN_BOTTOM = 8;
-var styles3 = StyleSheet.create({
+var styles4 = StyleSheet.create({
   // Loading is a TRANSITIONAL state: the spinner is an absolute overlay ON TOP of
   // stably-mounted children, never a replacement for them. Replacing children here
   // would unmount whatever they host (e.g. a navigator), and on remount React
@@ -1574,9 +1615,9 @@ function MessageCard({
 }) {
   const { theme } = useUi();
   const colors = theme.colors;
-  return /* @__PURE__ */ jsxs(View, { style: [styles3.card, { backgroundColor: colors.surface, borderColor: accentColor }], testID, children: [
-    /* @__PURE__ */ jsx(Text, { style: [styles3.cardTitle, { color: accentColor }], children: message.titleText }),
-    /* @__PURE__ */ jsx(Text, { style: [styles3.cardMessage, { color: colors.textSecondary }], children: message.messageText })
+  return /* @__PURE__ */ jsxs(View, { style: [styles4.card, { backgroundColor: colors.surface, borderColor: accentColor }], testID, children: [
+    /* @__PURE__ */ jsx(Text, { style: [styles4.cardTitle, { color: accentColor }], children: message.titleText }),
+    /* @__PURE__ */ jsx(Text, { style: [styles4.cardMessage, { color: colors.textSecondary }], children: message.messageText })
   ] });
 }
 function useContentBody(state, children, testID) {
@@ -1588,12 +1629,12 @@ function useContentBody(state, children, testID) {
     return /* @__PURE__ */ jsx(MessageCard, { accentColor: errorColor, message: state.forbidden, testID: `${testID}${APP_SHELL_SUFFIX.forbidden}` });
   if (state.error)
     return /* @__PURE__ */ jsx(MessageCard, { accentColor: errorColor, message: state.error, testID: `${testID}${APP_SHELL_SUFFIX.error}` });
-  return /* @__PURE__ */ jsxs(View, { style: styles3.loadingHost, children: [
+  return /* @__PURE__ */ jsxs(View, { style: styles4.loadingHost, children: [
     children,
     state.loading === true ? /* @__PURE__ */ jsx(
       View,
       {
-        style: [styles3.loadingOverlay, { backgroundColor: theme.colors.background }],
+        style: [styles4.loadingOverlay, { backgroundColor: theme.colors.background }],
         testID: `${testID}${APP_SHELL_SUFFIX.loading}`,
         children: /* @__PURE__ */ jsx(ActivityIndicator, { color: primary, size: "large" })
       }
@@ -1620,7 +1661,7 @@ var DEFAULT_DRAWER_LABELS = {
   closeLabel: "Close menu",
   closeHint: "Close the navigation menu"
 };
-var styles4 = StyleSheet.create({
+var styles5 = StyleSheet.create({
   overlay: { ...StyleSheet.absoluteFillObject, zIndex: DRAWER_Z_INDEX },
   // The scrim's tap-to-close hit area is anchored to the RIGHT of the panel
   // (`left: DRAWER_WIDTH`), so it NEVER overlaps the panel: nav-item taps always
@@ -1655,10 +1696,10 @@ var MenuToggle = ({ label, hint, onOpen, testID }) => {
       accessibilityHint: hint,
       accessibilityLabel: label,
       ringColor: theme.palette.primary["500"],
-      style: styles4.menuToggle,
+      style: styles5.menuToggle,
       testID,
       onPress: onOpen,
-      children: /* @__PURE__ */ jsx(Text, { style: [styles4.menuToggleGlyph, { color: theme.colors.text }], children: MENU_GLYPH2 })
+      children: /* @__PURE__ */ jsx(Text, { style: [styles5.menuToggleGlyph, { color: theme.colors.text }], children: MENU_GLYPH2 })
     }
   );
 };
@@ -1684,14 +1725,14 @@ var MobileDrawer = ({
     node.addEventListener("click", handleClick);
     return () => node.removeEventListener("click", handleClick);
   }, [onClose]);
-  return /* @__PURE__ */ jsxs(View, { style: styles4.overlay, children: [
+  return /* @__PURE__ */ jsxs(View, { style: styles5.overlay, children: [
     /* @__PURE__ */ jsx(
       Pressable,
       {
         accessibilityHint: labels.closeHint,
         accessibilityLabel: labels.closeLabel,
         accessibilityRole: "button",
-        style: styles4.scrim,
+        style: styles5.scrim,
         testID: scrimTestID,
         onPress: onClose
       }
@@ -1702,24 +1743,13 @@ var MobileDrawer = ({
         ref: panelRef,
         "aria-modal": true,
         role: "dialog",
-        style: [styles4.panel, { backgroundColor: theme.colors.surface }],
+        style: [styles5.panel, { backgroundColor: theme.colors.surface }],
         testID: drawerTestID,
         children: renderTextSlot(sidebar, { color: theme.colors.text })
       }
     )
   ] });
 };
-var RAIL_FULL_BREAKPOINT = LAYOUT_COLLAPSE_BREAKPOINT;
-var DEFAULT_COLLAPSED_RAIL_MAX = 1024;
-function resolveRailMode({ viewport, hasSidebar, hasCollapsed, range }) {
-  if (!hasSidebar) return "none";
-  if (hasCollapsed) {
-    if (viewport >= range.max) return "full";
-    if (viewport >= range.min) return "collapsed";
-    return "drawer";
-  }
-  return viewport >= RAIL_FULL_BREAKPOINT ? "full" : "drawer";
-}
 function resolveContentMaxWidth(width, viewport) {
   if (width === "full") return "full";
   const wideMinViewport = width.wideMinViewport ?? Number.POSITIVE_INFINITY;
@@ -1731,7 +1761,7 @@ function useContentMaxWidth(width) {
   return resolveContentMaxWidth(width, viewport);
 }
 var DEFAULT_CONTENT_PADDING = 24;
-var styles5 = StyleSheet.create({
+var styles6 = StyleSheet.create({
   root: { flex: 1 },
   // Auth-pending spinner: an opaque absolute overlay over the mounted shell, so
   // `children` (and any navigator they host) are never unmounted while the gate
@@ -1771,6 +1801,7 @@ var AppShell = ({
   const maxWidth = useContentMaxWidth(width);
   const body = useContentBody(state, children, testID);
   const { width: viewportWidth } = useWindowDimensions();
+  const look = resolveShellBackdrop(theme, viewportWidth, contentPadding, testID);
   const railRange = collapsedRailRange ?? { min: RAIL_FULL_BREAKPOINT, max: DEFAULT_COLLAPSED_RAIL_MAX };
   const railMode = resolveRailMode({
     viewport: viewportWidth,
@@ -1792,18 +1823,21 @@ var AppShell = ({
   }, [isUnauthenticated, gate]);
   const gatePending = gate?.pending === true;
   if (isUnauthenticated) return null;
-  const columnStyle = maxWidth === "full" ? styles5.columnFull : [styles5.columnCapped, { maxWidth }];
-  const navInnerStyle = chromeAlignment === "content" && maxWidth !== "full" ? [styles5.chromeCapped, { maxWidth, paddingHorizontal: contentPadding }] : void 0;
-  const scroller = /* @__PURE__ */ jsx(
+  const columnStyle = maxWidth === "full" ? styles6.columnFull : [styles6.columnCapped, { maxWidth }];
+  const navInnerStyle = chromeAlignment === "content" && maxWidth !== "full" ? [styles6.chromeCapped, { maxWidth, paddingHorizontal: contentPadding }] : void 0;
+  const scroller = /* @__PURE__ */ jsxs(
     ScrollView,
     {
-      contentContainerStyle: [styles5.scrollContent, { padding: contentPadding }],
-      style: styles5.scroll,
+      contentContainerStyle: [styles6.scrollContent, { padding: contentPadding }],
+      style: styles6.scroll,
       testID: `${testID}${APP_SHELL_SUFFIX.content}`,
-      children: /* @__PURE__ */ jsx(View, { style: columnStyle, children: body })
+      children: [
+        look.band,
+        /* @__PURE__ */ jsx(View, { style: columnStyle, children: body })
+      ]
     }
   );
-  const headerRegion = useDrawer ? /* @__PURE__ */ jsxs(View, { style: styles5.headerRow, testID: `${testID}${APP_SHELL_SUFFIX.header}`, children: [
+  const headerRegion = useDrawer ? /* @__PURE__ */ jsxs(View, { style: [styles6.headerRow, look.chrome], testID: `${testID}${APP_SHELL_SUFFIX.header}`, children: [
     /* @__PURE__ */ jsx(
       MenuToggle,
       {
@@ -1813,14 +1847,14 @@ var AppShell = ({
         onOpen: openDrawer
       }
     ),
-    /* @__PURE__ */ jsx(View, { style: styles5.headerFill, children: renderTextSlot(header, { color: theme.colors.text }) })
-  ] }) : /* @__PURE__ */ jsx(View, { testID: `${testID}${APP_SHELL_SUFFIX.header}`, children: renderTextSlot(header, { color: theme.colors.text }) });
+    /* @__PURE__ */ jsx(View, { style: styles6.headerFill, children: renderTextSlot(header, { color: look.chromeText }) })
+  ] }) : /* @__PURE__ */ jsx(View, { style: look.chrome, testID: `${testID}${APP_SHELL_SUFFIX.header}`, children: renderTextSlot(header, { color: look.chromeText }) });
   const railRegion = railMode === "full" ? /* @__PURE__ */ jsx(View, { testID: `${testID}${APP_SHELL_SUFFIX.sidebar}`, children: renderTextSlot(sidebar, { color: theme.colors.text }) }) : railMode === "collapsed" ? /* @__PURE__ */ jsx(View, { testID: `${testID}${APP_SHELL_SUFFIX.collapsedSidebar}`, children: renderTextSlot(collapsedSidebar, { color: theme.colors.text }) }) : null;
-  return /* @__PURE__ */ jsxs(View, { style: [styles5.root, { backgroundColor: theme.colors.background }], testID, children: [
+  return /* @__PURE__ */ jsxs(View, { style: [styles6.root, look.root], testID, children: [
     headerRegion,
-    nav !== void 0 ? /* @__PURE__ */ jsx(View, { testID: `${testID}${APP_SHELL_SUFFIX.nav}`, children: navInnerStyle !== void 0 ? /* @__PURE__ */ jsx(View, { style: navInnerStyle, children: renderTextSlot(nav, { color: theme.colors.text }) }) : renderTextSlot(nav, { color: theme.colors.text }) }) : null,
+    nav !== void 0 ? /* @__PURE__ */ jsx(View, { style: look.chrome, testID: `${testID}${APP_SHELL_SUFFIX.nav}`, children: navInnerStyle !== void 0 ? /* @__PURE__ */ jsx(View, { style: navInnerStyle, children: renderTextSlot(nav, { color: look.chromeText }) }) : renderTextSlot(nav, { color: look.chromeText }) }) : null,
     banner !== void 0 ? /* @__PURE__ */ jsx(View, { testID: `${testID}${APP_SHELL_SUFFIX.banner}`, children: renderTextSlot(banner, { color: theme.colors.text }) }) : null,
-    railRegion !== null ? /* @__PURE__ */ jsxs(View, { style: styles5.bodyRow, children: [
+    railRegion !== null ? /* @__PURE__ */ jsxs(View, { style: styles6.bodyRow, children: [
       railRegion,
       scroller
     ] }) : scroller,
@@ -1837,7 +1871,7 @@ var AppShell = ({
     gatePending ? /* @__PURE__ */ jsx(
       View,
       {
-        style: [styles5.pendingOverlay, { backgroundColor: theme.colors.background }],
+        style: [styles6.pendingOverlay, { backgroundColor: theme.colors.background }],
         testID: `${testID}${APP_SHELL_SUFFIX.pending}`,
         children: /* @__PURE__ */ jsx(ActivityIndicator, { color: primary, size: "large" })
       }
@@ -2204,7 +2238,7 @@ var KEY_DOWN = "ArrowDown";
 var KEY_UP = "ArrowUp";
 var KEY_ENTER = "Enter";
 var KEY_ESCAPE = "Escape";
-var styles6 = StyleSheet.create({
+var styles7 = StyleSheet.create({
   overlay: { ...StyleSheet.absoluteFillObject, zIndex: OVERLAY_Z_INDEX, alignItems: "center" },
   scrim: { ...StyleSheet.absoluteFillObject, backgroundColor: SCRIM_COLOR2 },
   panel: {
@@ -2233,14 +2267,14 @@ var PaletteRow = ({ item, selected, onChoose }) => {
       accessibilityLabel: item.label,
       accessibilityRole: "button",
       accessibilityState: { selected },
-      style: [styles6.row, selected ? { backgroundColor: colors.border } : void 0],
+      style: [styles7.row, selected ? { backgroundColor: colors.border } : void 0],
       testID: item.testID ?? item.key,
       onPress: () => onChoose(item),
       children: [
         typeof item.renderIcon === "function" ? item.renderIcon(colors.textSecondary, NAV_ICON_SIZE) : null,
-        /* @__PURE__ */ jsxs(View, { style: styles6.rowText, children: [
-          /* @__PURE__ */ jsx(Text, { style: [styles6.rowLabel, { color: colors.text }], children: item.label }),
-          item.hint ? /* @__PURE__ */ jsx(Text, { style: [styles6.rowHint, { color: colors.textSecondary }], children: item.hint }) : null
+        /* @__PURE__ */ jsxs(View, { style: styles7.rowText, children: [
+          /* @__PURE__ */ jsx(Text, { style: [styles7.rowLabel, { color: colors.text }], children: item.label }),
+          item.hint ? /* @__PURE__ */ jsx(Text, { style: [styles7.rowHint, { color: colors.textSecondary }], children: item.hint }) : null
         ] })
       ]
     }
@@ -2280,14 +2314,14 @@ var CommandPalette = ({ open, items, onClose, labels, testID }) => {
     [results, selected, choose, onClose]
   );
   if (!open) return null;
-  return /* @__PURE__ */ jsxs(View, { style: styles6.overlay, children: [
+  return /* @__PURE__ */ jsxs(View, { style: styles7.overlay, children: [
     /* @__PURE__ */ jsx(
       Pressable,
       {
         accessibilityHint: labels.closeHint,
         accessibilityLabel: labels.closeLabel,
         accessibilityRole: "button",
-        style: styles6.scrim,
+        style: styles7.scrim,
         testID: `${testID ?? "command-palette"}-scrim`,
         onPress: onClose
       }
@@ -2298,7 +2332,7 @@ var CommandPalette = ({ open, items, onClose, labels, testID }) => {
         "aria-modal": true,
         "aria-label": labels.regionLabel,
         role: "dialog",
-        style: [styles6.panel, { backgroundColor: colors.surface, borderColor: colors.border }],
+        style: [styles7.panel, { backgroundColor: colors.surface, borderColor: colors.border }],
         testID: testID ?? "command-palette",
         children: [
           /* @__PURE__ */ jsx(
@@ -2308,14 +2342,14 @@ var CommandPalette = ({ open, items, onClose, labels, testID }) => {
               accessibilityLabel: labels.placeholder,
               placeholder: labels.placeholder,
               placeholderTextColor: colors.textSecondary,
-              style: [styles6.input, { color: colors.text, borderBottomColor: colors.border }],
+              style: [styles7.input, { color: colors.text, borderBottomColor: colors.border }],
               testID: `${testID ?? "command-palette"}-input`,
               value: query,
               onChangeText: setQuery,
               onKeyPress
             }
           ),
-          results.length === 0 ? /* @__PURE__ */ jsx(Text, { style: [styles6.empty, { color: colors.textSecondary }], children: labels.emptyText }) : /* @__PURE__ */ jsx(ScrollView, { keyboardShouldPersistTaps: "handled", style: styles6.list, children: results.map((item, index) => /* @__PURE__ */ jsx(PaletteRow, { item, selected: index === selected, onChoose: choose }, item.key)) })
+          results.length === 0 ? /* @__PURE__ */ jsx(Text, { style: [styles7.empty, { color: colors.textSecondary }], children: labels.emptyText }) : /* @__PURE__ */ jsx(ScrollView, { keyboardShouldPersistTaps: "handled", style: styles7.list, children: results.map((item, index) => /* @__PURE__ */ jsx(PaletteRow, { item, selected: index === selected, onChoose: choose }, item.key)) })
         ]
       }
     )
@@ -2420,7 +2454,7 @@ var TAB_MIN_HEIGHT = 56;
 var LABEL_SIZE = 12;
 var LABEL_GAP = 2;
 var TAB_PADDING = 4;
-var styles7 = StyleSheet.create({
+var styles8 = StyleSheet.create({
   tab: {
     flex: 1,
     minHeight: TAB_MIN_HEIGHT,
@@ -2457,31 +2491,31 @@ var BottomTab = ({
       accessibilityLabel: item.label,
       accessibilityRole: "link",
       accessibilityState: { selected: isActive },
-      style: [styles7.tab, { opacity: feedback.opacity }],
+      style: [styles8.tab, { opacity: feedback.opacity }],
       testID: item.testID ?? item.key,
       onPress: () => onPress(item.route),
       onPressIn: () => setPressed(true),
       onPressOut: () => setPressed(false),
       ...ariaCurrentProps3(isActive),
       children: [
-        /* @__PURE__ */ jsxs(Animated.View, { style: [styles7.iconWrap, { transform: [{ scale }] }], children: [
+        /* @__PURE__ */ jsxs(Animated.View, { style: [styles8.iconWrap, { transform: [{ scale }] }], children: [
           feedback.pillScale === null ? null : /* @__PURE__ */ jsx(
             View,
             {
               pointerEvents: "none",
-              style: [styles7.pill, { backgroundColor: colors.pill, transform: [{ scale: feedback.pillScale }] }, motion]
+              style: [styles8.pill, { backgroundColor: colors.pill, transform: [{ scale: feedback.pillScale }] }, motion]
             }
           ),
           /* @__PURE__ */ jsx(View, { style: [{ transform: feedback.iconTransform }, motion], children: item.renderIcon?.(color, ICON_SIZE) })
         ] }),
-        /* @__PURE__ */ jsx(Text, { style: [styles7.label, { color }], children: item.label })
+        /* @__PURE__ */ jsx(Text, { style: [styles8.label, { color }], children: item.label })
       ]
     }
   );
 };
 var DEFAULT_TEST_ID = "bottom-tab-bar";
 var SLIDER_HEIGHT = 3;
-var styles8 = StyleSheet.create({
+var styles9 = StyleSheet.create({
   bar: { flexDirection: "row", borderTopWidth: StyleSheet.hairlineWidth },
   slider: { position: "absolute", top: 0, height: SLIDER_HEIGHT }
 });
@@ -2508,14 +2542,14 @@ var BottomTabBar = ({
     {
       "aria-label": regionLabel,
       role: "navigation",
-      style: [styles8.bar, { backgroundColor: theme.colors.surface, borderTopColor: theme.colors.border }, containerStyle],
+      style: [styles9.bar, { backgroundColor: theme.colors.surface, borderTopColor: theme.colors.border }, containerStyle],
       testID,
       children: [
         bar === null ? null : /* @__PURE__ */ jsx(
           View,
           {
             pointerEvents: "none",
-            style: [styles8.slider, { left: bar.left, width: bar.width, backgroundColor: primary }, webTransition("left", barMs, reducedMotion)]
+            style: [styles9.slider, { left: bar.left, width: bar.width, backgroundColor: primary }, webTransition("left", barMs, reducedMotion)]
           }
         ),
         items.map((item) => /* @__PURE__ */ jsx(