@react-md/core 1.0.0-next.0

package/src/tree/useTreeItems.ts

@@ -0,0 +1,137 @@
+import { useMemo } from "react";
+import type {
+  TreeItemSorter,
+  TreeItemNode,
+  TreeData,
+  DefaultTreeItemNode,
+} from "./types.js";
+
+/**
+ * A lookup to find all the child ids for a specific parent. This was added to
+ * support the `*` keyboard behavior of opening all tree items at the current
+ * level.
+ *
+ * @remarks \@since 6.0.0
+ * @internal
+ */
+export type TreeItemChildIds = Map<string | null, Set<string>>;
+
+/**
+ * @remarks \@since 6.0.0
+ * @internal
+ */
+export type RenderableTreeItemNode<
+  T extends TreeItemNode = DefaultTreeItemNode,
+> = T & {
+  items?: readonly RenderableTreeItemNode<T>[];
+};
+
+/**
+ * @remarks \@since 6.0.0
+ * @internal
+ */
+export interface BuildTreeOptions<T extends TreeItemNode> {
+  sort: TreeItemSorter<T>;
+  nodes: T[];
+  parentId: string | null;
+  treeItemChildIds: TreeItemChildIds;
+}
+
+/**
+ * This util performantly builds a nested list of tree items from a giant flat
+ * list of items by linking items together with the provided `parentId`. This
+ * will also recursively build the tree and _hopefully_ all items will be added.
+ *
+ * @remarks \@since 6.0.0 Updated to include the {@link TreeItemChildIds}
+ */
+export function buildTree<T extends TreeItemNode>(
+  options: BuildTreeOptions<T>
+): readonly RenderableTreeItemNode<T>[] | undefined {
+  const { sort, nodes, parentId, treeItemChildIds } = options;
+  const childIds = treeItemChildIds.get(parentId) || new Set();
+  const childItems: RenderableTreeItemNode<T>[] = [];
+
+  // doing a "reverse" order filter/move so that the items array shrinks while
+  // looping. This makes it so that the entire items array doesn't need to
+  // continually be looped through as more items are added to the tree, only the
+  // remaining items will have to be looped
+  let i = nodes.length;
+  while (i > 0) {
+    i -= 1;
+    if (nodes[i] && nodes[i].parentId === parentId) {
+      const [item] = nodes.splice(i, 1);
+      childIds.add(item.itemId);
+      // shallow cloning so childItems doesn't get applied to the original data
+      // set
+      childItems.unshift({ ...item });
+    }
+  }
+
+  if (!childItems.length) {
+    return undefined;
+  }
+
+  treeItemChildIds.set(parentId, childIds);
+  childItems.forEach((childItem) => {
+    childItem.items = buildTree({
+      sort,
+      nodes,
+      parentId: childItem.itemId,
+      treeItemChildIds,
+    });
+  });
+
+  return sort(childItems);
+}
+
+/**
+ * @remarks \@since 6.0.0
+ */
+export interface TreeItemOptions<T extends TreeItemNode> {
+  data: TreeData<T>;
+  sort: TreeItemSorter<T>;
+  rootId: string | null;
+}
+
+/**
+ * @remarks \@since 6.0.0
+ */
+export interface TreeItems<T extends TreeItemNode> {
+  items: readonly RenderableTreeItemNode<T>[];
+  treeItemChildIds: TreeItemChildIds;
+}
+
+/**
+ * This is mostly an internal hook, but can be used to build tree-like
+ * data structures without the need of the `Tree` component.
+ *
+ * @remarks \@since 6.0.0 converted to use an object argument instead of
+ * multiple arguments. Also logs any orphaned items that do not have a parent
+ */
+export function useTreeItems<T extends TreeItemNode>(
+  options: TreeItemOptions<T>
+): TreeItems<T> {
+  const { data, sort, rootId } = options;
+
+  return useMemo<TreeItems<T>>(() => {
+    const values = Object.values(data);
+    const treeItemChildIds = new Map<string, Set<string>>();
+    const items = buildTree<T>({
+      sort,
+      nodes: values,
+      parentId: rootId,
+      treeItemChildIds,
+    });
+
+    if (process.env.NODE_ENV !== "production" && values.length) {
+      /* eslint-disable no-console */
+      console.warn("The following tree items are orphaned without a parent:");
+      console.warn(values.slice());
+    }
+
+    return {
+      items: items || [],
+      treeItemChildIds,
+    };
+  }, [data, rootId, sort]);
+}

package/src/tree/useTreeMovement.ts

@@ -0,0 +1,205 @@
+"use client";
+import type {
+  FocusEventHandler,
+  KeyboardEventHandler,
+  MouseEventHandler,
+} from "react";
+import { useRef } from "react";
+import type { KeyboardMovementProviderImplementation } from "../movement/types.js";
+import { useKeyboardMovementProvider } from "../movement/useKeyboardMovementProvider.js";
+import { getNextFocusableIndex } from "../movement/utils.js";
+import type { NonNullMutableRef } from "../types.js";
+import type { TreeItemMetadataLookup } from "./TreeProvider.js";
+import type { TreeData, TreeItemNode } from "./types.js";
+import type { TreeExpansion } from "./useTreeExpansion.js";
+import type { TreeItemChildIds } from "./useTreeItems.js";
+
+/**
+ * This helps catch the edge case where the collapse transition has occurred for
+ * a tree item group, but the user uses the `ArrowDown` key before it has
+ * finished. So to do this:
+ *
+ * - find the parent group of the tree item
+ * - find the tree item that controls the group (the element before the group)
+ * - check if the `aria-expanded` state is `"false"` meaning it is considered
+ *   closed
+ *
+ * @internal
+ * @remarks \@since 6.0.0
+ */
+const isParentItemCollapsing = (item: HTMLElement): boolean =>
+  item
+    .closest("[role='group']")
+    ?.previousElementSibling?.getAttribute("aria-expanded") === "false";
+
+/**
+ * @remarks \@since 6.0.0
+ * @internal
+ */
+const getVisibleTreeItems = (
+  container: HTMLElement
+): readonly HTMLElement[] => {
+  const items = [
+    ...container.querySelectorAll<HTMLElement>('[role="treeitem"]'),
+  ];
+
+  return items.filter(
+    (item) =>
+      // do not include items that have a `hidden` parent group
+      item.offsetParent &&
+      // do not include items that are about to become hidden
+      !isParentItemCollapsing(item)
+  );
+};
+
+/**
+ * @remarks \@since 6.0.0
+ * @internal
+ */
+interface TreeMovementOptions<T extends TreeItemNode> extends TreeExpansion {
+  data: TreeData<T>;
+  onClick: MouseEventHandler<HTMLUListElement> | undefined;
+  onFocus: FocusEventHandler<HTMLUListElement> | undefined;
+  onKeyDown: KeyboardEventHandler<HTMLUListElement> | undefined;
+  selectedIds: ReadonlySet<string>;
+  treeItemChildIds: TreeItemChildIds;
+}
+
+/**
+ * @remarks \@since 6.0.0
+ * @internal
+ */
+interface TreeMovement
+  extends KeyboardMovementProviderImplementation<HTMLUListElement> {
+  /**
+   * This will be mutated by the `TreeItem` component and used to handle
+   * keyboard movement.
+   */
+  metadataLookup: NonNullMutableRef<TreeItemMetadataLookup>;
+}
+
+/**
+ * @remarks \@since 6.0.0
+ * @internal
+ */
+export function useTreeMovement<T extends TreeItemNode>(
+  options: TreeMovementOptions<T>
+): TreeMovement {
+  const {
+    onClick,
+    onFocus,
+    onKeyDown,
+    data,
+    expandedIds,
+    selectedIds,
+    treeItemChildIds,
+    toggleTreeItemExpansion,
+    expandMultipleTreeItems,
+  } = options;
+
+  const metadataLookup = useRef<TreeItemMetadataLookup>({
+    expandable: {},
+    disabledItems: {},
+    elementToItem: {},
+    itemToElement: {},
+  });
+  const movement = useKeyboardMovementProvider({
+    onClick,
+    onFocus,
+    onKeyDown,
+    extendKeyDown(movementData) {
+      const { event, activeDescendantId, currentFocusIndex, setFocusIndex } =
+        movementData;
+      const { expandable, disabledItems, elementToItem, itemToElement } =
+        metadataLookup.current;
+      const itemId = elementToItem[activeDescendantId];
+      const item = data[itemId];
+
+      /* c8 ignore start */
+      if (!item) {
+        return;
+      }
+      /* c8 ignore end */
+
+      const disabled = disabledItems[itemId];
+      const expanded = expandedIds.has(itemId);
+
+      let flagged = false;
+      switch (event.key) {
+        case "ArrowLeft":
+          if (expanded && !disabled) {
+            flagged = true;
+            toggleTreeItemExpansion(itemId);
+          } else if (item.parentId) {
+            // do not flag for this case since setFocusIndex already does this
+            const parentId = itemToElement[item.parentId];
+            const focusables = getVisibleTreeItems(event.currentTarget);
+            const index = focusables.findIndex(
+              (element) => element.id === parentId
+            );
+            setFocusIndex(index, focusables);
+          }
+
+          break;
+        case "ArrowRight":
+          if (expandable[itemId] && !disabled) {
+            if (!expanded) {
+              flagged = true;
+              toggleTreeItemExpansion(itemId);
+            } else {
+              // do not flag for this case since setFocusIndex already does this
+              const focusables = getVisibleTreeItems(event.currentTarget);
+              const index = getNextFocusableIndex({
+                loopable: false,
+                increment: true,
+                focusables,
+                includeDisabled: true,
+                currentFocusIndex: currentFocusIndex.current,
+              });
+
+              setFocusIndex(index, focusables);
+            }
+          }
+
+          break;
+        case "*": {
+          flagged = true;
+          const itemIds = treeItemChildIds.get(item.parentId);
+          if (itemIds) {
+            const expandableIds = [...itemIds].filter(
+              (itemId) => expandable[itemId]
+            );
+            if (expandableIds.length) {
+              expandMultipleTreeItems(
+                (prev) => new Set([...prev, ...expandableIds])
+              );
+              currentFocusIndex.current = -1;
+            }
+          }
+          break;
+        }
+      }
+
+      if (flagged) {
+        event.stopPropagation();
+        event.preventDefault();
+      }
+    },
+    searchable: true,
+    tabIndexBehavior: "virtual",
+    getFocusableElements: getVisibleTreeItems,
+    getDefaultFocusedIndex(options) {
+      const { focusables } = options;
+      const { elementToItem } = metadataLookup.current;
+
+      return focusables.findIndex((element) =>
+        selectedIds.has(elementToItem[element.id])
+      );
+    },
+  });
+
+  return {
+    metadataLookup,
+    ...movement,
+  };
+}

package/src/tree/useTreeSelection.ts

@@ -0,0 +1,63 @@
+"use client";
+import { useCallback, useState } from "react";
+import type { UseStateSetter } from "../types.js";
+import type { TreeItemDefaultIds, TreeItemIdSet } from "./types.js";
+
+/**
+ * @remarks \@since 6.0.0 Renamed from `TreeItemSelection` and uses a Set
+ * instead of a list to increase performance. Also renamed `onItemSelect` to
+ * `toggleTreeItemSelection` and `onMultiItemSelect` to
+ * `selectMultipleTreeItems`.
+ */
+export interface TreeSelection {
+  /** @defaultValue `false` */
+  multiSelect?: boolean;
+  selectedIds: ReadonlySet<string>;
+  toggleTreeItemSelection(itemId: string): void;
+  selectMultipleTreeItems: UseStateSetter<TreeItemIdSet>;
+}
+
+/**
+ * @remarks \@since 6.0.0 Renamed from `useTreeItemSelection` and uses a Set
+ * instead of a list to increase performance.
+ */
+export function useTreeSelection(
+  defaultSelectedIds?: TreeItemDefaultIds,
+  multiSelect = false
+): Required<TreeSelection> {
+  const [selectedIds, setSelectedIds] = useState<TreeItemIdSet>(() => {
+    const defaultIds =
+      typeof defaultSelectedIds === "function"
+        ? defaultSelectedIds()
+        : defaultSelectedIds;
+
+    return new Set(defaultIds);
+  });
+
+  const toggleTreeItemSelection = useCallback(
+    (itemId: string) => {
+      setSelectedIds((selectedIds) => {
+        if (!multiSelect) {
+          return selectedIds.has(itemId) ? selectedIds : new Set([itemId]);
+        }
+
+        const nextSelectedIds = new Set(selectedIds);
+        if (selectedIds.has(itemId)) {
+          nextSelectedIds.delete(itemId);
+        } else {
+          nextSelectedIds.add(itemId);
+        }
+
+        return nextSelectedIds;
+      });
+    },
+    [multiSelect]
+  );
+
+  return {
+    selectedIds,
+    multiSelect,
+    toggleTreeItemSelection,
+    selectMultipleTreeItems: setSelectedIds,
+  };
+}

package/src/tree/utils.ts

@@ -0,0 +1,64 @@
+import type { TreeItemNode, TreeData, DefaultTreeItemNode } from "./types.js";
+
+/**
+ * This will get all the items from the provided itemId up to the root of the
+ * tree that can be used for drag and drop behavior or building a breadcrumb
+ * list.
+ *
+ * @param data - The flattened tree data to navigate.
+ * @param itemId - The item id to start the search at.
+ * @returns an ordered list of the current item followed by all the direct
+ * parents of that item.
+ * @remarks \@since 6.0.0 Renamed from `getItemsFrom` to `getTreeItemsFrom`.
+ */
+export function getTreeItemsFrom<T extends TreeItemNode = DefaultTreeItemNode>(
+  data: TreeData<T>,
+  itemId: string | null
+): readonly T[] {
+  const items: T[] = [];
+  let currentId = itemId;
+  while (currentId) {
+    const item = data[currentId];
+    currentId = item?.parentId ?? null;
+    if (item) {
+      items.push(item);
+    }
+  }
+
+  return items;
+}
+
+/**
+ * Gets all the child items for a specific parent item id. If the `recursive`
+ * argument is enabled, all children of the items will also be returned instead
+ * of only the top level items.
+ *
+ * @param data - Either the flattened tree data or a list of all the tree data
+ * to iterate over
+ * @param parentId - The parent id to get children of
+ * @param recursive - Boolean if the children's children should also be returned
+ * @returns a list of all the items for a specific parent item id. Note: if the
+ * recursive param is enabled, the list will be ordered so that the children of
+ * a item will appear before the next item at the same level. So you either need
+ * to sort by `parentId` or something else if you want a specific order.
+ * @remarks \@since 6.0.0 Renamed from `getChildItems` to `getChildTreeItems`.
+ */
+export function getChildTreeItems<T extends TreeItemNode = DefaultTreeItemNode>(
+  data: TreeData<T> | readonly T[],
+  parentId: string | null,
+  recursive = false
+): readonly T[] {
+  const items = Array.isArray(data) ? data : Object.values(data);
+
+  return items.reduce<T[]>((list, item) => {
+    if (parentId !== item.parentId) {
+      return list;
+    }
+
+    return [
+      ...list,
+      item,
+      ...(recursive ? getChildTreeItems(items, item.itemId, recursive) : []),
+    ];
+  }, []);
+}

package/src/types.ts

@@ -0,0 +1,176 @@
+import type { Dispatch, ReactElement, Ref, SetStateAction } from "react";
+
+/**
+ * A helper type that allows an optional `ref` to also be applied with a props
+ * object even though a `ref` isn't a real prop.
+ */
+export type PropsWithRef<
+  Props extends {},
+  Element extends HTMLElement,
+> = Props & {
+  /**
+   * An optional ref that can be applied.
+   */
+  ref?: Ref<Element>;
+};
+
+/**
+ * A simple type that can be used for different components that clone a
+ * `className` into a child component.
+ */
+export type ClassNameCloneableChild<T = {}> = ReactElement<
+  T & { className?: string }
+>;
+
+/**
+ * This type allows you to require at least one of the provided keys. This is
+ * super helpful for things like `aria-label` or `aria-labelledby` when it's
+ * required for a11y.
+ *
+ * @see https://stackoverflow.com/questions/40510611/typescript-interface-require-one-of-two-properties-to-exist/49725198#49725198
+ */
+export type RequireAtLeastOne<T, Keys extends keyof T = keyof T> = Pick<
+  T,
+  Exclude<keyof T, Keys>
+> &
+  {
+    [K in Keys]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<Keys, K>>>;
+  }[Keys];
+
+export interface LabelA11y {
+  "aria-label"?: string;
+  "aria-labelledby"?: string;
+}
+
+/**
+ * A small accessibility helper to ensure that either `aria-label` or
+ * `aria-labelledby` have been provided to a component.
+ *
+ * @example
+ * Simple Example
+ * ```ts
+ * import type { HTMLAttributes, ReactElement } from "react";
+ * import type { LabelRequiredForA11y } from "@react-md/core";
+ *
+ * type Props = LabelRequiredForA11y<HTMLAttributes<HTMLDivElement>>;
+ *
+ * function Component(props: Props): ReactElement {
+ *   return <div {...props} />;
+ * }
+ *
+ * const test1 = <Component />
+ * //            ^ type error
+ * const test2 = <Component aria-label="Label" />
+ * const test3 = <Component aria-labelledby="some-other-id" />
+ * ```
+ */
+export type LabelRequiredForA11y<Props extends LabelA11y> = RequireAtLeastOne<
+  Props,
+  keyof LabelA11y
+>;
+
+/**
+ * @remarks \@since 5.0.0
+ * @internal
+ */
+export interface NonNullRef<T> {
+  readonly current: T;
+}
+
+/**
+ * @remarks \@since 6.0.0
+ * @internal
+ */
+export interface NonNullMutableRef<T> {
+  current: T;
+}
+
+/** @remarks \@since 6.0.0 */
+export type HtmlTagName = keyof JSX.IntrinsicElements;
+
+/**
+ * A function to get a string from a generic item.
+ *
+ * @example
+ * Simple Example
+ * ```ts
+ * interface Item {
+ *   name: string;
+ * }
+ *
+ * const items: Item[] = [{ name: 'Hello' }, { name: 'World' }];
+ *
+ * const extractor: TextExtractor<Item> = (item) => item.name;
+ * ```
+ * @remarks \@since 6.0.0
+ */
+export type TextExtractor<T> = (item: T) => string;
+
+/**
+ * @remarks \@since 6.0.0
+ * @internal
+ */
+export type UseStateSetter<T> = Dispatch<SetStateAction<T>>;
+
+/**
+ * @remarks \@since 6.0.0
+ * @internal
+ */
+export type UseStateInitializer<T> = T | (() => T);
+
+/**
+ * @example
+ * ```ts
+ * type Visibility = UseStateObject<"visible", boolean>;
+ * // type Visibility = {
+ * //   visible: boolean;
+ * //   setVisible: UseStateSetter<boolean>
+ * // }
+ *
+ * type AnotherOne = UseStateObject<"renderAsSheet", RenderMenuAsSheet>;
+ * // type AnotherOne = {
+ * //   renderAsSheet: RenderMenuAsSheet;
+ * //   setRenderAsSheet: UseStateSetter<RenderMenuAsSheet>;
+ * // }
+ * ```
+ * @remarks \@since 6.0.0
+ * @internal
+ */
+export type UseStateObject<Name extends string, Value> = {
+  [key in Name]: Value;
+} & {
+  [key in `set${Capitalize<Name>}`]: UseStateSetter<Value>;
+};
+
+/**
+ * @example
+ * ```ts
+ * interface Example {
+ *   value: number;
+ *   setValue: UseStateSetter<number>;
+ * }
+ *
+ * type WithPrefix = RenameKeysWithPrefix<Example, "thumb1">;
+ * // type WithPrefix = {
+ * //   thumb1Value: number;
+ * //   thumb1SetValue: UseStateSetter<number>;
+ * // }
+ * ```
+ *
+ * @remarks \@since 6.0.0
+ * @internal
+ */
+export type RenameKeysWithPrefix<T, Prefix extends string> = {
+  [Key in keyof T & string as `${Prefix}${Capitalize<Key>}`]: T[Key];
+};
+
+/**
+ * @remarks \@since 6.0.0
+ */
+export type CssPosition = "fixed" | "sticky" | "static";
+
+/**
+ * @remarks \@since 6.0.0
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyFunction = (...args: any[]) => any | void;