@shopify/ui-extensions 2024.4.2 → 2024.10.0

package/src/surfaces/point-of-sale/components/FormattedTextField/FormattedTextField.ts

@@ -2,11 +2,32 @@ import {createRemoteComponent} from '@remote-ui/core';
 import type {AutoCapitalizationType} from '../shared/auto-capitalization-type';
 import type {BaseTextFieldProps} from '../shared/BaseTextField';
 
+/**
+ * Dictates what type of values can be used in a `TextField`.
+ */
 export type InputType = 'text' | 'number' | 'currency' | 'giftcard' | 'email';
-
+/**
+ * @property `inputType` the `InputType` of the `TextField`. This will select the appropriate keyboard.
+ * @property `autoCapitalize` dictates when the text should be auto-capitalized.
+ * @property `customValidator` applies a custom validator that can dictate whether or not an entered value is valid.
+ */
 export interface FormattedTextFieldProps extends BaseTextFieldProps {
+  /**
+   * The `InputType` of the `TextField`. This will select the appropriate keyboard.
+   */
   inputType?: InputType;
+  /**
+   * Dictates when the text should be auto-capitalized.
+   */
   autoCapitalize?: AutoCapitalizationType;
+  /**
+   * **Warning:** This callback is currently broken and will not work as intended.
+   *
+   * Custom validator function to determine the validity of an entered value.
+   *
+   * @deprecated This callback will be removed in version 2025-01.
+   * Please update your code to avoid using this feature.
+   */
   customValidator?: (text: string) => boolean;
 }
 

package/src/surfaces/point-of-sale/components/Icon/Icon.ts

@@ -86,7 +86,14 @@ export type IconName =
 export type IconSize = 'minor' | 'major' | 'spot' | 'caption' | 'badge';
 
 export interface IconProps {
+  /**
+   * A name used to render the icon.
+   */
   name: IconName;
+  /**
+   * Size of the icon.
+   * @defaultValue 'major'
+   */
   size?: IconSize;
 }
 

package/src/surfaces/point-of-sale/components/Image/Image.ts

@@ -1,6 +1,9 @@
 import {createRemoteComponent} from '@remote-ui/core';
 
 export interface ImageProps {
+  /**
+   * The source of the image to be displayed.
+   */
   src?: string;
 }
 

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

@@ -3,12 +3,26 @@ import {BadgeProps} from '../Badge/Badge';
 import {ColorType} from '../Text/Text';
 
 export interface ToggleSwitch {
+  /**
+   * Whether or not the toggle switch is on or off.
+   */
   value?: boolean;
+
+  /**
+   * Whether or not the toggle switch is disabled.
+   */
   disabled?: boolean;
 }
 
 export interface SubtitleType {
+  /**
+   * The subtitles to display beneath the main label.
+   */
   content: string;
+
+  /**
+   * Property used to modify the subtitle appearance.
+   */
   color?: ColorType;
 }
 
@@ -23,7 +37,7 @@ export interface ListRowLeftSide {
    * 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.
    */
-  subtitle?: readonly [ListRowSubtitle, ListRowSubtitle?, ListRowSubtitle?];
+  subtitle?: [ListRowSubtitle, ListRowSubtitle?, ListRowSubtitle?];
   /**
    * @deprecated
    * badge will be removed in version 2.0.0 in favor of badges.
@@ -87,7 +101,7 @@ export interface ListProps {
    */
   title?: string;
   /**
-   * A header component for the list
+   * A header component for the list.
    */
   listHeaderComponent?: RemoteFragment;
   /**

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

@@ -1,9 +1,12 @@
 import {createRemoteComponent} from '@remote-ui/core';
 
 /**
- * @property `initialScreenName` sets the initial Screen by its `name` property.
+ * @property `initialScreenName` sets the initial `Screen` whose `name` matches.
  */
 export interface NavigatorProps {
+  /**
+   * Sets the initial `Screen` whose `name` matches.
+   */
   initialScreenName?: string;
 }
 

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

@@ -5,8 +5,6 @@ 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'.
- * @property {number} [max] - The highest decimal or integer to be accepted for the field.
- * @property {number} [min] - The lowest decimal or integer to be accepted for the field.
  */
 export interface NumberFieldProps extends InputProps {
   inputMode?: 'decimal' | 'numeric';

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

@@ -0,0 +1,31 @@
+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`.
+   */
+  action?: {
+    /**
+     * The title of the action button.
+     */
+    title: string;
+    /**
+     * Whether the action button is disabled.
+     * @defaultValue false
+     */
+    disabled?: boolean;
+    /**
+     * A callback that is called when the action button is pressed.
+     */
+    onPress: () => void;
+  };
+}
+
+export const POSBlock = createRemoteComponent<'POSBlock', POSBlockProps>(
+  'POSBlock',
+);

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

@@ -0,0 +1,16 @@
+import {createRemoteComponent} from '@remote-ui/core';
+
+/**
+ * Renders a `POSBlockRow` in a `POSBlock`.
+ */
+export interface POSBlockRowProps {
+  /**
+   * A callback for when the row is tapped.
+   */
+  onPress?: () => void;
+}
+
+export const POSBlockRow = createRemoteComponent<
+  'POSBlockRow',
+  POSBlockRowProps
+>('POSBlockRow');

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

@@ -19,7 +19,13 @@ export type PinLength = 4 | 5 | 6 | 7 | 8 | 9 | 10;
  * @property {function(): number[]} onPress - The function to be called when the action button is pressed.
  */
 export interface PinPadActionType {
+  /**
+   * The label for the action button.
+   */
   label: string;
+  /**
+   * The function to be called when the action button is pressed.
+   */
   onPress: () => Promise<number[]>;
 }
 
@@ -35,12 +41,33 @@ export interface PinPadActionType {
  * @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.
+   */
   masked?: boolean;
+  /**
+   * The minimum length of the PIN.
+   */
   minPinLength?: PinLength;
+  /**
+   * The maximum length of the PIN.
+   */
   maxPinLength?: PinLength;
+  /**
+   * The content for the prompt on the pin pad.
+   */
   label?: string;
+  /**
+   * The call to action between the entry view and the keypad, consisting of a label and function that returns the pin.
+   */
   pinPadAction?: PinPadActionType;
+  /**
+   * The function to be called when the PIN is submitted.
+   */
   onSubmit: (pin: number[]) => Promise<PinValidationResult>;
+  /**
+   * The function to be called when a PIN is entered.
+   */
   onPinEntry?: (pin: number[]) => void;
 }
 

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

@@ -1,9 +1,21 @@
 import {createRemoteComponent} from '@remote-ui/core';
 
 export interface RadioButtonListProps {
+  /**
+   * 	The radio button options.
+   */
   items: string[];
+  /**
+   * A callback to be performed when the radio list item is selected.
+   */
   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.
+   */
   initialSelectedItem?: string;
+  /**
+   * Whether the initialSelectedItem renders at the top of the list.
+   */
   initialOffsetToShowSelectedItem?: boolean;
 }
 

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

@@ -4,17 +4,29 @@ import {createRemoteComponent} from '@remote-ui/core';
  * @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`.
+   */
   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` displays the secondary action button when set `true`.
+ * @property `isEnabled` sets whether the action can be tapped.
  */
 export interface SecondaryActionProps {
+  /**
+   * Displays the name of the secondary action in the action bar.
+   */
   text: string;
+  /**
+   * Triggered when the secondary action button is pressed.
+   */
   onPress: () => void;
+  /**
+   * Sets whether the action can be tapped.
+   */
   isEnabled?: boolean;
 }
 
@@ -22,21 +34,50 @@ export interface SecondaryActionProps {
  * @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` is a callback that allows you to override the secondary navigation action. Runs when screen is mounted.
+ * @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.
+   */
   name: string;
+  /**
+   * The title of the screen which will be displayed on the UI.
+   */
   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.
+   */
   isLoading?: boolean;
+  /**
+   * Dictates how the `Screen` will be presented when navigated to.
+   */
   presentation?: ScreenPresentationProps;
+  /**
+   * Displays a secondary action button on the screen.
+   */
   secondaryAction?: SecondaryActionProps;
+  /**
+   * Triggered when the screen is navigated to.
+   */
   onNavigate?: () => void;
+  /**
+   * Triggered when the user navigates back from this screen. Runs after screen is unmounted.
+   */
   onNavigateBack?: () => void;
+  /**
+   * A callback that allows you to override the secondary navigation action. Runs when screen is mounted.
+   */
   overrideNavigateBack?: () => void;
+  /**
+   * A callback that gets triggered when the navigation event completes and the screen receives the parameters.
+   */
   onReceiveParams?: (params: any) => void;
 }
 

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

@@ -1,11 +1,29 @@
 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.
+   */
   initialValue?: string;
+  /**
+   * A callback containing the new text value of the search bar.
+   */
   onTextChange?: (value: string) => void;
+  /**
+   * A callback when the search button is tapped.
+   */
   onSearch: (value: string) => void;
+  /**
+   * A callback when the input is focused.
+   */
   onFocus?: () => void;
+  /**
+   * Whether the text can be changed.
+   */
   editable?: boolean;
+  /**
+   * The placeholder value to display in the search bar when no text is entered.
+   */
   placeholder?: string;
 }
 

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

@@ -1,12 +1,32 @@
 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.
+ */
 export interface SectionHeaderAction {
+  /**
+   * The title describing the action.
+   */
   title: string;
+  /**
+   * The callback when the action is tapped 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.
+   */
   title?: string;
+  /**
+   * The action in the top right of the section that can be triggered by a tap.
+   */
   action?: SectionHeaderAction;
 }
 

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

@@ -1,14 +1,32 @@
 import {createRemoteComponent} from '@remote-ui/core';
 
 export interface Segment {
+  /**
+   * The id of the segment.
+   */
   id: string;
+  /**
+   * The label of the segment.
+   */
   label: string;
+  /**
+   * Whether the segment is disabled.
+   */
   disabled: boolean;
 }
 
 export interface SegmentedControlProps {
+  /**
+   * The segments to display.
+   */
   segments: Segment[];
+  /**
+   * The id of the selected segment.
+   */
   selected: string;
+  /**
+   * A callback when a segment is selected.
+   */
   onSelect: (id: string) => void;
 }
 

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

@@ -1,7 +1,13 @@
 import {createRemoteComponent} from '@remote-ui/core';
 
 export interface SelectableProps {
+  /**
+   * The callback on press.
+   */
   onPress: () => void;
+  /**
+   * Whether the selectable reacts to presses.
+   */
   disabled?: boolean;
 }
 

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

@@ -18,7 +18,14 @@ export type Spacing =
   | 16;
 
 export interface StackProps {
+  /**
+   * The direction of the stack.
+   */
   direction: 'vertical' | 'horizontal';
+  /**
+   * The alignment of the children along the cross axis.
+   * @defaultValue 'flex-end'
+   */
   alignment?:
     | 'flex-end'
     | 'center'
@@ -26,12 +33,31 @@ export interface StackProps {
     | 'space-around'
     | 'space-between'
     | 'space-evenly';
+  /**
+   * The vertical padding around the stack.
+   */
   paddingVertical?: VerticalSpacing;
+  /**
+   * The horizontal padding around the stack.
+   */
   paddingHorizontal?: HorizontalSpacing;
+  /**
+   * The spacing between each child in the stack.
+   * @defaultValue 1
+   */
   spacing?: Spacing;
+  /**
+   * Whether the children should be stretched to fill the cross axis.
+   */
   flexChildren?: boolean;
+  /**
+   * The flex value for the stack.
+   */
   flex?: number;
-  flexWrap?: 'wrap' | 'nowrap' | 'wrap-reverse' | undefined;
+  /**
+   * Wrap behavior for the children of the stack.
+   */
+  flexWrap?: 'wrap' | 'nowrap' | 'wrap-reverse';
 }
 
 export const Stack = createRemoteComponent<'Stack', StackProps>('Stack');

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

@@ -7,13 +7,13 @@ export interface StepperProps {
   initialValue: number;
 
   /**
-   * A callback that is called when the value of the stepper changes.
+   * A callback when the value of the stepper changes.
    */
   onValueChanged: (value: number) => void;
 
   /**
-   * @defaultValue 1
    * Use to set the minimum value of the stepper.
+   * @defaultValue 1
    */
   minimumValue?: number;
 
@@ -28,8 +28,8 @@ export interface StepperProps {
   value?: number;
 
   /**
-   * @defaultValue false
    * Whether the field can be modified.
+   * @defaultValue false
    */
   disabled?: boolean;
 }

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

@@ -21,7 +21,13 @@ export type ColorType =
   | 'TextHighlight';
 
 export interface TextProps {
+  /**
+   * The text variant.
+   */
   variant?: TextVariant;
+  /**
+   * The text color.
+   */
   color?: ColorType;
 }
 

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

@@ -7,6 +7,9 @@ import type {InputProps} from '../shared/InputField';
  * @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.
+   */
   rows?: number;
 }
 

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

@@ -1,11 +1,37 @@
 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 is in a red destructive appearance.
+ * @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.
+   */
   title: string;
+  /**
+   * The text set on the secondary label of the tile.
+   */
   subtitle?: string;
+  /**
+   * Sets whether or not the tile can be tapped.
+   */
   enabled?: boolean;
+  /**
+   * Sets whether or not the tile is in a red destructive appearance.
+   */
   destructive?: boolean;
+  /**
+   * The number value displayed in the top right corner of the tile.
+   */
   badgeValue?: number;
+  /**
+   * The callback that is executed when the tile is tapped.
+   */
   onPress?: () => void;
 }
 

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

@@ -14,6 +14,10 @@ export interface TimeFieldProps
     | 'action'
     | 'helpText'
   > {
+  /**
+   * (Android only) Whether the clock displays in 24 hour time instead of 12 hour time.
+   * @defaultValue false
+   */
   is24Hour?: boolean;
 }
 

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

@@ -1,10 +1,37 @@
 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
+   */
   selected?: string;
+  /**
+   * A callback for changes.
+   */
   onChange?(selected: string): void;
+  /**
+   * Controls the visible state, and a callback to set the visible state as false when the dialog closes.
+   */
   visibleState: [boolean, (visible: boolean) => void];
+  /**
+   * (Android only) Whether the clock displays in 24 hour time instead of 12 hour time.
+   * @defaultValue false
+   */
   is24Hour?: boolean;
+  /**
+   * Whether to display the picker in inline (clock) mode or spinner mode.
+   * iOS only supports 'spinner'.
+   * @defaultValue 'inline'
+   */
   inputMode?: 'inline' | 'spinner';
 }
 

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

@@ -1,9 +1,34 @@
+/**
+ * @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`.
+   */
   title?: string;
-  subtitle?: string;
+  /**
+   * Populates the `TextField` with an text initial value.
+   */
   initialValue?: string;
+  /**
+   * Sets a placeholder value for when the `TextField` is empty.
+   */
   placeholder?: string;
+  /**
+   * Set whether the current value in the `TextField` is valid.
+   */
   isValid?: boolean;
+  /**
+   * Sets an error message to present to the user.
+   */
   errorMessage?: string;
+  /**
+   * A callback that is executed every time the `TextField` value changes.
+   */
   onChangeText?: (value: string) => void;
 }