Merge pull request #4409 from Shopify/cleanup-jsdoc-3-components-2026-04

Add JSDoc for component properties (2026-04)

Author: rennyG

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

@@ -822,6 +822,8 @@ interface BadgeProps$1 extends GlobalProps {
 	/**
 	 * An icon displayed inside the badge to provide additional visual context or reinforce the badge's meaning. Set to an empty string to display no icon.
 	 *
+	 * Always positioned relative to the text content. Independent positioning isn't supported.
+	 *
 	 * @default ''
 	 */
 	icon?: IconType | AnyString;
@@ -1410,6 +1412,8 @@ export interface LinkBehaviorProps extends InteractionProps, FocusEventProps {
 export interface InteractionProps {
 	/**
 	 * The ID of the component to control when this component is activated. Pair with the `command` property to specify what action to perform on the target component. Learn more about the [`commandFor` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#commandfor).
+	 *
+	 * When both `commandFor` and `href` are set, `commandFor` takes precedence. The command runs and the link doesn't navigate.
 	 */
 	commandFor?: string;
 	/**
@@ -1537,6 +1541,8 @@ export interface MultipleInputProps extends BaseInputProps {
 	 * An array of `value` attributes for the currently selected options.
 	 *
 	 * This is a convenience prop for setting the `selected` prop on child options.
+	 *
+	 * Form data captures the selected value strings only. Complex nested content inside choices is for display purposes and isn't included in form submissions.
 	 */
 	values?: string[];
 }
@@ -1805,6 +1811,8 @@ interface CheckboxProps$1 extends GlobalProps, BaseCheckableProps, FieldErrorPro
 	 * If you want to present an error when this field is empty, you can do
 	 * so with the `error` property.
 	 *
+	 * Adds semantic meaning for accessibility. Doesn't trigger automatic validation or display an error. Implement validation logic yourself and use the `error` prop to show results.
+	 *
 	 * @default false
 	 */
 	required?: boolean;
@@ -1906,6 +1914,8 @@ interface ChoiceListProps$1 extends GlobalProps, Pick<BasicFieldProps, "label" |
 	 * - `block`: The choices are displayed on the block axis.
 	 * - `grid`: The choices are displayed in a grid.
 	 *
+	 * The selected content slot is supported only in the default (stacked) variant. `inline` and `grid` ignore it.
+	 *
 	 * @implementation The `block`, `inline` and `grid` variants are more suitable for button looking choices, but it's at the
 	 * discretion of each surface.
 	 *
@@ -1969,6 +1979,8 @@ interface ClickableChipProps$1 extends ChipProps$1, GlobalProps {
 	 *
 	 * If the chip is not `removable`, it can still be hidden by setting this property.
 	 *
+	 * When using the `removable` variant, keep `hidden` synced with your app state. If `hidden` isn't updated after the chip is removed, the chip can become permanently hidden.
+	 *
 	 * @default false
 	 */
 	hidden?: boolean;
@@ -2051,6 +2063,8 @@ export type ConsentPolicy = "sms-marketing";
 interface ConsentCheckboxProps$1 extends GlobalProps, CheckboxProps$1 {
 	/**
 	 * The policy for which user consent is being collected.
+	 *
+	 * Only `sms-marketing` is supported. Other consent policy types aren't available through this component.
 	 */
 	policy?: ConsentPolicy;
 }
@@ -2059,13 +2073,17 @@ interface PhoneFieldProps$1 extends GlobalProps, BaseTextFieldProps, Pick<FieldD
 	/**
 	 * The type of phone number to collect. Specific styling may be applied to each type to provide extra guidance to users. No additional validation is performed based on the type.
 	 *
+	 * Styling hint for the input keyboard. Doesn't validate the phone number format. Implement validation in your extension and use the `error` prop to show results.
+	 *
 	 * @default ''
 	 */
 	type?: "mobile" | "";
 }
 interface ConsentPhoneFieldProps$1 extends GlobalProps, PhoneFieldProps$1 {
 	/**
 	 * The policy for which user consent is being collected.
+	 *
+	 * Only `sms-marketing` is supported.
 	 */
 	policy?: ConsentPolicy;
 }
@@ -2119,6 +2137,8 @@ interface DatePickerProps$1 extends GlobalProps, InputProps, FocusEventProps {
 	 *       So `--2024` is equivalent to `--2024-12-31`.
 	 *     - Whitespace is allowed either side of `--`.
 	 *
+	 * Comma-separated list of allowed dates in `YYYY-MM-DD` format.
+	 *
 	 * @default ""
 	 *
 	 * @example
@@ -2146,6 +2166,8 @@ interface DatePickerProps$1 extends GlobalProps, InputProps, FocusEventProps {
 	 *       So `--2024` is equivalent to `--2024-12-31`.
 	 *     - Whitespace is allowed either side of `--`.
 	 *
+	 * Comma-separated list of disallowed dates in `YYYY-MM-DD` format.
+	 *
 	 * @default ""
 	 *
 	 * @example
@@ -2210,6 +2232,8 @@ interface DatePickerProps$1 extends GlobalProps, InputProps, FocusEventProps {
 	 * - If `type="multiple"`, this is a comma-separated list of dates in `YYYY-MM-DD` format.
 	 * - If `type="range"`, this is a range in `YYYY-MM-DD--YYYY-MM-DD` format. The range is inclusive.
 	 *
+	 * Single dates use ISO 8601 format (`YYYY-MM-DD`); ranges use `YYYY-MM-DD--YYYY-MM-DD`. Locale-specific formats aren't supported.
+	 *
 	 * @default ""
 	 */
 	value?: string;
@@ -2327,6 +2351,9 @@ interface DropZoneProps$1 extends GlobalProps, FileInputProps, BasicFieldProps {
 	 */
 	onDropRejected?: (event: Event) => void;
 }
+/**
+ * Doesn't perform automatic format validation. Implement validation logic yourself and use the `error` prop to display results.
+ */
 interface EmailFieldProps$1 extends GlobalProps, BaseTextFieldProps, MinMaxLengthProps, AutocompleteProps<EmailAutocompleteField> {
 }
 export type EmailAutocompleteField = ExtractStrict<AnyAutocompleteField, "email" | `${AutocompleteAddressGroup} email`>;