shadcn-glass-ui 2.3.1 → 2.3.2

package/docs/DROPDOWN_ARCHITECTURE.md

@@ -1,290 +0,0 @@
-# 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/METRIC_CARD_API_REDESIGN.md

@@ -1,354 +0,0 @@
-# MetricCardGlass API Redesign
-
-## Goal
-
-Make `MetricCardGlass` fully compatible with **shadcn/ui patterns** and **consistent** with other
-Glass UI library components.
-
----
-
-## 📋 Analysis of Existing Glass UI Patterns
-
-### 1. Variant System Pattern
-
-All components follow a unified variant system:
-
-#### AlertGlass
-
-```tsx
-variant?: 'default' | 'destructive' | 'success' | 'warning'
-//         ^^^^^^^^   ^^^^^^^^^^^^ shadcn/ui compatible
-//                                  ^^^^^^^^  ^^^^^^^^ Glass UI extensions
-```
-
-#### BadgeGlass
-
-```tsx
-variant?: 'default' | 'secondary' | 'destructive' | 'outline' | 'success' | 'warning' | 'info'
-//         ^^^^^^^^   ^^^^^^^^^^^   ^^^^^^^^^^^^   ^^^^^^^^^ shadcn/ui
-//                                                             ^^^^^^^^  ^^^^^^^^  ^^^^^ Glass UI
-```
-
-#### ButtonGlass
-
-```tsx
-variant?: 'primary' | 'secondary' | 'ghost' | 'destructive' | 'success' | 'text'
-//         ^^^^^^^^   ^^^^^^^^^^^   ^^^^^^   ^^^^^^^^^^^^^ shadcn/ui-like
-//                                                          ^^^^^^^^^ Glass UI
-```
-
-**Conclusion:** Uses `variant` prop with base shadcn/ui variants + extensions.
-
----
-
-### 2. CSS Variables Pattern
-
-All components use CSS variables for styling:
-
-```tsx
-// AlertGlass
-const variantStyles: Record<AlertVariant, AlertStyleVars> = {
-  default: {
-    bg: 'var(--alert-default-bg)',
-    border: 'var(--alert-default-border)',
-    text: 'var(--alert-default-text)',
-  },
-  destructive: { ... },
-  success: { ... },
-};
-```
-
-**Conclusion:** Each variant has corresponding CSS variables in the format
-`--component-variant-property`.
-
----
-
-### 3. Props Interface Pattern
-
-Standard structure:
-
-```tsx
-export interface ComponentProps
-  extends React.HTMLAttributes<HTMLDivElement>, VariantProps<typeof componentVariants> {
-  // Required props
-  readonly label: string;
-  readonly value: string | number;
-
-  // Optional extensions
-  readonly icon?: ReactNode;
-  readonly variant?: Variant;
-  readonly size?: Size;
-}
-```
-
-**Conclusion:** Uses `readonly`, extends `HTMLAttributes`, integrates with CVA
-(class-variance-authority).
-
----
-
-## 🔍 Analysis of Current MetricCardGlass API
-
-### Problems:
-
-1. **❌ No `variant` system**
-   - Uses custom `color` instead of standard `variant`
-   - Colors: `'emerald' | 'amber' | 'blue' | 'red'` don't match shadcn/ui
-
-2. **❌ Complex data model**
-   - `value` as percentage 0-100 + `valueFormatter` - unintuitive
-   - Requires math for displaying real values
-
-3. **❌ Incompatible with shadcn/ui**
-   - Uses `label` instead of standard `title` from shadcn/ui Card
-   - No `description` support
-
-4. **❌ `trend` object too complex**
-   - Requires `{ value: number, direction: 'up' | 'down', label?: string }`
-   - shadcn/ui typically uses a simple `change` string
-
----
-
-## ✅ Proposed Solution
-
-### New API (v2.0)
-
-```tsx
-// ========================================
-// TYPES
-// ========================================
-
-export type MetricVariant =
-  | 'default' // shadcn/ui base
-  | 'secondary' // shadcn/ui base
-  | 'success' // Glass UI extension
-  | 'warning' // Glass UI extension
-  | 'destructive'; // shadcn/ui base
-
-export type TrendDirection = 'up' | 'down' | 'neutral';
-
-export interface MetricChange {
-  /** Change value (e.g., 12.5 for +12.5%) */
-  readonly value: number;
-  /** Trend direction */
-  readonly direction?: TrendDirection;
-  /** Optional period label (e.g., "vs last month") */
-  readonly period?: string;
-}
-
-export interface MetricCardGlassProps
-  extends React.HTMLAttributes<HTMLDivElement>, VariantProps<typeof metricCardVariants> {
-  // ========================================
-  // CORE PROPS (shadcn/ui compatible)
-  // ========================================
-
-  /** Metric title (shadcn/ui Card: title) */
-  readonly title: string;
-
-  /** Display value (shadcn/ui Card: value) */
-  readonly value: string | number;
-
-  /** Optional description (shadcn/ui Card: description) */
-  readonly description?: string;
-
-  /** Change indicator (shadcn/ui: change) */
-  readonly change?: string | number | MetricChange;
-
-  /** Semantic variant (shadcn/ui: variant) */
-  readonly variant?: MetricVariant;
-
-  // ========================================
-  // GLASS UI EXTENSIONS
-  // ========================================
-
-  /** Icon to display */
-  readonly icon?: ReactNode;
-
-  /** Data for sparkline visualization */
-  readonly sparklineData?: readonly number[];
-
-  /** Show sparkline chart */
-  readonly showSparkline?: boolean;
-
-  /** Show progress bar (value must be 0-100) */
-  readonly showProgress?: boolean;
-
-  /** Progress percentage (0-100, separate from display value) */
-  readonly progress?: number;
-}
-```
-
----
-
-## 📝 Usage Examples
-
-### Simple variant (shadcn/ui style)
-
-```tsx
-<MetricCardGlass
-  title="Total Revenue"
-  value="$45,231"
-  change="+12.5%"
-  variant="success"
-  icon={<DollarSign />}
-/>
-```
-
-### With detailed change object
-
-```tsx
-<MetricCardGlass
-  title="Total Revenue"
-  value="$45,231"
-  change={{
-    value: 12.5,
-    direction: 'up',
-    period: 'vs last month',
-  }}
-  variant="success"
-  icon={<DollarSign />}
-/>
-```
-
-### With progress and sparkline (Glass UI extensions)
-
-```tsx
-<MetricCardGlass
-  title="Completion Rate"
-  value="85%"
-  description="Project progress"
-  change="+5.2%"
-  variant="success"
-  progress={85}
-  sparklineData={[70, 75, 78, 80, 82, 84, 85]}
-  showProgress
-  showSparkline
-/>
-```
-
-### Backward Compatibility (optional)
-
-To support the old API, aliases can be added:
-
-```tsx
-<MetricCardGlass
-  label="Total Revenue" // ⚠️ deprecated, use title
-  value={75}
-  valueFormatter={(v) => `$${v}`} // ⚠️ deprecated, use value directly
-  color="emerald" // ⚠️ deprecated, use variant="success"
-/>
-```
-
----
-
-## 🎨 Mapping: old API → new API
-
-| Old API                       | New API                    | Note                                  |
-| ----------------------------- | -------------------------- | ------------------------------------- |
-| `label`                       | `title`                    | shadcn/ui standard                    |
-| `value: number (0-100)`       | `value: string \| number`  | Simplification                        |
-| `valueFormatter`              | —                          | Removed, format before passing        |
-| `valueSuffix`                 | `description`              | shadcn/ui standard                    |
-| `color: 'emerald'`            | `variant: 'success'`       | Unification                           |
-| `color: 'amber'`              | `variant: 'warning'`       | Unification                           |
-| `color: 'blue'`               | `variant: 'default'`       | Unification                           |
-| `color: 'red'`                | `variant: 'destructive'`   | Unification                           |
-| `trend: { value, direction }` | `change: string \| object` | Simplification                        |
-| —                             | `progress: number`         | New: separation of value and progress |
-
----
-
-## 🛠 CSS Variables Structure
-
-Following the library pattern:
-
-```css
-/* glass-theme.css */
-
-/* Default variant */
---metric-default-bg: rgba(255, 255, 255, 0.08);
---metric-default-border: rgba(255, 255, 255, 0.15);
---metric-default-text: var(--text-primary);
---metric-default-glow: 0 0 20px rgba(59, 130, 246, 0.3);
-
-/* Success variant (emerald) */
---metric-success-bg: rgba(16, 185, 129, 0.08);
---metric-success-border: rgba(16, 185, 129, 0.25);
---metric-success-text: rgb(52, 211, 153);
---metric-success-glow: 0 0 20px rgba(16, 185, 129, 0.3);
-
-/* Warning variant (amber) */
---metric-warning-bg: rgba(245, 158, 11, 0.08);
---metric-warning-border: rgba(245, 158, 11, 0.25);
---metric-warning-text: rgb(251, 191, 36);
---metric-warning-glow: 0 0 20px rgba(245, 158, 11, 0.3);
-
-/* Destructive variant (red/rose) */
---metric-destructive-bg: rgba(244, 63, 94, 0.08);
---metric-destructive-border: rgba(244, 63, 94, 0.25);
---metric-destructive-text: rgb(251, 113, 133);
---metric-destructive-glow: 0 0 20px rgba(244, 63, 94, 0.3);
-```
-
----
-
-## 🎯 Advantages of New API
-
-### 1. **shadcn/ui compatibility** ✅
-
-- Uses standard props: `title`, `value`, `description`, `variant`
-- Can easily be replaced with shadcn/ui Card without API changes
-
-### 2. **Consistency with the library** ✅
-
-- Follows `AlertGlass`, `BadgeGlass`, `ButtonGlass` patterns
-- Uses unified `variant` system
-- CSS variables in unified format
-
-### 3. **Ease of use** ✅
-
-- No need for `valueFormatter` and math
-- Simple string `change="+12.5%"` instead of object
-- Clear separation of `value` (display) and `progress` (0-100)
-
-### 4. **Flexibility** ✅
-
-- Supports both simple strings and objects for `change`
-- Optional Glass UI extensions (sparkline, progress)
-- Backward compatibility through aliases (optional)
-
----
-
-## 🚀 Migration Plan
-
-### Step 1: Create new component
-
-- [ ] Create `metric-card-glass-v2.tsx` with new API
-- [ ] Add CVA variants to `metric-card-glass-variants.ts`
-- [ ] Add CSS variables to `glass-theme.css`
-
-### Step 2: Testing
-
-- [ ] Create stories for new API
-- [ ] Add unit tests
-- [ ] Add visual regression tests
-
-### Step 3: Migration
-
-- [ ] Update `dashboard.stories.tsx`
-- [ ] Update other usages
-- [ ] Add deprecation warnings for old API
-
-### Step 4: Documentation
-
-- [ ] Update Storybook docs
-- [ ] Add migration guide
-- [ ] Update README
-
----
-
-## 📚 References
-
-- [Card - shadcn/ui](https://ui.shadcn.com/docs/components/card)
-- [The Anatomy of shadcn/ui Components | Vercel Academy](https://vercel.com/academy/shadcn-ui/extending-shadcn-ui-with-custom-components)
-- [Shadcn UI Dashboard Widgets](https://shadcnstore.com/blocks/application/widgets)
-- [Stat Cards - Shadcn UI Kit](https://shadcnuikit.com/components/cards/stat)