@botiverse/raft-ui 0.95.4 → 0.96.0

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;