Add readOnly prop to SingleSelect and MultiSelect #2873

beaesguerra · 2025-11-24T21:29:56Z

Summary:

As part of the Thunderblocks work, form fields have new visual styling for the readOnly state. This PR adds readOnly support for SingleSelect and MultiSelect:

read only styling is applied
aria-disabled is set on the combobox
behaviour is updated so the select cannot be opened when it is in a read only state

We use aria-disabled instead of aria-readonly for the read only state because of low browser + screen reader support. aria-readonly on a combobox role is not currently read out (tested with NVDA + Chrome/Firefox and VoiceOver + Safari). aria-disabled will read out "unavailable" for NVDA + Chrome/Firefox and "dimmed" for VoiceOver + Safari. When readOnly SingleSelect and MultiSelect components are used, they should be used with the LabeledField component with the readOnlyMessage prop set to provide context on why the field is in a read only state.

Test plan:

For SingleSelect and MultiSelect:

Confirm read only stying on the default opener
Confirm aria-disabled is set on the combobox (and that it is not set if aria-readonly is not set or is false)

This should apply to both default and custom openers

Confirm that the value of a Single/MultiSelect can't be opened or updated when in a read only state

This should apply to both default and custom openers
This means it can't be opened via clicking or keyboard navigation

Confirm its usage with LabeledField /?path=/story/packages-labeledfield--fields

changeset-bot · 2025-11-24T21:30:00Z

🦋 Changeset detected

Latest commit: a799388

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@khanacademy/wonder-blocks-dropdown	Minor
@khanacademy/wonder-blocks-labeled-field	Patch
@khanacademy/wonder-blocks-birthday-picker	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

github-actions · 2025-11-24T21:30:26Z

npm Snapshot: Published

🎉 Good news!! We've packaged up the latest commit from this PR (9afaf81) and published all packages with changesets to npm.

You can install the packages in frontend by running:

./dev/tools/deploy_wonder_blocks.js --tag="PR2873"

Packages can also be installed manually by running:

pnpm add @khanacademy/wonder-blocks-<package-name>@PR2873

github-actions · 2025-11-24T21:31:04Z

Size Change: +172 B (+0.16%)

Total Size: 109 kB

Filename	Size	Change
`packages/wonder-blocks-dropdown/dist/es/index.js`	19.5 kB	+170 B (+0.88%)
`packages/wonder-blocks-labeled-field/dist/es/index.js`	3.48 kB	+2 B (+0.06%)

ℹ️ View Unchanged

Filename	Size
`packages/wonder-blocks-accordion/dist/es/index.js`	3 kB
`packages/wonder-blocks-announcer/dist/es/index.js`	1.74 kB
`packages/wonder-blocks-badge/dist/es/index.js`	2.02 kB
`packages/wonder-blocks-banner/dist/es/index.js`	2.01 kB
`packages/wonder-blocks-birthday-picker/dist/es/index.js`	1.92 kB
`packages/wonder-blocks-breadcrumbs/dist/es/index.js`	755 B
`packages/wonder-blocks-button/dist/es/index.js`	4.25 kB
`packages/wonder-blocks-card/dist/es/index.js`	1.06 kB
`packages/wonder-blocks-cell/dist/es/index.js`	2.18 kB
`packages/wonder-blocks-clickable/dist/es/index.js`	2.66 kB
`packages/wonder-blocks-core/dist/es/index.js`	2.48 kB
`packages/wonder-blocks-data/dist/es/index.js`	5.48 kB
`packages/wonder-blocks-form/dist/es/index.js`	6.2 kB
`packages/wonder-blocks-grid/dist/es/index.js`	1.24 kB
`packages/wonder-blocks-icon-button/dist/es/index.js`	3.2 kB
`packages/wonder-blocks-icon/dist/es/index.js`	1.91 kB
`packages/wonder-blocks-layout/dist/es/index.js`	1.63 kB
`packages/wonder-blocks-link/dist/es/index.js`	1.52 kB
`packages/wonder-blocks-modal/dist/es/index.js`	7.06 kB
`packages/wonder-blocks-pill/dist/es/index.js`	1.31 kB
`packages/wonder-blocks-popover/dist/es/index.js`	4.3 kB
`packages/wonder-blocks-progress-spinner/dist/es/index.js`	1.48 kB
`packages/wonder-blocks-search-field/dist/es/index.js`	1.1 kB
`packages/wonder-blocks-styles/dist/es/index.js`	464 B
`packages/wonder-blocks-switch/dist/es/index.js`	1.55 kB
`packages/wonder-blocks-tabs/dist/es/index.js`	3.74 kB
`packages/wonder-blocks-testing-core/dist/es/index.js`	3.25 kB
`packages/wonder-blocks-testing/dist/es/index.js`	978 B
`packages/wonder-blocks-theming/dist/es/index.js`	384 B
`packages/wonder-blocks-timing/dist/es/index.js`	1.37 kB
`packages/wonder-blocks-tokens/dist/es/index.js`	5.01 kB
`packages/wonder-blocks-toolbar/dist/es/index.js`	906 B
`packages/wonder-blocks-tooltip/dist/es/index.js`	6.4 kB
`packages/wonder-blocks-typography/dist/es/index.js`	1.57 kB

_{compressed-size-action}

github-actions · 2025-11-24T21:32:58Z

A new build was pushed to Chromatic! 🚀

https://5e1bf4b385e3fb0020b7073c-egylwtzumw.chromatic.com/

Chromatic results:

Metric	Total
Captured snapshots	151
Tests with visual changes	0
Total stories	751
Inherited (not captured) snapshots [TurboSnap]	297
Tests on the build	448

beaesguerra · 2025-11-26T18:17:34Z

packages/wonder-blocks-labeled-field/src/components/labeled-field.tsx

            error: hasError,
            testId: testId ? `${testId}-field` : undefined,
-            readOnly: readOnlyMessage || field.props.readOnly,
+            readOnly: !!readOnlyMessage || field.props.readOnly,


This makes it so the readOnly prop passed in is a boolean instead of a string

beaesguerra · 2025-11-26T18:20:14Z

packages/wonder-blocks-dropdown/src/components/select-opener.tsx

        cursor: "pointer",
-        // :focus-visible -> Provide focus styles for keyboard users only.
-        ...focusStyles.focus,
+        ":focus": {


Changed to :focus instead of :focus-visible so that it has the same behaviour as other form fields

Using :focus-visible (readonly state):

Screen.Recording.2025-11-26.at.11.19.02.AM.mov

Using :focus (readonly state):

Screen.Recording.2025-11-26.at.11.18.36.AM.mov

Using :focus-visible (default state - focus outline isn't shown on the selector):

Screen.Recording.2025-11-26.at.11.21.01.AM.mov

Using :focus(default state - focus outline is shown on the selector temporarily):

Screen.Recording.2025-11-26.at.11.21.13.AM.mov

beaesguerra · 2025-11-26T18:24:18Z

packages/wonder-blocks-dropdown/src/components/dropdown-opener.tsx

+            // are true, set to undefined so attribute isn't set
+            // Note: We set `aria-disabled` instead of `aria-readonly` due to
+            // low browser + screen reader support for `aria-readonly` on comboboxes.
+            "aria-disabled": readOnly || disabled || undefined,


Something new is that if readOnly and disabled props are falsy, the aria-disabled attribute won't be set to false explicitly anymore

khan-actions-bot · 2025-11-26T18:27:06Z

Gerald

Required Reviewers

@Khan/wonder-blocks for changes to .changeset/hungry-bats-switch.md, .changeset/mighty-apricots-wave.md, __docs__/wonder-blocks-dropdown/base-select.argtypes.ts, __docs__/wonder-blocks-dropdown/multi-select-testing-snapshots.stories.tsx, __docs__/wonder-blocks-dropdown/multi-select.accessibility.mdx, __docs__/wonder-blocks-dropdown/multi-select.accessibility.stories.tsx, __docs__/wonder-blocks-dropdown/multi-select.stories.tsx, __docs__/wonder-blocks-dropdown/single-select-testing-snapshots.stories.tsx, __docs__/wonder-blocks-dropdown/single-select.accessibility.mdx, __docs__/wonder-blocks-dropdown/single-select.accessibility.stories.tsx, __docs__/wonder-blocks-dropdown/single-select.stories.tsx, packages/wonder-blocks-dropdown/src/components/dropdown-opener.tsx, packages/wonder-blocks-dropdown/src/components/multi-select.tsx, packages/wonder-blocks-dropdown/src/components/select-opener.tsx, packages/wonder-blocks-dropdown/src/components/single-select.tsx, packages/wonder-blocks-labeled-field/src/components/labeled-field.tsx, packages/wonder-blocks-dropdown/src/components/__tests__/dropdown-opener.test.tsx, packages/wonder-blocks-dropdown/src/components/__tests__/multi-select.test.tsx, packages/wonder-blocks-dropdown/src/components/__tests__/select-opener.test.tsx, packages/wonder-blocks-dropdown/src/components/__tests__/single-select.test.tsx

Don't want to be involved in this pull request? Comment #removeme and we won't notify you of further changes.

marcysutton

This is great progress! I left some comments and questions, and found one bug with arrow key navigation.

I'm also wondering if ActionMenu is affected at all since it shares DropdownOpener. I didn't dig into that, though!

marcysutton · 2025-12-03T23:42:23Z

__docs__/wonder-blocks-dropdown/single-select-testing-snapshots.stories.tsx

-        pseudo: defaultPseudoStates,
+        pseudo: {
+            ...defaultPseudoStates,
+            // Using the focus selector instead so that the focus outline is shown


Thanks for adding a comment here! What an odd scenario where focus is preferable for once. Is it because it's technically programmatic focus?

It is so the focus behaviour looks more similar to other form fields! This PR comment shows the difference between using focus and focus-visible: #2873 (comment)

There is also a comment where we set the focus styles for context!

wonder-blocks/packages/wonder-blocks-dropdown/src/components/select-opener.tsx

Lines 262 to 267 in a799388

":focus": {

// Using :focus instead of :focus-visible to ensure the focus ring is

// visible when the button is focused (even when clicked). This makes

// the focus behaviour more consistent with the other field components.

...focusStyles.focus[":focus-visible"],

},

marcysutton · 2025-12-03T23:46:54Z

__docs__/wonder-blocks-dropdown/single-select.accessibility.mdx

+browser + screen reader support currently with `combobox` roles. Using
+`aria-disabled` and the `readOnlyMessage` provides contextual information to
+users (`LabeledField`'s `readOnlyMessage` is included in the combobox element's
+`aria-describedby` attribute)


Can you add a working example showing usage with LabeledField? The aria-describedby with "Read only" in it is important screen reader context, but it isn't visible in the main ReadOnly docs:

It might also help to list the ReadOnly example among the other stories since there would be a canvas:

Good idea! I've included the LabeledField usage in the SingleSelect and MultiSelect Read Only stories. I also added examples with LabeledField for the readonly state in the a11y sections!

marcysutton · 2025-12-03T23:51:07Z

__docs__/wonder-blocks-dropdown/multi-select.accessibility.mdx

-<Canvas of={MultiSelectAccessibilityStories.WithVisibleAnnouncer} />
+<Canvas of={MultiSelectAccessibilityStories.WithVisibleAnnouncer} />
+
+## Read only state


I thought of this by the time I read on to the SingleSelect docs, but the same applies here: can you add a working example with LabeledField to show the effect of aria-describedby and the "Read only" text?

marcysutton · 2025-12-03T23:54:45Z

packages/wonder-blocks-dropdown/src/components/__tests__/dropdown-opener.test.tsx

+import userEvent from "@testing-library/user-event";
+import DropdownOpener from "../dropdown-opener";
+
+describe("DropdownOpener", () => {


I'm surprised there weren't already tests for DropdownOpener! Thanks for adding them!

marcysutton · 2025-12-03T23:55:50Z

packages/wonder-blocks-dropdown/src/components/__tests__/dropdown-opener.test.tsx

+            );
+
+            // Assert
+            expect(screen.getByRole("combobox")).not.toBeDisabled();


That is such a nuanced difference with the toBeDisabled matcher... here's hoping they don't ever add aria-disabled to the heuristics!

I ended up removing this test! I had originally added this when I first implemented aria-readonly before I manually tested for screen reader support (I was trying to confirm that it didn't have both aria-readonly and aria-disabled). Good to know though that we should probably explicitly check for disabled/aria-disabled attributes since this matcher is nuanced!

marcysutton · 2025-12-03T23:58:59Z

packages/wonder-blocks-dropdown/src/components/__tests__/multi-select.test.tsx

+                        <OptionItem label="item 2" value="2" />
+                    </MultiSelect>,
+                );
+                const combobox = await screen.findByRole("combobox");


I remembered today that Jeff suggested we avoid findBy queries unless absolutely necessary since they return Promises. Does this test pass with synchronous screen.getByRole?

marcysutton · 2025-12-04T00:00:12Z

packages/wonder-blocks-dropdown/src/components/__tests__/multi-select.test.tsx

+                await userEvent.tab();
+
+                // Assert
+                expect(await screen.findByRole("combobox")).toHaveFocus();


Same as above: does this assertion work with screen.getByRole?

marcysutton · 2025-12-04T00:01:38Z

packages/wonder-blocks-dropdown/src/components/__tests__/select-opener.test.tsx

+            );
+
+            // Act
+            await userEvent.keyboard("{Tab}");


Should we use await userEvent.tab(); for consistency with other tests? It is nice there's more than one way to tab programmatically!

marcysutton · 2025-12-04T00:04:28Z

packages/wonder-blocks-dropdown/src/components/dropdown-opener.tsx

-            disabled={disabled}
+            // If readOnly is true, clickable behaviour should be disabled to
+            // prevent interactions. Note: DropdownOpener is responsible for
+            // adding attributes to the opener


Thanks for this comment about where the attributes are set! That will come in handy!

marcysutton · 2025-12-04T00:09:50Z

packages/wonder-blocks-dropdown/src/components/select-opener.tsx

-                onKeyDown={!disabled ? this.handleKeyDown : undefined}
-                onKeyUp={!disabled ? this.handleKeyUp : undefined}
+                onClick={allowInteraction ? this.handleClick : undefined}
+                onKeyDown={allowInteraction ? this.handleKeyDown : undefined}


I'm still able to open the SingleSelect and MultiSelect with the down arrow key in all browsers. Here is a screenshot:

I believe the logic for arrow key handling is in DropdownCore?

Good catch yes! I disabled interactions in DropdownCore now when the selects are in a readonly state. Also added some tests!

…ad only styles, adds the aria-readonly attribute, and disables event handlers when readOnly is true

… aria-readonly and disables the interactions

…is passed into opener components and that it can't be opened when the opened prop is true and readOnly is true

…se aria-readonly doesn't have great sr support right now (tested with Chrome + Firefox with NVDA, Safari + VoiceOver)

… focus selector for those tests

…pener for multiselect

…Select` and `MultiSelect`. It applies read only styling for the TB theme, adds aria-disabled=true to the combobox element and disables interactions on the field

…readOnly prop so it is a boolean

…row to open the single and multiselect

…so true. This disables key handlers for dropdowncore

…s before when we thought we could use aria-readonly

beaesguerra · 2025-12-05T21:28:07Z

packages/wonder-blocks-dropdown/src/components/__tests__/multi-select.test.tsx

+jest.mock("react-popper", () => ({
+    ...jest.requireActual("react-popper"),
+    Popper: jest.fn().mockImplementation(({children}) => {
+        // Mock `isReferenceHidden` to always return false (or true for testing visibility)
+        return children({
+            ref: jest.fn(),
+            style: {},
+            placement: "bottom",
+            isReferenceHidden: false, // Mocking isReferenceHidden
+        });
+    }),
+}));
+


I followed TDD to confirm a fix for the bug where the selects would open using the down arrow key. The SingleSelect and MultiSelect tests had different behaviours. Turns out, SingleSelect had a mock for react-popper. I've copied it over to MultiSelect so they have the same configuration!

beaesguerra · 2025-12-05T21:28:35Z

packages/wonder-blocks-dropdown/src/components/__tests__/multi-select.test.tsx

+            it.each([
+                {key: "{Enter}", name: "Enter"},
+                {key: " ", name: "Space"},
+                {key: "{ArrowDown}", name: "Down arrow"},
+                {key: "{ArrowUp}", name: "Up arrow"},
+            ])(


Added more tests to make sure a variety of interactions don't open the dropdown

beaesguerra · 2025-12-05T21:32:39Z

I'm also wondering if ActionMenu is affected at all since it shares DropdownOpener.

@marcysutton Good question. The DropdownOpener component supports a new readOnly prop now, and this isn't used by ActionMenu so there are no changes there!

wonder-blocks/packages/wonder-blocks-dropdown/src/components/action-menu.tsx

Lines 264 to 275 in a799388

    
           <DropdownOpener 
        
               id={uniqueOpenerId} 
        
               aria-controls={dropdownId} 
        
               aria-haspopup="menu" 
        
               onClick={this.handleClick} 
        
               disabled={numItems === 0 || disabled} 
        
               text={menuText} 
        
               ref={this.handleOpenerRef} 
        
               testId={opener ? undefined : testId} 
        
               opened={this.state.opened} 
        
               role="button" 
        
           >

One difference is that aria-disabled won't be explicitly set anymore if it's false (see #2873 (comment))

marcysutton

Nice, great work @beaesguerra! I think you may need to update the branch from main for the Storybook failures, but otherwise looks good!

beaesguerra self-assigned this Nov 24, 2025

beaesguerra added the olc-5.0.869dc label Nov 24, 2025

beaesguerra force-pushed the dropdown-read-only branch from 527557b to 2f845f6 Compare November 25, 2025 21:25

beaesguerra commented Nov 26, 2025

View reviewed changes

beaesguerra marked this pull request as ready for review November 26, 2025 18:26

khan-actions-bot requested a review from a team November 26, 2025 18:27

marcysutton reviewed Dec 4, 2025

View reviewed changes

khan-actions-bot requested a review from a team December 5, 2025 21:11

beaesguerra added 17 commits December 5, 2025 14:18

[dropdown-read-only] Add readOnly prop to SelectOpener. It applies re…

c53877b

…ad only styles, adds the aria-readonly attribute, and disables event handlers when readOnly is true

[dropdown-read-only] Support readOnly prop in DropdownOpener. It sets…

47f8825

… aria-readonly and disables the interactions

[dropdown-read-only] Add readOnly prop to SingleSelect. Make sure it …

f6f8f18

…is passed into opener components and that it can't be opened when the opened prop is true and readOnly is true

[dropdown-read-only] Implement readOnly prop in MultiSelect

6aeb6a7

[dropdown-read-only] fix error

4b94f11

[dropdown-read-only] set aria-disabled instead of aria-readonly becau…

886b7ee

…se aria-readonly doesn't have great sr support right now (tested with Chrome + Firefox with NVDA, Safari + VoiceOver)

[dropdown-read-only] add readonly state to vis reg tests and also use…

d69c5ed

… focus selector for those tests

[dropdown-read-only] Add docs around the choice for using aria-readonly

47f7b7c

[dropdown-read-only] Add more docs. Add guidance for using a custom o…

67d0529

…pener for multiselect

[dropdown-read-only] disable chromatic for base readonly stories

1fff7df

[dropdown-read-only] Fix setting readOnly prop

b0c623c

[dropdown-read-only] docs(changeset): Add readOnly prop for `Single…

949da58

…Select` and `MultiSelect`. It applies read only styling for the TB theme, adds aria-disabled=true to the combobox element and disables interactions on the field

[dropdown-read-only] docs(changeset): LabeledField: Fix passing down …

6367622

…readOnly prop so it is a boolean

[dropdown-read-only] Create repro test cases for pressing the down ar…

054f45f

…row to open the single and multiselect

[dropdown-read-only] Set DropdownCore disabled prop if readonly is al…

c653ff5

…so true. This disables key handlers for dropdowncore

Add LabeledField to readonly examples to show how it should be used

db6dcd6

use .tab instead of keyboard({Tab}) for consistency

e209c95

beaesguerra added 4 commits December 5, 2025 14:18

add a11y stories for using readonly state with labeledfield

389a27f

[dropdown-read-only] Remove test checking for disabled state. This wa…

66337b0

…s before when we thought we could use aria-readonly

[dropdown-read-only] Use getByRole instead of findByRole

c959713

[dropdown-read-only] elaborate on focus selector usage

a799388

beaesguerra force-pushed the dropdown-read-only branch from 2f9c232 to a799388 Compare December 5, 2025 21:18

beaesguerra commented Dec 5, 2025

View reviewed changes

marcysutton approved these changes Dec 5, 2025

View reviewed changes

	":focus": {
	// Using :focus instead of :focus-visible to ensure the focus ring is
	// visible when the button is focused (even when clicked). This makes
	// the focus behaviour more consistent with the other field components.
	...focusStyles.focus[":focus-visible"],
	},

Add readOnly prop to SingleSelect and MultiSelect #2873

Are you sure you want to change the base?

Add readOnly prop to SingleSelect and MultiSelect #2873

Uh oh!

Conversation

beaesguerra commented Nov 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary:

Test plan:

Uh oh!

changeset-bot bot commented Nov 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

github-actions bot commented Nov 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

npm Snapshot: Published

Uh oh!

github-actions bot commented Nov 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Nov 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

A new build was pushed to Chromatic! 🚀

Chromatic results:

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!

khan-actions-bot commented Nov 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Gerald

Uh oh!

marcysutton left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

beaesguerra Dec 5, 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!

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!

beaesguerra commented Dec 5, 2025

Uh oh!

marcysutton left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

beaesguerra commented Nov 24, 2025 •

edited

Loading

changeset-bot bot commented Nov 24, 2025 •

edited

Loading

github-actions bot commented Nov 24, 2025 •

edited

Loading

github-actions bot commented Nov 24, 2025 •

edited

Loading

github-actions bot commented Nov 24, 2025 •

edited

Loading

khan-actions-bot commented Nov 26, 2025 •

edited

Loading

beaesguerra Dec 5, 2025 •

edited

Loading