@ariakit/react-components 0.1.0

package/src/form/form-radio-group.tsx

@@ -0,0 +1,93 @@
+import {
+  useWrapElement,
+  createElement,
+  createHook,
+  forwardRef,
+} from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import type { ElementType } from "react";
+import { CompositeScopedContextProvider } from "../composite/composite-context.tsx";
+import type { FormGroupOptions } from "./form-group.tsx";
+import { useFormGroup } from "./form-group.tsx";
+
+const TagName = "div" satisfies ElementType;
+type TagName = typeof TagName;
+
+/**
+ * Returns props to create a `FormRadioGroup` component.
+ * @see https://ariakit.com/components/form
+ * @example
+ * ```jsx
+ * const store = useFormStore({ defaultValues: { color: "red" } });
+ * const props = useFormRadioGroup({ store });
+ * <Form store={store}>
+ *   <Role {...props}>
+ *     <FormGroupLabel>Favorite color</FormGroupLabel>
+ *     <FormRadio name={store.names.color} value="red" />
+ *     <FormRadio name={store.names.color} value="blue" />
+ *     <FormRadio name={store.names.color} value="green" />
+ *   </Role>
+ * </Form>
+ * ```
+ */
+export const useFormRadioGroup = createHook<TagName, FormRadioGroupOptions>(
+  function useFormRadioGroup({ store, ...props }) {
+    // Reset the composite context so FormRadio items inside this group
+    // don't register to an unrelated ancestor composite store (e.g.,
+    // TabStore). Form controls explicitly pass their store to
+    // useCollectionItem, so they're not affected by this reset.
+    props = useWrapElement(
+      props,
+      (element) => (
+        <CompositeScopedContextProvider value={undefined}>
+          {element}
+        </CompositeScopedContextProvider>
+      ),
+      [],
+    );
+
+    props = { role: "radiogroup", ...props };
+    props = useFormGroup(props);
+    return props;
+  },
+);
+
+/**
+ * Renders a group element for
+ * [`FormRadio`](https://ariakit.com/reference/form-radio) elements. The
+ * [`FormGroupLabel`](https://ariakit.com/reference/form-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/form
+ * @example
+ * ```jsx {8-13}
+ * const form = useFormStore({
+ *   defaultValues: {
+ *     color: "red",
+ *   },
+ * });
+ *
+ * <Form store={form}>
+ *   <FormRadioGroup>
+ *     <FormGroupLabel>Favorite color</FormGroupLabel>
+ *     <FormRadio name={form.names.color} value="red" />
+ *     <FormRadio name={form.names.color} value="blue" />
+ *     <FormRadio name={form.names.color} value="green" />
+ *   </FormRadioGroup>
+ * </Form>
+ * ```
+ */
+export const FormRadioGroup = forwardRef(function FormRadioGroup(
+  props: FormRadioGroupProps,
+) {
+  const htmlProps = useFormRadioGroup(props);
+  return createElement(TagName, htmlProps);
+});
+
+export type FormRadioGroupOptions<T extends ElementType = TagName> =
+  FormGroupOptions<T>;
+
+export type FormRadioGroupProps<T extends ElementType = TagName> = Props<
+  T,
+  FormRadioGroupOptions<T>
+>;

package/src/form/form-radio.tsx

@@ -0,0 +1,122 @@
+import { useStoreState } from "@ariakit/react-store";
+import {
+  useEvent,
+  createElement,
+  createHook,
+  forwardRef,
+  memo,
+} from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import { invariant } from "@ariakit/utils";
+import type { ChangeEvent, ElementType } from "react";
+import type { RadioOptions } from "../radio/radio.tsx";
+import { useRadio } from "../radio/radio.tsx";
+import { useFormContext } from "./form-context.tsx";
+import type { FormControlOptions } from "./form-control.tsx";
+import { useFormControl } from "./form-control.tsx";
+
+const TagName = "input" satisfies ElementType;
+type TagName = typeof TagName;
+
+/**
+ * Returns props to create a `FormRadio` component.
+ * @see https://ariakit.com/components/form
+ * @example
+ * ```jsx
+ * const store = useFormStore({ defaultValues: { char: "a" } });
+ * const a = useFormRadio({ store, name: store.names.char, value: "a" });
+ * const b = useFormRadio({ store, name: store.names.char, value: "b" });
+ * const c = useFormRadio({ store, name: store.names.char, value: "c" });
+ * <Form store={store}>
+ *   <FormRadioGroup>
+ *     <FormGroupLabel>Favorite character</FormGroupLabel>
+ *     <Role {...a} />
+ *     <Role {...b} />
+ *     <Role {...c} />
+ *   </FormRadioGroup>
+ * </Form>
+ * ```
+ */
+export const useFormRadio = createHook<TagName, FormRadioOptions>(
+  function useFormRadio({ store, name: nameProp, value, ...props }) {
+    const context = useFormContext();
+    store = store || context;
+
+    invariant(
+      store,
+      process.env.NODE_ENV !== "production" &&
+        "FormRadio must be wrapped in a Form component.",
+    );
+
+    const name = String(nameProp);
+    const onChangeProp = props.onChange;
+
+    const onChange = useEvent((event: ChangeEvent<HTMLInputElement>) => {
+      onChangeProp?.(event);
+      if (event.defaultPrevented) return;
+      store?.setValue(name, value);
+    });
+
+    const checkedProp = props.checked;
+    const checked = useStoreState(
+      store,
+      () => checkedProp ?? store?.getValue(name) === value,
+    );
+
+    props = {
+      ...props,
+      checked,
+      onChange,
+    };
+
+    props = useRadio({ name, value, ...props });
+
+    props = useFormControl({
+      store,
+      name,
+      "aria-labelledby": undefined,
+      ...props,
+    });
+
+    return props;
+  },
+);
+
+/**
+ * Renders a radio button as a form control. This component must be wrapped in a
+ * [`FormRadioGroup`](https://ariakit.com/reference/form-radio-group) along with
+ * other radio buttons sharing the same
+ * [`name`](https://ariakit.com/reference/form-radio#name).
+ * @see https://ariakit.com/components/form
+ * @example
+ * ```jsx {10-12}
+ * const form = useFormStore({
+ *   defaultValues: {
+ *     char: "a",
+ *   },
+ * });
+ *
+ * <Form store={form}>
+ *   <FormRadioGroup>
+ *     <FormGroupLabel>Favorite character</FormGroupLabel>
+ *     <FormRadio name={form.names.char} value="a" />
+ *     <FormRadio name={form.names.char} value="b" />
+ *     <FormRadio name={form.names.char} value="c" />
+ *   </FormRadioGroup>
+ * </Form>
+ * ```
+ */
+export const FormRadio = memo(
+  forwardRef(function FormRadio(props: FormRadioProps) {
+    const htmlProps = useFormRadio(props);
+    return createElement(TagName, htmlProps);
+  }),
+);
+
+export interface FormRadioOptions<T extends ElementType = TagName>
+  extends FormControlOptions<T>, Omit<RadioOptions<T>, "store" | "name"> {}
+
+export type FormRadioProps<T extends ElementType = TagName> = Props<
+  T,
+  FormRadioOptions<T>
+>;

package/src/form/form-remove.tsx

@@ -0,0 +1,198 @@
+import type { StringLike } from "@ariakit/components/form/types";
+import {
+  useEvent,
+  createElement,
+  createHook,
+  forwardRef,
+} from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import { isTextField, invariant } from "@ariakit/utils";
+import type { ElementType, MouseEvent } from "react";
+import type { ButtonOptions } from "../button/button.tsx";
+import { useButton } from "../button/button.tsx";
+import { useFormContext } from "./form-context.tsx";
+import type { FormStore, FormStoreState } from "./form-store.ts";
+
+const TagName = "button" satisfies ElementType;
+type TagName = typeof TagName;
+type HTMLType = HTMLElementTagNameMap[TagName];
+
+function findNextOrPreviousField(
+  items: FormStoreState["items"] | undefined,
+  name: string,
+  index: number,
+) {
+  const fields = items?.filter(
+    (item) => item.type === "field" && item.name.startsWith(name),
+  );
+  const regex = new RegExp(`^${name}\\.(\\d+)`);
+  const nextField = fields?.find((field) => {
+    const fieldIndex = field.name.replace(regex, "$1");
+    return Number.parseInt(fieldIndex, 10) > index;
+  });
+  if (nextField) return nextField;
+  return fields?.reverse().find((field) => {
+    const fieldIndex = field.name.replace(regex, "$1");
+    return Number.parseInt(fieldIndex, 10) < index;
+  });
+}
+
+function findPushButton(
+  items: FormStoreState["items"] | undefined,
+  name: string,
+) {
+  return items?.find((item) => item.type === "button" && item.name === name);
+}
+
+/**
+ * Returns props to create a `FormRemove` component.
+ * @see https://ariakit.com/components/form
+ * @example
+ * ```jsx
+ * const store = useFormStore({
+ *   defaultValues: {
+ *     languages: ["JavaScript", "PHP"],
+ *   },
+ * });
+ * const props = useFormRemove({
+ *   store,
+ *   name: store.names.languages,
+ *   index: 0,
+ * });
+ * const values = useStoreState(store, "values");
+ *
+ * <Form store={store}>
+ *   {values.languages.map((_, i) => (
+ *     <FormInput key={i} name={store.names.languages[i]} />
+ *   ))}
+ *   <Role {...props}>Remove first language</Role>
+ * </Form>
+ * ```
+ */
+export const useFormRemove = createHook<TagName, FormRemoveOptions>(
+  function useFormRemove({
+    store,
+    name: nameProp,
+    index,
+    autoFocusOnClick = true,
+    ...props
+  }) {
+    const context = useFormContext();
+    store = store || context;
+
+    invariant(
+      store,
+      process.env.NODE_ENV !== "production" &&
+        "FormRemove must be wrapped in a Form component.",
+    );
+
+    const name = String(nameProp);
+    const onClickProp = props.onClick;
+
+    const onClick = useEvent((event: MouseEvent<HTMLType>) => {
+      onClickProp?.(event);
+      if (event.defaultPrevented) return;
+      if (!store) return;
+      store.removeValue(name, index);
+      if (!autoFocusOnClick) return;
+      const { items } = store.getState();
+      const item = findNextOrPreviousField(items, name, index);
+      const element = item?.element;
+      if (element) {
+        element.focus();
+        if (isTextField(element)) {
+          element.select();
+        }
+      } else {
+        const pushButton = findPushButton(items, name);
+        pushButton?.element?.focus();
+      }
+    });
+
+    props = {
+      ...props,
+      onClick,
+    };
+
+    props = useButton(props);
+
+    return props;
+  },
+);
+
+/**
+ * Renders a button that will remove an item from an array field in the form
+ * when clicked.
+ *
+ * The [`name`](https://ariakit.com/reference/form-remove#name) prop must be
+ * provided to identify the array field. Similarly, the
+ * [`index`](https://ariakit.com/reference/form-remove#index) prop is required
+ * to pinpoint the item to remove.
+ *
+ * By default, the button will automatically move focus to the next field in the
+ * form when clicked, or to the previous field if there isn't a next field. This
+ * behavior can be disabled by setting the
+ * [`autoFocusOnClick`](https://ariakit.com/reference/form-remove#autofocusonclick)
+ * prop to `false`.
+ * @see https://ariakit.com/components/form
+ * @example
+ * ```jsx {13}
+ * const form = useFormStore({
+ *   defaultValues: {
+ *     languages: ["JavaScript", "PHP"],
+ *   },
+ * });
+ *
+ * const values = useStoreState(form, "values");
+ *
+ * <Form store={form}>
+ *   {values.languages.map((_, i) => (
+ *     <div key={i}>
+ *       <FormInput name={form.names.languages[i]} />
+ *       <FormRemove name={form.names.languages} index={i} />
+ *     </div>
+ *   ))}
+ * </Form>
+ * ```
+ */
+export const FormRemove = forwardRef(function FormRemove(
+  props: FormRemoveProps,
+) {
+  const htmlProps = useFormRemove(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface FormRemoveOptions<
+  T extends ElementType = TagName,
+> extends ButtonOptions<T> {
+  /**
+   * Object returned by the
+   * [`useFormStore`](https://ariakit.com/reference/use-form-store) hook. If not
+   * provided, the closest [`Form`](https://ariakit.com/reference/form) or
+   * [`FormProvider`](https://ariakit.com/reference/form-provider) components'
+   * context will be used.
+   */
+  store?: FormStore;
+  /**
+   * Name of the array field. This can either be a string or a reference to a
+   * field name from the
+   * [`names`](https://ariakit.com/reference/use-form-store#names) object in the
+   * store, for type safety.
+   */
+  name: StringLike;
+  /**
+   * Index of the item to remove.
+   */
+  index: number;
+  /**
+   * Whether the focus should be moved to the next or previous field when the
+   * button is clicked.
+   * @default true
+   */
+  autoFocusOnClick?: boolean;
+}
+
+export type FormRemoveProps<T extends ElementType = TagName> = Props<
+  T,
+  FormRemoveOptions<T>
+>;

package/src/form/form-reset.tsx

@@ -0,0 +1,85 @@
+import { useStoreState } from "@ariakit/react-store";
+import { createElement, createHook, forwardRef } from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import { invariant } from "@ariakit/utils";
+import type { ElementType } from "react";
+import type { ButtonOptions } from "../button/button.tsx";
+import { useButton } from "../button/button.tsx";
+import { useFormContext } from "./form-context.tsx";
+import type { FormStore } from "./form-store.ts";
+
+const TagName = "button" satisfies ElementType;
+type TagName = typeof TagName;
+
+/**
+ * Returns props to create a `FormReset` component.
+ * @see https://ariakit.com/components/form
+ * @example
+ * ```jsx
+ * const store = useFormStore();
+ * const props = useFormReset({ store });
+ * <Form store={store}>
+ *   <Role {...props}>Reset</Role>
+ * </Form>
+ * ```
+ */
+export const useFormReset = createHook<TagName, FormResetOptions>(
+  function useFormReset({ store, ...props }) {
+    const context = useFormContext();
+    store = store || context;
+
+    invariant(
+      store,
+      process.env.NODE_ENV !== "production" &&
+        "FormReset must be wrapped in a Form component.",
+    );
+
+    props = {
+      type: "reset",
+      disabled: useStoreState(store, "submitting"),
+      ...props,
+    };
+
+    props = useButton(props);
+
+    return props;
+  },
+);
+
+/**
+ * Renders a button that resets the form to its initial values, as defined by
+ * the
+ * [`defaultValues`](https://ariakit.com/reference/use-form-store#defaultvalues)
+ * prop given to the form store.
+ * @see https://ariakit.com/components/form
+ * @example
+ * ```jsx {4}
+ * const form = useFormStore();
+ *
+ * <Form store={form}>
+ *   <FormReset>Reset</FormReset>
+ * </Form>
+ * ```
+ */
+export const FormReset = forwardRef(function FormReset(props: FormResetProps) {
+  const htmlProps = useFormReset(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface FormResetOptions<
+  T extends ElementType = TagName,
+> extends ButtonOptions<T> {
+  /**
+   * Object returned by the
+   * [`useFormStore`](https://ariakit.com/reference/use-form-store) hook. If not
+   * provided, the closest [`Form`](https://ariakit.com/reference/form) or
+   * [`FormProvider`](https://ariakit.com/reference/form-provider) components'
+   * context will be used.
+   */
+  store?: FormStore;
+}
+
+export type FormResetProps<T extends ElementType = TagName> = Props<
+  T,
+  FormResetOptions<T>
+>;

package/src/form/form-store.ts

@@ -0,0 +1,195 @@
+import * as Core from "@ariakit/components/form/form-store";
+import type { StringLike } from "@ariakit/components/form/types";
+import { useStore, useStoreProps, useStoreState } from "@ariakit/react-store";
+import type { Store } from "@ariakit/react-store";
+import { useEvent } from "@ariakit/react-utils";
+import type { PickRequired } from "@ariakit/utils";
+import { useCallback, useEffect, useMemo } from "react";
+import type {
+  CollectionStoreFunctions,
+  CollectionStoreOptions,
+  CollectionStoreState,
+} from "../collection/collection-store.ts";
+import { useCollectionStoreProps } from "../collection/collection-store.ts";
+
+export function useFormStoreProps<
+  T extends Omit<FormStore, "useValue" | "useValidate" | "useSubmit">,
+>(store: T, update: () => void, props: FormStoreProps) {
+  store = useCollectionStoreProps(store, update, props);
+
+  useStoreProps(store, props, "values", "setValues");
+  useStoreProps(store, props, "errors", "setErrors");
+  useStoreProps(store, props, "touched", "setTouched");
+
+  const useValue = useCallback<FormStore["useValue"]>(
+    (name) => useStoreState(store, () => store.getValue(name)),
+    [store],
+  );
+
+  const useValidate = useCallback<FormStore["useValidate"]>(
+    (callback) => {
+      callback = useEvent(callback);
+      // Whenever the items change (for example, when form fields are lazily
+      // rendered), we need to reset the callbacks so they always run in a
+      // consistent order.
+      const items = useStoreState(store, "items");
+      useEffect(() => store.onValidate(callback), [items, callback]);
+    },
+    [store],
+  );
+
+  const useSubmit = useCallback<FormStore["useSubmit"]>(
+    (callback) => {
+      callback = useEvent(callback);
+      // Same logic as useValidate.
+      const items = useStoreState(store, "items");
+      useEffect(() => store.onSubmit(callback), [items, callback]);
+    },
+    [store],
+  );
+
+  return useMemo(
+    () => ({
+      ...store,
+      useValue,
+      useValidate,
+      useSubmit,
+    }),
+    [store, useValue, useValidate, useSubmit],
+  );
+}
+
+/**
+ * Creates a form store to control the state of
+ * [Form](https://ariakit.com/components/form) components.
+ * @example
+ * ```jsx
+ * const form = useFormStore({
+ *   defaultValues: {
+ *     email: "",
+ *   },
+ * });
+ *
+ * <Form store={form}>
+ *   <FormLabel name={form.names.email}>Email</FormLabel>
+ *   <FormInput name={form.names.email} />
+ *   <FormError name={form.names.email} />
+ *   <FormSubmit>Submit</FormSubmit>
+ * </Form>
+ * ```
+ */
+export function useFormStore<T extends FormStoreValues = FormStoreValues>(
+  props: PickRequired<
+    FormStoreProps<T>,
+    | "values"
+    | "defaultValues"
+    | "errors"
+    | "defaultErrors"
+    | "touched"
+    | "defaultTouched"
+  >,
+): FormStore<T>;
+
+export function useFormStore(props: FormStoreProps): FormStore;
+
+export function useFormStore(props: FormStoreProps = {}): FormStore {
+  const [store, update] = useStore(Core.createFormStore, props);
+  return useFormStoreProps(store, update, props);
+}
+
+export interface FormStoreValues extends Core.FormStoreValues {}
+
+export interface FormStoreItem extends Core.FormStoreItem {}
+
+export interface FormStoreState<T extends FormStoreValues = FormStoreValues>
+  extends Core.FormStoreState<T>, CollectionStoreState<FormStoreItem> {}
+
+export interface FormStoreFunctions<T extends FormStoreValues = FormStoreValues>
+  extends Core.FormStoreFunctions<T>, CollectionStoreFunctions<FormStoreItem> {
+  /**
+   * A custom hook that rerenders the component when the value of the given
+   * field changes. It accepts a string or a reference to a field name from the
+   * [`names`](https://ariakit.com/reference/use-form-store#names) object in the
+   * store, for type safety. It returns the value of the field.
+   *
+   * Live examples:
+   * - [Form with Select](https://ariakit.com/examples/form-select)
+   * @example
+   * const nameValue = store.useValue("name");
+   * // Can also use store.names for type safety.
+   * const emailValue = store.useValue(store.names.email);
+   */
+  // oxlint-disable-next-line no-unnecessary-type-parameters
+  useValue: <T = any>(name: StringLike) => T;
+  /**
+   * Custom hook that accepts a callback that will be used to validate the form
+   * when [`validate`](https://ariakit.com/reference/use-form-store#validate) is
+   * called, typically when a form field is touched or when the form is
+   * submitted.
+   *
+   * Live examples:
+   * - [FormRadio](https://ariakit.com/examples/form-radio)
+   * @example
+   * store.useValidate(async (state) => {
+   *   const errors = await api.validate(state.values);
+   *   if (errors) {
+   *     store.setErrors(errors);
+   *   }
+   * });
+   */
+  useValidate: (callback: Core.FormStoreCallback<FormStoreState<T>>) => void;
+  /**
+   * Custom hook that accepts a callback that will be used to submit the form
+   * when [`submit`](https://ariakit.com/reference/use-form-store#submit) is
+   * called.
+   *
+   * Live examples:
+   * - [FormRadio](https://ariakit.com/examples/form-radio)
+   * - [Form with Select](https://ariakit.com/examples/form-select)
+   * @example
+   * store.useSubmit(async (state) => {
+   *   try {
+   *     await api.submit(state.values);
+   *   } catch (errors) {
+   *     store.setErrors(errors);
+   *   }
+   * });
+   */
+  useSubmit: (callback: Core.FormStoreCallback<FormStoreState<T>>) => void;
+}
+
+export interface FormStoreOptions<T extends FormStoreValues = FormStoreValues>
+  extends Core.FormStoreOptions<T>, CollectionStoreOptions<FormStoreItem> {
+  /**
+   * Function that will be called when
+   * [`values`](https://ariakit.com/reference/use-form-store#values) state
+   * changes.
+   * @example
+   * function MyForm({ values, onChange }) {
+   *   const form = useFormStore({ values, setValues: onChange });
+   * }
+   */
+  setValues?: (values: FormStoreState<T>["values"]) => void;
+  /**
+   * Function that will be called when the
+   * [`errors`](https://ariakit.com/reference/use-form-store#errors) state
+   * changes.
+   * @example
+   * useFormStore({ setErrors: (errors) => console.log(errors) });
+   */
+  setErrors?: (errors: FormStoreState<T>["errors"]) => void;
+  /**
+   * Function that will be called when the
+   * [`touched`](https://ariakit.com/reference/use-form-store#touched) state
+   * changes.
+   * @example
+   * useFormStore({ setTouched: (touched) => console.log(touched) });
+   */
+  setTouched?: (touched: FormStoreState<T>["touched"]) => void;
+}
+
+export interface FormStoreProps<T extends FormStoreValues = FormStoreValues>
+  extends FormStoreOptions<T>, Core.FormStoreProps<T> {}
+
+export interface FormStore<T extends FormStoreValues = FormStoreValues>
+  extends FormStoreFunctions<T>, Store<Core.FormStore<T>> {}