@trackunit/react-components 2.5.4 → 2.6.2-alpha-770d9994af7.0

package/src/components/Popover/PopoverSizing.d.ts

@@ -9,6 +9,51 @@ type HeightValueParams = {
     value: HeightSizeLimit | undefined;
     availableHeight: number;
 };
+type FloatingWidthBudgetParams = {
+    /**
+     * Floating UI `size()`'s side-relative available width at the current placement.
+     */
+    availableWidth: number;
+    /**
+     * The viewport's width in pixels (`window.innerWidth`).
+     */
+    viewportWidth: number;
+    /**
+     * When true (nested horizontal submenu), prefer the viewport so `shift` can cascade with
+     * overlap instead of `size` shrinking the panel into the remaining side-slot.
+     */
+    preferViewportBudget: boolean;
+};
+/**
+ * Width budget passed into `getMaxWidthValue` / `getMinWidthValue` from `size()`'s `apply()`.
+ *
+ * For nested horizontal submenus, Floating UI's side-relative `availableWidth` is only the
+ * remaining strip beside the parent panel. Capping to that shrinks the panel until `shift` no
+ * longer sees overflow -- so the intentional "cascade with overlap" path never runs, and any
+ * CSS min-width on the content (e.g. `MenuContent`'s `min-w-[200px]`) then overflows the
+ * wrapper and the page.
+ *
+ * Using the viewport width as the budget keeps the panel at its preferred size; `flip` still
+ * tries both sides, and `shift` slides it over the parent when neither side fits.
+ */
+export declare const getFloatingWidthBudget: ({ availableWidth, viewportWidth, preferViewportBudget, }: FloatingWidthBudgetParams) => number;
+type ShiftOptionsParams = {
+    /**
+     * True for a nested submenu whose requested placement is horizontal (`right*` / `left*`).
+     */
+    isNestedHorizontal: boolean;
+};
+/**
+ * Options for Floating UI's `shift()` middleware.
+ *
+ * For `right`/`left` placement, `shift`'s default only moves along the alignment (vertical) axis.
+ * Nested horizontal submenus need `crossAxis: true` so they can slide horizontally over the parent
+ * when neither side has room -- the "cascade with overlap" path paired with `getFloatingWidthBudget`.
+ */
+export declare const getShiftOptions: ({ isNestedHorizontal, }: ShiftOptionsParams) => {
+    padding: number;
+    crossAxis?: boolean;
+};
 /**
  * Converts a width size value into a CSS dimension value for max constraints
  *
@@ -19,13 +64,20 @@ type HeightValueParams = {
  */
 export declare const getMaxWidthValue: ({ value, referenceWidth, availableWidth }: WidthValueParams) => string;
 /**
- * Converts a width size value into a CSS dimension value for min constraints
+ * Converts a width size value into a CSS dimension value for min constraints.
+ *
+ * A numeric `value` is clamped to `availableWidth` so a caller's desired minimum can never force the
+ * floating panel wider than the viewport space `size()` already determined was safe -- without this, a
+ * fixed minWidth would win a losing fight against `getMaxWidthValue`'s cap (CSS resolves `min-width` over
+ * `max-width` on conflict) and the panel would overflow past its container/viewport edge instead of
+ * shrinking to fit.
  *
  * @param params - The parameters object
  * @param params.value - The size value: number for pixels, "trigger-width" to match trigger, "none" for no constraint
  * @param params.referenceWidth - The width of the trigger element in pixels
+ * @param params.availableWidth - The available width in the viewport
  */
-export declare const getMinWidthValue: ({ value, referenceWidth, }: Omit<WidthValueParams, "availableWidth">) => string | undefined;
+export declare const getMinWidthValue: ({ value, referenceWidth, availableWidth }: WidthValueParams) => string | undefined;
 /**
  * Converts a height size value into a CSS dimension value for max constraints
  *

package/src/components/Popover/PopoverTypes.d.ts

@@ -38,6 +38,7 @@ export type PopoverSizing = {
     minHeight?: HeightSizeLimit;
     maxHeight?: HeightSizeLimit;
 };
+export type PopoverRole = "dialog" | "menu" | "listbox" | "grid" | "tree";
 export interface PopoverProps extends CommonProps {
     /**
      * Size constraints for the popover
@@ -75,6 +76,12 @@ export interface PopoverProps extends CommonProps {
      * Callback to be called when the popover open state changes
      */
     onOpenStateChange?: (open: boolean) => void;
+    /**
+     * ARIA role for the floating element, forwarded to Floating UI's `useRole`.
+     *
+     * @default "dialog"
+     */
+    role?: PopoverRole;
     /**
      * The id of the html element
      */
@@ -86,6 +93,20 @@ export type UsePopoverType = {
     isOpen: boolean;
     setIsOpen: Dispatch<SetStateAction<boolean>>;
     isModal: boolean | undefined;
+    /**
+     * This popover's id within its `MenuTree`, if it is rendered inside one. Used to register it
+     * with the tree via `FloatingNode` regardless of whether a tree exists.
+     */
+    nodeId: string;
+    /**
+     * Whether this popover itself has an ancestor node in its `MenuTree`, i.e. it is not the root of
+     * that tree (always `false` outside any `MenuTree`). Read from `useMenuTree()` before this
+     * popover wraps its own children in `<FloatingNode>` -- consumers rendered *inside* this popover's
+     * content (e.g. `MenuContent`) sit beneath that `FloatingNode` and would otherwise see their own
+     * ambient parent id resolve to this popover's id and misreport themselves as nested, so they
+     * should read this flag instead of calling `useMenuTree()` a second time from within.
+     */
+    isNested: boolean;
     labelId?: string;
     descriptionId?: string;
     setLabelId: (id: string) => void;

package/src/components/Popover/hoverScrollGuard.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Module-level (not React state) tracking of whether hover-driven `Popover` opening should be
+ * held back right now, because scrolling is either happening or has not yet settled.
+ *
+ * ### Root cause this guards against
+ * Scrolling any container recomputes the browser's pointer hit-test target on every frame, which
+ * fires real `pointerenter`/`pointerleave` pairs on whichever element now sits under an
+ * otherwise-stationary cursor -- indistinguishable, at the DOM level, from the user actually
+ * hovering that element. A hover-activated `Popover` reacting to those phantom events opens every
+ * row a scrolling list happens to carry under the cursor (most visible with `MenuItem`'s nested
+ * submenus in a scrolling list, but the same browser behavior affects any hover-activated
+ * `Popover`, e.g. a `Tooltip` over a scrolling table row).
+ *
+ * ### Why "settled", not "next pointer move"
+ * An earlier version of this guard cleared suppression on the next genuine `pointermove`, so a
+ * still-scrolling list would keep flipping back and forth between "suppressed" and "open the row
+ * the cursor happens to be over this frame" the moment the user so much as twitched the mouse
+ * mid-scroll. That's backwards from how this is meant to feel: while the list is moving, whatever
+ * was hovered before the scroll started should just stay put, and only once the scroll actually
+ * comes to rest should the row the cursor now stably rests over take over. Debouncing off the
+ * `scroll` event itself -- clearing suppression only after a lull longer than
+ * {@link SCROLL_SETTLE_DELAY_MS} with no further scroll events -- gets exactly that: suppression
+ * spans the whole scroll gesture (however bumpy), not just individual frames of it.
+ *
+ * ### Why not intercept/cancel the phantom event instead
+ * `mouseenter`/`pointerenter` don't natively bubble, so React simulates their capture/bubble
+ * dispatch internally -- not a stable surface to hook into from outside, and Floating UI's
+ * `useHover` owns that event handling anyway (it also drives `handleClose`/`safePolygon`, which
+ * still needs to work normally). Gating hover on "no scroll event anywhere in the last
+ * {@link SCROLL_SETTLE_DELAY_MS}ms" gets the same real-world result without any of that.
+ *
+ * ### Why page-wide listeners, not scoped to a particular scroll container
+ * A `scroll` event reaches a capturing-phase listener on `document` regardless of which element
+ * scrolled or whether the event itself bubbles, so a single pair of listeners here -- shared by
+ * every *opted-in* hover instance on the page, rather than each one attaching its own -- is both
+ * simpler and cheaper than resolving each `Popover`'s own scrollable ancestors. Subscription is
+ * gated in `usePopover` to delayed-hover nested `MenuTree` members only (ADR-0002), so plain
+ * Popovers/tooltips never attach the listeners or inherit suppression. The remaining trade-off is
+ * that scrolling *anywhere* briefly holds back hover-opens for those opted-in menu rows, not just
+ * near the scrolling container; acceptable since the guard clears itself shortly after scrolling
+ * settles, wherever the cursor then happens to rest.
+ *
+ * ### Visual hover highlight (CSS)
+ * The same scroll-induced `:hover` flips that would open phantom submenus also restyle every row
+ * the cursor passes over via CSS `:hover` backgrounds -- even while this guard holds the *open*
+ * state still. Consumers that want the highlight to freeze with the open state (notably
+ * `MenuItem`) key off {@link HOVER_SCROLL_SUPPRESSED_ATTR} on `<html>`, which this module mirrors
+ * onto the document in lockstep with suppression, so the highlight can follow open-state rules
+ * without re-rendering every row on each scroll tick.
+ *
+ * ### Why this also tracks the last real pointer position
+ * Once scrolling settles, `useHoverScrollGuard` needs to know which element the cursor now rests
+ * over so it can open that one. The obvious answer -- ask the browser via `:hover` -- turns out
+ * not to work: browsers only recompute an element's cached `:hover` state in response to a new
+ * real pointer event, not just because a re-render or attribute change made it hit-testable again.
+ * Since scrolling itself is exactly what carried the cursor's hit-test target across a run of rows
+ * without the physical mouse ever moving, there's typically no fresh pointer event left to trigger
+ * that recomputation right when settling happens -- so `:hover` stays stuck reporting whatever it
+ * last had, easily confirmed by comparing it against `document.elementFromPoint` at the same
+ * coordinates, which performs a fresh, on-demand hit-test instead of reading a cached flag. Tracking
+ * real client coordinates here (via a `pointermove` listener, sharing this module's lifecycle) lets
+ * `useHoverScrollGuard` run that same fresh `elementFromPoint` check itself once settled, rather
+ * than trusting a pseudo-class the browser hasn't gotten around to updating yet.
+ */
+export declare const HOVER_SCROLL_SUPPRESSED_ATTR = "data-hover-scroll-suppressed";
+export declare const hoverScrollGuard: {
+    isSuppressed: () => boolean;
+    /**
+     * The last real pointer position seen anywhere on the page, or `null` if no `pointermove` has
+     * happened yet (e.g. scrolling driven by keyboard/touch before any mouse input). See this
+     * module's doc comment for why consumers should use this over reading `:hover` directly.
+     */
+    getLastPointerPosition: () => {
+        x: number;
+        y: number;
+    } | null;
+    /**
+     * Subscribes to changes in suppression state, lazily attaching the shared `scroll` listener on
+     * first subscriber and tearing it down once the last one unsubscribes.
+     *
+     * @param listener Called whenever suppression state flips
+     * @returns {() => void} Unsubscribe function
+     */
+    subscribe: (listener: () => void) => (() => void);
+};

package/src/components/Popover/isElementVisible.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Whether `element` is currently visible to the user -- not clipped out by any scrollable/clipping
+ * ancestor (the browser fact `PopoverContent`'s `returnFocus` needs to respect: focusing a clipped
+ * element still succeeds, and browsers then auto-scroll it into view, fighting whatever caused it
+ * to be clipped in the first place -- see that module's doc comment) and not clipped by the
+ * viewport itself.
+ *
+ * Deliberately synchronous (plain `getBoundingClientRect`/`getComputedStyle` reads) rather than an
+ * `IntersectionObserver`, which only reports asynchronously on its own schedule and can't answer
+ * "is it visible right now" at the exact moment a popover is closing.
+ *
+ * @param element The element to check
+ * @returns {boolean} `false` if `element` (or any ancestor up to the viewport) clips it out
+ */
+export declare const isElementVisible: (element: HTMLElement) => boolean;

package/src/components/Popover/useHoverScrollGuard.d.ts

@@ -0,0 +1,54 @@
+import { FloatingContext, ReferenceType } from "@floating-ui/react";
+import { MutableRefObject } from "react";
+export interface UseHoverScrollGuardOptions {
+    /**
+     * Whether this consumer should participate in the shared page-wide scroll guard at all.
+     * When false, no document listeners are attached on behalf of this instance (ADR-0002 opt-in).
+     */
+    enabled: boolean;
+    /** Whether this `Popover`'s own `activation.hover` is enabled at all (before this guard). */
+    hoverEnabled: boolean;
+    /** See `usePopover`'s own `openSiblingPinned` -- a click-pinned sibling should still win. */
+    openSiblingPinned: boolean;
+    /** Whether this `Popover` is already open (nothing to do if so). */
+    isOpen: boolean;
+    /** This `Popover`'s own Floating UI context, used to imperatively open it. See below. */
+    popoverContext: FloatingContext;
+    /** This `Popover`'s reference element ref, used to check whether the cursor rests on it. See below. */
+    referenceRef: MutableRefObject<ReferenceType | null>;
+}
+/**
+ * Wires a single `Popover`'s hover interaction up to the shared `hoverScrollGuard`: holds its
+ * hover-opens back for as long as scrolling anywhere on the page hasn't yet settled (see
+ * `hoverScrollGuard`'s own doc comment for the full root-cause rationale), and -- once it settles
+ * -- imperatively opens this `Popover` if the cursor turns out to be resting on it, bypassing any
+ * open delay.
+ *
+ * ### Why the open needs its own imperative check
+ * Scrolling can carry the cursor's hit-test target across a whole run of rows without the physical
+ * cursor ever moving, so by the time scrolling settles there is no fresh `pointerenter` left for
+ * `useHover` to react to on whichever row the cursor ends up over: entering already happened
+ * (suppressed) while the list was still moving, not as a new enter.
+ *
+ * ### Why `elementFromPoint`, not `:hover`
+ * The obvious way to ask "is the cursor over this element right now" is `element.matches(":hover")`
+ * -- but browsers only recompute that cached flag in response to a *new* real pointer event, not
+ * just because the element became hit-testable again. Scrolling is exactly what leaves no such event
+ * behind at the moment settling happens, so `:hover` reports stale information right when it's
+ * needed most. `document.elementFromPoint` performs a fresh, on-demand hit-test instead of reading a
+ * cached flag, so it agrees with reality even when `:hover` hasn't caught up yet. It's checked
+ * against the last real pointer position `hoverScrollGuard` tracked (see that module's doc comment)
+ * rather than this reference's own bounding box, so it naturally returns nothing (and this correctly
+ * no-ops) if another element -- e.g. a still-open popover -- now sits on top of it.
+ *
+ * @param options See `UseHoverScrollGuardOptions`
+ * @param options.enabled Whether this consumer should subscribe to the shared scroll guard
+ * @param options.hoverEnabled Whether this `Popover`'s own `activation.hover` is enabled at all
+ * @param options.openSiblingPinned See `usePopover`'s own `openSiblingPinned`
+ * @param options.isOpen Whether this `Popover` is already open
+ * @param options.popoverContext This `Popover`'s own Floating UI context
+ * @param options.referenceRef This `Popover`'s reference element ref
+ * @returns {boolean} Whether hover-opens should be held back right now -- fold into `useHover`'s
+ * own `enabled` option alongside this `Popover`'s other activation conditions
+ */
+export declare const useHoverScrollGuard: ({ enabled, hoverEnabled, openSiblingPinned, isOpen, popoverContext, referenceRef, }: UseHoverScrollGuardOptions) => boolean;

package/src/components/Popover/usePopover.d.ts

@@ -6,4 +6,4 @@ import { PopoverProps, UsePopoverType } from "./PopoverTypes";
  * @param {PopoverProps} options The options for the popover
  * @returns {UsePopoverType} The data for the popover
  */
-export declare const usePopover: ({ initialOpen, placement, isModal, isOpen: controlledIsOpen, activation, dismissal, sizing, onOpenStateChange, id, className, "data-testid": dataTestId, }: PopoverProps) => UsePopoverType;
+export declare const usePopover: ({ initialOpen, placement, isModal, isOpen: controlledIsOpen, activation, dismissal, sizing, onOpenStateChange, role, id, className, "data-testid": dataTestId, }: PopoverProps) => UsePopoverType;

package/src/components/Sidebar/Sidebar.d.ts

@@ -2,7 +2,7 @@ import { ComponentProps, MouseEventHandler, ReactElement } from "react";
 import { CommonProps } from "../../common/CommonProps";
 import { Refable } from "../../common/Refable";
 import type { Styleable } from "../../common/Styleable";
-import { MenuList } from "../Menu/MenuList/MenuList";
+import { MenuContent } from "../Menu/MenuContent/MenuContent";
 import { MoreMenu } from "../Menu/MoreMenu/MoreMenu";
 export interface SidebarItemProps extends CommonProps, Styleable {
     /**
@@ -42,9 +42,9 @@ export interface SidebarProps extends CommonProps, Styleable, Refable<HTMLDivEle
      */
     moreMenuProps?: Omit<ComponentProps<typeof MoreMenu>, "children">;
     /**
-     * Pass custom props to the MenuList component used to render overflow items
+     * Pass custom props to the MenuContent component used to render overflow items
      */
-    menuListProps?: Omit<ComponentProps<typeof MenuList>, "children">;
+    menuListProps?: Omit<ComponentProps<typeof MenuContent>, "children">;
 }
 /**
  * Sidebar renders a responsive horizontal/vertical navigation bar that automatically collapses overflowing items into a MoreMenu.

package/src/hooks/getScrollbarWidth.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The layout-reserved width of `element`'s own vertical scrollbar (in pixels), or `0` when it
+ * isn't currently reserving any (no overflow, or an overlay-style scrollbar that doesn't consume
+ * layout space, e.g. macOS's default).
+ *
+ * `offsetWidth` includes the element's border and any reserved scrollbar; `clientWidth` excludes
+ * both. Subtracting the (computed) border widths from that difference isolates the scrollbar
+ * itself -- a naive `offsetWidth - clientWidth` would wrongly fold border width into the result.
+ *
+ * @param element The element to measure
+ * @returns {number} The scrollbar's reserved width in pixels, or `0`
+ */
+export declare const getScrollbarWidth: (element: HTMLElement) => number;

package/src/index.d.ts

@@ -51,11 +51,11 @@ export * from "./components/List/List.variants";
 export * from "./components/List/useList";
 export * from "./components/ListItem/ListItem";
 export * from "./components/ListItem/useListItemHeight";
+export * from "./components/Menu/MenuContent/MenuContent";
+export * from "./components/Menu/MenuContent/MenuContent.variants";
 export * from "./components/Menu/MenuDivider/MenuDivider";
 export * from "./components/Menu/MenuItem/MenuItem";
 export * from "./components/Menu/MenuItem/MenuItem.variants";
-export * from "./components/Menu/MenuList/MenuList";
-export * from "./components/Menu/MenuList/MenuList.variants";
 export * from "./components/Menu/MoreMenu/MoreMenu";
 export * from "./components/Notice/Notice";
 export * from "./components/Page/Page";
@@ -68,6 +68,8 @@ export * from "./components/PageHeader/PageHeader.variants";
 export * from "./components/PageHeader/types";
 export * from "./components/Pagination/Pagination";
 export * from "./components/Polygon/Polygon";
+export type { MenuTreeCloseEvent, MenuTreeOpenEvent, UseMenuTreeType } from "./components/Popover/MenuTree";
+export { MenuTree, useMenuTree } from "./components/Popover/MenuTree";
 export * from "./components/Popover/Popover";
 export * from "./components/Popover/PopoverContent";
 export * from "./components/Popover/PopoverTitle";

package/src/components/Menu/MenuList/MenuList.d.ts

@@ -1,83 +0,0 @@
-import { MouseEventHandler, ReactElement, ReactNode } from "react";
-import { CommonProps } from "../../../common/CommonProps";
-import type { Styleable } from "../../../common/Styleable";
-import { Refable } from "../../../common/Refable";
-export interface MenuListProps extends CommonProps, Styleable, Refable<HTMLDivElement> {
-    /**
-     * List of menu items to be rendered.
-     */
-    children: ReactNode;
-    /** Click handler - typically used to trigger close action. when propagation is NOT prevented on menuItem */
-    onClick?: MouseEventHandler<HTMLDivElement>;
-    /**
-     * Enable multi-selection in the menu list.
-     *
-     * @default false
-     */
-    isMulti?: boolean;
-    /**
-     * Array of IDs representing the currently selected items.
-     */
-    selectedItems?: Array<string>;
-    /**
-     * Callback triggered when selected items change.
-     */
-    onSelectionChange?: (selected: Array<string>) => void;
-}
-/**
- * The MenuList is a popover menu that appears above all other content on the page. The menu offers a list of actions or functions that a user can access by clicking on a trigger.
- *
- * **When to use**
- * - Use the MenuList if you have limited space and need to display overflow actions in a list.
- * - Use the MenuList for actions that are not essential to completing workflows.
- * - Don't use the MenuList to display single or multi-select items within form components. For dropdowns within select components, use SelectDropdown (component not available yet).
- *
- * @example MenuList with action items
- * ```tsx
- * import { MenuList, MenuItem, MoreMenu, Icon } from "@trackunit/react-components";
- *
- * const ActionsMenu = () => (
- *   <MoreMenu>
- *     {(close) => (
- *       <MenuList onClick={close}>
- *         <MenuItem id="edit" prefix={<Icon name="PencilSquare" size="small" />}>
- *           Edit
- *         </MenuItem>
- *         <MenuItem id="duplicate" prefix={<Icon name="DocumentDuplicate" size="small" />}>
- *           Duplicate
- *         </MenuItem>
- *         <MenuItem id="delete" prefix={<Icon name="Trash" size="small" />} destructive>
- *           Delete
- *         </MenuItem>
- *       </MenuList>
- *     )}
- *   </MoreMenu>
- * );
- * ```
- * @example Multi-select MenuList
- * ```tsx
- * import { MenuList, MenuItem, MoreMenu } from "@trackunit/react-components";
- * import { useState } from "react";
- *
- * const FilterMenu = () => {
- *   const [selected, setSelected] = useState<string[]>(["active"]);
- *
- *   return (
- *     <MoreMenu label="Filter by status">
- *       <MenuList
- *         isMulti
- *         selectedItems={selected}
- *         onSelectionChange={setSelected}
- *       >
- *         <MenuItem id="active">Active</MenuItem>
- *         <MenuItem id="idle">Idle</MenuItem>
- *         <MenuItem id="offline">Offline</MenuItem>
- *       </MenuList>
- *     </MoreMenu>
- *   );
- * };
- * ```
- * @param {MenuListProps} props - The props for the MenuList component
- * @returns {ReactElement} MenuList component
- */
-export declare const MenuList: ({ "data-testid": dataTestId, className, children, isMulti, selectedItems: controlledSelectedItems, onSelectionChange, style, ref, ...args }: MenuListProps) => ReactElement;