@ariakit/react-components 0.1.0

package/readme.md

@@ -0,0 +1,19 @@
+# Ariakit React Components
+
+**Important:** This package is an internal dependency of Ariakit and does not follow semantic versioning, meaning breaking changes may occur in patch and minor versions. You probably want to use [`@ariakit/react`](https://npmjs.org/package/@ariakit/react) instead.
+
+## Installation
+
+```
+npm i @ariakit/react-components
+```
+
+## Core Team
+
+- [Diego Haz](https://bsky.app/profile/haz.dev)
+- [Ben Rodri](https://bsky.app/profile/ben.ariakit.org)
+- [Dani Guardiola](https://bsky.app/profile/dio.la)
+
+## Contributing
+
+Follow the instructions on the [contributing guide](https://github.com/ariakit/ariakit/blob/main/contributing.md).

package/src/button/button.tsx

@@ -0,0 +1,76 @@
+import {
+  useMergeRefs,
+  useTagName,
+  createElement,
+  createHook,
+  forwardRef,
+} from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import { isButton } from "@ariakit/utils";
+import type { ElementType } from "react";
+import { useEffect, useRef, useState } from "react";
+import type { CommandOptions } from "../command/command.tsx";
+import { useCommand } from "../command/command.tsx";
+
+const TagName = "button" satisfies ElementType;
+type TagName = typeof TagName;
+type HTMLType = HTMLElementTagNameMap[TagName];
+
+/**
+ * Returns props to create a `Button` component. If the element is not a native
+ * button, the hook will return additional props to make sure it's accessible.
+ * @see https://ariakit.com/components/button
+ * @example
+ * ```jsx
+ * const props = useButton({ render: <div /> });
+ * <Role {...props}>Accessible button</Role>
+ * ```
+ */
+export const useButton = createHook<TagName, ButtonOptions>(
+  function useButton(props) {
+    const ref = useRef<HTMLType>(null);
+    const tagName = useTagName(ref, TagName);
+    const [isNativeButton, setIsNativeButton] = useState(
+      () => !!tagName && isButton({ tagName, type: props.type }),
+    );
+
+    useEffect(() => {
+      if (!ref.current) return;
+      setIsNativeButton(isButton(ref.current));
+    }, []);
+
+    props = {
+      role: !isNativeButton && tagName !== "a" ? "button" : undefined,
+      ...props,
+      ref: useMergeRefs(ref, props.ref),
+    };
+
+    props = useCommand(props);
+
+    return props;
+  },
+);
+
+/**
+ * Renders an accessible button element. If the underlying element is not a
+ * native button, this component will pass additional attributes to make sure
+ * it's accessible.
+ * @see https://ariakit.com/components/button
+ * @example
+ * ```jsx
+ * <Button>Button</Button>
+ * ```
+ */
+export const Button = forwardRef(function Button(props: ButtonProps) {
+  const htmlProps = useButton(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface ButtonOptions<
+  T extends ElementType = TagName,
+> extends CommandOptions<T> {}
+
+export type ButtonProps<T extends ElementType = TagName> = Props<
+  T,
+  ButtonOptions<T>
+>;

package/src/checkbox/checkbox-check.tsx

@@ -0,0 +1,116 @@
+import { 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 { useContext } from "react";
+import { CheckboxCheckedContext } from "./checkbox-checked-context.tsx";
+import type { CheckboxStore } from "./checkbox-store.ts";
+
+const TagName = "span" satisfies ElementType;
+type TagName = typeof TagName;
+
+const checkmark = (
+  <svg
+    display="block"
+    fill="none"
+    stroke="currentColor"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    strokeWidth={1.5}
+    viewBox="0 0 16 16"
+    height="1em"
+    width="1em"
+  >
+    <polyline points="4,8 7,12 12,4" />
+  </svg>
+);
+
+function getChildren(props: Pick<CheckboxCheckProps, "checked" | "children">) {
+  if (props.checked) {
+    return props.children || checkmark;
+  }
+  if (typeof props.children === "function") {
+    return props.children;
+  }
+  return null;
+}
+
+/**
+ * Returns props to create a `CheckboxCheck` component, that's usually rendered
+ * inside a `Checkbox` component.
+ * @see https://ariakit.com/components/checkbox
+ * @example
+ * ```jsx
+ * const props = useCheckboxCheck({ checked: true });
+ * <Role {...props} />
+ * ```
+ */
+export const useCheckboxCheck = createHook<TagName, CheckboxCheckOptions>(
+  function useCheckboxCheck({ store, checked, ...props }) {
+    const context = useContext(CheckboxCheckedContext);
+    checked = checked ?? context;
+    const children = getChildren({ checked, children: props.children });
+
+    props = {
+      "aria-hidden": true,
+      ...props,
+      children,
+      style: {
+        width: "1em",
+        height: "1em",
+        pointerEvents: "none",
+        ...props.style,
+      },
+    };
+
+    return removeUndefinedValues(props);
+  },
+);
+
+/**
+ * Renders a checkmark icon when the
+ * [`checked`](https://ariakit.com/reference/checkbox-check#checked) prop is
+ * `true`. The icon can be overridden by providing a different one as children.
+ *
+ * When rendered inside a [`Checkbox`](https://ariakit.com/reference/checkbox)
+ * component, the
+ * [`checked`](https://ariakit.com/reference/checkbox-check#checked) prop is
+ * automatically derived from the context.
+ * @see https://ariakit.com/components/checkbox
+ * @example
+ * ```jsx
+ * <CheckboxCheck checked />
+ * ```
+ */
+export const CheckboxCheck = forwardRef(function CheckboxCheck(
+  props: CheckboxCheckProps,
+) {
+  const htmlProps = useCheckboxCheck(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface CheckboxCheckOptions<
+  _T extends ElementType = TagName,
+> extends Options {
+  /**
+   * Object returned by the
+   * [`useCheckboxStore`](https://ariakit.com/reference/use-checkbox-store)
+   * hook.
+   */
+  store?: CheckboxStore;
+  /**
+   * Determines if the checkmark should be rendered. This value is automatically
+   * derived from the context when it exists. Manually setting this prop will
+   * supersede the derived value.
+   *
+   * Live examples:
+   * - [Submenu with
+   *   Combobox](https://ariakit.com/examples/menu-nested-combobox)
+   */
+  checked?: boolean;
+}
+
+export type CheckboxCheckProps<T extends ElementType = TagName> = Props<
+  T,
+  CheckboxCheckOptions<T>
+>;

package/src/checkbox/checkbox-checked-context.tsx

@@ -0,0 +1,3 @@
+import { createContext } from "react";
+
+export const CheckboxCheckedContext = createContext(false);

package/src/checkbox/checkbox-context.tsx

@@ -0,0 +1,27 @@
+import { createStoreContext } from "@ariakit/react-utils";
+import type { CheckboxStore } from "./checkbox-store.ts";
+
+const ctx = createStoreContext<CheckboxStore>();
+
+/**
+ * Returns the checkbox store from the nearest checkbox container.
+ * @example
+ * function Checkbox() {
+ *   const store = useCheckboxContext();
+ *
+ *   if (!store) {
+ *     throw new Error("Checkbox must be wrapped in CheckboxProvider");
+ *   }
+ *
+ *   // Use the store...
+ * }
+ */
+export const useCheckboxContext = ctx.useContext;
+
+export const useCheckboxScopedContext = ctx.useScopedContext;
+
+export const useCheckboxProviderContext = ctx.useProviderContext;
+
+export const CheckboxContextProvider = ctx.ContextProvider;
+
+export const CheckboxScopedContextProvider = ctx.ScopedContextProvider;

package/src/checkbox/checkbox-provider.tsx

@@ -0,0 +1,53 @@
+import type { PickRequired } from "@ariakit/utils";
+import type { ReactElement, ReactNode } from "react";
+import { CheckboxContextProvider } from "./checkbox-context.tsx";
+import type {
+  CheckboxStoreProps,
+  CheckboxStoreValue,
+} from "./checkbox-store.ts";
+import { useCheckboxStore } from "./checkbox-store.ts";
+
+type Value = CheckboxStoreValue;
+
+/**
+ * Provides a checkbox store for its descendants. This comes in handy when
+ * creating a group of checkboxes that share the same state. `CheckboxProvider`
+ * can efficiently manage the value of a checkbox, whether it's a single string,
+ * number, or boolean value, or an array of such values.
+ * @see https://ariakit.com/components/checkbox
+ * @example
+ * ```jsx
+ * <CheckboxProvider defaultValue={["orange"]}>
+ *   <label>
+ *     <Checkbox value="apple" /> Apple
+ *   </label>
+ *   <label>
+ *     <Checkbox value="orange" /> Orange
+ *   </label>
+ *   <label>
+ *     <Checkbox value="mango" /> Mango
+ *   </label>
+ * </CheckboxProvider>
+ * ```
+ */
+
+export function CheckboxProvider<T extends Value = Value>(
+  props: PickRequired<CheckboxProviderProps<T>, "value" | "defaultValue">,
+): ReactElement;
+
+export function CheckboxProvider(props?: CheckboxProviderProps): ReactElement;
+
+export function CheckboxProvider(props: CheckboxProviderProps = {}) {
+  const store = useCheckboxStore(props);
+  return (
+    <CheckboxContextProvider value={store}>
+      {props.children}
+    </CheckboxContextProvider>
+  );
+}
+
+export interface CheckboxProviderProps<
+  T extends Value = Value,
+> extends CheckboxStoreProps<T> {
+  children?: ReactNode;
+}

package/src/checkbox/checkbox-store.ts

@@ -0,0 +1,76 @@
+import * as Core from "@ariakit/components/checkbox/checkbox-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 useCheckboxStoreProps<T extends Core.CheckboxStore>(
+  store: T,
+  update: () => void,
+  props: CheckboxStoreProps,
+) {
+  useUpdateEffect(update, [props.store]);
+  useStoreProps(store, props, "value", "setValue");
+  return store;
+}
+
+/**
+ * Creates a checkbox store to conveniently manage a checkbox value,
+ * whether it's a string, number, boolean, or an array of strings or numbers.
+ * @see https://ariakit.com/components/checkbox
+ * @example
+ * ```jsx
+ * const checkbox = useCheckboxStore({ defaultValue: true });
+ * <Checkbox store={checkbox} />
+ * ```
+ */
+
+export function useCheckboxStore<
+  T extends CheckboxStoreValue = CheckboxStoreValue,
+>(
+  props: PickRequired<CheckboxStoreProps<T>, "value" | "defaultValue">,
+): CheckboxStore<T>;
+
+export function useCheckboxStore(props?: CheckboxStoreProps): CheckboxStore;
+
+export function useCheckboxStore(
+  props: CheckboxStoreProps = {},
+): CheckboxStore {
+  const [store, update] = useStore(Core.createCheckboxStore, props);
+  return useCheckboxStoreProps(store, update, props);
+}
+
+export type CheckboxStoreValue = Core.CheckboxStoreValue;
+
+export type CheckboxStoreState<
+  T extends CheckboxStoreValue = CheckboxStoreValue,
+> = Core.CheckboxStoreState<T>;
+
+export type CheckboxStoreFunctions<
+  T extends CheckboxStoreValue = CheckboxStoreValue,
+> = Core.CheckboxStoreFunctions<T>;
+
+export interface CheckboxStoreOptions<
+  T extends CheckboxStoreValue = CheckboxStoreValue,
+> extends Core.CheckboxStoreOptions<T> {
+  /**
+   * A callback that gets called when the
+   * [`value`](https://ariakit.com/reference/checkbox-provider#value) state
+   * changes.
+   * @example
+   * function MyCheckbox({ value, onChange }) {
+   *   const checkbox = useCheckboxStore({ value, setValue: onChange });
+   * }
+   */
+  setValue?: BivariantCallback<(value: CheckboxStoreState<T>["value"]) => void>;
+}
+
+export interface CheckboxStoreProps<
+  T extends CheckboxStoreValue = CheckboxStoreValue,
+>
+  extends CheckboxStoreOptions<T>, Core.CheckboxStoreProps<T> {}
+
+export interface CheckboxStore<
+  T extends CheckboxStoreValue = CheckboxStoreValue,
+>
+  extends CheckboxStoreFunctions<T>, Store<Core.CheckboxStore<T>> {}

package/src/checkbox/checkbox.tsx

@@ -0,0 +1,271 @@
+import { useStoreState } from "@ariakit/react-store";
+import {
+  useEvent,
+  useForceUpdate,
+  useMergeRefs,
+  useTagName,
+  useWrapElement,
+  createElement,
+  createHook,
+  forwardRef,
+} from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import { disabledFromProps, removeUndefinedValues } from "@ariakit/utils";
+import type {
+  ChangeEvent,
+  ComponentPropsWithoutRef,
+  ElementType,
+  MouseEvent,
+} from "react";
+import { useEffect, useRef, useState } from "react";
+import type { CommandOptions } from "../command/command.tsx";
+import { useCommand } from "../command/command.tsx";
+import { CheckboxCheckedContext } from "./checkbox-checked-context.tsx";
+import { useCheckboxContext } from "./checkbox-context.tsx";
+import type { CheckboxStore } from "./checkbox-store.ts";
+
+const TagName = "input" satisfies ElementType;
+type TagName = typeof TagName;
+type HTMLType = HTMLElementTagNameMap[TagName];
+
+function setMixed(element: HTMLType, mixed?: boolean) {
+  if (mixed) {
+    element.indeterminate = true;
+  } else if (element.indeterminate) {
+    element.indeterminate = false;
+  }
+}
+
+function isNativeCheckbox(tagName?: string, type?: string) {
+  return tagName === "input" && (!type || type === "checkbox");
+}
+
+function getPrimitiveValue<T>(value: T) {
+  if (Array.isArray(value)) {
+    return value.toString();
+  }
+  return value as Exclude<T, readonly any[]>;
+}
+
+/**
+ * Returns props to create a `Checkbox` component. If the element is not a
+ * native checkbox, the hook will return additional props to make sure it's
+ * accessible.
+ * @see https://ariakit.com/components/checkbox
+ * @example
+ * ```jsx
+ * const props = useCheckbox({ render: <div /> });
+ * <Role {...props}>Accessible checkbox</Role>
+ * ```
+ */
+export const useCheckbox = createHook<TagName, CheckboxOptions>(
+  function useCheckbox({
+    store,
+    name,
+    value: valueProp,
+    checked: checkedProp,
+    defaultChecked,
+    ...props
+  }) {
+    const context = useCheckboxContext();
+    store = store || context;
+
+    const [_checked, setChecked] = useState(defaultChecked ?? false);
+
+    const checked = useStoreState(store, (state) => {
+      if (checkedProp !== undefined) return checkedProp;
+      if (state?.value === undefined) return _checked;
+      if (valueProp != null) {
+        if (Array.isArray(state.value)) {
+          const primitiveValue = getPrimitiveValue(valueProp);
+          return state.value.includes(primitiveValue);
+        }
+        return state.value === valueProp;
+      }
+      if (Array.isArray(state.value)) return false;
+      if (typeof state.value === "boolean") return state.value;
+      return false;
+    });
+
+    const ref = useRef<HTMLType>(null);
+    const tagName = useTagName(ref, TagName);
+    const nativeCheckbox = isNativeCheckbox(tagName, props.type);
+    const mixed = checked ? checked === "mixed" : undefined;
+    const isChecked = checked === "mixed" ? false : checked;
+    const disabled = disabledFromProps(props);
+    // When the checked property is programmatically set on the change event, we
+    // need to schedule the element's property update, so the controlled
+    // isChecked state can be taken into account.
+    const [propertyUpdated, schedulePropertyUpdate] = useForceUpdate();
+
+    useEffect(() => {
+      const element = ref.current;
+      if (!element) return;
+      setMixed(element, mixed);
+      if (nativeCheckbox) return;
+      element.checked = isChecked;
+      if (name !== undefined) {
+        element.name = name;
+      }
+      if (valueProp !== undefined) {
+        element.value = String(valueProp);
+      }
+    }, [propertyUpdated, mixed, nativeCheckbox, isChecked, name, valueProp]);
+
+    const onChangeProp = props.onChange;
+
+    const onChange = useEvent((event: ChangeEvent<HTMLType>) => {
+      if (disabled) {
+        event.stopPropagation();
+        event.preventDefault();
+        return;
+      }
+      setMixed(event.currentTarget, mixed);
+      if (!nativeCheckbox) {
+        // If the element is not a native checkbox, we need to manually update
+        // its checked property.
+        event.currentTarget.checked = !event.currentTarget.checked;
+        schedulePropertyUpdate();
+      }
+      onChangeProp?.(event);
+      if (event.defaultPrevented) return;
+
+      const elementChecked = event.currentTarget.checked;
+      setChecked(elementChecked);
+
+      store?.setValue((prevValue) => {
+        if (valueProp == null) return elementChecked;
+        const primitiveValue = getPrimitiveValue(valueProp);
+        if (!Array.isArray(prevValue)) {
+          return prevValue === primitiveValue ? false : primitiveValue;
+        }
+        if (elementChecked) {
+          if (prevValue.includes(primitiveValue)) {
+            return prevValue;
+          }
+          return [...prevValue, primitiveValue];
+        }
+        return prevValue.filter((v) => v !== primitiveValue);
+      });
+    });
+
+    const onClickProp = props.onClick;
+
+    const onClick = useEvent((event: MouseEvent<HTMLType>) => {
+      onClickProp?.(event);
+      if (event.defaultPrevented) return;
+      if (nativeCheckbox) return;
+      // @ts-expect-error The onChange event expects a ChangeEvent, but here we
+      // need to pass a MouseEvent.
+      onChange(event);
+    });
+
+    props = useWrapElement(
+      props,
+      (element) => (
+        <CheckboxCheckedContext.Provider value={isChecked}>
+          {element}
+        </CheckboxCheckedContext.Provider>
+      ),
+      [isChecked],
+    );
+
+    props = {
+      role: !nativeCheckbox ? "checkbox" : undefined,
+      type: nativeCheckbox ? "checkbox" : undefined,
+      "aria-checked": checked,
+      ...props,
+      ref: useMergeRefs(ref, props.ref),
+      onChange,
+      onClick,
+    };
+
+    props = useCommand<TagName>({ clickOnEnter: !nativeCheckbox, ...props });
+
+    return removeUndefinedValues({
+      name: nativeCheckbox ? name : undefined,
+      value: nativeCheckbox ? valueProp : undefined,
+      checked: isChecked,
+      ...props,
+    });
+  },
+);
+
+/**
+ * Renders an accessible checkbox element. If the underlying element is not a
+ * native checkbox, this component will pass additional attributes to make sure
+ * it's accessible.
+ * @see https://ariakit.com/components/checkbox
+ * @example
+ * ```jsx
+ * <Checkbox render={<div />}>Accessible checkbox</Checkbox>
+ * ```
+ */
+export const Checkbox = forwardRef(function Checkbox(props: CheckboxProps) {
+  const htmlProps = useCheckbox(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface CheckboxOptions<
+  T extends ElementType = TagName,
+> extends CommandOptions<T> {
+  /**
+   * Object returned by the
+   * [`useCheckboxStore`](https://ariakit.com/reference/use-checkbox-store)
+   * hook. If not provided, the closest
+   * [`CheckboxProvider`](https://ariakit.com/reference/checkbox-provider)
+   * component's context will be used. Otherwise, the component will fall back
+   * to an internal store.
+   *
+   * Live examples:
+   * - [Checkbox as button](https://ariakit.com/examples/checkbox-as-button)
+   */
+  store?: CheckboxStore;
+  /**
+   * The native `name` attribute.
+   *
+   * Live examples:
+   * - [MenuItemCheckbox](https://ariakit.com/examples/menu-item-checkbox)
+   */
+  name?: string;
+  /**
+   * The value of the checkbox. This is useful when the same checkbox store is
+   * used for multiple [`Checkbox`](https://ariakit.com/reference/checkbox)
+   * elements, in which case the value will be an array of checked values.
+   *
+   * Live examples:
+   * - [Checkbox group](https://ariakit.com/examples/checkbox-group)
+   * - [MenuItemCheckbox](https://ariakit.com/examples/menu-item-checkbox)
+   * @example
+   * ```jsx "value"
+   * <CheckboxProvider defaultValue={["Apple", "Orange"]}>
+   *   <Checkbox value="Apple" />
+   *   <Checkbox value="Orange" />
+   *   <Checkbox value="Watermelon" />
+   * </CheckboxProvider>
+   * ```
+   */
+  value?: ComponentPropsWithoutRef<TagName>["value"];
+  /**
+   * The default checked state of the checkbox. This prop is ignored if the
+   * [`checked`](https://ariakit.com/reference/checkbox#checked) or the
+   * [`store`](https://ariakit.com/reference/checkbox#store) props are provided.
+   */
+  defaultChecked?: "mixed" | boolean;
+  /**
+   * The checked state of the checkbox. This will override the value inferred
+   * from [`store`](https://ariakit.com/reference/checkbox#store) prop, if
+   * provided. This can be `"mixed"` to indicate that the checkbox is partially
+   * checked.
+   */
+  checked?: "mixed" | boolean;
+  /**
+   * A function that is called when the checkbox's checked state changes.
+   */
+  onChange?: ComponentPropsWithoutRef<TagName>["onChange"];
+}
+
+export type CheckboxProps<T extends ElementType = TagName> = Props<
+  T,
+  CheckboxOptions<T>
+>;

package/src/collection/collection-context.tsx

@@ -0,0 +1,27 @@
+import { createStoreContext } from "@ariakit/react-utils";
+import type { CollectionStore } from "./collection-store.ts";
+
+const ctx = createStoreContext<CollectionStore>();
+
+/**
+ * Returns the collection store from the nearest collection container.
+ * @example
+ * function CollectionItem() {
+ *   const store = useCollectionContext();
+ *
+ *   if (!store) {
+ *     throw new Error("CollectionItem must be wrapped in CollectionProvider");
+ *   }
+ *
+ *   // Use the store...
+ * }
+ */
+export const useCollectionContext = ctx.useContext;
+
+export const useCollectionScopedContext = ctx.useScopedContext;
+
+export const useCollectionProviderContext = ctx.useProviderContext;
+
+export const CollectionContextProvider = ctx.ContextProvider;
+
+export const CollectionScopedContextProvider = ctx.ScopedContextProvider;