@overdoser/react-toolkit 0.0.16 → 0.5.0

package/manifest.json

@@ -4,9 +4,16 @@
   "version": "0.0.2",
   "description": "Machine-readable manifest of components, props, allowed values, and hooks. Generated for tooling and AI assistants.",
   "themeCssImport": "@overdoser/react-toolkit/theme.css",
+  "themeCssLayeredImport": "@overdoser/react-toolkit/theme.layered.css",
+  "stylingNotes": "className/classes.* overrides are plain CSS classes — they only beat built-in styles if inserted after them. Import theme.layered.css (cascade layer 'crk') instead of theme.css to make any unlayered consumer rule, including classes.*, win deterministically regardless of order. theme.css and theme.layered.css are identical except the layer wrapper — import exactly one (never both); --crk-* token theming works the same in either.",
   "peerDependencies": {
-    "required": ["react", "react-dom"],
-    "optional": ["react-hook-form"]
+    "required": [
+      "react",
+      "react-dom"
+    ],
+    "optional": [
+      "react-hook-form"
+    ]
   },
   "components": {
     "Button": {
@@ -15,13 +22,59 @@
       "extendsNativeProps": "button",
       "forwardsRef": true,
       "props": {
-        "variant": { "type": "enum", "values": ["primary", "secondary", "danger", "ghost"], "default": "primary" },
-        "size": { "type": "enum", "values": ["sm", "md", "lg"], "default": "md" },
-        "loading": { "type": "boolean", "default": false, "notes": "Disables the button and sets aria-busy." },
-        "loadingStyle": { "type": "enum", "values": ["dots", "shimmer", "border"], "default": "dots", "notes": "Only used when loading=true." },
-        "fullWidth": { "type": "boolean", "default": false },
-        "iconOnly": { "type": "boolean", "default": false, "notes": "Squares the button and renders content larger/bolder. For single-glyph buttons (‹, ›, ×, +). Always pair with aria-label." },
-        "classes": { "type": "Partial<ButtonClasses>", "shape": ["root", "content", "shimmer", "dots", "dot"] }
+        "variant": {
+          "type": "enum",
+          "values": [
+            "primary",
+            "secondary",
+            "danger",
+            "ghost"
+          ],
+          "default": "primary"
+        },
+        "size": {
+          "type": "enum",
+          "values": [
+            "sm",
+            "md",
+            "lg"
+          ],
+          "default": "md"
+        },
+        "loading": {
+          "type": "boolean",
+          "default": false,
+          "notes": "Disables the button and sets aria-busy."
+        },
+        "loadingStyle": {
+          "type": "enum",
+          "values": [
+            "dots",
+            "shimmer",
+            "border"
+          ],
+          "default": "dots",
+          "notes": "Only used when loading=true."
+        },
+        "fullWidth": {
+          "type": "boolean",
+          "default": false
+        },
+        "iconOnly": {
+          "type": "boolean",
+          "default": false,
+          "notes": "Squares the button and renders content larger/bolder. For single-glyph buttons (‹, ›, ×, +). Always pair with aria-label."
+        },
+        "classes": {
+          "type": "Partial<ButtonClasses>",
+          "shape": [
+            "root",
+            "content",
+            "shimmer",
+            "dots",
+            "dot"
+          ]
+        }
       }
     },
     "Link": {
@@ -30,8 +83,25 @@
       "extendsNativeProps": "a",
       "forwardsRef": true,
       "props": {
-        "variant": { "type": "enum", "values": ["default", "muted", "danger"], "default": "default" },
-        "external": { "type": "boolean", "default": false, "notes": "Adds target=_blank, rel=noopener noreferrer, and an sr-only 'opens in a new tab' suffix." }
+        "variant": {
+          "type": "enum",
+          "values": [
+            "default",
+            "muted",
+            "danger"
+          ],
+          "default": "default"
+        },
+        "external": {
+          "type": "boolean",
+          "default": false,
+          "notes": "Adds target=_blank, rel=noopener noreferrer, an inline ↗ icon, and an sr-only 'opens in a new tab' suffix."
+        },
+        "hideExternalIcon": {
+          "type": "boolean",
+          "default": false,
+          "notes": "Hide the inline ↗ icon shown by default when the link opens in a new tab (external or manual target=_blank). The sr-only suffix is kept."
+        }
       }
     },
     "Typography": {
@@ -40,11 +110,53 @@
       "extendsNativeProps": "p (without color)",
       "forwardsRef": true,
       "props": {
-        "variant": { "type": "enum", "values": ["h1", "h2", "h3", "h4", "h5", "h6", "p", "span", "label"], "default": "p" },
-        "weight": { "type": "enum", "values": ["normal", "medium", "semibold", "bold"] },
-        "color": { "type": "enum", "values": ["default", "muted", "primary", "danger", "success"], "notes": "For arbitrary colors, use style or className." },
-        "align": { "type": "enum", "values": ["left", "center", "right"] },
-        "truncate": { "type": "boolean", "default": false }
+        "variant": {
+          "type": "enum",
+          "values": [
+            "h1",
+            "h2",
+            "h3",
+            "h4",
+            "h5",
+            "h6",
+            "p",
+            "span",
+            "label"
+          ],
+          "default": "p"
+        },
+        "weight": {
+          "type": "enum",
+          "values": [
+            "normal",
+            "medium",
+            "semibold",
+            "bold"
+          ]
+        },
+        "color": {
+          "type": "enum",
+          "values": [
+            "default",
+            "muted",
+            "primary",
+            "danger",
+            "success"
+          ],
+          "notes": "For arbitrary colors, use style or className."
+        },
+        "align": {
+          "type": "enum",
+          "values": [
+            "left",
+            "center",
+            "right"
+          ]
+        },
+        "truncate": {
+          "type": "boolean",
+          "default": false
+        }
       }
     },
     "List": {
@@ -53,8 +165,24 @@
       "extendsNativeProps": "ul",
       "forwardsRef": true,
       "props": {
-        "variant": { "type": "enum", "values": ["unordered", "ordered", "none"], "default": "unordered" },
-        "spacing": { "type": "enum", "values": ["sm", "md", "lg"], "default": "md" }
+        "variant": {
+          "type": "enum",
+          "values": [
+            "unordered",
+            "ordered",
+            "none"
+          ],
+          "default": "unordered"
+        },
+        "spacing": {
+          "type": "enum",
+          "values": [
+            "sm",
+            "md",
+            "lg"
+          ],
+          "default": "md"
+        }
       }
     },
     "ListItem": {
@@ -69,40 +197,140 @@
       "element": "table (inside wrapper div)",
       "generic": "T extends Record<string, unknown>",
       "props": {
-        "data": { "type": "T[]", "required": true },
-        "columns": { "type": "ColumnDef<T>[]", "required": true },
-        "sortConfig": { "type": "SortConfig[]", "notes": "Controlled sort. Provide with onSort for server-side mode." },
-        "onSort": { "type": "(config: SortConfig[]) => void", "notes": "When set, Table is fully controlled — does not sort or paginate data internally." },
-        "multiSort": { "type": "boolean", "default": true, "notes": "Ctrl/Cmd+click a sortable header to add a secondary sort." },
-        "striped": { "type": "boolean", "default": false },
-        "hoverable": { "type": "boolean", "default": false },
-        "compact": { "type": "boolean", "default": false },
-        "rowKey": { "type": "keyof T & string" },
-        "rowClassName": { "type": "string | ((row: T, index: number) => string | undefined)", "notes": "Per-row class. Use a callback to highlight rows matching a predicate." },
-        "rowStyle": { "type": "CSSProperties | ((row: T, index: number) => CSSProperties | undefined)", "notes": "Per-row inline style. Same shape as rowClassName." },
-        "emptyMessage": { "type": "ReactNode", "default": "No data" },
-        "pagination": { "type": "PaginationConfig" },
-        "classes": { "type": "Partial<TableClasses>", "shape": ["wrapper", "root", "headerCell", "row", "cell", "emptyCell", "paginator", "pageButton"] }
+        "data": {
+          "type": "T[]",
+          "required": true
+        },
+        "columns": {
+          "type": "ColumnDef<T>[]",
+          "required": true
+        },
+        "sortConfig": {
+          "type": "SortConfig[]",
+          "notes": "Controlled sort. Provide with onSort for server-side mode."
+        },
+        "onSort": {
+          "type": "(config: SortConfig[]) => void",
+          "notes": "When set, Table is fully controlled — does not sort or paginate data internally."
+        },
+        "multiSort": {
+          "type": "boolean",
+          "default": true,
+          "notes": "Ctrl/Cmd+click a sortable header to add a secondary sort."
+        },
+        "striped": {
+          "type": "boolean",
+          "default": false
+        },
+        "hoverable": {
+          "type": "boolean",
+          "default": false
+        },
+        "compact": {
+          "type": "boolean",
+          "default": false
+        },
+        "rowKey": {
+          "type": "keyof T & string"
+        },
+        "rowClassName": {
+          "type": "string | ((row: T, index: number) => string | undefined)",
+          "notes": "Per-row class. Use a callback to highlight rows matching a predicate."
+        },
+        "rowStyle": {
+          "type": "CSSProperties | ((row: T, index: number) => CSSProperties | undefined)",
+          "notes": "Per-row inline style. Same shape as rowClassName."
+        },
+        "emptyMessage": {
+          "type": "ReactNode",
+          "default": "No data"
+        },
+        "pagination": {
+          "type": "PaginationConfig"
+        },
+        "classes": {
+          "type": "Partial<TableClasses>",
+          "shape": [
+            "wrapper",
+            "root",
+            "headerCell",
+            "row",
+            "cell",
+            "emptyCell",
+            "paginator",
+            "pageButton"
+          ]
+        }
       },
       "subTypes": {
         "ColumnDef<T>": {
-          "key": { "type": "keyof T & string", "required": true },
-          "header": { "type": "ReactNode", "required": true },
-          "sortable": { "type": "boolean" },
-          "render": { "type": "(value, row, index) => ReactNode" },
-          "width": { "type": "string | number" },
-          "align": { "type": "enum", "values": ["left", "center", "right"] }
+          "key": {
+            "type": "keyof T & string",
+            "required": true
+          },
+          "header": {
+            "type": "ReactNode",
+            "required": true
+          },
+          "sortable": {
+            "type": "boolean"
+          },
+          "render": {
+            "type": "(value, row, index) => ReactNode"
+          },
+          "width": {
+            "type": "string | number"
+          },
+          "align": {
+            "type": "enum",
+            "values": [
+              "left",
+              "center",
+              "right"
+            ]
+          }
         },
         "SortConfig": {
-          "key": { "type": "string", "required": true },
-          "direction": { "type": "enum", "values": ["asc", "desc"], "required": true }
+          "key": {
+            "type": "string",
+            "required": true
+          },
+          "direction": {
+            "type": "enum",
+            "values": [
+              "asc",
+              "desc"
+            ],
+            "required": true
+          }
         },
         "PaginationConfig": {
-          "page": { "type": "number", "required": true, "notes": "1-based" },
-          "pageSize": { "type": "number", "required": true },
-          "totalRows": { "type": "number", "notes": "Required for server-side mode; defaults to data.length client-side." },
-          "pageSizeOptions": { "type": "number[]", "default": [10, 25, 50, 100] },
-          "onPageChange": { "type": "(page: number, pageSize: number) => void", "required": true }
+          "page": {
+            "type": "number",
+            "required": true,
+            "notes": "1-based"
+          },
+          "pageSize": {
+            "type": "number",
+            "required": true
+          },
+          "totalRows": {
+            "type": "number",
+            "notes": "Required for server-side mode; defaults to data.length client-side."
+          },
+          "pageSizeOptions": {
+            "type": "number[]",
+            "default": [
+              10,
+              25,
+              50,
+              100
+            ]
+          },
+          "onPageChange": {
+            "type": "(page: number, pageSize: number) => void",
+            "required": true
+          }
         }
       },
       "behavior": {
@@ -118,19 +346,66 @@
         "select": "Pass `options` + `value` + `onChange`. Trigger label shows the selected option."
       },
       "props": {
-        "trigger": { "type": "ReactNode", "notes": "Required for menu mode; ignored when `options` is provided." },
-        "options": { "type": "{ value: string; label: ReactNode; disabled?: boolean }[]" },
-        "value": { "type": "string", "notes": "Select-mode controlled value." },
-        "onChange": { "type": "(value: string) => void", "notes": "Select-mode callback." },
-        "placeholder": { "type": "ReactNode", "default": "Select..." },
-        "align": { "type": "enum", "values": ["left", "right"], "default": "left" },
-        "error": { "type": "boolean", "default": false },
-        "fullWidth": { "type": "boolean", "default": true },
-        "portal": { "type": "boolean", "default": true, "notes": "Renders the open menu in a portal at document.body using --crk-z-floating (1060). Escapes overflow:hidden ancestors and sits above modals. Set false to keep the menu in the trigger's subtree." },
-        "id": { "type": "string" },
-        "onOpen": { "type": "() => void" },
-        "onClose": { "type": "() => void" },
-        "classes": { "type": "Partial<DropdownClasses>", "shape": ["root", "trigger", "triggerLabel", "chevron", "menu", "item"] }
+        "trigger": {
+          "type": "ReactNode",
+          "notes": "Required for menu mode; ignored when `options` is provided."
+        },
+        "options": {
+          "type": "{ value: string; label: ReactNode; disabled?: boolean }[]"
+        },
+        "value": {
+          "type": "string",
+          "notes": "Select-mode controlled value."
+        },
+        "onChange": {
+          "type": "(value: string) => void",
+          "notes": "Select-mode callback."
+        },
+        "placeholder": {
+          "type": "ReactNode",
+          "default": "Select..."
+        },
+        "align": {
+          "type": "enum",
+          "values": [
+            "left",
+            "right"
+          ],
+          "default": "left"
+        },
+        "error": {
+          "type": "boolean",
+          "default": false
+        },
+        "fullWidth": {
+          "type": "boolean",
+          "default": true
+        },
+        "portal": {
+          "type": "boolean",
+          "default": true,
+          "notes": "Renders the open menu in a portal at document.body using --crk-z-floating (1060). Escapes overflow:hidden ancestors and sits above modals. Set false to keep the menu in the trigger's subtree."
+        },
+        "id": {
+          "type": "string"
+        },
+        "onOpen": {
+          "type": "() => void"
+        },
+        "onClose": {
+          "type": "() => void"
+        },
+        "classes": {
+          "type": "Partial<DropdownClasses>",
+          "shape": [
+            "root",
+            "trigger",
+            "triggerLabel",
+            "chevron",
+            "menu",
+            "item"
+          ]
+        }
       }
     },
     "DropdownItem": {
@@ -139,86 +414,800 @@
       "extendsNativeProps": "button",
       "forwardsRef": true,
       "props": {
-        "disabled": { "type": "boolean", "default": false }
+        "disabled": {
+          "type": "boolean",
+          "default": false
+        }
       }
     },
     "Popover": {
       "import": "import { Popover } from '@overdoser/react-toolkit'",
       "element": "div",
       "props": {
-        "trigger": { "type": "ReactNode", "required": true, "notes": "Default mode wraps the value in an internal <button>. Set asChild=true to pass your own interactive element instead." },
-        "asChild": { "type": "boolean", "default": false, "notes": "When true and trigger is a single React element, the element is rendered as-is with onClick/aria-*/ref cloned onto it (no wrapping <button>). Use to avoid the button-in-button hydration warning when passing <Button> as the trigger." },
-        "content": { "type": "ReactNode", "required": true },
-        "position": { "type": "enum", "values": ["top", "bottom", "left", "right"], "default": "bottom" },
-        "open": { "type": "boolean", "notes": "Controlled mode." },
-        "onOpenChange": { "type": "(open: boolean) => void" },
-        "classes": { "type": "Partial<PopoverClasses>", "shape": ["root", "trigger", "popover"] }
+        "trigger": {
+          "type": "ReactNode",
+          "required": true,
+          "notes": "Default mode wraps the value in an internal <button>. Set asChild=true to pass your own interactive element instead."
+        },
+        "asChild": {
+          "type": "boolean",
+          "default": false,
+          "notes": "When true and trigger is a single React element, the element is rendered as-is with onClick/aria-*/ref cloned onto it (no wrapping <button>). Use to avoid the button-in-button hydration warning when passing <Button> as the trigger."
+        },
+        "content": {
+          "type": "ReactNode",
+          "required": true
+        },
+        "position": {
+          "type": "enum",
+          "values": [
+            "top",
+            "bottom",
+            "left",
+            "right"
+          ],
+          "default": "bottom",
+          "notes": "The requested side; honored whenever it fits."
+        },
+        "autoPosition": {
+          "type": "boolean",
+          "default": true,
+          "notes": "Flip to the opposite side when the requested one overflows the viewport, and shift along the cross-axis near a screen edge. Set false to pin strictly to position."
+        },
+        "open": {
+          "type": "boolean",
+          "notes": "Controlled mode."
+        },
+        "onOpenChange": {
+          "type": "(open: boolean) => void"
+        },
+        "classes": {
+          "type": "Partial<PopoverClasses>",
+          "shape": [
+            "root",
+            "trigger",
+            "popover"
+          ]
+        }
       },
       "behavior": {
-        "closesOn": ["outside click", "Escape"],
+        "closesOn": [
+          "outside click",
+          "Escape"
+        ],
         "childrenTyped": "never — pass via `content` prop"
       }
     },
-    "Modal": {
-      "import": "import { Modal } from '@overdoser/react-toolkit'",
+    "Draggable": {
+      "import": "import { Draggable } from '@overdoser/react-toolkit'",
+      "element": "div wrapping arbitrary children",
+      "forwardsRef": true,
+      "extendsNativeProps": "div (except onDrag)",
+      "compoundComponents": [
+        "Draggable.Handle"
+      ],
+      "notes": "Free-move container. Position is a translate(x,y) offset from the element's natural layout position. Add Draggable.Handle to restrict the grab area; without one the whole surface drags. A focused handle is keyboard-movable (arrow keys).",
+      "props": {
+        "defaultPosition": {
+          "type": "{ x: number; y: number }",
+          "default": "{ x: 0, y: 0 }",
+          "notes": "Uncontrolled initial offset."
+        },
+        "position": {
+          "type": "{ x: number; y: number }",
+          "notes": "Controlled offset; pair with onDrag to update it."
+        },
+        "axis": {
+          "type": "'both' | 'x' | 'y'",
+          "default": "both"
+        },
+        "bounds": {
+          "type": "'viewport' | 'parent' | 'none'",
+          "default": "viewport",
+          "notes": "Clamp movement to the viewport / parent element, or leave unconstrained."
+        },
+        "keyboardStep": {
+          "type": "number",
+          "default": 10,
+          "notes": "Px per arrow-key press on a focused handle."
+        },
+        "disabled": {
+          "type": "boolean",
+          "default": false
+        },
+        "onDragStart": {
+          "type": "(position: { x: number; y: number }) => void"
+        },
+        "onDrag": {
+          "type": "(position: { x: number; y: number }) => void",
+          "notes": "Required to update a controlled position."
+        },
+        "onDragEnd": {
+          "type": "(position: { x: number; y: number }) => void"
+        },
+        "classes": {
+          "type": "Partial<DraggableClasses>",
+          "shape": [
+            "root",
+            "handle"
+          ]
+        }
+      }
+    },
+    "Toast": {
+      "import": "import { ToastProvider, toast, useToast } from '@overdoser/react-toolkit'",
+      "element": "portal viewport at document.body",
+      "notes": "Imperative notification system backed by a global store. Mount ToastProvider once (it is the renderer; do NOT render toast elements yourself). Trigger via the standalone toast(options) (no hook/context needed; also toast.dismiss(id) / toast.dismissAll()) OR via useToast() which returns the same { toast, dismiss, dismissAll }. useToast does not require the provider and never throws. toast() with no provider mounted warns (dev) and renders nothing. danger/warning use role=alert (assertive); others role=status (polite). Auto-dismiss pauses on hover.",
+      "standaloneTrigger": {
+        "name": "toast",
+        "signature": "toast(options: ToastOptions): string",
+        "methods": [
+          "toast.dismiss(id: string): void",
+          "toast.dismissAll(): void"
+        ],
+        "notes": "Importable; callable anywhere without a hook or context."
+      },
+      "provider": {
+        "name": "ToastProvider",
+        "props": {
+          "children": {
+            "type": "ReactNode",
+            "required": true
+          },
+          "position": {
+            "type": "'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right'",
+            "default": "top-right"
+          },
+          "duration": {
+            "type": "number",
+            "default": 5000,
+            "notes": "Default auto-dismiss ms."
+          },
+          "max": {
+            "type": "number",
+            "default": 5
+          },
+          "classes": {
+            "type": "Partial<ToastClasses>",
+            "shape": [
+              "viewport",
+              "toast",
+              "icon",
+              "content",
+              "title",
+              "description",
+              "close"
+            ]
+          }
+        }
+      },
+      "hook": {
+        "name": "useToast",
+        "returns": "ToastApi = { toast(options): string; dismiss(id): void; dismissAll(): void }",
+        "throwsWithoutProvider": false,
+        "toastOptions": {
+          "title": {
+            "type": "ReactNode"
+          },
+          "description": {
+            "type": "ReactNode"
+          },
+          "variant": {
+            "type": "'neutral' | 'info' | 'success' | 'warning' | 'danger'",
+            "default": "neutral"
+          },
+          "duration": {
+            "type": "number",
+            "notes": "Overrides provider default; 0 or Infinity persists until dismissed."
+          }
+        }
+      }
+    },
+    "Tabs": {
+      "import": "import { Tabs } from '@overdoser/react-toolkit'",
+      "element": "div wrapping role=tablist + panels",
+      "forwardsRef": true,
+      "compoundComponents": [
+        "Tabs.List",
+        "Tabs.Tab",
+        "Tabs.Panel"
+      ],
+      "notes": "A Tab and its Panel are linked by matching value. Keyboard: arrow keys (orientation-aware) + Home/End move and activate; roving tabindex; automatic activation on focus.",
+      "props": {
+        "value": {
+          "type": "string",
+          "notes": "Controlled active tab."
+        },
+        "defaultValue": {
+          "type": "string",
+          "notes": "Uncontrolled initial active tab."
+        },
+        "onValueChange": {
+          "type": "(value: string) => void"
+        },
+        "orientation": {
+          "type": "'horizontal' | 'vertical'",
+          "default": "horizontal"
+        },
+        "variant": {
+          "type": "'line' | 'solid' | 'pill'",
+          "default": "line"
+        },
+        "size": {
+          "type": "'sm' | 'md' | 'lg'",
+          "default": "md"
+        },
+        "classes": {
+          "type": "Partial<TabsClasses>",
+          "shape": [
+            "root",
+            "list",
+            "tab",
+            "panel"
+          ]
+        }
+      },
+      "subComponentProps": {
+        "Tabs.Tab": {
+          "value": {
+            "type": "string",
+            "required": true
+          },
+          "disabled": {
+            "type": "boolean",
+            "default": false
+          }
+        },
+        "Tabs.Panel": {
+          "value": {
+            "type": "string",
+            "required": true
+          },
+          "keepMounted": {
+            "type": "boolean",
+            "default": false,
+            "notes": "Keep inactive panels mounted but hidden."
+          }
+        }
+      }
+    },
+    "Alert": {
+      "import": "import { Alert } from '@overdoser/react-toolkit'",
+      "element": "div[role=alert]",
+      "forwardsRef": true,
+      "extendsNativeProps": "div (without title)",
+      "notes": "Inline, persistent status message. For transient feedback prefer Toast.",
+      "props": {
+        "variant": {
+          "type": "'info' | 'success' | 'warning' | 'danger'",
+          "default": "info"
+        },
+        "title": {
+          "type": "ReactNode"
+        },
+        "icon": {
+          "type": "ReactNode | boolean",
+          "default": true,
+          "notes": "true = variant icon; node = override; false = hide."
+        },
+        "onClose": {
+          "type": "() => void",
+          "notes": "When set, renders a dismiss button."
+        },
+        "closeLabel": {
+          "type": "string",
+          "default": "Dismiss"
+        },
+        "classes": {
+          "type": "Partial<AlertClasses>",
+          "shape": [
+            "root",
+            "icon",
+            "content",
+            "title",
+            "message",
+            "close"
+          ]
+        }
+      }
+    },
+    "Badge": {
+      "import": "import { Badge } from '@overdoser/react-toolkit'",
+      "element": "span",
+      "forwardsRef": true,
+      "extendsNativeProps": "span",
+      "props": {
+        "variant": {
+          "type": "'neutral' | 'primary' | 'success' | 'warning' | 'danger'",
+          "default": "neutral"
+        },
+        "appearance": {
+          "type": "'soft' | 'solid' | 'outline'",
+          "default": "soft"
+        },
+        "size": {
+          "type": "'sm' | 'md' | 'lg'",
+          "default": "md"
+        },
+        "dot": {
+          "type": "boolean",
+          "default": false,
+          "notes": "Leading status dot."
+        },
+        "classes": {
+          "type": "Partial<BadgeClasses>",
+          "shape": [
+            "root",
+            "dot"
+          ]
+        }
+      }
+    },
+    "Spinner": {
+      "import": "import { Spinner } from '@overdoser/react-toolkit'",
+      "element": "span[role=status]",
+      "forwardsRef": true,
+      "extendsNativeProps": "span",
+      "notes": "Indeterminate loading spinner; inherits currentColor.",
+      "props": {
+        "size": {
+          "type": "'sm' | 'md' | 'lg'",
+          "default": "md"
+        },
+        "color": {
+          "type": "string",
+          "notes": "Overrides currentColor."
+        },
+        "label": {
+          "type": "string",
+          "default": "Loading",
+          "notes": "Visually-hidden a11y label; pass '' to omit."
+        },
+        "classes": {
+          "type": "Partial<SpinnerClasses>",
+          "shape": [
+            "root",
+            "circle",
+            "label"
+          ]
+        }
+      }
+    },
+    "Skeleton": {
+      "import": "import { Skeleton } from '@overdoser/react-toolkit'",
+      "element": "div[aria-hidden]",
+      "forwardsRef": true,
+      "extendsNativeProps": "div (without children)",
+      "notes": "Decorative loading placeholder.",
+      "props": {
+        "variant": {
+          "type": "'text' | 'circle' | 'rect'",
+          "default": "text"
+        },
+        "width": {
+          "type": "number | string",
+          "notes": "number → px; defaults to 100%."
+        },
+        "height": {
+          "type": "number | string",
+          "notes": "number → px; defaults per variant."
+        },
+        "animation": {
+          "type": "'pulse' | 'wave' | 'none'",
+          "default": "pulse"
+        },
+        "lines": {
+          "type": "number",
+          "default": 1,
+          "notes": "For variant=text, render N stacked bars (last shorter)."
+        },
+        "classes": {
+          "type": "Partial<SkeletonClasses>",
+          "shape": [
+            "root",
+            "line"
+          ]
+        }
+      }
+    },
+    "Drawer": {
+      "import": "import { Drawer } from '@overdoser/react-toolkit'",
       "element": "div (portal at document.body)",
-      "compoundComponents": ["Modal.Header", "Modal.Body", "Modal.Footer"],
+      "forwardsRef": true,
+      "compoundComponents": ["Drawer.Header", "Drawer.Body", "Drawer.Footer"],
+      "notes": "Off-canvas panel sliding from a screen edge (left/right = full-height strip, top/bottom = full-width strip). Animates in/out and stays mounted through the close transition.",
       "props": {
         "open": { "type": "boolean", "required": true },
         "onClose": { "type": "() => void", "required": true },
-        "closeOnBackdrop": { "type": "boolean", "default": true },
+        "side": { "type": "'left' | 'right' | 'top' | 'bottom'", "default": "right" },
+        "size": { "type": "'sm' | 'md' | 'lg' | 'full'", "default": "md" },
+        "variant": { "type": "'temporary' | 'persistent'", "default": "temporary", "notes": "temporary = scrim + modal (scrim/Escape close); persistent = no scrim, page stays interactive." },
+        "closeOnBackdrop": { "type": "boolean", "default": true, "notes": "Temporary only." },
         "closeOnEscape": { "type": "boolean", "default": true },
-        "size": { "type": "enum", "values": ["sm", "md", "lg", "fullscreen"], "default": "md" },
-        "aria-label": { "type": "string" },
-        "aria-labelledby": { "type": "string" },
-        "classes": { "type": "Partial<ModalClasses>", "shape": ["backdrop", "modal", "header", "closeButton", "body", "footer"] }
+        "classes": { "type": "Partial<DrawerClasses>", "shape": ["backdrop", "drawer", "header", "closeButton", "body", "footer"] }
+      }
+    },
+    "Tooltip": {
+      "import": "import { Tooltip } from '@overdoser/react-toolkit'",
+      "element": "inline span wrapper + portaled bubble (role=tooltip)",
+      "notes": "Lightweight hover/focus label with delay. Use Popover for interactive/click content.",
+      "props": {
+        "content": { "type": "ReactNode", "required": true, "notes": "Nullish/empty → never shows." },
+        "children": { "type": "ReactNode", "required": true, "notes": "The trigger." },
+        "placement": { "type": "'top' | 'bottom' | 'left' | 'right'", "default": "top", "notes": "Flips on overflow." },
+        "delay": { "type": "number", "default": 300, "notes": "Open delay ms." },
+        "closeDelay": { "type": "number", "default": 0 },
+        "disabled": { "type": "boolean", "default": false },
+        "hideArrow": { "type": "boolean", "default": false },
+        "classes": { "type": "Partial<TooltipClasses>", "shape": ["wrapper", "tooltip", "arrow"] }
+      }
+    },
+    "Avatar": {
+      "import": "import { Avatar } from '@overdoser/react-toolkit'",
+      "element": "span",
+      "forwardsRef": true,
+      "extendsNativeProps": "span",
+      "notes": "Falls back to initials (from name) or a user icon if the image is missing or errors.",
+      "props": {
+        "src": { "type": "string" },
+        "alt": { "type": "string" },
+        "name": { "type": "string", "notes": "Used to derive initials." },
+        "fallback": { "type": "ReactNode" },
+        "size": { "type": "'xs' | 'sm' | 'md' | 'lg' | 'xl'", "default": "md" },
+        "shape": { "type": "'circle' | 'square'", "default": "circle" },
+        "status": { "type": "'online' | 'offline' | 'away' | 'busy'" },
+        "classes": { "type": "Partial<AvatarClasses>", "shape": ["root", "image", "fallback", "status"] }
+      }
+    },
+    "Divider": {
+      "import": "import { Divider } from '@overdoser/react-toolkit'",
+      "element": "div[role=separator]",
+      "forwardsRef": true,
+      "extendsNativeProps": "div (without children)",
+      "props": {
+        "orientation": { "type": "'horizontal' | 'vertical'", "default": "horizontal" },
+        "variant": { "type": "'solid' | 'dashed' | 'dotted'", "default": "solid" },
+        "label": { "type": "ReactNode", "notes": "Horizontal only." },
+        "labelPosition": { "type": "'start' | 'center' | 'end'", "default": "center" },
+        "classes": { "type": "Partial<DividerClasses>", "shape": ["root", "line", "label"] }
+      }
+    },
+    "Breadcrumbs": {
+      "import": "import { Breadcrumbs } from '@overdoser/react-toolkit'",
+      "element": "nav > ol",
+      "forwardsRef": true,
+      "compoundComponents": ["Breadcrumbs.Item"],
+      "notes": "Separators auto-inserted; the last item defaults to current (aria-current=page, no link).",
+      "props": {
+        "separator": { "type": "ReactNode", "default": "/" },
+        "label": { "type": "string", "default": "Breadcrumb" },
+        "classes": { "type": "Partial<BreadcrumbsClasses>", "shape": ["root", "list", "item", "link", "current", "separator"] }
+      },
+      "subComponentProps": {
+        "Breadcrumbs.Item": {
+          "href": { "type": "string", "notes": "Omit for a plain (non-link) crumb." },
+          "current": { "type": "boolean", "notes": "Renders as text with aria-current=page." }
+        }
+      }
+    },
+    "Pagination": {
+      "import": "import { Pagination } from '@overdoser/react-toolkit'",
+      "element": "nav > ul",
+      "forwardsRef": true,
+      "notes": "Windowed page list with ellipses, e.g. 1 … 6 7 8 9 10 … 99. Also exports paginationRange(page, count, boundaryCount?, siblingCount?). Table has its own pagination — use this for non-table lists.",
+      "props": {
+        "count": { "type": "number", "notes": "Total pages. Or use total + pageSize." },
+        "total": { "type": "number", "notes": "With pageSize, derives count." },
+        "pageSize": { "type": "number", "default": 10 },
+        "page": { "type": "number", "notes": "Controlled, 1-based." },
+        "defaultPage": { "type": "number", "default": 1 },
+        "onChange": { "type": "(page: number) => void" },
+        "boundaryCount": { "type": "number", "default": 1 },
+        "siblingCount": { "type": "number", "default": 2, "notes": "Defaults give at most 9 chips." },
+        "showPrevNext": { "type": "boolean", "default": true },
+        "showFirstLast": { "type": "boolean", "default": false },
+        "size": { "type": "'sm' | 'md' | 'lg'", "default": "md" },
+        "disabled": { "type": "boolean", "default": false },
+        "classes": { "type": "Partial<PaginationClasses>", "shape": ["root", "list", "item", "active", "ellipsis", "control"] }
+      }
+    },
+    "Slider": {
+      "import": "import { Slider } from '@overdoser/react-toolkit'",
+      "element": "div containing role=slider thumb(s)",
+      "forwardsRef": true,
+      "notes": "A tuple value makes it a range (two thumbs). Pointer drag + keyboard (arrows, Home/End, PageUp/Down).",
+      "props": {
+        "value": { "type": "number | [number, number]", "notes": "Tuple → range slider." },
+        "defaultValue": { "type": "number | [number, number]" },
+        "onChange": { "type": "(value: number | [number, number]) => void" },
+        "onChangeEnd": { "type": "(value: number | [number, number]) => void" },
+        "min": { "type": "number", "default": 0 },
+        "max": { "type": "number", "default": 100 },
+        "step": { "type": "number", "default": 1 },
+        "disabled": { "type": "boolean", "default": false },
+        "formatValue": { "type": "(value: number) => string", "notes": "For aria-valuetext." },
+        "classes": { "type": "Partial<SliderClasses>", "shape": ["root", "track", "range", "thumb"] }
+      }
+    },
+    "NumberInput": {
+      "import": "import { NumberInput } from '@overdoser/react-toolkit'",
+      "element": "div wrapping input + stepper buttons",
+      "forwardsRef": true,
+      "notes": "Emits onChange(value: number | null), so it binds directly inside FormField. Arrow keys step; clamps on blur.",
+      "props": {
+        "value": { "type": "number | null", "notes": "Controlled." },
+        "defaultValue": { "type": "number | null" },
+        "onChange": { "type": "(value: number | null) => void" },
+        "min": { "type": "number" },
+        "max": { "type": "number" },
+        "step": { "type": "number", "default": 1 },
+        "precision": { "type": "number", "notes": "Decimal places to round to." },
+        "inputSize": { "type": "'sm' | 'md' | 'lg'", "default": "md" },
+        "error": { "type": "boolean", "default": false },
+        "hideControls": { "type": "boolean", "default": false },
+        "classes": { "type": "Partial<NumberInputClasses>", "shape": ["root", "input", "controls", "increment", "decrement"] }
+      }
+    },
+    "DatePicker": {
+      "import": "import { DatePicker } from '@overdoser/react-toolkit'",
+      "element": "div wrapping a read-only input + calendar popover",
+      "forwardsRef": true,
+      "notes": "Single date with a pop-up calendar. Binds in FormField (value: Date | null). Keyboard: arrows move days, PageUp/Down change month, Home/End week ends, Enter selects, Esc closes.",
+      "props": {
+        "value": { "type": "Date | null", "notes": "Controlled." },
+        "defaultValue": { "type": "Date | null" },
+        "onChange": { "type": "(date: Date | null) => void" },
+        "min": { "type": "Date" },
+        "max": { "type": "Date" },
+        "disabledDate": { "type": "(date: Date) => boolean" },
+        "weekStartsOn": { "type": "number", "default": 0, "notes": "0 = Sunday." },
+        "locale": { "type": "string", "notes": "BCP-47 for month/weekday names." },
+        "format": { "type": "(date: Date) => string" },
+        "placeholder": { "type": "string", "default": "Select date" },
+        "inputSize": { "type": "'sm' | 'md' | 'lg'", "default": "md" },
+        "error": { "type": "boolean", "default": false },
+        "disabled": { "type": "boolean", "default": false },
+        "portal": { "type": "boolean", "default": true },
+        "classes": { "type": "Partial<DatePickerClasses>", "shape": ["root", "input", "icon", "popover", "header", "nav", "grid", "day", "daySelected", "dayToday", "dayOutside"] }
+      }
+    },
+    "Dropzone": {
+      "import": "import { Dropzone } from '@overdoser/react-toolkit'",
+      "element": "div[role=button] + hidden file input",
+      "forwardsRef": true,
+      "notes": "Drag-drop or click to browse. Emits accepted/rejected files; file-list UI is left to the consumer.",
+      "props": {
+        "onFiles": { "type": "(files: File[]) => void" },
+        "onReject": { "type": "(rejections: { file: File; reason: 'type' | 'size' | 'multiple' }[]) => void" },
+        "accept": { "type": "string", "notes": "Comma list of extensions and/or MIME patterns (e.g. '.png,image/*')." },
+        "multiple": { "type": "boolean", "default": false },
+        "maxSize": { "type": "number", "notes": "Max bytes per file." },
+        "disabled": { "type": "boolean", "default": false },
+        "label": { "type": "ReactNode" },
+        "hint": { "type": "ReactNode" },
+        "children": { "type": "ReactNode | ((state: { isDragging: boolean }) => ReactNode)", "notes": "Custom content; replaces the default UI." },
+        "classes": { "type": "Partial<DropzoneClasses>", "shape": ["root", "input", "content", "icon", "label", "hint"] }
+      }
+    },
+    "Timer": {
+      "import": "import { Timer } from '@overdoser/react-toolkit'",
+      "element": "div[role=timer]",
+      "forwardsRef": true,
+      "refHandle": "TimerHandle = { start(); pause(); reset(); restart(); getTime(): number; isRunning }",
+      "notes": "Countdown or stopwatch; digital, ring, or segments (one boxed cell per unit with the label below). Uncontrolled with autoStart + imperative ref, or display-only via value. Time values are in seconds; interval is ms.",
+      "props": {
+        "mode": { "type": "'countdown' | 'stopwatch'", "default": "countdown" },
+        "duration": { "type": "number", "notes": "Seconds; countdown length / stopwatch cap; drives ring progress." },
+        "to": { "type": "Date | number", "notes": "Absolute countdown target (overrides duration/pause)." },
+        "value": { "type": "number", "notes": "Controlled seconds → display-only (no internal clock)." },
+        "autoStart": { "type": "boolean", "default": true },
+        "running": { "type": "boolean", "notes": "Controlled run state." },
+        "interval": { "type": "number", "default": 1000, "notes": "Tick ms." },
+        "variant": { "type": "'digital' | 'ring' | 'segments'", "default": "digital" },
+        "size": { "type": "'sm' | 'md' | 'lg'", "default": "md" },
+        "format": { "type": "(seconds: number) => ReactNode", "notes": "digital/ring only." },
+        "units": { "type": "('days' | 'hours' | 'minutes' | 'seconds')[]", "notes": "segments variant; default = smallest set that fits the duration; leading unit absorbs overflow." },
+        "unitFormat": { "type": "'long' | 'short'", "default": "short", "notes": "short → d/h/m/s; long → days/hours/minutes/seconds (fixed, no singular/plural)." },
+        "unitLabels": { "type": "Partial<Record<TimerUnit, ReactNode | ((value: number) => ReactNode)>>", "notes": "Override unit labels." },
+        "segmentVariant": { "type": "'boxed' | 'plain'", "default": "boxed", "notes": "boxed = square with number, unit below." },
+        "renderSegment": { "type": "(segment: TimerSegment, index: number) => ReactNode", "notes": "Custom per-cell rendering; TimerSegment = { unit, value, text, label }." },
+        "segmentSeparator": { "type": "ReactNode", "notes": "Content between cells, e.g. ':'." },
+        "label": { "type": "ReactNode" },
+        "labelPlacement": { "type": "'top' | 'bottom' | 'left' | 'right'", "default": "bottom" },
+        "onComplete": { "type": "() => void", "notes": "Countdown reaches zero." },
+        "onTick": { "type": "(seconds: number) => void" },
+        "classes": { "type": "Partial<TimerClasses>", "shape": ["root", "display", "label", "ringTrack", "ringProgress", "segments", "segment", "segmentValue", "segmentLabel"] }
+      }
+    },
+    "Modal": {
+      "import": "import { Modal } from '@overdoser/react-toolkit'",
+      "element": "div (portal at document.body)",
+      "compoundComponents": [
+        "Modal.Header",
+        "Modal.Body",
+        "Modal.Footer"
+      ],
+      "props": {
+        "open": {
+          "type": "boolean",
+          "required": true
+        },
+        "onClose": {
+          "type": "() => void",
+          "required": true
+        },
+        "closeOnBackdrop": {
+          "type": "boolean",
+          "default": true
+        },
+        "closeOnEscape": {
+          "type": "boolean",
+          "default": true
+        },
+        "size": {
+          "type": "enum",
+          "values": [
+            "sm",
+            "md",
+            "lg",
+            "fullscreen"
+          ],
+          "default": "md"
+        },
+        "aria-label": {
+          "type": "string"
+        },
+        "aria-labelledby": {
+          "type": "string"
+        },
+        "classes": {
+          "type": "Partial<ModalClasses>",
+          "shape": [
+            "backdrop",
+            "modal",
+            "header",
+            "closeButton",
+            "body",
+            "footer"
+          ]
+        }
       },
       "subComponents": {
         "Modal.Header": {
           "props": {
-            "children": { "type": "ReactNode", "required": true },
-            "onClose": { "type": "() => void", "notes": "When set, renders an × close button." }
+            "children": {
+              "type": "ReactNode",
+              "required": true
+            },
+            "onClose": {
+              "type": "() => void",
+              "notes": "When set, renders an × close button."
+            }
           }
         },
-        "Modal.Body": { "props": { "children": { "type": "ReactNode", "required": true } } },
-        "Modal.Footer": { "props": { "children": { "type": "ReactNode", "required": true } } }
+        "Modal.Body": {
+          "props": {
+            "children": {
+              "type": "ReactNode",
+              "required": true
+            }
+          }
+        },
+        "Modal.Footer": {
+          "props": {
+            "children": {
+              "type": "ReactNode",
+              "required": true
+            }
+          }
+        }
       },
-      "behavior": ["body scroll lock", "focus trap", "restores prior focus on close"]
+      "behavior": [
+        "body scroll lock",
+        "focus trap",
+        "restores prior focus on close"
+      ]
     },
     "Form": {
       "import": "import { Form } from '@overdoser/react-toolkit'",
       "requires": "react-hook-form",
       "generic": "T extends FieldValues",
       "props": {
-        "form": { "type": "UseFormReturn<T>", "required": true, "notes": "The result of useForm()." },
-        "onSubmit": { "type": "SubmitHandler<T>", "required": true },
-        "errors": { "type": "ReactNode[]", "notes": "Top-of-form errors rendered above children with role=alert." }
+        "form": {
+          "type": "UseFormReturn<T>",
+          "required": true,
+          "notes": "The result of useForm()."
+        },
+        "onSubmit": {
+          "type": "SubmitHandler<T>",
+          "required": true
+        },
+        "errors": {
+          "type": "ReactNode[]",
+          "notes": "Top-of-form errors rendered above children with role=alert."
+        },
+        "reserveErrorSpace": {
+          "type": "boolean | number | string",
+          "default": true,
+          "notes": "Form-wide default for every FormField reserveErrorSpace (fields can override). Same values as the field prop."
+        },
+        "fieldClasses": {
+          "type": "Partial<FormFieldClasses>",
+          "notes": "Default classes applied to every FormField, merged with each field own classes (both apply; fields add not replace). Keys: field, label, message, error, helperText."
+        }
       }
     },
     "FormField": {
       "import": "import { FormField } from '@overdoser/react-toolkit'",
       "requires": "react-hook-form (must be inside <Form>)",
       "props": {
-        "name": { "type": "string", "required": true },
-        "label": { "type": "ReactNode" },
-        "helperText": { "type": "ReactNode" },
-        "required": { "type": "boolean", "notes": "Adds a * indicator next to the label." },
-        "rules": { "type": "Record<string, unknown>", "notes": "Passed to react-hook-form's useController." },
-        "children": { "type": "ReactElement", "required": true, "notes": "Exactly one input element. FormField clones it to inject value/onChange/id/name/error/aria-*." },
-        "classes": { "type": "Partial<FormFieldClasses>", "shape": ["field", "label", "error", "helperText"] }
+        "name": {
+          "type": "string",
+          "required": true
+        },
+        "label": {
+          "type": "ReactNode"
+        },
+        "helperText": {
+          "type": "ReactNode",
+          "notes": "Description below the input. Stays visible on error; the error appears above it (between input and description), not replacing it."
+        },
+        "required": {
+          "type": "boolean",
+          "notes": "Adds a * indicator next to the label."
+        },
+        "rules": {
+          "type": "Record<string, unknown>",
+          "notes": "Passed to react-hook-form's useController."
+        },
+        "reserveErrorSpace": {
+          "type": "boolean | number | string",
+          "default": true,
+          "notes": "Reserves a line AFTER the description so the field outer height stays constant when an error toggles. The error appears between input and description; the reserved spacer collapses 1:1, so fields below do not reflow (only the description shifts down). true=one line (--crk-field-error-min-height); false=no reservation; number=px; string=any CSS length."
+        },
+        "children": {
+          "type": "ReactElement",
+          "required": true,
+          "notes": "Exactly one input element. FormField clones it to inject value/onChange/id/name/error/aria-*."
+        },
+        "classes": {
+          "type": "Partial<FormFieldClasses>",
+          "shape": [
+            "field",
+            "label",
+            "message",
+            "error",
+            "helperText"
+          ]
+        }
       },
       "behavior": {
-        "supportedChildren": ["Input", "Textarea", "Select", "Dropdown (select-mode)", "Checkbox", "Radio", "RadioGroup"],
+        "supportedChildren": [
+          "Input",
+          "Textarea",
+          "Select",
+          "Dropdown (select-mode)",
+          "Checkbox",
+          "Radio",
+          "RadioGroup",
+          "CheckboxGroup"
+        ],
         "bridges": {
           "onValueChange": "Bridged to react-hook-form onChange (Select single, Dropdown).",
           "onValuesChange": "Bridged to react-hook-form onChange (Select multi).",
-          "checked": "Auto-set from value when value is boolean (Checkbox)."
+          "checked": "Auto-set from value when value is boolean (Checkbox).",
+          "values": "CheckboxGroup binds value:string[]/onChange(values) directly to the field — no bridge needed."
         }
       }
     },
     "FormRow": {
       "import": "import { FormRow } from '@overdoser/react-toolkit'",
-      "props": { "children": { "type": "ReactNode", "required": true } }
+      "props": {
+        "children": {
+          "type": "ReactNode",
+          "required": true
+        }
+      }
     },
     "Input": {
       "import": "import { Input } from '@overdoser/react-toolkit'",
@@ -226,11 +1215,35 @@
       "extendsNativeProps": "input (without prefix)",
       "forwardsRef": true,
       "props": {
-        "inputSize": { "type": "enum", "values": ["sm", "md", "lg"], "default": "md", "notes": "Toolkit size scale; independent of the native `size` HTML attribute." },
-        "error": { "type": "boolean", "default": false },
-        "prefix": { "type": "ReactNode" },
-        "suffix": { "type": "ReactNode" },
-        "classes": { "type": "Partial<InputClasses>", "shape": ["root", "wrapper", "prefix", "suffix"] }
+        "inputSize": {
+          "type": "enum",
+          "values": [
+            "sm",
+            "md",
+            "lg"
+          ],
+          "default": "md",
+          "notes": "Toolkit size scale; independent of the native `size` HTML attribute."
+        },
+        "error": {
+          "type": "boolean",
+          "default": false
+        },
+        "prefix": {
+          "type": "ReactNode"
+        },
+        "suffix": {
+          "type": "ReactNode"
+        },
+        "classes": {
+          "type": "Partial<InputClasses>",
+          "shape": [
+            "root",
+            "wrapper",
+            "prefix",
+            "suffix"
+          ]
+        }
       }
     },
     "Select": {
@@ -244,24 +1257,95 @@
         "multi": "When `multiple=true`. Chip-based multi with text filter."
       },
       "props": {
-        "inputSize": { "type": "enum", "values": ["sm", "md", "lg"], "default": "md" },
-        "error": { "type": "boolean", "default": false },
-        "options": { "type": "{ value: string; label: string; content?: ReactNode; disabled?: boolean }[]" },
-        "placeholder": { "type": "string", "default": "Select..." },
-        "searchable": { "type": "boolean", "default": false },
-        "searchPlaceholder": { "type": "string", "default": "Search..." },
-        "multiple": { "type": "boolean", "default": false },
-        "value": { "type": "string | string[]", "notes": "string for single-mode, string[] for multi." },
-        "onChange": { "type": "(e: ChangeEvent<HTMLSelectElement>) => void", "notes": "Native + searchable (synthetic for searchable)." },
-        "onValueChange": { "type": "(value: string) => void", "notes": "Single-mode value-only callback." },
-        "onValuesChange": { "type": "(values: string[]) => void", "notes": "Multi-mode callback." },
-        "clearSearchOnSelect": { "type": "boolean", "default": true, "notes": "Multi-mode only." },
-        "closeOnSelect": { "type": "boolean", "default": true, "notes": "Multi-mode only. Menu closes after each add/remove/create. Set false for the stay-open pattern." },
-        "allowCreate": { "type": "boolean", "default": false, "notes": "Multi-mode only. Adds a 'Create <query>' row when the query doesn't match an existing option; pressing Enter (or clicking it) pushes the trimmed query into onValuesChange and fires onCreate." },
-        "onCreate": { "type": "(value: string) => void", "notes": "Multi-mode only. Paired with allowCreate." },
-        "createLabel": { "type": "(query: string) => ReactNode", "notes": "Multi-mode only. Custom render for the Create row." },
-        "portal": { "type": "boolean", "default": true, "notes": "Applies to searchable + multiple modes. Renders the open menu in a portal at document.body using --crk-z-floating (1060) — escapes overflow:hidden ancestors and sits above modals. Set false to keep the menu in the trigger's subtree." },
-        "classes": { "type": "Partial<SelectClasses>", "shape": ["wrapper", "root", "arrow", "search", "menu", "item", "chip", "chipRemove"] }
+        "inputSize": {
+          "type": "enum",
+          "values": [
+            "sm",
+            "md",
+            "lg"
+          ],
+          "default": "md"
+        },
+        "error": {
+          "type": "boolean",
+          "default": false
+        },
+        "options": {
+          "type": "{ value: string; label: string; content?: ReactNode; disabled?: boolean }[]"
+        },
+        "placeholder": {
+          "type": "string",
+          "default": "Select..."
+        },
+        "searchable": {
+          "type": "boolean",
+          "default": false
+        },
+        "searchPlaceholder": {
+          "type": "string",
+          "default": "Search..."
+        },
+        "multiple": {
+          "type": "boolean",
+          "default": false
+        },
+        "value": {
+          "type": "string | string[]",
+          "notes": "string for single-mode, string[] for multi."
+        },
+        "onChange": {
+          "type": "(e: ChangeEvent<HTMLSelectElement>) => void",
+          "notes": "Native + searchable (synthetic for searchable)."
+        },
+        "onValueChange": {
+          "type": "(value: string) => void",
+          "notes": "Single-mode value-only callback."
+        },
+        "onValuesChange": {
+          "type": "(values: string[]) => void",
+          "notes": "Multi-mode callback."
+        },
+        "clearSearchOnSelect": {
+          "type": "boolean",
+          "default": true,
+          "notes": "Multi-mode only."
+        },
+        "closeOnSelect": {
+          "type": "boolean",
+          "default": true,
+          "notes": "Multi-mode only. Menu closes after each add/remove/create. Set false for the stay-open pattern."
+        },
+        "allowCreate": {
+          "type": "boolean",
+          "default": false,
+          "notes": "Multi-mode only. Adds a 'Create <query>' row when the query doesn't match an existing option; pressing Enter (or clicking it) pushes the trimmed query into onValuesChange and fires onCreate."
+        },
+        "onCreate": {
+          "type": "(value: string) => void",
+          "notes": "Multi-mode only. Paired with allowCreate."
+        },
+        "createLabel": {
+          "type": "(query: string) => ReactNode",
+          "notes": "Multi-mode only. Custom render for the Create row."
+        },
+        "portal": {
+          "type": "boolean",
+          "default": true,
+          "notes": "Applies to searchable + multiple modes. Renders the open menu in a portal at document.body using --crk-z-floating (1060) — escapes overflow:hidden ancestors and sits above modals. Set false to keep the menu in the trigger's subtree."
+        },
+        "classes": {
+          "type": "Partial<SelectClasses>",
+          "shape": [
+            "wrapper",
+            "root",
+            "arrow",
+            "search",
+            "menu",
+            "item",
+            "chip",
+            "chipRemove"
+          ]
+        }
       }
     },
     "Checkbox": {
@@ -270,9 +1354,107 @@
       "extendsNativeProps": "input",
       "forwardsRef": true,
       "props": {
-        "label": { "type": "ReactNode" },
-        "indeterminate": { "type": "boolean", "default": false },
-        "classes": { "type": "Partial<CheckboxClasses>", "shape": ["root", "input", "label"] }
+        "label": {
+          "type": "ReactNode"
+        },
+        "variant": {
+          "type": "'checkbox' | 'switch'",
+          "default": "checkbox",
+          "notes": "switch renders a sliding toggle; the underlying input[type=checkbox] is identical."
+        },
+        "indeterminate": {
+          "type": "boolean",
+          "default": false,
+          "notes": "Ignored when variant=switch."
+        },
+        "classes": {
+          "type": "Partial<CheckboxClasses>",
+          "shape": [
+            "root",
+            "input",
+            "label"
+          ]
+        }
+      }
+    },
+    "CheckboxGroup": {
+      "import": "import { CheckboxGroup } from '@overdoser/react-toolkit'",
+      "element": "div[role=group]",
+      "forwardsRef": true,
+      "props": {
+        "options": {
+          "type": "{ value: string; label: ReactNode; disabled?: boolean }[]",
+          "required": true
+        },
+        "value": {
+          "type": "string[]",
+          "default": [],
+          "notes": "Controlled selected values."
+        },
+        "onChange": {
+          "type": "(values: string[]) => void",
+          "notes": "Fires with the next array on each toggle."
+        },
+        "variant": {
+          "type": "enum",
+          "values": [
+            "checkbox",
+            "chips"
+          ],
+          "default": "checkbox",
+          "notes": "chips renders toggleable buttons (role=checkbox, aria-checked)."
+        },
+        "chipShape": {
+          "type": "enum",
+          "values": [
+            "pill",
+            "rounded",
+            "square"
+          ],
+          "default": "pill",
+          "notes": "Chip corner style (chips only); square is the most rectangular."
+        },
+        "chipCheckmark": {
+          "type": "boolean",
+          "default": true,
+          "notes": "Leading checkmark on selected chips (chips only). Chip total width stays constant: when checked, horizontal padding shrinks on both sides by half the mark+gap, so the freed space fits the mark and the centered content does not jump."
+        },
+        "orientation": {
+          "type": "enum",
+          "values": [
+            "vertical",
+            "horizontal"
+          ],
+          "notes": "Defaults to vertical for checkbox, horizontal (wrapping) for chips."
+        },
+        "disabled": {
+          "type": "boolean",
+          "default": false,
+          "notes": "Disables every option; per-option via options[].disabled."
+        },
+        "error": {
+          "type": "boolean",
+          "default": false
+        },
+        "name": {
+          "type": "string"
+        },
+        "required": {
+          "type": "boolean",
+          "notes": "Sets aria-required on the group."
+        },
+        "classes": {
+          "type": "Partial<CheckboxGroupClasses>",
+          "shape": [
+            "group",
+            "option",
+            "chip",
+            "chipSelected"
+          ]
+        }
+      },
+      "behavior": {
+        "formField": "Works inside <FormField> directly (value:string[]/onChange(values) bind to the field)."
       }
     },
     "Radio": {
@@ -281,9 +1463,21 @@
       "extendsNativeProps": "input (without type)",
       "forwardsRef": true,
       "props": {
-        "value": { "type": "string", "required": true },
-        "label": { "type": "ReactNode" },
-        "classes": { "type": "Partial<RadioClasses>", "shape": ["root", "input", "label"] }
+        "value": {
+          "type": "string",
+          "required": true
+        },
+        "label": {
+          "type": "ReactNode"
+        },
+        "classes": {
+          "type": "Partial<RadioClasses>",
+          "shape": [
+            "root",
+            "input",
+            "label"
+          ]
+        }
       },
       "behavior": "Inside a <RadioGroup>, name/checked/onChange come from context — do not pass them on Radio."
     },
@@ -291,13 +1485,29 @@
       "import": "import { RadioGroup } from '@overdoser/react-toolkit'",
       "element": "div[role=radiogroup]",
       "props": {
-        "name": { "type": "string", "required": true },
-        "value": { "type": "string", "notes": "Controlled selected value." },
-        "onChange": { "type": "(value: string) => void" },
-        "id": { "type": "string" },
-        "aria-label": { "type": "string" },
-        "aria-labelledby": { "type": "string" },
-        "required": { "type": "boolean" }
+        "name": {
+          "type": "string",
+          "required": true
+        },
+        "value": {
+          "type": "string",
+          "notes": "Controlled selected value."
+        },
+        "onChange": {
+          "type": "(value: string) => void"
+        },
+        "id": {
+          "type": "string"
+        },
+        "aria-label": {
+          "type": "string"
+        },
+        "aria-labelledby": {
+          "type": "string"
+        },
+        "required": {
+          "type": "boolean"
+        }
       }
     },
     "Textarea": {
@@ -306,17 +1516,53 @@
       "extendsNativeProps": "textarea",
       "forwardsRef": true,
       "props": {
-        "inputSize": { "type": "enum", "values": ["sm", "md", "lg"], "default": "md" },
-        "error": { "type": "boolean", "default": false },
-        "resize": { "type": "enum", "values": ["none", "vertical", "horizontal", "both"], "default": "vertical", "notes": "Ignored when autoExpand=true." },
-        "autoExpand": { "type": "boolean", "default": true, "notes": "When true, auto-grows height to fit content." }
+        "inputSize": {
+          "type": "enum",
+          "values": [
+            "sm",
+            "md",
+            "lg"
+          ],
+          "default": "md"
+        },
+        "error": {
+          "type": "boolean",
+          "default": false
+        },
+        "resize": {
+          "type": "enum",
+          "values": [
+            "none",
+            "vertical",
+            "horizontal",
+            "both"
+          ],
+          "default": "vertical",
+          "notes": "Ignored when autoExpand=true."
+        },
+        "autoExpand": {
+          "type": "boolean",
+          "default": true,
+          "notes": "When true, auto-grows height to fit content."
+        }
       }
     },
     "LineChart": {
       "import": "import { LineChart, type ChartConfig } from '@overdoser/react-toolkit'",
       "element": "div containing responsive SVG",
       "generic": "T extends Record<string, unknown>",
-      "themeTokens": ["--crk-chart-1", "--crk-chart-2", "--crk-chart-3", "--crk-chart-4", "--crk-chart-5", "--crk-chart-grid", "--crk-chart-axis", "--crk-chart-label-inside", "--crk-chart-tooltip-bg", "--crk-chart-tooltip-text"],
+      "themeTokens": [
+        "--crk-chart-1",
+        "--crk-chart-2",
+        "--crk-chart-3",
+        "--crk-chart-4",
+        "--crk-chart-5",
+        "--crk-chart-grid",
+        "--crk-chart-axis",
+        "--crk-chart-label-inside",
+        "--crk-chart-tooltip-bg",
+        "--crk-chart-tooltip-text"
+      ],
       "shadcnVariantMapping": {
         "default": "no extra props",
         "multiple": "no extra props (multiple keys in config)",
@@ -330,31 +1576,123 @@
         "interactive": "Series-toggle pattern: keep multiple series in `data` but pass only the active series in `config` (`{ [active]: fullConfig[active] }`). Consumer-side selector — tiles, prev/next navigator, or <Dropdown> (see recipes/interactive-line-chart.tsx)."
       },
       "props": {
-        "data": { "type": "T[]", "required": true },
-        "xKey": { "type": "keyof T & string", "required": true },
-        "config": { "type": "ChartConfig", "required": true, "notes": "Record<string, { label, color }> keyed by data-field names." },
-        "aspectRatio": { "type": "number", "default": "16/9" },
-        "height": { "type": "number", "notes": "Fixed pixel height. Overrides aspectRatio." },
-        "curve": { "type": "enum", "values": ["linear", "monotone", "step"], "default": "monotone", "notes": "'step' is step-after — value holds until the next x." },
-        "showPoints": { "type": "boolean", "default": true },
-        "dotColorKey": { "type": "keyof T & string", "notes": "Each dot's fill = row[dotColorKey]. Line keeps the series color. Tooltip swatch follows the dot color." },
-        "renderDot": { "type": "(args: { row, value, seriesKey, index, x, y, color, active }) => ReactNode", "notes": "Replaces the default circle with custom SVG per point." },
-        "showValues": { "type": "boolean", "default": false },
-        "valuePosition": { "type": "enum", "values": ["top", "bottom"], "default": "top" },
-        "renderLabel": { "type": "(args: { row, value, seriesKey, index }) => ReactNode", "notes": "Custom label content. Overrides valueFormat for labels. Return null to skip." },
-        "activeIndex": { "type": "number", "notes": "Highlight a specific point index; other points fade." },
-        "onPointClick": { "type": "(args: { row, value, seriesKey, index }) => void" },
-        "showGrid": { "type": "boolean", "default": true },
-        "showLegend": { "type": "boolean", "default": true },
-        "showTooltip": { "type": "boolean", "default": true },
-        "yTickCount": { "type": "number", "default": 5 },
-        "yFormat": { "type": "(v: number) => string" },
-        "xFormat": { "type": "(v: string) => string" },
-        "valueFormat": { "type": "(v: number) => string" },
-        "renderTooltip": { "type": "(row: T) => ReactNode" },
-        "margin": { "type": "Partial<ChartMargin>", "default": "{ top: 12, right: 16, bottom: 28, left: 48 }" },
-        "emptyMessage": { "type": "ReactNode", "default": "No data" },
-        "classes": { "type": "Partial<ChartClasses>", "shape": ["root", "svg", "grid", "axis", "axisLabel", "series", "point", "legend", "legendItem", "tooltip"] }
+        "data": {
+          "type": "T[]",
+          "required": true
+        },
+        "xKey": {
+          "type": "keyof T & string",
+          "required": true
+        },
+        "config": {
+          "type": "ChartConfig",
+          "required": true,
+          "notes": "Record<string, { label, color }> keyed by data-field names."
+        },
+        "aspectRatio": {
+          "type": "number",
+          "default": "16/9"
+        },
+        "height": {
+          "type": "number",
+          "notes": "Fixed pixel height. Overrides aspectRatio."
+        },
+        "curve": {
+          "type": "enum",
+          "values": [
+            "linear",
+            "monotone",
+            "step"
+          ],
+          "default": "monotone",
+          "notes": "'step' is step-after — value holds until the next x."
+        },
+        "showPoints": {
+          "type": "boolean",
+          "default": true
+        },
+        "dotColorKey": {
+          "type": "keyof T & string",
+          "notes": "Each dot's fill = row[dotColorKey]. Line keeps the series color. Tooltip swatch follows the dot color."
+        },
+        "renderDot": {
+          "type": "(args: { row, value, seriesKey, index, x, y, color, active }) => ReactNode",
+          "notes": "Replaces the default circle with custom SVG per point."
+        },
+        "showValues": {
+          "type": "boolean",
+          "default": false
+        },
+        "valuePosition": {
+          "type": "enum",
+          "values": [
+            "top",
+            "bottom"
+          ],
+          "default": "top"
+        },
+        "renderLabel": {
+          "type": "(args: { row, value, seriesKey, index }) => ReactNode",
+          "notes": "Custom label content. Overrides valueFormat for labels. Return null to skip."
+        },
+        "activeIndex": {
+          "type": "number",
+          "notes": "Highlight a specific point index; other points fade."
+        },
+        "onPointClick": {
+          "type": "(args: { row, value, seriesKey, index }) => void"
+        },
+        "showGrid": {
+          "type": "boolean",
+          "default": true
+        },
+        "showLegend": {
+          "type": "boolean",
+          "default": true
+        },
+        "showTooltip": {
+          "type": "boolean",
+          "default": true
+        },
+        "yTickCount": {
+          "type": "number",
+          "default": 5
+        },
+        "yFormat": {
+          "type": "(v: number) => string"
+        },
+        "xFormat": {
+          "type": "(v: string) => string"
+        },
+        "valueFormat": {
+          "type": "(v: number) => string"
+        },
+        "renderTooltip": {
+          "type": "(row: T) => ReactNode"
+        },
+        "margin": {
+          "type": "Partial<ChartMargin>",
+          "default": "{ top: 12, right: 16, bottom: 28, left: 48 }"
+        },
+        "emptyMessage": {
+          "type": "ReactNode",
+          "default": "No data"
+        },
+        "classes": {
+          "type": "Partial<ChartClasses>",
+          "shape": [
+            "root",
+            "svg",
+            "grid",
+            "axis",
+            "axisLabel",
+            "series",
+            "point",
+            "legend",
+            "legendItem",
+            "tooltip"
+          ]
+        }
       }
     },
     "AreaChart": {
@@ -374,28 +1712,100 @@
         "interactive": "Data-range filter: all series stay rendered (typically stacked + fillGradient); the selector swaps the slice of `data` shown (e.g. last 7d/14d/30d). Not a series toggle. Consumer-side selector — tiles, prev/next navigator, or <Dropdown>. See recipes/interactive-area-chart.tsx."
       },
       "props": {
-        "data": { "type": "T[]", "required": true },
-        "xKey": { "type": "keyof T & string", "required": true },
-        "config": { "type": "ChartConfig", "required": true, "notes": "Each SeriesConfig may also include `icon?: ReactNode` to override the legend swatch." },
-        "aspectRatio": { "type": "number", "default": "16/9" },
-        "height": { "type": "number" },
-        "curve": { "type": "enum", "values": ["linear", "monotone", "step"], "default": "monotone" },
-        "stacked": { "type": "boolean", "default": false, "notes": "Stacks series bottom-up in config-key order." },
-        "stackOffset": { "type": "enum", "values": ["none", "expand"], "default": "none", "notes": "`'expand'` normalizes each row to 100%. Requires stacked=true." },
-        "fillGradient": { "type": "boolean", "default": false, "notes": "Per-series vertical linear gradient (opaque top → transparent bottom)." },
-        "showGrid": { "type": "boolean", "default": true },
-        "showXAxis": { "type": "boolean", "default": true },
-        "showYAxis": { "type": "boolean", "default": true },
-        "showLegend": { "type": "boolean", "default": true },
-        "showTooltip": { "type": "boolean", "default": true },
-        "yTickCount": { "type": "number", "default": 5 },
-        "yFormat": { "type": "(v: number) => string" },
-        "xFormat": { "type": "(v: string) => string" },
-        "valueFormat": { "type": "(v: number) => string" },
-        "renderTooltip": { "type": "(row: T) => ReactNode" },
-        "margin": { "type": "Partial<ChartMargin>" },
-        "emptyMessage": { "type": "ReactNode", "default": "No data" },
-        "classes": { "type": "Partial<ChartClasses>" }
+        "data": {
+          "type": "T[]",
+          "required": true
+        },
+        "xKey": {
+          "type": "keyof T & string",
+          "required": true
+        },
+        "config": {
+          "type": "ChartConfig",
+          "required": true,
+          "notes": "Each SeriesConfig may also include `icon?: ReactNode` to override the legend swatch."
+        },
+        "aspectRatio": {
+          "type": "number",
+          "default": "16/9"
+        },
+        "height": {
+          "type": "number"
+        },
+        "curve": {
+          "type": "enum",
+          "values": [
+            "linear",
+            "monotone",
+            "step"
+          ],
+          "default": "monotone"
+        },
+        "stacked": {
+          "type": "boolean",
+          "default": false,
+          "notes": "Stacks series bottom-up in config-key order."
+        },
+        "stackOffset": {
+          "type": "enum",
+          "values": [
+            "none",
+            "expand"
+          ],
+          "default": "none",
+          "notes": "`'expand'` normalizes each row to 100%. Requires stacked=true."
+        },
+        "fillGradient": {
+          "type": "boolean",
+          "default": false,
+          "notes": "Per-series vertical linear gradient (opaque top → transparent bottom)."
+        },
+        "showGrid": {
+          "type": "boolean",
+          "default": true
+        },
+        "showXAxis": {
+          "type": "boolean",
+          "default": true
+        },
+        "showYAxis": {
+          "type": "boolean",
+          "default": true
+        },
+        "showLegend": {
+          "type": "boolean",
+          "default": true
+        },
+        "showTooltip": {
+          "type": "boolean",
+          "default": true
+        },
+        "yTickCount": {
+          "type": "number",
+          "default": 5
+        },
+        "yFormat": {
+          "type": "(v: number) => string"
+        },
+        "xFormat": {
+          "type": "(v: string) => string"
+        },
+        "valueFormat": {
+          "type": "(v: number) => string"
+        },
+        "renderTooltip": {
+          "type": "(row: T) => ReactNode"
+        },
+        "margin": {
+          "type": "Partial<ChartMargin>"
+        },
+        "emptyMessage": {
+          "type": "ReactNode",
+          "default": "No data"
+        },
+        "classes": {
+          "type": "Partial<ChartClasses>"
+        }
       }
     },
     "BarChart": {
@@ -416,35 +1826,134 @@
         "interactive": "Series-toggle pattern: keep multiple series in `data` but pass only the active series in `config` (`{ [active]: fullConfig[active] }`). Consumer-side selector — tiles, prev/next navigator, or <Dropdown> (see recipes/interactive-bar-chart.tsx)."
       },
       "props": {
-        "data": { "type": "T[]", "required": true },
-        "xKey": { "type": "keyof T & string", "required": true },
-        "config": { "type": "ChartConfig", "required": true },
-        "orientation": { "type": "enum", "values": ["vertical", "horizontal"], "default": "vertical" },
-        "stacked": { "type": "boolean", "default": false, "notes": "Stack series within each category. Ignored with a single series." },
-        "aspectRatio": { "type": "number", "default": "16/9" },
-        "height": { "type": "number" },
-        "groupPadding": { "type": "number", "default": 0.2, "notes": "Inner padding between category groups, fraction of band width." },
-        "barPadding": { "type": "number", "default": 0.1, "notes": "Inner padding between bars within a grouped group, fraction of bar width. Ignored when stacked." },
-        "barRadius": { "type": "number", "default": 4 },
-        "showGrid": { "type": "boolean", "default": true },
-        "showLegend": { "type": "boolean", "default": true },
-        "showTooltip": { "type": "boolean", "default": true },
-        "showValues": { "type": "boolean", "default": false, "notes": "Render a numeric label on every bar." },
-        "valuePosition": { "type": "enum", "values": ["outside", "inside", "inside-start"], "default": "outside", "notes": "'inside-start' anchors at the baseline edge of the bar; on vertical bars the text rotates ±90° to read along the bar's length." },
-        "renderLabel": { "type": "(args: { row, value, seriesKey, index }) => ReactNode", "notes": "Custom label content. Return null to skip. Overrides valueFormat for labels." },
-        "colorBy": { "type": "enum", "values": ["series", "index"], "default": "series", "notes": "'index' picks color per row from `colors` (config colors are ignored)." },
-        "colors": { "type": "string[]", "default": "the five --crk-chart-N tokens", "notes": "Palette used when colorBy='index'." },
-        "negativeColor": { "type": "string", "notes": "Override fill applied to bars whose value is negative." },
-        "activeIndex": { "type": "number", "notes": "Highlight one category index; other groups fade." },
-        "onBarClick": { "type": "(args: { row, value, seriesKey, index }) => void" },
-        "yTickCount": { "type": "number", "default": 5 },
-        "yFormat": { "type": "(v: number) => string" },
-        "xFormat": { "type": "(v: string) => string" },
-        "valueFormat": { "type": "(v: number) => string" },
-        "renderTooltip": { "type": "(row: T) => ReactNode" },
-        "margin": { "type": "Partial<ChartMargin>" },
-        "emptyMessage": { "type": "ReactNode", "default": "No data" },
-        "classes": { "type": "Partial<ChartClasses>" }
+        "data": {
+          "type": "T[]",
+          "required": true
+        },
+        "xKey": {
+          "type": "keyof T & string",
+          "required": true
+        },
+        "config": {
+          "type": "ChartConfig",
+          "required": true
+        },
+        "orientation": {
+          "type": "enum",
+          "values": [
+            "vertical",
+            "horizontal"
+          ],
+          "default": "vertical"
+        },
+        "stacked": {
+          "type": "boolean",
+          "default": false,
+          "notes": "Stack series within each category. Ignored with a single series."
+        },
+        "aspectRatio": {
+          "type": "number",
+          "default": "16/9"
+        },
+        "height": {
+          "type": "number"
+        },
+        "groupPadding": {
+          "type": "number",
+          "default": 0.2,
+          "notes": "Inner padding between category groups, fraction of band width."
+        },
+        "barPadding": {
+          "type": "number",
+          "default": 0.1,
+          "notes": "Inner padding between bars within a grouped group, fraction of bar width. Ignored when stacked."
+        },
+        "barRadius": {
+          "type": "number",
+          "default": 4
+        },
+        "showGrid": {
+          "type": "boolean",
+          "default": true
+        },
+        "showLegend": {
+          "type": "boolean",
+          "default": true
+        },
+        "showTooltip": {
+          "type": "boolean",
+          "default": true
+        },
+        "showValues": {
+          "type": "boolean",
+          "default": false,
+          "notes": "Render a numeric label on every bar."
+        },
+        "valuePosition": {
+          "type": "enum",
+          "values": [
+            "outside",
+            "inside",
+            "inside-start"
+          ],
+          "default": "outside",
+          "notes": "'inside-start' anchors at the baseline edge of the bar; on vertical bars the text rotates ±90° to read along the bar's length."
+        },
+        "renderLabel": {
+          "type": "(args: { row, value, seriesKey, index }) => ReactNode",
+          "notes": "Custom label content. Return null to skip. Overrides valueFormat for labels."
+        },
+        "colorBy": {
+          "type": "enum",
+          "values": [
+            "series",
+            "index"
+          ],
+          "default": "series",
+          "notes": "'index' picks color per row from `colors` (config colors are ignored)."
+        },
+        "colors": {
+          "type": "string[]",
+          "default": "the five --crk-chart-N tokens",
+          "notes": "Palette used when colorBy='index'."
+        },
+        "negativeColor": {
+          "type": "string",
+          "notes": "Override fill applied to bars whose value is negative."
+        },
+        "activeIndex": {
+          "type": "number",
+          "notes": "Highlight one category index; other groups fade."
+        },
+        "onBarClick": {
+          "type": "(args: { row, value, seriesKey, index }) => void"
+        },
+        "yTickCount": {
+          "type": "number",
+          "default": 5
+        },
+        "yFormat": {
+          "type": "(v: number) => string"
+        },
+        "xFormat": {
+          "type": "(v: string) => string"
+        },
+        "valueFormat": {
+          "type": "(v: number) => string"
+        },
+        "renderTooltip": {
+          "type": "(row: T) => ReactNode"
+        },
+        "margin": {
+          "type": "Partial<ChartMargin>"
+        },
+        "emptyMessage": {
+          "type": "ReactNode",
+          "default": "No data"
+        },
+        "classes": {
+          "type": "Partial<ChartClasses>"
+        }
       }
     },
     "PieChart": {
@@ -465,31 +1974,109 @@
         "stacked": "Not currently supported (nested rings)."
       },
       "props": {
-        "data": { "type": "T[]", "required": true },
-        "valueKey": { "type": "keyof T & string", "required": true },
-        "nameKey": { "type": "keyof T & string", "required": true },
-        "colorKey": { "type": "keyof T & string", "notes": "Per-row fill from data; falls back to `colors` palette." },
-        "colors": { "type": "string[]", "default": "the five --crk-chart-N tokens" },
-        "aspectRatio": { "type": "number", "default": 1 },
-        "height": { "type": "number" },
-        "innerRadius": { "type": "number | string", "default": 0, "notes": "0 = pie, >0 = donut. Number = pixels, string = 'NN%' of half the minimum chart side." },
-        "outerRadius": { "type": "number | string", "default": "'90%'" },
-        "strokeWidth": { "type": "number", "default": 2, "notes": "Slice separator stroke width. 0 = 'separator-none'." },
-        "strokeColor": { "type": "string", "default": "var(--crk-color-bg)" },
-        "padAngle": { "type": "number", "default": 0, "notes": "Degrees of visual gap between slices." },
-        "showLabels": { "type": "boolean", "default": false },
-        "valuePosition": { "type": "enum", "values": ["outside", "inside"], "default": "outside" },
-        "showLabelLines": { "type": "boolean", "default": true, "notes": "Thin slice-colored leader line from the slice edge to each outside label. No effect for inside labels." },
-        "renderLabel": { "type": "(args: { row, value, fraction, index }) => ReactNode", "notes": "Overrides showLabels default content. Return null to skip a slice." },
-        "centerLabel": { "type": "ReactNode", "notes": "Rendered via foreignObject in the centre of the chart (only useful with innerRadius > 0)." },
-        "activeIndex": { "type": "number", "notes": "Pulls the slice outward; other slices fade." },
-        "onSliceClick": { "type": "(args: { row, value, index }) => void" },
-        "showLegend": { "type": "boolean", "default": true },
-        "showTooltip": { "type": "boolean", "default": true },
-        "valueFormat": { "type": "(v: number) => string" },
-        "renderTooltip": { "type": "(row: T) => ReactNode" },
-        "emptyMessage": { "type": "ReactNode", "default": "No data" },
-        "classes": { "type": "Partial<ChartClasses>" }
+        "data": {
+          "type": "T[]",
+          "required": true
+        },
+        "valueKey": {
+          "type": "keyof T & string",
+          "required": true
+        },
+        "nameKey": {
+          "type": "keyof T & string",
+          "required": true
+        },
+        "colorKey": {
+          "type": "keyof T & string",
+          "notes": "Per-row fill from data; falls back to `colors` palette."
+        },
+        "colors": {
+          "type": "string[]",
+          "default": "the five --crk-chart-N tokens"
+        },
+        "aspectRatio": {
+          "type": "number",
+          "default": 1
+        },
+        "height": {
+          "type": "number"
+        },
+        "innerRadius": {
+          "type": "number | string",
+          "default": 0,
+          "notes": "0 = pie, >0 = donut. Number = pixels, string = 'NN%' of half the minimum chart side."
+        },
+        "outerRadius": {
+          "type": "number | string",
+          "default": "'90%'"
+        },
+        "strokeWidth": {
+          "type": "number",
+          "default": 2,
+          "notes": "Slice separator stroke width. 0 = 'separator-none'."
+        },
+        "strokeColor": {
+          "type": "string",
+          "default": "var(--crk-color-bg)"
+        },
+        "padAngle": {
+          "type": "number",
+          "default": 0,
+          "notes": "Degrees of visual gap between slices."
+        },
+        "showLabels": {
+          "type": "boolean",
+          "default": false
+        },
+        "valuePosition": {
+          "type": "enum",
+          "values": [
+            "outside",
+            "inside"
+          ],
+          "default": "outside"
+        },
+        "showLabelLines": {
+          "type": "boolean",
+          "default": true,
+          "notes": "Thin slice-colored leader line from the slice edge to each outside label. No effect for inside labels."
+        },
+        "renderLabel": {
+          "type": "(args: { row, value, fraction, index }) => ReactNode",
+          "notes": "Overrides showLabels default content. Return null to skip a slice."
+        },
+        "centerLabel": {
+          "type": "ReactNode",
+          "notes": "Rendered via foreignObject in the centre of the chart (only useful with innerRadius > 0)."
+        },
+        "activeIndex": {
+          "type": "number",
+          "notes": "Pulls the slice outward; other slices fade."
+        },
+        "onSliceClick": {
+          "type": "(args: { row, value, index }) => void"
+        },
+        "showLegend": {
+          "type": "boolean",
+          "default": true
+        },
+        "showTooltip": {
+          "type": "boolean",
+          "default": true
+        },
+        "valueFormat": {
+          "type": "(v: number) => string"
+        },
+        "renderTooltip": {
+          "type": "(row: T) => ReactNode"
+        },
+        "emptyMessage": {
+          "type": "ReactNode",
+          "default": "No data"
+        },
+        "classes": {
+          "type": "Partial<ChartClasses>"
+        }
       }
     },
     "RadarChart": {
@@ -513,28 +2100,95 @@
         "radius": "showRadiusAxis"
       },
       "props": {
-        "data": { "type": "T[]", "required": true },
-        "axisKey": { "type": "keyof T & string", "required": true },
-        "config": { "type": "ChartConfig", "required": true, "notes": "SeriesConfig may include `icon` for the icons variant." },
-        "aspectRatio": { "type": "number", "default": 1 },
-        "height": { "type": "number" },
-        "gridType": { "type": "enum", "values": ["polygon", "circle"], "default": "polygon" },
-        "showGrid": { "type": "boolean", "default": true },
-        "showRadialLines": { "type": "boolean", "default": true },
-        "showAxisLabels": { "type": "boolean", "default": true },
-        "showRadiusAxis": { "type": "boolean", "default": false },
-        "levels": { "type": "number", "default": 5 },
-        "showPoints": { "type": "boolean", "default": true },
-        "fillOpacity": { "type": "number", "default": 0.4, "notes": "0 = 'lines-only' variant." },
-        "strokeWidth": { "type": "number", "default": 2 },
-        "renderAxisLabel": { "type": "(args: { row, index, angle, x, y, textAnchor }) => ReactNode", "notes": "Return null to skip a vertex." },
-        "axisFormat": { "type": "(label: string) => string" },
-        "valueFormat": { "type": "(v: number) => string" },
-        "renderTooltip": { "type": "(row: T) => ReactNode" },
-        "showLegend": { "type": "boolean", "default": true },
-        "showTooltip": { "type": "boolean", "default": true },
-        "emptyMessage": { "type": "ReactNode", "default": "No data" },
-        "classes": { "type": "Partial<ChartClasses>" }
+        "data": {
+          "type": "T[]",
+          "required": true
+        },
+        "axisKey": {
+          "type": "keyof T & string",
+          "required": true
+        },
+        "config": {
+          "type": "ChartConfig",
+          "required": true,
+          "notes": "SeriesConfig may include `icon` for the icons variant."
+        },
+        "aspectRatio": {
+          "type": "number",
+          "default": 1
+        },
+        "height": {
+          "type": "number"
+        },
+        "gridType": {
+          "type": "enum",
+          "values": [
+            "polygon",
+            "circle"
+          ],
+          "default": "polygon"
+        },
+        "showGrid": {
+          "type": "boolean",
+          "default": true
+        },
+        "showRadialLines": {
+          "type": "boolean",
+          "default": true
+        },
+        "showAxisLabels": {
+          "type": "boolean",
+          "default": true
+        },
+        "showRadiusAxis": {
+          "type": "boolean",
+          "default": false
+        },
+        "levels": {
+          "type": "number",
+          "default": 5
+        },
+        "showPoints": {
+          "type": "boolean",
+          "default": true
+        },
+        "fillOpacity": {
+          "type": "number",
+          "default": 0.4,
+          "notes": "0 = 'lines-only' variant."
+        },
+        "strokeWidth": {
+          "type": "number",
+          "default": 2
+        },
+        "renderAxisLabel": {
+          "type": "(args: { row, index, angle, x, y, textAnchor }) => ReactNode",
+          "notes": "Return null to skip a vertex."
+        },
+        "axisFormat": {
+          "type": "(label: string) => string"
+        },
+        "valueFormat": {
+          "type": "(v: number) => string"
+        },
+        "renderTooltip": {
+          "type": "(row: T) => ReactNode"
+        },
+        "showLegend": {
+          "type": "boolean",
+          "default": true
+        },
+        "showTooltip": {
+          "type": "boolean",
+          "default": true
+        },
+        "emptyMessage": {
+          "type": "ReactNode",
+          "default": "No data"
+        },
+        "classes": {
+          "type": "Partial<ChartClasses>"
+        }
       }
     },
     "TradingChart": {
@@ -555,27 +2209,99 @@
         "volume": "{ type: 'volume', upColor?, downColor? } — sub-pane (histogram)"
       },
       "props": {
-        "datafeed": { "type": "Datafeed", "required": true },
-        "symbol": { "type": "string", "required": true },
-        "resolution": { "type": "Resolution", "required": true, "notes": "Bar size (the 'tick interval'). TradingView-style: numeric minutes ('1', '5', '60') or 'D'/'W'/'M'. Any other string passes through to the datafeed." },
-        "period": { "type": "Period", "notes": "Visible time-range window (the 'chart interval'): '1D' | '5D' | '1M' | '3M' | '6M' | '1Y' | '5Y' | '10Y' | '20Y' | 'MAX' or a `<n><unit>` string. Overrides initialLookback when set. 'MAX' fetches from epoch and renders whatever the datafeed returns — pair with a coarse resolution. The chart does not auto-adjust resolution; pair with suggestResolutionForPeriod() / suggestPeriodForResolution() to couple the two." },
-        "seriesType": { "type": "enum", "values": ["candle", "bar", "line", "area"], "default": "candle", "notes": "'bar' = OHLC bars (vertical high-low line, left tick at open, right tick at close)." },
-        "timezone": { "type": "Timezone", "notes": "Controlled timezone for the crosshair time label. 'local' | 'utc' | IANA name. Pair with onTimezoneChange." },
-        "defaultTimezone": { "type": "Timezone", "default": "local", "notes": "Initial timezone when uncontrolled." },
-        "onTimezoneChange": { "type": "(tz: Timezone) => void" },
-        "showConfigPanel": { "type": "boolean", "default": true, "notes": "Gear button in the header that opens a Popover with a Timezone dropdown (Local / UTC / common IANA zones)." },
-        "priceBadgeColorByDirection": { "type": "boolean", "default": false, "notes": "Tint the top cursor-value badge by bar direction (up/down) instead of the neutral palette." },
-        "priceBadgeShowTime": { "type": "boolean", "default": false, "notes": "Append a compact date (D/W/M: '17 Sep 2025') or weekday+date+time (intraday: 'Wed 17 Sep 14:30') AFTER the price in the top cursor-value badge. Honours `timezone`." },
-        "priceBadgeTimeFormat": { "type": "(unixSec: number, resolution: Resolution, timezone: Timezone) => string", "notes": "Optional override for the time portion when priceBadgeShowTime is on. Return any string; empty string suppresses the suffix." },
-        "indicators": { "type": "IndicatorConfig[]" },
-        "precision": { "type": "number", "default": 2 },
-        "initialLookback": { "type": "number", "default": 500, "notes": "Used only when `period` is not set." },
-        "height": { "type": "number", "default": 420 },
-        "upColor": { "type": "string", "default": "var(--crk-color-success)" },
-        "downColor": { "type": "string", "default": "var(--crk-color-danger)" },
-        "lineColor": { "type": "string", "default": "var(--crk-chart-1)" },
-        "onCrosshair": { "type": "(info: CrosshairInfo | null) => void" },
-        "onVisibleRangeChange": { "type": "(range: VisibleRange, bars: Bar[]) => void" }
+        "datafeed": {
+          "type": "Datafeed",
+          "required": true
+        },
+        "symbol": {
+          "type": "string",
+          "required": true
+        },
+        "resolution": {
+          "type": "Resolution",
+          "required": true,
+          "notes": "Bar size (the 'tick interval'). TradingView-style: numeric minutes ('1', '5', '60') or 'D'/'W'/'M'. Any other string passes through to the datafeed."
+        },
+        "period": {
+          "type": "Period",
+          "notes": "Visible time-range window (the 'chart interval'): '1D' | '5D' | '1M' | '3M' | '6M' | '1Y' | '5Y' | '10Y' | '20Y' | 'MAX' or a `<n><unit>` string. Overrides initialLookback when set. 'MAX' fetches from epoch and renders whatever the datafeed returns — pair with a coarse resolution. The chart does not auto-adjust resolution; pair with suggestResolutionForPeriod() / suggestPeriodForResolution() to couple the two."
+        },
+        "seriesType": {
+          "type": "enum",
+          "values": [
+            "candle",
+            "bar",
+            "line",
+            "area"
+          ],
+          "default": "candle",
+          "notes": "'bar' = OHLC bars (vertical high-low line, left tick at open, right tick at close)."
+        },
+        "timezone": {
+          "type": "Timezone",
+          "notes": "Controlled timezone for the crosshair time label. 'local' | 'utc' | IANA name. Pair with onTimezoneChange."
+        },
+        "defaultTimezone": {
+          "type": "Timezone",
+          "default": "local",
+          "notes": "Initial timezone when uncontrolled."
+        },
+        "onTimezoneChange": {
+          "type": "(tz: Timezone) => void"
+        },
+        "showConfigPanel": {
+          "type": "boolean",
+          "default": true,
+          "notes": "Gear button in the header that opens a Popover with a Timezone dropdown (Local / UTC / common IANA zones)."
+        },
+        "priceBadgeColorByDirection": {
+          "type": "boolean",
+          "default": false,
+          "notes": "Tint the top cursor-value badge by bar direction (up/down) instead of the neutral palette."
+        },
+        "priceBadgeShowTime": {
+          "type": "boolean",
+          "default": false,
+          "notes": "Append a compact date (D/W/M: '17 Sep 2025') or weekday+date+time (intraday: 'Wed 17 Sep 14:30') AFTER the price in the top cursor-value badge. Honours `timezone`."
+        },
+        "priceBadgeTimeFormat": {
+          "type": "(unixSec: number, resolution: Resolution, timezone: Timezone) => string",
+          "notes": "Optional override for the time portion when priceBadgeShowTime is on. Return any string; empty string suppresses the suffix."
+        },
+        "indicators": {
+          "type": "IndicatorConfig[]"
+        },
+        "precision": {
+          "type": "number",
+          "default": 2
+        },
+        "initialLookback": {
+          "type": "number",
+          "default": 500,
+          "notes": "Used only when `period` is not set."
+        },
+        "height": {
+          "type": "number",
+          "default": 420
+        },
+        "upColor": {
+          "type": "string",
+          "default": "var(--crk-color-success)"
+        },
+        "downColor": {
+          "type": "string",
+          "default": "var(--crk-color-danger)"
+        },
+        "lineColor": {
+          "type": "string",
+          "default": "var(--crk-chart-1)"
+        },
+        "onCrosshair": {
+          "type": "(info: CrosshairInfo | null) => void"
+        },
+        "onVisibleRangeChange": {
+          "type": "(range: VisibleRange, bars: Bar[]) => void"
+        }
       },
       "interactions": {
         "drag": "pan",
@@ -583,8 +2309,19 @@
         "arrow-keys": "nudge pan",
         "hover": "full crosshair — dashed horizontal + vertical lines, price badge on the right Y axis at the cursor's price, and a time badge under the X axis showing `YYYY-MM-DD HH:MM:SS <tz>` at the cursor's snapped bar (timezone configurable via the gear panel or props). OHLC readout in the chart header."
       },
-      "exportedHelpers": ["periodToSeconds", "suggestResolutionForPeriod", "suggestPeriodForResolution", "formatCrosshairTime"],
-      "exportedIndicatorMath": ["sma", "ema", "bollinger", "rsi", "volumeSeries"],
+      "exportedHelpers": [
+        "periodToSeconds",
+        "suggestResolutionForPeriod",
+        "suggestPeriodForResolution",
+        "formatCrosshairTime"
+      ],
+      "exportedIndicatorMath": [
+        "sma",
+        "ema",
+        "bollinger",
+        "rsi",
+        "volumeSeries"
+      ],
       "outOfScope": [
         "Drawing tools (trend lines, fibonacci, shapes)",
         "Custom indicator settings dialog",
@@ -599,15 +2336,46 @@
       "forwardsRef": true,
       "behavior": "Inline trend line, fixed pixel size, no axes/legend/tooltip — for table cells and KPI tiles.",
       "props": {
-        "data": { "type": "number[]", "required": true },
-        "width": { "type": "number", "default": 80 },
-        "height": { "type": "number", "default": 24 },
-        "color": { "type": "string", "default": "var(--crk-chart-1)" },
-        "strokeWidth": { "type": "number", "default": 1.5 },
-        "curve": { "type": "enum", "values": ["linear", "monotone"], "default": "monotone" },
-        "fill": { "type": "boolean", "default": false, "notes": "Render a low-opacity area under the line." },
-        "showLastPoint": { "type": "boolean", "default": false },
-        "aria-label": { "type": "string" }
+        "data": {
+          "type": "number[]",
+          "required": true
+        },
+        "width": {
+          "type": "number",
+          "default": 80
+        },
+        "height": {
+          "type": "number",
+          "default": 24
+        },
+        "color": {
+          "type": "string",
+          "default": "var(--crk-chart-1)"
+        },
+        "strokeWidth": {
+          "type": "number",
+          "default": 1.5
+        },
+        "curve": {
+          "type": "enum",
+          "values": [
+            "linear",
+            "monotone"
+          ],
+          "default": "monotone"
+        },
+        "fill": {
+          "type": "boolean",
+          "default": false,
+          "notes": "Render a low-opacity area under the line."
+        },
+        "showLastPoint": {
+          "type": "boolean",
+          "default": false
+        },
+        "aria-label": {
+          "type": "string"
+        }
       }
     }
   },