@j3m-quantum/ui 1.0.0 → 1.3.0

package/README.md

@@ -84,52 +84,59 @@ function App() {
 
 ## Theme Modes
 
-### Dark Mode
+The design system supports four theme modes. Use the `.j3m-app-bg` utility class for proper backgrounds:
+
+### Light Mode (Default)
 
-Add the `dark` class to your root element:
+```tsx
+<div className="j3m-app-bg">
+  {/* Light themed content */}
+</div>
+```
+
+### 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 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
+### Mesh Variant
 
-### Color System: Radix 12-Step Scale
+For a more complex gradient background, add the `.mesh` class:
 
-Colors use HSL format for easy theming and opacity manipulation:
+```tsx
+<div className="theme-glass j3m-app-bg mesh">
+  {/* Glass with mesh gradient */}
+</div>
+```
 
-```css
-/* Change accent color once, updates everywhere */
-:root {
-  --primary: 24 91% 62%;  /* Your brand orange */
-}
+## Design Tokens
 
-/* Usage with opacity */
-background: hsl(var(--primary));         /* Solid */
-background: hsl(var(--primary) / 0.3);   /* 30% opacity */
-```
+### Color System: 12-Step Scale
 
-### Color Scales
+Colors use HEX format for simplicity and compatibility:
 
 | Scale | Steps | Purpose |
 |-------|-------|---------|
@@ -150,7 +157,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 +165,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 +219,139 @@ 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,
+  SidebarProvider, Sidebar, SidebarContent,
+  NavMain, NavUser, SiteHeader 
+} from '@j3m-quantum/ui'
 
 // Styles (CSS)
 import '@j3m-quantum/ui/styles'
 ```
 
+## 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.)
@@ -253,6 +404,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