@carlonicora/nextjs-jsonapi 1.135.1 → 1.137.0

package/dist/features/help/index.js

@@ -22,7 +22,7 @@ var _chunkYBZVWLPHjs = require('../../chunk-YBZVWLPH.js');
 
 
 
-var _chunkDNWYHP4Vjs = require('../../chunk-DNWYHP4V.js');
+var _chunkCTKZM2YCjs = require('../../chunk-CTKZM2YC.js');
 
 
 var _chunkC2LEIBUKjs = require('../../chunk-C2LEIBUK.js');
@@ -74,29 +74,29 @@ var _lucidereact = require('lucide-react');
 
 
 function HelpAssistantSheet({ open, onOpenChange }) {
-  return /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkDNWYHP4Vjs.Sheet, { open, onOpenChange, children: /* @__PURE__ */ _jsxruntime.jsx.call(void 0, 
-    _chunkDNWYHP4Vjs.SheetContent,
+  return /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkCTKZM2YCjs.Sheet, { open, onOpenChange, children: /* @__PURE__ */ _jsxruntime.jsx.call(void 0, 
+    _chunkCTKZM2YCjs.SheetContent,
     {
       side: "right",
       className: "flex w-full flex-col data-[side=right]:sm:max-w-2xl data-[side=right]:lg:max-w-3xl",
-      children: /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkDNWYHP4Vjs.AssistantProvider, { manageUrl: false, children: /* @__PURE__ */ _jsxruntime.jsx.call(void 0, HelpAssistantSheetBody, {}) })
+      children: /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkCTKZM2YCjs.AssistantProvider, { manageUrl: false, children: /* @__PURE__ */ _jsxruntime.jsx.call(void 0, HelpAssistantSheetBody, {}) })
     }
   ) });
 }
 _chunk7QVYU63Ejs.__name.call(void 0, HelpAssistantSheet, "HelpAssistantSheet");
 function HelpAssistantSheetBody() {
   const t = _nextintl.useTranslations.call(void 0, );
-  const ctx = _chunkDNWYHP4Vjs.useAssistantContext.call(void 0, );
+  const ctx = _chunkCTKZM2YCjs.useAssistantContext.call(void 0, );
   const showThread = !!ctx.assistant || ctx.sending || ctx.messages.length > 0;
   const send = /* @__PURE__ */ _chunk7QVYU63Ejs.__name.call(void 0, (content) => ctx.sendMessage(content, { howToMode: true }), "send");
   return /* @__PURE__ */ _jsxruntime.jsxs.call(void 0, _jsxruntime.Fragment, { children: [
-    /* @__PURE__ */ _jsxruntime.jsxs.call(void 0, _chunkDNWYHP4Vjs.SheetHeader, { children: [
-      /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkDNWYHP4Vjs.SheetTitle, { children: t("help.askAi.sheet.title") }),
-      /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkDNWYHP4Vjs.SheetDescription, { children: t("help.askAi.sheet.subtitle") })
+    /* @__PURE__ */ _jsxruntime.jsxs.call(void 0, _chunkCTKZM2YCjs.SheetHeader, { children: [
+      /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkCTKZM2YCjs.SheetTitle, { children: t("help.askAi.sheet.title") }),
+      /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkCTKZM2YCjs.SheetDescription, { children: t("help.askAi.sheet.subtitle") })
     ] }),
-    !showThread ? /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkDNWYHP4Vjs.AssistantEmptyState, { onSend: send }) : /* @__PURE__ */ _jsxruntime.jsxs.call(void 0, _jsxruntime.Fragment, { children: [
+    !showThread ? /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkCTKZM2YCjs.AssistantEmptyState, { onSend: send }) : /* @__PURE__ */ _jsxruntime.jsxs.call(void 0, _jsxruntime.Fragment, { children: [
       /* @__PURE__ */ _jsxruntime.jsx.call(void 0, 
-        _chunkDNWYHP4Vjs.AssistantThread,
+        _chunkCTKZM2YCjs.AssistantThread,
         {
           messages: ctx.messages,
           sending: ctx.sending,
@@ -106,7 +106,7 @@ function HelpAssistantSheetBody() {
           onRetry: ctx.retrySend
         }
       ),
-      /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkDNWYHP4Vjs.AssistantComposer, { onSend: send, disabled: ctx.sending })
+      /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkCTKZM2YCjs.AssistantComposer, { onSend: send, disabled: ctx.sending })
     ] })
   ] });
 }
@@ -116,20 +116,20 @@ _chunk7QVYU63Ejs.__name.call(void 0, HelpAssistantSheetBody, "HelpAssistantSheet
 
 function HelpAskAi() {
   const t = _nextintl.useTranslations.call(void 0, );
-  const { currentUser } = _chunkDNWYHP4Vjs.useCurrentUserContext.call(void 0, );
+  const { currentUser } = _chunkCTKZM2YCjs.useCurrentUserContext.call(void 0, );
   const [open, setOpen] = _react.useState.call(void 0, false);
   const disabled = !currentUser;
   if (disabled) {
-    return /* @__PURE__ */ _jsxruntime.jsxs.call(void 0, _chunkDNWYHP4Vjs.Tooltip, { children: [
-      /* @__PURE__ */ _jsxruntime.jsxs.call(void 0, _chunkDNWYHP4Vjs.TooltipTrigger, { render: /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkDNWYHP4Vjs.Button, { variant: "outline", size: "sm", disabled: true }), children: [
+    return /* @__PURE__ */ _jsxruntime.jsxs.call(void 0, _chunkCTKZM2YCjs.Tooltip, { children: [
+      /* @__PURE__ */ _jsxruntime.jsxs.call(void 0, _chunkCTKZM2YCjs.TooltipTrigger, { render: /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkCTKZM2YCjs.Button, { variant: "outline", size: "sm", disabled: true }), children: [
         /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _lucidereact.SparklesIcon, { className: "h-4 w-4" }),
         t("help.askAi.button")
       ] }),
-      /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkDNWYHP4Vjs.TooltipContent, { children: t("help.askAi.loginTooltip") })
+      /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkCTKZM2YCjs.TooltipContent, { children: t("help.askAi.loginTooltip") })
     ] });
   }
   return /* @__PURE__ */ _jsxruntime.jsxs.call(void 0, _jsxruntime.Fragment, { children: [
-    /* @__PURE__ */ _jsxruntime.jsxs.call(void 0, _chunkDNWYHP4Vjs.Button, { variant: "outline", size: "sm", onClick: () => setOpen(true), children: [
+    /* @__PURE__ */ _jsxruntime.jsxs.call(void 0, _chunkCTKZM2YCjs.Button, { variant: "outline", size: "sm", onClick: () => setOpen(true), children: [
       /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _lucidereact.SparklesIcon, { className: "h-4 w-4" }),
       t("help.askAi.button")
     ] }),
@@ -142,7 +142,7 @@ _chunk7QVYU63Ejs.__name.call(void 0, HelpAskAi, "HelpAskAi");
 
 function HelpHeader() {
   const t = _nextintl.useTranslations.call(void 0, );
-  const { currentUser } = _chunkDNWYHP4Vjs.useCurrentUserContext.call(void 0, );
+  const { currentUser } = _chunkCTKZM2YCjs.useCurrentUserContext.call(void 0, );
   const { brand } = useHelp();
   const logo = _optionalChain([brand, 'optionalAccess', _ => _.logo]);
   const label = _nullishCoalesce(_optionalChain([brand, 'optionalAccess', _2 => _2.label]), () => ( "Help"));
@@ -158,7 +158,7 @@ function HelpHeader() {
     ] }),
     /* @__PURE__ */ _jsxruntime.jsxs.call(void 0, "div", { className: "flex items-center gap-2", children: [
       /* @__PURE__ */ _jsxruntime.jsx.call(void 0, HelpAskAi, {}),
-      currentUser ? /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkDNWYHP4Vjs.Button, { render: /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _link2.default, { href: appHref }), nativeButton: false, variant: "outline", size: "sm", children: t("help.header.openApp") }) : /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkDNWYHP4Vjs.Button, { render: /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _link2.default, { href: "/login" }), nativeButton: false, variant: "outline", size: "sm", children: t("help.header.login") })
+      currentUser ? /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkCTKZM2YCjs.Button, { render: /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _link2.default, { href: appHref }), nativeButton: false, variant: "outline", size: "sm", children: t("help.header.openApp") }) : /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkCTKZM2YCjs.Button, { render: /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _link2.default, { href: "/login" }), nativeButton: false, variant: "outline", size: "sm", children: t("help.header.login") })
     ] })
   ] });
 }
@@ -200,7 +200,7 @@ _chunk7QVYU63Ejs.__name.call(void 0, useHelpFilter, "useHelpFilter");
 
 function HelpSideNav() {
   const t = _nextintl.useTranslations.call(void 0, );
-  const generateUrl = _chunkDNWYHP4Vjs.usePageUrlGenerator.call(void 0, );
+  const generateUrl = _chunkCTKZM2YCjs.usePageUrlGenerator.call(void 0, );
   const pathname = _navigation.usePathname.call(void 0, );
   const [articles, setArticles] = _react.useState.call(void 0, []);
   _react.useEffect.call(void 0, () => {
@@ -281,7 +281,7 @@ _chunk7QVYU63Ejs.__name.call(void 0, HelpSideNav, "HelpSideNav");
 function HelpArticleBody(props) {
   const t = _nextintl.useTranslations.call(void 0, );
   const format = _nextintl.useFormatter.call(void 0, );
-  const generateUrl = _chunkDNWYHP4Vjs.usePageUrlGenerator.call(void 0, );
+  const generateUrl = _chunkCTKZM2YCjs.usePageUrlGenerator.call(void 0, );
   const { howToType, title, summary, updatedAt, prev, next, children } = props;
   return /* @__PURE__ */ _jsxruntime.jsxs.call(void 0, "article", { className: "prose dark:prose-invert max-w-none", children: [
     /* @__PURE__ */ _jsxruntime.jsxs.call(void 0, "nav", { className: "text-muted-foreground mb-2 text-xs", children: [
@@ -338,7 +338,7 @@ function HelpTOC({ headings }) {
   }, [headings]);
   if (headings.length === 0) return null;
   return /* @__PURE__ */ _jsxruntime.jsxs.call(void 0, "nav", { "aria-label": t("help.toc.title"), className: "hidden lg:block", children: [
-    /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkDNWYHP4Vjs.MicroLabel, { className: "mb-2", children: t("help.toc.title") }),
+    /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkCTKZM2YCjs.MicroLabel, { className: "mb-2", children: t("help.toc.title") }),
     /* @__PURE__ */ _jsxruntime.jsx.call(void 0, "ul", { className: "space-y-1 text-sm", children: headings.map((h) => /* @__PURE__ */ _jsxruntime.jsx.call(void 0, "li", { style: { paddingLeft: `${(h.depth - 2) * 0.75}rem` }, children: /* @__PURE__ */ _jsxruntime.jsx.call(void 0, 
       "a",
       {
@@ -359,7 +359,7 @@ _chunk7QVYU63Ejs.__name.call(void 0, HelpTOC, "HelpTOC");
 
 function HelpHint({ contextKey }) {
   const t = _nextintl.useTranslations.call(void 0, );
-  const generateUrl = _chunkDNWYHP4Vjs.usePageUrlGenerator.call(void 0, );
+  const generateUrl = _chunkCTKZM2YCjs.usePageUrlGenerator.call(void 0, );
   const [open, setOpen] = _react.useState.call(void 0, false);
   const [picked, setPicked] = _react.useState.call(void 0, null);
   const [articles, setArticles] = _react.useState.call(void 0, []);
@@ -377,7 +377,7 @@ function HelpHint({ contextKey }) {
   if (matches.length === 0) return null;
   const active = _nullishCoalesce(picked, () => ( (matches.length === 1 ? matches[0] : null)));
   return /* @__PURE__ */ _jsxruntime.jsxs.call(void 0, 
-    _chunkDNWYHP4Vjs.Sheet,
+    _chunkCTKZM2YCjs.Sheet,
     {
       open,
       onOpenChange: (o) => {
@@ -385,11 +385,11 @@ function HelpHint({ contextKey }) {
         if (!o) setPicked(null);
       },
       children: [
-        /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkDNWYHP4Vjs.SheetTrigger, { render: /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkDNWYHP4Vjs.Button, { variant: "ghost", size: "icon-sm", "aria-label": t("help.hint.trigger") }), children: /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _lucidereact.HelpCircleIcon, { className: "h-4 w-4" }) }),
-        /* @__PURE__ */ _jsxruntime.jsxs.call(void 0, _chunkDNWYHP4Vjs.SheetContent, { side: "right", className: "w-full max-w-md sm:max-w-lg", children: [
-          /* @__PURE__ */ _jsxruntime.jsxs.call(void 0, _chunkDNWYHP4Vjs.SheetHeader, { children: [
-            /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkDNWYHP4Vjs.SheetTitle, { children: active ? active.name : t("help.hint.pickArticle") }),
-            /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkDNWYHP4Vjs.SheetDescription, { children: _nullishCoalesce(_optionalChain([active, 'optionalAccess', _4 => _4.summary]), () => ( "")) })
+        /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkCTKZM2YCjs.SheetTrigger, { render: /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkCTKZM2YCjs.Button, { variant: "ghost", size: "icon-sm", "aria-label": t("help.hint.trigger") }), children: /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _lucidereact.HelpCircleIcon, { className: "h-4 w-4" }) }),
+        /* @__PURE__ */ _jsxruntime.jsxs.call(void 0, _chunkCTKZM2YCjs.SheetContent, { side: "right", className: "w-full max-w-md sm:max-w-lg", children: [
+          /* @__PURE__ */ _jsxruntime.jsxs.call(void 0, _chunkCTKZM2YCjs.SheetHeader, { children: [
+            /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkCTKZM2YCjs.SheetTitle, { children: active ? active.name : t("help.hint.pickArticle") }),
+            /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkCTKZM2YCjs.SheetDescription, { children: _nullishCoalesce(_optionalChain([active, 'optionalAccess', _4 => _4.summary]), () => ( "")) })
           ] }),
           active ? /* @__PURE__ */ _jsxruntime.jsxs.call(void 0, "div", { className: "mt-4 space-y-3", children: [
             /* @__PURE__ */ _jsxruntime.jsx.call(void 0, "p", { className: "text-muted-foreground text-sm", children: active.summary }),
@@ -421,7 +421,7 @@ _chunk7QVYU63Ejs.__name.call(void 0, HelpHint, "HelpHint");
 
 function HelpSearchResultRow({ result, onSelect }) {
   const t = _nextintl.useTranslations.call(void 0, );
-  const generateUrl = _chunkDNWYHP4Vjs.usePageUrlGenerator.call(void 0, );
+  const generateUrl = _chunkCTKZM2YCjs.usePageUrlGenerator.call(void 0, );
   const [article, setArticle] = _react.useState.call(void 0, null);
   _react.useEffect.call(void 0, () => {
     let active = true;
@@ -432,7 +432,7 @@ function HelpSearchResultRow({ result, onSelect }) {
   }, [result.id]);
   if (!article) {
     return /* @__PURE__ */ _jsxruntime.jsx.call(void 0, 
-      _chunkDNWYHP4Vjs.CommandItem,
+      _chunkCTKZM2YCjs.CommandItem,
       {
         value: result.id,
         disabled: true,
@@ -441,7 +441,7 @@ function HelpSearchResultRow({ result, onSelect }) {
       }
     );
   }
-  return /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkDNWYHP4Vjs.CommandItem, { value: result.id, onSelect, className: "cursor-pointer p-0", children: /* @__PURE__ */ _jsxruntime.jsxs.call(void 0, 
+  return /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkCTKZM2YCjs.CommandItem, { value: result.id, onSelect, className: "cursor-pointer p-0", children: /* @__PURE__ */ _jsxruntime.jsxs.call(void 0, 
     _link2.default,
     {
       href: generateUrl({ page: `/help/${article.howToType}/${article.slug}` }),

package/dist/features/help/index.mjs

@@ -22,7 +22,7 @@ import {
   useAssistantContext,
   useCurrentUserContext,
   usePageUrlGenerator
-} from "../../chunk-EF2HVXOV.mjs";
+} from "../../chunk-EWAOWYT5.mjs";
 import {
   _getStaticHelpContent
 } from "../../chunk-M5IAN7IR.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carlonicora/nextjs-jsonapi",
-  "version": "1.135.1",
+  "version": "1.137.0",
   "description": "Next.js JSON:API client with server/client support and caching",
   "author": "Carlo Nicora",
   "license": "GPL-3.0-or-later",

package/src/components/containers/RoundPageContainer.tsx

@@ -18,7 +18,7 @@ import {
   TabsTrigger,
 } from "@/components";
 import { partitionTabs, Tab } from "@/components/containers";
-import { RoundPageContainerTitle } from "@/components/containers/RoundPageContainerTitle";
+import { HEADER_ROW_MIN_H, RoundPageContainerTitle } from "@/components/containers/RoundPageContainerTitle";
 import { Header, MobileNavigationBar } from "@/components/navigations";
 import { useHeaderChildren, useHeaderLeftContent, useHeaderLogo, useHeaderMobileChildren } from "@/contexts";
 import { useUrlRewriter } from "@/hooks";
@@ -55,6 +55,44 @@ type RoundPageContainerProps = {
    * ancestors.
    */
   onSectionChange?: (section: string) => void;
+  /**
+   * `data-testid` for the page shell. Applied to the outermost content wrapper
+   * of BOTH return branches — the pre-hydration one and the main one — so an
+   * e2e suite gating page-readiness on the testid can attach before hydration
+   * completes rather than racing it.
+   */
+  testId?: string;
+  /**
+   * Initial state of the `details` panel before the persisted preference (the
+   * `round_page_details_state` cookie) is read. Defaults to `false` — the panel
+   * starts collapsed, which suits an informational aside.
+   *
+   * Pass `true` when `details` holds PRIMARY navigation rather than an aside
+   * (e.g. the chat / conversation list), where a collapsed-by-default panel
+   * would hide the page's main affordance behind a toggle. The stored
+   * preference still wins in both directions once the user sets one.
+   *
+   * Requires the title bar to be rendered (`!fullWidth || forceHeader`) —
+   * that is where the toggle lives, so a `fullWidth` caller passing `details`
+   * without `forceHeader` leaves the panel unreachable.
+   */
+  defaultDetailsOpen?: boolean;
+  /**
+   * Heading for the `details` panel. Rendered as a fixed header above the
+   * panel's scroll area, used as the mobile `Sheet` title (replacing the old
+   * hardcoded "Details"), and woven into the toggle's tooltip — so the control
+   * reads "Show conversations" rather than an unlabelled icon.
+   *
+   * Strongly recommended whenever `details` holds primary navigation: without
+   * it the panel is an unlabelled column and the toggle is unguessable.
+   */
+  detailsTitle?: ReactNode;
+  /**
+   * Icon for the `details` toggle. Defaults to an info glyph, which suits an
+   * informational aside. Pass a panel/list glyph when `details` holds primary
+   * navigation — an "info" icon actively misdescribes a conversation list.
+   */
+  detailsIcon?: ReactNode;
 };
 
 // Rail trigger class: override the horizontal TabsTrigger defaults for a
@@ -82,28 +120,47 @@ export function RoundPageContainer({
   header,
   layout = "tabs",
   onSectionChange,
+  testId,
+  defaultDetailsOpen = false,
+  detailsTitle,
+  detailsIcon,
 }: RoundPageContainerProps) {
   const headerChildren = useHeaderChildren();
   const headerLeftContent = useHeaderLeftContent();
   const headerLogo = useHeaderLogo();
   const headerMobileChildren = useHeaderMobileChildren();
-  const [showDetails, setShowDetailsState] = useState(false);
+  const [showDetails, setShowDetailsState] = useState(defaultDetailsOpen);
   const isMobile = useIsMobile();
   const [mounted, setMounted] = useState(false);
 
   useEffect(() => {
-    const match = document.cookie.split("; ").find((row) => row.startsWith(`${DETAILS_COOKIE_NAME}=`));
-    if (match?.split("=")[1] === "true") setShowDetailsState(true);
+    const match = document.cookie.split("; ").find((row) => row.startsWith(`${detailsCookieName}=`));
+    const stored = match?.split("=")[1];
+    // Apply the stored preference in BOTH directions. Previously this only ever
+    // opened the panel, which was harmless while the initial state was always
+    // `false` — but with `defaultDetailsOpen` a caller can start open, and a user
+    // who explicitly collapsed the panel must stay collapsed on the next load.
+    if (stored === "true") setShowDetailsState(true);
+    else if (stored === "false") setShowDetailsState(false);
   }, []);
 
   useEffect(() => {
     setMounted(true);
   }, []);
 
-  const setShowDetails = useCallback((value: boolean) => {
-    setShowDetailsState(value);
-    document.cookie = `${DETAILS_COOKIE_NAME}=${value}; path=/; max-age=${DETAILS_COOKIE_MAX_AGE}`;
-  }, []);
+  // Scope the persisted preference PER MODULE. A single global cookie meant
+  // collapsing an informational aside on one page silently collapsed a primary
+  // navigation panel on another — so a page declaring `defaultDetailsOpen`
+  // could still load collapsed because of an unrelated page's cookie.
+  const detailsCookieName = module?.name ? `${DETAILS_COOKIE_NAME}_${module.name}` : DETAILS_COOKIE_NAME;
+
+  const setShowDetails = useCallback(
+    (value: boolean) => {
+      setShowDetailsState(value);
+      document.cookie = `${detailsCookieName}=${value}; path=/; max-age=${DETAILS_COOKIE_MAX_AGE}`;
+    },
+    [detailsCookieName],
+  );
 
   const searchParams = useSearchParams();
   const section = searchParams.get("section");
@@ -163,7 +220,13 @@ export function RoundPageContainer({
         >
           {headerChildren}
         </Header>
-        <div className={cn("flex h-[calc(100vh-3rem)] w-full flex-col", isMobile ? "gap-1 p-1 pt-0" : "p-2 pt-0 pl-0")}>
+        <div
+          data-testid={testId}
+          className={cn(
+            "flex h-[calc(100dvh-var(--app-header-h,3rem))] w-full flex-col",
+            isMobile ? "gap-1 p-1 pt-0" : "p-2 pt-0 pl-0",
+          )}
+        >
           {/* `min-h-0 flex-1`, NOT `h-full`: the bar below is an in-flow sibling in
               this fixed-height flex column. `h-full` would resolve to 100% of the
               wrapper, leaving no room and pushing the bar below the fold (visible
@@ -187,7 +250,13 @@ export function RoundPageContainer({
       >
         {headerChildren}
       </Header>
-      <div className={cn(`flex h-[calc(100vh-3rem)] w-full flex-col`, isMobile ? "gap-1 p-1 pt-0" : "p-2 pt-0 pl-0")}>
+      <div
+        data-testid={testId}
+        className={cn(
+          `flex h-[calc(100dvh-var(--app-header-h,3rem))] w-full flex-col`,
+          isMobile ? "gap-1 p-1 pt-0" : "p-2 pt-0 pl-0",
+        )}
+      >
         {/* `min-h-0 flex-1`, NOT `h-full`: MobileNavigationBar below is an in-flow
             sibling in this fixed-height flex column. `h-full` resolves to 100% of
             the wrapper, leaving the bar no room and pushing it below the fold —
@@ -198,6 +267,8 @@ export function RoundPageContainer({
               <RoundPageContainerTitle
                 module={module}
                 details={details}
+                detailsTitle={detailsTitle}
+                detailsIcon={detailsIcon}
                 showDetails={showDetails}
                 setShowDetails={setShowDetails}
                 fullWidth={fullWidth}
@@ -402,7 +473,7 @@ export function RoundPageContainer({
               <Sheet open={showDetails} onOpenChange={setShowDetails}>
                 <SheetContent side="right">
                   <SheetHeader>
-                    <SheetTitle>Details</SheetTitle>
+                    <SheetTitle>{detailsTitle ?? "Details"}</SheetTitle>
                   </SheetHeader>
                   <div className="overflow-y-auto p-6 pt-0">{details}</div>
                 </SheetContent>
@@ -410,11 +481,25 @@ export function RoundPageContainer({
             ) : (
               <div
                 className={cn(
-                  "h-full shrink-0 overflow-hidden overflow-y-auto transition-all duration-300 ease-in-out",
-                  showDetails ? "w-96 border-l p-4 opacity-100" : "ml-0 w-0 border-l-0 p-0 opacity-0",
+                  // `flex-col` + a separate scroll body below: the header must stay
+                  // put while the panel content scrolls. Scrolling on this element
+                  // (as it did before) would carry the header away with the content.
+                  "flex h-full shrink-0 flex-col overflow-hidden transition-all duration-300 ease-in-out",
+                  showDetails ? "w-96 border-l opacity-100" : "ml-0 w-0 border-l-0 opacity-0",
                 )}
               >
-                {details}
+                {detailsTitle && (
+                  // Mirrors RoundPageContainerTitle's structure exactly — border on an
+                  // OUTER wrapper, height floor on the INNER row. Putting the border
+                  // inside the measured row instead leaves this header 1px short of
+                  // the page title bar, since `box-sizing: border-box` absorbs it.
+                  <div className="shrink-0 border-b">
+                    <div className={cn("flex items-center p-4", HEADER_ROW_MIN_H)}>
+                      <span className="text-primary truncate text-sm font-semibold">{detailsTitle}</span>
+                    </div>
+                  </div>
+                )}
+                <div className="min-h-0 flex-1 overflow-y-auto p-4">{details}</div>
               </div>
             ))}
         </div>

package/src/components/containers/RoundPageContainerTitle.tsx

@@ -7,9 +7,21 @@ import { cn, useIsMobile } from "@/utils";
 import { InfoIcon } from "lucide-react";
 import { ReactNode } from "react";
 
+/**
+ * Shared height floor for the card's top row. Applied BOTH here and to the
+ * `details` panel header in RoundPageContainer, so the two line up across the
+ * card's top edge. Expressed in px on purpose: the app scales its root
+ * font-size (14px), so a rem value would drift between the two rows.
+ */
+export const HEADER_ROW_MIN_H = "min-h-[53px]";
+
 type RoundPageContainerTitleProps = {
   module?: ModuleWithPermissions;
   details?: ReactNode;
+  /** Names what the toggle reveals, so the control is not an unlabelled icon. */
+  detailsTitle?: ReactNode;
+  /** Overrides the default info glyph — see `RoundPageContainer.detailsIcon`. */
+  detailsIcon?: ReactNode;
   showDetails: boolean;
   setShowDetails: (show: boolean) => void;
   fullWidth?: boolean;
@@ -18,6 +30,8 @@ type RoundPageContainerTitleProps = {
 export function RoundPageContainerTitle({
   module,
   details,
+  detailsTitle,
+  detailsIcon,
   showDetails,
   setShowDetails,
 }: RoundPageContainerTitleProps) {
@@ -26,7 +40,7 @@ export function RoundPageContainerTitle({
 
   return (
     <div className="flex w-full flex-col border-b">
-      <div className={cn(`flex w-full flex-row items-center gap-x-2 p-4 justify-between`)}>
+      <div className={cn(`flex w-full flex-row items-center gap-x-2 p-4 justify-between`, HEADER_ROW_MIN_H)}>
         {!isMobile ? (
           <div className="flex w-full gap-x-4">
             <div className={"text-muted-foreground flex items-center gap-x-2 text-lg font-light whitespace-nowrap"}>
@@ -56,16 +70,12 @@ export function RoundPageContainerTitle({
                     onClick={() => setShowDetails(!showDetails)}
                     className={cn(`cursor-pointer`)}
                   >
-                    {/* <InfoIcon className={cn(``, showDetails ? `text-muted-foreground` : `text-accent`)} /> */}
-                    <InfoIcon />
-                    {/* {showDetails ? (
-                      <PanelRightCloseIcon className="text-muted-foreground" />
-                    ) : (
-                      <PanelRightOpenIcon className="text-accent" />
-                    )} */}
+                    {detailsIcon ?? <InfoIcon />}
                   </Button>
                 </TooltipTrigger>
-                <TooltipContent>{showDetails ? "Hide details" : "Show details"}</TooltipContent>
+                <TooltipContent>
+                  {showDetails ? "Hide" : "Show"} {detailsTitle ?? "details"}
+                </TooltipContent>
               </Tooltip>
             )}
           </div>

package/src/components/navigations/Header.tsx

@@ -22,7 +22,21 @@ export function Header({ children, mobileChildren, leftContent, logo, className
   const isMobile = useIsMobile();
 
   return (
-    <header className={`sticky top-0 z-10 flex h-12 flex-col items-center justify-start gap-x-4 ${className ?? ""}`}>
+    // Outer element owns the safe-area inset; the inner row keeps h-12 so the
+    // content height is unchanged and only the notch padding is added above.
+    // bg-sidebar: the outer element has no background of its own, and a padded
+    // transparent strip would show scrolled content behind the status bar.
+    // The fallback is MANDATORY in this package: other consumers (neural-erp)
+    // never define --app-header-h, and a var() referencing an undefined
+    // property invalidates the whole declaration. The fallback MUST include the
+    // safe-area inset, because the padding below is unconditional: a consumer
+    // that never defines the variable but does set viewportFit: "cover" would
+    // otherwise get 3rem of height plus inset padding, squeezing the inner
+    // h-12 row. (Tailwind arbitrary values need _ for spaces; CSS calc needs
+    // whitespace around the +.)
+    <header
+      className={`bg-sidebar sticky top-0 z-10 flex h-[var(--app-header-h,calc(3rem_+_env(safe-area-inset-top)))] flex-col items-center justify-start gap-x-4 pt-[env(safe-area-inset-top)] ${className ?? ""}`}
+    >
       <div className="bg-sidebar flex h-12 w-full flex-row items-center justify-between pl-2 pr-4">
         {isMobile && logo && <div className="flex shrink-0 flex-row items-center pr-1">{logo}</div>}
         <SidebarTrigger aria-label="Toggle sidebar" id="sidebar-trigger" />

package/src/components/pages/PageContentContainer.tsx

@@ -35,7 +35,7 @@ export function PageContentContainer({ header, details, footer, content, fullBle
   });
 
   if (!isReady) {
-    return <div className="flex h-[calc(100vh-4rem)] w-full flex-col" />;
+    return <div className="flex h-[calc(100dvh-4rem)] w-full flex-col" />;
   }
 
   // v4 CRITICAL: Use STRING percentages for Panel defaultSize, not numbers!
@@ -46,7 +46,7 @@ export function PageContentContainer({ header, details, footer, content, fullBle
   const rightPanelDefaultSize = isMobile ? "90%" : "68%";
 
   return (
-    <div className="flex h-[calc(100vh-4rem)] w-full flex-col transition-opacity duration-150 animate-in fade-in">
+    <div className="flex h-[calc(100dvh-4rem)] w-full flex-col transition-opacity duration-150 animate-in fade-in">
       {header && <div className="mb-4 flex w-full shrink-0 border-b pr-4">{header}</div>}
       <div className="min-h-0 flex-1">
         {details || footer ? (

package/src/features/oauth/components/consent/OAuthConsentScreen.tsx

@@ -49,7 +49,7 @@ export function OAuthConsentScreen({
   // Loading state
   if (isLoading) {
     return (
-      <div className="min-h-screen flex items-center justify-center p-4">
+      <div className="min-h-dvh flex items-center justify-center p-4">
         <Card className="w-full max-w-md">
           <CardContent className="flex flex-col items-center justify-center py-12">
             <Loader2 className="h-8 w-8 animate-spin text-muted-foreground" />
@@ -63,7 +63,7 @@ export function OAuthConsentScreen({
   // Error state
   if (error || !clientInfo) {
     return (
-      <div className="min-h-screen flex items-center justify-center p-4">
+      <div className="min-h-dvh flex items-center justify-center p-4">
         <Card className="w-full max-w-md">
           <CardContent className="py-8">
             <Alert variant="destructive">
@@ -81,7 +81,7 @@ export function OAuthConsentScreen({
   const { client, scopes } = clientInfo;
 
   return (
-    <div className="min-h-screen flex items-center justify-center p-4 bg-muted/30">
+    <div className="min-h-dvh flex items-center justify-center p-4 bg-muted/30">
       <Card className="w-full max-w-md">
         <CardContent className="pt-6 space-y-6">
           {/* Header */}