Disciple Tools Web Component Library

A set of standard components to be used across the Disciple.Tools system

See the live documentation on the Storybook.

Get Started

These components are already included in the Disciple.Tools theme. If you are working in the theme or a plugin that is within the standard user interface, you can start using the components now without any extra including of scripts or styles.

In other cases, see the below samples for how to use the components in other scenarios.

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

Developing Components

Installation

Clone the Repo then runnpm install

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 src="/dist/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

Coding Standards

Linting

To scan the project for linting and formatting errors, run

npm run lint

Formatting

To automatically fix linting and formatting errors, run

npm run format

Component Standards

The Standards file contains a description of the implementation details that are expected for components.

They are written so that you can provide them to an AI coding agent and have it update the component for you:

Use the Standards.md file to make sure everything in src/components/form/dt-my-component is up to date

Automated Testing

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 outputting 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.