@marianmeres/stuic 3.133.0 → 3.134.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;
@@ -255,6 +262,7 @@
 			}
 		},
 		serializeValue = JSON.stringify,
+		onDownload,
 		classWrap = "",
 		// ...rest
 	}: Props = $props();
@@ -718,4 +726,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;

package/dist/components/Input/README.md

@@ -497,6 +497,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.134.0",
 	"packageManager": "pnpm@11.5.0",
 	"scripts": {
 		"dev": "vite dev",