doc: adding missing doc annotations (#20)

* chore: add ignore for custom-elements.json in core

* chore: update package lock in compas-scl-list

* doc: adding missing doc annotations

* chore: updating param to prop in plugin class

* doc: add missing jsdoc for filteredItems

* chore: missing jsdoc for run method

* doc: adds missing jsdoc for privates

components/compas-loading/src/compas-loading.ts

@@ -2,7 +2,14 @@ import { html, LitElement, TemplateResult, property } from "lit-element";
 import "@material/mwc-list";
 import "@material/mwc-list/mwc-list-item";
 
+/**
+ * @prop {string} message - The message to display.
+ * @example <compas-loading message="Custom Loading Message..."></compas-loading>
+ * @summary Displays a loading message.
+ * @tagname compas-loading
+ */
 export class CompasLoadingElement extends LitElement {
+  /** the message to display. */
   @property({ type: String }) message?: string;
 
   render(): TemplateResult {

components/compas-open/src/compas-open.ts

@@ -23,13 +23,25 @@ export function newDocRetrievedEvent(
   });
 }
 
+/**
+ * @prop {boolean} allowLocalFile - If true, the user can select a local file to open.
+ * @slot sclTypes - The list of SCL types.
+ * @slot sclList - The list of SCL documents.
+ * @slot - The default slot.
+ * @example <compas-open></compas-open>
+ * @summary Displays a file selector to open an SCL document and/or a list of SCL documents to open.
+ * @tagname compas-open
+ */
 export class CompasOpenElement extends LitElement {
+  /** if true, the user can select a local file to open. */
   @property({ type: Boolean })
   allowLocalFile = true;
 
+  /** the file input element. */
   @query("#scl-file")
   private sclFileUI!: HTMLInputElement;
 
+  /** parses selected SCL document and triggers a "doc-retrieved" event */
   private async getSclFile(fileObj: {
     isLocal: boolean;
     evt: Event;
@@ -44,6 +56,7 @@ export class CompasOpenElement extends LitElement {
     this.dispatchEvent(newDocRetrievedEvent(true, doc, docName));
   }
 
+  /** renders the file selector */
   private renderFileSelect(): TemplateResult {
     return html`
       <input
@@ -66,7 +79,6 @@ export class CompasOpenElement extends LitElement {
     `;
   }
 
-  //TODO: add wizard-devider
   render(): TemplateResult {
     return html`
       ${this.allowLocalFile

components/compas-scl-list/src/compas-scl-list.ts

@@ -22,21 +22,37 @@ export function newSclSelectedEvent(docId: string): SclSelectedEvent {
   });
 }
 
+/**
+ * @prop {string} type - The type of SCL to retrieve.
+ * @prop {string} nameSpace - The namespace of the SCL to retrieve.
+ * @prop {Element[]} items - The list of SCL documents.
+ * @prop {string[]} labels - The list of labels.
+ * @prop {string[]} selectedLabels - The list of selected labels.
+ * @prop {Element[]} filteredItems - The list of filtered SCL documents.
+ * @example <compas-scl-list></compas-scl-list>
+ * @summary Displays a list of SCL documents filterable by labels.
+ * @tagname compas-scl-list
+ * @cssprop --mdc-list-side-padding - The padding of the list.
+ * 
+ */
 export class CompasSclList extends LitElement {
+  /** the type of SCL to retrieve. */
   @property({ type: String })
   type?: string;
+  /** the namespace of the SCL to retrieve. */
   @property({ type: String })
   nameSpace = "";
-
+  /** the list of SCL documents. */
   @property({ type: Array })
   private items: Element[] | undefined;
-
+  /** the list of labels. */
   @property({ type: Array })
   private labels: string[] = [];
-
+  /** the list of selected labels. */
   @property({ type: Array })
   private selectedLabels: string[] = [];
 
+  /** the list of filtered SCL documents. */
   @property({ type: Array })
   private get filteredItems(): Element[] | undefined {
     // If items are still being retrieved, return undefined.
@@ -59,16 +75,19 @@ export class CompasSclList extends LitElement {
     });
   }
 
+  /** renders a loading message */
   private renderLoading(): TemplateResult {
     return html` <compas-loading message="Loading files..."></compas-loading> `;
   }
 
+  /** renders a message when no SCL documents are found */
   private renderNoScls(): TemplateResult {
     return html`<mwc-list>
       <mwc-list-item><i>No projects found in CoMPAS</i></mwc-list-item>
     </mwc-list>`;
   }
 
+  /** renders the list of SCL documents */
   private renderSclList(): TemplateResult {
     const { filteredItems } = this;
     return html`
@@ -81,7 +100,7 @@ export class CompasSclList extends LitElement {
           id="labelsFilter"
           multi="true"
           ?disabled="${this.labels.length <= 0}"
-          .header="Select"
+          header="Select"
           labels
           to
           be

components/compas-scl-type-list/src/compas-scl-type-list.ts

@@ -16,23 +16,34 @@ export function newTypeSelectedEvent(type: string): TypeSelectedEvent {
   });
 }
 
+/**
+ * @prop {Element[]} sclTypes - The list of SCL types.
+ * @prop {string} nameSpace - The namespace of the SCL types.
+ * @example <compas-scl-type-list></compas-scl-type-list>
+ * @summary Displays a list of SCL types.
+ * @tagname compas-scl-type-list
+ */
 export class CompasSclTypeList extends LitElement {
+  /** the list of SCL types. */
   @property({ type: Array })
   sclTypes: Element[] | undefined;
-
+  /** the namespace of the SCL types. */
   @property({ type: String })
   nameSpace = "";
 
+  /** renders a loading message */
   private renderLoading(): TemplateResult {
     return html` <compas-loading message="Loading types..."></compas-loading> `;
   }
 
+  /** renders a message when no types are found */
   private renderNoTypes(): TemplateResult {
     return html` <mwc-list>
       <mwc-list-item><i>No types found in CoMPAS</i></mwc-list-item>
     </mwc-list>`;
   }
 
+  /** renders the list of types */
   private renderTypes(): TemplateResult {
     return html` <mwc-list>
       ${this.sclTypes!.map((type) => {

components/oscd-filter-button/src/oscd-filter-button.ts

@@ -31,23 +31,36 @@ import {
   }
 
   /**
-   * A mwc-list with mwc-textfield that filters the list items for given or separated terms
+   * @prop {string} header - The header of the dialog.
+   * @prop {string} icon - The icon of the button.
+   * @prop {boolean} disabled - If true, the button is disabled.
+   * @slot - The default slot.
+   * @example <oscd-filter-button></oscd-filter-button>
+   * @summary Displays a button that opens a dialog with a list filterable by given search terms
+   * @tagname oscd-filter-button
+   * @cssprop --mdc-theme-on-surface - The color of the icon.
    */
   export class OscdFilterButton extends OscdFilteredList {
+    /** the header of the dialog. */
     @property()
     header!: TemplateResult | string;
+    /** the icon of the button. */
     @property()
     icon!: string;
+    /** if true, the button is disabled. */
     @property({ type: Boolean })
     disabled = false;
 
+    /** the dialog element containing the list. */
     @query("#filterDialog")
     private filterDialog!: Dialog;
 
+    /** toggles the dialog containing the list. */
     private toggleList(): void {
       this.filterDialog.show();
     }
 
+    /** dispatches a "selected-items-changed" event when the dialog is closed. */
     private onClosing(): void {
       const selectedItems: string[] = [];
       if (this.selected) {
@@ -71,7 +84,7 @@ import {
         </mwc-icon-button>
         <mwc-dialog
           id="filterDialog"
-          heading="${this.header ? this.header : "Filter"}
+          heading="${this.header ? this.header : "Filter"}"
           scrimClickAction=""
           @closing="${() => this.onClosing()}"
         >

packages/compas-open-plugin/src/compas-open-plugin.ts

@@ -29,33 +29,41 @@ import {
 
   /**
    * A plugin that opens a dialog to select a SCL document from a list of SCL documents.
-   * @param allowLocalFile - If true, the user can select a local file to open.
-   * @param selectedType - The selected SCL type.
-   * @param sclTypes - The list of SCL types.
-   * @param items - The list of SCL documents.
-   * @param labels - The list of labels.
-   * @param selectedLabels - The list of selected labels.
-   * @param locale - The locale to use for translations.
+   * @prop allowLocalFile - If true, the user can select a local file to open.
+   * @prop selectedType - The selected SCL type.
+   * @prop sclTypes - The list of SCL types.
+   * @prop items - The list of SCL documents.
+   * @prop labels - The list of labels.
+   * @prop selectedLabels - The list of selected labels.
+   * @prop locale - The locale to use for translations.
+   * @method run - Run method to start the plugin.
    */
   export default class CompasOpenMenuPlugin extends LitElement {
     @query("mwc-dialog#compas-open-dlg")
     dialog!: Dialog;
+    /** if true, the user can select a local file to open */
     @property({ type: Boolean })
     allowLocalFile = true;
-
+    /** the selected SCL type */
     @property({ type: String })
     selectedType: string | undefined;
+    /** the list of SCL types */
     @property({ type: Array })
     sclTypes!: Element[];
+    /** the list of SCL documents */
     @property({ type: Array })
     items: Element[] | undefined;
+    /** the list of labels */
     @property({ type: Array })
     labels: string[] = [];
+    /** the list of selected labels */
     @property({ type: Array })
     selectedLabels: string[] = [];
+    /** the locale to use for translations */
     @property({ type: String })
     locale = "en";
 
+    /** Run method to start the plugin. */
     async run(): Promise<void> {
       this.dialog.show();
     }
@@ -104,6 +112,7 @@ import {
       }
     }
 
+    /** retrieves SCL document from the CompasSclDataService and triggers a "doc-retrieved" event */
     private async getSclDocument(docId?: string): Promise<void> {
       const doc = await CompasSclDataService()
         .getSclDocument(this, this.selectedType ?? "", docId ?? "")

packages/core/.gitignore

@@ -21,4 +21,6 @@
 /out-tsc/
 /.tsbuildinfo
 
+custom-elements.json
+
 .rollup.cache/