Merge descriptions update - surface agnostic + minor tweaks.

Author: elisaseijas

packages/ui-extensions/buildTargetDts.ts

@@ -22,6 +22,10 @@ function copyComponentDefinitions({
   buildPath: string;
   surface: string;
 }) {
+  if (surface === 'checkout') {
+    // HACK: Checkout doesn't yet have `<component>.d.ts` files, so we can't process them
+    return true;
+  }
   const componentsSrcPath = join(srcPath, 'components');
   const componentsBuildPath = join(
     buildPath,

packages/ui-extensions/docs/surfaces/checkout/build-docs.sh

@@ -32,7 +32,6 @@ fi
 COMPILE_DOCS="yarn tsc --project $DOCS_PATH/tsconfig.docs.json --types react --moduleResolution node  --target esNext  --module CommonJS && yarn generate-docs --overridePath ./$DOCS_PATH/typeOverride.json --input ./$DOCS_PATH/reference ./$SRC_PATH --typesInput ./$SRC_PATH ../ui-extensions-react/$SRC_PATH --output ./$DOCS_PATH/generated"
 COMPILE_STATIC_PAGES="yarn tsc $DOCS_PATH/staticPages/*.doc.ts --types react --moduleResolution node  --target esNext  --module CommonJS && yarn generate-docs --isLandingPage --input ./$DOCS_PATH/staticPages --output ./$DOCS_PATH/generated"
 
-
 if echo "$PWD" | grep -q '\checkout-web'; then
   # We are generating docs from the private package, which does not have other surfaces aside from checkout
   eval $COMPILE_DOCS && eval $COMPILE_STATIC_PAGES
@@ -72,6 +71,7 @@ if [ $sed_exit -ne 0 ]; then
   fail_and_exit $sed_exit
 fi
 
+copy_generated_docs_to_shopify_dev() {
 # Copy the generated docs to shopify-dev
 if [ -d $SHOPIFY_DEV_PATH ]; then
   mkdir -p $SHOPIFY_DEV_PATH/db/data/docs/templated_apis/checkout_extensions/$API_VERSION
@@ -92,5 +92,15 @@ if [ -d $SHOPIFY_DEV_PATH ]; then
     echo "Docs: https://shopify-dev.myshopify.io/docs/api/checkout-ui-extensions"
   fi
 else
-  echo "Not copying docs to shopify-dev because it was not found at $SHOPIFY_DEV_PATH."
+    echo "Not copying docs to shopify-dev because it was not found at $SHOPIFY_DEV_PATH."
+  fi
+}
+
+if [ -d $SHOPIFY_DEV_PATH ]; then
+  copy_generated_docs_to_shopify_dev
+else
+  # We could be in the monorepo and need to go up several more directories to find shopify-dev
+  SHOPIFY_DEV_PATH="../../../../../../shopify-dev"
+  copy_generated_docs_to_shopify_dev
 fi
+

packages/ui-extensions/docs/surfaces/checkout/reference/apis/attributes.doc.ts

@@ -5,6 +5,7 @@ import {
   CHECKOUT_API_PROPERTIES_DESCRIPTION,
   getLinksByTag,
   getHookExample,
+  getExample,
 } from '../helper.docs';
 
 const data: ReferenceEntityTemplateSchema = {
@@ -42,7 +43,11 @@ const data: ReferenceEntityTemplateSchema = {
       type: 'UseAttributeValuesGeneratedType',
     },
   ],
-  defaultExample: getHookExample('attribute-values'),
+  defaultExample: getExample('attribute-values', ['jsx', 'js']),
+  examples: {
+    description: '',
+    examples: [getExample('attributes/attribute-change', ['jsx', 'js'])],
+  },
   related: getLinksByTag('apis'),
 };
 

packages/ui-extensions/docs/surfaces/checkout/reference/apis/buyer-journey.doc.ts

@@ -38,6 +38,7 @@ const data: ReferenceEntityTemplateSchema = {
         Installs a function for intercepting and preventing progress on checkout.
         To block checkout progress, you must set the [block_progress](/docs/api/checkout-ui-extensions/configuration#block-progress) capability in your extension's configuration.
         If you do, then you're expected to inform the buyer why navigation was blocked, either by passing validation errors to the checkout UI or rendering the errors in your extension.
+        \`useBuyerJourneyIntercept()\` should be called at the top level of the extension, not within an embedded or child component, to avoid errors should the child component get destroyed.
       `,
       type: 'UseBuyerJourneyInterceptGeneratedType',
     },

packages/ui-extensions/docs/surfaces/checkout/reference/apis/localized-fields.doc.ts

@@ -0,0 +1,40 @@
+import type {ReferenceEntityTemplateSchema} from '@shopify/generate-docs';
+
+import {
+  getExample,
+  getLinksByTag,
+  STANDARD_API_PROPERTIES_DESCRIPTION,
+  REQUIRES_PROTECTED_CUSTOMER_DATA,
+} from '../helper.docs';
+
+const data: ReferenceEntityTemplateSchema = {
+  name: 'Localized Fields',
+  description: 'The API for interacting with localized fields.',
+  isVisualComponent: false,
+  requires: REQUIRES_PROTECTED_CUSTOMER_DATA,
+  category: 'APIs',
+  type: 'API',
+  definitions: [
+    {
+      title: 'StandardApi',
+      description: STANDARD_API_PROPERTIES_DESCRIPTION,
+      type: 'Docs_Standard_LocalizedFieldsApi',
+    },
+    {
+      title: 'useLocalizedFields',
+      description:
+        'Returns the current localized fields and re-renders your component if the values change.',
+      type: 'UseLocalizedFieldsGeneratedType',
+    },
+    {
+      title: 'useLocalizedField',
+      description:
+        'Returns the current localized fields and re-renders your component if the values change.',
+      type: 'UseLocalizedFieldGeneratedType',
+    },
+  ],
+  defaultExample: getExample('localized-fields/default', ['jsx', 'js']),
+  related: getLinksByTag('apis'),
+};
+
+export default data;

packages/ui-extensions/docs/surfaces/checkout/reference/apis/metafields.doc.ts

@@ -5,6 +5,7 @@ import {
   REQUIRES_PROTECTED_CUSTOMER_DATA,
   STANDARD_API_PROPERTIES_DESCRIPTION,
   CHECKOUT_API_PROPERTIES_DESCRIPTION,
+  getExample,
 } from '../helper.docs';
 
 const data: ReferenceEntityTemplateSchema = {
@@ -49,6 +50,7 @@ const data: ReferenceEntityTemplateSchema = {
       type: 'UseApplyMetafieldsChangeGeneratedType',
     },
   ],
+  defaultExample: getExample('metafields/default', ['jsx', 'js', 'toml']),
   related: getLinksByTag('apis'),
 };
 

packages/ui-extensions/docs/surfaces/checkout/reference/apis/order.doc.ts

@@ -7,10 +7,6 @@ import {
   ORDER_STATUS_API_PROPERTIES_DESCRIPTION,
 } from '../helper.docs';
 
-// added temporarily to keep a note that the order status api docs have been moved to customer accounts
-// can be removed from 2025-01 on
-interface OrderStatusApiEmpty {}
-
 const data: ReferenceEntityTemplateSchema = {
   name: 'Order',
   description:

packages/ui-extensions/docs/surfaces/checkout/reference/apis/payment-options.doc.ts

@@ -30,10 +30,10 @@ const data: ReferenceEntityTemplateSchema = {
     },
   ],
   related: getLinksByTag('apis'),
-  defaultExample: getHookExample('payments/use-selected-payment-options'),
+  defaultExample: getHookExample('payments/use-available-payment-options'),
   examples: {
     description: '',
-    examples: [getHookExample('payments/use-available-payment-options')],
+    examples: [getHookExample('payments/use-selected-payment-options')],
   },
 };
 

packages/ui-extensions/docs/surfaces/checkout/reference/examples/analytics-publish.example.ts

@@ -1,6 +1,7 @@
-import {extension} from '@shopify/ui-extensions-react/checkout';
 import {useEffect} from 'react';
 
+import {extension} from '@shopify/ui-extensions/checkout';
+
 export default extension(
   'purchase.checkout.block.render',
   (root, {analytics}) => {

packages/ui-extensions/docs/surfaces/checkout/reference/examples/attribute-values.example.ts

@@ -0,0 +1,42 @@
+import {
+  extension,
+  Text,
+} from '@shopify/ui-extensions/checkout';
+
+export default extension(
+  'purchase.checkout.block.render',
+  (root, {attributes}) => {
+    attributes.subscribe(() => {
+      renderUI();
+    });
+
+    function renderUI() {
+      const buyerSelectedFreeTShirt =
+        attributes.current?.find(
+          (attr) =>
+            attr.key ===
+            'buyerSelectedFreeTShirt',
+        )?.value;
+
+      const tshirtSize = attributes.current?.find(
+        (attr) => attr.key === 'tshirtSize',
+      )?.value;
+
+      if (
+        Boolean(buyerSelectedFreeTShirt) === true
+      ) {
+        root.replaceChildren(
+          root.createComponent(
+            Text,
+            undefined,
+            `You selected a free t-shirt, size: ${tshirtSize}`,
+          ),
+        );
+      } else {
+        root.replaceChildren();
+      }
+    }
+
+    renderUI();
+  },
+);