@dloizides/ui-nav 1.19.0 → 1.20.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 1.20.0
+
+**The auth-pending and page-loading spinners now OVERLAY stably-mounted children instead of
+replacing them — closing a latent deep-link-collapse trap in the shared shell.**
+
+`AppShell`'s `gate.pending` branch and `appShellContent`'s `state.loading` branch each `return`ed a
+full-screen spinner *instead of* `children`. Replacing the subtree unmounts whatever `children` host
+— in a portal that is a navigator/`<Slot/>` — and on remount React Navigation re-derives its default
+route, so a deep-linked sub-route silently collapses to its default on every reload. (This is the
+exact class of bug that hit kefi-web's organizer portal, fixed there in its `OnboardingGate`; the
+same shape lived dormant here because no consumer passes `gate=`/`state=` yet.)
+
+- **`AppShell` (`gate.pending`)** now renders the shell tree normally and paints the pending spinner
+  as an opaque `position:absolute` overlay on top, so `children` mount once and are never torn down
+  across `pending → authenticated` (proven by a "same child instance, no remount" test).
+- **`appShellContent` (`state.loading`)** likewise overlays the loading spinner over mounted
+  `children` rather than swapping them out. The `loadingHost` wrapper is gated on `state` being
+  DEFINED, not on `loading`'s live value — so the element type at the mount point is invariant across
+  a `loading` true↔false toggle and `children` are reconciled in place, never remounted on the edge
+  (also proven by a "same child instance, no remount" test). Consumers that pass no `state` render
+  `children` bare, byte-identical to 1.19.0. Error / forbidden cards are TERMINAL and still replace;
+  unauthenticated still returns null + `onRedirect`.
+- **Rule encoded in the docblock:** a *transitional* status overlays; only a *terminal* state
+  replaces. Corollary for consumers — `children` mount beneath the pending overlay, so gate data
+  FETCHES on auth state (`enabled: isAuthenticated`), not on mount. No public API changed; behavior
+  is unchanged for any consumer not passing `gate`/`state`.
+
 ## 1.19.0
 
 **The "More ▾" overflow menu now opens at a readable width instead of cramping onto the trigger's tiny footprint.**

package/dist/index.d.mts

@@ -595,6 +595,16 @@ declare function useContentMaxWidth(width: AppShellWidth): number | 'full';
  * (pending spinner / redirect-when-unauthenticated) and page state cards
  * (loading / error / forbidden).
  *
+ * OVERLAY DISCIPLINE (do not regress): a TRANSITIONAL status — `gate.pending` and
+ * `state.loading` — renders as an absolute overlay OVER stably-mounted `children`,
+ * never as a replacement. Replacing the subtree unmounts whatever `children` host
+ * (typically a navigator/`<Slot/>`); on remount React Navigation re-derives its
+ * default route, so a deep-linked sub-route silently collapses to its default on
+ * every reload. Only TERMINAL states replace: unauthenticated returns null (we are
+ * navigating away) and error/forbidden cards win inside the content column.
+ * Corollary for consumers: `children` mount BENEATH the pending overlay, so gate
+ * your data FETCHES on auth state (`enabled: isAuthenticated`), not on mount.
+ *
  * 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

package/dist/index.d.ts

@@ -595,6 +595,16 @@ declare function useContentMaxWidth(width: AppShellWidth): number | 'full';
  * (pending spinner / redirect-when-unauthenticated) and page state cards
  * (loading / error / forbidden).
  *
+ * OVERLAY DISCIPLINE (do not regress): a TRANSITIONAL status — `gate.pending` and
+ * `state.loading` — renders as an absolute overlay OVER stably-mounted `children`,
+ * never as a replacement. Replacing the subtree unmounts whatever `children` host
+ * (typically a navigator/`<Slot/>`); on remount React Navigation re-derives its
+ * default route, so a deep-linked sub-route silently collapses to its default on
+ * every reload. Only TERMINAL states replace: unauthenticated returns null (we are
+ * navigating away) and error/forbidden cards win inside the content column.
+ * Corollary for consumers: `children` mount BENEATH the pending overlay, so gate
+ * your data FETCHES on auth state (`enabled: isAuthenticated`), not on mount.
+ *
  * 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

package/dist/index.js

@@ -1344,7 +1344,22 @@ var CARD_TITLE_FONT_SIZE = 16;
 var CARD_MESSAGE_FONT_SIZE = 14;
 var CARD_TITLE_MARGIN_BOTTOM = 8;
 var styles3 = reactNative.StyleSheet.create({
-  centerFill: { flex: 1, justifyContent: "center", alignItems: "center" },
+  // 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
+  // Navigation re-derives its default route — silently discarding a deep link.
+  // The host wraps children whenever a `state` is passed (not only while loading),
+  // so its element type is invariant across the loading toggle — see `useContentBody`.
+  loadingHost: { flex: 1 },
+  loadingOverlay: {
+    alignItems: "center",
+    bottom: 0,
+    justifyContent: "center",
+    left: 0,
+    position: "absolute",
+    right: 0,
+    top: 0
+  },
   card: {
     padding: CARD_PADDING,
     borderRadius: CARD_BORDER_RADIUS,
@@ -1369,13 +1384,22 @@ function useContentBody(state, children, testID) {
   const { theme } = uiFeedback.useUi();
   const primary = theme.palette.primary["500"];
   const errorColor = theme.semantic.error["500"];
-  if (state?.forbidden)
+  if (!state) return children;
+  if (state.forbidden)
     return /* @__PURE__ */ jsxRuntime.jsx(MessageCard, { accentColor: errorColor, message: state.forbidden, testID: `${testID}${APP_SHELL_SUFFIX.forbidden}` });
-  if (state?.error)
+  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: styles3.centerFill, testID: `${testID}${APP_SHELL_SUFFIX.loading}`, children: /* @__PURE__ */ jsxRuntime.jsx(reactNative.ActivityIndicator, { color: primary, size: "large" }) });
-  return children;
+  return /* @__PURE__ */ jsxRuntime.jsxs(reactNative.View, { style: styles3.loadingHost, children: [
+    children,
+    state.loading === true ? /* @__PURE__ */ jsxRuntime.jsx(
+      reactNative.View,
+      {
+        style: [styles3.loadingOverlay, { backgroundColor: theme.colors.background }],
+        testID: `${testID}${APP_SHELL_SUFFIX.loading}`,
+        children: /* @__PURE__ */ jsxRuntime.jsx(reactNative.ActivityIndicator, { color: primary, size: "large" })
+      }
+    ) : null
+  ] });
 }
 var SCRIM_COLOR = "rgba(0, 0, 0, 0.5)";
 var MENU_GLYPH2 = "\u2630";
@@ -1513,7 +1537,10 @@ function useContentMaxWidth(width) {
 var DEFAULT_CONTENT_PADDING = 24;
 var styles5 = reactNative.StyleSheet.create({
   root: { flex: 1 },
-  centerFill: { flex: 1, justifyContent: "center", alignItems: "center" },
+  // Auth-pending spinner: an opaque absolute overlay over the mounted shell, so
+  // `children` (and any navigator they host) are never unmounted while the gate
+  // resolves. See the `gatePending` note in the render body.
+  pendingOverlay: { alignItems: "center", bottom: 0, justifyContent: "center", left: 0, position: "absolute", right: 0, top: 0 },
   scroll: { flex: 1 },
   scrollContent: { flexGrow: 1 },
   // Mobile back-office header: the hamburger sits inline before the header slot.
@@ -1567,8 +1594,7 @@ var AppShell = ({
   React.useEffect(() => {
     if (isUnauthenticated && gate !== void 0) gate.onRedirect();
   }, [isUnauthenticated, gate]);
-  if (gate?.pending === true)
-    return /* @__PURE__ */ jsxRuntime.jsx(reactNative.View, { style: [styles5.root, styles5.centerFill, { backgroundColor: theme.colors.background }], testID: `${testID}${APP_SHELL_SUFFIX.pending}`, children: /* @__PURE__ */ jsxRuntime.jsx(reactNative.ActivityIndicator, { color: primary, size: "large" }) });
+  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;
@@ -1611,6 +1637,14 @@ var AppShell = ({
         sidebar,
         onClose: closeDrawer
       }
+    ) : null,
+    gatePending ? /* @__PURE__ */ jsxRuntime.jsx(
+      reactNative.View,
+      {
+        style: [styles5.pendingOverlay, { backgroundColor: theme.colors.background }],
+        testID: `${testID}${APP_SHELL_SUFFIX.pending}`,
+        children: /* @__PURE__ */ jsxRuntime.jsx(reactNative.ActivityIndicator, { color: primary, size: "large" })
+      }
     ) : null
   ] });
 };