@tradly/asset 1.0.25 → 1.0.27

package/README.md

@@ -1,7 +1,8 @@
 # @tradly/asset
 
-A reusable React component package for uploading and selecting media (images,
-videos, files) with Tradly authentication support.
+A cross-platform React component package for uploading and selecting media
+(images, videos, files) with Tradly authentication support. Works seamlessly on
+both Web (React) and Mobile (React Native).
 
 ## Features
 
@@ -100,6 +101,11 @@ function MyComponent() {
 import React, { useState } from "react";
 import { View, Button } from "react-native";
 import { MediaPopup, MediaApiService } from "@tradly/asset";
+import {
+	CameraIcon,
+	VideoIcon,
+	UploadIcon,
+} from "@tradly/asset/native/Icons.native";
 import { launchImageLibrary } from "react-native-image-picker";
 
 function MyComponent() {
@@ -121,6 +127,10 @@ function MyComponent() {
 	const picker = (options) => {
 		return new Promise((resolve) => {
 			launchImageLibrary(options, (response) => {
+				if (response.didCancel) {
+					resolve([]);
+					return;
+				}
 				resolve(response.assets || []);
 			});
 		});
@@ -137,9 +147,14 @@ function MyComponent() {
 				isOpen={isOpen}
 				onClose={() => setIsOpen(false)}
 				onSelect={handleSelect}
-				options={["image", "video"]}
+				options={["image", "video", "file"]}
 				apiService={apiService}
 				picker={picker} // REQUIRED: Your file picker function
+				icons={{
+					image: <CameraIcon />,
+					video: <VideoIcon />,
+					default: <UploadIcon />,
+				}}
 			/>
 		</View>
 	);
@@ -222,17 +237,76 @@ You can customize picker options based on the accept type:
 ```jsx
 <MediaPopup
 	picker={yourPickerFunction}
-	pickerOptions={(accept) => ({
-		mediaType: accept?.includes("image") ? "photo" : "video",
-		quality: 0.9,
-		allowsMultiple: true,
-		// Add any other options your picker library supports
-	})}
+	pickerOptions={(accept) => {
+		const isImage = accept?.includes("image");
+		const isVideo = accept?.includes("video");
+		const isFile = accept?.includes("file");
+
+		return {
+			mediaType: isImage ? "photo" : isVideo ? "video" : "mixed",
+			quality: 0.9,
+			allowsMultiple: true,
+			// Add any other options your picker library supports
+		};
+	}}
 	apiService={apiService}
 	// ... other props
 />
 ```
 
+#### File Picker Response Format
+
+The picker function should return an array of file objects. The package supports
+multiple formats:
+
+**react-native-image-picker format:**
+
+```javascript
+{
+	assets: [
+		{
+			uri: "file:///path/to/file.jpg",
+			fileName: "image.jpg",
+			mimeType: "image/jpeg",
+			fileSize: 12345,
+		},
+	];
+}
+```
+
+**expo-image-picker format:**
+
+```javascript
+{
+	assets: [
+		{
+			uri: "file:///path/to/file.jpg",
+			fileName: "image.jpg",
+			mimeType: "image/jpeg",
+		},
+	];
+}
+```
+
+**Custom format:**
+
+```javascript
+[
+	{
+		uri: "file:///path/to/file.jpg",
+		name: "image.jpg", // or fileName
+		type: "image/jpeg", // or mimeType
+	},
+];
+```
+
+The package will automatically:
+
+- Extract `uri` from `uri` or `path`
+- Extract file name from `fileName`, `name`, or parse from URI
+- Detect MIME type from `mimeType`, `type`, or file extension
+- Handle missing properties with smart fallbacks
+
 ### React Native UI Differences
 
 - **Bottom Sheet**: Media gallery opens as a bottom sheet (slides up from
@@ -242,6 +316,11 @@ You can customize picker options based on the accept type:
   `TouchableOpacity`, `FlatList`, `Image`)
 - **File Upload**: Requires `picker` prop to be provided
 - **Theme System**: Full theme support for easy dark/light mode customization
+- **Icons**: Support for custom icons per media type (image, video, file)
+- **File Handling**: Automatically handles `file://` URIs and converts them to
+  blobs for S3 upload
+- **MIME Type Detection**: Comprehensive MIME type detection from file
+  extensions and picker results
 
 ### React Native Theme & Customization
 
@@ -268,68 +347,313 @@ const lightTheme = createTheme({ mode: "light" });
 />;
 ```
 
-#### Custom Theme Colors
+#### Theme Examples
+
+**Example 1: Complete Custom Theme**
 
 ```jsx
 import { createTheme } from "@tradly/asset/native/theme";
 
 const customTheme = createTheme({
-  mode: "dark", // or "light"
+  mode: "dark",
   colors: {
     // Primary colors
     primary: "#6366F1",
-    tabActive: "#6366F1",
-    tabIndicator: "#6366F1",
+    primaryLight: "#818CF8",
+    primaryDark: "#4F46E5",
 
     // Backgrounds
     background: "#0F172A",
     backgroundSecondary: "#1E293B",
+    backgroundTertiary: "#334155",
 
     // Text
     text: "#F1F5F9",
     textSecondary: "#CBD5E1",
+    textTertiary: "#94A3B8",
 
     // Tabs
     tabActive: "#6366F1",
     tabInactive: "#94A3B8",
+    tabIndicator: "#6366F1",
     tabBackground: "#0F172A",
 
-    // Borders
-    border: "#334155",
+    // Upload
+    uploadBorder: "#6366F1",
+    uploadBackground: "#1E293B",
+    uploadIconBackground: "#6366F1",
+    uploadText: "#F1F5F9",
 
     // Pagination
+    paginationBackground: "#1E293B",
     paginationButtonActive: "#6366F1",
     paginationTextActive: "#FFFFFF",
 
-    // Upload button
-    uploadBorder: "#6366F1",
-    uploadIconBackground: "#6366F1",
-
-    // And many more...
+    // And all other colors...
+  },
+  spacing: {
+    xs: 4,
+    sm: 8,
+    md: 12,
+    lg: 16,
+    xl: 20,
+    xxl: 24,
   },
-  bottomSheetHeight: 0.92, // 92% of screen height
+  radius: {
+    sm: 6,
+    md: 8,
+    lg: 12,
+    xl: 16,
+    xxl: 20,
+  },
+  bottomSheetHeight: 0.92,
 });
 
 <MediaPopup theme={customTheme} ... />
 ```
 
-#### Available Theme Colors
+**Example 2: Minimal Override (Only Colors)**
 
-All colors are customizable via the theme object:
+```jsx
+// Only override specific colors, rest uses defaults
+const minimalTheme = createTheme({
+	colors: {
+		primary: "#FF6B6B",
+		tabActive: "#FF6B6B",
+		tabIndicator: "#FF6B6B",
+	},
+});
+```
 
-- **Primary**: `primary`, `primaryLight`, `primaryDark`
-- **Backgrounds**: `background`, `backgroundSecondary`, `backgroundTertiary`
-- **Text**: `text`, `textSecondary`, `textTertiary`, `textInverse`
-- **Borders**: `border`, `borderLight`, `borderDark`
-- **Tabs**: `tabActive`, `tabInactive`, `tabIndicator`, `tabBackground`
-- **Pagination**: `paginationBackground`, `paginationButton`,
-  `paginationButtonActive`, `paginationText`, `paginationTextActive`,
-  `paginationBorder`
-- **Upload**: `uploadBorder`, `uploadBackground`, `uploadIconBackground`,
-  `uploadText`
-- **Items**: `itemBackground`, `itemShadow`
-- **Loading**: `loadingBackground`, `loadingText`
-- **Overlay**: `overlay`
+#### Complete Theme Reference
+
+**All Available Theme Properties:**
+
+| Category                | Property                 | Type     | Description           | Default (Light)   |
+| ----------------------- | ------------------------ | -------- | --------------------- | ----------------- |
+| **Colors - Primary**    | `primary`                | `string` | Main brand color      | `#3B3269`         |
+|                         | `primaryLight`           | `string` | Lighter variant       | `#5A4A8A`         |
+|                         | `primaryDark`            | `string` | Darker variant        | `#2A1F4A`         |
+| **Colors - Background** | `background`             | `string` | Main background       | `#FFFFFF`         |
+|                         | `backgroundSecondary`    | `string` | Secondary background  | `#F5F5F5`         |
+|                         | `backgroundTertiary`     | `string` | Tertiary background   | `#E5E5E5`         |
+| **Colors - Text**       | `text`                   | `string` | Primary text          | `#000000`         |
+|                         | `textSecondary`          | `string` | Secondary text        | `#4F4F4F`         |
+|                         | `textTertiary`           | `string` | Tertiary text         | `#6B7280`         |
+|                         | `textInverse`            | `string` | Inverse text          | `#FFFFFF`         |
+| **Colors - Border**     | `border`                 | `string` | Default border        | `#E5E5E5`         |
+|                         | `borderLight`            | `string` | Light border          | `#F0F0F0`         |
+|                         | `borderDark`             | `string` | Dark border           | `#D1D5DB`         |
+| **Colors - Overlay**    | `overlay`                | `string` | Modal overlay         | `rgba(0,0,0,0.5)` |
+| **Colors - Tabs**       | `tabActive`              | `string` | Active tab text       | `#3B3269`         |
+|                         | `tabInactive`            | `string` | Inactive tab text     | `#4F4F4F`         |
+|                         | `tabIndicator`           | `string` | Tab indicator line    | `#3B3269`         |
+|                         | `tabBackground`          | `string` | Tab container         | `#FFFFFF`         |
+| **Colors - Items**      | `itemBackground`         | `string` | Media item background | `#FFFFFF`         |
+|                         | `itemShadow`             | `string` | Item shadow color     | `#000000`         |
+| **Colors - Pagination** | `paginationBackground`   | `string` | Container background  | `#F5F5F5`         |
+|                         | `paginationButton`       | `string` | Button background     | `#FFFFFF`         |
+|                         | `paginationButtonActive` | `string` | Active button         | `#3B3269`         |
+|                         | `paginationText`         | `string` | Text color            | `#6B7280`         |
+|                         | `paginationTextActive`   | `string` | Active text           | `#FFFFFF`         |
+|                         | `paginationBorder`       | `string` | Border color          | `#D1D5DB`         |
+| **Colors - Upload**     | `uploadBorder`           | `string` | Button border         | `#3B3269`         |
+|                         | `uploadBackground`       | `string` | Button background     | `#FFFFFF`         |
+|                         | `uploadIconBackground`   | `string` | Icon container        | `#3B3269`         |
+|                         | `uploadText`             | `string` | Button text           | `#000000`         |
+| **Colors - Loading**    | `loadingBackground`      | `string` | Skeleton background   | `#E5E5E5`         |
+|                         | `loadingText`            | `string` | Loading text          | `#666666`         |
+| **Spacing**             | `xs`                     | `number` | Extra small (4px)     | `4`               |
+|                         | `sm`                     | `number` | Small (8px)           | `8`               |
+|                         | `md`                     | `number` | Medium (12px)         | `12`              |
+|                         | `lg`                     | `number` | Large (16px)          | `16`              |
+|                         | `xl`                     | `number` | Extra large (20px)    | `20`              |
+|                         | `xxl`                    | `number` | 2X extra large (24px) | `24`              |
+| **Radius**              | `sm`                     | `number` | Small radius (6px)    | `6`               |
+|                         | `md`                     | `number` | Medium radius (8px)   | `8`               |
+|                         | `lg`                     | `number` | Large radius (12px)   | `12`              |
+|                         | `xl`                     | `number` | Extra large (16px)    | `16`              |
+|                         | `xxl`                    | `number` | 2X extra large (20px) | `20`              |
+| **Typography**          | `title.fontSize`         | `number` | Title font size       | `24`              |
+|                         | `title.fontWeight`       | `string` | Title weight          | `"bold"`          |
+|                         | `subtitle.fontSize`      | `number` | Subtitle size         | `18`              |
+|                         | `subtitle.fontWeight`    | `string` | Subtitle weight       | `"600"`           |
+|                         | `body.fontSize`          | `number` | Body font size        | `16`              |
+|                         | `body.fontWeight`        | `string` | Body weight           | `"500"`           |
+|                         | `caption.fontSize`       | `number` | Caption size          | `14`              |
+|                         | `caption.fontWeight`     | `string` | Caption weight        | `"400"`           |
+| **Other**               | `bottomSheetHeight`      | `number` | Sheet height (0-1)    | `0.9`             |
+|                         | `mode`                   | `string` | `"light"` or `"dark"` | `"light"`         |
+
+#### Complete Theme Customization
+
+The theme system supports comprehensive customization of colors, spacing,
+typography, and more:
+
+**Colors:**
+
+```jsx
+const customTheme = createTheme({
+	mode: "light", // or "dark"
+	colors: {
+		// Primary colors
+		primary: "#3B3269", // Main brand color
+		primaryLight: "#5A4A8A", // Lighter variant
+		primaryDark: "#2A1F4A", // Darker variant
+
+		// Background colors
+		background: "#FFFFFF", // Main background
+		backgroundSecondary: "#F5F5F5", // Secondary background
+		backgroundTertiary: "#E5E5E5", // Tertiary background
+
+		// Text colors
+		text: "#000000", // Primary text
+		textSecondary: "#4F4F4F", // Secondary text
+		textTertiary: "#6B7280", // Tertiary text
+		textInverse: "#FFFFFF", // Inverse text (for dark backgrounds)
+
+		// Border colors
+		border: "#E5E5E5", // Default border
+		borderLight: "#F0F0F0", // Light border
+		borderDark: "#D1D5DB", // Dark border
+
+		// Overlay
+		overlay: "rgba(0, 0, 0, 0.5)", // Modal overlay
+
+		// Tab colors
+		tabActive: "#3B3269", // Active tab text
+		tabInactive: "#4F4F4F", // Inactive tab text
+		tabIndicator: "#3B3269", // Tab indicator line
+		tabBackground: "#FFFFFF", // Tab container background
+
+		// Media item colors
+		itemBackground: "#FFFFFF", // Image/video item background
+		itemShadow: "#000000", // Item shadow color
+
+		// Pagination colors
+		paginationBackground: "#F5F5F5", // Pagination container
+		paginationButton: "#FFFFFF", // Page button background
+		paginationButtonActive: "#3B3269", // Active page button
+		paginationText: "#6B7280", // Page number text
+		paginationTextActive: "#FFFFFF", // Active page text
+		paginationBorder: "#D1D5DB", // Pagination border
+
+		// Upload button colors
+		uploadBorder: "#3B3269", // Upload button border
+		uploadBackground: "#FFFFFF", // Upload button background
+		uploadIconBackground: "#3B3269", // Icon container background
+		uploadText: "#000000", // Upload button text
+
+		// Loading state colors
+		loadingBackground: "#E5E5E5", // Loading skeleton background
+		loadingText: "#666666", // Loading text color
+	},
+	// Spacing (in pixels)
+	spacing: {
+		xs: 4, // Extra small
+		sm: 8, // Small
+		md: 12, // Medium
+		lg: 16, // Large
+		xl: 20, // Extra large
+		xxl: 24, // 2X extra large
+	},
+	// Border radius (in pixels)
+	radius: {
+		sm: 6, // Small radius
+		md: 8, // Medium radius
+		lg: 12, // Large radius
+		xl: 16, // Extra large radius
+		xxl: 20, // 2X extra large radius
+	},
+	// Typography
+	typography: {
+		title: {
+			fontSize: 24,
+			fontWeight: "bold",
+		},
+		subtitle: {
+			fontSize: 18,
+			fontWeight: "600",
+		},
+		body: {
+			fontSize: 16,
+			fontWeight: "500",
+		},
+		caption: {
+			fontSize: 14,
+			fontWeight: "400",
+		},
+	},
+	// Bottom sheet height (0.85 = 85%, 0.9 = 90%, etc.)
+	bottomSheetHeight: 0.9,
+});
+```
+
+**Partial Theme Override:**
+
+You can override only specific parts of the theme - other values will use
+defaults:
+
+```jsx
+// Only change primary color and background
+const brandTheme = createTheme({
+	colors: {
+		primary: "#6366F1",
+		tabActive: "#6366F1",
+		tabIndicator: "#6366F1",
+		background: "#F8F9FA",
+	},
+});
+
+// Only change spacing
+const compactTheme = createTheme({
+	spacing: {
+		md: 8, // Reduce medium spacing
+		lg: 12, // Reduce large spacing
+	},
+});
+
+// Only change bottom sheet height
+const tallTheme = createTheme({
+	bottomSheetHeight: 0.95, // 95% of screen
+});
+```
+
+#### Dark Mode Example
+
+```jsx
+import { createTheme } from "@tradly/asset/native/theme";
+
+const darkTheme = createTheme({
+  mode: "dark",
+  colors: {
+    primary: "#6366F1",
+    background: "#0F172A",
+    text: "#F1F5F9",
+    tabActive: "#6366F1",
+    tabInactive: "#94A3B8",
+    // ... customize other colors
+  },
+});
+
+<MediaPopup theme={darkTheme} ... />
+```
+
+#### Brand Color Customization
+
+```jsx
+const brandTheme = createTheme({
+	colors: {
+		// Your brand colors
+		primary: "#FF6B6B",
+		tabActive: "#FF6B6B",
+		tabIndicator: "#FF6B6B",
+		uploadBorder: "#FF6B6B",
+		uploadIconBackground: "#FF6B6B",
+		paginationButtonActive: "#FF6B6B",
+	},
+});
+```
 
 #### Customizing Bottom Sheet Height
 
@@ -343,20 +667,30 @@ All colors are customizable via the theme object:
 
 #### Individual Component Styling
 
-You can also override individual component styles:
+You can override individual component styles in addition to theme:
 
 ```jsx
 <MediaPopup
 	theme={darkTheme}
-	// Override specific styles
+	// Override specific styles (these override theme values)
 	containerStyle={{ padding: 24 }}
 	headerStyle={{ paddingBottom: 16 }}
-	titleStyle={{ fontSize: 28 }}
+	titleStyle={{ fontSize: 28, color: "#FFFFFF" }}
 	closeButtonStyle={{ padding: 12 }}
+	closeButtonTextStyle={{ color: "#FFFFFF" }}
+	// Tab styles
 	tabListStyle={{ paddingHorizontal: 8 }}
 	tabButtonStyle={{ paddingVertical: 16 }}
 	tabButtonActiveStyle={{ backgroundColor: "#F0F0F0" }}
 	tabButtonTextActiveStyle={{ fontWeight: "700" }}
+	tabButtonTextInactiveStyle={{ color: "#999999" }}
+	tabIndicatorStyle={{ height: 3 }}
+	// Gallery styles
+	gridStyle={{ padding: 8 }}
+	imageItemStyle={{ borderRadius: 12 }}
+	videoItemStyle={{ borderRadius: 12 }}
+	fileItemStyle={{ borderRadius: 12 }}
+	paginationContainerStyle={{ padding: 16 }}
 	// ... and many more style props
 />
 ```
@@ -372,6 +706,43 @@ upload logic is handled internally:
 2. **Upload files to S3** using the signed URLs
 3. **Save media metadata** to your API
 
+**React Native File Upload:**
+
+The package automatically handles React Native file formats:
+
+- Converts `file://` URIs to blobs for S3 upload
+- Handles `content://` URIs (Android)
+- Supports multiple file picker libraries
+- Automatic MIME type detection from file extensions
+- Proper file name cleaning (removes spaces)
+
+**File Format Support:**
+
+The package accepts files in these formats:
+
+- **react-native-image-picker**: `{ uri, fileName, mimeType, ... }`
+- **expo-image-picker**: `{ uri, fileName, mimeType, ... }`
+- **Custom pickers**: `{ uri, name, type, ... }` or
+  `{ uri, fileName, mimeType, ... }`
+
+The package will automatically:
+
+- Extract file name from `fileName`, `name`, or URI
+- Detect MIME type from `mimeType`, `type`, or file extension
+- Handle file URIs (`file://`, `content://`) for upload
+- Clean file names (removes spaces for S3 compatibility)
+- Convert file URIs to blobs for S3 PUT requests
+
+**Upload Process:**
+
+1. **File Selection**: User selects files via picker
+2. **File Processing**: Package converts picker results to standardized format
+3. **MIME Type Detection**: Automatically detects MIME type from extension or
+   picker result
+4. **S3 Signed URL**: Gets signed URL from Tradly API
+5. **File Upload**: Fetches file from URI, converts to blob, uploads to S3
+6. **Metadata Save**: Saves media metadata to Tradly API
+
 Configuration:
 
 ```jsx
@@ -393,15 +764,22 @@ const apiService = new MediaApiService({
 
 ### Using Individual Components
 
-You can also use the components individually:
+You can use individual gallery components if you need more control:
+
+**Web:**
 
 ```jsx
-import { ImagesGallery, MediaApiService } from "@tradly/asset";
+import {
+	ImagesGallery,
+	VideosGallery,
+	FilesGallery,
+	MediaApiService,
+} from "@tradly/asset";
 
 function CustomGallery() {
 	const apiService = new MediaApiService({
 		authKey: "your-auth-key",
-		baseUrl: "/api",
+		bearerToken: "your-bearer-token",
 	});
 
 	return (
@@ -414,6 +792,52 @@ function CustomGallery() {
 }
 ```
 
+**React Native:**
+
+```jsx
+import {
+	ImagesGallery,
+	VideosGallery,
+	FilesGallery,
+	MediaApiService,
+} from "@tradly/asset";
+import {
+	CameraIcon,
+	VideoIcon,
+	UploadIcon,
+} from "@tradly/asset/native/Icons.native";
+import { launchImageLibrary } from "react-native-image-picker";
+
+function CustomGallery() {
+	const apiService = new MediaApiService({
+		authKey: "your-auth-key",
+		bearerToken: "your-bearer-token",
+	});
+
+	const picker = (options) => {
+		return new Promise((resolve) => {
+			launchImageLibrary(options, (response) => {
+				if (response.didCancel) {
+					resolve([]);
+					return;
+				}
+				resolve(response.assets || []);
+			});
+		});
+	};
+
+	return (
+		<FilesGallery
+			update_data={(url) => console.log("Selected:", url)}
+			closePopup={() => console.log("Closed")}
+			apiService={apiService}
+			picker={picker}
+			icons={{ default: <UploadIcon /> }}
+		/>
+	);
+}
+```
+
 ### Error Handling
 
 ```jsx
@@ -472,6 +896,7 @@ apiService.setBearerToken("new-bearer-token");
 | `title`             | `string`          | `'Media Gallery'` | Popup title                                         | Web & Native |
 | `picker`            | `function`        | -                 | **Required for React Native**: File picker function | Native only  |
 | `pickerOptions`     | `function`        | -                 | Optional: Function to generate picker options       | Native only  |
+| `icons`             | `object`          | -                 | Icon components: `{ image, video, default }`        | Native only  |
 | `theme`             | `object`          | -                 | Theme object for colors/spacing (see Theme docs)    | Native only  |
 | `bottomSheetHeight` | `number`          | `0.9`             | Bottom sheet height (0.85 = 85%, 0.9 = 90%, etc.)   | Native only  |
 
@@ -483,6 +908,81 @@ apiService.setBearerToken("new-bearer-token");
        `{ uri: string, type?: string, fileName?: string }`
      - Example: `picker={(options) => launchImageLibrary(options, callback)}`
 
+**Icons Configuration (React Native):**
+
+You can provide different icons for each media type:
+
+```jsx
+import {
+	CameraIcon,
+	VideoIcon,
+	UploadIcon,
+} from "@tradly/asset/native/Icons.native";
+
+<MediaPopup
+	icons={{
+		image: <CameraIcon />, // Icon for image uploads
+		video: <VideoIcon />, // Icon for video uploads
+		default: <UploadIcon />, // Icon for file uploads (PDFs, docs, etc.)
+	}}
+	// ... other props
+/>;
+```
+
+If `icons` prop is not provided, the upload button will show only text (no
+icon).
+
+**Available Icons:**
+
+The package includes built-in icons that you can use:
+
+```jsx
+import {
+	CameraIcon, // For image uploads
+	VideoIcon, // For video uploads
+	UploadIcon, // For file uploads (default)
+	CloseIcon, // For close button (used internally)
+} from "@tradly/asset/native/Icons.native";
+
+<MediaPopup
+	icons={{
+		image: <CameraIcon />,
+		video: <VideoIcon />,
+		default: <UploadIcon />,
+	}}
+/>;
+```
+
+You can also use custom icon components from libraries like
+`react-native-vector-icons` or `lucide-react-native`:
+
+```jsx
+import { Camera, Video, Upload } from "lucide-react-native";
+
+<MediaPopup
+	icons={{
+		image: (
+			<Camera
+				size={20}
+				color="#3B3269"
+			/>
+		),
+		video: (
+			<Video
+				size={20}
+				color="#3B3269"
+			/>
+		),
+		default: (
+			<Upload
+				size={20}
+				color="#3B3269"
+			/>
+		),
+	}}
+/>;
+```
+
 ## Styling
 
 ### Web (React)
@@ -573,20 +1073,23 @@ using style props:
 - `tabIndicatorStyle` - Tab indicator line
 - `tabPanelStyle` - Tab panel container
 
-**ImagesGallery/VideosGallery:**
+**ImagesGallery/VideosGallery/FilesGallery:**
 
 - `containerStyle` - Gallery container
 - `gridStyle` - Media grid layout
-- `imageItemStyle` / `videoItemStyle` - Media item styles
+- `imageItemStyle` / `videoItemStyle` / `fileItemStyle` - Media item styles
 - `paginationContainerStyle` - Pagination container
 
 **FileUpload:**
 
 - `containerStyle` - Upload container
 - `buttonStyle` - Upload button
-- `iconContainerStyle` - Icon container
+- `iconContainerStyle` - Icon container (only shown if icon is provided)
 - `titleStyle` - Upload title text
 - `loadingStyle` - Loading state container
+- `icon` - Single icon (backward compatibility, overridden by `icons` prop)
+- `icons` - Object with `{ image, video, default }` icon components (React
+  Native)
 
 **Pagination:**
 
@@ -648,6 +1151,12 @@ For detailed styling documentation with examples, see
 **React Native:**
 
 ```jsx
+import {
+	CameraIcon,
+	VideoIcon,
+	UploadIcon,
+} from "@tradly/asset/native/Icons.native";
+
 <MediaPopup
 	isOpen={isOpen}
 	onClose={() => setIsOpen(false)}
@@ -655,9 +1164,25 @@ For detailed styling documentation with examples, see
 	options={["image", "video", "file"]}
 	apiService={apiService}
 	picker={picker} // Required
-/>
+	icons={{
+		image: <CameraIcon />,
+		video: <VideoIcon />,
+		default: <UploadIcon />, // For file uploads
+	}}
+/>;
 ```
 
+### File Type Gallery
+
+The `file` option displays non-image, non-video files (PDFs, documents,
+archives, etc.):
+
+- **Supported File Types**: PDF, Word, Excel, PowerPoint, ZIP, RAR, audio files,
+  text files, and more
+- **File Icons**: Automatically displays appropriate icons based on MIME type
+- **File Information**: Shows file name and extension
+- **Upload Support**: Full upload functionality for all file types
+
 ## Platform-Specific Notes
 
 ### Web (React)
@@ -666,30 +1191,118 @@ For detailed styling documentation with examples, see
 - Tailwind CSS for styling
 - HTML file input for file selection
 - Canvas API for image compression
+- Direct File/Blob objects for upload
 
 ### React Native
 
-- Uses `Modal` component for bottom sheet
+- Uses `Modal` component for bottom sheet (slides up from bottom)
 - React Native `StyleSheet` for styling
 - Requires file picker library (configurable)
 - Uses `FlatList` for efficient media rendering
 - Supports both iOS and Android
+- Handles `file://` and `content://` URIs
+- Converts file URIs to blobs for S3 upload
+- Comprehensive MIME type detection
+- File name cleaning (removes spaces)
+- 3-column grid layout (optimized for mobile)
+- Customizable icons per media type
 
-## Development
+## File Types Support
 
-To develop or modify this package:
+The package supports three media types:
 
-```bash
-cd packages/asset
-npm install
-npm run dev
+- **`image`**: Images (JPEG, PNG, GIF, WebP, SVG, HEIC, etc.)
+- **`video`**: Videos (MP4, MOV, AVI, WebM, etc.)
+- **`file`**: Other files (PDF, Word, Excel, PowerPoint, ZIP, audio files, text
+  files, etc.)
+
+Each type has its own gallery component:
+
+- `ImagesGallery` - For images
+- `VideosGallery` - For videos
+- `FilesGallery` - For non-image, non-video files
+
+The package automatically uses the correct gallery based on the `options` prop.
+
+## MIME Type Detection
+
+The package includes comprehensive MIME type detection:
+
+- **From Picker Result**: Uses `mimeType` or `type` from picker response
+- **From File Extension**: Automatically detects MIME type from file extension
+- **Fallback**: Defaults to `application/octet-stream` if detection fails
+
+Supported file types include:
+
+- **Images**: jpg, jpeg, png, gif, webp, svg, bmp, ico, heic, heif, tiff, avif
+- **Videos**: mp4, mov, avi, wmv, flv, mkv, webm, mpeg, mpg, m4v, 3gp
+- **Audio**: mp3, wav, ogg, m4a, aac, flac
+- **Documents**: pdf, doc, docx, xls, xlsx, ppt, pptx
+- **Archives**: zip, rar, 7z, tar, gz
+- **Text**: txt, html, css, js, json, xml, php
+
+## How It Works
+
+The package automatically detects the platform and uses the appropriate
+components:
+
+- **Web bundlers** (Webpack, Vite, etc.) automatically use `.web.jsx` files
+- **React Native bundlers** (Metro) automatically use `.native.jsx` files
+
+You don't need to import different files - the package handles platform
+detection automatically:
+
+```jsx
+// Same import works for both web and React Native
+import { MediaPopup, MediaApiService } from "@tradly/asset";
 ```
 
-**Note:** The package automatically detects the platform and uses the
-appropriate components:
+The package uses platform-specific implementations under the hood:
+
+- Web: Uses React DOM, Tailwind CSS, HTML file inputs
+- React Native: Uses React Native primitives, StyleSheet, configurable file
+  pickers
+
+## Troubleshooting
+
+### React Native File Upload Issues
+
+**Problem**: Files not uploading from React Native
+
+**Solutions**:
 
-- Web bundlers will use `.web.jsx` files
-- React Native bundlers (Metro) will use `.native.jsx` files
+1. Ensure `picker` prop is provided and returns files in correct format
+2. Check that file URIs are accessible (`file://` or `content://`)
+3. Verify MIME type is being detected correctly (check console logs)
+4. Ensure proper permissions are granted for file access
+
+**Problem**: MIME type not detected properly
+
+**Solutions**:
+
+1. The package automatically detects MIME type from:
+      - Picker result (`mimeType` or `type` property)
+      - File extension (comprehensive mapping included)
+2. If detection fails, it defaults to `application/octet-stream`
+3. Check console logs to see detected MIME type
+
+**Problem**: Bottom sheet not showing properly
+
+**Solutions**:
+
+1. Adjust `bottomSheetHeight` prop (default: 0.9 = 90%)
+2. Check container padding in theme
+3. Ensure `overflow: 'hidden'` is applied (already included)
+
+### Grid Layout Issues
+
+**Problem**: Items showing 2 per row instead of 3
+
+**Solutions**:
+
+1. Check container padding matches between skeleton and gallery
+2. Verify `ITEM_SIZE` calculation accounts for all padding/margins
+3. Ensure `FlatList` with `numColumns={3}` is used (not `flexWrap`)
 
 ## License
 
@@ -699,3 +1312,145 @@ MIT
 
 For issues and questions, please open an issue on the repository.
 
+## Quick Reference
+
+### Complete React Native Example
+
+```jsx
+import React, { useState } from "react";
+import { View, Button, Alert } from "react-native";
+import { MediaPopup, MediaApiService } from "@tradly/asset";
+import {
+	CameraIcon,
+	VideoIcon,
+	UploadIcon,
+} from "@tradly/asset/native/Icons.native";
+import { launchImageLibrary } from "react-native-image-picker";
+import { Platform } from "react-native";
+
+function App() {
+	const [isOpen, setIsOpen] = useState(false);
+	const [selectedMedia, setSelectedMedia] = useState(null);
+
+	const apiService = new MediaApiService({
+		authKey: "your-tradly-auth-key",
+		bearerToken: "your-bearer-token",
+		environment: "dev", // Auto-detected from process.env.ENVIRONMENT
+	});
+
+	const handleSelect = (mediaUrl) => {
+		setSelectedMedia(mediaUrl);
+		setIsOpen(false);
+		Alert.alert("Selected", mediaUrl);
+	};
+
+	const handleError = (error) => {
+		console.error("Error:", error);
+		Alert.alert("Error", error.message || "Something went wrong");
+	};
+
+	// File picker configuration
+	const picker = (options) => {
+		return new Promise((resolve) => {
+			launchImageLibrary(options, (response) => {
+				if (response.didCancel) {
+					resolve([]);
+					return;
+				}
+				if (response.errorMessage) {
+					Alert.alert("Error", response.errorMessage);
+					resolve([]);
+					return;
+				}
+				resolve(response.assets || []);
+			});
+		});
+	};
+
+	// Custom picker options
+	const pickerOptions = (accept) => {
+		const isImage = accept?.includes("image");
+		const isVideo = accept?.includes("video");
+		const isFile = accept?.includes("file");
+
+		return {
+			mediaType: isImage ? "photo" : isVideo ? "video" : "mixed",
+			quality: 0.8,
+			allowsMultiple: true,
+			selectionLimit: 10,
+		};
+	};
+
+	return (
+		<View style={{ flex: 1, justifyContent: "center", padding: 20 }}>
+			<Button
+				title="Open Media Gallery"
+				onPress={() => setIsOpen(true)}
+			/>
+
+			<MediaPopup
+				isOpen={isOpen}
+				onClose={() => setIsOpen(false)}
+				onSelect={handleSelect}
+				onError={handleError}
+				options={["image", "video", "file"]}
+				apiService={apiService}
+				picker={picker}
+				pickerOptions={pickerOptions}
+				icons={{
+					image: <CameraIcon />,
+					video: <VideoIcon />,
+					default: <UploadIcon />,
+				}}
+				bottomSheetHeight={0.9}
+				title="Select Media"
+			/>
+		</View>
+	);
+}
+
+export default App;
+```
+
+### Complete Web Example
+
+```jsx
+import React, { useState } from "react";
+import { MediaPopup, MediaApiService } from "@tradly/asset";
+
+function App() {
+	const [isOpen, setIsOpen] = useState(false);
+	const [selectedMedia, setSelectedMedia] = useState(null);
+
+	const apiService = new MediaApiService({
+		authKey: "your-tradly-auth-key",
+		bearerToken: "your-bearer-token",
+		// environment is auto-detected from process.env.ENVIRONMENT
+	});
+
+	const handleSelect = (mediaUrl) => {
+		setSelectedMedia(mediaUrl);
+		setIsOpen(false);
+		console.log("Selected:", mediaUrl);
+	};
+
+	return (
+		<div>
+			<button onClick={() => setIsOpen(true)}>
+				Open Media Gallery
+			</button>
+
+			<MediaPopup
+				isOpen={isOpen}
+				onClose={() => setIsOpen(false)}
+				onSelect={handleSelect}
+				options={["image", "video", "file"]}
+				apiService={apiService}
+			/>
+		</div>
+	);
+}
+
+export default App;
+```
+