@react-md/core 1.0.0-next.19 → 1.0.0-next.20

package/src/tabs/useTabs.ts

@@ -1,17 +1,12 @@
 "use client";
-import {
-  type Dispatch,
-  type Ref,
-  type RefObject,
-  useEffect,
-  useRef,
-  useState,
-} from "react";
+
+import { type Dispatch, type Ref, useEffect, useRef, useState } from "react";
+
 import { type SlideDirection } from "../transition/SlideContainer.js";
 import { type UseStateInitializer, type UseStateSetter } from "../types.js";
 import { useEnsuredId } from "../useEnsuredId.js";
 import { useEnsuredState } from "../useEnsuredState.js";
-
+import { applyRef } from "../utils/applyRef.js";
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 import { type TabProps } from "./Tab.js";
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
@@ -140,14 +135,22 @@ export interface TabsImplementation<TabValue extends string | number = number> {
   getTabProps: (tabValue: TabValue) => ProvidedTabProps;
   getTabListProps: () => ProvidedTabListProps;
   getTabPanelProps: (tabValue: TabValue) => ProvidedTabPanelProps;
-  getTabPanelsProps: <E extends HTMLElement>() => ProvidedTabPanelsProps<E>;
+  getTabPanelsProps: <E extends HTMLElement>(
+    ref?: Ref<E>
+  ) => ProvidedTabPanelsProps<E>;
 }
 
 /**
  * @example Super Simple
  * ```tsx
- * import { TabList, Tab, SlideContainer, Slide, useTabs } from "@react-md/core";
- * import type { ReactElement } from "react";
+ * "use client";
+ *
+ * import { Tab } from "@react-md/core/tabs/Tab";
+ * import { TabList } from "@react-md/core/tabs/TabList";
+ * import { useTabs } from "@react-md/core/tabs/useTabs";
+ * import { Slide } from "@react-md/core/transition/Slide";
+ * import { SlideContainer } from "@react-md/core/transition/SlideContainer";
+ * import { type ReactElement } from "react";
  *
  * function Example(): ReactElement {
  *   const {
@@ -190,9 +193,14 @@ export function useTabs(): TabsImplementation & {
  *
  * @example Controlled
  * ```tsx
- * import { TabList, Tab, SlideContainer, Slide, useTabs } from "@react-md/core";
- * import type { ReactElement } from "react";
- * import { useState } from "react";
+ * "use client";
+ *
+ * import { Tab } from "@react-md/core/tabs/Tab";
+ * import { TabList } from "@react-md/core/tabs/TabList";
+ * import { useTabs } from "@react-md/core/tabs/useTabs";
+ * import { Slide } from "@react-md/core/transition/Slide";
+ * import { SlideContainer } from "@react-md/core/transition/SlideContainer";
+ * import { type ReactElement, useState } from "react";
  *
  * function Example(): ReactElement {
  *   const [activeTab, setActiveTab] = useState(1);
@@ -253,8 +261,14 @@ export function useTabs<TabValue extends number>(
  *
  * @example String Value Simple
  * ```tsx
- * import { TabList, Tab, SlideContainer, Slide, useTabs } from "@react-md/core";
- * import type { ReactElement } from "react";
+ * "use client";
+ *
+ * import { Tab } from "@react-md/core/tabs/Tab";
+ * import { TabList } from "@react-md/core/tabs/TabList";
+ * import { useTabs } from "@react-md/core/tabs/useTabs";
+ * import { Slide } from "@react-md/core/transition/Slide";
+ * import { SlideContainer } from "@react-md/core/transition/SlideContainer";
+ * import { type ReactElement } from "react";
  *
  * const tabs = ["value-1", "value-2", "value-3"];
  *
@@ -306,8 +320,12 @@ export function useTabs<TabValue extends string>(
  *
  * @example String Controlled Simple
  * ```tsx
- * import { TabList, Tab, SlideContainer, Slide, useTabs } from "@react-md/core";
- * import type { ReactElement } from "react";
+ * import { Tab } from "@react-md/core/tabs/Tab";
+ * import { TabList } from "@react-md/core/tabs/TabList";
+ * import { useTabs } from "@react-md/core/tabs/useTabs";
+ * import { Slide } from "@react-md/core/transition/Slide";
+ * import { SlideContainer } from "@react-md/core/transition/SlideContainer";
+ * import { type ReactElement } from "react";
  *
  * const tabs = ["value-1", "value-2", "value-3"] as const;
  *
@@ -347,63 +365,27 @@ export function useTabs<TabValue extends string>(
  * @example Navigation Tabs
  * ```tsx
  * "use client";
- * import {
- *   RippleContainer,
- *   Tab,
- *   TabList,
- *   useElementInteraction,
- *   useEnsuredId,
- *   useHigherContrastChildren,
- *   useKeyboardMovementContext,
- *   useTabs,
- * } from "@react-md/core";
- * import type { LinkProps } from "next/link";
- * import Link from "next/link";
- * import type { PropsWithChildren, ReactElement } from "react";
- * import { usePathname } from "next/navigation";
  *
- * interface TabLinkProps extends LinkProps {
- *   active: boolean;
- * }
- *
- * function TabLink(props: LinkProps): ReactElement {
- *   const {
- *     id: propId,
- *     children: propChildren,
- *     active,
- *     className,
- *     ...remaining,
- *   } = props;
- *
- *   const id = useEnsuredId(propId, "tab");
- *   const { activeDescendantId } = useKeyboardMovementContext();
- *   const { handlers, ripples } = useElementInteraction(props);
- *   const children = useHigherContrastChildren(propChildren);
- *
- *   return (
- *     <Link
- *       {...props}
- *       {...handlers}
- *       id={id}
- *       aria-selected={active}
- *       role="tab"
- *       tabIndex={id === activeDescendantId ? 0 : -1}
- *       className={tab({
- *         className,
- *         active,
- *         // stacked,
- *         // reversed,
- *       })}
- *     >
- *       {children}
- *       {ripples}
- *     </Link>
- *   );
- * }
+ * import { Tab } from "@react-md/core/tabs/Tab";
+ * import { TabList } from "@react-md/core/tabs/TabList";
+ * import { useTabs } from "@react-md/core/tabs/useTabs";
+ * import Link from "next/link.js";
+ * import { usePathname } from "next/navigation.js";
+ * import {
+ *   type AnchorHTMLAttributes,
+ *   type ReactElement,
+ *   forwardRef,
+ *   useEffect,
+ *   useState,
+ * } from "react";
  *
- * const noop = (): void => {
- *  // do nothing
- * };
+ * // this just fixes the `href` type definition causing errors
+ * const SimpleLink = forwardRef<
+ *   HTMLAnchorElement,
+ *   AnchorHTMLAttributes<HTMLAnchorElement> & { href: string }
+ * >(function SimpleLink(props, ref) {
+ *   return <Link {...props} ref={ref} />;
+ * });
  *
  * const PATHNAME_TABS = ["/", "/page-1", "/page-2"];
  *
@@ -418,9 +400,9 @@ export function useTabs<TabValue extends string>(
  *   return (
  *     <>
  *       <TabList {...getTabListProps()}>
- *         <TabLink {...getTabProps("/")} href="/">Home</TabLink>
- *         <TabLink {...getTabProps("/page-1")} href="/page-1">Page 1</TabLink>
- *         <TabLink {...getTabProps("/page-2")} href="/page-2">Page 2</TabLink>
+ *         <Tab {...getTabProps("/")} href="/" as={SimpleLink}>Home</Tab>
+ *         <Tab {...getTabProps("/page-1")} href="/page-1" as={SimpleLink}>Page 1</Tab>
+ *         <Tab {...getTabProps("/page-2")} href="/page-2" as={SimpleLink}>Page 2</Tab>
  *       </TabList>
  *       <main>{children}</main>
  *     </>
@@ -526,9 +508,12 @@ export function useTabs<TabValue extends string | number>(
         active: tabValue === activeTab,
       };
     },
-    getTabPanelsProps<E>() {
+    getTabPanelsProps(ref) {
       return {
-        ref: tabPanelsRef as RefObject<E>,
+        ref: (instance) => {
+          applyRef(instance, ref);
+          applyRef(instance, tabPanelsRef);
+        },
         direction,
       };
     },

package/src/tabs/utils.ts

@@ -5,6 +5,15 @@ export const getTabRoleOnly = (container: Element): readonly HTMLElement[] => [
   ...container.querySelectorAll<HTMLElement>('[role="tab"]'),
 ];
 
+/**
+ * @internal
+ */
+export const getTabPanelRoleOnly = (
+  container: Element
+): readonly HTMLElement[] => [
+  ...container.querySelectorAll<HTMLElement>('[role="tabpanel"]'),
+];
+
 /** @internal */
 interface ScrollOptions {
   container: HTMLElement | null;

package/src/test-utils/drag.ts

@@ -1,5 +1,6 @@
 import { fireEvent } from "@testing-library/dom";
 import type { MouseEvent } from "react";
+
 import { wait } from "../utils/wait.js";
 
 interface XYCoords {
@@ -9,6 +10,7 @@ interface XYCoords {
 
 interface BaseDragOptions {
   to?: XYCoords | Element;
+  from?: XYCoords;
   delta?: XYCoords;
   steps?: number;
   duration?: number;
@@ -41,8 +43,14 @@ export async function drag(
   element: Element,
   options: DragOptions
 ): Promise<void> {
-  const { delta, to: inTo, steps = 20, duration = 500 } = options;
-  const from = getElementClientCenter(element);
+  const {
+    delta,
+    to: inTo,
+    from: fromCoords,
+    steps = 20,
+    duration = 500,
+  } = options;
+  const from = fromCoords ?? getElementClientCenter(element);
   const to = delta
     ? {
         x: from.x + delta.x,

package/src/test-utils/index.ts

@@ -1,8 +1,9 @@
 export * from "@testing-library/react";
 export * from "@testing-library/user-event";
-
-export * from "./IntersectionObserver.js";
-export * from "./ResizeObserver.js";
-export * from "./matchMedia.js";
+export * from "./mocks/IntersectionObserver.js";
+export * from "./mocks/match-media.js";
+export * from "./mocks/ResizeObserver.js";
+export * from "./queries/index.js";
 export * from "./render.js";
-export * from "./timers.js";
+export * from "./utils/createResizeObserverEntry.js";
+export * from "./utils/createFileList.js";

package/src/test-utils/jest-globals/index.ts

@@ -0,0 +1,4 @@
+export * from "./match-media.js";
+export * from "./timers.js";
+export * from "./uploadMenuItemFileInput.js";
+export * from "./resize-observer.js";

package/src/test-utils/jest-globals/match-media.ts

@@ -0,0 +1,41 @@
+import { jest } from "@jest/globals";
+
+import {
+  type MatchMediaChangeViewport,
+  createMatchMediaSpy,
+} from "../mocks/match-media-implementation.js";
+import { type MatchMediaMatcher, matchDesktop } from "../mocks/match-media.js";
+
+/**
+ * @example Default Behavior
+ * ```tsx
+ * import { matchPhone, render } from "@react-md/core/test-utils";
+ * import { spyOnMatchMedia } from "@react-md/core/test-utils/jest-globals";
+ *
+ * const matchMedia = spyOnMatchMedia();
+ * render(<Test />);
+ *
+ * // expect desktop results
+ *
+ * matchMedia.changeViewport(matchPhone);
+ * // expect phone results
+ * ```
+ *
+ * @example Set Default Media
+ * ```tsx
+ * import { matchPhone, render } from "@react-md/core/test-utils";
+ * import { spyOnMatchMedia } from "@react-md/core/test-utils/jest-globals";
+ *
+ * const matchMedia = spyOnMatchMedia(matchPhone);
+ * render(<Test />);
+ *
+ * // expect phone results
+ * ```
+ *
+ * @since 6.0.0
+ */
+export function spyOnMatchMedia(
+  defaultMatch: MatchMediaMatcher = matchDesktop
+): jest.SpiedFunction<typeof window.matchMedia> & MatchMediaChangeViewport {
+  return createMatchMediaSpy(jest.spyOn(window, "matchMedia"), defaultMatch);
+}

package/src/test-utils/jest-globals/resize-observer.ts

@@ -0,0 +1,11 @@
+import { afterEach, jest } from "@jest/globals";
+
+import { cleanupResizeObserverAfterEach as cleanup } from "../mocks/ResizeObserver.js";
+
+/**
+ * @param restoreAllMocks - Set to `false` to prevent `jest.restoreAllMocks()` from being
+ * called.
+ */
+export function cleanupResizeObserverAfterEach(restoreAllMocks = true): void {
+  cleanup(afterEach, restoreAllMocks ? jest.restoreAllMocks : undefined);
+}

package/src/test-utils/{jest-setup.ts → jest-globals/setup.ts}

@@ -1,6 +1,8 @@
 import { beforeEach } from "@jest/globals";
-import { INTERACTION_CONFIG } from "../interaction/config.js";
-import { TRANSITION_CONFIG } from "../transition/config.js";
+import "@testing-library/jest-dom/jest-globals";
+
+import { INTERACTION_CONFIG } from "../../interaction/config.js";
+import { TRANSITION_CONFIG } from "../../transition/config.js";
 
 beforeEach(() => {
   // set the mode to `none` in tests since ripples require

package/src/test-utils/{timers.ts → jest-globals/timers.ts}

@@ -8,7 +8,7 @@ export type RafSpy = jest.SpiedFunction<typeof requestAnimationFrame>;
 /**
  * @example
  * ```ts
- * import { testImmediateRaf } from "@react-md/core/test-utils";
+ * import { testImmediateRaf } from "@react-md/core/test-utils/jest-globals";
  *
  * describe("some test suite", () => {
  *   it("should test something with requestAnimationFrame", () => {
@@ -24,7 +24,7 @@ export type RafSpy = jest.SpiedFunction<typeof requestAnimationFrame>;
  *
  * @example Automatic Cleanup
  * ```ts
- * import { testImmediateRaf } from "@react-md/core/test-utils";
+ * import { testImmediateRaf } from "@react-md/core/test-utils/jest-globals";
  *
  * afterEach(() => {
  *   jest.restoreAllMocks();

package/src/test-utils/jest-globals/uploadMenuItemFileInput.ts

@@ -0,0 +1,52 @@
+import { jest } from "@jest/globals";
+import { fireEvent } from "@testing-library/dom";
+import { type UserEvent } from "@testing-library/user-event";
+
+import { createFileList } from "../utils/createFileList.js";
+
+/**
+ * @since 6.0.0
+ */
+export interface UploadMenuItemFileUploadOptions {
+  user: UserEvent;
+  files: File | readonly File[];
+  menuItem: HTMLElement;
+}
+
+/**
+ * @example Main Example
+ * ```tsx
+ * const user = userEvent.setup()
+ * render(<Test />);
+ *
+ * await user.click(screen.getByRole("button", { name: "Dropdown Menu" }));
+ *
+ * const menuItem = screen.getByRole("menuitem", { name: "Upload" });
+ * const file = new File(["pretend-bytes"], "README.txt");
+ * await uploadMenuItemFileUpload({
+ *   user,
+ *   // can be a single file or multiple
+ *   files: file,
+ *   menuItem,
+ * });
+ *
+ * // expect something with uploaded file
+ * ```
+ *
+ * @since 6.0.0
+ */
+export async function uploadMenuItemFileUpload(
+  options: UploadMenuItemFileUploadOptions
+): Promise<void> {
+  const { user, files, menuItem } = options;
+
+  const input = document.createElement("input");
+  jest.spyOn(document, "createElement").mockReturnValueOnce(input);
+  jest.spyOn(input, "click").mockImplementationOnce(() => {
+    fireEvent.change(input, {
+      target: { files: createFileList(window, files) },
+    });
+  });
+
+  await user.click(menuItem);
+}

package/src/test-utils/{ResizeObserver.ts → mocks/ResizeObserver.ts}

@@ -1,56 +1,12 @@
-import { afterEach, jest } from "@jest/globals";
 import {
-  resizeObserverManager,
   type ResizeObserverManager,
-} from "../useResizeObserver.js";
-
-/**
- * @since 6.0.0
- */
-export interface ResizeObserverEntrySize {
-  height?: number;
-  width?: number;
-}
-
-/**
- * @since 6.0.0
- */
-export type GetResizeObserverEntryMock = (
-  target: Element,
-  size?: ResizeObserverEntrySize
-) => ResizeObserverEntry;
-
-/**
- * This is mostly an internal function to be used with the {@link ResizeObserverMock}
- * and {@link setupResizeObserverMock}
- *
- * @since 6.0.0
- */
-export const createResizeObserverEntry: GetResizeObserverEntryMock = (
-  target,
-  size
-) => {
-  const contentRect = target.getBoundingClientRect();
-  if (typeof size?.height === "number") {
-    contentRect.height = size.height;
-  }
-  if (typeof size?.width === "number") {
-    contentRect.width = size.width;
-  }
-
-  const boxSize: ResizeObserverSize = {
-    blockSize: contentRect.height,
-    inlineSize: contentRect.width,
-  };
-
-  return {
-    target,
-    contentRect,
-    borderBoxSize: [boxSize],
-    contentBoxSize: [boxSize],
-    devicePixelContentBoxSize: [],
-  };
-};
+  resizeObserverManager,
+} from "../../useResizeObserver.js";
+import {
+  type GetResizeObserverEntryMock,
+  type ResizeObserverEntrySize,
+  createResizeObserverEntry,
+} from "../utils/createResizeObserverEntry.js";
 
 /**
  * This is the default ResizeObserver implementation if it does not already
@@ -92,7 +48,12 @@ export class ResizeObserverMock implements ResizeObserver {
    * import { useResizeObserver } from "@react-md/core";
    * import { ExampleComponent } from "../ExampleComponent.js";
    *
-   * cleanupResizeObserverAfterEach();
+   * // choose your test framework
+   * import { afterEach, jest } from "@jest/globals";
+   * cleanupResizeObserverAfterEach(afterEach, jest.restoreAllMocks);
+   *
+   * import { afterEach, vitest } from "vitest";
+   * cleanupResizeObserverAfterEach(afterEach, vitest.restoreAllMocks);
    *
    * describe("ExampleComponent", () => {
    *   it("should do stuff", () => {
@@ -226,6 +187,13 @@ export interface SetupResizeObserverMockOptions {
  * import { useResizeObserver } from "@react-md/core/useResizeObserver";
  * import { useCallback, useState } from "react";
  *
+ * // choose your test framework
+ * import { afterEach, jest } from "@jest/globals";
+ * cleanupResizeObserverAfterEach(afterEach, jest.restoreAllMocks);
+ *
+ * import { afterEach, vitest } from "vitest";
+ * cleanupResizeObserverAfterEach(afterEach, vitest.restoreAllMocks);
+ *
  * function ExampleComponent() {
  *   const [size, setSize] = useState({ height: 0, width: 0 });
  *   const ref = useResizeObserver({
@@ -245,8 +213,6 @@ export interface SetupResizeObserverMockOptions {
  *   );
  * }
  *
- * cleanupResizeObserverAfterEach();
- *
  * describe("ExampleComponent", () => {
  *   it("should do stuff", () => {
  *     const observer = setupResizeObserverMock();
@@ -304,14 +270,14 @@ export function setupResizeObserverMock(
  * @see {@link setupResizeObserverMock}
  * @since 6.0.0
  */
-export function cleanupResizeObserverAfterEach(restoreAllMocks = true): void {
+export function cleanupResizeObserverAfterEach(
+  afterEach: (callback: () => void) => void,
+  restoreAllMocks: () => void = () => {}
+): void {
   afterEach(() => {
     resizeObserverManager.frame = 0;
     resizeObserverManager.subscriptions = new Map();
     resizeObserverManager.sharedObserver = undefined;
-
-    if (restoreAllMocks) {
-      jest.restoreAllMocks();
-    }
+    restoreAllMocks();
   });
 }

package/src/test-utils/mocks/match-media-implementation.ts

@@ -0,0 +1,111 @@
+import { act } from "@testing-library/react";
+
+import {
+  BASE_MEDIA_QUERY_LIST,
+  type MatchMediaMatcher,
+  matchDesktop,
+} from "./match-media.js";
+
+/**
+ * @since 6.0.0
+ */
+export interface MatchMediaChangeViewport {
+  /**
+   * @example Default Behavior
+   * ```tsx
+   * const matchMedia = spyOnMatchMedia();
+   * render(<Test />);
+   *
+   * // expect desktop results
+   *
+   * matchMedia.changeViewport(matchPhone);
+   * // expect phone results
+   * ```
+   *
+   * @example Custom Act Behavior
+   * ```tsx
+   * const matchMedia = spyOnMatchMedia();
+   * const { rerender } = render(<Test />);
+   *
+   * // expect desktop results
+   *
+   * matchMedia.changeViewport(matchPhone, false);
+   * rerender(<Test key="new-key" />);
+   *
+   * // expect phone results
+   * ```
+   */
+  changeViewport: (matcher: MatchMediaMatcher, disableAct?: boolean) => void;
+}
+
+/**
+ * @since 6.0.0
+ */
+export interface MatchMediaMockFunction {
+  mockImplementation(fn: typeof window.matchMedia): this;
+}
+
+/**
+ * @since 6.0.0
+ */
+export const createMatchMediaSpy = <SpyFunction extends MatchMediaMockFunction>(
+  matchMediaSpy: SpyFunction,
+  defaultMatch: MatchMediaMatcher = matchDesktop
+): SpyFunction & MatchMediaChangeViewport => {
+  type Listener = (event: MediaQueryListEvent) => void;
+
+  const listeners = new Map<string, Listener>();
+  const matchMedia = matchMediaSpy.mockImplementation((query) => ({
+    ...BASE_MEDIA_QUERY_LIST,
+    addEventListener(type: string, listener: Listener | EventListenerObject) {
+      /* c8 ignore start */
+      if (typeof listener !== "function" || type !== "change") {
+        return;
+      }
+      /* c8 ignore stop */
+
+      listeners.set(query, listener);
+    },
+    removeEventListener(
+      type: string,
+      listener: Listener | EventListenerObject
+    ) {
+      /* c8 ignore start */
+      if (typeof listener !== "function" || type !== "change") {
+        return;
+      }
+      /* c8 ignore stop */
+
+      listeners.delete(query);
+    },
+    matches: defaultMatch(query),
+  }));
+
+  const changeViewport = (
+    matcher: MatchMediaMatcher,
+    disableAct = false
+  ): void => {
+    const update = (): void => {
+      window.dispatchEvent(new Event("resize"));
+
+      const event = new Event("change");
+      listeners.forEach((listener, query) => {
+        listener({
+          ...event,
+          media: "",
+          matches: matcher(query),
+        });
+      });
+    };
+    if (disableAct) {
+      update();
+    } else {
+      act(update);
+    }
+  };
+
+  const mock = matchMedia as SpyFunction & MatchMediaChangeViewport;
+  mock.changeViewport = changeViewport;
+
+  return mock;
+};