Package Exports
- @akson/cortex-ui-library
Readme
@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-libraryComponents
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 objectonChange: Callback when address changeserrors: Field-level error messagesgoogleMapsApiKey: Optional Google Maps API key for autocompleterequired: Mark as required fieldlabel: Field label (default: "Address")description: Helper description textshowCoordinates: Display coordinates when availablevalidateOnChange: Validate fields as user typesdisabled: Disable all inputsclassName: 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 stringonChange: Callback when phone number changesonValidChange: Callback with validation status and parsed phone datadefaultCountry: Default country code (default: "CH")autoFormat: Automatically format phone numbershowValidationIcon: Show validation status iconsvalidateOnChange: Validate as user typesplaceholder: Input placeholderrequired: Mark as required fielddisabled: Disable input and country selector
FileUploadField Props:
uploadHook: Supabase upload hook (from @akson/cortex-supabase)batchUploadHook: Batch upload hook for multiple filesvalidationHook: Validation hook with custom rulesonUpload: Direct upload handler (alternative to hooks)config: Upload configuration objectvalue: Current files arrayonChange: Callback when files changeonUploadComplete: Callback when upload completesonUploadError: Callback when upload failsdisabled: Disable the upload areaclassName: Custom CSS classes
FileUpload Config Options:
accept: Allowed file types (e.g., ['image/*', 'application/pdf'])maxSize: Maximum file size in bytesmaxFiles: Maximum number of filesmultiple: Allow multiple file selectionvariant: 'default' | 'compact' | 'gallery' | 'minimal'showThumbnails: Display file thumbnailsdragDropEnabled: Enable drag and dropautoUpload: Automatically upload when files are addedvalidationPosition: '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 stringonChange: Callback when OTP changesonComplete: Callback when OTP reaches specified lengthlength: 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 valueslabel: Field label (default: "Verification Code")error: Error message to displayhelperText: Helper text to displayrequired: Mark as required fielddisabled: Disable the inputclassName: 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-autocompletefor 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('user@example.com') // Uses validator.js
// Phone validation with libphonenumber-js
const phoneData = parsePhoneNumber('+41761234567', 'CH')
const phoneValidation = validatePhoneNumber('+41761234567')
// Address validation
const addressErrors = validateAddress({
streetLine1: '123 Main St',
city: 'Zurich',
// ... other fields
}, true) // required = trueStyling
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, cardContentStylesTypeScript 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: '+41 76 123 45 67',
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 testingRun tests in your project:
npm test
# or with coverage
npm run test:coverageExamples
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.