0.13.0

🎉 What's New

Embla Carousel Integration

This release implements Embla Carousel's official Thumbnails pattern for the Album components, providing smooth, accessible photo navigation with proper API-to-API synchronization.

✨ Features

AlbumViewer Enhancements

• 🎠 Embla Carousel Integration - Replaced custom navigation with Embla carousel
• 👆 Swipe Gestures - Native touch/swipe support for photo navigation
• 🔄 API Synchronization - Proper carousel sync between main viewer and thumbnails
• 📭 Empty State Support - New hideWhenEmpty and emptyStateContent props
• ⌨️ Enhanced Keyboard Navigation - Arrow keys and Escape integrated with Embla API

FilmStrip Improvements

• 🎠 Vertical Carousel - Converted to Embla carousel with vertical axis
• 🖱️ Mouse-Wheel Support - Added embla-carousel-wheel-gestures plugin for desktop accessibility
• 🎯 Drag-Free Scrolling - Natural, momentum-based thumbnail navigation
• 🔄 Smart Synchronization - API-to-API sync with main photo carousel
• 🎨 Vertical Centering - Better UX with centered thumbnail layout

Responsive Design

• 📱 3-Breakpoint System - Progressive enhancement across mobile (< 640px), tablet (≥ 640px), and desktop-wide (≥ 1024px)
• 📐 Adaptive Padding - 8px mobile → 16px tablet → 24px desktop-wide
• 👁️ Consistent Breakpoints - Sidebar visibility aligned with padding at 640px

🐛 Bug Fixes

Critical UX Issues Resolved

1. hideWhenEmpty Effects Issue

   • Problem: Body scroll lock and keyboard listeners mounted before early return, freezing page scroll when component returned null
   • Solution: Added isViewerVisible flag to conditionally run effects only when viewer is rendered
   • Impact: Prevents UX regression in "Hide When Empty" story

2. FilmStrip Thumbnail Clicks

   • Problem: Thumbnail clicks no-op when mainApi undefined/null, breaking standalone use and early clicks
   • Solution: Always call onSelect first, then conditionally scroll mainApi if available
   • Impact: Enables standalone FilmStrip use and handles early clicks gracefully

3. Mouse-Wheel Scrolling

   • Problem: FilmStrip used Embla with overflow:hidden, removing mouse-wheel scrolling for desktop users
   • Solution: Added embla-carousel-wheel-gestures plugin
   • Impact: Restored desktop accessibility with proper mouse-wheel support

📚 Documentation

• 📖 Comprehensive Responsive Docs - Added detailed responsive behavior section to Album pattern docs
• 🎯 Breakpoint Documentation - All three breakpoints and their behaviors fully documented
• 💡 Feature Descriptions - Updated with Embla carousel integration details

📦 Dependencies

• ➕ Added: embla-carousel-wheel-gestures@^8.1.0 - Mouse-wheel support for carousels

🔧 Technical Details

New Props

• AlbumViewer.hideWhenEmpty?: boolean - Hide viewer completely when album has no photos
• AlbumViewer.emptyStateContent?: React.ReactNode - Custom empty state content
• FilmStrip.mainApi?: EmblaCarouselType | null - Main carousel API for synchronization

Breaking Changes

None - This release is fully backward compatible.

🚀 Installation

npm install @ainativekit/ui@0.13.0

🙏 Acknowledgments

Thanks to the Embla Carousel team for their excellent carousel library and comprehensive documentation!
Full Changelog: v0.12.0...v0.13.0

0.12.0

Changed

• Carousel: Default viewport padding is now 0 instead of var(--ai-spacing-10)
  • Padding is now opt-in instead of opt-out
  • Prevents layout issues in constrained spaces (e.g., 640px ChatGPT iframe)
  • Use viewportPadding="var(--ai-spacing-10)" to restore previous behavior

Fixed

• SummaryCard.Overlay: Height calculation now correctly includes padding
  • Added box-sizing: border-box so height={40} with padding={8} results in 40px total, not 56px
  • Overlay content now clips properly to image rounded corners with overflow: hidden

NPM: https://www.npmjs.com/package/@ainativekit/ui/v/0.12.0

0.11.0

✨ New Features

Light/Dark Mode Brand Colors

Brand colors now support theme-aware variants, allowing different colors for light and dark modes.

<ThemeProvider
  brandColors={{
    // Simple: Same for both modes
    primary: '#6366F1',
    
    // Theme-aware: Different per mode
    success: { light: '#059669', dark: '#34D399' },
    warning: { light: '#D97706', dark: '#FBBF24' },
    error: { light: '#DC2626', dark: '#F87171' },
  }}
>
  <App />
</ThemeProvider>

Key improvements:

• New BrandColorValue type: string | { light: string; dark: string }
• Backward compatible - existing string colors work unchanged
• Automatic CSS generation for both themes
• Validation caching prevents duplicate console warnings
• Comprehensive unit tests (697 total tests passing)

📚 Documentation

• Updated all README files with brand color customization examples
• Added CSS variable reference table in TOKEN_USAGE.md
• Replaced brand-specific colors with generic Tailwind CSS colors

🔧 Fixes

• Added missing ESLint TypeScript plugins to workspace root

Full Changelog: v0.10.0...v0.11.0

0.10.0

[0.10.0] - 2025-11-11

Changed

• Repository Rename: Renamed from ainativekit-ui to chatgpt-apps-sdk-ui for improved discoverability

  • GitHub repository now at AINativeKit/chatgpt-apps-sdk-ui
  • NPM package name remains @ainativekit/ui for backward compatibility
  • All documentation URLs updated to reflect new repository name

• Branding & Positioning: Updated to "AINativeKit - ChatGPT Apps SDK UI"

  • Emphasizes "ChatGPT Apps SDK" positioning for better SEO and target audience clarity
  • Subtitle: "The React UI library for ChatGPT Apps SDK"
  • Tagline: "Build beautiful ChatGPT Apps 10x faster"

• Documentation Enhancements:

  • Added "Who This Is For" section targeting ChatGPT Apps developers
  • Added comparison table showing value proposition (before/after scenarios)
  • Replaced Contributing section with "Support the Project" featuring stronger CTAs
  • Added SEO footer with keywords and descriptive paragraph for search optimization
  • Updated badges: added npm downloads and GitHub stars, removed TypeScript badge

• NPM Optimization:

  • Updated package description to emphasize "ChatGPT Apps SDK"
  • Added 5 new high-value keywords: chatgpt-apps-sdk, react-components, ui-components, chatgpt-ui, mcp

Note: This is a documentation and marketing release. No breaking changes to components or APIs.

0.9.0

[0.9.0] - 2025-11-10

Fixed

• Carousel: Fixed horizontal page overflow in width-constrained containers (Issue #17)
  • Replaced negative margin gap implementation with CSS gap property
  • Carousel now properly contains itself without requiring parent containers to use overflow-x: hidden
  • Self-contained component handles its own overflow correctly

0.8.0

[0.8.0] - 2025-11-09

Fixed

• SummaryCard: Button skeleton width now matches button width (Issue #15)
  • Skeleton buttons use the same width logic as real buttons
  • buttonFullWidth={false} → auto-width (min 120px) for both skeleton and button
  • buttonFullWidth={true} → full-width (100%) for both skeleton and button
  • buttonFullWidth={undefined} → variant-based (full for default, auto for flat)

Changed

• SummaryCard: Simplified buttonFullWidth behavior
  • buttonFullWidth={false}: Always auto-width (min 120px)
  • buttonFullWidth={true}: Always full-width (100%)
  • buttonFullWidth={undefined}: Full-width for default variant, auto-width for flat variant
  • Button width is now fixed and predictable - no responsive behavior
  • Simpler implementation using standard CSS

Technical Details

All components use simple, predictable viewport-based media queries for responsive behavior:

/* SummaryCard: Fixed button widths based on prop */
.buttonSection[data-full-width='false'] .button {
  width: auto;
  min-width: 120px;
}

/* List & AlbumViewer: Viewport-based responsive behavior */
@media (min-width: 640px) {
  /* Tablet/desktop styles */
}

0.7.0

[0.7.0] - 2025-11-08

Added

• Responsive Breakpoints: Standardized breakpoint system across all components
  • Added design tokens for breakpoints (640px tablet, 768px desktop, 1024px desktop-wide)
  • Comprehensive Storybook documentation with interactive demos
  • Live viewport width indicators for testing responsive behavior
  • ChatGPT Desktop widget strategy (768px width optimization)

Fixed

• SummaryCard: Button skeleton width now responsive in loading states
  • Use CSS custom property (--button-skeleton-width) for dynamic width calculation
  • Calculate width based on button text length (min 88px, max 200px)
  • Preserve media query behavior for responsive breakpoints
  • Loading state buttons now match data state widths at all breakpoints

Changed

• Responsive Breakpoints: Standardized media queries across components
  • List component: 640px (ensures desktop layout at 768px ChatGPT widget width)
  • Card/SummaryCard/Album: 768px (button auto-width at ChatGPT widget size)
  • FullscreenMap: 1024px (sidebar only on wide screens)
  • All breakpoints use hardcoded px values with inline comments
  • Design tokens serve as documentation reference

0.6.0

Fixed

• SummaryCard: Prevent layout shift during loading to data mode transition
  • Set explicit height on description skeleton wrapper to match description's rendered height
  • Normal mode: includes marginTop spacing (2px between lines)
  • Compact mode: accounts for webkit-line-clamp rendering difference (-2px adjustment)
  • Button skeleton width now matches actual button width for flat variant (auto-width 160px)

0.5.0

[0.5.0] - 2025-11-06

Added

• SummaryCard Enhancements:
  • Top overlay support with topOverlay prop and helper component
  • Configurable description lines with maxDescriptionLines prop
  • Loading skeleton states for better UX
  • Flat variant with edge-to-edge layout for immersive designs
• Map Component: Configurable scroll wheel zoom controls
• Carousel Component: Drag-free scrolling and trackpad support
• Typography System: Complete font weight token system with light variants

Changed

• Card Component: Reduced spacing for more compact design
• Card Loading UI: Improve loading UI to be responsive to smoothly transit to data state.
• SummaryCard: Consolidated DiscoveryCard functionality with improved structure

Fixed

• Pizza restaurant description and SummaryCard dimension adjustments

0.3.0

🎉 Release v0.3.0 Ready!
Version: 0.3.0
Tag: v0.3.0
Status: ✅ Built & Tagged

📊 Release Summary
Commits in this release:

1. e41a930 - chore: release v0.3.0
2. ece1f40 - feat: unify design tokens to use numeric keys throughout
3. c049d33 - feat: add useTheme hook for reactive theme detection
4. 2090e58 - docs: add TypeScript support section for ChatGPT Apps SDK types
5. ad37780 - fix: resolve React warning for aspectRatio prop on Card.Image

Issues Closed: #1, #2, #3, #4, #5, #6 Test Results:

• ✅ 548/548 tests passing
• ✅ TypeScript compiles without errors
• ✅ Build successful (1.26s)

Bundle Sizes:

• ESM: 300KB (gzipped: 81KB)
• CJS: 208KB (gzipped: 67KB)
• CSS: 96.7KB (gzipped: 18KB)