@iqworksai/common-components 0.1.6 → 0.1.8

package/README.md

@@ -1,398 +1,513 @@
-# @iqworksai/common-components
-
-A reusable React component library and utilities package for IQWorks applications. Provides 46+ UI components, custom hooks, context providers, and utility functions extracted from DiscoverIQ Desktop.
-
-## 🎉 Current Status
-
-**Progress: 35 out of 46 components migrated (76%)**
-
-### ✅ Completed Categories
-- ✅ **Context Providers**: 4/4 (100%) - ThemeProvider, LoaderProvider, ToastProvider, ContextProvider
-- ✅ **Hooks**: 7/7 (100%) - All custom hooks migrated
-- ✅ **Basic UI Components**: 13/13 (100%) - Alert, Modal, Toast, ToolTip, StatusBadge, etc.
-- ✅ **Chart Components**: 7/7 (100%) - DonutChart, PieChart, BarCharts, GaugeChart, GeoChart, StorageChart
-- ✅ **Chart Helper Components**: 3/3 (100%) - NoDataChart, ChartHeader, CustomLegends
-- ✅ **Utility Components**: 4/4 (100%) - ConfirmationModal, Timer, ErrorBoundary, ComponentErrorBoundary
-- ✅ **Form Components**: 4/4 (100%) - Dropdown, MultiSelect, Table, CSVImporter
-- ✅ **Specialized Components**: 4/4 (100%) - TaskResult, InstallUpdateLoader, ConfidenceScoreTooltip, ImagePreviewModal
-
-### ⏳ In Progress
-- 🔄 **FilterModal** - Advanced filtering modal (next priority)
-- 📋 **Remaining Components**: 11 components remaining (FileBrowser, DbSchemaBrowser, MixedScanResults, etc.)
-
-## Features
-
-- 🎨 **35+ UI Components** - Comprehensive set of React components including modals, charts, forms, and data display components
-- 🪝 **7 Custom Hooks** - Reusable React hooks for common patterns (debounce, API caching, click outside, etc.)
-- 🎯 **4 Context Providers** - Theme, Toast, Loader, and main Context providers
-- 🛠️ **Utility Functions** - Data transformation, risk scoring, status configuration, and more
-- 📚 **Storybook Documentation** - Interactive component documentation with live examples for all migrated components
-- 🎯 **TypeScript** - Full TypeScript support with comprehensive type definitions
-- 🌲 **Tree-shakeable** - Optimized for bundle size with ES modules
-- ♿ **Accessible** - WCAG compliant components with keyboard navigation support
-- 🎨 **Tailwind CSS** - Styled with Tailwind CSS for easy customization
-- 🌓 **Dark Mode** - Full dark mode support via CSS variables and ThemeProvider
-- 🔌 **Optional Dependencies** - Redux and React Router are optional, making the library flexible
-
-## Installation
-
-```bash
-npm install @iqworksai/common-components
-# or
-yarn add @iqworksai/common-components
-# or
-pnpm add @iqworksai/common-components
-```
-
-## Quick Start
-
-### Basic Setup
-
-```tsx
-import { ThemeProvider, ToastProvider } from '@iqworksai/common-components';
-
-function App() {
-  return (
-    <ThemeProvider>
-      <ToastProvider>
-        {/* Your app content */}
-      </ToastProvider>
-    </ThemeProvider>
-  );
-}
-```
-
-### Using Components
-
-```tsx
-import { Alert, Modal, Loader, Table } from '@iqworksai/common-components';
-
-function MyComponent() {
-  return (
-    <div>
-      <Alert message="Welcome!" type="success" />
-      <Loader loading={true} />
-      <Table data={myData} columns={myColumns} />
-    </div>
-  );
-}
-```
-
-### Using Hooks
-
-```tsx
-import { useDebounce, useClickOutside } from '@iqworksai/common-components';
-
-function SearchComponent() {
-  const [searchTerm, setSearchTerm] = useState('');
-  const debouncedSearch = useDebounce(searchTerm, 500);
-  
-  // Use debouncedSearch for API calls
-}
-```
-
-### Using Utilities
-
-```tsx
-import { formatBytes, getStatusConfig, getRiskScoreInfo } from '@iqworksai/common-components';
-
-const size = formatBytes(1024); // "1 KB"
-const status = getStatusConfig('successful'); // Status configuration with icon and colors
-const riskInfo = getRiskScoreInfo(75); // Risk level information
-```
-
-## Documentation
-
-- **Storybook Documentation** - Run `npm run storybook` to view interactive component playground with live examples
-- **[Next Steps](./NEXT_STEPS.md)** - Detailed migration progress and roadmap
-- **[Component Migration Guide](./COMPONENT_MIGRATION_GUIDE.md)** - Guidelines for migrating components
-- **[Setup Progress](./SETUP_PROGRESS.md)** - Setup and configuration progress
-
-### Recent Accomplishments
-
-- ✅ **CSVImporter Component** - CSV import with preview, validation, and optional TestConnection integration
-- ✅ **Table Component** - Complex table with search, export, pagination, sorting, and bulk actions (Redux optional)
-- ✅ **All Chart Components** - 7 chart types with full dark mode support
-- ✅ **All Context Providers** - Theme, Toast, Loader, and ContextProvider with optional Redux/Router
-- ✅ **All Hooks** - 7 custom hooks with optional Redux integration
-- ✅ **Dark Mode Support** - All components support dark mode via CSS variables
-- ✅ **Storybook Stories** - All migrated components have comprehensive Storybook stories
-
-## Component Categories
-
-### ✅ Basic UI Components (13/13 - 100%)
-- **Alert** - Alert messages with variants (success, error, warning, info)
-- **Loader** - Loading spinner component
-- **Modal** - Modal dialog with header, body, and footer
-- **Toast** - Toast notification component
-- **ToolTip** - Tooltip component with positioning
-- **StatusBadge** - Status badge with icons and animations
-- **ToggleSwitch** - Toggle switch component
-- **ResourceUsageBadge** - Resource usage indicator
-- **ShowMultiData** - Expandable multi-line data display
-- **RiskScoreLabel** - Risk score display with color coding
-- **FileTypeIcon** - File type icon component
-- **NoActiveAttributeWarning** - Warning message component
-- **CountryBox** - Country selection/display box
-
-### ✅ Form Components (4/4 - 100%)
-- **Dropdown** - Dropdown menu using Headless UI
-- **MultiSelect** - Multi-select component using react-select
-- **Table** - Advanced table component with pagination, sorting, search, export, and bulk actions (Redux optional)
-- **CSVImporter** - CSV import component with preview and validation
-
-### ✅ Chart Components (7/7 - 100%)
-- **DonutChart** - Doughnut chart with legends and optional table
-- **PieChart** - Pie chart with percentage labels
-- **VerticalBarChart** - Vertical bar chart with optional line overlay
-- **HorizontalBarChart** - Horizontal bar chart with scale options (linear, logarithmic, normalized)
-- **GaugeChart** - Gauge/donut chart with optional year range slider
-- **GeoChart** - Geographic choropleth map chart
-- **StorageChart** - Storage visualization with icon and formatted values
-
-### ✅ Chart Helper Components (3/3 - 100%)
-- **NoDataChart** - Empty state component for charts
-- **ChartHeader** - Chart header with title and optional right content
-- **CustomLegends** - Custom legend component for charts
-
-### ✅ Utility Components (4/4 - 100%)
-- **ConfirmationModal** - Confirmation dialog with customizable actions
-- **Timer** - Countdown/elapsed time display
-- **ErrorBoundary** - Top-level error boundary with fallback UI
-- **ComponentErrorBoundary** - Component-level error boundary
-
-### ✅ Specialized Components (4/4 - 100%)
-- **TaskResult** - Task result modal with summary and error details
-- **InstallUpdateLoader** - Installation/update progress loader
-- **ConfidenceScoreTooltip** - Classification confidence score tooltip
-- **ImagePreviewModal** - Image preview modal with loading and error handling
-
-### ⏳ Remaining Components (11 components)
-- **FilterModal** - Advanced filtering modal (in progress)
-- **FileBrowser** - File browsing interface
-- **DbSchemaBrowser** - Database schema browser
-- **MixedScanResults** - Combined file and database scan results
-- **NotificationQueue** - Toast notification queue
-- **ProductSwitcher** - Product selection switcher
-- **TestConnection** - Connection testing component
-- **CustomRecurrenceDialog** - Recurrence pattern dialog
-- **UpdateDepartmentModal** - Department update modal
-- **UpdateSettings** - Settings update component
-- **UserAppUpdateSettings** - User app update settings
-
-## Hooks (7/7 - 100% Complete)
-
-- ✅ **useApiCache** - API response caching hook with Redux integration (optional)
-- ✅ **useAssetPath** / **useFileIconPath** - Asset path resolution hook (Electron-agnostic)
-- ✅ **useBodyScrollLock** - Body scroll lock hook for modals
-- ✅ **useClickOutside** - Click outside detection hook
-- ✅ **useDebounce** - Debounce hook for input values
-- ✅ **useFilterCache** - Filter state caching hook with Redux integration (optional)
-- ✅ **useReduxHook** - Redux integration hook (useAppDispatch, useAppSelector) - gracefully handles missing Redux
-
-## Context Providers (4/4 - 100% Complete)
-
-- ✅ **ThemeProvider** - Theme management (light/dark mode) with CSS variables, custom fonts, and global styling
-- ✅ **ToastProvider** - Toast notification management with optional Redux integration
-- ✅ **LoaderProvider** - Global loading state management
-- ✅ **ContextProvider** - Main context provider wrapper that aggregates all providers (Redux and Router optional)
-
-## Development
-
-### Prerequisites
-
-- Node.js 18+ 
-- npm, yarn, or pnpm
-
-### Setup
-
-```bash
-# Clone the repository
-git clone https://github.com/iqworksai/common-components.git
-cd common-components
-
-# Install dependencies
-npm install
-
-# Run Storybook
-npm run storybook
-
-# Build library
-npm run build
-
-# Run tests
-npm test
-
-# Run tests with coverage
-npm run test:coverage
-```
-
-### Available Scripts
-
-- `npm run build` - Build the library for production
-- `npm run build:watch` - Build in watch mode
-- `npm run typecheck` - Type check without emitting
-- `npm test` - Run tests
-- `npm run test:watch` - Run tests in watch mode
-- `npm run test:coverage` - Run tests with coverage
-- `npm run lint` - Lint code
-- `npm run lint:fix` - Fix linting issues
-- `npm run storybook` - Start Storybook dev server
-- `npm run build-storybook` - Build Storybook for deployment
-
-## Styling
-
-This library uses Tailwind CSS with CSS variables for theming. To use the components in your project:
-
-1. **Import the styles** in your app:
-```tsx
-import '@iqworksai/common-components/dist/style.css';
-```
-
-2. **Configure Tailwind** to include the library:
-```js
-// tailwind.config.js
-module.exports = {
-  content: [
-    './src/**/*.{js,jsx,ts,tsx}',
-    './node_modules/@iqworksai/common-components/**/*.{js,jsx,ts,tsx}',
-  ],
-  darkMode: 'class', // Required for dark mode support
-  // ... rest of config
-};
-```
-
-3. **Wrap your app with ThemeProvider** for theme support:
-```tsx
-import { ThemeProvider } from '@iqworksai/common-components';
-
-function App() {
-  return (
-    <ThemeProvider>
-      {/* Your app */}
-    </ThemeProvider>
-  );
-}
-```
-
-### CSS Variables
-
-The library uses CSS variables for theming. Key variables include:
-- `--bg-color` - Background color
-- `--text-color` - Text color
-- `--border-color` - Border color
-- `--brand-primary` - Primary brand color (orange)
-- `--brand-light` - Light brand color
-- `--brand-dark` - Dark brand color
-- `--hover-bg-color` - Hover background color
-
-See `src/styles/index.css` for the complete list of CSS variables.
-
-## TypeScript Support
-
-Full TypeScript support is included. Import types as needed:
-
-```tsx
-import type { 
-  AlertProps, 
-  TableProps, 
-  CSVRow,
-  PaginatedResult,
-  ListApiParameters,
-  FilterState,
-  FilterField
-} from '@iqworksai/common-components';
-```
-
-### Type Definitions
-
-All components export their prop types. Key type exports include:
-- Component prop types (e.g., `AlertProps`, `TableProps`, `ModalProps`)
-- Table types (`PaginatedResult`, `ListApiParameters`, `FilterState`, `FilterField`)
-- CSV types (`CSVRow`)
-- Status types (`StatusConfig`, `RiskScoreInfo`)
-- Context types (`ThemeConfig`, `ToastContextProps`, `LoaderContextProps`)
-
-## Browser Support
-
-- Chrome (latest)
-- Firefox (latest)
-- Safari (latest)
-- Edge (latest)
-
-## Contributing
-
-Contributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
-
-## Versioning
-
-This project follows [Semantic Versioning](https://semver.org/):
-- **MAJOR** version for breaking changes
-- **MINOR** version for new features (backward compatible)
-- **PATCH** version for bug fixes (backward compatible)
-
-## License
-
-PROPRIETARY - Internal use only
-
-## Support
-
-For issues and questions, please open an issue on [GitHub](https://github.com/iqworksai/common-components/issues).
-
-## Changelog
-
-See [CHANGELOG.md](./CHANGELOG.md) for a list of changes.
-
-## Key Features & Highlights
-
-### 🎯 Optional Dependencies
-- **Redux** - All Redux dependencies are optional. Components work without Redux, but can integrate if available.
-- **React Router** - Router is optional in ContextProvider.
-- **Electron** - All Electron-specific code has been removed or made optional.
-
-### 🌓 Dark Mode
-- All components support dark mode via CSS variables.
-- ThemeProvider manages theme state and CSS variables.
-- Seamless theme switching with `toggleTheme()`.
-
-### 📊 Advanced Table Component
-- Pagination, sorting, searching, and filtering
-- Bulk actions support
-- Export to CSV functionality
-- Optional Redux integration
-- Optional FilterModal integration
-- Row click handlers
-- Column borders and styling options
-
-### 📈 Chart Components
-- 7 chart types using Chart.js
-- Full dark mode support
-- Custom legends and headers
-- Empty state handling
-- Responsive and accessible
-
-### 🎨 Theming
-- CSS variable-based theming
-- Custom font support
-- Global style overrides
-- Consistent color palette
-
-## Migration Status
-
-**35 out of 46 components completed (76%)**
-
-- ✅ All basic UI components
-- ✅ All chart components
-- ✅ All context providers
-- ✅ All hooks
-- ✅ All form components (including complex Table)
-- ✅ All utility components
-- ⏳ FilterModal (in progress)
-- ⏳ 10 remaining specialized components
-
-See [NEXT_STEPS.md](./NEXT_STEPS.md) for detailed progress and roadmap.
-
----
-
-Built with ❤️ by the IQWorks team
-
+# @iqworksai/common-components
+
+A reusable React component library and utilities package for IQWorks applications. Provides 37+ UI components (80% complete), custom hooks, context providers, and utility functions extracted from DiscoverIQ Desktop. Fully SSR-compatible and Next.js ready.
+
+## 🎉 Current Status
+
+**Progress: 37 out of 46 components migrated (80%)**
+
+### ✅ Completed Categories
+- ✅ **Context Providers**: 4/4 (100%) - ThemeProvider, LoaderProvider, ToastProvider, ContextProvider
+- ✅ **Hooks**: 7/7 (100%) - All custom hooks migrated
+- ✅ **Basic UI Components**: 13/13 (100%) - Alert, Modal, Toast, ToolTip, StatusBadge, etc.
+- ✅ **Chart Components**: 7/7 (100%) - DonutChart, PieChart, BarCharts, GaugeChart, GeoChart, StorageChart
+- ✅ **Chart Helper Components**: 3/3 (100%) - NoDataChart, ChartHeader, CustomLegends
+- ✅ **Utility Components**: 4/4 (100%) - ConfirmationModal, Timer, ErrorBoundary, ComponentErrorBoundary
+- ✅ **Form Components**: 4/4 (100%) - Dropdown, MultiSelect, Table, CSVImporter
+- ✅ **Specialized Components**: 6/6 (100%) - TaskResult, InstallUpdateLoader, ConfidenceScoreTooltip, ImagePreviewModal, FileBrowser, DbSchemaBrowser
+
+### ⏳ In Progress
+- 🔄 **FilterModal** - Advanced filtering modal (next priority)
+- 📋 **Remaining Components**: 9 components remaining (MixedScanResults, NotificationQueue, etc.)
+
+## Features
+
+- 🎨 **37+ UI Components** - Comprehensive set of React components including modals, charts, forms, file browsers, and data display components
+- 🪝 **7 Custom Hooks** - Reusable React hooks for common patterns (debounce, API caching, click outside, etc.)
+- 🎯 **4 Context Providers** - Theme, Toast, Loader, and main Context providers
+- 🛠️ **Utility Functions** - Data transformation, risk scoring, status configuration, file browser utilities, and more
+- 📚 **Storybook Documentation** - Interactive component documentation with live examples for all migrated components
+- 🎯 **TypeScript** - Full TypeScript support with comprehensive type definitions
+- 🌲 **Tree-shakeable** - Optimized for bundle size with ES modules
+- ♿ **Accessible** - WCAG compliant components with keyboard navigation support
+- 🎨 **Tailwind CSS** - Styled with Tailwind CSS for easy customization
+- 🌓 **Dark Mode** - Full dark mode support via CSS variables and ThemeProvider
+- 🔌 **Optional Dependencies** - Redux and React Router are optional, making the library flexible
+- ⚡ **SSR Compatible** - Components are SSR-safe and work with Next.js (jQuery, jstree, and ReactFlow load client-side only)
+
+## Installation
+
+```bash
+npm install @iqworksai/common-components
+# or
+yarn add @iqworksai/common-components
+# or
+pnpm add @iqworksai/common-components
+```
+
+## Quick Start
+
+### Basic Setup
+
+```tsx
+import { ThemeProvider, ToastProvider } from '@iqworksai/common-components';
+
+function App() {
+  return (
+    <ThemeProvider>
+      <ToastProvider>
+        {/* Your app content */}
+      </ToastProvider>
+    </ThemeProvider>
+  );
+}
+```
+
+### Using Components
+
+```tsx
+import { Alert, Modal, Loader, Table } from '@iqworksai/common-components';
+
+function MyComponent() {
+  return (
+    <div>
+      <Alert message="Welcome!" type="success" />
+      <Loader loading={true} />
+      <Table data={myData} columns={myColumns} />
+    </div>
+  );
+}
+```
+
+### Using Hooks
+
+```tsx
+import { useDebounce, useClickOutside } from '@iqworksai/common-components';
+
+function SearchComponent() {
+  const [searchTerm, setSearchTerm] = useState('');
+  const debouncedSearch = useDebounce(searchTerm, 500);
+  
+  // Use debouncedSearch for API calls
+}
+```
+
+### Using Utilities
+
+```tsx
+import { 
+  formatBytes, 
+  getStatusConfig, 
+  getRiskScoreInfo,
+  convertScanObjectToFiledata,
+  formatDateTime,
+  convertScanObjectToDbSchema
+} from '@iqworksai/common-components';
+
+const size = formatBytes(1024); // "1 KB"
+const status = getStatusConfig('successful'); // Status configuration with icon and colors
+const riskInfo = getRiskScoreInfo(75); // Risk level information
+const fileData = convertScanObjectToFiledata(scanObject); // Convert scan object to file metadata
+const dbSchema = convertScanObjectToDbSchema(scanObject); // Convert scan object to database schema
+```
+
+### Using FileBrowser and DbSchemaBrowser
+
+```tsx
+import { FileBrowser, DbSchemaBrowser } from '@iqworksai/common-components';
+
+// FileBrowser requires an API interface
+const fileBrowserApi = {
+  readIndexScanObjectsForPath: async (uuid, path, filters, search, page, pageSize, isScanCompleted) => {
+    // Your API implementation
+    return { data: [], hasMore: false };
+  }
+};
+
+<FileBrowser 
+  scanConnectorUuid="uuid"
+  api={fileBrowserApi}
+  isEditable={true}
+/>
+
+// DbSchemaBrowser also requires an API interface
+const dbSchemaApi = {
+  readIndexScanObjects: async (uuid) => ({ data: [] }),
+  readConfig: async (options) => ({ data: [] }),
+  readScanReportDetails: async (options) => ({}),
+  startSelectedTableScan: async (params) => 'success'
+};
+
+<DbSchemaBrowser 
+  scanConnectorUuid="uuid"
+  api={dbSchemaApi}
+  connectionType="mssql"
+  isEditable={true}
+/>
+```
+
+## Documentation
+
+- **Storybook Documentation** - Run `npm run storybook` to view interactive component playground with live examples
+- **[Next Steps](./NEXT_STEPS.md)** - Detailed migration progress and roadmap
+- **[Component Migration Guide](./COMPONENT_MIGRATION_GUIDE.md)** - Guidelines for migrating components
+- **[Setup Progress](./SETUP_PROGRESS.md)** - Setup and configuration progress
+
+### Recent Accomplishments
+
+- ✅ **FileBrowser Component** - File browsing interface with hierarchical tree view, search, pagination, and metadata display (SSR-safe for Next.js)
+- ✅ **DbSchemaBrowser Component** - Interactive database schema browser with graph visualization, table selection, and attribute mapping (SSR-safe for Next.js)
+- ✅ **CSVImporter Component** - CSV import with preview, validation, and optional TestConnection integration
+- ✅ **Table Component** - Complex table with search, export, pagination, sorting, and bulk actions (Redux optional)
+- ✅ **All Chart Components** - 7 chart types with full dark mode support
+- ✅ **All Context Providers** - Theme, Toast, Loader, and ContextProvider with optional Redux/Router
+- ✅ **All Hooks** - 7 custom hooks with optional Redux integration
+- ✅ **Dark Mode Support** - All components support dark mode via CSS variables
+- ✅ **SSR/Next.js Compatibility** - FileBrowser and DbSchemaBrowser are SSR-safe with client-side library loading
+- ✅ **Storybook Stories** - All migrated components have comprehensive Storybook stories
+
+## Component Categories
+
+### ✅ Basic UI Components (13/13 - 100%)
+- **Alert** - Alert messages with variants (success, error, warning, info)
+- **Loader** - Loading spinner component
+- **Modal** - Modal dialog with header, body, and footer
+- **Toast** - Toast notification component
+- **ToolTip** - Tooltip component with positioning
+- **StatusBadge** - Status badge with icons and animations
+- **ToggleSwitch** - Toggle switch component
+- **ResourceUsageBadge** - Resource usage indicator
+- **ShowMultiData** - Expandable multi-line data display
+- **RiskScoreLabel** - Risk score display with color coding
+- **FileTypeIcon** - File type icon component
+- **NoActiveAttributeWarning** - Warning message component
+- **CountryBox** - Country selection/display box
+
+### ✅ Form Components (4/4 - 100%)
+- **Dropdown** - Dropdown menu using Headless UI
+- **MultiSelect** - Multi-select component using react-select
+- **Table** - Advanced table component with pagination, sorting, search, export, and bulk actions (Redux optional)
+- **CSVImporter** - CSV import component with preview and validation
+
+### ✅ Chart Components (7/7 - 100%)
+- **DonutChart** - Doughnut chart with legends and optional table
+- **PieChart** - Pie chart with percentage labels
+- **VerticalBarChart** - Vertical bar chart with optional line overlay
+- **HorizontalBarChart** - Horizontal bar chart with scale options (linear, logarithmic, normalized)
+- **GaugeChart** - Gauge/donut chart with optional year range slider
+- **GeoChart** - Geographic choropleth map chart
+- **StorageChart** - Storage visualization with icon and formatted values
+
+### ✅ Chart Helper Components (3/3 - 100%)
+- **NoDataChart** - Empty state component for charts
+- **ChartHeader** - Chart header with title and optional right content
+- **CustomLegends** - Custom legend component for charts
+
+### ✅ Utility Components (4/4 - 100%)
+- **ConfirmationModal** - Confirmation dialog with customizable actions
+- **Timer** - Countdown/elapsed time display
+- **ErrorBoundary** - Top-level error boundary with fallback UI
+- **ComponentErrorBoundary** - Component-level error boundary
+
+### ✅ Specialized Components (6/6 - 100%)
+- **TaskResult** - Task result modal with summary and error details
+- **InstallUpdateLoader** - Installation/update progress loader
+- **ConfidenceScoreTooltip** - Classification confidence score tooltip
+- **ImagePreviewModal** - Image preview modal with loading and error handling
+- **FileBrowser** - File browsing interface with tree view, search, pagination, and metadata display (uses jstree)
+- **DbSchemaBrowser** - Database schema browser with interactive graph visualization (uses ReactFlow)
+
+### ⏳ Remaining Components (9 components)
+- **FilterModal** - Advanced filtering modal (in progress)
+- **MixedScanResults** - Combined file and database scan results
+- **NotificationQueue** - Toast notification queue
+- **ProductSwitcher** - Product selection switcher
+- **TestConnection** - Connection testing component
+- **CustomRecurrenceDialog** - Recurrence pattern dialog
+- **UpdateDepartmentModal** - Department update modal
+- **UpdateSettings** - Settings update component
+- **UserAppUpdateSettings** - User app update settings
+
+## Hooks (7/7 - 100% Complete)
+
+- ✅ **useApiCache** - API response caching hook with Redux integration (optional)
+- ✅ **useAssetPath** / **useFileIconPath** - Asset path resolution hook (Electron-agnostic)
+- ✅ **useBodyScrollLock** - Body scroll lock hook for modals
+- ✅ **useClickOutside** - Click outside detection hook
+- ✅ **useDebounce** - Debounce hook for input values
+- ✅ **useFilterCache** - Filter state caching hook with Redux integration (optional)
+- ✅ **useReduxHook** - Redux integration hook (useAppDispatch, useAppSelector) - gracefully handles missing Redux
+
+## Utility Functions
+
+### General Utilities
+- **formatBytes** - Format bytes to human-readable size (KB, MB, GB, etc.)
+- **cn** - Class name utility (similar to clsx)
+- **conditionalClass** - Conditional class name utility
+- **switchClass** - Switch-based class name utility
+- **globalFiltersEqual** - Deep equality check for filter objects
+- **deepEqual** - Deep equality comparison utility
+
+### Status & Risk Utilities
+- **getStatusConfig** - Get status configuration with icon and colors
+- **isRunningStatus** - Check if status is running
+- **isFailedStatus** - Check if status is failed
+- **isSuccessStatus** - Check if status is successful
+- **getRiskLevel** - Get risk level from score
+- **getRiskScoreInfo** - Get risk score information with color and label
+- **isHighRisk** - Check if risk score is high
+
+### FileBrowser Utilities
+- **convertScanObjectToFiledata** - Convert scan object to file metadata format
+- **formatDateTime** - Format date/time to readable string
+- **isChildPath** - Check if path is a child of another path
+- **ucwords** - Capitalize first letter of each word
+
+### DbSchemaBrowser Utilities
+- **convertScanObjectToDbSchema** - Convert scan object to database schema format
+- **extractAttributeMapping** - Extract attribute mappings from metadata
+- **extractConfidenceMetadata** - Extract confidence metadata from scan objects
+- **getConfidenceColor** - Get color class for confidence score
+
+## Constants
+
+- **FILE_BROWSER_PAGE_SIZE** - Default page size for file browser pagination (50)
+- **NOT_APPLICABLE** - Constant for N/A values ('-')
+- **METADATA_KEYS** - Metadata key constants (attribute_mapping, confidence_metadata)
+- **PAGE_SIZE**, **PAGE_INDEX** - Table pagination constants
+- **STATUS_BADGE_CLASSES** - Status badge CSS class mappings
+
+## Context Providers (4/4 - 100% Complete)
+
+- ✅ **ThemeProvider** - Theme management (light/dark mode) with CSS variables, custom fonts, and global styling
+- ✅ **ToastProvider** - Toast notification management with optional Redux integration
+- ✅ **LoaderProvider** - Global loading state management
+- ✅ **ContextProvider** - Main context provider wrapper that aggregates all providers (Redux and Router optional)
+
+## Development
+
+### Prerequisites
+
+- Node.js 18+ 
+- npm, yarn, or pnpm
+
+### Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/iqworksai/common-components.git
+cd common-components
+
+# Install dependencies
+npm install
+
+# Run Storybook
+npm run storybook
+
+# Build library
+npm run build
+
+# Run tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+```
+
+### Available Scripts
+
+- `npm run build` - Build the library for production
+- `npm run build:watch` - Build in watch mode
+- `npm run typecheck` - Type check without emitting
+- `npm test` - Run tests
+- `npm run test:watch` - Run tests in watch mode
+- `npm run test:coverage` - Run tests with coverage
+- `npm run lint` - Lint code
+- `npm run lint:fix` - Fix linting issues
+- `npm run storybook` - Start Storybook dev server
+- `npm run build-storybook` - Build Storybook for deployment
+
+## Styling
+
+This library uses Tailwind CSS with CSS variables for theming. To use the components in your project:
+
+1. **Import the styles** in your app:
+```tsx
+import '@iqworksai/common-components/dist/style.css';
+```
+
+2. **Configure Tailwind** to include the library:
+```js
+// tailwind.config.js
+module.exports = {
+  content: [
+    './src/**/*.{js,jsx,ts,tsx}',
+    './node_modules/@iqworksai/common-components/**/*.{js,jsx,ts,tsx}',
+  ],
+  darkMode: 'class', // Required for dark mode support
+  // ... rest of config
+};
+```
+
+3. **Wrap your app with ThemeProvider** for theme support:
+```tsx
+import { ThemeProvider } from '@iqworksai/common-components';
+
+function App() {
+  return (
+    <ThemeProvider>
+      {/* Your app */}
+    </ThemeProvider>
+  );
+}
+```
+
+### CSS Variables
+
+The library uses CSS variables for theming. Key variables include:
+- `--bg-color` - Background color
+- `--text-color` - Text color
+- `--border-color` - Border color
+- `--brand-primary` - Primary brand color (orange)
+- `--brand-light` - Light brand color
+- `--brand-dark` - Dark brand color
+- `--hover-bg-color` - Hover background color
+
+See `src/styles/index.css` for the complete list of CSS variables.
+
+## TypeScript Support
+
+Full TypeScript support is included. Import types as needed:
+
+```tsx
+import type { 
+  AlertProps, 
+  TableProps, 
+  CSVRow,
+  PaginatedResult,
+  ListApiParameters,
+  FilterState,
+  FilterField
+} from '@iqworksai/common-components';
+```
+
+### Type Definitions
+
+All components export their prop types. Key type exports include:
+- Component prop types (e.g., `AlertProps`, `TableProps`, `ModalProps`, `FileBrowserProps`, `DBMetadataTableProps`)
+- Table types (`PaginatedResult`, `ListApiParameters`, `FilterState`, `FilterField`)
+- CSV types (`CSVRow`)
+- Status types (`StatusConfig`, `RiskScoreInfo`)
+- Context types (`ThemeConfig`, `ToastContextProps`, `LoaderContextProps`)
+- FileBrowser types (`FileMetadata`, `ScanReport`, `FileBrowserApi`, `FileBrowserScanObject`)
+- DbSchemaBrowser types (`Column`, `NodeData`, `SelectedTable`, `Attribute`, `CountryData`, `DbSchemaBrowserApi`, `DbSchemaScanObject`)
+
+## Dependencies
+
+### Core Dependencies
+- **React 18+** - Required peer dependency
+- **dayjs** - Date/time manipulation (replaces moment)
+- **jquery** - Required for FileBrowser (loaded client-side only)
+- **jstree** - Tree view component for FileBrowser (loaded client-side only)
+- **reactflow** - Graph visualization for DbSchemaBrowser (loaded client-side only)
+- **react-icons** - Icon library
+- **react-select** - Select component
+- **chart.js** - Chart components
+- **@tanstack/react-table** - Table component
+
+### Optional Dependencies
+- **@reduxjs/toolkit** - Optional Redux integration
+- **react-redux** - Optional Redux integration
+- **react-router-dom** - Optional router integration
+
+## Browser Support
+
+- Chrome (latest)
+- Firefox (latest)
+- Safari (latest)
+- Edge (latest)
+- Next.js 13+ (SSR compatible)
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+
+## Versioning
+
+This project follows [Semantic Versioning](https://semver.org/):
+- **MAJOR** version for breaking changes
+- **MINOR** version for new features (backward compatible)
+- **PATCH** version for bug fixes (backward compatible)
+
+## License
+
+PROPRIETARY - Internal use only
+
+## Support
+
+For issues and questions, please open an issue on [GitHub](https://github.com/iqworksai/common-components/issues).
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for a list of changes.
+
+## Key Features & Highlights
+
+### 🎯 Optional Dependencies
+- **Redux** - All Redux dependencies are optional. Components work without Redux, but can integrate if available.
+- **React Router** - Router is optional in ContextProvider.
+- **Electron** - All Electron-specific code has been removed or made optional.
+
+### ⚡ SSR & Next.js Compatibility
+- **FileBrowser** - Uses dynamic imports for jQuery and jstree (client-side only), fully SSR-safe
+- **DbSchemaBrowser** - Uses dynamic imports for ReactFlow (client-side only), fully SSR-safe
+- **Date Handling** - Uses dayjs instead of moment for better bundle size and SSR compatibility
+- All components work seamlessly with Next.js server-side rendering
+
+### 🌓 Dark Mode
+- All components support dark mode via CSS variables.
+- ThemeProvider manages theme state and CSS variables.
+- Seamless theme switching with `toggleTheme()`.
+
+### 📊 Advanced Table Component
+- Pagination, sorting, searching, and filtering
+- Bulk actions support
+- Export to CSV functionality
+- Optional Redux integration
+- Optional FilterModal integration
+- Row click handlers
+- Column borders and styling options
+
+### 📈 Chart Components
+- 7 chart types using Chart.js
+- Full dark mode support
+- Custom legends and headers
+- Empty state handling
+- Responsive and accessible
+
+### 🎨 Theming
+- CSS variable-based theming
+- Custom font support
+- Global style overrides
+- Consistent color palette
+
+## Migration Status
+
+**37 out of 46 components completed (80%)**
+
+- ✅ All basic UI components
+- ✅ All chart components
+- ✅ All context providers
+- ✅ All hooks
+- ✅ All form components (including complex Table)
+- ✅ All utility components
+- ✅ FileBrowser and DbSchemaBrowser (SSR-safe, Next.js compatible)
+- ⏳ FilterModal (in progress)
+- ⏳ 8 remaining specialized components
+
+See [NEXT_STEPS.md](./NEXT_STEPS.md) for detailed progress and roadmap.
+
+---
+
+Built with ❤️ by the IQWorks team
+