chore(core): update docs and tests

packages/core/src/utils/__tests__/alphaNumericSort.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from "@jest/globals";
+import { alphaNumericSort } from "../alphaNumericSort.js";
+
+describe("alphaNumericSort", () => {
+  it("should sort the list by creating a new list instead of mutating it", () => {
+    const list = ["a", "f", "d"];
+    const sorted = alphaNumericSort(list);
+    expect(sorted).toEqual(["a", "d", "f"]);
+    expect(sorted).not.toBe(list);
+    expect(list).toEqual(["a", "f", "d"]);
+  });
+
+  it("should require an extractor if the provided list is not a list of strings", () => {
+    // @ts-expect-error
+    expect(() => alphaNumericSort(["a", 2])).toThrow(
+      `A \`TextExtractor\` must be provided to \`alphaNumericSort\` for lists that do not contain strings`
+    );
+
+    expect(
+      alphaNumericSort(["a", 2], {
+        extractor: (a) => (typeof a === "number" ? `${a}` : a),
+      })
+    ).toEqual([2, "a"]);
+  });
+
+  it("should support a list of objects", () => {
+    const list = [{ name: "Hello" }, { name: "World!" }, { name: "Another!" }];
+    expect(
+      alphaNumericSort(list, {
+        extractor: (a) => a.name,
+      })
+    ).toEqual([{ name: "Another!" }, { name: "Hello" }, { name: "World!" }]);
+  });
+
+  it("should allow for a custom compare function", () => {
+    const list = ["Z", "a", "z", "ä"];
+    const compareDE = new Intl.Collator("de").compare;
+    const compareSV = new Intl.Collator("sv").compare;
+
+    expect(alphaNumericSort(list, { compare: compareDE })).toEqual([
+      "a",
+      "ä",
+      "z",
+      "Z",
+    ]);
+    expect(alphaNumericSort(list, { compare: compareSV })).toEqual([
+      "a",
+      "z",
+      "Z",
+      "ä",
+    ]);
+
+    expect(alphaNumericSort(list)).toEqual(["a", "ä", "Z", "z"]);
+  });
+});

packages/core/src/utils/alphaNumericSort.ts

@@ -25,9 +25,9 @@ export interface AlphaNumericSortOptions<T> {
    *
    * const items: Item[] = [{ name: 'Hello' }, { name: 'World' }];
    *
-   * `alphaNumericSort(items, {
-   *   extractor: item => item.name,
-   * })`
+   * alphaNumericSort(items, {
+   *   extractor: (item) => item.name,
+   * });
    * ```
    *
    * For javascript developers, this will throw an error in dev mode if an
@@ -95,7 +95,7 @@ export function alphaNumericSort<T extends string>(
  * const items: Item[] = [{ name: "World" }, { name: "Hello" }];
  *
  * const sorted = alphaNumericSort(items, {
- *   extractor: item => item.name,
+ *   extractor: (item) => item.name,
  * });
  * // sorted == [{ name: "Hello" }, { name: "World" }]
  * ```

packages/core/src/utils/bem.ts

@@ -26,7 +26,7 @@ export type BEMResult = (
  * Applies the BEM styled class name to an element.
  *
  * @example Simple Example
- * ```jsx
+ * ```tsx
  * import { bem } from "@react-md/core":
  *
  * const styles = bem("my-component"):