@shopify/ui-extensions 2026.7.4 → 2026.10.0-rc.10

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

@@ -1,4 +1,4 @@
-/** VERSION: 1.25.0 **/
+/** VERSION: 2.23.0 **/
 /* eslint-disable import/extensions */
 
 /* eslint-disable @typescript-eslint/no-namespace */
@@ -8,22 +8,28 @@
 import type {
   ExtendableEvent,
   FormProps$1,
-  ComponentChildren,
+  PreactCustomElement,
+  RenderImpl,
 } from './shared.d.ts';
 
 /**
- * A callback event with a strongly-typed `currentTarget` property that corresponds to a specific HTML element. This provides better type safety when handling events from custom elements.
+ * An event object with a strongly-typed `currentTarget` property that references the specific HTML element that triggered the event.
+ *
+ * This type extends the standard DOM `Event` interface and ensures type safety when accessing the element that fired the event.
  * @publicDocs
  */
 export type CallbackEvent<T extends keyof HTMLElementTagNameMap> = Event & {
-  /**
-   * The element that the event listener is attached to, strongly typed based on the element's tag name.
-   */
   currentTarget: HTMLElementTagNameMap[T];
 };
-
 /**
- * An event listener function type for callback events with a strongly-typed `currentTarget`. This ensures the event handler receives the correct element type.
+ * A function that handles events from UI components.
+ *
+ * This type represents an event listener callback that receives a `CallbackEvent` with a strongly-typed `currentTarget`. Use this for component event handlers like `click`, `focus`, `blur`, and other DOM events.
+ *
+ * @example
+ * const handleClick: CallbackEventListener<'button'> = (event) => {
+ *   console.log('Button clicked:', event.currentTarget);
+ * };
  * @publicDocs
  */
 export type CallbackEventListener<T extends keyof HTMLElementTagNameMap> =
@@ -31,18 +37,12 @@ export type CallbackEventListener<T extends keyof HTMLElementTagNameMap> =
       (event: CallbackEvent<T>): void;
     })
   | null;
-
-/**
- * A callback event that includes the `waitUntil` method for extending asynchronous operations. This allows you to delay form submission until promises resolve, enabling async validation or data processing before the form completes its action.
- * @publicDocs
- */
 export interface CallbackExtendableEvent<
   TTagName extends keyof HTMLElementTagNameMap,
 > extends CallbackEvent<TTagName>,
     Pick<ExtendableEvent, 'waitUntil'> {}
-
 /**
- * An event listener function type for extendable callback events. This combines strong typing with the ability to extend the event lifecycle using `waitUntil`.
+ * A function that handles extendable events from UI components. This type represents an event listener callback that can use `waitUntil` to extend the event lifetime.
  * @publicDocs
  */
 export type CallbackExtendableEventListener<
@@ -54,135 +54,42 @@ export type CallbackExtendableEventListener<
   | null;
 
 /**
- * The properties for the form component. These properties configure the form's identifier for targeting and referencing within the admin extension.
- * @publicDocs
+ * Configure the following properties on the form component.
  */
 export interface FormProps extends Pick<FormProps$1, 'id'> {}
 
 declare const tagName = 's-form';
-
-/**
- * The JSX props for the form component. These properties extend `FormProps` with event callbacks for form submission and reset actions in JSX rendering.
- * @publicDocs
- */
 export interface FormJSXProps extends Partial<FormProps> {
   /**
-   * A callback that's invoked when the form is submitted. Use the event's `waitUntil` method to perform async operations like validation or data processing before the submission completes.
+   * A callback that is run when the form is submitted.
    */
   onSubmit?: ((event: CallbackExtendableEvent<typeof tagName>) => void) | null;
   /**
-   * A callback that's invoked when the form is reset, restoring all form fields to their initial values.
+   * A callback that is run when the form is reset.
    */
   onReset?: ((event: CallbackEvent<typeof tagName>) => void) | null;
 }
 
-/**
- * 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 form custom element class that renders a form container in the Shopify admin interface. This component manages form submission, validation, and reset behavior for collecting merchant input.
+ * Configure the following properties on the form component.
+ * @publicDocs
  */
-declare class Form extends PreactCustomElement implements FormProps {
+declare class Form extends PolarisCustomElement implements FormProps {
   constructor();
-
   /**
-   * A callback that's invoked when the form is submitted. Use the event's `waitUntil` method to perform async operations like validation, data processing, or API calls before the submission completes.
+   * A callback that is run when the form is submitted.
    */
   accessor onsubmit: CallbackExtendableEventListener<typeof tagName> | null;
-
   /**
-   * A callback that's invoked when the form is reset, restoring all form fields to their initial values.
+   * A callback that is run when the form is reset.
    */
   accessor onreset: CallbackEventListener<typeof tagName> | null;
 }

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

@@ -1,4 +1,4 @@
-/** VERSION: 1.25.0 **/
+/** VERSION: 2.23.0 **/
 /* eslint-disable import/extensions */
 
 /* eslint-disable @typescript-eslint/no-namespace */
@@ -8,22 +8,27 @@
 import type {
   FunctionSettingsProps$1,
   ExtendableEvent,
-  ComponentChildren,
+  PreactCustomElement,
 } from './shared.d.ts';
 
 /**
- * A callback event with a strongly-typed `currentTarget` property that corresponds to a specific HTML element. This provides better type safety when handling events from custom elements.
+ * An event object with a strongly-typed `currentTarget` property that references the specific HTML element that triggered the event.
+ *
+ * This type extends the standard DOM `Event` interface and ensures type safety when accessing the element that fired the event.
  * @publicDocs
  */
 export type CallbackEvent<T extends keyof HTMLElementTagNameMap> = Event & {
-  /**
-   * The element that the event listener is attached to, strongly typed based on the element's tag name.
-   */
   currentTarget: HTMLElementTagNameMap[T];
 };
-
 /**
- * An event listener function type for callback events with a strongly-typed `currentTarget`. This ensures the event handler receives the correct element type.
+ * A function that handles events from UI components.
+ *
+ * This type represents an event listener callback that receives a `CallbackEvent` with a strongly-typed `currentTarget`. Use this for component event handlers like `click`, `focus`, `blur`, and other DOM events.
+ *
+ * @example
+ * const handleClick: CallbackEventListener<'button'> = (event) => {
+ *   console.log('Button clicked:', event.currentTarget);
+ * };
  * @publicDocs
  */
 export type CallbackEventListener<T extends keyof HTMLElementTagNameMap> =
@@ -31,9 +36,8 @@ export type CallbackEventListener<T extends keyof HTMLElementTagNameMap> =
       (event: CallbackEvent<T>): void;
     })
   | null;
-
 /**
- * An event listener function type for error events that includes an `error` property. This is used for handling validation errors and submission failures in forms.
+ * A function that handles error events from UI components. This type represents an event listener callback that receives both the event and an error object.
  * @publicDocs
  */
 export type CallbackErrorEventListener<
@@ -43,26 +47,17 @@ export type CallbackErrorEventListener<
   | (EventListener & {
       (
         event: CallbackEvent<TTagName> & {
-          /**
-           * The error that occurred during the operation.
-           */
           error: TError;
         },
       ): void;
     })
   | null;
-
-/**
- * A callback event that includes the `waitUntil` method for extending asynchronous operations. This allows you to delay event completion until promises resolve, enabling async operations during event handling.
- * @publicDocs
- */
 export interface CallbackExtendableEvent<
   TTagName extends keyof HTMLElementTagNameMap,
 > extends CallbackEvent<TTagName>,
     Pick<ExtendableEvent, 'waitUntil'> {}
-
 /**
- * An event listener function type for extendable callback events. This combines strong typing with the ability to extend the event lifecycle using `waitUntil`.
+ * A function that handles extendable events from UI components. This type represents an event listener callback that can use `waitUntil` to extend the event lifetime.
  * @publicDocs
  */
 export type CallbackExtendableEventListener<
@@ -74,24 +69,18 @@ export type CallbackExtendableEventListener<
   | null;
 
 /**
- * The properties for the function settings component. These properties configure the form's identifier for configuring Shopify Function settings in the admin interface.
- * @publicDocs
+ * Configure the following properties on the function settings component.
  */
 export interface FunctionSettingsProps
   extends Pick<FunctionSettingsProps$1, 'id'> {}
 
 declare const tagName = 's-function-settings';
-
-/**
- * The JSX props for the function settings component. These properties extend `FunctionSettingsProps` with event callbacks for form submission, reset, and error handling in JSX rendering.
- * @publicDocs
- */
 export interface FunctionSettingsJSXProps
   extends Partial<
     FunctionSettingsProps & Pick<FunctionSettingsProps$1, 'onError'>
   > {
   /**
-   * An optional callback function that'll be run by the admin when the user
+   * An optional callback function that will be run by the admin when the user
    * commits their changes in the admin-rendered part of the function settings
    * experience. If `event.waitUntil` is called with a promise, the admin will wait for the
    * promise to resolve before committing any changes to Shopify’s servers. If
@@ -100,115 +89,21 @@ export interface FunctionSettingsJSXProps
    */
   onSubmit?: ((event: CallbackExtendableEvent<typeof tagName>) => void) | null;
   /**
-   * A callback that's invoked when the function settings form is reset, restoring all form fields to their initial values.
+   * A callback that is run when the function settings form is reset.
    */
   onReset?: ((event: CallbackEvent<typeof tagName>) => void) | null;
 }
 
 /**
- * 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;
-  /** @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 error event type that's passed to the `onError` callback of function settings. This event contains validation errors that occurred when committing function settings to Shopify's servers.
+ * Represents the event type for function settings errors. Extracted from the parameters of the `onFunctionSettingsError` callback.
  * @publicDocs
  */
 export type FunctionSettingsErrorEvent = Parameters<
   NonNullable<FunctionSettingsProps$1['onError']>
 >[0];
-
 /**
- * The function settings custom element class that renders a specialized form for configuring Shopify Function settings in the admin interface. This component manages function configuration submission, validation, and error handling.
+ * Configure the following properties on the function settings component.
+ * @publicDocs
  */
 declare class FunctionSettings
   extends PreactCustomElement
@@ -216,7 +111,7 @@ declare class FunctionSettings
 {
   constructor();
   /**
-   * An optional callback function that'll be run by the admin when the user
+   * An optional callback function that will be run by the admin when the user
    * commits their changes in the admin-rendered part of the function settings
    * experience. If `event.waitUntil` is called with a promise, the admin will wait for the
    * promise to resolve before committing any changes to Shopify’s servers. If
@@ -224,13 +119,12 @@ declare class FunctionSettings
    * using the `message` property of the error you reject with.
    */
   accessor onsubmit: CallbackExtendableEventListener<typeof tagName> | null;
-
   /**
-   * An optional callback function that'll be run by the admin when
+   * An optional callback function that will be run by the admin when
    * committing the changes to Shopify’s servers fails. The error event you receive includes
-   * an `error` property that's an `AggregateError` object. This object includes
+   * an `error` property that is an `AggregateError` object. This object includes
    * an array of errors that were caused by data your extension provided.
-   * Network errors and user errors that are out of your control won't be reported here.
+   * Network errors and user errors that are out of your control will not be reported here.
    *
    * In the `onError` callback, you should update your extension’s UI to
    * highlight the fields that caused the errors, and display the error messages
@@ -242,7 +136,7 @@ declare class FunctionSettings
   > | null;
 
   /**
-   * A callback that's invoked when the function settings form is reset, restoring all form fields to their initial values.
+   * A callback that is run when the function settings form is reset.
    */
   accessor onreset: CallbackEventListener<typeof tagName> | null;
 }