@brightspace-ui/core 2.137.2 → 2.137.4

package/components/filter/README.md

@@ -189,6 +189,7 @@ The `d2l-filter-dimension-set` component is the main dimension type that will wo
 
 | Property | Type | Description |
 |---|---|---|
+| `has-more` | Boolean | Whether the dimension has more values to load. Must be used with selected-first and manual search-type. |
 | `header-text` | String | A heading displayed above the list items. This is usually unnecessary, but can be used to emphasize or promote something specific about the list of items to help orient users. |
 | `introductory-text` | String | The introductory text to display at the top of the filter dropdown |
 | `key` | String, required | Unique identifier for the dimension |
@@ -232,6 +233,36 @@ This component is built to be used alongside the [d2l-filter-dimension-set](#d2l
 | `selected` | Boolean, default: `false` | Whether the value in the filter is selected or not |
 <!-- docs: end hidden content -->
 
+## Search and Paging
+
+Most filters will not need search or paging features since filter value lists are generally short. For longer lists of filter values when Search is necessary, it can be enabled by setting search-type to `automatic` or `manual`.
+
+`automatic` search runs a basic case-insensitive text comparison on the dimension values that are loaded in the browser, having no awareness of server-side values that are not yet loaded. 
+
+`manual` search dispatches a `d2l-filter-dimension-search` event delegating the search to the component's consumer. The event's detail will contain the key of the dimension from where the event was dispatched (`key`), the text value used for the search (`value`) and a callback (`searchCompleteCallback`). This callback gives the consumer control of which keys to display, either by setting `displayAllKeys` to `true` or passing a list of the keys to display as `keysToDisplay` (all other keys will be hidden). The dimension will be in a loading state until the callback is called.
+```js
+e.detail.searchCompleteCallback({ keysToDisplay: keysToDisplay });
+e.detail.searchCompleteCallback({ displayAllKeys: true });
+```
+
+As with Search, paging is often unnecessary since filter lists are generally short. For long lists of filter values, load-more paging can be enabled by setting `has-more` on a dimension set, which will display a `d2l-pager-load-more` button at the end of the values. Note however that paging requires the search type to be set to `manual`. Clicking the button replaces its text with a loading spinner and dispatches a `d2l-filter-dimension-load-more` event whose detail, like the search event, contains the dimension key (`key`), active search value (`value`) and a callback (`loadMoreCompleteCallback`) that works just like `searchCompleteCallback` described above. The pager will also be in a loading state until the callback is called.
+```js
+e.detail.loadMoreCompleteCallback({ keysToDisplay: keysToDisplay });
+e.detail.loadMoreCompleteCallback({ displayAllKeys: true });
+```
+
+### Selection and manual search/paging
+
+The filter component depends entirely on the consumer to include the selected filter values in order for the selected counts and `d2l-filter-tags` to display the correct values. Ideally, all values should be loaded into the dimensions and the event callbacks should be leveraged to set the visibility on those values. However, in the cases where this is not possible and new values are being added/removed manually from the dimension, then selection should be persisted. This means that selected items should always be loaded and included in the dimension and they should not be removed in order to maintain the functionality of counts and filter tags.
+<!-- docs: demo -->
+```html
+<script type="module">
+  import '@brightspace-ui/core/components/filter/demo/filter-load-more-demo.js'
+</script>
+<d2l-filter-load-more-demo>
+</d2l-filter-load-more-demo>
+```
+
 ## Counts
 
 The `count` property displays a count next to each filter value to indicate the number of results a value will yield. This helps users more effectively explore data and make selections, so it’s a good idea to provide these counts if it can be done performantly.

package/components/filter/filter-dimension-set.js

@@ -11,6 +11,11 @@ class FilterDimensionSet extends LitElement {
 
 	static get properties() {
 		return {
+			/**
+			 * Whether the dimension has more values to load. Manual search and selected first should be set if has more is being used
+			 * @type {boolean}
+			 */
+			hasMore: { type: Boolean, attribute: 'has-more' },
 			/**
 			 * A heading displayed above the list items. This is usually unnecessary, but can be used to emphasize or promote something specific about the list of items to help orient users.
 			 * @type {string}
@@ -31,11 +36,6 @@ class FilterDimensionSet extends LitElement {
 			 * @type {boolean}
 			 */
 			loading: { type: Boolean },
-			/**
-			 * Whether the dimension has more values to load
-			 * @type {boolean}
-			 */
-			hasMore: { type: Boolean, attribute: 'has-more' },
 			/**
 			 * Whether to hide the search input, perform a simple text search, or fire an event on search
 			 * @type {'none'|'automatic'|'manual'}
@@ -47,7 +47,7 @@ class FilterDimensionSet extends LitElement {
 			 */
 			selectAll: { type: Boolean, attribute: 'select-all' },
 			/**
-			 * Whether to render the selected items at the top of the filter
+			 * Whether to render the selected items at the top of the filter. Forced on if load more paging is being used
 			 * @type {boolean}
 			 */
 			selectedFirst: { type: Boolean, attribute: 'selected-first' },

package/components/inputs/demo/input-text.html

@@ -69,6 +69,13 @@
 				</template>
 			</d2l-demo-snippet>
 
+			<h2>Instructions</h2>
+			<d2l-demo-snippet>
+				<template>
+					<d2l-input-text label="Name" instructions="Use the keyboard to enter some sweet stuff... :)"></d2l-input-text>
+				</template>
+			</d2l-demo-snippet>
+
 			<h3>Invalid</h3>
 			<d2l-demo-snippet>
 				<template>

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

@@ -80,6 +80,7 @@ The `<d2l-input-text>` element is a simple wrapper around the native `<input typ
 | `description` | String | A description to be added to the `input` for accessibility |
 | `disabled` | Boolean | Disables the input |
 | `input-width` | String, default: `100%` | Restricts the maximum width of the input box without impacting the width of the label |
+| `instructions` | String | Additional information relating to how to use the component |
 | `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 |
 | `max` | String | For number inputs, maximum value |

package/components/inputs/input-date.js

@@ -242,7 +242,6 @@ class InputDate extends FocusMixin(LabelledMixin(SkeletonMixin(FormElementMixin(
 			? html`<d2l-icon icon="tier1:alert" slot="left" style="${styleMap({ color: 'var(--d2l-color-cinnabar)' })}"></d2l-icon>`
 			: html`<d2l-icon icon="tier1:calendar" slot="left"></d2l-icon>`;
 		const errorTooltip = (this.validationError && !this.opened && this.childErrors.size === 0) ? html`<d2l-tooltip align="start" announced for="${this._inputId}" state="error">${this.validationError}</d2l-tooltip>` : null;
-		const infoTooltip = (this._showInfoTooltip && !errorTooltip && !this.invalid && !this.disabled && this.childErrors.size === 0 && !this.skeleton && this._inputTextFocusShowTooltip) ? html`<d2l-tooltip align="start" announced delay="1000" for="${this._inputId}">${this.localize(`${this._namespace}.openInstructions`, { format: shortDateFormat })}</d2l-tooltip>` : null;
 
 		const dropdownContent = this._dropdownFirstOpened ? html`
 			<d2l-dropdown-content
@@ -276,7 +275,6 @@ class InputDate extends FocusMixin(LabelledMixin(SkeletonMixin(FormElementMixin(
 				<div>${this.emptyText}</div>
 			</div>
 			${errorTooltip}
-			${infoTooltip}
 			<d2l-dropdown ?disabled="${this.disabled || this.skeleton}" no-auto-open>
 				<d2l-input-text
 					?novalidate="${this.noValidate}"
@@ -284,6 +282,7 @@ class InputDate extends FocusMixin(LabelledMixin(SkeletonMixin(FormElementMixin(
 					@blur="${this._handleInputTextBlur}"
 					@change="${this._handleChange}"
 					class="d2l-dropdown-opener"
+					instructions="${ifDefined((this._showInfoTooltip && !errorTooltip && !this.invalid && this.childErrors.size === 0 && this._inputTextFocusShowTooltip) ? this.localize(`${this._namespace}.openInstructions`, { format: shortDateFormat }) : undefined)}"
 					description="${ifDefined(this.emptyText ? this.emptyText : undefined)}"
 					?disabled="${this.disabled}"
 					@focus="${this._handleInputTextFocus}"

package/components/inputs/input-text.js

@@ -68,6 +68,11 @@ class InputText extends FocusMixin(LabelledMixin(FormElementMixin(SkeletonMixin(
 			 * @type {string}
 			 */
 			inputWidth: { attribute: 'input-width', type: String },
+			/**
+			 * ADVANCED: Additional information relating to how to use the component
+			 * @type {string}
+			 */
+			instructions: { type: String, attribute: 'instructions' },
 			/**
 			 * Hides the label visually (moves it to the input's "aria-label" attribute)
 			 * @type {boolean}
@@ -461,8 +466,13 @@ class InputText extends FocusMixin(LabelledMixin(FormElementMixin(SkeletonMixin(
 		}
 
 		let tooltip = nothing;
-		if (this.validationError && !this.skeleton && !this.noValidate) {
-			tooltip = html`<d2l-tooltip state="error" announced align="start">${this.validationError} <span class="d2l-offscreen">${this.description}</span></d2l-tooltip>`;
+		if (!this.skeleton) {
+			if (this.validationError && !this.noValidate) {
+				// this tooltip is using "announced" since we don't want aria-describedby wire-up which would bury the message in VoiceOver's More Content Available menu
+				tooltip = html`<d2l-tooltip state="error" announced align="start">${this.validationError} <span class="d2l-offscreen">${this.description}</span></d2l-tooltip>`;
+			} else if (this.instructions) {
+				tooltip = html`<d2l-tooltip align="start" for="${this._inputId}" delay="1000">${this.instructions}</d2l-tooltip>`;
+			}
 		}
 
 		return html`${tooltip}${label}${input}`;

package/custom-elements.json

@@ -3827,7 +3827,7 @@
         },
         {
           "name": "has-more",
-          "description": "Whether the dimension has more values to load",
+          "description": "Whether the dimension has more values to load. Manual search and selected first should be set if has more is being used",
           "type": "boolean",
           "default": "false"
         },
@@ -3845,7 +3845,7 @@
         },
         {
           "name": "selected-first",
-          "description": "Whether to render the selected items at the top of the filter",
+          "description": "Whether to render the selected items at the top of the filter. Forced on if load more paging is being used",
           "type": "boolean",
           "default": "false"
         },
@@ -3899,7 +3899,7 @@
         {
           "name": "hasMore",
           "attribute": "has-more",
-          "description": "Whether the dimension has more values to load",
+          "description": "Whether the dimension has more values to load. Manual search and selected first should be set if has more is being used",
           "type": "boolean",
           "default": "false"
         },
@@ -3920,7 +3920,7 @@
         {
           "name": "selectedFirst",
           "attribute": "selected-first",
-          "description": "Whether to render the selected items at the top of the filter",
+          "description": "Whether to render the selected items at the top of the filter. Forced on if load more paging is being used",
           "type": "boolean",
           "default": "false"
         },
@@ -6574,6 +6574,11 @@
           "description": "Restricts the maximum width of the input box without impacting the width of the label.",
           "type": "string"
         },
+        {
+          "name": "instructions",
+          "description": "ADVANCED: Additional information relating to how to use the component",
+          "type": "string"
+        },
         {
           "name": "max",
           "description": "For number inputs, maximum value",
@@ -6741,6 +6746,12 @@
           "description": "Restricts the maximum width of the input box without impacting the width of the label.",
           "type": "string"
         },
+        {
+          "name": "instructions",
+          "attribute": "instructions",
+          "description": "ADVANCED: Additional information relating to how to use the component",
+          "type": "string"
+        },
         {
           "name": "max",
           "attribute": "max",

package/package.json

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