@ariakit/react-components 0.1.0

package/src/collection/collection-store.ts

@@ -0,0 +1,84 @@
+import * as Core from "@ariakit/components/collection/collection-store";
+import { useStore, useStoreProps } from "@ariakit/react-store";
+import type { Store } from "@ariakit/react-store";
+import { useUpdateEffect } from "@ariakit/react-utils";
+import type { BivariantCallback, PickRequired } from "@ariakit/utils";
+
+export function useCollectionStoreProps<T extends Core.CollectionStore>(
+  store: T,
+  update: () => void,
+  props: CollectionStoreProps,
+) {
+  useUpdateEffect(update, [props.store]);
+  useStoreProps(store, props, "items", "setItems");
+  return store;
+}
+
+/**
+ * Creates a collection store to control
+ * [Collection](https://ariakit.com/components/collection) components.
+ * @see https://ariakit.com/components/collection
+ * @example
+ * ```jsx
+ * const collection = useCollectionStore();
+ *
+ * <Collection store={collection}>
+ *   <CollectionItem>Item</CollectionItem>
+ *   <CollectionItem>Item</CollectionItem>
+ *   <CollectionItem>Item</CollectionItem>
+ * </Collection>
+ * ```
+ */
+
+export function useCollectionStore<
+  T extends CollectionStoreItem = CollectionStoreItem,
+>(
+  props: PickRequired<CollectionStoreProps<T>, "items" | "defaultItems">,
+): CollectionStore<T>;
+
+export function useCollectionStore(
+  props?: CollectionStoreProps,
+): CollectionStore;
+
+export function useCollectionStore(
+  props: CollectionStoreProps = {},
+): CollectionStore {
+  const [store, update] = useStore(Core.createCollectionStore, props);
+  return useCollectionStoreProps(store, update, props);
+}
+
+export interface CollectionStoreItem extends Core.CollectionStoreItem {}
+
+export interface CollectionStoreState<
+  T extends CollectionStoreItem = CollectionStoreItem,
+> extends Core.CollectionStoreState<T> {}
+
+export interface CollectionStoreFunctions<
+  T extends CollectionStoreItem = CollectionStoreItem,
+> extends Core.CollectionStoreFunctions<T> {}
+
+export interface CollectionStoreOptions<
+  T extends CollectionStoreItem = CollectionStoreItem,
+> extends Core.CollectionStoreOptions<T> {
+  /**
+   * A callback that gets called when the
+   * [`items`](https://ariakit.com/reference/collection-provider#items) state
+   * changes.
+   * @example
+   * const [items, setItems] = useState([]);
+   * const collection = useCollectionStore({ items, setItems });
+   */
+  setItems?: BivariantCallback<
+    (items: CollectionStoreState<T>["items"]) => void
+  >;
+}
+
+export interface CollectionStoreProps<
+  T extends CollectionStoreItem = CollectionStoreItem,
+>
+  extends CollectionStoreOptions<T>, Core.CollectionStoreProps<T> {}
+
+export interface CollectionStore<
+  T extends CollectionStoreItem = CollectionStoreItem,
+>
+  extends CollectionStoreFunctions<T>, Store<Core.CollectionStore<T>> {}

package/src/collection/collection.tsx

@@ -0,0 +1,93 @@
+import {
+  useWrapElement,
+  createElement,
+  createHook,
+  forwardRef,
+} from "@ariakit/react-utils";
+import type { Options, Props } from "@ariakit/react-utils";
+import { removeUndefinedValues } from "@ariakit/utils";
+import type { ElementType } from "react";
+import {
+  CollectionScopedContextProvider,
+  useCollectionProviderContext,
+} from "./collection-context.tsx";
+import type { CollectionStore } from "./collection-store.ts";
+
+const TagName = "div" satisfies ElementType;
+type TagName = typeof TagName;
+
+/**
+ * Returns props to create a `Collection` component. It receives the collection
+ * store through the `store` prop and provides context for `CollectionItem`
+ * components.
+ * @see https://ariakit.com/components/collection
+ * @example
+ * ```jsx
+ * const collection = useCollectionStore();
+ * const props = useCollection({ store });
+ * <Role {...props}>
+ *   <CollectionItem>Item 1</CollectionItem>
+ *   <CollectionItem>Item 2</CollectionItem>
+ *   <CollectionItem>Item 3</CollectionItem>
+ * </Role>
+ * ```
+ */
+export const useCollection = createHook<TagName, CollectionOptions>(
+  function useCollection({ store, ...props }) {
+    const context = useCollectionProviderContext();
+    store = store || context;
+
+    props = useWrapElement(
+      props,
+      (element) => (
+        <CollectionScopedContextProvider value={store}>
+          {element}
+        </CollectionScopedContextProvider>
+      ),
+      [store],
+    );
+
+    return removeUndefinedValues(props);
+  },
+);
+
+/**
+ * Renders a simple wrapper for collection items. It accepts a collection store
+ * through the [`store`](https://ariakit.com/reference/collection#store) prop
+ * and provides context for
+ * [`CollectionItem`](https://ariakit.com/reference/collection-item) components.
+ * @see https://ariakit.com/components/collection
+ * @example
+ * ```jsx
+ * const collection = useCollectionStore();
+ * <Collection store={collection}>
+ *   <CollectionItem>Item 1</CollectionItem>
+ *   <CollectionItem>Item 2</CollectionItem>
+ *   <CollectionItem>Item 3</CollectionItem>
+ * </Collection>
+ * ```
+ */
+export const Collection = forwardRef(function Collection(
+  props: CollectionProps,
+) {
+  const htmlProps = useCollection(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface CollectionOptions<
+  _T extends ElementType = TagName,
+> extends Options {
+  /**
+   * Object returned by the
+   * [`useCollectionStore`](https://ariakit.com/reference/use-collection-store)
+   * hook. If not provided, the closest
+   * [`CollectionProvider`](https://ariakit.com/reference/collection-provider)
+   * component's context will be used.
+   */
+  store?: CollectionStore;
+}
+
+export type CollectionProps<T extends ElementType = TagName> = Props<
+  T,
+  CollectionOptions<T>
+>;

package/src/combobox/combobox-cancel.tsx

@@ -0,0 +1,153 @@
+import { useStoreState } from "@ariakit/react-store";
+import {
+  useEvent,
+  useWrapElement,
+  createElement,
+  createHook,
+  forwardRef,
+} from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import { invariant } from "@ariakit/utils";
+import type { ElementType, MouseEvent } from "react";
+import { Fragment } from "react";
+import type { ButtonOptions } from "../button/button.tsx";
+import { useButton } from "../button/button.tsx";
+import { useComboboxProviderContext } from "./combobox-context.tsx";
+import type { ComboboxStore } from "./combobox-store.ts";
+
+const TagName = "button" satisfies ElementType;
+type TagName = typeof TagName;
+type HTMLType = HTMLElementTagNameMap[TagName];
+
+const children = (
+  <svg
+    aria-hidden="true"
+    display="block"
+    viewBox="0 0 16 16"
+    fill="none"
+    stroke="currentColor"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    strokeWidth={1.5}
+    width="1em"
+    height="1em"
+    pointerEvents="none"
+  >
+    <line x1="5" y1="5" x2="11" y2="11" />
+    <line x1="5" y1="11" x2="11" y2="5" />
+  </svg>
+);
+
+/**
+ * Returns props to create a `ComboboxCancel` component that clears the combobox
+ * input when clicked.
+ * @see https://ariakit.com/components/combobox
+ * @example
+ * ```jsx
+ * const store = useComboboxStore();
+ * const props = useComboboxCancel({ store });
+ * <Combobox store={store} />
+ * <Role {...props} />
+ * ```
+ */
+export const useComboboxCancel = createHook<TagName, ComboboxCancelOptions>(
+  function useComboboxCancel({ store, hideWhenEmpty, ...props }) {
+    const context = useComboboxProviderContext();
+    store = store || context;
+
+    invariant(
+      store,
+      process.env.NODE_ENV !== "production" &&
+        "ComboboxCancel must receive a `store` prop or be wrapped in a ComboboxProvider component.",
+    );
+
+    const onClickProp = props.onClick;
+
+    const onClick = useEvent((event: MouseEvent<HTMLType>) => {
+      onClickProp?.(event);
+      if (event.defaultPrevented) return;
+      store?.setValue("");
+      // Move focus to the combobox input.
+      store?.move(null);
+    });
+
+    const comboboxId = useStoreState(store, (state) => state.baseElement?.id);
+    const empty = useStoreState(store, (state) => state.value === "");
+
+    props = useWrapElement(
+      props,
+      (element) => {
+        if (!hideWhenEmpty) return element;
+        if (empty) return <Fragment />;
+        return element;
+      },
+      [hideWhenEmpty, empty],
+    );
+
+    props = {
+      children,
+      "aria-label": "Clear input",
+      // This aria-controls will ensure the combobox popup remains visible when
+      // this element gets focused. This logic is done in the ComboboxPopover
+      // component.
+      "aria-controls": comboboxId,
+      ...props,
+      onClick,
+    };
+
+    props = useButton(props);
+
+    return props;
+  },
+);
+
+/**
+ * Renders a combobox cancel button that clears the combobox input value when
+ * clicked.
+ * @see https://ariakit.com/components/combobox
+ * @example
+ * ```jsx {3}
+ * <ComboboxProvider>
+ *   <Combobox />
+ *   <ComboboxCancel />
+ *   <ComboboxPopover>
+ *     <ComboboxItem value="Apple" />
+ *     <ComboboxItem value="Banana" />
+ *     <ComboboxItem value="Orange" />
+ *   </ComboboxPopover>
+ * </ComboboxProvider>
+ * ```
+ */
+export const ComboboxCancel = forwardRef(function ComboboxCancel(
+  props: ComboboxCancelProps,
+) {
+  const htmlProps = useComboboxCancel(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface ComboboxCancelOptions<
+  T extends ElementType = TagName,
+> extends ButtonOptions<T> {
+  /**
+   * 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;
+  /**
+   * When enabled, the button won't be rendered when the combobox input value is
+   * empty.
+   *
+   * Live examples:
+   * - [Combobox with Tabs](https://ariakit.com/examples/combobox-tabs)
+   * @default false
+   */
+  hideWhenEmpty?: boolean;
+}
+
+export type ComboboxCancelProps<T extends ElementType = TagName> = Props<
+  T,
+  ComboboxCancelOptions<T>
+>;

package/src/combobox/combobox-context.tsx

@@ -0,0 +1,49 @@
+import { createStoreContext } from "@ariakit/react-utils";
+import { createContext } from "react";
+import {
+  CompositeContextProvider,
+  CompositeScopedContextProvider,
+} from "../composite/composite-context.tsx";
+import {
+  PopoverContextProvider,
+  PopoverScopedContextProvider,
+} from "../popover/popover-context.tsx";
+import type { ComboboxStore } from "./combobox-store.ts";
+
+export const ComboboxListRoleContext = createContext<string | undefined>(
+  undefined,
+);
+
+const ctx = createStoreContext<ComboboxStore>(
+  [PopoverContextProvider, CompositeContextProvider],
+  [PopoverScopedContextProvider, CompositeScopedContextProvider],
+);
+
+/**
+ * Returns the combobox store from the nearest combobox container.
+ * @example
+ * function Combobox() {
+ *   const store = useComboboxContext();
+ *
+ *   if (!store) {
+ *     throw new Error("Combobox must be wrapped in ComboboxProvider");
+ *   }
+ *
+ *   // Use the store...
+ * }
+ */
+export const useComboboxContext = ctx.useContext;
+
+export const useComboboxScopedContext = ctx.useScopedContext;
+
+export const useComboboxProviderContext = ctx.useProviderContext;
+
+export const ComboboxContextProvider = ctx.ContextProvider;
+
+export const ComboboxScopedContextProvider = ctx.ScopedContextProvider;
+
+export const ComboboxItemValueContext = createContext<string | undefined>(
+  undefined,
+);
+
+export const ComboboxItemCheckedContext = createContext(false);

package/src/combobox/combobox-disclosure.tsx

@@ -0,0 +1,162 @@
+import { useStoreState } from "@ariakit/react-store";
+import {
+  useEvent,
+  useSafeLayoutEffect,
+  createElement,
+  createHook,
+  forwardRef,
+} from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import { invariant } from "@ariakit/utils";
+import type { ElementType, MouseEvent } from "react";
+import type { DialogDisclosureOptions } from "../dialog/dialog-disclosure.tsx";
+import { useDialogDisclosure } from "../dialog/dialog-disclosure.tsx";
+import { useComboboxProviderContext } from "./combobox-context.tsx";
+import type { ComboboxStore } from "./combobox-store.ts";
+
+const TagName = "button" satisfies ElementType;
+type TagName = typeof TagName;
+type HTMLType = HTMLElementTagNameMap[TagName];
+
+const children = (
+  <svg
+    aria-hidden="true"
+    display="block"
+    fill="none"
+    stroke="currentColor"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    strokeWidth={1.5}
+    viewBox="0 0 16 16"
+    height="1em"
+    width="1em"
+    pointerEvents="none"
+  >
+    <polyline points="4,6 8,10 12,6" />
+  </svg>
+);
+
+/**
+ * Returns props to create a `ComboboxDisclosure` component that toggles the
+ * combobox popover visibility when clicked.
+ * @see https://ariakit.com/components/combobox
+ * @example
+ * ```jsx
+ * const store = useComboboxStore();
+ * const props = useComboboxDisclosure({ store });
+ * <Combobox store={store} />
+ * <Role {...props} />
+ * <ComboboxPopover store={store}>
+ *   <ComboboxItem value="Item 1" />
+ *   <ComboboxItem value="Item 2" />
+ *   <ComboboxItem value="Item 3" />
+ * </ComboboxPopover>
+ * ```
+ */
+export const useComboboxDisclosure = createHook<
+  TagName,
+  ComboboxDisclosureOptions
+>(function useComboboxDisclosure({ store, ...props }) {
+  const context = useComboboxProviderContext();
+  store = store || context;
+
+  invariant(
+    store,
+    process.env.NODE_ENV !== "production" &&
+      "ComboboxDisclosure must receive a `store` prop or be wrapped in a ComboboxProvider component.",
+  );
+
+  const onMouseDownProp = props.onMouseDown;
+
+  const onMouseDown = useEvent((event: MouseEvent<HTMLType>) => {
+    onMouseDownProp?.(event);
+    // We have to prevent the element from getting focused on mousedown.
+    event.preventDefault();
+    // This will immediately move focus to the combobox input.
+    store?.move(null);
+  });
+
+  const onClickProp = props.onClick;
+
+  const onClick = useEvent((event: MouseEvent<HTMLType>) => {
+    onClickProp?.(event);
+    if (event.defaultPrevented) return;
+    if (!store) return;
+    const { baseElement } = store.getState();
+    store.setDisclosureElement(baseElement);
+  });
+
+  const baseElement = useStoreState(store, "baseElement");
+  const open = useStoreState(store, "open");
+
+  // The combobox input should remain the disclosure element so focus and Escape
+  // handling keep working when the popover is already open on mount.
+  useSafeLayoutEffect(() => {
+    if (!baseElement) return;
+    store.setDisclosureElement(baseElement);
+  }, [store, baseElement]);
+
+  props = {
+    children,
+    tabIndex: -1,
+    "aria-label": open ? "Hide popup" : "Show popup",
+    "aria-expanded": open,
+    ...props,
+    onMouseDown,
+    onClick,
+  };
+
+  // We're using DialogDisclosure, and not PopoverDisclosure, because
+  // PopoverDisclosure will also update the `store.anchorRef` with the
+  // disclosure element. We need to keep the combobox input as the anchorRef.
+  props = useDialogDisclosure({ store, ...props });
+
+  return props;
+});
+
+/**
+ * Renders a combobox disclosure button that toggles the
+ * [`ComboboxPopover`](https://ariakit.com/reference/combobox-popover) element's
+ * visibility when clicked.
+ *
+ * Although this button is not tabbable, it remains accessible to screen reader
+ * users. On clicking, it automatically shifts focus to the
+ * [`Combobox`](https://ariakit.com/reference/combobox) element.
+ * @see https://ariakit.com/components/combobox
+ * @example
+ * ```jsx {3}
+ * <ComboboxProvider>
+ *   <Combobox />
+ *   <ComboboxDisclosure />
+ *   <ComboboxPopover>
+ *     <ComboboxItem value="Apple" />
+ *     <ComboboxItem value="Banana" />
+ *     <ComboboxItem value="Orange" />
+ *   </ComboboxPopover>
+ * </ComboboxProvider>
+ * ```
+ */
+export const ComboboxDisclosure = forwardRef(function ComboboxDisclosure(
+  props: ComboboxDisclosureProps,
+) {
+  const htmlProps = useComboboxDisclosure(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface ComboboxDisclosureOptions<
+  T extends ElementType = TagName,
+> extends DialogDisclosureOptions<T> {
+  /**
+   * 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 ComboboxDisclosureProps<T extends ElementType = TagName> = Props<
+  T,
+  ComboboxDisclosureOptions<T>
+>;

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

@@ -0,0 +1,74 @@
+import { createElement, createHook, forwardRef } from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import type { ElementType } from "react";
+import type { CompositeGroupLabelOptions } from "../composite/composite-group-label.tsx";
+import { useCompositeGroupLabel } from "../composite/composite-group-label.tsx";
+import type { ComboboxStore } from "./combobox-store.ts";
+
+const TagName = "div" satisfies ElementType;
+type TagName = typeof TagName;
+
+/**
+ * Returns props to create a `ComboboxGroupLabel` component. This hook should be
+ * used in a component that's wrapped with `ComboboxGroup` so the
+ * `aria-labelledby` is correctly set on the combobox group element.
+ * @see https://ariakit.com/components/combobox
+ * @example
+ * ```jsx
+ * // This component should be wrapped with ComboboxGroup
+ * const props = useComboboxGroupLabel();
+ * <Role {...props}>Label</Role>
+ * ```
+ */
+export const useComboboxGroupLabel = createHook<
+  TagName,
+  ComboboxGroupLabelOptions
+>(function useComboboxGroupLabel(props) {
+  props = useCompositeGroupLabel(props);
+  return props;
+});
+
+/**
+ * Renders a label in a combobox group. This component should be wrapped with
+ * [`ComboboxGroup`](https://ariakit.com/reference/combobox-group) so the
+ * `aria-labelledby` is correctly set on the group element.
+ * @see https://ariakit.com/components/combobox
+ * @example
+ * ```jsx {5}
+ * <ComboboxProvider>
+ *   <Combobox />
+ *   <ComboboxPopover>
+ *     <ComboboxGroup>
+ *       <ComboboxGroupLabel>Fruits</ComboboxGroupLabel>
+ *       <ComboboxItem value="Apple" />
+ *       <ComboboxItem value="Banana" />
+ *     </ComboboxGroup>
+ *   </ComboboxPopover>
+ * </ComboboxProvider>
+ * ```
+ */
+export const ComboboxGroupLabel = forwardRef(function ComboboxGroupLabel(
+  props: ComboboxGroupLabelProps,
+) {
+  const htmlProps = useComboboxGroupLabel(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface ComboboxGroupLabelOptions<
+  T extends ElementType = TagName,
+> extends CompositeGroupLabelOptions<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.
+   */
+  store?: ComboboxStore;
+}
+
+export type ComboboxGroupLabelProps<T extends ElementType = TagName> = Props<
+  T,
+  ComboboxGroupLabelOptions<T>
+>;