@carlonicora/nextjs-jsonapi 1.117.1 → 1.118.0

package/dist/features/help/index.js

@@ -21,7 +21,7 @@ var _chunkYBZVWLPHjs = require('../../chunk-YBZVWLPH.js');
 
 
 
-var _chunk56QAXZKIjs = require('../../chunk-56QAXZKI.js');
+var _chunkM2ODDWY3js = require('../../chunk-M2ODDWY3.js');
 
 
 var _chunk6KLR3WJQjs = require('../../chunk-6KLR3WJQ.js');
@@ -73,29 +73,29 @@ var _lucidereact = require('lucide-react');
 
 
 function HelpAssistantSheet({ open, onOpenChange }) {
-  return /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunk56QAXZKIjs.Sheet, { open, onOpenChange, children: /* @__PURE__ */ _jsxruntime.jsx.call(void 0, 
-    _chunk56QAXZKIjs.SheetContent,
+  return /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkM2ODDWY3js.Sheet, { open, onOpenChange, children: /* @__PURE__ */ _jsxruntime.jsx.call(void 0, 
+    _chunkM2ODDWY3js.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, _chunk56QAXZKIjs.AssistantProvider, { manageUrl: false, children: /* @__PURE__ */ _jsxruntime.jsx.call(void 0, HelpAssistantSheetBody, {}) })
+      children: /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkM2ODDWY3js.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 = _chunk56QAXZKIjs.useAssistantContext.call(void 0, );
+  const ctx = _chunkM2ODDWY3js.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, _chunk56QAXZKIjs.SheetHeader, { children: [
-      /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunk56QAXZKIjs.SheetTitle, { children: t("help.askAi.sheet.title") }),
-      /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunk56QAXZKIjs.SheetDescription, { children: t("help.askAi.sheet.subtitle") })
+    /* @__PURE__ */ _jsxruntime.jsxs.call(void 0, _chunkM2ODDWY3js.SheetHeader, { children: [
+      /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkM2ODDWY3js.SheetTitle, { children: t("help.askAi.sheet.title") }),
+      /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkM2ODDWY3js.SheetDescription, { children: t("help.askAi.sheet.subtitle") })
     ] }),
-    !showThread ? /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunk56QAXZKIjs.AssistantEmptyState, { onSend: send }) : /* @__PURE__ */ _jsxruntime.jsxs.call(void 0, _jsxruntime.Fragment, { children: [
+    !showThread ? /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkM2ODDWY3js.AssistantEmptyState, { onSend: send }) : /* @__PURE__ */ _jsxruntime.jsxs.call(void 0, _jsxruntime.Fragment, { children: [
       /* @__PURE__ */ _jsxruntime.jsx.call(void 0, 
-        _chunk56QAXZKIjs.AssistantThread,
+        _chunkM2ODDWY3js.AssistantThread,
         {
           messages: ctx.messages,
           sending: ctx.sending,
@@ -105,7 +105,7 @@ function HelpAssistantSheetBody() {
           onRetry: ctx.retrySend
         }
       ),
-      /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunk56QAXZKIjs.AssistantComposer, { onSend: send, disabled: ctx.sending })
+      /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkM2ODDWY3js.AssistantComposer, { onSend: send, disabled: ctx.sending })
     ] })
   ] });
 }
@@ -115,20 +115,20 @@ _chunk7QVYU63Ejs.__name.call(void 0, HelpAssistantSheetBody, "HelpAssistantSheet
 
 function HelpAskAi() {
   const t = _nextintl.useTranslations.call(void 0, );
-  const { currentUser } = _chunk56QAXZKIjs.useCurrentUserContext.call(void 0, );
+  const { currentUser } = _chunkM2ODDWY3js.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, _chunk56QAXZKIjs.Tooltip, { children: [
-      /* @__PURE__ */ _jsxruntime.jsxs.call(void 0, _chunk56QAXZKIjs.TooltipTrigger, { render: /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunk56QAXZKIjs.Button, { variant: "outline", size: "sm", disabled: true }), children: [
+    return /* @__PURE__ */ _jsxruntime.jsxs.call(void 0, _chunkM2ODDWY3js.Tooltip, { children: [
+      /* @__PURE__ */ _jsxruntime.jsxs.call(void 0, _chunkM2ODDWY3js.TooltipTrigger, { render: /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkM2ODDWY3js.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, _chunk56QAXZKIjs.TooltipContent, { children: t("help.askAi.loginTooltip") })
+      /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkM2ODDWY3js.TooltipContent, { children: t("help.askAi.loginTooltip") })
     ] });
   }
   return /* @__PURE__ */ _jsxruntime.jsxs.call(void 0, _jsxruntime.Fragment, { children: [
-    /* @__PURE__ */ _jsxruntime.jsxs.call(void 0, _chunk56QAXZKIjs.Button, { variant: "outline", size: "sm", onClick: () => setOpen(true), children: [
+    /* @__PURE__ */ _jsxruntime.jsxs.call(void 0, _chunkM2ODDWY3js.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")
     ] }),
@@ -141,7 +141,7 @@ _chunk7QVYU63Ejs.__name.call(void 0, HelpAskAi, "HelpAskAi");
 
 function HelpHeader() {
   const t = _nextintl.useTranslations.call(void 0, );
-  const { currentUser } = _chunk56QAXZKIjs.useCurrentUserContext.call(void 0, );
+  const { currentUser } = _chunkM2ODDWY3js.useCurrentUserContext.call(void 0, );
   const { brand } = useHelp();
   const logo = _optionalChain([brand, 'optionalAccess', _ => _.logo]);
   const label = _nullishCoalesce(_optionalChain([brand, 'optionalAccess', _2 => _2.label]), () => ( "Help"));
@@ -157,7 +157,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, _chunk56QAXZKIjs.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, _chunk56QAXZKIjs.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, _chunkM2ODDWY3js.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, _chunkM2ODDWY3js.Button, { render: /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _link2.default, { href: "/login" }), nativeButton: false, variant: "outline", size: "sm", children: t("help.header.login") })
     ] })
   ] });
 }
@@ -199,7 +199,7 @@ _chunk7QVYU63Ejs.__name.call(void 0, useHelpFilter, "useHelpFilter");
 
 function HelpSideNav() {
   const t = _nextintl.useTranslations.call(void 0, );
-  const generateUrl = _chunk56QAXZKIjs.usePageUrlGenerator.call(void 0, );
+  const generateUrl = _chunkM2ODDWY3js.usePageUrlGenerator.call(void 0, );
   const pathname = _navigation.usePathname.call(void 0, );
   const [articles, setArticles] = _react.useState.call(void 0, []);
   _react.useEffect.call(void 0, () => {
@@ -280,7 +280,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 = _chunk56QAXZKIjs.usePageUrlGenerator.call(void 0, );
+  const generateUrl = _chunkM2ODDWY3js.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: [
@@ -358,7 +358,7 @@ _chunk7QVYU63Ejs.__name.call(void 0, HelpTOC, "HelpTOC");
 
 function HelpHint({ contextKey }) {
   const t = _nextintl.useTranslations.call(void 0, );
-  const generateUrl = _chunk56QAXZKIjs.usePageUrlGenerator.call(void 0, );
+  const generateUrl = _chunkM2ODDWY3js.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, []);
@@ -376,7 +376,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, 
-    _chunk56QAXZKIjs.Sheet,
+    _chunkM2ODDWY3js.Sheet,
     {
       open,
       onOpenChange: (o) => {
@@ -384,11 +384,11 @@ function HelpHint({ contextKey }) {
         if (!o) setPicked(null);
       },
       children: [
-        /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunk56QAXZKIjs.SheetTrigger, { render: /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunk56QAXZKIjs.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, _chunk56QAXZKIjs.SheetContent, { side: "right", className: "w-full max-w-md sm:max-w-lg", children: [
-          /* @__PURE__ */ _jsxruntime.jsxs.call(void 0, _chunk56QAXZKIjs.SheetHeader, { children: [
-            /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunk56QAXZKIjs.SheetTitle, { children: active ? active.name : t("help.hint.pickArticle") }),
-            /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunk56QAXZKIjs.SheetDescription, { children: _nullishCoalesce(_optionalChain([active, 'optionalAccess', _4 => _4.summary]), () => ( "")) })
+        /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkM2ODDWY3js.SheetTrigger, { render: /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkM2ODDWY3js.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, _chunkM2ODDWY3js.SheetContent, { side: "right", className: "w-full max-w-md sm:max-w-lg", children: [
+          /* @__PURE__ */ _jsxruntime.jsxs.call(void 0, _chunkM2ODDWY3js.SheetHeader, { children: [
+            /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkM2ODDWY3js.SheetTitle, { children: active ? active.name : t("help.hint.pickArticle") }),
+            /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkM2ODDWY3js.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 }),
@@ -420,7 +420,7 @@ _chunk7QVYU63Ejs.__name.call(void 0, HelpHint, "HelpHint");
 
 function HelpSearchResultRow({ result, onSelect }) {
   const t = _nextintl.useTranslations.call(void 0, );
-  const generateUrl = _chunk56QAXZKIjs.usePageUrlGenerator.call(void 0, );
+  const generateUrl = _chunkM2ODDWY3js.usePageUrlGenerator.call(void 0, );
   const [article, setArticle] = _react.useState.call(void 0, null);
   _react.useEffect.call(void 0, () => {
     let active = true;
@@ -431,7 +431,7 @@ function HelpSearchResultRow({ result, onSelect }) {
   }, [result.id]);
   if (!article) {
     return /* @__PURE__ */ _jsxruntime.jsx.call(void 0, 
-      _chunk56QAXZKIjs.CommandItem,
+      _chunkM2ODDWY3js.CommandItem,
       {
         value: result.id,
         disabled: true,
@@ -440,7 +440,7 @@ function HelpSearchResultRow({ result, onSelect }) {
       }
     );
   }
-  return /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunk56QAXZKIjs.CommandItem, { value: result.id, onSelect, className: "cursor-pointer p-0", children: /* @__PURE__ */ _jsxruntime.jsxs.call(void 0, 
+  return /* @__PURE__ */ _jsxruntime.jsx.call(void 0, _chunkM2ODDWY3js.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

@@ -21,7 +21,7 @@ import {
   useAssistantContext,
   useCurrentUserContext,
   usePageUrlGenerator
-} from "../../chunk-6D4GJHLK.mjs";
+} from "../../chunk-KXHEOLPZ.mjs";
 import {
   _getStaticHelpContent
 } from "../../chunk-WEPQD5MP.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carlonicora/nextjs-jsonapi",
-  "version": "1.117.1",
+  "version": "1.118.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

@@ -3,7 +3,9 @@
 import {
   Select,
   SelectContent,
+  SelectGroup,
   SelectItem,
+  SelectLabel,
   SelectTrigger,
   SelectValue,
   Sheet,
@@ -15,7 +17,7 @@ import {
   TabsList,
   TabsTrigger,
 } from "@/components";
-import { Tab } from "@/components/containers";
+import { partitionTabs, Tab } from "@/components/containers";
 import { RoundPageContainerTitle } from "@/components/containers/RoundPageContainerTitle";
 import { Header } from "@/components/navigations";
 import { useHeaderChildren, useHeaderLeftContent } from "@/contexts";
@@ -23,7 +25,7 @@ import { useUrlRewriter } from "@/hooks";
 import { cn, useIsMobile } from "@/index";
 import { ModuleWithPermissions } from "@/permissions";
 import { useSearchParams } from "next/navigation";
-import { ReactNode, useCallback, useEffect, useState } from "react";
+import { Fragment, ReactNode, useCallback, useEffect, useMemo, useState } from "react";
 
 const DETAILS_COOKIE_NAME = "round_page_details_state";
 const DETAILS_COOKIE_MAX_AGE = 60 * 60 * 24 * 7;
@@ -37,8 +39,31 @@ type RoundPageContainerProps = {
   fullWidth?: boolean;
   forceHeader?: boolean;
   header?: ReactNode;
+  /**
+   * Section-navigation layout for `tabs`.
+   * - `"tabs"` (default) — horizontal `TabsList` (desktop) / `Select` (mobile).
+   *   Unchanged from prior behaviour; existing callers need no edits.
+   * - `"rail"` — vertical 220px left rail grouped by each tab's `group`, with a
+   *   `<md` grouped `Select` fallback. Mirrors the retired
+   *   `PageContainerContentDetails` rail.
+   */
+  layout?: "tabs" | "rail";
 };
 
+// Rail trigger class: override the horizontal TabsTrigger defaults for a
+// vertical, left-aligned, dark-filled active state. tailwind-merge inside cn()
+// resolves the conflicts with the base classes.
+const railTriggerClass = cn(
+  "flex w-full items-center justify-start rounded-md px-3 py-1.5 text-left text-sm leading-tight whitespace-normal",
+  "text-muted-foreground",
+  "hover:bg-muted hover:text-foreground",
+  "data-[state=active]:bg-foreground data-[state=active]:text-background",
+  "data-[state=active]:font-semibold data-[state=active]:shadow-none",
+);
+
+/** Stable value for the URL `?section=` and active-tab matching. */
+const tabValue = (tab: Tab): string => tab.sectionKey ?? tab.key?.name ?? tab.label;
+
 export function RoundPageContainer({
   module,
   id,
@@ -48,6 +73,7 @@ export function RoundPageContainer({
   fullWidth,
   forceHeader,
   header,
+  layout = "tabs",
 }: RoundPageContainerProps) {
   const headerChildren = useHeaderChildren();
   const headerLeftContent = useHeaderLeftContent();
@@ -75,15 +101,14 @@ export function RoundPageContainer({
   const rewriteUrl = useUrlRewriter();
 
   const initialValue = tabs
-    ? (section && tabs.find((i) => (i.key?.name ?? i.label) === section) ? section : null) ||
-      (tabs[0].key?.name ?? tabs[0].label)
+    ? (section && tabs.find((i) => tabValue(i) === section) ? section : null) || tabValue(tabs[0])
     : undefined;
 
   const [activeTab, setActiveTab] = useState(initialValue);
 
   useEffect(() => {
     if (tabs && section) {
-      const tab = tabs.find((i) => (i.key?.name ?? i.label) === section);
+      const tab = tabs.find((i) => tabValue(i) === section);
       if (tab) {
         setActiveTab(section);
       }
@@ -98,7 +123,10 @@ export function RoundPageContainer({
     [module, id, rewriteUrl],
   );
 
-  const activeFillHeight = tabs?.find((t) => (t.key?.name ?? t.label) === activeTab)?.fillHeight === true;
+  const activeFillHeight = tabs?.find((t) => tabValue(t) === activeTab)?.fillHeight === true;
+
+  // Rail partition — only consumed by `layout="rail"` but cheap to compute.
+  const { ungrouped, groups } = useMemo(() => partitionTabs(tabs ?? []), [tabs]);
 
   const isReady = mounted && isMobile !== undefined;
 
@@ -135,85 +163,178 @@ export function RoundPageContainer({
               />
             )}
             <div className="flex h-full w-full overflow-hidden">
-              <div
-                className={cn(
-                  `grow`,
-                  isMobile ? `p-2` : `p-4`,
-                  activeFillHeight ? `flex flex-col overflow-hidden` : `overflow-y-auto`,
-                  fullWidth && `p-0`,
-                )}
-              >
+              {layout === "rail" && tabs ? (
+                // Rail layout: the vertical-tab navigation is a flush-left
+                // sidebar of the card and the content fills the full remaining
+                // width (like `fullWidth`) — NOT the centred max-w-6xl column.
+                <Tabs
+                  value={activeTab}
+                  onValueChange={handleTabChange}
+                  orientation="vertical"
+                  className="flex h-full min-w-0 grow overflow-hidden"
+                >
+                  {/* Flush-left section rail — md and up */}
+                  <aside
+                    data-testid="round-page-rail"
+                    className="hidden shrink-0 border-r p-4 md:flex md:w-56 md:flex-col md:overflow-y-auto"
+                  >
+                    <TabsList className="flex h-auto flex-col items-stretch gap-0.5 bg-transparent p-0">
+                      {ungrouped.map((tab) => (
+                        <TabsTrigger key={tab.label} value={tabValue(tab)} className={railTriggerClass}>
+                          {tab.contentLabel ?? tab.label}
+                        </TabsTrigger>
+                      ))}
+                      {groups.map((group) => (
+                        <Fragment key={group.label}>
+                          <div
+                            role="presentation"
+                            className="text-muted-foreground px-3 pt-3 pb-1 text-[10px] font-bold tracking-wider uppercase"
+                          >
+                            {group.label}
+                          </div>
+                          {group.items.map((tab) => (
+                            <TabsTrigger key={tab.label} value={tabValue(tab)} className={railTriggerClass}>
+                              {tab.contentLabel ?? tab.label}
+                            </TabsTrigger>
+                          ))}
+                        </Fragment>
+                      ))}
+                    </TabsList>
+                  </aside>
+
+                  {/* Content — full width, fills the remaining space */}
+                  <div className="flex min-w-0 grow flex-col overflow-hidden">
+                    {/* Section Select — below md */}
+                    <div data-testid="round-page-rail-select" className="p-2 md:hidden">
+                      <Select
+                        value={activeTab}
+                        onValueChange={(value) => {
+                          if (value) handleTabChange(value);
+                        }}
+                      >
+                        <SelectTrigger className="w-full">
+                          <SelectValue />
+                        </SelectTrigger>
+                        <SelectContent>
+                          {ungrouped.map((tab) => (
+                            <SelectItem key={tab.label} value={tabValue(tab)}>
+                              {tab.contentLabel ?? tab.label}
+                            </SelectItem>
+                          ))}
+                          {groups.map((group) => (
+                            <SelectGroup key={group.label}>
+                              <SelectLabel>{group.label}</SelectLabel>
+                              {group.items.map((tab) => (
+                                <SelectItem key={tab.label} value={tabValue(tab)}>
+                                  {tab.contentLabel ?? tab.label}
+                                </SelectItem>
+                              ))}
+                            </SelectGroup>
+                          ))}
+                        </SelectContent>
+                      </Select>
+                    </div>
+                    <div
+                      className={cn(
+                        `min-w-0 grow`,
+                        activeFillHeight ? `flex flex-col overflow-hidden` : `overflow-y-auto`,
+                      )}
+                    >
+                      {header}
+                      {tabs.map((tab) => (
+                        <TabsContent
+                          key={tab.label}
+                          value={tabValue(tab)}
+                          className={tab.fillHeight ? `flex min-h-0 w-full flex-1 flex-col` : ``}
+                        >
+                          {tab.content}
+                        </TabsContent>
+                      ))}
+                      {children && <div className="flex">{children}</div>}
+                    </div>
+                  </div>
+                </Tabs>
+              ) : (
                 <div
                   className={cn(
-                    `mx-auto max-w-6xl space-y-8`,
-                    activeFillHeight && `flex w-full flex-1 min-h-0 flex-col space-y-0`,
-                    fullWidth && `max-w-full w-full p-0 h-full`,
+                    `grow`,
+                    isMobile ? `p-2` : `p-4`,
+                    activeFillHeight ? `flex flex-col overflow-hidden` : `overflow-y-auto`,
+                    fullWidth && `p-0`,
                   )}
                 >
-                  {header}
-                  {tabs ? (
-                    <>
-                      <Tabs
-                        value={activeTab}
-                        className={cn(`w-full`, activeFillHeight && `flex flex-1 min-h-0 flex-col`)}
-                        onValueChange={handleTabChange}
-                      >
-                        {isMobile ? (
-                          <div className="p-0">
-                            <Select
-                              value={activeTab}
-                              onValueChange={(value) => {
-                                if (value) handleTabChange(value);
-                              }}
-                            >
-                              <SelectTrigger className="w-full">
-                                <SelectValue />
-                              </SelectTrigger>
-                              <SelectContent>
+                  <div
+                    className={cn(
+                      `mx-auto max-w-6xl space-y-8`,
+                      activeFillHeight && `flex w-full flex-1 min-h-0 flex-col space-y-0`,
+                      fullWidth && `max-w-full w-full p-0 h-full`,
+                    )}
+                  >
+                    {header}
+                    {tabs ? (
+                      <>
+                        <Tabs
+                          value={activeTab}
+                          className={cn(`w-full`, activeFillHeight && `flex flex-1 min-h-0 flex-col`)}
+                          onValueChange={handleTabChange}
+                        >
+                          {isMobile ? (
+                            <div className="p-0">
+                              <Select
+                                value={activeTab}
+                                onValueChange={(value) => {
+                                  if (value) handleTabChange(value);
+                                }}
+                              >
+                                <SelectTrigger className="w-full">
+                                  <SelectValue />
+                                </SelectTrigger>
+                                <SelectContent>
+                                  {tabs.map((tab) => (
+                                    <SelectItem key={tab.label} value={tabValue(tab)}>
+                                      {tab.contentLabel ?? tab.label}
+                                    </SelectItem>
+                                  ))}
+                                </SelectContent>
+                              </Select>
+                            </div>
+                          ) : (
+                            <div className="p-4">
+                              <TabsList>
                                 {tabs.map((tab) => (
-                                  <SelectItem key={tab.label} value={tab.key?.name ?? tab.label}>
+                                  <TabsTrigger key={tab.label} value={tabValue(tab)} className="px-4">
                                     {tab.contentLabel ?? tab.label}
-                                  </SelectItem>
+                                  </TabsTrigger>
                                 ))}
-                              </SelectContent>
-                            </Select>
-                          </div>
-                        ) : (
-                          <div className="p-4">
-                            <TabsList>
-                              {tabs.map((tab) => (
-                                <TabsTrigger key={tab.label} value={tab.key?.name ?? tab.label} className="px-4">
-                                  {tab.contentLabel ?? tab.label}
-                                </TabsTrigger>
-                              ))}
-                            </TabsList>
-                          </div>
-                        )}
-                        <div
-                          className={cn(
-                            `flex w-full `,
-                            isMobile ? `` : `px-4`,
-                            activeFillHeight ? `flex-1 min-h-0` : `overflow-y-auto`,
+                              </TabsList>
+                            </div>
                           )}
-                        >
-                          {tabs.map((tab) => (
-                            <TabsContent
-                              key={tab.label}
-                              value={tab.key?.name ?? tab.label}
-                              className={tab.fillHeight ? `flex flex-1 min-h-0 w-full flex-col` : `pb-20`}
-                            >
-                              {tab.content}
-                            </TabsContent>
-                          ))}
-                        </div>
-                      </Tabs>
-                      {children && <div className={cn(`flex`, isMobile ? `px-2` : `px-4`)}>{children}</div>}
-                    </>
-                  ) : (
-                    children
-                  )}
+                          <div
+                            className={cn(
+                              `flex w-full `,
+                              isMobile ? `` : `px-4`,
+                              activeFillHeight ? `flex-1 min-h-0` : `overflow-y-auto`,
+                            )}
+                          >
+                            {tabs.map((tab) => (
+                              <TabsContent
+                                key={tab.label}
+                                value={tabValue(tab)}
+                                className={tab.fillHeight ? `flex flex-1 min-h-0 w-full flex-col` : `pb-20`}
+                              >
+                                {tab.content}
+                              </TabsContent>
+                            ))}
+                          </div>
+                        </Tabs>
+                        {children && <div className={cn(`flex`, isMobile ? `px-2` : `px-4`)}>{children}</div>}
+                      </>
+                    ) : (
+                      children
+                    )}
+                  </div>
                 </div>
-              </div>
+              )}
               {details &&
                 (isMobile ? (
                   <Sheet open={showDetails} onOpenChange={setShowDetails}>

package/src/components/containers/TabsContainer.tsx

@@ -13,6 +13,20 @@ export type Tab = {
   content: React.ReactNode;
   modules?: ModuleWithPermissions[];
   action?: Action;
+  /**
+   * Section header this tab clusters under in the `RoundPageContainer`
+   * `layout="rail"` navigation. Tabs without a `group` render at the top of the
+   * rail (the "pinned" stratum) in declared order; groups render in first-seen
+   * order. Ignored by the default `layout="tabs"` (flat) rendering.
+   */
+  group?: string;
+  /**
+   * Stable identifier used for the URL `?section=` value and active-tab
+   * matching. Defaults to `key?.name ?? label`. Provide this for tabs that have
+   * no `key` (no backing module) but still need a stable, locale-independent
+   * deep link — e.g. `"dashboard"`, `"analysis"`, `"timeline"`.
+   */
+  sectionKey?: string;
   /**
    * When true, the tab content fills the available viewport height inside its
    * container. The tab's wrapper chain switches to a flex-column layout with

package/src/components/containers/__tests__/partitionTabs.spec.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from "vitest";
+import { partitionTabs } from "../partitionTabs";
+import type { Tab } from "../TabsContainer";
+
+const tab = (label: string, group?: string): Tab => ({
+  label,
+  content: null,
+  group,
+});
+
+describe("partitionTabs", () => {
+  it("returns empty partition for empty input", () => {
+    expect(partitionTabs([])).toEqual({ ungrouped: [], groups: [] });
+  });
+
+  it("keeps tabs without a group in the ungrouped stratum, in declared order", () => {
+    const result = partitionTabs([tab("a"), tab("b"), tab("c")]);
+    expect(result.ungrouped.map((t) => t.label)).toEqual(["a", "b", "c"]);
+    expect(result.groups).toEqual([]);
+  });
+
+  it("clusters tabs by group label", () => {
+    const result = partitionTabs([tab("a", "Casebook"), tab("b", "Casebook"), tab("c", "Work")]);
+    expect(result.ungrouped).toEqual([]);
+    expect(result.groups).toEqual([
+      { label: "Casebook", items: [expect.objectContaining({ label: "a" }), expect.objectContaining({ label: "b" })] },
+      { label: "Work", items: [expect.objectContaining({ label: "c" })] },
+    ]);
+  });
+
+  it("renders groups in the order they first appear", () => {
+    const result = partitionTabs([tab("a", "Work"), tab("b", "Casebook"), tab("c", "Work"), tab("d", "Casebook")]);
+    expect(result.groups.map((g) => g.label)).toEqual(["Work", "Casebook"]);
+    expect(result.groups[0].items.map((t) => t.label)).toEqual(["a", "c"]);
+    expect(result.groups[1].items.map((t) => t.label)).toEqual(["b", "d"]);
+  });
+
+  it("preserves ungrouped tabs above grouped tabs regardless of array order", () => {
+    const result = partitionTabs([tab("one", "Work"), tab("two"), tab("three", "Work"), tab("four")]);
+    expect(result.ungrouped.map((t) => t.label)).toEqual(["two", "four"]);
+    expect(result.groups).toHaveLength(1);
+    expect(result.groups[0].items.map((t) => t.label)).toEqual(["one", "three"]);
+  });
+
+  it("treats an empty-string group as 'no group'", () => {
+    const result = partitionTabs([tab("a", ""), tab("b", "Work")]);
+    expect(result.ungrouped.map((t) => t.label)).toEqual(["a"]);
+    expect(result.groups).toHaveLength(1);
+    expect(result.groups[0].label).toBe("Work");
+  });
+});

package/src/components/containers/index.ts

@@ -1,4 +1,5 @@
 export * from "./PageContainer";
+export * from "./partitionTabs";
 export * from "./ReactMarkdownContainer";
 export * from "./RoundPageContainer";
 export * from "./RoundPageContainerTitle";