@ariakit/react-components 0.1.0

package/src/hovercard/hovercard-heading.tsx

@@ -0,0 +1,68 @@
+import { createElement, createHook, forwardRef } from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import type { ElementType } from "react";
+import type { PopoverHeadingOptions } from "../popover/popover-heading.tsx";
+import { usePopoverHeading } from "../popover/popover-heading.tsx";
+import type { HovercardStore } from "./hovercard-store.ts";
+
+const TagName = "h1" satisfies ElementType;
+type TagName = typeof TagName;
+
+/**
+ * Returns props to create a `HovercardHeading` component. This hook must be
+ * used in a component that's wrapped with `Hovercard` so the `aria-labelledby`
+ * prop is properly set on the hovercard element.
+ * @see https://ariakit.com/components/hovercard
+ * @example
+ * ```jsx
+ * // This component must be wrapped with Hovercard
+ * const props = useHovercardHeading();
+ * <Role {...props}>Heading</Role>
+ * ```
+ */
+export const useHovercardHeading = createHook<TagName, HovercardHeadingOptions>(
+  function useHovercardHeading(props) {
+    props = usePopoverHeading(props);
+    return props;
+  },
+);
+
+/**
+ * Renders a heading in a hovercard. This component must be wrapped within
+ * [`Hovercard`](https://ariakit.com/reference/hovercard) so the
+ * `aria-labelledby` prop is properly set on the content element.
+ * @see https://ariakit.com/components/hovercard
+ * @example
+ * ```jsx {3}
+ * <HovercardProvider>
+ *   <Hovercard>
+ *     <HovercardHeading>Heading</HovercardHeading>
+ *   </Hovercard>
+ * </HovercardProvider>
+ * ```
+ */
+export const HovercardHeading = forwardRef(function HovercardHeading(
+  props: HovercardHeadingProps,
+) {
+  const htmlProps = useHovercardHeading(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface HovercardHeadingOptions<
+  T extends ElementType = TagName,
+> extends PopoverHeadingOptions<T> {
+  /**
+   * Object returned by the
+   * [`useHovercardStore`](https://ariakit.com/reference/use-hovercard-store)
+   * hook. If not provided, the closest
+   * [`Hovercard`](https://ariakit.com/reference/hovercard) or
+   * [`HovercardProvider`](https://ariakit.com/reference/hovercard-provider)
+   * components' context will be used.
+   */
+  store?: HovercardStore;
+}
+
+export type HovercardHeadingProps<T extends ElementType = TagName> = Props<
+  T,
+  HovercardHeadingOptions<T>
+>;

package/src/hovercard/hovercard-provider.tsx

@@ -0,0 +1,29 @@
+import type { ReactNode } from "react";
+import { HovercardContextProvider } from "./hovercard-context.tsx";
+import type { HovercardStoreProps } from "./hovercard-store.ts";
+import { useHovercardStore } from "./hovercard-store.ts";
+
+/**
+ * Provides a hovercard store to
+ * [Hovercard](https://ariakit.com/components/hovercard) components.
+ * @see https://ariakit.com/components/hovercard
+ * @example
+ * ```jsx
+ * <HovercardProvider timeout={250}>
+ *   <HovercardAnchor />
+ *   <Hovercard />
+ * </HovercardProvider>
+ * ```
+ */
+export function HovercardProvider(props: HovercardProviderProps = {}) {
+  const store = useHovercardStore(props);
+  return (
+    <HovercardContextProvider value={store}>
+      {props.children}
+    </HovercardContextProvider>
+  );
+}
+
+export interface HovercardProviderProps extends HovercardStoreProps {
+  children?: ReactNode;
+}

package/src/hovercard/hovercard-store.ts

@@ -0,0 +1,58 @@
+import * as Core from "@ariakit/components/hovercard/hovercard-store";
+import { useStore, useStoreProps } from "@ariakit/react-store";
+import type { Store } from "@ariakit/react-store";
+import type {
+  PopoverStoreFunctions,
+  PopoverStoreOptions,
+  PopoverStoreState,
+} from "../popover/popover-store.ts";
+import { usePopoverStoreProps } from "../popover/popover-store.ts";
+
+export function useHovercardStoreProps<T extends Core.HovercardStore>(
+  store: T,
+  update: () => void,
+  props: HovercardStoreProps,
+) {
+  useStoreProps(store, props, "timeout");
+  useStoreProps(store, props, "showTimeout");
+  useStoreProps(store, props, "hideTimeout");
+  return usePopoverStoreProps(store, update, props);
+}
+
+/**
+ * Creates a hovercard store to control the state of
+ * [Hovercard](https://ariakit.com/reference/hovercard) components.
+ * @see https://ariakit.com/components/hovercard
+ * @example
+ * ```jsx
+ * const hovercard = useHovercardStore({ placement: "top" });
+ *
+ * <HovercardAnchor store={hovercard}>@username</HovercardAnchor>
+ * <Hovercard store={hovercard}>Details</Hovercard>
+ * ```
+ */
+export function useHovercardStore(
+  props: HovercardStoreProps = {},
+): HovercardStore {
+  const [store, update] = useStore(Core.createHovercardStore, props);
+  return useHovercardStoreProps(store, update, props);
+}
+
+export interface HovercardStoreState
+  extends Core.HovercardStoreState, PopoverStoreState {}
+
+export interface HovercardStoreFunctions
+  extends
+    Omit<Core.HovercardStoreFunctions, "disclosure">,
+    PopoverStoreFunctions {}
+
+export interface HovercardStoreOptions
+  extends Omit<Core.HovercardStoreOptions, "disclosure">, PopoverStoreOptions {}
+
+export interface HovercardStoreProps
+  extends HovercardStoreOptions, Omit<Core.HovercardStoreProps, "disclosure"> {}
+
+export interface HovercardStore
+  extends
+    HovercardStoreFunctions,
+    Omit<Store<Core.HovercardStore>, "disclosure"> {}

package/src/hovercard/hovercard.tsx

@@ -0,0 +1,445 @@
+import { useStoreState } from "@ariakit/react-store";
+import {
+  useBooleanEvent,
+  useEvent,
+  useIsMouseMoving,
+  useLiveRef,
+  useMergeRefs,
+  usePortalRef,
+  useSafeLayoutEffect,
+  useWrapElement,
+  createElement,
+  createHook,
+  forwardRef,
+} from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import { sync } from "@ariakit/store";
+import {
+  contains,
+  addGlobalEventListener,
+  hasFocusWithin,
+  chain,
+  invariant,
+  isFalsyBooleanCallback,
+} from "@ariakit/utils";
+import type { BooleanOrCallback } from "@ariakit/utils";
+import type { ElementType, FocusEvent } from "react";
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+} from "react";
+import { createDialogComponent } from "../dialog/dialog.tsx";
+import type { PopoverOptions } from "../popover/popover.tsx";
+import { usePopover } from "../popover/popover.tsx";
+import {
+  HovercardScopedContextProvider,
+  useHovercardProviderContext,
+} from "./hovercard-context.tsx";
+import type { HovercardStore } from "./hovercard-store.ts";
+import type { Point } from "./utils/polygon.ts";
+import {
+  getElementPolygon,
+  getEventPoint,
+  isPointInPolygon,
+} from "./utils/polygon.ts";
+
+const TagName = "div" satisfies ElementType;
+type TagName = typeof TagName;
+type HTMLType = HTMLElementTagNameMap[TagName];
+
+function isMovingOnHovercard(
+  target: Node | null | undefined,
+  card: HTMLElement,
+  anchor: HTMLElement | null,
+  nested?: HTMLElement[],
+) {
+  // The hovercard element has focus so we should keep it visible.
+  if (hasFocusWithin(card)) return true;
+  if (!target) return false;
+  // The mouse is moving on an element inside the hovercard.
+  if (contains(card, target)) return true;
+  // The mouse is moving on an element inside the anchor element.
+  if (anchor && contains(anchor, target)) return true;
+  // The mouse is moving on an element inside a nested hovercard.
+  if (nested?.some((card) => isMovingOnHovercard(target, card, anchor))) {
+    return true;
+  }
+  return false;
+}
+
+// When the hovercard element has focus, we should move focus back to the anchor
+// element when the hovercard gets hidden (or unmounted).
+function useAutoFocusOnHide({
+  store,
+  ...props
+}: HovercardProps & { store: HovercardStore }) {
+  const [autoFocusOnHide, setAutoFocusOnHide] = useState(false);
+  const mounted = useStoreState(store, "mounted");
+
+  // Resets autoFocusOnHide
+  useEffect(() => {
+    if (!mounted) {
+      setAutoFocusOnHide(false);
+    }
+  }, [mounted]);
+
+  const onFocusProp = props.onFocus;
+
+  const onFocus = useEvent((event: FocusEvent<HTMLType>) => {
+    onFocusProp?.(event);
+    if (event.defaultPrevented) return;
+    setAutoFocusOnHide(true);
+  });
+
+  // TODO: Maybe use state.anchorElement directly?
+  const finalFocusRef = useRef<HTMLElement | null>(null);
+
+  useEffect(() => {
+    return sync(store, ["anchorElement"], (state) => {
+      finalFocusRef.current = state.anchorElement;
+    });
+  }, [store]);
+
+  props = {
+    autoFocusOnHide,
+    finalFocus: finalFocusRef,
+    ...props,
+    onFocus,
+  };
+
+  return props;
+}
+
+const NestedHovercardContext = createContext<
+  ((element: HTMLElement) => () => void) | null
+>(null);
+
+/**
+ * Returns props to create a `Hovercard` component.
+ * @see https://ariakit.com/components/hovercard
+ * @example
+ * ```jsx
+ * const store = useHovercardStore();
+ * const props = useHovercard({ store });
+ * <HovercardAnchor store={store}>@username</HovercardAnchor>
+ * <Role {...props}>Details</Role>
+ * ```
+ */
+export const useHovercard = createHook<TagName, HovercardOptions>(
+  function useHovercard({
+    store,
+    modal = false,
+    portal = modal,
+    hideOnEscape = true,
+    hideOnHoverOutside = true,
+    disablePointerEventsOnApproach = !!hideOnHoverOutside,
+    ...props
+  }) {
+    const context = useHovercardProviderContext();
+    store = store || context;
+
+    invariant(
+      store,
+      process.env.NODE_ENV !== "production" &&
+        "Hovercard must receive a `store` prop or be wrapped in a HovercardProvider component.",
+    );
+
+    const ref = useRef<HTMLType>(null);
+    const [nestedHovercards, setNestedHovercards] = useState<HTMLElement[]>([]);
+    const hideTimeoutRef = useRef(0);
+    const enterPointRef = useRef<Point | null>(null);
+    const { portalRef, domReady } = usePortalRef(portal, props.portalRef);
+
+    const isMouseMoving = useIsMouseMoving();
+
+    const mayHideOnHoverOutside = !!hideOnHoverOutside;
+    const hideOnHoverOutsideProp = useBooleanEvent(hideOnHoverOutside);
+    const mayDisablePointerEvents = !!disablePointerEventsOnApproach;
+    const disablePointerEventsProp = useBooleanEvent(
+      disablePointerEventsOnApproach,
+    );
+
+    const open = useStoreState(store, "open");
+    const mounted = useStoreState(store, "mounted");
+
+    // Checks whether the mouse is moving toward the hovercard. If not, hide the
+    // card after a short delay (hideTimeout).
+    useEffect(() => {
+      if (!domReady) return;
+      if (!mounted) return;
+      if (!mayHideOnHoverOutside && !mayDisablePointerEvents) return;
+      const element = ref.current;
+      if (!element) return;
+      const onMouseMove = (event: MouseEvent) => {
+        if (!store) return;
+        if (!isMouseMoving()) return;
+        const { anchorElement, hideTimeout, timeout } = store.getState();
+        const enterPoint = enterPointRef.current;
+        const [target] = event.composedPath() as Node[];
+        const anchor = anchorElement;
+        // Checks whether the hovercard element has focus or the mouse is moving
+        // through valid hovercard elements.
+        if (isMovingOnHovercard(target, element, anchor, nestedHovercards)) {
+          // While the mouse is moving over the anchor element while the hover
+          // card is open, keep track of the mouse position so we can use the
+          // last point before the mouse leaves the anchor element.
+          enterPointRef.current =
+            target && anchor && contains(anchor, target)
+              ? getEventPoint(event)
+              : null;
+          window.clearTimeout(hideTimeoutRef.current);
+          hideTimeoutRef.current = 0;
+          return;
+        }
+        // If there's already a scheduled timeout to hide the hovercard, we do
+        // nothing.
+        if (hideTimeoutRef.current) return;
+        // Enter point will be null when the user hovers over the hovercard
+        // element.
+        if (enterPoint) {
+          const currentPoint = getEventPoint(event);
+          const polygon = getElementPolygon(element, enterPoint);
+          // If the current event's mouse position is inside the transit
+          // polygon, this means that the mouse is moving toward the hover card,
+          // so we disable this event. This is necessary because the mousemove
+          // event may trigger focus on other elements and close the hovercard.
+          if (isPointInPolygon(currentPoint, polygon)) {
+            // Refreshes the enter point.
+            enterPointRef.current = currentPoint;
+            if (!disablePointerEventsProp(event)) return;
+            event.preventDefault();
+            event.stopPropagation();
+            return;
+          }
+        }
+        if (!hideOnHoverOutsideProp(event)) return;
+        // Otherwise, hide the hovercard after a short delay (hideTimeout).
+        hideTimeoutRef.current = window.setTimeout(() => {
+          hideTimeoutRef.current = 0;
+          store?.hide();
+        }, hideTimeout ?? timeout);
+      };
+      return chain(addGlobalEventListener("mousemove", onMouseMove, true), () =>
+        clearTimeout(hideTimeoutRef.current),
+      );
+    }, [
+      store,
+      isMouseMoving,
+      domReady,
+      mounted,
+      mayHideOnHoverOutside,
+      mayDisablePointerEvents,
+      nestedHovercards,
+      disablePointerEventsProp,
+      hideOnHoverOutsideProp,
+    ]);
+
+    // Disable mouse events while the mouse is moving toward the hovercard. This
+    // is necessary because these events may trigger focus on other elements and
+    // close the hovercard while the user is moving the mouse toward it.
+    useEffect(() => {
+      if (!domReady) return;
+      if (!mounted) return;
+      if (!mayDisablePointerEvents) return;
+      const disableEvent = (event: MouseEvent) => {
+        const element = ref.current;
+        if (!element) return;
+        const enterPoint = enterPointRef.current;
+        if (!enterPoint) return;
+        const polygon = getElementPolygon(element, enterPoint);
+        if (isPointInPolygon(getEventPoint(event), polygon)) {
+          if (!disablePointerEventsProp(event)) return;
+          event.preventDefault();
+          event.stopPropagation();
+        }
+      };
+      return chain(
+        // Note: we may need to add pointer events here in the future.
+        addGlobalEventListener("mouseenter", disableEvent, true),
+        addGlobalEventListener("mouseover", disableEvent, true),
+        addGlobalEventListener("mouseout", disableEvent, true),
+        addGlobalEventListener("mouseleave", disableEvent, true),
+      );
+    }, [domReady, mounted, mayDisablePointerEvents, disablePointerEventsProp]);
+
+    // The autoFocusOnShow state will be set to true when the hovercard
+    // disclosure element is clicked. We have to reset it to false when the
+    // hovercard element gets hidden.
+    useEffect(() => {
+      if (!domReady) return;
+      if (open) return;
+      store?.setAutoFocusOnShow(false);
+    }, [store, domReady, open]);
+
+    // On unmount as well.
+    const openRef = useLiveRef(open);
+    useEffect(() => {
+      if (!domReady) return;
+      return () => {
+        // oxlint-disable-next-line exhaustive-deps
+        if (!openRef.current) {
+          store?.setAutoFocusOnShow(false);
+        }
+      };
+      // This cleanup intentionally reads the live ref so it can observe the
+      // latest open state at unmount time.
+      // oxlint-disable-next-line exhaustive-deps
+    }, [store, domReady]);
+
+    const registerOnParent = useContext(NestedHovercardContext);
+
+    // Register the hovercard as a nested hovercard on the parent hovercard if
+    // it's not a modal, is portal and is mounted. We don't need to register
+    // non-portal hovercards because they will be captured by the contains
+    // function in the isMovingOnHovercard function above. This must be a layout
+    // effect so we don't lose mouse move events right after the nested
+    // hovercard has been mounted (for example, a submenu that's overlapping its
+    // menu button and we keep moving the mouse while the submenu is due to
+    // open).
+    useSafeLayoutEffect(() => {
+      if (modal) return;
+      if (!portal) return;
+      if (!mounted) return;
+      if (!domReady) return;
+      const element = ref.current;
+      if (!element) return;
+      return registerOnParent?.(element);
+    }, [modal, portal, mounted, domReady]);
+
+    const registerNestedHovercard = useCallback(
+      (element: any) => {
+        setNestedHovercards((prevElements) => [...prevElements, element]);
+        const parentUnregister = registerOnParent?.(element);
+        return () => {
+          setNestedHovercards((prevElements) =>
+            prevElements.filter((item) => item !== element),
+          );
+          parentUnregister?.();
+        };
+      },
+      [registerOnParent],
+    );
+
+    props = useWrapElement(
+      props,
+      (element) => (
+        <HovercardScopedContextProvider value={store}>
+          <NestedHovercardContext.Provider value={registerNestedHovercard}>
+            {element}
+          </NestedHovercardContext.Provider>
+        </HovercardScopedContextProvider>
+      ),
+      [store, registerNestedHovercard],
+    );
+
+    props = {
+      ...props,
+      ref: useMergeRefs(ref, props.ref),
+    };
+
+    props = useAutoFocusOnHide({ store, ...props });
+
+    // If the hovercard is modal, we should always autoFocus on show.
+    const autoFocusOnShow = useStoreState(
+      store,
+      (state) => modal || state.autoFocusOnShow,
+    );
+
+    props = usePopover({
+      store,
+      modal,
+      portal,
+      autoFocusOnShow,
+      ...props,
+      portalRef,
+      hideOnEscape(event) {
+        if (isFalsyBooleanCallback(hideOnEscape, event)) return false;
+        // Hide again on the next frame to avoid the popover being shown again
+        // when the user presses the escape key and trigger focusVisible on the
+        // anchor element (which is the case of tooltip anchor).
+        requestAnimationFrame(() => {
+          requestAnimationFrame(() => {
+            store?.hide();
+          });
+        });
+        return true;
+      },
+    });
+
+    return props;
+  },
+);
+
+/**
+ * Renders a hovercard element, which is a popover that's usually made visible
+ * by hovering the mouse cursor over a
+ * [`HovercardAnchor`](https://ariakit.com/reference/hovercard-anchor).
+ * @see https://ariakit.com/components/hovercard
+ * @example
+ * ```jsx {3}
+ * <HovercardProvider>
+ *   <HovercardAnchor>@username</HovercardAnchor>
+ *   <Hovercard>Details</Hovercard>
+ * </HovercardProvider>
+ * ```
+ */
+export const Hovercard = createDialogComponent(
+  forwardRef(function Hovercard(props: HovercardProps) {
+    const htmlProps = useHovercard(props);
+    return createElement(TagName, htmlProps);
+  }),
+  useHovercardProviderContext,
+);
+
+export interface HovercardOptions<
+  T extends ElementType = TagName,
+> extends PopoverOptions<T> {
+  /**
+   * Object returned by the
+   * [`useHovercardStore`](https://ariakit.com/reference/use-hovercard-store)
+   * hook. If not provided, the closest
+   * [`HovercardProvider`](https://ariakit.com/reference/hovercard-provider)
+   * component's context will be used.
+   */
+  store?: HovercardStore;
+  /**
+   * Determines whether the popover should hide when the mouse leaves the
+   * popover or the anchor element and there's no _hover intent_, meaning, the
+   * mouse isn't moving toward the popover.
+   *
+   * This can be either a boolean or a callback receiving the mouse move event
+   * that initiated the behavior. The callback should return a boolean.
+   *
+   * **Note**: This behavior won't be triggered when the popover or any of its
+   * descendants are in focus.
+   * @default true
+   */
+  hideOnHoverOutside?: BooleanOrCallback<MouseEvent>;
+  /**
+   * Determines if the pointer events outside of the popover and its anchor
+   * element should be disabled during _hover intent_, that is, when the mouse
+   * is moving toward the popover.
+   *
+   * This is required as these external events may trigger focus on other
+   * elements and close the popover while the user is attempting to hover over
+   * it.
+   *
+   * This can be either a boolean or a callback receiving the mouse event
+   * happening during hover intent. The callback should return a boolean.
+   * @default true
+   */
+  disablePointerEventsOnApproach?: BooleanOrCallback<MouseEvent>;
+  /**
+   * @default false
+   */
+  modal?: PopoverOptions<T>["modal"];
+}
+
+export type HovercardProps<T extends ElementType = TagName> = Props<
+  T,
+  HovercardOptions<T>
+>;

package/src/hovercard/utils/__tests__/polygon-test.ts

@@ -0,0 +1,66 @@
+import { expect, test } from "vitest";
+import type { Point, Polygon } from "../polygon.ts";
+import { isPointInPolygon } from "../polygon.ts";
+
+test("isPointInPolygon", () => {
+  const polygon: Polygon = [
+    [2, 2],
+    [2, 4],
+    [4, 4],
+    [4, 2],
+  ];
+
+  expect(isPointInPolygon([0, 0], polygon)).toBe(false);
+  expect(isPointInPolygon([1, 0], polygon)).toBe(false);
+  expect(isPointInPolygon([2, 0], polygon)).toBe(false);
+  expect(isPointInPolygon([3, 0], polygon)).toBe(false);
+  expect(isPointInPolygon([4, 0], polygon)).toBe(false);
+  expect(isPointInPolygon([5, 0], polygon)).toBe(false);
+
+  expect(isPointInPolygon([0, 1], polygon)).toBe(false);
+  expect(isPointInPolygon([1, 1], polygon)).toBe(false);
+  expect(isPointInPolygon([2, 1], polygon)).toBe(false);
+  expect(isPointInPolygon([3, 1], polygon)).toBe(false);
+  expect(isPointInPolygon([4, 1], polygon)).toBe(false);
+  expect(isPointInPolygon([5, 1], polygon)).toBe(false);
+
+  expect(isPointInPolygon([0, 2], polygon)).toBe(false);
+  expect(isPointInPolygon([1, 2], polygon)).toBe(false);
+  expect(isPointInPolygon([2, 2], polygon)).toBe(true);
+  expect(isPointInPolygon([3, 2], polygon)).toBe(true);
+  expect(isPointInPolygon([4, 2], polygon)).toBe(true);
+  expect(isPointInPolygon([5, 2], polygon)).toBe(false);
+
+  expect(isPointInPolygon([0, 3], polygon)).toBe(false);
+  expect(isPointInPolygon([1, 3], polygon)).toBe(false);
+  expect(isPointInPolygon([2, 3], polygon)).toBe(true);
+  expect(isPointInPolygon([3, 3], polygon)).toBe(true);
+  expect(isPointInPolygon([4, 3], polygon)).toBe(true);
+  expect(isPointInPolygon([5, 3], polygon)).toBe(false);
+
+  expect(isPointInPolygon([0, 4], polygon)).toBe(false);
+  expect(isPointInPolygon([1, 4], polygon)).toBe(false);
+  expect(isPointInPolygon([2, 4], polygon)).toBe(true);
+  expect(isPointInPolygon([3, 4], polygon)).toBe(true);
+  expect(isPointInPolygon([4, 4], polygon)).toBe(true);
+  expect(isPointInPolygon([5, 4], polygon)).toBe(false);
+
+  expect(isPointInPolygon([0, 5], polygon)).toBe(false);
+  expect(isPointInPolygon([1, 5], polygon)).toBe(false);
+  expect(isPointInPolygon([2, 5], polygon)).toBe(false);
+  expect(isPointInPolygon([3, 5], polygon)).toBe(false);
+  expect(isPointInPolygon([4, 5], polygon)).toBe(false);
+  expect(isPointInPolygon([5, 5], polygon)).toBe(false);
+});
+
+test("isPointInPolygon returns false for malformed polygons", () => {
+  const polygon: Array<Point | undefined> = [
+    [2, 2],
+    [2, 4],
+    [4, 4],
+    [4, 2],
+  ];
+  polygon[1] = undefined;
+
+  expect(isPointInPolygon([3, 3], polygon as Polygon)).toBe(false);
+});