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

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,
@@ -10,6 +9,7 @@ import type {
   CountryCode,
   GraphQLError,
   StorefrontApiVersion,
+  ReadonlySignalLike,
 } from '../../../shared';
 
 export {
@@ -21,6 +21,7 @@ export {
   CountryCode,
   GraphQLError,
   StorefrontApiVersion,
+  ReadonlySignalLike,
 };
 
 /**
@@ -162,7 +163,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: ReadonlySignalLike<Capability[]>;
 
   /**
    * Information about the editor where the extension is being rendered.
@@ -182,7 +183,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: ReadonlySignalLike<boolean>;
 
   /**
    * The URL to the script that started the extension target.
@@ -345,11 +346,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: ReadonlySignalLike<PurchasingCompany | undefined>;
   /**
    * Provides the customer information of the authenticated customer.
    */
-  customer: StatefulRemoteSubscribable<Customer | undefined>;
+  customer: ReadonlySignalLike<Customer | undefined>;
 }
 
 /**
@@ -393,30 +394,6 @@ export interface CompanyLocation {
 }
 
 export interface Ui {
-  /**
-   * An overlay is a contextual element on top of the main interface that provides additional information or functionality.
-   */
-  overlay: {
-    close(overlayId: string): void;
-  };
-  /**
-   * 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.
    *
@@ -443,6 +420,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.
@@ -614,3 +635,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

@@ -9,12 +9,14 @@ import {
   StorefrontApiVersion,
   Ui,
   SessionToken,
+  Analytics,
   CustomerPrivacy,
   ApplyTrackingConsentChangeType,
+  ToastApi,
+  ReadonlySignalLike,
 } 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 +81,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 +97,29 @@ 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: ReadonlySignalLike<ExtensionSettings>;
 
   /**
    * Methods to interact with the extension's UI.
    */
   ui: Ui;
 
-  navigation: StandardExtensionNavigation;
+  /**
+   * 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: ToastApi;
 
   /**
    * Used to query the Storefront GraphQL API with a prefetched token.
@@ -110,7 +134,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: ReadonlySignalLike<CustomerPrivacy>;
 
   /**
    * Allows setting and updating customer privacy consent settings and tracking consent metafields.
@@ -148,7 +172,7 @@ export interface Localization {
   /**
    * The language the buyer sees in the customer account hub.
    */
-  language: StatefulRemoteSubscribable<Language>;
+  language: ReadonlySignalLike<Language>;
 
   /**
    * This is the buyer's language, as supported by the extension.
@@ -161,26 +185,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: ReadonlySignalLike<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: ReadonlySignalLike<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 +220,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 +238,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 +257,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 +273,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,
+  ReadonlySignalLike,
 } 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-preact.example.tsx

@@ -0,0 +1,10 @@
+import '@shopify/ui-extensions/preact';
+import {render} from 'preact';
+
+export default async () => {
+  render(<Extension />, document.body);
+};
+
+function Extension() {
+  return <s-avatar initials="EW" alt="Evan White" size="base" />;
+}

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

@@ -0,0 +1,92 @@
+import {BaseElementPropsWithChildren, IdProps, SizeKeyword} from './shared';
+
+export type CallbackEventListener<
+  TTagName extends keyof HTMLElementTagNameMap,
+  TEvent extends Event = Event,
+> =
+  | (EventListener & {
+      (event: CallbackEvent<TTagName, TEvent>): void;
+    })
+  | null;
+
+export interface AvatarElementProps extends IdProps {
+  /**
+   * Initials to display in the avatar.
+   */
+  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?(event: Event): void;
+
+  /**
+   * Invoked on load error of provided image.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onerror
+   */
+  onError?(event: Event): void;
+}
+
+export interface AvatarElement
+  extends AvatarElementProps,
+    Omit<HTMLElement, 'id'> {
+  onload: AvatarElementEvents['onLoad'];
+  onerror: AvatarElementEvents['onError'];
+}
+
+export interface AvatarEvents {
+  /**
+   * Callback when the image loads successfully.
+   */
+  load?: ((event: CallbackEventListener<typeof tagName>) => void) | null;
+
+  /**
+   * Callback when the image fails to load.
+   */
+  error?: ((event: CallbackEventListener<typeof tagName>) => void) | null;
+}
+
+export type AvatarProps = AvatarElementProps & AvatarElementEvents;
+
+declare global {
+  interface HTMLElementTagNameMap {
+    ['s-avatar']: AvatarElement;
+  }
+}
+
+declare module 'preact' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace createElement.JSX {
+    interface IntrinsicElements {
+      ['s-avatar']: BaseElementPropsWithChildren<AvatarElement> & AvatarProps;
+    }
+  }
+}

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

@@ -0,0 +1,22 @@
+import '@shopify/ui-extensions/preact';
+import {render} from 'preact';
+
+export default async () => {
+  render(<Extension />, document.body);
+};
+
+function Extension() {
+  return (
+    <s-button-group accessibilityLabel="Order actions">
+      <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 to perform, provided as a button type element.
+   */
+  'primary-action'?: HTMLElement;
+  /**
+   * The secondary actions to perform, provided as button type 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-preact.example.tsx

@@ -1,15 +1,16 @@
+import '@shopify/ui-extensions/preact';
 import {render} from 'preact';
 
-export default function extension() {
-  render(<App />, document.body);
-}
+export default async () => {
+  render(<Extension />, document.body);
+};
 
-function App() {
+function Extension() {
   return (
-    <s-customer-account-action heading="Extension title">
+    <s-customer-account-action heading="Edit order">
       Extension content
-      <s-button slot="primaryAction" onClick={() => shopify.close()}>
-        Click to close
+      <s-button slot="primary-action" onClick={() => shopify.close()}>
+        Close
       </s-button>
     </s-customer-account-action>
   );

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

@@ -1,10 +1,23 @@
-export interface CustomerAccountActionProps {
+import {BaseElementPropsWithChildren, IdProps} from './shared';
+
+export interface CustomerAccountActionProps extends IdProps {
   /**
    * Sets the heading of the Action container.
    */
   heading: string;
 }
 
+export interface CustomerAccountActionElementSlots {
+  /**
+   * The primary action to perform, provided as a button type element.
+   */
+  'primary-action'?: HTMLElement;
+  /**
+   * The secondary actions to perform, provided as button type elements.
+   */
+  'secondary-actions'?: HTMLElement;
+}
+
 export interface CustomerAccountActionElement
   extends HTMLElement,
     CustomerAccountActionProps {}
@@ -16,14 +29,11 @@ declare global {
 }
 
 declare module 'preact' {
-  interface BaseProps {
-    children?: preact.ComponentChildren;
-    slot?: Lowercase<string>;
-  }
   // eslint-disable-next-line @typescript-eslint/no-namespace
   namespace createElement.JSX {
     interface IntrinsicElements {
-      ['s-customer-account-action']: BaseProps & CustomerAccountActionProps;
+      ['s-customer-account-action']: BaseElementPropsWithChildren<CustomerAccountActionElement> &
+        CustomerAccountActionProps;
     }
   }
 }

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

@@ -1,15 +1,17 @@
+import '@shopify/ui-extensions/preact';
 import {render} from 'preact';
 
-export default function extension() {
-  render(<App />, document.body);
-}
+export default async () => {
+  render(<Extension />, document.body);
+};
 
-function App() {
+function Extension() {
   return (
     <s-image-group>
       <s-image src="../assets/flower.jpg" />
       <s-image src="../assets/flower.jpg" />
       <s-image src="../assets/flower.jpg" />
+      <s-image src="../assets/flower.jpg" />
     </s-image-group>
   );
 }

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

@@ -1,4 +1,6 @@
-export interface ImageGroupProps {
+import {BaseElementPropsWithChildren, IdProps} from './shared';
+
+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.
@@ -15,13 +17,11 @@ declare global {
 }
 
 declare module 'preact' {
-  interface BaseProps {
-    children?: preact.ComponentChildren;
-  }
   // eslint-disable-next-line @typescript-eslint/no-namespace
   namespace createElement.JSX {
     interface IntrinsicElements {
-      ['s-image-group']: BaseProps & ImageGroupProps;
+      ['s-image-group']: BaseElementPropsWithChildren<ImageGroupElement> &
+        ImageGroupProps;
     }
   }
 }

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

@@ -0,0 +1,24 @@
+import '@shopify/ui-extensions/preact';
+import {render} from 'preact';
+
+export default async () => {
+  render(<Extension />, document.body);
+};
+
+function Extension() {
+  return (
+    <>
+      <s-button commandFor="order-actions-menu">Manage</s-button>
+      <s-menu
+        id="order-actions-menu"
+        accessibilityLabel="List of order actions"
+      >
+        <s-button onClick={() => console.log('Submit problem')}>
+          Submit problem
+        </s-button>
+        <s-button href="https://shopify.com">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;
+    }
+  }
+}