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

npm install sdcpl-react-component

Or using yarn:

yarn add sdcpl-react-component

Peer Dependencies

This library requires React and React DOM as peer dependencies:

npm install react react-dom

Optional Dependencies

For full functionality, you may also want to install:

npm install @fortawesome/react-fontawesome @fortawesome/free-solid-svg-icons

🚀 Quick Start

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
  • Form Components
  • Layout Components
  • Data Components
  • Dashboard Components
• Usage Examples
• API Reference
• Theming
• Utilities
• 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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

import 'sdcpl-react-component/styles';

Then override CSS variables in your 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:

import { resolveIcon } from 'sdcpl-react-component';

const icon = resolveIcon('user'); // Returns FontAwesome icon object

Utility Functions

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('[email protected]'); // 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:

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