feat: add field-control archetype and new form components

Add support for input, textarea, checkbox and radio-group components following the field-control semantic archetype:
- Extend component schemas and validation for boolean/numeric typed props
- Add runtime renderer support for field-control components with label/control/description structure
- Update test fixtures and validation tests for new form components
- Update documentation and roadmap to reflect current component adoption progress
- Add proper prop coercion for boolean and numeric values in render mappings

Author: Sayhi-bzb

README.md

@@ -98,7 +98,10 @@ The schema is the public contract. Agents write content structure, not raw HTML,
 │
 ╰──────────────
 ```
+thanks:
+- [Linux DO](linux.do)
 
+## Ref
 - [Quick Start](https://agent-html.pages.dev/docs)
 - [Best Practice](https://agent-html.pages.dev/docs/best-practice)
 - [Dev Docs](https://agent-html.pages.dev/docs/dev-docs)

packages/ahtml/src/cli/cli-test-helpers.ts

@@ -26,6 +26,17 @@ export const validAgentHtmlFixtures = [
     '<meta-agent profile="ops-compact" />',
     '<page title="Dashboard"><card title="Queue">Ready.</card></page>',
   ].join("\n"),
+  [
+    '<page title="Review Form">',
+    '  <card title="Decision">',
+    '    <checkbox label="Ship now" checked="true" description="Boolean field." />',
+    '    <radio-group label="Direction" value="ship" description="Single-select field.">',
+    '      <option value="ship" label="Ship">Use the current direction.</option>',
+    '      <option value="hold" label="Hold">Wait for the guard.</option>',
+    "    </radio-group>",
+    "  </card>",
+    "</page>",
+  ].join("\n"),
 ]
 
 export type CliSchemaOutput = {

packages/ahtml/src/cli/runtime-renderability.mjs

@@ -12,6 +12,9 @@ const rendererSpecScalarFields = [
   "requiredRegistryItem",
   "kind",
   "component",
+  "control",
+  "label",
+  "description",
   "root",
   "title",
   "titleContainer",
@@ -24,11 +27,15 @@ const rendererSpecScalarFields = [
   "headerCell",
   "bodyCell",
   "item",
+  "labelClassName",
+  "descriptionClassName",
   "itemSlot",
   "rowSlot",
   "cellSlot",
   "rootClassName",
   "titleClassName",
+  "labelProp",
+  "descriptionProp",
   "titleProp",
   "defaultProp",
   "fallback",

packages/ahtml/src/cli/runtime-surface.test.ts

@@ -436,7 +436,7 @@ async function createRuntimeFixture({
   )
   await writeFile(
     path.join(runtimePaths.runtimeSrcDir, "renderer", "kinds.ts"),
-    'export const runtimeRendererKinds = ["collection","compound","interactive-collection","primitive","table","tabs"] as const\nexport type RendererKind = (typeof runtimeRendererKinds)[number]\n',
+    'export const runtimeRendererKinds = ["collection","compound","field-control","interactive-collection","primitive","table","tabs"] as const\nexport type RendererKind = (typeof runtimeRendererKinds)[number]\n',
   )
   await writeFile(
     path.join(runtimePaths.runtimeSrcDir, "renderer", "parity.ts"),
@@ -608,6 +608,10 @@ function getRequiredComponentExports(component: string) {
     alert: ["Alert", "AlertDescription", "AlertTitle"],
     badge: ["Badge"],
     card: ["Card", "CardContent", "CardHeader", "CardTitle"],
+    checkbox: ["Checkbox"],
+    input: ["Input"],
+    progress: ["Progress"],
+    "radio-group": ["RadioGroup", "RadioGroupItem"],
     separator: ["Separator"],
     table: [
       "Table",
@@ -617,6 +621,7 @@ function getRequiredComponentExports(component: string) {
       "TableHeader",
       "TableRow",
     ],
+    textarea: ["Textarea"],
     tabs: ["Tabs", "TabsContent", "TabsList", "TabsTrigger"],
   }
   const exports = exportMap[component]

packages/ahtml/src/cli/runtime-template/src/renderer/kinds.ts

@@ -1,6 +1,7 @@
 export const runtimeRendererKinds = [
   "collection",
   "compound",
+  "field-control",
   "interactive-collection",
   "primitive",
   "table",

packages/ahtml/src/cli/runtime-template/src/renderer/render-node.test.ts

@@ -152,6 +152,180 @@ describe("createRendererNode", () => {
     expect(markup).toContain('value="0"')
   })
 
+  it("renders field-control components with visible labels and default values", () => {
+    const rendererSpecByName = new Map([
+      [
+        "textarea",
+        {
+          name: "textarea",
+          kind: "field-control",
+          renderKind: "field-control",
+          slots: [{ name: "children", children: [] }],
+          root: "div",
+          label: "p",
+          control: "textarea",
+          description: "p",
+          rootClassName: "grid gap-2",
+          labelClassName: "label",
+          descriptionClassName: "description",
+          labelProp: "label",
+          descriptionProp: "description",
+          propMappings: [
+            { prop: "value", target: "defaultValue" },
+            { prop: "label", target: "aria-label" },
+          ],
+        },
+      ],
+    ])
+
+    const RendererNode = createRendererNode(rendererSpecByName)
+    const markup = renderToStaticMarkup(
+      React.createElement(RendererNode, {
+        node: {
+          type: "component",
+          name: "textarea",
+          props: {
+            label: "Notes",
+            value: "Ship after the guard lands.",
+            description: "Long-form field.",
+          },
+          children: [],
+        },
+      }),
+    )
+
+    expect(markup).toContain('data-agent-html-component="textarea"')
+    expect(markup).toContain("<p class=\"label\">Notes</p>")
+    expect(markup).toContain(
+      "<textarea aria-label=\"Notes\">Ship after the guard lands.</textarea>",
+    )
+    expect(markup).toContain('aria-label="Notes"')
+    expect(markup).toContain("<p class=\"description\">Long-form field.</p>")
+  })
+
+  it("renders checkbox field-control components with boolean prop coercion", () => {
+    const rendererSpecByName = new Map([
+      [
+        "checkbox",
+        {
+          name: "checkbox",
+          kind: "field-control",
+          renderKind: "field-control",
+          slots: [{ name: "children", children: [] }],
+          root: "div",
+          label: "p",
+          control: "input",
+          description: "p",
+          rootClassName: "grid gap-2",
+          labelClassName: "label",
+          descriptionClassName: "description",
+          labelProp: "label",
+          descriptionProp: "description",
+          propMappings: [
+            { prop: "checked", target: "defaultChecked", coerce: "boolean" },
+            { prop: "label", target: "aria-label" },
+          ],
+        },
+      ],
+    ])
+
+    const RendererNode = createRendererNode(rendererSpecByName)
+    const markup = renderToStaticMarkup(
+      React.createElement(RendererNode, {
+        node: {
+          type: "component",
+          name: "checkbox",
+          props: {
+            label: "Ship now",
+            checked: "true",
+            description: "Boolean field.",
+          },
+          children: [],
+        },
+      }),
+    )
+
+    expect(markup).toContain("<p class=\"label\">Ship now</p>")
+    expect(markup).toContain("<input")
+    expect(markup).toContain('aria-label="Ship now"')
+    expect(markup).toContain("checked")
+    expect(markup).toContain("<p class=\"description\">Boolean field.</p>")
+  })
+
+  it("renders radio-group field-control components with option children", () => {
+    const rendererSpecByName = new Map([
+      [
+        "radio-group",
+        {
+          name: "radio-group",
+          kind: "field-control",
+          renderKind: "field-control",
+          slots: [
+            {
+              name: "option",
+              childNames: ["option"],
+              children: ["text"],
+            },
+          ],
+          root: "div",
+          label: "p",
+          control: "RadioGroup",
+          item: "RadioGroupItem",
+          itemSlot: "option",
+          itemValueProp: "value",
+          itemHeadingProp: "label",
+          description: "p",
+          rootClassName: "grid gap-3",
+          labelClassName: "label",
+          descriptionClassName: "description",
+          labelProp: "label",
+          descriptionProp: "description",
+          propMappings: [
+            { prop: "value", target: "defaultValue" },
+            { prop: "label", target: "aria-label" },
+          ],
+        },
+      ],
+    ])
+
+    const RendererNode = createRendererNode(rendererSpecByName)
+    const markup = renderToStaticMarkup(
+      React.createElement(RendererNode, {
+        node: {
+          type: "component",
+          name: "radio-group",
+          props: {
+            label: "Direction",
+            value: "ship",
+            description: "Single-select field.",
+          },
+          children: [
+            {
+              type: "component",
+              name: "option",
+              props: { value: "ship", label: "Ship" },
+              children: [{ type: "text", value: "Use the current direction." }],
+            },
+            {
+              type: "component",
+              name: "option",
+              props: { value: "hold", label: "Hold" },
+              children: [{ type: "text", value: "Wait for the guard." }],
+            },
+          ],
+        },
+      }),
+    )
+
+    expect(markup).toContain("<p class=\"label\">Direction</p>")
+    expect(markup).toContain("<RadioGroup")
+    expect(markup).toContain('aria-label="Direction"')
+    expect(markup).toContain("<RadioGroupItem")
+    expect(markup).toContain(">Ship</span>")
+    expect(markup).toContain("Use the current direction.")
+    expect(markup).toContain("<p class=\"description\">Single-select field.</p>")
+  })
+
   it("renders a no-script fallback for accordion items when configured", () => {
     const rendererSpecByName = new Map([
       [