gomukit

type AcceptSpec struct {
	// Tool is the MCP tool called when the reader accepts (required).
	Tool string
	// Label defaults to "Confirm".
	Label string
	// Args maps tool argument names to their sources. Static and FromRow
	// apply; FromSelection does not — a confirmation has no selection.
	// Ignored when ChatPrompt is set.
	Args map[string]ArgSource
	// ChatPrompt, when set, makes accepting post this text as a user message
	// (ui/message) instead of calling Tool directly, for hosts that answer a
	// view-initiated call without opening the widget behind it. Write it as
	// the request a user would type; the model then makes the call.
	//
	// Named apart from Confirm.Prompt, which is the question put to the
	// reader rather than a message sent on their behalf.
	ChatPrompt string
	// Variant overrides the button styling derived from Severity.
	Variant ActionVariant
	// SuccessMessage is shown in place of the buttons once the call succeeds.
	// Defaults to the tool result's own text.
	SuccessMessage string
}

type Action struct {
	Label string
	// Kind defaults to ActionTool.
	Kind ActionKind
	// Tool is the MCP tool name to call (Kind == ActionTool).
	Tool string
	// Args maps tool argument names to their sources. Ignored when Prompt is
	// set — the model chooses the arguments there.
	Args map[string]ArgSource
	// Prompt, when set, makes the action ask the host to post this text as a
	// user message (ui/message) instead of calling Tool itself. Write it as
	// the request a user would type; the model reads it and decides which
	// tool answers, so Tool documents what the action opens.
	//
	// The text is fixed: it carries no row values, because the model works
	// out which record is meant from the conversation. Only tool actions may
	// set it — a link action already navigates on its own.
	Prompt string
	// HrefKey is the row field holding the URL (Kind == ActionLink).
	HrefKey string
	// Confirm, when set, requires a second confirming click showing this
	// text before the action fires. (Rendered inline: native confirm()
	// dialogs are silently disabled in sandboxed MCP Apps iframes.)
	Confirm string
	Variant ActionVariant
}

type ActionKind string

type ActionVariant string

type Align string

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

type BadgeVariant string

type Brand struct {
	// Name is the application name shown next to the logo. Required unless a
	// logo is set.
	Name string
	// URL is an optional http(s) link opened through the host (ui/openLink);
	// it makes the whole brand clickable.
	URL string
	// LogoSVG is inline <svg> markup. It is author-trusted input, checked
	// only against script-bearing and resource-loading constructs.
	LogoSVG string
	// LogoDataURI is a "data:image/...;base64,..." alternative to LogoSVG.
	LogoDataURI string
	// LogoAlt is the alt text for LogoDataURI. Defaults to Name.
	LogoAlt string
}

type Calendar struct {
	// Min is the earliest selectable date, as "YYYY-MM-DD". Days before it
	// are shown but cannot be picked, and the grid will not travel past the
	// month holding it.
	Min string
	// Max is the latest selectable date, as "YYYY-MM-DD".
	Max string
	// Disabled lists individual days that cannot be picked ("YYYY-MM-DD") —
	// holidays, sold-out days, days already booked. In a range calendar a
	// span may not straddle one.
	Disabled []string
	// DisableWeekends blocks every Saturday and Sunday. It is about the days
	// themselves, not about where the week starts: WeekStartSaturday still
	// blocks the same two days.
	DisableWeekends bool

	// Months is how many months are shown at once. Defaults to 1 for a single
	// date and 2 for a range, which is what makes a span across a month
	// boundary one gesture rather than two. Maximum 4. They sit side by side
	// where the widget has room and wrap under each other where it has not —
	// every month asked for stays on screen, narrow chat pane or not.
	Months int
	// WeekNumbers adds a leading column of ISO 8601 week numbers.
	WeekNumbers bool
	// MonthDropdowns replaces the month caption with month and year
	// dropdowns, so a date years away is two presses rather than a hundred.
	// Use it for dates of birth and anything else far from today.
	MonthDropdowns bool
	// FromYear and ToYear bound the year dropdown. They default to the years
	// of Min and Max, and — where those are unset — to 100 years before and
	// 10 years after the year the document is rendered in.
	FromYear, ToYear int
	// WeekStart overrides the first day of the week. Defaults to the host
	// locale's own first day.
	WeekStart WeekStart

	// StartOn is the month the grid opens on while nothing is selected, as
	// "YYYY-MM-DD" (the day itself is ignored). Defaults to the month holding
	// the selection, or the reader's current month clamped into Min/Max.
	StartOn string

	// Presets are named shortcuts listed beside the grid.
	Presets []DatePreset
}

type CancelSpec struct {
	// Label defaults to "Cancel".
	Label string
}

type Card struct {
	// URI is the widget's ui:// resource URI (required).
	URI string
	// Title is shown in the toolbar and the document title.
	Title string
	// Template describes the card content (required).
	Template CardTemplate

	// RowsKey is the structuredContent key holding the rows array; the card
	// renders rows[0]. Defaults to "rows".
	RowsKey string
	// RowID is the record field used for FromRow action args. Defaults to
	// "id".
	RowID string
	// Empty configures the message shown when no record is present.
	Empty EmptyState

	// InitialData is an optional structuredContent-shaped snapshot baked into
	// the document as a JSON island.
	InitialData map[string]any

	// LoadTool, when set, names a read tool the runtime calls once on load to
	// hydrate the card from fresh data, replacing InitialData. It must return
	// the record under RowsKey.
	LoadTool string
	// LoadArgs are optional static arguments passed to LoadTool.
	LoadArgs map[string]any

	// Brand renders the application logo/name on the widget.
	Brand *Brand
	// Theme overrides gomukit design tokens for this widget.
	Theme *theme.Theme
	// UI overrides resource _meta.ui (CSP, permissions, prefersBorder).
	UI *uispec.ResourceUIMeta
}

type CardContent struct {
	// TextKey is a row field rendered as a paragraph of body text.
	TextKey string
	// Text is fixed body prose, used instead of TextKey.
	Text string
	// Items are the label/value detail rows.
	Items Descriptions
}

type CardFooter struct {
	// TextKey is a row field shown as a footer note.
	TextKey string
	// Text is a fixed footer note, used instead of TextKey.
	Text string
	// Actions renders the footer buttons. FromSelection args are invalid here
	// (they belong to CardList bulk actions).
	Actions []Action
}

type CardHeader struct {
	// TitleKey is the row field shown as the card title (required).
	TitleKey string
	// DescriptionKey is a row field shown under the title.
	DescriptionKey string
	// Description is fixed text shown under the title, used instead of
	// DescriptionKey.
	Description string
	// Badge is a status badge for the header's action slot. Construct it with
	// the Badge column constructor; it is present when its Key is set, and
	// must be a badge column.
	Badge Column
	// Action is a button for the header's action slot, used instead of Badge.
	// FromSelection args are invalid here (they belong to CardList bulk
	// actions).
	Action *Action
}

type CardList struct {
	// URI is the widget's ui:// resource URI (required).
	URI string
	// Title is shown in the toolbar and the document title.
	Title string
	// Template describes how each record renders as a card (required).
	Template CardTemplate

	// RowsKey is the structuredContent key holding the rows array. Defaults
	// to "rows".
	RowsKey string
	// RowID uniquely identifies a record, used for selection and
	// FromRow/FromSelection args. Defaults to "id".
	RowID string

	// PageSize enables client-side pagination when > 0.
	PageSize int
	// PageSizes offers alternative page sizes in a dropdown on the pagination
	// bar. Entries must be > 0 and PageSize must be set; PageSize is added to
	// the list if it is not among them. Empty renders no chooser.
	PageSizes []int
	// LoadMore turns the carousel into a growing strip instead of a paged one:
	// it starts at PageSize records and appends the next PageSize each time
	// the reader activates the "Load more" tile at the end of the strip, which
	// replaces the prev/next pagination bar. Records already scrolled past stay
	// where they are, so the strip reads as one continuous run.
	//
	// Requires PageSize > 0, and cannot be combined with PageSizes: the page
	// size chooser lives on the bar this removes.
	LoadMore bool
	// DefaultSort pre-sorts records on load.
	DefaultSort *SortSpec
	// Filterable adds a client-side text filter box.
	Filterable bool
	// Selection enables per-card checkboxes and bulk actions.
	Selection *SelectionConfig
	// Empty configures the no-data message.
	Empty EmptyState

	// InitialData is an optional structuredContent-shaped snapshot baked into
	// the document as a JSON island.
	InitialData map[string]any

	// LoadTool, when set, names a read tool the runtime calls once on load to
	// hydrate the list from fresh data, replacing InitialData. It must return
	// the records under RowsKey.
	LoadTool string
	// LoadArgs are optional static arguments passed to LoadTool.
	LoadArgs map[string]any

	// Brand renders the application logo/name on the widget.
	Brand *Brand
	// Theme overrides gomukit design tokens for this widget.
	Theme *theme.Theme
	// UI overrides resource _meta.ui (CSP, permissions, prefersBorder).
	UI *uispec.ResourceUIMeta
}

type CardTemplate struct {
	// Header is the top section (required: it holds the title).
	Header CardHeader
	// Content is the card body.
	Content CardContent
	// Footer is the bottom section.
	Footer CardFooter
}

type Choice struct {
	// URI is the widget's ui:// resource URI (required).
	URI string
	// Title is shown in the toolbar and the document title.
	Title string
	// Prompt is the headline question, e.g. "How should we ship this?"
	// (required).
	Prompt string
	// Body is supporting prose under the prompt.
	Body string

	// Layout places the description block. Defaults to ChoiceAuto.
	Layout ChoiceLayout
	// Multiple lets the reader pick more than one option. Without it the
	// options are radios and exactly one can be chosen.
	Multiple bool
	// Min is the fewest options a multiple choice accepts. Defaults to 1 —
	// submitting nothing is not a choice. Ignored unless Multiple.
	Min int
	// Max is the most a multiple choice accepts; 0 means no limit. Once Max
	// options are ticked the rest disable, so the limit is visible rather
	// than only enforced. Ignored unless Multiple.
	Max int

	// Options are the candidates, in reading order. May be empty when they
	// arrive at runtime under OptionsKey.
	Options []ChoiceOption
	// Details describes the record the question is about, read from rows[0].
	// It sits under the prompt, above the options.
	Details Descriptions

	// Submit configures the call the decision makes (required).
	Submit ChoiceSubmit
	// Cancel configures the declining button. Nil renders no such button,
	// leaving the host's own affordances as the only way out.
	Cancel *RejectSpec

	// RowsKey is the structuredContent key holding the context record; the
	// widget reads rows[0]. Defaults to "rows".
	RowsKey string
	// OptionsKey is the structuredContent key holding the option array.
	// Defaults to "options".
	OptionsKey string
	// RowID is the record field used for FromRow args. Defaults to "id".
	RowID string

	// InitialData is an optional structuredContent-shaped snapshot baked into
	// the document as a JSON island.
	InitialData map[string]any

	// LoadTool, when set, names a read tool the runtime calls once on load to
	// fetch the options and the record fresh, replacing InitialData. Use it
	// when what is on offer can change between registration and the question.
	LoadTool string
	// LoadArgs are optional static arguments passed to LoadTool.
	LoadArgs map[string]any

	// Brand renders the application logo/name on the widget.
	Brand *Brand
	// Theme overrides gomukit design tokens for this widget.
	Theme *theme.Theme
	// UI overrides resource _meta.ui (CSP, permissions, prefersBorder).
	UI *uispec.ResourceUIMeta
}

type ChoiceLayout string

type ChoiceOption struct {
	// Value is what the submit call sends for this option (required, unique).
	Value string
	// Label is the option's name in the list. Defaults to Value.
	Label string
	// Summary is a single supporting line under the label, shown in the list
	// whether or not the option is selected.
	Summary string

	// Body is prose about the option, shown in the description block.
	Body string
	// Bullets are short points about the option, listed under Body.
	Bullets []string
	// Details is a label/value list about the option, shown under Bullets.
	// Items with a Key read Data; items with Text are fixed.
	Details Descriptions
	// Data is the option's record, the source for Key detail items.
	Data map[string]any

	// Badge is optional short text beside the label — "recommended",
	// "cheapest".
	Badge string
	// BadgeVariant colors the badge. Defaults to BadgeNeutral.
	BadgeVariant BadgeVariant

	// Default preselects the option. A single choice takes at most one.
	Default bool
	// Disabled renders the option unselectable — on offer, but not now.
	Disabled bool
}

type ChoiceSubmit struct {
	// Tool is the MCP tool called on submit (required).
	Tool string
	// Label defaults to "Continue".
	Label string
	// ValueArg is the tool argument carrying the decision: the chosen option's
	// Value, or the array of chosen values in a multiple choice. Defaults to
	// "choice".
	ValueArg string
	// Args maps further tool argument names to their sources. Static and
	// FromRow apply; FromSelection does not — a choice has no row selection.
	// Ignored when ChatPrompt is set.
	Args map[string]ArgSource
	// ChatPrompt, when set, makes submitting post a user message (ui/message)
	// instead of calling Tool directly, for hosts that answer a view-initiated
	// call without opening the widget behind it. The reader's decision is
	// appended to this text, since a choice's whole output is what they picked
	// and ValueArg has no counterpart in a chat turn.
	//
	// Named apart from Choice.Prompt, which is the question put to the reader
	// rather than a message sent on their behalf.
	ChatPrompt string
	// Variant overrides the submit button styling (VariantPrimary).
	Variant ActionVariant
	// SuccessMessage is shown in place of the controls once the call succeeds.
	// Defaults to the tool result's own text.
	SuccessMessage string
}

type Column struct {
	// Key is the row field this column displays (unused for ColActions).
	Key   string
	Label string
	// Type defaults to ColText.
	Type ColumnType
	// Sortable overrides the default (text/number/date sortable, others not).
	Sortable *bool
	Align    Align
	// Format refines rendering, interpreted by the runtime via Intl:
	// numbers: "int" | "decimal:<digits>" | "percent" | "currency:<code>";
	// dates: "date" | "datetime" | "time" | "relative".
	Format string
	// Badge maps cell values to badge variants (ColBadge).
	Badge map[string]BadgeVariant
	// Link configures ColLink columns.
	Link *LinkSpec
	// Actions renders per-row action buttons (ColActions).
	Actions []Action
	// Width is a CSS width for the column (e.g. "12rem", "20%").
	Width string
}

type ColumnType string

type Confirm struct {
	// URI is the widget's ui:// resource URI (required).
	URI string
	// Title is shown in the toolbar and the document title.
	Title string
	// Prompt is the headline question, e.g. "Delete Ada Lovelace?"
	// (required).
	Prompt string
	// Body is supporting prose under the prompt.
	Body string
	// Severity colors the widget: BadgeInfo (the default), BadgeWarning or
	// BadgeDanger. It also picks the accept button's variant unless
	// Accept.Variant says otherwise.
	Severity BadgeVariant

	// Details describes the record the operation targets, read from rows[0].
	Details Descriptions
	// Effects are the side effects known at registration time. Any effects
	// delivered under EffectsKey at runtime replace this list wholesale.
	Effects []Effect

	// Acknowledge, when set, is the label of a checkbox the reader must tick
	// before the accept button enables ("I understand this cannot be undone").
	Acknowledge string
	// TypeToConfirm, when set, is a phrase the reader must type exactly
	// before the accept button enables — the record's name, usually.
	TypeToConfirm string

	// Accept configures the confirming call (required).
	Accept AcceptSpec
	// Reject configures the declining button. Nil renders no such button,
	// leaving the host's own affordances as the only way out.
	Reject *RejectSpec

	// RowsKey is the structuredContent key holding the record array; the
	// widget reads rows[0]. Defaults to "rows".
	RowsKey string
	// EffectsKey is the structuredContent key holding the side-effect array.
	// Defaults to "effects".
	EffectsKey string
	// RowID is the record field used for FromRow args. Defaults to "id".
	RowID string

	// InitialData is an optional structuredContent-shaped snapshot baked into
	// the document as a JSON island.
	InitialData map[string]any

	// LoadTool, when set, names a read tool the runtime calls once on load to
	// fetch the record and effects fresh, replacing InitialData. Use it when
	// the consequences must be current at decision time rather than at render
	// time.
	LoadTool string
	// LoadArgs are optional static arguments passed to LoadTool.
	LoadArgs map[string]any

	// Brand renders the application logo/name on the widget.
	Brand *Brand
	// Theme overrides gomukit design tokens for this widget.
	Theme *theme.Theme
	// UI overrides resource _meta.ui (CSP, permissions, prefersBorder).
	UI *uispec.ResourceUIMeta
}

type DateMode string

type DatePicker struct {
	// URI is the widget's ui:// resource URI (required).
	URI string
	// Title is shown in the toolbar and the document title.
	Title string
	// Prompt is the headline question, e.g. "When should we deliver?"
	// (required).
	Prompt string
	// Body is supporting prose under the prompt.
	Body string

	// Mode picks one date (the default) or a span.
	Mode DateMode
	// Calendar configures the grid. Nil is the zero value: one month for a
	// single date, two for a range, every day selectable.
	Calendar *Calendar

	// Default preselects a date ("YYYY-MM-DD"). In a range picker it is the
	// start, and DefaultEnd is the end.
	Default string
	// DefaultEnd preselects the end of the span (DateRange only).
	DefaultEnd string

	// Details describes the record the question is about, read from rows[0].
	// It sits under the prompt, above the calendar.
	Details Descriptions

	// Submit configures the call the decision makes (required).
	Submit DateSubmit
	// Cancel configures the declining button. Nil renders no such button,
	// leaving the host's own affordances as the only way out.
	Cancel *RejectSpec

	// ValueKey is the structuredContent key holding the runtime selection and
	// any runtime bounds. Defaults to "value". See docs/widgets.md for the
	// shape; briefly, a "YYYY-MM-DD" string, or an object with start, end,
	// min, max and disabled.
	ValueKey string
	// RowsKey is the structuredContent key holding the context record; the
	// widget reads rows[0]. Defaults to "rows".
	RowsKey string
	// RowID is the record field used for FromRow args. Defaults to "id".
	RowID string

	// InitialData is an optional structuredContent-shaped snapshot baked into
	// the document as a JSON island.
	InitialData map[string]any

	// LoadTool, when set, names a read tool the runtime calls once on load to
	// fetch the selection and bounds fresh, replacing InitialData. Use it when
	// what is still free to book can change between registration and the
	// question.
	LoadTool string
	// LoadArgs are optional static arguments passed to LoadTool.
	LoadArgs map[string]any

	// Brand renders the application logo/name on the widget.
	Brand *Brand
	// Theme overrides gomukit design tokens for this widget.
	Theme *theme.Theme
	// UI overrides resource _meta.ui (CSP, permissions, prefersBorder).
	UI *uispec.ResourceUIMeta
}

type DatePreset struct {
	// Label names the shortcut, e.g. "Last 7 days" (required).
	Label string
	// Span is a window relative to the reader's today, resolved at runtime in
	// the host's time zone.
	Span DateSpan
	// Start and End are a fixed window, as "YYYY-MM-DD" — a quarter that has
	// closed, a campaign that ran. In a single-date calendar only Start is
	// used; End is not allowed.
	Start, End string
}

type DateSpan string

type DateSubmit struct {
	// Tool is the MCP tool called on submit (required).
	Tool string
	// Label defaults to "Continue".
	Label string
	// ValueArg is the tool argument carrying the picked date, as
	// "YYYY-MM-DD". Defaults to "date" for a single date and "start" for a
	// range.
	ValueArg string
	// EndArg is the tool argument carrying the end of the span. Defaults to
	// "end". DateRange only.
	EndArg string
	// Args maps further tool argument names to their sources. Static and
	// FromRow apply; FromSelection does not — a date has no row selection.
	// Ignored when ChatPrompt is set.
	Args map[string]ArgSource
	// ChatPrompt, when set, makes submitting post a user message (ui/message)
	// instead of calling Tool directly, for hosts that answer a view-initiated
	// call without opening the widget behind it. The picked date is appended
	// to this text, since a picker's whole output is that date and ValueArg
	// has no counterpart in a chat turn.
	//
	// Named apart from DatePicker.Prompt, which is the question put to the
	// reader rather than a message sent on their behalf.
	ChatPrompt string
	// Variant overrides the submit button styling (VariantPrimary).
	Variant ActionVariant
	// SuccessMessage is shown in place of the controls once the call succeeds.
	// Defaults to the tool result's own text.
	SuccessMessage string
}

type DescriptionItem struct {
	// Label names the value (required).
	Label string
	// Key is the record field holding the value. On an Input item it is the
	// prefill source instead: the control opens on that field's value.
	Key string
	// Text is a fixed value, used instead of Key.
	Text string
	// Input makes this item a question: the value cell renders a control, and
	// what the reader puts in it travels with the widget's call. Only the
	// widgets that own a call accept one — DatePicker.Details and a card's
	// Content.Items; a Confirm's or a Choice's details are read-only.
	Input *Input
	// Type selects rendering: ColText (default), ColNumber, ColDate, ColBadge
	// or ColLink. Fixed-text items are always text.
	Type ColumnType
	// Format refines number and date rendering, exactly as Column.Format.
	Format string
	// Badge maps values to badge variants (ColBadge).
	Badge map[string]BadgeVariant
	// Link configures a ColLink item; its URL comes from the record.
	Link *LinkSpec
	// Align positions the value within its cell.
	Align Align
}

type Descriptions struct {
	// Items are the entries, in reading order (at least one to render).
	Items []DescriptionItem
}

type Effect struct {
	// Text states the consequence, e.g. "Deletes the audit trail" (required).
	Text string
	// Detail is a secondary line qualifying it.
	Detail string
	// Value is a magnitude shown at the end of the row, e.g. "12 records".
	Value string
	// Severity colors the row: BadgeNeutral (the default), BadgeInfo,
	// BadgeSuccess, BadgeWarning or BadgeDanger.
	Severity BadgeVariant
}

type EmptyState struct {
	Title string `json:"title,omitempty"`
	Body  string `json:"body,omitempty"`
}

type Field struct {
	// Name is the tool-call argument name (required, unique).
	Name  string
	Label string
	// Description renders as help text under the control.
	Description string
	Placeholder string
	// Type defaults to FText.
	Type FieldType
	// Required marks the field as mandatory.
	Required bool
	// Default is the initial value: string-like for most fields, bool for
	// FCheckbox, []string for FMultiSelect, and []string{start, end} for
	// FDateRange.
	Default any
	// Options are required for FSelect and FMultiSelect.
	Options []Option
	// Validation adds client-side constraints. Date fields take their bounds
	// from Calendar instead.
	Validation *Validation
	// Rows sets the textarea height (FTextarea).
	Rows int

	// Calendar configures the grid an FDate or FDateRange field opens, exactly
	// as it configures the standalone DatePicker widget: bounds, blocked days,
	// presets, month travel. Nil is the zero value — one month for a date, two
	// for a range, every day selectable.
	Calendar *Calendar
	// EndName is the tool-call argument carrying a range's end date
	// (FDateRange only). Defaults to Name + "_end". It shares the field's
	// namespace, so it must not collide with another field's Name.
	EndName string
}

type FieldType string

type Form struct {
	// URI is the widget's ui:// resource URI (required).
	URI string
	// Title is shown above the form and as the document title.
	Title string
	// Fields defines the form fields (required, non-empty).
	Fields []Field
	// Submit configures the submit tool call (required).
	Submit SubmitSpec
	// Cancel, when set, adds a reset button.
	Cancel *CancelSpec

	// PrefillKey is the structuredContent key holding {"field": value}
	// prefill data. Defaults to "values".
	PrefillKey string
	// ErrorsKey is the structuredContent key holding {"field": "message"}
	// validation errors. Defaults to "errors".
	ErrorsKey string

	// InitialData is an optional structuredContent-shaped snapshot baked
	// into the document (e.g. {"values": {...}} for a pre-filled edit form).
	InitialData map[string]any

	// LoadTool, when set, names a read tool the runtime calls once on load
	// (after the host handshake) to hydrate the form's prefill from fresh
	// data, replacing the baked InitialData snapshot. The tool must return
	// the prefill values under PrefillKey in its structuredContent.
	LoadTool string
	// LoadArgs are optional static arguments passed to LoadTool.
	LoadArgs map[string]any

	// Brand renders the application logo/name on the widget.
	Brand *Brand
	// Theme overrides gomukit design tokens for this widget.
	Theme *theme.Theme
	// UI overrides resource _meta.ui.
	UI *uispec.ResourceUIMeta
}

type Input struct {
	// Name is the tool argument the value travels in (required, unique within
	// the block, and distinct from every other argument the widget's call
	// builds).
	Name string
	// Type defaults to InputText.
	Type InputType
	// Placeholder is the empty-state text. On an InputSelect it is what the
	// dropdown reads before a choice is made.
	Placeholder string
	// Required blocks the widget's call until the control is filled in.
	Required bool
	// Default is the value the control opens on: string-like for text, number
	// and select, bool for InputCheckbox. The item's Key wins over it when the
	// record carries that field.
	Default any
	// Options are the choices of an InputSelect (required for it, invalid
	// otherwise).
	Options []Option
	// Validation adds client-side constraints, exactly as on a form Field.
	// Only Message applies to a select or a checkbox; the rest constrain text
	// length, number bounds and step.
	Validation *Validation
}

type InputType string

type LinkSpec struct {
	HrefKey string `json:"hrefKey"`
	TextKey string `json:"textKey,omitempty"`
	Text    string `json:"text,omitempty"`
}

type Menu struct {
	// URI is the widget's ui:// resource URI (required).
	URI string
	// Title is shown in the toolbar and the document title.
	Title string
	// Intro is optional lead text shown above the tiles.
	Intro string
	// Items are the menu entries (at least one is required).
	Items []MenuItem

	// Brand renders the application logo/name on the widget.
	Brand *Brand
	// Theme overrides gomukit design tokens for this widget.
	Theme *theme.Theme
	// UI overrides resource _meta.ui (CSP, permissions, prefersBorder).
	UI *uispec.ResourceUIMeta
}

type MenuItem struct {
	// Tool is the MCP tool called when the item is chosen (required). With
	// Prompt set the call is the model's to make, so Tool documents what the
	// item opens and still supplies the default Label.
	Tool string
	// Args are static arguments passed to Tool. Menu items carry no record,
	// so unlike Action args these are fixed values, not row lookups. Ignored
	// when Prompt is set — the model chooses the arguments there.
	Args map[string]any
	// Prompt, when set, makes the item ask the host to post this text as a
	// user message (ui/message) instead of calling Tool itself. Write it as
	// the request a user would type: the model reads it and decides which
	// tool answers, so name what the item opens rather than the tool.
	Prompt string
	// Label is the tile heading. Defaults to Tool.
	Label string
	// Description is the supporting line under the label.
	Description string
	// IconSVG is inline <svg> markup shown above the label. Documents stay
	// self-contained, so an icon is never a URL. It is author-trusted input,
	// checked only against script-bearing and resource-loading constructs.
	IconSVG string
	// Badge is optional short text shown in the tile's top right — a category
	// or state marker such as "read" or "beta".
	Badge string
	// BadgeVariant colors the badge. Defaults to BadgeNeutral.
	BadgeVariant BadgeVariant
}

type Option struct {
	Value string `json:"value"`
	Label string `json:"label"`
}

type RejectSpec struct {
	// Label defaults to "Cancel".
	Label string
	// Tool is an optional MCP tool called when the reader declines. Without
	// it, declining is a local outcome the server never hears about — set it
	// when the operation needs an explicit "no".
	Tool string
	// Args maps tool argument names to their sources (Static and FromRow).
	Args map[string]ArgSource
	// Message is shown in place of the buttons once the reader declines.
	// Defaults to "Cancelled."
	Message string
}

type SelectionConfig struct {
	// Bulk actions appear in the toolbar while rows are selected.
	// FromSelection args resolve across all selected rows.
	Bulk []Action
}

type SortSpec struct {
	Key  string `json:"key"`
	Desc bool   `json:"desc,omitempty"`
}

type SubmitSpec struct {
	// Tool is the MCP tool called with {field: value, ...} merged over
	// StaticArgs (required).
	Tool string
	// Label defaults to "Submit".
	Label string
	// StaticArgs are fixed arguments merged under the field values.
	StaticArgs map[string]any
	// SuccessMessage is shown after a successful submit.
	SuccessMessage string
}

type Table struct {
	// URI is the widget's ui:// resource URI (required).
	URI string
	// Title is shown in the toolbar and the document title.
	Title string
	// Columns defines the table's columns (required, non-empty).
	Columns []Column

	// RowsKey is the structuredContent key holding the rows array.
	// Defaults to "rows".
	RowsKey string
	// RowID is the row field that uniquely identifies a row, used for
	// selection and FromRow/FromSelection args. Defaults to "id".
	RowID string

	// PageSize enables client-side pagination when > 0.
	PageSize int
	// PageSizes offers alternative page sizes in a dropdown on the pagination
	// bar. Entries must be > 0 and PageSize must be set; PageSize is added to
	// the list if it is not among them. Empty renders no chooser.
	PageSizes []int
	// DefaultSort pre-sorts rows on load.
	DefaultSort *SortSpec
	// Filterable adds a client-side text filter box.
	Filterable bool
	// Selection enables row checkboxes and bulk actions.
	Selection *SelectionConfig
	// Empty configures the no-data message.
	Empty EmptyState

	// InitialData is an optional structuredContent-shaped snapshot baked
	// into the document as a JSON island.
	InitialData map[string]any

	// LoadTool, when set, names a read tool the runtime calls once on load
	// (after the host handshake) to hydrate the table from fresh data,
	// replacing the baked InitialData snapshot. This keeps a reloaded widget
	// current instead of reverting to the state frozen at render time. The
	// tool must return the rows under RowsKey in its structuredContent.
	LoadTool string
	// LoadArgs are optional static arguments passed to LoadTool.
	LoadArgs map[string]any

	// Brand renders the application logo/name on the widget.
	Brand *Brand
	// Theme overrides gomukit design tokens for this widget.
	Theme *theme.Theme
	// UI overrides resource _meta.ui (CSP, permissions, prefersBorder).
	UI *uispec.ResourceUIMeta
}

type Validation struct {
	// Pattern is a regular expression the value must match (HTML pattern
	// attribute semantics).
	Pattern string
	// Min/Max/Step constrain number, date, and time fields.
	Min  *float64
	Max  *float64
	Step *float64
	// MinLen/MaxLen constrain text lengths.
	MinLen *int
	MaxLen *int
	// Message overrides the browser's validation message.
	Message string
}

type WeekStart string

type Widget interface {
	// Document renders the complete self-contained HTML document.
	Document() (string, error)
	// Descriptor returns registration data for the template resource.
	Descriptor() uispec.ResourceDescriptor
	// ToolMeta returns the _meta map linking a tool to this widget:
	// {"ui": {"resourceUri": ...}}.
	ToolMeta() map[string]any
	// Validate checks the widget configuration.
	Validate() error
}