Deprecate suggestion prop in TextField component in favor of Autocomplete for accessibility and functionality

[daviareias]

Problem

The current suggestion prop in the TextField component (documentation) has critical functional and accessibility issues:

1. Unexpected Behavior: The inline suggestion does not clear correctly when pressing Backspace, leading to potential data inconsistencies.
2. Accessibility Violations:
   • The suggestion text is not programmatically linked to the input, making it unclear for screen reader users.
   • On blur, the suggestion overrides the input value without explicit user consent, violating WCAG Success Criterion 3.2.2 (Predictable Input).
3. Usability Concerns: The forced suggestion interaction pattern conflicts with standard input expectations, risking user confusion.

How to replicate the problem

1. Go to https://polaris.shopify.com/components/selection-and-input/text-field?example=text-field-with-inline-suggestion
2. Type "al", Alabama should appear as suggestion.
3. Press backspace -> suggestion won't be cleared
4. blur the input -> suggestion will still replace old value

Recommended Solution

Deprecate the suggestion prop and direct users to the Polaris Autocomplete component, which:

• Provides a robust, accessible solution for suggestion-based inputs.
• Handles keyboard navigation, ARIA roles, and screen reader announcements correctly.
• Allows explicit user selection of suggestions without overriding input values unexpectedly.

Deprecation Plan

1. Add a deprecation warning when the suggestion prop is used, linking to the Autocomplete documentation.
2. Remove the suggestion prop in the next major version of Polaris.
3. Update all internal Shopify usage of TextField with suggestions to migrate to Autocomplete.

Migration Example

Before (TextField with suggestion):

<TextField suggestion="Alabama" />

After (Autocomplete):

<Autocomplete
  options={[{value: 'alabama', label: 'Alabama'}]}
  onSelect={(value) => {/* Handle selection */}}
/>

Additional Context

• The Autocomplete component adheres to WAI-ARIA design patterns for comboboxes, ensuring accessibility compliance.
• For simple placeholder-like hints without interactivity, recommend using the placeholder prop instead.