@shopify/ui-extensions 2025.10.0-rc.4 → 2025.10.0-rc.41

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/api.ts

@@ -14,6 +14,10 @@ import {CheckoutUIExtensionError} from './errors';
  * 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).
+ *
+ * > Note:
+ * > As of version 2025-10, you no longer need this hook. The full API object is accessible via
+ * > the global `shopify` object.
  */
 export function useApi<
   Target extends RenderExtensionTarget = RenderExtensionTarget,

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,7 +1,8 @@
 import {useEffect, useState} from 'preact/hooks';
-import type {StatefulRemoteSubscribable} from '@remote-ui/async-subscription';
 
-type Subscriber<T> = Parameters<StatefulRemoteSubscribable<T>['subscribe']>[0];
+import type {SubscribableSignalLike} from '../shared';
+
+type Subscriber<T> = Parameters<SubscribableSignalLike<T>['subscribe']>[0];
 
 /**
  * Subscribes to the special wrapper type that all "changeable" values in the
@@ -9,13 +10,14 @@ type Subscriber<T> = Parameters<StatefulRemoteSubscribable<T>['subscribe']>[0];
  * and subscribes to update the value when changes occur in the checkout.
  *
  * > Note:
- * > You generally shouldn't need to use this directly, as there are dedicated hooks
- * > for accessing the current value of each individual resource in the checkout.
+ * > As of version 2025-10, you no longer need this hook. When you access `.value`
+ * > (instead of `.current`) on subscribable properties, Preact will automatically
+ * > re-render as `.value` changes.
  */
 export function useSubscription<Value>(
-  subscription: StatefulRemoteSubscribable<Value>,
+  subscription: SubscribableSignalLike<Value>,
 ): Value {
-  const [, setValue] = useState(subscription.current);
+  const [, setValue] = useState(subscription.value);
 
   useEffect(() => {
     let didUnsubscribe = false;
@@ -33,7 +35,7 @@ export function useSubscription<Value>(
     // Because we're subscribing in a passive effect,
     // it's possible for an update to occur between render and the effect handler.
     // Check for this and schedule an update if work has occurred.
-    checkForUpdates(subscription.current);
+    checkForUpdates(subscription.value);
 
     return () => {
       didUnsubscribe = true;
@@ -41,5 +43,5 @@ export function useSubscription<Value>(
     };
   }, [subscription]);
 
-  return subscription.current;
+  return subscription.value;
 }

package/src/surfaces/checkout/preact/tests/buyer-identity.test.tsx

@@ -1,11 +1,10 @@
-import type {StatefulRemoteSubscribable} from '@remote-ui/async-subscription';
+import type {SubscribableSignalLike} from '../../shared';
 import {faker} from '@faker-js/faker';
 
 import {ScopeNotGrantedError} from '../../errors';
 import {useCustomer, useEmail, usePhone} from '../buyer-identity';
 
 import {mount} from './mount';
-
 function createMockCustomer(customer = {}) {
   const firstName = faker.person.firstName();
   const lastName = faker.person.lastName();
@@ -41,7 +40,7 @@ function createUsePhoneContext(phone?: string) {
   return createMockHookContext(undefined, phone, undefined);
 }
 
-function createMockSuscribable<T>(data: T): StatefulRemoteSubscribable<T> {
+function createMockSuscribable<T>(data: T): SubscribableSignalLike<T> {
   return {
     current: data,
     value: data,

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/preact/tests/mount.tsx

@@ -1,5 +1,5 @@
 import {createRender} from '@quilted/react-testing';
-import type {StatefulRemoteSubscribable} from '@remote-ui/async-subscription';
+import type {SubscribableSignalLike} from '../../shared';
 
 import type {
   ApiForExtension,
@@ -39,8 +39,8 @@ interface Options {
 
 export function createMockStatefulRemoteSubscribable<T>(
   value: T,
-): StatefulRemoteSubscribable<T> {
-  const subscribable: StatefulRemoteSubscribable<T> = {
+): SubscribableSignalLike<T> {
+  const subscribable: SubscribableSignalLike<T> = {
     get current() {
       return value;
     },

package/src/surfaces/checkout/shared.ts

@@ -1,41 +1,109 @@
+import type {ReadonlySignalLike} from '../../shared';
+
 /**
  * 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 October 1st, 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',
+  'Choice',
+  'ChoiceList',
+  'Clickable',
+  'ClipboardItem',
+  'DateField',
+  'DatePicker',
+  'Details',
+  'Divider',
+  'DropZone',
+  'EmailField',
+  'Form',
+  'Grid',
+  'GridItem',
+  'Heading',
+  'Icon',
+  'Image',
+  'Link',
+  'ListItem',
+  'Map',
+  'MapMarker',
+  'Modal',
+  'MoneyField',
+  'NumberField',
+  'Option',
+  'OrderedList',
+  'Paragraph',
+  'PasswordField',
+  'PaymentIcon',
+  'PhoneField',
+  'Popover',
+  'ProductThumbnail',
+  'PressButton',
+  'Progress',
+  'QueryContainer',
+  'QRCode',
+  'ScrollBox',
+  'Section',
+  'Select',
+  'Sheet',
+  'SkeletonParagraph',
+  'Spinner',
+  'Stack',
+  'Summary',
+  'Switch',
+  'Text',
+  'TextArea',
+  'TextField',
+  'Time',
+  'Tooltip',
+  'UnorderedList',
+  'UrlField',
+] as const;
+
+/**
+ * Note: Chat is not supported in the 2025-10 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 October 1st, 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'
-  | 'QRCode'
-  | 'Section'
-  | 'Spinner'
-  | 'Stack'
-  | 'Text'
-  | 'TextField'
-  | 'Time'
-  | 'UnorderedList';
+  | (typeof SUPPORTED_COMPONENTS)[number]
+  | PrivateComponent;
 
 export type AllowedComponents<Allowed extends AnyComponent> = Allowed;
 export type AnyComponentExcept<Except extends AnyComponent> = Exclude<
   AnyComponent,
   Except
 >;
+
+/**
+ * Represents a read-only value managed on the main thread that an extension can subscribe to.
+ *
+ * Example: Checkout uses this to manage the state of an object and
+ * communicate state changes to extensions running in a sandboxed web worker.
+ *
+ * This interface is compatible with [Preact's ReadonlySignal](https://github.com/preactjs/signals/blob/a023a132a81bd4ba4a0bebb8cbbeffbd8c8bbafc/packages/core/src/index.ts#L700-L709).
+ *
+ * Some fields are deprecated but still supported for backwards compatibility.
+ * In version 2025-10, [`StatefulRemoteSubscribable`](https://github.com/Shopify/remote-dom/blob/03929aa8418a89d41d294005f219837582718df8/packages/async-subscription/src/types.ts#L17) was replaced with `ReadonlySignalLike`. Checkout will remove the old fields some time in the future.
+ *
+ */
+export interface SubscribableSignalLike<T> extends ReadonlySignalLike<T> {
+  /**
+   * @deprecated Use `.value` instead.
+   */
+  readonly current: T;
+  /**
+   * @deprecated No longer needed. Use Preact Signal management instead.
+   */
+  destroy(): Promise<void>;
+}

package/src/surfaces/checkout.ts

@@ -31,6 +31,7 @@ export type {
   AppMetafieldEntryTarget,
   AppMetafieldEntry,
   CartLine,
+  CartLineParentRelationship,
   PaymentOption,
   SelectedPaymentOption,
   CartDiscountCode,
@@ -85,6 +86,8 @@ export type {
   ShippingAddress,
 } from './checkout/api/shared';
 
+export type {SubscribableSignalLike} from './checkout/shared';
+
 export type {
   RedeemableAttribute,
   RedeemableChange,
@@ -182,8 +185,8 @@ export type {
 } from './checkout/api/payment/payment-option-item';
 
 export * from './checkout/extension-targets';
-
 export * from './checkout/shared';
+
 export {
   Style,
   isConditionalStyle,

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 {SubscribableSignalLike} from '../shared';
 
 export interface CartLineItemApi {
   /**
    * The cart line the extension is attached to.
    */
-  target: StatefulRemoteSubscribable<CartLine>;
+  target: SubscribableSignalLike<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'
   > {}