@ariakit/react-components 0.1.0

package/src/command/command.tsx

@@ -0,0 +1,215 @@
+import {
+  useEvent,
+  useMergeRefs,
+  useMetadataProps,
+  createElement,
+  createHook,
+  forwardRef,
+} from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import {
+  isButton,
+  isTextField,
+  fireClickEvent,
+  isSelfTarget,
+  queueBeforeEvent,
+  disabledFromProps,
+  isFirefox,
+} from "@ariakit/utils";
+import type { ElementType, KeyboardEvent } from "react";
+import { useEffect, useRef, useState } from "react";
+import type { FocusableOptions } from "../focusable/focusable.tsx";
+import { useFocusable } from "../focusable/focusable.tsx";
+
+const TagName = "button" satisfies ElementType;
+type TagName = typeof TagName;
+type HTMLType = HTMLElementTagNameMap[TagName];
+
+function isNativeClick(event: KeyboardEvent) {
+  if (!event.isTrusted) return false;
+  // istanbul ignore next: can't test trusted events yet
+  const element = event.currentTarget;
+  if (event.key === "Enter") {
+    return (
+      isButton(element) ||
+      element.tagName === "SUMMARY" ||
+      element.tagName === "A"
+    );
+  }
+  if (event.key === " ") {
+    return (
+      isButton(element) ||
+      element.tagName === "SUMMARY" ||
+      element.tagName === "INPUT" ||
+      element.tagName === "SELECT"
+    );
+  }
+  return false;
+}
+
+const symbol = Symbol("command");
+
+/**
+ * Returns props to create a `Command` component. If the element is not a native
+ * clickable element (like a button), this hook will return additional props to
+ * make sure it's accessible.
+ * @see https://ariakit.com/components/command
+ * @example
+ * ```jsx
+ * const props = useCommand({ render: <div /> });
+ * <Role {...props}>Accessible button</Role>
+ * ```
+ */
+export const useCommand = createHook<TagName, CommandOptions>(
+  function useCommand({ clickOnEnter = true, clickOnSpace = true, ...props }) {
+    const ref = useRef<HTMLType>(null);
+    const [isNativeButton, setIsNativeButton] = useState(false);
+
+    useEffect(() => {
+      if (!ref.current) return;
+      setIsNativeButton(isButton(ref.current));
+    }, []);
+
+    const [active, setActive] = useState(false);
+    const activeRef = useRef(false);
+    const disabled = disabledFromProps(props);
+    const [isDuplicate, metadataProps] = useMetadataProps(props, symbol, true);
+
+    const onKeyDownProp = props.onKeyDown;
+
+    const onKeyDown = useEvent((event: KeyboardEvent<HTMLType>) => {
+      onKeyDownProp?.(event);
+      const element = event.currentTarget;
+
+      if (event.defaultPrevented) return;
+      if (isDuplicate) return;
+      if (disabled) return;
+      if (!isSelfTarget(event)) return;
+      if (isTextField(element)) return;
+      if (element.isContentEditable) return;
+
+      const isEnter = clickOnEnter && event.key === "Enter";
+      const isSpace = clickOnSpace && event.key === " ";
+      const shouldPreventEnter = event.key === "Enter" && !clickOnEnter;
+      const shouldPreventSpace = event.key === " " && !clickOnSpace;
+
+      if (shouldPreventEnter || shouldPreventSpace) {
+        event.preventDefault();
+        return;
+      }
+
+      if (isEnter || isSpace) {
+        const nativeClick = isNativeClick(event);
+        if (isEnter) {
+          if (!nativeClick) {
+            event.preventDefault();
+            const { view, ...eventInit } = event;
+            // Fire a click event instead of calling element.click() directly so
+            // we can pass along the modifier state.
+            const click = () => fireClickEvent(element, eventInit);
+            // If this element is a link with target="_blank", Firefox will
+            // block the "popup" if the click event is dispatched synchronously
+            // or in a microtask. Queueing the event asynchronously fixes that.
+            if (isFirefox()) {
+              queueBeforeEvent(element, "keyup", click);
+            } else {
+              queueMicrotask(click);
+            }
+          }
+        } else if (isSpace) {
+          activeRef.current = true;
+          if (!nativeClick) {
+            event.preventDefault();
+            setActive(true);
+          }
+        }
+      }
+    });
+
+    const onKeyUpProp = props.onKeyUp;
+
+    const onKeyUp = useEvent((event: KeyboardEvent<HTMLType>) => {
+      onKeyUpProp?.(event);
+
+      if (event.defaultPrevented) return;
+      if (isDuplicate) return;
+      if (disabled) return;
+      if (event.metaKey) return;
+
+      const isSpace = clickOnSpace && event.key === " ";
+
+      if (activeRef.current && isSpace) {
+        activeRef.current = false;
+        if (!isNativeClick(event)) {
+          event.preventDefault();
+          setActive(false);
+          const element = event.currentTarget;
+          const { view, ...eventInit } = event;
+          queueMicrotask(() => fireClickEvent(element, eventInit));
+        }
+      }
+    });
+
+    props = {
+      "data-active": active || undefined,
+      type: isNativeButton ? "button" : undefined,
+      ...metadataProps,
+      ...props,
+      ref: useMergeRefs(ref, props.ref),
+      onKeyDown,
+      onKeyUp,
+    };
+
+    props = useFocusable<TagName>(props);
+
+    return props;
+  },
+);
+
+/**
+ * Renders a clickable element, which is a `button` by default, and inherits
+ * features from the [`Focusable`](https://ariakit.com/reference/focusable)
+ * component.
+ *
+ * If the base element isn't a native clickable one, this component will provide
+ * extra attributes and event handlers to ensure accessibility. It can be
+ * activated with the keyboard using the
+ * [`clickOnEnter`](https://ariakit.com/reference/command#clickonenter) and
+ * [`clickOnSpace`](https://ariakit.com/reference/command#clickonspace)
+ * props. Both are set to `true` by default.
+ * @see https://ariakit.com/components/command
+ * @example
+ * ```jsx
+ * <Command>Button</Command>
+ * ```
+ */
+export const Command = forwardRef(function Command(props: CommandProps) {
+  const htmlProps = useCommand(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface CommandOptions<
+  T extends ElementType = TagName,
+> extends FocusableOptions<T> {
+  /**
+   * If set to `true`, pressing the enter key while this element is focused will
+   * trigger a click on the element, regardless of whether it's a native button
+   * or not. If this prop is set to `false`, pressing enter will not initiate a
+   * click.
+   * @default true
+   */
+  clickOnEnter?: boolean;
+  /**
+   * If set to `true`, pressing and releasing the space key while this element
+   * is focused will trigger a click on the element, regardless of whether it's
+   * a native button or not. If this prop is set to `false`, space will not
+   * initiate a click.
+   * @default true
+   */
+  clickOnSpace?: boolean;
+}
+
+export type CommandProps<T extends ElementType = TagName> = Props<
+  T,
+  CommandOptions<T>
+>;

package/src/composite/composite-container.tsx

@@ -0,0 +1,278 @@
+// TODO: Add data-attribute to indicate whether it's expanded?
+import { useStoreState } from "@ariakit/react-store";
+import {
+  useEvent,
+  useMergeRefs,
+  createElement,
+  createHook,
+  forwardRef,
+} from "@ariakit/react-utils";
+import type { Options, Props } from "@ariakit/react-utils";
+import {
+  isButton,
+  isTextField,
+  isFocusEventOutside,
+  isSelfTarget,
+  disableFocusIn,
+  getFirstTabbableIn,
+  restoreFocusIn,
+  removeUndefinedValues,
+} from "@ariakit/utils";
+import type { ElementType, FocusEvent, KeyboardEvent, MouseEvent } from "react";
+import { useEffect, useRef } from "react";
+import { useCompositeContext } from "./composite-context.tsx";
+import type { CompositeStore } from "./composite-store.ts";
+import { selectTextField } from "./utils.ts";
+
+const TagName = "div" satisfies ElementType;
+type TagName = typeof TagName;
+type HTMLType = HTMLElementTagNameMap[TagName];
+
+function getFirstTabbable(container: HTMLElement) {
+  restoreFocusIn(container);
+  const tabbable = getFirstTabbableIn(container);
+  disableFocusIn(container);
+  return tabbable;
+}
+
+/**
+ * Returns props to create a `CompositeContainer` component. This component
+ * renders interactive widgets inside composite items. This should be used in
+ * conjunction with the `CompositeItem` component, the `useCompositeItem` hook,
+ * or any other component/hook that uses `CompositeItem` underneath.
+ * @see https://ariakit.com/components/composite
+ * @example
+ * ```jsx
+ * const store = useCompositeStore();
+ * const props = useCompositeContainer({ store });
+ * <Composite store={store}>
+ *   <CompositeItem {...props}>
+ *     <input type="text" />
+ *   </CompositeItem>
+ * </Composite>
+ * ```
+ */
+export const useCompositeContainer = createHook<
+  TagName,
+  CompositeContainerOptions
+>(function useCompositeContainer({ store, ...props }) {
+  const context = useCompositeContext();
+  store = store || context;
+
+  const ref = useRef<HTMLType>(null);
+  const isOpenRef = useRef(false);
+
+  const open = (collapseToEnd = false) => {
+    const container = ref.current;
+    if (!container) return;
+    restoreFocusIn(container);
+    const tabbable = getFirstTabbableIn(container);
+    if (!tabbable) {
+      disableFocusIn(container);
+      return;
+    }
+    isOpenRef.current = true;
+    queueMicrotask(() => {
+      tabbable.focus();
+      if (isTextField(tabbable) || tabbable.isContentEditable) {
+        selectTextField(tabbable, collapseToEnd);
+      }
+    });
+  };
+
+  const close = () => {
+    const container = ref.current;
+    if (!container) return;
+    isOpenRef.current = false;
+    disableFocusIn(container);
+  };
+
+  const renderedItems = useStoreState(store, "renderedItems");
+
+  // Disable focus on the tabbable elements inside the container when the
+  // container is mounted.
+  useEffect(() => {
+    const container = ref.current;
+    if (!container) return;
+    const isOpen = isOpenRef.current;
+    // We need to wait for the items to be populated before we can disable
+    // focus, so we consider edge cases where some tabbable elements become
+    // disabled after the first render (for example, when rendering nested
+    // composite elements).
+    if (!isOpen && renderedItems?.length) {
+      disableFocusIn(container);
+    }
+  }, [renderedItems]);
+
+  const onFocusProp = props.onFocus;
+
+  const onFocus = useEvent((event: FocusEvent<HTMLType>) => {
+    onFocusProp?.(event);
+    if (event.defaultPrevented) return;
+    if (!store) return;
+    const isOpen = isOpenRef.current;
+    if (isSelfTarget(event)) {
+      // The container element itself has received focus. Here we make an
+      // additional step in case tabbable elements have been added lazily to
+      // the DOM. We get all containers in the current composite element and
+      // disable all tabbable elements inside them.
+      isOpenRef.current = false;
+      const { baseElement } = store.getState();
+      const composite = baseElement;
+      const selector = "[data-composite-container]";
+      const containers = composite?.querySelectorAll<HTMLElement>(selector);
+      if (containers) {
+        for (const container of containers) {
+          disableFocusIn(container);
+        }
+      }
+    } else if (!isOpen) {
+      // Otherwise, if any element inside the container has received focus,
+      // for example, by a direct user click, we should act as the container
+      // has been opened.
+      isOpenRef.current = true;
+      restoreFocusIn(event.currentTarget);
+      // Resets the moves in the store so the composite item will not be
+      // focused right after the focusable element inside the container gets
+      // focus.
+      store?.setState("moves", 0);
+    }
+  });
+
+  const onBlurProp = props.onBlur;
+
+  const onBlur = useEvent((event: FocusEvent<HTMLType>) => {
+    onBlurProp?.(event);
+    if (event.defaultPrevented) return;
+    if (isFocusEventOutside(event)) {
+      close();
+    }
+  });
+
+  const onKeyDownProp = props.onKeyDown;
+
+  const onKeyDown = useEvent((event: KeyboardEvent<HTMLType>) => {
+    onKeyDownProp?.(event);
+    if (event.defaultPrevented) return;
+    if (event.altKey) return;
+    if (event.ctrlKey) return;
+    if (event.metaKey) return;
+    if (event.shiftKey) return;
+    const container = event.currentTarget;
+    if (isSelfTarget(event)) {
+      // Alphanumeric key on container: focus the first tabbable element in
+      // the container if it's a text field or contenteditable element. This
+      // will automatically replace the text field value with the pressed key.
+      if (event.key.length === 1 && event.key !== " ") {
+        const tabbable = getFirstTabbable(container);
+        if (!tabbable) return;
+        if (isTextField(tabbable) || tabbable.isContentEditable) {
+          event.stopPropagation();
+          open();
+        }
+      }
+
+      // Delete/Backspace on container: focus on the first tabbable element in
+      // the container if it's a text field or contenteditable element. This
+      // will automatically clear the text field value.
+      else if (event.key === "Delete" || event.key === "Backspace") {
+        const tabbable = getFirstTabbable(container);
+        if (!tabbable) return;
+        if (isTextField(tabbable) || tabbable.isContentEditable) {
+          open();
+          // We need to move focus back to the container as soon as the
+          // delete/backspace key is captured by the text field.
+          const onInput = () => queueMicrotask(() => container.focus());
+          container.addEventListener("input", onInput, { once: true });
+        }
+      }
+    }
+
+    // Escape on tabbable element inside container: move focus back to the
+    // container.
+    else if (event.key === "Escape") {
+      queueMicrotask(() => container.focus());
+    }
+
+    // Enter on tabbable element inside container: move focus back to the
+    // container only if it's an input or contenteditable element.
+    else if (event.key === "Enter") {
+      const target = event.target as HTMLElement;
+      const isInput =
+        (target.tagName === "INPUT" && !isButton(target)) ||
+        target.tagName === "TEXTAREA";
+      if (isInput || target.isContentEditable) {
+        event.preventDefault();
+        queueMicrotask(() => container.focus());
+      }
+    }
+  });
+
+  const onClickProp = props.onClick;
+
+  const onClick = useEvent((event: MouseEvent<HTMLType>) => {
+    onClickProp?.(event);
+    if (event.defaultPrevented) return;
+    if (isSelfTarget(event) && !event.detail) {
+      // Move focus to the first tabbable element in the container and place
+      // at the end.
+      open(true);
+    }
+  });
+
+  props = {
+    "data-composite-container": "",
+    ...props,
+    ref: useMergeRefs(ref, props.ref),
+    onFocus,
+    onBlur,
+    onKeyDown,
+    onClick,
+  };
+
+  return removeUndefinedValues(props);
+});
+
+/**
+ * Renders a container for interactive widgets inside composite items. This
+ * should be used in conjunction with the
+ * [`CompositeItem`](https://ariakit.com/reference/composite-item) component or
+ * a component that uses
+ * [`CompositeItem`](https://ariakit.com/reference/composite-item) underneath.
+ * @see https://ariakit.com/components/composite
+ * @example
+ * ```jsx {3-5}
+ * <CompositeProvider>
+ *   <Composite>
+ *     <CompositeItem render={<CompositeContainer />}>
+ *       <input type="text" />
+ *     </CompositeItem>
+ *   </Composite>
+ * </CompositeProvider>
+ * ```
+ */
+export const CompositeContainer = forwardRef(function CompositeContainer(
+  props: CompositeContainerProps,
+) {
+  const htmlProps = useCompositeContainer(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface CompositeContainerOptions<
+  _T extends ElementType = TagName,
+> extends Options {
+  /**
+   * Object returned by the
+   * [`useCompositeStore`](https://ariakit.com/reference/use-composite-store)
+   * hook. If not provided, the closest
+   * [`Composite`](https://ariakit.com/reference/composite) or
+   * [`CompositeProvider`](https://ariakit.com/reference/composite-provider)
+   * components' context will be used.
+   */
+  store?: CompositeStore;
+}
+
+export type CompositeContainerProps<T extends ElementType = TagName> = Props<
+  T,
+  CompositeContainerOptions<T>
+>;

package/src/composite/composite-context.tsx

@@ -0,0 +1,53 @@
+import { createStoreContext } from "@ariakit/react-utils";
+import { createContext } from "react";
+import {
+  CollectionContextProvider,
+  CollectionScopedContextProvider,
+} from "../collection/collection-context.tsx";
+import type { CompositeStore } from "./composite-store.ts";
+
+const ctx = createStoreContext<CompositeStore>(
+  [CollectionContextProvider],
+  [CollectionScopedContextProvider],
+);
+
+/**
+ * Returns the composite store from the nearest composite container.
+ * @example
+ * function CompositeItem() {
+ *   const store = useCompositeContext();
+ *
+ *   if (!store) {
+ *     throw new Error("CompositeItem must be wrapped in CompositeProvider");
+ *   }
+ *
+ *   // Use the store...
+ * }
+ */
+export const useCompositeContext = ctx.useContext;
+
+export const useCompositeScopedContext = ctx.useScopedContext;
+
+export const useCompositeProviderContext = ctx.useProviderContext;
+
+export const CompositeContextProvider = ctx.ContextProvider;
+
+export const CompositeScopedContextProvider = ctx.ScopedContextProvider;
+
+interface ItemContext {
+  baseElement?: HTMLElement;
+  id?: string;
+}
+
+export const CompositeItemContext = createContext<ItemContext | undefined>(
+  undefined,
+);
+
+interface RowContext extends ItemContext {
+  ariaSetSize?: number;
+  ariaPosInSet?: number;
+}
+
+export const CompositeRowContext = createContext<RowContext | undefined>(
+  undefined,
+);

package/src/composite/composite-group-label.tsx

@@ -0,0 +1,73 @@
+import { createElement, createHook, forwardRef } from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import type { ElementType } from "react";
+import type { GroupLabelOptions } from "../group/group-label.tsx";
+import { useGroupLabel } from "../group/group-label.tsx";
+import type { CompositeStore } from "./composite-store.ts";
+
+const TagName = "div" satisfies ElementType;
+type TagName = typeof TagName;
+
+/**
+ * Returns props to create a `CompositeGroupLabel` component. This hook must be
+ * used in a component that's wrapped with `CompositeGroup` so the
+ * `aria-labelledby` prop is properly set on the composite group element.
+ * @see https://ariakit.com/components/composite
+ * @example
+ * ```jsx
+ * // This component must be wrapped with CompositeGroup
+ * const props = useCompositeGroupLabel();
+ * <Role {...props}>Label</Role>
+ * ```
+ */
+export const useCompositeGroupLabel = createHook<
+  TagName,
+  CompositeGroupLabelOptions
+>(function useCompositeGroupLabel({ store, ...props }) {
+  props = useGroupLabel(props);
+  return props;
+});
+
+/**
+ * Renders a label in a composite group. This component must be wrapped with
+ * [`CompositeGroup`](https://ariakit.com/reference/composite-group) so the
+ * `aria-labelledby` prop is properly set on the group element.
+ * @see https://ariakit.com/components/composite
+ * @example
+ * ```jsx {4}
+ * <CompositeProvider>
+ *   <Composite>
+ *     <CompositeGroup>
+ *       <CompositeGroupLabel>Label</CompositeGroupLabel>
+ *       <CompositeItem>Item 1</CompositeItem>
+ *       <CompositeItem>Item 2</CompositeItem>
+ *     </CompositeGroup>
+ *   </Composite>
+ * </CompositeProvider>
+ * ```
+ */
+export const CompositeGroupLabel = forwardRef(function CompositeGroupLabel(
+  props: CompositeGroupLabelProps,
+) {
+  const htmlProps = useCompositeGroupLabel(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface CompositeGroupLabelOptions<
+  T extends ElementType = TagName,
+> extends GroupLabelOptions<T> {
+  /**
+   * Object returned by the
+   * [`useCompositeStore`](https://ariakit.com/reference/use-composite-store)
+   * hook. If not provided, the closest
+   * [`Composite`](https://ariakit.com/reference/composite) or
+   * [`CompositeProvider`](https://ariakit.com/reference/composite-provider)
+   * components' context will be used.
+   */
+  store?: CompositeStore;
+}
+
+export type CompositeGroupLabelProps<T extends ElementType = TagName> = Props<
+  T,
+  CompositeGroupLabelOptions<T>
+>;

package/src/composite/composite-group.tsx

@@ -0,0 +1,77 @@
+import { createElement, createHook, forwardRef } from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import type { ElementType } from "react";
+import type { GroupOptions } from "../group/group.tsx";
+import { useGroup } from "../group/group.tsx";
+import type { CompositeStore } from "./composite-store.ts";
+
+const TagName = "div" satisfies ElementType;
+type TagName = typeof TagName;
+
+/**
+ * Returns props to create a `CompositeGroup` component.
+ * @see https://ariakit.com/components/composite
+ * @example
+ * ```jsx
+ * const store = useCompositeStore();
+ * const props = useCompositeGroup({ store });
+ * <Composite store={store}>
+ *   <Role {...props}>
+ *     <CompositeGroupLabel>Label</CompositeGroupLabel>
+ *     <CompositeItem>Item 1</CompositeItem>
+ *     <CompositeItem>Item 2</CompositeItem>
+ *   </Role>
+ * </Composite>
+ * ```
+ */
+export const useCompositeGroup = createHook<TagName, CompositeGroupOptions>(
+  function useCompositeGroup({ store, ...props }) {
+    props = useGroup(props);
+    return props;
+  },
+);
+
+/**
+ * Renders a group element for composite items. The
+ * [`CompositeGroupLabel`](https://ariakit.com/reference/composite-group-label)
+ * component can be used inside this component so the `aria-labelledby` prop is
+ * properly set on the group element.
+ * @see https://ariakit.com/components/composite
+ * @example
+ * ```jsx {3-7}
+ * <CompositeProvider>
+ *   <Composite>
+ *     <CompositeGroup>
+ *       <CompositeGroupLabel>Label</CompositeGroupLabel>
+ *       <CompositeItem>Item 1</CompositeItem>
+ *       <CompositeItem>Item 2</CompositeItem>
+ *     </CompositeGroup>
+ *   </Composite>
+ * </CompositeProvider>
+ * ```
+ */
+export const CompositeGroup = forwardRef(function CompositeGroup(
+  props: CompositeGroupProps,
+) {
+  const htmlProps = useCompositeGroup(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface CompositeGroupOptions<
+  T extends ElementType = TagName,
+> extends GroupOptions<T> {
+  /**
+   * Object returned by the
+   * [`useCompositeStore`](https://ariakit.com/reference/use-composite-store)
+   * hook. If not provided, the closest
+   * [`Composite`](https://ariakit.com/reference/composite) or
+   * [`CompositeProvider`](https://ariakit.com/reference/composite-provider)
+   * components' context will be used.
+   */
+  store?: CompositeStore;
+}
+
+export type CompositeGroupProps<T extends ElementType = TagName> = Props<
+  T,
+  CompositeGroupOptions<T>
+>;