@shopify/ui-extensions 2025.10.0 → 2025.10.2

package/src/surfaces/point-of-sale/api/pin-pad-api.ts

@@ -1,11 +1,18 @@
 import {PinPadOptions, PinValidationResult} from '../types/pin-pad';
 
 export interface PinPadApiContent {
-  /** Shows a pin pad to the user in a modal dialog.
+  /** Shows a PIN pad to the user in a modal dialog.
+   *
+   * `onSubmit` is called when the PIN is submitted for validation by the user. The callback
+   * should validate the PIN and accept or reject it.
+   *
+   * If the PIN is accepted, the modal will be dismissed and the `onDismissed` callback
+   * (provided via `options`) will be called. It is recommended that any post-validation
+   * navigation is performed in this callback rather than in `onSubmit`.
+   *
+   * If the PIN is rejected, the optional `errorMessage` will be displayed to the user and the modal
+   * will not be dismissed.
    *
-   * @param onSubmit the function to be called when the PIN is submitted.
-   * The callback should be used to validate the PIN and return `accept` or `reject`.
-   * @param options the options for the pin pad
    */
   showPinPad(
     onSubmit: (
@@ -16,7 +23,7 @@ export interface PinPadApiContent {
 }
 
 /**
- * Access the Pin Pad API for pin pad functionality in a modal.
+ * Access the PIN Pad API for PIN pad functionality in a modal.
  */
 export interface PinPadApi {
   pinPad: PinPadApiContent;

package/src/surfaces/point-of-sale/types/pin-pad.ts

@@ -26,27 +26,34 @@ export interface PinPadActionType {
 
 export interface PinPadOptions {
   /**
-   * The function to be called when a pin is entered
+   * The function to be called whenever the entered PIN is updated
    */
   onPinEntry?: (pin: number[]) => void;
   /**
-   * The function to be called when the pin pad modal is dismissed
+   * The function to be called when the PIN pad modal is dismissed
    */
   onDismissed?: (result: PinPadResult) => void;
   /**
-   * The content for the prompt on the pin pad
+   * The content for the prompt on the PIN pad. This will be overridden by any
+   * `errorMessage` provided when rejecting a PIN from the `onSubmit` callback.
    */
   label?: string;
   /**
    * Whether the entered PIN should be masked
+   *
+   * @default true
    */
   masked?: boolean;
   /**
    * The minimum length of the PIN
+   *
+   * @default 4
    */
   minPinLength?: PinLength;
   /**
    * The maximum length of the PIN
+   *
+   * @default 6
    */
   maxPinLength?: PinLength;
   /**
@@ -58,7 +65,9 @@ export interface PinPadOptions {
    */
   title?: string;
   /**
-   * Whether the pin should be automatically submitted when the user has entered the maximum PIN length
+   * Whether the PIN should be automatically submitted when the user has entered the maximum PIN length
+   *
+   * @default false
    */
   autoSubmit?: boolean;
 }