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

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

@@ -45,7 +45,7 @@ export interface NavigationCurrentEntryChangeEvent {
  */
 export interface Navigation {
   /**
-   * Navigates to a specific URL, updating any provided state in the history entries list. Returns a promise that resolves when navigation is complete. Use for programmatic navigation between screens, implementing custom navigation controls, or deep-linking to specific modal states.
+   * Navigates to a specific URL, updating any provided state in the history entries list. The promise does not wait for the native screen transition to finish; listen for `navigatesuccess` on the screen that becomes active to know when it has finished appearing. Use for programmatic navigation between screens, implementing custom navigation controls, or deep-linking to specific modal states.
    */
   navigate: (url: string, options?: NavigationNavigateOptions) => Promise<void>;
   /**
@@ -57,23 +57,38 @@ export interface Navigation {
    */
   back(): void;
   /**
-   * Registers an event listener for navigation events. The `currententrychange` event fires when the `currentEntry` property changes, such as when the user navigates to a different screen within the extension modal. Use to track navigation changes, update UI state based on the current location, or implement analytics for navigation patterns.
-   * @param type - The event type to listen for. Currently only `'currententrychange'` is supported.
-   * @param cb - The callback function invoked when the event fires. Receives a `NavigationCurrentEntryChangeEvent` containing the previous entry that was navigated away from.
+   * Registers a listener for `currententrychange`, which fires when the active history entry changes. This can happen before the screen finishes appearing.
+   * @param type - The event type to listen for.
+   * @param cb - Receives the previous history entry in `event.from`.
    */
   addEventListener(
     type: 'currententrychange',
     cb: (event: NavigationCurrentEntryChangeEvent) => void,
   ): void;
   /**
-   * Removes a previously registered event listener. The callback reference must match the one passed to `addEventListener`. Use to clean up event listeners when they are no longer needed, such as when a component unmounts or navigation tracking should be disabled.
-   * @param type - The event type to remove the listener for. Currently only `'currententrychange'` is supported.
-   * @param cb - The callback function to remove. Must be the same function reference that was passed to `addEventListener`.
+   * Registers a listener for `navigatesuccess`, which fires after the extension screen becomes active and finishes its native transition. The callback receives a standard `Event`, not a history entry. When navigating back, register the listener on the screen that will reappear: the departing screen is removed and cannot receive the completion event. Older POS builds without support for this event do not emit it.
+   * @param type - The event type to listen for.
+   * @param cb - Called after the screen finishes appearing.
+   */
+  addEventListener(type: 'navigatesuccess', cb: (event: Event) => void): void;
+  /**
+   * Removes a `currententrychange` listener. Pass the same callback reference used with `addEventListener`.
+   * @param type - The event type to stop listening for.
+   * @param cb - The previously registered callback.
    */
   removeEventListener(
     type: 'currententrychange',
     cb: (event: NavigationCurrentEntryChangeEvent) => void,
   ): void;
+  /**
+   * Removes a `navigatesuccess` listener. Pass the same callback reference used with `addEventListener`.
+   * @param type - The event type to stop listening for.
+   * @param cb - The previously registered callback.
+   */
+  removeEventListener(
+    type: 'navigatesuccess',
+    cb: (event: Event) => void,
+  ): void;
 }
 
 /**

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

@@ -8,17 +8,44 @@ import type {ReadonlySignalLike} from '../../../../shared';
  * @private
  */
 export interface ResolutionApi<TEventData> {
+  /** The intercepted event data and save handler for the active resolution target. */
   resolution: ResolutionApiContent<TEventData>;
 }
 
 /**
- * @private
+ * Runs when staff advance the resolution flow. Return a promise to have POS
+ * wait for pending work to finish before it re-runs validation.
+ *
+ * @publicDocs
+ */
+export type ResolutionSaveHandler = () => void | Promise<void>;
+
+/**
+ * The intercepted event data and save handler available to a validation
+ * resolution target through `shopify.resolution`.
+ *
+ * @publicDocs
  */
 export interface ResolutionApiContent<TEventData> {
   /**
    * The data of the intercepted event this resolution target was opened for.
-   * The `value` property provides the current data, and `subscribe` allows
-   * listening for host-owned revalidation updates.
+   * The `value` property provides the current data, and `subscribe` receives
+   * Shopify POS revalidation updates.
    */
   event: ReadonlySignalLike<TEventData>;
+
+  /**
+   * Registers a handler that runs when staff advance the resolution flow
+   * (Save, Next, or Done). POS awaits the handler before it re-runs the
+   * intercepted validation, so use it to commit any pending work, for example
+   * cart updates or storage writes, and `await` those calls inside the handler.
+   * A rejected promise does not stop the flow; POS still re-runs validation and
+   * the interceptor result decides what happens next.
+   *
+   * Only the most recent handler is kept.
+   *
+   * @returns A promise that resolves to an async cleanup function that
+   * unregisters the handler.
+   */
+  onSave(handler: ResolutionSaveHandler): Promise<() => Promise<void>>;
 }

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

@@ -7,7 +7,7 @@ import type {Session, StaffMember} from '../../types/session';
  */
 export interface SessionApiContent {
   /**
-   * Provides comprehensive information about the current POS session including shop details, user authentication, location data, staff member information, currency settings, and POS version. This data is static for the duration of the session and updates when users switch locations or staff members change.
+   * Provides information about the current POS session including shop details, user authentication, location data, currency settings, and POS version. Use `session.staffMember` to access the staff member currently pinned into POS and subscribe to staff member changes.
    */
   currentSession: Session;
   /**

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

@@ -24,11 +24,13 @@ export type {DataTargetApi} from './api/data-target-api/data-target-api';
 export type {
   ResolutionApi,
   ResolutionApiContent,
+  ResolutionSaveHandler,
 } from './api/resolution-api/resolution-api';
 export type {
   TransactionCompleteEvent,
   CashTrackingSessionStartEvent,
   CashTrackingSessionCompleteEvent,
+  ScanEvent,
   ShopifyEventMap,
 } from './events';
 

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

@@ -0,0 +1,179 @@
+/** VERSION: undefined **/
+/* eslint-disable import-x/extensions */
+/* eslint-disable @typescript-eslint/no-namespace */
+/* eslint-disable @typescript-eslint/member-ordering */
+/* eslint-disable line-comment-position */
+/* eslint-disable @typescript-eslint/unified-signatures */
+/* eslint-disable no-var */
+/* eslint-disable import-x/namespace */
+// eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment
+/// <reference lib="DOM" />
+import type {Key, Ref, ComponentChild} from './components-shared.d.ts';
+
+export type ComponentChildren = any;
+/**
+ * Used when an element does not have children.
+ */
+export interface BaseElementProps<TClass = HTMLElement> {
+  key?: Key;
+  ref?: Ref<TClass>;
+  slot?: Lowercase<string>;
+}
+/**
+ * Used when an element has children.
+ */
+export interface BaseElementPropsWithChildren<TClass = HTMLElement>
+  extends BaseElementProps<TClass> {
+  children?: ComponentChildren;
+}
+export type IntrinsicElementProps<T> = T &
+  BaseElementPropsWithChildren<T & HTMLElement>;
+export type HtmlElementTagNameProps<T> = T & HTMLElement;
+export type ElementForTag<T extends string> =
+  T extends keyof HTMLElementTagNameMap
+    ? HTMLElementTagNameMap[T]
+    : HTMLElement;
+export interface CallbackEvent<T extends string> {
+  currentTarget: ElementForTag<T>;
+  bubbles?: boolean;
+  cancelable?: boolean;
+  composed?: boolean;
+  detail?: any;
+  eventPhase: number;
+  target: ElementForTag<T> | null;
+}
+
+/**
+ * The serialized template AST carried by `s-pos-list`'s `itemTemplates`
+ * property.
+ *
+ * Templates are authored in the extension sandbox with the `posListTemplate`
+ * tagged template, compiled once into this plain-JSON shape, and shipped
+ * across the bridge as a single property. The host hydrates the AST per
+ * visible row, so no RemoteDOM nodes exist for template content and no
+ * extension code runs while scrolling.
+ */
+/** A literal string piece or a row-field lookup within interpolated text. */
+export type POSListTemplateSegment =
+  | string
+  | {
+      path: string;
+    };
+export type POSListTemplateProp =
+  /** A static value. Web component attributes yield strings, or `true` when valueless. */
+  | {
+      kind: 'literal';
+      value: string | boolean;
+    }
+  /** The row field at `path`, passed through with its original type (`bind:prop="path"`). */
+  | {
+      kind: 'field';
+      path: string;
+    }
+  /** A string built from literal pieces and `{{path}}` lookups. */
+  | {
+      kind: 'segments';
+      segments: POSListTemplateSegment[];
+    };
+export type POSListTemplateNode =
+  | {
+      kind: 'element';
+      tag: string;
+      props?: Record<string, POSListTemplateProp>;
+      children?: POSListTemplateNode[];
+    }
+  /** Literal text, possibly interpolated with `{{path}}` lookups. */
+  | {
+      kind: 'text';
+      segments: POSListTemplateSegment[];
+    }
+  /** `{{#if path}}…{{/if}}`: children render only when the field is truthy. */
+  | {
+      kind: 'if';
+      path: string;
+      children: POSListTemplateNode[];
+    };
+/** One `<s-pos-list-item templateId="…">` root. */
+export interface POSListItemTemplate {
+  templateId: string;
+  /** `button` rows fire `rowclick`; `text` rows are static content. */
+  type: 'button' | 'text';
+  children: POSListTemplateNode[];
+}
+export interface POSListTemplates {
+  templates: POSListItemTemplate[];
+}
+
+declare const tagName = 's-pos-list';
+/**
+ * A row supplied to `s-pos-list`. Rows are plain data; every member other than `id` and
+ * `templateFor` is available to the row's item template through `{{path}}`, `bind:prop`,
+ * and `{{#if path}}` bindings.
+ */
+export interface POSListRow {
+  /** A unique identifier for the row. Keys virtualization and identity across incremental loads. */
+  id: string;
+  /** The `templateId` of the item template that renders this row. */
+  templateFor: string;
+  /** Any additional data the row's template reads. */
+  [field: string]: unknown;
+}
+/**
+ * The event fired when a `button` row is activated. `event.detail.item` is the activated row, and
+ * `event.detail.index` is its position in `rows`.
+ */
+export type POSListRowClickEvent = CallbackEvent<'s-pos-list'> & {
+  detail: {
+    item: POSListRow;
+    index: number;
+  };
+};
+/**
+ * Displays a virtualized list of rows rendered from plain data and item templates compiled with
+ * `posListTemplate`.
+ *
+ * @publicDocs
+ */
+export interface POSListJSXProps {
+  /** A unique identifier for the element. */
+  id?: string;
+  /** An array of POSListRow objects that define the content of each row in the list. */
+  rows?: POSListRow[];
+  /**
+   * Reusable templates that define the layout of list rows. Use `posListTemplate` to define one or
+   * more `<s-pos-list-item>` templates.
+   */
+  itemTemplates?: POSListTemplates;
+  /**
+   * Whether more data is being loaded. Set to `true` when paginating and fetching additional data
+   * for the list. POS shows a progress indicator after the last row.
+   *
+   * @default false
+   */
+  loadingMore?: boolean;
+  /**
+   * Callback when a `button` row is activated. `event.detail.item` is the row and
+   * `event.detail.index` its position in `rows`. Rows rendered by a `text` template never fire it.
+   */
+  onRowClick?: ((event: POSListRowClickEvent) => void) | null;
+  /** Callback when the list has scrolled near its end and more rows should be loaded. */
+  onLoadMore?: ((event: CallbackEvent<typeof tagName>) => void) | null;
+  /** Content displayed before the rows as part of the list's scrollable content. */
+  header?: ComponentChild;
+}
+export type ElementProps = Omit<POSListJSXProps, 'header'>;
+declare global {
+  interface HTMLElementTagNameMap {
+    [tagName]: HtmlElementTagNameProps<ElementProps>;
+  }
+}
+declare module 'preact' {
+  namespace createElement.JSX {
+    interface IntrinsicElements {
+      [tagName]: IntrinsicElementProps<ElementProps>;
+    }
+  }
+}
+
+export {tagName};
+export type {ElementProps, POSListJSXProps, POSListRow, POSListRowClickEvent};

package/src/surfaces/point-of-sale/components/targets/BlockExtensionComponents.ts

@@ -7,15 +7,11 @@ export type BlockExtensionComponents =
   | 'Button'
   | 'DatePicker'
   | 'DateSpinner'
-  | 'Dialog'
   | 'Heading'
   | 'Icon'
   | 'Image'
   | 'Modal'
-  | 'POSBlock'
   | 'PosBlock' // Case is important in 2025-10
-  | 'POSBlockRow'
-  | 'PrintPreview'
   | 'Section'
   | 'Stack'
   | 'Text'

package/src/surfaces/point-of-sale/components/targets/ResolutionComponents.ts

@@ -9,5 +9,5 @@ import type {StandardComponents} from './StandardComponents';
  */
 export type ResolutionComponents = Exclude<
   StandardComponents,
-  'Page' | 'POSBlock' | 'PosBlock' | 'Tile'
+  'Page' | 'PosBlock' | 'Tile'
 >;

package/src/surfaces/point-of-sale/components/targets/StandardComponents.ts

@@ -23,10 +23,8 @@ export type StandardComponents =
   | 'Modal'
   | 'NumberField'
   | 'Page'
-  | 'POSBlock'
+  | 'POSList'
   | 'PosBlock' // Case is important in 2025-10
-  | 'Route'
-  | 'Router'
   | 'ScrollBox'
   | 'SearchField'
   | 'Section'

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

@@ -5435,6 +5435,138 @@ declare module 'preact' {
   }
 }
 
+/**
+ * The serialized template AST carried by `s-pos-list`'s `itemTemplates`
+ * property.
+ *
+ * Templates are authored in the extension sandbox with the `posListTemplate`
+ * tagged template, compiled once into this plain-JSON shape, and shipped
+ * across the bridge as a single property. The host hydrates the AST per
+ * visible row, so no RemoteDOM nodes exist for template content and no
+ * extension code runs while scrolling.
+ */
+/** A literal string piece or a row-field lookup within interpolated text. */
+type POSListTemplateSegment =
+  | string
+  | {
+      path: string;
+    };
+type POSListTemplateProp =
+  /** A static value. Web component attributes yield strings, or `true` when valueless. */
+  | {
+      kind: 'literal';
+      value: string | boolean;
+    }
+  /** The row field at `path`, passed through with its original type (`bind:prop="path"`). */
+  | {
+      kind: 'field';
+      path: string;
+    }
+  /** A string built from literal pieces and `{{path}}` lookups. */
+  | {
+      kind: 'segments';
+      segments: POSListTemplateSegment[];
+    };
+type POSListTemplateNode =
+  | {
+      kind: 'element';
+      tag: string;
+      props?: Record<string, POSListTemplateProp>;
+      children?: POSListTemplateNode[];
+    }
+  /** Literal text, possibly interpolated with `{{path}}` lookups. */
+  | {
+      kind: 'text';
+      segments: POSListTemplateSegment[];
+    }
+  /** `{{#if path}}…{{/if}}`: children render only when the field is truthy. */
+  | {
+      kind: 'if';
+      path: string;
+      children: POSListTemplateNode[];
+    };
+/** One `<s-pos-list-item templateId="…">` root. */
+interface POSListItemTemplate {
+  templateId: string;
+  /** `button` rows fire `rowclick`; `text` rows are static content. */
+  type: 'button' | 'text';
+  children: POSListTemplateNode[];
+}
+interface POSListTemplates {
+  templates: POSListItemTemplate[];
+}
+
+declare const posListTagName = 's-pos-list';
+/**
+ * A row supplied to `s-pos-list`. Rows are plain data; every member other than `id` and
+ * `templateFor` is available to the row's item template through `{{path}}`, `bind:prop`,
+ * and `{{#if path}}` bindings.
+ */
+interface POSListRow {
+  /** A unique identifier for the row. Keys virtualization and identity across incremental loads. */
+  id: string;
+  /** The `templateId` of the item template that renders this row. */
+  templateFor: string;
+  /** Any additional data the row's template reads. */
+  [field: string]: unknown;
+}
+/**
+ * The event fired when a `button` row is activated. `event.detail.item` is the activated row, and
+ * `event.detail.index` is its position in `rows`.
+ */
+type POSListRowClickEvent = CallbackEvent<'s-pos-list'> & {
+  detail: {
+    item: POSListRow;
+    index: number;
+  };
+};
+/**
+ * Displays a virtualized list of rows rendered from plain data and item templates compiled with
+ * `posListTemplate`.
+ *
+ * @publicDocs
+ */
+interface POSListJSXProps {
+  /** A unique identifier for the element. */
+  id?: string;
+  /** An array of POSListRow objects that define the content of each row in the list. */
+  rows?: POSListRow[];
+  /**
+   * Reusable templates that define the layout of list rows. Use `posListTemplate` to define one or
+   * more `<s-pos-list-item>` templates.
+   */
+  itemTemplates?: POSListTemplates;
+  /**
+   * Whether more data is being loaded. Set to `true` when paginating and fetching additional data
+   * for the list. POS shows a progress indicator after the last row.
+   *
+   * @default false
+   */
+  loadingMore?: boolean;
+  /**
+   * Callback when a `button` row is activated. `event.detail.item` is the row and
+   * `event.detail.index` its position in `rows`. Rows rendered by a `text` template never fire it.
+   */
+  onRowClick?: ((event: POSListRowClickEvent) => void) | null;
+  /** Callback when the list has scrolled near its end and more rows should be loaded. */
+  onLoadMore?: ((event: CallbackEvent<typeof posListTagName>) => void) | null;
+  /** Content displayed before the rows as part of the list's scrollable content. */
+  header?: ComponentChild;
+}
+type POSListElementProps = Omit<POSListJSXProps, 'header'>;
+declare global {
+  interface HTMLElementTagNameMap {
+    [posListTagName]: HtmlElementTagNameProps<POSListElementProps>;
+  }
+}
+declare module 'preact' {
+  namespace createElement.JSX {
+    interface IntrinsicElements {
+      [posListTagName]: IntrinsicElementProps<POSListElementProps>;
+    }
+  }
+}
+
 export type {
   BadgeJSXProps,
   BannerJSXProps,
@@ -5457,6 +5589,7 @@ export type {
   ModalJSXProps,
   NumberFieldJSXProps,
   PageJSXProps,
+  POSListJSXProps,
   PosBlockJSXProps,
   QrCodeJSXProps,
   ScrollBoxJSXProps,
@@ -5477,6 +5610,52 @@ export type {
   TimePickerJSXProps,
 };
 
+/**
+ * The POS list component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events).
+ * @publicDocs
+ */
+interface POSListEvents {
+  /**
+   * Callback when a `button` row is activated. `event.detail.item` is the row and
+   * `event.detail.index` its position in `rows`. Rows rendered by a `text` template never fire it.
+   */
+  rowclick?: (event: POSListRowClickEvent) => void;
+  /** Callback when the list has scrolled near its end and more rows should be loaded. */
+  loadmore?: (event: CallbackEvent<typeof posListTagName>) => void;
+}
+
+/**
+ * Content slots for the POS list.
+ * @publicDocs
+ */
+interface POSListSlots {
+  /** Content displayed before the rows as part of the list's scrollable content. */
+  header?: HTMLElement;
+}
+
+/**
+ * Displays a virtualized list of rows rendered from plain data and item templates compiled with
+ * `posListTemplate`.
+ * @publicDocs
+ */
+interface POSList {
+  /** A unique identifier for the element. */
+  id?: string;
+  /** An array of POSListRow objects that define the content of each row in the list. */
+  rows?: POSListRow[];
+  /**
+   * Reusable templates that define the layout of list rows. Use `posListTemplate` to define one or
+   * more `<s-pos-list-item>` templates.
+   */
+  itemTemplates?: POSListTemplates;
+  /**
+   * Whether more data is being loaded. Set to `true` when paginating and fetching additional data
+   * for the list. POS shows a progress indicator after the last row.
+   * @default false
+   */
+  loadingMore?: boolean;
+}
+
 /**
  * The link component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events).
  * @publicDocs
@@ -7809,3 +7988,18 @@ declare global {
     }
   }
 }
+
+declare module 'react' {
+  namespace JSX {
+    interface IntrinsicElements {
+      [posListTagName]: IntrinsicElementProps<POSListElementProps>;
+    }
+  }
+}
+declare global {
+  namespace JSX {
+    interface IntrinsicElements {
+      [posListTagName]: IntrinsicElementProps<POSListElementProps>;
+    }
+  }
+}

package/src/surfaces/point-of-sale/event/data/BaseData.ts

@@ -4,6 +4,18 @@ import type {
   Session,
 } from '../../../point-of-sale';
 
+/**
+ * A snapshot of the POS session provided to receipt targets.
+ * @publicDocs
+ */
+export interface BaseDataSession extends Session {
+  /**
+   * The ID of the staff member pinned into POS for this receipt event. This
+   * snapshot is separate from the reactive `session.staffMember` on the Session API.
+   */
+  staffMemberId?: number;
+}
+
 /**
  * Base data object provided to all extension targets containing device information, session context, and connectivity state. This data is available at extension initialization and provides essential context about the runtime environment.
  * @publicDocs
@@ -24,5 +36,5 @@ export interface BaseData {
   /**
    * Comprehensive information about the current POS session including shop ID and domain, authenticated user, pinned staff member, active location, currency settings, and POS version. This session data remains constant for the session duration and provides critical context for business logic, permissions, API authentication, and transaction processing. Session data updates when users switch locations or change pinned staff members.
    */
-  session: Session;
+  session: BaseDataSession;
 }

package/src/surfaces/point-of-sale/event/data.ts

@@ -1,4 +1,4 @@
-export type {BaseData} from './data/BaseData';
+export type {BaseData, BaseDataSession} from './data/BaseData';
 export type {BaseApi} from './data/BaseApi';
 export type {ReprintReceiptData} from './data/ReprintReceiptData';
 export type {TransactionCompleteWithReprintData} from './data/TransactionCompleteData';

package/src/surfaces/point-of-sale/events/scan-event.ts

@@ -0,0 +1,34 @@
+import type {ScannerSource} from '../api/scanner-api/scanner-api';
+
+/**
+ * Dispatched once for each successful scan captured by a camera, external,
+ * or embedded scanner. Every event carries a decoded `data` value and its
+ * `source`; no event is dispatched for initial or empty scanner state.
+ *
+ * The event is delivered only after POS has finished handling the scan
+ * itself.
+ *
+ * @example
+ * ```ts
+ * shopify.addEventListener('scan', (event) => {
+ *   handleScan(event.data, event.source);
+ * });
+ * ```
+ * @publicDocs
+ */
+export interface ScanEvent {
+  /** The event name. */
+  readonly type: 'scan';
+  /**
+   * The decoded string captured by the scan. Contains the scanned barcode, QR code, or other scannable data. Always present: an event is only dispatched for a successful scan.
+   */
+  readonly data: string;
+  /**
+   * The scanner source that captured the scan. One of the following scanner types:
+   *
+   * • `'camera'` - Built-in device camera used for scanning
+   * • `'external'` - External scanner hardware connected to the device
+   * • `'embedded'` - Embedded scanner hardware built into the device
+   */
+  readonly source: ScannerSource;
+}