@ariakit/react-components 0.1.0

package/src/hovercard/hovercard-anchor.tsx

@@ -0,0 +1,195 @@
+import {
+  useBooleanEvent,
+  useEvent,
+  useIsMouseMoving,
+  useMergeRefs,
+  createElement,
+  createHook,
+  forwardRef,
+} from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import {
+  addGlobalEventListener,
+  disabledFromProps,
+  invariant,
+} from "@ariakit/utils";
+import type { BooleanOrCallback } from "@ariakit/utils";
+import type { ElementType, MouseEvent as ReactMouseEvent } from "react";
+import { useCallback, useEffect, useRef } from "react";
+import type { FocusableOptions } from "../focusable/focusable.tsx";
+import { useFocusable } from "../focusable/focusable.tsx";
+import { useHovercardProviderContext } from "./hovercard-context.tsx";
+import type { HovercardStore } from "./hovercard-store.ts";
+
+const TagName = "a" satisfies ElementType;
+type TagName = typeof TagName;
+type HTMLType = HTMLElementTagNameMap[TagName];
+
+/**
+ * Returns props to create a `HovercardAnchor` component.
+ * @see https://ariakit.com/components/hovercard
+ * @example
+ * ```jsx
+ * const store = useHovercardStore();
+ * const props = useHovercardAnchor({ store });
+ * <Role {...props} render={<a />}>@username</Role>
+ * <Hovercard store={store}>Details</Hovercard>
+ * ```
+ */
+export const useHovercardAnchor = createHook<TagName, HovercardAnchorOptions>(
+  function useHovercardAnchor({ store, showOnHover = true, ...props }) {
+    const context = useHovercardProviderContext();
+    store = store || context;
+
+    invariant(
+      store,
+      process.env.NODE_ENV !== "production" &&
+        "HovercardAnchor must receive a `store` prop or be wrapped in a HovercardProvider component.",
+    );
+
+    const disabled = disabledFromProps(props);
+    const showTimeoutRef = useRef(0);
+
+    // Clear the show timeout if the anchor is unmounted
+    useEffect(() => () => window.clearTimeout(showTimeoutRef.current), []);
+
+    // Clear the show timeout if the mouse leaves the anchor element. We're
+    // using the native mouseleave event instead of React's onMouseLeave so we
+    // bypass the event.stopPropagation() logic set on the Hovercard component
+    // for when the mouse is moving toward the Hovercard.
+    useEffect(() => {
+      const onMouseLeave = (event: MouseEvent) => {
+        if (!store) return;
+        const { anchorElement } = store.getState();
+        if (!anchorElement) return;
+        if (event.target !== anchorElement) return;
+        window.clearTimeout(showTimeoutRef.current);
+        showTimeoutRef.current = 0;
+      };
+      return addGlobalEventListener("mouseleave", onMouseLeave, true);
+    }, [store]);
+
+    const onMouseMoveProp = props.onMouseMove;
+    const showOnHoverProp = useBooleanEvent(showOnHover);
+    const isMouseMoving = useIsMouseMoving();
+
+    const onMouseMove = useEvent((event: ReactMouseEvent<HTMLType>) => {
+      onMouseMoveProp?.(event);
+      if (disabled) return;
+      if (!store) return;
+      if (event.defaultPrevented) return;
+      if (showTimeoutRef.current) return;
+      if (!isMouseMoving()) return;
+      if (!showOnHoverProp(event)) return;
+      const element = event.currentTarget;
+      store.setAnchorElement(element);
+      store.setDisclosureElement(element);
+      const { showTimeout, timeout } = store.getState();
+      const showHovercard = () => {
+        showTimeoutRef.current = 0;
+        // Let's check again if the mouse is moving. This is to avoid showing
+        // the hovercard on mobile clicks or after clicking on the anchor.
+        if (!isMouseMoving()) return;
+        store?.setAnchorElement(element);
+        store?.show();
+        queueMicrotask(() => {
+          // We need to set the anchor element as the hovercard disclosure
+          // element only when the hovercard is shown so it doesn't get
+          // assigned an arbitrary element by the dialog component.
+          store?.setDisclosureElement(element);
+        });
+      };
+      const timeoutMs = showTimeout ?? timeout;
+      if (timeoutMs === 0) {
+        showHovercard();
+      } else {
+        showTimeoutRef.current = window.setTimeout(showHovercard, timeoutMs);
+      }
+    });
+
+    const onClickProp = props.onClick;
+
+    const onClick = useEvent((event: ReactMouseEvent<HTMLType>) => {
+      onClickProp?.(event);
+      if (!store) return;
+      // Resets showOnHover when the anchor is clicked so the consumer (for
+      // example, TooltipAnchor) has the chance to prevent the hovercard from
+      // showing on mousemove after a click.
+      window.clearTimeout(showTimeoutRef.current);
+      showTimeoutRef.current = 0;
+    });
+
+    const ref = useCallback(
+      (element: HTMLElement | null) => {
+        if (!store) return;
+        const { anchorElement } = store.getState();
+        if (anchorElement?.isConnected) return;
+        // We can set the anchor element only if it isn't already set or if it's
+        // not linked to the DOM. This helps prevent the anchor element from
+        // being reassigned to a different element when using multiple anchors
+        // and new anchors are added to the DOM.
+        store.setAnchorElement(element);
+      },
+      [store],
+    );
+
+    props = {
+      ...props,
+      ref: useMergeRefs(ref, props.ref),
+      onMouseMove,
+      onClick,
+    };
+
+    props = useFocusable<TagName>(props);
+
+    return props;
+  },
+);
+
+/**
+ * Renders an anchor element that will open a
+ * [`Hovercard`](https://ariakit.com/reference/hovercard) popup on hover.
+ * @see https://ariakit.com/components/hovercard
+ * @example
+ * ```jsx {2}
+ * <HovercardProvider>
+ *   <HovercardAnchor>@username</HovercardAnchor>
+ *   <Hovercard>Details</Hovercard>
+ * </HovercardProvider>
+ * ```
+ */
+export const HovercardAnchor = forwardRef(function HovercardAnchor(
+  props: HovercardAnchorProps,
+) {
+  const htmlProps = useHovercardAnchor(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface HovercardAnchorOptions<
+  T extends ElementType = TagName,
+> extends FocusableOptions<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;
+  /**
+   * Shows the content element based on the user's _hover intent_ over the
+   * anchor element. This behavior purposely ignores mobile touch and
+   * unintentional mouse enter events, like those that happen during scrolling.
+   *
+   * Live examples:
+   * - [Navigation Menubar](https://ariakit.com/examples/menubar-navigation)
+   * - [Sliding Menu](https://ariakit.com/examples/menu-slide)
+   * @default true
+   */
+  showOnHover?: BooleanOrCallback<ReactMouseEvent<HTMLElement>>;
+}
+
+export type HovercardAnchorProps<T extends ElementType = TagName> = Props<
+  T,
+  HovercardAnchorOptions<T>
+>;

package/src/hovercard/hovercard-arrow.tsx

@@ -0,0 +1,74 @@
+import { createElement, createHook, forwardRef } from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import type { ElementType } from "react";
+import type { PopoverArrowOptions } from "../popover/popover-arrow.tsx";
+import { usePopoverArrow } from "../popover/popover-arrow.tsx";
+import { useHovercardContext } from "./hovercard-context.tsx";
+import type { HovercardStore } from "./hovercard-store.ts";
+
+const TagName = "div" satisfies ElementType;
+type TagName = typeof TagName;
+
+/**
+ * Returns props to create a `HovercardArrow` component.
+ * @see https://ariakit.com/components/hovercard
+ * @example
+ * ```jsx
+ * const store = useHovercardStore();
+ * const props = useHovercardArrow({ store });
+ * <Hovercard store={store}>
+ *   <Role {...props} />
+ *   Details
+ * </Hovercard>
+ * ```
+ */
+export const useHovercardArrow = createHook<TagName, HovercardArrowOptions>(
+  function useHovercardArrow({ store, ...props }) {
+    const context = useHovercardContext();
+    store = store || context;
+    props = usePopoverArrow({ store, ...props });
+    return props;
+  },
+);
+
+/**
+ * Renders an arrow element inside a
+ * [`Hovercard`](https://ariakit.com/reference/hovercard) component that points
+ * to the anchor element.
+ * @see https://ariakit.com/components/hovercard
+ * @example
+ * ```jsx {4}
+ * <HovercardProvider>
+ *   <HovercardAnchor>@username</HovercardAnchor>
+ *   <Hovercard>
+ *     <HovercardArrow />
+ *     Details
+ *   </Hovercard>
+ * </HovercardProvider>
+ * ```
+ */
+export const HovercardArrow = forwardRef(function HovercardArrow(
+  props: HovercardArrowProps,
+) {
+  const htmlProps = useHovercardArrow(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface HovercardArrowOptions<
+  T extends ElementType = TagName,
+> extends PopoverArrowOptions<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 HovercardArrowProps<T extends ElementType = TagName> = Props<
+  T,
+  HovercardArrowOptions<T>
+>;

package/src/hovercard/hovercard-context.tsx

@@ -0,0 +1,34 @@
+import { createStoreContext } from "@ariakit/react-utils";
+import {
+  PopoverContextProvider,
+  PopoverScopedContextProvider,
+} from "../popover/popover-context.tsx";
+import type { HovercardStore } from "./hovercard-store.ts";
+
+const ctx = createStoreContext<HovercardStore>(
+  [PopoverContextProvider],
+  [PopoverScopedContextProvider],
+);
+
+/**
+ * Returns the hovercard store from the nearest hovercard container.
+ * @example
+ * function Hovercard() {
+ *   const store = useHovercardContext();
+ *
+ *   if (!store) {
+ *     throw new Error("Hovercard must be wrapped in HovercardProvider");
+ *   }
+ *
+ *   // Use the store...
+ * }
+ */
+export const useHovercardContext = ctx.useContext;
+
+export const useHovercardScopedContext = ctx.useScopedContext;
+
+export const useHovercardProviderContext = ctx.useProviderContext;
+
+export const HovercardContextProvider = ctx.ContextProvider;
+
+export const HovercardScopedContextProvider = ctx.ScopedContextProvider;

package/src/hovercard/hovercard-description.tsx

@@ -0,0 +1,69 @@
+import { createElement, createHook, forwardRef } from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import type { ElementType } from "react";
+import type { PopoverDescriptionOptions } from "../popover/popover-description.tsx";
+import { usePopoverDescription } from "../popover/popover-description.tsx";
+import type { HovercardStore } from "./hovercard-store.ts";
+
+const TagName = "p" satisfies ElementType;
+type TagName = typeof TagName;
+
+/**
+ * Returns props to create a `HovercardDescription` component. This hook must be
+ * used in a component that's wrapped with `Hovercard` so the `aria-describedby`
+ * 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 = useHovercardDescription();
+ * <Role {...props}>Description</Role>
+ * ```
+ */
+export const useHovercardDescription = createHook<
+  TagName,
+  HovercardDescriptionOptions
+>(function useHovercardDescription(props) {
+  props = usePopoverDescription(props);
+  return props;
+});
+
+/**
+ * Renders a description in a hovercard. This component must be wrapped within
+ * [`Hovercard`](https://ariakit.com/reference/hovercard) so the
+ * `aria-describedby` prop is properly set on the content element.
+ * @see https://ariakit.com/components/hovercard
+ * @example
+ * ```jsx {3}
+ * <HovercardProvider>
+ *   <Hovercard>
+ *     <HovercardDescription>Description</HovercardDescription>
+ *   </Hovercard>
+ * </HovercardProvider>
+ * ```
+ */
+export const HovercardDescription = forwardRef(function HovercardDescription(
+  props: HovercardDescriptionProps,
+) {
+  const htmlProps = useHovercardDescription(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface HovercardDescriptionOptions<
+  T extends ElementType = TagName,
+> extends PopoverDescriptionOptions<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 HovercardDescriptionProps<T extends ElementType = TagName> = Props<
+  T,
+  HovercardDescriptionOptions<T>
+>;

package/src/hovercard/hovercard-disclosure.tsx

@@ -0,0 +1,196 @@
+import {
+  useEvent,
+  useMergeRefs,
+  createElement,
+  createHook,
+  forwardRef,
+} from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import { sync } from "@ariakit/store";
+import { contains, addGlobalEventListener, invariant } from "@ariakit/utils";
+import type {
+  ElementType,
+  MouseEvent,
+  FocusEvent as ReactFocusEvent,
+} from "react";
+import { useEffect, useState } from "react";
+import type { DialogDisclosureOptions } from "../dialog/dialog-disclosure.tsx";
+import { useDialogDisclosure } from "../dialog/dialog-disclosure.tsx";
+import { useVisuallyHidden } from "../visually-hidden/visually-hidden.tsx";
+import { useHovercardProviderContext } from "./hovercard-context.tsx";
+import type { HovercardStore } from "./hovercard-store.ts";
+
+const TagName = "button" satisfies ElementType;
+type TagName = typeof TagName;
+type HTMLType = HTMLElementTagNameMap[TagName];
+
+/**
+ * Returns props to create a `HovercardDisclosure` component.
+ * @see https://ariakit.com/components/hovercard
+ * @example
+ * ```jsx
+ * const store = useHovercardStore();
+ * const props = useHovercardDisclosure({ store });
+ * <HovercardAnchor store={store}>@username</HovercardAnchor>
+ * <Role {...props} />
+ * <Hovercard store={store}>Details</Hovercard>
+ * ```
+ */
+export const useHovercardDisclosure = createHook<
+  TagName,
+  HovercardDisclosureOptions
+>(function useHovercardDisclosure({ store, ...props }) {
+  const context = useHovercardProviderContext();
+  store = store || context;
+
+  invariant(
+    store,
+    process.env.NODE_ENV !== "production" &&
+      "HovercardDisclosure must receive a `store` prop or be wrapped in a HovercardProvider component.",
+  );
+
+  const [visible, setVisible] = useState(false);
+
+  // Listens to blur events on the whole document and hides the hovercard
+  // disclosure if either the hovercard, the anchor or the disclosure button
+  // itself loses focus.
+  useEffect(() => {
+    if (!visible) return;
+    const onBlur = (event: FocusEvent) => {
+      if (!store) return;
+      const nextActiveElement = event.relatedTarget as Element | null;
+      if (nextActiveElement) {
+        const {
+          anchorElement: anchor,
+          popoverElement: popover,
+          disclosureElement: disclosure,
+        } = store.getState();
+        if (anchor && contains(anchor, nextActiveElement)) return;
+        if (popover && contains(popover, nextActiveElement)) return;
+        if (disclosure && contains(disclosure, nextActiveElement)) return;
+        // When the portal prop is set to true on the Hovercard component,
+        // it's going to render focus trap elements outside of the portal.
+        // These elements may transfer focus to the disclosure button, so we
+        // also ignore them here.
+        if (nextActiveElement.hasAttribute("data-focus-trap")) return;
+      }
+      setVisible(false);
+    };
+    return addGlobalEventListener("focusout", onBlur, true);
+  }, [visible, store]);
+
+  // Shows the hovercard disclosure when the anchor receives keyboard focus.
+  useEffect(() => {
+    return sync(store, ["anchorElement"], (state) => {
+      const anchor = state.anchorElement;
+      if (!anchor) return;
+      const observer = new MutationObserver(() => {
+        if (!anchor.hasAttribute("data-focus-visible")) return;
+        setVisible(true);
+      });
+      observer.observe(anchor, { attributeFilter: ["data-focus-visible"] });
+      return () => observer.disconnect();
+    });
+  }, [store]);
+
+  const onClickProp = props.onClick;
+
+  // By default, hovercards don't receive focus when they are shown. When the
+  // disclosure element is clicked, though, we want it to behave like a
+  // popover, so we set the autoFocusOnShow prop to true.
+  const onClick = useEvent((event: MouseEvent<HTMLType>) => {
+    onClickProp?.(event);
+    if (event.defaultPrevented) return;
+    store?.setAutoFocusOnShow(true);
+  });
+
+  const onFocusProp = props.onFocus;
+
+  // Since the disclosure button is only visually hidden, it may receive focus
+  // when the user tabs to it. So we make sure it's visible when that happens.
+  const onFocus = useEvent((event: ReactFocusEvent<HTMLType>) => {
+    onFocusProp?.(event);
+    if (event.defaultPrevented) return;
+    setVisible(true);
+  });
+
+  const { style } = useVisuallyHidden();
+
+  if (!visible) {
+    props = {
+      ...props,
+      style: {
+        ...style,
+        ...props.style,
+      },
+    };
+  }
+
+  const children = (
+    <svg
+      display="block"
+      fill="none"
+      stroke="currentColor"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      strokeWidth={1.5}
+      viewBox="0 0 16 16"
+      height="1em"
+      width="1em"
+    >
+      <polyline points="4,6 8,10 12,6" />
+    </svg>
+  );
+
+  props = {
+    children,
+    ...props,
+    ref: useMergeRefs(store.setDisclosureElement, props.ref),
+    onClick,
+    onFocus,
+  };
+
+  props = useDialogDisclosure({ store, ...props });
+
+  return props;
+});
+
+/**
+ * Renders a hidden disclosure button that will be visible when the
+ * [`HovercardAnchor`](https://ariakit.com/reference/hovercard-anchor) receives
+ * keyboard focus. The user can then navigate to the button to open the
+ * hovercard when using the keyboard.
+ * @see https://ariakit.com/components/hovercard
+ * @example
+ * ```jsx {3}
+ * <HovercardProvider>
+ *   <HovercardAnchor>@username</HovercardAnchor>
+ *   <HovercardDisclosure />
+ *   <Hovercard>Details</Hovercard>
+ * </HovercardProvider>
+ * ```
+ */
+export const HovercardDisclosure = forwardRef(function HovercardDisclosure(
+  props: HovercardDisclosureProps,
+) {
+  const htmlProps = useHovercardDisclosure(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface HovercardDisclosureOptions<
+  T extends ElementType = TagName,
+> extends DialogDisclosureOptions<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;
+}
+
+export type HovercardDisclosureProps<T extends ElementType = TagName> = Props<
+  T,
+  HovercardDisclosureOptions<T>
+>;

package/src/hovercard/hovercard-dismiss.tsx

@@ -0,0 +1,70 @@
+import { createElement, createHook, forwardRef } from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import type { ElementType } from "react";
+import type { PopoverDismissOptions } from "../popover/popover-dismiss.tsx";
+import { usePopoverDismiss } from "../popover/popover-dismiss.tsx";
+import { useHovercardScopedContext } from "./hovercard-context.tsx";
+import type { HovercardStore } from "./hovercard-store.ts";
+
+const TagName = "button" satisfies ElementType;
+type TagName = typeof TagName;
+
+/**
+ * Returns props to create a `HovercardDismiss` component.
+ * @see https://ariakit.com/components/hovercard
+ * @example
+ * ```jsx
+ * const store = useHovercardStore();
+ * const props = useHovercardDismiss({ store });
+ * <Hovercard store={store}>
+ *   <Role {...props} />
+ * </Hovercard>
+ * ```
+ */
+export const useHovercardDismiss = createHook<TagName, HovercardDismissOptions>(
+  function useHovercardDismiss({ store, ...props }) {
+    const context = useHovercardScopedContext();
+    store = store || context;
+    props = usePopoverDismiss({ store, ...props });
+    return props;
+  },
+);
+
+/**
+ * Renders a button that hides a
+ * [`Hovercard`](https://ariakit.com/reference/hovercard) when clicked.
+ * @see https://ariakit.com/components/hovercard
+ * @example
+ * ```jsx {3}
+ * <HovercardProvider>
+ *   <Hovercard>
+ *     <HovercardDismiss />
+ *   </Hovercard>
+ * </HovercardProvider>
+ * ```
+ */
+export const HovercardDismiss = forwardRef(function HovercardDismiss(
+  props: HovercardDismissProps,
+) {
+  const htmlProps = useHovercardDismiss(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface HovercardDismissOptions<
+  T extends ElementType = TagName,
+> extends PopoverDismissOptions<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 HovercardDismissProps<T extends ElementType = TagName> = Props<
+  T,
+  HovercardDismissOptions<T>
+>;