@carlonicora/nextjs-jsonapi 1.117.1 → 1.119.0

package/dist/server/index.js

@@ -15,13 +15,13 @@ var _chunkIOLU4ASDjs = require('../chunk-IOLU4ASD.js');
 
 
 
-var _chunkS2PTWBN6js = require('../chunk-S2PTWBN6.js');
+var _chunk6P7MEU7Qjs = require('../chunk-6P7MEU7Q.js');
 require('../chunk-LXKSUWAV.js');
 require('../chunk-IBS6NI7D.js');
 
 
 
-var _chunkJ5LROFGLjs = require('../chunk-J5LROFGL.js');
+var _chunkRCMIVTVLjs = require('../chunk-RCMIVTVL.js');
 
 
 var _chunk7QVYU63Ejs = require('../chunk-7QVYU63E.js');
@@ -86,7 +86,7 @@ var ServerSession = class {
     if (!rawModules) return false;
     const modules = JSON.parse(_pako2.default.ungzip(Buffer.from(rawModules, "base64"), { to: "string" }));
     const selectedModule = modules.find((module) => module.id === params.module.moduleId);
-    return _chunkS2PTWBN6js.checkPermissionsFromServer.call(void 0, {
+    return _chunk6P7MEU7Qjs.checkPermissionsFromServer.call(void 0, {
       module: params.module,
       action: params.action,
       data: params.data,
@@ -158,7 +158,7 @@ async function ServerJsonApiGet(params) {
     language: params.language,
     additionalHeaders: _optionalChain([_serverConfig, 'optionalAccess', _23 => _23.additionalHeaders])
   });
-  return _chunkJ5LROFGLjs.translateResponse.call(void 0, {
+  return _chunkRCMIVTVLjs.translateResponse.call(void 0, {
     classKey: params.classKey,
     apiResponse,
     companyId: params.companyId,
@@ -179,7 +179,7 @@ async function ServerJsonApiPost(params) {
   if (!body) {
     body = {};
   } else if (params.overridesJsonApiCreation !== true) {
-    body = _chunkJ5LROFGLjs.JsonApiDataFactory.create(params.classKey, body);
+    body = _chunkRCMIVTVLjs.JsonApiDataFactory.create(params.classKey, body);
   }
   const apiResponse = await _chunkIOLU4ASDjs.serverRequest.call(void 0, {
     method: "POST",
@@ -191,7 +191,7 @@ async function ServerJsonApiPost(params) {
     language: params.language,
     additionalHeaders: _optionalChain([_serverConfig, 'optionalAccess', _24 => _24.additionalHeaders])
   });
-  return _chunkJ5LROFGLjs.translateResponse.call(void 0, {
+  return _chunkRCMIVTVLjs.translateResponse.call(void 0, {
     classKey: _nullishCoalesce(params.responseType, () => ( params.classKey)),
     apiResponse,
     companyId: params.companyId,
@@ -206,7 +206,7 @@ async function ServerJsonApiPut(params) {
   if (!body) {
     body = {};
   } else {
-    body = _chunkJ5LROFGLjs.JsonApiDataFactory.create(params.classKey, body);
+    body = _chunkRCMIVTVLjs.JsonApiDataFactory.create(params.classKey, body);
   }
   const apiResponse = await _chunkIOLU4ASDjs.serverRequest.call(void 0, {
     method: "PUT",
@@ -218,7 +218,7 @@ async function ServerJsonApiPut(params) {
     language: params.language,
     additionalHeaders: _optionalChain([_serverConfig, 'optionalAccess', _25 => _25.additionalHeaders])
   });
-  return _chunkJ5LROFGLjs.translateResponse.call(void 0, {
+  return _chunkRCMIVTVLjs.translateResponse.call(void 0, {
     classKey: _nullishCoalesce(params.responseType, () => ( params.classKey)),
     apiResponse,
     companyId: params.companyId,
@@ -233,7 +233,7 @@ async function ServerJsonApiPatch(params) {
   if (!body) {
     body = {};
   } else if (params.overridesJsonApiCreation !== true) {
-    body = _chunkJ5LROFGLjs.JsonApiDataFactory.create(params.classKey, body);
+    body = _chunkRCMIVTVLjs.JsonApiDataFactory.create(params.classKey, body);
   }
   const apiResponse = await _chunkIOLU4ASDjs.serverRequest.call(void 0, {
     method: "PATCH",
@@ -245,7 +245,7 @@ async function ServerJsonApiPatch(params) {
     language: params.language,
     additionalHeaders: _optionalChain([_serverConfig, 'optionalAccess', _26 => _26.additionalHeaders])
   });
-  return _chunkJ5LROFGLjs.translateResponse.call(void 0, {
+  return _chunkRCMIVTVLjs.translateResponse.call(void 0, {
     classKey: _nullishCoalesce(params.responseType, () => ( params.classKey)),
     apiResponse,
     companyId: params.companyId,
@@ -264,7 +264,7 @@ async function ServerJsonApiDelete(params) {
     language: params.language,
     additionalHeaders: _optionalChain([_serverConfig, 'optionalAccess', _27 => _27.additionalHeaders])
   });
-  return _chunkJ5LROFGLjs.translateResponse.call(void 0, {
+  return _chunkRCMIVTVLjs.translateResponse.call(void 0, {
     classKey: _nullishCoalesce(params.responseType, () => ( params.classKey)),
     apiResponse,
     companyId: params.companyId,
@@ -296,5 +296,5 @@ _chunk7QVYU63Ejs.__name.call(void 0, ServerJsonApiDelete, "ServerJsonApiDelete")
 
 
 
-exports.ServerAuthService = _chunkS2PTWBN6js.AuthService; exports.ServerCompanyService = _chunkS2PTWBN6js.CompanyService; exports.ServerContentService = _chunkS2PTWBN6js.ContentService; exports.ServerFeatureService = _chunkS2PTWBN6js.FeatureService; exports.ServerJsonApiDelete = ServerJsonApiDelete; exports.ServerJsonApiGet = ServerJsonApiGet; exports.ServerJsonApiPatch = ServerJsonApiPatch; exports.ServerJsonApiPost = ServerJsonApiPost; exports.ServerJsonApiPut = ServerJsonApiPut; exports.ServerNotificationService = _chunkS2PTWBN6js.NotificationService; exports.ServerPushService = _chunkS2PTWBN6js.PushService; exports.ServerRoleService = _chunkS2PTWBN6js.RoleService; exports.ServerS3Service = _chunkS2PTWBN6js.S3Service; exports.ServerSession = ServerSession; exports.ServerUserService = _chunkS2PTWBN6js.UserService; exports.configureServerJsonApi = configureServerJsonApi; exports.getServerApiUrl = getServerApiUrl; exports.getServerAppUrl = getServerAppUrl; exports.getServerToken = _chunkYUO55Q5Ajs.getServerToken; exports.getServerTrackablePages = getServerTrackablePages; exports.invalidateCacheTag = invalidateCacheTag; exports.invalidateCacheTags = invalidateCacheTags; exports.serverRequest = _chunkIOLU4ASDjs.serverRequest;
+exports.ServerAuthService = _chunk6P7MEU7Qjs.AuthService; exports.ServerCompanyService = _chunk6P7MEU7Qjs.CompanyService; exports.ServerContentService = _chunk6P7MEU7Qjs.ContentService; exports.ServerFeatureService = _chunk6P7MEU7Qjs.FeatureService; exports.ServerJsonApiDelete = ServerJsonApiDelete; exports.ServerJsonApiGet = ServerJsonApiGet; exports.ServerJsonApiPatch = ServerJsonApiPatch; exports.ServerJsonApiPost = ServerJsonApiPost; exports.ServerJsonApiPut = ServerJsonApiPut; exports.ServerNotificationService = _chunk6P7MEU7Qjs.NotificationService; exports.ServerPushService = _chunk6P7MEU7Qjs.PushService; exports.ServerRoleService = _chunk6P7MEU7Qjs.RoleService; exports.ServerS3Service = _chunk6P7MEU7Qjs.S3Service; exports.ServerSession = ServerSession; exports.ServerUserService = _chunk6P7MEU7Qjs.UserService; exports.configureServerJsonApi = configureServerJsonApi; exports.getServerApiUrl = getServerApiUrl; exports.getServerAppUrl = getServerAppUrl; exports.getServerToken = _chunkYUO55Q5Ajs.getServerToken; exports.getServerTrackablePages = getServerTrackablePages; exports.invalidateCacheTag = invalidateCacheTag; exports.invalidateCacheTags = invalidateCacheTags; exports.serverRequest = _chunkIOLU4ASDjs.serverRequest;
 //# sourceMappingURL=index.js.map

package/dist/server/index.mjs

@@ -15,13 +15,13 @@ import {
   S3Service,
   UserService,
   checkPermissionsFromServer
-} from "../chunk-M7XAKLSP.mjs";
+} from "../chunk-FWOS6PC5.mjs";
 import "../chunk-AUXK7QSA.mjs";
 import "../chunk-C7C7VY4F.mjs";
 import {
   JsonApiDataFactory,
   translateResponse
-} from "../chunk-KK7PYKVI.mjs";
+} from "../chunk-WC2BTKJP.mjs";
 import {
   __name
 } from "../chunk-PAWJFY3S.mjs";

package/package.json

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

package/src/client/JsonApiClient.ts

@@ -72,9 +72,18 @@ function runClientBootstrapper(): void {
   }
 }
 
-function buildClientUrl(endpoint: string): string {
-  const apiUrl = getClientApiUrl();
-  return endpoint.startsWith("http") ? endpoint : `${apiUrl}${endpoint}`;
+/**
+ * Resolve the final request URL for an endpoint (client-side variant of `buildUrl`
+ * in `unified/JsonApiRequest.ts` — kept in lockstep with it).
+ *
+ * - `endpoint` starting with "http" is always passed through unchanged (existing behaviour).
+ * - Otherwise, an explicit `baseUrl` (per-call override) takes precedence over the global
+ *   `getClientApiUrl()` resolution. Omitting `baseUrl` preserves today's behaviour exactly.
+ */
+export function buildClientUrl(endpoint: string, baseUrl?: string): string {
+  if (endpoint.startsWith("http")) return endpoint;
+  const apiUrl = baseUrl ?? getClientApiUrl();
+  return `${apiUrl}${endpoint}`;
 }
 
 export async function ClientJsonApiGet(params: {
@@ -82,13 +91,14 @@ export async function ClientJsonApiGet(params: {
   endpoint: string;
   companyId?: string;
   language: string;
+  baseUrl?: string;
 }): Promise<ApiResponseInterface> {
   runClientBootstrapper();
   const token = await getClientToken();
 
   const apiResponse = await directFetch({
     method: "GET",
-    url: buildClientUrl(params.endpoint),
+    url: buildClientUrl(params.endpoint, params.baseUrl),
     token,
     companyId: params.companyId,
     language: params.language,
@@ -106,6 +116,7 @@ export async function ClientJsonApiGet(params: {
         endpoint,
         companyId: params.companyId,
         language: params.language,
+        baseUrl: params.baseUrl,
       }),
   });
 }
@@ -119,6 +130,7 @@ export async function ClientJsonApiPost(params: {
   files?: { [key: string]: File | Blob } | File | Blob;
   language: string;
   responseType?: ApiRequestDataTypeInterface;
+  baseUrl?: string;
 }): Promise<ApiResponseInterface> {
   runClientBootstrapper();
   const token = await getClientToken();
@@ -132,7 +144,7 @@ export async function ClientJsonApiPost(params: {
 
   const apiResponse = await directFetch({
     method: "POST",
-    url: buildClientUrl(params.endpoint),
+    url: buildClientUrl(params.endpoint, params.baseUrl),
     token,
     body,
     files: params.files,
@@ -157,6 +169,7 @@ export async function ClientJsonApiPut(params: {
   files?: { [key: string]: File | Blob } | File | Blob;
   language: string;
   responseType?: ApiRequestDataTypeInterface;
+  baseUrl?: string;
 }): Promise<ApiResponseInterface> {
   runClientBootstrapper();
   const token = await getClientToken();
@@ -170,7 +183,7 @@ export async function ClientJsonApiPut(params: {
 
   const apiResponse = await directFetch({
     method: "PUT",
-    url: buildClientUrl(params.endpoint),
+    url: buildClientUrl(params.endpoint, params.baseUrl),
     token,
     body,
     files: params.files,
@@ -196,6 +209,7 @@ export async function ClientJsonApiPatch(params: {
   overridesJsonApiCreation?: boolean;
   responseType?: ApiRequestDataTypeInterface;
   language: string;
+  baseUrl?: string;
 }): Promise<ApiResponseInterface> {
   runClientBootstrapper();
   const token = await getClientToken();
@@ -209,7 +223,7 @@ export async function ClientJsonApiPatch(params: {
 
   const apiResponse = await directFetch({
     method: "PATCH",
-    url: buildClientUrl(params.endpoint),
+    url: buildClientUrl(params.endpoint, params.baseUrl),
     token,
     body,
     files: params.files,
@@ -232,13 +246,14 @@ export async function ClientJsonApiDelete(params: {
   companyId?: string;
   language: string;
   responseType?: ApiRequestDataTypeInterface;
+  baseUrl?: string;
 }): Promise<ApiResponseInterface> {
   runClientBootstrapper();
   const token = await getClientToken();
 
   const apiResponse = await directFetch({
     method: "DELETE",
-    url: buildClientUrl(params.endpoint),
+    url: buildClientUrl(params.endpoint, params.baseUrl),
     token,
     companyId: params.companyId,
     language: params.language,

package/src/client/__tests__/JsonApiClient.test.ts

@@ -0,0 +1,31 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { buildClientUrl } from "../JsonApiClient";
+
+describe("buildClientUrl", () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("uses NEXT_PUBLIC_API_URL when baseUrl is omitted", () => {
+    vi.stubEnv("NEXT_PUBLIC_API_URL", "https://api.example.com");
+
+    expect(buildClientUrl("/sncass/sync")).toBe("https://api.example.com/sncass/sync");
+  });
+
+  it("uses the per-call baseUrl override when provided", () => {
+    vi.stubEnv("NEXT_PUBLIC_API_URL", "https://api.example.com");
+
+    expect(buildClientUrl("/sncass/sync", "https://corpus.example.com")).toBe("https://corpus.example.com/sncass/sync");
+  });
+
+  it("passes through an http-prefixed endpoint regardless of baseUrl", () => {
+    vi.stubEnv("NEXT_PUBLIC_API_URL", "https://api.example.com");
+
+    expect(buildClientUrl("https://elsewhere.example.com/sncass/sync", "https://corpus.example.com")).toBe(
+      "https://elsewhere.example.com/sncass/sync",
+    );
+    expect(buildClientUrl("https://elsewhere.example.com/sncass/sync")).toBe(
+      "https://elsewhere.example.com/sncass/sync",
+    );
+  });
+});

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