@carlonicora/nextjs-jsonapi 1.117.0 → 1.118.0

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";

package/src/components/containers/partitionTabs.ts

@@ -0,0 +1,43 @@
+import { Tab } from "./TabsContainer";
+
+export type PartitionedTabs = {
+  ungrouped: Tab[];
+  groups: Array<{ label: string; items: Tab[] }>;
+};
+
+/**
+ * Split a `Tab[]` into ungrouped + grouped strata for the
+ * `RoundPageContainer` `layout="rail"` navigation.
+ *
+ * Tabs without a `group` land in `ungrouped` (the pinned stratum) in declared
+ * order. Grouped tabs cluster under their `group` label; groups appear in the
+ * order they first occur in the input array.
+ *
+ * Pure function — safe to call on every render. Complexity O(n).
+ */
+export function partitionTabs(tabs: Tab[]): PartitionedTabs {
+  const ungrouped: Tab[] = [];
+  const groupMap = new Map<string, Tab[]>();
+  const groupOrder: string[] = [];
+
+  for (const tab of tabs) {
+    if (!tab.group) {
+      ungrouped.push(tab);
+      continue;
+    }
+    if (!groupMap.has(tab.group)) {
+      groupMap.set(tab.group, []);
+      groupOrder.push(tab.group);
+    }
+    // The map entry is guaranteed to exist because we just initialized it.
+    groupMap.get(tab.group)!.push(tab);
+  }
+
+  return {
+    ungrouped,
+    groups: groupOrder.map((label) => ({
+      label,
+      items: groupMap.get(label)!,
+    })),
+  };
+}

package/src/components/forms/EditorSheet.tsx

@@ -1,7 +1,7 @@
 "use client";
 
 import { useTranslations } from "next-intl";
-import { ReactNode, useCallback, useEffect, useRef } from "react";
+import { ReactElement, ReactNode, useCallback, useEffect, useRef } from "react";
 import { FieldValues, UseFormReturn } from "react-hook-form";
 import { PencilIcon } from "lucide-react";
 import { ModuleWithPermissions } from "../../permissions/types";
@@ -161,7 +161,12 @@ export function EditorSheet<T extends FieldValues>({
         {dialogOpen === undefined &&
           forceShow === undefined &&
           (trigger ? (
-            <SheetTrigger>{trigger}</SheetTrigger>
+            // Base UI: the trigger renders its own <button>. Pass the caller's
+            // element via `render` (NOT as children) so it BECOMES the trigger
+            // button — otherwise an interactive trigger (e.g. <Button>) nests a
+            // <button> inside SheetTrigger's <button> (invalid HTML / hydration
+            // error). `render` also preserves the element's native `disabled`.
+            <SheetTrigger render={trigger as ReactElement} />
           ) : (
             <SheetTrigger>
               {isEdit ? (

package/src/components/navigations/Breadcrumb.tsx

@@ -45,7 +45,13 @@ function BreadcrumbDesktop({
         {items.length > ITEMS_TO_DISPLAY ? (
           <>
             <BreadcrumbItem>
-              {items[0].href ? <Link href={items[0].href}>{items[0].name}</Link> : <>{items[0].name}</>}
+              {items[0].href ? (
+                <Link href={items[0].href} onClick={items[0].onClick}>
+                  {items[0].name}
+                </Link>
+              ) : (
+                <>{items[0].name}</>
+              )}
             </BreadcrumbItem>
             <BreadcrumbSeparator />
             <BreadcrumbItem>
@@ -56,7 +62,9 @@ function BreadcrumbDesktop({
                 <DropdownMenuContent align="start">
                   {items.slice(1, -ITEMS_TO_DISPLAY + 2).map((item, index) => (
                     <DropdownMenuItem key={index}>
-                      <Link href={item.href ? item.href : "#"}>{item.name}</Link>
+                      <Link href={item.href ? item.href : "#"} onClick={item.onClick}>
+                        {item.name}
+                      </Link>
                     </DropdownMenuItem>
                   ))}
                 </DropdownMenuContent>
@@ -66,7 +74,13 @@ function BreadcrumbDesktop({
             {items.slice(-ITEMS_TO_DISPLAY + 2).map((item, index) => (
               <Fragment key={index}>
                 <BreadcrumbItem>
-                  {item.href ? <Link href={item.href}>{item.name}</Link> : <>{item.name}</>}
+                  {item.href ? (
+                    <Link href={item.href} onClick={item.onClick}>
+                      {item.name}
+                    </Link>
+                  ) : (
+                    <>{item.name}</>
+                  )}
                 </BreadcrumbItem>
                 {index < items.slice(-ITEMS_TO_DISPLAY + 2).length - 1 && <BreadcrumbSeparator />}
               </Fragment>
@@ -77,7 +91,13 @@ function BreadcrumbDesktop({
             {items.map((item, index) => (
               <Fragment key={index}>
                 <BreadcrumbItem>
-                  {item.href ? <Link href={item.href}>{item.name}</Link> : <>{item.name}</>}
+                  {item.href ? (
+                    <Link href={item.href} onClick={item.onClick}>
+                      {item.name}
+                    </Link>
+                  ) : (
+                    <>{item.name}</>
+                  )}
                 </BreadcrumbItem>
                 {index < items.length - 1 && <BreadcrumbSeparator />}
               </Fragment>
@@ -124,7 +144,13 @@ function BreadcrumbMobile({
       <DropdownMenuContent align="start">
         {allItems.map((item, index) => (
           <DropdownMenuItem key={index}>
-            {item.href ? <Link href={item.href}>{item.name}</Link> : <>{item.name}</>}
+            {item.href ? (
+              <Link href={item.href} onClick={item.onClick}>
+                {item.name}
+              </Link>
+            ) : (
+              <>{item.name}</>
+            )}
           </DropdownMenuItem>
         ))}
       </DropdownMenuContent>

package/src/hooks/useSocket.ts

@@ -114,7 +114,18 @@ export function useSocket({ token }: UseSocketOptions): UseSocketReturn {
     };
 
     const handleNotification = (data: any) => {
-      const notification = rehydrate(Modules.Notification, data) as NotificationInterface;
+      // The socket sends a JSON:API document { data, included }; rehydrate expects
+      // { jsonApi, included }. Map it (and guard against an unexpected shape so a
+      // malformed payload never throws an uncaught error that breaks the socket).
+      const resource = data?.data ?? data?.jsonApi;
+      if (!resource?.type) {
+        console.warn("[useSocket] ignoring notification with unexpected payload shape", data);
+        return;
+      }
+      const notification = rehydrate(Modules.Notification, {
+        jsonApi: resource,
+        included: data?.included || [],
+      }) as NotificationInterface;
       if (notification) {
         setSocketNotifications((prev) => {
           const newNotifications = [...prev, notification];

package/src/interfaces/breadcrumb.item.data.interface.ts

@@ -1,4 +1,5 @@
 export type BreadcrumbItemData = {
   name: string;
   href?: string;
+  onClick?: () => void;
 };