components

type AlertProps struct {
	ComponentProps

	Message     string `json:"message"`
	Title       string `json:"title,omitempty"`
	Tone        string `json:"tone,omitempty"` // neutral, info, success, warning, danger (default info)
	Dismissible bool   `json:"dismissible,omitempty"`
	Bordered    bool   `json:"bordered,omitempty"`
	Compact     bool   `json:"compact,omitempty"`
}

type BadgeProps struct {
	ComponentProps

	Label       string `json:"label"`
	Variant     string `json:"variant,omitempty"` // primary, secondary, outline
	Tone        string `json:"tone,omitempty"`    // neutral, brand, success, warning, danger, info
	Size        string `json:"size,omitempty"`    // xs, sm, md, lg, xl, 2xl
	Dot         bool   `json:"dot,omitempty"`     // show status dot before the label
	Count       int    `json:"count,omitempty"`   // positive count, visually capped to 99+
	Removable   bool   `json:"removable,omitempty"`
	RemoveLabel string `json:"removeLabel,omitempty"` // localized remove-button label
	Live        bool   `json:"live,omitempty"`        // polite status announcement
}

type BadgeSlots struct {
	IconStart []g.Node
	IconEnd   []g.Node
}

type BreadcrumbItem struct {
	Label   string `json:"label"`
	Href    string `json:"href,omitempty"` // empty = current page
	Icon    string `json:"icon,omitempty"`
	Current bool   `json:"current,omitempty"`
}

type BreadcrumbProps struct {
	ComponentProps
	HTMXProps

	Items     []BreadcrumbItem `json:"items"`
	Separator string           `json:"separator,omitempty"` // default "/"
	MaxItems  int              `json:"maxItems,omitempty"`  // collapse middle items
}

type ButtonProps struct {
	ComponentProps
	HTMXProps

	Label     string `json:"label"`
	Href      string `json:"href,omitempty"`    // renders an anchor with button styling when set
	Variant   string `json:"variant,omitempty"` // primary, secondary, outline, ghost, link
	Tone      string `json:"tone,omitempty"`    // neutral, brand, success, warning, danger, info
	Size      string `json:"size,omitempty"`    // xs, sm, md, lg, xl, 2xl
	Type      string `json:"type,omitempty"`    // button, submit, reset
	Loading   bool   `json:"loading,omitempty"`
	FullWidth bool   `json:"fullWidth,omitempty"`
	IconOnly  bool   `json:"iconOnly,omitempty"`
	AriaLabel string `json:"ariaLabel,omitempty"`
}

type ButtonSlots struct {
	IconStart []g.Node
	IconEnd   []g.Node
	Content   []g.Node
}

type CardProps struct {
	ComponentProps
	HTMXProps

	Title         string `json:"title,omitempty"`
	Description   string `json:"description,omitempty"`
	Image         string `json:"image,omitempty"`
	ImageAlt      string `json:"imageAlt,omitempty"`
	ImagePosition string `json:"imagePosition,omitempty"` // top, bottom, left, right
	Variant       string `json:"variant,omitempty"`       // default, elevated, outlined, plain
	Padding       string `json:"padding,omitempty"`       // none, small, medium, large
	Shadow        string `json:"shadow,omitempty"`        // none, small, medium, large
	Clickable     bool   `json:"clickable,omitempty"`
	Hoverable     bool   `json:"hoverable,omitempty"`
	Href          string `json:"href,omitempty"`
}

type CardSlots struct {
	Header  []g.Node
	Content []g.Node
	Footer  []g.Node
}

type CheckboxProps struct {
	ComponentProps

	Name          string `json:"name"`
	Label         string `json:"label,omitempty"`
	Checked       bool   `json:"checked,omitempty"`
	Indeterminate bool   `json:"indeterminate,omitempty"`
	Value         string `json:"value,omitempty"`
	Required      bool   `json:"required,omitempty"`
	HelpText      string `json:"helpText,omitempty"`
}

type ComponentProps struct {
	// ID is supplied by the component-tree transport, not authored as a
	// component property in design manifests or A2UI schemas.
	ID string `json:"id,omitempty" delivery:"internal"`
	// Class is a renderer escape hatch for trusted Go composition. It is not a
	// portable design-system property and is therefore excluded from delivery.
	Class    string `json:"class,omitempty" delivery:"internal"`
	Disabled bool   `json:"disabled,omitempty"`
	Hidden   bool   `json:"hidden,omitempty"`
	// Attrs is restricted to trusted direct-render callers; portable contracts
	// expose explicit typed properties instead of arbitrary HTML attributes.
	Attrs map[string]string `json:"attrs,omitempty" delivery:"internal"`
}

type ConfirmDialogProps struct {
	ComponentProps
	Title       string
	AcceptLabel string
	CancelLabel string
}

type ContainerProps struct {
	ComponentProps

	MaxWidth string `json:"maxWidth,omitempty"` // sm, md, lg, xl, 2xl, full
	Padding  string `json:"padding,omitempty"`
}

type DetailItem struct {
	Label       string `json:"label"`
	Value       string `json:"value"`
	Description string `json:"description,omitempty"`
	Tone        string `json:"tone,omitempty"` // neutral, brand, success, warning, danger, info
}

type DetailListProps struct {
	ComponentProps

	Title        string       `json:"title,omitempty"`
	Description  string       `json:"description,omitempty"`
	SemanticRole string       `json:"semanticRole,omitempty"`
	Items        []DetailItem `json:"items"`
}

type DividerProps struct {
	ComponentProps

	Orientation string `json:"orientation,omitempty"` // horizontal, vertical
	Text        string `json:"text,omitempty"`        // optional label (e.g., "OR")
}

type EmptyStateProps struct {
	ComponentProps

	Title       string `json:"title,omitempty"`
	Description string `json:"description,omitempty"`
	Compact     bool   `json:"compact,omitempty"`
	Bordered    bool   `json:"bordered,omitempty"`
}

type Example struct {
	// Group is the heading it appears under.
	Group string
	// Name is the component and the variant, "Button / primary".
	Name string
	Node g.Node
}

type FlexProps struct {
	ComponentProps

	Direction string `json:"direction,omitempty"` // row, column
	Wrap      bool   `json:"wrap,omitempty"`
	Gap       string `json:"gap,omitempty"`
	Align     string `json:"align,omitempty"`   // start, center, end, stretch
	Justify   string `json:"justify,omitempty"` // start, center, end, between, around
}

type FormActionsProps struct{ ComponentProps }

type FormProps struct {
	ComponentProps
	HTMXProps
	Action string
	// Label names the form for assistive technology, since a generated form
	// has no visible heading of its own.
	Label string
}

type GridProps struct {
	ComponentProps

	Columns string `json:"columns,omitempty"` // Tailwind grid-cols value
	Gap     string `json:"gap,omitempty"`
}

type HTMXProps struct {
	Get         string `json:"hx-get,omitempty"`
	Post        string `json:"hx-post,omitempty"`
	Put         string `json:"hx-put,omitempty"`
	Patch       string `json:"hx-patch,omitempty"`
	Delete      string `json:"hx-delete,omitempty"`
	Target      string `json:"hx-target,omitempty"`
	Swap        string `json:"hx-swap,omitempty"`
	Trigger     string `json:"hx-trigger,omitempty"`
	Include     string `json:"hx-include,omitempty"`
	Confirm     string `json:"hx-confirm,omitempty"`
	Ext         string `json:"hx-ext,omitempty"`
	Indicator   string `json:"hx-indicator,omitempty"`
	DisabledElt string `json:"hx-disabled-elt,omitempty"`
	Vals        string `json:"hx-vals,omitempty"`
	PushURL     string `json:"hx-push-url,omitempty"`
	Select      string `json:"hx-select,omitempty"`
	Boost       bool   `json:"hx-boost,omitempty"`
	Disable     bool   `json:"hx-disable,omitempty"`
}

type HeadingProps struct {
	ComponentProps

	Text     string `json:"text"`
	Level    int    `json:"level"`            // 1-6
	Anchor   string `json:"anchor,omitempty"` // optional anchor ID
	Truncate bool   `json:"truncate,omitempty"`
}

type IconProps struct {
	ComponentProps

	Name      string `json:"name"`
	Size      string `json:"size,omitempty"`   // xs, sm, md, lg, xl, 2xl
	Tone      string `json:"tone,omitempty"`   // neutral, brand, success, warning, danger, info
	Weight    string `json:"weight,omitempty"` // outline; extension providers may add governed weights
	AriaLabel string `json:"ariaLabel,omitempty"`
}

type InputProps struct {
	ComponentProps
	HTMXProps

	Name string `json:"name"`
	Type string `json:"type,omitempty"` // text, email, password, number, tel, url, search, date, time, file
	// Value is what the control starts with. A file input never carries one:
	// no browser lets a page choose a file for somebody.
	Value        string `json:"value,omitempty"`
	Placeholder  string `json:"placeholder,omitempty"`
	Label        string `json:"label,omitempty"`
	HelpText     string `json:"helpText,omitempty"`
	Error        string `json:"error,omitempty"`
	Invalid      bool   `json:"invalid,omitempty"`
	Required     bool   `json:"required,omitempty"`
	ReadOnly     bool   `json:"readOnly,omitempty"`
	AutoFocus    bool   `json:"autoFocus,omitempty"`
	Min          string `json:"min,omitempty"`
	Max          string `json:"max,omitempty"`
	Step         string `json:"step,omitempty"`
	MinLength    int    `json:"minLength,omitempty"`
	MaxLength    int    `json:"maxLength,omitempty"`
	Pattern      string `json:"pattern,omitempty"`
	Autocomplete string `json:"autocomplete,omitempty"`
	Size         string `json:"size,omitempty"` // sm, md, lg
	Tone         string `json:"tone,omitempty"` // neutral, success, warning, danger
	FullWidth    bool   `json:"fullWidth,omitempty"`

	// Accept and Multiple belong to Type "file" and are ignored elsewhere.
	// Accept is the browser's filter — "image/*", or a comma-separated list of
	// extensions and media types — and it is a courtesy to the person choosing,
	// never a check: what a form actually accepts is decided by whatever reads
	// the upload. Multiple lets them choose more than one.
	Accept   string `json:"accept,omitempty"`
	Multiple bool   `json:"multiple,omitempty"`
}

type LabelProps struct {
	ComponentProps

	Text     string `json:"text"`
	For      string `json:"for,omitempty"` // associated input ID
	Required bool   `json:"required,omitempty"`
}

type LinkProps struct {
	ComponentProps
	HTMXProps

	Label    string `json:"label"`
	Href     string `json:"href"`
	External bool   `json:"external,omitempty"` // opens in new tab
	Variant  string `json:"variant,omitempty"`  // primary, secondary, text, underline
	Target   string `json:"target,omitempty"`
	Rel      string `json:"rel,omitempty"`
}

type ModalProps struct {
	ComponentProps

	Title       string `json:"title,omitempty"`
	Description string `json:"description,omitempty"`
	Body        string `json:"body,omitempty"`
	Footer      string `json:"footer,omitempty"`
	AriaLabel   string `json:"ariaLabel,omitempty"`
	CloseLabel  string `json:"closeLabel,omitempty"`
	Size        string `json:"size,omitempty"` // small, medium, large, xl, full

	// Pointer booleans preserve the intended default-true behavior while still
	// allowing portable clients to explicitly disable an affordance.
	Closable       *bool `json:"closable,omitempty"`
	CloseOnOverlay *bool `json:"closeOnOverlay,omitempty"`
	CloseOnEscape  *bool `json:"closeOnEscape,omitempty"`
	ShowClose      *bool `json:"showClose,omitempty"`
	ShowOverlay    *bool `json:"showOverlay,omitempty"`
	Centered       *bool `json:"centered,omitempty"`
	ClearOnClose   *bool `json:"clearOnClose,omitempty"`
	Open           bool  `json:"open,omitempty"`
	OpenOnSwap     bool  `json:"openOnSwap,omitempty"`
	Deferred       bool  `json:"deferred,omitempty"`
}

type ModalSlots struct {
	Header []g.Node
	Body   []g.Node
	Footer []g.Node
}

type PaginationProps struct {
	ComponentProps
	HTMXProps

	CurrentPage int `json:"currentPage"`
	TotalPages  int `json:"totalPages"`
	// Siblings is how many pages are shown either side of the current one.
	Siblings int    `json:"siblings,omitempty"`
	BaseURL  string `json:"baseURL,omitempty"`
	// NavigationLabel names this landmark, for a page carrying more than one.
	NavigationLabel string `json:"navigationLabel,omitempty"`
}

type SelectOption struct {
	Label       string `json:"label"`
	Value       string `json:"value"`
	Description string `json:"description,omitempty"`
	Group       string `json:"group,omitempty"`
	Disabled    bool   `json:"disabled,omitempty"`
}

type SelectProps struct {
	ComponentProps
	HTMXProps

	Name        string         `json:"name"`
	Label       string         `json:"label,omitempty"`
	Value       string         `json:"value,omitempty"`
	Values      []string       `json:"values,omitempty"`
	Placeholder string         `json:"placeholder,omitempty"` // rendered as a disabled-free empty option
	Options     []SelectOption `json:"options"`
	Required    bool           `json:"required,omitempty"`
	Multiple    bool           `json:"multiple,omitempty"`
	VisibleRows int            `json:"visibleRows,omitempty"`
	FullWidth   bool           `json:"fullWidth,omitempty"`
	HelpText    string         `json:"helpText,omitempty"`
	Error       string         `json:"error,omitempty"`
}

type ShellProps struct {
	ComponentProps
	// SkipTarget is the id the skip link jumps to; the main region takes it.
	//
	// There is no SkipLabel beside it. One existed and nothing ever set it: a
	// skip link says "Skip to content" in every application that has one, and a
	// prop nobody writes is a prop every reader of this struct has to rule out.
	SkipTarget string
}

type ShellSlots struct {
	Sidebar []g.Node
	Header  []g.Node
	Main    []g.Node
	Footer  []g.Node
}

type SidebarItem struct {
	ID           string            `json:"id,omitempty"`
	Label        string            `json:"label"`
	Href         string            `json:"href,omitempty"`
	Icon         string            `json:"icon,omitempty"`
	Prefix       string            `json:"prefix,omitempty"`
	Badge        string            `json:"badge,omitempty"`
	BadgeVariant string            `json:"badgeVariant,omitempty"`
	Active       bool              `json:"active,omitempty"`
	Disabled     bool              `json:"disabled,omitempty"`
	SearchText   string            `json:"searchText,omitempty"`
	Attrs        map[string]string `json:"-" delivery:"internal"`
	Children     []SidebarItem     `json:"children,omitempty"`
}

type SidebarProps struct {
	ComponentProps

	Items           []SidebarItem    `json:"items,omitempty"`
	Sections        []SidebarSection `json:"sections,omitempty"`
	Current         string           `json:"current,omitempty"`
	Flavor          string           `json:"flavor,omitempty"` // admin, content
	Collapsible     bool             `json:"collapsible,omitempty"`
	Collapsed       bool             `json:"collapsed,omitempty"`
	NavigationLabel string           `json:"navigationLabel,omitempty"`
	BrandLabel      string           `json:"brandLabel,omitempty"`
	BrandHref       string           `json:"brandHref,omitempty"`
}

type SidebarSection struct {
	ID         string        `json:"id,omitempty"`
	Label      string        `json:"label,omitempty"`
	Glyph      string        `json:"glyph,omitempty"`
	Tone       string        `json:"tone,omitempty"` // neutral, brand, success, warning, danger, info
	SearchText string        `json:"searchText,omitempty"`
	Items      []SidebarItem `json:"items,omitempty"`
}

type SidebarSlots struct {
	Brand  []g.Node
	Items  []g.Node
	Footer []g.Node
}

type SkeletonProps struct {
	ComponentProps

	Shape string `json:"shape,omitempty"` // block, text, circle
	Size  string `json:"size,omitempty"`  // sm, md, lg
	Lines int    `json:"lines,omitempty"` // shape=text: placeholder line count (default 1)
}

type SpinnerProps struct {
	ComponentProps

	Label string `json:"label,omitempty"` // sr-only text
	Size  string `json:"size,omitempty"`  // xs, sm, md, lg, xl, 2xl
	Tone  string `json:"tone,omitempty"`  // neutral, brand, success, warning, danger, info (default brand)
}

type StackProps struct {
	ComponentProps

	Gap   string `json:"gap,omitempty"`
	Align string `json:"align,omitempty"` // start, center, end, stretch
}

type TabItem struct {
	Key      string `json:"key"`
	Label    string `json:"label"`
	Icon     string `json:"icon,omitempty"`
	Badge    string `json:"badge,omitempty"`
	Disabled bool   `json:"disabled,omitempty"`
	Content  string `json:"content,omitempty"` // static panel content for direct rendering
	URL      string `json:"url,omitempty"`     // navigation target in item mode
	HxGet    string `json:"hxGet,omitempty"`   // lazy-panel endpoint in panel mode
}

type TabSlot struct {
	ID       string
	Label    string
	Icon     string
	Badge    string
	Disabled bool
	HxGet    string
	Content  []g.Node
}

type TableColumn struct {
	Key      string `json:"key"`
	Label    string `json:"label"`
	Sortable bool   `json:"sortable,omitempty"`
	Primary  bool   `json:"primary,omitempty"` // emphasized identity cell
	Width    string `json:"width,omitempty"`
	Align    string `json:"align,omitempty"` // left, center, right
}

type TableProps struct {
	ComponentProps
	HTMXProps

	Columns    []TableColumn `json:"columns"`
	Rows       []TableRow    `json:"rows,omitempty"`
	Sortable   bool          `json:"sortable,omitempty"`
	Selectable bool          `json:"selectable,omitempty"`
	Striped    bool          `json:"striped,omitempty"`
	Compact    bool          `json:"compact,omitempty"`
	EmptyText  string        `json:"emptyText,omitempty"`
}

type TableRow struct {
	ID    string         `json:"id,omitempty"`
	Cells map[string]any `json:"cells"`
}

type TableSkeletonProps struct {
	ComponentProps

	Columns int  `json:"columns,omitempty"` // header/cell count (default 4)
	Rows    int  `json:"rows,omitempty"`    // placeholder row count (default 3)
	Compact bool `json:"compact,omitempty"`
}

type TableSlots struct {
	Cell             func(TableRow, TableColumn) g.Node
	CellAttrs        func(TableRow, TableColumn) []g.Node
	RowAttrs         func(TableRow) []g.Node
	SortURL          func(TableColumn) string
	SortState        func(TableColumn) string
	SortButtonAttrs  func(TableColumn) []g.Node
	SelectAllLabel   string
	SelectRowLabel   func(TableRow) string
	SelectRowChecked func(TableRow) bool
}

type TabsProps struct {
	ComponentProps

	Items        []TabItem `json:"items,omitempty"`
	ActiveTab    string    `json:"activeTab,omitempty"`
	Orientation  string    `json:"orientation,omitempty"` // horizontal, vertical
	Variant      string    `json:"variant,omitempty"`     // underline, pills
	HxGet        string    `json:"hxGet,omitempty"`       // default lazy-panel endpoint
	LoadingLabel string    `json:"loadingLabel,omitempty"`
}

type TabsSlots struct {
	Tabs []TabSlot
}

type TextProps struct {
	ComponentProps

	Content   string `json:"content"`
	Element   string `json:"element,omitempty"`   // p, span, div, strong, em, small, mark, del, ins, sub, sup, blockquote, code, pre, kbd, samp, var
	Size      string `json:"size,omitempty"`      // xs, sm, base, lg, xl, 2xl, 3xl, 4xl, 5xl
	Align     string `json:"align,omitempty"`     // left, center, right, justify
	Weight    string `json:"weight,omitempty"`    // thin, extralight, light, normal, medium, semibold, bold, extrabold, black
	Color     string `json:"color,omitempty"`     // primary, secondary, tertiary, muted, brand, success, warning, danger, info
	Transform string `json:"transform,omitempty"` // none, uppercase, lowercase, capitalize
	Truncate  bool   `json:"truncate,omitempty"`  // truncate with ellipsis
	NoWrap    bool   `json:"nowrap,omitempty"`
	Italic    bool   `json:"italic,omitempty"`
	Underline bool   `json:"underline,omitempty"`
	Lines     int    `json:"lines,omitempty"` // line clamp, 1-6
}

type TextareaProps struct {
	ComponentProps
	HTMXProps

	Name         string `json:"name"`
	Placeholder  string `json:"placeholder,omitempty"`
	Value        string `json:"value,omitempty"`
	Label        string `json:"label,omitempty"`
	HelperText   string `json:"helperText,omitempty"`
	ErrorMessage string `json:"errorMessage,omitempty"`
	Required     bool   `json:"required,omitempty"`
	ReadOnly     bool   `json:"readOnly,omitempty"`
	Rows         int    `json:"rows,omitempty"`
	MinRows      int    `json:"minRows,omitempty"`
	MaxRows      int    `json:"maxRows,omitempty"`
	MinLength    int    `json:"minLength,omitempty"`
	MaxLength    int    `json:"maxLength,omitempty"`
	ShowCount    bool   `json:"showCount,omitempty"`
	AutoResize   bool   `json:"autoResize,omitempty"`
	FullWidth    bool   `json:"fullWidth,omitempty"`
}

type ToolbarProps struct {
	ComponentProps
	Title    string
	Subtitle string
}