# @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
