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

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

@@ -0,0 +1,46 @@
+import {BaseElementPropsWithChildren, IdProps} from './shared';
+
+export interface SectionProps extends IdProps {
+  /**
+   * A label used to describe the section that will be announced by assistive technologies.
+   *
+   * When no `heading` property is provided or included as a children of the Section, you **must** provide an
+   * `accessibilityLabel` to describe the Section. This is important as it allows assistive technologies to provide
+   * the right context to users.
+   */
+  accessibilityLabel?: string;
+
+  /**
+   * A title that describes the content of the section.
+   */
+  heading?: string;
+}
+
+export interface SectionElementSlots {
+  /**
+   * 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 for the section. Accepts multiple [Button](/docs/api/checkout-ui-extensions/polaris-web-components/actions/button) elements.
+   */
+  'secondary-actions'?: HTMLElement;
+}
+
+export interface SectionElement extends SectionProps, Omit<HTMLElement, 'id'> {}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    ['s-section']: SectionElement;
+  }
+}
+
+declare module 'preact' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace createElement.JSX {
+    interface IntrinsicElements {
+      ['s-section']: BaseElementPropsWithChildren<SectionElement> &
+        SectionProps;
+    }
+  }
+}

package/src/surfaces/customer-account/components/StandardComponents.ts

@@ -2,9 +2,12 @@ import {AnyComponent} from '../../checkout';
 
 export type StandardComponents =
   | AnyComponent
-  | 'Page'
   | 'Avatar'
+  | 'ButtonGroup'
   | 'CustomerAccountAction'
-  | 'ImageGroup';
+  | 'ImageGroup'
+  | 'Menu'
+  | 'Page'
+  | 'Section';
 
 export default StandardComponents;

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

@@ -1,17 +1,24 @@
 export interface IdProps {
   /**
-   * A unique identifier for the component.
+   * A unique identifier for the element.
    */
   id?: string;
 }
 
-export type Size =
-  | 'extraSmall'
+export type SizeKeyword =
+  | 'small-500'
+  | 'small-400'
+  | 'small-300'
+  | 'small-200'
+  | 'small-100'
   | 'small'
   | 'base'
   | 'large'
-  | 'extraLarge'
-  | 'fill';
+  | 'large-100'
+  | 'large-200'
+  | 'large-300'
+  | 'large-400'
+  | 'large-500';
 
 export interface BaseElementProps<TClass = HTMLElement> {
   // Assigns a unique key to this element.

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

@@ -1,19 +1,39 @@
-import {Size} from './components/shared';
-
-export interface CustomerAccountActionProps {
-  /**
-   * Sets the heading of the Action container.
-   */
-  heading: string;
-}
-
-export interface CustomerAccountActionElement
-  extends HTMLElement,
-    CustomerAccountActionProps {}
+/**
+ * @fileoverview This file is used to generate the documentation for the customer-account surface. For component types, see the components folder.
+ */
+import {
+  AvatarProps,
+  AvatarElementProps,
+  AvatarElement,
+  AvatarEvents,
+} from './components/Avatar';
+import {
+  ButtonGroupProps,
+  ButtonGroupElement,
+  ButtonGroupElementSlots,
+} from './components/ButtonGroup';
+import {
+  CustomerAccountActionProps,
+  CustomerAccountActionElement,
+  CustomerAccountActionElementSlots,
+} from './components/CustomerAccountAction';
+import {ImageGroupProps, ImageGroupElement} from './components/ImageGroup';
+import {MenuProps, MenuElement} from './components/Menu';
+import {PageProps, PageElement, PageElementSlots} from './components/Page';
+import {
+  SectionProps,
+  SectionElement,
+  SectionElementSlots,
+} from './components/Section';
+
+export type CustomerAccountActionPropsDocs = CustomerAccountActionProps;
+export type CustomerAccountActionElementDocs = CustomerAccountActionElement;
+export type CustomerAccountActionElementSlotsDocs =
+  CustomerAccountActionElementSlots;
 
 declare global {
   interface HTMLElementTagNameMap {
-    ['s-customer-account-action']: CustomerAccountActionElement;
+    ['s-customer-account-action']: CustomerAccountActionElementDocs;
   }
 }
 
@@ -25,133 +45,139 @@ declare module 'preact' {
   // eslint-disable-next-line @typescript-eslint/no-namespace
   namespace createElement.JSX {
     interface IntrinsicElements {
-      ['s-customer-account-action']: BaseProps & CustomerAccountActionProps;
+      ['s-customer-account-action']: BaseProps & CustomerAccountActionPropsDocs;
     }
   }
 }
 
-export interface ImageGroupProps {
-  /**
-   * 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.
-   */
-  totalItems?: number;
+export type ImageGroupPropsDocs = ImageGroupProps;
+export type ImageGroupElementDocs = ImageGroupElement;
+
+declare global {
+  interface HTMLElementTagNameMap {
+    ['s-image-group']: ImageGroupElementDocs;
+  }
 }
 
-export interface ImageGroupElement extends HTMLElement, ImageGroupProps {}
+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 & ImageGroupPropsDocs;
+    }
+  }
+}
+
+export type PagePropsDocs = PageProps;
+export type PageElementDocs = PageElement;
+export type PageElementSlotsDocs = PageElementSlots;
 
 declare global {
   interface HTMLElementTagNameMap {
-    ['s-image-group']: ImageGroupElement;
+    ['s-page']: PageElementDocs;
   }
 }
 
 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-image-group']: BaseProps & ImageGroupProps;
+      ['s-page']: BaseProps & PagePropsDocs;
     }
   }
 }
 
-export interface PageProps {
-  /**
-   * The main page heading
-   */
-  heading?: string;
+export type AvatarElementPropsDocs = AvatarElementProps;
+export type AvatarPropsDocs = AvatarProps;
+export type AvatarElementDocs = AvatarElement;
+export type AvatarEventsDocs = AvatarEvents;
 
-  /**
-   * The text to be used as subheading.
-   */
-  subheading?: string;
+declare global {
+  interface HTMLElementTagNameMap {
+    ['s-avatar']: AvatarElementDocs;
+  }
 }
 
-export interface PageElement extends HTMLElement, PageProps {}
+declare module 'preact' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace createElement.JSX {
+    interface IntrinsicElements {
+      ['s-avatar']: BaseElementPropsWithChildren<AvatarElementDocs> &
+        AvatarPropsDocs;
+    }
+  }
+}
+
+export type MenuPropsDocs = MenuProps;
+export type MenuElementDocs = MenuElement;
 
 declare global {
   interface HTMLElementTagNameMap {
-    ['s-page']: PageElement;
+    ['s-menu']: MenuElementDocs;
   }
 }
 
 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-page']: BaseProps & PageProps;
+      ['s-menu']: BaseProps & MenuProps;
     }
   }
 }
 
-interface GlobalProps {
-  /**
-   * A unique identifier for the element.
-   */
-  id?: string;
+export type ButtonGroupPropsDocs = ButtonGroupProps;
+export type ButtonGroupElementDocs = ButtonGroupElement;
+export type ButtonGroupElementSlotsDocs = ButtonGroupElementSlots;
+
+declare global {
+  interface HTMLElementTagNameMap {
+    ['s-button-group']: ButtonGroupElement;
+  }
 }
 
-export interface AvatarProps extends GlobalProps {
-  /**
-   * 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;
-
-  /**
-   * Invoked when load of provided image completes successfully.
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onload
-   */
-  onLoad?(): void;
-
-  /**
-   * Invoked on load error of provided image.
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/API/GlobalEventHandlers/onerror
-   */
-  onError?(): void;
-
-  /**
-   * Size of the avatar.
-   *
-   * @default 'base'
-   */
-  size?: Extract<Size, 'base' | 'large' | 'extraLarge' | 'fill'>;
-
-  /**
-   * 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;
+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-button-group']: BaseProps & ButtonGroupProps;
+    }
+  }
 }
 
-export interface AvatarElement extends AvatarProps, Omit<HTMLElement, 'id'> {}
+export type SectionPropsDocs = SectionProps;
+export type SectionElementDocs = SectionElement;
+export type SectionElementSlotsDocs = SectionElementSlots;
 
 declare global {
   interface HTMLElementTagNameMap {
-    ['s-avatar']: AvatarElement;
+    ['s-section']: SectionElementDocs;
   }
 }
 
 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-avatar']: BaseElementPropsWithChildren<AvatarElement> & AvatarProps;
+      ['s-section']: BaseProps & SectionPropsDocs;
     }
   }
 }

package/src/surfaces/customer-account/extension-targets.ts

@@ -5,7 +5,6 @@ import type {OrderStatusApi} from './api/order-status/order-status';
 import type {RenderExtension} from '../../extension';
 import {
   StandardApi,
-  FullExtensionNavigation,
   CompanyLocationApi,
   OrderApi,
   FulfillmentApi,
@@ -39,6 +38,11 @@ export interface OrderStatusExtensionTargets {
       StandardApi<'customer-account.order-status.block.render'>,
     StandardComponents
   >;
+  'customer-account.order-status.announcement.render': RenderExtension<
+    OrderStatusApi<'customer-account.order-status.announcement.render'> &
+      StandardApi<'customer-account.order-status.announcement.render'>,
+    StandardComponents
+  >;
   /**
    * A static extension target that renders on every line item, inside the details
    * under the line item properties element on the **Order status** page.
@@ -89,8 +93,7 @@ export interface OrderStatusExtensionTargets {
   >;
   'customer-account.order.page.render': RenderExtension<
     OrderStatusApi<'customer-account.order.page.render'> &
-      Omit<StandardApi<'customer-account.order.page.render'>, 'navigation'> &
-      FullPageApi,
+      StandardApi<'customer-account.order.page.render'>,
     StandardComponents
   >;
 }
@@ -102,18 +105,25 @@ export type RenderCustomerAccountFullPageExtensionTarget =
 
 export interface CustomerAccountExtensionTargets {
   'customer-account.page.render': RenderExtension<
-    Omit<StandardApi<'customer-account.page.render'>, 'navigation'> &
-      FullPageApi,
+    StandardApi<'customer-account.page.render'>,
     StandardComponents
   >;
   'customer-account.order-index.block.render': RenderExtension<
     StandardApi<'customer-account.order-index.block.render'>,
     StandardComponents
   >;
+  'customer-account.order-index.announcement.render': RenderExtension<
+    StandardApi<'customer-account.order-index.announcement.render'>,
+    StandardComponents
+  >;
   'customer-account.profile.block.render': RenderExtension<
     StandardApi<'customer-account.profile.block.render'>,
     StandardComponents
   >;
+  'customer-account.profile.announcement.render': RenderExtension<
+    StandardApi<'customer-account.profile.announcement.render'>,
+    StandardComponents
+  >;
   'customer-account.profile.addresses.render-after': RenderExtension<
     StandardApi<'customer-account.profile.addresses.render-after'>,
     StandardComponents
@@ -254,10 +264,6 @@ export type AllowedComponentsForRenderExtension<
   Target extends keyof RenderExtensions,
 > = ExtractedAllowedComponentsFromRenderExtension<RenderExtensions[Target]>;
 
-export interface FullPageApi {
-  navigation: FullExtensionNavigation;
-}
-
 export interface ActionExtensionApi {
   close(): void;
 }

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

@@ -1,3 +1,4 @@
+import {Navigation} from './api';
 import type {ExtensionTargets} from './extension-targets';
 
 export interface ShopifyGlobal {
@@ -9,8 +10,7 @@ export interface ShopifyGlobal {
 }
 
 declare global {
-  // conflicts with build/ts/globals.d.ts
-  // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-  // @ts-ignore
-  const shopify: ShopifyGlobal;
+  // @ts-expect-error - Intentionally overriding navigation type for POS context
+  // This is safe as point-of-sale and customer-account are never used together
+  const navigation: Navigation;
 }

package/src/surfaces/customer-account/preact/live-navigation.ts

@@ -1,14 +1,7 @@
-import type {RenderCustomerAccountFullPageExtensionTarget} from '../extension-targets';
 import type {NavigationHistoryEntry} from '../api';
-
-import {useApi} from './api';
 import {useEffect, useReducer} from 'preact/hooks';
 
-export function useNavigationCurrentEntry<
-  Target extends RenderCustomerAccountFullPageExtensionTarget = RenderCustomerAccountFullPageExtensionTarget,
->(): NavigationHistoryEntry {
-  const navigation = useApi<Target>().navigation;
-
+export function useNavigationCurrentEntry(): NavigationHistoryEntry {
   const [entry, update] = useReducer(
     () => navigation.currentEntry,
     navigation.currentEntry,

package/src/surfaces/customer-account/preact/navigation.ts

@@ -1,12 +1,5 @@
-import type {
-  RenderCustomerAccountExtensionTarget,
-  ApiForExtension,
-} from '../extension-targets';
+import {Navigation} from '../api';
 
-import {useApi} from './api';
-
-export function useNavigation<
-  Target extends RenderCustomerAccountExtensionTarget = RenderCustomerAccountExtensionTarget,
->(): ApiForExtension<Target>['navigation'] {
-  return useApi<Target>().navigation;
+export function useNavigation(): Navigation {
+  return navigation;
 }

package/src/surfaces/customer-account/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 {SubscribableSignalLike} from '../api/shared';
+
+type Subscriber<T> = Parameters<SubscribableSignalLike<T>['subscribe']>[0];
 
 /**
  * Subscribes to the special wrapper type that all “changeable” values in the
@@ -13,9 +14,9 @@ type Subscriber<T> = Parameters<StatefulRemoteSubscribable<T>['subscribe']>[0];
  * > for accessing the current value of each individual resource in the checkout.
  */
 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 +34,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 +42,5 @@ export function useSubscription<Value>(
     };
   }, [subscription]);
 
-  return subscription.current;
+  return subscription.value;
 }

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

@@ -0,0 +1,15 @@
+export interface ActionApiContent {
+  /** Presents the `action-overlay.render` extension target on top of present view.
+   *
+   * For example: if we are calling presentModal() from pos.purchase.post.action.menu-item.render,
+   * it should present pos.purchase.post.action.render.
+   */
+  presentModal(): void;
+}
+
+/**
+ * Access the Action API to present your app in a full screen modal.
+ */
+export interface ActionApi {
+  action: ActionApiContent;
+}

package/src/surfaces/point-of-sale/api/action-target-api/action-target-api.ts

@@ -0,0 +1,7 @@
+import {ScannerApi} from '../scanner-api/scanner-api';
+import {StandardApi} from '../standard/standard-api';
+
+export type ActionTargetApi<T> = {[key: string]: any} & {
+  extensionPoint: T;
+} & StandardApi<T> &
+  ScannerApi;