@marianmeres/stuic 3.183.0 → 3.184.0

package/dist/components/Input/FieldSingleAsset.svelte

@@ -102,7 +102,8 @@
 		 * 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`.
+		 * an error state on the tile with Retry / Discard, and reports `notifications`
+		 * (see `onUploadError` to take over that report).
 		 * Without it the field is display-only (no picker, no drop, no paste).
 		 */
 		processAsset?: (
@@ -111,6 +112,17 @@
 		) => Promise<FieldAsset>;
 		/** Render a progress ring driven by `ctx.onProgress` instead of a spinner. */
 		withOnProgress?: boolean;
+		/**
+		 * Called when `processAsset` rejects (with the raw rejection, so a status code or
+		 * a custom error class is still inspectable), after the tile has entered its
+		 * error state and before the default `notifications.error(...)` toast. Return
+		 * `false` to skip that toast — for a rejection the page already renders its own
+		 * way (a quota / plan-limit panel). The tile keeps Retry / Discard regardless.
+		 */
+		onUploadError?: (
+			error: unknown,
+			ctx: { asset: FieldAsset; file: File }
+		) => void | 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. */
@@ -133,7 +145,12 @@
 		transformFile?: (
 			file: File
 		) => File | null | undefined | Promise<File | null | undefined>;
-		/** Return `false` (may be async) to keep the asset. */
+		/**
+		 * Return `false` (may be async) to keep the asset. While a returned promise is
+		 * pending the tile is busy: the Remove control shows a spinner, the tile and
+		 * its controls are inert, and a second Remove is a no-op — so the hook may do
+		 * the actual server-side delete and resolve with whether it succeeded.
+		 */
 		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>;
@@ -254,6 +271,7 @@
 		serializeValue = default_serialize,
 		processAsset,
 		withOnProgress = false,
+		onUploadError,
 		accept,
 		capture,
 		maxSize,
@@ -292,6 +310,9 @@
 	let pending = $state<Pending | null>(null);
 	// Bumped on every new upload / discard so a stale promise cannot land.
 	let uploadSeq = 0;
+	// `onBeforeRemove` in flight (it may be the real server-side delete): the tile
+	// is inert and the Remove control shows a spinner until it settles.
+	let removing = $state(false);
 	// The last removed asset while its Undo is still offered.
 	let removed = $state<FieldAsset | null>(null);
 	let undoTimer: ReturnType<typeof setTimeout> | undefined;
@@ -303,7 +324,9 @@
 	let descId = $derived(`${id}-action`);
 
 	let hasLabel = $derived(isTHCNotEmpty(label));
-	let canUpload = $derived(typeof processAsset === "function" && !disabled && !isLoading);
+	let canUpload = $derived(
+		typeof processAsset === "function" && !disabled && !isLoading && !removing
+	);
 	// what the tile shows: the upload in progress wins over the committed asset
 	let shown = $derived(pending?.asset ?? asset);
 	let shownIsImage = $derived(
@@ -312,13 +335,15 @@
 	let tileState = $derived(
 		isLoading
 			? "loading"
-			: pending
-				? pending.error
-					? "error"
-					: "uploading"
-				: asset
-					? "filled"
-					: "empty"
+			: removing
+				? "removing"
+				: pending
+					? pending.error
+						? "error"
+						: "uploading"
+					: asset
+						? "filled"
+						: "empty"
 	);
 	let sizePreset = $derived(SIZE_PRESETS.includes(size) ? size : undefined);
 	let sizeStyle = $derived(
@@ -337,6 +362,7 @@
 	);
 	let metaText = $derived.by(() => {
 		if (!shown) return "";
+		if (removing) return t("removing_short");
 		if (pending) {
 			if (pending.error) return t("upload_failed");
 			const parts = [
@@ -547,7 +573,11 @@
 				if (pending) pending.error = error;
 				const msg = t("upload_failed_named", { name: file.name, error });
 				announce(msg);
-				notifications?.error(msg);
+				// the consumer may own the report (a quota panel it already renders):
+				// `false` skips only the toast, the tile's Retry / Discard stay
+				if (onUploadError?.(e, { asset: optimistic, file }) !== false) {
+					notifications?.error(msg);
+				}
 			});
 	}
 
@@ -566,8 +596,17 @@
 
 	async function remove() {
 		const current = asset;
-		if (!current || disabled || isLoading) return;
-		if (typeof onBeforeRemove === "function" && !(await onBeforeRemove(current))) return;
+		if (!current || disabled || isLoading || removing) return;
+		if (typeof onBeforeRemove === "function") {
+			// busy for the whole round trip (the hook may be the real delete) — the
+			// `removing` guard above is what makes a second click a no-op meanwhile
+			removing = true;
+			try {
+				if (!(await onBeforeRemove(current))) return;
+			} finally {
+				removing = false;
+			}
+		}
 		assetsPreview?.close?.();
 		commit(null);
 		announce(t("removed", { name: current.name }));
@@ -632,20 +671,35 @@
 	});
 </script>
 
-{#snippet control(icon: string, labelText: string, onclick: () => void, action: string)}
+{#snippet control(
+	icon: string,
+	labelText: string,
+	onclick: () => void,
+	action: string,
+	opts: { busy?: boolean; inert?: boolean } = {}
+)}
+	<!-- `aria-disabled` (not `disabled`) so a busy control keeps focus for the
+	     round trip; the click is a no-op meanwhile (`remove()` guards on `removing`) -->
 	<button
 		type="button"
 		class={twMerge("stuic-field-single-asset-control", classControls)}
 		aria-label={labelText}
+		aria-disabled={opts.busy || opts.inert ? "true" : undefined}
+		aria-busy={opts.busy ? "true" : undefined}
 		data-action={action}
 		use:tooltip={() => ({ content: labelText })}
 		onclick={(e) => {
 			e.preventDefault();
 			e.stopPropagation();
+			if (opts.busy || opts.inert) return;
 			onclick();
 		}}
 	>
-		{@html icon}
+		{#if opts.busy}
+			<SpinnerCircleOscillate class="size-4" bgStrokeColor="rgba(255 255 255 / 0.3)" />
+		{:else}
+			{@html icon}
+		{/if}
 	</button>
 {/snippet}
 
@@ -740,7 +794,8 @@
 								iconZoomIn({ size: 16 }),
 								t("preview"),
 								() => assetsPreview.open(0),
-								"preview"
+								"preview",
+								{ inert: removing }
 							)}
 						{/if}
 						{#if pending || !disabled}
@@ -750,9 +805,12 @@
 									? pending.error
 										? t("discard")
 										: t("cancel_upload")
-									: t("remove"),
+									: removing
+										? t("removing_short")
+										: t("remove"),
 								on_x,
-								pending ? "discard" : "remove"
+								pending ? "discard" : "remove",
+								{ busy: removing }
 							)}
 						{/if}
 					</span>

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

@@ -65,12 +65,24 @@ export interface Props extends InputWrapClassProps, Record<string, any> {
      * 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`.
+     * an error state on the tile with Retry / Discard, and reports `notifications`
+     * (see `onUploadError` to take over that report).
      * 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;
+    /**
+     * Called when `processAsset` rejects (with the raw rejection, so a status code or
+     * a custom error class is still inspectable), after the tile has entered its
+     * error state and before the default `notifications.error(...)` toast. Return
+     * `false` to skip that toast — for a rejection the page already renders its own
+     * way (a quota / plan-limit panel). The tile keeps Retry / Discard regardless.
+     */
+    onUploadError?: (error: unknown, ctx: {
+        asset: FieldAsset;
+        file: File;
+    }) => void | 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. */
@@ -89,7 +101,12 @@ export interface Props extends InputWrapClassProps, Record<string, any> {
      * 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. */
+    /**
+     * Return `false` (may be async) to keep the asset. While a returned promise is
+     * pending the tile is busy: the Remove control shows a spinner, the tile and
+     * its controls are inert, and a second Remove is a no-op — so the hook may do
+     * the actual server-side delete and resolve with whether it succeeded.
+     */
     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>;

package/dist/components/Input/README.md

@@ -768,7 +768,9 @@ built around a single tile instead:
 - **The tile is the picker and the drop target.** Click it, drop onto the field, or (opt-in)
   paste — every source _replaces_ what is there. Two files at once are refused.
 - **Remove inline**, with an **Undo** offered for `undoTtl` ms (the asset is only unlinked
-  from `value`, never deleted anywhere, so undo is lossless). Focus returns to the tile.
+  from `value`, never deleted anywhere, so undo is lossless). Focus returns to the tile. An
+  async `onBeforeRemove` gets a busy state for its round trip (spinner on the Remove
+  control, tile inert, second click ignored) — so it may be the real server-side delete.
 - **Shape / fit / size presets**: `shape="circle"` for avatars, `shape="wide"` (16:9) for
   banners, `fit="contain"` for logos that must never be cropped; `size` is `sm` / `md` / `lg`
   (5 / 8 / 12rem tall) or any CSS length.
@@ -776,7 +778,8 @@ built around a single tile instead:
   `withOnProgress`.
 - **Rollback on failure.** `value` is only rewritten when the upload _resolves_. A rejection
   keeps the previous asset, shows the error on the tile with **Retry** (same file) and
-  **Discard**, and reports through `notifications`. X during an upload cancels it (a late
+  **Discard**, and reports through `notifications` — unless `onUploadError` returns `false`
+  because the page shows that failure its own way. X during an upload cancels it (a late
   resolution is ignored).
 - **Client-side checks** before any bytes move: `accept` (also for drops and pastes),
   `maxSize`, a custom async `validateFile`, and a `transformFile` seam for downscaling a
@@ -852,6 +855,54 @@ or `alert` without one):
 one file only → `accept` → `onBeforeReplace` → `transformFile` → `maxSize` → `validateFile`
 → `processAsset`
 
+### When the failure is yours to show (`onUploadError`)
+
+Some rejections are not failures but product states — a 402 "plan limit reached" that the
+page already renders as an upgrade panel. Without a hook the field would stack its generic
+toast on top of that panel. `onUploadError(error, { asset, file })` gets the raw rejection
+first; return `false` to skip the toast. The tile still shows the error with Retry / Discard
+(the user may come back to it after upgrading), so the override is deliberately that narrow:
+
+```svelte
+<script lang="ts">
+	let gated = $state<string | null>(null);
+</script>
+
+{#if gated}
+	<UpgradeNotice message={gated} />
+{/if}
+
+<FieldSingleAsset
+	...
+	onUploadError={(e) => {
+		if ((e as any)?.status === 402) {
+			gated = (e as Error).message;
+			return false; // handled above — no toast
+		}
+	}}
+/>
+```
+
+### Removing the server copy too (`onBeforeRemove`)
+
+By default a remove only unlinks the asset from `value` (hence the lossless Undo). When the
+field owns a file that must go away on the server as well, do the `DELETE` inside
+`onBeforeRemove` and resolve with whether it succeeded — the field clears `value` only then.
+The round trip gets a busy state (spinner on the Remove control, `data-state="removing"`,
+tile and controls inert, a second Remove ignored). Pair it with `undoTtl={0}`: restoring the
+local value would lie about a file that is already gone.
+
+```svelte
+<FieldSingleAsset
+	...
+	undoTtl={0}
+	onBeforeRemove={async (asset) => {
+		const res = await fetch(`/api/logo/${asset.id}`, { method: "DELETE" });
+		return res.ok;
+	}}
+/>
+```
+
 ### Downscale or crop before upload (`transformFile`)
 
 ```svelte
@@ -871,12 +922,13 @@ a dialog and resolves with the cropped file.
 | `name`                                                     | `string`                                               | required           | The hidden input's name                                                 |
 | `processAsset`                                             | `(asset, { file, onProgress }) => Promise<FieldAsset>` | -                  | The upload. Without it the field is display-only                        |
 | `withOnProgress`                                           | `boolean`                                              | `false`            | Progress ring instead of a spinner                                      |
+| `onUploadError`                                            | `(error, { asset, file }) => void \| boolean`          | -                  | On a rejected upload, before the toast; `false` skips the toast         |
 | `accept`                                                   | `string`                                               | -                  | HTML `accept` tokens (MIME, `image/*`, `.pdf`); applied to drops/pastes |
 | `capture`                                                  | `"user" \| "environment"`                              | -                  | Passed to the file input: phones open the camera directly               |
 | `maxSize`                                                  | `number`                                               | -                  | Max bytes, checked after `transformFile`                                |
 | `validateFile`                                             | `(file) => string \| void \| Promise<...>`             | -                  | Non-empty string rejects with that message                              |
 | `transformFile`                                            | `(file) => File \| null \| Promise<...>`               | -                  | Pre-upload hook; `null` cancels                                         |
-| `onBeforeRemove`                                           | `(asset) => boolean \| Promise<boolean>`               | -                  | `false` keeps the asset                                                 |
+| `onBeforeRemove`                                           | `(asset) => boolean \| Promise<boolean>`               | -                  | `false` keeps the asset; busy state while a promise settles             |
 | `onBeforeReplace`                                          | `(current, file) => boolean \| Promise<boolean>`       | -                  | `false` keeps the current asset                                         |
 | `undoTtl`                                                  | `number`                                               | `6000`             | ms the inline Undo stays after a remove; `0` disables                   |
 | `pasteable`                                                | `boolean`                                              | `false`            | Accept Ctrl/Cmd-V (same routing as `FieldAssets`)                       |

package/dist/components/Input/field-single-asset-i18n-sk.js

@@ -23,6 +23,7 @@ export const FIELD_SINGLE_ASSET_MESSAGES_SK = {
     replace_file: "Nahradiť {{name}}",
     empty_hint: "Presuňte sem súbor alebo kliknite a vyberte ho",
     remove: "Odstrániť",
+    removing_short: "Odstraňuje sa…",
     removed: "Súbor {{name}} bol odstránený",
     undo: "Vrátiť späť",
     restored: "Súbor {{name}} bol obnovený",

package/dist/components/Input/field-single-asset-i18n.d.ts

@@ -12,6 +12,7 @@ export declare const FIELD_SINGLE_ASSET_MESSAGES_EN: {
     replace_file: string;
     empty_hint: string;
     remove: string;
+    removing_short: string;
     removed: string;
     undo: string;
     restored: string;

package/dist/components/Input/field-single-asset-i18n.js

@@ -13,6 +13,7 @@ export const FIELD_SINGLE_ASSET_MESSAGES_EN = {
     replace_file: "Replace {{name}}",
     empty_hint: "Drop a file here or click to browse",
     remove: "Remove",
+    removing_short: "Removing…",
     removed: "{{name}} removed",
     undo: "Undo",
     restored: "{{name}} restored",

package/dist/components/Input/index.css

@@ -1645,8 +1645,11 @@
 		outline: 2px solid var(--stuic-color-ring);
 		outline-offset: 2px;
 	}
-	/* the tile is `disabled` while the field only displays — keep it legible */
+	/* the tile is `disabled` while the field only displays (or while an async
+	   `onBeforeRemove` is in flight) — keep it legible */
 	.stuic-field-single-asset[data-state="filled"]
+		.stuic-field-single-asset-preview:disabled,
+	.stuic-field-single-asset[data-state="removing"]
 		.stuic-field-single-asset-preview:disabled {
 		opacity: 1;
 	}
@@ -1699,9 +1702,12 @@
 		transition: opacity
 			var(--stuic-field-single-asset-transition, var(--stuic-transition));
 	}
+	/* pinned open on error (Retry / Discard must not depend on hover) and while a
+	   remove is in flight (the busy spinner lives in the Remove control) */
 	.stuic-field-single-asset-tile:hover .stuic-field-single-asset-actions,
 	.stuic-field-single-asset-tile:focus-within .stuic-field-single-asset-actions,
-	.stuic-field-single-asset[data-state="error"] .stuic-field-single-asset-actions {
+	.stuic-field-single-asset[data-state="error"] .stuic-field-single-asset-actions,
+	.stuic-field-single-asset[data-state="removing"] .stuic-field-single-asset-actions {
 		opacity: 1;
 		pointer-events: auto;
 	}
@@ -1725,9 +1731,16 @@
 		transition: background-color
 			var(--stuic-field-single-asset-transition, var(--stuic-transition));
 	}
-	.stuic-field-single-asset-control:hover {
+	.stuic-field-single-asset-control:hover:not([aria-disabled="true"]) {
 		background: var(--stuic-field-single-asset-control-bg-hover);
 	}
+	/* `aria-disabled`, not `disabled`: a busy control keeps focus for the round trip */
+	.stuic-field-single-asset-control[aria-disabled="true"] {
+		cursor: default;
+	}
+	.stuic-field-single-asset-control[aria-disabled="true"]:not([aria-busy="true"]) {
+		opacity: 0.5;
+	}
 	.stuic-field-single-asset-control:focus-visible {
 		outline: 2px solid var(--stuic-color-ring);
 		outline-offset: 1px;

package/package.json

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