@shopify/ui-extensions 2025.10.0-rc.40 → 2025.10.0-rc.42

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

@@ -1,8 +1,8 @@
 import {useEffect, useState} from 'preact/hooks';
 
-import type {StatefulRemoteSubscribable} from '../../../shared';
+import type {SubscribableSignalLike} from '../shared';
 
-type Subscriber<T> = Parameters<StatefulRemoteSubscribable<T>['subscribe']>[0];
+type Subscriber<T> = Parameters<SubscribableSignalLike<T>['subscribe']>[0];
 
 /**
  * Subscribes to the special wrapper type that all "changeable" values in the
@@ -10,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;
@@ -34,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;
@@ -42,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/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,6 +1,8 @@
+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-10 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',
@@ -9,8 +11,12 @@ export const SUPPORTED_COMPONENTS = [
   'Box',
   'Button',
   'Checkbox',
+  'Choice',
+  'ChoiceList',
   'Clickable',
   'ClipboardItem',
+  'DateField',
+  'DatePicker',
   'Details',
   'Divider',
   'DropZone',
@@ -26,15 +32,19 @@ export const SUPPORTED_COMPONENTS = [
   'Map',
   'MapMarker',
   'Modal',
+  'MoneyField',
   'NumberField',
   'Option',
   'OrderedList',
   'Paragraph',
+  'PasswordField',
   'PaymentIcon',
   'PhoneField',
   'Popover',
   'ProductThumbnail',
+  'PressButton',
   'Progress',
+  'QueryContainer',
   'QRCode',
   'ScrollBox',
   'Section',
@@ -49,12 +59,13 @@ export const SUPPORTED_COMPONENTS = [
   'TextArea',
   'TextField',
   'Time',
+  'Tooltip',
   '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.
+ * 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
  */
@@ -62,7 +73,7 @@ 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.
+ * 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 =
   | (typeof SUPPORTED_COMPONENTS)[number]
@@ -73,3 +84,26 @@ 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

@@ -86,6 +86,8 @@ export type {
   ShippingAddress,
 } from './checkout/api/shared';
 
+export type {SubscribableSignalLike} from './checkout/shared';
+
 export type {
   RedeemableAttribute,
   RedeemableChange,
@@ -183,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/shared.ts

@@ -9,9 +9,10 @@ import type {
   CountryCode,
   GraphQLError,
   StorefrontApiVersion,
-  SubscribableSignalLike,
 } from '../../../shared';
 
+import type {SubscribableSignalLike} from '../../checkout/shared';
+
 export {
   ApiVersion,
   Capability,

package/src/surfaces/customer-account/components/Avatar/examples/basic-Avatar.example.html

@@ -0,0 +1,4 @@
+<s-avatar
+  alt="John Doe"
+  initials="JD"
+></s-avatar>

package/src/surfaces/customer-account/components/Avatar.d.ts

@@ -12,13 +12,13 @@ export type CallbackEventListener<
 export interface AvatarElementProps extends IdProps {
   /**
    * Initials to display in the avatar.
+   *
+   * Initials will be rendered as a fallback if `src` is not provided, fails to load or does not load quickly.
    */
   initials?: string;
 
   /**
    * The URL or path to the image.
-   *
-   * Initials will be rendered as a fallback if `src` is not provided, fails to load or does not load quickly.
    */
   src?: string;
 

package/src/surfaces/customer-account/components/ButtonGroup/examples/basic-ButtonGroup.example.html

@@ -0,0 +1,11 @@
+<s-button-group>
+  <s-button slot="primary-action" variant="primary">
+    Pay now
+  </s-button>
+  <s-button slot="secondary-actions" variant="secondary">
+    Edit order
+  </s-button>
+  <s-button slot="secondary-actions" variant="secondary">
+    Cancel order
+  </s-button>
+</s-button-group>

package/src/surfaces/customer-account/components/ButtonGroup.d.ts

@@ -9,11 +9,11 @@ export interface ButtonGroupProps extends IdProps {
 
 export interface ButtonGroupElementSlots {
   /**
-   * The primary action to perform, provided as a button type element.
+   * The primary action for the group. Accepts a single [Button](/docs/api/checkout-ui-extensions/polaris-web-components/actions/button) element.
    */
   'primary-action'?: HTMLElement;
   /**
-   * The secondary actions to perform, provided as button type elements.
+   * The secondary actions for the group. Accepts multiple [Button](/docs/api/checkout-ui-extensions/polaris-web-components/actions/button) elements.
    */
   'secondary-actions'?: HTMLElement;
 }

package/src/surfaces/customer-account/components/CustomerAccountAction/examples/basic-CustomerAccountAction.example.html

@@ -0,0 +1,15 @@
+<s-customer-account-action heading="My order action">
+  Modal content
+  <s-button 
+    slot="primary-action" 
+    onClick={() => console.log('pressed primary action')}
+  >
+    Primary
+  </s-button>
+  <s-button 
+    slot="secondary-actions" 
+    onClick={() => console.log('pressed secondary action')}
+  >
+    Secondary
+  </s-button>
+</s-customer-account-action>

package/src/surfaces/customer-account/components/CustomerAccountAction.d.ts

@@ -2,18 +2,18 @@ import {BaseElementPropsWithChildren, IdProps} from './shared';
 
 export interface CustomerAccountActionProps extends IdProps {
   /**
-   * Sets the heading of the Action container.
+   * Sets the heading of the action container.
    */
   heading: string;
 }
 
 export interface CustomerAccountActionElementSlots {
   /**
-   * The primary action to perform, provided as a button type element.
+   * The primary action for the page. Accepts a single Button element with restricted properties (see below).
    */
   'primary-action'?: HTMLElement;
   /**
-   * The secondary actions to perform, provided as button type elements.
+   * The secondary actions for the page. Accepts multiple Button elements with restricted properties (see below).
    */
   'secondary-actions'?: HTMLElement;
 }

package/src/surfaces/customer-account/components/ImageGroup/examples/basic-ImageGroup.example.html

@@ -0,0 +1,18 @@
+<s-image-group>
+  <s-image 
+    src="https://cdn.shopify.com/YOUR_IMAGE_HERE"
+    alt="Product image"
+  ></s-image>
+  <s-image 
+    src="https://cdn.shopify.com/YOUR_IMAGE_HERE"
+    alt="Product image"
+  ></s-image>
+  <s-image 
+    src="https://cdn.shopify.com/YOUR_IMAGE_HERE"
+    alt="Product image"
+  ></s-image>
+  <s-image 
+    src="https://cdn.shopify.com/YOUR_IMAGE_HERE"
+    alt="Product image"
+  ></s-image>
+</s-image-group>

package/src/surfaces/customer-account/components/Menu/examples/basic-Menu.example.html

@@ -0,0 +1,14 @@
+<>
+  <s-button commandFor="order-actions-menu">
+    Manage
+  </s-button>
+
+  <s-menu
+    id="order-actions-menu"
+    accessibilityLabel="List of order actions"
+  >
+    <s-button>Submit problem</s-button>
+    <s-button>Request return</s-button>
+    <s-button tone="critical">Cancel order</s-button>
+  </s-menu>
+</>

package/src/surfaces/customer-account/components/Page/examples/basic-Page.example.html

@@ -0,0 +1,19 @@
+<s-page
+  heading="Order #1411"
+  subheading="Confirmed Oct 5"
+>
+  <s-button slot="primary-action">
+    Buy again
+  </s-button>
+  <s-button slot="secondary-actions">
+    Edit order
+  </s-button>
+  <s-button slot="secondary-actions">
+    Cancel order
+  </s-button>
+  <s-button
+    slot="breadcrumb-actions"
+    accessibilityLabel="Back to orders"
+  ></s-button>
+  Content
+</s-page>

package/src/surfaces/customer-account/components/Page.d.ts

@@ -14,15 +14,15 @@ export interface PageProps extends IdProps {
 
 export interface PageElementSlots {
   /**
-   * The breadcrumb actions to perform, provided as button type elements.
+   * The breadcrumb actions for the page. Accepts a single Button element with restricted properties (see below).
    */
   'breadcrumb-actions'?: HTMLElement;
   /**
-   * The primary action to perform, provided as a button type element.
+   * The primary action for the page. Accepts a single Button element with restricted properties (see below).
    */
   'primary-action'?: HTMLElement;
   /**
-   * The secondary actions to perform, provided as button type elements.
+   * The secondary actions for the page. Accepts multiple Button elements with restricted properties (see below).
    */
   'secondary-actions'?: HTMLElement;
 }

package/src/surfaces/customer-account/components/Section/examples/basic-Section.example.html

@@ -0,0 +1,12 @@
+<s-section heading="Rewards">
+  <s-button slot="primary-action" variant="primary">
+    Redeem
+  </s-button>
+  <s-button slot="secondary-actions" variant="secondary">
+    My rewards
+  </s-button>
+  <s-paragraph>
+    Earn 10 points for every $1 spent. Redeem 100 points for $10 off your
+    next purchase.
+  </s-paragraph>
+</s-section>

package/src/surfaces/customer-account/components/Section.d.ts

@@ -18,11 +18,11 @@ export interface SectionProps extends IdProps {
 
 export interface SectionElementSlots {
   /**
-   * The primary action to perform, provided as a button type element.
+   * The primary action for the section. Accepts a single [Button](/docs/api/checkout-ui-extensions/polaris-web-components/actions/button) element.
    */
   'primary-action'?: HTMLElement;
   /**
-   * The secondary actions to perform, provided as button type elements.
+   * The secondary actions for the section. Accepts multiple [Button](/docs/api/checkout-ui-extensions/polaris-web-components/actions/button) elements.
    */
   'secondary-actions'?: HTMLElement;
 }

package/src/surfaces/point-of-sale/api/navigation-api/navigation-api.ts

@@ -12,7 +12,7 @@ export interface NavigationHistoryEntry {
   /** Returns the key of the history entry. This is a unique, UA-generated value that represents the history entry's slot in the entries list rather than the entry itself. */
   key: string;
   /**
-   * Returns the URL of this history entry.
+   * Returns the lowercased URL of this history entry.
    */
   url: string | null;
   /**
@@ -35,7 +35,7 @@ export interface Navigation {
   /**
    * The navigate() method navigates to a specific URL, updating any provided state in the history entries list.
    */
-  navigate: NavigateFunction;
+  navigate: (url: string, options?: NavigationNavigateOptions) => void;
   /**
    * The currentEntry read-only property of the Navigation interface returns a NavigationHistoryEntry object representing the location the user is currently navigated to right now.
    */
@@ -53,11 +53,3 @@ export interface Navigation {
     cb: (event: NavigationCurrentEntryChangeEvent) => void,
   ): void;
 }
-
-export interface NavigateFunction {
-  /**
-   * Navigates to a specific URL, updating any provided state in the history entries list.
-   * @param url The destination URL to navigate to.
-   */
-  (url: string, options?: NavigationNavigateOptions): void;
-}

package/src/surfaces/point-of-sale/components/Badge/examples/default.html

@@ -1,5 +1,5 @@
-<s-badge tone="neutral">Neutral</s-badge>
-<s-badge tone="success">Success</s-badge>
-<s-badge tone="info">Highlight</s-badge>
-<s-badge tone="warning">Warning</s-badge>
-<s-badge tone="critical">Critical</s-badge>
+<s-badge tone="neutral">Paid</s-badge>
+<s-badge tone="success">Active</s-badge>
+<s-badge tone="info">Draft</s-badge>
+<s-badge tone="warning">On hold</s-badge>
+<s-badge tone="critical">Action required</s-badge>

package/src/surfaces/point-of-sale/components/Banner.d.ts

@@ -33,12 +33,21 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement>
 }
 
 declare const tagName = 's-banner';
-export interface BannerJSXProps
-  extends Pick<BannerProps, 'heading' | 'hidden' | 'tone' | 'id'> {
+export interface BannerJSXProps extends Pick<BannerProps, 'heading' | 'id'> {
+  /**
+   * Determines whether the banner is hidden.
+   */
+  hidden?: BannerProps['hidden'];
+  /**
+   * Sets the tone of the Banner, based on the intention of the information being conveyed.
+   */
   tone?: Extract<
     BannerProps['tone'],
     'success' | 'info' | 'warning' | 'critical'
   >;
+  /**
+   * The action taken when the Banner is pressed.
+   */
   primaryAction?: ComponentChild;
   children?: ComponentChildren;
 }

package/src/surfaces/point-of-sale/components/Button.d.ts

@@ -38,14 +38,39 @@ export interface CallbackEvent<T extends keyof HTMLElementTagNameMap> {
 
 declare const tagName = 's-button';
 export interface ButtonJSXProps
-  extends Pick<
-    ButtonProps,
-    'disabled' | 'command' | 'commandFor' | 'loading' | 'tone' | 'variant'
-  > {
+  extends Pick<ButtonProps, 'disabled' | 'command' | 'commandFor' | 'loading'> {
+  /**
+   * 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.
+   *
+   * @default '--auto'
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command
+   */
+  command?: Extract<
+    ButtonProps['command'],
+    '--auto' | '--show' | '--hide' | '--toggle'
+  >;
+  /**
+   * Sets the tone of the Button, based on the intention of the information being conveyed.
+   *
+   * @default 'auto'
+   */
   tone?: Extract<
     ButtonProps['tone'],
     'auto' | 'critical' | 'neutral' | 'warning' | 'caution'
   >;
+  /**
+   * Changes the visual appearance of the Button.
+   *
+   * @default 'auto' - the variant is automatically determined by the Button's context
+   */
   variant?: Extract<ButtonProps['variant'], 'primary' | 'secondary'>;
   onClick?: (event: CallbackEvent<typeof tagName>) => void;
   children?: ComponentChildren;

package/{build/ts/surfaces/point-of-sale/components/Navigator.d.ts → src/surfaces/point-of-sale/components/Divider.d.ts}

@@ -8,7 +8,7 @@
 /* eslint-disable import-x/namespace */
 // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment
 /// <reference lib="DOM" />
-import type {Key, Ref} from './components-shared.d.ts';
+import type {DividerProps, Key, Ref} from './components-shared.d.ts';
 
 export type ComponentChildren = any;
 /**
@@ -27,24 +27,21 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement>
   children?: ComponentChildren;
 }
 
-declare const tagName = 's-navigator';
-export interface NavigatorJSXProps {
-  initialScreenName?: string;
-  children?: React.ReactNode;
-}
+declare const tagName = 's-divider';
+export interface DividerJSXProps extends Pick<DividerProps, 'direction'> {}
 declare global {
   interface HTMLElementTagNameMap {
-    [tagName]: NavigatorJSXProps;
+    [tagName]: DividerJSXProps;
   }
 }
 declare module 'preact' {
   namespace createElement.JSX {
     interface IntrinsicElements {
-      [tagName]: NavigatorJSXProps &
-        BaseElementPropsWithChildren<NavigatorJSXProps>;
+      [tagName]: DividerJSXProps &
+        BaseElementPropsWithChildren<DividerJSXProps>;
     }
   }
 }
 
 export {tagName};
-export type {NavigatorJSXProps};
+export type {DividerJSXProps};

package/src/surfaces/point-of-sale/components/Modal.d.ts

@@ -14,7 +14,6 @@ import type {
   Ref,
   ComponentChild,
 } from './components-shared.d.ts';
-import {ReactNode} from 'react';
 
 export type ComponentChildren = any;
 /**
@@ -48,7 +47,7 @@ export interface ModalJSXProps extends Pick<ModalProps, 'id' | 'heading'> {
   secondaryActions?: ComponentChild;
   onHide?: (event: CallbackEvent<typeof tagName>) => void | null;
   onShow?: (event: CallbackEvent<typeof tagName>) => void | null;
-  children?: ReactNode;
+  children?: ComponentChildren;
 }
 declare global {
   interface HTMLElementTagNameMap {

package/src/surfaces/point-of-sale/components/Page.d.ts

@@ -35,12 +35,12 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement>
 declare const tagName = 's-page';
 export type PickedProps = Pick<
   PageProps,
-  'heading' | 'subheading' | 'secondaryActions'
+  'heading' | 'subheading' | 'secondaryActions' | 'aside'
 >;
 export interface PageJSXProps extends PickedProps {
   children?: ComponentChildren;
   secondaryActions?: ComponentChild;
-  primaryAction?: ComponentChild;
+  aside?: ComponentChild;
 }
 declare global {
   interface HTMLElementTagNameMap {
@@ -50,9 +50,9 @@ declare global {
 declare module 'preact' {
   namespace createElement.JSX {
     interface IntrinsicElements {
-      [tagName]: Omit<PageJSXProps, 'primaryAction' | 'secondaryActions'> &
+      [tagName]: Omit<PageJSXProps, 'secondaryActions' | 'aside'> &
         BaseElementPropsWithChildren<
-          Omit<PageJSXProps, 'primaryAction' | 'secondaryActions'>
+          Omit<PageJSXProps, 'secondaryActions' | 'aside'>
         >;
     }
   }