@brightspace-ui/labs 1.1.1 → 1.2.1

package/README.md

@@ -12,59 +12,42 @@ Install from NPM:
 npm install @brightspace-ui/labs
 ```
 
-## README Index
-
-
-## Developing, Testing and Contributing
+## Developing 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
 
+To run the full suite of tests:
+
 ```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
+Alternatively, tests can be selectively run:
 
-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.
+```shell
+# eslint
+npm run lint:eslint
 
-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.
+# stylelint
+npm run lint:style
 
-To run the tests locally to help troubleshoot or develop new tests, first install these dependencies:
+# translations
+npm run test:translations
 
-```shell
-npm install @brightspace-ui/visual-diff@X mocha@Y puppeteer@Z  --no-save
+# unit tests
+npm run test:unit
 ```
 
-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:
+This repo uses [@brightspace-ui/testing](https://github.com/BrightspaceUI/testing)'s vdiff command to perform visual regression testing:
 
 ```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
+# vdiff
+npm run test:vdiff
+
+# re-generate goldens
+npm run test:vdiff golden
 ```
 
 ### Running the demos
@@ -75,41 +58,8 @@ To start a [@web/dev-server](https://modern-web.dev/docs/dev-server/overview/) t
 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).
+### Versioning and Releasing
 
-Maintenance branch names should be of the form: `+([0-9])?(.{+([0-9]),x}).x`.
+This repo is configured to use `semantic-release`. Commits prefixed with `fix:` and `feat:` will trigger patch and minor releases when merged to `main`.
 
-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)
+To learn how to create major releases and release from maintenance branches, refer to the [semantic-release GitHub Action](https://github.com/BrightspaceUI/actions/tree/main/semantic-release) documentation.

package/package.json

@@ -4,35 +4,30 @@
   "type": "module",
   "repository": "https://github.com/BrightspaceUI/labs.git",
   "exports": {
+    "./components/opt-in-flyout.js": "./src/components/opt-in-flyout/opt-in-flyout.js",
+    "./components/opt-out-flyout.js": "./src/components/opt-in-flyout/opt-out-flyout.js",
+    "./components/opt-out-reason.js": "./src/components/opt-in-flyout/opt-out-reason.js",
     "./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": "npm run lint:eslint && 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"
+    "test": "npm run lint && npm run test:translations && npm run test:unit",
+    "test:translations": "mfv -e -s en -p ./lang/ -i untranslated",
+    "test:unit": "d2l-test-runner"
   },
   "author": "D2L Corporation",
   "license": "Apache-2.0",
   "devDependencies": {
-    "@babel/core": "^7",
-    "@babel/eslint-parser": "^7",
     "@brightspace-ui/stylelint-config": "^0.8",
-    "@open-wc/testing": "^2",
-    "@web/dev-server": "^0.2",
-    "@web/test-runner": "^0.16",
+    "@brightspace-ui/testing": "^0.28",
+    "@web/dev-server": "^0.3",
     "eslint": "^8",
-    "eslint-config-brightspace": "^0.23",
-    "eslint-plugin-html": "^7",
-    "eslint-plugin-import": "^2",
-    "eslint-plugin-lit": "^1",
-    "eslint-plugin-sort-class-members": "^1",
-    "lit-analyzer": "^1",
+    "eslint-config-brightspace": "^0.25",
+    "messageformat-validator": "^2",
     "stylelint": "^15"
   },
   "files": [
@@ -46,5 +41,5 @@
     "@brightspace-ui/core": "^2",
     "lit": "^2"
   },
-  "version": "1.1.1"
+  "version": "1.2.1"
 }

package/src/components/localize-labs-element.js

@@ -0,0 +1,11 @@
+import { LocalizeDynamicMixin } from '@brightspace-ui/core/mixins/localize-dynamic-mixin.js';
+
+export const LocalizeLabsElement = (superclass) => class extends LocalizeDynamicMixin(superclass) {
+
+	static get localizeConfig() {
+		return {
+			importFunc: async lang => (await import(`../lang/${lang}.js`)).default
+		};
+	}
+
+};

package/src/components/opt-in-flyout/README.md

@@ -0,0 +1,59 @@
+# Opt-in/Opt-out Flyouts
+
+The `<d2l-labs-opt-in-flyout>` and `<d2l-labs-opt-out-flyout>` can be used in applications to enable users to opt-in or out of new experiences.
+
+<!-- docs: start hidden content -->
+### Properties
+
+| Property | Type | Description |
+|---|---|---|
+| `opened` | Boolean, default: `false` | Indicates the opened or closed state of the flyout |
+| `flyout-title` | String, required | Title to display at the top of the flyout |
+| `short-description` | String |Descriptive text shown beneath the `flyout-title` |
+| `long-description` | String | Additional text shown beneath `short-description` |
+| `tab-position` | String, default: `'right'` | Position to display the expand/collapse tab. Can either be an integer percentage (including the `%` character) or the string `left`, `right`, or `center`/`centre`. |
+| `tutorial-link` | String | A URL for a tutorial of the new experience or feature |
+| `help-docs-link` | String | A URL for help documentation on the new experience or feature |
+
+Additional properties for `<d2l-labs-opt-out-flyout>`:
+
+| Property | Type | Description |
+|---|---|---|
+| `hide-reason` | Boolean, default: `false` | Hides the reason field from the opt-out dialog |
+| `hide-feedback` | Boolean, default: `false` | Hides the feedback textarea field from the opt-out dialog |
+
+If both `hide-reason` _and_ `hide-feedback` are specified, the opt-out dialog will not display.
+
+### Events
+* `flyout-opened`: flyout was expanded
+* `flyout-closed`: flyout was collapsed
+* `opt-in`: *Turn it on* / *Leave it on* button was clicked
+* `opt-out`: *Leave it off* / *Turn it off* button was clicked
+<!-- docs: end hidden content -->
+
+## Opt-out Reasons
+
+By default, `<d2l-labs-opt-out-flyout>` will make the following opt-out reasons available to the user, in addition to "other":
+
+| key | English text |
+| ----------------------- | ----------------------------------------------- |
+| `NotReadyForSomethingNew` | It's not a good time for me to try this version |
+| `MissingFeature` | It's missing a feature that I use |
+| `JustCheckingSomething` | Just switching back to check something |
+| `PreferOldExperience` | I think the old version is a better experience |
+
+To provide custom reasons, place `<d2l-labs-opt-out-reason>` elements as children of `<d2l-labs-opt-out-flyout>`.
+
+<!-- docs: start hidden content -->
+### Properties
+
+| Property | Type | Description |
+|---|---|---|
+| `key` | String, required | Uniquely identifies the opt-out reason |
+| `text` | String, required | Text that will be displayed to the user |
+<!-- docs: end hidden content -->
+
+When the `opt-out` event is fired from `<d2l-labs-opt-out-flyout>`, its `detail` will contain:
+
+* `reason`: unique identifier for the opt-out reason
+* `feedback`: optional feedback provided by the user