@marianmeres/stuic 3.181.0 → 3.183.0

package/dist/components/Input/FieldSingleAsset.svelte.d.ts

@@ -0,0 +1,135 @@
+import { type Snippet } from "svelte";
+import { type ValidateOptions, type ValidationResult } from "../../actions/validate.svelte.js";
+import type { TranslateFn } from "../../types.js";
+import { NotificationsStack } from "../Notifications/notifications-stack.svelte.js";
+import { type THC } from "../Thc/Thc.svelte";
+import type { FieldAsset } from "./FieldAssets.svelte";
+import type { InputWrapClassProps } from "./types.js";
+type SnippetWithId = Snippet<[{
+    id: string;
+}]>;
+/** What `processAsset` receives besides the optimistic (blob) asset. */
+export interface FieldSingleAssetUploadContext {
+    /** The file to upload — already run through `transformFile`, if any. */
+    file: File;
+    /** Report upload progress (0–100). Rendered when `withOnProgress` is set. */
+    onProgress: (progress: number) => void;
+}
+export type FieldSingleAssetShape = "square" | "circle" | "wide";
+export type FieldSingleAssetFit = "cover" | "contain";
+export type FieldSingleAssetSize = "sm" | "md" | "lg";
+/** `validateFile` verdict: a non-empty string rejects the file with that message. */
+export type FieldSingleAssetFileCheck = string | void | null | undefined | false;
+export interface Props extends InputWrapClassProps, Record<string, any> {
+    /**
+     * The serialized asset: by default the JSON of ONE `FieldAsset` object, or the
+     * empty string when the field is empty (see `parseValue` / `serializeValue`).
+     * Only ever rewritten when a user action SETTLES — an upload that resolves, a
+     * remove, an undo. An in-flight or failed upload never touches it.
+     */
+    value: string;
+    /** The hidden input's name (what the form submits). */
+    name: string;
+    label?: SnippetWithId | THC;
+    description?: SnippetWithId | THC;
+    labelAfter?: SnippetWithId | THC;
+    below?: SnippetWithId | THC;
+    class?: string;
+    id?: string;
+    tabindex?: number;
+    renderSize?: "sm" | "md" | "lg" | string;
+    required?: boolean;
+    disabled?: boolean;
+    validate?: boolean | Omit<ValidateOptions, "setValidationResult">;
+    labelLeft?: boolean;
+    labelLeftWidth?: "normal" | "wide";
+    labelLeftBreakpoint?: number;
+    /** Classes for the hidden `<input type="file">` */
+    classInput?: string;
+    /** Classes for the outermost wrapper (the drop zone) */
+    classWrap?: string;
+    /** Classes for the tile (the preview button) */
+    classPreview?: string;
+    /** Classes for the tile's action buttons (remove, preview, retry) */
+    classControls?: string;
+    style?: string;
+    t?: TranslateFn;
+    notifications?: NotificationsStack;
+    /** Initial-fetch state: renders a skeleton in the tile's shape; takes no input. */
+    isLoading?: boolean;
+    /** `value` -> asset. Default: `JSON.parse`, `null` for an empty/invalid string. */
+    parseValue?: (serialized: string) => FieldAsset | null;
+    /** asset -> `value`. Default: `JSON.stringify`, `""` for `null`. */
+    serializeValue?: (asset: FieldAsset | null) => string;
+    /**
+     * The upload. Receives the optimistic asset (its `id` and every `url` are one
+     * blob URL of the file) and the file itself; resolves with the stored asset,
+     * which becomes the new `value`. A rejection keeps the previous `value`, shows
+     * an error state on the tile with Retry / Discard, and reports `notifications`.
+     * Without it the field is display-only (no picker, no drop, no paste).
+     */
+    processAsset?: (asset: FieldAsset, ctx: FieldSingleAssetUploadContext) => Promise<FieldAsset>;
+    /** Render a progress ring driven by `ctx.onProgress` instead of a spinner. */
+    withOnProgress?: boolean;
+    /** Same tokens as the HTML `accept` attribute; also applied to drops and pastes. */
+    accept?: string;
+    /** Passed to the file input: on phones opens the camera directly. */
+    capture?: "user" | "environment";
+    /** Reject files larger than this many bytes (checked after `transformFile`). */
+    maxSize?: number;
+    /**
+     * Custom check, run after `transformFile` and `maxSize`. Return a non-empty
+     * string to reject the file with that message (may be async — e.g. read image
+     * dimensions first).
+     */
+    validateFile?: (file: File) => FieldSingleAssetFileCheck | Promise<FieldSingleAssetFileCheck>;
+    /**
+     * Pre-upload hook, run after the `accept` check: downscale a photo, or open a
+     * cropper and resolve with the cropped file. Resolving with `null`/`undefined`
+     * cancels silently (the user closed the cropper).
+     */
+    transformFile?: (file: File) => File | null | undefined | Promise<File | null | undefined>;
+    /** Return `false` (may be async) to keep the asset. */
+    onBeforeRemove?: (asset: FieldAsset) => boolean | Promise<boolean>;
+    /** Return `false` (may be async) to keep the current asset instead of uploading `file`. */
+    onBeforeReplace?: (current: FieldAsset, file: File) => boolean | Promise<boolean>;
+    /**
+     * After a remove, an inline "Undo" stays available this many ms (the removed
+     * asset is only unlinked from `value`, never deleted anywhere, so undo is
+     * lossless). `0` disables it. Default `6000`.
+     */
+    undoTtl?: number;
+    /**
+     * Opt-in: accept a clipboard paste (Ctrl/Cmd-V). Same routing as `FieldAssets`
+     * (one shared document listener: focused field wins; a bare paste with no focus
+     * goes to the only pasteable field on the page). A paste replaces. No-op without
+     * `processAsset`.
+     */
+    pasteable?: boolean;
+    /** Tile shape. `circle` for avatars, `wide` (16:9) for banners / logos. Default `square`. */
+    shape?: FieldSingleAssetShape;
+    /** `cover` crops to fill, `contain` letterboxes on a neutral background (logos). Default `cover`. */
+    fit?: FieldSingleAssetFit;
+    /** Tile height: a preset (`5rem` / `8rem` / `12rem`) or any CSS length. Default `md`. */
+    size?: FieldSingleAssetSize | string;
+    /** What the empty tile shows instead of the default icon (e.g. an `Avatar` with initials). */
+    placeholder?: THC;
+    /** Hide the "Preview" action (the `AssetsPreview` lightbox). */
+    noPreview?: boolean;
+    /** Hide the lightbox's Download button. */
+    noDownload?: boolean;
+    /** See `AssetsPreview.onDownload`: replaces the default download of `url.original`. */
+    onDownload?: (asset: FieldAsset) => void | Promise<void>;
+    /** After every user-driven change of `value` (upload settled, remove, undo). */
+    onChange?: (asset: FieldAsset | null) => void;
+}
+declare const FieldSingleAsset: import("svelte").Component<Props, {
+    validate: () => ValidationResult | undefined;
+    clearValidation: () => void;
+    getValidation: () => ValidationResult | undefined;
+    focus: () => void;
+    scrollIntoView: (opts?: ScrollIntoViewOptions) => void;
+    openFilePicker: () => void;
+}, "value">;
+type FieldSingleAsset = ReturnType<typeof FieldSingleAsset>;
+export default FieldSingleAsset;