README
@brightspace-ui-labs/input-duration
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
An input component for tracking durations of time. It supports various configurations from weeks to seconds.
Installation
Install from NPM:
npm install @brightspace-ui-labs/input-duration
Usage
<script type="module">
import '@brightspace-ui-labs/input-duration/input-duration.js';
</script>
<d2l-labs-input-duration
label="Duration"
units="hours:minutes"
></d2l-labs-input-duration>
Properties:
| Property | Type | Description |
|--|--|--|
| label
| String, required | Label for the input |
| label-hidden
| Boolean | Hides the label visually |
| units
| String, required | A colon (:
) delimited list of the units to use (ex: hours:minutes
). Supported units are weeks
days
hours
minutes
seconds
. |
| largest-unit-max
| Number, default: 99
| Sets the max number for the largest unit of the selected set |
| weeks
| Number | Value of weeks for the input |
| days
| Number | Value of days for the input |
| hours
| Number | Value of hours for the input |
| minutes
| Number | Value of minutes for the input |
| seconds
| Number | Value of seconds for the input |
| disabled
| Boolean | Disables the input |
| error
| Boolean | Sets the input into an error state |
Accessibility:
To make your usage of d2l-labs-input-duration
accessible, use the following properties when applicable:
| Attribute | Description |
|--|--|
| label
| REQUIRED Acts as a primary label on the input. Visible unless label-hidden
is also used. |
| label-hidden
| Use if label should be visually hidden but available for screen reader users |
Events:
change
: Dispatched whenever a value changes for any of the units within the input. The event detail (event.detail
) is an object containing the updated values for each unit (ex: an input withweeks:days:hours:minutes:seconds
might have anevent.detail
like this:{ weeks: 2, days: 5, hours: 10, minutes: 30, seconds: 0 }
).
Developing, Testing and Contributing
After cloning the repo, run npm install
to install dependencies.
Linting
# eslint and lit-analyzer
npm run lint
# eslint only
npm run lint:eslint
Testing
# lint & run headless unit tests
npm test
# unit tests only
npm run test:headless
# debug or run a subset of local unit tests
# then navigate to `http://localhost:9876/debug.html`
npm run test:headless:watch
Visual Diff Testing
This repo uses the @brightspace-ui/visual-diff utility 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. 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:
npm install @brightspace-ui/visual-diff@X mocha@Y puppeteer@Z --no-save
Replace X
, Y
and Z
with the current versions the action is using.
Then run the tests:
# 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 that hosts the demo page and tests:
npm start
Versioning & Releasing
TL;DR: Commits prefixed with
fix:
andfeat:
will trigger patch and minor releases when merged tomain
. 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:
- MAJOR version when you make incompatible API changes,
- MINOR version when you add functionality in a backwards compatible manner, and
- 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:
orperf:
will trigger apatch
release. Example:fix: validate input before using
- Commits which are prefixed with
feat:
will trigger aminor
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:
andtest:
. 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 the1.15
release (after version1.16
exists)2.x
for feature releases on top of the2
release (after version3
exists)