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
- type Choice
- type Handle
- 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 ¶
This section is empty.
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 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