@pixelscriptio/tessera/core

The signals runtime, the renderer and the component runtime. See Reactivity.

Child

type

Not documented yet.

export type Child<N, E extends N> = string | number | N | (() => string | number) | Mountable<N, E>

Component

type

Not documented yet.

export type Component = (input?: ComponentInput) => any

ComponentContext

interface

Not documented yet.

export interface ComponentContext {
  
  props<T extends Record<string, unknown> = Record<string, never>>(
    defaults?: T,
  ): { [K in keyof T]: ReadonlySignal<T[K]> } & Record<string, ReadonlySignal<any>>
  emit(name: string, detail?: unknown): void
  slot(name: string, fallback?: SlotContent): Mountable<any, any>
  
  root<T>(node: T, rootClass?: string): T
}

ComponentInput

interface

What a parent passes when it uses a component. Compiled templates build this.

export interface ComponentInput {
  
  props?: Record<string, ReadonlySignal<unknown>>
  
  events?: Record<string, (detail?: unknown) => void>
  slots?: Record<string, SlotContent>
}

constant

function

A read-only signal that never changes. Used for static component props.

function constant<T>(value: T): ReadonlySignal<T>

createDomAdapter

function

Not documented yet.

function createDomAdapter(doc?: Document): RendererAdapter<Node, Element>

createRenderer

function

Not documented yet.

function createRenderer<N, E extends N>(adapter: RendererAdapter<N, E>): Renderer<N, E>

createRoot

function

Run fn in a new, detached scope. Calling the disposer tears down everything created inside.

function createRoot<T>(fn: (dispose: () => void) => T): T

createStringAdapter

function

The renderer adapter for a tree of StringNodes. Properties that a browser would show as attributes (value, checked, selected) become attributes, so the HTML has what a page would have when it first loads.

function createStringAdapter(): RendererAdapter<StringNode, StringNode>

createStringNode

function

Not documented yet.

function createStringNode(tag: string): StringNode

defineComponent

function

Wrap a compiled setup function as a component. variants maps each contract variant to its default (the first allowed value). With an hmrId, re-evaluating the module swaps the implementation and re-renders live instances in place.

function defineComponent(name: string, variants: Record<string, string>, setup: Setup, hmrId?: string | undefined): Component

defineElement

function

Register a Tessera component as a custom element, so it can be used from any framework, or from plain HTML.

• Variants and props are attributes and properties. <t-button tone="danger" disabled>, and el.tone = 'danger'. A boolean is on when its attribute is present (and not "false"); a list or an object is set as a property (el.options = [...]), or as JSON in the attribute.
• Events are DOM events. What the component emits (press, toggle, ...) is dispatched on the element as a CustomEvent with the same name, with the payload in detail. It bubbles and crosses shadow roots. A native event of the same name from something inside the component (an input's own input event) is stopped at the component's root, so listeners on the element see the component's events and not both.
• Slots are children. Read when the element connects: children with slot="name" fill that slot, the rest fill the default slot. They are not watched afterward.
• It renders in the light DOM, so the page's tokens and the component's own styles apply, and display: contents keeps the element itself out of the layout.

Returns the element class. Registering a tag that exists already does nothing.

function defineElement(tag: string, component: Component, spec?: ElementSpec): CustomElementConstructor | undefined

derived

function

A lazy, memoized value computed from other signals. Must be pure.

function derived<T>(fn: () => T): ReadonlySignal<T>

effect

function

Run fn now and again whenever a signal it read changes. Effects created inside another effect or root are disposed with it. Returns a disposer.

function effect(fn: () => void): () => void

ElementOptions

interface

Not documented yet.

export interface ElementOptions {
  
  attrs?: Record<string, string | boolean | null | (() => string | boolean | null)>
  props?: Record<string, unknown | (() => unknown)>
  on?: Record<string, (event: any) => void>
  
  use?: Array<(el: any) => void | (() => void)>
  
  ns?: 'svg'
}

ElementSpec

interface

What a custom element needs to know about a component: the contract and the script's props, as plain data.

export interface ElementSpec {
  
  variants?: Array<{ name: string; values: readonly string[]; default: string }>
  
  props?: Array<{
    name: string
    type: 'boolean' | 'number' | 'string' | 'array' | 'object' | 'unknown'
    default?: unknown
  }>
  
  events?: readonly string[]
  
  slots?: readonly string[]
}

flush

function

Run all pending effects now instead of waiting for the microtask.

function flush(): void

getRenderer

function

Not documented yet.

function getRenderer(): Renderer<Node, Element>

isSignal

function

Not documented yet.

function isSignal(value: unknown): value is ReadonlySignal<unknown>

Mountable

interface

A dynamic child (a keyed list, a conditional, a slot) that manages its own nodes between two positions.

export interface Mountable<N, E extends N> {
  readonly [MOUNTABLE]: true
  mount(parent: E, anchor: N | null): void
}

onCleanup

function

Register cleanup to run before the current effect re-runs and when it is disposed.

function onCleanup(fn: () => void): void

onMount

function

Run fn once after the component has been created and attached, unless it was disposed first.

function onMount(fn: () => void): void

ReadonlySignal

interface

Not documented yet.

export interface ReadonlySignal<T> {
  readonly value: T
  
  peek(): T
}

Renderer

interface

Not documented yet.

export interface Renderer<N, E extends N> {
  readonly adapter: RendererAdapter<N, E>
  el(tag: string, options?: ElementOptions, ...children: Child<N, E>[]): E
  text(source: string | number | (() => string | number)): N
  each<T, K>(
    items: () => readonly T[],
    key: (item: T) => K,
    render: (item: ReadonlySignal<T>) => N,
  ): Mountable<N, E>
  
  cond(select: () => number, branches: Array<() => N>): Mountable<N, E>
  
  view(select: () => (() => N) | undefined, onRender?: (node: N) => void): Mountable<N, E>
  
  slot(content: SlotContent<N, E> | undefined, fallback?: SlotContent<N, E>): Mountable<N, E>
  
  mount(container: E, build: () => N): () => void
}

RendererAdapter

interface

The only surface through which the renderer touches a host tree. Anything above @tessera/core (tokens, contracts, behaviors) goes through this interface or through generated code, so the engine can be swapped later.

export interface RendererAdapter<N = unknown, E extends N = N> {
  
  createElement(tag: string, namespace?: 'svg'): E
  createText(text: string): N
  
  setAttribute(el: E, name: string, value: string | null): void
  setProperty(el: E, name: string, value: unknown): void
  getAttribute(el: E, name: string): string | null
  setText(node: N, text: string): void
  
  insert(parent: E, node: N, anchor: N | null): void
  
  move(parent: E, node: N, anchor: N | null): void
  remove(node: N): void
  nextSibling(node: N): N | null
  parentNode(node: N): E | null
  addListener(el: E, type: string, handler: (event: any) => void): void
  removeListener(el: E, type: string, handler: (event: any) => void): void
  
  observeAttribute?(el: E, name: string, callback: () => void): () => void
}

serializeChildren

function

The HTML of what is inside an element, which is what goes into the page's #app.

function serializeChildren(node: StringNode): string

serializeNode

function

The HTML text of a node: elements with their attributes, text escaped, void elements without a closing tag.

function serializeNode(node: StringNode): string

setRenderer

function

Choose the renderer that compiled components use. By default, the DOM.

function setRenderer(adapter: RendererAdapter<any, any>): void

Signal

interface

Not documented yet.

export interface Signal<T> extends ReadonlySignal<T> {
  value: T
}

SlotContent

type

Content a parent passes to a component slot. It runs when the slot is mounted.

export type SlotContent<N = any, E extends N = any> = () => Child<N, E>[]

state

function

A writable reactive value. Read and write with .value.

function state<T>(initial: T): Signal<T>

StringNode

interface

A tree of elements and text with no browser behind it, for rendering a page to HTML text: static prerendering, and tests that need no DOM. Listeners are accepted and ignored, so a component that attaches a behavior still renders.

export interface StringNode {
  readonly kind: 'element' | 'text'
  
  readonly tag?: string
  
  text?: string
  readonly attrs?: Map<string, string>
  readonly children?: StringNode[]
  parent: StringNode | null
}

untrack

function

Run fn without subscribing the current effect or derived value to what it reads.

function untrack<T>(fn: () => T): T

unwrap

function

The value of a signal, or the value itself when it is not one. Templates use this for bare names.

function unwrap<T>(value: T | ReadonlySignal<T>): T