### Install and Authenticate GitHub CLI

Source: https://github.com/totallyinformation/web-components/blob/main/libs/RELEASE.md

Instructions for installing GitHub CLI using `winget` on Windows and authenticating with GitHub, which is a prerequisite for the release script to interact with GitHub repositories.

```bash
# Install GitHub CLI (if not already installed)
winget install GitHub.cli

# Authenticate with GitHub
gh auth login
```

--------------------------------

### Examples of Creating New Web Components

Source: https://github.com/totallyinformation/web-components/blob/main/libs/CREATE-COMPONENT.md

Demonstrates various examples of using the `npm run new-component` command to scaffold different types of web components, such as `chart-display`, `form-builder`, and `data-grid`. These examples illustrate the command-line usage for specific component names.

```bash
# Create a new chart component
npm run new-component chart-display

# Create a new form component  
npm run new-component form-builder

# Create a new data component
npm run new-component data-grid
```

--------------------------------

### SimpleCard HTML Usage Example

Source: https://github.com/totallyinformation/web-components/blob/main/docs/jsdoc/alpha_simple-card.js.html

An example demonstrating how to instantiate the `SimpleCard` web component in HTML, setting its `name` and `inherit-style` attributes.

```HTML
<simple-card name="myComponent" inherit-style="./myComponent.css"></simple-card>
```

--------------------------------

### Instantiate visible-console Web Component

Source: https://github.com/totallyinformation/web-components/blob/main/docs/jsdoc/Beta.html

Simple HTML example showing how to include the `visible-console` web component in a web page.

```html
<visible-console></visible-console>
```

--------------------------------

### Basic Web Component Usage Example

Source: https://github.com/totallyinformation/web-components/blob/main/docs/readme/component-template.md

A simple HTML snippet demonstrating how to include and use the `visible-console` web component in a web page.

```HTML
<visible-console></visible-console>
```

--------------------------------

### Instantiate visible-console Component in HTML

Source: https://github.com/totallyinformation/web-components/blob/main/docs/jsdoc/Beta.html

Basic HTML example demonstrating how to include the `visible-console` web component in a web page.

```HTML
<visible-console></visible-console>
```

--------------------------------

### Release Script Command Line Options and Usage Examples

Source: https://github.com/totallyinformation/web-components/blob/main/libs/RELEASE.md

Demonstrates various `npm run` commands for specific release scenarios, such as dry-run, tag-only, or publish-only. It also shows the direct execution of the `release.mjs` script with command-line options.

```bash
# Preview what would happen without making changes
npm run release:dry-run

# Only create Git tag and GitHub release (no npm publish)
npm run release:tag-only

# Only publish to npm (requires existing tag)
npm run release:publish-only

# Direct script usage with options
node ./libs/release.mjs [options]
```

--------------------------------

### API Reference for syntax-highlight Web Component

Source: https://github.com/totallyinformation/web-components/blob/main/docs/jsdoc/Beta.html

Details the custom events, properties, and an example for the `syntax-highlight` web component, a zero-dependency ECMA module designed to convert objects to HTML.

```APIDOC
syntax-highlight Web Component:
  Description: A zero dependency custom web component ECMA module that converts objects to HTML.
  
  Custom Events:
    component-template:connected
      Description: Triggered when an instance of the component is attached to the DOM.
      Details: evt.details contains the details of the element.
    component-template:ready
      Description: Alias for 'connected'. The instance can handle property & attribute changes.
    component-template:disconnected
      Description: Triggered when an instance of the component is removed from the DOM.
      Details: evt.details contains the details of the element.
    component-template:attribChanged
      Description: Triggered when a watched attribute changes.
      Details: evt.details.data contains the details of the change.
      Note: Listeners can be attached either to the document or to the specific element instance.
  
  Properties:
    inherit-style
      Type: string | boolean
      Description: Optional. Loads external styles into component (only useful if using template). If present but empty, defaults to './index.css'. Optionally accepts a URL to load.
    name
      Type: string
      Description: Optional. HTML name attribute. Included in output _meta prop.
    componentVersion
      Type: string (Static)
      Description: The component version string (date updated). Also has a getter that returns component and base version strings.
    json
      Type: object | JSON | string
      Description: JSON to convert. By default, all attributes are also created as properties.
  
  Example Usage:
    Set the json property on the element:
    const showMsg = document.getElementsByTagName('syntax-highlight')[0];
    showMsg.json({....});
```

--------------------------------

### JavaScript Example: Setting JSON Property on SyntaxHighlight Component

Source: https://github.com/totallyinformation/web-components/blob/main/docs/jsdoc/Beta.html

Illustrates how to access an instance of the `syntax-highlight` web component in JavaScript and set its `json` property.

```javascript
const showMsg = document.getElementsByTagName('syntax-highlight')[0]
showMsg.json({....})
```

--------------------------------

### Instantiate visible-console Web Component

Source: https://github.com/totallyinformation/web-components/blob/main/docs/jsdoc/Beta.html

A basic HTML example demonstrating how to include the `visible-console` web component directly within a web page using its custom element tag.

```HTML
<visible-console></visible-console>
```

--------------------------------

### Run local development server for demos and docs

Source: https://github.com/totallyinformation/web-components/blob/main/README.md

This npm script starts a Node.js mini web server on port 8788, providing access to all available demos, documentation, and source code. It requires the Cloudflare `wrangler` server to be downloaded upon first run.

```Shell
npm run tests
```

--------------------------------

### HTML Usage Example for visible-console Web Component

Source: https://github.com/totallyinformation/web-components/blob/main/docs/jsdoc/Beta.html

This snippet demonstrates the basic HTML tag for integrating the `visible-console` web component into a web page. It shows how to instantiate the component without any attributes.

```HTML
<visible-console></visible-console>
```

--------------------------------

### HTML Example for Smart List Web Component

Source: https://github.com/totallyinformation/web-components/blob/main/docs/roadmap.md

Demonstrates the basic usage of the <smart-list> web component with attributes for data binding, ordering, prefixing, and checkboxes. It includes a nested <smart-item> to represent an individual list entry.

```HTML
<smart-list data="myData" type="ordered" prefix="date" checkbox>
  <smart-item><span>1</span> <span>Item 1</span></smart-item>
</smart-list>
```

--------------------------------

### Load Web Component as ES Module via HTML Script Tag (Local UIBUILDER)

Source: https://github.com/totallyinformation/web-components/blob/main/docs/using.md

This example shows how to load a web component as an ES Module using an inline HTML script tag, specifically when components are installed locally via UIBUILDER. The `type="module"` attribute enables ES Module syntax, and `async` ensures non-blocking asynchronous loading. This method is ideal for integrating components within a Node-RED UIBUILDER environment.

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

--------------------------------

### Example HTML Usage of DataList Component

Source: https://github.com/totallyinformation/web-components/blob/main/docs/jsdoc/data-list.js.html

Demonstrates how to instantiate and use the `DataList` web component in HTML, setting its ID, type, and inherited style.

```HTML
<data-list id="myComponent" type="ol" inherit-style="./myComponent.css"></data-list>
```

--------------------------------

### Example Web Component Template Structure

Source: https://github.com/totallyinformation/web-components/blob/main/docs/jsdoc/alpha_smart-table.js.html

An example of a commented-out HTML template for a web component, demonstrating basic structure with a style block for host styling and media queries, and a slot for content. This template is not currently in use but shows a common pattern for web component shadow DOM.

```JavaScript
// const template = document.createElement('template')
// template.innerHTML = /*html*/`
//     <style>
//         :host {
//         }

//         /* Small screen (37.5em @ 16pt is about 600px) */
//         @media all and (max-width: 37.5em) {
//             :host {
//             }
//         }
//     </style>
//     <div><slot></slot></div>
// `
```

--------------------------------

### Example Usage of simple-card Web Component

Source: https://github.com/totallyinformation/web-components/blob/main/docs/readme/simple-card.md

Demonstrates how to embed the `simple-card` web component in an HTML document, setting its `name` and `inherit-style` attributes to load external styles.

```html
<simple-card name="myComponent" inherit-style="./myComponent.css"></simple-card>
```

--------------------------------

### SyntaxHighlight Web Component API Reference: Class & Usage

Source: https://github.com/totallyinformation/web-components/blob/main/docs/jsdoc/syntax-highlight.js.html

Comprehensive API documentation for the `syntax-highlight` web component, detailing its inheritance from `TiBaseComponent`, its HTML tag usage (`<syntax-highlight>`), and an example of how to programmatically set its `json` property.

```APIDOC
@class SyntaxHighlight
@augments TiBaseComponent
@description Define a new zero dependency custom web component ECMA module that can be used as an HTML tag

@element syntax-highlight
@memberOf Beta

@example Set the json property on the element
  const showMsg = document.getElementsByTagName('syntax-highlight')[0]
  showMsg.json({....})
```

--------------------------------

### HTML Usage Example for led-gauge Web Component

Source: https://github.com/totallyinformation/web-components/blob/main/docs/components/live/led-gauge.md

Demonstrates how to embed the `led-gauge` web component in an HTML document, setting its initial attributes like segments, min, max, unit, and value, along with a label.

```HTML
<led-gauge segments="10" min="0" max="100" unit="%" value="20">Gauge label</led-gauge>
```

--------------------------------

### visible-console Web Component API Reference

Source: https://github.com/totallyinformation/web-components/blob/main/docs/jsdoc/Beta.html

Documentation for the `visible-console` web component, a zero-dependency component designed to display JavaScript console output on-page. It details properties, custom events, and an HTML usage example.

```APIDOC
visible-console Web Component:
  Description: A zero dependency web component that will display JavaScript console output on-page.

  Methods:
    (static) createHTMLVisualizer: Creates an HTML visualisation of the input. (Note: The description following this method header in the source text actually describes the component itself, not just this method.)

  Custom Events:
    "visible-console:connected": When an instance of the component is attached to the DOM. `evt.details` contains the details of the element.
    "component-template:ready": Alias for connected. The instance can handle property & attribute changes.
    "visible-console:disconnected": When an instance of the component is removed from the DOM. `evt.details` contains the details of the element.
    "visible-console:attribChanged": When a watched attribute changes. `evt.details` contains the details of the change.
      Note: Listeners can be attached either to the `document` or to the specific element instance.

  Properties:
    inherit-style:
      Type: string | boolean
      Description: Optional. Load external styles into component (only useful if using template). If present but empty, will default to './index.css'. Optionally give a URL to load.
    name:
      Type: string
      Description: Optional. HTML name attribute. Included in output _meta prop.
    componentVersion:
      Type: string (Static)
      Description: The component version string (date updated). Also has a getter that returns component and base version strings.
    colors:
      Type: object
      Description: The colors to use for different console output types.
    bgColors:
      Type: object
      Description: The background colors to use for different console output types.
    icons:
      Type: object
      Description: The icons to use for different console output types.

  Usage Example:
    <visible-console></visible-console>
```

--------------------------------

### syntax-highlight Web Component API and Usage

Source: https://github.com/totallyinformation/web-components/blob/main/docs/jsdoc/Beta.html

Documents the `syntax-highlight` web component, which converts JSON objects to HTML. It details custom events, properties like `inherit-style`, `name`, `componentVersion`, and `json`, and provides a JavaScript example for setting the `json` property.

```APIDOC
Custom Events:
  "component-template:connected"
    - Description: When an instance of the component is attached to the DOM. `evt.details` contains the details of the element.
  "component-template:ready"
    - Description: Alias for connected. The instance can handle property & attribute changes.
  "component-template:disconnected"
    - Description: When an instance of the component is removed from the DOM. `evt.details` contains the details of the element.
  "component-template:attribChanged"
    - Description: When a watched attribute changes. `evt.details.data` contains the details of the change.
    - Note: Listeners can be attached either to the `document` or to the specific element instance.

Properties:
  `inherit-style`
    - Type: string | boolean
    - Description: Optional. Load external styles into component (only useful if using template). If present but empty, will default to './index.css'. Optionally give a URL to load.
  `name`
    - Type: string
    - Description: Optional. HTML name attribute. Included in output _meta prop.
  `componentVersion`
    - Type: string
    - Description: Static. The component version string (date updated). Also has a getter that returns component and base version strings.
  `json`
    - Type: object | JSON | string
    - Description: JSON to convert. By default, all attributes are also created as properties.
```

```JavaScript
const showMsg = document.getElementsByTagName('syntax-highlight')[0]
showMsg.json({....})
```

--------------------------------

### Basic Usage Example for button-send Web Component

Source: https://github.com/totallyinformation/web-components/blob/main/docs/readme/button-send.md

This HTML snippet demonstrates how to instantiate and use the `button-send` web component in a web page. It shows a simple button that, when clicked, will trigger the component's internal logic to send a message or event.

```html
<button-send id="myButton">
     Click me to send a message
 </button-send>
```

--------------------------------

### Get HTML Element Reference by Cell ID in JavaScript

Source: https://github.com/totallyinformation/web-components/blob/main/docs/components/alpha/smart-table.md

Demonstrates how to retrieve an HTML element reference for a specific cell within a smart-table using its `RxCx` identifier. This allows for direct DOM manipulation, such as styling, but notes that such changes are not responsive to data updates. The example shows how to get the element, log its content, and apply styling based on its value.

```javascript
const tbl1 = document.getElementById('smart-table-1') // @type {HTMLTableElement}
const cellEl = tbl1.getCellById('R2C3') // @type {HTMLTableCellElement}
if (cellEl) {
  console.log('Reference to cell in row 2, column 3: ', cellEl)
  console.log('The text content of cell R2C3 is: ', cellEl.innerText)
  // At present, this kind of processing is not responsive to data changes
  if ( tbl1.getValueByCellId('R2C3') === 'R2C3' ) {
    cellEl.style.backgroundColor = 'darkgreen' // background-color: 'darkgreen'
  }
} else {
  console.warn('Cell R2C3 not found')
}
```

--------------------------------

### Execute Full Release Process

Source: https://github.com/totallyinformation/web-components/blob/main/libs/RELEASE.md

The recommended command to initiate the complete release process. This single command handles all steps including pre-release checks, Git tagging, GitHub release creation, and npm package publishing.

```bash
npm run release
```

--------------------------------

### Multi-Way Switch Component HTML Usage Examples

Source: https://github.com/totallyinformation/web-components/blob/main/docs/jsdoc/alpha_multi-way-switch.js.html

Illustrates how to use the <multi-way-switch> web component in HTML, demonstrating its three display modes: 'buttons', 'slider', and 'knob'. Each example specifies the number of positions and custom values.

```HTML
<multi-way-switch mode="buttons" positions="5" values="10,20,30,40,50"></multi-way-switch>
<multi-way-switch mode="slider" positions="3" values="low,medium,high"></multi-way-switch>
<multi-way-switch mode="knob" positions="4" values="1,2,4,8"></multi-way-switch>
```

--------------------------------

### Get Data Value by Cell ID in JavaScript

Source: https://github.com/totallyinformation/web-components/blob/main/docs/components/alpha/smart-table.md

Illustrates how to retrieve the actual data value of a cell from the smart-table's underlying dataset using its `RxCx` identifier. This method directly accesses the dataset and returns the correct data type as stored, providing a reliable way to get cell data.

```javascript
const tblEl = document.getElementById('st1') // @type {HTMLTableElement}
const cellValue = tblEl.getValueByCellId('R3C4') // @type {*}
console.log(cellValue, ' <= Value of cell 4th inner property of the 3rd outer property')
```

--------------------------------

### Split Release Process (Tag First, Publish Later)

Source: https://github.com/totallyinformation/web-components/blob/main/libs/RELEASE.md

Demonstrates how to execute the release process in two separate stages. First, create the Git tag and GitHub release, and then, at a later time, publish the package to npm.

```bash
# First, create tag and GitHub release
npm run release:tag-only

# Later, publish to npm
npm run release:publish-only
```

--------------------------------

### Initialize Web Component and Get Version in JavaScript

Source: https://github.com/totallyinformation/web-components/blob/main/tests/_test-template.html

This JavaScript snippet demonstrates how to interact with a web component after the DOM is fully loaded. It retrieves the version of a 'XxxxXxxx' component and gets a reference to another component with ID 'wc01'. This ensures that component-related operations are performed only when the necessary elements are available in the DOM.

```javascript
/** We usually need to wait for everything to be loaded before using components from JavaScript */
addEventListener("DOMContentLoaded", (event) => {
    // What version are we using? This is static so we use the class global reference
    document.getElementById('op2').value = XxxxXxxx.version
    // Get references to the elements
    const wc01 = document.querySelector('#wc01')
})
```

--------------------------------

### Initialize Web Component and Get Version on DOMContentLoaded

Source: https://github.com/totallyinformation/web-components/blob/main/tests/live/h1-title.html

This JavaScript snippet demonstrates how to interact with web components after the DOM is fully loaded. It listens for the `DOMContentLoaded` event, retrieves the version of the `H1Title` component, and gets a reference to another web component (`#wc01`). This ensures that web components are available before JavaScript attempts to manipulate them.

```JavaScript
/** We usually need to wait for everything to be loaded before using components from JavaScript */
addEventListener("DOMContentLoaded", (event) => {
  // What version are we using? This is static so we use the class global reference
  document.getElementById('op2').value = H1Title.version
  // Get references to the elements
  const wc01 = document.querySelector('#wc01')
})
```

--------------------------------

### Release Script Command Line Options Reference

Source: https://github.com/totallyinformation/web-components/blob/main/libs/RELEASE.md

Defines the available command-line arguments for the `release.mjs` script, detailing their purpose and effect on the release process. These options allow for fine-grained control over script execution.

```APIDOC
--dry-run: Show what would be done without executing
--skip-checks: Skip pre-release checks (linting, tests, build)
--tag-only: Only create Git tag and GitHub release
--publish-only: Only publish to npm (requires existing tag)
--verbose: Enable verbose logging (default)
--quiet: Disable verbose logging
--help, -h: Show help message
```

--------------------------------

### syntax-highlight Web Component API Reference

Source: https://github.com/totallyinformation/web-components/blob/main/docs/readme/syntax-highlight.md

Comprehensive API documentation for the `syntax-highlight` web component, detailing its attributes, properties, methods, and slots. This reference covers how to interact with the component programmatically and customize its behavior.

```APIDOC
Attributes:
  - `auto`: (No description provided)

Properties:
  - `$` (function(string): Element):
    Description: Mini jQuery-like shadow dom selector (see constructor)
  - `$$` (function(string): NodeList):
    Description: Mini jQuery-like shadow dom multi-selector (see constructor)
  - `connected` (boolean, default: false):
    Description: True when instance finishes connecting. Allows initial calls of attributeChangedCallback to be ignored if needed.
  - `inherit-style` (string|boolean, attribute: `inherit-style`):
    Description: Optional. Load external styles into component (only useful if using template). If present but empty, will default to './index.css'. Optionally give a URL to load.
  - `json`:
    Description: Element.json = {...} to show the json object
  - `jsonData` (object, default: {}):
    Description: (No description provided)
  - `name` (string, attribute: `name`):
    Description: Optional. HTML name attribute. Included in output _meta prop. Other watched attributes: None. PROPS FROM BASE: (see TiBaseComponent) OTHER STANDARD PROPS:
  - `opts` (object, default: {}):
    Description: Runtime configuration settings
  - `uib` (boolean, default: false):
    Description: Is UIBUILDER for Node-RED loaded?
  - `uibuilder` (default: "window['uibuilder']"):
    Description: (No description provided)

Methods:
  - `config(config: object|undefined): object`
    Description: OPTIONAL. Update runtime configuration, return complete config
    Parameters:
      - `config`: If present, partial or full set of options. If undefined, fn returns the current full option settings
  - `createShadowSelectors(): void`
    Description: Creates the $ and $$ fns that do css selections against the shadow dom
  - `doInheritStyles(): Promise<void>`
    Description: Optionally apply an external linked style sheet (called from connectedCallback)
    Parameters:
      - `url`: The URL for the linked style sheet (from description, not signature)
  - `ensureId(): void`
    Description: Ensure that the component instance has a unique ID & check again if uib loaded
  - `prependStylesheet(cssText: string, order?: number): Element`
    Description: Attaches a new stylesheet before all other stylesheets in the light DOM
    Parameters:
      - `cssText`: CSS text to inject directly
      - `order`: Optional order/priority for stylesheet placement. Lower numbers = higher priority (inserted first). Defaults to 0.
  - `uibSend(evtName: string, data: string): void`
    Description: Send a message to the Node-RED server via uibuilder if available. NB: These web components are NEVER dependent on Node-RED or uibuilder.
    Parameters:
      - `evtName`: The event name to send
      - `data`: The data to send

Slots:
  - (unnamed):
    Description: Container contents. See https://github.com/runem/web-component-analyzer?tab=readme-ov-file#-how-to-document-your-components-using-jsdoc
```

--------------------------------

### Set JSON Property on syntax-highlight Component

Source: https://github.com/totallyinformation/web-components/blob/main/docs/jsdoc/Beta.html

Example demonstrating how to set the `json` property on an instance of the `syntax-highlight` web component using JavaScript.

```JavaScript
const showMsg = document.getElementsByTagName('syntax-highlight')[0]
showMsg.json({....})
```

--------------------------------

### Basic Usage of component-template Web Component

Source: https://github.com/totallyinformation/web-components/blob/main/docs/readme/component-template.md

Demonstrates the basic HTML usage of the `component-template` web component, showing how to instantiate it and link an external stylesheet.

```html
<component-template name="myComponent" inherit-style="./myComponent.css"></component-template>
```

--------------------------------

### Execute Web Component Development Workflow Commands

Source: https://github.com/totallyinformation/web-components/blob/main/docs/dev.md

This snippet outlines the essential `npm` commands used throughout the web component development lifecycle, from continuous watching and building to testing and preparing documentation bundles. These commands automate compilation, testing, and deployment preparation.

```Shell
npm run watch
npm run build
npm run test
npm run buildDocBundle
```

--------------------------------

### Overriding labelled-value CSS Variables in HTML

Source: https://github.com/totallyinformation/web-components/blob/main/docs/components/beta/labelled-value.md

Shows examples of how to override the default CSS variables for specific `labelled-value` instances directly within the HTML `style` attribute.

```html
<labelled-value label="My Label" value="My Value" style="--label-font: italic small-caps bold 16px/2 cursive;"></labelled-value>
<labelled-value label="No value label" style="--label-before: '>> ℹ️ &quot;';--label-after: '&quot;';"></labelled-value>
```

--------------------------------

### Example Usage of State Timeline Web Component

Source: https://github.com/totallyinformation/web-components/blob/main/docs/jsdoc/alpha_state-timeline.js.html

Demonstrates how to embed the `state-timeline` web component into an HTML page for displaying state changes.

```HTML
<div id="container">
  <state-timeline></state-timeline>
</div>
```

--------------------------------

### HTML Usage Example for simple-container Web Component

Source: https://github.com/totallyinformation/web-components/blob/main/docs/components/alpha/simple-container.md

Demonstrates how to embed the `simple-container` web component in an HTML document, acting as a flexible wrapper for other custom elements like `simple-card`.

```html
<simple-container>
    <simple-card>This is a simple card.</simple-card>
    <simple-card>This is another simple card.</simple-card>
</simple-container>
```

--------------------------------

### syntax-highlight Web Component API Reference

Source: https://github.com/totallyinformation/web-components/blob/main/docs/components/beta/syntax-highlight.md

Comprehensive API documentation for the `syntax-highlight` web component, detailing its configurable attributes, accessible properties, and utility methods for programmatically highlighting data.

```APIDOC
syntax-highlight Web Component API:

Attributes:
  auto:
    Description: Automatically highlight JSON or JavaScript objects. Default is `true`.

Properties:
  auto: boolean
    Attribute: `auto`
    Default: `true`
    Description: Automatically highlight JSON or JavaScript objects.
  json: string | object
    Attribute: N/A
    Default: ""
    Description: The JSON or JavaScript object to highlight.

Methods:
  highlight(data: any): HTMLElement (Static)
    Description: Returns highlighted JSON wrapped in a `<pre>` tag.
```

--------------------------------

### Web Component Analyzer CLI Commands for Documentation Generation

Source: https://github.com/totallyinformation/web-components/blob/main/docs/jsdoc/alpha_uib-theme-changer.js.html

Provides command-line interface (CLI) examples for using `web-component-analyzer` to generate and update documentation for web components. This includes commands for creating JSDoc-based documentation and generating VS Code custom data files, facilitating consistent and automated documentation workflows.

```Shell
npx web-component-analyzer ./components/button-send.js
```

```Shell
npx web-component-analyzer ./components/*.js --format vscode --outFile ./vscode-descriptors/ti-web-components.html-data.json
```

--------------------------------

### syntax-highlight Web Component Properties API

Source: https://github.com/totallyinformation/web-components/blob/main/docs/jsdoc/Beta.html

Detailed API reference for the `syntax-highlight` web component, outlining its configurable properties, their types, and descriptions.

```APIDOC
"syntax-highlight" Component Properties:
  inherit-style: string | boolean
    Optional. Load external styles into component (only useful if using template). If present but empty, will default to './index.css'. Optionally give a URL to load.
  name: string
    Optional. HTML name attribute. Included in output _meta prop. Other watched attributes: None PROPS FROM BASE: (see TiBaseComponent) OTHER STANDARD PROPS:
  componentVersion: string
    Static. The component version string (date updated). Also has a getter that returns component and base version strings. Other props:
  json: object | JSON | string
    JSON to convert. By default, all attributes are also created as properties.
```

--------------------------------

### Basic Usage of simple-card Web Component

Source: https://github.com/totallyinformation/web-components/blob/main/docs/components/alpha/simple-card.md

Demonstrates how to embed the `simple-card` web component in HTML, including examples for basic content display and utilizing the optional `header` and `footer` slots for structured content.

```HTML
<simple-card>
  Some content in a card.
</simple-card>
```

```HTML
<simple-card>
  Hello, in a card
  <span slot="header">Some other header</span>
  <span slot="footer">Some footer</span>
</simple-card>
```

--------------------------------

### SyntaxHighlight Class API Reference

Source: https://github.com/totallyinformation/web-components/blob/main/docs/jsdoc/SyntaxHighlight.html

Detailed API documentation for the `SyntaxHighlight` custom element, including its constructor, properties, and methods for managing and displaying syntax-highlighted JSON.

```APIDOC
Class: SyntaxHighlight

Constructor:
  new SyntaxHighlight()
    - Description: Initializes a new SyntaxHighlight instance. Note: Attributes are not available directly in the constructor; use `connectedCallback` for attribute references.

Members:
  componentVersion
    - Type: string
    - Description: The version string of the component.

  json
    - Type: object | JSON
    - Description: Property to set a JSON object for display. Example usage: `Element.json = {...}`.

  (static) observedAttributes
    - Type: Array<string>
    - Description: A static property that defines which HTML attributes the component should observe for changes. When these attributes change, `attributeChangedCallback` is invoked.

Methods:
  attributeChangedCallback(attrib: string, oldVal: string, newVal: string)
    - Description: Invoked when one of the `observedAttributes` changes. Note: all attribute values are always strings.
    - Parameters:
      - `attrib`: (string) The name of the watched attribute that has changed.
      - `oldVal`: (string) The previous value of the attribute.
      - `newVal`: (string) The new value of the attribute.

  connectedCallback()
    - Description: Lifecycle callback invoked when the custom element is first connected to the document's DOM.

  disconnectedCallback()
    - Description: Lifecycle callback invoked when the custom element is disconnected from the document's DOM.

  (static) highlight(json: object | JSON) -> HTMLElement
    - Description: A static method that takes a JSON object and returns its formatted HTML representation, typically wrapped in a `<pre>` tag for display.
    - Parameters:
      - `json`: (object | JSON) The JSON object to be converted and highlighted.
    - Returns:
      - `HTMLElement`: An HTML element containing the syntax-highlighted JSON.
```

--------------------------------

### SmartTable: Build Column Metadata

Source: https://github.com/totallyinformation/web-components/blob/main/docs/jsdoc/SmartTable.html

An internal method responsible for constructing the column metadata for the `SmartTable`. It can optionally derive column definitions directly from the provided data, simplifying table setup.

```APIDOC
_buildCols(fromData)
  - Description: Builds the column metadata for the table.
  - Parameters:
    - fromData: boolean - If true, columns are calculated and built based on the provided data.
```

--------------------------------

### Visual Log Web Component (`visual-log`)

Source: https://github.com/totallyinformation/web-components/blob/main/docs/roadmap.md

Describes a component that creates an on-page log element. This log expands to a set number of lines and then drops older entries from the start.

```APIDOC
visual-log:
  Description: Creates a log element on-page that expands to a set number of lines then drops from the start.
```

--------------------------------

### Test Release Process with Dry Run

Source: https://github.com/totallyinformation/web-components/blob/main/libs/RELEASE.md

Command to perform a dry run of the release process. This allows users to preview all actions the script would take without actually making any changes, useful for testing and validation.

```bash
npm run release:dry-run
```

--------------------------------

### chart-statetrail Range Mapping Object Schema and Default

Source: https://github.com/totallyinformation/web-components/blob/main/docs/components/experiments/chart-statetrail.md

Defines the required JSON array structure for mapping input values to colors and titles, used by the `chart-statetrail` component for visual representation. Includes a default example.

```APIDOC
Range mapping object:
[
    { "range": [<number>, <number>], "title": <string>, "color": <CSScolor> },
    ...
]

Default example:
[
    { "range": [0, 0.3], "title": "Off", "color": "var(--failure, red)" },
    { "range": [0.3, 0.6], "title": "Partial", "color": "var(--warning, #c8b421)" },
    { "range": [0.6, 1], "title": "On", "color": "var(--success, green)" }
]
```

--------------------------------

### syntax-highlight Web Component API Reference

Source: https://github.com/totallyinformation/web-components/blob/main/docs/jsdoc/Beta.html

Comprehensive API documentation for the `syntax-highlight` web component, detailing its custom events and properties. This zero-dependency component converts JSON objects into HTML for display.

```APIDOC
syntax-highlight Web Component API

Custom Events:
  - "component-template:connected"
    Description: Triggered when an instance of the component is attached to the DOM.
    Details: `evt.details` contains the details of the element.
  - "component-template:ready"
    Description: Alias for "component-template:connected". Indicates the instance is ready to handle property & attribute changes.
  - "component-template:disconnected"
    Description: Triggered when an instance of the component is removed from the DOM.
    Details: `evt.details` contains the details of the element.
  - "component-template:attribChanged"
    Description: Triggered when a watched attribute changes.
    Details: `evt.details.data` contains the details of the change.
    Note: Listeners can be attached either to the `document` or to the specific element instance.

Properties:
  - `inherit-style`
    Type: string | boolean
    Description: Optional. Loads external styles into the component (only useful if using a template). If present but empty, defaults to './index.css'. Can also be a URL to load.
  - `name`
    Type: string
    Description: Optional. HTML name attribute. Included in the output `_meta` property.
  - `componentVersion`
    Type: string
    Description: Static. The component version string (date updated). Has a getter returning component and base version strings.
  - `json`
    Type: object | JSON | string
    Description: The JSON data to convert. By default, all attributes are also created as properties.
```

--------------------------------

### API Methods for visible-console Web Component

Source: https://github.com/totallyinformation/web-components/blob/main/docs/readme/component-template.md

Comprehensive documentation for all public methods available on the `visible-console` web component, including their signatures, descriptions, parameters, and return types.

```APIDOC
Methods:

checkType(input: *): string
  - Description: Find out the input JavaScript var type
  - Parameters:
    - input: The JavaScript var to type
  - Returns: string

config(config: object|undefined): object
  - Description: OPTIONAL. Update runtime configuration, return complete config
  - Parameters:
    - config: If present, partial or full set of options. If undefined, fn returns the current full option settings
  - Returns: object

createHTMLVisualizer(input: *): HTMLDivElement
  - Description: Creates an HTML visualisation of the input
  - Parameters:
    - input: Input data value to visualise
  - Returns: HTMLDivElement

createShadowSelectors(): void
  - Description: Creates the $ and $$ fns that do css selections against the shadow dom
  - Returns: void

doInheritStyles(): Promise<void>
  - Description: Optionally apply an external linked style sheet (called from connectedCallback)
  - Parameters:
    - url: The URL for the linked style sheet
  - Returns: Promise<void>

ensureId(): void
  - Description: Ensure that the component instance has a unique ID & check again if uib loaded
  - Returns: void

newLog(type: string, args: string): void
  - Description: Creates a new HTML log entry
  - Parameters:
    - type: The log type
    - args: The arguments to log
  - Returns: void

prependStylesheet(cssText: string, order?: number): Element
  - Description: Attaches a new stylesheet before all other stylesheets in the light DOM
  - Parameters:
    - cssText: CSS text to inject directly
    - order: Optional order/priority for stylesheet placement. Lower numbers = higher priority (inserted first). Defaults to 0.
  - Returns: Element

redirectConsole(): void
  - Description: Capture console.xxxx and write to the div. NB: Cannot use bind here and so console output will have the wrong file/line number
  - Returns: void

uibSend(evtName: string, data: string): void
  - Description: Send a message to the Node-RED server via uibuilder if available. NB: These web components are NEVER dependent on Node-RED or uibuilder.
  - Parameters:
    - evtName: The event name to send
    - data: The data to send
  - Returns: void
```

--------------------------------

### Standard Package Release Workflow

Source: https://github.com/totallyinformation/web-components/blob/main/libs/RELEASE.md

A three-step process outlining the typical workflow for a standard package release. This involves updating the package version, committing the version change, and then executing the full release script.

```bash
# 1. Update version in package.json
npm version patch  # or minor, major

# 2. Commit the version change
git add package.json
git commit -m "chore: bump version to 1.1.1"

# 3. Run the release script
npm run release
```

--------------------------------

### JavaScript Integration of data-list with UIBUILDER

Source: https://github.com/totallyinformation/web-components/blob/main/docs/components/experiments/edgewise-meter.md

Demonstrates how to initialize `uibuilder`, import the `data-list` web component, and programmatically populate and update a `data-list` instance. It includes an example of handling `uibuilder` messages to dynamically modify list entries.

```javascript
/** Main app script
 * NOTES: 
 * - Any imports are relative to THIS script.
 */

// Load the uibuilder client library - to load here, you have to use the module version.
import '../uibuilder/vendor/@totallyinformation/web-components/libs/uibuilder.module.js'  // Does NOT LOAD any exports

// Load the component. The component self-registers & adds the `DataList` object to the `window` global.
import '../uibuilder/vendor/@totallyinformation/web-components/components/data-list.js'

// Start uibuilder
uibuilder.start()

// Get a reference to your data-list tag
const dl1 = $('#dl1')

/** Initialise the data-list using an Object.
 * Uses uibuilder's $ shortcut to reference.
 * When using an object, each `<li>` will have its id set to the key & the slot text to the value.
 * If you use an array, each `<li>` will get a numbered id.
 */
dl1.data = {
    "one": "This is the first list entry",
    "two": "This is the second list entry",
    "three": "This is the third list entry",
}

// Change one of the entries in the list from a uibuilder msg from Node-RED
uibuilder.onTopic('update dl1', function(msg) {
    console.log('>> onTopic `update dl1` >>', msg)

    dl1.entry(msg.entryRef, msg.payload)
})

/* Example msg
    {
        "topic": "update dl1",
        "entryRef": "two",
        "payload": "This is the second entry amended"
    }
*/
```

--------------------------------

### Basic Usage of smart-table Web Component

Source: https://github.com/totallyinformation/web-components/blob/main/docs/components/alpha/smart-table.md

Demonstrates how to embed the `smart-table` web component in HTML and populate it with data using JavaScript after the DOM content is loaded. The example shows setting an array of objects as table data.

```html
<smart-table id="st1"></smart-table>
```

```js
const arrObj = [
  {"COL1":"R1C1","COL2":"R1C2","COL3":"R1C3"},
  {"COL1":"R2C1","COL2":"R2C2","COL3":"R2C"},
  {"COL1":"R3C1","COL2":"R3C2","COL3":"R3C3"}
]
const st1 = document.getElementById('st1')
/** We need to wait for everything to be loaded before using components from JavaScript */
addEventListener("DOMContentLoaded", (event) => {
    st1.data = arrObj
})
```

--------------------------------

### Basic HTML Usage for data-list Web Component

Source: https://github.com/totallyinformation/web-components/blob/main/docs/components/live/data-list.md

Demonstrates various ways to instantiate the `data-list` web component in HTML, including overriding default styles, using object/array inputs via global variables, and setting list types.

```html
<data-list></data-list>

<!-- override bullet type -->
<data-list id="dl1" style="--list-style: disclosure-closed">
    Items added by JavaScript
</data-list>

<!-- Using object input, set to ol, override separator between key and value -->
<data-list id="dl2" listvar="mylist1" type="ol" keyvalueseparator=" - ">
    Items added by global object variable
</data-list>

<!-- Using array input, override list style (don't forget to wrap custom entries with quotes) -->
<data-list id="dl3" listvar="mylist2" liststyle="'➡️'">
    Items added by global array variable
</data-list>

<!-- Override decimal list with upper case roman numerals -->
<data-list type="ol" liststyle="upper-roman"></data-list>
```

--------------------------------

### hello-world Web Component Properties

Source: https://github.com/totallyinformation/web-components/blob/main/docs/readme/hello-world.md

Defines the configurable properties for the `hello-world` web component, including their corresponding HTML attributes and data types. These properties allow customization of the component's behavior and appearance.

```APIDOC
hello-world Component Properties:

- Property: `name`
  Attribute: `name`
  Type: `string | null`
  Description: The name property of the component, which can be a string or null.
```

--------------------------------

### HtmlInclude: Web Component Lifecycle Methods

Source: https://github.com/totallyinformation/web-components/blob/main/docs/jsdoc/html-include.js.html

Implements standard Web Component lifecycle callbacks: the `constructor` for initial setup, `connectedCallback` which runs when an instance is added to the DOM, and `disconnectedCallback` when an instance is removed from the DOM.

```javascript
/** NB: Attributes not available here - use connectedCallback to reference */
constructor() {
    super()
    // Only attach the shadow dom if code and style isolation is needed - comment out if shadow dom not required
    if (template && template.content) this._construct(template.content.cloneNode(true))
}

/** Runs when an instance is added to the DOM */
connectedCallback() {
    this._connect() // Keep at start.

    this._ready() // Keep at end. Let everyone know that a new instance of the component has been connected & is ready
}

/** Runs when an instance is removed from the DOM */
disconnectedCallback() {
    this._disconnect() // Keep at end.
}
```

--------------------------------

### html-include Web Component Methods

Source: https://github.com/totallyinformation/web-components/blob/main/docs/readme/html-include.md

Outlines the public methods available on the `html-include` web component for runtime configuration, content inclusion, style management, and communication with Node-RED via uibuilder.

```APIDOC
Methods:

config(config: object|undefined): object
  Description: OPTIONAL. Update runtime configuration, return complete config.
  Parameters:
    config: If present, partial or full set of options. If undefined, fn returns the current full option settings.

createShadowSelectors(): void
  Description: Creates the $ and $$ fns that do css selections against the shadow DOM.

doInclude(url: string | URL): Promise<void>
  Description: Replaces the shadow DOM content with the imported HTML.
  Parameters:
    url: URL of the resource to import.

doInheritStyles(): Promise<void>
  Description: Optionally apply an external linked style sheet (called from connectedCallback).
  Parameters:
    url: The URL for the linked style sheet.

ensureId(): void
  Description: Ensure that the component instance has a unique ID & check again if uib loaded.

prependStylesheet(cssText: string, order?: number): Element
  Description: Attaches a new stylesheet before all other stylesheets in the light DOM.
  Parameters:
    cssText: CSS text to inject directly.
    order: Optional order/priority for stylesheet placement. Lower numbers = higher priority (inserted first). Defaults to 0.

uibSend(evtName: string, data: string): void
  Description: Send a message to the Node-RED server via uibuilder if available. NB: These web components are NEVER dependent on Node-RED or uibuilder.
  Parameters:
    evtName: The event name to send.
    data: The data to send.
```

--------------------------------

### HTML Structure for data-list Web Component (With UIBUILDER)

Source: https://github.com/totallyinformation/web-components/blob/main/docs/components/experiments/edgewise-meter.md

Outlines the HTML setup for integrating `data-list` and `definition-list` web components within a UIBUILDER environment. It shows various ways to embed the components, including assigning IDs and names.

```html
<!doctype html>
<html lang="en"><head>

    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">

    <!-- Can load the web components here as type=module but you have to load everything in the right order.
         Alternatively, use an import in index.js -->
    <!-- <script type="module" async src="https://cdn.jsdelivr.net/gh/totallyinformation/web-components@main/components/button-send.js"></script> -->

    <script type="module" async src="./index.js"></script> 

</head><body>

<div>
    <!-- The simplest use. Apply the data in your index.js. Give it an ID to make it easier to reference. -->
    <definition-list id="dl1"></definition-list>

    <!-- If you give it a name, it will be used as its ID but with spaces replace with underscores. -->
    <data-list name="jims list">Jim's Simple List</data-list>

    <!-- If you don't give an ID or name, the component will apply an ID for you. -->
    <data-list>Simple List</data-list>
</div>

</body></html>
```

--------------------------------

### Run Web Component Generator in Interactive Mode

Source: https://github.com/totallyinformation/web-components/blob/main/libs/CREATE-COMPONENT.md

Executes the web component generator script in interactive mode, prompting the user for input to create a new component. This mode is suitable for guided component creation.

```bash
npm run new-component
```