@react-md/core 1.0.0-next.19 → 1.0.0-next.20

package/src/positioning/useFixedPositioning.ts

@@ -1,14 +1,16 @@
 "use client";
+
 import {
-  useCallback,
-  useEffect,
-  useRef,
-  useState,
   type CSSProperties,
   type Ref,
   type RefCallback,
   type RefObject,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
 } from "react";
+
 import { delegateEvent } from "../delegateEvent.js";
 import { type TransitionCallbacks } from "../transition/types.js";
 import { useEnsuredRef } from "../useEnsuredRef.js";
@@ -138,8 +140,10 @@ export interface FixedPositioningOptions<
 /**
  * @typeParam E - An HTMLElement type for the fixed element.
  * @since 4.0.0
+ * @since 6.0.0 Renamed from `FixedPositioningHookReturnValue` to
+ * `FixedPositioningImplementation` to match naming conventions.
  */
-export interface FixedPositioningHookReturnValue<E extends HTMLElement> {
+export interface FixedPositioningImplementation<E extends HTMLElement> {
   /**
    * A ref that should be passed to a component for the fixed positioning
    * behavior to work correctly.
@@ -180,8 +184,12 @@ export interface FixedPositioningHookReturnValue<E extends HTMLElement> {
  *
  * @example Simple Example
  * ```tsx
- * import { ReactElement, useRef, useState } from "react";
- * import { Button, useCSSTransition, useFixedPositioning } from "@react-md/core";
+ * "use client";
+ *
+ * import { Button } from "@react-md/core/button/Button";
+ * import { useFixedPositioning } from "@react-md/core/positioning/useFixedPositioning";
+ * import { useCSSTransition } from "@react-md/core/transition/useCSSTransition";
+ * import { type ReactElement, useRef, useState } from "react";
  *
  * function Example(): ReactElement {
  *   const fixedTo = useRef<HTMLButtonElement>(null);
@@ -207,10 +215,7 @@ export interface FixedPositioningHookReturnValue<E extends HTMLElement> {
  *
  *   return (
  *     <>
- *       <Button
- *         ref={fixedTo}
- *         onClick={() => setTransitionIn(!transitionIn)}
- *       >
+ *       <Button ref={fixedTo} onClick={() => setTransitionIn(!transitionIn)}>
  *         Toggle
  *       </Button>
  *       {rendered && (
@@ -232,7 +237,7 @@ export function useFixedPositioning<
   FixedElement extends HTMLElement,
 >(
   options: FixedPositioningOptions<FixedToElement, FixedElement>
-): FixedPositioningHookReturnValue<FixedElement> {
+): FixedPositioningImplementation<FixedElement> {
   const {
     style: propStyle,
     nodeRef,

package/src/progress/CircularProgress.tsx

@@ -1,10 +1,11 @@
 import { cnb } from "cnbuilder";
 import {
-  forwardRef,
-  useMemo,
   type CSSProperties,
   type HTMLAttributes,
+  forwardRef,
+  useMemo,
 } from "react";
+
 import { cssUtils } from "../cssUtils.js";
 import { type LabelRequiredForA11y } from "../types.js";
 import { useEnsuredId } from "../useEnsuredId.js";

package/src/progress/LinearProgress.tsx

@@ -1,10 +1,11 @@
 import { cnb } from "cnbuilder";
 import {
-  forwardRef,
-  useMemo,
   type CSSProperties,
   type HTMLAttributes,
+  forwardRef,
+  useMemo,
 } from "react";
+
 import { cssUtils } from "../cssUtils.js";
 import { type LabelRequiredForA11y } from "../types.js";
 import { useEnsuredId } from "../useEnsuredId.js";

package/src/responsive-item/ResponsiveItem.tsx

@@ -1,7 +1,8 @@
-import { forwardRef, type HTMLAttributes } from "react";
+import { type HTMLAttributes, forwardRef } from "react";
+
 import {
-  responsiveItem,
   type ResponsiveItemClassNameOptions,
+  responsiveItem,
 } from "./responsiveItemStyles.js";
 
 /**

package/src/responsive-item/ResponsiveItemOverlay.tsx

@@ -1,9 +1,10 @@
-import { forwardRef, type HTMLAttributes } from "react";
+import { type HTMLAttributes, forwardRef } from "react";
+
 import {
-  responsiveItemOverlay,
   type ResponsiveItemOverlayClassNameOptions,
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   type ResponsiveItemOverlayPosition,
+  responsiveItemOverlay,
 } from "./responsiveItemOverlayStyles.js";
 
 /**

package/src/responsive-item/responsiveItemOverlayStyles.ts

@@ -1,4 +1,5 @@
 import { cnb } from "cnbuilder";
+
 import { bem } from "../utils/bem.js";
 
 const styles = bem("rmd-responsive-item-overlay");

package/src/responsive-item/responsiveItemStyles.ts

@@ -1,4 +1,5 @@
 import { cnb } from "cnbuilder";
+
 import { bem } from "../utils/bem.js";
 
 const styles = bem("rmd-responsive-item");

package/src/scroll/ScrollLock.tsx

@@ -1,4 +1,5 @@
 "use client";
+
 import { useScrollLock } from "./useScrollLock.js";
 
 /**

package/src/scroll/useScrollLock.ts

@@ -1,5 +1,7 @@
 "use client";
+
 import { useEffect } from "react";
+
 import { getScrollbarWidth } from "./getScrollbarWidth.js";
 
 declare module "react" {
@@ -15,8 +17,8 @@ export const SCROLLBAR_SIZE_VAR = "--rmd-scrollbar-size";
 let isLocked = false;
 
 /**
+ * Used to enable scroll locking on the entire page.
  *
- * @internal
  * @since 6.0.0 No longer support scroll locking elements other than
  * the `document.body` since it's more reliable to scroll lock with an overlay.
  * @since 6.0.0 Now applies `paddingRight` equal to the current OS's

package/src/searching/fuzzy.ts

@@ -120,7 +120,7 @@ export type FuzzySearchOptions<T> = BaseSearchOptions<T>;
  *   type: "search",
  * });
  * // "charCodeAt"
- *  //    ^   ^
+ * //    ^   ^
  * ```
  *
  * @since 6.0.0

package/src/searching/useFuzzyMatch.ts

@@ -1,5 +1,7 @@
 "use client";
+
 import { useCallback, useRef } from "react";
+
 import { createFuzzyRegExp } from "./fuzzy.js";
 
 /**

package/src/segmented-button/SegmentedButton.tsx

@@ -1,6 +1,8 @@
 "use client";
-import { forwardRef, type ButtonHTMLAttributes, type ReactNode } from "react";
-import { getIcon } from "../icon/iconConfig.js";
+
+import { type ButtonHTMLAttributes, type ReactNode, forwardRef } from "react";
+
+import { getIcon } from "../icon/config.js";
 import { type ComponentWithRippleProps } from "../interaction/types.js";
 import { useElementInteraction } from "../interaction/useElementInteraction.js";
 import { useHigherContrastChildren } from "../interaction/useHigherContrastChildren.js";

package/src/segmented-button/SegmentedButtonContainer.tsx

@@ -1,7 +1,8 @@
-import { forwardRef, type HTMLAttributes, type ReactNode } from "react";
+import { type HTMLAttributes, type ReactNode, forwardRef } from "react";
+
 import {
-  segmentedButtonContainerStyles,
   type SegmentedButtonContainerClassNameOptions,
+  segmentedButtonContainerStyles,
 } from "./segmentedButtonContainerStyles.js";
 
 /**

package/src/segmented-button/segmentedButtonContainerStyles.ts

@@ -1,4 +1,5 @@
 import { cnb } from "cnbuilder";
+
 import { bem } from "../utils/bem.js";
 
 const styles = bem("rmd-segmented-button-container");

package/src/segmented-button/segmentedButtonStyles.ts

@@ -1,4 +1,5 @@
 import { cnb } from "cnbuilder";
+
 import { cssUtils } from "../cssUtils.js";
 import { bem } from "../utils/bem.js";
 

package/src/sheet/Sheet.tsx

@@ -1,12 +1,14 @@
 "use client";
+
 import { forwardRef } from "react";
-import { Dialog, type BaseDialogProps } from "../dialog/Dialog.js";
+
+import { type BaseDialogProps, Dialog } from "../dialog/Dialog.js";
 import { type LabelRequiredForA11y } from "../types.js";
 import {
+  type BaseSheetClassNameOptions,
   DEFAULT_SHEET_CLASSNAMES,
   DEFAULT_SHEET_TIMEOUT,
   sheet,
-  type BaseSheetClassNameOptions,
 } from "./styles.js";
 
 /**

package/src/sheet/styles.ts

@@ -1,13 +1,13 @@
 import { cnb } from "cnbuilder";
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import { type BaseDialogProps } from "../dialog/Dialog.js";
 import {
   type CSSTransitionClassNames,
   type TransitionTimeout,
 } from "../transition/types.js";
 import { bem } from "../utils/bem.js";
 
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-import { type BaseDialogProps } from "../dialog/Dialog.js";
-
 declare module "react" {
   interface CSSProperties {
     "--rmd-sheet-height"?: string | number;

package/src/snackbar/DefaultToastRenderer.tsx

@@ -1,12 +1,14 @@
 "use client";
-import { useEffect, useMemo, type ReactElement } from "react";
+
+import { type ReactElement, useEffect, useMemo } from "react";
+
 import { usePageInactive } from "../usePageInactive.js";
-import { Toast, type ConfigurableToastProps } from "./Toast.js";
+import { type ConfigurableToastProps, Toast } from "./Toast.js";
 import { type ToastMeta } from "./ToastManager.js";
 import { useToastManager } from "./ToastManagerProvider.js";
 import {
-  CurrentToastActionsProvider,
   type CurrentToastActions,
+  CurrentToastActionsProvider,
 } from "./useCurrentToastActions.js";
 
 const noop = (): void => {

package/src/snackbar/Snackbar.tsx

@@ -1,5 +1,7 @@
 "use client";
-import { forwardRef, type ComponentType, type HTMLAttributes } from "react";
+
+import { type ComponentType, type HTMLAttributes, forwardRef } from "react";
+
 import { Portal } from "../portal/Portal.js";
 import { useEnsuredId } from "../useEnsuredId.js";
 import {
@@ -8,7 +10,7 @@ import {
 } from "./DefaultToastRenderer.js";
 import { type ConfigurableToastProps } from "./Toast.js";
 import { useToastQueue } from "./ToastManagerProvider.js";
-import { snackbar, type SnackbarPosition } from "./snackbarStyles.js";
+import { type SnackbarPosition, snackbar } from "./snackbarStyles.js";
 
 /**
  * @since 6.0.0 The `id` prop is optional

package/src/snackbar/Toast.tsx

@@ -1,12 +1,14 @@
 "use client";
+
 import {
-  forwardRef,
-  isValidElement,
   type AriaRole,
   type HTMLAttributes,
   type ReactElement,
   type ReactNode,
+  forwardRef,
+  isValidElement,
 } from "react";
+
 import { type ButtonProps } from "../button/Button.js";
 import { type BackgroundColor } from "../cssUtils.js";
 import {

package/src/snackbar/ToastActionButton.tsx

@@ -1,6 +1,8 @@
 "use client";
+
 import { cnb } from "cnbuilder";
 import { forwardRef } from "react";
+
 import { Button, type ButtonProps } from "../button/Button.js";
 import { type ButtonTheme } from "../button/buttonStyles.js";
 import { bem } from "../utils/bem.js";

package/src/snackbar/ToastCloseButton.tsx

@@ -1,9 +1,11 @@
 "use client";
+
 import { cnb } from "cnbuilder";
 import { forwardRef } from "react";
+
 import { Button, type ButtonProps } from "../button/Button.js";
 import { type ButtonType } from "../button/buttonStyles.js";
-import { getIcon } from "../icon/iconConfig.js";
+import { getIcon } from "../icon/config.js";
 import { bem } from "../utils/bem.js";
 import { useCurrentToastActions } from "./useCurrentToastActions.js";
 

package/src/snackbar/ToastContent.tsx

@@ -1,5 +1,7 @@
 "use client";
-import { forwardRef, useCallback, useState, type HTMLAttributes } from "react";
+
+import { type HTMLAttributes, forwardRef, useCallback, useState } from "react";
+
 import { useResizeObserver } from "../useResizeObserver.js";
 import { toastContent } from "./toastContentStyles.js";
 

package/src/snackbar/ToastManager.tsx

@@ -1,4 +1,5 @@
 import { nanoid } from "nanoid";
+
 import { type ConfigurableToastProps } from "./Toast.js";
 
 /**

package/src/snackbar/ToastManagerProvider.tsx

@@ -1,17 +1,18 @@
 "use client";
 
 import {
+  type ReactElement,
+  type ReactNode,
   createContext,
   useContext,
   useMemo,
   useSyncExternalStore,
-  type ReactElement,
-  type ReactNode,
 } from "react";
+
 import {
-  toastManager,
   type ToastManager,
   type ToastQueue,
+  toastManager,
 } from "./ToastManager.js";
 
 const context = createContext(toastManager);

package/src/snackbar/snackbarStyles.ts

@@ -1,4 +1,5 @@
 import { cnb } from "cnbuilder";
+
 import { bem } from "../utils/bem.js";
 
 const styles = bem("rmd-snackbar");

package/src/snackbar/toastContentStyles.ts

@@ -1,4 +1,5 @@
 import { cnb } from "cnbuilder";
+
 import { bem } from "../utils/bem.js";
 
 const styles = bem("rmd-toast-content");

package/src/snackbar/toastStyles.ts

@@ -1,5 +1,6 @@
 import { cnb } from "cnbuilder";
-import { cssUtils, type BackgroundColor } from "../cssUtils.js";
+
+import { type BackgroundColor, cssUtils } from "../cssUtils.js";
 import { bem } from "../utils/bem.js";
 
 declare module "react" {

package/src/snackbar/useCurrentToastActions.ts

@@ -1,4 +1,5 @@
 "use client";
+
 import { createContext, useContext } from "react";
 
 /**

package/src/storage/internalUtils.ts

@@ -0,0 +1,43 @@
+import { identity } from "../utils/identity.js";
+import { type StorageDeserializer, type StorageSerializers } from "./types.js";
+
+/**
+ * @since 6.0.0
+ * @internal
+ */
+export const defaultLocalStorageSerializer = (value: unknown): string =>
+  typeof value === "string" ? value : `${value}`;
+
+/**
+ * @since 6.0.0
+ * @internal
+ */
+export interface GetStorageSerializers<T> extends StorageSerializers<T> {
+  raw?: boolean;
+  initialValue: T;
+}
+
+/**
+ * @since 6.0.0
+ * @internal
+ */
+export function getStorageSerializers<T>(
+  options: GetStorageSerializers<T>
+): Required<StorageSerializers<T>> {
+  const { initialValue } = options;
+
+  // this allows for strings to automatically be stored as-is instead of adding
+  // additional quotes around then with JSON.stringify
+  const raw = options.raw ?? typeof initialValue === "string";
+  const serializer =
+    options.serializer ??
+    (raw ? defaultLocalStorageSerializer : JSON.stringify);
+  const deserializer: StorageDeserializer<T> =
+    options.deserializer ??
+    (raw && typeof initialValue === "string" ? identity : JSON.parse);
+
+  return {
+    serializer,
+    deserializer,
+  };
+}

package/src/storage/types.ts

@@ -0,0 +1,88 @@
+import { type UseStateInitializer, type UseStateSetter } from "../types.js";
+
+/** @since 6.0.0 */
+export type StorageSerializer<T> = (value: T) => string;
+
+/** @since 6.0.0 */
+export type StorageDeserializer<T> = (item: string) => T;
+
+/** @since 6.0.0 */
+export interface StorageSerializers<T> {
+  /**
+   * An optional function to serialize the `value` before storing it in local
+   * storage.
+   *
+   * @defaultValue `JSON.stringify`
+   */
+  serializer?: StorageSerializer<T>;
+
+  /**
+   * An optional function to deserialize the `value` if the item existed in
+   * local storage.
+   *
+   * @defaultValue `JSON.parse`
+   */
+  deserializer?: StorageDeserializer<T>;
+}
+
+/** @since 6.0.0 */
+export interface StorageOptions<T> extends StorageSerializers<T> {
+  /**
+   * The storage key name to use. This can be set to an empty string for
+   * internal usage of conditionally saving items to storage.
+   */
+  key: string;
+
+  /**
+   * The default value to use if an item does not exist in storage.
+   */
+  defaultValue: UseStateInitializer<T>;
+
+  /**
+   * Set this to `true` to update:
+   *
+   * - the default {@link serializer} to be:
+   * ```
+   * typeof value === "string" ? value : `${value}`
+   * ```
+   * - the default {@link deserializer} to not call `JSON.parse` if the
+   *   {@link defaultValue} is a string.
+   *
+   * @defaultValue `typeof defaultValue === 'string'`
+   */
+  raw?: boolean;
+
+  /**
+   * Set this to `true` to require a manual `persist()` or `remove()` call
+   * to update the storage value.
+   *
+   * @defaultValue `false`
+   */
+  manual?: boolean;
+
+  /** @defaultValue `globalThis.localStorage` */
+  storage?: Storage;
+}
+
+/** @since 6.0.0 */
+export interface StorageImplementation<T> {
+  value: T;
+
+  /**
+   * Updates the {@link value} in state. When the
+   * {@link StorageOptions.manual} option is `false`, the value will
+   * also be updated in local storage immediately.
+   */
+  setValue: UseStateSetter<T>;
+
+  /**
+   * Remove the item from local storage.
+   */
+  remove: () => void;
+
+  /**
+   * Manually persist the current {@link value} into local storage. This is only
+   * useful if the {@link StorageOptions.manual} option is `true`.
+   */
+  persist: () => void;
+}