@react-md/core 1.0.0-next.7 → 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";