feat(UpdateDescriptionSEL): add menu type plugin for SEL specific IEDs (openscd#424)

* feat(menu/UpdateDescriptionSEL): add plug-in menu type plugin

* feat(menu/UpdateDescriptionSEL): add unit tests

* refactor(menu/UpdateDescriptionSEL): add better csv parser

* test(menu/UpdateDescriptionSEL): update open-scd snapshot

Author: JakobVogelsang

public/js/plugins.js

@@ -100,6 +100,14 @@ export const officialPlugins = [
     requireDoc: true,
     position: 'middle'
   },
+  {
+    name: 'Update desc (SEL)',
+    src: '/src/menu/UpdateDescriptionSEL.js',
+    default: false,
+    kind: 'menu',
+    requireDoc: true,
+    position: 'middle'
+  },
   {
     name: 'Merge Project',
     src: '/src/menu/Merge.js',

src/menu/UpdateDescriptionSEL.ts

@@ -0,0 +1,255 @@
+import { css, html, LitElement, query, TemplateResult } from 'lit-element';
+import { get } from 'lit-translate';
+
+import '@material/mwc-list/mwc-check-list-item';
+import { List } from '@material/mwc-list';
+import { ListItemBase } from '@material/mwc-list/mwc-list-item-base';
+
+import '../filtered-list.js';
+import {
+  cloneElement,
+  identity,
+  isPublic,
+  newWizardEvent,
+  SCLTag,
+  selector,
+  Wizard,
+  WizardAction,
+  WizardActor,
+  WizardInput,
+} from '../foundation.js';
+
+interface SignalDescription {
+  desc: string;
+  tag: SCLTag;
+  identity: string | number;
+}
+
+function addDescriptionToSEL(
+  ied: Element,
+  signalList: string[][]
+): SignalDescription[] {
+  const iedName = ied.getAttribute('name');
+  const manufacturer = ied.getAttribute('manufacturer');
+  if (!iedName || manufacturer !== 'SEL') return [];
+
+  return <SignalDescription[]>Array.from(ied.getElementsByTagName('DAI'))
+    .filter(element => isPublic(element))
+    .filter(dai => {
+      const datasrc = dai.getAttributeNS(
+        'http://www.selinc.com/2006/61850',
+        'datasrc'
+      );
+      return datasrc?.startsWith('db:');
+    })
+    .map(dai => {
+      //the next lines are vendor dependant!!
+      const datasrc = dai.getAttributeNS(
+        'http://www.selinc.com/2006/61850',
+        'datasrc'
+      );
+
+      const tag = datasrc ? datasrc.replace('db:', '') : null;
+      const desc =
+        signalList.find(row => row[2] === tag && row[1] === iedName)?.[0] ??
+        null;
+
+      return desc ? { desc, tag: 'DAI', identity: identity(dai) } : null;
+    })
+    .filter(signalDescription => signalDescription);
+}
+
+function addDescriptionAction(doc: XMLDocument): WizardActor {
+  return (
+    _: WizardInput[],
+    wizard: Element,
+    list: List | null | undefined
+  ): WizardAction[] => {
+    const selectedItems = <ListItemBase[]>list!.selected;
+
+    const actions = selectedItems.map(item => {
+      const desc = (<Element>item.querySelector('span')).textContent;
+      const [tag, identity] = item.value.split(' | ');
+
+      const oldElement = doc.querySelector(selector(tag, identity))!;
+      const newElement = cloneElement(oldElement, { desc });
+      return { old: { element: oldElement }, new: { element: newElement } };
+    });
+
+    return [
+      {
+        title: get('updatedesc.sel'),
+        actions,
+      },
+    ];
+  };
+}
+
+function createLogWizard(doc: XMLDocument, items: SignalDescription[]): Wizard {
+  return [
+    {
+      title: get('wizard.title.add', { tagName: 'desc' }),
+      primary: {
+        label: get('save'),
+        icon: 'save',
+        action: addDescriptionAction(doc),
+      },
+      content: [
+        html`<filtered-list multi
+          >${Array.from(
+            items.map(
+              item =>
+                html`<mwc-check-list-item
+                  twoline
+                  selected
+                  value="${item.tag + ' | ' + item.identity}"
+                  ><span>${item.desc}</span
+                  ><span slot="secondary"
+                    >${item.tag + ' | ' + item.identity}</span
+                  ></mwc-check-list-item
+                >`
+            )
+          )}</filtered-list
+        >`,
+      ],
+    },
+  ];
+}
+
+function parseCsv(str: string, delimiter: ',' | ';'): string[][] {
+  // predefined for later use
+  const quoteChar = '"',
+    escapeChar = '\\';
+
+  const entries: string[][] = [];
+  let isInsideQuote = false;
+
+  // Iterate over each character, keep track of current row and column (of the returned array)
+  for (let row = 0, col = 0, char = 0; char < str.length; char++) {
+    const currentChar = str[char];
+    const nextChar = str[char + 1];
+
+    entries[row] = entries[row] || [];
+    entries[row][col] = entries[row][col] || '';
+
+    //Ignore escape character
+    if (currentChar === escapeChar) {
+      entries[row][col] += nextChar;
+      ++char;
+      continue;
+    }
+
+    // Check for quoted characters. Do not miss-interpret delimiter within field
+    if (currentChar === quoteChar) {
+      isInsideQuote = !isInsideQuote;
+      continue;
+    }
+
+    if (!isInsideQuote) {
+      if (currentChar === delimiter) {
+        ++col;
+        entries[row][col] = '';
+        continue;
+      }
+
+      if (currentChar === '\n' || currentChar === '\r') {
+        ++row;
+        col = 0;
+
+        // Skip the next character for CRLF
+        if (currentChar === '\r' && nextChar === '\n') ++char;
+
+        continue;
+      }
+    }
+
+    entries[row][col] += currentChar;
+  }
+
+  return entries;
+}
+
+function getGuessDelimiter(csvString: string): ';' | ',' {
+  let numberComma = 0,
+    numberSemicolon = 0;
+
+  const quoteChar = '"';
+
+  let isInsideQuote = false;
+  for (const currentChar of csvString) {
+    // Check for quoted characters. Do not miss-interpret delimiter within field
+    if (currentChar === quoteChar) {
+      isInsideQuote = !isInsideQuote;
+      continue;
+    }
+
+    if (!isInsideQuote) {
+      if (currentChar === ';') {
+        numberSemicolon++;
+        continue;
+      }
+
+      if (currentChar === ',') {
+        numberComma++;
+        continue;
+      }
+    }
+  }
+
+  return numberComma > numberSemicolon ? ',' : ';';
+}
+
+/**
+ * Plug-in that enriches the desc attribute in SEL type IED elements based on a signal list
+ * The signal list must be a  ; or , separated CSV file with 3 columns.
+ * 1st column: signal name
+ * 2nd column: IED name
+ * 3rd column: identifier from the SEL namespace excluding the prefix of "db:",
+ *             similar to relay word bit name (RWB), e.g. SV24T, 51P1T, IN203
+ */
+export default class UpdateDescriptionSel extends LitElement {
+  /** The document being edited as provided to plugins by [[`OpenSCD`]]. */
+  doc!: XMLDocument;
+
+  @query('#plugin-input') pluginFileUI!: HTMLInputElement;
+
+  processSignalList(csvString: string): void {
+    const signalList = parseCsv(csvString, getGuessDelimiter(csvString));
+
+    const items = Array.from(this.doc.querySelectorAll('IED'))
+      .filter(ied => isPublic(ied))
+      .flatMap(ied => addDescriptionToSEL(ied, signalList));
+
+    document
+      .querySelector('open-scd')
+      ?.dispatchEvent(newWizardEvent(createLogWizard(this.doc, items)));
+  }
+
+  private async onFileInput(e: Event): Promise<void> {
+    const file = (<HTMLInputElement | null>e.target)?.files?.item(0) ?? false;
+    if (!file) return;
+
+    this.processSignalList(await file.text());
+  }
+
+  /** Entry point for this plug-in */
+  async run(): Promise<void> {
+    this.pluginFileUI.click();
+  }
+
+  render(): TemplateResult {
+    return html`<input @click=${(event: MouseEvent) =>
+      ((<HTMLInputElement>event.target).value = '')} @change=${(e: Event) =>
+      this.onFileInput(
+        e
+      )} id="plugin-input" accept=".csv" type="file"></input>`;
+  }
+
+  static styles = css`
+    input {
+      width: 0;
+      height: 0;
+      opacity: 0;
+    }
+  `;
+}

src/translations/de.ts

@@ -402,6 +402,7 @@ export const de: Translations = {
   },
   updatedesc: {
     abb: 'Signalbeschreibungen zu ABB IEDs hinzugefügt',
+    sel: 'Signalbeschreibungen zu SEL IEDs hinzugefügt',
   },
   sld: {
     substationSelector: 'Schaltanlage auswählen',

src/translations/en.ts

@@ -399,6 +399,7 @@ export const en = {
   },
   updatedesc: {
     abb: 'Added signal descriptions to ABB IEDs',
+    sel: 'Added signal descriptions to SEL IEDs',
   },
   sld: {
     substationSelector: 'Select a substation',

test/integration/__snapshots__/open-scd.test.snap.js

@@ -798,6 +798,21 @@ snapshots["open-scd looks like its snapshot"] =
       </mwc-icon>
       Update desc (ABB)
     </mwc-check-list-item>
+    <mwc-check-list-item
+      aria-disabled="false"
+      class="official"
+      graphic="control"
+      hasmeta=""
+      left=""
+      mwc-list-item=""
+      tabindex="-1"
+      value="/src/menu/UpdateDescriptionSEL.js"
+    >
+      <mwc-icon slot="meta">
+        play_circle
+      </mwc-icon>
+      Update desc (SEL)
+    </mwc-check-list-item>
     <mwc-check-list-item
       aria-disabled="false"
       class="official"

test/testfiles/updatedesc/testSignalListComma.csv

@@ -0,0 +1,12 @@
+
+CB_CLOSED,IED2,IN101
+CB_OPEN,IED2,IN102
+BB1_DS_CLOSED,IED2,IN103
+BB1_DS_OPEN,IED2,IN104
+BB2_DS_CLOSED,IED2,IN105
+BB2_DS_OPEN,IED2,IN106
+LINE_DS_CLOSED,IED2,IN107
+LINE_DS_CLOSED,IED2
+LINE_DS_CLOSED
+LINE_DS_CLOSED,IED2,"IN,107"
+,

test/testfiles/updatedesc/testSignalListSemicolon.csv

@@ -0,0 +1,10 @@
+CB_CLOSED;IED2;IN101
+CB_OPEN;IED2;IN102
+BB1_DS_CLOSED;IED2;IN103
+BB1_DS_OPEN;IED2;IN104
+BB2_DS_CLOSED;IED2;IN105
+BB2_DS_OPEN;IED2;IN106
+LINE_DS_CLOSED;IED2;"IN107"
+LINE_DS_CLOSED;"IED2"
+LINE_DS_CLOSED
+;