sdcpl-react-component 1.0.0

package/README.md

@@ -0,0 +1,986 @@
+# sdcpl-react-component
+
+A comprehensive React component library with 20+ professional UI components including forms, tables, dashboards, charts, and more. Built with React 18+ and 19+ support, featuring full keyboard navigation, validation, icon support, and IndexedDB integration.
+
+## 📦 Installation
+
+```bash
+npm install sdcpl-react-component
+```
+
+Or using yarn:
+
+```bash
+yarn add sdcpl-react-component
+```
+
+### Peer Dependencies
+
+This library requires React and React DOM as peer dependencies:
+
+```bash
+npm install react react-dom
+```
+
+### Optional Dependencies
+
+For full functionality, you may also want to install:
+
+```bash
+npm install @fortawesome/react-fontawesome @fortawesome/free-solid-svg-icons
+```
+
+## 🚀 Quick Start
+
+```javascript
+import { CustomTextBox, CustomButton, CustomForm } from 'sdcpl-react-component';
+import 'sdcpl-react-component/styles';
+
+function App() {
+  const [name, setName] = useState('');
+
+  return (
+    <CustomTextBox
+      type="text"
+      value={name}
+      onChange={setName}
+      placeholder="Enter your name"
+      icon="user"
+    />
+  );
+}
+```
+
+## 📚 Table of Contents
+
+- [Components](#components)
+  - [Form Components](#form-components)
+  - [Layout Components](#layout-components)
+  - [Data Components](#data-components)
+  - [Dashboard Components](#dashboard-components)
+- [Usage Examples](#usage-examples)
+- [API Reference](#api-reference)
+- [Theming](#theming)
+- [Utilities](#utilities)
+- [IndexedDB Integration](#indexeddb-integration)
+
+## 📦 Components
+
+### Form Components
+
+#### CustomTextBox
+
+Advanced text input component with validation, masking, currency, date/time support.
+
+**Props:**
+- `type` (string): Input type - 'text', 'number', 'currency', 'date', 'datetime', 'time', 'password'
+- `value` (string): Controlled value
+- `onChange` (function): Callback: `(value: string) => void`
+- `placeholder` (string): Placeholder text
+- `validationType` (string): 'email', 'creditcard', 'pin', 'phone', 'url'
+- `masking` (string): Mask pattern (e.g., '(000) 000-0000')
+- `icon` (string): FontAwesome icon name
+- `required` (boolean): Mark as required field
+- `disabled` (boolean): Disable input
+- `loading` (boolean): Show loading spinner
+- `showValidationIcon` (boolean): Show check/cross validation icon
+- `currency` (string): Currency symbol (default: '$')
+- `decimalPlaces` (number): Decimal places for number/currency
+- `length` (number): Maximum character length
+- `fullWidth` (boolean): Take full container width
+- `helpText` (string): Help text below input
+- `tooltip` (string): Tooltip on hover
+
+**Methods (via ref):**
+- `getValue()`: Returns current value (ISO format for dates)
+- `setValue(value)`: Sets input value
+- `focus()`: Focuses the input
+- `reset()`: Resets to default and clears validation
+- `isValid()`: Returns validation state
+- `showLoading()`: Shows loading spinner
+- `hideLoading()`: Hides loading spinner
+
+**Example:**
+```javascript
+import { CustomTextBox } from 'sdcpl-react-component';
+import { useRef } from 'react';
+
+function MyComponent() {
+  const textBoxRef = useRef();
+  const [value, setValue] = useState('');
+
+  return (
+    <CustomTextBox
+      ref={textBoxRef}
+      type="text"
+      value={value}
+      onChange={setValue}
+      placeholder="Enter email"
+      validationType="email"
+      icon="envelope"
+      required
+      showValidationIcon
+    />
+  );
+}
+```
+
+#### CustomMultilineTextBox
+
+Multi-line text area with character counting and validation.
+
+**Props:**
+- `value` (string): Controlled value
+- `onChange` (function): Callback: `(value: string) => void`
+- `rows` (number): Number of rows (default: 4)
+- `maxLength` (number): Maximum character length
+- `showCharCount` (boolean): Show character counter
+- `placeholder` (string): Placeholder text
+- `icon` (string): FontAwesome icon name
+- `required` (boolean): Mark as required field
+- `disabled` (boolean): Disable input
+- `helpText` (string): Help text below input
+
+**Example:**
+```javascript
+import { CustomMultilineTextBox } from 'sdcpl-react-component';
+
+function MyComponent() {
+  const [notes, setNotes] = useState('');
+
+  return (
+    <CustomMultilineTextBox
+      value={notes}
+      onChange={setNotes}
+      rows={6}
+      maxLength={500}
+      showCharCount
+      placeholder="Enter your notes..."
+      icon="file-text"
+    />
+  );
+}
+```
+
+#### CustomButton
+
+Professional button with icon support and multiple styles.
+
+**Props:**
+- `text` (string): Button text
+- `icon` (string): FontAwesome icon name
+- `iconPosition` (string): 'left', 'right', 'top', 'bottom' (default: 'left')
+- `onClick` (function): Click handler
+- `backgroundColor` (string): Button background color
+- `width` (string): Button width
+- `height` (string): Button height
+- `disabled` (boolean): Disable button
+- `loading` (boolean): Show loading state
+- `iconColor` (string): Icon color
+- `iconSize` (string): Icon size
+- `textSize` (string): Text font size
+
+**Example:**
+```javascript
+import { CustomButton } from 'sdcpl-react-component';
+
+function MyComponent() {
+  return (
+    <CustomButton
+      text="Save"
+      icon="save"
+      onClick={() => console.log('Saved!')}
+      backgroundColor="#3b82f6"
+      iconPosition="left"
+    />
+  );
+}
+```
+
+#### CustomCheckBox
+
+Multi-select and single-select checkbox/radio with search functionality.
+
+**Props:**
+- `data` (object): Data source - `{ list: [[id, label], ...] }` or `{ indexdbKey: 'key' }`
+- `value` (array): Selected IDs array
+- `onChange` (function): Callback: `(ids: array) => void`
+- `mode` (string): 'multi' or 'single' (default: 'multi')
+- `searchable` (boolean): Enable search (default: true)
+- `layout` (string): 'list' or 'card' (default: 'list')
+- `icon` (string): FontAwesome icon name
+- `required` (boolean): Mark as required field
+- `disabled` (boolean): Disable checkbox
+
+**Methods (via ref):**
+- `getValue()`: Returns selected IDs array
+- `getObjectValue()`: Returns full selected items array
+- `setValue(ids)`: Sets selected IDs
+- `reset()`: Clears selection
+
+**Example:**
+```javascript
+import { CustomCheckBox } from 'sdcpl-react-component';
+
+function MyComponent() {
+  const [selected, setSelected] = useState([]);
+  const data = {
+    list: [
+      [1, 'Option 1'],
+      [2, 'Option 2'],
+      [3, 'Option 3']
+    ]
+  };
+
+  return (
+    <CustomCheckBox
+      data={data}
+      value={selected}
+      onChange={setSelected}
+      mode="multi"
+      searchable
+      layout="card"
+    />
+  );
+}
+```
+
+#### CustomCheckBoxSingle
+
+Single checkbox/switch control with caption and icon support.
+
+**Props:**
+- `value` (boolean): Checked state
+- `onChange` (function): Callback: `(checked: boolean) => void`
+- `caption` (string): Label text
+- `icon` (string): FontAwesome icon name
+- `position` (string): 'left' or 'right' (default: 'left')
+- `required` (boolean): Mark as required field
+- `disabled` (boolean): Disable checkbox
+
+**Example:**
+```javascript
+import { CustomCheckBoxSingle } from 'sdcpl-react-component';
+
+function MyComponent() {
+  const [agreed, setAgreed] = useState(false);
+
+  return (
+    <CustomCheckBoxSingle
+      value={agreed}
+      onChange={setAgreed}
+      caption="I agree to the terms and conditions"
+      icon="check"
+    />
+  );
+}
+```
+
+#### CustomComboBox
+
+Dropdown select with search, keyboard navigation, and portal rendering.
+
+**Props:**
+- `data` (object): Data source - `{ list: [[id, label], ...] }` or `{ indexdbKey: 'key' }`
+- `value` (string|number): Selected ID
+- `onChange` (function): Callback: `(id: string|number) => void`
+- `placeholder` (string): Placeholder text
+- `searchable` (boolean): Enable search (default: true)
+- `icon` (string): FontAwesome icon name
+- `required` (boolean): Mark as required field
+- `disabled` (boolean): Disable combobox
+- `loading` (boolean): Show loading state
+
+**Methods (via ref):**
+- `getValue()`: Returns selected ID
+- `getObjectValue()`: Returns full selected item object
+- `setValue(id)`: Sets selected ID
+- `focus()`: Focuses the combobox
+- `reset()`: Clears selection
+
+**Example:**
+```javascript
+import { CustomComboBox } from 'sdcpl-react-component';
+
+function MyComponent() {
+  const [selected, setSelected] = useState('');
+  const data = {
+    list: [
+      [1, 'Option 1'],
+      [2, 'Option 2'],
+      [3, 'Option 3']
+    ]
+  };
+
+  return (
+    <CustomComboBox
+      data={data}
+      value={selected}
+      onChange={setSelected}
+      placeholder="Select an option"
+      searchable
+      icon="list"
+    />
+  );
+}
+```
+
+#### CustomComboBoxMultiSelect
+
+Multi-select dropdown with badge display.
+
+**Props:**
+- `data` (object): Data source - `{ list: [[id, label], ...] }` or `{ indexdbKey: 'key' }`
+- `value` (array): Selected IDs array
+- `onChange` (function): Callback: `(ids: array) => void`
+- `placeholder` (string): Placeholder text
+- `searchable` (boolean): Enable search (default: true)
+- `icon` (string): FontAwesome icon name
+- `required` (boolean): Mark as required field
+- `disabled` (boolean): Disable combobox
+
+**Methods (via ref):**
+- `getValue()`: Returns selected IDs array
+- `getObjectValue()`: Returns full selected items array
+- `setValue(ids)`: Sets selected IDs
+- `reset()`: Clears selection
+
+**Example:**
+```javascript
+import { CustomComboBoxMultiSelect } from 'sdcpl-react-component';
+
+function MyComponent() {
+  const [selected, setSelected] = useState([]);
+  const data = {
+    list: [
+      [1, 'Tag 1'],
+      [2, 'Tag 2'],
+      [3, 'Tag 3']
+    ]
+  };
+
+  return (
+    <CustomComboBoxMultiSelect
+      data={data}
+      value={selected}
+      onChange={setSelected}
+      placeholder="Select tags"
+      searchable
+    />
+  );
+}
+```
+
+#### CustomFileUpload
+
+File upload component with drag & drop, validation, and optional textbox.
+
+**Props:**
+- `onFileSelect` (function): Callback: `(file: File) => void`
+- `accept` (string): Accepted file types (e.g., 'image/*', '.pdf')
+- `maxSize` (number): Maximum file size in bytes
+- `showTextBox` (boolean): Show optional textbox for notes
+- `textBoxValue` (string): Textbox value
+- `onTextBoxChange` (function): Textbox change handler
+- `textBoxPlaceholder` (string): Textbox placeholder
+- `icon` (string): FontAwesome icon name
+- `disabled` (boolean): Disable upload
+- `required` (boolean): Mark as required field
+
+**Example:**
+```javascript
+import { CustomFileUpload } from 'sdcpl-react-component';
+
+function MyComponent() {
+  const handleFileSelect = (file) => {
+    console.log('Selected file:', file);
+  };
+
+  return (
+    <CustomFileUpload
+      onFileSelect={handleFileSelect}
+      accept="image/*"
+      maxSize={5 * 1024 * 1024} // 5MB
+      showTextBox
+      textBoxPlaceholder="Add notes about the file..."
+    />
+  );
+}
+```
+
+#### CustomProgressBar
+
+Progress bar component with optional textbox and visual indicator.
+
+**Props:**
+- `value` (number): Progress value (0-100)
+- `showTextBox` (boolean): Show optional textbox
+- `textBoxValue` (string): Textbox value
+- `onTextBoxChange` (function): Textbox change handler
+- `height` (string): Progress bar height
+- `color` (string): Progress bar color
+- `animated` (boolean): Show animated stripes
+- `showButton` (boolean): Show embedded button
+- `buttonText` (string): Button text
+- `buttonIcon` (string): Button icon
+- `onButtonClick` (function): Button click handler
+
+**Example:**
+```javascript
+import { CustomProgressBar } from 'sdcpl-react-component';
+
+function MyComponent() {
+  const [progress, setProgress] = useState(45);
+
+  return (
+    <CustomProgressBar
+      value={progress}
+      height="20px"
+      color="#3b82f6"
+      animated
+      showTextBox
+      textBoxValue={`${progress}% complete`}
+    />
+  );
+}
+```
+
+#### CustomSlider
+
+Slider and range selector with keyboard navigation and multiple data types.
+
+**Props:**
+- `value` (number|string): Current value
+- `onChange` (function): Callback: `(value: number|string) => void`
+- `min` (number): Minimum value
+- `max` (number): Maximum value
+- `step` (number): Step size
+- `dataType` (string): 'number', 'date', 'weekday', 'hour', 'month'
+- `showTicks` (boolean): Show tick marks
+- `showLabels` (boolean): Show value labels
+- `icon` (string): FontAwesome icon name
+- `disabled` (boolean): Disable slider
+
+**Example:**
+```javascript
+import { CustomSlider } from 'sdcpl-react-component';
+
+function MyComponent() {
+  const [value, setValue] = useState(50);
+
+  return (
+    <CustomSlider
+      value={value}
+      onChange={setValue}
+      min={0}
+      max={100}
+      step={1}
+      showTicks
+      showLabels
+    />
+  );
+}
+```
+
+### Layout Components
+
+#### CustomMenu
+
+Hierarchical sidebar navigation with collapsible groups and icons.
+
+**Props:**
+- `data` (array): Menu items array
+- `value` (string): Selected menu item ID
+- `onChange` (function): Callback: `(id: string) => void`
+- `searchable` (boolean): Enable search
+- `icon` (string): FontAwesome icon name
+
+**Methods (via ref):**
+- `getValue()`: Returns selected menu item ID
+- `getObjectValue()`: Returns full selected menu item object
+- `setValue(id)`: Sets selected menu item
+
+**Example:**
+```javascript
+import { CustomMenu } from 'sdcpl-react-component';
+
+function MyComponent() {
+  const menuData = [
+    {
+      id: 'dashboard',
+      caption: 'Dashboard',
+      icon: 'home',
+      children: [
+        { id: 'overview', caption: 'Overview', icon: 'chart-line' },
+        { id: 'analytics', caption: 'Analytics', icon: 'chart-bar' }
+      ]
+    },
+    { id: 'settings', caption: 'Settings', icon: 'cog' }
+  ];
+
+  return (
+    <CustomMenu
+      data={menuData}
+      value="dashboard"
+      onChange={(id) => console.log('Selected:', id)}
+    />
+  );
+}
+```
+
+#### CustomForm
+
+Dynamic form generator with sections, formulas, and conditional visibility.
+
+**Props:**
+- `config` (object): Form configuration
+- `onButtonClick` (function): Button click handler
+- `onFieldChange` (function): Field change handler
+- `initialData` (object): Initial form data
+
+**Methods (via ref):**
+- `getValue()`: Returns form values as object
+- `getObjectValue()`: Returns full form data with metadata
+- `setValue(data)`: Sets form values
+- `validate()`: Validates all fields
+- `getValidationErrors()`: Returns validation errors
+- `reset()`: Resets form to initial state
+
+**Example:**
+```javascript
+import { CustomForm } from 'sdcpl-react-component';
+import { useRef } from 'react';
+
+function MyComponent() {
+  const formRef = useRef();
+  
+  const config = {
+    form: {
+      caption: 'User Registration',
+      logo: 'user-plus'
+    },
+    sections: [
+      {
+        id: 'personal',
+        title: 'Personal Information',
+        icon: 'user',
+        fields: [
+          { id: 'firstName', caption: 'First Name', type: 'text', required: true },
+          { id: 'email', caption: 'Email', type: 'text', validationType: 'email', required: true }
+        ]
+      }
+    ],
+    buttons: [
+      { id: 'submit', caption: 'Register', settings: { validate: true, icon: 'check' } }
+    ]
+  };
+
+  const handleButtonClick = (buttonId) => {
+    if (buttonId === 'submit') {
+      const values = formRef.current.getValue();
+      console.log('Form values:', values);
+    }
+  };
+
+  return (
+    <CustomForm
+      ref={formRef}
+      config={config}
+      onButtonClick={handleButtonClick}
+    />
+  );
+}
+```
+
+#### CustomLogin
+
+Comprehensive login component with Login, Register, and MFA views.
+
+**Props:**
+- `config` (object): Login configuration
+- `onLogin` (function): Login handler
+- `onRegister` (function): Register handler
+- `onMFAVerify` (function): MFA verification handler
+- `theme` (string): 'light' or 'dark'
+
+**Example:**
+```javascript
+import { CustomLogin } from 'sdcpl-react-component';
+
+function MyComponent() {
+  const handleLogin = (credentials) => {
+    console.log('Login:', credentials);
+  };
+
+  return (
+    <CustomLogin
+      config={{
+        title: 'Welcome Back',
+        logo: 'user-circle'
+      }}
+      onLogin={handleLogin}
+    />
+  );
+}
+```
+
+#### HomePageComponent
+
+Complete application layout with title bar, menu sidebar, container, and status bar.
+
+**Props:**
+- `config` (object): Homepage configuration
+- `onEvent` (function): Unified event handler
+- `theme` (string): 'light' or 'dark'
+
+**Example:**
+```javascript
+import { HomePageComponent } from 'sdcpl-react-component';
+
+function MyComponent() {
+  const handleEvent = (event) => {
+    console.log('Event:', event);
+  };
+
+  return (
+    <HomePageComponent
+      config={{
+        titleBar: { title: 'My Application', logo: 'home' },
+        menu: { data: menuData }
+      }}
+      onEvent={handleEvent}
+    />
+  );
+}
+```
+
+### Data Components
+
+#### CustomTable
+
+Data grid with inline editing, formulas, and custom cell types.
+
+**Props:**
+- `columns` (array): Column definitions
+- `data` (array): Table data (2D array)
+- `onChange` (function): Data change handler
+- `onCellBlur` (function): Cell blur handler
+- `onCellFocus` (function): Cell focus handler
+- `doNotAllowRowAdd` (boolean): Disable row addition
+- `loading` (boolean): Show loading state
+
+**Methods (via ref):**
+- `getValue()`: Returns table data as 2D array
+- `getObjectValue()`: Returns table data with column metadata
+- `setValue(data)`: Sets table data
+- `getCellValue(row, col)`: Gets cell value
+- `setCellValue(row, col, value)`: Sets cell value
+- `addRow()`: Adds new row
+- `deleteRow(rowIndex)`: Deletes row
+
+**Example:**
+```javascript
+import { CustomTable } from 'sdcpl-react-component';
+import { useRef } from 'react';
+
+function MyComponent() {
+  const tableRef = useRef();
+  
+  const columns = [
+    { header: 'Name', width: 200, type: 'textbox', params: { type: 'text' } },
+    { header: 'Price', width: 120, type: 'textbox', params: { type: 'currency' } },
+    { header: 'Total', width: 120, type: 'label', params: { formula: 'C1 * C2' } }
+  ];
+
+  const data = [
+    ['Laptop', 999.99, ''],
+    ['Desk', 299.99, '']
+  ];
+
+  return (
+    <CustomTable
+      ref={tableRef}
+      columns={columns}
+      data={data}
+      onChange={(newData) => console.log('Data changed:', newData)}
+    />
+  );
+}
+```
+
+#### CustomTableComboBox
+
+Advanced table with embedded combobox columns.
+
+**Props:**
+- `columns` (array): Column definitions (supports combobox type)
+- `data` (array): Table data
+- `onChange` (function): Data change handler
+- Similar to CustomTable props
+
+**Example:**
+```javascript
+import { CustomTableComboBox } from 'sdcpl-react-component';
+
+function MyComponent() {
+  const columns = [
+    { header: 'Product', width: 200, type: 'textbox' },
+    { header: 'Category', width: 150, type: 'combobox', params: {
+      data: { list: [[1, 'Electronics'], [2, 'Furniture']] }
+    }}
+  ];
+
+  return (
+    <CustomTableComboBox
+      columns={columns}
+      data={[['Laptop', '1']]}
+      onChange={(data) => console.log(data)}
+    />
+  );
+}
+```
+
+#### CustomReport
+
+Advanced report component with conditional formatting and data visualization.
+
+**Props:**
+- `config` (object): Report configuration
+- `data` (array): Report data
+- `onEvent` (function): Event handler
+
+**Methods (via ref):**
+- `getValue()`: Returns report data
+- `setValue(data)`: Sets report data
+- `export(format)`: Exports report (format: 'pdf', 'excel', 'csv')
+
+**Example:**
+```javascript
+import { CustomReport } from 'sdcpl-react-component';
+
+function MyComponent() {
+  const reportConfig = {
+    title: 'Sales Report',
+    columns: [
+      { header: 'Date', field: 'date', type: 'date' },
+      { header: 'Amount', field: 'amount', type: 'currency' }
+    ]
+  };
+
+  return (
+    <CustomReport
+      config={reportConfig}
+      data={reportData}
+    />
+  );
+}
+```
+
+#### CustomDashboard
+
+Comprehensive dashboard component with 45+ component types and unified event handling.
+
+**Props:**
+- `config` (object): Dashboard configuration
+- `onEvent` (function): Unified event handler
+- `theme` (string): 'light' or 'dark'
+
+**Methods (via ref):**
+- `getValue()`: Returns dashboard configuration
+- `setValue(config)`: Sets dashboard configuration
+- `getComponentValue(id)`: Gets component value
+- `setComponentValue(id, value)`: Sets component value
+
+**Example:**
+```javascript
+import { CustomDashboard } from 'sdcpl-react-component';
+
+function MyComponent() {
+  const dashboardConfig = {
+    layout: 'grid',
+    components: [
+      { id: 'chart1', type: 'barchart', settings: { data: chartData } },
+      { id: 'table1', type: 'table', settings: { columns: columns, data: data } }
+    ]
+  };
+
+  return (
+    <CustomDashboard
+      config={dashboardConfig}
+      onEvent={(event) => console.log('Event:', event)}
+    />
+  );
+}
+```
+
+### Dashboard Components
+
+The library includes 30+ dashboard chart components:
+
+- **BarChart** - Bar chart visualization
+- **LineChart** - Line chart visualization
+- **PieChart** - Pie chart visualization
+- **ScatterPlot** - Scatter plot visualization
+- **Radar** - Radar chart
+- **HeatMap** - Heat map visualization
+- **BoxPlot** - Box plot visualization
+- **PolarBar** - Polar bar chart
+- **Sankey** - Sankey diagram
+- **TreeMap** - Tree map visualization
+- **Sunburst** - Sunburst chart
+- **Tree** - Tree visualization
+- **Icicle** - Icicle chart
+- **CirclePacking** - Circle packing visualization
+- **Voronoi** - Voronoi diagram
+- **Funnel** - Funnel chart
+- **Stream** - Stream graph
+- **Bump** - Bump chart
+- **Bullet** - Bullet chart
+- **Chord** - Chord diagram
+- **Network** - Network graph
+- **ParallelCoordinates** - Parallel coordinates
+- **Calendar** - Calendar heatmap
+- **Waffle** - Waffle chart
+- **SwarmPlot** - Swarm plot
+- **RadialBar** - Radial bar chart
+- **Marimekko** - Marimekko chart
+- **Geo** - Geographic visualization
+- **ActivityFeed** - Activity feed component
+- **MetricCard** - Metric card display
+- **DataTable** - Data table widget
+- **MuiChartWrapper** - MUI chart wrapper
+- **HeatmapVisualizer** - Heatmap visualizer
+- **ComparisonVisualizer** - Comparison visualizer
+- **DistributionVisualizer** - Distribution visualizer
+- **MultiMetricVisualizer** - Multi-metric visualizer
+- **ProgressVisualizer** - Progress visualizer
+- **TimeSeriesVisualizer** - Time series visualizer
+
+**Example:**
+```javascript
+import { BarChart, LineChart, PieChart } from 'sdcpl-react-component';
+
+function MyComponent() {
+  const chartData = [
+    { x: 'Jan', y: 100 },
+    { x: 'Feb', y: 150 },
+    { x: 'Mar', y: 200 }
+  ];
+
+  return (
+    <div>
+      <BarChart data={chartData} />
+      <LineChart data={chartData} />
+      <PieChart data={chartData} />
+    </div>
+  );
+}
+```
+
+## 🎨 Theming
+
+All components support CSS variables for theming. Import the styles and customize:
+
+```javascript
+import 'sdcpl-react-component/styles';
+```
+
+Then override CSS variables in your CSS:
+
+```css
+:root {
+  /* Primary Colors */
+  --ctrl-primary-color: #3b82f6;
+  --ctrl-primary-hover: #2563eb;
+  --ctrl-primary-active: #1d4ed8;
+
+  /* Input Colors */
+  --ctrl-input-bg: #ffffff;
+  --ctrl-input-border: #d1d5db;
+  --ctrl-input-focus: #3b82f6;
+
+  /* Text Colors */
+  --ctrl-text-primary: #1f2937;
+  --ctrl-text-secondary: #6b7280;
+  --ctrl-text-disabled: #9ca3af;
+
+  /* Validation Colors */
+  --ctrl-error-color: #ef4444;
+  --ctrl-success-color: #10b981;
+}
+```
+
+## 🔧 Utilities
+
+### Icon Resolver
+
+Resolve FontAwesome icons by name:
+
+```javascript
+import { resolveIcon } from 'sdcpl-react-component';
+
+const icon = resolveIcon('user'); // Returns FontAwesome icon object
+```
+
+### Utility Functions
+
+```javascript
+import { utils } from 'sdcpl-react-component';
+
+// Formatting functions
+utils.formatCurrency(1000, '$'); // '$1,000.00'
+utils.formatNumber(1234.56, 2); // '1,234.56'
+utils.formatDateTime(new Date(), 'date'); // '2024-01-01'
+
+// Validation functions
+utils.validateEmail('test@example.com'); // true
+utils.validatePhone('123-456-7890'); // true
+
+// Focus management
+utils.moveFocus(currentElement, direction); // 'next' | 'prev' | 'first' | 'last'
+```
+
+## 🗄️ IndexedDB Integration
+
+The library includes IndexedDB support for offline data storage:
+
+```javascript
+import { IndexDBStore } from 'sdcpl-react-component';
+
+// Initialize IndexedDB
+await IndexDBStore.initialize('myapp.com', {
+  categories: {
+    version: 1,
+    type: 'object',
+    data: [
+      { id: 1, name: 'Electronics' },
+      { id: 2, name: 'Furniture' }
+    ]
+  }
+});
+
+// Use in ComboBox
+<CustomComboBox
+  datasource="indexdb"
+  indexdbKey="categories"
+  idColumn={0}
+  valueColumn={1}
+/>
+```
+
+## 📝 License
+
+MIT
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## 📧 Support
+
+For issues and questions, please open an issue on GitHub.
+
+---
+
+**Built with ❤️ using React and FontAwesome**
+