2024-10 gen docs v1

package.json

@@ -40,7 +40,7 @@
     "@shopify/babel-preset": "^24.1.0",
     "@shopify/browserslist-config": "^3.0.0",
     "@shopify/eslint-plugin": "^42.0.0",
-    "@shopify/generate-docs": "0.16.4",
+    "@shopify/generate-docs": "1.0.0",
     "@shopify/loom": "^1.0.0",
     "@shopify/loom-cli": "^1.0.0",
     "@shopify/loom-plugin-build-library": "^1.0.0",
@@ -54,4 +54,4 @@
     "typescript": "^4.9.0"
   },
   "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"
-}
+}

packages/ui-extensions-react/src/surfaces/checkout/hooks/api.ts

@@ -16,6 +16,8 @@ import {ExtensionApiContext} from '../context';
  * which contains a basic set of properties about the checkout.
  *
  * For a full list of the API available to each extension target, see the [ExtensionTargets type](https://shopify.dev/docs/api/checkout-ui-extensions/apis/extensiontargets).
+ *
+ * @publicDocs
  */
 export function useApi<
   Target extends RenderExtensionTarget = RenderExtensionTarget,
@@ -43,6 +45,8 @@ export function useApi<
  * > Caution: This is deprecated, use `useApi` instead.
  *
  * @deprecated This is deprecated, use `useApi` instead.
+ *
+ * @publicDocs
  */
 export function useExtensionApi<
   Target extends RenderExtensionTarget = RenderExtensionTarget,

packages/ui-extensions-react/src/surfaces/checkout/hooks/app-metafields.ts

@@ -23,6 +23,8 @@ type AppMetafieldFilterKeys = keyof AppMetafieldFilters;
 /**
  * Returns the metafields configured with `shopify.extension.toml`.
  * @arg {AppMetafieldFilters} - filter the list of returned metafields
+ *
+ * @publicDocs
  */
 export function useAppMetafields<
   Target extends RenderExtensionTarget = RenderExtensionTarget,

packages/ui-extensions-react/src/surfaces/checkout/hooks/attributes.ts

@@ -12,6 +12,8 @@ import {useSubscription} from './subscription';
 
 /**
  * Returns the proposed `attributes` applied to the checkout.
+ *
+ * @publicDocs
  */
 export function useAttributes<
   Target extends RenderExtensionTarget = RenderExtensionTarget,
@@ -23,6 +25,8 @@ export function useAttributes<
  * Returns the values for the specified `attributes` applied to the checkout.
  *
  * @param keys - An array of attribute keys.
+ *
+ * @publicDocs
  */
 export function useAttributeValues<
   Target extends RenderExtensionTarget = RenderExtensionTarget,
@@ -41,6 +45,8 @@ export function useAttributeValues<
 
 /**
  * Returns a function to mutate the `attributes` property of the checkout.
+ *
+ * @publicDocs
  */
 export function useApplyAttributeChange<
   Target extends RenderExtensionTarget = RenderExtensionTarget,

packages/ui-extensions-react/src/surfaces/checkout/hooks/billing-address.ts

@@ -10,6 +10,8 @@ import {useSubscription} from './subscription';
 
 /**
  * Returns the proposed `billingAddress` applied to the checkout.
+ *
+ * @publicDocs
  */
 export function useBillingAddress<
   Target extends RenderExtensionTarget = RenderExtensionTarget,

packages/ui-extensions-react/src/surfaces/checkout/hooks/buyer-identity.ts

@@ -13,6 +13,8 @@ import {useSubscription} from './subscription';
  * Returns the current `Customer`.
  *
  * The value is `undefined` if the buyer isn't a known customer for this shop or if they haven't logged in yet.
+ *
+ * @publicDocs
  */
 export function useCustomer<
   Target extends RenderExtensionTarget = RenderExtensionTarget,
@@ -31,6 +33,8 @@ export function useCustomer<
 /**
  * Returns the email address of the buyer that is interacting with the cart.
  * The value is `undefined` if the app does not have access to customer data.
+ *
+ * @publicDocs
  */
 export function useEmail<
   Target extends RenderExtensionTarget = RenderExtensionTarget,
@@ -49,6 +53,8 @@ export function useEmail<
 /**
  * Returns the phone number of the buyer that is interacting with the cart.
  * The value is `undefined` if the app does not have access to customer data.
+ *
+ * @publicDocs
  */
 export function usePhone<
   Target extends RenderExtensionTarget = RenderExtensionTarget,
@@ -70,6 +76,8 @@ export function usePhone<
  * identify both the company and its corresponding location to which the business customer belongs.
  *
  * The value is `undefined` if a business customer isn't logged in. This function throws an error if the app doesn't have access to customer data.
+ *
+ * @publicDocs
  */
 export function usePurchasingCompany<
   Target extends RenderExtensionTarget = RenderExtensionTarget,

packages/ui-extensions-react/src/surfaces/checkout/hooks/buyer-journey.ts

@@ -13,6 +13,8 @@ import {useSubscription} from './subscription';
 
 /**
  * Returns the `buyerJourney` details on buyer progression in checkout.
+ *
+ * @publicDocs
  */
 export function useBuyerJourney<
   Target extends RenderExtensionTarget = RenderExtensionTarget,
@@ -33,6 +35,8 @@ export function useBuyerJourney<
  * Returns true if the buyer completed submitting their order.
  *
  * For example, when viewing the **Order status** page after submitting payment, the buyer will have completed their order.
+ *
+ * @publicDocs
  */
 export function useBuyerJourneyCompleted<
   Target extends RenderExtensionTarget = RenderExtensionTarget,
@@ -54,6 +58,8 @@ export function useBuyerJourneyCompleted<
  *
  * 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.
+ *
+ * @publicDocs
  */
 export function useBuyerJourneyIntercept<
   Target extends RenderExtensionTarget = RenderExtensionTarget,
@@ -80,6 +86,8 @@ export function useBuyerJourneyIntercept<
 
 /**
  * Returns all possible steps a buyer can take to complete the checkout. These steps may vary depending on the type of checkout or the shop's configuration.
+ *
+ * @publicDocs
  */
 export function useBuyerJourneySteps<
   Target extends RenderExtensionTarget = RenderExtensionTarget,
@@ -95,6 +103,8 @@ export function useBuyerJourneySteps<
 
 /**
  * Returns the buyer journey step that the buyer is currently on.
+ *
+ * @publicDocs
  */
 export function useBuyerJourneyActiveStep<
   Target extends RenderExtensionTarget = RenderExtensionTarget,

packages/ui-extensions-react/src/surfaces/checkout/hooks/capabilities.ts

@@ -5,13 +5,17 @@ import {useApi} from './api';
 
 /**
  * Returns a list of an extension's granted capabilities.
+ *
+ * @publicDocs
  */
 export function useExtensionCapabilities(): Capability[] {
   return useSubscription(useApi().extension.capabilities);
 }
 
 /**
  * Returns whether or not a given capability of an extension is granted.
+ *
+ * @publicDocs
  */
 export function useExtensionCapability(capability: Capability): boolean {
   return useExtensionCapabilities().includes(capability);

packages/ui-extensions-react/src/surfaces/checkout/hooks/cart-line-target.ts

@@ -12,6 +12,8 @@ import {useSubscription} from './subscription';
  * - `purchase.checkout.cart-line-item.render-after`
  * - `purchase.thank-you.cart-line-item.render-after`
  * - 'customer-account.order-status.cart-line-item.render-after'
+ *
+ * @publicDocs
  */
 export function useCartLineTarget(): CartLine {
   const api = useApi<

packages/ui-extensions-react/src/surfaces/checkout/hooks/cart-lines.ts

@@ -13,6 +13,8 @@ import {useSubscription} from './subscription';
 /**
  * Returns the current line items for the checkout, and automatically re-renders
  * your component if line items are added, removed, or updated.
+ *
+ * @publicDocs
  */
 export function useCartLines<
   Target extends RenderExtensionTarget = RenderExtensionTarget,
@@ -24,6 +26,8 @@ export function useCartLines<
 
 /**
  * Returns a function to mutate the `lines` property of checkout.
+ *
+ * @publicDocs
  */
 export function useApplyCartLinesChange<
   Target extends RenderExtensionTarget = RenderExtensionTarget,

packages/ui-extensions-react/src/surfaces/checkout/hooks/checkout-settings.ts

@@ -8,6 +8,8 @@ import {useSubscription} from './subscription';
 
 /**
  * Returns the `checkoutSettings` applied to the checkout.
+ *
+ * @publicDocs
  */
 export function useCheckoutSettings<
   Target extends RenderExtensionTarget = RenderExtensionTarget,

packages/ui-extensions-react/src/surfaces/checkout/hooks/checkout-token.ts

@@ -11,6 +11,8 @@ import {useSubscription} from './subscription';
  *
  * Matches the `token` field in the [WebPixel checkout payload](https://shopify.dev/docs/api/pixels/customer-events#checkout)
  * and the `checkout_token` field in the [Admin REST API Order resource](https://shopify.dev/docs/api/admin-rest/unstable/resources/order#resource-object).
+ *
+ * @publicDocs
  */
 export function useCheckoutToken<
   Target extends RenderExtensionTarget = RenderExtensionTarget,

packages/ui-extensions-react/src/surfaces/checkout/hooks/cost.ts

@@ -9,6 +9,8 @@ import {useSubscription} from './subscription';
 /**
  * A `Money` value representing the subtotal value of the items in the cart at the current
  * step of checkout.
+ *
+ * @publicDocs
  */
 export function useSubtotalAmount<
   Target extends RenderExtensionTarget = RenderExtensionTarget,
@@ -20,6 +22,8 @@ export function useSubtotalAmount<
  * A `Money` value representing the total shipping a buyer can expect to pay at the current
  * step of checkout. This value includes shipping discounts. Returns undefined if shipping
  * has not been negotiated yet, such as on the information step.
+ *
+ * @publicDocs
  */
 export function useTotalShippingAmount<
   Target extends RenderExtensionTarget = RenderExtensionTarget,
@@ -31,6 +35,8 @@ export function useTotalShippingAmount<
  * A `Money` value representing the total tax a buyer can expect to pay at the current
  * step of checkout or the total tax included in product and shipping prices. Returns
  * undefined if taxes are unavailable.
+ *
+ * @publicDocs
  */
 export function useTotalTaxAmount<
   Target extends RenderExtensionTarget = RenderExtensionTarget,
@@ -42,6 +48,8 @@ export function useTotalTaxAmount<
  * Returns a `Money` value representing the minimum a buyer can expect to pay at the current
  * step of checkout. This value excludes amounts yet to be negotiated. For example,
  * the information step might not have delivery costs calculated.
+ *
+ * @publicDocs
  */
 export function useTotalAmount<
   Target extends RenderExtensionTarget = RenderExtensionTarget,

packages/ui-extensions-react/src/surfaces/checkout/hooks/country.ts

@@ -9,6 +9,8 @@ import {useSubscription} from './subscription';
 /**
  * Returns the country of the checkout, and automatically re-renders
  * your component if the country changes.
+ *
+ * @publicDocs
  */
 export function useLocalizationCountry<
   Target extends RenderExtensionTarget = RenderExtensionTarget,

packages/ui-extensions-react/src/surfaces/checkout/hooks/currency.ts

@@ -9,6 +9,8 @@ import {useSubscription} from './subscription';
 /**
  * Returns the currency of the checkout, and automatically re-renders
  * your component if the currency changes.
+ *
+ * @publicDocs
  */
 export function useCurrency<
   Target extends RenderExtensionTarget = RenderExtensionTarget,

packages/ui-extensions-react/src/surfaces/checkout/hooks/customer-privacy.ts

@@ -9,6 +9,8 @@ import {useSubscription} from './subscription';
 /**
  * Returns the current customer privacy settings and metadata and
  * re-renders your component if the customer privacy settings change.
+ *
+ * @publicDocs
  */
 export function useCustomerPrivacy<
   Target extends RenderExtensionTarget = RenderExtensionTarget,

packages/ui-extensions-react/src/surfaces/checkout/hooks/delivery-group-list-target.ts

@@ -8,6 +8,8 @@ import {useSubscription} from './subscription';
  * extension targets:
  * - purchase.checkout.shipping-option-list.render-before
  * - purchase.checkout.shipping-option-list.render-after
+ *
+ * @publicDocs
  */
 export function useDeliveryGroupListTarget(): DeliveryGroupList | undefined {
   const api = useApi<

packages/ui-extensions-react/src/surfaces/checkout/hooks/delivery-group-target.ts

@@ -12,6 +12,8 @@ import {useSubscription} from './subscription';
  * > Caution: Deprecated as of version `2024-07`, use `useDeliveryGroupListTarget()` instead.
  *
  * @deprecated Deprecated as of version `2024-07`, use `useDeliveryGroupListTarget()` instead.
+ *
+ * @publicDocs
  */
 export function useDeliveryGroupTarget(): DeliveryGroup | undefined {
   const api = useApi<

packages/ui-extensions-react/src/surfaces/checkout/hooks/delivery-group.ts

@@ -13,6 +13,8 @@ import {useSubscription} from './subscription';
 /**
  * Returns the full expanded details of a delivery group and automatically re-renders
  * your component when that delivery group changes.
+ *
+ * @publicDocs
  */
 export function useDeliveryGroup<
   ID extends RenderExtensionTarget = RenderExtensionTarget,

packages/ui-extensions-react/src/surfaces/checkout/hooks/delivery-groups.ts

@@ -11,6 +11,8 @@ import {useSubscription} from './subscription';
 /**
  * Returns the current delivery groups for the checkout, and automatically re-renders
  * your component when delivery address or delivery option selection changes.
+ *
+ * @publicDocs
  */
 export function useDeliveryGroups<
   Target extends RenderExtensionTarget = RenderExtensionTarget,

packages/ui-extensions-react/src/surfaces/checkout/hooks/delivery-selection-groups.ts

@@ -8,6 +8,8 @@ import {useSubscription} from './subscription';
  * extension targets:
  * - purchase.checkout.shipping-option-list.render-before
  * - purchase.checkout.shipping-option-list.render-after
+ *
+ * @publicDocs
  */
 export function useDeliverySelectionGroups():
   | DeliverySelectionGroup[]

packages/ui-extensions-react/src/surfaces/checkout/hooks/discounts.ts

@@ -14,6 +14,8 @@ import {useSubscription} from './subscription';
 /**
  * Returns the current discount codes applied to the cart, and automatically re-renders
  * your component if discount codes are added or removed.
+ *
+ * @publicDocs
  */
 export function useDiscountCodes<
   Target extends RenderExtensionTarget = RenderExtensionTarget,
@@ -26,6 +28,8 @@ export function useDiscountCodes<
 /**
  * Returns the current discount allocations applied to the cart, and automatically re-renders
  * your component if discount allocations changed.
+ *
+ * @publicDocs
  */
 export function useDiscountAllocations<
   Target extends RenderExtensionTarget = RenderExtensionTarget,
@@ -40,6 +44,8 @@ export function useDiscountAllocations<
  *
  * > Caution:
  * > See [security considerations](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#network-access) if your extension retrieves discount codes through a network call.
+ *
+ * @publicDocs
  */
 export function useApplyDiscountCodeChange<
   Target extends RenderExtensionTarget = RenderExtensionTarget,

packages/ui-extensions-react/src/surfaces/checkout/hooks/extension-editor.ts

@@ -4,6 +4,8 @@ import {useApi} from './api';
 
 /**
  * Returns information about the editor where the extension is being rendered.
+ *
+ * @publicDocs
  */
 export function useExtensionEditor(): Editor | undefined {
   return useApi().extension.editor;

packages/ui-extensions-react/src/surfaces/checkout/hooks/extension-language.ts

@@ -8,6 +8,8 @@ import {useSubscription} from './subscription';
 
 /**
  * Returns the buyer's language, as supported by the extension.
+ *
+ * @publicDocs
  */
 export function useExtensionLanguage<
   Target extends RenderExtensionTarget = RenderExtensionTarget,

packages/ui-extensions-react/src/surfaces/checkout/hooks/extension.ts

@@ -4,6 +4,8 @@ import {useApi} from './api';
 
 /**
  * Returns the metadata about the extension.
+ *
+ * @publicDocs
  */
 export function useExtension(): Extension {
   return useApi().extension as Extension;
@@ -13,6 +15,8 @@ export function useExtension(): Extension {
  * Returns the metadata about the extension.
  * > Caution: This is deprecated, use `useExtension()` instead.
  * @deprecated Use `useExtension()` instead.
+ *
+ * @publicDocs
  */
 export function useExtensionData(): Extension {
   return useExtension();