@shopify/ui-extensions 2025.10.7 → 2025.10.9

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

@@ -12,28 +12,64 @@ import type {ButtonProps, 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;
+  /**
+   * 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,25 +80,27 @@ export interface ButtonJSXProps
     'id' | 'disabled' | 'command' | 'commandFor' | 'loading'
   > {
   /**
-   * Sets the action the `commandFor` should take when this clickable is activated.
-   *
-   * See the documentation of particular components for the actions they support.
-   *
-   * - `--auto`: a default action for the target component.
-   * - `--show`: shows the target component.
-   * - `--hide`: hides the target component.
-   * - `--toggle`: toggles the target component.
+   * Sets the action the `commandFor` should take when this clickable is activated:
+   * - `--auto`: A default action for the target component
+   * - `--show`: Shows the target component
+   * - `--hide`: Hides the target component
+   * - `--toggle`: Toggles the target component
    *
    * @default '--auto'
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command
+   * Learn more about [button command on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command).
    */
   command?: Extract<
     ButtonProps['command'],
     '--auto' | '--show' | '--hide' | '--toggle'
   >;
   /**
-   * Sets the tone of the Button, based on the intention of the information being conveyed.
+   * Sets the tone of the button, based on the intention of the information being conveyed.
+   *
+   * - `'auto'` - Automatically determines the appropriate tone based on context.
+   * - `'neutral'` - The standard tone for general actions and interactions.
+   * - `'caution'` - Indicates actions that require careful consideration.
+   * - `'warning'` - Alerts users to potential issues or important information.
+   * - `'critical'` - Used for destructive actions like deleting or removing content.
    *
    * @default 'auto'
    */
@@ -71,17 +109,19 @@ export interface ButtonJSXProps
     'auto' | 'critical' | 'neutral' | 'warning' | 'caution'
   >;
   /**
-   * Changes the visual appearance of the Button.
+   * Changes the visual appearance of the button.
+   * - `primary`: Creates a prominent call-to-action button with high visual emphasis for the most important action on a screen.
+   * - `secondary`: Provides a less prominent button appearance for supporting actions and secondary interactions.
    *
    * @default 'auto' - the variant is automatically determined by the Button's context
    */
   variant?: Extract<ButtonProps['variant'], 'primary' | 'secondary'>;
   /**
-   * Called when the button is activated.
+   * An event that's called when the button is activated.
    */
   onClick?: (event: CallbackEvent<typeof tagName>) => void;
   /**
-   * The content of the Button.
+   * The child elements to render within this component.
    */
   children?: ComponentChildren;
 }

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

@@ -12,18 +12,30 @@ import type {ChoiceProps, 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>;

package/src/surfaces/point-of-sale/components/ChoiceList/examples/composed-choices.jsx

@@ -0,0 +1,35 @@
+<s-choice-list>
+  {/* Composed choice with image and text */}
+  <s-choice value="option1">
+    <s-stack gap="small-200" alignItems="center" direction="inline">
+      <s-box blockSize="40px" inlineSize="40px">
+        <s-image src="https://placehold.co/60x60" inlineSize="fill" objectFit="cover" />
+      </s-box>
+      <s-box>
+        <s-text>Option 1</s-text>
+        <s-text type="small" color="subdued">
+          Additional details for option 1
+        </s-text>
+      </s-box>
+    </s-stack>
+  </s-choice>
+
+  {/* Composed choice with nested text */}
+  <s-choice value="option2">
+    <s-text type="strong">
+      Option 2
+      <s-text type="small" color="subdued">
+        Additional details for option 2
+      </s-text>
+    </s-text>
+  </s-choice>
+
+  {/* Mix of text and composed elements */}
+  <s-choice value="option3" disabled>
+    Option 3
+    <s-text type="small" color="subdued">
+      (disabled)
+    </s-text>
+    <s-text type="strong">Additional details for option 3</s-text>
+  </s-choice>
+</s-choice-list>

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

@@ -12,28 +12,64 @@ import type {ChoiceListProps, 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;
+  /**
+   * 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,15 +77,15 @@ declare const tagName = 's-choice-list';
 export interface ChoiceListJSXProps
   extends Pick<ChoiceListProps, 'id' | 'values' | 'multiple'> {
   /**
-   * Callback when the user changes a choice. Fires simultaneously with onChange.
+   * Called when the user changes a choice. Fires simultaneously with `onChange`.
    */
   onInput?: ((event: CallbackEvent<typeof tagName>) => void) | null;
   /**
-   * Callback when the user changes a choice. Fires simultaneously with onInput.
+   * Called when the user changes a choice. Fires simultaneously with `onInput`.
    */
   onChange?: ((event: CallbackEvent<typeof tagName>) => void) | null;
   /**
-   * The content of the ChoiceList. Should be one or more Choice elements.
+   * The child elements to render within this component. Should be one or more Choice elements.
    */
   children?: ComponentChildren;
 }

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

@@ -12,28 +12,64 @@ import type {ClickableProps, 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;
+  /**
+   * Additional data associated with the event.
+   */
   detail?: any;
+  /**
+   * The current phase of the event flow. Returns a number indicating which phase the event is in: 1 (capturing phase), 2 (at target), or 3 (bubbling phase). This helps determine how the event is propagating through the DOM hierarchy.
+   */
   eventPhase: number;
+  /**
+   * The element that triggered the event.
+   */
   target: HTMLElementTagNameMap[T] | null;
 }
 
@@ -41,11 +77,11 @@ declare const tagName = 's-clickable';
 export interface ClickableJSXProps
   extends Pick<ClickableProps, 'id' | 'disabled'> {
   /**
-   * Callback when the element is activated.
+   * The callback when the element is activated.
    */
   onClick?: (event: CallbackEvent<typeof tagName>) => void;
   /**
-   * The content of the Clickable.
+   * The child elements to render within this component.
    */
   children?: ComponentChildren;
 }

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

@@ -12,28 +12,64 @@ import type {DateFieldProps, 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;
+  /**
+   * 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 DateFieldJSXProps
     'id' | 'label' | 'details' | 'value' | 'disabled' | 'error'
   > {
   /**
-   * 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/DatePicker.d.ts

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

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

@@ -12,28 +12,64 @@ import type {DateSpinnerProps, 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;
+  /**
+   * 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-date-spinner';
 export interface DateSpinnerJSXProps
   extends Pick<DateSpinnerProps, 'id' | 'value'> {
   /**
-   * Callback when the user makes a selection.
+   * Called when the user makes a selection in the spinner.
    */
   onInput?: (event: CallbackEvent<typeof tagName>) => void | null;
   /**
-   * Callback when the value changes. Only called when a different value is selected.
+   * Called when the value changes. Only called when a different value is selected.
    */
   onChange?: (event: CallbackEvent<typeof tagName>) => void | null;
   /**
-   * Callback when the date spinner is dismissed.
+   * Called when the date spinner is dismissed or closed.
    */
   onBlur?: (event: CallbackEvent<typeof tagName>) => void | null;
   /**
-   * Callback when the date spinner is revealed.
+   * Called when the date spinner is revealed or opened.
    */
   onFocus?: (event: CallbackEvent<typeof tagName>) => void | null;
 }

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

@@ -12,18 +12,30 @@ import type {DividerProps, 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>;