Symbiote.js

https://symbiotejs.org/
Admin
Symbiote.js is a JavaScript library for building web components and UIs. It offers features like...
Tokens:4,814
Snippets:41
Trust Score:5.8
Update:1 year ago
Show doc for...
Tokens:
Raw
### Define package.json scripts for Git submodules

Source: https://symbiotejs.org/2x/docs/Get_started

Example `package.json` scripts section demonstrating how to automate Git submodule operations. This includes updating, checking out specific versions, and integrating with `npm install` for a streamlined setup.

```JSON
{
  "scripts": {
    "git-modules": "git submodule update --init --recursive --remote",
    "sym-version": "cd symbiote && git checkout <VERSION_TAG> && cd ..",
    "setup": "npm run git-modules && npm run sym-version && npm i"
  }
}
```

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

### Run setup script for Git submodules

Source: https://symbiotejs.org/2x/docs/Get_started

Command to execute the combined setup script defined in `package.json`. This script handles both Git submodule updates and NPM installations, simplifying the project setup process.

```Shell
npm run setup
```

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

### Install Symbiote.js via NPM

Source: https://symbiotejs.org/2x/docs/Get_started

Standard NPM installation command for adding Symbiote.js as a production dependency to your project.

```Shell
npm i @symbiotejs/symbiote
```

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

### Checkout a specific Git submodule revision

Source: https://symbiotejs.org/2x/docs/Get_started

Commands to navigate into the submodule directory and checkout a particular version tag. This is useful for managing specific dependency versions within a Git submodule setup.

```Shell
cd symbiote && git checkout <VERSION_TAG>
```

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

### Install Symbiote.js as a dev dependency via NPM

Source: https://symbiotejs.org/2x/docs/Get_started

Installs Symbiote.js as a development dependency. This is useful when using a CDN for runtime but requiring static analysis support (e.g., TypeScript) during development.

```Shell
npm install @symbiotejs/symbiote --save-dev
```

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

### Add TypeScript declarations for CDN imports

Source: https://symbiotejs.org/2x/docs/Get_started

Provides a TypeScript declaration file example to map CDN URLs to local modules. This ensures proper type checking and 'Go to Definition' support for packages imported directly from a CDN.

```TypeScript
// List out all your dependencies.
// For every URL, you must map it to its local module:

declare module 'https://esm.run/@symbiotejs/symbiote' {
  export * from '@symbiotejs/symbiote';
}
```

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

### Update Git submodules

Source: https://symbiotejs.org/2x/docs/Get_started

Command to update and initialize Git submodules. This ensures all submodules are at their correct revisions and ready for use after cloning or pulling the main repository.

```Shell
git submodule update --init --recursive --remote
```

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

### Install Symbiote.js with NPM

Source: https://symbiotejs.org/1x/docs/Installation

This command installs the Symbiote.js library and its dependencies using the Node Package Manager (NPM), which is the recommended method for most projects.

```Shell
npm i @symbiotejs/symbiote
```

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

### Add Symbiote.js as a Git submodule

Source: https://symbiotejs.org/2x/docs/Get_started

Command to initialize Symbiote.js as a Git submodule. This allows its repository to be included directly within another project, managing it as a nested dependency.

```Shell
git submodule add -b main https://github.com/symbiotejs/symbiote.js.git ./symbiote
```

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

### Define package.json Scripts for Git Submodule Management

Source: https://symbiotejs.org/1x/docs/Installation

This JSON snippet shows a `package.json` 'scripts' section with commands to manage Git submodules. It includes scripts for updating submodules, checking out specific Symbiote.js versions, and a combined setup script to automate the process.

```JSON
{
  "scripts": {
    "git-modules": "git submodule update --init --recursive --remote",
    "sym-version": "cd symbiote && git checkout <VERSION_TAG> && cd ..",
    "setup": "npm run git-modules && npm run sym-version && npm i"
  }
}

```

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

### Create a basic Symbiote.js component

Source: https://symbiotejs.org/2x/docs/Get_started

A complete HTML file demonstrating how to define and register a simple Symbiote.js component. It includes import maps, state initialization, template definition, and styling, highlighting the ability to run Symbiote.js directly in a browser without a build step.

```HTML
<script type="importmap">
  {
    "imports": {
      "@symbiotejs/symbiote": "https://esm.run/@symbiotejs/symbiote"
    }
  }
</script>

<script type="module">
  import Symbiote, { html, css } from '@symbiotejs/symbiote';

  export class MyComponent extends Symbiote {

    // Initiate state:
    init$ = {
      count: 0,
      increment: () => {
        this.$.count++;
      },
    }

  }

  // Define template:
  MyComponent.template = html`
    <h2>{{count}}</h2>
    <button ${{onclick: 'increment'}}>Click me!</button>
  `;

  // Describe styles:
  MyComponent.rootStyles = css`
    my-component {
      color: #f00;
    }
  `;

  // Register the new HTML-tag in browser:
  MyComponent.reg('my-component');
</script>

<my-component></my-component>
```

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

### Define a base component class with CDN import

Source: https://symbiotejs.org/2x/docs/Get_started

Illustrates how to create a common base class for an application, extending `Symbiote` and importing it via CDN. This centralizes dependency management and provides an endpoint for app-level extensions.

```JavaScript
import { Symbiote } from 'https://esm.run/@symbiotejs/symbiote';

export class AppComponent extends Symbiote {
  // Your code...
}
```

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

### Quick Start with Symbiote.js Component

Source: https://symbiotejs.org/1x

This HTML snippet provides a quick start example for Symbiote.js. It demonstrates how to define a custom web component, `my-component`, directly within an HTML file using ES modules. The component extends `Symbiote`, manages a `count` state, and includes a method to increment it. The template uses `html` tagged template literals for rendering, showcasing declarative UI and event binding. This setup allows for direct execution in modern browsers without a build step.

```HTML
<script type="module">
  import Symbiote, { html } from 'https://symbiotejs.github.io/symbiote.js/core/Symbiote.js';

  class MyComponent extends Symbiote {
    init$ = {
      count: 0,
      increment: () => {
        this.$.count++;
      },
    }
  }

  MyComponent.template = html`
    <h2>{{count}}</h2>
    <button ${{onclick: 'increment'}}>Click me!</button>
  `;

  MyComponent.reg('my-component');
</script>

<my-component></my-component>
```

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

### Configure tsconfig.json for CDN imports

Source: https://symbiotejs.org/2x/docs/Get_started

Shows a necessary `compilerOptions` configuration in `tsconfig.json` to handle deep module paths. This setting is often required when using CDN imports with TypeScript to prevent resolution issues.

```JSON
{
  "compilerOptions": {
    "allowJs": true,
    "maxNodeModuleJsDepth": 2
  }
}
```

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

### Update Git Submodules

Source: https://symbiotejs.org/1x/docs/Installation

This command initializes, updates, and recursively fetches the latest changes for all Git submodules in the repository. It ensures all submodules are at their specified revisions.

```Shell
git submodule update --init --recursive --remote
```

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

### Import Symbiote.js via HTTPS/CDN

Source: https://symbiotejs.org/2x/docs/Get_started

Demonstrates how to import Symbiote.js directly from a CDN using an HTTPS URL. This approach facilitates sharing Symbiote.js as a common dependency across independent application parts like micro-frontends.

```JavaScript
import { Symbiote } from 'https://esm.run/@symbiotejs/symbiote';
```

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

### Add Symbiote.js as Git Submodule

Source: https://symbiotejs.org/1x/docs/Installation

This Git command adds the Symbiote.js repository as a submodule to the current project. It specifies the 'main' branch and the local path where the submodule will be cloned.

```Shell
git submodule add -b main https://github.com/symbiotejs/symbiote.js.git ./symbiote
```

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

### Import Symbiote.js via CDN

Source: https://symbiotejs.org/1x/docs/Installation

This JavaScript snippet demonstrates how to import the BaseComponent from Symbiote.js directly from a Content Delivery Network (CDN). This method is suitable for browser environments that do not use a build step.

```JavaScript
import { BaseComponent } = 'https://esm.sh/@symbiotejs/symbiote/';

```

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

### Checkout Specific Symbiote.js Submodule Revision

Source: https://symbiotejs.org/1x/docs/Installation

These commands navigate into the Symbiote.js submodule directory and check out a specific version tag. This allows for precise version control of the submodule within the parent repository.

```Shell
cd symbiote && git checkout <VERSION_TAG>
```

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

### Initialize Symbiote.js Component Properties from Template

Source: https://symbiotejs.org/index

This example demonstrates how the `allowTemplateInits` flag in Symbiote.js enables direct property initialization from component templates. Properties defined in the template become available in the `initCallback` method, allowing for immediate manipulation or access.

```JavaScript
class MyComponent extends Symbiote {

  initCallback() {
    // Property is already exists:
    this.$.myProp = 'new value';
  }

}

MyComponent.template = html`
  <h1>{{myProp}}</h1>
`;

```

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

### Configure TypeScript for CDN Imports

Source: https://symbiotejs.org/1x/docs/Installation

This TypeScript declaration file (`my-types.d.ts`) allows TypeScript to recognize and correctly type modules imported from HTTPS URLs, specifically for Symbiote.js via CDN. It suppresses TS errors for external modules and maps the CDN URL to its local module definition.

```TypeScript
// First, let TypeScript allow all module names starting with "https://". This will suppress TS errors.
declare module 'https://*';

// Second, list out all your dependencies. For every URL, you must map it to its local module.
declare module 'https://esm.sh/@symbiotejs/symbiote/' {
  export * from '@symbiotejs/symbiote';
}

```

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

### ESM Network Import for Symbiote.js Components

Source: https://symbiotejs.org/index

This JavaScript example showcases the use of ECMAScript Modules (ESM) with network imports to easily share and reuse Symbiote.js components and utilities. It imports `Symbiote`, `html`, and `css` from a CDN, and then exports a custom component and the utilities for broader application use, simplifying dependency management.

```JavaScript
import { Symbiote, html, css } from 'https://esm.run/@symbiotejs/symbiote';

export class MyAppComponent extends Symbiote {}

export { html, css }
```

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

### Highlight HTML and CSS in JavaScript Template Literals

Source: https://symbiotejs.org/index

This example illustrates a common practice in Symbiote.js development for enhancing IDE syntax highlighting. It uses `html` and `css` tag functions with JavaScript template literals to correctly identify and format embedded HTML and CSS code.

```JavaScript
let template = html`<div>MY_TEMPLATE</div>`;

let styles = css`
  div {
    color: #f00;
  }
`;

```

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

### Basic Symbiote.js Component Definition

Source: https://symbiotejs.org/pulse/1

This JavaScript code demonstrates a basic Symbiote.js component. It initializes component state with a `count` property and an `increment` method, defines the component's HTML template using `html` tagged literal, applies root-level CSS styles with `css` tagged literal, and registers the custom element `my-component`.

```javascript
import Symbiote, { html, css } from 'https://esm.run/@symbiotejs/symbiote';

export class MyComponent extends Symbiote {

  init$ = {
    count: 0,
    increment: () => {
      this.$.count++;
    },
  }

}

MyComponent.template = html`
  <h2>{{count}}</h2>
  <button ${{onclick: 'increment'}}>Click me!</button>
`;

MyComponent.rootStyles = css`
  my-component {
    color: green;
  }
`;

MyComponent.reg('my-component');
```

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

### Initiating Component Data from CSS Custom Properties in Symbiote.js

Source: https://symbiotejs.org/index

Symbiote.js enables initiating component data with values defined as CSS Custom Properties using the `--` token. This feature facilitates providing configurations for components directly through CSS, enhancing flexibility and separation of concerns.

```javascript
class TestApp extends Symbiote {}

TestApp.rootStyles = css`
  test-app {
    --header: 'CSS Data';
    --text: 'Hello!';
  }
`;
```

```javascript
TestApp.template = html`
  <h1>{{--header}}</h1>
  <div>{{--text}}</div>
`;
```

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

### Applying Styles with Symbiote.js using adoptedStyleSheets

Source: https://symbiotejs.org/index

Symbiote.js 2.3.x leverages `adoptedStyleSheets` for flexible web component styling. It allows defining `rootStyles` for higher-level CSS roots (document or shadow) and `shadowStyles` for component's Shadow DOM, enabling direct CSS definitions in JavaScript without CSP conflicts.

```javascript
import { css } from '@symbiotejs/symbiote';

// External component styles are set in higher level CSS root (document or shadow):
MyComponent.rootStyles = css`
  my-component {
    border: 1px solid currentColor;
  }
`;

// Styles for component's Shadow DOM (optional):
MyComponent.shadowStyles = css`
  :host {
    display: block;
    padding: 10px;
    color: #f00;
  }
`;
```

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

### Symbiote.js High-Performance List Rendering with Web Components

Source: https://symbiotejs.org/index

Demonstrates how to achieve highly performant dynamic list rendering in Symbiote.js by integrating lightweight native web components (e.g., TableRow) for individual list items. This approach is ideal for large datasets like dynamic tables, optimizing rendering by directly manipulating DOM elements within custom elements.

```JavaScript
// Create lightweight web-component for each table row:
class TableRow extends HTMLElement {

  set rowData(data) {
    data.forEach((cellContent, idx) => {
      if (!this.children[idx]) {
        this.appendChild(document.createElement('td'));
      }
      this.children[idx].textContent = cellContent;
    });
  }

}

window.customElements.define('table-row', TableRow);
```

```JavaScript
// Than render big dynamic table with Symbiote:
class MyTable extends Symbiote {

  init$ = {
    tableData: [],
  }

  initCallback() {
    window.setInterval(() => {
      let data = [];
      for (let i = 0; i < 10000; i++) {
        let rowData = [
          i + 1,
          Date.now(),
        ];

        data.push({rowData});
      }
      this.$.tableData = data;

    }, 1000);
  }

}

MyTable.reg('my-table');
```

```CSS
MyTable.rootStyles = css`
  table-row {
    display: table-row;
  }
  td {
    border: 1px solid currentColor;
  }
`;
```

```HTML
MyTable.template = html`
  <h1>Hello table!</h1>
  <table ${{itemize: 'tableData', 'item-tag': 'table-row'}}></table>
`;
```

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

### Symbiote.js Server-Side Rendering (SSR) Activation

Source: https://symbiotejs.org/index

Demonstrates the straightforward way to enable Server-Side Rendering (SSR) for Symbiote.js components. By simply setting the `ssrMode` property to `true` within a component, it becomes compatible with server-side markup generation.

```JavaScript
import Symbiote from '@symbiotejs/symbiote';

class MyComponent extends Symbiote {
  ssrMode = true;
}
```

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

### Symbiote.js Binding Syntax Update: Removal of Alternative Syntax

Source: https://symbiotejs.org/index

Highlights the removal of the less intuitive alternative binding syntax (`set -onclick`) in Symbiote.js. Developers should now exclusively use the more explicit object-based binding syntax (`{{onclick: 'onButtonClicked'}}`) for event handling and property binding.

```HTML
<button set -onclick="onButtonClicked"></button>
```

```HTML
<button ${{onclick: 'onButtonClicked'}}></button>
```

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

### Constructing HTML Templates with Symbiote.js html Tag

Source: https://symbiotejs.org/index

Symbiote.js introduces an `html` tag function for constructing HTML templates using JavaScript. This allows for native JavaScript string interpolation and mapping element attributes/properties to data models, simplifying dynamic content generation.

```javascript
import { html } from '@symbiotejs/symbiote';

let mySymbioteTemplate = html`<div>Hello world!</div>`;
```

```html
<h1>{{heading}}</h1>

<button ${{onclick: 'onButtonClicked'}}>Click me!</button>

<my-component ${{
  textContent: 'someText',
  'style.border': 'myComponentBorder',
  '$.data': 'someData',
}}></my-component>

<ul ${{list: 'myListData'}}>
  <li>{{listItemName}}</li>
</ul>
```

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

### Creating Virtual Components in Symbiote.js

Source: https://symbiotejs.org/index

Symbiote.js allows defining 'virtual' components by setting `isVirtual = true`. When enabled, the component renders directly as part of the DOM without a wrapping Custom Element, using its custom tag purely as a placeholder that is removed during rendering.

```javascript
class MyComponent extends Symbiote {

  isVirtual = true;

}
```

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

### Symbiote.js Attribute-to-Property Binding with `@` Token

Source: https://symbiotejs.org/index

Introduces the new `@` token in Symbiote.js for direct attribute-to-property binding. This allows initializing state properties from attributes or directly referencing attribute values within templates, simplifying data flow.

```JavaScript
class MyComponent extends Symbiote {
  init$ = {
    '@my-attribute': 'some initial value...',
  }
}
```

```HTML
// or use the direct template initiation:
class MyOtherComponent extends Symbiote {}

MyOtherComponent.template = html`
  <h1>{{@my-attribute}}</h2>
`;
```

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

### Binding to Upper-Level Component Properties in Symbiote.js

Source: https://symbiotejs.org/index

Symbiote.js introduces the `^` property token to bind handlers and properties directly to an upper component's state. This simplifies complex interaction cases by allowing cascade data models, automatically finding the first ancestor component where the specified property is defined.

```javascript
MyComponent.template = html`
  <button ${{onclick: '^upperLevelClickHandler'}}>Click me!</button>
`;
```

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

### Embed Symbiote.js File Uploader with Image Editor

Source: https://symbiotejs.org/index

This HTML snippet demonstrates how to integrate a Symbiote.js-powered file uploader component, which includes an built-in image editor. The `css-src` attribute links to the component's specific stylesheet for proper rendering.

```HTML
<lr-file-uploader-regular css-src="./2x/css/uploader/index.css"></lr-file-uploader-regular>

```

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

### Symbiote.js Manual Light DOM Slot Processor Integration

Source: https://symbiotejs.org/index

Shows how to manually enable Light DOM slot support in Symbiote.js components. Since default processing is removed, developers must import and add `slotProcessor` to their component's template processors when using slots without Shadow DOM.

```JavaScript
import Symbiote from '@symbiotejs/symbiote';
import { slotProcessor } from '@symbiotejs/symbiote/core/slotProcessor.js';

class MyComponent extends Symbiote {
  constructor() {
    super();
    this.addTemplateProcessor(slotProcessor);
  }
}
```

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

### Embed Symbiote.js Photo-360 Player

Source: https://symbiotejs.org/index

This HTML snippet shows how to embed a Symbiote.js-based Photo-360 player component into a web page. The `data` attribute is used to specify the URL of the JSON data required by the player.

```HTML
<ims-photo-spinner data="DATA_JSON_URL"></ims-photo-spinner>

```

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

### JSDoc Annotation for Function Parameters

Source: https://symbiotejs.org/index

This JavaScript code snippet demonstrates how to use JSDoc comments to define the types of function parameters. It specifies 'a' as Boolean, 'b' as Number, and 'c' as String, which aids in static analysis and type checking, especially when integrating with TypeScript.

```JavaScript
/**
 * @param {Boolean} a
 * @param {Number} b
 * @param {String} c
 */

function myFunction(a, b, c) {
  ...
}
```

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

### Symbiote.js HTML Attribute Rename: `set` to `bind`

Source: https://symbiotejs.org/index

Illustrates the change in Symbiote.js from the `set` attribute to the new `bind` attribute for direct data binding within raw HTML templates. This update standardizes attribute-based data manipulation.

```HTML
<div set="textContent: textVariableName"></div>
```

```HTML
<div bind="textContent: textVariableName"></div>
```

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

### Defining Computed Properties in Symbiote.js Components

Source: https://symbiotejs.org/index

Symbiote.js 2.x allows defining computed properties using the `+` prefix, which are automatically recalculated when any of their dependent local properties change. The calculation flow is optimized to only invoke after all synchronous changes are complete.

```javascript
class MyComponent extends Symbiote {

  init$ = {
    a: 1,
    b: 1,
    '+sum': () => this.$.a + this.$.b;
  }

}
```

```javascript
MyComponent.template = html`<div>{{+sum}}</div>`;
```

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

### Symbiote.js List Iteration Attribute Rename: `repeat` to `itemize`

Source: https://symbiotejs.org/index

Explains the renaming of the list iteration attribute from `repeat` to `itemize` in Symbiote.js. This update affects how dynamic lists are rendered, introducing a clearer semantic for item iteration and supporting the new object-based binding syntax.

```HTML
<ul repeat="data" repeat-item-tag="list-item"></ul>
```

```HTML
<ul itemize="data" item-tag="list-item"></ul>
or
<ul ${{itemize: 'data', 'item-tag': 'list-item'}}></ul>
```

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

### Symbiote.js Context Attribute Rename: `ctx-name` to `ctx`

Source: https://symbiotejs.org/index

Details the simplification of the context attribute in Symbiote.js, where `ctx-name` has been renamed to the more concise `ctx`. This applies to both direct attribute usage and CSS variable-based context linking.

```HTML
<my-component ctx-name="my_data_ctx"></my-component>
or
<my-component style="--ctx-name: 'my_data_ctx'"></my-component>
```

```HTML
<my-component ctx="my_data_ctx"></my-component>
or
<my-component style="--ctx: 'my_data_ctx'"></my-component>
```
Tokens:
Raw