@shopify/ui-extensions 2025.7.1 → 2025.7.3

package/src/surfaces/point-of-sale/render/components/List/List.ts

@@ -4,24 +4,24 @@ import {ColorType} from '../Text/Text';
 
 export interface ToggleSwitch {
   /**
-   * Whether or not the toggle switch is on or off.
+   * The current state of the toggle switch. When `true`, the switch is in the "on" position. When `false`, it's in the "off" position.
    */
   value?: boolean;
 
   /**
-   * Whether or not the toggle switch is disabled.
+   * Controls whether the toggle switch can be interacted with. When `true`, the switch is disabled and users cannot change its state.
    */
   disabled?: boolean;
 }
 
 export interface SubtitleType {
   /**
-   * The subtitles to display beneath the main label.
+   * The text content to display as a subtitle beneath the main label.
    */
   content: string;
 
   /**
-   * Property used to modify the subtitle appearance.
+   * The semantic color of the subtitle text that conveys meaning and intent through visual styling.
    */
   color?: ColorType;
 }
@@ -30,25 +30,27 @@ export type ListRowSubtitle = string | SubtitleType;
 
 export interface ListRowLeftSide {
   /**
-   * The main label that will be displayed on the left side of the row.
+   * The main label text displayed prominently on the left side of the row.
    */
   label: string;
   /**
-   * The subtitles to display beneath the main label. Up to 3 subtitles can be displayed.
-   * Subtitles can optionally be configured with colors by passing an object with a `content` and `color` properties.
+   * An array of up to three subtitles displayed beneath the main label. Each subtitle can be a string or an object with content and color properties.
    */
   subtitle?: [ListRowSubtitle, ListRowSubtitle?, ListRowSubtitle?];
   /**
-   * Colored badges that are displayed underneath the `title` and `subtitles`.
+   * An array of colored badges displayed underneath the title and subtitles for additional status or category information.
    */
   badges?: BadgeProps[];
+  /**
+   * An image configuration object for displaying images on the far left side of the row with optional badge overlay.
+   */
   image?: {
     /**
-     * A link to an image to be displayed on the far left side of the row.
+     * A URL to an image to be displayed on the far left side of the row.
      */
     source?: string;
     /**
-     * A number that is displayed on the top right of the image.
+     * A numeric badge displayed on the top right corner of the image, typically used for counts or quantities.
      */
     badge?: number;
   };
@@ -56,65 +58,68 @@ export interface ListRowLeftSide {
 
 export interface ListRowRightSide {
   /**
-   * The main label that will be displayed on the right side of the row.
+   * An optional label text displayed on the right side of the row for additional information or values.
    */
   label?: string;
   /**
-   * Show a chevron. Set this to true if pressing on the row navigates to another screen.
+   * A boolean that controls chevron display. Set to `true` when pressing the row navigates to another screen.
+   *
    * @defaultValue `false`
    */
   showChevron?: boolean;
   /**
-   * A toggle switch that is be displayed on the right side of the row.
+   * A toggle switch configuration object displayed on the right side of the row for boolean settings or states.
    */
   toggleSwitch?: ToggleSwitch;
 }
 
 export interface ListRow {
   /**
-   * The unique identifier for this list item.
+   * The unique identifier for the list item used for tracking and interaction handling.
    */
   id: string;
   /**
-   * The user interface of the left side of the row.
+   * The content configuration for the left side of the row, including label, subtitles, badges, and optional image.
    */
   leftSide: ListRowLeftSide;
   /**
-   * The user interface of the right side of the row.
+   * The content configuration for the right side of the row, including optional label, chevron, and toggle switch.
    */
   rightSide?: ListRowRightSide;
   /**
-   * Callback for when the user taps the row.
+   * A callback function executed when the user taps the row.
    */
   onPress?: () => void;
 }
 
 export interface ListProps {
   /**
-   * A large display title at the top of the `List`.
+   * A large display title shown at the top of the list.
    */
   title?: string;
   /**
-   * A header component for the list.
+   * A header component displayed at the top of the list for additional context or controls.
    */
   listHeaderComponent?: RemoteFragment;
   /**
-   * The array of `ListRow` which will be converted into rows for this list.
+   * An array of ListRow objects that define the content and structure of each row in the list.
    */
   data: ListRow[];
   /**
-   * Whether or not more data is being loaded. Set this to `true` when paginating and fetching more data for the list.
+   * A boolean indicating whether more data is being loaded. Set to `true` when paginating and fetching additional data for the list.
    */
   isLoadingMore?: boolean;
   /**
-   * The logic behind displaying an image or placeholder. `automatic` will display an image or placeholder if it detects
-   * that a `ListItem` in `data` has an `imageUri` value. `never` will never display images or placeholders. `always` will
-   * always display images or placeholders if `imageUri` is undefined or empty.
+   * The logic for displaying images or placeholders:
+   * - `automatic`: Displays images or placeholders only when it detects that a ListRow has an image source value.
+   * - `always`: Displays images or placeholders for all rows, even when image sources are undefined or empty.
+   * - `never`: Hides all images and placeholders, creating a text-only list layout.
+   *
    * @defaultValue `automatic`
    */
   imageDisplayStrategy?: 'automatic' | 'always' | 'never';
   /**
-   * Callback for when the user reaches the end of the `List`. This can be used to fire a request to load more data.
+   * A callback function executed when the user reaches the end of the list. Use this to trigger requests for loading additional data.
    */
   onEndReached?: () => void;
 }

package/src/surfaces/point-of-sale/render/components/Navigator/Navigator.ts

@@ -1,11 +1,8 @@
 import {createRemoteComponent} from '@remote-ui/core';
 
-/**
- * @property `initialScreenName` sets the initial `Screen` whose `name` matches.
- */
 export interface NavigatorProps {
   /**
-   * Sets the initial `Screen` whose `name` matches.
+   * The name of the initial `Screen` component to display when the Navigator is first rendered. Must match the `name` property of a child `Screen` component.
    */
   initialScreenName?: string;
 }

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

@@ -1,19 +1,19 @@
 import {createRemoteComponent} from '@remote-ui/core';
 import type {InputProps} from '../shared/InputField';
 
-/**
- * Represents the properties for the NumberField component.
- * @typedef {Object} NumberFieldProps
- * @property {'decimal' | 'numeric'} [inputMode] - The mode of input, can be either 'decimal' or 'numeric'.
- */
 export interface NumberFieldProps extends InputProps {
+  /**
+   * The virtual keyboard layout to display:
+   * - `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.
+   */
   inputMode?: 'decimal' | 'numeric';
   /**
-   * The highest decimal or integer to be accepted for the field.
+   * The highest decimal or integer to be accepted for the field. Users can still input higher numbers by keyboard—you must add appropriate validation logic.
    */
   max?: number;
   /**
-   * The lowest decimal or integer to be accepted for the field.
+   * The lowest decimal or integer to be accepted for the field. Users can still input lower numbers by keyboard—you must add appropriate validation logic.
    */
   min?: number;
 }

package/src/surfaces/point-of-sale/render/components/POSBlock/POSBlock.ts

@@ -1,26 +1,22 @@
 import {createRemoteComponent} from '@remote-ui/core';
 
-/**
- * Renders a `POSBlock`. Note that the text displayed on this `POSBlock`
- * is dependent on the description of the extension. A `POSBlock` only
- * accepts `POSBlockRow` as children.
- */
 export interface POSBlockProps {
   /**
-   * Sets an optional action button to be displayed on the `POSBlock`.
+   * An optional action button configuration to be displayed on the `POSBlock`.
    */
   action?: {
     /**
-     * The title of the action button.
+     * The text displayed on the action button. Use clear, action-oriented language like "View Details" or "Update Status."
      */
     title: string;
     /**
-     * Whether the action button is disabled.
+     * Controls whether the action button can be pressed. When `true`, the button is disabled and users cannot interact with it.
+     *
      * @defaultValue false
      */
     disabled?: boolean;
     /**
-     * A callback that is called when the action button is pressed.
+     * A callback function executed when the action button is pressed. Use this to handle user interactions such as navigation or triggering specific actions.
      */
     onPress: () => void;
   };

package/src/surfaces/point-of-sale/render/components/POSBlock/POSBlockRow.ts

@@ -1,11 +1,8 @@
 import {createRemoteComponent} from '@remote-ui/core';
 
-/**
- * Renders a `POSBlockRow` in a `POSBlock`.
- */
 export interface POSBlockRowProps {
   /**
-   * A callback for when the row is tapped.
+   * A callback function executed when the user taps the row. Use this to handle row-specific interactions or navigation.
    */
   onPress?: () => void;
 }

package/src/surfaces/point-of-sale/render/components/POSReceiptBlock/POSReceiptBlock.ts

@@ -2,10 +2,6 @@ import {createRemoteComponent} from '@remote-ui/core';
 import {QRCode} from '../QRCode/QRCode';
 import {Text} from '../Text/Text';
 
-/**
- * Renders a `POSReceiptBlock`. A `POSReceiptBlock` only accepts
- * `Text` and `QRCode` as children (more to be added in the future).
- */
 export interface POSReceiptBlockProps {}
 export type AllowedChildrenComponents = typeof Text | typeof QRCode;
 

package/src/surfaces/point-of-sale/render/components/PinPad/PinPad.ts

@@ -1,72 +1,69 @@
 import {createRemoteComponent} from '@remote-ui/core';
 
 /**
- * Represents the result of the pin pad onSubmit function.
- * @typedef {('accept'|'reject')} PinValidationResult
+ * Defines the validation result values that the `onSubmit` callback must return to indicate PIN verification status.
+ *
+ * Available values:
+ * - `accept`: A validation result indicating the PIN is correct and authentication was successful.
+ * - `reject`: A validation result indicating the PIN is incorrect and authentication failed.
  */
 export type PinValidationResult = 'accept' | 'reject';
 
 /**
- * Represents the allowed lengths of a PIN.
- * @typedef {(4|5|6|7|8|9|10)} PinLength
+ * Defines the allowed PIN length values that constrain how many digits users can enter.
+ *
+ * Available lengths:
+ * - `4`: A four-digit PIN length, commonly used for basic security codes and quick authentication.
+ * - `5`: A five-digit PIN length for moderate security requirements.
+ * - `6`: A six-digit PIN length, commonly used for enhanced security codes and verification.
+ * - `7`: A seven-digit PIN length for higher security requirements.
+ * - `8`: An eight-digit PIN length for strong security and complex authentication scenarios.
+ * - `9`: A nine-digit PIN length for very high security requirements.
+ * - `10`: A ten-digit PIN length, the maximum supported for highly secure authentication workflows.
  */
 export type PinLength = 4 | 5 | 6 | 7 | 8 | 9 | 10;
 
 /**
- * Represents an action type for the PinPad component.
- * @typedef {Object} PinPadActionType
- * @property {string} label - The label for the action button.
- * @property {function(): number[]} onPress - The function to be called when the action button is pressed.
+ * Defines the configuration object for action buttons displayed between the PIN entry view and keypad.
  */
 export interface PinPadActionType {
   /**
-   * The label for the action button.
+   * The label text displayed on the action button.
    */
   label: string;
   /**
-   * The function to be called when the action button is pressed.
+   * A callback function executed when the action button is pressed, returning the current PIN as an array of numbers.
    */
   onPress: () => Promise<number[]>;
 }
 
-/**
- * Represents the properties for the PinPad component.
- * @typedef {Object} PinPadProps
- * @property {boolean} [masked] - Whether the entered PIN should be masked.
- * @property {PinLength} [minPinLength] - The minimum length of the PIN.
- * @property {PinLength} [maxPinLength] - The maximum length of the PIN.
- * @property {string} [label] - The content for the prompt on the pin pad.
- * @property {PinPadActionType} [pinPadAction] - The call to action between the entry view and the keypad, consisting of a label and function that returns the pin.
- * @property {function(pin: number[]): Promise<PinValidationResult>} onSubmit - The function to be called when the PIN is submitted.
- * @property {function(pin: number[]): void} [onPinEntry] - The function to be called when a PIN is entered.
- */
 export interface PinPadProps {
   /**
-   * Whether the entered PIN should be masked.
+   * A boolean that determines whether the entered PIN should be masked with dots or asterisks to protect privacy and security.
    */
   masked?: boolean;
   /**
-   * The minimum length of the PIN.
+   * The minimum length of the PIN that users must enter before submission is allowed.
    */
   minPinLength?: PinLength;
   /**
-   * The maximum length of the PIN.
+   * The maximum length of the PIN that users can enter, constraining the number of digits.
    */
   maxPinLength?: PinLength;
   /**
-   * The content for the prompt on the pin pad.
+   * The content for the prompt displayed on the pin pad that instructs users what to enter.
    */
   label?: string;
   /**
-   * The call to action between the entry view and the keypad, consisting of a label and function that returns the pin.
+   * A call-to-action configuration displayed between the entry view and the keypad, consisting of a label and function that returns the current PIN.
    */
   pinPadAction?: PinPadActionType;
   /**
-   * The function to be called when the PIN is submitted.
+   * A callback function executed when the PIN is submitted, receiving the PIN as an array of numbers. Must return a Promise that resolves to either `'accept'` or `'reject'` to indicate validation success or failure.
    */
   onSubmit: (pin: number[]) => Promise<PinValidationResult>;
   /**
-   * The function to be called when a PIN is entered.
+   * A callback function executed when a PIN is entered, receiving the PIN as an array of numbers. Use this for real-time feedback or validation during PIN entry.
    */
   onPinEntry?: (pin: number[]) => void;
 }

package/src/surfaces/point-of-sale/render/components/PrintPreview/PrintPreview.ts

@@ -2,17 +2,7 @@ import {createRemoteComponent} from '@remote-ui/core';
 
 export interface PrintPreviewProps {
   /**
-   * The source to print.
-   *
-   * The src must be either:
-   * - A relative path that will be appended to your app's [application_url](/docs/apps/build/cli-for-apps/app-configuration#application_url)
-   * - A full URL to your app's backend that will be used to return the document
-   *
-   * Supported document types:
-   * - HTML documents (recommended for best printing experience)
-   * - Text files
-   * - Image files (PNG, JPEG, etc.)
-   * - PDF files
+   * The source URL of the content to preview for printing. Must be either a relative path appended to your app's [`application_url`](/docs/apps/build/cli-for-apps/app-configuration) or a full URL to your app's backend that returns the document.
    */
   src: string;
 }

package/src/surfaces/point-of-sale/render/components/QRCode/QRCode.ts

@@ -1,12 +1,8 @@
 import {createRemoteComponent} from '@remote-ui/core';
 
-/**
- * The `QRCode` component renders a QR code in Shopify POS.
- * @property `value` the content to be encoded in the QR code.
- */
 export interface QRCodeProps {
   /**
-   * The content to be encoded in the QR code.
+   * The content to be encoded in the QR code. Can be any string such as a URL, email address, plain text, phone number, or formatted data. Specific string formatting can trigger actions on the user's device when scanned, like opening apps, preparing messages, or navigating to locations.
    */
   value: string;
 }

package/src/surfaces/point-of-sale/render/components/RadioButtonList/RadioButtonList.ts

@@ -2,19 +2,19 @@ import {createRemoteComponent} from '@remote-ui/core';
 
 export interface RadioButtonListProps {
   /**
-   * 	The radio button options.
+   * An array of string values representing the radio button options available for selection.
    */
   items: string[];
   /**
-   * A callback to be performed when the radio list item is selected.
+   * A callback function executed when a radio list item is selected, receiving the selected item string as a parameter. You must update the `initialSelectedItem` property in response to this callback to reflect the new selection.
    */
   onItemSelected: (item: string) => void;
   /**
-   * The name of the selected item. Warning: This is a controlled component, so this prop must be used in conjunction with onItemSelected.
+   * The name of the currently selected item. You control the selection by setting this property and updating it when `onItemSelected` fires.
    */
   initialSelectedItem?: string;
   /**
-   * Whether the initialSelectedItem renders at the top of the list.
+   * A boolean that determines whether the initially selected item renders at the top of the list, automatically scrolling to show the selected option.
    */
   initialOffsetToShowSelectedItem?: boolean;
 }

package/src/surfaces/point-of-sale/render/components/Screen/Screen.ts

@@ -1,82 +1,62 @@
 import {createRemoteComponent} from '@remote-ui/core';
 
-/** Represents the presentation of a screen in the navigation stack.
- * @property `sheet` displays the screen from the bottom on `navigate` when `true`.
- */
 export interface ScreenPresentationProps {
   /**
-   * Displays the screen from the bottom on `navigate` when `true`.
+   * Displays the screen from the bottom as a sheet presentation when true during navigation. The text label displayed on the secondary action button in the screen's action bar.
    */
   sheet?: boolean;
 }
 
-/** Represents the secondary action button of a screen in the navigation stack.
- * @property `text` displays the name of the secondary action in the action bar.
- * @property `onPress` triggered when the secondary action button is pressed.
- * @property `isEnabled` sets whether the action can be tapped.
- */
 export interface SecondaryActionProps {
   /**
-   * Displays the name of the secondary action in the action bar.
+   * The text label displayed on the secondary action button in the screen's action bar.
    */
   text: string;
   /**
-   * Triggered when the secondary action button is pressed.
+   * A callback function triggered when the secondary action button is pressed by the user.
    */
   onPress: () => void;
   /**
-   * Sets whether the action can be tapped.
+   * Whether the secondary action button can be tapped and is interactive.
    */
   isEnabled?: boolean;
 }
 
-/** Represents a screen in the navigation stack.
- * @property `name` used to identify this screen as a destination in the navigation stack.
- * @property `title` the title of the screen which will be displayed on the UI.
- * @property `isLoading` displays a loading indicator when `true`. Set this to `true` when performing an asynchronous task, and then to false when the data becomes available to the UI.
- * @property `presentation` dictates how the `Screen` will be presented when navigated to.
- * @property `secondaryAction` displays a secondary action button on the screen.
- * @property `onNavigate` triggered when the screen is navigated to.
- * @property `onNavigateBack` triggered when the user navigates back from this screen. Runs after screen is unmounted.
- * @property `overrideNavigateBack` a callback that allows you to override the secondary navigation action. Runs when screen is mounted.
- * @property `onReceiveParams` a callback that gets triggered when the navigation event completes and the screen receives the parameters.
- */
 export interface ScreenProps {
   /**
-   * Used to identify this screen as a destination in the navigation stack.
+   * The unique identifier used to identify this screen as a destination in the navigation stack.
    */
   name: string;
   /**
-   * The title of the screen which will be displayed on the UI.
+   * The title text of the screen that will be displayed in the UI header.
    */
   title: string;
   /**
-   * Displays a loading indicator when `true`.
-   * Set this to `true` when performing an asynchronous task, and then to false when the data becomes available to the UI.
+   * A boolean that displays a loading indicator when `true`. Set this during asynchronous tasks and return to `false` when data becomes available.
    */
   isLoading?: boolean;
   /**
-   * Dictates how the `Screen` will be presented when navigated to.
+   * The presentation configuration that dictates how the screen will be displayed when navigated to.
    */
   presentation?: ScreenPresentationProps;
   /**
-   * Displays a secondary action button on the screen.
+   * The configuration for a secondary action button displayed on the screen header.
    */
   secondaryAction?: SecondaryActionProps;
   /**
-   * Triggered when the screen is navigated to.
+   * A callback function triggered when the screen is navigated to in the navigation stack.
    */
   onNavigate?: () => void;
   /**
-   * Triggered when the user navigates back from this screen. Runs after screen is unmounted.
+   * A callback function triggered when the user navigates back from this screen. Runs after the screen is unmounted.
    */
   onNavigateBack?: () => void;
   /**
-   * A callback that allows you to override the secondary navigation action. Runs when screen is mounted.
+   * A callback function that allows you to override the default back navigation action. Runs when the screen is mounted.
    */
   overrideNavigateBack?: () => void;
   /**
-   * A callback that gets triggered when the navigation event completes and the screen receives the parameters.
+   * A callback function triggered when the navigation event completes and the screen receives parameters passed during navigation.
    */
   onReceiveParams?: (params: any) => void;
 }

package/src/surfaces/point-of-sale/render/components/SearchBar/SearchBar.ts

@@ -2,31 +2,31 @@ import {createRemoteComponent} from '@remote-ui/core';
 
 export interface SearchBarProps {
   /**
-   * The initial text value in the search bar. This is different from `placeHolder`, which is displayed in the search bar when the search bar doesn't have a populated string.
+   * The initial text value displayed in the search bar when first rendered. This differs from placeholder text which appears when the field is empty.
    */
   initialValue?: string;
   /**
-   * A callback containing the new text value of the search bar.
+   * A callback function executed whenever the text value changes, receiving the new text value as a parameter for real-time search or filtering.
    */
   onTextChange?: (value: string) => void;
   /**
-   * A callback when the search button is tapped.
+   * A callback function executed when the search button is tapped, receiving the current search text as a parameter.
    */
   onSearch: (value: string) => void;
   /**
-   * A callback when the input is focused.
+   * A callback function executed when the search input field receives focus.
    */
   onFocus?: () => void;
   /**
-   * A callback when focus is removed.
+   * A callback function executed when focus is removed from the search input field.
    */
   onBlur?: () => void;
   /**
-   * Whether the text can be changed.
+   * A boolean that determines whether the text can be changed by user input.
    */
   editable?: boolean;
   /**
-   * The placeholder value to display in the search bar when no text is entered.
+   * The placeholder text displayed in the search bar when no text is entered, providing guidance about what users can search for.
    */
   placeholder?: string;
 }

package/src/surfaces/point-of-sale/render/components/Section/Section.ts

@@ -1,31 +1,26 @@
 import {createRemoteComponent} from '@remote-ui/core';
 
-/** Allows the implementation of an action at the top right of a `Section`.
- * @property `title` the title describing the action.
- * @property `onPress` the callback when the action is tapped by the user.
+/**
+ * Defines the configuration object for the action button displayed within the section header.
  */
 export interface SectionHeaderAction {
   /**
-   * The title describing the action.
+   * The title text describing the action that will be displayed on the button.
    */
   title: string;
   /**
-   * The callback when the action is tapped by the user.
+   * A callback function that is executed when the action button is pressed by the user.
    */
   onPress: () => void;
 }
 
-/** Renders content that is bound by a border, with a title and a call to action at the top.
- * @property `title` the title of the section.
- * @property `action` the action in the top right of the section that can be triggered by a tap.
- */
 export interface SectionProps {
   /**
-   * The title of the section.
+   * The title text displayed at the top of the section to describe its content.
    */
   title?: string;
   /**
-   * The action in the top right of the section that can be triggered by a tap.
+   * An optional action configuration displayed in the top right of the section that can be triggered by user interaction.
    */
   action?: SectionHeaderAction;
 }

package/src/surfaces/point-of-sale/render/components/SectionHeader/SectionHeader.ts

@@ -2,28 +2,28 @@ import {createRemoteComponent} from '@remote-ui/core';
 
 export interface SectionHeaderProps {
   /**
-   * Title to be displayed.
+   * The title text displayed in the section header. Provide clear, descriptive text that accurately represents the content section below.
    */
   title: string;
   /**
-   * Action button to be displayed. The SectionHeader must have a `title` for `action` to work.
+   * An optional action button configuration to be displayed alongside the title. The `SectionHeader` must have a title for the action to work properly.
    */
   action?: {
     /**
-     * Label for the action button.
+     * The label text displayed on the action button. Use clear, descriptive labels like "Edit Settings" or "Add Item."
      */
     label: string;
     /**
-     * Function to handle action button press.
+     * A callback function executed when the action button is pressed. Use this to handle user interactions such as navigation or triggering specific actions.
      */
     onPress: () => void;
     /**
-     * Whether or not the action button is disabled.
+     * Controls whether the action button can be pressed. When `true`, the button is disabled and users can't interact with it.
      */
     disabled?: boolean;
   };
   /**
-   * Whether or not the divider line under the SectionHeader should be hidden.
+   * A boolean that controls whether the divider line under the `SectionHeader` should be hidden.
    */
   hideDivider?: boolean;
 }