Utility Components

/**
 * ThemeProvider component for Bootstrap theme configuration
 * @param prefixes - Custom CSS class prefixes for components
 * @param breakpoints - Responsive breakpoint configuration
 * @param minBreakpoint - Minimum breakpoint name
 * @param dir - Text direction for RTL support
 */
function ThemeProvider(props: ThemeProviderProps): JSX.Element;

interface ThemeProviderProps {
  /** Custom CSS class prefixes for components */
  prefixes?: Record<string, string>;
  /** Responsive breakpoint configuration */
  breakpoints?: string[];
  /** Minimum breakpoint name */
  minBreakpoint?: string;
  /** Text direction for RTL support */
  dir?: "ltr" | "rtl";
  /** Child components */
  children?: React.ReactNode;
}

import { ThemeProvider, Button } from "react-bootstrap";

// Custom component prefixes
<ThemeProvider prefixes={{ btn: 'my-btn', card: 'my-card' }}>
  <App />
</ThemeProvider>

// RTL support
<ThemeProvider dir="rtl">
  <App />
</ThemeProvider>

// Custom breakpoints
<ThemeProvider 
  breakpoints={['xs', 'sm', 'md', 'lg', 'xl']}
  minBreakpoint="xs"
>
  <App />
</ThemeProvider>

/**
 * SSRProvider component for server-side rendering support
 * @param children - Child components
 */
function SSRProvider(props: SSRProviderProps): JSX.Element;

interface SSRProviderProps {
  /** Child components */
  children?: React.ReactNode;
}

import { SSRProvider } from "react-bootstrap";

// Wrap your app for SSR compatibility
<SSRProvider>
  <App />
</SSRProvider>

/**
 * Spinner component for loading indicators
 * @param animation - Animation type
 * @param variant - Color variant
 * @param size - Size variant
 * @param role - ARIA role
 */
function Spinner(props: SpinnerProps): JSX.Element;

interface SpinnerProps extends React.HTMLAttributes<HTMLElement> {
  /** Animation type */
  animation?: "border" | "grow";
  /** Color variant */
  variant?: "primary" | "secondary" | "success" | "danger" | "warning" | "info" | "light" | "dark";
  /** Size variant */
  size?: "sm";
  /** ARIA role for accessibility */
  role?: string;
  /** Component used for the root node */
  as?: React.ElementType;
  /** Bootstrap CSS class prefix */
  bsPrefix?: string;
}

import { Spinner, Button } from "react-bootstrap";

// Basic border spinner
<Spinner animation="border" role="status">
  <span className="visually-hidden">Loading...</span>
</Spinner>

// Colored grow spinner
<Spinner animation="grow" variant="primary" />

// Small spinner in button
<Button variant="primary" disabled>
  <Spinner animation="border" size="sm" role="status" />
  <span className="visually-hidden">Loading...</span>
</Button>

/**
 * Placeholder component for loading placeholders
 * @param animation - Animation type
 * @param bg - Background color variant
 * @param size - Size variant
 * @param xs,sm,md,lg,xl,xxl - Responsive width
 */
function Placeholder(props: PlaceholderProps): JSX.Element;

interface PlaceholderProps extends React.HTMLAttributes<HTMLElement> {
  /** Animation type */
  animation?: "glow" | "wave";
  /** Background color variant */
  bg?: "primary" | "secondary" | "success" | "danger" | "warning" | "info" | "light" | "dark";
  /** Size variant */
  size?: "xs" | "sm" | "lg";
  /** Width at xs breakpoint */
  xs?: number;
  /** Width at sm breakpoint */
  sm?: number;
  /** Width at md breakpoint */
  md?: number;
  /** Width at lg breakpoint */
  lg?: number;
  /** Width at xl breakpoint */
  xl?: number;
  /** Width at xxl breakpoint */
  xxl?: number;
  /** Component used for the root node */
  as?: React.ElementType;
  /** Bootstrap CSS class prefix */
  bsPrefix?: string;
}

/**
 * PlaceholderButton component for button placeholders
 * @param variant - Button variant style
 * @param size - Button size
 * @param xs,sm,md,lg,xl,xxl - Responsive width
 */
function PlaceholderButton(props: PlaceholderButtonProps): JSX.Element;

interface PlaceholderButtonProps extends React.HTMLAttributes<HTMLElement> {
  /** Button variant style */
  variant?: "primary" | "secondary" | "success" | "danger" | "warning" | "info" | "light" | "dark" | "outline-primary" | "outline-secondary" | "outline-success" | "outline-danger" | "outline-warning" | "outline-info" | "outline-light" | "outline-dark";
  /** Button size */
  size?: "sm" | "lg";
  /** Width at xs breakpoint */
  xs?: number;
  /** Width at sm breakpoint */
  sm?: number;
  /** Width at md breakpoint */
  md?: number;
  /** Width at lg breakpoint */
  lg?: number;
  /** Width at xl breakpoint */
  xl?: number;
  /** Width at xxl breakpoint */
  xxl?: number;
  /** Component used for the root node */
  as?: React.ElementType;
  /** Bootstrap CSS class prefix */
  bsPrefix?: string;
}

import { Placeholder, PlaceholderButton, Card } from "react-bootstrap";

// Basic placeholders
<Placeholder xs={6} />
<Placeholder className="w-75" />

// Animated placeholders
<Placeholder animation="glow">
  <Placeholder xs={12} />
</Placeholder>

<Placeholder animation="wave">
  <Placeholder xs={12} />
</Placeholder>

// Colored placeholders
<Placeholder bg="primary" xs={4} />
<Placeholder bg="secondary" xs={6} />

// Different sizes
<Placeholder size="lg" xs={12} />
<Placeholder size="sm" xs={12} />
<Placeholder size="xs" xs={12} />

// Placeholder buttons
<PlaceholderButton variant="primary" xs={6} />
<PlaceholderButton variant="outline-secondary" xs={4} />

// Card with placeholders
<Card style={{ width: '18rem' }}>
  <Card.Img variant="top" src="..." />
  <Card.Body>
    <Placeholder animation="glow">
      <Placeholder xs={6} />
      <Placeholder className="w-75" />
      <Placeholder className="w-50" />
    </Placeholder>
    <PlaceholderButton variant="primary" xs={6} />
  </Card.Body>
</Card>

/**
 * Ratio component for aspect ratio containers
 * @param aspectRatio - Aspect ratio preset or custom ratio
 */
function Ratio(props: RatioProps): JSX.Element;

interface RatioProps extends React.HTMLAttributes<HTMLDivElement> {
  /** Aspect ratio preset or custom ratio */
  aspectRatio?: "1x1" | "4x3" | "16x9" | "21x9" | string;
  /** Component used for the root node */
  as?: React.ElementType;
  /** Bootstrap CSS class prefix */
  bsPrefix?: string;
}

import { Ratio } from "react-bootstrap";

// Standard video aspect ratio
<Ratio aspectRatio="16x9">
  <iframe src="https://www.youtube.com/embed/..." title="YouTube video"></iframe>
</Ratio>

// Square aspect ratio
<Ratio aspectRatio="1x1">
  <div>Square content</div>
</Ratio>

// Custom aspect ratio
<Ratio aspectRatio="2x1">
  <div>Custom ratio content</div>
</Ratio>

/**
 * CloseButton component for close buttons
 * @param variant - Visual variant
 * @param disabled - Disabled state
 * @param onClick - Click handler
 */
function CloseButton(props: CloseButtonProps): JSX.Element;

interface CloseButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  /** Visual variant */
  variant?: "white";
  /** Disabled state */
  disabled?: boolean;
  /** Click handler */
  onClick?: (event: React.MouseEvent<HTMLButtonElement>) => void;
  /** Bootstrap CSS class prefix */
  bsPrefix?: string;
}

import { CloseButton, Alert } from "react-bootstrap";

// Basic close button
<CloseButton onClick={() => setShow(false)} />

// White variant for dark backgrounds
<CloseButton variant="white" onClick={() => setShow(false)} />

// Disabled close button
<CloseButton disabled />

// In alert context
<Alert variant="warning" dismissible>
  <Alert.Heading>Oh snap! You got an error!</Alert.Heading>
  <p>Change this and that and try again.</p>
</Alert>

/**
 * Collapse component for collapsible content
 * @param in - Show/hide state
 * @param mountOnEnter - Mount on enter transition
 * @param unmountOnExit - Unmount on exit transition
 * @param appear - Appear transition on mount
 * @param timeout - Transition timeout
 * @param dimension - Collapse dimension
 * @param getDimensionValue - Custom dimension calculation
 * @param onEnter - Enter transition callback
 * @param onEntering - Entering transition callback
 * @param onEntered - Entered transition callback
 * @param onExit - Exit transition callback
 * @param onExiting - Exiting transition callback
 * @param onExited - Exited transition callback
 */
function Collapse(props: CollapseProps): JSX.Element;

interface CollapseProps extends React.HTMLAttributes<HTMLElement> {
  /** Show/hide state */
  in?: boolean;
  /** Mount component on enter transition */
  mountOnEnter?: boolean;
  /** Unmount component on exit transition */
  unmountOnExit?: boolean;
  /** Appear transition on mount */
  appear?: boolean;
  /** Transition timeout in milliseconds */
  timeout?: number;
  /** Collapse dimension ('height' | 'width' | function) */
  dimension?: "height" | "width" | (() => "height" | "width");
  /** Custom dimension value calculation */
  getDimensionValue?: (dimension: string, element: HTMLElement) => number;
  /** Enter transition start callback */
  onEnter?: (element: HTMLElement) => void;
  /** Entering transition callback */
  onEntering?: (element: HTMLElement) => void;
  /** Entered transition end callback */
  onEntered?: (element: HTMLElement) => void;
  /** Exit transition start callback */
  onExit?: (element: HTMLElement) => void;
  /** Exiting transition callback */
  onExiting?: (element: HTMLElement) => void;
  /** Exited transition end callback */
  onExited?: (element: HTMLElement) => void;
  /** Component used for the root node */
  as?: React.ElementType;
  /** Bootstrap CSS class prefix */
  bsPrefix?: string;
}

/**
 * Fade component for fade transitions
 * @param in - Show/hide state
 * @param mountOnEnter - Mount on enter transition
 * @param unmountOnExit - Unmount on exit transition
 * @param appear - Appear transition on mount
 * @param timeout - Transition timeout
 * @param onEnter - Enter callback
 * @param onEntering - Entering callback
 * @param onEntered - Entered callback
 * @param onExit - Exit callback
 * @param onExiting - Exiting callback
 * @param onExited - Exited callback
 */
function Fade(props: FadeProps): JSX.Element;

interface FadeProps extends React.HTMLAttributes<HTMLElement> {
  /** Show/hide state */
  in?: boolean;
  /** Mount component on enter transition */
  mountOnEnter?: boolean;
  /** Unmount component on exit transition */
  unmountOnExit?: boolean;
  /** Appear transition on mount */
  appear?: boolean;
  /** Transition timeout in milliseconds */
  timeout?: number;
  /** Enter transition start callback */
  onEnter?: (element: HTMLElement, isAppearing: boolean) => void;
  /** Entering transition callback */
  onEntering?: (element: HTMLElement, isAppearing: boolean) => void;
  /** Entered transition end callback */
  onEntered?: (element: HTMLElement, isAppearing: boolean) => void;
  /** Exit transition start callback */
  onExit?: (element: HTMLElement) => void;
  /** Exiting transition callback */
  onExiting?: (element: HTMLElement) => void;
  /** Exited transition end callback */
  onExited?: (element: HTMLElement) => void;
  /** Component used for the root node */
  as?: React.ElementType;
  /** Bootstrap CSS class prefix */
  bsPrefix?: string;
}

/**
 * Image component for responsive images
 * @param fluid - Responsive scaling
 * @param rounded - Rounded corners
 * @param roundedCircle - Circular shape
 * @param thumbnail - Thumbnail styling
 */
function Image(props: ImageProps): JSX.Element;

interface ImageProps extends React.ImgHTMLAttributes<HTMLImageElement> {
  /** Responsive fluid scaling */
  fluid?: boolean;
  /** Rounded corners */
  rounded?: boolean;
  /** Circular shape */
  roundedCircle?: boolean;
  /** Thumbnail styling with border */
  thumbnail?: boolean;
  /** Bootstrap CSS class prefix */
  bsPrefix?: string;
}

/**
 * Figure component for figures with captions
 */
function Figure(props: FigureProps): JSX.Element;

interface FigureProps extends React.HTMLAttributes<HTMLElement> {
  /** Component used for the root node */
  as?: React.ElementType;
  /** Bootstrap CSS class prefix */
  bsPrefix?: string;
}

/**
 * FigureCaption component for figure captions
 */
function FigureCaption(props: FigureCaptionProps): JSX.Element;

interface FigureCaptionProps extends React.HTMLAttributes<HTMLElement> {
  /** Component used for the root node */
  as?: React.ElementType;
  /** Bootstrap CSS class prefix */
  bsPrefix?: string;
}

/**
 * FigureImage component for figure images
 * @param fluid - Responsive scaling
 * @param rounded - Rounded corners
 * @param thumbnail - Thumbnail styling
 */
function FigureImage(props: FigureImageProps): JSX.Element;

interface FigureImageProps extends ImageProps {
  // Inherits all ImageProps
}

/**
 * Anchor component for styled links
 */
function Anchor(props: AnchorProps): JSX.Element;

interface AnchorProps extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
  /** Component used for the root node */
  as?: React.ElementType;
  /** Bootstrap CSS class prefix */
  bsPrefix?: string;
}

// Compound component structure
Figure.Image = FigureImage;
Figure.Caption = FigureCaption;

import { Figure } from "react-bootstrap";

// Figure with image and caption
<Figure>
  <Figure.Image
    width={171}
    height={180}
    alt="171x180"
    src="holder.js/171x180"
  />
  <Figure.Caption>
    Nulla vitae elit libero, a pharetra augue mollis interdum.
  </Figure.Caption>
</Figure>

// Fluid responsive figure
<Figure>
  <Figure.Image
    fluid
    alt="Responsive image"
    src="image.jpg"
  />
  <Figure.Caption>
    A responsive figure with fluid image.
  </Figure.Caption>
</Figure>