import { isFileIdToken } from '@objectstack/spec/data';
/** A file value normalised for rendering, whatever form it arrived in. */
export interface FileValueView {
    /** `sys_file` id, when the value carries one. */
    id?: string;
    /** Best available display name. Never empty. */
    name: string;
    /** Resolvable URL, when the value carries one. A bare reference does not. */
    url?: string;
    size?: number;
    mimeType?: string;
    /** The value as it arrived, so callers can pass it through untouched. */
    raw: unknown;
}
/**
 * A minted file id: uuid/nanoid-shaped, and crucially not a URL — a URL always
 * carries `:`, `/` or `.`, so it can never match.
 *
 * This IS the platform's arbiter now, not a mirror of it (objectui#3161,
 * objectstack#4115 ledger batch 7). The declaration that stood here said it
 * "mirrors the platform's `isFileIdToken`" while being a character-for-character
 * copy of that function's body under that function's own name — the shape
 * objectui#3003 argued about and objectui#3169 caught again in
 * `isAggregatedViewContainer`: every value test and every behaviour test passes
 * against a faithful copy, so reference identity is the only check that can tell
 * a re-export from a fork. It is asserted in
 * `__tests__/spec-symbol-batch7.test.ts`.
 *
 * Why it matters that this one is shared rather than duplicated: the regex is a
 * WIRE decision. Widening it server-side (say, ids grow past 64 chars) while a
 * copy here keeps the old bound turns every new id into "not a reference", and
 * the widget then submits the legacy inline blob against a backend that expects
 * a reference. That failure surfaces as a broken thumbnail, nowhere near a
 * regex.
 */
export { isFileIdToken };
/**
 * The `sys_file` id a value refers to, or `undefined`.
 *
 * `file_id ?? id` matches the rule `serializeParamValues` already applies to
 * action params — one extraction rule for both surfaces.
 */
export declare function fileIdOf(value: unknown): string | undefined;
/**
 * The stable download endpoint a bare `sys_file` id resolves to.
 *
 * `createObjectStackUploadAdapter` stores exactly this URL (`${basePath}/files/
 * :id`, default base `/api/v1/storage`) as a completed upload's value, and the
 * endpoint 302-redirects to a freshly-signed short-lived URL on every request —
 * so it can be used directly as an `<img src>`. Building it here means a value
 * still in its bare-reference form (the backend read path didn't expand it —
 * seen on the edit-form data path, objectui image thumbnails rendering broken)
 * resolves to a real URL instead of an empty `src`.
 */
export declare const FILE_STORAGE_BASE_PATH = "/api/v1/storage";
/** The stable download URL for a `sys_file` id. */
export declare function fileUrlFromId(id: string): string;
/**
 * Normalise one file value for display.
 *
 * @param fallbackName shown when the value carries no usable name — pass a
 *   translated string so the widget stays localised.
 */
export declare function readFileValue(value: unknown, fallbackName?: string): FileValueView;
/** Normalise a field value (single or `multiple`) to an array of views. */
export declare function readFileValues(value: unknown, fallbackName?: string): FileValueView[];
/** Does this value look like an image, by MIME type? */
export declare function isImageValue(view: FileValueView): boolean;
/** The subset of an upload result these helpers read. */
export interface UploadResultLike {
    url: string;
    name: string;
    size: number;
    mimeType: string;
    meta?: Record<string, unknown>;
}
/**
 * What to store in the field for a completed upload.
 *
 * Returns the bare `sys_file` id when the adapter surfaced one — the reference
 * form — and the legacy inline blob when it did not, so a deployment whose
 * upload adapter or backend predates file-as-reference keeps working unchanged.
 */
export declare function fileValueForSubmit(result: UploadResultLike, originalName?: string): string | Record<string, unknown>;
/**
 * The display view of a just-completed upload.
 *
 * Submitting a bare id means the field value no longer carries the name, size
 * or URL needed to render it, and the enriched form only comes back on the next
 * read. Widgets keep these views keyed by id so an upload appears immediately
 * instead of showing a bare token until a refetch.
 */
export declare function uploadResultView(result: UploadResultLike, originalName?: string): FileValueView;
/**
 * Merge locally-known upload views over a field value's own views, matched by
 * id. A value that is still a bare reference picks up the name/URL captured at
 * upload time; anything already enriched by the backend is left alone.
 */
export declare function withRecentUploads(views: FileValueView[], recent: Record<string, FileValueView>): FileValueView[];