chore(checkbox): update docs and stories to align checkbox help text handling w/other components

Author: cdransf

.circleci/config.yml

@@ -22,7 +22,7 @@ parameters:
     # 3. Commit this change to the PR branch where the changes exist.
     current_golden_images_hash:
         type: string
-        default: 53d43cef8f05a527cd662707fd6a7a8e930a6a52
+        default: 618dd949972712d04808ff96e90ba6127e3dffbc
 
     wireit_cache_name:
         type: string

1st-gen/packages/checkbox/README.md

@@ -108,9 +108,14 @@ focus to the content.
 
     <div style="display: flex; flex-direction: column;">
         <h4 class="spectrum-Heading--subtitle1">Invalid</h4>
-        <sp-checkbox invalid>Web component</sp-checkbox>
-        <sp-checkbox checked invalid>Web component</sp-checkbox>
-        <sp-checkbox indeterminate invalid>Web component</sp-checkbox>
+        <sp-field-group vertical label="Select an option" invalid>
+            <sp-checkbox invalid>Web component</sp-checkbox>
+            <sp-checkbox checked invalid>Web component</sp-checkbox>
+            <sp-checkbox indeterminate invalid>Web component</sp-checkbox>
+            <sp-help-text slot="negative-help-text" icon>
+                This selection is invalid.
+            </sp-help-text>
+        </sp-field-group>
     </div>
 
     <div style="display: flex; flex-direction: column;">
@@ -141,11 +146,16 @@ of assets, etc. where the checkboxes need to be noticed.
 
     <div style="display: flex; flex-direction: column;">
         <h4 class="spectrum-Heading--subtitle1">Invalid</h4>
-        <sp-checkbox emphasized invalid>Web component</sp-checkbox>
-        <sp-checkbox emphasized checked invalid>Web component</sp-checkbox>
-        <sp-checkbox emphasized indeterminate invalid>
-            Web component
-        </sp-checkbox>
+        <sp-field-group vertical label="Select an option" invalid>
+            <sp-checkbox emphasized invalid>Web component</sp-checkbox>
+            <sp-checkbox emphasized checked invalid>Web component</sp-checkbox>
+            <sp-checkbox emphasized indeterminate invalid>
+                Web component
+            </sp-checkbox>
+            <sp-help-text slot="negative-help-text" icon>
+                This selection is invalid.
+            </sp-help-text>
+        </sp-field-group>
     </div>
 
     <div style="display: flex; flex-direction: column;">
@@ -168,8 +178,15 @@ of assets, etc. where the checkboxes need to be noticed.
 
 The `invalid` attribute indicates that the checkbox's value is invalid. When set, appropriate ARIA attributes will be automatically applied.
 
+When a checkbox is in an invalid state, provide help text to explain the error and guide the user toward a solution. Wrap the checkbox in an `<sp-field-group>` to associate the help text with the checkbox. (See [help text](#help-text) for more information.)
+
 ```html
-<sp-checkbox invalid>Invalid</sp-checkbox>
+<sp-field-group vertical label="Terms and conditions" invalid>
+    <sp-checkbox invalid>I accept the terms and conditions</sp-checkbox>
+    <sp-help-text slot="negative-help-text" icon>
+        You must accept the terms to continue.
+    </sp-help-text>
+</sp-field-group>
 ```
 
 #### Disabled
@@ -196,6 +213,86 @@ Checkboxes have a `readonly` attribute for when they’re in the disabled state
 <sp-checkbox readonly>Read-only</sp-checkbox>
 ```
 
+### Help text
+
+Help text can be accessibly associated with checkboxes by using the `help-text` or `negative-help-text` slots on an `<sp-field-group>` element. When using the `negative-help-text` slot, `<sp-field-group>` will self manage the presence of this content based on the value of the `invalid` property on your `<sp-field-group>` element. Content within the `help-text` slot will be shown by default. When your `<sp-field-group>` should receive help text based on state outside of the complexity of `invalid` or not, manage the content addressed to the `help-text` from above to ensure that it displays the right messaging and possesses the right `variant`.
+
+Read more about using [help text](../help-text).
+
+<sp-tabs selected="self" auto label="Help text usage with checkboxes">
+<sp-tab value="self">Self managed</sp-tab>
+<sp-tab-panel value="self">
+
+```html
+<sp-field-group
+    vertical
+    id="self"
+    label="Notification preferences"
+    onchange="
+        const checkboxes = this.querySelectorAll('sp-checkbox');
+        const noneChecked = ![...checkboxes].some(cb => cb.checked);
+        this.invalid = noneChecked;
+    "
+>
+    <sp-checkbox value="email">Email notifications</sp-checkbox>
+    <sp-checkbox value="sms">SMS notifications</sp-checkbox>
+    <sp-checkbox value="push" checked>Push notifications</sp-checkbox>
+    <sp-help-text slot="help-text">
+        Choose how you'd like to be notified.
+    </sp-help-text>
+    <sp-help-text slot="negative-help-text" icon>
+        Select at least one notification method.
+    </sp-help-text>
+</sp-field-group>
+```
+
+</sp-tab-panel>
+<sp-tab value="above">Managed from above</sp-tab>
+<sp-tab-panel value="above">
+
+```html
+<sp-field-label for="above">Notification preferences</sp-field-label>
+<sp-field-group
+    vertical
+    id="above"
+    onchange="
+        const checkboxes = this.querySelectorAll('sp-checkbox');
+        const noneChecked = ![...checkboxes].some(cb => cb.checked);
+        const helpText = this.querySelector(`[slot='help-text']`);
+        helpText.icon = noneChecked;
+        helpText.textContent = noneChecked ? 'Select at least one notification method.' : 'Choose how you\'d like to be notified.';
+        helpText.variant = noneChecked ? 'negative' : 'neutral';
+    "
+>
+    <sp-checkbox value="email">Email notifications</sp-checkbox>
+    <sp-checkbox value="sms">SMS notifications</sp-checkbox>
+    <sp-checkbox value="push" checked>Push notifications</sp-checkbox>
+    <sp-help-text slot="help-text">
+        Choose how you'd like to be notified.
+    </sp-help-text>
+</sp-field-group>
+```
+
+</sp-tab-panel>
+<sp-tab value="single">Single checkbox</sp-tab>
+<sp-tab-panel value="single">
+
+When a single checkbox requires validation, wrap it in an `<sp-field-group>` to associate help text:
+
+```html
+<sp-field-group vertical label="Agreement" invalid>
+    <sp-checkbox invalid>
+        I have read and accept the terms of service
+    </sp-checkbox>
+    <sp-help-text slot="negative-help-text" icon>
+        You must accept the terms of service to continue.
+    </sp-help-text>
+</sp-field-group>
+```
+
+</sp-tab-panel>
+</sp-tabs>
+
 ### Behaviors
 
 #### Handling events
@@ -236,6 +333,14 @@ Sets of checkboxes should always have a clear label that describes what the list
 </sp-field-group>
 ```
 
+#### Provide help text in the correct location
+
+Checkbox groups should use help text for error messaging and descriptions. Descriptions are valuable for giving context about a selection or for clarifying the options.
+
+It is [not currently possible](https://w3c.github.io/webcomponents-cg/#cross-root-aria) to provide accessible ARIA references between elements in different shadow roots. To ensure proper association between elements, help text must be included via the `slot="help-text"` or `slot="negative-help-text"` on the parent `<sp-field-group>`.
+
+See [help text](../help-text) for more information.
+
 #### Keyboard Navigation
 
 Checkboxes can be toggled using the <kbd>Space</kbd> key when focused. They follow the standard tab order of the page.

1st-gen/packages/checkbox/stories/checkbox.stories.ts

@@ -11,7 +11,9 @@
  */
 import '@spectrum-web-components/checkbox/sp-checkbox.js';
 import '@spectrum-web-components/field-group/sp-field-group.js';
+import '@spectrum-web-components/help-text/sp-help-text.js';
 import { html, TemplateResult } from '@spectrum-web-components/base';
+import type { Checkbox } from '@spectrum-web-components/checkbox';
 
 export default {
     component: 'sp-checkbox',
@@ -167,3 +169,56 @@ export const verticalTabIndexExample = (): TemplateResult => {
         </sp-field-group>
     `;
 };
+
+export const invalidWithHelpText = (): TemplateResult => {
+    return html`
+        <sp-field-group vertical label="Required selections" invalid>
+            <sp-checkbox invalid>Option A</sp-checkbox>
+            <sp-checkbox invalid>Option B</sp-checkbox>
+            <sp-checkbox invalid>Option C</sp-checkbox>
+            <sp-help-text slot="negative-help-text" icon>
+                Select at least one option to continue.
+            </sp-help-text>
+        </sp-field-group>
+    `;
+};
+
+export const invalidSingleCheckboxWithHelpText = (): TemplateResult => {
+    return html`
+        <sp-field-group vertical label="Agreement" invalid>
+            <sp-checkbox invalid>
+                I have read and accept the terms of service
+            </sp-checkbox>
+            <sp-help-text slot="negative-help-text" icon>
+                You must accept the terms of service to continue.
+            </sp-help-text>
+        </sp-field-group>
+    `;
+};
+
+export const helpTextSelfManaged = (): TemplateResult => {
+    return html`
+        <sp-field-group
+            vertical
+            label="Notification preferences"
+            @change=${(event: Event) => {
+                const fieldGroup = event.currentTarget as HTMLElement;
+                const checkboxes = fieldGroup.querySelectorAll('sp-checkbox');
+                const noneChecked = ![...checkboxes].some(
+                    (cb) => (cb as Checkbox).checked
+                );
+                fieldGroup.toggleAttribute('invalid', noneChecked);
+            }}
+        >
+            <sp-checkbox value="email">Email notifications</sp-checkbox>
+            <sp-checkbox value="sms">SMS notifications</sp-checkbox>
+            <sp-checkbox value="push" checked>Push notifications</sp-checkbox>
+            <sp-help-text slot="help-text">
+                Choose how you'd like to be notified.
+            </sp-help-text>
+            <sp-help-text slot="negative-help-text" icon>
+                Select at least one notification method.
+            </sp-help-text>
+        </sp-field-group>
+    `;
+};

1st-gen/packages/field-group/README.md

@@ -121,6 +121,23 @@ Help text can be accessibly associated with an `<sp-field-group>` element by usi
 </sp-field-group>
 ```
 
+### States
+
+#### Invalid
+
+When a group of checkboxes fails validation, use the `invalid` attribute on the field group along with `negative-help-text` to explain the error. Set the `invalid` attribute on individual checkboxes as well to apply the appropriate visual styling.
+
+```html
+<sp-field-group vertical label="Required selections" invalid>
+    <sp-checkbox invalid>Option A</sp-checkbox>
+    <sp-checkbox invalid>Option B</sp-checkbox>
+    <sp-checkbox invalid>Option C</sp-checkbox>
+    <sp-help-text slot="negative-help-text" icon>
+        Select at least one option to continue.
+    </sp-help-text>
+</sp-field-group>
+```
+
 ### Accessibility
 
 #### Include a label
@@ -131,9 +148,9 @@ Every field group should have a label. A field without a label is ambiguous and
 
 The description in the help text is flexible and encompasses a range of guidance. Sometimes this guidance is about what to input, and sometime it’s about how to input. This includes information such as:
 
--   An overall description of the input field
--   Hints for what kind of information needs to be input
--   Specific formatting examples or requirements
+- An overall description of the input field
+- Hints for what kind of information needs to be input
+- Specific formatting examples or requirements
 
 Learn more about [using help text](https://spectrum.adobe.com/page/text-field/#Use-help-text-to-show-hints,-formatting,-and-requirements).
 

1st-gen/packages/field-group/stories/field-group.stories.ts

@@ -15,6 +15,7 @@ import { html, TemplateResult } from '@spectrum-web-components/base';
 import '@spectrum-web-components/field-group/sp-field-group.js';
 import '@spectrum-web-components/checkbox/sp-checkbox.js';
 import '@spectrum-web-components/radio/sp-radio.js';
+import '@spectrum-web-components/help-text/sp-help-text.js';
 
 export default {
     title: 'Field Group',
@@ -44,3 +45,16 @@ export const vertical = (): TemplateResult => {
         </sp-field-group>
     `;
 };
+
+export const invalid = (): TemplateResult => {
+    return html`
+        <sp-field-group vertical label="Required selections" invalid>
+            <sp-checkbox invalid>Option A</sp-checkbox>
+            <sp-checkbox invalid>Option B</sp-checkbox>
+            <sp-checkbox invalid>Option C</sp-checkbox>
+            <sp-help-text slot="negative-help-text" icon>
+                Select at least one option to continue.
+            </sp-help-text>
+        </sp-field-group>
+    `;
+};