@shopify/ui-extensions 2025.10.13 → 2025.10.14

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

@@ -11,18 +11,36 @@ import type {
   ComponentChildren,
 } 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.
+ */
 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.
+ */
 export type CallbackEventListener<T extends keyof HTMLElementTagNameMap> =
   | (EventListener & {
       (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.
+ */
 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`.
+ */
 export type CallbackExtendableEventListener<
   TTagName extends keyof HTMLElementTagNameMap,
 > =
@@ -31,34 +49,71 @@ 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.
+ */
 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.
+ */
 export interface FormJSXProps extends Partial<FormProps> {
   /**
-   * A callback that is run when the form is submitted.
+   * 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.
    */
   onSubmit?: ((event: CallbackExtendableEvent<typeof tagName>) => void) | null;
   /**
-   * A callback that is run when the form is reset.
+   * A callback that's invoked when the form is reset, restoring all form fields to their initial values.
    */
   onReset?: ((event: CallbackEvent<typeof tagName>) => void) | null;
 }
 
+/**
+ * The CSS styles as a string, used for styling web components within their shadow DOM.
+ */
 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.
+ */
 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.
+ */
 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.
+ */
 export interface ClickOptions {
   /**
-   * The event you want to influence the synthetic click.
+   * 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;
 }
@@ -105,14 +160,19 @@ declare abstract class PreactCustomElement extends BaseClass {
   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.
+ */
 declare class Form extends PreactCustomElement implements FormProps {
   constructor();
+
   /**
-   * A callback that is run when the form is submitted.
+   * 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.
    */
   accessor onsubmit: CallbackExtendableEventListener<typeof tagName> | null;
+
   /**
-   * A callback that is run when the form is reset.
+   * A callback that's invoked when the form is reset, restoring all form fields to their initial values.
    */
   accessor onreset: CallbackEventListener<typeof tagName> | null;
 }

package/src/surfaces/admin/components/FormExtensionComponents.ts

@@ -1,5 +1,8 @@
 import {StandardComponents} from './StandardComponents';
 
+/**
+ * The components available for building form-based extensions. Includes all standard components plus the form component for creating structured data collection interfaces with submission handling and validation.
+ */
 export type FormExtensionComponents = StandardComponents | 'Form';
 
 export default FormExtensionComponents;

package/src/surfaces/admin/components/FunctionSettings/examples/default.html

@@ -0,0 +1,9 @@
+<s-function-settings>
+  <s-number-field
+    step="1"
+    suffix="%"
+    label="Percentage"
+    name="percentage"
+    value="10"
+  ></s-number-field>
+</s-function-settings>

package/src/surfaces/admin/components/FunctionSettings/examples/with-multiple-settings.html

@@ -0,0 +1,16 @@
+<s-function-settings>
+  <s-stack direction="block" gap="base">
+    <s-section heading="Tier 1">
+      <s-stack direction="inline" gap="base">
+        <s-number-field label="Minimum quantity" name="tier1Qty" value="5" min="1" step="1"></s-number-field>
+        <s-number-field label="Discount" name="tier1Discount" value="10" min="0" max="100" step="1" suffix="%"></s-number-field>
+      </s-stack>
+    </s-section>
+    <s-section heading="Tier 2">
+      <s-stack direction="inline" gap="base">
+        <s-number-field label="Minimum quantity" name="tier2Qty" value="10" min="1" step="1"></s-number-field>
+        <s-number-field label="Discount" name="tier2Discount" value="20" min="0" max="100" step="1" suffix="%"></s-number-field>
+      </s-stack>
+    </s-section>
+  </s-stack>
+</s-function-settings>

package/src/surfaces/admin/components/FunctionSettings/examples/with-select-options.html

@@ -0,0 +1,10 @@
+<s-function-settings>
+  <s-stack direction="block" gap="base">
+    <s-select label="Apply discount to" name="target">
+      <s-option value="all">All products</s-option>
+      <s-option value="collection">Specific collection</s-option>
+      <s-option value="tagged">Products with tag</s-option>
+    </s-select>
+    <s-text-field label="Collection or tag" name="identifier"></s-text-field>
+  </s-stack>
+</s-function-settings>

package/src/surfaces/admin/components/FunctionSettings/examples/with-toggle.html

@@ -0,0 +1,13 @@
+<s-function-settings>
+  <s-stack direction="block" gap="base">
+    <s-switch label="Enable free shipping threshold" name="freeShippingEnabled" checked></s-switch>
+    <s-number-field
+      step="0.01"
+      prefix="$"
+      label="Minimum order amount"
+      name="freeShippingThreshold"
+      value="75.00"
+      min="0"
+    ></s-number-field>
+  </s-stack>
+</s-function-settings>

package/src/surfaces/admin/components/FunctionSettings/examples/with-validation.html

@@ -0,0 +1,23 @@
+<s-function-settings>
+  <s-stack direction="block" gap="base">
+    <s-number-field
+      step="1"
+      suffix="%"
+      label="Discount percentage"
+      name="percentage"
+      min="0"
+      max="100"
+      required
+      error="Enter a percentage between 0 and 100"
+    ></s-number-field>
+    <s-number-field
+      step="0.01"
+      prefix="$"
+      label="Maximum discount amount"
+      name="maxDiscount"
+      min="0"
+      required
+      error="Enter a positive dollar amount"
+    ></s-number-field>
+  </s-stack>
+</s-function-settings>

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

@@ -11,14 +11,28 @@ import type {
   ComponentChildren,
 } 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.
+ */
 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.
+ */
 export type CallbackEventListener<T extends keyof HTMLElementTagNameMap> =
   | (EventListener & {
       (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.
+ */
 export type CallbackErrorEventListener<
   TTagName extends keyof HTMLElementTagNameMap,
   TError extends Error = Error,
@@ -26,15 +40,26 @@ 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.
+ */
 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`.
+ */
 export type CallbackExtendableEventListener<
   TTagName extends keyof HTMLElementTagNameMap,
 > =
@@ -43,16 +68,23 @@ 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.
+ */
 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.
+ */
 export interface FunctionSettingsJSXProps
   extends Partial<
     FunctionSettingsProps & Pick<FunctionSettingsProps$1, 'onError'>
   > {
   /**
-   * An optional callback function that will be run by the admin when the user
+   * An optional callback function that'll 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
@@ -61,25 +93,55 @@ export interface FunctionSettingsJSXProps
    */
   onSubmit?: ((event: CallbackExtendableEvent<typeof tagName>) => void) | null;
   /**
-   * A callback that is run when the function settings form is reset.
+   * A callback that's invoked when the function settings form is reset, restoring all form fields to their initial values.
    */
   onReset?: ((event: CallbackEvent<typeof tagName>) => void) | null;
 }
 
+/**
+ * The CSS styles as a string, used for styling web components within their shadow DOM.
+ */
 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.
+ */
 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.
+ */
 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.
+ */
 export interface ClickOptions {
   /**
-   * The event you want to influence the synthetic click.
+   * 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;
 }
@@ -126,16 +188,23 @@ declare abstract class PreactCustomElement extends BaseClass {
   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.
+ */
 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.
+ */
 declare class FunctionSettings
   extends PreactCustomElement
   implements FunctionSettingsProps
 {
   constructor();
   /**
-   * An optional callback function that will be run by the admin when the user
+   * An optional callback function that'll 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
@@ -143,12 +212,13 @@ declare class FunctionSettings
    * using the `message` property of the error you reject with.
    */
   accessor onsubmit: CallbackExtendableEventListener<typeof tagName> | null;
+
   /**
-   * An optional callback function that will be run by the admin when
+   * An optional callback function that'll be run by the admin when
    * committing the changes to Shopify’s servers fails. The error event you receive includes
-   * an `error` property that is an `AggregateError` object. This object includes
+   * an `error` property that's 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 will not be reported here.
+   * Network errors and user errors that are out of your control won't 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
@@ -160,7 +230,7 @@ declare class FunctionSettings
   > | null;
 
   /**
-   * A callback that is run when the function settings form is reset.
+   * A callback that's invoked when the function settings form is reset, restoring all form fields to their initial values.
    */
   accessor onreset: CallbackEventListener<typeof tagName> | null;
 }

package/src/surfaces/admin/components/FunctionSettingsComponents.ts

@@ -1,5 +1,8 @@
 import {FormExtensionComponents} from './FormExtensionComponents';
 
+/**
+ * The components available for building function settings extensions. Includes all form components plus the function settings component required for function settings configuration.
+ */
 export type FunctionSettingsComponents =
   | FormExtensionComponents
   | 'FunctionSettings';