@brightspace-ui/labs 1.0.0

package/LICENSE

@@ -0,0 +1,201 @@
+Apache License
+						Version 2.0, January 2004
+						http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+	"License" shall mean the terms and conditions for use, reproduction,
+	and distribution as defined by Sections 1 through 9 of this document.
+
+	"Licensor" shall mean the copyright owner or entity authorized by
+	the copyright owner that is granting the License.
+
+	"Legal Entity" shall mean the union of the acting entity and all
+	other entities that control, are controlled by, or are under common
+	control with that entity. For the purposes of this definition,
+	"control" means (i) the power, direct or indirect, to cause the
+	direction or management of such entity, whether by contract or
+	otherwise, or (ii) ownership of fifty percent (50%) or more of the
+	outstanding shares, or (iii) beneficial ownership of such entity.
+
+	"You" (or "Your") shall mean an individual or Legal Entity
+	exercising permissions granted by this License.
+
+	"Source" form shall mean the preferred form for making modifications,
+	including but not limited to software source code, documentation
+	source, and configuration files.
+
+	"Object" form shall mean any form resulting from mechanical
+	transformation or translation of a Source form, including but
+	not limited to compiled object code, generated documentation,
+	and conversions to other media types.
+
+	"Work" shall mean the work of authorship, whether in Source or
+	Object form, made available under the License, as indicated by a
+	copyright notice that is included in or attached to the work
+	(an example is provided in the Appendix below).
+
+	"Derivative Works" shall mean any work, whether in Source or Object
+	form, that is based on (or derived from) the Work and for which the
+	editorial revisions, annotations, elaborations, or other modifications
+	represent, as a whole, an original work of authorship. For the purposes
+	of this License, Derivative Works shall not include works that remain
+	separable from, or merely link (or bind by name) to the interfaces of,
+	the Work and Derivative Works thereof.
+
+	"Contribution" shall mean any work of authorship, including
+	the original version of the Work and any modifications or additions
+	to that Work or Derivative Works thereof, that is intentionally
+	submitted to Licensor for inclusion in the Work by the copyright owner
+	or by an individual or Legal Entity authorized to submit on behalf of
+	the copyright owner. For the purposes of this definition, "submitted"
+	means any form of electronic, verbal, or written communication sent
+	to the Licensor or its representatives, including but not limited to
+	communication on electronic mailing lists, source code control systems,
+	and issue tracking systems that are managed by, or on behalf of, the
+	Licensor for the purpose of discussing and improving the Work, but
+	excluding communication that is conspicuously marked or otherwise
+	designated in writing by the copyright owner as "Not a Contribution."
+
+	"Contributor" shall mean Licensor and any individual or Legal Entity
+	on behalf of whom a Contribution has been received by Licensor and
+	subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+	this License, each Contributor hereby grants to You a perpetual,
+	worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+	copyright license to reproduce, prepare Derivative Works of,
+	publicly display, publicly perform, sublicense, and distribute the
+	Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+	this License, each Contributor hereby grants to You a perpetual,
+	worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+	(except as stated in this section) patent license to make, have made,
+	use, offer to sell, sell, import, and otherwise transfer the Work,
+	where such license applies only to those patent claims licensable
+	by such Contributor that are necessarily infringed by their
+	Contribution(s) alone or by combination of their Contribution(s)
+	with the Work to which such Contribution(s) was submitted. If You
+	institute patent litigation against any entity (including a
+	cross-claim or counterclaim in a lawsuit) alleging that the Work
+	or a Contribution incorporated within the Work constitutes direct
+	or contributory patent infringement, then any patent licenses
+	granted to You under this License for that Work shall terminate
+	as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+	Work or Derivative Works thereof in any medium, with or without
+	modifications, and in Source or Object form, provided that You
+	meet the following conditions:
+
+	(a) You must give any other recipients of the Work or
+		Derivative Works a copy of this License; and
+
+	(b) You must cause any modified files to carry prominent notices
+		stating that You changed the files; and
+
+	(c) You must retain, in the Source form of any Derivative Works
+		that You distribute, all copyright, patent, trademark, and
+		attribution notices from the Source form of the Work,
+		excluding those notices that do not pertain to any part of
+		the Derivative Works; and
+
+	(d) If the Work includes a "NOTICE" text file as part of its
+		distribution, then any Derivative Works that You distribute must
+		include a readable copy of the attribution notices contained
+		within such NOTICE file, excluding those notices that do not
+		pertain to any part of the Derivative Works, in at least one
+		of the following places: within a NOTICE text file distributed
+		as part of the Derivative Works; within the Source form or
+		documentation, if provided along with the Derivative Works; or,
+		within a display generated by the Derivative Works, if and
+		wherever such third-party notices normally appear. The contents
+		of the NOTICE file are for informational purposes only and
+		do not modify the License. You may add Your own attribution
+		notices within Derivative Works that You distribute, alongside
+		or as an addendum to the NOTICE text from the Work, provided
+		that such additional attribution notices cannot be construed
+		as modifying the License.
+
+	You may add Your own copyright statement to Your modifications and
+	may provide additional or different license terms and conditions
+	for use, reproduction, or distribution of Your modifications, or
+	for any such Derivative Works as a whole, provided Your use,
+	reproduction, and distribution of the Work otherwise complies with
+	the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+	any Contribution intentionally submitted for inclusion in the Work
+	by You to the Licensor shall be under the terms and conditions of
+	this License, without any additional terms or conditions.
+	Notwithstanding the above, nothing herein shall supersede or modify
+	the terms of any separate license agreement you may have executed
+	with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+	names, trademarks, service marks, or product names of the Licensor,
+	except as required for reasonable and customary use in describing the
+	origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+	agreed to in writing, Licensor provides the Work (and each
+	Contributor provides its Contributions) on an "AS IS" BASIS,
+	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+	implied, including, without limitation, any warranties or conditions
+	of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+	PARTICULAR PURPOSE. You are solely responsible for determining the
+	appropriateness of using or redistributing the Work and assume any
+	risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+	whether in tort (including negligence), contract, or otherwise,
+	unless required by applicable law (such as deliberate and grossly
+	negligent acts) or agreed to in writing, shall any Contributor be
+	liable to You for damages, including any direct, indirect, special,
+	incidental, or consequential damages of any character arising as a
+	result of this License or out of the use or inability to use the
+	Work (including but not limited to damages for loss of goodwill,
+	work stoppage, computer failure or malfunction, or any and all
+	other commercial damages or losses), even if such Contributor
+	has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+	the Work or Derivative Works thereof, You may choose to offer,
+	and charge a fee for, acceptance of support, warranty, indemnity,
+	or other liability obligations and/or rights consistent with this
+	License. However, in accepting such obligations, You may act only
+	on Your own behalf and on Your sole responsibility, not on behalf
+	of any other Contributor, and only if You agree to indemnify,
+	defend, and hold each Contributor harmless for any liability
+	incurred by, or claims asserted against, such Contributor by reason
+	of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+	To apply the Apache License to your work, attach the following
+	boilerplate notice, with the fields enclosed by brackets "{}"
+	replaced with your own identifying information. (Don't include
+	the brackets!)  The text should be enclosed in the appropriate
+	comment syntax for the file format. We also recommend that a
+	file or class name and description of purpose be included on the
+	same "printed page" as the copyright notice for easier
+	identification within third-party archives.
+
+Copyright 2022 D2L Corporation
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+	http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,115 @@
+# @brightspace-ui/labs
+
+[![NPM version](https://img.shields.io/npm/v/@brightspace-ui/labs.svg)](https://www.npmjs.org/package/@brightspace-ui/labs)
+
+A collection of experimental web components and tools for building Brightspace applications.
+
+## Installation
+
+Install from NPM:
+
+```shell
+npm install @brightspace-ui/labs
+```
+
+## README Index
+
+
+## Developing, Testing and Contributing
+
+After cloning the repo, run `npm install` to install dependencies.
+
+### Linting
+
+```shell
+# eslint and lit-analyzer
+npm run lint
+
+# eslint only
+npm run lint:eslint
+```
+
+### Testing
+
+```shell
+# lint & run headless unit tests
+npm test
+
+# unit tests only
+npm run test:headless
+
+# debug or run a subset of local unit tests
+npm run test:headless:watch
+```
+
+### Visual Diff Testing
+
+This repo uses the [@brightspace-ui/visual-diff utility](https://github.com/BrightspaceUI/visual-diff/) to compare current snapshots against a set of golden snapshots stored in source control.
+
+The golden snapshots in source control must be updated by the [visual-diff GitHub Action](https://github.com/BrightspaceUI/actions/tree/main/visual-diff).  If a pull request results in visual differences, a draft pull request with the new goldens will automatically be opened against its branch.
+
+To run the tests locally to help troubleshoot or develop new tests, first install these dependencies:
+
+```shell
+npm install @brightspace-ui/visual-diff@X mocha@Y puppeteer@Z  --no-save
+```
+
+Replace `X`, `Y` and `Z` with [the current versions](https://github.com/BrightspaceUI/actions/tree/main/visual-diff#current-dependency-versions) the action is using.
+
+Then run the tests:
+
+```shell
+# run visual-diff tests
+npx mocha './test/**/*.visual-diff.js' -t 10000
+# subset of visual-diff tests:
+npx mocha './test/**/*.visual-diff.js' -t 10000 -g some-pattern
+# update visual-diff goldens
+npx mocha './test/**/*.visual-diff.js' -t 10000 --golden
+```
+
+### Running the demos
+
+To start a [@web/dev-server](https://modern-web.dev/docs/dev-server/overview/) that hosts the demo pages and tests:
+
+```shell
+npm start
+```
+
+## Versioning & Releasing
+
+> TL;DR: Commits prefixed with `fix:` and `feat:` will trigger patch and minor releases when merged to `main`. Read on for more details...
+
+The [semantic-release GitHub Action](https://github.com/BrightspaceUI/actions/tree/main/semantic-release) is called from the `release.yml` GitHub Action workflow to handle version changes and releasing.
+
+### Version Changes
+
+All version changes should obey [semantic versioning](https://semver.org/) rules:
+1. **MAJOR** version when you make incompatible API changes,
+2. **MINOR** version when you add functionality in a backwards compatible manner, and
+3. **PATCH** version when you make backwards compatible bug fixes.
+
+The next version number will be determined from the commit messages since the previous release. Our semantic-release configuration uses the [Angular convention](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-angular) when analyzing commits:
+* Commits which are prefixed with `fix:` or `perf:` will trigger a `patch` release. Example: `fix: validate input before using`
+* Commits which are prefixed with `feat:` will trigger a `minor` release. Example: `feat: add toggle() method`
+* To trigger a MAJOR release, include `BREAKING CHANGE:` with a space or two newlines in the footer of the commit message
+* Other suggested prefixes which will **NOT** trigger a release: `build:`, `ci:`, `docs:`, `style:`, `refactor:` and `test:`. Example: `docs: adding README for new component`
+
+To revert a change, add the `revert:` prefix to the original commit message. This will cause the reverted change to be omitted from the release notes. Example: `revert: fix: validate input before using`.
+
+### Releases
+
+When a release is triggered, it will:
+* Update the version in `package.json`
+* Tag the commit
+* Create a GitHub release (including release notes)
+* Deploy a new package to NPM
+
+### Releasing from Maintenance Branches
+
+Occasionally you'll want to backport a feature or bug fix to an older release. `semantic-release` refers to these as [maintenance branches](https://semantic-release.gitbook.io/semantic-release/usage/workflow-configuration#maintenance-branches).
+
+Maintenance branch names should be of the form: `+([0-9])?(.{+([0-9]),x}).x`.
+
+Regular expressions are complicated, but this essentially means branch names should look like:
+* `1.15.x` for patch releases on top of the `1.15` release (after version `1.16` exists)
+* `2.x` for feature releases on top of the `2` release (after version `3` exists)

package/labs.serge.json

@@ -0,0 +1,9 @@
+{
+  "name": "labs",
+  "parser_plugin": {
+    "plugin": "parse_js"
+  },
+  "source_match": "en\\.js$",
+  "source_dir": "src/lang",
+  "output_file_path": "src/lang/%LANG%.js"
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@brightspace-ui/labs",
+  "description": "A collection of experimental web components and tools for building Brightspace applications.",
+  "type": "module",
+  "repository": "https://github.com/BrightspaceUI/labs.git",
+  "exports": {
+    "./controllers/computed-value.js": "./src/controllers/computed-values/computed-value.js",
+    "./controllers/computed-values.js": "./src/controllers/computed-values/computed-values.js"
+  },
+  "scripts": {
+    "lint": "npm run lint:eslint && npm run lint:lit && npm run lint:style",
+    "lint:eslint": "eslint . --ext .js,.html",
+    "lint:lit": "lit-analyzer \"src/**/*.js\" --strict",
+    "lint:style": "stylelint \"**/*.{js,html}\"",
+    "start": "web-dev-server --node-resolve --open --watch",
+    "test": "npm run lint && npm run test:headless",
+    "test:headless": "web-test-runner",
+    "test:headless:watch": "web-test-runner --watch"
+  },
+  "author": "D2L Corporation",
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@babel/core": "^7",
+    "@babel/eslint-parser": "^7",
+    "@brightspace-ui/stylelint-config": "^0.4",
+    "@open-wc/testing": "^2",
+    "@web/dev-server": "^0.1",
+    "@web/test-runner": "^0.13",
+    "eslint": "^8",
+    "eslint-config-brightspace": "^0.17",
+    "eslint-plugin-html": "^6",
+    "eslint-plugin-import": "^2",
+    "eslint-plugin-lit": "^1",
+    "eslint-plugin-sort-class-members": "^1",
+    "lit-analyzer": "^1",
+    "stylelint": "^14"
+  },
+  "files": [
+    "labs.serge.json",
+    "/src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@brightspace-ui/core": "^2",
+    "lit": "^2"
+  },
+  "version": "1.0.0"
+}

package/src/controllers/computed-values/README.md

@@ -0,0 +1,170 @@
+# ComputedValues Controller
+
+The `ComputedValues` (plural) controller allows you to define a collection of `ComputedValue` (singular) controllers. Each of these `ComputedValue` controllers holds a value that is dependent on other variables or properties within a component and will automatically update that value whenever the dependencies change.
+
+The main benefit of this controller is that it gives a quick and clean way of definining the update and computation logic of an instance member that is dependent on other members or properties.
+
+Some use cases for this controller include:
+* Computing values that you want to show in render, but whose computation is too expensive to perform every render (ex: filtering or sorting a list in the front end based on user input).
+* Asynchronously computing values whenever a dependency changes (ex: refetching a value from the API any time a specific property changes).
+* Creating a reusable controller that knows how to recompute a value based on dependencies.
+
+## `ComputedValues` vs `ComputedValue`
+
+Internally, the `ComputedValues` (plural) controller uses another controller called `ComputedValue` (singular). The `ComputedValue` controller holds the majority of the functionality that `ComputedValues` uses and the `ComputedValues` controller simply instantiates a collection of `ComputedValue` controllers and assigns them to itself for easy access.
+
+While it's possible to use the `ComputedValue` controller directly, it is recommended that the `ComputedValues` controller be used in most cases, since it makes it easier to create a collection of computed values. Direct use of the `ComputedValue` controller should be reserved for creating reusable controllers.
+
+## Usage
+
+Create an instance of the `ComputedValues` controller and assign it to a member variable. Pass the host and an array of objects to the constructor that each represent one value that will be computed based on dependencies.
+
+```js
+import ComputedValues from '@brightspace-ui/labs/controllers/computed-values.js';
+
+class DemoComponent extends LitElement {
+	static properties = {
+		firstName: { type: String },
+		lastName: { type: String }
+	};
+
+	constructor() {
+		super();
+		this.firstName = 'John';
+		this.lastName = 'Smith';
+	}
+
+	render() {
+		return html`
+			<p>
+				fullName: ${this._computed.fullName.value}<br>
+				screamingFullName: ${this._computed.screamingFullName.value}<br>
+                shortName: ${this._computed.shortName.value}<br>
+				asyncName: ${this._computed.asyncName.pending ? '<loading...>' : this._computed.asyncName.value}<br>
+			</p>
+		`;
+	}
+
+	_computed = new ComputedValues(this, [{
+		// This computed value is dependent on both firstName and lastName
+		name: 'fullName',
+		initialValue: '',
+		getDependencies: () => [this.firstName, this.lastName],
+		compute: (firstName, lastName) => `${firstName} ${lastName}`
+	}, {
+		// This computed value is dependent on the fullName computed value
+		name: 'screamingFullName',
+		initialValue: '',
+		getDependencies: () => [this._computed.fullName.value],
+		compute: (fullName) => fullName.toUpperCase()
+	}, {
+		// This computed value implements a custom shouldCompute method
+		name: 'shortName',
+		initialValue: '',
+		isAsync: true,
+		getDependencies: () => [this.firstName, this.lastName],
+		shouldCompute: (prevDeps, currDeps) => {
+			if (prevDeps === null) return true;
+
+			const [prevFirstName, prevLastName] = prevDeps;
+			const [currFirstName, currLastName] = currDeps;
+
+			return prevFirstName[0] !== currFirstName[0] || prevLastName !== currLastName;
+		},
+		compute: (firstName, lastName) => {
+			return `${firstName[0]}. ${lastName}`;
+		}
+	}, {
+		// This computed value is asynchronous
+		name: 'asyncName',
+		initialValue: '',
+		isAsync: true,
+		getDependencies: () => [this.firstName, this.lastName],
+		compute: async(firstName, lastName) => {
+			return await asyncApiCall(firstName, lastName);
+		}
+	}]);
+}
+```
+
+Check the demo page for additional working examples.
+
+## Compute Lifecycle
+
+There is a flow of steps that each `ComputedValue` instance follows in order to compute its value. Being aware of how this controller works is important to understand how best to make use of it.
+
+### Host `update`
+
+The compute lifecycle starts with the host executing its `update` method, which then triggers the controller's `hostUpdate`.
+
+All computation logic for this controller starts here. So, if the host's `update` method isn't called (for example by never triggering one or by explicitly using `shouldUpdate` to skip updates), then computes will never be called.
+
+This also means that `compute` functions should not look at the dom directly, since the logic for calculating the updated value happens before the render executes.
+
+### Controller `getDependencies` and `shouldCompute`
+
+The `getDependencies` and `shouldCompute` functions are important in order to decide whether to execute the `compute` function. As such, these two functions are called every host `update` for each `ComputedValue` instance.
+
+The `getDependencies` function must always be defined by the consumer, whereas the `shouldCompute` function has an internal default if the consumer does not define their own.
+
+The default `shouldCompute` function will do an indentity comparison for each of the previous and current dependencies one by one and return true immediately if one of the dependencies has changed.
+
+While this controller can be very helpful for making sure to only execute heavy computations when needed, be aware of the performance costs of using this approach. So, keep in mind what processes occur each `update` call.
+
+### Controller `compute`
+
+Once the `shouldCompute` function returns true during the `update` step, the `compute` function will be called.
+
+If the controller is set to run synchronously, the `compute` function will execute in its entirety and the return value will be assigned to the controller's `value` instance member. This all happens during the host's `update` step.
+
+If the controller is set to run asynchronously, the controller will call the `compute` function and expect a promise as the return value. It will update its async statuses as appropriate before continuing with the host's `update` step. Once the promise returned from the `compute` function resolves, the controller will assign the result to the controller's `value` instance member, it will update its async statuses as appropriate, and will then request and update from the host using `requestUpdate`.
+
+Note that if the controller is asynchronous and a controller's `compute` functions is called while a previous `compute` call is in progress, only the last `compute` function call will update the value and async statuses.
+
+## Order of `ComputeValue` Instances
+
+The compute lifecycle for each `ComputeValue` controller instance will be executed in its entirety before moving on to the next. This means that the order that these instances are defined in the array matters in some cases. If one of the controller instances is dependent on the result from another, then the one that is being depended on must come first in the order to make sure the most up-to-date value is passed to the dependant.
+
+## `ComputedValues` Instance Methods
+
+### Constructor
+
+| Parameter Name | Type | Description | Required |
+|---|---|---|---|
+| `host` | LitElement | The host for the controller. | Yes |
+| `valuesOptions` | Array | The array of objects that each define a computed value. | Yes |
+| `valuesOptions[i].name` | String | The name of the computed value. Used to assign the internal `ComputedValue` instance to the `ComputedValues` instance. | Yes |
+| `...valuesOptions[i]` | Object | The rest of the attributes for the object are passed to the internal `ComputedValue` instance constructor. See the `ComputedValue` constructor for details. | Yes |
+
+## `ComputedValues` Instance Members
+
+| Member Name | Type | Description |
+|---|---|---|
+|`this[name]` | `ComputedValue` controller | For each of the objects in the `valuesOptions` array, a `ComputedValue` controller is instantiated and assigned to a memeber on the `ComputedValues` controller instance.<br><br>For example, the following `ComputedValues` instance...<br><br><pre>class MyElement extends LitElement {<br>  _computed = new ComputedValues(this, [{<br>    name: 'myValue',<br>    ...<br>  }]);<br>}</pre><br>...will end up with a `ComputedValue` instance assigned to `this._computed.myValue`.<br><br>For details on what instance members each `ComputedValue` instance has, see the `ComputedValue` Instance Members section below. |
+
+## `ComputedValue` Instance Methods
+
+### Constructor
+
+| Parameter Name | Type | Description | Required |
+|---|---|---|---|
+| `host` | Lit Element | The host for the controller. | Yes |
+| `options` | Object | A collection of options for the controller. | Yes |
+| `options.getDependencies` | Function() : Array | The function used to get the array of dependencies for this value. Must return an array and the array should always be the same length. The previous and current dependencies will be used to decide whether or not to update, so they should be kept in the same order as well. | Yes |
+| `options.compute` | Function(...Any) : Any | The function used to calculate the computed value. It's passed the most recent dependencies every time it is called, and the return value is assigned to the controller value member before each render. | Yes |
+| `options.initialValue` | Any | The value of the controller value member before the first update occurs. | |
+| `options.shouldCompute` | Function(Array, Array) : Bool | The function used to decide whether or not to run the compute function.<br><br>This function is passed an array of the previous dependencies and an array of the current dependencies. It must return a boolean representing whether to call the compute function or not.<br><br>If not assigned, the default `shouldCompute` function will do an indentity comparison for each of the previous and current dependencies one by one and return true immediately if one of the dependencies has changed. | |
+| `options.isAsync` | Bool | This tells the controller whether the compute function is asynchronous. If this is true, the compute function must return a promise. | |
+| `options.shouldRequestUpdate` | Function(Object, Object) : Bool | This function is used to decide whether or not to call the host's `requestUpdate` method after an async `compute` function finished updating the value.<br><br>This function is passed an object that contains the value and async status before the compute finished executing, and one object with the current value and async status. It must return a boolean representing whether to call the `requestUpdate` method or not.<br><br>If not assigned, this defaults to a function that always returns true. | |
+
+## `ComputedValue` Instance Members
+
+| Member Name | Type | Description |
+|---|---|---|
+| `host` | LitElement | The host element of this controller. |
+| `value` | Any | This holds the computed value of the controller. |
+| `pending` | Bool | Only used when the controller is async. This will be true while an async compute is processing, and false otherwise. |
+| `success` | Bool\|Null | Only used when the controller is async. This will be set to true if the previous async compute resolved successfully. This will be set to false if the previous async compute threw an error. This will be set to null if no async compute function has completed yet. |
+| `error` | Any | Only used when the controller is async. This will hold error info in the event that previous async compute threw an error. This will be assigned null otherwise. |
+| `asyncStatus` | String | Only used when the controller is async. This holds a string representing the current async status of the controller.<br>`"initial"`: Before the first compute function is called.<br>`"pending"`: While an async compute function is in progress.<br>`"success"`: If the last async compute was successful (and another is not currently pending).<br>`"error"`: If the last async compute ended in error (and another is not currently pending). |
+| `computeComplete` | Promise | This member is assigned a promise whenever the value starts being computed, and that promise resolves when the value is done being computed. Note that this is intended to be used for testing and should not be relied on for normal use cases. |

package/src/controllers/computed-values/computed-value.js

@@ -0,0 +1,159 @@
+export const ASYNC_STATUSES = Object.freeze({
+	INITIAL: 'initial',
+	PENDING: 'pending',
+	SUCCESS: 'success',
+	ERROR: 'error'
+});
+
+function defaultShouldCompute(prevDependencies, currDependencies) {
+	// If no dependencies exist yet, then this is the first update
+	if (prevDependencies === null) {
+		return true;
+	}
+
+	return prevDependencies.some((prev, index) => prev !== currDependencies[index]);
+}
+
+export default class ComputedValue {
+	computeComplete = Promise.resolve();
+	error = null;
+	host;
+	pending = false;
+	success = null;
+	value;
+
+	constructor(host, options = {}) {
+		const {
+			compute,
+			shouldCompute = defaultShouldCompute,
+			getDependencies,
+			isAsync = false,
+			shouldRequestUpdate = () => true,
+			initialValue
+		} = options;
+
+		if (typeof compute !== 'function') {
+			throw new TypeError('Failed to initialize ComputedValueController: compute parameter must be a function.');
+		}
+
+		if (typeof getDependencies !== 'function') {
+			throw new TypeError('Failed to initialize ComputedValueController: getDependencies parameter must be a function.');
+		}
+
+		this._compute = compute;
+		this._shouldCompute = shouldCompute;
+		this._getDependencies = getDependencies;
+		this._isAsync = isAsync;
+		this._shouldRequestUpdate = shouldRequestUpdate;
+		this.value = initialValue;
+
+		(this.host = host).addController(this);
+	}
+
+	get asyncStatus() {
+		if (this.pending) {
+			return ASYNC_STATUSES.PENDING;
+		}
+
+		if (this.success === null) {
+			return ASYNC_STATUSES.INITIAL;
+		}
+
+		if (this.success) {
+			return ASYNC_STATUSES.SUCCESS;
+		}
+
+		return ASYNC_STATUSES.ERROR;
+	}
+
+	hostUpdate() {
+		const currDependencies = this._getDependencies();
+
+		if (this._shouldCompute(this._prevDependencies, currDependencies)) {
+			this._prevDependencies = currDependencies;
+			this._updateValue(currDependencies);
+		}
+	}
+
+	_compute;
+	_computeCompleteResolve = () => {};
+	_getDependencies;
+	_isAsync;
+	_latestPromise;
+	_prevDependencies = null;
+	_shouldCompute;
+	_shouldRequestUpdate;
+
+	_updateAsyncValue(dependencies) {
+		this._latestPromise = null; // Prevent any ongoing compute update from completing as this is the latest now
+
+		// If there's still an ongoing compute update, don't replace the computeComplete promise.
+		// Instead, this effectively extends the computeComplete promise resolution until the _latestPromise is done.
+		if (this.pending === false) {
+			this.computeComplete = new Promise((resolve) => {
+				this._computeCompleteResolve = resolve;
+			});
+		}
+		this.pending = true;
+
+		const promise = this._compute(...dependencies);
+		this._latestPromise = promise;
+
+		(async() => {
+			let newValue;
+			let success;
+			let error = null;
+
+			try {
+				newValue = await promise;
+				success = true;
+			} catch (err) {
+				error = err;
+				success = false;
+			}
+
+			// Make sure this promise is still the latest so as not to overwrite a more recent async value
+			if (this._latestPromise === promise) {
+				const prevState = {
+					value: this.value,
+					success: this.success,
+					error: this.error,
+					pending: this.pending
+				};
+
+				if (success) {
+					this.value = newValue;
+				}
+
+				this.success = success;
+				this.error = error;
+				this.pending = false;
+
+				const currState = {
+					value: this.value,
+					success: this.success,
+					error: this.error,
+					pending: this.pending
+				};
+
+				if (this._shouldRequestUpdate(prevState, currState)) {
+					this.host.requestUpdate();
+				}
+
+				this._computeCompleteResolve();
+			}
+		})();
+	}
+
+	_updateValue(dependencies) {
+		if (this._isAsync) {
+			this._updateAsyncValue(dependencies);
+		} else {
+			this.computeComplete = new Promise((resolve) => {
+				this._computeCompleteResolve = resolve;
+			});
+			this.value = this._compute(...dependencies);
+			this._computeCompleteResolve();
+		}
+	}
+}

package/src/controllers/computed-values/computed-values.js

@@ -0,0 +1,9 @@
+import ComputedValue from './computed-value.js';
+
+export default class ComputedValues {
+	constructor(host, valuesOptions = []) {
+		valuesOptions.forEach(({ name, ...options }) => {
+			this[name] = new ComputedValue(host, options);
+		});
+	}
+}

package/src/lang/ar.js

@@ -0,0 +1,4 @@
+/* eslint quotes: 0 */
+
+export default {
+};

package/src/lang/cy.js

@@ -0,0 +1,4 @@
+/* eslint quotes: 0 */
+
+export default {
+};

package/src/lang/da.js

@@ -0,0 +1,4 @@
+/* eslint quotes: 0 */
+
+export default {
+};

package/src/lang/de.js

@@ -0,0 +1,4 @@
+/* eslint quotes: 0 */
+
+export default {
+};

package/src/lang/en.js

@@ -0,0 +1,4 @@
+/* eslint quotes: 0 */
+
+export default {
+};

package/src/lang/es-es.js

@@ -0,0 +1,4 @@
+/* eslint quotes: 0 */
+
+export default {
+};

package/src/lang/es.js

@@ -0,0 +1,4 @@
+/* eslint quotes: 0 */
+
+export default {
+};

package/src/lang/fr-fr.js

@@ -0,0 +1,4 @@
+/* eslint quotes: 0 */
+
+export default {
+};

package/src/lang/fr.js

@@ -0,0 +1,4 @@
+/* eslint quotes: 0 */
+
+export default {
+};

package/src/lang/ja.js

@@ -0,0 +1,4 @@
+/* eslint quotes: 0 */
+
+export default {
+};

package/src/lang/ko.js

@@ -0,0 +1,4 @@
+/* eslint quotes: 0 */
+
+export default {
+};

package/src/lang/nl.js

@@ -0,0 +1,4 @@
+/* eslint quotes: 0 */
+
+export default {
+};

package/src/lang/pt.js

@@ -0,0 +1,4 @@
+/* eslint quotes: 0 */
+
+export default {
+};

package/src/lang/sv.js

@@ -0,0 +1,4 @@
+/* eslint quotes: 0 */
+
+export default {
+};

package/src/lang/tr.js

@@ -0,0 +1,4 @@
+/* eslint quotes: 0 */
+
+export default {
+};

package/src/lang/zh-cn.js

@@ -0,0 +1,4 @@
+/* eslint quotes: 0 */
+
+export default {
+};

package/src/lang/zh-tw.js

@@ -0,0 +1,4 @@
+/* eslint quotes: 0 */
+
+export default {
+};