@carlonicora/nextjs-jsonapi 6.26.0 → 6.28.0

package/src/components/containers/RoundPageContainer.tsx

@@ -18,6 +18,7 @@ import {
   TabsTrigger,
 } from "@/components";
 import { partitionTabs, Tab } from "@/components/containers";
+import { detailsFitsByDefault } from "@/components/containers/detailsFitsByDefault";
 import { HEADER_ROW_MIN_H, RoundPageContainerTitle } from "@/components/containers/RoundPageContainerTitle";
 import { Header, MobileNavigationBar } from "@/components/navigations";
 import { MicroLabel } from "@/components/typography";
@@ -118,6 +119,8 @@ type RoundPageContainerProps = {
    * navigation — an "info" icon actively misdescribes a conversation list.
    */
   detailsIcon?: ReactNode;
+  /** Paints the details panel on the recessed surface so cards inside it read as cards. Default "default" (unchanged). */
+  detailsSurface?: "default" | "muted";
   /**
    * Which element scrolls the page.
    * - `"document"` (default) — the shell's height only FLOORS at the viewport
@@ -186,6 +189,7 @@ export function RoundPageContainer({
   defaultDetailsOpen = false,
   detailsTitle,
   detailsIcon,
+  detailsSurface = "default",
   scroll = "fixed",
 }: RoundPageContainerProps) {
   const t = useTranslations();
@@ -207,8 +211,13 @@ export function RoundPageContainer({
   // without one (the customer portal) keeps the padding on both sides.
   const hasSidebar = useOptionalSidebar() !== null;
   const [mounted, setMounted] = useState(false);
+  // The page card; its inner width decides the details panel's default.
+  const cardRef = useRef<HTMLDivElement>(null);
 
+  // Runs once, on the first render after `mounted`: before that the container
+  // renders its placeholder and the card (measured below) does not exist yet.
   useEffect(() => {
+    if (!mounted) return;
     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
@@ -217,7 +226,22 @@ export function RoundPageContainer({
     // who explicitly collapsed the panel must stay collapsed on the next load.
     if (stored === "true") setShowDetailsState(true);
     else if (stored === "false") setShowDetailsState(false);
-  }, []);
+    // No stored choice yet: open when the page card fits the panel beside the
+    // centred content column. The card is measured, so the left sidebar's real
+    // state (open, minimised, absent) counts. Decided once, on load — resizing
+    // does not move it.
+    else if (
+      !defaultDetailsOpen &&
+      cardRef.current &&
+      detailsFitsByDefault({
+        cardInnerPx: cardRef.current.clientWidth,
+        remPx: parseFloat(getComputedStyle(document.documentElement).fontSize) || 16,
+        hasRail: layout === "rail" && !!tabs,
+        hasCentredColumn: !fullWidth && (!activeFillHeight || activeConstrainWidth),
+      })
+    )
+      setShowDetailsState(true);
+  }, [mounted]);
 
   useEffect(() => {
     setMounted(true);
@@ -433,7 +457,7 @@ export function RoundPageContainer({
             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 —
             it then appears only after scrolling to the very end of the page. */}
-        <div className="bg-background flex min-h-0 w-full flex-1 rounded-lg border p-0">
+        <div ref={cardRef} className="bg-background flex min-h-0 w-full flex-1 rounded-lg border p-0">
           {/* pb-16 under mobileFlow: room for the floating Help button, which
               otherwise sits over the last lines of the page. */}
           <div className={cn("flex w-full flex-col", mobileFlow && "min-h-0 overflow-y-auto pb-16")}>
@@ -681,7 +705,15 @@ export function RoundPageContainer({
                   <SheetHeader>
                     <SheetTitle>{detailsTitle ?? t("ui.labels.details")}</SheetTitle>
                   </SheetHeader>
-                  <div className="overflow-y-auto p-6 pt-0">{details}</div>
+                  <div
+                    data-slot="details-body"
+                    className={cn(
+                      "overflow-y-auto",
+                      detailsSurface === "muted" ? "bg-muted dark:bg-background p-3" : "p-6 pt-0",
+                    )}
+                  >
+                    {details}
+                  </div>
                 </SheetContent>
               </Sheet>
             ) : (
@@ -718,7 +750,15 @@ export function RoundPageContainer({
                     </div>
                   </div>
                 )}
-                <div className="min-h-0 flex-1 overflow-y-auto p-4">{details}</div>
+                <div
+                  data-slot="details-body"
+                  className={cn(
+                    "min-h-0 flex-1 overflow-y-auto",
+                    detailsSurface === "muted" ? "bg-muted dark:bg-background p-3" : "p-4",
+                  )}
+                >
+                  {details}
+                </div>
               </div>
             ))}
         </div>

package/src/components/containers/__tests__/RoundPageContainer.detailsSurface.spec.tsx

@@ -0,0 +1,82 @@
+import { render, screen } from "@testing-library/react";
+import { beforeAll, describe, expect, it, vi } from "vitest";
+import { SharedProvider } from "../../../contexts/SharedContext";
+import { configureI18n } from "../../../i18n";
+import { RoundPageContainer } from "../../containers/RoundPageContainer";
+
+vi.mock("next/navigation", () => ({
+  usePathname: () => "/",
+  useRouter: () => ({
+    push: vi.fn(),
+    replace: vi.fn(),
+    prefetch: vi.fn(),
+    back: vi.fn(),
+    forward: vi.fn(),
+    refresh: vi.fn(),
+  }),
+  useSearchParams: () => new URLSearchParams(),
+  useParams: () => ({}),
+  redirect: vi.fn(),
+  notFound: vi.fn(),
+}));
+
+beforeAll(() => {
+  configureI18n({
+    useRouter: () => ({
+      push: vi.fn(),
+      replace: vi.fn(),
+      back: vi.fn(),
+      forward: vi.fn(),
+      refresh: vi.fn(),
+      prefetch: vi.fn(),
+    }),
+    useTranslations: () => (key: string) => key,
+    usePathname: () => "/",
+    Link: ({ href, children, ...rest }: { href: string; children: React.ReactNode; [key: string]: any }) => (
+      <a href={href} {...rest}>
+        {children}
+      </a>
+    ),
+  });
+});
+
+function withShared(node: React.ReactNode) {
+  return <SharedProvider value={{ breadcrumbs: [], title: { type: "" } }}>{node}</SharedProvider>;
+}
+
+async function detailsBody(): Promise<HTMLElement> {
+  const content = await screen.findByText("d");
+  const body = content.closest<HTMLElement>('[data-slot="details-body"]');
+  if (!body) throw new Error("details body not found");
+  return body;
+}
+
+describe("RoundPageContainer details surface", () => {
+  it("default surface keeps the details body unpainted with p-4", async () => {
+    render(
+      withShared(
+        <RoundPageContainer testId="shell" details={<div>d</div>} defaultDetailsOpen>
+          content
+        </RoundPageContainer>,
+      ),
+    );
+    const body = await detailsBody();
+    expect(body.classList.contains("p-4")).toBe(true);
+    expect(body.classList.contains("bg-muted")).toBe(false);
+  });
+
+  it("muted surface paints the details body", async () => {
+    render(
+      withShared(
+        <RoundPageContainer testId="shell" details={<div>d</div>} defaultDetailsOpen detailsSurface="muted">
+          content
+        </RoundPageContainer>,
+      ),
+    );
+    const body = await detailsBody();
+    expect(body.classList.contains("bg-muted")).toBe(true);
+    expect(body.classList.contains("dark:bg-background")).toBe(true);
+    expect(body.classList.contains("p-3")).toBe(true);
+    expect(body.classList.contains("p-4")).toBe(false);
+  });
+});

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

@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vitest";
+import { detailsFitsByDefault } from "../detailsFitsByDefault";
+
+const base = { remPx: 16, hasRail: false, hasCentredColumn: true };
+
+describe("detailsFitsByDefault", () => {
+  it("needs column + padding + panel inside the card (1569px)", () => {
+    expect(detailsFitsByDefault({ ...base, cardInnerPx: 1569 })).toBe(true);
+    expect(detailsFitsByDefault({ ...base, cardInnerPx: 1568 })).toBe(false);
+  });
+
+  it("adds the section rail when the page has one (1793px)", () => {
+    expect(detailsFitsByDefault({ ...base, hasRail: true, cardInnerPx: 1793 })).toBe(true);
+    expect(detailsFitsByDefault({ ...base, hasRail: true, cardInnerPx: 1792 })).toBe(false);
+  });
+
+  it("scales with the root font size", () => {
+    expect(detailsFitsByDefault({ ...base, remPx: 20, cardInnerPx: 1961 })).toBe(true);
+    expect(detailsFitsByDefault({ ...base, remPx: 20, cardInnerPx: 1960 })).toBe(false);
+  });
+
+  it("stays closed on pages without a centred column", () => {
+    expect(detailsFitsByDefault({ ...base, hasCentredColumn: false, cardInnerPx: 4000 })).toBe(false);
+  });
+});

package/src/components/containers/detailsFitsByDefault.ts

@@ -0,0 +1,30 @@
+// Widths, in rem, of what has to fit INSIDE the page card next to each other.
+// Each value mirrors a class in RoundPageContainer — change them together.
+const RAIL_REM = 14; // section rail `md:w-56`, only on `layout="rail"` pages
+const CONTENT_PADDING_REM = 2; // `p-4` on both sides of the content column
+const CONTENT_COLUMN_REM = 72; // `max-w-6xl`
+const DETAILS_REM = 24; // details panel `w-96`
+const DETAILS_BORDER_PX = 1; // details panel `border-s`
+
+/**
+ * Whether the details panel fits beside the page's centred content column
+ * without squeezing it. Used only as the default when the user has never
+ * toggled the panel on this module.
+ *
+ * `cardInnerPx` is the measured inner width of the page card, so whatever sits
+ * outside it — the left sidebar open, minimised to icons or absent, the shell
+ * margins — is already accounted for.
+ *
+ * Pages without a centred column (`fullWidth`, or a full-bleed fill-height tab)
+ * have nothing to protect, so they return `false` and keep the closed default.
+ */
+export function detailsFitsByDefault(params: {
+  cardInnerPx: number;
+  remPx: number;
+  hasRail: boolean;
+  hasCentredColumn: boolean;
+}): boolean {
+  if (!params.hasCentredColumn) return false;
+  const rem = (params.hasRail ? RAIL_REM : 0) + CONTENT_PADDING_REM + CONTENT_COLUMN_REM + DETAILS_REM;
+  return params.cardInnerPx >= rem * params.remPx + DETAILS_BORDER_PX;
+}

package/src/components/typography/DetailField.tsx

@@ -6,6 +6,8 @@ type DetailFieldProps = React.ComponentProps<"div"> & {
   value?: React.ReactNode;
   horizontal?: boolean;
   labelWidth?: string;
+  /** Extra classes for the value element (e.g. "min-w-0 flex-1 break-words" so long values wrap in a horizontal row). */
+  valueClassName?: string;
 };
 
 function DetailField({
@@ -13,6 +15,7 @@ function DetailField({
   value,
   horizontal = false,
   labelWidth,
+  valueClassName,
   className,
   children,
   ...props
@@ -26,7 +29,7 @@ function DetailField({
       <span className={cn("text-muted-foreground text-xs", horizontal && labelWidth && cn("shrink-0", labelWidth))}>
         {label}
       </span>
-      <div className="text-sm">{value ?? children}</div>
+      <div className={cn("text-sm", valueClassName)}>{value ?? children}</div>
     </div>
   );
 }

package/src/components/typography/__tests__/DetailField.spec.tsx

@@ -0,0 +1,13 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { DetailField } from "../DetailField";
+
+describe("DetailField", () => {
+  it("valueClassName lands on the value element", () => {
+    render(<DetailField horizontal label="L" value="V" valueClassName="min-w-0 flex-1" />);
+    const value = screen.getByText("V");
+    expect(value.classList.contains("text-sm")).toBe(true);
+    expect(value.classList.contains("min-w-0")).toBe(true);
+    expect(value.classList.contains("flex-1")).toBe(true);
+  });
+});