ui

type A ¶

type A struct{ HTMLInner }

An A renders an HTML anchor element with dynamic inner HTML.

One A value may back multiple live jaws.Element values. Its HTML getter is shared by those Elements and must be safe for their render, update and event calls.

func NewA(innerHTML any) *A

func (u *A) JawsRender(elem *jaws.Element, w io.Writer, params []any) error

type Button ¶

type Button struct{ HTMLInner }

Button renders an HTML button element with dynamic inner HTML.

One Button value may back multiple live jaws.Element values. Its HTML getter is shared by those Elements and must be safe for their render, update and event calls.

func NewButton(innerHTML any) *Button

func (u *Button) JawsRender(elem *jaws.Element, w io.Writer, params []any) error

type Checkbox ¶

type Checkbox struct{ InputBool }

Checkbox renders an HTML checkbox input bound to a bool setter.

A Checkbox value must back at most one live jaws.Element. Construct distinct Checkbox values over the same setter to render one bound value more than once.

func NewCheckbox(g bind.Setter[bool]) *Checkbox

func (u *Checkbox) JawsRender(elem *jaws.Element, w io.Writer, params []any) error

type Container ¶

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

Container renders an HTML element around a dynamic child collection.

Its outer tag and child provider define its identity. The provider's dynamic value must be comparable and equal to itself. Rebuilding an equal Container lets a parent retain its live Element. Keep application state containing a slice, map, or function behind a stable pointer and synchronize access to it.

Reconciliation affects direct children only. Reordering retained equal children preserves their Elements and nested subtrees. Nested containers whose children change need their own update. Child Element identity is scoped to its parent; moving a child definition between parents does not preserve its Element. Each child must render one direct DOM node carrying its Element's JaWS ID. Use NewTemplate for Template children so removal and ordering can target a wrapper.

Equal Container values may back multiple live Elements in one jaws.Request when the provider is safe for all calls and each child UI value reused across those Elements supports multiple live Elements. Use Container as a value; taking its address changes identity and is unsupported.

A typed-nil provider is called normally and must tolerate its nil receiver.

package main

import (
	"bytes"
	"encoding/json"
	"fmt"

	"github.com/linkdata/jaws"
	"github.com/linkdata/jaws/lib/ui"
)

type exampleContainer []string

func (c exampleContainer) JawsContains(elem *jaws.Element) (contents []jaws.UI) {
	for _, item := range c {
		contents = append(contents, ui.NewSpan(item))
	}
	return
}

func main() {
	firstRows := exampleContainer{"one"}
	secondRows := exampleContainer{"two"}
	first := ui.NewContainer("div", &firstRows)
	second := ui.NewContainer("div", &secondRows)
	fmt.Println(first == second)

	var b bytes.Buffer
	enc := json.NewEncoder(&b)
	_ = enc.Encode([]string{"construct containers during render"})
	fmt.Print(b.String())

}

Output:
false
["construct containers during render"]

func NewContainer(outerHTMLTag string, children jaws.Container) Container

func (u Container) JawsRender(elem *jaws.Element, w io.Writer, params []any) error

func (u Container) JawsUpdate(elem *jaws.Element)

type Date ¶

type Date struct{ InputDate }

Date renders an HTML date input bound to a time value setter.

A Date value must back at most one live jaws.Element. Construct distinct Date values over the same setter to render one bound value more than once.

The control is date-only: a browser edit normalizes the bound time.Time to midnight UTC of the picked date, discarding time-of-day and location. See InputDate.JawsInput.

func NewDate(g bind.Setter[time.Time]) *Date

func (u *Date) JawsRender(elem *jaws.Element, w io.Writer, params []any) error

type Div ¶

type Div struct{ HTMLInner }

Div renders an HTML div element with dynamic inner HTML.

One Div value may back multiple live jaws.Element values. Its HTML getter is shared by those Elements and must be safe for their render, update and event calls.

func NewDiv(innerHTML any) *Div

func (u *Div) JawsRender(elem *jaws.Element, w io.Writer, params []any) error

type HTMLInner ¶

type HTMLInner struct {
	// HTMLGetter returns the trusted inner HTML to render and update.
	HTMLGetter bind.HTMLGetter
}

HTMLInner is a reusable base for widgets that render as `<tag>inner</tag>`.

HTMLInner retains no Element-specific state. A widget embedding it may back multiple live jaws.Element values when its HTMLGetter is also safe for those Elements' render, update and event calls.

func (u *HTMLInner) JawsUpdate(elem *jaws.Element)

type Img ¶

type Img struct{ bind.Getter[string] }

Img renders an HTML img element whose src is read from a string getter.

The getter-derived src takes precedence over any src attribute passed as a render param or returned by the getter's jaws.InitialHTMLAttrHandler.

One Img value may back multiple live jaws.Element values. Its getter is shared by those Elements and must be safe for their render, update and event calls.

func NewImg(g bind.Getter[string]) *Img

func (u *Img) JawsRender(elem *jaws.Element, w io.Writer, params []any) (err error)

func (u *Img) JawsUpdate(elem *jaws.Element)

type Input ¶

type Input struct {

	// Last holds widget-specific state used to filter redundant browser updates.
	// Widget implementations own this cache; callers must not modify it.
	Last atomic.Value
	// contains filtered or unexported fields
}

Input stores common state for interactive input widgets.

An Input value provides a widget-owned update cache and dirty target for one live jaws.Element. A widget embedding Input must therefore back at most one live Element. To render the same bound state more than once, construct distinct widgets that share the setter.

For post-set reconciliation, a writable setter must expose at least one stable, usable tag through jaws.Element.ApplyGetter. bind.New exposes its backing value pointer.

After bind.Setter.JawsSet returns a result that does not match jaws.ErrValueUnchanged, Input dirties the setter-derived tag so the server value can reconcile rejected or normalized browser input. Tags supplied as render parameters register the Element but do not replace that dirty target. Without a valid setter-derived target, automatic reconciliation does not occur.

A completed native form reset changes browser state without an input/change event, so it does not update the Go binding. Reset authoritative Go values from a JaWS-handled button with type="button", then dirty their tags.

type InputBool ¶

type InputBool struct {
	Input
	bind.Setter[bool]
}

InputBool is the reusable base for boolean input widgets.

A widget embedding InputBool must back at most one live jaws.Element.

func (u *InputBool) JawsInput(elem *jaws.Element, value string) (err error)

func (u *InputBool) JawsUpdate(elem *jaws.Element)

type InputDate ¶

type InputDate struct {
	Input
	bind.Setter[time.Time]
}

InputDate is the reusable base for date input widgets.

A widget embedding InputDate must back at most one live jaws.Element.

The control is date-only. Rendering shows the calendar date in the bound value's own location, but a browser edit normalizes the bound time.Time to midnight UTC of the picked date, and only years 1 through 9999 round-trip; see InputDate.JawsInput.

func (u *InputDate) JawsInput(elem *jaws.Element, value string) (err error)

func (u *InputDate) JawsUpdate(elem *jaws.Element)

type InputText ¶

type InputText struct {
	Input
	bind.Setter[string]
}

InputText is the reusable base for string input widgets.

A widget embedding InputText must back at most one live jaws.Element.

func (u *InputText) JawsInput(elem *jaws.Element, value string) (err error)

func (u *InputText) JawsUpdate(elem *jaws.Element)

type IsJsVar ¶

type IsJsVar interface {
	bind.RWLocker
	jaws.UI
	jaws.InputHandler
	PathSetter
}

IsJsVar is implemented by JaWS UI values that bind a Go value to a browser-side JavaScript variable.

type JsVar ¶

type JsVar[T any] struct {
	bind.RWLocker
	Ptr         *T            // bound Go value
	ClientCheck JsVarCheck[T] // optional check for generic browser writes; configure before first use
	// contains filtered or unexported fields
}

JsVar binds a Go value to a named JavaScript variable in the browser.

A JsVar is request-scoped and must not be rendered by more than one jaws.Request. Within that request, it must back at most one live jaws.Element. Construct a fresh JsVar for each binding, either directly while rendering or through JsVarMaker. Distinct JsVar values may use the same locker and Ptr to expose synchronized application state to multiple Elements or requests.

JsVar is intended for JSON-marshalable state shared with application JavaScript. The browser binding reads and writes the window property named when the JsVar is rendered. Existing application variables are therefore valid bindings. Do not use a browser-owned property such as window.name, or a global owned by unrelated code.

Browser JSON numbers use JavaScript Number values. Signed and unsigned integers outside -9007199254740991 through 9007199254740991 may be rounded in a snapshot or broadcast; a later browser write may store the rounded value in Go.

Represent exact wide integers as built-in string fields and convert them explicitly. Browser code must convert BigInt values back to strings before calling jawsVar. A json:",string" tag is not generic round-trip support; use a built-in string field or a PathSetter.

JSON-marshalable describes server-to-browser values. Generic browser writes decode into any and assign by path; they do not unmarshal directly into T or invoke destination custom unmarshaling. Consequently, time.Time, []byte, and maps with non-string keys are not round-trip writable by the generic setter. Use a browser-facing DTO compatible with the generic setter, or implement PathSetter to parse and validate the decoded value.

Generic array and slice path components must be canonical JavaScript array indices representable as int: "0" or ASCII decimal digits without a leading zero, at most 4294967294. A component that violates these rules produces an error matching github.com/linkdata/jq.ErrPathNotFound when traversal reaches an array or slice. String-keyed map entries are matched exactly. Struct path components and map-to-struct keys follow the default field-selection rules of encoding/json. An exact json:"-" tag excludes an otherwise selected exported field. For a non-promoting field, a valid nonempty JSON tag name is used verbatim, while an absent, empty, or invalid name falls back to the Go field name; json:"-," therefore names the field "-". Ambiguous fields are absent from the path namespace.

An anonymous struct without a valid explicit JSON name contributes its promoted fields directly and does not add its Go type name as a component: use "value", not "Inner.value", or give the anonymous field an explicit tag to create a nested path. Promotion reaches exported fields through unexported embedded structs. An explicitly named unexported anonymous struct is not itself a readable or writable endpoint or writable map-to-struct key, but longer paths can reach its exported fields.

Reads and generic writes that traverse a nil pointer produce an error matching github.com/linkdata/jq.ErrPathNotFound, and generic writes do not allocate the pointer. Empty components are ignored, and both "" and "." address the root.

While the WebSocket is open, jawsVar sends one complete message per matching live binding, subject to jaws.Request.ServeHTTP's inbound limit. JsVar.ClientCheck runs only after receipt and cannot enforce that limit. Use a separate upload endpoint for large data.

The variable name and browser-side jawsVar paths must be application-controlled. The browser rejects exact "__proto__" path components; put user data in values, not names or paths.

Multiple bindings may share a name. The name is a single browser window property, and a browser-initiated write to it is delivered to every live binding of that name; a removed binding stops receiving writes. This lets a subtree re-render replace a binding, lets several requests expose the same application-owned global, and lets one browser value fan out to several independent Go bindings.

When bindings sharing a name also share a mutable backing object graph, a browser write applies to that shared state once per binding. Those bindings must use the same locker. Do not expose that state through several simultaneously rendered bindings when its PathSetter is not idempotent (for example one that appends).

Unlike most JaWS UI values, a JsVar is a bidirectional channel and does not imply that the Go value is always authoritative. Browser and Go updates may each carry a complete value or individual paths. Any desired ownership, conflict, or merge policy is the application's responsibility.

When Ptr is non-nil, JsVar.JawsRender serializes a snapshot of the bound Go value to initialize the browser variable. A browser call to the JavaScript jawsVar function sends only while its WebSocket is open; an earlier call is not queued for later transmission. JsVar.JawsSet and JsVar.JawsSetPath broadcast only to matching active requests, so an update is not replayed to a page between its initial render and its broadcast subscription. Applications that require the two sides to converge after either can change the value during that interval must reconcile it explicitly.

It is safe for concurrent use when the locker passed to NewJsVar is safe for concurrent use. Concurrent writes are applied one at a time. Any broadcasts they produce preserve the order in which the writes modify the bound value. This concurrency guarantee does not permit one JsVar to be shared between requests.

Rendering and write broadcasts invoke JSON marshalers while the locker passed to NewJsVar is held. Custom marshaling callbacks reached in either case, including MarshalJSON and MarshalText, must not acquire that locker or re-enter the JsVar.

A JsVar must not be copied after first use.

SECURITY: a JsVar is client-writable. Incoming browser "set" messages are applied by path to the bound value. If the bound value implements PathSetter, its JawsSetPath validates and applies the change. Otherwise github.com/linkdata/jq.Set can write any exported field addressable by the generic path rules above and append one element per message to a slice.

There is no default cumulative size bound. Set JsVar.ClientCheck before first use to validate each tentative generic browser update. JSONSizeCheck provides an exact serialized-size limit. Every client-writable binding that can mutate the same backing object graph must share synchronization and use an equivalent checking policy. An unchecked or less restrictive binding can otherwise commit first; another binding then sees an unchanged value and does not run its check. A ClientCheck does not run for rendering, programmatic writes, invalid or unchanged writes, or values implementing PathSetter. It is an acceptance gate, not a monitor that proves the current value always satisfies an invariant. A check that uses github.com/linkdata/jq.Get cannot inspect an explicitly named unexported anonymous struct at its own endpoint; it must inspect a longer exported-field path or the tentative Go value directly.

A size check does not prevent a client from setting individual exported fields. When only some fields or paths should be client-writable, implement PathSetter on the bound value to allow-list paths and bound lengths.

Rejecting a browser write rolls back Go state without changing the value that the browser already assigned before sending it. Except for ErrJsVarTooLarge, which aborts the associated request when present, the application must resynchronize the browser if it requires immediate convergence after rejection. See the Node type in github.com/linkdata/jawstree for an example that restricts client writes to a single boolean field.

package main

import (
	"errors"
	"fmt"
	"sync"

	"github.com/linkdata/jaws"
	"github.com/linkdata/jaws/lib/ui"
)

type examplePathState struct {
	Title string   `json:"title"`
	Items []string `json:"items"`
}

func (state *examplePathState) JawsSetPath(elem *jaws.Element, jsPath string, value any) error {
	if jsPath != "title" {
		return fmt.Errorf("%w: %s", ui.ErrIllegalJsVarPath, jsPath)
	}
	title, ok := value.(string)
	if !ok {
		return fmt.Errorf("title: %T", value)
	}
	if state.Title == title {
		return jaws.ErrValueUnchanged
	}
	state.Title = title
	return nil
}

func main() {
	var mu sync.Mutex
	state := examplePathState{Title: "old", Items: []string{"server-owned"}}
	jsv := ui.NewJsVar(&mu, &state)

	if err := jsv.JawsSetPath(nil, "title", "new"); err != nil {
		panic(err)
	}
	err := jsv.JawsSetPath(nil, "items.1", "blocked")
	fmt.Println(state.Title)
	fmt.Println(errors.Is(err, ui.ErrIllegalJsVarPath))

}

Output:
new
true

func NewJsVar[T any](l sync.Locker, v *T) *JsVar[T]

func (jsvar *JsVar[T]) JawsGet(elem *jaws.Element) (value T)

func (jsvar *JsVar[T]) JawsGetPath(elem *jaws.Element, jsPath string) (value any)

func (jsvar *JsVar[T]) JawsGetTag() any

func (jsvar *JsVar[T]) JawsInput(elem *jaws.Element, value string) (err error)

func (jsvar *JsVar[T]) JawsRender(elem *jaws.Element, w io.Writer, params []any) (err error)

func (jsvar *JsVar[T]) JawsSet(elem *jaws.Element, value T) (err error)

func (jsvar *JsVar[T]) JawsSetPath(elem *jaws.Element, jsPath string, value any) (err error)

func (jsvar *JsVar[T]) JawsUpdate(elem *jaws.Element)

type JsVarCheck ¶ added in v0.700.0

type JsVarCheck[T any] = func(value *T, jsPath string) error

JsVarCheck validates a tentative browser update to a JsVar.

JsVarCheck is a type alias so a value of a defined function type with this signature can be assigned to JsVar.ClientCheck without explicit conversion.

The value contains the complete tentative state, and jsPath is the original browser-supplied jq path. The generic setter ignores empty components, so use jsPath only as an inspection hint; implement PathSetter to allow-list paths. See JsVar for generic path rules.

A nil error accepts the update. A non-nil error rejects it atomically and is returned unchanged, except that an error matching ErrJsVarTooLarge is returned as that sentinel after cancelling the associated request, when one is present. A panic rejects the update before continuing unchanged.

The check validates tentative Go state only. A broadcast carries the decoded browser value rather than reading the stored path back, so jq conversions or ignored map-to-struct entries can make the peer value differ from the state inspected here. Use PathSetter when peer-visible input also needs validation.

The check runs while the locker passed to NewJsVar is write-locked. It may inspect or marshal value, but it must not mutate it, acquire that locker, re-enter the JsVar, call a jq setter on the value, or retain references into a rejected tentative value. Any custom marshaling callback it invokes, including MarshalJSON or MarshalText, has the same restrictions. The check must not return or wrap jaws.ErrEventUnhandled, which has handler-dispatch semantics.

func JSONSizeCheck[T any](maxBytes int) (check JsVarCheck[T])

package main

import (
	"sync"

	"github.com/linkdata/jaws/lib/ui"
)

func main() {
	type clientState struct {
		Items []string `json:"items"`
	}

	var mu sync.Mutex
	state := clientState{}
	jsv := ui.NewJsVar(&mu, &state)
	jsv.ClientCheck = ui.JSONSizeCheck[clientState](1 << 20)

	_ = jsv // render this request-scoped binding normally
}

Output:

type JsVarMaker ¶

type JsVarMaker interface {
	JawsMakeJsVar(rq *jaws.Request) (value IsJsVar, err error)
}

JsVarMaker creates a request-scoped JavaScript variable binding.

JawsMakeJsVar must return a fresh IsJsVar for each call. The returned value is scoped to rq and one live jaws.Element. Bindings may share synchronized backing state, but the binding values themselves must remain distinct.

type Label ¶

type Label struct{ HTMLInner }

Label renders an HTML label element with dynamic inner HTML.

One Label value may back multiple live jaws.Element values. Its HTML getter is shared by those Elements and must be safe for their render, update and event calls.

func NewLabel(innerHTML any) *Label

func (u *Label) JawsRender(elem *jaws.Element, w io.Writer, params []any) error

type Li ¶

type Li struct{ HTMLInner }

Li renders an HTML list item with dynamic inner HTML.

One Li value may back multiple live jaws.Element values. Its HTML getter is shared by those Elements and must be safe for their render, update and event calls.

func NewLi(innerHTML any) *Li

func (u *Li) JawsRender(elem *jaws.Element, w io.Writer, params []any) error

type Number ¶

type Number struct {
	Input
	// contains filtered or unexported fields
}

Number renders an HTML number input.

A Number value must back at most one live jaws.Element. Construct distinct Number values over the same source to render one bound value more than once. Construct a Number with NewNumber; using its zero value as a widget panics.

Editable Numbers send edits on the browser's change event. Pending edits remain browser-local until then and may be replaced by server or ancestor renders.

func NewNumber[T Numeric](source bind.Getter[T]) *Number

func (u *Number) JawsInput(elem *jaws.Element, text string) error

func (u *Number) JawsRender(elem *jaws.Element, w io.Writer, params []any) (err error)

func (u *Number) JawsUpdate(elem *jaws.Element)

type Numeric ¶ added in v0.700.0

type Numeric interface {
	~int | ~int8 | ~int16 | ~int32 | ~int64 |
		~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~uintptr |
		~float32 | ~float64
}

Numeric is an integer or floating-point type supported by Number and Range.

Named types with one of these underlying types are included.

type Object ¶ added in v0.400.0

type Object interface {
	bind.HTMLGetter
	tag.TagGetter
	jaws.ClickHandler
	jaws.ContextMenuHandler
	jaws.InitialHTMLAttrHandler

	// Clicked adds fn as the newest click hook and returns the resulting [Object].
	Clicked(fn ObjectClickedHook) (newobj Object)

	// ContextMenu adds fn as the newest context-menu hook and returns the
	// resulting [Object].
	ContextMenu(fn ObjectContextMenuHook) (newobj Object)

	// InitialHTMLAttr adds fn as the newest initial-attribute hook and returns the
	// resulting [Object].
	InitialHTMLAttr(fn ObjectInitialHTMLAttrHook) (newobj Object)
}

Object is a chainable UI object.

Each call to Object.Clicked, Object.ContextMenu, or Object.InitialHTMLAttr returns a new chain node wrapping its receiver. Calls to jaws.ClickHandler.JawsClick and jaws.ContextMenuHandler.JawsContextMenu run the corresponding hooks from newest to oldest. Dispatch continues while the result matches jaws.ErrEventUnhandled according to errors.Is, including when wrapped, and stops at the first other result. If no hook handles the event, the invoked method returns an error matching jaws.ErrEventUnhandled. Each hook receives the node containing it as its Object argument; that node includes the hook and all older links, but no newer links.

jaws.InitialHTMLAttrHandler.JawsInitialHTMLAttr runs all initial-attribute hooks from newest to oldest. Their non-empty results are joined in that order with one space inserted between results.

The effective expanded tag set combines the non-nil tag contributions of every link, and adding a link preserves older links' contributions. The resulting Object remains subject to tag.TagGetter's initialization, stability, and concurrency requirements. Use tag.TagExpand to obtain flattened, validated keys.

func New(innerHTML any) (obj Object)

type ObjectClickedHook ¶ added in v0.500.0

type ObjectClickedHook func(obj Object, elem *jaws.Element, click jaws.Click) (err error)

ObjectClickedHook handles a click event for an Object.

obj is the chain node containing the hook. See Object for composition semantics.

Unlike bind.ClickedHook, ObjectClickedHook receives an Object rather than a bind.Binder.

type ObjectContextMenuHook ¶ added in v0.500.0

type ObjectContextMenuHook func(obj Object, elem *jaws.Element, click jaws.Click) (err error)

ObjectContextMenuHook handles a context menu event for an Object.

obj is the chain node containing the hook. See Object for composition semantics.

type ObjectInitialHTMLAttrHook ¶ added in v0.500.0

type ObjectInitialHTMLAttrHook = func(obj Object, elem *jaws.Element) (s template.HTMLAttr)

ObjectInitialHTMLAttrHook provides attributes when an Object is initially rendered.

obj is the chain node containing the hook. See Object for composition semantics.

ObjectInitialHTMLAttrHook is a type alias so a value of a defined function type with this signature can be passed to Object.InitialHTMLAttr without explicit conversion.

type Option ¶

type Option struct{ *named.Bool }

Option renders an HTML option element backed by a named.Bool.

The value attribute is always named.Bool.Name and takes precedence over a value attribute passed as a render param.

One Option value may back multiple live jaws.Element values. All of those Elements reflect the shared Bool.

func NewOption(nb *named.Bool) Option

func (u Option) JawsRender(elem *jaws.Element, w io.Writer, params []any) error

func (u Option) JawsUpdate(elem *jaws.Element)

type Password ¶

type Password struct{ InputText }

Password renders an HTML password input bound to a string setter.

A Password value must back at most one live jaws.Element. Construct distinct Password values over the same setter to render one bound value more than once.

func NewPassword(g bind.Setter[string]) *Password

func (u *Password) JawsRender(elem *jaws.Element, w io.Writer, params []any) error

type PathSetter ¶

type PathSetter interface {
	// JawsSetPath should set the JSON object member identified by jsPath to the given value.
	//
	// Browser writes pass [json.Unmarshal]'s generic any representation without
	// the raw JSON bytes. Programmatic [JsVar.JawsSetPath] calls pass the
	// caller-supplied value unchanged.
	//
	// A [JsVar] returns [ErrIllegalJsVarPath] before calling a PathSetter when
	// jsPath contains a protocol byte. Otherwise it passes jsPath unchanged and
	// does not apply generic jq validation. Successful broadcasts preserve jsPath
	// and the requested value.
	//
	// If the member is already the given value, it should return [jaws.ErrValueUnchanged].
	//
	// When a [JsVar]'s bound value (Ptr) implements PathSetter, the JsVar
	// delegates to it while holding the JsVar write lock. Such an
	// implementation must not lock or unlock the JsVar, nor call its locked
	// accessors such as [JsVar.JawsGet] or [JsVar.JawsSet].
	//
	// When an accepted update is broadcast, the JsVar marshals value before
	// releasing that write lock. Custom marshaling callbacks reachable from value,
	// including MarshalJSON and MarshalText, must not acquire the same locker or
	// re-enter the JsVar.
	//
	// If an implementation panics, the calling JsVar releases its write lock
	// before propagating the panic.
	JawsSetPath(elem *jaws.Element, jsPath string, value any) (err error)
}

PathSetter can set a nested JSON path value.

type Radio ¶

type Radio struct{ InputBool }

Radio renders an HTML radio input bound to a bool setter.

A Radio value must back at most one live jaws.Element. Construct distinct Radio values over the same setter to render one bound value more than once.

Each Radio binds an independent boolean. An HTML radio group does not group its Go bindings: the browser reports the newly checked radio, not peers it unchecks. Use RequestWriter.RadioGroup with a single-select named.BoolArray and distinct named.Bool.Name values, or coordinated setters that clear peers together and dirty every changed binding.

func NewRadio(g bind.Setter[bool]) *Radio

func (u *Radio) JawsRender(elem *jaws.Element, w io.Writer, params []any) error

type RadioElement ¶

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

RadioElement renders the input and label elements for one radio option.

The underlying jaws.Element values are created lazily on the first call to RadioElement.Radio or RadioElement.Label, so options that a template never renders register no elements on the jaws.Request. Call each of Radio and Label at most once. Render Label only when Radio is also rendered: Label emits a for="..." referencing the radio's id, so a Label without its Radio points at an input that is absent from the document. The radio Element it created is still unregistered by the Template that owns it (see RequestWriter.RadioGroup) when that template next replaces its content. With no template owner it has no DOM node for a removal to report either, so it stays registered until the jaws.Request ends.

func (re RadioElement) Label(params ...any) template.HTML

func (re RadioElement) Radio(params ...any) template.HTML

type Range ¶

type Range struct {
	Input
	// contains filtered or unexported fields
}

Range renders an HTML range input.

A Range value must back at most one live jaws.Element. Construct distinct Range values over the same source to render one bound value more than once. Construct a Range with NewRange; using its zero value as a widget panics. Editable Ranges send live browser input while their thumb moves.

func NewRange[T Numeric](source bind.Getter[T]) *Range

func (u *Range) JawsInput(elem *jaws.Element, text string) error

func (u *Range) JawsRender(elem *jaws.Element, w io.Writer, params []any) (err error)

func (u *Range) JawsUpdate(elem *jaws.Element)

type RequestWriter ¶

type RequestWriter struct {
	*jaws.Request
	io.Writer
	// contains filtered or unexported fields
}

RequestWriter combines a jaws.Request with an io.Writer while rendering.

func (rw RequestWriter) A(innerHTML any, params ...any) error

func (rw RequestWriter) Button(innerHTML any, params ...any) error

func (rw RequestWriter) Checkbox(value any, params ...any) error

func (rw RequestWriter) Container(outerHTMLTag string, children jaws.Container, params ...any) error

func (rw RequestWriter) Date(value any, params ...any) error

func (rw RequestWriter) Div(innerHTML any, params ...any) error

func (rw RequestWriter) Get(key string) (value any)

func (rw RequestWriter) HeadHTML() error

func (rw RequestWriter) Img(imageSrc any, params ...any) error

func (rw RequestWriter) Initial() *http.Request

func (rw RequestWriter) JsVar(jsvarName string, jsvar any, params ...any) (err error)

func (rw RequestWriter) Label(innerHTML any, params ...any) error

func (rw RequestWriter) Li(innerHTML any, params ...any) error

func (rw RequestWriter) NewElement(ui jaws.UI) *jaws.Element

func (rw RequestWriter) NewUI(ui jaws.UI, params ...any) (err error)

func (rw RequestWriter) Number(value any, params ...any) error

func (rw RequestWriter) Password(value any, params ...any) error

func (rw RequestWriter) Radio(value any, params ...any) error

func (rw RequestWriter) RadioGroup(nba *named.BoolArray) (rel []RadioElement)

func (rw RequestWriter) Range(value any, params ...any) error

rw.Range(floatBinder, `min="0"`, `max="200"`, `step="0.5"`)

func (rw RequestWriter) Register(updater jaws.Updater, params ...any) jid.Jid

<div id="{{$.Register .MyUpdater}}">...</div>

func (rw RequestWriter) Select(handler named.SelectHandler, params ...any) error

func (rw RequestWriter) Session() *jaws.Session

func (rw RequestWriter) Set(key string, value any)

func (rw RequestWriter) Span(innerHTML any, params ...any) error

func (rw RequestWriter) TailHTML() error

func (rw RequestWriter) Tbody(children jaws.Container, params ...any) error

func (rw RequestWriter) Td(innerHTML any, params ...any) error

func (rw RequestWriter) Template(outerHTMLTag, name string, dot any, params ...any) error

func (rw RequestWriter) Text(value any, params ...any) error

func (rw RequestWriter) Textarea(value any, params ...any) error

func (rw RequestWriter) Tr(innerHTML any, params ...any) error

func (rw RequestWriter) Write(p []byte) (n int, err error)

type Select ¶

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

Select renders a single-selection HTML select element.

Its handler supplies the options and represents the selection as a string. Option values must be non-empty. A string that matches no option value represents no selection. named.BoolArray is the standard handler and requires non-empty named.Bool.Name values.

The handler's dynamic value defines Select's identity and must be comparable and equal to itself. Rebuilding with an equal handler lets a parent retain its live Element. Keep application state containing a slice, map, or function behind a stable pointer and synchronize access to it.

Equal Select values may back multiple live jaws.Element values in one jaws.Request when the handler is safe for all calls and each option UI value reused across those Elements supports multiple live Elements. Use Select as a value; taking its address changes identity and is unsupported.

A typed-nil handler is called normally and must tolerate its nil receiver.

Select supports one selected option; a multiple select is unsupported. A completed native form reset changes browser state without an input/change event, so it does not update the Go binding. Reset the authoritative selection from a JaWS-handled button with type="button", then dirty its tag.

func NewSelect(handler named.SelectHandler) Select

func (u Select) JawsInput(elem *jaws.Element, value string) (err error)

func (u Select) JawsRender(elem *jaws.Element, w io.Writer, params []any) (err error)

func (u Select) JawsUpdate(elem *jaws.Element)

type SetPather ¶

type SetPather interface {
	// JawsPathSet notifies that a JSON object member identified by jsPath has been set
	// to the given value and the change has been queued for broadcast.
	//
	// Unlike [PathSetter.JawsSetPath], a [JsVar] calls this after releasing
	// its lock, so locking the JsVar or calling its locked accessors is
	// allowed here.
	JawsPathSet(elem *jaws.Element, jsPath string, value any)
}

SetPather is notified after a nested JSON path value has been set and broadcast.

type Span ¶

type Span struct{ HTMLInner }

Span renders an HTML span element with dynamic inner HTML.

One Span value may back multiple live jaws.Element values. Its HTML getter is shared by those Elements and must be safe for their render, update and event calls.

func NewSpan(innerHTML any) *Span

func (u *Span) JawsRender(elem *jaws.Element, w io.Writer, params []any) error

type Tbody ¶

type Tbody struct {
	Container
}

Tbody renders an HTML tbody containing dynamic child rows.

NewTbody configures its embedded Container for tbody. Replacing that Container is unsupported. Tbody otherwise follows Container's identity, reconciliation, multiplicity, and typed-nil-provider behavior. Treat it as immutable after use and use it as a value; taking its address changes identity and is unsupported.

func NewTbody(children jaws.Container) Tbody

type Td ¶

type Td struct{ HTMLInner }

Td renders an HTML table cell with dynamic inner HTML.

One Td value may back multiple live jaws.Element values. Its HTML getter is shared by those Elements and must be safe for their render, update and event calls.

func NewTd(innerHTML any) *Td

func (u *Td) JawsRender(elem *jaws.Element, w io.Writer, params []any) error

type Template ¶

type Template struct {
	OuterHTMLTag string // Wrapper element; empty renders unwrapped and disables JawsUpdate.
	Name         string // Template name to be looked up using Jaws.LookupTemplate.
	Dot          any    // Template data, tag source, event delegate, and initial-attribute source.
}

Template renders a named Go html/template partial through JaWS.

Use Templates as values; NewTemplate is the usual constructor for wrapped Templates. A Template may back multiple live jaws.Element values in one jaws.Request; its Dot and callbacks must support all of their render, update, and event calls. Taking a Template's address is unsupported because it changes container reuse from value identity to pointer identity.

Dot may be a nil interface. Otherwise the Template must be comparable at runtime and equal to itself, and Dot must be usable as a tag under tag.TagExpand.

If Dot implements jaws.InitialHTMLAttrHandler, its callback supplies wrapper attributes separately for each wrapped Element's initial render. An unwrapped Template has no attribute target and does not invoke the callback. The callback is not invoked during Template.JawsUpdate.

OuterHTMLTag names the wrapper that receives the JaWS ID and render-time HTML attributes from render parameters and Dot. Render-parameter attributes take precedence when Dot returns an attribute with the same name. An empty field renders without a wrapper, making Template.JawsUpdate a no-op. NewTemplate defaults an empty wrapper argument to "div". The named template must be a partial; use Handler for a complete document.

A Template owns the Elements created through its RequestWriter. A successful update unregisters Elements from the previous execution. Elements created by a failed execution are also unregistered.

Replacing wrapper contents reports all managed descendants being removed in one WebSocket message, subject to jaws.Request.ServeHTTP's 32 KiB inbound limit. Split large trees into independently updated nested wrappers.

Execution is not transactional. An error may leave partial output, queued messages, or application side effects in place.

package main

import (
	"bytes"
	"fmt"
	"html/template"
	"strings"

	"github.com/linkdata/jaws"
	"github.com/linkdata/jaws/lib/tag"
	"github.com/linkdata/jaws/lib/ui"
)

func main() {
	tmpl := template.Must(template.New("partial").Parse(`before {{.Dot}} {{call .Missing}} after`))
	jw, err := jaws.New()
	if err != nil {
		panic(err)
	}
	defer jw.Close()
	if err = jw.AddTemplateLookuper(tmpl); err != nil {
		panic(err)
	}
	rq := jw.NewRequest(nil)
	elem := rq.NewElement(ui.NewTemplate("div", "partial", tag.Tag("dot")))

	var out bytes.Buffer
	err = elem.JawsRender(&out, nil)
	fmt.Println(strings.Contains(out.String(), `id="Jid.1"`))
	fmt.Println(strings.Contains(out.String(), "before dot"))
	fmt.Println(err != nil)

}

Output:
true
true
true

func NewTemplate(outerHTMLTag, name string, dot any) Template

package main

import (
	"fmt"

	"github.com/linkdata/jaws/lib/tag"
	"github.com/linkdata/jaws/lib/ui"
)

func main() {
	tmpl := ui.NewTemplate("", "partial", tag.Tag("dot"))
	fmt.Println(tmpl.OuterHTMLTag)

}

Output:
div

func (tmpl Template) JawsClick(elem *jaws.Element, click jaws.Click) (err error)

func (tmpl Template) JawsContextMenu(elem *jaws.Element, click jaws.Click) (err error)

func (tmpl Template) JawsInput(elem *jaws.Element, value string) (err error)

func (tmpl Template) JawsRender(elem *jaws.Element, w io.Writer, params []any) (err error)

func (tmpl Template) JawsUpdate(elem *jaws.Element)

func (tmpl Template) String() string

type Text ¶

type Text struct{ InputText }

Text renders an HTML text input bound to a string setter.

A Text value must back at most one live jaws.Element. Construct distinct Text values over the same setter to render one bound value more than once.

func NewText(g bind.Setter[string]) *Text

func (u *Text) JawsRender(elem *jaws.Element, w io.Writer, params []any) error

type Textarea ¶

type Textarea struct{ InputText }

Textarea renders an HTML textarea bound to a string setter.

A Textarea value must back at most one live jaws.Element. Construct distinct Textarea values over the same setter to render one bound value more than once.

While the WebSocket is open, each input event sends the complete value in one message. The value plus protocol and JSON overhead must fit the 32 KiB inbound limit documented by jaws.Request.ServeHTTP. Use a conservative maxlength or a separate upload endpoint for potentially large text.

func NewTextarea(g bind.Setter[string]) *Textarea

func (u *Textarea) JawsRender(elem *jaws.Element, w io.Writer, params []any) (err error)

type Tr ¶

type Tr struct{ HTMLInner }

Tr renders an HTML table row with dynamic inner HTML.

One Tr value may back multiple live jaws.Element values. Its HTML getter is shared by those Elements and must be safe for their render, update and event calls.

func NewTr(innerHTML any) *Tr

func (u *Tr) JawsRender(elem *jaws.Element, w io.Writer, params []any) error

type With ¶

type With struct {
	*jaws.Element     // the Element being rendered using a template
	RequestWriter     // the RequestWriter for nested UI helpers
	Dot           any // user data parameter
	// Auth is the authentication information from [jaws.Jaws.MakeAuth]. When
	// MakeAuth is nil it is a [jaws.DefaultAuth], whose IsAdmin returns true for
	// everyone — gating UI on {{if .Auth.IsAdmin}} is only safe once MakeAuth is
	// set. See [jaws.DefaultAuth] for the fail-open caveat.
	Auth jaws.Auth
}

With is passed as the data parameter when using RequestWriter.Template, populated with all required members set.