discipletoolsbot / disciple-tools-web-components

Disciple Tools Web Component Library

These web components mostly follow the open-wc recommendations.

Installation

Clone the Repo then run

npm install

Usage

Samples

• Use in static HTML (Note: Need to Build for use in HTML, see below)
• Use in React
• Use in Vue
• Extend your own Lit Components

Build for use in HTML

To build/transpile the components for use in basic HTML as a script include, run the following:

npm run build

This will create a dist directory with all of the final javascript files that can be included in any HTML page like so:

<script type="module" src="/dist/form/index.js"></script>

You can then use any of the new elements in your HTML and they will be used from this library.

Demoing with Storybook

See the current Storybook here.

To run a local instance of Storybook for your component, run

npm run storybook

To build a production version of Storybook, run

npm run storybook:build

Linting and formatting

To scan the project for linting and formatting errors, run

npm run lint

To automatically fix linting and formatting errors, run

npm run format

Testing with Web Test Runner

To execute a single test run:

npm run test

To run the tests in interactive watch mode run:

npm run test:watch

Resources for writing tests

• @open-wc/testing - Overall testing framework
• @web/test-runner-commands - simulating keyboard/mouse input
• ChaiJS - Basic assertions
• Chai DOM - DOM assertions

Local Demo with web-dev-server

npm start

To run a local development server that serves the basic demo located in demo/index.html

Localization

Localization happens in 3 steps:

1. Use localized strings in code
2. Extract all of the strings used in the code to XLIFF file
3. Build localized templates for use in code

Using localized strings

See Lit Localize docs for full documentation.

When outputing text within a component that is not coming from the user (and would thus be translated by the user), use the msg function:

import {msg} from '@lit/localize';

class MyComp extends LitElement {
  render() {
    return msg(html`Hello <b>${this.who}</b>`);
  }
}
customElements.define('my-comp', MyComp);

The locale can either be passed into the component via attribute/property, or else it will attempt to read the direction and language from the nearest parent elements with dir and/or lang attributes.

Extract Messages

See Lit Localize docs for full documentation.

Run lit-localize extract in the console to generate XLIFF files into the /xliff/ directory. These should be able to be imported into translation software for translators to set the values.

The XLIFF files should be updated by translators and saved back into the space directory with correct translations.

Build localized templates

See Lit Localize docs for full documentation.

Run lit-localize build to process XLIFF files into javascript files that are saved into /i18n/generated/{locale}.js. These files are used by the msg function to use the correct localized string based on the selected locale.