@botiverse/raft-ui 0.95.3 → 0.96.0

package/dist/lib/frame-insets.mjs

@@ -1,4 +1,5 @@
-import { useMemo, useState } from "react";
+import { sheetPopupBoundary, usePopupSheet, visualViewportShift } from "./popup-boundary.mjs";
+import { useLayoutEffect, useMemo, useState } from "react";
 // src/lib/frame-insets.ts
 const NO_FRAME_INSETS = Object.freeze({
 	top: 0,
@@ -127,15 +128,20 @@ function portalsToBody(container) {
 	return element == null || element === document.body || element === document.documentElement;
 }
 /**
-* The window inset by the frame insets, as a collision boundary rect. Its size
-* is read each time Base UI places the popup (it copies the rect's fields), so
-* it follows the window when it resizes while the popup is open.
+* The window inset by the frame insets, as a collision boundary rect. Its
+* fields are read each time Base UI places the popup (it copies them), so it
+* follows the window when it resizes while the popup is open, and WebKit's
+* visual viewport when it pans (visualViewportShift).
 */
 function frameCollisionBoundary(insets) {
 	const root = () => document.documentElement;
 	return {
-		x: insets.left,
-		y: insets.top,
+		get x() {
+			return insets.left + visualViewportShift().x;
+		},
+		get y() {
+			return insets.top + visualViewportShift().y;
+		},
 		get width() {
 			return Math.max(0, root().clientWidth - insets.left - insets.right);
 		},
@@ -191,16 +197,54 @@ function frameCollision(padding, boundary, insets, gap, container) {
 * inset, and `gap` (8px) inside each inset, the insets as the boundary
 * (frameCollision). A `collisionPadding` the caller passes wins as it is, and
 * a `collisionBoundary` the caller passes is kept. Call it from a part inside
-* the popup's portal, which mounts each time the popup opens.
+* the popup's portal, which mounts each time the popup opens, and spread the
+* result on the positioner.
+*
+* In a sheet (a phone's DialogSheetContent, a Drawer, an app's own under
+* SheetPopupBoundary) a popup with no `collisionBoundary` of its own takes the
+* sheet's: the area under its head, decided for this popup each time it is
+* placed (sheetPopupBoundary), whatever its portal container. Pass the
+* positioner's own `anchor` as `anchor`: the sheet then decides by it, not by
+* the trigger it would look up in the page. Outside a sheet nothing changes,
+* and no `ref` is returned.
 */
-function usePopupCollision(collisionPadding, collisionBoundary, defaultPadding, container, gap = 8) {
+function usePopupCollision(collisionPadding, collisionBoundary, defaultPadding, container, gap = 8, anchor) {
 	const insets = useFrameInsets(container);
-	return useMemo(() => collisionPadding === void 0 ? frameCollision(defaultPadding, collisionBoundary, insets, gap, container) : {
-		collisionPadding,
-		collisionBoundary
+	const sheet = usePopupSheet();
+	const [positioner] = useState(() => ({ current: null }));
+	const [latest] = useState(() => {
+		let current = anchor;
+		return {
+			read: () => current,
+			set: (next) => {
+				current = next;
+			}
+		};
+	});
+	useLayoutEffect(() => {
+		latest.set(anchor);
+	}, [latest, anchor]);
+	const sheetBoundary = useMemo(() => sheet && collisionBoundary === void 0 ? sheetPopupBoundary(sheet, () => positioner.current, latest.read) : void 0, [
+		sheet,
+		collisionBoundary,
+		positioner,
+		latest
+	]);
+	const boundary = collisionBoundary ?? sheetBoundary;
+	return useMemo(() => {
+		const collision = collisionPadding === void 0 ? frameCollision(defaultPadding, boundary, insets, gap, container) : {
+			collisionPadding,
+			collisionBoundary: boundary
+		};
+		return sheetBoundary ? {
+			...collision,
+			ref: positioner
+		} : collision;
 	}, [
 		collisionPadding,
-		collisionBoundary,
+		boundary,
+		sheetBoundary,
+		positioner,
 		defaultPadding,
 		insets,
 		gap,

package/dist/lib/overlay-depth.d.mts

@@ -24,6 +24,11 @@ export type OverlayLayerProviderProps = {
  * `useParentOverlayKind` inside it to pick its own scrim. Modal overlays only:
  * a non-modal one passes `modal={false}`, adds nothing, and must not call
  * `useParentOverlayKind` (it would read the layer below as its own).
+ *
+ * It is a surface of its own, modal or not, so what is inside starts outside
+ * any sheet around it: a popup opened in it isn't held inside a sheet it was
+ * opened from (dialog.md, "Popups in a sheet"). A sheet of the app's own puts
+ * its `SheetPopupBoundary` inside this provider.
  */
 export declare function OverlayLayerProvider({ kind, modal, children }: OverlayLayerProviderProps): import("react").JSX.Element;
 /**

package/dist/lib/overlay-depth.mjs

@@ -1,8 +1,27 @@
+import { PopupSheetReset } from "./popup-boundary.mjs";
 import { createContext, useContext, useMemo } from "react";
 import { jsx } from "react/jsx-runtime";
 // src/lib/overlay-depth.tsx
 const OverlayStackContext = createContext([]);
 /**
+* Adds a modal surface to the stack for everything under it. raft-ui's own
+* roots use this one: a root also holds its trigger, which is still in the
+* surface it is written in, so it must not start outside that sheet as
+* `OverlayLayerProvider` does.
+*/
+function OverlayLayer({ kind, modal, children }) {
+	const stack = useContext(OverlayStackContext);
+	const value = useMemo(() => modal ? [...stack, kind] : stack, [
+		stack,
+		kind,
+		modal
+	]);
+	return /* @__PURE__ */ jsx(OverlayStackContext.Provider, {
+		value,
+		children
+	});
+}
+/**
 * Tells everything under it that a modal surface is open, so a raft-ui
 * Dialog, AlertDialog or Drawer opened from inside draws the lighter nested
 * scrim (design/foundations/elevation.md#stacked-overlays). raft-ui's own
@@ -11,17 +30,17 @@ const OverlayStackContext = createContext([]);
 * `useParentOverlayKind` inside it to pick its own scrim. Modal overlays only:
 * a non-modal one passes `modal={false}`, adds nothing, and must not call
 * `useParentOverlayKind` (it would read the layer below as its own).
+*
+* It is a surface of its own, modal or not, so what is inside starts outside
+* any sheet around it: a popup opened in it isn't held inside a sheet it was
+* opened from (dialog.md, "Popups in a sheet"). A sheet of the app's own puts
+* its `SheetPopupBoundary` inside this provider.
 */
 function OverlayLayerProvider({ kind, modal, children }) {
-	const stack = useContext(OverlayStackContext);
-	const value = useMemo(() => modal ? [...stack, kind] : stack, [
-		stack,
+	return /* @__PURE__ */ jsx(OverlayLayer, {
 		kind,
-		modal
-	]);
-	return /* @__PURE__ */ jsx(OverlayStackContext.Provider, {
-		value,
-		children
+		modal,
+		children: /* @__PURE__ */ jsx(PopupSheetReset, { children })
 	});
 }
 /**
@@ -44,15 +63,15 @@ function useParentOverlayKind() {
 * children be a render function (`({ payload }) => …`), so keep that shape.
 */
 function withOverlayLayer(kind, modal, children) {
-	if (typeof children === "function") return (...args) => /* @__PURE__ */ jsx(OverlayLayerProvider, {
+	if (typeof children === "function") return (...args) => /* @__PURE__ */ jsx(OverlayLayer, {
 		kind,
 		modal,
 		children: children(...args)
 	});
-	return /* @__PURE__ */ jsx(OverlayLayerProvider, {
+	return /* @__PURE__ */ jsx(OverlayLayer, {
 		kind,
 		modal,
 		children
 	});
 }
-export { OverlayLayerProvider, useParentOverlayKind, withOverlayLayer };
+export { OverlayLayer, OverlayLayerProvider, useParentOverlayKind, withOverlayLayer };

package/dist/lib/popup-boundary.d.mts

@@ -0,0 +1,24 @@
+import { ReactNode, RefObject } from "react";
+export type SheetPopupBoundaryProps = {
+  /** The sheet's head: popups stay under its bottom edge. */
+  head: RefObject<Element | null>;
+  /**
+   * The sheet's surface: popups stay above its bottom edge.
+   * @default The head's parent element.
+   */
+  surface?: RefObject<Element | null>;
+  children?: ReactNode;
+};
+/**
+ * For a sheet an app draws itself (its own surface, a head that stays put and
+ * a body that scrolls): every raft-ui popup opened under it (Select, Combobox,
+ * ComboboxSelect, DropdownMenu, ContextMenu, Popover, PreviewCard, Tooltip,
+ * NotificationCenter) flips and sizes inside the sheet, under its head
+ * (sheetPopupBoundary says when it doesn't). Wrap the sheet's body in it, or
+ * the head and the body: a popup anchored in the head is left alone either
+ * way. Put it inside the sheet's own `OverlayLayerProvider`, which starts
+ * without one. raft-ui's own sheets, `DialogSheetContent` on a phone and
+ * `Drawer`, do this by themselves, and a `collisionBoundary` passed to a popup
+ * still wins. It renders no element.
+ */
+export declare function SheetPopupBoundary({ head, surface, children }: SheetPopupBoundaryProps): import("react").JSX.Element;

package/dist/lib/popup-boundary.mjs

@@ -0,0 +1,256 @@
+import { createContext, useContext, useMemo } from "react";
+import { jsx } from "react/jsx-runtime";
+// src/lib/popup-boundary.tsx
+/** WebKit, by floating-ui's own test (`isWebKit` in @floating-ui/utils). */
+function isWebKit() {
+	return typeof CSS !== "undefined" && CSS.supports?.("-webkit-backdrop-filter", "none") === true;
+}
+const NOT_NONE = (value) => !!value && value !== "none";
+const WILL_CHANGE = /transform|translate|scale|rotate|perspective|filter/;
+const CONTAIN = /paint|layout|strict|content/;
+/**
+* Whether floating-ui takes the window as `popup`'s offset parent: it is
+* `position: fixed` and no ancestor is a containing block for fixed boxes
+* (`getOffsetParent` and `isContainingBlock` in @floating-ui 1.8, as they
+* read in WebKit, where a filter doesn't count). With no popup to look at,
+* yes: a raft-ui popup is fixed and portaled beside its dialog or to the body.
+*/
+function offsetParentIsWindow(popup) {
+	if (!popup) return true;
+	if (getComputedStyle(popup).position !== "fixed") return false;
+	for (let node = popup.parentElement; node; node = node.parentElement) {
+		const css = getComputedStyle(node);
+		if (NOT_NONE(css.transform) || NOT_NONE(css.translate) || NOT_NONE(css.scale) || NOT_NONE(css.rotate) || NOT_NONE(css.perspective) || WILL_CHANGE.test(css.willChange || "") || CONTAIN.test(css.contain || "")) return false;
+	}
+	return true;
+}
+/**
+* How far to move a boundary rect so floating-ui (@floating-ui/dom 1.8, under
+* Base UI) reads it where the window draws it: 0 outside WebKit, and in WebKit
+* the visual viewport's offset, twice for a fixed popup whose offset parent is
+* the window and once for any other.
+*
+* In WebKit (floating-ui's own test: `-webkit-backdrop-filter` is supported)
+* the visual viewport has an offset while the page is panned under it: the
+* on-screen keyboard is up on iOS, or the page is pinch-zoomed. floating-ui
+* SUBTRACTS that offset from a boundary given as a rect
+* (`getClientRectFromClippingAncestor`), whatever the popup. For a
+* `position: fixed` popup whose offset parent is the window, which every
+* raft-ui popup is by default, it also ADDS the offset to the trigger's rect
+* (`getBoundingClientRect` with `shouldAddVisualOffsets`). A rect in window
+* coordinates therefore lands twice the offset away from the trigger it
+* bounds: with the keyboard up, a list bounded under a sheet's head ran under
+* the head again. For a popup with `positionMethod="absolute"`, or one
+* portaled into an element that is a containing block for fixed boxes (a
+* drawer's popup, which is transformed), the trigger gets no offset and the
+* rect is off by once. An element as the boundary gets no offset at all, so it
+* is no way around this.
+*
+* `popup` is the positioner being placed; without one the popup is taken to be
+* fixed to the window.
+*/
+function visualViewportShift(popup) {
+	if (typeof window === "undefined") return {
+		x: 0,
+		y: 0
+	};
+	const viewport = window.visualViewport;
+	if (!viewport || !isWebKit()) return {
+		x: 0,
+		y: 0
+	};
+	if (viewport.offsetLeft === 0 && viewport.offsetTop === 0) return {
+		x: 0,
+		y: 0
+	};
+	const times = offsetParentIsWindow(popup) ? 2 : 1;
+	return {
+		x: times * viewport.offsetLeft,
+		y: times * viewport.offsetTop
+	};
+}
+/**
+* The element an open popup is anchored to, found from its positioner, or
+* `null` when it can't be told. Base UI keeps this in each primitive's own
+* store, so it is read from the DOM Base UI renders:
+*
+* - a menu, a submenu, a popover, a select or a combobox: the open trigger
+*   (`data-popup-open`) whose `aria-controls` names an element inside the
+*   positioner;
+* - a tooltip or a preview card, which nothing names: the open trigger of its
+*   kind, when exactly one is open.
+*
+* A context menu is anchored to a point and has none. An `anchor` passed to
+* the popup isn't read here: sheetPopupBoundary takes it before this lookup.
+*/
+function findPopupAnchor(positioner) {
+	if (!positioner) return null;
+	const root = positioner.ownerDocument;
+	for (const trigger of root.querySelectorAll("[data-popup-open][aria-controls]")) {
+		const controlled = root.getElementById(trigger.getAttribute("aria-controls") ?? "");
+		if (controlled && positioner.contains(controlled)) return trigger;
+	}
+	const unnamed = positioner.querySelector("[data-slot=\"tooltip-content\"]") ? "[data-base-ui-tooltip-trigger][data-popup-open]" : positioner.querySelector("[data-slot=\"preview-card-content\"]") ? "[data-slot=\"preview-card-trigger\"][data-popup-open]" : null;
+	if (!unnamed) return null;
+	const open = root.querySelectorAll(unnamed);
+	return open.length === 1 ? open[0] : null;
+}
+const UNBOUNDED = 1e6;
+const isElement = (value) => typeof value.nodeType === "number";
+/** The element or virtual element an `anchor` prop stands for now, or `null`: an empty ref, or none passed. */
+function resolvePopupAnchor(anchor) {
+	const value = typeof anchor === "function" ? anchor() : anchor;
+	if (!value) return null;
+	if (!isElement(value) && "current" in value) return value.current;
+	return value;
+}
+/** Runs `clear` before the next frame is drawn, or as soon as the caller is done where there are no frames. */
+function nextFrame(clear) {
+	if (typeof requestAnimationFrame === "function") requestAnimationFrame(clear);
+	else queueMicrotask(clear);
+}
+/**
+* The part of a sheet a popup opened in it may cover: from the bottom of the
+* sheet's head to the bottom of what is visible of the sheet (its own bottom
+* edge, or the visual viewport's when the on-screen keyboard covers it), the
+* window's full width. A list bounded by it flips and shrinks under the head
+* instead of opening over it and past the sheet's top edge.
+*
+* Decided for each popup, each time Base UI places it (it copies the rect's
+* fields, which are getters), so the rect follows the sheet as the keyboard
+* resizes it. The sheet bounds nothing, and the popup keeps to the window as
+* outside a sheet, when:
+*
+* - the popup's anchor is inside the head (a tooltip or a menu on a head
+*   button belongs above or over the head, not under it);
+* - neither side of the anchor has `POPUP_ROOM_MIN_PX` of the area: a list
+*   held there would show a row or two, so it opens over the head instead;
+* - the sheet has no head, or nothing visible under it.
+*
+* The anchor is the popup's own `anchor` prop when `anchor` returns one that
+* resolves to something (resolvePopupAnchor), and the trigger found in the
+* page otherwise (findPopupAnchor). A virtual anchor has no element, so it is
+* inside the head when the middle of its rect is. A popup whose anchor can't
+* be found stays bounded.
+*
+* Floating-ui reads `y` and `height` one after the other, several times in
+* one placement (once for each of flip, shift, size and hide). The two reads
+* share one measurement: it is kept until the caller yields (a microtask), so
+* a sheet that resized or a keyboard that came up is measured again by the
+* next read. The trigger found in the page is kept longer, until the next
+* frame, for the same positioner and while it is still in the page and open:
+* which element a popup is anchored to doesn't change with layout, and finding
+* it is a query over the whole document. A lookup that found nothing isn't
+* kept.
+*
+* The rect is moved by `visualViewportShift`, so it is in the coordinates
+* floating-ui reads it in, not the window's.
+*/
+function sheetPopupBoundary(sheet, popup = () => null, anchor = () => void 0) {
+	let found = null;
+	const lookUp = (positioner) => {
+		if (found && found.positioner === positioner && found.anchor.isConnected && found.anchor.hasAttribute("data-popup-open")) return found.anchor;
+		found = null;
+		const trigger = findPopupAnchor(positioner);
+		if (trigger && positioner) {
+			found = {
+				positioner,
+				anchor: trigger
+			};
+			nextFrame(() => {
+				found = null;
+			});
+		}
+		return trigger;
+	};
+	const measure = () => {
+		const head = sheet.head();
+		const headBox = head?.getBoundingClientRect();
+		const surfaceBox = sheet.surface()?.getBoundingClientRect();
+		if (!head || !headBox || !surfaceBox) return null;
+		const viewport = window.visualViewport;
+		const top = headBox.bottom;
+		const bottom = viewport ? Math.min(surfaceBox.bottom, viewport.offsetTop + viewport.height) : surfaceBox.bottom;
+		if (bottom <= top) return null;
+		const positioner = popup();
+		const target = resolvePopupAnchor(anchor()) ?? lookUp(positioner);
+		if (target) {
+			const anchorBox = target.getBoundingClientRect();
+			if (isElement(target)) {
+				if (head.contains(target)) return null;
+			} else {
+				const x = (anchorBox.left + anchorBox.right) / 2;
+				const y = (anchorBox.top + anchorBox.bottom) / 2;
+				if (x >= headBox.left && x <= headBox.right && y >= headBox.top && y <= headBox.bottom) return null;
+			}
+			const above = Math.min(anchorBox.top, bottom) - top;
+			const below = bottom - Math.max(anchorBox.bottom, top);
+			if (Math.max(above, below) < 150) return null;
+		}
+		return {
+			top: top + visualViewportShift(positioner).y,
+			height: bottom - top
+		};
+	};
+	let measured = null;
+	const read = () => {
+		if (!measured) {
+			measured = { value: measure() };
+			queueMicrotask(() => {
+				measured = null;
+			});
+		}
+		return measured.value;
+	};
+	return {
+		x: -1e6,
+		width: 2 * UNBOUNDED,
+		get y() {
+			return read()?.top ?? -1e6;
+		},
+		get height() {
+			return read()?.height ?? 2 * UNBOUNDED;
+		}
+	};
+}
+/**
+* The sheet around a popup, or `undefined` outside one. Set by a phone sheet
+* (`DialogSheetContent`), a `Drawer` and `SheetPopupBoundary`; every modal
+* surface (a dialog, an alert dialog, a drawer, a lightbox, an app's own under
+* `OverlayLayerProvider`) and every sheet's head start without one.
+*/
+const PopupSheetContext = createContext(void 0);
+/** The sheet a popup is in, whose area it takes when its caller passes no `collisionBoundary`. */
+function usePopupSheet() {
+	return useContext(PopupSheetContext);
+}
+/** Starts its children outside any sheet: a new surface, or a sheet's head. */
+function PopupSheetReset({ children }) {
+	return /* @__PURE__ */ jsx(PopupSheetContext.Provider, {
+		value: void 0,
+		children
+	});
+}
+/**
+* For a sheet an app draws itself (its own surface, a head that stays put and
+* a body that scrolls): every raft-ui popup opened under it (Select, Combobox,
+* ComboboxSelect, DropdownMenu, ContextMenu, Popover, PreviewCard, Tooltip,
+* NotificationCenter) flips and sizes inside the sheet, under its head
+* (sheetPopupBoundary says when it doesn't). Wrap the sheet's body in it, or
+* the head and the body: a popup anchored in the head is left alone either
+* way. Put it inside the sheet's own `OverlayLayerProvider`, which starts
+* without one. raft-ui's own sheets, `DialogSheetContent` on a phone and
+* `Drawer`, do this by themselves, and a `collisionBoundary` passed to a popup
+* still wins. It renders no element.
+*/
+function SheetPopupBoundary({ head, surface, children }) {
+	const sheet = useMemo(() => ({
+		head: () => head.current,
+		surface: () => surface ? surface.current : head.current?.parentElement
+	}), [head, surface]);
+	return /* @__PURE__ */ jsx(PopupSheetContext.Provider, {
+		value: sheet,
+		children
+	});
+}
+export { PopupSheetContext, PopupSheetReset, SheetPopupBoundary, findPopupAnchor, resolvePopupAnchor, sheetPopupBoundary, usePopupSheet, visualViewportShift };

package/dist/lint/no-raw-z-index.mjs

@@ -9,10 +9,10 @@ import { classContext, constDeclarator, propertyKey, stringValue } from "./prefe
 * Reported:
 * - a Tailwind z-index class with a number or an arbitrary value (`z-10`,
 *   `-z-1`, `z-[60]`, `z-(--my-z)`, `[z-index:5]`, with any variant prefix or
-*   `!`) in a string or template literal that is a class, found as
-*   `raft-ui/prefer-scroll-area` finds one (a `className`, `class` or
-*   `*ClassName` attribute or property, an argument of `cn`, `tv` and the
-*   like, or a `const` of the same file used as a class). `z-auto` and the
+*   `!`) in a string or template literal that is a class: a `className`,
+*   `class` or `*ClassName` attribute or property, an argument of `cn`, `tv`
+*   and the like, or a `const` of the same file used as a class (not the
+*   wider set `raft-ui/prefer-scroll-area` reads). `z-auto` and the
 *   named layers (`z-raised`, `max-md:z-chrome`) are not reported;
 * - a `zIndex` property whose value is a number or a numeric string
 *   (`style={{ zIndex: 10 }}`, `const s = { zIndex: open ? 20 : "5" }`), a

package/dist/lint/prefer-scroll-area.d.mts

@@ -5,28 +5,56 @@
  *
  * Reported:
  * - a native-scrolling Tailwind class (`overflow`, `overflow-x` or `overflow-y`
- *   set to auto or scroll, with any variant prefix, `!`, or as an arbitrary
- *   property) in a string or template literal that is a class: the value of a
- *   `className`, `class` or `*ClassName` JSX attribute, or an argument of
- *   `cn`, `clsx`, `cx`, `tv`, `cva`, `twMerge`, `twJoin` or `classNames`, or
- *   a `className`, `class` or `*ClassName` property (a recipe slot's option,
- *   `content({ className: "…" })`), through conditionals, `&&`, arrays,
- *   objects (keys and values) and `+`;
+ *   set to auto or scroll, with any variant prefix, `!`, an arbitrary value
+ *   `overflow-y-[scroll]`, `overflow-[hidden_auto]` or an arbitrary property
+ *   `[overflow:overlay]`) in a string or template literal that is a class:
+ *   - the value of a JSX attribute with a class name (`className`, `class`,
+ *     `classNames`, `*ClassName`, `*ClassNames`, `*Class`), a property with
+ *     such a name (a recipe slot's option, `content({ className: "…" })`) or
+ *     the default of a parameter with one (`{ className = "…" }`), through
+ *     conditionals, `&&`, arrays, objects, members, `+`, a method called on
+ *     it (`[…].join(" ")`), a function that returns it (Base UI's
+ *     `className={(state) => …}`) and one call that isn't a class helper
+ *     (`className={wrap("…")}`);
+ *   - an argument of a class helper (`cn`, `clsx`, `cx`, `tv`, `cva`,
+ *     `twMerge`, `twJoin`, `classNames`), through the same, except a call
+ *     that isn't a class helper: what `t("…")` takes inside `cn(…)` is its
+ *     own, in a class attribute or outside one;
+ *   - an argument of the call a JSX spread spreads (`{...guard("…")}`), but
+ *     not under a key that isn't a class name, nor in a function;
  * - such a string in a `const` of the same file that is used as a class
- *   (`const log = "max-h-64 …"`, then `className={log}` or
- *   `cn(log)`), wherever in the file it is declared;
- * - an inline `style={{ overflow | overflowX | overflowY: "auto" | "scroll" }}`.
+ *   (`const log = "max-h-64 …"`, then `className={log}` or `cn(log)`),
+ *   wherever in the file it is declared: a string, a list joined into one, a
+ *   const built from another (`const b = \`p-2 ${a}\``), or an object or
+ *   variant map, of which only the members read as a class count
+ *   (`cls.body`), all of them when it is read by a computed key
+ *   (`VARIANTS[kind]`) or used whole;
+ * - a `style` whose `overflow`, `overflowX` or `overflowY` has `auto`,
+ *   `scroll` or `overlay` in it (`"hidden auto"` too): in a `style` attribute,
+ *   under a `style` key (`{...{ style: { … } }}`), or an object in a `const`
+ *   of the same file that a `style` uses (`style={s}`, `style={styles.pre}`).
  *
- * Allowed with a `raft-ui: native-scroll <reason>` comment, line or block, on
- * the line above the reported string (or at the end of its line): it covers
- * the string that starts on that line only, not the rest of the call or the
- * attribute it is in, so a class added to a multi-line `cn(...)` later is
- * still reported. For an inline style, the line of its property. A comment
- * without a reason doesn't count.
+ * The message follows the direction (down, sideways, both ways) and the
+ * element the hit is on: a `<textarea>` gets ScrollAreaTextarea; `<pre>`,
+ * `<html>`, `<body>` and `<iframe>` get no replacement, only the comment; a
+ * `classNames` object, whose classes go to another component's elements,
+ * gets `useScrollAreaContainer`; a ScrollArea's own class is to be removed.
  *
- * It reads the file as written, with no scope or type information: a const is
- * matched by its name in the same file, and a class in a `let`, an import, a
- * member (`styles.log`) or a function's return isn't seen.
+ * Allowed with a `raft-ui: native-scroll <reason>` comment, line or block:
+ * on a line of its own right above the reported string, or at the end of
+ * the string's own line. It covers the string that starts on that line only,
+ * not the rest of the call or the attribute it is in, so a class added to a
+ * multi-line `cn(...)` later is still reported; a comment at the end of a
+ * line doesn't reach the next line. For a style, the line of its property. A
+ * comment without a reason doesn't count.
+ *
+ * A const is resolved by scope where the linter gives one (a parameter of
+ * the same name is not the const), and by its name in the file otherwise.
+ *
+ * Known misses: a class added by script (`el.classList.add(…)`,
+ * `el.className = …`), a style set by script (`el.style.overflowY = "auto"`),
+ * a const or object imported from another file, a `let`, a string a function
+ * returns to a const, and CSS files.
  */
 export interface Position {
   line: number;
@@ -51,9 +79,22 @@ export interface Comment {
   };
   range?: [number, number];
 }
+/** The part of a scope this rule reads, to find the declaration a name refers to. */
+export interface Scope {
+  set?: Map<string, {
+    defs?: {
+      type: string;
+      node: Node;
+      parent?: Node | null;
+    }[];
+  }>;
+  upper?: Scope | null;
+}
 export interface SourceCode {
+  text?: string;
   getAllComments(): Comment[];
   getLocFromIndex(index: number): Position;
+  getScope?(node: Node): Scope | null;
 }
 export interface RuleContext {
   sourceCode?: SourceCode;