@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

npm install @iqworksai/common-components
# or
yarn add @iqworksai/common-components
# or
pnpm add @iqworksai/common-components

Quick Start

Basic Setup

import { ThemeProvider, ToastProvider } from '@iqworksai/common-components';

function App() {
  return (
    <ThemeProvider>
      <ToastProvider>
        {/* Your app content */}
      </ToastProvider>
    </ThemeProvider>
  );
}

Using Components

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

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

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 - Detailed migration progress and roadmap
• Component Migration Guide - Guidelines for migrating components
• Setup Progress - 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

# 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:

import '@iqworksai/common-components/dist/style.css';

2. Configure Tailwind to include the library:

// 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:

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:

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 for guidelines.

Versioning

This project follows Semantic Versioning:

• 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.

Changelog

See 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 for detailed progress and roadmap.

Built with ❤️ by the IQWorks team