@servicetitan/json-render-react 0.2.0 → 0.3.0

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

@@ -46,29 +46,28 @@ For lists where users can add/remove items (todos, carts, etc.), use pushState a
 
 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, el?: "h1" | "h2" | "h3" | "h4" | "h5" | "h6" } - Display text. variant: headline=bold title, eyebrow=small label, body=default. size: small/medium/large/xlarge (headline and body only). subdued: deemphasized body text. el: heading element for variant=headline (default h3).
-- Card: { background?: "strong" | "stronger", padding?: "0" | "xsmall" | "small" | "medium" | "large" } - White surface with padding; groups related content. background: strong | stronger for elevated surfaces. padding: 0 | xsmall | small | medium (default) | large. [accepts children]
-- Flex: { direction?: "row" | "column", gap?: "1" | "2" | "3" | "4" | "5" | "6", alignItems?: "center" | "flex-start" | "flex-end" | "stretch" | "baseline", justifyContent?: "center" | "flex-start" | "flex-end" | "space-between" | "space-around" | "space-evenly", wrap?: "wrap" | "nowrap" | "wrap-reverse", grow?: number, shrink?: number, inline?: boolean } - Flex layout container. gap: 1=4px 2=8px 3=12px 4=16px 5=20px 6=24px. grow: 1=fill available width. alignItems: vertical alignment. justifyContent: horizontal distribution. [accepts children]
-- Grid: { templateColumns?: string, gap?: "1" | "2" | "3" | "4" | "5" | "6", 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: 1=4px … 6=24px. 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 } - Alert/notification banner. dismissible: true adds a close button that emits a "close" event. [accepts children]
-- Divider: { vertical?: boolean, spacing?: "0" | "1" | "2" | "3" | "4" | "5" | "6" | "8" | "12" | "half", alignContent?: "start" | "center" | "end" } - Divider between sections. vertical: true for vertical separator. spacing: gap around the divider. alignContent: alignment of content within the divider.
-- Icon: { name: "check-circle" | "in-progress" | "radio-button-unchecked", size?: "small" | "medium" | "large" | "xlarge", color?: string } - Anvil2 icon. name: check-circle=completed checkmark, in-progress=spinning partial circle, radio-button-unchecked=empty circle (pending)
-- Badge: { content?: string, offset?: { x?: string, y?: string } } - Unread notification count on a Button or Link. Wrap the interactive element as a child of Badge (the renderer adds position:relative). content: numerical count only (e.g. 3, 99+); omit for dot-only. offset: {x, y} CSS values to fine-tune position on non-square anchors like links. [accepts children]
-- 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 Badge for those). size: small | medium (default). color: any CSS color. icon: optional leading icon. removable: true adds a close button (not available for size=small).
-- Link: { label: string, href: string, appearance?: "primary" | "secondary", target?: "_blank" | "_self", ghost?: boolean } - Inline navigation link. href: destination URL. appearance: primary (default) | secondary. target: _blank opens in new tab (shows external-link icon). ghost: quieter styling (primary only).
-- ProgressBar: { label: string, value?: number, description?: string, indeterminate?: boolean } - Progress bar showing task completion. value: 0–100 (percentage). Omit value and set indeterminate=true for unknown progress.
+AVAILABLE COMPONENTS (20):
+
+- 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", size?: "xsmall" | "small" | "medium" | "large", loading?: boolean, disabled?: boolean } - Clickable button. Every button automatically submits form data when pressed — the element key is used as the actionId to identify which button was clicked. loading: true shows a spinner. disabled: true prevents interaction. size: xsmall | small | medium (default) | large.
-- Checkbox: { label: string, checked?: boolean, disabled?: boolean } - Checkbox input with label. Use $bindState on checked to track state.
-- 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. Use $bindState on value to bind to state. Prefer this over Select when the value is not from a fixed list.
-- 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). Use $bindState on value to bind to state. rows: visible row count (default 3).
-- Listbox: { label: string, options: Array<{ value: string, label: string }>, value?: string, disabled?: boolean } - Listbox for choosing from a fixed list of known options. Use only when options are predefined. For free-text user input use Input instead.
-- RadioGroup: { label: string, options: Array<{ value: string, label: string }>, value?: string, disabled?: boolean } - Group of radio buttons for single selection. Use $bindState on value to capture selection.
-- Switch: { label: string, checked?: boolean, disabled?: boolean } - Toggle switch for binary on/off settings. Prefer over Checkbox for enabling/disabling features. Use $bindState on checked to track state.
+- 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]
 
 AVAILABLE ACTIONS:
 
@@ -167,117 +166,132 @@ CRITICAL — apply these rules before choosing any form component:
 
 ━━━ LAYOUT RULES ━━━
 
-1. ALWAYS wrap everything in a root Flex { direction: "column", gap: "4" } — EXCEPT when the root element is a chart (BarChart or DonutChart), 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.
-3. Inside a Card, use Flex { direction: "column", gap: "3" } as the first child.
+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. Badge attaches to a Button or Link — wrap the interactive element as a child of Badge in the spec (the renderer adds position: relative). Use Chip to show status labels, not Badge.
-6. Divider separates content sections — can be placed between Cards or inside a Card (with padding="0" on the Card).
-7. Button at the bottom of its Card inside Flex { direction: "row", gap: "2" }.
-8. Do not nest Cards within Cards — use headings, body text, and actions to provide structure instead.
+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: use RevenueCard in a row Flex, one per metric.
+- 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.
+- 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. Add submit Buttons with a unique actionId prop per button — every Button automatically submits the form with its actionId, no on.press wiring needed.
+- 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", or "by region/tech/status": use BarChart or DonutChart as the root element. Do NOT wrap charts in Card or Flex.
+- 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 only: "body" (default), "eyebrow", "headline".
-- "headline" REQUIRES the el prop ("h1"–"h4"). Always pair with a meaningful heading level.
-- "eyebrow" does NOT support size="xlarge".
-- Use subdued prop (variant="body" only) for de-emphasized secondary text.
-- When nesting body Text inside body Text, add inline prop to the inner Text so it renders as <span> not <p>.
+- 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
-- Always set flexDirection="column" when stacking children vertically (the default layout is inline-flex).
+- 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 options: "0" | "xsmall" | "small" | "medium" (default) | "large". Use padding="0" + Divider for section-divided cards.
-- For clickable cards, use InteractiveCard — never add onClick to a plain Card.
-- To create sections within a Card: set padding="0", then place Divider between child elements.
+- 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 all layout containers within page content (not for top-level page column structure).
-- direction defaults to "row" — always explicitly set direction="column" when stacking.
-- gap values are design tokens: "0" | "half" | "1" | "2" | "3" | "4" | "5" | "6" | "8" | "12" | "13" | "14".
-- Flex can be both a container and a flex item — use grow, shrink, basis, alignSelf props when nested inside another 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
-- Use status prop to set semantic meaning: "info" (default) | "success" | "warning" | "danger".
-- title is optional but strongly recommended — it is the primary label for the alert.
-- Alert is for contextual, inline notifications on the page, not for toasts or announcements.
-- Use status="danger" for errors, status="warning" for cautionary messages, status="success" for confirmations.
-
-BADGE
-- Badge indicates unread notifications or attention-required counts on Button or Link — NEVER use it as a status label (use Chip for that).
-- In the spec, make Badge the parent and put the Button or Link as its child element; the renderer wraps them in position: relative.
-- Only put numerical values in the content prop. Cap at 99 (show "99+") or 999 for high-volume cases.
-- Omit content for a dot-only unread indicator (no count).
-- Use offset prop to fine-tune position when used on non-square elements like text links.
-- The child Button or Link must have a clear label (e.g., "Notifications", "Inbox"); do not add props that are not defined on the Badge catalog schema.
+- 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 visually labels and organizes statuses, metadata, and objects — NOT for notification counts (use Badge for that).
-- label prop is required — keep it short and descriptive.
-- Use color prop to convey status meaning (e.g., success = green, danger = red) — always pair color with text, never rely on color alone.
-- icon and avatar are mutually exclusive on a single Chip.
-- When size="small", only onClick OR onClose can be used, not both.
-- Default size is "medium". Use "small" in dense contexts (tables, tabs, sidenav).
-- Chips truncate by default; add textWrap to allow wrapping.
+- 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
-- Use spacing prop to control vertical/horizontal space around the divider: "0"–"6" (in 0.5rem steps), "8", "12". Default is "0".
-- Use vertical prop for side-by-side content separation; default (horizontal) for stacked sections.
-- To divide Card sections: set Card padding="0" and place Divider between children with each child managing its own padding.
+- 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
-- svg prop is required — always import SVG assets from @servicetitan/anvil2/assets/icons/material/round/*.svg.
+- 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".
-- If Icon is standalone with no text label, provide aria-label for accessibility.
-- If Icon is paired with a visible text label, no aria-label needed.
-- Use color prop for custom colors (accepts CSS color values and CSS variables). For icon color that should match surrounding text, use inherit prop.
-- Do NOT use Icon for interactive affordances without a Tooltip and tabIndex={0}.
+- 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 prop creates a quieter appearance — only valid when appearance="primary".
-- Link text must be descriptive (not "click here") — screen readers use the link text for context.
-- Use Link for navigation (renders <a>). For a button styled as a link, use LinkButton instead.
-- For external links, add target="_blank".
+- 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 (or aria-label / aria-labelledby) is required.
-- value (0–max) determines fill percentage. max defaults to 100.
-- Use indeterminate prop (no value) when progress cannot be determined — do NOT use both value and indeterminate together.
-- Use error prop (boolean or string) to show error state; string value shows an error message below the bar.
-- Use description prop for optional supplemental context below the bar.
+- 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).
-- Use for grouped comparisons across multiple categories; use stacked variant to show part-of-whole within each bar.
-- Apply 4px corner radius to the top of bars. Use 4px spacing between stacked segments.
-- Use monochrome color palette for data with natural order/progression (≤4 variables). Use categorical palette for 5–9 distinct categories.
+- 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.
-- Always include title, axis labels, and legend.
 
 DONUTCHART
-- Best for part-of-whole breakdowns where all slices add up to 100%.
-- Use for showing proportions (job status mix, revenue share by category). NOT for precise category comparisons.
-- Sort slices from largest to smallest (clockwise). Group minor categories into an "Other" slice placed last.
-- Use 4px spacing (1.4px gap) between donut sections.
-- Preferred over pie charts for dashboards — the open center allows central metric labeling.
-- Use color to differentiate categories; apply extended palette for >5 categories; always ensure accessibility contrast.
+- 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.
 

package/dist/catalog/core/schema.json

@@ -18,7 +18,6 @@
               "Alert",
               "Divider",
               "Icon",
-              "Badge",
               "Chip",
               "Link",
               "ProgressBar",