@brightspace-ui/core 3.121.0 → 3.122.0

package/components/inputs/README.md

@@ -2,11 +2,11 @@
 
 There are various input components available:
 
-- [Checkboxes (input-checkbox*)](docs/input-checkbox.md)
+- [Checkbox Input (input-checkbox*)](docs/input-checkbox.md)
 - [Color Input (input-color)](docs/input-color.md)
 - [Date & Time Inputs (input-date, input-time, input-date-time)](docs/input-date-time.md)
 - [Numeric Inputs (input-number, input-percent)](docs/input-numeric.md)
-- [Radio Buttons (input-radio-*)](docs/input-radio.md)
+- [Radio Inputs (input-radio-*)](docs/input-radio.md)
 - [Search (input-search)](docs/input-search.md)
 - [Select Lists (input-select-styles)](docs/input-select-styles.md)
 - [Text (input-text, input-styles, input-textarea)](docs/input-text.md)

package/components/inputs/docs/input-checkbox.md

@@ -1,51 +1,78 @@
-# Checkboxes
+# Checkbox Input
 
-Checkboxes are used in forms to toggle an option or preference.
+Checkboxes are used in forms to toggle an option or preference. They may be grouped to form a set of options.
 
-<!-- docs: demo -->
+<!-- docs: demo display:block -->
 ```html
 <script type="module">
   import '@brightspace-ui/core/components/inputs/input-checkbox.js';
+  import '@brightspace-ui/core/components/inputs/input-checkbox-group.js';
 </script>
-<d2l-input-checkbox label="Label for checkbox" checked></d2l-input-checkbox>
+<d2l-input-checkbox-group label="Toppings">
+  <d2l-input-checkbox label="Ketchup" checked></d2l-input-checkbox>
+  <d2l-input-checkbox label="Mustard"></d2l-input-checkbox>
+  <d2l-input-checkbox label="Relish"></d2l-input-checkbox>
+</d2l-input-checkbox-group>
 ```
 
 ## Best Practices
 <!-- docs: start best practices -->
 <!-- docs: start dos -->
-* Use in a form to indicate an option or preference.
+* Use in a form to indicate an option or preference
 * Use to allow the user to select multiple, independent options from a set
+* When multiple options are presented together, [wrap them in a group](#d2l-input-checkbox-group)
 * Use an indeterminate state to indicate a mixed state where some child items are checked and some are not
-* Use as progressive disclosure in forms, so long as users are made aware both visually and non-visually that new options have been made available.
+* Use as progressive disclosure in forms, so long as users are made aware both visually and non-visually that new options have been made available
 <!-- docs: end dos -->
 
 <!-- docs: start donts -->
-* Don't use as a toggle that performs an immediate action, use a Switch component.
-* Don't use for mutually exclusive options, use radio buttons.
+* Don't use as a toggle that performs an immediate action, use a Switch component
+* Don't use for mutually exclusive options, use radio input groups
 * Don't use labels as “instructions” or “phrases”. Good label: “Visible to Students”. Bad label: (“Check this to make it visible to students”)
 * Don't use labels to describe the default or “off” state of the option. As much as possible, use the label to refer to the “on” state. Good label: “Visible”. Bad label: “Hidden”.
 <!-- docs: end donts -->
 <!-- docs: end best practices -->
 
+## Checkbox Input Group [d2l-input-checkbox-group]
+
+When multiple checkboxes are displayed together, wrap them in a `<d2l-input-checkbox-group>`.
+
+This will not only provide consistent spacing between checkboxes, but the group also internally renders a `<fieldset>` and `<legend>` with the provided `label`, which gives additional accessibility context. The label can be hidden visually if desired.
+
+<!-- docs: demo code properties name:d2l-input-checkbox-group sandboxTitle:'Checkbox Group' display:block -->
+```html
+<script type="module">
+  import '@brightspace-ui/core/components/inputs/input-checkbox.js';
+  import '@brightspace-ui/core/components/inputs/input-checkbox-group.js';
+</script>
+<d2l-input-checkbox-group label="Toppings">
+  <d2l-input-checkbox label="Ketchup"></d2l-input-checkbox>
+  <d2l-input-checkbox label="Mustard"></d2l-input-checkbox>
+  <d2l-input-checkbox label="Relish"></d2l-input-checkbox>
+</d2l-input-checkbox-group>
+```
+
+<!-- docs: start hidden content -->
+### Properties
+
+| Property | Type | Description |
+|---|---|---|
+| `label` | String, required | Label for the group of checkboxes |
+| `label-hidden` | Boolean | Hides the label visually |
+<!-- docs: end hidden content -->
+
 ## Checkbox Input [d2l-input-checkbox]
 
-The `<d2l-input-checkbox>` element can be used to get a checkbox and optional visible label.
+The `<d2l-input-checkbox>` element can be used on its own or as an option within a `<d2l-input-checkbox-group>` collection. It will display a checkbox and optional visible label.
+
+When provided with a `name`, the checkbox will participate in forms if it is `checked` and enabled.
 
 <!-- docs: demo code properties name:d2l-input-checkbox sandboxTitle:'Checkbox Input' display:block -->
 ```html
 <script type="module">
   import '@brightspace-ui/core/components/inputs/input-checkbox.js';
-
-  window.addEventListener('load', () => {
-    document.querySelector('d2l-input-checkbox')
-      .addEventListener('change', e => {
-        console.log('checked value: ', e.target.checked);
-      });
-  });
 </script>
-<div>
-  <d2l-input-checkbox label="Label for checkbox"></d2l-input-checkbox>
-</div>
+<d2l-input-checkbox label="Label for checkbox"></d2l-input-checkbox>
 ```
 
 <!-- docs: start hidden content -->
@@ -59,7 +86,7 @@ The `<d2l-input-checkbox>` element can be used to get a checkbox and optional vi
 | `indeterminate` | Boolean | Sets checkbox to an indeterminate state |
 | `label` | String, required | Label for the input |
 | `label-hidden` | Boolean | Hides the label visually (moves it to the input's `aria-label` attribute) |
-| `name` | String | Name of the input |
+| `name` | String | Name of the form control. Submitted with the form as part of a name/value pair. |
 | `not-tabbable` | Boolean | Sets `tabindex="-1"` on the checkbox. Note that an alternative method of focusing is necessary to implement if using this property. |
 | `value` | String | Value of the input |
 
@@ -79,49 +106,6 @@ checkbox.addEventListener('change', e => {
 * `supporting`: Supporting information which will appear below and be aligned with the checkbox.
 <!-- docs: end hidden content -->
 
-### Groups of Checkboxes
-
-If multiple checkboxes are displayed together, wrapping them in a `<d2l-input-checkbox-group>` provides consistent spacing between each checkbox.
-
-<!-- docs: demo code -->
-```html
-<script type="module">
-  import '@brightspace-ui/core/components/inputs/input-checkbox.js';
-  import '@brightspace-ui/core/components/inputs/input-checkbox-group.js';
-</script>
-<d2l-input-checkbox-group label="Toppings">
-  <d2l-input-checkbox label="Ketchup"></d2l-input-checkbox>
-  <d2l-input-checkbox label="Mustard"></d2l-input-checkbox>
-  <d2l-input-checkbox label="Relish"></d2l-input-checkbox>
-</d2l-input-checkbox-group>
-```
-
-## Applying styles to native checkboxes
-
-As an alternative to using the `<d2l-input-checkbox>` custom element, you can style a native checkbox inside your own element. Import `input-checkbox-styles.js` and apply the `d2l-input-checkbox` CSS class to the input:
-
-<!-- docs: demo code display:block -->
-```html
-<script type="module">
-  import { html, LitElement } from 'lit';
-  import { checkboxStyles } from '@brightspace-ui/core/components/inputs/input-checkbox.js';
-
-  class MyCheckboxElem extends LitElement {
-
-    static get styles() {
-      return checkboxStyles;
-    }
-
-    render() {
-      return html`<input type="checkbox" class="d2l-input-checkbox">`;
-    }
-
-  }
-  customElements.define('d2l-my-checkbox-elem', MyCheckboxElem);
-</script>
-<d2l-my-checkbox-elem></d2l-my-checkbox-elem>
-```
-
 ## Accessibility
 
 The `d2l-input-checkbox` component follows W3C's best practice recommendations for a [checkbox](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/). This means that the component works in the following way:

package/components/inputs/docs/input-radio.md

@@ -1,6 +1,6 @@
-# Radio Buttons
+# Radio Inputs
 
-Radio Buttons are used in forms to offer a single choice among mutually exclusive options.
+Radio inputs are used in forms to offer a single choice among mutually exclusive options.
 
 <!-- docs: demo display:block -->
 ```html
@@ -15,11 +15,6 @@ Radio Buttons are used in forms to offer a single choice among mutually exclusiv
 </d2l-input-radio-group>
 ```
 
-Unlike checkboxes, individual radio buttons cannot be placed in a custom element. Items belonging to a radio group cannot span across different shadow roots -- all radios in the same group must be in the same shadow root.
-
-As a result, we have to apply styles to native radio inputs.
-
-
 ## Best Practices
 <!-- docs: start best practices -->
 <!-- docs: start dos -->
@@ -28,127 +23,87 @@ As a result, we have to apply styles to native radio inputs.
 <!-- docs: end dos -->
 
 <!-- docs: start donts -->
-* Don’t use two radio buttons if a single checkbox works better
-* Don’t use for triggering an immediate action. Notable exceptions are forms that autosave with clear indication and as a trigger for progressive disclosure on traditional forms, so long as users are made aware that new options have been made available
+* Don’t use two radio inputs if a single checkbox works better
+* Don’t use for triggering an immediate action. Notable exceptions are forms that autosave with clear indication and as a trigger for progressive disclosure on traditional forms, so long as users are made aware that new options have been made available.
 <!-- docs: end donts -->
 <!-- docs: end best practices -->
 
-## Radio Inputs With Labels
+## Radio Input Group [d2l-input-radio-group]
 
-The simplest way to apply radio styles is to use the `d2l-input-radio-label` CSS class on a `<label>` element that wraps the input.
+The group is a required parent of `<d2l-input-radio>`. It internally renders a `<fieldset>` and `<legend>` with the provided `label`, which gives additional accessibility context. The label can be hidden visually if desired.
 
-For disabled items, add the `d2l-input-radio-label-disabled` class on the label and the `disabled` attribute on the input itself.
+When provided with a `name`, the group will participate in forms with the `value` of the currently checked input.
 
-<!-- docs: demo code display:block -->
+<!-- docs: demo code properties name:d2l-input-radio-group sandboxTitle:'Checkbox Group' display:block -->
 ```html
 <script type="module">
-  import { html, LitElement } from 'lit';
-  import { radioStyles } from '@brightspace-ui/core/components/inputs/input-radio-styles.js';
-
-  class MyRadioElem extends LitElement {
-
-    static get styles() {
-      return radioStyles;
-    }
-
-    render() {
-      return html`
-        <label class="d2l-input-radio-label">
-          <input type="radio" name="myGroup" checked>
-          Option 1 (selected)
-        </label>
-        <label class="d2l-input-radio-label d2l-input-radio-label-disabled">
-          <input type="radio" name="myGroup" disabled>
-          Option 2 (disabled)
-        </label>
-        <label class="d2l-input-radio-label">
-          <input type="radio" name="myGroup">
-          Option 3
-        </label>
-      `;
-    }
-
-  }
-  customElements.define('d2l-my-radio-elem', MyRadioElem);
+  import '@brightspace-ui/core/components/inputs/input-radio.js';
+  import '@brightspace-ui/core/components/inputs/input-radio-group.js';
 </script>
-<d2l-my-radio-elem></d2l-my-radio-elem>
+<d2l-input-radio-group label="Bread" name="bread">
+  <d2l-input-radio label="Whole wheat" name="whole-wheat" checked></d2l-input-radio>
+  <d2l-input-radio label="Baguette" name="baguette"></d2l-input-radio>
+  <d2l-input-radio label="Marble Rye" name="marble-rye"></d2l-input-radio>
+</d2l-input-radio-group>
 ```
 
-## Individual Radio Inputs
+<!-- docs: start hidden content -->
+### Properties
 
-If you'd like to manually link the radio input with a label, or use an ARIA label, place the `d2l-radio-input` CSS class on the input itself to style it. For example:
+| Property | Type | Description |
+|---|---|---|
+| `label` | String, required | Label for the group of radio inputs |
+| `label-hidden` | Boolean | Hides the label visually |
+| `name` | String | Name of the form control. Submitted with the form as part of a name/value pair. |
+| `required` | Boolean | Indicates that a value is required |
 
-<!-- docs: demo code properties name:d2l-test-input-radio-solo display:block -->
-```html
-<script type="module">
-  import { html, LitElement } from 'lit';
-  import { radioStyles } from '@brightspace-ui/core/components/inputs/input-radio-styles.js';
-
-  class MyRadioElem extends LitElement {
-
-    static get properties() {
-      return {
-        checked: { type: Boolean },
-        disabled: { type: Boolean },
-        invalid: { type: Boolean }
-      };
-    }
-
-    static get styles() {
-      return radioStyles;
-    }
-
-    render() {
-      const invalid = this.invalid ? 'true' : 'false';
-      return html`
-        <input
-          aria-invalid="${invalid}"
-          aria-label="Option 1"
-          ?checked="${this.checked}"
-          class="d2l-input-radio"
-          ?disabled="${this.disabled}"
-          type="radio">
-      `;
-    }
-
-  }
-  customElements.define('d2l-test-input-radio-solo', MyRadioElem);
-</script>
-<d2l-test-input-radio-solo></d2l-test-input-radio-solo>
+### Events
+
+When the radio group's state changes, it dispatches the `change` event:
+
+```javascript
+checkbox.addEventListener('change', e => {
+  const newValue = e.target.detail.value;
+  const oldValue = e.target.detail.oldValue; // may be undefined
+});
 ```
+<!-- docs: end hidden content -->
 
-## Radio Spacer [d2l-input-radio-spacer]
+## Radio Input [d2l-input-radio]
 
-To align related content below radio buttons, the `d2l-input-radio-spacer` element can be used in conjunction with the `d2l-input-radio-label` class:
+The `<d2l-input-radio>` element represents an option within its parent `<d2l-input-radio-group>`.
 
-<!-- docs: demo code display:block -->
+<!-- docs: demo code properties name:d2l-input-radio sandboxTitle:'Radio Input' display:block -->
 ```html
 <script type="module">
-  import '@brightspace-ui/core/components/inputs/input-radio-spacer.js';
-  import { html, LitElement } from 'lit';
-  import { inlineHelpStyles } from '@brightspace-ui/core/components/inputs/input-inline-help.js';
-  import { radioStyles } from '@brightspace-ui/core/components/inputs/input-radio-styles.js';
-
-  class MyRadioElem extends LitElement {
-
-    static get styles() {
-      return [ radioStyles, inlineHelpStyles ];
-    }
-
-    render() {
-      return html`
-        <label class="d2l-input-radio-label">
-          <input type="radio" aria-describedby="desc1" value="normal" checked>
-          Option 1
-        </label>
-        <d2l-input-radio-spacer id="desc1" class="d2l-input-inline-help">
-          Additional content can go here and will line up nicely with the edge of the radio.
-        </d2l-input-radio-spacer>
-      `;
-    }
-
-  }
-  customElements.define('d2l-my-radio-spacer-elem', MyRadioElem);
+  import '@brightspace-ui/core/components/inputs/input-radio.js';
+  import '@brightspace-ui/core/components/inputs/input-radio-group.js';
 </script>
-<d2l-my-radio-spacer-elem></d2l-my-radio-spacer-elem>
+<d2l-input-radio-group label="Bread" name="bread">
+  <d2l-input-radio label="Whole wheat" name="whole-wheat" checked></d2l-input-radio>
+  <d2l-input-radio label="Baguette" name="baguette"></d2l-input-radio>
+  <d2l-input-radio label="Marble Rye" name="marble-rye"></d2l-input-radio>
+</d2l-input-radio-group>
 ```
+
+<!-- docs: start hidden content -->
+### Properties
+
+| Property | Type | Description |
+|---|---|---|
+| `label` | String, required | Label for the input |
+| `checked` | Boolean | Checked state |
+| `description` | String | Additional information communicated to screenreader users when focusing on the input |
+| `disabled` | Boolean | Disables the input |
+| `supporting-hidden-when-unchecked` | Boolean | Hides the supporting slot when unchecked |
+| `value` | String | Value of the input |
+
+### Slots
+
+* `inline-help`: Help text that will appear below the input. Use this only when other helpful cues are not sufficient, such as a carefully-worded label.
+* `supporting`: Supporting information which will appear below and be aligned with the input.
+<!-- docs: end hidden content -->
+
+## Accessibility
+
+The `d2l-input-radio-group` and `d2l-input-radio` components follow W3C's best practice recommendations for a [radio group](https://www.w3.org/WAI/ARIA/apg/patterns/radio/).

package/components/inputs/docs/styling-native-inputs.md

@@ -0,0 +1,153 @@
+# Styling Native Inputs
+
+In the majority of cases, it's recommended to use our web component wrappers around native inputs like text, textarea, checkboxes and radios. They'll provide functionality like inline help, skeletons, form participation, and localized validation out-of-the-box.
+
+In the rare circumstance where a native HTML input is preferred, it is possible to apply styles such that they appear similar to our web component variants.
+
+## Checkbox Input
+
+Import `input-checkbox-styles.js` and apply the `d2l-input-checkbox` CSS class to the input:
+
+<!-- docs: demo code display:block -->
+```html
+<script type="module">
+  import { html, LitElement } from 'lit';
+  import { checkboxStyles } from '@brightspace-ui/core/components/inputs/input-checkbox.js';
+
+  class MyCheckboxElem extends LitElement {
+
+    static get styles() {
+      return checkboxStyles;
+    }
+
+    render() {
+      return html`<input type="checkbox" class="d2l-input-checkbox">`;
+    }
+
+  }
+  customElements.define('d2l-my-checkbox-elem', MyCheckboxElem);
+</script>
+<d2l-my-checkbox-elem></d2l-my-checkbox-elem>
+```
+
+## Radio Inputs
+
+### With Labels
+
+The simplest way to apply radio styles is to use the `d2l-input-radio-label` CSS class on a `<label>` element that wraps the input.
+
+For disabled items, add the `d2l-input-radio-label-disabled` class on the label and the `disabled` attribute on the input itself.
+
+<!-- docs: demo code display:block -->
+```html
+<script type="module">
+  import { html, LitElement } from 'lit';
+  import { radioStyles } from '@brightspace-ui/core/components/inputs/input-radio-styles.js';
+
+  class MyRadioElem extends LitElement {
+
+    static get styles() {
+      return radioStyles;
+    }
+
+    render() {
+      return html`
+        <label class="d2l-input-radio-label">
+          <input type="radio" name="myGroup" checked>
+          Option 1 (selected)
+        </label>
+        <label class="d2l-input-radio-label d2l-input-radio-label-disabled">
+          <input type="radio" name="myGroup" disabled>
+          Option 2 (disabled)
+        </label>
+        <label class="d2l-input-radio-label">
+          <input type="radio" name="myGroup">
+          Option 3
+        </label>
+      `;
+    }
+
+  }
+  customElements.define('d2l-my-radio-elem', MyRadioElem);
+</script>
+<d2l-my-radio-elem></d2l-my-radio-elem>
+```
+
+### Individual Radio Inputs
+
+If you'd like to manually link the radio input with a label, or use an ARIA label, place the `d2l-radio-input` CSS class on the input itself to style it. For example:
+
+<!-- docs: demo code properties name:d2l-test-input-radio-solo display:block -->
+```html
+<script type="module">
+  import { html, LitElement } from 'lit';
+  import { radioStyles } from '@brightspace-ui/core/components/inputs/input-radio-styles.js';
+
+  class MyRadioElem extends LitElement {
+
+    static get properties() {
+      return {
+        checked: { type: Boolean },
+        disabled: { type: Boolean },
+        invalid: { type: Boolean }
+      };
+    }
+
+    static get styles() {
+      return radioStyles;
+    }
+
+    render() {
+      const invalid = this.invalid ? 'true' : 'false';
+      return html`
+        <input
+          aria-invalid="${invalid}"
+          aria-label="Option 1"
+          ?checked="${this.checked}"
+          class="d2l-input-radio"
+          ?disabled="${this.disabled}"
+          type="radio">
+      `;
+    }
+
+  }
+  customElements.define('d2l-test-input-radio-solo', MyRadioElem);
+</script>
+<d2l-test-input-radio-solo></d2l-test-input-radio-solo>
+```
+
+### Radio Spacer [d2l-input-radio-spacer]
+
+To align related content below radio buttons, the `d2l-input-radio-spacer` element can be used in conjunction with the `d2l-input-radio-label` class:
+
+<!-- docs: demo code display:block -->
+```html
+<script type="module">
+  import '@brightspace-ui/core/components/inputs/input-radio-spacer.js';
+  import { html, LitElement } from 'lit';
+  import { inlineHelpStyles } from '@brightspace-ui/core/components/inputs/input-inline-help.js';
+  import { radioStyles } from '@brightspace-ui/core/components/inputs/input-radio-styles.js';
+
+  class MyRadioElem extends LitElement {
+
+    static get styles() {
+      return [ radioStyles, inlineHelpStyles ];
+    }
+
+    render() {
+      return html`
+        <label class="d2l-input-radio-label">
+          <input type="radio" aria-describedby="desc1" value="normal" checked>
+          Option 1
+        </label>
+        <d2l-input-radio-spacer id="desc1" class="d2l-input-inline-help">
+          Additional content can go here and will line up nicely with the edge of the radio.
+        </d2l-input-radio-spacer>
+      `;
+    }
+
+  }
+  customElements.define('d2l-my-radio-spacer-elem', MyRadioElem);
+</script>
+<d2l-my-radio-spacer-elem></d2l-my-radio-spacer-elem>
+```

package/components/inputs/input-radio-group.js

@@ -16,7 +16,7 @@ class InputRadioGroup extends PropertyRequiredMixin(SkeletonMixin(FormElementMix
 	static get properties() {
 		return {
 			/**
-			 * REQUIRED: Label for the input
+			 * REQUIRED: Label for the group of radio inputs
 			 * @type {string}
 			 */
 			label: { required: true, type: String },

package/custom-elements.json

@@ -6918,7 +6918,7 @@
       "attributes": [
         {
           "name": "label",
-          "description": "REQUIRED: Label for the input",
+          "description": "REQUIRED: Label for the group of radio inputs",
           "type": "string"
         },
         {
@@ -6948,7 +6948,7 @@
         {
           "name": "label",
           "attribute": "label",
-          "description": "REQUIRED: Label for the input",
+          "description": "REQUIRED: Label for the group of radio inputs",
           "type": "string"
         },
         {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brightspace-ui/core",
-  "version": "3.121.0",
+  "version": "3.122.0",
   "description": "A collection of accessible, free, open-source web components for building Brightspace applications",
   "type": "module",
   "repository": "https://github.com/BrightspaceUI/core.git",