@tempots/dom

BrowserContext

DOMContext is an immutable class that represents the context of a DOM element. It provides methods and properties to manipulate and interact with the DOM element.

A reference in a DOMContext is to mark a position within a set of sibblings. It is used to insert new elements before the reference.

Computed

Represents a computed signal that derives its value from a function. It extends the Signal class.

ElementPosition

Represents the position of an element in a collection.

HeadlessAdapter

Represents an adapter for headless rendering environments. This class provides methods to interact with elements in a headless context.

This class is used to adapt the HeadlesContext to whatever you want to use to render your final HTML. You can use libraries like cheerio to render your HTML.

For cheerio an adapter could look like this:

const renderWithCheerio = (html: string, root: HeadlessPortal) => {
  const $ = cheerio.load(html)

  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  const adapter = new HeadlessAdapter<cheerio.Cheerio<any>>({
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    select: (selector: string): cheerio.Cheerio<any>[] => [$(selector)],
    getAttribute: (el, name: string) => el.attr(name) ?? null,
    setAttribute: (el, name: string, value: string | null) => {
      if (value === null) {
        el.removeAttr(name)
      } else {
        el.attr(name, value)
      }
    },
    getClass: el => el.attr('class') ?? '',
    setClass: (el, value: string | null) => {
      if (value === null) {
        el.removeAttr('class')
      } else {
        el.attr('class', value)
      }
    },
    getStyles: el => el.attr('style') ?? {},
    setStyles: (el, value: Record<string, string>) => {
      if (Object.keys(value).length === 0) {
        el.removeAttr('style')
      } else {
        el.css(value)
      }
    },
    appendHTML: (el, html) => el.append(html),
    getInnerHTML: el => el.html() ?? '',
    setInnerHTML: (el, html) => el.html(html),
    getInnerText: el => el.text() ?? '',
    setInnerText: (el, text) => el.text(text),
  })

  adapter.setFromRoot(root, true)

  return $.html()
}

This function will return the rendered HTML as a string.

HeadlessContext

HeadlessElement

HeadlessPortal

HeadlessText

MemoryStore

Represents a memory store that stores key-value pairs.

Prop

Represents a property signal that holds a value of type T. It extends the Signal class.

ProviderNotFoundError

Error thrown when a provider is not found.

RenderingError

Represents an error that occurs during rendering.

Signal

Represents a signal that holds a value and notifies its listeners when the value changes.

animateSignal(signal, options)

Animates a signal by creating a new signal that transitions from an initial value to the current value of the input signal.

animateSignals(initialValue, fn, dependencies, options)

Animates signals based on the provided options.

Async(promise, options)

Creates a renderable asynchronous task that wraps a promise.

BindChecked(prop)

Binds a boolean property to the checked value of an input element. The binding is two-way.

BindDate(prop, handler)

Binds a Date property to an input element. The binding is two-way. Changes to the input element will update the property but will only be affected by day changes and ignore time changes.

BindDateTime(prop, handler)

Binds a Date property to an input element. The binding is two-way.

BindNumber(prop, handler)

Binds a number property to an input element. The binding is two-way.

BindText(prop, handler)

Binds a string property to an input element. The binding is two-way.

Conjunction(separator, options)

Creates a Renderable that returns the appropriate separator based on the element position.

DOMNode(node)

Creates a renderable DOM node.

El(tagName, children)

Creates a Renderable that represents an HTML element.

ElNS(tagName, namespace, children)

Creates a renderable function that represents an element in the DOM with a specified namespace.

emitChecked(fn)

Calls the provided function with the checked value of the event target.

emitPreventDefault(fn)

Wraps a function to prevent the default behavior of an event before invoking it.

emitStopImmediatePropagation(fn)

Creates an event handler that stops immediate propagation of the event and invokes the provided function.

emitStopPropagation(fn)

Creates a new event handler that stops event propagation and invokes the provided function.

emitValue(fn)

Creates an event handler that emits the value of an HTMLInputElement.

emitValueAsDate(fn)

Converts the value of an HTML input element to a Date object and emits it using the provided callback function.

emitValueAsDateTime(fn)

Emits the value of an HTMLInputElement as a Date object.

emitValueAsNumber(fn)

Calls the provided function with the value of an HTMLInputElement as a number.

endInterpolate(_start, end)

A fake interpolate function that always returns the end value.

Ensure(value, then, otherwise)

Represents a function that ensures a signal has a value before rendering a TNode.

EnsureAll(signals)

Ensures that all signals have a value before rendering a TNode.

ForEach(value, item, separator)

Renders a list of items based on a signal of arrays.

Fragment(children)

Creates a fragment renderable that represents a collection of child renderables.

The Fragment itself does not render any DOM elements. Instead, it renders the child renderables in the given DOM context.

It can be used any time a single Renderable/TNode is expected, but multiple renderables are needed.

getWindow()

guessInterpolate(value)

Returns an interpolation function based on the type of the value.

localStorageProp(options)

Creates a prop that is backed by the localStorage or a MemoryStore.

makeComputed(fn, dependencies, equals)

Creates a computed signal that depends on other signals and updates when any of the dependencies change.

makeComputedOf(args)

Creates a computed signal that depends on other signals or literal values and updates when any of the dependencies change.

makeComputedRecord(record, fn)

Computes a value based on a record of signals and literals.

makeEffect(fn, signals, options)

Executes the provided function fn whenever any of the signals in the signals array change. Returns a disposable object that can be used to stop the effect.

makeEffectOf(args)

Creates an effect that depends on other signals or literal values and updates when any of the dependencies change.

makeProp(value, equals)

Creates a new Prop object with the specified value and equality function.

makeProviderMark(identifier)

Creates a unique symbol that can be used as a provider mark for a specific type T. The provider mark is used to identify the provider of a value of type T in a dependency injection system.

makeSignal(value, equals)

Creates a signal with the specified initial value and equality function.

MapSignal(value, fn)

Maps the values emitted by a signal to a renderable function and returns a new renderable function.

While it is tempting to use MapSignal for its simplicity, it is important to remember that the renderable function returned by MapSignal will be re-rendered every time the signal emits a new value.

In other contexts link Ensure or OneOf, the renderable function is only re-rendered when the signal changes to a state that requires a different renderable function.

NotEmpty(value, display, whenEmpty)

Returns a renderable component that displays the given display component when the signal contains a non-empty array, and the whenEmpty component otherwise.

OnBrowserCtx(fn)

Returns a renderable function that executes the given function with the current DOMContext as argument. The given function can return a TNode or void. If you need to perform some actions when the Renderable is disposed, you can use OnDispose as the return value.

OnChecked(fn)

(ALPHA) Attaches an event handler to the 'click' event that triggers when a checkbox is checked or unchecked.

OnCtx(fn)

Returns a renderable function that executes the given function with the current DOMContext as argument. The given function can return a TNode or void. If you need to perform some actions when the Renderable is disposed, you can use OnDispose as the return value.

OnDispose(fns)

Creates a renderable function that will be called when the component is unmounted.

OnElement(fn)

Executes a callback function when the parent element is mounted in the DOM. The given function can return a TNode or void. Any returned TNode will be appended to the element argument. If you need to perform some actions when the Renderable is disposed, you can use OnDispose as the return value.

OneOf(match, cases)

Creates a renderable function that renders different components based on the value of a signal.

The signal value should be an object with a single key that matches one of the keys in the cases object.

OneOfField(match, field, cases)

Creates a renderable that renders different components based on the value of the specified field.

OneOfKind(match, cases)

Creates a renderable field that matches the value of the kind property in the provided match signal.

It uses the cases object to determine the appropriate field to render based on the value of kind.

OneOfTuple(match, cases)

Creates a tuple-based one-of component that matches a signal value with a set of cases.

The signal value should be a tuple with the first element being the key to match against.

OneOfType(match, cases)

Creates a field that renders one of the provided cases based on the value of the type property.

It uses the cases object to determine the appropriate field to render based on the value of type.

OneOfValue(match, cases)

Creates a renderable value that represents one of the provided cases based on the given match signal.

The match signal should emit a value that matches one of the keys in the cases object.

OnHeadlessCtx(fn)

Returns a renderable function that executes the given function with the current DOMContext as argument.

Portal(selector, node)

Renders the given node into a DOM element selected by the provided selector. Throws an error if the element cannot be found.

Provide(providerFns)

Higher-order function that composes multiple provider functions into a single provider function.

ProvideGlobalProbe({ callback, timeout, }, child)

Provides a global probe, which can be used to trigger a callback when all probes with the same identifier are resolved. To resolve a probe, call the done function passed using the UseProbe renderable.

ProvideProbe({ identifier, callback, child, timeout, })

Provides a child component with a probe, which can be used to trigger a callback when all probes with the same identifier are resolved. To resolve a probe, call the done function passed using the UseProbe renderable.

render(node, parent, { doc, clear, disposeWithParent })

Renders a Renderable node into a specified parent element or selector.

renderableOfTNode(child)

Converts a TNode into a Renderable.

renderWithContext(renderable, ctx)

Renders the given renderable with the provided ctx DOM context.

Repeat(times, element, separator)

Creates a renderable function that repeats a given element a specified number of times.

restoreTempoPlaceholders()

Restores all placeholders in the DOM. This function is useful when the HTML is rendered on the server and then hydrated on the client. It restores the original content that was replaced with placeholders during the initial render. When you render on the server side, make sure to call HeadlessAdapter.setFromRoot with the result of runHeadless and the second parameter setPlaceholders to true.

runHeadless(makeRenderable, { startUrl, selector, })

Runs a renderable function in a headless environment.

sessionStorageProp(options)

Creates a prop that stores its value in the session storage.

storedProp({ key, defaultValue, store, serialize, deserialize, equals, onLoad, })

Creates a stored property that persists its value in a storage mechanism.

Task(task, options)

Represents a renderable task that can be executed asynchronously.

TextNode(value)

Creates a renderable text node.

Unless(condition, then, otherwise)

Lazily renders content when a condition is false.

Use(providers, fn)

Creates a renderable function that consumes data from multiple consumers and renders the result.

UseGlobalProbe(fn)

Uses a global probe, which can be used to trigger a callback when all probes with the same identifier are resolved. To resolve a probe, call the done function.

UseProbe(identifier, fn)

Uses a probe, which can be used to trigger a callback when all probes with the same identifier are resolved. To resolve a probe, call the done function.

UseProvider(mark, fn)

Creates a renderable function that consumes a provider value and renders a TNode.

UseProviders(marks, fn)

Creates a renderable function that consumes providers and renders a TNode.

When(condition, then, otherwise)

Lazily renders content based on a boolean condition.

WithProvider(mark, value, child)

Creates a renderable with a provider mark and value.

The value will be available to any consumers that request the provider mark.

WithProviders(providers, child)

Renders the given child with the specified providers.

DOMContext

DOMContext is an immutable class that represents the context of a DOM element. It provides methods and properties to manipulate and interact with the DOM element.

A reference in a DOMContext is to mark a position within a set of sibblings. It is used to insert new elements before the reference.

HeadlessContainer

aria

An object that provides a convenient way to create mountable attributes for ARIA properties.

The type of the value is inferred from the attribute name.

attr

The attr object allows to create any HTML attribute. Either a literal value or Signal<?> can be passed as a value. The type of the value is inferred from the attribute name.

CLASS_PLACEHOLDER_ATTR

dataAttr

The data object allows to create any data- attributes. Either a literal value or Signal<string> can be passed as a value.

Empty

Represents an empty renderable function.

html

A convenience object to create Renderables for HTML elements.

input

A convenience object to create Renderables for HTMLInput elements.

It automatically creates an attribute with the specified type

interpolateDate

Interpolates between two dates based on a delta value.

interpolateNumber

Interpolates a number between a start and end value based on a delta.

interpolateString

Interpolates between two strings based on a delta value.

math

A convenience object to create Renderables for MATH elements.

mathAttr

An object that provides attribute functions for MathML tags.

on

Represents a collection of HTML event handlers that can be attached to an element.

probeMarker

A provider mark for a signal representing the current appearance type.

style

A collection of functions to create style renderables.

svg

A convenience object to create Renderables for SVG elements.

svgAttr

An object that provides a convenient way to create mountable attributes for SVG elements.

Value

AnimateSignal

Represents the configuration options for animating a signal.

AnimateSignalsOptions

Options for animating signals.

AnySignal

Represents any type of signal. It can be a Signal, Prop, or Computed.

AriaAttributes

Represents a collection of ARIA attributes and their corresponding types.

AsyncOptions

Options for the Async component.

AtGetter

Represents a type that maps each property of T to a Signal of its corresponding type.

Clear

Represents a function that clears a resource.

ConjunctionOptions

Options for configuring a conjunction.

Consumer

Represents a consumer function that takes a callback function and returns a renderable object. The callback function takes a value of type T and returns a TNode.

CSSStyles

Represents a subset of CSS styles. It is a type that excludes certain properties from the CSSStyleDeclaration type.

DisposeCallback

ExcludeFromStyle

Represents a set of properties or values that are excluded from the CSSStyleDeclaration interface.

GetValueType

Gets the value type of a given Value type. If the type is a Signal, it returns the inferred value type. Otherwise, it returns the type itself.

GetValueTypes

Gets the value types of a given array of Value types.

HandlerOptions

Options for event listeners.

HeadlessNode

HTMLAttributes

Represents the HTML attributes that can be used in an HTML element.

HTMLEvents

Represents a mapping of HTML event names to their corresponding event types.

HTMLTags

Represents a mapping of HTML tag names to their corresponding element types.

Id

InputTypes

Represents the possible input types for HTML input elements.

Interpolate

Represents a function that interpolates between two values.

ListenerOptions

MathMLAttributes

Represents the attributes used in MathML elements.

MathMLTags

Represents a collection of MathML tags.

Merge

NillifyValue

NonNillable

NValue

Represents a nullable value or a signal of a nullable value.

ObjectToUnion

Converts an object to a union of its keys.

OneOfFieldOptions

Represents the options for a one-of field.

OneOfKindOptions

The options for a one-of kind field.

OneOfOptions

Represents a set of options for a one-of type.

OneOfTupleOptions

Represents a mapping of keys to functions that accept a value of type Signal<V> and return a TNode.

OneOfTypeOptions

Represents a mapping of types to rendering functions.

OneOfValueOptions

Represents a set of options for a one-of value.

ProbeResolution

Provider

Represents a provider function that takes a TNode and returns a Renderable.

ProviderMark

Represents a provider mark.

Providers

Represents a collection of providers. The keys of the record are ProviderMark types, and the values are of unknown type.

ReducerEffect

Represents a function that defines a reducer effect. A reducer effect is a function that takes in the previous state, current state, action, and a dispatch function, and performs some side effects based on the state and action.

ReducerEffectData

Represents the data passed to a reducer effect.

RemoveSignals

Removes signals from a given object type and returns a new object type with only the non-signal properties.

Renderable

Represents a function that can be rendered in the DOM.

RenderOptions

Options for rendering.

Size

Represents the size of an object with width and height.

StorageOptions

Represents the properties required for storing and retrieving a value of type T.

StoredPropOptions

Represents the properties required for storing and retrieving a value of type T.

SVGAttributes

Represents the attributes that can be used in SVG elements.

SVGTags

Represents a mapping of SVG tag names to their corresponding SVG element types.

TaskOptions

Represents the options for a task.

TNode

Represents a node in the rendering tree. It can be a renderable element, a string value, undefined, null, or an array of renderable elements.

ToArrayOfMarks

Converts a tuple type T into an array of ProviderMark types. If T is an empty tuple, returns an empty array. If T has only one element, returns an array with a single ProviderMark. If T has more than one element, recursively converts each element into a ProviderMark and returns an array.

ToProviders

Represents a type that transforms a tuple of values into an object where each value is associated with a provider mark.

UseMany

Represents a type that extracts the value types from a record of Consumer types.

Value

Represents a value that can either be a Signal<T> or a generic type T.