@ariakit/react-components 0.1.0

package/src/tooltip/tooltip-arrow.tsx

@@ -0,0 +1,84 @@
+import { createElement, createHook, forwardRef } from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import { invariant } from "@ariakit/utils";
+import type { ElementType } from "react";
+import type { PopoverArrowOptions } from "../popover/popover-arrow.tsx";
+import { usePopoverArrow } from "../popover/popover-arrow.tsx";
+import { useTooltipContext } from "./tooltip-context.tsx";
+import type { TooltipStore } from "./tooltip-store.ts";
+
+const TagName = "div" satisfies ElementType;
+type TagName = typeof TagName;
+
+/**
+ * Returns props to create a `TooltipArrow` component.
+ * @see https://ariakit.com/components/tooltip
+ * @example
+ * ```jsx
+ * const store = useToolTipStore();
+ * const props = useTooltipArrow({ store });
+ * <TooltipAnchor store={store}>Anchor</TooltipAnchor>
+ * <Tooltip store={store}>
+ *   <Role {...props} />
+ *   Tooltip
+ * </Tooltip>
+ * ```
+ */
+export const useTooltipArrow = createHook<TagName, TooltipArrowOptions>(
+  function useTooltipArrow({ store, size = 16, ...props }) {
+    // We need to get the tooltip store here because Tooltip is not using the
+    // Popover component, so PopoverArrow can't access the popover context.
+    const context = useTooltipContext();
+    store = store || context;
+
+    invariant(
+      store,
+      process.env.NODE_ENV !== "production" &&
+        "TooltipArrow must be wrapped in a Tooltip component.",
+    );
+
+    props = usePopoverArrow({ store, size, ...props });
+    return props;
+  },
+);
+
+/**
+ * Renders an arrow inside a [`Tooltip`](https://ariakit.com/reference/tooltip)
+ * pointing to the anchor element.
+ * @see https://ariakit.com/components/tooltip
+ * @example
+ * ```jsx {4}
+ * <TooltipProvider>
+ *   <TooltipAnchor>Anchor</TooltipAnchor>
+ *   <Tooltip>
+ *     <TooltipArrow />
+ *     Tooltip
+ *   </Tooltip>
+ * </TooltipProvider>
+ * ```
+ */
+export const TooltipArrow = forwardRef(function TooltipArrow(
+  props: TooltipArrowProps,
+) {
+  const htmlProps = useTooltipArrow(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface TooltipArrowOptions<
+  T extends ElementType = TagName,
+> extends PopoverArrowOptions<T> {
+  /**
+   * Object returned by the
+   * [`useTooltipStore`](https://ariakit.com/reference/use-tooltip-store) hook.
+   * If not provided, the closest
+   * [`Tooltip`](https://ariakit.com/reference/tooltip) or
+   * [`TooltipProvider`](https://ariakit.com/reference/tooltip-provider)
+   * components' context will be used.
+   */
+  store?: TooltipStore;
+}
+
+export type TooltipArrowProps<T extends ElementType = TagName> = Props<
+  T,
+  TooltipArrowOptions<T>
+>;

package/src/tooltip/tooltip-context.tsx

@@ -0,0 +1,34 @@
+import { createStoreContext } from "@ariakit/react-utils";
+import {
+  HovercardContextProvider,
+  HovercardScopedContextProvider,
+} from "../hovercard/hovercard-context.tsx";
+import type { TooltipStore } from "./tooltip-store.ts";
+
+const ctx = createStoreContext<TooltipStore>(
+  [HovercardContextProvider],
+  [HovercardScopedContextProvider],
+);
+
+/**
+ * Returns the tooltip store from the nearest tooltip container.
+ * @example
+ * function Tooltip() {
+ *   const store = useTooltipContext();
+ *
+ *   if (!store) {
+ *     throw new Error("Tooltip must be wrapped in TooltipProvider");
+ *   }
+ *
+ *   // Use the store...
+ * }
+ */
+export const useTooltipContext = ctx.useContext;
+
+export const useTooltipScopedContext = ctx.useScopedContext;
+
+export const useTooltipProviderContext = ctx.useProviderContext;
+
+export const TooltipContextProvider = ctx.ContextProvider;
+
+export const TooltipScopedContextProvider = ctx.ScopedContextProvider;

package/src/tooltip/tooltip-provider.tsx

@@ -0,0 +1,29 @@
+import type { ReactNode } from "react";
+import { TooltipContextProvider } from "./tooltip-context.tsx";
+import type { TooltipStoreProps } from "./tooltip-store.ts";
+import { useTooltipStore } from "./tooltip-store.ts";
+
+/**
+ * Provides a tooltip store to [Tooltip](https://ariakit.com/components/tooltip)
+ * components.
+ * @see https://ariakit.com/components/tooltip
+ * @example
+ * ```jsx
+ * <TooltipProvider timeout={250}>
+ *   <TooltipAnchor />
+ *   <Tooltip />
+ * </TooltipProvider>
+ * ```
+ */
+export function TooltipProvider(props: TooltipProviderProps = {}) {
+  const store = useTooltipStore(props);
+  return (
+    <TooltipContextProvider value={store}>
+      {props.children}
+    </TooltipContextProvider>
+  );
+}
+
+export interface TooltipProviderProps extends TooltipStoreProps {
+  children?: ReactNode;
+}

package/src/tooltip/tooltip-store.ts

@@ -0,0 +1,53 @@
+import * as Core from "@ariakit/components/tooltip/tooltip-store";
+import { useStore, useStoreProps } from "@ariakit/react-store";
+import type { Store } from "@ariakit/react-store";
+import type {
+  HovercardStoreFunctions,
+  HovercardStoreOptions,
+  HovercardStoreState,
+} from "../hovercard/hovercard-store.ts";
+import { useHovercardStoreProps } from "../hovercard/hovercard-store.ts";
+
+export function useTooltipStoreProps<T extends Core.TooltipStore>(
+  store: T,
+  update: () => void,
+  props: TooltipStoreProps,
+) {
+  useStoreProps(store, props, "type");
+  useStoreProps(store, props, "skipTimeout");
+  return useHovercardStoreProps(store, update, props);
+}
+
+/**
+ * Creates a tooltip store to control the state of
+ * [Tooltip](https://ariakit.com/components/tooltip) components.
+ * @see https://ariakit.com/components/tooltip
+ * @example
+ * ```jsx
+ * const tooltip = useTooltipStore();
+ *
+ * <TooltipAnchor store={tooltip}>Anchor</TooltipAnchor>
+ * <Tooltip store={tooltip}>Tooltip</Tooltip>
+ * ```
+ */
+export function useTooltipStore(props: TooltipStoreProps = {}): TooltipStore {
+  const [store, update] = useStore(Core.createTooltipStore, props);
+  return useTooltipStoreProps(store, update, props);
+}
+
+export interface TooltipStoreState
+  extends Core.TooltipStoreState, HovercardStoreState {}
+
+export interface TooltipStoreFunctions
+  extends
+    Omit<Core.TooltipStoreFunctions, "disclosure">,
+    HovercardStoreFunctions {}
+
+export interface TooltipStoreOptions
+  extends Omit<Core.TooltipStoreOptions, "disclosure">, HovercardStoreOptions {}
+
+export interface TooltipStoreProps
+  extends TooltipStoreOptions, Omit<Core.TooltipStoreProps, "disclosure"> {}
+
+export interface TooltipStore
+  extends TooltipStoreFunctions, Omit<Store<Core.TooltipStore>, "disclosure"> {}

package/src/tooltip/tooltip.tsx

@@ -0,0 +1,153 @@
+import { useStoreState } from "@ariakit/react-store";
+import {
+  useWrapElement,
+  createElement,
+  createHook,
+  forwardRef,
+} from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import { contains, invariant, isFalsyBooleanCallback } from "@ariakit/utils";
+import type { ElementType } from "react";
+import { createDialogComponent } from "../dialog/dialog.tsx";
+import type { HovercardOptions } from "../hovercard/hovercard.tsx";
+import { useHovercard } from "../hovercard/hovercard.tsx";
+import {
+  TooltipScopedContextProvider,
+  useTooltipProviderContext,
+} from "./tooltip-context.tsx";
+import type { TooltipStore } from "./tooltip-store.ts";
+
+const TagName = "div" satisfies ElementType;
+type TagName = typeof TagName;
+
+/**
+ * Returns props to create a `Tooltip` component.
+ * @see https://ariakit.com/components/tooltip
+ * @example
+ * ```jsx
+ * const store = useToolTipStore();
+ * const props = useTooltip({ store });
+ * <TooltipAnchor store={store}>Anchor</TooltipAnchor>
+ * <Role {...props}>Tooltip</Role>
+ * ```
+ */
+export const useTooltip = createHook<TagName, TooltipOptions>(
+  function useTooltip({
+    store,
+    portal = true,
+    gutter = 8,
+    preserveTabOrder = false,
+    hideOnHoverOutside = true,
+    hideOnInteractOutside = true,
+    ...props
+  }) {
+    const context = useTooltipProviderContext();
+    store = store || context;
+
+    invariant(
+      store,
+      process.env.NODE_ENV !== "production" &&
+        "Tooltip must receive a `store` prop or be wrapped in a TooltipProvider component.",
+    );
+
+    props = useWrapElement(
+      props,
+      (element) => (
+        <TooltipScopedContextProvider value={store}>
+          {element}
+        </TooltipScopedContextProvider>
+      ),
+      [store],
+    );
+
+    const role = useStoreState(store, (state) =>
+      state.type === "description" ? "tooltip" : "none",
+    );
+
+    props = { role, ...props };
+
+    props = useHovercard({
+      ...props,
+      store,
+      portal,
+      gutter,
+      preserveTabOrder,
+      hideOnHoverOutside(event) {
+        if (isFalsyBooleanCallback(hideOnHoverOutside, event)) return false;
+        const anchorElement = store?.getState().anchorElement;
+        if (!anchorElement) return true;
+        // If the anchor element has the `data-focus-visible` attribute (added
+        // by the `Focusable` component that is used by several components), we
+        // don't hide the tooltip when the mouse leaves the anchor element. In
+        // this case, the tooltip will be hidden only if the user presses the
+        // Escape key or if the anchor element loses focus.
+        if ("focusVisible" in anchorElement.dataset) return false;
+        return true;
+      },
+      hideOnInteractOutside: (event) => {
+        if (isFalsyBooleanCallback(hideOnInteractOutside, event)) return false;
+        const anchorElement = store?.getState().anchorElement;
+        if (!anchorElement) return true;
+        // Prevent hiding the tooltip when the user interacts with the anchor
+        // element. It's up to the developer to hide the tooltip when the user
+        // clicks on the anchor element if that's the intended behavior.
+        if (contains(anchorElement, event.target as Node)) return false;
+        return true;
+      },
+    });
+
+    return props;
+  },
+);
+
+/**
+ * Renders a tooltip element that visually describes a
+ * [`TooltipAnchor`](https://ariakit.com/reference/tooltip-anchor) when it
+ * receives focus or is hovered.
+ *
+ * The tooltip is strictly for visual purposes. It's your responsibility to
+ * ensure the anchor element has an accessible name. See [Tooltip anchors must
+ * have accessible
+ * names](https://ariakit.com/components/tooltip#tooltip-anchors-must-have-accessible-names)
+ * @see https://ariakit.com/components/tooltip
+ * @example
+ * ```jsx {3}
+ * <TooltipProvider>
+ *   <TooltipAnchor>Anchor</TooltipAnchor>
+ *   <Tooltip>Tooltip</Tooltip>
+ * </TooltipProvider>
+ * ```
+ */
+export const Tooltip = createDialogComponent(
+  forwardRef(function Tooltip(props: TooltipProps) {
+    const htmlProps = useTooltip(props);
+    return createElement(TagName, htmlProps);
+  }),
+  useTooltipProviderContext,
+);
+
+export interface TooltipOptions<
+  T extends ElementType = TagName,
+> extends HovercardOptions<T> {
+  /**
+   * Object returned by the
+   * [`useTooltipStore`](https://ariakit.com/reference/use-tooltip-store) hook.
+   * If not provided, the closest
+   * [`TooltipProvider`](https://ariakit.com/reference/tooltip-provider)
+   * component's context will be used.
+   */
+  store?: TooltipStore;
+  /**
+   * @default true
+   */
+  portal?: HovercardOptions<T>["portal"];
+  /**
+   * @default 8
+   */
+  gutter?: HovercardOptions<T>["gutter"];
+}
+
+export type TooltipProps<T extends ElementType = TagName> = Props<
+  T,
+  TooltipOptions<T>
+>;

package/src/visually-hidden/visually-hidden.tsx

@@ -0,0 +1,67 @@
+import { createElement, createHook, forwardRef } from "@ariakit/react-utils";
+import type { Options, Props } from "@ariakit/react-utils";
+import type { ElementType } from "react";
+
+const TagName = "span" satisfies ElementType;
+type TagName = typeof TagName;
+
+/**
+ * Returns props to create a `VisuallyHidden` component. When applying the props
+ * returned by this hook to a component, the component will be visually hidden,
+ * but still accessible to screen readers.
+ * @see https://ariakit.com/components/visually-hidden
+ * @example
+ * ```jsx
+ * const props = useVisuallyHidden();
+ * <a href="#">
+ *   Learn more<Role {...props}> about the Solar System</Role>.
+ * </a>
+ * ```
+ */
+export const useVisuallyHidden = createHook<TagName, VisuallyHiddenOptions>(
+  function useVisuallyHidden(props) {
+    props = {
+      ...props,
+      style: {
+        border: 0,
+        clip: "rect(0 0 0 0)",
+        height: "1px",
+        margin: "-1px",
+        overflow: "hidden",
+        padding: 0,
+        position: "absolute",
+        whiteSpace: "nowrap",
+        width: "1px",
+        ...props.style,
+      },
+    };
+    return props;
+  },
+);
+
+/**
+ * Renders an element that's visually hidden, but still accessible to screen
+ * readers.
+ * @see https://ariakit.com/components/visually-hidden
+ * @example
+ * ```jsx
+ * <a href="#">
+ *   Learn more<VisuallyHidden> about the Solar System</VisuallyHidden>.
+ * </a>
+ * ```
+ */
+export const VisuallyHidden = forwardRef(function VisuallyHidden(
+  props: VisuallyHiddenProps,
+) {
+  const htmlProps = useVisuallyHidden(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface VisuallyHiddenOptions<
+  _T extends ElementType = TagName,
+> extends Options {}
+
+export type VisuallyHiddenProps<T extends ElementType = TagName> = Props<
+  T,
+  VisuallyHiddenOptions<T>
+>;