@j3m-quantum/ui 2.1.0 → 2.1.5

package/README.md

@@ -73,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
 

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
-
-### 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>
-```
+SiteHeader, NavMain, NavProjects, NavSecondary, NavUser, SearchForm, PlanningTable, CalibrationTable, SupplierWeeklyLoading, Gantt, Kanban
 
-## 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
 ```
 
 ---