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

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

@@ -1,32 +1,33 @@
+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-page heading="Order #1411" subheading="Confirmed Oct 5">
       <s-button
-        slot="primaryAction"
+        slot="primary-action"
         onClick={() => console.log('Primary action')}
       >
-        Primary action
+        Buy again
       </s-button>
       <s-button
-        slot="secondaryActions"
+        slot="secondary-actions"
         onClick={() => console.log('Secondary action 1')}
       >
         Secondary action 1
       </s-button>
       <s-button
-        slot="secondaryActions"
+        slot="secondary-actions"
         onClick={() => console.log('Secondary action 2')}
       >
         Secondary action 2
       </s-button>
       <s-button
-        slot="breadcrumbActions"
+        slot="breadcrumb-actions"
         accessibilitylabel="Button"
         href="shopify://customer-account/orders"
       />

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

@@ -1,4 +1,6 @@
-export interface PageProps {
+import {BaseElementPropsWithChildren, IdProps} from './shared';
+
+export interface PageProps extends IdProps {
   /**
    * The main page heading
    */
@@ -10,6 +12,21 @@ export interface PageProps {
   subheading?: string;
 }
 
+export interface PageElementSlots {
+  /**
+   * The breadcrumb actions to perform, provided as button type elements.
+   */
+  'breadcrumb-actions'?: HTMLElement;
+  /**
+   * 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 PageElement extends HTMLElement, PageProps {}
 
 declare global {
@@ -19,14 +36,10 @@ 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-page']: BaseProps & PageProps;
+      ['s-page']: BaseElementPropsWithChildren<PageElement> & PageProps;
     }
   }
 }

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

@@ -0,0 +1,23 @@
+import '@shopify/ui-extensions/preact';
+import {render} from 'preact';
+
+export default async () => {
+  render(<Extension />, document.body);
+};
+
+function Extension() {
+  return (
+    <s-section heading="Rewards">
+      <s-button slot="primary-action" variant="primary">
+        Redeem
+      </s-button>
+      <s-button slot="secondary-action" 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 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 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,8 +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,14 +1,38 @@
 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.
+  key?: preact.Key;
+  // Assigns a ref (generally from `useRef()`) to this element.
+  ref?: preact.Ref<TClass>;
+  // Assigns this element to a parent's slot.
+  slot?: Lowercase<string>;
+}
+
+/**
+ * Used when an element has children.
+ */
+export interface BaseElementPropsWithChildren<TClass = HTMLElement>
+  extends BaseElementProps<TClass> {
+  children?: preact.ComponentChildren;
+}

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

@@ -1,17 +1,83 @@
-export interface CustomerAccountActionProps {
-  /**
-   * Sets the heading of the Action container.
-   */
-  heading: string;
+/**
+ * @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']: CustomerAccountActionElementDocs;
+  }
 }
 
-export interface CustomerAccountActionElement
-  extends HTMLElement,
-    CustomerAccountActionProps {}
+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 & CustomerAccountActionPropsDocs;
+    }
+  }
+}
+
+export type ImageGroupPropsDocs = ImageGroupProps;
+export type ImageGroupElementDocs = ImageGroupElement;
 
 declare global {
   interface HTMLElementTagNameMap {
-    ['s-customer-account-action']: CustomerAccountActionElement;
+    ['s-image-group']: ImageGroupElementDocs;
+  }
+}
+
+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-page']: PageElementDocs;
   }
 }
 
@@ -23,24 +89,38 @@ declare module 'preact' {
   // eslint-disable-next-line @typescript-eslint/no-namespace
   namespace createElement.JSX {
     interface IntrinsicElements {
-      ['s-customer-account-action']: BaseProps & CustomerAccountActionProps;
+      ['s-page']: BaseProps & PagePropsDocs;
     }
   }
 }
 
-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 AvatarElementPropsDocs = AvatarElementProps;
+export type AvatarPropsDocs = AvatarProps;
+export type AvatarElementDocs = AvatarElement;
+export type AvatarEventsDocs = AvatarEvents;
+
+declare global {
+  interface HTMLElementTagNameMap {
+    ['s-avatar']: AvatarElementDocs;
+  }
+}
+
+declare module 'preact' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace createElement.JSX {
+    interface IntrinsicElements {
+      ['s-avatar']: BaseElementPropsWithChildren<AvatarElementDocs> &
+        AvatarPropsDocs;
+    }
+  }
 }
 
-export interface ImageGroupElement extends HTMLElement, ImageGroupProps {}
+export type MenuPropsDocs = MenuProps;
+export type MenuElementDocs = MenuElement;
 
 declare global {
   interface HTMLElementTagNameMap {
-    ['s-image-group']: ImageGroupElement;
+    ['s-menu']: MenuElementDocs;
   }
 }
 
@@ -51,28 +131,41 @@ declare module 'preact' {
   // eslint-disable-next-line @typescript-eslint/no-namespace
   namespace createElement.JSX {
     interface IntrinsicElements {
-      ['s-image-group']: BaseProps & ImageGroupProps;
+      ['s-menu']: BaseProps & MenuProps;
     }
   }
 }
 
-export interface PageProps {
-  /**
-   * The main page heading
-   */
-  heading?: string;
+export type ButtonGroupPropsDocs = ButtonGroupProps;
+export type ButtonGroupElementDocs = ButtonGroupElement;
+export type ButtonGroupElementSlotsDocs = ButtonGroupElementSlots;
 
-  /**
-   * The text to be used as subheading.
-   */
-  subheading?: string;
+declare global {
+  interface HTMLElementTagNameMap {
+    ['s-button-group']: ButtonGroupElement;
+  }
+}
+
+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 PageElement extends HTMLElement, PageProps {}
+export type SectionPropsDocs = SectionProps;
+export type SectionElementDocs = SectionElement;
+export type SectionElementSlotsDocs = SectionElementSlots;
 
 declare global {
   interface HTMLElementTagNameMap {
-    ['s-page']: PageElement;
+    ['s-section']: SectionElementDocs;
   }
 }
 
@@ -84,7 +177,7 @@ declare module 'preact' {
   // eslint-disable-next-line @typescript-eslint/no-namespace
   namespace createElement.JSX {
     interface IntrinsicElements {
-      ['s-page']: BaseProps & PageProps;
+      ['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,5 @@ 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;
+  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 {ReadonlySignalLike} from '../api/shared';
+
+type Subscriber<T> = Parameters<ReadonlySignalLike<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: ReadonlySignalLike<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,9 @@
+import {ScannerApi} from '../scanner-api/scanner-api';
+import {NavigationApi} from '../navigation-api/navigation-api';
+import {StandardApi} from '../standard/standard-api';
+
+export type ActionTargetApi<T> = {[key: string]: any} & {
+  extensionPoint: T;
+} & StandardApi<T> &
+  ScannerApi &
+  NavigationApi;