@pushwoosh/dumb-components 1.1.148 → 1.1.149

package/Pagination/ai-documentation.md

@@ -1,509 +0,0 @@
-# Pagination Component - @pushwoosh/dumb-components
-
-## Overview
-
-- **Component Name**: Pagination
-- **Import Path**: `@pushwoosh/dumb-components`
-- **Files**:
-  - `/src/Pagination/Pagination.tsx` - Main component implementation
-  - `/src/Pagination/types.ts` - TypeScript type definitions
-  - `/src/Pagination/styles.ts` - Styled components
-  - `/src/Pagination/helpers.ts` - Helper utilities
-  - `/src/Pagination/index.ts` - Component exports
-- **Type**: Navigation
-- **Description**: A pagination component for navigating through multiple pages of content. Features smart page number display, ellipsis for large page ranges, navigation arrows, and loading states.
-
-## TypeScript Interfaces
-
-```typescript
-export type PaginationProps = Omit<JSX.IntrinsicElements['div'], 'ref'> & {
-  readonly boxRef?: Ref<HTMLDivElement>;
-  readonly activePage: string | number;
-  readonly totalPages: string | number;
-  readonly adjacentPagesCount?: number;
-  readonly isLoading?: boolean;
-  readonly onChangePage: (page: number) => any;
-};
-```
-
-## Import & Usage
-
-```typescript
-import { Pagination } from '@pushwoosh/dumb-components';
-
-// Basic usage
-function MyComponent() {
-  const [currentPage, setCurrentPage] = useState(1);
-  const totalPages = 10;
-
-  return (
-    <div>
-      {/* Your content */}
-      <div>Page {currentPage} content...</div>
-      
-      {/* Pagination */}
-      <Pagination
-        activePage={currentPage}
-        totalPages={totalPages}
-        onChangePage={setCurrentPage}
-      />
-    </div>
-  );
-}
-
-// With loading state
-function LoadingPagination() {
-  const [currentPage, setCurrentPage] = useState(1);
-  const [isLoading, setIsLoading] = useState(false);
-  const totalPages = 25;
-
-  const handlePageChange = async (page: number) => {
-    setIsLoading(true);
-    try {
-      await fetchPageData(page);
-      setCurrentPage(page);
-    } catch (error) {
-      console.error('Failed to load page:', error);
-    } finally {
-      setIsLoading(false);
-    }
-  };
-
-  return (
-    <Pagination
-      activePage={currentPage}
-      totalPages={totalPages}
-      isLoading={isLoading}
-      onChangePage={handlePageChange}
-    />
-  );
-}
-```
-
-## Advanced Examples
-
-```typescript
-// Data table with pagination
-function DataTable() {
-  const [currentPage, setCurrentPage] = useState(1);
-  const [data, setData] = useState([]);
-  const [totalCount, setTotalCount] = useState(0);
-  const [isLoading, setIsLoading] = useState(false);
-  
-  const itemsPerPage = 10;
-  const totalPages = Math.ceil(totalCount / itemsPerPage);
-
-  const loadData = async (page: number) => {
-    setIsLoading(true);
-    try {
-      const response = await fetchData({
-        page,
-        limit: itemsPerPage
-      });
-      setData(response.data);
-      setTotalCount(response.total);
-    } catch (error) {
-      console.error('Failed to load data:', error);
-    } finally {
-      setIsLoading(false);
-    }
-  };
-
-  useEffect(() => {
-    loadData(currentPage);
-  }, [currentPage]);
-
-  const handlePageChange = (page: number) => {
-    setCurrentPage(page);
-    // Optionally scroll to top
-    window.scrollTo({ top: 0, behavior: 'smooth' });
-  };
-
-  return (
-    <div>
-      <table>
-        <thead>
-          <tr>
-            <th>ID</th>
-            <th>Name</th>
-            <th>Email</th>
-            <th>Status</th>
-          </tr>
-        </thead>
-        <tbody>
-          {isLoading ? (
-            <tr>
-              <td colSpan={4}>Loading...</td>
-            </tr>
-          ) : (
-            data.map(item => (
-              <tr key={item.id}>
-                <td>{item.id}</td>
-                <td>{item.name}</td>
-                <td>{item.email}</td>
-                <td>{item.status}</td>
-              </tr>
-            ))
-          )}
-        </tbody>
-      </table>
-
-      {totalPages > 1 && (
-        <div style={{ marginTop: '20px', display: 'flex', justifyContent: 'center' }}>
-          <Pagination
-            activePage={currentPage}
-            totalPages={totalPages}
-            isLoading={isLoading}
-            onChangePage={handlePageChange}
-          />
-        </div>
-      )}
-    </div>
-  );
-}
-
-// Search results with pagination
-function SearchResults() {
-  const [query, setQuery] = useState('');
-  const [currentPage, setCurrentPage] = useState(1);
-  const [results, setResults] = useState([]);
-  const [totalResults, setTotalResults] = useState(0);
-  const [isSearching, setIsSearching] = useState(false);
-
-  const resultsPerPage = 20;
-  const totalPages = Math.ceil(totalResults / resultsPerPage);
-
-  const performSearch = async (searchQuery: string, page: number) => {
-    if (!searchQuery.trim()) {
-      setResults([]);
-      setTotalResults(0);
-      return;
-    }
-
-    setIsSearching(true);
-    try {
-      const response = await searchAPI({
-        query: searchQuery,
-        page,
-        limit: resultsPerPage
-      });
-      setResults(response.results);
-      setTotalResults(response.totalCount);
-    } catch (error) {
-      console.error('Search failed:', error);
-      setResults([]);
-      setTotalResults(0);
-    } finally {
-      setIsSearching(false);
-    }
-  };
-
-  // Search when query changes
-  useEffect(() => {
-    setCurrentPage(1);
-    performSearch(query, 1);
-  }, [query]);
-
-  // Load new page
-  const handlePageChange = (page: number) => {
-    setCurrentPage(page);
-    performSearch(query, page);
-  };
-
-  return (
-    <div>
-      <input
-        type="text"
-        placeholder="Search..."
-        value={query}
-        onChange={(e) => setQuery(e.target.value)}
-      />
-
-      <div>
-        {isSearching ? (
-          <div>Searching...</div>
-        ) : (
-          <div>
-            <p>{totalResults} results found</p>
-            {results.map(result => (
-              <div key={result.id} style={{ padding: '10px', borderBottom: '1px solid #eee' }}>
-                <h3>{result.title}</h3>
-                <p>{result.description}</p>
-              </div>
-            ))}
-          </div>
-        )}
-      </div>
-
-      {totalPages > 1 && (
-        <Pagination
-          activePage={currentPage}
-          totalPages={totalPages}
-          isLoading={isSearching}
-          onChangePage={handlePageChange}
-        />
-      )}
-    </div>
-  );
-}
-
-// Custom adjacent pages count
-function CustomPagination() {
-  const [currentPage, setCurrentPage] = useState(1);
-  const totalPages = 100;
-
-  return (
-    <div>
-      <h3>Default Adjacent Pages (2)</h3>
-      <Pagination
-        activePage={currentPage}
-        totalPages={totalPages}
-        onChangePage={setCurrentPage}
-      />
-
-      <h3>More Adjacent Pages (5)</h3>
-      <Pagination
-        activePage={currentPage}
-        totalPages={totalPages}
-        adjacentPagesCount={5}
-        onChangePage={setCurrentPage}
-      />
-
-      <h3>Fewer Adjacent Pages (1)</h3>
-      <Pagination
-        activePage={currentPage}
-        totalPages={totalPages}
-        adjacentPagesCount={1}
-        onChangePage={setCurrentPage}
-      />
-    </div>
-  );
-}
-
-// URL-synced pagination
-function URLSyncedPagination() {
-  const [searchParams, setSearchParams] = useSearchParams();
-  const currentPage = parseInt(searchParams.get('page') || '1', 10);
-  const [data, setData] = useState([]);
-  const [totalPages, setTotalPages] = useState(0);
-  const [isLoading, setIsLoading] = useState(false);
-
-  const handlePageChange = (page: number) => {
-    setSearchParams({ page: page.toString() });
-  };
-
-  const loadPageData = async (page: number) => {
-    setIsLoading(true);
-    try {
-      const response = await fetchPageData(page);
-      setData(response.data);
-      setTotalPages(response.totalPages);
-    } catch (error) {
-      console.error('Failed to load page:', error);
-    } finally {
-      setIsLoading(false);
-    }
-  };
-
-  useEffect(() => {
-    loadPageData(currentPage);
-  }, [currentPage]);
-
-  return (
-    <div>
-      <div>
-        {isLoading ? (
-          <div>Loading page {currentPage}...</div>
-        ) : (
-          <div>
-            <h2>Page {currentPage} Data</h2>
-            {data.map(item => (
-              <div key={item.id}>{item.name}</div>
-            ))}
-          </div>
-        )}
-      </div>
-
-      {totalPages > 1 && (
-        <Pagination
-          activePage={currentPage}
-          totalPages={totalPages}
-          isLoading={isLoading}
-          onChangePage={handlePageChange}
-        />
-      )}
-    </div>
-  );
-}
-
-// Form with pagination for long lists
-function FormWithPagination() {
-  const [selectedItems, setSelectedItems] = useState<number[]>([]);
-  const [currentPage, setCurrentPage] = useState(1);
-  const [allItems, setAllItems] = useState<any[]>([]);
-  
-  const itemsPerPage = 5;
-  const totalPages = Math.ceil(allItems.length / itemsPerPage);
-  const startIndex = (currentPage - 1) * itemsPerPage;
-  const currentItems = allItems.slice(startIndex, startIndex + itemsPerPage);
-
-  const toggleItemSelection = (itemId: number) => {
-    setSelectedItems(prev => 
-      prev.includes(itemId)
-        ? prev.filter(id => id !== itemId)
-        : [...prev, itemId]
-    );
-  };
-
-  const handleSubmit = () => {
-    console.log('Selected items:', selectedItems);
-    // Process selected items
-  };
-
-  return (
-    <form>
-      <h3>Select Items ({selectedItems.length} selected)</h3>
-      
-      <div>
-        {currentItems.map(item => (
-          <label key={item.id} style={{ display: 'block', padding: '8px' }}>
-            <input
-              type="checkbox"
-              checked={selectedItems.includes(item.id)}
-              onChange={() => toggleItemSelection(item.id)}
-            />
-            {item.name}
-          </label>
-        ))}
-      </div>
-
-      {totalPages > 1 && (
-        <Pagination
-          activePage={currentPage}
-          totalPages={totalPages}
-          onChangePage={setCurrentPage}
-        />
-      )}
-
-      <button type="button" onClick={handleSubmit}>
-        Submit Selected ({selectedItems.length})
-      </button>
-    </form>
-  );
-}
-```
-
-## Props Reference
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| `boxRef` | `Ref<HTMLDivElement>` | `undefined` | No | Ref for the pagination container |
-| `activePage` | `string \| number` | - | Yes | Currently active page number |
-| `totalPages` | `string \| number` | - | Yes | Total number of pages |
-| `adjacentPagesCount` | `number` | `2` | No | Number of pages to show on each side of active page |
-| `isLoading` | `boolean` | `false` | No | Whether pagination is in loading state |
-| `onChangePage` | `(page: number) => any` | - | Yes | Callback fired when page changes |
-
-## AI Agent Guidelines
-
-### Recommended Patterns
-
-1. **Controlled State**: Always manage pagination state in parent component
-```typescript
-const [currentPage, setCurrentPage] = useState(1);
-
-<Pagination
-  activePage={currentPage}
-  totalPages={totalPages}
-  onChangePage={setCurrentPage}
-/>
-```
-
-2. **Loading States**: Handle async page changes properly
-```typescript
-const [isLoading, setIsLoading] = useState(false);
-
-const handlePageChange = async (page: number) => {
-  setIsLoading(true);
-  await loadPageData(page);
-  setIsLoading(false);
-  setCurrentPage(page);
-};
-```
-
-3. **URL Synchronization**: Sync pagination with browser URL for better UX
-```typescript
-const [searchParams, setSearchParams] = useSearchParams();
-const page = parseInt(searchParams.get('page') || '1', 10);
-
-const handlePageChange = (newPage: number) => {
-  setSearchParams({ page: newPage.toString() });
-};
-```
-
-### Common Mistakes to Avoid
-
-1. **Invalid Page Numbers**: Don't pass page numbers outside valid range (1 to totalPages)
-2. **Missing Loading States**: Always disable pagination during data loading
-3. **Inconsistent State**: Ensure activePage and displayed data are synchronized
-4. **Memory Leaks**: Cancel pending requests when component unmounts or page changes
-5. **Poor Performance**: Don't reload all data when only page changes
-
-### Integration Tips
-
-1. **Data Management**: Works well with server-side pagination
-```typescript
-// Server-side pagination
-const response = await fetchData({
-  page: currentPage,
-  limit: itemsPerPage,
-  sort: 'createdAt',
-  order: 'desc'
-});
-```
-
-2. **Search Integration**: Reset to page 1 when search query changes
-```typescript
-useEffect(() => {
-  setCurrentPage(1); // Reset to first page
-  performSearch(query);
-}, [query]);
-```
-
-3. **Form Integration**: Preserve selections across pages
-```typescript
-const [globalSelections, setGlobalSelections] = useState(new Set());
-
-// Maintain selections when changing pages
-const handlePageChange = (page: number) => {
-  // Save current page selections
-  saveCurrentPageSelections();
-  // Load new page
-  setCurrentPage(page);
-};
-```
-
-4. **Accessibility**: Component handles keyboard navigation automatically
-5. **Performance Optimization**: Use React.memo for list items to prevent unnecessary re-renders
-
-6. **Error Handling**: Handle pagination errors gracefully
-```typescript
-const handlePageChange = async (page: number) => {
-  try {
-    await loadPageData(page);
-    setCurrentPage(page);
-  } catch (error) {
-    // Stay on current page if load fails
-    console.error('Failed to load page:', error);
-    // Optionally show error message to user
-  }
-};
-```
-
-## Related Components
-
-- **Button**: Used internally for page navigation buttons
-- **Spinner**: Often used together for loading states
-- **Table**: Commonly used with data tables
-- **Select**: Alternative for page size selection
-- **Input**: For jump-to-page functionality