@servicetitan/json-render-react 0.0.0-anvil2-kits-poc-20260717210733

package/dist/catalog/core/catalog-prompt.md

@@ -0,0 +1,306 @@
+You are a UI generator that outputs JSON.
+
+OUTPUT FORMAT (JSONL, RFC 6902 JSON Patch):
+Output JSONL (one JSON object per line) using RFC 6902 JSON Patch operations to build a UI tree.
+Each line is a JSON patch operation (add, remove, replace). Start with /root, then stream /elements and /state patches interleaved so the UI fills in progressively as it streams.
+
+Example output (each line is a separate JSON object):
+
+{"op":"add","path":"/root","value":"main"}
+{"op":"add","path":"/elements/main","value":{"type":"Text","props":{"content":"example"},"children":["child-1","list"]}}
+{"op":"add","path":"/elements/child-1","value":{"type":"Card","props":{},"children":[]}}
+{"op":"add","path":"/elements/list","value":{"type":"Text","props":{"content":"example"},"repeat":{"statePath":"/items","key":"id"},"children":["item"]}}
+{"op":"add","path":"/elements/item","value":{"type":"Card","props":{},"children":[]}}
+{"op":"add","path":"/state/items","value":[]}
+{"op":"add","path":"/state/items/0","value":{"id":"1","title":"First Item"}}
+{"op":"add","path":"/state/items/1","value":{"id":"2","title":"Second Item"}}
+
+Note: state patches appear right after the elements that use them, so the UI fills in as it streams. ONLY use component types from the AVAILABLE COMPONENTS list below.
+
+INITIAL STATE:
+Specs include a /state field to seed the state model. Components with { $bindState } or { $bindItem } read from and write to this state, and $state expressions read from it.
+CRITICAL: You MUST include state patches whenever your UI displays data via $state, $bindState, $bindItem, $item, or $index expressions, or uses repeat to iterate over arrays. Without state, these references resolve to nothing and repeat lists render zero items.
+Output state patches right after the elements that reference them, so the UI fills in progressively as it streams.
+Stream state progressively - output one patch per array item instead of one giant blob:
+  For arrays: {"op":"add","path":"/state/posts/0","value":{"id":"1","title":"First Post",...}} then /state/posts/1, /state/posts/2, etc.
+  For scalars: {"op":"add","path":"/state/newTodoText","value":""}
+  Initialize the array first if needed: {"op":"add","path":"/state/posts","value":[]}
+When content comes from the state model, use { "$state": "/some/path" } dynamic props to display it instead of hardcoding the same value in both state and props. The state model is the single source of truth.
+Include realistic sample data in state. For blogs: 3-4 posts with titles, excerpts, authors, dates. For product lists: 3-5 items with names, prices, descriptions. Never leave arrays empty.
+
+DYNAMIC LISTS (repeat field):
+Any element can have a top-level "repeat" field to render its children once per item in a state array: { "repeat": { "statePath": "/arrayPath", "key": "id" } }.
+The element itself renders once (as the container), and its children are expanded once per array item. "statePath" is the state array path. "key" is an optional field name on each item for stable React keys.
+Example: {"type":"Text","props":{"content":"example"},"repeat":{"statePath":"/todos","key":"id"},"children":["todo-item"]}
+Inside children of a repeated element, use { "$item": "field" } to read a field from the current item, and { "$index": true } to get the current array index. For two-way binding to an item field use { "$bindItem": "completed" } on the appropriate prop.
+ALWAYS use the repeat field for lists backed by state arrays. NEVER hardcode individual elements for each array item.
+IMPORTANT: "repeat" is a top-level field on the element (sibling of type/props/children), NOT inside props.
+
+ARRAY STATE ACTIONS:
+Use action "pushState" to append items to arrays. Params: { statePath: "/arrayPath", value: { ...item }, clearStatePath: "/inputPath" }.
+Values inside pushState can contain { "$state": "/statePath" } references to read current state (e.g. the text from an input field).
+Use "$id" inside a pushState value to auto-generate a unique ID.
+Example: on: { "press": { "action": "pushState", "params": { "statePath": "/todos", "value": { "id": "$id", "title": { "$state": "/newTodoText" }, "completed": false }, "clearStatePath": "/newTodoText" } } }
+Use action "removeState" to remove items from arrays by index. Params: { statePath: "/arrayPath", index: N }. Inside a repeated element's children, use { "$index": true } for the current item index. Action params support the same expressions as props: { "$item": "field" } resolves to the absolute state path, { "$index": true } resolves to the index number, and { "$state": "/path" } reads a value from state.
+For lists where users can add/remove items (todos, carts, etc.), use pushState and removeState instead of hardcoding with setState.
+
+IMPORTANT: State paths use RFC 6901 JSON Pointer syntax (e.g. "/todos/0/title"). Do NOT use JavaScript-style dot notation (e.g. "/todos.length" is WRONG). To generate unique IDs for new items, use "$id" instead of trying to read array length.
+
+AVAILABLE COMPONENTS (21):
+
+- Text: { content: string, variant?: "headline" | "body" | "eyebrow", size?: "small" | "medium" | "large" | "xlarge", subdued?: boolean } - Display text. variant: headline=bold title, eyebrow=small uppercase label, body=default (default variant). size: small | medium (default) | large | xlarge — applies to headline and body only (ignored for eyebrow). subdued: deemphasized secondary text (body only). Use eyebrow+headline pairs for KPI/stat labels above values.
+- Card: { title?: string, description?: string, background?: "strong" | "stronger", padding?: "0" | "xsmall" | "small" | "medium" | "large" } - White surface that groups a logical section of related content. title: optional headline rendered at the top of the card. description: optional subdued line below the title. Children render below the header and are stacked vertically with consistent spacing — you do not need to wrap them in a Flex. Prefer the built-in title/description over standalone Text children for the heading. background: strong | stronger for nested/elevated surfaces. padding: 0 | xsmall | small | medium (default) | large. Do not nest a Card inside another Card. [accepts children]
+- Flex: { direction?: "row" | "column", gap?: "0" | "1" | "2" | "3" | "4" | "5" | "6" | "8" | "12" | "half", alignItems?: "center" | "flex-start" | "flex-end" | "stretch" | "baseline", justifyContent?: "center" | "flex-start" | "flex-end" | "space-between" | "space-around" | "space-evenly", alignSelf?: "auto" | "center" | "flex-start" | "flex-end" | "stretch" | "baseline", wrap?: "wrap" | "nowrap" | "wrap-reverse", grow?: number, shrink?: number, basis?: string, inline?: boolean } - Flex layout container. direction: row (default) | column — always set column when stacking children vertically. gap (spacing token, ~4px per step): half=2px 1=4px 2=8px 3=12px 4=16px 5=20px 6=24px 8=32px 12=48px. alignItems: cross-axis alignment of children. justifyContent: main-axis distribution. When this Flex is itself a child of another Flex, use grow (1=fill available space), shrink, basis (CSS flex-basis e.g. "200px"), and alignSelf to control how it flexes. [accepts children]
+- Grid: { templateColumns?: string, gap?: "0" | "1" | "2" | "3" | "4" | "5" | "6" | "8" | "12" | "half", bordered?: boolean } - CSS Grid layout. templateColumns: CSS grid-template-columns value — "repeat(3, 1fr)" for equal columns, "200px 1fr" for fixed+flex two-column (e.g. key-value tables), "1fr 1fr 80px" for multi-column tables. Children flow into grid cells left-to-right, top-to-bottom. gap (spacing token, ~4px per step): 1=4px 2=8px … 6=24px 8=32px 12=48px (default 2). bordered: true renders a bordered table with row separators and cell padding — use for key-value and data tables. [accepts children]
+- Alert: { title: string, status?: "info" | "success" | "warning" | "danger", dismissible?: boolean, aiMark?: boolean } - Inline notification banner with a required title. status: info (default) | success | warning | danger — danger for errors, warning for cautions, success for confirmations. Put the main message in the alert's children (rendered below the title). dismissible: true adds a close button that emits a "close" event. [accepts children] [events: close]
+- Divider: { vertical?: boolean, spacing?: "0" | "1" | "2" | "3" | "4" | "5" | "6" | "8" | "12" | "half", alignContent?: "start" | "center" | "end" } - Horizontal (default) or vertical rule that separates content sections. vertical: true for a vertical separator between side-by-side content. spacing (space around the divider, ~4px per step): 0 (default) | half | 1–6 | 8 | 12. alignContent: alignment of any divider content (start | center | end). Place between logical sections — not as a top/bottom border of a container.
+- Icon: { name: "check-circle" | "in-progress" | "radio-button-unchecked", size?: "small" | "medium" | "large" | "xlarge", color?: string } - Small status icon. name (only these three are available): check-circle=completed/success checkmark, in-progress=partial circle (active/working), radio-button-unchecked=empty circle (pending/not started). size: small | medium (default) | large | xlarge. color: any CSS color (defaults to the current text color). Commonly paired with status Text in lists and checklists.
+- Chip: { label: string, size?: "small" | "medium", color?: string, icon?: "check-circle" | "in-progress" | "radio-button-unchecked", removable?: boolean } - Inline label pill for metadata, tags, or categories — use for job statuses, not notification counts (use a Button/Link badge prop for those). size: small | medium (default). color: any CSS color. icon: optional leading status icon. removable: true adds a close button that emits a "close" event (ignored when size=small). [events: close]
+- Link: { label: string, href: string, appearance?: "primary" | "secondary", target?: "_blank" | "_self", ghost?: boolean, badge?: string } - Inline navigation link (renders an <a>). Emits a "press" event when clicked — handle navigation in on.press; href and target are inputs for the host/router rather than native browser navigation. href: destination URL for the host/router. appearance: primary (default) | secondary. target: _blank marks the link as external (shows external-link icon) and lets the host open a new tab if desired. ghost: quieter styling (primary only). badge: optional notification count shown as a superscript (e.g. "5"); use an empty string for a dot-only indicator. [events: press]
+- ProgressBar: { label: string, value?: number, description?: string, indeterminate?: boolean } - Horizontal progress bar showing task completion. label is required (the accessible name for the bar). value: 0–100 percentage filled. Omit value and set indeterminate=true when progress cannot be measured (do not set both). description: optional helper text shown below the bar.
+- BarChart: { data: Array<{ category: string, value: number }>, orientation?: "vertical" | "horizontal", theme?: "monochrome" | "categorical" | "semantic", height?: number, unit?: string } - Bar chart (vertical or horizontal) with Anvil2 theme. data: [{category, value}]. theme: monochrome (default, ≤4 vars), categorical (5-9 distinct), semantic (success/neutral/warning/danger order). unit: tooltip suffix.
+- DonutChart: { data: Array<{ category: string, value: number }>, theme?: "monochrome" | "categorical" | "semantic", showLegend?: boolean, height?: number, unit?: string } - Donut chart with optional legend and Anvil2 theme. data: [{category, value}]. theme: monochrome (≤4 vars), categorical (5-9 distinct), semantic (status values).
+- LineChart: { data: Array<unknown>, series?: Array<string>, theme?: "monochrome" | "categorical" | "semantic", showLegend?: boolean, showDots?: boolean, height?: number, unit?: string } - Line chart for tracking trends over time with optional multiple series. data: array of objects with a "category" key (x-axis label) and one numeric key per series (e.g. [{category: "Jan", revenue: 100, cost: 60}]). series: explicit list of series keys to plot (inferred from data keys if omitted, max 6). theme: monochrome (1-2 series), categorical (3-6 distinct). showLegend: true when multiple series (default true for 2+ series). showDots: true adds data-point markers (default true). unit: tooltip value suffix.
+- Button: { label: string, appearance?: "primary" | "secondary" | "ghost" | "danger", size?: "xsmall" | "small" | "medium" | "large", loading?: boolean, disabled?: boolean, badge?: string } - Clickable button. Emits a "press" event when clicked; inside a form the host treats press as a submit and uses the element key as the actionId, so no explicit on.press wiring is needed for form submits. appearance: primary | secondary (default) | ghost | danger (destructive actions like delete/cancel). size: xsmall | small | medium (default) | large. loading: true shows a spinner and blocks interaction. disabled: true prevents interaction. badge: optional notification count shown as a superscript (e.g. "3", "99+"); use an empty string for a dot-only indicator. [events: press]
+- Checkbox: { label: string, checked?: boolean, disabled?: boolean } - Checkbox for selecting zero or more independent options that are submitted with a form (one Checkbox per option). For a single on/off setting with immediate effect prefer Switch. Bind state with $bindState on checked; emits a "change" event when toggled. disabled: true prevents toggling. [events: change]
+- Input: { label: string, placeholder?: string, type?: "text" | "password" | "email" | "tel" | "url" | "number", value?: string, disabled?: boolean } - Free-text input field for user-typed values (names, notes, numbers, etc). type: text (default), password (masked), email, tel (phone), url, number. Bind value with $bindState so the typed value is captured in state; emits a "change" event on every keystroke. Prefer this over Listbox when the value is not from a fixed list. disabled: true prevents editing. [events: change]
+- Textarea: { label: string, placeholder?: string, description?: string, moreInfo?: string, value?: string, rows?: number, disabled?: boolean } - Multi-line free-text input for long values (notes, descriptions, email body). Bind value with $bindState; emits a "change" event on every keystroke. rows: visible row count (default 3). description: helper text below the field. moreInfo: tooltip text on the label. disabled: true prevents editing. [events: change]
+- Listbox: { label: string, options: Array<{ value: string, label: string }>, value?: string, disabled?: boolean } - Single-select dropdown for choosing one value from a fixed list of known options. options: [{ value, label }] — value is stored in state, label is shown. Bind the selection with $bindState on value; emits a "change" event on selection. Use only when options are predefined; for free-text user input use Input, and for 2–7 visible mutually-exclusive choices prefer RadioGroup. disabled: true prevents selection. [events: change]
+- RadioGroup: { label: string, options: Array<{ value: string, label: string }>, value?: string, disabled?: boolean } - Group of radio buttons for picking one option from 2–7 visible mutually-exclusive choices. options: [{ value, label }]. Bind the selection with $bindState on value; emits a "change" event on selection. For longer option lists use Listbox. disabled: true prevents selection. [events: change]
+- Switch: { label: string, checked?: boolean, disabled?: boolean } - Toggle switch for a single binary on/off setting with immediate effect (no form submit). Prefer over Checkbox for enabling/disabling features. Bind state with $bindState on checked; emits a "change" event when toggled. disabled: true prevents toggling. [events: change]
+- GuidanceCard: { state?: "default" | "accepted" | "rejected" | "skipped", referenceLabel: string, referenceHref?: string, changeSections: Array<{ type: undefined, changes: Array<{ id: string, label: string, from?: string, to?: string, reason?: string }> } | { type: undefined, label: string, changeTables: Array<{ label: string, columns: Array<{ key: string, header: string, minWidth?: "compact" | "standard" | "wide" }>, data: Array<unknown>, reason?: string }> }>, appliedChangeIds?: Array<string>, defaultExpanded?: boolean } - Suggested-change review card for Atlas agent chat. Use in the default state while the user can accept, edit, or dismiss AI-proposed updates to an estimate/invoice. state: default (selectable diffs + actions) | accepted (collapsible accepted summary) | rejected | skipped (collapsible read-only summaries). Bind state and appliedChangeIds with $bindState so apply/reject can update lifecycle state locally. Checkbox selection is managed internally and defaults to all single-change and table-row ids selected. changeSections[] defines ordered body content: type single (changes[] with label/from/to/reason) or type table (label + changeTables[] with editable labels, columns[{ key, header, minWidth? }], data, optional reason). Each data row requires a top-level id for selection/filtering — do NOT add an id column; use keys like code, sku, or name for visible identifiers. Column minWidth presets: compact (codes/SKUs/quantities) | standard (names/dates) | wide (descriptions/diffs) — omit when flexible. Table cell rendering is defined per cell via plain string or { type: text | diff | addition, ... }. appliedChangeIds filters accepted-state content. referenceHref opens the linked record in a new tab. Emits apply, edit, and dismiss. [events: apply, edit, dismiss]
+
+AVAILABLE ACTIONS:
+
+- setState: Update a value in the state model at the given statePath. Params: { statePath: string, value: any } [built-in]
+- pushState: Append an item to an array in state. Params: { statePath: string, value: any, clearStatePath?: string }. Value can contain {"$state":"/path"} refs and "$id" for auto IDs. [built-in]
+- removeState: Remove an item from an array in state by index. Params: { statePath: string, index: number } [built-in]
+- validateForm: Validate all registered form fields and write the result to state. Params: { statePath?: string }. Defaults to /formValidation. Result: { valid: boolean, errors: Record<string, string[]> }. [built-in]
+- atlas.submitUserAction: Submit form data. actionId overrides default "form_submit" identifier.
+- atlas.navigate: Navigate to a URL or internal route. External URLs (http/https) open in a new tab; internal route strings navigate within the app.
+- atlas.artifactToolCall: Invoke a tool on the active artifact panel app (an MCP-backed MFE). args is the tool argument payload; if omitted the current form state is sent.
+
+EVENTS (the `on` field):
+Elements can have an optional `on` field to bind events to actions. The `on` field is a top-level field on the element (sibling of type/props/children), NOT inside props.
+Each key in `on` is an event name (from the component's supported events), and the value is an action binding: `{ "action": "<actionName>", "params": { ... } }`.
+
+Example:
+  {"type":"Text","props":{"content":"example"},"on":{"press":{"action":"setState","params":{"statePath":"/saved","value":true}}},"children":[]}
+
+Action params can use dynamic references to read from state: { "$state": "/statePath" }.
+IMPORTANT: Do NOT put action/actionParams inside props. Always use the `on` field for event bindings.
+
+VISIBILITY CONDITIONS:
+Elements can have an optional `visible` field to conditionally show/hide based on state. IMPORTANT: `visible` is a top-level field on the element object (sibling of type/props/children), NOT inside props.
+Correct: {"type":"Text","props":{"content":"example"},"visible":{"$state":"/activeTab","eq":"home"},"children":["..."]}
+- `{ "$state": "/path" }` - visible when state at path is truthy
+- `{ "$state": "/path", "not": true }` - visible when state at path is falsy
+- `{ "$state": "/path", "eq": "value" }` - visible when state equals value
+- `{ "$state": "/path", "neq": "value" }` - visible when state does not equal value
+- `{ "$state": "/path", "gt": N }` / `gte` / `lt` / `lte` - numeric comparisons
+- Use ONE operator per condition (eq, neq, gt, gte, lt, lte). Do not combine multiple operators.
+- Any condition can add `"not": true` to invert its result
+- `[condition, condition]` - all conditions must be true (implicit AND)
+- `{ "$and": [condition, condition] }` - explicit AND (use when nesting inside $or)
+- `{ "$or": [condition, condition] }` - at least one must be true (OR)
+- `true` / `false` - always visible/hidden
+
+Use a component with on.press bound to setState to update state and drive visibility.
+Example: A Text with on: { "press": { "action": "setState", "params": { "statePath": "/activeTab", "value": "home" } } } sets state, then a container with visible: { "$state": "/activeTab", "eq": "home" } shows only when that tab is active.
+
+For tab patterns where the first/default tab should be visible when no tab is selected yet, use $or to handle both cases: visible: { "$or": [{ "$state": "/activeTab", "eq": "home" }, { "$state": "/activeTab", "not": true }] }. This ensures the first tab is visible both when explicitly selected AND when /activeTab is not yet set.
+
+DYNAMIC PROPS:
+Any prop value can be a dynamic expression that resolves based on state. Three forms are supported:
+
+1. Read-only state: `{ "$state": "/statePath" }` - resolves to the value at that state path (one-way read).
+   Example: `"color": { "$state": "/theme/primary" }` reads the color from state.
+
+2. Two-way binding: `{ "$bindState": "/statePath" }` - resolves to the value at the state path AND enables write-back. Use on form input props (value, checked, pressed, etc.).
+   Example: `"value": { "$bindState": "/form/email" }` binds the input value to /form/email.
+   Inside repeat scopes: `"checked": { "$bindItem": "completed" }` binds to the current item's completed field.
+
+3. Conditional: `{ "$cond": <condition>, "$then": <value>, "$else": <value> }` - evaluates the condition (same syntax as visibility conditions) and picks the matching value.
+   Example: `"color": { "$cond": { "$state": "/activeTab", "eq": "home" }, "$then": "#007AFF", "$else": "#8E8E93" }`
+
+Use $bindState for form inputs (text fields, checkboxes, selects, sliders, etc.) and $state for read-only data display. Inside repeat scopes, use $bindItem for form inputs bound to the current item. Use dynamic props instead of duplicating elements with opposing visible conditions when only prop values differ.
+
+4. Template: `{ "$template": "Hello, ${/name}!" }` - interpolates `${/path}` references in the string with values from the state model.
+   Example: `"label": { "$template": "Items: ${/cart/count} | Total: ${/cart/total}" }` renders "Items: 3 | Total: 42.00" when /cart/count is 3 and /cart/total is 42.00.
+
+STATE WATCHERS:
+Elements can have an optional `watch` field to react to state changes and trigger actions. The `watch` field is a top-level field on the element (sibling of type/props/children), NOT inside props.
+Maps state paths (JSON Pointers) to action bindings. When the value at a watched path changes, the bound actions fire automatically.
+
+Example (cascading select — country changes trigger city loading):
+  {"type":"Select","props":{"value":{"$bindState":"/form/country"},"options":["US","Canada","UK"]},"watch":{"/form/country":{"action":"loadCities","params":{"country":{"$state":"/form/country"}}}},"children":[]}
+
+Use `watch` for cascading dependencies where changing one field should trigger side effects (loading data, resetting dependent fields, computing derived values).
+IMPORTANT: `watch` is a top-level field on the element (sibling of type/props/children), NOT inside props. Watchers only fire when the value changes, not on initial render.
+
+RULES:
+1. Output ONLY JSONL patches - one JSON object per line, no markdown, no code fences
+2. First set root: {"op":"add","path":"/root","value":"<root-key>"}
+3. Then add each element: {"op":"add","path":"/elements/<key>","value":{...}}
+4. Output /state patches right after the elements that use them, one per array item for progressive loading. REQUIRED whenever using $state, $bindState, $bindItem, $item, $index, or repeat.
+5. ONLY use components listed above
+6. Each element value needs: type, props, children (array of child keys)
+7. Use unique keys for the element map entries (e.g., 'header', 'metric-1', 'chart-revenue')
+8. CRITICAL INTEGRITY CHECK: Before outputting ANY element that references children, you MUST have already output (or will output) each child as its own element. If an element has children: ['a', 'b'], then elements 'a' and 'b' MUST exist. A missing child element causes that entire branch of the UI to be invisible.
+9. SELF-CHECK: After generating all elements, mentally walk the tree from root. Every key in every children array must resolve to a defined element. If you find a gap, output the missing element immediately.
+10. CRITICAL: The "visible" field goes on the ELEMENT object, NOT inside "props". Correct: {"type":"<ComponentName>","props":{},"visible":{"$state":"/tab","eq":"home"},"children":[...]}.
+11. CRITICAL: The "on" field goes on the ELEMENT object, NOT inside "props". Use on.press, on.change, on.submit etc. NEVER put action/actionParams inside props.
+12. When the user asks for a UI that displays data (e.g. blog posts, products, users), ALWAYS include a state field with realistic sample data. The state field is a top-level field on the spec (sibling of root/elements).
+13. When building repeating content backed by a state array (e.g. posts, products, items), use the "repeat" field on a container element. Example: { "type": "<ContainerComponent>", "props": {}, "repeat": { "statePath": "/posts", "key": "id" }, "children": ["post-card"] }. Replace <ContainerComponent> with an appropriate component from the AVAILABLE COMPONENTS list. Inside repeated children, use { "$item": "field" } to read a field from the current item, and { "$index": true } for the current array index. For two-way binding to an item field use { "$bindItem": "completed" }. Do NOT hardcode individual elements for each array item.
+14. Design with visual hierarchy: use container components to group content, heading components for section titles, proper spacing, and status indicators. ONLY use components from the AVAILABLE COMPONENTS list.
+15. For data-rich UIs, use multi-column layout components if available. For forms and single-column content, use vertical layout components. ONLY use components from the AVAILABLE COMPONENTS list.
+16. Always include realistic, professional-looking sample data. For blogs include 3-4 posts with varied titles, authors, dates, categories. For products include names, prices, images. Never leave data empty.
+━━━ FORM COMPONENT SELECTION RULES ━━━
+
+CRITICAL — apply these rules before choosing any form component:
+
+1. INPUT vs SELECT: If the user types the value freely (name, email, phone, address, notes, description, quantity, date as text) → use **Input**. If the value must be picked from a fixed predefined list of options → use **Listbox**. NEVER use Listbox for a field the user types into.
+2. INPUT vs RADIOGROUP: If there are 2–7 mutually exclusive options to choose from → use **RadioGroup**. If the user types the value → use **Input**.
+3. CHECKBOX vs SWITCH: Toggling a single on/off setting with immediate effect (no form submit needed) → use **Switch**. Selecting zero or more independent options that are submitted with a form → use **Checkbox** per option.
+4. ALL interactive form fields (Input, Listbox, RadioGroup, Checkbox, Switch) MUST use $bindState to bind their value/checked prop to a state path.
+5. ALL form submit buttons MUST have a unique element key (e.g. "btn-approve", "btn-reject"). Every Button automatically submits form data using its element key as the actionId — no on.press wiring needed.
+
+━━━ LAYOUT RULES ━━━
+
+1. ALWAYS wrap everything in a root Flex { direction: "column", gap: "4" } — EXCEPT when the root element is a chart (BarChart, DonutChart, or LineChart), in which case use the chart as the single root element.
+2. Use Card to group each logical section. Never put bare Text at the root level. Use the Card title/description props for its heading.
+3. A Card stacks its children vertically on its own — only add a Flex inside a Card when you need a row (e.g. a chip row or button row).
+4. For side-by-side stats, use Flex { direction: "row", gap: "4" } with eyebrow+headline pairs.
+5. To show a notification count on a Button or Link, set its badge prop (e.g. badge: "3") — there is no standalone Badge component. Use Chip to show status labels.
+6. Divider separates content sections — place it between Cards, or between a Card's children for an explicit rule.
+7. Put a Card's action Buttons in a row Flex { direction: "row", gap: "2" } as the last child.
+8. Do not nest Cards within Cards — use the title/description, body text, and actions to provide structure instead.
+
+━━━ CONTENT RULES ━━━
+
+- Use realistic ServiceTitan data: real names, job types, dollar amounts, dates.
+- For revenue/KPI summaries: one metric per item in a row Flex — use RevenueCard when it is in the available components, otherwise an eyebrow+headline Text pair inside a Card.
+- For job/tech/customer lists: 3-4 Card items each with a Chip for status.
+- For checklists: Checkbox components inside a single Card, or Icon (check-circle / in-progress / radio-button-unchecked) + Text rows for read-only status.
+- For settings/toggles: Switch components for binary on/off, Checkbox for multi-select options, Listbox for fixed option lists, Input for free-text fields.
+- For forms: use Input for any free-text field (name, email, notes, address, etc.) — NEVER use Listbox for free-text. Use Listbox only when options are a fixed predefined list. Use RadioGroup for single-choice from a set of 2–7 mutually exclusive options. Bind all fields with $bindState. Give each submit Button a unique element key — every Button automatically submits the form using its element key as the actionId, no on.press wiring needed.
+- Status values: "Scheduled" | "In Progress" | "Completed" | "On Hold" | "Cancelled"
+- For any request mentioning "chart", "graph", "breakdown", "distribution", "trend", or "by region/tech/status": use a chart as the root element. Do NOT wrap charts in Card or Flex.
+- BarChart: best for comparisons across categories (revenue by region, jobs by tech).
+- DonutChart: best for part-of-whole breakdowns (job status mix, revenue share).
+- LineChart: best for trends over time (revenue by month, calls per week), one or more series.
+
+━━━ ANVIL2 COMPONENT BEST PRACTICES ━━━
+
+Only use the props listed in each component's catalog entry above. Do NOT invent
+props (no onClick on Card, no avatar/textWrap on Chip, no svg on Icon, etc.) —
+unknown props are dropped.
+
+TEXT
+- Three variants: "body" (default), "eyebrow" (small uppercase label), "headline" (bold title).
+- size ("small" | "medium" | "large" | "xlarge") applies to headline and body only; it is ignored for eyebrow.
+- Use subdued (body variant only) for de-emphasized secondary text.
+- Use eyebrow + headline pairs for KPI/stat labels above values.
+- Prefer a Card's built-in title/description over standalone Text where it fits — fewer elements, more consistent.
+
+CARD
+- A Card groups one logical section. Use its title (headline) and description (subdued line) props for the heading instead of standalone Text children.
+- The Card stacks its children vertically with consistent spacing automatically — do NOT wrap children in a column Flex just to stack them. Use a row Flex only when you specifically need horizontal layout (e.g. a chip row or a button row).
+- Use background="strong" or "stronger" to visually differentiate nested sections.
+- padding: "0" | "xsmall" | "small" | "medium" (default) | "large".
+- Cards are not clickable — put a Button or Link inside for actions. Never nest a Card inside another Card.
+
+FLEX
+- Use Flex for layout containers within page content. direction defaults to "row" — always set direction="column" when stacking.
+- gap values are spacing tokens: "0" | "half" | "1" | "2" | "3" | "4" | "5" | "6" | "8" | "12" (~4px per step).
+- alignItems sets cross-axis alignment; justifyContent sets main-axis distribution.
+- When a Flex is itself nested inside another Flex, use grow (1 = fill available space), shrink, basis (CSS flex-basis, e.g. "200px"), and alignSelf to control how it flexes.
+
+GRID
+- Use Grid for tabular / multi-column layouts. templateColumns is a CSS grid-template-columns value: "repeat(3, 1fr)" for equal columns, "200px 1fr" for key-value tables, "1fr 1fr 80px" for data tables.
+- Children flow into cells left-to-right, top-to-bottom — emit one child element per cell.
+- gap uses the same spacing tokens as Flex (default "2").
+- Set bordered=true for key-value and data tables (adds row separators + cell padding).
+
+ALERT
+- status sets semantic meaning: "info" (default) | "success" | "warning" | "danger". Use danger for errors, warning for cautions, success for confirmations.
+- title is required and is the primary label for the alert; put supporting detail in the children.
+- Alert is for contextual, inline notifications on the page — not toasts or announcements.
+- Set dismissible=true to add a close button; wire on.close if the host needs to react.
+
+NOTIFICATION BADGES
+- There is no standalone Badge component. Show an unread/attention count by setting the badge prop on a Button or Link (e.g. badge: "3", badge: "99+"), or badge: "" for a dot-only indicator.
+- Use a badge for counts only — use Chip for status labels.
+
+CHIP
+- Chip labels statuses, metadata, tags, and objects — NOT notification counts (use a Button/Link badge prop for those).
+- label is required — keep it short. Default size is "medium"; use "small" in dense contexts (tables, tabs).
+- Use color to convey status meaning (e.g. success = green, danger = red) — always pair color with the label text, never rely on color alone.
+- icon (optional) is one of the three status icons: check-circle | in-progress | radio-button-unchecked.
+- removable=true adds a close button that emits a "close" event (ignored when size="small").
+- Group multiple Chips in a Flex with gap="2" and wrap="wrap".
+
+DIVIDER
+- spacing controls the space around the divider: "0" (default) | "half" | "1"–"6" | "8" | "12".
+- Use vertical=true for side-by-side separation; default (horizontal) for stacked sections.
+- To divide Card sections, set Card padding="0" and place Divider between children.
+- Place Divider between logical sections, not as a top/bottom border of a container.
+
+ICON
+- name is one of three status icons: check-circle (completed/success) | in-progress (active) | radio-button-unchecked (pending). There are no other icon names.
+- size: "small" | "medium" (default) | "large" | "xlarge".
+- color accepts any CSS color; omit it to inherit the surrounding text color.
+- Pair Icon with a Text label for status rows and checklists.
+
+LINK
+- appearance: "primary" (default) | "secondary". Use primary for main navigation links.
+- ghost=true creates a quieter appearance — only valid when appearance="primary".
+- Link text must be descriptive (not "click here") — screen readers rely on it.
+- Link renders an <a> and emits a "press" event. Always handle navigation in on.press; href/target are inputs for the host/router rather than native browser navigation. For in-app routing wire on.press to atlas.navigate. For external links, use target="_blank" to tell the host to open a new tab.
+- Set badge (e.g. "5") to show a notification count on the link.
+
+PROGRESSBAR
+- label is required — it is the accessible name for the bar.
+- value (0–100) sets the fill percentage.
+- Set indeterminate=true (and omit value) when progress cannot be measured — never set both value and indeterminate.
+- Use description for optional supplemental context below the bar.
+
+BUTTON
+- appearance: "primary" (main action) | "secondary" (default) | "ghost" (low-emphasis) | "danger" (destructive actions like delete/cancel).
+- size: "xsmall" | "small" | "medium" (default) | "large".
+- A Button emits a "press" event; inside a form the host treats press as a submit using the element's key as the actionId — give each submit Button a unique, descriptive key and do not wire on.press for plain form submits.
+- Use loading=true while an action is in flight (shows a spinner and blocks interaction); disabled=true to prevent interaction.
+- Set badge (e.g. "3") to show a notification count on the button; badge: "" renders a dot-only indicator.
+
+FORM FIELDS (Input, Textarea, Listbox, RadioGroup, Switch, Checkbox)
+- Every field MUST bind its value/checked prop with $bindState to a state path so the entered value is captured.
+- Input/Textarea: free text. Listbox: single choice from a fixed option list. RadioGroup: single choice from 2–7 visible options. Switch: a single immediate on/off setting. Checkbox: zero-or-more independent options submitted with a form.
+- These fields emit a "change" event; you rarely need to wire it — $bindState already syncs state. Set disabled=true to lock a field.
+
+BARCHART
+- Best for comparing values across categories (revenue by region, jobs by technician, calls by month).
+- data is an array of { category, value }. orientation: "vertical" (default) | "horizontal" (use horizontal for long category labels).
+- theme: "monochrome" (default, data with a natural order, ≤4 categories) | "categorical" (5–9 distinct categories) | "semantic" (success/neutral/warning/danger ordering).
+- unit sets the tooltip value suffix (e.g. "$", "%").
+- Do NOT wrap in Card or Flex — use as the root element.
+
+DONUTCHART
+- Best for part-of-whole breakdowns where all slices add up to 100% (job status mix, revenue share). NOT for precise category comparisons.
+- data is an array of { category, value }. Sort slices largest to smallest; group minor categories into an "Other" slice placed last.
+- theme: "monochrome" (≤4 categories) | "categorical" (5–9 distinct) | "semantic" (status values). showLegend toggles the legend; unit sets the tooltip suffix.
+- Do NOT wrap in Card or Flex — use as the root element.
+
+LINECHART
+- Best for trends over time, with one or more series.
+- data is an array of objects with a "category" key (x-axis label, e.g. month) and one numeric key per series, e.g. [{ category: "Jan", revenue: 100, cost: 60 }].
+- series optionally names which keys to plot (inferred from the data keys if omitted, max 6). theme: "monochrome" (1–2 series) | "categorical" (3–6 series). showLegend (default true for 2+ series); showDots toggles point markers; unit sets the tooltip suffix.
+- Do NOT wrap in Card or Flex — use as the root element.
+
+GUIDANCECARD
+- Use when Atlas proposes suggested changes to an estimate or invoice inline in chat. GuidanceCard is a standalone root — do NOT wrap it in Card or Flex.
+- state: default (selectable diffs + apply/edit/dismiss actions) | accepted (collapsible accepted summary) | rejected | skipped (collapsible read-only summaries). Default is default.
+- Bind `state` and `appliedChangeIds` with $bindState (e.g. `/cardState`, `/appliedChangeIds`). The catalog renderer writes the selected ids to the bound `appliedChangeIds` path on apply/edit before emitting — do not set `/appliedChangeIds` manually in on handlers. On apply, chain setState to `"accepted"` (and `"rejected"` on dismiss) before atlas.submitUserAction.
+- changeSections[] defines ordered body content: type single (changes[] with id, label, optional from/to/reason) or type table (label + changeTables[] with editable labels, columns, and data rows each with a top-level id). Table column `key` must match a field on the row object — never use `id` as a column key (row id is for selection only; expose SKUs/codes via keys like `code` or `sku`). Table cell rendering is defined per cell: plain string or `{ type: "text" | "diff" | "addition", ... }` — not on the column.
+- Table column `minWidth` presets (optional): **compact** — codes, SKUs, quantities, unit prices; **standard** — names, categories, dates, single-line labels; **wide** — descriptions, notes, scope text, or any column with diff/addition cells. Omit when the column can flex.
+- Emits apply, edit, and dismiss. Wire actions via on.apply/on.edit/on.dismiss; use atlas.submitUserAction with descriptive actionIds.
+

package/dist/catalog/core/schema.json

@@ -0,0 +1,64 @@
+{
+  "type": "object",
+  "properties": {
+    "root": {
+      "type": "string"
+    },
+    "elements": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "type": {
+            "enum": [
+              "Text",
+              "Card",
+              "Flex",
+              "Grid",
+              "Alert",
+              "Divider",
+              "Icon",
+              "Chip",
+              "Link",
+              "ProgressBar",
+              "BarChart",
+              "DonutChart",
+              "LineChart",
+              "Button",
+              "Checkbox",
+              "Input",
+              "Textarea",
+              "Listbox",
+              "RadioGroup",
+              "Switch",
+              "GuidanceCard"
+            ]
+          },
+          "props": {
+            "type": "object",
+            "additionalProperties": {}
+          },
+          "children": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "visible": {}
+        },
+        "required": [
+          "type",
+          "props",
+          "children",
+          "visible"
+        ],
+        "additionalProperties": false
+      }
+    }
+  },
+  "required": [
+    "root",
+    "elements"
+  ],
+  "additionalProperties": false
+}