@marianmeres/stuic 3.132.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 */