feat: Support secondaryText and labelTag for button-dropdown #3844

kuahuu · 2025-09-05T15:40:39Z

Description

Added support for secondaryText and labelTag properties to ButtonDropdown items, enabling richer item content similar to other Cloudscape components like Select and Multiselect.

This PR also added deprecated annotation for description prop for button dropdown item.

New features:
secondaryText: Displays additional descriptive text below the main item text
labelTag: Adds a visual tag/label to items for categorization or status indication

Implementation details:

Extended ButtonDropdownProps.Item interface to include the new properties
Updated ItemElement component to render secondary text and label tags
Added corresponding styles for proper layout and visual hierarchy
Added comprehensive test coverage for the new functionality
Add deprecated annotation into the description prop
Introduce findSecondaryText and findLabelTag test utils

Related links, issue #, if available: n/a

How has this been tested?

Unit Tests:

Added tests in button-dropdown-items.test.tsx for secondaryText rendering
Added tests in button-dropdown-keyboard.test.tsx for keyboard navigation with secondaryText
All existing ButtonDropdown tests continue to pass

Manual Testing:

Verified visual appearance and layout of items with secondaryText and labelTag
Tested keyboard navigation and accessibility
Confirmed backward compatibility with existing ButtonDropdown usage

Reviewers can test by running:

npm test -- --testPathPattern="button-dropdown"
npm run test:integ -- --testPathPattern="button-dropdown"

Review checklist

The following items are to be evaluated by the author(s) and the reviewer(s).

Correctness

Changes include appropriate documentation updates.
Changes are backward-compatible if not indicated, see CONTRIBUTING.md.
Changes do not include unsupported browser features, see CONTRIBUTING.md.
Changes were manually tested for accessibility, see accessibility guidelines.

Security

If the code handles URLs: all URLs are validated through the checkSafeUrl function.

Testing

Changes are covered with new/existing unit tests?
Changes are covered with new/existing integration tests?

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

codecov · 2025-09-10T11:07:59Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.16%. Comparing base (46bf2fc) to head (0e1347b).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3844   +/-   ##
=======================================
  Coverage   97.16%   97.16%           
=======================================
  Files         850      850           
  Lines       24785    24791    +6     
  Branches     8735     8737    +2     
=======================================
+ Hits        24082    24088    +6     
  Misses        696      696           
  Partials        7        7

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

…description-deprecation

src/__tests__/snapshot-tests/__snapshots__/documenter.test.ts.snap

…description-deprecation

cansuaa · 2025-09-16T12:13:50Z

src/button-dropdown/interfaces.ts

+   * - `secondaryText` (string) - (Optional) Secondary text displayed in the menu for this item.
   * - `lang` (string) - (Optional) The language of the item, provided as a BCP 47 language tag.
   * - `disabled` (boolean) - whether the item is disabled. Disabled items are not clickable, but they can be highlighted with the keyboard to make them accessible.
   * - `disabledReason` (string) - (Optional) Displays text near the `text` property when item is disabled. Use to provide additional context.
-   * - `description` (string) - additional data that will be passed to a `data-description` attribute.
+   * - `description` (string) - additional data that will be passed to a `data-description` attribute. **Deprecated**, has no effect.
   * - `ariaLabel` (string) - (Optional) - ARIA label of the item element.
+   * - `labelTag` (string) - (Optional) - Label for the item. Displayed near the item text for visually impaired users.


The new APIs shouldn't be added here because this list is all the APIs available in all types which is not the case for the new APIs, they are only available in action and checkbox so instead of here, they should be down

Moved these 2 API description below to applicable types.

cansuaa · 2025-09-16T12:16:32Z

src/button-dropdown/item-element/styles.scss

+.text-with-icon {
+  display: flex;
+  align-items: center;
+}


This is not used anywhere?

Removed in latest PR

…e types

kuahuu · 2025-09-29T00:46:17Z

Rebased from the latest origin main and resolve the conflict.

cansuaa · 2025-09-29T12:45:27Z

src/test-utils/dom/button-dropdown/index.ts

+  /**
+   * Finds the label tag element for a dropdown item. Returns null if the element has no label tag.
+   */
+  findLabelTags(): ElementWrapper | null {


findLabelTag is more correct

Updated to findLabelTag

cansuaa · 2025-09-29T12:55:39Z

src/button-dropdown/item-element/index.tsx

+            <InternalBox fontWeight="light" data-testid={'button-dropdown-label-tag'}>
+              {item.labelTag}
+            </InternalBox>


Instead of having data-testid, I suggest wrapping {item.labelTag} with a span and a className. For className to work, you'll need to have the className defined in the styles files with a comment like this:

.label-tag { /* used in test-utils */ }

Additionally, something we started doing recently is having a different styles file where we add the classNames used for test-util so here you can follow a similar approach where you create a folder called test-classes under button-dropdown folder and create a new styles.scss where you have this class defined. The same thing applies to the secondaryText below. You don't need to define any other class in that - the old ones should stay as is.

Or actually, instead of using InternalBox, use a div with a classname and apply the styles to the div. For color you can use this design token color-text-dropdown-item-secondary, this way the users who wish to change the colors will be able to do so. With InternalBox a different design token would be used which is an implementation detail and users wouldn't expect that design token to be used here.

And one more thing, the label tag shouldn't have the same color with description. In select component, it is that way and it's better to keep it consistent.

Replaced the InternalBox with div + css classes defined in the styles.scss file.

But the description and label tag seem use the same color in Select component

As Cansu said, the label tag should be darker, just like in select. See the "128 Gb" here:

ahh seems there are both label tag and tags on the selector, and I was referring to tags.

Updated to color: awsui.$color-text-body-default; as reference

cansuaa · 2025-09-29T12:58:06Z

src/button-dropdown/interfaces.ts

+   * - `secondaryText` (string) - (Optional) Secondary text displayed in the menu for this item.
+   * - `labelTag` (string) - (Optional) - Label for the item. Displayed near the item text for visually impaired users.


In the documenter snapshot these still appear in their old place, could you update the snapshot again?

Pull and build again and now new props are showing on the right place

cansuaa · 2025-09-29T12:59:17Z

pages/button-dropdown/events.page.tsx

The integ tests are failing since these pages are updated but the tests not. Could you run them locally and update as expected?

Can you suggest how to resolve the following issue when run npm run test:integ?

FatalError: Jest: Got error running globalSetup - /Volumes/workplace/cloudscape-components/components/build-tools/integ/global-setup.js, reason: Cannot find local chromedriver. Did you run 'npm i -g chromedriver'?

You need to follow these instructions: https://github.com/cloudscape-design/components/blob/main/CONTRIBUTING.md#run-integration-tests.

Basically, you globally install chromedriver and then run the integ tests. You can specifically run the button dropdown tests only using this command:

npx jest -c jest.integ.config.js src/button-dropdown/__integ__

Make sure that you have the dev server (npm start) running somewhere else in the background

Thanks for the guidance. I'm now able to run the integration test and resolve all failure.

…description-deprecation

timogasda · 2025-10-10T08:21:54Z

package.json

      "path": "lib/components/internal/widget-exports.js",
      "brotli": false,
-      "limit": "962 kB",
+      "limit": "963 kB",


are we sure this is needed?

Yes, this was needed otherwise the bundle size was 962.1kb before.

timogasda · 2025-10-10T08:23:11Z

pages/button-dropdown/permutations-main-action.page.tsx

  href: 'https://instances.com',
  external: true,
  externalIconAriaLabel: '(opens in new tab)',
+  labelTag: 'Ctrl + Click',


Something broke here. If you go to this permutations page in the browser, you'll see the following error message:

hook.js:608 Warning: React does not recognize the labelTag prop on a DOM element. If you intentionally want it to appear in the DOM as a custom attribute, spell it as lowercase labeltag instead. If you accidentally passed it from a parent component, remove it from the DOM element.

That's also why the a11y tests are failing

Found the issue was these props are passing to another internal component and wasn't included in the destructuring assignment, causing it to be spread onto a DOM element. Remove the labelTag in this page as we do have labelTag in other permutation pages.

timogasda · 2025-10-10T08:25:32Z

src/button-dropdown/__integ__/button-dropdown-expandable.test.ts

There's a few integ tests that are failing. This is because you've added the new descriptions in a lot of places, which is now breaking the element text assertions.

Please 1) make sure to update test assertions where needed, and 2) review if we really need to add the new descriptions to all 9 button-dropdown pages that you're currently touching. I suggest we keep it simpler and only add it to the permutation pages and maybe 1-2 integ test pags.

Thanks for the callout. I've removed some description out of the example pages, and make the integ tests all passed now.

timogasda · 2025-10-10T08:28:24Z

pages/button-dropdown/events.page.tsx

You need to follow these instructions: https://github.com/cloudscape-design/components/blob/main/CONTRIBUTING.md#run-integration-tests.

Basically, you globally install chromedriver and then run the integ tests. You can specifically run the button dropdown tests only using this command:

npx jest -c jest.integ.config.js src/button-dropdown/__integ__

Make sure that you have the dev server (npm start) running somewhere else in the background

timogasda · 2025-10-10T08:30:01Z

src/button-dropdown/item-element/index.tsx

+            <InternalBox fontWeight="light" data-testid={'button-dropdown-label-tag'}>
+              {item.labelTag}
+            </InternalBox>


As Cansu said, the label tag should be darker, just like in select. See the "128 Gb" here:

This reverts commit f43c798.

…description-deprecation

…belTag

…description-deprecation

… ESC clicked (cloudscape-design#3941)

…sign#3694)

…pe-design#3796)

…description-deprecation

feat: Support secondaryText and labelTag for button-dropdown

a3f2998

kuahuu requested a review from a team as a code owner September 5, 2025 15:40

kuahuu requested review from YueyingLu and removed request for a team September 5, 2025 15:40

kuahuu had a problem deploying to dev-pages September 10, 2025 11:07 — with GitHub Actions Failure

Kuai Hu added 2 commits September 11, 2025 21:37

Merge branch 'main' into button-dropdown-secondaryText-labelTags-and-…

0318384

…description-deprecation

Add the missing document snapshots

a06cf13

cansuaa reviewed Sep 15, 2025

View reviewed changes

src/__tests__/snapshot-tests/__snapshots__/documenter.test.ts.snap Show resolved Hide resolved

Merge branch 'main' into button-dropdown-secondaryText-labelTags-and-…

390b77e

…description-deprecation

cansuaa reviewed Sep 16, 2025

View reviewed changes

Kuai Hu added 2 commits September 28, 2025 20:36

Merge commit

77e2289

remove unused css styling and move API description into the applicabl…

cc28835

…e types

cansuaa reviewed Sep 29, 2025

View reviewed changes

Kuai Hu added 3 commits October 10, 2025 00:59

Merge branch 'main' into button-dropdown-secondaryText-labelTags-and-…

da3f4e4

…description-deprecation

move usage of internalBox in button-dropdown and use styles instead

30b7018

fix the integration test and increase the size limit

0e1347b

kuahuu had a problem deploying to dev-pages-react16 October 10, 2025 07:52 — with GitHub Actions Failure

kuahuu had a problem deploying to dev-pages-react18 October 10, 2025 07:52 — with GitHub Actions Failure

timogasda requested changes Oct 10, 2025

View reviewed changes

timogasda and others added 3 commits October 13, 2025 11:23

test

f43c798

Revert "test"

f6068d5

This reverts commit f43c798.

Merge branch 'main' into button-dropdown-secondaryText-labelTags-and-…

8e6a9ed

…description-deprecation

YueyingLu removed their request for review October 23, 2025 09:00

Kuai Hu and others added 4 commits October 23, 2025 10:53

Merge branch 'main' into button-dropdown-secondaryText-labelTags-and-…

7ee0478

…description-deprecation

fix the broken integ and a11y tests. Correct the font and color of la…

5d132f9

…belTag

Merge branch 'main' into button-dropdown-secondaryText-labelTags-and-…

201e320

…description-deprecation

feat: Bottom drawer (v2) (cloudscape-design#3922)

9f8f63a

taheramr and others added 4 commits October 24, 2025 10:28

chore: Close autosuggest dropdown when recovery button is focused and…

fd77494

… ESC clicked (cloudscape-design#3941)

feat: Add support for download links in ButtonDropdown (cloudscape-de…

0500609

…sign#3694)

chore: consistently use direct imports for Lodash functions (cloudsca…

b507d79

…pe-design#3796)

Merge branch 'main' into button-dropdown-secondaryText-labelTags-and-…

2e78d15

…description-deprecation

kuahuu requested a review from timogasda October 24, 2025 15:29

		* - `secondaryText` (string) - (Optional) Secondary text displayed in the menu for this item.
		* - `labelTag` (string) - (Optional) - Label for the item. Displayed near the item text for visually impaired users.

feat: Support secondaryText and labelTag for button-dropdown #3844

Are you sure you want to change the base?

feat: Support secondaryText and labelTag for button-dropdown #3844

Uh oh!

Conversation

kuahuu commented Sep 5, 2025

Description

How has this been tested?

Unit Tests:

Manual Testing:

Reviewers can test by running:

Correctness

Security

Testing

Uh oh!

codecov bot commented Sep 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cansuaa Sep 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kuahuu commented Sep 29, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kuahuu Oct 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kuahuu Oct 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codecov bot commented Sep 10, 2025 •

edited

Loading

cansuaa Sep 16, 2025 •

edited

Loading

kuahuu Oct 23, 2025 •

edited

Loading

kuahuu Oct 23, 2025 •

edited

Loading