@react-md/core 1.0.0-next.1 → 1.0.0-next.10

package/src/tooltip/useTooltip.ts

@@ -96,21 +96,23 @@ export interface TooltipPositioningOptions {
  * \@since 2.8.0
  * \@since 6.0.0 Removed the `TooltipTouchEventHandlers` and
  * `TooltipKeyboardEventHandlers` types, removed the need for the `onKeyDown`
- * event, and infer element typeparam while calling instead of at hook level.
+ * event.
  */
-export interface TooltippedElementEventHandlers {
-  onBlur?<E extends HTMLElement>(event: FocusEvent<E>): void;
-  onFocus?<E extends HTMLElement>(event: FocusEvent<E>): void;
-  onMouseEnter?<E extends HTMLElement>(event: MouseEvent<E>): void;
-  onMouseLeave?<E extends HTMLElement>(event: MouseEvent<E>): void;
-  onTouchStart?<E extends HTMLElement>(event: TouchEvent<E>): void;
-  onTouchEnd?<E extends HTMLElement>(event: TouchEvent<E>): void;
-  onContextMenu?<E extends HTMLElement>(event: MouseEvent<E>): void;
+export interface TooltippedElementEventHandlers<
+  E extends HTMLElement = HTMLButtonElement,
+> {
+  onBlur?(event: FocusEvent<E>): void;
+  onFocus?(event: FocusEvent<E>): void;
+  onMouseEnter?(event: MouseEvent<E>): void;
+  onMouseLeave?(event: MouseEvent<E>): void;
+  onTouchStart?(event: TouchEvent<E>): void;
+  onTouchEnd?(event: TouchEvent<E>): void;
+  onContextMenu?(event: MouseEvent<E>): void;
 }
 
 /** @remarks \@since 2.8.0 */
-export interface ProvidedTooltippedElementProps
-  extends Required<TooltippedElementEventHandlers> {
+export interface ProvidedTooltippedElementProps<E extends HTMLElement>
+  extends Required<TooltippedElementEventHandlers<E>> {
   "aria-describedby": string | undefined;
   id: string;
 }
@@ -123,9 +125,10 @@ export interface ProvidedTooltippedElementProps
  * `TooltipHookOptions` to `TooltipOptions` to match other hook naming
  * conventions.
  */
-export interface TooltipOptions
-  extends FixedPositioningTransitionCallbacks,
-    TooltippedElementEventHandlers,
+export interface TooltipOptions<
+  TooltippedElement extends HTMLElement = HTMLButtonElement,
+> extends FixedPositioningTransitionCallbacks,
+    TooltippedElementEventHandlers<TooltippedElement>,
     TooltipPositioningOptions,
     TooltipPositionHookOptions {
   /**
@@ -255,13 +258,14 @@ export interface ProvidedTooltipProps<E extends HTMLElement = HTMLSpanElement>
  * naming conventions.
  */
 export interface TooltipImplementation<
+  TooltippedElement extends HTMLElement = HTMLButtonElement,
   TooltipElement extends HTMLElement = HTMLSpanElement,
 > extends ControlledHoverModeImplementation {
   visible: boolean;
   setVisible: UseStateSetter<boolean>;
   animatedOnce: boolean;
   initiatedBy: MutableRefObject<UserInteractionMode | null>;
-  elementProps: ProvidedTooltippedElementProps;
+  elementProps: ProvidedTooltippedElementProps<TooltippedElement>;
   tooltipProps: ProvidedTooltipProps<TooltipElement>;
 
   /**
@@ -367,8 +371,11 @@ export interface TooltipImplementation<
  * stay visible
  */
 export function useTooltip<
+  TooltippedElement extends HTMLElement = HTMLButtonElement,
   TooltipElement extends HTMLElement = HTMLSpanElement,
->(options: TooltipOptions = {}): TooltipImplementation<TooltipElement> {
+>(
+  options: TooltipOptions<TooltippedElement> = {}
+): TooltipImplementation<TooltippedElement, TooltipElement> {
   const {
     id: propId,
     style: propStyle,

package/src/transition/SkeletonPlaceholder.tsx

@@ -1,5 +1,10 @@
 "use client";
-import { type HTMLAttributes, type ReactElement, type ReactNode } from "react";
+import {
+  forwardRef,
+  type HTMLAttributes,
+  type ReactElement,
+  type ReactNode,
+} from "react";
 import {
   useSkeletonPlaceholder,
   type SkeletonPlaceholderOptions,
@@ -132,9 +137,10 @@ export interface SkeletonPlaceholderProps
  *
  * @remarks \@since 6.0.0
  */
-export function SkeletonPlaceholder(
-  props: SkeletonPlaceholderProps
-): ReactElement {
+export const SkeletonPlaceholder = forwardRef<
+  HTMLDivElement,
+  SkeletonPlaceholderProps
+>(function SkeletonPlaceholder(props, ref): ReactElement {
   const {
     style,
     className,
@@ -142,6 +148,9 @@ export function SkeletonPlaceholder(
     width,
     children,
     disabled = !!children,
+    delay,
+    minDelay,
+    maxDelay,
     minPercentage,
     maxPercentage,
     ...remaining
@@ -152,13 +161,16 @@ export function SkeletonPlaceholder(
     className,
     height,
     width,
+    delay,
+    minDelay,
+    maxDelay,
     minPercentage,
     maxPercentage,
   });
 
   return (
-    <div {...remaining} {...skeleton}>
+    <div {...remaining} ref={ref} {...skeleton}>
       {children}
     </div>
   );
-}
+});

package/src/transition/__tests__/SkeletonPlaceholder.tsx

@@ -0,0 +1,72 @@
+import { describe, expect, it } from "@jest/globals";
+import { createRef, type ReactElement } from "react";
+import { render, rmdRender, screen } from "../../test-utils/index.js";
+import { type NonNullMutableRef } from "../../types.js";
+import { SkeletonPlaceholder } from "../SkeletonPlaceholder.js";
+import {
+  useSkeletonPlaceholder,
+  type SkeletonPlaceholderStylingProps,
+} from "../useSkeletonPlaceholder.js";
+
+describe("SkeletonPlaceholder", () => {
+  it("should apply the correct styling, HTMLAttributes, and allow a ref", () => {
+    const ref = createRef<HTMLDivElement>();
+    const props = {
+      "data-testid": "placeholder",
+      ref,
+      delay: "0ms",
+      width: "405",
+    } as const;
+
+    const { rerender } = render(<SkeletonPlaceholder {...props} />);
+
+    const element = screen.getByTestId("placeholder");
+    expect(ref.current).toBeInstanceOf(HTMLDivElement);
+    expect(ref.current).toBe(element);
+    expect(element).toMatchSnapshot();
+
+    rerender(
+      <SkeletonPlaceholder
+        {...props}
+        style={{ color: "white" }}
+        className="custom-class-name"
+      />
+    );
+    expect(element).toMatchSnapshot();
+  });
+
+  it("should support disabling the random values by enabling the disabled prop", () => {
+    render(<SkeletonPlaceholder disabled data-testid="placeholder" />);
+    const placeholder = screen.getByTestId("placeholder");
+
+    expect(placeholder).not.toHaveClass("rmd-skeleton-placeholder");
+    expect(placeholder).toMatchSnapshot();
+  });
+
+  it("should generate random styles on the client only when ssr is enabled", () => {
+    const renderCount: NonNullMutableRef<number> = { current: 0 };
+    const generatedProps: NonNullMutableRef<SkeletonPlaceholderStylingProps[]> =
+      {
+        current: [],
+      };
+
+    function Test(): ReactElement {
+      renderCount.current++;
+
+      const skeleton = useSkeletonPlaceholder();
+      generatedProps.current.push(skeleton);
+      return <div {...skeleton} />;
+    }
+
+    rmdRender(<Test />, { rmdConfig: { ssr: true } });
+    expect(renderCount.current).toBe(2);
+    expect(generatedProps.current.length).toBe(2);
+    const [ssrProps, clientProps] = generatedProps.current;
+
+    expect(ssrProps.style).toBe(undefined);
+    expect(clientProps.style).toMatchObject({
+      animationDelay: expect.any(String),
+      width: expect.any(String),
+    });
+  });
+});

package/src/transition/__tests__/__snapshots__/SkeletonPlaceholder.tsx.snap

@@ -0,0 +1,24 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`SkeletonPlaceholder should apply the correct styling, HTMLAttributes, and allow a ref 1`] = `
+<div
+  class="rmd-skeleton-placeholder"
+  data-testid="placeholder"
+  style="animation-delay: 0ms;"
+/>
+`;
+
+exports[`SkeletonPlaceholder should apply the correct styling, HTMLAttributes, and allow a ref 2`] = `
+<div
+  class="custom-class-name rmd-skeleton-placeholder"
+  data-testid="placeholder"
+  style="animation-delay: 0ms; color: white;"
+/>
+`;
+
+exports[`SkeletonPlaceholder should support disabling the random values by enabling the disabled prop 1`] = `
+<div
+  class=""
+  data-testid="placeholder"
+/>
+`;

package/src/transition/__tests__/utils.ts

@@ -175,6 +175,31 @@ describe("getElementSizing", () => {
     expect(getComputedStyle).toHaveBeenCalledWith(clone);
     expect(removeChild).toHaveBeenCalledWith(clone);
   });
+
+  it("should add the paddingTop and paddingBottom to the maxHeight when `box-sizing: content-box` has been set", () => {
+    const scrollHeight = 1000;
+    const paddingTop = 20;
+    const paddingBottom = 16;
+    const container = document.createElement("div");
+    const element = document.createElement("div");
+    const clone = document.createElement("div");
+    container.appendChild(element);
+
+    jest.spyOn(clone, "scrollHeight", "get").mockReturnValue(scrollHeight);
+    jest.spyOn(element, "cloneNode").mockReturnValue(clone);
+    jest.spyOn(window, "getComputedStyle").mockReturnValue({
+      ...document.body.style,
+      paddingTop: "20px",
+      paddingBottom: "16px",
+      boxSizing: "content-box",
+    });
+
+    expect(getElementSizing(element)).toEqual({
+      maxHeight: scrollHeight + paddingTop + paddingBottom,
+      paddingTop,
+      paddingBottom,
+    });
+  });
 });
 
 describe("getTransitionClassNames", () => {

package/src/transition/_transition.scss

@@ -4,14 +4,14 @@
 @use "../theme/colors";
 @use "../theme/theme";
 
-$disable-everything: false !default;
-$disable-collapse-transition: $disable-everything !default;
-$disable-cross-fade-transition: $disable-everything !default;
-$disable-scale-transition: $disable-everything !default;
+$disable-transitions: false !default;
+$disable-collapse-transition: $disable-transitions !default;
+$disable-cross-fade-transition: $disable-transitions !default;
+$disable-scale-transition: $disable-transitions !default;
 $disable-scale-y-transition: $disable-scale-transition !default;
-$disable-skeleton-placeholder: $disable-everything !default;
-$disable-slide-transition: $disable-everything !default;
-$disable-max-width-transition: $disable-everything !default;
+$disable-skeleton-placeholder: $disable-transitions !default;
+$disable-slide-transition: $disable-transitions !default;
+$disable-max-width-transition: $disable-transitions !default;
 $disable-max-width-transition-gap: $disable-max-width-transition !default;
 
 $linear-duration: 0.15s !default;
@@ -32,6 +32,7 @@ $scale-y-transition-enter-duration: $enter-duration !default;
 $scale-y-transition-leave-duration: $leave-duration !default;
 
 $skeleton-placeholder-height: 1.125em !default;
+$skeleton-placeholder-width: 43% !default;
 $skeleton-placeholder-border-radius: 0.25rem !default;
 $skeleton-placeholder-light-background-color: #000 !default;
 $skeleton-placeholder-dark-background-color: colors.$grey-300 !default;
@@ -64,52 +65,28 @@ $max-width-transition-duration: $linear-duration !default;
 $max-width-transition-timing-function: $linear-timing-function !default;
 $max-width-transition-default: 100% !default;
 
-$transition-var-lookup: (
-  skeleton-placeholder-background-color: (
-    var: --rmd-skeleton-placeholder-background-color,
-    value: $skeleton-placeholder-background-color,
-  ),
-  skeleton-placeholder-height: (
-    var: --rmd-skeleton-placeholder-height,
-    value: $skeleton-placeholder-height,
-  ),
-  skeleton-placeholder-width: (
-    var: --rmd-skeleton-placeholder-width,
-    value: null,
-  ),
-  slide-duration: (
-    var: --rmd-slide-duration,
-    value: $slide-duration,
-  ),
-  max-width: (
-    var: --rmd-max-width,
-    value: $max-width-transition-default,
-  ),
-  max-width-gap: (
-    var: --rmd-max-width-gap,
-    value: 0,
-  ),
+$transition-variables: (
+  skeleton-placeholder-background-color,
+  skeleton-placeholder-height,
+  skeleton-placeholder-width,
+  slide-duration,
+  max-width,
+  max-width-gap
 );
 
 @function transition-get-var($name, $fallback: null) {
-  $found: utils.validate($transition-var-lookup, $name, "transition var");
-  $var: map.get($found, var);
-  $value: if($fallback, $fallback, map.get($found, value));
-
-  @if $value {
-    @return var(#{$var}, #{$value});
+  $var: utils.get-var-name($transition-variables, $name, "transition");
+  @if $fallback {
+    @return var(#{$var}, #{$fallback});
   }
 
   @return var(#{$var});
 }
 
 @mixin transition-set-var($name, $value) {
-  $var: map.get(
-    utils.validate($transition-var-lookup, $name, "transition var"),
-    var
-  );
-
-  #{$var}: #{$value};
+  @if $value {
+    #{utils.get-var-name($transition-variables, $name, "transition")}: #{$value};
+  }
 }
 
 @mixin transition-use-var($property, $name: $property, $fallback: null) {
@@ -241,6 +218,10 @@ $transition-var-lookup: (
       $skeleton-placeholder-animation-timing-function infinite;
     border-radius: $skeleton-placeholder-border-radius;
     color: transparent;
+
+    // this was added so that at least _something_ renders on SSR. It would be
+    // nice to have SSR-safe random numbers for this.
+    width: $skeleton-placeholder-width;
   }
 
   @include keyframes(rmd-skeleton-placeholder) {
@@ -301,53 +282,83 @@ $transition-var-lookup: (
   }
 }
 
-@mixin transition-styles {
-  @if not $disable-collapse-transition {
-    @include collapse-transition;
+@mixin transition-variables {
+  @if not $disable-skeleton-placeholder {
+    @include transition-set-var(
+      skeleton-placeholder-background-color,
+      $skeleton-placeholder-background-color
+    );
+    @include transition-set-var(
+      skeleton-placeholder-height,
+      $skeleton-placeholder-height
+    );
   }
 
-  @if not $disable-cross-fade-transition {
-    @include cross-fade-transition;
+  @if not $disable-slide-transition {
+    @include transition-set-var(slide-duration, $slide-duration);
   }
 
-  @if not $disable-scale-transition or not $disable-scale-y-transition {
-    @include scale-transition;
-  }
+  @if not $disable-max-width-transition {
+    @include transition-set-var(max-width, $max-width-transition-default);
 
-  @if not $disable-scale-y-transition {
-    @include scale-y-transition;
+    @if not $disable-max-width-transition-gap {
+      @include transition-set-var(max-width-gap, 0);
+    }
   }
+}
 
-  @if not $disable-skeleton-placeholder {
-    @include skeleton-placeholder-animation;
-  }
+@mixin transition-styles($disable-layer: false) {
+  @include utils.optional-layer(
+    transition,
+    $disable-layer or $disable-transitions
+  ) {
+    @if not $disable-collapse-transition {
+      @include collapse-transition;
+    }
 
-  @if not $disable-slide-transition {
-    @include slide-transition;
-  }
+    @if not $disable-cross-fade-transition {
+      @include cross-fade-transition;
+    }
 
-  @if not $disable-max-width-transition {
-    .rmd-max-width-transition {
-      @if not $disable-max-width-transition-gap {
-        @include utils.auto-rtl(
-          margin-right,
-          utils.negate-var(transition-get-var(max-width-gap)),
-          0
-        );
-      }
+    @if not $disable-scale-transition or not $disable-scale-y-transition {
+      @include scale-transition;
+    }
 
-      max-width: 0;
-      overflow: hidden;
-      transition: max-width
-        $max-width-transition-duration
-        $max-width-transition-timing-function;
-      will-change: max-width;
+    @if not $disable-scale-y-transition {
+      @include scale-y-transition;
+    }
+
+    @if not $disable-skeleton-placeholder {
+      @include skeleton-placeholder-animation;
+    }
+
+    @if not $disable-slide-transition {
+      @include slide-transition;
+    }
 
-      &--visible {
+    @if not $disable-max-width-transition {
+      .rmd-max-width-transition {
         @if not $disable-max-width-transition-gap {
-          @include utils.auto-rtl(margin-right, 0);
+          @include utils.auto-rtl(
+            margin-right,
+            utils.negate-var(transition-get-var(max-width-gap)),
+            0
+          );
+        }
+
+        max-width: 0;
+        overflow: hidden;
+        transition: max-width
+          $max-width-transition-duration
+          $max-width-transition-timing-function;
+        will-change: max-width;
+
+        &--visible {
+          @if not $disable-max-width-transition-gap {
+            @include utils.auto-rtl(margin-right, 0);
+          }
+          @include transition-use-var(max-width);
         }
-        @include transition-use-var(max-width);
       }
     }
   }

package/src/transition/skeletonPlaceholderUtils.ts

@@ -0,0 +1,105 @@
+import { type CSSProperties } from "react";
+import { bem } from "../utils/bem.js";
+import { randomInt } from "../utils/randomInt.js";
+
+/**
+ * @remarks \@since 6.0.0
+ */
+export const skeletonPlaceholder = bem("rmd-skeleton-placeholder");
+
+/**
+ * @remarks \@since 6.0.0
+ */
+export interface SkeletonPlaceholderRandomOptions {
+  /**
+   * The minimum `animation-delay` milliseconds allowed in the random generator.
+   * This value should be: `0 <= minDelay < maxDelay`.
+   *
+   * The `animation-delay` will be generated by:
+   * ```ts
+   * const delay = randomInt({
+   *   min: minDelay,
+   *   max: maxDelay,
+   * });
+   *
+   * return {
+   *   animationDelay: `-${delay}ms`,
+   * };
+   * ```
+   *
+   * @defaultValue `0`
+   */
+  minDelay?: number;
+
+  /**
+   * @see {@link minDelay}
+   * @defaultValue `400`
+   */
+  maxDelay?: number;
+
+  /**
+   * The minimum width percentage allowed in the random generator. This value
+   * should be: `0 >= minPercentage < maxPercentage`.
+   *
+   * The `width` will be generated by:
+   * ```ts
+   * const width = randomInt({
+   *   min: minPercentage,
+   *   max: maxPercentage,
+   * });
+   *
+   * return {
+   *   width: `${width}%`,
+   * };
+   * ```
+   * @defaultValue `40`
+   */
+  minPercentage?: number;
+
+  /**
+   * @see {@link minPercentage}
+   * @defaultValue `85`
+   */
+  maxPercentage?: number;
+}
+
+/**
+ * A server-only safe util to generate a random skeleton placeholder.
+ *
+ * @example
+ * ```tsx
+ * import { skeletonPlaceholder, randomSkeletonPlaceholder } from "@react-md/core";
+ * import "server-only";
+ *
+ * export function RandomSkeletonPlaceholder(): ReactElement {
+ *   return
+ *     <div
+ *       style={randomSkeletonPlaceholder()}
+ *       className={skeletonPlaceholder()}
+ *     />
+ *   );
+ * }
+ * ```
+ * @remarks \@since 6.0.0
+ */
+export function randomSkeletonPlaceholder(
+  options: SkeletonPlaceholderRandomOptions = {}
+): CSSProperties {
+  const {
+    minDelay = 0,
+    maxDelay = 400,
+    minPercentage = 40,
+    maxPercentage = 85,
+  } = options;
+
+  return {
+    animationDelay: `-${randomInt({
+      min: minDelay,
+      max: maxDelay,
+    })}ms`,
+    width: `${randomInt({
+      min: minPercentage,
+      max: maxPercentage,
+    })}%`,
+  };
+}

package/src/transition/useCollapseTransition.ts

@@ -19,21 +19,6 @@ const noop = (): void => {
   // do nothing
 };
 
-/**
- * @remarks \@since 2.0.0
- */
-export const DEFAULT_COLLAPSE_MIN_HEIGHT = 0;
-
-/**
- * @remarks \@since 2.0.0
- */
-export const DEFAULT_COLLAPSE_MIN_PADDING_TOP = 0;
-
-/**
- * @remarks \@since 2.0.0
- */
-export const DEFAULT_COLLAPSE_MIN_PADDING_BOTTOM = 0;
-
 /**
  * @remarks \@since 2.0.0
  */
@@ -58,8 +43,7 @@ export interface CollapseConfigurationStyle {
    * are all set to `0` (default), the child will be removed from the DOM while
    * collapsed.
    *
-   * @see {@link DEFAULT_COLLAPSE_MIN_HEIGHT}
-   * @defaultValue `DEFAULT_COLLAPSE_MIN_HEIGHT`
+   * @defaultValue `0`
    */
   minHeight?: number | string;
 
@@ -72,8 +56,7 @@ export interface CollapseConfigurationStyle {
    * are all set to `0` (default), the child will be removed from the DOM while
    * collapsed.
    *
-   * @see {@link DEFAULT_COLLAPSE_MIN_PADDING_TOP}
-   * @defaultValue `DEFAULT_COLLAPSE_MIN_PADDING_TOP`
+   * @defaultValue `0`
    */
   minPaddingTop?: number | string;
 
@@ -86,8 +69,7 @@ export interface CollapseConfigurationStyle {
    * are all set to `0` (default), the child will be removed from the DOM while
    * collapsed.
    *
-   * @see {@link DEFAULT_COLLAPSE_MIN_PADDING_BOTTOM}
-   * @defaultValue `DEFAULT_COLLAPSE_MIN_PADDING_BOTTOM`
+   * @defaultValue `0`
    */
   minPaddingBottom?: number | string;
 }
@@ -307,9 +289,9 @@ export function useCollapseTransition<E extends HTMLElement>(
     className,
     transitionIn,
     timeout = DEFAULT_COLLAPSE_TIMEOUT,
-    minHeight = DEFAULT_COLLAPSE_MIN_HEIGHT,
-    minPaddingTop = DEFAULT_COLLAPSE_MIN_PADDING_TOP,
-    minPaddingBottom = DEFAULT_COLLAPSE_MIN_PADDING_BOTTOM,
+    minHeight = 0,
+    minPaddingTop = 0,
+    minPaddingBottom = 0,
     temporary = minHeight === 0 &&
       minPaddingTop === 0 &&
       minPaddingBottom === 0,