uploaderkit 1.0.0 → 2.0.0

package/dist/ui.d.cts

@@ -0,0 +1,331 @@
+import { f as UseSlottedUploaderOptions } from './useSlottedUploader-BzT5jV8c.cjs';
+export { U as UploaderLanguage, d as UploaderProvider, e as UploaderProviderProps, j as useUploaderLabels } from './useSlottedUploader-BzT5jV8c.cjs';
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { U as UploaderLabels, o as StoredFile, d as ScopeConfig } from './types-BSlJJwti.cjs';
+import { e as UploaderFile, R as RemoveStrategy, U as UseUploaderOptions } from './useUploader-BiBdS-7y.cjs';
+import { V as ViewableFile, F as FileViewerProps } from './FileViewer-ChTf7-uY.cjs';
+export { a as FileViewer } from './FileViewer-ChTf7-uY.cjs';
+
+/** Minimal class joiner — the package has no runtime deps to spend on clsx. */
+declare const cn: (...values: (string | false | null | undefined)[]) => string;
+
+type ConfirmDialogProps = {
+    open: boolean;
+    title: string;
+    message: ReactNode;
+    /** Tone of the affirmative button. @defaultValue 'danger' */
+    variant?: 'danger' | 'primary';
+    confirmLabel?: string;
+    cancelLabel?: string;
+    onConfirm: () => void;
+    onCancel: () => void;
+    labels?: Partial<UploaderLabels>;
+};
+/**
+ * Second-step gate for destructive file actions — remove a stored file,
+ * replace a slot. Focus lands on **cancel** so a stray Enter never destroys
+ * anything, Escape and the backdrop cancel, and `Tab` stays inside. Exported
+ * for app-level use around the uploaders' callbacks.
+ */
+declare const ConfirmDialog: ({ open, title, message, variant, confirmLabel, cancelLabel, onConfirm, onCancel, labels, }: ConfirmDialogProps) => react.ReactPortal | null;
+
+/**
+ * When a styled uploader sends, as the three flows every product screen falls
+ * into — named at the UI level so a call site declares its intent instead of
+ * assembling it from `uploadOn` + button + controller by hand:
+ *
+ * - `'select'` — fires the moment a valid file lands. Avatars, quick
+ *   replacements: surfaces where the file IS the action and there is nothing
+ *   else to wait for.
+ * - `'submit'` — staged until the surrounding form sends it through
+ *   `controllerRef`, together with the rest of the fields. The only correct
+ *   mode when the record the file belongs to does not exist yet, or when a
+ *   stable-key scope would overwrite what the entity serves before the user
+ *   confirmed anything.
+ * - `'manual'` — staged, and the zone shows its own upload button: the user
+ *   drops files and decides the moment. Evidence and other punctual flows
+ *   with no form around them.
+ *
+ * The hook underneath only knows `'select' | 'manual'` (fire now vs wait for
+ * `upload()`): `'submit'` and `'manual'` are the same machine state with a
+ * different owner of the send — the form or the zone.
+ */
+type UiUploadTrigger = 'select' | 'submit' | 'manual';
+/**
+ * What a surrounding form needs to send the staged files from its own submit —
+ * the flow `uploadOn: 'manual'` exists for, where the file travels together
+ * with the rest of the fields instead of the moment it is picked.
+ *
+ * A ref rather than a callback prop: the form reads it inside its submit
+ * handler, and a controller passed down would re-render the zone on every
+ * keystroke elsewhere in the form.
+ *
+ * @see AGENTS.md §3 — "Arity lives on the scope", same reasoning one level up
+ */
+type UploaderController<TResult = StoredFile[]> = {
+    /** Uploads everything still waiting. Resolves with what the server confirmed. */
+    upload: () => Promise<TResult>;
+    /** `true` while a file waits for `upload()`. */
+    hasPending: boolean;
+    isUploading: boolean;
+};
+/** Slots settle through `onChange`, so the batch itself resolves with nothing. */
+type SlottedUploaderController = UploaderController<void>;
+/**
+ * Structural rather than React's `RefObject`: that type is read-only under the
+ * v18 typings and writable under v19, and the package supports both.
+ * `useRef<UploaderController | null>(null)` satisfies it either way.
+ */
+type UploaderControllerRef<TResult = StoredFile[]> = {
+    current: UploaderController<TResult> | null;
+};
+
+type DropzoneProps = {
+    accept: string;
+    multiple?: boolean;
+    disabled?: boolean;
+    /**
+     * Mobile camera shortcut: `'environment'` (rear) or `'user'` (front) makes
+     * the file picker offer the camera directly on touch devices. Desktop
+     * browsers ignore it.
+     */
+    capture?: 'user' | 'environment';
+    /** @defaultValue 'md' */
+    size?: 'sm' | 'md';
+    /**
+     * Global keyboard shortcut that opens this zone's picker, e.g. `'mod+u'`
+     * (⌘U / Ctrl+U). A small key hint renders under the prompt on fine
+     * pointers. With several zones on screen, give each its own combo.
+     */
+    shortcut?: string;
+    onFiles: (files: File[]) => void;
+    children: ReactNode;
+    className?: string;
+};
+/**
+ * The one drag-and-drop surface both uploaders share: drag state, click and
+ * keyboard to browse, paste while focused (screenshots land as files), and a
+ * hidden input. Presentation comes from `children`.
+ */
+declare const Dropzone: ({ accept, multiple, disabled, capture, size, shortcut, onFiles, children, className, }: DropzoneProps) => react.JSX.Element;
+
+type FileItemProps = {
+    file: UploaderFile;
+    onRemove: () => void;
+    onAbort: () => void;
+    /** Present on successes when a viewer is available. */
+    onView?: () => void;
+    /** @defaultValue 'md' */
+    size?: 'sm' | 'md';
+    labels?: Partial<UploaderLabels>;
+};
+/**
+ * One row of upload state: preview/extension badge, name, size, a progress
+ * bar while in flight, the error when it failed. Shared by both uploaders so
+ * a file always looks the same wherever it is being uploaded.
+ */
+declare const FileItem: ({ file, onRemove, onAbort, onView, size, labels, }: FileItemProps) => react.JSX.Element;
+
+type SlottedUploaderProps<T extends Record<string, ScopeConfig>> = Omit<UseSlottedUploaderOptions<T>, 'uploadOn'> & {
+    /**
+     * When the slots travel. This presentation has no upload button of its
+     * own, so `'manual'` is not offered here: staged slots can only leave
+     * through a form's `controllerRef`, which is `'submit'`.
+     * @defaultValue 'select'
+     * @see UiUploadTrigger
+     */
+    uploadOn?: Exclude<UiUploadTrigger, 'manual'>;
+    title?: string;
+    description?: string;
+    /** Hide the bulk dropzone and keep only per-row buttons. */
+    hideDropzone?: boolean;
+    /**
+     * Gate removing a filled slot behind a confirmation dialog. `true` uses
+     * the label defaults; an object overrides the copy.
+     */
+    confirmRemove?: boolean | {
+        title?: string;
+        message?: string;
+    };
+    /**
+     * Confirm before a picked file replaces what a slot already holds. The
+     * dialog names both files, so the user sees what is about to be lost.
+     */
+    confirmReplace?: boolean | {
+        title?: string;
+        message?: string;
+    };
+    /**
+     * Deletion transport. With it, a confirmed slot removal deletes the object
+     * from storage BY ITSELF — unless the scope is `keepOnRemove`, the history
+     * contract — same wiring as `Uploader`.
+     */
+    removeStrategy?: RemoveStrategy;
+    /** Fresh URL right before previewing — for private scopes whose signed url expired. */
+    resolveViewUrl?: (file: ViewableFile) => Promise<string>;
+    /** Compact paddings and glyphs everywhere. @defaultValue 'md' */
+    size?: 'sm' | 'md';
+    /** Glyph inside the bulk dropzone. `null` removes it. */
+    icon?: ReactNode;
+    /** Keyboard shortcut that opens the bulk picker, e.g. `'mod+u'`. */
+    shortcut?: string;
+    /**
+     * Filled with the live controller so the surrounding form can send the
+     * staged slots from its own submit. Required by `uploadOn: 'submit'`:
+     * without it a staged slot has no way to ever leave.
+     */
+    controllerRef?: UploaderControllerRef<void>;
+    /**
+     * Fires when the zone starts or stops holding files that `upload()`
+     * would send. The companion of `controllerRef`: a form that defers the
+     * send has no other way to know it has unsent work, so its save button
+     * would stay disabled on a pristine form the user has just dropped a
+     * file into.
+     */
+    onPendingChange?: (hasPending: boolean) => void;
+    className?: string;
+};
+/**
+ * Named-slot presentation over the same machine as `Uploader`: a status row
+ * per slot plus one bulk dropzone whose matcher routes each file to its slot.
+ */
+declare const SlottedUploader: <T extends Record<string, ScopeConfig>>({ uploadOn, title, description, hideDropzone, confirmRemove, confirmReplace, removeStrategy, resolveViewUrl, size, icon, shortcut, controllerRef, onPendingChange, className, ...options }: SlottedUploaderProps<T>) => react.JSX.Element;
+
+/**
+ * What {@link UploaderProps.renderFiles} is handed.
+ *
+ * Both the raw state and the default rows already built, so a custom layout can
+ * keep the standard item and only change where — and among what — it sits.
+ */
+type UploaderFilesSlot = {
+    /** Files already persisted, exactly as passed in `stored`. */
+    stored: StoredFile[];
+    /** Files staged in this session, each with its live upload status. */
+    staged: UploaderFile[];
+    /** The default rows. Place them, wrap them, or drop them entirely. */
+    nodes: ReactNode;
+    /** Nothing persisted and nothing staged. */
+    isEmpty: boolean;
+    /** Open a persisted file in the built-in viewer. */
+    view: (file: StoredFile) => void;
+    /** Forget a staged file. */
+    remove: (id: string) => void;
+    /**
+     * Forget a persisted file, honouring `confirmRemove` and `removeStrategy`.
+     * `undefined` when this uploader accepts no removals.
+     */
+    removeStored?: (file: StoredFile) => void;
+};
+type UploaderProps<T extends Record<string, ScopeConfig>> = Omit<UseUploaderOptions<T>, 'uploadOn'> & {
+    /**
+     * When the files travel. @defaultValue 'select'
+     * @see UiUploadTrigger — which mode fits which screen
+     */
+    uploadOn?: UiUploadTrigger;
+    label?: string;
+    description?: string;
+    /** Files already persisted, rendered on the {@link filesPosition} side. */
+    stored?: StoredFile[];
+    /**
+     * Which side of the dropzone the file lists sit on. @defaultValue 'above'
+     *
+     * `'below'` keeps the drop target anchored: with the lists above it, every
+     * added file pushes the zone further down, so the control the user is
+     * repeatedly aiming at moves under the cursor.
+     */
+    filesPosition?: 'above' | 'below';
+    /**
+     * Lay the file lists out yourself: a grid of thumbnails, a single summary
+     * line, a count folded into your own card — whatever the screen needs.
+     *
+     * It replaces the rows, not their place: the result still renders on the
+     * {@link filesPosition} side. For a layout the zone itself has to be part of
+     * (files BESIDE the dropzone, files inside your own frame), skip this skin
+     * and compose `useUploader` with the exported `Dropzone` / `FileItem` /
+     * `StoredFileItem` — nothing here is unavailable there.
+     */
+    renderFiles?: (slot: UploaderFilesSlot) => ReactNode;
+    /**
+     * Notified when a persisted file is forgotten — the app's bookkeeping
+     * (clear the DB reference). Storage deletion belongs to `removeStrategy`.
+     */
+    onRemoveStored?: (file: StoredFile) => void;
+    /**
+     * Deletion transport. With it, a confirmed removal deletes the object from
+     * storage BY ITSELF — unless the scope is `keepOnRemove`, the history
+     * contract — so no consumer can orphan by forgetting a callback.
+     */
+    removeStrategy?: RemoveStrategy;
+    /**
+     * Gate `onRemoveStored` behind a confirmation dialog. `true` uses the
+     * label defaults; an object overrides the copy for this uploader.
+     */
+    confirmRemove?: boolean | {
+        title?: string;
+        message?: string;
+    };
+    /** Fresh URL right before previewing — for private scopes whose signed url expired. */
+    resolveViewUrl?: (file: ViewableFile) => Promise<string>;
+    /** Mobile camera shortcut, forwarded to the dropzone's input. */
+    capture?: 'user' | 'environment';
+    /** Compact paddings and glyphs everywhere. @defaultValue 'md' */
+    size?: 'sm' | 'md';
+    /** Glyph inside the dropzone. `null` removes it; defaults to an upload cloud. */
+    icon?: ReactNode;
+    /** Keyboard shortcut that opens the picker, e.g. `'mod+u'`. Hinted in the zone. */
+    shortcut?: string;
+    /**
+     * Filled with the live controller so the surrounding form can send the
+     * staged files from its own submit. Required by `uploadOn: 'submit'`,
+     * which has no other way to fire; readable under `'manual'` too, where
+     * the zone's button stays the sender.
+     */
+    controllerRef?: UploaderControllerRef;
+    /**
+     * Fires when the zone starts or stops holding files that `upload()`
+     * would send. The companion of `controllerRef`: a form that defers the
+     * send has no other way to know it has unsent work, so its save button
+     * would stay disabled on a pristine form the user has just dropped a
+     * file into.
+     */
+    onPendingChange?: (hasPending: boolean) => void;
+    disabled?: boolean;
+    className?: string;
+};
+/**
+ * The styled single-zone uploader: one dropzone, one or many files in it.
+ * Purely a skin over `useUploader` — apps needing custom markup use the hook
+ * directly and lose nothing.
+ *
+ * Defaults `uploadOn` to `'select'`. `'manual'` gives the zone its own upload
+ * button; `'submit'` hands the send to the surrounding form via
+ * `controllerRef`. @see UiUploadTrigger for which mode fits which screen.
+ */
+declare const Uploader: <T extends Record<string, ScopeConfig>>({ uploadOn, label, description, stored, filesPosition, renderFiles, onRemoveStored, confirmRemove, resolveViewUrl, capture, size, icon, shortcut, controllerRef, onPendingChange, removeStrategy, disabled, className, ...options }: UploaderProps<T>) => react.JSX.Element;
+
+type UseFileViewerOptions = {
+    /** Forwarded to the viewer — the authenticated resolver for private urls. */
+    resolveUrl?: FileViewerProps['resolveUrl'];
+};
+type UseFileViewerReturn = {
+    /** Currently open file, `null` when closed. */
+    viewing: ViewableFile | null;
+    open: (file: ViewableFile) => void;
+    close: () => void;
+    /** Spread into `<FileViewer {...viewerProps} />` — the whole wiring. */
+    viewerProps: Pick<FileViewerProps, 'file' | 'onClose' | 'resolveUrl'>;
+};
+/**
+ * The open/close state every screen with a `FileViewer` repeats. One call
+ * replaces the `useState` + prop plumbing:
+ *
+ * ```tsx
+ * const viewer = useFileViewer({ resolveUrl })
+ * <button onClick={() => viewer.open(stored)}>Ver</button>
+ * <FileViewer {...viewer.viewerProps} />
+ * ```
+ */
+declare const useFileViewer: ({ resolveUrl, }?: UseFileViewerOptions) => UseFileViewerReturn;
+
+export { ConfirmDialog, type ConfirmDialogProps, Dropzone, type DropzoneProps, FileItem, type FileItemProps, FileViewerProps, SlottedUploader, type SlottedUploaderController, type SlottedUploaderProps, type UiUploadTrigger, Uploader, type UploaderController, type UploaderControllerRef, type UploaderFilesSlot, type UploaderProps, type UseFileViewerOptions, type UseFileViewerReturn, ViewableFile, cn, useFileViewer };

package/dist/ui.d.ts

@@ -0,0 +1,331 @@
+import { f as UseSlottedUploaderOptions } from './useSlottedUploader-IkG5RhEO.js';
+export { U as UploaderLanguage, d as UploaderProvider, e as UploaderProviderProps, j as useUploaderLabels } from './useSlottedUploader-IkG5RhEO.js';
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { U as UploaderLabels, o as StoredFile, d as ScopeConfig } from './types-BSlJJwti.js';
+import { e as UploaderFile, R as RemoveStrategy, U as UseUploaderOptions } from './useUploader-CQHpj_oI.js';
+import { V as ViewableFile, F as FileViewerProps } from './FileViewer-nuD-GEdJ.js';
+export { a as FileViewer } from './FileViewer-nuD-GEdJ.js';
+
+/** Minimal class joiner — the package has no runtime deps to spend on clsx. */
+declare const cn: (...values: (string | false | null | undefined)[]) => string;
+
+type ConfirmDialogProps = {
+    open: boolean;
+    title: string;
+    message: ReactNode;
+    /** Tone of the affirmative button. @defaultValue 'danger' */
+    variant?: 'danger' | 'primary';
+    confirmLabel?: string;
+    cancelLabel?: string;
+    onConfirm: () => void;
+    onCancel: () => void;
+    labels?: Partial<UploaderLabels>;
+};
+/**
+ * Second-step gate for destructive file actions — remove a stored file,
+ * replace a slot. Focus lands on **cancel** so a stray Enter never destroys
+ * anything, Escape and the backdrop cancel, and `Tab` stays inside. Exported
+ * for app-level use around the uploaders' callbacks.
+ */
+declare const ConfirmDialog: ({ open, title, message, variant, confirmLabel, cancelLabel, onConfirm, onCancel, labels, }: ConfirmDialogProps) => react.ReactPortal | null;
+
+/**
+ * When a styled uploader sends, as the three flows every product screen falls
+ * into — named at the UI level so a call site declares its intent instead of
+ * assembling it from `uploadOn` + button + controller by hand:
+ *
+ * - `'select'` — fires the moment a valid file lands. Avatars, quick
+ *   replacements: surfaces where the file IS the action and there is nothing
+ *   else to wait for.
+ * - `'submit'` — staged until the surrounding form sends it through
+ *   `controllerRef`, together with the rest of the fields. The only correct
+ *   mode when the record the file belongs to does not exist yet, or when a
+ *   stable-key scope would overwrite what the entity serves before the user
+ *   confirmed anything.
+ * - `'manual'` — staged, and the zone shows its own upload button: the user
+ *   drops files and decides the moment. Evidence and other punctual flows
+ *   with no form around them.
+ *
+ * The hook underneath only knows `'select' | 'manual'` (fire now vs wait for
+ * `upload()`): `'submit'` and `'manual'` are the same machine state with a
+ * different owner of the send — the form or the zone.
+ */
+type UiUploadTrigger = 'select' | 'submit' | 'manual';
+/**
+ * What a surrounding form needs to send the staged files from its own submit —
+ * the flow `uploadOn: 'manual'` exists for, where the file travels together
+ * with the rest of the fields instead of the moment it is picked.
+ *
+ * A ref rather than a callback prop: the form reads it inside its submit
+ * handler, and a controller passed down would re-render the zone on every
+ * keystroke elsewhere in the form.
+ *
+ * @see AGENTS.md §3 — "Arity lives on the scope", same reasoning one level up
+ */
+type UploaderController<TResult = StoredFile[]> = {
+    /** Uploads everything still waiting. Resolves with what the server confirmed. */
+    upload: () => Promise<TResult>;
+    /** `true` while a file waits for `upload()`. */
+    hasPending: boolean;
+    isUploading: boolean;
+};
+/** Slots settle through `onChange`, so the batch itself resolves with nothing. */
+type SlottedUploaderController = UploaderController<void>;
+/**
+ * Structural rather than React's `RefObject`: that type is read-only under the
+ * v18 typings and writable under v19, and the package supports both.
+ * `useRef<UploaderController | null>(null)` satisfies it either way.
+ */
+type UploaderControllerRef<TResult = StoredFile[]> = {
+    current: UploaderController<TResult> | null;
+};
+
+type DropzoneProps = {
+    accept: string;
+    multiple?: boolean;
+    disabled?: boolean;
+    /**
+     * Mobile camera shortcut: `'environment'` (rear) or `'user'` (front) makes
+     * the file picker offer the camera directly on touch devices. Desktop
+     * browsers ignore it.
+     */
+    capture?: 'user' | 'environment';
+    /** @defaultValue 'md' */
+    size?: 'sm' | 'md';
+    /**
+     * Global keyboard shortcut that opens this zone's picker, e.g. `'mod+u'`
+     * (⌘U / Ctrl+U). A small key hint renders under the prompt on fine
+     * pointers. With several zones on screen, give each its own combo.
+     */
+    shortcut?: string;
+    onFiles: (files: File[]) => void;
+    children: ReactNode;
+    className?: string;
+};
+/**
+ * The one drag-and-drop surface both uploaders share: drag state, click and
+ * keyboard to browse, paste while focused (screenshots land as files), and a
+ * hidden input. Presentation comes from `children`.
+ */
+declare const Dropzone: ({ accept, multiple, disabled, capture, size, shortcut, onFiles, children, className, }: DropzoneProps) => react.JSX.Element;
+
+type FileItemProps = {
+    file: UploaderFile;
+    onRemove: () => void;
+    onAbort: () => void;
+    /** Present on successes when a viewer is available. */
+    onView?: () => void;
+    /** @defaultValue 'md' */
+    size?: 'sm' | 'md';
+    labels?: Partial<UploaderLabels>;
+};
+/**
+ * One row of upload state: preview/extension badge, name, size, a progress
+ * bar while in flight, the error when it failed. Shared by both uploaders so
+ * a file always looks the same wherever it is being uploaded.
+ */
+declare const FileItem: ({ file, onRemove, onAbort, onView, size, labels, }: FileItemProps) => react.JSX.Element;
+
+type SlottedUploaderProps<T extends Record<string, ScopeConfig>> = Omit<UseSlottedUploaderOptions<T>, 'uploadOn'> & {
+    /**
+     * When the slots travel. This presentation has no upload button of its
+     * own, so `'manual'` is not offered here: staged slots can only leave
+     * through a form's `controllerRef`, which is `'submit'`.
+     * @defaultValue 'select'
+     * @see UiUploadTrigger
+     */
+    uploadOn?: Exclude<UiUploadTrigger, 'manual'>;
+    title?: string;
+    description?: string;
+    /** Hide the bulk dropzone and keep only per-row buttons. */
+    hideDropzone?: boolean;
+    /**
+     * Gate removing a filled slot behind a confirmation dialog. `true` uses
+     * the label defaults; an object overrides the copy.
+     */
+    confirmRemove?: boolean | {
+        title?: string;
+        message?: string;
+    };
+    /**
+     * Confirm before a picked file replaces what a slot already holds. The
+     * dialog names both files, so the user sees what is about to be lost.
+     */
+    confirmReplace?: boolean | {
+        title?: string;
+        message?: string;
+    };
+    /**
+     * Deletion transport. With it, a confirmed slot removal deletes the object
+     * from storage BY ITSELF — unless the scope is `keepOnRemove`, the history
+     * contract — same wiring as `Uploader`.
+     */
+    removeStrategy?: RemoveStrategy;
+    /** Fresh URL right before previewing — for private scopes whose signed url expired. */
+    resolveViewUrl?: (file: ViewableFile) => Promise<string>;
+    /** Compact paddings and glyphs everywhere. @defaultValue 'md' */
+    size?: 'sm' | 'md';
+    /** Glyph inside the bulk dropzone. `null` removes it. */
+    icon?: ReactNode;
+    /** Keyboard shortcut that opens the bulk picker, e.g. `'mod+u'`. */
+    shortcut?: string;
+    /**
+     * Filled with the live controller so the surrounding form can send the
+     * staged slots from its own submit. Required by `uploadOn: 'submit'`:
+     * without it a staged slot has no way to ever leave.
+     */
+    controllerRef?: UploaderControllerRef<void>;
+    /**
+     * Fires when the zone starts or stops holding files that `upload()`
+     * would send. The companion of `controllerRef`: a form that defers the
+     * send has no other way to know it has unsent work, so its save button
+     * would stay disabled on a pristine form the user has just dropped a
+     * file into.
+     */
+    onPendingChange?: (hasPending: boolean) => void;
+    className?: string;
+};
+/**
+ * Named-slot presentation over the same machine as `Uploader`: a status row
+ * per slot plus one bulk dropzone whose matcher routes each file to its slot.
+ */
+declare const SlottedUploader: <T extends Record<string, ScopeConfig>>({ uploadOn, title, description, hideDropzone, confirmRemove, confirmReplace, removeStrategy, resolveViewUrl, size, icon, shortcut, controllerRef, onPendingChange, className, ...options }: SlottedUploaderProps<T>) => react.JSX.Element;
+
+/**
+ * What {@link UploaderProps.renderFiles} is handed.
+ *
+ * Both the raw state and the default rows already built, so a custom layout can
+ * keep the standard item and only change where — and among what — it sits.
+ */
+type UploaderFilesSlot = {
+    /** Files already persisted, exactly as passed in `stored`. */
+    stored: StoredFile[];
+    /** Files staged in this session, each with its live upload status. */
+    staged: UploaderFile[];
+    /** The default rows. Place them, wrap them, or drop them entirely. */
+    nodes: ReactNode;
+    /** Nothing persisted and nothing staged. */
+    isEmpty: boolean;
+    /** Open a persisted file in the built-in viewer. */
+    view: (file: StoredFile) => void;
+    /** Forget a staged file. */
+    remove: (id: string) => void;
+    /**
+     * Forget a persisted file, honouring `confirmRemove` and `removeStrategy`.
+     * `undefined` when this uploader accepts no removals.
+     */
+    removeStored?: (file: StoredFile) => void;
+};
+type UploaderProps<T extends Record<string, ScopeConfig>> = Omit<UseUploaderOptions<T>, 'uploadOn'> & {
+    /**
+     * When the files travel. @defaultValue 'select'
+     * @see UiUploadTrigger — which mode fits which screen
+     */
+    uploadOn?: UiUploadTrigger;
+    label?: string;
+    description?: string;
+    /** Files already persisted, rendered on the {@link filesPosition} side. */
+    stored?: StoredFile[];
+    /**
+     * Which side of the dropzone the file lists sit on. @defaultValue 'above'
+     *
+     * `'below'` keeps the drop target anchored: with the lists above it, every
+     * added file pushes the zone further down, so the control the user is
+     * repeatedly aiming at moves under the cursor.
+     */
+    filesPosition?: 'above' | 'below';
+    /**
+     * Lay the file lists out yourself: a grid of thumbnails, a single summary
+     * line, a count folded into your own card — whatever the screen needs.
+     *
+     * It replaces the rows, not their place: the result still renders on the
+     * {@link filesPosition} side. For a layout the zone itself has to be part of
+     * (files BESIDE the dropzone, files inside your own frame), skip this skin
+     * and compose `useUploader` with the exported `Dropzone` / `FileItem` /
+     * `StoredFileItem` — nothing here is unavailable there.
+     */
+    renderFiles?: (slot: UploaderFilesSlot) => ReactNode;
+    /**
+     * Notified when a persisted file is forgotten — the app's bookkeeping
+     * (clear the DB reference). Storage deletion belongs to `removeStrategy`.
+     */
+    onRemoveStored?: (file: StoredFile) => void;
+    /**
+     * Deletion transport. With it, a confirmed removal deletes the object from
+     * storage BY ITSELF — unless the scope is `keepOnRemove`, the history
+     * contract — so no consumer can orphan by forgetting a callback.
+     */
+    removeStrategy?: RemoveStrategy;
+    /**
+     * Gate `onRemoveStored` behind a confirmation dialog. `true` uses the
+     * label defaults; an object overrides the copy for this uploader.
+     */
+    confirmRemove?: boolean | {
+        title?: string;
+        message?: string;
+    };
+    /** Fresh URL right before previewing — for private scopes whose signed url expired. */
+    resolveViewUrl?: (file: ViewableFile) => Promise<string>;
+    /** Mobile camera shortcut, forwarded to the dropzone's input. */
+    capture?: 'user' | 'environment';
+    /** Compact paddings and glyphs everywhere. @defaultValue 'md' */
+    size?: 'sm' | 'md';
+    /** Glyph inside the dropzone. `null` removes it; defaults to an upload cloud. */
+    icon?: ReactNode;
+    /** Keyboard shortcut that opens the picker, e.g. `'mod+u'`. Hinted in the zone. */
+    shortcut?: string;
+    /**
+     * Filled with the live controller so the surrounding form can send the
+     * staged files from its own submit. Required by `uploadOn: 'submit'`,
+     * which has no other way to fire; readable under `'manual'` too, where
+     * the zone's button stays the sender.
+     */
+    controllerRef?: UploaderControllerRef;
+    /**
+     * Fires when the zone starts or stops holding files that `upload()`
+     * would send. The companion of `controllerRef`: a form that defers the
+     * send has no other way to know it has unsent work, so its save button
+     * would stay disabled on a pristine form the user has just dropped a
+     * file into.
+     */
+    onPendingChange?: (hasPending: boolean) => void;
+    disabled?: boolean;
+    className?: string;
+};
+/**
+ * The styled single-zone uploader: one dropzone, one or many files in it.
+ * Purely a skin over `useUploader` — apps needing custom markup use the hook
+ * directly and lose nothing.
+ *
+ * Defaults `uploadOn` to `'select'`. `'manual'` gives the zone its own upload
+ * button; `'submit'` hands the send to the surrounding form via
+ * `controllerRef`. @see UiUploadTrigger for which mode fits which screen.
+ */
+declare const Uploader: <T extends Record<string, ScopeConfig>>({ uploadOn, label, description, stored, filesPosition, renderFiles, onRemoveStored, confirmRemove, resolveViewUrl, capture, size, icon, shortcut, controllerRef, onPendingChange, removeStrategy, disabled, className, ...options }: UploaderProps<T>) => react.JSX.Element;
+
+type UseFileViewerOptions = {
+    /** Forwarded to the viewer — the authenticated resolver for private urls. */
+    resolveUrl?: FileViewerProps['resolveUrl'];
+};
+type UseFileViewerReturn = {
+    /** Currently open file, `null` when closed. */
+    viewing: ViewableFile | null;
+    open: (file: ViewableFile) => void;
+    close: () => void;
+    /** Spread into `<FileViewer {...viewerProps} />` — the whole wiring. */
+    viewerProps: Pick<FileViewerProps, 'file' | 'onClose' | 'resolveUrl'>;
+};
+/**
+ * The open/close state every screen with a `FileViewer` repeats. One call
+ * replaces the `useState` + prop plumbing:
+ *
+ * ```tsx
+ * const viewer = useFileViewer({ resolveUrl })
+ * <button onClick={() => viewer.open(stored)}>Ver</button>
+ * <FileViewer {...viewer.viewerProps} />
+ * ```
+ */
+declare const useFileViewer: ({ resolveUrl, }?: UseFileViewerOptions) => UseFileViewerReturn;
+
+export { ConfirmDialog, type ConfirmDialogProps, Dropzone, type DropzoneProps, FileItem, type FileItemProps, FileViewerProps, SlottedUploader, type SlottedUploaderController, type SlottedUploaderProps, type UiUploadTrigger, Uploader, type UploaderController, type UploaderControllerRef, type UploaderFilesSlot, type UploaderProps, type UseFileViewerOptions, type UseFileViewerReturn, ViewableFile, cn, useFileViewer };