@brightspace-ui/core 3.126.4 → 3.127.0

package/components/form/README.md

@@ -6,7 +6,7 @@ There are several components and mixins available to help make working with form
 
 Much like a native `<form>` element, `<d2l-form>` groups nested form elements together and controls how their data is validated and submitted. Unlike native `<form>`s, it supports our custom form elements.
 
-- [d2l-form](docs/form.md#form-d2l-form): supports aggregation of nested forms for validation and submission
+See: [Form Layout and Validation](../inputs/docs/form-layout-validation.md)
 
 ## Custom Elements in Forms
 

package/components/inputs/README.md

@@ -9,88 +9,8 @@ There are various input components available:
 - [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)
+- [Text (input-text, input-textarea)](docs/input-text.md)
 
-## Labelling Inputs
-
-All inputs *must* have a label. Web component-based inputs like `<d2l-input-checkbox>`, `<d2l-input-number>`, `<d2l-input-percent>`, `<d2l-input-search>`, `<d2l-input-text>`, and `<d2l-input-textarea>` come with built-in labels. For the rest, labelling is accomplished visually using a `<label>` element or with a hidden label via the `aria-label` attribute.
-
-Groups of inputs (like checkboxes or radios) should be wrapped in a `<fieldset>` which can have label styles applied to it.
-
-### Visible labels using the `<label>` element
-
-Import the label styles and include them in your component:
-
-```javascript
-import { inputLabelStyles } from '@brightspace-ui/core/components/inputs/input-label-styles.js';
-
-class MyElem extends LitElement {
-
-  static get styles() {
-    return inputLabelStyles;
-  }
-
-}
-```
-
-Label styles are then applied using the `d2l-input-label` CSS class.
-
-Wrap the input in a `<label>` element and apply the styles to a nested `<span>` element:
-
-```html
-<label>
-  <span class="d2l-input-label">City</span>
-  <select>...</select>
-</label>
-```
-
-Alternately, associate the `<label>` with the input using the `for` and `id` attributes and apply the styles to the label directly:
-
-```html
-<label for="myInput" class="d2l-input-label">City</label>
-<select id="myInput">...</select>
-```
-
-For required inputs, add the `d2l-input-label-required` CSS class to the label to get a visual indicator. Don't forget to add `aria-required="true"` to the input so that assistive technology is aware as well.
-
-```html
-<label for="myInput" class="d2l-input-label d2l-input-label-required">City</label>
-<select id="myInput" aria-required="true">...</select>
-```
-
-### Hidden labels
-
-If you wish to visually hide the label, use the `aria-label` attribute on your input instead:
-
-```html
-<select aria-label="City">...</select>
-```
-
-### Grouping inputs with `<fieldset>`
-
-When a page contains multiple inputs which are related (for example to form an address), wrap the inputs with `<fieldset>` and `<legend>` elements. Then apply the `d2l-input-label-fieldset` and `d2l-input-label` CSS classes to the `<fieldset>` and `<legend>` elements respectively.
-
-```html
-<fieldset class="d2l-input-label-fieldset">
-  <legend class="d2l-input-label">Shipping Address</legend>
-  <!-- set of related inputs go here -->
-</fieldset>
-```
-
-Alternately, the `<d2l-input-fieldset>` component can accomplish this for you. The legend can be visually hidden by applying the `label-hidden` attribute to the component.
-
-```html
-<script type="module">
-  import '@brightspace-ui/core/components/inputs/input-fieldset.js';
-</script>
-<d2l-input-fieldset label="Shipping Address">
-	<!-- set of related inputs go here -->
-</d2l-input-fieldset>
-```
-
-## Future Enhancements
-
-- Color input with contrast analysis
-- Auto-growing textareas
-
-Looking for an enhancement not listed here? Create a GitHub issue!
+See also:
+- [Form Layout and Validation](docs/form-layout-validation.md)
+- [FormElementMixin](../form/docs/form-element-mixin.md)

package/components/inputs/docs/form-layout-validation.md

@@ -0,0 +1,146 @@
+# Form Layout & Validation
+
+There are several components available for working with collections of inputs. Inputs can be validated and submitted in a form, visually layed out using an input group, and related to each other semantically using an input fieldset.
+
+<!-- docs: demo display:block -->
+```html
+<script type="module">
+  import '@brightspace-ui/core/components/button/button.js';
+  import '@brightspace-ui/core/components/form/form.js';
+  import '@brightspace-ui/core/components/inputs/input-fieldset.js';
+  import '@brightspace-ui/core/components/inputs/input-group.js';
+  import '@brightspace-ui/core/components/inputs/input-text.js';
+
+  const form = document.querySelector('d2l-form');
+  document.querySelector('d2l-button').addEventListener('click', () => form.submit());
+</script>
+<d2l-form>
+  <d2l-input-group>
+    <d2l-input-text label="Name" required style="max-width: 200px;"></d2l-input-text>
+    <d2l-input-fieldset label="Address" label-style="heading">
+      <d2l-input-group>
+        <d2l-input-text label="Street" style="max-width: 350px;"></d2l-input-text>
+        <d2l-input-text label="City" style="max-width: 200px;"></d2l-input-text>
+      </d2l-input-group>
+    </d2l-input-fieldset>
+  </d2l-input-group>
+  <d2l-button primary style="margin-top: 1rem;">Submit</d2l-button>
+</d2l-form>
+```
+
+## Form [d2l-form]
+
+The `<d2l-form>` component is used to wrap inputs which are then validated and submitted together.
+
+Unlike the standard HTML `<form>` element, `<d2l-form>` supports validating and submitting custom elements. It also displays an aggregated summary of validation errors at the top of the form.
+
+<!-- docs: demo code properties name:d2l-form sandboxTitle:'Form' display:block -->
+```html
+<script type="module">
+  import '@brightspace-ui/core/components/button/button.js';
+  import '@brightspace-ui/core/components/form/form.js';
+  import '@brightspace-ui/core/components/inputs/input-group.js';
+  import '@brightspace-ui/core/components/inputs/input-text.js';
+  import '@brightspace-ui/core/components/inputs/input-textarea.js';
+
+  const form = document.querySelector('d2l-form');
+  form.addEventListener('d2l-form-submit', e => {
+    const data = e.detail.formData;
+    console.log(`name: "${data.name}"`);
+    console.log(`description: "${data.description}"`);
+  });
+  document
+    .querySelector('d2l-button')
+    .addEventListener('click', () => form.submit());
+</script>
+<d2l-form>
+  <d2l-input-group>
+    <d2l-input-text label="Name" required style="max-width: 200px;"></d2l-input-text>
+    <d2l-input-textarea label="Description" rows="3" style="max-width: 300px;"></d2l-input-textarea>
+  </d2l-input-group>
+  <d2l-button primary style="margin-top: 1rem;">Submit</d2l-button>
+</d2l-form>
+```
+
+<!-- docs: start hidden content -->
+### Properties
+
+| Property | Type | Description |
+|---|---|---|
+| `no-nesting` | Boolean, default: `false` | Indicates that the form should opt-out of nesting.<br><br>This means that it will not be submitted or validated if an ancestor form is submitted or validated. However, directly submitting or validating a form with `no-nesting` will still trigger submission and validation for its descendant forms unless they also opt-out using `no-nesting`. |
+
+### Events
+- `d2l-form-submit`: Dispatched when the form is submitted. The form data can be obtained from the `detail`'s `formData` property.
+- `d2l-form-invalid`: Dispatched when the form fails validation. The error map can be obtained from the `detail`'s `errors` property.
+- `d2l-form-dirty`: Dispatched whenever any form element fires an `input` or `change` event. Can be used to track whether the form is dirty or not.
+<!-- docs: end hidden content -->
+
+### Submitting and Handling Form Submissions
+
+A typical setup will involve listening for the `d2l-form-submit` event on the `<d2l-form>` and calling the form's `submit()` API to trigger the submission.
+
+Before submission can proceed, all inputs in the form are validated.
+
+If validation succeeds, the form data will be aggregated and provided to the `d2l-form-submit` event's `detail.formData`. If validation fails, a summary of the errors will be displayed to the user.
+
+### Nested Forms
+
+By default, `<d2l-form>` will discover nested descendant `<d2l-form>` elements and include their inputs in its validation and submission process. To opt a form out of this behaviour, set the `no-nesting` attribute.
+
+When forms are nested, validation is _**atomic**_. Validation will only succeed if validation succeeds for the root form and all nested forms. If any form fails validation, none of them will be submitted.
+
+Alternatively, nested form submission is _**independent**_. As a result, when nested forms all pass validation, each `<d2l-form>` will fire its own `d2l-form-submit` event with the data associated with that form. This avoids potential collisions when inputs in different forms share the same `name`.
+
+## Input Group [d2l-input-group]
+
+When more than one input is displayed together, a `<d2l-input-group>` can be used to apply a consistent gap to elements in its slot, as well as appropriate space between itself and a parent `<d2l-form>`'s validation errors.
+
+<!-- docs: demo code display:block name:d2l-input-group sandboxTitle:'Input Group' -->
+```html
+<script type="module">
+  import '@brightspace-ui/core/components/inputs/input-group.js';
+  import '@brightspace-ui/core/components/inputs/input-text.js';
+  import '@brightspace-ui/core/components/inputs/input-textarea.js';
+</script>
+<d2l-input-group>
+  <d2l-input-text label="Name" style="max-width: 200px;"></d2l-input-text>
+  <d2l-input-textarea label="Description" rows="3" style="max-width: 300px;"></d2l-input-textarea>
+</d2l-input-group>
+```
+
+## Input Fieldset [d2l-input-fieldset]
+
+When inputs are related to each other (for example multiple inputs which together form a mailing address), a `<d2l-input-fieldset>` is used to provide that additional context.
+
+Within the fieldset, `<d2l-input-group>` can still be used to provide a consistent gap between the inputs.
+
+<!-- docs: demo code properties display:block name:d2l-input-fieldset sandboxTitle:'Input Fieldset' -->
+```html
+<script type="module">
+  import '@brightspace-ui/core/components/inputs/input-fieldset.js';
+  import '@brightspace-ui/core/components/inputs/input-group.js';
+  import '@brightspace-ui/core/components/inputs/input-text.js';
+</script>
+<d2l-input-fieldset label="Contact Information" label-style="heading">
+  <d2l-input-group>
+    <d2l-input-text type="tel" label="Phone" style="max-width: 200px;"></d2l-input-text>
+    <d2l-input-text type="email" label="Email" style="max-width: 250px;"></d2l-input-text>
+  </d2l-input-group>
+</d2l-input-fieldset>
+```
+
+<!-- docs: start hidden content -->
+### Properties
+
+| Property | Type | Description |
+|---|---|---|
+| `label` | String, required | Label for the fieldset
+| `label-hidden` | Boolean | Hides the label visually |
+| `label-style` | Boolean | Style of the fieldset label |
+| `required` | Boolean | Indicates that a value is required for inputs in the fieldset |
+
+### Slots
+
+* `Default`: Related input components
+* `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.
+<!-- docs: end hidden content -->

package/components/inputs/docs/input-select-styles.md

@@ -15,7 +15,7 @@ A Select List allows the user to select a single option out of a relatively larg
     }
     render() {
       return html`
-        <select class="d2l-input-select">
+        <select class="d2l-input-select" aria-label="Options">
           <option>Option 1</option>
           <option>Option 2</option>
         </select>
@@ -32,23 +32,22 @@ A Select List allows the user to select a single option out of a relatively larg
 <!-- docs: start best practices -->
 <!-- docs: start dos -->
 * Use to allow the user to select a single option from a relatively large list of options
-* Use to save space / reduce the visual prominence of an exclusive selection option (instead of a choice from 8 radio buttons)
-* Use a Select List to tuck away non-critical options, or options where the default selection is likely to be the most desirable.
+* Use to save space / reduce the visual prominence of an exclusive selection option (instead of a choice from 8 radio inputs)
+* Use a Select List to tuck away non-critical options, or options where the default selection is likely to be the most desirable
 <!-- docs: end dos -->
 
 <!-- docs: start donts -->
-* Don't use if your options are more than 1-2 words. The cognitive load of comparing options in a Select List is relatively high
-* Select Lists show the available options offscreen – be careful if the selections you are asking the user to make are on the critical path – see [Dropdowns should be the UI of last resort](https://www.lukew.com/ff/entry.asp?1950) and be careful about your selection.
-* Select Lists are form controls, and should not submit data or have instant actions on page occur without an explicit submit action.
-Toggling progressive disclosure is OK
-* Don't use prompt text in place of a Select List field label – it’s harder to scan and negatively impacts accessibility.
-* Don't use for numeric input – a text field with type “number” or a date-picker is much easier to use control
+* Don't use if your options are more than 1-2 words. The cognitive load of comparing options in a Select List is relatively high.
+* Select Lists show the available options offscreen – be careful if the selections you are asking the user to make are on the critical path – see [Dropdowns should be the UI of last resort](https://www.lukew.com/ff/entry.asp?1950) and be careful about your selection
+* Select Lists are form controls, and should not submit data or execute an action without an explicit submit action. Toggling progressive disclosure is OK.
+* Don't use prompt text in place of a Select List field label – it’s harder to scan and negatively impacts accessibility
+* Don't use for numeric input – a `<d2l-input-number>` or a date input is much easier to use
 <!-- docs: end donts -->
 <!-- docs: end best practices -->
 
 ## Applying styles to native select elements
 
-Native `<select>` elements can be styled by importing `input-select-styles.js` into your LitElement and applying the `d2l-input-select` CSS class.
+Native `<select>` elements can be styled by importing `input-select-styles.js` into your Lit element and applying the `d2l-input-select` CSS class.
 
 The styles support the pseudo-classes `disabled`, `focus`, and `hover`, as well as the `aria-invalid` attribute.
 
@@ -63,14 +62,14 @@ When applying styles to the native element, we also recommend using the [`Skelet
 
   class TestInputSelect extends SkeletonMixin(LitElement) {
   static get styles() {
-    return [ super.styles, selectStyles ];
+    return [super.styles, selectStyles];
   }
 
   render() {
     return html`
       <div class="d2l-skeletize">
         <select
-          aria-label="Choose a dinosaur:"
+          aria-label="Dinosaur"
           class="d2l-input-select">
           <option>Tyrannosaurus</option>
           <option>Velociraptor</option>
@@ -86,34 +85,37 @@ When applying styles to the native element, we also recommend using the [`Skelet
 <d2l-test-input-select></d2l-test-input-select>
 ```
 
-### Invalid
+## Labelling
 
-Use the [`aria-invalid`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-invalid) attribute to support screenreader users and apply our consistent error styles.
+The `aria-label` attribute can be used in places where a non-visible label is desired.
 
-<!-- docs: demo -->
+For a visible label, import the label styles and include them in your component's `styles`. Wrap the `<select>` in a `<label>` element and apply the styles by adding the `d2l-input-label` CSS class to a nested `<span>` element:
+
+<!-- docs: demo code -->
 ```html
 <script type="module">
   import { html, LitElement } from 'lit';
   import { selectStyles } from '@brightspace-ui/core/components/inputs/input-select-styles.js';
+  import { inputLabelStyles } from '@brightspace-ui/core/components/inputs/input-label-styles.js';
 
   class TestInputSelect extends LitElement {
 
-  static get styles() {
-    return [ selectStyles ];
-  }
+    static get styles() {
+      return [inputLabelStyles, selectStyles];
+    }
 
-  render() {
-    return html`
-      <select
-        aria-label="Choose a dinosaur:"
-        aria-invalid="true"
-        class="d2l-input-select">
-        <option>Tyrannosaurus</option>
-        <option>Velociraptor</option>
-        <option>Deinonychus</option>
-      </select>
-    `;
-  }
+    render() {
+      return html`
+        <label>
+          <span class="d2l-input-label">Dinosaur</span>
+          <select class="d2l-input-select">
+            <option>Tyrannosaurus</option>
+            <option>Velociraptor</option>
+            <option>Deinonychus</option>
+          </select>
+        </label>
+      `;
+    }
 
   }
   customElements.define('d2l-test-input-select', TestInputSelect);
@@ -126,5 +128,5 @@ Use the [`aria-invalid`](https://developer.mozilla.org/en-US/docs/Web/Accessibil
 - Due to applying styles based on a CSS class rather than being its own component, the accessibility provided by `selectStyles` comes purely in the way of following the guidelines for [contrast](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html) and [focus](https://www.w3.org/WAI/WCAG21/Understanding/focus-visible.html)
 - There are several things that can be done to make sure your `select` component is accessible, including:
   - Following the W3C [Combobox](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) pattern
-  - Using either the `aria-label` or `aria-labelledby` to appropriately assign a label to your component
+  - Using either the `aria-label` attribute, a wrapper `<label>` element or `<label>` with `aria-labelledby` to appropriately assign a label to your component
   - Using `label` for `optgroup` if you choose to use that element within the select element, so that it can be read out to screenreaders

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

@@ -2,24 +2,17 @@
 
 Text inputs allow users to input, edit, and select text.
 
-<!-- docs: demo -->
+<!-- docs: demo display:block -->
 ```html
 <script type="module">
+  import '@brightspace-ui/core/components/inputs/input-group.js';
   import '@brightspace-ui/core/components/inputs/input-text.js';
   import '@brightspace-ui/core/components/inputs/input-textarea.js';
 </script>
-<style>
-  div {
-    width: 100%;
-  }
-  d2l-input-text {
-    padding-bottom: 1rem;
-  }
-</style>
-<div>
+<d2l-input-group>
   <d2l-input-text label="Name"></d2l-input-text>
   <d2l-input-textarea label="Description" max-rows="4" rows="4"></d2l-input-textarea>
-</div>
+</d2l-input-group>
 ```
 
 ## Best Practices

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

@@ -203,3 +203,14 @@ Import `input-styles.js` and apply the `d2l-input` CSS class to the  native `<te
 </script>
 <d2l-my-textarea-input-elem></d2l-my-textarea-input-elem>
 ```
+
+### Grouping inputs with `<fieldset>`
+
+When a page contains multiple inputs which are related, wrap the inputs with `<fieldset>` and `<legend>` elements. Then apply the `d2l-input-label-fieldset` and `d2l-input-label` CSS classes to the `<fieldset>` and `<legend>` elements respectively.
+
+```html
+<fieldset class="d2l-input-label-fieldset">
+  <legend class="d2l-input-label">Shipping Address</legend>
+  <!-- set of related inputs go here -->
+</fieldset>
+```

package/components/inputs/input-fieldset.js

@@ -12,6 +12,7 @@ import { SkeletonMixin } from '../skeleton/skeleton-mixin.js';
 /**
  * A component wrapper to be used when a page contains multiple inputs which are related (for example to form an address) to wrap those related inputs.
  * @slot - Related input components
+ * @slot inline-help - Help text that will appear below the fieldset. Use this only when other helpful cues are not sufficient, such as a carefully-worded label.
  */
 class InputFieldset extends PropertyRequiredMixin(InputInlineHelpMixin(SkeletonMixin(LitElement))) {
 

package/custom-elements.json

@@ -6463,6 +6463,10 @@
         {
           "name": "",
           "description": "Related input components"
+        },
+        {
+          "name": "inline-help",
+          "description": "Help text that will appear below the fieldset. Use this only when other helpful cues are not sufficient, such as a carefully-worded label."
         }
       ]
     },

package/lang/mi.js

@@ -3,7 +3,7 @@ export default {
 	"components.breadcrumbs.breadcrumb": "Pānui",
 	"components.button-add.addItem": "Tāpiri Tūemi",
 	"components.button-split.otherOptions": "Other Options",
-	"components.calendar.hasEvents": "He takahanga anō.",
+	"components.calendar.hasEvents": "He takatu ēnei.",
 	"components.calendar.notSelected": "Kāore i tīpakona.",
 	"components.calendar.selected": "I tīpakona.",
 	"components.calendar.show": "Whakaatu {month}",
@@ -33,10 +33,10 @@ export default {
 	"components.filter-dimension-set-date-text-value.textMonths": "Ngā marama {num} whakamutunga",
 	"components.filter-dimension-set-date-time-range-value.label": "{text}, whakaroha hei kōwhiri i ngā rā",
 	"components.filter-dimension-set-date-time-range-value.valueTextRange": "{startValue} ki {endValue}",
-	"components.filter-dimension-set-date-time-range-value.valueTextRangeStartOnly": "After {startValue}",
-	"components.filter-dimension-set-date-time-range-value.valueTextRangeEndOnly": "Before {endValue}",
+	"components.filter-dimension-set-date-time-range-value.valueTextRangeStartOnly": "I muri o {startValue}",
+	"components.filter-dimension-set-date-time-range-value.valueTextRangeEndOnly": "I mua i {endValue}",
 	"components.filter-dimension-set-date-time-range-value.text": "Awhe rā ritenga",
-	"components.form-element.defaultError": "{label} is invalid",
+	"components.form-element.defaultError": "Kāore i te whai mana te {label}",
 	"components.form-element.defaultFieldLabel": "Āpure",
 	"components.form-element.input.email.typeMismatch": "Kāore te īmēra i te tika",
 	"components.form-element.input.number.rangeError": "{minExclusive, select, true {{maxExclusive, select, true {Number me nui ake i te {min} me iti iho i te {max}.} other {Number me nui ake i te {min} me iti iho rānei i te ōrite ki {max}.}}} other {{maxExclusive, select, true {Number me nui ake, ōrite rānei ki {min} and less than {max}.} other {Number me nui ake, ōrite rānei ki {min} me iti iho, ōrite rānei ki {max}.}}}}",
@@ -44,7 +44,7 @@ export default {
 	"components.form-element.input.number.rangeUnderflow": "{minExclusive, select, true {Number must me nui ake i te {min}.} other {Number me nui ake, ōrite rānei ki {min}.}}",
 	"components.form-element.input.text.tooShort": "Me noho te {label} kia {minlength} ngā pūāhua",
 	"components.form-element.input.url.typeMismatch": "Kāore te URL i te tika",
-	"components.form-element.valueMissing": "{label} is required",
+	"components.form-element.valueMissing": "E hiahiatia ana te {label}",
 	"components.form-error-summary.errorSummary": "{count, plural, one {Tērā {count} hapa i kitea i te mōhiohio i tukuna e koe} other {I te {count} ngā hapa i kitea i te mōhiohio i tukuna e koe}}",
 	"components.form-error-summary.text": "Takahuri taipitopito hapa",
 	"components.input-color.backgroundColor": "Tae papamuri",
@@ -70,9 +70,9 @@ export default {
 	"components.input-date.errorOutsideRange": "Me noho te rā ki waenga i te {minDate} me te {maxDate}",
 	"components.input-date.openInstructions": "Whakamahia te hōputu rā {format}. Pere whakararo, pēhi rānei i te tāuru hei uru ki te pae-iti.",
 	"components.input-date.now": "Ināianei",
-	"components.input-date.revert": "{label} reverted to previous value.",
+	"components.input-date.revert": "Kua hokia te {label} ki te uara tōmua.",
 	"components.input-date.today": "Āianei",
-	"components.input-date.useDateFormat": "Use date format {format}.",
+	"components.input-date.useDateFormat": "Whakamahia te hōputu rā {format}.",
 	"components.input-number.hintInteger": "Ka whakaae anake tēnei āpure ki ngā uara tau tōpū (kāore he ira)",
 	"components.input-number.hintDecimalDuplicate": "He ira kē kei tēnei tau",
 	"components.input-number.hintDecimalIncorrectComma": "Hei tāpiri i tētahi ira whakamahi i te piko \",\" pūāhua",
@@ -112,8 +112,8 @@ export default {
 	"components.pageable.info": "{count, plural, one {{countFormatted} Tūemi} other {{countFormatted} Ngā tūemi}}",
 	"components.pageable.info-with-total": "{totalCount, plural, one {{countFormatted} o {totalCountFormatted} Tūemi} other {{countFormatted} o {totalCountFormatted} Ngā tūemi}}",
 	"components.pager-load-more.status-loading": "Uta ana i ētahi atu tūemi",
-	"components.selection.action-max-hint": "{count, plural, one {Disabled when more than {countFormatted} item is selected} other {Disabled when more than {countFormatted} items are selected}}",
-	"components.selection.action-required-hint": "Select an item to perform this action",
+	"components.selection.action-max-hint": "{count, plural, one {Kua whakakorehia ina neke atu i te {countFormatted} o ngā tūemi i tīpakohia} other {Kua whakakorehia ina neke atu i te {countFormatted} o ngā tūemi i tīpakohia}}",
+	"components.selection.action-required-hint": "Tīpakohia tētahi tūemi hei whakahaere i tēnei mahi",
 	"components.selection.select-all": "Tīpako Katoa",
 	"components.selection.select-all-items": "Tīpakohia Ngā Tūemi {count} Katoa",
 	"components.selection.selected": "{count} kua tīpakohia",

package/package.json

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

package/components/form/docs/form.md

@@ -1,168 +0,0 @@
-# Form [d2l-form]
-
-<!-- docs: demo -->
-```html
-<script type="module">
-  import '@brightspace-ui/core/components/button/button.js';
-  import '@brightspace-ui/core/components/form/form.js';
-  import '@brightspace-ui/core/components/inputs/input-text.js';
-  import '@brightspace-ui/core/components/inputs/input-textarea.js';
-
-  const button = document.querySelector('d2l-button');
-  const form = document.querySelector('d2l-form#root');
-  button.addEventListener('click', () => {
-    form.submit();
-  });
-</script>
-<style>
-  .d2l-form-demo-container {
-    margin-bottom: 10px;
-  }
-</style>
-<d2l-form id="root" @d2l-form-submit=${this._onRootSubmit} style="width: 100%;">
-  <div class="d2l-form-demo-split-container">
-    <d2l-form class="d2l-form-demo-main" @d2l-form-submit=${this._onMainSubmit}>
-      <div class="d2l-form-demo-container">
-        <d2l-input-text label="Email" name="email" type="email"></d2l-input-text>
-      </div>
-      <div class="d2l-form-demo-container">
-        <d2l-input-textarea label="Description" name="description" rows="2" max-rows="2" required></d2l-input-textarea>
-      </div>
-    </d2l-form>
-  </div>
-	<d2l-button primary>Save</d2l-button>
-</d2l-form>
-```
-
-The `d2l-form` component can be used to build sections containing interactive controls that are validated and submitted as a group.
-
-It differs from the native HTML `form` element in 4 ways:
-1. It supports custom form elements made using the [`FormElementMixin`](./form-element-mixin.md) in addition to native form elements like `input`, `select` and `textarea`.
-1. Upon validation, it will display an error summary that contains error messages for any elements that failed validation.
-1. `d2l-form` elements can be nested. If a parent form is validated or submitted it will also trigger the corresponding action for descendent `d2l-form`s unless they explicitly opt-out using `no-nesting`. This means that a `d2l-form` will only pass validation if it and all of its nested descendants pass validation.
-1. Submission is not handled directly by `d2l-form`. Instead, all form data will be aggregated and passed back to the caller via an event. The caller is then responsible for submitting the data.
-
-<!-- docs: demo code properties name:d2l-form sandboxTitle:'Form' autoSize:false display:block size:large -->
-```html
-<script type="module">
-  import '@brightspace-ui/core/components/form/form.js';
-  import '@brightspace-ui/core/components/inputs/input-text.js';
-
-  const button = document.querySelector('button');
-  const form = document.querySelector('d2l-form#root');
-  button.addEventListener('click', () => {
-    form.submit();
-  });
-
-  const formA = document.querySelector('d2l-form#a');
-  const formB = document.querySelector('d2l-form#b');
-
-  function handleSubmission(e) {
-    const { formData } = e.detail;
-    console.log('Form ' + e.target.id + ' submission data ' + JSON.stringify(formData));
-  }
-  form.addEventListener('d2l-form-submit', (e) => handleSubmission(e));
-  formA.addEventListener('d2l-form-submit', (e) => handleSubmission(e));
-  formB.addEventListener('d2l-form-submit', (e) => handleSubmission(e));
-</script>
-<!-- docs: start hidden content -->
-<style>
-  d2l-input-text {
-    padding: 0.5rem 0;
-  }
-</style>
-<!-- docs: end hidden content -->
-<d2l-form id="root">
-  <select class="d2l-input-select" name="pets" required>
-    <option value="">--Please choose an option--</option>
-    <option value="porpoise">Porpoise</option>
-    <option value="house hippo">House Hippo</option>
-    <option value="spiker monkey">Spider Monkey</option>
-    <option value="capybara">Capybara</option>
-  </select>
-  <d2l-form id="a">
-    <d2l-input-text label="Name" type="text" name="name" required minlength="4"></d2l-input-text>
-  </d2l-form>
-  <d2l-form id="b" no-nesting>
-    <d2l-input-text required label="Email" name="email" type="email"></d2l-input-text>
-  </d2l-form>
-  <button name="action" value="save" type="submit">Save</button>
-</d2l-form>
-```
-
-<!-- docs: start hidden content -->
-### Properties
-
-| Property | Type | Description |
-|---|---|---|
-| `no-nesting` | Boolean, default: `false` | Indicates that the form should opt-out of nesting.<br><br>This means that it will not be submitted or validated if an ancestor form is submitted or validated. However, directly submitting or validating a form with `no-nesting` will still trigger submission and validation for its descendant forms unless they also opt-out using `no-nesting`. |
-
-### Events
-- `d2l-form-submit`: Dispatched when the form is submitted. The form data can be obtained from the `detail`'s `formData` property.
-- `d2l-form-invalid`: Dispatched when the form fails validation. The error map can be obtained from the `detail`'s `errors` property.
-- `d2l-form-dirty`: Dispatched whenever any form element fires an `input` or `change` event. Can be used to track whether the form is dirty or not.
-<!-- docs: end hidden content -->
-
-### Methods
-- `submit()`: Submits the form. This will first perform validation on all elements within the form including nested `d2l-form` elements.
-  - **Note:** If validation succeeds, the form data will be aggregated and passed back to the caller via the `d2l-form-submit` event. It will not be submitted by the form itself.
-- `resetValidation()`: Resets the validation errors. Note that this does not reset any form values. Daylight dialog components (e.g., `d2l-dialog`) will automatically run this method on close.
-- `async validate()`: Validates the form and any nested `d2l-form` elements without submitting even if validation succeeds for all elements. Returns a `Map` mapping from an element to the list of error messages associated with it.
-  - **Note:** The return value will include elements and errors from both the root form and any nested descendant forms.
-
-### Advanced Usages: Nesting
-
-`d2l-form` supports nesting by default meaning a `d2l-form` will discover descendant `d2l-form` elements. This includes *both*:
-1. `d2l-form` elements nested directly within the ancestor form's slot
-1. `d2l-form` elements contained within the shadow DOM of elements nested within the ancestor form's slot.
-
-Form nesting will only consider descendants relative to the `d2l-form` that `submit` or `validate` is called on. If `submit` is called on a `d2l-form` element, it will not trigger submission for any ancestor forms, only desdenants.
-
-- **Nested Validation:**
-  - When forms are nested, validation is _**atomic**_. This means that validation will only succeed if validation succeeds for the root form and all nested forms. If any form fails validation, none of them will be submitted.
-- **Nested Submission:**
-  - When forms are nested, submission is _**independent**_. As a result, when nested forms all pass validation, each `d2l-form` will fire its own `d2l-form-submit` event with the data associated with that form.
-
-```html
-<script type="module">
-  import '@brightspace-ui/core/components/form/form.js';
-</script>
-<d2l-form id="root">
-  <div>
-    <d2l-form id="a">
-      <d2l-input-text required label="Email" name="email" type="email"></d2l-input-text>
-      <select class="d2l-input-select" name="pets" required>
-        <option value="">--Please choose an option--</option>
-        <option value="porpoise">Porpoise</option>
-        <option value="house hippo">House Hippo</option>
-        <option value="spiker monkey">Spider Monkey</option>
-        <option value="capybara">Capybara</option>
-      </select>
-      <div>
-        <d2l-form id="b">
-          <d2l-input-text label="Description" type="text" name="description" required></d2l-input-text>
-        </d2l-form>
-      </div>
-    </d2l-form>
-  </div>
-  <d2l-form no-nesting id="c">
-    <d2l-input-text label="Name" type="text" name="name" required minlength="4"></d2l-input-text>
-  </d2l-form>
-  <my-ele-with-an-internal-d2l-form id="d">
-  </my-ele-with-an-internal-d2l-form>
-</d2l-form>
-```
-
-#### Example 1
-In the above example, calling `submit` on the `#root` form will cause forms `#root`, `#a`, `#b`, and `#d` to be validated and submitted.
-- `d2l-form#root` will be submitted because submit was called on it directly.
-- `d2l-form#a` will be submitted because it is nested directly within `#root`'s slot.
-- `d2l-form#b` will be submitted because it is nested within `#d2l-form#a` which was submitted.
-- The `d2l-form` within the shadow root of `#d` will be submitted because it is within the shadow DOM of an element nested directly within `#root`'s slot.
-- `d2l-form#c` will _**not**_ be submitted because it has the `no-nesting` attribute despite being nested directly within `#root's` slot.
-
-#### Example 2
-In the above example, calling `submit` on form `#a` will cause forms `#a` and `#b` to be validated and submitted.
-- `d2l-form#a` will be submitted because submit was called on it directly.
-- `d2l-form#b` will be submitted because it is nested directly within `#a`'s slot.
-- `d2l-form#root`, `d2l-form#c` and the `d2l-form` within the shadow root of `#d` will _**not**_ be submitted because they are ancestors of `#a` rather than descendants.