@ariakit/react-components 0.1.0

package/src/form/form-submit.tsx

@@ -0,0 +1,93 @@
+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 = useFormSubmit({ store });
+ * <Form store={store}>
+ *   <Role {...props}>Submit</Role>
+ * </Form>
+ * ```
+ */
+export const useFormSubmit = createHook<TagName, FormSubmitOptions>(
+  function useFormSubmit({ store, accessibleWhenDisabled = true, ...props }) {
+    const context = useFormContext();
+    store = store || context;
+
+    invariant(
+      store,
+      process.env.NODE_ENV !== "production" &&
+        "FormSubmit must be wrapped in a Form component.",
+    );
+
+    props = {
+      type: "submit",
+      disabled: useStoreState(store, "submitting"),
+      ...props,
+    };
+
+    props = useButton({ ...props, accessibleWhenDisabled });
+
+    return props;
+  },
+);
+
+/**
+ * Renders a native submit button inside a form. The button will be
+ * [`disabled`](https://ariakit.com/reference/form-submit#disabled) while the
+ * form is submitting, but it will remain accessible to keyboard and screen
+ * reader users thanks to the
+ * [`accessibleWhenDisabled`](https://ariakit.com/reference/form-submit#accessiblewhendisabled)
+ * prop that's enabled by default.
+ * @see https://ariakit.com/components/form
+ * @example
+ * ```jsx {4}
+ * const form = useFormStore();
+ *
+ * <Form store={form}>
+ *   <FormSubmit>Submit</FormSubmit>
+ * </Form>
+ * ```
+ */
+export const FormSubmit = forwardRef(function FormSubmit(
+  props: FormSubmitProps,
+) {
+  const htmlProps = useFormSubmit(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface FormSubmitOptions<
+  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;
+  /**
+   * @default true
+   */
+  accessibleWhenDisabled?: ButtonOptions<T>["accessibleWhenDisabled"];
+}
+
+export type FormSubmitProps<T extends ElementType = TagName> = Props<
+  T,
+  FormSubmitOptions<T>
+>;

package/src/form/form.tsx

@@ -0,0 +1,249 @@
+import { useStoreState } from "@ariakit/react-store";
+import {
+  useEvent,
+  useInitialValue,
+  useMergeRefs,
+  useTagName,
+  useUpdateEffect,
+  useWrapElement,
+  createElement,
+  createHook,
+  forwardRef,
+} from "@ariakit/react-utils";
+import type { Options, Props } from "@ariakit/react-utils";
+import { isTextField, invariant } from "@ariakit/utils";
+import type { ElementType, FocusEvent, FormEvent } from "react";
+import { useEffect, useRef, useState } from "react";
+import { FormScopedContextProvider, useFormContext } from "./form-context.tsx";
+import type { FormStore, FormStoreState } from "./form-store.ts";
+
+const TagName = "form" satisfies ElementType;
+type TagName = typeof TagName;
+type HTMLType = HTMLElementTagNameMap[TagName];
+
+function isField(element: HTMLElement, items: FormStoreState["items"]) {
+  return items.some(
+    (item) => item.type === "field" && item.element === element,
+  );
+}
+
+function getFirstInvalidField(items: FormStoreState["items"]) {
+  return items.find(
+    (item) =>
+      item.type === "field" &&
+      item.element?.getAttribute("aria-invalid") === "true",
+  );
+}
+
+/**
+ * Returns props to create a `Form` component.
+ * @see https://ariakit.com/components/form
+ * @example
+ * ```jsx
+ * const store = useFormStore();
+ * const props = useForm({ store, render: <form /> });
+ * <Role {...props} />
+ * ```
+ */
+export const useForm = createHook<TagName, FormOptions>(function useForm({
+  store,
+  validateOnChange = true,
+  validateOnBlur = true,
+  resetOnUnmount = false,
+  resetOnSubmit = true,
+  autoFocusOnSubmit = true,
+  ...props
+}) {
+  const context = useFormContext();
+  store = store || context;
+
+  invariant(
+    store,
+    process.env.NODE_ENV !== "production" &&
+      "Form must receive a `store` prop or be wrapped in a FormProvider component.",
+  );
+
+  const ref = useRef<HTMLType>(null);
+  const values = useStoreState(store, "values");
+  const submitSucceed = useStoreState(store, "submitSucceed");
+  const submitFailed = useStoreState(store, "submitFailed");
+  const items = useStoreState(store, "items");
+  const defaultValues = useInitialValue(values);
+
+  useEffect(
+    () => (resetOnUnmount ? store?.reset : undefined),
+    [resetOnUnmount, store],
+  );
+
+  useUpdateEffect(() => {
+    if (!validateOnChange) return;
+    if (values === defaultValues) return;
+    void store?.validate();
+  }, [validateOnChange, values, defaultValues, store]);
+
+  useEffect(() => {
+    if (!resetOnSubmit) return;
+    if (!submitSucceed) return;
+    store?.reset();
+  }, [resetOnSubmit, submitSucceed, store]);
+
+  const [shouldFocusOnSubmit, setShouldFocusOnSubmit] = useState(false);
+
+  useEffect(() => {
+    if (!shouldFocusOnSubmit) return;
+    if (!submitFailed) return;
+    const field = getFirstInvalidField(items);
+    const element = field?.element;
+    if (!element) return;
+    setShouldFocusOnSubmit(false);
+    element.focus();
+    if (isTextField(element)) {
+      element.select();
+    }
+    // oxlint-disable-next-line exhaustive-deps
+  }, [autoFocusOnSubmit, submitFailed, items]);
+
+  const onSubmitProp = props.onSubmit;
+
+  const onSubmit = useEvent((event: FormEvent<HTMLType>) => {
+    onSubmitProp?.(event);
+    if (event.defaultPrevented) return;
+    event.preventDefault();
+    void store?.submit();
+    if (!autoFocusOnSubmit) return;
+    setShouldFocusOnSubmit(true);
+  });
+
+  const onBlurProp = props.onBlur;
+
+  const onBlur = useEvent((event: FocusEvent<HTMLType>) => {
+    onBlurProp?.(event);
+    if (event.defaultPrevented) return;
+    if (!validateOnBlur) return;
+    if (!store) return;
+    if (!isField(event.target, store.getState().items)) return;
+    void store.validate();
+  });
+
+  const onResetProp = props.onReset;
+
+  const onReset = useEvent((event: FormEvent<HTMLType>) => {
+    onResetProp?.(event);
+    if (event.defaultPrevented) return;
+    event.preventDefault();
+    store?.reset();
+  });
+
+  props = useWrapElement(
+    props,
+    (element) => (
+      <FormScopedContextProvider value={store}>
+        {element}
+      </FormScopedContextProvider>
+    ),
+    [store],
+  );
+
+  const tagName = useTagName(ref, TagName);
+
+  props = {
+    role: tagName !== "form" ? "form" : undefined,
+    noValidate: true,
+    ...props,
+    ref: useMergeRefs(ref, props.ref),
+    onSubmit,
+    onBlur,
+    onReset,
+  };
+
+  return props;
+});
+
+/**
+ * Renders a form element and provides a [form
+ * store](https://ariakit.com/reference/use-form-store) to its controls.
+ *
+ * The form is automatically validated on change and on blur. This behavior can
+ * be disabled with the
+ * [`validateOnChange`](https://ariakit.com/reference/form#validateonchange) and
+ * [`validateOnBlur`](https://ariakit.com/reference/form#validateonblur) props.
+ *
+ * When the form is submitted with errors, the first invalid field is
+ * automatically focused thanks to the
+ * [`autoFocusOnSubmit`](https://ariakit.com/reference/form#autofocusonsubmit)
+ * prop. If it's successful, the
+ * [`resetOnSubmit`](https://ariakit.com/reference/form#resetonsubmit) prop
+ * ensures the form is reset to its initial values as defined by the
+ * [`defaultValues`](https://ariakit.com/reference/use-form-store#defaultvalues)
+ * option on the [store](https://ariakit.com/reference/use-form-store).
+ * @see https://ariakit.com/components/form
+ * @example
+ * ```jsx {5-8}
+ * const form = useFormStore({
+ *   defaultValues: { username: "johndoe" },
+ * });
+ *
+ * <Form store={form}>
+ *   <FormLabel name={form.names.username}>Username</FormLabel>
+ *   <FormInput name={form.names.username} />
+ * </Form>
+ * ```
+ */
+export const Form = forwardRef(function Form(props: FormProps) {
+  const htmlProps = useForm(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface FormOptions<_T extends ElementType = TagName> extends Options {
+  /**
+   * Object returned by the
+   * [`useFormStore`](https://ariakit.com/reference/use-form-store) hook. If not
+   * provided, the closest
+   * [`FormProvider`](https://ariakit.com/reference/form-provider) component's
+   * context will be used.
+   */
+  store?: FormStore;
+  /**
+   * Determines if the form should invoke the validation callbacks registered
+   * with
+   * [`useValidate`](https://ariakit.com/reference/use-form-store#usevalidate)
+   * when the [`values`](https://ariakit.com/reference/use-form-store#values)
+   * change.
+   * @default true
+   */
+  validateOnChange?: boolean;
+  /**
+   * Determines if the form should invoke the validation callbacks registered
+   * with
+   * [`useValidate`](https://ariakit.com/reference/use-form-store#usevalidate)
+   * when a field loses focus.
+   * @default true
+   */
+  validateOnBlur?: boolean;
+  /**
+   * Determines if the form state should reset to its
+   * [`defaultValues`](https://ariakit.com/reference/use-form-store#defaultvalues)
+   * when the [`Form`](https://ariakit.com/reference/form) component is
+   * unmounted.
+   * @default false
+   */
+  resetOnUnmount?: boolean;
+  /**
+   * Determines if the form state should be reset to its
+   * [`defaultValues`](https://ariakit.com/reference/use-form-store#defaultvalues)
+   * upon successful form submission.
+   * @default true
+   */
+  resetOnSubmit?: boolean;
+  /**
+   * Determines if the form should automatically focus on the first invalid
+   * field when the form is submitted.
+   * @default true
+   */
+  autoFocusOnSubmit?: boolean;
+}
+
+export type FormProps<T extends ElementType = TagName> = Props<
+  T,
+  FormOptions<T>
+>;

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

@@ -0,0 +1,6 @@
+import type { SetState } from "@ariakit/utils";
+import { createContext } from "react";
+
+export const GroupLabelContext = createContext<
+  SetState<string | undefined> | undefined
+>(undefined);

package/src/group/group-label.tsx

@@ -0,0 +1,75 @@
+import {
+  useId,
+  useSafeLayoutEffect,
+  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 { GroupLabelContext } from "./group-label-context.tsx";
+
+const TagName = "div" satisfies ElementType;
+type TagName = typeof TagName;
+
+/**
+ * Returns props to create a `GroupLabel` component. This hook must be used in a
+ * component that's wrapped with `Group` so the `aria-labelledby` prop is
+ * properly set on the group element.
+ * @see https://ariakit.com/components/group
+ * @example
+ * ```jsx
+ * // This component must be wrapped with Group
+ * const props = useGroupLabel();
+ * <Role {...props}>Label</Role>
+ * ```
+ */
+export const useGroupLabel = createHook<TagName, GroupLabelOptions>(
+  function useGroupLabel(props) {
+    const setLabelId = useContext(GroupLabelContext);
+    const id = useId(props.id);
+
+    useSafeLayoutEffect(() => {
+      setLabelId?.(id);
+      return () => setLabelId?.(undefined);
+    }, [setLabelId, id]);
+
+    props = {
+      "aria-hidden": true,
+      ...props,
+      id,
+    };
+
+    return removeUndefinedValues(props);
+  },
+);
+
+/**
+ * Renders a label in a group. This component should be wrapped with a
+ * [`Group`](https://ariakit.com/reference/group) so the `aria-labelledby`
+ * prop is correctly set on the group element.
+ * @see https://ariakit.com/components/group
+ * @example
+ * ```jsx
+ * <Group>
+ *   <GroupLabel>Label</GroupLabel>
+ * </Group>
+ * ```
+ */
+export const GroupLabel = forwardRef(function GroupLabel(
+  props: GroupLabelProps,
+) {
+  const htmlProps = useGroupLabel(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface GroupLabelOptions<
+  _T extends ElementType = TagName,
+> extends Options {}
+
+export type GroupLabelProps<T extends ElementType = TagName> = Props<
+  T,
+  GroupLabelOptions<T>
+>;

package/src/group/group.tsx

@@ -0,0 +1,69 @@
+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 { useState } from "react";
+import { GroupLabelContext } from "./group-label-context.tsx";
+
+const TagName = "div" satisfies ElementType;
+type TagName = typeof TagName;
+
+/**
+ * Returns props to create a `Group` component.
+ * @see https://ariakit.com/components/group
+ * @example
+ * ```jsx
+ * const props = useGroup();
+ * <Role {...props}>Group</Role>
+ * ```
+ */
+export const useGroup = createHook<TagName, GroupOptions>(
+  function useGroup(props) {
+    const [labelId, setLabelId] = useState<string>();
+
+    props = useWrapElement(
+      props,
+      (element) => (
+        <GroupLabelContext.Provider value={setLabelId}>
+          {element}
+        </GroupLabelContext.Provider>
+      ),
+      [],
+    );
+
+    props = {
+      role: "group",
+      "aria-labelledby": props["aria-label"] != null ? undefined : labelId,
+      ...props,
+    };
+
+    return removeUndefinedValues(props);
+  },
+);
+
+/**
+ * Renders a group element. Optionally, a
+ * [`GroupLabel`](https://ariakit.com/reference/group-label) can be rendered as
+ * a child to provide a label for the group.
+ * @see https://ariakit.com/components/group
+ * @example
+ * ```jsx
+ * <Group>Group</Group>
+ * ```
+ */
+export const Group = forwardRef(function Group(props: GroupProps) {
+  const htmlProps = useGroup(props);
+  return createElement(TagName, htmlProps);
+});
+
+export type GroupOptions<_T extends ElementType = TagName> = Options;
+
+export type GroupProps<T extends ElementType = TagName> = Props<
+  T,
+  GroupOptions<T>
+>;

package/src/heading/heading-context.tsx

@@ -0,0 +1,4 @@
+import { createContext } from "react";
+import type { HeadingLevels } from "./utils.ts";
+
+export const HeadingContext = createContext<HeadingLevels | 0>(0);

package/src/heading/heading-level.tsx

@@ -0,0 +1,42 @@
+import type { ReactNode } from "react";
+import { useContext } from "react";
+import { HeadingContext } from "./heading-context.tsx";
+import type { HeadingLevels } from "./utils.ts";
+
+/**
+ * A component that sets the heading level for its children. It doesn't render
+ * any HTML element, just sets the
+ * [`level`](https://ariakit.com/reference/heading-level#level) prop on the
+ * context.
+ * @see https://ariakit.com/components/heading
+ * @example
+ * ```jsx
+ * <HeadingLevel>
+ *   <Heading>Heading 1</Heading>
+ *   <HeadingLevel>
+ *     <Heading>Heading 2</Heading>
+ *   </HeadingLevel>
+ * </HeadingLevel>
+ * ```
+ */
+export function HeadingLevel({ level, children }: HeadingLevelProps) {
+  const contextLevel = useContext(HeadingContext);
+  const nextLevel = Math.max(
+    Math.min(level || contextLevel + 1, 6),
+    1,
+  ) as HeadingLevels;
+  return (
+    <HeadingContext.Provider value={nextLevel}>
+      {children}
+    </HeadingContext.Provider>
+  );
+}
+
+export interface HeadingLevelProps {
+  /**
+   * The heading level. By default, it'll increase the level by 1 based on the
+   * context.
+   */
+  level?: HeadingLevels;
+  children?: ReactNode;
+}

package/src/heading/heading.tsx

@@ -0,0 +1,81 @@
+import {
+  useMergeRefs,
+  useTagName,
+  createElement,
+  createHook,
+  forwardRef,
+} from "@ariakit/react-utils";
+import type { Options, Props } from "@ariakit/react-utils";
+import type { ElementType } from "react";
+import { useContext, useMemo, useRef } from "react";
+import { HeadingContext } from "./heading-context.tsx";
+import type { HeadingLevels } from "./utils.ts";
+
+type HeadingElements = `h${HeadingLevels}`;
+const TagName = "h1" satisfies ElementType;
+type TagName = HeadingElements;
+type HTMLType = HTMLElementTagNameMap[TagName];
+
+/**
+ * Returns props to create a `Heading` component. The element type (or the
+ * `aria-level` prop, if the element type is not a native heading) is determined
+ * by the context level provided by the parent `HeadingLevel` component.
+ * @see https://ariakit.com/components/heading
+ * @example
+ * ```jsx
+ * const props = useHeading();
+ * <Role {...props}>Heading</Role>
+ * ```
+ */
+export const useHeading = createHook<TagName, HeadingOptions>(
+  function useHeading(props) {
+    const ref = useRef<HTMLType>(null);
+    const level: HeadingLevels = useContext(HeadingContext) || 1;
+    const Element = `h${level}` as const;
+    const tagName = useTagName(ref, Element);
+    const isNativeHeading = useMemo(
+      () => !!tagName && /^h\d$/.test(tagName),
+      [tagName],
+    );
+
+    props = {
+      render: <Element />,
+      role: !isNativeHeading ? "heading" : undefined,
+      "aria-level": !isNativeHeading ? level : undefined,
+      ...props,
+      ref: useMergeRefs(ref, props.ref),
+    };
+
+    return props;
+  },
+);
+
+/**
+ * Renders a heading element. The element type (or the `aria-level` attribute,
+ * if the element type is not a native heading) is determined by the context
+ * level provided by the closest
+ * [`HeadingLevel`](https://ariakit.com/reference/heading-level) ancestor.
+ * @see https://ariakit.com/components/heading
+ * @example
+ * ```jsx
+ * <HeadingLevel>
+ *   <Heading>Heading 1</Heading>
+ *   <HeadingLevel>
+ *     <Heading>Heading 2</Heading>
+ *   </HeadingLevel>
+ * </HeadingLevel>
+ * ```
+ */
+export const Heading = forwardRef(function Heading(props: HeadingProps) {
+  const htmlProps = useHeading(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface HeadingOptions<
+  _T extends ElementType = TagName,
+> extends Options {}
+
+export type HeadingProps<T extends ElementType = TagName> = Props<
+  T,
+  HeadingOptions<T>
+>;

package/src/heading/utils.ts

@@ -0,0 +1 @@
+export type HeadingLevels = 1 | 2 | 3 | 4 | 5 | 6;