@mks2508/sidebar-headless 0.1.0 → 0.2.0

package/README.md

@@ -1,21 +1,22 @@
-# @mks2508/sidebar-headless
-
-Headless sidebar component for React with advanced animations, keyboard navigation, and full WAI-ARIA accessibility.
-
-[![npm version](https://img.shields.io/npm/v/@mks2508/sidebar-headless.svg)](https://www.npmjs.com/package/@mks2508/sidebar-headless)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-
+# @mks2508/sidebar-headless
+
+Headless sidebar component for React with advanced animations, keyboard navigation, and full WAI-ARIA accessibility.
+
+[![npm version](https://img.shields.io/npm/v/@mks2508/sidebar-headless.svg)](https://www.npmjs.com/package/@mks2508/sidebar-headless)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
 ## Features
 
 - 🎨 **Headless Architecture** - Complete control over styling and behavior
 - ⌨️ **Keyboard Navigation** - Full arrow key, Home/End support
 - ♿ **WAI-ARIA Compliant** - Full accessibility out of the box
 - 🎭 **Advanced Animations** - Fluid hover indicators, glassmorphism effects, 3D transforms
+- 📱 **Mobile-First Bottom Navigation** - iOS 26 Safari compatible, safe area support
 - 🎯 **TypeScript First** - Full type safety with comprehensive declarations
 - 🪶 **Lightweight** - Minimal dependencies (only clsx + tailwind-merge)
 - 🎨 **Dark/Light Mode** - Automatic theme support via CSS tokens
 - 🔧 **Highly Configurable** - Extensive customization options
-
+
 ## Installation
 
 ```bash
@@ -30,10 +31,10 @@ bun add @mks2508/sidebar-headless
 
 ### Peer Dependencies
 
-This package requires React 18+:
+This package requires React 18+ and Framer Motion:
 
 ```bash
-npm install react react-dom
+npm install react react-dom motion
 ```
 
 ### Optional Dependencies
@@ -43,7 +44,7 @@ For advanced liquid glass effects (optional):
 ```bash
 npm install @liquid-svg-glass/core @liquid-svg-glass/react
 ```
-
+
 ## Quick Start
 
 ```tsx
@@ -53,189 +54,719 @@ import {
   SidebarToggle,
   SidebarContent,
   SidebarItem,
-  SidebarIconLibrary
+  SidebarIconLibrary,
+  MobileBottomNav,
+  NavVariant,
+  NavItemState
 } from '@mks2508/sidebar-headless'
 import '@mks2508/sidebar-headless/styles.css'
 
 function App() {
   return (
-    <Sidebar defaultOpen={true}>
-      <SidebarNav>
-        <SidebarToggle iconLibrary={SidebarIconLibrary.LUCIDE} />
-        <SidebarContent>
-          <SidebarItem href="/" icon={<HomeIcon />} label="Home" />
-          <SidebarItem href="/settings" icon={<SettingsIcon />} label="Settings" />
-        </SidebarContent>
-      </SidebarNav>
-    </Sidebar>
+    <>
+      {/* Desktop Sidebar */}
+      <Sidebar defaultOpen={true}>
+        <SidebarNav>
+          <SidebarToggle iconLibrary={SidebarIconLibrary.LUCIDE} />
+          <SidebarContent>
+            <SidebarItem href="/" icon={<HomeIcon />} label="Home" />
+            <SidebarItem href="/settings" icon={<SettingsIcon />} label="Settings" />
+          </SidebarContent>
+        </SidebarNav>
+      </Sidebar>
+
+      {/* Mobile Bottom Navigation */}
+      <MobileBottomNav.Root variant={NavVariant.GLASS}>
+        <MobileBottomNav.NavList>
+          <MobileBottomNav.NavItem
+            icon={<HomeIcon />}
+            label="Home"
+            state={NavItemState.ACTIVE}
+          />
+          <MobileBottomNav.NavItem
+            icon={<SearchIcon />}
+            label="Search"
+          />
+        </MobileBottomNav.NavList>
+      </MobileBottomNav.Root>
+    </>
   )
 }
 ```
 
-## Core Components
+## Mobile Bottom Navigation
 
-### Sidebar (Root Provider)
+### MobileBottomNav (Mobile Navigation)
 
-The main container that provides context to all child components.
+A mobile-optimized bottom navigation component with slot architecture and iOS 26 compatibility.
 
 ```tsx
-<Sidebar
-  defaultOpen={true}
-  collapseMode="hide"
-  layoutBehaviour="floating"
+<MobileBottomNav.Root
+  variant={NavVariant.GLASS}
+  size={NavSize.MEDIUM}
+  visible={true}
 >
-  {/* ... */}
-</Sidebar>
+  <MobileBottomNav.NavList>
+    <MobileBottomNav.NavItem
+      icon={<HomeIcon />}
+      label="Home"
+      state={NavItemState.ACTIVE}
+      onClick={() => navigate('/home')}
+    />
+    <MobileBottomNav.NavItem
+      icon={<SearchIcon />}
+      label="Search"
+      badge={5}
+    />
+  </MobileBottomNav.NavList>
+</MobileBottomNav.Root>
 ```
 
-### SidebarNav
+### Navigation Variants
 
-Navigation container with event management.
+#### Glass Variant (iOS 26 Compatible)
+```tsx
+<MobileBottomNav.Root
+  variant={NavVariant.GLASS}
+  glassConfig={{
+    blur: BlurIntensity.MEDIUM,
+    opacity: 0.72,
+    borderOpacity: 0.18
+  }}
+/>
+```
+
+#### Solid Variant
+```tsx
+<MobileBottomNav.Root
+  variant={NavVariant.SOLID}
+/>
+```
 
+#### Headless Variant (Custom Styling)
 ```tsx
-<SidebarNav>
-  <SidebarToggle />
-  <SidebarContent>
-    {/* items */}
-  </SidebarContent>
-</SidebarNav>
+<MobileBottomNav.Root
+  variant={NavVariant.HEADLESS}
+  className="custom-nav-style"
+/>
 ```
 
-### SidebarItem
+### Mobile Bottom Nav Features
+
+- **iOS 26 Safari Compatible**: Fixes viewport bugs with address bar
+- **Safe Area Support**: Handles notched devices (iPhone X+)
+- **Glassmorphism Effects**: Beautiful blur and transparency
+- **Motion Animations**: Spring and tween animations with Framer Motion
+- **Accessibility**: Full WAI-ARIA support with keyboard navigation
+- **Badge Support**: Show notifications and counts
+- **Size Variants**: SMALL (56px), MEDIUM (72px), LARGE (88px)
+- **Label Positions**: BELOW, BESIDE, HIDDEN
+- **Touch Optimized**: WCAG 2.2 compliant touch targets (44px+)
 
-Individual navigation item with optional sub-content.
+### Mobile Navigation APIs
 
+#### Root Props
 ```tsx
-<SidebarItem
-  href="/dashboard"
-  icon={<DashboardIcon />}
-  label="Dashboard"
->
-  <SidebarSubContent title="Dashboard">
-    <SidebarSubLink href="/analytics">Analytics</SidebarSubLink>
-    <SidebarSubLink href="/reports">Reports</SidebarSubLink>
-  </SidebarSubContent>
-</SidebarItem>
+interface RootProps {
+  variant?: NavVariant
+  size?: NavSize
+  visible?: boolean
+  glassConfig?: GlassConfig
+  animationConfig?: AnimationConfig
+  rounded?: NavBorderRadius | number
+  full?: boolean
+  gap?: boolean
+  zIndex?: ZIndexLevel | number
+}
+```
+
+#### Nav Item Props
+```tsx
+interface NavItemProps {
+  icon: ReactNode
+  label: string
+  state?: NavItemState
+  onClick?: () => void
+  href?: string
+  badge?: number | boolean
+  disabled?: boolean
+  labelPosition?: LabelPosition
+  iconSize?: IconSize | number
+}
 ```
 
-## Configuration Options
+#### Mobile Utilities
+```tsx
+// Spacer to prevent content overlap
+<MobileBottomNav.Spacer size={NavSize.MEDIUM} />
+
+// iOS Safari fix utilities
+import { 
+  useIOSSafariFix, 
+  useIOSFixedReset, 
+  detectIOSVersion 
+} from '@mks2508/sidebar-headless'
+```
 
-### Collapse Modes
+### iOS Safari Compatibility Hooks
 
+#### `useIOSSafariFix()` - iOS Detection
 ```tsx
-import { SidebarCollapseMode } from '@mks2508/sidebar-headless'
+const { iosInfo, hasViewportBugs } = useIOSSafariFix({
+  enableScrollFix: true,
+  enableKeyboardFix: true,
+})
+
+interface IOSInfo {
+  isIOS: boolean
+  majorVersion: number | null
+  hasViewportBugs: boolean
+  device: 'iphone' | 'ipad' | 'unknown'
+  isStandalone: boolean
+}
+```
 
-// Collapse to icon-only width
-<Sidebar collapseMode={SidebarCollapseMode.COLLAPSE} />
+#### `useIOSFixedReset()` - Position Reset
+```tsx
+const ref = useRef<HTMLElement>(null)
+const { forceReset } = useIOSFixedReset(ref)
+
+// Call when keyboard dismisses or viewport changes
+useEffect(() => {
+  if (keyboardDismissed) {
+    forceReset()
+  }
+}, [keyboardDismissed])
+```
 
-// Hide completely
-<Sidebar collapseMode={SidebarCollapseMode.HIDE} />
+#### `detectIOSVersion()` - Version Detection
+```tsx
+const version = detectIOSVersion()
+// Returns: { major: 26, minor: 0, patch: 1, full: "26.0.1" }
 ```
 
-### Layout Behaviours
+### iOS 26 Safari Known Issues & Fixes
+
+#### Issues Fixed:
+- **Address bar shifting**: Fixed elements drift when URL bar hides
+- **Keyboard dismissal**: VisualViewport doesn't reset after keyboard
+- **100dvh gaps**: Dynamic viewport units don't account for floating tab bar
+
+#### Automatic Fixes Applied:
+- Hardware acceleration (`translateZ(0)`)
+- Scroll containment (`contain: layout style`)
+- Proper stacking context creation
+- CSS custom properties for safe areas
+- Responsive design with fallbacks
 
+#### Manual Fixes Available:
 ```tsx
-import { SidebarLayoutBehaviour } from '@mks2508/sidebar-headless'
+// Enable debug mode to see iOS detection
+<MobileBottomNav.Root 
+  data-ios-debug="true"
+  variant={NavVariant.GLASS}
+>
+```
+
+### Advanced Configuration
+
+#### Animation Configuration
+```tsx
+<MobileBottomNav.Root
+  animationConfig={{
+    type: AnimationType.SPRING,
+    pressScale: 0.95,
+    hoverScale: 1.05,
+    spring: {
+      stiffness: 400,
+      damping: 30,
+    },
+  }}
+/>
+```
 
-// Floating sidebar (doesn't push content)
-<Sidebar layoutBehaviour={SidebarLayoutBehaviour.FLOATING} />
+#### Glass Configuration
+```tsx
+<MobileBottomNav.Root
+  variant={NavVariant.GLASS}
+  glassConfig={{
+    blur: BlurIntensity.HEAVY, // or number (px)
+    opacity: 0.8,            // 0-1
+    saturation: 180,         // 100-200%
+    borderOpacity: 0.15,     // 0-1
+  }}
+/>
+```
 
-// Inline sidebar (pushes content)
-<Sidebar layoutBehaviour={SidebarLayoutBehaviour.INLINE} />
+#### Responsive Design
+```tsx
+// Size variants affect height and touch targets
+<MobileBottomNav.Root size={NavSize.SMALL}>  {/* 56px */}
+<MobileBottomNav.Root size={NavSize.MEDIUM}> {/* 72px */}
+<MobileBottomNav.Root size={NavSize.LARGE}> {/* 88px */}
+
+// Custom border radius
+<MobileBottomNav.Root rounded={1.5} /> {/* rem */}
+<MobileBottomNav.Root rounded={NavBorderRadius.ROUNDED} />
 ```
 
-### Custom Dimensions
+## Core Components
+
+### Sidebar (Root Provider)
+
+The main container that provides context to all child components.
+
+```tsx
+<Sidebar
+  defaultOpen={true}
+  collapseMode="hide"
+  layoutBehaviour="floating"
+>
+  {/* ... */}
+</Sidebar>
+```
+
+### SidebarNav
+
+Navigation container with event management.
+
+```tsx
+<SidebarNav>
+  <SidebarToggle />
+  <SidebarContent>
+    {/* items */}
+  </SidebarContent>
+</SidebarNav>
+```
+
+### SidebarItem
+
+Individual navigation item with optional sub-content.
+
+```tsx
+<SidebarItem
+  href="/dashboard"
+  icon={<DashboardIcon />}
+  label="Dashboard"
+>
+  <SidebarSubContent title="Dashboard">
+    <SidebarSubLink href="/analytics">Analytics</SidebarSubLink>
+    <SidebarSubLink href="/reports">Reports</SidebarSubLink>
+  </SidebarSubContent>
+</SidebarItem>
+```
+
+## Configuration Options
+
+### Collapse Modes
+
+```tsx
+import { SidebarCollapseMode } from '@mks2508/sidebar-headless'
+
+// Collapse to icon-only width
+<Sidebar collapseMode={SidebarCollapseMode.COLLAPSE} />
+
+// Hide completely
+<Sidebar collapseMode={SidebarCollapseMode.HIDE} />
+```
+
+### Layout Behaviours
+
+```tsx
+import { SidebarLayoutBehaviour } from '@mks2508/sidebar-headless'
+
+// Floating sidebar (doesn't push content)
+<Sidebar layoutBehaviour={SidebarLayoutBehaviour.FLOATING} />
+
+// Inline sidebar (pushes content)
+<Sidebar layoutBehaviour={SidebarLayoutBehaviour.INLINE} />
+```
+
+### Custom Dimensions
+
+```tsx
+<Sidebar
+  dimensions={{
+    collapsedWidth: "4rem",
+    expandedWidth: "18rem",
+    indicatorHeight: "3rem",
+    tooltipDistance: "16px"
+  }}
+/>
+```
+
+## Advanced Features
+
+### Fluid Indicators
+
+Enable glassmorphism-style hover indicators:
+
+```tsx
+<Sidebar
+  enableFluidIndicator={true}
+  liquidGlass={{
+    enableLiquidGlassV2: true,
+    enableChromaticAberration: true
+  }}
+/>
+```
+
+### Keyboard Navigation
+
+Built-in keyboard shortcuts:
+
+- **Arrow Up/Down**: Navigate between items
+- **Home**: Jump to first item
+- **End**: Jump to last item
+- **Enter**: Activate focused item
+
+### Render Props
+
+Access sidebar state via render props:
+
+```tsx
+<Sidebar>
+  {({ open, collapsed }) => (
+    <div>
+      <SidebarNav />
+      <p>Sidebar is {open ? 'open' : 'closed'}</p>
+    </div>
+  )}
+</Sidebar>
+```
+
+## Styling
+
+The sidebar uses shadcn-style CSS tokens for theming:
+
+```css
+:root {
+  --sidebar: oklch(98% 0 0);
+  --sidebar-foreground: oklch(20% 0 0);
+  --sidebar-primary: oklch(55% 0.2 250);
+  --sidebar-accent: oklch(95% 0.01 250);
+  --sidebar-border: oklch(90% 0.01 250);
+  --sidebar-ring: oklch(55% 0.2 250);
+}
+
+.dark {
+  --sidebar: oklch(17% 0 0);
+  --sidebar-foreground: oklch(90% 0 0);
+  /* ... */
+}
+```
+
+## TypeScript Support
+
+Full TypeScript support with comprehensive type definitions:
+
+```tsx
+import type {
+  SidebarProps,
+  SidebarItemProps,
+  SidebarContextValue
+} from '@mks2508/sidebar-headless'
+```
+
+## Performance & Troubleshooting
+
+### Performance Tips
+
+#### Glass Variant Performance
+```tsx
+// Reduce blur for better performance on older devices
+<MobileBottomNav.Root
+  variant={NavVariant.GLASS}
+  glassConfig={{
+    blur: BlurIntensity.LIGHT,  // 10px vs 20px
+    saturation: 150,             // Less saturation
+  }}
+/>
+```
 
+#### Animation Performance
 ```tsx
-<Sidebar
-  dimensions={{
-    collapsedWidth: "4rem",
-    expandedWidth: "18rem",
-    indicatorHeight: "3rem",
-    tooltipDistance: "16px"
+// Disable animations for reduced motion
+const prefersReduced = useMediaQuery('(prefers-reduced-motion: reduce)')
+
+<MobileBottomNav.Root
+  animationConfig={{
+    type: prefersReduced ? AnimationType.NONE : AnimationType.SPRING,
   }}
 />
 ```
 
-## Advanced Features
+#### Bundle Size Optimization
+```tsx
+// Import only what you need
+import { 
+  MobileBottomNav, 
+  NavVariant, 
+  NavItemState 
+} from '@mks2508/sidebar-headless'
+
+// Tree-shake CSS imports
+import '@mks2508/sidebar-headless/mobile-optimizations.css'
+```
+
+### Common Issues & Solutions
+
+#### iOS Safari Issues
+```tsx
+// Problem: Navigation shifts when scrolling
+// Solution: Enable scroll fix
+const { hasViewportBugs } = useIOSSafariFix({ 
+  enableScrollFix: true 
+})
+
+// Problem: Navigation offset after keyboard
+// Solution: Force reset
+const { forceReset } = useIOSFixedReset(navRef)
+useEffect(() => {
+  if (keyboardDismissed) forceReset()
+}, [keyboardDismissed])
+```
 
-### Fluid Indicators
+#### Touch Target Issues
+```tsx
+// Problem: Touch targets too small
+// Solution: Use larger size or custom styling
+<MobileBottomNav.Root size={NavSize.LARGE} /> // 88px
 
-Enable glassmorphism-style hover indicators:
+// Or custom minimum touch targets
+<MobileBottomNav.NavItem
+  className="min-touch-target" // CSS: min-width: 48px; min-height: 48px;
+/>
+```
 
+#### Animation Conflicts
 ```tsx
-<Sidebar
-  enableFluidIndicator={true}
-  liquidGlass={{
-    enableLiquidGlassV2: true,
-    enableChromaticAberration: true
+// Problem: Conflicts with parent animations
+// Solution: Use NONE animation type
+<MobileBottomNav.Root
+  animationConfig={{
+    type: AnimationType.NONE,
   }}
 />
 ```
 
-### Keyboard Navigation
+### Debug Mode
 
-Built-in keyboard shortcuts:
+Enable debug mode to see internal state and iOS detection:
+```tsx
+<MobileBottomNav.Root
+  data-ios-debug="true"
+  data-mobile-nav-debug="true"
+  variant={NavVariant.GLASS}
+>
+```
+
+## Browser Support
+
+- Chrome/Edge (latest)
+- Firefox (latest)
+- Safari (latest) - Full iOS 26 Safari compatibility
+- Modern browsers with ES2020 support
+
+## Mobile Compatibility
+
+- ✅ iOS 15+ (including iOS 26 Safari viewport fixes)
+- ✅ Android 8+
+- ✅ Safe area support (iPhone X+ notched devices)
+- ✅ Foldable devices support
+- ✅ Touch gesture navigation
+- ✅ Keyboard dismissal handling
+
+### Device-Specific Notes
+
+#### iPhone X and newer (with notch)
+- Safe area padding automatically applied via CSS `env()`
+- No additional configuration needed
+- Works with both portrait and landscape orientations
+
+#### iPad with Home Indicator
+- Bottom safe area respected automatically
+- Optimal touch targets for finger navigation
+
+#### Foldable Devices (Samsung Galaxy Fold, etc.)
+- Uses `horizontal-viewport-segments` CSS media query
+- Automatic layout adjustment for fold position
+
+#### Android Devices
+- Material Design navigation patterns compatible
+- Back gesture handling respected
+- Dynamic viewport units supported
+
+## API Reference
+
+### MobileBottomNav Components
+
+#### `MobileBottomNav.Root`
+Main container for mobile bottom navigation.
+
+**Props:** `RootProps`
+```tsx
+<MobileBottomNav.Root
+  variant={NavVariant.GLASS}
+  size={NavSize.MEDIUM}
+  visible={true}
+  glassConfig={glassConfig}
+  animationConfig={animationConfig}
+  rounded={NavBorderRadius.ROUNDED}
+  full={false}
+  gap={true}
+  zIndex={50}
+  aria-label="Main navigation"
+  data-testid="mobile-nav"
+  className="custom-nav"
+>
+  {children}
+</MobileBottomNav.Root>
+```
+
+#### `MobileBottomNav.NavList`
+Container for navigation items with flexbox layout.
+
+**Props:** `NavListProps`
+```tsx
+<MobileBottomNav.NavList
+  justify="around"  // "start" | "center" | "end" | "around" | "between"
+  gap={1}         // number (rem)
+  className="nav-list"
+>
+  {children}
+</MobileBottomNav.NavList>
+```
+
+#### `MobileBottomNav.NavItem`
+Individual navigation item with icon, label, and optional badge.
+
+**Props:** `NavItemProps`
+```tsx
+<MobileBottomNav.NavItem
+  icon={<HomeIcon />}
+  label="Home"
+  state={NavItemState.ACTIVE}
+  onClick={() => navigate('/home')}
+  href="/home"                    // Optional: renders as <a>
+  badge={5}                       // number | boolean
+  disabled={false}
+  labelPosition={LabelPosition.BELOW}
+  iconSize={IconSize.MEDIUM}
+  aria-label="Go to home"
+  data-testid="nav-item-home"
+  className="nav-item"
+/>
+```
 
-- **Arrow Up/Down**: Navigate between items
-- **Home**: Jump to first item
-- **End**: Jump to last item
-- **Enter**: Activate focused item
+#### `MobileBottomNav.Spacer`
+Invisible spacer to prevent content from being hidden under navigation.
 
-### Render Props
+**Props:** `SpacerProps`
+```tsx
+<MobileBottomNav.Spacer
+  size={NavSize.MEDIUM}
+  className="content-spacer"
+/>
+```
 
-Access sidebar state via render props:
+### Enums & Types
 
+#### `NavVariant`
 ```tsx
-<Sidebar>
-  {({ open, collapsed }) => (
-    <div>
-      <SidebarNav />
-      <p>Sidebar is {open ? 'open' : 'closed'}</p>
-    </div>
-  )}
-</Sidebar>
+enum NavVariant {
+  GLASS = "glass",      // Glassmorphism with blur
+  SOLID = "solid",      // Solid background
+  HEADLESS = "headless" // No default styles
+}
 ```
 
-## Styling
+#### `NavSize`
+```tsx
+enum NavSize {
+  SMALL = "sm",  // 56px height
+  MEDIUM = "md", // 72px height
+  LARGE = "lg"   // 88px height
+}
+```
 
-The sidebar uses shadcn-style CSS tokens for theming:
+#### `NavItemState`
+```tsx
+enum NavItemState {
+  INACTIVE = "inactive",
+  ACTIVE = "active",
+  DISABLED = "disabled"
+}
+```
 
-```css
-:root {
-  --sidebar: oklch(98% 0 0);
-  --sidebar-foreground: oklch(20% 0 0);
-  --sidebar-primary: oklch(55% 0.2 250);
-  --sidebar-accent: oklch(95% 0.01 250);
-  --sidebar-border: oklch(90% 0.01 250);
-  --sidebar-ring: oklch(55% 0.2 250);
+#### `LabelPosition`
+```tsx
+enum LabelPosition {
+  BELOW = "below",   // Icon above text
+  BESIDE = "beside",  // Icon beside text
+  HIDDEN = "hidden"   // Icon only
 }
+```
 
-.dark {
-  --sidebar: oklch(17% 0 0);
-  --sidebar-foreground: oklch(90% 0 0);
-  /* ... */
+#### `IconSize`
+```tsx
+enum IconSize {
+  SMALL = 18,   // 18px
+  MEDIUM = 24,  // 24px
+  LARGE = 28    // 28px
 }
 ```
 
-## TypeScript Support
+#### `BlurIntensity`
+```tsx
+enum BlurIntensity {
+  LIGHT = 10,   // 10px blur
+  MEDIUM = 20,  // 20px blur
+  HEAVY = 30    // 30px blur
+}
+```
 
-Full TypeScript support with comprehensive type definitions:
+### Configuration Interfaces
 
+#### `GlassConfig`
 ```tsx
-import type {
-  SidebarProps,
-  SidebarItemProps,
-  SidebarContextValue
-} from '@mks2508/sidebar-headless'
+interface GlassConfig {
+  blur: BlurIntensity | number     // Blur amount in pixels
+  saturation: number                // 100-200%
+  opacity: number                  // 0-1
+  borderOpacity: number             // 0-1
+}
 ```
 
-## Browser Support
+#### `AnimationConfig`
+```tsx
+interface AnimationConfig {
+  type: AnimationType              // SPRING | TWEEN | NONE
+  pressScale?: number              // Scale when pressed (0-1)
+  hoverScale?: number              // Scale when hovered (>1)
+  spring?: SpringConfig            // Spring physics
+  tween?: TweenConfig              // Tween animation
+}
 
-- Chrome/Edge (latest)
-- Firefox (latest)
-- Safari (latest)
-- Modern browsers with ES2020 support
+interface SpringConfig {
+  stiffness?: number               // Spring stiffness (100-1000)
+  damping?: number                 // Spring damping (10-100)
+}
+
+interface TweenConfig {
+  duration?: number                // Duration in seconds (0.1-2)
+  ease?: string                   // CSS easing function
+}
+```
+
+#### `IOSSafariFixConfig`
+```tsx
+interface IOSSafariFixConfig {
+  enableScrollFix?: boolean        // Fix scroll-induced drift
+  enableKeyboardFix?: boolean     // Fix keyboard dismissal issues
+  debug?: boolean                // Enable debug logging
+}
+```
 
 ## License
 
@@ -249,3 +780,4 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 
 - [GitHub Repository](https://github.com/mks2508/sidebar-headless)
 - [Report Issues](https://github.com/mks2508/sidebar-headless/issues)
+- [npm Package](https://npmjs.com/package/@mks2508/sidebar-headless)