react-native-unilist 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +103 -450
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,516 +1,169 @@
1
1
  # react-native-unilist
2
2
 
3
- **UniList** - The most powerful React Native list component that handles both FlatList and ScrollView seamlessly. This library provides everything you need to create beautiful, interactive lists with minimal code.
4
-
5
- ## 🚀 Features
6
-
7
- - **Dual Modes**: Supports both FlatList and ScrollView
8
- - **Smart Switching**: Automatically chooses FlatList or ScrollView based on props
9
- - **Pre-built Cards**: 5 card types with 5 design styles
10
- - **Layout System**: Grid, Masonry, and Carousel layouts
11
- - **Theme System**: Light, dark, and custom themes with color schemes
12
- - **Pagination**: Built-in pagination with loading states
13
- - **Search & Filter**: Built-in search functionality with highlighting
14
- - **Spacing Support**: Easily add spacing between items
15
- - **Loading States**: Support for loading indicators
16
- - **Empty States**: Custom UI for empty lists
17
- - **Imperative API**: Methods for programmatic scrolling
18
- - **Horizontal/Vertical**: Scroll support in both directions
19
- - **TypeScript Support**: Full TypeScript support
3
+ [![npm version](https://img.shields.io/npm/v/react-native-unilist.svg)](https://www.npmjs.com/package/react-native-unilist)
4
+ [![npm downloads](https://img.shields.io/npm/dm/react-native-unilist.svg)](https://www.npmjs.com/package/react-native-unilist)
5
+ [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
20
6
 
21
- ## 📦 Installation
7
+ > **The most powerful, flexible, and beautiful FlatList & ScrollView wrapper for React Native.**
22
8
 
23
- ```sh
24
- npm install react-native-unilist
25
- ```
9
+ ---
10
+
11
+ ## 🚀 Why use `react-native-unilist`?
26
12
 
27
- or
13
+ - **All-in-one**: FlatList, ScrollView, Grid, Masonry, Carousel, Cards, Pagination, Search, Themes, and more!
14
+ - **Super easy**: Minimal code, maximum features.
15
+ - **Beautiful UI**: Pre-built card designs, layouts, and theme system.
16
+ - **SEO Keywords**: React Native List, FlatList, ScrollView, Grid, Masonry, Carousel, Card, Pagination, Search, Theme, Universal List, Best List Library, react-native-unilist
28
17
 
29
- ```sh
18
+ ---
19
+
20
+ ## 📦 Installation
21
+
22
+ ```bash
23
+ npm install react-native-unilist
24
+ # or
30
25
  yarn add react-native-unilist
31
26
  ```
32
27
 
33
- ## 🎯 Quick Start
28
+ ---
34
29
 
35
- ### Basic Usage
30
+ ## ⚡ Quick Example
36
31
 
37
32
  ```jsx
38
- import React from 'react';
39
- import { Text, View } from 'react-native';
40
33
  import { UniList, ElevatedCard } from 'react-native-unilist';
41
34
 
42
- const MyComponent = () => {
43
- const data = [
44
- { id: 1, title: 'Card 1', subtitle: 'Subtitle 1', content: 'Content 1' },
45
- { id: 2, title: 'Card 2', subtitle: 'Subtitle 2', content: 'Content 2' },
46
- ];
47
-
48
- return (
49
- <UniList
50
- data={data}
51
- renderItem={(item) => (
52
- <ElevatedCard
53
- title={item.title}
54
- subtitle={item.subtitle}
55
- cardStyle="modern"
56
- >
57
- <Text>{item.content}</Text>
58
- </ElevatedCard>
59
- )}
60
- spacing={16}
61
- />
62
- );
63
- };
35
+ const data = [
36
+ { id: 1, title: 'Item 1', subtitle: 'Subtitle 1' },
37
+ { id: 2, title: 'Item 2', subtitle: 'Subtitle 2' },
38
+ ];
39
+
40
+ <UniList
41
+ data={data}
42
+ renderItem={item => (
43
+ <ElevatedCard title={item.title} subtitle={item.subtitle} />
44
+ )}
45
+ />
64
46
  ```
65
47
 
66
- ## 🎨 Card Components
48
+ ---
67
49
 
68
- ### Available Card Types
50
+ ## ✨ Features
69
51
 
70
- ```jsx
71
- import {
72
- ElevatedCard, // With shadow and elevation
73
- OutlinedCard, // With border
74
- FilledCard, // Solid background
75
- GradientCard, // Gradient background
76
- GlassCard // Glass effect
77
- } from 'react-native-unilist';
78
- ```
52
+ - **FlatList & ScrollView**: Smart switching, best performance
53
+ - **Pre-built Cards**: 5 types × 5 styles (Modern, Classic, Minimal, Material, Neumorphic)
54
+ - **Layouts**: Grid, Masonry, Carousel
55
+ - **Theme System**: Light/Dark + color schemes
56
+ - **Pagination**: Infinite scroll, loading states
57
+ - **Search & Filter**: Built-in hooks, highlight results
58
+ - **Horizontal/Vertical**: Both directions
59
+ - **Loading/Empty States**: Customizable
60
+ - **Imperative API**: Scroll to index/top
61
+ - **TypeScript Support**: Full types
62
+ - **SEO Optimized**: All major list keywords
79
63
 
80
- ### Card Styles
81
-
82
- ```jsx
83
- // 5 different design styles
84
- <ElevatedCard cardStyle="modern"> // Clean and modern
85
- <ElevatedCard cardStyle="classic"> // Traditional design
86
- <ElevatedCard cardStyle="minimal"> // Minimalist approach
87
- <ElevatedCard cardStyle="material"> // Material Design
88
- <ElevatedCard cardStyle="neumorphic"> // Neumorphic design
89
- ```
64
+ ---
90
65
 
91
- ### Card Usage Examples
66
+ ## 🖼️ Card & Layout Examples
92
67
 
93
68
  ```jsx
94
- // Basic card
95
- <ElevatedCard
96
- title="Card Title"
97
- subtitle="Card Subtitle"
98
- cardStyle="modern"
99
- >
100
- <Text>Card content goes here</Text>
101
- </ElevatedCard>
102
-
103
- // Custom styled card
104
- <GradientCard
105
- title="Custom Card"
106
- subtitle="With custom colors"
107
- backgroundColor="#FF6B6B"
108
- borderRadius={20}
109
- elevation={10}
110
- >
111
- <Text style={{ color: 'white' }}>Custom content</Text>
112
- </GradientCard>
113
- ```
114
-
115
- ## 📐 Layout System
69
+ import { ElevatedCard, OutlinedCard, GradientCard, GlassCard } from 'react-native-unilist';
116
70
 
117
- ### Grid Layout
71
+ <ElevatedCard title="Modern Card" cardStyle="modern">...</ElevatedCard>
72
+ <OutlinedCard title="Classic Card" cardStyle="classic">...</OutlinedCard>
73
+ <GradientCard title="Gradient Card" cardStyle="material">...</GradientCard>
74
+ <GlassCard title="Glass Card" cardStyle="neumorphic">...</GlassCard>
75
+ ```
118
76
 
77
+ **Grid Layout:**
119
78
  ```jsx
120
79
  import { GridLayout } from 'react-native-unilist';
121
-
122
- <GridLayout columns={2} spacing={16}>
123
- <ElevatedCard title="Item 1" />
124
- <ElevatedCard title="Item 2" />
125
- <ElevatedCard title="Item 3" />
126
- <ElevatedCard title="Item 4" />
127
- </GridLayout>
80
+ <GridLayout columns={2} spacing={12}>...</GridLayout>
128
81
  ```
129
82
 
130
- ### Carousel Layout
131
-
83
+ **Carousel Layout:**
132
84
  ```jsx
133
85
  import { CarouselLayout } from 'react-native-unilist';
134
-
135
- <CarouselLayout
136
- autoplay={true}
137
- interval={3000}
138
- showDots={true}
139
- itemWidth={300}
140
- >
141
- <ElevatedCard title="Slide 1" />
142
- <ElevatedCard title="Slide 2" />
143
- <ElevatedCard title="Slide 3" />
144
- </CarouselLayout>
86
+ <CarouselLayout autoplay interval={3000} showDots>...</CarouselLayout>
145
87
  ```
146
88
 
147
- ### Masonry Layout
148
-
89
+ **Masonry Layout:**
149
90
  ```jsx
150
91
  import { MasonryLayout } from 'react-native-unilist';
151
-
152
- <MasonryLayout columns={3} spacing={8}>
153
- <ElevatedCard title="Item 1" />
154
- <ElevatedCard title="Item 2" />
155
- <ElevatedCard title="Item 3" />
156
- </MasonryLayout>
92
+ <MasonryLayout columns={2} spacing={8}>...</MasonryLayout>
157
93
  ```
158
94
 
159
- ## 🎨 Theme System
95
+ ---
160
96
 
161
- ### Using Themes
97
+ ## 🎨 Theme System
162
98
 
163
99
  ```jsx
164
100
  import { ThemeManager, useTheme } from 'react-native-unilist';
165
-
166
- // Set theme
167
101
  ThemeManager.getInstance().setThemeType('dark', 'blue');
168
-
169
- // Use theme in component
170
- const MyComponent = () => {
171
- const theme = useTheme();
172
-
173
- return (
174
- <ElevatedCard
175
- style={{ backgroundColor: theme.colors.surface }}
176
- >
177
- <Text style={{ color: theme.colors.text }}>
178
- Themed content
179
- </Text>
180
- </ElevatedCard>
181
- );
182
- };
102
+ const theme = useTheme();
183
103
  ```
184
104
 
185
- ### Available Themes
186
-
187
- ```jsx
188
- // Theme types
189
- ThemeManager.getInstance().setThemeType('light', 'blue');
190
- ThemeManager.getInstance().setThemeType('dark', 'purple');
191
- ThemeManager.getInstance().setThemeType('light', 'green');
192
-
193
- // Custom theme
194
- ThemeManager.getInstance().setCustomTheme({
195
- primary: '#FF0000',
196
- secondary: '#00FF00',
197
- background: '#000000',
198
- });
199
- ```
200
-
201
- ## 📄 Pagination
105
+ ---
202
106
 
203
- ### Using Pagination Hook
107
+ ## 🔍 Pagination & Search
204
108
 
109
+ **Pagination:**
205
110
  ```jsx
206
111
  import { usePagination } from 'react-native-unilist';
207
-
208
- const MyComponent = () => {
209
- const {
210
- data,
211
- loading,
212
- hasMore,
213
- loadMore,
214
- refresh
215
- } = usePagination({
216
- pageSize: 20,
217
- onLoadMore: async (page) => {
218
- // Fetch data from API
219
- const response = await fetch(`/api/items?page=${page}`);
220
- return response.json();
221
- }
222
- });
223
-
224
- return (
225
- <UniList
226
- data={data}
227
- renderItem={(item) => <ElevatedCard title={item.title} />}
228
- onEndReached={hasMore ? loadMore : undefined}
229
- onEndReachedThreshold={0.5}
230
- ListFooterComponent={
231
- loading ? <ActivityIndicator size="large" /> : null
232
- }
233
- />
234
- );
235
- };
112
+ const { data, loading, hasMore, loadMore } = usePagination({ ... });
236
113
  ```
237
114
 
238
- ## 🔍 Search & Filter
239
-
240
- ### Using Search Hook
241
-
115
+ **Search:**
242
116
  ```jsx
243
117
  import { useSearch } from 'react-native-unilist';
244
-
245
- const MyComponent = () => {
246
- const {
247
- query,
248
- results,
249
- setQuery,
250
- clearSearch
251
- } = useSearch({
252
- data: originalData,
253
- searchFields: ['title', 'subtitle', 'content'],
254
- debounceMs: 300,
255
- highlightResults: true
256
- });
257
-
258
- return (
259
- <View>
260
- <TextInput
261
- value={query}
262
- onChangeText={setQuery}
263
- placeholder="Search items..."
264
- />
265
- <UniList
266
- data={results}
267
- renderItem={(item) => <ElevatedCard title={item.title} />}
268
- />
269
- </View>
270
- );
271
- };
272
- ```
273
-
274
- ## 🎯 Advanced Usage Examples
275
-
276
- ### 1. Complete App with All Features
277
-
278
- ```jsx
279
- import React, { useState } from 'react';
280
- import { View, Text, TextInput, ActivityIndicator } from 'react-native';
281
- import {
282
- UniList,
283
- ElevatedCard,
284
- GridLayout,
285
- usePagination,
286
- useSearch,
287
- ThemeManager
288
- } from 'react-native-unilist';
289
-
290
- const App = () => {
291
- // Set theme
292
- React.useEffect(() => {
293
- ThemeManager.getInstance().setThemeType('dark', 'blue');
294
- }, []);
295
-
296
- // Pagination
297
- const {
298
- data,
299
- loading,
300
- hasMore,
301
- loadMore
302
- } = usePagination({
303
- pageSize: 10,
304
- onLoadMore: async (page) => {
305
- // Simulate API call
306
- await new Promise(resolve => setTimeout(resolve, 1000));
307
- return Array.from({ length: 10 }, (_, i) => ({
308
- id: page * 10 + i,
309
- title: `Item ${page * 10 + i}`,
310
- subtitle: `Subtitle ${page * 10 + i}`,
311
- content: `Content for item ${page * 10 + i}`
312
- }));
313
- }
314
- });
315
-
316
- // Search
317
- const {
318
- query,
319
- results,
320
- setQuery
321
- } = useSearch({
322
- data,
323
- searchFields: ['title', 'subtitle'],
324
- debounceMs: 300
325
- });
326
-
327
- return (
328
- <View style={{ flex: 1, padding: 16 }}>
329
- <TextInput
330
- value={query}
331
- onChangeText={setQuery}
332
- placeholder="Search items..."
333
- style={{ padding: 12, borderWidth: 1, borderRadius: 8, marginBottom: 16 }}
334
- />
335
-
336
- <UniList
337
- data={results}
338
- renderItem={(item) => (
339
- <ElevatedCard
340
- title={item.title}
341
- subtitle={item.subtitle}
342
- cardStyle="modern"
343
- >
344
- <Text>{item.content}</Text>
345
- </ElevatedCard>
346
- )}
347
- spacing={16}
348
- onEndReached={hasMore ? loadMore : undefined}
349
- onEndReachedThreshold={0.5}
350
- ListFooterComponent={
351
- loading ? (
352
- <View style={{ padding: 20, alignItems: 'center' }}>
353
- <ActivityIndicator size="large" />
354
- </View>
355
- ) : null
356
- }
357
- />
358
- </View>
359
- );
360
- };
118
+ const { query, results, setQuery } = useSearch({ ... });
361
119
  ```
362
120
 
363
- ### 2. Grid Layout with Cards
364
-
365
- ```jsx
366
- import React from 'react';
367
- import { View, Dimensions } from 'react-native';
368
- import { UniList, ElevatedCard } from 'react-native-unilist';
369
-
370
- const MyComponent = () => {
371
- const { width } = Dimensions.get('window');
372
- const cardWidth = (width - 48) / 2;
373
-
374
- const data = Array.from({ length: 20 }, (_, i) => ({
375
- id: i + 1,
376
- title: `Card ${i + 1}`,
377
- subtitle: `Subtitle ${i + 1}`,
378
- }));
379
-
380
- return (
381
- <UniList
382
- data={data}
383
- renderItem={(item) => (
384
- <View style={{ width: cardWidth }}>
385
- <ElevatedCard
386
- title={item.title}
387
- subtitle={item.subtitle}
388
- cardStyle="minimal"
389
- style={{ margin: 8 }}
390
- />
391
- </View>
392
- )}
393
- spacing={8}
394
- contentContainerStyle={{ padding: 16 }}
395
- />
396
- );
397
- };
398
- ```
399
-
400
- ### 3. Horizontal Carousel
401
-
402
- ```jsx
403
- import React from 'react';
404
- import { View, Dimensions } from 'react-native';
405
- import { UniList, GlassCard } from 'react-native-unilist';
406
-
407
- const MyComponent = () => {
408
- const { width } = Dimensions.get('window');
409
- const cardWidth = width * 0.8;
410
-
411
- const data = [
412
- { id: 1, title: 'Featured 1', subtitle: 'Premium content' },
413
- { id: 2, title: 'Featured 2', subtitle: 'Premium content' },
414
- { id: 3, title: 'Featured 3', subtitle: 'Premium content' },
415
- ];
416
-
417
- return (
418
- <View style={{ height: 200 }}>
419
- <UniList
420
- data={data}
421
- horizontal={true}
422
- renderItem={(item) => (
423
- <View style={{ width: cardWidth }}>
424
- <GlassCard
425
- title={item.title}
426
- subtitle={item.subtitle}
427
- cardStyle="modern"
428
- style={{ margin: 16 }}
429
- />
430
- </View>
431
- )}
432
- spacing={16}
433
- showsHorizontalScrollIndicator={false}
434
- pagingEnabled={true}
435
- />
436
- </View>
437
- );
438
- };
439
- ```
440
-
441
- ## 📋 Props Reference
442
-
443
- ### UniListProps
444
-
445
- | Prop | Type | Description |
446
- |------|------|-------------|
447
- | `data` | `ItemT[]` | Data array - triggers FlatList mode |
448
- | `renderItem` | `(item: ItemT, index: number) => ReactElement` | Function to render items in FlatList mode |
449
- | `children` | `ReactNode` | Static children for ScrollView mode |
450
- | `spacing` | `number` | Spacing between items (in px) |
451
- | `horizontal` | `boolean` | For horizontal scrolling |
452
- | `ListEmptyComponent` | `ReactElement` | Custom component for empty state |
453
- | `loading` | `boolean` | Loading state |
454
- | `contentContainerStyle` | `StyleProp<ViewStyle>` | Custom container styling |
455
-
456
- ### CardProps
457
-
458
- | Prop | Type | Description |
459
- |------|------|-------------|
460
- | `type` | `CardType` | Card type: elevated, outlined, filled, gradient, glass |
461
- | `cardStyle` | `CardStyle` | Design style: modern, classic, minimal, material, neumorphic |
462
- | `title` | `string` | Card title |
463
- | `subtitle` | `string` | Card subtitle |
464
- | `children` | `ReactNode` | Card content |
465
- | `backgroundColor` | `string` | Custom background color |
466
- | `borderRadius` | `number` | Custom border radius |
467
- | `elevation` | `number` | Shadow elevation (Android) |
468
-
469
- ### UniListRef (Imperative API)
470
-
471
- | Method | Parameters | Description |
472
- |--------|------------|-------------|
473
- | `scrollToIndex` | `{ index: number, animated?: boolean }` | Scroll to specific index (FlatList only) |
474
- | `scrollToTop` | `animated?: boolean` | Scroll to top |
475
-
476
- ## 🔄 Mode Switching Logic
477
-
478
- UniList automatically switches between two modes:
479
-
480
- 1. **FlatList Mode**: When both `data` and `renderItem` are provided
481
- 2. **ScrollView Mode**: When `data` is undefined and `children` are provided
482
-
483
- ## 🎨 Styling Tips
484
-
485
- - Use `spacing` prop for consistent spacing between items
486
- - Use `contentContainerStyle` for container styling
487
- - Set `width` and `height` properly with `horizontal` prop
488
- - Use individual item styling for custom shadows and borders
489
- - Leverage the theme system for consistent colors and spacing
121
+ ---
490
122
 
491
- ## 🚀 Performance Tips
123
+ ## 📝 Props Reference
124
+
125
+ ### UniList
126
+ | Prop | Type | Description |
127
+ |---------------------|-------------------------------------|-----------------------------------|
128
+ | data | array | List data |
129
+ | renderItem | function(item, index) => ReactNode | Render each item |
130
+ | children | ReactNode | For ScrollView mode |
131
+ | spacing | number | Space between items |
132
+ | horizontal | boolean | Horizontal scroll |
133
+ | ListEmptyComponent | ReactNode | Empty state UI |
134
+ | loading | boolean | Loading state |
135
+ | contentContainerStyle| style | Container style |
136
+
137
+ ### Card
138
+ | Prop | Type | Description |
139
+ |--------------|-----------|-----------------------------------|
140
+ | type | string | elevated, outlined, filled, ... |
141
+ | cardStyle | string | modern, classic, minimal, ... |
142
+ | title | string | Card title |
143
+ | subtitle | string | Card subtitle |
144
+ | children | ReactNode | Card content |
145
+ | ... | ... | ... |
492
146
 
493
- - Use FlatList mode for large lists
494
- - Optimize `keyExtractor` function for unique keys
495
- - Use `getItemLayout` for fixed height items
496
- - Use `windowSize` and `maxToRenderPerBatch` props for performance tuning
497
- - Implement pagination for large datasets
498
- - Use search debouncing to avoid excessive filtering
147
+ ---
499
148
 
500
- ## 📱 Platform Support
149
+ ## 📚 More Examples
150
+ - [See USAGE_EXAMPLES.md for advanced usage](./USAGE_EXAMPLES.md)
151
+ - [See Example App](./SampleProject/App.tsx)
501
152
 
502
- - ✅ iOS
503
- - ✅ Android
504
- - ✅ Web (React Native Web)
153
+ ---
505
154
 
506
155
  ## 🤝 Contributing
156
+ Pull requests welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md).
507
157
 
508
- See the [contributing guide](CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow.
158
+ ---
509
159
 
510
160
  ## 📄 License
511
-
512
161
  MIT
513
162
 
514
163
  ---
515
164
 
516
- Made with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)
165
+ **Keywords:** react-native, FlatList, ScrollView, List, Grid, Masonry, Carousel, Card, Pagination, Search, Theme, Universal List, Best List Library, react-native-unilist
166
+
167
+ ---
168
+
169
+ Made with ❤️ by [SamadK01](https://github.com/SamadK01)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "react-native-unilist",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "Beautiful FlatList and ScrollView wrapper for React Native",
5
5
  "main": "lib/module/index.js",
6
6
  "module": "lib/module/index.js",