[CMSDS-3582] Deprecate ariaClearLabel prop for Autocomplete (#3812)

* Add deprecation warning for Type docs and console in dev mode

* Add unit tests to verify deprecation warning

* Updates the web component docs as well

* Updates storybook docs snapshots

Author: tamara-corbalt

packages/design-system/src/components/Autocomplete/Autocomplete.test.tsx

@@ -347,6 +347,36 @@ describe('Autocomplete', () => {
   });
 
   describe('default props', () => {
+    describe('ariaClearLabel deprecation', () => {
+      const originalEnv = process.env.NODE_ENV;
+      let consoleWarnSpy: jest.SpyInstance;
+
+      beforeEach(() => {
+        process.env.NODE_ENV = 'development';
+        consoleWarnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
+      });
+
+      afterEach(() => {
+        process.env.NODE_ENV = originalEnv;
+        consoleWarnSpy.mockRestore();
+      });
+
+      it('logs a deprecation warning when ariaClearLabel is used in dev mode', () => {
+        renderAutocomplete({ ariaClearLabel: 'Old label' });
+
+        expect(consoleWarnSpy).toHaveBeenCalledWith(
+          expect.stringContaining("[Deprecated]: The 'ariaClearLabel' prop is deprecated")
+        );
+      });
+
+      it('does not log a warning in production mode', () => {
+        process.env.NODE_ENV = 'production';
+        renderAutocomplete({ ariaClearLabel: 'Old label' });
+
+        expect(consoleWarnSpy).not.toHaveBeenCalled();
+      });
+    });
+
     it('defaults ariaClearLabel', () => {
       renderAutocomplete();
       const button = screen.getByRole('button');

packages/design-system/src/components/Autocomplete/Autocomplete.tsx

@@ -60,7 +60,12 @@ export type AutocompleteItems = Array<AutocompleteItem | AutocompleteItemGroup>;
 
 export interface AutocompleteProps {
   /**
-   * Screen reader-specific label for the Clear search `<button>`. Intended to provide a longer, more descriptive explanation of the button's behavior.
+   * @deprecated Use the `clearInputText` prop (which sets the visible Clear search button text) instead.
+   *
+   * Providing an `aria-label` on the Clear Search `<button>` can override its visible text label,
+   * which may confuse users who rely on both visual and screen reader feedback when the two differ.
+   * This prop was originally intended to provide a more descriptive label for screen reader users
+   * but is no longer recommended.
    */
   ariaClearLabel?: string;
   /**
@@ -199,6 +204,13 @@ export const Autocomplete = (props: AutocompleteProps) => {
     ...autocompleteProps
   } = props;
 
+  if (process.env.NODE_ENV !== 'production' && ariaClearLabel) {
+    console.warn(
+      "[Deprecated]: The 'ariaClearLabel' prop is deprecated and will be removed in a future release. " +
+        "Use the 'clearInputText' prop instead to set the visible Clear search button text."
+    );
+  }
+
   const hasValidStandaloneItems = items?.some((item) => !('items' in item));
   const hasValidGroupedItems = items?.some((item) => 'items' in item && item.items?.length > 0);
 

packages/design-system/src/components/web-components/ds-autocomplete/ds-autocomplete.stories.tsx

@@ -39,8 +39,12 @@ const meta: Meta = {
   },
   argTypes: {
     'aria-clear-label': {
-      description:
-        "Screen reader-specific label for the Clear search `<button>`. Intended to provide a longer, more descriptive explanation of the button's behavior.",
+      description: `
+**Deprecated:** Use the \`clearInputText\` prop instead to set the visible Clear search button text.
+
+Providing an \`aria-label\` on the Clear Search button can override its visible text label, 
+which may confuse users who rely on both visual and screen reader feedback when the two differ.
+      `,
       control: 'text',
     },
     'aria-complete-label': {

tests/browser/snapshots/storybook-docs/Docs-Components-Autocomplete-Docs-prop-table-matches-snapshot-1.txt

@@ -8,9 +8,12 @@
   [
     "Deprecated: This is no longer used"
   ],
+  [
+    "Deprecated: Use the `clearInputText` prop (which sets the visible Clear search button text) instead. Providing an `aria-label` on the Clear Search `<button>` can override its visible text label, which may confuse users who rely on both visual and screen reader feedback when the two differ. This prop was originally intended to provide a more descriptive label for screen reader users but is no longer recommended."
+  ],
   [
     "ariaClearLabel",
-    "Screen reader-specific label for the Clear search <button>. Intended to provide a longer, more descriptive explanation of the button's behavior.\nstring",
+    "string\nDeprecated: Use the `clearInputText` prop (which sets the visible Clear search button text) instead. Providing an `aria-label` on the Clear Search `<button>` can override its visible text label, which may confuse users who rely on both visual and screen reader feedback when the two differ. This prop was originally intended to provide a more descriptive label for screen reader users but is no longer recommended.",
     "Clear search to try again"
   ],
   [

tests/browser/snapshots/storybook-docs/Docs-Web-Components-ds-autocomplete-Docs-prop-table-matches-snapshot-1.txt

@@ -1,7 +1,7 @@
 [
   [
     "aria-clear-label",
-    "Screen reader-specific label for the Clear search <button>. Intended to provide a longer, more descriptive explanation of the button's behavior.",
+    "Deprecated: Use the clearInputText prop instead to set the visible Clear search button text.\n\nProviding an aria-label on the Clear Search button can override its visible text label, which may confuse users who rely on both visual and screen reader feedback when the two differ.",
     "string"
   ],
   [