@brightspace-ui/core 3.122.0 → 3.123.0

package/components/alert/README.md

@@ -96,14 +96,13 @@ Use a toast alert to provide feedback about an operation the user has just initi
 <!-- docs: start best practices -->
 <!-- docs: start dos -->
 * Use to convey results of a user's action when the result is not otherwise obvious
-* Keep text brief — toasts should rarely spill onto more than one line at any screen size
+* Keep the message brief, especially if adding additional `subtext` since toasts are only displayed for a few seconds
 * Use specific language — “Assignment saved” is more informative than “Successfully saved”
 <!-- docs: end dos -->
 <!-- docs: start donts -->
 * If possible, avoid displaying multiple toasts — see [Multiple Toast Alerts](#multiple-toast-alerts)
 * Don't allow the close button to be blocked by other elements; users shouldn't have to wait for the toast alert to go away on its own
 * Don’t use for instructions or critical information since toast alerts disappear and can be easily missed or ignored — use an [Inline Alert](#d2l-alert) instead
-* Avoid having two lines with `subtext` — toasts should be very brief
 <!-- docs: end donts -->
 <!-- docs: end best practices -->
 

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

@@ -34,6 +34,7 @@ The `<d2l-input-color>` will open a dialog to allow the user to select a color f
 | `disallow-none` | Boolean, default: `false` | Disallows the user from selecting "None" as a color value. |
 | `label` | String, required | Label for the input. Comes with a default value for background & foreground types. |
 | `label-hidden` | Boolean, default: `false` | Hides the label visually. |
+| `name` | String | Name of the form control. Submitted with the form as part of a name/value pair. |
 | `readonly` | Boolean, default: `false` | Puts the input into a read-only state. |
 | `type` | String, default: `custom` | Type of color being chosen. Can be one of: `custom`, `background`, `foreground`. |
 | `value` | Number | Value of the input. |

package/components/inputs/docs/input-date-time.md

@@ -51,6 +51,7 @@ Note: All `*value` properties should be in ISO 8601 calendar date format (`YYYY-
 | `labelled-by` | String | HTML id of an element in the same shadow root which acts as the input's label |
 | `max-value` | String | Maximum valid date that could be selected by a user. |
 | `min-value` | String | Minimum valid date that could be selected by a user. |
+| `name` | String | Name of the form control. Submitted with the form as part of a name/value pair. |
 | `opened` | Boolean | Indicates if the calendar dropdown is open |
 | `required` | Boolean | Indicates that a value is required |
 | `value` | String, default `''` | Value of the input. |
@@ -95,6 +96,7 @@ Note: All `*value` properties should be in ISO 8601 calendar date format (`YYYY-
 | `label-hidden` | Boolean | Hides the fieldset label visually |
 | `max-value` | String | Maximum valid date that could be selected by a user |
 | `min-value` | String |  Minimum valid date that could be selected by a user |
+| `name` | String | Name of the form control. Submitted with the form as part of a name/value pair. |
 | `required` | Boolean | Indicates that values are required |
 | `start-label` | String, default `'Start Date'` | Accessible label for the first date input |
 | `start-opened` | Boolean | Indicates if the start calendar dropdown is open |
@@ -135,6 +137,7 @@ Note: All `*value` properties should be in ISO 8601 time format (`hh:mm:ss`) and
 | `enforce-time-intervals` | Boolean | Rounds up to nearest valid interval time (specified with `time-interval`) when user types a time |
 | `label-hidden` | Boolean | Hides the label visually (moves it to the input's `aria-label` attribute) |
 | `labelled-by` | String | HTML id of an element in the same shadow root which acts as the input's label |
+| `name` | String | Name of the form control. Submitted with the form as part of a name/value pair. |
 | `opened` | Boolean | Indicates if the dropdown is open |
 | `required` | Boolean | Indicates that a value is required |
 | `timezone-hidden` | Boolean | Hides the timezone inside the selection dropdown. Should only be used when the input uses a different timezone than the document's settings |
@@ -180,6 +183,7 @@ Note: All `*value` properties should be in ISO 8601 time format (`hh:mm:ss`) and
 | `enforce-time-intervals` | Boolean | Rounds up to nearest valid interval time (specified with `time-interval`) when user types a time |
 | `inclusive-time-range` | Boolean | Validate on inclusive range (i.e., it is valid for start and end times to be equal) |
 | `label-hidden` | Boolean | Hides the fieldset label visually |
+| `name` | String | Name of the form control. Submitted with the form as part of a name/value pair. |
 | `required` | Boolean | Indicates that values are required |
 | `start-label` | String, default `'Start Time'` | Accessible label for the first time input |
 | `start-opened` | Boolean | Indicates if the start dropdown is open |
@@ -218,6 +222,7 @@ Note: All `*value` properties should be in ISO 8601 combined date and time forma
 | `localized` | Boolean | Indicates that any timezone localization will be handeld by the consumer and so any values will not be converted from/to UTC |
 | `max-value` | String | Maximum valid date/time that could be selected by a user |
 | `min-value` | String | Minimum valid date/time that could be selected by a user |
+| `name` | String | Name of the form control. Submitted with the form as part of a name/value pair. |
 | `opened` | Boolean | Indicates if the date or time dropdown is open |
 | `required` | Boolean | Indicates that a value is required |
 | `time-default-value`| String, default:`'00:00:00'` | Set default value of time input. Accepts ISO 8601 time format (`hh:mm:ss`) and the following keywords: `startOfDay`,`endOfDay`. |
@@ -261,6 +266,7 @@ Note: All `*value` properties should be in ISO 8601 combined date and time forma
 | `end-value` | String, default `''` | Value of the second date-time input |
 | `inclusive-date-range` | Boolean | Validate on inclusive range (i.e., it is valid for start and end date-times to be equal) |
 | `label-hidden` | Boolean | Hides the fieldset label visually |
+| `name` | String | Name of the form control. Submitted with the form as part of a name/value pair. |
 | `required` | Boolean | Indicates that values are required |
 | `start-label` | String, default `'Start Date'` | Accessible label for the first date-time input |
 | `start-opened` | Boolean | Indicates if the start date or time dropdown is open |

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

@@ -1,6 +1,6 @@
 # Numeric Inputs
 
-Numeric inputs allow users to input numbers. These include the more generic `d2l-input-number`, as well as the percentage input `d2l-input-percent`.
+Numeric inputs allow users to input numbers. These include the more generic `<d2l-input-number>`, as well as the percentage input `<d2l-input-percent>`.
 
 <!-- docs: demo -->
 ```html
@@ -25,15 +25,8 @@ The `<d2l-input-number>` element is similar to `<d2l-input-text>`, except it's i
 ```html
 <script type="module">
   import '@brightspace-ui/core/components/inputs/input-number.js';
-
-  window.addEventListener('load', function () {
-    var input = document.querySelector('#number');
-    input.addEventListener('change', (e) => {
-      console.log('numeric value: ', input.value);
-    });
-  });
 </script>
-<d2l-input-number id="number" label="Label"></d2l-input-number>
+<d2l-input-number label="Label"></d2l-input-number>
 ```
 
 <!-- docs: start hidden content -->
@@ -54,6 +47,7 @@ The `<d2l-input-number>` element is similar to `<d2l-input-text>`, except it's i
 | `min` | Number | Minimum value allowed. |
 | `min-exclusive` | Boolean, default: `false` | Indicates whether the min value is exclusive. |
 | `min-fraction-digits` | Number, default: `0` | Minimum number of digits allowed after the decimal place. Must be between 0 and 20 and less than or equal to `maxFractionDigits` |
+| `name` | String | Name of the form control. Submitted with the form as part of a name/value pair. |
 | `required` | Boolean, default: `false` | Indicates that a value is required. |
 | `unit` | String | Unit associated with the input value, displayed next to input and announced as part of the label |
 | `unit-label` | String | Label for the unit, which is only picked up by screenreaders. Required if `unit` is used. |
@@ -94,15 +88,8 @@ The `<d2l-input-percent>` element is similar to `<d2l-input-number>`, except it
 ```html
 <script type="module">
   import '@brightspace-ui/core/components/inputs/input-percent.js';
-
-  window.addEventListener('load', function () {
-    var input = document.querySelector('#percent');
-    input.addEventListener('change', (e) => {
-      console.log('percentage value: ', input.value);
-    });
-  });
 </script>
-<d2l-input-percent id="percent" label="Label"></d2l-input-percent>
+<d2l-input-percent label="Label"></d2l-input-percent>
 ```
 
 <!-- docs: start hidden content -->
@@ -117,6 +104,7 @@ The `<d2l-input-percent>` element is similar to `<d2l-input-number>`, except it
 | `label-hidden` | Boolean, default: `false` | Hides the label visually. Hidden labels are still read by screen readers so make sure to set an appropriate label. |
 | `max-fraction-digits` | Number | Maximum number of digits allowed after the decimal place. |
 | `min-fraction-digits` | Number | Minimum number of digits allowed after the decimal place. |
+| `name` | String | Name of the form control. Submitted with the form as part of a name/value pair. |
 | `required` | Boolean, default: `false` | Indicates that a value is required. |
 | `value` | Number | Value of the input. |
 

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

@@ -1,4 +1,4 @@
-# Search Inputs
+# Search Input
 
 Search inputs allow users to input text, execute a search, and clear results. A search input may be used in conjunction with filters, sort, and/or auto-complete.
 
@@ -39,14 +39,8 @@ For text searches use `<d2l-input-search>`, which wraps the native `<input type=
 ```html
 <script type="module">
   import '@brightspace-ui/core/components/inputs/input-search.js';
-
-  window.addEventListener('load', function () {
-    document.querySelector('#search').addEventListener('d2l-input-search-searched', (e) => {
-      console.log('searched term:', e.detail.value);
-    });
-  });
 </script>
-<d2l-input-search id="search" label="Search">
+<d2l-input-search label="Search">
 </d2l-input-search>
 ```
 
@@ -66,7 +60,7 @@ For text searches use `<d2l-input-search>`, which wraps the native `<input type=
 
 ### Events
 
-The `d2l-input-search` component dispatches the `d2l-input-search-searched` event when a search is performed:
+The `<d2l-input-search>` component dispatches the `d2l-input-search-searched` event when a search is performed:
 
 ```javascript
 search.addEventListener('d2l-input-search-searched', (e) => {

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

@@ -44,18 +44,8 @@ The `<d2l-input-text>` element is a simple wrapper around the native `<input typ
 ```html
 <script type="module">
   import '@brightspace-ui/core/components/inputs/input-text.js';
-
-  window.addEventListener('load', function () {
-    var input = document.querySelector('#text');
-    input.addEventListener('change', (e) => {
-      console.log('input-text change: ', input.value);
-    });
-    input.addEventListener('input', (e) => {
-      console.log('input-text input: ', input.value);
-    });
-  });
 </script>
-<d2l-input-text id="text" label="Label"></d2l-input-text>
+<d2l-input-text label="Label"></d2l-input-text>
 ```
 
 <!-- docs: start hidden content -->
@@ -78,7 +68,7 @@ The `<d2l-input-text>` element is a simple wrapper around the native `<input typ
 | `maxlength` | Number | Imposes an upper character limit |
 | `min` | String | For number inputs, minimum value |
 | `minlength` | Number | Imposes a lower character limit |
-| `name` | String | Name of the input |
+| `name` | String | Name of the form control. Submitted with the form as part of a name/value pair. |
 | `novalidate` | Boolean | Disables the built-in validation |
 | `pattern` | String | Regular expression pattern to validate the value |
 | `pattern-failure-text` | String | Text to display when input fails validation against the pattern. If a list of characters is included in the message, use `LocalizeMixin`'s `localizeCharacter`. |
@@ -93,7 +83,7 @@ The `<d2l-input-text>` element is a simple wrapper around the native `<input typ
 
 ### Events
 
-The `d2l-input-text` dispatches the `change` event when an alteration to the value is committed (typically after focus is lost) by the user. To be notified immediately of changes made by the user, use the `input` event.
+The `<d2l-input-text>` dispatches the `change` event when an alteration to the value is committed (typically after focus is lost) by the user. To be notified immediately of changes made by the user, use the `input` event.
 
 ```javascript
 // dispatched when value changes are committed
@@ -116,45 +106,18 @@ input.addEventListener('input', (e) => {
 
 ### Accessibility Properties
 
-To make your usage of `d2l-input-text` accessible, use the following properties when applicable:
+To make your usage of `<d2l-input-text>` accessible, use the following properties when applicable:
 
 | Attribute | Description |
 |---|---|
 | `aria-haspopup` | [Indicate clicking the input opens a menu](https://www.w3.org/WAI/PF/aria/states_and_properties#aria-haspopup). |
 | `aria-invalid` | [Indicate that the input value is invalid](https://www.w3.org/WAI/PF/aria/states_and_properties#aria-invalid) |
-| `aria-label` | Use when `label` does not provide enough context. Only applies if no `label-hidden`. |
 | `description` | Use when label on input does not provide enough context. |
 | `label` | **REQUIRED**  [Acts as a primary label on the input](https://www.w3.org/WAI/tutorials/forms/labels/). Visible unless `label-hidden` is also used. |
 | `label-hidden` | Use if label should be visually hidden but available for screen reader users |
 | `labelled-by` | Use when another visible element should act as the label |
 | `unit` | Use to render the unit (offscreen) as part of the label. |
 
-## Applying styles to native text input
-
-As an alternative to using the `<d2l-input-text>` custom element, you can style a native text input inside your own element. Import `input-styles.js` and apply the `d2l-input` CSS class to the input:
-
-<!-- docs: demo code -->
-```html
-<script type="module">
-  import { html, LitElement } from 'lit';
-  import { inputStyles } from '@brightspace-ui/core/components/inputs/input-styles.js';
-
-  class MyTextInputElem extends LitElement {
-
-    static get styles() {
-      return inputStyles;
-    }
-
-    render() {
-      return html`<input type="text" class="d2l-input">`;
-    }
-
-  }
-  customElements.define('d2l-my-text-input-elem', MyTextInputElem);
-</script>
-<d2l-my-text-input-elem></d2l-my-text-input-elem>
-```
-
 ## Textarea Input [d2l-input-textarea]
 
 The `<d2l-input-textarea>` is a wrapper around the native `<textarea>` element that provides auto-grow and validation behaviours. It's intended for inputting unformatted multi-line text.
@@ -163,23 +126,13 @@ The `<d2l-input-textarea>` is a wrapper around the native `<textarea>` element t
 ```html
 <script type="module">
   import '@brightspace-ui/core/components/inputs/input-textarea.js';
-
-  window.addEventListener('load', function () {
-    var input = document.querySelector('#textarea');
-    input.addEventListener('change', (e) => {
-      console.log('input-textarea change: ', input.value);
-    });
-    input.addEventListener('input', (e) => {
-      console.log('input-textarea input: ', input.value);
-    });
-  });
 </script>
 <style>
   d2l-input-textarea {
     width: 100%;
   }
 </style>
-<d2l-input-textarea id="textarea" label="Description"></d2l-input-textarea>
+<d2l-input-textarea label="Description"></d2l-input-textarea>
 ```
 
 <!-- docs: start hidden content -->
@@ -187,15 +140,16 @@ The `<d2l-input-textarea>` is a wrapper around the native `<textarea>` element t
 
 | Property | Type | Description |
 |---|---|---|
+| `label` | String, required | Label for the `textarea` |
 | `aria-invalid` | String | Indicates that the `textarea` value is invalid |
 | `description` | String | A description to be added to the `textarea` for accessibility |
 | `disabled` | Boolean | Disables the `textarea` |
-| `label` | String, required | Label for the `textarea` |
 | `label-hidden` | Boolean | Hides the label visually (moves it to the `textarea`'s `aria-label` attribute) |
 | `labelled-by` | String | HTML id of an element in the same shadow root which acts as the input's label |
 | `max-rows` | Number, default: 11 | Maximum number of rows before scrolling. Less than 1 allows `textarea` to grow infinitely. |
 | `maxlength` | Number | Imposes an upper character limit |
 | `minlength` | Number | Imposes a lower character limit |
+| `name` | String | Name of the form control. Submitted with the form as part of a name/value pair. |
 | `no-border` | Boolean | Hides the border |
 | `no-padding` | Boolean | Removes left/right padding |
 | `required` | Boolean | Indicates that a value is required |
@@ -204,7 +158,7 @@ The `<d2l-input-textarea>` is a wrapper around the native `<textarea>` element t
 
 ### Events
 
-The `d2l-input-textarea` dispatches the `change` event when an alteration to the value is committed (typically after focus is lost) by the user. To be notified immediately of changes made by the user, use the `input` event.
+The `<d2l-input-textarea>` dispatches the `change` event when an alteration to the value is committed (typically after focus is lost) by the user. To be notified immediately of changes made by the user, use the `input` event.
 
 ```javascript
 // dispatched when value changes are committed
@@ -235,29 +189,3 @@ To make your usage of `d2l-input-textarea` accessible, use the following propert
 
 * `focus()`: Places focus in the `textarea`
 * `select()`: Selects the contents of the `textarea`
-
-## Applying styles to native textarea
-
-Native `<textarea>` elements can be styled by importing `input-styles.js` into your LitElement and applying the `d2l-input` CSS class.
-
-<!-- docs: demo code -->
-```html
-<script type="module">
-  import { html, LitElement } from 'lit';
-  import { inputStyles } from '@brightspace-ui/core/components/inputs/input-styles.js';
-
-  class MyTextareaInputElem extends LitElement {
-    static get styles() {
-      return inputStyles;
-    }
-    render() {
-      return html`
-        <textarea class="d2l-input">
-        </textarea>
-        `;
-    }
-  }
-  customElements.define('d2l-my-textarea-input-elem', MyTextareaInputElem);
-</script>
-<d2l-my-textarea-input-elem></d2l-my-textarea-input-elem>
-```

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

@@ -151,3 +151,55 @@ To align related content below radio buttons, the `d2l-input-radio-spacer` eleme
 </script>
 <d2l-my-radio-spacer-elem></d2l-my-radio-spacer-elem>
 ```
+
+## Text Input
+
+Import `input-styles.js` and apply the `d2l-input` CSS class to the native `<input>`:
+
+<!-- docs: demo code -->
+```html
+<script type="module">
+  import { html, LitElement } from 'lit';
+  import { inputStyles } from '@brightspace-ui/core/components/inputs/input-styles.js';
+
+  class MyTextInputElem extends LitElement {
+
+    static get styles() {
+      return inputStyles;
+    }
+
+    render() {
+      return html`<input type="text" class="d2l-input">`;
+    }
+
+  }
+  customElements.define('d2l-my-text-input-elem', MyTextInputElem);
+</script>
+<d2l-my-text-input-elem></d2l-my-text-input-elem>
+```
+
+## Textarea Input
+
+Import `input-styles.js` and apply the `d2l-input` CSS class to the  native `<textarea>`.
+
+<!-- docs: demo code -->
+```html
+<script type="module">
+  import { html, LitElement } from 'lit';
+  import { inputStyles } from '@brightspace-ui/core/components/inputs/input-styles.js';
+
+  class MyTextareaInputElem extends LitElement {
+    static get styles() {
+      return inputStyles;
+    }
+    render() {
+      return html`
+        <textarea class="d2l-input">
+        </textarea>
+        `;
+    }
+  }
+  customElements.define('d2l-my-textarea-input-elem', MyTextareaInputElem);
+</script>
+<d2l-my-textarea-input-elem></d2l-my-textarea-input-elem>
+```

package/components/inputs/input-text.js

@@ -42,7 +42,7 @@ class InputText extends InputInlineHelpMixin(PropertyRequiredMixin(FocusMixin(La
 			 */
 			ariaInvalid: { type: String, attribute: 'aria-invalid' },
 			/**
-			 * Specifies which types of values can be autofilled by the browser
+			 * ADVANCED: Specifies which types of values can be autofilled by the browser
 			 * @type {string}
 			 */
 			autocomplete: { type: String },
@@ -125,7 +125,7 @@ class InputText extends InputInlineHelpMixin(PropertyRequiredMixin(FocusMixin(La
 			 */
 			preventSubmit: { type: Boolean, attribute: 'prevent-submit' },
 			/**
-			 * Makes the input read-only
+			 * ADVANCED: Makes the input read-only
 			 * @type {boolean}
 			 */
 			readonly: { type: Boolean },
@@ -140,7 +140,7 @@ class InputText extends InputInlineHelpMixin(PropertyRequiredMixin(FocusMixin(La
 			 */
 			size: { type: Number },
 			/**
-			 * For number inputs, sets the step size
+			 * ADVANCED: For number inputs, sets the step size
 			 * @type {string}
 			 */
 			step: { type: String },
@@ -181,7 +181,7 @@ class InputText extends InputInlineHelpMixin(PropertyRequiredMixin(FocusMixin(La
 			 */
 			value: { type: String },
 			/**
-			 * Alignment of the value text within the input
+			 * ADVANCED: Alignment of the value text within the input
 			 * @type {'start'|'end'}
 			 */
 			valueAlign: { attribute: 'value-align', type: String },

package/custom-elements.json

@@ -7242,7 +7242,7 @@
         },
         {
           "name": "autocomplete",
-          "description": "Specifies which types of values can be autofilled by the browser",
+          "description": "ADVANCED: Specifies which types of values can be autofilled by the browser",
           "type": "string"
         },
         {
@@ -7297,7 +7297,7 @@
         },
         {
           "name": "step",
-          "description": "For number inputs, sets the step size",
+          "description": "ADVANCED: For number inputs, sets the step size",
           "type": "string"
         },
         {
@@ -7347,7 +7347,7 @@
         },
         {
           "name": "readonly",
-          "description": "Makes the input read-only",
+          "description": "ADVANCED: Makes the input read-only",
           "type": "boolean",
           "default": "false"
         },
@@ -7365,7 +7365,7 @@
         },
         {
           "name": "value-align",
-          "description": "Alignment of the value text within the input",
+          "description": "ADVANCED: Alignment of the value text within the input",
           "type": "'start'|'end'",
           "default": "\"start\""
         },
@@ -7406,7 +7406,7 @@
         {
           "name": "autocomplete",
           "attribute": "autocomplete",
-          "description": "Specifies which types of values can be autofilled by the browser",
+          "description": "ADVANCED: Specifies which types of values can be autofilled by the browser",
           "type": "string"
         },
         {
@@ -7472,7 +7472,7 @@
         {
           "name": "step",
           "attribute": "step",
-          "description": "For number inputs, sets the step size",
+          "description": "ADVANCED: For number inputs, sets the step size",
           "type": "string"
         },
         {
@@ -7536,7 +7536,7 @@
         {
           "name": "readonly",
           "attribute": "readonly",
-          "description": "Makes the input read-only",
+          "description": "ADVANCED: Makes the input read-only",
           "type": "boolean",
           "default": "false"
         },
@@ -7557,7 +7557,7 @@
         {
           "name": "valueAlign",
           "attribute": "value-align",
-          "description": "Alignment of the value text within the input",
+          "description": "ADVANCED: Alignment of the value text within the input",
           "type": "'start'|'end'",
           "default": "\"start\""
         },

package/package.json

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