@botiverse/raft-ui 0.96.1 → 0.97.0

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+## [0.97.0](https://github.com/botiverse/raft-design/compare/v0.96.1...v0.97.0) (2026-11-13)
+
+### Added
+
+- **A check for native scrollers written in CSS files, which the lint rule can't see** ([Use raft-ui › CSS files](https://raft-design.botiverse.build/about/use-raft-ui/#css-files)). `node node_modules/@botiverse/raft-ui/checks/native-scroll-css.mjs [<dir, file or glob>...] [--json]` reads `.css` files (every one under the current directory by default, without `node_modules`, `dist`, `build` and dot folders) and reports each declaration of `overflow`, `overflow-x`, `overflow-y`, `overflow-inline` or `overflow-block` whose value has `auto`, `scroll` or `overlay` in it (`hidden auto`, `auto !important` and `var(--x, auto)` too), in minified CSS and inside `@media`, `@layer`, `@supports` and nested rules, and each native-scrolling class in an `@apply` (`overflow-y-auto`, `md:overflow-auto`, `overflow-[auto]`, `[overflow:overlay]`). Each report is `file:line:column  selector { declaration }`, followed by one message that says what to write instead and ends with the address of ScrollArea's page as Markdown. It exits 1 when it reports anything, 0 when it reports nothing and 2 for a path that doesn't exist or can't be read, a glob that matches no file, or an unknown option. A comment allows one declaration: above a line that holds several, only the first. A plain Node script with no dependencies, shipped in a new `checks` folder of the package.
+  - Why: `raft-ui/prefer-scroll-area` reads JS and TSX only, so a scroller made in a stylesheet (a diagram's `<pre>`, a standalone page's own `styles.css`) passed the lint and kept the platform's scrollbar.
+  - Affects: nothing until an app runs it. Chain it into the app's lint script, such as `"lint": "oxlint && node node_modules/@botiverse/raft-ui/checks/native-scroll-css.mjs src"`, then make the element each reported rule styles a `ScrollArea` (`useScrollAreaContainer` and `ScrollAreaGutters` for an element another component renders) and remove the declaration, or, for an allowed native case, put `/* raft-ui: native-scroll <reason> */` on a line of its own right above the declaration, or after it at the end of its line. A comment without a reason doesn't count. It doesn't read Sass or Less, a `<style>` block in HTML or CSS in a JS string.
+  - Docs: https://raft-design.botiverse.build/about/use-raft-ui/#css-files
+- **`TableScroll`, the area a wide table scrolls sideways in** ([Table › Wide tables](https://raft-design.botiverse.build/components/table/#wide-tables)). A part of Table: a horizontal ScrollArea around a `Table` or a plain `<table>`, with `data-slot="table-scroll"`. It takes ScrollArea's props but `orientation`, and has no frame or size of its own.
+  - Why: the only such part was Markdown's `MarkdownTableScroll`, so everywhere else a table wider than its column got a hand-written `overflow-x-auto` wrapper and the platform's scrollbar, or widened the page.
+  - Affects: nothing that exists. `MarkdownTableScroll` is now a `TableScroll` under its own slot name and renders the same DOM and classes as before. Give the `Table` a least width (`min-w-*`): without one its columns are first squeezed to their headers' width, long cells wrapping at any character, and it scrolls only once the headers don't fit. The area scrolls sideways only, so a vertical wheel over the table still scrolls the page, and it is a tab stop while the table is wider than it. `raft-ui/prefer-scroll-area` names `TableScroll` in its message for an element that scrolls sideways.
+  - Docs: https://raft-design.botiverse.build/components/table/#wide-tables
+- **`textareaScrollAreaVariants`, Textarea's look for a `ScrollAreaTextarea`** ([Textarea › A field that scrolls](https://raft-design.botiverse.build/components/textarea/#a-field-that-scrolls)), from `@botiverse/raft-ui/wip`. `wrapper()` goes to `wrapperClassName` (the border, radius, background, least height, and the focus ring, invalid and disabled looks read from the textarea inside) and `textarea()` to `className` (the type and padding).
+  - Why: `Textarea` stays a native `<textarea>`, which shows the platform's scrollbar when it scrolls, and nothing said what to use for a field that is meant to scroll. `ScrollAreaTextarea` draws raft-ui's scrollbar but has no look, so each form re-derived the field's classes for its frame.
+  - Affects: nothing that exists: `Textarea` renders the same classes as before. A field whose height is capped or whose `rows` are fixed, with text long enough to scroll, can move to `ScrollAreaTextarea` with these classes and keeps the box of a `Textarea`. Put the cap on the frame (`wrapper({ className: "max-h-40" })`), and set `aria-invalid` beside `data-invalid` yourself.
+  - Docs: https://raft-design.botiverse.build/components/textarea/#a-field-that-scrolls
+- **`DialogBody` can scroll in a ScrollArea, with raft-ui's scrollbar in place of the platform's** ([Dialog › Scrolling in a ScrollArea](https://raft-design.botiverse.build/components/dialog/#scrolling-in-a-scrollarea)). `<DialogBody unstable_scrollArea>` renders a frame (`data-slot="dialog-body-frame"`) around the body and binds the body as a ScrollArea with absolute gutters. The body keeps `data-slot="dialog-body"`, `className`, `ref`, the native props and its children, so a layout written on it (`className="grid gap-4"`) is unchanged; `wrapperClassName` is the frame's class, for the classes that size the body in the dialog (`max-h-*`, `h-*`, `flex-*`). The body is a Tab stop only while it overflows and holds nothing that takes focus (a `tabIndex` of your own wins), so a form gains no stop and a long text that is only read can be scrolled with the keyboard, and a scroll stops at its end with the bounce kept (`overscroll="contain"`). It works the same in `DialogSheetContent` below 768px. A `bar` body ignores the prop.
+  - Why: `DialogBody` was one of the few regions that still scrolled natively, because callers lay the body out themselves and ScrollArea's sticky gutters would take the grid's first cell. On Windows, and on a Mac set to always show scrollbars, a long dialog drew the platform's scrollbar, which takes room from the form when it appears. Absolute gutters put nothing inside the body, at the price of one element around it.
+  - Affects: nothing unless the prop is passed: without it `DialogBody` renders the same element and classes as before. It becomes the default in the next minor release, and the prop can be deleted then. With it, the frame, not the body, is the child of `DialogContent` (or of a `<form className="contents">` in it): a selector such as `[data-slot=dialog-content] > [data-slot=dialog-body]` no longer matches, a sizing class on the body moves to `wrapperClassName`, and a `p-0` in `className` also removes the top inset of a body with no header above it. The frame is a stacking context of its own, so a popup portaled into the body is drawn under the dialog's head; leave popups where raft-ui portals them. `DrawerBody` is unchanged.
+  - Docs: https://raft-design.botiverse.build/components/dialog/#scrolling-in-a-scrollarea
+
 ## [0.96.1](https://github.com/botiverse/raft-design/compare/v0.96.0...v0.96.1) (2026-11-13)
 
 ### Fixed

package/checks/native-scroll-css.mjs

@@ -0,0 +1,467 @@
+#!/usr/bin/env node
+// Finds native scrollers written in CSS files, which the lint rule
+// `raft-ui/prefer-scroll-area` can't see: it reads JS and TSX only.
+//
+//   node node_modules/@botiverse/raft-ui/checks/native-scroll-css.mjs [<dir-file-or-glob>...] [--json]
+//
+// With no path it reads every .css file under the current directory. A
+// directory is read recursively; inside it node_modules, dist, build and dot
+// folders are skipped at any depth (`src/build` too), and so is raft-ui's own
+// CSS. A folder or a file named on the command line is read whatever it is
+// called. Exits 1 when it reports anything, 0
+// when it reports nothing, 2 on a path that doesn't exist or can't be read, a
+// glob that matches no file, or an unknown option, so an app can chain it into
+// its lint script:
+//
+//   "lint": "oxlint && node node_modules/@botiverse/raft-ui/checks/native-scroll-css.mjs src"
+//
+// Reported:
+// - a declaration of `overflow`, `overflow-x`, `overflow-y`, `overflow-inline`
+//   or `overflow-block` whose value has `auto`, `scroll` or `overlay` in it
+//   (`hidden auto` and `auto !important` too), in a rule at any depth
+//   (`@media`, `@layer`, `@supports`, nested rules);
+// - a native-scrolling Tailwind class in an `@apply`: `overflow-auto`,
+//   `overflow-scroll`, their `-x-` and `-y-` forms, with any variant or `!`,
+//   an arbitrary value (`overflow-[auto]`, `overflow-y-[scroll]`) or an
+//   arbitrary property (`[overflow:overlay]`).
+//
+// Not reported: `hidden`, `visible` and `clip`, a value that is only a
+// `var(--x)` with no keyword in it, a condition (`@supports (overflow: auto)`,
+// `@media (overflow-block: scroll)`), and anything in a comment or a string.
+//
+// Allowed with a `/* raft-ui: native-scroll <reason> */` comment: on a line of
+// its own right above the declaration (or the `@apply`), or after it at the
+// end of its line. One comment allows one declaration: above a line that holds
+// several, only the first; an `@apply` is one declaration however many lines
+// its classes take. A `//` line is not a comment in CSS and allows nothing. The comment starts with the marker, and one without
+// a reason doesn't count. The wording is
+// the lint rule's (design/about/use-raft-ui.md#lint-rules).
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PROPERTIES = new Set([
+  "overflow",
+  "overflow-x",
+  "overflow-y",
+  "overflow-inline",
+  "overflow-block",
+]);
+const SCROLLING_VALUE = /(?<![\w-])(?:auto|scroll|overlay)(?![\w-])/i;
+// A class (group 1 a keyword, 2 an arbitrary value) or an arbitrary property (group 3 its value).
+const OVERFLOW_CLASS =
+  /(?<![\w-])overflow(?:-[xy])?-(?:(auto|scroll)|\[([^\]\s]+)\])(?![\w-])|\[overflow(?:-(?:[xy]|inline|block))?:([^\]\s]+)\]/g;
+// The comment starts with the marker, and a reason follows it: a word, not the
+// `*` of a decorated comment.
+const OPT_OUT = /^[\s*]*raft-ui:\s*native-scroll\s+[^\s*]/;
+
+export const DOCS_URL = "https://raft-design.botiverse.build/components/scroll-area.md";
+export const MESSAGE = [
+  "A native scroller shows the platform's own scrollbar. The element each of these rules styles",
+  "should be a ScrollArea from @botiverse/raft-ui instead: the size stays on its className, grid,",
+  'flex, gap and padding go on contentClassName, with orientation="horizontal" for overflow-x and',
+  '"both" for overflow, and the overflow declaration is removed. For an element another component',
+  "renders, bind it with useScrollAreaContainer and render <ScrollAreaGutters> as its first child.",
+  "Where it must scroll natively (one of the allowed cases in the docs), say why in",
+  "/* raft-ui: native-scroll <reason> */ on the line above the declaration.",
+  `Docs: ${DOCS_URL}`,
+].join("\n");
+
+const collapse = (text) => text.replace(/\s+/g, " ").trim();
+
+/**
+ * The native scrollers in a CSS source: `{ line, column, selector, declaration,
+ * property, value }` for each, 1-based, in source order. `optOut: false` also
+ * returns the ones a `raft-ui: native-scroll <reason>` comment allows.
+ */
+export function scanCss(source, { optOut = true } = {}) {
+  const text = source.replace(/^/, " ");
+  const lineStarts = [0];
+  for (let i = 0; i < text.length; i++) if (text[i] === "\n") lineStarts.push(i + 1);
+  const lineOf = (offset) => {
+    let low = 0;
+    let high = lineStarts.length - 1;
+    while (low < high) {
+      const mid = (low + high + 1) >> 1;
+      if (lineStarts[mid] <= offset) low = mid;
+      else high = mid - 1;
+    }
+    return low;
+  };
+  const lineEnd = (line) => (line + 1 < lineStarts.length ? lineStarts[line + 1] - 1 : text.length);
+
+  const comments = [];
+  const findings = [];
+  // The preludes of the open blocks, outermost first.
+  const blocks = [];
+  // The statement being read: what it holds with comments left out, the offset
+  // of each character kept, and the depth of the brackets open in it.
+  let buffer = "";
+  let tail = "";
+  let offsets = [];
+  let depth = 0;
+  const reset = () => {
+    buffer = "";
+    offsets = [];
+    depth = 0;
+    tail = "";
+  };
+
+  function selector() {
+    const rules = blocks.filter((prelude) => prelude !== "" && !prelude.startsWith("@"));
+    if (rules.length > 0) return rules.join(" ");
+    return blocks.findLast((prelude) => prelude !== "") ?? "";
+  }
+
+  // The opt-out comments by line: one alone on its lines under its last line
+  // (its statement starts on the next), any other under its first (its
+  // statement ends on it).
+  let byLine;
+  function optOuts() {
+    if (byLine) return byLine;
+    byLine = new Map();
+    for (const comment of comments) {
+      if (!OPT_OUT.test(comment.value)) continue;
+      const first = lineOf(comment.start);
+      const last = lineOf(comment.end - 1);
+      const alone =
+        text.slice(lineStarts[first], comment.start).trim() === "" &&
+        text.slice(comment.end, lineEnd(last)).trim() === "";
+      const key = alone ? last : first;
+      if (!byLine.has(key)) byLine.set(key, []);
+      byLine.get(key).push({ comment, first, last, alone });
+    }
+    return byLine;
+  }
+
+  function allowed(start, end) {
+    if (!optOut) return false;
+    const startLine = lineOf(start);
+    const endLine = lineOf(end - 1);
+    const near = [...(optOuts().get(startLine - 1) ?? []), ...(optOuts().get(endLine) ?? [])];
+    return near.some(({ comment, first, last, alone }) => {
+      // On the line above, it allows the first statement of the next line
+      // only: nothing ends before it there (`.a { overflow: auto }`, not the
+      // second rule or declaration of a line, so not a minified file).
+      if (alone) {
+        if (last !== startLine - 1) return false;
+        const before = text.slice(lineStarts[startLine], start).replace(/\/\*[\s\S]*?\*\//g, "");
+        return !/[;}]/.test(before);
+      }
+      // At the end of the statement's own line: nothing but the end of the
+      // statement and of its rule between the two, and nothing after it.
+      if (comment.start < end || first !== endLine) return false;
+      const between = text.slice(end, comment.start).replace(/\/\*[\s\S]*?\*\//g, "");
+      return /^[\s;}]*$/.test(between) && /^[\s;}]*$/.test(text.slice(comment.end, lineEnd(last)));
+    });
+  }
+
+  function report(offset, declaration, property, value, start, end) {
+    const line = lineOf(offset);
+    findings.push({
+      start,
+      end,
+      line: line + 1,
+      column: offset - lineStarts[line] + 1,
+      selector: selector(),
+      declaration: collapse(declaration),
+      property,
+      value,
+    });
+  }
+
+  function statement() {
+    const lead = buffer.length - buffer.trimStart().length;
+    const body = buffer.trim();
+    if (body === "") return;
+    const start = offsets[lead];
+    const end = offsets[lead + body.length - 1] + 1;
+    const apply = /^@apply(?=[\s![]|$)/i.exec(body);
+    if (apply) {
+      for (const match of body.matchAll(OVERFLOW_CLASS)) {
+        const value = match[1] ?? (match[2] ?? match[3]).replaceAll("_", " ");
+        if (!SCROLLING_VALUE.test(value)) continue;
+        report(offsets[lead + match.index], `@apply ${match[0]}`, "@apply", match[0], start, end);
+      }
+      return;
+    }
+    const declaration = /^([-\w]+)\s*:([\s\S]*)$/.exec(body);
+    if (!declaration) return;
+    const property = declaration[1].toLowerCase();
+    if (!PROPERTIES.has(property)) return;
+    const value = collapse(declaration[2]);
+    if (!SCROLLING_VALUE.test(value)) return;
+    report(start, `${property}: ${value}`, property, value, start, end);
+  }
+
+  // Nothing of a statement has been read yet (a space stands for a comment).
+  const blank = () => buffer.length < 64 && buffer.trim() === "";
+  // The last characters kept, read apart from the buffer: reading the end of
+  // a string built a character at a time copies all of it.
+  const push = (char, offset) => {
+    tail = (tail + char).slice(-4);
+    buffer += char;
+    offsets.push(offset);
+  };
+
+  for (let i = 0; i < text.length; i++) {
+    const char = text[i];
+    if (char === "/" && text[i + 1] === "*") {
+      const close = text.indexOf("*/", i + 2);
+      const end = close === -1 ? text.length : close + 2;
+      comments.push({ start: i, end, value: text.slice(i + 2, close === -1 ? end : close) });
+      // A comment separates what is on its two sides, as a space does.
+      push(" ", i);
+      i = end - 1;
+    } else if (char === '"' || char === "'") {
+      // A string is kept whole: a brace or a semicolon in it ends nothing.
+      // An unclosed one ends with its line, as CSS reads it.
+      push(char, i);
+      for (i++; i < text.length && text[i] !== char && text[i] !== "\n"; i++) {
+        if (text[i] === "\\" && i + 1 < text.length) push(text[i], i++);
+        push(text[i], i);
+      }
+      if (text[i] === char) push(char, i);
+    } else if (char === "\\" && i + 1 < text.length) {
+      // An escaped character is never a delimiter: `.a\{b`, `.sm\:flex`.
+      push(char, i);
+      push(text[i + 1], ++i);
+    } else if (char === "/" && text[i + 1] === "/" && depth === 0 && blank()) {
+      // CSS has no `//` comment, but a build step may take one, and an
+      // apostrophe or a brace in such a line would be read as CSS. At the start
+      // of a statement the line is skipped whole, so the declaration under it
+      // is read on its own, and `//` allows nothing.
+      const end = text.indexOf("\n", i);
+      i = end === -1 ? text.length : end;
+    } else if (
+      char === "(" &&
+      /(?:^|[^\w-])url$/i.test(tail) &&
+      !/^\s*["']/.test(text.slice(i + 1, i + 40))
+    ) {
+      // An unquoted `url(…)` is kept whole to its `)`: `/*`, a brace or a
+      // semicolon in it (`url(/img/*.png)`, `url(data:…;base64,…)`) is part
+      // of the address.
+      push(char, i);
+      for (i++; i < text.length && text[i] !== ")"; i++) {
+        if (text[i] === "\\" && i + 1 < text.length) push(text[i], i++);
+        push(text[i], i);
+      }
+      if (text[i] === ")") push(")", i);
+    } else if (char === "(" || char === "[") {
+      depth++;
+      push(char, i);
+    } else if (char === ")" || char === "]") {
+      depth = Math.max(0, depth - 1);
+      push(char, i);
+    } else if (depth > 0 && char !== "}") {
+      // Inside brackets: `url(data:image/png;base64,…)` ends no declaration.
+      push(char, i);
+    } else if (char === "{") {
+      blocks.push(collapse(buffer));
+      reset();
+    } else if (char === "}") {
+      // The last declaration of a rule needs no semicolon.
+      statement();
+      reset();
+      blocks.pop();
+    } else if (char === ";") {
+      statement();
+      reset();
+    } else {
+      push(char, i);
+    }
+  }
+  statement();
+  // Once every comment is known: one at the end of a line comes after its statement.
+  return findings
+    .filter(({ start, end }) => !allowed(start, end))
+    .map(({ start: _start, end: _end, ...finding }) => finding);
+}
+
+const SKIP = new Set(["node_modules", "dist", "build"]);
+const byName = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+const toPosix = (file) => file.split(path.sep).join("/");
+
+function* walk(dir, seen = new Set()) {
+  // A folder is read once: a symlink back to one already read is a loop.
+  const real = realpathSync(dir);
+  if (seen.has(real)) return;
+  seen.add(real);
+  for (const name of readdirSync(dir).sort(byName)) {
+    if (SKIP.has(name) || name.startsWith(".")) continue;
+    const full = path.join(dir, name);
+    let stat;
+    try {
+      stat = statSync(full);
+    } catch {
+      continue; // a dangling symlink
+    }
+    if (stat.isDirectory()) yield* walk(full, seen);
+    else if (name.toLowerCase().endsWith(".css")) yield full;
+  }
+}
+
+/** A glob as a RegExp over a posix path: `**`, `*`, `?`, `{a,b}` and `[abc]`. */
+export function globToRegExp(glob) {
+  let out = "";
+  let braces = 0;
+  for (let i = 0; i < glob.length; i++) {
+    const char = glob[i];
+    if (char === "*") {
+      if (glob[i + 1] === "*") {
+        i++;
+        // `**/` is any number of folders, none included.
+        if (glob[i + 1] === "/") {
+          i++;
+          out += "(?:[^/]+/)*";
+        } else out += ".*";
+      } else out += "[^/]*";
+    } else if (char === "?") out += "[^/]";
+    else if (char === "{") {
+      braces++;
+      out += "(?:";
+    } else if (char === "}" && braces > 0) {
+      braces--;
+      out += ")";
+    } else if (char === "," && braces > 0) out += "|";
+    else if (char === "[") {
+      const close = glob.indexOf("]", i + 2);
+      if (close === -1) out += "\\[";
+      else {
+        const body = glob.slice(i + 1, close).replace(/\\/g, "\\\\");
+        out += `[${body.startsWith("!") ? `^${body.slice(1)}` : body}]`;
+        i = close;
+      }
+    } else out += char.replace(/[.+^$()|\\\]}]/g, "\\$&");
+  }
+  return new RegExp(`^${out}$`);
+}
+
+const IS_GLOB = /[*?{[]/;
+
+/** The CSS files a path names: the file, every .css file under a directory, or a glob's matches. */
+export function cssFiles(target, cwd = process.cwd()) {
+  const full = path.resolve(cwd, target);
+  if (existsSync(full)) return statSync(full).isDirectory() ? [...walk(full)] : [full];
+  if (!IS_GLOB.test(target)) return undefined;
+  // Walk from the folders the glob names before its first wildcard.
+  const parts = toPosix(target).split("/");
+  const fixed = [];
+  while (parts.length > 1 && !IS_GLOB.test(parts[0])) fixed.push(parts.shift());
+  const base = path.resolve(cwd, fixed.join("/") || ".");
+  if (!existsSync(base) || !statSync(base).isDirectory()) return [];
+  const pattern = globToRegExp(parts.join("/"));
+  return [...walk(base)].filter((file) => pattern.test(toPosix(path.relative(base, file))));
+}
+
+const PACKAGE_DIR = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+
+/** raft-ui's own CSS, which scrolls natively where its docs say: read by mistake, never reported. */
+function isOwnCss(file) {
+  if (toPosix(file).includes("/node_modules/@botiverse/raft-ui/")) return true;
+  try {
+    // A symlinked install (pnpm, a workspace) resolves to the package's folder.
+    const real = realpathSync(file);
+    const own = realpathSync(PACKAGE_DIR) + path.sep;
+    return real.startsWith(own) && toPosix(real.slice(own.length)).startsWith("dist/");
+  } catch {
+    return false;
+  }
+}
+
+const USAGE =
+  "usage: native-scroll-css.mjs [<dir-file-or-glob>...] [--json]\n" +
+  "Reports native scrollers (overflow: auto | scroll | overlay) in CSS files.\n" +
+  "With no path, reads every .css file under the current directory.";
+
+/** Runs the check: `{ code, stdout, stderr }`, without printing or exiting. */
+export function run(argv, cwd = process.cwd()) {
+  const flags = argv.filter((arg) => arg.startsWith("-"));
+  const targets = argv.filter((arg) => !arg.startsWith("-"));
+  if (flags.includes("--help") || flags.includes("-h"))
+    return { code: 0, stdout: `${USAGE}\n`, stderr: "" };
+  const unknown = flags.filter((flag) => flag !== "--json");
+  if (unknown.length > 0) {
+    return { code: 2, stdout: "", stderr: `unknown option ${unknown.join(", ")}\n${USAGE}\n` };
+  }
+  const json = flags.includes("--json");
+
+  const files = new Set();
+  for (const target of targets.length > 0 ? targets : ["."]) {
+    let found;
+    try {
+      found = cssFiles(target, cwd);
+    } catch (error) {
+      return {
+        code: 2,
+        stdout: "",
+        stderr: `can't read ${target}: ${error.code ?? error.message}\n`,
+      };
+    }
+    if (found === undefined) {
+      return { code: 2, stdout: "", stderr: `no such file or directory: ${target}\n` };
+    }
+    // A glob that matches nothing is a mistyped path, as a missing one is: a
+    // lint script must not stay green on it.
+    if (found.length === 0 && !existsSync(path.resolve(cwd, target))) {
+      return { code: 2, stdout: "", stderr: `no CSS files match: ${target}\n` };
+    }
+    for (const file of found) if (!isOwnCss(file)) files.add(file);
+  }
+
+  const findings = [];
+  for (const file of [...files].sort(byName)) {
+    const shown = toPosix(path.relative(cwd, file)) || toPosix(file);
+    let source;
+    try {
+      source = readFileSync(file, "utf8");
+    } catch (error) {
+      return {
+        code: 2,
+        stdout: "",
+        stderr: `can't read ${shown}: ${error.code ?? error.message}\n`,
+      };
+    }
+    for (const finding of scanCss(source)) {
+      findings.push({ file: shown, ...finding });
+    }
+  }
+
+  const code = findings.length > 0 ? 1 : 0;
+  if (json) {
+    const report = { files: files.size, findings, message: code ? MESSAGE : "", docs: DOCS_URL };
+    return { code, stdout: `${JSON.stringify(report, null, 2)}\n`, stderr: "" };
+  }
+  const plural = (count, word) => `${count} ${word}${count === 1 ? "" : "s"}`;
+  if (code === 0) {
+    return {
+      code,
+      stdout: `No native scrollers in ${plural(files.size, "CSS file")}.\n`,
+      stderr: "",
+    };
+  }
+  const lines = findings.map(
+    ({ file, line, column, selector, declaration }) =>
+      `${file}:${line}:${column}  ${selector ? `${selector} ` : ""}{ ${declaration} }`,
+  );
+  const reported = new Set(findings.map((finding) => finding.file)).size;
+  const summary = `${plural(findings.length, "native scroller")} in ${plural(reported, "CSS file")}.`;
+  return { code, stdout: `${lines.join("\n")}\n\n${summary}\n${MESSAGE}\n`, stderr: "" };
+}
+
+// Run only when invoked directly. Compare real paths: pnpm installs packages
+// through symlinks, so `process.argv[1]` (the path typed) and this module's
+// URL (the resolved file) differ.
+function isInvokedDirectly() {
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+if (isInvokedDirectly()) {
+  const { code, stdout, stderr } = run(process.argv.slice(2));
+  if (stdout) process.stdout.write(stdout);
+  if (stderr) process.stderr.write(stderr);
+  process.exitCode = code;
+}

package/dist/components/dialog/dialog.d.mts

@@ -57,8 +57,23 @@ export declare function DialogHeader({ className, bar, children, ...props }: Dia
 export type DialogBodyProps = ComponentPropsWithRef<"div"> & {
   /** A pinned bar of a scrolling (`size="wide"`) dialog. */
   bar?: boolean;
+  /**
+   * Scroll the body in a ScrollArea, with raft-ui's scrollbar in place of the
+   * platform's. A frame (`data-slot="dialog-body-frame"`) is rendered around
+   * the body and holds the scrollbars; the body keeps its slot, `className`,
+   * `ref`, native props and children, so a layout written on it
+   * (`grid gap-4`) is unchanged. It becomes the default in the next minor
+   * release: delete the prop then. A `bar` body ignores it.
+   */
+  unstable_scrollArea?: boolean;
+  /**
+   * With `unstable_scrollArea`, the class of the frame around the body: the
+   * classes that size the body in the dialog (`max-h-*`, `h-*`, `flex-*`) go
+   * here, not in `className`. Ignored without `unstable_scrollArea`.
+   */
+  wrapperClassName?: string;
 };
-export declare function DialogBody({ className, bar, children, ...props }: DialogBodyProps): import("react").JSX.Element;
+export declare function DialogBody({ className, bar, unstable_scrollArea: scrollArea, wrapperClassName, children, ...props }: DialogBodyProps): import("react").JSX.Element;
 export type DialogFooterProps = ComponentPropsWithRef<"div"> & {
   /** A pinned bar of a scrolling (`size="wide"`) dialog. */
   bar?: boolean;

package/dist/components/dialog/dialog.mjs

@@ -3,6 +3,8 @@ import { barButtonDesktop, headEdgePull } from "../../lib/head-edges.mjs";
 import { decisionWidth } from "../../lib/decision-width.mjs";
 import { PopupSheetReset } from "../../lib/popup-boundary.mjs";
 import { ScrollArea } from "../scroll-area/scroll-area.mjs";
+import { ScrollAreaGutters } from "../scroll-area/scroll-area-gutters.mjs";
+import { useScrollAreaContainer } from "../scroll-area/use-scroll-area-container.mjs";
 import { stackedActions, useStackedActions } from "../../lib/stacked-actions.mjs";
 import { tv } from "../../lib/tv.mjs";
 import { useThemeScopeProps } from "../../lib/theme/theme-scope.mjs";
@@ -15,7 +17,7 @@ import { PanelAction } from "../panel/panel-action.mjs";
 import { DialogSheetHeadContext, DialogSheetReset, DialogSheetSurfaceContext, dialogSheet, useDialogSheet, useInDialogSheetHead } from "./dialog-sheet-context.mjs";
 import { Dialog } from "@base-ui/react/dialog";
 import { ArrowLeft, X } from "lucide-react";
-import { Children, createContext, isValidElement, useContext, useEffect, useState } from "react";
+import { Children, createContext, isValidElement, useCallback, useContext, useEffect, useState } from "react";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 import { mergeProps } from "@base-ui/react/merge-props";
 import { useRender } from "@base-ui/react/use-render";
@@ -41,6 +43,12 @@ const dialog = tv({
 			"px-(--surface-inset) pt-1.5 pb-(--surface-inset) first:pt-(--surface-inset)",
 			"font-sans text-subhead text-foreground-muted"
 		],
+		bodyFrame: ["min-h-0 min-w-0 flex-1", "[--dialog-body-top:--spacing(1.5)] first:[--dialog-body-top:var(--surface-inset)]"],
+		bodyScroll: [
+			"min-h-0 min-w-0 flex-1",
+			"px-(--surface-inset) pt-(--dialog-body-top) pb-(--surface-inset)",
+			"font-sans text-subhead text-foreground-muted"
+		],
 		footer: [
 			"flex shrink-0 items-center justify-end",
 			...stackedActions,
@@ -285,10 +293,16 @@ function DialogHeader({ className, bar = false, children, ...props }) {
 		children
 	});
 }
-function DialogBody({ className, bar = false, children, ...props }) {
+function DialogBody({ className, bar = false, unstable_scrollArea: scrollArea = false, wrapperClassName, children, ...props }) {
 	const { sheet, setBodyEndSlot } = useDialogSheet();
 	const { body } = dialog({ bar });
 	const sheetBody = sheet ? cn(bar && dialogSheet().barBody(), dialogSheet().body()) : void 0;
+	if (scrollArea && !bar) return /* @__PURE__ */ jsx(DialogBodyScrollArea, {
+		className,
+		wrapperClassName,
+		...props,
+		children
+	});
 	return /* @__PURE__ */ jsxs("div", {
 		"data-slot": "dialog-body",
 		className: body({ className: sheetBody ? cn(sheetBody, className) : className }),
@@ -300,6 +314,86 @@ function DialogBody({ className, bar = false, children, ...props }) {
 		}) : null]
 	});
 }
+/**
+* DialogBody as a ScrollArea with absolute gutters: nothing is put inside the
+* body, so its own grid or flex layout holds only the caller's children.
+*/
+function DialogBodyScrollArea({ className, wrapperClassName, children, ref, tabIndex, ...props }) {
+	const { sheet, setBodyEndSlot } = useDialogSheet();
+	const { bodyFrame, bodyScroll } = dialog();
+	const [body, setBody] = useState(null);
+	const setRef = useCallback((element) => {
+		setBody(element);
+		if (typeof ref === "function") ref(element);
+		else if (ref) ref.current = element;
+	}, [ref]);
+	const holdsFocusable = useHoldsFocusable(body);
+	const { containerProps, frameProps, guttersProps } = useScrollAreaContainer({
+		containerRef: setRef,
+		guttersPosition: "absolute",
+		overscroll: "contain"
+	});
+	return /* @__PURE__ */ jsxs("div", {
+		...frameProps,
+		"data-slot": "dialog-body-frame",
+		className: bodyFrame({ className: cn(frameProps.className, wrapperClassName) }),
+		children: [/* @__PURE__ */ jsxs("div", {
+			"data-slot": "dialog-body",
+			...containerProps,
+			...props,
+			tabIndex: tabIndex ?? (holdsFocusable ? -1 : containerProps.tabIndex),
+			className: bodyScroll({ className: cn(containerProps.className, sheet && dialogSheet().body(), className) }),
+			children: [children, sheet ? /* @__PURE__ */ jsx("div", {
+				ref: setBodyEndSlot,
+				"data-slot": "dialog-sheet-body-end",
+				className: dialogSheet().bodyEnd()
+			}) : null]
+		}), /* @__PURE__ */ jsx(ScrollAreaGutters, { ...guttersProps })]
+	});
+}
+const FOCUSABLE = "a[href], button, input:not([type=\"hidden\"]), select, textarea, summary, iframe, audio[controls], video[controls], [contenteditable]:not([contenteditable=\"false\"]), [tabindex]";
+/** Whether Tab stops at `candidate`: enabled, not inert, and rendered. */
+function takesTab(candidate) {
+	if (!candidate.isContentEditable && candidate.tabIndex < 0) return false;
+	if (candidate.matches(":disabled") || candidate.closest("[inert]")) return false;
+	if (typeof candidate.checkVisibility !== "function") return true;
+	return candidate.checkVisibility({ visibilityProperty: true });
+}
+/** Whether `element` holds something Tab stops at, kept current as its content changes. */
+function useHoldsFocusable(element) {
+	const [holds, setHolds] = useState(true);
+	useEffect(() => {
+		if (!element) return;
+		const read = () => {
+			for (const candidate of element.querySelectorAll(FOCUSABLE)) if (takesTab(candidate)) {
+				setHolds(true);
+				return;
+			}
+			setHolds(false);
+		};
+		read();
+		if (typeof MutationObserver === "undefined") return;
+		const observer = new MutationObserver(read);
+		observer.observe(element, {
+			childList: true,
+			subtree: true,
+			attributes: true,
+			attributeFilter: [
+				"disabled",
+				"tabindex",
+				"href",
+				"inert",
+				"contenteditable",
+				"hidden",
+				"class",
+				"style",
+				"open"
+			]
+		});
+		return () => observer.disconnect();
+	}, [element]);
+	return holds;
+}
 function DialogFooter({ className, bar = false, hidden, children, ref, ...props }) {
 	const { sheet, bodyEndSlot } = useDialogSheet();
 	const items = Children.toArray(children);