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

.eslintignore

@@ -18,6 +18,7 @@
 /packages/material-ui-icons/legacy
 /packages/material-ui-icons/src
 /packages/material-ui-icons/templateSvgIcon.js
+/packages/material-ui-utils/macros/__fixtures__/
 # Ignore fixtures
 /packages/typescript-to-proptypes/test/*/*
 /tmp

packages/material-ui-utils/macros/MuiError.macro.d.ts

@@ -0,0 +1,3 @@
+export default class MuiError {
+  constructor(message: string);
+}

packages/material-ui-utils/macros/MuiError.macro.js

@@ -1,6 +1,7 @@
 const { createMacro, MacroError } = require('babel-plugin-macros');
 const helperModuleImports = require('@babel/helper-module-imports');
 const fs = require('fs');
+const path = require('path');
 
 function invertObject(object) {
   const inverted = {};
@@ -11,9 +12,13 @@ function invertObject(object) {
 }
 
 /**
+ * Supported imports:
+ * 1. bare specifier e.g. `'@material-ui/utils/macros/MuiError.macro'`
+ * 2. relative import from `packages/material-ui-utils/src` e.g. `'../macros/MuiError.macro'`
+ *
  * @param {import('babel-plugin-macros').MacroParams} param0
  */
-function muiError({ references, babel, config }) {
+function muiError({ references, babel, config, source }) {
   const { errorCodesPath = {}, missingError = 'annotate' } = config;
   const errorCodes = JSON.parse(fs.readFileSync(errorCodesPath, { encoding: 'utf8' }));
   const errorCodesLookup = invertObject(errorCodes);
@@ -125,13 +130,33 @@ function muiError({ references, babel, config }) {
     errorCode = parseInt(errorCode, 10);
 
     if (formatMuiErrorMessageIdentifier === null) {
-      // Outputs:
-      // import { formatMuiErrorMessage } from '@material-ui/utils';
-      formatMuiErrorMessageIdentifier = helperModuleImports.addNamed(
-        babelPath,
-        'formatMuiErrorMessage',
-        '@material-ui/utils',
-      );
+      const isBareImportSourceIdentifier = source.startsWith('@material-ui/utils');
+      if (isBareImportSourceIdentifier) {
+        // Input: import MuiError from '@material-ui/utils/macros/MuiError.macro'
+        // Outputs:
+        // import { formatMuiErrorMessage } from '@material-ui/utils';
+        formatMuiErrorMessageIdentifier = helperModuleImports.addNamed(
+          babelPath,
+          'formatMuiErrorMessage',
+          '@material-ui/utils',
+        );
+      } else {
+        const normalizedRelativeImport = path.normalize(
+          source.replace('../macros/MuiError.macro', './formatMuiErrorMessage'),
+        );
+        // 'formatMuiErrorMessage' implies './formatMuiErrorMessage' for fs paths but not for import specifiers.
+        const formatMuiErrorMessageImportSource = normalizedRelativeImport.startsWith('.')
+          ? normalizedRelativeImport
+          : `./${normalizedRelativeImport}`;
+        // Input: import MuiError from '../macros/MuiError.macro'
+        // Outputs:
+        // import formatMuiErrorMessage from './formatMuiErrorMessage';
+        formatMuiErrorMessageIdentifier = helperModuleImports.addDefault(
+          babelPath,
+          formatMuiErrorMessageImportSource,
+          { nameHint: 'formatMuiErrorMessage' },
+        );
+      }
     }
 
     // Outputs:

packages/material-ui-utils/macros/MuiError.macro.test.js

@@ -95,5 +95,13 @@ pluginTester({
         },
       },
     },
+    {
+      title: 'relative-import',
+      pluginOptions: {
+        muiError: { errorCodesPath: path.join(fixturePath, 'relative-import', 'error-codes.json') },
+      },
+      fixture: path.join(fixturePath, 'relative-import', 'input.js'),
+      output: readOutputFixtureSync('relative-import', 'output.js'),
+    },
   ],
 });

packages/material-ui-utils/macros/__fixtures__/relative-import/error-codes.json

@@ -0,0 +1,3 @@
+{
+  "1": "Material-UI: Expected valid input target.\nDid you use `inputComponent`?"
+}

packages/material-ui-utils/macros/__fixtures__/relative-import/input.js

@@ -0,0 +1,3 @@
+import MuiError from '../../../macros/MuiError.macro';
+
+throw new MuiError('Material-UI: Expected valid input target.\n' + 'Did you use `inputComponent`?');

packages/material-ui-utils/macros/__fixtures__/relative-import/output.js

@@ -0,0 +1,7 @@
+import _formatMuiErrorMessage from '../../formatMuiErrorMessage';
+throw new Error(
+  process.env.NODE_ENV !== 'production'
+    ? `Material-UI: Expected valid input target.
+Did you use \`inputComponent\`?`
+    : _formatMuiErrorMessage(1),
+);

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

@@ -0,0 +1 @@
+export default function capitalize(string: string): string;

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

@@ -0,0 +1,12 @@
+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 in the sentence.
+// We only handle the first word.
+export default function capitalize(string) {
+  if (typeof string !== 'string') {
+    throw new MuiError('Material-UI: `capitalize(string)` expects a string argument.');
+  }
+
+  return string.charAt(0).toUpperCase() + string.slice(1);
+}

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

@@ -0,0 +1,5 @@
+export type ChainedFunction = ((...args: any[]) => void) | undefined | null;
+
+export default function createChainedFunction(
+  ...funcs: ChainedFunction[]
+): (...args: any[]) => never;

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

@@ -0,0 +1,31 @@
+/**
+ * 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) {
+  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) {
+        acc.apply(this, args);
+        func.apply(this, args);
+      };
+    },
+    () => {},
+  );
+}

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

@@ -0,0 +1,8 @@
+export interface Cancelable {
+  clear(): void;
+}
+
+export default function debounce<T extends (...args: any[]) => any>(
+  func: T,
+  wait?: number
+): T & Cancelable;

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

@@ -0,0 +1,18 @@
+// 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(func, wait = 166) {
+  let timeout;
+  function debounced(...args) {
+    const later = () => {
+      func.apply(this, args);
+    };
+    clearTimeout(timeout);
+    timeout = setTimeout(later, wait);
+  }
+
+  debounced.clear = () => {
+    clearTimeout(timeout);
+  };
+
+  return debounced;
+}

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

@@ -0,0 +1 @@
+export default function deprecatedPropType<T>(validator: T, reason: string): T;

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

@@ -0,0 +1,19 @@
+export default function deprecatedPropType(validator, reason) {
+  if (process.env.NODE_ENV === 'production') {
+    return () => null;
+  }
+
+  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,24 @@ 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 unstable_capitalize } from './capitalize';
+export { default as unstable_createChainedFunction } from './createChainedFunction';
+export { default as unstable_debounce } from './debounce';
+export { default as unstable_deprecatedPropType } from './deprecatedPropType';
+export { default as unstable_isMuiElement } from './isMuiElement';
+export { default as unstable_ownerDocument } from './ownerDocument';
+export { default as unstable_ownerWindow } from './ownerWindow';
+export { default as unstable_requirePropFactory } from './requirePropFactory';
+export { default as unstable_setRef } from './setRef';
+export { default as unstable_useEnhancedEffect } from './useEnhancedEffect';
+export { default as unstable_useId } from './useId';
+export { default as unstable_unsupportedProp } from './unsupportedProp';
+export { default as unstable_useControlled } from './useControlled';
+export { default as unstable_useEventCallback } from './useEventCallback';
+export { default as unstable_useForkRef } from './useForkRef';
+export { default as unstable_useIsFocusVisible } from './useIsFocusVisible';
+export { default as unstable_getScrollbarSize } from './getScrollbarSize';
+export {
+  detectScrollType as unstable_detectScrollType,
+  getNormalizedScrollLeft as unstable_getNormalizedScrollLeft,
+} from './scrollLeft';

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

@@ -0,0 +1,35 @@
+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>;
+}
+
+/**
+ * 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;

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

@@ -0,0 +1,5 @@
+import * as React from 'react';
+
+export default function isMuiElement(element, muiNames) {
+  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.d.ts

@@ -0,0 +1 @@
+export default function requirePropFactory(componentNameInError: string): any;

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

@@ -0,0 +1,25 @@
+export default function requirePropFactory(componentNameInError) {
+  if (process.env.NODE_ENV === 'production') {
+    return () => null;
+  }
+
+  const requireProp = (requiredProp) => (
+    props,
+    propName,
+    componentName,
+    location,
+    propFullName,
+  ) => {
+    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.d.ts

@@ -0,0 +1,2 @@
+export function detectScrollType(): string;
+export function getNormalizedScrollLeft(element: HTMLElement, direction: string): number;