input

package
v0.1.7 Latest Latest
Warning

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

 Go to latest Published: Aug 5, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Overview

Package input provides the Vibrant Gio form controls — TextField, Checkbox, Radio and Dropdown — on the same contract as prism/button: an rx.Observable[theme.Theme] and a props struct in, an rx.Observable[layout.Widget] out, with a matching pure Render, RenderCheckbox, RenderRadio and RenderDropdown path that takes resolved tokens and an explicit render state and draws one frame without handling events.

Reach for it for form input inside an MVU or FRP layer. Every control reports both ways: through a Props callback — OnChange, OnSubmit — which is handed the frame's layout.Context so it can emit a message from inside the callback, or through Props.Message, which adds an mvu.MessageOp to the frame's ops for the runtime to deliver to Update.

Elevation (goal G-E2): the controls themselves are flat — the text field, checkbox and radio inner fills and the closed dropdown trigger paint the plain Surface token, sitting in the page plane. The one raised plane in the package is the dropdown's open option menu, a floating unscrimmed, shadowless transient overlay: its rows fill at SurfaceAt(Level3) (Neutral step 400), the same rung cadence/popover takes, and the selected row composes its D2.3 state walk on that level's step.

The text field is uncontrolled. Props.Seed pre-fills a newly created instance so an existing value can be edited rather than retyped, but a later Seed does not touch a live instance — rebuild the field, keyed on an epoch, to reseed it. TextField and Dropdown draw text in the theme's BodyLarge role, shaped with the theme's shaper (Typography.Shaper()); Props.Shaper is an explicit per-instance override for the rare case where one control must shape with a different shaper than the theme provides. Checkbox and Radio draw no text and need no shaper.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Checkbox 

func Checkbox(th rx.Observable[theme.Theme], props CheckboxProps) rx.Observable[layout.Widget]

Checkbox returns an rx.Observable[layout.Widget] that emits a new widget whenever the theme or disabled state changes. Widget state (checked value, focus) lives in the rx.Defer scope and persists across emissions.

Both integration paths are supported:

  • FRP: set CheckboxProps.OnChange.
  • MVU: set CheckboxProps.Message; the component emits mvu.MessageOp on toggle.
func Dropdown(th rx.Observable[theme.Theme], props DropdownProps) rx.Observable[layout.Widget]

Dropdown returns an rx.Observable[layout.Widget] that emits a new widget whenever the theme or disabled state changes. Widget state (open/closed, selected index, focus) lives in the rx.Defer scope and persists across emissions.

Both integration paths are supported:

  • FRP: set DropdownProps.OnSelect.
  • MVU: set DropdownProps.Message; the component emits mvu.MessageOp on selection.

func Radio 

func Radio(th rx.Observable[theme.Theme], props RadioProps) rx.Observable[layout.Widget]

Radio returns an rx.Observable[layout.Widget] that emits a new widget whenever the theme or disabled state changes. Widget state (selected value, focus) lives in the rx.Defer scope and persists across emissions.

Both integration paths are supported:

  • FRP: set RadioProps.OnChange.
  • MVU: set RadioProps.Message; the component emits mvu.MessageOp on toggle.

func Render 

func Render(
	shaper *text.Shaper,
	placeholder string,
	colors tokens.ColorTokens,
	sp tokens.SpacingScale,
	rad tokens.RadiusScale,
	ts tokens.TypeScale,
	s RenderState,
) layout.Widget

Render produces a layout.Widget for a text field in an explicit visual state, without any event processing or rx machinery. Intended for golden-image testing and static demonstrations; production code should use TextField, which takes the shaper and the BodyLarge text style from the theme's Typography. The TypeScale parameter contributes only the BodyLarge size; typeface, weight and line height stay at the shaper's defaults. Density is not a parameter (the signature predates E1.3): the static path renders at tokens.Comfortable; density-aware rendering goes through TextField.

func RenderCheckbox 

func RenderCheckbox(
	colors tokens.ColorTokens,
	sp tokens.SpacingScale,
	rad tokens.RadiusScale,
	s CheckboxRenderState,
) layout.Widget

RenderCheckbox produces a layout.Widget for a checkbox in an explicit visual state, without any event processing or rx machinery. Intended for golden-image testing and static demonstrations; production code should use Checkbox.

func RenderDropdown 

func RenderDropdown(
	shaper *text.Shaper,
	colors tokens.ColorTokens,
	sp tokens.SpacingScale,
	rad tokens.RadiusScale,
	ts tokens.TypeScale,
	s DropdownRenderState,
) layout.Widget

RenderDropdown produces a layout.Widget for a dropdown in an explicit visual state, without any event processing or rx machinery. Intended for golden-image testing and static demonstrations; production code should use Dropdown, which takes the shaper and the BodyLarge text style from the theme's Typography. The TypeScale parameter contributes only the BodyLarge size; typeface, weight and line height stay at the shaper's defaults.

func RenderRadio 

func RenderRadio(
	colors tokens.ColorTokens,
	sp tokens.SpacingScale,
	rad tokens.RadiusScale,
	s RadioRenderState,
) layout.Widget

RenderRadio produces a layout.Widget for a radio button in an explicit visual state, without any event processing or rx machinery. Intended for golden-image testing and static demonstrations; production code should use Radio.

func TextField 

func TextField(th rx.Observable[theme.Theme], props TextFieldProps) rx.Observable[layout.Widget]

TextField returns an rx.Observable[layout.Widget] that emits a new widget whenever the theme or disabled state changes. Widget state (editor content, focus) lives in the rx.Defer scope and persists across emissions.

Both integration paths are supported:

  • FRP: set TextFieldProps.OnChange; FRP consumers wrap with rx.NewSubject if needed.
  • MVU: set TextFieldProps.Message; the component emits mvu.MessageOp on text change.

Types

type CheckboxProps 

type CheckboxProps struct {
	// Description is the screen-reader label.
	Description string

	// Checked is the initial checked state established on subscribe.
	Checked bool

	// Disabled, if non-nil, disables the checkbox when it emits true.
	Disabled rx.Observable[bool]

	// OnChange is called with the new checked value on every toggle.
	// This is the FRP callback path. The gtx argument is the layout.Context
	// active on the frame when the toggle is processed, allowing consumers to
	// emit mvu.MessageOp{Message: ...}.Add(gtx.Ops) inside the callback.
	OnChange func(gtx layout.Context, checked bool)

	// Message, if non-nil, causes the checkbox to emit mvu.MessageOp{Message}
	// on every toggle. This is the MVU integration path.
	Message any
}

CheckboxProps configures a Checkbox instance.

type CheckboxRenderState 

type CheckboxRenderState struct {
	Checked  bool
	Focused  bool
	Disabled bool
}

CheckboxRenderState holds explicit visual state for static rendering. All fields default to false (normal/unchecked/idle). Intended for golden-image testing; production code obtains state from the Gio event system via Checkbox. 

type DropdownProps struct {
	// Description is the screen-reader label.
	Description string

	// Options is the list of selectable items.
	Options []string

	// Selected is the initial selected index established on subscribe.
	Selected int

	// Disabled, if non-nil, disables the dropdown when it emits true.
	Disabled rx.Observable[bool]

	// OnSelect is called with the newly selected index on every selection.
	// This is the FRP callback path. The gtx argument is the layout.Context
	// active on the frame when the selection is processed, allowing consumers to
	// emit mvu.MessageOp{Message: ...}.Add(gtx.Ops) inside the callback.
	OnSelect func(gtx layout.Context, index int)

	// Message, if non-nil, causes the dropdown to emit mvu.MessageOp{Message}
	// on every selection. This is the MVU integration path.
	Message any

	// Shaper is an explicit per-instance override of the text shaper. Leave it
	// nil in normal use: the dropdown then shapes its text with the theme's
	// shaper (Typography.Shaper()), which is built once and cached inside the
	// theme's Typography value. Set it only when this dropdown must shape with
	// a different shaper than the theme provides.
	Shaper *text.Shaper
}

DropdownProps configures a Dropdown instance. 

type DropdownRenderState struct {
	Open     bool
	Focused  bool
	Disabled bool
	Selected int
	Options  []string
}

DropdownRenderState holds explicit visual state for static rendering. All fields default to their zero values (normal/closed/idle). Intended for golden-image testing; production code obtains state from the Gio event system via Dropdown.

type RadioProps 

type RadioProps struct {
	// Description is the screen-reader label.
	Description string

	// Selected is the initial selected state established on subscribe.
	Selected bool

	// Disabled, if non-nil, disables the radio when it emits true.
	Disabled rx.Observable[bool]

	// OnChange is called with the new selected value on every toggle.
	// This is the FRP callback path. The gtx argument is the layout.Context
	// active on the frame when the toggle is processed, allowing consumers to
	// emit mvu.MessageOp{Message: ...}.Add(gtx.Ops) inside the callback.
	OnChange func(gtx layout.Context, selected bool)

	// Message, if non-nil, causes the radio to emit mvu.MessageOp{Message}
	// on every toggle. This is the MVU integration path.
	Message any
}

RadioProps configures a Radio instance.

type RadioRenderState 

type RadioRenderState struct {
	Selected bool
	Focused  bool
	Disabled bool
}

RadioRenderState holds explicit visual state for static rendering. All fields default to false (normal/unselected/idle). Intended for golden-image testing; production code obtains state from the Gio event system via Radio.

type RenderState 

type RenderState struct {
	Focused  bool
	Disabled bool
	// Text, when non-empty, is rendered in place of the placeholder using the
	// text colour. It models a field that holds user input for the static
	// render path; it has no effect on the live TextField, whose text is held
	// by the inner widget.Editor.
	Text string
}

RenderState holds explicit visual interaction state for static rendering. All fields default to false (normal/idle state). Intended for golden-image testing; production code obtains state from the Gio event system via TextField.

type TextFieldProps 

type TextFieldProps struct {
	// Placeholder is shown when the field is empty and unfocused.
	Placeholder string

	// Description is the screen-reader label. Falls back to Placeholder when empty.
	Description string

	// Seed, when non-empty, pre-fills the editor when the field instance is
	// created, so an existing value can be EDITED rather than retyped. The
	// field stays uncontrolled: later Seed values have no effect on a live
	// instance — rebuild the field (e.g. keyed on an epoch, the modal-form
	// pattern) to reseed it.
	Seed string

	// FocusTag, if non-nil, is called once when the field instance is
	// created, with the editor's focus tag — for callers that manage a
	// focus cycle (e.g. cadence/modal's Tab trap) and need to include the
	// field in it. A rebuilt field (new epoch) calls it again with the new
	// instance's tag.
	FocusTag func(tag event.Tag)

	// Mask, when non-zero, hides the entered text by rendering every rune as
	// this one (e.g. '•' for a password or secret field). The unmasked value is
	// still delivered through OnChange/Message and the editor's Text(); only the
	// on-screen display is obscured. The placeholder is never masked.
	Mask rune

	// Disabled, if non-nil, disables the field when it emits true.
	Disabled rx.Observable[bool]

	// OnChange is called with the new value on every text change.
	// This is the FRP callback path. The gtx argument is the layout.Context
	// active on the frame when the change is processed, allowing consumers to
	// emit mvu.MessageOp{Message: ...}.Add(gtx.Ops) inside the callback.
	OnChange func(gtx layout.Context, text string)

	// Message, if non-nil, causes the field to emit mvu.MessageOp{Message}
	// on every text change. This is the MVU integration path.
	Message any

	// Submit, when true, configures the inner widget.Editor to translate
	// carriage-return key presses into widget.SubmitEvent rather than
	// inserting newlines. Required for chat-style inputs.
	Submit bool

	// SubmitMessage, if non-nil, is invoked on each submit and its return
	// value is wrapped in mvu.MessageOp and emitted on the current frame.
	SubmitMessage func(text string) any

	// OnSubmit, if non-nil, is invoked on each submit with the editor's
	// current text. After both callbacks run the editor is cleared.
	// The gtx argument is the layout.Context active on the frame when the
	// submit is processed, allowing consumers to emit
	// mvu.MessageOp{Message: ...}.Add(gtx.Ops) inside the callback.
	OnSubmit func(gtx layout.Context, text string)

	// Shaper is an explicit per-instance override of the text shaper. Leave it
	// nil in normal use: the field then shapes its text with the theme's
	// shaper (Typography.Shaper()), which is built once and cached inside the
	// theme's Typography value. Set it only when this field must shape with
	// a different shaper than the theme provides.
	Shaper *text.Shaper
}

TextFieldProps configures a TextField instance.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.