@vireocodedev/ui/tanstack-query

export type UseVireoMutationOptions<TData = unknown, TError = Error, TVariables = void, TContext = unknown, TErrorDetails = unknown> = Omit<UseMutationOptions<TData, TError, TVariables, TContext>, "mutationFn" | "onError" | "onSuccess"> & {
    mutationFn: NonNullable<UseMutationOptions<TData, TError, TVariables, TContext>["mutationFn"]>;
    successMessage?: VireoMutationMessage<TData>;
    errorMessage?: VireoMutationMessage<TError>;
    errorDetails?: VireoMutationErrorDetails<TError, TErrorDetails>;
    onSuccess?: UseMutationOptions<TData, TError, TVariables, TContext>["onSuccess"];
    onError?: UseMutationOptions<TData, TError, TVariables, TContext>["onError"];
};

export type VireoMutationErrorDetails<TError, TDetails> = {
    /** Validates the application-selected error payload before it is rendered. */
    schema: z.ZodType<TDetails>;
    /** Selects the unknown payload validated by `schema`. Defaults to an Axios-style `response.data`, then the error. */
    select?: (error: TError) => unknown;
    /** @default 'Show error details' */
    label?: string;
    /** @default 'Error details' */
    title?: React.ReactNode;
    /** @default 'Close' */
    closeLabel?: string;
    /** @default 'Copy JSON to clipboard' */
    copyLabel?: string;
    /** @default 'JSON copied' */
    copiedLabel?: string;
    /** @default 'Unable to copy JSON' */
    copyErrorLabel?: string;
};

export type VireoMutationMessage<TValue> = React.ReactNode | ((value: TValue) => React.ReactNode);

export type VireoPagedSearchQueryPolicy = {
    staleTime: number;
    refetchOnMount: boolean;
    refetchOnWindowFocus: boolean;
    refetchOnReconnect: boolean;
};

export type VireoPagedSearchRequestOptions = {
    signal?: AbortSignal;
};

Coordinates Suspense loading, descendant errors, and TanStack Query reset semantics in one local boundary.

/** Coordinates Suspense loading, descendant errors, and TanStack Query reset semantics in one local boundary. */
export declare const VireoQueryBoundary: React.ForwardRefExoticComponent<Omit<VireoQueryBoundaryProps, "ref"> & React.RefAttributes<HTMLDivElement>>;

export interface VireoQueryBoundaryActionsSlotPropsOverrides {
    [key: `data-${string}`]: VireoDataAttributeValue;
}

Valid keys for VireoQueryBoundary utility classes and theme style overrides.

/** Valid keys for VireoQueryBoundary utility classes and theme style overrides. */
export type VireoQueryBoundaryClassKey = keyof VireoQueryBoundaryClasses;

Utility classes available to VireoQueryBoundary.

/** Utility classes available to VireoQueryBoundary. */
export type VireoQueryBoundaryClasses = Record<VireoQueryBoundarySlotName | "loading" | "error" | "hasErrorDetails", string>;

export interface VireoQueryBoundaryErrorAlertSlotPropsOverrides {
    [key: `data-${string}`]: VireoDataAttributeValue;
}

export interface VireoQueryBoundaryErrorDetailsButtonSlotPropsOverrides {
    [key: `data-${string}`]: VireoDataAttributeValue;
}

export interface VireoQueryBoundaryErrorDetailsDialogSlotPropsOverrides {
    [key: `data-${string}`]: VireoDataAttributeValue;
}

Props VireoQueryBoundary inherits from its default root after excluding component-owned props.

/** Props VireoQueryBoundary inherits from its default root after excluding component-owned props. */
export type VireoQueryBoundaryInheritedProps = Omit<BoxProps<"div">, "children" | "component">;

export interface VireoQueryBoundaryLoadingIndicatorSlotPropsOverrides {
    [key: `data-${string}`]: VireoDataAttributeValue;
}

Props owned by {@link VireoQueryBoundary }.

/** Props owned by {@link VireoQueryBoundary}. */
export type VireoQueryBoundaryOwnProps = VireoQueryBoundarySlotsAndSlotProps & {
    children: React.ReactNode;
    /** Whether the default loading fallback announces prolonged loading. Disable for a boundary covered by an announcing ancestor. @default true */
    announceLoading?: boolean;
    loadingFallback?: React.ReactNode;
    errorFallback?: (context: VireoQueryErrorFallbackContext) => React.ReactNode;
    /** @default 'Loading' */
    loadingLabel?: string;
    /** Delay before the default loading indicator and announcement become visible. @default VIREO_LOADING_TOKENS.revealDelay */
    loadingRevealDelay?: number;
    /** @default 'Something went wrong' */
    errorTitle?: React.ReactNode;
    /** @default 'The requested content could not be loaded.' */
    errorMessage?: React.ReactNode;
    /** @default 'Retry' */
    retryLabel?: React.ReactNode;
    /** @default 'Show error details' */
    errorDetailsLabel?: string;
    /** @default 'Error details' */
    errorDetailsTitle?: React.ReactNode;
    /** @default 'Close error details' */
    closeErrorDetailsLabel?: string;
    /** @default 'Copy error details' */
    copyErrorDetailsLabel?: string;
    /** @default 'Error details copied' */
    copiedErrorDetailsLabel?: string;
    /** @default 'Unable to copy error details' */
    copyErrorDetailsErrorLabel?: string;
    selectErrorDetails?: (error: unknown) => unknown;
    /** @default true */
    retryable?: boolean | ((error: unknown) => boolean);
    resetKeys?: readonly unknown[];
    onError?: (error: unknown, info: VireoQueryErrorInfo) => void;
    onRetry?: (error: unknown) => void;
    /** Override or extend the utility classes applied to each slot and state. */
    classes?: Partial<VireoQueryBoundaryClasses>;
};

export type VireoQueryBoundaryOwnerState = {
    status: VireoQueryBoundaryStatus;
    hasErrorDetails: boolean;
    retryable: boolean;
};

Props accepted by {@link VireoQueryBoundary }.

/** Props accepted by {@link VireoQueryBoundary}. */
export type VireoQueryBoundaryProps = VireoQueryBoundaryOwnProps & VireoQueryBoundaryInheritedProps;

export interface VireoQueryBoundaryRetryButtonSlotPropsOverrides {
    [key: `data-${string}`]: VireoDataAttributeValue;
}

export interface VireoQueryBoundaryRootSlotPropsOverrides {
    [key: `data-${string}`]: VireoDataAttributeValue;
}

Replaceable semantic regions exposed by {@link VireoQueryBoundary }.

/** Replaceable semantic regions exposed by {@link VireoQueryBoundary}. */
export type VireoQueryBoundarySlots = {
    [TSlotName in VireoQueryBoundarySlotName]: React.ElementType;
};

Slot props exposed by {@link VireoQueryBoundary }.

/** Slot props exposed by {@link VireoQueryBoundary}. */
export type VireoQueryBoundarySlotsAndSlotProps = CreateSlotsAndSlotProps<VireoQueryBoundarySlots, {
    /** @default Box */
    root: SlotProps<typeof Box, VireoQueryBoundaryRootSlotPropsOverrides, VireoQueryBoundaryOwnerState>;
    /** @default CircularProgress */
    loadingIndicator: SlotProps<typeof CircularProgress, VireoQueryBoundaryLoadingIndicatorSlotPropsOverrides, VireoQueryBoundaryOwnerState>;
    /** @default Alert */
    errorAlert: SlotProps<typeof Alert, VireoQueryBoundaryErrorAlertSlotPropsOverrides, VireoQueryBoundaryOwnerState>;
    /** @default Stack */
    actions: SlotProps<typeof Stack, VireoQueryBoundaryActionsSlotPropsOverrides, VireoQueryBoundaryOwnerState>;
    /** @default Button */
    retryButton: SlotProps<typeof Button, VireoQueryBoundaryRetryButtonSlotPropsOverrides, VireoQueryBoundaryOwnerState>;
    /** @default IconButton */
    errorDetailsButton: SlotProps<typeof IconButton, VireoQueryBoundaryErrorDetailsButtonSlotPropsOverrides, VireoQueryBoundaryOwnerState>;
    /** @default Dialog */
    errorDetailsDialog: SlotProps<typeof Dialog, VireoQueryBoundaryErrorDetailsDialogSlotPropsOverrides, VireoQueryBoundaryOwnerState>;
}>;

export type VireoQueryBoundaryStatus = "loading" | "error";

export type VireoQueryEngineQueries = ReturnType<typeof createVireoQueryEngineQueries>;

export type VireoQueryErrorFallbackContext = {
    error: unknown;
    retry: () => void;
    retryable: boolean;
};

export type VireoQueryErrorInfo = {
    componentStack: string | null;
};

export declare function createVireoPagedSearchQueries<TFilters, TResult extends PageableResponse<unknown>>(args: {
    queryKeyRoot: string;
    searchFn: (pagination: PageableParams, filters: TFilters, request?: VireoPagedSearchRequestOptions) => Promise<TResult>;
    policy: VireoPagedSearchQueryPolicy;
}): {
    search: (pagination: PageableParams, filters: TFilters) => VireoPagedSearchQueryOptions<TFilters, TResult>;
    searchInfinite: (pagination: PageableParams, filters: TFilters) => VireoPagedSearchInfiniteQueryOptions<TFilters, TResult>;
};

Creates React Query options for the framework-free QueryEngine API.

/** Creates React Query options for the framework-free QueryEngine API. */
export declare function createVireoQueryEngineQueries(api: QueryEngineApi): {
    listEntities: () => VireoQueryEngineQueryOptions<QueryEngineEntitySummary[], (typeof QueryEngineQueryKey.entities)[]>;
    listEntityDefinitions: (entityKeys: QueryEngineEntityKey[]) => VireoQueryEngineQueryOptions<Partial<Record<QueryEngineEntityKey, QueryEngineEntityDefinition>>, string[]>;
    describeEntity: (entityKey: QueryEngineEntityKey) => VireoQueryEngineQueryOptions<QueryEngineEntityDefinition, string[]>;
};

Returns the generated utility class name for a VireoQueryBoundary slot or state.

/** Returns the generated utility class name for a VireoQueryBoundary slot or state. */
export declare function getVireoQueryBoundaryUtilityClass(slot: string): string;

Extends TanStack Query mutations with Vireo notifications and schema-validated error details.

/** Extends TanStack Query mutations with Vireo notifications and schema-validated error details. */
export declare function useVireoMutation<TData = unknown, TError = Error, TVariables = void, TContext = unknown, TErrorDetails = unknown>({ mutationFn, successMessage, errorMessage, errorDetails, onSuccess, onError, ...options }: UseVireoMutationOptions<TData, TError, TVariables, TContext, TErrorDetails>): import("@tanstack/react-query").UseMutationResult<TData, TError, TVariables, TContext>;

Generated utility class names keyed by each public VireoQueryBoundary class key.

/** Generated utility class names keyed by each public VireoQueryBoundary class key. */
export declare const vireoQueryBoundaryClasses: VireoQueryBoundaryClasses;