@brightspace-ui/core 2.137.3 → 2.138.0

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/skeleton/README.md

@@ -12,13 +12,7 @@ For example, this causes a text input to be skeletized:
 <d2l-input-text label="Name" skeleton></d2l-input-text>
 ```
 
-In a typical scenario, many skeleton-aware components would have their `skeleton` attributes bound to a single property on the host component, making it easy to toggle them all together:
-
-```html
-<d2l-input-text label="Name" ?skeleton="${this.skeleton}"></d2l-text-input>
-<d2l-input-date label="Due Date" ?skeleton="${this.skeleton}"></d2l-input-date>
-<my-element ?skeleton="${this.skeleton}"></my-element>
-```
+A parent component could contain several skeleton-aware components. In this case, the parent would extend [`SkeletonGroupMixin`](#skeleton-groups), which would automatically handle the skeleton state of its contents.
 
 ## Skeletizing Custom Elements with SkeletonMixin
 
@@ -133,6 +127,23 @@ For example:
 
 When skeletized, this heading will take up `45%` of the available width.
 
+## Skeleton groups
+Skeleton groups can be used to ensure a collection of components all appear at the same time. This can be used to prevent individual components from popping in before everything has loaded.
+
+```js
+import { SkeletonGroupMixin } from '@brightspace-ui/core/skeleton/skeleton-group-mixin.js';
+
+class MyElement extends SkeletonGroupMixin(LitElement) {
+
+  render() {
+    return html`
+      // Anything that can be skeletonized.
+      // All components will remain in skeleton state until they have all loaded
+    `;
+  }
+}
+```
+
 ## Future Enhancements
 
 Looking for an enhancement not listed here? Is there a core component that should support skeletons but doesn't yet? Create a GitHub issue!

package/components/skeleton/demo/skeleton-group-nested-test.js

@@ -0,0 +1,71 @@
+import '../../switch/switch.js';
+import './skeleton-group-test-wrapper.js';
+import './skeleton-test-box.js';
+import './skeleton-test-container.js';
+import './skeleton-test-heading.js';
+
+import { css, html, LitElement } from 'lit';
+import { SkeletonGroupMixin } from '../skeleton-group-mixin.js';
+
+class SkeletonTestNestedGroup extends SkeletonGroupMixin(LitElement) {
+	static get properties() {
+		return {
+			_skeletonParent: { state: true },
+			_skeletonContainer: { state: true },
+			_skeletonHeading: { state: true },
+		};
+	}
+	static get styles() {
+		return css`
+			.controls {
+				align-items: center;
+				display: flex;
+				gap: 0.6rem;
+				margin-bottom: 0.6rem;
+			}
+		`;
+	}
+
+	constructor() {
+		super();
+		this._skeletonParent = false;
+		this._skeletonContainer = false;
+		this._skeletonHeading = false;
+	}
+
+	render() {
+		return html`
+			<div class="controls">
+				<d2l-switch @click="${this._loadGroup}" ?on="${this._skeletonSetExplicitly}" text="parent skeleton"></d2l-switch>
+				<d2l-switch @click="${this._loadList}" ?on="${this._skeletonContainer}" text="container skeleton"></d2l-switch>
+				<d2l-switch @click="${this._loadInput}" ?on="${this._skeletonHeading}" text="heading skeleton"></d2l-switch>
+			</div>
+			<d2l-skeleton-group-test-wrapper>
+				<d2l-test-skeleton-heading level="1">Heading 1</d2l-test-skeleton-heading>
+				<d2l-skeleton-group-test-wrapper ?skeleton="${this._skeletonContainer}">
+					<d2l-test-skeleton-heading level="3" ?skeleton="${this._skeletonHeading}">Inner heading</d2l-test-skeleton-heading>
+					<d2l-test-skeleton-box></d2l-test-skeleton-box>
+				</d2l-skeleton-group-test-wrapper>
+				<d2l-skeleton-group-test-wrapper>
+					<d2l-test-skeleton-heading level="3">Heading 3</d2l-test-skeleton-heading>
+					<d2l-test-skeleton-container></d2l-test-skeleton-container>
+				</d2l-skeleton-group-test-wrapper>
+			</d2l-skeleton-group-test-wrapper>
+		`;
+	}
+
+	_loadGroup() {
+		this._skeletonParent = !this._skeletonParent;
+		this.skeleton = this._skeletonParent;
+	}
+
+	_loadInput() {
+		this._skeletonHeading = !this._skeletonHeading;
+	}
+
+	_loadList() {
+		this._skeletonContainer = !this._skeletonContainer;
+	}
+}
+customElements.define('d2l-test-nested-skeleton-group', SkeletonTestNestedGroup);
+

package/components/skeleton/demo/skeleton-group-test-wrapper.js

@@ -0,0 +1,9 @@
+import { html, LitElement } from 'lit';
+import { SkeletonGroupMixin } from '../skeleton-group-mixin.js';
+
+class SkeletonGroupTestWrapper extends SkeletonGroupMixin(LitElement) {
+	render() {
+		return html`<slot></slot>`;
+	}
+}
+customElements.define('d2l-skeleton-group-test-wrapper', SkeletonGroupTestWrapper);

package/components/skeleton/demo/skeleton-group-test.js

@@ -0,0 +1,91 @@
+import '../../switch/switch.js';
+import '../../button/button-subtle.js';
+import './skeleton-test-container.js';
+import { css, html, LitElement } from 'lit';
+import { SkeletonGroupMixin } from '../skeleton-group-mixin.js';
+
+class SkeletonTestGroup extends LitElement {
+	static get properties() {
+		return {
+			_items: { state: true },
+			_loadAsGroup: { state: true },
+		};
+	}
+	static get styles() {
+		return css`
+			.controls {
+				align-items: center;
+				display: flex;
+				gap: 0.6rem;
+				justify-content: space-between;
+				margin-bottom: 0.6rem;
+			}
+			d2l-test-skeleton-container {
+				margin-bottom: 0.6rem;
+			}
+		`;
+	}
+
+	constructor() {
+		super();
+		this._items = [1, 2, 3];
+		this._loadAsGroup = true;
+	}
+
+	render() {
+		return html`
+			<div class="controls">
+				<div>
+					<d2l-button-subtle @click="${this._loadItems}" text="Load items" icon="tier1:download"></d2l-button-subtle>
+					<d2l-button-subtle @click="${this._addItem}" text="Add item" icon="tier1:add"></d2l-button-subtle>
+					<d2l-button-subtle @click="${this._removeItem}" text="Remove item" icon="tier1:delete"></d2l-button-subtle>
+				</div>
+				<d2l-switch @click="${this._toggleLoadType}" text="Wait for all elements to load" ?on="${this._loadAsGroup}"></d2l-switch>
+			</div>
+
+			${this._loadAsGroup ? this._renderGroup() : this._renderIndividual() }
+		`;
+	}
+
+	_addItem() {
+		this._items.push((this._items.length + 1));
+		this.requestUpdate();
+	}
+
+	_loadItems() {
+		this._items.forEach(id => {
+			const item = this.shadowRoot.getElementById(id);
+			item.skeleton = true;
+			setTimeout(() => item.skeleton = false, Math.random() * 2000);
+		});
+	}
+
+	_removeItem() {
+		this._items.pop();
+		this.requestUpdate();
+	}
+
+	_renderContents() {
+		return html`
+			${this._items.map(item => html`<d2l-test-skeleton-container skeleton id="${item}"></d2l-test-skeleton-container>`)}
+		`;
+	}
+
+	_renderGroup() {
+		return html`<d2l-test-skeleton-group-on>${this._renderContents()}</d2l-test-skeleton-group-on>`;
+	}
+
+	_renderIndividual() {
+		return html`<div class="panels">${this._renderContents()}</div>`;
+	}
+
+	_toggleLoadType() {
+		this._loadAsGroup = !this._loadAsGroup;
+	}
+}
+customElements.define('d2l-test-skeleton-group', SkeletonTestGroup);
+
+class SkeletonTestGroupOn extends SkeletonGroupMixin(LitElement) {
+	render() { return html`<slot></slot>`; }
+}
+customElements.define('d2l-test-skeleton-group-on', SkeletonTestGroupOn);

package/components/skeleton/demo/skeleton-mixin.html

@@ -11,6 +11,8 @@
 			import './skeleton-test-heading.js';
 			import './skeleton-test-link.js';
 			import './skeleton-test-paragraph.js';
+			import './skeleton-group-nested-test.js';
+			import './skeleton-group-test.js';
 		</script>
 	</head>
 	<body unresolved>
@@ -62,6 +64,15 @@
 				<d2l-test-skeleton-container></d2l-test-skeleton-container>
 			</d2l-demo-snippet>
 
+			<h2>Skeleton group</h2>
+			<d2l-demo-snippet>
+				<d2l-test-skeleton-group></d2l-test-skeleton-group>
+			</d2l-demo-snippet>
+
+			<h2>Nested skeleton groups</h2>
+			<d2l-demo-snippet>
+				<d2l-test-nested-skeleton-group></d2l-test-nested-skeleton-group>
+			</d2l-demo-snippet>
 		</d2l-demo-page>
 	</body>
 </html>

package/components/skeleton/demo/skeleton-test-container.js

@@ -2,9 +2,9 @@ import '../../colors/colors.js';
 import '../../inputs/input-checkbox.js';
 import { css, html, LitElement } from 'lit';
 import { bodyCompactStyles } from '../../typography/styles.js';
-import { SkeletonMixin } from '../skeleton-mixin.js';
+import { SkeletonGroupMixin } from '../skeleton-group-mixin.js';
 
-export class SkeletonTestContainer extends SkeletonMixin(LitElement) {
+export class SkeletonTestContainer extends SkeletonGroupMixin(LitElement) {
 
 	static get styles() {
 		return [
@@ -36,7 +36,7 @@ export class SkeletonTestContainer extends SkeletonMixin(LitElement) {
 			<div class="d2l-demo-box d2l-skeletize-container">
 				<div class="d2l-skeletize">Container with Skeletons Inside</div>
 				<span class="d2l-body-compact">No skeleton</span>
-				<d2l-input-checkbox checked ?skeleton="${this.skeleton}">Skeleton</d2l-input-checkbox>
+				<d2l-input-checkbox checked>Skeleton</d2l-input-checkbox>
 			</div>
 		`;
 	}

package/components/skeleton/skeleton-group-mixin.js

@@ -0,0 +1,49 @@
+import { dedupeMixin } from '@open-wc/dedupe-mixin';
+import { SkeletonMixin } from './skeleton-mixin.js';
+import { SubscriberRegistryController } from '../../controllers/subscriber/subscriberControllers.js';
+
+export const SkeletonGroupMixin = dedupeMixin(superclass => class extends SkeletonMixin(superclass) {
+
+	static get properties() {
+		return {
+			_anySubscribersWithSkeletonActive : { state: true },
+		};
+	}
+
+	constructor() {
+		super();
+		this._anySubscribersWithSkeletonActive  = false;
+		this._skeletonSubscribers = new SubscriberRegistryController(this, 'skeleton', {
+			onSubscribe: this.onSubscriberChange.bind(this),
+			onUnsubscribe: this.onSubscriberChange.bind(this),
+			updateSubscribers: this._checkSubscribersSkeletonState.bind(this),
+		});
+	}
+
+	updated(changedProperties) {
+		super.updated(changedProperties);
+		if (changedProperties.has('skeleton')) {
+			this._skeletonSubscribers.updateSubscribers();
+		}
+	}
+
+	onSubscriberChange() {
+		this._skeletonSubscribers.updateSubscribers();
+	}
+
+	_checkSubscribersSkeletonState(subscribers) {
+		this._anySubscribersWithSkeletonActive = [...subscribers.values()].some(subscriber => (
+			subscriber._skeletonSetExplicitly || subscriber._anySubscribersWithSkeletonActive
+		));
+
+		this.setSkeletonActive(this._skeletonSetExplicitly || this._anySubscribersWithSkeletonActive || this._skeletonSetByParent);
+
+		subscribers.forEach(subscriber => {
+			subscriber.setSkeletonActive(this._skeletonActive);
+			subscriber.setSkeletonSetByParent(this._skeletonActive && !subscriber._skeletonSetExplicitly);
+		});
+
+		this._parentSkeleton?.registry?.onSubscriberChange();
+	}
+
+});

package/components/skeleton/skeleton-mixin.js

@@ -1,6 +1,7 @@
 import '../colors/colors.js';
 import { css } from 'lit';
 import { dedupeMixin } from '@open-wc/dedupe-mixin';
+import { EventSubscriberController } from '../../controllers/subscriber/subscriberControllers.js';
 import { RtlMixin } from '../../mixins/rtl/rtl-mixin.js';
 
 // DE50056: starting in Safari 16, the pulsing animation causes FACE
@@ -152,10 +153,10 @@ export const SkeletonMixin = dedupeMixin(superclass => class extends RtlMixin(su
 	static get properties() {
 		return {
 			/**
-			 * Renders the input as a [skeleton loader](https://github.com/BrightspaceUI/core/tree/main/components/skeleton)
+			 * Render the component as a [skeleton loader](https://github.com/BrightspaceUI/core/tree/main/components/skeleton).
 			 * @type {boolean}
 			 */
-			skeleton: { reflect: true, type: Boolean  }
+			skeleton: { reflect: true, type: Boolean },
 		};
 	}
 
@@ -167,7 +168,53 @@ export const SkeletonMixin = dedupeMixin(superclass => class extends RtlMixin(su
 
 	constructor() {
 		super();
-		this.skeleton = false;
+		this._skeletonSetByParent = false;
+		this._skeletonSetExplicitly = false;
+		this._skeletonActive = false;
+		this._skeletonWait = false;
+
+		this._parentSkeleton = new EventSubscriberController(this, 'skeleton', {
+			onSubscribe: this._onSubscribe.bind(this),
+			onUnsubscribe: this._onUnsubscribe.bind(this)
+		});
+	}
+
+	get skeleton() {
+		return this._skeletonActive;
+	}
+
+	set skeleton(val) {
+		const oldVal = this._skeletonSetExplicitly;
+		if (oldVal === val) return;
+		this._skeletonSetExplicitly = val;
+
+		// keep _skeletonActive aligned with _skeletonSetExplicitly. _skeletonActive may be modified separately by a parent SkeletonGroup
+		this._skeletonActive = val;
+
+		this.requestUpdate('skeleton', oldVal);
+		this._parentSkeleton?.registry?.onSubscriberChange();
+	}
+
+	setSkeletonActive(skeletonActive) {
+		const oldVal = this._skeletonActive;
+		if (skeletonActive !== oldVal) {
+			this._skeletonActive = skeletonActive;
+			this.requestUpdate('skeleton', oldVal);
+		}
+	}
+
+	setSkeletonSetByParent(skeletonSetByParent) {
+		this._skeletonSetByParent = skeletonSetByParent;
+	}
+
+	_onSubscribe() {
+		this._skeletonWait = true;
+	}
+
+	_onUnsubscribe() {
+		this._skeletonWait = false;
+		this._skeletonActive = this._skeletonSetExplicitly;
+		this.requestUpdate('skeleton', this._skeletonSetExplicitly);
 	}
 
 });

package/controllers/subscriber/subscriberControllers.js

@@ -115,6 +115,8 @@ export class SubscriberRegistryController extends BaseController {
 	}
 
 	_handleSubscribe(e) {
+		if (e.detail.subscriber === this._host) { return; }
+
 		e.stopPropagation();
 		e.detail.registry = this._host;
 		e.detail.registryController = this;
@@ -137,7 +139,9 @@ export class EventSubscriberController extends BaseSubscriber {
 	}
 
 	hostConnected() {
-		this._subscriptionComplete = this._keepTrying(() => this._subscribe(), 40, 400);
+		requestAnimationFrame(() => {
+			this._subscriptionComplete = this._keepTrying(() => this._subscribe(), 40, 400);
+		});
 	}
 
 	hostDisconnected() {