Merge branch 'unstable' into internal

.changeset/fuzzy-trainers-work.md

@@ -0,0 +1,6 @@
+---
+'@shopify/ui-extensions-react': minor
+'@shopify/ui-extensions': minor
+---
+
+Release a new Chat component, chat.render targets and preloads.chat configuration

.changeset/hot-shirts-clean.md

@@ -0,0 +1,5 @@
+---
+'@shopify/ui-extensions': patch
+---
+
+Make POS UI Ext PrintAPI async

.changeset/hot-years-relate.md

@@ -0,0 +1,5 @@
+---
+'@shopify/ui-extensions': patch
+---
+
+POS UI Ext PrintAPI src non-optional

packages/ui-extensions-react/src/surfaces/checkout/components/Chat/examples/basic-chat.example.tsx

@@ -0,0 +1,16 @@
+import {
+  reactExtension,
+  Chat,
+} from '@shopify/ui-extensions-react/checkout';
+
+export default reactExtension(
+  'purchase.checkout.chat.render',
+  () => <Extension />,
+);
+
+// This component requires the configuration of the `extensions.targeting.preloads.chat` in the extensions configuration file.
+// Its value will be used as the `src` attribute of the Chat component.
+
+function Extension() {
+  return <Chat inlineSize={100} blockSize={50} />;
+}

packages/ui-extensions/docs/surfaces/checkout/reference/examples/purchase.checkout.chat.render/default.example.ts

@@ -0,0 +1,18 @@
+import {
+  Chat,
+  extension,
+} from '@shopify/ui-extensions/checkout';
+
+// 1. Choose an extension target
+export default extension(
+  'purchase.checkout.chat.render',
+  (root) => {
+    // 2. Render a Chat UI. This target only accepts the Chat component. Any other components will not render.
+    root.appendChild(
+      root.createComponent(Chat, {
+        inlineSize: 100,
+        blockSize: 50,
+      }),
+    );
+  },
+);

packages/ui-extensions/docs/surfaces/checkout/reference/examples/purchase.checkout.chat.render/default.example.tsx

@@ -0,0 +1,15 @@
+import {
+  Chat,
+  reactExtension,
+} from '@shopify/ui-extensions-react/checkout';
+
+// 1. Choose an extension target
+export default reactExtension(
+  'purchase.checkout.chat.render',
+  () => <Extension />,
+);
+
+function Extension() {
+  // 2. Render a Chat UI. This target only accepts the Chat component. Any other components will not render.
+  return <Chat inlineSize={100} blockSize={50} />;
+}

packages/ui-extensions/docs/surfaces/checkout/reference/examples/purchase.thank-you.chat.render/default.example.ts

@@ -0,0 +1,18 @@
+import {
+  Chat,
+  extension,
+} from '@shopify/ui-extensions/checkout';
+
+// 1. Choose an extension target
+export default extension(
+  'purchase.thank-you.chat.render',
+  (root) => {
+    // 2. Render a Chat UI. This target only accepts the Chat component. Any other components will not render.
+    root.appendChild(
+      root.createComponent(Chat, {
+        inlineSize: 100,
+        blockSize: 50,
+      }),
+    );
+  },
+);

packages/ui-extensions/docs/surfaces/checkout/reference/examples/purchase.thank-you.chat.render/default.example.tsx

@@ -0,0 +1,15 @@
+import {
+  Chat,
+  reactExtension,
+} from '@shopify/ui-extensions-react/checkout';
+
+// 1. Choose an extension target
+export default reactExtension(
+  'purchase.thank-you.chat.render',
+  () => <Extension />,
+);
+
+function Extension() {
+  // 2. Render a Chat UI. This target only accepts the Chat component. Any other components will not render.
+  return <Chat inlineSize={100} blockSize={50} />;
+}

packages/ui-extensions/docs/surfaces/checkout/reference/helper.docs.ts

@@ -145,6 +145,8 @@ export function getExamples(
     ...createExample('purchase.checkout.footer.render-after/default'),
     ...createExample('purchase.thank-you.header.render-after/default'),
     ...createExample('purchase.thank-you.footer.render-after/default'),
+    ...createExample('purchase.checkout.chat.render/default'),
+    ...createExample('purchase.thank-you.chat.render/default'),
     'analytics-publish': {
       description:
         'You can publish analytics events to the Shopify analytics frameworks and they will be propagated to all web pixels on the page.',

packages/ui-extensions/docs/surfaces/checkout/reference/targets/purchase.checkout.chat.render.doc.ts

@@ -0,0 +1,21 @@
+import type {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+import {CHECKOUT_API, getExample, getLinksByTag} from '../helper.docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'purchase.checkout.chat.render',
+  description: `
+A static extension target that floats above the checkout in the bottom right corner of the screen.
+
+> Note: This target only accepts the [Chat](https://shopify.dev/docs/api/checkout-ui-extensions/unstable/components/overlays/chat) component. Any other components will not render.
+  `,
+  defaultExample: getExample('purchase.checkout.chat.render/default', [
+    'jsx',
+    'js',
+  ]),
+  subCategory: 'Overlays',
+  related: getLinksByTag('targets'),
+  ...CHECKOUT_API,
+};
+
+export default data;

packages/ui-extensions/docs/surfaces/checkout/reference/targets/purchase.thank-you.chat.render.doc.ts

@@ -0,0 +1,21 @@
+import type {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+import {THANK_YOU_API, getExample, getLinksByTag} from '../helper.docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'purchase.thank-you.chat.render',
+  description: `
+A static extension target that floats above the Thank you page in the bottom right corner of the screen.
+
+> Note: This target only accepts the [Chat](https://shopify.dev/docs/api/checkout-ui-extensions/unstable/components/overlays/chat) component. Any other components will not render.
+  `,
+  defaultExample: getExample('purchase.thank-you.chat.render/default', [
+    'jsx',
+    'js',
+  ]),
+  subCategory: 'Overlays',
+  related: getLinksByTag('targets'),
+  ...THANK_YOU_API,
+};
+
+export default data;

packages/ui-extensions/docs/surfaces/checkout/staticPages/configuration.doc.ts

@@ -463,6 +463,34 @@ You retrieve these metafields in your extension by reading [\`appMetafields\`](/
         ],
       },
     },
+    {
+      type: 'Generic',
+      anchorLink: 'preloads-definition',
+      title: 'Preloads definition',
+      sectionContent: `
+For specific targets, you must provide the URL of assets or pages loaded by UI components within its extension. This allows Shopify to preload them as early as possible and ensure a performant experience for buyers.
+Currently, the only supported component is \`chat\`.
+The URL for the iframe used in this extension target. The URL can be absolute or relative. Relative URLs are resolved against the app URL.
+For example,
+* if the app URL is \`https://example.com\` and \`chat = "/my-chat-application"\`, the resolved URL will be \`https://example.com/my-chat-application\`.
+* if \`chat = "https://my-chat-application.com"\`, the resolved URL will be \`https://my-chat-application.com\`.
+      `,
+      codeblock: {
+        title: 'Extension target preloads',
+        tabs: [
+          {
+            title: 'shopify.extension.toml',
+            code: './examples/configuration/preloads.example.toml',
+            language: 'toml',
+          },
+          {
+            title: 'Block.jsx',
+            code: './examples/configuration/preloads.example.tsx',
+            language: 'jsx',
+          },
+        ],
+      },
+    },
   ],
 };
 

packages/ui-extensions/docs/surfaces/checkout/staticPages/examples/configuration/preloads.example.toml

@@ -0,0 +1,10 @@
+# ...
+
+[[extensions.targeting]]
+target = "purchase.checkout.chat.render"
+module = "./Block.jsx"
+
+  [extensions.targeting.preloads]
+  chat = "https://my-chat-application.com"
+
+# ...

packages/ui-extensions/docs/surfaces/checkout/staticPages/examples/configuration/preloads.example.tsx

@@ -0,0 +1,10 @@
+// ...
+
+export default reactExtension(
+  'purchase.checkout.chat.render',
+  <Extension />,
+);
+
+function Extension() {
+  // ...
+}

packages/ui-extensions/docs/surfaces/checkout/staticPages/extension-overview.doc.ts

@@ -28,7 +28,7 @@ You register for targets in your [configuration file](/docs/api/checkout-ui-exte
           description: `
 This is the first step in the checkout process where the buyer enters contact information and a delivery address.
 
-See [all extensions targets](/docs/api/checkout-ui-extensions/targets).
+Review [all extensions targets](/docs/api/checkout-ui-extensions/targets).
 `,
           image: 'supported-locations-information.png',
         },
@@ -37,7 +37,7 @@ See [all extensions targets](/docs/api/checkout-ui-extensions/targets).
           description: `
 Point in checkout where the buyer selects a shipping method.
 
-See [all extensions targets](/docs/api/checkout-ui-extensions/targets).
+Review [all extensions targets](/docs/api/checkout-ui-extensions/targets).
 `,
           image: 'supported-locations-shipping.png',
         },
@@ -46,7 +46,7 @@ See [all extensions targets](/docs/api/checkout-ui-extensions/targets).
           description: `
 Point in checkout where the buyer enters their payment information.
 
-See [all extensions targets](/docs/api/checkout-ui-extensions/targets).
+Review [all extensions targets](/docs/api/checkout-ui-extensions/targets).
 `,
           image: 'supported-locations-payment.png',
         },
@@ -55,7 +55,7 @@ See [all extensions targets](/docs/api/checkout-ui-extensions/targets).
           description: `
 Summary of the cart contents, discounts, and order totals.
 
-See [all extensions targets](/docs/api/checkout-ui-extensions/targets).
+Review [all extensions targets](/docs/api/checkout-ui-extensions/targets).
 `,
           image: 'supported-locations-order-summary.png',
         },
@@ -64,7 +64,7 @@ See [all extensions targets](/docs/api/checkout-ui-extensions/targets).
           description: `
 Accelerated checkout where Shopify pre-fills buyer information using their Shop Pay account.
 
-See [all extensions targets](/docs/api/checkout-ui-extensions/targets).
+Review [all extensions targets](/docs/api/checkout-ui-extensions/targets).
 `,
           image: 'supported-locations-shop-pay.png',
         },
@@ -73,7 +73,7 @@ See [all extensions targets](/docs/api/checkout-ui-extensions/targets).
           description: `
 When multiple shipments are expected, a checkout will render split shipping options.
 
-See [all extensions targets](/docs/api/checkout-ui-extensions/targets).
+Review [all extensions targets](/docs/api/checkout-ui-extensions/targets).
 `,
           image: 'supported-locations-split-shipping.png',
         },
@@ -82,7 +82,7 @@ See [all extensions targets](/docs/api/checkout-ui-extensions/targets).
           description: `
 Point in checkout where the buyer can select a store location to pick up their purchase.
 
-See [all extensions targets](/docs/api/checkout-ui-extensions/targets).
+Review [all extensions targets](/docs/api/checkout-ui-extensions/targets).
 `,
           image: 'supported-locations-local-pickup.png',
         },
@@ -91,10 +91,19 @@ See [all extensions targets](/docs/api/checkout-ui-extensions/targets).
           description: `
 Point in checkout where the buyer can select a pickup point to have their purchase delivered to.
 
-See [all extensions targets](/docs/api/checkout-ui-extensions/targets).
+Review [all extensions targets](/docs/api/checkout-ui-extensions/targets).
 `,
           image: 'supported-locations-pickup-points.png',
         },
+        {
+          title: 'Overlays',
+          description: `
+Static extension targets that floats above the checkout.
+
+Review [all extensions targets](/docs/api/checkout-ui-extensions/targets).
+`,
+          image: 'supported-locations-chat.png',
+        },
         {
           title: 'One-page checkout',
           description: `
@@ -131,6 +140,15 @@ Review [all **Thank you** page extensions targets](/docs/api/checkout-ui-extensi
 `,
           image: 'supported-locations-order-summary-thank-you.png',
         },
+        {
+          title: 'Overlays',
+          description: `
+Static extension targets that floats above the Thank you page.
+
+Review [all **Thank you** page extensions targets](/docs/api/checkout-ui-extensions/targets).
+`,
+          image: 'supported-locations-chat-thank-you.png',
+        },
       ],
     },
     {

packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/locale-api.doc.ts

@@ -7,7 +7,7 @@ const generateCodeBlockForLocaleApi = (title: string, fileName: string) =>
 const data: ReferenceEntityTemplateSchema = {
   name: 'Locale API',
   description:
-    'The Locale API allows the extension to retreive the merchants locale.',
+    "The Locale API allows the extension to retrieve the merchant's locale.",
   isVisualComponent: false,
   type: 'APIs',
   definitions: [

packages/ui-extensions/docs/surfaces/point-of-sale/reference/apis/print-api.doc.ts

@@ -1,30 +1,46 @@
 import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
-import {generateCodeBlock} from '../helpers/generateCodeBlock';
+import {
+  generateCodeBlock,
+  generateTSXCodeBlock,
+} from '../helpers/generateCodeBlock';
 
 const generateCodeBlockForPrintApi = (title: string, fileName: string) =>
   generateCodeBlock(title, 'print-api', fileName);
 
 const data: ReferenceEntityTemplateSchema = {
   name: 'Print API',
-  description: `
-The Print API provides access to printing functionality.
-`,
+  description: `The Print API enables document printing functionality in your point of sale extension. Use this API to trigger the native print dialog for your documents.
+
+The \`print()\` method accepts either:
+- A relative path that will be appended to your app's [application_url](/docs/apps/build/cli-for-apps/app-configuration#application_url)
+- A full URL to your app's backend that will be used to return the document to print
+
+Supported document types:
+- HTML documents (recommended for best printing experience)
+- Text files
+- Image files (PNG, JPEG, etc.)
+- PDF files (Note: On Android devices, PDFs will be downloaded and must be printed using an external application)`,
   isVisualComponent: false,
   type: 'APIs',
   definitions: [
     {
       title: 'PrintApi',
-      description: '',
+      description: 'Interface for handling print operations',
       type: 'PrintApiContent',
     },
   ],
   category: 'APIs',
   related: [
     {
       name: 'PrintPreview Component',
-      subtitle: 'See how to use the Print API with a PrintPreview.',
+      subtitle: 'Preview documents before printing',
       url: '/api/pos-ui-extensions/components/printpreview',
     },
+    {
+      name: 'Build a Print Extension',
+      subtitle: 'Learn how to implement printing',
+      url: '/docs/api/pos-ui-extensions/examples/print-extension',
+    },
   ],
   examples: {
     description: 'Examples of using the Print API',
@@ -35,6 +51,20 @@ The Print API provides access to printing functionality.
           'print',
         ),
       },
+      {
+        codeblock: generateTSXCodeBlock(
+          'Print with relative path',
+          'print-api',
+          'print-relative',
+        ),
+      },
+      {
+        codeblock: generateTSXCodeBlock(
+          'Print with full URL',
+          'print-api',
+          'print-full-url',
+        ),
+      },
     ],
   },
 };