widget

README

tinywasm/widget

Visual component contracts, states, layout, and styling for the tinywasm suite.

Usage

package main

import (
	"github.com/tinywasm/fmt"
	"github.com/tinywasm/widget"
	"github.com/tinywasm/widget/style"
)

type MasterDetail struct{}

func (m *MasterDetail) WidgetName() widget.Name { return widget.Name("masterdetail") }
func (m *MasterDetail) WidgetKind() widget.Kind { return widget.Grid }

func (m *MasterDetail) Style() *style.Sheet {
	return style.For(m).
		Root(style.Grid(style.ColumnNarrow, style.Space2), style.As(style.Page), style.Scroll()).
		Part("master", style.Stack(style.Space1), style.As(style.Panel), style.Pad(style.Space3)).
		Part("detail", style.Stack(style.Space2), style.As(style.Panel), style.Pad(style.Space3)).
		Part("item",   style.Row(style.Space1),   style.Interactive(style.Subtle)).
		When(widget.Selected, "item", style.As(style.Highlight))
}

func main() {
	m := &MasterDetail{}
	fmt.Println(m.Style().Stylesheet().String())
}

Documentation

• AGENTS.md — constraints for anyone (human or agent) changing this library: the WASM boundary, zero escape, never invent a value, and the SSR contract every style builder must satisfy.
• GUIDE.md — task-oriented decision guide and standard scales.
• docs/ARCHITECTURE.md — package boundaries (WASM / non-WASM), anatomy and state contracts, and CSS emission guarantees.
• docs/SPECS.md — exact public surface, scale-to-token mappings, emission tables, and validation conditions.
• docs/DESIGN.md — the reasoning behind each decision and the alternatives rejected.
• docs/TRADEOFFS.md — what the architecture buys, what it costs, and the limitations it accepts.
• docs/MIGRATION.md — moving a consumer to the closed API.
• docs/diagrams/BOUNDARIES.md — how css, widget and ssr divide the problem, and the WASM boundary.

Documentation

Overview

Package widget defines visual component contracts, states, and layout.

It travels inside the WASM binary, so it carries zero style logic and zero emission.

Index

• Constants
• type Class
  • func (c Class) AsAttr() fmt.KeyValue
  • func (c Class) String() string
• type Cue
• type Dismissible
• type Expandable
• type Kind
  • func (k Kind) Allows(s State) bool
  • func (k Kind) Layer() Layer
  • func (k Kind) Role() fmt.KeyValue
  • func (k Kind) String() string
• type Layer
• type Name
  • func (n Name) Class(p Part) Class
  • func (n Name) Root() Class
• type Part
• type Selectable
• type State
  • func (s State) Attr() fmt.KeyValue
  • func (s State) String() string
• type Widget

Constants

const (
	PartLabel      = Part("label")
	PartInput      = Part("input")
	PartError      = Part("error")
	PartRadioGroup = Part("radio-group")
)

Parts of the field. The names are generic by design: Part is local to its widget and only becomes a class through a Name, so "label" here produces "tw-field__label" and never collides with the "label" of another widget.

const NameField = Name("tw-field")

NameField is the shared anatomy of the form field.

It is emitted by github.com/tinywasm/form (which builds the markup) and styled by github.com/tinywasm/components/fieldset (which is the global skin of the forms). It lives here because it crosses the boundary between these two libraries, and neither can own it without the other depending on it.

Types

type Class

type Class string

Class is a CSS class name. It has NO public constructor: the only way to obtain one is to derive it from a Name. This ensures markup and stylesheet agree by construction.

func (Class) AsAttr

func (c Class) AsAttr() fmt.KeyValue

func (Class) String

func (c Class) String() string

type Cue

type Cue uint8

Cue is a state that the BROWSER possesses. It is only styled; it cannot be written from Go — which is why it is a separate type and has no Attr().

const (
	Hover Cue = iota
	Focus
	Press
	Target
)

type Dismissible

type Dismissible interface{ Dismiss() }

type Expandable

type Expandable interface{ Expand(open bool) }

type Kind

type Kind uint8

Kind is the type of widget according to WAI-ARIA Authoring Practices. It determines the role, valid states, and expected keyboard interactions. Closed by design: if a widget does not fit any pattern, it is almost always two widgets.

const (
	Region Kind = iota
	Listbox
	Menu
	Dialog
	Disclosure
	Tabs
	Toolbar
	Grid
	Combobox
	Form
	Alert
)

func (Kind) Allows

func (k Kind) Allows(s State) bool

Allows returns whether the given state is meaningful for the Kind.

func (Kind) Layer

func (k Kind) Layer() Layer

Layer returns the stacking level of the Kind.

func (Kind) Role

func (k Kind) Role() fmt.KeyValue

Role returns the ARIA role of the Kind as a KeyValue attribute.

func (Kind) String

func (k Kind) String() string

type Layer

type Layer uint8

Layer is the stacking level of a pattern. It is an enum, not a css.Token: this package travels inside the WASM binary and must not import css. widget/style maps it to the --z-* catalog.

const (
	LayerBase Layer = iota
	LayerDropdown
	LayerSticky
	LayerModal
	LayerToast
	LayerTooltip
)

type Name

type Name string

Name identifies a widget. It is the prefix of EVERY class it emits, so two widgets cannot collide even if they choose the same part name.

func (Name) Class

func (n Name) Class(p Part) Class

Class derives the class of an anatomical part: e.g. "targetlist__row".

func (Name) Root

func (n Name) Root() Class

Root is the outer class of the widget.

type Part

type Part string

Part is a named slot of a widget's anatomy (Open UI vocabulary). It is local to the widget: e.g. "row", "menu", "header". It never carries a prefix.

type Selectable

type Selectable interface{ Select(id string) }

Capabilities — each hook asserts only the capability it needs.

type State

type State uint8

State is a state that the widget POSSESSES: written by Go, read by the stylesheet.

const (
	Selected State = iota
	Disabled
	Locked // read-only, but fully legible
	Invalid
	Busy
	Open    // deployed / expanded
	Current // active navigation item
)

func (State) Attr

func (s State) Attr() fmt.KeyValue

Attr returns the attribute that the DOM writes and upon which the stylesheet selects. Markup and CSS match by construction, not by convention.

func (State) String

func (s State) String() string

type Widget

type Widget interface {
	WidgetName() Name
	WidgetKind() Kind
}

Widget is the identity. It is the only mandatory interface.