[utils] Add all @material-ui/core/utils to @material-ui/utils

packages/material-ui-utils/src/capitalize.ts

@@ -0,0 +1,13 @@
+// TODO: error TS7016: Could not find a declaration file for module '../macros/MuiError.macro'. '/tmp/material-ui/packages/material-ui-utils/macros/MuiError.macro.js' implicitly has an 'any' type.
+// import MuiError from '../macros/MuiError.macro';
+// It should to be noted that this function isn't equivalent to `text-transform: capitalize`.
+//
+// A strict capitalization should uppercase the first letter of each word a the sentence.
+// We only handle the first word.
+export default function capitalize(string: string): string {
+  if (typeof string !== 'string') {
+    throw new Error('Material-UI: capitalize(string) expects a string argument.');
+  }
+
+  return string.charAt(0).toUpperCase() + string.slice(1);
+}

packages/material-ui-utils/src/createChainedFunction.ts

@@ -0,0 +1,37 @@
+export type ChainedFunction = ((...args: any[]) => void) | undefined | null;
+
+/**
+ * Safe chained function
+ *
+ * Will only create a new function if needed,
+ * otherwise will pass back existing functions or null.
+ * @param {function} functions to chain
+ * @returns {function|null}
+ */
+export default function createChainedFunction(
+  ...funcs: ChainedFunction[]
+): (...args: any[]) => never {
+  return funcs.reduce(
+    (acc, func) => {
+      if (func == null) {
+        return acc;
+      }
+
+      if (process.env.NODE_ENV !== 'production') {
+        if (typeof func !== 'function') {
+          console.error(
+            'Material-UI: Invalid Argument Type, must only provide functions, undefined, or null.',
+          );
+        }
+      }
+
+      return function chainedFunction(...args) {
+        // @ts-ignore
+        acc.apply(this, args);
+        // @ts-ignore
+        func.apply(this, args);
+      };
+    },
+    () => {},
+  ) as (...args: any[]) => never;
+}

packages/material-ui-utils/src/debounce.ts

@@ -0,0 +1,26 @@
+export interface Cancelable {
+  clear(): void;
+}
+
+// Corresponds to 10 frames at 60 Hz.
+// A few bytes payload overhead when lodash/debounce is ~3 kB and debounce ~300 B.
+export default function debounce<T extends (...args: any[]) => any>(
+  func: T,
+  wait: number = 166,
+): T & Cancelable {
+  let timeout: any;
+  function debounced(...args: any[]) {
+    const later = () => {
+      // @ts-ignore
+      func.apply(this, args);
+    };
+    clearTimeout(timeout);
+    timeout = setTimeout(later, wait);
+  }
+
+  debounced.clear = () => {
+    clearTimeout(timeout);
+  };
+
+  return debounced as T & Cancelable;
+}

packages/material-ui-utils/src/deprecatedPropType.ts

@@ -0,0 +1,20 @@
+export default function deprecatedPropType<T>(validator: T, reason: string): T | Function {
+  if (process.env.NODE_ENV === 'production') {
+    return () => null;
+  }
+
+  // @ts-ignore
+  return (props, propName, componentName, location, propFullName) => {
+    const componentNameSafe = componentName || '<<anonymous>>';
+    const propFullNameSafe = propFullName || propName;
+
+    if (typeof props[propName] !== 'undefined') {
+      return new Error(
+        `The ${location} \`${propFullNameSafe}\` of ` +
+          `\`${componentNameSafe}\` is deprecated. ${reason}`,
+      );
+    }
+
+    return null;
+  };
+}

packages/material-ui-utils/src/getScrollbarSize.ts

@@ -0,0 +1,16 @@
+// A change of the browser zoom change the scrollbar size.
+// Credit https://github.com/twbs/bootstrap/blob/3ffe3a5d82f6f561b82ff78d82b32a7d14aed558/js/src/modal.js#L512-L519
+export default function getScrollbarSize(doc: Document): number {
+  const scrollDiv = doc.createElement('div');
+  scrollDiv.style.width = '99px';
+  scrollDiv.style.height = '99px';
+  scrollDiv.style.position = 'absolute';
+  scrollDiv.style.top = '-9999px';
+  scrollDiv.style.overflow = 'scroll';
+
+  doc.body.appendChild(scrollDiv);
+  const scrollbarSize = scrollDiv.offsetWidth - scrollDiv.clientWidth;
+  doc.body.removeChild(scrollDiv);
+
+  return scrollbarSize;
+}

packages/material-ui-utils/src/index.ts

@@ -8,3 +8,21 @@ export { default as getDisplayName } from './getDisplayName';
 export { default as HTMLElementType } from './HTMLElementType';
 export { default as ponyfillGlobal } from './ponyfillGlobal';
 export { default as refType } from './refType';
+export { default as capitalize } from './capitalize';
+export { default as createChainedFunction } from './createChainedFunction';
+export { default as debounce } from './debounce';
+export { default as deprecatedPropType } from './deprecatedPropType';
+export { default as isMuiElement } from './isMuiElement';
+export { default as ownerDocument } from './ownerDocument';
+export { default as ownerWindow } from './ownerWindow';
+export { default as requirePropFactory } from './requirePropFactory';
+export { default as setRef } from './setRef';
+export { default as unstable_useEnhancedEffect } from './useEnhancedEffect';
+export { default as unstable_useId } from './useId';
+export { default as unsupportedProp } from './unsupportedProp';
+export { default as useControlled } from './useControlled';
+export { default as useEventCallback } from './useEventCallback';
+export { default as useForkRef } from './useForkRef';
+export { default as useIsFocusVisible } from './useIsFocusVisible';
+export { default as getScrollbarSize } from './getScrollbarSize';
+export { detectScrollType, getNormalizedScrollLeft } from './scrollLeft';

packages/material-ui-utils/src/isMuiElement.ts

@@ -0,0 +1,40 @@
+import * as React from 'react';
+
+export type ClassNameMap<ClassKey extends string = string> = Record<ClassKey, string>;
+
+export interface StyledComponentProps<ClassKey extends string = string> {
+  /**
+   * Override or extend the styles applied to the component.
+   */
+  classes?: Partial<ClassNameMap<ClassKey>>;
+  innerRef?: React.Ref<any>;
+}
+
+/**
+ * @private ONLY USE FROM WITHIN mui-org/material-ui
+ *
+ * Internal helper type for conform (describeConformance) components that are decorated with `withStyles
+ * However, we don't declare classes on this type.
+ * It is recommended to declare them manually with an interface so that each class can have a separate JSDOC.
+ */
+export type StandardProps<C, Removals extends keyof C = never> = Omit<C, 'classes' | Removals> &
+  // each component declares it's classes in a separate interface for proper JSDOC
+  StyledComponentProps<never> & {
+    ref?: C extends { ref?: infer RefType } ? RefType : React.Ref<unknown>;
+    // TODO: Remove implicit props. Up to each component.
+    className?: string;
+    style?: React.CSSProperties;
+  };
+
+export type NamedMuiComponent = React.ComponentType & { muiName: string };
+
+export interface NamedMuiElement {
+  type: NamedMuiComponent;
+  props: StandardProps<{}>;
+  key: string | number | null;
+}
+
+export default function isMuiElement(element: any, muiNames: string[]): element is NamedMuiElement {
+  // @ts-ignore
+  return React.isValidElement(element) && muiNames.indexOf(element.type.muiName) !== -1;
+}

packages/material-ui-utils/src/ownerDocument.ts

@@ -0,0 +1,3 @@
+export default function ownerDocument(node: Node | undefined): Document {
+  return (node && node.ownerDocument) || document;
+}

packages/material-ui-utils/src/ownerWindow.ts

@@ -0,0 +1,6 @@
+import ownerDocument from './ownerDocument';
+
+export default function ownerWindow(node: Node | undefined): Window {
+  const doc = ownerDocument(node);
+  return doc.defaultView || window;
+}

packages/material-ui-utils/src/requirePropFactory.ts

@@ -0,0 +1,25 @@
+export default function requirePropFactory(componentNameInError: string): any {
+  if (process.env.NODE_ENV === 'production') {
+    return () => null;
+  }
+
+  const requireProp = (requiredProp: string): any => (
+    props: { [key: string]: any },
+    propName: string,
+    componentName: string,
+    location: string,
+    propFullName: string,
+  ) => {
+    const propFullNameSafe = propFullName || propName;
+
+    if (typeof props[propName] !== 'undefined' && !props[requiredProp]) {
+      return new Error(
+        `The prop \`${propFullNameSafe}\` of ` +
+          `\`${componentNameInError}\` must be used on \`${requiredProp}\`.`,
+      );
+    }
+
+    return null;
+  };
+  return requireProp;
+}

packages/material-ui-utils/src/scrollLeft.ts

@@ -0,0 +1,77 @@
+// Source from https://github.com/alitaheri/normalize-scroll-left
+let cachedType: string;
+
+/**
+ * Based on the jquery plugin https://github.com/othree/jquery.rtl-scroll-type
+ *
+ * Types of scrollLeft, assuming scrollWidth=100 and direction is rtl.
+ *
+ * Type             | <- Most Left | Most Right -> | Initial
+ * ---------------- | ------------ | ------------- | -------
+ * default          | 0            | 100           | 100
+ * negative (spec*) | -100         | 0             | 0
+ * reverse          | 100          | 0             | 0
+ *
+ * Edge 85: default
+ * Safari 14: negative
+ * Chrome 85: negative
+ * Firefox 81: negative
+ * IE11: reverse
+ *
+ * spec* https://drafts.csswg.org/cssom-view/#dom-window-scroll
+ */
+export function detectScrollType(): string {
+  if (cachedType) {
+    return cachedType;
+  }
+
+  const dummy = document.createElement('div');
+  const container = document.createElement('div');
+  container.style.width = '10px';
+  container.style.height = '1px';
+  dummy.appendChild(container);
+  dummy.dir = 'rtl';
+  dummy.style.fontSize = '14px';
+  dummy.style.width = '4px';
+  dummy.style.height = '1px';
+  dummy.style.position = 'absolute';
+  dummy.style.top = '-1000px';
+  dummy.style.overflow = 'scroll';
+
+  document.body.appendChild(dummy);
+
+  cachedType = 'reverse';
+
+  if (dummy.scrollLeft > 0) {
+    cachedType = 'default';
+  } else {
+    dummy.scrollLeft = 1;
+    if (dummy.scrollLeft === 0) {
+      cachedType = 'negative';
+    }
+  }
+
+  document.body.removeChild(dummy);
+  return cachedType;
+}
+
+// Based on https://stackoverflow.com/a/24394376
+export function getNormalizedScrollLeft(element: Element, direction: string): number {
+  const scrollLeft = element.scrollLeft;
+
+  // Perform the calculations only when direction is rtl to avoid messing up the ltr behavior
+  if (direction !== 'rtl') {
+    return scrollLeft;
+  }
+
+  const type = detectScrollType();
+
+  switch (type) {
+    case 'negative':
+      return element.scrollWidth - element.clientWidth + scrollLeft;
+    case 'reverse':
+      return element.scrollWidth - element.clientWidth - scrollLeft;
+    default:
+      return scrollLeft;
+  }
+}

packages/material-ui-utils/src/setRef.ts

@@ -0,0 +1,25 @@
+import * as React from 'react';
+
+/**
+ * TODO v5: consider to make it private
+ *
+ * passes {value} to {ref}
+ *
+ * WARNING: Be sure to only call this inside a callback that is passed as a ref.
+ * Otherwise make sure to cleanup previous {ref} if it changes. See
+ * https://github.com/mui-org/material-ui/issues/13539
+ *
+ * useful if you want to expose the ref of an inner component to the public api
+ * while still using it inside the component
+ * @param ref a ref callback or ref object if anything falsy this is a no-op
+ */
+export default function setRef<T>(
+  ref: React.MutableRefObject<T | null> | ((instance: T | null) => void) | null | undefined,
+  value: T | null,
+): void {
+  if (typeof ref === 'function') {
+    ref(value);
+  } else if (ref) {
+    ref.current = value;
+  }
+}

packages/material-ui-utils/src/unsupportedProp.d.ts

@@ -0,0 +1,7 @@
+export default function unsupportedProp(
+  props: { [key: string]: any },
+  propName: string,
+  componentName: string,
+  location: string,
+  propFullName: string
+): Error | null;

packages/material-ui-utils/src/unsupportedProp.ts

@@ -0,0 +1,19 @@
+export default function unsupportedProp(
+  props: { [key: string]: any },
+  propName: string,
+  componentName: string,
+  location: string,
+  propFullName: string,
+): Error | null {
+  if (process.env.NODE_ENV === 'production') {
+    return null;
+  }
+
+  const propFullNameSafe = propFullName || propName;
+
+  if (typeof props[propName] !== 'undefined') {
+    return new Error(`The prop \`${propFullNameSafe}\` is not supported. Please remove it.`);
+  }
+
+  return null;
+}