@shopify/ui-extensions 2025.10.0-rc.8 → 2025.10.0

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

@@ -1,5 +1,4 @@
 import type {ExtensionTarget} from '../extension-targets';
-import type {StatefulRemoteSubscribable} from '@remote-ui/async-subscription';
 
 import type {
   ApiVersion,
@@ -12,6 +11,8 @@ import type {
   StorefrontApiVersion,
 } from '../../../shared';
 
+import type {SubscribableSignalLike} from '../../checkout/shared';
+
 export {
   ApiVersion,
   Capability,
@@ -21,6 +22,7 @@ export {
   CountryCode,
   GraphQLError,
   StorefrontApiVersion,
+  SubscribableSignalLike,
 };
 
 /**
@@ -162,7 +164,7 @@ export interface Extension<Target extends ExtensionTarget = ExtensionTarget> {
    *
    * * [`block_progress`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#block-progress): the extension can block a buyer's progress and the merchant has allowed this blocking behavior.
    */
-  capabilities: StatefulRemoteSubscribable<Capability[]>;
+  capabilities: SubscribableSignalLike<Capability[]>;
 
   /**
    * Information about the editor where the extension is being rendered.
@@ -182,7 +184,7 @@ export interface Extension<Target extends ExtensionTarget = ExtensionTarget> {
    * from where it was rendered. The extension continues running so that
    * your extension is immediately available to render if the buyer navigates back.
    */
-  rendered: StatefulRemoteSubscribable<boolean>;
+  rendered: SubscribableSignalLike<boolean>;
 
   /**
    * The URL to the script that started the extension target.
@@ -345,11 +347,11 @@ export interface AuthenticatedAccount {
    * Provides the company info of the authenticated business customer.
    * If the customer is not authenticated or is not a business customer, this value is `undefined`.
    */
-  purchasingCompany: StatefulRemoteSubscribable<PurchasingCompany | undefined>;
+  purchasingCompany: SubscribableSignalLike<PurchasingCompany | undefined>;
   /**
    * Provides the customer information of the authenticated customer.
    */
-  customer: StatefulRemoteSubscribable<Customer | undefined>;
+  customer: SubscribableSignalLike<Customer | undefined>;
 }
 
 /**
@@ -392,41 +394,6 @@ export interface CompanyLocation {
   id: string;
 }
 
-export interface Ui {
-  /**
-   * The Toast API displays a non-disruptive message that displays at the bottom
-   * of the interface to provide quick, at-a-glance feedback on the outcome
-   * of an action.
-   *
-   * How to use:
-   *
-   * - Use toasts to confirm successful actions.
-   *
-   * - Aim for two words.
-   *
-   * - Use noun + past tense verb format. For example, \`Changes saved\`.
-   *
-   * For errors, or information that needs to persist on the page, use a [banner](/docs/api/checkout-ui-extensions/unstable/components/feedback/banner) component.
-   */
-  toast: {
-    show(content: string): void;
-  };
-  /**
-   * Refresh data so the surrounding information on the page is updated. The `content` string will appear in a toast message after refresh, to confirm the action was successful.
-   *
-   * To request access to this API:
-   *
-   * 1. Go to your partner dashboard and click **Apps**.
-   *
-   * 2. Select the app you need to request access for.
-   *
-   * 3. Click **API access**.
-   *
-   * 4. Under **Access force data refresh**, click **Request access**.
-   */
-  forceDataRefresh(content: string): Promise<void>;
-}
-
 export interface SessionToken {
   /**
    * Requests a session token that hasn't expired. You should call this method every
@@ -437,6 +404,50 @@ export interface SessionToken {
   get(): Promise<string>;
 }
 
+export interface Analytics {
+  /**
+   * Publish method to emit analytics events to [Web Pixels](https://shopify.dev/docs/apps/marketing).
+   */
+  publish(name: string, data: Record<string, unknown>): Promise<boolean>;
+
+  /**
+   * A method for capturing details about a visitor on the online store.
+   */
+  visitor(data: {email?: string; phone?: string}): Promise<VisitorResult>;
+}
+/**
+ * Represents a visitor result.
+ */
+export type VisitorResult = VisitorSuccess | VisitorError;
+
+/**
+ * Represents a successful visitor result.
+ */
+export interface VisitorSuccess {
+  /**
+   * Indicates that the visitor information was validated and submitted.
+   */
+  type: 'success';
+}
+
+/**
+ * Represents an unsuccessful visitor result.
+ */
+export interface VisitorError {
+  /**
+   * Indicates that the visitor information is invalid and wasn't submitted.
+   * Examples are using the wrong data type or missing a required property.
+   */
+  type: 'error';
+
+  /**
+   * A message that explains the error. This message is useful for debugging.
+   * It's **not** localized, and therefore should not be presented directly
+   * to the buyer.
+   */
+  message: string;
+}
+
 export interface AllowedProcessing {
   /**
    * Can collect customer analytics about how the shop was used and interactions made on the shop.
@@ -608,3 +619,10 @@ export interface TrackingConsentChangeResultError {
    */
   message: string;
 }
+
+export interface ToastApiResult {
+  hide: () => void;
+}
+export interface ToastApi {
+  show: (content: string) => Promise<ToastApiResult>;
+}

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

@@ -7,14 +7,15 @@ import {
   AuthenticatedAccount,
   GraphQLError,
   StorefrontApiVersion,
-  Ui,
   SessionToken,
+  Analytics,
   CustomerPrivacy,
   ApplyTrackingConsentChangeType,
+  ToastApi,
+  SubscribableSignalLike,
 } from '../shared';
 
 import type {ExtensionTarget} from '../../extension-targets';
-import {StatefulRemoteSubscribable} from '@remote-ui/async-subscription';
 
 /**
  * The merchant-defined setting values for the extension.
@@ -79,6 +80,13 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
    */
   sessionToken: SessionToken;
 
+  /**
+   * Methods for interacting with [Web Pixels](https://shopify.dev/docs/apps/marketing), such as emitting an event.
+   *
+   * > Note: Requires to [connect a third-party domain](https://help.shopify.com/en/manual/domains/add-a-domain/connecting-domains/connect-domain-customer-account) to Shopify for your customer account pages.
+   */
+  analytics: Analytics;
+
   /**
    * The settings matching the settings definition written in the
    * [`shopify.ui.extension.toml`](https://shopify.dev/docs/api/customer-account-ui-extensions/configuration) file.
@@ -88,14 +96,24 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
    * > Note: When an extension is being installed in the editor, the settings will be empty until
    * a merchant sets a value. In that case, this object will be updated in real time as a merchant fills in the settings.
    */
-  settings: StatefulRemoteSubscribable<ExtensionSettings>;
+  settings: SubscribableSignalLike<ExtensionSettings>;
 
   /**
-   * Methods to interact with the extension's UI.
+   * The Toast API displays a non-disruptive message that displays at the bottom
+   * of the interface to provide quick, at-a-glance feedback on the outcome
+   * of an action.
+   *
+   * How to use:
+   *
+   * - Use toasts to confirm successful actions.
+   *
+   * - Aim for two words.
+   *
+   * - Use noun + past tense verb format. For example, \`Changes saved\`.
+   *
+   * For errors, or information that needs to persist on the page, use a [banner](/docs/api/checkout-ui-extensions/unstable/components/feedback/banner) component.
    */
-  ui: Ui;
-
-  navigation: StandardExtensionNavigation;
+  toast: ToastApi;
 
   /**
    * Used to query the Storefront GraphQL API with a prefetched token.
@@ -110,7 +128,7 @@ export interface StandardApi<Target extends ExtensionTarget = ExtensionTarget> {
   /**
    * Customer privacy consent settings and a flag denoting if consent has previously been collected.
    */
-  customerPrivacy: StatefulRemoteSubscribable<CustomerPrivacy>;
+  customerPrivacy: SubscribableSignalLike<CustomerPrivacy>;
 
   /**
    * Allows setting and updating customer privacy consent settings and tracking consent metafields.
@@ -148,7 +166,7 @@ export interface Localization {
   /**
    * The language the buyer sees in the customer account hub.
    */
-  language: StatefulRemoteSubscribable<Language>;
+  language: SubscribableSignalLike<Language>;
 
   /**
    * This is the buyer's language, as supported by the extension.
@@ -161,26 +179,26 @@ export interface Localization {
    * 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: SubscribableSignalLike<Language>;
 
   /**
    * The country context of the buyer sees in the customer account.
    * It will update if the buyer changes the country in the customer account
    * If the country is unknown, then the value is undefined.
    */
-  country: StatefulRemoteSubscribable<Country | undefined>;
+  country: SubscribableSignalLike<Country | undefined>;
 }
 
 /**
  * An enumerated value representing the type of navigation.
  */
-export type NavigationType = 'push' | 'replace' | 'traverse';
+export type NavigationTypeString = 'push' | 'replace' | 'traverse';
 
-export interface NavigationOptions {
+export interface NavigationNavigateOptions {
   /**
    * Developer-defined information to be stored in the associated NavigationHistoryEntry once the navigation is complete, retrievable via getState().
    */
-  state?: Record<string, any>;
+  state?: unknown;
   /**
    * An enumerated value that sets the history behavior of this navigation.
    */
@@ -196,11 +214,15 @@ export interface NavigationHistoryEntry {
   /**
    * Returns the URL of this history entry.
    */
-  url: string;
+  url: string | null;
   /**
    * Returns a clone of the available state associated with this history entry.
    */
-  getState(): Record<string, any>;
+  getState(): unknown;
+}
+
+export interface NavigationUpdateCurrentEntryOptions {
+  state: unknown;
 }
 
 /**
@@ -210,21 +232,18 @@ export interface NavigationCurrentEntryChangeEvent {
   /**
    * Returns the type of the navigation that resulted in the change.
    */
-  navigationType: NavigationType;
+  navigationType?: NavigationTypeString;
   /**
    * Returns the NavigationHistoryEntry that was navigated from.
    */
   from: NavigationHistoryEntry;
 }
 
-export interface StandardExtensionNavigation {
+export interface Navigation {
   /**
    * The navigate() method navigates to a specific URL, updating any provided state in the history entries list.
    */
   navigate: NavigateFunction;
-}
-
-export interface FullExtensionNavigation extends StandardExtensionNavigation {
   /**
    * The currentEntry read-only property of the Navigation interface returns a NavigationHistoryEntry object representing the location the user is currently navigated to right now.
    */
@@ -232,7 +251,7 @@ export interface FullExtensionNavigation extends StandardExtensionNavigation {
   /**
    * The updateCurrentEntry() method of the Navigation interface updates the state of the currentEntry; used in cases where the state change will be independent of a navigation or reload.
    */
-  updateCurrentEntry(options: {state: Record<string, any>}): void;
+  updateCurrentEntry(options: NavigationUpdateCurrentEntryOptions): void;
   addEventListener(
     type: 'currententrychange',
     cb: (event: NavigationCurrentEntryChangeEvent) => void,
@@ -248,7 +267,7 @@ 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?: NavigationOptions): void;
+  (url: string, options?: NavigationNavigateOptions): void;
 }
 
 export type Version = string;

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

@@ -66,6 +66,7 @@ export type {
   Company,
   Customer,
   SessionToken,
+  Analytics,
   ApplyTrackingConsentChangeType,
   CustomerPrivacy,
   TrackingConsentChangeResult,
@@ -74,6 +75,10 @@ export type {
   TrackingConsentMetafieldChange,
   VisitorConsent,
   VisitorConsentChange,
+  VisitorResult,
+  VisitorSuccess,
+  VisitorError,
+  SubscribableSignalLike,
 } from './api/shared';
 
 export type {CartLineItemApi} from './api/cart-line/cart-line-item';
@@ -81,12 +86,11 @@ export type {CartLineItemApi} from './api/cart-line/cart-line-item';
 export type {
   Version,
   StandardApi,
-  FullExtensionNavigation,
-  StandardExtensionNavigation,
+  Navigation,
   NavigationCurrentEntryChangeEvent,
   NavigationHistoryEntry,
-  NavigationOptions,
-  NavigationType,
+  NavigationNavigateOptions,
+  NavigationTypeString,
   NavigateFunction,
   Localization,
   CompanyLocationApi,

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

@@ -0,0 +1,4 @@
+<s-avatar
+  alt="Evan White"
+  initials="EW"
+></s-avatar>

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

@@ -1,54 +1,80 @@
-import {BaseElementPropsWithChildren, Size} from './shared';
+import {BaseElementPropsWithChildren, IdProps, SizeKeyword} from './shared';
 
-interface GlobalProps {
-  /**
-   * A unique identifier for the element.
-   */
-  id?: string;
-}
+export type CallbackEventListener<
+  TTagName extends keyof HTMLElementTagNameMap,
+  TEvent extends Event = Event,
+> =
+  | (EventListener & {
+      (event: CallbackEvent<TTagName, TEvent>): void;
+    })
+  | null;
 
-export interface AvatarProps extends GlobalProps {
+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;
 
+  /**
+   * Size of the avatar.
+   *
+   * @default 'base'
+   */
+  size?: Extract<
+    SizeKeyword,
+    'small-200' | 'small' | 'base' | 'large' | 'large-200'
+  >;
+
+  /**
+   * An alternative text description that describe the image for the reader
+   * to understand what it is about or identify the user the avatar belongs to.
+   */
+  alt?: string;
+}
+
+export interface AvatarElementEvents {
   /**
    * Invoked when load of provided image completes successfully.
    *
    * @see https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onload
    */
-  onLoad?(): void;
+  onLoad?(event: Event): void;
 
   /**
    * Invoked on load error of provided image.
    *
    * @see https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onerror
    */
-  onError?(): void;
+  onError?(event: Event): void;
+}
+
+export interface AvatarElement
+  extends AvatarElementProps,
+    Omit<HTMLElement, 'id'> {
+  onload: AvatarElementEvents['onLoad'];
+  onerror: AvatarElementEvents['onError'];
+}
 
+export interface AvatarEvents {
   /**
-   * Size of the avatar.
-   *
-   * @default 'base'
+   * Callback when the image loads successfully.
    */
-  size?: Extract<Size, 'base' | 'large' | 'extraLarge' | 'fill'>;
+  load?: ((event: CallbackEventListener<typeof tagName>) => void) | null;
 
   /**
-   * An alternative text description that describe the image for the reader
-   * to understand what it is about or identify the user the avatar belongs to.
+   * Callback when the image fails to load.
    */
-  alt?: string;
+  error?: ((event: CallbackEventListener<typeof tagName>) => void) | null;
 }
 
-export interface AvatarElement extends AvatarProps, Omit<HTMLElement, 'id'> {}
+export type AvatarProps = AvatarElementProps & AvatarElementEvents;
 
 declare global {
   interface HTMLElementTagNameMap {

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

@@ -0,0 +1,39 @@
+import {BaseElementPropsWithChildren, IdProps} from './shared';
+
+export interface ButtonGroupProps extends IdProps {
+  /**
+   * Label for the button group that describes the content of the group for screen reader users to understand what's included.
+   */
+  accessibilityLabel?: string;
+}
+
+export interface ButtonGroupElementSlots {
+  /**
+   * 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 for the group. Accepts multiple [Button](/docs/api/checkout-ui-extensions/polaris-web-components/actions/button) elements.
+   */
+  'secondary-actions'?: HTMLElement;
+}
+
+export interface ButtonGroupElement
+  extends ButtonGroupProps,
+    Omit<HTMLElement, 'id'> {}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    ['s-button-group']: ButtonGroupElement;
+  }
+}
+
+declare module 'preact' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace createElement.JSX {
+    interface IntrinsicElements {
+      ['s-button-group']: BaseElementPropsWithChildren<ButtonGroupElement> &
+        ButtonGroupProps;
+    }
+  }
+}

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

@@ -0,0 +1,9 @@
+<s-customer-account-action heading="Action title">
+  Modal content
+  <s-button slot="primary-action">
+    Save
+  </s-button>
+  <s-button slot="secondary-actions">
+    Cancel
+  </s-button>
+</s-customer-account-action>

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

@@ -1,12 +1,23 @@
-import {BaseElementPropsWithChildren} from './shared';
+import {BaseElementPropsWithChildren, IdProps} from './shared';
 
-export interface CustomerAccountActionProps {
+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 for the page. Accepts a single Button element with restricted properties (see below).
+   */
+  'primary-action'?: HTMLElement;
+  /**
+   * The secondary actions for the page. Accepts multiple Button elements with restricted properties (see below).
+   */
+  'secondary-actions'?: HTMLElement;
+}
+
 export interface CustomerAccountActionElement
   extends HTMLElement,
     CustomerAccountActionProps {}

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/ImageGroup.d.ts

@@ -1,6 +1,6 @@
-import {BaseElementPropsWithChildren} from './shared';
+import {BaseElementPropsWithChildren, IdProps} from './shared';
 
-export interface ImageGroupProps {
+export interface ImageGroupProps extends IdProps {
   /**
    * Indicates the total number of items that could be displayed in the image group.
    * It is used to determine the remaining number to show when all the available image slots have been filled.

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/Menu.d.ts

@@ -0,0 +1,25 @@
+import {BaseElementPropsWithChildren, IdProps} from './shared';
+
+export interface MenuProps extends IdProps {
+  /**
+   * A label to describe the purpose of the menu that is announced by screen readers.
+   */
+  accessibilityLabel?: string;
+}
+
+export interface MenuElement extends MenuProps, Omit<HTMLElement, 'id'> {}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    ['s-menu']: MenuElement;
+  }
+}
+
+declare module 'preact' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace createElement.JSX {
+    interface IntrinsicElements {
+      ['s-menu']: BaseElementPropsWithChildren<MenuElement> & MenuProps;
+    }
+  }
+}

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

@@ -1,6 +1,6 @@
-import {BaseElementPropsWithChildren} from './shared';
+import {BaseElementPropsWithChildren, IdProps} from './shared';
 
-export interface PageProps {
+export interface PageProps extends IdProps {
   /**
    * The main page heading
    */
@@ -12,6 +12,21 @@ export interface PageProps {
   subheading?: string;
 }
 
+export interface PageElementSlots {
+  /**
+   * The breadcrumb actions for the page. Accepts a single Button element with restricted properties (see below).
+   */
+  'breadcrumb-actions'?: HTMLElement;
+  /**
+   * The primary action for the page. Accepts a single Button element with restricted properties (see below).
+   */
+  'primary-action'?: HTMLElement;
+  /**
+   * The secondary actions for the page. Accepts multiple Button elements with restricted properties (see below).
+   */
+  'secondary-actions'?: HTMLElement;
+}
+
 export interface PageElement extends HTMLElement, PageProps {}
 
 declare global {