@react-md/core 1.0.0-next.8 → 1.0.0-next.9

package/src/searching/caseInsensitive.ts

@@ -0,0 +1,200 @@
+import { type TextExtractor } from "../types.js";
+import { type BaseSearchOptions } from "./types.js";
+import { defaultExtractor, search } from "./utils.js";
+
+/**
+ * @remarks \@since 6.0.0
+ */
+export interface CaseInsensitiveStartsWithOptions {
+  /**
+   * Set this to `true` if the item in the list must start with the query
+   * instead of only including it.
+   *
+   * @example
+   * Search Example
+   * ```ts
+   * const fruits = ["Banana", "Grape", "Apple", "Orange"];
+   *
+   * caseInsensitiveSearch({
+   *   list: fruits,
+   *   query: "ap",
+   *   type: "search",
+   * });
+   * // "Grape"
+   *
+   * caseInsensitiveSearch({
+   *   list: fruits,
+   *   query: "ap",
+   *   type: "search",
+   *   startsWith: true,
+   * });
+   * // "Apple"
+   * ```
+   *
+   * @example
+   * Filter Example
+   * ```ts
+   * const fruits = ["Apple", "Banana", "Grape", "Orange"];
+   *
+   * caseInsensitiveSearch({
+   *   list: fruits,
+   *   query: "ap",
+   * });
+   * // ["Apple", "Grape"]
+   *
+   * caseInsensitiveSearch({
+   *   list: fruits,
+   *   query: "ap",
+   *   startsWith: true,
+   * });
+   * // ["Apple"]
+   * ```
+   *
+   * @defaultValue `false`
+   */
+  startsWith?: boolean;
+}
+
+/**
+ * @remarks \@since 6.0.0
+ */
+export interface IsCaseInsensitiveMatchOptions
+  extends CaseInsensitiveStartsWithOptions {
+  /**
+   * The current search query.
+   */
+  query: string;
+
+  /**
+   * The current value to compare against.
+   */
+  value: string;
+}
+
+/**
+ * @remarks \@since 6.0.0
+ */
+export function isCaseInsensitiveMatch(
+  options: IsCaseInsensitiveMatchOptions
+): boolean {
+  const { query, value, startsWith } = options;
+  const matchIndex = value.indexOf(query);
+  if (startsWith) {
+    return matchIndex === 0;
+  }
+
+  return matchIndex !== -1;
+}
+
+/**
+ * @remarks \@since 6.0.0
+ */
+export interface CaseInsensitiveOptions<T>
+  extends BaseSearchOptions<T>,
+    CaseInsensitiveStartsWithOptions {}
+
+/**
+ * @example
+ * String list
+ * ```ts
+ * const fruits = ["Apple", "Banana", "Grape", "Orange"];
+ *
+ * caseInsensitiveSearch({
+ *   list: fruits,
+ *   query: "ap",
+ * });
+ * // ["Apple", "Grape"]
+ *
+ * caseInsensitiveSearch({
+ *   list: fruits,
+ *   query: "ap",
+ *   startsWith: true,
+ * });
+ * // ["Apple"]
+ *
+ * caseInsensitiveSearch({
+ *   list: fruits,
+ *   query: "  a p",
+ * });
+ * // []
+ *
+ * caseInsensitiveSearch({
+ *   list: fruits,
+ *   query: "  a p",
+ *   whitespace: "ignore",
+ * });
+ * // ["Apple", "Grape"]
+ *
+ * caseInsensitiveSearch({
+ *   list: fruits,
+ *   query: "  ap  ",
+ *   whitespace: "trim",
+ * });
+ * // ["Apple", "Grape"]
+ * ```
+ *
+ * @example
+ * Objects
+ * ```ts
+ * const fruits = [
+ *   { name: "Apple", value: 0 },
+ *   { name: "Banana", value: 1 },
+ *   { name: "Grape", value: 2 },
+ *   { name: "Orange", value: 3 },
+ * ];
+ *
+ * caseInsensitiveSearch({
+ *   list: fruits,
+ *   query: "ap",
+ *   extractor: (item) => item.name,
+ * });
+ * // [{ name: "Apple", value: 0 }, { name: "Grape", value: 2 }]
+ * ```
+ *
+ * @remarks \@since 6.0.0
+ */
+export function caseInsensitiveSearch<T extends string>(
+  options: Omit<CaseInsensitiveOptions<T>, "extractor"> & { type?: "filter" }
+): readonly T[];
+export function caseInsensitiveSearch<T extends string>(
+  options: Omit<CaseInsensitiveOptions<T>, "extractor"> & { type: "search" }
+): T | undefined;
+export function caseInsensitiveSearch<T>(
+  options: CaseInsensitiveOptions<T> & {
+    extractor: TextExtractor<T>;
+    type?: "filter";
+  }
+): readonly T[];
+export function caseInsensitiveSearch<T>(
+  options: CaseInsensitiveOptions<T> & {
+    extractor: TextExtractor<T>;
+    type: "search";
+  }
+): T | undefined;
+export function caseInsensitiveSearch<T>(
+  options: CaseInsensitiveOptions<T>
+): readonly T[] | T | undefined {
+  const {
+    list,
+    type = "filter",
+    query,
+    extractor = defaultExtractor("caseInsensitiveSearch"),
+    startsWith,
+    whitespace,
+  } = options;
+
+  return search({
+    type,
+    list,
+    query,
+    extractor,
+    whitespace,
+    filter(q, value) {
+      return isCaseInsensitiveMatch({
+        query: q,
+        value,
+        startsWith,
+      });
+    },
+  });
+}

package/src/searching/fuzzy.ts

@@ -0,0 +1,175 @@
+import { type TextExtractor } from "../types.js";
+import { type BaseSearchOptions } from "./types.js";
+import { defaultExtractor, search } from "./utils.js";
+
+/**
+ * @example
+ * ```tsx
+ * import { createFuzzyRegExp, toSearchQuery } from "@react-md/core":
+ * import { useDeferredValue, useMemo, useState, type ReactElement } from "react";
+ *
+ * function Example(): ReactElement {
+ *   const [value, setValue] = useState("");
+ *   const deferredValue = useDeferredValue(value)
+ *
+ *   const match = useMemo(() => {
+ *     const query = toSearchQuery(deferredValue);
+ *     if (!query) {
+ *       return;
+ *     }
+ *
+ *     const fuzzyRegExp = createFuzzyRegExp(query);
+ *     return options.find(option => fuzzyRegExp.test(option.label)):
+ *   }, [options])
+ *
+ *   if (match) {
+ *     // do something
+ *   }
+ * }
+ *
+ * ```
+ *
+ * @remarks \@since 6.0.0
+ * @see {@link fuzzySearch}
+ */
+export function createFuzzyRegExp(query: string): RegExp {
+  return new RegExp(
+    query
+      .split("")
+      .join("\\w*")
+      .replace(/(\(|\||\)|\\(?!w\*)|\[|\|-|\.|\^|\+|\$|\?|^(?!w)\*)/g, "\\$1")
+      // Couldn't get the matching of two '*' working, so replace them here..
+      .replace(/\*\*/g, "*\\*"),
+    "i"
+  );
+}
+
+/**
+ * @remarks \@since 6.0.0
+ */
+export type FuzzySearchOptions<T> = BaseSearchOptions<T>;
+
+/**
+ * Filters a list by making sure that all the letters appear in order ignoring
+ * case, punctuation, whitespace, and special characters. This is kind of the
+ * same filtering that appears in text editors.
+ *
+ * @example
+ * Simple Example
+ * ```ts
+ * const list = [
+ *   "at",
+ *   "charAt",
+ *   "charCodeAt",
+ *   "codePointAt",
+ *   "concat",
+ *   "constructor",
+ *   "endsWith",
+ *   "includes",
+ *   "indexOf",
+ *   "lastIndexOf",
+ *   "length",
+ *   "localeCompare",
+ *   "match",
+ *   "matchAll",
+ *   "normalize",
+ *   "padEnd",
+ *   "padStart",
+ *   "repeat",
+ *   "replace",
+ *   "replaceAll",
+ *   "search",
+ *   "slice",
+ *   "split",
+ *   "startsWith",
+ *   "substring",
+ *   "toLocaleLowerCase",
+ *   "toLocaleUpperCase",
+ *   "toLowerCase",
+ *   "toString",
+ *   "toUpperCase",
+ *   "trim",
+ *   "trimEnd",
+ *   "trimStart",
+ *   "valueOf",
+ * ];
+ *
+ * fuzzySearch({
+ *   list,
+ *   query: "la",
+ * });
+ * // [
+ * //   "lastIndexOf",
+ * //    ^^
+ * //   "localeCompare",
+ * //    ^  ^
+ * //   "replace",
+ * //       ^^
+ * //   "replaceAll",
+ * //       ^^
+ * //   "toLocaleLowerCase",
+ * //      ^  ^
+ * //   "toLocaleUpperCase",
+ * //      ^  ^
+ * //   "toLowerCase",
+ * //      ^     ^
+ * // ]
+ *
+ * fuzzySearch({
+ *   list,
+ *   query: "ad",
+ *   type: "search",
+ * });
+ * // "charCodeAt"
+ *  //    ^   ^
+ * ```
+ *
+ * @remarks \@since 6.0.0
+ */
+export function fuzzySearch<T extends string>(
+  options: Omit<FuzzySearchOptions<T>, "extractor"> & { type?: "filter" }
+): readonly T[];
+export function fuzzySearch<T extends string>(
+  options: Omit<FuzzySearchOptions<T>, "extractor"> & { type?: "search" }
+): T | undefined;
+export function fuzzySearch<T>(
+  option: FuzzySearchOptions<T> & {
+    extractor: TextExtractor<T>;
+    type?: "filter";
+  }
+): readonly T[];
+export function fuzzySearch<T>(
+  option: FuzzySearchOptions<T> & {
+    extractor: TextExtractor<T>;
+    type?: "search";
+  }
+): T | undefined;
+export function fuzzySearch<T>(
+  options: FuzzySearchOptions<T>
+): readonly T[] | T | undefined {
+  const {
+    list,
+    type = "filter",
+    query,
+    extractor = defaultExtractor("fuzzySearch"),
+    whitespace,
+  } = options;
+
+  // lazy initialize the RegExp since the base `filter` function will modify the
+  // query and never call the filter function if:
+  // - there is no query
+  // - the list is empty
+  let regexp: RegExp;
+  return search({
+    type,
+    list,
+    query,
+    extractor,
+    whitespace,
+    filter(query, value) {
+      return (
+        value.length > 0 && (regexp ??= createFuzzyRegExp(query)).test(value)
+      );
+    },
+  });
+}

package/src/searching/toSearchQuery.ts

@@ -0,0 +1,18 @@
+import { type WhitespaceFilter } from "./types.js";
+
+/**
+ * @remarks \@since 6.0.0
+ */
+export function toSearchQuery(
+  s: string,
+  whitespace: WhitespaceFilter = "keep"
+): string {
+  let q = s.toLowerCase();
+  if (whitespace === "ignore") {
+    q = q.replace(/\s/g, "");
+  } else if (whitespace === "trim") {
+    q = q.trim();
+  }
+
+  return q;
+}

package/src/searching/types.ts

@@ -0,0 +1,34 @@
+import { type TextExtractor } from "../types.js";
+
+/**
+ * @remarks \@since 6.0.0
+ */
+export type WhitespaceFilter = "ignore" | "trim" | "keep";
+
+/**
+ * @remarks \@since 6.0.0
+ */
+export interface BaseSearchOptions<T> {
+  list: readonly T[];
+
+  /**
+   * @defaultValue `"filter"`
+   */
+  type?: "search" | "filter";
+
+  /**
+   * The current query string. i.e. `"SeArch"`
+   */
+  query: string;
+
+  /**
+   * This is required if the list includes anything other than strings.
+   * @see {@link TextExtractor}
+   */
+  extractor?: TextExtractor<T>;
+
+  /**
+   * @defaultValue `"keep"`
+   */
+  whitespace?: WhitespaceFilter;
+}

package/src/searching/utils.ts

@@ -0,0 +1,54 @@
+import { type TextExtractor } from "../types.js";
+import { toSearchQuery } from "./toSearchQuery.js";
+import { type BaseSearchOptions } from "./types.js";
+
+/**
+ * @remarks \@since 6.0.0
+ * @internal
+ */
+export const defaultExtractor =
+  <T>(name: string) =>
+  (item: T): string => {
+    if (typeof item === "string") {
+      return item;
+    }
+
+    throw new Error(
+      `A \`TextExtractor\` must be provided to \`${name}\` for lists that do not contain strings`
+    );
+  };
+
+/**
+ * @internal
+ * @remarks \@since 6.0.0
+ */
+export interface SearchOptions<T> extends BaseSearchOptions<T> {
+  type: "search" | "filter";
+  filter(query: string, value: string): boolean;
+  extractor: TextExtractor<T>;
+}
+
+/**
+ * @internal
+ * @remarks \@since 6.0.0
+ */
+export function search<T>(
+  options: SearchOptions<T>
+): readonly T[] | T | undefined {
+  const { list, type, query, filter, extractor, whitespace = "keep" } = options;
+  const fallback = type === "search" ? undefined : list;
+  if (!list.length) {
+    return fallback;
+  }
+
+  const q = toSearchQuery(query, whitespace);
+  if (!q) {
+    return fallback;
+  }
+
+  const fn = type === "search" ? "find" : "filter";
+
+  return list[fn]((item) =>
+    filter(q, toSearchQuery(extractor(item), whitespace))
+  );
+}

package/src/test-utils/data-testid.ts

@@ -1,5 +1,9 @@
+/// <reference types="react" />
+
 declare module "react" {
-  interface HTMLAttributes<T> extends AriaAttributes, DOMAttributes<T> {
+  interface HTMLAttributes<T>
+    extends React.AriaAttributes,
+      React.DOMAttributes<T> {
     "data-testid"?: string | number;
   }
 }

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

@@ -0,0 +1,7 @@
+import { TextDecoder } from "node:util";
+
+if (typeof global.TextDecoder === "undefined") {
+  // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+  // @ts-expect-error browser TextDecoder does not support `null` while `node:util` does
+  global.TextDecoder = TextDecoder;
+}

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

@@ -0,0 +1,5 @@
+import { TextEncoder } from "node:util";
+
+if (typeof global.TextEncoder === "undefined") {
+  global.TextEncoder = TextEncoder;
+}

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

@@ -1,5 +1,7 @@
 import "./IntersectionObserver.js";
 import "./ResizeObserver.js";
+import "./TextDecoder.js";
+import "./TextEncoder.js";
 import "./matchMedia.js";
 import "./offsetParent.js";
 import "./scrollIntoView.js";

package/src/transition/__tests__/utils.ts

@@ -175,6 +175,31 @@ describe("getElementSizing", () => {
     expect(getComputedStyle).toHaveBeenCalledWith(clone);
     expect(removeChild).toHaveBeenCalledWith(clone);
   });
+
+  it("should add the paddingTop and paddingBottom to the maxHeight when `box-sizing: content-box` has been set", () => {
+    const scrollHeight = 1000;
+    const paddingTop = 20;
+    const paddingBottom = 16;
+    const container = document.createElement("div");
+    const element = document.createElement("div");
+    const clone = document.createElement("div");
+    container.appendChild(element);
+
+    jest.spyOn(clone, "scrollHeight", "get").mockReturnValue(scrollHeight);
+    jest.spyOn(element, "cloneNode").mockReturnValue(clone);
+    jest.spyOn(window, "getComputedStyle").mockReturnValue({
+      ...document.body.style,
+      paddingTop: "20px",
+      paddingBottom: "16px",
+      boxSizing: "content-box",
+    });
+
+    expect(getElementSizing(element)).toEqual({
+      maxHeight: scrollHeight + paddingTop + paddingBottom,
+      paddingTop,
+      paddingBottom,
+    });
+  });
 });
 
 describe("getTransitionClassNames", () => {

package/src/transition/useCollapseTransition.ts

@@ -19,21 +19,6 @@ const noop = (): void => {
   // do nothing
 };
 
-/**
- * @remarks \@since 2.0.0
- */
-export const DEFAULT_COLLAPSE_MIN_HEIGHT = 0;
-
-/**
- * @remarks \@since 2.0.0
- */
-export const DEFAULT_COLLAPSE_MIN_PADDING_TOP = 0;
-
-/**
- * @remarks \@since 2.0.0
- */
-export const DEFAULT_COLLAPSE_MIN_PADDING_BOTTOM = 0;
-
 /**
  * @remarks \@since 2.0.0
  */
@@ -58,8 +43,7 @@ export interface CollapseConfigurationStyle {
    * are all set to `0` (default), the child will be removed from the DOM while
    * collapsed.
    *
-   * @see {@link DEFAULT_COLLAPSE_MIN_HEIGHT}
-   * @defaultValue `DEFAULT_COLLAPSE_MIN_HEIGHT`
+   * @defaultValue `0`
    */
   minHeight?: number | string;
 
@@ -72,8 +56,7 @@ export interface CollapseConfigurationStyle {
    * are all set to `0` (default), the child will be removed from the DOM while
    * collapsed.
    *
-   * @see {@link DEFAULT_COLLAPSE_MIN_PADDING_TOP}
-   * @defaultValue `DEFAULT_COLLAPSE_MIN_PADDING_TOP`
+   * @defaultValue `0`
    */
   minPaddingTop?: number | string;
 
@@ -86,8 +69,7 @@ export interface CollapseConfigurationStyle {
    * are all set to `0` (default), the child will be removed from the DOM while
    * collapsed.
    *
-   * @see {@link DEFAULT_COLLAPSE_MIN_PADDING_BOTTOM}
-   * @defaultValue `DEFAULT_COLLAPSE_MIN_PADDING_BOTTOM`
+   * @defaultValue `0`
    */
   minPaddingBottom?: number | string;
 }
@@ -307,9 +289,9 @@ export function useCollapseTransition<E extends HTMLElement>(
     className,
     transitionIn,
     timeout = DEFAULT_COLLAPSE_TIMEOUT,
-    minHeight = DEFAULT_COLLAPSE_MIN_HEIGHT,
-    minPaddingTop = DEFAULT_COLLAPSE_MIN_PADDING_TOP,
-    minPaddingBottom = DEFAULT_COLLAPSE_MIN_PADDING_BOTTOM,
+    minHeight = 0,
+    minPaddingTop = 0,
+    minPaddingBottom = 0,
     temporary = minHeight === 0 &&
       minPaddingTop === 0 &&
       minPaddingBottom === 0,

package/src/transition/utils.ts

@@ -57,9 +57,9 @@ export interface CollapseSizing {
  * @internal
  */
 export function getElementSizing(element: HTMLElement | null): CollapseSizing {
-  let maxHeight;
-  let paddingTop;
-  let paddingBottom;
+  let maxHeight: number | undefined;
+  let paddingTop: number | undefined;
+  let paddingBottom: number | undefined;
   if (element) {
     // clone the element so that the total height and padding can be calculated
     // without being affected by the collapse transition inline styles
@@ -74,14 +74,19 @@ export function getElementSizing(element: HTMLElement | null): CollapseSizing {
     container.appendChild(cloned);
     maxHeight = cloned.scrollHeight;
     const style = window.getComputedStyle(cloned);
+    const isContentBox = style.boxSizing === "content-box";
     if (style.paddingTop) {
       paddingTop = parseFloat(style.paddingTop);
-      maxHeight + paddingTop;
+      if (isContentBox) {
+        maxHeight += paddingTop;
+      }
     }
 
     if (style.paddingBottom) {
       paddingBottom = parseFloat(style.paddingBottom);
-      maxHeight + paddingBottom;
+      if (isContentBox) {
+        maxHeight += paddingBottom;
+      }
     }
     container.removeChild(cloned);
   }

package/src/useEnsuredState.ts

@@ -9,7 +9,7 @@ import type { UseStateInitializer, UseStateSetter } from "./types.js";
  */
 export interface EnsuredStateOptions<
   V,
-  Setter extends Dispatch<V> | UseStateSetter<V>,
+  Setter extends Dispatch<V> | UseStateSetter<V> = UseStateSetter<V>,
 > {
   value?: V;
   setValue?: Setter;

package/src/utils/alphaNumericSort.ts

@@ -1,18 +1,5 @@
-import type { TextExtractor } from "../types.js";
-
-const identity = <T>(item: T): string => {
-  if (typeof item === "string") {
-    return item;
-  }
-
-  if (process.env.NODE_ENV !== "production") {
-    throw new Error(
-      "A `TextExtractor` must be provided to `alphaNumericSort` for lists that do not contain strings"
-    );
-  }
-
-  return "";
-};
+import { defaultExtractor } from "../searching/utils.js";
+import { type TextExtractor } from "../types.js";
 
 /**
  * The default `Intl.Collator` that should be used for sorting large lists.
@@ -131,7 +118,7 @@ export function alphaNumericSort<T>(
 ): readonly T[] {
   const {
     compare = DEFAULT_COLLATOR.compare,
-    extractor = identity,
+    extractor = defaultExtractor("alphaNumericSort"),
     descending = false,
   } = options;
 

package/tsconfig.json

@@ -13,7 +13,7 @@
     "allowSyntheticDefaultImports": true,
     "forceConsistentCasingInFileNames": true,
     "jsx": "preserve",
-    "lib": ["dom", "dom.iterable", "esnext"],
+    "lib": ["dom", "dom.iterable", "esnext"]
   },
-  "exclude": ["node_modules", "dist"],
+  "exclude": ["node_modules", "dist"]
 }