@machinemetrics/mm-react-components 1.5.0-0 → 1.5.0

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

@@ -1,71 +0,0 @@
-# mm-carbide reference
-
-## Styling and conventions
-
-- **Authoritative tokens:** **`@machinemetrics/mm-react-components/themes/carbide`** (`carbide.css`) — search for `--` variables and `.carbide` rules. **`agent-docs/style-color-reference.md`** is an overview only. Precompiled `/styles` is scoped to this library’s build; use **`var(--token)`** from `carbide.css` when needed.
-- **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`. For palette stops, use arbitrary values: `bg-[var(--grey-500)]`, etc.
-- **Variants and sizes:** Use component props: `variant="default"|"destructive"|"outline"|"secondary"|"ghost"|"link"`, `size="sm"|"md"|"lg"|"icon"` where supported (Button and similar). **Badge** also supports semantic status variants: `neutral`, `info`, `success`, `critical`, `warning`, `attention`, `production`, `setup`, `custom` — see **agent-documentation-reference.md** (_Badge variants_).
-- **Layout:** In apps with Tailwind, use `flex`, `grid`, and `gap-*` for spacing; avoid ad-hoc margins between siblings. For **copy-paste examples** that must run with **only** `/styles` + `.carbide`, avoid utility `className` on snippet nodes; use component props (`Card variant="sectioned"`, `tone="muted"`, `Accordion variant="inset"`, `CollapsibleContent spacing="comfortable"`, etc.) or `style` with `var(--…)`.
-- **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
-
-**When the package is installed in this project:** Check **agent-docs** at `node_modules/@machinemetrics/mm-react-components/agent-docs/`; use **agent-documentation-reference.md** as the index for existing components and patterns.
-
-**When the package is not installed in this workspace:** agent-docs is not present. Use this reference and [widget-rules.md](widget-rules.md); recommend installing the package in the project (`mm-init` or `npm install @machinemetrics/mm-react-components`) for the full doc set.
-
-## Key exports (from @machinemetrics/mm-react-components)
-
-Import from the package main entry (see `src/index.ts` in the repo for the full list).
-
-**Layout and structure**: PageHeader, ResizablePanelGroup (ResizablePanel, ResizableHandle), Sidebar (SidebarProvider, SidebarInset, SidebarMenu, SidebarMenuButton, SidebarTrigger, etc.), Card (CardHeader, CardTitle, CardDescription, CardContent, CardFooter, CardAction; `variant="sectioned"`, section `tone="muted"`), **ScrollArea** (ScrollBar), Tabs (TabsList, TabsTrigger, TabsContent), Breadcrumb, Field (FieldLabel, FieldDescription, FieldError, FieldGroup, etc.), Item (ItemMedia, ItemContent, ItemActions, etc.).
-
-**Overlays and dialogs**: Dialog (DialogTrigger, DialogContent, DialogHeader, DialogFooter, etc.), Sheet, Drawer, AlertDialog, Popover, Tooltip (TooltipTrigger, TooltipContent, TooltipProvider), DropdownMenu, HoverCard, ContextMenu.
-
-**Forms**: Form, FormField, FormItem, FormLabel, FormControl, FormDescription, FormMessage; Input, SearchInput, Textarea, Label, Checkbox, Switch, RadioGroup/RadioGroupItem, Select, Slider, NativeSelect, Combobox, InputOTP, InputGroup, DatePicker, DateRangePicker, Calendar.
-
-**Data display**: DataTable, DataTablePagination, ResponsiveTable, DataTableToolbar, createColumnDescriptor, createTextColumn, createNumericColumn, createBadgeColumn, createDateColumn, etc.; Table (TableHeader, TableBody, TableRow, TableCell, etc.); ChartContainer, ChartTooltip, ChartLegend, ChartStyle; Progress, Skeleton, Badge, Avatar, HeroMetricCard.
-
-**Feedback and actions**: Button, buttonVariants, ButtonGroup; Toaster, toast; Alert, AlertTitle, AlertDescription; Spinner, SpinnerCarbide; Pagination, SimplePagination; Empty (EmptyHeader, EmptyTitle, EmptyDescription, etc.).
-
-**Other**: Accordion (`variant="default"|"inset"`), Collapsible (`CollapsibleContent` `spacing`), Separator, Dropzone, Carousel, Command, CodePreview, Kbd, cn (utility). Theme: activateCarbideTheme, toggleCarbideTheme, isCarbideThemeActive, etc.
-
-## Panel-like UI (don’t use Card for every section)
-
-| Need | Use |
-|------|-----|
-| Split workspace, dashboard, IDE-like layout | **ResizablePanelGroup** (drag-to-resize; stack vertically on mobile) |
-| Navigation panel (app nav, links, sidebar) | **Sidebar** (collapsible to icons) |
-| Temporary/slide-out panel (settings, details, filters) | **Sheet** (slides from any side) |
-| Discrete content block (summary, metric, form section) | **Card** |
-
-Use Card only for content blocks. For full app layout: Sidebar + ResizablePanelGroup (or main content area); Sheet for overlay panels.
-
-## Scrolling: Card vs ScrollArea
-
-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.
-
-- **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.
-
-**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
-
-- **DateRangePicker**: For **date ranges** (filters, reports). State: `value` / `onValueChange` with tuple `[string \| null, string \| null]` (**`yyyy-MM-dd`**). **`variant="full"`** = presets sidebar + dual-month calendar + company/custom hours. Customize presets with **`presetIds`** (use **`PRESET_IDS`** constants) and **`presetLabels`**. Programmatic matching: **`resolvePresets`**, **`findMatchingPreset`**, **`DATE_RANGE_PRESETS`**. Single date → **`DatePicker`**; bare calendar → **`Calendar`**. Full details: `agent-docs/agent-documentation-reference.md` (DateRangePicker section) and `src/components/ui/date-range-picker/README.md`.
-- **PageHeader**: Use for page titles with optional actions, tabs, and breadcrumbs (ActionConfig, TabConfig, MenuItemConfig).
-- **DataTable**: Use createColumnDescriptor / createTextColumn / createNumericColumn / createBadgeColumn / createDateColumn and column registry; use useDataTableState, DataTableToolbar, DataTablePagination.
-- **Form**: Use Form + FormField with react-hook-form; FormItem, FormLabel, FormControl, FormDescription, FormMessage.
-- **Charts**: Use ChartContainer, ChartTooltip, ChartLegend, ChartStyle with recharts; see chart component for config.
-
-## Widget rules summary
-
-- **When to use**: Charts/graphs for trends, comparisons, distributions (with insight annotations). Icons/indicators for status, categories, severity. Metrics/numbers for single KPIs with context (vs target, trend). Text only for labels, brief context, annotations.
-- **Insight-driven**: Add comparisons (vs average, vs goal), highlight what matters (color, sizing), show direction/trend (arrows, sparklines), explain significance.
-- **Avoid**: Text-only widgets, generic charts without context, equal visual weight for all data, missing comparison or context.
-- **Chart limits**: Max 4 lines per line chart, max 4 bars per cluster, max 5 sectors in pie; use small multiples or focus charts if more needed.
-- **Accessibility**: WCAG contrast (4.5:1 text, 3:1 graphics); never rely on color alone—use patterns, shapes, or labels; direct labels on data when possible.
-
-For full widget and visualization rules, see [widget-rules.md](widget-rules.md).

package/dist/lib/normalize-host-color-mode.d.ts

@@ -1,6 +0,0 @@
-/**
- * Maps host-reported color mode to next-themes names. Unknown values default to light.
- * @internal Used by useHostTheme; not part of the public package API.
- */
-export declare function normalizeHostColorMode(colorMode: string | undefined): 'dark' | 'light';
-//# sourceMappingURL=normalize-host-color-mode.d.ts.map

package/dist/lib/normalize-host-color-mode.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"normalize-host-color-mode.d.ts","sourceRoot":"","sources":["../../src/lib/normalize-host-color-mode.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,GAAG,SAAS,GAC5B,MAAM,GAAG,OAAO,CAMlB"}

package/dist/lib/theme-root.d.ts

@@ -1,18 +0,0 @@
-import { type ThemeProviderProps } from 'next-themes';
-export type ThemeRootProps = ThemeProviderProps;
-/**
- * Wrap your app tree once (inside `#root`, not on `<html>`). Applies Carbide-friendly
- * defaults: class on `document.documentElement`, light default, no system theme, no
- * localStorage (host-driven apps). Pass standard `ThemeProvider` props to override.
- *
- * @example
- * ```tsx
- * import { ThemeRoot } from '@machinemetrics/mm-react-components';
- *
- * <ThemeRoot>
- *   <App />
- * </ThemeRoot>
- * ```
- */
-export declare function ThemeRoot({ children, ...rest }: Readonly<ThemeRootProps>): import("react/jsx-runtime").JSX.Element;
-//# sourceMappingURL=theme-root.d.ts.map

package/dist/lib/theme-root.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"theme-root.d.ts","sourceRoot":"","sources":["../../src/lib/theme-root.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAErE,MAAM,MAAM,cAAc,GAAG,kBAAkB,CAAC;AAEhD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,EAAE,QAAQ,CAAC,cAAc,CAAC,2CAcxE"}

package/dist/lib/use-host-theme.d.ts

@@ -1,15 +0,0 @@
-/**
- * Syncs light/dark on `document.documentElement` with a host-provided value (e.g.
- * `useMMAppParams().colorMode`). Call once near the top of your root `App` inside
- * {@link ThemeRoot}. Trims and lowercases host values; unknown values become light.
- *
- * @example
- * ```tsx
- * import { useHostTheme } from '@machinemetrics/mm-react-components';
- * import { useMMAppParams } from '@machinemetrics/mm-react-tools';
- *
- * useHostTheme(useMMAppParams().colorMode);
- * ```
- */
-export declare function useHostTheme(colorMode: string | undefined): void;
-//# sourceMappingURL=use-host-theme.d.ts.map

package/dist/lib/use-host-theme.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"use-host-theme.d.ts","sourceRoot":"","sources":["../../src/lib/use-host-theme.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAsBhE"}

package/dist/lib/with-display-name.d.ts

@@ -1,2 +0,0 @@
-export declare function withDisplayName<T>(component: T, name: string): T;
-//# sourceMappingURL=with-display-name.d.ts.map

package/dist/lib/with-display-name.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"with-display-name.d.ts","sourceRoot":"","sources":["../../src/lib/with-display-name.ts"],"names":[],"mappings":"AAAA,wBAAgB,eAAe,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAWhE"}

package/dist/preview/KanbanPreview.d.ts

@@ -1,2 +0,0 @@
-export default function KanbanPreview(): import("react/jsx-runtime").JSX.Element;
-//# sourceMappingURL=KanbanPreview.d.ts.map

package/dist/preview/KanbanPreview.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"KanbanPreview.d.ts","sourceRoot":"","sources":["../../src/preview/KanbanPreview.tsx"],"names":[],"mappings":"AAuEA,MAAM,CAAC,OAAO,UAAU,aAAa,4CAsDpC"}

package/dist/preview/StatusPreview.d.ts

@@ -1,2 +0,0 @@
-export default function StatusPreview(): import("react/jsx-runtime").JSX.Element;
-//# sourceMappingURL=StatusPreview.d.ts.map

package/dist/preview/StatusPreview.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"StatusPreview.d.ts","sourceRoot":"","sources":["../../src/preview/StatusPreview.tsx"],"names":[],"mappings":"AAeA,MAAM,CAAC,OAAO,UAAU,aAAa,4CA+DpC"}

package/dist/preview/TicketsPreview.d.ts

@@ -1,2 +0,0 @@
-export default function TicketsPreview(): import("react/jsx-runtime").JSX.Element;
-//# sourceMappingURL=TicketsPreview.d.ts.map

package/dist/preview/TicketsPreview.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"TicketsPreview.d.ts","sourceRoot":"","sources":["../../src/preview/TicketsPreview.tsx"],"names":[],"mappings":"AAmSA,MAAM,CAAC,OAAO,UAAU,cAAc,4CAmErC"}