@digilogiclabs/saas-factory-ui 1.0.1 → 1.2.0

package/README.md

@@ -1,1004 +1,1072 @@
-# @digilogiclabs/saas-factory-ui
-
-A comprehensive cross-platform UI component library built for both **Next.js web applications** and **React Native/Expo mobile applications**. This package provides a complete set of accessible, mobile-optimized components with consistent design across platforms.
-
-## 🌟 Features
-
-- 🎨 **Cross-Platform Design System**
-  - Consistent components for web and mobile
-  - Platform-optimized implementations
-  - Shared design tokens and theming
-- 🌐 **Web Support**
-  - Built with React, Tailwind CSS, Radix UI, and Framer Motion
-  - Dark mode support
-  - Responsive by default
-- 📱 **React Native Support**
-  - Native mobile components with Expo compatibility
-  - Platform-specific optimizations
-  - Haptic feedback integration
-- ♿️ **Accessibility First**
-  - WCAG 2.2 AA compliant components
-  - Screen reader support
-  - Keyboard navigation and touch alternatives
-- ⚡ **Performance Optimized**
-  - Advanced mobile interactions with gesture recognition
-  - Lazy loading and progressive image optimization
-  - Virtual scrolling for large datasets
-  - Network-aware content delivery
-- 🌐 **Offline Support**
-  - Comprehensive caching strategies
-  - Offline-first component architecture
-  - Network detection and graceful degradation
-- 🎯 **Developer Experience**
-  - Full TypeScript support
-  - Tree-shakeable exports
-  - Comprehensive documentation
-  - Optimized bundle sizes
-
-## 📦 Installation
-
-```bash
-npm install @digilogiclabs/saas-factory-ui
-```
-
-## 🚀 Platform Requirements
-
-### Web Applications
-- Node.js >=20.0.0
-- Next.js 15+ or React 19+
-- Tailwind CSS 3.4 or higher
-- TypeScript (recommended)
-
-### React Native Applications
-- Node.js >=20.0.0
-- React Native 0.70 or higher
-- Expo SDK 49 or higher
-- React 19 or higher
-
-## 🌐 Web Setup (Next.js)
-
-### 1. Install Dependencies
-
-```bash
-npm install @digilogiclabs/saas-factory-ui
-npm install -D tailwindcss postcss autoprefixer
-npx tailwindcss init -p
-```
-
-### 2. Configure Tailwind CSS
-
-Update your `tailwind.config.js` to include the component library:
-
-```js
-// tailwind.config.js
-/** @type {import('tailwindcss').Config} */
-export default {
-  content: [
-    "./src/**/*.{js,ts,jsx,tsx}",
-    "./app/**/*.{js,ts,jsx,tsx}",
-    "./pages/**/*.{js,ts,jsx,tsx}",
-    "./components/**/*.{js,ts,jsx,tsx}",
-    // 🚨 IMPORTANT: Include the UI package
-    "./node_modules/@digilogiclabs/saas-factory-ui/**/*.{js,ts,jsx,tsx}",
-  ],
-  theme: {
-    extend: {},
-  },
-  plugins: [],
-}
-```
-
-### 3. Import Styles (REQUIRED)
-
-Add the CSS import to your root layout or app file:
-
-```tsx
-// app/layout.tsx (Next.js 13+) or pages/_app.tsx (Next.js 12)
-import '@digilogiclabs/saas-factory-ui/styles.css';
-import './globals.css'; // Your app styles
-```
-
-### 4. Use Components
-
-```tsx
-import { 
-  Button, 
-  Card, 
-  Container,
-  PageTransition,
-  SwipeableCard,
-  LazyImage 
-} from '@digilogiclabs/saas-factory-ui';
-
-export default function HomePage() {
-  return (
-    <PageTransition type="slide" direction="horizontal">
-      <Container>
-        <Card className="p-6">
-          <h1 className="text-2xl font-bold mb-4">Welcome to Web</h1>
-          <LazyImage 
-            src="/hero-image.jpg" 
-            alt="Hero image"
-            className="w-full h-64 object-cover rounded-lg mb-4"
-            placeholder="blur"
-            webpSupport={true}
-          />
-          <Button variant="default" size="lg">
-            Get Started
-          </Button>
-        </Card>
-      </Container>
-    </PageTransition>
-  );
-}
-```
-
-## 📱 React Native Setup
-
-### 1. Install Dependencies
-
-```bash
-npm install @digilogiclabs/saas-factory-ui
-# Required for advanced features
-npm install @react-native-community/netinfo
-npm install @react-native-async-storage/async-storage
-npm install expo-haptics
-```
-
-### 2. Import Native Components
-
-```tsx
-import { 
-  NativeButton, 
-  NativeContainer, 
-  NativeCard,
-  NativePageTransition,
-  NativeSwipeableCard,
-  NativeLazyImage
-} from '@digilogiclabs/saas-factory-ui/native';
-import { Text } from 'react-native';
-
-export default function App() {
-  return (
-    <NativePageTransition type="slide" direction="horizontal">
-      <NativeContainer style={{ flex: 1, padding: 20 }}>
-        <NativeCard style={{ padding: 20 }}>
-          <Text style={{ fontSize: 20, fontWeight: 'bold', marginBottom: 16 }}>
-            Welcome to Mobile
-          </Text>
-          <NativeLazyImage 
-            source={{ uri: 'https://example.com/image.jpg' }}
-            style={{ width: '100%', height: 200, borderRadius: 8, marginBottom: 16 }}
-            placeholder="skeleton"
-          />
-          <NativeButton 
-            variant="default" 
-            size="lg" 
-            onPress={() => console.log('Pressed')}
-          >
-            Get Started
-          </NativeButton>
-        </NativeCard>
-      </NativeContainer>
-    </NativePageTransition>
-  );
-}
-```
-
-## 📚 Available Components
-
-### ✅ Core Components (v0.13.0)
-
-| Component | Web | Native | Description |
-|-----------|-----|--------|-------------|
-| **Layout & Structure** | | | |
-| `Container` | ✅ | ✅ | Responsive layout containers |
-| `Grid` | ✅ | ✅ | Flexible grid layouts |
-| `Section` | ✅ | ✅ | Semantic page sections |
-| `Card` | ✅ | ✅ | Content containers with elevation |
-| **Interactive Elements** | | | |
-| `Button` | ✅ | ✅ | Primary action buttons with variants |
-| `SwipeableCard` | ✅ | ✅ | **NEW** Touch-friendly swipe gestures with haptic feedback |
-| **Advanced Mobile Interactions** | | | |
-| `PageTransition` | ✅ | ✅ | **NEW** Smooth page transitions with multiple animation types |
-| `PullToRefresh` | ✅ | ✅ | **NEW** Native pull-to-refresh functionality |
-| **Performance & Media** | | | |
-| `LazyImage` | ✅ | ✅ | **NEW** Intelligent lazy loading with WebP support |
-| `ProgressiveImage` | ✅ | ✅ | **NEW** Quality-aware progressive image loading |
-| `VirtualScrollList` | ✅ | ✅ | **NEW** Memory-efficient virtual scrolling |
-| **Network & Offline** | | | |
-| `NetworkAwareContent` | ✅ | ✅ | **NEW** Smart content delivery based on network conditions |
-| `OfflineWrapper` | ✅ | ✅ | **NEW** Comprehensive offline support with caching |
-
-### 🌐 Web-Specific Components
-
-- `Alert` - Contextual feedback messages
-- `Avatar` - User profile pictures and initials
-- `Badge` - Status indicators and counts
-- `Checkbox` - Boolean input controls
-- `DataTable` - Sortable data tables with pagination support
-- `Dialog` - Modal dialogs and overlays
-- `DropdownMenu` - Contextual action menus
-- `Form` - Form validation and state management
-- `Input` - Text input fields with validation
-- `Label` - Accessible form labels
-- `Modal` - Simple modal wrapper component
-- `Pagination` - Data navigation with page controls
-- `Progress` - Progress indicators and loading bars
-- `Select` - Dropdown selection controls
-- `Skeleton` - Loading state placeholders
-- `Tabs` - Tabbed content navigation
-- `Toast` - Notification messages
-- `Tooltip` - Contextual help and information
-- `AudioPlayer` - Advanced audio playback with playlists
-- `VideoPlayer` - Feature-rich video player
-- `AudioUploader` - Audio file upload with preview
-- `FileUpload` - Drag-and-drop file uploads
-- `Waveform` - Audio waveform visualization
-
-### 📱 Native-Specific Components
-
-- `SafeContainer` - Safe area aware container
-- `TouchableCard` - Pressable card component
-
-## 🆕 NEW v0.21.0: Layout & Navigation System
-
-### Complete Application Structure
-A comprehensive system providing everything needed for modern SaaS applications:
-
-#### 🏗️ App Shell Components
-
-| Component | Web | Native | Description |
-|-----------|-----|--------|-------------|
-| `AppShell` | ✅ | ✅ | Complete application layout orchestration |
-| `Header` | ✅ | ✅ | Top navigation with user menu and actions |
-| `Sidebar` | ✅ | - | Collapsible navigation sidebar (web) |
-| `Drawer` | - | ✅ | Slide-out navigation drawer (mobile) |
-| `Breadcrumbs` | ✅ | - | Hierarchical navigation breadcrumbs |
-
-#### 🧭 Navigation Components
-
-| Component | Web | Native | Description |
-|-----------|-----|--------|-------------|
-| `Tabs` | ✅ | ✅ | Feature-rich tabbed navigation |
-| `BottomTabBar` | - | ✅ | Mobile-optimized bottom tab navigation |
-| `Stepper` | ✅ | ✅ | Step-by-step process visualization |
-| `Pagination` | ✅ | ✅ | Data navigation with page controls |
-| `CommandPalette` | ✅ | - | Keyboard-driven command palette (Cmd+K) |
-
-#### 🎯 Tour & Onboarding
-
-| Component | Web | Native | Description |
-|-----------|-----|--------|-------------|
-| `Tour` | ✅ | ✅ | Interactive guided tours with spotlights |
-| `Onboarding` | ✅ | ✅ | Multi-step onboarding with progress tracking |
-| `Tooltip` | ✅ | ✅ | Contextual feature highlights |
-| `WelcomeModal` | ✅ | ✅ | Welcome screens with feature showcase |
-| `FeatureHighlight` | ✅ | - | Animated feature callouts with pulse effects |
-
-#### 📋 Layout Templates
-
-| Template | Web | Native | Description |
-|----------|-----|--------|-------------|
-| `DashboardLayout` | ✅ | ✅ | Complete dashboard with navigation |
-| `AuthLayout` | ✅ | ✅ | Authentication pages with features showcase |
-| `SettingsLayout` | ✅ | ✅ | Settings pages with tabbed navigation |
-
-### Usage Examples
-
-#### Web Dashboard with Command Palette
-```tsx
-import { 
-  DashboardLayout, 
-  CommandPalette, 
-  useCommandPalette 
-} from '@digilogiclabs/saas-factory-ui';
-
-export default function Dashboard() {
-  const commands = [
-    {
-      id: 'nav',
-      label: 'Navigation',
-      items: [
-        { id: 'dashboard', label: 'Go to Dashboard', action: () => router.push('/') },
-        { id: 'settings', label: 'Open Settings', action: () => router.push('/settings') },
-      ]
-    }
-  ];
-
-  const { isOpen, toggle } = useCommandPalette({
-    commands,
-    keyboardShortcut: 'cmd+k'
-  });
-
-  return (
-    <DashboardLayout>
-      <div className="p-6">
-        <h1>Dashboard Content</h1>
-        <p>Press Cmd+K to open command palette</p>
-      </div>
-      
-      <CommandPalette
-        open={isOpen}
-        onOpenChange={toggle}
-        commands={commands}
-      />
-    </DashboardLayout>
-  );
-}
-```
-
-#### Native App with Bottom Tabs
-```tsx
-import { 
-  DashboardLayout, 
-  Tour,
-  useTour 
-} from '@digilogiclabs/saas-factory-ui/native';
-
-export default function MobileApp() {
-  const tourSteps = [
-    {
-      id: 'welcome',
-      title: 'Welcome!',
-      content: 'Let me show you around',
-      target: '#main-content'
-    }
-  ];
-
-  const { isOpen, start } = useTour({ 
-    steps: tourSteps,
-    localStorage: { key: 'app-tour' }
-  });
-
-  return (
-    <DashboardLayout
-      showBottomTabs={true}
-      bottomTabs={[
-        { id: 'home', label: 'Home', icon: '🏠' },
-        { id: 'search', label: 'Search', icon: '🔍' },
-        { id: 'profile', label: 'Profile', icon: '👤' },
-      ]}
-    >
-      <ScrollView>
-        <Text style={styles.title}>Mobile Dashboard</Text>
-        <TouchableOpacity onPress={start}>
-          <Text>Start Tour</Text>
-        </TouchableOpacity>
-      </ScrollView>
-
-      <Tour
-        steps={tourSteps}
-        isOpen={isOpen}
-        onRequestClose={() => {}}
-      />
-    </DashboardLayout>
-  );
-}
-```
-
-### 🔧 Available Hooks
-
-#### Cross-Platform Hooks
-- `useMounted` - Component mount status detection
-- `useNetworkInfo` - **NEW** Network connection monitoring
-- `useOfflineState` - **NEW** Online/offline status detection
-- `useCache` - **NEW** Persistent caching utilities
-- `useTour` - **NEW** Tour state management with localStorage persistence
-- `useOnboarding` - **NEW** Multi-step onboarding flow management
-
-#### Web-Only Hooks
-- `useMediaQuery` - Responsive breakpoint detection
-- `useLockBody` - Body scroll lock for modals
-- `useCommandPalette` - **NEW** Command palette state management
-- `useResponsive` - **NEW** Advanced responsive breakpoint detection
-
-#### Native-Only Hooks
-- `useDimensions` - Screen dimensions and orientation
-- `useKeyboard` - Keyboard visibility and height
-
-## 🚀 New v0.13.0 Features
-
-### Advanced Mobile Interactions
-
-#### PageTransition
-Smooth, customizable page transitions with multiple animation types:
-
-```tsx
-// Web
-import { PageTransition } from '@digilogiclabs/saas-factory-ui';
-
-<PageTransition 
-  type="slide" 
-  direction="horizontal" 
-  duration={300}
-  key={pageKey}
->
-  <YourPageContent />
-</PageTransition>
-
-// Supported types: 'slide', 'fade', 'scale', 'flip', 'elastic'
-// Directions: 'horizontal', 'vertical', 'up', 'down', 'left', 'right'
-```
-
-#### SwipeableCard
-Touch-friendly cards with swipe actions and haptic feedback:
-
-```tsx
-// Web
-import { SwipeableCard } from '@digilogiclabs/saas-factory-ui';
-
-<SwipeableCard
-  leftActions={[{
-    id: 'archive',
-    label: 'Archive',
-    backgroundColor: '#10B981',
-    onAction: () => archiveItem()
-  }]}
-  rightActions={[{
-    id: 'delete',
-    label: 'Delete',
-    backgroundColor: '#EF4444',
-    onAction: () => deleteItem()
-  }]}
-  hapticFeedback={true}
-  threshold={80}
->
-  <div className="p-4">
-    <h3>Swipe me left or right!</h3>
-  </div>
-</SwipeableCard>
-```
-
-#### PullToRefresh
-Native pull-to-refresh functionality:
-
-```tsx
-// Web
-import { PullToRefresh } from '@digilogiclabs/saas-factory-ui';
-
-<PullToRefresh
-  onRefresh={async () => {
-    await fetchFreshData();
-  }}
-  threshold={60}
-  hapticFeedback={true}
->
-  <YourScrollableContent />
-</PullToRefresh>
-```
-
-### Performance Optimization
-
-#### LazyImage
-Intelligent lazy loading with modern format support:
-
-```tsx
-// Web
-import { LazyImage } from '@digilogiclabs/saas-factory-ui';
-
-<LazyImage
-  src="/large-image.jpg"
-  alt="Description"
-  placeholder="blur"
-  webpSupport={true}
-  mobileOptimization={{
-    quality: 75,
-    format: "webp",
-    sizes: "(max-width: 768px) 100vw, 50vw"
-  }}
-  loading="lazy"
-  fetchPriority="high"
-  retryAttempts={3}
-/>
-```
-
-#### ProgressiveImage
-Quality-aware progressive loading:
-
-```tsx
-// Web
-import { ProgressiveImage } from '@digilogiclabs/saas-factory-ui';
-
-<ProgressiveImage
-  lowQualitySrc="/thumbnail.jpg"
-  highQualitySrc="/full-quality.jpg"
-  alt="Progressive image"
-  mobileStrategy="blur-up"
-  transition="fade"
-  networkAware={true}
-/>
-```
-
-#### VirtualScrollList
-Memory-efficient virtual scrolling for large datasets:
-
-```tsx
-// Web
-import { VirtualScrollList } from '@digilogiclabs/saas-factory-ui';
-
-<VirtualScrollList
-  items={largeDataArray}
-  itemHeight={80}
-  containerHeight={400}
-  renderItem={(item, index) => (
-    <div key={index} className="p-4 border-b">
-      {item.name}
-    </div>
-  )}
-  onEndReached={() => loadMore()}
-  mobileOptimized={true}
-  overscan={5}
-/>
-```
-
-### Network & Offline Support
-
-#### NetworkAwareContent
-Smart content delivery based on connection quality:
-
-```tsx
-// Web
-import { NetworkAwareContent } from '@digilogiclabs/saas-factory-ui';
-
-<NetworkAwareContent
-  showOnFast={<HighQualityContent />}
-  showOnSlow={<LightweightContent />}
-  showOnOffline={<OfflineMessage />}
-  respectSaveData={true}
->
-  <DefaultContent />
-</NetworkAwareContent>
-```
-
-#### OfflineWrapper
-Comprehensive offline support with caching:
-
-```tsx
-// Web
-import { OfflineWrapper } from '@digilogiclabs/saas-factory-ui';
-
-<OfflineWrapper
-  cacheStrategy="stale-while-revalidate"
-  cacheKey="user-data"
-  cacheDuration={3600000} // 1 hour
-  showOfflineIndicator={true}
-  retryOnReconnect={true}
->
-  <YourOnlineContent />
-</OfflineWrapper>
-```
-
-## 🎨 Advanced Usage Examples
-
-### Mobile-Optimized Dashboard
-
-```tsx
-import { 
-  PageTransition,
-  NetworkAwareContent,
-  VirtualScrollList,
-  PullToRefresh,
-  LazyImage
-} from '@digilogiclabs/saas-factory-ui';
-
-function MobileDashboard() {
-  const [data, setData] = useState([]);
-  const [refreshing, setRefreshing] = useState(false);
-
-  const handleRefresh = async () => {
-    setRefreshing(true);
-    await fetchFreshData();
-    setRefreshing(false);
-  };
-
-  return (
-    <PageTransition type="slide" direction="up">
-      <div className="h-screen flex flex-col">
-        <NetworkAwareContent
-          showOnSlow={<SimpleDashboardHeader />}
-          showOnFast={<RichDashboardHeader />}
-        >
-          <DashboardHeader />
-        </NetworkAwareContent>
-
-        <PullToRefresh 
-          onRefresh={handleRefresh}
-          className="flex-1"
-        >
-          <VirtualScrollList
-            items={data}
-            itemHeight={120}
-            renderItem={(item, index) => (
-              <div className="p-4 border-b">
-                <div className="flex items-center space-x-3">
-                  <LazyImage
-                    src={item.avatar}
-                    alt={item.name}
-                    className="w-12 h-12 rounded-full"
-                    placeholder="blur"
-                  />
-                  <div>
-                    <h3 className="font-semibold">{item.name}</h3>
-                    <p className="text-sm text-gray-500">{item.status}</p>
-                  </div>
-                </div>
-              </div>
-            )}
-            onEndReached={loadMoreData}
-            mobileOptimized={true}
-          />
-        </PullToRefresh>
-      </div>
-    </PageTransition>
-  );
-}
-```
-
-### Swipeable Card List with Actions
-
-```tsx
-import { SwipeableCard, LazyImage, Button } from '@digilogiclabs/saas-factory-ui';
-
-function MessageList({ messages }) {
-  return (
-    <div className="space-y-2">
-      {messages.map((message) => (
-        <SwipeableCard
-          key={message.id}
-          leftActions={[{
-            id: 'archive',
-            label: 'Archive',
-            icon: '📁',
-            backgroundColor: '#10B981',
-            onAction: () => archiveMessage(message.id)
-          }]}
-          rightActions={[{
-            id: 'delete',
-            label: 'Delete',
-            icon: '🗑️',
-            backgroundColor: '#EF4444',
-            onAction: () => deleteMessage(message.id)
-          }]}
-          threshold={100}
-          hapticFeedback={true}
-        >
-          <div className="flex items-center p-4 bg-white rounded-lg shadow">
-            <LazyImage
-              src={message.sender.avatar}
-              alt={message.sender.name}
-              className="w-12 h-12 rounded-full mr-3"
-              placeholder="skeleton"
-            />
-            <div className="flex-1">
-              <h4 className="font-semibold">{message.sender.name}</h4>
-              <p className="text-gray-600 truncate">{message.preview}</p>
-            </div>
-            <span className="text-xs text-gray-400">{message.time}</span>
-          </div>
-        </SwipeableCard>
-      ))}
-    </div>
-  );
-}
-```
-
-### Progressive Image Gallery
-
-```tsx
-import { ProgressiveImage, VirtualScrollList } from '@digilogiclabs/saas-factory-ui';
-
-function ImageGallery({ images }) {
-  return (
-    <VirtualScrollList
-      items={images}
-      itemHeight={300}
-      renderItem={(image, index) => (
-        <div className="p-2">
-          <ProgressiveImage
-            lowQualitySrc={image.thumbnail}
-            highQualitySrc={image.fullSize}
-            alt={image.description}
-            className="w-full h-64 object-cover rounded-lg"
-            mobileStrategy="blur-up"
-            transition="crossfade"
-            networkAware={true}
-          />
-        </div>
-      )}
-      containerHeight={600}
-      mobileOptimized={true}
-    />
-  );
-}
-```
-
-## 🌐 Network-Aware Development
-
-### Connection-Based Content Delivery
-
-```tsx
-import { NetworkAwareContent, useNetworkInfo } from '@digilogiclabs/saas-factory-ui';
-
-function AdaptiveApp() {
-  const networkInfo = useNetworkInfo();
-
-  return (
-    <div>
-      <NetworkAwareContent
-        fastThreshold={['4g', 'fast']}
-        slowThreshold={['2g', '3g', 'slow']}
-        showOnFast={
-          <div>
-            <HighResolutionImages />
-            <AnimatedComponents />
-            <VideoContent />
-          </div>
-        }
-        showOnSlow={
-          <div>
-            <CompressedImages />
-            <StaticComponents />
-            <TextContent />
-          </div>
-        }
-        showOnOffline={<OfflineFallback />}
-        respectSaveData={true}
-        onNetworkChange={(info) => {
-          console.log('Network changed:', info);
-          // Adjust app behavior based on network
-        }}
-      >
-        <DefaultContent />
-      </NetworkAwareContent>
-    </div>
-  );
-}
-```
-
-### Offline-First Architecture
-
-```tsx
-import { OfflineWrapper, useOfflineState, useCache } from '@digilogiclabs/saas-factory-ui';
-
-function OfflineCapableComponent() {
-  const isOnline = useOfflineState();
-  const { get, set } = useCache('user-preferences', 3600000);
-
-  return (
-    <OfflineWrapper
-      cacheStrategy="stale-while-revalidate"
-      cacheKey="dashboard-data"
-      showOfflineIndicator={true}
-      enableServiceWorker={true}
-      onOffline={() => console.log('Gone offline')}
-      onOnline={() => console.log('Back online')}
-      fallback={
-        <div className="text-center p-8">
-          <h3>You're offline</h3>
-          <p>Some features may not be available</p>
-        </div>
-      }
-    >
-      <div>
-        <h2>Dashboard {isOnline ? '🟢' : '🔴'}</h2>
-        <DashboardContent />
-      </div>
-    </OfflineWrapper>
-  );
-}
-```
-
-## 🎨 Theming & Styling
-
-### Custom Theme Configuration
-
-Create a custom theme by extending the default CSS variables:
-
-```css
-/* custom-theme.css */
-:root {
-  /* Primary colors */
-  --primary: 262 83% 58%;        /* Purple */
-  --primary-foreground: 0 0% 98%;
-
-  /* Secondary colors */
-  --secondary: 220 14% 96%;
-  --secondary-foreground: 220 9% 46%;
-
-  /* Accent colors */
-  --accent: 262 83% 58%;
-  --accent-foreground: 0 0% 98%;
-
-  /* Custom border radius */
-  --radius: 0.75rem;
-}
-
-/* Dark mode overrides */
-.dark {
-  --primary: 262 83% 58%;
-  --primary-foreground: 0 0% 98%;
-  --background: 224 71% 4%;
-  --foreground: 213 31% 91%;
-}
-```
-
-## 📝 Migration Guide
-
-### From v0.12.x to v0.13.0
-
-#### New Dependencies (Optional)
-For full functionality, install additional dependencies:
-
-```bash
-# For React Native projects
-npm install @react-native-community/netinfo
-npm install @react-native-async-storage/async-storage
-npm install expo-haptics
-
-# These are optional and only needed if using specific components
-```
-
-#### Breaking Changes
-- None. All new components are additive.
-
-#### New Features Available
-- Advanced mobile interactions (PageTransition, SwipeableCard, PullToRefresh)
-- Performance optimization components (LazyImage, ProgressiveImage, VirtualScrollList)
-- Network and offline support (NetworkAwareContent, OfflineWrapper)
-- New hooks (useNetworkInfo, useOfflineState, useCache)
-
-## 🏗 Development Status
-
-### ✅ Completed (v0.13.0) - Mobile-First Optimization Release
-
-**Advanced Mobile Interactions**
-- ✅ PageTransition - Smooth page transitions with gesture support
-- ✅ SwipeableCard - Touch-friendly swipe gestures with haptic feedback
-- ✅ PullToRefresh - Native pull-to-refresh functionality
-
-**Performance Optimization**
-- ✅ LazyImage - Intelligent lazy loading with WebP support
-- ✅ ProgressiveImage - Quality-aware progressive image loading
-- ✅ VirtualScrollList - Memory-efficient virtual scrolling
-
-**Network & Offline Support**
-- ✅ NetworkAwareContent - Smart content delivery based on network conditions
-- ✅ OfflineWrapper - Comprehensive offline support with caching strategies
-- ✅ Network detection hooks and utilities
-
-**Developer Experience**
-- ✅ Cross-platform architecture (Web + React Native)
-- ✅ Full TypeScript support with platform-specific types
-- ✅ Accessibility-first design (WCAG 2.2 AA compliant)
-- ✅ Tree-shakeable exports and optimized bundle sizes
-- ✅ Comprehensive documentation and examples
-
-### 🚧 Coming Next (v0.14.0)
-
-**Enhanced Authentication Components**
-- 🔄 MobileAuthForm with biometric authentication
-- 🔄 MobileUserMenu with gesture-enabled navigation
-- 🔄 Social login optimizations
-
-**Mobile Payment Optimization**
-- 🔄 MobileCheckout with Apple Pay/Google Pay
-- 🔄 MobileBilling dashboard
-- 🔄 MobilePricing with comparison tables
-
-### 📋 Future Roadmap
-
-- Advanced UI components (BottomSheet, InfiniteScroll, FAB)
-- Enhanced theming system with brand color extraction
-- Real-time components with WebSocket integration
-- PWA optimization features
-- Advanced accessibility features
-- Comprehensive Storybook documentation
-
-## 🚀 Performance Metrics
-
-### Bundle Sizes (v0.13.0)
-- **Main Bundle**: 270KB ESM (295KB CJS) + 73KB CSS
-- **Web Bundle**: 295KB optimized for web platforms
-- **Native Bundle**: 18KB optimized for React Native
-- **Tree-shakeable**: Import only what you need
-
-### Performance Targets ✅
-- **Bundle Size**: < 250KB gzipped ✅ (Optimized)
-- **Load Time**: < 3s on 3G networks ✅
-- **First Paint**: < 1.5s ✅
-- **Interaction Ready**: < 2.5s ✅
-- **Accessibility Score**: 95+ Lighthouse ✅
-
-## 🔧 Development & Contributing
-
-### Local Development
-
-```bash
-# Clone the repository
-git clone https://github.com/DigiLogicLabs/saas-factory-ui
-cd saas-factory-ui
-
-# Install dependencies
-npm install
-
-# Build the package
-npm run build
-
-# Run tests
-npm run test
-
-# Type check
-npm run type-check
-
-# Lint
-npm run lint
-
-# Link for local testing
-npm link
-
-# In your test project
-npm link @digilogiclabs/saas-factory-ui
-```
-
-### Testing Your Changes
-
-1. Build the package: `npm run build`
-2. Test in a Next.js app with mobile interactions
-3. Test in a React Native/Expo app
-4. Verify TypeScript types work correctly
-5. Test offline/online scenarios
-6. Verify accessibility with screen readers
-
-## 🐛 Troubleshooting
-
-### Quick Diagnostic Commands
-
-```bash
-# Check if package is installed correctly
-npm ls @digilogiclabs/saas-factory-ui
-
-# Check package contents
-ls node_modules/@digilogiclabs/saas-factory-ui/dist/
-
-# Verify CSS file exists
-find node_modules/@digilogiclabs/saas-factory-ui -name "*.css"
-
-# Test network features (in browser console)
-navigator.onLine  // Should return true/false
-navigator.connection  // Should show connection info
-```
-
-### Common Solutions
-
-1. **Clear cache**: `rm -rf .next node_modules package-lock.json && npm install`
-2. **Rebuild**: `npm run build` in your project
-3. **Check imports**: Verify import paths match package exports
-4. **Update dependencies**: Ensure compatible React/Next.js versions
-5. **Network features not working**: Check browser support and permissions
-6. **Haptic feedback not working**: Verify device and browser support
-
-### Mobile-Specific Issues
-
-1. **Gestures not working**: Ensure `touch-action` CSS is not preventing interactions
-2. **Performance issues**: Enable `mobileOptimized` props where available
-3. **Network detection not working on mobile**: Check app permissions and service worker registration
-
-## 📄 License
-
-MIT © [DigiLogic Labs](https://github.com/DigiLogicLabs)
-
-## 🔗 Links
-
-- [Documentation](https://github.com/DigiLogicLabs/saas-factory-ui)
-- [NPM Package](https://www.npmjs.com/package/@digilogiclabs/saas-factory-ui)
-- [Issues](https://github.com/DigiLogicLabs/saas-factory-ui/issues)
-- [Changelog](CHANGELOG.md)
-- [Migration Guide](MIGRATION.md)
-
----
-
-**Current Version**: 0.13.0  
-**Release Date**: September 2025  
-**Platforms**: Web (Next.js/React) + React Native/Expo  
-**License**: MIT
+# @digilogiclabs/saas-factory-ui
+
+A comprehensive cross-platform UI component library built for both **Next.js web applications** and **React Native/Expo mobile applications**. This package provides a complete set of accessible, mobile-optimized components with consistent design across platforms.
+
+## 🌟 Features
+
+- 🎨 **Cross-Platform Design System**
+  - Consistent components for web and mobile
+  - Platform-optimized implementations
+  - Shared design tokens and theming
+- 🌐 **Web Support**
+  - Built with React, Tailwind CSS, Radix UI, and Framer Motion
+  - Dark mode support
+  - Responsive by default
+- 📱 **React Native Support**
+  - Native mobile components with Expo compatibility
+  - Platform-specific optimizations
+  - Haptic feedback integration
+- ♿️ **Accessibility First**
+  - WCAG 2.2 AA compliant components
+  - Screen reader support
+  - Keyboard navigation and touch alternatives
+- ⚡ **Performance Optimized**
+  - Advanced mobile interactions with gesture recognition
+  - Lazy loading and progressive image optimization
+  - Virtual scrolling for large datasets
+  - Network-aware content delivery
+- 🌐 **Offline Support**
+  - Comprehensive caching strategies
+  - Offline-first component architecture
+  - Network detection and graceful degradation
+- 🎯 **Developer Experience**
+  - Full TypeScript support
+  - Tree-shakeable exports
+  - Comprehensive documentation
+  - Optimized bundle sizes
+
+## 📦 Installation
+
+```bash
+npm install @digilogiclabs/saas-factory-ui
+```
+
+## 🚀 Platform Requirements
+
+### Web Applications
+
+- Node.js >=20.0.0
+- Next.js 15+ or React 19+
+- Tailwind CSS 3.4 or higher
+- TypeScript (recommended)
+
+### React Native Applications
+
+- Node.js >=20.0.0
+- React Native 0.70 or higher
+- Expo SDK 49 or higher
+- React 19 or higher
+
+## 🌐 Web Setup (Next.js)
+
+### 1. Install Dependencies
+
+```bash
+npm install @digilogiclabs/saas-factory-ui
+npm install -D tailwindcss postcss autoprefixer
+npx tailwindcss init -p
+```
+
+### 2. Configure Tailwind CSS
+
+Update your `tailwind.config.js` to include the component library:
+
+```js
+// tailwind.config.js
+/** @type {import('tailwindcss').Config} */
+export default {
+  content: [
+    "./src/**/*.{js,ts,jsx,tsx}",
+    "./app/**/*.{js,ts,jsx,tsx}",
+    "./pages/**/*.{js,ts,jsx,tsx}",
+    "./components/**/*.{js,ts,jsx,tsx}",
+    // 🚨 IMPORTANT: Include the UI package
+    "./node_modules/@digilogiclabs/saas-factory-ui/**/*.{js,ts,jsx,tsx}",
+  ],
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+};
+```
+
+### 3. Import Styles (REQUIRED)
+
+Add the CSS import to your root layout or app file:
+
+```tsx
+// app/layout.tsx (Next.js 13+) or pages/_app.tsx (Next.js 12)
+import "@digilogiclabs/saas-factory-ui/styles.css";
+import "./globals.css"; // Your app styles
+```
+
+### 4. Use Components
+
+```tsx
+import {
+  Button,
+  Card,
+  Container,
+  PageTransition,
+  SwipeableCard,
+  LazyImage,
+} from "@digilogiclabs/saas-factory-ui";
+
+export default function HomePage() {
+  return (
+    <PageTransition type="slide" direction="horizontal">
+      <Container>
+        <Card className="p-6">
+          <h1 className="text-2xl font-bold mb-4">Welcome to Web</h1>
+          <LazyImage
+            src="/hero-image.jpg"
+            alt="Hero image"
+            className="w-full h-64 object-cover rounded-lg mb-4"
+            placeholder="blur"
+            webpSupport={true}
+          />
+          <Button variant="default" size="lg">
+            Get Started
+          </Button>
+        </Card>
+      </Container>
+    </PageTransition>
+  );
+}
+```
+
+## 📱 React Native Setup
+
+### 1. Install Dependencies
+
+```bash
+npm install @digilogiclabs/saas-factory-ui
+# Required for advanced features
+npm install @react-native-community/netinfo
+npm install @react-native-async-storage/async-storage
+npm install expo-haptics
+```
+
+### 2. Import Native Components
+
+```tsx
+import {
+  NativeButton,
+  NativeContainer,
+  NativeCard,
+  NativePageTransition,
+  NativeSwipeableCard,
+  NativeLazyImage,
+} from "@digilogiclabs/saas-factory-ui/native";
+import { Text } from "react-native";
+
+export default function App() {
+  return (
+    <NativePageTransition type="slide" direction="horizontal">
+      <NativeContainer style={{ flex: 1, padding: 20 }}>
+        <NativeCard style={{ padding: 20 }}>
+          <Text style={{ fontSize: 20, fontWeight: "bold", marginBottom: 16 }}>
+            Welcome to Mobile
+          </Text>
+          <NativeLazyImage
+            source={{ uri: "https://example.com/image.jpg" }}
+            style={{
+              width: "100%",
+              height: 200,
+              borderRadius: 8,
+              marginBottom: 16,
+            }}
+            placeholder="skeleton"
+          />
+          <NativeButton
+            variant="default"
+            size="lg"
+            onPress={() => console.log("Pressed")}
+          >
+            Get Started
+          </NativeButton>
+        </NativeCard>
+      </NativeContainer>
+    </NativePageTransition>
+  );
+}
+```
+
+## 📚 Available Components
+
+### ✅ Core Components (v0.13.0)
+
+| Component                        | Web | Native | Description                                                   |
+| -------------------------------- | --- | ------ | ------------------------------------------------------------- |
+| **Layout & Structure**           |     |        |                                                               |
+| `Container`                      | ✅  | ✅     | Responsive layout containers                                  |
+| `Grid`                           | ✅  | ✅     | Flexible grid layouts                                         |
+| `Section`                        | ✅  | ✅     | Semantic page sections                                        |
+| `Card`                           | ✅  | ✅     | Content containers with elevation                             |
+| **Interactive Elements**         |     |        |                                                               |
+| `Button`                         | ✅  | ✅     | Primary action buttons with variants                          |
+| `SwipeableCard`                  | ✅  | ✅     | **NEW** Touch-friendly swipe gestures with haptic feedback    |
+| **Advanced Mobile Interactions** |     |        |                                                               |
+| `PageTransition`                 | ✅  | ✅     | **NEW** Smooth page transitions with multiple animation types |
+| `PullToRefresh`                  | ✅  | ✅     | **NEW** Native pull-to-refresh functionality                  |
+| **Performance & Media**          |     |        |                                                               |
+| `LazyImage`                      | ✅  | ✅     | **NEW** Intelligent lazy loading with WebP support            |
+| `ProgressiveImage`               | ✅  | ✅     | **NEW** Quality-aware progressive image loading               |
+| `VirtualScrollList`              | ✅  | ✅     | **NEW** Memory-efficient virtual scrolling                    |
+| **Network & Offline**            |     |        |                                                               |
+| `NetworkAwareContent`            | ✅  | ✅     | **NEW** Smart content delivery based on network conditions    |
+| `OfflineWrapper`                 | ✅  | ✅     | **NEW** Comprehensive offline support with caching            |
+
+### 🌐 Web-Specific Components
+
+- `Alert` - Contextual feedback messages
+- `Avatar` - User profile pictures and initials
+- `Badge` - Status indicators and counts
+- `Checkbox` - Boolean input controls
+- `DataTable` - Sortable data tables with pagination support
+- `Dialog` - Modal dialogs and overlays
+- `DropdownMenu` - Contextual action menus
+- `Form` - Form validation and state management
+- `Input` - Text input fields with validation
+- `Label` - Accessible form labels
+- `Modal` - Simple modal wrapper component
+- `Pagination` - Data navigation with page controls
+- `Progress` - Progress indicators and loading bars
+- `Select` - Dropdown selection controls
+- `Skeleton` - Loading state placeholders
+- `Tabs` - Tabbed content navigation
+- `Toast` - Notification messages
+- `Tooltip` - Contextual help and information
+- `AudioPlayer` - Advanced audio playback with playlists
+- `VideoPlayer` - Feature-rich video player
+- `AudioUploader` - Audio file upload with preview
+- `FileUpload` - Drag-and-drop file uploads
+- `Waveform` - Audio waveform visualization
+
+### 📱 Native-Specific Components
+
+- `SafeContainer` - Safe area aware container
+- `TouchableCard` - Pressable card component
+
+## 🆕 NEW v0.21.0: Layout & Navigation System
+
+### Complete Application Structure
+
+A comprehensive system providing everything needed for modern SaaS applications:
+
+#### 🏗️ App Shell Components
+
+| Component     | Web | Native | Description                               |
+| ------------- | --- | ------ | ----------------------------------------- |
+| `AppShell`    | ✅  | ✅     | Complete application layout orchestration |
+| `Header`      | ✅  | ✅     | Top navigation with user menu and actions |
+| `Sidebar`     | ✅  | -      | Collapsible navigation sidebar (web)      |
+| `Drawer`      | -   | ✅     | Slide-out navigation drawer (mobile)      |
+| `Breadcrumbs` | ✅  | -      | Hierarchical navigation breadcrumbs       |
+
+#### 🧭 Navigation Components
+
+| Component        | Web | Native | Description                             |
+| ---------------- | --- | ------ | --------------------------------------- |
+| `Tabs`           | ✅  | ✅     | Feature-rich tabbed navigation          |
+| `BottomTabBar`   | -   | ✅     | Mobile-optimized bottom tab navigation  |
+| `Stepper`        | ✅  | ✅     | Step-by-step process visualization      |
+| `Pagination`     | ✅  | ✅     | Data navigation with page controls      |
+| `CommandPalette` | ✅  | -      | Keyboard-driven command palette (Cmd+K) |
+
+#### 🎯 Tour & Onboarding
+
+| Component          | Web | Native | Description                                  |
+| ------------------ | --- | ------ | -------------------------------------------- |
+| `Tour`             | ✅  | ✅     | Interactive guided tours with spotlights     |
+| `Onboarding`       | ✅  | ✅     | Multi-step onboarding with progress tracking |
+| `Tooltip`          | ✅  | ✅     | Contextual feature highlights                |
+| `WelcomeModal`     | ✅  | ✅     | Welcome screens with feature showcase        |
+| `FeatureHighlight` | ✅  | -      | Animated feature callouts with pulse effects |
+
+#### 📋 Layout Templates
+
+| Template          | Web | Native | Description                                 |
+| ----------------- | --- | ------ | ------------------------------------------- |
+| `DashboardLayout` | ✅  | ✅     | Complete dashboard with navigation          |
+| `AuthLayout`      | ✅  | ✅     | Authentication pages with features showcase |
+| `SettingsLayout`  | ✅  | ✅     | Settings pages with tabbed navigation       |
+
+### Usage Examples
+
+#### Web Dashboard with Command Palette
+
+```tsx
+import {
+  DashboardLayout,
+  CommandPalette,
+  useCommandPalette,
+} from "@digilogiclabs/saas-factory-ui";
+
+export default function Dashboard() {
+  const commands = [
+    {
+      id: "nav",
+      label: "Navigation",
+      items: [
+        {
+          id: "dashboard",
+          label: "Go to Dashboard",
+          action: () => router.push("/"),
+        },
+        {
+          id: "settings",
+          label: "Open Settings",
+          action: () => router.push("/settings"),
+        },
+      ],
+    },
+  ];
+
+  const { isOpen, toggle } = useCommandPalette({
+    commands,
+    keyboardShortcut: "cmd+k",
+  });
+
+  return (
+    <DashboardLayout>
+      <div className="p-6">
+        <h1>Dashboard Content</h1>
+        <p>Press Cmd+K to open command palette</p>
+      </div>
+
+      <CommandPalette open={isOpen} onOpenChange={toggle} commands={commands} />
+    </DashboardLayout>
+  );
+}
+```
+
+#### Native App with Bottom Tabs
+
+```tsx
+import {
+  DashboardLayout,
+  Tour,
+  useTour,
+} from "@digilogiclabs/saas-factory-ui/native";
+
+export default function MobileApp() {
+  const tourSteps = [
+    {
+      id: "welcome",
+      title: "Welcome!",
+      content: "Let me show you around",
+      target: "#main-content",
+    },
+  ];
+
+  const { isOpen, start } = useTour({
+    steps: tourSteps,
+    localStorage: { key: "app-tour" },
+  });
+
+  return (
+    <DashboardLayout
+      showBottomTabs={true}
+      bottomTabs={[
+        { id: "home", label: "Home", icon: "🏠" },
+        { id: "search", label: "Search", icon: "🔍" },
+        { id: "profile", label: "Profile", icon: "👤" },
+      ]}
+    >
+      <ScrollView>
+        <Text style={styles.title}>Mobile Dashboard</Text>
+        <TouchableOpacity onPress={start}>
+          <Text>Start Tour</Text>
+        </TouchableOpacity>
+      </ScrollView>
+
+      <Tour steps={tourSteps} isOpen={isOpen} onRequestClose={() => {}} />
+    </DashboardLayout>
+  );
+}
+```
+
+### 🔧 Available Hooks
+
+#### Cross-Platform Hooks
+
+- `useMounted` - Component mount status detection
+- `useNetworkInfo` - **NEW** Network connection monitoring
+- `useOfflineState` - **NEW** Online/offline status detection
+- `useCache` - **NEW** Persistent caching utilities
+- `useTour` - **NEW** Tour state management with localStorage persistence
+- `useOnboarding` - **NEW** Multi-step onboarding flow management
+
+#### Web-Only Hooks
+
+- `useMediaQuery` - Responsive breakpoint detection
+- `useLockBody` - Body scroll lock for modals
+- `useCommandPalette` - **NEW** Command palette state management
+- `useResponsive` - **NEW** Advanced responsive breakpoint detection
+
+#### Native-Only Hooks
+
+- `useDimensions` - Screen dimensions and orientation
+- `useKeyboard` - Keyboard visibility and height
+
+## 🚀 New v0.13.0 Features
+
+### Advanced Mobile Interactions
+
+#### PageTransition
+
+Smooth, customizable page transitions with multiple animation types:
+
+```tsx
+// Web
+import { PageTransition } from "@digilogiclabs/saas-factory-ui";
+
+<PageTransition
+  type="slide"
+  direction="horizontal"
+  duration={300}
+  key={pageKey}
+>
+  <YourPageContent />
+</PageTransition>;
+
+// Supported types: 'slide', 'fade', 'scale', 'flip', 'elastic'
+// Directions: 'horizontal', 'vertical', 'up', 'down', 'left', 'right'
+```
+
+#### SwipeableCard
+
+Touch-friendly cards with swipe actions and haptic feedback:
+
+```tsx
+// Web
+import { SwipeableCard } from "@digilogiclabs/saas-factory-ui";
+
+<SwipeableCard
+  leftActions={[
+    {
+      id: "archive",
+      label: "Archive",
+      backgroundColor: "#10B981",
+      onAction: () => archiveItem(),
+    },
+  ]}
+  rightActions={[
+    {
+      id: "delete",
+      label: "Delete",
+      backgroundColor: "#EF4444",
+      onAction: () => deleteItem(),
+    },
+  ]}
+  hapticFeedback={true}
+  threshold={80}
+>
+  <div className="p-4">
+    <h3>Swipe me left or right!</h3>
+  </div>
+</SwipeableCard>;
+```
+
+#### PullToRefresh
+
+Native pull-to-refresh functionality:
+
+```tsx
+// Web
+import { PullToRefresh } from "@digilogiclabs/saas-factory-ui";
+
+<PullToRefresh
+  onRefresh={async () => {
+    await fetchFreshData();
+  }}
+  threshold={60}
+  hapticFeedback={true}
+>
+  <YourScrollableContent />
+</PullToRefresh>;
+```
+
+### Performance Optimization
+
+#### LazyImage
+
+Intelligent lazy loading with modern format support:
+
+```tsx
+// Web
+import { LazyImage } from "@digilogiclabs/saas-factory-ui";
+
+<LazyImage
+  src="/large-image.jpg"
+  alt="Description"
+  placeholder="blur"
+  webpSupport={true}
+  mobileOptimization={{
+    quality: 75,
+    format: "webp",
+    sizes: "(max-width: 768px) 100vw, 50vw",
+  }}
+  loading="lazy"
+  fetchPriority="high"
+  retryAttempts={3}
+/>;
+```
+
+#### ProgressiveImage
+
+Quality-aware progressive loading:
+
+```tsx
+// Web
+import { ProgressiveImage } from "@digilogiclabs/saas-factory-ui";
+
+<ProgressiveImage
+  lowQualitySrc="/thumbnail.jpg"
+  highQualitySrc="/full-quality.jpg"
+  alt="Progressive image"
+  mobileStrategy="blur-up"
+  transition="fade"
+  networkAware={true}
+/>;
+```
+
+#### VirtualScrollList
+
+Memory-efficient virtual scrolling for large datasets:
+
+```tsx
+// Web
+import { VirtualScrollList } from "@digilogiclabs/saas-factory-ui";
+
+<VirtualScrollList
+  items={largeDataArray}
+  itemHeight={80}
+  containerHeight={400}
+  renderItem={(item, index) => (
+    <div key={index} className="p-4 border-b">
+      {item.name}
+    </div>
+  )}
+  onEndReached={() => loadMore()}
+  mobileOptimized={true}
+  overscan={5}
+/>;
+```
+
+### Network & Offline Support
+
+#### NetworkAwareContent
+
+Smart content delivery based on connection quality:
+
+```tsx
+// Web
+import { NetworkAwareContent } from "@digilogiclabs/saas-factory-ui";
+
+<NetworkAwareContent
+  showOnFast={<HighQualityContent />}
+  showOnSlow={<LightweightContent />}
+  showOnOffline={<OfflineMessage />}
+  respectSaveData={true}
+>
+  <DefaultContent />
+</NetworkAwareContent>;
+```
+
+#### OfflineWrapper
+
+Comprehensive offline support with caching:
+
+```tsx
+// Web
+import { OfflineWrapper } from "@digilogiclabs/saas-factory-ui";
+
+<OfflineWrapper
+  cacheStrategy="stale-while-revalidate"
+  cacheKey="user-data"
+  cacheDuration={3600000} // 1 hour
+  showOfflineIndicator={true}
+  retryOnReconnect={true}
+>
+  <YourOnlineContent />
+</OfflineWrapper>;
+```
+
+## 🎨 Advanced Usage Examples
+
+### Mobile-Optimized Dashboard
+
+```tsx
+import {
+  PageTransition,
+  NetworkAwareContent,
+  VirtualScrollList,
+  PullToRefresh,
+  LazyImage,
+} from "@digilogiclabs/saas-factory-ui";
+
+function MobileDashboard() {
+  const [data, setData] = useState([]);
+  const [refreshing, setRefreshing] = useState(false);
+
+  const handleRefresh = async () => {
+    setRefreshing(true);
+    await fetchFreshData();
+    setRefreshing(false);
+  };
+
+  return (
+    <PageTransition type="slide" direction="up">
+      <div className="h-screen flex flex-col">
+        <NetworkAwareContent
+          showOnSlow={<SimpleDashboardHeader />}
+          showOnFast={<RichDashboardHeader />}
+        >
+          <DashboardHeader />
+        </NetworkAwareContent>
+
+        <PullToRefresh onRefresh={handleRefresh} className="flex-1">
+          <VirtualScrollList
+            items={data}
+            itemHeight={120}
+            renderItem={(item, index) => (
+              <div className="p-4 border-b">
+                <div className="flex items-center space-x-3">
+                  <LazyImage
+                    src={item.avatar}
+                    alt={item.name}
+                    className="w-12 h-12 rounded-full"
+                    placeholder="blur"
+                  />
+                  <div>
+                    <h3 className="font-semibold">{item.name}</h3>
+                    <p className="text-sm text-gray-500">{item.status}</p>
+                  </div>
+                </div>
+              </div>
+            )}
+            onEndReached={loadMoreData}
+            mobileOptimized={true}
+          />
+        </PullToRefresh>
+      </div>
+    </PageTransition>
+  );
+}
+```
+
+### Swipeable Card List with Actions
+
+```tsx
+import {
+  SwipeableCard,
+  LazyImage,
+  Button,
+} from "@digilogiclabs/saas-factory-ui";
+
+function MessageList({ messages }) {
+  return (
+    <div className="space-y-2">
+      {messages.map((message) => (
+        <SwipeableCard
+          key={message.id}
+          leftActions={[
+            {
+              id: "archive",
+              label: "Archive",
+              icon: "📁",
+              backgroundColor: "#10B981",
+              onAction: () => archiveMessage(message.id),
+            },
+          ]}
+          rightActions={[
+            {
+              id: "delete",
+              label: "Delete",
+              icon: "🗑️",
+              backgroundColor: "#EF4444",
+              onAction: () => deleteMessage(message.id),
+            },
+          ]}
+          threshold={100}
+          hapticFeedback={true}
+        >
+          <div className="flex items-center p-4 bg-white rounded-lg shadow">
+            <LazyImage
+              src={message.sender.avatar}
+              alt={message.sender.name}
+              className="w-12 h-12 rounded-full mr-3"
+              placeholder="skeleton"
+            />
+            <div className="flex-1">
+              <h4 className="font-semibold">{message.sender.name}</h4>
+              <p className="text-gray-600 truncate">{message.preview}</p>
+            </div>
+            <span className="text-xs text-gray-400">{message.time}</span>
+          </div>
+        </SwipeableCard>
+      ))}
+    </div>
+  );
+}
+```
+
+### Progressive Image Gallery
+
+```tsx
+import {
+  ProgressiveImage,
+  VirtualScrollList,
+} from "@digilogiclabs/saas-factory-ui";
+
+function ImageGallery({ images }) {
+  return (
+    <VirtualScrollList
+      items={images}
+      itemHeight={300}
+      renderItem={(image, index) => (
+        <div className="p-2">
+          <ProgressiveImage
+            lowQualitySrc={image.thumbnail}
+            highQualitySrc={image.fullSize}
+            alt={image.description}
+            className="w-full h-64 object-cover rounded-lg"
+            mobileStrategy="blur-up"
+            transition="crossfade"
+            networkAware={true}
+          />
+        </div>
+      )}
+      containerHeight={600}
+      mobileOptimized={true}
+    />
+  );
+}
+```
+
+## 🌐 Network-Aware Development
+
+### Connection-Based Content Delivery
+
+```tsx
+import {
+  NetworkAwareContent,
+  useNetworkInfo,
+} from "@digilogiclabs/saas-factory-ui";
+
+function AdaptiveApp() {
+  const networkInfo = useNetworkInfo();
+
+  return (
+    <div>
+      <NetworkAwareContent
+        fastThreshold={["4g", "fast"]}
+        slowThreshold={["2g", "3g", "slow"]}
+        showOnFast={
+          <div>
+            <HighResolutionImages />
+            <AnimatedComponents />
+            <VideoContent />
+          </div>
+        }
+        showOnSlow={
+          <div>
+            <CompressedImages />
+            <StaticComponents />
+            <TextContent />
+          </div>
+        }
+        showOnOffline={<OfflineFallback />}
+        respectSaveData={true}
+        onNetworkChange={(info) => {
+          console.log("Network changed:", info);
+          // Adjust app behavior based on network
+        }}
+      >
+        <DefaultContent />
+      </NetworkAwareContent>
+    </div>
+  );
+}
+```
+
+### Offline-First Architecture
+
+```tsx
+import {
+  OfflineWrapper,
+  useOfflineState,
+  useCache,
+} from "@digilogiclabs/saas-factory-ui";
+
+function OfflineCapableComponent() {
+  const isOnline = useOfflineState();
+  const { get, set } = useCache("user-preferences", 3600000);
+
+  return (
+    <OfflineWrapper
+      cacheStrategy="stale-while-revalidate"
+      cacheKey="dashboard-data"
+      showOfflineIndicator={true}
+      enableServiceWorker={true}
+      onOffline={() => console.log("Gone offline")}
+      onOnline={() => console.log("Back online")}
+      fallback={
+        <div className="text-center p-8">
+          <h3>You're offline</h3>
+          <p>Some features may not be available</p>
+        </div>
+      }
+    >
+      <div>
+        <h2>Dashboard {isOnline ? "🟢" : "🔴"}</h2>
+        <DashboardContent />
+      </div>
+    </OfflineWrapper>
+  );
+}
+```
+
+## 🎨 Theming & Styling
+
+### Custom Theme Configuration
+
+Create a custom theme by extending the default CSS variables:
+
+```css
+/* custom-theme.css */
+:root {
+  /* Primary colors */
+  --primary: 262 83% 58%; /* Purple */
+  --primary-foreground: 0 0% 98%;
+
+  /* Secondary colors */
+  --secondary: 220 14% 96%;
+  --secondary-foreground: 220 9% 46%;
+
+  /* Accent colors */
+  --accent: 262 83% 58%;
+  --accent-foreground: 0 0% 98%;
+
+  /* Custom border radius */
+  --radius: 0.75rem;
+}
+
+/* Dark mode overrides */
+.dark {
+  --primary: 262 83% 58%;
+  --primary-foreground: 0 0% 98%;
+  --background: 224 71% 4%;
+  --foreground: 213 31% 91%;
+}
+```
+
+## 📝 Migration Guide
+
+### From v0.12.x to v0.13.0
+
+#### New Dependencies (Optional)
+
+For full functionality, install additional dependencies:
+
+```bash
+# For React Native projects
+npm install @react-native-community/netinfo
+npm install @react-native-async-storage/async-storage
+npm install expo-haptics
+
+# These are optional and only needed if using specific components
+```
+
+#### Breaking Changes
+
+- None. All new components are additive.
+
+#### New Features Available
+
+- Advanced mobile interactions (PageTransition, SwipeableCard, PullToRefresh)
+- Performance optimization components (LazyImage, ProgressiveImage, VirtualScrollList)
+- Network and offline support (NetworkAwareContent, OfflineWrapper)
+- New hooks (useNetworkInfo, useOfflineState, useCache)
+
+## 🏗 Development Status
+
+### ✅ Completed (v0.13.0) - Mobile-First Optimization Release
+
+**Advanced Mobile Interactions**
+
+- ✅ PageTransition - Smooth page transitions with gesture support
+- ✅ SwipeableCard - Touch-friendly swipe gestures with haptic feedback
+- ✅ PullToRefresh - Native pull-to-refresh functionality
+
+**Performance Optimization**
+
+- ✅ LazyImage - Intelligent lazy loading with WebP support
+- ✅ ProgressiveImage - Quality-aware progressive image loading
+- ✅ VirtualScrollList - Memory-efficient virtual scrolling
+
+**Network & Offline Support**
+
+- ✅ NetworkAwareContent - Smart content delivery based on network conditions
+- ✅ OfflineWrapper - Comprehensive offline support with caching strategies
+- ✅ Network detection hooks and utilities
+
+**Developer Experience**
+
+- ✅ Cross-platform architecture (Web + React Native)
+- ✅ Full TypeScript support with platform-specific types
+- ✅ Accessibility-first design (WCAG 2.2 AA compliant)
+- ✅ Tree-shakeable exports and optimized bundle sizes
+- ✅ Comprehensive documentation and examples
+
+### ✅ Completed (v1.1.0) - Security Validators & Animation Presets
+
+**Security Validators**
+
+- ✅ `noHtml` - Block HTML tags in text fields (contact forms, comments)
+- ✅ `noUrls` - Block protocol-prefixed URLs (https://, http://, ftp://, www.)
+- ✅ `noLinks` - Block all links including bare domains (stricter than noUrls)
+
+**Framer Motion Presets**
+
+- ✅ `DURATIONS` - Standardized animation durations (instant/fast/normal/slow/slower)
+- ✅ `EASINGS` - Easing curves including cubic-bezier and spring configs
+- ✅ `VARIANTS` - 10 reusable animation variants (fadeIn, slideUp, scale, cardReveal, etc.)
+- ✅ `HOVER` / `HOVER_TRANSITION` - Consistent hover effect presets
+- ✅ `STAGGER_CONTAINERS` / `STAGGER_ITEMS` - Staggered children animations
+- ✅ `VIEWPORT` - Scroll-trigger viewport settings
+- ✅ `DISTANCES` - Movement distance presets (sm/md/lg/xl)
+- ✅ Helper functions: `createTransition()`, `createSlideVariant()`, `mergeVariants()`
+
+### 🚧 Coming Next (v1.2.0)
+
+**Enhanced Authentication Components**
+
+- 🔄 MobileAuthForm with biometric authentication
+- 🔄 MobileUserMenu with gesture-enabled navigation
+- 🔄 Social login optimizations
+
+**Mobile Payment Optimization**
+
+- 🔄 MobileCheckout with Apple Pay/Google Pay
+- 🔄 MobileBilling dashboard
+- 🔄 MobilePricing with comparison tables
+
+### 📋 Future Roadmap
+
+- Advanced UI components (BottomSheet, InfiniteScroll, FAB)
+- Enhanced theming system with brand color extraction
+- Real-time components with WebSocket integration
+- PWA optimization features
+- Advanced accessibility features
+- Comprehensive Storybook documentation
+
+## 🚀 Performance Metrics
+
+### Bundle Sizes (v0.13.0)
+
+- **Main Bundle**: 270KB ESM (295KB CJS) + 73KB CSS
+- **Web Bundle**: 295KB optimized for web platforms
+- **Native Bundle**: 18KB optimized for React Native
+- **Tree-shakeable**: Import only what you need
+
+### Performance Targets ✅
+
+- **Bundle Size**: < 250KB gzipped ✅ (Optimized)
+- **Load Time**: < 3s on 3G networks ✅
+- **First Paint**: < 1.5s ✅
+- **Interaction Ready**: < 2.5s ✅
+- **Accessibility Score**: 95+ Lighthouse ✅
+
+## 🔧 Development & Contributing
+
+### Local Development
+
+```bash
+# Clone the repository
+git clone https://github.com/DigiLogicLabs/saas-factory-ui
+cd saas-factory-ui
+
+# Install dependencies
+npm install
+
+# Build the package
+npm run build
+
+# Run tests
+npm run test
+
+# Type check
+npm run type-check
+
+# Lint
+npm run lint
+
+# Link for local testing
+npm link
+
+# In your test project
+npm link @digilogiclabs/saas-factory-ui
+```
+
+### Testing Your Changes
+
+1. Build the package: `npm run build`
+2. Test in a Next.js app with mobile interactions
+3. Test in a React Native/Expo app
+4. Verify TypeScript types work correctly
+5. Test offline/online scenarios
+6. Verify accessibility with screen readers
+
+## 🐛 Troubleshooting
+
+### Quick Diagnostic Commands
+
+```bash
+# Check if package is installed correctly
+npm ls @digilogiclabs/saas-factory-ui
+
+# Check package contents
+ls node_modules/@digilogiclabs/saas-factory-ui/dist/
+
+# Verify CSS file exists
+find node_modules/@digilogiclabs/saas-factory-ui -name "*.css"
+
+# Test network features (in browser console)
+navigator.onLine  // Should return true/false
+navigator.connection  // Should show connection info
+```
+
+### Common Solutions
+
+1. **Clear cache**: `rm -rf .next node_modules package-lock.json && npm install`
+2. **Rebuild**: `npm run build` in your project
+3. **Check imports**: Verify import paths match package exports
+4. **Update dependencies**: Ensure compatible React/Next.js versions
+5. **Network features not working**: Check browser support and permissions
+6. **Haptic feedback not working**: Verify device and browser support
+
+### Mobile-Specific Issues
+
+1. **Gestures not working**: Ensure `touch-action` CSS is not preventing interactions
+2. **Performance issues**: Enable `mobileOptimized` props where available
+3. **Network detection not working on mobile**: Check app permissions and service worker registration
+
+## 📄 License
+
+MIT © [DigiLogic Labs](https://github.com/DigiLogicLabs)
+
+## 🔗 Links
+
+- [Documentation](https://github.com/DigiLogicLabs/saas-factory-ui)
+- [NPM Package](https://www.npmjs.com/package/@digilogiclabs/saas-factory-ui)
+- [Issues](https://github.com/DigiLogicLabs/saas-factory-ui/issues)
+- [Changelog](CHANGELOG.md)
+
+---
+
+**Current Version**: 1.1.0
+**Platforms**: Web (Next.js/React) + React Native/Expo
+**License**: MIT