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

package/dist/icon/styles.d.ts

@@ -1,9 +1,10 @@
 import { type TextColor, type ThemeColor } from "../cssUtils.js";
-import type { MaterialIconFamily, MaterialSymbolFamily } from "./material.js";
+import { type MaterialIconFamily, type MaterialSymbolFamily } from "./material.js";
 declare module "react" {
     interface CSSProperties {
         "--rmd-icon-color"?: string;
         "--rmd-icon-size"?: string | number;
+        "--rmd-icon-dense-size"?: string | number;
         "--rmd-icon-spacing"?: string | number;
         "--rmd-icon-rotate-from"?: string | number;
         "--rmd-icon-rotate-to"?: string | number;

package/dist/icon/styles.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/icon/styles.ts"],"sourcesContent":["import { cnb } from \"cnbuilder\";\n\nimport { type TextColor, type ThemeColor, cssUtils } from \"../cssUtils.js\";\nimport { bem } from \"../utils/bem.js\";\nimport type { MaterialIconFamily, MaterialSymbolFamily } from \"./material.js\";\n\ndeclare module \"react\" {\n  interface CSSProperties {\n    \"--rmd-icon-color\"?: string;\n    \"--rmd-icon-size\"?: string | number;\n    \"--rmd-icon-spacing\"?: string | number;\n    \"--rmd-icon-rotate-from\"?: string | number;\n    \"--rmd-icon-rotate-to\"?: string | number;\n  }\n}\n\nconst styles = bem(\"rmd-icon\");\nconst rotatorStyles = bem(\"rmd-icon-rotator\");\n\n/** @since 6.0.0 */\nexport interface SVGIconClassNameOptions {\n  className?: string;\n\n  /**\n   * An optional theme color to apply to the icon. When this is `undefined`, the\n   * default icon color will be used instead.\n   *\n   * - `primary -> $primary-color`\n   * - `secondary -> $secondary-color`\n   * - `warning -> $warning-color`\n   * - `success -> $success-color`\n   * - `error -> $error-color`\n   * - `text-primary -> $text-primary-color`\n   * - `text-secondary -> $text-primary-color`\n   * - `text-hint -> $text-hint-color`\n   * - `text-disabled -> $text-disabled-color`\n   */\n  theme?: ThemeColor | TextColor;\n\n  /**\n   * Boolean if the font icon should use the dense spec.\n   *\n   * @defaultValue `false`\n   */\n  dense?: boolean;\n\n  /**\n   * Set this to `true` if the icon should display inline with other text (like\n   * a paragraph) by applying `vertical-align: bottom`.\n   *\n   * @example\n   * ```tsx\n   * <Typography>\n   *   <InfoIcon inline className=\"rmd-icon--before\" />\n   *   Some additional information around xyz.\n   * </Typography>\n   * ```\n   *\n   * @defaultValue `false`\n   */\n  inline?: boolean;\n}\n\n/** @since 6.0.0 */\nexport interface FontIconClassNameOptions extends SVGIconClassNameOptions {\n  /**\n   * The font icon class name to use.\n   *\n   * @defaultValue `\"material-icons\"`\n   */\n  iconClassName?: string;\n}\n\n/** @since 6.0.0 */\nexport interface MaterialIconClassNameOptions extends SVGIconClassNameOptions {\n  family: MaterialIconFamily;\n}\n\n/** @since 6.0.0 */\nexport interface MaterialSymbolClassNameOptions\n  extends SVGIconClassNameOptions {\n  family: MaterialSymbolFamily;\n}\n\n/** @since 6.0.0 */\nexport type IconClassNameOptions =\n  | ({ type: \"font\" } & FontIconClassNameOptions)\n  | ({ type: \"svg\" } & SVGIconClassNameOptions)\n  | ({ type: \"material\" } & MaterialIconClassNameOptions)\n  | ({ type: \"symbol\" } & MaterialSymbolClassNameOptions);\n\n/**\n *\n * @since 6.0.0\n */\nexport function icon(options: IconClassNameOptions): string {\n  const {\n    className,\n    type,\n    theme,\n    family = \"\",\n    dense = false,\n    inline = false,\n    iconClassName,\n  } = options as FontIconClassNameOptions &\n    SVGIconClassNameOptions & {\n      type: \"font\" | \"svg\" | \"symbol\" | \"material\";\n      family?: MaterialIconFamily;\n    };\n\n  const isFont = type === \"font\";\n  const isSvg = type === \"svg\";\n  const isSymbol = type === \"symbol\";\n  const isMaterial = type === \"material\";\n\n  return cnb(\n    styles({\n      svg: isSvg,\n      font: isFont || isMaterial,\n      symbol: isSymbol,\n      vam: inline,\n      dense,\n    }),\n    isSymbol && `material-symbols-${family}`,\n    isMaterial &&\n      `material-icons${\n        family === \"filled\" ? \"\" : `-${family === \"rounded\" ? \"round\" : family}`\n      }`,\n    cssUtils({\n      textColor: theme,\n    }),\n    iconClassName,\n    className\n  );\n}\n\n/** @since 6.0.0 */\nexport interface IconRotatorClassNameOptions {\n  className?: string;\n\n  /**\n   * Boolean if the icon is currently rotated.\n   */\n  rotated: boolean;\n\n  /**\n   * Boolean if changing the {@link rotated} state should no longer transition.\n   *\n   * @defaultValue `false`\n   */\n  disableTransition?: boolean;\n}\n\n/**\n *\n * @since 6.0.0\n */\nexport function iconRotator(options: IconRotatorClassNameOptions): string {\n  const { className, rotated, disableTransition = false } = options;\n\n  return cnb(\n    rotatorStyles({\n      animate: !disableTransition,\n      rotated,\n    }),\n    className\n  );\n}\n"],"names":["cnb","cssUtils","bem","styles","rotatorStyles","icon","options","className","type","theme","family","dense","inline","iconClassName","isFont","isSvg","isSymbol","isMaterial","svg","font","symbol","vam","textColor","iconRotator","rotated","disableTransition","animate"],"mappings":"AAAA,SAASA,GAAG,QAAQ,YAAY;AAEhC,SAA0CC,QAAQ,QAAQ,iBAAiB;AAC3E,SAASC,GAAG,QAAQ,kBAAkB;AAatC,MAAMC,SAASD,IAAI;AACnB,MAAME,gBAAgBF,IAAI;AA0E1B;;;CAGC,GACD,OAAO,SAASG,KAAKC,OAA6B;IAChD,MAAM,EACJC,SAAS,EACTC,IAAI,EACJC,KAAK,EACLC,SAAS,EAAE,EACXC,QAAQ,KAAK,EACbC,SAAS,KAAK,EACdC,aAAa,EACd,GAAGP;IAMJ,MAAMQ,SAASN,SAAS;IACxB,MAAMO,QAAQP,SAAS;IACvB,MAAMQ,WAAWR,SAAS;IAC1B,MAAMS,aAAaT,SAAS;IAE5B,OAAOR,IACLG,OAAO;QACLe,KAAKH;QACLI,MAAML,UAAUG;QAChBG,QAAQJ;QACRK,KAAKT;QACLD;IACF,IACAK,YAAY,CAAC,iBAAiB,EAAEN,QAAQ,EACxCO,cACE,CAAC,cAAc,EACbP,WAAW,WAAW,KAAK,CAAC,CAAC,EAAEA,WAAW,YAAY,UAAUA,QAAQ,EACxE,EACJT,SAAS;QACPqB,WAAWb;IACb,IACAI,eACAN;AAEJ;AAmBA;;;CAGC,GACD,OAAO,SAASgB,YAAYjB,OAAoC;IAC9D,MAAM,EAAEC,SAAS,EAAEiB,OAAO,EAAEC,oBAAoB,KAAK,EAAE,GAAGnB;IAE1D,OAAON,IACLI,cAAc;QACZsB,SAAS,CAACD;QACVD;IACF,IACAjB;AAEJ"}
+{"version":3,"sources":["../../src/icon/styles.ts"],"sourcesContent":["import { cnb } from \"cnbuilder\";\n\nimport { type TextColor, type ThemeColor, cssUtils } from \"../cssUtils.js\";\nimport { bem } from \"../utils/bem.js\";\nimport {\n  type MaterialIconFamily,\n  type MaterialSymbolFamily,\n} from \"./material.js\";\n\ndeclare module \"react\" {\n  interface CSSProperties {\n    \"--rmd-icon-color\"?: string;\n    \"--rmd-icon-size\"?: string | number;\n    \"--rmd-icon-dense-size\"?: string | number;\n    \"--rmd-icon-spacing\"?: string | number;\n    \"--rmd-icon-rotate-from\"?: string | number;\n    \"--rmd-icon-rotate-to\"?: string | number;\n  }\n}\n\nconst styles = bem(\"rmd-icon\");\nconst rotatorStyles = bem(\"rmd-icon-rotator\");\n\n/** @since 6.0.0 */\nexport interface SVGIconClassNameOptions {\n  className?: string;\n\n  /**\n   * An optional theme color to apply to the icon. When this is `undefined`, the\n   * default icon color will be used instead.\n   *\n   * - `primary -> $primary-color`\n   * - `secondary -> $secondary-color`\n   * - `warning -> $warning-color`\n   * - `success -> $success-color`\n   * - `error -> $error-color`\n   * - `text-primary -> $text-primary-color`\n   * - `text-secondary -> $text-primary-color`\n   * - `text-hint -> $text-hint-color`\n   * - `text-disabled -> $text-disabled-color`\n   */\n  theme?: ThemeColor | TextColor;\n\n  /**\n   * Boolean if the font icon should use the dense spec.\n   *\n   * @defaultValue `false`\n   */\n  dense?: boolean;\n\n  /**\n   * Set this to `true` if the icon should display inline with other text (like\n   * a paragraph) by applying `vertical-align: bottom`.\n   *\n   * @example\n   * ```tsx\n   * <Typography>\n   *   <InfoIcon inline className=\"rmd-icon--before\" />\n   *   Some additional information around xyz.\n   * </Typography>\n   * ```\n   *\n   * @defaultValue `false`\n   */\n  inline?: boolean;\n}\n\n/** @since 6.0.0 */\nexport interface FontIconClassNameOptions extends SVGIconClassNameOptions {\n  /**\n   * The font icon class name to use.\n   *\n   * @defaultValue `\"material-icons\"`\n   */\n  iconClassName?: string;\n}\n\n/** @since 6.0.0 */\nexport interface MaterialIconClassNameOptions extends SVGIconClassNameOptions {\n  family: MaterialIconFamily;\n}\n\n/** @since 6.0.0 */\nexport interface MaterialSymbolClassNameOptions\n  extends SVGIconClassNameOptions {\n  family: MaterialSymbolFamily;\n}\n\n/** @since 6.0.0 */\nexport type IconClassNameOptions =\n  | ({ type: \"font\" } & FontIconClassNameOptions)\n  | ({ type: \"svg\" } & SVGIconClassNameOptions)\n  | ({ type: \"material\" } & MaterialIconClassNameOptions)\n  | ({ type: \"symbol\" } & MaterialSymbolClassNameOptions);\n\n/**\n *\n * @since 6.0.0\n */\nexport function icon(options: IconClassNameOptions): string {\n  const {\n    className,\n    type,\n    theme,\n    family = \"\",\n    dense = false,\n    inline = false,\n    iconClassName,\n  } = options as FontIconClassNameOptions &\n    SVGIconClassNameOptions & {\n      type: \"font\" | \"svg\" | \"symbol\" | \"material\";\n      family?: MaterialIconFamily;\n    };\n\n  const isFont = type === \"font\";\n  const isSvg = type === \"svg\";\n  const isSymbol = type === \"symbol\";\n  const isMaterial = type === \"material\";\n\n  return cnb(\n    styles({\n      svg: isSvg,\n      font: isFont || isMaterial,\n      symbol: isSymbol,\n      vam: inline,\n      dense,\n    }),\n    isSymbol && `material-symbols-${family}`,\n    isMaterial &&\n      `material-icons${\n        family === \"filled\" ? \"\" : `-${family === \"rounded\" ? \"round\" : family}`\n      }`,\n    cssUtils({\n      textColor: theme,\n    }),\n    iconClassName,\n    className\n  );\n}\n\n/** @since 6.0.0 */\nexport interface IconRotatorClassNameOptions {\n  className?: string;\n\n  /**\n   * Boolean if the icon is currently rotated.\n   */\n  rotated: boolean;\n\n  /**\n   * Boolean if changing the {@link rotated} state should no longer transition.\n   *\n   * @defaultValue `false`\n   */\n  disableTransition?: boolean;\n}\n\n/**\n *\n * @since 6.0.0\n */\nexport function iconRotator(options: IconRotatorClassNameOptions): string {\n  const { className, rotated, disableTransition = false } = options;\n\n  return cnb(\n    rotatorStyles({\n      animate: !disableTransition,\n      rotated,\n    }),\n    className\n  );\n}\n"],"names":["cnb","cssUtils","bem","styles","rotatorStyles","icon","options","className","type","theme","family","dense","inline","iconClassName","isFont","isSvg","isSymbol","isMaterial","svg","font","symbol","vam","textColor","iconRotator","rotated","disableTransition","animate"],"mappings":"AAAA,SAASA,GAAG,QAAQ,YAAY;AAEhC,SAA0CC,QAAQ,QAAQ,iBAAiB;AAC3E,SAASC,GAAG,QAAQ,kBAAkB;AAiBtC,MAAMC,SAASD,IAAI;AACnB,MAAME,gBAAgBF,IAAI;AA0E1B;;;CAGC,GACD,OAAO,SAASG,KAAKC,OAA6B;IAChD,MAAM,EACJC,SAAS,EACTC,IAAI,EACJC,KAAK,EACLC,SAAS,EAAE,EACXC,QAAQ,KAAK,EACbC,SAAS,KAAK,EACdC,aAAa,EACd,GAAGP;IAMJ,MAAMQ,SAASN,SAAS;IACxB,MAAMO,QAAQP,SAAS;IACvB,MAAMQ,WAAWR,SAAS;IAC1B,MAAMS,aAAaT,SAAS;IAE5B,OAAOR,IACLG,OAAO;QACLe,KAAKH;QACLI,MAAML,UAAUG;QAChBG,QAAQJ;QACRK,KAAKT;QACLD;IACF,IACAK,YAAY,CAAC,iBAAiB,EAAEN,QAAQ,EACxCO,cACE,CAAC,cAAc,EACbP,WAAW,WAAW,KAAK,CAAC,CAAC,EAAEA,WAAW,YAAY,UAAUA,QAAQ,EACxE,EACJT,SAAS;QACPqB,WAAWb;IACb,IACAI,eACAN;AAEJ;AAmBA;;;CAGC,GACD,OAAO,SAASgB,YAAYjB,OAAoC;IAC9D,MAAM,EAAEC,SAAS,EAAEiB,OAAO,EAAEC,oBAAoB,KAAK,EAAE,GAAGnB;IAE1D,OAAON,IACLI,cAAc;QACZsB,SAAS,CAACD;QACVD;IACF,IACAjB;AAEJ"}

package/dist/interaction/Ripple.d.ts

@@ -2,9 +2,18 @@ import { type ReactElement } from "react";
 import { type CSSTransitionClassNames, type TransitionTimeout } from "../transition/types.js";
 import { type RippleState, type RippleTransitionCallbacks } from "./types.js";
 /** @internal */
-export declare const DEFAULT_RIPPLE_CLASSNAMES: Readonly<CSSTransitionClassNames>;
+export declare const DEFAULT_RIPPLE_CLASSNAMES: {
+    readonly enter: "rmd-ripple--animating";
+    readonly enterActive: "rmd-ripple--scaling";
+    readonly enterDone: "rmd-ripple--animating rmd-ripple--scaling";
+    readonly exit: "rmd-ripple--animating rmd-ripple--scaling";
+    readonly exitActive: "rmd-ripple--fading";
+};
 /** @internal */
-export declare const DEFAULT_RIPPLE_TIMEOUT: Readonly<TransitionTimeout>;
+export declare const DEFAULT_RIPPLE_TIMEOUT: {
+    readonly enter: 150;
+    readonly exit: 300;
+};
 /** @internal */
 export interface RippleProps extends RippleTransitionCallbacks {
     className?: string;

package/dist/interaction/Ripple.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/interaction/Ripple.tsx"],"sourcesContent":["\"use client\";\n\nimport { cnb } from \"cnbuilder\";\nimport { type ReactElement } from \"react\";\n\nimport {\n  type CSSTransitionClassNames,\n  type TransitionTimeout,\n} from \"../transition/types.js\";\nimport { useCSSTransition } from \"../transition/useCSSTransition.js\";\nimport { type RippleState, type RippleTransitionCallbacks } from \"./types.js\";\n\n/** @internal */\nexport const DEFAULT_RIPPLE_CLASSNAMES: Readonly<CSSTransitionClassNames> = {\n  enter: \"rmd-ripple--animating\",\n  enterActive: \"rmd-ripple--scaling\",\n  enterDone: \"rmd-ripple--animating rmd-ripple--scaling\",\n  exit: \"rmd-ripple--animating rmd-ripple--scaling\",\n  exitActive: \"rmd-ripple--fading\",\n};\n\n/** @internal */\nexport const DEFAULT_RIPPLE_TIMEOUT: Readonly<TransitionTimeout> = {\n  enter: 150,\n  exit: 300,\n};\n\n/** @internal */\nexport interface RippleProps extends RippleTransitionCallbacks {\n  className?: string;\n  timeout?: TransitionTimeout;\n  classNames?: CSSTransitionClassNames;\n  ripple: RippleState;\n}\n\n/**\n * **Client Component**\n *\n * This component should only be used by the `RippleContainer` component.\n *\n * @internal\n */\nexport function Ripple(props: RippleProps): ReactElement {\n  const {\n    className,\n    timeout = DEFAULT_RIPPLE_TIMEOUT,\n    classNames = DEFAULT_RIPPLE_CLASSNAMES,\n    ripple,\n    onEntered,\n    onExited,\n  } = props;\n  const { style, exiting } = ripple;\n  const { elementProps, rendered } = useCSSTransition({\n    appear: true,\n    className: cnb(\"rmd-ripple\", className),\n    transitionIn: !exiting,\n    timeout,\n    classNames,\n    onEntered() {\n      onEntered(ripple);\n    },\n    onExited() {\n      onExited(ripple);\n    },\n  });\n\n  return <>{rendered && <span style={style} {...elementProps} />}</>;\n}\n"],"names":["cnb","useCSSTransition","DEFAULT_RIPPLE_CLASSNAMES","enter","enterActive","enterDone","exit","exitActive","DEFAULT_RIPPLE_TIMEOUT","Ripple","props","className","timeout","classNames","ripple","onEntered","onExited","style","exiting","elementProps","rendered","appear","transitionIn","span"],"mappings":"AAAA;;AAEA,SAASA,GAAG,QAAQ,YAAY;AAOhC,SAASC,gBAAgB,QAAQ,oCAAoC;AAGrE,cAAc,GACd,OAAO,MAAMC,4BAA+D;IAC1EC,OAAO;IACPC,aAAa;IACbC,WAAW;IACXC,MAAM;IACNC,YAAY;AACd,EAAE;AAEF,cAAc,GACd,OAAO,MAAMC,yBAAsD;IACjEL,OAAO;IACPG,MAAM;AACR,EAAE;AAUF;;;;;;CAMC,GACD,OAAO,SAASG,OAAOC,KAAkB;IACvC,MAAM,EACJC,SAAS,EACTC,UAAUJ,sBAAsB,EAChCK,aAAaX,yBAAyB,EACtCY,MAAM,EACNC,SAAS,EACTC,QAAQ,EACT,GAAGN;IACJ,MAAM,EAAEO,KAAK,EAAEC,OAAO,EAAE,GAAGJ;IAC3B,MAAM,EAAEK,YAAY,EAAEC,QAAQ,EAAE,GAAGnB,iBAAiB;QAClDoB,QAAQ;QACRV,WAAWX,IAAI,cAAcW;QAC7BW,cAAc,CAACJ;QACfN;QACAC;QACAE;YACEA,UAAUD;QACZ;QACAE;YACEA,SAASF;QACX;IACF;IAEA,qBAAO;kBAAGM,0BAAY,KAACG;YAAKN,OAAOA;YAAQ,GAAGE,YAAY;;;AAC5D"}
+{"version":3,"sources":["../../src/interaction/Ripple.tsx"],"sourcesContent":["\"use client\";\n\nimport { cnb } from \"cnbuilder\";\nimport { type ReactElement } from \"react\";\n\nimport {\n  type CSSTransitionClassNames,\n  type TransitionTimeout,\n} from \"../transition/types.js\";\nimport { useCSSTransition } from \"../transition/useCSSTransition.js\";\nimport { type RippleState, type RippleTransitionCallbacks } from \"./types.js\";\n\n/** @internal */\nexport const DEFAULT_RIPPLE_CLASSNAMES = {\n  enter: \"rmd-ripple--animating\",\n  enterActive: \"rmd-ripple--scaling\",\n  enterDone: \"rmd-ripple--animating rmd-ripple--scaling\",\n  exit: \"rmd-ripple--animating rmd-ripple--scaling\",\n  exitActive: \"rmd-ripple--fading\",\n} as const satisfies CSSTransitionClassNames;\n\n/** @internal */\nexport const DEFAULT_RIPPLE_TIMEOUT = {\n  enter: 150,\n  exit: 300,\n} as const satisfies TransitionTimeout;\n\n/** @internal */\nexport interface RippleProps extends RippleTransitionCallbacks {\n  className?: string;\n  timeout?: TransitionTimeout;\n  classNames?: CSSTransitionClassNames;\n  ripple: RippleState;\n}\n\n/**\n * **Client Component**\n *\n * This component should only be used by the `RippleContainer` component.\n *\n * @internal\n */\nexport function Ripple(props: RippleProps): ReactElement {\n  const {\n    className,\n    timeout = DEFAULT_RIPPLE_TIMEOUT,\n    classNames = DEFAULT_RIPPLE_CLASSNAMES,\n    ripple,\n    onEntered,\n    onExited,\n  } = props;\n  const { style, exiting } = ripple;\n  const { elementProps, rendered } = useCSSTransition({\n    appear: true,\n    className: cnb(\"rmd-ripple\", className),\n    transitionIn: !exiting,\n    timeout,\n    classNames,\n    onEntered() {\n      onEntered(ripple);\n    },\n    onExited() {\n      onExited(ripple);\n    },\n  });\n\n  return <>{rendered && <span style={style} {...elementProps} />}</>;\n}\n"],"names":["cnb","useCSSTransition","DEFAULT_RIPPLE_CLASSNAMES","enter","enterActive","enterDone","exit","exitActive","DEFAULT_RIPPLE_TIMEOUT","Ripple","props","className","timeout","classNames","ripple","onEntered","onExited","style","exiting","elementProps","rendered","appear","transitionIn","span"],"mappings":"AAAA;;AAEA,SAASA,GAAG,QAAQ,YAAY;AAOhC,SAASC,gBAAgB,QAAQ,oCAAoC;AAGrE,cAAc,GACd,OAAO,MAAMC,4BAA4B;IACvCC,OAAO;IACPC,aAAa;IACbC,WAAW;IACXC,MAAM;IACNC,YAAY;AACd,EAA6C;AAE7C,cAAc,GACd,OAAO,MAAMC,yBAAyB;IACpCL,OAAO;IACPG,MAAM;AACR,EAAuC;AAUvC;;;;;;CAMC,GACD,OAAO,SAASG,OAAOC,KAAkB;IACvC,MAAM,EACJC,SAAS,EACTC,UAAUJ,sBAAsB,EAChCK,aAAaX,yBAAyB,EACtCY,MAAM,EACNC,SAAS,EACTC,QAAQ,EACT,GAAGN;IACJ,MAAM,EAAEO,KAAK,EAAEC,OAAO,EAAE,GAAGJ;IAC3B,MAAM,EAAEK,YAAY,EAAEC,QAAQ,EAAE,GAAGnB,iBAAiB;QAClDoB,QAAQ;QACRV,WAAWX,IAAI,cAAcW;QAC7BW,cAAc,CAACJ;QACfN;QACAC;QACAE;YACEA,UAAUD;QACZ;QACAE;YACEA,SAASF;QACX;IACF;IAEA,qBAAO;kBAAGM,0BAAY,KAACG;YAAKN,OAAOA;YAAQ,GAAGE,YAAY;;;AAC5D"}

package/dist/interaction/UserInteractionModeProvider.d.ts

@@ -32,7 +32,7 @@ export interface UserInteractionModeProviderProps {
  * @example Mount at the root of your app
  * ```tsx
  * import { createRoot } from "react-dom/client";
- * import { UserInteractionModeProvider } from "@react-md/core";
+ * import { UserInteractionModeProvider } from "@react-md/core/interaction/UserInteractionModeProvider";
  * import App from "./App":
  *
  * const container = document.getElementById("root");

package/dist/interaction/UserInteractionModeProvider.js

@@ -31,7 +31,7 @@ const { Provider } = context;
  * @example Mount at the root of your app
  * ```tsx
  * import { createRoot } from "react-dom/client";
- * import { UserInteractionModeProvider } from "@react-md/core";
+ * import { UserInteractionModeProvider } from "@react-md/core/interaction/UserInteractionModeProvider";
  * import App from "./App":
  *
  * const container = document.getElementById("root");

package/dist/interaction/UserInteractionModeProvider.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/interaction/UserInteractionModeProvider.tsx"],"sourcesContent":["\"use client\";\n\nimport {\n  type ReactElement,\n  type ReactNode,\n  createContext,\n  useContext,\n  useEffect,\n  useMemo,\n  useRef,\n  useState,\n} from \"react\";\n\n/**\n * This is the current mode for how your user is interacting with your app. This\n * will be used to determine which type of state styles should be applied at the\n * time of interacting with an element on your page.\n *\n * @defaultValue `\"mouse\"`\n */\nexport type UserInteractionMode = \"keyboard\" | \"mouse\" | \"touch\";\n\n/** @internal */\ninterface UserInteractionModeContext {\n  __root: boolean;\n  mode: UserInteractionMode;\n}\n\nconst context = createContext<UserInteractionModeContext>({\n  __root: false,\n  mode: \"mouse\",\n});\ncontext.displayName = \"UserInteractionMode\";\nconst { Provider } = context;\n\n/**\n * @returns the current user interaction mode\n */\nexport function useUserInteractionMode(): UserInteractionMode {\n  return useContext(context).mode;\n}\n\n/** @internal */\nconst TOUCH_TIMEOUT = 1200;\n\nexport interface UserInteractionModeProviderProps {\n  children: ReactNode;\n}\n\n/**\n * **Client Component**\n *\n * This component is used to determine how a user is interacting with your app\n * to update component functionality and applying the following class names to\n * the `document.body`:\n *\n * - `\"rmd-mouse-mode\"`\n * - `\"rmd-keyboard-mode\"`\n * - `\"rmd-touch-mode\"`\n *\n * Within `react-md`, these classes are used for the following behavior:\n * - only display `:focus` outlines while in `\"rmd-keyboard-mode\"`\n * - do not display `:hover` effects while in `\"rmd-touch-mode\"`\n *\n * @example Mount at the root of your app\n * ```tsx\n * import { createRoot } from \"react-dom/client\";\n * import { UserInteractionModeProvider } from \"@react-md/core\";\n * import App from \"./App\":\n *\n * const container = document.getElementById(\"root\");\n * const root = createRoot(container);\n *\n * root.render(\n *   <UserInteractionModeProvider>\n *     <App />\n *   </UserInteractionModeProvider>\n * );\n * ```\n *\n * @throws \"The `UserInteractionModeProvider` cannot be mounted multiple times.\"\n * if this component is mounted multiple times in your app.\n */\nexport function UserInteractionModeProvider(\n  props: UserInteractionModeProviderProps\n): ReactElement {\n  const { children } = props;\n  const { __root } = useContext(context);\n  if (__root) {\n    throw new Error(\n      \"The `UserInteractionModeProvider` cannot be mounted multiple times.\"\n    );\n  }\n\n  const [mode, setMode] = useState<UserInteractionMode>(\"mouse\");\n  const lastTouchTime = useRef(0);\n  const isTouchContextMenu = useRef(false);\n\n  /**\n   * This effect helps determine the current interaction mode by attaching the\n   * required event listeners to the window. The `mode` will always be defaulted\n   * to `mouse` at first since it has the least possibilities of causing errors\n   * with styles since the mouse-only styles are normally just `:hover` effects.\n   *\n   * ## Switching between modes:\n   *\n   * ### While in `mouse` mode:\n   *\n   * - any `keydown` event will switch to `keyboard` mode\n   *   - this does have the side effect of meta keys also causing the switch over,\n   *     but it feels fine since it helps show the current focus in the document\n   *     as well\n   * - any `touchstart` event will switch to `touch` mode\n   *\n   * ### While in `keyboard` mode:\n   *\n   * - any `mousedown` event will switch to `mouse` mode\n   *   - it is perfectly okay to move the mouse while in keyboard mode, but still\n   *     want to keep the keyboard styles until the user actually starts clicking\n   * - any `touchstart` event will switch to `touch` mode\n   *\n   * ### While in `touch` mode:\n   *\n   * - any `mousemove` event will switch to `mouse` mode, but **only** if there\n   *   hasn't been a `contextmenu` event within the last `1.2s`\n   *   - you can really only switch back to `mouse` mode if you are using the\n   *     devtools to emulate devices OR using a touch-desktop. I don't know how\n   *     common this really is though.\n   *   - touching the screen will always fire a `mousemove` event (which is why\n   *     the `:hover` styles are normally with `rmd-utils-mouse-only`) and even\n   *     after the `contextmenu` event. Normally want to go back to `mouse` mode\n   *     when the mouse re-enters the `window`\n   *\n   * Note: It's currently impossible to switch from `touch` to `keyboard`\n   * immediately. You'd first need to switch to `mouse` and then to `keyboard`. I\n   * don't really know of any use-cases other than the weird touch-desktop stuff\n   * and I have no experience using them.\n   */\n  useEffect(() => {\n    const enableMouseMode = (): void => {\n      setMode(\"mouse\");\n    };\n    const enableKeyboardMode = (): void => {\n      setMode(\"keyboard\");\n    };\n\n    const handleTouchStart = (): void => {\n      lastTouchTime.current = Date.now();\n      isTouchContextMenu.current = false;\n      setMode(\"touch\");\n    };\n\n    const handleMouseMove = (): void => {\n      if (\n        isTouchContextMenu.current ||\n        Date.now() - lastTouchTime.current < TOUCH_TIMEOUT\n      ) {\n        isTouchContextMenu.current = false;\n        return;\n      }\n\n      enableMouseMode();\n    };\n    const handleContextMenu = (): void => {\n      isTouchContextMenu.current = true;\n    };\n\n    const className = `rmd-${mode}-mode`;\n    document.body.classList.add(className);\n    window.addEventListener(\"touchstart\", handleTouchStart, true);\n    if (mode === \"mouse\") {\n      window.addEventListener(\"keydown\", enableKeyboardMode, true);\n    } else if (mode === \"keyboard\") {\n      window.addEventListener(\"mousedown\", enableMouseMode, true);\n    } else {\n      window.addEventListener(\"mousemove\", handleMouseMove, true);\n      window.addEventListener(\"contextmenu\", handleContextMenu, true);\n    }\n\n    return () => {\n      document.body.classList.remove(className);\n      window.removeEventListener(\"touchstart\", handleTouchStart, true);\n      if (mode === \"mouse\") {\n        window.removeEventListener(\"keydown\", enableKeyboardMode, true);\n      } else if (mode === \"keyboard\") {\n        window.removeEventListener(\"mousedown\", enableMouseMode, true);\n      } else {\n        window.removeEventListener(\"mousemove\", handleMouseMove, true);\n        window.removeEventListener(\"contextmenu\", handleContextMenu, true);\n      }\n    };\n  }, [mode]);\n\n  const value = useMemo<UserInteractionModeContext>(\n    () => ({\n      mode,\n      __root: true,\n    }),\n    [mode]\n  );\n  return <Provider value={value}>{children}</Provider>;\n}\n"],"names":["createContext","useContext","useEffect","useMemo","useRef","useState","context","__root","mode","displayName","Provider","useUserInteractionMode","TOUCH_TIMEOUT","UserInteractionModeProvider","props","children","Error","setMode","lastTouchTime","isTouchContextMenu","enableMouseMode","enableKeyboardMode","handleTouchStart","current","Date","now","handleMouseMove","handleContextMenu","className","document","body","classList","add","window","addEventListener","remove","removeEventListener","value"],"mappings":"AAAA;;AAEA,SAGEA,aAAa,EACbC,UAAU,EACVC,SAAS,EACTC,OAAO,EACPC,MAAM,EACNC,QAAQ,QACH,QAAQ;AAiBf,MAAMC,wBAAUN,cAA0C;IACxDO,QAAQ;IACRC,MAAM;AACR;AACAF,QAAQG,WAAW,GAAG;AACtB,MAAM,EAAEC,QAAQ,EAAE,GAAGJ;AAErB;;CAEC,GACD,OAAO,SAASK;IACd,OAAOV,WAAWK,SAASE,IAAI;AACjC;AAEA,cAAc,GACd,MAAMI,gBAAgB;AAMtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiCC,GACD,OAAO,SAASC,4BACdC,KAAuC;IAEvC,MAAM,EAAEC,QAAQ,EAAE,GAAGD;IACrB,MAAM,EAAEP,MAAM,EAAE,GAAGN,WAAWK;IAC9B,IAAIC,QAAQ;QACV,MAAM,IAAIS,MACR;IAEJ;IAEA,MAAM,CAACR,MAAMS,QAAQ,GAAGZ,SAA8B;IACtD,MAAMa,gBAAgBd,OAAO;IAC7B,MAAMe,qBAAqBf,OAAO;IAElC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCC,GACDF,UAAU;QACR,MAAMkB,kBAAkB;YACtBH,QAAQ;QACV;QACA,MAAMI,qBAAqB;YACzBJ,QAAQ;QACV;QAEA,MAAMK,mBAAmB;YACvBJ,cAAcK,OAAO,GAAGC,KAAKC,GAAG;YAChCN,mBAAmBI,OAAO,GAAG;YAC7BN,QAAQ;QACV;QAEA,MAAMS,kBAAkB;YACtB,IACEP,mBAAmBI,OAAO,IAC1BC,KAAKC,GAAG,KAAKP,cAAcK,OAAO,GAAGX,eACrC;gBACAO,mBAAmBI,OAAO,GAAG;gBAC7B;YACF;YAEAH;QACF;QACA,MAAMO,oBAAoB;YACxBR,mBAAmBI,OAAO,GAAG;QAC/B;QAEA,MAAMK,YAAY,CAAC,IAAI,EAAEpB,KAAK,KAAK,CAAC;QACpCqB,SAASC,IAAI,CAACC,SAAS,CAACC,GAAG,CAACJ;QAC5BK,OAAOC,gBAAgB,CAAC,cAAcZ,kBAAkB;QACxD,IAAId,SAAS,SAAS;YACpByB,OAAOC,gBAAgB,CAAC,WAAWb,oBAAoB;QACzD,OAAO,IAAIb,SAAS,YAAY;YAC9ByB,OAAOC,gBAAgB,CAAC,aAAad,iBAAiB;QACxD,OAAO;YACLa,OAAOC,gBAAgB,CAAC,aAAaR,iBAAiB;YACtDO,OAAOC,gBAAgB,CAAC,eAAeP,mBAAmB;QAC5D;QAEA,OAAO;YACLE,SAASC,IAAI,CAACC,SAAS,CAACI,MAAM,CAACP;YAC/BK,OAAOG,mBAAmB,CAAC,cAAcd,kBAAkB;YAC3D,IAAId,SAAS,SAAS;gBACpByB,OAAOG,mBAAmB,CAAC,WAAWf,oBAAoB;YAC5D,OAAO,IAAIb,SAAS,YAAY;gBAC9ByB,OAAOG,mBAAmB,CAAC,aAAahB,iBAAiB;YAC3D,OAAO;gBACLa,OAAOG,mBAAmB,CAAC,aAAaV,iBAAiB;gBACzDO,OAAOG,mBAAmB,CAAC,eAAeT,mBAAmB;YAC/D;QACF;IACF,GAAG;QAACnB;KAAK;IAET,MAAM6B,QAAQlC,QACZ,IAAO,CAAA;YACLK;YACAD,QAAQ;QACV,CAAA,GACA;QAACC;KAAK;IAER,qBAAO,KAACE;QAAS2B,OAAOA;kBAAQtB;;AAClC"}
+{"version":3,"sources":["../../src/interaction/UserInteractionModeProvider.tsx"],"sourcesContent":["\"use client\";\n\nimport {\n  type ReactElement,\n  type ReactNode,\n  createContext,\n  useContext,\n  useEffect,\n  useMemo,\n  useRef,\n  useState,\n} from \"react\";\n\n/**\n * This is the current mode for how your user is interacting with your app. This\n * will be used to determine which type of state styles should be applied at the\n * time of interacting with an element on your page.\n *\n * @defaultValue `\"mouse\"`\n */\nexport type UserInteractionMode = \"keyboard\" | \"mouse\" | \"touch\";\n\n/** @internal */\ninterface UserInteractionModeContext {\n  __root: boolean;\n  mode: UserInteractionMode;\n}\n\nconst context = createContext<UserInteractionModeContext>({\n  __root: false,\n  mode: \"mouse\",\n});\ncontext.displayName = \"UserInteractionMode\";\nconst { Provider } = context;\n\n/**\n * @returns the current user interaction mode\n */\nexport function useUserInteractionMode(): UserInteractionMode {\n  return useContext(context).mode;\n}\n\n/** @internal */\nconst TOUCH_TIMEOUT = 1200;\n\nexport interface UserInteractionModeProviderProps {\n  children: ReactNode;\n}\n\n/**\n * **Client Component**\n *\n * This component is used to determine how a user is interacting with your app\n * to update component functionality and applying the following class names to\n * the `document.body`:\n *\n * - `\"rmd-mouse-mode\"`\n * - `\"rmd-keyboard-mode\"`\n * - `\"rmd-touch-mode\"`\n *\n * Within `react-md`, these classes are used for the following behavior:\n * - only display `:focus` outlines while in `\"rmd-keyboard-mode\"`\n * - do not display `:hover` effects while in `\"rmd-touch-mode\"`\n *\n * @example Mount at the root of your app\n * ```tsx\n * import { createRoot } from \"react-dom/client\";\n * import { UserInteractionModeProvider } from \"@react-md/core/interaction/UserInteractionModeProvider\";\n * import App from \"./App\":\n *\n * const container = document.getElementById(\"root\");\n * const root = createRoot(container);\n *\n * root.render(\n *   <UserInteractionModeProvider>\n *     <App />\n *   </UserInteractionModeProvider>\n * );\n * ```\n *\n * @throws \"The `UserInteractionModeProvider` cannot be mounted multiple times.\"\n * if this component is mounted multiple times in your app.\n */\nexport function UserInteractionModeProvider(\n  props: UserInteractionModeProviderProps\n): ReactElement {\n  const { children } = props;\n  const { __root } = useContext(context);\n  if (__root) {\n    throw new Error(\n      \"The `UserInteractionModeProvider` cannot be mounted multiple times.\"\n    );\n  }\n\n  const [mode, setMode] = useState<UserInteractionMode>(\"mouse\");\n  const lastTouchTime = useRef(0);\n  const isTouchContextMenu = useRef(false);\n\n  /**\n   * This effect helps determine the current interaction mode by attaching the\n   * required event listeners to the window. The `mode` will always be defaulted\n   * to `mouse` at first since it has the least possibilities of causing errors\n   * with styles since the mouse-only styles are normally just `:hover` effects.\n   *\n   * ## Switching between modes:\n   *\n   * ### While in `mouse` mode:\n   *\n   * - any `keydown` event will switch to `keyboard` mode\n   *   - this does have the side effect of meta keys also causing the switch over,\n   *     but it feels fine since it helps show the current focus in the document\n   *     as well\n   * - any `touchstart` event will switch to `touch` mode\n   *\n   * ### While in `keyboard` mode:\n   *\n   * - any `mousedown` event will switch to `mouse` mode\n   *   - it is perfectly okay to move the mouse while in keyboard mode, but still\n   *     want to keep the keyboard styles until the user actually starts clicking\n   * - any `touchstart` event will switch to `touch` mode\n   *\n   * ### While in `touch` mode:\n   *\n   * - any `mousemove` event will switch to `mouse` mode, but **only** if there\n   *   hasn't been a `contextmenu` event within the last `1.2s`\n   *   - you can really only switch back to `mouse` mode if you are using the\n   *     devtools to emulate devices OR using a touch-desktop. I don't know how\n   *     common this really is though.\n   *   - touching the screen will always fire a `mousemove` event (which is why\n   *     the `:hover` styles are normally with `rmd-utils-mouse-only`) and even\n   *     after the `contextmenu` event. Normally want to go back to `mouse` mode\n   *     when the mouse re-enters the `window`\n   *\n   * Note: It's currently impossible to switch from `touch` to `keyboard`\n   * immediately. You'd first need to switch to `mouse` and then to `keyboard`. I\n   * don't really know of any use-cases other than the weird touch-desktop stuff\n   * and I have no experience using them.\n   */\n  useEffect(() => {\n    const enableMouseMode = (): void => {\n      setMode(\"mouse\");\n    };\n    const enableKeyboardMode = (): void => {\n      setMode(\"keyboard\");\n    };\n\n    const handleTouchStart = (): void => {\n      lastTouchTime.current = Date.now();\n      isTouchContextMenu.current = false;\n      setMode(\"touch\");\n    };\n\n    const handleMouseMove = (): void => {\n      if (\n        isTouchContextMenu.current ||\n        Date.now() - lastTouchTime.current < TOUCH_TIMEOUT\n      ) {\n        isTouchContextMenu.current = false;\n        return;\n      }\n\n      enableMouseMode();\n    };\n    const handleContextMenu = (): void => {\n      isTouchContextMenu.current = true;\n    };\n\n    const className = `rmd-${mode}-mode`;\n    document.body.classList.add(className);\n    window.addEventListener(\"touchstart\", handleTouchStart, true);\n    if (mode === \"mouse\") {\n      window.addEventListener(\"keydown\", enableKeyboardMode, true);\n    } else if (mode === \"keyboard\") {\n      window.addEventListener(\"mousedown\", enableMouseMode, true);\n    } else {\n      window.addEventListener(\"mousemove\", handleMouseMove, true);\n      window.addEventListener(\"contextmenu\", handleContextMenu, true);\n    }\n\n    return () => {\n      document.body.classList.remove(className);\n      window.removeEventListener(\"touchstart\", handleTouchStart, true);\n      if (mode === \"mouse\") {\n        window.removeEventListener(\"keydown\", enableKeyboardMode, true);\n      } else if (mode === \"keyboard\") {\n        window.removeEventListener(\"mousedown\", enableMouseMode, true);\n      } else {\n        window.removeEventListener(\"mousemove\", handleMouseMove, true);\n        window.removeEventListener(\"contextmenu\", handleContextMenu, true);\n      }\n    };\n  }, [mode]);\n\n  const value = useMemo<UserInteractionModeContext>(\n    () => ({\n      mode,\n      __root: true,\n    }),\n    [mode]\n  );\n  return <Provider value={value}>{children}</Provider>;\n}\n"],"names":["createContext","useContext","useEffect","useMemo","useRef","useState","context","__root","mode","displayName","Provider","useUserInteractionMode","TOUCH_TIMEOUT","UserInteractionModeProvider","props","children","Error","setMode","lastTouchTime","isTouchContextMenu","enableMouseMode","enableKeyboardMode","handleTouchStart","current","Date","now","handleMouseMove","handleContextMenu","className","document","body","classList","add","window","addEventListener","remove","removeEventListener","value"],"mappings":"AAAA;;AAEA,SAGEA,aAAa,EACbC,UAAU,EACVC,SAAS,EACTC,OAAO,EACPC,MAAM,EACNC,QAAQ,QACH,QAAQ;AAiBf,MAAMC,wBAAUN,cAA0C;IACxDO,QAAQ;IACRC,MAAM;AACR;AACAF,QAAQG,WAAW,GAAG;AACtB,MAAM,EAAEC,QAAQ,EAAE,GAAGJ;AAErB;;CAEC,GACD,OAAO,SAASK;IACd,OAAOV,WAAWK,SAASE,IAAI;AACjC;AAEA,cAAc,GACd,MAAMI,gBAAgB;AAMtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiCC,GACD,OAAO,SAASC,4BACdC,KAAuC;IAEvC,MAAM,EAAEC,QAAQ,EAAE,GAAGD;IACrB,MAAM,EAAEP,MAAM,EAAE,GAAGN,WAAWK;IAC9B,IAAIC,QAAQ;QACV,MAAM,IAAIS,MACR;IAEJ;IAEA,MAAM,CAACR,MAAMS,QAAQ,GAAGZ,SAA8B;IACtD,MAAMa,gBAAgBd,OAAO;IAC7B,MAAMe,qBAAqBf,OAAO;IAElC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCC,GACDF,UAAU;QACR,MAAMkB,kBAAkB;YACtBH,QAAQ;QACV;QACA,MAAMI,qBAAqB;YACzBJ,QAAQ;QACV;QAEA,MAAMK,mBAAmB;YACvBJ,cAAcK,OAAO,GAAGC,KAAKC,GAAG;YAChCN,mBAAmBI,OAAO,GAAG;YAC7BN,QAAQ;QACV;QAEA,MAAMS,kBAAkB;YACtB,IACEP,mBAAmBI,OAAO,IAC1BC,KAAKC,GAAG,KAAKP,cAAcK,OAAO,GAAGX,eACrC;gBACAO,mBAAmBI,OAAO,GAAG;gBAC7B;YACF;YAEAH;QACF;QACA,MAAMO,oBAAoB;YACxBR,mBAAmBI,OAAO,GAAG;QAC/B;QAEA,MAAMK,YAAY,CAAC,IAAI,EAAEpB,KAAK,KAAK,CAAC;QACpCqB,SAASC,IAAI,CAACC,SAAS,CAACC,GAAG,CAACJ;QAC5BK,OAAOC,gBAAgB,CAAC,cAAcZ,kBAAkB;QACxD,IAAId,SAAS,SAAS;YACpByB,OAAOC,gBAAgB,CAAC,WAAWb,oBAAoB;QACzD,OAAO,IAAIb,SAAS,YAAY;YAC9ByB,OAAOC,gBAAgB,CAAC,aAAad,iBAAiB;QACxD,OAAO;YACLa,OAAOC,gBAAgB,CAAC,aAAaR,iBAAiB;YACtDO,OAAOC,gBAAgB,CAAC,eAAeP,mBAAmB;QAC5D;QAEA,OAAO;YACLE,SAASC,IAAI,CAACC,SAAS,CAACI,MAAM,CAACP;YAC/BK,OAAOG,mBAAmB,CAAC,cAAcd,kBAAkB;YAC3D,IAAId,SAAS,SAAS;gBACpByB,OAAOG,mBAAmB,CAAC,WAAWf,oBAAoB;YAC5D,OAAO,IAAIb,SAAS,YAAY;gBAC9ByB,OAAOG,mBAAmB,CAAC,aAAahB,iBAAiB;YAC3D,OAAO;gBACLa,OAAOG,mBAAmB,CAAC,aAAaV,iBAAiB;gBACzDO,OAAOG,mBAAmB,CAAC,eAAeT,mBAAmB;YAC/D;QACF;IACF,GAAG;QAACnB;KAAK;IAET,MAAM6B,QAAQlC,QACZ,IAAO,CAAA;YACLK;YACAD,QAAQ;QACV,CAAA,GACA;QAACC;KAAK;IAER,qBAAO,KAACE;QAAS2B,OAAOA;kBAAQtB;;AAClC"}

package/dist/interaction/_interaction.scss

@@ -1,3 +1,7 @@
+////
+/// @group interaction
+////
+
 @use "sass:map";
 @use "sass:list";
 @use "../utils";
@@ -5,22 +9,71 @@
 @use "../theme/theme";
 @use "../transition/transition";
 
-/// ripple | press | both | none
+/// This should be one of:
+/// - `ripple`
+/// - `press`
+/// - `both`
+/// - `none`
+///
+/// @type String
 $mode: ripple !default;
-$disable-surface: false !default;
-$disable-outline-offset: false !default;
-$disable-focus-background: false !default;
-$disable-ripple-inset-var: false !default;
-$disable-ripple-border-radius-var: false !default;
-$disable-surface-inset-var: $disable-surface !default;
-$disable-surface-border-radius-var: $disable-surface !default;
 
-$_disable-ripple: not
+/// Convenience feature flag check for ripples
+/// @type Boolean
+$disable-ripple: not
   list.index(
     (ripple, both),
     utils.validate((ripple, press, both, none), $mode, "interaction mode")
   );
 
+/// Set to `true` if the interaction surface styles should not be created. This
+/// includes the:
+///
+/// - `.rmd-interaction-surface` class
+/// - `use-light-surface` and `use-dark-surface` mixins
+/// - `hover-background-color`
+/// - `focus-background-color`
+/// - `press-background-color`
+/// - `selected-background-color`
+///
+/// @type Boolean
+$disable-surface: false !default;
+
+/// Set to `true` if the `outline` styles should not also apply an
+/// `outline-offset`.
+/// @type Boolean
+$disable-outline-offset: false !default;
+
+/// Set to `true` if the default focus styles should not also change the
+/// background color of the element.
+///
+/// @type Boolean
+$disable-focus-background: false !default;
+
+/// Set to `true` if not using the interaction ripple behavior.
+/// @type Boolean
+$disable-ripple-inset-var: $disable-ripple !default;
+
+/// Set to `true` if not using the interaction ripple behavior.
+/// @type Boolean
+$disable-ripple-border-radius-var: $disable-ripple !default;
+
+/// Set this to `true` if the interaction surface background inset should not
+/// be configurable through custom CSS properties.
+///
+/// @type Boolean
+$disable-surface-inset-var: $disable-surface !default;
+
+/// Set this to `true` if the interaction surface border-radius should not be
+/// configurable through custom CSS properties.
+///
+/// @type Boolean
+$disable-surface-border-radius-var: $disable-surface !default;
+
+/// The class name to apply while an element is pressed and using the
+/// `useElementInteraction` hook.
+///
+/// @type String
 $pressed-class-name: "rmd-pressed";
 
 /// Setting this value to `true` will update the styles for all interactable
@@ -36,88 +89,192 @@ $pressed-class-name: "rmd-pressed";
 /// This helps improve the legibility of the content since the normal
 /// interaction states apply an overlay with some opacity for the different
 /// states.
+///
+/// @type Boolean
 $disable-higher-contrast: false !default;
+
+/// The base interaction background color to apply when an element is on a
+/// light surface.
+/// @type Color
 $light-surface-base-background-color: #000 !default;
+
+/// The base interaction background color to apply when an element is on a
+/// dark surface.
+/// @type Color
 $dark-surface-base-background-color: #fff !default;
 
+/// The default color to use while elements are focused.
+/// @type Color
 $focus-color: colors.$blue-500 !default;
+
+/// The default outline/box-shadow width while elements are focused.
+/// @type Number
 $focus-width: 0.125rem !default;
+
+/// Set to `true` if focus behavior should use `box-shadow` instead of
+/// `outline`.
+/// @type Boolean
 $focus-box-shadow: false !default;
 
+/// The base interaction background color to apply when an element is on a
+/// light surface.
+/// @type Color
 $light-surface-ripple-background-color: rgba(
   $light-surface-base-background-color,
   0.08
 ) !default;
+/// The base interaction background color to apply when an element is on a
+/// light surface.
+/// @type Color
 $dark-surface-ripple-background-color: rgba(
   $dark-surface-base-background-color,
   0.12
 ) !default;
+
+/// The default background color for interaction ripples.
+/// @type Color
 $ripple-background-color: theme.get-default-color(
   $light-surface-ripple-background-color,
   $dark-surface-ripple-background-color
 ) !default;
+
+/// The ripple animation duration.
+/// @type Number
 $ripple-transform-duration: 0.45s !default;
+
+/// The ripple opacity animation duration. This should normally be shorter than
+/// the `$ripple-transform-duration` so the ripple is fully visible before the
+/// transition completes.
+///
+/// @type Number
 $ripple-opacity-duration: 0.3s !default;
 
+/// The `opacity` to apply while hovering an element on a light surface.
+/// @see $light-surface-hover-background-color
+/// @type Number
 $light-surface-hover-opacity: 0.08 !default;
+
+/// The `opacity` to apply while focusing an element on a light surface.
+/// @see $light-surface-focus-background-color
+/// @type Number
 $light-surface-focus-opacity: 0.24 !default;
+
+/// The `opacity` to apply while pressing an element on a light surface.
+/// @see $light-surface-press-background-color
+/// @type Number
 $light-surface-press-opacity: 0.32 !default;
+
+/// The `opacity` to apply while an element is selected on a light surface.
+/// @see $light-surface-selected-background-color
+/// @type Number
 $light-surface-selected-opacity: 0.16 !default;
+
+/// The background color for an element while hovered on a light surface.
+/// @type Color
 $light-surface-hover-background-color: rgba(
   $light-surface-base-background-color,
   $light-surface-hover-opacity
 ) !default;
+
+/// The background color for an element while focused on a light surface.
+/// @type Color
 $light-surface-focus-background-color: rgba(
   $light-surface-base-background-color,
   $light-surface-focus-opacity
 ) !default;
+
+/// The background color for an element while pressed on a light surface.
+/// @type Color
 $light-surface-press-background-color: rgba(
   $light-surface-base-background-color,
   $light-surface-press-opacity
 ) !default;
+
+/// The background color for a selected element on a light surface.
+/// @type Color
 $light-surface-selected-background-color: rgba(
   $light-surface-base-background-color,
   $light-surface-selected-opacity
 ) !default;
 
+/// The `opacity` to apply while hovering an element on a dark surface.
+/// @see $dark-surface-hover-background-color
+/// @type Number
 $dark-surface-hover-opacity: 0.1 !default;
+
+/// The `opacity` to apply while focusing an element on a dark surface.
+/// @see $dark-surface-hover-background-color
+/// @type Number
 $dark-surface-focus-opacity: 0.12 !default;
+
+/// The `opacity` to apply while pressing an element on a dark surface.
+/// @see $dark-surface-hover-background-color
+/// @type Number
 $dark-surface-press-opacity: 0.24 !default;
+/// The `opacity` to apply while hovering an element on a dark surface.
+/// @see $dark-surface-hover-background-color
+/// @type Number
 $dark-surface-selected-opacity: 0.12 !default;
+
+/// The background color for an element while hovered on a dark surface.
+/// @type Color
 $dark-surface-hover-background-color: rgba(
   $dark-surface-base-background-color,
   $dark-surface-hover-opacity
 ) !default;
+
+/// The background color for an element while focused on a dark surface.
+/// @type Color
 $dark-surface-focus-background-color: rgba(
   $dark-surface-base-background-color,
   $dark-surface-focus-opacity
 ) !default;
+
+/// The background color for an element while pressed on a dark surface.
+/// @type Color
 $dark-surface-press-background-color: rgba(
   $dark-surface-base-background-color,
   $dark-surface-press-opacity
 ) !default;
+
+/// The background color for a selected element on a dark surface.
+/// @type Color
 $dark-surface-selected-background-color: rgba(
   $dark-surface-base-background-color,
   $dark-surface-selected-opacity
 ) !default;
 
+/// The default background color for an element while hovered.
+/// @type Color
 $hover-background-color: theme.get-default-color(
   $light-surface-hover-background-color,
   $dark-surface-hover-background-color
 ) !default;
+
+/// The default background color for an element while focused.
+/// @type Color
 $focus-background-color: theme.get-default-color(
   $light-surface-focus-background-color,
   $dark-surface-focus-background-color
 ) !default;
+
+/// The default background color for an element while pressed.
+/// @type Color
 $press-background-color: theme.get-default-color(
   $light-surface-press-background-color,
   $dark-surface-press-background-color
 ) !default;
+
+/// The default background color for an element while selected.
+/// @type Color
 $selected-background-color: theme.get-default-color(
   $light-surface-selected-background-color,
   $dark-surface-selected-background-color
 ) !default;
 
+/// The available configurable css variables and mostly used internally for the
+/// `get-var`, `set-var`, and `use-var` utils.
+/// @type List
 $variables: (
   background-color,
   hover-background-color,
@@ -133,6 +290,11 @@ $variables: (
   surface-border-radius
 );
 
+/// Used to check if a variable is disabled based on feature flags.
+///
+/// @access private
+/// @param {String} name - The var name
+/// @returns {Boolean} true if the variable is disabled
 @function _is-var-disabled($name) {
   @if $name == ripple-inset {
     @return $disable-ripple-inset-var;
@@ -153,6 +315,9 @@ $variables: (
   @return false;
 }
 
+/// @param {String} name - The supported variable name
+/// @param {any} fallback [null] - An optional fallback value
+/// @returns {String} a `var()` statement
 @function get-var($name, $fallback: null) {
   // cannot set a custom property to `inherit` for some reason. It will not be parsed.
   @if not
@@ -175,6 +340,9 @@ $variables: (
   @return var(#{$var});
 }
 
+/// @param {String} name - The supported variable name
+/// @param {any} value - The value to set the variable to. Supports `null` which
+/// will just be a no-op.
 @mixin set-var($name, $value) {
   @if _is-var-disabled($name) {
     @error '"#{$name}" is currently disabled and cannot be changed. Set "$disable-#{$name}-var" to `true` or remove it from the Sass module overrides.';
@@ -185,10 +353,24 @@ $variables: (
   }
 }
 
+/// @param {String} property - The css property to apply the variable to
+/// @param {String} name [$property] - The supported variable name
+/// @param {any} fallback [null] - An optional fallback value if the variable
+/// has not been set
 @mixin use-var($property, $name: $property, $fallback: null) {
   #{$property}: get-var($name, $fallback);
 }
 
+/// This mixin is used to apply interaction state colors that are visible on
+/// a light surface color.
+///
+/// @example scss - Example Usage SCSS
+///   .container {
+///     background-color: #fff;
+///
+///     @include use-light-surface;
+///   }
+///
 @mixin use-light-surface {
   @if not $disable-surface {
     @include set-var(
@@ -209,7 +391,7 @@ $variables: (
     );
   }
 
-  @if not $_disable-ripple {
+  @if not $disable-ripple {
     @include set-var(
       ripple-background-color,
       $light-surface-ripple-background-color
@@ -217,6 +399,16 @@ $variables: (
   }
 }
 
+/// This mixin is used to apply interaction state colors that are visible on
+/// a dark surface color.
+///
+/// @example scss - Example Usage SCSS
+///   .container {
+///     background-color: #000;
+///
+///     @include use-dark-surface;
+///   }
+///
 @mixin use-dark-surface {
   @if not $disable-surface {
     @include set-var(
@@ -237,7 +429,7 @@ $variables: (
     );
   }
 
-  @if not $_disable-ripple {
+  @if not $disable-ripple {
     @include set-var(
       ripple-background-color,
       $dark-surface-ripple-background-color
@@ -245,6 +437,21 @@ $variables: (
   }
 }
 
+/// This mixin should only be used when not using the `surface`
+/// mixin.
+///
+/// @example scss - Example Usage SCSS
+///   .link {
+///     @include outline;
+///   }
+///
+/// @param {Boolean} box-shadow [$focus-box-shadow] - Set this to `true` to
+/// disable the `outline` styles when using `box-shadow` instead.
+/// @param {Color} color [transparent] - The outline color to use by default
+/// @param {Boolean} outline-offset [not $disable-outline-offset] - Set to
+/// `true` if the `outline-offset` property should also be set to match how
+/// box shadow would have been applied.
+/// @see surface
 @mixin outline(
   $box-shadow: $focus-box-shadow,
   $color: transparent,
@@ -263,6 +470,22 @@ $variables: (
   }
 }
 
+/// This mixin should only be used when not using the `surface`
+/// mixin.
+///
+/// @example scss - Example Usage SCSS
+///   .link {
+///     &:focus-visible {
+///       @include focus-styles($disable-background: true);
+///     }
+///   }
+///
+/// @param {Boolean} $box-shadow [$focus-box-shadow] - Set to `true` if using
+/// `box-shadow` instead of `outline` styles for focus states.
+/// @param {Boolean} $disable-background [$disable-focus-background] - Set to
+/// `true` if the `background-color` should not change while the element is
+/// focused.
+/// @see surface
 @mixin focus-styles(
   $box-shadow: $focus-box-shadow,
   $disable-background: $disable-focus-background
@@ -278,6 +501,13 @@ $variables: (
   }
 }
 
+/// This mixin should only be used when not using the `surface`
+/// mixin.
+///
+/// @param {Boolean} $clickable [true] - Set to `false` if the `cursor: auto`
+/// styles should not be applied.
+/// @param {Boolean} $hoverable [true] - Set to `false` if the element was not
+/// hoverable.
 @mixin surface-disabled($clickable: true, $hoverable: true) {
   @if $clickable {
     cursor: auto;
@@ -290,6 +520,37 @@ $variables: (
   }
 }
 
+/// Creates a "surface" for an interactable element that:
+/// - applies a focus outline/box-shadow
+/// - applies different background colors based on the `focus` and `hover` states
+/// - applies styles based on if the element is clickable
+/// - applies styles if the element is disabled
+///
+/// @example scss - Example Usage SCSS
+///   .container {
+///     display: flex;
+///
+///     @include surface;
+///   }
+///
+/// @param {String} $focus-selector ["&:focus" + if(utils.disable-focus-visible, "", "-visible")] -
+/// The selector to use indicating the element has been focused.
+/// @param {Boolean} $keyboard-only-focus [utils.$disable-focus-visible] -
+/// @param {String} $disabled-selector ["&:disabled"] - The selector to use
+/// indicating the element is disabled.
+/// @param {Boolean} $clickable [true] - Set to `false` if the element should
+/// not gain the `cursor: pointer` styles.
+/// @param {Boolean} $hoverable [true] - Set to `false` if the element should
+/// not apply styles for changing the background color while hovering.
+/// @param {Boolean} $css-modules [false] - Set to `true` if this mixin is
+/// being used within CSS modules to fix the global name spacing of classes.
+/// @param {Boolean} $higher-contrast [true] - Set to `false` if all child
+/// elements should no longer gain a `z-index: 1` to appear above the
+/// background styles.
+/// @param {Boolean} $box-shadow [$focus-box-shadow] - Set to `true` if using
+/// focus box shadow behavior instead of outlines
+/// @param {Boolean} $disable-background [$disable-focus-background] - Set to
+/// `true` to disable the focus background color styles.
 @mixin surface(
   $focus-selector: "&:focus" + if(utils.$disable-focus-visible, "", "-visible"),
   $keyboard-only-focus: utils.$disable-focus-visible,
@@ -364,6 +625,7 @@ $variables: (
   }
 }
 
+/// Conditionally applies the css variables based on feature flags
 @mixin variables {
   @include set-var(focus-color, $focus-color);
   @include set-var(focus-width, $focus-width);
@@ -375,7 +637,7 @@ $variables: (
     @include set-var(selected-background-color, $selected-background-color);
   }
 
-  @if not $_disable-ripple {
+  @if not $disable-ripple {
     @include set-var(ripple-background-color, $ripple-background-color);
     @include set-var(ripple-inset, 0);
   }
@@ -385,9 +647,13 @@ $variables: (
   }
 }
 
+/// Generates all the styles based on feature flags.
+///
+/// @param {Boolean} disable-layer [false] - Set this to `true` to disable the
+/// layer behavior
 @mixin styles($disable-layer: false) {
   @include utils.optional-layer(interaction, $disable-layer) {
-    @if not $_disable-ripple {
+    @if not $disable-ripple {
       .rmd-ripple-container {
         @include use-var(border-radius, ripple-border-radius);
         @include use-var(inset, ripple-inset);

package/dist/layout/LayoutAppBar.d.ts

@@ -43,6 +43,7 @@ export interface LayoutAppBarProps extends AppBarProps {
  * }
  * ```
  *
+ * @see {@link https://next.react-md.dev/getting-started/layout | Layout Demos}
  * @since 6.0.0 This component no longer renders the `LayoutNavToggle` and
  * `LayoutAppBarTitle` since they no longer exist. The only purpose of this
  * component is to dynamically set the `--rmd-layout-header-height` variable.

package/dist/layout/LayoutAppBar.js

@@ -35,6 +35,7 @@ import { useLayoutAppBarHeight } from "./useLayoutAppBarHeight.js";
  * }
  * ```
  *
+ * @see {@link https://next.react-md.dev/getting-started/layout | Layout Demos}
  * @since 6.0.0 This component no longer renders the `LayoutNavToggle` and
  * `LayoutAppBarTitle` since they no longer exist. The only purpose of this
  * component is to dynamically set the `--rmd-layout-header-height` variable.