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 @omicronenergy/oscd-material-web-base components. We plan to add more and more of the @omicronenergy/oscd-material-web-base components as and when they are needed, adding our own as the need arrises.

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

For palettes, MD3 system tokens and the optional Lit mappings, see the theming guide.

For the planned 0.1.0 breaking theming changes, see the migration guide.

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 @omicronenergy/oscd-material-web-base 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

<oscd-icon> accepts Material Symbols names (for example, warning) and SCL icon names (for example, gooseIcon). Set --md-icon-size to a CSS length to resize either kind, and use CSS color for monochrome icons; there is no --md-icon-color token. The legacy SVG warning is named scl-warning, including in <oscd-scl-icon> and the exported SCL icon helpers. Replace previous SCL warning lookups with scl-warning if you need that SVG rather than the stock Material symbol.

The Icons / Icon Storybook story exposes the size in pixels with a number control and foreground/background dropdowns for all public palette color slots. The selected slots follow the active Storybook palette.

Text and SCL element editors

Use ace-editor/OscdAceEditor.js for string .value input and live text output. Use scl-editor/OscdSclEditor.js for .element input/output: it preserves the element's in-scope namespaces and parses a new element without modifying the original document. Its inherited .value exposes the editable text. element returns null for empty or malformed text; validation checks exactly one well-formed element, not SCL schema conformance. Empty input is allowed. The obsolete xml-editor export paths did not contain shipped modules; use scl-editor instead.

Both components share Ace, persisted settings, an optional .toolbar, and native form association. Ace accepts an optional .validator callback returning null or an error message; SCL supplies namespace-aware XML validation by default. setCustomValidity() errors persist until explicitly cleared. User edits emit input plus a bubbling/composed CustomEvent<string>('change') whose detail is the current text. The existing text-bearing change contract is retained; it is not a blur event. Programmatic writes emit neither. Both preserve the cursor on unchanged value echoes and start at the beginning on actual text replacements.

The Editors / Ace Editor stories show a shared publisher-demo document with five IEDs, communication and data templates, plus toolbar and custom validation examples in SCL Doc as text. Editors / SCL Editor shows Full SCL Document using the parsed document's .documentElement and SCL Element using its PUB_A IED with inherited SCL namespaces, plus toolbar, invalid text and empty-input examples. Both SCL examples pass an Element through .element, not an XMLDocument object. The fixture comes from OMICRONEnergyOSS/oscd-editor-publisher/demo/sample.scd; it is demonstration data, not a schema-conformance assertion.

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