@react-md/core 1.0.0-next.16 → 1.0.0-next.17

package/src/tree/useTreeExpansion.ts

@@ -1,6 +1,6 @@
 "use client";
-import { useCallback, useState } from "react";
 import { type UseStateSetter } from "../types.js";
+import { useReadonlySet } from "../useReadonlySet.js";
 import { type TreeDefaultIds, type TreeItemIdSet } from "./types.js";
 
 /**
@@ -11,7 +11,7 @@ import { type TreeDefaultIds, type TreeItemIdSet } from "./types.js";
  */
 export interface TreeExpansion {
   expandedIds: TreeItemIdSet;
-  toggleTreeItemExpansion(itemId: string): void;
+  toggleTreeItemExpansion: (itemId: string) => void;
   expandMultipleTreeItems: UseStateSetter<TreeItemIdSet>;
 }
 
@@ -22,31 +22,13 @@ export interface TreeExpansion {
 export function useTreeExpansion(
   defaultExpandedIds?: TreeDefaultIds
 ): TreeExpansion {
-  const [expandedIds, setExpandedIds] = useState<TreeItemIdSet>(() => {
-    const defaultIds =
-      typeof defaultExpandedIds === "function"
-        ? defaultExpandedIds()
-        : defaultExpandedIds;
-
-    return new Set(defaultIds);
+  const { value, setValue, toggleValue } = useReadonlySet({
+    defaultValue: defaultExpandedIds,
   });
 
-  const toggleTreeItemExpansion = useCallback((itemId: string) => {
-    setExpandedIds((prevExpandedIds) => {
-      const expandedIds = new Set(prevExpandedIds);
-      if (expandedIds.has(itemId)) {
-        expandedIds.delete(itemId);
-      } else {
-        expandedIds.add(itemId);
-      }
-
-      return expandedIds;
-    });
-  }, []);
-
   return {
-    expandedIds,
-    toggleTreeItemExpansion,
-    expandMultipleTreeItems: setExpandedIds,
+    expandedIds: value,
+    toggleTreeItemExpansion: toggleValue,
+    expandMultipleTreeItems: setValue,
   };
 }

package/src/tree/useTreeSelection.ts

@@ -1,6 +1,6 @@
 "use client";
-import { useCallback, useState } from "react";
 import { type UseStateSetter } from "../types.js";
+import { useReadonlySet } from "../useReadonlySet.js";
 import { type TreeDefaultIds, type TreeItemIdSet } from "./types.js";
 
 /**
@@ -13,7 +13,7 @@ export interface TreeSelection {
   /** @defaultValue `false` */
   multiSelect?: boolean;
   selectedIds: ReadonlySet<string>;
-  toggleTreeItemSelection(itemId: string): void;
+  toggleTreeItemSelection: (itemId: string) => void;
   selectMultipleTreeItems: UseStateSetter<TreeItemIdSet>;
 }
 
@@ -25,39 +25,15 @@ export function useTreeSelection(
   defaultSelectedIds?: TreeDefaultIds,
   multiSelect = false
 ): Required<TreeSelection> {
-  const [selectedIds, setSelectedIds] = useState<TreeItemIdSet>(() => {
-    const defaultIds =
-      typeof defaultSelectedIds === "function"
-        ? defaultSelectedIds()
-        : defaultSelectedIds;
-
-    return new Set(defaultIds);
+  const { value, setValue, toggleValue } = useReadonlySet({
+    toggleType: multiSelect ? "multiple" : "single-select",
+    defaultValue: defaultSelectedIds,
   });
 
-  const toggleTreeItemSelection = useCallback(
-    (itemId: string) => {
-      setSelectedIds((selectedIds) => {
-        if (!multiSelect) {
-          return selectedIds.has(itemId) ? selectedIds : new Set([itemId]);
-        }
-
-        const nextSelectedIds = new Set(selectedIds);
-        if (selectedIds.has(itemId)) {
-          nextSelectedIds.delete(itemId);
-        } else {
-          nextSelectedIds.add(itemId);
-        }
-
-        return nextSelectedIds;
-      });
-    },
-    [multiSelect]
-  );
-
   return {
-    selectedIds,
     multiSelect,
-    toggleTreeItemSelection,
-    selectMultipleTreeItems: setSelectedIds,
+    selectedIds: value,
+    toggleTreeItemSelection: toggleValue,
+    selectMultipleTreeItems: setValue,
   };
 }

package/src/tree/utils.ts

@@ -1,4 +1,8 @@
-import type { TreeItemNode, TreeData, DefaultTreeItemNode } from "./types.js";
+import {
+  type DefaultTreeItemNode,
+  type TreeData,
+  type TreeItemNode,
+} from "./types.js";
 
 /**
  * This will get all the items from the provided itemId up to the root of the
@@ -48,7 +52,7 @@ export function getChildTreeItems<T extends TreeItemNode = DefaultTreeItemNode>(
   parentId: string | null,
   recursive = false
 ): readonly T[] {
-  const items = Array.isArray(data) ? data : Object.values(data);
+  const items: readonly T[] = Array.isArray(data) ? data : Object.values(data);
 
   return items.reduce<T[]>((list, item) => {
     if (parentId !== item.parentId) {

package/src/types.ts

@@ -5,7 +5,7 @@ import type { Dispatch, ReactElement, Ref, SetStateAction } from "react";
  * object even though a `ref` isn't a real prop.
  */
 export type PropsWithRef<
-  Props extends {},
+  Props extends object,
   Element extends HTMLElement,
 > = Props & {
   /**
@@ -18,7 +18,7 @@ export type PropsWithRef<
  * A simple type that can be used for different components that clone a
  * `className` into a child component.
  */
-export type ClassNameCloneableChild<T = {}> = ReactElement<
+export type ClassNameCloneableChild<T = object> = ReactElement<
   T & { className?: string }
 >;
 
@@ -171,12 +171,28 @@ export type CssPosition = "fixed" | "sticky" | "static";
  * @since 6.0.0
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type AnyFunction = (...args: any[]) => any | void;
+export type AnyFunction = (...args: any[]) => any;
 
 /**
  * @since 6.0.0
  */
-export type CancelableFunction<F extends AnyFunction> = F & { cancel(): void };
+export type CancelableFunction<F extends AnyFunction> = F & {
+  cancel: () => void;
+};
+
+/**
+ * @since 6.0.0
+ */
+export type DebouncedFunction<F extends AnyFunction> = CancelableFunction<
+  (...args: Parameters<F>) => void
+>;
+
+/**
+ * @since 6.0.0
+ */
+export type ThrottledFunction<F extends AnyFunction> = CancelableFunction<
+  (...args: Parameters<F>) => ReturnType<F>
+>;
 
 /**
  * @since 6.0.0

package/src/typography/WritingDirectionProvider.tsx

@@ -34,7 +34,7 @@ export interface WritingDirectionContext {
   /**
    * Toggles the current writing direction for the first parent `Dir` component.
    */
-  toggleDir(): void;
+  toggleDir: () => void;
 }
 
 /** @internal */

package/src/useDebouncedFunction.ts

@@ -1,15 +1,8 @@
 "use client";
 import { useEffect, useMemo, useRef } from "react";
-import { type CancelableFunction, type AnyFunction } from "./types.js";
+import { type AnyFunction, type DebouncedFunction } from "./types.js";
 import { useIsomorphicLayoutEffect } from "./useIsomorphicLayoutEffect.js";
 
-/**
- * @since 6.0.0
- */
-export type DebouncedFunction<F extends AnyFunction> = CancelableFunction<
-  (...args: Parameters<F>) => void
->;
-
 /**
  * Creates a function that will only be called if it has not been called again
  * for X milliseconds.
@@ -109,7 +102,9 @@ export function useDebouncedFunction<F extends AnyFunction>(
         funcRef.current(...args);
       }, wait);
     };
-    debounced.cancel = () => window.clearTimeout(timeout.current);
+    debounced.cancel = () => {
+      window.clearTimeout(timeout.current);
+    };
 
     return debounced;
   }, [wait]);

package/src/useDropzone.ts

@@ -12,10 +12,10 @@ const noop = (): void => {
  * instead of the `DropzoneHandlers` type.
  */
 export interface DropzoneHandlers {
-  onDrop<E extends HTMLElement>(event: DragEvent<E>): void;
-  onDragEnter?<E extends HTMLElement>(event: DragEvent<E>): void;
-  onDragOver?<E extends HTMLElement>(event: DragEvent<E>): void;
-  onDragLeave?<E extends HTMLElement>(event: DragEvent<E>): void;
+  onDrop: <E extends HTMLElement>(event: DragEvent<E>) => void;
+  onDragEnter?: <E extends HTMLElement>(event: DragEvent<E>) => void;
+  onDragOver?: <E extends HTMLElement>(event: DragEvent<E>) => void;
+  onDragLeave?: <E extends HTMLElement>(event: DragEvent<E>) => void;
 }
 
 /**

package/src/useIntersectionObserver.ts

@@ -89,7 +89,7 @@ export interface BaseIntersectionObserverHookOptions {
    *     // pretend some expensive computation
    *     return [0, 0.25, 0.5, 0.75, 1];
    *   }, []),
-   *   OnUpdate: useCallback(() => {
+   *   onUpdate: useCallback(() => {
    *     // do something
    *   }, []),
    * });
@@ -97,7 +97,7 @@ export interface BaseIntersectionObserverHookOptions {
    *
    * If this option is provided, {@link threshold}'s value will be ignored.
    */
-  getThreshold?(): IntersectionObserverThreshold;
+  getThreshold?: () => IntersectionObserverThreshold;
 
   /**
    * **Must be wrapped in `useCallback` to prevent re-creating the
@@ -121,7 +121,7 @@ export interface BaseIntersectionObserverHookOptions {
    *
    * Note: If this option is provided, {@link rootMargin} will be ignored.
    */
-  getRootMargin?(): IntersectionObserverRootMargin;
+  getRootMargin?: () => IntersectionObserverRootMargin;
 }
 
 /**
@@ -156,7 +156,7 @@ export interface IntersectionObserverHookOptions<E extends HTMLElement>
    * }
    * ```
    */
-  onUpdate(entries: readonly IntersectionObserverEntry[]): void;
+  onUpdate: (entries: readonly IntersectionObserverEntry[]) => void;
 
   /**
    * **Must be wrapped in `useCallback` to prevent re-creating the
@@ -185,7 +185,7 @@ export interface IntersectionObserverHookOptions<E extends HTMLElement>
    * }
    * ```
    */
-  getTargets?(): readonly Element[];
+  getTargets?: () => readonly Element[];
 }
 
 /**

package/src/useLocalStorage.ts

@@ -69,7 +69,7 @@ export interface LocalStorageHookOptions<T> {
 /**
  * @since 6.0.0
  */
-export const defaultLocalStorageSerializer = <T>(value: T): string =>
+export const defaultLocalStorageSerializer = (value: unknown): string =>
   typeof value === "string" ? value : `${value}`;
 
 /** @since 6.0.0 */
@@ -135,7 +135,7 @@ export const getItemFromStorage = <T>(
     key,
     fallback,
     storage = localStorage,
-    deserializer = JSON.parse,
+    deserializer = JSON.parse as LocalStorageDeserializer<T>,
   } = options;
   if (!key) {
     return fallback;
@@ -144,7 +144,7 @@ export const getItemFromStorage = <T>(
   try {
     const value = storage.getItem(key);
     return !value ? fallback : deserializer(value);
-  } catch (e) {
+  } catch {
     return fallback;
   }
 };
@@ -255,7 +255,7 @@ export interface LocalStorageHookReturnValue<T> {
   /**
    * Remove the item from local storage.
    */
-  remove(): void;
+  remove: () => void;
 
   /**
    * Manually persist the current {@link value} into local storage. This is only
@@ -291,7 +291,7 @@ export interface LocalStorageHookReturnValue<T> {
    * }
    * ```
    */
-  persist(): void;
+  persist: () => void;
 }
 
 /**
@@ -456,7 +456,7 @@ export function useLocalStorage<T>(
   const serializer =
     options.serializer ??
     (raw ? defaultLocalStorageSerializer : JSON.stringify);
-  const deserializer =
+  const deserializer: LocalStorageDeserializer<T> =
     options.deserializer ??
     (raw && typeof initialValue === "string" ? identity : JSON.parse);
 

package/src/useMutationObserver.ts

@@ -14,7 +14,7 @@ export interface MutationObserverHookOptions<E extends HTMLElement>
    */
   disabled?: boolean;
 
-  onObserved(mutation: MutationRecord): void;
+  onObserved: (mutation: MutationRecord) => void;
 }
 
 /**

package/src/useOrientation.ts

@@ -40,7 +40,9 @@ export const getOrientationType = (): OrientationType => {
 export function useOrientation(): OrientationType {
   const [orientation, setOrientation] = useState(getOrientationType);
   useEffect(() => {
-    const handler = (): void => setOrientation(getOrientationType());
+    const handler = (): void => {
+      setOrientation(getOrientationType());
+    };
 
     const { orientation } = window.screen;
     if (orientation) {

package/src/usePageInactive.ts

@@ -36,7 +36,7 @@ export interface PageInactiveOptions {
    * This will be called whenever the page activity changes based on the
    * {@link PageInactiveType}.
    */
-  onChange(active: boolean): void;
+  onChange: (active: boolean) => void;
 
   /**
    * This will be fired whenever the {@link disabled} state is `true` which can
@@ -47,7 +47,7 @@ export interface PageInactiveOptions {
    *
    * @defaultValue `() => {}`
    */
-  onDisabledCleanup?(): void;
+  onDisabledCleanup?: () => void;
 }
 
 /**

package/src/useReadonlySet.ts

@@ -0,0 +1,122 @@
+"use client";
+import { useCallback, useState } from "react";
+import { type UseStateSetter, type UseStateInitializer } from "./types.js";
+
+/**
+ * @since 6.0.0
+ */
+export interface ReadonlySetOptions<T> {
+  /**
+   * Sets the behavior for when the
+   * {@link ReadonlySetImplementation.toggleValue} is triggered and mostly for
+   * internal usage. The default behavior (`"multiple"`) is to work how most
+   * would expect:
+   * - If the item does not exist in the set, add it.
+   * - If the item exists in the set, remove it.
+   *
+   * Setting this to `"single"` makes it so that only a single item can be in
+   * the set at once and will toggle like normal:
+   * - If the item does not exist in the set, return a new set only including
+   *   the item.
+   * - If the item exists in the set, return an empty set.
+   * An example usage is the `useExpansionPanels` to allow only a single panel
+   * to be expanded at a time.
+   *
+   * Setting this to `"single-select"` makes it so that only a single item can
+   * be in the set at once but will not toggle:
+   * - If the item does not exist in the set, return a new set only including
+   *   the item.
+   * - If the item exists in the set, do nothing
+   * An example usage is the `useTreeSelection` to always require at least one
+   * tree item to be selected. It is impossible to deselect an item.
+   *
+   * @defaultValue `"multiple"`
+   */
+  toggleType?: "single" | "multiple" | "single-select";
+  defaultValue?: UseStateInitializer<ReadonlySet<T> | readonly T[]>;
+}
+
+/**
+ * @since 6.0.0
+ */
+export interface ReadonlySetImplementation<T> {
+  value: ReadonlySet<T>;
+  setValue: UseStateSetter<ReadonlySet<T>>;
+  toggleValue: (item: T) => void;
+}
+
+/**
+ * This is most likely an internal only hook to manage state for a
+ * `ReadonlySet`. You most likely want to use one of the other hooks that
+ * leverage this instead:
+ *
+ * - `useCheckboxGroup`
+ * - `useExpansionPanels`
+ * - `useTreeSelection`
+ * - `useTreeExpansion`
+ * - etc
+ *
+ * @example Simple Example
+ * ```tsx
+ * import { cnb } from "cnbuilder";
+ * import { useReadonlySet } from "@react-md/core/useReadonlySet";
+ *
+ * function Example() {
+ *   const { value, toggleValue } = useReadonlySet();
+ *
+ *   return (
+ *     <>
+ *       {someList.map((item) => (
+ *         <div key={item.id} className={cnb(value.has(item.id) && styles.selected)}>
+ *           {item.name}
+ *           <Button onClick={() => toggleValue(item.id)}>Button</Button>
+ *         </div>
+ *       ))}
+ *     </>
+ *   );
+ * }
+ * ```
+ * @since 6.0.0
+ */
+export function useReadonlySet<T>(
+  options: ReadonlySetOptions<T> = {}
+): ReadonlySetImplementation<T> {
+  const { defaultValue, toggleType = "multiple" } = options;
+  const [value, setValue] = useState<ReadonlySet<T>>(() => {
+    const initial =
+      defaultValue instanceof Function ? defaultValue() : (defaultValue ?? []);
+
+    return new Set(initial);
+  });
+
+  const toggleValue = useCallback(
+    (item: T) => {
+      setValue((prevValue) => {
+        const exists = prevValue.has(item);
+        if (toggleType === "single") {
+          return new Set(exists ? [] : [item]);
+        }
+
+        if (toggleType === "single-select") {
+          return exists ? prevValue : new Set([item]);
+        }
+
+        const nextValue = new Set(prevValue);
+        if (exists) {
+          nextValue.delete(item);
+        } else {
+          nextValue.add(item);
+        }
+
+        return nextValue;
+      });
+    },
+    [toggleType]
+  );
+
+  return {
+    value,
+    setValue,
+    toggleValue,
+  };
+}

package/src/useResizeListener.ts

@@ -33,7 +33,7 @@ export interface ResizeListenerOptions extends AddEventListenerOptions {
    * This function will be called whenever the resize event is fired on the
    * `window`. This should be wrapped in `useCallback`.
    */
-  onUpdate(event: Event): void;
+  onUpdate: (event: Event) => void;
 }
 
 /**

package/src/useThrottledFunction.ts

@@ -1,15 +1,8 @@
 "use client";
 import { useEffect, useMemo, useRef } from "react";
-import { type AnyFunction, type CancelableFunction } from "./types.js";
+import { type AnyFunction, type ThrottledFunction } from "./types.js";
 import { useIsomorphicLayoutEffect } from "./useIsomorphicLayoutEffect.js";
 
-/**
- * @since 6.0.0
- */
-export type ThrottledFunction<F extends AnyFunction> = CancelableFunction<
-  (...args: Parameters<F>) => ReturnType<F>
->;
-
 /**
  * Creates a function that will only be called once every X milliseconds.
  *
@@ -113,19 +106,23 @@ export function useThrottledFunction<F extends AnyFunction>(
       const remaining = wait - (now - lastCalledTime.current);
       if (remaining <= 0 || remaining > wait) {
         lastCalledTime.current = now;
+
         result.current = funcRef.current(...args.current);
       } else if (!timeout.current) {
         timeout.current = window.setTimeout(() => {
           lastCalledTime.current = Date.now();
           timeout.current = undefined;
           // should exist by this time
+
           result.current = funcRef.current(...(args.current as Parameters<F>));
         }, remaining);
       }
 
       return result.current as ReturnType<F>;
     };
-    throttled.cancel = () => window.clearTimeout(timeout.current);
+    throttled.cancel = () => {
+      window.clearTimeout(timeout.current);
+    };
 
     return throttled;
   }, [wait]);

package/src/useToggle.ts

@@ -8,9 +8,9 @@ import { type UseStateInitializer, type UseStateSetter } from "./types.js";
 export interface ToggleImplementation {
   toggled: boolean;
   setToggled: UseStateSetter<boolean>;
-  toggle(): void;
-  enable(): void;
-  disable(): void;
+  toggle: () => void;
+  enable: () => void;
+  disable: () => void;
 }
 
 /**

package/src/utils/RenderRecursively.tsx

@@ -97,7 +97,7 @@ export interface RenderRecursivelyProps<
    * @see {@link getRecursiveItemKey}
    * @defaultValue `({ index, depth }) => ${depth}-${index}`.
    */
-  getItemKey?(options: RecursiveItemKeyOptions<Item>): string;
+  getItemKey?: (options: RecursiveItemKeyOptions<Item>) => string;
 }
 
 /**

package/src/utils/alphaNumericSort.ts

@@ -58,7 +58,7 @@ export interface AlphaNumericSortOptions<T> {
    * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Collator/Collator
    * @defaultValue `new Intl.Collator("en-US", { numeric: true, caseFirst: "upper" }).compare`
    */
-  compare?(a: string, b: string): number;
+  compare?: (a: string, b: string) => number;
 
   /**
    * Setting this to `true` will return the list in descending order instead of

package/src/utils/debounce.ts

@@ -0,0 +1,22 @@
+import { type AnyFunction, type DebouncedFunction } from "../types.js";
+
+/**
+ * @since 6.0.0
+ */
+export function debounce<F extends AnyFunction>(
+  fn: F,
+  duration: number
+): DebouncedFunction<F> {
+  let timeout: NodeJS.Timeout | undefined;
+  const debounced: DebouncedFunction<F> = (...args) => {
+    clearTimeout(timeout);
+    timeout = setTimeout(() => {
+      fn(...args);
+    }, duration);
+  };
+  debounced.cancel = () => {
+    clearTimeout(timeout);
+  };
+
+  return debounced;
+}

package/src/utils/throttle.ts

@@ -0,0 +1,38 @@
+import { type AnyFunction, type ThrottledFunction } from "../types.js";
+
+/**
+ * @since 6.0.0
+ */
+export function throttle<F extends AnyFunction>(
+  fn: F,
+  wait: number
+): ThrottledFunction<F> {
+  let args: Parameters<F>;
+  let result: ReturnType<F>;
+  let timeout: NodeJS.Timeout | undefined;
+  let lastCalledTime = 0;
+
+  const throttled: ThrottledFunction<F> = (...nextArgs) => {
+    args = nextArgs;
+
+    const now = Date.now();
+    const remaining = wait - (now - lastCalledTime);
+    if (remaining <= 0 || remaining > wait) {
+      lastCalledTime = now;
+      result = fn(...args);
+    } else if (!timeout) {
+      timeout = setTimeout(() => {
+        lastCalledTime = Date.now();
+        timeout = undefined;
+        result = fn(...args);
+      }, remaining);
+    }
+
+    return result;
+  };
+  throttled.cancel = () => {
+    clearTimeout(timeout);
+  };
+
+  return throttled;
+}

package/src/utils/wait.ts

@@ -14,4 +14,8 @@
  * @since 6.0.0
  */
 export const wait = (ms: number): Promise<void> =>
-  new Promise((resolve) => setTimeout(() => resolve(), ms));
+  new Promise((resolve) =>
+    setTimeout(() => {
+      resolve();
+    }, ms)
+  );