shadcn-glass-ui 2.0.8 → 2.0.9

package/docs/DROPDOWN_ARCHITECTURE.md

@@ -0,0 +1,290 @@
+# Dropdown Components Architecture
+
+## Overview
+
+All dropdown-style components in the Glass UI library follow the **shadcn/ui compound component
+pattern**, built on **Radix UI primitives** and **shared styling utilities**.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      Radix UI Primitives                         │
+│              @radix-ui/react-dropdown-menu                       │
+└──────────────────────────────┬──────────────────────────────────┘
+                               │
+                               ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                   Shared Styling Utilities                       │
+│         src/lib/variants/dropdown-content-styles.ts             │
+└──────────────────────────────┬──────────────────────────────────┘
+                               │
+                               ▼
+┌─────────────────────────────────────────────────────────────────┐
+│              DropdownMenuGlass (Compound Components)             │
+│                src/components/glass/ui/dropdown-menu-glass.tsx  │
+│                                                                  │
+│  Exports:                                                        │
+│  • DropdownMenuGlass (Root)                                     │
+│  • DropdownMenuGlassTrigger                                     │
+│  • DropdownMenuGlassContent                                     │
+│  • DropdownMenuGlassItem                                        │
+│  • DropdownMenuGlassSeparator                                   │
+│  • DropdownMenuGlassLabel                                       │
+│  • DropdownMenuGlassCheckboxItem                                │
+│  • DropdownMenuGlassRadioGroup / RadioItem                      │
+│  • DropdownMenuGlassSub / SubTrigger / SubContent               │
+│  • DropdownMenuGlassShortcut                                    │
+└──────────────────────────────┬──────────────────────────────────┘
+                               │
+               ┌───────────────┼───────────────┐
+               ▼               ▼               ▼
+         ┌──────────┐   ┌──────────┐   ┌───────────────┐
+         │ Dropdown │   │   Sort   │   │   ComboBox    │
+         │  Glass   │   │ Dropdown │   │     Glass     │
+         │ (Simple) │   │  Glass   │   │  (Searchable) │
+         └──────────┘   └──────────┘   └───────────────┘
+```
+
+## Component APIs
+
+### 1. DropdownMenuGlass (Compound Components) - shadcn/ui Pattern
+
+**Location:** `src/components/glass/ui/dropdown-menu-glass.tsx`
+
+**Purpose:** Base compound components for building any dropdown menu
+
+```tsx
+import {
+  DropdownMenuGlass,
+  DropdownMenuGlassTrigger,
+  DropdownMenuGlassContent,
+  DropdownMenuGlassItem,
+  DropdownMenuGlassSeparator,
+  DropdownMenuGlassLabel,
+} from '@/components/glass/ui/dropdown-menu-glass';
+
+// Basic usage
+<DropdownMenuGlass>
+  <DropdownMenuGlassTrigger asChild>
+    <Button>Open Menu</Button>
+  </DropdownMenuGlassTrigger>
+  <DropdownMenuGlassContent>
+    <DropdownMenuGlassLabel>Actions</DropdownMenuGlassLabel>
+    <DropdownMenuGlassItem onSelect={() => console.log('Edit')}>
+      <Edit className="mr-2 h-4 w-4" />
+      Edit
+    </DropdownMenuGlassItem>
+    <DropdownMenuGlassSeparator />
+    <DropdownMenuGlassItem variant="destructive">
+      <Trash className="mr-2 h-4 w-4" />
+      Delete
+    </DropdownMenuGlassItem>
+  </DropdownMenuGlassContent>
+</DropdownMenuGlass>;
+```
+
+**Available Components:**
+
+| Component                       | Description                     |
+| ------------------------------- | ------------------------------- |
+| `DropdownMenuGlass`             | Root component (manages state)  |
+| `DropdownMenuGlassTrigger`      | Trigger element (use `asChild`) |
+| `DropdownMenuGlassContent`      | Dropdown content container      |
+| `DropdownMenuGlassItem`         | Menu item with `variant` prop   |
+| `DropdownMenuGlassSeparator`    | Visual divider                  |
+| `DropdownMenuGlassLabel`        | Section label                   |
+| `DropdownMenuGlassCheckboxItem` | Checkbox menu item              |
+| `DropdownMenuGlassRadioGroup`   | Radio group container           |
+| `DropdownMenuGlassRadioItem`    | Radio menu item                 |
+| `DropdownMenuGlassSub`          | Sub-menu root                   |
+| `DropdownMenuGlassSubTrigger`   | Sub-menu trigger                |
+| `DropdownMenuGlassSubContent`   | Sub-menu content                |
+| `DropdownMenuGlassShortcut`     | Keyboard shortcut hint          |
+
+### 2. DropdownGlass (Simple API)
+
+**Location:** `src/components/glass/ui/dropdown-glass.tsx`
+
+**Purpose:** Quick setup for basic dropdown menus (wrapper over compound components)
+
+```tsx
+import { DropdownGlass } from '@/components/glass/ui/dropdown-glass';
+
+<DropdownGlass
+  trigger={
+    <button>
+      <MoreVertical />
+    </button>
+  }
+  items={[
+    { label: 'Edit', icon: Edit, onClick: handleEdit },
+    { divider: true },
+    { label: 'Delete', icon: Trash, onClick: handleDelete, danger: true },
+  ]}
+  align="left"
+/>;
+```
+
+**When to use:**
+
+- Simple menus with items, dividers, and icons
+- No need for checkboxes, radio groups, or sub-menus
+
+### 3. SortDropdownGlass (Specialized)
+
+**Location:** `src/components/glass/atomic/sort-dropdown-glass.tsx`
+
+**Purpose:** Sort field selection with order toggle
+
+```tsx
+import { SortDropdownGlass } from '@/components/glass/atomic/sort-dropdown-glass';
+
+<SortDropdownGlass
+  sortBy="commits"
+  sortOrder="desc"
+  onSortChange={(field, order) => console.log(field, order)}
+  options={['commits', 'stars', 'name']}
+  compact={false}
+/>;
+```
+
+**Built on:** DropdownMenuGlass compound components
+
+### 4. ComboBoxGlass (Searchable)
+
+**Location:** `src/components/glass/ui/combobox-glass.tsx`
+
+**Purpose:** Searchable select dropdown with filtering
+
+```tsx
+import { ComboBoxGlass } from '@/components/glass/ui/combobox-glass';
+
+<ComboBoxGlass
+  options={[
+    { value: '1', label: 'Option 1' },
+    { value: '2', label: 'Option 2' },
+  ]}
+  value={selectedValue}
+  onChange={setSelectedValue}
+  searchable
+/>;
+```
+
+**Built on:** Radix UI Popover + shadcn Command (separate pattern for search)
+
+## Shared Styling
+
+### CSS Variables
+
+```css
+--dropdown-bg          /* Background color */
+--dropdown-border      /* Border color */
+--dropdown-glow        /* Shadow/glow effect */
+--dropdown-item-text   /* Item text color */
+--dropdown-item-hover  /* Hover background */
+--dropdown-icon        /* Icon color */
+--dropdown-icon-hover  /* Icon hover color */
+--dropdown-divider     /* Separator color */
+```
+
+### Styling Utilities
+
+**Location:** `src/lib/variants/dropdown-content-styles.ts`
+
+```typescript
+// Glass surface styling
+getDropdownContentStyles(): CSSProperties
+
+// Container classes
+dropdownContentClasses: string
+
+// Item classes with state support
+getDropdownItemClasses({ danger?, selected?, highlighted? }): string
+
+// Icon classes
+getDropdownIconClasses({ danger? }): string
+
+// Other classes
+dropdownSeparatorClasses: string
+dropdownLabelClasses: string
+```
+
+## Creating New Dropdown Components
+
+### Step 1: Import DropdownMenuGlass primitives
+
+```tsx
+import {
+  DropdownMenuGlass,
+  DropdownMenuGlassTrigger,
+  DropdownMenuGlassContent,
+  DropdownMenuGlassItem,
+} from '@/components/glass/ui/dropdown-menu-glass';
+```
+
+### Step 2: Build your component
+
+```tsx
+export function MyDropdown({ value, onChange, options }) {
+  return (
+    <DropdownMenuGlass>
+      <DropdownMenuGlassTrigger asChild>
+        <button>{value}</button>
+      </DropdownMenuGlassTrigger>
+      <DropdownMenuGlassContent>
+        {options.map((opt) => (
+          <DropdownMenuGlassItem key={opt.value} onSelect={() => onChange(opt.value)}>
+            {opt.label}
+          </DropdownMenuGlassItem>
+        ))}
+      </DropdownMenuGlassContent>
+    </DropdownMenuGlass>
+  );
+}
+```
+
+### Step 3: Add custom styling if needed
+
+```tsx
+<DropdownMenuGlassItem
+  className={cn(
+    'justify-between',
+    isSelected && 'bg-(--select-item-selected-bg)'
+  )}
+>
+```
+
+## Benefits
+
+1. **shadcn/ui Compatible**: Same compound component pattern
+2. **Composable**: Mix and match components as needed
+3. **Accessible**: Full Radix UI accessibility support
+4. **Themeable**: Uses CSS variables for easy customization
+5. **Tree-shakeable**: Import only what you need
+
+## Migration from v1.x
+
+### SortDropdownGlass Changes
+
+**Before (v1.x):**
+
+- Manual state management with useState
+- Custom click outside/Escape handlers
+- Z-index hacks
+
+**After (v2.x):**
+
+- Built on DropdownMenuGlass primitives
+- Radix UI handles all interactions
+- No z-index issues
+
+The API remains the same - no breaking changes for consumers.
+
+## Related Files
+
+- `src/components/glass/ui/dropdown-menu-glass.tsx` - Compound components
+- `src/components/glass/ui/dropdown-glass.tsx` - Simple API wrapper
+- `src/components/glass/atomic/sort-dropdown-glass.tsx` - Sort dropdown
+- `src/components/glass/ui/combobox-glass.tsx` - Searchable dropdown
+- `src/lib/variants/dropdown-content-styles.ts` - Shared styling

package/docs/GETTING_STARTED.md

@@ -28,9 +28,9 @@ Before starting, ensure you have:
 The easiest way to add components to an existing shadcn/ui project:
 
 ```bash
-npx shadcn@latest add @shadcn-glass-ui/button
-npx shadcn@latest add @shadcn-glass-ui/input
-npx shadcn@latest add @shadcn-glass-ui/modal
+npx shadcn@latest add @shadcn-glass-ui/button-glass
+npx shadcn@latest add @shadcn-glass-ui/input-glass
+npx shadcn@latest add @shadcn-glass-ui/modal-glass
 ```
 
 This will:
@@ -634,8 +634,9 @@ Read [UI_DESIGN.md](design-system/UI_DESIGN.md) to understand:
 ### Browse Examples
 
 - [Storybook](https://yhooi2.github.io/shadcn-glass-ui-library/) - Live component demos
-- [ComponentShowcase](../src/components/ComponentShowcase.tsx) - All components in one page
-- [DesktopShowcase](../src/components/DesktopShowcase.tsx) - Full application example
+- [ComponentShowcase](../src/components/demos/ComponentShowcase.tsx) - All components in one page
+- [DesktopShowcase](../src/components/demos/DesktopShowcase.tsx) - Full application example
+- [MobileShowcase](../src/components/demos/MobileShowcase.tsx) - Mobile-optimized showcase
 
 ### Customize
 

package/docs/TOKEN_ARCHITECTURE.md

@@ -340,6 +340,106 @@ src/styles/
 
 ---
 
+## Tailwind CSS v4: Base vs Derived Values
+
+### The Problem
+
+In Tailwind CSS v4, variables defined inside `@theme` are **overwritten by Tailwind's defaults**.
+This means custom base values like `--radius` get replaced.
+
+```css
+/* ❌ WRONG: Tailwind will overwrite --radius with its default (0.25rem) */
+@theme {
+  --radius: 0.75rem;
+  --radius-lg: var(--radius);
+}
+```
+
+### The Solution (Glass UI Pattern)
+
+Put **ALL values** (base AND derived) in `:root`, use `@theme` only for registration:
+
+```css
+/* ✅ CORRECT: ALL values in :root, @theme only references them */
+
+:root {
+  /* Base value - editable */
+  --radius: 0.75rem;
+
+  /* Derived values - MUST also be in :root to override Tailwind defaults */
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+}
+
+@theme {
+  /* Registration only - references :root values */
+  --radius-sm: var(--radius-sm);
+  --radius-md: var(--radius-md);
+  --radius-lg: var(--radius-lg);
+  --radius-xl: var(--radius-xl);
+}
+```
+
+**Why derived values MUST be in `:root`:**
+
+Tailwind v4 generates defaults like `--radius-xl: 0.75rem` in `@layer theme`. If you put your
+derived values in `@theme`, Tailwind's defaults will override them because `@layer theme` is
+processed after `@theme`.
+
+### Why This Works
+
+1. **`:root` has higher specificity** than Tailwind's `@layer theme`
+2. **ALL values are preserved** - both base and derived override Tailwind defaults
+3. **Derived values reference base** - they update automatically when base changes
+4. **`@theme` registers utilities** - makes values available as Tailwind classes
+5. **Single point of control** - change `--radius` once, affects all `--radius-*`
+
+### File Structure
+
+```
+src/styles/tokens/primitives.css
+├── :root { }           ← ALL VALUES (base + derived)
+│   ├── --radius (base)
+│   ├── --radius-sm, --radius-md, --radius-lg, ... (derived)
+│   ├── --blur (base)
+│   ├── --blur-sm, --blur-md, --blur-lg, ... (derived)
+│   └── ... all other scales
+│
+└── @theme { }          ← REGISTRATION ONLY (references)
+    ├── --radius-sm: var(--radius-sm);
+    ├── --blur-lg: var(--blur-lg);
+    └── ... references to :root values
+```
+
+### Customization Examples
+
+To change the global border radius:
+
+```css
+/* In your custom CSS (after importing Glass UI) */
+:root {
+  --radius: 1rem; /* 16px - Apple-style liquid glass */
+}
+```
+
+All `rounded-*` utilities will automatically update:
+
+| `--radius` Value | `rounded-sm` | `rounded-md` | `rounded-lg` | `rounded-xl` |
+| ---------------- | ------------ | ------------ | ------------ | ------------ |
+| `0.5rem` (8px)   | 4px          | 6px          | 8px          | 12px         |
+| `0.75rem` (12px) | 8px          | 10px         | 12px         | 16px         |
+| `1rem` (16px)    | 12px         | 14px         | 16px         | 20px         |
+| `1.25rem` (20px) | 16px         | 18px         | 20px         | 24px         |
+
+### References
+
+- [Tailwind v4 - shadcn/ui](https://ui.shadcn.com/docs/tailwind-v4)
+- [Theming shadcn with Tailwind v4](https://www.shadcnblocks.com/blog/tailwind4-shadcn-themeing/)
+
+---
+
 ## Browser Compatibility
 
 **Primitive Tokens:** Universal support (CSS custom properties)

package/docs/api/README.md

@@ -43,7 +43,7 @@ comprehensive docs.
 - **Storybook 10.1** - Component workshop with ESM-only architecture
 - **Vitest 4.0** - Browser mode testing with visual regression
 
-See [DEPENDENCIES.md](DEPENDENCIES.md) for detailed dependency documentation.
+See [DEPENDENCIES.md](../technical/DEPENDENCIES.md) for detailed dependency documentation.
 
 ## 🤖 AI Assistant Support
 
@@ -91,7 +91,7 @@ npm install shadcn-glass-ui
 
 - React 18.0+ or 19.0+
 - React-DOM 18.0+ or 19.0+
-- Tailwind CSS 4.0+
+- Tailwind CSS 4.1+
 
 ### Basic Usage
 
@@ -302,7 +302,7 @@ See [CHANGELOG.md](../../CHANGELOG.md) for complete version history and breaking
 - **[Visual Testing Guide](../../docs/visual-testing-guide.md)** - Screenshot update workflow
 - **[Migration Guide](MIGRATION_GUIDE.md)** - Upgrading from v1
 - **[Breaking Changes](BREAKING_CHANGES.md)** - API changes log
-- **[Dependencies](DEPENDENCIES.md)** - Detailed dependency docs
+- **[Dependencies](../technical/DEPENDENCIES.md)** - Detailed dependency docs
 - **[Contributing](../../CONTRIBUTING.md)** - Development guidelines
 
 ## 🎯 Component Categories