@react-md/core 1.0.0-next.8 → 6.0.0

package/src/positioning/createVerticalPosition.ts

@@ -1,24 +1,24 @@
-import type { YCoordConfig } from "./utils.js";
+import { type FixedPositionOptions, type VerticalPosition } from "./types.js";
 import {
+  type YCoordConfig,
   getAboveCoord,
   getBelowCoord,
   getBottomCoord,
   getCenterYCoord,
   getTopCoord,
 } from "./utils.js";
-import type { FixedPositionOptions, VerticalPosition } from "./types.js";
 
 /** @internal */
 interface YPosition {
   top: number;
   bottom?: number;
   actualY: VerticalPosition;
-  /** @remarks \@since 6.0.0 */
+  /** @since 5.1.6 */
   transformOriginY?: number;
 }
 
 /** @internal */
-export interface FixConfig extends YCoordConfig {
+export interface VerticalFixConfig extends YCoordConfig {
   vhMargin: number;
   screenBottom: number;
   preventOverlap: boolean;
@@ -55,7 +55,7 @@ export interface CreateVerticalPositionOptions
  *
  * @internal
  */
-export function createAnchoredAbove(config: FixConfig): YPosition {
+export function createAnchoredAbove(config: VerticalFixConfig): YPosition {
   const {
     yMargin,
     vhMargin,
@@ -113,7 +113,7 @@ export function createAnchoredAbove(config: FixConfig): YPosition {
  *
  * @internal
  */
-export function createAnchoredTop(config: FixConfig): YPosition {
+export function createAnchoredTop(config: VerticalFixConfig): YPosition {
   const { vhMargin, screenBottom, elHeight, disableSwapping, disableVHBounds } =
     config;
   let top = getTopCoord(config);
@@ -142,7 +142,9 @@ export function createAnchoredTop(config: FixConfig): YPosition {
  *
  * @internal
  */
-export function createAnchoredCenter(config: FixConfig): YPosition {
+export function createAnchoredVerticalCenter(
+  config: VerticalFixConfig
+): YPosition {
   const { vhMargin, screenBottom, elHeight, disableVHBounds } = config;
   let top = getCenterYCoord(config);
   const actualY: VerticalPosition = "center";
@@ -168,7 +170,7 @@ export function createAnchoredCenter(config: FixConfig): YPosition {
  *
  * @internal
  */
-export function createAnchoredBottom(config: FixConfig): YPosition {
+export function createAnchoredBottom(config: VerticalFixConfig): YPosition {
   const { vhMargin, screenBottom, elHeight, disableSwapping, disableVHBounds } =
     config;
   let top = getBottomCoord(config);
@@ -198,7 +200,7 @@ export function createAnchoredBottom(config: FixConfig): YPosition {
  *
  * @internal
  */
-export function createAnchoredBelow(config: FixConfig): YPosition {
+export function createAnchoredBelow(config: VerticalFixConfig): YPosition {
   const {
     yMargin,
     vhMargin,
@@ -277,7 +279,7 @@ export function createVerticalPosition(
     };
   }
 
-  const config: FixConfig = {
+  const config: VerticalFixConfig = {
     vhMargin,
     yMargin,
     elHeight,
@@ -295,7 +297,7 @@ export function createVerticalPosition(
     case "top":
       return createAnchoredTop(config);
     case "center":
-      return createAnchoredCenter(config);
+      return createAnchoredVerticalCenter(config);
     case "bottom":
       return createAnchoredBottom(config);
     case "below":

package/src/positioning/getFixedPosition.ts

@@ -2,7 +2,7 @@ import { getScrollbarWidth } from "../scroll/getScrollbarWidth.js";
 import { BELOW_CENTER_ANCHOR } from "./constants.js";
 import { createHorizontalPosition } from "./createHorizontalPosition.js";
 import { createVerticalPosition } from "./createVerticalPosition.js";
-import type { FixedPosition, FixedPositionOptions } from "./types.js";
+import { type FixedPosition, type FixedPositionOptions } from "./types.js";
 import {
   findSizingContainer,
   getElementRect,
@@ -15,7 +15,7 @@ import {
  * `initialX` and `initialY` options have been provided.
  *
  * @internal
- * @remarks \@since 5.0.0
+ * @since 5.0.0
  */
 const FALLBACK_DOM_RECT: DOMRect = {
   x: 0,

package/src/positioning/types.ts

@@ -90,7 +90,7 @@ export interface InitialCoords {
   initialY?: number;
 }
 
-/** @remarks \@since 4.0.0 */
+/** @since 4.0.0 */
 export interface CalculateFixedPositionOptions extends InitialCoords {
   /**
    * The configuration to anchor the fixed element to the container element.
@@ -158,9 +158,9 @@ export interface CalculateFixedPositionOptions extends InitialCoords {
    * screen.
    *
    * @defaultValue `false`
-   * @remarks \@since 5.0.0 This will always be `true` if the
+   * @since 5.0.0 This will always be `true` if the
    * {@link FixedPositionOptions.container} is `null`.
-   * \@remarks \@since 6.0.0 Allow this to be `false` while the `container` is
+   * @since 5.1.6 Allow this to be `false` while the `container` is
    * null. I can't figure out why I prevented that.
    */
   disableSwapping?: boolean;
@@ -215,7 +215,7 @@ export interface Coords {
  * Note: The fixed element styles **will not** contain styles for `z-index` or
  * `background-color` so you'll need to add that manually.
  *
- * @remarks \@since 4.0.0
+ * @since 4.0.0
  */
 export interface FixedPositionStyle extends Coords {
   /**

package/src/positioning/useFixedPositioning.ts

@@ -1,19 +1,33 @@
 "use client";
-import type { CSSProperties, Ref, RefCallback, RefObject } from "react";
-import { useCallback, useEffect, useRef, useState } from "react";
+
+import {
+  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 { type TransitionCallbacks } from "../transition/types.js";
 import { useEnsuredRef } from "../useEnsuredRef.js";
 import { useIsomorphicLayoutEffect } from "../useIsomorphicLayoutEffect.js";
 import { BELOW_CENTER_ANCHOR } from "./constants.js";
 import { getFixedPosition } from "./getFixedPosition.js";
-import type { CalculateFixedPositionOptions } from "./types.js";
+import {
+  type CalculateFixedPositionOptions,
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  type FixedPositionStyle,
+} from "./types.js";
 import { isWithinViewport } from "./utils.js";
 
 const noop = (): undefined => undefined;
 
 /**
- * @remarks \@since 4.0.0
+ * @since 4.0.0
  */
 export type FixedPositioningTransitionCallbacks = Pick<
   TransitionCallbacks,
@@ -26,7 +40,7 @@ export type FixedPositioningTransitionCallbacks = Pick<
  *
  * @typeParam E - An HTMLElement type used for the ref required for the
  * transition.
- * @remarks \@since 4.0.0
+ * @since 4.0.0
  */
 export interface FixedPositioningTransitionOptions<E extends HTMLElement>
   extends FixedPositioningTransitionCallbacks {
@@ -37,7 +51,7 @@ export interface FixedPositioningTransitionOptions<E extends HTMLElement>
 /**
  * @typeParam FixedToElement - An HTMLElement type for the static element.
  * @typeParam FixedElement - An HTMLElement type for the fixed element.
- * @remarks \@since 4.0.0
+ * @since 4.0.0
  */
 export interface FixedPositioningScrollData<
   FixedToElement extends HTMLElement,
@@ -62,7 +76,7 @@ export interface FixedPositioningScrollData<
  * @param event - The scroll event
  * @param data - The {@link FixedPositioningScrollData} that can be used for
  * custom scroll behavior.
- * @remarks \@since 4.0.0
+ * @since 4.0.0
  */
 export type TransitionScrollCallback<
   FixedToElement extends HTMLElement,
@@ -75,7 +89,7 @@ export type TransitionScrollCallback<
 /**
  * @typeParam FixedToElement - An HTMLElement type for the static element.
  * @typeParam FixedElement - An HTMLElement type for the fixed element.
- * @remarks \@since 4.0.0
+ * @since 4.0.0
  */
 export interface FixedPositioningOptions<
   FixedToElement extends HTMLElement,
@@ -101,7 +115,7 @@ export interface FixedPositioningOptions<
    * some options require the element to be in the DOM for specific
    * calculations.
    */
-  getFixedPositionOptions?(): CalculateFixedPositionOptions;
+  getFixedPositionOptions?: () => CalculateFixedPositionOptions;
 
   /**
    * An optional function to call if the page resizes while the `FixedElement`
@@ -110,13 +124,26 @@ export interface FixedPositioningOptions<
   onResize?: EventListener;
   /** @see {@link TransitionScrollCallback} */
   onScroll?: TransitionScrollCallback<FixedToElement, FixedElement>;
+
+  /**
+   * Set this to `true` to disable the fixed positioning behavior so it can be
+   * customized within CSS or manually instead. This was added mostly to just
+   * support rendering menus inline with other content (like autocompletes
+   * within a dialog).
+   *
+   * @defaultValue `false`
+   * @since 6.0.0
+   */
+  disabled?: boolean;
 }
 
 /**
  * @typeParam E - An HTMLElement type for the fixed element.
- * @remarks \@since 4.0.0
+ * @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.
@@ -127,9 +154,12 @@ export interface FixedPositioningHookReturnValue<E extends HTMLElement> {
   ref: RefCallback<E>;
 
   /**
-   * @see {@link FixedPositionStyle}
+   * This is the {@link FixedPositionStyle} merged with the
+   * {@link FixedPositioningOptions.style}. This will only return `undefined`
+   * when {@link FixedPositioningOptions.disabled} is `true` and no `style` was
+   * provided.
    */
-  style: CSSProperties;
+  style: CSSProperties | undefined;
 
   /**
    * This should really only be used if the {@link transitionOptions} is not
@@ -140,7 +170,7 @@ export interface FixedPositioningHookReturnValue<E extends HTMLElement> {
   /**
    * A function that can be called to update the style for the fixed element.
    */
-  updateStyle(): void;
+  updateStyle: () => void;
 
   /** {@inheritDoc FixedPositioningTransitionOptions} */
   transitionOptions: Readonly<Required<FixedPositioningTransitionOptions<E>>>;
@@ -152,11 +182,14 @@ export interface FixedPositioningHookReturnValue<E extends HTMLElement> {
  * `position: fixed` as if it were `position: absolute` to a parent element that
  * had `position: relative`.
  *
- * @example
- * Simple Example
+ * @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);
@@ -182,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 && (
@@ -198,20 +228,22 @@ export interface FixedPositioningHookReturnValue<E extends HTMLElement> {
  * }
  * ```
  *
+ * @see {@link https://next.react-md.dev/hooks/use-fixed-positioning | useFixedPositioning Demos}
  * @typeParam FixedToElement - An HTMLElement type for the static element.
  * @typeParam FixedElement - An HTMLElement type for the fixed element.
- * @remarks \@since 4.0.0
+ * @since 4.0.0
  */
 export function useFixedPositioning<
   FixedToElement extends HTMLElement,
   FixedElement extends HTMLElement,
 >(
   options: FixedPositioningOptions<FixedToElement, FixedElement>
-): FixedPositioningHookReturnValue<FixedElement> {
+): FixedPositioningImplementation<FixedElement> {
   const {
     style: propStyle,
     nodeRef,
     fixedTo,
+    disabled,
     onEnter = noop,
     onEntering = noop,
     onEntered = noop,
@@ -303,6 +335,10 @@ export function useFixedPositioning<
   );
 
   const updateStyle = useCallback(() => {
+    if (disabled) {
+      return;
+    }
+
     const {
       ref,
       fixedTo,
@@ -341,12 +377,12 @@ export function useFixedPositioning<
     setStyle(style);
     setActive(!!element && !element.hidden);
 
-    // Only changing the initialX and initialY should cause the useEffect below
-    // to trigger, which is why everything else is set in a ref.
-  }, [initialX, initialY]);
+    // Only changing the initialX, initialY, or disabled should cause the
+    // useEffect below to trigger, which is why everything else is set in a ref.
+  }, [disabled, initialX, initialY]);
 
   useEffect(() => {
-    if (!active) {
+    if (!active || disabled) {
       return;
     }
 
@@ -378,13 +414,7 @@ export function useFixedPositioning<
       resizeHandler.remove(resizeCallback);
       scrollHandler.remove(scrollCallback);
     };
-  }, [active, fixedTo, onResize, onScroll, ref, updateStyle]);
-
-  useEffect(() => {
-    if (!ref.current || !ref.current.hidden) {
-      updateStyle();
-    }
-  }, [ref, updateStyle]);
+  }, [active, disabled, fixedTo, onResize, onScroll, ref, updateStyle]);
 
   const callbacks: Required<FixedPositioningTransitionCallbacks> = {
     onEnter(appearing) {
@@ -407,7 +437,7 @@ export function useFixedPositioning<
 
   return {
     ref: refHandler,
-    style: { ...style, ...propStyle },
+    style: disabled ? propStyle : { ...style, ...propStyle },
     callbacks,
     updateStyle,
     transitionOptions: {

package/src/positioning/utils.ts

@@ -1,4 +1,4 @@
-import type { PositionAnchor } from "./types.js";
+import { type PositionAnchor } from "./types.js";
 
 /** @internal */
 export interface XCoordConfig {
@@ -195,7 +195,7 @@ export function getBelowCoord({
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  * @internal
  */
 export interface TransformOriginOptions extends PositionAnchor {
@@ -353,7 +353,7 @@ export function getElementRect(element: HTMLElement): DOMRect {
 }
 
 /**
- * @remarks \@since 4.0.0
+ * @since 4.0.0
  * @internal
  */
 interface IsWithinViewportOptions {
@@ -362,7 +362,7 @@ interface IsWithinViewportOptions {
 }
 
 /**
- * @remarks \@since 4.0.0
+ * @since 4.0.0
  * @internal
  */
 export function isWithinViewport(options: IsWithinViewportOptions): boolean {

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";
@@ -13,11 +14,11 @@ import { getPercentage } from "../utils/getPercentage.js";
 import { type ProgressProps } from "./types.js";
 
 /**
- * @remarks \@since 6.0.0
- * Removed the `determinateRotateDegrees` prop since the determinate state no
+ * @since 6.0.0 Added the `disableShrink` prop.
+ * @since 6.0.0 Renamed `small` to `dense`.
+ * @since 6.0.0 Renamed `centered` to `disableCentered`.
+ * @since 6.0.0 Removed the `maxRotation` prop since the determinate state no
  * longer rotates while increasing value.
- * Added the `disableShrink` prop.
- * Renamed the `small` prop to `dense` to match other components.
  */
 export interface CircularProgressProps
   extends Omit<HTMLAttributes<HTMLSpanElement>, "id">,
@@ -88,6 +89,7 @@ export interface CircularProgressProps
    * margins.
    *
    * @defaultValue `false`
+   * @since 6.0.0 Renamed from `centered`
    */
   disableCentered?: boolean;
 
@@ -95,9 +97,8 @@ export interface CircularProgressProps
    * Set to `true` to render as a smaller size.
    *
    * @defaultValue `false`
-   * @remarks
-   * \@since 2.3.0
-   * \@since 6.0.0 Renamed from `small`
+   * @since 2.3.0
+   * @since 6.0.0 Renamed from `small`
    */
   dense?: boolean;
 
@@ -107,7 +108,7 @@ export interface CircularProgressProps
    * loading spinners are displayed at once on the page.
    *
    * @defaultValue `false`
-   * @remarks \@since 6.0.0
+   * @since 6.0.0
    */
   disableShrink?: boolean;
 }
@@ -115,12 +116,9 @@ export interface CircularProgressProps
 const styles = bem("rmd-circular-progress");
 
 /**
- * **Server Component**
- *
- * @example
- * Indeterminate Example
+ * @example Indeterminate Example
  * ```tsx
- * import { CircularProgress } from "@react-md/core":
+ * import { CircularProgress } from "@react-md/core/progress/CircularProgress":
  * import { type ReactElement } from "react";
  *
  * function Example(): ReactElement {
@@ -128,10 +126,9 @@ const styles = bem("rmd-circular-progress");
  * }
  * ```
  *
- * @example
- * Determinate Example
+ * @example Determinate Example
  * ```tsx
- * import { CircularProgress } from "@react-md/core":
+ * import { CircularProgress } from "@react-md/core/progress/CircularProgress":
  * import { useState, type ReactElement } from "react";
  *
  * function Example(): ReactElement {
@@ -142,7 +139,8 @@ const styles = bem("rmd-circular-progress");
  * }
  * ```
  *
- * @remarks \@since 6.0.0 Updated the determinate circular progress to no longer
+ * @see {@link https://next.react-md.dev/components/progress#circular-progress | Progress Demos}
+ * @since 6.0.0 Updated the determinate circular progress to no longer
  * rotate while increasing the value and require a label for accessibility.
  */
 export const CircularProgress = forwardRef<

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";
@@ -13,7 +14,7 @@ import { getPercentage } from "../utils/getPercentage.js";
 import { type ProgressProps } from "./types.js";
 
 /**
- * @remarks \@since 6.0.0 Added the `theme` prop
+ * @since 6.0.0 Added the `theme` prop
  */
 export interface LinearProgressProps
   extends Omit<HTMLAttributes<HTMLSpanElement>, "id" | "children">,
@@ -63,12 +64,9 @@ export interface LinearProgressProps
 const styles = bem("rmd-linear-progress");
 
 /**
- * **Server Component**
- *
- * @example
- * Indeterminate Example
+ * @example Indeterminate Example
  * ```tsx
- * import { LinearProgress } from "@react-md/core";
+ * import { LinearProgress } from "@react-md/core/progress/LinearProgress";
  * import { type ReactElement } from "react";
  *
  * function Example(): ReactElement {
@@ -76,10 +74,9 @@ const styles = bem("rmd-linear-progress");
  * }
  * ```
  *
- * @example
- * Determinate Example
+ * @example Determinate Example
  * ```tsx
- * import { LinearProgress } from "@react-md/core";
+ * import { LinearProgress } from "@react-md/core/progress/LinearProgress";
  * import { useState, type ReactElement } from "react";
  *
  * function Example(): ReactElement {
@@ -90,7 +87,8 @@ const styles = bem("rmd-linear-progress");
  * }
  * ```
  *
- * @remarks \@since 6.0.0 Supports rendering as any of the theme colors and
+ * @see {@link https://next.react-md.dev/components/progress#linear-progress | Progress Demos}
+ * @since 6.0.0 Supports rendering as any of the theme colors and
  * requires a label for accessibility.
  */
 export const LinearProgress = forwardRef<

package/src/progress/types.ts

@@ -11,14 +11,14 @@ declare module "react" {
 }
 
 /**
- * @remarks \@since 6.0.0
+ * @since 6.0.0
  */
 export type ProgressTheme = ThemeColor | "current-color";
 
 /**
  * The base progress props for both the linear and circular progress components.
  *
- * @remarks \@since 6.0.0 Added the `theme` prop.
+ * @since 6.0.0 Added the `theme` prop.
  */
 export interface ProgressProps {
   /**
@@ -28,8 +28,8 @@ export interface ProgressProps {
    * should also be updated to have `aria-busy="true"` and
    * `aria-describedby="THIS_ID"`.
    *
-   * @defaultValue `"circular-progress-" useId() || "linear-progress-" + useId()`
-   * @remarks \@since 6.0.0 This prop is now optional.
+   * @defaultValue `"circular-progress-" + useId() || "linear-progress-" + useId()`
+   * @since 6.0.0 This prop is now optional.
    */
   id?: string;
 
@@ -65,14 +65,14 @@ export interface ProgressProps {
    * progress updates or the updates happen in chunks.
    *
    * @defaultValue `false`
-   * @remarks \@since 6.0.0 This was renamed from `animate` to
+   * @since 6.0.0 This was renamed from `animate` to
    * `disableTransition`.
    */
   disableTransition?: boolean;
 
   /**
    * @defaultValue `"primary"`
-   * @remarks \@since 6.0.0
+   * @since 6.0.0
    */
   theme?: ProgressTheme;
 }