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

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;
+}