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

package/src/tabs/SimpleTabPanels.tsx

@@ -0,0 +1,28 @@
+import { type HTMLAttributes, type ReactNode, forwardRef } from "react";
+
+import { type ProvidedTabPanelsProps } from "./useTabs.js";
+
+/**
+ * @since 6.0.0
+ */
+export interface SimpleTabPanelsProps
+  extends HTMLAttributes<HTMLDivElement>,
+    Omit<ProvidedTabPanelsProps<HTMLDivElement>, "ref"> {
+  children: ReactNode;
+}
+
+/**
+ * This component can be used as a replacement for the `SlideContainer` when
+ * animations are not required for changing the active tab contents.
+ *
+ * This should be normally be used along with the `SimpleTabPanel` component.
+ *
+ * @since 6.0.0
+ */
+export const SimpleTabPanels = forwardRef<HTMLDivElement, SimpleTabPanelsProps>(
+  function SimpleTabPanels(props, ref) {
+    const { direction: _direction, ...remaining } = props;
+
+    return <div ref={ref} {...remaining} />;
+  }
+);

package/src/tabs/Tab.tsx

@@ -1,22 +1,23 @@
 "use client";
+
 import {
   type AnchorHTMLAttributes,
   type ButtonHTMLAttributes,
   type ReactElement,
   type ReactNode,
 } from "react";
+
 import { type ComponentWithRippleProps } from "../interaction/types.js";
 import { useElementInteraction } from "../interaction/useElementInteraction.js";
 import { useHigherContrastChildren } from "../interaction/useHigherContrastChildren.js";
 import { type CustomLinkComponent } from "../link/Link.js";
 import { useKeyboardMovementContext } from "../movement/useKeyboardMovementProvider.js";
 import { useEnsuredId } from "../useEnsuredId.js";
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import { type TabListProps } from "./TabList.js";
 import { tab } from "./tabStyles.js";
-
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 import { type useTabs } from "./useTabs.js";
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-import { type TabListProps } from "./TabList.js";
 
 /**
  * @since 6.0.0

package/src/tabs/TabList.tsx

@@ -1,51 +1,37 @@
 "use client";
+
 import {
+  type HTMLAttributes,
   forwardRef,
   useEffect,
   useRef,
   useState,
-  type HTMLAttributes,
 } from "react";
-import { useAppSize } from "../media-queries/AppSizeProvider.js";
+
 import { KeyboardMovementProvider } from "../movement/useKeyboardMovementProvider.js";
-import { type GetTabListScrollToOptions } from "./getTabListScrollToOptions.js";
 import {
-  TabListScrollButton,
   type BaseTabListScrollButtonProps,
+  TabListScrollButton,
 } from "./TabListScrollButton.js";
-import { tabList, type TabsAlignment } from "./tabListStyles.js";
+import { type GetTabListScrollToOptions } from "./getTabListScrollToOptions.js";
+import { type TabListClassNameOptions, tabList } from "./tabListStyles.js";
+import {
+  type TabListActivationMode,
+  type TabListScrollButtonsBehavior,
+} from "./types.js";
 import { useTabList } from "./useTabList.js";
-
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 import { type useTabs } from "./useTabs.js";
 
 /**
  * @since 6.0.0
  */
-export interface TabListProps extends HTMLAttributes<HTMLDivElement> {
+export interface TabListProps
+  extends HTMLAttributes<HTMLDivElement>,
+    Omit<TabListClassNameOptions, "animate" | "indicator"> {
   activeIndex: number;
   setActiveIndex: (nextActiveIndex: number) => void;
 
-  /**
-   * @defaultValue `"left"`
-   */
-  align?: TabsAlignment;
-
-  /**
-   * @defaultValue `false`
-   */
-  padded?: boolean;
-
-  /**
-   * @defaultValue `false`
-   */
-  vertical?: boolean;
-
-  /**
-   * @defaultValue `false`
-   */
-  inline?: boolean;
-
   /**
    * Set this to `true` to show a scrollbar when the number of tabs cause
    * overflow.
@@ -72,17 +58,15 @@ export interface TabListProps extends HTMLAttributes<HTMLDivElement> {
 
   /**
    * @defaultValue `"manual"`
+   * @see {@link TabListActivationMode}
    */
-  activationMode?: "manual" | "automatic";
+  activationMode?: TabListActivationMode;
 
   /**
-   * Set this to `true` to render buttons that can scroll forwards or backwards
-   * within the tab list if there is overflow **on desktop**. If you want to
-   * display the scroll buttons on mobile as well, set this to `"allow-phone"` .
-   *
    * @defaultValue `false`
+   * @see {@link TabListScrollButtonsBehavior}
    */
-  scrollButtons?: boolean | "allow-phone";
+  scrollButtons?: TabListScrollButtonsBehavior;
 
   /**
    * A convenience prop for the {@link BaseTabListScrollButtonProps.getScrollToOptions}
@@ -152,6 +136,7 @@ export const TabList = forwardRef<HTMLDivElement, TabListProps>(
       vertical = false,
       scrollbar = false,
       scrollButtons = false,
+      fullWidthTabs,
       disableTransition = false,
       transitionDuration = 150,
       getScrollToOptions,
@@ -160,24 +145,25 @@ export const TabList = forwardRef<HTMLDivElement, TabListProps>(
       ...remaining
     } = props;
 
-    const { isPhone } = useAppSize();
-    const showScrollButtons =
-      !!scrollButtons && (scrollButtons === "allow-phone" || !isPhone);
-
-    const { elementProps, movementContext, backwardProps, forwardProps } =
-      useTabList({
-        ref,
-        style,
-        onClick,
-        onFocus,
-        onKeyDown,
-        vertical,
-        activeIndex,
-        setActiveIndex,
-        activationMode,
-        scrollButtons: showScrollButtons,
-        disableTransition,
-      });
+    const {
+      elementProps,
+      movementContext,
+      backwardProps,
+      forwardProps,
+      showScrollButtons,
+    } = useTabList({
+      ref,
+      style,
+      onClick,
+      onFocus,
+      onKeyDown,
+      vertical,
+      activeIndex,
+      setActiveIndex,
+      activationMode,
+      scrollButtons,
+      disableTransition,
+    });
 
     const prevActiveIndex = useRef(activeIndex);
     const [animate, setAnimate] = useState(false);
@@ -212,6 +198,7 @@ export const TabList = forwardRef<HTMLDivElement, TabListProps>(
             vertical,
             scrollbar,
             indicator: !disableTransition,
+            fullWidthTabs,
             className,
           })}
         >

package/src/tabs/TabListScrollButton.tsx

@@ -1,21 +1,23 @@
 "use client";
+
 import {
+  type HTMLAttributes,
   forwardRef,
   useCallback,
   useRef,
   useState,
-  type HTMLAttributes,
 } from "react";
+
 import { Button, type ButtonProps } from "../button/Button.js";
 import { type ButtonClassNameThemeOptions } from "../button/buttonStyles.js";
-import { getIcon } from "../icon/iconConfig.js";
+import { getIcon } from "../icon/config.js";
 import { type PropsWithRef } from "../types.js";
 import { useDir } from "../typography/WritingDirectionProvider.js";
 import { useIntersectionObserver } from "../useIntersectionObserver.js";
 import { applyRef } from "../utils/applyRef.js";
 import {
-  getTabListScrollToOptions,
   type GetTabListScrollToOptions,
+  getTabListScrollToOptions,
 } from "./getTabListScrollToOptions.js";
 import {
   tabListScrollButton,
@@ -84,6 +86,7 @@ export const TabListScrollButton = forwardRef<
   const [disabled, setDisabled] = useState(!forward);
   const nodeRef = useIntersectionObserver({
     root,
+    rootMargin: "1px",
     onUpdate: useCallback(([entry]) => {
       setDisabled(entry.intersectionRatio === 1);
     }, []),

package/src/tabs/tabIndicatorStyles.ts

@@ -1,4 +1,5 @@
 import { cnb } from "cnbuilder";
+
 import { bem } from "../utils/bem.js";
 
 const styles = bem("rmd-tab-indicator");

package/src/tabs/tabListScrollButtonStyles.ts

@@ -1,4 +1,5 @@
 import { cnb } from "cnbuilder";
+
 import { bem } from "../utils/bem.js";
 
 const styles = bem("rmd-tablist-button");

package/src/tabs/tabListStyles.ts

@@ -1,4 +1,5 @@
 import { cnb } from "cnbuilder";
+
 import { bem } from "../utils/bem.js";
 import { tabIndicator } from "./tabIndicatorStyles.js";
 
@@ -14,13 +15,30 @@ export type TabsAlignment = "left" | "center" | "right";
  */
 export interface TabListClassNameOptions {
   className?: string;
+
+  /** @defaultValue `"left"` */
   align?: TabsAlignment;
+
+  /** @defaultValue `false` */
   animate?: boolean;
+
+  /** @defaultValue `false` */
   inline?: boolean;
+
+  /** @defaultValue `false` */
   padded?: boolean;
+
+  /** @defaultValue `false` */
   vertical?: boolean;
+
+  /** @defaultValue `false` */
   scrollbar?: boolean;
+
+  /** @defaultValue `false` */
   indicator?: boolean;
+
+  /** @defaultValue `false` */
+  fullWidthTabs?: boolean;
 }
 
 /**
@@ -34,8 +52,9 @@ export function tabList(options: TabListClassNameOptions = {}): string {
     inline,
     vertical,
     scrollbar,
-    animate = false,
-    indicator = false,
+    animate,
+    indicator,
+    fullWidthTabs,
   } = options;
 
   return cnb(
@@ -44,6 +63,7 @@ export function tabList(options: TabListClassNameOptions = {}): string {
       padded,
       vertical,
       "full-width": !inline,
+      "full-width-tabs": fullWidthTabs,
       "no-scrollbar": !scrollbar,
     }),
     indicator && tabIndicator({ tablist: true, animate, vertical }),

package/src/tabs/tabStyles.ts

@@ -1,4 +1,5 @@
 import { cnb } from "cnbuilder";
+
 import { cssUtils } from "../cssUtils.js";
 import { bem } from "../utils/bem.js";
 import { tabIndicator } from "./tabIndicatorStyles.js";
@@ -12,6 +13,13 @@ declare module "react" {
 
     "--rmd-tab-size"?: string;
     "--rmd-tab-offset"?: string | number;
+    "--rmd-tab-min-width"?: string;
+    "--rmd-tab-max-width"?: string;
+    "--rmd-tab-min-height"?: string;
+    "--rmd-tab-stacked-height"?: string;
+    "--rmd-tab-stacked-width"?: string;
+    "--rmd-tab-padding"?: string | number;
+    "--rmd-tab-stacked-padding"?: string | number;
     "--rmd-tab-indicator-background"?: string;
   }
 }

package/src/tabs/types.ts

@@ -0,0 +1,30 @@
+/**
+ * Set this to `"automatic"` to make it so focusing tabs with a keyboard
+ * automatically selects them instead of requiring another click. Set this to
+ * `"manual"` if it should require another click before selecting the tab.
+ *
+ * @since 6.0.0
+ */
+export type TabListActivationMode = "manual" | "automatic";
+
+/**
+ * Set this to `true` to always render buttons that can scroll forwards or
+ * backwards (or upwards and downwards while vertical) within the tab list when
+ * there is overflow.
+ *
+ * Set this to `"tablet-or-above"` to only render the buttons when the
+ * app size is at least a tablet's width.
+ *
+ * Set this to `"auto"` to only render the buttons when there is overflow in
+ * the tab list.
+ *
+ * Set this to `"auto-tablet-or-above"` to only render the buttons when there is
+ * overflow in the tab list and the app size is at least a tablet's width
+ *
+ * @since 6.0.0
+ */
+export type TabListScrollButtonsBehavior =
+  | boolean
+  | "tablet-or-above"
+  | "auto"
+  | "auto-tablet-or-above";

package/src/tabs/useMaxTabPanelHeight.ts

@@ -0,0 +1,138 @@
+import { type CSSProperties, type Ref, useCallback, useState } from "react";
+
+import { type UseStateInitializer } from "../types.js";
+import { useResizeObserver } from "../useResizeObserver.js";
+import { DISPLAY_NONE_CLASS } from "../utils/isElementVisible.js";
+import {
+  type ProvidedTabPanelsProps,
+  type TabsImplementation,
+} from "./useTabs.js";
+import { getTabPanelRoleOnly } from "./utils.js";
+
+/**
+ * @since 6.0.0
+ */
+export interface MaxTabPanelHeightOptions<E extends HTMLElement>
+  extends Pick<TabsImplementation, "getTabPanelsProps"> {
+  ref?: Ref<E>;
+  style?: CSSProperties;
+
+  /**
+   * @defaultValue `undefined`
+   */
+  defaultHeight?: UseStateInitializer<string | number>;
+}
+
+/**
+ * @since 6.0.0
+ */
+export interface ProvidedMaxTabPanelsHeightProps<E extends HTMLElement>
+  extends ProvidedTabPanelsProps<E> {
+  style: CSSProperties;
+}
+
+/**
+ * @since 6.0.0
+ */
+export interface MaxTabPanelHeightImplementation<E extends HTMLElement> {
+  getMaxTabPanelHeightProps: (
+    style?: CSSProperties
+  ) => ProvidedMaxTabPanelsHeightProps<E>;
+}
+
+/**
+ * The `useMaxTabPanelHeight` hook can be used to enforce the tab panels to
+ * have the same height so content does not shift below the tab panels by
+ * calculating the height of all tabs and setting the height to the largest
+ * value.
+ *
+ * If a maximum height should be used, set it through CSS and scrollbars will
+ * appear in each tab panel.
+ *
+ * @example Main Usage
+ * ```tsx
+ * import { Tab } from "@react-md/core/tabs/Tab";
+ * import { TabList } from "@react-md/core/tabs/TabList";
+ * import { useMaxTabPanelHeight } from "@react-md/core/tabs/useMaxTabPanelHeight";
+ * import { useTabs } from "@react-md/core/tabs/useTabs";
+ * import { Slide } from "@react-md/core/transition/Slide";
+ * import { SlideContainer } from "@react-md/core/transition/SlideContainer";
+ * import { Typography } from "@react-md/core/typography/Typography";
+ * import { type ReactElement } from "react";
+ *
+ * function Example(): ReactElement {
+ *   const { getTabProps, getTabListProps, getTabPanelProps, getTabPanelsProps } =
+ *     useTabs();
+ *   const { getMaxTabPanelHeightProps } = useMaxTabPanelHeight({
+ *     getTabPanelsProps,
+ *   });
+ *
+ *   return (
+ *     <>
+ *       <TabList {...getTabListProps()}>
+ *         <Tab {...getTabProps(0)}>Tab 1</Tab>
+ *         <Tab {...getTabProps(1)}>Tab 2</Tab>
+ *         <Tab {...getTabProps(2)}>Tab 3</Tab>
+ *       </TabList>
+ *       <SlideContainer {...getMaxTabPanelHeightProps()}>
+ *         <Slide {...getTabPanelProps(0)}>
+ *           <Tab1Content />
+ *         </Slide>
+ *         <Slide {...getTabPanelProps(1)}>
+ *           <Tab2Content />
+ *         </Slide>
+ *         <Slide {...getTabPanelProps(2)}>
+ *           <Tab3Content />
+ *         </Slide>
+ *       </SlideContainer>
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * NOTE: This will **not work** when dynamically rendering the active tab panel
+ * by enabling the `temporary` prop on the `Slide` or custom behavior.
+ *
+ * @since 6.0.0
+ */
+export function useMaxTabPanelHeight<E extends HTMLElement = HTMLDivElement>(
+  options: MaxTabPanelHeightOptions<E>
+): MaxTabPanelHeightImplementation<E> {
+  const { ref, style, defaultHeight, getTabPanelsProps } = options;
+
+  const [height, setHeight] = useState(defaultHeight);
+  const panelRef = useResizeObserver({
+    ref,
+    onUpdate: useCallback((entry) => {
+      const element = entry.target as HTMLElement;
+      const { height } = element.style;
+      element.style.height = "";
+      const panels = getTabPanelRoleOnly(element);
+      const maxHeight = panels.reduce((maxHeight, panel) => {
+        let { scrollHeight } = panel;
+        if (panel.classList.contains(DISPLAY_NONE_CLASS)) {
+          panel.classList.toggle(DISPLAY_NONE_CLASS);
+          ({ scrollHeight } = panel);
+          panel.classList.toggle(DISPLAY_NONE_CLASS);
+        }
+
+        return Math.max(maxHeight, scrollHeight);
+      }, 0);
+      element.style.height = height;
+
+      // don't set the height to 0 since it usually means a calculation issue
+      setHeight((prevHeight) => (maxHeight <= 0 ? prevHeight : maxHeight));
+    }, []),
+  });
+
+  return {
+    getMaxTabPanelHeightProps: (moreStyle) => ({
+      ...getTabPanelsProps(panelRef),
+      style: {
+        height,
+        ...style,
+        ...moreStyle,
+      },
+    }),
+  };
+}

package/src/tabs/useTabList.ts

@@ -1,4 +1,5 @@
 "use client";
+
 import type {
   CSSProperties,
   FocusEventHandler,
@@ -8,6 +9,8 @@ import type {
   RefObject,
 } from "react";
 import { useCallback, useEffect, useRef, useState } from "react";
+
+import { useAppSize } from "../media-queries/AppSizeProvider.js";
 import type {
   KeyboardMovementContext,
   KeyboardMovementProps,
@@ -16,6 +19,10 @@ import { useKeyboardMovementProvider } from "../movement/useKeyboardMovementProv
 import { useDir } from "../typography/WritingDirectionProvider.js";
 import { useEnsuredRef } from "../useEnsuredRef.js";
 import { useResizeObserver } from "../useResizeObserver.js";
+import {
+  type TabListActivationMode,
+  type TabListScrollButtonsBehavior,
+} from "./types.js";
 import { getTabRoleOnly, scrollTabIntoView } from "./utils.js";
 
 const TAB_SIZE_VAR = "--rmd-tab-size";
@@ -36,8 +43,8 @@ export interface TabListHookOptions {
   style: CSSProperties | undefined;
   activeIndex: number;
   setActiveIndex: (nextActiveIndex: number) => void;
-  scrollButtons: boolean;
-  activationMode: "manual" | "automatic";
+  scrollButtons: TabListScrollButtonsBehavior;
+  activationMode: TabListActivationMode;
   vertical: boolean;
   onClick: MouseEventHandler<HTMLDivElement> | undefined;
   onFocus: FocusEventHandler<HTMLDivElement> | undefined;
@@ -65,6 +72,7 @@ export interface TabListHookReturnValue {
     vertical: boolean;
     disableTransition?: boolean;
   };
+  showScrollButtons: boolean;
 }
 
 /**
@@ -88,6 +96,15 @@ export function useTabList(
   } = options;
 
   const isRTL = useDir().dir === "rtl";
+  const { isPhone } = useAppSize();
+  const isScrollObserverEnabled =
+    scrollButtons === "auto" ||
+    (scrollButtons === "auto-tablet-or-above" && !isPhone);
+  const [autoScrollButtons, setAutoScrollButtons] = useState(false);
+  const showScrollButtons =
+    scrollButtons === true ||
+    (scrollButtons === "tablet-or-above" && !isPhone) ||
+    (isScrollObserverEnabled && autoScrollButtons);
 
   const [indicatorStyles, setIndicatorStyles] =
     useState<IndicatorCSSProperties>(() => {
@@ -101,17 +118,28 @@ export function useTabList(
   const [nodeRef, ref] = useEnsuredRef(propRef);
   const tabListRef = useResizeObserver({
     ref,
-    disabled: disableTransition,
+    disabled: disableTransition && !isScrollObserverEnabled,
+    disableHeight: disableTransition && !isScrollObserverEnabled && !vertical,
+    disableWidth: disableTransition && !isScrollObserverEnabled && vertical,
     onUpdate: useCallback(
       (entry) => {
-        // this is kind of hacky -- the styles should update when switching between
-        // RTL, but the RTL state isn't required for any styles. Just reference it
-        // so that the hooks eslint rule doesn't show a warning...
+        // this is kind of hacky -- the styles should update when switching
+        // between RTL or when the scroll buttons appear, but they aren't
+        // required for any styles. Just reference them so that the hooks
+        // eslint rule doesn't show a warning...
         // eslint-disable-next-line @typescript-eslint/no-unused-expressions
         isRTL;
+        // eslint-disable-next-line @typescript-eslint/no-unused-expressions
+        showScrollButtons;
+
+        if (isScrollObserverEnabled && nodeRef.current) {
+          setAutoScrollButtons(
+            nodeRef.current.scrollWidth > nodeRef.current.offsetWidth
+          );
+        }
 
         const activeTab = getTabRoleOnly(entry.target)[activeIndex];
-        if (!activeTab) {
+        if (!activeTab || disableTransition) {
           return;
         }
 
@@ -134,7 +162,15 @@ export function useTabList(
           return cssVars;
         });
       },
-      [activeIndex, isRTL, vertical]
+      [
+        activeIndex,
+        disableTransition,
+        isRTL,
+        isScrollObserverEnabled,
+        nodeRef,
+        showScrollButtons,
+        vertical,
+      ]
     ),
   });
   const forwardRef = useRef<HTMLDivElement>(null);
@@ -210,5 +246,6 @@ export function useTabList(
       disableTransition,
     },
     movementContext,
+    showScrollButtons,
   };
 }