@jinaan/uikit 0.1.3 → 0.1.5

package/src/dialog.tsx

@@ -1,46 +1,289 @@
 import * as DialogPrimitive from "@radix-ui/react-dialog";
 import { X } from "@phosphor-icons/react";
 import {
+  createContext,
   forwardRef,
+  useCallback,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
   type ComponentPropsWithoutRef,
   type ElementRef,
   type HTMLAttributes,
 } from "react";
 
+import { computeDialogFlight, type DialogOriginRect } from "./dialog-motion";
 import { cn } from "./utils";
 
-export const Dialog = DialogPrimitive.Root;
-export const DialogTrigger = DialogPrimitive.Trigger;
+const SOURCE_SELECTOR =
+  'button, a, [role="button"], [role="menuitem"], [data-dialog-origin]';
+
+let lastSource: { rect: DialogOriginRect; at: number } | null = null;
+let trackerInstalled = false;
+
+function rectOf(element: Element): DialogOriginRect | null {
+  const rect = element.getBoundingClientRect();
+  if (rect.width <= 0 || rect.height <= 0) return null;
+  return {
+    left: rect.left,
+    top: rect.top,
+    width: rect.width,
+    height: rect.height,
+  };
+}
+
+function rememberSource(target: EventTarget | null) {
+  if (!(target instanceof Element)) return;
+  const element = target.closest(SOURCE_SELECTOR);
+  if (!element) return;
+  const rect = rectOf(element);
+  if (rect) lastSource = { rect, at: Date.now() };
+}
+
+function installSourceTracker() {
+  if (trackerInstalled || typeof document === "undefined") return;
+  trackerInstalled = true;
+  document.addEventListener(
+    "pointerdown",
+    (event) => rememberSource(event.target),
+    true,
+  );
+  document.addEventListener(
+    "keydown",
+    (event) => {
+      if (event.key !== "Enter" && event.key !== " ") return;
+      rememberSource(document.activeElement);
+    },
+    true,
+  );
+}
+
+function resolveOrigin(content: HTMLElement): DialogOriginRect | null {
+  if (lastSource && Date.now() - lastSource.at < 2000) {
+    const rect = lastSource.rect;
+    lastSource = null;
+    return rect;
+  }
+  lastSource = null;
+
+  const active = document.activeElement;
+  if (
+    active instanceof Element &&
+    active !== content &&
+    !content.contains(active) &&
+    active.matches(SOURCE_SELECTOR)
+  ) {
+    return rectOf(active);
+  }
+  return null;
+}
+
+const DIALOG_CLOSE_MS = 250;
+const DialogClosingContext = createContext(false);
+
+/** Dialog root; owns the delayed close so the fly-out can finish. */
+export function Dialog({
+  open: controlledOpen,
+  defaultOpen,
+  onOpenChange,
+  children,
+  ...props
+}: ComponentPropsWithoutRef<typeof DialogPrimitive.Root>) {
+  const [uncontrolledOpen, setUncontrolledOpen] = useState(
+    defaultOpen ?? false,
+  );
+  const [closing, setClosing] = useState(false);
+  const closeTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const open = controlledOpen ?? uncontrolledOpen;
+  const openRef = useRef(open);
+  openRef.current = open;
+  const controlled = controlledOpen !== undefined;
+
+  useEffect(() => installSourceTracker(), []);
+
+  useEffect(() => {
+    if (controlledOpen) setClosing(false);
+  }, [controlledOpen]);
+
+  useEffect(
+    () => () => {
+      if (closeTimer.current) clearTimeout(closeTimer.current);
+    },
+    [],
+  );
+
+  const handleOpenChange = (next: boolean) => {
+    if (next) {
+      if (closeTimer.current) clearTimeout(closeTimer.current);
+      setClosing(false);
+      if (!controlled) setUncontrolledOpen(true);
+      onOpenChange?.(true);
+      return;
+    }
+    if (!open || closing) return;
+
+    const reduced =
+      typeof window !== "undefined" &&
+      typeof window.matchMedia === "function" &&
+      window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+    if (reduced) {
+      if (!controlled) setUncontrolledOpen(false);
+      onOpenChange?.(false);
+      return;
+    }
+
+    setClosing(true);
+    closeTimer.current = setTimeout(() => {
+      if (!controlled) setUncontrolledOpen(false);
+      onOpenChange?.(false);
+      requestAnimationFrame(() => {
+        // Restore the overlay only when a controlled parent vetoed the close.
+        if (openRef.current) setClosing(false);
+      });
+    }, DIALOG_CLOSE_MS);
+  };
+
+  return (
+    <DialogClosingContext.Provider value={closing}>
+      <DialogPrimitive.Root
+        open={open}
+        onOpenChange={handleOpenChange}
+        {...props}
+      >
+        {children}
+      </DialogPrimitive.Root>
+    </DialogClosingContext.Provider>
+  );
+}
+
+export const DialogTrigger = forwardRef<
+  ElementRef<typeof DialogPrimitive.Trigger>,
+  ComponentPropsWithoutRef<typeof DialogPrimitive.Trigger>
+>(({ onClick, ...props }, ref) => (
+  <DialogPrimitive.Trigger
+    ref={ref}
+    onClick={(event) => {
+      rememberSource(event.currentTarget);
+      onClick?.(event);
+    }}
+    {...props}
+  />
+));
+DialogTrigger.displayName = "DialogTrigger";
+
 export const DialogClose = DialogPrimitive.Close;
 
+function startDialogMotion(content: HTMLDivElement, retry = true) {
+  if (content.dataset.dialogMotionStarted === "true") return;
+  if (
+    typeof window !== "undefined" &&
+    typeof window.matchMedia === "function" &&
+    window.matchMedia("(prefers-reduced-motion: reduce)").matches
+  ) {
+    return;
+  }
+
+  const target = rectOf(content);
+  if (!target) {
+    if (retry) {
+      window.requestAnimationFrame(() => startDialogMotion(content, false));
+    }
+    return;
+  }
+
+  content.dataset.dialogMotionStarted = "true";
+  const origin = resolveOrigin(content);
+  const flight = origin ? computeDialogFlight(origin, target) : null;
+  if (flight) {
+    content.style.setProperty("--dialog-dx", `${flight.dx}px`);
+    content.style.setProperty("--dialog-dy", `${flight.dy}px`);
+    content.style.setProperty("--dialog-sx", String(flight.sx));
+    content.style.setProperty("--dialog-sy", String(flight.sy));
+    content.classList.add("dialog-fly-in");
+  } else {
+    content.classList.add("dialog-pop-in");
+  }
+
+  const clear = () => {
+    content.classList.remove("dialog-fly-in", "dialog-pop-in");
+    content.style.removeProperty("--dialog-dx");
+    content.style.removeProperty("--dialog-dy");
+    content.style.removeProperty("--dialog-sx");
+    content.style.removeProperty("--dialog-sy");
+  };
+  const onEnd = (event: AnimationEvent) => {
+    if (event.target !== content) return;
+    if (
+      event.animationName !== "dialog-fly-in" &&
+      event.animationName !== "dialog-pop-in"
+    ) {
+      return;
+    }
+    content.removeEventListener("animationend", onEnd);
+    clear();
+  };
+  content.addEventListener("animationend", onEnd);
+}
+
 export const DialogContent = forwardRef<
   ElementRef<typeof DialogPrimitive.Content>,
   ComponentPropsWithoutRef<typeof DialogPrimitive.Content>
->(({ className, children, ...props }, ref) => (
-  <DialogPrimitive.Portal>
-    <DialogPrimitive.Overlay className="fixed inset-0 z-50 bg-overlay backdrop-blur-[1px] data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=closed]:animate-out data-[state=closed]:fade-out-0" />
-    <DialogPrimitive.Content
-      ref={ref}
-      className={cn(
-        "fixed left-1/2 top-1/2 z-50 flex max-h-[min(85vh,44rem)] w-full max-w-[22.4rem] -translate-x-1/2 -translate-y-1/2 flex-col gap-0 overflow-hidden",
-        "rounded-2xl border border-[var(--dialog-shell-border)] bg-[var(--dialog-shell-bg)] pb-3 shadow-[var(--dialog-shell-shadow)] sm:pb-4",
-        "data-[state=open]:animate-in data-[state=closed]:animate-out",
-        "data-[state=open]:fade-in-0 data-[state=closed]:fade-out-0",
-        "data-[state=open]:zoom-in-95 data-[state=closed]:zoom-out-95",
-        "data-[state=open]:slide-in-from-top-2 duration-200 ease-out",
-        "focus:outline-none",
-        className,
-      )}
-      {...props}
-    >
-      {children}
-      <DialogPrimitive.Close className="absolute right-3.5 top-3.5 z-10 rounded-sm text-subtle transition-colors hover:text-fg focus-visible:outline-none">
-        <X className="size-4" />
-        <span className="sr-only">Close</span>
-      </DialogPrimitive.Close>
-    </DialogPrimitive.Content>
-  </DialogPrimitive.Portal>
-));
+>(({ className, children, ...props }, ref) => {
+  const closing = useContext(DialogClosingContext);
+  const contentRef = useRef<HTMLDivElement>(null);
+  const setRef = useCallback(
+    (node: HTMLDivElement | null) => {
+      contentRef.current = node;
+      if (node) startDialogMotion(node);
+      if (typeof ref === "function") {
+        ref(node);
+        return;
+      }
+      if (ref) {
+        (ref as { current: HTMLDivElement | null }).current = node;
+      }
+    },
+    [ref],
+  );
+
+  return (
+    <DialogPrimitive.Portal>
+      <DialogPrimitive.Overlay
+        className={cn(
+          "fixed inset-0 z-50 overflow-hidden bg-overlay data-[state=open]:animate-in data-[state=open]:fade-in-0",
+          !closing &&
+            "data-[state=closed]:animate-out data-[state=closed]:fade-out-0",
+          closing && "opacity-0 transition-opacity duration-200",
+        )}
+      >
+        <span
+          aria-hidden="true"
+          className="dialog-noise pointer-events-none absolute inset-0"
+        />
+      </DialogPrimitive.Overlay>
+      <div className="pointer-events-none fixed inset-0 z-50 flex items-center justify-center overflow-y-auto p-4">
+        <DialogPrimitive.Content
+          ref={setRef}
+          className={cn(
+            "dialog-content pointer-events-auto relative flex max-h-[min(85vh,44rem)] w-full max-w-[22.4rem] flex-col gap-0 overflow-hidden will-change-[transform,opacity]",
+            "rounded-2xl border border-(--dialog-shell-border) bg-(--dialog-shell-bg) pb-3 shadow-(--dialog-shell-shadow) sm:pb-4",
+            closing && "dialog-closing",
+            "focus:outline-none",
+            className,
+          )}
+          {...props}
+        >
+          {children}
+          <DialogPrimitive.Close className="absolute right-3.5 top-3.5 z-10 rounded-sm text-subtle transition-colors hover:text-fg focus-visible:outline-none">
+            <X className="size-4" />
+            <span className="sr-only">Close</span>
+          </DialogPrimitive.Close>
+        </DialogPrimitive.Content>
+      </div>
+    </DialogPrimitive.Portal>
+  );
+});
 DialogContent.displayName = "DialogContent";
 
 /**
@@ -48,12 +291,15 @@ DialogContent.displayName = "DialogContent";
  * and right edges (the shell clips its top corners); the footer stays below on
  * the shell so the two surfaces read as distinct layers.
  */
-export function DialogPanel({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
+export function DialogPanel({
+  className,
+  ...props
+}: HTMLAttributes<HTMLDivElement>) {
   return (
     <div
       data-slot="panel"
       className={cn(
-        "flex min-h-0 flex-1 flex-col overflow-hidden rounded-b-2xl border-x-0 border-t-0 border-b border-[var(--dialog-panel-border)] bg-[var(--dialog-panel-bg)] shadow-[var(--dialog-panel-shadow)]",
+        "flex min-h-0 flex-1 flex-col overflow-hidden rounded-b-2xl border-x-0 border-t-0 border-b border-(--dialog-panel-border) bg-(--dialog-panel-bg) shadow-(--dialog-panel-shadow)",
         className,
       )}
       {...props}
@@ -62,7 +308,10 @@ export function DialogPanel({ className, ...props }: HTMLAttributes<HTMLDivEleme
 }
 
 /** Scrollable region inside `DialogPanel`; keeps the footer pinned. */
-export function DialogBody({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
+export function DialogBody({
+  className,
+  ...props
+}: HTMLAttributes<HTMLDivElement>) {
   return (
     <div
       data-slot="body"
@@ -72,12 +321,15 @@ export function DialogBody({ className, ...props }: HTMLAttributes<HTMLDivElemen
   );
 }
 
-export function DialogHeader({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
+export function DialogHeader({
+  className,
+  ...props
+}: HTMLAttributes<HTMLDivElement>) {
   return (
     <div
       data-slot="header"
       className={cn(
-        "flex shrink-0 flex-col gap-1.5 border-b border-[var(--dialog-panel-border)] px-5 py-4",
+        "flex shrink-0 flex-col gap-1.5 border-b border-(--dialog-panel-border) px-5 py-4",
         className,
       )}
       {...props}
@@ -85,7 +337,10 @@ export function DialogHeader({ className, ...props }: HTMLAttributes<HTMLDivElem
   );
 }
 
-export function DialogFooter({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
+export function DialogFooter({
+  className,
+  ...props
+}: HTMLAttributes<HTMLDivElement>) {
   return (
     <div
       data-slot="footer"

package/src/dropdown-menu.tsx

@@ -16,13 +16,13 @@ export const DropdownMenuPortal = DropdownMenuPrimitive.Portal;
 export const DropdownMenuContent = forwardRef<
   ElementRef<typeof DropdownMenuPrimitive.Content>,
   ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Content>
->(({ className, sideOffset = 6, ...props }, ref) => (
+>(({ className, sideOffset = 8, ...props }, ref) => (
   <DropdownMenuPrimitive.Portal>
     <DropdownMenuPrimitive.Content
       ref={ref}
       sideOffset={sideOffset}
       className={cn(
-        "z-50 min-w-48 overflow-hidden rounded-lg border border-line bg-[var(--button-secondary-bg)] p-1 shadow-md",
+        "menu-surface btn-inner-border z-50 min-w-48 overflow-hidden rounded-lg border border-line bg-[var(--button-secondary-bg)] p-1",
         "data-[state=open]:animate-in data-[state=closed]:animate-out",
         "data-[state=open]:fade-in-0 data-[state=closed]:fade-out-0",
         "data-[state=open]:zoom-in-95 data-[state=closed]:zoom-out-95",
@@ -39,7 +39,9 @@ DropdownMenuContent.displayName = "DropdownMenuContent";
 
 export const DropdownMenuItem = forwardRef<
   ElementRef<typeof DropdownMenuPrimitive.Item>,
-  ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Item> & { inset?: boolean }
+  ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Item> & {
+    inset?: boolean;
+  }
 >(({ className, inset, ...props }, ref) => (
   <DropdownMenuPrimitive.Item
     ref={ref}

package/src/empty-state.tsx

@@ -1,6 +1,6 @@
 import type { ReactNode } from "react";
 
-import { cn } from "./utils";
+import { TableSurface } from "./table-surface";
 
 interface EmptyStateProps {
   icon?: ReactNode;
@@ -12,24 +12,21 @@ interface EmptyStateProps {
 
 export function EmptyState({ icon, title, description, action, className }: EmptyStateProps) {
   return (
-    <div
-      className={cn(
-        "flex flex-col items-center justify-center gap-4 rounded-card border border-line bg-surface px-6 py-16 text-center",
-        className,
-      )}
-    >
-      {icon ? (
-        <div className="flex size-11 items-center justify-center rounded-xl border border-line bg-elevated text-subtle [&_svg]:size-6">
-          {icon}
-        </div>
-      ) : null}
-      <div className="space-y-1">
-        <p className="text-sm font-medium text-fg">{title}</p>
-        {description ? (
-          <p className="mx-auto max-w-sm text-sm text-muted">{description}</p>
+    <TableSurface className={className}>
+      <div className="flex flex-col items-center justify-center gap-4 px-6 py-16 text-center">
+        {icon ? (
+          <div className="flex size-11 items-center justify-center rounded-xl border border-line bg-elevated text-subtle [&_svg]:size-6">
+            {icon}
+          </div>
         ) : null}
+        <div className="space-y-1">
+          <p className="text-sm font-medium text-fg">{title}</p>
+          {description ? (
+            <p className="mx-auto max-w-sm text-sm text-muted">{description}</p>
+          ) : null}
+        </div>
+        {action}
       </div>
-      {action}
-    </div>
+    </TableSurface>
   );
 }

package/src/label.tsx

@@ -10,7 +10,7 @@ export const Label = forwardRef<
   <LabelPrimitive.Root
     ref={ref}
     className={cn(
-      "text-sm font-medium text-fg leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70",
+      "mb-1 text-sm font-medium text-fg leading-none last:mb-0 peer-disabled:cursor-not-allowed peer-disabled:opacity-70",
       className,
     )}
     {...props}

package/src/radio-group.tsx

@@ -113,8 +113,8 @@ export function RadioCard({
       <span
         aria-hidden
         className={cn(
-          "mt-0.5 grid size-4.5 shrink-0 place-items-center rounded-full border-2 border-transparent bg-line-strong transition-colors",
-          "peer-checked:border-[5px] peer-checked:border-primary peer-checked:bg-primary-fg",
+          "mt-[5px] grid size-3.5 shrink-0 place-items-center rounded-full border-2 border-transparent bg-line-strong transition-colors",
+          "peer-checked:border-4 peer-checked:border-primary peer-checked:bg-primary-fg",
           "peer-focus-visible:ring-2 peer-focus-visible:ring-focus/40 peer-focus-visible:ring-offset-2 peer-focus-visible:ring-offset-canvas",
         )}
       />

package/src/select.tsx

@@ -1,6 +1,10 @@
 import * as SelectPrimitive from "@radix-ui/react-select";
 import { CaretDown, Check } from "@phosphor-icons/react";
-import { forwardRef, type ComponentPropsWithoutRef, type ElementRef } from "react";
+import {
+  forwardRef,
+  type ComponentPropsWithoutRef,
+  type ElementRef,
+} from "react";
 
 import { cn } from "./utils";
 
@@ -8,16 +12,27 @@ export const Select = SelectPrimitive.Root;
 export const SelectGroup = SelectPrimitive.Group;
 export const SelectValue = SelectPrimitive.Value;
 
+export interface SelectTriggerProps extends ComponentPropsWithoutRef<
+  typeof SelectPrimitive.Trigger
+> {
+  /** `field` fills a form; `inline` mimics the compact app dropdown. */
+  variant?: "field" | "inline";
+}
+
 export const SelectTrigger = forwardRef<
   ElementRef<typeof SelectPrimitive.Trigger>,
-  ComponentPropsWithoutRef<typeof SelectPrimitive.Trigger>
->(({ className, children, ...props }, ref) => (
+  SelectTriggerProps
+>(({ className, children, variant = "field", ...props }, ref) => (
   <SelectPrimitive.Trigger
     ref={ref}
     className={cn(
-      "flex h-9 w-full items-center justify-between gap-2 rounded-md border border-line bg-surface px-3 text-sm text-fg",
-      "focus:outline-none focus:border-primary focus:ring-2 focus:ring-focus/30 disabled:cursor-not-allowed disabled:opacity-50",
+      "flex items-center justify-between gap-2 text-sm text-fg",
+      "focus:outline-none disabled:cursor-not-allowed disabled:opacity-50",
       "[&>span]:truncate",
+      variant === "field" &&
+        "h-9 w-full rounded-md border border-line bg-surface px-3 focus:border-primary focus:ring-2 focus:ring-focus/30",
+      variant === "inline" &&
+        "btn-fill btn-inner-border btn-interactive h-8 w-auto rounded-(--control-radius) border-0 bg-(--button-secondary-bg) px-(--control-pad-x-sm) font-medium text-fg hover:bg-(--button-surface-hover) active:bg-(--button-surface-active) focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-line-strong",
       className,
     )}
     {...props}
@@ -33,27 +48,35 @@ SelectTrigger.displayName = "SelectTrigger";
 export const SelectContent = forwardRef<
   ElementRef<typeof SelectPrimitive.Content>,
   ComponentPropsWithoutRef<typeof SelectPrimitive.Content>
->(({ className, children, position = "popper", ...props }, ref) => (
-  <SelectPrimitive.Portal>
-    <SelectPrimitive.Content
-      ref={ref}
-      position={position}
-      className={cn(
-        "z-50 min-w-[8rem] overflow-hidden rounded-lg border border-line bg-surface p-1 shadow-md",
-        "data-[state=open]:animate-in data-[state=closed]:animate-out",
-        "data-[state=open]:fade-in-0 data-[state=closed]:fade-out-0",
-        "data-[state=open]:zoom-in-95 data-[state=closed]:zoom-out-95",
-        "data-[side=bottom]:slide-in-from-top-2 data-[side=top]:slide-in-from-bottom-2",
-        "data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2",
-        "duration-150 ease-out",
-        className,
-      )}
-      {...props}
-    >
-      <SelectPrimitive.Viewport className="p-0">{children}</SelectPrimitive.Viewport>
-    </SelectPrimitive.Content>
-  </SelectPrimitive.Portal>
-));
+>(
+  (
+    { className, children, position = "popper", sideOffset = 8, ...props },
+    ref,
+  ) => (
+    <SelectPrimitive.Portal>
+      <SelectPrimitive.Content
+        ref={ref}
+        position={position}
+        sideOffset={sideOffset}
+        className={cn(
+          "menu-surface btn-inner-border z-50 min-w-48 overflow-hidden rounded-lg border border-line bg-(--button-secondary-bg) p-1",
+          "data-[state=open]:animate-in data-[state=closed]:animate-out",
+          "data-[state=open]:fade-in-0 data-[state=closed]:fade-out-0",
+          "data-[state=open]:zoom-in-95 data-[state=closed]:zoom-out-95",
+          "data-[side=bottom]:slide-in-from-top-2 data-[side=top]:slide-in-from-bottom-2",
+          "data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2",
+          "duration-150 ease-out",
+          className,
+        )}
+        {...props}
+      >
+        <SelectPrimitive.Viewport className="p-0">
+          {children}
+        </SelectPrimitive.Viewport>
+      </SelectPrimitive.Content>
+    </SelectPrimitive.Portal>
+  ),
+);
 SelectContent.displayName = "SelectContent";
 
 export const SelectItem = forwardRef<
@@ -63,7 +86,7 @@ export const SelectItem = forwardRef<
   <SelectPrimitive.Item
     ref={ref}
     className={cn(
-      "relative flex cursor-default select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-sm text-fg outline-none focus:bg-elevated data-[disabled]:pointer-events-none data-[disabled]:opacity-50",
+      "relative flex cursor-default select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-sm text-fg outline-none focus:bg-(--menu-highlight) data-disabled:pointer-events-none data-disabled:opacity-50",
       className,
     )}
     {...props}

package/src/table-surface.tsx

@@ -16,6 +16,10 @@ export interface TableSurfaceAction {
 }
 
 interface TableSurfaceProps {
+  /** Title above the header row. */
+  title?: ReactNode;
+  /** Supporting text under the title. */
+  description?: ReactNode;
   /** Header row content (a single row of column cells). */
   header?: ReactNode;
   /** Panel content: the body table, or an empty / loading / error state. */
@@ -65,6 +69,8 @@ function isActionConfig(
  * `tone` plus `headerClassName` / `panelClassName`.
  */
 export function TableSurface({
+  title,
+  description,
   header,
   children,
   action,
@@ -74,6 +80,7 @@ export function TableSurface({
   panelClassName,
   minHeight,
 }: TableSurfaceProps) {
+  const hasTitle = Boolean(title || description);
   const actionNode = isActionConfig(action) ? (
     <Button
       variant={action.variant ?? "primary"}
@@ -99,9 +106,24 @@ export function TableSurface({
   return (
     <TableContainer className={cn("relative", SHELL_TONE[tone], className)}>
       <div className="overflow-x-auto">
-        {header ? (
+        {header || hasTitle ? (
           // Header rows must not inherit the body row hover surface.
           <div className={cn("[--table-row-hover:transparent]", 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>
+            ) : null}
             {header}
           </div>
         ) : null}