Package Exports

@birhaus/loading

Readme

@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:

Cognitive Load Reduction: Clear visual hierarchy in loading states
Miller's Law: Limited information during loading phases
Progressive Disclosure: Information revealed at appropriate times
Miller's Law in Forms: Loading states don't overwhelm users
Undo over Confirm: Loading states support cancellation where possible
Accessibility = Dignity: Full WCAG AA+ compliance with ARIA attributes
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.