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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shopify/ui-extensions",
-  "version": "2026.10.0-rc.8",
+  "version": "2026.10.0",
   "scripts": {
     "docs:admin": "node ./docs/surfaces/admin/build-docs.mjs",
     "docs:checkout": "bash ./docs/surfaces/checkout/build-docs.sh",
@@ -169,6 +169,7 @@
     }
   },
   "dependencies": {
+    "htm": "^3.1.1",
     "ts-morph": "^25.0.1"
   }
 }

package/src/shared.ts

@@ -853,16 +853,29 @@ export type CountryCode =
   | 'ZZ';
 
 /**
- * A buyer's country, identified by its ISO country code.
+ * An address input a country's address format carries. Flat fields
+ * (`address1`, `city`, `zip`, …) are written on the change's `address`; line
+ * components (`streetName`, `streetNumber`, `additionalInformation`,
+ * `district`, `subdistrict`) are written inside `addressLineComponents`, and
+ * are rejected as unknown properties if sent at the top level.
  */
-export interface Country {
-  /**
-   * The two-letter country code in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format.
-   *
-   * @example 'CA' for Canada, 'US' for United States.
-   */
-  isoCode: CountryCode;
-}
+export type AcceptedAddressInputField =
+  | 'additionalInformation'
+  | 'address1'
+  | 'address2'
+  | 'addressCode'
+  | 'city'
+  | 'company'
+  | 'countryCode'
+  | 'district'
+  | 'firstName'
+  | 'lastName'
+  | 'phone'
+  | 'provinceCode'
+  | 'streetName'
+  | 'streetNumber'
+  | 'subdistrict'
+  | 'zip';
 
 // For instructions on how to update this list see: https://github.com/Shopify/checkout-web/pull/39534
 /**
@@ -931,18 +944,6 @@ export type StorefrontApiVersion =
   | '2026-07'
   | '2026-10';
 
-/**
- * A buyer's country, identified by its ISO country code.
- */
-export interface Country {
-  /**
-   * The two-letter country code in [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format.
-   *
-   * @example 'CA' for Canada, 'US' for United States.
-   */
-  isoCode: CountryCode;
-}
-
 /**
  * An error returned by the Storefront GraphQL API. Contains a human-readable `message` and an `extensions` object with the request ID and error code for debugging.
  */

package/src/surfaces/admin/api/picker/picker.ts

@@ -58,7 +58,10 @@ export type Tone = 'info' | 'success' | 'warning' | 'critical';
  * The progress state for picker badges showing completion status. Use this to indicate how complete an item is: `'incomplete'` for not started, `'partiallyComplete'` for in progress, or `'complete'` for finished.
  * @publicDocs
  */
-export type Progress = 'incomplete' | 'partiallyComplete' | 'complete';
+export type PickerBadgeProgress =
+  | 'incomplete'
+  | 'partiallyComplete'
+  | 'complete';
 
 /**
  * A single data point that can appear in a picker table cell. Can be text, a number, or undefined if the cell should be empty.
@@ -75,7 +78,7 @@ export interface PickerBadge {
   /** The visual tone indicating status or importance. Choose a tone that matches the badge's meaning. */
   tone?: Tone;
   /** The progress indicator for the badge. Use this to show completion status for items that have progress states. */
-  progress?: Progress;
+  progress?: PickerBadgeProgress;
 }
 
 /**

package/src/surfaces/admin/components/AdminAction.d.ts

@@ -1,151 +1,105 @@
-/** VERSION: 1.25.0 **/
+/** VERSION: 2.26.1 **/
 /* eslint-disable import/extensions */
 
 /* eslint-disable @typescript-eslint/no-namespace */
 
 // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment
 /// <reference lib="DOM" />
-import type {ComponentChildren, AdminActionProps$1} from './shared.d.ts';
+import type {
+  ComponentChildren,
+  AdminActionProps$1,
+  PreactCustomElement,
+  RenderImpl,
+} from './shared.d.ts';
+import * as preact$1 from 'preact';
+import {ReactNode, RefAttributes} from 'react';
 
 /**
- * The properties for the admin action component. These properties configure the heading and loading state of the admin action extension interface.
+ * Configure the following properties on the admin action component.
  * @publicDocs
  */
 export interface AdminActionProps
-  extends Pick<AdminActionProps$1, 'heading' | 'loading'> {}
+  extends Pick<AdminActionProps$1, 'heading' | 'loading'> {
+  /**
+   * Whether the action is in a loading state, such as during initial page load or when the action is being opened.
+   * When `true`, the action is in an inert state that prevents user interaction.
+   *
+   * @default false
+   */
+  loading?: AdminActionProps$1['loading'];
+}
 
-declare const tagName = 's-admin-action';
+export type ReactIntrinsicElementChildren<PreactProps extends object> =
+  'children' extends keyof PreactProps
+    ? {
+        children?: ReactNode;
+      }
+    : Record<never, never>;
+export type ReactIntrinsicElementProps<
+  PreactProps extends object,
+  ElementType,
+> = Omit<PreactProps, 'children' | 'key' | 'ref' | 'slot'> &
+  ReactIntrinsicElementChildren<PreactProps> &
+  RefAttributes<ElementType> & {
+    slot?: Lowercase<string>;
+  };
+export type ReactIntrinsicElements = {
+  [Tag in Exclude<
+    Extract<keyof preact$1.createElement.JSX.IntrinsicElements, `s-${string}`>,
+    `s-test-${string}`
+  >]: ReactIntrinsicElementProps<
+    preact$1.createElement.JSX.IntrinsicElements[Tag],
+    Tag extends keyof HTMLElementTagNameMap
+      ? HTMLElementTagNameMap[Tag]
+      : HTMLElement
+  >;
+};
+declare module 'react' {
+  namespace JSX {
+    interface IntrinsicElements extends ReactIntrinsicElements {}
+  }
+}
 
-/**
- * The JSX props for the admin action component. These properties extend `AdminActionProps` with slots for primary and secondary action buttons that merchants can interact with.
- * @publicDocs
- */
+declare const tagName = 's-admin-action';
 export interface AdminActionJSXProps
   extends Partial<AdminActionProps>,
     Pick<AdminActionProps$1, 'id'> {
   /**
-   * The primary action button or link to display in the admin action area. This is the main call-to-action that appears prominently in the interface. Typically uses a button component with `variant="primary"` to complete or advance the workflow.
+   * The main action button or link displayed in the admin action modal.
+   * This represents the primary or most important action that users can take in this modal context, typically displayed with high visual prominence.
    */
   primaryAction: ComponentChildren;
   /**
-   * The secondary action buttons or links to display in the admin action area. These are supporting actions like cancel, back, or alternative operations. Typically uses button components with `variant="secondary"` or `variant="tertiary"`.
+   * Additional action buttons or links displayed in the admin action modal.
+   * These provide alternative or supporting actions, visually de-emphasized compared to the primary action to establish clear hierarchy.
    */
   secondaryActions: ComponentChildren;
 }
 
-/**
- * The CSS styles as a string, used for styling web components within their shadow DOM.
- * @publicDocs
- */
-export type Styles = string;
-/**
- * The implementation configuration for rendering a Preact component into a shadow root. Defines the render function that returns JSX elements and optional CSS styles to apply to the component's shadow DOM.
- * @publicDocs
- */
-export type RenderImpl = Omit<ShadowRootInit, 'mode'> & {
-  /**
-   * The render function that returns Preact/JSX elements to display in the component's shadow root.
-   */
-  ShadowRoot: (element: any) => ComponentChildren;
-  /**
-   * The optional CSS styles to inject into the component's shadow DOM.
-   */
-  styles?: Styles;
-};
-/**
- * The properties of an activation event (such as a click or keyboard press) that describe which modifier keys and mouse buttons were involved. This is used to determine intended behavior like opening links in new tabs when Command/Control is pressed.
- * @publicDocs
- */
-export interface ActivationEventEsque {
-  /**
-   * Whether the Shift key was pressed during the activation event.
-   */
-  shiftKey: boolean;
-  /**
-   * Whether the Meta key (Command on Mac, Windows key on Windows) was pressed during the activation event.
-   */
-  metaKey: boolean;
-  /**
-   * Whether the Control key was pressed during the activation event.
-   */
-  ctrlKey: boolean;
-  /**
-   * The mouse button that was pressed during the activation event. `0` for primary button (left click), `1` for auxiliary button (middle click), `2` for secondary button (right click).
-   */
-  button: number;
-}
-/**
- * The options for controlling how a synthetic click behaves. Allows passing modifier key states and button information from an original event to influence link behavior such as opening in new tabs or background tabs.
- * @publicDocs
- */
-export interface ClickOptions {
-  /**
-   * The activation event (such as a click or keyboard event) whose modifier key state and button information should influence the synthetic click behavior. For example, passing an event with `metaKey: true` will cause links to open in a new tab.
-   */
-  sourceEvent?: ActivationEventEsque;
-}
-/**
- * Base class for creating custom elements with Preact.
- * While this class could be used in both Node and the browser, the constructor will only be used in the browser.
- * So we give it a type of HTMLElement to avoid typing issues later where it's used, which will only happen in the browser.
- */
-declare const BaseClass: typeof globalThis.HTMLElement;
-declare abstract class PreactCustomElement extends BaseClass {
-  /** @private */
-  static get observedAttributes(): string[];
-  constructor({
-    styles,
-    ShadowRoot: renderFunction,
-    delegatesFocus,
-    ...options
-  }: RenderImpl);
-
-  /** @private */
-  setAttribute(name: string, value: string): void;
-  /** @private */
-  attributeChangedCallback(name: string): void;
+declare class PolarisCustomElement extends PreactCustomElement {
+  constructor(renderImpl: Omit<RenderImpl, 'globalShadowCSS'>);
   /** @private */
   connectedCallback(): void;
   /** @private */
-  disconnectedCallback(): void;
-  /** @private */
   adoptedCallback(): void;
-  /**
-   * Queue a run of the render function.
-   * You shouldn't need to call this manually - it should be handled by changes to @property values.
-   * @private
-   */
-  queueRender(): void;
-  /**
-   * Like the standard `element.click()`, but you can influence the behavior with a `sourceEvent`.
-   *
-   * For example, if the `sourceEvent` was a middle click, or has particular keys held down,
-   * components will attempt to produce the desired behavior on links, such as opening the page in the background tab.
-   * @private
-   * @param options
-   */
-  click({sourceEvent}?: ClickOptions): void;
 }
 
 /**
- * The admin action custom element class that renders action controls in the Shopify admin interface. This component creates a standardized action area with a heading and slots for primary and secondary action buttons, used exclusively in admin action extensions.
+ * Configure the following properties on the admin action component.
+ * @publicDocs
  */
 declare class AdminAction
-  extends PreactCustomElement
+  extends PolarisCustomElement
   implements AdminActionProps
 {
   /**
-   * The heading text to display at the top of the action area. This title describes the action or task the merchant is performing. If not provided, the extension name is used as the heading.
+   * The text to use as the Action modal's title. If not provided, the name of the extension will be used.
    */
   heading: string;
-
   /**
-   * Whether the action extension is currently in a loading state, such as during initial data fetching or when opening the action. When `true`, the action area might display loading indicators and prevent user interaction until loading completes.
-   *
-   * @default false
+   * Whether the action is in a loading state, such as during initial page load or when the action is being opened. When `true`, the action might be in an inert state that prevents user interaction.
    */
   loading: boolean;
-
   constructor();
 }
 declare global {

package/src/surfaces/admin/components/AdminBlock.d.ts

@@ -1,140 +1,55 @@
-/** VERSION: 1.25.0 **/
+/** VERSION: 2.26.1 **/
 /* eslint-disable import/extensions */
 
 /* eslint-disable @typescript-eslint/no-namespace */
 
 // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment
 /// <reference lib="DOM" />
-import type {AdminBlockProps$1, ComponentChildren} from './shared.d.ts';
+import type {
+  AdminBlockProps$1,
+  PreactCustomElement,
+  RenderImpl,
+} from './shared.d.ts';
 
 /**
- * The properties for the admin block component. These properties configure the heading and collapsed summary of collapsible content blocks in the admin interface.
+ * Configure the following properties on the admin block component.
  * @publicDocs
  */
 export interface AdminBlockProps
-  extends Pick<AdminBlockProps$1, 'heading' | 'collapsedSummary'> {}
-
-declare const tagName = 's-admin-block';
-
-/**
- * The JSX props for the admin block component. These properties extend `AdminBlockProps` with an optional `id` for element identification in JSX rendering.
- * @publicDocs
- */
-export interface AdminBlockJSXProps
-  extends Partial<AdminBlockProps>,
-    Pick<AdminBlockProps$1, 'id'> {}
-
-/**
- * The CSS styles as a string, used for styling web components within their shadow DOM.
- * @publicDocs
- */
-export type Styles = string;
-/**
- * The implementation configuration for rendering a Preact component into a shadow root. Defines the render function that returns JSX elements and optional CSS styles to apply to the component's shadow DOM.
- * @publicDocs
- */
-export type RenderImpl = Omit<ShadowRootInit, 'mode'> & {
-  /**
-   * The render function that returns Preact/JSX elements to display in the component's shadow root.
-   */
-  ShadowRoot: (element: any) => ComponentChildren;
-  /**
-   * The optional CSS styles to inject into the component's shadow DOM.
-   */
-  styles?: Styles;
-};
-/**
- * The properties of an activation event (such as a click or keyboard press) that describe which modifier keys and mouse buttons were involved. This is used to determine intended behavior like opening links in new tabs when Command/Control is pressed.
- * @publicDocs
- */
-export interface ActivationEventEsque {
-  /**
-   * Whether the Shift key was pressed during the activation event.
-   */
-  shiftKey: boolean;
+  extends Pick<AdminBlockProps$1, 'heading' | 'collapsedSummary'> {
   /**
-   * Whether the Meta key (Command on Mac, Windows key on Windows) was pressed during the activation event.
+   * The text displayed as the block's title in the header. If not provided, the extension name will be used.
    */
-  metaKey: boolean;
+  heading?: AdminBlockProps$1['heading'];
   /**
-   * Whether the Control key was pressed during the activation event.
+   * The summary text displayed when the app block is collapsed. Summaries longer than 30 characters will be truncated.
    */
-  ctrlKey: boolean;
-  /**
-   * The mouse button that was pressed during the activation event. `0` for primary button (left click), `1` for auxiliary button (middle click), `2` for secondary button (right click).
-   */
-  button: number;
+  collapsedSummary?: AdminBlockProps$1['collapsedSummary'];
 }
-/**
- * The options for controlling how a synthetic click behaves. Allows passing modifier key states and button information from an original event to influence link behavior such as opening in new tabs or background tabs.
- * @publicDocs
- */
-export interface ClickOptions {
-  /**
-   * The activation event (such as a click or keyboard event) whose modifier key state and button information should influence the synthetic click behavior. For example, passing an event with `metaKey: true` will cause links to open in a new tab.
-   */
-  sourceEvent?: ActivationEventEsque;
-}
-/**
- * Base class for creating custom elements with Preact.
- * While this class could be used in both Node and the browser, the constructor will only be used in the browser.
- * So we give it a type of HTMLElement to avoid typing issues later where it's used, which will only happen in the browser.
- */
-declare const BaseClass: typeof globalThis.HTMLElement;
-declare abstract class PreactCustomElement extends BaseClass {
-  /** @private */
-  static get observedAttributes(): string[];
-  constructor({
-    styles,
-    ShadowRoot: renderFunction,
-    delegatesFocus,
-    ...options
-  }: RenderImpl);
 
-  /** @private */
-  setAttribute(name: string, value: string): void;
-  /** @private */
-  attributeChangedCallback(name: string): void;
+declare const tagName = 's-admin-block';
+export interface AdminBlockJSXProps
+  extends Partial<AdminBlockProps>,
+    Pick<AdminBlockProps$1, 'id'> {}
+
+declare class PolarisCustomElement extends PreactCustomElement {
+  constructor(renderImpl: Omit<RenderImpl, 'globalShadowCSS'>);
   /** @private */
   connectedCallback(): void;
   /** @private */
-  disconnectedCallback(): void;
-  /** @private */
   adoptedCallback(): void;
-  /**
-   * Queue a run of the render function.
-   * You shouldn't need to call this manually - it should be handled by changes to @property values.
-   * @private
-   */
-  queueRender(): void;
-  /**
-   * Like the standard `element.click()`, but you can influence the behavior with a `sourceEvent`.
-   *
-   * For example, if the `sourceEvent` was a middle click, or has particular keys held down,
-   * components will attempt to produce the desired behavior on links, such as opening the page in the background tab.
-   * @private
-   * @param options
-   */
-  click({sourceEvent}?: ClickOptions): void;
 }
 
 /**
- * The admin block custom element class that renders a collapsible content block in the Shopify admin interface. This component organizes content into expandable sections with headings and provides a summary when collapsed.
+ * Configure the following properties on the admin block component.
+ * @publicDocs
  */
 declare class AdminBlock
-  extends PreactCustomElement
+  extends PolarisCustomElement
   implements AdminBlockProps
 {
-  /**
-   * The heading text to display at the top of the block. This title describes the content section the merchant is viewing. If not provided, no heading is displayed.
-   */
   heading: string;
-
-  /**
-   * The summary text to display when the block is collapsed. This provides merchants with a preview of the block's contents without expanding it. If not provided, no summary is displayed.
-   */
   collapsedSummary: string;
-
   constructor();
 }
 declare global {

package/src/surfaces/admin/components/AdminPrintAction.d.ts

@@ -1,135 +1,54 @@
-/** VERSION: 1.25.0 **/
+/** VERSION: 2.26.1 **/
 /* eslint-disable import/extensions */
 
 /* eslint-disable @typescript-eslint/no-namespace */
 
 // eslint-disable-next-line @typescript-eslint/triple-slash-reference, spaced-comment
 /// <reference lib="DOM" />
-import type {AdminPrintActionProps$1, ComponentChildren} from './shared.d.ts';
+import type {
+  AdminPrintActionProps$1,
+  PreactCustomElement,
+  RenderImpl,
+} from './shared.d.ts';
 
 /**
- * The properties for the admin print action component. These properties configure the source URL for printing content within admin extensions.
+ * Configure the following properties on the admin print action component.
  * @publicDocs
  */
 export interface AdminPrintActionProps
-  extends Pick<AdminPrintActionProps$1, 'src'> {}
+  extends Pick<AdminPrintActionProps$1, 'src'> {
+  /**
+   * The URL of the document to preview and print. Supports HTML, PDF, and image formats.
+   * If not provided, the preview will show an empty state and the print button will be disabled.
+   */
+  src?: AdminPrintActionProps$1['src'];
+}
 
 declare const tagName = 's-admin-print-action';
-
-/**
- * The JSX props for the admin print action component. These properties extend `AdminPrintActionProps` with an optional `id` for element identification in JSX rendering.
- * @publicDocs
- */
 export interface AdminPrintActionJSXProps
   extends Partial<AdminPrintActionProps>,
     Pick<AdminPrintActionProps$1, 'id'> {}
 
-/**
- * The CSS styles as a string, used for styling web components within their shadow DOM.
- * @publicDocs
- */
-export type Styles = string;
-/**
- * The implementation configuration for rendering a Preact component into a shadow root. Defines the render function that returns JSX elements and optional CSS styles to apply to the component's shadow DOM.
- * @publicDocs
- */
-export type RenderImpl = Omit<ShadowRootInit, 'mode'> & {
-  /**
-   * The render function that returns Preact/JSX elements to display in the component's shadow root.
-   */
-  ShadowRoot: (element: any) => ComponentChildren;
-  /**
-   * The optional CSS styles to inject into the component's shadow DOM.
-   */
-  styles?: Styles;
-};
-/**
- * The properties of an activation event (such as a click or keyboard press) that describe which modifier keys and mouse buttons were involved. This is used to determine intended behavior like opening links in new tabs when Command/Control is pressed.
- * @publicDocs
- */
-export interface ActivationEventEsque {
-  /**
-   * Whether the Shift key was pressed during the activation event.
-   */
-  shiftKey: boolean;
-  /**
-   * Whether the Meta key (Command on Mac, Windows key on Windows) was pressed during the activation event.
-   */
-  metaKey: boolean;
-  /**
-   * Whether the Control key was pressed during the activation event.
-   */
-  ctrlKey: boolean;
-  /**
-   * The mouse button that was pressed during the activation event. `0` for primary button (left click), `1` for auxiliary button (middle click), `2` for secondary button (right click).
-   */
-  button: number;
-}
-/**
- * The options for controlling how a synthetic click behaves. Allows passing modifier key states and button information from an original event to influence link behavior such as opening in new tabs or background tabs.
- * @publicDocs
- */
-export interface ClickOptions {
-  /**
-   * The activation event (such as a click or keyboard event) whose modifier key state and button information should influence the synthetic click behavior. For example, passing an event with `metaKey: true` will cause links to open in a new tab.
-   */
-  sourceEvent?: ActivationEventEsque;
-}
-/**
- * Base class for creating custom elements with Preact.
- * While this class could be used in both Node and the browser, the constructor will only be used in the browser.
- * So we give it a type of HTMLElement to avoid typing issues later where it's used, which will only happen in the browser.
- */
-declare const BaseClass: typeof globalThis.HTMLElement;
-declare abstract class PreactCustomElement extends BaseClass {
-  /** @private */
-  static get observedAttributes(): string[];
-  constructor({
-    styles,
-    ShadowRoot: renderFunction,
-    delegatesFocus,
-    ...options
-  }: RenderImpl);
-
-  /** @private */
-  setAttribute(name: string, value: string): void;
-  /** @private */
-  attributeChangedCallback(name: string): void;
+declare class PolarisCustomElement extends PreactCustomElement {
+  constructor(renderImpl: Omit<RenderImpl, 'globalShadowCSS'>);
   /** @private */
   connectedCallback(): void;
   /** @private */
-  disconnectedCallback(): void;
-  /** @private */
   adoptedCallback(): void;
-  /**
-   * Queue a run of the render function.
-   * You shouldn't need to call this manually - it should be handled by changes to @property values.
-   * @private
-   */
-  queueRender(): void;
-  /**
-   * Like the standard `element.click()`, but you can influence the behavior with a `sourceEvent`.
-   *
-   * For example, if the `sourceEvent` was a middle click, or has particular keys held down,
-   * components will attempt to produce the desired behavior on links, such as opening the page in the background tab.
-   * @private
-   * @param options
-   */
-  click({sourceEvent}?: ClickOptions): void;
 }
 
 /**
- * The admin print action custom element class that renders a print interface in the Shopify admin. This component enables merchants to print content from a specified source URL using the browser's print functionality.
+ * Configure the following properties on the admin print action component.
+ * @publicDocs
  */
 declare class AdminPrintAction
-  extends PreactCustomElement
+  extends PolarisCustomElement
   implements AdminPrintActionProps
 {
   /**
-   * The source URL of the content to print. This should point to the document or page that'll be sent to the printer when the merchant initiates the print action.
+   * The `src` URL of the preview and the document to print. If not provided, the preview will show an empty state and the print button will be disabled. HTML, PDFs, and images are supported.
    */
   src: string;
-
   constructor();
 }
 declare global {