Skip to content

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

Merged
sordaz00 merged 7 commits into2026-04-rcfrom
forms-web-components-2026-04-rc
Apr 9, 2026
Merged

Improve Forms component descriptions to match admin quality (2026-04-rc)#4271
sordaz00 merged 7 commits into2026-04-rcfrom
forms-web-components-2026-04-rc

Conversation

@sordaz00
Copy link
Copy Markdown
Contributor

@sordaz00 sordaz00 commented Apr 7, 2026

Summary

Updates JSDoc descriptions for all Forms web components to match admin quality:

  • Props interface: "Configure the following properties on the X component."
  • Events interface: "The X component provides event callbacks..." with Polaris handling-events link
  • Slots interface: "The X component supports slots..." with Polaris using-slots link
  • Event members: "A callback fired when..." with MDN Learn more links
  • Shared props (id, name, label, error, etc.) enriched to match admin descriptions

Files changed

  • 21 checkout component .d.ts files (18 Forms + Choice, Option, Chip)
  • components-shared.d.ts (shared prop descriptions)
  • CA generated_docs_data_v2.json for 2026-04-rc

Made with Cursor

@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Apr 7, 2026

🚨🚨🚨 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:

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! 🙏

@sordaz00 sordaz00 force-pushed the forms-web-components-2026-04-rc branch from 19340be to db43c67 Compare April 7, 2026 14:50
sordaz00 added 5 commits April 8, 2026 19:45
@sordaz00
Improve Forms component descriptions to match admin quality
0186db6 
- Update event/slot interface descriptions with Polaris handling-events and using-slots links
- Align event member descriptions to admin pattern: "A callback fired when..." with MDN links
- Update shared InputProps/MultipleInputProps/FileInputProps/FocusEventProps descriptions
- Use lowercase friendly names for all component references in prose

Made-with: Cursor
@sordaz00
Address review feedback: fix commandFor, command, name, choice descri…
8c70cf7 
…ptions

- commandFor: rewrite with clear pairing guidance and MDN link
- command: capitalize value descriptions, remove vague docs reference, lowercase "clipboard item"
- interestFor: enriched description
- name (BaseCheckableProps): remove Form backticks, use plain "form"
- Choice error: remove ChoiceList backticks, rewrite clearly
- Choice secondaryContent: replace circular description with helpful text

Made-with: Cursor
@sordaz00
Address review feedback: autocomplete, disabled, checked/selected des…
b56a9d5 
…criptions

- autocomplete: condensed opening, @see -> Learn more inline link, simplified defaults
- disabled: "Disables the field/control" -> "Whether the field/control is disabled"
- checked/selected: "active" -> "checked"/"selected" (less ambiguous)
- defaultChecked/defaultSelected: same fix

Made-with: Cursor
@sordaz00
Regen CA v2 JSON with review feedback fixes
e0705ab 
Made-with: Cursor
@sordaz00
Fix remaining review items: min->minimum, policy/sms placement, autoc…
2caa91c 
…omplete section, disabled wording

Made-with: Cursor
@sordaz00 sordaz00 force-pushed the forms-web-components-2026-04-rc branch 3 times, most recently from 4e2d8fe to 9c9f627 Compare April 9, 2026 01:23
@sordaz00
Fix number-field review items: controls ordering, inputMode values, m…
e970e8c 
…ax/min contractions, prefix/suffix

Made-with: Cursor
@sordaz00 sordaz00 force-pushed the forms-web-components-2026-04-rc branch from 9c9f627 to e970e8c Compare April 9, 2026 01:43
mcvinci
mcvinci approved these changes Apr 9, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

@mcvinci mcvinci left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

❤️

@sordaz00 sordaz00 merged commit 7372500 into 2026-04-rc Apr 9, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@mcvinci mcvinci mcvinci approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@sordaz00 @mcvinci