@instructure/ui-spinner 8.45.1-snapshot-3 → 8.46.0

package/CHANGELOG.md

@@ -3,9 +3,12 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-## [8.45.1-snapshot-3](https://github.com/instructure/instructure-ui/compare/v8.45.0...v8.45.1-snapshot-3) (2023-10-06)
+# [8.46.0](https://github.com/instructure/instructure-ui/compare/v8.45.0...v8.46.0) (2023-10-11)
 
-**Note:** Version bump only for package @instructure/ui-spinner
+
+### Features
+
+* **ui-spinner): feat(ui-spinner:** add delay prop and functionality to the Spinner ([1f44e5d](https://github.com/instructure/instructure-ui/commit/1f44e5dc81cd5a209ac9d05b87a361f63a0ead9f))
 
 
 

package/es/Spinner/__new-tests__/Spinner.test.js

@@ -0,0 +1,46 @@
+var _Spinner;
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+import React from 'react';
+import { render, waitFor } from '@testing-library/react';
+import '@testing-library/jest-dom/extend-expect';
+import Spinner from '../index';
+describe('<Spinner />', () => {
+  describe('with the delay prop', () => {
+    it('should delay rendering', async () => {
+      const _render = render(_Spinner || (_Spinner = /*#__PURE__*/React.createElement(Spinner, {
+          delay: 300
+        }))),
+        container = _render.container;
+      const spinnerElements = container.querySelectorAll('[data-cid="Spinner"]');
+      expect(spinnerElements.length).toBe(0);
+      await waitFor(() => {
+        const spinnerElements = container.querySelectorAll('[data-cid="Spinner"]');
+        expect(spinnerElements.length).toBe(1);
+      }, {
+        timeout: 400
+      });
+    });
+  });
+});

package/es/Spinner/index.js

@@ -44,6 +44,7 @@ let Spinner = (_dec = withDeterministicId(), _dec2 = withStyle(generateStyle, ge
     super(props);
     this.ref = null;
     this.titleId = void 0;
+    this.delayTimeout = void 0;
     this.handleRef = el => {
       const elementRef = this.props.elementRef;
       this.ref = el;
@@ -52,15 +53,29 @@ let Spinner = (_dec = withDeterministicId(), _dec2 = withStyle(generateStyle, ge
       }
     };
     this.titleId = props.deterministicId();
+    this.state = {
+      shouldRender: !props.delay
+    };
   }
   componentDidMount() {
     var _this$props$makeStyle, _this$props;
     (_this$props$makeStyle = (_this$props = this.props).makeStyles) === null || _this$props$makeStyle === void 0 ? void 0 : _this$props$makeStyle.call(_this$props);
+    const delay = this.props.delay;
+    if (delay) {
+      this.delayTimeout = setTimeout(() => {
+        this.setState({
+          shouldRender: true
+        });
+      }, delay);
+    }
   }
   componentDidUpdate() {
     var _this$props$makeStyle2, _this$props2;
     (_this$props$makeStyle2 = (_this$props2 = this.props).makeStyles) === null || _this$props$makeStyle2 === void 0 ? void 0 : _this$props$makeStyle2.call(_this$props2);
   }
+  componentWillUnmount() {
+    clearTimeout(this.delayTimeout);
+  }
   radius() {
     switch (this.props.size) {
       case 'x-small':
@@ -73,7 +88,7 @@ let Spinner = (_dec = withDeterministicId(), _dec2 = withStyle(generateStyle, ge
         return '1.75em';
     }
   }
-  render() {
+  renderSpinner() {
     var _this$props$styles, _this$props$styles2, _this$props$styles3, _this$props$styles4;
     const passthroughProps = View.omitViewProps(omitProps(this.props, Spinner.allowedProps), Spinner);
     const hasTitle = this.props.renderTitle;
@@ -104,6 +119,9 @@ let Spinner = (_dec = withDeterministicId(), _dec2 = withStyle(generateStyle, ge
       r: this.radius()
     }))));
   }
+  render() {
+    return this.state.shouldRender ? this.renderSpinner() : null;
+  }
 }, _class2.displayName = "Spinner", _class2.componentId = 'Spinner', _class2.allowedProps = allowedProps, _class2.propTypes = propTypes, _class2.defaultProps = {
   as: 'div',
   size: 'medium',

package/es/Spinner/props.js

@@ -24,6 +24,7 @@
 import PropTypes from 'prop-types';
 import { ThemeablePropTypes } from '@instructure/emotion';
 const propTypes = {
+  delay: PropTypes.number,
   renderTitle: PropTypes.oneOfType([PropTypes.func, PropTypes.node]),
   size: PropTypes.oneOf(['x-small', 'small', 'medium', 'large']),
   variant: PropTypes.oneOf(['default', 'inverse']),
@@ -31,5 +32,5 @@ const propTypes = {
   elementRef: PropTypes.func,
   as: PropTypes.elementType
 };
-const allowedProps = ['renderTitle', 'size', 'variant', 'margin', 'elementRef', 'as'];
+const allowedProps = ['delay', 'renderTitle', 'size', 'variant', 'margin', 'elementRef', 'as'];
 export { propTypes, allowedProps };

package/lib/Spinner/__new-tests__/Spinner.test.js

@@ -0,0 +1,49 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault").default;
+var _react = _interopRequireDefault(require("react"));
+var _react2 = require("@testing-library/react");
+require("@testing-library/jest-dom/extend-expect");
+var _index = _interopRequireDefault(require("../index"));
+var _Spinner;
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+describe('<Spinner />', () => {
+  describe('with the delay prop', () => {
+    it('should delay rendering', async () => {
+      const _render = (0, _react2.render)(_Spinner || (_Spinner = /*#__PURE__*/_react.default.createElement(_index.default, {
+          delay: 300
+        }))),
+        container = _render.container;
+      const spinnerElements = container.querySelectorAll('[data-cid="Spinner"]');
+      expect(spinnerElements.length).toBe(0);
+      await (0, _react2.waitFor)(() => {
+        const spinnerElements = container.querySelectorAll('[data-cid="Spinner"]');
+        expect(spinnerElements.length).toBe(1);
+      }, {
+        timeout: 400
+      });
+    });
+  });
+});

package/lib/Spinner/index.js

@@ -52,6 +52,7 @@ let Spinner = (_dec = (0, _withDeterministicId.withDeterministicId)(), _dec2 = (
     super(props);
     this.ref = null;
     this.titleId = void 0;
+    this.delayTimeout = void 0;
     this.handleRef = el => {
       const elementRef = this.props.elementRef;
       this.ref = el;
@@ -60,15 +61,29 @@ let Spinner = (_dec = (0, _withDeterministicId.withDeterministicId)(), _dec2 = (
       }
     };
     this.titleId = props.deterministicId();
+    this.state = {
+      shouldRender: !props.delay
+    };
   }
   componentDidMount() {
     var _this$props$makeStyle, _this$props;
     (_this$props$makeStyle = (_this$props = this.props).makeStyles) === null || _this$props$makeStyle === void 0 ? void 0 : _this$props$makeStyle.call(_this$props);
+    const delay = this.props.delay;
+    if (delay) {
+      this.delayTimeout = setTimeout(() => {
+        this.setState({
+          shouldRender: true
+        });
+      }, delay);
+    }
   }
   componentDidUpdate() {
     var _this$props$makeStyle2, _this$props2;
     (_this$props$makeStyle2 = (_this$props2 = this.props).makeStyles) === null || _this$props$makeStyle2 === void 0 ? void 0 : _this$props$makeStyle2.call(_this$props2);
   }
+  componentWillUnmount() {
+    clearTimeout(this.delayTimeout);
+  }
   radius() {
     switch (this.props.size) {
       case 'x-small':
@@ -81,7 +96,7 @@ let Spinner = (_dec = (0, _withDeterministicId.withDeterministicId)(), _dec2 = (
         return '1.75em';
     }
   }
-  render() {
+  renderSpinner() {
     var _this$props$styles, _this$props$styles2, _this$props$styles3, _this$props$styles4;
     const passthroughProps = _View.View.omitViewProps((0, _omitProps.omitProps)(this.props, Spinner.allowedProps), Spinner);
     const hasTitle = this.props.renderTitle;
@@ -112,6 +127,9 @@ let Spinner = (_dec = (0, _withDeterministicId.withDeterministicId)(), _dec2 = (
       r: this.radius()
     }))));
   }
+  render() {
+    return this.state.shouldRender ? this.renderSpinner() : null;
+  }
 }, _class2.displayName = "Spinner", _class2.componentId = 'Spinner', _class2.allowedProps = _props.allowedProps, _class2.propTypes = _props.propTypes, _class2.defaultProps = {
   as: 'div',
   size: 'medium',

package/lib/Spinner/props.js

@@ -32,6 +32,7 @@ var _emotion = require("@instructure/emotion");
  */
 
 const propTypes = {
+  delay: _propTypes.default.number,
   renderTitle: _propTypes.default.oneOfType([_propTypes.default.func, _propTypes.default.node]),
   size: _propTypes.default.oneOf(['x-small', 'small', 'medium', 'large']),
   variant: _propTypes.default.oneOf(['default', 'inverse']),
@@ -40,5 +41,5 @@ const propTypes = {
   as: _propTypes.default.elementType
 };
 exports.propTypes = propTypes;
-const allowedProps = ['renderTitle', 'size', 'variant', 'margin', 'elementRef', 'as'];
+const allowedProps = ['delay', 'renderTitle', 'size', 'variant', 'margin', 'elementRef', 'as'];
 exports.allowedProps = allowedProps;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instructure/ui-spinner",
-  "version": "8.45.1-snapshot-3",
+  "version": "8.46.0",
   "description": "A spinner/loading component",
   "author": "Instructure, Inc. Engineering and Product Design",
   "module": "./es/index.js",
@@ -24,22 +24,24 @@
   "license": "MIT",
   "dependencies": {
     "@babel/runtime": "^7.22.15",
-    "@instructure/console": "8.45.1-snapshot-3",
-    "@instructure/emotion": "8.45.1-snapshot-3",
-    "@instructure/shared-types": "8.45.1-snapshot-3",
-    "@instructure/ui-color-utils": "8.45.1-snapshot-3",
-    "@instructure/ui-react-utils": "8.45.1-snapshot-3",
-    "@instructure/ui-testable": "8.45.1-snapshot-3",
-    "@instructure/ui-utils": "8.45.1-snapshot-3",
-    "@instructure/ui-view": "8.45.1-snapshot-3",
-    "@instructure/uid": "8.45.1-snapshot-3",
+    "@instructure/console": "8.46.0",
+    "@instructure/emotion": "8.46.0",
+    "@instructure/shared-types": "8.46.0",
+    "@instructure/ui-color-utils": "8.46.0",
+    "@instructure/ui-react-utils": "8.46.0",
+    "@instructure/ui-testable": "8.46.0",
+    "@instructure/ui-utils": "8.46.0",
+    "@instructure/ui-view": "8.46.0",
+    "@instructure/uid": "8.46.0",
     "prop-types": "^15.8.1"
   },
   "devDependencies": {
-    "@instructure/ui-babel-preset": "8.45.1-snapshot-3",
-    "@instructure/ui-test-locator": "8.45.1-snapshot-3",
-    "@instructure/ui-test-utils": "8.45.1-snapshot-3",
-    "@instructure/ui-themes": "8.45.1-snapshot-3"
+    "@instructure/ui-babel-preset": "8.46.0",
+    "@instructure/ui-test-locator": "8.46.0",
+    "@instructure/ui-test-utils": "8.46.0",
+    "@instructure/ui-themes": "8.46.0",
+    "@testing-library/jest-dom": "^5.17.0",
+    "@testing-library/react": "^14.0.0"
   },
   "peerDependencies": {
     "react": ">=16.8 <=18"

package/src/Spinner/README.md

@@ -12,7 +12,7 @@ The `size` prop allows you to select from `x-small`, `small`, `medium` and `larg
 example: true
 ---
 <div>
-  <Spinner renderTitle="Loading" size="x-small" />
+  <Spinner renderTitle="Loading" size="x-small"/>
   <Spinner renderTitle="Loading" size="small" margin="0 0 0 medium" />
   <Spinner renderTitle="Loading" margin="0 0 0 medium" />
   <Spinner renderTitle="Loading" size="large" margin="0 0 0 medium" />
@@ -33,6 +33,22 @@ example: true
 </View>
 ```
 
+### Delay rendering
+
+The `delay` prop allows you to delay the rendering of the spinner a desired time to prevent flickering in cases of very fast load times.
+
+```js
+---
+example: true
+---
+<div>
+  <Spinner renderTitle="Loading" size="x-small" delay={1000} />
+  <Spinner renderTitle="Loading" size="small" margin="0 0 0 medium" delay={2000} />
+  <Spinner renderTitle="Loading" margin="0 0 0 medium"  delay={3000} />
+  <Spinner renderTitle="Loading" size="large" margin="0 0 0 medium"  delay={4000} />
+</div>
+```
+
 ### Screen reader support
 
 The `renderTitle` prop is read to screen readers.

package/src/Spinner/__new-tests__/Spinner.test.tsx

@@ -0,0 +1,52 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+import React from 'react'
+import { render, waitFor } from '@testing-library/react'
+
+import '@testing-library/jest-dom/extend-expect'
+import Spinner from '../index'
+
+describe('<Spinner />', () => {
+  describe('with the delay prop', () => {
+    it('should delay rendering', async () => {
+      const { container } = render(<Spinner delay={300} />)
+
+      const spinnerElements = container.querySelectorAll('[data-cid="Spinner"]')
+
+      expect(spinnerElements.length).toBe(0)
+
+      await waitFor(
+        () => {
+          const spinnerElements = container.querySelectorAll(
+            '[data-cid="Spinner"]'
+          )
+          expect(spinnerElements.length).toBe(1)
+        },
+        {
+          timeout: 400
+        }
+      )
+    })
+  })
+})

package/src/Spinner/index.tsx

@@ -37,7 +37,7 @@ import { withStyle, jsx } from '@instructure/emotion'
 
 import generateStyle from './styles'
 import generateComponentTheme from './theme'
-import type { SpinnerProps } from './props'
+import type { SpinnerProps, SpinnerState } from './props'
 import { allowedProps, propTypes } from './props'
 
 /**
@@ -49,7 +49,7 @@ category: components
 @withDeterministicId()
 @withStyle(generateStyle, generateComponentTheme)
 @testable()
-class Spinner extends Component<SpinnerProps> {
+class Spinner extends Component<SpinnerProps, SpinnerState> {
   static readonly componentId = 'Spinner'
   static allowedProps = allowedProps
   static propTypes = propTypes
@@ -61,6 +61,7 @@ class Spinner extends Component<SpinnerProps> {
 
   ref: Element | null = null
   private readonly titleId?: string
+  private delayTimeout?: NodeJS.Timeout
 
   handleRef = (el: Element | null) => {
     const { elementRef } = this.props
@@ -76,16 +77,31 @@ class Spinner extends Component<SpinnerProps> {
     super(props)
 
     this.titleId = props.deterministicId!()
+
+    this.state = {
+      shouldRender: !props.delay
+    }
   }
 
   componentDidMount() {
     this.props.makeStyles?.()
+    const { delay } = this.props
+
+    if (delay) {
+      this.delayTimeout = setTimeout(() => {
+        this.setState({ shouldRender: true })
+      }, delay)
+    }
   }
 
   componentDidUpdate() {
     this.props.makeStyles?.()
   }
 
+  componentWillUnmount() {
+    clearTimeout(this.delayTimeout)
+  }
+
   radius() {
     switch (this.props.size) {
       case 'x-small':
@@ -99,7 +115,7 @@ class Spinner extends Component<SpinnerProps> {
     }
   }
 
-  render() {
+  renderSpinner() {
     const passthroughProps = View.omitViewProps(
       omitProps(this.props, Spinner.allowedProps),
       Spinner
@@ -148,6 +164,10 @@ class Spinner extends Component<SpinnerProps> {
       </View>
     )
   }
+
+  render() {
+    return this.state.shouldRender ? this.renderSpinner() : null
+  }
 }
 
 export default Spinner

package/src/Spinner/props.ts

@@ -41,17 +41,17 @@ import { Renderable } from '@instructure/shared-types'
 
 type SpinnerOwnProps = {
   /**
-   * Give the spinner a title to be read by screenreaders
+   * Render Spinner "as" another HTML element
    */
-  renderTitle?: Renderable
+  as?: AsElementType
   /**
-   * Different-sized spinners
+   * delay spinner rendering for a time (in ms). Used to prevent flickering in case of very fast load times
    */
-  size?: 'x-small' | 'small' | 'medium' | 'large'
+  delay?: number
   /**
-   * Different color schemes for use with light or dark backgrounds
+   * provides a reference to the underlying html root element
    */
-  variant?: 'default' | 'inverse'
+  elementRef?: (element: Element | null) => void
   /**
    * Valid values are `0`, `none`, `auto`, `xxx-small`, `xx-small`, `x-small`,
    * `small`, `medium`, `large`, `x-large`, `xx-large`. Apply these values via
@@ -59,10 +59,17 @@ type SpinnerOwnProps = {
    */
   margin?: Spacing
   /**
-   * provides a reference to the underlying html root element
+   * Give the spinner a title to be read by screenreaders
    */
-  elementRef?: (element: Element | null) => void
-  as?: AsElementType
+  renderTitle?: Renderable
+  /**
+   * Different-sized spinners
+   */
+  size?: 'x-small' | 'small' | 'medium' | 'large'
+  /**
+   * Different color schemes for use with light or dark backgrounds
+   */
+  variant?: 'default' | 'inverse'
 }
 
 type PropKeys = keyof SpinnerOwnProps
@@ -74,11 +81,16 @@ type SpinnerProps = SpinnerOwnProps &
   OtherHTMLAttributes<SpinnerOwnProps> &
   WithDeterministicIdProps
 
+type SpinnerState = {
+  shouldRender: boolean
+}
+
 type SpinnerStyle = ComponentStyle<
   'spinner' | 'circle' | 'circleTrack' | 'circleSpin'
 >
 
 const propTypes: PropValidators<PropKeys> = {
+  delay: PropTypes.number,
   renderTitle: PropTypes.oneOfType([PropTypes.func, PropTypes.node]),
   size: PropTypes.oneOf(['x-small', 'small', 'medium', 'large']),
   variant: PropTypes.oneOf(['default', 'inverse']),
@@ -88,6 +100,7 @@ const propTypes: PropValidators<PropKeys> = {
 }
 
 const allowedProps: AllowedPropKeys = [
+  'delay',
   'renderTitle',
   'size',
   'variant',
@@ -96,5 +109,5 @@ const allowedProps: AllowedPropKeys = [
   'as'
 ]
 
-export type { SpinnerProps, SpinnerStyle }
+export type { SpinnerProps, SpinnerState, SpinnerStyle }
 export { propTypes, allowedProps }