Loading & Progress Components

/**
 * General loading spinner component
 */
interface LoadingProps extends HTMLAttributes<HTMLDivElement> {
  /** Controls spinner animation - defaults to true */
  active?: boolean;
  /** CSS class name */
  className?: string;
  /** Accessible description of loading state - defaults to "loading" */
  description?: string;
  /** Small variant for inline use */
  small?: boolean;
  /** Render with overlay backdrop - defaults to true */
  withOverlay?: boolean;
}

import { Loading } from "@carbon/react";

// Full-page loading with overlay
<Loading description="Loading data..." />

// Small inline loading
<Loading small withOverlay={false} description="Saving..." />

// Inactive loading (stopped)
<Loading active={false} />

/**
 * Inline loading with status states
 */
interface InlineLoadingProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'> {
  /** CSS class name */
  className?: string;
  /** Descriptive text displayed alongside the loading state */
  description?: React.ReactNode;
  /** Accessible description for the loading icon */
  iconDescription?: string;
  /** Callback invoked when status becomes 'finished' after successDelay */
  onSuccess?: () => void;
  /** Current loading status - defaults to 'active' */
  status?: 'inactive' | 'active' | 'finished' | 'error';
  /** Delay in milliseconds before onSuccess is called - defaults to 1500 */
  successDelay?: number;
}

/**
 * Available status values
 */
type InlineLoadingStatus = 'inactive' | 'active' | 'finished' | 'error';

import { InlineLoading } from "@carbon/react";

// Basic form loading
<InlineLoading status="active" description="Saving changes..." />

// Success state with callback
<InlineLoading 
  status="finished" 
  description="Saved successfully"
  onSuccess={() => console.log('Save completed')}
/>

// Error state
<InlineLoading status="error" description="Failed to save" />

// Inactive state
<InlineLoading status="inactive" description="Ready to save" />

/**
 * Progress indicator for multi-step workflows
 */
interface ProgressIndicatorProps extends Omit<React.HTMLAttributes<HTMLUListElement>, 'onChange'> {
  /** ProgressStep components */
  children?: React.ReactNode;
  /** CSS class name */
  className?: string;
  /** Current active step index - defaults to 0 */
  currentIndex?: number;
  /** Callback when step is clicked - receives step index */
  onChange?: (stepIndex: number) => void;
  /** Equal spacing for all steps */
  spaceEqually?: boolean;
  /** Vertical layout orientation */
  vertical?: boolean;
}

/**
 * Individual progress step configuration
 */
interface ProgressStepProps {
  /** CSS class name */
  className?: string;
  /** Step is completed */
  complete?: boolean;
  /** Step is currently active */
  current?: boolean;
  /** Step description for accessibility */
  description?: string;
  /** Step is disabled */
  disabled?: boolean;
  /** Step index (set automatically) */
  index?: number;
  /** Step has error state */
  invalid?: boolean;
  /** Step display label - required */
  label: string;
  /** Click handler for step navigation */
  onClick?: (event: React.KeyboardEvent<HTMLButtonElement> | React.MouseEvent<HTMLButtonElement>) => void;
  /** Optional secondary label */
  secondaryLabel?: string;
  /** Translation function for internationalization */
  translateWithId?: (messageId: string) => string;
}

/**
 * Progress indicator skeleton for loading states
 */
interface ProgressIndicatorSkeletonProps {
  /** CSS class name */
  className?: string;
  /** Vertical layout orientation */
  vertical?: boolean;
}

import { ProgressIndicator, ProgressStep } from "@carbon/react";

// Basic multi-step workflow
<ProgressIndicator currentIndex={1} onChange={(index) => setStep(index)}>
  <ProgressStep label="Account Setup" description="Create your account" />
  <ProgressStep label="Profile Info" description="Add personal details" />
  <ProgressStep label="Verification" description="Verify your email" />
  <ProgressStep label="Complete" description="Setup finished" />
</ProgressIndicator>

// Vertical layout with secondary labels
<ProgressIndicator vertical currentIndex={0}>
  <ProgressStep 
    label="Planning" 
    secondaryLabel="Define requirements"
    complete={false}
  />
  <ProgressStep 
    label="Development" 
    secondaryLabel="Build features"
    disabled
  />
</ProgressIndicator>

// Loading state
<ProgressIndicatorSkeleton />

/**
 * Linear progress bar for task completion
 */
interface ProgressBarProps {
  /** CSS class name */
  className?: string;
  /** Descriptive text for current progress */
  helperText?: string;
  /** Visually hide the label (keeps it accessible) */
  hideLabel?: boolean;
  /** Progress bar label - required */
  label: string;
  /** Maximum value - defaults to 100 */
  max?: number;
  /** Visual size variant - defaults to 'big' */
  size?: 'small' | 'big';
  /** Progress status - defaults to 'active' */
  status?: 'active' | 'finished' | 'error';
  /** Layout alignment variant - defaults to 'default' */
  type?: 'default' | 'inline' | 'indented';
  /** Current progress value (0 to max) */
  value?: number;
}

import { ProgressBar } from "@carbon/react";

// File upload progress
<ProgressBar 
  label="Uploading document"
  value={45}
  max={100}
  helperText="45% complete"
/>

// Indeterminate progress (no value)
<ProgressBar 
  label="Processing data"
  helperText="Please wait..."
/>

// Finished state
<ProgressBar 
  label="Upload complete"
  status="finished"
  helperText="File uploaded successfully"
/>

// Error state
<ProgressBar 
  label="Upload failed"
  status="error"
  helperText="Please try again"
/>

// Small inline variant
<ProgressBar 
  size="small"
  type="inline"
  label="Saving"
  value={75}
/>

import { ProgressIndicatorSkeleton } from "@carbon/react";

// Basic skeleton
<ProgressIndicatorSkeleton />

// Vertical skeleton
<ProgressIndicatorSkeleton vertical />

import { 
  ButtonSkeleton,
  TextInputSkeleton,
  DropdownSkeleton,
  DataTableSkeleton 
} from "@carbon/react";

// Form skeleton
<>
  <TextInputSkeleton />
  <DropdownSkeleton />
  <ButtonSkeleton />
</>

// Table skeleton
<DataTableSkeleton 
  columnCount={4}
  rowCount={5}
  headers={['Name', 'Status', 'Date', 'Actions']}
/>