@ariakit/react-components 0.1.0

package/src/tag/tag-context.tsx

@@ -0,0 +1,40 @@
+import { createStoreContext } from "@ariakit/react-utils";
+import { createContext } from "react";
+import {
+  CompositeContextProvider,
+  CompositeScopedContextProvider,
+} from "../composite/composite-context.tsx";
+import type { TagStore } from "./tag-store.ts";
+
+export const TagValueContext = createContext<string | null>(null);
+export const TagRemoveIdContext = createContext<((id?: string) => void) | null>(
+  null,
+);
+
+const ctx = createStoreContext<TagStore>(
+  [CompositeContextProvider],
+  [CompositeScopedContextProvider],
+);
+
+/**
+ * Returns the tag store from the nearest tag container.
+ * @example
+ * function Tag() {
+ *   const store = useTagContext();
+ *
+ *   if (!store) {
+ *     throw new Error("Tag must be wrapped in TagProvider");
+ *   }
+ *
+ *   // Use the store...
+ * }
+ */
+export const useTagContext = ctx.useContext;
+
+export const useTagScopedContext = ctx.useScopedContext;
+
+export const useTagProviderContext = ctx.useProviderContext;
+
+export const TagContextProvider = ctx.ContextProvider;
+
+export const TagScopedContextProvider = ctx.ScopedContextProvider;

package/src/tag/tag-input.tsx

@@ -0,0 +1,321 @@
+import { useStoreState } from "@ariakit/react-store";
+import {
+  useBooleanEvent,
+  useEvent,
+  useMergeRefs,
+  createElement,
+  createHook,
+  forwardRef,
+} from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import {
+  toArray,
+  getTextboxSelection,
+  setSelectionRange,
+  getInputType,
+  invariant,
+  UndoManager,
+} from "@ariakit/utils";
+import type { BooleanOrCallback } from "@ariakit/utils";
+import type {
+  ChangeEvent,
+  ClipboardEvent,
+  ElementType,
+  KeyboardEvent,
+  SyntheticEvent,
+} from "react";
+import type { CompositeItemOptions } from "../composite/composite-item.tsx";
+import { useCompositeItem } from "../composite/composite-item.tsx";
+import { useTagContext } from "./tag-context.tsx";
+import type { TagStore } from "./tag-store.ts";
+
+const TagName = "input" satisfies ElementType;
+type TagName = typeof TagName;
+type HTMLType = HTMLElementTagNameMap[TagName];
+
+type EventWithValues<T extends SyntheticEvent> = T & {
+  values: string[];
+};
+
+const DEFAULT_DELIMITER = ["\n", ";", ",", /\s/];
+
+function getDelimiters(
+  delimiter: TagInputOptions["delimiter"],
+  defaultDelimiter: TagInputOptions["delimiter"] = DEFAULT_DELIMITER,
+) {
+  const finalDelimiter = delimiter === undefined ? defaultDelimiter : delimiter;
+  if (!finalDelimiter) return [];
+  return toArray(finalDelimiter);
+}
+
+function splitValueByDelimiter(value: string, delimiters: (string | RegExp)[]) {
+  for (const delimiter of delimiters) {
+    let match = value.match(delimiter);
+    // Remove delimiter from the start of the string
+    while (match?.index === 0) {
+      value = value.slice(match[0].length);
+      match = value.match(delimiter);
+    }
+    if (!match) continue;
+    return value.split(delimiter);
+  }
+  return [];
+}
+
+/**
+ * Returns props to create a `TagInput` component.
+ * @see https://ariakit.com/components/tag
+ * @example
+ * ```jsx
+ * const props = useTagInput();
+ * <Role.input {...props} />
+ * ```
+ */
+export const useTagInput = createHook<TagName, TagInputOptions>(
+  function useTagInput({
+    store,
+    tabbable = true,
+    delimiter,
+    addValueOnPaste = true,
+    addValueOnChange = true,
+    setValueOnChange = true,
+    removeOnBackspace = true,
+    ...props
+  }) {
+    const context = useTagContext();
+    store = store || context;
+
+    invariant(
+      store,
+      process.env.NODE_ENV !== "production" &&
+        "TagInput must receive a `store` prop or be wrapped in a TagProvider component.",
+    );
+
+    const value = useStoreState(store, "value");
+
+    const onPasteProp = props.onPaste;
+    const addValueOnPasteProp = useBooleanEvent(addValueOnPaste);
+
+    const onPaste = useEvent((event: ClipboardEvent<HTMLType>) => {
+      onPasteProp?.(event);
+      if (event.defaultPrevented) return;
+      const text = event.clipboardData.getData("text");
+      const delimiters = getDelimiters(delimiter);
+      const values = splitValueByDelimiter(text.trim(), delimiters)
+        .map((value) => value.trim())
+        .filter((value) => value !== "");
+      // Create a new event with the values extracted from the clipboard text so
+      // that the user can use the values in the event handler.
+      const eventWithValues = Object.assign(event, { values });
+      if (!addValueOnPasteProp(eventWithValues)) return;
+      if (!values.length) return;
+      // Prevent pasting the text into the input
+      event.preventDefault();
+      for (const tagValue of values) {
+        store.addValue(tagValue);
+      }
+    });
+
+    const onChangeProp = props.onChange;
+    const setValueOnChangeProp = useBooleanEvent(setValueOnChange);
+    const addValueOnChangeProp = useBooleanEvent(addValueOnChange);
+
+    const onChange = useEvent((event: ChangeEvent<HTMLType>) => {
+      onChangeProp?.(event);
+      if (event.defaultPrevented) return;
+      if (!store) return;
+      const { value: prevValue } = store.getState();
+      const inputType = getInputType(event);
+      const currentTarget = event.currentTarget;
+      const { start, end } = getTextboxSelection(currentTarget);
+      const { value } = currentTarget;
+      // Set the value in the store if the value changes
+      if (setValueOnChangeProp(event)) {
+        void UndoManager.execute(() => {
+          store.setValue(value);
+          // When the value is not set synchronously, the selection range may be
+          // lost.
+          queueMicrotask(() => {
+            setSelectionRange(currentTarget, start, end);
+          });
+          if (value === prevValue) return;
+          return () => store.setValue(prevValue);
+        }, inputType);
+      }
+      // Add values to the store if the input value ends with a delimiter
+      const isTrailingCaret = start === end && start === value.length;
+      if (isTrailingCaret) {
+        const delimiters = getDelimiters(delimiter);
+        // Split values and get the trailing value that will remain in the input
+        let values = splitValueByDelimiter(value, delimiters);
+        const trailingvalue = values.pop() || "";
+        values = values
+          .map((value) => value.trim())
+          .filter((value) => value !== "");
+        const eventWithValues = Object.assign(event, { values });
+        if (values.length && addValueOnChangeProp(eventWithValues)) {
+          // We need to prevent the default behavior here in case the tag input
+          // component is combined with another component that also listens to the
+          // change event and updates the store value, such as Combobox. In this
+          // case, the tag input logic should take precedence even if this event
+          // handler is called first.
+          event.preventDefault();
+          for (const tagValue of values) {
+            store.addValue(tagValue);
+          }
+          void UndoManager.execute(() => {
+            store.setValue(trailingvalue);
+            if (trailingvalue === prevValue) return;
+            return () => store.setValue(prevValue);
+          }, inputType);
+        }
+      }
+    });
+
+    const onKeyDownProp = props.onKeyDown;
+    const removeOnBackspaceProp = useBooleanEvent(removeOnBackspace);
+
+    const onKeyDown = useEvent((event: KeyboardEvent<HTMLType>) => {
+      onKeyDownProp?.(event);
+      if (event.defaultPrevented) return;
+      if (event.key === "Backspace" && removeOnBackspaceProp(event)) {
+        const { start, end } = getTextboxSelection(event.currentTarget);
+        const isLeadingCaret = start === end && start === 0;
+        if (!isLeadingCaret) return;
+        store.setValues((values) => {
+          if (!values.length) return values;
+          return values.slice(0, -1);
+        });
+      }
+    });
+
+    props = {
+      value,
+      ...props,
+      ref: useMergeRefs(store.setInputElement, props.ref),
+      onPaste,
+      onChange,
+      onKeyDown,
+    };
+
+    props = useCompositeItem<TagName>({ store, tabbable, ...props });
+
+    return props;
+  },
+);
+
+/**
+ * Renders an input element within a
+ * [`TagList`](https://ariakit.com/reference/tag-list) component. This component
+ * lets users input tag values that are added to the store when the input value
+ * changes or when the user pastes text into the input element, based on the
+ * [`delimiter`](https://ariakit.com/reference/tag-input#delimiter) prop.
+ *
+ * This component can be combined with a
+ * [`Combobox`](https://ariakit.com/reference/combobox) component using the
+ * [`render`](https://ariakit.com/reference/tag-input#render) prop to create a
+ * tag input with suggestions.
+ * @see https://ariakit.com/components/tag
+ * @example
+ * ```jsx {14}
+ * <TagProvider>
+ *   <TagListLabel>Invitees</TagListLabel>
+ *   <TagList>
+ *     <TagValues>
+ *       {(values) =>
+ *         values.map((value) => (
+ *           <Tag key={value} value={value}>
+ *             {value}
+ *             <TagRemove />
+ *           </Tag>
+ *         ))
+ *       }
+ *     </TagValues>
+ *     <TagInput />
+ *   </TagList>
+ * </TagProvider>
+ * ```
+ */
+export const TagInput = forwardRef(function TagInput(props: TagInputProps) {
+  const htmlProps = useTagInput(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface TagInputOptions<
+  T extends ElementType = TagName,
+> extends CompositeItemOptions<T> {
+  /**
+   * Object returned by the
+   * [`useTagStore`](https://ariakit.com/reference/use-tag-store) hook. If not
+   * provided, the closest
+   * [`TagProvider`](https://ariakit.com/reference/tag-provider) component's
+   * context will be used.
+   */
+  store?: TagStore;
+  /**
+   * The string or pattern employed to break the input value into multiple tags.
+   * This could be a string, a regular expression, an array of strings and
+   * regular expressions, or `null` to prevent splitting on input.
+   *
+   * When an array is given, the input value is split by the first matching
+   * delimiter. All other delimiters are disregarded for the same input event.
+   * For example, if the delimiters are `["\n", ","]` and the user pastes text
+   * containing commas and newlines, the text will be split solely by newlines.
+   * The commas will be preserved in the tag values. If you want to split by
+   * both commas and newlines, you should use a regular expression that matches
+   * both characters (e.g., `/[\n,]/`).
+   * @default ["\n", ";", ",", /\s/]
+   */
+  delimiter?: string | RegExp | null | (string | RegExp)[];
+  /**
+   * Determines if tag values should be added to the store when the input value
+   * is pasted. The values are extracted from the clipboard text and
+   * automatically processed with the
+   * [`delimiter`](https://ariakit.com/reference/tag-input#delimiter) prop.
+   *
+   * This can be either a boolean or a callback that receives an event with an
+   * extra `values` property and should return a boolean.
+   * @default true
+   */
+  addValueOnPaste?: BooleanOrCallback<
+    EventWithValues<ClipboardEvent<HTMLElement>>
+  >;
+  /**
+   * Determines if the tag value should be added to the store when the input
+   * value changes. The tag value is automatically processed with the
+   * [`delimiter`](https://ariakit.com/reference/tag-input#delimiter) prop.
+   *
+   * This can be either a boolean or a callback that receives an event with an
+   * extra `values` property and should return a boolean.
+   * @default true
+   */
+  addValueOnChange?: BooleanOrCallback<
+    EventWithValues<ChangeEvent<HTMLElement>>
+  >;
+  /**
+   * Whether the tag
+   * [`value`](https://ariakit.com/reference/tag-provider#value) state
+   * should be updated when the input value changes. This is useful if you want
+   * to customize how the store
+   * [`value`](https://ariakit.com/reference/tag-provider#value) is updated
+   * based on the input element's value.
+   * @default true
+   */
+  setValueOnChange?: BooleanOrCallback<ChangeEvent<HTMLElement>>;
+  /**
+   * Determines whether the last tag value should be removed from the store when
+   * the `Backspace` key is pressed and the cursor is at the start of the input
+   * value.
+   * @default true
+   */
+  removeOnBackspace?: BooleanOrCallback<KeyboardEvent<HTMLElement>>;
+  /**
+   * @default true
+   */
+  tabbable?: CompositeItemOptions<T>["tabbable"];
+}
+
+export type TagInputProps<T extends ElementType = TagName> = Props<
+  T,
+  TagInputOptions<T>
+>;

package/src/tag/tag-list-label.tsx

@@ -0,0 +1,102 @@
+import { useStoreState } from "@ariakit/react-store";
+import {
+  useId,
+  useMergeRefs,
+  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 { CompositeOptions } from "../composite/composite.tsx";
+import { useTagContext } from "./tag-context.tsx";
+import type { TagStore } from "./tag-store.ts";
+
+const TagName = "label" satisfies ElementType;
+type TagName = typeof TagName;
+
+/**
+ * Returns props to create a `TagListLabel` component.
+ * @see https://ariakit.com/components/tag
+ * @example
+ * ```jsx
+ * const props = useTagListLabel();
+ * <Role.label {...props} />
+ * ```
+ */
+export const useTagListLabel = createHook<TagName, TagListLabelOptions>(
+  function useTagListLabel({ store, ...props }) {
+    const context = useTagContext();
+    store = store || context;
+
+    invariant(
+      store,
+      process.env.NODE_ENV !== "production" &&
+        "TagListLabel must receive a `store` prop or be wrapped in a TagProvider component.",
+    );
+
+    const id = useId(props.id);
+    const htmlFor = useStoreState(store, (state) => state.inputElement?.id);
+
+    props = {
+      htmlFor,
+      ...props,
+      id,
+      ref: useMergeRefs(store.setLabelElement, props.ref),
+    };
+
+    return props;
+  },
+);
+
+/**
+ * Renders a label element for the
+ * [`TagInput`](https://ariakit.com/reference/tag-input) and also acts as the
+ * accessible name for the listbox element rendered by
+ * [`TagList`](https://ariakit.com/reference/tag-list).
+ * @see https://ariakit.com/components/tag
+ * @example
+ * ```jsx {2}
+ * <TagProvider>
+ *   <TagListLabel>Invitees</TagListLabel>
+ *   <TagList>
+ *     <TagValues>
+ *       {(values) =>
+ *         values.map((value) => (
+ *           <Tag key={value} value={value}>
+ *             {value}
+ *             <TagRemove />
+ *           </Tag>
+ *         ))
+ *       }
+ *     </TagValues>
+ *     <TagInput />
+ *   </TagList>
+ * </TagProvider>
+ * ```
+ */
+export const TagListLabel = forwardRef(function TagListLabel(
+  props: TagListLabelProps,
+) {
+  const htmlProps = useTagListLabel(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface TagListLabelOptions<
+  T extends ElementType = TagName,
+> extends CompositeOptions<T> {
+  /**
+   * Object returned by the
+   * [`useTagStore`](https://ariakit.com/reference/use-tag-store) hook. If not
+   * provided, the closest
+   * [`TagProvider`](https://ariakit.com/reference/tag-provider) component's
+   * context will be used.
+   */
+  store?: TagStore;
+}
+
+export type TagListLabelProps<T extends ElementType = TagName> = Props<
+  T,
+  TagListLabelOptions<T>
+>;

package/src/tag/tag-list.tsx

@@ -0,0 +1,210 @@
+import { useStoreState } from "@ariakit/react-store";
+import {
+  useEvent,
+  useWrapElement,
+  createElement,
+  createHook,
+  forwardRef,
+} from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import {
+  queueBeforeEvent,
+  getClosestFocusable,
+  invariant,
+  isApple,
+  UndoManager,
+} from "@ariakit/utils";
+import type { ElementType, KeyboardEvent, MouseEvent } from "react";
+import type { CompositeOptions } from "../composite/composite.tsx";
+import { useComposite } from "../composite/composite.tsx";
+import {
+  TagScopedContextProvider,
+  useTagProviderContext,
+} from "./tag-context.tsx";
+import type { TagStore } from "./tag-store.ts";
+import { useTouchDevice } from "./utils.ts";
+
+const TagName = "div" satisfies ElementType;
+type TagName = typeof TagName;
+type HTMLType = HTMLElementTagNameMap[TagName];
+
+/**
+ * Returns props to create a `TagList` component.
+ * @see https://ariakit.com/components/tag
+ * @example
+ * ```jsx
+ * const props = useTagList();
+ * <Role.div {...props} />
+ * ```
+ */
+export const useTagList = createHook<TagName, TagListOptions>(
+  function useTagList({ store, ...props }) {
+    const context = useTagProviderContext();
+    store = store || context;
+
+    invariant(
+      store,
+      process.env.NODE_ENV !== "production" &&
+        "TagList must receive a `store` prop or be wrapped in a TagProvider component.",
+    );
+
+    const onMouseDownProp = props.onMouseDown;
+
+    // Focus on the input element when clicking on the tag list.
+    const onMouseDown = useEvent((event: MouseEvent<HTMLType>) => {
+      onMouseDownProp?.(event);
+      if (event.defaultPrevented) return;
+      const target = event.target as HTMLElement;
+      const currentTarget = event.currentTarget;
+      const focusableTarget = getClosestFocusable(target);
+      const isSelfFocusable = focusableTarget === currentTarget;
+      // If the user clicked on an element that's already focusable, don't focus
+      // the input element.
+      if (!isSelfFocusable && currentTarget.contains(focusableTarget)) return;
+      const { inputElement } = store.getState();
+      // We can't immediately focus on mousedown, otherwise the input element
+      // will lose focus to the body as an effect of the mousedown event.
+      queueBeforeEvent(event.currentTarget, "mouseup", () => {
+        inputElement?.focus();
+      });
+    });
+
+    const onKeyDownProp = props.onKeyDown;
+
+    const onKeyDown = useEvent((event: KeyboardEvent<HTMLType>) => {
+      onKeyDownProp?.(event);
+      if (event.defaultPrevented) return;
+      const pc = !isApple();
+      const z = event.key === "z" || event.key === "Z";
+      const mod = pc ? event.ctrlKey : event.metaKey;
+      const shiftZ = (event.shiftKey && z) || (pc && event.key === "y");
+      if (mod && shiftZ) {
+        event.preventDefault();
+        void UndoManager.redo();
+      } else if (mod && z) {
+        event.preventDefault();
+        void UndoManager.undo();
+      }
+    });
+
+    props = useWrapElement(
+      props,
+      (element) => (
+        <TagScopedContextProvider value={store}>
+          {element}
+        </TagScopedContextProvider>
+      ),
+      [store],
+    );
+
+    props = {
+      ...props,
+      onMouseDown,
+      onKeyDown,
+    };
+
+    props = useComposite({ store, ...props });
+
+    const orientation = useStoreState(store, (state) =>
+      state.orientation === "both" ? undefined : state.orientation,
+    );
+    const items = useStoreState(store, (state) => state.renderedItems);
+    const itemIds = items.filter((item) => !!item.value).map((item) => item.id);
+    const labelId = useStoreState(store, (state) => state.labelElement?.id);
+
+    // Remove aria attributes from tha TagList element and add them to a
+    // separate div that will serve as the accessible listbox element.
+    const listboxProps: typeof props = {};
+    for (const key in props) {
+      if (key === "role" || key.startsWith("aria-")) {
+        const prop = key as keyof typeof props;
+        listboxProps[prop] = props[prop];
+        delete props[prop];
+      }
+    }
+
+    const touchDevice = useTouchDevice();
+
+    // We can't render TagList as a listbox because it may include an input
+    // (textbox) for styling purposes (it must be a sibling of the tags). The
+    // listbox role accepts only options as children, so we render a separate
+    // listbox element using aria-owns to reference the options.
+    const children = (
+      <>
+        <div
+          role={touchDevice ? "list" : "listbox"}
+          aria-live="polite"
+          aria-relevant="all"
+          aria-atomic
+          aria-labelledby={
+            listboxProps["aria-label"] != null ? undefined : labelId
+          }
+          aria-orientation={orientation}
+          aria-owns={itemIds.join(" ")}
+          {...listboxProps}
+          style={{ position: "fixed" }}
+        />
+        {props.children}
+      </>
+    );
+
+    props = {
+      ...props,
+      children,
+    };
+
+    return props;
+  },
+);
+
+/**
+ * Renders a wrapper for [`Tag`](https://ariakit.com/reference/tag) and
+ * [`TagInput`](https://ariakit.com/reference/tag-input) components. This
+ * component is typically styled as an input field.
+ *
+ * The [`TagListLabel`](https://ariakit.com/reference/tag-list-label) component
+ * can be used to provide an accessible name for the listbox element that owns
+ * the tags.
+ * @see https://ariakit.com/components/tag
+ * @example
+ * ```jsx {3-15}
+ * <TagProvider>
+ *   <TagListLabel>Invitees</TagListLabel>
+ *   <TagList>
+ *     <TagValues>
+ *       {(values) =>
+ *         values.map((value) => (
+ *           <Tag key={value} value={value}>
+ *             {value}
+ *             <TagRemove />
+ *           </Tag>
+ *         ))
+ *       }
+ *     </TagValues>
+ *     <TagInput />
+ *   </TagList>
+ * </TagProvider>
+ * ```
+ */
+export const TagList = forwardRef(function TagList(props: TagListProps) {
+  const htmlProps = useTagList(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface TagListOptions<
+  T extends ElementType = TagName,
+> extends CompositeOptions<T> {
+  /**
+   * Object returned by the
+   * [`useTagStore`](https://ariakit.com/reference/use-tag-store) hook. If not
+   * provided, the closest
+   * [`TagProvider`](https://ariakit.com/reference/tag-provider) component's
+   * context will be used.
+   */
+  store?: TagStore;
+}
+
+export type TagListProps<T extends ElementType = TagName> = Props<
+  T,
+  TagListOptions<T>
+>;