@watt42/a2ui-component-catalog 0.1.0

package/catalog.json

@@ -0,0 +1,817 @@
+{
+  "catalogId": "watt42:a2ui:catalog:manifest:v1",
+  "catalogVersion": "manifest/2026.08.24.2",
+  "uiVersion": "v0.9.1",
+  "generated": {
+    "source": "manifests",
+    "command": "npm run generate:catalog --workspace=@watt42/a2ui-component-catalog"
+  },
+  "components": [
+    {
+      "name": "Button",
+      "description": "Clickable control that emits an A2UI action when selected.",
+      "version": "1.0.0",
+      "implementation": {
+        "source": "shadcn",
+        "base": "base",
+        "sourceVersion": "4.17.0"
+      },
+      "props": {
+        "label": {
+          "type": "string",
+          "required": true,
+          "description": "Text shown on the button. Not a React child tree."
+        },
+        "variant": {
+          "type": "string",
+          "required": false,
+          "default": "default",
+          "enum": [
+            "default",
+            "secondary",
+            "destructive",
+            "outline",
+            "ghost",
+            "link"
+          ],
+          "description": "Visual style (A2UI subset of shadcn Button variants)."
+        },
+        "size": {
+          "type": "string",
+          "required": false,
+          "default": "default",
+          "enum": [
+            "default",
+            "sm",
+            "lg",
+            "icon"
+          ],
+          "description": "Control size."
+        },
+        "disabled": {
+          "type": "boolean",
+          "required": false,
+          "default": false
+        },
+        "action": {
+          "type": "object",
+          "required": false,
+          "description": "ActionContract: { name, context }. Not { event: { name, context } }.",
+          "properties": {
+            "name": {
+              "type": "string",
+              "required": true,
+              "description": "UserActionHandler actionName."
+            },
+            "context": {
+              "type": "object",
+              "required": false,
+              "description": "Optional payload merged into handler context."
+            }
+          }
+        }
+      },
+      "allowedChildren": "none",
+      "supportedBy": [
+        "surface"
+      ],
+      "actions": {
+        "action": {
+          "type": "object",
+          "description": "Same schema as props.action (ActionContract)."
+        }
+      },
+      "events": [
+        {
+          "name": "action",
+          "description": "Fired on activate with ActionContract name and context."
+        }
+      ],
+      "dataBindings": {},
+      "llmGuidance": [
+        "Visible Button text is properties.label (required). Do not nest Label children (allowedChildren is none) and do not add a sibling Label that only repeats the same action text.",
+        "Actions use ActionContract { name, context } — not { event: { name, context } }.",
+        "Button has no hover-description property. For 'button with hover description' / hover help, emit a single HoverCard (triggerText + content) — do not invent properties.hoverDescription and do not emit a Button that repeats the same label."
+      ]
+    },
+    {
+      "name": "Card",
+      "description": "Container for grouped catalog components in the compiled A2UI tree. In UIIntent, Card accepts only the props listed below; allowedChildren is not a properties.children prop. Use Label for static copy and Carousel for slide navigation.",
+      "version": "1.0.0",
+      "implementation": {
+        "source": "shadcn",
+        "base": "base",
+        "sourceVersion": "4.17.0"
+      },
+      "props": {
+        "variant": {
+          "type": "string",
+          "required": false,
+          "default": "default",
+          "enum": [
+            "default",
+            "outline"
+          ],
+          "description": "Visual treatment. outline is an A2UI variant, not a shadcn Card API dump."
+        }
+      },
+      "allowedChildren": "any",
+      "supportedBy": [
+        "surface"
+      ],
+      "actions": {},
+      "events": [],
+      "dataBindings": {},
+      "llmGuidance": [
+        "Card may include a nested components array of child component specs ({ type, properties, title? }).",
+        "Use Card.components for grouped Labels and other catalog children.",
+        "Card title is rendered as the first Label.",
+        "Do not put nested specs in properties.children on Card."
+      ]
+    },
+    {
+      "name": "Carousel",
+      "description": "Horizontal slide container for catalog child components. Provide slide content with properties.slides as nested component specs; do not use properties.children.",
+      "version": "1.0.0",
+      "implementation": {
+        "source": "shadcn",
+        "base": "base",
+        "sourceVersion": "4.17.0"
+      },
+      "props": {
+        "title": {
+          "type": "string",
+          "required": false,
+          "description": "Optional heading above the carousel."
+        },
+        "showControls": {
+          "type": "boolean",
+          "required": false,
+          "default": true,
+          "description": "Show previous/next controls when there is more than one slide."
+        },
+        "slides": {
+          "type": "array",
+          "required": true,
+          "description": "Nested component specs for each slide: { type, properties, title? }.",
+          "items": {
+            "type": "object"
+          }
+        }
+      },
+      "allowedChildren": "any",
+      "supportedBy": [
+        "surface"
+      ],
+      "actions": {},
+      "events": [],
+      "dataBindings": {},
+      "llmGuidance": [
+        "Carousel uses properties.slides: a non-empty array of nested component specs ({ type, properties, title? }) — one entry per slide.",
+        "Do not use properties.children for Carousel.",
+        "Each slide should usually be a Label with properties.text set to the visible copy (title alone is not shown)."
+      ],
+      "nestedSpecProps": [
+        "slides"
+      ],
+      "defaultNestedTypes": [
+        "Label"
+      ]
+    },
+    {
+      "name": "Chart",
+      "description": "Line, bar, pie, or area chart using user-provided, static, demo, illustrative, or live values. Chart does not require an energy-system service. LLM uses ChartSpec only — never raw ECharts options.",
+      "version": "1.0.0",
+      "implementation": {
+        "source": "echarts",
+        "sourceVersion": "5.6.0",
+        "specVersion": "1.0.0"
+      },
+      "props": {
+        "chartType": {
+          "type": "string",
+          "required": true,
+          "enum": [
+            "line",
+            "bar",
+            "pie",
+            "area"
+          ],
+          "description": "A2UI chart kind. Maps to ECharts via normalizeChartSpec (renderer adapter, not intent normalize)."
+        },
+        "title": {
+          "type": "string",
+          "required": false
+        },
+        "categories": {
+          "type": "array",
+          "required": true,
+          "description": "Non-empty category labels (x-axis or pie names).",
+          "items": {
+            "type": "string"
+          }
+        },
+        "series": {
+          "type": "array",
+          "required": true,
+          "description": "Non-empty series. Each entry uses values, not ECharts data.",
+          "items": {
+            "type": "object",
+            "properties": {
+              "name": {
+                "type": "string",
+                "required": true
+              },
+              "values": {
+                "type": "array",
+                "required": true,
+                "items": {
+                  "type": "number"
+                }
+              }
+            }
+          }
+        },
+        "xLabel": {
+          "type": "string",
+          "required": false
+        },
+        "yLabel": {
+          "type": "string",
+          "required": false
+        },
+        "height": {
+          "type": "number",
+          "required": false,
+          "default": 360,
+          "description": "Pixel height; renderer clamps to 120–800."
+        }
+      },
+      "allowedChildren": "none",
+      "supportedBy": [
+        "surface"
+      ],
+      "actions": {},
+      "events": [],
+      "dataBindings": {},
+      "llmGuidance": [
+        "Chart uses ChartSpec only: chartType, categories, series[].values — never ECharts option, properties.type, or series data.",
+        "Chart supports user-provided, static, demo, and illustrative values for every catalog chartType, including pie.",
+        "Chart does not require a live data source.",
+        "Do not claim that Chart is limited to energy-system series.",
+        "When the user requests a chart with categories and values, render it without asking for confirmation.",
+        "For illustrative or sample chart data, use realistic values and describe the data as illustrative."
+      ]
+    },
+    {
+      "name": "DataTable",
+      "description": "Read-only tabular data display. Provide columns and rows as declarative data — no sorting, filtering, pagination, or row selection.",
+      "version": "1.0.0",
+      "implementation": {
+        "source": "shadcn",
+        "base": "base",
+        "sourceVersion": "4.17.0"
+      },
+      "props": {
+        "columns": {
+          "type": "array",
+          "required": true,
+          "description": "Non-empty column definitions.",
+          "items": {
+            "type": "object",
+            "properties": {
+              "key": {
+                "type": "string",
+                "required": true,
+                "description": "Row object key for this column."
+              },
+              "header": {
+                "type": "string",
+                "required": true,
+                "description": "Accessible column header text."
+              },
+              "align": {
+                "type": "string",
+                "required": false,
+                "enum": [
+                  "left",
+                  "center",
+                  "right"
+                ],
+                "default": "left",
+                "description": "Cell text alignment."
+              }
+            }
+          }
+        },
+        "rows": {
+          "type": "array",
+          "required": true,
+          "description": "Row objects. Each row must provide a value for every column key.",
+          "items": {
+            "type": "object"
+          }
+        },
+        "caption": {
+          "type": "string",
+          "required": false,
+          "description": "Accessible table caption."
+        },
+        "striped": {
+          "type": "boolean",
+          "required": false,
+          "default": true,
+          "description": "Zebra striping for row scanability."
+        }
+      },
+      "allowedChildren": "none",
+      "supportedBy": [
+        "surface"
+      ],
+      "actions": {},
+      "events": [],
+      "dataBindings": {},
+      "llmGuidance": [
+        "Provide rectangular data only. Every row must include a value for every column key.",
+        "DataTable is read-only. Do not request sorting, filtering, pagination, or row selection.",
+        "Use string or number cell values. Keep column keys stable across rows."
+      ]
+    },
+    {
+      "name": "Dialog",
+      "description": "Modal dialog for confirmation and decision flows. Body content uses catalog child components; footer actions use ActionContract.",
+      "version": "1.0.0",
+      "implementation": {
+        "source": "shadcn",
+        "base": "base",
+        "sourceVersion": "4.17.0"
+      },
+      "props": {
+        "title": {
+          "type": "string",
+          "required": true,
+          "description": "Accessible dialog title."
+        },
+        "description": {
+          "type": "string",
+          "required": false,
+          "description": "Accessible dialog description."
+        },
+        "primaryAction": {
+          "type": "object",
+          "required": false,
+          "description": "ActionContract for the primary footer action.",
+          "properties": {
+            "name": {
+              "type": "string",
+              "required": true,
+              "description": "UserActionHandler actionName."
+            },
+            "context": {
+              "type": "object",
+              "required": false,
+              "description": "Optional payload merged into handler context."
+            }
+          }
+        },
+        "primaryLabel": {
+          "type": "string",
+          "required": false,
+          "default": "Confirm",
+          "description": "Primary footer button label."
+        },
+        "secondaryAction": {
+          "type": "object",
+          "required": false,
+          "description": "ActionContract for the secondary/dismiss footer action.",
+          "properties": {
+            "name": {
+              "type": "string",
+              "required": true,
+              "description": "UserActionHandler actionName."
+            },
+            "context": {
+              "type": "object",
+              "required": false,
+              "description": "Optional payload merged into handler context."
+            }
+          }
+        },
+        "secondaryLabel": {
+          "type": "string",
+          "required": false,
+          "default": "Cancel",
+          "description": "Secondary footer button label."
+        }
+      },
+      "allowedChildren": "any",
+      "supportedBy": [
+        "surface"
+      ],
+      "actions": {
+        "primaryAction": {
+          "type": "object",
+          "description": "Same schema as props.primaryAction (ActionContract)."
+        },
+        "secondaryAction": {
+          "type": "object",
+          "description": "Same schema as props.secondaryAction (ActionContract)."
+        }
+      },
+      "events": [
+        {
+          "name": "primaryAction",
+          "description": "Fired when the primary footer action is activated."
+        },
+        {
+          "name": "secondaryAction",
+          "description": "Fired when the secondary footer action is activated."
+        }
+      ],
+      "dataBindings": {},
+      "llmGuidance": [
+        "Dialog does not expose an open prop. Give Dialog a stable id and pair it with a Button whose action.name is openDialog:<dialogComponentId> to open at runtime.",
+        "Use Dialog for confirmation and decision flows with title, optional description, body children, and footer actions.",
+        "Place dialog body content as nested catalog children in components[] on the Dialog node (body Label is content; do not duplicate the opener Button label).",
+        "Tab titles and Button labels are owned by those components — do not invent a second Label that only repeats the same control text."
+      ],
+      "defaultNestedTypes": [
+        "Label",
+        "Button"
+      ]
+    },
+    {
+      "name": "HoverCard",
+      "description": "Supplementary contextual information revealed on hover or focus. The trigger must remain understandable without the hover panel.",
+      "version": "1.0.0",
+      "implementation": {
+        "source": "shadcn",
+        "base": "base",
+        "sourceVersion": "4.17.0"
+      },
+      "props": {
+        "triggerText": {
+          "type": "string",
+          "required": true,
+          "description": "Visible, focusable trigger label."
+        },
+        "title": {
+          "type": "string",
+          "required": false,
+          "description": "Optional card heading."
+        },
+        "content": {
+          "type": "string",
+          "required": true,
+          "description": "Concise supplementary body text."
+        }
+      },
+      "allowedChildren": "none",
+      "supportedBy": [
+        "surface"
+      ],
+      "actions": {},
+      "events": [],
+      "dataBindings": {},
+      "llmGuidance": [
+        "HoverCard content is supplementary only. Do not place essential information or the only path to an important action inside the hover panel.",
+        "The trigger text must remain understandable on its own without the hover interaction.",
+        "For requests like 'button with hover description' or 'Get Started with hover help', emit a single HoverCard (triggerText + content). Do not also emit a Button with the same label — that duplicates controls and breaks layout.",
+        "Only add a sibling Button when a real ActionContract click is required AND use a different HoverCard.triggerText (for example 'What's this?'), never the same string as Button.label."
+      ]
+    },
+    {
+      "name": "Input",
+      "description": "Form field bound to the surface data model. A2UI does not expose the full HTML input API.",
+      "version": "1.0.0",
+      "implementation": {
+        "source": "shadcn",
+        "base": "base",
+        "sourceVersion": "4.17.0"
+      },
+      "props": {
+        "label": {
+          "type": "string",
+          "required": false,
+          "description": "Accessible field label."
+        },
+        "placeholder": {
+          "type": "string",
+          "required": false
+        },
+        "inputType": {
+          "type": "string",
+          "required": false,
+          "default": "text",
+          "enum": [
+            "text",
+            "number",
+            "email",
+            "textarea"
+          ],
+          "description": "A2UI input kinds. textarea is an A2UI convenience, not a separate component."
+        },
+        "value": {
+          "type": "object",
+          "required": false,
+          "description": "BindingContract: data-model path. Not a literal string in UIIntent.",
+          "properties": {
+            "path": {
+              "type": "string",
+              "required": true,
+              "description": "Data-model path, e.g. /form/email."
+            },
+            "mode": {
+              "type": "string",
+              "required": false,
+              "default": "readWrite",
+              "enum": [
+                "read",
+                "write",
+                "readWrite"
+              ]
+            }
+          }
+        }
+      },
+      "allowedChildren": "none",
+      "supportedBy": [
+        "surface"
+      ],
+      "actions": {},
+      "events": [],
+      "dataBindings": {
+        "value": {
+          "type": "object",
+          "description": "Same schema as props.value (BindingContract)."
+        }
+      },
+      "llmGuidance": [
+        "Field caption and placeholder are properties.label and properties.placeholder. Bind value with BindingContract { path, mode? } — not a literal string.",
+        "Do not add a separate Label that only duplicates the Input field name unless using Label.htmlFor for explicit association."
+      ]
+    },
+    {
+      "name": "Item",
+      "description": "Display row for list and summary content with optional media and trailing action. Primarily a presentation component.",
+      "version": "1.0.0",
+      "implementation": {
+        "source": "shadcn",
+        "base": "base",
+        "sourceVersion": "4.17.0"
+      },
+      "props": {
+        "title": {
+          "type": "string",
+          "required": true,
+          "description": "Primary heading text: plain string, or BindingContract { path } for a live bound value."
+        },
+        "description": {
+          "type": "string",
+          "required": false,
+          "description": "Secondary supporting text: plain string, or BindingContract { path } for a live bound value (e.g. Switch checked path)."
+        },
+        "variant": {
+          "type": "string",
+          "required": false,
+          "default": "default",
+          "enum": [
+            "default",
+            "outline",
+            "muted"
+          ],
+          "description": "Visual treatment."
+        },
+        "size": {
+          "type": "string",
+          "required": false,
+          "default": "default",
+          "enum": [
+            "default",
+            "sm",
+            "xs"
+          ],
+          "description": "Density."
+        },
+        "mediaType": {
+          "type": "string",
+          "required": false,
+          "default": "none",
+          "enum": [
+            "none",
+            "initials",
+            "image"
+          ],
+          "description": "Optional leading media. No icon registry."
+        },
+        "mediaValue": {
+          "type": "string",
+          "required": false,
+          "description": "Initials (1–2 chars) or image URL when mediaType is initials or image."
+        },
+        "actionLabel": {
+          "type": "string",
+          "required": false,
+          "description": "Trailing action button label. Optional."
+        },
+        "action": {
+          "type": "object",
+          "required": false,
+          "description": "ActionContract for the optional trailing action.",
+          "properties": {
+            "name": {
+              "type": "string",
+              "required": true,
+              "description": "UserActionHandler actionName."
+            },
+            "context": {
+              "type": "object",
+              "required": false,
+              "description": "Optional payload merged into handler context."
+            }
+          }
+        }
+      },
+      "allowedChildren": "none",
+      "supportedBy": [
+        "surface"
+      ],
+      "actions": {
+        "action": {
+          "type": "object",
+          "description": "Same schema as props.action (ActionContract)."
+        }
+      },
+      "events": [
+        {
+          "name": "action",
+          "description": "Fired when the optional trailing action is activated."
+        }
+      ],
+      "dataBindings": {
+        "description": {
+          "type": "object",
+          "description": "Optional BindingContract when description is bound to the data model."
+        },
+        "title": {
+          "type": "object",
+          "description": "Optional BindingContract when title is bound to the data model."
+        }
+      },
+      "llmGuidance": [
+        "Use Item for list rows and summary entries with title, optional description, and optional trailing action.",
+        "Item is primarily a display component; action and actionLabel are optional enhancements, not required for a valid Item.",
+        "For a live Switch/Input summary in an Item, bind description (or title) with { path } to the same path as Switch.checked or Input.value — booleans display as ON/OFF.",
+        "Do not use Item for form inputs; use Input or Switch instead."
+      ]
+    },
+    {
+      "name": "Label",
+      "description": "Accessible text for static copy or a live data-model value. Use a plain string for fixed captions, or BindingContract { path } for values that update with Input/Switch edits.",
+      "version": "1.0.0",
+      "implementation": {
+        "source": "shadcn",
+        "base": "base",
+        "sourceVersion": "4.17.0"
+      },
+      "props": {
+        "text": {
+          "type": "string",
+          "required": true,
+          "description": "Visible text: plain string, or BindingContract { path, mode? } for a live bound value. Not a React child tree."
+        },
+        "htmlFor": {
+          "type": "string",
+          "required": false,
+          "description": "Optional target control id when associating with another catalog control."
+        }
+      },
+      "allowedChildren": "none",
+      "supportedBy": [
+        "surface"
+      ],
+      "actions": {},
+      "events": [],
+      "dataBindings": {
+        "text": {
+          "type": "object",
+          "description": "Optional BindingContract when text is bound to the data model."
+        }
+      },
+      "llmGuidance": [
+        "Static captions use text as a plain string.",
+        "For values that should update when Input/Switch change, set text to BindingContract { path } pointing at the same path as the control (e.g. Input value.path or Switch checked.path).",
+        "Do not invent template strings like \"Status: {value}\"; use a static Label for the caption and a bound Label for the live value, or rely on Input.label / Switch.label."
+      ]
+    },
+    {
+      "name": "Switch",
+      "description": "Boolean toggle bound to the surface data model via BindingContract.",
+      "version": "1.0.0",
+      "implementation": {
+        "source": "shadcn",
+        "base": "base",
+        "sourceVersion": "4.17.0"
+      },
+      "props": {
+        "label": {
+          "type": "string",
+          "required": true,
+          "description": "Accessible label rendered beside the control."
+        },
+        "checked": {
+          "type": "object",
+          "required": false,
+          "description": "BindingContract: boolean path in the draft store.",
+          "properties": {
+            "path": {
+              "type": "string",
+              "required": true,
+              "description": "Data-model path, e.g. /settings/notifications."
+            },
+            "mode": {
+              "type": "string",
+              "required": false,
+              "default": "readWrite",
+              "enum": [
+                "read",
+                "write",
+                "readWrite"
+              ]
+            }
+          }
+        },
+        "disabled": {
+          "type": "boolean",
+          "required": false,
+          "default": false,
+          "description": "Disables interaction. Also forced when binding mode is read."
+        }
+      },
+      "allowedChildren": "none",
+      "supportedBy": [
+        "surface"
+      ],
+      "actions": {},
+      "events": [],
+      "dataBindings": {
+        "checked": {
+          "type": "object",
+          "description": "Same schema as props.checked (BindingContract)."
+        }
+      },
+      "llmGuidance": [
+        "Switch is the boolean toggle for simple settings. Use checked: { path } to bind to the data model.",
+        "Use Input for text entry and Switch for on/off settings on the same surface."
+      ]
+    },
+    {
+      "name": "Tabs",
+      "description": "Tabbed container that switches between catalog child panels. Each tab links a title to an existing child component id.",
+      "version": "1.0.0",
+      "implementation": {
+        "source": "shadcn",
+        "base": "base",
+        "sourceVersion": "4.17.0"
+      },
+      "props": {
+        "tabs": {
+          "type": "array",
+          "required": true,
+          "description": "Non-empty array of { title, child } entries. title is visible copy; child is the panel component id.",
+          "items": {
+            "type": "object"
+          }
+        },
+        "defaultTab": {
+          "type": "string",
+          "required": false,
+          "description": "Child component id for the initially selected tab. Defaults to the first tab entry."
+        }
+      },
+      "allowedChildren": "any",
+      "supportedBy": [
+        "surface"
+      ],
+      "actions": {},
+      "events": [],
+      "dataBindings": {},
+      "llmGuidance": [
+        "Tabs uses properties.tabs: a non-empty array of { title, child } entries.",
+        "Provide one nested panel component per tab in components[] (same order as tabs).",
+        "Set each tabs[].child to the panel component id (for example tab1, tab2, tab3).",
+        "Use string titles or {\"path\":\"...\"} for dynamic titles bound to the data model — tab trigger text is tabs[].title, not a separate Label control.",
+        "Do not use properties.children on Tabs; panel content is referenced by child ids."
+      ]
+    }
+  ],
+  "screenTypes": [
+    "dashboard",
+    "form",
+    "summary",
+    "confirmation",
+    "details",
+    "screen",
+    "chart"
+  ]
+}