@duetds/components

Duet Components

This package includes Duet Web Components and related tools.

Usage

For usage instructions, please see Duet Design System documentation.

Architecture

This package is built with Stencil.js, a compiler and toolchain for building web components. The component source code is written in TypeScript + JSX (TSX), with stylesheets written in SCSS.

Development

The following are the most commonly used commands during development:

• npm start - Compile components, start watching for changes, start local development server
• ES5=true npm start - As above, but with support for legacy browsers. Useful for testing IE11
• SSR=true npm start - Enables SSR in dev server
• npm run build - Build project
• npm test - Run all tests once
• `npm test:dev - Run tests with a development koa server to serve assets and act as upload target for duet-upload
• `npm test:fixtures - Run the visuall regressions tests
• `npm lint:fix - Run the linters and autofix what can be autofixed

The local development server started by npm start serves a file located at /src/index.html. Any local changes or new components are available on this page, so this can be used as a testing ground when developing.

How to develop new components

1. Create component files
   1. add directory for component under src/components/[component-name]
   2. add [component-name].tsx
   3. add [component-name].scss
   4. add [component-name].e2e.ts
   5. add readme.md
2. In stencil.config.js
   1. Add new component to bundles field of config
   2. For input components, configure angular value accessors (see section below)
3. Implement component
4. Write tests
5. Write readme
   1. add info for docs
   2. add comprehensive examples
6. Test theming for both default and turva
7. Browser testing
   1. Evergreen browsers
   2. Edge on Windows
8. Accessibility testing, following the Duet accessibility checklist
9. Test SSR
10. Add the following to docs/:
    1. An SVG icon for listing on component page
    2. Add to changelog.md

Documentation and examples

• Documentation that is shown on duetds.com acts as our primary component development platform. To get started locally, open /docs/ directory and run npm install and npm start.
• Once the server is up and running, you can access the local development environment by pointing your browser to http://localhost:8000. The components section in the documentation will be empty at this point.
• Next, go to /packages/components/ directory and run npm install and npm start that starts up the component watch and build tasks.
• If you now open any of the *.tsx, *.scss, or readme.md files underneath /packages/components/src/components/ and hit save, that will trigger a rebuild task which also copies the necessary changes over to the local documentation running at http://localhost:8000.
• Editing *.tsx and *.scss files will generate a new JavaScript bundle, while editing the readme.md files only generates and copies over the documentation and component usage examples.
• When working on new components or editing existing ones, make sure to follow our code style guide found under the guidelines section.
• Component variation examples are inside each component’s readme.md, while the component templates are located under /docs/src/templates/ directory.

How angular value accessors work

Angular's ControlValueAccessors are used to adapt custom inputs to work with Angular's reactive forms. The angular-output-target accepts config to auto-generate value accessors for stencil components.

To correctly adapt a component for Angular reactive forms, the output target must know:

1. The CSS selector for the component
2. The type of input (text, radio, select, number, boolean)
3. The name of the attribute which holds the input's value
4. The name of the event raised on change

As an example, consider duet-checkbox:

1. duet-checkbox is the CSS selector for this component
2. boolean is the type of input component (since it is true when checked, false when unchecked)
3. The checked attribute that holds the component's value
4. The duetChange event is raised when the value is changed

You can likely add any new components to one of the existing configs, but if not, you can simply add a new config providing all the above information.

Why use a forked version of angular output target?

We originally forked @stencil/angular-output-target in order to add support for disabled inputs in Angular reactive forms. Whilst this feature has now landed upstream, we have not upgraded as we observed a number of compatibility issues between the angular-output-target and newer versions of angular.

Copyright

Copyright © 2021 LocalTapiola/Turva.