Add app home loading API types

Author: andrewiggins

packages/ui-extensions-tester/README.md

@@ -401,6 +401,8 @@ Imports and executes the extension module's default export, rendering the extens
 
 A mock `shopify` global, typed correctly for the target under test. You can mutate any property.
 
+When testing `admin.app.home.render`, the mock `shopify` object also includes `toast`, `app`, and `loading()`.
+
 When testing `admin.app.intent.render`, the mock `shopify.intents` object also includes `response.ok()`, `response.error()`, and `response.closed()`.
 
 #### `extension.fetch`

packages/ui-extensions-tester/src/admin/README.md

@@ -23,6 +23,10 @@ extension.shopify.storage = createStorage({
 });
 ```
 
+## 🏠 App home mocks
+
+The `admin.app.home.render` target mock includes `shopify.toast`, `shopify.app`, and `shopify.loading()`.
+
 ## 🧭 App intent mocks
 
 The `admin.app.intent.render` target mock includes `shopify.intents.response.ok()`, `.error()`, and `.closed()`.

packages/ui-extensions-tester/src/admin/factories.ts

@@ -8,6 +8,7 @@ import type {
   Intents,
   ToastApi,
   AppApi,
+  LoadingApi,
 } from '@shopify/ui-extensions/admin';
 import {createReadonlySignalLike} from '../mocks/signals';
 import {createMockI18n} from '../mocks/i18n';
@@ -119,11 +120,16 @@ function createMockAppApi(): AppApi {
   };
 }
 
+function createMockLoadingApi(): LoadingApi {
+  return () => {};
+}
+
 function createAppHomeMock<T extends ExtensionTarget>(target: T) {
   return {
     ...createMockStandardRenderingApi(target),
     toast: createMockToastApi(),
     app: createMockAppApi(),
+    loading: createMockLoadingApi(),
   };
 }
 

packages/ui-extensions-tester/src/tests/admin-factories.test.ts

@@ -40,6 +40,17 @@ describe('createMockAdminTargetApi', () => {
     expect(api).not.toHaveProperty('resourcePicker');
   });
 
+  it('creates an app home api with loading controls', () => {
+    const api = createMockAdminTargetApi('admin.app.home.render');
+
+    expect(api.extension.target).toBe('admin.app.home.render');
+    expect(typeof api.resourcePicker).toBe('function');
+    expect(typeof api.picker).toBe('function');
+    expect(typeof api.toast.show).toBe('function');
+    expect(typeof api.app.extensions).toBe('function');
+    expect(typeof api.loading).toBe('function');
+  });
+
   it('creates a standard rendering api for app intent targets', () => {
     const api = createMockAdminTargetApi('admin.app.intent.render');
 

packages/ui-extensions/src/surfaces/admin/api.ts

@@ -1,6 +1,7 @@
 export type {I18n, I18nTranslate} from '../../api';
 export type {StandardApi, Intents} from './api/standard/standard';
 export type {ToastApi, ToastOptions} from './api/toast/toast';
+export type {LoadingApi} from './api/loading/loading';
 export type {
   AppApi,
   ExtensionInfo,

packages/ui-extensions/src/surfaces/admin/api/app-home/app-home.ts

@@ -2,9 +2,10 @@ import type {StandardApi} from '../standard/standard';
 import type {ExtensionTarget as AnyExtensionTarget} from '../../extension-targets';
 import type {ToastApi} from '../toast/toast';
 import type {AppApi} from '../app/app';
+import type {LoadingApi} from '../loading/loading';
 
 /**
- * The `AppHomeApi` object provides methods for app home extensions. Access the following properties on the `AppHomeApi` object to authenticate users, query the [GraphQL Admin API](/docs/api/admin-graphql), translate content, handle intents, persist data, display toast notifications, and access app-level data.
+ * The `AppHomeApi` object provides methods for app home extensions. Access the following properties on the `AppHomeApi` object to authenticate users, query the [GraphQL Admin API](/docs/api/admin-graphql), translate content, handle intents, persist data, display toast notifications, control the Admin page-level loading indicator, and access app-level data.
  * @publicDocs
  */
 export interface AppHomeApi<ExtensionTarget extends AnyExtensionTarget>
@@ -18,4 +19,9 @@ export interface AppHomeApi<ExtensionTarget extends AnyExtensionTarget>
    * Provides access to app-level data and functionality. Use this API to query information about extensions registered for the current app, including their activation status and target information.
    */
   app: AppApi;
+
+  /**
+   * Sets the Admin page-level loading indicator. Call `loading(true)` to show the loading indicator while your app home extension performs an asynchronous task. Call `loading(false)`, or call `loading()` without an argument, to hide it when the task completes.
+   */
+  loading: LoadingApi;
 }

packages/ui-extensions/src/surfaces/admin/api/loading/loading.ts

@@ -0,0 +1,9 @@
+/**
+ * Sets the Admin page-level loading indicator for hosted app home extensions.
+ *
+ * Call with `true` to start loading. Call with `false`, or without an argument,
+ * to stop loading.
+ *
+ * @publicDocs
+ */
+export type LoadingApi = (isLoading?: boolean) => void;