@shopify/ui-extensions 2025.10.13 → 2025.10.14

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

@@ -8,49 +8,116 @@
 /// <reference lib="DOM" />
 import type {ComponentChildren, TextFieldProps$1} 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;
+/**
+ * The JSX-style event callback props for form field components. These properties provide React-like event handling for input, change, focus, and blur events.
+ */
 export interface FieldReactProps<T extends keyof HTMLElementTagNameMap> {
+  /**
+   * A callback that's invoked when the user makes any changes in the field. This fires on every keystroke or modification. Learn more about the [input event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event).
+   */
   onInput?: ((event: CallbackEvent<T>) => void) | null;
+  /**
+   * A callback that's invoked when the user has finished editing the field, such as when they blur the field or press Enter. This fires less frequently than `onInput`. Learn more about the [change event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event).
+   */
   onChange?: ((event: CallbackEvent<T>) => void) | null;
+  /**
+   * A callback that's invoked when the field receives focus, typically when the user clicks into it or tabs to it. Learn more about the [focus event](https://developer.mozilla.org/en-US/docs/Web/API/Element/focus_event).
+   */
   onFocus?: ((event: CallbackEvent<T>) => void) | null;
+  /**
+   * A callback that's invoked when the field loses focus, typically when the user clicks away or tabs out of it. Learn more about the [blur event](https://developer.mozilla.org/en-US/docs/Web/API/Element/blur_event).
+   */
   onBlur?: ((event: CallbackEvent<T>) => void) | null;
 }
-/** Used when an element does not have children. */
+/**
+ * The base properties for Preact elements without children. Provides `key`, `ref`, and `slot` properties for element identification, DOM access, and slot-based positioning.
+ */
 export interface PreactBaseElementProps<TClass extends HTMLElement> {
-  /** Assigns a unique key to this element. */
+  /**
+   * A unique identifier for the element when used in lists. Preact uses keys for efficient rendering and reconciliation when lists change.
+   */
   key?: preact.Key;
-  /** Assigns a ref (generally from `useRef()`) to this element. */
+  /**
+   * A reference to the underlying DOM element. Typically created with `useRef()` to access the element directly for imperative operations like focusing or measuring.
+   */
   ref?: preact.Ref<TClass>;
-  /** Assigns this element to a parent's slot. */
+  /**
+   * The named slot this element should be placed in when used within a web component. Learn more about [using slots](/docs/api/app-ui/using-web-components#slots).
+   */
   slot?: Lowercase<string>;
 }
-/** Used when an element has children. */
+/**
+ * The base properties for Preact elements with children. Extends `PreactBaseElementProps` with the ability to render child elements.
+ */
 export interface PreactBaseElementPropsWithChildren<TClass extends HTMLElement>
   extends PreactBaseElementProps<TClass> {
+  /**
+   * The child elements to render within this component.
+   */
   children?: preact.ComponentChildren;
 }
 
+/**
+ * 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;
 }
@@ -98,9 +165,13 @@ declare abstract class PreactCustomElement extends BaseClass {
 }
 
 declare const internals: unique symbol;
+/**
+ * The base properties for an input element that participates in form submission. Defines the core properties needed for form integration including identifier, name, value, and disabled state.
+ */
 export type PreactInputProps = Required<
   Pick<TextFieldProps$1, 'disabled' | 'id' | 'name' | 'value'>
 >;
+/** @private */
 declare class PreactInputElement
   extends PreactCustomElement
   implements PreactInputProps
@@ -108,16 +179,39 @@ declare class PreactInputElement
   static formAssociated: boolean;
   /** @private */
   [internals]: ElementInternals;
+  /**
+   * A callback that's invoked when the user has finished editing the field, such as when they blur the field.
+   */
   accessor onchange: CallbackEventListener<'input'>;
+  /**
+   * A callback that's invoked when the user makes any changes in the field.
+   */
   accessor oninput: CallbackEventListener<'input'>;
+  /**
+   * Whether the field is disabled, disallowing any interaction.
+   *
+   * @default false
+   */
   accessor disabled: PreactInputProps['disabled'];
+  /**
+   * An identifier for the field.
+   */
   accessor id: PreactInputProps['id'];
+  /**
+   * An identifier for the field that's unique within the nearest containing form.
+   */
   accessor name: PreactInputProps['name'];
+  /**
+   * The current value for the field.
+   */
   get value(): PreactInputProps['value'];
   set value(value: PreactInputProps['value']);
   constructor(renderImpl: RenderImpl);
 }
 
+/**
+ * The base properties for form field elements that support labels, validation, and autocomplete. Extends `PreactInputProps` with additional form field features like labels, placeholders, error messages, and autocomplete hints.
+ */
 export type PreactFieldProps<Autocomplete extends string = string> =
   PreactInputProps &
     Required<
@@ -134,19 +228,9 @@ export type PreactFieldProps<Autocomplete extends string = string> =
       >
     > & {
       /**
-       * A hint as to the intended content of the field.
-       *
-       * When set to `on` (the default), this property indicates that the field should support
-       * autofill, but you do not have any more semantic information on the intended
-       * contents.
+       * A hint about the intended content of the field for browser autocomplete functionality. When set to `'on'` (the default), this indicates that the field should support autofill, but you don't have specific semantic information about the contents. When set to `'off'`, you're indicating that this field contains sensitive information or contents that are never saved, like one-time codes. Alternatively, you can provide a specific autocomplete value that describes the data you'd like to be entered during autofill, such as `'email'`, `'name'`, or `'street-address'`.
        *
-       * When set to `off`, you are indicating that this field contains sensitive
-       * information, or contents that are never saved, like one-time codes.
-       *
-       * Alternatively, you can provide value which describes the
-       * specific data you would like to be entered into this field during autofill.
-       *
-       * @see Learn more about the set of {@link https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill-detail-tokens|autocomplete values} supported in browsers.
+       * @see Learn more about the set of [autocomplete values](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill-detail-tokens) supported in browsers.
        *
        * @default 'tel' for PhoneField
        * @default 'email' for EmailField
@@ -155,20 +239,58 @@ export type PreactFieldProps<Autocomplete extends string = string> =
        */
       autocomplete: Autocomplete;
     };
+/** @private */
 declare class PreactFieldElement<Autocomplete extends string = string>
   extends PreactInputElement
   implements PreactFieldProps<Autocomplete>
 {
+  /**
+   * A callback that's invoked when the field loses focus.
+   */
   accessor onblur: CallbackEventListener<'input'>;
+  /**
+   * A callback that's invoked when the field receives focus.
+   */
   accessor onfocus: CallbackEventListener<'input'>;
+  /**
+   * A hint as to the intended content of the field for autocomplete purposes.
+   */
   accessor autocomplete: PreactFieldProps<Autocomplete>['autocomplete'];
+  /**
+   * The initial value for the field when it's first rendered.
+   */
   accessor defaultValue: PreactFieldProps['defaultValue'];
+  /**
+   * Additional descriptive text to display below the field that provides supplementary information.
+   */
   accessor details: PreactFieldProps['details'];
+  /**
+   * An error message to display below the field, indicating validation failure or other issues.
+   */
   accessor error: PreactFieldProps['error'];
+  /**
+   * The text label to display for the field, describing what the user should enter.
+   */
   accessor label: PreactFieldProps['label'];
+  /**
+   * Controls the visibility of the label for accessibility purposes.
+   */
   accessor labelAccessibilityVisibility: PreactFieldProps['labelAccessibilityVisibility'];
+  /**
+   * The placeholder text that's displayed inside the field when it's empty, providing a hint about expected input.
+   */
   accessor placeholder: PreactFieldProps['placeholder'];
+  /**
+   * Whether the field is read-only, preventing edits while still allowing focus and selection.
+   *
+   * @default false
+   */
   accessor readOnly: PreactFieldProps['readOnly'];
+  /**
+   * Whether the field must be filled out before form submission.
+   *
+   * @default false
+   */
   accessor required: PreactFieldProps['required'];
   /**
    * Global keyboard event handlers for things like key bindings typically
@@ -197,6 +319,9 @@ declare class PreactFieldElement<Autocomplete extends string = string>
   constructor(renderImpl: RenderImpl);
 }
 
+/**
+ * The properties for the text field component. Extends `PreactFieldProps` with text-specific features like icons, length constraints, and prefix/suffix content.
+ */
 export type TextFieldProps = PreactFieldProps<
   /** @default 'on' */
   Required<TextFieldProps$1>['autocomplete']
@@ -208,15 +333,38 @@ export type TextFieldProps = PreactFieldProps<
     >
   >;
 
+/**
+ * The text field custom element class that renders a single-line text input field in the Shopify admin interface. This component allows merchants to enter and edit text with support for labels, validation, icons, and prefix/suffix content.
+ */
 declare class TextField
   extends PreactFieldElement<TextFieldProps['autocomplete']>
   implements TextFieldProps
 {
+  /**
+   * An icon to display at the start of the text field, providing visual context for the input. Accepts any valid icon type from the admin icon set, or an empty string to display no icon.
+   */
   accessor icon: TextFieldProps['icon'];
+  /**
+   * The maximum number of characters the merchant can enter in the field. When this limit is reached, the field prevents further input.
+   */
   accessor maxLength: TextFieldProps['maxLength'];
+  /**
+   * The minimum number of characters required in the field for validation. The field will be considered invalid if the merchant enters fewer characters than this value.
+   */
   accessor minLength: TextFieldProps['minLength'];
+  /**
+   * Text or content to display before the merchant's input, such as a currency symbol (`$`) or protocol (`https://`).
+   */
   accessor prefix: TextFieldProps['prefix'];
+  /**
+   * Text or content to display after the merchant's input, such as a unit of measurement (`kg`, `%`) or domain (`.myshopify.com`).
+   */
   accessor suffix: TextFieldProps['suffix'];
+  /**
+   * The current text value in the field as a string. When setting this property programmatically, it updates the field's display value. When reading it, you get the user's current input.
+   */
+  get value(): string;
+  set value(value: string);
   constructor();
 }
 declare global {
@@ -234,12 +382,15 @@ declare module 'preact' {
 }
 
 declare const tagName = 's-text-field';
+/**
+ * The JSX props for the text field component. These properties extend `TextFieldProps` with JSX-specific event callbacks and an accessory slot for rendering additional content at the end of the field.
+ */
 export interface TextFieldJSXProps
   extends Partial<Omit<TextFieldProps, 'accessory'>>,
     Pick<TextFieldProps$1, 'id'>,
     FieldReactProps<typeof tagName> {
   /**
-   * The accessory to display in the text field.
+   * An accessory element to display at the end of the text field, such as a button, icon, or other interactive component. This appears inside the field's visual boundary, typically for actions like clearing the field or showing additional options.
    */
   accessory?: ComponentChildren;
 }

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

@@ -1,4 +1,4 @@
 <s-thumbnail
-  alt="White sneakers"
+  alt="Image of white sneakers"
   src="https://cdn.shopify.com/static/images/polaris/thumbnail-wc_src.jpg"
 ></s-thumbnail>

package/src/surfaces/admin/components/Thumbnail/examples/different-sizes.html

@@ -1,17 +1,17 @@
 <s-stack gap="large-100">
   <s-thumbnail
     src="https://cdn.shopify.com/static/sample-product/House-Plant1.png"
-    alt="Small thumbnail"
+    alt="Image of indoor plant"
     size="small-200"
   ></s-thumbnail>
   <s-thumbnail
     src="https://cdn.shopify.com/static/sample-product/House-Plant1.png"
-    alt="Base thumbnail"
+    alt="Image of indoor plant"
     size="base"
   ></s-thumbnail>
   <s-thumbnail
     src="https://cdn.shopify.com/static/sample-product/House-Plant1.png"
-    alt="Large thumbnail"
+    alt="Image of indoor plant"
     size="large"
   ></s-thumbnail>
 </s-stack>

package/src/surfaces/admin/components/Thumbnail/examples/with-event-handling.html

@@ -1,9 +1,22 @@
-  <s-stack direction="inline" gap="base">
-    <s-thumbnail
-      src="https://cdn.shopify.com/static/sample-product/House-Plant1.png"
-      alt="Product"
-      size="small-200"
-      onLoad="setLoading(false)"
-    />
-    <s-paragraph>Image loaded</s-paragraph>
- </s-stack>
+<s-stack direction="inline" gap="base" alignItems="center">
+  <s-thumbnail
+    id="product-thumbnail"
+    src="https://cdn.shopify.com/static/sample-product/House-Plant1.png"
+    alt="Image of indoor plant"
+    size="small-200"
+  />
+  <s-text id="status-text">Loading...</s-text>
+</s-stack>
+
+<script>
+  const thumbnail = document.getElementById('product-thumbnail');
+  const statusText = document.getElementById('status-text');
+
+  thumbnail.addEventListener('load', () => {
+    statusText.textContent = 'Image loaded';
+  });
+
+  thumbnail.addEventListener('error', () => {
+    statusText.textContent = 'Failed to load image';
+  });
+</script>

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

@@ -8,55 +8,121 @@
 /// <reference lib="DOM" />
 import type {ThumbnailProps$1, ComponentChildren} from './shared.d.ts';
 
+/**
+ * A callback event that's typed to a specific HTML element.
+ */
 export type CallbackEvent<T extends keyof HTMLElementTagNameMap> = Event & {
+  /**
+   * The element that currently has the event listener attached.
+   */
   currentTarget: HTMLElementTagNameMap[T];
 };
+/**
+ * An event listener for callback events, typed to a specific HTML element.
+ */
 export type CallbackEventListener<T extends keyof HTMLElementTagNameMap> =
   | (EventListener & {
       (event: CallbackEvent<T>): void;
     })
   | null;
-/** Used when an element does not have children. */
+/**
+ * The base properties for Preact elements that don't have children, providing essential attributes like keys and refs for component management.
+ */
 export interface PreactBaseElementProps<TClass extends HTMLElement> {
-  /** Assigns a unique key to this element. */
+  /**
+   * A unique identifier for this element within its parent. Preact uses keys to optimize rendering performance when lists change by tracking which items have been added, removed, or reordered.
+   */
   key?: preact.Key;
-  /** Assigns a ref (generally from `useRef()`) to this element. */
+  /**
+   * A reference to the underlying DOM element, typically created using `useRef()`. This allows you to access and manipulate the DOM element directly in your component logic.
+   */
   ref?: preact.Ref<TClass>;
-  /** Assigns this element to a parent's slot. */
+  /**
+   * Assigns this element to a named slot in a parent component that uses shadow DOM or slot-based composition patterns.
+   */
   slot?: Lowercase<string>;
 }
 
+/**
+ * The properties for the thumbnail component. A thumbnail displays a small preview image with configurable sizing. Properties include `src` for the image URL, `alt` for accessibility text, and `size` for controlling the thumbnail dimensions.
+ */
 export interface ThumbnailProps
   extends Required<Pick<ThumbnailProps$1, 'src' | 'alt' | 'size'>> {
+  /**
+   * The URL of the image to display in the thumbnail. You can provide an absolute or relative URL pointing to the image file.
+   */
+  src: ThumbnailProps$1['src'];
+  /**
+   * Alternative text that describes the image for screen readers. This text should convey the meaning or content of the image to users who can't see it.
+   */
+  alt: ThumbnailProps$1['alt'];
+  /**
+   * The size of the thumbnail. Choose from `'small-200'`, `'small-100'`, `'small'`, `'base'`, `'large'`, or `'large-100'` to control the thumbnail dimensions.
+   *
+   * @default 'base'
+   */
   size: Extract<
     ThumbnailProps$1['size'],
     'small-200' | 'small-100' | 'small' | 'base' | 'large' | 'large-100'
   >;
 }
 
+/**
+ * A string containing CSS styles for a custom element.
+ */
 export type Styles = string;
+/**
+ * The configuration for rendering a custom element with Preact.
+ */
 export type RenderImpl = Omit<ShadowRootInit, 'mode'> & {
+  /**
+   * The function that renders the shadow root content.
+   */
   ShadowRoot: (element: any) => ComponentChildren;
+  /**
+   * The optional CSS styles to apply to the shadow root.
+   */
   styles?: Styles;
 };
+/**
+ * The properties of an activation event, such as a click or keypress. These properties capture which modifier keys were pressed and which mouse button was used during the event.
+ */
 export interface ActivationEventEsque {
+  /**
+   * Whether the shift key was pressed during the event.
+   */
   shiftKey: boolean;
+  /**
+   * Whether the meta key (Command on Mac, Windows key on Windows) was pressed during the event.
+   */
   metaKey: boolean;
+  /**
+   * Whether the control key was pressed during the event.
+   */
   ctrlKey: boolean;
+  /**
+   * The mouse button that was pressed (0 for left, 1 for middle, 2 for right).
+   */
   button: number;
 }
+/**
+ * The options for triggering a synthetic click event.
+ */
 export interface ClickOptions {
   /**
-   * The event you want to influence the synthetic click.
+   * The original user event (such as a click or keyboard event) that triggered this programmatic click. When provided, the component preserves important event properties like modifier keys (Ctrl, Shift, Alt, Meta) and mouse button states, enabling behaviors such as opening links in a new tab when middle-clicked or Ctrl+clicked.
    */
   sourceEvent?: ActivationEventEsque;
 }
 /**
- * Base class for creating custom elements with Preact.
+ * The 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.
+ * 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;
+/**
+ * An abstract base class for creating custom elements that render with Preact.
+ */
 declare abstract class PreactCustomElement extends BaseClass {
   /** @private */
   static get observedAttributes(): string[];
@@ -78,8 +144,8 @@ declare abstract class PreactCustomElement extends BaseClass {
   /** @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.
+   * Queues 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;
@@ -87,18 +153,36 @@ declare abstract class PreactCustomElement extends BaseClass {
    * 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.
+   * components will attempt to produce the desired behavior on links, such as opening the page in a background tab.
    * @private
    * @param options
    */
   click({sourceEvent}?: ClickOptions): void;
 }
 
+/**
+ * A thumbnail displays a small preview image with configurable sizing.
+ */
 declare class Thumbnail extends PreactCustomElement implements ThumbnailProps {
+  /**
+   * The URL of the image to display in the thumbnail.
+   */
   accessor src: ThumbnailProps['src'];
+  /**
+   * Alternative text that describes the image for screen readers.
+   */
   accessor alt: ThumbnailProps['alt'];
+  /**
+   * The size of the thumbnail.
+   */
   accessor size: ThumbnailProps['size'];
+  /**
+   * A callback that's fired when the image has loaded successfully.
+   */
   accessor onload: CallbackEventListener<typeof tagName> | null;
+  /**
+   * A callback that's fired when the image fails to load.
+   */
   accessor onerror: OnErrorEventHandler;
   constructor();
 }
@@ -116,10 +200,19 @@ declare module 'preact' {
 }
 
 declare const tagName = 's-thumbnail';
+/**
+ * The properties for the thumbnail component when it's used in JSX.
+ */
 export interface ThumbnailJSXProps
   extends Partial<ThumbnailProps>,
     Pick<ThumbnailProps$1, 'id'> {
+  /**
+   * A callback that's fired when the image has loaded successfully.
+   */
   onLoad?: ((event: CallbackEvent<typeof tagName>) => void) | null;
+  /**
+   * A callback that's fired when the image fails to load.
+   */
   onError?: ((event: CallbackEvent<typeof tagName>) => void) | null;
 }
 

package/src/surfaces/admin/components/Tooltip/examples/basic-usage.html

@@ -1,4 +1,2 @@
-<s-tooltip id="shipping-status-tooltip">
-  <s-text>This order has shipping labels.</s-text>
-</s-tooltip>
-<s-text interestFor="shipping-status-tooltip">Shipping status</s-text>
+<s-tooltip id="shipping-tooltip">This order has active shipping labels.</s-tooltip>
+<s-text interestFor="shipping-tooltip">Shipping status</s-text>

package/src/surfaces/admin/components/Tooltip/examples/keyboard-shortcut.html

@@ -0,0 +1,2 @@
+<s-tooltip id="save-shortcut">Save (⌘S)</s-tooltip>
+<s-button interestFor="save-shortcut">Save</s-button>

package/src/surfaces/admin/components/Tooltip/examples/with-icon-button.html

@@ -1,6 +1,4 @@
-<s-tooltip id="delete-button-tooltip">
-  <s-text>Delete item permanently</s-text>
-</s-tooltip>
-<s-button interestFor="delete-button-tooltip">
-  <s-icon tone="neutral" type="info"></s-icon>
+<s-tooltip id="info-tooltip">View product details and inventory status</s-tooltip>
+<s-button interestFor="info-tooltip" accessibilityLabel="More information">
+  <s-icon type="info"></s-icon>
 </s-button>