@ariakit/react-components 0.1.0

package/src/combobox/combobox-item.tsx

@@ -0,0 +1,363 @@
+import { useStoreStateObject } from "@ariakit/react-store";
+import {
+  useBooleanEvent,
+  useEvent,
+  useWrapElement,
+  createElement,
+  createHook,
+  forwardRef,
+  memo,
+} from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import {
+  isTextField,
+  isDownloading,
+  isOpeningInNewTab,
+  hasFocus,
+  invariant,
+} from "@ariakit/utils";
+import type { BooleanOrCallback } from "@ariakit/utils";
+import type { ElementType, KeyboardEvent, MouseEvent } from "react";
+import { useCallback, useContext } from "react";
+import type { CompositeHoverOptions } from "../composite/composite-hover.tsx";
+import { useCompositeHover } from "../composite/composite-hover.tsx";
+import type { CompositeItemOptions } from "../composite/composite-item.tsx";
+import { useCompositeItem } from "../composite/composite-item.tsx";
+import {
+  ComboboxItemCheckedContext,
+  ComboboxItemValueContext,
+  ComboboxListRoleContext,
+  useComboboxScopedContext,
+} from "./combobox-context.tsx";
+import type { ComboboxStore } from "./combobox-store.ts";
+
+const TagName = "div" satisfies ElementType;
+type TagName = typeof TagName;
+type HTMLType = HTMLElementTagNameMap[TagName];
+
+function isSelected(
+  storeValue?: string | readonly string[],
+  itemValue?: string,
+) {
+  if (itemValue == null) return;
+  if (storeValue == null) return false;
+  if (Array.isArray(storeValue)) {
+    return storeValue.includes(itemValue);
+  }
+  return storeValue === itemValue;
+}
+
+function getItemRole(popupRole?: string) {
+  const itemRoleByPopupRole = {
+    menu: "menuitem",
+    listbox: "option",
+    tree: "treeitem",
+  };
+  const key = popupRole as keyof typeof itemRoleByPopupRole;
+  return itemRoleByPopupRole[key] ?? "option";
+}
+
+/**
+ * Returns props to create a `ComboboxItem` component.
+ * @see https://ariakit.com/components/combobox
+ * @example
+ * ```jsx
+ * const store = useComboboxStore();
+ * const props = useComboboxItem({ store, value: "value" });
+ * <Role {...props} />
+ * ```
+ */
+export const useComboboxItem = createHook<TagName, ComboboxItemOptions>(
+  function useComboboxItem({
+    store,
+    value,
+    hideOnClick,
+    setValueOnClick,
+    selectValueOnClick = true,
+    resetValueOnSelect,
+    focusOnHover = false,
+    moveOnKeyPress = true,
+    getItem: getItemProp,
+    ...props
+  }) {
+    const context = useComboboxScopedContext();
+    store = store || context;
+
+    invariant(
+      store,
+      process.env.NODE_ENV !== "production" &&
+        "ComboboxItem must be wrapped in a ComboboxList or ComboboxPopover component.",
+    );
+
+    const { resetValueOnSelectState, multiSelectable, selected } =
+      useStoreStateObject(store, {
+        resetValueOnSelectState: "resetValueOnSelect",
+        multiSelectable(state) {
+          return Array.isArray(state.selectedValue);
+        },
+        selected(state) {
+          return isSelected(state.selectedValue, value);
+        },
+      });
+
+    const getItem = useCallback<NonNullable<CompositeItemOptions["getItem"]>>(
+      (item) => {
+        const nextItem = { ...item, value };
+        if (getItemProp) {
+          return getItemProp(nextItem);
+        }
+        return nextItem;
+      },
+      [value, getItemProp],
+    );
+
+    setValueOnClick = setValueOnClick ?? !multiSelectable;
+    hideOnClick = hideOnClick ?? (value != null && !multiSelectable);
+
+    const onClickProp = props.onClick;
+    const setValueOnClickProp = useBooleanEvent(setValueOnClick);
+    const selectValueOnClickProp = useBooleanEvent(selectValueOnClick);
+    const resetValueOnSelectProp = useBooleanEvent(
+      resetValueOnSelect ?? resetValueOnSelectState ?? multiSelectable,
+    );
+    const hideOnClickProp = useBooleanEvent(hideOnClick);
+
+    const onClick = useEvent((event: MouseEvent<HTMLType>) => {
+      onClickProp?.(event);
+      if (event.defaultPrevented) return;
+      if (isDownloading(event)) return;
+      if (isOpeningInNewTab(event)) return;
+      if (value != null) {
+        if (selectValueOnClickProp(event)) {
+          if (resetValueOnSelectProp(event)) {
+            store?.resetValue();
+          }
+          store?.setSelectedValue((prevValue) => {
+            if (!Array.isArray(prevValue)) return value;
+            if (prevValue.includes(value)) {
+              return prevValue.filter((v) => v !== value);
+            }
+            return [...prevValue, value];
+          });
+        }
+        if (setValueOnClickProp(event)) {
+          store?.setValue(value);
+        }
+      }
+      if (hideOnClickProp(event)) {
+        store?.hide();
+      }
+    });
+
+    const onKeyDownProp = props.onKeyDown;
+
+    const onKeyDown = useEvent((event: KeyboardEvent<HTMLType>) => {
+      onKeyDownProp?.(event);
+      if (event.defaultPrevented) return;
+      const baseElement = store?.getState().baseElement;
+      if (!baseElement) return;
+      if (hasFocus(baseElement)) return;
+      // When the combobox is not working with virtual focus, the items will
+      // receive DOM focus. Therefore, pressing printable keys will not fill
+      // the text field. So we need to programmatically focus on the text
+      // field when the user presses printable keys.
+      const printable = event.key.length === 1;
+      if (printable || event.key === "Backspace" || event.key === "Delete") {
+        queueMicrotask(() => baseElement.focus());
+        if (isTextField(baseElement)) {
+          // If the combobox element is a text field, we should update the
+          // store value with the current's element value. This is necessary
+          // because the value may temporarily change based on the currently
+          // selected item, but it'll be reset to the original value when the
+          // combobox input is focused.
+          store?.setValue(baseElement.value);
+        }
+      }
+    });
+
+    if (multiSelectable && selected != null) {
+      props = {
+        "aria-selected": selected,
+        ...props,
+      };
+    }
+
+    props = useWrapElement(
+      props,
+      (element) => (
+        <ComboboxItemValueContext.Provider value={value}>
+          <ComboboxItemCheckedContext.Provider value={selected ?? false}>
+            {element}
+          </ComboboxItemCheckedContext.Provider>
+        </ComboboxItemValueContext.Provider>
+      ),
+      [value, selected],
+    );
+
+    const popupRole = useContext(ComboboxListRoleContext);
+
+    props = {
+      role: getItemRole(popupRole),
+      children: value,
+      ...props,
+      onClick,
+      onKeyDown,
+    };
+
+    const moveOnKeyPressProp = useBooleanEvent(moveOnKeyPress);
+
+    props = useCompositeItem<TagName>({
+      store,
+      ...props,
+      getItem,
+      // Dispatch a custom event on the combobox input when moving to an item
+      // with the keyboard so the Combobox component can enable inline
+      // autocompletion.
+      moveOnKeyPress: (event) => {
+        if (!moveOnKeyPressProp(event)) return false;
+        const moveEvent = new Event("combobox-item-move");
+        const baseElement = store?.getState().baseElement;
+        baseElement?.dispatchEvent(moveEvent);
+        return true;
+      },
+    });
+
+    props = useCompositeHover({ store, focusOnHover, ...props });
+
+    return props;
+  },
+);
+
+/**
+ * Renders a combobox item inside
+ * [`ComboboxList`](https://ariakit.com/reference/combobox-list) or
+ * [`ComboboxPopover`](https://ariakit.com/reference/combobox-popover)
+ * components.
+ *
+ * By default, the [`value`](https://ariakit.com/reference/combobox-item#value)
+ * prop will be rendered as the children, but this can be overriden.
+ * @see https://ariakit.com/components/combobox
+ * @example
+ * ```jsx {4-6}
+ * <ComboboxProvider>
+ *   <Combobox />
+ *   <ComboboxPopover>
+ *     <ComboboxItem value="Apple" />
+ *     <ComboboxItem value="Banana" />
+ *     <ComboboxItem value="Orange" />
+ *   </ComboboxPopover>
+ * </ComboboxProvider>
+ * ```
+ */
+export const ComboboxItem = memo(
+  forwardRef(function ComboboxItem(props: ComboboxItemProps) {
+    const htmlProps = useComboboxItem(props);
+    return createElement(TagName, htmlProps);
+  }),
+);
+
+export interface ComboboxItemOptions<T extends ElementType = TagName>
+  extends CompositeItemOptions<T>, CompositeHoverOptions<T> {
+  /**
+   * Object returned by the
+   * [`useComboboxStore`](https://ariakit.com/reference/use-combobox-store)
+   * hook. If not provided, the closest
+   * [`ComboboxList`](https://ariakit.com/reference/combobox-list) or
+   * [`ComboboxPopover`](https://ariakit.com/reference/combobox-popover)
+   * components' context will be used.
+   *
+   * Live examples:
+   * - [Navigation Menubar](https://ariakit.com/examples/menubar-navigation)
+   */
+  store?: ComboboxStore;
+  /**
+   * The value of the item. This will be rendered as the children by default.
+   * - If
+   *   [`setValueOnClick`](https://ariakit.com/reference/combobox-item#setvalueonclick)
+   *   is set to `true`, this will be the value of the combobox input when the
+   *   user clicks on this item.
+   * - If
+   *   [`selectValueOnClick`](https://ariakit.com/reference/combobox-item#selectvalueonclick)
+   *   is set to `true`, this will be the value of the
+   *   [`selectedValue`](https://ariakit.com/reference/combobox-provider#selectedvalue)
+   *   state.
+   * - If the
+   *   [`autoComplete`](https://ariakit.com/reference/combobox#autocomplete)
+   *   prop on the [`Combobox`](https://ariakit.com/reference/combobox)
+   *   component is set to `both` or `inline`, this will be the value of the
+   *   combobox input when the combobox loses focus.
+   *
+   * Live examples:
+   * - [Animated Combobox](https://ariakit.com/examples/combobox-animated)
+   * - [ComboboxCancel](https://ariakit.com/examples/combobox-cancel)
+   * - [ComboboxDisclosure](https://ariakit.com/examples/combobox-disclosure)
+   * - [Combobox filtering](https://ariakit.com/examples/combobox-filtering)
+   * - [ComboboxGroup](https://ariakit.com/examples/combobox-group)
+   * - [Textarea with inline
+   *   Combobox](https://ariakit.com/examples/combobox-textarea)
+   */
+  value?: string;
+  /**
+   * Whether to hide the combobox when this item is clicked. By default, the
+   * combobox will be hidden when the user clicks on an item with a
+   * [`value`](https://ariakit.com/reference/combobox-item#value) prop, unless
+   * the combobox is
+   * [multi-selectable](https://ariakit.com/examples/combobox-multiple).
+   *
+   * Live examples:
+   * - [Combobox with links](https://ariakit.com/examples/combobox-links)
+   * - [Submenu with
+   *   Combobox](https://ariakit.com/examples/menu-nested-combobox)
+   * - [Command Menu](https://ariakit.com/examples/dialog-combobox-command-menu)
+   * - [Command Menu with
+   *   Tabs](https://ariakit.com/examples/dialog-combobox-tab-command-menu)
+   */
+  hideOnClick?: BooleanOrCallback<MouseEvent<HTMLElement>>;
+  /**
+   * Whether to set the combobox
+   * [`value`](https://ariakit.com/reference/combobox-provider#value) state
+   * using this item's
+   * [`value`](https://ariakit.com/reference/combobox-item#value) when the item
+   * is clicked. The default is `true`, unless the combobox is
+   * [multi-selectable](https://ariakit.com/examples/combobox-multiple).
+   *
+   * Live examples:
+   * - [Menu with Combobox](https://ariakit.com/examples/menu-combobox)
+   * - [Submenu with
+   *   Combobox](https://ariakit.com/examples/menu-nested-combobox)
+   */
+  setValueOnClick?: BooleanOrCallback<MouseEvent<HTMLElement>>;
+  /**
+   * Whether to set the
+   * [`selectedValue`](https://ariakit.com/reference/combobox-provider#selectedvalue)
+   * state using this item's
+   * [`value`](https://ariakit.com/reference/combobox-item#value) when the item
+   * is clicked. If a callback is provided, it will only be invoked if the item
+   * has a value.
+   *
+   * Live examples:
+   * - [Submenu with
+   *   Combobox](https://ariakit.com/examples/menu-nested-combobox)
+   * @default true
+   */
+  selectValueOnClick?: BooleanOrCallback<MouseEvent<HTMLElement>>;
+  /**
+   * Whether to reset the the combobox input value when this item is selected or
+   * unselected by click. This prop is set to `true` by default if
+   * the combobox supports multiple selections. In other words, if the
+   * [`selectedValue`](https://ariakit.com/reference/combobox-provider#selectedvalue)
+   * or
+   * [`defaultSelectedValue`](https://ariakit.com/reference/combobox-provider#defaultselectedvalue)
+   * props are arrays.
+   */
+  resetValueOnSelect?: BooleanOrCallback<MouseEvent<HTMLElement>>;
+  /**
+   * @default false
+   */
+  focusOnHover?: CompositeHoverOptions["focusOnHover"];
+}
+
+export type ComboboxItemProps<T extends ElementType = TagName> = Props<
+  T,
+  ComboboxItemOptions<T>
+>;

package/src/combobox/combobox-label.tsx

@@ -0,0 +1,89 @@
+import { useStoreState } from "@ariakit/react-store";
+import {
+  createElement,
+  createHook,
+  forwardRef,
+  memo,
+} from "@ariakit/react-utils";
+import type { Options, Props } from "@ariakit/react-utils";
+import { invariant, removeUndefinedValues } from "@ariakit/utils";
+import type { ElementType } from "react";
+import { useComboboxProviderContext } from "./combobox-context.tsx";
+import type { ComboboxStore } from "./combobox-store.ts";
+
+const TagName = "label" satisfies ElementType;
+type TagName = typeof TagName;
+
+/**
+ * Returns props to create a `ComboboxLabel` component.
+ * @see https://ariakit.com/components/combobox
+ * @example
+ * ```jsx
+ * const store = useComboboxStore();
+ * const props = useComboboxLabel({ store });
+ * <Role {...props}>Favorite fruit</Role>
+ * <Combobox store={store} />
+ * ```
+ */
+export const useComboboxLabel = createHook<TagName, ComboboxLabelOptions>(
+  function useComboboxLabel({ store, ...props }) {
+    const context = useComboboxProviderContext();
+    store = store || context;
+
+    invariant(
+      store,
+      process.env.NODE_ENV !== "production" &&
+        "ComboboxLabel must receive a `store` prop or be wrapped in a ComboboxProvider component.",
+    );
+
+    const comboboxId = useStoreState(store, (state) => state.baseElement?.id);
+
+    props = {
+      htmlFor: comboboxId,
+      ...props,
+    };
+
+    return removeUndefinedValues(props);
+  },
+);
+
+/**
+ * Renders a label for the [`Combobox`](https://ariakit.com/reference/combobox)
+ * component.
+ * @see https://ariakit.com/components/combobox
+ * @example
+ * ```jsx {2}
+ * <ComboboxProvider>
+ *   <ComboboxLabel>Favorite fruit</ComboboxLabel>
+ *   <Combobox />
+ *   <ComboboxPopover>
+ *     <ComboboxItem value="Apple" />
+ *     <ComboboxItem value="Orange" />
+ *   </ComboboxPopover>
+ * </ComboboxProvider>
+ * ```
+ */
+export const ComboboxLabel = memo(
+  forwardRef(function ComboboxLabel(props: ComboboxLabelProps) {
+    const htmlProps = useComboboxLabel(props);
+    return createElement(TagName, htmlProps);
+  }),
+);
+
+export interface ComboboxLabelOptions<
+  _T extends ElementType = TagName,
+> extends Options {
+  /**
+   * Object returned by the
+   * [`useComboboxStore`](https://ariakit.com/reference/use-combobox-store)
+   * hook. If not provided, the closest
+   * [`ComboboxProvider`](https://ariakit.com/reference/combobox-provider)
+   * component's context will be used.
+   */
+  store?: ComboboxStore;
+}
+
+export type ComboboxLabelProps<T extends ElementType = TagName> = Props<
+  T,
+  ComboboxLabelOptions<T>
+>;

package/src/combobox/combobox-list.tsx

@@ -0,0 +1,176 @@
+import { useStoreState } from "@ariakit/react-store";
+import {
+  useAttribute,
+  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 { useRef, useState } from "react";
+import type { DisclosureContentOptions } from "../disclosure/disclosure-content.tsx";
+import { isHidden } from "../disclosure/disclosure-content.tsx";
+import {
+  ComboboxListRoleContext,
+  ComboboxScopedContextProvider,
+  useComboboxContext,
+  useComboboxScopedContext,
+} from "./combobox-context.tsx";
+import type { ComboboxStore } from "./combobox-store.ts";
+
+const TagName = "div" satisfies ElementType;
+type TagName = typeof TagName;
+type HTMLType = HTMLElementTagNameMap[TagName];
+
+/**
+ * Returns props to create a `ComboboxList` component.
+ * @see https://ariakit.com/components/combobox
+ * @example
+ * ```jsx
+ * const store = useComboboxStore();
+ * const props = useComboboxList({ store });
+ * <Role {...props}>
+ *   <ComboboxItem value="Item 1" />
+ *   <ComboboxItem value="Item 2" />
+ *   <ComboboxItem value="Item 3" />
+ * </Role>
+ * ```
+ */
+export const useComboboxList = createHook<TagName, ComboboxListOptions>(
+  function useComboboxList({ store, alwaysVisible, ...props }) {
+    const scopedContext = useComboboxScopedContext(true);
+    const context = useComboboxContext();
+    store = store || context;
+    const scopedContextSameStore = !!store && store === scopedContext;
+
+    invariant(
+      store,
+      process.env.NODE_ENV !== "production" &&
+        "ComboboxList must receive a `store` prop or be wrapped in a ComboboxProvider component.",
+    );
+
+    const ref = useRef<HTMLType>(null);
+    const id = useId(props.id);
+    const mounted = useStoreState(store, "mounted");
+    const hidden = isHidden(mounted, props.hidden, alwaysVisible);
+    const style = hidden ? { ...props.style, display: "none" } : props.style;
+
+    const multiSelectable = useStoreState(store, (state) =>
+      Array.isArray(state.selectedValue),
+    );
+    const role = useAttribute(ref, "role", props.role);
+    const isCompositeRole =
+      role === "listbox" || role === "tree" || role === "grid";
+    const ariaMultiSelectable = isCompositeRole
+      ? multiSelectable || undefined
+      : undefined;
+
+    const [hasListboxInside, setHasListboxInside] = useState(false);
+    const contentElement = useStoreState(store, "contentElement");
+
+    // We support nested <ComboboxList> elements (usually in the form of
+    // ComboboxPopover>ComboboxList), but we can't have nested listbox roles, so
+    // we check here if there's already a listbox element inside the current
+    // element.
+    useSafeLayoutEffect(() => {
+      if (!mounted) return;
+      const element = ref.current;
+      if (!element) return;
+      if (contentElement !== element) return;
+      const callback = () => {
+        setHasListboxInside(!!element.querySelector("[role='listbox']"));
+      };
+      const observer = new MutationObserver(callback);
+      observer.observe(element, {
+        subtree: true,
+        childList: true,
+        attributeFilter: ["role"],
+      });
+      callback();
+      return () => observer.disconnect();
+    }, [mounted, contentElement]);
+
+    if (!hasListboxInside) {
+      props = {
+        role: "listbox",
+        "aria-multiselectable": ariaMultiSelectable,
+        ...props,
+      };
+    }
+
+    props = useWrapElement(
+      props,
+      (element) => (
+        <ComboboxScopedContextProvider value={store}>
+          <ComboboxListRoleContext.Provider value={role}>
+            {element}
+          </ComboboxListRoleContext.Provider>
+        </ComboboxScopedContextProvider>
+      ),
+      [store, role],
+    );
+
+    // When nesting ComboboxList elements, the content element should be
+    // assigned to the topmost ComboboxList element.
+    const setContentElement =
+      id && (!scopedContext || !scopedContextSameStore)
+        ? store.setContentElement
+        : null;
+
+    props = {
+      hidden,
+      ...props,
+      id,
+      ref: useMergeRefs(setContentElement, ref, props.ref),
+      style,
+    };
+
+    return removeUndefinedValues(props);
+  },
+);
+
+/**
+ * Renders a combobox list. The `role` prop is set to `listbox` by default, but
+ * can be overriden by any other valid combobox popup role (`listbox`, `menu`,
+ * `tree`, `grid` or `dialog`).
+ * @see https://ariakit.com/components/combobox
+ * @example
+ * ```jsx {3-7}
+ * <ComboboxProvider>
+ *   <Combobox />
+ *   <ComboboxList>
+ *     <ComboboxItem value="Apple" />
+ *     <ComboboxItem value="Banana" />
+ *     <ComboboxItem value="Orange" />
+ *   </ComboboxList>
+ * </ComboboxProvider>
+ * ```
+ */
+export const ComboboxList = forwardRef(function ComboboxList(
+  props: ComboboxListProps,
+) {
+  const htmlProps = useComboboxList(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface ComboboxListOptions<T extends ElementType = TagName>
+  extends Options, Pick<DisclosureContentOptions<T>, "alwaysVisible"> {
+  /**
+   * Object returned by the
+   * [`useComboboxStore`](https://ariakit.com/reference/use-combobox-store)
+   * hook. If not provided, the closest
+   * [`ComboboxProvider`](https://ariakit.com/reference/combobox-provider)
+   * component's context will be used.
+   */
+  store?: ComboboxStore;
+}
+
+export type ComboboxListProps<T extends ElementType = TagName> = Props<
+  T,
+  ComboboxListOptions<T>
+>;