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

package/build/esm/surfaces/point-of-sale/pos-list-template.mjs

@@ -0,0 +1,331 @@
+import htm from 'htm';
+
+/**
+ * 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
+ */
+
+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;
+function fail(message) {
+  throw new Error(`posListTemplate: ${message}`);
+}
+function isRawElement(value) {
+  return typeof value === 'object' && value !== null && 'tag' in value && 'props' in value && 'children' in value;
+}
+function createRawElement(type, props, ...children) {
+  if (typeof type !== 'string') {
+    fail('interpolated values are not supported; templates must be static');
+  }
+  return {
+    tag: type,
+    props: props !== null && props !== void 0 ? props : {},
+    children
+  };
+}
+const parse = htm.bind(createRawElement);
+
+/**
+ * Splits a string into literal and `{{path}}` segments. Used for attribute
+ * values, where block expressions have no meaning.
+ */
+function parseSegments(value) {
+  const segments = [];
+  let lastIndex = 0;
+  for (const match of value.matchAll(ANY_EXPRESSION_PATTERN)) {
+    var _match$index;
+    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 = match.index) !== null && _match$index !== void 0 ? _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, tokens) {
+  let lastIndex = 0;
+  for (const match of value.matchAll(ANY_EXPRESSION_PATTERN)) {
+    var _match$index2;
+    const index = (_match$index2 = match.index) !== null && _match$index2 !== void 0 ? _match$index2 : 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) {
+  const tokens = [];
+  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, value, props) {
+  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, parentIfPath) {
+  if (element.tag === ITEM_TAG || element.tag === LIST_TAG) {
+    fail(`<${element.tag}> can only appear as a template root`);
+  }
+  const props = {};
+  // 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 = {
+    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, atRoot, parentIfPath) {
+  var _openIf$path2, _openIf2;
+  const nodes = [];
+  let pendingText = [];
+  let openIf;
+  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':
+        {
+          var _openIf$path, _openIf;
+          flushText();
+          const enclosingIfPath = (_openIf$path = (_openIf = openIf) === null || _openIf === void 0 ? void 0 : _openIf.path) !== null && _openIf$path !== void 0 ? _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$path2 = (_openIf2 = openIf) === null || _openIf2 === void 0 ? void 0 : _openIf2.path) !== null && _openIf$path2 !== void 0 ? _openIf$path2 : parentIfPath));
+        break;
+    }
+  }
+  flushText();
+  if (openIf) {
+    fail(`{{#if ${openIf.path}}} is missing its {{/if}}`);
+  }
+  return nodes;
+}
+function compileRoot(root, seen) {
+  if (!isRawElement(root) || root.tag !== ITEM_TAG) {
+    fail(`every template root must be an <${ITEM_TAG} templateId="…"> element`);
+  }
+  let templateId;
+  let 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
+ */
+const posListTemplate = (strings, ...values) => {
+  if (values.length > 0) {
+    fail('interpolated values are not supported; templates must be static');
+  }
+  const parsed = parse(strings);
+  const roots = Array.isArray(parsed) ? parsed : [parsed];
+  const seen = new Set();
+  const templates = roots.filter(root => !(typeof root === 'string' && root.trim().length === 0)).map(root => compileRoot(root, seen));
+  return {
+    templates
+  };
+};
+
+export { posListTemplate };

package/build/esm/surfaces/point-of-sale.mjs

@@ -1,2 +1,3 @@
 export { POS_EVENT_NAMES, POS_INTERCEPT_NAMES } from './point-of-sale/events.mjs';
+export { posListTemplate } from './point-of-sale/pos-list-template.mjs';
 export { StorageError } from './point-of-sale/types/storage.mjs';

package/build/esnext/surfaces/customer-account/preact/authenticated-account.esnext

@@ -2,7 +2,7 @@ import { useApi } from './api.esnext';
 import { useSubscription } from './subscription.esnext';
 
 /**
- * Returns the current authenticated `Customer`.
+ * Returns the current `AuthenticatedAccountCustomer`.
  *
  * The value is `undefined` if the customer isn't authenticated.
  */

package/build/esnext/surfaces/point-of-sale/events.esnext

@@ -7,7 +7,8 @@
 const POS_EVENT_NAMES = {
   TRANSACTION_COMPLETE: 'transactioncomplete',
   CASH_TRACKING_SESSION_START: 'cashtrackingsessionstart',
-  CASH_TRACKING_SESSION_COMPLETE: 'cashtrackingsessioncomplete'
+  CASH_TRACKING_SESSION_COMPLETE: 'cashtrackingsessioncomplete',
+  SCAN: 'scan'
 };
 
 /**
@@ -35,26 +36,26 @@ const POS_INTERCEPT_NAMES = {
  *
  * Used as the generic type parameter for `shopify.intercept`.
  *
- * @private
+ * @publicDocs
  */
 
 /**
  * The data carried by a `cartvalidations` event.
  *
- * @private
+ * @publicDocs
  */
 
 /**
  * The event a `cartvalidations` interceptor receives. Carries a snapshot of
  * the POS cart taken when the event was produced.
  *
- * @private
+ * @publicDocs
  */
 
 /**
  * The kind of payment method being attempted.
  *
- * @private
+ * @publicDocs
  */
 
 /**
@@ -64,7 +65,7 @@ const POS_INTERCEPT_NAMES = {
  * disambiguates method types a shop can have several of (for example custom
  * payment methods) as they become interceptable.
  *
- * @private
+ * @publicDocs
  */
 
 /**
@@ -72,77 +73,93 @@ const POS_INTERCEPT_NAMES = {
  * attempt's payment method and amount; split payments produce one event per
  * tender, each with its own amount.
  *
- * @private
+ * @publicDocs
  */
 
 /**
  * The data carried by a `paymentvalidations` event.
  *
- * @private
+ * @publicDocs
  */
 
 /**
  * Targets the whole cart rather than a specific line item.
  *
- * @private
+ * @publicDocs
  */
 
 /**
  * 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
  */
 
-/** @private */
+/**
+ * A target that a `cartvalidations` interceptor can use: the whole cart or
+ * one cart line item.
+ *
+ * @publicDocs
+ */
 
 /**
  * Targets the payment attempt being intercepted.
  *
- * @private
+ * @publicDocs
  */
 
-/** @private */
+/**
+ * A target that a `paymentvalidations` interceptor can use. The only
+ * supported target is the payment attempt.
+ *
+ * @publicDocs
+ */
 
 /**
  * Where a validation applies, as an enumerated token. Targets are matched
  * as exact strings, never evaluated as JSON paths.
  *
- * @private
+ * @publicDocs
  */
 
 /**
  * Maps POS interceptable workflow names to their valid validation targets.
  *
- * @private
+ * @publicDocs
  */
 
 /**
  * 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
  */
 
 /**
- * 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
  */
 
 /**
  * A single host operation produced by an interceptor.
  *
- * @private
+ * @publicDocs
  */
 
-/** @private */
+/**
+ * The severity of a validation. `ERROR` can block the workflow when blocking
+ * is declared and allowed by the store. `WARNING` never blocks.
+ *
+ * @publicDocs
+ */
 
 /**
  * Adds a validation to the workflow being intercepted.
  *
- * @private
+ * @publicDocs
  */
 
 export { POS_EVENT_NAMES, POS_INTERCEPT_NAMES };