@react-md/core 1.0.0-next.15 → 1.0.0-next.17

package/src/tabs/getTabListScrollToOptions.ts

@@ -0,0 +1,37 @@
+/**
+ * @since 6.0.0
+ */
+export interface TabListScrollToOptions {
+  isRTL: boolean;
+  animate: boolean;
+  vertical: boolean;
+  increment: boolean;
+  container: HTMLElement;
+}
+
+/**
+ * @since 6.0.0
+ */
+export type GetTabListScrollToOptions = (
+  options: TabListScrollToOptions
+) => ScrollToOptions | undefined;
+
+/**
+ * @since 6.0.0
+ */
+export const getTabListScrollToOptions: GetTabListScrollToOptions = (
+  options
+) => {
+  const { isRTL, animate, vertical, increment, container } = options;
+  const { scrollLeft, scrollTop, scrollWidth, scrollHeight } = container;
+  const currentScroll = vertical ? scrollTop : scrollLeft;
+  const scrollDistance = vertical ? scrollHeight : scrollWidth;
+  const amount = (scrollDistance / 10) * (increment ? 1 : -1);
+  const distance = currentScroll + amount * (vertical || !isRTL ? 1 : -1);
+
+  return {
+    left: vertical ? undefined : distance,
+    top: vertical ? distance : undefined,
+    behavior: animate ? "smooth" : "auto",
+  };
+};

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

@@ -9,6 +9,10 @@ declare module "react" {
     "--rmd-tab-active-color"?: string;
     "--rmd-tab-inactive-color"?: string;
     "--rmd-tab-disabled-color"?: string;
+
+    "--rmd-tab-size"?: string;
+    "--rmd-tab-offset"?: string | number;
+    "--rmd-tab-indicator-background"?: string;
   }
 }
 

package/src/tabs/useTabList.ts

@@ -18,14 +18,6 @@ import { useEnsuredRef } from "../useEnsuredRef.js";
 import { useResizeObserver } from "../useResizeObserver.js";
 import { getTabRoleOnly, scrollTabIntoView } from "./utils.js";
 
-declare module "react" {
-  interface CSSProperties {
-    "--rmd-tab-size"?: string;
-    "--rmd-tab-offset"?: string | number;
-    "--rmd-tab-indicator-background"?: string;
-  }
-}
-
 const TAB_SIZE_VAR = "--rmd-tab-size";
 const TAB_OFFSET_VAR = "--rmd-tab-offset";
 
@@ -43,7 +35,7 @@ export interface TabListHookOptions {
   ref: Ref<HTMLDivElement> | undefined;
   style: CSSProperties | undefined;
   activeIndex: number;
-  setActiveIndex(nextActiveIndex: number): void;
+  setActiveIndex: (nextActiveIndex: number) => void;
   scrollButtons: boolean;
   activationMode: "manual" | "automatic";
   vertical: boolean;
@@ -65,11 +57,13 @@ export interface TabListHookReturnValue {
     ref: RefObject<HTMLDivElement>;
     type: "back";
     vertical: boolean;
+    disableTransition?: boolean;
   };
   forwardProps: {
     ref: RefObject<HTMLDivElement>;
     type: "forward";
     vertical: boolean;
+    disableTransition?: boolean;
   };
 }
 
@@ -113,6 +107,7 @@ export function useTabList(
         // 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...
+        // eslint-disable-next-line @typescript-eslint/no-unused-expressions
         isRTL;
 
         const activeTab = getTabRoleOnly(entry.target)[activeIndex];
@@ -206,11 +201,13 @@ export function useTabList(
       ref: backwardRef,
       type: "back",
       vertical,
+      disableTransition,
     },
     forwardProps: {
       ref: forwardRef,
       type: "forward",
       vertical,
+      disableTransition,
     },
     movementContext,
   };

package/src/tabs/useTabs.ts

@@ -1,11 +1,22 @@
 "use client";
-import type { Dispatch, Ref, RefObject } from "react";
-import { useEffect, useRef, useState } from "react";
-import type { SlideDirection } from "../transition/SlideContainer.js";
-import type { UseStateInitializer, UseStateSetter } from "../types.js";
+import {
+  type Dispatch,
+  type Ref,
+  type RefObject,
+  useEffect,
+  useRef,
+  useState,
+} from "react";
+import { type SlideDirection } from "../transition/SlideContainer.js";
+import { type UseStateInitializer, type UseStateSetter } from "../types.js";
 import { useEnsuredId } from "../useEnsuredId.js";
 import { useEnsuredState } from "../useEnsuredState.js";
 
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import { type TabProps } from "./Tab.js";
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import { type TabListProps } from "./TabList.js";
+
 const EMPTY_LIST = [] as const;
 const PANEL_PREFIX = "panel-";
 
@@ -21,15 +32,6 @@ export interface TabsHookOptions<TabValue extends string | number = number> {
    */
   baseId?: string;
 
-  /**
-   * Set this to `true` if changing active tabs should no longer attempt to
-   * scroll to the top of the tab panels container when using the
-   * {@link TabsImplementation.getTabPanelsProps}.
-   *
-   * @defaultValue `false`
-   */
-  disableScrollFix?: boolean;
-
   /**
    * Set this to an **ordered** list of tab values when:
    * - using a `string` tab value
@@ -55,6 +57,30 @@ export interface TabsHookOptions<TabValue extends string | number = number> {
    * @defaultValue `0`
    */
   defaultActiveTab?: UseStateInitializer<TabValue>;
+
+  /** Convenience pass-through prop to {@link TabProps.stacked} */
+  stacked?: boolean;
+  /** Convenience pass-through prop to {@link TabProps.iconAfter} */
+  iconAfter?: boolean;
+
+  /** Convenience pass-through props to {@link TabListProps.vertical} */
+  vertical?: boolean;
+
+  /**
+   * Set this to `true` if changing active tabs should no longer attempt to
+   * scroll to the top of the tab panels container when using the
+   * {@link TabsImplementation.getTabPanelsProps}.
+   *
+   * @defaultValue `false`
+   */
+  disableScrollFix?: boolean;
+
+  /**
+   * Convenience prop to disable all transitions for the
+   * {@link TabsImplementation.getTabProps} and
+   * {@link TabsImplementation.getTabListProps}.
+   */
+  disableTransition?: boolean;
 }
 
 /**
@@ -64,6 +90,15 @@ export interface ProvidedTabProps {
   "aria-controls": string;
   id: string;
   active: boolean;
+
+  /** Convenience pass-through prop from {@link TabsHookOptions.stacked} */
+  stacked?: boolean;
+  /** Convenience pass-through prop from {@link TabsHookOptions.iconAfter} */
+  iconAfter?: boolean;
+  /** Convenience pass-through prop from {@link TabsHookOptions.disableTransition} */
+  activeIndicator?: boolean;
+  /** Convenience pass-through prop from {@link TabsHookOptions.vertical} and {@link TabsHookOptions.disableTransition} */
+  verticalActiveIndicator?: boolean;
 }
 
 /**
@@ -72,6 +107,8 @@ export interface ProvidedTabProps {
 export interface ProvidedTabListProps {
   activeIndex: number;
   setActiveIndex: Dispatch<number>;
+  vertical?: boolean;
+  disableTransition?: boolean;
 }
 
 /**
@@ -99,11 +136,11 @@ export interface TabsImplementation<TabValue extends string | number = number> {
   direction: SlideDirection;
   setDirection: UseStateSetter<SlideDirection>;
   activeTab?: TabValue;
-  setActiveTab?(nextActiveTab: TabValue): void;
-  getTabProps(tabValue: TabValue): ProvidedTabProps;
-  getTabListProps(): ProvidedTabListProps;
-  getTabPanelProps(tabValue: TabValue): ProvidedTabPanelProps;
-  getTabPanelsProps<E extends HTMLElement>(): ProvidedTabPanelsProps<E>;
+  setActiveTab?: (nextActiveTab: TabValue) => void;
+  getTabProps: (tabValue: TabValue) => ProvidedTabProps;
+  getTabListProps: () => ProvidedTabListProps;
+  getTabPanelProps: (tabValue: TabValue) => ProvidedTabPanelProps;
+  getTabPanelsProps: <E extends HTMLElement>() => ProvidedTabPanelsProps<E>;
 }
 
 /**
@@ -143,7 +180,7 @@ export interface TabsImplementation<TabValue extends string | number = number> {
  *
  * @since 6.0.0
  */
-export function useTabs(): TabsImplementation<number> & {
+export function useTabs(): TabsImplementation & {
   activeTab: number;
   setActiveTab: number;
 };
@@ -412,11 +449,15 @@ export function useTabs<TabValue extends string | number>(
 ): TabsImplementation<TabValue> {
   const {
     baseId: propBaseId,
-    disableScrollFix,
     tabs = EMPTY_LIST,
+    stacked,
+    vertical,
+    iconAfter,
     activeTab: propActiveTab,
     setActiveTab: propSetActiveTab,
     defaultActiveTab,
+    disableScrollFix,
+    disableTransition,
   } = options;
 
   const baseId = useEnsuredId(propBaseId, "tab");
@@ -456,6 +497,10 @@ export function useTabs<TabValue extends string | number>(
         "aria-controls": getTabId(tabValue, PANEL_PREFIX),
         id: getTabId(tabValue),
         active: tabValue === activeTab,
+        stacked,
+        iconAfter,
+        activeIndicator: disableTransition,
+        verticalActiveIndicator: vertical && disableTransition,
       };
     },
     getTabListProps() {
@@ -469,6 +514,8 @@ export function useTabs<TabValue extends string | number>(
             setActiveTab(nextActiveIndex as TabValue);
           }
         },
+        vertical,
+        disableTransition,
       };
     },
     getTabPanelProps(tabValue) {

package/src/tabs/utils.ts

@@ -44,41 +44,3 @@ export const scrollTabIntoView = (options: ScrollOptions): void => {
     container[scrollAttribute] = elementStart - firstOffset;
   }
 };
-
-/**
- * @since 6.0.0
- */
-export interface TabListScrollToOptions {
-  isRTL: boolean;
-  animate: boolean;
-  vertical: boolean;
-  increment: boolean;
-  container: HTMLElement;
-}
-
-/**
- * @since 6.0.0
- */
-export type GetTabListScrollToOptions = (
-  options: TabListScrollToOptions
-) => ScrollToOptions | undefined;
-
-/**
- * @since 6.0.0
- */
-export const getTabListScrollToOptions: GetTabListScrollToOptions = (
-  options
-) => {
-  const { isRTL, animate, vertical, increment, container } = options;
-  const { scrollLeft, scrollTop, scrollWidth, scrollHeight } = container;
-  const currentScroll = vertical ? scrollTop : scrollLeft;
-  const scrollDistance = vertical ? scrollHeight : scrollWidth;
-  const amount = (scrollDistance / 10) * (increment ? 1 : -1);
-  const distance = currentScroll + amount * (vertical || !isRTL ? 1 : -1);
-
-  return {
-    left: vertical ? undefined : distance,
-    top: vertical ? distance : undefined,
-    behavior: animate ? "smooth" : "auto",
-  };
-};

package/src/test-utils/IntersectionObserver.ts

@@ -14,7 +14,7 @@ export class IntersectionObserverMock implements IntersectionObserver {
     this.thresholds =
       typeof options.threshold === "number"
         ? [options.threshold]
-        : options.threshold ?? [];
+        : (options.threshold ?? []);
 
     this.elements = new Set();
   }

package/src/test-utils/matchMedia.ts

@@ -36,7 +36,7 @@ export type MatchMediaMatcher = (query: string) => boolean;
  * @returns `true` for phone media queries
  */
 export const matchPhone: MatchMediaMatcher = (query) =>
-  query.includes(`${DEFAULT_PHONE_MAX_WIDTH}`);
+  query.includes(DEFAULT_PHONE_MAX_WIDTH);
 
 /**
  * @see {@link spyOnMatchMedia} for usage
@@ -44,7 +44,7 @@ export const matchPhone: MatchMediaMatcher = (query) =>
  * @returns `true` for tablet media queries
  */
 export const matchTablet: MatchMediaMatcher = (query) =>
-  query.includes(`${DEFAULT_TABLET_MIN_WIDTH}`);
+  query.includes(DEFAULT_TABLET_MIN_WIDTH);
 
 /**
  * @see {@link spyOnMatchMedia} for usage
@@ -52,7 +52,7 @@ export const matchTablet: MatchMediaMatcher = (query) =>
  * @returns `true` for desktop media queries
  */
 export const matchDesktop: MatchMediaMatcher = (query) =>
-  query.includes(`${DEFAULT_DESKTOP_MIN_WIDTH}`);
+  query.includes(DEFAULT_DESKTOP_MIN_WIDTH);
 
 /**
  * @see {@link spyOnMatchMedia} for usage
@@ -60,7 +60,7 @@ export const matchDesktop: MatchMediaMatcher = (query) =>
  * @returns `true` for large desktop media queries
  */
 export const matchLargeDesktop: MatchMediaMatcher = (query) =>
-  query.includes(`${DEFAULT_DESKTOP_LARGE_MIN_WIDTH}`);
+  query.includes(DEFAULT_DESKTOP_LARGE_MIN_WIDTH);
 
 /**
  * @see {@link spyOnMatchMedia} for usage
@@ -101,7 +101,7 @@ export type MatchMediaSpiedFunction = jest.SpiedFunction<
    * // expect phone results
    * ```
    */
-  changeViewport(matcher: MatchMediaMatcher, disableAct?: boolean): void;
+  changeViewport: (matcher: MatchMediaMatcher, disableAct?: boolean) => void;
 };
 
 /**

package/src/test-utils/polyfills/TextDecoder.ts

@@ -1,7 +1,6 @@
 import { TextDecoder } from "node:util";
 
 if (typeof global.TextDecoder === "undefined") {
-  // eslint-disable-next-line @typescript-eslint/ban-ts-comment
   // @ts-expect-error browser TextDecoder does not support `null` while `node:util` does
   global.TextDecoder = TextDecoder;
 }

package/src/test-utils/timers.ts

@@ -1,13 +1,18 @@
 import { jest } from "@jest/globals";
 
+/**
+ * @since 6.0.0
+ */
+export type RafSpy = jest.SpiedFunction<typeof requestAnimationFrame>;
+
 /**
  * @example
  * ```ts
- * import { useImmediateRaf } from "@react-md/core/test-utils";
+ * import { testImmediateRaf } from "@react-md/core/test-utils";
  *
  * describe("some test suite", () => {
  *   it("should test something with requestAnimationFrame", () => {
- *     const raf = useImmediateRaf();
+ *     const raf = testImmediateRaf();
  *
  *     // do some testing with requestAnimationFrame
  *
@@ -19,7 +24,7 @@ import { jest } from "@jest/globals";
  *
  * @example Automatic Cleanup
  * ```ts
- * import { useImmediateRaf } from "@react-md/core/test-utils";
+ * import { testImmediateRaf } from "@react-md/core/test-utils";
  *
  * afterEach(() => {
  *   jest.restoreAllMocks();
@@ -27,7 +32,7 @@ import { jest } from "@jest/globals";
  *
  * describe("some test suite", () => {
  *   it("should test something with requestAnimationFrame", () => {
- *     const raf = useImmediateRaf();
+ *     const raf = testImmediateRaf();
  *
  *     // do some testing with requestAnimationFrame
  *   });
@@ -36,9 +41,7 @@ import { jest } from "@jest/globals";
  *
  * @since 6.0.0
  */
-export const useImmediateRaf = (): jest.SpiedFunction<
-  typeof requestAnimationFrame
-> =>
+export const testImmediateRaf = (): RafSpy =>
   jest.spyOn(window, "requestAnimationFrame").mockImplementation((cb) => {
     cb(0);
     return 0;

package/src/theme/LocalStorageColorSchemeProvider.tsx

@@ -1,8 +1,10 @@
 "use client";
 import { type ReactElement, type ReactNode } from "react";
 import { useLocalStorage } from "../useLocalStorage.js";
-import { ColorSchemeProvider, type ColorSchemeMode } from "./useColorScheme.js";
+import { type ColorSchemeMode } from "./types.js";
+import { ColorSchemeProvider } from "./useColorScheme.js";
 import { useColorSchemeProvider } from "./useColorSchemeProvider.js";
+import { isColorSchemeMode } from "./isColorScheme.js";
 
 /**
  * @since 6.0.0
@@ -115,9 +117,7 @@ export function LocalStorageColorSchemeProvider(
       key: localStorageKey,
       defaultValue: defaultColorSchemeMode,
       deserializer: (item) =>
-        item === "light" || item === "dark" || item === "system"
-          ? item
-          : defaultColorSchemeMode,
+        isColorSchemeMode(item) ? item : defaultColorSchemeMode,
     });
 
   const value = useColorSchemeProvider({

package/src/theme/ThemeProvider.tsx

@@ -384,9 +384,9 @@ export function ThemeProvider(props: ThemeProviderProps): ReactElement {
     // NOTE: This will not be correct the first time a new theme is lazy-loaded
     // and applied. It might be good to have a way to manually force this flow
     // again?
-    const frame = window.requestAnimationFrame(() =>
-      setDerivedTheme(getDerivedTheme(document.documentElement))
-    );
+    const frame = window.requestAnimationFrame(() => {
+      setDerivedTheme(getDerivedTheme(document.documentElement));
+    });
 
     return () => {
       window.cancelAnimationFrame(frame);

package/src/theme/isColorScheme.ts

@@ -0,0 +1,22 @@
+import { type ColorSchemeMode, type ColorScheme } from "./types.js";
+
+/**
+ * A type assertion helper to check if a value is a valid {@link ColorScheme}
+ * when it is pulled from unknown sources (like local storage).
+ *
+ * @since 6.0.0
+ */
+export function isColorScheme(value: unknown): value is ColorScheme {
+  return value === "light" || value === "dark";
+}
+
+/**
+ * A type assertion helper to check if a value is a valid
+ * {@link ColorSchemeMode} when it is pulled from unknown sources (like local
+ * storage).
+ *
+ * @since 6.0.0
+ */
+export function isColorSchemeMode(value: unknown): value is ColorSchemeMode {
+  return isColorScheme(value) || value === "system";
+}

package/src/theme/types.ts

@@ -1,4 +1,5 @@
-import type { CSSProperties } from "react";
+import { type CSSProperties } from "react";
+import { type UseStateSetter } from "../types.js";
 
 /**
  * @since 6.0.0
@@ -36,3 +37,68 @@ export type DefinedCustomProperty<Property = keyof CSSProperties> =
  * @since 6.0.0
  */
 export type DefinedCSSVariableName = DefinedCustomProperty;
+
+/**
+ * @since 6.0.0
+ */
+export interface CSSVariable<
+  Name extends CSSVariableName = DefinedCSSVariableName,
+> {
+  name: Name;
+  value: string | number;
+}
+
+/**
+ * @since 6.0.0
+ */
+export type CSSVariablesProperties<
+  Name extends CSSVariableName = DefinedCSSVariableName,
+> = {
+  [key in Name]?: string | number;
+};
+
+/**
+ * @since 6.0.0
+ */
+export type ReadonlyCSSVariableList<
+  Name extends CSSVariableName = DefinedCSSVariableName,
+> = readonly Readonly<CSSVariable<Name>>[];
+
+/** @since 6.0.0 */
+export type ColorScheme = "light" | "dark";
+
+/** @since 6.0.0 */
+export type ColorSchemeMode = ColorScheme | "system";
+
+/**
+ * @since 6.0.0
+ */
+export interface ColorSchemeModeBehavior {
+  /**
+   * The current color scheme mode that is being used by your app that should
+   * default to the `$color-scheme` SCSS variable. If the
+   * {@link setColorSchemeMode} is called, this will update to that new value.
+   *
+   * TODO: Figure out how to document this
+   *
+   * - `colorScheme` - only `light` or `dark` -- only useful when the `colorSchemeMode` is set to `system`
+   * - `colorSchemeMode` - current **user** defined color scheme behavior? should default to `$color-scheme`, but will change based on `setColorSchemeMode`
+   */
+  colorSchemeMode: ColorSchemeMode;
+
+  /**
+   * A function to update the color scheme.
+   *
+   * @see {@link useColorScheme} for an example usage
+   */
+  setColorSchemeMode: UseStateSetter<ColorSchemeMode>;
+}
+
+/** @since 6.0.0 */
+export interface ColorSchemeContext extends ColorSchemeModeBehavior {
+  /**
+   * The current color scheme that is being used. This is only useful when the
+   * {@link colorSchemeMode} is set to `"system"`.
+   */
+  colorScheme: ColorScheme;
+}

package/src/theme/useCSSVariables.ts

@@ -1,33 +1,10 @@
 "use client";
-import type { RefObject } from "react";
-import { useEffect, useMemo } from "react";
-import type { CSSVariableName, DefinedCSSVariableName } from "./types.js";
-
-/**
- * @since 6.0.0
- */
-export interface CSSVariable<
-  Name extends CSSVariableName = DefinedCSSVariableName,
-> {
-  name: Name;
-  value: string | number;
-}
-
-/**
- * @since 6.0.0
- */
-export type CSSVariablesProperties<
-  Name extends CSSVariableName = DefinedCSSVariableName,
-> = {
-  [key in Name]?: string | number;
-};
-
-/**
- * @since 6.0.0
- */
-export type ReadonlyCSSVariableList<
-  Name extends CSSVariableName = DefinedCSSVariableName,
-> = readonly Readonly<CSSVariable<Name>>[];
+import { type RefObject, useEffect, useMemo } from "react";
+import {
+  type CSSVariableName,
+  type CSSVariablesProperties,
+  type ReadonlyCSSVariableList,
+} from "./types.js";
 
 /**
  * @example Applying Variables the root html element
@@ -110,7 +87,7 @@ export function useCSSVariables<Name extends CSSVariableName>(
 export function useCSSVariables<Name extends CSSVariableName>(
   variables: ReadonlyCSSVariableList<Name>,
   rootNodeOrInlineStyle?: RefObject<HTMLElement> | HTMLElement | boolean
-): CSSVariablesProperties<Name> | void {
+): CSSVariablesProperties<Name> | undefined {
   useEffect(() => {
     if (rootNodeOrInlineStyle === true || !variables.length) {
       return;