@brightspace-ui/core 1.235.3 → 1.236.0

package/README.md

@@ -66,6 +66,7 @@ npm install @brightspace-ui/core
 * Mixins
   * [ArrowKeysMixin](mixins/arrow-keys-mixin.md): manage focus with arrow keys
   * [AsyncContainerMixin](mixins/async-container/): manage collective async state
+  * [FocusMixin](mixins/focus-mixin.md): delegate focus to a nested element when `focus()` is called
   * [FocusVisiblePolyfillMixin](mixins/focus-visible-polyfill-mixin.md): components can use the `:focus-visible` pseudo-class polyfill
   * [FormElementMixin](components/form/docs/form-element-mixin.md): allow components to participate in forms and validation
   * [LabelledMixin](mixins/labelled-mixin.md): label custom elements by referencing elements across DOM scopes

package/components/button/button-mixin.js

@@ -1,6 +1,7 @@
+import { FocusMixin } from '../../mixins/focus-mixin.js';
 import { FocusVisiblePolyfillMixin } from '../../mixins/focus-visible-polyfill-mixin.js';
 
-export const ButtonMixin = superclass => class extends FocusVisiblePolyfillMixin(superclass) {
+export const ButtonMixin = superclass => class extends FocusMixin(FocusVisiblePolyfillMixin(superclass)) {
 
 	static get properties() {
 		return {
@@ -65,6 +66,8 @@ export const ButtonMixin = superclass => class extends FocusVisiblePolyfillMixin
 		};
 	}
 
+	static focusElementSelector = 'button';
+
 	constructor() {
 		super();
 		this.disabled = false;
@@ -107,11 +110,6 @@ export const ButtonMixin = superclass => class extends FocusVisiblePolyfillMixin
 		this.removeEventListener('click', this._handleClick, true);
 	}
 
-	focus() {
-		const button = this.shadowRoot && this.shadowRoot.querySelector('button');
-		if (button) button.focus();
-	}
-
 	/** @internal */
 	_getType() {
 		if (this.type === 'submit' || this.type === 'reset') {

package/components/card/card.js

@@ -1,6 +1,7 @@
 import '../colors/colors.js';
 import { css, html, LitElement } from 'lit-element/lit-element.js';
 import { classMap } from 'lit-html/directives/class-map.js';
+import { FocusMixin } from '../../mixins/focus-mixin.js';
 import { ifDefined } from 'lit-html/directives/if-defined.js';
 import { offscreenStyles } from '../offscreen/offscreen.js';
 import ResizeObserver from 'resize-observer-polyfill/dist/ResizeObserver.es.js';
@@ -15,7 +16,7 @@ import { styleMap } from 'lit-html/directives/style-map.js';
  * @slot footer - Slot for footer content, such secondary actions
  * @slot header - Slot for header content, such as course image (no actionable elements)
  */
-class Card extends RtlMixin(LitElement) {
+class Card extends FocusMixin(RtlMixin(LitElement)) {
 
 	static get properties() {
 		return {
@@ -234,6 +235,8 @@ class Card extends RtlMixin(LitElement) {
 		`];
 	}
 
+	static focusElementSelector = 'a';
+
 	constructor() {
 		super();
 		this.alignCenter = false;
@@ -306,12 +309,6 @@ class Card extends RtlMixin(LitElement) {
 		`;
 	}
 
-	focus() {
-		const elem = this.shadowRoot && this.shadowRoot.querySelector('a');
-		if (!elem) return;
-		elem.focus();
-	}
-
 	_onBadgeResize(entries) {
 		if (!entries || entries.length === 0) return;
 		const entry = entries[0];

package/components/filter/filter.js

@@ -19,6 +19,7 @@ import { bodyCompactStyles, bodySmallStyles, bodyStandardStyles } from '../typog
 import { css, html, LitElement } from 'lit-element/lit-element.js';
 import { announce } from '../../helpers/announce.js';
 import { classMap } from 'lit-html/directives/class-map.js';
+import { FocusMixin } from '../../mixins/focus-mixin.js';
 import { ifDefined } from 'lit-html/directives/if-defined.js';
 import { LocalizeCoreElement } from '../../lang/localize-core-element.js';
 import { offscreenStyles } from '../offscreen/offscreen.js';
@@ -37,7 +38,7 @@ const SET_DIMENSION_ID_PREFIX = 'list-';
  * @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
  */
-class Filter extends LocalizeCoreElement(RtlMixin(LitElement)) {
+class Filter extends FocusMixin(LocalizeCoreElement(RtlMixin(LitElement))) {
 
 	static get properties() {
 		return {
@@ -136,6 +137,8 @@ class Filter extends LocalizeCoreElement(RtlMixin(LitElement)) {
 		`];
 	}
 
+	static focusElementSelector = 'd2l-dropdown-button-subtle';
+
 	constructor() {
 		super();
 		this.disabled = false;
@@ -229,11 +232,6 @@ class Filter extends LocalizeCoreElement(RtlMixin(LitElement)) {
 		`;
 	}
 
-	focus() {
-		const opener = this.shadowRoot && this.shadowRoot.querySelector('d2l-dropdown-button-subtle');
-		if (opener) opener.focus();
-	}
-
 	getSubscriberController() {
 		return this._activeFiltersSubscribers;
 	}

package/components/focus-trap/focus-trap.js

@@ -1,5 +1,6 @@
 import { css, html, LitElement } from 'lit-element/lit-element.js';
 import { forceFocusVisible, getNextFocusable, getPreviousFocusable } from '../../helpers/focus.js';
+import { FocusMixin } from '../../mixins/focus-mixin.js';
 import { ifDefined } from 'lit-html/directives/if-defined.js';
 import { isComposedAncestor } from '../../helpers/dom.js';
 
@@ -7,7 +8,7 @@ import { isComposedAncestor } from '../../helpers/dom.js';
  * A generic container component to trap user focus.
  * @fires d2l-focus-trap-enter - Dispatched when focus enters the trap. May be used to override initial focus placement when focus enters the trap.
  */
-class FocusTrap extends LitElement {
+class FocusTrap extends FocusMixin(LitElement) {
 
 	static get properties() {
 		return {
@@ -30,6 +31,8 @@ class FocusTrap extends LitElement {
 		`;
 	}
 
+	static focusElementSelector = '.d2l-focus-trap-start';
+
 	constructor() {
 		super();
 		this.trap = false;
@@ -55,11 +58,6 @@ class FocusTrap extends LitElement {
 		`;
 	}
 
-	focus() {
-		const focusable = this.shadowRoot && this.shadowRoot.querySelector('.d2l-focus-trap-start');
-		if (focusable) focusable.focus();
-	}
-
 	_focusFirst() {
 		const focusable = this.shadowRoot &&
 			getNextFocusable(this.shadowRoot.querySelector('.d2l-focus-trap-start'));

package/components/inputs/input-checkbox.js

@@ -1,6 +1,7 @@
 import '../colors/colors.js';
 import { css, html, LitElement } from 'lit-element/lit-element.js';
 import { classMap } from 'lit-html/directives/class-map.js';
+import { FocusMixin } from '../../mixins/focus-mixin.js';
 import { getUniqueId } from '../../helpers/uniqueId.js';
 import { ifDefined } from 'lit-html/directives/if-defined.js';
 import { offscreenStyles } from '../offscreen/offscreen.js';
@@ -56,7 +57,7 @@ export const checkboxStyles = css`
  * @slot - Checkbox information (e.g., text)
  * @fires change - Dispatched when the checkbox's state changes
  */
-class InputCheckbox extends SkeletonMixin(RtlMixin(LitElement)) {
+class InputCheckbox extends FocusMixin(SkeletonMixin(RtlMixin(LitElement))) {
 
 	static get properties() {
 		return {
@@ -163,6 +164,8 @@ class InputCheckbox extends SkeletonMixin(RtlMixin(LitElement)) {
 		];
 	}
 
+	static focusElementSelector = 'input.d2l-input-checkbox';
+
 	constructor() {
 		super();
 		this.checked = false;
@@ -205,11 +208,6 @@ class InputCheckbox extends SkeletonMixin(RtlMixin(LitElement)) {
 		`;
 	}
 
-	focus() {
-		const elem = this.shadowRoot && this.shadowRoot.querySelector('input.d2l-input-checkbox');
-		if (elem) elem.focus();
-	}
-
 	simulateClick() {
 		this.checked = !this.checked;
 		this.indeterminate = false;

package/components/inputs/input-date-range.js

@@ -4,6 +4,7 @@ import './input-fieldset.js';
 import '../tooltip/tooltip.js';
 import { css, html, LitElement } from 'lit-element/lit-element.js';
 import { formatDateTimeInISO, getDateFromISODate, parseISODateTime } from '../../helpers/dateTime.js';
+import { FocusMixin } from '../../mixins/focus-mixin.js';
 import { FormElementMixin } from '../form/form-element-mixin.js';
 import { getUniqueId } from '../../helpers/uniqueId.js';
 import { ifDefined } from 'lit-html/directives/if-defined.js';
@@ -30,7 +31,7 @@ export function getShiftedEndDate(startValue, endValue, prevStartValue, inclusiv
  * A component consisting of two input-date components - one for start of range and one for end of range. Values specified for these components (through start-value and/or end-value attributes) should be localized to the user's timezone if applicable and must be in ISO 8601 calendar date format ("YYYY-MM-DD").
  * @fires change - Dispatched when there is a change to selected start date or selected end date. `start-value` and `end-value` correspond to the selected values and are formatted in ISO 8601 calendar date format (`YYYY-MM-DD`).
  */
-class InputDateRange extends SkeletonMixin(FormElementMixin(RtlMixin(LocalizeCoreElement(LitElement)))) {
+class InputDateRange extends FocusMixin(SkeletonMixin(FormElementMixin(RtlMixin(LocalizeCoreElement(LitElement))))) {
 
 	static get properties() {
 		return {
@@ -128,6 +129,8 @@ class InputDateRange extends SkeletonMixin(FormElementMixin(RtlMixin(LocalizeCor
 		`];
 	}
 
+	static focusElementSelector = 'd2l-input-date';
+
 	constructor() {
 		super();
 
@@ -251,11 +254,6 @@ class InputDateRange extends SkeletonMixin(FormElementMixin(RtlMixin(LocalizeCor
 		});
 	}
 
-	focus() {
-		const input = this.shadowRoot && this.shadowRoot.querySelector('d2l-input-date');
-		if (input) input.focus();
-	}
-
 	async validate() {
 		if (!this.shadowRoot) return;
 		const startDateInput = this.shadowRoot.querySelector('.d2l-input-date-range-start');

package/components/inputs/input-date-time-range.js

@@ -5,6 +5,7 @@ import '../tooltip/tooltip.js';
 import { convertLocalToUTCDateTime, convertUTCToLocalDateTime } from '@brightspace-ui/intl/lib/dateTime.js';
 import { css, html, LitElement } from 'lit-element/lit-element.js';
 import { formatDateTimeInISO, getAdjustedTime, getDateFromISODateTime, getDateNoConversion, parseISODateTime } from '../../helpers/dateTime.js';
+import { FocusMixin } from '../../mixins/focus-mixin.js';
 import { FormElementMixin } from '../form/form-element-mixin.js';
 import { getUniqueId } from '../../helpers/uniqueId.js';
 import { ifDefined } from 'lit-html/directives/if-defined.js';
@@ -63,7 +64,7 @@ export function getShiftedEndDateTime(startValue, endValue, prevStartValue, incl
  * @slot end - Optional content that would appear below the end input-date-time
  * @fires change - Dispatched when there is a change to selected start date-time or selected end date-time. `start-value` and `end-value` correspond to the selected values and are formatted in ISO 8601 combined date and time format (`YYYY-MM-DDTHH:mm:ss.sssZ`).
  */
-class InputDateTimeRange extends SkeletonMixin(FormElementMixin(RtlMixin(LocalizeCoreElement(LitElement)))) {
+class InputDateTimeRange extends FocusMixin(SkeletonMixin(FormElementMixin(RtlMixin(LocalizeCoreElement(LitElement))))) {
 
 	static get properties() {
 		return {
@@ -171,6 +172,8 @@ class InputDateTimeRange extends SkeletonMixin(FormElementMixin(RtlMixin(Localiz
 		`];
 	}
 
+	static focusElementSelector = 'd2l-input-date-time';
+
 	constructor() {
 		super();
 
@@ -307,11 +310,6 @@ class InputDateTimeRange extends SkeletonMixin(FormElementMixin(RtlMixin(Localiz
 		});
 	}
 
-	focus() {
-		const input = this.shadowRoot && this.shadowRoot.querySelector('d2l-input-date-time');
-		if (input) input.focus();
-	}
-
 	async validate() {
 		if (!this.shadowRoot) return;
 		const startDateTimeInput = this.shadowRoot.querySelector('.d2l-input-date-time-range-start');

package/components/inputs/input-date-time.js

@@ -13,6 +13,7 @@ import { formatDateInISO,
 	parseISODate,
 	parseISODateTime,
 	parseISOTime } from '../../helpers/dateTime.js';
+import { FocusMixin } from '../../mixins/focus-mixin.js';
 import { FormElementMixin } from '../form/form-element-mixin.js';
 import { getDefaultTime } from './input-time.js';
 import { getDocumentLocaleSettings } from '@brightspace-ui/intl/lib/common.js';
@@ -40,7 +41,7 @@ function _getFormattedDefaultTime(defaultValue) {
  * A component that consists of a "<d2l-input-date>" and a "<d2l-input-time>" component. The time input only appears once a date is selected. This component displays the "value" if one is specified, and reflects the selected value when one is selected or entered.
  * @fires change - Dispatched when there is a change to selected date or selected time. `value` corresponds to the selected value and is formatted in ISO 8601 combined date and time format (`YYYY-MM-DDTHH:mm:ss.sssZ`).
  */
-class InputDateTime extends LabelledMixin(SkeletonMixin(FormElementMixin(LocalizeCoreElement(RtlMixin(LitElement))))) {
+class InputDateTime extends FocusMixin(LabelledMixin(SkeletonMixin(FormElementMixin(LocalizeCoreElement(RtlMixin(LitElement)))))) {
 
 	static get properties() {
 		return {
@@ -112,6 +113,8 @@ class InputDateTime extends LabelledMixin(SkeletonMixin(FormElementMixin(Localiz
 		`];
 	}
 
+	static focusElementSelector = 'd2l-input-date';
+
 	constructor() {
 		super();
 		this.disabled = false;
@@ -295,11 +298,6 @@ class InputDateTime extends LabelledMixin(SkeletonMixin(FormElementMixin(Localiz
 		});
 	}
 
-	focus() {
-		const elem = this.shadowRoot && this.shadowRoot.querySelector('d2l-input-date');
-		if (elem) elem.focus();
-	}
-
 	async validate() {
 		if (!this.shadowRoot) return;
 		const dateInput = this.shadowRoot.querySelector('d2l-input-date');

package/components/inputs/input-date.js

@@ -8,6 +8,7 @@ import './input-text.js';
 import { css, html, LitElement } from 'lit-element/lit-element.js';
 import { formatDate, parseDate } from '@brightspace-ui/intl/lib/dateTime.js';
 import { formatDateInISO, getDateFromISODate, getDateTimeDescriptorShared, getToday } from '../../helpers/dateTime.js';
+import { FocusMixin } from '../../mixins/focus-mixin.js';
 import { FormElementMixin } from '../form/form-element-mixin.js';
 import { getUniqueId } from '../../helpers/uniqueId.js';
 import { ifDefined } from 'lit-html/directives/if-defined.js';
@@ -27,7 +28,7 @@ export function formatISODateInUserCalDescriptor(val) {
  * A component that consists of a text input field for typing a date and an attached calendar (d2l-calendar) dropdown. It displays the "value" if one is specified, or a placeholder if not, and reflects the selected value when one is selected in the calendar or entered in the text input.
  * @fires change - Dispatched when there is a change to selected date. `value` corresponds to the selected value and is formatted in ISO 8601 calendar date format (`YYYY-MM-DD`).
  */
-class InputDate extends LabelledMixin(SkeletonMixin(FormElementMixin(LocalizeCoreElement(LitElement)))) {
+class InputDate extends FocusMixin(LabelledMixin(SkeletonMixin(FormElementMixin(LocalizeCoreElement(LitElement))))) {
 
 	static get properties() {
 		return {
@@ -137,6 +138,8 @@ class InputDate extends LabelledMixin(SkeletonMixin(FormElementMixin(LocalizeCor
 		`];
 	}
 
+	static focusElementSelector = 'd2l-input-text';
+
 	constructor() {
 		super();
 
@@ -331,10 +334,6 @@ class InputDate extends LabelledMixin(SkeletonMixin(FormElementMixin(LocalizeCor
 		});
 	}
 
-	focus() {
-		if (this._textInput) this._textInput.focus();
-	}
-
 	async validate() {
 		if (!this.shadowRoot) return;
 		const textInput = this.shadowRoot.querySelector('d2l-input-text');

package/components/inputs/input-number.js

@@ -1,6 +1,7 @@
 import './input-text.js';
 import { css, html, LitElement } from 'lit-element/lit-element.js';
 import { formatNumber, getNumberDescriptor, parseNumber } from '@brightspace-ui/intl/lib/number.js';
+import { FocusMixin } from '../../mixins/focus-mixin.js';
 import { FormElementMixin } from '../form/form-element-mixin.js';
 import { getUniqueId } from '../../helpers/uniqueId.js';
 import { ifDefined } from 'lit-html/directives/if-defined.js';
@@ -68,7 +69,7 @@ function roundPrecisely(val, maxFractionDigits) {
  * @slot right - Slot within the input on the right side. Useful for an "icon" or "button-icon".
  * @fires change - Dispatched when an alteration to the value is committed (typically after focus is lost) by the user. The `value` attribute reflects a JavaScript Number which is parsed from the formatted input value.
  */
-class InputNumber extends LabelledMixin(SkeletonMixin(FormElementMixin(LocalizeCoreElement(LitElement)))) {
+class InputNumber extends FocusMixin(LabelledMixin(SkeletonMixin(FormElementMixin(LocalizeCoreElement(LitElement))))) {
 
 	static get properties() {
 		return {
@@ -185,6 +186,8 @@ class InputNumber extends LabelledMixin(SkeletonMixin(FormElementMixin(LocalizeC
 		];
 	}
 
+	static focusElementSelector = 'd2l-input-text';
+
 	constructor() {
 		super();
 		this.autofocus = false;
@@ -364,16 +367,6 @@ class InputNumber extends LabelledMixin(SkeletonMixin(FormElementMixin(LocalizeC
 		});
 	}
 
-	async focus() {
-		const elem = this.shadowRoot && this.shadowRoot.querySelector('d2l-input-text');
-		if (elem) {
-			elem.focus();
-		} else {
-			await this.updateComplete;
-			this.focus();
-		}
-	}
-
 	async validate() {
 		if (!this.shadowRoot) return;
 		const inputTextElem = this.shadowRoot.querySelector('d2l-input-text');

package/components/inputs/input-percent.js

@@ -1,5 +1,6 @@
 import './input-number.js';
 import { css, html, LitElement } from 'lit-element/lit-element.js';
+import { FocusMixin } from '../../mixins/focus-mixin.js';
 import { FormElementMixin } from '../form/form-element-mixin.js';
 import { ifDefined } from 'lit-html/directives/if-defined.js';
 import { LabelledMixin } from '../../mixins/labelled-mixin.js';
@@ -12,7 +13,7 @@ import { SkeletonMixin } from '../skeleton/skeleton-mixin.js';
  * @slot after - Slot beside the input on the right side. Useful for an "icon" or "button-icon".
  * @fires change - Dispatched when an alteration to the value is committed (typically after focus is lost) by the user. The `value` attribute reflects a JavaScript Number which is parsed from the formatted input value.
  */
-class InputPercent extends LabelledMixin(SkeletonMixin(FormElementMixin(LocalizeCoreElement(RtlMixin(LitElement))))) {
+class InputPercent extends FocusMixin(LabelledMixin(SkeletonMixin(FormElementMixin(LocalizeCoreElement(RtlMixin(LitElement)))))) {
 
 	static get properties() {
 		return {
@@ -85,6 +86,8 @@ class InputPercent extends LabelledMixin(SkeletonMixin(FormElementMixin(Localize
 		];
 	}
 
+	static focusElementSelector = 'd2l-input-number';
+
 	constructor() {
 		super();
 		this.autofocus = false;
@@ -131,11 +134,6 @@ class InputPercent extends LabelledMixin(SkeletonMixin(FormElementMixin(Localize
 		`;
 	}
 
-	focus() {
-		const elem = this.shadowRoot && this.shadowRoot.querySelector('d2l-input-number');
-		if (elem) elem.focus();
-	}
-
 	async validate() {
 		if (!this.shadowRoot) return;
 		const inputNumberElem = this.shadowRoot.querySelector('d2l-input-number');

package/components/inputs/input-search.js

@@ -2,6 +2,7 @@ import '../button/button-icon.js';
 import '../colors/colors.js';
 import './input-text.js';
 import { css, html, LitElement } from 'lit-element/lit-element.js';
+import { FocusMixin } from '../../mixins/focus-mixin.js';
 import { ifDefined } from 'lit-html/directives/if-defined.js';
 import { inputStyles } from './input-styles.js';
 import { LocalizeCoreElement } from '../../lang/localize-core-element.js';
@@ -11,7 +12,7 @@ import { RtlMixin } from '../../mixins/rtl-mixin.js';
  * This component wraps the native "<input type="search">"" element and is for text searching.
  * @fires d2l-input-search-searched - Dispatched when a search is performed. When the input is cleared, this will be fired with an empty value.
  */
-class InputSearch extends LocalizeCoreElement(RtlMixin(LitElement)) {
+class InputSearch extends FocusMixin(LocalizeCoreElement(RtlMixin(LitElement))) {
 
 	static get properties() {
 		return {
@@ -73,6 +74,8 @@ class InputSearch extends LocalizeCoreElement(RtlMixin(LitElement)) {
 		];
 	}
 
+	static focusElementSelector = 'd2l-input-text';
+
 	constructor() {
 		super();
 		this._lastSearchValue = '';
@@ -122,11 +125,6 @@ class InputSearch extends LocalizeCoreElement(RtlMixin(LitElement)) {
 		`;
 	}
 
-	focus() {
-		const elem = this.shadowRoot && this.shadowRoot.querySelector('d2l-input-text');
-		if (elem) elem.focus();
-	}
-
 	search() {
 		this._setLastSearchValue(this.value);
 		this._dispatchEvent();

package/components/inputs/input-text.js

@@ -1,6 +1,7 @@
 import '../tooltip/tooltip.js';
 import { css, html, LitElement } from 'lit-element/lit-element.js';
 import { classMap } from 'lit-html/directives/class-map.js';
+import { FocusMixin } from '../../mixins/focus-mixin.js';
 import { formatNumber } from '@brightspace-ui/intl/lib/number.js';
 import { FormElementMixin } from '../form/form-element-mixin.js';
 import { getUniqueId } from '../../helpers/uniqueId.js';
@@ -22,7 +23,7 @@ import { styleMap } from 'lit-html/directives/style-map.js';
  * @fires change - Dispatched when an alteration to the value is committed (typically after focus is lost) by the user
  * @fires input - Dispatched immediately after changes by the user
  */
-class InputText extends LabelledMixin(FormElementMixin(SkeletonMixin(RtlMixin(LitElement)))) {
+class InputText extends FocusMixin(LabelledMixin(FormElementMixin(SkeletonMixin(RtlMixin(LitElement))))) {
 
 	static get properties() {
 		return {
@@ -234,6 +235,8 @@ class InputText extends LabelledMixin(FormElementMixin(SkeletonMixin(RtlMixin(Li
 		];
 	}
 
+	static focusElementSelector = '.d2l-input';
+
 	constructor() {
 		super();
 		this.autofocus = false;
@@ -463,16 +466,6 @@ class InputText extends LabelledMixin(FormElementMixin(SkeletonMixin(RtlMixin(Li
 		});
 	}
 
-	async focus() {
-		const elem = this.shadowRoot && this.shadowRoot.querySelector('.d2l-input');
-		if (elem) {
-			elem.focus();
-		} else {
-			await this.updateComplete;
-			this.focus();
-		}
-	}
-
 	_getAriaLabel() {
 		if (this.label && (this.labelHidden || this.labelledBy)) {
 			return this.label;

package/components/inputs/input-textarea.js

@@ -1,5 +1,6 @@
 import '../tooltip/tooltip.js';
 import { css, html, LitElement } from 'lit-element/lit-element.js';
+import { FocusMixin } from '../../mixins/focus-mixin.js';
 import { formatNumber } from '@brightspace-ui/intl/lib/number.js';
 import { FormElementMixin } from '../form/form-element-mixin.js';
 import { getUniqueId } from '../../helpers/uniqueId.js';
@@ -17,7 +18,7 @@ import { styleMap } from 'lit-html/directives/style-map.js';
  * @fires change - Dispatched when an alteration to the value is committed (typically after focus is lost) by the user
  * @fires input - Dispatched immediately after changes by the user
  */
-class InputTextArea extends LabelledMixin(FormElementMixin(SkeletonMixin(RtlMixin(LitElement)))) {
+class InputTextArea extends FocusMixin(LabelledMixin(FormElementMixin(SkeletonMixin(RtlMixin(LitElement))))) {
 
 	static get properties() {
 		return {
@@ -149,6 +150,8 @@ class InputTextArea extends LabelledMixin(FormElementMixin(SkeletonMixin(RtlMixi
 		`];
 	}
 
+	static focusElementSelector = 'textarea';
+
 	constructor() {
 		super();
 		this.disabled = false;
@@ -263,16 +266,6 @@ class InputTextArea extends LabelledMixin(FormElementMixin(SkeletonMixin(RtlMixi
 		});
 	}
 
-	async focus() {
-		const elem = this.shadowRoot && this.shadowRoot.querySelector('textarea');
-		if (elem) {
-			elem.focus();
-		} else {
-			await this.updateComplete;
-			this.focus();
-		}
-	}
-
 	async select() {
 		const elem = this.shadowRoot && this.shadowRoot.querySelector('textarea');
 		if (elem) {

package/components/inputs/input-time-range.js

@@ -4,6 +4,7 @@ import '../tooltip/tooltip.js';
 import { css, html, LitElement } from 'lit-element/lit-element.js';
 import { formatDateInISOTime, formatTimeInISO, getAdjustedTime, getDateFromISOTime, isValidTime, parseISOTime } from '../../helpers/dateTime.js';
 import { getDefaultTime, getIntervalNumber, getTimeAtInterval } from './input-time.js';
+import { FocusMixin } from '../../mixins/focus-mixin.js';
 import { FormElementMixin } from '../form/form-element-mixin.js';
 import { getUniqueId } from '../../helpers/uniqueId.js';
 import { ifDefined } from 'lit-html/directives/if-defined.js';
@@ -38,7 +39,7 @@ function getValidISOTimeAtInterval(val, timeInterval) {
  * @fires change - Dispatched when there is a change to selected start time or selected end time. `start-value` and `end-value` correspond to the selected values and are formatted in ISO 8601 calendar time format (`hh:mm:ss`).
  */
 
-class InputTimeRange extends SkeletonMixin(FormElementMixin(RtlMixin(LocalizeCoreElement(LitElement)))) {
+class InputTimeRange extends FocusMixin(SkeletonMixin(FormElementMixin(RtlMixin(LocalizeCoreElement(LitElement))))) {
 
 	static get properties() {
 		return {
@@ -136,6 +137,8 @@ class InputTimeRange extends SkeletonMixin(FormElementMixin(RtlMixin(LocalizeCor
 		`];
 	}
 
+	static focusElementSelector = 'd2l-input-time';
+
 	constructor() {
 		super();
 
@@ -302,11 +305,6 @@ class InputTimeRange extends SkeletonMixin(FormElementMixin(RtlMixin(LocalizeCor
 		});
 	}
 
-	focus() {
-		const input = this.shadowRoot && this.shadowRoot.querySelector('d2l-input-time');
-		if (input) input.focus();
-	}
-
 	async validate() {
 		if (!this.shadowRoot) return;
 		const startTimeInput = this.shadowRoot.querySelector('.d2l-input-time-range-start');

package/components/inputs/input-time.js

@@ -7,6 +7,7 @@ import { css, html, LitElement } from 'lit-element/lit-element.js';
 import { formatDateInISOTime, getDateFromISOTime, getToday } from '../../helpers/dateTime.js';
 import { formatTime, parseTime } from '@brightspace-ui/intl/lib/dateTime.js';
 import { bodySmallStyles } from '../typography/styles.js';
+import { FocusMixin } from '../../mixins/focus-mixin.js';
 import { FormElementMixin } from '../form/form-element-mixin.js';
 import { getUniqueId } from '../../helpers/uniqueId.js';
 import { ifDefined } from 'lit-html/directives/if-defined.js';
@@ -116,7 +117,7 @@ function initIntervals(size, enforceTimeIntervals) {
  * A component that consists of a text input field for typing a time and an attached dropdown for time selection. It displays the "value" if one is specified, or a placeholder if not, and reflects the selected value when one is selected in the dropdown or entered in the text input.
  * @fires change - Dispatched when there is a change to selected time. `value` corresponds to the selected value and is formatted in ISO 8601 time format (`hh:mm:ss`).
  */
-class InputTime extends LabelledMixin(SkeletonMixin(FormElementMixin(LitElement))) {
+class InputTime extends FocusMixin(LabelledMixin(SkeletonMixin(FormElementMixin(LitElement)))) {
 
 	static get properties() {
 		return {
@@ -214,6 +215,8 @@ class InputTime extends LabelledMixin(SkeletonMixin(FormElementMixin(LitElement)
 		];
 	}
 
+	static focusElementSelector = '.d2l-input';
+
 	constructor() {
 		super();
 		this.disabled = false;
@@ -349,11 +352,6 @@ class InputTime extends LabelledMixin(SkeletonMixin(FormElementMixin(LitElement)
 		});
 	}
 
-	focus() {
-		const elem = this.shadowRoot && this.shadowRoot.querySelector('.d2l-input');
-		if (elem) elem.focus();
-	}
-
 	getTime() {
 		const time = getDateFromISOTime(this.value);
 		return {

package/components/link/link.js

@@ -1,6 +1,7 @@
 import '../colors/colors.js';
 import { css, html, LitElement } from 'lit-element/lit-element.js';
 import { classMap } from 'lit-html/directives/class-map.js';
+import { FocusMixin } from '../../mixins/focus-mixin.js';
 import { ifDefined } from 'lit-html/directives/if-defined.js';
 
 export const linkStyles = css`
@@ -41,7 +42,7 @@ export const linkStyles = css`
  * This component can be used just like the native anchor tag.
  * @slot - The content (e.g., text) that when selected causes navigation
  */
-class Link extends LitElement {
+class Link extends FocusMixin(LitElement) {
 
 	static get properties() {
 		return {
@@ -96,6 +97,8 @@ class Link extends LitElement {
 		];
 	}
 
+	static focusElementSelector = '.d2l-link';
+
 	constructor() {
 		super();
 		this.download = false;
@@ -117,9 +120,5 @@ class Link extends LitElement {
 				target="${ifDefined(this.target)}"><slot></slot></a>`;
 	}
 
-	focus() {
-		const link = this.shadowRoot && this.shadowRoot.querySelector('.d2l-link');
-		if (link) link.focus();
-	}
 }
 customElements.define('d2l-link', Link);

package/components/selection/selection-action-dropdown.js

@@ -2,6 +2,7 @@ import '../button/button-subtle.js';
 import { html, LitElement } from 'lit-element/lit-element.js';
 import { DropdownOpenerMixin } from '../dropdown/dropdown-opener-mixin.js';
 import { dropdownOpenerStyles } from '../dropdown/dropdown-opener-styles.js';
+import { FocusMixin } from '../../mixins/focus-mixin.js';
 import { ifDefined } from 'lit-html/directives/if-defined.js';
 import { LocalizeCoreElement } from '../../lang/localize-core-element.js';
 import { SelectionActionMixin } from './selection-action-mixin.js';
@@ -11,7 +12,7 @@ import { SelectionActionMixin } from './selection-action-mixin.js';
  * @slot - Dropdown content (e.g., "d2l-dropdown-content", "d2l-dropdown-menu" or "d2l-dropdown-tabs")
  * @fires d2l-selection-observer-subscribe - Internal event
  */
-class ActionDropdown extends LocalizeCoreElement(SelectionActionMixin(DropdownOpenerMixin(LitElement))) {
+class ActionDropdown extends FocusMixin(LocalizeCoreElement(SelectionActionMixin(DropdownOpenerMixin(LitElement)))) {
 
 	static get properties() {
 		return {
@@ -27,6 +28,8 @@ class ActionDropdown extends LocalizeCoreElement(SelectionActionMixin(DropdownOp
 		return dropdownOpenerStyles;
 	}
 
+	static focusElementSelector = 'd2l-button-subtle';
+
 	render() {
 		return html`
 			<d2l-button-subtle
@@ -39,11 +42,6 @@ class ActionDropdown extends LocalizeCoreElement(SelectionActionMixin(DropdownOp
 		`;
 	}
 
-	focus() {
-		const elem = this.shadowRoot && this.shadowRoot.querySelector('d2l-button-subtle');
-		if (elem) elem.focus();
-	}
-
 	/**
 	 * Gets the opener element with class "d2l-dropdown-opener" (required by dropdown-opener-mixin).
 	 * @return {HTMLElement}

package/components/selection/selection-action.js

@@ -1,6 +1,7 @@
 import '../button/button-subtle.js';
 import { css, html, LitElement } from 'lit-element/lit-element.js';
 import { ButtonMixin } from '../button/button-mixin.js';
+import { FocusMixin } from '../../mixins/focus-mixin.js';
 import { ifDefined } from 'lit-html/directives/if-defined.js';
 import { LocalizeCoreElement } from '../../lang/localize-core-element.js';
 import { SelectionActionMixin } from './selection-action-mixin.js';
@@ -11,7 +12,7 @@ import { SelectionInfo } from './selection-mixin.js';
  * @fires d2l-selection-action-click - Dispatched when the user clicks the action button. The `SelectionInfo` is provided as the event `detail`. If `requires-selection` was specified then the event will only be dispatched if items are selected.
  * @fires d2l-selection-observer-subscribe - Internal event
  */
-class Action extends LocalizeCoreElement(SelectionActionMixin(ButtonMixin(LitElement))) {
+class Action extends FocusMixin(LocalizeCoreElement(SelectionActionMixin(ButtonMixin(LitElement)))) {
 
 	static get properties() {
 		return {
@@ -39,6 +40,8 @@ class Action extends LocalizeCoreElement(SelectionActionMixin(ButtonMixin(LitEle
 		`;
 	}
 
+	static focusElementSelector = 'd2l-button-subtle';
+
 	connectedCallback() {
 		super.connectedCallback();
 		this.addEventListener('d2l-button-ghost-click', this._handleActionClick);
@@ -61,11 +64,6 @@ class Action extends LocalizeCoreElement(SelectionActionMixin(ButtonMixin(LitEle
 		`;
 	}
 
-	focus() {
-		const elem = this.shadowRoot && this.shadowRoot.querySelector('d2l-button-subtle');
-		if (elem) elem.focus();
-	}
-
 	_handleActionClick(e) {
 		e.stopPropagation();
 

package/components/selection/selection-select-all-pages.js

@@ -1,5 +1,6 @@
 import '../button/button-subtle.js';
 import { css, html, LitElement } from 'lit-element/lit-element.js';
+import { FocusMixin } from '../../mixins/focus-mixin.js';
 import { LocalizeCoreElement } from '../../lang/localize-core-element.js';
 import { SelectionInfo } from './selection-mixin.js';
 import { SelectionObserverMixin } from './selection-observer-mixin.js';
@@ -8,7 +9,7 @@ import { SelectionObserverMixin } from './selection-observer-mixin.js';
  * A subtle button that selects all items for all pages.
  * @fires d2l-selection-observer-subscribe - Internal event
  */
-class SelectAllPages extends LocalizeCoreElement(SelectionObserverMixin(LitElement)) {
+class SelectAllPages extends FocusMixin(LocalizeCoreElement(SelectionObserverMixin(LitElement))) {
 
 	static get styles() {
 		return css`
@@ -21,6 +22,8 @@ class SelectAllPages extends LocalizeCoreElement(SelectionObserverMixin(LitEleme
 		`;
 	}
 
+	static focusElementSelector = 'd2l-button-subtle';
+
 	render() {
 		if (!this._provider) return;
 		if (!this._provider.itemCount) return;
@@ -34,11 +37,6 @@ class SelectAllPages extends LocalizeCoreElement(SelectionObserverMixin(LitEleme
 			</d2l-button-subtle>`;
 	}
 
-	focus() {
-		const elem = this.shadowRoot && this.shadowRoot.querySelector('d2l-button-subtle');
-		if (elem) elem.focus();
-	}
-
 	_handleClick() {
 		if (this._provider) this._provider.setSelectionForAll(true, true);
 	}

package/components/selection/selection-select-all.js

@@ -1,5 +1,6 @@
 import '../inputs/input-checkbox.js';
 import { css, html, LitElement } from 'lit-element/lit-element.js';
+import { FocusMixin } from '../../mixins/focus-mixin.js';
 import { ifDefined } from 'lit-html/directives/if-defined.js';
 import { LocalizeCoreElement } from '../../lang/localize-core-element.js';
 import { SelectionInfo } from './selection-mixin.js';
@@ -9,7 +10,7 @@ import { SelectionObserverMixin } from './selection-observer-mixin.js';
  * A checkbox that provides select-all behavior for selection components such as tables and lists.
  * @fires d2l-selection-observer-subscribe - Internal event
  */
-class SelectAll extends LocalizeCoreElement(SelectionObserverMixin(LitElement)) {
+class SelectAll extends FocusMixin(LocalizeCoreElement(SelectionObserverMixin(LitElement))) {
 
 	static get properties() {
 		return {
@@ -33,6 +34,8 @@ class SelectAll extends LocalizeCoreElement(SelectionObserverMixin(LitElement))
 		`;
 	}
 
+	static focusElementSelector = 'd2l-input-checkbox';
+
 	constructor() {
 		super();
 		this.disabled = false;
@@ -56,11 +59,6 @@ class SelectAll extends LocalizeCoreElement(SelectionObserverMixin(LitElement))
 		`;
 	}
 
-	focus() {
-		const elem = this.shadowRoot && this.shadowRoot.querySelector('d2l-input-checkbox');
-		if (elem) elem.focus();
-	}
-
 	_handleCheckboxChange(e) {
 		if (this._provider) this._provider.setSelectionForAll(e.target.checked, false);
 	}

package/components/switch/switch-mixin.js

@@ -1,12 +1,13 @@
 import '../colors/colors.js';
 import '../tooltip/tooltip.js';
 import { css, html } from 'lit-element/lit-element.js';
+import { FocusMixin } from '../../mixins/focus-mixin.js';
 import { FocusVisiblePolyfillMixin } from '../../mixins/focus-visible-polyfill-mixin.js';
 import { getUniqueId } from '../../helpers/uniqueId.js';
 import { ifDefined } from 'lit-html/directives/if-defined.js';
 import { RtlMixin } from '../../mixins/rtl-mixin.js';
 
-export const SwitchMixin = superclass => class extends RtlMixin(FocusVisiblePolyfillMixin(superclass)) {
+export const SwitchMixin = superclass => class extends FocusMixin(RtlMixin(FocusVisiblePolyfillMixin(superclass))) {
 
 	static get properties() {
 		return {
@@ -165,6 +166,8 @@ export const SwitchMixin = superclass => class extends RtlMixin(FocusVisiblePoly
 		`;
 	}
 
+	static focusElementSelector = '.d2l-switch-container';
+
 	constructor() {
 		super();
 		this.disabled = false;
@@ -212,11 +215,6 @@ export const SwitchMixin = superclass => class extends RtlMixin(FocusVisiblePoly
 		`;
 	}
 
-	focus() {
-		const elem = this.shadowRoot && this.shadowRoot.querySelector('.d2l-switch-container');
-		if (elem) elem.focus();
-	}
-
 	_handleClick() {
 		this._toggleState();
 	}

package/components/table/table-col-sort-button.js

@@ -1,11 +1,12 @@
 import '../icons/icon.js';
 import { css, html, LitElement } from 'lit-element/lit-element.js';
+import { FocusMixin } from '../../mixins/focus-mixin.js';
 
 /**
  * Button for sorting a table column in ascending/descending order.
  * @slot - Text of the sort button
  */
-export class TableColSortButton extends LitElement {
+export class TableColSortButton extends FocusMixin(LitElement) {
 
 	static get properties() {
 		return {
@@ -57,6 +58,8 @@ export class TableColSortButton extends LitElement {
 		`;
 	}
 
+	static focusElementSelector = 'button';
+
 	constructor() {
 		super();
 		this.nosort = false;
@@ -70,11 +73,6 @@ export class TableColSortButton extends LitElement {
 		return html`<button type="button"><slot></slot>${iconView}</button>`;
 	}
 
-	focus() {
-		const button = this.shadowRoot && this.shadowRoot.querySelector('button');
-		if (button) button.focus();
-	}
-
 }
 
 customElements.define('d2l-table-col-sort-button', TableColSortButton);

package/custom-elements.json

@@ -408,6 +408,11 @@
           "type": "boolean",
           "default": "false"
         },
+        {
+          "name": "focusElementSelector",
+          "type": "string",
+          "default": "\"button\""
+        },
         {
           "name": "visibleOnAncestor",
           "type": "boolean",
@@ -502,6 +507,11 @@
           "description": "Disables the button",
           "type": "boolean",
           "default": "false"
+        },
+        {
+          "name": "focusElementSelector",
+          "type": "string",
+          "default": "\"button\""
         }
       ],
       "slots": [
@@ -565,6 +575,11 @@
           "description": "Disables the button",
           "type": "boolean",
           "default": "false"
+        },
+        {
+          "name": "focusElementSelector",
+          "type": "string",
+          "default": "\"button\""
         }
       ],
       "slots": [
@@ -979,6 +994,11 @@
           "description": "Subtle aesthetic on non-white backgrounds",
           "type": "boolean",
           "default": "false"
+        },
+        {
+          "name": "focusElementSelector",
+          "type": "string",
+          "default": "\"a\""
         }
       ],
       "slots": [
@@ -3137,6 +3157,11 @@
           "description": "Indicates if the filter is open",
           "type": "boolean",
           "default": "false"
+        },
+        {
+          "name": "focusElementSelector",
+          "type": "string",
+          "default": "\"d2l-dropdown-button-subtle\""
         }
       ],
       "events": [
@@ -3179,6 +3204,11 @@
           "description": "Whether the component should trap user focus.",
           "type": "boolean",
           "default": "false"
+        },
+        {
+          "name": "focusElementSelector",
+          "type": "string",
+          "default": "\".d2l-focus-trap-start\""
         }
       ],
       "events": [
@@ -3759,6 +3789,11 @@
           "type": "string",
           "default": "\"on\""
         },
+        {
+          "name": "focusElementSelector",
+          "type": "string",
+          "default": "\"input.d2l-input-checkbox\""
+        },
         {
           "name": "skeleton",
           "attribute": "skeleton",
@@ -3983,6 +4018,11 @@
           "type": "boolean",
           "default": "false"
         },
+        {
+          "name": "focusElementSelector",
+          "type": "string",
+          "default": "\"d2l-input-date\""
+        },
         {
           "name": "skeleton",
           "attribute": "skeleton",
@@ -4280,6 +4320,11 @@
           "type": "boolean",
           "default": "false"
         },
+        {
+          "name": "focusElementSelector",
+          "type": "string",
+          "default": "\"d2l-input-date-time\""
+        },
         {
           "name": "skeleton",
           "attribute": "skeleton",
@@ -4450,6 +4495,11 @@
           "type": "string",
           "default": "\"startOfDay\""
         },
+        {
+          "name": "focusElementSelector",
+          "type": "string",
+          "default": "\"d2l-input-date\""
+        },
         {
           "name": "labelledBy",
           "attribute": "labelled-by",
@@ -4616,6 +4666,11 @@
           "type": "string",
           "default": "\"\""
         },
+        {
+          "name": "focusElementSelector",
+          "type": "string",
+          "default": "\"d2l-input-text\""
+        },
         {
           "name": "labelledBy",
           "attribute": "labelled-by",
@@ -4955,6 +5010,11 @@
           "type": "boolean",
           "default": "false"
         },
+        {
+          "name": "focusElementSelector",
+          "type": "string",
+          "default": "\"d2l-input-text\""
+        },
         {
           "name": "labelledBy",
           "attribute": "labelled-by",
@@ -5153,6 +5213,11 @@
           "type": "boolean",
           "default": "false"
         },
+        {
+          "name": "focusElementSelector",
+          "type": "string",
+          "default": "\"d2l-input-number\""
+        },
         {
           "name": "labelledBy",
           "attribute": "labelled-by",
@@ -5290,6 +5355,11 @@
           "description": "Value of the input",
           "type": "string",
           "default": "\"\""
+        },
+        {
+          "name": "focusElementSelector",
+          "type": "string",
+          "default": "\"d2l-input-text\""
         }
       ],
       "events": [
@@ -5629,6 +5699,11 @@
           "type": "'text'|'email'|'number'|'password'|'search'|'tel'|'url'",
           "default": "\"text\""
         },
+        {
+          "name": "focusElementSelector",
+          "type": "string",
+          "default": "\".d2l-input\""
+        },
         {
           "name": "labelledBy",
           "attribute": "labelled-by",
@@ -5868,6 +5943,11 @@
           "type": "string",
           "default": "\"\""
         },
+        {
+          "name": "focusElementSelector",
+          "type": "string",
+          "default": "\"textarea\""
+        },
         {
           "name": "labelledBy",
           "attribute": "labelled-by",
@@ -6117,6 +6197,11 @@
           "type": "'five'|'ten'|'fifteen'|'twenty'|'thirty'|'sixty'",
           "default": "\"thirty\""
         },
+        {
+          "name": "focusElementSelector",
+          "type": "string",
+          "default": "\"d2l-input-time\""
+        },
         {
           "name": "skeleton",
           "attribute": "skeleton",
@@ -6277,6 +6362,11 @@
           "type": "'five'|'ten'|'fifteen'|'twenty'|'thirty'|'sixty'",
           "default": "\"thirty\""
         },
+        {
+          "name": "focusElementSelector",
+          "type": "string",
+          "default": "\".d2l-input\""
+        },
         {
           "name": "labelledBy",
           "attribute": "labelled-by",
@@ -6393,6 +6483,11 @@
           "description": "Whether to apply the \"small\" link style",
           "type": "boolean",
           "default": "false"
+        },
+        {
+          "name": "focusElementSelector",
+          "type": "string",
+          "default": "\".d2l-link\""
         }
       ],
       "slots": [
@@ -8518,6 +8613,11 @@
           "description": "REQUIRED: Text for the dropdown opener button",
           "type": "string"
         },
+        {
+          "name": "focusElementSelector",
+          "type": "string",
+          "default": "\"d2l-button-subtle\""
+        },
         {
           "name": "requiresSelection",
           "attribute": "requires-selection",
@@ -8751,6 +8851,11 @@
           "description": "Disables the button",
           "type": "boolean",
           "default": "false"
+        },
+        {
+          "name": "focusElementSelector",
+          "type": "string",
+          "default": "\"d2l-button-subtle\""
         }
       ],
       "events": [
@@ -8870,6 +8975,11 @@
         }
       ],
       "properties": [
+        {
+          "name": "focusElementSelector",
+          "type": "string",
+          "default": "\"d2l-button-subtle\""
+        },
         {
           "name": "selectionFor",
           "attribute": "selection-for",
@@ -8912,6 +9022,11 @@
           "type": "boolean",
           "default": "false"
         },
+        {
+          "name": "focusElementSelector",
+          "type": "string",
+          "default": "\"d2l-input-checkbox\""
+        },
         {
           "name": "selectionFor",
           "attribute": "selection-for",
@@ -9334,6 +9449,11 @@
           "description": "Determines where text should be positioned relative to the switch.",
           "type": "'start'|'end'|'hidden'",
           "default": "\"end\""
+        },
+        {
+          "name": "focusElementSelector",
+          "type": "string",
+          "default": "\".d2l-switch-container\""
         }
       ],
       "events": [
@@ -9423,6 +9543,11 @@
           "description": "Determines where text should be positioned relative to the switch.",
           "type": "'start'|'end'|'hidden'",
           "default": "\"end\""
+        },
+        {
+          "name": "focusElementSelector",
+          "type": "string",
+          "default": "\".d2l-switch-container\""
         }
       ],
       "events": [
@@ -9516,6 +9641,11 @@
           "description": "Whether sort direction is descending",
           "type": "boolean",
           "default": "false"
+        },
+        {
+          "name": "focusElementSelector",
+          "type": "string",
+          "default": "\"button\""
         }
       ],
       "slots": [

package/mixins/focus-mixin.js

@@ -0,0 +1,41 @@
+import { dedupeMixin } from '@open-wc/dedupe-mixin';
+
+export const FocusMixin = dedupeMixin(superclass => class extends superclass {
+
+	static focusElementSelector = null;
+
+	constructor() {
+		super();
+		this._focusOnFirstRender = false;
+	}
+
+	firstUpdated(changedProperties) {
+		super.firstUpdated(changedProperties);
+		if (this._focusOnFirstRender) {
+			this._focusOnFirstRender = false;
+			this.focus();
+		}
+	}
+
+	focus() {
+
+		const selector = this.constructor.focusElementSelector;
+		if (!selector) {
+			throw new Error(`FocusMixin: no static focusElementSelector provided for "${this.tagName}"`);
+		}
+
+		if (!this.hasUpdated) {
+			this._focusOnFirstRender = true;
+			return;
+		}
+
+		const elem = this.shadowRoot.querySelector(selector);
+		if (!elem) {
+			throw new Error(`FocusMixin: selector "${selector}" yielded no element for "${this.tagName}"`);
+		}
+
+		elem.focus();
+
+	}
+
+});

package/mixins/focus-mixin.md

@@ -0,0 +1,24 @@
+# FocusMixin
+
+The `FocusMixin` can be used to delegate focus to an element within a component's shadow root when its `focus()` method is called.
+
+If the component has yet to render, focus will automatically be applied after `firstUpdated`.
+
+## Usage
+
+Apply the mixin and set the static `focusElementSelector` to a CSS query selector which will match the element to which focus should be delegated.
+
+```js
+import { FocusMixin } from '@brightspace-ui/core/mixins/focus-mixin.js';
+
+class MyComponent extends FocusMixin(LitElement) {
+  
+  // delegate focus to the underlying input
+  static focusElementSelector = 'input';
+
+  render() {
+	  return html`<input type="text">`;
+  }
+
+}
+```

package/package.json

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