@react-md/core 1.0.0-next.14 → 1.0.0-next.16

package/src/table/TableHeader.tsx

@@ -1,61 +1,27 @@
 "use client";
-import {
-  forwardRef,
-  useCallback,
-  useMemo,
-  useState,
-  type HTMLAttributes,
-} from "react";
-import { useEnsuredRef } from "../useEnsuredRef.js";
-import { useIntersectionObserver } from "../useIntersectionObserver.js";
-import {
-  TableConfigProvider,
-  useTableConfig,
-  type TableCellConfig,
-  type TableConfigContext,
-} from "./TableConfigurationProvider.js";
-import { useTableContainer } from "./TableContainerProvider.js";
+import { forwardRef, type HTMLAttributes } from "react";
+import { TableConfigProvider } from "./TableConfigurationProvider.js";
 import { tableHeader } from "./tableHeaderStyles.js";
-import {
-  type IsStickyTableSectionActive,
-  type TableStickySectionProps,
-} from "./types.js";
+import { type TableSectionConfiguration } from "./types.js";
+import { useTableSectionConfig } from "./useTableSectionConfig.js";
 
-/**
- * @since 6.0.0
- */
-export const isTableHeaderStickyActive: IsStickyTableSectionActive = (
-  entry
-) => {
-  return (
-    entry.intersectionRatio < 1 &&
-    entry.boundingClientRect.bottom <= window.innerHeight
-  );
-};
-
-/**
- * @since 6.0.0 Added support for "sticky-active" state.
- */
 export interface TableHeaderProps
   extends HTMLAttributes<HTMLTableSectionElement>,
-    Pick<TableCellConfig, "lineWrap">,
-    TableStickySectionProps {
+    TableSectionConfiguration {
   /**
-   * This is a rename of the `disableHover` of the `TableConfig` since table
-   * headers are not hoverable by default. This prop can be enabled to add the
-   * row hover color within table headers, but it is not really recommended.
+   * NOTE: It is recommended to use the `StickyTableSection` component instead
+   * of enabling this prop since it supports dynamically adding styles while the
+   * header covering table rows.
+   *
+   * Set this to `true` to enable the sticky behavior.
    *
    * @defaultValue `false`
    */
-  hoverable?: boolean;
-
-  /** @defaultValue {@link isTableHeaderStickyActive} */
-  isStickyActive?: IsStickyTableSectionActive;
+  sticky?: boolean;
 }
 
 /**
  * **Client Component**
- * TODO: Create separate useStickyTableHeader + StickyTableHeader component
  *
  * Creates a `<thead>` element with some basic styles. This component will also
  * update the table configuration so that all the `TableCell` children will
@@ -68,93 +34,29 @@ export const TableHeader = forwardRef<
   HTMLTableSectionElement,
   TableHeaderProps
 >(function TableHeader(props, propRef) {
-  const {
-    className,
-    hoverable = false,
-    lineWrap: propLineWrap,
-    children,
-    sticky = false,
-    stickyOptions,
-    isStickyActive = isTableHeaderStickyActive,
-    disableStickyStyles = false,
-    stickyActiveClassName,
-    ...remaining
-  } = props;
-
-  // update the table configuration with the custom overrides for the `<thead>`
-  const { dense, hAlign, vAlign, lineWrap, disableHover, disableBorders } =
-    useTableConfig({
-      lineWrap: propLineWrap,
-      disableHover: !hoverable,
-    });
-
-  const configuration = useMemo<TableConfigContext>(
-    () => ({
-      dense,
-      header: true,
-      hAlign,
-      vAlign,
-      lineWrap,
-      disableBorders,
-      disableHover,
-    }),
-    [dense, hAlign, vAlign, lineWrap, disableBorders, disableHover]
-  );
-
-  const [theadRef, theadRefCallback] = useEnsuredRef(propRef);
-  const { exists, containerRef } = useTableContainer();
-  const [stickyActive, setStickyActive] = useState(false);
-  const targetRef = useIntersectionObserver({
-    ref: exists ? undefined : theadRefCallback,
-    root: containerRef,
-    disabled: !sticky || disableStickyStyles,
-    threshold: exists ? 0 : 1,
-    getRootMargin: useCallback(() => {
-      const thead = theadRef.current;
-      if (!thead) {
-        return;
-      }
-
-      let topOffset: number;
-      if (exists) {
-        topOffset = thead.offsetHeight - 1;
-      } else {
-        const top = parseFloat(window.getComputedStyle(thead).top);
-        topOffset = Number.isNaN(top) ? 1 : top + 1;
-      }
+  const { className, sticky, lineWrap, hoverable, children, ...remaining } =
+    props;
 
-      return `-${topOffset}px 0px 0px`;
-    }, [exists, theadRef]),
-    onUpdate: useCallback(
-      ([entry]) => {
-        setStickyActive(isStickyActive(entry, exists));
-      },
-      [exists, isStickyActive]
-    ),
-    // allow the user defined sticky options to override the default behavior
-    ...stickyOptions,
+  const config = useTableSectionConfig({
+    type: "header",
+    lineWrap,
+    hoverable,
   });
+  const { dense } = config;
 
   return (
-    <TableConfigProvider value={configuration}>
+    <TableConfigProvider value={config}>
       <thead
         {...remaining}
-        ref={exists ? theadRefCallback : targetRef}
+        ref={propRef}
         className={tableHeader({
           className,
           dense,
           sticky,
-          stickyActive,
-          stickyActiveClassName,
         })}
       >
         {children}
       </thead>
-      {exists && sticky && !disableStickyStyles && (
-        // rendering a `<tbody>` since it is valid to have 0-many in a table
-        // https://html.spec.whatwg.org/multipage/tables.html#the-table-element
-        <tbody aria-hidden ref={targetRef} />
-      )}
     </TableConfigProvider>
   );
 });

package/src/table/TableRow.tsx

@@ -1,10 +1,8 @@
 "use client";
 import { forwardRef, type HTMLAttributes } from "react";
-import {
-  useTableConfig,
-  type TableRowConfiguration,
-} from "./TableConfigurationProvider.js";
+import { useTableConfig } from "./TableConfigurationProvider.js";
 import { tableRow } from "./tableRowStyles.js";
+import { type TableRowConfiguration } from "./types.js";
 
 export interface TableRowProps
   extends HTMLAttributes<HTMLTableRowElement>,

package/src/table/tableCellStyles.ts

@@ -3,7 +3,7 @@ import { cssUtils } from "../cssUtils.js";
 import {
   type TableCellHorizontalAlignment,
   type TableCellVerticalAlignment,
-} from "./TableConfigurationProvider.js";
+} from "./types.js";
 
 /** @since 6.0.0 */
 export interface TableCellClassNameOptions {

package/src/table/types.ts

@@ -1,7 +1,95 @@
-import type { IntersectionObserverHookOptions } from "../useIntersectionObserver.js";
+import { type IntersectionObserverHookOptions } from "../useIntersectionObserver.js";
+
+export type SortOrder = "ascending" | "descending" | "none" | "other";
+
+// interfaces that are "public" should be the full word `Configuration` while
+// the private/internal should just be `Config`. "Great" naming convention!
+
+export interface TableRowConfiguration {
+  /**
+   * Set to `true` if rows should no longer change background color while
+   * hovered.
+   *
+   * @defaultValue `false`
+   */
+  disableHover?: boolean;
+
+  /**
+   * Set to `true` if the rows in the `TableBody` should no longer have borders
+   * applied.
+   *
+   * @defaultValue `false`
+   */
+  disableBorders?: boolean;
+}
+
+/**
+ * The horizontal alignment for the content within a cell.
+ *
+ * Note: Table default behavior is to align to the left.
+ */
+export type TableCellHorizontalAlignment = "left" | "center" | "right";
+
+/**
+ * The vertical alignment for the content within a cell.
+ *
+ * Note: When this is set to `"top"` or `"bottom"`, `padding-top` or
+ * `padding-bottom` will also be applied due to how styling tables work.
+ */
+export type TableCellVerticalAlignment = "top" | "middle" | "bottom";
+
+export interface TableCellConfiguration {
+  hAlign?: TableCellHorizontalAlignment;
+  vAlign?: TableCellVerticalAlignment;
+
+  /**
+   * Set this to `true` to allow `TableCell` content to line wrap.
+   *
+   * @defaultValue `false`
+   */
+  lineWrap?: boolean;
+}
+
+/**
+ * @internal
+ */
+export interface TableCellConfig extends TableCellConfiguration {
+  /**
+   * Boolean if all the `TableCell` components should be rendered as a `<th>`
+   * instead of a `<td>`. This is really just a convenience prop for the
+   * `TableHeader` component so the user of `react-md` doesn't need to keep
+   * setting the `type="th"` fot the `TableCell` if using the low-level
+   * components.
+   *
+   * @internal
+   */
+  header?: boolean;
+}
+
+export interface TableConfig extends TableRowConfiguration, TableCellConfig {
+  /**
+   * Set this to `true` to decrease the height of all cells within the table.
+   *
+   * @defaultValue `false`
+   */
+  dense?: boolean;
+}
+
+export interface TableConfiguration extends TableConfig {
+  /**
+   * Set this to `true` to allow the table to span the full width of the
+   * container element instead of having the width be determined by the content
+   * within the table.
+   *
+   * @defaultValue `false`
+   */
+  fullWidth?: boolean;
+}
+
+export type TableConfigContext = Required<TableConfig>;
 
 /** @since 6.0.0 */
-export type TableStickySectionOptions = Pick<
+export type TableStickySectionIntersectionObserverOptions = Pick<
   IntersectionObserverHookOptions<HTMLTableSectionElement>,
   "disabled" | "getThreshold" | "getRootMargin"
 >;
@@ -20,7 +108,7 @@ export type TableStickySectionOptions = Pick<
  *   viewport.
  *   - Note: This really only works with `px` and `rem` units.
  *
- * @see {@link TableStickySectionProps.stickyOptions} for an example usage with custom threshold and
+ * @see {@link TableStickySectionConfiguration.stickyOptions} for an example usage with custom threshold and
  * margin.
  * @since 6.0.0
  */
@@ -30,12 +118,7 @@ export type IsStickyTableSectionActive = (
 ) => boolean;
 
 /** @since 6.0.0 */
-export interface TableStickySectionProps {
-  /**
-   * @defaultValue `false`
-   */
-  sticky?: boolean;
-
+export interface TableStickySectionConfiguration {
   /**
    * This can be used when the {@link sticky} prop is set to `true` for
    * additional behavior around the "active" state for sticky headers.
@@ -68,7 +151,7 @@ export interface TableStickySectionProps {
    * @since 6.0.0
    * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API}
    */
-  stickyOptions?: TableStickySectionOptions;
+  stickyOptions?: TableStickySectionIntersectionObserverOptions;
 
   /**
    * An optional className to use when the sticky section is covering other rows
@@ -97,3 +180,15 @@ export interface TableStickySectionProps {
    */
   disableStickyStyles?: boolean;
 }
+
+/** @since 6.0.0 */
+export interface TableSectionConfiguration {
+  /** @see {@link TableCellConfiguration.lineWrap} */
+  lineWrap?: boolean;
+
+  /**
+   * @see {@link TableRowConfiguration.disableHover}
+   * @defaultValue `false`
+   */
+  hoverable?: boolean;
+}

package/src/table/useStickyTableSection.tsx

@@ -0,0 +1,126 @@
+"use client";
+import {
+  useCallback,
+  useState,
+  type ReactNode,
+  type Ref,
+  type RefCallback,
+} from "react";
+import { useEnsuredRef } from "../useEnsuredRef.js";
+import { useIntersectionObserver } from "../useIntersectionObserver.js";
+import { useTableContainer } from "./TableContainerProvider.js";
+import {
+  type IsStickyTableSectionActive,
+  type TableStickySectionConfiguration,
+} from "./types.js";
+
+/**
+ * @since 6.0.0
+ */
+export const isTableHeaderStickyActive: IsStickyTableSectionActive = (
+  entry
+) => {
+  return (
+    entry.intersectionRatio < 1 &&
+    entry.boundingClientRect.bottom <= window.innerHeight
+  );
+};
+
+/**
+ * @since 6.0.0
+ */
+export const isTableFooterStickyActive: IsStickyTableSectionActive = (
+  entry,
+  isInTableContainer
+) => {
+  const { intersectionRatio, boundingClientRect, isIntersecting } = entry;
+  if (isInTableContainer) {
+    return !isIntersecting;
+  }
+
+  return intersectionRatio < 1 && boundingClientRect.top >= 0;
+};
+
+/** @since 6.0.0 */
+export interface TableStickySectionOptions
+  extends TableStickySectionConfiguration {
+  ref?: Ref<HTMLTableSectionElement>;
+  type: "header" | "footer";
+}
+
+/** @since 6.0.0 */
+export interface TableStickySectionImplementation {
+  tbody: ReactNode;
+  targetRef: RefCallback<HTMLTableSectionElement>;
+  sectionRef: RefCallback<HTMLTableSectionElement>;
+  stickyActive: boolean;
+}
+
+/**
+ * @since 6.0.0
+ * @internal
+ */
+export function useStickyTableSection(
+  options: TableStickySectionOptions
+): TableStickySectionImplementation {
+  const { ref, type, disableStickyStyles, stickyOptions } = options;
+
+  const isHeader = type === "header";
+  const isStickyActive =
+    options.isStickyActive ??
+    (isHeader ? isTableHeaderStickyActive : isTableFooterStickyActive);
+
+  const [sectionRef, sectionRefCallback] = useEnsuredRef(ref);
+  const { exists, containerRef } = useTableContainer();
+  const [stickyActive, setStickyActive] = useState(false);
+  const targetRef = useIntersectionObserver({
+    ref: exists ? undefined : sectionRefCallback,
+    root: containerRef,
+    disabled: disableStickyStyles,
+    threshold: exists ? 0 : 1,
+    getRootMargin: useCallback(() => {
+      const section = sectionRef.current;
+      if (!isHeader) {
+        const topOffset = exists && section ? section.offsetHeight - 1 : 1;
+
+        return `0px 0px -${topOffset}px 0px`;
+      }
+
+      if (!section) {
+        return;
+      }
+
+      let topOffset: number;
+      if (exists) {
+        topOffset = section.offsetHeight - 1;
+      } else {
+        const top = parseFloat(window.getComputedStyle(section).top);
+        topOffset = Number.isNaN(top) ? 1 : top + 1;
+      }
+
+      return `-${topOffset}px 0px 0px`;
+    }, [exists, isHeader, sectionRef]),
+    onUpdate: useCallback(
+      ([entry]) => {
+        setStickyActive(isStickyActive(entry, exists));
+      },
+      [exists, isStickyActive]
+    ),
+    // allow the user defined sticky options to override the default behavior
+    ...stickyOptions,
+  });
+
+  let tbody: ReactNode;
+  if (exists && !disableStickyStyles) {
+    // rendering a `<tbody>` since it is valid to have 0-many in a table
+    // https://html.spec.whatwg.org/multipage/tables.html#the-table-element
+    tbody = <tbody aria-hidden ref={targetRef} />;
+  }
+
+  return {
+    tbody,
+    targetRef,
+    sectionRef: exists ? sectionRefCallback : targetRef,
+    stickyActive,
+  };
+}

package/src/table/useTableSectionConfig.ts

@@ -0,0 +1,45 @@
+"use client";
+import { useMemo } from "react";
+import { useTableConfig } from "./TableConfigurationProvider.js";
+import {
+  type TableConfigContext,
+  type TableSectionConfiguration,
+} from "./types.js";
+
+/**
+ * @since 6.0.0
+ * @internal
+ */
+export interface TableSectionConfigOptions extends TableSectionConfiguration {
+  type: "header" | "footer";
+}
+
+/**
+ * @since 6.0.0
+ * @internal
+ */
+export function useTableSectionConfig(
+  options: TableSectionConfigOptions
+): Readonly<TableConfigContext> {
+  const { type, lineWrap: propLineWrap, hoverable } = options;
+
+  // update the table configuration with the custom overrides for the `<thead>/<tfoot>`
+  const { dense, hAlign, vAlign, lineWrap, disableHover, disableBorders } =
+    useTableConfig({
+      lineWrap: propLineWrap,
+      disableHover: !hoverable,
+    });
+
+  return useMemo<TableConfigContext>(
+    () => ({
+      dense,
+      header: type === "header",
+      hAlign,
+      vAlign,
+      lineWrap,
+      disableBorders,
+      disableHover,
+    }),
+    [dense, type, hAlign, vAlign, lineWrap, disableBorders, disableHover]
+  );
+}

package/src/tabs/Tab.tsx

@@ -79,6 +79,9 @@ export interface TabButtonProps
   as?: "button";
 }
 
+/**
+ * @since 6.0.0
+ */
 export interface TabLinkProps
   extends BaseTabProps,
     AnchorHTMLAttributes<HTMLAnchorElement> {

package/src/tabs/TabListScrollButton.tsx

@@ -98,7 +98,11 @@ export const TabListScrollButton = forwardRef<
           applyRef(instance, ref);
           root.current = instance?.parentElement || null;
         }}
-        className={tabListScrollButtonContainer({ forward, className })}
+        className={tabListScrollButtonContainer({
+          forward,
+          vertical,
+          className,
+        })}
       >
         <Button
           aria-label={ariaLabel || (iconButton ? type : undefined)}
@@ -107,7 +111,10 @@ export const TabListScrollButton = forwardRef<
           buttonType={buttonType}
           disabled={propDisabled || disabled}
           {...buttonProps}
-          className={tabListScrollButton(buttonProps)}
+          className={tabListScrollButton({
+            className: buttonProps?.className,
+            vertical,
+          })}
           onClick={(event) => {
             buttonProps?.onClick?.(event);
             const container = root.current;

package/src/tabs/tabListScrollButtonStyles.ts

@@ -9,6 +9,7 @@ const styles = bem("rmd-tablist-button");
 export interface TabListScrollButtonContainerClassNameOptions {
   className?: string;
   forward: boolean;
+  vertical?: boolean;
 }
 
 /**
@@ -17,12 +18,14 @@ export interface TabListScrollButtonContainerClassNameOptions {
 export function tabListScrollButtonContainer(
   options: TabListScrollButtonContainerClassNameOptions
 ): string {
-  const { forward, className } = options;
+  const { forward, vertical, className } = options;
 
   return cnb(
     styles({
-      left: !forward,
-      right: forward,
+      left: !vertical && !forward,
+      right: !vertical && forward,
+      above: vertical && !forward,
+      below: vertical && forward,
     }),
     className
   );
@@ -33,6 +36,7 @@ export function tabListScrollButtonContainer(
  */
 export interface TabListScrollButtonClassNameOptions {
   className?: string;
+  vertical?: boolean;
 }
 
 /**
@@ -41,7 +45,7 @@ export interface TabListScrollButtonClassNameOptions {
 export function tabListScrollButton(
   options: TabListScrollButtonClassNameOptions = {}
 ): string {
-  const { className } = options;
+  const { className, vertical } = options;
 
-  return cnb(styles("button"), className);
+  return cnb(styles("button", { v: vertical }), className);
 }

package/src/tabs/useTabList.ts

@@ -65,11 +65,13 @@ export interface TabListHookReturnValue {
     ref: RefObject<HTMLDivElement>;
     type: "back";
     vertical: boolean;
+    disableTransition?: boolean;
   };
   forwardProps: {
     ref: RefObject<HTMLDivElement>;
     type: "forward";
     vertical: boolean;
+    disableTransition?: boolean;
   };
 }
 
@@ -206,11 +208,13 @@ export function useTabList(
       ref: backwardRef,
       type: "back",
       vertical,
+      disableTransition,
     },
     forwardProps: {
       ref: forwardRef,
       type: "forward",
       vertical,
+      disableTransition,
     },
     movementContext,
   };