izen-react-starter 1.1.4 → 2.1.0

package/README.md

@@ -11,7 +11,7 @@ A modern React component library built with Vite, TypeScript, and best practices
 - 🎨 **Theme Provider**: Dark/light mode with system preference support
 - 🌐 **API Service**: Axios-based service for data fetching and posting
 - 🔄 **React Query Integration**: Built-in query client and provider
-- � **RBAC System**: Role-based access control with customizable permissions
+- 🔐 **RBAC System**: Fully configurable role-based access control - bring your own roles and resources
 - 🎣 **Custom Hooks**: Utility hooks like useIsMobile, useRouter, usePathname
 - 🛠️ **Utility Functions**: Helper functions for common tasks (cn, debounce, throttle, etc.)
 - 💾 **Cache Utilities**: React Query cache manipulation helpers
@@ -211,6 +211,269 @@ function MyApp() {
 }
 ```
 
+### Generic Table
+
+```tsx
+import { GenericTable, ActionType } from 'izen-react-starter';
+
+type SpecialDay = {
+  id: number;
+  name: string;
+  start: string;
+  end: string;
+  floatingHoliday?: boolean;
+};
+
+function SpecialDaysView({ rows, pagination, onAction }: { rows: SpecialDay[]; pagination: any; onAction: (row: SpecialDay, action: ActionType) => void }) {
+  return (
+    <GenericTable
+      rows={rows}
+      columns={[
+        { header: 'Name', render: (row) => `${row.name}${row.floatingHoliday ? ' (Floating Holiday)' : ''}` },
+        { header: 'Start', render: (row) => new Date(row.start).toLocaleDateString() },
+        { header: 'End', render: (row) => new Date(row.end).toLocaleDateString() },
+      ]}
+      getRowId={(row) => row.id}
+      onAction={(row, action) => onAction(row, action)}
+      getActionLink={(row) => `/preferences/special-days/${row.id}`}
+      pagination={pagination}
+      emptyText="No special days found."
+    />
+  );
+}
+```
+
+### Table Utilities
+
+```tsx
+import { TableActions, Pagination, TableHeader, GenericTab } from 'izen-react-starter';
+
+// Actions cell example
+<TableActions
+  link="/resource/123"
+  Item={{ id: 123 }}
+  handleAction={(row, action) => console.log(row, action)}
+/>;
+
+// Pagination example (expects meta/links/url shape)
+<Pagination
+  meta={{ currentPage: 1, itemsPerPage: 10, totalItems: 42 }}
+  links={{ prev: null, next: '?page=2', first: '?page=1', last: '?page=5' }}
+  url="/api/resources"
+/>;
+
+// Table header helper (basic)
+<table>
+  <TableHeader headers={["Name", "Email"]} />
+  {/* ...rows */}
+</table>;
+
+// GenericTab helper to wrap tab content and reuse TableActions
+<GenericTab
+  key="notes"
+  data={[{ id: 1, text: 'Note text' }]}
+  handleAction={(item, action) => console.log(item, action)}
+/>;
+```
+
+### Layout System
+
+The library provides a complete layout system with sidebar, header, and navigation components.
+
+#### DashboardLayout (Complete Layout)
+
+A full dashboard layout that combines sidebar and header:
+
+```tsx
+import { DashboardLayout, Overlay } from 'izen-react-starter';
+import { Home, Settings, FileText, HelpCircle } from 'lucide-react';
+
+function App() {
+  return (
+    <DashboardLayout
+      sidebarProps={{
+        brandName: "My App",
+        brandIcon: Home,
+        navMain: [
+          { title: "Dashboard", url: "/dashboard", icon: Home },
+          { 
+            title: "Settings", 
+            url: "#",
+            icon: Settings,
+            items: [
+              { title: "Profile", url: "/settings/profile" },
+              { title: "Security", url: "/settings/security" },
+            ]
+          },
+        ],
+        navSecondary: [
+          { title: "Help", url: "/help", icon: HelpCircle },
+          { title: "Docs", url: "/docs", icon: FileText, target: "_blank" },
+        ],
+        user: {
+          name: "John Doe",
+          email: "john@example.com",
+          avatar: "/avatar.jpg",
+        },
+        onLogout: () => console.log("Logout"),
+        userMenuItems: [
+          { label: "Profile", onClick: () => {} },
+          { label: "Settings", onClick: () => {} },
+        ],
+      }}
+      headerProps={{
+        pageTitles: {
+          "/dashboard": "Dashboard",
+          "/settings": "Settings",
+        },
+        defaultTitle: "My App",
+      }}
+      defaultOpen={true}
+      showOverlay={false}
+      overlayComponent={<Overlay show={false} />}
+    >
+      {/* Your page content */}
+    </DashboardLayout>
+  );
+}
+```
+
+#### AppSidebar (Sidebar Component)
+
+Collapsible sidebar with navigation menu:
+
+```tsx
+import { AppSidebar } from 'izen-react-starter';
+import { Home, Settings, Users } from 'lucide-react';
+
+<AppSidebar
+  brandName="Acme Inc"
+  brandIcon={Home}
+  navMain={[
+    { title: "Home", url: "/", icon: Home, badge: "3" },
+    { 
+      title: "Settings", 
+      url: "#",
+      icon: Settings,
+      items: [
+        { title: "Profile", url: "/settings/profile" },
+        { title: "Security", url: "/settings/security" },
+      ]
+    },
+  ]}
+  navSecondary={[
+    { title: "Help", url: "/help", icon: HelpCircle },
+  ]}
+  user={{
+    name: "Jane Doe",
+    email: "jane@example.com",
+    avatar: "/avatar.jpg",
+  }}
+  onLogout={() => console.log("Logging out")}
+  userMenuItems={[
+    { label: "Account", onClick: () => {} },
+  ]}
+/>
+```
+
+#### Navigation Components
+
+**NavMain** - Main navigation menu with collapsible groups:
+
+```tsx
+import { NavMain } from 'izen-react-starter';
+import { Home, Settings } from 'lucide-react';
+
+<NavMain
+  items={[
+    { title: "Dashboard", url: "/dashboard", icon: Home },
+    { 
+      title: "Settings",
+      icon: Settings,
+      items: [
+        { title: "Profile", url: "/settings/profile" },
+        { title: "Security", url: "/settings/security", badge: "2" },
+      ]
+    },
+  ]}
+/>
+```
+
+**NavSecondary** - Secondary navigation links:
+
+```tsx
+import { NavSecondary } from 'izen-react-starter';
+import { HelpCircle, FileText } from 'lucide-react';
+
+<NavSecondary
+  items={[
+    { title: "Help", url: "/help", icon: HelpCircle },
+    { title: "Documentation", url: "https://docs.example.com", icon: FileText, target: "_blank" },
+  ]}
+/>
+```
+
+**NavUser** - User menu dropdown:
+
+```tsx
+import { NavUser } from 'izen-react-starter';
+
+<NavUser
+  user={{
+    name: "John Doe",
+    email: "john@example.com",
+    avatar: "/avatar.jpg",
+  }}
+  onLogout={() => console.log("Logout")}
+  menuItems={[
+    { label: "Profile", onClick: () => {} },
+    { label: "Settings", onClick: () => {} },
+  ]}
+/>
+```
+
+**NavDocuments** - Document list with actions:
+
+```tsx
+import { NavDocuments } from 'izen-react-starter';
+import { FileText } from 'lucide-react';
+
+<NavDocuments
+  items={[
+    { name: "Report Q1", url: "/docs/q1", icon: FileText },
+    { name: "Budget 2024", url: "/docs/budget", icon: FileText },
+  ]}
+/>
+```
+
+#### SiteHeader
+
+Header with page title and sidebar trigger:
+
+```tsx
+import { SiteHeader } from 'izen-react-starter';
+
+<SiteHeader
+  pageTitles={{
+    "/dashboard": "Dashboard",
+    "/settings": "Settings",
+  }}
+  defaultTitle="My App"
+/>
+```
+
+### Charts and Overlay
+
+```tsx
+import { ChartAreaInteractive, Overlay } from 'izen-react-starter';
+
+// Chart with timeframe controls
+<ChartAreaInteractive />;
+
+// Simple overlay toggled by boolean
+<Overlay show={isLoading} />;
+```
+
 ### Layout Context
 
 ```tsx
@@ -243,58 +506,116 @@ function MyComponent() {
 ### API Service
 
 ```tsx
-import { apiService } from 'izen-react-starter';
+import React, { useEffect } from 'react';
+import { useApiService } from 'izen-react-starter';
 
-// Configure base URL
-apiService.setBaseURL('https://api.example.com');
+// Set the base URL once, typically in your app root
+export function App() {
+  const apiService = useApiService();
 
-// Set auth token
-apiService.setAuthToken('your-token-here');
+  useEffect(() => {
+    apiService.setBaseURL('https://api.example.com');
+  }, [apiService]);
 
-// Make API calls
-async function fetchData() {
-  try {
-    const data = await apiService.get('/users');
-    console.log(data);
-  } catch (error) {
-    console.error('Error fetching data:', error);
-  }
+  return <UsersPage />;
 }
 
-async function postData() {
-  try {
-    const response = await apiService.post('/users', {
-      name: 'John Doe',
-      email: 'john@example.com'
-    });
-    console.log(response);
-  } catch (error) {
-    console.error('Error posting data:', error);
-  }
+// Usage in a page/component
+export function UsersPage() {
+  const apiService = useApiService();
+
+  // Fetch users example
+  const fetchUsers = async () => {
+    try {
+      const users = await apiService.get('/users');
+      console.log(users);
+    } catch (error) {
+      console.error('Error fetching users:', error);
+    }
+  };
+
+  // Create user example
+  const createUser = async () => {
+    try {
+      const response = await apiService.post('/users', {
+        name: 'John Doe',
+        email: 'john@example.com',
+      });
+      console.log(response);
+    } catch (error) {
+      console.error('Error creating user:', error);
+    }
+  };
+
+  return (
+    <div>
+      <button onClick={fetchUsers}>Fetch Users</button>
+      <button onClick={createUser}>Create User</button>
+    </div>
+  );
 }
 ```
+> **Tip:** You only need to set the baseURL once per app session. After that, all requests will use this base URL automatically. The token will always be injected from AuthProvider for every request.
 
 ### Role-Based Access Control (RBAC)
 
+The RBAC system is now fully configurable! Define your own roles, resources, and rules.
+
 ```tsx
 import { 
+  RBACProvider,
   useAccessControl, 
   AccessControlWrapper, 
   withAccessControl,
-  Action, 
-  Resource 
+  CommonActions,
+  RBACConfig 
 } from 'izen-react-starter';
 
-// Using the hook
+// 1. Define your RBAC configuration
+const rbacConfig: RBACConfig = {
+  roles: ['admin', 'editor', 'viewer'],
+  resources: ['posts', 'comments', 'users'],
+  rules: {
+    admin: {
+      [CommonActions.Manage]: { can: 'all' },
+      [CommonActions.Create]: { can: 'all' },
+      [CommonActions.Read]: { can: 'all' },
+      [CommonActions.Update]: { can: 'all' },
+      [CommonActions.Delete]: { can: 'all' },
+    },
+    editor: {
+      [CommonActions.Create]: { can: ['posts', 'comments'] },
+      [CommonActions.Read]: { can: 'all' },
+      [CommonActions.Update]: { can: ['posts', 'comments'] },
+      [CommonActions.Delete]: { can: ['comments'] },
+    },
+    viewer: {
+      [CommonActions.Read]: { can: 'all' },
+    },
+  },
+};
+
+// 2. Wrap your app with RBACProvider
+function App() {
+  return (
+    <AuthProvider>
+      <RBACProvider config={rbacConfig}>
+        <YourApp />
+      </RBACProvider>
+    </AuthProvider>
+  );
+}
+
+// 3. Use access control in your components
 function AdminPanel() {
   const { isAllowed } = useAccessControl();
   
   return (
     <div>
-      {isAllowed(Action.Create, Resource.Users) && (
+      {isAllowed('create', 'users') && (
         <button>Create User</button>
       )}
-      {isAllowed(Action.Delete, Resource.Users) && (
+      {isAllowed('delete', 'users') && (
         <button>Delete User</button>
       )}
     </div>
@@ -304,8 +625,8 @@ function AdminPanel() {
 // Using the wrapper component
 function Dashboard() {
   return (
-    <AccessControlWrapper resource={Resource.Reports} action={Action.Read}>
-      <ReportsPanel />
+    <AccessControlWrapper resource="posts" action="create">
+      <CreatePostButton />
     </AccessControlWrapper>
   );
 }
@@ -314,12 +635,15 @@ function Dashboard() {
 const ProtectedComponent = withAccessControl(MyComponent);
 
 <ProtectedComponent 
-  accessedResource={Resource.Users} 
-  accessAction={Action.Update}
+  accessedResource="users" 
+  accessAction="update"
   otherProp="value" 
 />
 ```
 
+> 📖 **See [RBAC.md](./RBAC.md) for comprehensive documentation** including custom actions, multiple roles, migration guide, and advanced examples.
+```
+
 ### Utility Functions
 
 ```tsx
@@ -565,8 +889,933 @@ Methods:
 - `patch<T>(url, data?, config?)`: Promise<T>
 - `delete<T>(url, config?)`: Promise<T>
 - `setBaseURL(baseURL)`: void
-- `setAuthToken(token)`: void
-- `removeAuthToken()`: void
+
+> **Note:** The API service now always uses the latest token from the AuthProvider. Use the `useApiService` hook in your components. You no longer need to call `setAuthToken` or `removeAuthToken` manually.
+### Organized Component Library
+
+The library includes a comprehensive set of components organized by functionality:
+
+#### Modals
+
+Reusable modal dialogs for common user interactions.
+
+```tsx
+import { AlertModal, DeleteDialog, PopupModal } from 'izen-react-starter';
+
+// Alert Modal - Generic confirmation dialog
+function MyComponent() {
+  const [isOpen, setIsOpen] = useState(false);
+  
+  return (
+    <AlertModal
+      isOpen={isOpen}
+      onClose={() => setIsOpen(false)}
+      onConfirm={handleConfirm}
+      loading={loading}
+      title="Are you sure?"
+      description="This action cannot be undone."
+    />
+  );
+}
+
+// Delete Dialog - Specific delete confirmation
+<DeleteDialog
+  openDeleteDialog={isDeleteOpen}
+  setIsOpenDeleteDialog={setIsDeleteOpen}
+  onDelete={handleDelete}
+/>
+
+// Popup Modal - Complex modal with scroll area and optional "Add New" button
+<PopupModal
+  isOpen={modalName === 'create'}
+  setIsOpen={setModalName}
+  modalName="create"
+  title="Add New Item"
+  showAddBtn={true}
+  isAllowedCreate={true}
+  renderModal={(onClose) => (
+    <YourForm 
+      onSubmit={(data) => {
+        handleSubmit(data);
+        onClose();
+      }}
+    />
+  )}
+  extraBtns={() => (
+    <Button onClick={handleExtraAction}>Custom Action</Button>
+  )}
+/>
+```
+
+#### Navigation Components
+
+Complete navigation system with responsive design.
+
+```tsx
+import { UserNav, DashboardNav, Sidebar, MobileSidebar, Header } from 'izen-react-starter';
+
+// User navigation dropdown with avatar
+<UserNav
+  user={{ 
+    name: 'John Doe', 
+    email: 'john@example.com',
+    avatar: 'https://example.com/avatar.jpg'
+  }}
+  onLogout={handleLogout}
+/>
+
+// Dashboard navigation list with icons
+const navItems = [
+  { href: '/dashboard', label: 'Dashboard', icon: 'home', isShow: true },
+  { href: '/settings', label: 'Settings', icon: 'settings', isShow: true },
+  { href: '/users', label: 'Users', icon: 'users', isShow: false } // Hidden item
+];
+
+<DashboardNav
+  items={navItems}
+  setOpen={setIsSidebarOpen} // Optional - for mobile
+/>
+
+// Desktop sidebar with branding
+<Sidebar
+  navItems={navItems}
+  logoText="My App"
+  logoHref="/"
+/>
+
+// Mobile sidebar with sheet overlay
+<MobileSidebar
+  sidebarOpen={isMobileOpen}
+  setSidebarOpen={setIsMobileOpen}
+  navItems={navItems}
+  logoText="My App"
+  logoHref="/"
+/>
+
+// Complete header with user nav and theme toggle
+<Header
+  title="My Application"
+  user={{ name: 'John Doe', email: 'john@example.com' }}
+  onLogout={handleLogout}
+  setTheme={setTheme}
+  extraContent={
+    <Button>Custom Button</Button>
+  }
+/>
+```
+
+#### Date Picker Components
+
+Date selection and filtering with URL parameter integration.
+
+```tsx
+import { DatePickerWithRange, DateRangeFilter } from 'izen-react-starter';
+
+// Date range picker with calendar (3 months view)
+<DatePickerWithRange
+  startDate={new Date('2024-01-01')}
+  endDate={new Date('2024-01-31')}
+  onChange={(from, to) => {
+    console.log('Selected range:', from, to);
+    // Update your state or make API calls
+  }}
+  className="my-custom-class"
+/>
+
+// Date range filter with URL params (great for tables/reports)
+// Automatically syncs with URL query parameters
+<DateRangeFilter
+  startDateParamName="startDate"  // URL param name, defaults to 'filterStartDate'
+  endDateParamName="endDate"      // URL param name, defaults to 'filterEndDate'
+  className="mb-4"
+/>
+// URL will be updated to: ?startDate=2024-01-01&endDate=2024-01-31
+// Default range: 2 days ago to 3 days ahead
+```
+
+#### Search Components
+
+Search input with debouncing and URL parameter integration.
+
+```tsx
+import { TableSearchInput } from 'izen-react-starter';
+
+// Debounced search input (1 second delay)
+// Automatically updates URL search params
+<TableSearchInput 
+  placeholder="Search users..." 
+/>
+// Updates URL to: ?search=query&page=1
+// Integrates with react-router-dom's useSearchParams
+```
+
+#### Common UI Components
+
+Basic UI building blocks used across the application.
+
+```tsx
+import { Heading, PageHead, ThemeToggle, Header } from 'izen-react-starter';
+
+// Page heading with optional description
+<Heading 
+  title="Dashboard" 
+  description="Welcome to your dashboard"
+  className="mb-4"
+/>
+
+// Document head/title (uses react-helmet-async)
+<PageHead title="Dashboard | My App" />
+
+// Theme toggle dropdown (light/dark/pink/system)
+<ThemeToggle setTheme={(theme) => {
+  // theme: 'light' | 'dark' | 'pink' | 'system'
+  console.log('Theme changed to:', theme);
+}} />
+```
+
+#### Enhanced Table Components
+
+Advanced table utilities with server-side features.
+
+```tsx
+import { 
+  DataTableSkeleton, 
+  PaginationSection, 
+  ServerDataTable,
+  TableSearchInput 
+} from 'izen-react-starter';
+
+// Loading skeleton while data is fetching
+<DataTableSkeleton
+  columnCount={5}
+  rowCount={10}
+  searchableColumnCount={1}
+  filterableColumnCount={2}
+  showViewOptions={true}
+/>
+
+// Client-side pagination component
+<PaginationSection
+  totalPosts={100}
+  postsPerPage={10}
+  currentPage={currentPage}
+  setCurrentPage={setCurrentPage}
+/>
+
+// Server-side data table with TanStack Table
+// Automatically syncs with URL params (?page=1&limit=10)
+const columns: ColumnDef<User>[] = [
+  {
+    accessorKey: 'name',
+    header: 'Name',
+  },
+  {
+    accessorKey: 'email',
+    header: 'Email',
+  },
+];
+
+<ServerDataTable
+  columns={columns}
+  data={users}
+  pageCount={totalPages}
+  pageSizeOptions={[10, 20, 50, 100]}
+/>
+// Features:
+// - Automatic URL sync (?page=2&limit=20)
+// - Server-side pagination
+// - Row selection
+// - Sorting support
+// - Custom page size options
+```
+
+**Complete Table Example with Search and Filters:**
+
+```tsx
+import { 
+  ServerDataTable, 
+  TableSearchInput, 
+  DateRangeFilter,
+  DataTableSkeleton 
+} from 'izen-react-starter';
+
+function UsersTable() {
+  const { data, isLoading } = useQuery({
+    queryKey: ['users', searchParams.toString()],
+    queryFn: () => fetchUsers(searchParams)
+  });
+
+  if (isLoading) {
+    return <DataTableSkeleton columnCount={4} />;
+  }
+
+  return (
+    <div>
+      {/* Search and filters */}
+      <div className="flex gap-4 mb-4">
+        <TableSearchInput placeholder="Search users..." />
+        <DateRangeFilter />
+      </div>
+      
+      {/* Data table */}
+      <ServerDataTable
+        columns={columns}
+        data={data.users}
+        pageCount={data.totalPages}
+      />
+    </div>
+  );
+}
+```
+
+### Form Components
+
+The library provides a complete set of form components that are library-ready without tight coupling to app-specific contexts.
+
+#### FileUploadButton
+
+Flexible file upload button with validation:
+
+```tsx
+import { FileUploadButton } from 'izen-react-starter';
+
+<FileUploadButton
+  title="Upload File"
+  name="document"
+  accept={{
+    'application/pdf': ['.pdf'],
+    'image/*': ['.png', '.jpg', '.jpeg']
+  }}
+  maxSize={5 * 1024 * 1024} // 5MB
+  disabled={false}
+  onValidationError={(error) => {
+    console.error('Validation error:', error);
+    // Show toast or alert
+  }}
+  onSuccess={(file) => {
+    console.log('File uploaded:', file);
+    // Handle file upload
+  }}
+  className="my-4"
+/>
+```
+
+#### DatePicker
+
+Calendar-based date picker with popover:
+
+```tsx
+import { DatePicker } from 'izen-react-starter';
+
+<DatePicker
+  title="Select Date"
+  name="eventDate"
+  value={selectedDate}
+  onChange={(date) => setSelectedDate(date)}
+  placeholder="Pick a date"
+  error={errors.eventDate}
+  disabled={false}
+/>
+```
+
+#### TimeInput
+
+Time input with hours, minutes, and optional seconds:
+
+```tsx
+import { TimeInput } from 'izen-react-starter';
+
+<TimeInput
+  title="Event Time"
+  name="startTime"
+  value="14:30"
+  onChange={(time) => console.log('Time:', time)}
+  showSeconds={false}
+  error={errors.startTime}
+  disabled={false}
+/>
+```
+
+#### TextInput
+
+Versatile text input supporting multiple types and textarea:
+
+```tsx
+import { TextInput } from 'izen-react-starter';
+import { Mail, Lock } from 'lucide-react';
+
+// Text input with icon
+<TextInput
+  title="Email"
+  name="email"
+  type="email"
+  icon={<Mail />}
+  placeholder="Enter your email"
+  error={errors.email}
+/>
+
+// Password input
+<TextInput
+  title="Password"
+  name="password"
+  type="password"
+  icon={<Lock />}
+  placeholder="Enter password"
+  error={errors.password}
+/>
+
+// Textarea
+<TextInput
+  title="Description"
+  name="description"
+  type="textarea"
+  rows={5}
+  placeholder="Enter description"
+  error={errors.description}
+/>
+
+// Number input
+<TextInput
+  title="Age"
+  name="age"
+  type="number"
+  min={0}
+  max={120}
+  placeholder="Enter age"
+/>
+```
+
+#### CheckboxGroup
+
+Checkbox input supporting single or multiple items:
+
+```tsx
+import { CheckboxGroup } from 'izen-react-starter';
+
+// Single checkbox
+<CheckboxGroup
+  title="Accept Terms"
+  name="terms"
+  items={[
+    { id: 'terms', name: 'terms', displayName: 'I accept the terms and conditions' }
+  ]}
+  error={errors.terms}
+/>
+
+// Multiple checkboxes
+<CheckboxGroup
+  title="Select Features"
+  name="features"
+  items={[
+    { id: 'feature1', name: 'features', displayName: 'Email Notifications', checked: true },
+    { id: 'feature2', name: 'features', displayName: 'SMS Alerts', checked: false },
+    { id: 'feature3', name: 'features', displayName: 'Push Notifications', checked: true },
+  ]}
+  onChange={(e) => {
+    const checked = e.target.checked;
+    const id = e.target.id;
+    console.log(`Checkbox ${id} is ${checked ? 'checked' : 'unchecked'}`);
+  }}
+/>
+```
+
+#### RadioGroup
+
+Radio button group with horizontal or vertical layout:
+
+```tsx
+import { RadioGroup } from 'izen-react-starter';
+
+// Horizontal layout
+<RadioGroup
+  title="Select Plan"
+  name="plan"
+  items={[
+    { value: 'free', title: 'Free Plan' },
+    { value: 'pro', title: 'Pro Plan' },
+    { value: 'enterprise', title: 'Enterprise Plan' },
+  ]}
+  onChange={(e) => console.log('Selected:', e.target.value)}
+  error={errors.plan}
+/>
+
+// Vertical layout
+<RadioGroup
+  title="Notification Preference"
+  name="notifications"
+  vertical={true}
+  items={[
+    { value: 'all', title: 'All Notifications' },
+    { value: 'important', title: 'Important Only' },
+    { value: 'none', title: 'None' },
+  ]}
+  onChange={(e) => setNotificationPref(e.target.value)}
+/>
+```
+
+**Complete Form Example:**
+
+```tsx
+import { 
+  TextInput, 
+  DatePicker, 
+  TimeInput, 
+  CheckboxGroup,
+  RadioGroup,
+  FileUploadButton 
+} from 'izen-react-starter';
+import { useState } from 'react';
+
+function EventForm() {
+  const [formData, setFormData] = useState({
+    name: '',
+    date: undefined,
+    time: '09:00',
+    type: 'public',
+    features: [],
+    document: null
+  });
+  
+  const [errors, setErrors] = useState({});
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    console.log('Form data:', formData);
+  };
+
+  return (
+    <form onSubmit={handleSubmit} className="space-y-4">
+      <TextInput
+        title="Event Name"
+        name="name"
+        value={formData.name}
+        onChange={(e) => setFormData({ ...formData, name: e.target.value })}
+        placeholder="Enter event name"
+        error={errors.name}
+      />
+      
+      <DatePicker
+        title="Event Date"
+        name="date"
+        value={formData.date}
+        onChange={(date) => setFormData({ ...formData, date })}
+        error={errors.date}
+      />
+      
+      <TimeInput
+        title="Start Time"
+        name="time"
+        value={formData.time}
+        onChange={(time) => setFormData({ ...formData, time })}
+        error={errors.time}
+      />
+      
+      <RadioGroup
+        title="Event Type"
+        name="type"
+        items={[
+          { value: 'public', title: 'Public Event' },
+          { value: 'private', title: 'Private Event' },
+        ]}
+        onChange={(e) => setFormData({ ...formData, type: e.target.value })}
+      />
+      
+      <CheckboxGroup
+        title="Event Features"
+        name="features"
+        items={[
+          { id: 'catering', name: 'features', displayName: 'Catering' },
+          { id: 'parking', name: 'features', displayName: 'Parking' },
+          { id: 'wifi', name: 'features', displayName: 'WiFi' },
+        ]}
+      />
+      
+      <FileUploadButton
+        title="Event Document"
+        name="document"
+        accept={{ 'application/pdf': ['.pdf'] }}
+        onSuccess={(file) => setFormData({ ...formData, document: file })}
+        onValidationError={(error) => setErrors({ ...errors, document: error })}
+      />
+      
+      <button type="submit" className="btn btn-primary">
+        Create Event
+      </button>
+    </form>
+  );
+}
+```
+
+#### FormInput
+
+Enhanced input component with card number formatting and date display:
+
+```tsx
+import { FormInput } from 'izen-react-starter';
+import { User, Mail, CreditCard } from 'lucide-react';
+
+// Text input with icon
+<FormInput
+  title="Full Name"
+  name="fullName"
+  type="text"
+  icon={<User />}
+  placeholder="Enter your name"
+  value={name}
+  onValueChange={(value) => setName(value)}
+  error={errors.name}
+/>
+
+// Card number with auto-formatting
+<FormInput
+  title="Card Number"
+  name="cardNumber"
+  type="cardNumber"
+  icon={<CreditCard />}
+  placeholder="0000 0000 0000 0000"
+  value={cardNumber}
+  onValueChange={(value) => setCardNumber(value)}
+/>
+
+// Date input with formatted label
+<FormInput
+  title="Birth Date"
+  name="birthDate"
+  type="date"
+  value={birthDate}
+  onChange={(e) => setBirthDate(e.target.value)}
+  showDateLabel={true} // Shows formatted date like "(Jan 15)"
+/>
+
+// Textarea
+<FormInput
+  title="Comments"
+  name="comments"
+  type="textarea"
+  rows={4}
+  placeholder="Enter your comments"
+  value={comments}
+  onValueChange={(value) => setComments(value)}
+/>
+```
+
+#### FormSelect
+
+Standard dropdown select component:
+
+> **Note:** This component is exported as `FormSelect` to avoid naming conflict with shadcn/ui's `Select` component.
+
+```tsx
+import { FormSelect } from 'izen-react-starter';
+
+<FormSelect
+  title="Country"
+  name="country"
+  placeholder="Select country"
+  value={country}
+  options={[
+    { value: 'us', label: 'United States' },
+    { value: 'uk', label: 'United Kingdom' },
+    { value: 'ca', label: 'Canada' },
+  ]}
+  onChange={(value) => setCountry(value)}
+  error={errors.country}
+/>
+
+// With "Please Select" option
+<FormSelect
+  title="Category"
+  name="category"
+  showOtherOption={true}
+  otherOptionLabel="Please Select"
+  options={categories}
+  onChange={(value) => setCategory(value)}
+/>
+```
+
+#### ComboboxSelect
+
+Advanced searchable select with Command palette:
+
+```tsx
+import { ComboboxSelect } from 'izen-react-starter';
+import { Building } from 'lucide-react';
+
+<ComboboxSelect
+  title="Company"
+  name="company"
+  icon={<Building />}
+  placeholder="Search companies..."
+  value={selectedCompany}
+  options={companies}
+  onChange={(value) => setSelectedCompany(value)}
+  onSearch={(searchTerm) => {
+    // Trigger API call to search companies
+    fetchCompanies(searchTerm);
+  }}
+  showOtherOption={true}
+  otherOptionLabel="No Company"
+  emptyMessage="No companies found."
+  error={errors.company}
+/>
+```
+
+**Features:**
+- Searchable with Command palette UI
+- Toggle selection (click again to deselect)
+- Optional "other" option
+- Custom empty state message
+- Search callback for dynamic loading
+
+#### FormButtons
+
+Reusable form action buttons:
+
+```tsx
+import { FormButtons } from 'izen-react-starter';
+
+<FormButtons
+  loading={isSubmitting}
+  showSubmit={true}
+  showCancel={true}
+  showReset={true}
+  submitText="Save"
+  cancelText="Cancel"
+  resetText="Clear"
+  onCancel={() => router.back()}
+  onReset={() => form.reset()}
+  onSubmit={() => form.handleSubmit(onSubmit)()}
+/>
+```
+
+**Props:**
+- `loading`: Shows "Please wait..." text
+- `showSubmit/showCancel/showReset`: Toggle button visibility
+- `submitText/cancelText/resetText`: Custom button labels
+- `onCancel/onReset/onSubmit`: Click handlers
+
+#### FormLayout
+
+Complete form wrapper with error display and action buttons:
+
+```tsx
+import { FormLayout, FormInput, FormSelect } from 'izen-react-starter';
+import { useState } from 'react';
+
+function CreateUser() {
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState('');
+
+  const handleSubmit = async (data: any) => {
+    setLoading(true);
+    setError('');
+    
+    try {
+      await createUser(data);
+      router.push('/users');
+    } catch (err) {
+      setError(err.message);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <FormLayout
+      onSubmit={handleSubmit}
+      error={error}
+      loading={loading}
+      showSubmit={true}
+      showCancel={true}
+      showReset={true}
+      submitText="Create User"
+      onCancel={() => router.back()}
+      onReset={() => {
+        // Reset form logic
+      }}
+      fullHeight={false}
+    >
+      <FormInput
+        title="Name"
+        name="name"
+        placeholder="Enter name"
+      />
+      
+      <FormInput
+        title="Email"
+        name="email"
+        type="email"
+        placeholder="Enter email"
+      />
+      
+      <FormSelect
+        title="Role"
+        name="role"
+        options={[
+          { value: 'admin', label: 'Admin' },
+          { value: 'user', label: 'User' },
+        ]}
+      />
+    </FormLayout>
+  );
+}
+```
+
+**Features:**
+- Automatic form submission handling
+- Error display with Alert component
+- Integrated FormButtons
+- Card wrapper with styling
+- Loading state management
+- Sticky button footer
+
+**Complete Advanced Form Example:**
+
+```tsx
+import {
+  FormLayout,
+  FormInput,
+  Select,
+  ComboboxSelect,
+  DatePicker,
+  TimeInput,
+  CheckboxGroup,
+  RadioGroup,
+  FileUploadButton
+} from 'izen-react-starter';
+import { useState } from 'react';
+
+function AdvancedForm() {
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState('');
+  const [formData, setFormData] = useState({
+    name: '',
+    email: '',
+    cardNumber: '',
+    country: '',
+    company: '',
+    eventDate: undefined,
+    startTime: '09:00',
+    plan: 'free',
+    features: [],
+    document: null
+  });
+
+  const handleSubmit = async (data: any) => {
+    setLoading(true);
+    try {
+      // Process form data
+      await submitForm({ ...formData, ...data });
+    } catch (err) {
+      setError(err.message);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <FormLayout
+      onSubmit={handleSubmit}
+      error={error}
+      loading={loading}
+      submitText="Submit Registration"
+      fullHeight={false}
+    >
+      <div className="grid grid-cols-2 gap-4">
+        <FormInput
+          title="Full Name"
+          name="name"
+          placeholder="John Doe"
+          value={formData.name}
+          onValueChange={(value) => setFormData({ ...formData, name: value })}
+        />
+        
+        <FormInput
+          title="Email"
+          name="email"
+          type="email"
+          placeholder="john@example.com"
+          value={formData.email}
+          onValueChange={(value) => setFormData({ ...formData, email: value })}
+        />
+      </div>
+
+      <FormInput
+        title="Card Number"
+        name="cardNumber"
+        type="cardNumber"
+        placeholder="0000 0000 0000 0000"
+        value={formData.cardNumber}
+        onValueChange={(value) => setFormData({ ...formData, cardNumber: value })}
+      />
+
+      <FormSelect
+        title="Country"
+        name="country"
+        placeholder="Select country"
+        value={formData.country}
+        options={countries}
+        onChange={(value) => setFormData({ ...formData, country: value })}
+      />
+
+      <ComboboxSelect
+        title="Company"
+        name="company"
+        placeholder="Search companies..."
+        value={formData.company}
+        options={companies}
+        onChange={(value) => setFormData({ ...formData, company: value })}
+        onSearch={(term) => searchCompanies(term)}
+      />
+
+      <div className="grid grid-cols-2 gap-4">
+        <DatePicker
+          title="Event Date"
+          name="eventDate"
+          value={formData.eventDate}
+          onChange={(date) => setFormData({ ...formData, eventDate: date })}
+        />
+        
+        <TimeInput
+          title="Start Time"
+          name="startTime"
+          value={formData.startTime}
+          onChange={(time) => setFormData({ ...formData, startTime: time })}
+        />
+      </div>
+
+      <RadioGroup
+        title="Subscription Plan"
+        name="plan"
+        items={[
+          { value: 'free', title: 'Free' },
+          { value: 'pro', title: 'Pro' },
+          { value: 'enterprise', title: 'Enterprise' },
+        ]}
+        onChange={(e) => setFormData({ ...formData, plan: e.target.value })}
+      />
+
+      <CheckboxGroup
+        title="Features"
+        name="features"
+        items={[
+          { id: 'email', name: 'features', displayName: 'Email Notifications' },
+          { id: 'sms', name: 'features', displayName: 'SMS Alerts' },
+          { id: 'push', name: 'features', displayName: 'Push Notifications' },
+        ]}
+      />
+
+      <FileUploadButton
+        title="Upload Document"
+        name="document"
+        accept={{ 'application/pdf': ['.pdf'] }}
+        maxSize={5 * 1024 * 1024}
+        onSuccess={(file) => setFormData({ ...formData, document: file })}
+      />
+    </FormLayout>
+  );
+}
+```
 
 ### RBAC System