uispec

package
v0.8.0 Latest Latest
Warning

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

 Go to latest Published: Sep 26, 2026 License: MIT Imports: 1 Imported by: 0

Documentation

Overview

Package uispec defines the canonical UISpec type system — the JSON IR for declarative UI composition. Go structs are the source of truth; JSON Schemas are generated from these types.

Index

Constants

View Source 
const (
	CapabilityDataRead   = "data.read"
	CapabilityStateWrite = "state.write"
)

Well-known capability names. Capabilities are open-vocabulary strings — hosts may define their own — but these are the ones UIForge's own machinery understands: the renderers' data runtime refuses connector fetches without CapabilityDataRead when a grant set is in force, and state-writing form controls check CapabilityStateWrite.

View Source 
const (
	LayoutResponsiveGrid   = "responsive-grid"
	LayoutStack            = "stack"
	LayoutSplitPane        = "split-pane"
	LayoutTabs             = "tabs"
	LayoutApplicationShell = "application-shell"
)
View Source 
const (
	APIVersion = "ui.plexusone.dev/v1"
	KindPage   = "Page"
)
View Source 
const (
	ProfileDashboard   = "dashboard"
	ProfileApplication = "application"
	ProfileAgent       = "agent"
	ProfilePortal      = "portal"
	ProfileEmbedded    = "embedded"
)

Variables

View Source 
var ValidThemeTokenKeys = []string{
	"primary",
	"secondary",
	"accent",
	"danger",
	"warning",
	"success",
	"info",
	"neutral",
	"surface",
	"background",
	"text",
	"text-muted",
	"text-inverse",
	"border",
	"focus",
	"disabled",
	"shadow",
	"font-family",
	"radius",
}

ValidThemeTokenKeys is UIForge's design-token contract: the semantic color vocabulary (mirroring design-system-spec's ValidSemantics — the theme package guards this equivalence in its tests) plus UIForge's non-color category keys. Renderers surface each key as a --uiforge-<key> CSS custom property; components read only these keys.

Functions

func IsValidThemeToken 

func IsValidThemeToken(key string) bool

IsValidThemeToken reports whether key is part of the design-token contract.

Types

type Binding 

type Binding struct {
	Source     string         `json:"source"`
	Operation  string         `json:"operation,omitempty"`
	Parameters map[string]any `json:"parameters,omitempty"`
	Transform  string         `json:"transform,omitempty"`
	Default    any            `json:"default,omitempty"`
}

Binding connects a component property to a data source.

type BreakpointConfig 

type BreakpointConfig struct {
	MinWidth int    `json:"minWidth"`
	Columns  int    `json:"columns,omitempty"`
	Gap      string `json:"gap,omitempty"`
}

BreakpointConfig adjusts layout at different viewport widths.

type CapabilitySpec 

type CapabilitySpec struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	Required    bool   `json:"required,omitempty"`
}

CapabilitySpec declares permissions a component requires.

type ComponentInstance 

type ComponentInstance struct {
	ID         string              `json:"id"`
	Type       string              `json:"type"`
	Version    string              `json:"version,omitempty"`
	Position   *Position           `json:"position,omitempty"`
	Properties map[string]any      `json:"properties,omitempty"`
	Data       map[string]Binding  `json:"data,omitempty"`
	Children   []ComponentInstance `json:"children,omitempty"`
	Visibility *VisibilityRule     `json:"visibility,omitempty"`
	Slot       string              `json:"slot,omitempty"`
	Style      map[string]string   `json:"style,omitempty"`
	RawConfig  json.RawMessage     `json:"rawConfig,omitempty"`
}

ComponentInstance represents a placed component on a page.

type Interaction 

type Interaction struct {
	When InteractionTrigger  `json:"when"`
	Then []InteractionAction `json:"then"`
}

Interaction defines a declarative event→condition→action rule.

type InteractionAction 

type InteractionAction struct {
	Target    string         `json:"target"`
	Action    string         `json:"action"`
	Value     any            `json:"value,omitempty"`
	Condition string         `json:"condition,omitempty"`
	Params    map[string]any `json:"params,omitempty"`
}

InteractionAction describes what happens when the trigger fires.

type InteractionTrigger 

type InteractionTrigger struct {
	Component string `json:"component"`
	Event     string `json:"event"`
}

InteractionTrigger identifies the source event.

type LayoutConfig 

type LayoutConfig struct {
	Columns     int                         `json:"columns,omitempty"`
	Rows        int                         `json:"rows,omitempty"`
	Gap         string                      `json:"gap,omitempty"`
	Direction   string                      `json:"direction,omitempty"`
	Breakpoints map[string]BreakpointConfig `json:"breakpoints,omitempty"`
	Sizes       []string                    `json:"sizes,omitempty"`
	Resizable   bool                        `json:"resizable,omitempty"`
}

LayoutConfig holds type-specific layout parameters.

type LayoutRegion 

type LayoutRegion struct {
	Name     string      `json:"name"`
	Layout   *LayoutSpec `json:"layout,omitempty"`
	MinWidth string      `json:"minWidth,omitempty"`
	MaxWidth string      `json:"maxWidth,omitempty"`
	Default  string      `json:"default,omitempty"`
}

LayoutRegion defines a named slot within a layout.

type LayoutSpec 

type LayoutSpec struct {
	Type    string         `json:"type"`
	Config  *LayoutConfig  `json:"config,omitempty"`
	Regions []LayoutRegion `json:"regions,omitempty"`
}

LayoutSpec defines how components are arranged on a page. 

type NavItem struct {
	ID       string    `json:"id"`
	Label    string    `json:"label"`
	Icon     string    `json:"icon,omitempty"`
	Target   string    `json:"target,omitempty"`
	Children []NavItem `json:"children,omitempty"`
	Badge    string    `json:"badge,omitempty"`
}

NavItem is a single navigation entry. 

type NavigationSpec struct {
	Type       string    `json:"type,omitempty"`
	Items      []NavItem `json:"items,omitempty"`
	Breadcrumb []NavItem `json:"breadcrumb,omitempty"`
}

NavigationSpec defines page-level navigation (menus, sidebars, breadcrumbs). Field names follow the implemented cross-renderer contract: "type" (e.g. "sidebar") and per-item "target" hrefs.

type PageMetadata 

type PageMetadata struct {
	ID          string            `json:"id"`
	Name        string            `json:"name"`
	Title       string            `json:"title,omitempty"`
	Description string            `json:"description,omitempty"`
	Version     string            `json:"version,omitempty"`
	Labels      map[string]string `json:"labels,omitempty"`
}

PageMetadata holds identity and descriptive fields.

type PageSpec 

type PageSpec struct {
	APIVersion   string              `json:"apiVersion"`
	Kind         string              `json:"kind"`
	Metadata     PageMetadata        `json:"metadata"`
	Profile      string              `json:"profile,omitempty"`
	Context      map[string]string   `json:"context,omitempty"`
	Layout       LayoutSpec          `json:"layout"`
	Components   []ComponentInstance `json:"components"`
	Interactions []Interaction       `json:"interactions,omitempty"`
	Navigation   *NavigationSpec     `json:"navigation,omitempty"`
	Theme        *ThemeRef           `json:"theme,omitempty"`
}

PageSpec is the top-level document describing a single composable page.

type Position 

type Position struct {
	Row     int    `json:"row,omitempty"`
	Col     int    `json:"col,omitempty"`
	RowSpan int    `json:"rowSpan,omitempty"`
	ColSpan int    `json:"colSpan,omitempty"`
	Order   int    `json:"order,omitempty"`
	Region  string `json:"region,omitempty"`
}

Position places a component within a grid or flex layout.

type ProfileConstraints 

type ProfileConstraints struct {
	Name              string   `json:"name"`
	AllowedLayouts    []string `json:"allowedLayouts"`
	AllowedNamespaces []string `json:"allowedNamespaces"`
	RequiredSlots     []string `json:"requiredSlots,omitempty"`
	MaxDepth          int      `json:"maxDepth,omitempty"`
	// AllowedCapabilities restricts which capabilities components used under
	// this profile may declare. nil means unrestricted; a non-nil list means
	// every capability a component's manifest declares must appear in it.
	AllowedCapabilities []string `json:"allowedCapabilities,omitempty"`
}

ProfileConstraints defines what a profile permits.

type ThemeRef 

type ThemeRef struct {
	ID      string            `json:"id"`
	Variant string            `json:"variant,omitempty"`
	Tokens  map[string]string `json:"tokens,omitempty"`
	// Modes holds per-mode token overlays (e.g. "light", "dark"). At render
	// time the active mode's overlay is applied on top of Tokens; Variant
	// names the default mode, and renderers can switch modes at runtime.
	Modes map[string]map[string]string `json:"modes,omitempty"`

	// Density selects the active spacing density by ID — any key present in
	// Densities (e.g. "comfortable", "compact", or a document-specific name
	// like "spacious"). Renderers surface it as a data-uiforge-density
	// attribute. A density with no matching Densities entry is invalid.
	Density string `json:"density,omitempty"`
	// Densities holds every declared density's spacing scale multiplier,
	// keyed by ID — resolved from a design system's foundations by
	// theme.FromDesignSystemWithModes. Renderers look up densities[density]
	// for the --uiforge-density CSS custom property, falling back to 1 when
	// absent.
	Densities map[string]float64 `json:"densities,omitempty"`
}

ThemeRef references a design-system theme for the page.

type VisibilityRule 

type VisibilityRule struct {
	Condition  string   `json:"condition"`
	Roles      []string `json:"roles,omitempty"`
	Capability string   `json:"capability,omitempty"`
}

VisibilityRule controls whether a component is rendered.

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.