@brightspace-ui-labs/user-feedback NPM

d2l-labs-user-feedback

Note: this is a "labs" component. While functional, these tasks are prerequisites to promotion to BrightspaceUI "official" status:
Design organization buy-in
design.d2l entry
Architectural sign-off
Continuous integration
Cross-browser testing
Unit tests (if applicable)
Accessibility tests
Visual diff tests
Localization with Serge (if applicable)
Demo page
README documentation

Elements for acquiring user feedback on our products

Installation

To install from NPM:

npm install @brightspace-ui-labs/user-feedback

Usage

d2l-labs-user-feedback-container

The wrapper for your feedback elements, this adds submit, cancel, and opt-out buttons and also handles the different states after the user submits.

Attributes

feedback-version: Starts at 1, increment this each time you change the feedback interior for versioning
feedback-application: The name of the application you want to provide feedback for, must be set up as an lms plugin
feedback-type: The type of the feedback you want to provide for the application, must be set up as an lms plugin
feedback-href: The root of the feedback hm domain
token: A token to use for the api calls
additional-fields: An object containing any other key/value pairs you would like to add to the feedback payload

	<d2l-labs-user-feedback-container prompt="Container Prompt"
		feedback-version="1"
		feedback-application="name-of-application"
		feedback-type="type-of-feedback"
		feedback-href="href-of-feedback-hm-domain-root"
		token="token"
	>
		<!-- slotted d2l-labs-user-feedback-text-input and d2l-labs-user-feedback-scale elements -->
	</d2l-labs-user-feedback-container>

d2l-labs-user-feedback-scale

A component where a user can select from a group of items on how they feel about something.

Attributes

prompt: The text prompt to list above the scale
serializeprefix: A prefix to prepend to the values when serializing

When the container submits, the scale will add these properties to the submitted post request

[serializeprefix]prompt
[serializeprefix]scaleValue
[serializeprefix]scaleOutOfValue
[serializeprefix]scaleText

<d2l-labs-user-feedback-scale prompt="How do you like using our product?">
	<!-- slotted scale items -->
</d2l-labs-user-feedback-scale>

d2l-labs-user-feedback-text-input

Attributes

defaultlabeltext: the default prompt for the text

<d2l-labs-user-feedback-text-input defaultlabeltext="Type something here"></d2l-labs-user-feedback-text-input>

Slotting in a feedback scale

This will cause a feedback scale to render on top of the text input, when the user selects an item, the item's selectedtextprompt value will be used as the prompt for the text input.

<d2l-labs-user-feedback-text-input defaultlabeltext="Type something here">
	<d2l-labs-user-feedback-scale prompt="How do you like using our product?">
		<d2l-labs-user-feedback-scale-item value="1" selectedtextprompt="Why don't you like it?">I don't like it</d2l-labs-user-feedback-scale-item>
		<d2l-labs-user-feedback-scale-item value="2" selectedtextprompt="What could be better?">It's alright</d2l-labs-user-feedback-scale-item>
		<d2l-labs-user-feedback-scale-item value="3" selectedtextprompt="Why do you like it?">It's good</d2l-labs-user-feedback-scale-item>
	</d2l-labs-user-feedback-scale>
</d2l-labs-user-feedback-text-input>

When the container submits, the text-input will add these properties to the submitted post request

[serializeprefix]textField
[serializeprefix]textFieldUserInput
(and the serialized result of a nested scale, if any)

d2l-labs-user-feedback-flyout

A component for placing your feedback items in a flyout tray that opens from the bottom of the screen. Will only appear after the container loads the hypermedia entities for submitting to the api, after the user has submitted feedback and closed the flyout, it disappears

<d2l-labs-user-feedback-flyout button-text="launch the feedback component">
	<!-- slotted d2l-labs-user-feedback-container -->
</d2l-labs-user-feedback-flyout>

Attributes

button-text: the text that you want to place on the button

d2l-labs-user-feedback-launcher

A component for placing your feedback items in a d2l-dialog that opens when the user clicks the button. Will only appear after the container loads the hypermedia entities for submitting to the api, after the user has submitted feedback and closed the dialog, it disappears

<d2l-labs-user-feedback-launcher
	button-text="launch the feedback component"
>
	<!-- slotted d2l-labs-user-feedback-container -->
</d2l-labs-user-feedback-launcher>

Attributes

button-text: the text that you want to place on the button
dialog-title: set this to override the default dialog title

Developing

After cloning the repo, run npm install to install dependencies.

Running the demos

Start a @web/dev-server that hosts the demo pages:

npm start

Linting

# eslint
npm run lint

Testing

# lint and unit tests
npm test

# unit tests
npm run test:headless

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 sematic-release GitHub Action is called from the release.yml GitHub Action workflow to handle version changes and releasing.

Version Changes

All version changes should obey semantic versioning 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 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.

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)