Agentic-GenUI-Tools 0.2.0__py3-none-any.whl

adaptive_card_tools/catalog.py

@@ -0,0 +1,488 @@
+"""The element vocabulary: canonical types, the many names models use for them,
+field aliases, and inference of a missing or unknown type from an element's fields.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+from .normalize import Context, as_number, as_url, closest, is_slug_like, token
+
+
+@dataclass(frozen=True)
+class Spec:
+    kind: str                       # display | input | layout
+    main: str                       # field that receives a bare value, e.g. {"facts": {...}}
+    fields: dict[str, tuple[str, ...]]
+    doc: str
+    example: dict = field(default_factory=dict)
+
+
+def _f(**fields: str) -> dict[str, tuple[str, ...]]:
+    return {name: tuple(aliases.split()) for name, aliases in fields.items()}
+
+
+INPUT = dict(
+    label="question prompt title text caption display_name displayname header heading field_label",
+    id="input_id field_id field key identifier ref variable var field_name input_name",
+    required="is_required isrequired mandatory must",
+    placeholder="hint placeholder_text watermark example sample",
+    value="default default_value initial initial_value prefill preset selected selected_value answer current",
+    error_message="validation_message error_text error invalid_message errormessage",
+)
+BOUNDS = dict(min="minimum min_value minvalue lower lower_bound floor from start earliest min_date min_time after",
+              max="maximum max_value maxvalue upper upper_bound ceiling to end latest max_date max_time before")
+TITLE = "heading header caption name"
+
+SPECS: dict[str, Spec] = {
+    "heading": Spec("display", "text", _f(text="title heading label content value name header string"),
+                    "Section heading.", {"type": "heading", "text": "Summary"}),
+    "text": Spec("display", "text", _f(text="content body value message paragraph markdown md string copy inlines", title=TITLE),
+                 "Paragraph. **bold**, _italic_ and [links](https://…) work.", {"type": "text", "text": "Your order has shipped."}),
+    "note": Spec("display", "text", _f(text="content body value message string copy"),
+                 "Small grey print (disclaimer, footnote).", {"type": "note", "text": "Prices exclude tax."}),
+    "list": Spec("display", "items", _f(items="list bullets points entries values lines steps elements rows options texts",
+                                        numbered="ordered is_ordered numbering", title=TITLE),
+                 "Bulleted list; numbered=true for steps.", {"type": "list", "items": ["Fast setup", "No card required"]}),
+    "facts": Spec("display", "facts", _f(facts="items data details properties attributes specs pairs fields rows values entries info kv key_values", title=TITLE),
+                  "Label/value pairs.", {"type": "facts", "facts": {"Owner": "Dana", "Due": "2026-10-01"}}),
+    "table": Spec("display", "rows", _f(rows="data records items entries body values products lines list",
+                                        columns="headers header fields keys cols head column_names labels", title=TITLE),
+                  "Rows of records; columns are inferred.", {"type": "table", "rows": [{"Item": "Laptop", "Qty": 2}, {"Item": "Monitor", "Qty": 3}]}),
+    "metrics": Spec("display", "items", _f(items="metrics kpis stats values data figures numbers entries cards tiles", title=TITLE,
+                                           label="metric kpi stat key", value="amount number figure count total score current_value val result",
+                                           change="delta diff difference trend growth variance pct_change percent_change movement change_percent",
+                                           note="period context subtext secondary comparison target description subtitle",
+                                           lower_is_better="good_direction inverse invert better"),
+                    "Big-number KPI tiles; change like \"+8%\" is coloured.", {"type": "metrics", "items": [{"label": "Revenue", "value": "$1.2M", "change": "+8%"}]}),
+    "badge": Spec("display", "text", _f(text="label title value name content", tone="status state color colour style variant severity level intent appearance"),
+                  "Status pill. tone: success|warning|danger|info|neutral (inferred if omitted).", {"type": "badge", "text": "Approved", "tone": "success"}),
+    "image": Spec("display", "url", _f(url="src source href link uri image image_url imageurl img path picture photo",
+                                       alt="alt_text alttext alternate", caption="caption_text description text label subtitle legend",
+                                       title="heading header name", size="scale dimension", shape="style rounded crop"),
+                  "Image from an https URL you were given.", {"type": "image", "url": "https://example.com/photo.png", "alt": "Product photo"}),
+    "images": Spec("display", "images", _f(images="urls items photos pictures gallery sources src thumbnails", title=TITLE),
+                   "Image gallery.", {"type": "images", "images": ["https://example.com/a.png", "https://example.com/b.png"]}),
+    "media": Spec("display", "sources", _f(sources="source url src video audio urls file link href", poster="thumbnail cover preview image poster_url",
+                                           alt="alt_text description", title=TITLE),
+                  "Video/audio player.", {"type": "media", "sources": "https://example.com/video.mp4"}),
+    "chart": Spec("display", "data", _f(chart_type="chart charttype graph graph_type subtype variant style chart_style kind_of_chart",
+                                        data="values points dataset data_points datapoints items records",
+                                        series="datasets lines groups bars", labels="categories x x_values xvalues keys names",
+                                        title=TITLE, x_label="x_axis x_axis_title x_title x_axis_label xname x_name xaxis",
+                                        y_label="y_axis y_axis_title y_title y_axis_label yname y_name yaxis unit units",
+                                        value="current reading", min="minimum", max="maximum target total",
+                                        segments="ranges bands zones thresholds"),
+                  "chart_type: bar|horizontal_bar|line|pie|donut|stacked_bar|grouped_bar|gauge.",
+                  {"type": "chart", "chart_type": "bar", "title": "Orders", "data": {"Jan": 120, "Feb": 150, "Mar": 170}}),
+    "progress": Spec("display", "value", _f(label="title name text caption", value="progress percent percentage current completed done complete pct amount",
+                                            max="total target goal of out_of maximum"),
+                     "Progress bar; value is a percent unless max is given.", {"type": "progress", "label": "Migration", "value": 70}),
+    "spinner": Spec("display", "label", _f(label="title text message"), "Loading indicator.", {"type": "spinner", "label": "Loading"}),
+    "rating": Spec("display", "value", _f(value="rating score stars average avg rate", max="out_of scale max_stars of best maximum",
+                                          count="votes reviews review_count num_ratings ratings number_of_reviews n", title="label heading name"),
+                   "Star rating (read-only).", {"type": "rating", "value": 4.5, "count": 120}),
+    "divider": Spec("display", "", {}, "Thin line between parts of the card.", {"type": "divider"}),
+    "section": Spec("layout", "elements", _f(title="heading header label name", elements="items body children content components fields widgets blocks contents questions"),
+                    "Titled group of elements.", {"type": "section", "title": "Details", "elements": [{"type": "text", "text": "…"}]}),
+    "columns": Spec("layout", "columns", _f(columns="cols items children panels cards cells sections groups products plans tiers"),
+                    "Side-by-side tiles, each {title, elements}.",
+                    {"type": "columns", "columns": [{"title": "Basic", "elements": [{"type": "facts", "facts": {"Price": "$10"}}]},
+                                                    {"title": "Pro", "elements": [{"type": "facts", "facts": {"Price": "$20"}}]}]}),
+    "buttons": Spec("layout", "buttons", _f(buttons="actions items links ctas", label="title text name caption",
+                                            url="href link uri target open_url openurl website destination",
+                                            data="payload submit_data params parameters body value",
+                                            action="on_click onclick click behavior action_type kind", style="tone variant color appearance intent importance priority"),
+                    "Buttons: with url opens a link, without url submits.",
+                    {"type": "buttons", "buttons": [{"label": "Approve"}, {"label": "View details", "url": "https://example.com/req/42"}]}),
+    "text_input": Spec("input", "label", _f(**INPUT, multiline="is_multiline ismultiline multi_line textarea long long_text",
+                                            max_length="maxlength max_chars character_limit max_characters char_limit limit length max_len",
+                                            format="input_format text_format input_type inputtype style subtype variant mode",
+                                            regex="pattern validation validation_regex"),
+                       "Text box. format: email|tel|url|password; multiline for long answers.",
+                       {"type": "text_input", "label": "Email", "id": "email", "format": "email", "required": True}),
+    "number_input": Spec("input", "label", _f(**INPUT, **BOUNDS, unit="units currency suffix prefix measure"),
+                         "Number box.", {"type": "number_input", "label": "Quantity", "min": 1}),
+    "date_input": Spec("input", "label", _f(**INPUT, **BOUNDS), "Date picker (any common date format).", {"type": "date_input", "label": "Start date"}),
+    "time_input": Spec("input", "label", _f(**INPUT, **BOUNDS), "Time picker (9:30, 2pm…).", {"type": "time_input", "label": "Meeting time"}),
+    "datetime_input": Spec("input", "label", _f(**INPUT, **BOUNDS), "Date and time pickers side by side.", {"type": "datetime_input", "label": "Pickup"}),
+    "choice": Spec("input", "options", _f(**INPUT, options="choices items values list selections answers enum option_list entries",
+                                          multiple="multiselect is_multi_select ismultiselect allow_multiple multi select_multiple many multi_select allowmultiple",
+                                          display="style presentation appearance variant widget ui layout control render_as display_as"),
+                   "Pick from options. multiple=true for several; display: radio|dropdown.",
+                   {"type": "choice", "label": "Plan", "options": ["Basic", "Pro", "Enterprise"]}),
+    "checkbox": Spec("input", "label", _f(**{**INPUT, "value": "checked is_checked default selected state default_value initial"},
+                                          on_value="value_on valueon checked_value true_value", off_value="value_off valueoff unchecked_value false_value"),
+                     "Single yes/no checkbox.", {"type": "checkbox", "label": "I agree to the terms", "required": True}),
+    "rating_input": Spec("input", "label", _f(**INPUT, max="max_stars stars out_of scale maximum of",
+                                              half_steps="allow_half_steps allowhalfsteps half half_stars allow_half"),
+                         "Star rating the user can pick.", {"type": "rating_input", "label": "How was your visit?"}),
+    # Internal pseudo-types reached through aliases; never documented to the model.
+    "column": Spec("layout", "elements", _f(title="heading header label name", elements="items body children content components blocks widgets"), ""),
+    "document": Spec("layout", "elements", {}, ""),
+}
+DOCUMENTED = [k for k, s in SPECS.items() if s.doc]
+
+TYPE_NAMES = {
+    "heading": "heading header headline title h1 h2 h3 h4 h5 h6 subheading subheader sectiontitle sectionheader",
+    "text": "text textblock paragraph p para markdown md string content message description richtext richtextblock span label copy prose body summary intro introduction codeblock tagline",
+    "note": "note caption footnote footer disclaimer fineprint smallprint subtle helptext remark aside small hint",
+    "list": "list bullets bulletlist bulletedlist bulletpoints ul unorderedlist itemlist",
+    "facts": "facts factset fact keyvalue keyvalues keyvaluelist properties details specs specifications attributes definitionlist dl kv summarylist",
+    "table": "table datatable grid datagrid spreadsheet comparison compare comparisontable matrix",
+    "metrics": "metrics metric kpi kpis stat stats statistic statistics scorecard figure figures counter kpicard statcard kpitile",
+    "badge": "badge tag pill chip status statusbadge lozenge statuspill",
+    "image": "image img photo picture pic logo avatar thumbnail hero banner icon",
+    "images": "images imageset gallery carousel photos pictures thumbnails imagegallery",
+    "media": "media video audio player videoplayer",
+    "chart": "chart graph plot visualization visualisation viz datachart",
+    "progress": "progress progressbar completion loadingbar",
+    "spinner": "spinner progressring loading loader busy",
+    "rating": "rating stars starrating reviews",
+    "divider": "divider separator hr rule spacer horizontalrule",
+    "section": "section group container panel box block fieldset stack stackpanel vstack div area region well wrapper subform",
+    "columns": "columns columnset row hstack sidebyside split layout grouprow",
+    "column": "column col",
+    "buttons": "buttons button actions action actionset cta ctas buttongroup buttonrow toolbar",
+    "text_input": "textinput inputtext input textfield textbox field entry freetext shorttext shortanswer answer",
+    "number_input": "numberinput inputnumber number numeric integer int float decimal quantity slider stepper spinbutton range amountinput",
+    "date_input": "dateinput inputdate date datepicker calendar dateselector dob birthday",
+    "time_input": "timeinput inputtime time timepicker",
+    "datetime_input": "datetime datetimeinput datetimepicker timestamp",
+    "choice": "choice choices choiceset inputchoiceset options option question multiplechoice selection choiceinput",
+    "checkbox": "checkbox toggle switch boolean bool consent agree agreement acceptance tickbox inputtoggle confirm confirmation",
+    "rating_input": "ratinginput inputrating starinput starpicker starrating_input feedbackrating ratingpicker",
+    "document": "adaptivecard card document form page survey questionnaire dashboard report",
+}
+# Names that also imply a field value, e.g. "radio" is a choice displayed as radio buttons.
+IMPLIED = [
+    ("choice", {"display": "radio"}, "radio radiogroup radiobuttons radiobutton radioinput singleselect singlechoice radiobuttongroup"),
+    ("choice", {"display": "dropdown"}, "dropdown select selectbox selectinput combobox combo picker dropdowninput inputdropdown dropdownlist selectlist menu"),
+    ("choice", {"multiple": True}, "multiselect multichoice multipleselect checkboxes checkboxgroup checkboxlist checklist multiselectinput"),
+    ("choice", {"options": ["Yes", "No"], "display": "radio"}, "yesno yesnoquestion boolchoice"),
+    ("text_input", {"multiline": True}, "textarea multilinetext longtext multiline paragraphinput comment comments longanswer"),
+    ("text_input", {"format": "email"}, "email emailinput emailfield emailaddress"),
+    ("text_input", {"format": "tel"}, "phone tel telephone phoneinput phonenumber mobile"),
+    ("text_input", {"format": "url"}, "urlinput urlfield website"),
+    ("text_input", {"format": "password"}, "password passwordinput secret"),
+    ("text_input", {"format": "url", "_unsupported": "file upload"}, "file fileupload upload attachment fileinput"),
+    ("list", {"numbered": True}, "numberedlist orderedlist ol steps stepslist"),
+    ("chart", {"chart_type": "bar"}, "bar barchart verticalbar verticalbarchart columnchart chartverticalbar histogram"),
+    ("chart", {"chart_type": "horizontal_bar"}, "horizontalbar hbar horizontalbarchart barh charthorizontalbar"),
+    ("chart", {"chart_type": "line"}, "line linechart linegraph trend trendline timeseries area areachart sparkline chartline"),
+    ("chart", {"chart_type": "pie"}, "pie piechart chartpie"),
+    ("chart", {"chart_type": "donut"}, "donut doughnut donutchart doughnutchart ring chartdonut"),
+    ("chart", {"chart_type": "stacked_bar"}, "stackedbar stackedbarchart stackedcolumn stackedcolumnchart chartverticalbarstacked"),
+    ("chart", {"chart_type": "stacked_horizontal_bar"}, "stackedhorizontalbar horizontalstackedbar charthorizontalbarstacked"),
+    ("chart", {"chart_type": "grouped_bar"}, "groupedbar groupedbarchart clusteredbar clusteredcolumn multibar chartverticalbargrouped"),
+    ("chart", {"chart_type": "gauge"}, "gauge gaugechart meter dial speedometer chartgauge"),
+    ("buttons", {"action": "submit"}, "submit submitbutton actionsubmit actionexecute execute"),
+    ("buttons", {"action": "open_url"}, "link hyperlink openurl actionopenurl linkbutton"),
+]
+
+TYPE_ALIASES: dict[str, tuple[str, dict]] = {}
+for _canonical, _names in TYPE_NAMES.items():
+    for _name in [_canonical, *_names.split()]:
+        TYPE_ALIASES.setdefault(token(_name), (_canonical, {}))
+for _canonical, _implied, _names in IMPLIED:
+    for _name in _names.split():
+        TYPE_ALIASES[token(_name)] = (_canonical, _implied)
+
+# Words searched inside unknown type names such as "EmailField" or "RevenueBarGraph".
+_INPUT_WORDS = ("input", "field", "picker", "entry", "textbox", "selector")
+KEYWORDS = [
+    (("chart", "graph", "plot", "viz"), "chart"),
+    (("button", "action", "cta"), "buttons"),
+    (("kpi", "metric", "stat", "scorecard"), "metrics"),
+    (("table", "grid"), "table"),
+    (("fact", "keyvalue", "propert", "spec"), "facts"),
+    (("gallery", "images", "photos"), "images"),
+    (("image", "img", "photo", "picture", "logo", "avatar", "thumbnail", "banner"), "image"),
+    (("video", "audio", "media"), "media"),
+    (("bullet", "list"), "list"),
+    (("badge", "tag", "pill", "chip", "status"), "badge"),
+    (("progress",), "progress"),
+    (("rating", "star"), "rating"),
+    (("divider", "separator", "spacer"), "divider"),
+    (("heading", "header", "title"), "heading"),
+    (("columns", "row"), "columns"),
+    (("section", "group", "container", "panel", "card", "box", "block", "stack", "wrapper"), "section"),
+    (("text", "paragraph", "label", "description", "markdown", "message", "content"), "text"),
+]
+CHART_WORDS = [("donut", "donut"), ("doughnut", "donut"), ("pie", "pie"), ("gauge", "gauge"), ("line", "line"),
+               ("area", "line"), ("trend", "line"), ("stackedhorizontal", "stacked_horizontal_bar"),
+               ("stack", "stacked_bar"), ("group", "grouped_bar"), ("cluster", "grouped_bar"),
+               ("horizontal", "horizontal_bar"), ("bar", "bar"), ("column", "bar")]
+INPUT_WORDS = [("datetime", ("datetime_input", {})), ("date", ("date_input", {})), ("time", ("time_input", {})),
+               ("email", ("text_input", {"format": "email"})), ("phone", ("text_input", {"format": "tel"})),
+               ("password", ("text_input", {"format": "password"})), ("url", ("text_input", {"format": "url"})),
+               ("number", ("number_input", {})), ("numeric", ("number_input", {})), ("amount", ("number_input", {})),
+               ("rating", ("rating_input", {})), ("star", ("rating_input", {})),
+               ("check", ("checkbox", {})), ("toggle", ("checkbox", {})), ("switch", ("checkbox", {})),
+               ("radio", ("choice", {"display": "radio"})), ("dropdown", ("choice", {"display": "dropdown"})),
+               ("select", ("choice", {})), ("choice", ("choice", {})), ("option", ("choice", {})),
+               ("textarea", ("text_input", {"multiline": True})), ("multiline", ("text_input", {"multiline": True}))]
+
+
+def resolve_type(name, ctx: Context, path: str) -> tuple[str, dict] | None:
+    """Canonical type for a type name: exact alias, typo, then keywords."""
+    if not isinstance(name, str) or not name.strip():
+        return None
+    t = token(name)
+    if t in TYPE_ALIASES:
+        result = TYPE_ALIASES[t]
+        if name != result[0]:
+            ctx.fixed(path, "type_alias", source=name, target=result[0])
+        return result
+    near = closest(t, TYPE_ALIASES, ctx)
+    if near:
+        ctx.fixed(path, "type_typo", source=name, target=TYPE_ALIASES[near][0])
+        return TYPE_ALIASES[near]
+    result = None
+    if any(w in t for w in _INPUT_WORDS):
+        result = next((r for w, r in INPUT_WORDS if w in t), ("text_input", {}))
+    else:
+        for words, canonical in KEYWORDS:
+            if any(w in t for w in words):
+                implied = {}
+                if canonical == "chart":
+                    implied = next(({"chart_type": v} for w, v in CHART_WORDS if w in t), {})
+                result = (canonical, implied)
+                break
+    if result:
+        ctx.fixed(path, "type_guessed_from_name", source=name, target=result[0])
+    return result
+
+
+# ---------------------------------------------------------------- fields
+
+TYPE_KEYS = {"type", "kind", "component", "componenttype", "elementtype", "element", "widget", "control",
+             "atype", "typename", "blocktype", "fieldtype", "inputtype", "as"}
+STYLE_KEYS = {token(k) for k in """
+    size weight color colour isSubtle subtle spacing separator horizontalAlignment alignment align textAlign
+    verticalAlignment verticalContentAlignment width height minHeight maxHeight style bleed fontType font fontSize
+    fontWeight fontFamily wrap maxLines backgroundImage background backgroundColor bgColor selectAction fallback
+    fallbackText requires isVisible visible hidden $schema version $when msteams targetWidth lang speak rtl padding
+    margin border borderRadius rounded roundedCorners shadow elevation class className css theme emphasis iconUrl
+    tooltip isEnabled enabled disabled mode associatedInputs gridStyle showGridLines firstRowAsHeader firstRowAsHeaders
+    horizontalCellContentAlignment verticalCellContentAlignment imageSize pixelWidth pixelHeight order index uuid
+    testId aria ariaLabel role visibility opacity position animation italic bold underline strikethrough highlight
+    monospace fontStyle textStyle textColor textSize valueFormat showTitle colorSet showLegend legendPosition level
+    stacked horizontal orientation step increment isInline inline columnsCount span colspan rowspan layoutHint
+    ordering variantStyle labelPosition labelWidth inputStyle choicesData isHidden debug comment_for_developer
+    """.split()}
+CONTENT_KEYS = {token(k) for k in """
+    subtitle subheading description desc summary details detail note notes body content message caption footer
+    footnote info remark remarks explanation context help helpText tip tips disclaimer text subtext tagline byline
+    instructions hint
+    """.split()}
+ICON_KEYS = {"icon", "emoji"}
+
+
+@dataclass
+class Fields:
+    values: dict
+    hints: dict            # style properties that carry meaning (size, weight, stacked...)
+    extras: list           # (key, value) content found under unrecognized keys; rendered as notes
+    unknown: list          # (key, value) that could not be placed
+
+
+def alias_map(canonical: str) -> dict[str, str]:
+    spec = SPECS[canonical]
+    mapping = {}
+    for name, aliases in spec.fields.items():
+        mapping.setdefault(token(name), name)
+    for name, aliases in spec.fields.items():
+        for alias in aliases:
+            mapping.setdefault(token(alias), name)
+    return mapping
+
+
+FIELD_ALIASES = {name: alias_map(name) for name in SPECS}
+
+
+def map_fields(canonical: str, raw: dict, path: str, ctx: Context, skip=()) -> Fields:
+    spec = SPECS[canonical]
+    mapping = FIELD_ALIASES[canonical]
+    out = Fields({}, {}, [], [])
+    exact = {}
+    for key, value in raw.items():
+        if key in skip:
+            continue
+        t = token(key)
+        target = mapping.get(t)
+        if target is None and t == "name" and spec.kind == "input":
+            target = "id" if is_slug_like(value) and " " not in str(value) else "label"
+            if target in out.values:
+                target = "label" if target == "id" else None
+        if target is None and t in {"optional", "isoptional"} and spec.kind == "input":
+            out.hints["optional"] = value
+            continue
+        if target is None and t in ICON_KEYS:
+            out.hints["icon"] = value
+            continue
+        if target is None and t in STYLE_KEYS:
+            out.hints[t] = value
+            ctx.fixed(f"{path}.{key}", "ignored_style_key")
+            continue
+        if target is None and t in CONTENT_KEYS:
+            if value not in (None, "", [], {}):
+                out.extras.append((key, value))
+            continue
+        if target is None:
+            near = closest(t, mapping, ctx)
+            if near:
+                target = mapping[near]
+                ctx.fixed(f"{path}.{key}", "field_typo", target=target)
+        if target is None:
+            if key != "id" and value not in (None, "", [], {}):
+                out.unknown.append((key, value))
+            continue
+        if value is None:
+            continue
+        is_exact = t == token(target)
+        if target in out.values:
+            # Two keys for one field. The exact name wins; distinct text is kept as a note.
+            loser = value
+            if is_exact and not exact[target]:
+                loser, out.values[target], exact[target] = out.values[target], value, True
+            if isinstance(loser, str) and loser.strip() and loser != out.values[target] and target in {"label", "text", "title", "caption"}:
+                out.extras.append((key, loser))
+            else:
+                ctx.fixed(f"{path}.{key}", "duplicate_field_ignored", target=target)
+            continue
+        out.values[target], exact[target] = value, is_exact
+        if not is_exact:
+            ctx.fixed(f"{path}.{key}", "field_alias", target=target)
+    return out
+
+
+# ---------------------------------------------------------------- inference
+
+_IMAGE_EXT = re.compile(r"\.(png|jpe?g|gif|webp|svg|bmp|avif)(\?|#|$)", re.I)
+_MEDIA_EXT = re.compile(r"\.(mp4|webm|mov|m4v|mp3|wav|ogg|m4a|aac)(\?|#|$)", re.I)
+
+
+def _is_numeric_mapping(value) -> bool:
+    return isinstance(value, dict) and bool(value) and all(as_number(v) is not None for v in value.values())
+
+
+def _looks_like_elements(value) -> bool:
+    return isinstance(value, list) and bool(value) and all(
+        isinstance(v, (dict, list)) and (not isinstance(v, dict) or any(token(k) in TYPE_KEYS for k in v)) for v in value)
+
+
+def infer_type(obj: dict) -> tuple[str, dict] | None:
+    """Guess a type from the fields present when no usable type was given."""
+    keys = {token(k): v for k, v in obj.items()}
+    has = keys.__contains__
+    if has("options") or has("choices"):
+        return "choice", {}
+    if has("rows") or has("records"):
+        return "table", {}
+    if has("columns"):
+        cols = keys["columns"]
+        if isinstance(cols, list) and cols and all(isinstance(c, str) for c in cols) and not has("elements"):
+            return "table", {}
+        return "columns", {}
+    if has("facts"):
+        return "facts", {}
+    if any(has(k) for k in ("metrics", "kpis", "stats")):
+        return "metrics", {}
+    if has("change") or has("delta") or has("trend") and has("value"):
+        return "metrics", {}
+    if any(has(k) for k in ("series", "datasets", "charttype")) or (has("data") and _is_numeric_mapping(keys["data"])):
+        return "chart", {}
+    if has("images") or has("gallery"):
+        return "images", {}
+    if has("sources") or has("video") or has("audio"):
+        return "media", {}
+    if has("buttons") or has("actions"):
+        return "buttons", {}
+    for k in ("elements", "children", "components", "body", "questions", "fields", "items"):
+        if has(k) and _looks_like_elements(keys[k]):
+            return "section", {}
+    if has("items") and isinstance(keys["items"], list):
+        return "list", {}
+    link = next((keys[k] for k in ("url", "src", "href", "link", "image", "imageurl") if has(k)), None)
+    if isinstance(link, str) and as_url(link):
+        if _MEDIA_EXT.search(link):
+            return "media", {}
+        if _IMAGE_EXT.search(link) or has("alt") or has("alttext") or has("src") or has("image") or has("imageurl"):
+            return "image", {}
+        if any(has(k) for k in ("label", "title", "text")):
+            return "buttons", {"action": "open_url"}
+        return "image", {}
+    if has("rating") or has("stars"):
+        return "rating", {}
+    if has("progress") or has("percent") or has("percentage"):
+        return "progress", {}
+    if has("tone") and has("text"):
+        return "badge", {}
+    if has("text") or has("content") or has("markdown") or has("paragraph") or has("message") or has("body"):
+        return "text", {}
+    if any(has(k) for k in ("label", "question", "prompt", "placeholder", "required", "isrequired")):
+        return "text_input", {}
+    if has("title") or has("heading") or has("header"):
+        return "heading", {}
+    return None
+
+
+# ---------------------------------------------------------------- documentation
+
+def describe(canonical: str) -> dict:
+    spec = SPECS[canonical]
+    return {"type": canonical, "summary": spec.doc,
+            "fields": {name: list(aliases) for name, aliases in spec.fields.items()},
+            "also_called": sorted({n for n, (c, _) in TYPE_ALIASES.items() if c == canonical})[:25],
+            "example": spec.example}
+
+
+def reference_doc() -> str:
+    lines = ["Element reference (every field is optional unless the example shows it is needed; aliases in brackets):"]
+    for name in DOCUMENTED:
+        spec = SPECS[name]
+        lines.append(f"\n{name}: {spec.doc}")
+        for fname, aliases in spec.fields.items():
+            lines.append(f"    {fname}" + (f" [{', '.join(aliases)}]" if aliases else ""))
+    return "\n".join(lines)
+
+
+def json_schema() -> dict:
+    """Rich parameter schema with an enum of element types (small models follow enums well)."""
+    scalar = {"description": "Number (or date/time for date and time inputs)."}
+    element_props = {
+        "type": {"type": "string", "enum": DOCUMENTED},
+        "text": {"type": "string"}, "title": {"type": "string"}, "label": {"type": "string"},
+        "id": {"type": "string", "description": "Input submission key."},
+        "required": {"type": "boolean"}, "placeholder": {"type": "string"},
+        "value": {"description": "Initial value, or the number for progress/rating/metric/gauge."},
+        "options": {"type": "array", "items": {"type": "string"}, "description": "Choice options."},
+        "multiple": {"type": "boolean"}, "multiline": {"type": "boolean"},
+        "format": {"type": "string", "enum": ["text", "email", "tel", "url", "password"]},
+        "min": scalar, "max": scalar,
+        "items": {"type": "array", "items": {}, "description": "list: strings. metrics: [{label, value, change?, note?}]."},
+        "facts": {"type": "object", "description": "{label: value}", "additionalProperties": True},
+        "rows": {"type": "array", "items": {"type": "object", "additionalProperties": True}},
+        "chart_type": {"type": "string", "enum": ["bar", "horizontal_bar", "line", "pie", "donut", "stacked_bar", "grouped_bar", "gauge"]},
+        "data": {"type": "object", "description": "Chart data {label: number}.", "additionalProperties": True},
+        "series": {"type": "array", "description": "[{name, data: {label: number}}] for several series.",
+                   "items": {"type": "object", "additionalProperties": True}},
+        "url": {"type": "string"}, "alt": {"type": "string"},
+        "tone": {"type": "string", "enum": ["success", "warning", "danger", "info", "neutral"]},
+        "elements": {"type": "array", "description": "Child elements (section).", "items": {"$ref": "#/$defs/element"}},
+        "columns": {"type": "array", "description": "columns: [{title, elements}].",
+                    "items": {"type": "object", "properties": {"title": {"type": "string"},
+                                                               "elements": {"type": "array", "items": {"$ref": "#/$defs/element"}}}}},
+        "buttons": {"type": "array", "items": {"$ref": "#/$defs/button"}},
+    }
+    button = {"type": "object", "properties": {"label": {"type": "string"}, "url": {"type": "string", "description": "Opens this link. Omit to submit."},
+                                               "data": {"type": "object", "additionalProperties": True}}, "required": ["label"]}
+    request = {"type": "object", "properties": {
+        "title": {"type": "string"}, "subtitle": {"type": "string"}, "status": {"type": "string", "description": "Optional status badge next to the title."},
+        "elements": {"type": "array", "items": {"$ref": "#/$defs/element"}},
+        "submit_label": {"type": "string"}, "buttons": {"type": "array", "items": {"$ref": "#/$defs/button"}}},
+        "required": ["elements"]}
+    return {"type": "object", "properties": {"request": request}, "required": ["request"],
+            "$defs": {"element": {"type": "object", "properties": element_props, "required": ["type"], "additionalProperties": True},
+                      "button": button}}