@birhaus/loading

Loading states and skeleton components for the BIRHAUS design system. Built for progressive disclosure with Spanish-first internationalization and accessibility.

Features

• 🔄 Skeleton Loading: Realistic content placeholders with smooth animations
• ⏳ Progress Indicators: Progress bars, spinners, and overlays
• 🌍 Spanish-First: All components support Spanish-primary, English-fallback labels
• ♿ Accessibility: Full ARIA support with screen reader announcements
• 🎨 BIRHAUS Compliant: Follows all 7 BIRHAUS design principles
• ⚡ Performance: GPU-accelerated animations and optimized rendering
• 🎯 Progressive Disclosure: Show information at the right time

Installation

npm install @birhaus/loading

Quick Start

import { 
  BirhausSkeleton,
  BirhausSpinner,
  BirhausLoadingOverlay,
  useLoadingState 
} from '@birhaus/loading'

function LoadingExample() {
  const { isLoading, startLoading, setSuccess } = useLoadingState({
    timeout: 10000,
    retryCount: 3
  })

  return (
    <BirhausLoadingOverlay 
      isLoading={isLoading}
      messageEs="Cargando datos..."
      messageEn="Loading data..."
    >
      <div className="space-y-4">
        {isLoading ? (
          <>
            <BirhausSkeleton height={24} width="75%" />
            <BirhausSkeleton lines={3} />
            <BirhausSkeleton height={40} width={120} />
          </>
        ) : (
          <div>
            <h1>Contenido Cargado</h1>
            <p>El contenido se ha cargado exitosamente.</p>
            <button onClick={startLoading}>Recargar</button>
          </div>
        )}
      </div>
    </BirhausLoadingOverlay>
  )
}

Components

Skeleton Components

BirhausSkeleton

Basic skeleton element with customizable dimensions:

import { BirhausSkeleton } from '@birhaus/loading'

<BirhausSkeleton width={200} height={20} />
<BirhausSkeleton lines={3} /> // Multiple lines
<BirhausSkeleton circle width={40} height={40} /> // Avatar

BirhausSkeletonText

Text-specific skeleton with realistic proportions:

import { BirhausSkeletonText } from '@birhaus/loading'

<BirhausSkeletonText lines={3} randomWidth />
<BirhausSkeletonText lines={1} /> // Single line

BirhausSkeletonCard

Complete card layout skeleton:

import { BirhausSkeletonCard } from '@birhaus/loading'

<BirhausSkeletonCard 
  showImage
  showTitle
  showDescription
  showActions
/>

Loading Indicators

BirhausSpinner

Animated loading spinner with multiple sizes:

import { BirhausSpinner } from '@birhaus/loading'

<BirhausSpinner 
  size="lg"
  color="primary"
  labelEs="Cargando..."
  labelEn="Loading..."
  showLabel
/>

BirhausLoadingOverlay

Full-screen or container loading overlay:

import { BirhausLoadingOverlay } from '@birhaus/loading'

<BirhausLoadingOverlay
  isLoading={isLoading}
  messageEs="Procesando solicitud..."
  messageEn="Processing request..."
  blur
  opacity={0.8}
>
  <YourContent />
</BirhausLoadingOverlay>

BirhausProgressLoader

Progress bar with percentage and time estimation:

import { BirhausProgressLoader } from '@birhaus/loading'

<BirhausProgressLoader
  progress={65}
  messageEs="Subiendo archivo..."
  messageEn="Uploading file..."
  showPercentage
  showEstimatedTime
  estimatedSeconds={120}
  color="primary"
/>

Hooks

useLoadingState

Comprehensive loading state management with timeout and retry logic:

import { useLoadingState } from '@birhaus/loading'

function DataComponent() {
  const {
    isLoading,
    isSuccess,
    isError,
    error,
    retryCount,
    startLoading,
    setSuccess,
    setError,
    retry,
    reset
  } = useLoadingState({
    timeout: 30000,
    retryCount: 3,
    retryDelay: 1000,
    onStateChange: (state) => console.log('State changed:', state),
    onTimeout: () => console.log('Operation timed out'),
    onError: (error) => console.log('Error:', error),
    onRetry: (attempt) => console.log(`Retry attempt: ${attempt}`)
  })

  const fetchData = async () => {
    startLoading()
    try {
      const data = await api.getData()
      setSuccess()
    } catch (err) {
      setError(err)
    }
  }

  return (
    <div>
      {isLoading && <BirhausSpinner labelEs="Cargando datos..." />}
      {isError && (
        <div>
          <p>Error: {error?.message}</p>
          <button onClick={retry}>
            Reintentar ({retryCount}/{3})
          </button>
        </div>
      )}
      {isSuccess && <p>Datos cargados exitosamente</p>}
    </div>
  )
}

Presets and Utilities

Skeleton Presets

Pre-configured skeleton layouts for common UI elements:

import { getSkeletonPreset } from '@birhaus/loading'

const textPreset = getSkeletonPreset('text')
const cardPreset = getSkeletonPreset('card')
const avatarPreset = getSkeletonPreset('avatar')

// Available presets:
// 'text', 'paragraph', 'title', 'button', 'card', 
// 'avatar', 'table-row', 'list-item', 'form-field', 'image'

Spinner Presets

Contextual spinner configurations:

import { getSpinnerPreset } from '@birhaus/loading'

const buttonSpinner = getSpinnerPreset('button-md')
const pageSpinner = getSpinnerPreset('page-center')
const formSpinner = getSpinnerPreset('form-submit')

// Available presets:
// 'button-sm', 'button-md', 'button-lg', 'page-center',
// 'form-submit', 'data-fetch', 'search-results',
// 'file-upload', 'file-download', 'auth-login', 'auth-logout'

Loading Messages

Spanish-first loading messages for different contexts:

import { getLoadingMessage } from '@birhaus/loading'

const message = getLoadingMessage('submitting', 'es') // "Enviando formulario..."
const messageEn = getLoadingMessage('submitting', 'en') // "Submitting form..."

// Available contexts:
// 'general', 'fetching', 'saving', 'updating', 'deleting',
// 'submitting', 'validating', 'uploading', 'downloading',
// 'processing', 'signingIn', 'signingOut', 'verifying',
// 'searching', 'navigating', 'connecting', 'synchronizing',
// 'retrying', 'recovering'

Custom Presets

Create your own loading presets:

import { createLoadingPreset } from '@birhaus/loading'

const myCustomPreset = createLoadingPreset('custom-upload', {
  skeleton: { height: 100, lines: 2 },
  spinner: { 
    size: 'lg', 
    color: 'primary',
    labelEs: 'Subiendo archivo personalizado...',
    labelEn: 'Uploading custom file...'
  },
  loadingState: { 
    timeout: 60000, 
    retryCount: 2 
  },
  messages: {
    es: 'Procesando archivo personalizado...',
    en: 'Processing custom file...'
  }
})

BIRHAUS Principles

This package enforces all 7 BIRHAUS design principles:

1. Cognitive Load Reduction: Clear visual hierarchy in loading states
2. Miller's Law: Limited information during loading phases
3. Progressive Disclosure: Information revealed at appropriate times
4. Miller's Law in Forms: Loading states don't overwhelm users
5. Undo over Confirm: Loading states support cancellation where possible
6. Accessibility = Dignity: Full WCAG AA+ compliance with ARIA attributes
7. Spanish-First: All text content requires Spanish labels first

Performance

• GPU-accelerated CSS animations
• Optimized rendering with transform properties
• Memory leak prevention with proper cleanup
• Efficient skeleton rendering with minimal DOM impact
• Performance monitoring built into loading state hooks

Accessibility

• Full ARIA support with role="status" and aria-live="polite"
• Screen reader announcements for state changes
• Keyboard navigation support
• High contrast support
• Focus management during loading states

TypeScript Support

Comprehensive TypeScript definitions:

import type {
  LoadingState,
  BirhausSpinnerProps,
  LoadingStateReturn,
  SkeletonPreset
} from '@birhaus/loading'

License

MIT License - see LICENSE file for details.