@ariakit/react-components 0.1.0

package/src/dialog/utils/use-previous-mouse-down-ref.ts

@@ -0,0 +1,19 @@
+import { addGlobalEventListener } from "@ariakit/utils";
+import { useEffect, useRef } from "react";
+
+export function usePreviousMouseDownRef(enabled?: boolean, scope?: Window) {
+  const previousMouseDownRef = useRef<EventTarget | null>(null);
+
+  useEffect(() => {
+    if (!enabled) {
+      previousMouseDownRef.current = null;
+      return;
+    }
+    const onMouseDown = (event: MouseEvent) => {
+      previousMouseDownRef.current = event.target;
+    };
+    return addGlobalEventListener("mousedown", onMouseDown, true, scope);
+  }, [enabled, scope]);
+
+  return previousMouseDownRef;
+}

package/src/dialog/utils/use-root-dialog.ts

@@ -0,0 +1,49 @@
+import { useForceUpdate } from "@ariakit/react-utils";
+import { getDocument } from "@ariakit/utils";
+import { useCallback, useEffect } from "react";
+import { flushSync } from "react-dom";
+
+interface Props {
+  attribute: string;
+  contentId?: string;
+  contentElement?: HTMLElement | null;
+  enabled?: boolean;
+}
+
+export function useRootDialog({
+  attribute,
+  contentId,
+  contentElement,
+  enabled,
+}: Props) {
+  const [updated, retry] = useForceUpdate();
+
+  const isRootDialog = useCallback(() => {
+    if (!enabled) return false;
+    if (!contentElement) return false;
+    const { body } = getDocument(contentElement);
+    const id = body.getAttribute(attribute);
+    return !id || id === contentId;
+    // oxlint-disable-next-line exhaustive-deps
+  }, [updated, enabled, contentElement, attribute, contentId]);
+
+  useEffect(() => {
+    if (!enabled) return;
+    if (!contentId) return;
+    if (!contentElement) return;
+    const { body } = getDocument(contentElement);
+    if (isRootDialog()) {
+      body.setAttribute(attribute, contentId);
+      return () => body.removeAttribute(attribute);
+    }
+    // If the dialog is not the root, there may be another dialog that will be
+    // closed soon, which will remove the root attribute from the body. We
+    // observe this change and retry to see if this dialog is now the root.
+    const observer = new MutationObserver(() => flushSync(retry));
+    observer.observe(body, { attributeFilter: [attribute] });
+    return () => observer.disconnect();
+    // oxlint-disable-next-line exhaustive-deps
+  }, [updated, enabled, contentId, contentElement, isRootDialog, attribute]);
+
+  return isRootDialog;
+}

package/src/dialog/utils/walk-tree-outside.ts

@@ -0,0 +1,85 @@
+import { contains, getDocument, chain } from "@ariakit/utils";
+import { setProperty } from "./orchestrate.ts";
+
+type Elements = Array<Element | null>;
+
+// We don't need to walk through certain tags.
+const ignoreTags = ["SCRIPT", "STYLE"];
+
+function getSnapshotPropertyName(id: string) {
+  return `__ariakit-dialog-snapshot-${id}` as keyof Element;
+}
+
+function inSnapshot(id: string, element: Element) {
+  const doc = getDocument(element);
+  const propertyName = getSnapshotPropertyName(id);
+  if (!doc.body[propertyName]) return true;
+  do {
+    if (element === doc.body) return false;
+    if (element[propertyName]) return true;
+    if (!element.parentElement) return false;
+    element = element.parentElement;
+    // oxlint-disable-next-line no-constant-condition
+  } while (true);
+}
+
+export function isValidElement(
+  id: string,
+  element: Element,
+  ignoredElements: Elements,
+) {
+  if (ignoreTags.includes(element.tagName)) return false;
+  if (!inSnapshot(id, element)) return false;
+  return !ignoredElements.some(
+    (enabledElement) => enabledElement && contains(element, enabledElement),
+  );
+}
+
+export function walkTreeOutside(
+  id: string,
+  elements: Elements,
+  callback: (element: Element, originalElement: Element) => void,
+  ancestorCallback?: (element: Element, originalElement: Element) => void,
+) {
+  for (let element of elements) {
+    if (!element?.isConnected) continue;
+    // If the element has already an ancestor element in the list, we skip it.
+    const hasAncestorAlready = elements.some((maybeAncestor) => {
+      if (!maybeAncestor) return false;
+      if (maybeAncestor === element) return false;
+      return maybeAncestor.contains(element);
+    });
+    const doc = getDocument(element);
+    const originalElement = element;
+    // Loops through the parent elements and then through each of their
+    // children.
+    while (element.parentElement && element !== doc.body) {
+      ancestorCallback?.(element.parentElement, originalElement);
+      if (!hasAncestorAlready) {
+        for (const child of element.parentElement.children) {
+          if (isValidElement(id, child, elements)) {
+            callback(child, originalElement);
+          }
+        }
+      }
+      element = element.parentElement;
+    }
+  }
+}
+
+export function createWalkTreeSnapshot(id: string, elements: Elements) {
+  const { body } = getDocument(elements[0]);
+  const cleanups: Array<() => void> = [];
+
+  const markElement = (element: Element) => {
+    cleanups.push(setProperty(element, getSnapshotPropertyName(id), true));
+  };
+
+  walkTreeOutside(id, elements, markElement);
+
+  return chain(setProperty(body, getSnapshotPropertyName(id), true), () => {
+    for (const cleanup of cleanups) {
+      cleanup();
+    }
+  });
+}

package/src/disclosure/disclosure-content.tsx

@@ -0,0 +1,344 @@
+import { useStoreState } from "@ariakit/react-store";
+import {
+  useId,
+  useMergeRefs,
+  useSafeLayoutEffect,
+  useWrapElement,
+  createElement,
+  createHook,
+  forwardRef,
+} from "@ariakit/react-utils";
+import type { Options, Props } from "@ariakit/react-utils";
+import { invariant, removeUndefinedValues } from "@ariakit/utils";
+import type { ElementType } from "react";
+import { useMemo, useRef, useState } from "react";
+import { flushSync } from "react-dom";
+import { DialogScopedContextProvider } from "../dialog/dialog-context.tsx";
+import { useDisclosureProviderContext } from "./disclosure-context.tsx";
+import type { DisclosureStore } from "./disclosure-store.ts";
+
+const TagName = "div" satisfies ElementType;
+type TagName = typeof TagName;
+type HTMLType = HTMLElementTagNameMap[TagName];
+type TransitionState = "enter" | "leave" | null;
+
+function afterTimeout(timeoutMs: number, cb: () => void) {
+  const timeoutId = setTimeout(cb, timeoutMs);
+  return () => clearTimeout(timeoutId);
+}
+
+function afterPaint(cb: () => void) {
+  let raf = requestAnimationFrame(() => {
+    raf = requestAnimationFrame(cb);
+  });
+  return () => cancelAnimationFrame(raf);
+}
+
+function parseCSSTime(...times: string[]) {
+  return times
+    .join(", ")
+    .split(", ")
+    .reduce((longestTime, currentTimeString) => {
+      const multiplier = currentTimeString.endsWith("ms") ? 1 : 1000;
+      const currentTime =
+        Number.parseFloat(currentTimeString || "0s") * multiplier;
+      // When multiple times are specified, we want to use the longest one so we
+      // wait until the longest transition has finished.
+      if (currentTime > longestTime) return currentTime;
+      return longestTime;
+    }, 0);
+}
+
+export function isHidden(
+  mounted: boolean,
+  hidden?: boolean | null,
+  alwaysVisible?: boolean | null,
+) {
+  return !alwaysVisible && hidden !== false && (!mounted || !!hidden);
+}
+
+/**
+ * Returns props to create a `DislosureContent` component.
+ * @see https://ariakit.com/components/disclosure
+ * @example
+ * ```jsx
+ * const store = useDisclosureStore();
+ * const props = useDisclosureContent({ store });
+ * <Disclosure store={store}>Disclosure</Disclosure>
+ * <Role {...props}>Content</Role>
+ * ```
+ */
+export const useDisclosureContent = createHook<
+  TagName,
+  DisclosureContentOptions
+>(function useDisclosureContent({ store, alwaysVisible, ...props }) {
+  const context = useDisclosureProviderContext();
+  store = store || context;
+
+  invariant(
+    store,
+    process.env.NODE_ENV !== "production" &&
+      "DisclosureContent must receive a `store` prop or be wrapped in a DisclosureProvider component.",
+  );
+
+  const ref = useRef<HTMLType>(null);
+  const id = useId(props.id);
+  const [transition, setTransition] = useState<TransitionState>(null);
+  const open = useStoreState(store, "open");
+  const mounted = useStoreState(store, "mounted");
+  const animated = useStoreState(store, "animated");
+  const contentElement = useStoreState(store, "contentElement");
+  const otherElement = useStoreState(store.disclosure, "contentElement");
+  const hasClosedRef = useRef(false);
+
+  // This is a workaround to avoid the content element from being reset to null
+  // on fast refresh.
+  useSafeLayoutEffect(() => {
+    if (!ref.current) return;
+    store?.setContentElement(ref.current);
+  }, [store]);
+
+  // When the disclosure content element is rendered, we automatically set the
+  // animated state to true. If there's no enter animation, the animated state
+  // will be set to false later on.
+  useSafeLayoutEffect(() => {
+    let previousAnimated: boolean | number | undefined;
+    store?.setState("animated", (animated) => {
+      previousAnimated = animated;
+      return true;
+    });
+    return () => {
+      if (previousAnimated === undefined) return;
+      store?.setState("animated", previousAnimated);
+    };
+  }, [store]);
+
+  useSafeLayoutEffect(() => {
+    if (!animated) {
+      // When animation detection has disabled animations (e.g., no CSS
+      // transition was detected on the content element), manage data-enter
+      // so wrapper elements using :has([data-enter]) work correctly even
+      // when the content element itself has no transitions.
+      if (!open) {
+        hasClosedRef.current = true;
+        setTransition(null);
+      } else if (hasClosedRef.current) {
+        // On reopen after animation detection disabled animations, restore
+        // data-enter so enter styles are re-applied.
+        hasClosedRef.current = false;
+        setTransition("enter");
+      }
+      return;
+    }
+    // When the disclosure content element is rendered in a portal, we need to
+    // wait for the portal to be mounted and connected to the DOM before we
+    // can start the animation.
+    if (!contentElement?.isConnected) {
+      setTransition(null);
+      return;
+    }
+    // Double requestAnimationFrame is necessary here to avoid potential bugs
+    // when the data attribute is added before the element is fully rendered
+    // in the DOM, which wouldn't trigger the animation.
+    return afterPaint(() => {
+      setTransition(open ? "enter" : mounted ? "leave" : null);
+    });
+  }, [animated, contentElement, open, mounted]);
+
+  useSafeLayoutEffect(() => {
+    if (!store) return;
+    if (!animated) return;
+    if (!transition) return;
+    if (!contentElement) return;
+    const stopAnimation = () => store?.setState("animating", false);
+    const stopAnimationSync = () => flushSync(stopAnimation);
+    // Ignore transition states that don't match the current open state. This
+    // may happen because transitions are updated asynchronously using
+    // requestAnimationFrame.
+    if (transition === "leave" && open) return;
+    if (transition === "enter" && !open) return;
+    // When the animated state is a number, the user has manually set the
+    // animation timeout, so we just respect it.
+    if (typeof animated === "number") {
+      const timeout = animated;
+      return afterTimeout(timeout, stopAnimationSync);
+    }
+    // We need to parse the CSS transition/animation duration and delay to know
+    // when the animation ends. This is safer than relying on the
+    // transitionend/animationend events because it's not guaranteed that these
+    // events will fire. For example, if the element is removed from the DOM
+    // before the animation ends or if the animation wasn't triggered in the
+    // first place, the events won't fire. Besides, there may be multiple
+    // transitions or animations with different durations and delays, and we
+    // need to consider the longest one.
+    const {
+      transitionDuration,
+      animationDuration,
+      transitionDelay,
+      animationDelay,
+    } = getComputedStyle(contentElement);
+    // If we're rendering a dialog backdrop, otherElement will be the dialog
+    // element itself. We need to consider both the backdrop and the dialog
+    // animation/transition durations and delays because the dialog may be
+    // animated while the backdrop is not.
+    const {
+      transitionDuration: transitionDuration2 = "0",
+      animationDuration: animationDuration2 = "0",
+      transitionDelay: transitionDelay2 = "0",
+      animationDelay: animationDelay2 = "0",
+    } = otherElement ? getComputedStyle(otherElement) : {};
+    const delay = parseCSSTime(
+      transitionDelay,
+      animationDelay,
+      transitionDelay2,
+      animationDelay2,
+    );
+    const duration = parseCSSTime(
+      transitionDuration,
+      animationDuration,
+      transitionDuration2,
+      animationDuration2,
+    );
+    const timeout = delay + duration;
+    // If the timeout is zero, there's no animation or transition, either
+    // because they weren't defined in the CSS or the duration was explicitly
+    // set to zero. In this scenario, we can halt the animation right away
+    // and, if we're entering, we can set the animated state to false so
+    // the element unmounts immediately on close without waiting for a
+    // leave animation.
+    if (!timeout) {
+      if (transition === "enter") {
+        store.setState("animated", false);
+      }
+      stopAnimation();
+      return;
+    }
+    // Since setTimeout may be delayed by a few milliseconds, we need to
+    // subtract a frame duration from the timeout to make sure the animation is
+    // stopped right after it ends, preventing flickering.
+    const frameRate = 1000 / 60;
+    const maxTimeout = Math.max(timeout - frameRate, 0);
+    return afterTimeout(maxTimeout, stopAnimationSync);
+  }, [store, animated, contentElement, otherElement, open, transition]);
+
+  props = useWrapElement(
+    props,
+    (element) => (
+      <DialogScopedContextProvider value={store}>
+        {element}
+      </DialogScopedContextProvider>
+    ),
+    [store],
+  );
+
+  const hidden = isHidden(mounted, props.hidden, alwaysVisible);
+  const styleProp = props.style;
+  const style = useMemo(() => {
+    if (hidden) {
+      return { ...styleProp, display: "none" };
+    }
+    return styleProp;
+  }, [hidden, styleProp]);
+
+  props = {
+    "data-open": open || undefined,
+    "data-enter": transition === "enter" || undefined,
+    "data-leave": transition === "leave" || undefined,
+    hidden,
+    ...props,
+    id,
+    ref: useMergeRefs(id ? store.setContentElement : null, ref, props.ref),
+    style,
+  };
+
+  return removeUndefinedValues(props);
+});
+
+const DisclosureContentImpl = forwardRef(function DisclosureContentImpl(
+  props: DisclosureContentProps,
+) {
+  const htmlProps = useDisclosureContent(props);
+  return createElement(TagName, htmlProps);
+});
+
+/**
+ * Renders an element that can be shown or hidden by a
+ * [`Disclosure`](https://ariakit.com/components/disclosure) component.
+ * @see https://ariakit.com/components/disclosure
+ * @example
+ * ```jsx {3}
+ * <DisclosureProvider>
+ *   <Disclosure>Disclosure</Disclosure>
+ *   <DisclosureContent>Content</DisclosureContent>
+ * </DisclosureProvider>
+ * ```
+ */
+export const DisclosureContent = forwardRef(function DisclosureContent({
+  unmountOnHide,
+  ...props
+}: DisclosureContentProps) {
+  const context = useDisclosureProviderContext();
+  const store = props.store || context;
+  const mounted = useStoreState(
+    store,
+    (state) => !unmountOnHide || state?.mounted,
+  );
+  if (mounted === false) return null;
+  return <DisclosureContentImpl {...props} />;
+});
+
+export interface DisclosureContentOptions<
+  _T extends ElementType = TagName,
+> extends Options {
+  /**
+   * Object returned by the
+   * [`useDisclosureStore`](https://ariakit.com/reference/use-disclosure-store)
+   * hook. If not provided, the closest
+   * [`DisclosureProvider`](https://ariakit.com/reference/disclosure-provider)
+   * component's context will be used.
+   */
+  store?: DisclosureStore;
+  /**
+   * Determines whether the content element should remain visible even when the
+   * [`open`](https://ariakit.com/reference/disclosure-provider#open) state is
+   * `false`. If this prop is set to `true`, the `hidden` prop and the `display:
+   * none` style will not be applied, unless explicitly set otherwise.
+   *
+   * This prop is particularly useful when using third-party animation libraries
+   * such as Motion or React Spring, where the element needs to be
+   * visible for exit animations to work.
+   *
+   * Live examples:
+   * - [Dialog with
+   *   Motion](https://ariakit.com/examples/dialog-framer-motion)
+   * - [Menu with
+   *   Motion](https://ariakit.com/examples/menu-framer-motion)
+   * - [Tooltip with
+   *   Motion](https://ariakit.com/examples/tooltip-framer-motion)
+   * - [Dialog with details &
+   *   summary](https://ariakit.com/examples/dialog-details)
+   * @default false
+   */
+  alwaysVisible?: boolean;
+  /**
+   * When set to `true`, the content element will be unmounted and removed from
+   * the DOM when it's hidden.
+   *
+   * Live examples:
+   * - [Navigation Menubar](https://ariakit.com/examples/menubar-navigation)
+   * - [Combobox with integrated
+   *   filter](https://ariakit.com/examples/combobox-filtering-integrated)
+   * - [Textarea with inline
+   *   Combobox](https://ariakit.com/examples/combobox-textarea)
+   * - [Standalone Popover](https://ariakit.com/examples/popover-standalone)
+   * - [Animated Select](https://ariakit.com/examples/select-animated)
+   * - [Multi-Select](https://ariakit.com/examples/select-multiple)
+   * @default false
+   */
+  unmountOnHide?: boolean;
+}
+
+export type DisclosureContentProps<T extends ElementType = TagName> = Props<
+  T,
+  DisclosureContentOptions<T>
+>;

package/src/disclosure/disclosure-context.tsx

@@ -0,0 +1,27 @@
+import { createStoreContext } from "@ariakit/react-utils";
+import type { DisclosureStore } from "./disclosure-store.ts";
+
+const ctx = createStoreContext<DisclosureStore>();
+
+/**
+ * Returns the disclosure store from the nearest disclosure container.
+ * @example
+ * function Disclosure() {
+ *   const store = useDisclosureContext();
+ *
+ *   if (!store) {
+ *     throw new Error("Disclosure must be wrapped in DisclosureProvider");
+ *   }
+ *
+ *   // Use the store...
+ * }
+ */
+export const useDisclosureContext = ctx.useContext;
+
+export const useDisclosureScopedContext = ctx.useScopedContext;
+
+export const useDisclosureProviderContext = ctx.useProviderContext;
+
+export const DisclosureContextProvider = ctx.ContextProvider;
+
+export const DisclosureScopedContextProvider = ctx.ScopedContextProvider;

package/src/disclosure/disclosure-provider.tsx

@@ -0,0 +1,29 @@
+import type { ReactNode } from "react";
+import { DisclosureContextProvider } from "./disclosure-context.tsx";
+import type { DisclosureStoreProps } from "./disclosure-store.ts";
+import { useDisclosureStore } from "./disclosure-store.ts";
+
+/**
+ * Provides a disclosure store to
+ * [Disclosure](https://ariakit.com/components/disclosure) components.
+ * @see https://ariakit.com/components/disclosure
+ * @example
+ * ```jsx
+ * <DisclosureProvider>
+ *   <Disclosure />
+ *   <DisclosureContent />
+ * </DisclosureProvider>
+ * ```
+ */
+export function DisclosureProvider(props: DisclosureProviderProps = {}) {
+  const store = useDisclosureStore(props);
+  return (
+    <DisclosureContextProvider value={store}>
+      {props.children}
+    </DisclosureContextProvider>
+  );
+}
+
+export interface DisclosureProviderProps extends DisclosureStoreProps {
+  children?: ReactNode;
+}

package/src/disclosure/disclosure-store.ts

@@ -0,0 +1,85 @@
+import * as Core from "@ariakit/components/disclosure/disclosure-store";
+import { useStore, useStoreProps } from "@ariakit/react-store";
+import type { Store } from "@ariakit/react-store";
+import { useUpdateEffect } from "@ariakit/react-utils";
+
+export function useDisclosureStoreProps<T extends Core.DisclosureStore>(
+  store: T,
+  update: () => void,
+  props: DisclosureStoreProps,
+) {
+  useUpdateEffect(update, [props.store, props.disclosure]);
+  useStoreProps(store, props, "open", "setOpen");
+  useStoreProps(store, props, "mounted", "setMounted");
+  useStoreProps(store, props, "animated");
+
+  return Object.assign(store, { disclosure: props.disclosure });
+}
+
+/**
+ * Creates a disclosure store to control the state of
+ * [Disclosure](https://ariakit.com/components/disclosure) components.
+ * @see https://ariakit.com/components/disclosure
+ * @example
+ * ```jsx
+ * const disclosure = useDisclosureStore();
+ *
+ * <Disclosure store={disclosure}>Disclosure</Disclosure>
+ * <DisclosureContent store={disclosure}>Content</DisclosureContent>
+ * ```
+ */
+export function useDisclosureStore(
+  props: DisclosureStoreProps = {},
+): DisclosureStore {
+  const [store, update] = useStore(Core.createDisclosureStore, props);
+  return useDisclosureStoreProps(store, update, props);
+}
+
+export interface DisclosureStoreState extends Core.DisclosureStoreState {}
+
+export interface DisclosureStoreFunctions
+  extends
+    Pick<DisclosureStoreOptions, "disclosure">,
+    Omit<Core.DisclosureStoreFunctions, "disclosure"> {}
+
+export interface DisclosureStoreOptions extends Core.DisclosureStoreOptions {
+  /**
+   * A callback that gets called when the
+   * [`open`](https://ariakit.com/reference/disclosure-provider#open) state
+   * changes.
+   * @example
+   * const [open, setOpen] = useState(false);
+   * const disclosure = useDisclosureStore({ open, setOpen });
+   */
+  setOpen?: (open: DisclosureStoreState["open"]) => void;
+  /**
+   * A callback that gets called when the `mounted` state changes.
+   * @example
+   * const [mounted, setMounted] = useState(false);
+   * const disclosure = useDisclosureStore({ setMounted });
+   */
+  setMounted?: (mounted: DisclosureStoreState["mounted"]) => void;
+  /**
+   * A reference to another disclosure store that controls another disclosure
+   * component to keep them in sync. Element states like `contentElement` and
+   * `disclosureElement` won't be synced. For that, use the
+   * [`store`](https://ariakit.com/reference/disclosure-provider#store) prop
+   * instead.
+   *
+   * Live examples:
+   * - [Command Menu](https://ariakit.com/examples/dialog-combobox-command-menu)
+   * - [Command Menu with
+   *   Tabs](https://ariakit.com/examples/dialog-combobox-tab-command-menu)
+   */
+  disclosure?: DisclosureStore | null;
+}
+
+export interface DisclosureStoreProps
+  extends
+    DisclosureStoreOptions,
+    Omit<Core.DisclosureStoreProps, "disclosure"> {}
+
+export interface DisclosureStore
+  extends
+    DisclosureStoreFunctions,
+    Omit<Store<Core.DisclosureStore>, "disclosure"> {}