Merge pull request #4274 from Shopify/forms-web-components-2025-07

Improve Forms component descriptions (2025-07)

Author: sordaz00

packages/ui-extensions/docs/surfaces/customer-account/generated/customer_account_ui_extensions/2025-07/generated_docs_data.json

@@ -33,24 +33,23 @@ export interface CheckboxProps extends DisclosureActivatorProps {
   checked?: boolean;
 
   /**
-   * Whether the checkbox can be changed.
+   * Whether the checkbox is disabled, preventing any user interaction.
    */
   disabled?: boolean;
 
   /**
-   * Indicate an error to the user. The field will be given a specific stylistic treatment
-   * to communicate problems that have to be resolved immediately.
+   * An error message displayed below the field to indicate validation problems. When set, the field is styled with error indicators.
    */
   error?: string;
 
   /**
-   * A label used for buyers using assistive technologies. When set, any
+   * A label used for users of assistive technologies. When set, any
    * `children` supplied to this component will not be announced to screen reader users.
    */
   accessibilityLabel?: string;
 
   /**
-   * A callback that is run whenever the checkbox is changed. This callback
+   * A callback fired when the checkbox value changes. This callback
    * is called with a boolean indicating whether the checkbox should now be
    * active or inactive. This component is [controlled](https://reactjs.org/docs/forms.html#controlled-components),
    * so you must store this value in state and reflect it back in the

packages/ui-extensions/docs/surfaces/customer-account/generated/customer_account_ui_extensions/2025-07/generated_docs_data_v2.json

@@ -1,7 +1,7 @@
 import {createRemoteComponent} from '@remote-ui/core';
 
 /**
- * Use choice lists to present a list of choices where buyers can make a single selection or multiple selections.
+ * Use choice lists to present a list of choices where users can make a single selection or multiple selections.
  * @publicDocs
  */
 export interface ChoiceListProps<T extends string | string[]> {
@@ -25,7 +25,7 @@ export interface ChoiceListProps<T extends string | string[]> {
    */
   variant?: 'base' | 'group';
   /**
-   * A callback that is run whenever the choice list is changed. This callback
+   * A callback fired when the choice list value changes. This callback
    * is called with a string or array of strings indicating the ids of choices
    * that should now be selected. This component is
    * [controlled](https://reactjs.org/docs/forms.html#controlled-components),
@@ -36,7 +36,7 @@ export interface ChoiceListProps<T extends string | string[]> {
 }
 
 /**
- * Use choice lists to present a list of choices where buyers can make
+ * Use choice lists to present a list of choices where users can make
  * a single selection or multiple selections.
  */
 export const ChoiceList = createRemoteComponent<

packages/ui-extensions/src/surfaces/checkout/components/Checkbox/Checkbox.ts

@@ -26,8 +26,8 @@ export interface DateFieldProps
       'yearMonth' | 'defaultYearMonth' | 'disabled' | 'onYearMonthChange'
     > {
   /**
-   * Callback when the field has an invalid date.
-   * This callback will be called, if the date typed is invalid or disabled.
+   * A callback fired when the date field contains an invalid or disabled date after the user finishes editing.
+   * This callback is invoked when the date typed is invalid or disabled.
    *
    * Dates that don’t exist or have formatting errors are considered invalid. Some examples of invalid dates are:
    * - 2021-02-31: February doesn’t have 31 days
@@ -39,15 +39,15 @@ export interface DateFieldProps
    *
    * Note that this will be called only when the user **finishes editing** the date,
    * after the `onChange` callback.
-   * The field is **not** validated on every change to the input. Once the buyer has signalled that
+   * The field is **not** validated on every change to the input. Once the user has signalled that
    * they have finished editing the field (typically, by blurring the field), the field gets validated and the callback is run if the value is invalid.
    */
   onInvalid?(): void;
 }
 
 /**
- * The DateField component is used to collect date information from buyers.
- * It also provides the ability to display a DatePicker UI, which allows users to select dates with ease.
+ * The date field component is used to collect date information from users.
+ * It also provides the ability to display a date picker UI, which allows users to select dates with ease.
  */
 export const DateField = createRemoteComponent<'DateField', DateFieldProps>(
   'DateField',

packages/ui-extensions/src/surfaces/checkout/components/ChoiceList/ChoiceList.ts

@@ -29,7 +29,7 @@ export type SelectedDate = DateString | DateString[] | DateRange;
 export type DisabledDate = DateString | DateRange | DayString;
 
 /**
- * The DatePicker component is a calendar picker UI that allows users to select a single date or a date range
+ * The date picker component is a calendar picker UI that allows users to select a single date or a date range.
  * @publicDocs
  */
 export interface DatePickerProps<T extends SelectedDate> {
@@ -51,7 +51,7 @@ export interface DatePickerProps<T extends SelectedDate> {
    */
   disabled?: DisabledDate[] | boolean;
   /**
-   * Whether the date picker is read-only.
+   * Whether the date picker is read-only and can't be edited. Read-only date pickers remain focusable and their state is announced by screen readers where applicable.
    */
   readOnly?: boolean;
   /**
@@ -60,15 +60,15 @@ export interface DatePickerProps<T extends SelectedDate> {
    */
   selected: T;
   /**
-   * A callback that is run whenever a date is selected or unselected. This callback
+   * A callback fired when the selected date or dates change. This callback
    * is called with a string, an array of strings or a range object representing the selected dates.
    * This component is [controlled](https://reactjs.org/docs/forms.html#controlled-components),
    * so you must store these values in state and reflect it back in the
    * `selected` props.
    */
   onChange?(selected: T): void;
   /**
-   * A callback that is run whenever the month is changed. This callback
+   * A callback fired when the displayed year and month change. This callback
    * is called with an object indicating the year/month the UI should change to.
    * When year/month navigation is controlled you must store these values in state and
    * reflect it back in the `yearMonth` prop.
@@ -77,7 +77,7 @@ export interface DatePickerProps<T extends SelectedDate> {
 }
 
 /**
- * The DatePicker component is a calendar picker UI that allows users to select a single date or a date range.
+ * The date picker component is a calendar picker UI that allows users to select a single date or a date range..
  */
 export const DatePicker = createRemoteComponent<
   'DatePicker',

packages/ui-extensions/src/surfaces/checkout/components/DateField/DateField.ts

@@ -3,12 +3,12 @@ import {createRemoteComponent} from '@remote-ui/core';
 import type {IdProps} from '../shared';
 
 /**
- * DropZone allows file uploads through drag-and-drop functionality into a designated area on a page, or by activating a button. At present, DropZone does not offer image upload preview capabilities. The use of object URLs directly in an image component is not possible due to the extension and host operating on separate domains. Any element focused within the Dropzone component, including child elements such as the 'Add file' button, will initiate the file selector when the Enter or Spacebar key is pressed.
+ * The drop zone component allows file uploads through drag-and-drop functionality into a designated area on a page, or by activating a button. At present, DropZone does not offer image upload preview capabilities. The use of object URLs directly in an image component is not possible due to the extension and host operating on separate domains. Any element focused within the drop zone component, including child elements such as the 'Add file' button, will initiate the file selector when the Enter or Spacebar key is pressed.
  * @publicDocs
  */
 export interface DropZoneProps extends IdProps {
   /**
-   * Whether the field can be modified.
+   * Whether the drop zone is disabled, preventing any user interaction.
    */
   disabled?: boolean;
 
@@ -21,13 +21,12 @@ export interface DropZoneProps extends IdProps {
   required?: boolean;
 
   /**
-   * Indicate an error to the user. The field will be given a specific stylistic treatment
-   * to communicate problems that have to be resolved immediately.
+   * An error message displayed below the field to indicate validation problems. When set, the drop zone is styled with error indicators.
    */
   error?: string;
 
   /**
-   * Content to use as the field label.
+   * The text displayed as the field label, which identifies the purpose of the drop zone to users.
    */
   label?: string;
 
@@ -51,7 +50,7 @@ export interface DropZoneProps extends IdProps {
 
   /**
    * A label that describes the purpose or contents of the item. When set,
-   * it will be announced to buyers using assistive technologies and will
+   * it will be announced to users of assistive technologies and will
    * provide them with more context.
    */
   accessibilityLabel?: string;
@@ -64,13 +63,13 @@ export interface DropZoneProps extends IdProps {
   multiple?: boolean;
 
   /**
-   * Callback when files are dropped or selected.
+   * A callback fired when files are dropped or selected.
    * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/drop_event
    */
   onInput?(files: File[]): void;
 
   /**
-   * Callback when rejected files are dropped. Files are rejected based on the `accept` prop.
+   * A callback fired when rejected files are dropped. Files are rejected based on the `accept` prop.
    */
   onDropRejected?(files: File[]): void;
 }

packages/ui-extensions/src/surfaces/checkout/components/DatePicker/DatePicker.ts

@@ -8,12 +8,11 @@ Unlike an HTML `form` element, this component does not support configuring the d
  */
 export interface FormProps {
   /**
-   * Whether the form is able to be submitted. When set to `true`, this will
-   * disable the implicit submit behavior of the form.
+   * Whether the form is disabled, preventing submission and the implicit submit behavior from inputs. When set to `true`, pressing Enter in a field will not submit the form.
    */
   disabled?: boolean;
   /**
-   * A callback that is run when the form is submitted.
+   * A callback fired when the form is submitted.
    */
   onSubmit(): void;
   /**

packages/ui-extensions/src/surfaces/checkout/components/DropZone/DropZone.ts

@@ -5,7 +5,7 @@ import type {Autocomplete} from '../shared';
 import type {IconSource} from '../Icon/Icon';
 
 /**
- * A PhoneField is an input field that merchants can type into optimized for phone numbers with a country code base auto-formatting. The country code is required for the initial render of the field but it can be overriden later by the user either by selecting a country in the country selection dropdown or by manually editing the country phone code directly in the text field.
+ * A phone field is an input field that users can type into optimized for phone numbers with a country code base auto-formatting. The country code is required for the initial render of the field but it can be overriden later by the user either by selecting a country in the country selection dropdown or by manually editing the country phone code directly in the text field.
  * @publicDocs
  */
 export interface PhoneFieldProps {
@@ -36,13 +36,12 @@ export interface PhoneFieldProps {
   autocomplete?: Autocomplete | boolean;
 
   /**
-   * Whether the field can be modified.
+   * Whether the phone field is disabled, preventing any user interaction.
    */
   disabled?: boolean;
 
   /**
-   * Indicate an error to the user. The field will be given a specific stylistic treatment
-   * to communicate problems that have to be resolved immediately.
+   * An error message displayed below the field to indicate validation problems. When set, the field is styled with error indicators.
    */
   error?: string;
 
@@ -59,8 +58,8 @@ export interface PhoneFieldProps {
   id?: string;
 
   /**
-   * Content to use as the field label. This value is also used as the placeholder
-   * when the field is empty.
+   * The text displayed as the field label, which identifies the purpose of the field to users.
+   * This value is also used as the placeholder when the field is empty.
    */
   label: string;
 
@@ -76,7 +75,7 @@ export interface PhoneFieldProps {
   name?: string;
 
   /**
-   * Whether the field is read-only.
+   * Whether the field is read-only and can't be edited. Read-only fields remain focusable and their content is announced by screen readers.
    */
   readonly?: boolean;
 
@@ -95,11 +94,11 @@ export interface PhoneFieldProps {
   value?: string;
 
   /**
-   * Callback when the buyer has **finished editing** a field or pressed the country dropdown.
+   * A callback fired when the user has **finished editing** the field, such as when they blur the field, or after using the country dropdown.
    * Unlike `onChange` callbacks you may be familiar with from Polaris or other React component libraries,
    * this callback is **not** run on every change to the input. Phone fields are
-   * “partially controlled” components, which means that while the buyer edits the
-   * field, its state is controlled by the component. Once the buyer has signalled that
+   * “partially controlled” components, which means that while the user edits the
+   * field, its state is controlled by the component. Once the user has signalled that
    * they have finished editing the field (typically, by blurring the field), `onChange`
    * is called if the input actually changed from the most recent `value` property. At
    * that point, you are expected to store this “committed value” in state, and reflect
@@ -111,7 +110,7 @@ export interface PhoneFieldProps {
    * is to have the component be the source of truth for the input `value`, and update
    * the `value` on every user input. The delay in responding to events from a UI
    * extension is only a few milliseconds, but attempting to strictly store state with
-   * this delay can cause issues if a user types quickly, or if the buyer is using a
+   * this delay can cause issues if a user types quickly, or if the user is using a
    * lower-powered device. Having the UI thread take ownership for “in progress” input,
    * and only synchronizing when the user is finished with a field, avoids this risk.
    *
@@ -125,28 +124,27 @@ export interface PhoneFieldProps {
    */
   onChange?(value: string): void;
   /**
-   * Callback when the user makes any changes in the field including selecting a country
-   * in the dropdown. As noted in the documentation for `onChange`, you must not use
+   * A callback fired when the user makes any changes in the field, such as typing a character or selecting a country in the dropdown. As noted in the documentation for `onChange`, you must not use
    * this to update `state` — use the `onChange` callback for that purpose.
-   * Use the `onInput` prop when you need to do something as soon as the buyer makes a change,
+   * 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.
    *
    * This callback is called with the current formatted value.
    */
   onInput?(value: string): void;
   /**
-   * Callback when input is focused.
+   * A callback fired when the phone field receives focus.
    */
   onFocus?(): void;
   /**
-   * Callback when focus is removed.
+   * A callback fired when the phone field loses focus.
    */
   onBlur?(): void;
 }
 
 /**
- * A PhoneField is an input field that merchants can type into optimized
+ * A phone field is an input field that users can type into optimized
  * for phone numbers with a country code base auto-formatting.
  * The country code is required for the initial render of the field but
  * it can be overriden later by the user either by selecting a country