@jinaan/uikit 0.1.39 → 0.1.41

package/dist/table-surface.d.ts

@@ -1,4 +1,4 @@
-import type { ReactNode } from "react";
+import type { ReactNode, Ref } from "react";
 export type TableSurfaceTone = "default" | "muted" | "transparent";
 export interface TableSurfaceAction {
     label: string;
@@ -29,6 +29,15 @@ interface TableSurfaceProps {
     panelClassName?: string;
     /** Minimum panel height; keeps empty states from collapsing. */
     minHeight?: string;
+    /**
+     * Where horizontal scrolling lives. `surface` (default) scrolls band and
+     * panel together — right for short content. `panel` keeps both shells fixed
+     * while the caller puts the scroller inside the panel; the band content is
+     * then expected to translate in lockstep via `headerContentRef`.
+     */
+    scrollMode?: "surface" | "panel";
+    /** Panel mode only: ref for the band's translating inner wrapper. */
+    headerContentRef?: Ref<HTMLDivElement>;
 }
 /**
  * Layered table surface: an outer shell holding a header band and an inset
@@ -37,6 +46,6 @@ interface TableSurfaceProps {
  * Colors come from the `--table-*` tokens and can be adjusted per surface with
  * `tone` plus `headerClassName` / `panelClassName`.
  */
-export declare function TableSurface({ title, description, header, children, action, tone, className, headerClassName, panelClassName, minHeight, }: TableSurfaceProps): import("react").JSX.Element;
+export declare function TableSurface({ title, description, header, children, action, tone, className, headerClassName, panelClassName, minHeight, scrollMode, headerContentRef, }: TableSurfaceProps): import("react").JSX.Element;
 export {};
 //# sourceMappingURL=table-surface.d.ts.map

package/dist/table-surface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"table-surface.d.ts","sourceRoot":"","sources":["../src/table-surface.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAMvC,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,OAAO,GAAG,aAAa,CAAC;AAEnE,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,aAAa,CAAC;IAC1D,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,UAAU,iBAAiB;IACzB,kCAAkC;IAClC,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,uCAAuC;IACvC,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,yDAAyD;IACzD,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,0EAA0E;IAC1E,QAAQ,EAAE,SAAS,CAAC;IACpB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,SAAS,GAAG,kBAAkB,CAAC;IACxC,8EAA8E;IAC9E,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,2DAA2D;IAC3D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAyBD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,EAC3B,KAAK,EACL,WAAW,EACX,MAAM,EACN,QAAQ,EACR,MAAM,EACN,IAAgB,EAChB,SAAS,EACT,eAAe,EACf,cAAc,EACd,SAAS,GACV,EAAE,iBAAiB,+BA8DnB"}
+{"version":3,"file":"table-surface.d.ts","sourceRoot":"","sources":["../src/table-surface.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAM5C,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,OAAO,GAAG,aAAa,CAAC;AAEnE,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,aAAa,CAAC;IAC1D,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,UAAU,iBAAiB;IACzB,kCAAkC;IAClC,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,uCAAuC;IACvC,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,yDAAyD;IACzD,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,0EAA0E;IAC1E,QAAQ,EAAE,SAAS,CAAC;IACpB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,SAAS,GAAG,kBAAkB,CAAC;IACxC,8EAA8E;IAC9E,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,2DAA2D;IAC3D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC;IACjC,qEAAqE;IACrE,gBAAgB,CAAC,EAAE,GAAG,CAAC,cAAc,CAAC,CAAC;CACxC;AAyBD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,EAC3B,KAAK,EACL,WAAW,EACX,MAAM,EACN,QAAQ,EACR,MAAM,EACN,IAAgB,EAChB,SAAS,EACT,eAAe,EACf,cAAc,EACd,SAAS,EACT,UAAsB,EACtB,gBAAgB,GACjB,EAAE,iBAAiB,+BAuFnB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jinaan/uikit",
-  "version": "0.1.39",
+  "version": "0.1.41",
   "description": "Reusable React and Tailwind UI components for Jinaan projects.",
   "license": "UNLICENSED",
   "type": "module",

package/src/data-table.tsx

@@ -12,7 +12,15 @@ import {
   WarningCircle,
   X,
 } from "@phosphor-icons/react";
-import { useEffect, useLayoutEffect, useMemo, useRef, useState, type ReactNode } from "react";
+import {
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
 
 import { Avatar, AvatarFallback, AvatarImage } from "./avatar";
 import { Button } from "./button";
@@ -117,6 +125,8 @@ interface DataTableProps<T> {
   filters?: DataTableFilter<T>[];
   toolbarStart?: ReactNode;
   toolbarEnd?: ReactNode;
+  /** Show the "Columns" visibility/reorder picker in the toolbar. Default true. */
+  columnPicker?: boolean;
 
   tabs?: TabDef[];
   activeTab?: string;
@@ -203,6 +213,7 @@ export function DataTable<T>({
   filters,
   toolbarStart,
   toolbarEnd,
+  columnPicker = true,
   tabs,
   activeTab,
   onTabChange,
@@ -354,20 +365,43 @@ export function DataTable<T>({
   // same pixel widths; both tables share the surface's horizontal scroller.
   const bodyTableRef = useRef<HTMLTableElement | null>(null);
   const bandTableRef = useRef<HTMLTableElement | null>(null);
+  const bandContentRef = useRef<HTMLDivElement | null>(null);
+  const scrollerRef = useRef<HTMLDivElement | null>(null);
   const [columnWidths, setColumnWidths] = useState<number[]>([]);
   // Deps must be primitives: visibleColumns is a fresh array every render and
   // would re-run this effect (and its setState) in a loop.
   const columnKey = visibleColumns.map((c) => c.id).join("\u0000");
+  // Identity of the rendered column set (selection, actions, visibility,
+  // order). The pinned colgroup maps positionally onto the columns, so any
+  // structural change invalidates the measured widths — otherwise the new
+  // column steals its neighbor's width and every column shifts by one.
+  const structureKey = `${selectable ? "s" : "-"}|${rowActions ? "a" : "-"}|${columnKey}`;
+  const structureRef = useRef(structureKey);
+  const pinned = columnWidths.length > 0;
+
+  // Panel-scroll mode: the band stays fixed to the shell and cannot scroll
+  // natively, so it translates by the row scroller's scrollLeft to keep every
+  // title over its column. Direct DOM write — no re-render per scroll event.
+  const syncBandScroll = useCallback(() => {
+    const band = bandContentRef.current;
+    const scroller = scrollerRef.current;
+    if (band && scroller) band.style.transform = `translateX(${-scroller.scrollLeft}px)`;
+  }, []);
 
   useLayoutEffect(() => {
     const table = bodyTableRef.current;
     if (!table) return;
+    if (structureRef.current !== structureKey) {
+      // Column set changed: drop the pinned widths so the body re-renders
+      // content-sized (table-auto) and the next pass measures intrinsic
+      // widths against the new structure. Without this, the effect would
+      // measure the stale colgroup's shifted layout and pin the wrong widths.
+      structureRef.current = structureKey;
+      setColumnWidths((prev) => (prev.length === 0 ? prev : []));
+      return;
+    }
     const measure = () => {
       const cells = table.tBodies[0]?.rows.item(0)?.cells;
-      // The band may be squeezed narrower than its own sort-button content by
-      // the body-measured widths; scrollWidth reports the true minimum, so it
-      // floors each column and stops titles from overflowing their neighbors.
-      const bandCells = bandTableRef.current?.querySelectorAll("thead th");
       if (!cells || cells.length === 0) {
         setColumnWidths((prev) => (prev.length === 0 ? prev : []));
         return;
@@ -375,10 +409,19 @@ export function DataTable<T>({
       // Widths cover every rendered column — including the selection checkbox
       // and row-actions cells — in order, so one <col> per entry maps 1:1 in
       // both colgroups. Never add extra <col> elements alongside these.
+      //
+      // Header floor: read the th's sizer span, never the th/cell layout
+      // itself. Once pinned with w-full, fixed-layout columns render wider
+      // than their content (surplus distribution) and reading them back would
+      // ratchet totalWidth up to the container size — after any container
+      // shrink the stale minWidth would keep a scrollbar alive forever. The
+      // sizer span is intrinsic in every state. Widths stay unrounded so the
+      // sum is the exact content requirement.
+      const bandThs = bandTableRef.current?.querySelectorAll("thead th");
       const widths = Array.from(cells, (cell, i) =>
         Math.max(
-          Math.round(cell.getBoundingClientRect().width),
-          Math.round(bandCells?.item(i)?.scrollWidth ?? 0),
+          cell.getBoundingClientRect().width,
+          bandThs?.item(i)?.querySelector("[data-col-sizer]")?.getBoundingClientRect().width ?? 0,
         ),
       );
       // Bail out when nothing changed: a new array would re-render, and the
@@ -388,11 +431,16 @@ export function DataTable<T>({
       );
     };
     measure();
+    syncBandScroll();
     if (typeof ResizeObserver === "undefined") return;
     const observer = new ResizeObserver(measure);
     observer.observe(table);
     return () => observer.disconnect();
-  }, [columnKey, selectable, rowActions, loading, error]);
+    // `pinned` re-runs this effect after the structure reset clears the
+    // widths (false) and again after re-pinning (true). Safe to measure in
+    // the pinned state because the floor reads sizer spans — intrinsic in
+    // every state — never the pinned layout itself.
+  }, [structureKey, pinned, loading, error, syncBandScroll]);
 
   const totalWidth = columnWidths.reduce((sum, width) => sum + width, 0);
 
@@ -439,84 +487,86 @@ export function DataTable<T>({
             />
           )}
           {toolbarStart}
-          <DropdownMenu>
-            <DropdownMenuTrigger asChild>
-              <Button
-                variant="secondary"
-                size="md"
-                leadingIcon={<ColumnsIcon />}
-                trailingIcon={<DropdownMenuChevron />}
-              >
-                Columns
-              </Button>
-            </DropdownMenuTrigger>
-            <DropdownMenuContent align="end" className="w-54">
-              <DropdownMenuLabel className="text-[13px]">Active columns</DropdownMenuLabel>
-              {visibleColumns.map((c) => {
-                const pinned = isPinned(c);
-                return (
-                  <DropdownMenuCheckboxItem
-                    key={c.id}
-                    checked
-                    draggable={!pinned}
-                    onDragStart={(e) => {
-                      if (pinned) {
-                        e.preventDefault();
-                        return;
-                      }
-                      e.dataTransfer.effectAllowed = "move";
-                      e.dataTransfer.setData("text/plain", c.id);
-                      setDragId(c.id);
-                    }}
-                    onDragOver={(e) => {
-                      if (dragId) {
-                        e.preventDefault();
-                        moveBefore(dragId, c.id);
-                      }
-                    }}
-                    onDrop={(e) => e.preventDefault()}
-                    onDragEnd={() => setDragId(null)}
-                    onCheckedChange={(next) => {
-                      if (!next && !pinned) {
-                        setHidden((prev) => ({ ...prev, [c.id]: true }));
-                      }
-                    }}
-                    onSelect={(e) => e.preventDefault()}
-                    className="justify-between"
-                  >
-                    <span className="truncate">{c.header}</span>
-                    {pinned ? (
-                      <Lock className="size-3.5 shrink-0 text-subtle" aria-hidden />
-                    ) : (
-                      <DotsSixVertical
-                        aria-hidden
-                        className={cn(
-                          "size-3.5 shrink-0",
-                          dragId === c.id ? "text-primary" : "text-subtle",
-                        )}
-                      />
-                    )}
-                  </DropdownMenuCheckboxItem>
-                );
-              })}
-              {hiddenColumns.length > 0 ? (
-                <>
-                  <DropdownMenuSeparator />
-                  <DropdownMenuLabel className="text-[13px]">Available columns</DropdownMenuLabel>
-                  {hiddenColumns.map((c) => (
+          {columnPicker && (
+            <DropdownMenu>
+              <DropdownMenuTrigger asChild>
+                <Button
+                  variant="secondary"
+                  size="md"
+                  leadingIcon={<ColumnsIcon />}
+                  trailingIcon={<DropdownMenuChevron />}
+                >
+                  Columns
+                </Button>
+              </DropdownMenuTrigger>
+              <DropdownMenuContent align="end" className="w-54">
+                <DropdownMenuLabel className="text-[13px]">Active columns</DropdownMenuLabel>
+                {visibleColumns.map((c) => {
+                  const pinned = isPinned(c);
+                  return (
                     <DropdownMenuCheckboxItem
                       key={c.id}
-                      checked={false}
-                      onCheckedChange={() => showColumn(c.id)}
+                      checked
+                      draggable={!pinned}
+                      onDragStart={(e) => {
+                        if (pinned) {
+                          e.preventDefault();
+                          return;
+                        }
+                        e.dataTransfer.effectAllowed = "move";
+                        e.dataTransfer.setData("text/plain", c.id);
+                        setDragId(c.id);
+                      }}
+                      onDragOver={(e) => {
+                        if (dragId) {
+                          e.preventDefault();
+                          moveBefore(dragId, c.id);
+                        }
+                      }}
+                      onDrop={(e) => e.preventDefault()}
+                      onDragEnd={() => setDragId(null)}
+                      onCheckedChange={(next) => {
+                        if (!next && !pinned) {
+                          setHidden((prev) => ({ ...prev, [c.id]: true }));
+                        }
+                      }}
                       onSelect={(e) => e.preventDefault()}
+                      className="justify-between"
                     >
-                      {c.header}
+                      <span className="truncate">{c.header}</span>
+                      {pinned ? (
+                        <Lock className="size-3.5 shrink-0 text-subtle" aria-hidden />
+                      ) : (
+                        <DotsSixVertical
+                          aria-hidden
+                          className={cn(
+                            "size-3.5 shrink-0",
+                            dragId === c.id ? "text-primary" : "text-subtle",
+                          )}
+                        />
+                      )}
                     </DropdownMenuCheckboxItem>
-                  ))}
-                </>
-              ) : null}
-            </DropdownMenuContent>
-          </DropdownMenu>
+                  );
+                })}
+                {hiddenColumns.length > 0 ? (
+                  <>
+                    <DropdownMenuSeparator />
+                    <DropdownMenuLabel className="text-[13px]">Available columns</DropdownMenuLabel>
+                    {hiddenColumns.map((c) => (
+                      <DropdownMenuCheckboxItem
+                        key={c.id}
+                        checked={false}
+                        onCheckedChange={() => showColumn(c.id)}
+                        onSelect={(e) => e.preventDefault()}
+                      >
+                        {c.header}
+                      </DropdownMenuCheckboxItem>
+                    ))}
+                  </>
+                ) : null}
+              </DropdownMenuContent>
+            </DropdownMenu>
+          )}
           {filters && filters.length > 0 ? (
             <DropdownMenu>
               <DropdownMenuTrigger asChild>
@@ -657,6 +707,8 @@ export function DataTable<T>({
       )}
 
       <TableSurface
+        scrollMode="panel"
+        headerContentRef={bandContentRef}
         action={headerAction}
         tone={tone}
         headerClassName={headerClassName}
@@ -670,7 +722,9 @@ export function DataTable<T>({
             role="presentation"
             className="w-full table-fixed border-collapse"
             style={{
-              width: totalWidth > 0 ? totalWidth : undefined,
+              // Fill the container when it fits; force totalWidth (and the
+              // shared scroller) only when the columns need more room.
+              minWidth: totalWidth > 0 ? totalWidth : undefined,
               visibility: totalWidth > 0 ? undefined : "hidden",
             }}
           >
@@ -681,8 +735,11 @@ export function DataTable<T>({
             </colgroup>
             <thead>
               <tr>
+                {/* text-left: UA stylesheets center th content; without this
+                    the select-all checkbox centers in its (surplus-widened)
+                    column and drifts right of the row checkboxes. */}
                 {selectable && (
-                  <th className="h-(--table-header-h) w-11 px-4 align-middle">
+                  <th className="h-(--table-header-h) w-11 px-(--table-pad-x) text-left align-middle">
                     <Checkbox
                       aria-label="Select all rows"
                       checked={allSelected ? true : someSelected ? "indeterminate" : false}
@@ -695,34 +752,44 @@ export function DataTable<T>({
                     key={c.id}
                     className={cn(HEADER_CELL, c.align === "right" && "text-right", c.className)}
                   >
-                    {c.sortable ? (
-                      <Button
-                        type="button"
-                        variant="ghost"
-                        size="xs"
-                        aria-label={`Sort by ${c.header}`}
-                        onClick={() => toggleSort(c)}
-                        className={cn(
-                          "h-auto gap-1.5 rounded-none px-0 py-0 text-[0.8125rem] text-table-header transition-colors [&_svg]:size-3.5",
-                          "hover:bg-transparent hover:text-table-header-active hover:shadow-none",
-                          "active:scale-100 active:bg-transparent active:shadow-none",
-                          sort?.id === c.id && "text-table-header-active",
-                        )}
-                      >
-                        {c.header}
-                        {sort?.id === c.id ? (
-                          sort.dir === "asc" ? (
-                            <CaretUp className="size-3.5" weight="bold" />
+                    {/* Sizer: shrink-wraps the title (sort carets included) so
+                        its rect is the column's intrinsic header width even
+                        while the fixed layout squeezes the th. The negative
+                        margins cancel the cell padding the span adds, so the
+                        measured width is directly comparable to cell widths. */}
+                    <span
+                      data-col-sizer
+                      className="inline-block whitespace-nowrap px-(--table-pad-x) -mx-(--table-pad-x)"
+                    >
+                      {c.sortable ? (
+                        <Button
+                          type="button"
+                          variant="ghost"
+                          size="xs"
+                          aria-label={`Sort by ${c.header}`}
+                          onClick={() => toggleSort(c)}
+                          className={cn(
+                            "h-auto gap-1.5 rounded-none px-0 py-0 text-[0.8125rem] text-table-header transition-colors [&_svg]:size-3.5",
+                            "hover:bg-transparent hover:text-table-header-active hover:shadow-none",
+                            "active:scale-100 active:bg-transparent active:shadow-none",
+                            sort?.id === c.id && "text-table-header-active",
+                          )}
+                        >
+                          {c.header}
+                          {sort?.id === c.id ? (
+                            sort.dir === "asc" ? (
+                              <CaretUp className="size-3.5" weight="bold" />
+                            ) : (
+                              <CaretDown className="size-3.5" weight="bold" />
+                            )
                           ) : (
-                            <CaretDown className="size-3.5" weight="bold" />
-                          )
-                        ) : (
-                          <CaretUpDown className="size-3.5 opacity-50" />
-                        )}
-                      </Button>
-                    ) : (
-                      c.header
-                    )}
+                            <CaretUpDown className="size-3.5 opacity-50" />
+                          )}
+                        </Button>
+                      ) : (
+                        c.header
+                      )}
+                    </span>
                   </th>
                 ))}
                 {rowActions && (
@@ -735,6 +802,10 @@ export function DataTable<T>({
           </table>
         }
       >
+        {/* The scroller lives inside the panel: both shells stay fixed while
+            only the row content scrolls, and onScroll keeps the band titles
+            translated in lockstep with the rows. */}
+        <div ref={scrollerRef} className="overflow-x-auto" onScroll={syncBandScroll}>
             {loading ? (
               <div className="space-y-2 p-4">
                 {[0, 1, 2].map((i) => (
@@ -772,10 +843,12 @@ export function DataTable<T>({
                   "border-collapse text-left",
                   // Unmeasured: content-sized so intrinsic column widths can be
                   // measured (w-full would squeeze columns into the container).
-                  // Measured: pinned to the band's colgroup pixel widths.
+                  // Measured: fill the container, pinned to the band's colgroup
+                  // pixel widths; minWidth forces the shared scroller open only
+                  // when the columns need more room than the container has.
                   columnWidths.length > 0 ? "w-full table-fixed" : "table-auto",
                 )}
-                style={{ width: totalWidth > 0 ? totalWidth : undefined }}
+                style={{ minWidth: totalWidth > 0 ? totalWidth : undefined }}
               >
                 {columnWidths.length > 0 && (
                   <colgroup>
@@ -808,7 +881,7 @@ export function DataTable<T>({
                         className={onRowClick ? "cursor-pointer" : undefined}
                       >
                         {selectable && (
-                          <TableCell className="w-11 px-4" onClick={(e) => e.stopPropagation()}>
+                          <TableCell className="w-11" onClick={(e) => e.stopPropagation()}>
                             <Checkbox
                               aria-label="Select row"
                               checked={isSelected}
@@ -836,7 +909,8 @@ export function DataTable<T>({
                 </TableBody>
               </table>
             )}
-          </TableSurface>
+        </div>
+      </TableSurface>
 
       {showPagination && (
         <div className="flex flex-wrap items-center justify-between gap-3 text-sm">

package/src/table-surface.tsx

@@ -1,4 +1,4 @@
-import type { ReactNode } from "react";
+import type { ReactNode, Ref } from "react";
 
 import { Button } from "./button";
 import { TableContainer, TablePanel } from "./table";
@@ -36,6 +36,15 @@ interface TableSurfaceProps {
   panelClassName?: string;
   /** Minimum panel height; keeps empty states from collapsing. */
   minHeight?: string;
+  /**
+   * Where horizontal scrolling lives. `surface` (default) scrolls band and
+   * panel together — right for short content. `panel` keeps both shells fixed
+   * while the caller puts the scroller inside the panel; the band content is
+   * then expected to translate in lockstep via `headerContentRef`.
+   */
+  scrollMode?: "surface" | "panel";
+  /** Panel mode only: ref for the band's translating inner wrapper. */
+  headerContentRef?: Ref<HTMLDivElement>;
 }
 
 const SHELL_TONE: Record<TableSurfaceTone, string> = {
@@ -79,8 +88,11 @@ export function TableSurface({
   headerClassName,
   panelClassName,
   minHeight,
+  scrollMode = "surface",
+  headerContentRef,
 }: TableSurfaceProps) {
   const hasTitle = Boolean(title || description);
+  const panelScroll = scrollMode === "panel";
   const actionNode = isActionConfig(action) ? (
     <Button
       variant={action.variant ?? "primary"}
@@ -103,37 +115,61 @@ export function TableSurface({
     action
   );
 
-  return (
-    <TableContainer className={cn("relative", SHELL_TONE[tone], className)}>
-      <div className="overflow-x-auto">
-        {header || hasTitle ? (
-          // Header rows must not inherit the body row hover surface.
-          <div className={cn("[--table-row-hover:transparent] text-table-header", headerClassName)}>
-            {hasTitle ? (
-              <div
-                className={cn(
-                  "px-(--table-pad-x) pb-3 pt-4",
-                  actionNode && "pr-28",
-                )}
-              >
-                {title ? (
-                  <div className="text-sm font-semibold text-fg">{title}</div>
-                ) : null}
-                {description ? (
-                  <div className="mt-0.5 text-sm text-muted">{description}</div>
-                ) : null}
-              </div>
+  const band =
+    header || hasTitle ? (
+      // Header rows must not inherit the body row hover surface. Panel mode
+      // clips the band instead of scrolling it; the caller translates the
+      // inner wrapper so titles track the row content. px-px mirrors the
+      // panel's 1px border so band and body share the same width context —
+      // identical fixed-layout distribution keeps every column aligned.
+      <div
+        className={cn(
+          "[--table-row-hover:transparent] text-table-header",
+          panelScroll && "overflow-hidden px-px",
+          headerClassName,
+        )}
+      >
+        {hasTitle ? (
+          <div
+            className={cn(
+              "px-(--table-pad-x) pb-3 pt-4",
+              actionNode && "pr-28",
+            )}
+          >
+            {title ? (
+              <div className="text-sm font-semibold text-fg">{title}</div>
+            ) : null}
+            {description ? (
+              <div className="mt-0.5 text-sm text-muted">{description}</div>
             ) : null}
-            {header}
           </div>
         ) : null}
-        <TablePanel
-          className={cn(PANEL_TONE[tone], panelClassName)}
-          style={minHeight ? { minHeight } : undefined}
-        >
-          {children}
-        </TablePanel>
+        {panelScroll ? <div ref={headerContentRef}>{header}</div> : header}
       </div>
+    ) : null;
+
+  const panel = (
+    <TablePanel
+      className={cn(PANEL_TONE[tone], panelClassName)}
+      style={minHeight ? { minHeight } : undefined}
+    >
+      {children}
+    </TablePanel>
+  );
+
+  return (
+    <TableContainer className={cn("relative", SHELL_TONE[tone], className)}>
+      {panelScroll ? (
+        <>
+          {band}
+          {panel}
+        </>
+      ) : (
+        <div className="overflow-x-auto">
+          {band}
+          {panel}
+        </div>
+      )}
       {actionNode ? (
         <div className="pointer-events-none absolute right-4 top-(--table-inset) flex h-(--table-header-h) items-center">
           <div className="pointer-events-auto">{actionNode}</div>