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

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/_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,6 +282,31 @@ $transition-var-lookup: (
   }
 }
 
+@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-slide-transition {
+    @include transition-set-var(slide-duration, $slide-duration);
+  }
+
+  @if not $disable-max-width-transition {
+    @include transition-set-var(max-width, $max-width-transition-default);
+
+    @if not $disable-max-width-transition-gap {
+      @include transition-set-var(max-width-gap, 0);
+    }
+  }
+}
+
 @mixin transition-styles {
   @if not $disable-collapse-transition {
     @include collapse-transition;

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/useSkeletonPlaceholder.ts

@@ -1,23 +1,28 @@
 "use client";
 import { cnb } from "cnbuilder";
-import type { CSSProperties } from "react";
-import { useEffect, useMemo, useState } from "react";
+import { useEffect, useState, type CSSProperties } from "react";
 import { useSsr } from "../SsrProvider.js";
-import { bem } from "../utils/bem.js";
-import { randomInt } from "../utils/randomInt.js";
-
-export const skeletonPlaceholder = bem("rmd-skeleton-placeholder");
+import {
+  randomSkeletonPlaceholder,
+  skeletonPlaceholder,
+  type SkeletonPlaceholderRandomOptions,
+} from "./skeletonPlaceholderUtils.js";
 
 /** @remarks \@since 6.0.0 */
-export interface SkeletonPlaceholderOptions {
+export interface SkeletonPlaceholderOptions
+  extends SkeletonPlaceholderRandomOptions {
   style?: CSSProperties;
   className?: string;
 
-  /** @defaultValue `40` */
-  minPercentage?: number;
-
-  /** @defaultValue `85` */
-  maxPercentage?: number;
+  /**
+   * Set this to a custom `animation-delay` value (should be in milliseconds).
+   *
+   * @example
+   * ```ts
+   * delay="200ms"
+   * ```
+   */
+  delay?: string;
 
   /**
    * Set this value tp a number or length unit string to set the height with
@@ -209,63 +214,73 @@ export function useSkeletonPlaceholder(
     height,
     width: propWidth,
     disabled = false,
-    minPercentage = 40,
-    maxPercentage = 85,
+    delay: propDelay,
+    minDelay,
+    maxDelay,
+    minPercentage,
+    maxPercentage,
   } = options;
   const ssr = useSsr();
 
-  const [randomPercentage, setRandomPercentage] = useState<string | undefined>(
-    () => {
-      if (
-        typeof window === "undefined" ||
-        ssr ||
-        typeof propWidth !== "undefined"
-      ) {
-        return;
-      }
-
-      return `${randomInt({ min: minPercentage, max: maxPercentage })}%`;
+  const isDefinedWidth = typeof propWidth !== "undefined";
+  const isDefinedDelay = typeof propDelay !== "undefined";
+  const [randomStyles, setRandomStyles] = useState<CSSProperties>(() => {
+    if (typeof window === "undefined" || ssr || disabled) {
+      return {};
     }
-  );
+
+    return randomSkeletonPlaceholder({
+      minDelay,
+      maxDelay,
+      minPercentage,
+      maxPercentage,
+    });
+  });
 
   useEffect(() => {
-    if (!ssr || disabled || typeof propWidth !== "undefined") {
+    if (!ssr || disabled || (isDefinedDelay && isDefinedWidth)) {
       return;
     }
 
-    setRandomPercentage(
-      `${randomInt({ min: minPercentage, max: maxPercentage })}%`
+    setRandomStyles(
+      randomSkeletonPlaceholder({
+        minDelay,
+        maxDelay,
+        minPercentage,
+        maxPercentage,
+      })
     );
-  }, [disabled, maxPercentage, minPercentage, propWidth, ssr]);
-
-  const width = useMemo(() => {
-    if (disabled || typeof propWidth !== "undefined") {
-      return propWidth;
-    }
-
-    if (ssr) {
-      return randomPercentage;
-    }
-
-    return `${randomInt({ min: minPercentage, max: maxPercentage })}%`;
   }, [
     disabled,
+    isDefinedDelay,
+    isDefinedWidth,
+    maxDelay,
     maxPercentage,
+    minDelay,
     minPercentage,
-    propWidth,
-    randomPercentage,
     ssr,
   ]);
 
+  let width = propWidth;
+  let animationDelay = propDelay;
+  if (!disabled) {
+    if (!isDefinedDelay) {
+      ({ animationDelay } = randomStyles);
+    }
+    if (!isDefinedWidth) {
+      ({ width } = randomStyles);
+    }
+  }
+
   let style: CSSProperties | undefined = propStyle;
-  if (
-    (typeof width !== "undefined" && width !== "") ||
-    typeof height !== "undefined"
-  ) {
+  if (!!width || !!animationDelay || typeof height !== "undefined") {
     style = {
       ...style,
       height: height ?? style?.height,
       width: width ?? style?.width,
+      // Note: not including MozAnimationDelay and WebkitAnimationDelay since
+      // they weren't applied when they were set. Probably no longer required?
+      animationDelay: animationDelay ?? style?.animationDelay,
     };
   }
 

package/src/tree/DefaultTreeItemRenderer.tsx

@@ -1,7 +1,11 @@
 import { type ReactElement } from "react";
 import { type RenderRecursiveItemsProps } from "../utils/RenderRecursively.js";
 import { TreeItem } from "./TreeItem.js";
-import { type DefaultTreeItemNode, type TreeItemNode } from "./types.js";
+import {
+  type DefaultTreeItemNode,
+  type TreeData,
+  type TreeItemNode,
+} from "./types.js";
 
 /**
  * **Client Component**
@@ -17,7 +21,7 @@ import { type DefaultTreeItemNode, type TreeItemNode } from "./types.js";
  */
 export function DefaultTreeItemRenderer<
   T extends TreeItemNode = DefaultTreeItemNode,
->(props: RenderRecursiveItemsProps<T>): ReactElement {
+>(props: RenderRecursiveItemsProps<T, TreeData<T>>): ReactElement {
   const { item: _item, parents, children: childItems } = props;
   const item = props.item as DefaultTreeItemNode;
 

package/src/tree/Tree.tsx

@@ -122,11 +122,15 @@ export interface TreeProps<T extends TreeItemNode>
    * @example
    * Custom Tree Item Renderer
    * ```tsx
-   * import type { TreeItemRendererProps } from "@react-md/core";
-   * import { TreeItem, useKeyboardMovementContext, useTreeContext } from "@react-md/core";
+   * import {
+   *   TreeItem,
+   *   useKeyboardMovementContext,
+   *   useTreeContext,
+   *   type RenderRecursiveItemsProps,
+   * } from "@react-md/core";
    * import FolderIcon from "@react-md/material-icons/FolderIcon";
    * import FolderOpenIcon from "@react-md/material-icons/FolderOpenIcon";
-   * import type { ReactElement } from "react";
+   * import { type ReactElement } from "react";
    *
    * export function CustomTreeItem(props: TreeItemRendererProps): ReactElement {
    *   const { item, ...remaining  } = props;
@@ -162,7 +166,7 @@ export interface TreeProps<T extends TreeItemNode>
    * @see {@link DefaultTreeItemRenderer}
    * @defaultValue `DefaultTreeItemRenderer`
    */
-  renderer?: ComponentType<RenderRecursiveItemsProps<T>>;
+  renderer?: ComponentType<RenderRecursiveItemsProps<T, TreeData<T>>>;
 
   /**
    * The link component to use for any tree item nodes that have a `to` or

package/src/tree/TreeItem.tsx

@@ -117,7 +117,7 @@ export function TreeItem(props: TreeItemProps): ReactElement {
     secondaryText,
     secondaryTextProps,
     secondaryTextClassName,
-    threeLines,
+    multiline,
     childItems,
     contentClassName,
     temporaryChildItems,
@@ -237,7 +237,6 @@ export function TreeItem(props: TreeItemProps): ReactElement {
         {...handlers}
         className={treeItemContent({
           link: isLink,
-          padded: depth > 0,
           focused,
           selected,
           disabled,
@@ -247,7 +246,7 @@ export function TreeItem(props: TreeItemProps): ReactElement {
         })}
       >
         <ListItemChildren
-          threeLines={threeLines}
+          multiline={multiline}
           textClassName={textClassName}
           secondaryTextClassName={secondaryTextClassName}
           disableTextChildren={disableTextChildren}
@@ -298,7 +297,7 @@ export function TreeItem(props: TreeItemProps): ReactElement {
         temporary={temporaryChildItems}
         disableTransition={disableTransition}
         {...groupProps}
-        depth={depth - 1}
+        depth={depth + 1}
         collapsed={isLeafNode || !expanded}
       >
         {childItems}

package/src/tree/__tests__/Tree.tsx

@@ -632,7 +632,7 @@ describe("Tree", () => {
       },
     } satisfies TreeData<CustomNode>;
     function CustomRenderer(
-      props: RenderRecursiveItemsProps<CustomNode>
+      props: RenderRecursiveItemsProps<CustomNode, TreeData<CustomNode>>
     ): ReactElement {
       const { item } = props;
       if (item.divider) {