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

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

@@ -0,0 +1,306 @@
+import {posListTemplate} from '../pos-list-template';
+import type {POSListTemplateNode} from '../pos-list-template';
+
+function item(markup: string, attributes = 'templateId="p"') {
+  return `<s-pos-list-item ${attributes}>${markup}</s-pos-list-item>`;
+}
+
+function compileItem(markup: string, attributes?: string) {
+  return posListTemplate(
+    Object.assign([item(markup, attributes)], {
+      raw: [item(markup, attributes)],
+    }),
+  );
+}
+
+function firstChild(markup: string): POSListTemplateNode {
+  const [template] = compileItem(markup).templates;
+  const [child] = template!.children;
+  return child!;
+}
+
+describe('posListTemplate', () => {
+  describe('roots', () => {
+    it('compiles text with a path placeholder into text segments', () => {
+      const result = posListTemplate`<s-pos-list-item templateId="p"><s-text>Hi {{name}}</s-text></s-pos-list-item>`;
+
+      expect(result).toStrictEqual({
+        templates: [
+          {
+            templateId: 'p',
+            type: 'button',
+            children: [
+              {
+                kind: 'element',
+                tag: 's-text',
+                props: {},
+                children: [{kind: 'text', segments: ['Hi ', {path: 'name'}]}],
+              },
+            ],
+          },
+        ],
+      });
+    });
+
+    it('compiles several roots and honours type="text"', () => {
+      const result = posListTemplate`
+        <s-pos-list-item templateId="header" type="text"><s-heading>{{title}}</s-heading></s-pos-list-item>
+        <s-pos-list-item templateId="product"><s-text>{{name}}</s-text></s-pos-list-item>
+      `;
+
+      expect(
+        result.templates.map(({templateId, type}) => ({templateId, type})),
+      ).toStrictEqual([
+        {templateId: 'header', type: 'text'},
+        {templateId: 'product', type: 'button'},
+      ]);
+    });
+
+    it('rejects an unknown type', () => {
+      expect(() =>
+        compileItem('<s-text>x</s-text>', 'templateId="p" type="link"'),
+      ).toThrow(
+        'posListTemplate: <s-pos-list-item> type must be "button" or "text", got "link"',
+      );
+    });
+
+    it('rejects a missing, empty, or duplicate templateId', () => {
+      expect(() => compileItem('<s-text>x</s-text>', 'type="text"')).toThrow(
+        'posListTemplate: <s-pos-list-item> requires a literal, non-empty templateId',
+      );
+      expect(() => compileItem('<s-text>x</s-text>', 'templateId=""')).toThrow(
+        'posListTemplate: <s-pos-list-item> requires a literal, non-empty templateId',
+      );
+      expect(
+        () => posListTemplate`
+          <s-pos-list-item templateId="p"><s-text>a</s-text></s-pos-list-item>
+          <s-pos-list-item templateId="p"><s-text>b</s-text></s-pos-list-item>
+        `,
+      ).toThrow('posListTemplate: duplicate templateId "p"');
+    });
+
+    it('rejects other root attributes, non-item roots, and nested items', () => {
+      expect(() =>
+        compileItem('<s-text>x</s-text>', 'templateId="p" id="x"'),
+      ).toThrow(
+        'posListTemplate: <s-pos-list-item> does not accept a "id" attribute; only templateId and type are allowed',
+      );
+      expect(() => posListTemplate`<s-text>loose</s-text>`).toThrow(
+        'posListTemplate: every template root must be an <s-pos-list-item templateId="…"> element',
+      );
+      expect(() =>
+        compileItem(
+          '<s-pos-list-item templateId="q"><s-text>x</s-text></s-pos-list-item>',
+        ),
+      ).toThrow(
+        'posListTemplate: <s-pos-list-item> can only appear as a template root',
+      );
+      expect(() => compileItem('<s-pos-list rows="x"></s-pos-list>')).toThrow(
+        'posListTemplate: <s-pos-list> can only appear as a template root',
+      );
+    });
+
+    it('rejects text directly under the item root', () => {
+      expect(() => compileItem('{{label}}')).toThrow(
+        'posListTemplate: text must be inside a component such as <s-text>',
+      );
+      expect(() => compileItem('Plain text')).toThrow(
+        'posListTemplate: text must be inside a component such as <s-text>',
+      );
+      expect(() => compileItem('{{#if a}}{{label}}{{/if}}')).toThrow(
+        'posListTemplate: text must be inside a component such as <s-text>',
+      );
+    });
+
+    it('rejects interpolated values of any kind', () => {
+      // The tag's type already forbids interpolation; this exercises the runtime check JS callers hit.
+      const compileDynamic = posListTemplate as unknown as (
+        strings: TemplateStringsArray,
+        ...values: unknown[]
+      ) => unknown;
+      const dynamic = () => {};
+      const tag = 's-text';
+      expect(
+        () =>
+          compileDynamic`<s-pos-list-item templateId="p"><s-text onClick=${dynamic}>x</s-text></s-pos-list-item>`,
+      ).toThrow(
+        'posListTemplate: interpolated values are not supported; templates must be static',
+      );
+      expect(
+        () =>
+          compileDynamic`<s-pos-list-item templateId="p"><${tag}>x</${tag}></s-pos-list-item>`,
+      ).toThrow(
+        'posListTemplate: interpolated values are not supported; templates must be static',
+      );
+    });
+  });
+
+  describe('conditionals', () => {
+    it('compiles {{#if}} blocks into if nodes wrapping the sibling elements between the markers', () => {
+      const stack = firstChild(
+        '<s-stack>{{#if onSale}}<s-badge tone="success">Sale</s-badge>{{/if}}</s-stack>',
+      );
+
+      expect(stack).toStrictEqual({
+        kind: 'element',
+        tag: 's-stack',
+        props: {},
+        children: [
+          {
+            kind: 'if',
+            path: 'onSale',
+            children: [
+              {
+                kind: 'element',
+                tag: 's-badge',
+                props: {tone: {kind: 'literal', value: 'success'}},
+                children: [{kind: 'text', segments: ['Sale']}],
+              },
+            ],
+          },
+        ],
+      });
+    });
+
+    it('keeps text inside an if within a component', () => {
+      const text = firstChild(
+        '<s-text>{{#if a}}Yes {{label}}{{/if}} always</s-text>',
+      );
+
+      expect(text).toStrictEqual({
+        kind: 'element',
+        tag: 's-text',
+        props: {},
+        children: [
+          {
+            kind: 'if',
+            path: 'a',
+            children: [{kind: 'text', segments: ['Yes ', {path: 'label'}]}],
+          },
+          {kind: 'text', segments: [' always']},
+        ],
+      });
+    });
+
+    it('rejects a condition nested through component children', () => {
+      expect(() =>
+        compileItem(
+          '{{#if outer}}<s-box><s-stack>{{#if inner}}<s-text>Visible</s-text>{{/if}}</s-stack></s-box>{{/if}}',
+        ),
+      ).toThrow(/cannot be nested/);
+    });
+
+    it('allows a separate condition after an enclosing condition closes', () => {
+      const result = compileItem(
+        '{{#if first}}<s-box><s-text>First</s-text></s-box>{{/if}}<s-stack>{{#if second}}<s-text>Second</s-text>{{/if}}</s-stack>',
+      );
+
+      expect(result.templates[0]?.children).toMatchObject([
+        {
+          kind: 'if',
+          path: 'first',
+          children: [{kind: 'element', tag: 's-box'}],
+        },
+        {
+          kind: 'element',
+          tag: 's-stack',
+          children: [{kind: 'if', path: 'second'}],
+        },
+      ]);
+    });
+
+    it('rejects nested, unopened, unclosed, and unsupported block expressions', () => {
+      expect(() =>
+        compileItem(
+          '<s-stack>{{#if a}}{{#if b}}<s-text>x</s-text>{{/if}}{{/if}}</s-stack>',
+        ),
+      ).toThrow(
+        'posListTemplate: {{#if}} cannot be nested: {{#if b}} inside {{#if a}}',
+      );
+      expect(() => compileItem('<s-stack>{{/if}}</s-stack>')).toThrow(
+        'posListTemplate: {{/if}} without a matching {{#if}}',
+      );
+      expect(() =>
+        compileItem('<s-stack>{{#if a}}<s-text>x</s-text></s-stack>'),
+      ).toThrow('posListTemplate: {{#if a}} is missing its {{/if}}');
+      expect(() =>
+        compileItem(
+          '<s-stack>{{#each x}}<s-text>x</s-text>{{/each}}</s-stack>',
+        ),
+      ).toThrow(
+        'posListTemplate: unsupported template expression "{{#each x}}"',
+      );
+      expect(() => compileItem('<s-text>{{a + b}}</s-text>')).toThrow(
+        'posListTemplate: unsupported template expression "{{a + b}}"',
+      );
+    });
+  });
+
+  describe('props', () => {
+    it('compiles bind: attributes into typed field bindings', () => {
+      expect(firstChild('<s-switch bind:checked="active" />')).toStrictEqual({
+        kind: 'element',
+        tag: 's-switch',
+        props: {checked: {kind: 'field', path: 'active'}},
+      });
+    });
+
+    it('compiles placeholders inside attributes into string segments', () => {
+      expect(
+        firstChild('<s-image src="{{image.src}}" alt="{{label}} image" />'),
+      ).toStrictEqual({
+        kind: 'element',
+        tag: 's-image',
+        props: {
+          src: {kind: 'segments', segments: [{path: 'image.src'}]},
+          alt: {kind: 'segments', segments: [{path: 'label'}, ' image']},
+        },
+      });
+    });
+
+    it('keeps literal strings and valueless attributes as literals', () => {
+      expect(firstChild('<s-switch checked label="Wifi" />')).toStrictEqual({
+        kind: 'element',
+        tag: 's-switch',
+        props: {
+          checked: {kind: 'literal', value: true},
+          label: {kind: 'literal', value: 'Wifi'},
+        },
+      });
+    });
+
+    it.each([
+      'onClick="x"',
+      'onclick="x"',
+      'ONCLICK="{{handler}}"',
+      'OnClick="x"',
+      'bind:onClick="handler"',
+      'bind:onclick="handler"',
+      'bind:ONCLICK="handler"',
+      'bind:OnClick="handler"',
+    ])('rejects the event handler attribute %s', (attribute) => {
+      expect(() => compileItem(`<s-button ${attribute}>Go</s-button>`)).toThrow(
+        'posListTemplate: event handlers are not supported in templates; use onRowClick on <s-pos-list>',
+      );
+    });
+
+    it('rejects a bind: attribute that collides with a plain attribute or names an invalid path', () => {
+      expect(() =>
+        compileItem('<s-switch checked bind:checked="active" />'),
+      ).toThrow(
+        'posListTemplate: "checked" is set both as an attribute and through bind:checked',
+      );
+      expect(() => compileItem('<s-switch bind:checked="a b" />')).toThrow(
+        'posListTemplate: bind:checked must name a row field path',
+      );
+    });
+
+    it('rejects block expressions inside attribute values', () => {
+      expect(() =>
+        compileItem('<s-text tone="{{#if a}}critical{{/if}}">x</s-text>'),
+      ).toThrow(
+        'posListTemplate: {{#if}} is not supported inside an attribute value: "{{#if a}}"',
+      );
+    });
+  });
+});

package/src/surfaces/point-of-sale/types/base-transaction-complete.ts

@@ -19,6 +19,10 @@ export interface BaseTransactionComplete {
    * The unique numeric identifier for the Shopify order created by this transaction. This ID links the POS transaction to the order record in Shopify's system and can be used for order lookups, tracking, and API operations. Returns `undefined` for transactions that don't create orders (for example, reprints) or when order creation is pending.
    */
   orderId?: number;
+  /**
+   * The source identifier POS assigned to this transaction. Matches the `sourceIdentifier` of the order this transaction belongs to. Returns `undefined` when POS didn't assign one.
+   */
+  sourceIdentifier?: string;
   /**
    * The customer information if this transaction is associated with a customer account. Contains the customer ID for linking to customer records. Returns `undefined` for guest transactions where no customer was selected or when the transaction doesn't support customer association.
    */
@@ -31,6 +35,10 @@ export interface BaseTransactionComplete {
    * The total tax amount charged on this transaction as a `Money` object. This is the sum of all tax lines and represents the combined tax from all applicable tax jurisdictions and rules. Tax calculations are based on the location, products, customer, and tax settings configured in Shopify.
    */
   taxTotal: Money;
+  /**
+   * Whether the prices in this transaction include taxes (tax-inclusive pricing), rather than taxes being added on top. Matches the `taxesIncluded` field on the `Order` object in the GraphQL Admin API. Returns `undefined` when this information isn't available.
+   */
+  taxesIncluded?: boolean;
   /**
    * The subtotal amount before taxes and after discounts are applied, as a `Money` object. This represents the sum of all line item prices (quantity × unit price) minus any discounts, but before tax is added. This is the taxable base amount for most tax calculations.
    */

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

@@ -36,13 +36,6 @@ export interface Session {
    */
   locationId: number;
 
-  /**
-   * The staff ID of the staff member pinned into POS when the extension started. This may differ from the user ID if the pinned staff member is different from the logged in user.
-   *
-   * @deprecated Use `session.staffMember` on the Session API instead.
-   */
-  staffMemberId?: number;
-
   /**
    * The [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code associated with the location currently active on POS.
    */

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

@@ -3,3 +3,4 @@ export * from './point-of-sale/events';
 export * from './point-of-sale/extension-targets';
 export * from './point-of-sale/event/data';
 export * from './point-of-sale/event/output';
+export {posListTemplate} from './point-of-sale/pos-list-template';