@akson/cortex-ui-library

@akson/cortex-ui-library

A comprehensive UI components library with best-in-class validation using industry-standard libraries. Perfect for form inputs with robust validation, internationalization, and excellent UX.

Features

• 🎯 Industry-Standard Validation: Uses proven libraries (validator.js, libphonenumber-js)
• 🌍 International Support: Full phone number and address validation for 100+ countries
• 🚀 Google Places Integration: Smart address autocomplete with fallback manual entry
• ♿ Accessible: Full ARIA support and keyboard navigation
• 📱 Mobile First: Responsive design with touch-friendly interactions
• 🎨 Customizable: Flexible styling with CSS classes and variants
• 🧪 Well Tested: Comprehensive test coverage with Jest and Testing Library
• ⚡ Optimized UX: Built-in debouncing, caching, and smart suggestions

Installation

npm install @akson/cortex-ui-library
# or
yarn add @akson/cortex-ui-library
# or
pnpm add @akson/cortex-ui-library

Components

AddressInput

A comprehensive address input component with Google Maps integration and manual entry fallback.

import { AddressInput } from '@akson/cortex-ui-library'

function MyForm() {
  const [address, setAddress] = useState({})

  return (
    <AddressInput
      address={address}
      onChange={setAddress}
      required
      label="Delivery Address"
      googleMapsApiKey="your-api-key" // Optional
      showCoordinates
      validateOnChange
    />
  )
}

Props:

• address: Partial address data object
• onChange: Callback when address changes
• errors: Field-level error messages
• googleMapsApiKey: Optional Google Maps API key for autocomplete
• required: Mark as required field
• label: Field label (default: "Address")
• description: Helper description text
• showCoordinates: Display coordinates when available
• validateOnChange: Validate fields as user types
• disabled: Disable all inputs
• className: Custom CSS classes

PhoneInput

International phone number input with country selection and format validation.

import { PhoneInput } from '@akson/cortex-ui-library'

function MyForm() {
  const [phone, setPhone] = useState('')
  const [isValid, setIsValid] = useState(false)

  return (
    <PhoneInput
      value={phone}
      onChange={setPhone}
      onValidChange={(valid, phoneData) => {
        setIsValid(valid)
        console.log('Phone data:', phoneData)
      }}
      defaultCountry="CH"
      autoFormat
      showValidationIcon
      required
    />
  )
}

OTPInput

Modern one-time password input with industry-standard accessibility and UX features.

import { OTPInput } from '@akson/cortex-ui-library'

function MyForm() {
  const [otp, setOtp] = useState('')

  return (
    <OTPInput
      value={otp}
      onChange={setOtp}
      onComplete={(code) => {
        console.log('OTP completed:', code)
        // Auto-submit when complete
      }}
      length={6}
      label="Verification Code"
      helperText="Enter the code sent to your phone"
      allowedCharacters="numeric"
      required
    />
  )
}

FileUploadField

Enterprise-grade file upload component with Supabase integration support, drag & drop, thumbnails, and advanced validation.

import { FileUploadField, fileUploadPresets } from '@akson/cortex-ui-library'
import { useDocumentUpload } from '@akson/cortex-supabase'

function MyUploadForm() {
  // Supabase integration (optional)
  const documentUpload = useDocumentUpload({
    bucketName: 'documents',
    pathPrefix: 'uploads'
  })

  return (
    <FileUploadField
      uploadHook={documentUpload} // Inject Supabase functionality
      config={{
        ...fileUploadPresets.documents, // Use preset configuration
        maxFiles: 10,
        showThumbnails: true,
        variant: 'gallery'
      }}
      onUploadComplete={(results) => {
        console.log('Files uploaded:', results)
      }}
    />
  )
}

// Without Supabase - use direct upload handler
function CustomUploadForm() {
  const handleUpload = async (files: File[]) => {
    // Your custom upload logic
    return await uploadToMyBackend(files)
  }

  return (
    <FileUploadField
      onUpload={handleUpload}
      config={fileUploadPresets.images}
    />
  )
}

PhoneInput Props:

• value: Current phone number string
• onChange: Callback when phone number changes
• onValidChange: Callback with validation status and parsed phone data
• defaultCountry: Default country code (default: "CH")
• autoFormat: Automatically format phone number
• showValidationIcon: Show validation status icons
• validateOnChange: Validate as user types
• placeholder: Input placeholder
• required: Mark as required field
• disabled: Disable input and country selector

FileUploadField Props:

• uploadHook: Supabase upload hook (from @akson/cortex-supabase)
• batchUploadHook: Batch upload hook for multiple files
• validationHook: Validation hook with custom rules
• onUpload: Direct upload handler (alternative to hooks)
• config: Upload configuration object
• value: Current files array
• onChange: Callback when files change
• onUploadComplete: Callback when upload completes
• onUploadError: Callback when upload fails
• disabled: Disable the upload area
• className: Custom CSS classes

FileUpload Config Options:

• accept: Allowed file types (e.g., ['image/*', 'application/pdf'])
• maxSize: Maximum file size in bytes
• maxFiles: Maximum number of files
• multiple: Allow multiple file selection
• variant: 'default' | 'compact' | 'gallery' | 'minimal'
• showThumbnails: Display file thumbnails
• dragDropEnabled: Enable drag and drop
• autoUpload: Automatically upload when files are added
• validationPosition: 'top' | 'bottom' | 'inline'

Built-in Presets:

• fileUploadPresets.images - Image upload (10MB, thumbnails, gallery view)
• fileUploadPresets.documents - Document upload (50MB, PDF/Office files)
• fileUploadPresets.media - Media files (100MB, images/video/audio)
• fileUploadPresets.profilePicture - Single image (5MB, compact view)
• fileUploadPresets.gallery - Photo gallery (20MB, auto-upload)

OTPInput Props:

• value: Current OTP string
• onChange: Callback when OTP changes
• onComplete: Callback when OTP reaches specified length
• length: Number of digits (default: 6)
• allowedCharacters: 'numeric' or 'alphanumeric' (default: 'numeric')
• autoComplete: Enable browser autocomplete='one-time-code' (default: true)
• pushPasswordManagerStrategy: Auto-adjust for password managers (default: true)
• pasteTransformer: Custom function to transform pasted values
• label: Field label (default: "Verification Code")
• error: Error message to display
• helperText: Helper text to display
• required: Mark as required field
• disabled: Disable the input
• className: Custom CSS classes

Validation Utilities

The library uses industry-standard validation libraries for maximum reliability:

• Email validation: Uses validator.js - the most trusted email validation library
• Phone validation: Uses libphonenumber-js - Google's libphonenumber in JavaScript
• Address validation: Uses use-places-autocomplete for Google Places integration

import {
  required,
  minLength,
  maxLength,
  email,
  parsePhoneNumber,
  validatePhoneNumber,
  validateAddress
} from '@akson/cortex-ui-library'

// Basic validation
const nameValidation = required('John Doe')
const emailValidation = email('[e-mail]') // Uses validator.js

// Phone validation with libphonenumber-js
const phoneData = parsePhoneNumber('[phone]', 'CH')
const phoneValidation = validatePhoneNumber('[phone]')

// Address validation
const addressErrors = validateAddress({
  streetLine1: '123 Main St',
  city: 'Zurich',
  // ... other fields
}, true) // required = true

Styling

The library provides flexible styling through CSS classes. All components use semantic class names:

import { cn, inputVariants } from '@akson/cortex-ui-library'

// Combine classes conditionally
const inputClassName = cn(
  'base-input',
  hasError && 'error-state',
  isDisabled && 'disabled'
)

// Use built-in style variants
const className = cn(
  baseInputStyles,
  hasError ? inputVariants.error : inputVariants.default
)

Built-in Style Variables

// Input styles
baseInputStyles, inputVariants
// Label styles
labelStyles
// Error and helper text
errorStyles, helperTextStyles
// Buttons
buttonStyles, buttonVariants
// Card layout
cardStyles, cardHeaderStyles, cardContentStyles

TypeScript Support

Full TypeScript support with comprehensive type definitions:

import type {
  AddressData,
  AddressInputProps,
  PhoneData,
  PhoneInputProps,
  ValidationResult,
  FieldErrors
} from '@akson/cortex-ui-library'

// Address data structure
const address: AddressData = {
  streetLine1: '123 Main Street',
  streetLine2: 'Apt 4B',
  city: 'Zurich',
  state: 'ZH',
  postalCode: '8001',
  country: 'Switzerland',
  fullFormattedAddress: '123 Main Street, Apt 4B, 8001 Zurich, Switzerland',
  placeId: 'ChIJ...',
  coordinates: { lat: 47.3769, lng: 8.5417 }
}

// Phone data structure
const phoneData: PhoneData = {
  countryCode: '+41',
  nationalNumber: '761234567',
  formattedNumber: '[phone]',
  isValid: true
}

Supported Countries

Phone Numbers

• Switzerland (CH) - +41
• United States (US) - +1
• Canada (CA) - +1
• United Kingdom (GB) - +44
• Germany (DE) - +49
• France (FR) - +33
• Italy (IT) - +39
• Spain (ES) - +34
• Austria (AT) - +43
• Belgium (BE) - +32
• Netherlands (NL) - +31

Address Autocomplete

Supports Google Maps Places API for all countries with enhanced support for European countries.

Testing

The library includes comprehensive test utilities and mocks:

// Jest setup is included
import '@testing-library/jest-dom'

// Google Maps mocks are provided
// No additional setup needed for testing

Run tests in your project:

npm test
# or with coverage
npm run test:coverage

Examples

Complete Form Example

import React, { useState } from 'react'
import { AddressInput, PhoneInput, validateAddress } from '@akson/cortex-ui-library'

function ContactForm() {
  const [formData, setFormData] = useState({
    address: {},
    phone: ''
  })
  const [errors, setErrors] = useState({})

  const handleSubmit = (e) => {
    e.preventDefault()

    // Validate address
    const addressErrors = validateAddress(formData.address, true)

    if (Object.keys(addressErrors).length > 0) {
      setErrors({ address: addressErrors })
      return
    }

    // Submit form
    console.log('Form data:', formData)
  }

  return (
    <form onSubmit={handleSubmit} className="space-y-6">
      <AddressInput
        address={formData.address}
        onChange={(address) => setFormData(prev => ({ ...prev, address }))}
        errors={errors.address}
        required
        label="Your Address"
        googleMapsApiKey={process.env.GOOGLE_MAPS_API_KEY}
      />

      <PhoneInput
        value={formData.phone}
        onChange={(phone) => setFormData(prev => ({ ...prev, phone }))}
        required
        label="Phone Number"
        autoFormat
        showValidationIcon
      />

      <button type="submit">Submit</button>
    </form>
  )
}

Custom Styling Example

import { AddressInput, cn } from '@akson/cortex-ui-library'

function StyledAddressInput() {
  return (
    <AddressInput
      // ... props
      className={cn(
        // Custom card styling
        'shadow-lg border-2 border-blue-200',
        // Hover effects
        'hover:border-blue-400 transition-colors'
      )}
    />
  )
}

API Reference

AddressData Type

interface AddressData {
  streetLine1: string
  streetLine2?: string
  city: string
  state: string
  postalCode: string
  country: string
  fullFormattedAddress?: string
  placeId?: string
  coordinates?: { lat: number; lng: number }
}

PhoneData Type

interface PhoneData {
  countryCode: string
  nationalNumber: string
  formattedNumber: string
  isValid: boolean
}

ValidationResult Type

interface ValidationResult {
  isValid: boolean
  error?: string
}

Contributing

We welcome contributions! Please see our contributing guidelines and feel free to submit issues and pull requests.

License

MIT License - see LICENSE file for details.