fix: correct the display of checkbox read-only state #3328

jawinn · 2024-10-25T20:34:34Z

Description

As noted in CSS-833, the CSS, SWC, and RSP implementations of read-only checkboxes/checkbox groups, and the docs surrounding them, conflicted with each other. After discussing with the design team, it was decided that the first step would be for CSS to bring our visual styles in line with React's implementation.

Field group:

This PR updates field group to remove the additional checkbox read-only styles that were causing the box to not display and for commas to be appended.
Template: added aria-labeledby connected to the group label, so this is announced as a group by the screen reader.

Checkbox:

Removes some unnecessary read-only CSS. Read-only just needs to override disabled styles. It was confirmed with PJ on the design team that otherwise it uses default styles (for both default and emphasized; React also displays this).
Template: The checkboxes are made sure to be shown as both focusable and immutable. Some JS was added to prevent the checkbox value from changing.
Template: disabled attribute removed when read-only. Read-only still needs to be focusable / in the tab order.
Template: Added aria-disabled="true" when read-only, so screen readers do not announce as a normal interactive checkbox. For VoiceOver, this will add "dimmed" now and won't announce the shortcut to check or uncheck. Note that I've not used aria-readonly like as seen in React Spectrum as it is not announced by the screen reader (any differently than a normal checkbox) and MDN states that it is "not relevant" for input with type checkbox.
Adds additional VRT tests to cover some missing combination of states

This also updates all of the docs surrounding these things and adds a new storybook Docs example for Checkbox. The field group usage notes have been cleaned up as well.

CSS-1004

How and where has this been tested?

Please tag yourself on the tests you've marked complete to confirm the tests have been run by someone other than the author.

Validation steps

Field group docs page: read-only example shows full checkbox with boxes and no added commas, and read-only colors
Checkbox docs page: read-only example shows full checkbox with boxes and no added commas, and read-only colors
Checkbox docs page: read-only default shows default colors and read-only emphasized shows emphasized colors (should include the blue, which is different than it was previously) @marissahuysentruyt
Checkbox testing preview: additional test cases appear and cover the usage of read-only @marissahuysentruyt
Review and proofread docs for both examples
Read-only checkbox is immutable in both docs and stories (clicking does not change checkedness)
Read-only checkboxes are focusable
Field group of checkboxes is announced as a group by screen reader (VoiceOver) @marissahuysentruyt
Read only checkboxes are announced as dimmed/disabled by screen reader @marissahuysentruyt

Regression testing

Expected changes:

Additional tests added
Read-only checked for emphasized now displays with blue
Field group read-only no longer shows comma display (see screenshots)

Validate:

The documentation pages for at least two other components are still loading, including:

The pages render correctly, are accessible, and are responsive.

If components have been modified, VRTs have been run on this branch:

VRTs have been run and looked at.
Any VRT changes have been accepted (by reviewer and/or PR author), or there are no changes.

Screenshots

Before:

After:

To-do list

I have read the contribution guidelines.
I have updated relevant storybook stories and templates.
I have tested these changes in Windows High Contrast mode.
If my change impacts documentation, I have updated the documentation accordingly.
✨ This pull request is ready to merge. ✨

changeset-bot · 2024-10-25T20:34:38Z

🦋 Changeset detected

Latest commit: dedd54c

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

This PR includes changesets to release 2 packages

Name	Type
@spectrum-css/checkbox	Patch
@spectrum-css/fieldgroup	Minor

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 · 2024-10-25T20:38:18Z

🚀 Deployed on https://pr-3328--spectrum-css.netlify.app

github-actions · 2024-10-25T20:39:31Z

File metrics

Summary

Total size: 4.26 MB^*
Total change (Δ): 🟢 ⬇ 2.79 KB (-0.06%)

Table reports on changes to a package's main file. Other changes can be found in the collapsed Details section below.

Package	Size	Δ
checkbox	23.57 KB	🟢 ⬇ 0.64 KB
fieldgroup	1.37 KB	🟢 ⬇ 0.31 KB

Details

checkbox

Filename	Head	Compared to base
index-base.css	22.95 KB	🟢 ⬇ 0.64 KB (-2.67%)
index-theme.css	1.24 KB	-
index-vars.css	23.57 KB	🟢 ⬇ 0.64 KB (-2.60%)
index.css	23.57 KB	🟢 ⬇ 0.64 KB (-2.60%)
themes/express.css	0.95 KB	-
themes/spectrum.css	0.94 KB	-

fieldgroup

Filename	Head	Compared to base
index-base.css	1.37 KB	🟢 ⬇ 0.31 KB (-17.98%)
index-vars.css	1.37 KB	🟢 ⬇ 0.31 KB (-17.98%)
index.css	1.37 KB	🟢 ⬇ 0.31 KB (-17.98%)

* Size determined by adding together the size of the main file for all packages in the library.
* Results are not gzipped or minified.
* An ASCII character in UTF-8 is 8 bits or 1 byte.

marissahuysentruyt

Love this- the read-only checkboxes are focusable, but cannot be checked/unchecked. 👍 I love that you added a bunch of the documentation from the guidelines site- thank you!

I did have a question about the expectations for what would be announced by a screenreader in read-only cases. Maybe that's something that's part of the research on read-only that's coming up. When using voice over, a read-only checkbox is announced like any of the other non-disabled checkboxes, so how would a user know that they cannot change the selection? I would think this would probably be a bigger discussion involving all of our team and some accessibility folks, so I'm not going to let it block my approval right now. Just wondered if you had any knowledge I don't!

components/checkbox/stories/checkbox.stories.js

components/fieldgroup/stories/fieldgroup.stories.js

I reviewed too early before the PR was ready.

jawinn · 2024-10-29T18:06:35Z

When using voice over, a read-only checkbox is announced like any of the other non-disabled checkboxes, so how would a user know that they cannot change the selection?

Good call-out. VoiceOver reads it the same way that you had heard, for React Spectrum's version that uses aria-readonly. I've updated this to use aria-disabled, which now announces it as "dimmed" and does not announce the keyboard shortcut to check/uncheck. See the updated PR notes about that.

components/fieldgroup/stories/template.js

marissahuysentruyt

I think this is looking good. The read-only behavior works as you described, VoiceOver is announcing the read-only checkboxes in a way that is distinct from other editable checkboxes, and field group no longer has those commas! Just a few things from me!

love all of the new tests you added
thanks for going so deep into the aria-labelled / aria-readonly / aria-disabled attributes. I might ping you for resources so I can keep those straight and know when to use them.

components/checkbox/stories/template.js

marissahuysentruyt · 2024-11-05T21:25:43Z

components/checkbox/stories/template.js

@@ -62,13 +62,19 @@ export const Template = ({
 				type="checkbox"
 				class="${rootClass}-input"
 				aria-labelledby=${ifDefined(ariaLabelledby)}
+				aria-disabled=${ifDefined(isReadOnly ? "true" : undefined)}


I can look it up on MDN, but I wonder why aria-disabled adds the "dimmed" part of the screen reader announcement, as opposed to just saying something like "read-only." 🤔

marissahuysentruyt · 2024-11-05T21:31:34Z

components/checkbox/stories/template.js

+						e.preventDefault();
+						e.target.checked = !e.target.checked;
+					}
+					if (isDisabled || isReadOnly) return;


Would we ever get to this "or" portion of the code, the || isReadOnly?

The code would run through the first if(isReadOnly), and if it's also disabled, it'll return anyways, but I guess my question is do we need the "or read only" in this if(isDisabled || isReadOnly) block. Could it run through both if blocks, if a read-only checkbox isn't disabled? Should the return just go in the if(isReadOnly) block?

Yes, since readonly is not disabled. This is as intended. If readonly, it keeps checked from changing on click. Then it returns if it's disabled or readonly, and only runs updateArgs to changed the isChecked control value for checkboxes that aren't disabled or readonly.

components/checkbox/stories/checkbox.test.js

pfulton · 2024-11-11T19:15:48Z

@jawinn Just need you to talk a look at the Chromatic changes here. Once those are good to go, we can merge!

This removes some unnecessary read-only styles. Read-only just needs to override disabled styles; otherwise it uses default styles (for both default and emphasized). Also adjusts template to include aria-disabled when in the read-only state, so screen readers such as VoiceOver do not announce the input as normal. Note that aria-readonly is not used as it is not announced property and MDN states that it is "not relevant" for input with type checkbox.

The previous display of the read-only state, without checkboxes and displaying commas did not match up with any guidelines. This update is to make the display of read-only match with what is implemented in React Spectrum. It also includes aria-labeledby in the template so the group is announced by screen readers.

marissahuysentruyt previously approved these changes Oct 28, 2024

View reviewed changes

components/checkbox/stories/checkbox.stories.js Show resolved Hide resolved

components/fieldgroup/stories/fieldgroup.stories.js Show resolved Hide resolved

components/fieldgroup/stories/fieldgroup.stories.js Show resolved Hide resolved

jawinn marked this pull request as draft October 28, 2024 15:47

marissahuysentruyt requested review from marissahuysentruyt and removed request for marissahuysentruyt October 28, 2024 19:41

jawinn force-pushed the jawinn/css-1004-checkbox-readonly-refactor branch from 32a1113 to c2cac21 Compare October 29, 2024 17:49

jawinn force-pushed the jawinn/css-1004-checkbox-readonly-refactor branch 2 times, most recently from f1def57 to 67057d1 Compare October 29, 2024 18:30

jawinn marked this pull request as ready for review October 29, 2024 18:34

jawinn added the ready-for-review label Oct 29, 2024

jawinn requested review from marissahuysentruyt and 5t3ph October 29, 2024 18:35

5t3ph mentioned this pull request Oct 29, 2024

fix(radio): correct display of read-only state #3350

Merged

16 tasks

5t3ph reviewed Oct 29, 2024

View reviewed changes

components/fieldgroup/stories/template.js Show resolved Hide resolved

jawinn added the s1 label Oct 30, 2024

marissahuysentruyt approved these changes Nov 5, 2024

View reviewed changes

jawinn force-pushed the jawinn/css-1004-checkbox-readonly-refactor branch from 67057d1 to 7d0aa56 Compare November 8, 2024 14:56

jawinn requested a review from 5t3ph November 8, 2024 16:21

5t3ph approved these changes Nov 11, 2024

View reviewed changes

pfulton force-pushed the jawinn/css-1004-checkbox-readonly-refactor branch from 372e49f to a255a12 Compare November 11, 2024 18:49

pfulton added the run_vrt For use on PRs looking to kick off VRT label Nov 11, 2024

jawinn added 4 commits November 12, 2024 10:32

docs(checkbox): add additional tests for combination of some states

5c50f08

docs(fieldgroup): display a checked option in readonly fieldgroup

bcaeddf

chore(checkbox): fix stylelint max-nesting-depth warning

dedd54c

jawinn force-pushed the jawinn/css-1004-checkbox-readonly-refactor branch from a255a12 to dedd54c Compare November 12, 2024 15:33

jawinn merged commit a0486b3 into main Nov 12, 2024
14 checks passed

jawinn deleted the jawinn/css-1004-checkbox-readonly-refactor branch November 12, 2024 15:50

This was referenced Nov 12, 2024

chore: release #3389

Merged

chore: release (s2-foundations) #3391

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix: correct the display of checkbox read-only state #3328

fix: correct the display of checkbox read-only state #3328

jawinn commented Oct 25, 2024 •

edited

Loading

changeset-bot bot commented Oct 25, 2024 •

edited

Loading

github-actions bot commented Oct 25, 2024 •

edited

Loading

github-actions bot commented Oct 25, 2024 •

edited

Loading

checkbox

fieldgroup

marissahuysentruyt left a comment

jawinn commented Oct 29, 2024 •

edited

Loading

marissahuysentruyt left a comment

marissahuysentruyt Nov 5, 2024

marissahuysentruyt Nov 5, 2024

jawinn Nov 7, 2024 •

edited

Loading

pfulton commented Nov 11, 2024

fix: correct the display of checkbox read-only state #3328

fix: correct the display of checkbox read-only state #3328

Conversation

jawinn commented Oct 25, 2024 • edited Loading

Description

How and where has this been tested?

Validation steps

Regression testing

Screenshots

To-do list

changeset-bot bot commented Oct 25, 2024 • edited Loading

🦋 Changeset detected

github-actions bot commented Oct 25, 2024 • edited Loading

github-actions bot commented Oct 25, 2024 • edited Loading

File metrics

Summary

checkbox

fieldgroup

marissahuysentruyt left a comment

Choose a reason for hiding this comment

jawinn commented Oct 29, 2024 • edited Loading

marissahuysentruyt left a comment

Choose a reason for hiding this comment

marissahuysentruyt Nov 5, 2024

Choose a reason for hiding this comment

marissahuysentruyt Nov 5, 2024

Choose a reason for hiding this comment

jawinn Nov 7, 2024 • edited Loading

Choose a reason for hiding this comment

pfulton commented Nov 11, 2024

jawinn commented Oct 25, 2024 •

edited

Loading

changeset-bot bot commented Oct 25, 2024 •

edited

Loading

github-actions bot commented Oct 25, 2024 •

edited

Loading

github-actions bot commented Oct 25, 2024 •

edited

Loading

jawinn commented Oct 29, 2024 •

edited

Loading

jawinn Nov 7, 2024 •

edited

Loading