@ariakit/components 0.1.0

package/src/select/select-store.ts

@@ -0,0 +1,323 @@
+import {
+  batch,
+  createStore,
+  mergeStore,
+  omit,
+  setup,
+  sync,
+  throwOnConflictingProps,
+} from "@ariakit/store";
+import type { Store, StoreOptions, StoreProps } from "@ariakit/store";
+import { toArray, defaultValue } from "@ariakit/utils";
+import type { PickRequired, SetState } from "@ariakit/utils";
+import type { ComboboxStore } from "../combobox/combobox-store.ts";
+import type {
+  CompositeStoreFunctions,
+  CompositeStoreItem,
+  CompositeStoreOptions,
+  CompositeStoreState,
+} from "../composite/composite-store.ts";
+import { createCompositeStore } from "../composite/composite-store.ts";
+import type {
+  PopoverStoreFunctions,
+  PopoverStoreOptions,
+  PopoverStoreState,
+} from "../popover/popover-store.ts";
+import { createPopoverStore } from "../popover/popover-store.ts";
+
+type MutableValue<T extends SelectStoreValue = SelectStoreValue> =
+  T extends string ? string : T;
+
+export function createSelectStore<
+  T extends SelectStoreValue = SelectStoreValue,
+>(
+  props: PickRequired<SelectStoreProps<T>, "value" | "defaultValue">,
+): SelectStore<T>;
+
+export function createSelectStore(props?: SelectStoreProps): SelectStore;
+
+export function createSelectStore({
+  combobox,
+  ...props
+}: SelectStoreProps = {}): SelectStore {
+  const store = mergeStore(
+    props.store,
+    omit(combobox, [
+      "value",
+      "items",
+      "renderedItems",
+      "baseElement",
+      "arrowElement",
+      "anchorElement",
+      "contentElement",
+      "popoverElement",
+      "disclosureElement",
+    ]),
+  );
+
+  throwOnConflictingProps(props, store);
+
+  const syncState = store.getState();
+
+  const composite = createCompositeStore({
+    ...props,
+    store,
+    virtualFocus: defaultValue(
+      props.virtualFocus,
+      syncState.virtualFocus,
+      true,
+    ),
+    includesBaseElement: defaultValue(
+      props.includesBaseElement,
+      syncState.includesBaseElement,
+      false,
+    ),
+    activeId: defaultValue(
+      props.activeId,
+      syncState.activeId,
+      props.defaultActiveId,
+      null,
+    ),
+    orientation: defaultValue(
+      props.orientation,
+      syncState.orientation,
+      "vertical" as const,
+    ),
+  });
+
+  const popover = createPopoverStore({
+    ...props,
+    store,
+    placement: defaultValue(
+      props.placement,
+      syncState.placement,
+      "bottom-start" as const,
+    ),
+  });
+
+  const initialValue = new String("") as "";
+
+  const initialState: SelectStoreState = {
+    ...composite.getState(),
+    ...popover.getState(),
+    value: defaultValue(
+      props.value,
+      syncState.value,
+      props.defaultValue,
+      initialValue,
+    ),
+    setValueOnMove: defaultValue(
+      props.setValueOnMove,
+      syncState.setValueOnMove,
+      false,
+    ),
+    labelElement: defaultValue(syncState.labelElement, null),
+    selectElement: defaultValue(syncState.selectElement, null),
+    listElement: defaultValue(syncState.listElement, null),
+  };
+
+  const select = createStore(initialState, composite, popover, store);
+
+  // Automatically sets the default value if it's not set.
+  setup(select, () =>
+    sync(select, ["value", "items"], (state) => {
+      if (state.value !== initialValue) return;
+      if (!state.items.length) return;
+      const item = state.items.find(
+        (item) => !item.disabled && item.value != null,
+      );
+      if (item?.value == null) return;
+      select.setState("value", item.value);
+    }),
+  );
+
+  // Resets the active id to its initial state when the popover is hidden. This
+  // guarantees that the active id won't be pointing to another item when the
+  // popover is shown again, which would cause the selected item to not be
+  // auto-focused. See test "clicking on different tab and clicking outside
+  // resets the selected tab".
+  setup(select, () =>
+    sync(select, ["mounted"], (state) => {
+      if (state.mounted) return;
+      select.setState("activeId", initialState.activeId);
+    }),
+  );
+
+  // Sets the active id when the value changes and the popover is hidden.
+  setup(select, () =>
+    sync(select, ["mounted", "items", "value"], (state) => {
+      // TODO: Revisit this. See test "open with keyboard, then try to open
+      // again". Probably deprecate together with using ComboboxProvider as a
+      // parent of SelectProvider.
+      if (combobox) return;
+      if (state.mounted) return;
+      const values = toArray(state.value);
+      const lastValue = values[values.length - 1];
+      if (lastValue == null) return;
+      const item = state.items.find(
+        (item) => !item.disabled && item.value === lastValue,
+      );
+      if (!item) return;
+      select.setState("activeId", item.id);
+    }),
+  );
+
+  // Sets the select value when the active item changes by moving (which usually
+  // happens when moving to an item using the keyboard).
+  setup(select, () =>
+    batch(select, ["setValueOnMove", "moves"], (state) => {
+      const { mounted, value, activeId } = select.getState();
+      if (!state.setValueOnMove && mounted) return;
+      if (Array.isArray(value)) return;
+      if (!state.moves) return;
+      if (!activeId) return;
+      const item = composite.item(activeId);
+      if (!item || item.disabled || item.value == null) return;
+      select.setState("value", item.value);
+    }),
+  );
+
+  return {
+    ...composite,
+    ...popover,
+    ...select,
+    combobox,
+    setValue: (value) => select.setState("value", value),
+    setLabelElement: (element) => select.setState("labelElement", element),
+    setSelectElement: (element) => select.setState("selectElement", element),
+    setListElement: (element) => select.setState("listElement", element),
+  };
+}
+
+export type SelectStoreValue = string | readonly string[];
+
+export interface SelectStoreItem extends CompositeStoreItem {
+  value?: string;
+}
+
+export interface SelectStoreState<T extends SelectStoreValue = SelectStoreValue>
+  extends CompositeStoreState<SelectStoreItem>, PopoverStoreState {
+  /** @default true */
+  virtualFocus: CompositeStoreState<SelectStoreItem>["virtualFocus"];
+  /** @default null */
+  activeId: CompositeStoreState<SelectStoreItem>["activeId"];
+  /** @default "vertical" */
+  orientation: CompositeStoreState<SelectStoreItem>["orientation"];
+  /** @default "bottom-start" */
+  placement: PopoverStoreState["placement"];
+  /**
+   * The select value.
+   *
+   * Live examples:
+   * - [Form with Select](https://ariakit.com/examples/form-select)
+   * - [Select Grid](https://ariakit.com/examples/select-grid)
+   * - [Select with custom
+   *   items](https://ariakit.com/examples/select-item-custom)
+   * - [Multi-Select](https://ariakit.com/examples/select-multiple)
+   * - [Toolbar with Select](https://ariakit.com/examples/toolbar-select)
+   * - [Select with Next.js App
+   *   Router](https://ariakit.com/examples/select-next-router)
+   */
+  value: MutableValue<T>;
+  /**
+   * Whether the select
+   * [`value`](https://ariakit.com/reference/select-provider#value) should be
+   * set when the active item changes by moving (which usually happens when
+   * moving to an item using the keyboard).
+   *
+   * Live examples:
+   * - [Select Grid](https://ariakit.com/examples/select-grid)
+   * - [Select with custom
+   *   items](https://ariakit.com/examples/select-item-custom)
+   * @default false
+   */
+  setValueOnMove: boolean;
+  /**
+   * The select label element.
+   */
+  labelElement: HTMLElement | null;
+  /**
+   * The select button element.
+   *
+   * Live examples:
+   * - [Form with Select](https://ariakit.com/examples/form-select)
+   */
+  selectElement: HTMLElement | null;
+  /**
+   * The select list element.
+   */
+  listElement: HTMLElement | null;
+}
+
+export interface SelectStoreFunctions<
+  T extends SelectStoreValue = SelectStoreValue,
+>
+  extends
+    Pick<SelectStoreOptions<T>, "combobox">,
+    CompositeStoreFunctions<SelectStoreItem>,
+    PopoverStoreFunctions {
+  /**
+   * Sets the [`value`](https://ariakit.com/reference/select-provider#value)
+   * state.
+   * @example
+   * store.setValue("Apple");
+   * store.setValue(["Apple", "Banana"]);
+   * store.setValue((value) => value === "Apple" ? "Banana" : "Apple"));
+   */
+  setValue: SetState<SelectStoreState<T>["value"]>;
+  /**
+   * Sets the `labelElement` state.
+   */
+  setLabelElement: SetState<SelectStoreState<T>["labelElement"]>;
+  /**
+   * Sets the `selectElement` state.
+   */
+  setSelectElement: SetState<SelectStoreState<T>["selectElement"]>;
+  /**
+   * Sets the `listElement` state.
+   */
+  setListElement: SetState<SelectStoreState<T>["listElement"]>;
+}
+
+export interface SelectStoreOptions<
+  T extends SelectStoreValue = SelectStoreValue,
+>
+  extends
+    StoreOptions<
+      SelectStoreState<T>,
+      | "virtualFocus"
+      | "activeId"
+      | "orientation"
+      | "placement"
+      | "value"
+      | "setValueOnMove"
+    >,
+    CompositeStoreOptions<SelectStoreItem>,
+    PopoverStoreOptions {
+  /**
+   * A reference to a combobox store. This is used when combining the combobox
+   * with a select (e.g., select with a search input). The stores will share the
+   * same state.
+   */
+  combobox?: ComboboxStore | null;
+  /**
+   * The default value. If not set, the first non-disabled item will be used.
+   *
+   * Live examples:
+   * - [Form with Select](https://ariakit.com/examples/form-select)
+   * - [Animated Select](https://ariakit.com/examples/select-animated)
+   * - [Select with Combobox](https://ariakit.com/examples/select-combobox)
+   * - [SelectGroup](https://ariakit.com/examples/select-group)
+   * - [Select with Next.js App
+   *   Router](https://ariakit.com/examples/select-next-router)
+   * - [Select with Combobox and
+   *   Tabs](https://ariakit.com/examples/select-combobox-tab)
+   */
+  defaultValue?: SelectStoreState<T>["value"];
+}
+
+export interface SelectStoreProps<T extends SelectStoreValue = SelectStoreValue>
+  extends SelectStoreOptions<T>, StoreProps<SelectStoreState<T>> {}
+
+export interface SelectStore<T extends SelectStoreValue = SelectStoreValue>
+  extends SelectStoreFunctions<T>, Store<SelectStoreState<T>> {}

package/src/tab/tab-store.ts

@@ -0,0 +1,330 @@
+import {
+  batch,
+  createStore,
+  mergeStore,
+  omit,
+  setup,
+  sync,
+} from "@ariakit/store";
+import type { Store, StoreOptions, StoreProps } from "@ariakit/store";
+import { chain, defaultValue } from "@ariakit/utils";
+import type { SetState } from "@ariakit/utils";
+import type {
+  CollectionStore,
+  CollectionStoreItem,
+} from "../collection/collection-store.ts";
+import { createCollectionStore } from "../collection/collection-store.ts";
+import type { ComboboxStore } from "../combobox/combobox-store.ts";
+import type {
+  CompositeStore,
+  CompositeStoreFunctions,
+  CompositeStoreItem,
+  CompositeStoreOptions,
+  CompositeStoreState,
+} from "../composite/composite-store.ts";
+import { createCompositeStore } from "../composite/composite-store.ts";
+import type { SelectStore } from "../select/select-store.ts";
+
+export function createTabStore({
+  composite: parentComposite,
+  combobox,
+  ...props
+}: TabStoreProps = {}): TabStore {
+  const independentKeys = [
+    "items",
+    "renderedItems",
+    "moves",
+    "orientation",
+    "virtualFocus",
+    "includesBaseElement",
+    "baseElement",
+    "focusLoop",
+    "focusShift",
+    "focusWrap",
+  ] as const;
+
+  const store = mergeStore(
+    props.store,
+    omit(parentComposite, independentKeys),
+    omit(combobox, independentKeys),
+  );
+  const syncState = store?.getState();
+
+  const composite = createCompositeStore({
+    ...props,
+    store,
+    // We need to explicitly set the default value of `includesBaseElement` to
+    // `false` since we don't want the composite store to default it to `true`
+    // when the activeId state is null, which could be the case when rendering
+    // combobox with tab.
+    includesBaseElement: defaultValue(
+      props.includesBaseElement,
+      syncState?.includesBaseElement,
+      false,
+    ),
+    orientation: defaultValue(
+      props.orientation,
+      syncState?.orientation,
+      "horizontal" as const,
+    ),
+    focusLoop: defaultValue(props.focusLoop, syncState?.focusLoop, true),
+  });
+
+  const panels = createCollectionStore<TabStorePanel>();
+
+  const initialState: TabStoreState = {
+    ...composite.getState(),
+    selectedId: defaultValue(
+      props.selectedId,
+      syncState?.selectedId,
+      props.defaultSelectedId,
+    ),
+    selectOnMove: defaultValue(
+      props.selectOnMove,
+      syncState?.selectOnMove,
+      true,
+    ),
+  };
+  const tab = createStore(initialState, composite, store);
+
+  // Selects the active tab when selectOnMove is true. Since we're listening to
+  // the moves state, but not the activeId state, this callback will run only
+  // when there's a move, which is usually triggered by moving through the tabs
+  // using the keyboard.
+  setup(tab, () =>
+    sync(tab, ["moves"], () => {
+      const { activeId, selectOnMove } = tab.getState();
+      if (!selectOnMove) return;
+      if (!activeId) return;
+      const tabItem = composite.item(activeId);
+      if (!tabItem) return;
+      if (tabItem.dimmed) return;
+      if (tabItem.disabled) return;
+      tab.setState("selectedId", tabItem.id);
+    }),
+  );
+
+  let syncActiveId = true;
+
+  // Keep activeId in sync with selectedId.
+  setup(tab, () =>
+    batch(tab, ["selectedId"], (state, prev) => {
+      // There are cases where we don't want to sync activeId with selectedId.
+      // For example, restoring the selectedId from a select or combobox
+      // selected value. In those cases, we set syncActiveId to false.
+      if (!syncActiveId) {
+        syncActiveId = true;
+        return;
+      }
+      // If there's a parent composite widget, we don't need to sync the
+      // activeId state with the initial selectedId state. The parent composite
+      // widget should handle the initial activeId state.
+      if (parentComposite && state.selectedId === prev.selectedId) return;
+      tab.setState("activeId", state.selectedId);
+    }),
+  );
+
+  // Automatically set selectedId if it's undefined.
+  setup(tab, () =>
+    sync(tab, ["selectedId", "renderedItems"], (state) => {
+      if (state.selectedId !== undefined) return;
+      // First, we try to set selectedId based on the current active tab.
+      const { activeId, renderedItems } = tab.getState();
+      const tabItem = composite.item(activeId);
+      if (tabItem && !tabItem.disabled && !tabItem.dimmed) {
+        tab.setState("selectedId", tabItem.id);
+      }
+      // If there's no active tab or the active tab is dimmed, we get the
+      // first enabled tab instead.
+      else {
+        const tabItem = renderedItems.find(
+          (item) => !item.disabled && !item.dimmed,
+        );
+        tab.setState("selectedId", tabItem?.id);
+      }
+    }),
+  );
+
+  // Keep panels tabIds in sync with the current tabs.
+  setup(tab, () =>
+    sync(tab, ["renderedItems"], (state) => {
+      const tabs = state.renderedItems;
+      if (!tabs.length) return;
+      return sync(panels, ["renderedItems"], (state) => {
+        const items = state.renderedItems;
+        const hasOrphanPanels = items.some((panel) => !panel.tabId);
+        if (!hasOrphanPanels) return;
+        items.forEach((panel, i) => {
+          if (panel.tabId) return;
+          const tabItem = tabs[i];
+          if (!tabItem) return;
+          panels.renderItem({ ...panel, tabId: tabItem.id });
+        });
+      });
+    }),
+  );
+
+  // Preserve the selected tab when a select or combobox value is selected
+  // within the tab panel.
+  let selectedIdFromSelectedValue: string | null | undefined = null;
+
+  setup(tab, () => {
+    const backupSelectedId = () => {
+      selectedIdFromSelectedValue = tab.getState().selectedId;
+    };
+    const restoreSelectedId = () => {
+      // We set syncActiveId to false to prevent the activeId state from being
+      // set to the selectedId state since this is just a restoration of the
+      // selectedId state from a select or combobox selected value.
+      syncActiveId = false;
+      tab.setState("selectedId", selectedIdFromSelectedValue);
+    };
+    if (parentComposite && "setSelectElement" in parentComposite) {
+      return chain(
+        sync(parentComposite, ["value"], backupSelectedId),
+        sync(parentComposite, ["mounted"], restoreSelectedId),
+      );
+    }
+    if (!combobox) return;
+    return chain(
+      sync(combobox, ["selectedValue"], backupSelectedId),
+      sync(combobox, ["mounted"], restoreSelectedId),
+    );
+  });
+
+  return {
+    ...composite,
+    ...tab,
+    panels,
+    setSelectedId: (id) => tab.setState("selectedId", id),
+    select: (id) => {
+      tab.setState("selectedId", id);
+      composite.move(id);
+    },
+  };
+}
+
+export interface TabStoreItem extends CompositeStoreItem {
+  dimmed?: boolean;
+}
+
+export interface TabStorePanel extends CollectionStoreItem {
+  tabId?: string | null;
+}
+
+export interface TabStoreState extends CompositeStoreState<TabStoreItem> {
+  /** @default "horizontal" */
+  orientation: CompositeStoreState<TabStoreItem>["orientation"];
+  /** @default true */
+  focusLoop: CompositeStoreState<TabStoreItem>["focusLoop"];
+  /**
+   * The id of the tab whose panel is currently visible. If it's `undefined`, it
+   * will be automatically set to the first enabled tab.
+   *
+   * Live examples:
+   * - [Tab with React Router](https://ariakit.com/examples/tab-react-router)
+   * - [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)
+   */
+  selectedId: TabStoreState["activeId"];
+  /**
+   * Determines if the tab should be selected when it receives focus. If set to
+   * `false`, the tab will only be selected upon clicking, not when using arrow
+   * keys to shift focus.
+   *
+   * Live examples:
+   * - [Tab with React Router](https://ariakit.com/examples/tab-react-router)
+   * - [Select with Combobox and
+   *   Tabs](https://ariakit.com/examples/select-combobox-tab)
+   * @default true
+   */
+  selectOnMove?: boolean;
+}
+
+export interface TabStoreFunctions extends CompositeStoreFunctions<TabStoreItem> {
+  /**
+   * Sets the
+   * [`selectedId`](https://ariakit.com/reference/tab-provider#selectedid) state
+   * without moving focus. If you want to move focus, use the
+   * [`select`](https://ariakit.com/reference/use-tab-store#select) function
+   * instead.
+   * @example
+   * // Selects the tab with id "tab-1"
+   * store.setSelectedId("tab-1");
+   * // Toggles between "tab-1" and "tab-2"
+   * store.setSelectedId((id) => id === "tab-1" ? "tab-2" : "tab-1"));
+   * // Selects the first tab
+   * store.setSelectedId(store.first());
+   * // Selects the next tab
+   * store.setSelectedId(store.next());
+   */
+  setSelectedId: SetState<TabStoreState["selectedId"]>;
+  /**
+   * A collection store containing the tab panels.
+   *
+   * Live examples:
+   * - [Animated TabPanel](https://ariakit.com/examples/tab-panel-animated)
+   */
+  panels: CollectionStore<TabStorePanel>;
+  /**
+   * Selects the tab for the given id and moves focus to it. If you want to set
+   * the [`selectedId`](https://ariakit.com/reference/tab-provider#selectedid)
+   * state without moving focus, use the
+   * [`setSelectedId`](https://ariakit.com/reference/use-tab-store#setselectedid-1)
+   * function instead.
+   * @example
+   * // Selects the tab with id "tab-1"
+   * store.select("tab-1");
+   * // Selects the first tab
+   * store.select(store.first());
+   * // Selects the next tab
+   * store.select(store.next());
+   */
+  select: TabStore["move"];
+}
+
+export interface TabStoreOptions
+  extends
+    StoreOptions<
+      TabStoreState,
+      "orientation" | "focusLoop" | "selectedId" | "selectOnMove"
+    >,
+    CompositeStoreOptions<TabStoreItem> {
+  /**
+   * A reference to another [composite
+   * store](https://ariakit.com/reference/use-composite-store). This is used when
+   * rendering tabs as part of another composite widget such as
+   * [Combobox](https://ariakit.com/components/combobox) or
+   * [Select](https://ariakit.com/components/select). The stores will share the
+   * same state.
+   */
+  composite?: CompositeStore | SelectStore | null;
+  /**
+   * A reference to a [combobox
+   * store](https://ariakit.com/reference/use-combobox-store). This is used when
+   * rendering tabs inside a
+   * [Combobox](https://ariakit.com/components/combobox).
+   */
+  combobox?: ComboboxStore | null;
+  /**
+   * The id of the tab whose panel is currently visible. If it's `undefined`, it
+   * will be automatically set to the first enabled tab.
+   *
+   * Live examples:
+   * - [Combobox with Tabs](https://ariakit.com/examples/combobox-tabs)
+   * - [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)
+   */
+  defaultSelectedId?: TabStoreState["selectedId"];
+}
+
+export interface TabStoreProps
+  extends TabStoreOptions, StoreProps<TabStoreState> {}
+
+export interface TabStore extends TabStoreFunctions, Store<TabStoreState> {}