@ariakit/react-components 0.1.0

package/src/tab/tab-panel.tsx

@@ -0,0 +1,314 @@
+import { useStoreState } from "@ariakit/react-store";
+import {
+  useEvent,
+  useId,
+  useMergeRefs,
+  useSafeLayoutEffect,
+  useWrapElement,
+  createElement,
+  createHook,
+  forwardRef,
+} from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import { getAllTabbableIn, invariant } from "@ariakit/utils";
+import type { ElementType, KeyboardEvent, RefObject } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { CollectionItemOptions } from "../collection/collection-item.tsx";
+import { useCollectionItem } from "../collection/collection-item.tsx";
+import type { DisclosureContentOptions } from "../disclosure/disclosure-content.tsx";
+import { useDisclosureContent } from "../disclosure/disclosure-content.tsx";
+import { useDisclosureStore } from "../disclosure/disclosure-store.ts";
+import type { FocusableOptions } from "../focusable/focusable.tsx";
+import { useFocusable } from "../focusable/focusable.tsx";
+import {
+  TabScopedContextProvider,
+  useTabProviderContext,
+} from "./tab-context.tsx";
+import type { TabStore } from "./tab-store.ts";
+
+const TagName = "div" satisfies ElementType;
+type TagName = typeof TagName;
+type HTMLType = HTMLElementTagNameMap[TagName];
+
+/**
+ * Returns props to create a `TabPanel` component.
+ * @see https://ariakit.com/components/tab
+ * @example
+ * ```jsx
+ * const store = useTabStore();
+ * const props = useTabPanel({ store });
+ * <TabList store={store}>
+ *   <Tab>Tab 1</Tab>
+ * </TabList>
+ * <Role {...props}>Panel 1</Role>
+ * ```
+ */
+export const useTabPanel = createHook<TagName, TabPanelOptions>(
+  function useTabPanel({
+    store,
+    unmountOnHide,
+    tabId: tabIdProp,
+    getItem: getItemProp,
+    scrollRestoration,
+    scrollElement,
+    ...props
+  }) {
+    const context = useTabProviderContext();
+    store = store || context;
+
+    invariant(
+      store,
+      process.env.NODE_ENV !== "production" &&
+        "TabPanel must receive a `store` prop or be wrapped in a TabProvider component.",
+    );
+
+    const ref = useRef<HTMLType>(null);
+    const id = useId(props.id);
+
+    const tabId = useStoreState(
+      store.panels,
+      () => tabIdProp || store?.panels.item(id)?.tabId,
+    );
+    const open = useStoreState(
+      store,
+      (state) => !!tabId && state.selectedId === tabId,
+    );
+
+    const disclosure = useDisclosureStore({ open });
+    const mounted = useStoreState(disclosure, "mounted");
+
+    // Store the scroll position for each tabId. The component may receive
+    // different tab ids if it's a single tab panel with dynamic tab id and
+    // content.
+    const scrollPositionRef = useRef(
+      new Map<string, { x: number; y: number }>(),
+    );
+
+    const getScrollElement = useEvent(() => {
+      const panelElement = ref.current;
+      if (!panelElement) return null;
+      if (!scrollElement) return panelElement;
+      if (typeof scrollElement === "function") {
+        return scrollElement(panelElement);
+      }
+      if ("current" in scrollElement) {
+        return scrollElement.current;
+      }
+      return scrollElement;
+    });
+
+    // Adds scroll restoration behavior to the tab panel.
+    useEffect(() => {
+      if (!scrollRestoration) return;
+      if (!mounted) return;
+      const element = getScrollElement();
+      if (!element) return;
+      // If scrollRestoration is set to "reset", scroll to the top of the
+      // element and return early.
+      if (scrollRestoration === "reset") {
+        element.scroll(0, 0);
+        return;
+      }
+      if (!tabId) return;
+      const position = scrollPositionRef.current.get(tabId);
+      element.scroll(position?.x ?? 0, position?.y ?? 0);
+      // On scroll, save the scroll position for the current tab id.
+      const onScroll = () => {
+        scrollPositionRef.current.set(tabId, {
+          x: element.scrollLeft,
+          y: element.scrollTop,
+        });
+      };
+      element.addEventListener("scroll", onScroll);
+      return () => {
+        element.removeEventListener("scroll", onScroll);
+      };
+    }, [scrollRestoration, mounted, tabId, getScrollElement, store]);
+
+    const [hasTabbableChildren, setHasTabbableChildren] = useState(false);
+
+    // Re-check tabbable children each time the panel becomes visible so
+    // content rendered conditionally on tab selection is accounted for.
+    useSafeLayoutEffect(() => {
+      if (!mounted) return;
+      const element = ref.current;
+      if (!element) return;
+      setHasTabbableChildren(!!getAllTabbableIn(element).length);
+    }, [mounted]);
+
+    const getItem = useCallback<NonNullable<CollectionItemOptions["getItem"]>>(
+      (item) => {
+        const nextItem = { ...item, id: id || item.id, tabId: tabIdProp };
+        if (getItemProp) {
+          return getItemProp(nextItem);
+        }
+        return nextItem;
+      },
+      [id, tabIdProp, getItemProp],
+    );
+
+    const onKeyDownProp = props.onKeyDown;
+
+    const onKeyDown = useEvent((event: KeyboardEvent<HTMLType>) => {
+      onKeyDownProp?.(event);
+      if (event.defaultPrevented) return;
+      if (!store?.composite) return;
+      const keyMap = {
+        ArrowLeft: store.previous,
+        ArrowRight: store.next,
+        Home: store.first,
+        End: store.last,
+      };
+      const action = keyMap[event.key as keyof typeof keyMap];
+      if (!action) return;
+      const { selectedId } = store.getState();
+      const nextId = action({ activeId: selectedId });
+      if (!nextId) return;
+      event.preventDefault();
+      store.move(nextId);
+    });
+
+    props = useWrapElement(
+      props,
+      (element) => (
+        <TabScopedContextProvider value={store}>
+          {element}
+        </TabScopedContextProvider>
+      ),
+      [store],
+    );
+
+    props = {
+      role: "tabpanel",
+      "aria-labelledby":
+        props["aria-label"] != null ? undefined : tabId || undefined,
+      ...props,
+      id,
+      children: unmountOnHide && !mounted ? null : props.children,
+      ref: useMergeRefs(ref, props.ref),
+      onKeyDown,
+    };
+
+    props = useFocusable({
+      // If the tab panel is rendered as part of another composite widget such
+      // as combobox, it should not be focusable.
+      focusable: !store.composite && !hasTabbableChildren,
+      ...props,
+    });
+    props = useDisclosureContent({ store: disclosure, ...props });
+    props = useCollectionItem({ store: store.panels, ...props, getItem });
+
+    return props;
+  },
+);
+
+/**
+ * Renders a tab panel element that's controlled by a
+ * [`Tab`](https://ariakit.com/reference/tab) component.
+ *
+ * If the [`tabId`](https://ariakit.com/reference/tab-panel#tabid) prop isn't
+ * provided, the tab panel will automatically associate with a
+ * [`Tab`](https://ariakit.com/reference/tab) based on its position in the DOM.
+ * Alternatively, you can render a single tab panel with a dynamic
+ * [`tabId`](https://ariakit.com/reference/tab-panel#tabid) value pointing to
+ * the selected tab.
+ * @see https://ariakit.com/components/tab
+ * @example
+ * ```jsx {6,7}
+ * <TabProvider>
+ *   <TabList>
+ *     <Tab>Tab 1</Tab>
+ *     <Tab>Tab 2</Tab>
+ *   </TabList>
+ *   <TabPanel>Panel 1</TabPanel>
+ *   <TabPanel>Panel 2</TabPanel>
+ * </TabProvider>
+ * ```
+ */
+export const TabPanel = forwardRef(function TabPanel(props: TabPanelProps) {
+  const htmlProps = useTabPanel(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface TabPanelOptions<T extends ElementType = TagName>
+  extends
+    FocusableOptions<T>,
+    CollectionItemOptions<T>,
+    Omit<DisclosureContentOptions<T>, "store"> {
+  /**
+   * Object returned by the
+   * [`useTabStore`](https://ariakit.com/reference/use-tab-store) hook. If not
+   * provided, the closest
+   * [`TabProvider`](https://ariakit.com/reference/tab-provider) component's
+   * context will be used.
+   */
+  store?: TabStore;
+  /**
+   * The [`id`](https://ariakit.com/reference/tab#id) of the tab controlling
+   * this panel. This connection is used to assign the `aria-labelledby`
+   * attribute to the tab panel and to determine if the tab panel should be
+   * visible.
+   *
+   * This link is automatically established by matching the order of
+   * [`Tab`](https://ariakit.com/reference/tab) and
+   * [`TabPanel`](https://ariakit.com/reference/tab-panel) elements in the DOM.
+   * If you're rendering a single tab panel, this can be set to a dynamic value
+   * that refers to the selected tab.
+   *
+   * Live examples:
+   * - [Combobox with Tabs](https://ariakit.com/examples/combobox-tabs)
+   * - [Tab with React Router](https://ariakit.com/examples/tab-react-router)
+   * - [Animated TabPanel](https://ariakit.com/examples/tab-panel-animated)
+   * - [Select with Combobox and
+   *   Tabs](https://ariakit.com/examples/select-combobox-tab)
+   * - [Command Menu with
+   *   Tabs](https://ariakit.com/examples/dialog-combobox-tab-command-menu)
+   */
+  tabId?: string | null;
+  /**
+   * Manages the scrolling behavior of the tab panel when it is hidden and then
+   * shown again.
+   *
+   * This is especially useful when using a single tab panel for multiple tabs,
+   * where you dynamically change the
+   * [`tabId`](https://ariakit.com/reference/tab-panel#tabid) prop and the
+   * panel's children, which would otherwise retain the current scroll position
+   * when switching tabs.
+   *
+   * When set to `true`, the component will save the scroll position and restore
+   * it when the panel is shown again. When set to `"reset"`, the scroll
+   * position will reset to the top when the panel is displayed again.
+   *
+   * The default scroll element is the tab panel itself. To scroll a different
+   * element, use the
+   * [`scrollElement`](https://ariakit.com/reference/tab-panel#scrollelement)
+   * prop.
+   * @default false
+   */
+  scrollRestoration?: boolean | "reset";
+  /**
+   * When using the
+   * [`scrollRestoration`](https://ariakit.com/reference/tab-panel#scrollrestoration)
+   * prop, the tab panel element serves as the default scroll element. You can
+   * use this prop to designate a different element for scrolling.
+   *
+   * If a function is provided, it will be called with the tab panel element as
+   * an argument. The function should return the element to scroll.
+   * @example
+   * ```jsx
+   * <TabPanel
+   *   scrollRestoration
+   *   scrollElement={(panel) => panel.querySelector(".scrollable")}
+   * />
+   * ```
+   */
+  scrollElement?:
+    | HTMLElement
+    | RefObject<HTMLElement | null>
+    | ((panel: HTMLElement) => HTMLElement | null);
+}
+
+export type TabPanelProps<T extends ElementType = TagName> = Props<
+  T,
+  TabPanelOptions<T>
+>;

package/src/tab/tab-provider.tsx

@@ -0,0 +1,30 @@
+import type { ReactNode } from "react";
+import { TabContextProvider } from "./tab-context.tsx";
+import type { TabStoreProps } from "./tab-store.ts";
+import { useTabStore } from "./tab-store.ts";
+
+/**
+ * Provides a tab store to [Tab](https://ariakit.com/components/tab) components.
+ * @see https://ariakit.com/components/tab
+ * @example
+ * ```jsx
+ * <TabProvider>
+ *   <TabList>
+ *     <Tab>For You</Tab>
+ *     <Tab>Following</Tab>
+ *   </TabList>
+ *   <TabPanel>For You</TabPanel>
+ *   <TabPanel>Following</TabPanel>
+ * </TabProvider>
+ * ```
+ */
+export function TabProvider(props: TabProviderProps = {}) {
+  const store = useTabStore(props);
+  return (
+    <TabContextProvider value={store}>{props.children}</TabContextProvider>
+  );
+}
+
+export interface TabProviderProps extends TabStoreProps {
+  children?: ReactNode;
+}

package/src/tab/tab-store.ts

@@ -0,0 +1,124 @@
+import * as Core from "@ariakit/components/tab/tab-store";
+import { useStore, useStoreProps } from "@ariakit/react-store";
+import type { Store } from "@ariakit/react-store";
+import { useUpdateEffect } from "@ariakit/react-utils";
+import { useMemo } from "react";
+import { useComboboxContext } from "../combobox/combobox-context.tsx";
+import type { ComboboxStore } from "../combobox/combobox-store.ts";
+import type {
+  CompositeStore,
+  CompositeStoreFunctions,
+  CompositeStoreOptions,
+  CompositeStoreState,
+} from "../composite/composite-store.ts";
+import { useCompositeStoreProps } from "../composite/composite-store.ts";
+import { useSelectContext } from "../select/select-context.tsx";
+
+export function useTabStoreProps<T extends Core.TabStore>(
+  store: T,
+  update: () => void,
+  props: TabStoreProps,
+) {
+  useUpdateEffect(update, [props.composite, props.combobox]);
+
+  store = useCompositeStoreProps(store, update, props);
+  useStoreProps(store, props, "selectedId", "setSelectedId");
+  useStoreProps(store, props, "selectOnMove");
+
+  const [panels, updatePanels] = useStore(() => store.panels, {});
+  useUpdateEffect(updatePanels, [store, updatePanels]);
+
+  return Object.assign(
+    useMemo(() => ({ ...store, panels }), [store, panels]),
+    { composite: props.composite, combobox: props.combobox },
+  );
+}
+
+/**
+ * Creates a tab store to control the state of
+ * [Tab](https://ariakit.com/components/tab) components.
+ * @see https://ariakit.com/components/tab
+ * @example
+ * ```jsx
+ * const tab = useTabStore();
+ *
+ * <TabList store={tab}>
+ *   <Tab>Tab 1</Tab>
+ *   <Tab>Tab 2</Tab>
+ * </TabList>
+ * <TabPanel store={tab}>Panel 1</TabPanel>
+ * <TabPanel store={tab}>Panel 2</TabPanel>
+ * ```
+ */
+export function useTabStore(props: TabStoreProps = {}): TabStore {
+  const combobox = useComboboxContext();
+  const composite = useSelectContext() || combobox;
+  props = {
+    ...props,
+    composite: props.composite !== undefined ? props.composite : composite,
+    combobox: props.combobox !== undefined ? props.combobox : combobox,
+  };
+  const [store, update] = useStore(Core.createTabStore, props);
+  return useTabStoreProps(store, update, props);
+}
+
+export interface TabStoreItem extends Core.TabStoreItem {}
+
+export interface TabStoreState
+  extends Core.TabStoreState, CompositeStoreState<TabStoreItem> {}
+
+export interface TabStoreFunctions
+  extends
+    Pick<TabStoreOptions, "composite" | "combobox">,
+    Omit<Core.TabStoreFunctions, "panels" | "composite" | "combobox">,
+    CompositeStoreFunctions<TabStoreItem> {
+  panels: Store<Core.TabStoreFunctions["panels"]>;
+}
+
+export interface TabStoreOptions
+  extends
+    Omit<Core.TabStoreOptions, "composite" | "combobox">,
+    CompositeStoreOptions<TabStoreItem> {
+  /**
+   * Function that will be called when the
+   * [`selectedId`](https://ariakit.com/reference/tab-provider#selectedid) state
+   * changes.
+   *
+   * Live examples:
+   * - [Combobox with Tabs](https://ariakit.com/examples/combobox-tabs)
+   * - [Select with Combobox and
+   *   Tabs](https://ariakit.com/examples/select-combobox-tab)
+   * - [Command Menu with
+   *   Tabs](https://ariakit.com/examples/dialog-combobox-tab-command-menu)
+   */
+  setSelectedId?: (selectedId: TabStoreState["selectedId"]) => void;
+  /**
+   * A reference to another [composite
+   * store](https://ariakit.com/reference/use-composite-store). This is
+   * automatically set when rendering tabs as part of another composite widget,
+   * such as [Combobox](https://ariakit.com/components/combobox) or
+   * [Select](https://ariakit.com/components/select).
+   *
+   * Live examples:
+   * - [Combobox with Tabs](https://ariakit.com/examples/combobox-tabs)
+   */
+  composite?: CompositeStore | null;
+  /**
+   * A reference to a [combobox
+   * store](https://ariakit.com/reference/use-combobox-store). This is
+   * automatically set when rendering tabs inside a
+   * [Combobox](https://ariakit.com/components/combobox).
+   *
+   * Live examples:
+   * - [Combobox with Tabs](https://ariakit.com/examples/combobox-tabs)
+   */
+  combobox?: ComboboxStore | null;
+}
+
+export interface TabStoreProps
+  extends TabStoreOptions, Omit<Core.TabStoreProps, "composite" | "combobox"> {}
+
+export interface TabStore
+  extends
+    TabStoreFunctions,
+    Omit<Store<Core.TabStore>, "panels" | "composite" | "combobox"> {}

package/src/tab/tab.tsx

@@ -0,0 +1,208 @@
+import { useStoreState } from "@ariakit/react-store";
+import {
+  useEvent,
+  useId,
+  createElement,
+  createHook,
+  forwardRef,
+  memo,
+} from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import { disabledFromProps, invariant } from "@ariakit/utils";
+import type { ElementType, MouseEvent } from "react";
+import { useCallback } from "react";
+import type { CompositeItemOptions } from "../composite/composite-item.tsx";
+import {
+  CompositeItem,
+  useCompositeItem,
+} from "../composite/composite-item.tsx";
+import { useTabScopedContext } from "./tab-context.tsx";
+import type { TabStore } from "./tab-store.ts";
+
+const TagName = "button" satisfies ElementType;
+type TagName = typeof TagName;
+type HTMLType = HTMLElementTagNameMap[TagName];
+
+/**
+ * Returns props to create a `Tab` component.
+ * @see https://ariakit.com/components/tab
+ * @example
+ * ```jsx
+ * const store = useTabStore();
+ * const props = useTab({ store });
+ * <TabList store={store}>
+ *   <Role {...props}>Tab 1</Role>
+ * </TabList>
+ * <TabPanel store={store}>Panel 1</TabPanel>
+ * ```
+ */
+export const useTab = createHook<TagName, TabOptions>(function useTab({
+  store,
+  getItem: getItemProp,
+  ...props
+}) {
+  const context = useTabScopedContext();
+  store = store || context;
+
+  invariant(
+    store,
+    process.env.NODE_ENV !== "production" &&
+      "Tab must be wrapped in a TabList component.",
+  );
+
+  // Keep a reference to the default id so we can wait before all tabs have
+  // been assigned an id before registering them in the store. See
+  // https://github.com/ariakit/ariakit/issues/1721
+  const defaultId = useId();
+  const id = props.id || defaultId;
+  const dimmed = disabledFromProps(props);
+
+  const getItem = useCallback<NonNullable<CompositeItemOptions["getItem"]>>(
+    (item) => {
+      const nextItem = { ...item, dimmed };
+      if (getItemProp) {
+        return getItemProp(nextItem);
+      }
+      return nextItem;
+    },
+    [dimmed, getItemProp],
+  );
+
+  const onClickProp = props.onClick;
+
+  const onClick = useEvent((event: MouseEvent<HTMLType>) => {
+    onClickProp?.(event);
+    if (event.defaultPrevented) return;
+    store?.setSelectedId(id);
+  });
+
+  const panelId = useStoreState(
+    store.panels,
+    (state) => state.items.find((item) => item.tabId === id)?.id,
+  );
+  const shouldRegisterItem = defaultId ? props.shouldRegisterItem : false;
+
+  const isActive = useStoreState(
+    store,
+    (state) => !!id && state.activeId === id,
+  );
+  const selected = useStoreState(
+    store,
+    (state) => !!id && state.selectedId === id,
+  );
+  const hasActiveItem = useStoreState(
+    store,
+    (state) => !!store.item(state.activeId),
+  );
+  const canRegisterComposedItem = isActive || (selected && !hasActiveItem);
+  const accessibleWhenDisabled =
+    selected || (props.accessibleWhenDisabled ?? true);
+
+  // If the tab is rendered within another composite widget with virtual focus,
+  // such as combobox, it shouldn't be tabbable even if the tab store uses
+  // roving tabindex. Otherwise, the focus will be trapped within the composite
+  // widget.
+  const isWithinVirtualFocusComposite = useStoreState(
+    store.combobox || store.composite,
+    "virtualFocus",
+  );
+
+  if (isWithinVirtualFocusComposite) {
+    props = {
+      ...props,
+      tabIndex: -1,
+    };
+  }
+
+  props = {
+    role: "tab",
+    "aria-selected": selected,
+    "aria-controls": panelId || undefined,
+    ...props,
+    id,
+    onClick,
+  };
+
+  // If the tab is rendered as part of another composite widget such as
+  // combobox, we need to render it as a composite item. This ensures it's
+  // recognized in the composite store and lets us manage arrow key navigation
+  // to move focus to other composite items that might be rendered in a tab
+  // panel. We only register the selected tab to maintain a vertical list
+  // orientation.
+  if (store.composite) {
+    const defaultProps = {
+      id,
+      accessibleWhenDisabled,
+      store: store.composite,
+      shouldRegisterItem: canRegisterComposedItem && shouldRegisterItem,
+      rowId: props.rowId,
+      render: props.render,
+    } satisfies CompositeItemOptions;
+    props = {
+      ...props,
+      render: (
+        <CompositeItem
+          {...defaultProps}
+          render={
+            store.combobox && store.composite !== store.combobox ? (
+              <CompositeItem {...defaultProps} store={store.combobox} />
+            ) : (
+              defaultProps.render
+            )
+          }
+        />
+      ),
+    };
+  }
+
+  props = useCompositeItem({
+    store,
+    ...props,
+    accessibleWhenDisabled,
+    getItem,
+    shouldRegisterItem,
+  });
+
+  return props;
+});
+
+/**
+ * Renders a tab element inside a
+ * [`TabList`](https://ariakit.com/reference/tab-list) wrapper.
+ * @see https://ariakit.com/components/tab
+ * @example
+ * ```jsx {3,4}
+ * <TabProvider>
+ *   <TabList>
+ *     <Tab>Tab 1</Tab>
+ *     <Tab>Tab 2</Tab>
+ *   </TabList>
+ *   <TabPanel>Panel 1</TabPanel>
+ *   <TabPanel>Panel 2</TabPanel>
+ * </TabProvider>
+ * ```
+ */
+export const Tab = memo(
+  forwardRef(function Tab(props: TabProps) {
+    const htmlProps = useTab(props);
+    return createElement(TagName, htmlProps);
+  }),
+);
+
+export interface TabOptions<
+  T extends ElementType = TagName,
+> extends CompositeItemOptions<T> {
+  /**
+   * Object returned by the
+   * [`useTabStore`](https://ariakit.com/reference/use-tab-store) hook. If not
+   * provided, the closest [`TabList`](https://ariakit.com/reference/tab-list)
+   * component's context will be used.
+   */
+  store?: TabStore;
+  /**
+   * @default true
+   */
+  accessibleWhenDisabled?: CompositeItemOptions["accessibleWhenDisabled"];
+}
+
+export type TabProps<T extends ElementType = TagName> = Props<T, TabOptions<T>>;