shadcn-glass-ui 1.0.10 → 2.0.0

package/CHANGELOG.md

@@ -2,14 +2,238 @@
 
 All notable changes to this project will be documented in this file.
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.0.0] - 2025-12-11
+
+### ✨ Added
+
+**New Components:**
+
+- **StepperGlass** - Compound stepper component for multi-step workflows
+  - 3 variants: `numbered` (default), `icon`, `dots`
+  - 2 orientations: `horizontal` (default), `vertical`
+  - 3 sizes: `sm`, `md`, `lg`
+  - Linear mode support for wizard patterns (locks future steps)
+  - Full accessibility: keyboard navigation, ARIA labels, focus management
+  - 14+ Storybook stories covering all variants and use cases
+  - Complete unit test coverage
+
+**Token Architecture:**
+
+- **3-Layer CSS Token System** implemented across all themes
+  - **Layer 1**: 207 primitive tokens in `src/styles/tokens/oklch-primitives.css`
+  - **Layer 2**: Semantic tokens (role-based) in each theme file
+  - **Layer 3**: Component tokens (component-specific)
+- **Zero hardcoded OKLCH values** in all theme files:
+  - glass.css: 98 → 0 hardcoded values ✅
+  - light.css: 3 → 0 hardcoded values ✅
+  - aurora.css: 0 → 0 hardcoded values ✅
+- **296+ CSS variables per theme** with complete semantic coverage
+- **Theme creation time**: Reduced from 2-3 hours to 10-15 minutes (90% faster)
+
+**Documentation:**
+
+- [TOKEN_ARCHITECTURE.md](docs/TOKEN_ARCHITECTURE.md) (365 lines) - Complete 3-layer token system
+  guide
+- [THEME_CREATION_GUIDE.md](docs/THEME_CREATION_GUIDE.md) (455 lines) - 15-minute theme creation
+  tutorial
+- [CSS_VARIABLES_AUDIT.md](docs/CSS_VARIABLES_AUDIT.md) - Complete audit of 296+ variables
+- [API_PATTERNS_COMPARISON.md](docs/API_PATTERNS_COMPARISON.md) - Component API consistency guide
+- [PRIMITIVE_MAPPING.md](docs/PRIMITIVE_MAPPING.md) - Primitive token reference
+- [CSS_VARIABLES_MIGRATION_2.0.md](docs/migration/CSS_VARIABLES_MIGRATION_2.0.md) - v1.x → v2.0.0
+  migration guide
+
+**Custom Hooks (Exported):**
+
+- `useFocus` - Focus state management with glow effects
+- `useHover` - Hover detection for interactive components
+- `useResponsive` - Responsive breakpoint detection
+- `useWallpaperTint` - Wallpaper color tint detection
+
+**Registry:**
+
+- Added `stepper-glass` to shadcn registry
+- Total registry items: 55 components
+
+### 🔧 Internal
+
+**CSS Variables Standardization:**
+
+- Migrated all internal components to semantic CSS variable names
+- Updated `CircularMetricGlass`, `MetricCardGlass`, `MetricsGridGlass` to use semantic tokens
+- Updated `InteractiveCard` documentation with new variable names
+- All unit tests updated to reflect semantic naming
+- Complete migration to 3-layer token architecture
+
+**Performance:**
+
+- Theme creation time: 2-3 hours → 10-15 minutes (90% faster)
+- CSS maintainability improved with semantic token layer
+- Zero code duplication in color values
+
+### ⚠️ BREAKING CHANGES
+
+**CSS Variables REMOVED:**
+
+The following CSS variable names have been **REMOVED** in v2.0.0:
+
+| Removed (v1.x)       | Replacement (v2.0+)      | Semantic Meaning |
+| -------------------- | ------------------------ | ---------------- |
+| `--metric-emerald-*` | `--metric-success-*`     | Success states   |
+| `--metric-amber-*`   | `--metric-warning-*`     | Warning states   |
+| `--metric-blue-*`    | `--metric-default-*`     | Neutral/default  |
+| `--metric-red-*`     | `--metric-destructive-*` | Error/danger     |
+
+**Total affected variables:** 16 (4 color families × 4 properties: -bg, -text, -border, -glow)
+
+**Migration:**
+
+```css
+/* ❌ REMOVED in v2.0.0 */
+background: var(--metric-emerald-bg);
+color: var(--metric-amber-text);
+box-shadow: var(--metric-blue-glow);
+
+/* ✅ Use in v2.0.0+ */
+background: var(--metric-success-bg);
+color: var(--metric-warning-text);
+box-shadow: var(--metric-default-glow);
+```
+
+**Why?**
+
+- Aligns with shadcn/ui naming conventions
+- Improves semantic meaning (color names → semantic roles)
+- Consistency with component variant props (AlertGlass, BadgeGlass, ButtonGlass)
+- Part of 3-layer token architecture migration
+
+**Migration Guide:**
+[docs/migration/CSS_VARIABLES_MIGRATION_2.0.md](docs/migration/CSS_VARIABLES_MIGRATION_2.0.md)
+
+**Automated Migration Script:**
+
+```bash
+# macOS/Linux
+find src/ -type f \( -name "*.tsx" -o -name "*.css" \) -exec sed -i '' \
+  -e 's/--metric-emerald-/--metric-success-/g' \
+  -e 's/--metric-amber-/--metric-warning-/g' \
+  -e 's/--metric-blue-/--metric-default-/g' \
+  -e 's/--metric-red-/--metric-destructive-/g' \
+  {} +
+```
+
+### 📊 Statistics
+
+- **Components**: 57 → **58** (added StepperGlass)
+- **Tests**: 1,355+ → **~1,570+**
+  - Visual: 582 → **802** (+220 screenshots from StepperGlass variants)
+  - Compliance: ~650
+  - Unit: ~125
+- **Primitive Tokens**: **207** OKLCH color primitives
+- **CSS Variables**: **296+** per theme (glass, light, aurora)
+- **Hardcoded OKLCH**: **0** (was 98 in glass.css)
+- **Themes**: 3 (glass, light, aurora)
+- **Registry Items**: **55**
+- **Exported Hooks**: **4**
+
+### 📚 Related Documentation
+
+- [TOKEN_ARCHITECTURE.md](docs/TOKEN_ARCHITECTURE.md) - Complete token system documentation
+- [THEME_CREATION_GUIDE.md](docs/THEME_CREATION_GUIDE.md) - Create themes in 15 minutes
+- [CSS_VARIABLES_MIGRATION_2.0.md](docs/migration/CSS_VARIABLES_MIGRATION_2.0.md) - Migration guide
+- [CSS_VARIABLES_AUDIT.md](docs/CSS_VARIABLES_AUDIT.md) - Full variable audit
+
+## [1.1.0] - 2025-12-10
+
+### ✨ Added
+
+**New Components:**
+
+- **SparklineGlass**: Compact bar chart for time series visualization
+  - Support for height variants (sm/md/lg) and gap spacing (none/sm/md)
+  - Highlight maximum value with custom colors
+  - Animated grow effect with staggered delays
+  - Full accessibility with role="img" and descriptive aria-labels
+  - 10 Storybook stories and comprehensive unit tests
+
+- **InsightCardGlass**: Insight display component with 7 semantic variants
+  - Variants: default, tip, highlight, warning, stat, growth, decline
+  - Inline and card display modes
+  - Clickable with full keyboard support (Enter/Space keys)
+  - Animated fade-in effect
+  - Full accessibility support
+
+**Extended Components:**
+
+- **YearCardGlass**:
+  - Added optional `sparklineData` for monthly activity trends
+  - Added optional `insights` array for analytical insight cards
+  - Support for all 7 InsightCardGlass variants
+  - Full backward compatibility maintained
+  - 8 new Storybook stories, 30 unit tests
+
+- **MetricCardGlass**:
+  - Added optional `sparklineData` for metric trend visualization
+  - Added `showSparkline` flag for toggling sparkline display
+  - Automatic positioning of progress bar and sparkline
+  - Full backward compatibility maintained
+  - 11 new Storybook stories, 33 unit tests
+
+**AI Compatibility:**
+
+- Included `docs/` folder in npm package for AI assistants
+- Added `docs/EXPORTS_MAP.json` - Machine-readable component registry
+- Added `docs/AI_USAGE.md` - Quick reference guide for AI tools
+- Enhanced TypeDoc comments with `@example` and `@accessibility` sections
+- Added `context7.json` for Context7 MCP integration
+- Added CLI commands for component exploration:
+  - `npx shadcn-glass-ui info <name>` - Show component details (fuzzy search)
+  - `npx shadcn-glass-ui list` - List all components
+  - `npx shadcn-glass-ui list --category=core` - Filter by category
+
+**Infrastructure:**
+
+- Installed `framer-motion` dependency for animations
+- Added CVA variants for SparklineGlass and InsightCardGlass
+- Added CSS animations: `sparkline-grow` and `insight-fade-in`
+- Added CSS variables for SparklineGlass theming
+- Created visual regression tests for new components
+
+### 📊 Testing
+
+- **Total new tests**: 83 unit tests + 5 visual regression tests
+- **Pass rate**: 100% (all tests passing)
+- **Coverage**: SparklineGlass (10 tests), InsightCardGlass (10 tests), YearCardGlass (+30 tests),
+  MetricCardGlass (+33 tests)
+
+### 🔄 Changed
+
+- Updated component count: 55+ components (was 53)
+- Updated `package.json` to include `docs/` in published package
+- Enhanced registry with new component entries
+
+### 🚀 Breaking Changes
+
+**None** - This release maintains full backward compatibility with v1.0.x
+
+## [1.0.9] - 2025-12-06
+
+### 📚 AIDocumentation
+
+- Added improved AI-focused documentation to help LLMs understand and work with the codebase more
+  effectively
+- Added guidance for AI assistants, workflows, and common automation patterns
+- Enhanced internal docs to optimize reasoning and code navigation for AI tools
+- Added improved storybook stories
 
 ## [1.0.9] - 2025-12-06
 
 ### 🐛 Bug Fixes
 
 **CSS Import Order:**
+
 - Fixed PostCSS warnings by moving all `@import` directives before CSS rules
 - All imports now precede style declarations (per CSS spec requirement)
 - Build process now runs completely clean without warnings
@@ -21,6 +245,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### 📚 Documentation
 
 **Major CLAUDE.md Restructure - AI-Friendly Documentation:**
+
 - Added **Quick Commands Cheatsheet** at the top for instant reference
 - Added **Common Tasks for AI** section with step-by-step workflows:
   - Adding new Glass components
@@ -66,11 +291,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### 🔄 Changed
 
 **Package Name:**
+
 - Renamed package from `@yhooi2/shadcn-glass-ui` to `shadcn-glass-ui`
 - Simpler installation: `npm install shadcn-glass-ui`
-- **Migration:** Update your `package.json` dependencies from `@yhooi2/shadcn-glass-ui` to `shadcn-glass-ui`
+- **Migration:** Update your `package.json` dependencies from `@yhooi2/shadcn-glass-ui` to
+  `shadcn-glass-ui`
 
 **Publishing:**
+
 - Now publishing only to npm Registry (removed GitHub Packages)
 - Simplified installation - no authentication required
 - Single source of truth for package distribution
@@ -101,6 +329,7 @@ npm install shadcn-glass-ui
 ```
 
 Update your imports (no changes needed - imports remain the same):
+
 ```tsx
 // Still works the same way
 import { ButtonGlass, InputGlass } from 'shadcn-glass-ui';
@@ -111,11 +340,14 @@ import { ButtonGlass, InputGlass } from 'shadcn-glass-ui';
 ### 🔄 Changed
 
 **Package Name:**
+
 - Renamed package from `@yhooi2/shadcn-glass-ui` to `shadcn-glass-ui`
 - Simpler installation: `npm install shadcn-glass-ui`
-- **Migration:** Update your `package.json` dependencies from `@yhooi2/shadcn-glass-ui` to `shadcn-glass-ui`
+- **Migration:** Update your `package.json` dependencies from `@yhooi2/shadcn-glass-ui` to
+  `shadcn-glass-ui`
 
 **Publishing:**
+
 - Now publishing only to npm Registry (removed GitHub Packages)
 - Simplified installation - no authentication required
 - Single source of truth for package distribution
@@ -146,6 +378,7 @@ npm install shadcn-glass-ui
 ```
 
 Update your imports (no changes needed - imports remain the same):
+
 ```tsx
 // Still works the same way
 import { ButtonGlass, InputGlass } from 'shadcn-glass-ui';
@@ -156,6 +389,7 @@ import { ButtonGlass, InputGlass } from 'shadcn-glass-ui';
 ### ✨ Added
 
 **Glass Variants System:**
+
 - New comprehensive glass effect variants: `crystal`, `frosted`, `fluted`, `glass`
 - Color tint modifiers: `purple`, `cyan`, `amber`, `emerald`, `rose`
 - Intensity modifiers: `subtle`, `medium`, `strong`
@@ -163,10 +397,12 @@ import { ButtonGlass, InputGlass } from 'shadcn-glass-ui';
 - New CSS utility classes in `primitives.css` for all variants
 
 **Components:**
+
 - `GlassVariantsDemo` - Interactive showcase of all 72 glass variant combinations
 - Updated `GlassCard.stories.tsx` with variant demonstrations
 
 **Publishing:**
+
 - Dual registry support: npm Registry + GitHub Packages
 - Automated publishing to both registries on release
 - Enhanced GitHub Actions workflow with registry validation
@@ -239,7 +475,8 @@ import { ButtonGlass, InputGlass } from 'shadcn-glass-ui';
 
 - **ModalGlass:** Legacy props API completely removed
   - **Old API:** `isOpen`, `onClose`, `title` props
-  - **New API:** Compound API only (`ModalGlass.Root`, `.Overlay`, `.Content`, `.Header`, `.Body`, `.Footer`, `.Title`, `.Description`, `.Close`)
+  - **New API:** Compound API only (`ModalGlass.Root`, `.Overlay`, `.Content`, `.Header`, `.Body`,
+    `.Footer`, `.Title`, `.Description`, `.Close`)
   - **Migration:** See [ModalGlass Compound API guide](docs/migration/modal-glass-compound-api.md)
   - **Key Changes:**
     - `isOpen` → `open` (on ModalGlass.Root)
@@ -291,7 +528,8 @@ import { ButtonGlass, InputGlass } from 'shadcn-glass-ui';
 
 ### ⚠️ BREAKING CHANGES
 
-- **ButtonGlass:** Removed `danger` variant in favor of `destructive` for shadcn/ui API compatibility
+- **ButtonGlass:** Removed `danger` variant in favor of `destructive` for shadcn/ui API
+  compatibility
   - **Migration:** Replace `variant="danger"` with `variant="destructive"`
   - **Affected:** 3 files in library, user code may require updates
   - **Rationale:** Aligns with shadcn/ui design system standards
@@ -312,7 +550,8 @@ import { ButtonGlass, InputGlass } from 'shadcn-glass-ui';
 
 ### 🔧 Refactored
 
-- **AlertGlass:** Migrated from deprecated `type` prop to `variant` prop (57 instances across codebase)
+- **AlertGlass:** Migrated from deprecated `type` prop to `variant` prop (57 instances across
+  codebase)
 - **NotificationGlass:** Migrated from deprecated `type` prop to `variant` prop (8 source files)
 - Updated all visual regression tests to use new `variant` API (582 tests passing)
 - Updated all unit tests to use new `variant` API (32 NotificationGlass tests, 32 AlertGlass tests)
@@ -398,8 +637,10 @@ If you're using this library and have code that breaks after updating, here's ho
 
 All changes align the library with shadcn/ui design system standards:
 
-1. **Consistent Naming**: `variant` is the standard prop name across shadcn/ui components (Button, Badge, Alert, etc.)
-2. **Semantic Correctness**: `variant` describes visual style variations, while `type` describes data types
+1. **Consistent Naming**: `variant` is the standard prop name across shadcn/ui components (Button,
+   Badge, Alert, etc.)
+2. **Semantic Correctness**: `variant` describes visual style variations, while `type` describes
+   data types
 3. **Better DX**: Consistent APIs across all Glass components improve developer experience
 4. **Design System Compliance**: Makes the library easier to integrate with shadcn/ui projects
 
@@ -415,13 +656,13 @@ All changes align the library with shadcn/ui design system standards:
 
 ### Changes Summary
 
-| Category           | Count |
-|--------------------|-------|
+| Category           | Count                                          |
+| ------------------ | ---------------------------------------------- |
 | Breaking changes   | 3 (ButtonGlass, AlertGlass, NotificationGlass) |
-| Files modified     | 20+ |
-| Empty dirs removed | 9 |
-| Tests updated      | 582 visual + 64 unit |
-| Documentation      | 5 new files (1,967 lines) |
+| Files modified     | 20+                                            |
+| Empty dirs removed | 9                                              |
+| Tests updated      | 582 visual + 64 unit                           |
+| Documentation      | 5 new files (1,967 lines)                      |
 
 ### Quality Metrics
 
@@ -448,4 +689,6 @@ All changes align the library with shadcn/ui design system standards:
 
 ---
 
-**Note**: This changelog documents the breaking changes and migrations performed during the legacy code cleanup initiative. For future releases, this file will continue to track all notable changes to the project.
+**Note**: This changelog documents the breaking changes and migrations performed during the legacy
+code cleanup initiative. For future releases, this file will continue to track all notable changes
+to the project.