solid

package
v0.2.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 3, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package solid lowers JSX into the DOM-expressions calls that solid-js/web provides.

The transform operates on the JSX intermediate representation defined in this file rather than on any parser's AST. Build the IR directly, or use the tsx package to produce it from TypeScript source.

m := solid.NewModule(solid.Options{})
expr := m.Compile(node)
src := m.Prelude() + "const C = () => " + expr + ";" + m.Postlude()

Compile returns a JavaScript expression. Prelude returns the runtime import and hoisted templates the compiled expressions refer to, and Postlude the event delegation registration; both must be included in the emitted module.

Index

Constants

This section is empty.

Variables

View Source
var Undef = undef{}

Undef is the value of a property that was never set.

Functions

func DelegatedEvents added in v0.2.2

func DelegatedEvents() []string

DelegatedEvents lists the delegated event names, sorted.

func Display added in v0.2.2

func Display(v any) (string, bool)

Display encodes a value as JSX writes it, reporting false for the values JSX omits: null, undefined, and the booleans.

func EscapeValue added in v0.2.2

func EscapeValue(s string, mode Escape) string

EscapeValue encodes a value arriving at render time, which is how a renderer must write what a Hole or an Attribute evaluates to.

Unlike the escaping applied to author-written text, an ampersand is always encoded: a value that happens to read as a character reference is data.

func Eval added in v0.2.2

func Eval(p Plan, props map[string]any) (any, error)

Eval computes a plan against props. The error reports the first construct the plan required and the value could not supply.

v, err := solid.Eval(slot.Plan, props)
s, ok := solid.Display(v) // ok is false for values JSX omits

func FormatNumber added in v0.2.2

func FormatNumber(f float64) string

FormatNumber implements ECMAScript Number::toString for base ten.

Go's shortest representation agrees on digits but not on when to switch to exponential form, which JavaScript does only at 1e21 and below 1e-6.

func IsBooleanAttribute added in v0.2.2

func IsBooleanAttribute(name string) bool

IsBooleanAttribute reports whether an attribute carries its value by presence rather than by content.

func IsComponentTag

func IsComponentTag(tag string) bool

IsComponentTag reports whether a JSX tag names a component rather than a host element: capitalized, dotted, or namespaced.

func IsDelegatedEvent

func IsDelegatedEvent(name string) bool

IsDelegatedEvent reports whether an event name is delegated by solid-js.

func IsPropertyAttribute added in v0.2.2

func IsPropertyAttribute(name string) bool

IsPropertyAttribute reports whether a name is assigned as a DOM property.

func IsVoidElement

func IsVoidElement(tag string) bool

IsVoidElement reports whether tag is an HTML void element.

func NormalizeJSXText

func NormalizeJSXText(s string) string

NormalizeJSXText applies JSX's whitespace rules to raw text between tags: whitespace-only lines vanish, indentation is stripped, and interior line breaks collapse to a single space.

The empty string means the text contributes nothing.

func PlanKey added in v0.2.2

func PlanKey(p Plan) string

PlanKey renders a plan compactly. Two plans with the same key compute the same value from the same fields, which is what lets a consumer key a cache on a slot rather than on whole props.

func PropertyAttributes added in v0.2.2

func PropertyAttributes() []string

PropertyAttributes lists the property-assigned names, sorted.

func Reads added in v0.2.2

func Reads(p Plan) []string

Reads reports every props path a plan depends on, sorted and deduplicated. A fragment's cache key needs only these fields rather than the whole props object.

key := hashFields(props, solid.Reads(slot.Plan))

func StrictEqual added in v0.2.2

func StrictEqual(l, r any) bool

StrictEqual implements ===, under which NaN equals nothing and the two zeroes are equal.

func ToNumber added in v0.2.2

func ToNumber(v any) float64

ToNumber coerces to a number, yielding NaN where JavaScript does.

func ToString added in v0.2.2

func ToString(v any) string

ToString encodes a value as JavaScript's String() does.

func Truthy added in v0.2.2

func Truthy(v any) bool

Truthy reports whether a value is truthy. Empty strings, zero, NaN, null, and undefined are not; every object and array is.

Types

type Attr

type Attr struct {
	Namespace string
	Name      string
	Kind      AttrKind
	// Value is the string content for AttrString, or the expression source
	// for AttrExpr.
	Value string

	// Eval derives the value from props alone, or is nil when the frontend
	// could not prove it derivable. Only ever set for AttrExpr. See [Plan].
	Eval Plan
}

Attr is a JSX attribute. Namespace holds the part before a colon, as in on:click, use:directive, prop:value, attr:id, bool:x, style:color, class:active.

func (Attr) IsDynamic

func (a Attr) IsDynamic() bool

IsDynamic reports whether the value must be re-evaluated when reactive state changes.

type AttrKind

type AttrKind uint8

AttrKind discriminates how an attribute's value was written.

const (
	// AttrBare is a valueless attribute, as in <input disabled />, which means
	// the boolean true.
	AttrBare AttrKind = iota
	// AttrString is a literal string value, as in class="card".
	AttrString
	// AttrExpr is an interpolated value, as in class={x}.
	AttrExpr
)

type Attribute added in v0.2.2

type Attribute struct {
	Name string
	Slot Slot
	// Bool marks an attribute whose presence carries its value: written bare
	// when the value is truthy, omitted otherwise.
	Bool bool
}

Attribute writes name="value". A value JSX omits omits the attribute entirely rather than writing it empty.

type BinOp added in v0.2.2

type BinOp uint8

BinOp is a binary operator. Only operators with agreed semantics across the JavaScript and Go evaluators appear here; == and != deliberately do not.

const (
	OpStrictEq BinOp = iota
	OpStrictNe
	OpLt
	OpLe
	OpGt
	OpGe
	OpAdd
	OpSub
	OpMul
	OpDiv
	OpMod
)

type Binary added in v0.2.2

type Binary struct {
	Op   BinOp
	L, R Plan
}

Binary applies an arithmetic or comparison operator.

type Component

type Component struct {
	Tag      string
	Attrs    []Attr
	Children []Node
}

Component is a capitalized or dotted tag, which compiles to a createComponent call rather than to DOM.

type Concat added in v0.2.2

type Concat struct{ Parts []Plan }

Concat is string building, from a template literal or the + operator.

type Cond added in v0.2.2

type Cond struct{ If, Then, Else Plan }

Cond is a ternary, or a logical operator lowered to one.

type Const added in v0.2.2

type Const struct{ Value Value }

Const is a value fixed at compile time.

type Element

type Element struct {
	Tag      string
	Attrs    []Attr
	Children []Node
}

Element is a host element: a lowercase tag that becomes real DOM.

type Escape added in v0.2.2

type Escape uint8

Escape selects the encoding a plan's result is written with.

const (
	// EscapeText encodes for character data.
	EscapeText Escape = iota
	// EscapeAttr encodes for a double-quoted attribute value.
	EscapeAttr
)

type Expr

type Expr struct {
	Code string

	// Eval derives the value from props alone, or is nil when the frontend
	// could not prove it derivable. See [Plan].
	Eval Plan
}

Expr is a {...} interpolation. Code is the original TypeScript source of the expression, which is emitted verbatim.

func (*Expr) IsDynamic

func (e *Expr) IsDynamic() bool

IsDynamic reports whether an interpolated child must be wrapped so that it re-runs on change.

type Fragment

type Fragment struct {
	Children []Node
}

Fragment is <>...</>, which compiles to an array.

type Hole added in v0.2.2

type Hole struct{ Slot Slot }

Hole writes a slot's value as character data, or nothing when the value is one JSX omits.

type Map added in v0.2.2

type Map struct {
	Each Plan
	Bind string
	Body Plan
}

Map repeats Body once per element of Each, binding the element to Bind. It is what <For>, <Index>, and Array.prototype.map lower to.

type Module

type Module struct {
	// contains filtered or unexported fields
}

Module accumulates the state shared across every JSX expression in one source file: hoisted templates, the runtime helpers used, and the events needing delegation.

Compile one expression at a time, then take the Prelude and Postlude. A Module is not safe for concurrent use.

func NewModule

func NewModule(opts Options) *Module

NewModule returns a Module ready to compile the JSX of one source file.

func (*Module) Compile

func (m *Module) Compile(n Node) string

Compile lowers one JSX node into a JavaScript expression, suitable for substituting in place of the original JSX.

func (*Module) Helpers

func (m *Module) Helpers() []string

Helpers returns the runtime helpers used so far, sorted. The template helper is included whenever any template was hoisted.

func (*Module) Postlude

func (m *Module) Postlude() string

Postlude returns the statements that must appear at the end of the module: the event delegation registration, if any.

func (*Module) Prelude

func (m *Module) Prelude() string

Prelude returns the statements that must appear at the top of the module: the runtime import and the hoisted template declarations.

type Node

type Node interface {
	// contains filtered or unexported methods
}

Node is a node of the JSX intermediate representation.

type Options

type Options struct {
	// ModuleName is the import source for runtime helpers.
	// Defaults to "solid-js/web".
	ModuleName string

	// Delegate routes supported events through a single document-level
	// listener. Defaults to true; set DisableDelegation to turn it off.
	DisableDelegation bool

	// Prefix is prepended to generated runtime helper identifiers.
	// Defaults to "_$", matching solid's own output.
	Prefix string
}

Options configures the transform. The zero value is valid.

type Path added in v0.2.2

type Path struct {
	Root  string // "" for props, otherwise a Map binding
	Steps []string
}

Path is a property chain rooted at props or at a Map binding, as in props.user.name.

type Plan added in v0.2.2

type Plan interface {
	// contains filtered or unexported methods
}

Plan is a hole's value expressed over props. A nil Plan marks a red hole: one no frontend could prove derivable.

type Program added in v0.2.2

type Program struct {
	Segments []Segment

	// Red lists the holes that need the client. A program with none can be
	// rendered from props alone.
	Red []Red

	// Interactive lists the reasons the component needs client JavaScript
	// even where its markup is complete: event handlers, refs, directives.
	Interactive []Red
}

Program is a component's markup as segments, with whatever it could not describe.

func Emit added in v0.2.2

func Emit(n Node) *Program

Emit lowers a JSX node into a segment program.

prog := solid.Emit(node)
if prog.Inert() { /* markup alone; the component needs no client JS */ }

func (*Program) Green added in v0.2.2

func (p *Program) Green() bool

Green reports whether every hole could be described in terms of props, which is what makes the program renderable without a JavaScript engine.

func (*Program) Hash added in v0.2.2

func (p *Program) Hash() string

Hash identifies a program by content, so that a consumer storing the same markup reached from two components can store it once.

func (*Program) Inert added in v0.2.2

func (p *Program) Inert() bool

Inert reports whether the program is green and also needs no client JavaScript, so the component can ship as markup alone.

type Red added in v0.2.2

type Red struct {
	Code   string
	Reason string
}

Red is a hole whose markup could not be described without running JavaScript. Code is the expression's source, for diagnostics.

type Segment added in v0.2.2

type Segment interface {
	// contains filtered or unexported methods
}

Segment is one piece of a program's markup.

type Slot added in v0.2.2

type Slot struct {
	Plan   Plan
	Escape Escape
}

Slot is one plan together with the encoding its result is written with. It is the unit a segment program interleaves with static markup.

type Spread

type Spread struct {
	Code string
}

Spread is a {...props} attribute position.

type Static added in v0.2.2

type Static struct{ HTML string }

Static is markup fixed at compile time, already escaped.

type Text

type Text struct {
	Value string
}

Text is literal text between tags. Value is the already-normalized text; see NormalizeJSXText.

type UnOp added in v0.2.2

type UnOp uint8

UnOp is a prefix operator.

const (
	OpNot UnOp = iota
	OpNeg
)

type Unary added in v0.2.2

type Unary struct {
	Op UnOp
	X  Plan
}

Unary applies a prefix operator.

type Value added in v0.2.2

type Value struct {
	Kind ValueKind
	Num  float64
	Str  string
	B    bool
}

Value is a compile-time constant. The zero value is JavaScript undefined.

type ValueKind added in v0.2.2

type ValueKind uint8

ValueKind discriminates a Value.

const (
	Undefined ValueKind = iota
	Null
	Bool
	Number
	String
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL