a2ui

package
v0.0.0-...-8acab51 Latest Latest
Warning

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

Go to latest
Published: Apr 26, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package a2ui provides Agent-to-UI (A2UI) capabilities for dynamic UI generation. A2UI allows AI agents to generate interactive UI components that can be rendered by the frontend, enabling rich interactions beyond simple text responses.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Action

type Action struct {
	// ID is the unique identifier for this action.
	ID string `json:"id"`
	// Type is the action type (click, submit, change, etc.).
	Type string `json:"type"`
	// Label is the display label for the action.
	Label string `json:"label,omitempty"`
	// Handler is the handler name to invoke when action is triggered.
	Handler string `json:"handler"`
	// Params contains parameters to pass to the handler.
	Params map[string]interface{} `json:"params,omitempty"`
	// Confirm contains confirmation dialog settings.
	Confirm *ConfirmDialog `json:"confirm,omitempty"`
}

Action represents an interactive action that can be triggered by a component.

type ActionHandler

type ActionHandler func(ctx context.Context, action Action, formData map[string]interface{}) (*ActionResult, error)

ActionHandler is a function that handles an action.

type ActionResult

type ActionResult struct {
	// Success indicates if the action was successful.
	Success bool `json:"success"`
	// Data contains the result data.
	Data interface{} `json:"data,omitempty"`
	// Error contains the error message if failed.
	Error string `json:"error,omitempty"`
	// UpdatedComponents contains components to update after action.
	UpdatedComponents []Component `json:"updated_components,omitempty"`
	// NewCanvas contains a new canvas to render (replaces current).
	NewCanvas *Canvas `json:"new_canvas,omitempty"`
}

ActionResult represents the result of an action execution.

type Builder

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

Builder provides a fluent interface for building UI components.

func NewBuilder

func NewBuilder(componentType ComponentType) *Builder

NewBuilder creates a new component builder.

func (*Builder) Action

func (b *Builder) Action(action Action) *Builder

Action adds an action to the component.

func (*Builder) Build

func (b *Builder) Build() Component

Build returns the built component.

func (*Builder) Child

func (b *Builder) Child(child Component) *Builder

Child adds a child component.

func (*Builder) Children

func (b *Builder) Children(children ...Component) *Builder

Children adds multiple child components.

func (*Builder) ID

func (b *Builder) ID(id string) *Builder

ID sets the component ID.

func (*Builder) Prop

func (b *Builder) Prop(key string, value interface{}) *Builder

Prop sets a component property.

func (*Builder) Props

func (b *Builder) Props(props map[string]interface{}) *Builder

Props sets multiple properties.

func (*Builder) Style

func (b *Builder) Style(key string, value interface{}) *Builder

Style sets a style property.

func (*Builder) Styles

func (b *Builder) Styles(styles map[string]interface{}) *Builder

Styles sets multiple style properties.

func (*Builder) Validation

func (b *Builder) Validation(validation *Validation) *Builder

Validation sets validation rules.

type Canvas

type Canvas struct {
	// ID is the unique identifier for this canvas.
	ID string `json:"id"`
	// Title is the canvas title.
	Title string `json:"title,omitempty"`
	// Description is the canvas description.
	Description string `json:"description,omitempty"`
	// Components contains the root-level components.
	Components []Component `json:"components"`
	// Layout specifies the layout type (vertical, horizontal, grid).
	Layout string `json:"layout,omitempty"`
	// Metadata contains additional canvas metadata.
	Metadata map[string]interface{} `json:"metadata,omitempty"`
	// CreatedAt is when the canvas was created.
	CreatedAt time.Time `json:"created_at"`
	// ExpiresAt is when the canvas expires (optional).
	ExpiresAt *time.Time `json:"expires_at,omitempty"`
}

Canvas represents a collection of UI components to be rendered.

func FromJSON

func FromJSON(data []byte) (*Canvas, error)

FromJSON parses a canvas from JSON.

func (*Canvas) ToJSON

func (c *Canvas) ToJSON() ([]byte, error)

ToJSON converts a canvas to JSON.

func (*Canvas) UnmarshalJSON

func (c *Canvas) UnmarshalJSON(data []byte) error

type Component

type Component struct {
	// ID is the unique identifier for this component.
	ID string `json:"id"`
	// Type is the component type.
	Type ComponentType `json:"type"`
	// Props contains component-specific properties.
	Props map[string]interface{} `json:"props,omitempty"`
	// Children contains nested components.
	Children []Component `json:"children,omitempty"`
	// Actions contains interactive actions for this component.
	Actions []Action `json:"actions,omitempty"`
	// Style contains CSS-like styling properties.
	Style map[string]interface{} `json:"style,omitempty"`
	// Validation contains validation rules for input components.
	Validation *Validation `json:"validation,omitempty"`
}

Component represents a UI component that can be rendered by the frontend.

func Alert

func Alert(id, alertType, message string) Component

Alert creates an alert component.

func Button

func Button(id, label, handler string) Component

Button creates a button component.

func Card

func Card(id, title string, children ...Component) Component

Card creates a card component.

func Code

func Code(id, language, code string) Component

Code creates a code block component.

func Form

func Form(id, submitHandler string, children ...Component) Component

Form creates a form component.

func Grid

func Grid(id string, columns int, children ...Component) Component

Grid creates a grid layout component.

func Image

func Image(id, src, alt string) Component

Image creates an image component.

func Input

func Input(id, label, placeholder string) Component

Input creates an input component.

func List

func List(id string, items []string) Component

List creates a list component.

func Markdown

func Markdown(id, content string) Component

Markdown creates a markdown component.

func Progress

func Progress(id string, value, max int) Component

Progress creates a progress component.

func Select

func Select(id, label string, options []map[string]interface{}) Component

Select creates a select component.

func Table

func Table(id string, columns []string, rows [][]interface{}) Component

Table creates a table component.

func Text

func Text(id, content string) Component

Text creates a text component.

type ComponentType

type ComponentType string

ComponentType represents the type of UI component.

const (
	// ComponentTypeText represents a text display component.
	ComponentTypeText ComponentType = "text"
	// ComponentTypeButton represents a clickable button.
	ComponentTypeButton ComponentType = "button"
	// ComponentTypeInput represents a text input field.
	ComponentTypeInput ComponentType = "input"
	// ComponentTypeSelect represents a dropdown select.
	ComponentTypeSelect ComponentType = "select"
	// ComponentTypeCheckbox represents a checkbox.
	ComponentTypeCheckbox ComponentType = "checkbox"
	// ComponentTypeRadio represents radio buttons.
	ComponentTypeRadio ComponentType = "radio"
	// ComponentTypeSlider represents a slider input.
	ComponentTypeSlider ComponentType = "slider"
	// ComponentTypeImage represents an image display.
	ComponentTypeImage ComponentType = "image"
	// ComponentTypeCard represents a card container.
	ComponentTypeCard ComponentType = "card"
	// ComponentTypeList represents a list of items.
	ComponentTypeList ComponentType = "list"
	// ComponentTypeTable represents a data table.
	ComponentTypeTable ComponentType = "table"
	// ComponentTypeChart represents a chart/graph.
	ComponentTypeChart ComponentType = "chart"
	// ComponentTypeForm represents a form container.
	ComponentTypeForm ComponentType = "form"
	// ComponentTypeProgress represents a progress indicator.
	ComponentTypeProgress ComponentType = "progress"
	// ComponentTypeAlert represents an alert/notification.
	ComponentTypeAlert ComponentType = "alert"
	// ComponentTypeCode represents a code block.
	ComponentTypeCode ComponentType = "code"
	// ComponentTypeMarkdown represents markdown content.
	ComponentTypeMarkdown ComponentType = "markdown"
	// ComponentTypeContainer represents a generic container.
	ComponentTypeContainer ComponentType = "container"
	// ComponentTypeGrid represents a grid layout.
	ComponentTypeGrid ComponentType = "grid"
	// ComponentTypeTabs represents tabbed content.
	ComponentTypeTabs ComponentType = "tabs"
	// ComponentTypeAccordion represents collapsible sections.
	ComponentTypeAccordion ComponentType = "accordion"
)

type ConfirmDialog

type ConfirmDialog struct {
	// Title is the dialog title.
	Title string `json:"title"`
	// Message is the confirmation message.
	Message string `json:"message"`
	// ConfirmText is the confirm button text.
	ConfirmText string `json:"confirm_text"`
	// CancelText is the cancel button text.
	CancelText string `json:"cancel_text"`
}

ConfirmDialog represents a confirmation dialog before action execution.

type Handler

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

Handler handles A2UI HTTP requests.

func NewHandler

func NewHandler(manager *Manager) *Handler

NewHandler creates a new A2UI handler.

func (*Handler) CreateCanvas

func (h *Handler) CreateCanvas(c echo.Context) error

CreateCanvas creates a new canvas.

func (*Handler) DeleteCanvas

func (h *Handler) DeleteCanvas(c echo.Context) error

DeleteCanvas deletes a canvas.

func (*Handler) ExecuteAction

func (h *Handler) ExecuteAction(c echo.Context) error

ExecuteAction executes an action on a canvas.

func (*Handler) GetCanvas

func (h *Handler) GetCanvas(c echo.Context) error

GetCanvas returns a canvas by ID.

func (*Handler) ListCanvases

func (h *Handler) ListCanvases(c echo.Context) error

ListCanvases returns all canvas IDs.

func (*Handler) RegisterRoutes

func (h *Handler) RegisterRoutes(g *echo.Group)

RegisterRoutes registers the A2UI routes.

func (*Handler) UpdateCanvas

func (h *Handler) UpdateCanvas(c echo.Context) error

UpdateCanvas updates an existing canvas.

type Manager

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

Manager manages A2UI canvases and action handlers.

func NewManager

func NewManager(logger *zap.Logger) *Manager

NewManager creates a new A2UI manager.

func (*Manager) CleanupExpired

func (m *Manager) CleanupExpired() int

CleanupExpired removes expired canvases.

func (*Manager) CreateCanvas

func (m *Manager) CreateCanvas(canvas *Canvas) error

CreateCanvas creates and stores a new canvas.

func (*Manager) DeleteCanvas

func (m *Manager) DeleteCanvas(id string)

DeleteCanvas removes a canvas.

func (*Manager) ExecuteAction

func (m *Manager) ExecuteAction(ctx context.Context, canvasID string, actionID string, formData map[string]interface{}) (*ActionResult, error)

ExecuteAction executes an action and returns the result.

func (*Manager) GetCanvas

func (m *Manager) GetCanvas(id string) (*Canvas, error)

GetCanvas retrieves a canvas by ID.

func (*Manager) ListCanvases

func (m *Manager) ListCanvases() []string

ListCanvases returns all active canvas IDs.

func (*Manager) RegisterHandler

func (m *Manager) RegisterHandler(name string, handler ActionHandler)

RegisterHandler registers an action handler.

func (*Manager) UnregisterHandler

func (m *Manager) UnregisterHandler(name string)

UnregisterHandler removes an action handler.

func (*Manager) UpdateCanvas

func (m *Manager) UpdateCanvas(canvas *Canvas) error

UpdateCanvas updates an existing canvas.

type Validation

type Validation struct {
	// Required indicates if the field is required.
	Required bool `json:"required,omitempty"`
	// MinLength is the minimum string length.
	MinLength int `json:"min_length,omitempty"`
	// MaxLength is the maximum string length.
	MaxLength int `json:"max_length,omitempty"`
	// Min is the minimum numeric value.
	Min *float64 `json:"min,omitempty"`
	// Max is the maximum numeric value.
	Max *float64 `json:"max,omitempty"`
	// Pattern is a regex pattern for validation.
	Pattern string `json:"pattern,omitempty"`
	// Message is the validation error message.
	Message string `json:"message,omitempty"`
}

Validation represents validation rules for input components.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL