@shopify/ui-extensions 2026.4.1 → 2026.4.3

package/build/ts/surfaces/customer-account/components/Checkbox.d.ts

@@ -11,21 +11,32 @@
 import type {CheckboxProps$1} from './components-shared.d.ts';
 
 /**
- * Used when an element does not have children.
+ * The base properties for elements that don't have children, providing essential attributes like keys and refs for component management.
  */
 export interface BaseElementProps<TClass = HTMLElement> {
+    /**
+     * A unique identifier for this element within its parent. This is used by the rendering engine for efficient reconciliation when lists change.
+     */
     key?: preact.Key;
+    /**
+     * 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 the element to a named slot in a parent component that uses slot-based composition patterns.
+     */
     slot?: Lowercase<string>;
 }
 /**
  * An event type that narrows the `currentTarget` to the specific HTML element associated with the custom element tag. This provides type-safe event handling in callback listeners.
+ * @publicDocs
  */
 export type CallbackEvent<TTagName extends keyof HTMLElementTagNameMap, TEvent extends Event = Event> = TEvent & {
     currentTarget: HTMLElementTagNameMap[TTagName];
 };
 /**
  * A typed event listener for custom element events. The listener receives a `CallbackEvent` with the correct `currentTarget` type for the associated custom element tag.
+ * @publicDocs
  */
 export type CallbackEventListener<TTagName extends keyof HTMLElementTagNameMap, TData = object> = (EventListener & {
     (event: CallbackEvent<TTagName, Event> & TData): void;
@@ -33,9 +44,16 @@ export type CallbackEventListener<TTagName extends keyof HTMLElementTagNameMap,
 
 declare const tagName = "s-checkbox";
 /** @publicDocs */
-export interface CheckboxElementProps extends Pick<CheckboxProps$1, 'accessibilityLabel' | 'checked' | 'command' | 'commandFor' | 'defaultChecked' | 'disabled' | 'error' | 'id' | 'label' | 'name' | 'required' | 'value'> {
+export interface CheckboxElementProps extends Pick<CheckboxProps$1, 'accessibilityLabel' | 'checked' | 'command' | 'commandFor' | 'defaultChecked' | 'disabled' | 'error' | 'id' | 'name' | 'required' | 'value'> {
     command?: Extract<CheckboxProps$1['command'], '--auto' | '--show' | '--hide' | '--toggle'>;
+    /**
+     * The visual content to use as the control label. Use a string to provide a simple text label displayed to the user.
+     *
+     * If a `label` slot is also provided, the slot content takes precedence. [Learn more about slots](/docs/api/{API_NAME}/{API_VERSION}/web-components/forms/checkbox#slots-propertydetail-label).
+     */
+    label?: string;
 }
+/** @publicDocs */
 export interface CheckboxEvents extends Pick<CheckboxProps$1, 'onChange'> {
 }
 /** @publicDocs */
@@ -47,9 +65,20 @@ export interface CheckboxElementEvents {
      */
     change?: CallbackEventListener<typeof tagName>;
 }
+/** @publicDocs */
 export interface CheckboxElement extends CheckboxElementProps, Omit<HTMLElement, 'id' | 'onchange'> {
     onchange: CheckboxEvents['onChange'];
 }
+/** @publicDocs */
+export interface CheckboxElementSlots {
+    /**
+     * The visual content to use as the control label.
+     *
+     * Use an `HTMLElement` as a rich control label composed of elements. Only an `s-text` element is supported with plain text and `s-link` as its only allowed children. Any other elements are stripped while preserving their text content.
+     */
+    label?: HTMLElement;
+}
+/** @publicDocs */
 export interface CheckboxProps extends CheckboxElementProps, CheckboxEvents {
 }
 declare global {
@@ -65,4 +94,4 @@ declare module 'preact' {
     }
 }
 
-export type { CheckboxElement, CheckboxElementEvents, CheckboxElementProps, CheckboxEvents, CheckboxProps };
+export type { CheckboxElement, CheckboxElementEvents, CheckboxElementProps, CheckboxElementSlots, CheckboxEvents, CheckboxProps };

package/build/ts/surfaces/customer-account/components/Clickable.d.ts

@@ -65,6 +65,16 @@ export interface ClickableElementProps extends Pick<ClickableProps$1, 'accessibi
     borderWidth?: MaybeAllValuesShorthandProperty<ReducedBorderSizeKeyword> | '';
     borderRadius?: MaybeAllValuesShorthandProperty<Extract<ClickableProps$1['borderRadius'], 'none' | 'small-100' | 'small' | 'base' | 'large' | 'large-100' | 'max'>>;
     target?: Extract<ClickableProps$1['target'], 'auto' | '_blank'>;
+    /**
+     * The behavioral type of the clickable component, which determines what action it performs when activated.
+     *
+     * - `submit`: Submits the nearest containing form.
+     * - `button`: Performs no default action, relying on the `click` event handler for behavior.
+     *
+     * This property is ignored if `href` or `commandFor`/`command` is set.
+     *
+     * @default 'button'
+     */
     type?: Extract<ClickableProps$1['type'], 'submit' | 'button'>;
 }
 export interface ClickableEvents extends Pick<ClickableProps$1, 'onBlur' | 'onClick' | 'onFocus'> {

package/build/ts/surfaces/customer-account/components/Paragraph.d.ts

@@ -11,7 +11,7 @@
 import type {ParagraphProps$1} from './components-shared.d.ts';
 
 /**
- * Used when an element does not have children.
+ * The base properties for elements that don't have children, providing essential attributes like keys and refs for component management.
  */
 export interface BaseElementProps<TClass = HTMLElement> {
     key?: preact.Key;
@@ -19,7 +19,8 @@ export interface BaseElementProps<TClass = HTMLElement> {
     slot?: Lowercase<string>;
 }
 /**
- * Used when an element has children.
+ * The base properties for elements that have children, extending `BaseElementProps` with children support.
+ * @publicDocs
  */
 export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends BaseElementProps<TClass> {
     children?: preact.ComponentChildren;
@@ -31,19 +32,17 @@ export interface ParagraphElementProps extends Pick<ParagraphProps$1, 'accessibi
     color?: Extract<ParagraphProps$1['color'], 'subdued' | 'base'>;
     tone?: Extract<ParagraphProps$1['tone'], 'auto' | 'info' | 'success' | 'warning' | 'critical' | 'neutral' | 'custom'>;
     /**
-     * The semantic type and styling treatment for the paragraph content.
+     * Sets the alignment of the text.
+     * @see https://developer.mozilla.org/en-US/docs/Web/CSS/text-align
      *
-     * Other presentation properties on `s-paragraph` override the default styling.
-     *
-     * - `paragraph`: A semantic type that indicates the text is a structural grouping of related content.
-     * - `small`: A semantic type that indicates the text is considered less important than the main content, but is still necessary for the reader to understand.
-     *
-     * @default 'paragraph'
+     * @default 'auto'
      */
-    type?: Extract<ParagraphProps$1['type'], 'paragraph' | 'small'>;
+    textAlign?: 'start' | 'end' | 'center' | 'auto';
 }
+/** @publicDocs */
 export interface ParagraphElement extends ParagraphElementProps, Omit<HTMLElement, 'id' | 'dir' | 'lang'> {
 }
+/** @publicDocs */
 export interface ParagraphProps extends ParagraphElementProps {
 }
 declare global {

package/build/ts/surfaces/customer-account/components/components-shared.d.ts

@@ -822,6 +822,8 @@ interface BadgeProps$1 extends GlobalProps {
 	/**
 	 * An icon displayed inside the badge to provide additional visual context or reinforce the badge's meaning. Set to an empty string to display no icon.
 	 *
+	 * Always positioned relative to the text content. Independent positioning isn't supported.
+	 *
 	 * @default ''
 	 */
 	icon?: IconType | AnyString;
@@ -1410,10 +1412,12 @@ export interface LinkBehaviorProps extends InteractionProps, FocusEventProps {
 export interface InteractionProps {
 	/**
 	 * The ID of the component to control when this component is activated. Pair with the `command` property to specify what action to perform on the target component. Learn more about the [`commandFor` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#commandfor).
+	 *
+	 * When both `commandFor` and `href` are set, `commandFor` takes precedence. The command runs and the link doesn't navigate.
 	 */
 	commandFor?: string;
 	/**
-	 * Sets the action the [`command`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command) should take when this component is activated. Available options:
+	 * Sets the action the `commandFor` target should take when this component is activated. Available options:
 	 *
 	 * - `'--auto'`: Performs the default action appropriate for the target component.
 	 * - `'--show'`: Displays the target component if it's currently hidden.
@@ -1421,7 +1425,7 @@ export interface InteractionProps {
 	 * - `'--toggle'`: Alternates the target component between visible and hidden states.
 	 * - `'--copy'`: Copies the target clipboard item.
 	 *
-	 * The supported actions vary by target component type.
+	 * The supported actions vary by target component type. Learn more about the [`command` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command).
 	 *
 	 * @default '--auto'
 	 */
@@ -1537,6 +1541,8 @@ export interface MultipleInputProps extends BaseInputProps {
 	 * An array of `value` attributes for the currently selected options.
 	 *
 	 * This is a convenience prop for setting the `selected` prop on child options.
+	 *
+	 * Form data captures the selected value strings only. Complex nested content inside choices is for display purposes and isn't included in form submissions.
 	 */
 	values?: string[];
 }
@@ -1805,6 +1811,8 @@ interface CheckboxProps$1 extends GlobalProps, BaseCheckableProps, FieldErrorPro
 	 * If you want to present an error when this field is empty, you can do
 	 * so with the `error` property.
 	 *
+	 * Adds semantic meaning for accessibility. Doesn't trigger automatic validation or display an error. Implement validation logic yourself and use the `error` prop to show results.
+	 *
 	 * @default false
 	 */
 	required?: boolean;
@@ -1906,6 +1914,8 @@ interface ChoiceListProps$1 extends GlobalProps, Pick<BasicFieldProps, "label" |
 	 * - `block`: The choices are displayed on the block axis.
 	 * - `grid`: The choices are displayed in a grid.
 	 *
+	 * The selected content slot is supported only in the default (stacked) variant. `inline` and `grid` ignore it.
+	 *
 	 * @implementation The `block`, `inline` and `grid` variants are more suitable for button looking choices, but it's at the
 	 * discretion of each surface.
 	 *
@@ -1969,6 +1979,8 @@ interface ClickableChipProps$1 extends ChipProps$1, GlobalProps {
 	 *
 	 * If the chip is not `removable`, it can still be hidden by setting this property.
 	 *
+	 * When using the `removable` variant, keep `hidden` synced with your app state. If `hidden` isn't updated after the chip is removed, the chip can become permanently hidden.
+	 *
 	 * @default false
 	 */
 	hidden?: boolean;
@@ -1993,6 +2005,8 @@ interface ClipboardItemProps$1 extends GlobalProps {
 	/**
 	 * Plain text to be written to the clipboard.
 	 *
+	 * Rich text, HTML, and binary content aren't supported.
+	 *
 	 * @default ''
 	 */
 	text?: string;
@@ -2051,6 +2065,8 @@ export type ConsentPolicy = "sms-marketing";
 interface ConsentCheckboxProps$1 extends GlobalProps, CheckboxProps$1 {
 	/**
 	 * The policy for which user consent is being collected.
+	 *
+	 * Only `sms-marketing` is supported. Other consent policy types aren't available through this component.
 	 */
 	policy?: ConsentPolicy;
 }
@@ -2059,6 +2075,8 @@ interface PhoneFieldProps$1 extends GlobalProps, BaseTextFieldProps, Pick<FieldD
 	/**
 	 * The type of phone number to collect. Specific styling may be applied to each type to provide extra guidance to users. No additional validation is performed based on the type.
 	 *
+	 * Styling hint for the input keyboard. Doesn't validate the phone number format. Implement validation in your extension and use the `error` prop to show results.
+	 *
 	 * @default ''
 	 */
 	type?: "mobile" | "";
@@ -2066,6 +2084,8 @@ interface PhoneFieldProps$1 extends GlobalProps, BaseTextFieldProps, Pick<FieldD
 interface ConsentPhoneFieldProps$1 extends GlobalProps, PhoneFieldProps$1 {
 	/**
 	 * The policy for which user consent is being collected.
+	 *
+	 * Only `sms-marketing` is supported.
 	 */
 	policy?: ConsentPolicy;
 }
@@ -2119,6 +2139,8 @@ interface DatePickerProps$1 extends GlobalProps, InputProps, FocusEventProps {
 	 *       So `--2024` is equivalent to `--2024-12-31`.
 	 *     - Whitespace is allowed either side of `--`.
 	 *
+	 * Comma-separated list of allowed dates in `YYYY-MM-DD` format.
+	 *
 	 * @default ""
 	 *
 	 * @example
@@ -2146,6 +2168,8 @@ interface DatePickerProps$1 extends GlobalProps, InputProps, FocusEventProps {
 	 *       So `--2024` is equivalent to `--2024-12-31`.
 	 *     - Whitespace is allowed either side of `--`.
 	 *
+	 * Comma-separated list of disallowed dates in `YYYY-MM-DD` format.
+	 *
 	 * @default ""
 	 *
 	 * @example
@@ -2210,6 +2234,8 @@ interface DatePickerProps$1 extends GlobalProps, InputProps, FocusEventProps {
 	 * - If `type="multiple"`, this is a comma-separated list of dates in `YYYY-MM-DD` format.
 	 * - If `type="range"`, this is a range in `YYYY-MM-DD--YYYY-MM-DD` format. The range is inclusive.
 	 *
+	 * Single dates use ISO 8601 format (`YYYY-MM-DD`); ranges use `YYYY-MM-DD--YYYY-MM-DD`. Locale-specific formats aren't supported.
+	 *
 	 * @default ""
 	 */
 	value?: string;
@@ -2280,7 +2306,7 @@ interface DividerProps$1 extends GlobalProps {
 	 * The orientation of the divider, using [logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values).
 	 *
 	 * - `inline`: A horizontal divider that separates content stacked vertically.
-	 * - `block`: A vertical divider that separates content arranged horizontally.
+	 * - `block`: A vertical divider that separates content arranged horizontally. Requires a parent with a defined height to render visibly.
 	 *
 	 * @default 'inline'
 	 */
@@ -2327,6 +2353,9 @@ interface DropZoneProps$1 extends GlobalProps, FileInputProps, BasicFieldProps {
 	 */
 	onDropRejected?: (event: Event) => void;
 }
+/**
+ * Doesn't perform automatic format validation. Implement validation logic yourself and use the `error` prop to display results.
+ */
 interface EmailFieldProps$1 extends GlobalProps, BaseTextFieldProps, MinMaxLengthProps, AutocompleteProps<EmailAutocompleteField> {
 }
 export type EmailAutocompleteField = ExtractStrict<AnyAutocompleteField, "email" | `${AutocompleteAddressGroup} email`>;

package/build/ts/surfaces/customer-account/components/components.d.ts

@@ -115,7 +115,7 @@ export interface ToggleEventProps {
 	 * - If the element transitioned from showing to hidden, the `oldState` property will be set to `open` and the
 	 *   `newState` will be `closed`.
 	 *
-	 * Learn more about [ToggleEvent.newState](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState) and [ToggleEvent.oldState](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState).
+	 * Learn more about [`newState` property](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState) and [`oldState` property](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState).
 	 */
 	onAfterToggle?: (event: ToggleEvent$1) => void;
 	/**
@@ -126,7 +126,7 @@ export interface ToggleEventProps {
 	 * - If the element is transitioning from showing to hidden, then `oldState` property will be set to `open` and the
 	 *   `newState` will be `closed`.
 	 *
-	 * Learn more about the [toggle event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/toggle_event), [ToggleEvent.newState](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState), and [ToggleEvent.oldState](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState).
+	 * Learn more about the [`toggle` event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/toggle_event), [`newState` property](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/newState), and [`oldState` property](https://developer.mozilla.org/en-US/docs/Web/API/ToggleEvent/oldState).
 	 */
 	onToggle?: (event: ToggleEvent$1) => void;
 }
@@ -1390,15 +1390,11 @@ export interface LinkBehaviorProps extends InteractionProps, FocusEventProps {
 }
 export interface InteractionProps {
 	/**
-	 * ID of a component that should respond to activations (e.g. clicks) on this component.
-	 *
-	 * Pair with the `command` property to specify what action to perform on the target component.
-	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#commandfor
+	 * The ID of the component to control when this component is activated. Pair with the `command` property to specify what action to perform on the target component. Learn more about the [`commandFor` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#commandfor).
 	 */
 	commandFor?: string;
 	/**
-	 * Sets the action the `commandFor` should take when this clickable is activated.
+	 * Sets the action the `commandFor` target should take when this component is activated.
 	 *
 	 * See the documentation of particular components for the actions they support.
 	 *
@@ -1410,11 +1406,11 @@ export interface InteractionProps {
 	 *
 	 * @default '--auto'
 	 *
-	 * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command
+	 * Learn more about the [`command` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command).
 	 */
 	command?: "--auto" | "--show" | "--hide" | "--toggle" | "--copy";
 	/**
-	 * ID of a component that should respond to interest (e.g. hover and focus) on this component.
+	 * The ID of the component to show when users hover over or focus on this component. Use this to connect interactive components to popovers or tooltips that provide additional context or information.
 	 */
 	interestFor?: string;
 }
@@ -1481,7 +1477,7 @@ export interface BaseInputProps {
 }
 export interface InputProps extends BaseInputProps {
 	/**
-	 * Callback when the user has **finished editing** a field, e.g. once they have blurred the field.
+	 * Callback when the user has **finished editing** a field, such as once they have blurred the field.
 	 *
 	 * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event
 	 */
@@ -2521,8 +2517,8 @@ export interface BaseTypographyProps {
 	/**
 	 * Indicates the directionality of the element’s text.
 	 *
-	 * - `ltr`: languages written from left to right (e.g. English)
-	 * - `rtl`: languages written from right to left (e.g. Arabic)
+	 * - `ltr`: languages written from left to right (such as English)
+	 * - `rtl`: languages written from right to left (such as Arabic)
 	 * - `auto`: the user agent determines the direction based on the content
 	 * - `''`: direction is inherited from parent elements (equivalent to not setting the attribute)
 	 *

package/build/ts/surfaces/point-of-sale/components/components-shared.d.ts

@@ -1380,27 +1380,21 @@ export interface LinkBehaviorProps extends InteractionProps, FocusEventProps {
 /** @publicDocs */
 export interface InteractionProps {
   /**
-   * ID of a component that should respond to activations (e.g. clicks) on this component.
-   *
-   * See `command` for how to control the behavior of the target.
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#commandfor
+   * The ID of the component to control when this component is activated. Pair with the `command` property to specify what action to perform on the target component. Learn more about the [`commandFor` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#commandfor).
    */
   commandFor?: string;
   /**
-   * Sets the action the `commandFor` should take when this clickable is activated.
+   * Sets the action the `commandFor` target should take when this component is activated. Available options:
    *
-   * See the documentation of particular components for the actions they support.
+   * - `'--auto'`: Performs the default action appropriate for the target component.
+   * - `'--show'`: Displays the target component if it's currently hidden.
+   * - `'--hide'`: Conceals the target component from view.
+   * - `'--toggle'`: Alternates the target component between visible and hidden states.
+   * - `'--copy'`: Copies the target clipboard item.
    *
-   * - `--auto`: a default action for the target component.
-   * - `--show`: shows the target component.
-   * - `--hide`: hides the target component.
-   * - `--toggle`: toggles the target component.
-   * - `--copy`: copies the target ClipboardItem.
+   * The supported actions vary by target component type. Learn more about the [`command` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command).
    *
    * @default '--auto'
-   *
-   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#command
    */
   command?: '--auto' | '--show' | '--hide' | '--toggle' | '--copy';
   /**