A component framework.
npm install @substrate-system/tonic






Tonic is a low profile component framework for the web.
It's designed to be used with contemporary Javascript and is compatible
with all modern browsers. It's built on top of
Web Components.
Contents
- Install
- tl;dr
- Use
* Bundler
* Pre-bundled
- Get Started
* Register
* HTML
* Render
* Rerender
* Events
* State
- Server-Side Rendering
* SSR Example
* Async Components
* Hydration
- Docs
- API
* Event listeners
* tag
* emit
* static event
* dispatch
- Develop
* build ESM
* build Common JS
* build UMD modules
- Useful links
``sh`
npm i -S @substrate-system/tonic
This is a front-end view library, like React, but using web components.
> [!TIP]
> DOM state, such as element focus and input values, is preserved
> across multiple calls to reRender.
-------
`js`
import Tonic from '@substrate-system/tonic'
#### Copy
`sh`
cp ./node_modules/@substrate-system/tonic/dist/index.min.js ./public/tonic.min.js
#### HTML
`html`
-----------------------------------
Building a component with Tonic starts by creating a function or a
class.
The class should have at least one method named render which returns
a template literal
of HTML.
`js
import Tonic from '@substrate-system/tonic'
class MyGreeting extends Tonic {
render () {
return this.html
}
}
`or
`js
function MyGreeting () {
return this.html
}
`---
The HTML tag for your component will match the class or function name.
> [!NOTE]
> Tonic is a thin wrapper around
web components. Web
> components require a name with two or more parts. So your class name should
> be CamelCased (starting with an uppercase letter). For example, MyGreeting
> becomes .
>
---
$3
Next, register your component with
Tonic.add(ClassName).`js
Tonic.add(MyGreeting)
`---
$3
After adding your Javascript to your HTML, you can use your component anywhere.
`html
`>
> [!NOTE]
> Custom tags (in all browsers) require a closing tag even if
> they have no children. Tonic doesn't add any "magic" to change how this works.
>
---
$3
When the component is rendered by the browser, the result of your render
function will be inserted into the component tag.
`html
Hello, World.
`A component (or its render function) may be an
async or an async generator.`js
class GithubUrls extends Tonic {
async * render () {
yield this.htmlLoading...
const res = await fetch('https://api.github.com/')
const urls = await res.json()
return this.html
${JSON.stringify(urls, 2, 2)}
}
}
`$3
Call
tonicInstance.reRender() to render your component again with updated
state. This is totally decoupled from any kind of state machine, so you can
choose how to batch state updates, and just re-render when necessary.> [!TIP]
> DOM state, such as focus and input values, is preserved
> across multiple calls to
reRender.$3
There is a convention for event handler method names. Name a method like
handle_example, and the method will be called with any example type
event.#### Events Example
`js
import { Tonic } from '@substrate-system/tonic'class ButtonExample extends Tonic {
handle_click (ev) {
ev.preventDefault()
if (Tonic.match(ev.target as HTMLButtonElement, 'button')) {
// button clicks only
this.increment()
}
this.props.onbtnclick('hello')
}
render () {
return this.html
}
}
`$3
this.state is a plain-old javascript object. Its value will be persisted if
the component is re-rendered. Any component with state must have an
id property.Setting the state will not cause a component to re-render. This way you can
make incremental updates. Components can be updated independently, and
rendering only happens only when necessary.
Remember to clean up! States are just a set of key-value pairs on the Tonic
object. So if you create temporary components that use state,
clean up their state after you delete them. For example,
if I have a component with thousands of temporary child elements that
all use state, I should delete their state after they get destroyed.
Delete
Tonic._states[someRandomId]
Server-Side Rendering
Tonic includes a
renderToString function that converts component instances
to static HTML strings, making it easy to implement server-side rendering.The
renderToString function will process nested Tonic components recursively.$3
#### The Component
`js
// my-component.js
import Tonic from '@substrate-system/tonic'export class MyComponent extends Tonic {
render () {
return this.html
}
}
`#### Render
Need to import
Tonic after render, because it will polyfill some globals.`js
// this runs in node
import {
render as renderToString
} from '@substrate-system/tonic/render-to-string'
// Import Tonic after render-to-string
import { Tonic } from '@substrate-system/tonic'
import { MyComponent } from './my-component.js'// Create a component instance
const component = new MyComponent()
component.props = { name: 'World' }
// Render to HTML string
const html = await renderToString(component)
console.log(html)
// => '
Hello, World!'
`#### Nested Components
`js
class InnerComponent extends Tonic {
render () {
return this.html${this.props.text}
}
}class OuterComponent extends Tonic {
render () {
return this.html
}
}Tonic.add(InnerComponent)
Tonic.add(OuterComponent)
const component = new OuterComponent()
const html = await renderToString(component)
// Nested components are rendered correctly
`$3
The
renderToString function works with async component render methods:`js
class AsyncComponent extends Tonic {
async render () {
const data = await fetchData()
return this.html
}
}Tonic.add(AsyncComponent)
const component = new AsyncComponent()
const html = await renderToString(component)
// Waits for async render to complete
`$3
Add interactivity to server-rendered HTML without re-rendering.
The server attaches serialized state to the page,
and the client initializes components with that state.
#### Start a local example
`sh
npm run start:hydration
`#### Build the hydration example
`sh
npm run build:hydration
`#### Server
render returns the inner HTML of a component. toHtml
wraps that in the custom element tag (e.g.
), with props encoded as
attributes. Pass a state option to embed complex props
as JSON.`js
import {
render,
toHtml
} from '@substrate-system/tonic/render-to-string'class MyApp extends Tonic {
render () {
return this.html
- ${item}
}
}Tonic.add(MyApp)
const props = { title: 'Hello', items: ['a', 'b', 'c'] }
const app = new MyApp()
app.props = props
const content = await render(app)
// Wrap in component tag + embed state for hydration
const html = toHtml(app, content, {
id: 'app',
state: { app: props }
})
// html =>
//
// Hello
...
//
//
`Simple props (strings, numbers, booleans, null) are encoded
as HTML attributes automatically. Complex props (objects,
arrays) are transferred via the JSON