Documentation
¶
Overview ¶
Package events manages global, transient UI requests. It owns presentation lifecycle and response arbitration; callers retain ownership of domain work.
Index ¶
- Constants
- Variables
- func RendersKind(r Renderer, kind models.UIEventKind) bool
- func RendersOverMedia(r Renderer) bool
- type Choice
- type Handle
- type KindRenderer
- type OverMediaRenderer
- type Publisher
- type Renderer
- type Request
- type Result
- type Service
- func (s *Service) Cancel(id string) error
- func (s *Service) Open(ctx context.Context, request *Request) (*Handle, error)
- func (s *Service) Respond(id string, action models.UIResponseAction, choiceID string) error
- func (s *Service) Shutdown()
- func (s *Service) State() models.UIStateResponse
- func (s *Service) Update(id string, update Update) error
- type TimedRenderer
- type Update
- type UpdatingRenderer
Constants ¶
const ( MaxTitleBytes = 512 MaxMessageBytes = 16 * 1024 MaxChoices = 1000 MaxLabelBytes = 512 )
Variables ¶
var ( ErrClosed = errors.New("UI event service is closed") ErrNoActiveEvent = errors.New("no active UI event") ErrEventNotActive = errors.New("UI event is not active") ErrInvalidKind = errors.New("invalid UI event kind") ErrInvalidAction = errors.New("invalid UI response action") ErrNotDismissible = errors.New("UI event is not dismissible") ErrChoiceRequired = errors.New("choice ID is required") ErrChoiceNotFound = errors.New("UI choice was not found") ErrInvalidRequest = errors.New("invalid UI event request") ErrInvalidOutcome = errors.New("invalid UI event outcome") ErrEventExpired = errors.New("UI event has expired") )
Functions ¶
func RendersKind ¶ added in v2.21.0
func RendersKind(r Renderer, kind models.UIEventKind) bool
RendersKind reports whether r exists and shows events of kind. A nil renderer shows nothing; one that does not say which kinds it shows is assumed to show them all.
func RendersOverMedia ¶ added in v2.21.0
RendersOverMedia reports whether r can show an event while media is running without disturbing it. A nil renderer shows nothing.
Types ¶
type Choice ¶
Choice combines public display text with a private caller-owned value. Value is returned only to producer and is never serialized into public event.
type Handle ¶
type Handle struct {
Results <-chan Result
ID string
MinimumDisplay time.Duration
// contains filtered or unexported fields
}
Handle lets producer update or complete request it opened.
type KindRenderer ¶ added in v2.21.0
type KindRenderer interface {
RendersUIKind(models.UIEventKind) bool
}
KindRenderer is optionally implemented by a Renderer that shows only some kinds of event, so callers can tell whether a kind will reach the screen. A Renderer without it is taken to show every kind.
type OverMediaRenderer ¶ added in v2.21.0
type OverMediaRenderer interface {
RendersOverMedia() bool
}
OverMediaRenderer is optionally implemented by a Renderer that cannot show an event while media is running without disturbing it, such as one whose display replaces the running program. A Renderer without it is taken to show events over running media without harm.
type Publisher ¶
type Publisher func(models.UIStateResponse)
Publisher broadcasts an authoritative UI state snapshot.
type Renderer ¶
type Renderer interface {
PresentUI(context.Context, *models.UIEvent) (closeFn func() error, err error)
}
Renderer presents UI events on the host platform. Renderer failure never cancels an event because remote clients remain valid fallback renderers.
type Request ¶
type Request struct {
Kind models.UIEventKind
Title string
Message string
Choices []Choice
// SelectedChoice is picker choice index. Zero selects first choice; use -1
// explicitly when no choice should be preselected.
SelectedChoice int
Timeout time.Duration
Dismissible bool
// SkipHostRenderer keeps the request available to API clients without
// presenting it through the platform renderer.
SkipHostRenderer bool
}
Request describes one transient UI interaction. A positive Timeout creates authoritative expiry; zero or negative values leave event open until resolved.
type Result ¶
type Result struct {
Value any
Resolution models.UIResolution
}
Result is delivered once when an external response, timeout, cancellation, or supersession resolves request. Value contains private selected choice value.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service owns current global UI event and arbitrates all terminal outcomes.
func New ¶
New creates UI event service. Nil clock uses real time. Renderer and publisher may be nil for headless use and tests.
func (*Service) Respond ¶
Respond atomically resolves current event from API or host renderer input.
func (*Service) Shutdown ¶
func (s *Service) Shutdown()
Shutdown prevents new events and cancels active request, if present.
func (*Service) State ¶
func (s *Service) State() models.UIStateResponse
State returns immutable current snapshot. Resolved is always empty for query.
type TimedRenderer ¶
type TimedRenderer interface {
MinimumUIDisplay(models.UIEventKind) time.Duration
}
TimedRenderer reports minimum time a producer should keep a newly presented event open before completing it. This accommodates host UI startup latency.
Source Files