@ariakit/react-components 0.1.0

package/src/composite/composite-store.ts

@@ -0,0 +1,101 @@
+import * as Core from "@ariakit/components/composite/composite-store";
+import { useStore, useStoreProps } from "@ariakit/react-store";
+import type { Store } from "@ariakit/react-store";
+import { useId } from "@ariakit/react-utils";
+import type { PickRequired } from "@ariakit/utils";
+import type {
+  CollectionStoreFunctions,
+  CollectionStoreOptions,
+  CollectionStoreState,
+} from "../collection/collection-store.ts";
+import { useCollectionStoreProps } from "../collection/collection-store.ts";
+
+export function useCompositeStoreOptions<T extends Core.CompositeStoreOptions>(
+  props: T,
+) {
+  const id = useId(props.id);
+  return { id, ...props };
+}
+
+export function useCompositeStoreProps<T extends Core.CompositeStore>(
+  store: T,
+  update: () => void,
+  props: CompositeStoreProps,
+) {
+  store = useCollectionStoreProps(store, update, props);
+  useStoreProps(store, props, "activeId", "setActiveId");
+  useStoreProps(store, props, "includesBaseElement");
+  useStoreProps(store, props, "virtualFocus");
+  useStoreProps(store, props, "orientation");
+  useStoreProps(store, props, "rtl");
+  useStoreProps(store, props, "focusLoop");
+  useStoreProps(store, props, "focusWrap");
+  useStoreProps(store, props, "focusShift");
+  return store;
+}
+
+/**
+ * Creates a composite store to control the state of
+ * [Composite](https://ariakit.com/components/composite) components.
+ * @see https://ariakit.com/components/composite
+ * @example
+ * ```jsx
+ * const composite = useCompositeStore();
+ *
+ * <Composite store={composite}>
+ *   <CompositeItem>Item</CompositeItem>
+ *   <CompositeItem>Item</CompositeItem>
+ *   <CompositeItem>Item</CompositeItem>
+ * </Composite>
+ * ```
+ */
+
+export function useCompositeStore<
+  T extends CompositeStoreItem = CompositeStoreItem,
+>(
+  props: PickRequired<CompositeStoreProps<T>, "items" | "defaultItems">,
+): CompositeStore<T>;
+
+export function useCompositeStore(props?: CompositeStoreProps): CompositeStore;
+
+export function useCompositeStore(
+  props: CompositeStoreProps = {},
+): CompositeStore {
+  props = useCompositeStoreOptions(props);
+  const [store, update] = useStore(Core.createCompositeStore, props);
+  return useCompositeStoreProps(store, update, props);
+}
+
+export interface CompositeStoreItem extends Core.CompositeStoreItem {}
+
+export interface CompositeStoreState<
+  T extends CompositeStoreItem = CompositeStoreItem,
+>
+  extends Core.CompositeStoreState<T>, CollectionStoreState<T> {}
+
+export interface CompositeStoreFunctions<
+  T extends CompositeStoreItem = CompositeStoreItem,
+>
+  extends Core.CompositeStoreFunctions<T>, CollectionStoreFunctions<T> {}
+
+export interface CompositeStoreOptions<
+  T extends CompositeStoreItem = CompositeStoreItem,
+>
+  extends Core.CompositeStoreOptions<T>, CollectionStoreOptions<T> {
+  /**
+   * A callback that gets called when the
+   * [`activeId`](https://ariakit.com/reference/composite-provider#activeid)
+   * state changes.
+   */
+  setActiveId?: (activeId: CompositeStoreState<T>["activeId"]) => void;
+}
+
+export interface CompositeStoreProps<
+  T extends CompositeStoreItem = CompositeStoreItem,
+>
+  extends CompositeStoreOptions<T>, Core.CompositeStoreProps<T> {}
+
+export interface CompositeStore<
+  T extends CompositeStoreItem = CompositeStoreItem,
+>
+  extends CompositeStoreFunctions<T>, Store<Core.CompositeStore<T>> {}

package/src/composite/composite-typeahead.tsx

@@ -0,0 +1,246 @@
+import {
+  useEvent,
+  createElement,
+  createHook,
+  forwardRef,
+} from "@ariakit/react-utils";
+import type { Options, Props } from "@ariakit/react-utils";
+import {
+  getDocument,
+  isTextField,
+  sortBasedOnDOMPosition,
+  isSelfTarget,
+  invariant,
+  normalizeString,
+  removeUndefinedValues,
+} from "@ariakit/utils";
+import type { ElementType, KeyboardEvent } from "react";
+import { useRef } from "react";
+import { useCompositeContext } from "./composite-context.tsx";
+import type { CompositeStore, CompositeStoreItem } from "./composite-store.ts";
+import { flipItems } from "./utils.ts";
+
+const TagName = "div" satisfies ElementType;
+type TagName = typeof TagName;
+type HTMLType = HTMLElementTagNameMap[TagName];
+
+let chars = "";
+
+function clearChars() {
+  chars = "";
+}
+
+function isValidTypeaheadEvent(event: KeyboardEvent) {
+  const target = event.target as HTMLElement | null;
+  if (target && isTextField(target)) return false;
+  // If the spacebar is pressed, we'll only consider it a valid typeahead event
+  // if there were already other characters typed.
+  if (event.key === " " && chars.length) return true;
+  return (
+    event.key.length === 1 &&
+    !event.ctrlKey &&
+    !event.altKey &&
+    !event.metaKey &&
+    /^[\p{Letter}\p{Number}]$/u.test(event.key)
+  );
+}
+
+function isSelfTargetOrItem(event: KeyboardEvent, items: CompositeStoreItem[]) {
+  if (isSelfTarget(event)) return true;
+  const target = event.target as HTMLElement | null;
+  if (!target) return false;
+  const isItem = items.some((item) => item.element === target);
+  return isItem;
+}
+
+function getEnabledItems(items: CompositeStoreItem[]) {
+  return items.filter((item) => !item.disabled);
+}
+
+function itemTextStartsWith(item: CompositeStoreItem, text: string) {
+  const itemText =
+    item.element?.textContent ||
+    item.children ||
+    // The composite item object itself doesn't include a value property, but
+    // other components like Select do. Since CompositeTypeahead is a generic
+    // component that can be used with those as well, we also consider the value
+    // property as a fallback for the typeahead text content.
+    ("value" in item && (item.value as string | undefined));
+  if (!itemText) return false;
+  return normalizeString(itemText)
+    .trim()
+    .toLowerCase()
+    .startsWith(text.toLowerCase());
+}
+
+function getSameInitialItems(
+  items: CompositeStoreItem[],
+  char: string,
+  activeId?: string | null,
+) {
+  if (!activeId) return items;
+  const activeItem = items.find((item) => item.id === activeId);
+  if (!activeItem) return items;
+  if (!itemTextStartsWith(activeItem, char)) return items;
+  // Typing "oo" will match "oof" instead of moving to the next item.
+  if (chars !== char && itemTextStartsWith(activeItem, chars)) return items;
+  // If we're looping through the items, we'll want to reset the chars so "oo"
+  // becomes just "o".
+  chars = char;
+  // flipItems will put the previous items at the end of the list so we can loop
+  // through them.
+  return flipItems(
+    items.filter((item) => itemTextStartsWith(item, chars)),
+    activeId,
+  ).filter((item) => item.id !== activeId);
+}
+
+/**
+ * Returns props to create a `CompositeTypeahead` component.
+ * @see https://ariakit.com/components/composite
+ * @example
+ * ```jsx
+ * const store = useCompositeStore();
+ * const props = useCompositeTypeahead({ store });
+ * <Composite store={store} {...props}>
+ *   <CompositeItem>Item 1</CompositeItem>
+ *   <CompositeItem>Item 2</CompositeItem>
+ * </Composite>
+ * ```
+ */
+export const useCompositeTypeahead = createHook<
+  TagName,
+  CompositeTypeaheadOptions
+>(function useCompositeTypeahead({ store, typeahead = true, ...props }) {
+  const context = useCompositeContext();
+  store = store || context;
+
+  invariant(
+    store,
+    process.env.NODE_ENV !== "production" &&
+      "CompositeTypeahead must be a Composite component",
+  );
+
+  const onKeyDownCaptureProp = props.onKeyDownCapture;
+  const cleanupTimeoutRef = useRef(0);
+
+  // We have to listen to the event in the capture phase because the event
+  // might be handled by a child component. For example, the space key may
+  // trigger a click event on a child component. We need to prevent this
+  // behavior if the character is a valid typeahead key.
+  const onKeyDownCapture = useEvent((event: KeyboardEvent<HTMLType>) => {
+    onKeyDownCaptureProp?.(event);
+    if (event.defaultPrevented) return;
+    if (!typeahead) return;
+    if (!store) return;
+    if (!isValidTypeaheadEvent(event)) {
+      return clearChars();
+    }
+    const { renderedItems, items, activeId, id } = store.getState();
+    // We typically want to use the rendered items, as they're already sorted.
+    // However, the composite list might be unmounted or virtualized, in which
+    // case we'll use the original items.
+    let enabledItems = getEnabledItems(
+      items.length > renderedItems.length ? items : renderedItems,
+    );
+    // When the composite widget contains items with the `offscreenMode`
+    // prop, we need to consider them as well.
+    const document = getDocument(event.currentTarget);
+    const selector = `[data-offscreen-id="${id}"]`;
+    const offscreenItems = document.querySelectorAll<HTMLElement>(selector);
+    // Push the offscreen items to the enabled items list.
+    for (const element of offscreenItems) {
+      const disabled =
+        element.ariaDisabled === "true" ||
+        ("disabled" in element && !!element.disabled);
+      enabledItems.push({ id: element.id, element, disabled });
+    }
+    // If there are offscreen items, we need to sort the enabled items based on
+    // their DOM position so offscreen elements above the viewport are correctly
+    // considered.
+    if (offscreenItems.length) {
+      enabledItems = sortBasedOnDOMPosition(enabledItems, (i) => i.element);
+    }
+    if (!isSelfTargetOrItem(event, enabledItems)) return clearChars();
+    event.preventDefault();
+    // We need to clear the previous cleanup timeout so we can append the
+    // pressed char to the existing one.
+    window.clearTimeout(cleanupTimeoutRef.current);
+    // Schedule a new cleanup timeout. After a short delay we'll reset the
+    // characters so the next one counts as a new start character.
+    cleanupTimeoutRef.current = window.setTimeout(() => {
+      chars = "";
+    }, 500);
+    // Always consider the lowercase version of the key.
+    const char = event.key.toLowerCase();
+    chars += char;
+    enabledItems = getSameInitialItems(enabledItems, char, activeId);
+    const item = enabledItems.find((item) => itemTextStartsWith(item, chars));
+    if (item) {
+      store.move(item.id);
+    } else {
+      // Immediately clear the characters so the next keypress starts a new
+      // search.
+      clearChars();
+    }
+  });
+
+  props = {
+    ...props,
+    onKeyDownCapture,
+  };
+
+  return removeUndefinedValues(props);
+});
+
+/**
+ * Renders a component that adds typeahead functionality to composite
+ * components.
+ *
+ * When the
+ * [`typeahead`](https://ariakit.com/reference/composite-typeahead#typeahead)
+ * prop is enabled, which it is by default, hitting printable character keys
+ * will move focus to the next composite item that begins with the input
+ * characters.
+ * @see https://ariakit.com/components/composite
+ * @example
+ * ```jsx
+ * <CompositeProvider>
+ *   <Composite render={<CompositeTypeahead />}>
+ *     <CompositeItem>Item 1</CompositeItem>
+ *     <CompositeItem>Item 2</CompositeItem>
+ *   </Composite>
+ * </CompositeProvider>
+ * ```
+ */
+export const CompositeTypeahead = forwardRef(function CompositeTypeahead(
+  props: CompositeTypeaheadProps,
+) {
+  const htmlProps = useCompositeTypeahead(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface CompositeTypeaheadOptions<
+  _T extends ElementType = TagName,
+> extends Options {
+  /**
+   * Object returned by the
+   * [`useCompositeStore`](https://ariakit.com/reference/use-composite-store)
+   * hook. If not provided, the closest
+   * [`Composite`](https://ariakit.com/reference/composite) or
+   * [`CompositeProvider`](https://ariakit.com/reference/composite-provider)
+   * components' context will be used.
+   */
+  store?: CompositeStore;
+  /**
+   * When enabled, pressing printable character keys will move focus to the next
+   * composite item that starts with the entered characters.
+   * @default true
+   */
+  typeahead?: boolean;
+}
+
+export type CompositeTypeaheadProps<T extends ElementType = TagName> = Props<
+  T,
+  CompositeTypeaheadOptions<T>
+>;