@stanfordspezi/spezi-web-design-system/dist/src/components/Async/Async.d.ts

Stanford Biodesign Digital Health Spezi Web Design System

import { ReactNode } from 'react';
import { ErrorStateProps } from '../ErrorState';
import { StateContainerProps } from '../StateContainer';
import { EmptyStateProps } from '../EmptyState';
export type FullEmptyProps = {
    show: boolean;
} & EmptyStateProps;
export type FullErrorProps = {
    show: boolean;
} & ErrorStateProps;
export interface AsyncProps extends Pick<StateContainerProps, "grow" | "padding"> {
    /**
     * This is the main content that will be shown when there is no error,
     * loading, or empty state.
     */
    children: ReactNode;
    /**
     * Pluralized name of the represented entity.
     * Used in error and empty state messages.
     * @example "users"
     */
    entityName?: string;
    /**
     * Controls the display of the error state.
     * Can be a boolean to simply show/hide the error state
     * or an object with additional error state configuration.
     * When true or an object with show: true, the error state will be displayed.
     *
     * @example
     * ```tsx
     * // Simple boolean usage
     * <Async error={true} >
     * ```
     *
     * @example
     * ```tsx
     * // Object with additional configuration
     * <Async
     *   error={{
     *     show: true,
     *     children: "Custom error message ",
     *   }}
     * />
     * />
     * ```
     */
    error?: boolean | FullErrorProps;
    /**
     * Controls the display of the empty state.
     * Can be a boolean to simply show/hide the empty state
     * or an object with additional empty state configuration.
     * When true or an object with show: true, the empty state will be displayed.
     *
     * @example
     * ```tsx
     * // Simple boolean usage
     * <Async empty={true} />
     * ```
     *
     * @example
     * ```tsx
     * // Object with additional configuration
     * <Async
     *   empty={{
     *     show: true,
     *     children: "No Items Found",
     *   }}
     * />
     * ```
     */
    empty?: boolean | FullEmptyProps;
    /**
     * Controls the display of the loading state.
     * When true, a loading spinner will be displayed.
     * Useful for indicating data fetching or processing states.
     */
    loading?: boolean;
    /**
     * Can be used to wrap state with a custom container.
     * Useful for customizing the layout or styling of error,
     * loading, or empty states.
     *
     * Uses a render prop pattern to conditionally wrap state components only when they are present.
     *
     * @param specialState - The state component to wrap (ErrorState, Spinner, or EmptyState)
     */
    renderState?: (specialState: ReactNode) => ReactNode;
    className?: string;
}
/**
 * Generic container for representing async states.
 * Handles common data states: empty, error and loading.
 * Provides a consistent way to handle loading, error, and empty states
 * across the application.
 *
 * @example
 * ```tsx
 * // Basic usage with loading state
 * <Async loading={isLoading}>
 *   <div>Content</div>
 * </Async>
 * ```
 *
 * @example
 * ```tsx
 * // Usage with queriesToAsyncProps utility that parses query results
 * <Async
 *   {...queriesToAsyncProps([notificationQuery])}
 *   empty={notifications.length === 0}
 *   entityName="unread notifications"
 * >
 *   <div>
 *     {notifications.map((notification) => (
 *       <Notification key={notification.id} notification={notification} />
 *     ))}
 *   </div>
 * </Async>
 * ```
 *
 * @example
 * ```tsx
 * // Custom state rendering
 * <Async
 *   loading={isLoading}
 *   renderState={(state) => (
 *     <div className="custom-container">
 *       {state}
 *     </div>
 *   )}
 * >
 *   <div>Content</div>
 * </Async>
 * ```
 */
export declare const Async: ({ entityName, empty: emptyProp, error: errorProp, loading, renderState, children, grow, className, padding, }: AsyncProps) => string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import('react').ReactPortal | import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react").JSX.Element | null | undefined;