@shopify/ui-extensions 2025.10.7 → 2025.10.9

package/src/surfaces/point-of-sale/components/EmailField.d.ts

@@ -17,28 +17,64 @@ import type {
 
 export type ComponentChildren = any;
 /**
- * Used when an element does not have children.
+ * The base props for elements without children, providing key, ref, and slot properties.
  */
 export interface BaseElementProps<TClass = HTMLElement> {
+  /**
+   * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation.
+   */
   key?: Key;
+  /**
+   * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations.
+   */
   ref?: Ref<TClass>;
+  /**
+   * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component.
+   */
   slot?: Lowercase<string>;
 }
 /**
- * Used when an element has children.
+ * The base props for elements with children, extending `BaseElementProps` with children support.
  */
 export interface BaseElementPropsWithChildren<TClass = HTMLElement>
   extends BaseElementProps<TClass> {
+  /**
+   * The child elements to render within this component.
+   */
   children?: ComponentChildren;
 }
 export type IntrinsicElementProps<T> = T & BaseElementPropsWithChildren<T>;
+/**
+ * Represents the event object passed to callback functions when interactive events occur. Contains metadata about the event, including the target element, event phase, and propagation behavior.
+ */
 export interface CallbackEvent<T extends keyof HTMLElementTagNameMap> {
+  /**
+   * The element that the event listener is attached to.
+   */
   currentTarget: HTMLElementTagNameMap[T];
+  /**
+   * Whether the event bubbles up through the DOM tree.
+   */
   bubbles?: boolean;
+  /**
+   * Whether the event can be canceled.
+   */
   cancelable?: boolean;
+  /**
+   * Whether the event will trigger listeners outside of a shadow root.
+   */
   composed?: boolean;
+  /**
+   * Additional data associated with the event.
+   */
   detail?: any;
+  /**
+   * The current phase of the event flow.
+   */
   eventPhase: number;
+  /**
+   * The element that triggered the event.
+   */
   target: HTMLElementTagNameMap[T] | null;
 }
 
@@ -57,23 +93,23 @@ export interface EmailFieldJSXProps
     | 'details'
   > {
   /**
-   * Callback when the user makes any changes in the field.
+   * Called when the user makes any changes in the field.
    */
   onInput?: ((event: CallbackEvent<typeof tagName>) => void) | null;
   /**
-   * Callback after editing completes (typically on blur).
+   * Called after editing completes, typically on blur.
    */
   onChange?: ((event: CallbackEvent<typeof tagName>) => void) | null;
   /**
-   * Callback when the element loses focus.
+   * Called when the element loses focus.
    */
   onBlur?: ((event: CallbackEvent<typeof tagName>) => void) | null;
   /**
-   * Callback when the element receives focus.
+   * Called when the element receives focus.
    */
   onFocus?: ((event: CallbackEvent<typeof tagName>) => void) | null;
   /**
-   * Additional content to be displayed in the field. Commonly used to display clickable text.
+   * Additional content to be displayed in the field. Commonly used to display clickable text or action elements. Only `Button` and `Clickable` components are supported in this slot. Use the `slot="accessory"` attribute to place elements in this area.
    */
   accessory?: ComponentChild;
 }

package/src/surfaces/point-of-sale/components/Heading.d.ts

@@ -12,18 +12,30 @@ import type {HeadingProps, Key, Ref} from './components-shared.d.ts';
 
 export type ComponentChildren = any;
 /**
- * Used when an element does not have children.
+ * The base props for elements without children, providing key, ref, and slot properties.
  */
 export interface BaseElementProps<TClass = HTMLElement> {
+  /**
+   * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation.
+   */
   key?: Key;
+  /**
+   * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations.
+   */
   ref?: Ref<TClass>;
+  /**
+   * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component.
+   */
   slot?: Lowercase<string>;
 }
 /**
- * Used when an element has children.
+ * The base props for elements with children, extending `BaseElementProps` with children support.
  */
 export interface BaseElementPropsWithChildren<TClass = HTMLElement>
   extends BaseElementProps<TClass> {
+  /**
+   * The content of the heading, typically text that describes the section or page it introduces.
+   */
   children?: ComponentChildren;
 }
 export type IntrinsicElementProps<T> = T & BaseElementPropsWithChildren<T>;
@@ -31,7 +43,7 @@ export type IntrinsicElementProps<T> = T & BaseElementPropsWithChildren<T>;
 declare const tagName = 's-heading';
 export interface HeadingJSXProps extends Pick<HeadingProps, 'id'> {
   /**
-   * The content of the Heading.
+   * The content of the heading, typically text that describes the section or page it introduces.
    */
   children?: ComponentChildren;
 }

package/src/surfaces/point-of-sale/components/Icon.d.ts

@@ -12,23 +12,38 @@ import type {IconProps, Key, Ref} from './components-shared.d.ts';
 
 export type ComponentChildren = any;
 /**
- * Used when an element does not have children.
+ * The base props for elements without children, providing key, ref, and slot properties.
  */
 export interface BaseElementProps<TClass = HTMLElement> {
+  /**
+   * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation.
+   */
   key?: Key;
+  /**
+   * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations.
+   */
   ref?: Ref<TClass>;
+  /**
+   * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component.
+   */
   slot?: Lowercase<string>;
 }
 /**
- * Used when an element has children.
+ * The base props for elements with children, extending `BaseElementProps` with children support.
  */
 export interface BaseElementPropsWithChildren<TClass = HTMLElement>
   extends BaseElementProps<TClass> {
+  /**
+   * The child elements to render within this component.
+   */
   children?: ComponentChildren;
 }
 export type IntrinsicElementProps<T> = T & BaseElementPropsWithChildren<T>;
 
 declare const tagName = 's-icon';
+/**
+ * Lists all currently supported icon names available for use in the POS interface. Reference this list when selecting icons to ensure compatibility and availability.
+ */
 export type SupportedIconNames = Extract<
   IconProps['type'],
   | 'alert-circle'

package/src/surfaces/point-of-sale/components/Image.d.ts

@@ -26,10 +26,13 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement>
   extends BaseElementProps<TClass> {
   children?: ComponentChildren;
 }
-export type IntrinsicElementProps<T> = T & BaseElementPropsWithChildren<T>;
+export type IntrinsicElementProps<T> = T &
+  BaseElementPropsWithChildren<T & HTMLElement>;
+export type HtmlElementTagNameProps<T> = T & HTMLElement;
 
 declare const tagName = 's-image';
-export interface ImageJSXProps extends Pick<ImageProps, 'id' | 'objectFit'> {
+export interface ImageJSXProps
+  extends Pick<ImageProps, 'id' | 'objectFit' | 'alt'> {
   /**
    * The displayed inline width of the image.
    *
@@ -56,7 +59,7 @@ export interface ImageJSXProps extends Pick<ImageProps, 'id' | 'objectFit'> {
 }
 declare global {
   interface HTMLElementTagNameMap {
-    [tagName]: ImageJSXProps;
+    [tagName]: HtmlElementTagNameProps<ImageJSXProps>;
   }
 }
 declare module 'preact' {

package/src/surfaces/point-of-sale/components/Modal.d.ts

@@ -17,55 +17,87 @@ import type {
 
 export type ComponentChildren = any;
 /**
- * Used when an element does not have children.
+ * The base props for elements without children, providing key, ref, and slot properties.
  */
 export interface BaseElementProps<TClass = HTMLElement> {
+  /**
+   * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation.
+   */
   key?: Key;
+  /**
+   * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations.
+   */
   ref?: Ref<TClass>;
+  /**
+   * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component.
+   */
   slot?: Lowercase<string>;
 }
 /**
- * Used when an element has children.
+ * The base props for elements with children, extending `BaseElementProps` with children support.
  */
 export interface BaseElementPropsWithChildren<TClass = HTMLElement>
   extends BaseElementProps<TClass> {
+  /**
+   * The child elements to render within this component.
+   */
   children?: ComponentChildren;
 }
 export type IntrinsicElementProps<T> = T & BaseElementPropsWithChildren<T>;
+/**
+ * Represents the event object passed to callback functions when interactive events occur. Contains metadata about the event, including the target element, event phase, and propagation behavior.
+ */
 export interface CallbackEvent<T extends keyof HTMLElementTagNameMap> {
+  /**
+   * The element that the event listener is attached to.
+   */
   currentTarget: HTMLElementTagNameMap[T];
+  /**
+   * Whether the event bubbles up through the DOM tree.
+   */
   bubbles?: boolean;
+  /**
+   * Whether the event can be canceled.
+   */
   cancelable?: boolean;
+  /**
+   * Whether the event will trigger listeners outside of a shadow root.
+   */
   composed?: boolean;
+  /**
+   * Additional data associated with the event.
+   */
   detail?: any;
+  /**
+   * The current phase of the event flow.
+   */
   eventPhase: number;
+  /**
+   * The element that triggered the event.
+   */
   target: HTMLElementTagNameMap[T] | null;
 }
 
 declare const tagName = 's-modal';
 export interface ModalJSXProps extends Pick<ModalProps, 'id' | 'heading'> {
   /**
-   * Callback when the modal is hidden.
+   * The callback when the modal is hidden. Use this event to perform cleanup tasks, update application state, or trigger other actions when the modal is dismissed or closed.
    */
   onHide?: (event: CallbackEvent<typeof tagName>) => void | null;
   /**
-   * Callback when the modal is shown.
+   * The callback when the modal is shown. Use this event to initialize modal content, focus specific elements, or perform setup tasks when the modal becomes visible.
    */
   onShow?: (event: CallbackEvent<typeof tagName>) => void | null;
   /**
-   * The primary action button displayed in the modal.
-   *
-   * The tone of the button is used to define the tone of the modal.
-   *
-   * If omitted, the modal will default to an 'info' tone, and show an 'OK' button, translated according to the user's locale.
+   * The primary action button displayed in the modal. The tone of the button is used to define the tone of the modal. If omitted, the modal will default to an `'info'` tone, and show an OK button, translated according to the user's locale.
    */
   primaryAction?: ComponentChild;
   /**
-   * The secondary action buttons displayed in the modal.
+   * The secondary action buttons displayed in the modal. Use this slot to provide alternative actions or cancel options that give users flexibility in how they respond to the modal.
    */
   secondaryActions?: ComponentChild;
   /**
-   * The content of the Modal.
+   * The child elements to render within this component.
    */
   children?: ComponentChildren;
 }

package/src/surfaces/point-of-sale/components/NumberField.d.ts

@@ -17,28 +17,64 @@ import type {
 
 export type ComponentChildren = any;
 /**
- * Used when an element does not have children.
+ * The base props for elements without children, providing key, ref, and slot properties.
  */
 export interface BaseElementProps<TClass = HTMLElement> {
+  /**
+   * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation.
+   */
   key?: Key;
+  /**
+   * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations.
+   */
   ref?: Ref<TClass>;
+  /**
+   * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component.
+   */
   slot?: Lowercase<string>;
 }
 /**
- * Used when an element has children.
+ * The base props for elements with children, extending `BaseElementProps` with children support.
  */
 export interface BaseElementPropsWithChildren<TClass = HTMLElement>
   extends BaseElementProps<TClass> {
+  /**
+   * The child elements to render within this component.
+   */
   children?: ComponentChildren;
 }
 export type IntrinsicElementProps<T> = T & BaseElementPropsWithChildren<T>;
+/**
+ * Represents the event object passed to callback functions when interactive events occur. Contains metadata about the event, including the target element, event phase, and propagation behavior.
+ */
 export interface CallbackEvent<T extends keyof HTMLElementTagNameMap> {
+  /**
+   * The element that the event listener is attached to.
+   */
   currentTarget: HTMLElementTagNameMap[T];
+  /**
+   * Whether the event bubbles up through the DOM tree.
+   */
   bubbles?: boolean;
+  /**
+   * Whether the event can be canceled.
+   */
   cancelable?: boolean;
+  /**
+   * Whether the event will trigger listeners outside of a shadow root.
+   */
   composed?: boolean;
+  /**
+   * The additional data associated with the event.
+   */
   detail?: any;
+  /**
+   * The current phase of the event flow.
+   */
   eventPhase: number;
+  /**
+   * The element that triggered the event.
+   */
   target: HTMLElementTagNameMap[T] | null;
 }
 
@@ -59,85 +95,64 @@ export interface NumberFieldJSXProps
     | 'controls'
   > {
   /**
-   * Content to use as the field label.
-   *
-   * Label is not supported when using Stepper controls
+   * The text content that displays as the field label, describing the numeric information being requested. This property isn't supported when using `stepper` controls.
    */
   label?: NumberFieldProps['label'];
   /**
-   * Additional text to provide context or guidance for the field.
-   * This text is displayed along with the field and its label
-   * to offer more information or instructions to the user.
-   *
-   * This will also be exposed to screen reader users.
-   *
-   * Details are not supported when using Stepper controls
+   * The additional text to provide context or guidance for the field. This text is displayed along with the field and its label to offer more information or instructions to the user. This will also be exposed to screen reader users. This property isn't supported when using `stepper` controls.
    */
   details?: NumberFieldProps['details'];
   /**
-   * Whether the field needs a value. This requirement adds semantic value
-   * to the field, but it will not cause an error to appear automatically.
-   * If you want to present an error when this field is empty, you can do
-   * so with the `error` property.
+   * Whether the field needs a value. This requirement adds semantic value to the field but doesn't cause an error to appear automatically. Use the `error` property to present validation errors. This property isn't supported when using `stepper` controls.
    *
    * @default false
-   *
-   * Required is not supported when using Stepper controls
    */
   required?: NumberFieldProps['required'];
   /**
-   * Indicate an error to the user. The field will be given a specific stylistic treatment
-   * to communicate problems that have to be resolved immediately.
-   *
-   * Error is not supported when using Stepper controls
+   * An error message that indicates a problem to the user. The field receives specific stylistic treatment to communicate issues that must be resolved immediately. This property isn't supported when using `stepper` controls.
    */
   error?: NumberFieldProps['error'];
   /**
-   * Sets the virtual keyboard.
+   * The virtual keyboard layout that the field displays for numeric input. This property isn't supported when using `stepper` controls.
    *
-   * Input mode is not supported when using Stepper controls
+   * - `'decimal'` - A keyboard layout that includes decimal point support for entering fractional numbers, prices, or measurements with decimal precision.
+   * - `'numeric'` - A keyboard layout optimized for integer-only entry without decimal point support, ideal for quantities, counts, or whole number values.
    *
-   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/inputmode
    * @default 'decimal'
    */
   inputMode?: NumberFieldProps['inputMode'];
   /**
-   * A short hint that describes the expected value of the field.
-   *
-   * Placeholder text is not supported when using Stepper controls due to constrained space for the number field, especially on phones.
+   * A short hint that provides guidance about the expected value of the field. This property isn't supported when using `stepper` controls due to constrained space, especially on phones.
    */
   placeholder?: NumberFieldProps['placeholder'];
   /**
-   *  Additional content to be displayed in the field. Commonly used to display clickable text.
-   *
-   * > Note: Accessory is not supported when using Stepper controls
+   * The additional content to be displayed in the field. Commonly used to display clickable text or action elements. Use the `slot="accessory"` attribute to place elements in this area. This slot isn't supported when using `stepper` controls.
    */
   accessory?: ComponentChild;
   /**
-   * Sets the type of controls displayed for the field.
+   * The type of controls displayed for the field:
    *
-   * - `stepper`: displays buttons to increase or decrease the value of the field by the stepping interval defined in the `step` property. Note that in POS
-   *   adding stepper controls simplifies the behaviour of the Number Field itself. The field supports only integer values, is always-populated and automatically
-   *   validates the value to be within the min and max bounds. Validation, label, details and placeholder are not supported when using Stepper controls.
+   * - `'auto'` - An automatic setting where the presence of controls depends on the surface and context. The system determines the most appropriate control type based on the usage scenario.
+   * - `'stepper'` - Displays increment (+) and decrement (-) buttons for adjusting the numeric value. When `stepper` controls are enabled, the field behavior is constrained: it accepts only integer values, always contains a value (never empty), and automatically validates against `min` and `max` bounds. The `label`, `details`, `placeholder`, `error`, `required`, and `inputMode` properties aren't supported with `stepper` controls.
+   * - `'none'` - A control type with no visible controls where users must input the value manually using the keyboard.
    *
-   * - `none`: no controls are displayed and users must input the value manually.
-   * - `auto`: the presence of the controls depends on the surface and context.
+   * @default 'auto'
    */
   controls?: NumberFieldProps['controls'];
   /**
-   * Callback when the user makes any changes in the field.
+   * A callback function that executes when the user makes any changes in the field.
    */
   onInput?: ((event: CallbackEvent<typeof tagName>) => void) | null;
   /**
-   * Callback after editing completes (typically on blur).
+   * A callback function that executes after editing completes, typically on blur.
    */
   onChange?: ((event: CallbackEvent<typeof tagName>) => void) | null;
   /**
-   * Callback when the element loses focus.
+   * A callback function that executes when the element loses focus.
    */
   onBlur?: ((event: CallbackEvent<typeof tagName>) => void) | null;
   /**
-   * Callback when the element receives focus.
+   * A callback function that executes when the element receives focus.
    */
   onFocus?: ((event: CallbackEvent<typeof tagName>) => void) | null;
 }

package/src/surfaces/point-of-sale/components/Page.d.ts

@@ -17,18 +17,30 @@ import type {
 
 export type ComponentChildren = any;
 /**
- * Used when an element does not have children.
+ * The base props for elements without children, providing key, ref, and slot properties.
  */
 export interface BaseElementProps<TClass = HTMLElement> {
+  /**
+   * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation.
+   */
   key?: Key;
+  /**
+   * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations.
+   */
   ref?: Ref<TClass>;
+  /**
+   * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component.
+   */
   slot?: Lowercase<string>;
 }
 /**
- * Used when an element has children.
+ * The base props for elements with children, extending `BaseElementProps` with children support.
  */
 export interface BaseElementPropsWithChildren<TClass = HTMLElement>
   extends BaseElementProps<TClass> {
+  /**
+   * The child elements to render within this component.
+   */
   children?: ComponentChildren;
 }
 export type IntrinsicElementProps<T> = T & BaseElementPropsWithChildren<T>;
@@ -36,25 +48,25 @@ export type IntrinsicElementProps<T> = T & BaseElementPropsWithChildren<T>;
 declare const tagName = 's-page';
 export interface PageJSXProps extends Pick<PageProps, 'id'> {
   /**
-   * The main page heading, displayed in the action bar at the top of the page.
+   * The main page heading displayed in the action bar at the top of the page.
    *
    * @default: ''
    */
   heading?: PageProps['heading'];
   /**
-   * A secondary page heading, displayed under the main heading in the action bar.
+   * A secondary page heading displayed under the main heading in the action bar.
    */
   subheading?: PageProps['subheading'];
   /**
-   * Button element to display in the action bar. Only a single button is supported.
+   * A button element to display in the action bar. Only a single button is supported. Use the `slot="secondary-actions"` attribute to place content in this area.
    */
   secondaryActions?: ComponentChild;
   /**
-   * Content to display in the page's sidebar.
+   * The content to display in the page's sidebar. This area is for content that is tangentially related to the main content, such as navigation or contextual information. Use the `slot="aside"` attribute to place content in this area.
    */
   aside?: ComponentChild;
   /**
-   * The content of the Page.
+   * The child elements to render within this component.
    */
   children?: ComponentChildren;
 }

package/src/surfaces/point-of-sale/components/PosBlock.d.ts

@@ -17,18 +17,30 @@ import type {
 
 export type ComponentChildren = any;
 /**
- * Used when an element does not have children.
+ * The base props for elements without children, providing key, ref, and slot properties.
  */
 export interface BaseElementProps<TClass = HTMLElement> {
+  /**
+   * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation.
+   */
   key?: Key;
+  /**
+   * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations.
+   */
   ref?: Ref<TClass>;
+  /**
+   * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component.
+   */
   slot?: Lowercase<string>;
 }
 /**
- * Used when an element has children.
+ * The base props for elements with children, extending `BaseElementProps` with children support.
  */
 export interface BaseElementPropsWithChildren<TClass = HTMLElement>
   extends BaseElementProps<TClass> {
+  /**
+   * The child elements to render within this component.
+   */
   children?: ComponentChildren;
 }
 export type IntrinsicElementProps<T> = T & BaseElementPropsWithChildren<T>;
@@ -37,11 +49,11 @@ declare const tagName = 's-pos-block';
 export interface PosBlockJSXProps
   extends Pick<POSBlockProps, 'id' | 'heading'> {
   /**
-   * The secondary actions to perform, provided as button or link type elements.
+   * The secondary actions to perform, provided as button or link type elements. Use the `slot="secondary-actions"` attribute to place interactive elements that allow users to take actions related to the block's content.
    */
   secondaryActions?: ComponentChild;
   /**
-   * The content of the Block.
+   * The child elements to render within this component.
    */
   children?: ComponentChildren;
 }

package/src/surfaces/point-of-sale/components/QrCode.d.ts

@@ -12,18 +12,30 @@ import type {QRCodeProps, Key, Ref} from './components-shared.d.ts';
 
 export type ComponentChildren = any;
 /**
- * Used when an element does not have children.
+ * The base props for elements without children, providing key, ref, and slot properties.
  */
 export interface BaseElementProps<TClass = HTMLElement> {
+  /**
+   * A unique identifier for the element in lists. Used by Preact for efficient rendering and reconciliation.
+   */
   key?: Key;
+  /**
+   * A reference to the underlying DOM element. Commonly used to access the element directly for imperative operations.
+   */
   ref?: Ref<TClass>;
+  /**
+   * The named [slot](/docs/api/polaris/using-polaris-web-components#slots) this element should be placed in when used within a web component.
+   */
   slot?: Lowercase<string>;
 }
 /**
- * Used when an element has children.
+ * The base props for elements with children, extending `BaseElementProps` with children support.
  */
 export interface BaseElementPropsWithChildren<TClass = HTMLElement>
   extends BaseElementProps<TClass> {
+  /**
+   * The child elements to render within this component.
+   */
   children?: ComponentChildren;
 }
 export type IntrinsicElementProps<T> = T & BaseElementPropsWithChildren<T>;