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

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

@@ -0,0 +1,63 @@
+import {
+  DEFAULT_DESKTOP_LARGE_MIN_WIDTH,
+  DEFAULT_DESKTOP_MIN_WIDTH,
+  DEFAULT_PHONE_MAX_WIDTH,
+  DEFAULT_TABLET_MIN_WIDTH,
+} from "../../media-queries/appSize.js";
+
+const noop = (): void => {
+  // do nothing
+};
+
+/**
+ * @internal
+ * @since 6.0.0
+ */
+export const BASE_MEDIA_QUERY_LIST: MediaQueryList = {
+  media: "",
+  matches: false,
+  onchange: noop,
+  addListener: noop,
+  addEventListener: noop,
+  removeEventListener: noop,
+  removeListener: noop,
+  dispatchEvent: () => false,
+};
+
+/** @since 6.0.0 */
+export type MatchMediaMatcher = (query: string) => boolean;
+
+/**
+ * @since 6.0.0
+ * @returns `true` for phone media queries
+ */
+export const matchPhone: MatchMediaMatcher = (query) =>
+  query.includes(DEFAULT_PHONE_MAX_WIDTH);
+
+/**
+ * @since 6.0.0
+ * @returns `true` for tablet media queries
+ */
+export const matchTablet: MatchMediaMatcher = (query) =>
+  query.includes(DEFAULT_TABLET_MIN_WIDTH);
+
+/**
+ * @since 6.0.0
+ * @returns `true` for desktop media queries
+ */
+export const matchDesktop: MatchMediaMatcher = (query) =>
+  query.includes(DEFAULT_DESKTOP_MIN_WIDTH);
+
+/**
+ * @since 6.0.0
+ * @returns `true` for large desktop media queries
+ */
+export const matchLargeDesktop: MatchMediaMatcher = (query) =>
+  query.includes(DEFAULT_DESKTOP_LARGE_MIN_WIDTH);
+
+/**
+ * @since 6.0.0
+ * @returns `true` for both desktop and large desktop media queries
+ */
+export const matchAnyDesktop: MatchMediaMatcher = (query) =>
+  matchDesktop(query) || matchLargeDesktop(query);

package/src/test-utils/polyfills/IntersectionObserver.ts

@@ -1,4 +1,4 @@
-import { IntersectionObserverMock } from "../IntersectionObserver.js";
+import { IntersectionObserverMock } from "../mocks/IntersectionObserver.js";
 
 if (
   typeof window !== "undefined" &&

package/src/test-utils/polyfills/ResizeObserver.ts

@@ -1,4 +1,4 @@
-import { ResizeObserverMock } from "../ResizeObserver.js";
+import { ResizeObserverMock } from "../mocks/ResizeObserver.js";
 
 if (typeof window !== "undefined" && typeof ResizeObserver === "undefined") {
   window.ResizeObserver = ResizeObserverMock;

package/src/test-utils/polyfills/matchMedia.ts

@@ -1,4 +1,4 @@
-import { BASE_MEDIA_QUERY_LIST, matchDesktop } from "../matchMedia.js";
+import { BASE_MEDIA_QUERY_LIST, matchDesktop } from "../mocks/match-media.js";
 
 if (typeof window !== "undefined" && typeof window.matchMedia !== "function") {
   window.matchMedia = (query) => ({

package/src/test-utils/queries/index.ts

@@ -0,0 +1,2 @@
+export * from "./select.js";
+export * from "./slider.js";

package/src/test-utils/queries/select.ts

@@ -0,0 +1,116 @@
+import { screen, within } from "@testing-library/dom";
+
+import { type GetPartsByRoleOptions } from "./types.js";
+
+/**
+ * @since 6.0.0
+ */
+export interface SelectTestElements {
+  /**
+   * The element that should be interacted with for showing and hiding the
+   * listbox of available options in the `Select`.
+   */
+  select: HTMLDivElement;
+
+  /**
+   * The input element storing the current value for the `Select`. This should
+   * be used to verify a specific option has been selected and will be the
+   * `Option`'s `value` prop.
+   *
+   * i.e. Selecting `<Option value="a">Option 1</Option>` -> `selectInput`
+   * would have value `"a"`.
+   */
+  selectInput: HTMLInputElement;
+
+  /**
+   * The current selected option that is shown in the `Select` underneath the
+   * floating label. This should be used if the selected option label needs to
+   * be verified instead of the value.
+   *
+   * i.e. Selecting `<Option value="a">Option 1</Option>` -> `selectedOption`
+   * would have text content `"Option 1"`.
+   */
+  selectedOption: HTMLDivElement;
+}
+
+/**
+ * @example Simple Example
+ * ```tsx
+ * import {
+ *   getSelectTestElements,
+ *   screen,
+ *   rmdRender,
+ *   userEvent,
+ * } from "@react-md/core/test-utils";
+ *
+ * it("should be able to verify the display value", async () => {
+ *   const user = userEvent.setup();
+ *   rmdRender(<SimpleSelect />);
+ *
+ *   const { select, selectInput, selectedOption } = getSelectTestElements({
+ *     name: "Label",
+ *   });
+ *   // this isn't required, but added to show what element this is
+ *   expect(selectedOption).toHaveClass("rmd-selected-option");
+ *
+ *   // there is currently no selected value
+ *   expect(selectedOption).toHaveTextContent("");
+ *
+ *   await user.click(select);
+ *   await user.click(screen.getByRole("option", { name: "Option 1" }));
+ *   expect(selectInput).toHaveValue("a");
+ *   expect(selectedOption).toHaveTextContent("Option 1");
+ * });
+ * ```
+ *
+ * @since 6.0.0
+ */
+export function getSelectTestElements(
+  options: GetPartsByRoleOptions
+): SelectTestElements {
+  const { container = screen, ...byRoleOptions } = options;
+  const select = container.getByRole<HTMLDivElement>("combobox", byRoleOptions);
+  const selectInput = within(select).getByRole<HTMLInputElement>("textbox", {
+    hidden: true,
+  });
+  const selectedOption = select.firstElementChild;
+  if (!(selectedOption instanceof HTMLDivElement)) {
+    throw new Error("Unable to find the `Select` selected option element");
+  }
+
+  return {
+    select,
+    selectInput,
+    selectedOption,
+  };
+}
+
+/**
+ * @see {@link getSelectTestElements}
+ * @since 6.0.0
+ */
+export async function findSelectTestElements(
+  options: GetPartsByRoleOptions
+): Promise<SelectTestElements> {
+  const { container = screen, ...byRoleOptions } = options;
+  const select = await container.findByRole<HTMLDivElement>(
+    "combobox",
+    byRoleOptions
+  );
+  const selectInput = await within(select).findByRole<HTMLInputElement>(
+    "textbox",
+    {
+      hidden: true,
+    }
+  );
+  const selectedOption = select.firstElementChild;
+  if (!(selectedOption instanceof HTMLDivElement)) {
+    throw new Error("Unable to find the `Select` selected option element");
+  }
+
+  return {
+    select,
+    selectInput,
+    selectedOption,
+  };
+}

package/src/test-utils/queries/slider.ts

@@ -0,0 +1,247 @@
+import {
+  type BoundFunctions,
+  type ByRoleOptions,
+  type queries,
+  screen,
+} from "@testing-library/dom";
+
+import { type GetPartsByRoleOptions } from "./types.js";
+
+type Elements = Omit<SliderTestElements, "slider">;
+
+function getElements(slider: HTMLSpanElement): Elements {
+  const sliderInput = slider.nextElementSibling;
+  const sliderTrack = slider.parentElement;
+  const sliderContainer = sliderTrack?.parentElement;
+  if (!(sliderInput instanceof HTMLInputElement)) {
+    throw new Error("Unable to find the `Slider` input element");
+  }
+  if (
+    !(sliderTrack instanceof HTMLSpanElement) ||
+    !sliderTrack.classList.contains("rmd-slider-track")
+  ) {
+    throw new Error("Unable to find the `Slider` track element");
+  }
+  if (
+    !(sliderContainer instanceof HTMLDivElement) ||
+    !sliderContainer.classList.contains("rmd-slider-container")
+  ) {
+    throw new Error("Unable to find the `Slider` container element");
+  }
+
+  return { sliderInput, sliderTrack, sliderContainer };
+}
+
+/**
+ * @since 6.0.0
+ */
+export interface SliderTestElements {
+  /**
+   * The element that is visible to screen readers and can be updated using
+   * drag, touch, or keyboard events. Since this is usually annoying for tests,
+   * the `sliderInput` should normally be used instead.
+   */
+  slider: HTMLSpanElement;
+
+  /**
+   * The element that is hidden to screen readers but stores the current value
+   * and can be updated using
+   * `fireEvent.change(sliderInput, { target: { value: "100" }})`.
+   */
+  sliderInput: HTMLInputElement;
+
+  /**
+   * This is only useful when needing to verify that clicking somewhere on the
+   * track updates the value. Most test cases can be solved through the
+   * {@link slider} or {@link sliderInput} instead.
+   */
+  sliderTrack: HTMLSpanElement;
+
+  /**
+   * Returns the slider container element if it is needed for testing. It's
+   * useful for simple snapshot tests.
+   */
+  sliderContainer: HTMLDivElement;
+}
+
+/**
+ * @example Simple Example
+ * ```tsx
+ * function Test(): ReactElement {
+ *   const slider = useSlider({ defaultValue: 30 });
+ *   return <Slider {...slider} aria-label="Example" />;
+ * }
+ *
+ * rmdRender(<Test />);
+ *
+ * const { slider, sliderInput } = getSliderTestElements({ name: "Example" });
+ *
+ * expect(slider).toHaveValue(30);
+ * expect(sliderInput).toHaveValue("30");
+ *
+ * fireEvent.change(sliderInput, { target: { value: "55" }});
+ * expect(slider).toHaveValue(55);
+ * expect(sliderInput).toHaveValue("55");
+ * ```
+ *
+ * @since 6.0.0
+ */
+export function getSliderTestElements(
+  options: GetPartsByRoleOptions
+): SliderTestElements {
+  const { container = screen, ...byRoleOptions } = options;
+  const slider = container.getByRole<HTMLSpanElement>("slider", byRoleOptions);
+
+  return {
+    slider,
+    ...getElements(slider),
+  };
+}
+
+/**
+ * @see {@link getSliderTestElements}
+ * @since 6.0.0
+ */
+export async function findSliderTestElements(
+  options: GetPartsByRoleOptions
+): Promise<SliderTestElements> {
+  const { container = screen, ...byRoleOptions } = options;
+  const slider = await container.findByRole<HTMLSpanElement>(
+    "slider",
+    byRoleOptions
+  );
+
+  return {
+    slider,
+    ...getElements(slider),
+  };
+}
+
+/**
+ * @since 6.0.0
+ */
+export interface GetRangetSliderTestElementsOptions {
+  /** @defaultValue `screen` */
+  container?: BoundFunctions<typeof queries>;
+
+  /** @defaultValue `{ name: "Min" }` */
+  min?: ByRoleOptions;
+
+  /** @defaultValue `{ name: "Max" }` */
+  max?: ByRoleOptions;
+}
+
+/**
+ * @since 6.0.0
+ */
+export interface RangeSliderTestElements {
+  /** @see {@link SliderTestElements.slider} */
+  minSlider: HTMLSpanElement;
+  /** @see {@link SliderTestElements.sliderInput} */
+  minSliderInput: HTMLInputElement;
+  /** @see {@link SliderTestElements.slider} */
+  maxSlider: HTMLSpanElement;
+  /** @see {@link SliderTestElements.sliderInput} */
+  maxSliderInput: HTMLInputElement;
+  /** @see {@link SliderTestElements.sliderTrack} */
+  sliderTrack: HTMLSpanElement;
+  /** @see {@link SliderTestElements.sliderContainer} */
+  sliderContainer: HTMLDivElement;
+}
+
+/**
+ * @example Simple Example
+ * ```tsx
+ * function Test(): ReactElement {
+ *   const slider = useRangeSlider({ defaultValue: [30, 60] });
+ *   return <Slider {...slider} aria-label="Example" />;
+ * }
+ *
+ * rmdRender(<Test />);
+ *
+ * const { slider, sliderInput } = getSliderTestElements();
+ *
+ * const { minSlider, minSliderInput, maxSlider, maxSliderInput } =
+ *   getRangeSliderTestElements();
+ * expect(minSlider).toHaveValue(30);
+ * expect(minSliderInput).toHaveValue("30");
+ * expect(maxSlider).toHaveAttribute(60);
+ * expect(maxSliderInput).toHaveValue("60");
+ *
+ * fireEvent.change(minSliderInput, { target: { value: "55" }});
+ * expect(minSlider).toHaveValue(55);
+ * expect(minSliderInput).toHaveValue("55");
+ * expect(maxSlider).toHaveAttribute(60);
+ * expect(maxSliderInput).toHaveValue("60");
+ *
+ * fireEvent.change(maxSliderInput, { target: { value: "88" }});
+ * expect(minSlider).toHaveValue(55);
+ * expect(minSliderInput).toHaveValue("55");
+ * expect(maxSlider).toHaveAttribute(88);
+ * expect(maxSliderInput).toHaveValue("88");
+ * ```
+ *
+ * @since 6.0.0
+ */
+export function getRangeSliderTestElements(
+  options: GetRangetSliderTestElementsOptions = {}
+): RangeSliderTestElements {
+  const { container = screen, min, max } = options;
+  const minSlider = container.getByRole<HTMLSpanElement>(
+    "slider",
+    min ?? { name: "Min" }
+  );
+  const maxSlider = container.getByRole<HTMLSpanElement>(
+    "slider",
+    max ?? { name: "Max" }
+  );
+
+  const {
+    sliderInput: minSliderInput,
+    sliderTrack,
+    sliderContainer,
+  } = getElements(minSlider);
+  const { sliderInput: maxSliderInput } = getElements(maxSlider);
+
+  return {
+    minSlider,
+    minSliderInput,
+    maxSlider,
+    maxSliderInput,
+    sliderTrack,
+    sliderContainer,
+  };
+}
+
+/**
+ * @see {@link getRangeSliderTestElements}
+ * @since 6.0.0
+ */
+export async function findRangeSliderTestElements(
+  options: GetRangetSliderTestElementsOptions = {}
+): Promise<RangeSliderTestElements> {
+  const { container = screen, min, max } = options;
+  const minSlider = await container.findByRole<HTMLSpanElement>(
+    "slider",
+    min ?? { name: "Min" }
+  );
+  const maxSlider = await container.findByRole<HTMLSpanElement>(
+    "slider",
+    max ?? { name: "Max" }
+  );
+  const {
+    sliderInput: minSliderInput,
+    sliderTrack,
+    sliderContainer,
+  } = getElements(minSlider);
+  const { sliderInput: maxSliderInput } = getElements(maxSlider);
+
+  return {
+    minSlider,
+    minSliderInput,
+    maxSlider,
+    maxSliderInput,
+    sliderTrack,
+    sliderContainer,
+  };
+}

package/src/test-utils/queries/types.ts

@@ -0,0 +1,13 @@
+import {
+  type BoundFunctions,
+  type ByRoleOptions,
+  type queries,
+} from "@testing-library/dom";
+
+/**
+ * @since 6.0.0
+ */
+export interface GetPartsByRoleOptions extends ByRoleOptions {
+  /** @defaultValue `screen` */
+  container?: BoundFunctions<typeof queries>;
+}

package/src/test-utils/render.tsx

@@ -1,11 +1,12 @@
 import {
-  render,
   type Queries,
   type RenderOptions,
   type RenderResult,
   type queries,
+  render,
 } from "@testing-library/react";
 import { Fragment, type ReactElement } from "react";
+
 import { CoreProviders, type CoreProvidersProps } from "../CoreProviders.js";
 
 /**

package/src/test-utils/utils/createFileList.ts

@@ -0,0 +1,27 @@
+/**
+ * @see https://github.com/testing-library/user-event/blob/d42954be66484bcf78486a298cc37f8a7c9e4bea/src/utils/dataTransfer/FileList.ts
+ */
+export function createFileList(
+  window: Window & typeof globalThis,
+  fileOrFiles: File | readonly File[]
+): FileList & Iterable<File> {
+  const files = Array.isArray(fileOrFiles) ? fileOrFiles : [fileOrFiles];
+  const fileList: FileList & Iterable<File> = {
+    ...files,
+    length: files.length,
+    item: (index) => fileList[index],
+    // needs to be `any` to match the FileList definition
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    [Symbol.iterator]: function* nextFile(): Generator<File, any, any> {
+      for (let i = 0; i < fileList.length; i++) {
+        yield fileList[i];
+      }
+    },
+  };
+  fileList.constructor = window.FileList;
+  if (window.FileList) {
+    Object.setPrototypeOf(fileList, window.FileList.prototype);
+  }
+  Object.freeze(fileList);
+  return fileList;
+}

package/src/test-utils/utils/createResizeObserverEntry.ts

@@ -0,0 +1,47 @@
+/**
+ * @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: [],
+  };
+};

package/src/test-utils/vitest/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/vitest/match-media.ts

@@ -0,0 +1,41 @@
+import { type MockInstance, vi } from "vitest";
+
+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/vitest";
+ *
+ * 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/vitest";
+ *
+ * const matchMedia = spyOnMatchMedia(matchPhone);
+ * render(<Test />);
+ *
+ * // expect phone results
+ * ```
+ *
+ * @since 6.0.0
+ */
+export function spyOnMatchMedia(
+  defaultMatch: MatchMediaMatcher = matchDesktop
+): MockInstance<typeof window.matchMedia> & MatchMediaChangeViewport {
+  return createMatchMediaSpy(vi.spyOn(window, "matchMedia"), defaultMatch);
+}

package/src/test-utils/vitest/resize-observer.ts

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

package/src/test-utils/vitest/setup.ts

@@ -0,0 +1,15 @@
+import "@testing-library/jest-dom/vitest";
+import { beforeEach } from "vitest";
+
+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
+  // `getBoundingClientRect()` to create correct CSS. You'll either see warnings
+  // in the console around invalid css values or `NaN`.
+  INTERACTION_CONFIG.mode = "none";
+
+  // disable transitions in tests since it just makes it more difficult
+  TRANSITION_CONFIG.disabled = true;
+});

package/src/test-utils/vitest/timers.ts

@@ -0,0 +1,48 @@
+import { type MockInstance, vi } from "vitest";
+
+/**
+ * @since 6.0.0
+ */
+export type RafSpy = MockInstance<typeof requestAnimationFrame>;
+
+/**
+ * @example
+ * ```ts
+ * import { testImmediateRaf } from "@react-md/core/test-utils/vitest";
+ *
+ * describe("some test suite", () => {
+ *   it("should test something with requestAnimationFrame", () => {
+ *     const raf = testImmediateRaf();
+ *
+ *     // do some testing with requestAnimationFrame
+ *
+ *     // reset to original at the end of the test
+ *     raf.mockRestore()
+ *   });
+ * });
+ * ```
+ *
+ * @example Automatic Cleanup
+ * ```ts
+ * import { testImmediateRaf } from "@react-md/core/test-utils/vitest";
+ *
+ * afterEach(() => {
+ *   jest.restoreAllMocks();
+ * });
+ *
+ * describe("some test suite", () => {
+ *   it("should test something with requestAnimationFrame", () => {
+ *     const raf = testImmediateRaf();
+ *
+ *     // do some testing with requestAnimationFrame
+ *   });
+ * });
+ * ```
+ *
+ * @since 6.0.0
+ */
+export const testImmediateRaf = (): RafSpy =>
+  vi.spyOn(window, "requestAnimationFrame").mockImplementation((cb) => {
+    cb(0);
+    return 0;
+  });