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

package/src/typography/TextContainer.tsx

@@ -15,8 +15,6 @@ export interface TextContainerProps
     TextContainerClassNameOptions {}
 
 /**
- * **Server Component**
- *
  * This component should be used to render text based content with an
  * appropriate max line length to optimize legibility.
  *

package/src/typography/Typography.tsx

@@ -97,8 +97,6 @@ export interface TypographyProps
 }
 
 /**
- * **Server Component**
- *
  * Render text with one of the material design typography styles applied and
  * optional styles like font-weight, font-style, text color, etc.
  *

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 */
@@ -109,7 +109,7 @@ export interface WritingDirectionProviderProps {
  *
  * In node environments, this will default to `"ltr"`.
  *
- * @since 6.0.0
+ * @since 6.0.0 Renamed from `DEFAULT_DIR`
  */
 export const DEFAULT_WRITING_DIRECTION = (): Dir => {
   let dir: Dir = "ltr";
@@ -194,7 +194,7 @@ export const DEFAULT_WRITING_DIRECTION = (): Dir => {
  * );
  * ```
  *
- * @since 6.0.0
+ * @since 6.0.0 Renamed from `Dir`
  */
 export function WritingDirectionProvider(
   props: WritingDirectionProviderProps

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

@@ -5,7 +5,12 @@ import { delegateEvent } from "./delegateEvent.js";
 import { type useResizeObserver } from "./useResizeObserver.js";
 
 /**
- * @since 6.0.0  Updated the API
+ * @since 6.0.0 Removed the `immediate` option to force the resize handler to be
+ * called immediately.
+ * @since 6.0.0 Renamed to a new API so that there is no longer an `options`
+ * property and instead the `AddEventListenerOptions` are part of the hook
+ * options.
+ * @since 6.0.0 Renamed `onResize` to `onUpdate` and `enabled` to `disabled`.
  */
 export interface ResizeListenerOptions extends AddEventListenerOptions {
   /**
@@ -13,6 +18,7 @@ export interface ResizeListenerOptions extends AddEventListenerOptions {
    * `window.requestAnimationFrame`.
    *
    * @defaultValue `true`
+   * @since 6.0.0
    */
   throttle?: boolean;
 
@@ -27,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/useResizeObserver.ts

@@ -23,9 +23,9 @@ interface TargetSize {
 
 /** @internal */
 interface TargetSubscription {
-  readonly onUpdate: ResizeObserverEntryCallback;
-  readonly disableHeight: boolean;
-  readonly disableWidth: boolean;
+  onUpdate: ResizeObserverEntryCallback;
+  disableHeight: boolean;
+  disableWidth: boolean;
 
   size?: TargetSize;
 }

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

@@ -1,16 +1,16 @@
 "use client";
 import { useCallback, useState } from "react";
-import type { UseStateInitializer, UseStateSetter } from "./types.js";
+import { type UseStateInitializer, type UseStateSetter } from "./types.js";
 
 /**
  * @since 6.0.0
  */
-export interface ToggleHookReturnValue {
+export interface ToggleImplementation {
   toggled: boolean;
   setToggled: UseStateSetter<boolean>;
-  toggle(): void;
-  enable(): void;
-  disable(): void;
+  toggle: () => void;
+  enable: () => void;
+  disable: () => void;
 }
 
 /**
@@ -25,7 +25,7 @@ export interface ToggleHookReturnValue {
  *
  *   return (
  *     <>
- *       <Button onClick=[toggle]>Toggle</Button>
+ *       <Button onClick={toggle}>Toggle</Button>
  *       {`Toggled: ${toggled}`}
  *     </>
  *   );
@@ -36,7 +36,7 @@ export interface ToggleHookReturnValue {
  */
 export function useToggle(
   defaultValue: UseStateInitializer<boolean> = false
-): Readonly<ToggleHookReturnValue> {
+): ToggleImplementation {
   const [toggled, setToggled] = useState(defaultValue);
 
   return {

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)
+  );

package/src/window-splitter/WindowSplitter.tsx

@@ -1,51 +1,10 @@
-import { cnb } from "cnbuilder";
 import { forwardRef, type ButtonHTMLAttributes } from "react";
 import { type LabelRequiredForA11y } from "../types.js";
-import { bem } from "../utils/bem.js";
+import { windowSplitter } from "./styles.js";
 
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 import { type useWindowSplitter } from "./useWindowSplitter.js";
 
-const styles = bem("rmd-window-splitter");
-
-/**
- * @since 6.0.0
- */
-export interface WindowSplitterClassNameOptions {
-  className?: string;
-  dragging?: boolean;
-  reversed?: boolean;
-  vertical?: boolean;
-  disableFixed?: boolean;
-}
-
-/**
- * @since 6.0.0
- */
-export function windowSplitter(
-  options: WindowSplitterClassNameOptions = {}
-): string {
-  const {
-    vertical = false,
-    dragging,
-    reversed,
-    disableFixed,
-    className,
-  } = options;
-
-  return cnb(
-    styles({
-      h: !vertical,
-      hr: !vertical && reversed,
-      v: vertical,
-      vr: vertical && reversed,
-      a: disableFixed,
-      dragging,
-    }),
-    className
-  );
-}
-
 /**
  * @since 6.0.0
  * @see {@link https://www.w3.org/WAI/ARIA/apg/patterns/windowsplitter/}
@@ -82,10 +41,46 @@ export interface BaseWindowSplitterProps
 export type WindowSplitterProps = LabelRequiredForA11y<BaseWindowSplitterProps>;
 
 /**
- * **Server Component**
- * Most likely a client component since it relies on `useWindowSplitter`
+ * The `WindowSplitter` should be used with the `useWindowSplitter` hook to
+ * resize parts of a layout.
+ *
+ * See the `useResizableLayout` hook if the entire page layout should be
+ * resizable.
+ *
+ * @example Simple Example
+ * ```tsx
+ * "use client";
+ * import { WindowSplitter } from "@react-md/core/window-splitter/WindowSplitter";
+ * import { useWindowSplitter } from "@react-md/core/window-splitter/useWindowSplitter";
+ * import { useId, type ReactElement } from "react";
+ *
+ * export function Example(): ReactElement {
+ *   const panelId = useId();
+ *   const { value, splitterProps } = useWindowSplitter({
+ *     min: 120,
+ *     max: 380,
+ *   });
+ *
+ *   return (
+ *     <div
+ *       style={{
+ *         "--rmd-window-splitter-position": `${value}px`,
+ *         display: "grid",
+ *         gridTemplateColumns: "var(--rmd-window-splitter-position, 120px) 1fr",
+ *       }}
+ *     >
+ *       <div>Panel 1</div>
+ *       <WindowSplitter
+ *         {...splitterProps}
+ *         aria-controls={panelId}
+ *         aria-labelledby={panelId}
+ *       />
+ *       <div>Panel 2</div>
+ *     </div>
+ *   );
+ * }
+ * ```
  *
- * @see {@link useWindowSplitter} for an example usage
  * @since 6.0.0
  */
 export const WindowSplitter = forwardRef<