@elabs-ai/components-ui 4.0.0

package/src/components/dialog/dialog.test.tsx

@@ -0,0 +1,285 @@
+import { describe, it, expect } from "vitest";
+import { render, screen, waitFor } from "@testing-library/react";
+import {
+  Dialog,
+  DialogBody,
+  DialogContent,
+  DialogSection,
+  DialogTitle,
+  DialogDescription,
+} from "./dialog";
+import { Label } from "../label";
+
+function Wrapper({ size }: { size?: "sm" | "lg" | "xl" | "full" }) {
+  return (
+    <Dialog open>
+      <DialogContent size={size}>
+        <DialogTitle>Test dialog</DialogTitle>
+        <DialogDescription>Test description</DialogDescription>
+        Content
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+describe("DialogContent size variants", () => {
+  it("default (no size prop) renders max-w-lg — regression lock", () => {
+    render(<Wrapper />);
+    const content = screen.getByRole("dialog");
+    expect(content.className).toContain("max-w-lg");
+  });
+
+  it("size='lg' renders max-w-lg", () => {
+    render(<Wrapper size="lg" />);
+    const content = screen.getByRole("dialog");
+    expect(content.className).toContain("max-w-lg");
+  });
+
+  it("size='sm' renders max-w-sm", () => {
+    render(<Wrapper size="sm" />);
+    const content = screen.getByRole("dialog");
+    expect(content.className).toContain("max-w-sm");
+  });
+
+  it("size='xl' renders max-w-3xl", () => {
+    render(<Wrapper size="xl" />);
+    const content = screen.getByRole("dialog");
+    expect(content.className).toContain("max-w-3xl");
+  });
+
+  it("size='full' renders max-w-[95vw] and h-[90vh]", () => {
+    render(<Wrapper size="full" />);
+    const content = screen.getByRole("dialog");
+    expect(content.className).toContain("max-w-[95vw]");
+    expect(content.className).toContain("h-[90vh]");
+  });
+});
+
+describe("DialogContent grid overflow guard (regression)", () => {
+  // The grid that lays out DialogContent's children must use a
+  // `minmax(0,1fr)` column, not the implicit `auto` column. Without the floor,
+  // a grid item's default `min-width:auto` lets a `truncate`/`nowrap` child or a
+  // long unbreakable token set the column's min-content size and push the dialog
+  // past its `max-w-*`. jsdom can't measure layout, so this locks the class that
+  // prevents it; the visual proof is the `OverflowGuard` Storybook story.
+  it("renders a minmax(0,1fr) grid column so truncate children can shrink", () => {
+    render(<Wrapper />);
+    const content = screen.getByRole("dialog");
+    expect(content.className).toContain("grid-cols-[minmax(0,1fr)]");
+    expect(content.className).toContain("grid");
+  });
+
+  it("keeps the minmax column on every size variant", () => {
+    for (const size of ["sm", "lg", "xl", "full"] as const) {
+      const { unmount } = render(<Wrapper size={size} />);
+      expect(screen.getByRole("dialog").className).toContain("grid-cols-[minmax(0,1fr)]");
+      unmount();
+    }
+  });
+});
+
+describe("DialogContent height/scroll regime (#341)", () => {
+  // jsdom does NO layout, so these are CLASS assertions and nothing more — they
+  // lock the contract that produces the behaviour. The behaviour itself (header
+  // and footer fixed, body scrolling, at a short viewport) is proven in the
+  // `WideWithSections` / `ShortViewport` stories, which run in a real browser.
+  it("caps at the viewport and scrolls itself when no DialogBody is present", () => {
+    render(<Wrapper />);
+    const content = screen.getByRole("dialog");
+    expect(content.className).toContain("max-h-[calc(100dvh-2rem)]");
+    expect(content.className).toContain("overflow-y-auto");
+  });
+
+  it("hands scroll to the body via a has-[] variant (inert without one)", () => {
+    render(<Wrapper />);
+    const content = screen.getByRole("dialog");
+    expect(content.className).toContain("has-[[data-slot=dialog-body]]:overflow-hidden");
+    expect(content.className).toContain(
+      "has-[[data-slot=dialog-body]]:grid-rows-[auto_minmax(0,1fr)_auto]",
+    );
+  });
+
+  it("size='full' keeps its own overflow/height after the merge", () => {
+    render(<Wrapper size="full" />);
+    const content = screen.getByRole("dialog");
+    // tailwind-merge resolves the base `overflow-y-auto` away in favour of the
+    // later variant utility, so `full` still lets its body own the scroll.
+    expect(content.className).toContain("overflow-hidden");
+    expect(content.className).not.toContain("overflow-y-auto");
+    expect(content.className).toContain("max-h-[90vh]");
+    expect(content.className).not.toContain("max-h-[calc(100dvh-2rem)]");
+  });
+});
+
+describe("DialogBody", () => {
+  it("declares the dialog-body slot and owns the scroll", () => {
+    render(
+      <Dialog open>
+        <DialogContent>
+          <DialogTitle>Test dialog</DialogTitle>
+          <DialogDescription>Test description</DialogDescription>
+          <DialogBody>Body</DialogBody>
+        </DialogContent>
+      </Dialog>,
+    );
+    const body = screen.getByText("Body");
+    expect(body.getAttribute("data-slot")).toBe("dialog-body");
+    expect(body.className).toContain("overflow-y-auto");
+    expect(body.className).toContain("min-h-0");
+    // Scroll must not chain to the page behind the overlay.
+    expect(body.className).toContain("overscroll-contain");
+    // Focus-ring gutter (#425): `p-1`/`-m-1`/`scroll-p-1` reserve 4px of
+    // scrollport padding so an outward `box-shadow` ring on a flush child is
+    // not clipped, then pull the border box back so body content stays flush
+    // with the header/footer. jsdom performs no layout and no paint, so this
+    // can only assert the classes are DECLARED — it can never observe a
+    // `box-shadow` actually being clipped (or not). Its job is to stop a
+    // future "tidy the class string" edit from silently deleting the trio;
+    // the real geometric proof is the `FocusRingClearance` story, run in a
+    // real browser via `@storybook/addon-vitest`.
+    expect(body.className).toContain("p-1");
+    expect(body.className).toContain("-m-1");
+    expect(body.className).toContain("scroll-p-1");
+  });
+
+  it("is keyboard-operable by default and lets a caller opt out", () => {
+    const { rerender } = render(
+      <Dialog open>
+        <DialogContent>
+          <DialogTitle>Test dialog</DialogTitle>
+          <DialogDescription>Test description</DialogDescription>
+          <DialogBody>Body</DialogBody>
+        </DialogContent>
+      </Dialog>,
+    );
+    expect(screen.getByText("Body")).toHaveAttribute("tabindex", "0");
+
+    rerender(
+      <Dialog open>
+        <DialogContent>
+          <DialogTitle>Test dialog</DialogTitle>
+          <DialogDescription>Test description</DialogDescription>
+          <DialogBody tabIndex={-1}>Body</DialogBody>
+        </DialogContent>
+      </Dialog>,
+    );
+    expect(screen.getByText("Body")).toHaveAttribute("tabindex", "-1");
+  });
+});
+
+describe("DialogBody opening focus", () => {
+  function Wrapped({ withBody }: { withBody: boolean }) {
+    const fields = (
+      <>
+        <label htmlFor="first">First</label>
+        <input id="first" />
+      </>
+    );
+    return (
+      <Dialog open>
+        <DialogContent>
+          <DialogTitle>Test dialog</DialogTitle>
+          <DialogDescription>Test description</DialogDescription>
+          {withBody ? <DialogBody>{fields}</DialogBody> : fields}
+        </DialogContent>
+      </Dialog>
+    );
+  }
+
+  // The body takes a tab stop so it can be scrolled from the keyboard; it must
+  // NOT therefore become the dialog's opening focus target — that would ring the
+  // whole scroll region on open and skip the first field.
+  it("skips the scroll wrapper and opens on the first real control", async () => {
+    render(<Wrapped withBody />);
+    const input = screen.getByLabelText("First");
+    await waitFor(() => expect(document.activeElement).toBe(input));
+    expect(document.activeElement).not.toBe(screen.getByText("First").closest("div"));
+  });
+
+  it("leaves a body-less dialog's focus behaviour untouched", async () => {
+    render(<Wrapped withBody={false} />);
+    await waitFor(() => expect(document.activeElement).toBe(screen.getByLabelText("First")));
+  });
+
+  // A body with nothing focusable in it must fall back to Radix, which focuses
+  // the body — the right target for a text-only scroll region. Reaching past it
+  // to the footer would open the dialog with the keyboard on the PRIMARY action.
+  it("leaves a control-less body to Radix, which focuses the scroll region", async () => {
+    render(
+      <Dialog open>
+        <DialogContent>
+          <DialogTitle>Test dialog</DialogTitle>
+          <DialogDescription>Test description</DialogDescription>
+          <DialogBody>Nothing focusable in here.</DialogBody>
+          <button type="button">Save</button>
+        </DialogContent>
+      </Dialog>,
+    );
+    const body = screen.getByText("Nothing focusable in here.");
+    await waitFor(() => expect(document.activeElement).toBe(body));
+    expect(document.activeElement).not.toBe(screen.getByRole("button", { name: "Save" }));
+  });
+
+  // A candidate that matches the selector but cannot take focus (a `hidden` file
+  // input is the everyday case) must not consume the redirect: preventing
+  // Radix's default for it strands focus on the TRIGGER, outside the modal.
+  // NOT assertable here — jsdom does no layout and happily focuses a `hidden`
+  // input — so the lock is the `HiddenFirstControl` story, which runs in a real
+  // browser under `test-storybook`.
+});
+
+describe("DialogSection", () => {
+  function SectionWrapper() {
+    return (
+      <Dialog open>
+        <DialogContent>
+          <DialogTitle>Test dialog</DialogTitle>
+          <DialogDescription>Test description</DialogDescription>
+          <DialogSection title="Retention" description="How long runs are kept.">
+            <Label htmlFor="days">Days to keep</Label>
+          </DialogSection>
+        </DialogContent>
+      </Dialog>
+    );
+  }
+
+  it("renders a real heading one level below DialogTitle", () => {
+    render(<SectionWrapper />);
+    const heading = screen.getByRole("heading", { name: "Retention" });
+    expect(heading.tagName).toBe("H3");
+    expect(heading.getAttribute("data-slot")).toBe("dialog-section-title");
+  });
+
+  it("renders the section title one type ROLE above a field label", () => {
+    render(<SectionWrapper />);
+    const heading = screen.getByRole("heading", { name: "Retention" });
+    const label = screen.getByText("Days to keep");
+    // The rungs must differ: section = `subtitle` (1rem), label = body (0.875rem).
+    // jsdom applies no stylesheet, so this asserts the ROLE; the rendered pixel
+    // sizes are compared with getComputedStyle in the `WideWithSections` story.
+    expect(heading.className).toContain("text-subtitle");
+    expect(label.className).not.toContain("text-subtitle");
+  });
+
+  it("accepts a deeper level and slots its description and actions", () => {
+    render(
+      <Dialog open>
+        <DialogContent>
+          <DialogTitle>Test dialog</DialogTitle>
+          <DialogDescription>Test description</DialogDescription>
+          <DialogSection
+            level={4}
+            title="Retention"
+            description="How long runs are kept."
+            actions={<button type="button">Reset</button>}
+          />
+        </DialogContent>
+      </Dialog>,
+    );
+    expect(screen.getByRole("heading", { name: "Retention" }).tagName).toBe("H4");
+    expect(screen.getByText("How long runs are kept.").getAttribute("data-slot")).toBe(
+      "dialog-section-description",
+    );
+    expect(screen.getByRole("button", { name: "Reset" })).toBeInTheDocument();
+  });
+});

package/src/components/dialog/dialog.tsx

@@ -0,0 +1,340 @@
+import {
+  forwardRef,
+  useCallback,
+  useRef,
+  type ComponentPropsWithoutRef,
+  type ElementRef,
+  type HTMLAttributes,
+  type MutableRefObject,
+  type ReactNode,
+} from "react";
+import * as DialogPrimitive from "@radix-ui/react-dialog";
+import { cva, type VariantProps } from "class-variance-authority";
+import { cn } from "../../lib/cn";
+import { Heading, Text } from "../typography";
+
+/**
+ * The first keyboard-reachable control inside a dialog, EXCLUDING the
+ * `DialogBody` wrapper itself. Deliberately a pragmatic selector rather than a
+ * full tabbability implementation — Radix owns focus trapping; this only
+ * reorders the opening target (see `DialogContent`'s `onOpenAutoFocus`).
+ */
+const TABBABLE = [
+  "a[href]",
+  "button:not([disabled])",
+  "input:not([disabled])",
+  "select:not([disabled])",
+  "textarea:not([disabled])",
+  '[tabindex]:not([tabindex="-1"]):not([data-slot="dialog-body"])',
+].join(",");
+
+export const dialogContentVariants = cva(
+  // `grid-cols-[minmax(0,1fr)]` (NOT the implicit `auto` column): grid items
+  // default to `min-width:auto`, so a `nowrap`/`truncate` child or a long
+  // unbreakable token (a file path, a URL) sets the column's min-content size and
+  // pushes the dialog past its `max-w-*`. A `minmax(0,1fr)` column floors that at
+  // 0, so inner `truncate`/`w-full` shrink instead of overflowing (#regression).
+  //
+  // Height/scroll (#341). Two mutually-exclusive regimes, picked by ANATOMY —
+  // never by a `scroll` prop (`.claude/rules/component-api.md`: `cva` is for
+  // visual axes, behaviour is composition):
+  //   1. NO `DialogBody` — the content box itself caps at the viewport
+  //      (`max-h-…` + `overflow-y-auto`) and scrolls as one column. Before this,
+  //      a taller-than-viewport dialog overflowed past BOTH viewport edges and
+  //      its top was unreachable (the `-translate-y-1/2` centring).
+  //   2. WITH a `DialogBody` — the `has-[…]` pair turns the content box into a
+  //      3-row grid (`auto | minmax(0,1fr) | auto`) and stops it scrolling, so a
+  //      fixed header and footer sandwich a body that owns the scroll. The pair
+  //      is INERT for every dialog that has no `DialogBody`.
+  // `size="full"`'s own `h-/max-h-/overflow-hidden` still wins — cva emits the
+  // base first, so tailwind-merge resolves the later variant utilities over it.
+  "fixed left-1/2 top-1/2 z-50 grid grid-cols-[minmax(0,1fr)] w-full -translate-x-1/2 -translate-y-1/2 gap-4 max-h-[calc(100dvh-2rem)] overflow-y-auto overscroll-contain has-[[data-slot=dialog-body]]:overflow-hidden has-[[data-slot=dialog-body]]:grid-rows-[auto_minmax(0,1fr)_auto] rounded-xl bg-card p-6 text-card-foreground shadow-ring-lg data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95",
+  {
+    variants: {
+      size: {
+        sm: "max-w-sm",
+        lg: "max-w-lg",
+        xl: "max-w-3xl",
+        full: "max-w-[95vw] h-[90vh] max-h-[90vh] overflow-hidden",
+      },
+    },
+    defaultVariants: { size: "lg" },
+  },
+);
+
+export const Dialog = DialogPrimitive.Root;
+export const DialogTrigger = DialogPrimitive.Trigger;
+export const DialogPortal = DialogPrimitive.Portal;
+export const DialogClose = DialogPrimitive.Close;
+
+export const DialogOverlay = forwardRef<
+  ElementRef<typeof DialogPrimitive.Overlay>,
+  ComponentPropsWithoutRef<typeof DialogPrimitive.Overlay>
+>(function DialogOverlay({ className, ...props }, ref) {
+  return (
+    <DialogPrimitive.Overlay
+      ref={ref}
+      data-slot="dialog-overlay"
+      className={cn(
+        "fixed inset-0 z-50 bg-foreground/50 backdrop-blur-sm",
+        "data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
+        className,
+      )}
+      {...props}
+    />
+  );
+});
+
+export const DialogContent = forwardRef<
+  ElementRef<typeof DialogPrimitive.Content>,
+  ComponentPropsWithoutRef<typeof DialogPrimitive.Content> &
+    VariantProps<typeof dialogContentVariants>
+>(function DialogContent({ className, children, size, onOpenAutoFocus, ...props }, ref) {
+  const contentRef = useRef<HTMLDivElement | null>(null);
+  const setRefs = useCallback(
+    (node: HTMLDivElement | null) => {
+      contentRef.current = node;
+      if (typeof ref === "function") ref(node);
+      else if (ref) (ref as MutableRefObject<HTMLDivElement | null>).current = node;
+    },
+    [ref],
+  );
+
+  /**
+   * A `DialogBody` carries `tabIndex={0}` so a keyboard user can scroll it — but
+   * being the first tab stop would also make the scroll WRAPPER the dialog's
+   * opening focus target, which paints a focus ring around the whole body on
+   * open and skips the first field. Skip past it to the first real control
+   * INSIDE the body. Inert for dialogs with no `DialogBody`, so nothing that
+   * shipped before changes.
+   *
+   * Two things this deliberately does NOT do, both because getting them wrong
+   * strands the keyboard:
+   *   * It only prevents Radix's default once a candidate has *actually taken*
+   *     focus. A selector match is not proof of focusability — a `display:none`
+   *     candidate (the ubiquitous `<input type="file" hidden>`) swallows
+   *     `.focus()`, so preventing the default for it would leave focus on the
+   *     TRIGGER, outside the modal.
+   *   * It gives up when the body holds no focusable control at all. Radix's own
+   *     fallback then focuses the body — which is the right target for a
+   *     text-only scroll region, and better than reaching past it to the
+   *     footer's primary action.
+   */
+  const handleOpenAutoFocus = useCallback(
+    (event: Event) => {
+      onOpenAutoFocus?.(event);
+      if (event.defaultPrevented) return;
+      const body = contentRef.current?.querySelector<HTMLElement>('[data-slot="dialog-body"]');
+      if (!body) return;
+      for (const candidate of body.querySelectorAll<HTMLElement>(TABBABLE)) {
+        candidate.focus({ preventScroll: true });
+        if (candidate.ownerDocument.activeElement !== candidate) continue;
+        event.preventDefault();
+        return;
+      }
+    },
+    [onOpenAutoFocus],
+  );
+
+  return (
+    <DialogPortal>
+      <DialogOverlay />
+      <DialogPrimitive.Content
+        ref={setRefs}
+        data-slot="dialog-content"
+        className={cn(dialogContentVariants({ size }), className)}
+        onOpenAutoFocus={handleOpenAutoFocus}
+        {...props}
+      >
+        {children}
+        <DialogPrimitive.Close
+          data-slot="dialog-close"
+          className="absolute end-4 top-4 rounded-md p-1 text-muted-foreground opacity-70 transition-opacity hover:opacity-100 focus:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+          aria-label="Close"
+        >
+          <svg
+            width="16"
+            height="16"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            aria-hidden="true"
+          >
+            <path d="M18 6 6 18M6 6l12 12" />
+          </svg>
+        </DialogPrimitive.Close>
+      </DialogPrimitive.Content>
+    </DialogPortal>
+  );
+});
+
+export function DialogHeader({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      data-slot="dialog-header"
+      className={cn("flex flex-col gap-1.5 text-start", className)}
+      {...props}
+    />
+  );
+}
+
+export function DialogFooter({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      data-slot="dialog-footer"
+      className={cn("flex flex-col-reverse gap-2 sm:flex-row sm:justify-end", className)}
+      {...props}
+    />
+  );
+}
+
+export const DialogTitle = forwardRef<
+  ElementRef<typeof DialogPrimitive.Title>,
+  ComponentPropsWithoutRef<typeof DialogPrimitive.Title>
+>(function DialogTitle({ className, ...props }, ref) {
+  return (
+    <DialogPrimitive.Title
+      ref={ref}
+      data-slot="dialog-title"
+      className={cn("text-title leading-none", className)}
+      {...props}
+    />
+  );
+});
+
+export const DialogDescription = forwardRef<
+  ElementRef<typeof DialogPrimitive.Description>,
+  ComponentPropsWithoutRef<typeof DialogPrimitive.Description>
+>(function DialogDescription({ className, ...props }, ref) {
+  return (
+    <DialogPrimitive.Description
+      ref={ref}
+      data-slot="dialog-description"
+      className={cn("text-sm text-muted-foreground", className)}
+      {...props}
+    />
+  );
+});
+
+export type DialogBodyProps = HTMLAttributes<HTMLDivElement>;
+
+/**
+ * The dialog's scroll owner (#341).
+ *
+ * Placing a `DialogBody` between `DialogHeader` and `DialogFooter` switches
+ * `DialogContent` into its fixed-header/footer regime (see
+ * `dialogContentVariants`): the header and footer stay put and ONLY this region
+ * scrolls, so the primary action never scrolls out of view. Without it a dialog
+ * behaves exactly as before — the anatomy is the switch, there is no `scroll`
+ * prop.
+ *
+ * `overscroll-contain` stops the scroll chaining to the page underneath
+ * (`.claude/rules/interaction-guidelines.md`, Touch & overscroll).
+ *
+ * **The `p-1`/`-m-1`/`scroll-p-1` trio reserves a focus-ring gutter (#425).**
+ * Per CSS Overflow 3, authoring only `overflow-y-auto` still makes this a
+ * two-axis scroll container (the `visible` axis computes to `auto` too), and a
+ * scroll container clips at its **padding box**. With no padding of its own,
+ * that padding box IS the content box, so a full-width child's border box
+ * lands exactly on the clip edge — leaving 0px for a focus ring, which is
+ * `box-shadow` (ink overflow: never part of the scrollable region, so it is
+ * simply cut, not merely scrolled out of reach). `p-1` moves the scrollport
+ * 4px outward on every side — enough for the library's widest outward paint
+ * (`ring-2 ring-offset-2` = 4px) — and `-m-1` pulls the border box back by the
+ * same amount so body content stays flush with `DialogHeader`/`DialogFooter`
+ * instead of indenting 4px against them. `scroll-p-1` keeps a keyboard-driven
+ * scroll-into-view (Tab landing on a control currently outside the scrollport)
+ * from placing that control flush against the scrollport edge again.
+ *
+ * Two consumer-facing consequences: a larger `className` padding (e.g. `p-6`)
+ * still wins through `tailwind-merge`, with the border box remaining 4px
+ * outward; but **`className="p-0"` re-opens the bug** — the merge kills `p-1`
+ * while `-m-1` survives — so a consumer who genuinely wants no gutter must
+ * clear both sides with `className="m-0 p-0"`.
+ *
+ * Known, accepted residual: at `data-density="compact"`, `--spacing` is
+ * `0.222rem` (`density.css:97`), so `p-1` is 3.55px against a 4px ring — a
+ * 0.45px shortfall on the outermost edge of a 2px stroke. Do not "fix" this
+ * with a fixed-px override; that would break the density dial's contract.
+ */
+export const DialogBody = forwardRef<HTMLDivElement, DialogBodyProps>(function DialogBody(
+  { className, tabIndex, ...props },
+  ref,
+) {
+  return (
+    <div
+      ref={ref}
+      data-slot="dialog-body"
+      // A scroll container must be keyboard-operable (WCAG 2.1.1; axe's
+      // `scrollable-region-focusable`). A body holding only text has no focusable
+      // child to scroll from, so the region itself takes the tab stop. Pass
+      // `tabIndex={-1}` to opt out when the body always contains its own
+      // focusable content.
+      tabIndex={tabIndex ?? 0}
+      className={cn(
+        "-m-1 min-h-0 overflow-y-auto overscroll-contain p-1 scroll-p-1 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+        className,
+      )}
+      {...props}
+    />
+  );
+});
+
+export interface DialogSectionProps extends Omit<HTMLAttributes<HTMLElement>, "title"> {
+  /** The section heading. States what the group of fields is for. */
+  title: ReactNode;
+  /** One line of supporting context under the heading. */
+  description?: ReactNode;
+  /**
+   * Semantic heading level. `DialogTitle` renders an `<h2>`, so a section is an
+   * `<h3>` by default and an `<h4>` when nested a rung deeper.
+   */
+  level?: 3 | 4;
+  /** Section-scoped actions, aligned to the inline end of the heading row. */
+  actions?: ReactNode;
+}
+
+/**
+ * A real section heading inside a dialog (#341).
+ *
+ * The recurring downstream defect was section labels rendering at the same size
+ * as the field labels beneath them, which flattens a long form into one
+ * undifferentiated list. The rungs are distinct BY TOKEN, not by eye:
+ * `DialogTitle` `text-title` (1.25rem) > `DialogSection` `text-subtitle` (1rem) >
+ * `Label` `text-body` (0.875rem).
+ *
+ * Deliberately NOT `SectionHeader` (`../section-header`): that is the page-level
+ * `<h2>` row with an eyebrow, one rung too loud and one level too high inside a
+ * dialog whose title already owns the `<h2>`.
+ */
+export const DialogSection = forwardRef<HTMLElement, DialogSectionProps>(function DialogSection(
+  { className, title, description, level = 3, actions, children, ...props },
+  ref,
+) {
+  return (
+    <section
+      ref={ref}
+      data-slot="dialog-section"
+      className={cn("flex flex-col gap-3", className)}
+      {...props}
+    >
+      <div className="flex items-start justify-between gap-3">
+        <div className="flex min-w-0 flex-col gap-1">
+          <Heading level={level} size="subtitle" data-slot="dialog-section-title">
+            {title}
+          </Heading>
+          {description ? (
+            <Text variant="caption" tone="muted" data-slot="dialog-section-description">
+              {description}
+            </Text>
+          ) : null}
+        </div>
+        {actions ? <div className="shrink-0">{actions}</div> : null}
+      </div>
+      {children}
+    </section>
+  );
+});

package/src/components/dialog/index.ts

@@ -0,0 +1,18 @@
+export {
+  dialogContentVariants,
+  Dialog,
+  DialogTrigger,
+  DialogPortal,
+  DialogClose,
+  DialogOverlay,
+  DialogContent,
+  DialogHeader,
+  DialogFooter,
+  DialogTitle,
+  DialogDescription,
+  DialogBody,
+  DialogSection,
+} from "./dialog";
+export type { DialogBodyProps, DialogSectionProps } from "./dialog";
+export { useDialogDismissGuard } from "./use-dialog-dismiss-guard";
+export type { UseDialogDismissGuardOptions, DialogDismissGuard } from "./use-dialog-dismiss-guard";