A component is one entry in the finite catalog that constrains what the
model can render. It couples a model-facing tool schema (name,
description, typed args) with developer-written rendering code: a
ui function plus an optional server function, instantiated together
as a dynamic Shiny module every time the model creates or updates an
instance. The model only ever supplies data arguments validated against
the declared types; it never emits code.
Arguments
- name
Tool name the model sees. A snake_case string: lowercase letters, digits, and underscores, starting with a letter. Must be unique within a catalog and must not collide with the built-in lifecycle tools (
update_component,remove_component,clear_canvas).- description
One to three sentences telling the model what the component shows and when to use it. This is the model-facing documentation for the component, so write it well.
- args
Named list of ellmer type specifications (for example
ellmer::type_string(),ellmer::type_enum()) describing the arguments the model may supply. As a shorthand, a plain string is promoted toellmer::type_string(<string>). Argument namesidandparent_idare reserved by the package. Catalogs are often built inside the Shiny server function so enums can enumerate live facts, such as the column names of the active dataset.- ui
function(id, args)returning anhtmltools::tag()(or tag list).idis the fully namespaced module id for this instance; useshiny::NS(id)to namespace any embedded inputs and outputs.argsis the validated argument list; see the "Argument values" section.- server
Optional
function(id, args, data)that callsshiny::moduleServer()to wire outputs and embedded inputs.datais the reactive passed togenui_server(). If the module creates observers, include them in the module's return value (alone or inside a list) so the package can destroy them when the instance is updated or removed. Areactiveselement in the return value is stored in the instance registry keyed by instance id; nothing reads it in v0.1, it is the hook for cross-component reactivity in a later release.- check
Optional
function(args, data)for semantic validation beyond the declared types. ReturnNULLwhenargsare acceptable, or a string describing the problem; the string is returned to the model as a tool error so it can self-correct.- container
If
TRUE, this component can host child instances: itsuimust render an element with idshiny::NS(id, "slot"), and other components may target it by passing the instance's id asparent_id.- width
Layout hint for the canvas grid:
"auto"(default),"wide", or"full".
Argument values
ui, server, and check receive args in the same form whether the
call came from the model, from update_component, or from
genui_replay():
A string, enum, boolean, integer, or number is a length-one vector.
An array of those is an atomic vector, which may be empty.
An array of objects or of arrays is an unnamed list.
An object is a named list that holds only the fields supplied.
An optional argument that the model omitted or set to null is absent from
args, so test for it with is.null().
Examples
genui_component(
name = "note_card",
description = "A card showing a short markdown note. Use for narrative
text that should live on the canvas rather than in the chat.",
args = list(
title = "A short title for the card.",
text = ellmer::type_string("The markdown body text.")
),
ui = function(id, args) {
htmltools::div(
htmltools::h5(args$title),
htmltools::p(args$text)
)
}
)
#> <genui_component> "note_card"
#> A card showing a short markdown note. Use for narrative text that should live
#> on the canvas rather than in the chat.
#> args: "title" and "text"
