@machinemetrics/mm-react-components 1.1.1-2 → 1.1.1-3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/agent-docs/agent-documentation-reference.md +23 -8
- package/agent-docs/ai-agent-guide.md +2 -0
- package/agent-docs/ai-agent-init-guide.md +1 -1
- package/agent-docs/component-mapping-reference.md +3 -1
- package/dist/cursor-skill/mm-carbide/SKILL.md +5 -2
- package/dist/cursor-skill/mm-carbide/reference.md +13 -7
- package/package.json +1 -1
|
@@ -50,14 +50,16 @@ This directory contains comprehensive documentation and tools for AI agents work
|
|
|
50
50
|
|
|
51
51
|
### Layout & Navigation
|
|
52
52
|
|
|
53
|
-
| Component
|
|
54
|
-
|
|
|
55
|
-
| **
|
|
56
|
-
| **
|
|
57
|
-
| **
|
|
58
|
-
| **
|
|
59
|
-
| **
|
|
60
|
-
| **
|
|
53
|
+
| Component | Exports | Description |
|
|
54
|
+
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
|
|
55
|
+
| **ResizablePanelGroup** | `ResizablePanelGroup`, `ResizablePanel`, `ResizableHandle` | Split layouts with drag-to-resize; use for workspaces, dashboards, IDE-like UIs |
|
|
56
|
+
| **Sidebar** | `Sidebar`, `SidebarProvider`, `SidebarInset`, `SidebarHeader`, `SidebarContent`, `SidebarMenu`, `SidebarMenuItem`, `SidebarMenuButton`, `SidebarTrigger`, etc. | Navigation panel; collapsible to icons; use for app nav, not generic content |
|
|
57
|
+
| **Card** | `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter` | Discrete content blocks (summary, form section, metric); **not** for structural layout or panels (no built-in scroll) |
|
|
58
|
+
| **ScrollArea** | `ScrollArea`, `ScrollBar` | Scrollable region when content can overflow a fixed-height box |
|
|
59
|
+
| **Separator** | `Separator` | Visual divider |
|
|
60
|
+
| **Tabs** | `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent` | Tabbed interface |
|
|
61
|
+
| **Breadcrumb** | `Breadcrumb`, `BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbPage`, `BreadcrumbSeparator`, `BreadcrumbEllipsis` | Navigation breadcrumbs |
|
|
62
|
+
| **PageHeader** | `PageHeader` (+ types) | Application page header with actions/tabs |
|
|
61
63
|
|
|
62
64
|
### Overlays & Modals
|
|
63
65
|
|
|
@@ -124,6 +126,19 @@ All components follow shadcn/ui patterns with Carbide theme integration for indu
|
|
|
124
126
|
|
|
125
127
|
## Component Usage Guides
|
|
126
128
|
|
|
129
|
+
### Layout and panel-like UI: don’t use Card for every section
|
|
130
|
+
|
|
131
|
+
Use the right component for the job instead of wrapping everything in Card:
|
|
132
|
+
|
|
133
|
+
| Need | Use | Notes |
|
|
134
|
+
|------|-----|--------|
|
|
135
|
+
| **Split workspace / dashboard / IDE-like layout** | **ResizablePanelGroup** | Horizontal or vertical split; drag-to-resize; keyboard accessible. Best for admin panels, SaaS tools, file-explorer style UIs. On mobile, use CSS to stack panels vertically. |
|
|
136
|
+
| **Navigation panel (app nav, links, structural sidebar)** | **Sidebar** | Composable, themeable, collapsible to icons. Use for application layout with nav links and groups, not for arbitrary “panel” content. |
|
|
137
|
+
| **Temporary or slide-out panel (settings, details, filters)** | **Sheet** | Slides in from any side (left, right, top, bottom). Use for settings, notifications, detail views, form overlays. See Overlays & Modals table. |
|
|
138
|
+
| **Discrete content block (summary box, metric, form section)** | **Card** | Card is for **content** with sections (header, body, footer), not for structural layout. Do not use Card as the main wrapper for full-page sections, side panels, or workspace areas. |
|
|
139
|
+
|
|
140
|
+
**Best practice for full app layout:** Combine Sidebar for navigation and ResizablePanelGroup (or a main content area) for the main workspace. Use Sheet for overlay panels; use Card only for distinct content blocks within a panel or page.
|
|
141
|
+
|
|
127
142
|
### Scrolling content: Card vs ScrollArea
|
|
128
143
|
|
|
129
144
|
**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.
|
|
@@ -184,6 +184,8 @@ The migration configuration is located at `scripts/chakra-to-shadcn-migrator/cha
|
|
|
184
184
|
|
|
185
185
|
### Card Components
|
|
186
186
|
|
|
187
|
+
Use Card for **discrete content blocks** (summary, metric, form section), not for panel or layout structure. For panel-like UI use **ResizablePanelGroup**, **Sidebar**, or **Sheet** (see agent-documentation-reference.md).
|
|
188
|
+
|
|
187
189
|
```tsx
|
|
188
190
|
// Chakra UI
|
|
189
191
|
<Card>
|
|
@@ -129,7 +129,7 @@ function MyComponent() {
|
|
|
129
129
|
}
|
|
130
130
|
```
|
|
131
131
|
|
|
132
|
-
**Done!** Components are ready to use.
|
|
132
|
+
**Done!** Components are ready to use. (This example uses Card for a single content block; for panel layouts or split UIs use ResizablePanelGroup, Sidebar, or Sheet—see agent-documentation-reference.md.)
|
|
133
133
|
|
|
134
134
|
## Project Structure After Setup (zero-config)
|
|
135
135
|
|
|
@@ -82,7 +82,7 @@ This reference provides detailed mappings between Chakra UI components and Machi
|
|
|
82
82
|
| Chakra UI | MachineMetrics | Import | Notes |
|
|
83
83
|
| --------- | -------------- | ------------------------------------- | ------------------ |
|
|
84
84
|
| `Table` | `Table` | `@machinemetrics/mm-react-components` | Direct replacement |
|
|
85
|
-
| `Card` | `Card` | `@machinemetrics/mm-react-components` |
|
|
85
|
+
| `Card` | `Card` | `@machinemetrics/mm-react-components` | Use for discrete content blocks; for panel/split layout use ResizablePanelGroup, Sidebar, or Sheet (see agent-documentation-reference.md). |
|
|
86
86
|
| `Avatar` | `Avatar` | `@machinemetrics/mm-react-components` | New component |
|
|
87
87
|
| `Tooltip` | `Tooltip` | `@machinemetrics/mm-react-components` | Direct replacement |
|
|
88
88
|
| `Popover` | `Popover` | `@machinemetrics/mm-react-components` | Direct replacement |
|
|
@@ -216,6 +216,8 @@ This reference provides detailed mappings between Chakra UI components and Machi
|
|
|
216
216
|
|
|
217
217
|
### Card Structure
|
|
218
218
|
|
|
219
|
+
Use Card for **discrete content blocks** (e.g. summary box, metric card, form section). Do not use Card for structural layout or panel-like UI—prefer **ResizablePanelGroup** (split workspaces), **Sidebar** (nav panels), or **Sheet** (slide-out panels). See agent-documentation-reference.md “Layout and panel-like UI.”
|
|
220
|
+
|
|
219
221
|
```tsx
|
|
220
222
|
// Chakra UI Structure
|
|
221
223
|
<Card>
|
|
@@ -8,7 +8,8 @@ description: Generate UIs and widgets with Carbide and MachineMetrics React Comp
|
|
|
8
8
|
## Components
|
|
9
9
|
|
|
10
10
|
- Use **only** exports from `@machinemetrics/mm-react-components`. Do not create new components or use other UI libraries.
|
|
11
|
-
- Use compound components as in the library: Dialog + DialogTrigger + DialogContent; Form + FormField; DataTable + column descriptors; Card + CardHeader + CardContent + CardFooter; Sheet, DropdownMenu, Tabs, etc. Never replace them with raw divs and custom classes.
|
|
11
|
+
- 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.
|
|
12
|
+
- **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.
|
|
12
13
|
- Use `cn()` from the library and Tailwind for layout and styling. Respect `data-slot` for Carbide theming where applicable.
|
|
13
14
|
- For a component list and patterns, see [reference.md](reference.md). For full widget and visualization rules, see [widget-rules.md](widget-rules.md).
|
|
14
15
|
|
|
@@ -33,7 +34,9 @@ description: Generate UIs and widgets with Carbide and MachineMetrics React Comp
|
|
|
33
34
|
|
|
34
35
|
**Avoid:** Hardcoded colors (e.g. `bg-blue-600`, `text-gray-500`); inline brand styling; non-semantic HTML; missing focus or labels on interactive elements.
|
|
35
36
|
|
|
36
|
-
**
|
|
37
|
+
**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.”
|
|
38
|
+
|
|
39
|
+
**Scrolling:** For regions where content can exceed the box, use **ScrollArea** with a fixed or max height. Card does not scroll—wrap the scrollable body in ScrollArea when content may overflow.
|
|
37
40
|
|
|
38
41
|
## Widget rules
|
|
39
42
|
|
|
@@ -17,7 +17,7 @@
|
|
|
17
17
|
|
|
18
18
|
Import from the package main entry (see `src/index.ts` in the repo for the full list).
|
|
19
19
|
|
|
20
|
-
**Layout and structure**: PageHeader, Card (CardHeader, CardTitle,
|
|
20
|
+
**Layout and structure**: PageHeader, ResizablePanelGroup (ResizablePanel, ResizableHandle), Sidebar (SidebarProvider, SidebarInset, SidebarMenu, SidebarMenuButton, SidebarTrigger, etc.), Card (CardHeader, CardTitle, CardContent, CardFooter), ScrollArea (ScrollBar), Tabs (TabsList, TabsTrigger, TabsContent), Breadcrumb, Field (FieldLabel, FieldDescription, FieldError, FieldGroup, etc.), Item (ItemMedia, ItemContent, ItemActions, etc.).
|
|
21
21
|
|
|
22
22
|
**Overlays and dialogs**: Dialog (DialogTrigger, DialogContent, DialogHeader, DialogFooter, etc.), Sheet, Drawer, AlertDialog, Popover, Tooltip (TooltipTrigger, TooltipContent, TooltipProvider), DropdownMenu, HoverCard, ContextMenu.
|
|
23
23
|
|
|
@@ -27,16 +27,22 @@ Import from the package main entry (see `src/index.ts` in the repo for the full
|
|
|
27
27
|
|
|
28
28
|
**Feedback and actions**: Button, buttonVariants, ButtonGroup; Toaster, toast; Alert, AlertTitle, AlertDescription; Spinner, SpinnerCarbide; Pagination, SimplePagination; Empty (EmptyHeader, EmptyTitle, EmptyDescription, etc.).
|
|
29
29
|
|
|
30
|
-
**Other**: Accordion, Collapsible, Separator, Dropzone,
|
|
30
|
+
**Other**: Accordion, Collapsible, Separator, Dropzone, Carousel, Command, CodePreview, Kbd, cn (utility). Theme: activateCarbideTheme, toggleCarbideTheme, isCarbideThemeActive, etc.
|
|
31
31
|
|
|
32
|
-
##
|
|
32
|
+
## Panel-like UI (don’t use Card for every section)
|
|
33
|
+
|
|
34
|
+
| Need | Use |
|
|
35
|
+
|------|-----|
|
|
36
|
+
| Split workspace, dashboard, IDE-like layout | **ResizablePanelGroup** (drag-to-resize; stack vertically on mobile) |
|
|
37
|
+
| Navigation panel (app nav, links, sidebar) | **Sidebar** (collapsible to icons) |
|
|
38
|
+
| Temporary/slide-out panel (settings, details, filters) | **Sheet** (slides from any side) |
|
|
39
|
+
| Discrete content block (summary, metric, form section) | **Card** |
|
|
33
40
|
|
|
34
|
-
|
|
41
|
+
Use Card only for content blocks. For full app layout: Sidebar + ResizablePanelGroup (or main content area); Sheet for overlay panels.
|
|
35
42
|
|
|
36
|
-
|
|
37
|
-
- Put long content inside ScrollArea; use Card for the outer container and ScrollArea inside CardContent (or as the body) when the body should scroll.
|
|
43
|
+
## Scrolling: Card vs ScrollArea
|
|
38
44
|
|
|
39
|
-
|
|
45
|
+
There is no "Panel" component. For content longer than the visible area, use **ScrollArea** with a fixed or max height. Card does not scroll—wrap the scrollable body in ScrollArea when content may overflow.
|
|
40
46
|
|
|
41
47
|
## Patterns
|
|
42
48
|
|