@j3m-quantum/ui 1.0.0 → 1.3.1

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,69 +67,97 @@ 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>
   )
 }
 ```
 
 ## Theme Modes
 
-### Dark Mode
+The design system supports four theme modes. Use the `.j3m-app-bg` utility class for proper backgrounds:
+
+### Light Mode (Default)
+
+```tsx
+<div className="j3m-app-bg">
+  {/* Light themed content */}
+</div>
+```
 
-Add the `dark` class to your root element:
+### Dark Mode
 
 ```tsx
-<div className="dark">
+<div className="dark j3m-app-bg">
   {/* Dark themed content */}
 </div>
 ```
 
-### Glass Mode
+### Glass Mode (Light)
 
-Add `theme-glass` class for frosted glass effects:
+Frosted glass on colorful gradient or image background:
 
 ```tsx
-<div className="theme-glass">
-  {/* Glass themed content */}
+<div className="theme-glass j3m-app-bg">
+  {/* Light glass themed content */}
 </div>
 ```
 
-Combine with dark mode:
+### Glass Mode (Dark)
+
+Dark frosted glass on deep gradient - sophisticated industrial aesthetic:
 
 ```tsx
-<div className="dark theme-glass">
+<div className="dark theme-glass j3m-app-bg">
   {/* Dark glass themed content */}
 </div>
 ```
 
-## Design Tokens
-
-### Color System: Radix 12-Step Scale
+### Custom Background Images
 
-Colors use HSL format for easy theming and opacity manipulation:
+In glass mode, you can set a custom background image:
 
 ```css
-/* Change accent color once, updates everywhere */
 :root {
-  --primary: 24 91% 62%;  /* Your brand orange */
+  --j3m-bg-image: url('/your-background.jpg');
 }
+```
+
+## Glass Context
 
-/* Usage with opacity */
-background: hsl(var(--primary));         /* Solid */
-background: hsl(var(--primary) / 0.3);   /* 30% opacity */
+When using glass mode, cards containing interactive components (inputs, buttons, selects) need the `glass-context` class for proper styling:
+
+```tsx
+// 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>
 ```
 
-### Color Scales
+**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
+
+Colors use HEX format for simplicity and compatibility:
 
 | Scale | Steps | Purpose |
 |-------|-------|---------|
@@ -150,7 +178,7 @@ background: hsl(var(--primary) / 0.3);   /* 30% opacity */
 
 | Token | Description |
 |-------|-------------|
-| `--primary` | Brand accent (orange-9) |
+| `--primary` | Brand accent (#F58446) |
 | `--background` | Page background |
 | `--foreground` | Main text |
 | `--muted` | Subtle backgrounds |
@@ -158,6 +186,42 @@ background: hsl(var(--primary) / 0.3);   /* 30% opacity */
 | `--ring` | Focus rings |
 | `--radius` | Global border radius (12px) |
 
+### Background & Surface Tokens
+
+A hierarchical system that adapts to all four theme modes automatically:
+
+| Token | Purpose |
+|-------|---------|
+| `--j3m-bg-app` | Root app canvas |
+| `--j3m-bg-page` | Content area |
+| `--j3m-bg-surface` | Cards, sections |
+| `--j3m-bg-surface-hover` | Hovered cards |
+| `--j3m-bg-surface-active` | Active/pressed cards |
+| `--j3m-bg-elevated` | Raised elements |
+| `--j3m-bg-overlay` | Popovers, tooltips |
+| `--j3m-bg-muted` | Subtle backgrounds |
+| `--j3m-bg-subtle` | Very subtle backgrounds |
+| `--j3m-bg-element` | Interactive elements |
+| `--j3m-bg-input` | Input backgrounds |
+| `--j3m-bg-sidebar` | Sidebar background |
+
+These tokens automatically resolve to the correct values in each theme mode:
+- **Light/Dark solid**: Solid gray colors
+- **Glass Light**: Frosted white glass fills
+- **Glass Dark**: Dark frosted glass with blue tint
+
+### Dark Glass Primitives
+
+For advanced dark glass customization:
+
+| Token | Description |
+|-------|-------------|
+| `--j3m-glass-dark-surface` | Main dark glass surface |
+| `--j3m-glass-dark-elevated` | Elevated dark glass |
+| `--j3m-glass-dark-overlay` | Dark glass overlays |
+| `--j3m-glass-dark-border` | Subtle white border |
+| `--j3m-glass-dark-element` | Interactive element highlight |
+
 ## Included Dependencies
 
 All of these are bundled and ready to use:
@@ -176,31 +240,163 @@ All of these are bundled and ready to use:
 ## Exports
 
 ```typescript
-// Components
-import { Button, Card, Dialog, ... } from '@j3m-quantum/ui'
+// Everything from one package!
+import { 
+  Button, Card, Dialog, Input,
+  SidebarProvider, Sidebar, SidebarContent,
+  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.
+
+### Sidebar with Header
+
+A collapsible sidebar with sticky header, based on shadcn's sidebar-16.
+
+```tsx
+import { 
+  SidebarProvider, 
+  SidebarInset, 
+  SidebarTrigger,
+  Sidebar,
+  SidebarContent,
+  SidebarFooter,
+  SiteHeader,
+  NavMain,
+  NavUser,
+} from '@j3m-quantum/ui'
+import { HomeIcon, SettingsIcon } from 'lucide-react'
+
+const navItems = [
+  {
+    title: "Dashboard",
+    url: "/dashboard",
+    icon: HomeIcon,
+    isActive: true,
+    items: [
+      { title: "Overview", url: "/dashboard" },
+      { title: "Analytics", url: "/dashboard/analytics" },
+    ],
+  },
+]
+
+export default function Dashboard() {
+  return (
+    <div style={{ "--header-height": "3.5rem" }}>
+      <SidebarProvider>
+        <SiteHeader 
+          trigger={<SidebarTrigger />}
+          breadcrumbs={[{ label: "Dashboard" }]} 
+        />
+        <div className="flex flex-1">
+          <Sidebar>
+            <SidebarContent>
+              <NavMain items={navItems} />
+            </SidebarContent>
+            <SidebarFooter>
+              <NavUser user={{ name: "User", email: "user@example.com", avatar: "" }} />
+            </SidebarFooter>
+          </Sidebar>
+          <SidebarInset>
+            <main className="p-4">
+              {/* Your content */}
+            </main>
+          </SidebarInset>
+        </div>
+      </SidebarProvider>
+    </div>
+  )
+}
+```
+
+### Block Components
+
+| Component | Description |
+|-----------|-------------|
+| `SiteHeader` | Sticky header with breadcrumbs and trigger slot |
+| `NavMain` | Collapsible navigation groups with sub-items |
+| `NavProjects` | Projects section with dropdown actions |
+| `NavSecondary` | Secondary links (Support, Feedback) |
+| `NavUser` | User avatar with dropdown menu |
+| `SearchForm` | Search input component |
+
+### Custom Navigation
+
+```tsx
+import { NavMain, type NavItem } from '@j3m-quantum/ui'
+import { HomeIcon, SettingsIcon } from 'lucide-react'
+
+const navItems: NavItem[] = [
+  {
+    title: "Dashboard",
+    url: "/dashboard",
+    icon: HomeIcon,
+    isActive: true,
+    items: [
+      { title: "Overview", url: "/dashboard" },
+      { title: "Analytics", url: "/dashboard/analytics" },
+    ],
+  },
+  {
+    title: "Settings",
+    url: "/settings",
+    icon: SettingsIcon,
+    items: [
+      { title: "Profile", url: "/settings/profile" },
+      { title: "Team", url: "/settings/team" },
+    ],
+  },
+]
+
+<NavMain items={navItems} />
+```
+
 ## Customization
 
-Override CSS variables after the import using HSL format:
+Override CSS variables after the import:
 
 ```css
 @import "tailwindcss";
 @import "tw-animate-css";
 @import "@j3m-quantum/ui/styles";
 
-/* Custom overrides - use HSL values */
+/* Custom overrides */
 :root {
-  --primary: 210 100% 50%;  /* Blue accent instead of orange */
+  --primary: #3B82F6;  /* Blue accent instead of orange */
   --radius: 8px;
 }
 ```
 
-The HSL format allows automatic opacity variations throughout the UI.
-
 ## Troubleshooting
 
 ### Animations not working (Dialog, Sheet, Select, etc.)
@@ -222,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.
@@ -253,6 +458,10 @@ npm update @j3m-quantum/ui
 npm install @j3m-quantum/ui@latest
 ```
 
+## Third-Party Licenses
+
+- **Event Calendar**: Based on [big-calendar](https://github.com/lramos33/big-calendar) by Leonardo Ramos, MIT License
+
 ## License
 
 MIT

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>
   )
 }
 ```