Improve Forms component descriptions to match admin quality (2026-04-rc)

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

@@ -33,7 +33,7 @@ export type CallbackEventListener<TTagName extends keyof HTMLElementTagNameMap,
 
 declare const tagName = "s-checkbox";
 /**
- * The element props interface for the Checkbox component.
+ * Configure the following properties on the checkbox component.
  * @publicDocs
  */
 export interface CheckboxElementProps extends Pick<CheckboxProps$1, 'accessibilityLabel' | 'checked' | 'command' | 'commandFor' | 'defaultChecked' | 'disabled' | 'error' | 'id' | 'label' | 'name' | 'required' | 'value'> {
@@ -42,14 +42,15 @@ export interface CheckboxElementProps extends Pick<CheckboxProps$1, 'accessibili
 export interface CheckboxEvents extends Pick<CheckboxProps$1, 'onChange'> {
 }
 /**
- * The events interface for the Checkbox component.
+ * The checkbox component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events).
+ *
  * @publicDocs
  */
 export interface CheckboxElementEvents {
     /**
-     * A callback that is run whenever the control is changed.
+     * A callback fired when the checkbox value changes.
      *
-     * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event
+     * Learn more about the [change event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event).
      */
     change?: CallbackEventListener<typeof tagName>;
 }

packages/ui-extensions/src/surfaces/checkout/components/Chip.d.ts

@@ -27,13 +27,13 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends Base
 
 declare const tagName = "s-chip";
 /**
- * The element props interface for the Chip component.
+ * Configure the following properties on the chip component.
  * @publicDocs
  */
 export interface ChipElementProps extends Pick<ChipProps$1, 'accessibilityLabel' | 'id'> {
 }
 /**
- * The slots interface for the Chip component.
+ * The chip component supports slots for additional content placement within the component. Learn more about [using slots](/docs/api/polaris/using-polaris-web-components#slots).
  * @publicDocs
  */
 export interface ChipElementSlots {

packages/ui-extensions/src/surfaces/checkout/components/Choice.d.ts

@@ -27,13 +27,13 @@ export interface BaseElementPropsWithChildren<TClass = HTMLElement> extends Base
 
 declare const tagName = "s-choice";
 /**
- * The element props interface for the Choice component.
+ * Configure the following properties on the choice component.
  * @publicDocs
  */
 export interface ChoiceElementProps extends Pick<ChoiceProps$1, 'accessibilityLabel' | 'defaultSelected' | 'disabled' | 'id' | 'selected' | 'error' | 'value'> {
 }
 /**
- * The slots interface for the Choice component.
+ * The choice component supports slots for additional content placement within the component. Learn more about [using slots](/docs/api/polaris/using-polaris-web-components#slots).
  * @publicDocs
  */
 export interface ChoiceElementSlots {

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

@@ -39,22 +39,23 @@ export type CallbackEventListener<TTagName extends keyof HTMLElementTagNameMap,
 
 declare const tagName = "s-choice-list";
 /**
- * The element props interface for the ChoiceList component.
+ * Configure the following properties on the choice list component.
  * @publicDocs
  */
 export interface ChoiceListElementProps extends Pick<ChoiceListProps$1, 'disabled' | 'error' | 'id' | 'label' | 'labelAccessibilityVisibility' | 'multiple' | 'name' | 'values' | 'variant'> {
 }
 export interface ChoiceListEvents extends Pick<ChoiceListProps$1, 'onChange'> {
 }
 /**
- * The events interface for the ChoiceList component.
+ * The choice list component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events).
+ *
  * @publicDocs
  */
 export interface ChoiceListElementEvents {
     /**
-     * A callback that is run whenever the control is changed.
+     * A callback fired when the choice list value changes.
      *
-     * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event
+     * Learn more about the [change event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event).
      */
     change?: CallbackEventListener<typeof tagName>;
 }

packages/ui-extensions/src/surfaces/checkout/components/ConsentCheckbox.d.ts

@@ -57,7 +57,7 @@ declare module 'preact' {
 
 declare const tagName = "s-consent-checkbox";
 /**
- * The element props interface for the ConsentCheckbox component.
+ * Configure the following properties on the consent checkbox component.
  * @publicDocs
  */
 export interface ConsentCheckboxElementProps extends Pick<ConsentCheckboxProps$1, 'accessibilityLabel' | 'checked' | 'command' | 'commandFor' | 'defaultChecked' | 'disabled' | 'error' | 'id' | 'label' | 'name' | 'policy' | 'value'> {
@@ -66,14 +66,15 @@ export interface ConsentCheckboxElementProps extends Pick<ConsentCheckboxProps$1
 export interface ConsentCheckboxEvents extends Pick<CheckboxEvents, 'onChange'> {
 }
 /**
- * The events interface for the ConsentCheckbox component.
+ * The consent checkbox component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events).
+ *
  * @publicDocs
  */
 export interface ConsentCheckboxElementEvents {
     /**
-     * A callback that is run whenever the control is changed.
+     * A callback fired when the consent checkbox value changes.
      *
-     * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event
+     * Learn more about the [change event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event).
      */
     change?: CallbackEventListener<typeof tagName>;
 }

packages/ui-extensions/src/surfaces/checkout/components/ConsentPhoneField.d.ts

@@ -70,7 +70,7 @@ declare module 'preact' {
 
 declare const tagName = "s-consent-phone-field";
 /**
- * The element props interface for the ConsentPhoneField component.
+ * Configure the following properties on the consent phone field component.
  * @publicDocs
  */
 export interface ConsentPhoneFieldElementProps extends Pick<ConsentPhoneFieldProps$1, 'autocomplete' | 'defaultValue' | 'disabled' | 'error' | 'id' | 'label' | 'labelAccessibilityVisibility' | 'name' | 'policy' | 'readOnly' | 'required' | 'type' | 'value'> {
@@ -83,32 +83,33 @@ export interface ConsentPhoneFieldElementProps extends Pick<ConsentPhoneFieldPro
 export interface ConsentPhoneFieldEvents extends Pick<PhoneFieldEvents, 'onBlur' | 'onChange' | 'onFocus' | 'onInput'> {
 }
 /**
- * The events interface for the ConsentPhoneField component.
+ * The consent phone field component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events).
+ *
  * @publicDocs
  */
 export interface ConsentPhoneFieldElementEvents {
     /**
-     * Callback when the element loses focus.
+     * A callback fired when the consent phone field loses focus.
      *
-     * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/blur_event
+     * Learn more about the [blur event](https://developer.mozilla.org/en-US/docs/Web/API/Element/blur_event).
      */
     blur?: CallbackEventListener<typeof tagName>;
     /**
-     * Callback when the user has **finished editing** a field, e.g. once they have blurred the field.
+     * A callback fired when the consent phone field value changes.
      *
-     * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event
+     * Learn more about the [change event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event).
      */
     change?: CallbackEventListener<typeof tagName>;
     /**
-     * Callback when the element receives focus.
+     * A callback fired when the consent phone field receives focus.
      *
-     * @see https://developer.mozilla.org/en-US/docs/Web/API/Element/focus_event
+     * Learn more about the [focus event](https://developer.mozilla.org/en-US/docs/Web/API/Element/focus_event).
      */
     focus?: CallbackEventListener<typeof tagName>;
     /**
-     * Callback when the user makes any changes in the field.
+     * A callback fired when the user inputs data into the consent phone field.
      *
-     * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event
+     * Learn more about the [input event](https://developer.mozilla.org/en-US/docs/Web/API/Element/input_event).
      */
     input?: CallbackEventListener<typeof tagName>;
 }
@@ -119,13 +120,13 @@ export interface ConsentPhoneFieldElement extends ConsentPhoneFieldElementProps,
     oninput: ConsentPhoneFieldEvents['onInput'];
 }
 /**
- * The slots interface for the ConsentPhoneField component.
+ * The consent phone field component supports slots for additional content placement within the component. Learn more about [using slots](/docs/api/polaris/using-polaris-web-components#slots).
+ *
  * @publicDocs
  */
 export interface ConsentPhoneFieldElementSlots {
     /**
-     * Additional content to be displayed in the field.
-     * Commonly used to display an icon that activates a tooltip providing more information.
+     * Additional interactive content displayed within the field. Accepts button and clickable components with text content only. Other component types or complex layouts are not supported.
      */
     accessory?: HTMLElement;
 }

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

@@ -33,7 +33,7 @@ export type CallbackEventListener<TTagName extends keyof HTMLElementTagNameMap,
 
 declare const tagName = "s-date-field";
 /**
- * The element props interface for the DateField component.
+ * Configure the following properties on the date field component.
  * @publicDocs
  */
 export interface DateFieldElementProps extends Pick<DateFieldProps$1, 'allow' | 'allowDays' | 'autocomplete' | 'defaultValue' | 'defaultView' | 'disabled' | 'disallow' | 'disallowDays' | 'error' | 'id' | 'label' | 'name' | 'readOnly' | 'required' | 'value' | 'view'> {
@@ -46,32 +46,43 @@ export interface DateFieldElementProps extends Pick<DateFieldProps$1, 'allow' |
 export interface DateFieldEvents extends Pick<DateFieldProps$1, 'onBlur' | 'onChange' | 'onFocus' | 'onInput' | 'onInvalid' | 'onViewChange'> {
 }
 /**
- * The events interface for the DateField component.
+ * The date field component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events).
+ *
  * @publicDocs
  */
 export interface DateFieldElementEvents {
     /**
-     * Callback when the element loses focus.
+     * A callback fired when the date field loses focus.
+     *
+     * Learn more about the [blur event](https://developer.mozilla.org/en-US/docs/Web/API/Element/blur_event).
      */
     blur?: CallbackEventListener<typeof tagName>;
     /**
-     * Callback when the user has **finished editing** a field, e.g. once they have blurred the field.
+     * A callback fired when the date field value changes.
+     *
+     * Learn more about the [change event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event).
      */
     change?: CallbackEventListener<typeof tagName>;
     /**
-     * Callback when the element receives focus.
+     * A callback fired when the date field receives focus.
+     *
+     * Learn more about the [focus event](https://developer.mozilla.org/en-US/docs/Web/API/Element/focus_event).
      */
     focus?: CallbackEventListener<typeof tagName>;
     /**
-     * Callback when the user makes any changes in the field.
+     * A callback fired when the user inputs data into the date field.
+     *
+     * Learn more about the [input event](https://developer.mozilla.org/en-US/docs/Web/API/Element/input_event).
      */
     input?: CallbackEventListener<typeof tagName>;
     /**
-     * Callback when the user enters an invalid date.
+     * A callback fired when the date field value is invalid.
+     *
+     * Learn more about the [invalid event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/invalid_event).
      */
     invalid?: CallbackEventListener<typeof tagName>;
     /**
-     * Callback when the view changes.
+     * A callback fired when the calendar view changes, such as when navigating between months.
      */
     viewChange?: CallbackEventListener<typeof tagName>;
 }

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

@@ -33,36 +33,45 @@ export type CallbackEventListener<TTagName extends keyof HTMLElementTagNameMap,
 
 declare const tagName = "s-date-picker";
 /**
- * The element props interface for the DatePicker component.
+ * Configure the following properties on the date picker component.
  * @publicDocs
  */
 export interface DatePickerElementProps extends Pick<DatePickerProps$1, 'allow' | 'allowDays' | 'defaultValue' | 'defaultView' | 'disabled' | 'disallow' | 'disallowDays' | 'id' | 'name' | 'type' | 'value' | 'view'> {
 }
 export interface DatePickerEvents extends Pick<DatePickerProps$1, 'onBlur' | 'onChange' | 'onFocus' | 'onInput' | 'onViewChange'> {
 }
 /**
- * The events interface for the DatePicker component.
+ * The date picker component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events).
+ *
  * @publicDocs
  */
 export interface DatePickerElementEvents {
     /**
-     * Callback when the element loses focus.
+     * A callback fired when the date picker loses focus.
+     *
+     * Learn more about the [blur event](https://developer.mozilla.org/en-US/docs/Web/API/Element/blur_event).
      */
     blur?: CallbackEventListener<typeof tagName>;
     /**
-     * Callback when the user has **finished editing** a field, e.g. once they have blurred the field.
+     * A callback fired when the date picker value changes.
+     *
+     * Learn more about the [change event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event).
      */
     change?: CallbackEventListener<typeof tagName>;
     /**
-     * Callback when the element receives focus.
+     * A callback fired when the date picker receives focus.
+     *
+     * Learn more about the [focus event](https://developer.mozilla.org/en-US/docs/Web/API/Element/focus_event).
      */
     focus?: CallbackEventListener<typeof tagName>;
     /**
-     * Callback when the user makes any changes in the field.
+     * A callback fired when the user inputs data into the date picker.
+     *
+     * Learn more about the [input event](https://developer.mozilla.org/en-US/docs/Web/API/Element/input_event).
      */
     input?: CallbackEventListener<typeof tagName>;
     /**
-     * Callback when the view changes.
+     * A callback fired when the calendar view changes, such as when navigating between months.
      */
     viewChange?: CallbackEventListener<typeof tagName>;
 }

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

@@ -33,28 +33,33 @@ export type CallbackEventListener<TTagName extends keyof HTMLElementTagNameMap,
 
 declare const tagName = "s-drop-zone";
 /**
- * The element props interface for the DropZone component.
+ * Configure the following properties on the drop zone component.
  * @publicDocs
  */
 export interface DropZoneElementProps extends Pick<DropZoneProps$1, 'accept' | 'accessibilityLabel' | 'disabled' | 'error' | 'id' | 'label' | 'multiple' | 'name' | 'required' | 'value'> {
 }
 export interface DropZoneEvents extends Pick<DropZoneProps$1, 'onDropRejected' | 'onInput' | 'onChange'> {
 }
 /**
- * The events interface for the DropZone component.
+ * The drop zone component provides event callbacks for handling user interactions. Learn more about [handling events](/docs/api/polaris/using-polaris-web-components#handling-events).
+ *
  * @publicDocs
  */
 export interface DropZoneElementEvents {
     /**
-     * Callback when rejected files are dropped. Files are rejected based on the `accept` prop.
+     * A callback fired when files are rejected based on the `accept` prop.
      */
     droprejected?: CallbackEventListener<typeof tagName>;
     /**
-     * Callback when the user makes any changes in the field.
+     * A callback fired when the user inputs data into the drop zone.
+     *
+     * Learn more about the [input event](https://developer.mozilla.org/en-US/docs/Web/API/Element/input_event).
      */
     input?: CallbackEventListener<typeof tagName>;
     /**
-     * Callback when the user has finished selecting a file or files.
+     * A callback fired when the drop zone value changes.
+     *
+     * Learn more about the [change event](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event).
      */
     change?: CallbackEventListener<typeof tagName>;
 }