@j3m-quantum/ui 1.12.1 → 2.1.1

package/README.md

@@ -32,6 +32,16 @@ npm install @j3m-quantum/ui tw-animate-css
 
 That's it! All dependencies (Radix UI, lucide-react, etc.) are bundled with the package.
 
+### Set Up AI Assistance (Recommended)
+
+If you use Cursor or AI coding assistants, run this to ensure AI uses the correct components:
+
+```bash
+npx @j3m-quantum/ui init
+```
+
+This creates cursor rules so AI assistants know about all components and use them correctly instead of creating new files.
+
 ## Quick Start
 
 ### 1. Setup Vite + Tailwind
@@ -63,9 +73,14 @@ export default defineConfig({
 @import "tailwindcss";
 @import "tw-animate-css";              /* Required for animations */
 @import "@j3m-quantum/ui/styles";      /* J3M theme and tokens */
+
+/* REQUIRED: Tell Tailwind v4 to scan package for utility classes */
+@source "../node_modules/@j3m-quantum/ui/dist/**/*.js";
 ```
 
-**Order matters!** Import `tw-animate-css` before `@j3m-quantum/ui/styles` to ensure animations work correctly on Dialog, Sheet, Select, Popover, and other overlay components.
+**Critical notes:**
+- **Order matters!** Import `tw-animate-css` before `@j3m-quantum/ui/styles`
+- **The `@source` directive is required!** Without it, Tailwind v4 won't scan the package and components will be completely unstyled
 
 ### 4. Use Components
 
@@ -527,16 +542,71 @@ Make sure to add `glass-context` class to Cards containing interactive component
 </Card>
 ```
 
-## Cursor Rules (AI Assistant)
+## CLI Commands
+
+The package includes a CLI to help with setup and discovery.
+
+### Initialize AI Assistance (Recommended)
+
+Run this after installing to set up Cursor/AI assistant rules:
+
+```bash
+npx @j3m-quantum/ui init
+```
+
+This creates `.cursor/rules/j3m-quantum.md` with:
+- Complete component list with import statements
+- Figma layer name → component mappings
+- Usage guidelines and patterns
+- Instructions for AI to use package components (not create new ones)
+
+### List Available Components
+
+```bash
+npx @j3m-quantum/ui list
+
+# Filter by category
+npx @j3m-quantum/ui list --category blocks
+npx @j3m-quantum/ui list --category inputs
+```
+
+### Check Setup
+
+Validate your project configuration:
+
+```bash
+npx @j3m-quantum/ui doctor
+```
+
+This checks:
+- Package installation
+- CSS import order
+- Cursor rules configuration
+- Required dependencies
+
+## AI Assistant Integration
+
+If your team uses Cursor, Copilot, or other AI coding assistants:
+
+1. **Run `npx @j3m-quantum/ui init`** - This is the most important step
+2. The AI will now:
+   - Use components from `@j3m-quantum/ui` instead of creating new files
+   - Know all 60+ available components
+   - Map Figma layer names to correct components
+   - Follow J3M styling guidelines
+
+### Figma MCP Integration
 
-If your team uses Cursor or AI coding assistants, we provide ready-to-use rules to ensure consistent usage of the design system.
+The cursor rules include a Figma layer → component mapping table. When your Figma MCP suggests a design element, the AI will automatically use the correct package component:
 
-See [`cursor-rules-for-consumers.md`](./cursor-rules-for-consumers.md) for:
-- Rules to copy into your project's `.cursor/rules` file
-- Quick setup guide for new projects
-- Complete component list
+| Figma Layer | Package Component |
+|-------------|------------------|
+| "Button", "CTA" | `Button` |
+| "Card", "Panel" | `Card` |
+| "Planning Grid" | `PlanningTable` |
+| "Dialog", "Modal" | `Dialog` |
 
-This helps AI assistants understand how to use @j3m-quantum/ui correctly and avoid common mistakes.
+See [`cursor-rules-for-consumers.md`](./cursor-rules-for-consumers.md) for the complete mapping.
 
 ## Version Strategy
 

package/cursor-rules-for-consumers.md

@@ -2,6 +2,8 @@
 
 Copy the rules below to `.cursor/rules` or `.cursorrules` in your project to help AI assistants use the J3M Design System correctly.
 
+**Recommended:** Run `npx @j3m-quantum/ui init` to automatically set up these rules.
+
 ---
 
 ## Rules to Copy
@@ -15,16 +17,127 @@ Copy the rules below to `.cursor/rules` or `.cursorrules` in your project to hel
 - Do NOT use shadcn CLI to add components - everything is already bundled
 - Do NOT create local component copies - use the package exports
 
+## CRITICAL: Pre-built Blocks - USE THESE FIRST!
+
+Before implementing ANY sidebar, navigation, header, or dashboard layout, ALWAYS import these pre-built blocks:
+
+```tsx
+// Pre-built blocks - USE THESE, don't build from scratch!
+import {
+  SiteHeader,      // Header with breadcrumbs + search + sidebar trigger
+  NavMain,         // Main navigation with icons + collapsible sub-items
+  NavSecondary,    // Secondary nav (Support, Feedback links)
+  NavUser,         // User profile with dropdown menu
+  NavProjects,     // Project list navigation
+  SearchForm,      // Search input for sidebar
+} from '@j3m-quantum/ui'
+```
+
+## ⛔ NEVER Create These Manually
+
+| Instead of building... | Use this block |
+|------------------------|----------------|
+| ❌ Custom sidebar navigation | ✅ `NavMain` |
+| ❌ Custom user menu/profile | ✅ `NavUser` |
+| ❌ Custom page header | ✅ `SiteHeader` |
+| ❌ Custom project list | ✅ `NavProjects` |
+| ❌ Custom secondary links | ✅ `NavSecondary` |
+| ❌ Custom search in sidebar | ✅ `SearchForm` |
+| ❌ Custom CSS tokens | ✅ Package provides all tokens |
+
+## Block Props Reference
+
+### NavMain
+```tsx
+import { NavMain, type NavItem } from '@j3m-quantum/ui'
+import { Home, Settings, Users } from 'lucide-react'
+
+const navItems: NavItem[] = [
+  { title: "Home", url: "/", icon: Home, isActive: true },
+  { title: "Settings", url: "/settings", icon: Settings, items: [
+    { title: "General", url: "/settings/general" },
+    { title: "Team", url: "/settings/team" },
+  ]},
+  { title: "Users", url: "/users", icon: Users },
+]
+
+<NavMain items={navItems} label="Navigation" />
+```
+
+### NavUser
+```tsx
+import { NavUser } from '@j3m-quantum/ui'
+
+<NavUser 
+  user={{ 
+    name: "John Doe", 
+    email: "john@example.com", 
+    avatar: "/avatar.jpg"  // or "" for initials fallback
+  }} 
+/>
+```
+
+### SiteHeader
+```tsx
+import { SiteHeader, SidebarTrigger } from '@j3m-quantum/ui'
+
+<SiteHeader 
+  trigger={<SidebarTrigger />}
+  breadcrumbs={[
+    { label: "Dashboard", href: "/" },
+    { label: "Settings" }  // No href = current page
+  ]}
+  showSearch={true}
+/>
+```
+
+### NavSecondary
+```tsx
+import { NavSecondary } from '@j3m-quantum/ui'
+import { LifeBuoy, Send } from 'lucide-react'
+
+<NavSecondary items={[
+  { title: "Support", url: "/support", icon: LifeBuoy },
+  { title: "Feedback", url: "/feedback", icon: Send },
+]} />
+```
+
+## Sidebar Features Checklist
+
+| Feature | Usage |
+|---------|-------|
+| `collapsible="icon"` | Collapses sidebar to icons only |
+| `collapsible="offcanvas"` | Slides sidebar off screen |
+| `<SidebarRail />` | Edge rail for drag-to-toggle |
+| `tooltip` prop on SidebarMenuButton | Shows tooltips when collapsed |
+| `<SidebarMenuBadge>` | Notification counts on menu items |
+| `<SidebarGroup>` + `<SidebarGroupLabel>` | Organize sections |
+
+```tsx
+<Sidebar collapsible="icon">
+  <SidebarContent>
+    <SidebarGroup>
+      <SidebarGroupLabel>Platform</SidebarGroupLabel>
+      <NavMain items={navItems} />
+    </SidebarGroup>
+  </SidebarContent>
+  <SidebarRail />
+</Sidebar>
+```
+
 ## CSS Import Order (Critical)
-The order in src/index.css must be:
 ```css
 @import "tailwindcss";
 @import "tw-animate-css";           /* Required for animations */
 @import "@j3m-quantum/ui/styles";   /* J3M theme and tokens */
+
+/* REQUIRED: Tell Tailwind v4 to scan package for utility classes */
+@source "../node_modules/@j3m-quantum/ui/dist/**/*.js";
 ```
 
+**The @source directive is CRITICAL!** Without it, Tailwind v4 won't generate CSS for the component utility classes and all components will be unstyled.
+
 ## Theme Modes (4 Modes)
-The design system supports four theme modes:
 
 | Mode | Classes | Description |
 |------|---------|-------------|
@@ -33,85 +146,108 @@ The design system supports four theme modes:
 | Light Glass | `theme-glass` | Frosted glass on image/gradient |
 | Dark Glass | `dark theme-glass` | Dark frosted glass on image |
 
-### Setting Up Theme
 ```tsx
-// Root element with theme classes and background utility
 <div className="j3m-app-bg">                    {/* Light solid */}
 <div className="dark j3m-app-bg">               {/* Dark solid */}
 <div className="theme-glass j3m-app-bg">        {/* Light glass */}
 <div className="dark theme-glass j3m-app-bg">   {/* Dark glass */}
 ```
 
-### Background Images (Glass Mode)
-Set a custom background image with CSS variable:
-```css
-:root {
-  --j3m-bg-image: url('/your-background.jpg');
-}
-```
-
 ## Glass Context (Important!)
 In glass mode, cards containing interactive components need the `glass-context` class:
 
 ```tsx
-// Correct - interactive components styled properly
 <Card className="glass-context">
   <CardContent>
     <Input placeholder="Name" />
-    <Select>...</Select>
     <Button>Submit</Button>
   </CardContent>
 </Card>
-
-// Also works - variant="glass" includes glass-context
-<Card variant="glass">
-  <CardContent>...</CardContent>
-</Card>
 ```
 
-Without `glass-context`, inputs/buttons inside cards may have incorrect colors in glass mode.
-
-## Portal vs In-App Components
-- **Portal components** (Dialog, Sheet, Drawer, Popover, Select dropdown, Command palette): 
-  Automatically styled correctly for the current theme mode. No extra classes needed.
-  
-- **In-app components** (cards with forms, interactive content):
-  Add `glass-context` class to the parent Card when in glass mode.
-
-## J3M Design Tokens
-- Primary: #F58446 (orange) - use `bg-primary`, `text-primary`
-- Destructive: #FB3748 (red) - use `bg-destructive`
-- Background: adapts to theme mode - use `bg-background`
-- Foreground: adapts to theme mode - use `text-foreground`
-- Muted: subtle backgrounds - use `bg-muted`, `text-muted-foreground`
-- Radius: Components use pill shape (rounded-full) for buttons/inputs
-
 ## DO
 - Import all components from @j3m-quantum/ui
+- Use pre-built blocks (NavMain, NavUser, SiteHeader) instead of building custom
 - Use Tailwind semantic classes: bg-primary, text-muted-foreground, bg-accent
-- Use CSS variables for custom styling: var(--primary), var(--background)
 - Use `glass-context` class on Cards with interactive components in glass mode
-- Check the component catalogue before building custom components
-- Use the j3m-app-bg class on root element for proper backgrounds
+- Check the component/block list BEFORE building anything custom
 
 ## DON'T
+- Don't create new component files for UI that exists in @j3m-quantum/ui
+- Don't build custom sidebar/navigation - use NavMain, NavUser, etc.
 - Don't use shadcn CLI - components are already bundled
-- Don't override component CSS unless approved by design system maintainer
+- Don't add custom CSS tokens - the package provides everything
 - Don't use arbitrary color values like bg-[#F58446] - use bg-primary
-- Don't recreate existing components - use what's in @j3m-quantum/ui
-- Don't modify component border-radius - pill shapes are intentional
-- Don't style portal components manually - they auto-adapt to theme
+
+## Complete Dashboard Example
+
+```tsx
+import { 
+  SidebarProvider, Sidebar, SidebarContent, SidebarFooter, SidebarInset, SidebarRail,
+  SiteHeader, SidebarTrigger, NavMain, NavUser, NavSecondary, type NavItem
+} from '@j3m-quantum/ui'
+import { Home, Settings, LifeBuoy, Send } from 'lucide-react'
+
+const navItems: NavItem[] = [
+  { title: "Home", url: "/", icon: Home, isActive: true },
+  { title: "Settings", url: "/settings", icon: Settings },
+]
+
+function App() {
+  return (
+    <div className="j3m-app-bg min-h-screen">
+      <SidebarProvider>
+        <Sidebar collapsible="icon">
+          <SidebarContent>
+            <NavMain items={navItems} />
+          </SidebarContent>
+          <SidebarFooter>
+            <NavSecondary items={[
+              { title: "Support", url: "#", icon: LifeBuoy },
+              { title: "Feedback", url: "#", icon: Send },
+            ]} />
+            <NavUser user={{ name: "John Doe", email: "john@example.com", avatar: "" }} />
+          </SidebarFooter>
+          <SidebarRail />
+        </Sidebar>
+        <SidebarInset>
+          <SiteHeader 
+            trigger={<SidebarTrigger />} 
+            breadcrumbs={[{ label: "Dashboard" }]} 
+          />
+          <main className="p-4">
+            {/* Your content here */}
+          </main>
+        </SidebarInset>
+      </SidebarProvider>
+    </div>
+  )
+}
+```
+
+## Recommended Prompts for AI
+
+**Good prompts:**
+- "Create a dashboard using @j3m-quantum/ui blocks: NavMain, NavUser, SiteHeader"
+- "Use only pre-built blocks from @j3m-quantum/ui, don't create custom components"
+- "Import SiteHeader for the header and NavMain for navigation from @j3m-quantum/ui"
+- "Check the j3m-quantum cursor rules before implementing"
+
+**Bad prompts (avoid these):**
+- "Create a sidebar" → AI might build from scratch
+- "Add navigation" → Too vague, specify NavMain
+- "Make a header" → Specify SiteHeader instead
 
 ## Available Components (60+)
 
 ### Inputs
-Button, ButtonGroup, Input, InputGroup, Textarea, Checkbox, RadioGroup, Switch, Slider, Select, NativeSelect, Toggle, ToggleGroup, Form, Field, Label, CopyButton
+Button, ButtonGroup, Input, InputGroup, Textarea, Checkbox, RadioGroup, Switch, Slider, Select, NativeSelect, Toggle, ToggleGroup, ThemeSwitch, Form, Field, Label
 
 ### Display
 Card, Table, Badge, Avatar, UserAvatarsDropdown, Separator, Skeleton, Accordion, Tabs, Calendar, EventCalendar, Carousel, Chart, AspectRatio, Empty, Item, Kbd
 
 ### Feedback
-Alert, AlertDialog, Progress, Tooltip, Sonner (Toast), Spinner
+Alert, AlertDialog, Progress, CircularProgress, Tooltip, Sonner (Toast), Spinner
 
 ### Navigation
 Breadcrumb, Pagination, Command, SearchTrigger, DropdownMenu, Menubar, NavigationMenu, ContextMenu
@@ -123,69 +259,10 @@ Dialog, Drawer, Sheet, Popover, HoverCard
 ScrollArea, Collapsible, Resizable, Sidebar, SidebarProvider, SidebarInset, Section
 
 ### Blocks (Pre-built compositions)
-SiteHeader, NavMain, NavProjects, NavSecondary, NavUser, SearchForm
-
-### Utilities
-ThemeSwitch, ToolbarCanvas, PlayerCanvas
-
-## Common Patterns
+SiteHeader, NavMain, NavProjects, NavSecondary, NavUser, SearchForm, PlanningTable, CalibrationTable, SupplierWeeklyLoading, Gantt, Kanban
 
-### Form in Card (Glass Mode)
-```tsx
-<Card className="glass-context">
-  <CardHeader>
-    <CardTitle>Contact Form</CardTitle>
-  </CardHeader>
-  <CardContent className="space-y-4">
-    <Input placeholder="Name" />
-    <Input placeholder="Email" />
-    <Textarea placeholder="Message" />
-    <Button>Send</Button>
-  </CardContent>
-</Card>
-```
-
-### Dashboard Layout
-```tsx
-<SidebarProvider>
-  <Sidebar>
-    <SidebarContent>
-      <NavMain items={navItems} />
-    </SidebarContent>
-    <SidebarFooter>
-      <NavUser user={userData} />
-    </SidebarFooter>
-  </Sidebar>
-  <SidebarInset>
-    <SiteHeader breadcrumbs={[{ label: "Dashboard" }]} />
-    <main className="p-4">
-      {/* Content */}
-    </main>
-  </SidebarInset>
-</SidebarProvider>
-```
-
-### Dialog with Form
-```tsx
-<Dialog>
-  <DialogTrigger asChild>
-    <Button>Open Form</Button>
-  </DialogTrigger>
-  <DialogContent>
-    <DialogHeader>
-      <DialogTitle>Edit Profile</DialogTitle>
-    </DialogHeader>
-    {/* No glass-context needed - Dialog is a portal */}
-    <Input placeholder="Name" />
-    <Button>Save</Button>
-  </DialogContent>
-</Dialog>
-```
-
-## Requesting Changes
-Need a new component or styling change? Don't build it locally.
-Contact the design system maintainer to request additions or modifications.
-This ensures consistency across all J3M applications.
+### Map
+Map, MapTileLayer, MapMarker, MapPopup, MapTooltip, MapZoomControl
 ```
 
 ---
@@ -205,7 +282,14 @@ npm add -D tailwindcss @tailwindcss/vite
 npm install @j3m-quantum/ui tw-animate-css
 ```
 
-### 3. Configure Vite
+### 3. Set Up AI Assistance (Important!)
+```bash
+npx @j3m-quantum/ui init
+```
+
+This automatically creates the cursor rules so AI assistants use the correct components.
+
+### 4. Configure Vite
 ```typescript
 // vite.config.ts
 import { defineConfig } from 'vite'
@@ -217,7 +301,7 @@ export default defineConfig({
 })
 ```
 
-### 4. Setup CSS
+### 5. Setup CSS
 ```css
 /* src/index.css */
 @import "tailwindcss";
@@ -225,19 +309,9 @@ export default defineConfig({
 @import "@j3m-quantum/ui/styles";
 ```
 
-### 5. Add Cursor Rules
-Create `.cursor/rules` or `.cursorrules` in your project root and paste the rules from above.
-
-### 6. Setup App Root
-```tsx
-// src/App.tsx
-function App() {
-  return (
-    <div className="j3m-app-bg min-h-screen">
-      {/* Your app content */}
-    </div>
-  )
-}
+### 6. Verify Setup
+```bash
+npx @j3m-quantum/ui doctor
 ```
 
 ### 7. Use Components
@@ -271,6 +345,16 @@ function App() {
 
 ---
 
+## CLI Commands
+
+```bash
+npx @j3m-quantum/ui init      # Set up cursor rules for AI assistance
+npx @j3m-quantum/ui list      # List all available components
+npx @j3m-quantum/ui doctor    # Check if setup is correct
+```
+
+---
+
 ## Updating the Package
 
 To get the latest components and styling:
@@ -280,3 +364,5 @@ npm update @j3m-quantum/ui
 # or
 npm install @j3m-quantum/ui@latest
 ```
+
+After updating, you may want to re-run `npx @j3m-quantum/ui init` to get the latest cursor rules.