@brightspace-ui/core 3.277.0 → 3.278.0

package/components/backdrop/backdrop-loading.js

@@ -1,10 +1,10 @@
+import './backdrop-stale-overlay.js';
 import '../colors/colors.js';
 import '../loading-spinner/loading-spinner.js';
-import './backdrop-dirty-overlay.js';
-import { css, html, LitElement, nothing } from 'lit';
+import { css, html, LitElement, nothing, unsafeCSS } from 'lit';
+import { freshness, FreshnessMixin } from '../../mixins/freshness/freshness-mixin.js';
 import { getComposedChildren, getComposedParent } from '../../helpers/dom.js';
 import { LocalizeCoreElement } from '../../helpers/localize-core-element.js';
-
 import { PropertyRequiredMixin } from '../../mixins/property-required/property-required-mixin.js';
 import { styleMap } from 'lit/directives/style-map.js';
 
@@ -12,7 +12,6 @@ const BACKDROP_DELAY_MS = 800;
 const FADE_DURATION_MS = 500;
 const SPINNER_DELAY_MS = FADE_DURATION_MS;
 const LOADING_ANNOUNCEMENT_DELAY = 1000;
-
 const LOADING_SPINNER_SIZE = 50;
 
 const reduceMotion = matchMedia('(prefers-reduced-motion: reduce)').matches;
@@ -20,56 +19,31 @@ const reduceMotion = matchMedia('(prefers-reduced-motion: reduce)').matches;
 /**
  * A component for displaying a semi-transparent backdrop and a loading spinner over the containing element
  */
-class LoadingBackdrop extends PropertyRequiredMixin(LocalizeCoreElement(LitElement)) {
+class BackdropLoading extends PropertyRequiredMixin(FreshnessMixin(LocalizeCoreElement(LitElement))) {
 
 	static properties = {
-		/**
-		 * The state of data in the element being overlaid. Set to 'clean' when the data represents the user's latest selections, 'dirty' when the data does not represent the user's latest selections, and 'loading' if the data is being actively refreshed
-		 * @type {'clean'|'dirty'|'loading'}
-		 */
-		dataState: {
-			reflect: true,
-			type: String
-		},
 		/**
 		 * Used to identify content that the backdrop should make inert
 		 * @type {string}
 		 */
 		for: { type: String, required: true },
-		/**
-		 * The text displayed on the dirty state overlay when the 'dirty' dataState is set.
-		 * @type {string}
-		 */
-		dirtyText: {
-			reflect: true,
-			attribute: 'dirty-text',
-			type: String
-		},
-		/**
-		 * The text displayed on the button of the dirty state overlay when the 'dirty' dataState is set.
-		 * @type {string}
-		 */
-		dirtyButtonText: {
-			reflect: true,
-			attribute: 'dirty-button-text',
-			type: String
-		},
-		_state: { type: String, reflect: true },
-		_spinnerTop: { state: true },
-		_ariaContent: { state: true }
+		_ariaContent: { state: true },
+		_loadingSpinnerTop: { state: true },
+		_staleOverlayTop: { state: true },
+		_state: { type: String, reflect: true }
 	};
 
 	static styles = [css`
-		#visible {
+		.backdrop-container {
 			display: none;
 		}
 
 		:host([_state="showing"]),
 		:host([_state="shown"]),
 		:host([_state="hiding"]),
-		:host([_state="showing"]) #visible,
-		:host([_state="shown"]) #visible,
-		:host([_state="hiding"]) #visible {
+		:host([_state="showing"]) .backdrop-container,
+		:host([_state="shown"]) .backdrop-container,
+		:host([_state="hiding"]) .backdrop-container {
 			display: flex;
 			inset: 0;
 			justify-content: center;
@@ -99,13 +73,13 @@ class LoadingBackdrop extends PropertyRequiredMixin(LocalizeCoreElement(LitEleme
 			opacity: 1;
 			transition: opacity ${FADE_DURATION_MS}ms ease-in ${SPINNER_DELAY_MS}ms;
 		}
-		:host([_state="shown"][dataState="dirty"]) d2l-loading-spinner,
+		:host([_state="shown"][freshness="${unsafeCSS(freshness.stale)}"]) d2l-loading-spinner,
 		:host([_state="hiding"]) d2l-loading-spinner {
 			opacity: 0;
 			transition: opacity ${FADE_DURATION_MS}ms ease-out;
 		}
 
-		d2l-backdrop-dirty-overlay {
+		d2l-backdrop-stale-overlay {
 			background-color: var(--d2l-theme-backdrop-dialog-color);
 			height: fit-content;
 			justify-content: center;
@@ -114,12 +88,12 @@ class LoadingBackdrop extends PropertyRequiredMixin(LocalizeCoreElement(LitEleme
 			top: 0;
 			z-index: 1000;
 		}
-		:host([_state="shown"]) d2l-backdrop-dirty-overlay {
+		:host([_state="shown"]) d2l-backdrop-stale-overlay {
 			opacity: 1;
 			transition: opacity ${FADE_DURATION_MS}ms ease-in;
 		}
-		:host([_state="shown"][dataState="loading"]) d2l-backdrop-dirty-overlay,
-		:host([_state="hiding"]) d2l-backdrop-dirty-overlay {
+		:host([_state="shown"][freshness="${unsafeCSS(freshness.loading)}"]) d2l-backdrop-stale-overlay,
+		:host([_state="hiding"]) d2l-backdrop-stale-overlay {
 			opacity: 0;
 			transition: opacity ${FADE_DURATION_MS}ms ease-out;
 		}
@@ -131,46 +105,46 @@ class LoadingBackdrop extends PropertyRequiredMixin(LocalizeCoreElement(LitEleme
 
 	constructor() {
 		super();
-		this.dataState = 'clean';
-		this._state = 'hidden';
-		this._spinnerTop = 0;
-		this._dirtyDialogTop = 0;
 		this._ariaContent = '';
+		this._loadingSpinnerTop = 0;
+		this._staleOverlayTop = 0;
+		this._state = 'hidden';
 	}
 
 	render() {
 		const backdropVisible = this._state !== 'hidden';
 
+		const backdropContainer = backdropVisible ? html`<div class="backdrop-container">
+			<div class="backdrop" @transitionend="${this.#handleTransitionEnd}" @transitioncancel="${this.#handleTransitionEnd}"></div>
+			<d2l-loading-spinner style="${styleMap({ top: `${this._loadingSpinnerTop}px` })}" size="${LOADING_SPINNER_SIZE}"></d2l-loading-spinner>
+		</div>` : nothing;
+
+		const backdropStaleOverlay = backdropVisible ? html`<d2l-backdrop-stale-overlay
+			button-text="${this.freshnessStaleButtonText}"
+			text="${this.freshnessStaleText}"
+			?inert="${this.freshness !== freshness.stale}"
+			style="${styleMap({ top: `${this._staleOverlayTop}px` })}">
+		</d2l-backdrop-stale-overlay>` : nothing;
+
 		return html`
-			${backdropVisible ?
-					html`<div id="visible">
-						<div class="backdrop" @transitionend="${this.#handleTransitionEnd}" @transitioncancel="${this.#handleTransitionEnd}"></div>
-						<d2l-loading-spinner style=${styleMap({ top: `${this._spinnerTop}px` })} size="${LOADING_SPINNER_SIZE}"></d2l-loading-spinner>
-					</div>` : nothing
-			}
-			<div aria-live="polite" id="d2l-live-region">
-				${backdropVisible ?
-					html`<d2l-backdrop-dirty-overlay
-						style=${styleMap({ top: `${this._dirtyDialogTop}px` })}
-						description="${this.dirtyText}"
-						action="${this.dirtyButtonText}"
-						?inert=${this.dataState !== 'dirty'}
-					></d2l-backdrop-dirty-overlay>` : nothing }
-				<d2l-offscreen>
-					${this._ariaContent}
-				</d2l-offscreen>
+			${backdropContainer}
+			<div aria-live="polite" class="backdrop-stale-container">
+				${backdropStaleOverlay}
+				<d2l-offscreen>${this._ariaContent}</d2l-offscreen>
 			</div>
 		`;
 	}
+
 	updated(changedProperties) {
-		if (changedProperties.get('_state') && changedProperties.get('_state') === 'hidden')
-		{
-			this.#centerLoadingSpinnerAndDialog();
+		super.updated(changedProperties);
+
+		if (changedProperties.get('_state') && changedProperties.get('_state') === 'hidden') {
+			this.#updatePosition();
 		}
 
 		if (changedProperties.has('_state')) {
 			if (this._state === 'showing') {
-				if (this.dataState === 'loading') {
+				if (this.freshness === freshness.loading) {
 					setTimeout(() => {
 						if (this._state === 'showing') this._state = 'shown';
 					}, BACKDROP_DELAY_MS);
@@ -180,26 +154,27 @@ class LoadingBackdrop extends PropertyRequiredMixin(LocalizeCoreElement(LitEleme
 			}
 		}
 	}
+
 	willUpdate(changedProperties) {
-		if (changedProperties.has('dataState') && changedProperties.get('dataState') !== undefined) {
-			this.#clearLiveArea();
+		super.willUpdate(changedProperties);
 
-			const oldState = changedProperties.get('dataState');
-			const newState = this.dataState;
+		if (changedProperties.has('freshness') && changedProperties.get('freshness') !== undefined) {
+			this.#clearLiveRegionContent();
 
-			// Calculate announcements
-			if (newState === 'loading') {
-				this.#setLiveArea(this.localize('components.backdrop-loading.loadingAnnouncement'), { delay: LOADING_ANNOUNCEMENT_DELAY });
-			} else if (oldState === 'loading' && newState === 'clean') {
-				this.#setLiveArea(this.localize('components.backdrop-loading.loadingCompleteAnnouncement'));
+			const oldState = changedProperties.get('freshness');
+			const newState = this.freshness;
+
+			if (newState === freshness.loading) {
+				this.#setLiveRegionContent(this.localize('components.backdrop-loading.loadingAnnouncement'), { delay: LOADING_ANNOUNCEMENT_DELAY });
+			} else if (oldState === freshness.loading && newState === freshness.fresh) {
+				this.#setLiveRegionContent(this.localize('components.backdrop-loading.loadingCompleteAnnouncement'));
 			}
 
-			// Update backdrop
-			if (oldState === 'clean') {
+			if (oldState === freshness.fresh) {
 				this.#show();
-			} else if (newState === 'clean') {
+			} else if (newState === freshness.fresh) {
 				this.#fade();
-			} else if (oldState === 'loading' && newState === 'dirty') {
+			} else if (oldState === freshness.loading && newState === freshness.stale) {
 				setTimeout(() => {
 					if (this._state === 'showing') this._state = 'shown';
 				}, BACKDROP_DELAY_MS);
@@ -207,52 +182,19 @@ class LoadingBackdrop extends PropertyRequiredMixin(LocalizeCoreElement(LitEleme
 		}
 	}
 
-	async #centerLoadingSpinnerAndDialog() {
-		if (this._state === 'hidden') { return; }
-
-		const loadingSpinner = this.shadowRoot.querySelector('d2l-loading-spinner');
-		if (!loadingSpinner) { return; }
-
-		const boundingRect = this.shadowRoot.querySelector('#visible').getBoundingClientRect();
-
-		// Calculate the centerpoint of the visible portion of the element
-		const upperVisibleBound = Math.max(0, boundingRect.top);
-		const lowerVisibleBound = Math.min(window.innerHeight, boundingRect.bottom);
-		const visibleHeight = lowerVisibleBound - upperVisibleBound;
-		const centeringOffset = (visibleHeight / 4);
-
-		// Calculate if an offset is required to move to the top of the viewport before centering
-		const topOffset = Math.max(0, -boundingRect.top); // measures the distance below the top of the viewport, which is negative if the element starts above the viewport
-
-		// Adjust for the size of the spinner
-		const spinnerSizeOffset = LOADING_SPINNER_SIZE / 2;
-
-		this._spinnerTop = centeringOffset + topOffset - spinnerSizeOffset;
+	#announcementTimeoutId;
 
-		// Adjust for the size of the dirty dialog
-		const dirtyOverlay = this.shadowRoot.querySelector('d2l-backdrop-dirty-overlay');
-		if (dirtyOverlay) {
-			await this.shadowRoot.querySelector('d2l-empty-state-action-button')?.getUpdateComplete();
-			const dirtyDialogSizeOffset = dirtyOverlay.getBoundingClientRect().height / 2;
-
-			this._dirtyDialogTop = centeringOffset + topOffset - dirtyDialogSizeOffset;
-		}
-	}
-
-	#clearLiveArea() {
+	#clearLiveRegionContent() {
 		this._ariaContent = '';
 
-		if (this.announcementTimeout) {
-			clearTimeout(this.announcementTimeout);
-		}
-
-		this.announcementTimeout = null;
+		if (this.#announcementTimeoutId) clearTimeout(this.#announcementTimeoutId);
+		this.#announcementTimeoutId = null;
 	}
 
 	#fade() {
 		let hideImmediately = reduceMotion || this._state === 'showing';
 		if (this._state === 'shown') {
-			const currentOpacity = getComputedStyle(this.shadowRoot.querySelector('#d2l-live-region')).opacity;
+			const currentOpacity = getComputedStyle(this.shadowRoot.querySelector('.backdrop-stale-container')).opacity;
 			hideImmediately ||= (currentOpacity === '0');
 		}
 
@@ -266,14 +208,10 @@ class LoadingBackdrop extends PropertyRequiredMixin(LocalizeCoreElement(LitEleme
 	#getBackdropTarget() {
 		const parent = getComposedParent(this);
 
-		const targetedChildren = getComposedChildren(
-			parent,
-			(elem) => elem.id === this.for,
-			false
-		);
-
-		if (targetedChildren.length === 0) { throw new Error(`Backdrop cannot find sibling identified by 'for' property with value ${this.for}`);}
-
+		const targetedChildren = getComposedChildren(parent, (elem) => elem.id === this.for, false);
+		if (targetedChildren.length === 0) {
+			throw new Error(`Backdrop cannot find sibling identified by 'for' property with value ${this.for}`);
+		}
 		return targetedChildren[0];
 	}
 
@@ -287,24 +225,53 @@ class LoadingBackdrop extends PropertyRequiredMixin(LocalizeCoreElement(LitEleme
 		this._state = 'hidden';
 
 		const containingBlock = this.#getBackdropTarget();
-
 		if (containingBlock.dataset.initiallyInert !== '1') containingBlock.removeAttribute('inert');
 	}
 
-	#setLiveArea(content, { delay } = {}) {
-		this.announcementTimeout = setTimeout(() => this._ariaContent = content, delay || 0);
+	#setLiveRegionContent(content, { delay } = {}) {
+		this.#announcementTimeoutId = setTimeout(() => this._ariaContent = content, delay || 0);
 	}
 
 	#show() {
 		this._state = reduceMotion ? 'shown' : 'showing';
 
 		const containingBlock = this.#getBackdropTarget();
-
 		if (containingBlock.getAttribute('inert') !== null) containingBlock.dataset.initiallyInert = '1';
-
 		containingBlock.setAttribute('inert', 'inert');
 	}
 
+	async #updatePosition() {
+		if (this._state === 'hidden') return;
+
+		const loadingSpinner = this.shadowRoot.querySelector('d2l-loading-spinner');
+		if (!loadingSpinner) return;
+
+		const backdropContainerRect = this.shadowRoot.querySelector('.backdrop-container').getBoundingClientRect();
+
+		// Calculate the centerpoint of the visible portion of the element
+		const upperVisibleBound = Math.max(0, backdropContainerRect.top);
+		const lowerVisibleBound = Math.min(window.innerHeight, backdropContainerRect.bottom);
+		const visibleHeight = lowerVisibleBound - upperVisibleBound;
+		const centeringOffset = (visibleHeight / 4);
+
+		// Calculate if an offset is required to move to the top of the viewport before centering
+		const topOffset = Math.max(0, -backdropContainerRect.top); // measures the distance below the top of the viewport, which is negative if the element starts above the viewport
+
+		// Adjust for the size of the spinner
+		const spinnerSizeOffset = LOADING_SPINNER_SIZE / 2;
+
+		this._loadingSpinnerTop = centeringOffset + topOffset - spinnerSizeOffset;
+
+		// Adjust for the size of the stale overlay
+		const staleOverlay = this.shadowRoot.querySelector('d2l-backdrop-stale-overlay');
+		if (staleOverlay) {
+			await this.shadowRoot.querySelector('d2l-empty-state-action-button')?.getUpdateComplete();
+			const staleOverlaySizeOffset = staleOverlay.getBoundingClientRect().height / 2;
+
+			this._staleOverlayTop = centeringOffset + topOffset - staleOverlaySizeOffset;
+		}
+	}
+
 }
 
-customElements.define('d2l-backdrop-loading', LoadingBackdrop);
+customElements.define('d2l-backdrop-loading', BackdropLoading);

package/components/backdrop/backdrop-stale-overlay.js

@@ -0,0 +1,58 @@
+import '../button/button-subtle.js';
+import { css, html, LitElement } from 'lit';
+import { bodyCompactStyles } from '../typography/styles.js';
+import { LocalizeCoreElement } from '../../helpers/localize-core-element.js';
+
+/**
+ * A component to render as an overlay over another element with stale data.
+ */
+class BackdropStaleOverlay extends LocalizeCoreElement(LitElement) {
+
+	static properties = {
+		/**
+		 * The action button text
+		 * @type {string}
+		 */
+		buttonText: { type: String, attribute: 'button-text' },
+		/**
+		 * The text displayed on the overlay
+		 * @type {string}
+		 */
+		text: { type: String }
+	};
+
+	static styles = [bodyCompactStyles, css`
+		:host {
+			align-items: center;
+			border: 1px solid var(--d2l-color-mica);
+			border-radius: 0.3rem;
+			column-gap: 0.75rem;
+			display: flex;
+			flex-wrap: wrap;
+			padding: 1.2rem 1.5rem;
+		}
+	`];
+
+	render() {
+		const message = this.text || this.localize('components.backdrop-stale-overlay.message');
+		const buttonText = this.buttonText || this.localize('intl-common:actions:reload');;
+
+		return html`
+			<p class="d2l-body-compact">${message}</p>
+			<d2l-button-subtle
+				@click="${this.#handleActionClick}"
+				text="${buttonText}">
+			</d2l-button-subtle>
+		`;
+	}
+
+	#handleActionClick(e) {
+		e.stopPropagation();
+
+		/** Dispatched when the action button on the overlay is clicked */
+		this.dispatchEvent(new CustomEvent('d2l-backdrop-stale-overlay-action', { bubbles: true, composed: true }));
+	}
+
+}
+
+customElements.define('d2l-backdrop-stale-overlay', BackdropStaleOverlay);

package/components/table/demo/table-test.js

@@ -18,7 +18,7 @@ import '../../inputs/input-radio.js';
 import '../../inputs/input-radio-group.js';
 
 import { css, html, nothing } from 'lit';
-import { tableStyles, TableWrapper } from '../table-wrapper.js';
+import { tableFreshness, tableStyles, TableWrapper } from '../table-wrapper.js';
 import { DemoPassthroughMixin } from '../../demo/demo-passthrough-mixin.js';
 import { ifDefined } from 'lit/directives/if-defined.js';
 
@@ -83,12 +83,12 @@ class TestTable extends DemoPassthroughMixin(TableWrapper, 'd2l-table-wrapper')
 		this._data = data();
 		this._sortField = undefined;
 		this._sortDesc = false;
-		this.dataState = 'clean';
+		this.freshness = tableFreshness.fresh;
 	}
 
 	render() {
 		return html`
-			<d2l-table-wrapper item-count="${ifDefined(this.paging ? 500 : undefined)}" dirty-text="This text indicates we're in the dirty state" dirty-button-text="Refresh">
+			<d2l-table-wrapper item-count="${ifDefined(this.paging ? 500 : undefined)}" freshness-stale-text="This table data is out of date." freshness-stale-button-text="Reload Me!">
 				<d2l-table-controls slot="controls" ?no-sticky="${!this.stickyControls}" select-all-pages-allowed>
 					<d2l-selection-action
 						text="Sticky controls"
@@ -100,10 +100,10 @@ class TestTable extends DemoPassthroughMixin(TableWrapper, 'd2l-table-wrapper')
 						icon="tier1:${this.stickyHeaders ? 'check' : 'close-default'}"
 						@d2l-selection-action-click="${this._toggleStickyHeaders}">
 					</d2l-selection-action>
-					<d2l-input-radio-group label="Date State" horizontal label-hidden name="dataState" @change=${this._handleDataStateChange}>
-						<d2l-input-radio label="Clean" value="clean" ?checked=${this.dataState === 'clean'}></d2l-input-radio>
-						<d2l-input-radio label="Dirty" value="dirty" ?checked=${this.dataState === 'dirty'}></d2l-input-radio>
-						<d2l-input-radio label="Loading" value="loading" ?checked=${this.dataState === 'loading'}></d2l-input-radio>
+					<d2l-input-radio-group label="Freshness" horizontal label-hidden name="freshness" @change=${this._handleFreshnessChange}>
+						<d2l-input-radio label="Fresh" value="${tableFreshness.fresh}" ?checked=${this.freshness === tableFreshness.fresh}></d2l-input-radio>
+						<d2l-input-radio label="Stale" value="${tableFreshness.stale}" ?checked=${this.freshness === tableFreshness.stale}></d2l-input-radio>
+						<d2l-input-radio label="Loading" value="${tableFreshness.loading}" ?checked=${this.freshness === tableFreshness.loading}></d2l-input-radio>
 					</d2l-input-radio-group>
 				</d2l-table-controls>
 
@@ -170,8 +170,8 @@ class TestTable extends DemoPassthroughMixin(TableWrapper, 'd2l-table-wrapper')
 		`;
 	}
 
-	_handleDataStateChange(e) {
-		this.dataState = e.detail.value;
+	_handleFreshnessChange(e) {
+		this.freshness = e.detail.value;
 	}
 
 	async _handlePagerLoadMore(e) {

package/components/table/table-wrapper.js

@@ -2,13 +2,15 @@ import '../colors/colors.js';
 import '../scroll-wrapper/scroll-wrapper.js';
 import '../backdrop/backdrop-loading.js';
 import { css, html, LitElement, nothing } from 'lit';
+import { freshness, FreshnessMixin } from '../../mixins/freshness/freshness-mixin.js';
 import { cssSizes } from '../inputs/input-checkbox-styles.js';
 import { getComposedParent } from '../../helpers/dom.js';
 import { isPopoverSupported } from '../popover/popover-mixin.js';
 import { PageableMixin } from '../paging/pageable-mixin.js';
-import { PropertyRequiredMixin } from '../../mixins/property-required/property-required-mixin.js';
 import { SelectionMixin } from '../selection/selection-mixin.js';
 
+export const tableFreshness = freshness;
+
 export const tableStyles = css`
 	.d2l-table {
 		border-collapse: separate; /* needed to override reset stylesheets */
@@ -263,9 +265,24 @@ const SELECTORS = {
  * @slot controls - Slot for `d2l-table-controls` to be rendered above the table
  * @slot pager - Slot for `d2l-pager-load-more` to be rendered below the table
  */
-export class TableWrapper extends PropertyRequiredMixin(PageableMixin(SelectionMixin(LitElement))) {
+export class TableWrapper extends FreshnessMixin(PageableMixin(SelectionMixin(LitElement))) {
 
 	static properties = {
+		/**
+		 * Todo: remove once consumers are updated to freshness. Use freshness instead.
+		 * @ignore
+		 */
+		dataState: { reflect: true, type: String },
+		/**
+		 * Todo: remove once consumers are updated to freshness-stale-text. Use freshness-stale-text instead.
+		 * @ignore
+		 */
+		dirtyText: { reflect: true, attribute: 'dirty-text', type: String },
+		/**
+		 * Todo: remove once consumers are updated to freshness-stale-button-text. Use freshness-stale-button-text instead.
+		 * @ignore
+		 */
+		dirtyButtonText: { reflect: true, attribute: 'dirty-button-text', type: String },
 		/**
 		 * Hides the column borders on "default" table type
 		 * @type {boolean}
@@ -307,40 +324,6 @@ export class TableWrapper extends PropertyRequiredMixin(PageableMixin(SelectionM
 			attribute: '_no-scroll-width',
 			reflect: true,
 			type: Boolean,
-		},
-		/**
-		 * The state of data in the table. Set to 'clean' when the data represents the user's latest selections, 'dirty' when the data does not represent the user's latest selections, and 'loading' if the data is being actively refreshed
-		 * @type {'clean'|'dirty'|'loading'}
-		 */
-		dataState: {
-			reflect: true,
-			type: String
-		},
-		/**
-		 * The text displayed on the dirty state overlay when the 'dirty' dataState is set.
-		 * @type {string}
-		 */
-		dirtyText: {
-			reflect: true,
-			attribute: 'dirty-text',
-			required: {
-				dependentProps: ['dataState'],
-				validator: (_value, elem, hasValue) => hasValue || elem.dataState !== 'dirty'
-			},
-			type: String
-		},
-		/**
-		 * The text displayed on the button dirty state overlay when the 'dirty' dataState is set.
-		 * @type {string}
-		 */
-		dirtyButtonText: {
-			reflect: true,
-			attribute: 'dirty-button-text',
-			required: {
-				dependentProps: ['dataState'],
-				validator: (_value, elem, hasValue) => hasValue || elem.dataState !== 'dirty'
-			},
-			type: String
 		}
 	};
 
@@ -409,10 +392,6 @@ export class TableWrapper extends PropertyRequiredMixin(PageableMixin(SelectionM
 		this._tableIntersectionObserver = null;
 		this._tableMutationObserver = null;
 		this._tableScrollers = {};
-		this.dataState = 'clean';
-
-		this.dirtyText = null;
-		this.dirtyButtonText = null;
 	}
 
 	connectedCallback() {
@@ -444,7 +423,7 @@ export class TableWrapper extends PropertyRequiredMixin(PageableMixin(SelectionM
 		const slot = html`
 			<div style="position:relative">
 				<slot id="table-slot" @slotchange="${this._handleSlotChange}"></slot>
-				<d2l-backdrop-loading @d2l-backdrop-dirty-overlay-action=${this._handleDirtyButton} for="table-slot" dataState=${this.dataState} dirty-text="${this.dirtyText}" dirty-button-text="${this.dirtyButtonText}"></d2l-backdrop-loading>
+				<d2l-backdrop-loading @d2l-backdrop-stale-overlay-action="${this._handleStaleButton}" for="table-slot" freshness="${this.freshness}" freshness-stale-text="${this.freshnessStaleText}" freshness-stale-button-text="${this.freshnessStaleButtonText}"></d2l-backdrop-loading>
 			</div>
 		`;
 		const useScrollWrapper = this.stickyHeadersScrollWrapper || !this.stickyHeaders;
@@ -469,6 +448,19 @@ export class TableWrapper extends PropertyRequiredMixin(PageableMixin(SelectionM
 		}
 	}
 
+	willUpdate(changedProperties) {
+		super.willUpdate(changedProperties);
+
+		// Todo: remove these once consumers are updated to freshness properties
+		if (this.dataState) {
+			if (this.dataState === 'clean') this.freshness = freshness.fresh;
+			else if (this.dataState === 'dirty') this.freshness = freshness.stale;
+			else if (this.dataState === 'loading') this.freshness = freshness.loading;
+		}
+		if (this.dirtyText) this.freshnessStaleText = this.dirtyText;
+		if (this.dirtyButtonText) this.freshnessStaleButtonText = this.dirtyButtonText;
+	}
+
 	#hasIntersected = false;
 
 	#noScrollWidthTimeout = null;
@@ -571,11 +563,6 @@ export class TableWrapper extends PropertyRequiredMixin(PageableMixin(SelectionM
 		this._handleControlsChange();
 	}
 
-	_handleDirtyButton() {
-		/** Dispatched when the action button on the dirty overlay is clicked */
-		this.dispatchEvent(new CustomEvent('d2l-table-dirty-button-clicked'));
-	}
-
 	_handlePopoverClose(e) {
 		this._updateStickyAncestor(e.target, false);
 	}
@@ -630,6 +617,14 @@ export class TableWrapper extends PropertyRequiredMixin(PageableMixin(SelectionM
 		this._handleTableChange();
 	}
 
+	_handleStaleButton() {
+		/** Dispatched when the action button on the stale overlay is clicked */
+		this.dispatchEvent(new CustomEvent('d2l-table-stale-button-click'));
+
+		/** @ignore Todo: remove once consumers are updated to d2l-table-stale-button-click */
+		this.dispatchEvent(new CustomEvent('d2l-table-dirty-button-clicked'));
+	}
+
 	async _handleTableChange(mutationRecords) {
 		const updateList = [];