@marianmeres/stuic 3.133.0 → 3.135.0

package/dist/components/AssetsPreview/AssetsPreview.svelte

@@ -37,6 +37,13 @@
 				close: () => void;
 			}
 		) => void;
+		/**
+		 * Optional consumer-supplied download handler. When provided, the Download button
+		 * calls this instead of `forceDownload(asset.url.original)` — for auth-gated bytes
+		 * or lazy fetching. Receives the current asset + its index. May be async; the
+		 * button shows a busy/disabled state while the returned promise settles.
+		 */
+		onDownload?: (asset: AssetPreview, index: number) => void | Promise<void>;
 		/** optional "do not display file name" switch flag */
 		noName?: boolean;
 		/** When true (default), panning is clamped to keep image within bounds */
@@ -74,6 +81,7 @@
 		t = t_default,
 		classControls = "",
 		onDelete,
+		onDownload,
 		onAreaClick,
 		noName,
 		clampPan = false,
@@ -185,6 +193,7 @@
 			{classControls}
 			{t}
 			{onDelete}
+			{onDownload}
 			{noName}
 			{clampPan}
 			{noDownload}

package/dist/components/AssetsPreview/AssetsPreview.svelte.d.ts

@@ -16,6 +16,13 @@ export interface Props {
     onDelete?: (asset: AssetPreview, index: number, controls: {
         close: () => void;
     }) => void;
+    /**
+     * Optional consumer-supplied download handler. When provided, the Download button
+     * calls this instead of `forceDownload(asset.url.original)` — for auth-gated bytes
+     * or lazy fetching. Receives the current asset + its index. May be async; the
+     * button shows a busy/disabled state while the returned promise settles.
+     */
+    onDownload?: (asset: AssetPreview, index: number) => void | Promise<void>;
     /** optional "do not display file name" switch flag */
     noName?: boolean;
     /** When true (default), panning is clamped to keep image within bounds */

package/dist/components/AssetsPreview/AssetsPreviewInline.svelte

@@ -22,6 +22,13 @@
 				close: () => void;
 			}
 		) => void;
+		/**
+		 * Optional consumer-supplied download handler. When provided, the Download button
+		 * calls this instead of `forceDownload(asset.url.original)` — for auth-gated bytes
+		 * or lazy fetching. Receives the current asset + its index. May be async; the
+		 * button shows a busy/disabled state while the returned promise settles.
+		 */
+		onDownload?: (asset: AssetPreview, index: number) => void | Promise<void>;
 		/** optional "do not display file name" switch flag */
 		noName?: boolean;
 		/** When true (default), panning is clamped to keep image within bounds */
@@ -65,6 +72,7 @@
 		class: classProp = "",
 		classControls = "",
 		onDelete,
+		onDownload,
 		onAreaClick,
 		noName,
 		clampPan = false,
@@ -154,6 +162,7 @@
 			{classControls}
 			{t}
 			{onDelete}
+			{onDownload}
 			{noName}
 			{clampPan}
 			{noDownload}

package/dist/components/AssetsPreview/AssetsPreviewInline.svelte.d.ts

@@ -12,6 +12,13 @@ export interface Props {
     onDelete?: (asset: AssetPreview, index: number, controls: {
         close: () => void;
     }) => void;
+    /**
+     * Optional consumer-supplied download handler. When provided, the Download button
+     * calls this instead of `forceDownload(asset.url.original)` — for auth-gated bytes
+     * or lazy fetching. Receives the current asset + its index. May be async; the
+     * button shows a busy/disabled state while the returned promise settles.
+     */
+    onDownload?: (asset: AssetPreview, index: number) => void | Promise<void>;
     /** optional "do not display file name" switch flag */
     noName?: boolean;
     /** When true (default), panning is clamped to keep image within bounds */

package/dist/components/AssetsPreview/README.md

@@ -4,13 +4,14 @@ A modal-based asset preview component for displaying images and files. Supports
 
 ## Props
 
-| Prop             | Type                         | Default  | Description                       |
-| ---------------- | ---------------------------- | -------- | --------------------------------- |
-| `assets`         | `string[] \| AssetPreview[]` | -        | Array of assets to preview        |
-| `classControls`  | `string`                     | -        | CSS for control buttons           |
-| `t`              | `TranslateFn`                | built-in | Translation function for i18n     |
-| `onDelete`       | `(asset, index) => void`     | -        | Optional delete handler           |
-| `prevNextBottom` | `boolean`                    | `false`  | Render prev/next arrows at bottom |
+| Prop             | Type                                      | Default  | Description                                                                                                            |
+| ---------------- | ----------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `assets`         | `string[] \| AssetPreview[]`              | -        | Array of assets to preview                                                                                             |
+| `classControls`  | `string`                                  | -        | CSS for control buttons                                                                                                |
+| `t`              | `TranslateFn`                             | built-in | Translation function for i18n                                                                                          |
+| `onDelete`       | `(asset, index) => void`                  | -        | Optional delete handler                                                                                                |
+| `onDownload`     | `(asset, index) => void \| Promise<void>` | -        | Optional download handler. Replaces the default `forceDownload(url.original)` — for auth-gated or lazily-fetched bytes |
+| `prevNextBottom` | `boolean`                                 | `false`  | Render prev/next arrows at bottom                                                                                      |
 
 ## Types
 
@@ -140,6 +141,46 @@ interface AssetPreview {
 <AssetsPreview bind:this={preview} {assets} onDelete={handleDelete} />
 ```
 
+### With a Custom Download Handler
+
+By default the Download button calls the built-in `forceDownload(asset.url.original)`,
+which does a plain unauthenticated `fetch`. Supply `onDownload` to take over the action —
+e.g. to fetch **auth-gated** bytes (a `Authorization: Bearer …` route), or to fetch
+**lazily** only when the user actually clicks Download instead of pre-resolving an object
+URL for every asset up front. When provided, the default path is skipped entirely.
+
+The handler may be async; while the returned promise is pending the button shows a busy
+spinner and is disabled (so rapid clicks can't fire duplicate fetches). Rejections are
+caught and logged, so a failed download never breaks the preview.
+
+```svelte
+<script lang="ts">
+	import { AssetsPreview, type AssetPreview } from "stuic";
+
+	let preview: AssetsPreview;
+
+	async function handleDownload(asset: AssetPreview) {
+		// Fetch the bytes yourself (e.g. with an auth header), then save them.
+		const res = await fetch(String(asset.url.original), {
+			headers: { Authorization: `Bearer ${token}` },
+		});
+		const objUrl = URL.createObjectURL(await res.blob());
+		const a = document.createElement("a");
+		a.href = objUrl;
+		a.download = asset.name || "download";
+		document.body.appendChild(a);
+		a.click();
+		a.remove();
+		setTimeout(() => URL.revokeObjectURL(objUrl), 10_000);
+	}
+</script>
+
+<AssetsPreview bind:this={preview} {assets} onDownload={handleDownload} />
+```
+
+> Visibility of the Download button is still controlled solely by `noDownload` —
+> `onDownload` only changes _what_ the button does, not _whether_ it shows.
+
 ### With Custom Translations
 
 ```svelte

package/dist/components/AssetsPreview/_internal/AssetsPreviewContent.svelte

@@ -55,6 +55,13 @@
 				close: () => void;
 			}
 		) => void;
+		/**
+		 * Optional consumer-supplied download handler. When provided, the Download button
+		 * calls this instead of `forceDownload(asset.url.original)` — for auth-gated bytes
+		 * or lazy fetching. Receives the current preview asset + its index. May be async;
+		 * the button shows a busy/disabled state while the returned promise settles.
+		 */
+		onDownload?: (asset: AssetPreview, index: number) => void | Promise<void>;
 		/** Callback when a clickable area on an image is clicked */
 		onAreaClick?: (data: { area: AssetArea; asset: AssetPreviewNormalized }) => void;
 		onClose?: () => void;
@@ -81,11 +88,37 @@
 		classControls = "",
 		t = t_default,
 		onDelete,
+		onDownload,
 		onAreaClick,
 		onClose,
 		slideDuration = 300,
 	}: Props = $props();
 
+	// Busy state for an async `onDownload`; disables the button + shows a spinner so
+	// rapid clicks can't fire duplicate (possibly authed) fetches. Only the custom
+	// path drives this — the default `forceDownload` path is left exactly as-is.
+	let downloading = $state(false);
+
+	async function handleDownload() {
+		if (typeof onDownload === "function") {
+			try {
+				downloading = true;
+				await onDownload(previewAsset, previewIdx);
+			} catch (e) {
+				// A failed/late download must never reject up and tear down the preview.
+				clog.error("onDownload failed", e);
+			} finally {
+				downloading = false;
+			}
+			return;
+		}
+		// Default (unchanged): fetch the original bytes and force a browser download.
+		forceDownload(
+			resolveUrl(String(previewAsset.url.original), baseUrl),
+			previewAsset?.name || ""
+		);
+	}
+
 	let dotTooltip: string | undefined = $state();
 
 	// Zoom state
@@ -747,12 +780,12 @@
 				<Button
 					class={twMerge(BUTTON_CLS, classControls)}
 					type="button"
+					disabled={downloading}
+					spinner={downloading}
+					spinnerOnly
 					onclick={(e) => {
 						e.preventDefault();
-						forceDownload(
-							resolveUrl(String(previewAsset.url.original), baseUrl),
-							previewAsset?.name || ""
-						);
+						handleDownload();
 					}}
 					aria-label={t("download")}
 					tooltip={t("download")}

package/dist/components/AssetsPreview/_internal/AssetsPreviewContent.svelte.d.ts

@@ -26,6 +26,13 @@ interface Props {
     onDelete?: (asset: AssetPreview, index: number, controls: {
         close: () => void;
     }) => void;
+    /**
+     * Optional consumer-supplied download handler. When provided, the Download button
+     * calls this instead of `forceDownload(asset.url.original)` — for auth-gated bytes
+     * or lazy fetching. Receives the current preview asset + its index. May be async;
+     * the button shows a busy/disabled state while the returned promise settles.
+     */
+    onDownload?: (asset: AssetPreview, index: number) => void | Promise<void>;
     /** Callback when a clickable area on an image is clicked */
     onAreaClick?: (data: {
         area: AssetArea;

package/dist/components/Avatar/Avatar.svelte

@@ -1,10 +1,7 @@
 <script lang="ts" module>
 	export type IconFn = (opts?: { size?: number; class?: string }) => string;
 	export type AvatarFallback =
-		| "icon"
-		| "initials"
-		| { icon: IconFn }
-		| { initials: string };
+		"icon" | "initials" | { icon: IconFn } | { initials: string };
 
 	export interface Props {
 		/** Photo URL - when provided, renders in photo mode */

package/dist/components/Input/FieldAssets.svelte

@@ -163,6 +163,13 @@
 		t?: TranslateFn;
 		parseValue?: (strigifiedModels: string) => FieldAsset[];
 		serializeValue?: (assets: FieldAsset[]) => string;
+		/**
+		 * See AssetsPreview.onDownload. When provided, the preview's Download button calls
+		 * this instead of `forceDownload(asset.url.original)` — for auth-gated bytes or
+		 * lazy fetching. Receives the full `FieldAsset` (incl. `_raw`) for the clicked
+		 * asset + its index. May be async; the button shows a busy state while it settles.
+		 */
+		onDownload?: (asset: FieldAsset, index: number) => void | Promise<void>;
 		notifications?: NotificationsStack;
 		cardinality?: number;
 		accept?: string;
@@ -180,6 +187,15 @@
 		 * reserved for file drops); full keyboard + aria-live announcements. Default `false`.
 		 */
 		ordered?: boolean;
+		/**
+		 * Opt-in: allow pasting image/file data from the clipboard (Ctrl/Cmd-V) into
+		 * the field. Focus-scoped — the paste is consumed only while the field (or a
+		 * control inside it) holds focus; clicking anywhere in the field focuses it,
+		 * so no Tab is needed. Routed through the same validation + upload path as
+		 * drag and the file picker, so `accept`, `cardinality` and `processAssets`
+		 * all apply. No-op unless `processAssets` is provided. Default `false`.
+		 */
+		pasteable?: boolean;
 		//
 		classWrap?: string;
 	}
@@ -245,6 +261,7 @@
 		classControls = "",
 		isLoading = false,
 		ordered = false,
+		pasteable = false,
 		parseValue = (strigifiedModels: string) => {
 			const val = strigifiedModels ?? "[]";
 			try {
@@ -255,6 +272,7 @@
 			}
 		},
 		serializeValue = JSON.stringify,
+		onDownload,
 		classWrap = "",
 		// ...rest
 	}: Props = $props();
@@ -272,6 +290,10 @@
 	let inputEl = $state<HTMLInputElement>()!;
 	// Outer wrapper for scrollIntoView and focus targeting.
 	let wrapEl: HTMLDivElement | undefined = $state();
+	// The asset grid container, which lives INSIDE InputWrap's `.input-wrap` box.
+	// `focusForPaste` focuses this (not `wrapEl`, an ancestor) so the `:focus-within`
+	// ring on `.input-wrap` actually lights up on click.
+	let gridEl: HTMLDivElement | undefined = $state();
 	let hiddenInputEl: HTMLInputElement | undefined = $state();
 	let assetsPreview: AssetsPreview = $state()!;
 
@@ -404,6 +426,160 @@
 		focusMovedButton(to, to < from ? "prev" : "next");
 	}
 
+	// Funnels every file source (drop, picker, paste) through one path so they all
+	// share the same accept/cardinality checks, optimistic tiles and processAssets
+	// upload. Accepts a plain File[] too (paste builds one); the spread normalizes
+	// both it and a FileList.
+	function handleIncomingFiles(files: FileList | File[] | null, wasDrop = false) {
+		clog.debug(`processFiles`, wasDrop ? "[DROPPED]" : "", files);
+
+		// Copy the File objects into a stable array, then IMMEDIATELY release the
+		// hidden <input type="file">'s retained FileList. A native file input
+		// keeps its FileList after a selection until it is reset (form reset or
+		// `value = ""`), and its `change` event (wired by the `fileDropzone`
+		// action) calls back into this handler. Without this reset, any later
+		// stray `change` re-runs this with the SAME file still in `inputEl.files`,
+		// pushing a duplicate optimistic asset and firing a real re-upload.
+		// `onSubmitValidityCheck` used to dispatch exactly such a synthetic
+		// `change` on submit (now fixed there too — belt and braces). Clearing
+		// also restores the ability to re-select the same file twice in a row (an
+		// unchanged value emits no `change`). The blob URLs we create below are
+		// independent of the input, so clearing here is safe.
+		const incoming = [...(files ?? [])];
+		if (inputEl) inputEl.value = "";
+
+		// Nothing to consume — a cancelled picker, or a stray/synthetic `change`
+		// on an already-cleared input. Bail before touching state or calling
+		// processAssets (which would otherwise run with an empty batch).
+		if (!incoming.length) return;
+
+		if (accept && incoming.some((f) => !is_accepted_type(accept, f.type))) {
+			const msg = t("invalid_type", { accept });
+			if (notifications) notifications.error(msg);
+			else alert(msg);
+			return;
+		}
+
+		const cardErrMsg = t("cardinality_reached", { max: cardinality });
+		// `>=` (not `>`): refuse the moment the field already holds `cardinality`
+		// assets, instead of optimistically adding one past the limit and relying
+		// on the validator to reject it afterwards (the off-by-one that made the
+		// single-cardinality symptom loud).
+		if (assets.length >= cardinality) {
+			if (notifications) notifications.error(cardErrMsg);
+			else alert(cardErrMsg);
+			return;
+		}
+
+		const toBeProcessed: FieldAsset[] = [];
+
+		for (const file of incoming) {
+			if (assets.length >= cardinality) {
+				notifications ? notifications.error(cardErrMsg) : alert(cardErrMsg);
+				break;
+			}
+
+			// this create a unique blob url, which we'll use as id as well
+			const url = URL.createObjectURL(file);
+			const asset: FieldAsset = {
+				id: url,
+				url: { thumb: url, full: url, original: url },
+				type: file.type,
+				name: file.name,
+				meta: { isUploading: true },
+			};
+
+			// ASAP optimistic UI update
+			assets.push(asset);
+
+			// prepare data for server upload
+			toBeProcessed.push(asset);
+		}
+		value = serializeValue(assets);
+
+		if (typeof processAssets === "function") {
+			isUploading = true;
+			processAssets(toBeProcessed, onProgress)
+				.then((uploaded: FieldAssetWithBlobUrl[]) => {
+					// clog("uploaded", uploaded);
+					for (const ass of uploaded ?? []) {
+						ass.meta ??= {};
+						ass.meta.isUploading = false;
+						if (ass.blobUrl) {
+							const idx = assets.findIndex((a) => a.id === ass.blobUrl);
+							if (idx > -1) {
+								ass.meta ??= {};
+								ass.meta.isUploading = false;
+								assets[idx] = ass;
+							} else {
+								clog.error(`Asset idx ${idx} not found?!?`, ass);
+							}
+						} else {
+							clog.warn(`Missing blobUrl in`, ass);
+						}
+					}
+					value = serializeValue(assets);
+				})
+				.catch((e) => notifications?.error(`${e}`))
+				.finally(() => (isUploading = false));
+		}
+	}
+
+	// --- Clipboard paste (opt-in via `pasteable`) -------------------------------
+	// Focus-scoped: the paste listener lives on the field wrapper, so it only fires
+	// while the field (or a control inside it) holds focus. `focusForPaste` focuses
+	// the wrapper on any click within it, so a click + Ctrl/Cmd-V works with no Tab.
+	// Pasted files go through `handleIncomingFiles`, inheriting accept/cardinality
+	// validation and the processAssets upload — no synthetic `change` event.
+	function extractClipboardFiles(e: ClipboardEvent): File[] {
+		const dt = e.clipboardData;
+		if (!dt) return [];
+		const out: File[] = [];
+		// Prefer items (lets us keep only file-kind entries, e.g. a pasted
+		// screenshot); fall back to `.files` for browsers that only populate that.
+		for (let i = 0; i < (dt.items?.length ?? 0); i++) {
+			const it = dt.items[i];
+			if (it?.kind === "file") {
+				const f = it.getAsFile();
+				if (f) out.push(f);
+			}
+		}
+		if (!out.length && dt.files?.length) out.push(...dt.files);
+		return out;
+	}
+
+	function handlePaste(e: ClipboardEvent) {
+		if (!pasteable || typeof processAssets !== "function") return;
+		const files = extractClipboardFiles(e);
+		if (!files.length) return; // let plain-text pastes etc. pass through
+		e.preventDefault();
+		handleIncomingFiles(files);
+	}
+
+	// Focus the wrapper on any click inside it so a following paste lands here.
+	// Capture phase: fires even though the inner thumbnail/control buttons
+	// stopPropagation, and even in browsers that don't focus <button> on click
+	// (Safari/Firefox on macOS). Skipped when focus is already inside the field —
+	// paste bubbles from any focused descendant anyway.
+	function focusForPaste() {
+		if (!pasteable || !wrapEl) return;
+		if (wrapEl.contains(document.activeElement)) return;
+		// Focus a node INSIDE `.input-wrap` (the grid) so its `:focus-within` ring
+		// shows; fall back to the wrapper when the grid isn't mounted (loading).
+		(gridEl ?? wrapEl).focus({ preventScroll: true });
+	}
+
+	$effect(() => {
+		if (!pasteable || !wrapEl) return;
+		const el = wrapEl;
+		el.addEventListener("paste", handlePaste);
+		el.addEventListener("click", focusForPaste, true);
+		return () => {
+			el.removeEventListener("paste", handlePaste);
+			el.removeEventListener("click", focusForPaste, true);
+		};
+	});
+
 	onDestroy(() => {
 		try {
 			assets.forEach((a) => {
@@ -429,7 +605,11 @@
 			<!-- screen-reader announcements for reorder actions -->
 			<div class="sr-only" aria-live="polite" aria-atomic="true">{liveAnnouncement}</div>
 		{/if}
-		<div class={["p-2 flex items-center gap-0.5 flex-wrap"]}>
+		<div
+			class="p-2 flex items-center gap-0.5 flex-wrap w-full focus:outline-none"
+			bind:this={gridEl}
+			tabindex="-1"
+		>
 			{#each assets as asset, idx (asset.id)}
 				{@const { thumb, full, original } = asset_urls(asset)}
 				{@const _is_img = isImage(asset.type ?? thumb)}
@@ -563,100 +743,7 @@
 	use:fileDropzone={() => ({
 		enabled: typeof processAssets === "function",
 		inputEl,
-		processFiles(files: FileList | null, wasDrop?: boolean) {
-			clog.debug(`processFiles`, wasDrop ? "[DROPPED]" : "", files);
-
-			// Copy the File objects into a stable array, then IMMEDIATELY release the
-			// hidden <input type="file">'s retained FileList. A native file input
-			// keeps its FileList after a selection until it is reset (form reset or
-			// `value = ""`), and its `change` event (wired by the `fileDropzone`
-			// action) calls back into this handler. Without this reset, any later
-			// stray `change` re-runs processFiles with the SAME file still in
-			// `inputEl.files`, pushing a duplicate optimistic asset and firing a real
-			// re-upload. `onSubmitValidityCheck` used to dispatch exactly such a
-			// synthetic `change` on submit (now fixed there too — belt and braces).
-			// Clearing also restores the ability to re-select the same file twice in
-			// a row (an unchanged value emits no `change`). The blob URLs we create
-			// below are independent of the input, so clearing here is safe.
-			const incoming = [...(files ?? [])];
-			if (inputEl) inputEl.value = "";
-
-			// Nothing to consume — a cancelled picker, or a stray/synthetic `change`
-			// on an already-cleared input. Bail before touching state or calling
-			// processAssets (which would otherwise run with an empty batch).
-			if (!incoming.length) return;
-
-			if (accept && incoming.some((f) => !is_accepted_type(accept, f.type))) {
-				const msg = t("invalid_type", { accept });
-				if (notifications) notifications.error(msg);
-				else alert(msg);
-				return;
-			}
-
-			const cardErrMsg = t("cardinality_reached", { max: cardinality });
-			// `>=` (not `>`): refuse the moment the field already holds `cardinality`
-			// assets, instead of optimistically adding one past the limit and relying
-			// on the validator to reject it afterwards (the off-by-one that made the
-			// single-cardinality symptom loud).
-			if (assets.length >= cardinality) {
-				if (notifications) notifications.error(cardErrMsg);
-				else alert(cardErrMsg);
-				return;
-			}
-
-			const toBeProcessed: FieldAsset[] = [];
-
-			for (const file of incoming) {
-				if (assets.length >= cardinality) {
-					notifications ? notifications.error(cardErrMsg) : alert(cardErrMsg);
-					break;
-				}
-
-				// this create a unique blob url, which we'll use as id as well
-				const url = URL.createObjectURL(file);
-				const asset: FieldAsset = {
-					id: url,
-					url: { thumb: url, full: url, original: url },
-					type: file.type,
-					name: file.name,
-					meta: { isUploading: true },
-				};
-
-				// ASAP optimistic UI update
-				assets.push(asset);
-
-				// prepare data for server upload
-				toBeProcessed.push(asset);
-			}
-			value = serializeValue(assets);
-
-			if (typeof processAssets === "function") {
-				isUploading = true;
-				processAssets(toBeProcessed, onProgress)
-					.then((uploaded: FieldAssetWithBlobUrl[]) => {
-						// clog("uploaded", uploaded);
-						for (const ass of uploaded ?? []) {
-							ass.meta ??= {};
-							ass.meta.isUploading = false;
-							if (ass.blobUrl) {
-								const idx = assets.findIndex((a) => a.id === ass.blobUrl);
-								if (idx > -1) {
-									ass.meta ??= {};
-									ass.meta.isUploading = false;
-									assets[idx] = ass;
-								} else {
-									clog.error(`Asset idx ${idx} not found?!?`, ass);
-								}
-							} else {
-								clog.warn(`Missing blobUrl in`, ass);
-							}
-						}
-						value = serializeValue(assets);
-					})
-					.catch((e) => notifications?.error(`${e}`))
-					.finally(() => (isUploading = false));
-			}
-		},
+		processFiles: handleIncomingFiles,
 		allowClick: !assets?.length,
 	})}
 >
@@ -676,7 +763,11 @@
 		{classLabel}
 		{classLabelBox}
 		{classInputBox}
-		{classInputBoxWrap}
+		classInputBoxWrap={twMerge(
+			pasteable &&
+				"focus-within:outline-2 focus-within:outline-offset-2 focus-within:outline-(--stuic-color-ring)",
+			classInputBoxWrap
+		)}
 		{classInputBoxWrapInvalid}
 		{classDescBox}
 		{classDescBoxToggle}
@@ -718,4 +809,7 @@
 	onDelete={(_, index) => {
 		remove_by_idx(index);
 	}}
+	onDownload={onDownload
+		? (_previewAsset, idx) => onDownload(assets[idx], idx)
+		: undefined}
 />

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

@@ -54,6 +54,13 @@ export interface Props extends InputWrapClassProps, Record<string, any> {
     t?: TranslateFn;
     parseValue?: (strigifiedModels: string) => FieldAsset[];
     serializeValue?: (assets: FieldAsset[]) => string;
+    /**
+     * See AssetsPreview.onDownload. When provided, the preview's Download button calls
+     * this instead of `forceDownload(asset.url.original)` — for auth-gated bytes or
+     * lazy fetching. Receives the full `FieldAsset` (incl. `_raw`) for the clicked
+     * asset + its index. May be async; the button shows a busy state while it settles.
+     */
+    onDownload?: (asset: FieldAsset, index: number) => void | Promise<void>;
     notifications?: NotificationsStack;
     cardinality?: number;
     accept?: string;
@@ -68,6 +75,15 @@ export interface Props extends InputWrapClassProps, Record<string, any> {
      * reserved for file drops); full keyboard + aria-live announcements. Default `false`.
      */
     ordered?: boolean;
+    /**
+     * Opt-in: allow pasting image/file data from the clipboard (Ctrl/Cmd-V) into
+     * the field. Focus-scoped — the paste is consumed only while the field (or a
+     * control inside it) holds focus; clicking anywhere in the field focuses it,
+     * so no Tab is needed. Routed through the same validation + upload path as
+     * drag and the file picker, so `accept`, `cardinality` and `processAssets`
+     * all apply. No-op unless `processAssets` is provided. Default `false`.
+     */
+    pasteable?: boolean;
     classWrap?: string;
 }
 declare const FieldAssets: import("svelte").Component<Props, {

package/dist/components/Input/README.md

@@ -475,9 +475,29 @@ on submit (and round-trips on reopen). Single-select fields ignore the prop.
 ## FieldAssets
 
 Asset/image upload field with an inline thumbnail grid and a built-in lightbox preview
-(`AssetsPreview`). Files are added via the picker button or by dragging them onto the
-field; each shows as a thumbnail with its filename (and an upload progress indicator while
-processing).
+(`AssetsPreview`). Files are added via the picker button, by dragging them onto the field,
+or (opt-in) by pasting from the clipboard; each shows as a thumbnail with its filename (and
+an upload progress indicator while processing).
+
+### Paste from the clipboard (`pasteable`)
+
+Opt in with `pasteable` to let users paste image/file data from the clipboard (Ctrl/Cmd-V) —
+a screenshot, a copied image, etc. It is **focus-scoped**: a paste is consumed only while the
+field (or a control inside it) holds focus. Clicking anywhere in the field focuses it, so no
+Tab is needed, and a `:focus-within` ring on the input box signals the paste-ready state.
+Pasted files go through the same path as the picker and drag-and-drop, so `accept`,
+`cardinality` and `processAssets` all apply. No-op unless `processAssets` is provided.
+
+```svelte
+<FieldAssets
+	label="Screenshots"
+	name="screenshots"
+	bind:value
+	{processAssets}
+	accept="image/*"
+	pasteable
+/>
+```
 
 ### Ordering the assets (`ordered`)
 
@@ -497,6 +517,42 @@ announcements. The chosen order is serialized to `value`.
 />
 ```
 
+### Lazy / auth-gated download (`onDownload`)
+
+By default the preview's **Download** button fetches `asset.url.original` with a plain
+unauthenticated request. When the bytes live behind an authenticated route (a Bearer
+token, a signed request, …), or you'd rather fetch them **only on download-click** instead
+of pre-resolving an object URL for every asset up front, pass `onDownload`. It receives the
+full `FieldAsset` (including `_raw`, so you can recover your own model id) plus its index,
+and replaces the default download entirely. It may be async — the button shows a busy state
+until it settles, and a rejection is caught so a failed download never breaks the preview.
+
+```svelte
+<FieldAssets
+	label="Attachments"
+	name="attachments"
+	bind:value
+	{processAssets}
+	onDownload={async (asset) => {
+		const id = (asset._raw as { model_id: string }).model_id;
+		const res = await fetch(`/todo/attachment/${id}`, {
+			headers: { Authorization: `Bearer ${token}` },
+		});
+		const objUrl = URL.createObjectURL(await res.blob());
+		const a = document.createElement("a");
+		a.href = objUrl;
+		a.download = asset.name || "download";
+		document.body.appendChild(a);
+		a.click();
+		a.remove();
+		setTimeout(() => URL.revokeObjectURL(objUrl), 10_000);
+	}}
+/>
+```
+
+> With this, non-image attachments need **no** pre-fetched object URL at all — they render
+> as a file icon and only fetch bytes when the user actually clicks Download.
+
 ---
 
 ## Honeypot & TimeTrap (anti-bot primitives)

package/dist/components/Nav/README.md

@@ -282,9 +282,7 @@ Note: in icon-only sidebar mode (`isCollapsed`), the section title is visually h
 	import { Nav } from "stuic";
 	import { page } from "$app/stores";
 
-	const groups = [
-		/* ... */
-	];
+	const groups = [/* ... */];
 </script>
 
 <Nav

package/dist/components/Thc/Thc.svelte

@@ -57,12 +57,7 @@
 	 * ```
 	 */
 	export type THC =
-		| string
-		| WithText
-		| WithHtml
-		| WithComponent
-		| WithSnippet
-		| AsSnippet;
+		string | WithText | WithHtml | WithComponent | WithSnippet | AsSnippet;
 
 	export interface Props extends Record<string, any> {
 		thc: THC;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/stuic",
-	"version": "3.133.0",
+	"version": "3.135.0",
 	"packageManager": "pnpm@11.5.0",
 	"scripts": {
 		"dev": "vite dev",