diff --git a/README.md b/README.md index c6f4e5d..3be29ed 100644 --- a/README.md +++ b/README.md @@ -6,23 +6,25 @@ This repository hosts the components and plugins related to the (db-stored) SCL The following components are featured in this repository: -- `compas-loading` (**TODO**: add README to compas-loading) +- [`compas-loading`](/components/compas-loading/README.md) - [`compas-open`](/components/compas-open/README.md) -- `compas-scl-list` (**TODO**: add README to compas-scl-list) -- `compas-scl-type-list` (**TODO**: add README to compas-scl-type-list) -- `oscd-filter-button` (**TODO**: move this to [`@openscd/oscd-components`](https://github.com/openscd/oscd-components)) +- [`compas-scl-list`](/components/compas-scl-list/README.md) +- [`compas-scl-type-list`](/components/compas-scl-type-list/README.md) +- [`oscd-filter-button`](/components/oscd-filter-button/README.md) | **TODO**: move this to [`@openscd/oscd-components`](https://github.com/openscd/oscd-components) The following plugins are featured in this repository: -- [`compas-open`](/packages/compas-open-plugin/README.md) + +- [`compas-open`](/packages/compas-open-plugin/README.md) ## Usage + This project uses [Nx](https://nx.dev/), a set of extensible dev tools for monorepos. It is used in this repository to manage the development and build process of the various components and plugins. Feel free to use any of the Nx commands in here. We provide the following scripts for your convenience: - + - `npm test` runs the tests in all the components - `npm run build` builds a deployable version of every component into their /dist directory -- `npm build:all` same as the one before but it tells Nx to skip the cache +- `npm build:all` same as the one before but it tells Nx to skip the cache - `bundle` generates a javascript bundle for every plugin © 2023 Alliander N.V. diff --git a/components/compas-loading/README.md b/components/compas-loading/README.md new file mode 100644 index 0000000..753ef42 --- /dev/null +++ b/components/compas-loading/README.md @@ -0,0 +1,32 @@ +## `src/compas-loading.ts`: + +### class: `CompasLoadingElement`, `compas-loading` + +#### Superclass + +| Name | Module | Package | +| ------------ | ------ | ----------- | +| `LitElement` | | lit-element | + +#### Fields + +| Name | Privacy | Type | Default | Description | Inherited From | +| --------- | ------- | -------- | ------- | ----------------------- | -------------- | +| `message` | | `string` | | The message to display. | | + +
+ +### Exports + +| Kind | Name | Declaration | Module | Package | +| ---- | ---------------------- | -------------------- | --------------------- | ------- | +| `js` | `CompasLoadingElement` | CompasLoadingElement | src/compas-loading.ts | | + +## `src/CompasLoading.ts`: + +### Exports + +| Kind | Name | Declaration | Module | Package | +| --------------------------- | ---------------------- | -------------------- | ---------------------- | ------- | +| `custom-element-definition` | `compas-loading` | CompasLoadingElement | /src/compas-loading.js | | +| `js` | `CompasLoadingElement` | CompasLoadingElement | src/CompasLoading.ts | | diff --git a/components/compas-loading/custom-elements-manifest.config.js b/components/compas-loading/custom-elements-manifest.config.js new file mode 100644 index 0000000..6d93ac2 --- /dev/null +++ b/components/compas-loading/custom-elements-manifest.config.js @@ -0,0 +1,12 @@ +import { readmePlugin } from "cem-plugin-readme"; + +export default { + globs: ["src/*.ts"], + exclude: ["test/*.ts", "stories/*.ts"], + litelement: true, + plugins: [ + readmePlugin({ + to: "components/compas-loading/README.md", + }), + ], +}; diff --git a/components/compas-open/README.md b/components/compas-open/README.md index c329a8e..ac67725 100644 --- a/components/compas-open/README.md +++ b/components/compas-open/README.md @@ -1,77 +1,71 @@ -# \ +## `src/compas-open.ts`: -This webcomponent follows the [open-wc](https://github.com/open-wc/open-wc) recommendation. +### class: `CompasOpenElement`, `compas-open` -## Installation +#### Superclass -```bash -npm i compas-open -``` +| Name | Module | Package | +| ------------ | ------ | ------- | +| `LitElement` | | lit | -## Usage +#### Fields -```html - +| Name | Privacy | Type | Default | Description | Inherited From | +| ---------------- | ------- | --------- | ------- | -------------------------------------------------- | -------------- | +| `allowLocalFile` | | `boolean` | `true` | If true, the user can select a local file to open. | | - -``` +#### Slots -## Linting and formatting +| Name | Description | +| ---------- | -------------------------- | +| `sclTypes` | The list of SCL types. | +| `sclList` | The list of SCL documents. | +| | The default slot. | -To scan the project for linting and formatting errors, run +
Private API -```bash -npm run lint -``` +#### Fields -To automatically fix linting and formatting errors, run +| Name | Privacy | Type | Default | Description | Inherited From | +| ----------- | ------- | ------------------ | ------- | ----------------------- | -------------- | +| `sclFileUI` | private | `HTMLInputElement` | | the file input element. | | -```bash -npm run format -``` +#### Methods -## Testing with Web Test Runner +| Name | Privacy | Description | Parameters | Return | Inherited From | +| ------------------ | ------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------ | ---------------- | -------------- | +| `getSclFile` | private | parses selected SCL document and triggers a "doc-retrieved" event | `fileObj: { + isLocal: boolean; + evt: Event; + docId?: string; + }` | `Promise` | | +| `renderFileSelect` | private | renders the file selector | | `TemplateResult` | | -To execute a single test run: +
-```bash -npm run test -``` +
-To run the tests in interactive watch mode run: +### Functions -```bash -npm run test:watch -``` +| Name | Description | Parameters | Return | +| ---------------------- | ----------- | ------------------------------------------------------------------- | ------------------- | +| `newDocRetrievedEvent` | | `localFile: boolean, doc: Document, docName: string, docId: string` | `DocRetrievedEvent` | -## Demoing with Storybook +
-To run a local instance of Storybook for your component, run +### Exports -```bash -npm run storybook -``` +| Kind | Name | Declaration | Module | Package | +| ---- | ---------------------- | -------------------- | ------------------ | ------- | +| `js` | `newDocRetrievedEvent` | newDocRetrievedEvent | src/compas-open.ts | | +| `js` | `CompasOpenElement` | CompasOpenElement | src/compas-open.ts | | -To build a production version of Storybook, run +## `src/CompasOpen.ts`: -```bash -npm run storybook:build -``` +### Exports -## Tooling configs - -For most of the tools, the configuration is in the `package.json` to reduce the amount of files in your project. - -If you customize the configuration a lot, you can consider moving them to individual files. - -## Local Demo with `web-dev-server` - -```bash -npm start -``` - -To run a local development server that serves the basic demo located in `demo/index.html` - -© 2023 Alliander N.V. +| Kind | Name | Declaration | Module | Package | +| --------------------------- | ------------------- | ----------------- | ------------------- | ------- | +| `custom-element-definition` | `compas-open` | CompasOpenElement | /src/compas-open.js | | +| `js` | `CompasOpenElement` | CompasOpenElement | src/CompasOpen.ts | | +| `js` | `DocRetrievedEvent` | DocRetrievedEvent | src/CompasOpen.ts | | diff --git a/components/compas-open/custom-elements-manifest.config.js b/components/compas-open/custom-elements-manifest.config.js index 81abf6b..8344646 100644 --- a/components/compas-open/custom-elements-manifest.config.js +++ b/components/compas-open/custom-elements-manifest.config.js @@ -1,7 +1,12 @@ +import { readmePlugin } from "cem-plugin-readme"; + export default { - globs: ['src/*.ts'], - exclude: ['test/*.ts'], - litelement: true, - plugins: [], - }; - \ No newline at end of file + globs: ["src/*.ts"], + exclude: ["test/*.ts", "stories/*.ts"], + litelement: true, + plugins: [ + readmePlugin({ + to: "components/compas-open/README.md", + }), + ], +}; diff --git a/components/compas-scl-list/README.md b/components/compas-scl-list/README.md new file mode 100644 index 0000000..013f030 --- /dev/null +++ b/components/compas-scl-list/README.md @@ -0,0 +1,70 @@ +## `src/compas-scl-list.ts`: + +### class: `CompasSclList`, `compas-scl-list` + +#### Superclass + +| Name | Module | Package | +| ------------ | ------ | ----------- | +| `LitElement` | | lit-element | + +#### Fields + +| Name | Privacy | Type | Default | Description | Inherited From | +| ----------- | ------- | -------- | ------- | ------------------------------------- | -------------- | +| `type` | | `string` | | The type of SCL to retrieve. | | +| `nameSpace` | | `string` | `""` | The namespace of the SCL to retrieve. | | + +#### CSS Properties + +| Name | Default | Description | +| ------------------------- | ------- | ------------------------ | +| `--mdc-list-side-padding` | | The padding of the list. | + +
Private API + +#### Fields + +| Name | Privacy | Type | Default | Description | Inherited From | +| ---------------- | ------- | ----------- | ------- | ----------------------------------- | -------------- | +| `items` | private | `Element[]` | | The list of SCL documents. | | +| `labels` | private | `string[]` | `[]` | The list of labels. | | +| `selectedLabels` | private | `string[]` | `[]` | The list of selected labels. | | +| `filteredItems` | private | `Element[]` | | The list of filtered SCL documents. | | + +#### Methods + +| Name | Privacy | Description | Parameters | Return | Inherited From | +| --------------- | ------- | ------------------------------------------------- | ---------- | ---------------- | -------------- | +| `renderLoading` | private | renders a loading message | | `TemplateResult` | | +| `renderNoScls` | private | renders a message when no SCL documents are found | | `TemplateResult` | | +| `renderSclList` | private | renders the list of SCL documents | | `TemplateResult` | | + +
+ +
+ +### Functions + +| Name | Description | Parameters | Return | +| --------------------- | ----------- | --------------- | ------------------ | +| `newSclSelectedEvent` | | `docId: string` | `SclSelectedEvent` | + +
+ +### Exports + +| Kind | Name | Declaration | Module | Package | +| ---- | --------------------- | ------------------- | ---------------------- | ------- | +| `js` | `newSclSelectedEvent` | newSclSelectedEvent | src/compas-scl-list.ts | | +| `js` | `CompasSclList` | CompasSclList | src/compas-scl-list.ts | | + +## `src/CompasSclList.ts`: + +### Exports + +| Kind | Name | Declaration | Module | Package | +| --------------------------- | ------------------ | ---------------- | ----------------------- | ------- | +| `custom-element-definition` | `compas-scl-list` | CompasSclList | /src/compas-scl-list.js | | +| `js` | `CompasSclList` | CompasSclList | src/CompasSclList.ts | | +| `js` | `SclSelectedEvent` | SclSelectedEvent | src/CompasSclList.ts | | diff --git a/components/compas-scl-list/custom-elements-manifest.config.js b/components/compas-scl-list/custom-elements-manifest.config.js new file mode 100644 index 0000000..2588e5b --- /dev/null +++ b/components/compas-scl-list/custom-elements-manifest.config.js @@ -0,0 +1,12 @@ +import { readmePlugin } from "cem-plugin-readme"; + +export default { + globs: ["src/*.ts"], + exclude: ["test/*.ts", "stories/*.ts"], + litelement: true, + plugins: [ + readmePlugin({ + to: "components/compas-scl-list/README.md", + }), + ], +}; diff --git a/components/compas-scl-type-list/README.md b/components/compas-scl-type-list/README.md new file mode 100644 index 0000000..c01f25b --- /dev/null +++ b/components/compas-scl-type-list/README.md @@ -0,0 +1,55 @@ +## `src/compas-scl-type-list.ts`: + +### class: `CompasSclTypeList`, `compas-scl-type-list` + +#### Superclass + +| Name | Module | Package | +| ------------ | ------ | ----------- | +| `LitElement` | | lit-element | + +#### Fields + +| Name | Privacy | Type | Default | Description | Inherited From | +| ----------- | ------- | ----------- | ------- | ------------------------------- | -------------- | +| `sclTypes` | | `Element[]` | | The list of SCL types. | | +| `nameSpace` | | `string` | `""` | The namespace of the SCL types. | | + +
Private API + +#### Methods + +| Name | Privacy | Description | Parameters | Return | Inherited From | +| --------------- | ------- | ----------------------------------------- | ---------- | ---------------- | -------------- | +| `renderLoading` | private | renders a loading message | | `TemplateResult` | | +| `renderNoTypes` | private | renders a message when no types are found | | `TemplateResult` | | +| `renderTypes` | private | renders the list of types | | `TemplateResult` | | + +
+ +
+ +### Functions + +| Name | Description | Parameters | Return | +| ---------------------- | ----------- | -------------- | ------------------- | +| `newTypeSelectedEvent` | | `type: string` | `TypeSelectedEvent` | + +
+ +### Exports + +| Kind | Name | Declaration | Module | Package | +| ---- | ---------------------- | -------------------- | --------------------------- | ------- | +| `js` | `newTypeSelectedEvent` | newTypeSelectedEvent | src/compas-scl-type-list.ts | | +| `js` | `CompasSclTypeList` | CompasSclTypeList | src/compas-scl-type-list.ts | | + +## `src/CompasSclTypeList.ts`: + +### Exports + +| Kind | Name | Declaration | Module | Package | +| --------------------------- | --------------------- | ----------------- | ---------------------------- | ------- | +| `custom-element-definition` | `compas-scltype-list` | CompasSclTypeList | /src/compas-scl-type-list.js | | +| `js` | `CompasSclTypeList` | CompasSclTypeList | src/CompasSclTypeList.ts | | +| `js` | `TypeSelectedEvent` | TypeSelectedEvent | src/CompasSclTypeList.ts | | diff --git a/components/compas-scl-type-list/custom-elements-manifest.config.js b/components/compas-scl-type-list/custom-elements-manifest.config.js new file mode 100644 index 0000000..d61e4b0 --- /dev/null +++ b/components/compas-scl-type-list/custom-elements-manifest.config.js @@ -0,0 +1,12 @@ +import { readmePlugin } from "cem-plugin-readme"; + +export default { + globs: ["src/*.ts"], + exclude: ["test/*.ts", "stories/*.ts"], + litelement: true, + plugins: [ + readmePlugin({ + to: "components/compas-scl-type-list/README.md", + }), + ], +}; diff --git a/components/oscd-filter-button/README.md b/components/oscd-filter-button/README.md new file mode 100644 index 0000000..7fcc7cc --- /dev/null +++ b/components/oscd-filter-button/README.md @@ -0,0 +1,64 @@ +## `src/oscd-filter-button.ts`: + +### class: `OscdFilterButton`, `oscd-filter-button` + +#### Superclass + +| Name | Module | Package | +| ------------------ | ------ | --------------------------- | +| `OscdFilteredList` | | @openscd/oscd-filtered-list | + +#### Fields + +| Name | Privacy | Type | Default | Description | Inherited From | +| ---------- | ------- | --------- | ------- | -------------------------------- | -------------- | +| `header` | | `string` | | The header of the dialog. | | +| `icon` | | `string` | | The icon of the button. | | +| `disabled` | | `boolean` | `false` | If true, the button is disabled. | | + +#### CSS Properties + +| Name | Default | Description | +| ------------------------ | ------- | ---------------------- | +| `--mdc-theme-on-surface` | | The color of the icon. | + +#### Slots + +| Name | Description | +| ---- | ----------------- | +| | The default slot. | + +
Private API + +#### Fields + +| Name | Privacy | Type | Default | Description | Inherited From | +| -------------- | ------- | -------- | ------- | --------------------------------------- | -------------- | +| `filterDialog` | private | `Dialog` | | the dialog element containing the list. | | + +#### Methods + +| Name | Privacy | Description | Parameters | Return | Inherited From | +| ------------ | ------- | ---------------------------------------------------------------------- | ---------- | ------ | -------------- | +| `toggleList` | private | toggles the dialog containing the list. | | `void` | | +| `onClosing` | private | dispatches a "selected-items-changed" event when the dialog is closed. | | `void` | | + +
+ +
+ +### Exports + +| Kind | Name | Declaration | Module | Package | +| ---- | ------------------ | ---------------- | ------------------------- | ------- | +| `js` | `OscdFilterButton` | OscdFilterButton | src/oscd-filter-button.ts | | + +## `src/OscdFilterButton.ts`: + +### Exports + +| Kind | Name | Declaration | Module | Package | +| --------------------------- | --------------------------- | ------------------------- | -------------------------- | ------- | +| `custom-element-definition` | `oscd-filter-button` | OscdFilterButton | /src/oscd-filter-button.js | | +| `js` | `OscdFilterButton` | OscdFilterButton | src/OscdFilterButton.ts | | +| `js` | `SelectedItemsChangedEvent` | SelectedItemsChangedEvent | src/OscdFilterButton.ts | | diff --git a/components/oscd-filter-button/custom-elements-manifest.config.js b/components/oscd-filter-button/custom-elements-manifest.config.js new file mode 100644 index 0000000..cac3ba1 --- /dev/null +++ b/components/oscd-filter-button/custom-elements-manifest.config.js @@ -0,0 +1,12 @@ +import { readmePlugin } from "cem-plugin-readme"; + +export default { + globs: ["src/*.ts"], + exclude: ["test/*.ts", "stories/*.ts"], + litelement: true, + plugins: [ + readmePlugin({ + to: "components/oscd-filter-button/README.md", + }), + ], +};