/**
 * File download utilities for BeatUI.
 *
 * Provides functions for downloading files from URLs, creating downloads from
 * in-memory content, and monitoring download progress with reactive signals.
 *
 * @module
 */
import { Signal } from '@tempots/dom';
/**
 * Represents an in-progress download with a known content length.
 */
export interface Progress {
    /** Discriminant for the `DownloadResult` union. */
    type: 'progress';
    /** Download progress as a fraction from 0 to 1. */
    value: number;
}
/**
 * Represents an in-progress download with an unknown content length.
 */
export interface Undetermined {
    /** Discriminant for the `DownloadResult` union. */
    type: 'undetermined';
}
/**
 * Represents a completed download with the resulting file.
 */
export interface Done {
    /** Discriminant for the `DownloadResult` union. */
    type: 'done';
    /** The downloaded file. */
    file: File;
}
/**
 * Represents a failed download with the error that occurred.
 */
export interface DownloadError {
    /** Discriminant for the `DownloadResult` union. */
    type: 'error';
    /** The error that caused the download failure. */
    error: Error;
}
/**
 * Discriminated union representing the current state of a monitored download.
 * Use the `type` property to determine the current state.
 */
export type DownloadResult = Progress | Undetermined | Done | DownloadError;
/**
 * Downloads a file from a URL and triggers a browser download dialog.
 * Falls back to opening the URL in a new tab if the fetch fails (e.g., due to CORS).
 *
 * @param url - The URL to download from
 * @param filename - The suggested filename for the download
 * @default filename ''
 *
 * @example
 * ```ts
 * await downloadUrl('https://example.com/file.pdf', 'document.pdf')
 * ```
 */
export declare const downloadUrl: (url: string, filename?: string) => Promise<void>;
/**
 * Creates a browser download from in-memory content (string or binary data).
 *
 * @param content - The content to download, either a string or a `Uint8Array`
 * @param filename - The suggested filename for the download
 * @param type - The MIME type of the content
 * @default type 'application/octet-stream'
 *
 * @example
 * ```ts
 * downloadContent('Hello, world!', 'hello.txt', 'text/plain')
 * downloadContent(new Uint8Array([0x89, 0x50, 0x4e, 0x47]), 'image.png', 'image/png')
 * ```
 */
export declare const downloadContent: (content: string | Uint8Array<ArrayBuffer>, filename: string, type?: string) => void;
/**
 * Downloads a file from a URL while providing real-time progress monitoring
 * through a reactive signal. Returns both the progress signal and a cancel function.
 *
 * The signal emits:
 * - `{ type: 'progress', value: 0..1 }` when content length is known
 * - `{ type: 'undetermined' }` when content length is unknown
 * - `{ type: 'done', file }` on successful completion
 * - `{ type: 'error', error }` on failure
 *
 * @param url - The URL to download from
 * @returns An object with a `signal` for monitoring progress and a `cancel` function to abort
 *
 * @example
 * ```ts
 * const { signal, cancel } = downloadUrlAndMonitor('https://example.com/large-file.zip')
 * signal.on(result => {
 *   if (result.type === 'progress') console.log(`${result.value * 100}%`)
 *   if (result.type === 'done') downloadFile(result.file)
 * })
 * // To cancel: cancel()
 * ```
 */
export declare const downloadUrlAndMonitor: (url: string) => {
    signal: Signal<DownloadResult>;
    cancel: () => void;
};
/**
 * Triggers a browser download dialog for a `File` object.
 *
 * @param file - The `File` object to download
 *
 * @example
 * ```ts
 * const file = new File(['content'], 'example.txt', { type: 'text/plain' })
 * downloadFile(file)
 * ```
 */
export declare const downloadFile: (file: File) => void;