Open SCD UI Component Library

This library is intended to be used for OpenSCD Plugins. This library is intended to be used for OpenSCD Plugins. Currently this is a subset of the existing @material/web components. We plan to add more and more of the @material/web components as and when they are needed, adding our own as the need arrises.

The original @material/web documentation can be found here: https://material-web.dev/about/intro/

The predecessor Material Web Components (mwc) are officially depricated and the newer Material Design components (md) are in maintenance mode. So we plan to maintain this set of components moving forward no matter what happens to the @material/web project.

For plugins which used the mwc-* components, these used the older Material Icons (legacy) which were glyph-based and relatively simple but fixed to a style. @omicronenergy/oscd-ui components all use the newer Material Symbol font icons, which are variable fonts and far more flexible. Use the following link in your html to make use Material icons with these components:

<link
  href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined"
  rel="stylesheet"
/>

The full set of available Material Symbol icons can be found here: https://fonts.google.com/icons

Scoped Web Components

All OSCD UI components are scoped web components, which means its possible to use plugins can use multiple different versions of @omicronenergy/oscd-ui without risk of conflict. More details on how to use these components in a scoped manor are below. General details on scoping web components can be found here

Installation

npm install --save @omicronenergy/oscd-ui

Usage

All components can be either be scoped or non-scoped (globally defined)

Using the components globally (non-scoped)

To use the globally scoped version of the component, import the lower (kebab) case file. e.g. If you want to use <oscd-app-bar /> import oscd-app-bar.js and that is enough to have it registered.

import { LitElement, html } from "lit";
import "@omicronenergy/oscd-ui/oscd-app-bar.js";

export class NotScopedExample extends LitElement {
  render() {
    return html`
      <oscd-app-bar>
        <span slot="title">Open SCD Example App Bar</span>
      </oscd-app-bar>
    `;
  }
}

Using the components scoped

To use the Scoped version of the components, your component must extend @open-wc's ScopedElementMixin and define the scopedElements like so:

you must not import the kebab case version of the file. Instead import the Camel case version

import { LitElement, html } from "lit";
import { ScopedElementsMixin } from "@open-wc/scoped-elements";
import { OscdAppBar } from "@omicronenergy/oscd-ui/app-bar/OscdAppBar.js";
import { OscdIcon } from "@omicronenergy/oscd-ui/icon/OscdIcon.js";
import { OscdFilledIconButton } from "@omicronenergy/oscd-ui/button/OscdFilledIconButton.js";

export class ScopedExample extends ScopedElementsMixin(LitElement) {
  static get scopedElements() {
    return {
      "oscd-app-bar": OscdAppBar,
      "oscd-icon": OscdIcon,
      "oscd-filled-icon-button": OscdFilledIconButton,
    };
  }

  render() {
    return html`
      <oscd-app-bar>
        <oscd-filled-icon-button slot="actionStart">
          <oscd-icon>menu</oscd-icon>
        </oscd-filled-icon-button>
        <span slot="title"> Open SCD Example App Bar (Scoped) </span>
      </oscd-app-bar>
    `;
  }
}

Note: You must not import the kebab-case version of the file. If you do, it will be registered globally, defeating the purpose of scoping. Notice the example above imports OscdAppBar.js and NOT oscd-app-bar.js

Component Library

The full set of components currently supported in oscd-ui can be found here:

Browse the full Catalog