@ariakit/react-components 0.1.0

package/src/form/form-control.tsx

@@ -0,0 +1,227 @@
+import type { StringLike } from "@ariakit/components/form/types";
+import { useStoreState } from "@ariakit/react-store";
+import {
+  useBooleanEvent,
+  useEvent,
+  useId,
+  useMergeRefs,
+  createElement,
+  createHook,
+  forwardRef,
+  memo,
+} from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import { getDocument, cx, invariant } from "@ariakit/utils";
+import type { BooleanOrCallback } from "@ariakit/utils";
+import type { ElementType, FocusEvent, RefObject } from "react";
+import { useCallback, useRef } from "react";
+import type { CollectionItemOptions } from "../collection/collection-item.tsx";
+import { useCollectionItem } from "../collection/collection-item.tsx";
+import { useFormContext } from "./form-context.tsx";
+import type { FormStore } from "./form-store.ts";
+
+const TagName = "input" satisfies ElementType;
+type TagName = typeof TagName;
+type HTMLType = HTMLElementTagNameMap[TagName];
+type ItemType = "label" | "error" | "description";
+
+function getNamedElement(
+  ref: RefObject<HTMLInputElement | null>,
+  name: string,
+) {
+  const element = ref.current;
+  if (!element) return null;
+  if (element.name === name) return element;
+  if (element.form) {
+    return element.form.elements.namedItem(name) as HTMLInputElement | null;
+  }
+  const document = getDocument(element);
+  return document.getElementsByName(name)[0] as HTMLInputElement | null;
+}
+
+function useItem(store: FormStore, name: string, type: ItemType) {
+  return useStoreState(store, (state) =>
+    state.items.find((item) => item.type === type && item.name === name),
+  );
+}
+
+/**
+ * Returns props to create a `FormControl` component. Unlike `useFormInput`,
+ * this hook doesn't automatically returns the `value` and `onChange` props.
+ * This is so we can use it not only for native form elements but also for
+ * custom components whose value is not controlled by the native `value` and
+ * `onChange` props.
+ * @see https://ariakit.com/components/form
+ * @example
+ * ```jsx
+ * const store = useFormStore({ defaultValues: { content: "" } });
+ * const props = useFormControl({ store, name: store.names.content });
+ * const value = store.useValue(store.names.content);
+ *
+ * <Form store={store}>
+ *   <FormLabel name={store.names.content}>Content</FormLabel>
+ *   <Role
+ *     {...props}
+ *     value={value}
+ *     onChange={(value) => store.setValue(store.names.content, value)}
+ *     render={<Editor />}
+ *   />
+ * </Form>
+ * ```
+ */
+export const useFormControl = createHook<TagName, FormControlOptions>(
+  function useFormControl({
+    store,
+    name: nameProp,
+    getItem: getItemProp,
+    touchOnBlur = true,
+    ...props
+  }) {
+    const context = useFormContext();
+    store = store || context;
+
+    invariant(
+      store,
+      process.env.NODE_ENV !== "production" &&
+        "FormControl must be wrapped in a Form component.",
+    );
+
+    const name = String(nameProp);
+    const id = useId(props.id);
+    const ref = useRef<HTMLType>(null);
+
+    store.useValidate(async () => {
+      const element = getNamedElement(ref, name);
+      if (!element) return;
+      // Flush microtasks to make sure the validity state is up to date
+      await Promise.resolve();
+      if ("validity" in element && !element.validity.valid) {
+        store?.setError(name, element.validationMessage);
+      }
+    });
+
+    const getItem = useCallback<NonNullable<CollectionItemOptions["getItem"]>>(
+      (item) => {
+        const nextItem = { ...item, id: id || item.id, name, type: "field" };
+        if (getItemProp) {
+          return getItemProp(nextItem);
+        }
+        return nextItem;
+      },
+      [id, name, getItemProp],
+    );
+
+    const onBlurProp = props.onBlur;
+    const touchOnBlurProp = useBooleanEvent(touchOnBlur);
+
+    const onBlur = useEvent((event: FocusEvent<HTMLType>) => {
+      onBlurProp?.(event);
+      if (event.defaultPrevented) return;
+      if (!touchOnBlurProp(event)) return;
+      store?.setFieldTouched(name, true);
+    });
+
+    const label = useItem(store, name, "label");
+    const error = useItem(store, name, "error");
+    const description = useItem(store, name, "description");
+    const describedBy = cx(
+      error?.id,
+      description?.id,
+      props["aria-describedby"],
+    );
+
+    const invalid = useStoreState(
+      store,
+      () => !!store?.getError(name) && store.getFieldTouched(name),
+    );
+
+    props = {
+      "aria-labelledby": props["aria-label"] != null ? undefined : label?.id,
+      "aria-invalid": invalid,
+      ...props,
+      id,
+      "aria-describedby": describedBy || undefined,
+      ref: useMergeRefs(ref, props.ref),
+      onBlur,
+    };
+
+    props = useCollectionItem<TagName>({ store, ...props, name, getItem });
+
+    return props;
+  },
+);
+
+/**
+ * Abstract component that renders a form control. Unlike
+ * [`FormInput`](https://ariakit.com/reference/form-input), this component
+ * doesn't automatically pass the `value` and `onChange` props down to the
+ * underlying element. This is so we can use it not only for native form
+ * elements but also for custom components whose value is not controlled by the
+ * native `value` and `onChange` props.
+ * @see https://ariakit.com/components/form
+ * @example
+ * ```jsx {11-19}
+ * const form = useFormStore({
+ *   defaultValues: {
+ *     content: "",
+ *   },
+ * });
+ *
+ * const value = form.useValue(form.names.content);
+ *
+ * <Form store={form}>
+ *   <FormLabel name={form.names.content}>Content</FormLabel>
+ *   <FormControl
+ *     name={form.names.content}
+ *     render={
+ *       <Editor
+ *         value={value}
+ *         onChange={(value) => form.setValue(form.names.content, value)}
+ *       />
+ *     }
+ *   />
+ * </Form>
+ * ```
+ */
+export const FormControl = memo(
+  forwardRef(function FormControl(props: FormControlProps) {
+    const htmlProps = useFormControl(props);
+    return createElement(TagName, htmlProps);
+  }),
+);
+
+export interface FormControlOptions<
+  T extends ElementType = TagName,
+> extends CollectionItemOptions<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;
+  /**
+   * Field name. This can either be a string corresponding to an existing
+   * property name in the
+   * [`values`](https://ariakit.com/reference/use-form-store#values) state of
+   * the store, or a reference to a field name from the
+   * [`names`](https://ariakit.com/reference/use-form-store#names) object in the
+   * store, ensuring type safety.
+   *
+   * Live examples:
+   * - [FormRadio](https://ariakit.com/examples/form-radio)
+   * - [Form with Select](https://ariakit.com/examples/form-select)
+   */
+  name: StringLike;
+  /**
+   * Whether the field should be marked touched on blur.
+   * @default true
+   */
+  touchOnBlur?: BooleanOrCallback<FocusEvent>;
+}
+
+export type FormControlProps<T extends ElementType = TagName> = Props<
+  T,
+  FormControlOptions<T>
+>;

package/src/form/form-description.tsx

@@ -0,0 +1,142 @@
+import type { StringLike } from "@ariakit/components/form/types";
+import {
+  useId,
+  useMergeRefs,
+  createElement,
+  createHook,
+  forwardRef,
+  memo,
+} from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import { invariant } from "@ariakit/utils";
+import type { ElementType } from "react";
+import { useCallback, useRef } from "react";
+import type { CollectionItemOptions } from "../collection/collection-item.tsx";
+import { useCollectionItem } from "../collection/collection-item.tsx";
+import { useFormContext } from "./form-context.tsx";
+import type { FormStore } from "./form-store.ts";
+
+const TagName = "div" satisfies ElementType;
+type TagName = typeof TagName;
+type HTMLType = HTMLElementTagNameMap[TagName];
+
+/**
+ * Returns props to create a `FormDescription` component.
+ * @see https://ariakit.com/components/form
+ * @example
+ * ```jsx
+ * const store = useFormStore({ defaultValues: { password: "" } });
+ * const props = useFormDescription({ store, name: store.names.password });
+ * <Form store={store}>
+ *   <FormLabel name={store.names.password}>Password</FormLabel>
+ *   <FormInput name={store.names.password} type="password" />
+ *   <Role {...props}>Password with at least 8 characters.</Role>
+ * </Form>
+ * ```
+ */
+export const useFormDescription = createHook<TagName, FormDescriptionOptions>(
+  function useFormDescription({
+    store,
+    name: nameProp,
+    getItem: getItemProp,
+    ...props
+  }) {
+    const context = useFormContext();
+    store = store || context;
+
+    invariant(
+      store,
+      process.env.NODE_ENV !== "production" &&
+        "FormDescription must be wrapped in a Form component.",
+    );
+
+    const id = useId(props.id);
+    const ref = useRef<HTMLType>(null);
+    const name = String(nameProp);
+
+    const getItem = useCallback<NonNullable<CollectionItemOptions["getItem"]>>(
+      (item) => {
+        const nextItem = {
+          ...item,
+          id: id || item.id,
+          name,
+          type: "description",
+        };
+        if (getItemProp) {
+          return getItemProp(nextItem);
+        }
+        return nextItem;
+      },
+      [id, name, getItemProp],
+    );
+
+    props = {
+      ...props,
+      id,
+      ref: useMergeRefs(ref, props.ref),
+    };
+
+    props = useCollectionItem({ store, ...props, getItem });
+
+    return props;
+  },
+);
+
+/**
+ * Renders a description element for a form field, which will automatically
+ * receive an `aria-describedby` attribute pointing to this element.
+ * @see https://ariakit.com/components/form
+ * @example
+ * ```jsx {10-12}
+ * const form = useFormStore({
+ *   defaultValues: {
+ *     password: "",
+ *   },
+ * });
+ *
+ * <Form store={form}>
+ *   <FormLabel name={form.names.password}>Password</FormLabel>
+ *   <FormInput name={form.names.password} type="password" />
+ *   <FormDescription name={form.names.password}>
+ *     Password with at least 8 characters.
+ *   </FormDescription>
+ * </Form>
+ * ```
+ */
+export const FormDescription = memo(
+  forwardRef(function FormDescription(props: FormDescriptionProps) {
+    const htmlProps = useFormDescription(props);
+    return createElement(TagName, htmlProps);
+  }),
+);
+
+export interface FormDescriptionOptions<
+  T extends ElementType = TagName,
+> extends CollectionItemOptions<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 field described by this element. 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.
+   * @example
+   * ```jsx
+   * <FormDescription name="password">
+   *   Password with at least 8 characters.
+   * </FormDescription>
+   * ```
+   */
+  name: StringLike;
+}
+
+export type FormDescriptionProps<T extends ElementType = TagName> = Props<
+  T,
+  FormDescriptionOptions<T>
+>;

package/src/form/form-error.tsx

@@ -0,0 +1,156 @@
+import type { StringLike } from "@ariakit/components/form/types";
+import { useStoreState } from "@ariakit/react-store";
+import {
+  useId,
+  useMergeRefs,
+  createElement,
+  createHook,
+  forwardRef,
+  memo,
+} from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import { invariant } from "@ariakit/utils";
+import type { ElementType } from "react";
+import { useCallback, useRef } from "react";
+import type { CollectionItemOptions } from "../collection/collection-item.tsx";
+import { useCollectionItem } from "../collection/collection-item.tsx";
+import { useFormContext } from "./form-context.tsx";
+import type { FormStore } from "./form-store.ts";
+
+const TagName = "div" satisfies ElementType;
+type TagName = typeof TagName;
+type HTMLType = HTMLElementTagNameMap[TagName];
+
+/**
+ * Returns props to create a `FormDescription` component.
+ * @see https://ariakit.com/components/form
+ * @example
+ * ```jsx
+ * const store = useFormStore({ defaultValues: { email: "" } });
+ * const props = useFormError({ store, name: store.names.email });
+ *
+ * store.useValidate(() => {
+ *   if (!store.getValue(store.names.email)) {
+ *     store.setError(store.names.email, "Email is required!");
+ *   }
+ * });
+ *
+ * <Form store={store}>
+ *   <FormLabel name={store.names.email}>Email</FormLabel>
+ *   <FormInput name={store.names.email} />
+ *   <Role {...props} />
+ * </Form>
+ * ```
+ */
+export const useFormError = createHook<TagName, FormErrorOptions>(
+  function useFormError({
+    store,
+    name: nameProp,
+    getItem: getItemProp,
+    ...props
+  }) {
+    const context = useFormContext();
+    store = store || context;
+
+    invariant(
+      store,
+      process.env.NODE_ENV !== "production" &&
+        "FormError must be wrapped in a Form component.",
+    );
+
+    const id = useId(props.id);
+    const ref = useRef<HTMLType>(null);
+    const name = String(nameProp);
+
+    const getItem = useCallback<NonNullable<CollectionItemOptions["getItem"]>>(
+      (item) => {
+        const nextItem = { ...item, id: id || item.id, name, type: "error" };
+        if (getItemProp) {
+          return getItemProp(nextItem);
+        }
+        return nextItem;
+      },
+      [id, name, getItemProp],
+    );
+
+    const children = useStoreState(store, () => {
+      const error = store?.getError(name);
+      if (error == null) return;
+      if (!store?.getFieldTouched(name)) return;
+      return error;
+    });
+
+    props = {
+      role: "alert",
+      children,
+      ...props,
+      id,
+      ref: useMergeRefs(ref, props.ref),
+    };
+
+    props = useCollectionItem({ store, ...props, getItem });
+
+    return props;
+  },
+);
+
+/**
+ * Renders an element that shows an error message. The `children` will
+ * automatically display the error message defined in the store.
+ * @see https://ariakit.com/components/form
+ * @example
+ * ```jsx {16}
+ * const form = useFormStore({
+ *   defaultValues: {
+ *     email: "",
+ *   },
+ * });
+ *
+ * form.useValidate(() => {
+ *   if (!form.values.email) {
+ *     form.setError(form.names.email, "Email is required!");
+ *   }
+ * });
+ *
+ * <Form store={form}>
+ *   <FormLabel name={form.names.email}>Email</FormLabel>
+ *   <FormInput name={form.names.email} />
+ *   <FormError name={form.names.email} />
+ * </Form>
+ * ```
+ */
+export const FormError = memo(
+  forwardRef(function FormError(props: FormErrorProps) {
+    const htmlProps = useFormError(props);
+    return createElement(TagName, htmlProps);
+  }),
+);
+
+export interface FormErrorOptions<
+  T extends ElementType = TagName,
+> extends CollectionItemOptions<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 field associated with this error. 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.
+   * @example
+   * ```jsx
+   * <FormError name="password" />
+   * ```
+   */
+  name: StringLike;
+}
+
+export type FormErrorProps<T extends ElementType = TagName> = Props<
+  T,
+  FormErrorOptions<T>
+>;

package/src/form/form-field.tsx

@@ -0,0 +1,94 @@
+import {
+  createElement,
+  createHook,
+  forwardRef,
+  memo,
+} from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import type { ElementType } from "react";
+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 `FormField` component. Unlike `useFormInput`, this
+ * hook doesn't automatically returns the `value` and `onChange` props. This is
+ * so we can use it not only for native form elements but also for custom
+ * components whose value is not controlled by the native `value` and `onChange`
+ * props.
+ * @deprecated Use `useFormControl` instead.
+ * @example
+ * ```jsx
+ * const store = useFormStore({ defaultValues: { content: "" } });
+ * const props = useFormField({ store, name: store.names.content });
+ * const value = store.useValue(store.names.content);
+ *
+ * <Form store={store}>
+ *   <FormLabel name={store.names.content}>Content</FormLabel>
+ *   <Role
+ *     {...props}
+ *     value={value}
+ *     onChange={(value) => store.setValue(store.names.content, value)}
+ *     render={<Editor />}
+ *   />
+ * </Form>
+ * ```
+ */
+export const useFormField = createHook<TagName, FormFieldOptions>(
+  function useFormField(props) {
+    return useFormControl(props);
+  },
+);
+
+/**
+ * Abstract component that renders a form field. Unlike
+ * [`FormInput`](https://ariakit.com/reference/form-input), this component
+ * doesn't automatically pass the `value` and `onChange` props down to the
+ * underlying element. This is so we can use it not only for native form
+ * elements but also for custom components whose value is not controlled by the
+ * native `value` and `onChange` props.
+ * @deprecated
+ * This component has been renamed to
+ * [`FormControl`](https://ariakit.com/reference/form-control). The API remains
+ * the same.
+ * @example
+ * ```jsx {11-19}
+ * const form = useFormStore({
+ *   defaultValues: {
+ *     content: "",
+ *   },
+ * });
+ *
+ * const value = form.useValue(form.names.content);
+ *
+ * <Form store={form}>
+ *   <FormLabel name={form.names.content}>Content</FormLabel>
+ *   <FormField
+ *     name={form.names.content}
+ *     render={
+ *       <Editor
+ *         value={value}
+ *         onChange={(value) => form.setValue(form.names.content, value)}
+ *       />
+ *     }
+ *   />
+ * </Form>
+ * ```
+ */
+export const FormField = memo(
+  forwardRef(function FormField(props: FormFieldProps) {
+    const htmlProps = useFormField(props);
+    return createElement(TagName, htmlProps);
+  }),
+);
+
+export interface FormFieldOptions<
+  T extends ElementType = TagName,
+> extends FormControlOptions<T> {}
+
+export type FormFieldProps<T extends ElementType = TagName> = Props<
+  T,
+  FormFieldOptions<T>
+>;

package/src/form/form-group-label.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 { GroupLabelOptions } from "../group/group-label.tsx";
+import { useGroupLabel } from "../group/group-label.tsx";
+import type { FormStore } from "./form-store.ts";
+
+const TagName = "div" satisfies ElementType;
+type TagName = typeof TagName;
+
+/**
+ * Returns props to create a `FormGroupLabel` component. This hook must be used
+ * in a component that's wrapped with `FormGroup` so the `aria-labelledby` prop
+ * is properly set on the form group element.
+ * @see https://ariakit.com/components/form
+ * @example
+ * ```jsx
+ * // This component must be wrapped with FormGroup
+ * const props = useFormGroupLabel();
+ * <Role {...props}>Label</Role>
+ * ```
+ */
+export const useFormGroupLabel = createHook<TagName, FormGroupLabelOptions>(
+  function useFormGroupLabel({ store, ...props }) {
+    props = useGroupLabel(props);
+    return props;
+  },
+);
+
+/**
+ * Renders a label in a form group. This component must be wrapped with the
+ * [`FormGroup`](https://ariakit.com/reference/form-group) or
+ * [`FormRadioGroup`](https://ariakit.com/reference/form-radio-group) components
+ * so the `aria-labelledby` prop is properly set on the form group element.
+ * @see https://ariakit.com/components/form
+ * @example
+ * ```jsx {10}
+ * const form = useFormStore({
+ *   defaultValues: {
+ *     username: "",
+ *     email: "",
+ *   },
+ * });
+ *
+ * <Form store={form}>
+ *   <FormGroup>
+ *     <FormGroupLabel>Account</FormGroupLabel>
+ *     <FormLabel name={form.names.username}>Username</FormLabel>
+ *     <FormInput name={form.names.username} />
+ *     <FormLabel name={form.names.email}>Email</FormLabel>
+ *     <FormInput name={form.names.email} />
+ *   </FormGroup>
+ * </Form>
+ * ```
+ */
+export const FormGroupLabel = forwardRef(function FormGroupLabel(
+  props: FormGroupLabelProps,
+) {
+  const htmlProps = useFormGroupLabel(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface FormGroupLabelOptions<
+  T extends ElementType = TagName,
+> extends GroupLabelOptions<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 FormGroupLabelProps<T extends ElementType = TagName> = Props<
+  T,
+  FormGroupLabelOptions<T>
+>;