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

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

@@ -3,6 +3,7 @@ import type {
   CashTrackingSessionStartEvent,
   CashTrackingSessionCompleteEvent,
 } from './events/cash-tracking-session-events';
+import type {ScanEvent} from './events/scan-event';
 import type {Cart} from './types/cart';
 import type {MoneyV2} from './types/money';
 
@@ -16,6 +17,7 @@ export const POS_EVENT_NAMES = {
   TRANSACTION_COMPLETE: 'transactioncomplete',
   CASH_TRACKING_SESSION_START: 'cashtrackingsessionstart',
   CASH_TRACKING_SESSION_COMPLETE: 'cashtrackingsessioncomplete',
+  SCAN: 'scan',
 } as const;
 
 /**
@@ -47,6 +49,12 @@ export interface ShopifyEventMap {
   [POS_EVENT_NAMES.CASH_TRACKING_SESSION_START]: CashTrackingSessionStartEvent;
   /** Dispatched when a cash tracking session closes after reconciliation. */
   [POS_EVENT_NAMES.CASH_TRACKING_SESSION_COMPLETE]: CashTrackingSessionCompleteEvent;
+  /**
+   * Dispatched once for each successful scan captured by a camera, external,
+   * or embedded scanner, after POS has finished handling the scan itself.
+   * Every event carries decoded `data` and its `source`.
+   */
+  [POS_EVENT_NAMES.SCAN]: ScanEvent;
 }
 
 /**
@@ -54,7 +62,7 @@ export interface ShopifyEventMap {
  *
  * Used as the generic type parameter for `shopify.intercept`.
  *
- * @private
+ * @publicDocs
  */
 export interface ShopifyInterceptMap {
   [POS_INTERCEPT_NAMES.CART_VALIDATIONS]: CartValidationsEvent;
@@ -64,7 +72,7 @@ export interface ShopifyInterceptMap {
 /**
  * The data carried by a `cartvalidations` event.
  *
- * @private
+ * @publicDocs
  */
 export interface CartValidationsEventData {
   /** A snapshot of the POS cart taken when the event was produced. */
@@ -75,16 +83,17 @@ export interface CartValidationsEventData {
  * The event a `cartvalidations` interceptor receives. Carries a snapshot of
  * the POS cart taken when the event was produced.
  *
- * @private
+ * @publicDocs
  */
 export interface CartValidationsEvent extends CartValidationsEventData {
+  /** The event name, always `'cartvalidations'`. */
   readonly type: typeof POS_INTERCEPT_NAMES.CART_VALIDATIONS;
 }
 
 /**
  * The kind of payment method being attempted.
  *
- * @private
+ * @publicDocs
  */
 export type InterceptedPaymentMethodType = 'cash';
 
@@ -95,7 +104,7 @@ export type InterceptedPaymentMethodType = 'cash';
  * disambiguates method types a shop can have several of (for example custom
  * payment methods) as they become interceptable.
  *
- * @private
+ * @publicDocs
  */
 export interface InterceptedPaymentMethod {
   readonly type: InterceptedPaymentMethodType;
@@ -109,29 +118,30 @@ export interface InterceptedPaymentMethod {
  * attempt's payment method and amount; split payments produce one event per
  * tender, each with its own amount.
  *
- * @private
+ * @publicDocs
  */
 export interface PaymentValidationsEvent extends PaymentValidationsEventData {
+  /** The event name, always `'paymentvalidations'`. */
   readonly type: typeof POS_INTERCEPT_NAMES.PAYMENT_VALIDATIONS;
 }
 
 /**
  * The data carried by a `paymentvalidations` event.
  *
- * @private
+ * @publicDocs
  */
 export interface PaymentValidationsEventData {
   /** The payment method staff selected. */
   readonly paymentMethod: InterceptedPaymentMethod;
 
-  /** The amount this tender would charge, in presentment currency. */
+  /** The cash amount received for this tender, in presentment currency. */
   readonly amount: MoneyV2;
 }
 
 /**
  * Targets the whole cart rather than a specific line item.
  *
- * @private
+ * @publicDocs
  */
 export type CartTarget = '$.cart';
 
@@ -139,38 +149,50 @@ export type CartTarget = '$.cart';
  * Targets one cart line item by its `uuid` from this event's `cart` snapshot,
  * for example `$.cart.lineItems['adfd6b06-4a24-4f5f-9f4b-ea21f4432dd4']`.
  *
- * @private
+ * @publicDocs
  */
 export type CartLineItemTarget = `$.cart.lineItems['${string}']`;
 
-/** @private */
+/**
+ * A target that a `cartvalidations` interceptor can use: the whole cart or
+ * one cart line item.
+ *
+ * @publicDocs
+ */
 export type CartValidationTarget = CartTarget | CartLineItemTarget;
 
 /**
  * Targets the payment attempt being intercepted.
  *
- * @private
+ * @publicDocs
  */
 export type PaymentTarget = '$.payment';
 
-/** @private */
+/**
+ * A target that a `paymentvalidations` interceptor can use. The only
+ * supported target is the payment attempt.
+ *
+ * @publicDocs
+ */
 export type PaymentValidationTarget = PaymentTarget;
 
 /**
  * Where a validation applies, as an enumerated token. Targets are matched
  * as exact strings, never evaluated as JSON paths.
  *
- * @private
+ * @publicDocs
  */
 export type ValidationTarget = CartValidationTarget | PaymentValidationTarget;
 
 /**
  * Maps POS interceptable workflow names to their valid validation targets.
  *
- * @private
+ * @publicDocs
  */
 interface ValidationTargetMap {
+  /** The targets that a `cartvalidations` interceptor can return. */
   [POS_INTERCEPT_NAMES.CART_VALIDATIONS]: CartValidationTarget;
+  /** The targets that a `paymentvalidations` interceptor can return. */
   [POS_INTERCEPT_NAMES.PAYMENT_VALIDATIONS]: PaymentValidationTarget;
 }
 
@@ -178,28 +200,30 @@ interface ValidationTargetMap {
  * The interceptor callback for a POS interceptable workflow, keyed by the
  * workflow name so the event and its valid validation targets stay paired.
  *
- * @private
+ * @publicDocs
  */
 export type ShopifyInterceptor<K extends keyof ShopifyInterceptMap> = (
   event: ShopifyInterceptMap[K],
 ) => InterceptResult<ValidationTargetMap[K]>;
 
 /**
- * The result an interceptor returns. An empty `operations` list allows the
- * workflow; an `ERROR` validation blocks it.
+ * The result an interceptor returns. An empty `operations` list adds no
+ * findings from this interceptor and doesn't remove or override findings from
+ * other interceptors.
  *
- * @private
+ * @publicDocs
  */
 export interface InterceptResult<
   TTarget extends ValidationTarget = ValidationTarget,
 > {
+  /** The operations to apply. Each operation can add one validation finding. */
   operations: Operation<TTarget>[];
 }
 
 /**
  * A single host operation produced by an interceptor.
  *
- * @private
+ * @publicDocs
  */
 export interface Operation<
   TTarget extends ValidationTarget = ValidationTarget,
@@ -207,31 +231,37 @@ export interface Operation<
   validationAdd?: ValidationAdd<TTarget>;
 }
 
-/** @private */
+/**
+ * The severity of a validation. `ERROR` can block the workflow when blocking
+ * is declared and allowed by the store. `WARNING` never blocks.
+ *
+ * @publicDocs
+ */
 export type ValidationLevel = 'WARNING' | 'ERROR';
 
 /**
  * Adds a validation to the workflow being intercepted.
  *
- * @private
+ * @publicDocs
  */
 export interface ValidationAdd<
   TTarget extends ValidationTarget = ValidationTarget,
 > {
-  /** `ERROR` blocks the workflow. `WARNING` does not. */
+  /** `ERROR` creates a finding labeled `Required` only when blocking is declared and allowed by the store. Otherwise, it creates a finding labeled `Recommended`. `WARNING` always creates a finding labeled `Recommended`. */
   level: ValidationLevel;
 
   /**
-   * Stable identifier for this validation. Handles are namespaced per
-   * extension and may repeat across targets: the same handle on two line
-   * items is two validations.
+   * Stable identifier for this validation, namespaced per extension. Each
+   * handle must be unique within one `operations` array, even across
+   * different targets. A result that repeats a handle is rejected. To flag
+   * several line items, include the line item `uuid` in each handle.
    */
   handle: string;
 
   /**
    * Locates the data the validation applies to; the host decides where it
    * renders. Omitted or unrecognized targets fall back to the event's root
-   * scope (`$.cart` / `$.payment`) — the validation still applies, rendered
+   * scope (`$.cart` / `$.payment`). The validation still applies, rendered
    * less specifically.
    *
    * Line item uuids are only valid within the event that delivered them:
@@ -246,4 +276,5 @@ export type {
   TransactionCompleteEvent,
   CashTrackingSessionStartEvent,
   CashTrackingSessionCompleteEvent,
+  ScanEvent,
 };

package/src/surfaces/point-of-sale/extension-targets.ts

@@ -52,19 +52,19 @@ export interface RenderExtensionTargets {
   /**
    * Renders a single interactive tile component on the POS home screen's smart grid. The tile appears once during home screen initialization and remains persistent until navigation occurs. Use this target for high-frequency actions, status displays, or entry points to workflows that merchants need daily.
    *
-   * Extensions at this target can dynamically update properties like enabled state and badge values in response to cart changes or device conditions. Tiles typically invoke `shopify.action.presentModal()` to launch the companion modal for complete workflows.
+   * Extensions at this target can dynamically update properties like enabled state and badge values in response to cart changes or device conditions. Tiles typically invoke `shopify.action.presentModal()` to launch the companion modal for complete workflows. Tiles can also open the connected cash drawer through the Cash Drawer API.
    */
   'pos.home.tile.render': RenderExtension<
-    StandardApi<'pos.home.tile.render'> & ActionApi & CartApi,
+    StandardApi<'pos.home.tile.render'> & ActionApi & CartApi & CashDrawerApi,
     SmartGridComponents
   >;
   /**
    * Renders a full-screen modal interface launched from smart grid tiles. The modal appears when users tap a companion tile. Use this target for complete workflow experiences that require more space and functionality than the tile interface provides, such as multi-step processes, detailed information displays, or complex user interactions.
    *
-   * Extensions at this target support full navigation hierarchies with multiple screens, scroll views, and interactive components to handle sophisticated workflows.
+   * Extensions at this target support full navigation hierarchies with multiple screens, scroll views, and interactive components to handle sophisticated workflows, and can open the connected cash drawer through the Cash Drawer API.
    */
   'pos.home.modal.render': RenderExtension<
-    ActionTargetApi<'pos.home.modal.render'> & CartApi,
+    ActionTargetApi<'pos.home.modal.render'> & CartApi & CashDrawerApi,
     BasicComponents
   >;
   /**

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

@@ -44,8 +44,6 @@ export interface BackgroundShopifyGlobal extends ShopifyGlobal {
   /**
    * Register an interceptor for a POS host workflow that can be blocked.
    * Returns a function that unregisters the interceptor.
-   *
-   * @private
    */
   intercept<K extends keyof ShopifyInterceptMap>(
     type: K,

package/src/surfaces/point-of-sale/pos-list-template.ts

@@ -0,0 +1,351 @@
+import htm from 'htm';
+
+import type {
+  POSListItemTemplate,
+  POSListTemplateNode,
+  POSListTemplateProp,
+  POSListTemplateSegment,
+  POSListTemplates,
+} from './components/POSList';
+
+export type {
+  POSListItemTemplate,
+  POSListTemplateNode,
+  POSListTemplateProp,
+  POSListTemplateSegment,
+  POSListTemplates,
+};
+
+/**
+ * The tagged template that compiles `<s-pos-list-item>` markup into the
+ * `itemTemplates` value `<s-pos-list>` accepts. Templates are static: the
+ * result contains no functions. Compilation and validation happen when the
+ * helper executes, not during the extension build. Define templates at module
+ * scope to compile once per module execution.
+ * Invalid templates throw synchronously and return no partial collection.
+ * An uncaught module-scope exception aborts module evaluation; catch the helper
+ * invocation to recover explicitly. There is no automatic list-only fallback.
+ *
+ * @publicDocs
+ */
+export type POSListTemplateTag = (
+  strings: TemplateStringsArray,
+  ...values: never[]
+) => POSListTemplates;
+
+const ITEM_TAG = 's-pos-list-item';
+const LIST_TAG = 's-pos-list';
+const PATH_PATTERN = /^[\w.]+$/;
+const EVENT_PROP_PATTERN = /^on/i;
+const BIND_PREFIX = 'bind:';
+/** `{{#if path}}`, `{{/if}}`, or `{{path}}`; anything else inside `{{ }}` is unsupported. */
+const EXPRESSION_PATTERN = /\{\{\s*(?:#if\s+([\w.]+)|(\/if)|([\w.]+))\s*\}\}/g;
+const ANY_EXPRESSION_PATTERN = /\{\{([\s\S]*?)\}\}/g;
+
+interface RawElement {
+  tag: string;
+  props: Record<string, unknown>;
+  children: unknown[];
+}
+
+type Token =
+  | {kind: 'text'; value: string}
+  | {kind: 'path'; path: string}
+  | {kind: 'if'; path: string}
+  | {kind: 'endif'}
+  | {kind: 'element'; element: RawElement};
+
+function fail(message: string): never {
+  throw new Error(`posListTemplate: ${message}`);
+}
+
+function isRawElement(value: unknown): value is RawElement {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'tag' in value &&
+    'props' in value &&
+    'children' in value
+  );
+}
+
+function createRawElement(
+  type: unknown,
+  props: Record<string, unknown> | null,
+  ...children: unknown[]
+): RawElement {
+  if (typeof type !== 'string') {
+    fail('interpolated values are not supported; templates must be static');
+  }
+  return {tag: type, props: props ?? {}, children};
+}
+
+const parse = htm.bind<RawElement>(createRawElement);
+
+/**
+ * Splits a string into literal and `{{path}}` segments. Used for attribute
+ * values, where block expressions have no meaning.
+ */
+function parseSegments(value: string): POSListTemplateSegment[] {
+  const segments: POSListTemplateSegment[] = [];
+  let lastIndex = 0;
+  for (const match of value.matchAll(ANY_EXPRESSION_PATTERN)) {
+    const expression = match[1]!.trim();
+    if (!PATH_PATTERN.test(expression)) {
+      if (expression.startsWith('#if') || expression === '/if') {
+        fail(
+          `{{#if}} is not supported inside an attribute value: "${match[0]}"`,
+        );
+      }
+      fail(`unsupported template expression "${match[0]}"`);
+    }
+    const index = match.index ?? 0;
+    if (index > lastIndex) {
+      segments.push(value.slice(lastIndex, index));
+    }
+    segments.push({path: expression});
+    lastIndex = index + match[0].length;
+  }
+  if (lastIndex < value.length) {
+    segments.push(value.slice(lastIndex));
+  }
+  return segments;
+}
+
+function tokenizeText(value: string, tokens: Token[]): void {
+  let lastIndex = 0;
+  for (const match of value.matchAll(ANY_EXPRESSION_PATTERN)) {
+    const index = match.index ?? 0;
+    if (index > lastIndex) {
+      tokens.push({kind: 'text', value: value.slice(lastIndex, index)});
+    }
+    EXPRESSION_PATTERN.lastIndex = 0;
+    const expression = EXPRESSION_PATTERN.exec(match[0]);
+    if (expression === null || expression[0].length !== match[0].length) {
+      fail(`unsupported template expression "${match[0]}"`);
+    }
+    const [, ifPath, endIf, path] = expression;
+    if (ifPath !== undefined) {
+      tokens.push({kind: 'if', path: ifPath});
+    } else if (endIf !== undefined) {
+      tokens.push({kind: 'endif'});
+    } else if (path !== undefined) {
+      tokens.push({kind: 'path', path});
+    }
+    lastIndex = index + match[0].length;
+  }
+  if (lastIndex < value.length) {
+    tokens.push({kind: 'text', value: value.slice(lastIndex)});
+  }
+}
+
+function tokenize(rawChildren: unknown[]): Token[] {
+  const tokens: Token[] = [];
+  for (const child of rawChildren.flat()) {
+    if (typeof child === 'string') {
+      if (child.trim().length > 0) {
+        tokenizeText(child, tokens);
+      }
+    } else if (isRawElement(child)) {
+      tokens.push({kind: 'element', element: child});
+    } else if (child !== null && child !== undefined && child !== false) {
+      fail('interpolated values are not supported; templates must be static');
+    }
+  }
+  return tokens;
+}
+
+function compileProp(
+  name: string,
+  value: unknown,
+  props: Record<string, POSListTemplateProp>,
+): void {
+  const isBinding = name.startsWith(BIND_PREFIX);
+  const propName = isBinding ? name.slice(BIND_PREFIX.length) : name;
+  if (EVENT_PROP_PATTERN.test(propName)) {
+    fail(
+      `event handlers are not supported in templates; use onRowClick on <${LIST_TAG}>`,
+    );
+  }
+  if (isBinding) {
+    if (typeof value !== 'string' || !PATH_PATTERN.test(value)) {
+      fail(`${name} must name a row field path`);
+    }
+    if (propName in props) {
+      fail(`"${propName}" is set both as an attribute and through ${name}`);
+    }
+    props[propName] = {kind: 'field', path: value};
+    return;
+  }
+  if (typeof value === 'string') {
+    props[name] = value.includes('{{')
+      ? {kind: 'segments', segments: parseSegments(value)}
+      : {kind: 'literal', value};
+    return;
+  }
+  if (typeof value === 'boolean') {
+    props[name] = {kind: 'literal', value};
+    return;
+  }
+  fail('interpolated values are not supported; templates must be static');
+}
+
+function compileElement(
+  element: RawElement,
+  parentIfPath?: string,
+): POSListTemplateNode {
+  if (element.tag === ITEM_TAG || element.tag === LIST_TAG) {
+    fail(`<${element.tag}> can only appear as a template root`);
+  }
+  const props: Record<string, POSListTemplateProp> = {};
+  // Plain attributes first so `bind:` can detect a collision with one.
+  const entries = Object.entries(element.props);
+  for (const [name, value] of entries) {
+    if (!name.startsWith(BIND_PREFIX)) {
+      compileProp(name, value, props);
+    }
+  }
+  for (const [name, value] of entries) {
+    if (name.startsWith(BIND_PREFIX)) {
+      compileProp(name, value, props);
+    }
+  }
+  const node: POSListTemplateNode = {kind: 'element', tag: element.tag, props};
+  const children = compileChildren(element.children, false, parentIfPath);
+  if (children.length > 0) {
+    node.children = children;
+  }
+  return node;
+}
+
+function compileChildren(
+  rawChildren: unknown[],
+  atRoot: boolean,
+  parentIfPath?: string,
+): POSListTemplateNode[] {
+  const nodes: POSListTemplateNode[] = [];
+  let pendingText: POSListTemplateSegment[] = [];
+  let openIf: {path: string; children: POSListTemplateNode[]} | undefined;
+
+  const target = () => (openIf ? openIf.children : nodes);
+  const flushText = () => {
+    if (pendingText.length === 0) {
+      return;
+    }
+    if (atRoot) {
+      fail('text must be inside a component such as <s-text>');
+    }
+    target().push({kind: 'text', segments: pendingText});
+    pendingText = [];
+  };
+
+  for (const token of tokenize(rawChildren)) {
+    switch (token.kind) {
+      case 'text':
+        pendingText.push(token.value);
+        break;
+      case 'path':
+        pendingText.push({path: token.path});
+        break;
+      case 'if': {
+        flushText();
+        const enclosingIfPath = openIf?.path ?? parentIfPath;
+        if (enclosingIfPath !== undefined) {
+          fail(
+            `{{#if}} cannot be nested: {{#if ${token.path}}} inside {{#if ${enclosingIfPath}}}`,
+          );
+        }
+        openIf = {path: token.path, children: []};
+        break;
+      }
+      case 'endif':
+        flushText();
+        if (!openIf) {
+          fail('{{/if}} without a matching {{#if}}');
+        }
+        nodes.push({kind: 'if', path: openIf.path, children: openIf.children});
+        openIf = undefined;
+        break;
+      case 'element':
+        flushText();
+        target().push(
+          compileElement(token.element, openIf?.path ?? parentIfPath),
+        );
+        break;
+    }
+  }
+  flushText();
+  if (openIf) {
+    fail(`{{#if ${openIf.path}}} is missing its {{/if}}`);
+  }
+  return nodes;
+}
+
+function compileRoot(root: unknown, seen: Set<string>): POSListItemTemplate {
+  if (!isRawElement(root) || root.tag !== ITEM_TAG) {
+    fail(`every template root must be an <${ITEM_TAG} templateId="…"> element`);
+  }
+  let templateId: string | undefined;
+  let type: POSListItemTemplate['type'] = 'button';
+  for (const [name, value] of Object.entries(root.props)) {
+    if (name === 'templateId') {
+      if (typeof value !== 'string' || value.length === 0) {
+        fail(`<${ITEM_TAG}> requires a literal, non-empty templateId`);
+      }
+      templateId = value;
+    } else if (name === 'type') {
+      if (value !== 'button' && value !== 'text') {
+        fail(
+          `<${ITEM_TAG}> type must be "button" or "text", got ${JSON.stringify(
+            value,
+          )}`,
+        );
+      }
+      type = value;
+    } else {
+      fail(
+        `<${ITEM_TAG}> does not accept a "${name}" attribute; only templateId and type are allowed`,
+      );
+    }
+  }
+  if (templateId === undefined) {
+    fail(`<${ITEM_TAG}> requires a literal, non-empty templateId`);
+  }
+  if (seen.has(templateId)) {
+    fail(`duplicate templateId "${templateId}"`);
+  }
+  seen.add(templateId);
+  return {templateId, type, children: compileChildren(root.children, true)};
+}
+
+/**
+ * Compiles `<s-pos-list-item>` markup into the `itemTemplates` value for
+ * `<s-pos-list>`.
+ *
+ * Compilation and validation happen when this helper executes, not during the
+ * extension build. Define templates at module scope to compile once per module
+ * execution.
+ * Invalid templates throw synchronously and return no partial collection.
+ * An uncaught module-scope exception aborts module evaluation; catch the helper
+ * invocation to recover explicitly. There is no automatic list-only fallback.
+ *
+ * Inside a template, `{{path}}` interpolates a row field as text, `bind:prop="path"`
+ * passes a row field to a component prop with its own type, and
+ * `{{#if path}}…{{/if}}` renders its content only when the field is truthy.
+ * Event handlers, interpolated values, and any other `{{…}}` expression are
+ * rejected when the template is compiled.
+ *
+ * @publicDocs
+ */
+export const posListTemplate: POSListTemplateTag = (strings, ...values) => {
+  if (values.length > 0) {
+    fail('interpolated values are not supported; templates must be static');
+  }
+  const parsed: unknown = parse(strings);
+  const roots = Array.isArray(parsed) ? parsed : [parsed];
+  const seen = new Set<string>();
+  const templates = roots
+    .filter((root) => !(typeof root === 'string' && root.trim().length === 0))
+    .map((root) => compileRoot(root, seen));
+  return {templates};
+};