@brightspace-ui/core 2.90.0 → 2.91.0

package/components/filter/README.md

@@ -154,6 +154,7 @@ The filter will announce changes to filter selections, search results, and when
 
 ### Events
 * `d2l-filter-change`: dispatched when any filter value has changed (may contain info about multiple dimensions and multiple changes in each)
+* `d2l-filter-dimension-empty-state-action`: dispatched when an empty state action button is clicked
 * `d2l-filter-dimension-first-open`: dispatched when a dimension is opened for the first time (if there is only one dimension, this will be dispatched when the dropdown is first opened)
 * `d2l-filter-dimension-search`: dispatched when a dimension that supports searching and has the "manual" search-type is searched
 
@@ -259,6 +260,43 @@ Note that when using multiple filter dimensions, the counts should be updated wh
 </d2l-filter>
 ```
 
+## Dimension Set Empty State [d2l-filter-dimension-set-empty-state]
+
+The `d2l-filter-dimension-set-empty-state` component allows you to customize the empty state components that are rendered in [d2l-filter-dimension-set](#d2l-filter-dimension-set). When placed in the `d2l-filter-dimension-set` empty state slots, it will replace the component's default empty state. This component can be placed in either the `set-empty-state` or the `search-empty-state` slots.
+
+<!-- docs: demo live name:d2l-filter-dimension-set-empty-state autoOpen:true autoSize:false size:large -->
+```html
+<script type="module">
+  import '@brightspace-ui/core/components/filter/filter.js';
+  import '@brightspace-ui/core/components/filter/filter-dimension-set.js';
+  import '@brightspace-ui/core/components/filter/filter-dimension-set-empty-state.js';
+  import '@brightspace-ui/core/components/filter/filter-dimension-set-value.js';
+</script>
+<d2l-filter>
+  <d2l-filter-dimension-set key="course" text="Course" >
+    <d2l-filter-dimension-set-value key="art" text="Art" count="1" selected></d2l-filter-dimension-set-value>
+    <d2l-filter-dimension-set-value key="astronomy" text="Astronomy" count="3" disabled></d2l-filter-dimension-set-value>
+    <d2l-filter-dimension-set-value key="biology" text="Biology" count="5"></d2l-filter-dimension-set-value>
+    <d2l-filter-dimension-set-empty-state slot="search-empty-state" description="Search returned no results." action-text="Add a course"></d2l-filter-dimension-set-empty-state>
+    <d2l-filter-dimension-set-empty-state slot="set-empty-state" description="There are no available items." action-text="Add a course"></d2l-filter-dimension-set-empty-state>
+  </d2l-filter-dimension-set>
+</d2l-filter>
+<script>
+    document.querySelector('#filter-single').addEventListener('d2l-filter-dimension-empty-state-action', e => {
+            console.log(`Filter dimension empty state action clicked:\nkey: ${e.detail.key}\ntype: ${e.detail.type}`);
+        });
+</script>
+```
+<!-- docs: start hidden content -->
+### Properties
+
+| Property | Type | Description |
+|---|---|---|
+| `action-href` | String | The href that will be used for the empty state action. When set with action-text, d2l-filter will render a link action. |
+| `action-text` | String | The text that will be displayed in the empty state action. When set, d2l-filter renders a button action, or a link if action-href is also defined. |
+| `description` | String, required | The text that is displayed in the empty state description |
+<!-- docs: end hidden content -->
+
 ## Tags for Applied Filters [d2l-filter-tags]
 
 A tag-list allowing the user to see (and remove) the currently applied filters. Works with the `d2l-filter`. It supports hooking up to multiple filters.

package/components/filter/demo/filter.html

@@ -8,6 +8,7 @@
 		import '../../button/button.js';
 		import '../../filter/filter.js';
 		import '../../filter/filter-dimension-set.js';
+		import '../../filter/filter-dimension-set-empty-state.js';
 		import '../../filter/filter-dimension-set-value.js';
 		import './filter-search-demo.js';
 	</script>
@@ -22,7 +23,7 @@
 		<h2>Single Set Dimension</h2>
 		<d2l-demo-snippet>
 			<template>
-				<d2l-filter>
+				<d2l-filter id="filter-single">
 					<d2l-filter-dimension-set key="course" introductory-text="Filter content by courses. Start typing any course name to explore." text="Course" select-all>
 						<d2l-filter-dimension-set-value key="art" text="Art" count="12"></d2l-filter-dimension-set-value>
 						<d2l-filter-dimension-set-value key="astronomy" text="Astronomy" count="2" selected></d2l-filter-dimension-set-value>
@@ -35,6 +36,8 @@
 						<d2l-filter-dimension-set-value key="physics" text="Physics" count="23"></d2l-filter-dimension-set-value>
 						<d2l-filter-dimension-set-value key="stats" text="Statistics" count="333"></d2l-filter-dimension-set-value>
 						<d2l-filter-dimension-set-value key="writerscraft" text="Writer's Craft" count="2211"></d2l-filter-dimension-set-value>
+						<d2l-filter-dimension-set-empty-state slot="search-empty-state" description="Search returned no results." action-text="Do something"></d2l-filter-dimension-set-empty-state>
+						<d2l-filter-dimension-set-empty-state slot="set-empty-state" description="There are no available items." action-text="Add an item"></d2l-filter-dimension-set-empty-state>
 					</d2l-filter-dimension-set>
 				</d2l-filter>
 			</template>
@@ -70,6 +73,7 @@
 						<d2l-filter-dimension-set-value key="physics" text="Physics" count="1012"></d2l-filter-dimension-set-value>
 						<d2l-filter-dimension-set-value key="stats" text="Statistics" count="2"></d2l-filter-dimension-set-value>
 						<d2l-filter-dimension-set-value key="writerscraft" text="Writer's Craft"></d2l-filter-dimension-set-value>
+						<d2l-filter-dimension-set-empty-state slot="search-empty-state" description="Search returned no results." action-text="Do something" action-href="https://d2l.com/"></d2l-filter-dimension-set-empty-state>
 					</d2l-filter-dimension-set>
 					<d2l-filter-dimension-set key="role" text="Role">
 						<d2l-filter-dimension-set-value key="admin" text="Admin" count="0"></d2l-filter-dimension-set-value>
@@ -144,6 +148,10 @@
 			console.log(`Filter dimension opened for the first time: ${e.detail.key}`);
 		});
 
+		document.querySelector('#filter-single').addEventListener('d2l-filter-dimension-empty-state-action', e => {
+			console.log(`Filter dimension empty state action clicked:\nkey: ${e.detail.key}\ntype: ${e.detail.type}`);
+		});
+
 		requestAnimationFrame(() => {
 			document.getElementById('finish-loading').addEventListener('click', e => {
 				e.target.disabled = true;

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

@@ -0,0 +1,38 @@
+import { LitElement } from 'lit';
+
+/**
+ * A component to customize the empty state parameters for a particular filter-dimension-set.
+ * This component does not render anything, but instead gathers data needed for the d2l-filter.
+ */
+class FilterDimensionSetEmptyState extends LitElement {
+
+	static get properties() {
+		return {
+			/**
+			 * The href that will be used for the empty state action. When set with action-text, d2l-filter will render a link action.
+			 * @type {string}
+			 */
+			actionHref: { type: String, attribute: 'action-href' },
+			/**
+			 * The text that will be displayed in the empty state action. When set, d2l-filter renders a button action, or a link if action-href is also defined.
+			 * @type {string}
+			 */
+			actionText: { type: String, attribute: 'action-text' },
+			/**
+			 * REQUIRED: The text that is displayed in the empty state description
+			 * @type {string}
+			 */
+			description: { type: String }
+		};
+	}
+
+	constructor() {
+		super();
+		this.actionHref = '';
+		this.actionText = '';
+		this.description = '';
+	}
+
+}
+
+customElements.define('d2l-filter-dimension-set-empty-state', FilterDimensionSetEmptyState);

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

@@ -1,9 +1,16 @@
 import { html, LitElement } from 'lit';
 
+export const EmptyStateType = {
+	Search: 'search',
+	Set: 'set'
+};
+
 /**
  * A component to represent the main filter dimension type - a set of possible values that can be selected.
  * This component does not render anything, but instead gathers data needed for the d2l-filter.
  * @slot - For d2l-filter-dimension-set-value components
+ * @slot search-empty-state - The empty state that is displayed when the search returns no results
+ * @slot set-empty-state - The empty state that is displayed when the dimension-set has no values
  */
 class FilterDimensionSet extends LitElement {
 
@@ -61,6 +68,8 @@ class FilterDimensionSet extends LitElement {
 		this.selectionSingle = false;
 		this.text = '';
 		this.valueOnlyActiveFilterText = false;
+		this._searchEmptyStatesSlot = null;
+		this._setEmptyStatesSlot = null;
 		this._slot = null;
 	}
 
@@ -70,7 +79,11 @@ class FilterDimensionSet extends LitElement {
 	}
 
 	render() {
-		return html`<slot @slotchange="${this._handleSlotChange}"></slot>`;
+		return html`
+			<slot @slotchange="${this._handleSlotChange}"></slot>
+			<slot name="search-empty-state" @slotchange="${this._handleSearchEmptyStateSlotChange}"></slot>
+			<slot name="set-empty-state" @slotchange="${this._handleSetEmptyStateSlotChange}"></slot>
+		`;
 	}
 
 	updated(changedProperties) {
@@ -90,22 +103,15 @@ class FilterDimensionSet extends LitElement {
 		}
 	}
 
-	_dispatchDataChangeEvent(eventDetail) {
-		/** @ignore */
-		this.dispatchEvent(new CustomEvent('d2l-filter-dimension-data-change', {
-			detail: eventDetail,
-			bubbles: true,
-			composed: false
-		}));
+	getSearchEmptyState() {
+		return this._getEmptyState(this._searchEmptyStateSlot);
 	}
 
-	_getSlottedNodes() {
-		if (!this._slot) return [];
-		const nodes = this._slot.assignedNodes({ flatten: true });
-		return nodes.filter((node) => node.nodeType === Node.ELEMENT_NODE && node.tagName.toLowerCase() === 'd2l-filter-dimension-set-value');
+	getSetEmptyState() {
+		return this._getEmptyState(this._setEmptyStateSlot);
 	}
 
-	_getValues() {
+	getValues() {
 		const valueNodes = this._getSlottedNodes();
 		const values = valueNodes.map(value => {
 			return {
@@ -119,14 +125,51 @@ class FilterDimensionSet extends LitElement {
 		return values;
 	}
 
+	_dispatchDataChangeEvent(eventDetail) {
+		/** @ignore */
+		this.dispatchEvent(new CustomEvent('d2l-filter-dimension-data-change', {
+			detail: eventDetail,
+			bubbles: true,
+			composed: false
+		}));
+	}
+
+	_getEmptyState(emptyStateSlot) {
+		if (!emptyStateSlot) return null;
+		const nodes = emptyStateSlot.assignedNodes({ flatten: true });
+		const emptyState = nodes.find((node) => node.nodeType === Node.ELEMENT_NODE && node.tagName.toLowerCase() === 'd2l-filter-dimension-set-empty-state');
+		if (!emptyState) return null;
+		return {
+			actionHref: emptyState.actionHref,
+			actionText: emptyState.actionText,
+			description: emptyState.description
+		};
+	}
+
+	_getSlottedNodes() {
+		if (!this._slot) return [];
+		const nodes = this._slot.assignedNodes({ flatten: true });
+		return nodes.filter((node) => node.nodeType === Node.ELEMENT_NODE && node.tagName.toLowerCase() === 'd2l-filter-dimension-set-value');
+	}
+
 	_handleDimensionSetValueDataChange(e) {
 		e.stopPropagation();
 		this._dispatchDataChangeEvent({ dimensionKey: this.key, valueKey: e.detail.valueKey, changes: e.detail.changes });
 	}
 
+	_handleSearchEmptyStateSlotChange(e) {
+		if (!this._searchEmptyStateSlot) this._searchEmptyStateSlot = e.target;
+		this._dispatchDataChangeEvent({ dimensionKey: this.key, changes: new Map([['searchEmptyState', this.getSearchEmptyState()]]) });
+	}
+
+	_handleSetEmptyStateSlotChange(e) {
+		if (!this._setEmptyStateSlot) this._setEmptyStateSlot = e.target;
+		this._dispatchDataChangeEvent({ dimensionKey: this.key, changes: new Map([['setEmptyState', this.getSetEmptyState()]]) });
+	}
+
 	_handleSlotChange(e) {
 		if (!this._slot) this._slot = e.target;
-		const values = this._getValues();
+		const values = this.getValues();
 		this._dispatchDataChangeEvent({ dimensionKey: this.key, changes: new Map([['values', values]]) });
 	}
 

package/components/filter/filter.js

@@ -5,6 +5,8 @@ import '../button/button-subtle.js';
 import '../dropdown/dropdown-button-subtle.js';
 import '../dropdown/dropdown-content.js';
 import '../dropdown/dropdown-menu.js';
+import '../empty-state/empty-state-action-button.js';
+import '../empty-state/empty-state-action-link.js';
 import '../empty-state/empty-state-simple.js';
 import '../hierarchical-view/hierarchical-view.js';
 import '../inputs/input-search.js';
@@ -20,6 +22,7 @@ import { bodyCompactStyles, bodySmallStyles, bodyStandardStyles } from '../typog
 import { css, html, LitElement, nothing } from 'lit';
 import { announce } from '../../helpers/announce.js';
 import { classMap } from 'lit/directives/class-map.js';
+import { EmptyStateType } from './filter-dimension-set.js';
 import { FocusMixin } from '../../mixins/focus-mixin.js';
 import { formatNumber } from '@brightspace-ui/intl/lib/number.js';
 import { ifDefined } from 'lit/directives/if-defined.js';
@@ -37,6 +40,7 @@ const SET_DIMENSION_ID_PREFIX = 'list-';
  * This component is in charge of all rendering.
  * @slot - Dimension components used by the filter to construct the different dimensions locally
  * @fires d2l-filter-change - Dispatched when a dimension's value(s) have changed
+ * @fires d2l-filter-dimension-empty-state-action - Dispatched when an empty state action button is clicked
  * @fires d2l-filter-dimension-first-open - Dispatched when a dimension is opened for the first time
  * @fires d2l-filter-dimension-search - Dispatched when a dimension that supports searching and has the "manual" search-type is searched
  */
@@ -411,6 +415,35 @@ class Filter extends FocusMixin(LocalizeCoreElement(RtlMixin(LitElement))) {
 		`;
 	}
 
+	_createEmptyState(emptyState, dimensionKey, type) {
+		let emptyStateAction = nothing;
+		if (emptyState.actionText && emptyState.actionHref) {
+			emptyStateAction = html`
+				<d2l-empty-state-action-link
+					href="${emptyState.actionHref}"
+					text="${emptyState.actionText}">
+				</d2l-empty-state-action-link>
+			`;
+		}
+		else if (emptyState.actionText) {
+			emptyStateAction = html`
+				<d2l-empty-state-action-button
+					@d2l-empty-state-action="${this._handleEmptyStateAction}"
+					data-dimension-key="${dimensionKey}"
+					data-type="${type}"
+					text="${emptyState.actionText}">
+				</d2l-empty-state-action-button>
+			`;
+		}
+		return html`
+			<d2l-empty-state-simple
+				class="d2l-filter-dimension-info-message"
+				description="${emptyState.description}">
+				${emptyStateAction}
+			</d2l-empty-state-simple>
+		`;
+	}
+
 	_createSetDimension(dimension) {
 		if (dimension.loading) {
 			return html`
@@ -420,12 +453,17 @@ class Filter extends FocusMixin(LocalizeCoreElement(RtlMixin(LitElement))) {
 		}
 
 		if (this._isDimensionEmpty(dimension)) {
-			return html`
-				<div class="d2l-empty-state-container" role="alert">
+			const emptyState = dimension.setEmptyState
+				? this._createEmptyState(dimension.setEmptyState, dimension.key, EmptyStateType.Set)
+				: html`
 					<d2l-empty-state-simple
 						class="d2l-filter-dimension-info-message"
 						description="${this.localize('components.filter.noFilters')}">
 					</d2l-empty-state-simple>
+				`;
+			return html`
+				<div class="d2l-empty-state-container" role="alert">
+					${emptyState}
 				</div>
 			`;
 		}
@@ -437,13 +475,17 @@ class Filter extends FocusMixin(LocalizeCoreElement(RtlMixin(LitElement))) {
 				'd2l-empty-state-container': true,
 				'd2l-offscreen': count !== 0
 			};
-
-			searchResults = html`
-				<div class="${classMap(classes)}" role="alert">
+			const emptyState = dimension.searchEmptyState
+				? this._createEmptyState(dimension.searchEmptyState, dimension.key, EmptyStateType.Search)
+				: html`
 					<d2l-empty-state-simple
 						class="d2l-filter-dimension-info-message"
 						description="${this.localize('components.filter.searchResults', { number: count })}">
 					</d2l-empty-state-simple>
+				`;
+			searchResults =  html`
+				<div class="${classMap(classes)}" role="alert">
+					${emptyState}
 				</div>
 			`;
 
@@ -647,6 +689,14 @@ class Filter extends FocusMixin(LocalizeCoreElement(RtlMixin(LitElement))) {
 		this._stopPropagation(e);
 	}
 
+	_handleEmptyStateAction(e) {
+		this.dispatchEvent(new CustomEvent(
+			'd2l-filter-dimension-empty-state-action', {
+				detail: { key: e.target.getAttribute('data-dimension-key'), type: e.target.getAttribute('data-type') }
+			}
+		));
+	}
+
 	_handleSearch(e) {
 		const dimension = this._getActiveDimension();
 		const searchValue = e.detail.value.trim();
@@ -695,8 +745,10 @@ class Filter extends FocusMixin(LocalizeCoreElement(RtlMixin(LitElement))) {
 					info.searchType = dimension.searchType;
 					info.selectionSingle = dimension.selectionSingle;
 					if (dimension.selectAll && !dimension.selectionSingle) info.selectAllIdPrefix = SET_DIMENSION_ID_PREFIX;
+					info.searchEmptyState = dimension.getSearchEmptyState();
+					info.setEmptyState = dimension.getSetEmptyState();
 					info.valueOnlyActiveFilterText = dimension.valueOnlyActiveFilterText;
-					const values = dimension._getValues();
+					const values = dimension.getValues();
 					info.values = values;
 					break;
 				}

package/custom-elements.json

@@ -3493,6 +3493,54 @@
       "name": "d2l-filter-search-demo",
       "path": "./components/filter/demo/filter-search-demo.js"
     },
+    {
+      "name": "d2l-filter-dimension-set-empty-state",
+      "path": "./components/filter/filter-dimension-set-empty-state.js",
+      "description": "A component to customize the empty state parameters for a particular filter-dimension-set.\nThis component does not render anything, but instead gathers data needed for the d2l-filter.",
+      "attributes": [
+        {
+          "name": "action-href",
+          "description": "The href that will be used for the empty state action. When set with action-text, d2l-filter will render a link action.",
+          "type": "string",
+          "default": "\"\""
+        },
+        {
+          "name": "action-text",
+          "description": "The text that will be displayed in the empty state action. When set, d2l-filter renders a button action, or a link if action-href is also defined.",
+          "type": "string",
+          "default": "\"\""
+        },
+        {
+          "name": "description",
+          "description": "REQUIRED: The text that is displayed in the empty state description",
+          "type": "string",
+          "default": "\"\""
+        }
+      ],
+      "properties": [
+        {
+          "name": "actionHref",
+          "attribute": "action-href",
+          "description": "The href that will be used for the empty state action. When set with action-text, d2l-filter will render a link action.",
+          "type": "string",
+          "default": "\"\""
+        },
+        {
+          "name": "actionText",
+          "attribute": "action-text",
+          "description": "The text that will be displayed in the empty state action. When set, d2l-filter renders a button action, or a link if action-href is also defined.",
+          "type": "string",
+          "default": "\"\""
+        },
+        {
+          "name": "description",
+          "attribute": "description",
+          "description": "REQUIRED: The text that is displayed in the empty state description",
+          "type": "string",
+          "default": "\"\""
+        }
+      ]
+    },
     {
       "name": "d2l-filter-dimension-set-value",
       "path": "./components/filter/filter-dimension-set-value.js",
@@ -3677,6 +3725,14 @@
         {
           "name": "",
           "description": "For d2l-filter-dimension-set-value components"
+        },
+        {
+          "name": "search-empty-state",
+          "description": "The empty state that is displayed when the search returns no results"
+        },
+        {
+          "name": "set-empty-state",
+          "description": "The empty state that is displayed when the dimension-set has no values"
         }
       ]
     },
@@ -3829,6 +3885,10 @@
           "name": "d2l-filter-change",
           "description": "Dispatched when a dimension's value(s) have changed"
         },
+        {
+          "name": "d2l-filter-dimension-empty-state-action",
+          "description": "Dispatched when an empty state action button is clicked"
+        },
         {
           "name": "d2l-filter-dimension-first-open",
           "description": "Dispatched when a dimension is opened for the first time"

package/package.json

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