@delightui/components 0.1.104 → 0.1.106

package/docs/components/molecules/PaginationNumberField.md

@@ -0,0 +1,722 @@
+# PaginationNumberField
+
+## Description
+
+A specialized number input component designed for pagination controls. Allows users to directly enter a page number for quick navigation, with built-in validation, bounds checking, and integration with pagination state management.
+
+## Aliases
+
+- PaginationNumberField
+- PageNumberInput
+- PageJumpField
+- PageInput
+- NavigationNumberField
+
+## Props Breakdown
+
+**Extends:** Standalone interface (no HTML element inheritance)
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `className` | `string` | - | No | Additional CSS class names for custom styling |
+| `page` | `number` | - | No | Current page number value |
+| `totalPages` | `number` | - | No | Maximum page number allowed |
+| `onPageChanged` | `(page: number) => void` | - | No | Callback function when page number changes |
+
+## Examples
+
+### Basic Usage
+```tsx
+import { PaginationNumberField } from '@delightui/components';
+
+function BasicExample() {
+  const [currentPage, setCurrentPage] = useState(1);
+  const totalPages = 10;
+
+  return (
+    <div className="pagination-controls">
+      <Text>Go to page:</Text>
+      <PaginationNumberField
+        page={currentPage}
+        totalPages={totalPages}
+        onPageChanged={setCurrentPage}
+      />
+      <Text>of {totalPages}</Text>
+    </div>
+  );
+}
+```
+
+### Integrated with Pagination
+```tsx
+function IntegratedPaginationExample() {
+  const [currentPage, setCurrentPage] = useState(1);
+  const totalPages = 25;
+  const totalItems = 247;
+  const itemsPerPage = 10;
+
+  const startItem = (currentPage - 1) * itemsPerPage + 1;
+  const endItem = Math.min(currentPage * itemsPerPage, totalItems);
+
+  return (
+    <div className="integrated-pagination">
+      <div className="content-area">
+        <Text type="Heading4">Page {currentPage} Content</Text>
+        <Text type="BodyMedium">
+          Showing items {startItem}-{endItem} of {totalItems}
+        </Text>
+      </div>
+
+      <div className="pagination-bar">
+        <Pagination
+          currentPage={currentPage}
+          totalPages={totalPages}
+          updateCurrentPage={setCurrentPage}
+        />
+        
+        <div className="page-jump">
+          <Text type="BodySmall">Jump to:</Text>
+          <PaginationNumberField
+            page={currentPage}
+            totalPages={totalPages}
+            onPageChanged={setCurrentPage}
+          />
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+### Search Results with Page Jump
+```tsx
+function SearchResultsExample() {
+  const [currentPage, setCurrentPage] = useState(1);
+  const [searchTerm, setSearchTerm] = useState('React');
+  const [resultsPerPage, setResultsPerPage] = useState(10);
+  
+  const totalResults = 156;
+  const totalPages = Math.ceil(totalResults / resultsPerPage);
+
+  const mockResults = Array.from({ length: resultsPerPage }, (_, index) => ({
+    id: (currentPage - 1) * resultsPerPage + index + 1,
+    title: `${searchTerm} Tutorial ${(currentPage - 1) * resultsPerPage + index + 1}`,
+    description: 'Comprehensive guide to modern development practices...',
+    category: 'Tutorial'
+  }));
+
+  return (
+    <div className="search-results-example">
+      <div className="search-header">
+        <Input 
+          placeholder="Search tutorials..."
+          value={searchTerm}
+          onValueChange={setSearchTerm}
+          leadingIcon={<Icon icon="Search" />}
+        />
+        
+        <div className="results-info">
+          <Text type="BodySmall">
+            {totalResults} results found
+          </Text>
+          
+          <Select value={resultsPerPage} onValueChange={setResultsPerPage}>
+            <Option value={5}>5 per page</Option>
+            <Option value={10}>10 per page</Option>
+            <Option value={20}>20 per page</Option>
+          </Select>
+        </div>
+      </div>
+
+      <div className="search-results">
+        {mockResults.map(result => (
+          <Card key={result.id} className="result-card">
+            <div className="result-header">
+              <Text type="Heading6">{result.title}</Text>
+              <Chip size="Small">{result.category}</Chip>
+            </div>
+            <Text type="BodyMedium">{result.description}</Text>
+          </Card>
+        ))}
+      </div>
+
+      <div className="search-pagination">
+        <Pagination
+          currentPage={currentPage}
+          totalPages={totalPages}
+          updateCurrentPage={setCurrentPage}
+        />
+        
+        <div className="quick-navigation">
+          <Text type="BodySmall">Page:</Text>
+          <PaginationNumberField
+            page={currentPage}
+            totalPages={totalPages}
+            onPageChanged={setCurrentPage}
+            className="compact-field"
+          />
+          <Text type="BodySmall">of {totalPages}</Text>
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+### Data Table with Page Jump
+```tsx
+function DataTableExample() {
+  const [currentPage, setCurrentPage] = useState(1);
+  const [sortBy, setSortBy] = useState('id');
+  const [sortOrder, setSortOrder] = useState('asc');
+  
+  const rowsPerPage = 15;
+  const totalRows = 342;
+  const totalPages = Math.ceil(totalRows / rowsPerPage);
+
+  const mockData = Array.from({ length: rowsPerPage }, (_, index) => {
+    const id = (currentPage - 1) * rowsPerPage + index + 1;
+    return {
+      id,
+      name: `User ${id}`,
+      email: `user${id}@example.com`,
+      status: ['Active', 'Inactive', 'Pending'][Math.floor(Math.random() * 3)],
+      lastLogin: '2024-01-15'
+    };
+  });
+
+  return (
+    <div className="data-table-example">
+      <div className="table-controls">
+        <div className="sort-controls">
+          <Select value={sortBy} onValueChange={setSortBy}>
+            <Option value="id">Sort by ID</Option>
+            <Option value="name">Sort by Name</Option>
+            <Option value="email">Sort by Email</Option>
+            <Option value="status">Sort by Status</Option>
+          </Select>
+          
+          <Select value={sortOrder} onValueChange={setSortOrder}>
+            <Option value="asc">Ascending</Option>
+            <Option value="desc">Descending</Option>
+          </Select>
+        </div>
+        
+        <Text type="BodySmall">
+          {totalRows} total records
+        </Text>
+      </div>
+
+      <Table className="data-table">
+        <TableHeader>
+          <TableHeaderCell>ID</TableHeaderCell>
+          <TableHeaderCell>Name</TableHeaderCell>
+          <TableHeaderCell>Email</TableHeaderCell>
+          <TableHeaderCell>Status</TableHeaderCell>
+          <TableHeaderCell>Last Login</TableHeaderCell>
+        </TableHeader>
+        <TableBody>
+          {mockData.map(row => (
+            <TableRow key={row.id}>
+              <TableCell>{row.id}</TableCell>
+              <TableCell>{row.name}</TableCell>
+              <TableCell>{row.email}</TableCell>
+              <TableCell>
+                <Chip 
+                  size="Small" 
+                  style={row.status === 'Active' ? 'Success' : row.status === 'Pending' ? 'Warning' : 'Default'}
+                >
+                  {row.status}
+                </Chip>
+              </TableCell>
+              <TableCell>{row.lastLogin}</TableCell>
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+
+      <div className="table-pagination">
+        <div className="pagination-info">
+          <Text type="BodySmall">
+            Showing {(currentPage - 1) * rowsPerPage + 1}-{Math.min(currentPage * rowsPerPage, totalRows)} of {totalRows}
+          </Text>
+        </div>
+        
+        <div className="pagination-controls">
+          <Pagination
+            currentPage={currentPage}
+            totalPages={totalPages}
+            updateCurrentPage={setCurrentPage}
+          />
+          
+          <div className="page-jump-controls">
+            <Text type="BodySmall">Go to:</Text>
+            <PaginationNumberField
+              page={currentPage}
+              totalPages={totalPages}
+              onPageChanged={setCurrentPage}
+            />
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+### Advanced Navigation Controls
+```tsx
+function AdvancedNavigationExample() {
+  const [currentPage, setCurrentPage] = useState(1);
+  const [jumpToPage, setJumpToPage] = useState('');
+  const [pageHistory, setPageHistory] = useState([1]);
+  const totalPages = 50;
+
+  const handlePageChange = (newPage) => {
+    setCurrentPage(newPage);
+    setPageHistory(prev => [...prev.slice(-9), newPage]); // Keep last 10 pages
+  };
+
+  const goToFirstPage = () => handlePageChange(1);
+  const goToLastPage = () => handlePageChange(totalPages);
+  
+  const goToRandomPage = () => {
+    const randomPage = Math.floor(Math.random() * totalPages) + 1;
+    handlePageChange(randomPage);
+  };
+
+  return (
+    <div className="advanced-navigation">
+      <div className="navigation-controls">
+        <div className="quick-actions">
+          <Button onClick={goToFirstPage} size="Small">
+            First Page
+          </Button>
+          <Button onClick={goToLastPage} size="Small">
+            Last Page
+          </Button>
+          <Button onClick={goToRandomPage} size="Small" type="Outlined">
+            Random Page
+          </Button>
+        </div>
+
+        <div className="primary-pagination">
+          <Pagination
+            currentPage={currentPage}
+            totalPages={totalPages}
+            updateCurrentPage={handlePageChange}
+          />
+        </div>
+
+        <div className="page-jump-section">
+          <Text type="BodySmall">Jump to page:</Text>
+          <PaginationNumberField
+            page={currentPage}
+            totalPages={totalPages}
+            onPageChanged={handlePageChange}
+            className="main-page-field"
+          />
+          <Text type="BodySmall">of {totalPages}</Text>
+        </div>
+      </div>
+
+      <div className="page-history">
+        <Text type="BodySmall">Recently visited pages:</Text>
+        <div className="history-buttons">
+          {pageHistory.slice(-5).reverse().map((page, index) => (
+            <Button
+              key={`${page}-${index}`}
+              size="Small"
+              type={page === currentPage ? 'Filled' : 'Ghost'}
+              onClick={() => handlePageChange(page)}
+            >
+              {page}
+            </Button>
+          ))}
+        </div>
+      </div>
+
+      <div className="current-page-info">
+        <Text type="Heading5">Page {currentPage}</Text>
+        <Text type="BodyMedium">Content for page {currentPage} would be displayed here.</Text>
+      </div>
+    </div>
+  );
+}
+```
+
+### Form-based Page Navigation
+```tsx
+function FormPageNavigationExample() {
+  const [currentPage, setCurrentPage] = useState(1);
+  const [pageInput, setPageInput] = useState('');
+  const [isValidPage, setIsValidPage] = useState(true);
+  const totalPages = 100;
+
+  const validateAndNavigate = () => {
+    const pageNumber = parseInt(pageInput);
+    
+    if (isNaN(pageNumber) || pageNumber < 1 || pageNumber > totalPages) {
+      setIsValidPage(false);
+      return;
+    }
+    
+    setIsValidPage(true);
+    setCurrentPage(pageNumber);
+    setPageInput('');
+  };
+
+  const handleKeyPress = (event) => {
+    if (event.key === 'Enter') {
+      validateAndNavigate();
+    }
+  };
+
+  const handleInputChange = (value) => {
+    setPageInput(value);
+    setIsValidPage(true); // Reset validation state when user types
+  };
+
+  return (
+    <div className="form-page-navigation">
+      <div className="content-section">
+        <Text type="Heading4">Page {currentPage} Content</Text>
+        <Text type="BodyMedium">
+          This is the content for page {currentPage} of {totalPages}.
+        </Text>
+      </div>
+
+      <div className="navigation-form">
+        <FormField 
+          label="Navigate to Page"
+          error={!isValidPage ? `Please enter a valid page number (1-${totalPages})` : ''}
+        >
+          <div className="page-input-group">
+            <Input
+              value={pageInput}
+              onValueChange={handleInputChange}
+              onKeyPress={handleKeyPress}
+              placeholder={`1-${totalPages}`}
+              state={!isValidPage ? 'Error' : 'Default'}
+            />
+            <Button onClick={validateAndNavigate}>
+              Go
+            </Button>
+          </div>
+        </FormField>
+
+        <div className="current-page-field">
+          <Text type="BodySmall">Current page:</Text>
+          <PaginationNumberField
+            page={currentPage}
+            totalPages={totalPages}
+            onPageChanged={setCurrentPage}
+          />
+        </div>
+      </div>
+
+      <div className="standard-pagination">
+        <Pagination
+          currentPage={currentPage}
+          totalPages={totalPages}
+          updateCurrentPage={setCurrentPage}
+        />
+      </div>
+    </div>
+  );
+}
+```
+
+### Mobile-Optimized Page Input
+```tsx
+function MobilePageInputExample() {
+  const [currentPage, setCurrentPage] = useState(1);
+  const [isMobile, setIsMobile] = useState(false);
+  const totalPages = 30;
+
+  useEffect(() => {
+    const checkMobile = () => {
+      setIsMobile(window.innerWidth < 768);
+    };
+    
+    checkMobile();
+    window.addEventListener('resize', checkMobile);
+    
+    return () => window.removeEventListener('resize', checkMobile);
+  }, []);
+
+  return (
+    <div className="mobile-page-input">
+      <div className="page-content">
+        <Text type="Heading4">Page {currentPage}</Text>
+        <Text type="BodyMedium">
+          Content optimized for {isMobile ? 'mobile' : 'desktop'} viewing.
+        </Text>
+      </div>
+
+      {isMobile ? (
+        <div className="mobile-navigation">
+          <div className="mobile-page-controls">
+            <Button 
+              disabled={currentPage === 1}
+              onClick={() => setCurrentPage(currentPage - 1)}
+              leadingIcon={<Icon icon="ChevronLeft" />}
+            />
+            
+            <div className="mobile-page-display">
+              <PaginationNumberField
+                page={currentPage}
+                totalPages={totalPages}
+                onPageChanged={setCurrentPage}
+                className="mobile-page-field"
+              />
+              <Text type="BodySmall">/ {totalPages}</Text>
+            </div>
+            
+            <Button 
+              disabled={currentPage === totalPages}
+              onClick={() => setCurrentPage(currentPage + 1)}
+              trailingIcon={<Icon icon="ChevronRight" />}
+            />
+          </div>
+        </div>
+      ) : (
+        <div className="desktop-navigation">
+          <Pagination
+            currentPage={currentPage}
+            totalPages={totalPages}
+            updateCurrentPage={setCurrentPage}
+          />
+          
+          <div className="desktop-page-jump">
+            <Text type="BodySmall">Page:</Text>
+            <PaginationNumberField
+              page={currentPage}
+              totalPages={totalPages}
+              onPageChanged={setCurrentPage}
+            />
+            <Text type="BodySmall">of {totalPages}</Text>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+### Batch Operations with Page Navigation
+```tsx
+function BatchOperationsExample() {
+  const [currentPage, setCurrentPage] = useState(1);
+  const [selectedItems, setSelectedItems] = useState(new Set());
+  const [selectAll, setSelectAll] = useState(false);
+  
+  const itemsPerPage = 20;
+  const totalItems = 189;
+  const totalPages = Math.ceil(totalItems / itemsPerPage);
+
+  const mockItems = Array.from({ length: itemsPerPage }, (_, index) => {
+    const id = (currentPage - 1) * itemsPerPage + index + 1;
+    return {
+      id,
+      name: `Item ${id}`,
+      status: 'Active',
+      type: ['Document', 'Image', 'Video'][Math.floor(Math.random() * 3)]
+    };
+  });
+
+  const handleSelectAll = (checked) => {
+    setSelectAll(checked);
+    if (checked) {
+      const currentPageIds = mockItems.map(item => item.id);
+      setSelectedItems(new Set([...selectedItems, ...currentPageIds]));
+    } else {
+      const currentPageIds = new Set(mockItems.map(item => item.id));
+      setSelectedItems(new Set([...selectedItems].filter(id => !currentPageIds.has(id))));
+    }
+  };
+
+  const handlePageChange = (newPage) => {
+    setCurrentPage(newPage);
+    setSelectAll(false); // Reset select all when changing pages
+  };
+
+  return (
+    <div className="batch-operations-example">
+      <div className="operations-header">
+        <div className="selection-controls">
+          <Checkbox 
+            checked={selectAll}
+            onCheckedChange={handleSelectAll}
+            label={`Select all on page ${currentPage}`}
+          />
+          
+          {selectedItems.size > 0 && (
+            <div className="batch-actions">
+              <Text type="BodySmall">
+                {selectedItems.size} items selected
+              </Text>
+              <Button size="Small" type="Outlined">
+                Delete Selected
+              </Button>
+              <Button size="Small" type="Outlined">
+                Export Selected
+              </Button>
+            </div>
+          )}
+        </div>
+
+        <div className="page-navigation">
+          <Text type="BodySmall">
+            Page {currentPage} of {totalPages} ({totalItems} total items)
+          </Text>
+          <PaginationNumberField
+            page={currentPage}
+            totalPages={totalPages}
+            onPageChanged={handlePageChange}
+          />
+        </div>
+      </div>
+
+      <div className="items-list">
+        {mockItems.map(item => (
+          <Card key={item.id} className="batch-item">
+            <Checkbox 
+              checked={selectedItems.has(item.id)}
+              onCheckedChange={(checked) => {
+                const newSelected = new Set(selectedItems);
+                if (checked) {
+                  newSelected.add(item.id);
+                } else {
+                  newSelected.delete(item.id);
+                }
+                setSelectedItems(newSelected);
+              }}
+            />
+            
+            <div className="item-info">
+              <Text type="BodyMedium">{item.name}</Text>
+              <Text type="BodySmall">{item.type}</Text>
+            </div>
+            
+            <Chip size="Small" style="Success">
+              {item.status}
+            </Chip>
+          </Card>
+        ))}
+      </div>
+
+      <div className="pagination-footer">
+        <Pagination
+          currentPage={currentPage}
+          totalPages={totalPages}
+          updateCurrentPage={handlePageChange}
+        />
+      </div>
+    </div>
+  );
+}
+```
+
+### Real-time Page Validation
+```tsx
+function RealTimeValidationExample() {
+  const [currentPage, setCurrentPage] = useState(1);
+  const [inputValue, setInputValue] = useState('');
+  const [validationMessage, setValidationMessage] = useState('');
+  const [isValid, setIsValid] = useState(true);
+  const totalPages = 75;
+
+  const validatePageInput = (value) => {
+    if (value === '') {
+      setValidationMessage('');
+      setIsValid(true);
+      return;
+    }
+
+    const pageNumber = parseInt(value);
+    
+    if (isNaN(pageNumber)) {
+      setValidationMessage('Please enter a valid number');
+      setIsValid(false);
+      return;
+    }
+    
+    if (pageNumber < 1) {
+      setValidationMessage('Page number must be at least 1');
+      setIsValid(false);
+      return;
+    }
+    
+    if (pageNumber > totalPages) {
+      setValidationMessage(`Page number cannot exceed ${totalPages}`);
+      setIsValid(false);
+      return;
+    }
+    
+    setValidationMessage(`Valid page number (${pageNumber})`);
+    setIsValid(true);
+  };
+
+  const handleInputChange = (value) => {
+    setInputValue(value);
+    validatePageInput(value);
+  };
+
+  const applyPageChange = () => {
+    if (isValid && inputValue) {
+      setCurrentPage(parseInt(inputValue));
+      setInputValue('');
+      setValidationMessage('');
+    }
+  };
+
+  return (
+    <div className="realtime-validation-example">
+      <div className="current-page-display">
+        <Text type="Heading4">Current Page: {currentPage}</Text>
+        <Text type="BodyMedium">Content for page {currentPage} goes here.</Text>
+      </div>
+
+      <div className="validation-section">
+        <FormField 
+          label="Enter Page Number"
+          helpText={validationMessage}
+          error={!isValid ? validationMessage : ''}
+        >
+          <div className="validated-input-group">
+            <Input
+              value={inputValue}
+              onValueChange={handleInputChange}
+              placeholder={`1-${totalPages}`}
+              state={!isValid ? 'Error' : validationMessage ? 'Success' : 'Default'}
+            />
+            <Button 
+              onClick={applyPageChange}
+              disabled={!isValid || !inputValue}
+            >
+              Apply
+            </Button>
+          </div>
+        </FormField>
+
+        <div className="standard-field">
+          <Text type="BodySmall">Or use the standard page field:</Text>
+          <PaginationNumberField
+            page={currentPage}
+            totalPages={totalPages}
+            onPageChanged={setCurrentPage}
+          />
+        </div>
+      </div>
+
+      <Pagination
+        currentPage={currentPage}
+        totalPages={totalPages}
+        updateCurrentPage={setCurrentPage}
+        className="main-pagination"
+      />
+    </div>
+  );
+}
+```