Documentation navigation

Published API · 0.1.0-rc.1

foldkit · customElement

Published foldkit API declarations for customElement.

./customElement

@wsagency/wseffect-foldkit · MIT · source · MIT license · WS-AGENCY-NOTICE · THIRD-PARTY-NOTICES

This entry point is published in @wsagency/wseffect-foldkit@0.1.0-rc.1. Import it from the package subpath shown below; the signatures and documentation are read from the installed package declarations.

import * as Wseffect from '@wsagency/wseffect-foldkit/customElement'

Exported declarations

Builder

The typed builder for a given spec and Message universe. Equivalent to the value `Spec.withMessage<Message>()` returns, expressed as a type consumers can name without reaching for `ReturnType<typeof ...>`.

export type Builder<Spec, Message> = Spec extends CustomElementSpec<string, infer Properties, infer Events> ? ElementBuilder<Message, Properties, Events> : never;

CustomElementConfig

Configuration accepted by `CustomElement.define`.

export interface CustomElementConfig<Tag extends string, Properties extends Record<string, Schema.Top>, Events extends Record<string, EventSchema>> {
    readonly tag: Tag;
    readonly properties: Properties;
    readonly events: Events;
}

CustomElementSpec

A defined custom element, untyped on Message at definition time so the spec can be exported and shared across modules. Call `.withMessage(h)` with a view's builder to mint a typed `ElementBuilder` bound to that frame's Message universe. The builder argument is a type witness: it fixes `Message` to the frame the element renders in, so the spec cannot be bound to a Message universe its events will not dispatch into.

export interface CustomElementSpec<Tag extends string, Properties extends Record<string, Schema.Top>, Events extends Record<string, EventSchema>> {
    readonly tag: Tag;
    readonly properties: Properties;
    readonly events: Events;
    readonly withMessage: <Message>(h: HtmlBuilder<Message>) => ElementBuilder<Message, Properties, Events>;
}

define

Define a typed binding for a custom element. The returned spec describes the element's properties and events with Schema, and exposes a `.withMessage<Message>()` factory that yields a typed `ElementBuilder` for the consumer's Message universe. Property changes diff across renders; declared `CustomEvent` details are decoded against their Schema before the runtime converts them to Messages. A detail the Schema rejects is reported to the console and dispatches no Message.

define: <Tag extends string, Properties extends Record<string, Schema.Top>, Events extends Record<string, EventSchema>>(config: CustomElementConfig<Tag, Properties, Events>) => CustomElementSpec<Tag, Properties, Events>

ElementBuilder

export type ElementBuilder<Message, Properties extends Record<string, Schema.Top>, Events extends Record<string, EventSchema>> = ((attributes?: ReadonlyArray<Attribute<Message> | ChildAttribute>, children?: ReadonlyArray<Child>) => Html) & PropertyFactories<Message, Properties> & EventFactories<Message, Events>;

EventSchema

Constraint on a declared event's `detail` Schema. The runtime decodes `detail` synchronously inside the DOM event handler, where there is no Effect context to draw from, so a Schema requiring decoding services cannot describe an event payload.

export type EventSchema = Schema.Codec<unknown, unknown, never, unknown>;