@shopify/ui-extensions 2025.10.8 → 2025.10.9

package/src/surfaces/point-of-sale/components/TextArea.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;
 }
 
@@ -58,23 +94,23 @@ export interface TextAreaJSXProps
     | 'rows'
   > {
   /**
-   * 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;
   /**
-   * Additional content to be displayed in the field. Commonly used to display clickable text.
+   * The 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/TextField.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;
 }
 
@@ -57,23 +93,23 @@ export interface TextFieldJSXProps
     | 'maxLength'
   > {
   /**
-   * 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;
   /**
-   * Additional content to be displayed in the field. Commonly used to display clickable text.
+   * The additional content to be displayed in the field. Commonly used to display clickable text or action elements. Only `Button` and `Clickable` components with text content only 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/Tile.d.ts

@@ -12,28 +12,64 @@ import type {TileProps, 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>;
+/**
+ * Represents an event triggered by user interaction with the tile. Provides information about the event and access to the tile element that triggered it.
+ */
 export interface CallbackEvent<T extends keyof HTMLElementTagNameMap> {
+  /**
+   * The tile element to which the event handler is attached. This always refers to the element that the event listener was added to, unlike `target` which may refer to a child element. Commonly used to access the tile's properties or manipulate the element directly.
+   */
   currentTarget: HTMLElementTagNameMap[T];
+  /**
+   * Indicates whether the event bubbles up through the DOM tree. When `true`, parent elements can also handle this event. Commonly used to determine if the event will propagate to parent handlers.
+   */
   bubbles?: boolean;
+  /**
+   * Indicates whether the event's default action can be prevented. When `true`, calling `preventDefault()` on the event will prevent the default behavior. Commonly used to determine if you can prevent the default action programmatically.
+   */
   cancelable?: boolean;
+  /**
+   * Indicates whether the event will propagate across shadow DOM boundaries into the standard DOM. When `true`, the event can be handled by elements outside the shadow DOM. Relevant for web component implementations.
+   */
   composed?: boolean;
+  /**
+   * The custom data associated with the event. For custom events, this can contain any additional information about the event. For standard tile click events, this is typically undefined unless custom data is provided.
+   */
   detail?: any;
+  /**
+   * Indicates the current phase of the event flow. Standard DOM event phase values: `0` (none), `1` (capturing), `2` (at target), or `3` (bubbling). Typically applied when implementing custom event handling logic that needs to differentiate between event phases.
+   */
   eventPhase: number;
+  /**
+   * The element that originally triggered the event. For tiles, this is typically the same as `currentTarget` since tiles are single interactive elements. Returns `null` if the target is no longer in the document.
+   */
   target: HTMLElementTagNameMap[T] | null;
 }
 
@@ -44,13 +80,13 @@ export interface TileJSXProps
     'heading' | 'id' | 'itemCount' | 'tone' | 'subheading'
   > {
   /**
-   * Disables the Tile meaning it cannot be clicked or receive focus.
+   * Controls whether the tile can be clicked or receive focus. When `true`, the tile appears dimmed and doesn't respond to user interactions or fire click events. Commonly used to prevent actions when conditions aren't met, such as insufficient cart contents or missing permissions. Defaults to `false`.
    *
    * @default false
    */
   disabled?: TileProps['disabled'];
   /**
-   * Callback when the Tile is activated.
+   * The callback function executed when the tile is activated by user interaction. Use this to launch modal workflows with `api.action.presentModal()`, update application state, or trigger other actions. The event parameter provides details about the interaction and the tile element that was clicked.
    */
   onClick?: (event: CallbackEvent<typeof tagName>) => void;
 }

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

@@ -12,28 +12,64 @@ import type {TimeFieldProps, 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>;
+/**
+ * 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;
 }
 
@@ -44,19 +80,19 @@ export interface TimeFieldJSXProps
     'id' | 'label' | 'disabled' | 'value' | 'error' | '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;
 }

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

@@ -12,28 +12,64 @@ import type {TimePickerProps, 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>;
+/**
+ * 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;
 }
 
@@ -41,19 +77,19 @@ declare const tagName = 's-time-picker';
 export interface TimePickerJSXProps
   extends Pick<TimePickerProps, 'id' | 'value'> {
   /**
-   * Callback when the user selects a time from the picker.
+   * Called when the user selects a time from the picker.
    */
   onInput?: (event: CallbackEvent<typeof tagName>) => void | null;
   /**
-   * Callback when the user selects a time from the picker that is different to the current value.
+   * Called when the user selects a time from the picker that is different from the current value.
    */
   onChange?: (event: CallbackEvent<typeof tagName>) => void | null;
   /**
-   * Callback when the time picker is dismissed.
+   * Called when the time picker is dismissed or closed.
    */
   onBlur?: (event: CallbackEvent<typeof tagName>) => void | null;
   /**
-   * Callback when the time picker is revealed.
+   * Called when the time picker is revealed or opened.
    */
   onFocus?: (event: CallbackEvent<typeof tagName>) => void | null;
 }