@ariakit/react-components 0.1.0

package/src/select/select-group.tsx

@@ -0,0 +1,79 @@
+import { createElement, createHook, forwardRef } from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import type { ElementType } from "react";
+import type { CompositeGroupOptions } from "../composite/composite-group.tsx";
+import { useCompositeGroup } from "../composite/composite-group.tsx";
+import type { SelectStore } from "./select-store.ts";
+
+const TagName = "div" satisfies ElementType;
+type TagName = typeof TagName;
+
+/**
+ * Returns props to create a `SelectGroup` component.
+ * @see https://ariakit.com/components/select
+ * @example
+ * ```jsx
+ * const store = useSelectStore();
+ * const props = useSelectGroup({ store });
+ * <Select store={store} />
+ * <SelectPopover store={store}>
+ *   <Role {...props}>
+ *     <SelectGroupLabel>Fruits</SelectGroupLabel>
+ *     <SelectItem value="Apple" />
+ *     <SelectItem value="Orange" />
+ *   </Role>
+ * </SelectPopover>
+ * ```
+ */
+export const useSelectGroup = createHook<TagName, SelectGroupOptions>(
+  function useSelectGroup(props) {
+    props = useCompositeGroup(props);
+    return props;
+  },
+);
+
+/**
+ * Renders a group for [`SelectItem`](https://ariakit.com/reference/select-item)
+ * elements. Optionally, a
+ * [`SelectGroupLabel`](https://ariakit.com/reference/select-group-label) can be
+ * rendered as a child to provide a label for the group.
+ * @see https://ariakit.com/components/select
+ * @example
+ * ```jsx {4-8}
+ * <SelectProvider>
+ *   <Select />
+ *   <SelectPopover>
+ *     <SelectGroup>
+ *       <SelectGroupLabel>Fruits</SelectGroupLabel>
+ *       <SelectItem value="Apple" />
+ *       <SelectItem value="Orange" />
+ *     </SelectGroup>
+ *   </SelectPopover>
+ * </SelectProvider>
+ * ```
+ */
+export const SelectGroup = forwardRef(function SelectGroup(
+  props: SelectGroupProps,
+) {
+  const htmlProps = useSelectGroup(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface SelectGroupOptions<
+  T extends ElementType = TagName,
+> extends CompositeGroupOptions<T> {
+  /**
+   * Object returned by the
+   * [`useSelectStore`](https://ariakit.com/reference/use-select-store) hook. If
+   * not provided, the parent
+   * [`SelectList`](https://ariakit.com/reference/select-list) or
+   * [`SelectPopover`](https://ariakit.com/reference/select-popover) components'
+   * context will be used.
+   */
+  store?: SelectStore;
+}
+
+export type SelectGroupProps<T extends ElementType = TagName> = Props<
+  T,
+  SelectGroupOptions<T>
+>;

package/src/select/select-heading.tsx

@@ -0,0 +1,98 @@
+import {
+  useId,
+  useSafeLayoutEffect,
+  createElement,
+  createHook,
+  forwardRef,
+} from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import type { ElementType } from "react";
+import { useContext } from "react";
+import type { PopoverHeadingOptions } from "../popover/popover-heading.tsx";
+import { usePopoverHeading } from "../popover/popover-heading.tsx";
+import { SelectHeadingContext } from "./select-context.tsx";
+import type { SelectStore } from "./select-store.ts";
+
+const TagName = "h1" satisfies ElementType;
+type TagName = typeof TagName;
+
+/**
+ * Returns props to create a `SelectHeading` component.
+ * @see https://ariakit.com/components/select
+ * @example
+ * ```jsx
+ * const props = useSelectHeading();
+ * <Role {...props}>Heading</Role>
+ * ```
+ */
+export const useSelectHeading = createHook<TagName, SelectHeadingOptions>(
+  function useSelectHeading(props) {
+    const [, setHeadingId] = useContext(SelectHeadingContext) || [];
+    const id = useId(props.id);
+
+    useSafeLayoutEffect(() => {
+      setHeadingId?.(id);
+      return () => setHeadingId?.(undefined);
+    }, [setHeadingId, id]);
+
+    props = {
+      ...props,
+      id,
+    };
+
+    props = usePopoverHeading(props);
+
+    return props;
+  },
+);
+
+/**
+ * Renders a heading element that serves as a label for
+ * [`SelectPopover`](https://ariakit.com/reference/select-popover) and
+ * [`SelectList`](https://ariakit.com/reference/select-list) components.
+ *
+ * When this component is rendered within
+ * [`SelectPopover`](https://ariakit.com/reference/select-popover), all
+ * [`SelectItem`](https://ariakit.com/reference/select-item) elements must be
+ * rendered within a [`SelectList`](https://ariakit.com/reference/select-list)
+ * instead of directly within the popover.
+ * @see https://ariakit.com/components/select
+ * @example
+ * ```jsx {4}
+ * <SelectProvider>
+ *   <Select />
+ *   <SelectPopover>
+ *     <SelectHeading>Fruits</SelectHeading>
+ *     <SelectList>
+ *       <SelectItem value="Apple" />
+ *       <SelectItem value="Orange" />
+ *     </SelectList>
+ *   </SelectPopover>
+ * </SelectProvider>
+ * ```
+ */
+export const SelectHeading = forwardRef(function SelectHeading(
+  props: SelectHeadingProps,
+) {
+  const htmlProps = useSelectHeading(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface SelectHeadingOptions<
+  T extends ElementType = TagName,
+> extends PopoverHeadingOptions<T> {
+  /**
+   * Object returned by the
+   * [`useSelectStore`](https://ariakit.com/reference/use-select-store) hook.
+   * If not provided, the closest
+   * [`Select`](https://ariakit.com/reference/select) or
+   * [`SelectProvider`](https://ariakit.com/reference/select-provider)
+   * components' context will be used.
+   */
+  store?: SelectStore;
+}
+
+export type SelectHeadingProps<T extends ElementType = TagName> = Props<
+  T,
+  SelectHeadingOptions<T>
+>;

package/src/select/select-item-check.tsx

@@ -0,0 +1,80 @@
+import { createElement, createHook, forwardRef } from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import type { ElementType } from "react";
+import { useContext } from "react";
+import type { CheckboxCheckOptions } from "../checkbox/checkbox-check.tsx";
+import { useCheckboxCheck } from "../checkbox/checkbox-check.tsx";
+import { SelectItemCheckedContext } from "./select-context.tsx";
+import type { SelectStore } from "./select-store.ts";
+
+const TagName = "span" satisfies ElementType;
+type TagName = typeof TagName;
+
+/**
+ * Returns props to create a `SelectItemCheck` component. This hook must be used
+ * in a component that's wrapped with `SelectItem` or the `checked` prop must be
+ * explicitly passed to the component.
+ * @see https://ariakit.com/components/select
+ * @example
+ * ```jsx
+ * const props = useSelectItemCheck({ checked: true });
+ * <Role {...props} />
+ * ```
+ */
+export const useSelectItemCheck = createHook<TagName, SelectItemCheckOptions>(
+  function useSelectItemCheck({ store, checked, ...props }) {
+    const context = useContext(SelectItemCheckedContext);
+    checked = checked ?? context;
+    props = useCheckboxCheck({ ...props, checked });
+    return props;
+  },
+);
+
+/**
+ * Renders a checkmark icon when the
+ * [`checked`](https://ariakit.com/reference/select-item-check#checked) prop is
+ * `true`. The icon can be overridden by providing a different one as children.
+ *
+ * When rendered inside a
+ * [`SelectItem`](https://ariakit.com/reference/select-item) component, the
+ * [`checked`](https://ariakit.com/reference/select-item-check#checked) prop is
+ * automatically derived from the context.
+ * @see https://ariakit.com/components/select
+ * @example
+ * ```jsx {5,9}
+ * <SelectProvider>
+ *   <Select />
+ *   <SelectPopover>
+ *     <SelectItem value="Apple">
+ *       <SelectItemCheck />
+ *       Apple
+ *     </SelectItem>
+ *     <SelectItem value="Orange">
+ *       <SelectItemCheck />
+ *       Orange
+ *     </SelectItem>
+ *   </SelectPopover>
+ * </SelectProvider>
+ * ```
+ */
+export const SelectItemCheck = forwardRef(function SelectItemCheck(
+  props: SelectItemCheckProps,
+) {
+  const htmlProps = useSelectItemCheck(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface SelectItemCheckOptions<
+  T extends ElementType = TagName,
+> extends CheckboxCheckOptions<T> {
+  /**
+   * Object returned by the
+   * [`useSelectStore`](https://ariakit.com/reference/use-select-store) hook.
+   */
+  store?: SelectStore;
+}
+
+export type SelectItemCheckProps<T extends ElementType = TagName> = Props<
+  T,
+  SelectItemCheckOptions<T>
+>;

package/src/select/select-item-offscreen.tsx

@@ -0,0 +1,59 @@
+import { useMergeRefs, forwardRef } from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import type { ElementType } from "react";
+import type { CompositeItemOptions } from "../composite/composite-item-offscreen.tsx";
+import { useCompositeItemOffscreen } from "../composite/composite-item-offscreen.tsx";
+import { Role } from "../role/role.tsx";
+import { useSelectScopedContext } from "./select-context.tsx";
+import * as Base from "./select-item.tsx";
+
+const TagName = "div" satisfies ElementType;
+type TagName = typeof TagName;
+
+export function useSelectItemOffscreen<
+  T extends ElementType,
+  // oxlint-disable-next-line no-unnecessary-type-parameters
+  P extends SelectItemProps<T>,
+>({ store, value, ...props }: P) {
+  const context = useSelectScopedContext();
+  store = store || context;
+  return useCompositeItemOffscreen({ store, value, ...props });
+}
+
+export const SelectItem = forwardRef(function SelectItem({
+  offscreenMode,
+  offscreenRoot,
+  ...props
+}: SelectItemProps) {
+  const { active, ref, ...rest } = useSelectItemOffscreen({
+    offscreenMode,
+    offscreenRoot,
+    ...props,
+  });
+  const allProps = { ...rest, ...props, ref: useMergeRefs(ref, props.ref) };
+  if (active) {
+    return <Base.SelectItem {...allProps} />;
+  }
+  // Remove SelectItem props
+  const {
+    store,
+    value,
+    getItem,
+    hideOnClick,
+    setValueOnClick,
+    preventScrollOnKeyDown,
+    focusOnHover,
+    blurOnHoverEnd,
+    ...htmlProps
+  } = allProps;
+  const Component = Role[TagName];
+  return <Component {...htmlProps} />;
+});
+
+export interface SelectItemOptions<T extends ElementType = TagName>
+  extends Base.SelectItemOptions<T>, Omit<CompositeItemOptions<T>, "store"> {}
+
+export type SelectItemProps<T extends ElementType = TagName> = Props<
+  T,
+  SelectItemOptions<T>
+>;

package/src/select/select-item.tsx

@@ -0,0 +1,294 @@
+import { useStoreState, useStoreStateObject } from "@ariakit/react-store";
+import {
+  useBooleanEvent,
+  useEvent,
+  useId,
+  useWrapElement,
+  createElement,
+  createHook,
+  forwardRef,
+  memo,
+} from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import {
+  getPopupItemRole,
+  isDownloading,
+  isOpeningInNewTab,
+  disabledFromProps,
+  invariant,
+} from "@ariakit/utils";
+import type { BooleanOrCallback } from "@ariakit/utils";
+import type { ElementType, MouseEvent } from "react";
+import { useCallback } 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 {
+  SelectItemCheckedContext,
+  useSelectScopedContext,
+} from "./select-context.tsx";
+import type { SelectStore } from "./select-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;
+}
+
+/**
+ * Returns props to create a `SelectItem` component.
+ * @see https://ariakit.com/components/select
+ * @example
+ * ```jsx
+ * const store = useSelectStore();
+ * const props = useSelectItem({ store, value: "Apple" });
+ * <Role {...props} />
+ * ```
+ */
+export const useSelectItem = createHook<TagName, SelectItemOptions>(
+  function useSelectItem({
+    store,
+    value,
+    getItem: getItemProp,
+    hideOnClick,
+    setValueOnClick = value != null,
+    preventScrollOnKeyDown = true,
+    focusOnHover = true,
+    ...props
+  }) {
+    const context = useSelectScopedContext();
+    store = store || context;
+
+    invariant(
+      store,
+      process.env.NODE_ENV !== "production" &&
+        "SelectItem must be wrapped in a SelectList or SelectPopover component.",
+    );
+
+    const id = useId(props.id);
+    const disabled = disabledFromProps(props);
+
+    const { listElement, multiSelectable, selected, autoFocus } =
+      useStoreStateObject(store, {
+        listElement: "listElement",
+        multiSelectable(state) {
+          return Array.isArray(state.value);
+        },
+        selected(state) {
+          return isSelected(state.value, value);
+        },
+        autoFocus(state) {
+          if (value == null) return false;
+          if (state.value == null) return false;
+          if (state.activeId !== id && store?.item(state.activeId)) {
+            return false;
+          }
+          if (Array.isArray(state.value)) {
+            return state.value[state.value.length - 1] === value;
+          }
+          return state.value === value;
+        },
+      });
+
+    const virtualFocus = useStoreState(store?.combobox, "virtualFocus");
+
+    const getItem = useCallback<NonNullable<CompositeItemOptions["getItem"]>>(
+      (item) => {
+        // When the item is disabled, we don't register its value.
+        const nextItem = {
+          ...item,
+          value: disabled ? undefined : value,
+        };
+        if (getItemProp) {
+          return getItemProp(nextItem);
+        }
+        return nextItem;
+      },
+      [disabled, value, getItemProp],
+    );
+
+    hideOnClick = hideOnClick ?? (value != null && !multiSelectable);
+
+    const onClickProp = props.onClick;
+    const setValueOnClickProp = useBooleanEvent(setValueOnClick);
+    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 (setValueOnClickProp(event) && value != null) {
+        store?.setValue((prevValue) => {
+          if (!Array.isArray(prevValue)) return value;
+          if (prevValue.includes(value)) {
+            return prevValue.filter((v) => v !== value);
+          }
+          return [...prevValue, value];
+        });
+      }
+      if (hideOnClickProp(event)) {
+        store?.hide();
+      }
+    });
+
+    props = useWrapElement(
+      props,
+      (element) => (
+        <SelectItemCheckedContext.Provider value={selected ?? false}>
+          {element}
+        </SelectItemCheckedContext.Provider>
+      ),
+      [selected],
+    );
+
+    const shouldAutoFocus = props.autoFocus ?? autoFocus;
+
+    props = {
+      role: getPopupItemRole(listElement),
+      "aria-selected": selected,
+      children: value,
+      ...props,
+      id,
+      // When virtualFocus is false (e.g., iOS Safari), we suppress autoFocus to
+      // prevent a re-mounted selected item from stealing focus from the
+      // combobox input (which dismisses the iOS keyboard). We keep
+      // data-autofocus so the dialog's initial focus effect can still find and
+      // focus this element. See https://github.com/ariakit/ariakit/issues/5047
+      autoFocus: virtualFocus === false ? false : shouldAutoFocus,
+      "data-autofocus": shouldAutoFocus || undefined,
+      onClick,
+    };
+
+    props = useCompositeItem<TagName>({
+      store,
+      getItem,
+      preventScrollOnKeyDown,
+      ...props,
+    });
+
+    const focusOnHoverProp = useBooleanEvent(focusOnHover);
+
+    props = useCompositeHover({
+      store,
+      ...props,
+      // We have to disable focusOnHover when the popup is closed, otherwise
+      // the active item will change to null (the container) when the popup is
+      // closed by clicking on an item.
+      focusOnHover(event) {
+        if (!focusOnHoverProp(event)) return false;
+        const state = store.getState();
+        return state.open;
+      },
+    });
+
+    return props;
+  },
+);
+
+/**
+ * Renders a select item inside a
+ * [`SelectList`](https://ariakit.com/reference/select-list) or
+ * [`SelectPopover`](https://ariakit.com/reference/select-popover).
+ *
+ * The `role` attribute will be automatically set on the item based on the
+ * list's own `role` attribute. For example, if the
+ * [`SelectPopover`](https://ariakit.com/reference/select-popover) component's
+ * `role` attribute is set to `listbox` (which is the default), the item `role`
+ * will be set to `option`.
+ *
+ * By default, the [`value`](https://ariakit.com/reference/select-item#value)
+ * prop will be rendered as the children, but this can be overriden if a custom
+ * children is provided.
+ * @see https://ariakit.com/components/select
+ * @example
+ * ```jsx {4-5}
+ * <SelectProvider>
+ *   <Select />
+ *   <SelectPopover>
+ *     <SelectItem value="Apple" />
+ *     <SelectItem value="Orange" />
+ *   </SelectPopover>
+ * </SelectProvider>
+ * ```
+ */
+export const SelectItem = memo(
+  forwardRef(function SelectItem(props: SelectItemProps) {
+    const htmlProps = useSelectItem(props);
+    return createElement(TagName, htmlProps);
+  }),
+);
+
+export interface SelectItemOptions<T extends ElementType = TagName>
+  extends CompositeItemOptions<T>, CompositeHoverOptions<T> {
+  /**
+   * Object returned by the
+   * [`useSelectStore`](https://ariakit.com/reference/use-select-store) hook. If
+   * not provided, the parent
+   * [`SelectList`](https://ariakit.com/reference/select-list) or
+   * [`SelectPopover`](https://ariakit.com/reference/select-popover) components'
+   * context will be used.
+   */
+  store?: SelectStore;
+  /**
+   * The value of the item. This will be rendered as the children by default.
+   * - If
+   *   [`setValueOnClick`](https://ariakit.com/reference/select-item#setvalueonclick)
+   *   is set to `true`, the
+   *   [`value`](https://ariakit.com/reference/select-provider#value) state will
+   *   be set to this value when the user clicks on it.
+   * - If
+   *   [`setValueOnMove`](https://ariakit.com/reference/select-provider#setvalueonmove)
+   *   is set to `true`, the
+   *   [`value`](https://ariakit.com/reference/select-provider#value) state will
+   *   be set to this value when the user moves to it (which is usually the case
+   *   when moving through the items using the keyboard).
+   *
+   * Live examples:
+   * - [Form with Select](https://ariakit.com/examples/form-select)
+   * - [Animated Select](https://ariakit.com/examples/select-animated)
+   * - [Select with Combobox](https://ariakit.com/examples/select-combobox)
+   * - [Select Grid](https://ariakit.com/examples/select-grid)
+   * - [SelectGroup](https://ariakit.com/examples/select-group)
+   * - [Select with custom
+   *   item](https://ariakit.com/examples/select-item-custom)
+   * @example
+   * ```jsx
+   * <SelectItem value="Apple" />
+   * ```
+   */
+  value?: string;
+  /**
+   * Whether to hide the select when this item is clicked. By default, it's
+   * `true` when the [`value`](https://ariakit.com/reference/select-item#value)
+   * prop is also provided.
+   */
+  hideOnClick?: BooleanOrCallback<MouseEvent<HTMLElement>>;
+  /**
+   * Whether to set the select value with this item's value, if any, when this
+   * item is clicked. By default, it's `true` when the
+   * [`value`](https://ariakit.com/reference/select-item#value) prop is also
+   * provided.
+   *
+   * Live examples:
+   * - [Select with Next.js App
+   *   Router](https://ariakit.com/examples/select-next-router)
+   */
+  setValueOnClick?: BooleanOrCallback<MouseEvent<HTMLElement>>;
+}
+
+export type SelectItemProps<T extends ElementType = TagName> = Props<
+  T,
+  SelectItemOptions<T>
+>;