@shopify/ui-extensions 2025.10.0-rc.3 → 2025.10.0-rc.31

package/src/surfaces/checkout/extension-targets.ts

@@ -662,6 +662,14 @@ export interface RenderExtensionTargets {
     OrderConfirmationApi & StandardApi<'purchase.thank-you.chat.render'>,
     AllowedComponents<'Chat'>
   >;
+  /**
+   * A static extension target that is rendered on top of the **Thank you page** as a dismissable announcement.
+   */
+  'purchase.thank-you.announcement.render': RenderExtension<
+    OrderConfirmationApi &
+      StandardApi<'purchase.thank-you.announcement.render'>,
+    AnyComponent
+  >;
 }
 
 export interface RunnableExtensionTargets {

package/src/surfaces/checkout/preact/attributes.ts

@@ -14,7 +14,7 @@ import {useSubscription} from './subscription';
  */
 export function useAttributes<
   Target extends RenderExtensionTarget = RenderExtensionTarget,
->(): Attribute[] | undefined {
+>(): Attribute[] {
   return useSubscription(useApi<Target>().attributes);
 }
 
@@ -28,7 +28,7 @@ export function useAttributeValues<
 >(keys: string[]): (string | undefined)[] {
   const attributes = useAttributes<Target>();
 
-  if (!attributes?.length) {
+  if (!attributes.length) {
     return [];
   }
 

package/src/surfaces/checkout/preact/subscription.ts

@@ -1,5 +1,6 @@
 import {useEffect, useState} from 'preact/hooks';
-import type {StatefulRemoteSubscribable} from '@remote-ui/async-subscription';
+
+import type {StatefulRemoteSubscribable} from '../../../shared';
 
 type Subscriber<T> = Parameters<StatefulRemoteSubscribable<T>['subscribe']>[0];
 

package/src/surfaces/checkout/preact/tests/delivery-group-target.test.ts

@@ -4,7 +4,7 @@ import type {
   ShippingOption,
 } from '@shopify/ui-extensions/checkout';
 
-// eslint-disable-next-line import/no-deprecated
+// eslint-disable-next-line import-x/no-deprecated
 import {useDeliveryGroupTarget} from '../delivery-group-target';
 
 import {mount, createMockStatefulRemoteSubscribable} from './mount';
@@ -61,7 +61,7 @@ describe.skip('useDeliveryGroupTarget', () => {
     const target: ExtensionTarget =
       'purchase.checkout.shipping-option-list.render-before';
 
-    // eslint-disable-next-line import/no-deprecated
+    // eslint-disable-next-line import-x/no-deprecated
     const {value} = mount.hook(() => useDeliveryGroupTarget(), {
       extensionApi: {
         extension: {target},

package/src/surfaces/checkout/shared.ts

@@ -1,35 +1,72 @@
 /**
  * The list of supported components.
- * As of April 15th, 2025, this is a subset of the components that will be available in the 2025-07 stable release.
+ * As of April 15th, 2025, this is a subset of the components that will be available in the 2025-10 stable release.
+ */
+export const SUPPORTED_COMPONENTS = [
+  'Abbreviation',
+  'Badge',
+  'Banner',
+  'Box',
+  'Button',
+  'Checkbox',
+  'Clickable',
+  'ClipboardItem',
+  'Details',
+  'Divider',
+  'DropZone',
+  'EmailField',
+  'Form',
+  'Grid',
+  'GridItem',
+  'Heading',
+  'Icon',
+  'Image',
+  'Link',
+  'ListItem',
+  'Map',
+  'MapMarker',
+  'Modal',
+  'NumberField',
+  'Option',
+  'OrderedList',
+  'Paragraph',
+  'PaymentIcon',
+  'PhoneField',
+  'Popover',
+  'ProductThumbnail',
+  'Progress',
+  'QRCode',
+  'ScrollBox',
+  'Section',
+  'Select',
+  'Sheet',
+  'SkeletonParagraph',
+  'Spinner',
+  'Stack',
+  'Summary',
+  'Switch',
+  'Text',
+  'TextArea',
+  'TextField',
+  'Time',
+  'UnorderedList',
+  'UrlField',
+] as const;
+
+/**
+ * Note: Chat is not supported in the 2025-07 release candidate, but it is tied to a target, and we don't want to remove the target documentation.
+ * Once Chat is supported, you can remove this note.
+ * @private
+ */
+export type PrivateComponent = 'Chat';
+
+/**
+ * The list of supported components.
+ * As of April 15th, 2025, this is a subset of the components that will be available in the 2025-10 stable release.
  */
 export type AnyComponent =
-  | 'Abbreviation'
-  | 'Banner'
-  | 'Box'
-  | 'Button'
-  /**
-   * Note: Chat is not supported in the 2025-07 release candidate, but it is tied to a target, and we don't want to remove the target documentation.
-   * Once Chat is supported, you can remove this note.
-   * @private
-   */
-  | 'Chat'
-  | 'ClipboardItem'
-  | 'DropZone'
-  | 'Form'
-  | 'Heading'
-  | 'Icon'
-  | 'Image'
-  | 'Link'
-  | 'ListItem'
-  | 'OrderedList'
-  | 'Paragraph'
-  | 'PaymentIcon'
-  | 'Progress'
-  | 'Spinner'
-  | 'Stack'
-  | 'Text'
-  | 'Time'
-  | 'UnorderedList';
+  | (typeof SUPPORTED_COMPONENTS)[number]
+  | PrivateComponent;
 
 export type AllowedComponents<Allowed extends AnyComponent> = Allowed;
 export type AnyComponentExcept<Except extends AnyComponent> = Exclude<

package/src/surfaces/checkout.ts

@@ -31,6 +31,7 @@ export type {
   AppMetafieldEntryTarget,
   AppMetafieldEntry,
   CartLine,
+  CartLineParentRelationship,
   PaymentOption,
   SelectedPaymentOption,
   CartDiscountCode,

package/src/surfaces/customer-account/api/cart-line/cart-line-item.ts

@@ -1,10 +1,9 @@
-import type {StatefulRemoteSubscribable} from '@remote-ui/async-subscription';
-
 import {CartLine} from '../order-status/order-status';
+import {ReadonlySignalLike} from '../shared';
 
 export interface CartLineItemApi {
   /**
    * The cart line the extension is attached to.
    */
-  target: StatefulRemoteSubscribable<CartLine>;
+  target: ReadonlySignalLike<CartLine>;
 }

package/src/surfaces/customer-account/api/docs.ts

@@ -1,7 +1,24 @@
 import {OrderStatusApi} from './order-status/order-status';
 import {StandardApi} from './standard-api/standard-api';
 import {CartLineItemApi} from './cart-line/cart-line-item';
-import {FullPageApi} from '../extension-targets';
+
+export type CallbackEvent<
+  TTagName extends keyof HTMLElementTagNameMap,
+  TEvent extends Event = Event,
+> = TEvent & {
+  currentTarget: HTMLElementTagNameMap[TTagName];
+};
+
+export type CallbackEventListener<
+  TTagName extends keyof HTMLElementTagNameMap,
+  TEvent extends Event = Event,
+> =
+  | (EventListener & {
+      (event: CallbackEvent<TTagName, TEvent>): void;
+    })
+  | null;
+
+declare const buttonTagName = 's-button';
 
 interface ButtonProps {
   /**
@@ -11,8 +28,30 @@ interface ButtonProps {
    * for users using assistive technologies.
    */
   accessibilityLabel?: string;
-  command?: '--auto' | '--toggle' | '--copy';
+  /**
+   * ID of a component that should respond to activations (e.g. clicks) on this component.
+   *
+   * See `command` for how to control the behavior of the target.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#commandfor
+   */
   commandFor?: string;
+  /**
+   * Sets the action the `commandFor` should take when this clickable is activated.
+   *
+   * See the documentation of particular components for the actions they support.
+   *
+   * - `--auto`: a default action for the target component.
+   * - `--show`: shows the target component.
+   * - `--hide`: hides the target component.
+   * - `--toggle`: toggles the target component.
+   * - `--copy`: copies the target ClipboardItem.
+   *
+   * @default '--auto'
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command
+   */
+  command?: '--auto' | '--show' | '--hide' | '--toggle' | '--copy';
   /**
    * Disables the button, disallowing any interaction.
    *
@@ -26,6 +65,9 @@ interface ButtonProps {
    * - If a `commandFor` is set, the `command` will be executed instead of the navigation.
    */
   href?: string;
+  /**
+   * A unique identifier for the element.
+   */
   id?: string;
   /**
    * Replaces content with a loading indicator.
@@ -72,8 +114,10 @@ interface ButtonProps {
   /**
    * Callback when the button is activated.
    * This will be called before the action indicated by `type`.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event
    */
-  onClick?(): void;
+  click?: ((event: CallbackEventListener<typeof buttonTagName>) => void) | null;
 }
 
 export interface Docs_OrderStatus_MetafieldsApi
@@ -139,6 +183,9 @@ export interface Docs_Standard_LocalizationApi
 export interface Docs_Standard_SessionTokenApi
   extends Pick<StandardApi<any>, 'sessionToken'> {}
 
+export interface Docs_Standard_AnalyticsApi
+  extends Pick<StandardApi<any>, 'analytics'> {}
+
 export interface Docs_Standard_SettingsApi
   extends Pick<StandardApi, 'settings'> {}
 
@@ -146,52 +193,60 @@ export interface Docs_Standard_StorageApi
   extends Pick<StandardApi<any>, 'storage'> {}
 
 export interface Docs_Standard_CustomerPrivacyApi
-  extends Pick<StandardApi<any>, 'customerPrivacy'> {}
+  extends Pick<
+    StandardApi<any>,
+    'customerPrivacy' | 'applyTrackingConsentChange'
+  > {}
 
-export interface Docs_Standard_UIApi extends Pick<StandardApi<any>, 'ui'> {}
+export interface Docs_Standard_ToastApi
+  extends Pick<StandardApi<any>, 'toast'> {}
 
 export interface Docs_Standard_QueryApi
   extends Pick<StandardApi<any>, 'query'> {}
 
 export interface Docs_StandardApi extends Omit<StandardApi<any>, 'router'> {}
 
-export interface Docs_FullPageApi extends FullPageApi {}
-
 export interface Docs_Page_Button_PrimaryAction
   extends Pick<
     ButtonProps,
-    'onClick' | 'loading' | 'disabled' | 'accessibilityLabel' | 'href'
+    | 'click'
+    | 'loading'
+    | 'disabled'
+    | 'accessibilityLabel'
+    | 'href'
+    | 'command'
+    | 'commandFor'
   > {}
 export interface Docs_Page_Button_SecondaryAction
   extends Pick<
     ButtonProps,
-    'onClick' | 'loading' | 'disabled' | 'accessibilityLabel' | 'href'
+    | 'click'
+    | 'loading'
+    | 'disabled'
+    | 'accessibilityLabel'
+    | 'href'
+    | 'command'
+    | 'commandFor'
   > {}
 
 export interface Docs_Page_Button_BreadcrumbAction
-  extends Pick<ButtonProps, 'onClick' | 'href'> {
+  extends Pick<ButtonProps, 'click' | 'href'> {
   /**
    * A label used for buyers using assistive technologies. Needed because `children` passed to this component will be discarded.
    */
   accessibilityLabel: ButtonProps['accessibilityLabel'];
 }
 
-export interface Docs_ResourceItem_Button_Action
-  extends Pick<
-    ButtonProps,
-    'onClick' | 'loading' | 'disabled' | 'accessibilityLabel' | 'href'
-  > {}
-
 export interface Docs_Menu_Button_Action
   extends Omit<
     ButtonProps,
-    'kind' | 'textDecoration' | 'inlineAlignment' | 'inlineSize' | 'size'
+    'variant' | 'textDecoration' | 'inlineAlignment' | 'inlineSize' | 'size'
   > {}
 
 export interface Docs_OrderActionMenu_Button
   extends Pick<
     ButtonProps,
-    'onClick' | 'loading' | 'disabled' | 'accessibilityLabel' | 'href'
+    'click' | 'loading' | 'disabled' | 'accessibilityLabel' | 'href' | 'tone'
   > {
   /**
    * Destination URL to link to.
@@ -201,14 +256,14 @@ export interface Docs_OrderActionMenu_Button
   href: ButtonProps['href'];
 }
 
-export interface Docs_CustomerAccountAction_Button_PrimaryAction
-  extends Pick<
-    ButtonProps,
-    'onClick' | 'loading' | 'disabled' | 'accessibilityLabel' | 'href'
-  > {}
-
-export interface Docs_CustomerAccountAction_Button_SecondaryAction
+export interface Docs_CustomerAccountAction_SlotButton
   extends Pick<
     ButtonProps,
-    'onClick' | 'loading' | 'disabled' | 'accessibilityLabel' | 'href'
+    | 'click'
+    | 'loading'
+    | 'disabled'
+    | 'accessibilityLabel'
+    | 'href'
+    | 'command'
+    | 'commandFor'
   > {}

package/src/surfaces/customer-account/api/order-status/order-status.ts

@@ -1,5 +1,3 @@
-import type {StatefulRemoteSubscribable} from '@remote-ui/async-subscription';
-
 import type {
   CurrencyCode,
   Country,
@@ -8,6 +6,7 @@ import type {
   Attribute,
   MailingAddress,
   Language,
+  ReadonlySignalLike,
 } from '../shared';
 import type {ExtensionTarget} from '../../extension-targets';
 import {Extension} from '../shared';
@@ -138,17 +137,17 @@ export interface OrderStatusLocalization {
   /**
    * The currency that the buyer sees for money amounts in the checkout.
    */
-  currency: StatefulRemoteSubscribable<Currency>;
+  currency: ReadonlySignalLike<Currency>;
 
   /**
    * The buyer’s time zone.
    */
-  timezone: StatefulRemoteSubscribable<Timezone>;
+  timezone: ReadonlySignalLike<Timezone>;
 
   /**
    * The language the buyer sees in the checkout.
    */
-  language: StatefulRemoteSubscribable<Language>;
+  language: ReadonlySignalLike<Language>;
 
   /**
    * This is the buyer's language, as supported by the extension.
@@ -161,7 +160,7 @@ export interface OrderStatusLocalization {
    * translations at all, this value is the default locale for your
    * extension (that is, the one matching your .default.json file).
    */
-  extensionLanguage: StatefulRemoteSubscribable<Language>;
+  extensionLanguage: ReadonlySignalLike<Language>;
 
   /**
    * The country context of the checkout. This value carries over from the
@@ -169,7 +168,7 @@ export interface OrderStatusLocalization {
    * experience. It will update if the buyer changes the country of their
    * shipping address. The value is undefined if unknown.
    */
-  country: StatefulRemoteSubscribable<Country | undefined>;
+  country: ReadonlySignalLike<Country | undefined>;
 
   /**
    * The [market](https://shopify.dev/docs/apps/markets) context of the
@@ -178,21 +177,16 @@ export interface OrderStatusLocalization {
    * buyer changes the country of their shipping address. The value is undefined
    * if unknown.
    */
-  market: StatefulRemoteSubscribable<Market | undefined>;
+  market: ReadonlySignalLike<Market | undefined>;
 }
 
 export type AuthenticationState = 'fully_authenticated' | 'pre_authenticated';
 
 export interface OrderStatusApi<Target extends ExtensionTarget> {
-  /**
-   * Methods for interacting with [Web Pixels](https://shopify.dev/docs/apps/marketing), such as emitting an event.
-   */
-  analytics: Analytics;
-
   /**
    * Gift Cards that have been applied to the order.
    */
-  appliedGiftCards: StatefulRemoteSubscribable<AppliedGiftCard[]>;
+  appliedGiftCards: ReadonlySignalLike<AppliedGiftCard[]>;
 
   /**
    * The metafields requested in the
@@ -202,12 +196,12 @@ export interface OrderStatusApi<Target extends ExtensionTarget> {
    *
    * {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
    */
-  appMetafields: StatefulRemoteSubscribable<AppMetafieldEntry[]>;
+  appMetafields: ReadonlySignalLike<AppMetafieldEntry[]>;
 
   /**
    * Custom attributes left by the customer to the merchant, either in their cart or during checkout.
    */
-  attributes: StatefulRemoteSubscribable<Attribute[] | undefined>;
+  attributes: ReadonlySignalLike<Attribute[] | undefined>;
 
   /**
    * Information about the buyer that is interacting with the order.
@@ -219,7 +213,7 @@ export interface OrderStatusApi<Target extends ExtensionTarget> {
   /**
    * Settings applied to the buyer's checkout.
    */
-  checkoutSettings: StatefulRemoteSubscribable<CheckoutSettings>;
+  checkoutSettings: ReadonlySignalLike<CheckoutSettings>;
 
   /**
    * Details on the costs of the purchase for the buyer.
@@ -229,12 +223,12 @@ export interface OrderStatusApi<Target extends ExtensionTarget> {
   /**
    * A list of discount codes applied to the purchase.
    */
-  discountCodes: StatefulRemoteSubscribable<CartDiscountCode[]>;
+  discountCodes: ReadonlySignalLike<CartDiscountCode[]>;
 
   /**
    * Discounts that have been applied to the entire cart.
    */
-  discountAllocations: StatefulRemoteSubscribable<CartDiscountAllocation[]>;
+  discountAllocations: ReadonlySignalLike<CartDiscountAllocation[]>;
 
   /**
    * Meta information about the extension.
@@ -257,7 +251,7 @@ export interface OrderStatusApi<Target extends ExtensionTarget> {
   /**
    * A list of lines containing information about the items the customer intends to purchase.
    */
-  lines: StatefulRemoteSubscribable<CartLine[]>;
+  lines: ReadonlySignalLike<CartLine[]>;
 
   /**
    * Details about the location, language, and currency of the buyer. For utilities to easily
@@ -287,17 +281,17 @@ export interface OrderStatusApi<Target extends ExtensionTarget> {
    * Once the order is created, you can query these metafields using the
    * [GraphQL Admin API](https://shopify.dev/docs/admin-api/graphql/reference/orders/order#metafield-2021-01)
    */
-  metafields: StatefulRemoteSubscribable<Metafield[]>;
+  metafields: ReadonlySignalLike<Metafield[]>;
 
   /**
    * A note left by the customer to the merchant, either in their cart or during checkout.
    */
-  note: StatefulRemoteSubscribable<string | undefined>;
+  note: ReadonlySignalLike<string | undefined>;
 
   /**
    * Information about the order that was placed.
    */
-  order: StatefulRemoteSubscribable<Order | undefined>;
+  order: ReadonlySignalLike<Order | undefined>;
 
   /**
    * id that represents the checkout used to create the order.
@@ -305,21 +299,21 @@ export interface OrderStatusApi<Target extends ExtensionTarget> {
    * 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).
    */
-  checkoutToken: StatefulRemoteSubscribable<CheckoutToken | undefined>;
+  checkoutToken: ReadonlySignalLike<CheckoutToken | undefined>;
 
   /**
    * The buyer shipping address used for the order.
    *
    * {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
    */
-  shippingAddress?: StatefulRemoteSubscribable<MailingAddress | undefined>;
+  shippingAddress?: ReadonlySignalLike<MailingAddress | undefined>;
 
   /**
    * The buyer billing address used for the order.
    *
    * {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
    */
-  billingAddress?: StatefulRemoteSubscribable<MailingAddress | undefined>;
+  billingAddress?: ReadonlySignalLike<MailingAddress | undefined>;
 
   /** Shop where the purchase took place. */
   shop: Shop;
@@ -339,7 +333,7 @@ export interface OrderStatusApi<Target extends ExtensionTarget> {
   /**
    * The authentication state of Order status page.
    */
-  authenticationState: StatefulRemoteSubscribable<AuthenticationState>;
+  authenticationState: ReadonlySignalLike<AuthenticationState>;
 }
 
 export interface OrderStatusBuyerIdentity {
@@ -349,7 +343,7 @@ export interface OrderStatusBuyerIdentity {
    *
    * {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
    */
-  customer: StatefulRemoteSubscribable<OrderStatusCustomer | undefined>;
+  customer: ReadonlySignalLike<OrderStatusCustomer | undefined>;
 
   /**
    * The email address of the buyer that is interacting with the cart.
@@ -357,7 +351,7 @@ export interface OrderStatusBuyerIdentity {
    *
    * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
    */
-  email: StatefulRemoteSubscribable<string | undefined>;
+  email: ReadonlySignalLike<string | undefined>;
 
   /**
    * The phone number of the buyer that is interacting with the cart.
@@ -365,7 +359,7 @@ export interface OrderStatusBuyerIdentity {
    *
    * {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
    */
-  phone: StatefulRemoteSubscribable<string | undefined>;
+  phone: ReadonlySignalLike<string | undefined>;
 
   /**
    * Provides details of the company and the company location that the business customer is purchasing on behalf of.
@@ -374,7 +368,7 @@ export interface OrderStatusBuyerIdentity {
    *
    * {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
    */
-  purchasingCompany: StatefulRemoteSubscribable<
+  purchasingCompany: ReadonlySignalLike<
     OrderStatusPurchasingCompany | undefined
   >;
 }
@@ -485,28 +479,28 @@ export interface CartCost {
    * A `Money` value representing the subtotal value of the items in the cart at the current
    * step of checkout.
    */
-  subtotalAmount: StatefulRemoteSubscribable<Money>;
+  subtotalAmount: ReadonlySignalLike<Money>;
 
   /**
    * 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.
    */
-  totalShippingAmount: StatefulRemoteSubscribable<Money | undefined>;
+  totalShippingAmount: ReadonlySignalLike<Money | undefined>;
 
   /**
    * 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.
    */
-  totalTaxAmount: StatefulRemoteSubscribable<Money | undefined>;
+  totalTaxAmount: ReadonlySignalLike<Money | undefined>;
 
   /**
    * 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.
    */
-  totalAmount: StatefulRemoteSubscribable<Money>;
+  totalAmount: ReadonlySignalLike<Money>;
 }
 
 export interface CartLine {
@@ -952,13 +946,6 @@ export interface StoreCreditAccount {
   balance: Money;
 }
 
-export interface Analytics {
-  /**
-   * Publish method to emit analytics events to [Web Pixels](https://shopify.dev/docs/apps/marketing).
-   */
-  publish(name: string, data: {[key: string]: unknown}): Promise<boolean>;
-}
-
 /**
  * Represents the delivery information and options available for one or
  * more cart lines.