@machinemetrics/mm-react-components 1.1.3 → 1.2.0

package/README.md

@@ -37,6 +37,7 @@ npm install @machinemetrics/mm-react-components
 
 **This library has comprehensive documentation for AI-assisted development!**
 
+- **Lovable (Custom Knowledge):** Add [`agent-docs/lovable.md`](./agent-docs/lovable.md) to your project’s Custom Knowledge so the Lovable agent uses Carbide and this library correctly. (Lovable cannot use skills; this doc is the equivalent.)
 - **New Project Setup:** [`agent-docs/ai-agent-init-guide.md`](./agent-docs/ai-agent-init-guide.md)
 - **Chakra UI Migration:** [`agent-docs/ai-agent-guide.md`](./agent-docs/ai-agent-guide.md)
 - **Component Mappings (83 components):** [`agent-docs/component-mapping-summary.md`](./agent-docs/component-mapping-summary.md)

package/agent-docs/agent-documentation-reference.md

@@ -5,6 +5,8 @@
 > - The main `README.md` with prominent AI agent section at the top
 > - This `agent-docs/` folder with descriptive naming
 > - Package.json exports this folder as `./agent-docs`
+>
+> **For Lovable:** Lovable cannot use installable skills. Add [lovable.md](./lovable.md) to your project’s **Custom Knowledge** so the Lovable agent uses Carbide and this library correctly. The package also exports it as `@machinemetrics/mm-react-components/agent-docs/lovable`.
 
 ## Library Foundation
 
@@ -53,7 +55,7 @@ This directory contains comprehensive documentation and tools for AI agents work
 | Component      | Exports                                                                                                                           | Description                               |
 | -------------- | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
 | **Card**       | `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter`                                                 | Content container with sections (no built-in scroll) |
-| **ScrollArea** | `ScrollArea`, `ScrollBar`                                                                                                         | Scrollable region; use when content can overflow a fixed-height box |
+| **ScrollArea** | `ScrollArea`, `ScrollBar`                                                                                                         | Scrollable region; **must have constrained height** (e.g. `h-[300px]`, `max-h-[50vh]`, or `flex-1 min-h-0` in flex layout) or it won’t scroll |
 | **Separator**  | `Separator`                                                                                                                       | Visual divider                            |
 | **Tabs**       | `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`                                                                                  | Tabbed interface                          |
 | **Breadcrumb** | `Breadcrumb`, `BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbPage`, `BreadcrumbSeparator`, `BreadcrumbEllipsis` | Navigation breadcrumbs                    |
@@ -129,7 +131,8 @@ All components follow shadcn/ui patterns with Carbide theme integration for indu
 **There is no "Panel" component.** For a panel-like or card-like region where content may be longer than the visible area, use **ScrollArea** around the scrollable content. **Card** is a structural container (border, padding, sections) and does not add scrolling.
 
 - **Card**: Use for layout and visual grouping (CardHeader, CardTitle, CardContent, CardFooter). Card does not scroll; overflowing content will clip or spill.
-- **ScrollArea**: Use when content can exceed the box height. Give ScrollArea a fixed or max height (e.g. `className="h-[300px]"` or `max-h-[50vh]`) and put the long content inside it.
+- **ScrollArea**: Use when content can exceed the box height. **ScrollArea only scrolls when it has a constrained height**—without one, the container grows with content and no scrollbar appears. Always give ScrollArea an explicit height: e.g. `className="h-[300px]"` or `max-h-[50vh]`. In a flex column, use `ScrollArea className="flex-1 min-h-0"` (the parent must have a max height; `min-h-0` is required so the flex item can shrink and scroll).
+- **If ScrollArea doesn’t scroll:** Ensure the ScrollArea element has a bounded height (fixed height, max-height, or `flex-1 min-h-0` inside a constrained flex container).
 
 **Pattern for a scrollable card/panel:**
 
@@ -201,6 +204,7 @@ The `DataTable` component supports both client-side and server-side pagination.
 ```
 agent-docs/
 ├── agent-documentation-reference.md    # This reference file
+├── lovable.md                          # For Lovable Custom Knowledge (skill-equivalent)
 ├── ai-agent-init-guide.md              # Main init setup guide
 ├── setup-reference.md                  # Detailed setup reference
 ├── init-troubleshooting.md             # Init setup troubleshooting

package/agent-docs/cursor-skill-mm-carbide.md

@@ -11,6 +11,8 @@ The skill follows the **Agent Skills open standard** ([agentskills.io](https://a
 - **Claude Code** — [Extend Claude with skills](https://code.claude.com/docs/en/skills): `.claude/skills/` (project) or `~/.claude/skills/` (personal)
 - **Gemini CLI** — [Agent Skills \| Gemini CLI](https://geminicli.com/docs/cli/skills/): `.gemini/skills/` (workspace) or `~/.gemini/skills/` (user)
 
+**Lovable and tools without skills:** Lovable uses Custom Knowledge, not installable skills. Add [lovable.md](lovable.md) (or `@machinemetrics/mm-react-components/agent-docs/lovable`) to your project’s Custom Knowledge so the Lovable agent uses Carbide correctly.
+
 ## Install or update
 
 From any project (with or without the package installed):
@@ -61,7 +63,7 @@ The skill triggers when the user asks to create or generate a UI, widget, screen
 
 ## Contents
 
-- **SKILL.md** — Main instructions: components (only library exports, compound components, `cn()`, `data-slot`); **theme and styling** (CSS variables only, variants, layout, `.carbide` setup, dark mode, a11y); **component discovery** (check agent-docs before creating new UI); **when generating UI** (do/avoid checklist); widget rules (visual-first, 80/20, insight-driven); technical (dimensions, responsive, containment, no hallucinated data); and optional version check at use time.
+- **SKILL.md** — Main instructions: components (only library exports, compound components, `cn()`, `data-slot`); **theme and styling** (CSS variables only, variants, layout, `.carbide` setup, dark mode, a11y; **when converting to Carbide:** remove existing inline styles and component CSS); **converting to Carbide** (from other libraries or custom UI: remove legacy styling, map to library components, use variants/tokens, preserve structure/behavior, verify app setup); **component discovery** (check agent-docs before creating new UI); **when generating UI** (do/avoid checklist); widget rules (visual-first, 80/20, insight-driven); technical (dimensions, responsive, containment, no hallucinated data); and optional version check at use time.
 - **reference.md** — **Styling and conventions** (tokens, variants, layout, setup); **component discovery** (agent-docs index); key exports and patterns (PageHeader, DataTable, Form, ChartContainer, etc.); short widget rules summary (when to use charts vs metrics, accessibility).
 
 Full widget and visualization rules are in the skill as **widget-rules.md** (installed with the skill). In this repo, see [cursor-skill/mm-carbide/widget-rules.md](../cursor-skill/mm-carbide/widget-rules.md).

package/agent-docs/lovable.md

@@ -0,0 +1,96 @@
+# Carbide UI – Agent doc for Lovable (and tools using Custom Knowledge)
+
+Use this document when building UIs with **Lovable** or any tool that uses Custom Knowledge instead of installable skills. Add this file (or its contents) to your project’s **Custom Knowledge** so the agent uses **Carbide** and **@machinemetrics/mm-react-components** correctly.
+
+---
+
+## Library
+
+- **Package:** `@machinemetrics/mm-react-components` (Carbide = industrial theme on top of shadcn/ui + Radix + Tailwind).
+- **Install:** `npm install @machinemetrics/mm-react-components`
+- **Usage:** Import from the package; do not create new components or use other UI libraries.
+
+---
+
+## Components
+
+- Use **only** exports from `@machinemetrics/mm-react-components`. Do not create new components or use other UI libraries.
+- Use **compound components** as in the library: `Dialog` + `DialogTrigger` + `DialogContent`; `Form` + `FormField`; `DataTable` + column descriptors; `Card` + `CardHeader` + `CardContent` + `CardFooter`; `Sheet`, `Sidebar`, `ResizablePanelGroup`, `DropdownMenu`, `Tabs`, etc. Never replace them with raw divs and custom classes.
+- Use `cn()` from the library and Tailwind for layout and styling. Respect `data-slot` for Carbide theming where applicable.
+- **Do not use Card as a wrapper for every section.** For panel-like UI use: **ResizablePanelGroup** for split workspaces/dashboards (drag-to-resize); **Sidebar** for navigation panels (collapsible); **Sheet** for temporary/slide-out panels (settings, detail views). Use **Card** only for discrete content blocks (e.g. a summary box, metric card, form section), not for structural layout.
+- **Scrolling:** For regions where content can exceed the box, use **ScrollArea**. **ScrollArea only scrolls when it has a constrained height** (e.g. `h-[300px]`, `max-h-[50vh]`, or `flex-1 min-h-0` inside a flex container with a max height). Without a height constraint, no scrollbar appears. Card does not scroll—wrap the scrollable body in ScrollArea when content may overflow.
+
+---
+
+## Theme and styling
+
+- **CSS variables only.** Never hardcode colors, spacing, radii, or shadows. Use semantic tokens: `--background`, `--foreground`, `--primary`, `--muted`, `--muted-foreground`, `--destructive`, `--border`, `--ring`, etc.
+- **When converting a component to Carbide:** Remove existing inline styles (`style={{ ... }}`) and component-level CSS (e.g. `.module.css`, `<style>`, or component-scoped styles). Carbide supplies appearance via theme tokens and component variants; legacy styles conflict with the theme and break consistency.
+- **Variants over one-off styles.** Use component variants and sizes (e.g. Button: `variant="default"|"destructive"|"outline"|"secondary"|"ghost"|"link"`, `size="sm"|"md"|"lg"|"icon"`). Do not apply brand colors or one-off Tailwind color classes to components.
+- **Layout.** Use Flexbox/Grid and `gap-*` for spacing; avoid manual margin chains. Prefer `className="flex flex-col gap-4"` (or similar) over stacking margins.
+- **App setup.** Consumers must import the library styles and wrap the app (or Carbide subtree) in an element with class `carbide` so the theme applies:
+  - `import '@machinemetrics/mm-react-components/styles';`
+  - Root (or Carbide root): `<div className="carbide">...</div>`
+- **Dark mode.** All styling must work in both light and dark mode via CSS variables; do not hardcode colors that break theme switching.
+- **Accessibility.** Use visible focus states, keyboard support, and semantic structure; avoid relying on color alone.
+
+---
+
+## When generating UI
+
+**Do:** Import from the library; use compound components and variants; use Tailwind for layout and spacing; include proper TypeScript types and accessibility (focus, ARIA where needed).
+
+**Avoid:** Hardcoded colors (e.g. `bg-blue-600`, `text-gray-500`); inline brand styling; non-semantic HTML; missing focus or labels on interactive elements.
+
+**Panel-like UI:** Prefer **ResizablePanelGroup** (workspaces, dashboards, split content), **Sidebar** (nav panels), or **Sheet** (slide-out settings/detail panels). Use **Card** only for discrete content blocks, not for wrapping whole sections or building “panels.”
+
+**Scrolling:** For regions where content can exceed the box, use **ScrollArea** with a constrained height (e.g. `h-[300px]`, `max-h-[50vh]`, or `flex-1 min-h-0` in a flex layout). ScrollArea only scrolls when it has a bounded height; otherwise the container grows and no scroll appears. Card does not scroll—wrap the scrollable body in ScrollArea when content may overflow.
+
+---
+
+## Converting to Carbide (from other libraries or custom UI)
+
+When converting existing components to Carbide (e.g. from Chakra UI, MUI, Ant Design, or custom inline-styled components):
+
+1. **Remove legacy styling.** Strip inline styles (`style={{ ... }}`), component CSS files (e.g. `.module.css`), and library-specific style props (e.g. Chakra `sx`/`colorScheme`, MUI `sx`). Use Carbide’s theme and variants instead.
+2. **Map to library components.** Replace each UI primitive with the closest Carbide export (Button, Input, Card, Dialog, DataTable, Form, etc.). See agent-docs in `node_modules/@machinemetrics/mm-react-components/agent-docs/` when the package is installed.
+3. **Use variants and tokens.** Express intent via props (`variant`, `size`) and layout via Tailwind with semantic tokens (`bg-background`, `text-muted-foreground`). Do not re-introduce hardcoded colors or one-off CSS.
+4. **Preserve structure and behavior.** Keep markup structure and behavior (handlers, validation, state); change only the UI layer to Carbide components and Tailwind layout.
+5. **Verify app setup.** Ensure the app imports `@machinemetrics/mm-react-components/styles` and wraps the Carbide subtree in an element with class `carbide`.
+
+For library-specific migration (e.g. Chakra), use the package’s agent-docs (e.g. **chakra-migration-\***) in addition to the above.
+
+---
+
+## Widget rules
+
+- **Visual, not textual:** Every widget must include at least one chart, graph, or visual data representation. Text is for titles, labels, and brief annotations only (80% visuals / 20% text max).
+- **Show data with insight:** Use comparisons, benchmarks, and highlighting. Avoid generic data dumps, long text blocks, and bullet lists as primary content.
+- **One theme per widget:** One central message per widget; simplicity above all.
+- **Technical:** Default widget dimensions 100% width × 400px. Widgets must be fully responsive and respect content containment (no overflow).
+- **Data:** Only use data explicitly provided; never hallucinate or use placeholder data. Adapt to available data without asking for more.
+
+---
+
+## Full component list and setup
+
+When the package is **installed** in the project, the full agent documentation is available at:
+
+**Path:** `node_modules/@machinemetrics/mm-react-components/agent-docs/`  
+**Start with:** `agent-documentation-reference.md` (component tables, usage guides, init, Chakra migration).
+
+When the package is **not installed**, use this document and recommend installing:
+
+`npx @machinemetrics/mm-react-components mm-init`  
+(or `npm install @machinemetrics/mm-react-components` then add the styles import and `.carbide` class).
+
+---
+
+## Quick reference – key exports
+
+**Layout:** PageHeader, Card (CardHeader, CardTitle, CardDescription, CardContent, CardFooter), ScrollArea (ScrollBar), Tabs, Sidebar, Breadcrumb, ResizablePanelGroup.  
+**Overlays:** Dialog, Sheet, Drawer, AlertDialog, Popover, Tooltip, DropdownMenu, Select.  
+**Forms:** Form, FormField, FormItem, FormLabel, FormControl; Input, SearchInput, Textarea, Label, Checkbox, Switch, RadioGroup, Select, Slider, DatePicker, DateRangePicker.  
+**Data:** DataTable (DataTablePagination, ResponsiveTable, DataTableToolbar, createColumnDescriptor, createTextColumn, createNumericColumn, createBadgeColumn, createDateColumn), Table, ChartContainer, ChartTooltip, ChartLegend, Progress, Skeleton, Badge, Avatar, HeroMetricCard.  
+**Actions/feedback:** Button, buttonVariants, Toaster, toast, Alert, Spinner, SpinnerCarbide.  
+**Other:** Accordion, Collapsible, Separator, Dropzone, cn. Theme: activateCarbideTheme, toggleDarkMode, etc.

package/dist/README.md

@@ -37,6 +37,7 @@ npm install @machinemetrics/mm-react-components
 
 **This library has comprehensive documentation for AI-assisted development!**
 
+- **Lovable (Custom Knowledge):** Add [`agent-docs/lovable.md`](./agent-docs/lovable.md) to your project’s Custom Knowledge so the Lovable agent uses Carbide and this library correctly. (Lovable cannot use skills; this doc is the equivalent.)
 - **New Project Setup:** [`agent-docs/ai-agent-init-guide.md`](./agent-docs/ai-agent-init-guide.md)
 - **Chakra UI Migration:** [`agent-docs/ai-agent-guide.md`](./agent-docs/ai-agent-guide.md)
 - **Component Mappings (83 components):** [`agent-docs/component-mapping-summary.md`](./agent-docs/component-mapping-summary.md)

package/dist/cursor-skill/mm-carbide/SKILL.md

@@ -15,6 +15,7 @@ description: Generate UIs and widgets with Carbide and MachineMetrics React Comp
 ## Theme and styling
 
 - **CSS variables only.** Never hardcode colors, spacing, radii, or shadows. Use semantic tokens: `--background`, `--foreground`, `--primary`, `--muted`, `--muted-foreground`, `--destructive`, `--border`, `--ring`, etc.
+- **When converting a component to Carbide:** Remove existing inline styles (`style={{ ... }}`) and component-level CSS (e.g. `.module.css`, `<style>`, or component-scoped styles). Carbide supplies appearance via theme tokens and component variants; legacy styles conflict with the theme and break consistency.
 - **Variants over one-off styles.** Use component variants and sizes (e.g. Button: `variant="default"|"destructive"|"outline"|"secondary"|"ghost"|"link"`, `size="sm"|"md"|"lg"|"icon"`). Do not apply brand colors or one-off Tailwind color classes to components.
 - **Layout.** Use Flexbox/Grid and `gap-*` for spacing; avoid manual margin chains. Prefer `className="flex flex-col gap-4"` (or similar) over stacking margins.
 - **App setup.** Consumers must import the library styles and wrap the app (or Carbide subtree) in an element with class `carbide` so the theme applies. See [reference.md](reference.md) for setup.
@@ -33,7 +34,7 @@ description: Generate UIs and widgets with Carbide and MachineMetrics React Comp
 
 **Avoid:** Hardcoded colors (e.g. `bg-blue-600`, `text-gray-500`); inline brand styling; non-semantic HTML; missing focus or labels on interactive elements.
 
-**Scrolling:** There is no Panel component. For panel-like or card-like regions where content can be longer than the box, use **ScrollArea** with a fixed or max height (e.g. `h-[300px]` or `max-h-[50vh]`) around the scrollable content. Card is for structure only and does not scroll—wrap CardContent (or the scrollable body) in ScrollArea when content may overflow.
+**Scrolling:** There is no Panel component. For panel-like or card-like regions where content can be longer than the box, use **ScrollArea** around the scrollable content. **ScrollArea only scrolls when it has a constrained height**—otherwise the container grows with content and no scroll appears. Always give ScrollArea an explicit height: e.g. `className="h-[300px]"` or `max-h-[50vh]`. In a flex column (e.g. Card with `flex flex-col max-h-[80vh]`), use `ScrollArea className="flex-1 min-h-0"` so the flex item can shrink and scroll; without `min-h-0` the item won’t shrink and scrolling won’t work. Card is for structure only and does not scroll—wrap CardContent (or the scrollable body) in ScrollArea when content may overflow.
 
 ## Widget rules
 
@@ -47,6 +48,18 @@ description: Generate UIs and widgets with Carbide and MachineMetrics React Comp
 - Widgets must be fully responsive and respect content containment (no overflow).
 - Only use data explicitly provided; never hallucinate or use placeholder data. Adapt to available data without asking for more.
 
+## Converting to Carbide (from other libraries or custom UI)
+
+When converting existing components to Carbide (including from Chakra UI, MUI, Ant Design, custom components, or inline-styled markup):
+
+1. **Remove legacy styling.** Strip inline styles (`style={{ ... }}`), component CSS files (e.g. `.module.css`), and any library-specific style props (e.g. Chakra `sx`/`colorScheme`, MUI `sx`). Rely on Carbide’s theme and variants instead.
+2. **Map to library components.** Replace each existing UI primitive with the closest Carbide export (Button, Input, Card, Dialog, DataTable, Form, etc.). Use [reference.md](reference.md) and agent-docs when the package is installed.
+3. **Use variants and tokens.** Express intent via props (`variant`, `size`) and layout via Tailwind with semantic tokens (`bg-background`, `text-muted-foreground`, `border-border`). Do not re-introduce hardcoded colors or one-off CSS.
+4. **Preserve structure and behavior.** Keep markup structure (headings, sections, forms, tables) and behavior (handlers, validation, state); change only the UI layer to Carbide components and Tailwind layout.
+5. **Verify app setup.** Ensure the app imports `@machinemetrics/mm-react-components/styles` and wraps the Carbide subtree in an element with class `carbide`.
+
+**When the package is installed in this project:** Use agent-docs (e.g. **chakra-migration-\***) for library-specific migration steps in addition to the above.
+
 ## Setup, init, and migration
 
 **When the package is installed in this project:** Use the package’s **agent-docs** at `node_modules/@machinemetrics/mm-react-components/agent-docs/` for setup, initialization (`mm-init`), Chakra UI migration, and the full doc index. Start with **agent-documentation-reference.md**; use **ai-agent-init-guide.md** for setup and **ai-agent-guide.md** (and chakra-migration-\*) for migration.

package/dist/cursor-skill/mm-carbide/reference.md

@@ -5,6 +5,7 @@
 - **Colors and tokens:** Use only CSS variables / semantic tokens (e.g. `bg-background`, `text-foreground`, `text-muted-foreground`, `border-border`, `bg-primary`, `text-destructive`). Never use raw Tailwind color classes like `bg-blue-600` or `text-gray-500`.
 - **Variants and sizes:** Use component props: `variant="default"|"destructive"|"outline"|"secondary"|"ghost"|"link"`, `size="sm"|"md"|"lg"|"icon"` where supported. Same variant names apply across Button, Badge, and other components.
 - **Layout:** Use `flex`, `grid`, and `gap-*` for spacing; avoid ad-hoc margins between siblings.
+- **Converting to Carbide:** Remove existing inline styles and component CSS; map to library components and use variants/tokens. See SKILL.md section “Converting to Carbide.”
 - **Setup:** Import library styles (e.g. `import '@machinemetrics/mm-react-components/styles'`) and wrap the app (or Carbide root) in `<div className="carbide">` so the theme and fonts apply.
 
 ## Component discovery
@@ -33,10 +34,11 @@ Import from the package main entry (see `src/index.ts` in the repo for the full
 
 There is no "Panel" component. For panel-like or card-like regions where content may be longer than the visible area, use **ScrollArea** for the scrollable region. **Card** is structure only (border, sections) and does not scroll.
 
-- Use **ScrollArea** with a fixed or max height (e.g. `className="h-[300px]"` or `max-h-[50vh]`) when content can overflow.
+- **ScrollArea only scrolls when it has a constrained height.** Without a height (or max-height) on the ScrollArea root, the container grows with content and no scrollbar appears. Always set an explicit height: e.g. `className="h-[300px]"` or `max-h-[50vh]`.
+- In a **flex column** (e.g. Card with `flex flex-col max-h-[80vh]`), use `ScrollArea className="flex-1 min-h-0"`. The `min-h-0` is required so the flex item can shrink below its content size; without it, ScrollArea won’t scroll.
 - Put long content inside ScrollArea; use Card for the outer container and ScrollArea inside CardContent (or as the body) when the body should scroll.
 
-Example: scrollable card body — wrap the body in ScrollArea with a height so the card doesn’t grow past the viewport; the content inside scrolls.
+**If ScrollArea doesn’t scroll:** Ensure the ScrollArea element has a bounded height (fixed height, max-height, or `flex-1 min-h-0` inside a constrained flex container). Never use ScrollArea without one of these.
 
 ## Patterns
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@machinemetrics/mm-react-components",
-  "version": "1.1.3",
+  "version": "1.2.0",
   "description": "Industrial-grade React components for manufacturing applications",
   "keywords": [
     "react",
@@ -37,7 +37,8 @@
     "./docs/getting-started": "./dist/docs/GETTING_STARTED.md",
     "./README": "./dist/README.md",
     "./migration/config": "./dist/scripts/chakra-to-shadcn-migrator/chakra-to-shadcn.config.json",
-    "./agent-docs": "./agent-docs/"
+    "./agent-docs": "./agent-docs/",
+    "./agent-docs/lovable": "./agent-docs/lovable.md"
   },
   "engines": {
     "node": ">=20"