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

package/src/tabs/useTabList.ts

@@ -20,20 +20,20 @@ import { getTabRoleOnly, scrollTabIntoView } from "./utils.js";
 
 declare module "react" {
   interface CSSProperties {
-    "--rmd-tab-width"?: string;
+    "--rmd-tab-size"?: string;
     "--rmd-tab-offset"?: string | number;
     "--rmd-tab-indicator-background"?: string;
   }
 }
 
-const TAB_WIDTH_VAR = "--rmd-tab-width";
+const TAB_SIZE_VAR = "--rmd-tab-size";
 const TAB_OFFSET_VAR = "--rmd-tab-offset";
 
 const noop = (): void => {
   // do nothing
 };
 
-export type TabWidthVar = typeof TAB_WIDTH_VAR;
+export type TabWidthVar = typeof TAB_SIZE_VAR;
 export type TabOffsetVar = typeof TAB_OFFSET_VAR;
 
 export type IndicatorCSSProperties = CSSProperties &
@@ -99,7 +99,7 @@ export function useTabList(
     useState<IndicatorCSSProperties>(() => {
       const tabWidth = `${100 / 3}%`;
       return {
-        [TAB_WIDTH_VAR]: tabWidth,
+        [TAB_SIZE_VAR]: tabWidth,
         [TAB_OFFSET_VAR]: "0px",
       };
     });
@@ -120,15 +120,17 @@ export function useTabList(
           return;
         }
 
+        const size = vertical ? activeTab.offsetHeight : activeTab.offsetWidth;
+        const offset = vertical ? activeTab.offsetTop : activeTab.offsetLeft;
         const cssVars: IndicatorCSSProperties = {
-          [TAB_WIDTH_VAR]: `${activeTab.offsetWidth}px`,
-          [TAB_OFFSET_VAR]: `${activeTab.offsetLeft}px`,
+          [TAB_SIZE_VAR]: `${size}px`,
+          [TAB_OFFSET_VAR]: `${offset}px`,
         };
 
         setIndicatorStyles((prevStyles) => {
           if (
             prevStyles &&
-            prevStyles[TAB_WIDTH_VAR] === cssVars[TAB_WIDTH_VAR] &&
+            prevStyles[TAB_SIZE_VAR] === cssVars[TAB_SIZE_VAR] &&
             prevStyles[TAB_OFFSET_VAR] === cssVars[TAB_OFFSET_VAR]
           ) {
             return prevStyles;
@@ -137,7 +139,7 @@ export function useTabList(
           return cssVars;
         });
       },
-      [activeIndex, isRTL]
+      [activeIndex, isRTL, vertical]
     ),
   });
   const forwardRef = useRef<HTMLDivElement>(null);

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/_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;
@@ -217,6 +218,10 @@ $transition-variables: (
       $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) {

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) {