JSPM

@akson/cortex-ui-library

1.5.2
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 10
  • Score
    100M100P100Q47341F
  • License MIT

UI components library with built-in validation using industry-standard libraries

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-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('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 = 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: '+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 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.