Add JSDoc for component properties (2026-04)

[SteveSill]

Summary

Adds JSDoc to checkout component property descriptions whose documentation was moved out of ## Limitations sections in shopify-dev. Pairs with the .mdx cleanup in shopify/world#669910 and the multi-agent plan in shopify/world#660052.

References shopify/issues-learn#1612.

Properties touched (Agent D scope, D.* checkout components)

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

• D.2 ClickableChipProps$1.hidden — sync-with-app-state guidance for the removable variant.
• D.4 InteractionProps.commandFor — precedence note when both commandFor and href are set (used by the link component).
• D.6 BadgeProps$1.icon — icon position is fixed relative to text content.
• D.7 CheckboxProps$1.required — required adds semantic meaning, doesn't auto-validate.
• D.8 ChoiceListProps$1.variant — selected content slot supported in the default (stacked) variant only.
• D.8 MultipleInputProps.values — form data captures selected value strings only.
• D.9 ConsentCheckboxProps$1.policy — only sms-marketing is supported.
• D.10 PhoneFieldProps$1.type — styling hint, doesn't validate phone format (used by consent-phone-field).
• D.10 ConsentPhoneFieldProps$1.policy — only sms-marketing is supported.
• D.11 DatePickerProps$1.allow — comma-separated list in YYYY-MM-DD (used by date-field via Pick<>).
• D.11 DatePickerProps$1.disallow — comma-separated list in YYYY-MM-DD (used by date-field via Pick<>).
• D.12 DatePickerProps$1.value — ISO 8601 format (also covers D.11 date-field value via Pick<>).
• D.13 EmailFieldProps$1 interface description — doesn't perform automatic format validation.

Notes / deviations from the plan

• D.4 commandFor: Per the plan, edited at the base interface (InteractionProps). The note is conditional on href being set, so it's accurate for both link (which has href) and button (vacuously true).
• D.11 / D.12 value: Both date-field and date-picker share the value prop via Pick<DatePickerProps$1, "value" | ...>. The D.12 text (which covers ranges) supersedes the D.11 text (single dates only) since it's broader and accurate for both. Added once on DatePickerProps$1.value.
• D.13 email-field component-level: EmailFieldProps$1 had no leading description. Added a JSDoc block above the interface declaration.
• Style: Removed em dashes from the plan text (replaced with periods or commas) per the agreed style rules. Kept "only" next to what it modifies.

Test plan

• CI passes on this PR
• Sibling PRs land for 2025-10, 2026-01, 2026-07-rc with byte-identical JSDoc

Generated with Claude Code

[github-actions]

🚨🚨🚨 Docs migration in progress 🚨🚨🚨

We are actively migrating UI extension reference docs to MDX in the areas/platforms/shopify-dev zone of the monorepo. This impacts docs for the following surfaces:

• Admin UI extensions
• App Home
• Checkout UI extensions
• Customer account UI extensions
• POS UI extensions

During this migration, please be aware of the following:

.doc.ts files are being deprecated. Changes to .doc.ts files in this repo will not be reflected in the new MDX-based docs. If you need to update docs for a reference that has already been migrated, make your changes directly in the areas/platforms/shopify-dev zone of the monorepo instead.

Doc comments in .ts source files (the comment blocks above types and functions) are also affected. Generating docs from these comments currently requires a newer version of the @shopify/generate-docs library that isn't yet available. Updates to doc comments may not produce the expected output until the migration is complete.

Examples that previously lived in this repo are being moved to the areas/platforms/shopify-dev zone of the monorepo and should be authored there going forward.

What should I do?

• If your PR includes changes to .doc.ts files, doc comments, or examples, please reach out to us in #devtools-proj-templated-refs so we can help ensure your updates are captured correctly.
• If your PR is limited to source code changes (non-docs), you can ignore this notice.

Thanks for your patience while we complete the migration! 🙏

[github-actions]

This PR targets a stable release branch (2026-04). Once merged, the change typically also needs to be forward-ported to 2026-07-rc so it ships in the next release.

When you open the forward-port PR, include a line like this in its body so the needs-rc-port label gets removed automatically when that PR merges:

Forward-port of #4409

Accepted formats (comma-separated for multiple):

• #4409
• GH-4409
• 4409
• https://github.com/Shopify/ui-extensions/pull/4409

If a forward-port isn't needed (e.g., the change is stable-only), you can remove the needs-rc-port label manually.

[github-actions]

We detected some changes in packages/*/package.json or packages/*/src, and there are no updates in the .changeset directory. If the changes are user-facing and should cause a version bump, run yarn changeset to track your changes and include them in the next release CHANGELOG. If you are making simple updates to repo configuration, examples, or documentation, you do not need to add a changeset.