Skip to content

Commit

Permalink
Updates
Browse files Browse the repository at this point in the history
  • Loading branch information
@TotallyInformation
TotallyInformation committed Sep 29, 2024
1 parent 0f13f4c commit 423ce20
Show file tree
Hide file tree
Showing 58 changed files with 20,596 additions and 2,576 deletions.
214 changes: 78 additions & 136 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,13 @@ Additional documentation is available in the docs folder which is also exposed a

Install locally using npm or access via [jsdelivr](https://www.jsdelivr.com/package/gh/totallyinformation/web-components).

See the [component documentation](docs) for specific usage information for each component.

<details>
<summary><b>Useage details</b></summary>

### File locations

Files for live use are in the `dist` folder. The alpha quality components are in the `dist/alpha` folder.

Each component has 4 files but you only need 1 of them.
Expand All @@ -26,16 +33,83 @@ If using ES Modules, import the `*.esm.min.js` files in your module code.
import 'https://cdn.jsdelivr.net/gh/totallyinformation/web-components/dist/visible-console.esm.min.js'
```

> [!TIP]
> If using with UIBUILDER for Node-RED, load _after_ the uibuilder client library so that the component registers that uibuilder is in use and becomes responsive to it.

Each component self-registers its custom HTML tag. They also globally self-register their class name so that you can access static variables and functions if needed. The tag name and global name are both listed in the tables below.

When using your browser's developer tools, the matching `.map` file will be loaded. This ensures that reported line numbers and full variable/function names are reported.

The source for the components is in the `src` folder for the main components and in the `alpha` folder for the alpha quality components.

### Useage with UIBUILDER for Node-RED

* You can install the components library using UIBUILDER's library manager.
* In your front-end HTML, load the components _after_ the uibuilder client library so that the components register that uibuilder is in use and becomes responsive to it.

If using with Node-RED, you can install the components with the help of node-red-contrib-uibuilder. The uibuilder node has a library manager feature and you should use that to install the repository direct from GitHub (requires uibuilder v5+). In that case, uibuilder adds the repository to its web server and you can access them as: `../uibuilder/vendor/@totallyinformation/web-components/dist/button-send.js`. See below for details.

### Local installation

If you wish to install locally, you can npm install from the GitHub repository with `npm install totallyinformation/web-components`. If these ever get published to npm, you would install with `npm install @totallyinformation/web-components`. However, note that, at this point, I am not intending to publish them quickly as they are still evolving quite rapidly.

If installing locally, you will need to make the installed `web-components/components/` folder available to your web server as a static resource folder.

### Loading components into your web page

The individual component documentation contains details on how to load the component files. In general, however, there are two choices on how to load them.

#### Load as an ECMA module

This is the preferred method. However, it is generally best to load via a script module. While you can load them via your HTML as a script link, you loose some capability this way.

```html
<script type="module" async>
import '../uibuilder/vendor/@totallyinformation/web-components/components/simple-container.js'
</script>
```

#### Load from HTML with a script tag

They **must** be loaded as a type "module".

```html
<script type="module" async src="https://cdn.jsdelivr.net/gh/totallyinformation/web-components@master/components/button-send.js"></script>
```

Or from the local resource of course. Note that this is not recommended. It is better to load them from a script module and then you can use an import statement.

#### Load from a standard script

Alternatively, you can load them in your main JavaScript script using dynamic imports as:

```html
<script defer async>
import('https://cdn.jsdelivr.net/gh/totallyinformation/web-components@master/components/button-send.js')
</script>
```

The disadvantage of this method is that the import function is asynchronous and so your own code may try to execute before the module has loaded. Generally, this won't matter if you aren't assigning the import to a variable. If you are, you may need to use top-level async or the promise-style then/catch.

The potential advantage of this approach is that you can access exported variables and methods from the component if any are available (see the syntax-highlight component for an example).

### Visual Studio Code (VSCode) Intelligence

VSCode supposts the use of HTML and CSS Custom Data JSON files that describe custom web components and CSS in a way that gives some intelligence to the editor when writing HTML and CSS code.

This collection of web components uses [Web Component Analyzer](https://github.com/runem/web-component-analyzer) to help document the components. It is also used to create an html custom data file that can be added to VSCode or to a specific workspace or folder settings to provide additional Intellisense help for the components.

To do so, find the html custom data setting in VSCode settings and add:

```
/path/to/totallyinformation/web-components/vscode-descriptors/ti-web-components.html-data.json
```


</details>

### Demos

All of the components have demo web pages in `tests`. There is a built-in Node.js mini web server. Running the npm script `tests` will start the server on port 8080. Opening `http://127.0.0.1:8080` or `http://127.0.0.1:8080/list.html` will give a list of all available demos.


## Components

These components can be considered `beta` quality or better. They may not be complete but they should have basic usefulness.
Expand Down Expand Up @@ -119,138 +193,6 @@ There is also a `alpha/no-complete` folder. This contains some components not ye

* `libs/uib-brand.css` - a copy of the alternate (new) stylesheet from uibuilder that these components can use.


## Requirements

These are the requirements for any web component to be included in this repository.

* MUST be standalone with no external requirements. Common internal library modules may be permitted however.
* MUST be useable in the majority of modern browsers, anything supporting ES2019+ should be usable. IE will not be supported.
* MUST use ES6+. Maxumum JavaScript version should be 2 years behind the leading edge and only features supported by the majority of mainstream browsers are allowed. Other features MAY be permitted as long as they are optional and do not produce errors.
* MUST be linted using ESLINT. SHOULD use JavaScript Standard format (with some variations documented in the `.eslintrc.js` file).
* MUST self-register the custom tag using `customElements.define`.
* MUST use a Class name using a _CamelCase_ version of the component name with an initial upper-case letter (e.g. `syntax-highlight` will be `export default class SyntaxHighlight extends HTMLElement { ... }` ).
* MUST be documented in the `docs` folder.{}

* SHOULD have a `<slot>` to allow nested rich content (where it makes sense).
* SHOULD export a _camelCase_ version of the component-name which contains any useful methods and data. (e.g. `syntax-highlight` should export `syntaxHighlight`).
* SHOULD meet the [Web Components Gold Standard](https://github.com/webcomponents/gold-standard/wiki).
* SHOULD define any shadow template content and required component name as static variables in the class.

* [Best practices](https://web.dev/articles/custom-elements-best-practices)

### HTML Standards limitations

* Custom HTML tags MUST use pascal-case with at least 1 `-`.
* Custom HTML tags MUST use lower-case attribute names.

## Installation and loading

You can use these components directly from the jsdelivr CDN by referencing like: `https://cdn.jsdelivr.net/gh/totallyinformation/web-components@master/components/button-send.js`. So no install is required if you are happy to load from the Internet.

### Local installation

If you wish to install locally, you can npm install from the GitHub repository with `npm install totallyinformation/web-components`. If these ever get published to npm, you would install with `npm install @totallyinformation/web-components`. However, note that, at this point, I am not intending to publish them quickly as they are still evolving quite rapidly.

If installing locally, you will need to make the installed `web-components/components/` folder available to your web server as a static resource folder.

### Using with Node-RED and uibuilder

If using with Node-RED, you can install the components with the help of node-red-contrib-uibuilder. The uibuilder node has a library manager feature and you should use that to install the repository direct from GitHub (requires uibuilder v5+). In that case, uibuilder adds the repository to its web server and you can access them as: `../uibuilder/vendor/@totallyinformation/web-components/components/button-send.js`. See below for details.

### Loading components into your web page

The individual component documentation contains details on how to load the component files. In general, however, there are two choices on how to load them.

#### Load as an ECMA module

This is the preferred method. However, it is generally best to load via a script module. While you can load them via your HTML as a script link, you loose some capability this way.

```html
<script type="module" async>
import '../uibuilder/vendor/@totallyinformation/web-components/components/simple-container.js'
</script>
```

#### Load from HTML with a script tag

They **must** be loaded as a type "module".

```html
<script type="module" async src="https://cdn.jsdelivr.net/gh/totallyinformation/web-components@master/components/button-send.js"></script>
```

Or from the local resource of course. Note that this is not recommended. It is better to load them from a script module and then you can use an import statement.

#### Load from a standard script

Alternatively, you can load them in your main JavaScript script using dynamic imports as:

```html
<script defer async>
import('https://cdn.jsdelivr.net/gh/totallyinformation/web-components@master/components/button-send.js')
</script>
```

The disadvantage of this method is that the import function is asynchronous and so your own code may try to execute before the module has loaded. Generally, this won't matter if you aren't assigning the import to a variable. If you are, you may need to use top-level async or the promise-style then/catch.

The potential advantage of this approach is that you can access exported variables and methods from the component if any are available (see the syntax-highlight component for an example).


## Stand-alone use

### Installation and loading

See the general information above.

### Using the components

See the [component documentation](docs) for specific usage information for each component.



## Use with [Node-RED](https://nodered.org/) and [node-red-contrib-uibuilder](https://github.com/TotallyInformation/node-red-contrib-uibuilder)

### Installation and loading

You can, of course, use the components direct from a CDN as shown above.

Otherwise, install this repository using the library manager in a uibuilder node in Node-RED.

<img src="docs/images/2022-04-05-14-03-33.png" alt="uibuilder library manager" width="350"/>

Which results in something like:

<img src="docs/images/2022-04-05-14-09-34.png" alt="uibuilder installed library" width="350"/>

Noting that this library does not actually have a default script so the listed on is spurious.

You can then access the components by loading them into your html or JavaScript as shown above.

### Using the components

The components can, of course, be used in the same way as if not using uibuilder. However, there are additional capabilities aimed at making their use in conjunction with Node-RED and uibuilder even easier. Specifically reducing the amount of code required to use them.

Components will automatically recognise when uibuilder is being used. They will each:

* Have a specific msg schema - when a msg with the matching schema is sent from Node-RED via uibuilder, a singular instance of the component on a page will be automatically updated. Where multiple instances are present, the msg must include an html id so that the msg will target that instance.

See the [component documentation](docs) for specific usage information for each component.



## Visual Studio Code (VSCode) Intelligence

VSCode supposts the use of HTML and CSS Custom Data JSON files that describe custom web components and CSS in a way that gives some intelligence to the editor when writing HTML and CSS code.

This collection of web components uses [Web Component Analyzer](https://github.com/runem/web-component-analyzer) to help document the components. It is also used to create an html custom data file that can be added to VSCode or to a specific workspace or folder settings to provide additional Intellisense help for the components.

To do so, find the html custom data setting in VSCode settings and add:

```
/path/to/totallyinformation/web-components/vscode-descriptors/ti-web-components.html-data.json
```

## Discussions and suggestions

The best place to ask questions, or suggest improvements about these components is the [GitHub discussion board for this repository](https://github.com/TotallyInformation/web-components/discussions).
Expand Down
2 changes: 1 addition & 1 deletion alpha/labelled-value.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -172,7 +172,7 @@ export default class LabelledValue extends HTMLElement {
}
}

document.dispatchEvent(new CustomEvent(`${componentName}:attribChanged`, {
document.dispatchEvent(new CustomEvent(`${this.localName}:attribChanged`, {
bubbles: true,
composed: true,
detail: {
Expand Down
13 changes: 11 additions & 2 deletions docs/dev.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,14 @@ updated: 2024-09-22 14:34:05

## Standards

These are the requirements and standards for any web component to be included in this repository.

* MUST be standalone with no external requirements. Common include library modules (e.g. charts) MAY be imported however. The resulting file MUST be useable stand-alone.
* MUST be useable in the majority of modern browsers, anything supporting ES2019+ should be usable. IE will not be supported.

* All components MUST self register the custom tag AND their Class Name. All tag namess are lower-case with at least one dash (_kebab-case_) . All Class names start with an upper-case letter and the name is the tag name in _PascalCase_. MUST self-register the custom tag using `customElements.define`.
* The Class is the default export and is also self-registered to the window global.
* MUST provide source-code in either `./src` (for production ready components) or `./alpha`. Any component in `./src` MUST be usable even if it is not feature complete.
* MUST be useable in the majority of modern browsers. IE will not be supported.
* MUST be standalone with no external requirements. Common include library modules (e.g. charts) MAY be imported however. The resulting file MUST be useable stand-alone.
* MUST have both IIFE and ESM minimised versions built using ESBUILD. The built versions should target common browser features no newer than 2-years old. Built versions will be in the `./dist` folder with alpha quality components built to the `./dist/alpha` folder. All built versions will include `.map` files for debugging.
* MUST use JSDoc to self-document. MUST use ESLint and follow the modified _JavaScript Standard_ formatting.
* MUST provide a document file in `./docs` describing use, settings, etc.
Expand All @@ -29,10 +32,16 @@ updated: 2024-09-22 14:34:05
* MUST NOT be dependent on UIBUILDER for Node-RED. SHOULD be enhanced if the UIBUILDER client library is loaded.
* SHOULD be derived from the `./libs/ti-base-component.js` class to inherit standard properties and methods.
* SHOULD meet the [Web Components Gold Standard](https://github.com/webcomponents/gold-standard/wiki).
* SHOULD follow [Best practices](https://web.dev/articles/custom-elements-best-practices).
* SHOULD have a `<slot>` to allow nested rich content (where it makes sense).

* Where _static_ properties or methods are referred to, `this.constructor` should be used rather than the class name. This avoids errors should the class ever be renamed or the code copied to a different class. Similarly, `this.localName` can be used to get the class name as text which should be used in debugging and error logging.

### HTML Standards limitations

* Custom HTML tags MUST use pascal-case with at least 1 `-`.
* Custom HTML tags MUST use lower-case attribute names.

## Styling

Where shadow dom is used (most of these components), note that style isolation between parent and component instance applies.
Expand Down
0 docs/data-list.md → docs/dynamic-list.md
View file
File renamed without changes.
58 changes: 58 additions & 0 deletions docs/ideas.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
---
title: Ideas for future components and enhancements
description: |
Where might we go?
created: 2024-09-25 02:04:04
updated: 2024-09-28 13:24:19
---

## Possible future components

### Version of uib-var

* Shows content from a JavaScript variable.
* Possibly allows dynamic overrides of attributes.
* Test with component version text.

### `light-switch` - on/off, level, colour. Location.

### `layout-area` - Switch between a few core layouts such as blog & dash
#### `area-*` - Define an area for a layout, e.g. `area-main`, `area-head`, `area-foot`, `area-sidebar` - all included in the parent component's package.

### `smart-list` - 2-way data controllable list wrapper

* Wraps around lists to easily add different entry formats including numbering (nested), icons, checkboxes, prefixes (e.g. dates)
* Dynamic property to store contents - ideally 2-way
* Multiple ways to update content: DOM changes, custom event, proxied property. For uibuilder: auto-topic updates
* Optionally drag/drop to re-order with data property updated
* Optionally content editable - double-click on icon, prefix and text to edit
* Optional checkbox with data store
* UIBUILDER data enabled. Controllable updates back to Node-RED (e.g. when no longer visible or immediate)

### `smart-report` - Like collapsible-headings but also data controllable

* Wraps around a collection of `<hx>` and `<p>`/`<div>`/`<img>` tags adding smarter formatting and control
* Optional collapsible headings
* Optional numbered headings (including nested numbers), format controllable
* Dynamic property to store contents - ideally 2-way
* Multiple ways to update content: DOM changes, custom event, proxied property. For uibuilder: auto-topic updates
* *Maybe - Optional drag/drop re-oder*
* *Maybe - double-click to content edit*

### `linear-gauge`

* horizontal/vertical
* Segmented (led style) or smooth
* Multiple colour segments
* Optional current value with positioning

Refs: [1](https://discourse.nodered.org/t/gauges-for-dashboard-2-0-made-with-ui-template/85955), Discourse vert indicators.


## Thoughts

* Any way to have a component that is able to get meta-data from another component. Eg version, docs, etc?

* Article with heading should be collapsible

* Each component could have a getter to output their own TODO lists!
Loading

0 comments on commit 423ce20

Please sign in to comment.