cozy-ui-plus 12.1.5 → 12.2.1

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [12.2.1](https://github.com/cozy/cozy-libs/compare/cozy-ui-plus@12.2.0...cozy-ui-plus@12.2.1) (2026-07-28)
+
+**Note:** Version bump only for package cozy-ui-plus
+
+# [12.2.0](https://github.com/cozy/cozy-libs/compare/cozy-ui-plus@12.1.5...cozy-ui-plus@12.2.0) (2026-07-27)
+
+### Features
+
+- **intent:** Wait for intent readiness signal ([b8d64dd](https://github.com/cozy/cozy-libs/commit/b8d64dd023e57ef976df08fda295ab6fa643b7ad))
+
 ## [12.1.5](https://github.com/cozy/cozy-libs/compare/cozy-ui-plus@12.1.4...cozy-ui-plus@12.1.5) (2026-07-23)
 
 **Note:** Version bump only for package cozy-ui-plus

package/dist/Intent/IntentDialogOpener/index.js

@@ -23,7 +23,7 @@ var _Dialog = _interopRequireDefault(require("cozy-ui/transpiled/react/Dialog"))
 
 var _IntentIframe = _interopRequireWildcard(require("../IntentIframe"));
 
-var _excluded = ["options", "action", "doctype", "children", "closable", "showCloseButton", "create", "tag", "onComplete", "onDismiss", "onReadyToUse", "iframeProps", "Component"];
+var _excluded = ["options", "action", "doctype", "children", "closable", "showCloseButton", "create", "tag", "onComplete", "onDismiss", "onReadyToUse", "waitForReadyToUse", "iframeProps", "Component"];
 
 function _getRequireWildcardCache(nodeInterop) { if (typeof WeakMap !== "function") return null; var cacheBabelInterop = new WeakMap(); var cacheNodeInterop = new WeakMap(); return (_getRequireWildcardCache = function _getRequireWildcardCache(nodeInterop) { return nodeInterop ? cacheNodeInterop : cacheBabelInterop; })(nodeInterop); }
 
@@ -45,6 +45,7 @@ var IntentDialogOpener = function IntentDialogOpener(props) {
       onComplete = props.onComplete,
       onDismiss = props.onDismiss,
       onReadyToUse = props.onReadyToUse,
+      waitForReadyToUse = props.waitForReadyToUse,
       iframeProps = props.iframeProps,
       Component = props.Component,
       componentProps = (0, _objectWithoutProperties2.default)(props, _excluded);
@@ -96,6 +97,7 @@ var IntentDialogOpener = function IntentDialogOpener(props) {
       onCancel: handleDismiss,
       onTerminate: handleComplete,
       onReadyToUse: onReadyToUse,
+      waitForReadyToUse: waitForReadyToUse,
       iframeProps: iframeProps
     })));
   }
@@ -116,6 +118,9 @@ IntentDialogOpener.propTypes = {
   /** Called when the intent service signals it is ready to use */
   onReadyToUse: _propTypes.default.func,
 
+  /** Keep the loading state until the intent service signals it is ready to use */
+  waitForReadyToUse: _propTypes.default.bool,
+
   /** Action you want to execute */
   action: _propTypes.default.string.isRequired,
 
@@ -141,7 +146,8 @@ IntentDialogOpener.defaultProps = {
   tag: 'span',
   closable: true,
   Component: _Dialog.default,
-  showCloseButton: true
+  showCloseButton: true,
+  waitForReadyToUse: false
 };
 var _default = IntentDialogOpener;
 exports.default = _default;

package/dist/Intent/IntentIframe/index.js

@@ -46,6 +46,7 @@ function _isNativeReflectConstruct() { if (typeof Reflect === "undefined" || !Re
 var styles = {
   "intentContainer": "styles__intentContainer___5Zqqq",
   "intentPlaceHolder": "styles__intentPlaceHolder___1f_u6",
+  "intentContainer__loader": "styles__intentContainer__loader___1krAq",
   "intentContainer__error": "styles__intentContainer__error___YO3Lz"
 };
 var DEFAULT_DATA = {
@@ -71,16 +72,36 @@ var IntentIframe = /*#__PURE__*/function (_React$Component) {
 
     _this = _super.call.apply(_super, [this].concat(args));
     (0, _defineProperty2.default)((0, _assertThisInitialized2.default)(_this), "state", {
-      loading: false
+      error: null,
+      frameLoaded: false,
+      readyToUse: false
     });
     (0, _defineProperty2.default)((0, _assertThisInitialized2.default)(_this), "onFrameLoaded", function () {
-      var _this$props$iframePro, _this$props$iframePro2;
+      _this.setState({
+        frameLoaded: true
+      }, function () {
+        if (!_this.props.waitForReadyToUse || _this.state.readyToUse) {
+          _this.setIsLoading(false);
+        }
+      });
+    });
+    (0, _defineProperty2.default)((0, _assertThisInitialized2.default)(_this), "onReadyToUse", function () {
+      var _this$props$onReadyTo, _this$props;
 
       _this.setState({
-        loading: false
+        readyToUse: true
+      }, function () {
+        if (_this.props.waitForReadyToUse && _this.state.frameLoaded) {
+          _this.setIsLoading(false);
+        }
       });
 
-      (_this$props$iframePro = _this.props.iframeProps) === null || _this$props$iframePro === void 0 ? void 0 : (_this$props$iframePro2 = _this$props$iframePro.setIsLoading) === null || _this$props$iframePro2 === void 0 ? void 0 : _this$props$iframePro2.call(_this$props$iframePro, false);
+      (_this$props$onReadyTo = (_this$props = _this.props).onReadyToUse) === null || _this$props$onReadyTo === void 0 ? void 0 : _this$props$onReadyTo.call(_this$props);
+    });
+    (0, _defineProperty2.default)((0, _assertThisInitialized2.default)(_this), "setIsLoading", function (isLoading) {
+      var _this$props$iframePro, _this$props$iframePro2;
+
+      (_this$props$iframePro = _this.props.iframeProps) === null || _this$props$iframePro === void 0 ? void 0 : (_this$props$iframePro2 = _this$props$iframePro.setIsLoading) === null || _this$props$iframePro2 === void 0 ? void 0 : _this$props$iframePro2.call(_this$props$iframePro, isLoading);
     });
     return _this;
   }
@@ -90,14 +111,14 @@ var IntentIframe = /*#__PURE__*/function (_React$Component) {
     value: function componentDidMount() {
       var _this2 = this;
 
-      var _this$props = this.props,
-          action = _this$props.action,
-          data = _this$props.data,
-          type = _this$props.type,
-          onCancel = _this$props.onCancel,
-          onError = _this$props.onError,
-          onTerminate = _this$props.onTerminate,
-          client = _this$props.client;
+      var _this$props2 = this.props,
+          action = _this$props2.action,
+          data = _this$props2.data,
+          type = _this$props2.type,
+          onCancel = _this$props2.onCancel,
+          onError = _this$props2.onError,
+          onTerminate = _this$props2.onTerminate,
+          client = _this$props2.client;
       console.warn('Be carful to use `withBreakpoints()` and not `useBreakpoints()` in intents. See https://github.com/cozy/cozy-ui/issues/1807');
       var create;
 
@@ -110,28 +131,22 @@ var IntentIframe = /*#__PURE__*/function (_React$Component) {
         create = intents.create;
       }
 
-      this.setState({
-        loading: true
-      });
       create(action, type, _objectSpread(_objectSpread({}, DEFAULT_DATA), data)).start(this.intentViewer, {
         onReady: this.onFrameLoaded,
         onHideCross: this.props.onHideCross,
         onShowCross: this.props.onShowCross,
-        onReadyToUse: this.props.onReadyToUse
+        onReadyToUse: this.onReadyToUse
       }).then(function (result) {
         // eslint-disable-next-line promise/always-return
         result ? onTerminate && onTerminate(result) : onCancel();
       }).catch(function (error) {
-        var _this2$props$iframePr, _this2$props$iframePr2;
-
         onError === null || onError === void 0 ? void 0 : onError(error);
 
         _this2.setState({
-          error: error,
-          loading: false
+          error: error
         });
 
-        (_this2$props$iframePr = _this2.props.iframeProps) === null || _this2$props$iframePr === void 0 ? void 0 : (_this2$props$iframePr2 = _this2$props$iframePr.setIsLoading) === null || _this2$props$iframePr2 === void 0 ? void 0 : _this2$props$iframePr2.call(_this2$props$iframePr, false);
+        _this2.setIsLoading(false);
       });
     }
   }, {
@@ -139,19 +154,27 @@ var IntentIframe = /*#__PURE__*/function (_React$Component) {
     value: function render() {
       var _this3 = this;
 
-      var iframeProps = this.props.iframeProps;
+      var _this$props3 = this.props,
+          iframeProps = _this$props3.iframeProps,
+          waitForReadyToUse = _this$props3.waitForReadyToUse;
       var _this$state = this.state,
           error = _this$state.error,
-          loading = _this$state.loading;
+          frameLoaded = _this$state.frameLoaded,
+          readyToUse = _this$state.readyToUse;
+      var loading = error === null && (!frameLoaded || waitForReadyToUse && !readyToUse);
       return /*#__PURE__*/_react.default.createElement("div", (0, _extends2.default)({
         ref: function ref(intentViewer) {
           return _this3.intentViewer = intentViewer;
         },
         className: styles.intentContainer,
-        "aria-busy": loading
-      }, (0, _get.default)(iframeProps, 'wrapperProps')), loading && /*#__PURE__*/_react.default.createElement(_Spinner.default, (0, _extends2.default)({
+        "aria-busy": loading,
+        "data-iframe-loaded": frameLoaded,
+        "data-waiting-for-ready-to-use": waitForReadyToUse && !readyToUse
+      }, (0, _get.default)(iframeProps, 'wrapperProps')), loading && /*#__PURE__*/_react.default.createElement("div", {
+        className: styles.intentContainer__loader
+      }, /*#__PURE__*/_react.default.createElement(_Spinner.default, (0, _extends2.default)({
         size: "xxlarge"
-      }, (0, _get.default)(iframeProps, 'spinnerProps'))), error && /*#__PURE__*/_react.default.createElement("div", {
+      }, (0, _get.default)(iframeProps, 'spinnerProps')))), error && /*#__PURE__*/_react.default.createElement("div", {
         className: styles.intentContainer__error
       }, error.message));
     }
@@ -177,10 +200,12 @@ IntentIframe.propTypes = {
   iframeProps: iframeProps,
   onHideCross: _propTypes.default.func,
   onShowCross: _propTypes.default.func,
-  onReadyToUse: _propTypes.default.func
+  onReadyToUse: _propTypes.default.func,
+  waitForReadyToUse: _propTypes.default.bool
 };
 IntentIframe.defaultProps = {
-  data: {}
+  data: {},
+  waitForReadyToUse: false
 };
 
 var _default = (0, _cozyClient.withClient)(IntentIframe);

package/dist/src/Intent/IntentDialogOpener/index.d.ts

@@ -10,6 +10,7 @@ declare namespace IntentDialogOpener {
         export let onComplete: PropTypes.Requireable<(...args: any[]) => any>;
         export let onDismiss: PropTypes.Requireable<(...args: any[]) => any>;
         export let onReadyToUse: PropTypes.Requireable<(...args: any[]) => any>;
+        export let waitForReadyToUse: PropTypes.Requireable<boolean>;
         export let action: PropTypes.Validator<string>;
         export let doctype: PropTypes.Validator<string>;
         export let closable: PropTypes.Validator<boolean>;
@@ -26,6 +27,8 @@ declare namespace IntentDialogOpener {
         export { Dialog as Component };
         let showCloseButton_1: boolean;
         export { showCloseButton_1 as showCloseButton };
+        let waitForReadyToUse_1: boolean;
+        export { waitForReadyToUse_1 as waitForReadyToUse };
     }
 }
 import PropTypes from 'prop-types';

package/dist/src/Intent/IntentDialogOpener/index.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/Intent/IntentIframe/index.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/stylesheet.css

@@ -409,11 +409,31 @@ iframe {
   justify-content: center;
   align-items: center;
 }
+.styles__intentContainer___5Zqqq {
+  position: relative;
+}
+.styles__intentContainer__loader___1krAq {
+  display: flex;
+  justify-content: center;
+  align-items: center;
+}
+.styles__intentContainer___5Zqqq[data-iframe-loaded=true] .styles__intentContainer__loader___1krAq {
+  position: absolute;
+  z-index: 1;
+  top: 0;
+  right: 0;
+  bottom: 0;
+  left: 0;
+  background-color: var(--paperBackgroundColor);
+}
 /* Don't mess with the spinner centering until the iframe is fully loaded. */
-.styles__intentContainer___5Zqqq[aria-busy=true] iframe {
+.styles__intentContainer___5Zqqq[data-iframe-loaded=false] iframe {
   height: 0;
   width: 0;
 }
+.styles__intentContainer___5Zqqq[data-waiting-for-ready-to-use=true] iframe {
+  visibility: hidden;
+}
 .styles__intentContainer__error___YO3Lz {
   color: var(--errorColor);
   font-size: 1.5em;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cozy-ui-plus",
-  "version": "12.1.5",
+  "version": "12.2.1",
   "description": "Cozy-ui-plus is an extension of cozy-ui and provides components based on cozy-client",
   "main": "dist/index.js",
   "license": "MIT",
@@ -36,9 +36,9 @@
     "cozy-client": "^60.21.3",
     "cozy-device-helper": "2.0.0",
     "cozy-intent": "^2.31.1",
-    "cozy-interapp": "^0.18.1",
+    "cozy-interapp": "^0.18.2",
     "cozy-logger": "^1.18.1",
-    "cozy-sharing": "^37.2.3",
+    "cozy-sharing": "^37.2.5",
     "cozy-stack-client": "^60.21.1",
     "cozy-ui": "^138.1.0",
     "jest": "30.3.0",
@@ -78,5 +78,5 @@
     "react-dom": "^16 || ^17 || ^18",
     "twake-i18n": ">=0.3.0"
   },
-  "gitHead": "5a5005bb37840651944ccb730a749066a719d1a6"
+  "gitHead": "663ae9860187ebdc6d6a2cfa2e7919d8a39c824f"
 }

package/src/Intent/IntentDialogOpener/Readme.md

@@ -16,6 +16,7 @@ import DemoProvider from 'cozy-ui/docs/components/DemoProvider'
     fullWidth // extra props will be passed to the dialog
     maxWidth="md" // extra props will be passed to the dialog
     iframeProps={{ spinnerProps: { middle: true } }}
+    waitForReadyToUse
     onComplete={res => alert('intent has completed ! ' + JSON.stringify(res))}
     onDismiss={() => alert('intent has been dismissed !')}
   >
@@ -23,3 +24,7 @@ import DemoProvider from 'cozy-ui/docs/components/DemoProvider'
   </IntentDialogOpener>
 </DemoProvider>
 ```
+
+Set `waitForReadyToUse` to keep the intent hidden behind the loading spinner
+until its service sends the `readyToUse` signal. This option is disabled by
+default because older intent services do not send this signal.

package/src/Intent/IntentDialogOpener/index.jsx

@@ -23,6 +23,7 @@ const IntentDialogOpener = props => {
     onComplete,
     onDismiss,
     onReadyToUse,
+    waitForReadyToUse,
     iframeProps,
     Component,
     ...componentProps
@@ -70,6 +71,7 @@ const IntentDialogOpener = props => {
           onCancel={handleDismiss}
           onTerminate={handleComplete}
           onReadyToUse={onReadyToUse}
+          waitForReadyToUse={waitForReadyToUse}
           iframeProps={iframeProps}
         />
       </Component>
@@ -88,6 +90,8 @@ IntentDialogOpener.propTypes = {
   onDismiss: PropTypes.func,
   /** Called when the intent service signals it is ready to use */
   onReadyToUse: PropTypes.func,
+  /** Keep the loading state until the intent service signals it is ready to use */
+  waitForReadyToUse: PropTypes.bool,
   /** Action you want to execute */
   action: PropTypes.string.isRequired,
   /** Doctype on which you want to execute the action */
@@ -108,7 +112,8 @@ IntentDialogOpener.defaultProps = {
   tag: 'span',
   closable: true,
   Component: Dialog,
-  showCloseButton: true
+  showCloseButton: true,
+  waitForReadyToUse: false
 }
 
 export default IntentDialogOpener

package/src/Intent/IntentDialogOpener/index.spec.jsx

@@ -0,0 +1,44 @@
+import { fireEvent, render } from '@testing-library/react'
+import React from 'react'
+
+import IntentDialogOpener from './index'
+
+jest.mock('cozy-ui/transpiled/react/CozyDialogs', () => ({
+  DialogCloseButton: () => null
+}))
+
+jest.mock('cozy-ui/transpiled/react/Dialog', () => ({ children }) => (
+  <div>{children}</div>
+))
+
+jest.mock('../IntentIframe', () => ({
+  __esModule: true,
+  default: ({ waitForReadyToUse }) => (
+    <div
+      data-testid="intent-iframe"
+      data-wait-for-ready-to-use={waitForReadyToUse}
+    />
+  ),
+  iframeProps: require('prop-types').shape({})
+}))
+
+describe('IntentDialogOpener', () => {
+  it('forwards waitForReadyToUse to the intent iframe', () => {
+    const { getByRole, getByTestId } = render(
+      <IntentDialogOpener
+        action="PICK"
+        doctype="io.cozy.files"
+        waitForReadyToUse
+      >
+        <button type="button">Open</button>
+      </IntentDialogOpener>
+    )
+
+    fireEvent.click(getByRole('button', { name: 'Open' }))
+
+    expect(getByTestId('intent-iframe')).toHaveAttribute(
+      'data-wait-for-ready-to-use',
+      'true'
+    )
+  })
+})

package/src/Intent/IntentIframe/Readme.md

@@ -19,9 +19,14 @@ import utils from '../../docs/utils'
   onCancel={() => alert('intent cancelled')}
   onError={(error) => alert('intent has failed with error: ' + error.message)}
   onTerminate={doc => alert('intent has completed ! ' + JSON.stringify(doc))}
+  waitForReadyToUse
 />
 ```
 
+Set `waitForReadyToUse` to keep the intent hidden behind the loading spinner
+until its service sends the `readyToUse` signal. This option is disabled by
+default because older intent services do not send this signal.
+
 ### Within an application side controled Dialog
 
 Sometimes you have to render an Intent inside a modal, and handle the modal opening state on the application side. You can then use IntentIframe wrapped in a Dialog for that use case, instead of using IntentDialogOpener component (that is useful to start a new intent modal from a click on a button).

package/src/Intent/IntentIframe/index.jsx

@@ -18,7 +18,7 @@ const DEFAULT_DATA = {
 }
 
 class IntentIframe extends React.Component {
-  state = { loading: false }
+  state = { error: null, frameLoaded: false, readyToUse: false }
 
   componentDidMount() {
     const { action, data, type, onCancel, onError, onTerminate, client } =
@@ -36,7 +36,6 @@ class IntentIframe extends React.Component {
       create = intents.create
     }
 
-    this.setState({ loading: true })
     create(action, type, {
       ...DEFAULT_DATA,
       ...data
@@ -45,7 +44,7 @@ class IntentIframe extends React.Component {
         onReady: this.onFrameLoaded,
         onHideCross: this.props.onHideCross,
         onShowCross: this.props.onShowCross,
-        onReadyToUse: this.props.onReadyToUse
+        onReadyToUse: this.onReadyToUse
       })
       .then(result => {
         // eslint-disable-next-line promise/always-return
@@ -53,29 +52,51 @@ class IntentIframe extends React.Component {
       })
       .catch(error => {
         onError?.(error)
-        this.setState({ error: error, loading: false })
-        this.props.iframeProps?.setIsLoading?.(false)
+        this.setState({ error })
+        this.setIsLoading(false)
       })
   }
 
   onFrameLoaded = () => {
-    this.setState({ loading: false })
-    this.props.iframeProps?.setIsLoading?.(false)
+    this.setState({ frameLoaded: true }, () => {
+      if (!this.props.waitForReadyToUse || this.state.readyToUse) {
+        this.setIsLoading(false)
+      }
+    })
+  }
+
+  onReadyToUse = () => {
+    this.setState({ readyToUse: true }, () => {
+      if (this.props.waitForReadyToUse && this.state.frameLoaded) {
+        this.setIsLoading(false)
+      }
+    })
+    this.props.onReadyToUse?.()
+  }
+
+  setIsLoading = isLoading => {
+    this.props.iframeProps?.setIsLoading?.(isLoading)
   }
 
   render() {
-    const { iframeProps } = this.props
-    const { error, loading } = this.state
+    const { iframeProps, waitForReadyToUse } = this.props
+    const { error, frameLoaded, readyToUse } = this.state
+    const loading =
+      error === null && (!frameLoaded || (waitForReadyToUse && !readyToUse))
 
     return (
       <div
         ref={intentViewer => (this.intentViewer = intentViewer)}
         className={styles.intentContainer}
         aria-busy={loading}
+        data-iframe-loaded={frameLoaded}
+        data-waiting-for-ready-to-use={waitForReadyToUse && !readyToUse}
         {...get(iframeProps, 'wrapperProps')}
       >
         {loading && (
-          <Spinner size="xxlarge" {...get(iframeProps, 'spinnerProps')} />
+          <div className={styles.intentContainer__loader}>
+            <Spinner size="xxlarge" {...get(iframeProps, 'spinnerProps')} />
+          </div>
         )}
         {error && (
           <div className={styles.intentContainer__error}>{error.message}</div>
@@ -103,11 +124,13 @@ IntentIframe.propTypes = {
   iframeProps: iframeProps,
   onHideCross: PropTypes.func,
   onShowCross: PropTypes.func,
-  onReadyToUse: PropTypes.func
+  onReadyToUse: PropTypes.func,
+  waitForReadyToUse: PropTypes.bool
 }
 
 IntentIframe.defaultProps = {
-  data: {}
+  data: {},
+  waitForReadyToUse: false
 }
 
 export default withClient(IntentIframe)

package/src/Intent/IntentIframe/index.spec.jsx

@@ -0,0 +1,121 @@
+import { act, render, waitFor } from '@testing-library/react'
+import React from 'react'
+
+import IntentIframe from './index'
+
+jest.mock('cozy-ui/transpiled/react/Spinner', () => () => (
+  <div data-testid="intent-spinner" />
+))
+
+function setup({ startError = null, waitForReadyToUse = false } = {}) {
+  let startOptions
+  const start = jest.fn((element, options) => {
+    startOptions = options
+    element.appendChild(document.createElement('iframe'))
+    return startError ? Promise.reject(startError) : new Promise(() => {})
+  })
+  const create = jest.fn(() => ({ start }))
+  const onError = jest.fn()
+  const onReadyToUse = jest.fn()
+  const setIsLoading = jest.fn()
+
+  const result = render(
+    <IntentIframe
+      action="PICK"
+      client={{}}
+      create={create}
+      iframeProps={{ setIsLoading }}
+      onCancel={jest.fn()}
+      onError={onError}
+      onReadyToUse={onReadyToUse}
+      onTerminate={jest.fn()}
+      type="io.cozy.files"
+      waitForReadyToUse={waitForReadyToUse}
+    />
+  )
+
+  return {
+    ...result,
+    getStartOptions: () => startOptions,
+    onError,
+    onReadyToUse,
+    setIsLoading
+  }
+}
+
+describe('IntentIframe', () => {
+  beforeEach(() => {
+    jest.spyOn(console, 'warn').mockImplementation(() => {})
+  })
+
+  afterEach(() => {
+    jest.restoreAllMocks()
+  })
+
+  it('keeps the iframe rendered behind the spinner until it is ready to use', () => {
+    const {
+      container,
+      getStartOptions,
+      onReadyToUse,
+      queryByTestId,
+      setIsLoading
+    } = setup({ waitForReadyToUse: true })
+
+    act(() => getStartOptions().onReady())
+
+    expect(queryByTestId('intent-spinner')).toBeInTheDocument()
+    expect(container.querySelector('iframe')).toBeInTheDocument()
+    expect(
+      container.querySelector(
+        '[data-iframe-loaded="true"][data-waiting-for-ready-to-use="true"]'
+      )
+    ).toBeInTheDocument()
+    expect(setIsLoading).not.toHaveBeenCalled()
+
+    act(() => getStartOptions().onReadyToUse())
+
+    expect(queryByTestId('intent-spinner')).toBe(null)
+    expect(onReadyToUse).toHaveBeenCalledTimes(1)
+    expect(setIsLoading).toHaveBeenCalledWith(false)
+  })
+
+  it('waits for the iframe when readyToUse is received first', () => {
+    const { getStartOptions, queryByTestId, setIsLoading } = setup({
+      waitForReadyToUse: true
+    })
+
+    act(() => getStartOptions().onReadyToUse())
+
+    expect(queryByTestId('intent-spinner')).toBeInTheDocument()
+    expect(setIsLoading).not.toHaveBeenCalled()
+
+    act(() => getStartOptions().onReady())
+
+    expect(queryByTestId('intent-spinner')).toBe(null)
+    expect(setIsLoading).toHaveBeenCalledWith(false)
+  })
+
+  it('hides the spinner when the iframe loads by default', () => {
+    const { getStartOptions, queryByTestId, setIsLoading } = setup()
+
+    act(() => getStartOptions().onReady())
+    act(() => getStartOptions().onReadyToUse())
+
+    expect(queryByTestId('intent-spinner')).toBe(null)
+    expect(setIsLoading).toHaveBeenCalledTimes(1)
+  })
+
+  it('shows intent errors instead of waiting for readyToUse', async () => {
+    const error = new Error('Intent failed')
+    const { container, onError, queryByTestId, setIsLoading } = setup({
+      startError: error,
+      waitForReadyToUse: true
+    })
+
+    await waitFor(() => expect(queryByTestId('intent-spinner')).toBe(null))
+
+    expect(container).toHaveTextContent('Intent failed')
+    expect(onError).toHaveBeenCalledWith(error)
+    expect(setIsLoading).toHaveBeenCalledWith(false)
+  })
+})

package/src/Intent/IntentIframe/styles.styl

@@ -11,11 +11,31 @@ iframe
     justify-content center
     align-items center
 
+.intentContainer
+    position relative
+
+.intentContainer__loader
+    display flex
+    justify-content center
+    align-items center
+
+.intentContainer[data-iframe-loaded=true] .intentContainer__loader
+    position absolute
+    z-index 1
+    top 0
+    right 0
+    bottom 0
+    left 0
+    background-color var(--paperBackgroundColor)
+
 /* Don't mess with the spinner centering until the iframe is fully loaded. */
-.intentContainer[aria-busy=true] iframe
+.intentContainer[data-iframe-loaded=false] iframe
     height 0
     width 0
 
+.intentContainer[data-waiting-for-ready-to-use=true] iframe
+    visibility hidden
+
 .intentContainer__error
     color var(--errorColor)
     font-size 1.5em