@j3m-quantum/ui 1.3.0 → 1.4.0

package/README.md

@@ -13,7 +13,7 @@ J3M Quantum UI - A React component library with J3M design tokens.
 - **J3M Design Tokens** - Orange primary, neutral grays, pill-shaped buttons
 - **Dark Mode** - Full dark theme support via `.dark` class
 - **Glass Mode** - Frosted glass effects via `.theme-glass` class
-- **55+ Components** - Complete UI component library with J3M styling
+- **60+ Components** - Complete UI component library with J3M styling
 - **All-in-One** - Everything bundled, just install and use
 - **Smooth Animations** - Powered by tw-animate-css
 
@@ -67,17 +67,19 @@ import { Button, Card, Input, Dialog, DialogTrigger, DialogContent } from '@j3m-
 
 function App() {
   return (
-    <Card>
-      <Input placeholder="Enter email" />
-      <Dialog>
-        <DialogTrigger asChild>
-          <Button>Open Dialog</Button>
-        </DialogTrigger>
-        <DialogContent>
-          <p>This dialog has smooth animations!</p>
-        </DialogContent>
-      </Dialog>
-    </Card>
+    <div className="j3m-app-bg min-h-screen p-8">
+      <Card className="glass-context">
+        <Input placeholder="Enter email" />
+        <Dialog>
+          <DialogTrigger asChild>
+            <Button>Open Dialog</Button>
+          </DialogTrigger>
+          <DialogContent>
+            <p>This dialog has smooth animations!</p>
+          </DialogContent>
+        </Dialog>
+      </Card>
+    </div>
   )
 }
 ```
@@ -104,7 +106,7 @@ The design system supports four theme modes. Use the `.j3m-app-bg` utility class
 
 ### Glass Mode (Light)
 
-Frosted glass on colorful gradient background:
+Frosted glass on colorful gradient or image background:
 
 ```tsx
 <div className="theme-glass j3m-app-bg">
@@ -122,16 +124,35 @@ Dark frosted glass on deep gradient - sophisticated industrial aesthetic:
 </div>
 ```
 
-### Mesh Variant
+### Custom Background Images
+
+In glass mode, you can set a custom background image:
 
-For a more complex gradient background, add the `.mesh` class:
+```css
+:root {
+  --j3m-bg-image: url('/your-background.jpg');
+}
+```
+
+## Glass Context
+
+When using glass mode, cards containing interactive components (inputs, buttons, selects) need the `glass-context` class for proper styling:
 
 ```tsx
-<div className="theme-glass j3m-app-bg mesh">
-  {/* Glass with mesh gradient */}
-</div>
+// Correct - inputs and buttons styled properly in glass mode
+<Card className="glass-context">
+  <CardHeader>
+    <CardTitle>Contact Form</CardTitle>
+  </CardHeader>
+  <CardContent>
+    <Input placeholder="Name" />
+    <Button>Submit</Button>
+  </CardContent>
+</Card>
 ```
 
+**Note:** Portal components (Dialog, Sheet, Popover, Select dropdown) automatically adapt to the current theme mode - no `glass-context` needed.
+
 ## Design Tokens
 
 ### Color System: 12-Step Scale
@@ -221,15 +242,39 @@ All of these are bundled and ready to use:
 ```typescript
 // Everything from one package!
 import { 
-  Button, Card, Dialog,
+  Button, Card, Dialog, Input,
   SidebarProvider, Sidebar, SidebarContent,
-  NavMain, NavUser, SiteHeader 
+  NavMain, NavUser, SiteHeader,
+  EventCalendar, ThemeSwitch
 } from '@j3m-quantum/ui'
 
 // Styles (CSS)
 import '@j3m-quantum/ui/styles'
 ```
 
+## Components
+
+### Inputs
+Button, ButtonGroup, Input, InputGroup, Textarea, Checkbox, RadioGroup, Switch, Slider, Select, NativeSelect, Toggle, ToggleGroup, Form, Field, Label, CopyButton
+
+### 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
+
+### Navigation
+Breadcrumb, Pagination, Command, SearchTrigger, DropdownMenu, Menubar, NavigationMenu, ContextMenu
+
+### Overlay
+Dialog, Drawer, Sheet, Popover, HoverCard
+
+### Layout
+ScrollArea, Collapsible, Resizable, Sidebar, SidebarProvider, SidebarInset, Section
+
+### Utilities
+ThemeSwitch, ToolbarCanvas, PlayerCanvas
+
 ## Blocks
 
 Pre-built, composable sidebar components for enterprise applications.
@@ -373,6 +418,15 @@ export default defineConfig({
 })
 ```
 
+### Components look wrong in glass mode
+Make sure to add `glass-context` class to Cards containing interactive components:
+```tsx
+<Card className="glass-context">
+  <Input />
+  <Button>Submit</Button>
+</Card>
+```
+
 ## Cursor Rules (AI Assistant)
 
 If your team uses Cursor or AI coding assistants, we provide ready-to-use rules to ensure consistent usage of the design system.

package/cursor-rules-for-consumers.md

@@ -1,6 +1,6 @@
 # J3M Quantum UI - Cursor Rules
 
-Copy the rules below to `.cursor/rules` in your project to help AI assistants use the J3M Design System correctly.
+Copy the rules below to `.cursor/rules` or `.cursorrules` in your project to help AI assistants use the J3M Design System correctly.
 
 ---
 
@@ -13,6 +13,7 @@ Copy the rules below to `.cursor/rules` in your project to help AI assistants us
 - This project uses @j3m-quantum/ui - a complete React component library with J3M styling
 - Import components directly: `import { Button, Card, Input } from '@j3m-quantum/ui'`
 - Do NOT use shadcn CLI to add components - everything is already bundled
+- Do NOT create local component copies - use the package exports
 
 ## CSS Import Order (Critical)
 The order in src/index.css must be:
@@ -22,44 +23,164 @@ The order in src/index.css must be:
 @import "@j3m-quantum/ui/styles";   /* J3M theme and tokens */
 ```
 
-## Theme Modes
-- Dark mode: Add `dark` class to root element
-- Glass mode: Add `theme-glass` class to root element
-- Combined: `<div className="dark theme-glass">`
+## Theme Modes (4 Modes)
+The design system supports four theme modes:
+
+| Mode | Classes | Description |
+|------|---------|-------------|
+| Light Solid | (default) | Opaque surfaces, gray backgrounds |
+| Dark Solid | `dark` | Dark opaque surfaces |
+| 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: #FFFFFF - use `bg-background`
-- Foreground: #333333 - use `text-foreground`
-- Muted: #E8E8E8 - use `bg-muted`, `text-muted-foreground`
+- 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 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
 
 ## DON'T
 - Don't use shadcn CLI - components are already bundled
-- Don't override CSS variables unless approved by design system maintainer
+- Don't override component CSS unless approved by design system maintainer
 - 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
+
+## Available Components (60+)
+
+### Inputs
+Button, ButtonGroup, Input, InputGroup, Textarea, Checkbox, RadioGroup, Switch, Slider, Select, NativeSelect, Toggle, ToggleGroup, Form, Field, Label, CopyButton
+
+### Display
+Card, Table, Badge, Avatar, UserAvatarsDropdown, Separator, Skeleton, Accordion, Tabs, Calendar, EventCalendar, Carousel, Chart, AspectRatio, Empty, Item, Kbd
 
-## Available Components (55+)
-Inputs: Button, ButtonGroup, Input, Textarea, Checkbox, RadioGroup, Switch, Slider, Select, NativeSelect, Toggle, ToggleGroup, ToolBarCanvas, PlayerCanvas, Form, Label
+### Feedback
+Alert, AlertDialog, Progress, Tooltip, Sonner (Toast), Spinner
 
-Display: Card, Table, Badge, Avatar, Separator, Skeleton, Accordion, Tabs, Calendar, Carousel, Chart, AspectRatio, Empty, Item, Kbd
+### Navigation
+Breadcrumb, Pagination, Command, SearchTrigger, DropdownMenu, Menubar, NavigationMenu, ContextMenu
 
-Feedback: Alert, AlertDialog, Progress, Tooltip, Sonner (Toast), Spinner
+### Overlay
+Dialog, Drawer, Sheet, Popover, HoverCard
 
-Navigation: Breadcrumb, Pagination, Command, DropdownMenu, Menubar, NavigationMenu, ContextMenu
+### Layout
+ScrollArea, Collapsible, Resizable, Sidebar, SidebarProvider, SidebarInset, Section
 
-Overlay: Dialog, Drawer, Sheet, Popover, HoverCard
+### Blocks (Pre-built compositions)
+SiteHeader, NavMain, NavProjects, NavSecondary, NavUser, SearchForm
 
-Layout: ScrollArea, Collapsible, Resizable, Sidebar, Section
+### 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>
+```
 
 ## Requesting Changes
 Need a new component or styling change? Don't build it locally.
@@ -105,23 +226,45 @@ export default defineConfig({
 ```
 
 ### 5. Add Cursor Rules
-Create `.cursor/rules` in your project root and paste the rules from above.
+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. Use Components
+### 7. Use Components
 ```tsx
-import { Button, Card, CardHeader, CardTitle, CardContent, Input } from '@j3m-quantum/ui'
+import { 
+  Button, 
+  Card, CardHeader, CardTitle, CardContent, 
+  Input,
+  ThemeSwitch 
+} from '@j3m-quantum/ui'
 
 function App() {
   return (
-    <Card>
-      <CardHeader>
-        <CardTitle>Welcome</CardTitle>
-      </CardHeader>
-      <CardContent>
-        <Input placeholder="Enter your name" />
-        <Button>Submit</Button>
-      </CardContent>
-    </Card>
+    <div className="j3m-app-bg min-h-screen p-8">
+      <div className="flex justify-end mb-4">
+        <ThemeSwitch />
+      </div>
+      <Card className="glass-context max-w-md">
+        <CardHeader>
+          <CardTitle>Welcome</CardTitle>
+        </CardHeader>
+        <CardContent className="space-y-4">
+          <Input placeholder="Enter your name" />
+          <Button>Submit</Button>
+        </CardContent>
+      </Card>
+    </div>
   )
 }
 ```