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

package/src/form/useCheckboxGroup.ts

@@ -146,6 +146,8 @@ export interface CombinedCheckboxGroupReturnValue<V extends string> {
  * );
  * ```
  *
+ * @see {@link https://next.react-md.dev/components/Checkbox | Checkbox Demos}
+ * @see {@link https://next.react-md.dev/hooks/use-checkbox-group | useCheckboxGroup Demos}
  * @since 6.0.0
  */
 export function useCheckboxGroup<V extends string>(
@@ -184,6 +186,8 @@ export function useCheckboxGroup<V extends string>(
  * );
  * ```
  *
+ * @see {@link https://next.react-md.dev/components/Checkbox | Checkbox Demos}
+ * @see {@link https://next.react-md.dev/hooks/use-checkbox-group | useCheckboxGroup Demos}
  * @since 6.0.0
  */
 export function useCheckboxGroup<V extends string>(
@@ -213,6 +217,8 @@ export function useCheckboxGroup<V extends string>(
  * );
  * ```
  *
+ * @see {@link https://next.react-md.dev/components/Checkbox | Checkbox Demos}
+ * @see {@link https://next.react-md.dev/hooks/use-checkbox-group | useCheckboxGroup Demos}
  * @since 6.0.0
  */
 export function useCheckboxGroup<V extends string>(
@@ -251,6 +257,8 @@ export function useCheckboxGroup<V extends string>(
  * );
  * ```
  *
+ * @see {@link https://next.react-md.dev/components/Checkbox | Checkbox Demos}
+ * @see {@link https://next.react-md.dev/hooks/use-checkbox-group | useCheckboxGroup Demos}
  * @since 6.0.0
  */
 export function useCheckboxGroup<V extends string>(
@@ -260,6 +268,12 @@ export function useCheckboxGroup<V extends string>(
     values: readonly V[];
   }
 ): IndeterminateMenuItemCheckboxGroupImplementation<V>;
+/**
+ * @see {@link https://next.react-md.dev/components/Checkbox | Checkbox Demos}
+ * @see {@link https://next.react-md.dev/hooks/use-checkbox-group | useCheckboxGroup Demos}
+ * @since 6.0.0
+ * @internal
+ */
 export function useCheckboxGroup<V extends string>(
   options: CheckboxGroupOptions<V>
 ): CombinedCheckboxGroupReturnValue<V> {

package/src/form/useCombobox.ts

@@ -28,12 +28,8 @@ import {
   type PositionAnchor,
   type PositionWidth,
 } from "../positioning/types.js";
-import { TRANSITION_CONFIG } from "../transition/config.js";
-import {
-  type TransitionCallbacks,
-  type TransitionEnterHandler,
-  type TransitionExitHandler,
-} from "../transition/types.js";
+import { getTransitionCallbacks } from "../transition/getTransitionCallbacks.js";
+import { type TransitionCallbacks } from "../transition/types.js";
 import {
   type NonNullMutableRef,
   type UseStateInitializer,
@@ -302,9 +298,6 @@ export interface ComboboxImplementation<
   getMenuProps: (
     overrides?: ConfigurableComboboxMenuProps
   ) => ComboboxMenuProps<PopupEl>;
-  getTransitionCallbacks: (
-    options: ComboboxTransitionOptions
-  ) => Required<ComboboxTransitionCallbacks>;
 }
 
 /**
@@ -391,6 +384,9 @@ export function useCombobox<
       if (visible) {
         switch (event.key) {
           case "Tab":
+            // do not stop propagation for tab so that shift+tab works correctly in dialogs
+            hide();
+            break;
           case "Escape":
             event.stopPropagation();
             hide();
@@ -435,78 +431,6 @@ export function useCombobox<
     isNegativeOneAllowed,
     getDefaultFocusedIndex,
   });
-  const getTransitionCallbacks = (
-    options: ComboboxTransitionOptions = {}
-  ): Required<ComboboxTransitionCallbacks> => {
-    const { onEntered, onEntering, onExiting, onExited, disableTransition } =
-      options;
-
-    const handleEntering =
-      (callback: TransitionEnterHandler = noop, skipped: boolean) =>
-      (appearing: boolean) => {
-        callback(appearing);
-
-        const popup = popupRef.current;
-        if (!popup || skipped) {
-          // Chrome does not trigger the scrollIntoView behavior correctly while
-          // using a scale transition, so need to trigger this on the entered
-          // flow to really make sure the item is in view.
-          // An alternative would be to implement a custom scrollIntoView
-          // behavior again like the previous versions of react-md, but this is
-          // less lines of code
-          const activeOption = document.getElementById(activeDescendantId);
-          if (activeOption) {
-            activeOption.scrollIntoView({ block: "nearest" });
-          }
-          return;
-        }
-
-        const focusables = getFocusableElements(popup, true);
-        const index = getEnterDefaultFocusedIndex({
-          focusLast: focusLast.current,
-          focusables,
-          currentFocusIndex: currentFocusIndex.current,
-        });
-        focusLast.current = false;
-        currentFocusIndex.current = index;
-
-        const option = focusables[index];
-        if (!option) {
-          return;
-        }
-
-        onFocusChange({
-          index,
-          element: option,
-        });
-
-        option.scrollIntoView({ block: "nearest" });
-        setActiveDescendantId(option.id || "");
-      };
-    const handleExiting =
-      (callback: TransitionExitHandler = noop, skipped: boolean) =>
-      (): void => {
-        callback();
-
-        if (!skipped) {
-          // since the menu is unmounted or set to hidden while not visible, need
-          // to clear the aria-activedescendant and current focus index when
-          // hiding
-          currentFocusIndex.current = -1;
-          setActiveDescendantId("");
-        }
-      };
-
-    const isTransitionCompleteSkipped =
-      !disableTransition && !TRANSITION_CONFIG.disabled;
-
-    return {
-      onEntering: handleEntering(onEntering, false),
-      onEntered: handleEntering(onEntered, isTransitionCompleteSkipped),
-      onExiting: handleExiting(onExiting, false),
-      onExited: handleExiting(onExited, isTransitionCompleteSkipped),
-    };
-  };
 
   const popupProps: ComboboxWidgetPopupProps<PopupEl> = {
     "aria-multiselectable": multiselect || undefined,
@@ -539,9 +463,59 @@ export function useCombobox<
     currentFocusIndex,
     activeDescendantId,
     setActiveDescendantId,
-    getTransitionCallbacks,
     getMenuProps(props = {}) {
-      const { sheetProps, disableTransition } = props;
+      const {
+        sheetProps,
+        disableTransition,
+        onEnter,
+        onEntering,
+        onEntered = noop,
+        onExited,
+        onExiting,
+        onExit,
+      } = props;
+
+      // Chrome does not trigger the scrollIntoView behavior correctly while
+      // using a scale transition, so need to trigger this on the entered flow
+      // to really make sure the item is in view. An alternative would be to
+      // implement a custom scrollIntoView behavior again like the previous
+      // versions of react-md, but this is less lines of code
+      const attemptScroll = (): void => {
+        const activeOption = document.getElementById(activeDescendantId);
+        if (activeOption) {
+          activeOption.scrollIntoView({ block: "nearest" });
+        }
+      };
+      const onEnterOnce = (): void => {
+        const popup = popupRef.current;
+        if (!popup) {
+          attemptScroll();
+          return;
+        }
+
+        const focusables = getFocusableElements(popup, true);
+        const index = getEnterDefaultFocusedIndex({
+          focusLast: focusLast.current,
+          focusables,
+          currentFocusIndex: currentFocusIndex.current,
+        });
+        focusLast.current = false;
+        currentFocusIndex.current = index;
+
+        const option = focusables[index];
+        if (!option) {
+          return;
+        }
+
+        onFocusChange({
+          index,
+          element: option,
+        });
+
+        option.scrollIntoView({ block: "nearest" });
+        setActiveDescendantId(option.id || "");
+      };
+
       return {
         anchor: BELOW_CENTER_ANCHOR,
         width: "min",
@@ -550,11 +524,31 @@ export function useCombobox<
         ...popupProps,
         visible,
         onRequestClose: hide,
-        ...getTransitionCallbacks(props),
+        ...getTransitionCallbacks({
+          disableTransition,
+          onEnter,
+          onEntered: (appearing) => {
+            onEntered(appearing);
+            attemptScroll();
+          },
+          onEntering,
+          onEnterOnce,
+          onExit,
+          onExiting,
+          onExited,
+          onExitOnce: () => {
+            // since the menu is unmounted or set to hidden while not visible, need
+            // to clear the aria-activedescendant and current focus index when
+            // hiding
+            currentFocusIndex.current = -1;
+            setActiveDescendantId("");
+          },
+        }),
         sheetProps: {
           ...sheetProps,
           ...getTransitionCallbacks({
             ...sheetProps,
+            onEnterOnce,
             disableTransition:
               sheetProps?.disableTransition ?? disableTransition,
           }),

package/src/form/useNumberField.ts

@@ -64,7 +64,8 @@ export interface NumberFieldHookOptions
    *
    * @example Deferring Updates on Blur
    * ```tsx
-   * import { TextField, useNumberField } from "@react-md/core";
+   * import { TextField } from "@react-md/core/form/TextField";
+   * import { useNumberField } from "@react-md/core/form/useNumberField";
    * import type { ReactElement } from "react";
    *
    * function Example(): ReactElement {
@@ -163,7 +164,8 @@ export interface ValidatedNumberFieldImplementation
 /**
  * @example Enforce Number Value and No Error Messages
  * ```tsx
- * import { TextField, useNumberField } from "@react-md/core";
+ * import { TextField } from "@react-md/core/form/TextField";
+ * import { useNumberField } from "@react-md/core/form/useNumberField";
  * import type { ReactElement } from "react";
  *
  * function Example(): ReactElement {
@@ -182,6 +184,7 @@ export interface ValidatedNumberFieldImplementation
  *
  *   return <TextField {...fieldProps} label="Label" />;
  * }
+ * ```
  *
  * @see {@link useTextField}
  * @see {@link useNumberField} overrides for other examples.
@@ -200,7 +203,8 @@ export function useNumberField(
 /**
  * @example No Error Messages
  * ```tsx
- * import { TextField, useNumberField } from "@react-md/core";
+ * import { TextField } from "@react-md/core/form/TextField";
+ * import { useNumberField } from "@react-md/core/form/useNumberField";
  * import type { ReactElement } from "react";
  *
  * function Example(): ReactElement {
@@ -231,7 +235,8 @@ export function useNumberField(
 /**
  * @example Enforce Number Value
  * ```tsx
- * import { TextField, useNumberField } from "@react-md/core";
+ * import { TextField } from "@react-md/core/form/TextField";
+ * import { useNumberField } from "@react-md/core/form/useNumberField";
  * import type { ReactElement } from "react";
  *
  * function Example(): ReactElement {
@@ -253,7 +258,8 @@ export function useNumberField(
  *
  * @example Enforce Number Value and Deferring Updates
  * ```tsx
- * import { TextField, useNumberField } from "@react-md/core";
+ * import { TextField } from "@react-md/core/form/TextField";
+ * import { useNumberField } from "@react-md/core/form/useNumberField";
  * import type { ReactElement } from "react";
  *
  * function Example(): ReactElement {
@@ -292,7 +298,8 @@ export function useNumberField(
  *
  * @example Default Implementation
  * ```tsx
- * import { TextField, useNumberField } from "@react-md/core";
+ * import { TextField } from "@react-md/core/form/TextField";
+ * import { useNumberField } from "@react-md/core/form/useNumberField";
  * import type { ReactElement } from "react";
  *
  * function Example(): ReactElement {
@@ -314,7 +321,8 @@ export function useNumberField(
  *
  * @example Adding Constraints
  * ```tsx
- * import { TextField, useNumberField } from "@react-md/core";
+ * import { TextField } from "@react-md/core/form/TextField";
+ * import { useNumberField } from "@react-md/core/form/useNumberField";
  * import type { ReactElement } from "react";
  *
  * function Example(): ReactElement {
@@ -331,6 +339,8 @@ export function useNumberField(
  * ```
  *
  * @see https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/HTML5/Constraint_validation
+ * @see {@link https://next.react-md.dev/components/text-field#number | Number TextField Demos}
+ * @see {@link https://next.react-md.dev/hooks/use-number-field | useNumberField Demos}
  * @see {@link useTextField}
  */
 export function useNumberField(
@@ -339,6 +349,8 @@ export function useNumberField(
 
 /**
  * @internal
+ * @see {@link https://next.react-md.dev/components/text-field#number | Number TextField Demos}
+ * @see {@link https://next.react-md.dev/hooks/use-number-field | useNumberField Demos}
  * @see {@link useTextField}
  * @see {@link useNumberField} overrides for other examples.
  */

package/src/form/useRadioGroup.ts

@@ -148,6 +148,9 @@ export interface CombinedRadioGroupReturnValue<V extends string | number> {
  *   </>
  * );
  * ```
+ *
+ * @see {@link https://next.react-md.dev/components/radio | Radio Demos}
+ * @see {@link https://next.react-md.dev/hooks/use-radio-group | useRadioGroup Demos}
  * @since 6.0.0
  */
 export function useRadioGroup<V extends number>(
@@ -206,6 +209,9 @@ export function useRadioGroup<V extends number>(
  *   </>
  * );
  * ```
+ *
+ * @see {@link https://next.react-md.dev/components/radio | Radio Demos}
+ * @see {@link https://next.react-md.dev/hooks/use-radio-group | useRadioGroup Demos}
  * @since 6.0.0
  */
 export function useRadioGroup<V extends string>(
@@ -248,6 +254,9 @@ export function useRadioGroup<V extends string>(
  *   </>
  * );
  * ```
+ *
+ * @see {@link https://next.react-md.dev/components/radio | Radio Demos}
+ * @see {@link https://next.react-md.dev/hooks/use-radio-group | useRadioGroup Demos}
  * @since 6.0.0
  */
 export function useRadioGroup<V extends string | number>(

package/src/form/useRangeSlider.ts

@@ -37,7 +37,11 @@ export interface RangeSliderImplementation
 /**
  * @example Range Slider Example
  * ```tsx
- * import { Fieldset, Form, Legend, Slider, useRangeSlider } from "@react-md/core";
+ * import { Fieldset } from "@react-md/core/form/Fieldset";
+ * import { Form } from "@react-md/core/form/Form";
+ * import { Legend } from "@react-md/core/form/Legend";
+ * import { Slider } from "@react-md/core/form/Slider";
+ * import { useRangeSlider } from "@react-md/core/form/useRangeSlider";
  * import type { ReactElement } from "react";
  * import { useId } from "react";
  *
@@ -66,6 +70,7 @@ export interface RangeSliderImplementation
  * }
  * ```
  *
+ * @see {@link https://next.react-md.dev/components/slider | Slider Demos}
  * @see The `Slider` component for additional examples.
  * @since 2.5.0
  * @since 6.0.0 Now returns an object instead of an ordered tuple and only

package/src/form/useSlider.ts

@@ -59,7 +59,9 @@ export interface SliderOptions extends SliderValueOptions {
 /**
  * @example Simple Example
  * ```tsx
- * import { Form, Slider, useSlider } from "@react-md/core";
+ * import { Form } from "@react-md/core/form/Form";
+ * import { Slider } from "@react-md/core/form/Slider";
+ * import { useSlider } from "@react-md/core/form/useSlider";
  * import type { ReactElement } from "react";
  *
  * function Example(): ReactElement {
@@ -83,6 +85,7 @@ export interface SliderOptions extends SliderValueOptions {
  * }
  * ```
  *
+ * @see {@link https://next.react-md.dev/components/slider | Slider Demos}
  * @see The `Slider` component for additional examples.
  * @since 2.5.0
  * @since 6.0.0 Now returns an object instead of an ordered tuple and only

package/src/form/useTextField.ts

@@ -184,7 +184,8 @@ export interface TextFieldHookOptions<
    *
    * @example Accessing TextField DOM Node
    * ```tsx
-   * import { TextField, useTextField } from "@react-md/core";
+   * import { TextField } from "@react-md/core/form/TextField";
+   * import { useTextField } from "@react-md/core/form/useTextField";
    * import { useEffect } from "react";
    * import type { ReactElement } from "react";
    *
@@ -360,6 +361,9 @@ export interface ValidatedTextFieldImplementation<
  * ```
  *
  * Look at the other {@link useTextField} override for additional examples.
+ *
+ * @see {@link https://next.react-md.dev/components/text-field | TextField Demos}
+ * @see {@link https://next.react-md.dev/hooks/use-text-field | useTextField Demos}
  */
 export function useTextField<E extends HTMLInputElement | HTMLTextAreaElement>(
   options: TextFieldHookOptions<E> & { disableMessage: true }
@@ -469,6 +473,8 @@ export function useTextField<E extends HTMLInputElement | HTMLTextAreaElement>(
  * }
  * ```
  *
+ * @see {@link https://next.react-md.dev/components/text-field | TextField Demos}
+ * @see {@link https://next.react-md.dev/hooks/use-text-field | useTextField Demos}
  * @see https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/HTML5/Constraint_validation
  * @since 2.5.6
  * @since 6.0.0 This hook returns an object instead of an ordered list. Also
@@ -478,6 +484,11 @@ export function useTextField<E extends HTMLInputElement | HTMLTextAreaElement>(
 export function useTextField<E extends HTMLInputElement | HTMLTextAreaElement>(
   options: TextFieldHookOptions<E>
 ): TextFieldWithMessageImplementation<E>;
+/**
+ * @see {@link https://next.react-md.dev/components/text-field | TextField Demos}
+ * @see {@link https://next.react-md.dev/hooks/use-text-field | useTextField Demos}
+ * @since 6.0.0
+ */
 export function useTextField<E extends HTMLInputElement | HTMLTextAreaElement>(
   options: TextFieldHookOptions<E>
 ): ValidatedTextFieldImplementation<E> {

package/src/form/validation.ts

@@ -42,6 +42,7 @@ export type TextFieldValidationType =
 
 /**
  * @since 2.5.0
+ * @since 6.0.0 Renamed `validateOnChange` to `validationType`
  */
 export interface ErrorMessageOptions extends TextFieldValidationOptions {
   /**

package/src/icon/FontIcon.tsx

@@ -33,6 +33,7 @@ export interface FontIconProps
  * The default is to use the `material-icons` library, but others can be used as
  * well.
  *
+ * @see {@link https://next.react-md.dev/components/icon | Icon Demos}
  * @since 6.0.0 Switched from `<i>` to `<span>` element and removed
  * the `forceSize`/`forceFontSize` props.
  */

package/src/icon/IconRotator.tsx

@@ -45,6 +45,8 @@ export interface IconRotatorProps extends IconRotatorBaseProps {
 /**
  * The `IconRotator` is a simple component that is used to rotate an icon from a
  * one degrees to another.
+ *
+ * @see {@link https://next.react-md.dev/components/icon-rotator | IconRotator Demos}
  */
 export const IconRotator = forwardRef<HTMLSpanElement, IconRotatorProps>(
   function IconRotator(props, ref) {

package/src/icon/MaterialIcon.tsx

@@ -34,6 +34,8 @@ export interface MaterialIconProps
  * <MaterialIcon name="wifi" family="two-tone" dense theme="warning" />
  * ```
  *
+ * @see {@link https://next.react-md.dev/components/icon | Icon Demos}
+ * @see {@link https://next.react-md.dev/components/material-icons|Available Material Icons}
  * @since 6.0.0
  */
 export const MaterialIcon = forwardRef<HTMLSpanElement, MaterialIconProps>(

package/src/icon/MaterialSymbol.tsx

@@ -43,7 +43,7 @@ export interface MaterialSymbolProps
  *
  * @example Simple Example
  * ```tsx
- * import { MaterialSymbol } from "@react-md/core";
+ * import { MaterialSymbol } from "@react-md/core/icon/MaterialSymbol";
  * import type { ReactElement } from "react";
  * import { createRoot } from "react-dom/client";
  *
@@ -63,6 +63,8 @@ export interface MaterialSymbolProps
  * root.render(<App />);
  * ```
  *
+ * @see {@link https://next.react-md.dev/components/icon | Icon Demos}
+ * @see {@link https://next.react-md.dev/components/material-icons|Available Material Icons}
  * @since 6.0.0
  */
 export const MaterialSymbol = forwardRef<HTMLSpanElement, MaterialSymbolProps>(

package/src/icon/SVGIcon.tsx

@@ -76,6 +76,8 @@ export interface SVGIconProps
 /**
  * The `SVGIcon` component is used to render inline SVG icons or SVG icons in a
  * sprite map as an icon.
+ *
+ * @see {@link https://next.react-md.dev/components/icon | Icon Demos}
  */
 export const SVGIcon = forwardRef<SVGSVGElement, SVGIconProps>(
   function SVGIcon(props, ref) {

package/src/icon/TextIconSpacing.tsx

@@ -109,7 +109,8 @@ export interface TextIconSpacingProps {
  *
  * @example Simple Example
  * ```tsx
- * import { TextIconSpacing, FontIcon } from "@react-md/core";
+ * import { FontIcon } from "@react-md/core/icon/FontIcon";
+ * import { TextIconSpacing } from "@react-md/core/icon/TextIconSpacing"
  * import type { ReactElement } from "react";
  *
  * function Example(): ReactElement {
@@ -123,7 +124,8 @@ export interface TextIconSpacingProps {
  *
  * @example Stacked Example
  * ```tsx
- * import { TextIconSpacing, FontIcon } from "@react-md/core";
+ * import { FontIcon } from "@react-md/core/icon/FontIcon";
+ * import { TextIconSpacing } from "@react-md/core/icon/TextIconSpacing"
  * import type { ReactElement } from "react";
  *
  * function Example(): ReactElement {
@@ -134,6 +136,8 @@ export interface TextIconSpacingProps {
  *   );
  * }
  * ```
+ *
+ * @see {@link https://next.react-md.dev/components/text-icon-spacing | TextIconSpacing Demos}
  */
 export function TextIconSpacing(props: TextIconSpacingProps): ReactElement {
   const {

package/src/icon/config.tsx

@@ -173,7 +173,7 @@ export type ConfigurableIconName = keyof ConfigurableIcons;
  *
  * @example Mutating this object
  * ```tsx
- * import { ICON_CONFIG } from "@react-md/core";
+ * import { ICON_CONFIG } from "@react-md/core/icon/config";
  * import ArrowDropDownIcon from "@react-md/material-icons/ArrowDropDownIcon";
  * import ArrowUpwardIcon from "@react-md/material-icons/ArrowUpwardIcon";
  * import CancelIcon from "@react-md/material-icons/CancelIcon";
@@ -244,7 +244,7 @@ export const ICON_CONFIG: ConfiguredIcons = {
  * @example Using SVG Material Icons
  * ```tsx
  * "use client";
- * import { configureIcons } from "@react-md/core";
+ * import { configureIcons } from "@react-md/core/icon/config";
  * import ArrowDropDownIcon from "@react-md/material-icons/ArrowDropDownIcon";
  * import ArrowUpwardIcon from "@react-md/material-icons/ArrowUpwardIcon";
  * import CancelIcon from "@react-md/material-icons/CancelIcon";