@shopify/ui-extensions 1.0.2 → 2.0.0-alpha.0

package/README.md

@@ -1,3 +1,59 @@
 # `@shopify/ui-extensions`
 
-This package contains shared types and utilities for all of the other ui-extensions packages in this repo.
+This package contains the public type definitions and utilities needed to create a Shopify UI extension. This is a generalized package that is intended to be the long-term home of the surface-specific packages in this repository, like `@shopify/checkout-ui-extensions` and `@shopify/admin-ui-extensions`.
+
+Currently, this package contains the API for two [surfaces](https://github.com/Shopify/ui-extensions-private/discussions/1770#discussion-4324275):
+
+- [`admin`](./src/surfaces/admin)
+- [`checkout`](./src/surfaces/checkout)
+
+This surface-based grouping is mostly cosmetic; all extensions use the same underlying technology, and most of the same “core” components (e.g., `Layout`, `BlockStack`, etc) and capabilities (e.g., direct API access, session tokens). Separating APIs by surface makes it easier for a developer to see what is available to them in each context, and gives us a flexible system for introducing components and APIs available in only some surfaces.
+
+An admin extension using “vanilla” JavaScript would be written as follows:
+
+```ts
+import {
+  extension,
+  TextField,
+  EditorSettings,
+} from '@shopify/ui-extensions/admin';
+
+export default extension(
+  'Admin::CheckoutEditor::RenderSettings',
+  (root, {settings, applySettingChange}) => {
+    const editorSettings = root.createComponent(EditorSettings);
+
+    const textfield = root.createComponent(TextField, {
+      label: 'Message',
+      helpText: 'The message to show to buyers when this extension is rendered',
+      value: settings.current.message,
+      onChange(value) {
+        applySettingsChange({key: 'message', value});
+      },
+    });
+
+    editorSettings.appendChild(textfield);
+    root.appendChild(editorSettings);
+  },
+);
+```
+
+## What is a “UI Extension”?
+
+A UI extension is a JavaScript-based module that can hook in to client-side behaviors on any of Shopify’s first party UI surface areas. No matter whether the developer is embedding into the admin or checkout, whether they are rendering UI or [registering listeners for client-side events](https://shopify.dev/apps/pixels); it’s all a UI extension.
+
+The most minimal definition of a UI extension has the following properties:
+
+- A **name** that is presented to merchants when interacting with the extension.
+- The **extension points** that the UI extension implements. These are represented with string identifiers that describe the surface and responsibility of the extension. For example, [`Checkout::CartLines::RenderAfter`](https://shopify.dev/api/checkout-extensions/checkout/extension-points/api) gives the UI Extension the ability to render UI after the cart lines in a checkout; [`WebPixel::Register`](https://shopify.dev/apps/pixels/pixel-extension) registers a Web Pixel to track client-side events. A UI Extension can register to support multiple extension points, and must map each to a JavaScript module in their application.
+
+The types in this package allow us to represent additional details about the extension points developers can implement. Each extension point can define what APIs it supports, including:
+
+- What **UI Components** are available to be rendered, and what properties those UI components accept
+- What **imperative APIs** are provided by the host, for reading and writing data relevant to the extension
+
+The available components and APIs can be different for each extension point. Additionally, Shopify can vary the components and APIs it provides based on many other factors at runtime, like:
+
+- Whether an extension is built by Shopify or a third party
+- Whether the API client that owns the extension has certain approval scopes,
+- Whether the shop or API client has particular beta flags enabled

package/admin.d.ts

@@ -0,0 +1,2 @@
+export * from "./build/ts/surfaces/admin/index.ts";
+export {default} from "./build/ts/surfaces/admin/index.ts";

package/admin.esnext

@@ -0,0 +1,2 @@
+export * from "./build/esnext/surfaces/admin/index.ts/index";
+export {default} from "./build/esnext/surfaces/admin/index.ts/index";

package/admin.js

@@ -0,0 +1 @@
+module.exports = require("./build/cjs/surfaces/admin/index.ts/index");

package/admin.mjs

@@ -0,0 +1,2 @@
+export * from "./build/esm/surfaces/admin/index.ts/index";
+export {default} from "./build/esm/surfaces/admin/index.ts/index";

package/build/cjs/components/BlockStack/BlockStack.js

@@ -0,0 +1,11 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.BlockStack = void 0;
+
+var _core = require("@remote-ui/core");
+
+var BlockStack = (0, _core.createRemoteComponent)('BlockStack');
+exports.BlockStack = BlockStack;

package/build/cjs/components/BlockStack/README.md

@@ -0,0 +1 @@
+# BlockStack

package/build/cjs/components/Button/Button.js

@@ -0,0 +1,11 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.Button = void 0;
+
+var _core = require("@remote-ui/core");
+
+var Button = (0, _core.createRemoteComponent)('Button');
+exports.Button = Button;

package/build/cjs/components/Button/README.md

@@ -0,0 +1 @@
+# Button

package/build/cjs/components/Text/README.md

@@ -0,0 +1 @@
+# Text

package/build/cjs/components/Text/Text.js

@@ -0,0 +1,11 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.Text = void 0;
+
+var _core = require("@remote-ui/core");
+
+var Text = (0, _core.createRemoteComponent)('Text');
+exports.Text = Text;

package/build/cjs/components/TextField/README.md

@@ -0,0 +1 @@
+# TextField

package/build/cjs/components/TextField/TextField.js

@@ -0,0 +1,11 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.TextField = void 0;
+
+var _core = require("@remote-ui/core");
+
+var TextField = (0, _core.createRemoteComponent)('TextField');
+exports.TextField = TextField;

package/build/cjs/components/View/README.md

@@ -0,0 +1 @@
+# View

package/build/cjs/components/View/View.js

@@ -0,0 +1,11 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.View = void 0;
+
+var _core = require("@remote-ui/core");
+
+var View = (0, _core.createRemoteComponent)('View');
+exports.View = View;

package/build/cjs/components/index.js

@@ -0,0 +1,45 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "BlockStack", {
+  enumerable: true,
+  get: function get() {
+    return _BlockStack.BlockStack;
+  }
+});
+Object.defineProperty(exports, "Button", {
+  enumerable: true,
+  get: function get() {
+    return _Button.Button;
+  }
+});
+Object.defineProperty(exports, "Text", {
+  enumerable: true,
+  get: function get() {
+    return _Text.Text;
+  }
+});
+Object.defineProperty(exports, "TextField", {
+  enumerable: true,
+  get: function get() {
+    return _TextField.TextField;
+  }
+});
+Object.defineProperty(exports, "View", {
+  enumerable: true,
+  get: function get() {
+    return _View.View;
+  }
+});
+
+var _BlockStack = require("./BlockStack/BlockStack");
+
+var _Button = require("./Button/Button");
+
+var _Text = require("./Text/Text");
+
+var _TextField = require("./TextField/TextField");
+
+var _View = require("./View/View");

package/build/cjs/components.js

@@ -0,0 +1,45 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "BlockStack", {
+  enumerable: true,
+  get: function get() {
+    return _BlockStack.BlockStack;
+  }
+});
+Object.defineProperty(exports, "Button", {
+  enumerable: true,
+  get: function get() {
+    return _Button.Button;
+  }
+});
+Object.defineProperty(exports, "Text", {
+  enumerable: true,
+  get: function get() {
+    return _Text.Text;
+  }
+});
+Object.defineProperty(exports, "TextField", {
+  enumerable: true,
+  get: function get() {
+    return _TextField.TextField;
+  }
+});
+Object.defineProperty(exports, "View", {
+  enumerable: true,
+  get: function get() {
+    return _View.View;
+  }
+});
+
+var _BlockStack = require("./components/BlockStack/BlockStack");
+
+var _Button = require("./components/Button/Button");
+
+var _Text = require("./components/Text/Text");
+
+var _TextField = require("./components/TextField/TextField");
+
+var _View = require("./components/View/View");

package/build/cjs/index.js

@@ -1 +1,44 @@
-"use strict";
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+
+var _api = require("./api");
+
+Object.keys(_api).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _api[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function get() {
+      return _api[key];
+    }
+  });
+});
+
+var _components = require("./components");
+
+Object.keys(_components).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _components[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function get() {
+      return _components[key];
+    }
+  });
+});
+
+var _extension = require("./extension");
+
+Object.keys(_extension).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _extension[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function get() {
+      return _extension[key];
+    }
+  });
+});

package/build/cjs/surfaces/admin/api/checkout-editor/README.md

@@ -0,0 +1 @@
+# Checkout editor API

package/build/cjs/surfaces/admin/api/standard/README.md

@@ -0,0 +1 @@
+# Standard admin API

package/build/cjs/{types/shared/index.js → surfaces/admin/components.js}

@@ -4,15 +4,15 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 
-var _Spacing = require("./Spacing");
+var _components = require("../../components");
 
-Object.keys(_Spacing).forEach(function (key) {
+Object.keys(_components).forEach(function (key) {
   if (key === "default" || key === "__esModule") return;
-  if (key in exports && exports[key] === _Spacing[key]) return;
+  if (key in exports && exports[key] === _components[key]) return;
   Object.defineProperty(exports, key, {
     enumerable: true,
     get: function get() {
-      return _Spacing[key];
+      return _components[key];
     }
   });
 });

package/build/cjs/surfaces/admin/extension.js

@@ -0,0 +1,27 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+var _exportNames = {
+  extension: true
+};
+exports.extension = void 0;
+
+var _registration = require("../../utilities/registration");
+
+var _extension = require("../../extension");
+
+Object.keys(_extension).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (Object.prototype.hasOwnProperty.call(_exportNames, key)) return;
+  if (key in exports && exports[key] === _extension[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function get() {
+      return _extension[key];
+    }
+  });
+});
+var extension = (0, _registration.createExtensionRegistrationFunction)();
+exports.extension = extension;

package/build/cjs/surfaces/admin/index.js

@@ -0,0 +1,70 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+
+var _api = require("./api");
+
+Object.keys(_api).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _api[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function get() {
+      return _api[key];
+    }
+  });
+});
+
+var _components = require("./components");
+
+Object.keys(_components).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _components[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function get() {
+      return _components[key];
+    }
+  });
+});
+
+var _extensionPoints = require("./extension-points");
+
+Object.keys(_extensionPoints).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _extensionPoints[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function get() {
+      return _extensionPoints[key];
+    }
+  });
+});
+
+var _extension = require("./extension");
+
+Object.keys(_extension).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _extension[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function get() {
+      return _extension[key];
+    }
+  });
+});
+
+var _shared = require("./shared");
+
+Object.keys(_shared).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _shared[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function get() {
+      return _shared[key];
+    }
+  });
+});

package/build/cjs/surfaces/checkout/api/cart-line-details/README.md

@@ -0,0 +1 @@
+# Checkout cart line details API

package/build/cjs/surfaces/checkout/api/standard/README.md

@@ -0,0 +1 @@
+# Standard checkout API

package/build/cjs/surfaces/checkout/components.js

@@ -0,0 +1,18 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+
+var _components = require("../../components");
+
+Object.keys(_components).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _components[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function get() {
+      return _components[key];
+    }
+  });
+});

package/build/cjs/surfaces/checkout/extension.js

@@ -0,0 +1,27 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+var _exportNames = {
+  extension: true
+};
+exports.extension = void 0;
+
+var _registration = require("../../utilities/registration");
+
+var _extension = require("../../extension");
+
+Object.keys(_extension).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (Object.prototype.hasOwnProperty.call(_exportNames, key)) return;
+  if (key in exports && exports[key] === _extension[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function get() {
+      return _extension[key];
+    }
+  });
+});
+var extension = (0, _registration.createExtensionRegistrationFunction)();
+exports.extension = extension;

package/build/cjs/surfaces/checkout/index.js

@@ -0,0 +1,70 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+
+var _api = require("./api");
+
+Object.keys(_api).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _api[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function get() {
+      return _api[key];
+    }
+  });
+});
+
+var _components = require("./components");
+
+Object.keys(_components).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _components[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function get() {
+      return _components[key];
+    }
+  });
+});
+
+var _extensionPoints = require("./extension-points");
+
+Object.keys(_extensionPoints).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _extensionPoints[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function get() {
+      return _extensionPoints[key];
+    }
+  });
+});
+
+var _extension = require("./extension");
+
+Object.keys(_extension).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _extension[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function get() {
+      return _extension[key];
+    }
+  });
+});
+
+var _shared = require("./shared");
+
+Object.keys(_shared).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _shared[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function get() {
+      return _shared[key];
+    }
+  });
+});