@ariakit/react-components 0.1.0

package/src/form/form-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 { GroupOptions } from "../group/group.tsx";
+import { useGroup } from "../group/group.tsx";
+import type { FormStore } from "./form-store.ts";
+
+const TagName = "div" satisfies ElementType;
+type TagName = typeof TagName;
+
+/**
+ * Returns props to create a `FormGroup` component.
+ * @see https://ariakit.com/components/form
+ * @example
+ * ```jsx
+ * const store = useFormStore();
+ * const props = useFormGroup({ store });
+ * <Form store={store}>
+ *   <Role {...props}>
+ *     <FormGroupLabel>Label</FormGroupLabel>
+ *   </Role>
+ * </Form>
+ * ```
+ */
+export const useFormGroup = createHook<TagName, FormGroupOptions>(
+  function useFormGroup({ store, ...props }) {
+    props = useGroup(props);
+    return props;
+  },
+);
+
+/**
+ * Renders a group element for form controls. 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 {9-15}
+ * 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 FormGroup = forwardRef(function FormGroup(props: FormGroupProps) {
+  const htmlProps = useFormGroup(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface FormGroupOptions<
+  T extends ElementType = TagName,
+> extends GroupOptions<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 FormGroupProps<T extends ElementType = TagName> = Props<
+  T,
+  FormGroupOptions<T>
+>;

package/src/form/form-input.tsx

@@ -0,0 +1,104 @@
+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 { FocusableOptions } from "../focusable/focusable.tsx";
+import { useFocusable } from "../focusable/focusable.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;
+type HTMLType = HTMLElementTagNameMap[TagName];
+
+/**
+ * Returns props to create a `FormInput` component. Unlike `useFormControl`, this
+ * hook returns the `value` and `onChange` props that can be passed to a native
+ * input, select or textarea elements.
+ * @see https://ariakit.com/components/form
+ * @example
+ * ```jsx
+ * const store = useFormStore({ defaultValues: { email: "" } });
+ * const props = useFormInput({ store, name: store.names.email });
+ * <Form store={store}>
+ *   <FormLabel name={store.names.email}>Email</FormLabel>
+ *   <Role {...props} render={<input />} />
+ * </Form>
+ * ```
+ */
+export const useFormInput = createHook<TagName, FormInputOptions>(
+  function useFormInput({ store, name: nameProp, ...props }) {
+    const context = useFormContext();
+    store = store || context;
+
+    invariant(
+      store,
+      process.env.NODE_ENV !== "production" &&
+        "FormInput must be wrapped in a Form component.",
+    );
+
+    const name = String(nameProp);
+    const onChangeProp = props.onChange;
+
+    const onChange = useEvent((event: ChangeEvent<HTMLType>) => {
+      onChangeProp?.(event);
+      if (event.defaultPrevented) return;
+      store?.setValue(name, event.target.value);
+    });
+
+    const value = store.useValue(name);
+
+    props = {
+      value,
+      ...props,
+      onChange,
+    };
+
+    props = useFocusable<TagName>(props);
+    props = useFormControl({ store, name, ...props });
+
+    return props;
+  },
+);
+
+/**
+ * Renders a form input. Unlike
+ * [`FormControl`](https://ariakit.com/reference/form-control), this component
+ * passes the `value` and `onChange` props down to the underlying element that
+ * can be native input, select or textarea elements.
+ * @see https://ariakit.com/components/form
+ * @example
+ * ```jsx {9}
+ * const form = useFormStore({
+ *   defaultValues: {
+ *     email: "",
+ *   },
+ * });
+ *
+ * <Form store={form}>
+ *   <FormLabel name={form.names.email}>Email</FormLabel>
+ *   <FormInput name={form.names.email} />
+ * </Form>
+ * ```
+ */
+export const FormInput = memo(
+  forwardRef(function FormInput(props: FormInputProps) {
+    const htmlProps = useFormInput(props);
+    return createElement(TagName, htmlProps);
+  }),
+);
+
+export interface FormInputOptions<T extends ElementType = TagName>
+  extends FormControlOptions<T>, FocusableOptions<T> {}
+
+export type FormInputProps<T extends ElementType = TagName> = Props<
+  T,
+  FormInputOptions<T>
+>;

package/src/form/form-label.tsx

@@ -0,0 +1,192 @@
+import type { StringLike } from "@ariakit/components/form/types";
+import { useStoreState } from "@ariakit/react-store";
+import {
+  useEvent,
+  useId,
+  useMergeRefs,
+  useTagName,
+  createElement,
+  createHook,
+  forwardRef,
+  memo,
+} from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import { getFirstTabbableIn, invariant } from "@ariakit/utils";
+import type { ElementType, MouseEvent } 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 = "label" satisfies ElementType;
+type TagName = typeof TagName;
+type HTMLType = HTMLElementTagNameMap[TagName];
+
+function supportsNativeLabel(tagName?: string) {
+  return (
+    tagName === "input" ||
+    tagName === "textarea" ||
+    tagName === "select" ||
+    tagName === "meter" ||
+    tagName === "progress"
+  );
+}
+
+/**
+ * Returns props to create a `FormLabel` component. If the field is not a native
+ * input, select or textarea element, the hook will return props to render a
+ * `span` element. Instead of relying on the `htmlFor` prop, it'll rely on the
+ * `aria-labelledby` attribute on the form field. Clicking on the label will
+ * move focus to the field even if it's not a native input.
+ * @see https://ariakit.com/components/form
+ * @example
+ * ```jsx
+ * const store = useFormStore({ defaultValues: { email: "" } });
+ * const props = useFormLabel({ store, name: store.names.email });
+ * <Form store={store}>
+ *   <Role {...props}>Email</Role>
+ *   <FormInput name={store.names.email} />
+ * </Form>
+ * ```
+ */
+export const useFormLabel = createHook<TagName, FormLabelOptions>(
+  function useFormLabel({
+    store,
+    name: nameProp,
+    getItem: getItemProp,
+    ...props
+  }) {
+    const context = useFormContext();
+    store = store || context;
+
+    invariant(
+      store,
+      process.env.NODE_ENV !== "production" &&
+        "FormLabel 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: "label" };
+        if (getItemProp) {
+          return getItemProp(nextItem);
+        }
+        return nextItem;
+      },
+      [id, name, getItemProp],
+    );
+
+    const field = useStoreState(store, (state) =>
+      state.items.find((item) => item.type === "field" && item.name === name),
+    );
+    const fieldTagName = useTagName(field?.element, "input");
+    const isNativeLabel = supportsNativeLabel(fieldTagName);
+
+    const onClickProp = props.onClick;
+
+    const onClick = useEvent((event: MouseEvent<HTMLLabelElement>) => {
+      onClickProp?.(event);
+      if (event.defaultPrevented) return;
+      if (isNativeLabel) return;
+      const fieldElement = field?.element;
+      if (!fieldElement) return;
+      queueMicrotask(() => {
+        const focusableElement = getFirstTabbableIn(fieldElement, true, true);
+        focusableElement?.focus();
+        const role = focusableElement?.getAttribute("role");
+        // If the field is a combobox, we don't want to click on it, as it'll
+        // open the listbox.
+        if (role === "combobox") return;
+        focusableElement?.click();
+      });
+    });
+
+    props = {
+      render: isNativeLabel ? <label /> : <span />,
+      htmlFor: isNativeLabel ? field?.id : undefined,
+      ...props,
+      id,
+      ref: useMergeRefs(ref, props.ref),
+      onClick,
+    };
+
+    if (!isNativeLabel) {
+      props = {
+        ...props,
+        style: {
+          cursor: "default",
+          ...props.style,
+        },
+      };
+    }
+
+    props = useCollectionItem<TagName>({ store, ...props, getItem });
+
+    return props;
+  },
+);
+
+/**
+ * Renders a label associated with a form field, even if the field is not a
+ * native input.
+ *
+ * If the field is a native input, select or textarea element, this component
+ * will render a native `label` element and rely on its `htmlFor` prop.
+ * Otherwise, it'll render a `span` element and rely on the `aria-labelledby`
+ * attribute on the form field instead. Clicking on the label will move focus to
+ * the field even if it's not a native input.
+ * @see https://ariakit.com/components/form
+ * @example
+ * ```jsx {8}
+ * const form = useFormStore({
+ *   defaultValues: {
+ *     email: "",
+ *   },
+ * });
+ *
+ * <Form store={form}>
+ *   <FormLabel name={form.names.email}>Email</Role>
+ *   <FormInput name={form.names.email} />
+ * </Form>
+ * ```
+ */
+export const FormLabel = memo(
+  forwardRef(function FormLabel(props: FormLabelProps) {
+    const htmlProps = useFormLabel(props);
+    return createElement(TagName, htmlProps);
+  }),
+);
+
+export interface FormLabelOptions<
+  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 labeled 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
+   * <FormLabel name="email">Email</FormLabel>
+   * ```
+   */
+  name: StringLike;
+}
+
+export type FormLabelProps<T extends ElementType = TagName> = Props<
+  T,
+  FormLabelOptions<T>
+>;

package/src/form/form-provider.tsx

@@ -0,0 +1,49 @@
+import type { FormStoreValues } from "@ariakit/components/form/form-store";
+import type { PickRequired } from "@ariakit/utils";
+import type { ReactElement, ReactNode } from "react";
+import { FormContextProvider } from "./form-context.tsx";
+import type { FormStoreProps } from "./form-store.ts";
+import { useFormStore } from "./form-store.ts";
+
+type Values = FormStoreValues;
+
+/**
+ * Provides a form store to [Form](https://ariakit.com/components/form)
+ * components.
+ * @see https://ariakit.com/components/form
+ * @example
+ * ```jsx
+ * <FormProvider defaultValues={{ email: "" }}>
+ *   <Form>
+ *     <FormInput />
+ *   </Form>
+ * </FormProvider>
+ * ```
+ */
+
+export function FormProvider<T extends Values = Values>(
+  props: PickRequired<
+    FormProviderProps<T>,
+    | "values"
+    | "defaultValues"
+    | "errors"
+    | "defaultErrors"
+    | "touched"
+    | "defaultTouched"
+  >,
+): ReactElement;
+
+export function FormProvider(props: FormProviderProps): ReactElement;
+
+export function FormProvider(props: FormProviderProps = {}) {
+  const store = useFormStore(props);
+  return (
+    <FormContextProvider value={store}>{props.children}</FormContextProvider>
+  );
+}
+
+export interface FormProviderProps<
+  T extends Values = Values,
+> extends FormStoreProps<T> {
+  children?: ReactNode;
+}

package/src/form/form-push.tsx

@@ -0,0 +1,200 @@
+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 { invariant } from "@ariakit/utils";
+import type { ElementType, MouseEvent } from "react";
+import { useCallback, useEffect, useState } from "react";
+import type { ButtonOptions } from "../button/button.tsx";
+import { useButton } from "../button/button.tsx";
+import type { CollectionItemOptions } from "../collection/collection-item.tsx";
+import { useCollectionItem } from "../collection/collection-item.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 getFirstFieldsByName(
+  items: FormStoreState["items"] | undefined,
+  name: string,
+) {
+  if (!items) return [];
+  const fields: FormStoreState["items"] = [];
+  for (const item of items) {
+    if (item.type !== "field") continue;
+    if (!item.name.startsWith(name)) continue;
+    const nameWithIndex = item.name.replace(/(\.\d+)\..+$/, "$1");
+    const regex = new RegExp(`^${nameWithIndex}`);
+    if (!fields.some((i) => regex.test(i.name))) {
+      fields.push(item);
+    }
+  }
+  return fields;
+}
+
+/**
+ * Returns props to create a `FormPush` component.
+ * @see https://ariakit.com/components/form
+ * @example
+ * ```jsx
+ * const store = useFormStore({
+ *   defaultValues: {
+ *     languages: ["JavaScript", "PHP"],
+ *   },
+ * });
+ * const props = useFormPush({
+ *   store,
+ *   name: store.names.languages,
+ *   value: "",
+ * });
+ * const values = useStoreState(store, "values");
+ *
+ * <Form store={store}>
+ *   {values.languages.map((_, i) => (
+ *     <FormInput key={i} name={store.names.languages[i]} />
+ *   ))}
+ *   <Role {...props}>Add new language</Role>
+ * </Form>
+ * ```
+ */
+export const useFormPush = createHook<TagName, FormPushOptions>(
+  function useFormPush({
+    store,
+    value,
+    name: nameProp,
+    getItem: getItemProp,
+    autoFocusOnClick = true,
+    ...props
+  }) {
+    const context = useFormContext();
+    store = store || context;
+
+    invariant(
+      store,
+      process.env.NODE_ENV !== "production" &&
+        "FormPush must be wrapped in a Form component.",
+    );
+
+    const name = String(nameProp);
+    const [shouldFocus, setShouldFocus] = useState(false);
+
+    useEffect(() => {
+      if (!shouldFocus) return;
+      const items = getFirstFieldsByName(store?.getState().items, name);
+      const element = items?.[items.length - 1]?.element;
+      if (!element) return;
+      element.focus();
+      setShouldFocus(false);
+    }, [store, shouldFocus, name]);
+
+    const getItem = useCallback<NonNullable<CollectionItemOptions["getItem"]>>(
+      (item) => {
+        const nextItem = { ...item, type: "button", name };
+        if (getItemProp) {
+          return getItemProp(nextItem);
+        }
+        return nextItem;
+      },
+      [name, getItemProp],
+    );
+
+    const onClickProp = props.onClick;
+
+    const onClick = useEvent((event: MouseEvent<HTMLType>) => {
+      onClickProp?.(event);
+      if (event.defaultPrevented) return;
+      store?.pushValue(name, value);
+      if (!autoFocusOnClick) return;
+      setShouldFocus(true);
+    });
+
+    props = {
+      ...props,
+      onClick,
+    };
+
+    props = useButton(props);
+    props = useCollectionItem<TagName>({ store, ...props, getItem });
+
+    return props;
+  },
+);
+
+/**
+ * Renders a button that will push items to an array value in the form store
+ * when clicked.
+ *
+ * The [`name`](https://ariakit.com/reference/form-push#name) prop needs to be
+ * provided to identify the array field. The
+ * [`value`](https://ariakit.com/reference/form-push#value) prop is required to
+ * define the value that will be added to the array.
+ *
+ * By default, the newly added input will be automatically focused when the
+ * button is clicked unless the
+ * [`autoFocusOnClick`](https://ariakit.com/reference/form-push#autofocusonclick)
+ * prop is set to `false`.
+ * @see https://ariakit.com/components/form
+ * @example
+ * ```jsx {13-15}
+ * const form = useFormStore({
+ *   defaultValues: {
+ *     languages: ["JavaScript", "PHP"],
+ *   },
+ * });
+ *
+ * const values = useStoreState(form, "values");
+ *
+ * <Form store={form}>
+ *   {values.languages.map((_, i) => (
+ *     <FormInput key={i} name={form.names.languages[i]} />
+ *   ))}
+ *   <FormPush name={form.names.languages} value="">
+ *     Add new language
+ *   </FormPush>
+ * </Form>
+ * ```
+ */
+export const FormPush = forwardRef(function FormPush(props: FormPushProps) {
+  const htmlProps = useFormPush(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface FormPushOptions<T extends ElementType = TagName>
+  extends ButtonOptions<T>, 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 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;
+  /**
+   * Value that will initially be assigned to the array item when it's pushed.
+   */
+  value: unknown;
+  /**
+   * Whether the newly added input should be automatically focused when the
+   * button is clicked.
+   * @default true
+   */
+  autoFocusOnClick?: boolean;
+}
+
+export type FormPushProps<T extends ElementType = TagName> = Props<
+  T,
+  FormPushOptions<T>
+>;