@shopify/ui-extensions 2025.7.2 → 2025.7.3

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

@@ -1,31 +1,33 @@
 import {createRemoteComponent} from '@remote-ui/core';
-
+/**
+ * Defines the structure and configuration options for individual segments within the `SegmentedControl` component.
+ */
 export interface Segment {
   /**
-   * The id of the segment.
+   * The unique identifier for the segment used for selection tracking and callback identification.
    */
   id: string;
   /**
-   * The label of the segment.
+   * The text label displayed on the segment that users see and interact with.
    */
   label: string;
   /**
-   * Whether the segment is disabled.
+   * Whether the segment is disabled and non-interactive.
    */
   disabled: boolean;
 }
 
 export interface SegmentedControlProps {
   /**
-   * The segments to display.
+   * An array of segment objects that define the available options in the segmented control.
    */
   segments: Segment[];
   /**
-   * The id of the selected segment.
+   * The id of the currently selected segment that determines which option is visually highlighted.
    */
   selected: string;
   /**
-   * A callback when a segment is selected.
+   * A callback function executed when a segment is selected, receiving the selected segment's id as a parameter.
    */
   onSelect: (id: string) => void;
 }

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

@@ -2,11 +2,11 @@ import {createRemoteComponent} from '@remote-ui/core';
 
 export interface SelectableProps {
   /**
-   * The callback on press.
+   * The callback function that's executed when the user taps or presses the selectable component. This is the primary way to handle user interactions with the wrapped content. The function receives no parameters and should contain the logic for what happens when the selection occurs, such as navigation, state updates, or triggering other actions.
    */
   onPress: () => void;
   /**
-   * Whether the selectable reacts to presses.
+   * Controls whether the selectable component responds to user interactions. When set to `true`, the component won't react to taps or presses, the `onPress` callback won't be triggered, and the wrapped content appears non-interactive. Use this to temporarily disable selection during loading states, form validation, or when certain conditions aren't met. When `false` or undefined, the component responds normally to user interactions.
    */
   disabled?: boolean;
 }

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

@@ -6,11 +6,13 @@ import {
   SpacingKeyword,
   GapProps,
 } from '../shared/inner-layouts';
+/* eslint-disable import/no-deprecated */
 import {
   HorizontalSpacing,
   Spacing,
   VerticalSpacing,
 } from '../shared/deprecated-types';
+/* eslint-enable import/no-deprecated */
 
 /**
  *
@@ -20,8 +22,7 @@ type DeprecatedStackDirection = 'vertical' | 'horizontal';
 
 export interface StackProps extends PaddingProps, SizingProps, GapProps {
   /**
-   * Sets how the Stack's children are placed within the Stack.
-   * 'vertical' and 'horizontal' are deprecated. Using these values will use the Stack implementation from 2024-10.
+   * The direction in which children are placed within the `Stack` component. Use `'block'` for vertical arrangement along the block axis without wrapping, or `'inline'` for horizontal arrangement along the inline axis with automatic wrapping.
    *
    * @default 'inline'
    */
@@ -36,85 +37,89 @@ export interface StackProps extends PaddingProps, SizingProps, GapProps {
   alignment?: ContentPosition | ContentDistribution;
 
   /**
-   * Aligns the Stack along the main axis.
+   * The alignment of the `Stack` component along the main axis, controlling how space is distributed between and around content items.
+   * Learn more about [justify-content on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content).
    *
-   * @see https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content
    * @default 'start'
    */
   justifyContent?: ContentPosition | ContentDistribution;
 
   /**
-   * Aligns the Stack along the cross axis.
+   * The alignment of the `Stack` component along the cross axis, controlling how content is distributed when there's extra space.
+   * Learn more about [align-content on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/align-content).
    *
-   * @see https://developer.mozilla.org/en-US/docs/Web/CSS/align-content
    * @default 'start'
    */
   alignContent?: 'stretch' | ContentPosition | ContentDistribution;
 
   /**
-   * Aligns the Stack's children along the cross axis.
+   * The alignment of the `Stack` component's children along the cross axis, controlling how individual items are positioned.
+   * Learn more about [align-items on MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/align-items).
    *
-   * @see https://developer.mozilla.org/en-US/docs/Web/CSS/align-items
    * @default 'stretch'
    */
   alignItems?: 'stretch' | 'baseline' | ContentPosition;
 
   /**
-   * The vertical padding around the stack.
+   * The vertical padding around the `Stack` component.
+   *
    * @deprecated Use the `paddingBlock` prop instead.
    */
+  // eslint-disable-next-line import/no-deprecated
   paddingVertical?: VerticalSpacing;
 
   /**
-   * The horizontal padding around the stack.
+   * The horizontal padding around the `Stack` component.
+   *
    * @deprecated Use the `paddingInline` prop instead.
    */
+  // eslint-disable-next-line import/no-deprecated
   paddingHorizontal?: HorizontalSpacing;
 
   /**
-   * The spacing between each child in the stack.
+   * The spacing between each child in the `Stack` component.
+   *
    * @defaultValue 1
    * @deprecated Use the `gap` prop instead.
    */
+  // eslint-disable-next-line import/no-deprecated
   spacing?: Spacing;
 
   /**
-   * The size of the gap between each child in the stack.
+   * The size of the gap between each child in the `Stack` component.
+   *
    * @defaultValue '0'
    */
   gap?: SpacingKeyword;
 
   /**
-   * Adjust spacing between elements in the block axis.
-   *
-   * This overrides the row value of `gap`.
+   * The spacing between elements in the block axis. Overrides the row value of gap.
    *
    * @default '' - meaning no override
    */
   rowGap?: SpacingKeyword | '';
 
   /**
-   * Adjust spacing between elements in the inline axis.
-   *
-   * This overrides the column value of `gap`.
+   * The spacing between elements in the inline axis. Overrides the column value of gap.
    *
    * @default '' - meaning no override
    */
   columnGap?: SpacingKeyword | '';
 
   /**
-   * Whether the children should be stretched to fill the cross axis.
+   * A boolean that determines whether the children should be stretched to fill the cross axis.
    */
   flexChildren?: boolean;
 
   /**
-   * The flex value for the stack. Flex 1 will stretch the stack to fill the parent.
+   * The flex value for the `Stack` component. A value of 1 will stretch the component to fill the parent container.
    */
   flex?: number;
 
   /**
-   * Wrap behavior for the children of the stack.
-   * @deprecated Has no effect, content will always wrap.
+   * The wrap behavior for the children of the `Stack` component.
+   *
+   * @deprecated This property has no effect as content will always wrap.
    */
   flexWrap?: 'wrap' | 'nowrap' | 'wrap-reverse';
 }

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

@@ -2,33 +2,35 @@ import {createRemoteComponent} from '@remote-ui/core';
 
 export interface StepperProps {
   /**
-   * The initial value of the stepper.
+   * The initial value of the stepper that sets the starting numeric value when the component is first rendered.
    */
   initialValue: number;
 
   /**
-   * A callback when the value of the stepper changes.
+   * A callback function executed when the value of the stepper changes, receiving the new numeric value as a parameter.
    */
   onValueChanged: (value: number) => void;
 
   /**
-   * Use to set the minimum value of the stepper.
+   * The minimum value that the stepper can reach. When the value equals the minimum, the decrement button will be disabled.
+   *
    * @defaultValue 1
    */
   minimumValue?: number;
 
   /**
-   * Use to set the maximum value of the stepper.
+   * The maximum value that the stepper can reach. When the value equals the maximum, the increment button will be disabled.
    */
   maximumValue?: number;
 
   /**
-   * Only use this field if you wish to override the internal state of this component.
+   * An optional value to override the internal state of the component. Only use this if you need complete control over the stepper's value from external state.
    */
   value?: number;
 
   /**
-   * Whether the field can be modified.
+   * Whether the field can be modified, disabling both increment and decrement buttons.
+   *
    * @defaultValue false
    */
   disabled?: boolean;

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

@@ -1,5 +1,18 @@
 import {createRemoteComponent} from '@remote-ui/core';
 
+/**
+ * Defines the typography hierarchy options for text elements. Each variant provides specific sizing, weight, and styling appropriate for different content types.
+ *
+ * Available variants:
+ * - `sectionHeader`: A section header variant for titles that organize and introduce content sections.
+ * - `captionRegular`: A regular caption variant for supplementary text, labels, or secondary information.
+ * - `captionRegularTall`: A taller caption variant with increased line height for improved readability in dense layouts.
+ * - `captionMedium`: A medium-weight caption variant for slightly emphasized secondary text or important labels.
+ * - `body`: The standard body text variant for primary content, descriptions, and general text.
+ * - `headingSmall`: A small heading variant for subsection titles and secondary headings.
+ * - `headingLarge`: A large heading variant for main section titles and primary headings.
+ * - `display`: The largest display variant for prominent titles, hero text, or major interface elements.
+ */
 export type TextVariant =
   | 'sectionHeader'
   | 'captionRegular'
@@ -10,6 +23,19 @@ export type TextVariant =
   | 'headingLarge'
   | 'display';
 
+/**
+ * Defines the semantic color options for text elements. Each color conveys specific meaning and intent through visual styling.
+ *
+ * Available colors:
+ * - `TextNeutral`: A neutral text color for general content that doesn't convey specific semantic meaning.
+ * - `TextSubdued`: A subdued text color for secondary information, captions, or content that should be less prominent.
+ * - `TextDisabled`: A disabled text color for inactive or unavailable content that users can't interact with.
+ * - `TextWarning`: A warning text color for cautionary messages or content that requires user attention.
+ * - `TextCritical`: A critical text color for errors, failures, or destructive actions that require immediate attention.
+ * - `TextSuccess`: A success text color for positive outcomes, confirmations, or completed actions.
+ * - `TextInteractive`: An interactive text color for clickable elements, links, or content that users can interact with.
+ * - `TextHighlight`: A highlight text color for emphasized content that needs to stand out or draw special attention.
+ */
 export type ColorType =
   | 'TextNeutral'
   | 'TextSubdued'
@@ -22,11 +48,11 @@ export type ColorType =
 
 export interface TextProps {
   /**
-   * The text variant.
+   * The typography variant that determines the size, weight, and styling of the text within the design system hierarchy.
    */
   variant?: TextVariant;
   /**
-   * The text color.
+   * The semantic color of the text that conveys meaning and intent through visual styling.
    */
   color?: ColorType;
 }

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

@@ -1,14 +1,9 @@
 import {createRemoteComponent} from '@remote-ui/core';
 import type {InputProps} from '../shared/InputField';
 
-/**
- * Represents the properties for the TextField component.
- * @typedef {Object} TextAreaProps
- * @property {number} [rows] - The initial number of lines to be displayed. Maximum of 8 lines.
- */
 export interface TextAreaProps extends InputProps {
   /**
-   * The initial number of lines to be displayed. Maximum of 8 lines.
+   * The initial number of visible text lines to be displayed. Maximum of 8 lines.
    */
   rows?: number;
 }

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

@@ -2,24 +2,54 @@ import {createRemoteComponent} from '@remote-ui/core';
 import type {InputProps} from '../shared/InputField';
 
 export interface ActionProps {
+  /**
+   * Identifies this as an action-type embedded element.
+   */
   type: 'action';
+  /**
+   * The message or label text displayed for the action.
+   */
   message: string;
+  /**
+   * A callback function executed when the action button is pressed, receiving the current field value as a parameter.
+   */
   onPress: (value: string) => void;
 }
 
 export interface InfoProps {
+  /**
+   * Identifies this as an info-type embedded element.
+   */
   type: 'info';
+  /**
+   * The informational message text to display to the user.
+   */
   message: string;
+  /**
+   * Controls whether the info message is always visible or only shown under certain conditions.
+   */
   alwaysShow?: boolean;
 }
 
 export interface SuccessProps {
+  /**
+   * Identifies this as a success-type embedded element.
+   */
   type: 'success';
+  /**
+   * An optional success message to display when the field validation or operation succeeds.
+   */
   message?: string;
 }
 
 export interface PasswordProps {
+  /**
+   * Identifies this as a password-type embedded element.
+   */
   type: 'password';
+  /**
+   * A callback function executed when the password action button is pressed, receiving the current field value as a parameter.
+   */
   onPress: (value: string) => void;
 }
 

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

@@ -1,37 +1,28 @@
 import {createRemoteComponent} from '@remote-ui/core';
 
-/**
- * @property `title` the text set on the main label of the tile.
- * @property `subtitle` the text set on the secondary label of the tile.
- * @property `enabled` sets whether or not the tile can be tapped.
- * @property `destructive` sets whether or not the tile has a destructive appearance and active state as of POS
- * 10.0.0.
- * @property `badgeValue` the number value displayed in the top right corner of the tile.
- * @property `onPress` the callback that is executed when the tile is tapped.
- */
 export interface TileProps {
   /**
-   * The text set on the main label of the tile.
+   * The text displayed as the main label of the tile.
    */
   title: string;
   /**
-   * The text set on the secondary label of the tile.
+   * The text displayed as the secondary label below the title.
    */
   subtitle?: string;
   /**
-   * Sets whether or not the tile can be tapped.
+   * Whether the tile can be tapped and responds to user interaction. When disabled, the tile appears dimmed and doesn't respond to tap events.
    */
   enabled?: boolean;
   /**
-   * Sets whether or not the tile is in a red destructive appearance.
+   * Sets whether the tile appears in a destructive/warning state. As of POS 10.0.0, this property creates an "active state" appearance rather than just red coloring.
    */
   destructive?: boolean;
   /**
-   * The number value displayed in the top right corner of the tile.
+   * A numeric value displayed as a small badge in the top right corner of the tile.
    */
   badgeValue?: number;
   /**
-   * The callback that is executed when the tile is tapped.
+   * The callback function that's executed when users tap the tile.
    */
   onPress?: () => void;
 }

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

@@ -15,7 +15,8 @@ export interface TimeFieldProps
     | 'helpText'
   > {
   /**
-   * (Android only) Whether the clock displays in 24 hour time instead of 12 hour time.
+   * Whether the clock displays in 24-hour format instead of 12-hour format. This property only affects Android devices.
+   *
    * @defaultValue false
    */
   is24Hour?: boolean;

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

@@ -1,17 +1,10 @@
 import {createRemoteComponent} from '@remote-ui/core';
 
-/**
- * Represents the properties for the TimePicker component.
- * @property selected - The selected time.
- * @property onChange - A callback for changes.
- * @property visibleState - Controls the visible state, and a callback to set the visible state as false when the dialog closes.
- * @property is24Hour - (Android only) Whether the clock displays in 24 hour time instead of 12 hour time.
- * @property inputMode - Whether to display the picker in inline (clock) mode or spinner mode.
- */
 export interface TimePickerProps {
   /**
-   * The selected time.
-   * @defaultValue The current time
+   * The currently selected time value. Defaults to the current time when not specified.
+   *
+   * @defaultValue The current time.
    */
   selected?: string;
   /**
@@ -19,17 +12,20 @@ export interface TimePickerProps {
    */
   onChange?(selected: string): void;
   /**
-   * Controls the visible state, and a callback to set the visible state as false when the dialog closes.
+   * A tuple that controls the visible state of the picker and provides a callback to set visibility to false when the dialog closes. The first element is the current visibility state, and the second is a setter function.
    */
   visibleState: [boolean, (visible: boolean) => void];
   /**
-   * (Android only) Whether the clock displays in 24 hour time instead of 12 hour time.
+   * Whether the clock displays in 24-hour format instead of 12-hour format. This property only affects Android devices.
+   *
    * @defaultValue false
    */
   is24Hour?: boolean;
   /**
-   * Whether to display the picker in inline (clock) mode or spinner mode.
-   * iOS only supports 'spinner'.
+   * The display mode for the time picker.
+   * - `inline`: A clock-style interface that displays an analog or digital clock where users can tap to select specific times. Provides visual context about time relationships. Only available on Android devices—iOS always uses spinner mode.
+   * - `spinner`: A spinner-style selector with scrollable columns for hours, minutes, and optionally seconds. Offers a more compact interface suitable for all devices and is the only mode supported on iOS.
+   *
    * @defaultValue 'inline'
    */
   inputMode?: 'inline' | 'spinner';

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

@@ -1,34 +1,26 @@
-/**
- * @property `title` the title of the `TextField`.
- * @property `initialValue` populates the `TextField` with an text initial value.
- * @property `placeholder` sets a placeholder value for when the `TextField` is empty.
- * @property `isValid` set whether the current value in the `TextField` is valid.
- * @property `errorMessage` sets an error message to present to the user.
- * @property `onChangeText` a callback that is executed every time the `TextField` value changes.
- */
 export interface BaseTextFieldProps {
   /**
-   * The title of the `TextField`.
+   * The title text displayed for the text field.
    */
   title?: string;
   /**
-   * Populates the `TextField` with an text initial value.
+   * The initial text value to populate the text field with when it first renders.
    */
   initialValue?: string;
   /**
-   * Sets a placeholder value for when the `TextField` is empty.
+   * A placeholder hint displayed when the text field is empty.
    */
   placeholder?: string;
   /**
-   * Set whether the current value in the `TextField` is valid.
+   * Controls the validation state of the current value in the text field. When `false`, indicates invalid input.
    */
   isValid?: boolean;
   /**
-   * Sets an error message to present to the user.
+   * An error message to display to the user when validation fails.
    */
   errorMessage?: string;
   /**
-   * A callback that is executed every time the `TextField` value changes.
+   * A callback function executed every time the text field value changes, receiving the new value as a parameter.
    */
   onChangeText?: (value: string) => void;
 }

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

@@ -1,69 +1,48 @@
 /**
- * Represents an action type for the text field components.
- * @typedef {Object} InputAction
- * @property {string} label - The text displayed in the button.
- * @property {boolean} [disabled] - Whether the button is disabled.
- * @property {function(): void} onPress - A callback to be performed.
+ * Defines the configuration object for action buttons displayed below input fields to provide extra functionality.
  */
 export interface InputAction {
   /**
-   * The text displayed in the button.
+   * The text displayed on the action button.
    */
   label: string;
   /**
-   * A callback to be performed.
+   * A callback function executed when the action button is pressed.
    */
   onPress: () => void;
   /**
-   * Whether the button can be pressed.
+   * A boolean value that determines whether the action button can be pressed.
    */
   disabled?: boolean;
 }
 
-/**
- * Represents the properties for the text field components.
- * @typedef {Object} InputProps
- * @property {boolean} [disabled] - Whether the field is disabled.
- * @property {string} [error] - Indicate an error to the user. The field will be given a specific stylistic treatment to communicate problems that have to be resolved immediately.
- * @property {string} [label] - Content to use as the field label.
- * @property {function(): void} [onBlur] - Callback when focus is blurred.
- * @property {function(value: string): void} [onChange] - Callback when the user has finished editing a field.
- * @property {function(): void} [onFocus] - Callback when input is focused.
- * @property {function(value: string): void} [onInput] - Callback when the user makes any changes in the field. As noted in the documentation for `onChange`, you **must not** use this to update `value` — use the `onChange` callback for that purpose. Use the `onInput` prop when you need to do something as soon as the user makes a change, like clearing validation errors that apply to the field as soon as the user begins making the necessary adjustments.
- * @property {string} [placeholder] - A short hint that describes the expected value of the field.
- * @property {boolean} [required] - Whether the field needs a value.
- * @property {string} [value] - The current value for the field. If omitted, the field will be empty. You should update this value in response to the `onChange` callback.
- * @property {string} [helpText] - Label under the text field which provides guidance or instructions that assist users.
- * @property {InputAction} [action] - A button under the text field to provide extra functionality.
- * @property {number?} [maxLength] - Specifies the maximum number of characters allowed.
- */
 export interface InputProps {
   /**
-   * Whether the field can be modified.
+   * Controls whether the field can be modified. When `true`, the field is disabled and users cannot edit its value.
    */
   disabled?: boolean;
   /**
-   * Indicates an error to the user. The field is given specific stylistic treatment to communicate problems that have to be resolved immediately.
+   * An error message that indicates a problem to the user. The field is given specific stylistic treatment to communicate issues that must be resolved immediately.
    */
   error?: string;
   /**
-   * The content to use as the field label.
+   * The content to use as the field label that describes the text information being requested.
    */
   label: string;
   /**
-   * The callback when focus is removed.
+   * A callback function executed when focus is removed from the field.
    */
   onBlur?: () => void;
   /**
-   * The callback when the user has finished editing a field.
+   * A callback function executed when the user has finished editing the field, receiving the new text value as a parameter. You should update the `value` property in response to this callback.
    */
   onChange?: (value: string) => void;
   /**
-   * The callback when input is focused.
+   * A callback function executed when the field receives focus.
    */
   onFocus?: () => void;
   /**
-   * Callback when the user makes any changes in the field. As noted in the documentation for `onChange`, you **must not** use this to update `value` — use the `onChange` callback for that purpose. Use the `onInput` prop when you need to do something as soon as the user makes a change, like clearing validation errors that apply to the field as soon as the user begins making the necessary adjustments.
+   * A callback function executed immediately when the user makes any change in the field. Use this for real-time feedback, such as clearing validation errors as soon as the user begins making corrections. Don't use this to update the `value` property—the `onChange` callback is the appropriate handler for updating the field's value.
    */
   onInput?: (value: string) => void;
   /**
@@ -71,23 +50,23 @@ export interface InputProps {
    */
   placeholder?: string;
   /**
-   * Whether the field needs a value.
+   * A boolean that indicates whether the field needs a value for form submission or validation purposes.
    */
   required?: boolean;
   /**
-   * The current value for the field. Defaults to now. You should update this value in response to the `onChange` callback.
+   * The current text value for the field. If omitted, the field will be empty. You should update the `value` property in response to the `onChange` callback.
    */
   value?: string;
   /**
-   * The label under the text field which provides guidance or instructions that assist users.
+   * The label text displayed under the field that provides guidance or instructions to assist users.
    */
   helpText?: string;
   /**
-   * A button under the text field to provide extra functionality.
+   * A button configuration object displayed under the text field to provide extra functionality.
    */
   action?: InputAction;
   /**
-   * The maximum number of characters allowed in the input field.
+   * The maximum number of characters allowed in the text field.
    */
   maxLength?: number;
 }