[5/7] Add s-pos-list web component types and the posListTemplate compiler by ajanth-u · Pull Request #4690 · Shopify/ui-extensions

ajanth-u · 2026-09-12T15:05:52Z

What

Adds <s-pos-list> for POS API version 2026-10 and the posListTemplate tagged template that compiles its row markup. This is the templated candidate for GSD #51755; the legacy-parity alternative is #4661 (unmodified, held as contingency). Exactly one of the two should merge.

Companion PRs: World #2061117 (ui-api-design contract), #2061112 → #2061124 → #2061132 (pos-mobile host stack), Shopify/pos-e2e-ui-extension (sandbox screen, follows), World shopify-dev docs (follows).

Design

rows is plain data ({id, templateFor, ...fields}) and itemTemplates is a compiled AST produced once in the extension bundle by posListTemplate:

const itemTemplates = posListTemplate`
  <s-pos-list-item templateId="section-header" type="text">
    <s-heading>{{title}}</s-heading>
  </s-pos-list-item>
  <s-pos-list-item templateId="product">
    <s-stack direction="inline">
      <s-image src="{{image.src}}" alt="{{name}}" />
      <s-text>{{name}}</s-text>
      {{#if onSale}}<s-badge tone="success">Sale</s-badge>{{/if}}
      <s-switch bind:checked="active" />
    </s-stack>
  </s-pos-list-item>
`;
<s-pos-list rows={rows} itemTemplates={itemTemplates} onRowClick={(e) => e.detail.item.id} />

POS hydrates one template copy per FlashList-mounted row, so no extension code runs while scrolling and no functions cross the bridge (no Shopify/extensibility change needed).

Output is stamped with this package's API version (version: '2026-10'); POS renders templates only for an extension declaring the same API version and reports a mismatch by name (itemTemplates were compiled for API version X but this extension runs API version Y).

Grammar: {{path}} in text; {{path}} inside an attribute (always a string); bind:prop="path" (the only typed binding); {{#if path}}…{{/if}} (no nesting, no else). Compilation and validation happen when the helper executes, not during the extension build. Define templates at module scope to compile once per module execution. Rejected by the helper with posListTemplate:-prefixed errors: on* attributes (including bind:onClick), ${} interpolation of any kind, #each/other expressions, nested/unbalanced #if (including nesting through component children), #if inside an attribute, text directly under <s-pos-list-item>, non-item roots, nested s-pos-list-item/s-pos-list, missing/duplicate templateId, unknown type, any other root attribute.

Changes

src/surfaces/point-of-sale/pos-list-template.ts — the compiler (htm-based; htm becomes a direct dependency).
src/surfaces/point-of-sale.ts — exports posListTemplate plus POSListTemplateTag, POSListTemplates, POSListItemTemplate, POSListTemplateNode, POSListTemplateProp, POSListTemplateSegment, POSListRow, POSListRowClickEvent.
components/POSList.d.ts (generated from pos-mobile meta.ts via pnpm build-extension-components:publish 2026-10, with the generator fixes from World #2061112) and the POSList blocks merged into components.d.ts. POSListRowClickEvent carries {item, index} in detail, the only event field POS's RemoteDOM bridge forwards to an extension; the ui-api-design contract (World #2061117) declares item/index on the event, and POS exposes them once the bridge forwards custom event properties. POSListTemplates.version is the compiling API version string (`${number}-${number}` | 'unstable'). Only POSList additions are included; the pre-existing drift between the generator output and this repo's components.d.ts/components-shared.d.ts is left alone.
components/targets/StandardComponents.ts — | 'POSList'.
components/POSList/examples/{default,incremental-loading}.jsx.
docs/.../2026-10/{generated_docs_data_v2.json,targets.json} regenerated with build-docs.mjs 2026-10.
.changeset/pos-list-template-component.md (minor).

Verification

yarn build, yarn type-check green; build/esm/surfaces/point-of-sale.mjs exports posListTemplate.
loom test packages/ui-extensions/src/surfaces/point-of-sale/tests/pos-list-template — 19 tests: exact AST output for text placeholders, {{#if}} blocks, bind:, attribute segments, valueless attributes, type="text"; and every rejection above with its literal message.
eslint clean on the changed files.

Co-authored by AI.

ajanth-u · 2026-09-12T15:07:40Z

/snapit

shopify-github-actions-access · 2026-09-12T15:09:22Z