@brightspace-ui/core 2.137.4 → 2.138.0

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() {