@oxyhq/bloom 0.89.0 → 1.0.0

package/src/floating/shared.tsx

@@ -0,0 +1,233 @@
+/**
+ * The menu ROW itself, and the pieces of its shape that both the row set and
+ * BOTH sub-menu implementations need.
+ *
+ * `menu-rows.tsx` is universal; `menu-sub-inline.tsx` and `menu-sub-flyout.tsx`
+ * are the native and web halves of the sub trio and cannot import it (it imports
+ * them). This module is what they share instead of each re-deriving a row's
+ * inset, its type or its `inset` gutter — a sub-trigger that disagreed with the
+ * rows above it by two pixels is exactly the drift this prevents.
+ *
+ * ── WHY THIS IS NOT `item/Item` ANY MORE ─────────────────────────────────────
+ *
+ * Every menu row used to BE an `Item`, for the good reason that the disabled
+ * treatment, the destructive colour and the ARIA state then lived in one place.
+ * That is incompatible with expressing a row's shape as classes: `Item` writes
+ * its padding, gap, radius, minimum height and background into an inline
+ * `style`, and on web an inline style outranks a class whatever the array order
+ * — so every geometry class a menu row (or a CALLER) passed would be silently
+ * discarded. Conditioning `Item`'s own defaults on the presence of a `className`
+ * would push the same trap onto its several dozen other callers.
+ *
+ * So the row is its own one-node pressable here, and the three things `Item` was
+ * carrying are each two lines below. `Item` is untouched and still serves every
+ * other row in the library.
+ *
+ * ── ONE NODE, NOT TWO ────────────────────────────────────────────────────────
+ *
+ * `Item` renders a `Pressable` wrapping a `View`: the pressable holds the
+ * interaction and the view holds the geometry. A class landing on the pressable
+ * would then style a box that hugs nothing. `button/Button.tsx` collapsed the
+ * same two nodes for the same reason — layout and visuals are one box in the
+ * DOM, so a layout class and a visual class cannot land in different places.
+ */
+import React from 'react';
+import { type StyleProp, type ViewStyle } from 'react-native';
+
+import {
+  StyledPressable,
+  StyledText,
+  StyledView,
+  type WebAriaProps,
+} from '../styles/styled-primitives';
+import { useInteractionState } from '../hooks/use-interaction-state';
+import {
+  ROW_CHEVRON_CLASS,
+  ROW_CLASS,
+  ROW_DISABLED_CLASS,
+  ROW_ENABLED_CLASS,
+  ROW_GUTTER_CLASS,
+  ROW_HIGHLIGHT_CLASS,
+  ROW_INSET_CLASS,
+  ROW_LEADING_CLASS,
+  ROW_TEXT_CLASS,
+  ROW_TEXT_DESTRUCTIVE_CLASS,
+} from './constants';
+
+/**
+ * Join class strings, dropping the empty ones.
+ *
+ * Deliberately a CONCATENATION and never a substitution: a caller's `className`
+ * is appended to the row's own, so a single layout utility cannot strip the
+ * chrome (Bloom AGENTS.md, "Never let a component's own default `className`
+ * compete with the caller's"). What the caller then gets is Tailwind's ordinary
+ * cascade — two utilities for one property are resolved by the order Tailwind
+ * emits them in, not by the order of the attribute — which is the same contract
+ * every shadcn consumer already works under, and the `style` prop is still there
+ * as the unambiguous override.
+ */
+export function cx(...parts: (string | false | null | undefined)[]): string {
+  return parts.filter(Boolean).join(' ');
+}
+
+/**
+ * A string child becomes the row's LABEL so the row colours it (destructive,
+ * disabled); anything else is rendered verbatim, which is shadcn's own
+ * `<Icon /><Text>…</Text>` composition.
+ */
+export function splitChildren(children: React.ReactNode): {
+  title?: string;
+  body?: React.ReactNode;
+} {
+  return typeof children === 'string' ? { title: children } : { body: children };
+}
+
+/**
+ * Which ARIA role the row renders, and therefore which state it announces.
+ *
+ * `menuitem` carries no state of its own (a sub-trigger's `expanded` is a
+ * separate prop); `checkbox` and `radio` both carry a CHECKED one, which is what
+ * `aria-checked` spells. Spelling it `aria-*` is what makes it reach both
+ * platforms: react-native-web reads only `aria-*` and React Native folds
+ * `aria-checked` back into `accessibilityState`, so one prop covers both.
+ */
+export type MenuRowRole = 'menuitem' | 'checkbox' | 'radio';
+
+export interface MenuRowShellProps {
+  role: MenuRowRole;
+  /** `aria-checked`, for the two roles that have a checked state. */
+  checked?: boolean;
+  /** `aria-expanded`, for a sub-trigger. */
+  expanded?: boolean;
+  /**
+   * `aria-haspopup` — what this row OPENS, for the rows that open something.
+   *
+   * The companion to `expanded` and not a duplicate of it: `aria-expanded`
+   * announces that the thing is open or shut, `aria-haspopup` announces that
+   * there is a thing at all and what kind. A sub-trigger with only the first
+   * says "collapsed" without ever saying "submenu", so a screen-reader user
+   * cannot tell it from an ordinary row that happens to toggle something.
+   *
+   * Deliberately NOT derived from `expanded`: an ordinary row must not carry it,
+   * and the two are separate claims.
+   */
+  hasPopup?: WebAriaProps['aria-haspopup'];
+  disabled: boolean;
+  destructive?: boolean;
+  /** Indent to line up with the rows that carry an indicator. */
+  inset?: boolean;
+  /** This row carries an out-of-flow indicator, so it takes the full gutter. */
+  gutter?: boolean;
+  leading?: React.ReactNode;
+  trailing?: React.ReactNode;
+  /** A plain-string child, rendered as the row's own label. */
+  title?: string;
+  onPress: () => void;
+  accessibilityLabel?: string;
+  className?: string;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+  children?: React.ReactNode;
+}
+
+/**
+ * One menu row.
+ *
+ * The highlight rides component state rather than the CSS `:hover` pseudo-class,
+ * which is both what the target does (Radix's `data-[highlighted]` is a JS-driven
+ * roving highlight, not `:hover`) and the only mechanism that behaves the same on
+ * a platform with no pointer at all.
+ */
+export function MenuRowShell({
+  role,
+  checked,
+  expanded,
+  hasPopup,
+  disabled,
+  destructive = false,
+  inset = false,
+  gutter = false,
+  leading,
+  trailing,
+  title,
+  onPress,
+  accessibilityLabel,
+  className,
+  style,
+  testID,
+  children,
+}: MenuRowShellProps) {
+  const { state: hovered, onIn: onHoverIn, onOut: onHoverOut } = useInteractionState();
+  const { state: pressed, onIn: onPressIn, onOut: onPressOut } = useInteractionState();
+  const highlighted = (hovered || pressed) && !disabled;
+
+  const rowClass = cx(
+    ROW_CLASS,
+    disabled ? ROW_DISABLED_CLASS : ROW_ENABLED_CLASS,
+    gutter ? ROW_GUTTER_CLASS : inset ? ROW_INSET_CLASS : false,
+    highlighted && ROW_HIGHLIGHT_CLASS,
+    className,
+  );
+
+  return (
+    <StyledPressable
+      role={role}
+      // `radio` and `checkbox` are roles BOTH platforms have, so they travel on
+      // `accessibilityRole` as well. `menuitem` has no React Native counterpart,
+      // so the row announces itself as a button there — which is what `Item` did.
+      accessibilityRole={role === 'menuitem' ? 'button' : role}
+      accessibilityLabel={accessibilityLabel ?? title}
+      // One spelling, both platforms: react-native-web reads only `aria-*` and
+      // React Native folds these two back into `accessibilityState`. The disabled
+      // half travels on the `disabled` prop, which both platforms map.
+      {...(checked == null ? {} : { 'aria-checked': checked })}
+      {...(expanded == null ? {} : { 'aria-expanded': expanded })}
+      {...(hasPopup == null ? {} : { 'aria-haspopup': hasPopup })}
+      disabled={disabled}
+      onPress={disabled ? undefined : onPress}
+      onPressIn={disabled ? undefined : onPressIn}
+      onPressOut={disabled ? undefined : onPressOut}
+      // React Native types these on `Pressable` and only a platform with a real
+      // pointer ever calls them, so there is no `Platform.OS` branch to write and
+      // a touch never flashes a hover state on its way to a press.
+      onHoverIn={disabled ? undefined : onHoverIn}
+      onHoverOut={disabled ? undefined : onHoverOut}
+      className={rowClass}
+      style={style}
+      testID={testID}>
+      {leading != null ? (
+        <StyledView className={ROW_LEADING_CLASS}>{leading}</StyledView>
+      ) : null}
+      {title != null ? (
+        <StyledText
+          numberOfLines={1}
+          className={destructive ? ROW_TEXT_DESTRUCTIVE_CLASS : ROW_TEXT_CLASS}>
+          {title}
+        </StyledText>
+      ) : (
+        children
+      )}
+      {/* No wrapper: the shortcut's own `ms-auto` and the chevron's have to act
+          on a direct flex child of the row, and a slot view would absorb them. */}
+      {trailing}
+    </StyledPressable>
+  );
+}
+
+/**
+ * The sub-trigger's chevron slot — `size-4 shrink-0 ms-auto`. A component rather
+ * than a class string because both sub-menu forks render it and only the glyph
+ * differs.
+ */
+export function MenuRowChevron({ children }: { children: React.ReactNode }) {
+  return <StyledView className={ROW_CHEVRON_CLASS}>{children}</StyledView>;
+}
+
+/**
+ * `justify-between` — what a sub-trigger adds to a row, so its chevron is pushed
+ * to the far edge even when the label is short. The target spells the same
+ * intent twice (`justify-between` on the row AND `ms-auto` on the chevron); both
+ * are kept, because the first is what native's Yoga acts on and the second is
+ * what survives a caller replacing the row's justification.
+ */
+export const SUB_TRIGGER_CLASS = 'justify-between';

package/src/floating/types.ts

@@ -0,0 +1,365 @@
+/**
+ * The shared internals of Bloom's ANCHORED families — `dropdown-menu`,
+ * `context-menu`, `menubar` and `popover`.
+ *
+ * Nothing here is public API: `floating/` has no barrel and no subpath export,
+ * for the same reason `overlay/dropdown-placement` and `dialog/SheetShell` have
+ * none. The four families import it directly.
+ *
+ * What it holds, and why each piece is here rather than copied four times:
+ *
+ *  - `TriggerSlot` — Radix's `asChild` composition, plus the anchor wrapper the
+ *    web forks measure.
+ *  - `FloatingPanel` — the WEB anchored surface: portal, overlay rank, dismiss
+ *    layer and placement, in one place.
+ *  - `use-sheet-open-bridge` — the NATIVE half, bridging a Radix-shaped
+ *    `open`/`onOpenChange` pair onto `Dialog`'s imperative control.
+ *  - `menu-rows` — the row vocabulary all THREE menu families render.
+ *  - `context` — the contexts those rows read.
+ */
+import type { GestureResponderEvent, StyleProp, TextStyle, View, ViewStyle } from 'react-native';
+
+import type { WebAriaProps } from '../styles/styled-primitives';
+
+/**
+ * What a family's ROOT publishes to its own trigger and surface: the open
+ * state, and the box the surface anchors to. Each of the four families owns its
+ * OWN context object built on this shape — one shared context would make a
+ * menu nested inside a popover drive the popover.
+ */
+export interface OverlayShellContextValue {
+  open: boolean;
+  setOpen: (next: boolean) => void;
+  /** The trigger wrapper. Measured by the web forks, unused on native. */
+  anchorRef: React.RefObject<View | null>;
+}
+
+/**
+ * Which side of its anchor a floating surface PREFERS, and therefore which axis
+ * it fits-flips-clamps on. It is a preference:
+ * `overlay/dropdown-placement` flips to the OPPOSITE side when the named one
+ * does not fit and clamps when neither does.
+ *
+ * `'left'`/`'right'` are the submenu axis: a sub-panel flies out beside its
+ * trigger row rather than under it.
+ */
+export type FloatingSide = 'top' | 'bottom' | 'left' | 'right';
+
+/**
+ * How the surface lines up with its anchor on the CROSS axis — Radix/shadcn's
+ * `align`, mapped straight onto `resolveDropdownPlacement`'s own. Horizontal
+ * under a vertical `side`, vertical under a horizontal one.
+ */
+export type FloatingAlign = 'start' | 'center' | 'end';
+
+/** A viewport-relative anchor box. A right-click point is a zero-area anchor. */
+export interface FloatingAnchor {
+  top: number;
+  bottom: number;
+  left: number;
+  right: number;
+}
+
+/**
+ * The positioning props every anchored Bloom surface takes, spelled the way
+ * Radix/shadcn spells them so a call site ports across unchanged.
+ */
+export interface FloatingPositionProps {
+  /** Preferred side of the anchor. Defaults to `'bottom'`. */
+  side?: FloatingSide;
+  /** Horizontal alignment against the anchor. Defaults per component. */
+  align?: FloatingAlign;
+  /** Gap between the anchor and the surface, on the `side` axis. */
+  sideOffset?: number;
+  /** Shift along the `align` axis, applied before the viewport clamp. */
+  alignOffset?: number;
+}
+
+export interface FloatingPanelProps extends FloatingPositionProps {
+  /** Rendered only while true — `OverlayRoot` takes its stack rank on mount. */
+  open: boolean;
+  /**
+   * Viewport-relative box to anchor against, or `null` while it is still being
+   * measured (the panel renders nothing until it has one).
+   */
+  anchor: FloatingAnchor | null;
+  /** Dismiss on an outside press and on Escape. Defaults to `true`. */
+  dismissible?: boolean;
+  /**
+   * Whether the outside press is CAUGHT or merely observed. Defaults to `true`.
+   *
+   * A modal surface lays a full-screen `Backdrop` over the app: the press
+   * dismisses the surface and goes no further, which is what a dropdown menu, a
+   * context menu and a popover all want — the click that closes a menu should
+   * not also activate whatever was behind it.
+   *
+   * A NON-modal surface lays down nothing and listens for the press instead, so
+   * it dismisses AND the press reaches the app. `Menubar` needs this and it is
+   * the reason the option exists: with a backdrop in the way, clicking a sibling
+   * trigger while one menu is open only closed the first one, and switching
+   * menus took two clicks. Radix draws the same distinction under the same name.
+   */
+  modal?: boolean;
+  /** Called for a user-initiated dismissal (outside press or Escape). */
+  onDismiss: () => void;
+  /** Accessible name of the panel. */
+  label?: string;
+  /**
+   * ARIA role of the panel itself. `'menu'` for the three menu families,
+   * `'dialog'` for a popover.
+   */
+  role: 'menu' | 'dialog';
+  /** Floor for the panel width. A menu passes its anchor's width. */
+  minWidth?: number;
+  maxWidth?: number;
+  /**
+   * Utility classes APPENDED to the panel's own chrome (radius, border,
+   * background, inset, elevation) — never substituted for it. A surface that
+   * needs a different width or inset says so here.
+   */
+  className?: string;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+  children?: React.ReactNode;
+}
+
+/**
+ * The props a trigger hands to whatever it renders — either Bloom's own
+ * `Pressable`, or the caller's single child under `asChild`.
+ *
+ * `aria-expanded` is the one state prop here: React Native types exactly five
+ * boolean `aria-*` props (`busy`, `checked`, `disabled`, `expanded`,
+ * `selected`) and folds them back into `accessibilityState`, so it is the
+ * spelling that reaches BOTH platforms.
+ *
+ * `aria-haspopup` is here too, and it is a PROPERTY rather than a state: React
+ * Native types no such prop — there is no state for it to fold into
+ * `accessibilityState` — while react-native-web forwards it.
+ * `styles/styled-primitives.ts`'s `WebAriaProps` is what makes it spellable
+ * without a cast, and each family passes its OWN value from
+ * `floating/constants.ts`, because the five families open three different kinds
+ * of surface and one shared default would be a lie for two of them.
+ *
+ * BOTH of these reach an `asChild` child only if that child FORWARDS them.
+ * `cloneTrigger` sets them, and a component that destructures a known prop list
+ * drops what it does not name — measured, an `asChild` `<Button>` emitted
+ * `aria-label` (which `Button` named) and neither of these. Bloom's own `Button`
+ * now forwards both; an arbitrary caller element is the caller's to wire, which
+ * is inherent to `asChild` rather than something this type can fix.
+ */
+export interface TriggerHandleProps {
+  onPress: (event: GestureResponderEvent) => void;
+  onLongPress?: (event: GestureResponderEvent) => void;
+  disabled?: boolean;
+  accessibilityLabel?: string;
+  accessibilityRole?: 'button';
+  'aria-expanded'?: boolean;
+  /**
+   * What this trigger OPENS. Set by each family from its own constant in
+   * `floating/constants.ts`, never defaulted here — the five families open three
+   * different kinds of surface.
+   */
+  'aria-haspopup'?: WebAriaProps['aria-haspopup'];
+}
+
+/**
+ * The open-state contract every anchored ROOT takes, spelled the way
+ * Radix/shadcn spells it: uncontrolled by default, controlled the moment `open`
+ * is passed, and `onOpenChange` fires either way.
+ */
+export interface OverlayOpenProps {
+  /** Controlled open state. Omit for an uncontrolled surface. */
+  open?: boolean;
+  /** Initial open state when uncontrolled. Defaults to `false`. */
+  defaultOpen?: boolean;
+  /** Called whenever the surface opens or closes, from any cause. */
+  onOpenChange?: (open: boolean) => void;
+}
+
+/** Props shared by every trigger in the four families. */
+export interface OverlayTriggerProps {
+  children?: React.ReactNode;
+  /**
+   * Render the single element child AS the trigger, merging the open handler
+   * and a11y props into it (Radix's composition escape hatch). Without it the
+   * children render inside Bloom's own `Pressable`.
+   */
+  asChild?: boolean;
+  disabled?: boolean;
+  /** Accessible name. Ignored when the `asChild` child carries its own. */
+  label?: string;
+  /**
+   * Appended to whatever chrome the trigger draws of its own. A trigger that
+   * draws none (a dropdown's, a popover's) simply has nothing to append to, so
+   * the class lands alone.
+   */
+  className?: string;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}
+
+/** Props shared by the anchored surfaces of the three menus and the popover. */
+export interface OverlaySurfaceProps extends FloatingPositionProps {
+  children?: React.ReactNode;
+  /** Accessible name of the surface. */
+  label?: string;
+  /** Dismiss on outside press and Escape. Defaults to `true`. */
+  dismissible?: boolean;
+  minWidth?: number;
+  maxWidth?: number;
+  /** Appended to the surface's own chrome — see {@link FloatingPanelProps.className}. */
+  className?: string;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}
+
+// ---------------------------------------------------------------------------
+//  The menu ROW vocabulary
+//
+//  One set of prop shapes for the rows `dropdown-menu`, `context-menu` and
+//  `menubar` all render. Each family re-exports these under its own part names
+//  (`DropdownMenuItemProps`, `ContextMenuItemProps`, `MenubarItemProps`), which
+//  is shadcn's vocabulary — the props themselves are identical because the rows
+//  are identical.
+// ---------------------------------------------------------------------------
+
+export interface MenuRowProps {
+  /**
+   * Row content. A plain string is rendered as the row's own title — so it
+   * picks up the destructive and disabled colours — while element children are
+   * rendered verbatim, which is the shadcn composition (`<Icon /><Text>…`).
+   */
+  children?: React.ReactNode;
+  onPress?: () => void;
+  disabled?: boolean;
+  /** Leading slot (icon, avatar). A Bloom addition over shadcn's children-only row. */
+  leading?: React.ReactNode;
+  /** Trailing slot (shortcut, badge). */
+  trailing?: React.ReactNode;
+  /** Indent to line up with the rows that carry a checkbox or radio indicator. */
+  inset?: boolean;
+  /** `'destructive'` paints the row in the theme's negative colour. */
+  variant?: 'default' | 'destructive';
+  /**
+   * Keep the menu open after activation. Defaults to `false` — every menu row
+   * dismisses, which is what both shadcn and Bloom's previous menus did.
+   */
+  keepOpen?: boolean;
+  /**
+   * The row's accessible name.
+   *
+   * Only needed when `children` is not a plain string: a row composed as
+   * `<Icon /><Text>Profile</Text>` has no name a screen reader can announce,
+   * because the name is derived from a string child and there isn't one. A
+   * string child names itself and needs nothing here.
+   *
+   * This is where the upstream primitive's `textValue` lands. It is spelled
+   * `accessibilityLabel` because in Bloom that is all it does — `textValue`'s
+   * other job upstream is matching keystrokes for type-ahead, and Bloom has no
+   * type-ahead for it to feed.
+   */
+  accessibilityLabel?: string;
+  /**
+   * Utility classes APPENDED to the row's own — never substituted for them, so a
+   * single layout class cannot strip the chrome. Two utilities for one property
+   * are then resolved by Tailwind's own emission order, exactly as they are in
+   * any shadcn consumer; `style` remains the unambiguous override.
+   */
+  className?: string;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}
+
+export interface MenuCheckboxRowProps
+  extends Omit<MenuRowProps, 'onPress' | 'variant' | 'leading' | 'inset'> {
+  checked: boolean;
+  onCheckedChange: (checked: boolean) => void;
+}
+
+export interface MenuRadioGroupProps {
+  children?: React.ReactNode;
+  value?: string;
+  onValueChange: (value: string) => void;
+}
+
+export interface MenuRadioRowProps
+  extends Omit<MenuRowProps, 'onPress' | 'variant' | 'leading' | 'inset'> {
+  value: string;
+}
+
+export interface MenuLabelProps {
+  children?: React.ReactNode;
+  inset?: boolean;
+  /** Appended to the label's own classes — see {@link MenuRowProps.className}. */
+  className?: string;
+  style?: StyleProp<TextStyle>;
+}
+
+export interface MenuShortcutProps {
+  children?: React.ReactNode;
+  /** Appended to the shortcut's own classes — see {@link MenuRowProps.className}. */
+  className?: string;
+  style?: StyleProp<TextStyle>;
+}
+
+export interface MenuGroupProps {
+  children?: React.ReactNode;
+  className?: string;
+  style?: StyleProp<ViewStyle>;
+}
+
+export type MenuSubProps = React.PropsWithChildren<OverlayOpenProps>;
+
+export interface MenuSubTriggerProps {
+  children?: React.ReactNode;
+  disabled?: boolean;
+  inset?: boolean;
+  leading?: React.ReactNode;
+  /** The row's accessible name, when `children` is not a plain string. */
+  accessibilityLabel?: string;
+  /** Appended to the row's own classes — see {@link MenuRowProps.className}. */
+  className?: string;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}
+
+export interface MenuSubContentProps {
+  children?: React.ReactNode;
+  /** Appended to the sub panel's own classes — see {@link MenuRowProps.className}. */
+  className?: string;
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * The sub-menu trio, the ONE part of the row vocabulary that presents
+ * differently per platform: an inline disclosure inside a native sheet
+ * (`menu-sub-inline`), a flyout panel beside the row on web
+ * (`menu-sub-flyout`).
+ *
+ * `createMenuRows` takes a factory of this shape rather than branching on
+ * `Platform.OS`, because the flyout imports the web-only `FloatingPanel` — a
+ * runtime branch would link `react-dom` into every native bundle.
+ */
+export interface MenuSubParts {
+  Sub: React.ComponentType<MenuSubProps>;
+  SubTrigger: React.ComponentType<MenuSubTriggerProps>;
+  SubContent: React.ComponentType<MenuSubContentProps>;
+}
+
+/** Builds one family's sub trio. The argument is the family prefix, for `displayName`. */
+export type MenuSubFactory = (prefix: string) => MenuSubParts;
+
+/**
+ * The row parts one call of `createMenuRows` produces. Each menu family binds
+ * one set and publishes it under its own prefix.
+ */
+export interface MenuRowParts extends MenuSubParts {
+  Item: React.ComponentType<MenuRowProps>;
+  CheckboxItem: React.ComponentType<MenuCheckboxRowProps>;
+  RadioGroup: React.ComponentType<MenuRadioGroupProps>;
+  RadioItem: React.ComponentType<MenuRadioRowProps>;
+  Label: React.ComponentType<MenuLabelProps>;
+  Separator: React.ComponentType<Record<string, never>>;
+  Shortcut: React.ComponentType<MenuShortcutProps>;
+  Group: React.ComponentType<MenuGroupProps>;
+}

package/src/floating/use-anchor-rect.ts

@@ -0,0 +1,65 @@
+/**
+ * Measure a trigger into the viewport-relative box `resolveDropdownPlacement`
+ * takes. WEB ONLY — imported by the `.web.tsx` forks; the native families
+ * present a sheet and never anchor to anything.
+ *
+ * `getBoundingClientRect` rather than `measureInWindow`: the panels are
+ * `position: fixed`, so viewport coordinates are exactly what they need, and
+ * the DOM call is synchronous — an async `measureInWindow` callback lands a
+ * frame late and the surface visibly jumps into place on open.
+ */
+import { useCallback, useEffect, useLayoutEffect, useState } from 'react';
+import type { View } from 'react-native';
+
+import type { FloatingAnchor } from './types';
+
+/**
+ * react-native-web resolves a `View` ref to the DOM element itself. Read
+ * through the one method needed rather than asserting the whole `HTMLElement`
+ * interface, so a ref that is NOT a DOM node (a jsdom stub, a native build that
+ * reached this file by accident) answers `null` instead of throwing.
+ */
+function rectOf(node: View | null): FloatingAnchor | null {
+  const element = node as unknown as { getBoundingClientRect?: () => DOMRect } | null;
+  if (typeof element?.getBoundingClientRect !== 'function') return null;
+  const box = element.getBoundingClientRect();
+  return { top: box.top, bottom: box.bottom, left: box.left, right: box.right };
+}
+
+/**
+ * The trigger's viewport box while `open`, re-measured on scroll and resize.
+ * `null` until it has been measured — callers render nothing until then rather
+ * than painting at the wrong place for one frame.
+ */
+export function useAnchorRect(
+  ref: React.RefObject<View | null>,
+  open: boolean,
+): FloatingAnchor | null {
+  const [anchor, setAnchor] = useState<FloatingAnchor | null>(null);
+
+  const measure = useCallback(() => {
+    setAnchor(rectOf(ref.current));
+  }, [ref]);
+
+  useLayoutEffect(() => {
+    if (!open) {
+      setAnchor(null);
+      return;
+    }
+    measure();
+  }, [open, measure]);
+
+  useEffect(() => {
+    if (!open || typeof window === 'undefined') return;
+    // Capture phase: a scroll inside any ancestor moves the trigger too, and a
+    // bubbling listener never sees a scroll on an inner container.
+    window.addEventListener('resize', measure);
+    window.addEventListener('scroll', measure, true);
+    return () => {
+      window.removeEventListener('resize', measure);
+      window.removeEventListener('scroll', measure, true);
+    };
+  }, [open, measure]);
+
+  return anchor;
+}