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

package/src/test-utils/vitest/uploadMenuItemFileInput.ts

@@ -0,0 +1,52 @@
+import { fireEvent } from "@testing-library/dom";
+import { type UserEvent } from "@testing-library/user-event";
+import { vitest } from "vitest";
+
+import { createFileList } from "../utils/createFileList.js";
+
+/**
+ * @since 6.0.0
+ */
+export interface UploadMenuItemFileUploadOptions {
+  user: UserEvent;
+  files: File | readonly File[];
+  menuItem: HTMLElement;
+}
+
+/**
+ * @example Main Example
+ * ```tsx
+ * const user = userEvent.setup()
+ * render(<Test />);
+ *
+ * await user.click(screen.getByRole("button", { name: "Dropdown Menu" }));
+ *
+ * const menuItem = screen.getByRole("menuitem", { name: "Upload" });
+ * const file = new File(["pretend-bytes"], "README.txt");
+ * await uploadMenuItemFileUpload({
+ *   user,
+ *   // can be a single file or multiple
+ *   files: file,
+ *   menuItem,
+ * });
+ *
+ * // expect something with uploaded file
+ * ```
+ *
+ * @since 6.0.0
+ */
+export async function uploadMenuItemFileUpload(
+  options: UploadMenuItemFileUploadOptions
+): Promise<void> {
+  const { user, files, menuItem } = options;
+
+  const input = document.createElement("input");
+  vitest.spyOn(document, "createElement").mockReturnValueOnce(input);
+  vitest.spyOn(input, "click").mockImplementationOnce(() => {
+    fireEvent.change(input, {
+      target: { files: createFileList(window, files) },
+    });
+  });
+
+  await user.click(menuItem);
+}

package/src/theme/LocalStorageColorSchemeProvider.tsx

@@ -1,10 +1,12 @@
 "use client";
+
 import { type ReactElement, type ReactNode } from "react";
-import { useLocalStorage } from "../useLocalStorage.js";
-import { type ColorSchemeMode } from "./types.js";
+
+import { useStorage } from "../storage/useStorage.js";
+import { isColorScheme } from "./isColorScheme.js";
+import { type ColorScheme } from "./types.js";
 import { ColorSchemeProvider } from "./useColorScheme.js";
 import { useColorSchemeProvider } from "./useColorSchemeProvider.js";
-import { isColorSchemeMode } from "./isColorScheme.js";
 
 /**
  * @since 6.0.0
@@ -19,20 +21,20 @@ export interface LocalStorageColorSchemeProviderProps {
   disableMetaTag?: boolean;
 
   /**
-   * Set this to a string like `"colorScheme"` if you want to store the user's
-   * color scheme preference in local storage.
+   * Set this to an empty string to disable the local storage behavior. Otherwise,
+   * this can be used to customize the name.
    *
-   * @defaultValue `""`
+   * @defaultValue `"colorScheme"`
    */
   localStorageKey?: string;
 
   /**
-   * The current color scheme mode that is being used by your app. This should
+   * The current color scheme that is being used by your app. This should
    * match the `$color-scheme` SCSS variable.
    *
    * @defaultValue `"light"`
    */
-  defaultColorSchemeMode?: ColorSchemeMode;
+  defaultColorScheme?: ColorScheme;
 
   children: ReactNode;
 }
@@ -53,34 +55,34 @@ export interface LocalStorageColorSchemeProviderProps {
  * import { createRoot } from "react-dom/client";
  *
  * function MyComponent(): ReactElement {
- *   const { colorScheme, colorSchemeMode, setColorSchemeMode } = useColorScheme();
- *   // colorScheme: "light" | "dark"
- *   // colorSchemeMode: "light" | "dark" | "system"
+ *   const { currentColor, colorScheme, setColorScheme } = useColorScheme();
+ *   // currentColor: "light" | "dark"
+ *   // colorScheme: "light" | "dark" | "system"
  *
  *   return (
  *     <>
- *       The current color scheme is {colorScheme}
+ *       The current color scheme is {currentColor}
  *       <SegmentedButtonContainer>
  *         <SegmentedButton
- *           selected={colorSchemeMode === "light"}
+ *           selected={colorScheme === "light"}
  *           onClick={() => {
- *             setColorSchemeMode("light")
+ *             setColorScheme("light")
  *           }}
  *         >
  *           Light
  *         </SegmentedButton>
  *         <SegmentedButton
- *           selected={colorSchemeMode === "dark"}
+ *           selected={colorScheme === "dark"}
  *           onClick={() => {
- *             setColorSchemeMode("dark")
+ *             setColorScheme("dark")
  *           }}
  *         >
  *           Dark
  *         </SegmentedButton>
  *         <SegmentedButton
- *           selected={colorSchemeMode === "system"}
+ *           selected={colorScheme === "system"}
  *           onClick={() => {
- *             setColorSchemeMode("system")
+ *             setColorScheme("system")
  *           }}
  *         >
  *           System
@@ -94,7 +96,7 @@ export interface LocalStorageColorSchemeProviderProps {
  * const root = createRoot(container);
  *
  * root.render(
- *   <LocalStorageColorSchemeProvider defaultColorSchemeMode="system">
+ *   <LocalStorageColorSchemeProvider defaultColorScheme="system">
  *     <MyComponent />
  *   </LocalStorageColorSchemeProvider>
  * );
@@ -106,24 +108,22 @@ export function LocalStorageColorSchemeProvider(
   props: LocalStorageColorSchemeProviderProps
 ): ReactElement {
   const {
-    localStorageKey = "",
-    defaultColorSchemeMode = "light",
+    localStorageKey = "colorScheme",
+    defaultColorScheme = "light",
     disableMetaTag,
     children,
   } = props;
 
-  const { value: colorSchemeMode, setValue: setColorSchemeMode } =
-    useLocalStorage({
-      key: localStorageKey,
-      defaultValue: defaultColorSchemeMode,
-      deserializer: (item) =>
-        isColorSchemeMode(item) ? item : defaultColorSchemeMode,
-    });
+  const { value: colorScheme, setValue: setColorScheme } = useStorage({
+    key: localStorageKey,
+    defaultValue: defaultColorScheme,
+    deserializer: (item) => (isColorScheme(item) ? item : defaultColorScheme),
+  });
 
   const value = useColorSchemeProvider({
     disableMetaTag,
-    colorSchemeMode,
-    setColorSchemeMode,
+    colorScheme,
+    setColorScheme,
   });
 
   return <ColorSchemeProvider value={value}>{children}</ColorSchemeProvider>;

package/src/theme/ThemeProvider.tsx

@@ -1,13 +1,15 @@
 "use client";
+
 import {
+  type ReactElement,
+  type ReactNode,
   createContext,
   useContext,
   useEffect,
   useMemo,
   useState,
-  type ReactElement,
-  type ReactNode,
 } from "react";
+
 import { useSsr } from "../SsrProvider.js";
 import { type UseStateSetter } from "../types.js";
 import {
@@ -257,7 +259,7 @@ export interface ThemeProviderProps {
    * When this is `undefined`, the theme will be derived by computing the
    * `document.documentElement`'s styles for all the `react-md` theme custom
    * properties. The theme will also automatically update whenever the
-   * `colorScheme` or `colorSchemeMode` change.
+   * `currentColor` or `colorScheme` change.
    *
    * It is recommended to manually provide your theme if you know it beforehand.
    * Deriving the theme is really only useful if you allow your user to
@@ -266,7 +268,7 @@ export interface ThemeProviderProps {
    *
    * @see {@link DEFAULT_DARK_THEME}
    * @see {@link DEFAULT_LIGHT_THEME}
-   * @defaultValue `colorScheme === "dark" ? DEFAULT_DARK_THEME : DEFAULT_LIGHT_THEME`
+   * @defaultValue `currentColor === "dark" ? DEFAULT_DARK_THEME : DEFAULT_LIGHT_THEME`
    */
   theme?: Readonly<ConfigurableThemeColors>;
 
@@ -356,7 +358,7 @@ export interface ThemeProviderProps {
 export function ThemeProvider(props: ThemeProviderProps): ReactElement {
   const { children, theme } = props;
   const ssr = useSsr();
-  const { colorScheme, colorSchemeMode } = useColorScheme();
+  const { currentColor, colorScheme } = useColorScheme();
   const [derivedTheme, setDerivedTheme] = useState<ConfigurableThemeColors>(
     () => {
       if (theme) {
@@ -367,7 +369,7 @@ export function ThemeProvider(props: ThemeProviderProps): ReactElement {
         return getDerivedTheme(document.documentElement);
       }
 
-      return colorScheme === "dark" ? DEFAULT_DARK_THEME : DEFAULT_LIGHT_THEME;
+      return currentColor === "dark" ? DEFAULT_DARK_THEME : DEFAULT_LIGHT_THEME;
     }
   );
 
@@ -391,7 +393,7 @@ export function ThemeProvider(props: ThemeProviderProps): ReactElement {
     return () => {
       window.cancelAnimationFrame(frame);
     };
-  }, [theme, colorScheme, colorSchemeMode]);
+  }, [theme, currentColor, colorScheme]);
 
   const value = useMemo<ThemeContext>(() => {
     const backgroundColor =

package/src/theme/isColorScheme.ts

@@ -1,22 +1,24 @@
-import { type ColorSchemeMode, type ColorScheme } from "./types.js";
+import { type ColorScheme, type LightDarkColorScheme } from "./types.js";
 
 /**
- * A type assertion helper to check if a value is a valid {@link ColorScheme}
+ * A type assertion helper to check if a value is a valid {@link LightDarkColorScheme}
  * when it is pulled from unknown sources (like local storage).
  *
  * @since 6.0.0
  */
-export function isColorScheme(value: unknown): value is ColorScheme {
+export function isLightDarkColorScheme(
+  value: unknown
+): value is LightDarkColorScheme {
   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
+ * {@link ColorScheme} 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";
+export function isColorScheme(value: unknown): value is ColorScheme {
+  return isLightDarkColorScheme(value) || value === "system";
 }

package/src/theme/types.ts

@@ -1,4 +1,5 @@
 import { type CSSProperties } from "react";
+
 import { type UseStateSetter } from "../types.js";
 
 /**
@@ -65,40 +66,27 @@ export type ReadonlyCSSVariableList<
 > = readonly Readonly<CSSVariable<Name>>[];
 
 /** @since 6.0.0 */
-export type ColorScheme = "light" | "dark";
+export type LightDarkColorScheme = "light" | "dark";
 
 /** @since 6.0.0 */
-export type ColorSchemeMode = ColorScheme | "system";
+export type ColorScheme = LightDarkColorScheme | "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;
-
+export interface ColorSchemeState {
   /**
-   * A function to update the color scheme.
-   *
-   * @see {@link useColorScheme} for an example usage
+   * The defined color scheme for the app that should match the `$color-scheme`
+   * SCSS variable.
    */
-  setColorSchemeMode: UseStateSetter<ColorSchemeMode>;
+  colorScheme: ColorScheme;
+  setColorScheme: UseStateSetter<ColorScheme>;
 }
 
 /** @since 6.0.0 */
-export interface ColorSchemeContext extends ColorSchemeModeBehavior {
+export interface ColorSchemeContext extends ColorSchemeState {
   /**
-   * The current color scheme that is being used. This is only useful when the
-   * {@link colorSchemeMode} is set to `"system"`.
+   * When the {@link colorScheme} is set to `"system"`, this will reflect
    */
-  colorScheme: ColorScheme;
+  currentColor: LightDarkColorScheme;
 }

package/src/theme/useCSSVariables.ts

@@ -1,5 +1,7 @@
 "use client";
+
 import { type RefObject, useEffect, useMemo } from "react";
+
 import {
   type CSSVariableName,
   type CSSVariablesProperties,
@@ -9,12 +11,9 @@ import {
 /**
  * @example Applying Variables the root html element
  * ```ts
- * import {
- *   contrastColor,
- *   pinkAccent200,
- *   purple500,
- *   useCSSVariables,
- *  } from "@react-md/core";
+ * import { purple500 } from "@react-md/core/theme/colors";
+ * import { useCSSVariables } from "@react-md/core/theme/useCSSVariables";
+ * import { contrastColor } from "@react-md/core/theme/utils";
  * import { useMemo } from "react";
  *
  * function Example(): null {
@@ -46,15 +45,11 @@ export function useCSSVariables<Name extends CSSVariableName>(
 /**
  * @example Applying variables through inline styles
  * ```tsx
- * import {
- *   contrastColor,
- *   ReadonlyCSSVariableList,
- *   pinkAccent200,
- *   purple500,
- *   useCSSVariables,
- *  } from "@react-md/core";
- * import { useMemo } from "react";
- * import type { ReactElement, ReactNode } from "react";
+ * import { purple500 } from "@react-md/core/theme/colors";
+ * import { type ReadonlyCSSVariableList } from "@react-md/core/theme/types";
+ * import { useCSSVariables } from "@react-md/core/theme/useCSSVariables";
+ * import { contrastColor } from "@react-md/core/theme/utils";
+ * import { type ReactElement, type ReactNode, useMemo } from "react";
  *
  * function Example({ children }: { children: ReactNode }): ReactElement {
  *   const customVariables = useMemo<ReadonlyCSSVariableList>(() => {

package/src/theme/useColorScheme.ts

@@ -1,11 +1,13 @@
 "use client";
+
 import { createContext, useContext } from "react";
+
 import { type ColorSchemeContext } from "./types.js";
 
 const context = createContext<ColorSchemeContext>({
+  currentColor: "light",
   colorScheme: "light",
-  colorSchemeMode: "light",
-  setColorSchemeMode() {
+  setColorScheme() {
     if (process.env.NODE_ENV !== "production") {
       throw new Error("The `ColorSchemeProvider` has not been initialized.");
     }
@@ -17,45 +19,47 @@ export const { Provider: ColorSchemeProvider } = context;
 /**
  * @example Lazy Load Configurable Themes
  * ```tsx
- * import type { ChangeEvent, ReactElement } from "react";
- * import { lazy } from "react";
- * import { createRoot } from "react-doc/client";
- * import { Checkbox, ColorSchemeProvider, useColorScheme } from "@react-md/core";
+ * import { Checkbox } from "@react-md/core/form/Checkbox";
+ * import { ColorSchemeProvider, useColorScheme } from "@react-md/core/theme/useColorScheme";
+ * import { type ChangeEvent, lazy, type ReactElement } from "react";
+ * import { createRoot } from "react-dom/client";
  *
- * const DarkTheme = lazy(() => import("./DarkTheme"));
- * const SystemTheme = lazy(() => import("./SystemTheme"));
+ * const DarkTheme = lazy(() => import("./DarkTheme.jsx"));
+ * const SystemTheme = lazy(() => import("./SystemTheme.jsx"));
  *
  * function App(): ReactElement {
- *   const { colorScheme, colorSchemeMode, setColorSchemeMode } =
+ *   const { currentColor, colorScheme, setColorScheme } =
  *     useColorScheme();
  *
  *   const onChange = (event: ChangeEvent<HTMLInputElement>): void => {
  *     const { value } = event.currentTarget;
  *     if (value === "light" || value === "dark" || value === "system") {
- *       setColorSchemeMode(value);
+ *       setColorScheme(value);
  *     }
  *   };
  *
  *   return (
  *     <>
- *       {colorSchemeMode === "dark" && <DarkTheme />}
- *       {colorSchemeMode === "system" && <SystemTheme />}
+ *       <NullSuspense>
+ *         {colorScheme === "dark" && <DarkTheme />}
+ *         {colorScheme === "system" && <SystemTheme />}
+ *       </NullSuspense>
  *       <Checkbox
  *         label="Light"
  *         value="light"
- *         checked={colorSchemeMode === "light"}
+ *         checked={colorScheme === "light"}
  *         onChange={onChange}
  *       />
  *       <Checkbox
  *         label="Dark"
  *         value="dark"
- *         checked={colorSchemeMode === "dark"}
+ *         checked={colorScheme === "dark"}
  *         onChange={onChange}
  *       />
  *       <Checkbox
  *         label="System"
  *         value="system"
- *         checked={colorSchemeMode === "system"}
+ *         checked={colorScheme === "system"}
  *         onChange={onChange}
  *       />
  *     </>

package/src/theme/useColorSchemeMetaTag.ts

@@ -1,6 +1,8 @@
 "use client";
+
 import { useEffect } from "react";
-import { type ColorScheme } from "./types.js";
+
+import { type LightDarkColorScheme } from "./types.js";
 
 /**
  * @since 6.0.0
@@ -10,7 +12,7 @@ export interface ColorSchemeMetaTagOptions {
    * @defaultValue `"false"`
    */
   disabled?: boolean;
-  colorScheme: ColorScheme;
+  colorScheme: LightDarkColorScheme;
 }
 
 /**
@@ -19,6 +21,19 @@ export interface ColorSchemeMetaTagOptions {
  * should not be used if you are using the `useColorSchemeProvider` since it is
  * already built in.
  *
+ * @example
+ * ```tsx
+ * import { useColorScheme } from "@react-md/core/theme/useColorScheme";
+ * import { useColorSchemeMetaTag } from "@react-md/core/theme/useColorSchemeMetaTag";
+ *
+ * function Example() {
+ *   const { currentColor } = useColorScheme();
+ *   useColorSchemeMetaTag({ colorScheme: currentColor });
+ *
+ *   return null;
+ * }
+ * ```
+ *
  * @since 6.0.0
  */
 export function useColorSchemeMetaTag(

package/src/theme/useColorSchemeProvider.ts

@@ -1,20 +1,21 @@
 "use client";
+
 import { useMemo } from "react";
+
 import { type UseStateInitializer } from "../types.js";
 import { useEnsuredState } from "../useEnsuredState.js";
 import {
+  type ColorScheme,
   type ColorSchemeContext,
-  type ColorSchemeMode,
-  type ColorSchemeModeBehavior,
+  type ColorSchemeState,
 } from "./types.js";
 import { useColorSchemeMetaTag } from "./useColorSchemeMetaTag.js";
-import { usePrefersDarkTheme } from "./usePrefersDarkScheme.js";
+import { usePrefersDarkTheme } from "./usePrefersDarkTheme.js";
 
 /**
  * @since 6.0.0
  */
-export interface ColorSchemeProviderOptions
-  extends Partial<ColorSchemeModeBehavior> {
+export interface ColorSchemeProviderOptions extends Partial<ColorSchemeState> {
   /**
    * Set this to `true` to prevent a `<meta name="color-scheme" content="{COLOR_SCHEME}">`
    * from being added to the `document.head`.
@@ -24,60 +25,58 @@ export interface ColorSchemeProviderOptions
   disableMetaTag?: boolean;
 
   /**
-   * The current color scheme mode that is being used by your app. This should
+   * The current color scheme that is being used by your app. This should
    * match the `$color-scheme` SCSS variable.
    *
    * @defaultValue `"light"`
    */
-  defaultColorSchemeMode?: UseStateInitializer<ColorSchemeMode>;
+  defaultColorScheme?: UseStateInitializer<ColorScheme>;
 }
 
 /**
  * @example
  * ```tsx
- * import {
- *   ColorSchemeProvider,
- *   useColorSchemeProvider,
- *   type ColorSchemeMode,
- * } from "@react-md/core";
+ * import { type ColorScheme } from "@react-md/core/theme/types";
+ * import { ColorSchemeProvider } from "@react-md/core/theme/useColorScheme";
+ * import { useColorSchemeProvider } from "@reat-md/core/theme/useColorSchemeProvider";
  * import { type PropsWithChildren, type ReactElement } from "react";
  * import Cookies from "js-cookie";
  *
  * function MyColorSchemeProvider(props: PropsWithChildren): ReactElement {
  *   const { children } = props;
  *
- *   const [colorSchemeMode, setColorSchemeMode] = useState<ColorSchemeMode>(
- *     () => Cookies.get("colorSchemeMode") || "system"
+ *   const [colorScheme, setColorScheme] = useState<ColorScheme>(
+ *     () => Cookies.get("colorScheme") || "system"
  *   );
  *   const value = useColorSchemeProvider({
- *     colorSchemeMode,
- *     setColorSchemeMode(nextValue) {
- *       setColorSchemeMode((prevValue) => {
+ *     colorScheme,
+ *     setColorScheme(nextValue) {
+ *       setColorScheme((prevValue) => {
  *         const value = typeof nextValue === "function"
  *           ? nextValue(prevValue)
  *           : nextValue;
  *
- *         Cookies.set("colorSchemeMode", value);
+ *         Cookies.set("colorScheme", value);
  *         return value;
  *       });
  *     }
  *   });
  *
- *   return <ColorSchemeProvider value={value}>{children}</ColorSchemeProvider>
+ *   return <ColorSchemeProvider value={value}>{children}</ColorSchemeProvider>;
  * }
  * ```
  * @since 6.0.0
  */
 export function useColorSchemeProvider(
-  options?: { [key in keyof ColorSchemeModeBehavior]?: never } & {
+  options?: { [key in keyof ColorSchemeState]?: never } & {
     disableMetaTag?: boolean;
-    defaultColorSchemeMode?: UseStateInitializer<ColorSchemeMode>;
+    defaultColorScheme?: UseStateInitializer<ColorScheme>;
   }
 ): ColorSchemeContext;
 export function useColorSchemeProvider(
-  options: ColorSchemeModeBehavior & {
+  options: ColorSchemeState & {
     disableMetaTag?: boolean;
-    defaultColorSchemeMode?: never;
+    defaultColorScheme?: never;
   }
 ): ColorSchemeContext;
 export function useColorSchemeProvider(
@@ -85,32 +84,32 @@ export function useColorSchemeProvider(
 ): ColorSchemeContext {
   const {
     disableMetaTag,
-    colorSchemeMode: value,
-    setColorSchemeMode: setValue,
-    defaultColorSchemeMode,
+    colorScheme: propColorScheme,
+    setColorScheme: propSetColorScheme,
+    defaultColorScheme,
   } = options;
 
-  const [colorSchemeMode, setColorSchemeMode] = useEnsuredState({
-    value,
-    setValue,
-    defaultValue: defaultColorSchemeMode,
+  const [colorScheme, setColorScheme] = useEnsuredState({
+    value: propColorScheme,
+    setValue: propSetColorScheme,
+    defaultValue: defaultColorScheme,
   });
-  const prefersDarkTheme = usePrefersDarkTheme(colorSchemeMode !== "system");
+  const prefersDarkTheme = usePrefersDarkTheme(colorScheme !== "system");
   const derivedColorScheme = prefersDarkTheme ? "dark" : "light";
-  const colorScheme =
-    colorSchemeMode === "system" ? derivedColorScheme : colorSchemeMode;
+  const currentColor =
+    colorScheme === "system" ? derivedColorScheme : colorScheme;
 
   useColorSchemeMetaTag({
     disabled: disableMetaTag,
-    colorScheme,
+    colorScheme: currentColor,
   });
 
   return useMemo<ColorSchemeContext>(
     () => ({
+      currentColor,
       colorScheme,
-      colorSchemeMode,
-      setColorSchemeMode,
+      setColorScheme,
     }),
-    [colorScheme, colorSchemeMode, setColorSchemeMode]
+    [currentColor, colorScheme, setColorScheme]
   );
 }

package/src/theme/{usePrefersDarkScheme.ts → usePrefersDarkTheme.ts}

@@ -1,4 +1,5 @@
 "use client";
+
 import { useMediaQuery } from "../media-queries/useMediaQuery.js";
 
 /**

package/src/tooltip/Tooltip.tsx

@@ -1,5 +1,7 @@
 "use client";
-import { forwardRef, type HTMLAttributes } from "react";
+
+import { type HTMLAttributes, forwardRef } from "react";
+
 import { type TextOverflow } from "../cssUtils.js";
 import { Portal } from "../portal/Portal.js";
 import { type SimplePosition } from "../positioning/types.js";