@brightspace-ui/core 2.52.1 → 2.54.0

package/components/filter/README.md

@@ -159,7 +159,7 @@ The filter will announce changes to filter selections, search results, and when
 
 <!-- docs: end hidden content -->
 
-## Filter Dimension: Set [d2l-filter-dimension-set]
+## Dimension Set [d2l-filter-dimension-set]
 
 The `d2l-filter-dimension-set` component is the main dimension type that will work for most use cases.  Used alongside the [d2l-filter-dimension-set-value](#d2l-filter-dimension-set-value), this will give you a selectable list of filter values.
 
@@ -197,7 +197,7 @@ The `d2l-filter-dimension-set` component is the main dimension type that will wo
 | `value-only-active-filter-text` | Boolean | Whether to hide the dimension in the text sent to active filter subscribers |
 <!-- docs: end hidden content -->
 
-## Filter Dimension: Set Value [d2l-filter-dimension-set-value]
+## Dimension Set Value [d2l-filter-dimension-set-value]
 
 This component is built to be used alongside the [d2l-filter-dimension-set](#d2l-filter-dimension-set) component, this will give you a selectable list of filter values.
 
@@ -210,8 +210,9 @@ This component is built to be used alongside the [d2l-filter-dimension-set](#d2l
 </script>
 <d2l-filter>
   <d2l-filter-dimension-set key="course" text="Course" >
-    <d2l-filter-dimension-set-value key="art" text="Art" selected></d2l-filter-dimension-set-value>
-    <d2l-filter-dimension-set-value key="biology" text="Biology"></d2l-filter-dimension-set-value>
+    <d2l-filter-dimension-set-value key="art" text="Art" count="1" selected></d2l-filter-dimension-set-value>
+    <d2l-filter-dimension-set-value key="astronomy" text="Astronomy" count="3" disabled></d2l-filter-dimension-set-value>
+    <d2l-filter-dimension-set-value key="biology" text="Biology" count="5"></d2l-filter-dimension-set-value>
   </d2l-filter-dimension-set>
 </d2l-filter>
 ```
@@ -220,12 +221,43 @@ This component is built to be used alongside the [d2l-filter-dimension-set](#d2l
 
 | Property | Type | Description |
 |---|---|---|
+| `count` | Number | Count for the value in the list. If no count is provided, no count will be displayed |
 | `disabled` | Boolean, default: `false` | Whether the value in the filter is disabled or not |
 | `key` | String, required | Unique identifier within a dimension for the value |
 | `text` | String, required | Text for the value in the list |
 | `selected` | Boolean, default: `false` | Whether the value in the filter is selected or not |
 <!-- docs: end hidden content -->
 
+## Counts [d2l-filter-dimension-set-value]
+
+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.
+
+Note that when using multiple filter dimensions, the counts should be updated when selections are made across dimensions so that they always reflect the number of results a filter will yield.
+
+<!-- docs: demo code align:start autoOpen:true autoSize:false size:large -->
+```html
+<script type="module">
+  import '@brightspace-ui/core/components/filter/filter.js';
+  import '@brightspace-ui/core/components/filter/filter-dimension-set.js';
+  import '@brightspace-ui/core/components/filter/filter-dimension-set-value.js';
+</script>
+<d2l-filter>
+  <d2l-filter-dimension-set key="course" text="Course" >
+    <d2l-filter-dimension-set-value key="art" text="Art" count="0"></d2l-filter-dimension-set-value>
+    <d2l-filter-dimension-set-value key="astronomy" text="Astronomy" count="1" selected></d2l-filter-dimension-set-value>
+    <d2l-filter-dimension-set-value key="biology" text="Biology" count="1024"></d2l-filter-dimension-set-value>
+    <d2l-filter-dimension-set-value key="chemistry" text="Chemistry" count="25" disabled></d2l-filter-dimension-set-value>
+    <d2l-filter-dimension-set-value key="drama" text="Drama" count="362"></d2l-filter-dimension-set-value>
+    <d2l-filter-dimension-set-value key="english" text="English" count="881"></d2l-filter-dimension-set-value>
+    <d2l-filter-dimension-set-value key="how-to" text="How To Write a How To Article With a Flashy Title" count="212"></d2l-filter-dimension-set-value>
+    <d2l-filter-dimension-set-value key="math" text="Math" count="22365"></d2l-filter-dimension-set-value>
+    <d2l-filter-dimension-set-value key="physics" text="Physics" count="27"></d2l-filter-dimension-set-value>
+    <d2l-filter-dimension-set-value key="stats" text="Statistics" count="2"></d2l-filter-dimension-set-value>
+    <d2l-filter-dimension-set-value key="writerscraft" text="Writer's Craft" count="96"></d2l-filter-dimension-set-value>
+  </d2l-filter-dimension-set>
+</d2l-filter>
+```
+
 ## Tags for Applied Filters [d2l-filter-tags]
 
 A tag-list allowing the user to see (and remove) the currently applied filters. Works with the `d2l-filter`. It supports hooking up to multiple filters.
@@ -374,13 +406,10 @@ The `d2l-filter-overflow-group` is a container for multiple filters that handles
 | `tags` | Boolean, default: `false` | Show `d2l-filter-tags` beneath the filters. Tags will be shown for all filters in the group. |
 <!-- docs: end hidden content -->
 
-## Filter Dimension: Date [d2l-filter-dimension-date]
-
-**Coming Soon!**
-
 <!-- docs: start hidden content -->
 ## Future Improvements
 
+* Date Dimension - Ability to filter by dates
 * ability to delay change events until the user has pressed an apply button (see [#341](https://github.com/BrightspaceUI/core/issues/341))
 
 Looking for an enhancement not listed here? Create a GitHub issue!

package/components/filter/demo/filter.html

@@ -24,17 +24,17 @@
 			<template>
 				<d2l-filter>
 					<d2l-filter-dimension-set key="course" text="Course" select-all>
-						<d2l-filter-dimension-set-value key="art" text="Art"></d2l-filter-dimension-set-value>
-						<d2l-filter-dimension-set-value key="astronomy" text="Astronomy" selected></d2l-filter-dimension-set-value>
-						<d2l-filter-dimension-set-value key="biology" text="Biology"></d2l-filter-dimension-set-value>
-						<d2l-filter-dimension-set-value key="chemistry" text="Chemistry" disabled></d2l-filter-dimension-set-value>
-						<d2l-filter-dimension-set-value key="drama" text="Drama" disabled></d2l-filter-dimension-set-value>
-						<d2l-filter-dimension-set-value key="english" text="English"></d2l-filter-dimension-set-value>
-						<d2l-filter-dimension-set-value key="how-to" text="How To Write a How To Article With a Flashy Title"></d2l-filter-dimension-set-value>
-						<d2l-filter-dimension-set-value key="math" text="Math"></d2l-filter-dimension-set-value>
-						<d2l-filter-dimension-set-value key="physics" text="Physics"></d2l-filter-dimension-set-value>
-						<d2l-filter-dimension-set-value key="stats" text="Statistics"></d2l-filter-dimension-set-value>
-						<d2l-filter-dimension-set-value key="writerscraft" text="Writer's Craft"></d2l-filter-dimension-set-value>
+						<d2l-filter-dimension-set-value key="art" text="Art" count="12"></d2l-filter-dimension-set-value>
+						<d2l-filter-dimension-set-value key="astronomy" text="Astronomy" count="2" selected></d2l-filter-dimension-set-value>
+						<d2l-filter-dimension-set-value key="biology" text="Biology" count="15"></d2l-filter-dimension-set-value>
+						<d2l-filter-dimension-set-value key="chemistry" text="Chemistry" count="1"disabled></d2l-filter-dimension-set-value>
+						<d2l-filter-dimension-set-value key="drama" text="Drama" count="23" disabled></d2l-filter-dimension-set-value>
+						<d2l-filter-dimension-set-value key="english" text="English" count="100"></d2l-filter-dimension-set-value>
+						<d2l-filter-dimension-set-value key="how-to" text="How To Write a How To Article With a Flashy Title" count="100"></d2l-filter-dimension-set-value>
+						<d2l-filter-dimension-set-value key="math" text="Math" count="50"></d2l-filter-dimension-set-value>
+						<d2l-filter-dimension-set-value key="physics" text="Physics" count="23"></d2l-filter-dimension-set-value>
+						<d2l-filter-dimension-set-value key="stats" text="Statistics" count="333"></d2l-filter-dimension-set-value>
+						<d2l-filter-dimension-set-value key="writerscraft" text="Writer's Craft" count="2211"></d2l-filter-dimension-set-value>
 					</d2l-filter-dimension-set>
 				</d2l-filter>
 			</template>
@@ -59,22 +59,22 @@
 			<template>
 				<d2l-filter>
 					<d2l-filter-dimension-set key="course" text="Course" select-all>
-						<d2l-filter-dimension-set-value key="art" text="Art"></d2l-filter-dimension-set-value>
-						<d2l-filter-dimension-set-value key="astronomy" text="Astronomy" selected></d2l-filter-dimension-set-value>
-						<d2l-filter-dimension-set-value key="biology" text="Biology"></d2l-filter-dimension-set-value>
-						<d2l-filter-dimension-set-value key="chemistry" text="Chemistry"></d2l-filter-dimension-set-value>
-						<d2l-filter-dimension-set-value key="drama" text="Drama"></d2l-filter-dimension-set-value>
-						<d2l-filter-dimension-set-value key="english" text="English"></d2l-filter-dimension-set-value>
-						<d2l-filter-dimension-set-value key="how-to" text="How To Write a How To Article With a Flashy Title"></d2l-filter-dimension-set-value>
-						<d2l-filter-dimension-set-value key="math" text="Math"></d2l-filter-dimension-set-value>
-						<d2l-filter-dimension-set-value key="physics" text="Physics"></d2l-filter-dimension-set-value>
-						<d2l-filter-dimension-set-value key="stats" text="Statistics"></d2l-filter-dimension-set-value>
+						<d2l-filter-dimension-set-value key="art" text="Art" count="0"></d2l-filter-dimension-set-value>
+						<d2l-filter-dimension-set-value key="astronomy" text="Astronomy" count="1" selected></d2l-filter-dimension-set-value>
+						<d2l-filter-dimension-set-value key="biology" text="Biology" count="-12"></d2l-filter-dimension-set-value>
+						<d2l-filter-dimension-set-value key="chemistry" text="Chemistry" count="12.35"></d2l-filter-dimension-set-value>
+						<d2l-filter-dimension-set-value key="drama" text="Drama" count="xxx"></d2l-filter-dimension-set-value>
+						<d2l-filter-dimension-set-value key="english" text="English" count="881"></d2l-filter-dimension-set-value>
+						<d2l-filter-dimension-set-value key="how-to" text="How To Write a How To Article With a Flashy Title" count="100"></d2l-filter-dimension-set-value>
+						<d2l-filter-dimension-set-value key="math" text="Math" count="23909"></d2l-filter-dimension-set-value>
+						<d2l-filter-dimension-set-value key="physics" text="Physics" count="1012"></d2l-filter-dimension-set-value>
+						<d2l-filter-dimension-set-value key="stats" text="Statistics" count="2"></d2l-filter-dimension-set-value>
 						<d2l-filter-dimension-set-value key="writerscraft" text="Writer's Craft"></d2l-filter-dimension-set-value>
 					</d2l-filter-dimension-set>
 					<d2l-filter-dimension-set key="role" text="Role">
-						<d2l-filter-dimension-set-value key="admin" text="Admin"></d2l-filter-dimension-set-value>
-						<d2l-filter-dimension-set-value key="instructor" text="Instructor"></d2l-filter-dimension-set-value>
-						<d2l-filter-dimension-set-value key="student" text="Student"></d2l-filter-dimension-set-value>
+						<d2l-filter-dimension-set-value key="admin" text="Admin" count="0"></d2l-filter-dimension-set-value>
+						<d2l-filter-dimension-set-value key="instructor" text="Instructor" count="22"></d2l-filter-dimension-set-value>
+						<d2l-filter-dimension-set-value key="student" text="Student" count="50"></d2l-filter-dimension-set-value>
 					</d2l-filter-dimension-set>
 					<d2l-filter-dimension-set key="semester" text="Semester" selection-single>
 						<d2l-filter-dimension-set-value key="fall" text="Fall"></d2l-filter-dimension-set-value>

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

@@ -8,6 +8,11 @@ class FilterDimensionSetValue extends LitElement {
 
 	static get properties() {
 		return {
+			/**
+			 * Count for the value in the list. If no count is provided, no count will be displayed
+			 * @type {number}
+			 */
+			count: { type: Number },
 			/**
 			 * Whether this value in the filter is disabled or not
 			 * @type {boolean}
@@ -38,6 +43,21 @@ class FilterDimensionSetValue extends LitElement {
 		this.text = '';
 	}
 
+	get count() {
+		return this._count;
+	}
+
+	set count(val) {
+		if (val < 0) val = 0;
+		if (!Number.isInteger(val)) val = Math.floor(val);
+		if (Number.isNaN(val)) val = undefined;
+		const oldVal = this._count;
+		if (oldVal !== val) {
+			this._count = val;
+			this.requestUpdate('count', oldVal);
+		}
+	}
+
 	updated(changedProperties) {
 		super.updated(changedProperties);
 
@@ -45,11 +65,10 @@ class FilterDimensionSetValue extends LitElement {
 		changedProperties.forEach((oldValue, prop) => {
 			if (oldValue === undefined) return;
 
-			if (prop === 'disabled' || prop === 'selected' || prop === 'text') {
+			if (prop === 'count' || prop === 'disabled' || prop === 'selected' || prop === 'text') {
 				changes.set(prop, this[prop]);
 			}
 		});
-
 		if (changes.size > 0) {
 			/** @ignore */
 			this.dispatchEvent(new CustomEvent('d2l-filter-dimension-set-value-data-change', {
@@ -59,7 +78,6 @@ class FilterDimensionSetValue extends LitElement {
 			}));
 		}
 	}
-
 }
 
 customElements.define('d2l-filter-dimension-set-value', FilterDimensionSetValue);

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

@@ -103,6 +103,7 @@ class FilterDimensionSet extends LitElement {
 		const valueNodes = this._getSlottedNodes();
 		const values = valueNodes.map(value => {
 			return {
+				count: value.count,
 				disabled: value.disabled,
 				key: value.key,
 				selected: value.selected,

package/components/filter/filter.js

@@ -16,10 +16,11 @@ import '../selection/selection-select-all.js';
 import '../selection/selection-summary.js';
 
 import { bodyCompactStyles, bodySmallStyles, bodyStandardStyles } from '../typography/styles.js';
-import { css, html, LitElement } from 'lit';
+import { css, html, LitElement, nothing } from 'lit';
 import { announce } from '../../helpers/announce.js';
 import { classMap } from 'lit/directives/class-map.js';
 import { FocusMixin } from '../../mixins/focus-mixin.js';
+import { formatNumber } from '@brightspace-ui/intl/lib/number.js';
 import { ifDefined } from 'lit/directives/if-defined.js';
 import { LocalizeCoreElement } from '../../helpers/localize-core-element.js';
 import { offscreenStyles } from '../offscreen/offscreen.js';
@@ -120,12 +121,16 @@ class Filter extends FocusMixin(LocalizeCoreElement(RtlMixin(LitElement))) {
 				white-space: nowrap;
 			}
 
-			.d2l-filter-dimension-set-value-text {
+			.d2l-filter-dimension-set-value {
 				color: var(--d2l-color-ferrite);
+				display: flex;
+				gap: 0.45rem;
 				line-height: unset;
+				overflow: hidden;
 			}
 
-			d2l-list-item[disabled] .d2l-filter-dimension-set-value-text {
+			d2l-list-item[disabled] .d2l-filter-dimension-set-value,
+			d2l-list-item[disabled] .d2l-body-small {
 				color: var(--d2l-color-chromite);
 			}
 
@@ -417,7 +422,10 @@ class Filter extends FocusMixin(LocalizeCoreElement(RtlMixin(LitElement))) {
 						label="${item.text}"
 						selectable
 						?selected="${item.selected}">
-						<div class="d2l-filter-dimension-set-value-text d2l-body-compact">${item.text}</div>
+						<div class="d2l-filter-dimension-set-value d2l-body-compact">
+							<div class="d2l-filter-dimension-set-value-text">${item.text}</div>
+							${item.count !== undefined ? html`<div class="d2l-body-small">(${formatNumber(item.count)})</div>` : nothing}
+						</div>
 					</d2l-list-item>
 				`)}
 			</d2l-list>

package/custom-elements.json

@@ -167,6 +167,10 @@
           "description": "Type of the alert being displayed",
           "type": "'default'|'critical'|'success'|'warning'",
           "default": "\"default\""
+        },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
         }
       ],
       "events": [
@@ -326,6 +330,10 @@
           "description": "Renders in compact mode, displaying only the last item",
           "type": "boolean",
           "default": "false"
+        },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
         }
       ],
       "slots": [
@@ -691,6 +699,10 @@
           "attribute": "summary",
           "description": "Summary of the calendar for accessibility",
           "type": "string"
+        },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
         }
       ],
       "events": [
@@ -1198,6 +1210,10 @@
           "type": "'count'|'notification'",
           "default": "\"count\""
         },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
+        },
         {
           "name": "skeleton",
           "attribute": "skeleton",
@@ -1345,6 +1361,10 @@
           "type": "'count'|'notification'",
           "default": "\"count\""
         },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
+        },
         {
           "name": "skeleton",
           "attribute": "skeleton",
@@ -1628,6 +1648,10 @@
           "type": "boolean",
           "default": "false"
         },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
+        },
         {
           "name": "asyncContainerCustom",
           "type": "boolean"
@@ -1733,6 +1757,10 @@
           "type": "number",
           "default": "600"
         },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
+        },
         {
           "name": "asyncContainerCustom",
           "type": "boolean"
@@ -2213,6 +2241,10 @@
           "description": "Optionally render a d2l-focus-trap around the dropdown content",
           "type": "boolean",
           "default": "false"
+        },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
         }
       ],
       "events": [
@@ -2582,6 +2614,10 @@
           "description": "Optionally render a d2l-focus-trap around the dropdown content",
           "type": "boolean",
           "default": "false"
+        },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
         }
       ],
       "events": [
@@ -2951,6 +2987,10 @@
           "description": "Optionally render a d2l-focus-trap around the dropdown content",
           "type": "boolean",
           "default": "false"
+        },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
         }
       ],
       "events": [
@@ -3262,6 +3302,11 @@
           "description": "REQUIRED: Unique key to represent this value in the dimension",
           "type": "string"
         },
+        {
+          "name": "count",
+          "description": "Count for the value in the list. If no count is provided, no count will be displayed",
+          "type": "number"
+        },
         {
           "name": "disabled",
           "description": "Whether this value in the filter is disabled or not",
@@ -3288,6 +3333,12 @@
           "description": "REQUIRED: Unique key to represent this value in the dimension",
           "type": "string"
         },
+        {
+          "name": "count",
+          "attribute": "count",
+          "description": "Count for the value in the list. If no count is provided, no count will be displayed",
+          "type": "number"
+        },
         {
           "name": "disabled",
           "attribute": "disabled",
@@ -3468,6 +3519,10 @@
           "name": "openerType",
           "type": "string",
           "default": "\"DEFAULT\""
+        },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
         }
       ],
       "events": [
@@ -3512,6 +3567,10 @@
           "description": "The text displayed in this component's label (hidden when default is used)",
           "type": "string",
           "default": "\"\\\"Active Filters:\\\"\""
+        },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
         }
       ]
     },
@@ -3558,6 +3617,10 @@
           "description": "Indicates if the filter is open",
           "type": "boolean",
           "default": "false"
+        },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
         }
       ],
       "events": [
@@ -3633,6 +3696,10 @@
           "name": "errors",
           "type": "object",
           "default": "[]"
+        },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
         }
       ]
     },
@@ -3707,6 +3774,10 @@
           "description": "Indicates that the form should interrupt and warn on navigation if the user has unsaved changes on native elements.",
           "type": "boolean",
           "default": "false"
+        },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
         }
       ],
       "events": [
@@ -3760,6 +3831,10 @@
           "description": "Indicates that the form should interrupt and warn on navigation if the user has unsaved changes on native elements.",
           "type": "boolean",
           "default": "false"
+        },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
         }
       ],
       "events": [
@@ -3840,6 +3915,10 @@
           "attribute": "name",
           "description": "Name of the form control. Submitted with the form as part of a name/value pair.",
           "type": "string"
+        },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
         }
       ]
     },
@@ -4442,6 +4521,10 @@
           "attribute": "name",
           "description": "Name of the form control. Submitted with the form as part of a name/value pair.",
           "type": "string"
+        },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
         }
       ],
       "events": [
@@ -4508,6 +4591,10 @@
           "description": "Renders the input as a [skeleton loader](https://github.com/BrightspaceUI/core/tree/main/components/skeleton)",
           "type": "boolean",
           "default": "false"
+        },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
         }
       ]
     },
@@ -4739,6 +4826,10 @@
           "attribute": "name",
           "description": "Name of the form control. Submitted with the form as part of a name/value pair.",
           "type": "string"
+        },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
         }
       ],
       "events": [
@@ -4926,6 +5017,10 @@
           "attribute": "name",
           "description": "Name of the form control. Submitted with the form as part of a name/value pair.",
           "type": "string"
+        },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
         }
       ],
       "events": [
@@ -5092,6 +5187,10 @@
           "attribute": "name",
           "description": "Name of the form control. Submitted with the form as part of a name/value pair.",
           "type": "string"
+        },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
         }
       ],
       "events": [
@@ -5432,6 +5531,10 @@
           "attribute": "name",
           "description": "Name of the form control. Submitted with the form as part of a name/value pair.",
           "type": "string"
+        },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
         }
       ],
       "events": [
@@ -5630,6 +5733,10 @@
           "attribute": "name",
           "description": "Name of the form control. Submitted with the form as part of a name/value pair.",
           "type": "string"
+        },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
         }
       ],
       "events": [
@@ -5738,6 +5845,10 @@
           "description": "Value of the input",
           "type": "string",
           "default": "\"\""
+        },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
         }
       ],
       "events": [
@@ -6100,6 +6211,10 @@
           "description": "Name of the form control. Submitted with the form as part of a name/value pair.",
           "type": "string"
         },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
+        },
         {
           "name": "skeleton",
           "attribute": "skeleton",
@@ -6339,6 +6454,10 @@
           "description": "Name of the form control. Submitted with the form as part of a name/value pair.",
           "type": "string"
         },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
+        },
         {
           "name": "skeleton",
           "attribute": "skeleton",
@@ -6577,6 +6696,10 @@
           "attribute": "name",
           "description": "Name of the form control. Submitted with the form as part of a name/value pair.",
           "type": "string"
+        },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
         }
       ],
       "events": [
@@ -6754,6 +6877,10 @@
           "attribute": "name",
           "description": "Name of the form control. Submitted with the form as part of a name/value pair.",
           "type": "string"
+        },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
         }
       ],
       "events": [
@@ -7052,6 +7179,10 @@
           "type": "'normal'|'none'",
           "default": "\"normal\""
         },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
+        },
         {
           "name": "dragHandleText",
           "attribute": "drag-handle-text",
@@ -7189,6 +7320,10 @@
           "description": "Whether all pages can be selected",
           "type": "boolean",
           "default": "false"
+        },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
         }
       ],
       "slots": [
@@ -7316,6 +7451,10 @@
           "type": "'normal'|'none'",
           "default": "\"normal\""
         },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
+        },
         {
           "name": "dragHandleText",
           "attribute": "drag-handle-text",
@@ -7489,6 +7628,10 @@
           "description": "Disables the handle",
           "type": "boolean",
           "default": "false"
+        },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
         }
       ],
       "events": [
@@ -7748,6 +7891,10 @@
           "type": "'normal'|'none'",
           "default": "\"normal\""
         },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
+        },
         {
           "name": "dragHandleText",
           "attribute": "drag-handle-text",
@@ -8370,6 +8517,10 @@
         }
       ],
       "properties": [
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
+        },
         {
           "name": "text",
           "attribute": "text",
@@ -8566,6 +8717,10 @@
           "description": "REQUIRED: Current number of completed units.\nValid values: A number between 0 and max",
           "type": "number",
           "default": "0"
+        },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
         }
       ]
     },
@@ -8638,6 +8793,10 @@
           "description": "REQUIRED: Current number of completed units.\nValid values: A number between 0 and max",
           "type": "number",
           "default": "0"
+        },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
         }
       ]
     },
@@ -8697,6 +8856,10 @@
           "description": "REQUIRED: Current number of completed units.\nValid values: A number between 0 and max",
           "type": "number",
           "default": "0"
+        },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
         }
       ]
     },
@@ -8767,6 +8930,10 @@
           "description": "Whether the component is active or inactive",
           "type": "boolean",
           "default": "false"
+        },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
         }
       ],
       "events": [
@@ -8969,6 +9136,10 @@
           "name": "openerType",
           "type": "string",
           "default": "\"DEFAULT\""
+        },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
         }
       ],
       "events": [
@@ -9029,6 +9200,10 @@
           "description": "The number of additional items to load.",
           "type": "number",
           "default": "50"
+        },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
         }
       ],
       "events": [
@@ -9203,6 +9378,10 @@
           "description": "REQUIRED: Text for the dropdown opener button",
           "type": "string"
         },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
+        },
         {
           "name": "requiresSelection",
           "attribute": "requires-selection",
@@ -9416,6 +9595,10 @@
           "description": "REQUIRED: The text for the action",
           "type": "string"
         },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
+        },
         {
           "name": "requiresSelection",
           "attribute": "requires-selection",
@@ -9564,6 +9747,10 @@
         }
       ],
       "properties": [
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
+        },
         {
           "name": "selectionFor",
           "attribute": "selection-for",
@@ -9606,6 +9793,10 @@
           "type": "boolean",
           "default": "false"
         },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
+        },
         {
           "name": "selectionFor",
           "attribute": "selection-for",
@@ -9646,6 +9837,10 @@
           "description": "Text to display if no items are selected",
           "type": "string"
         },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
+        },
         {
           "name": "selectionFor",
           "attribute": "selection-for",
@@ -9995,6 +10190,10 @@
           "name": "onIcon",
           "type": "TemplateResult<1>"
         },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
+        },
         {
           "name": "disabled",
           "attribute": "disabled",
@@ -10402,6 +10601,10 @@
           "type": "number",
           "default": "-1"
         },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
+        },
         {
           "name": "arrowKeysDirection",
           "type": "string",
@@ -10470,6 +10673,10 @@
           "description": "Enables the option to clear a tag list item. The `d2l-tag-list-item-clear` event will be dispatched when the user selects to delete the item. The consumer must handle the actual item deletion.",
           "type": "boolean",
           "default": "false"
+        },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
         }
       ],
       "events": [
@@ -10522,6 +10729,10 @@
           "type": "number",
           "default": "0"
         },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
+        },
         {
           "name": "arrowKeysDirection",
           "type": "string",
@@ -10567,6 +10778,10 @@
           "description": "Enables the option to clear a tag list item. The `d2l-tag-list-item-clear` event will be dispatched when the user selects to delete the item. The consumer must handle the actual item deletion.",
           "type": "boolean",
           "default": "false"
+        },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
         }
       ],
       "events": [
@@ -10914,6 +11129,10 @@
           "description": "Whether content fills the screen or not",
           "type": "'fullscreen'|'normal'",
           "default": "\"fullscreen\""
+        },
+        {
+          "name": "documentLocaleSettings",
+          "default": "\"getDocumentLocaleSettings()\""
         }
       ],
       "events": [

package/mixins/localize-mixin.js

@@ -11,16 +11,15 @@ export const LocalizeMixin = dedupeMixin(superclass => class extends superclass
 		};
 	}
 
+	static documentLocaleSettings = getDocumentLocaleSettings();
+
 	constructor() {
 		super();
-
-		this.__documentLocaleSettings = getDocumentLocaleSettings();
 		this.__resourcesLoadedPromise = new Promise((resolve) => {
 			let first = true;
 			this.__languageChangeCallback = () => {
 				if (!this._hasResources()) return;
-				const possibleLanguages = this._generatePossibleLanguages();
-				const localizeResources = this.constructor._getAllLocalizeResources(possibleLanguages);
+				const localizeResources = this.constructor._getAllLocalizeResources();
 				const resourcesLoadedPromise = Promise.all(localizeResources);
 				resourcesLoadedPromise
 					.then((results) => {
@@ -45,18 +44,17 @@ export const LocalizeMixin = dedupeMixin(superclass => class extends superclass
 		});
 
 		this.__updatedProperties = new Map();
-
 	}
 
 	connectedCallback() {
 		super.connectedCallback();
-		this.__documentLocaleSettings.addChangeListener(this.__languageChangeCallback);
+		this.constructor.documentLocaleSettings.addChangeListener(this.__languageChangeCallback);
 		this.__languageChangeCallback();
 	}
 
 	disconnectedCallback() {
 		super.disconnectedCallback();
-		this.__documentLocaleSettings.removeChangeListener(this.__languageChangeCallback);
+		this.constructor.documentLocaleSettings.removeChangeListener(this.__languageChangeCallback);
 		this.__updatedProperties.clear();
 	}
 
@@ -130,49 +128,30 @@ export const LocalizeMixin = dedupeMixin(superclass => class extends superclass
 
 	}
 
-	_generatePossibleLanguages() {
-		const langs = new Set();
-
-		let docLang = this.__documentLocaleSettings.language;
-		if (docLang) {
-			docLang = docLang.toLowerCase();
-			langs.add(docLang);
-
-			if (docLang.indexOf('-') !== -1) {
-				const baseDocLang = docLang.split('-')[0];
-				langs.add(baseDocLang);
-			}
-		}
-
-		let docFallbackLang = this.__documentLocaleSettings.fallbackLanguage;
-		if (docFallbackLang) {
-			docFallbackLang = docFallbackLang.toLowerCase();
-			langs.add(docFallbackLang);
+	static _generatePossibleLanguages(config) {
 
-			if (docFallbackLang.indexOf('-') !== -1) {
-				const baseDocFallbackLang = docFallbackLang.split('-')[0];
-				langs.add(baseDocFallbackLang);
-			}
-		}
+		if (config?.useBrowserLangs) return navigator.languages.map(e => e.toLowerCase()).concat('en');
 
-		langs.add('en-us');
-		langs.add('en');
+		const { language, fallbackLanguage } = this.documentLocaleSettings;
+		const langs = [ language, fallbackLanguage ]
+			.filter(e => e)
+			.map(e => [ e.toLowerCase(), e.split('-')[0] ])
+			.flat();
 
-		return Array.from(langs);
+		return Array.from(new Set([ ...langs, 'en-us', 'en' ]));
 	}
 
-	static _getAllLocalizeResources(possibleLanguages, config = this.localizeConfig) {
+	static _getAllLocalizeResources(config = this.localizeConfig) {
 		let resourcesLoadedPromises = [];
 		const superCtor = Object.getPrototypeOf(this);
 		// get imported terms for each config, head up the chain to get them all
 		if ('_getAllLocalizeResources' in superCtor) {
-			// eslint-disable-next-line no-prototype-builtins
-			const superConfig = superCtor.hasOwnProperty('localizeConfig') && superCtor.localizeConfig.importFunc ? superCtor.localizeConfig : config;
-			resourcesLoadedPromises = superCtor._getAllLocalizeResources(possibleLanguages, superConfig);
+			const superConfig = Object.hasOwn(superCtor, 'localizeConfig') && superCtor.localizeConfig.importFunc ? superCtor.localizeConfig : config;
+			resourcesLoadedPromises = superCtor._getAllLocalizeResources(superConfig);
 		}
-		// eslint-disable-next-line no-prototype-builtins
-		if (this.hasOwnProperty('getLocalizeResources') || this.hasOwnProperty('resources')) {
-			const res = this.getLocalizeResources([...possibleLanguages], config);
+		if (Object.hasOwn(this, 'getLocalizeResources') || Object.hasOwn(this, 'resources')) {
+			const possibleLanguages = this._generatePossibleLanguages(config);
+			const res = this.getLocalizeResources(possibleLanguages, config);
 			resourcesLoadedPromises.push(res);
 		}
 		return resourcesLoadedPromises;

package/mixins/localize-mixin.md

@@ -77,13 +77,12 @@ class MyComponent extends LocalizeDynamicMixin(LitElement) {
        // Import path must be relative
       importFunc: async lang => (await import(`../lang/${lang}.js`)).default,
       // Optionally enable OSLO
-      osloCollection: 'my-project\\myComponent',
+      osloCollection: '@d2l\\my-project\\myComponent',
     };
   }
 }
 ```
-
-When using this method, depending on various user settings, it's possible that a language file that does not exist will be requested, resulting in a network error (404). In production, your build system should prevent this by transpiling the variable dynamic import into a `switch` statement.
+Occasionally, it may be desirable to localize based on the user's browser settings. To do this, add `useBrowserLangs: true` to your `localizeConfig` object. This option should only be used if *all* supported *locales* have corresponding files named with their 4-character locale code, and all supported *languages*, in addition, have 2-character files. (e.g. `en-us.js`, `en-ca.js` and `en.js`)
 
 If your build system does not support variable dynamic imports, you'll need to manually set up imports for each supported language:
 

package/package.json

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