@marianmeres/stuic 3.110.0 → 3.112.0

package/dist/actions/on-submit-validity-check.svelte.js

@@ -61,6 +61,17 @@ export function onSubmitValidityCheck(node) {
                 // input (last radio input), which is not desired
                 if (el.type === "radio")
                     continue;
+                // File inputs: validate WITHOUT re-dispatching events. A synthetic
+                // `change` can't change a file input's value (it's read-only to
+                // script), so it adds nothing for validation — but it DOES re-trigger
+                // any dropzone/upload listener bound to the input. `FieldAssets`'
+                // hidden `<input type="file">` is exactly such a listener (wired via
+                // the `fileDropzone` action): re-firing `change` re-runs its
+                // `processFiles` with the file still sitting in `inputEl.files`,
+                // pushing a duplicate optimistic asset and kicking off a real
+                // re-upload on every submit. We still read `el.validity` below, so
+                // native `required` file inputs are honored as before.
+                const isFile = el.type === "file";
                 // // [debug] kept commented for the next time Issue A regresses
                 // // eslint-disable-next-line no-console
                 // console.log(`[onSubmitValidityCheck] el#${i} ${el.name || el.type} BEFORE`, {
@@ -80,10 +91,12 @@ export function onSubmitValidityCheck(node) {
                 // error, silently routing the form to `submit_invalid` and never calling
                 // the consumer's onSubmit. The dispatched change event below re-runs the
                 // per-field validator which re-applies a real customValidity if needed.
-                if (typeof el.setCustomValidity === "function")
-                    el.setCustomValidity("");
-                el.dispatchEvent(new Event("input", { bubbles: true }));
-                el.dispatchEvent(new Event("change", { bubbles: true }));
+                if (!isFile) {
+                    if (typeof el.setCustomValidity === "function")
+                        el.setCustomValidity("");
+                    el.dispatchEvent(new Event("input", { bubbles: true }));
+                    el.dispatchEvent(new Event("change", { bubbles: true }));
+                }
                 // // [debug] kept commented for the next time Issue A regresses
                 // // eslint-disable-next-line no-console
                 // console.log(`[onSubmitValidityCheck] el#${i} ${el.name || el.type} AFTER `, {

package/dist/components/Input/FieldAssets.svelte

@@ -453,7 +453,27 @@
 		processFiles(files: FileList | null, wasDrop?: boolean) {
 			clog.debug(`processFiles`, wasDrop ? "[DROPPED]" : "", files);
 
-			if (accept && [...(files ?? [])].some((f) => !is_accepted_type(accept, f.type))) {
+			// 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);
@@ -461,8 +481,11 @@
 			}
 
 			const cardErrMsg = t("cardinality_reached", { max: cardinality });
-			if (assets.length > cardinality) {
-				// if (assets.length + (files?.length ?? 0) > 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;
@@ -470,8 +493,8 @@
 
 			const toBeProcessed: FieldAsset[] = [];
 
-			for (const file of files ?? []) {
-				if (assets.length > cardinality) {
+			for (const file of incoming) {
+				if (assets.length >= cardinality) {
 					notifications ? notifications.error(cardErrMsg) : alert(cardErrMsg);
 					break;
 				}

package/dist/components/MarkdownEditor/MarkdownEditor.svelte

@@ -112,6 +112,23 @@
 		 * (any `window.prompt`-compatible sync/async function works).
 		 */
 		prompt?: PromptFn;
+		/**
+		 * Caps the editing surface height so a long document scrolls *inside* the
+		 * surface instead of growing the editor (which would push the toolbar out
+		 * of view). `number` → pixels; `string` → any CSS length (`"40rem"`,
+		 * `"60vh"`, `"min(40rem,50vh)"`). Defaults to `32rem` (themeable via
+		 * `--stuic-markdown-editor-max-height`). The surface is additionally capped
+		 * to the parent's available height when {@link capToParent} is on — the
+		 * smaller limit wins.
+		 */
+		maxHeight?: number | string;
+		/**
+		 * Also cap the editing surface to the height available in the parent
+		 * container (measured at runtime), so the editor never overflows a
+		 * height-constrained parent. Default `true`. Set `false` to rely solely on
+		 * {@link maxHeight}.
+		 */
+		capToParent?: boolean;
 		/** Show the WYSIWYG/Source mode toggle. Default `true`. */
 		showModeToggle?: boolean;
 		/** Label for the toggle when in WYSIWYG mode (switches to source). */
@@ -165,6 +182,12 @@
 	} from "../../icons/index.js";
 	import InputWrap from "../Input/_internal/InputWrap.svelte";
 	import type { EditorCommands, EditorHandle, PromptFn } from "./_internal/types.js";
+	import {
+		computeParentAvailable,
+		DEFAULT_MAX_HEIGHT_VAR,
+		maxHeightToCss,
+		surfaceMaxHeight,
+	} from "./_internal/max-height.js";
 	import "./index.css";
 
 	// Default URL prompt for link/image — the native `window.prompt`. Opt into
@@ -227,6 +250,8 @@
 		autoSourceOnMobile = true,
 		mobileQuery = "(pointer: coarse) and (max-width: 640px)",
 		prompt = defaultPrompt,
+		maxHeight,
+		capToParent = true,
 		showModeToggle = true,
 		sourceLabel = "Source",
 		previewLabel = "Preview",
@@ -285,6 +310,78 @@
 		input = host;
 	});
 
+	// --- Surface max-height ---------------------------------------------------
+	// Cap the editing surface so a long document scrolls internally instead of
+	// growing the editor (which scrolls the toolbar out of view). The base cap is
+	// the `maxHeight` prop (funneled into the CSS var so the surface rule + the
+	// min() below both see it) or `32rem`; `capToParent` further caps it to the
+	// parent's measured available height. `min()` picks the smaller limit.
+
+	// Funnel an explicit `maxHeight` into the themeable CSS var on the root.
+	const maxHeightVar = $derived.by(() => {
+		const css = maxHeightToCss(maxHeight);
+		return css ? `--stuic-markdown-editor-max-height: ${css};` : undefined;
+	});
+
+	// Measured parent-available height (px), or null when capping is off / not
+	// yet measured / the parent is unconstrained — then the CSS default applies.
+	let parentAvailable = $state<number | null>(null);
+
+	// Inline surface `max-height`; undefined falls back to the CSS rule default.
+	const surfaceMaxHeightCss = $derived(
+		capToParent && parentAvailable != null
+			? surfaceMaxHeight(DEFAULT_MAX_HEIGHT_VAR, parentAvailable)
+			: undefined
+	);
+
+	$effect(() => {
+		if (!capToParent || !host || typeof ResizeObserver === "undefined") {
+			parentAvailable = null;
+			return;
+		}
+		const surface = host;
+		// Measure against the parent of the whole field (InputWrap's root), which
+		// is the consumer's container — that is the "parent" whose height we cap to.
+		const root = (surface.closest(".stuic-input") as HTMLElement | null) ?? surface;
+		const parent = root.parentElement;
+		if (!parent) {
+			parentAvailable = null;
+			return;
+		}
+
+		const measure = () => {
+			const cs = getComputedStyle(parent);
+			const next = computeParentAvailable({
+				fromTop: surface.getBoundingClientRect().top,
+				parentBottom: parent.getBoundingClientRect().bottom,
+				parentBorderBottom: parseFloat(cs.borderBottomWidth) || 0,
+				parentPaddingBottom: parseFloat(cs.paddingBottom) || 0,
+			});
+			// `untrack` the read of `parentAvailable`: the initial measure() runs
+			// inside this effect, and tracking its own output would tear down and
+			// rebuild the observer on every measurement. The threshold also guards
+			// against sub-pixel ResizeObserver feedback loops.
+			const prev = untrack(() => parentAvailable);
+			if (next == null) {
+				if (prev !== null) parentAvailable = null;
+			} else if (prev == null || Math.abs(next - prev) > 1) {
+				parentAvailable = next;
+			}
+		};
+
+		measure();
+		const ro = new ResizeObserver(measure);
+		ro.observe(parent);
+		// Observe the field root too, so the surface re-measures when content above
+		// it reflows (label wraps, description expands, validation message appears).
+		ro.observe(root);
+		window.addEventListener("resize", measure);
+		return () => {
+			ro.disconnect();
+			window.removeEventListener("resize", measure);
+		};
+	});
+
 	// Handle to whichever backend is currently mounted (null while (re)loading).
 	let activeHandle = $state<EditorHandle | undefined>();
 
@@ -464,6 +561,7 @@
 		class:disabled
 		data-size={renderSize}
 		data-mode={mode}
+		style={maxHeightVar}
 	>
 		{#if toolbarItems.length || showModeToggle}
 			<div class={twMerge("stuic-markdown-editor-bar", classToolbar)}>
@@ -511,6 +609,7 @@
 		<div
 			bind:this={host}
 			class="stuic-markdown-editor-surface"
+			style:max-height={surfaceMaxHeightCss}
 			onfocusout={handleFocusOut}
 			role="textbox"
 			aria-multiline="true"

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

@@ -54,6 +54,23 @@ export interface Props extends InputWrapClassProps {
      * (any `window.prompt`-compatible sync/async function works).
      */
     prompt?: PromptFn;
+    /**
+     * Caps the editing surface height so a long document scrolls *inside* the
+     * surface instead of growing the editor (which would push the toolbar out
+     * of view). `number` → pixels; `string` → any CSS length (`"40rem"`,
+     * `"60vh"`, `"min(40rem,50vh)"`). Defaults to `32rem` (themeable via
+     * `--stuic-markdown-editor-max-height`). The surface is additionally capped
+     * to the parent's available height when {@link capToParent} is on — the
+     * smaller limit wins.
+     */
+    maxHeight?: number | string;
+    /**
+     * Also cap the editing surface to the height available in the parent
+     * container (measured at runtime), so the editor never overflows a
+     * height-constrained parent. Default `true`. Set `false` to rely solely on
+     * {@link maxHeight}.
+     */
+    capToParent?: boolean;
     /** Show the WYSIWYG/Source mode toggle. Default `true`. */
     showModeToggle?: boolean;
     /** Label for the toggle when in WYSIWYG mode (switches to source). */

package/dist/components/MarkdownEditor/README.md

@@ -60,6 +60,8 @@ Bind the component instance to access:
 | `validate`       | `boolean \| ValidateOptions` | –           | Pass a `customValidator` to validate markdown                       |
 | `renderSize`     | `"sm" \| "md" \| "lg"`       | `"md"`      |                                                                     |
 | `toolbar`        | `boolean \| ToolbarItem[]`   | `true`      | `true` = default toolbar, `false` = none, or an ordered button list |
+| `maxHeight`      | `number \| string`           | `32rem`     | Surface height cap (`number` = px). Long docs scroll internally     |
+| `capToParent`    | `boolean`                    | `true`      | Also cap the surface to the parent's available height               |
 | `showModeToggle` | `boolean`                    | `true`      | Show the WYSIWYG/source toggle                                      |
 | `name`           | `string`                     | –           | Hidden input name for form submission                               |
 
@@ -95,6 +97,33 @@ Available items: `bold`, `italic`, `heading1`, `heading2`, `heading3`, `link`,
 `hardBreak`, `undo`, `redo`, and `"|"` (separator). The default layout is
 exported as `DEFAULT_TOOLBAR`.
 
+### Height & scrolling
+
+A long document never grows the editor unbounded (which would scroll the toolbar
+out of view). The editing **surface** has a finite max height and scrolls
+internally instead:
+
+- **Fixed cap** — `maxHeight` (`number` → px, or any CSS length string like
+  `"40rem"` / `"60vh"`), defaulting to `32rem` (themeable via
+  `--stuic-markdown-editor-max-height`).
+- **Parent cap** — with `capToParent` on (default), the surface is _also_ capped
+  to the height available in the parent container, measured at runtime. The
+  **smaller** of the two limits wins, so the editor fills — but never overflows —
+  a height-constrained parent (e.g. a flex column, modal body, or split pane).
+
+```svelte
+<!-- explicit fixed cap; ignore the parent -->
+<MarkdownEditor bind:value maxHeight="20rem" capToParent={false} />
+
+<!-- fill a height-constrained pane, scrolling internally past its available height -->
+<div style="height: 60vh; display: flex; flex-direction: column;">
+	<MarkdownEditor bind:value maxHeight="100vh" />
+</div>
+```
+
+The minimum height (`--stuic-markdown-editor-min-height`, `12rem` for `md`) still
+applies, so the surface never collapses below a usable editing area.
+
 ### Link / image URL prompt
 
 By default the link and image buttons ask for a URL via the native
@@ -146,7 +175,7 @@ input/global tokens:
 --stuic-markdown-editor-border-focus
 --stuic-markdown-editor-bg
 --stuic-markdown-editor-min-height  /* default 12rem (9/16rem for sm/lg) */
---stuic-markdown-editor-max-height
+--stuic-markdown-editor-max-height  /* default 32rem; see "Height & scrolling" */
 --stuic-markdown-editor-font-size
 --stuic-markdown-editor-font-mono
 --stuic-markdown-editor-code-bg

package/dist/components/MarkdownEditor/_internal/max-height.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Pure helpers for the MarkdownEditor's editing-surface max-height resolution.
+ *
+ * Deliberately framework-free (no DOM, no Svelte) so the height-capping logic is
+ * unit-testable without a browser/layout engine. `MarkdownEditor.svelte` does the
+ * actual DOM measurement and feeds the resulting numbers through these helpers.
+ */
+/**
+ * Base cap applied to the editing surface, as a CSS expression. Reads the
+ * themeable `--stuic-markdown-editor-max-height` custom property, falling back
+ * to `32rem`. The `32rem` fallback is kept in sync with the same value in
+ * `index.css` (`.stuic-markdown-editor-surface`).
+ */
+export declare const DEFAULT_MAX_HEIGHT_VAR = "var(--stuic-markdown-editor-max-height, 32rem)";
+/**
+ * Normalize a `maxHeight` prop value into a CSS length.
+ * - `number` → pixels (`240` → `"240px"`)
+ * - `string` → used verbatim (any CSS length: `"40rem"`, `"60vh"`, `"min(40rem,50vh)"`)
+ * - `null` / `undefined` / empty / non-finite → `null` (caller uses the default)
+ */
+export declare function maxHeightToCss(value: number | string | null | undefined): string | null;
+/**
+ * Combine the configured cap (`base`, a CSS length/expression) with the measured
+ * parent-available height. When a positive `parentAvailablePx` is given the
+ * surface is capped to the smaller of the two via CSS `min()`, so it never
+ * overflows a height-constrained parent. Otherwise the base cap is returned
+ * unchanged.
+ */
+export declare function surfaceMaxHeight(base: string, parentAvailablePx: number | null): string;
+/** Inputs for {@link computeParentAvailable}, in CSS px (viewport coords for tops/bottoms). */
+export interface ParentAvailableInput {
+    /** Viewport-relative top of the element we measure from (the editing surface). */
+    fromTop: number;
+    /** Viewport-relative bottom of the parent's border box (`getBoundingClientRect().bottom`). */
+    parentBottom: number;
+    /** Parent computed `border-bottom-width` in px. Default `0`. */
+    parentBorderBottom?: number;
+    /** Parent computed `padding-bottom` in px. Default `0`. */
+    parentPaddingBottom?: number;
+    /** Extra breathing room to leave below the editor, in px. Default `0`. */
+    bottomGap?: number;
+}
+/**
+ * Compute the vertical space available to the editor inside its parent: the
+ * distance from `fromTop` down to the bottom of the parent's content box, less
+ * an optional `bottomGap`.
+ *
+ * Returns `null` when the result is not positive — the parent is smaller than
+ * the editor's offset (e.g. not laid out yet), so no meaningful cap can be
+ * derived and the caller should fall back to the configured base.
+ *
+ * Note: in an auto-height (content-sized) parent this naturally returns roughly
+ * the editor's own height, so `surfaceMaxHeight(base, …)` resolves to the base
+ * cap and the parent constraint only bites when the parent is genuinely smaller.
+ */
+export declare function computeParentAvailable(input: ParentAvailableInput): number | null;

package/dist/components/MarkdownEditor/_internal/max-height.js

@@ -0,0 +1,60 @@
+/**
+ * Pure helpers for the MarkdownEditor's editing-surface max-height resolution.
+ *
+ * Deliberately framework-free (no DOM, no Svelte) so the height-capping logic is
+ * unit-testable without a browser/layout engine. `MarkdownEditor.svelte` does the
+ * actual DOM measurement and feeds the resulting numbers through these helpers.
+ */
+/**
+ * Base cap applied to the editing surface, as a CSS expression. Reads the
+ * themeable `--stuic-markdown-editor-max-height` custom property, falling back
+ * to `32rem`. The `32rem` fallback is kept in sync with the same value in
+ * `index.css` (`.stuic-markdown-editor-surface`).
+ */
+export const DEFAULT_MAX_HEIGHT_VAR = "var(--stuic-markdown-editor-max-height, 32rem)";
+/**
+ * Normalize a `maxHeight` prop value into a CSS length.
+ * - `number` → pixels (`240` → `"240px"`)
+ * - `string` → used verbatim (any CSS length: `"40rem"`, `"60vh"`, `"min(40rem,50vh)"`)
+ * - `null` / `undefined` / empty / non-finite → `null` (caller uses the default)
+ */
+export function maxHeightToCss(value) {
+    if (value == null)
+        return null;
+    if (typeof value === "number")
+        return Number.isFinite(value) ? `${value}px` : null;
+    const trimmed = value.trim();
+    return trimmed.length ? trimmed : null;
+}
+/**
+ * Combine the configured cap (`base`, a CSS length/expression) with the measured
+ * parent-available height. When a positive `parentAvailablePx` is given the
+ * surface is capped to the smaller of the two via CSS `min()`, so it never
+ * overflows a height-constrained parent. Otherwise the base cap is returned
+ * unchanged.
+ */
+export function surfaceMaxHeight(base, parentAvailablePx) {
+    if (parentAvailablePx != null && parentAvailablePx > 0) {
+        return `min(${base}, ${Math.round(parentAvailablePx)}px)`;
+    }
+    return base;
+}
+/**
+ * Compute the vertical space available to the editor inside its parent: the
+ * distance from `fromTop` down to the bottom of the parent's content box, less
+ * an optional `bottomGap`.
+ *
+ * Returns `null` when the result is not positive — the parent is smaller than
+ * the editor's offset (e.g. not laid out yet), so no meaningful cap can be
+ * derived and the caller should fall back to the configured base.
+ *
+ * Note: in an auto-height (content-sized) parent this naturally returns roughly
+ * the editor's own height, so `surfaceMaxHeight(base, …)` resolves to the base
+ * cap and the parent constraint only bites when the parent is genuinely smaller.
+ */
+export function computeParentAvailable(input) {
+    const { fromTop, parentBottom, parentBorderBottom = 0, parentPaddingBottom = 0, bottomGap = 0, } = input;
+    const contentBottom = parentBottom - parentBorderBottom - parentPaddingBottom;
+    const available = contentBottom - fromTop - bottomGap;
+    return available > 0 ? Math.floor(available) : null;
+}

package/dist/components/MarkdownEditor/index.css

@@ -157,7 +157,12 @@
 	flex: 1;
 	min-width: 0;
 	min-height: var(--_min-height);
-	max-height: var(--stuic-markdown-editor-max-height, none);
+	/* A finite default cap so a long document scrolls INSIDE the surface instead
+	   of growing the editor unbounded (which scrolls the toolbar out of view).
+	   `32rem` is kept in sync with DEFAULT_MAX_HEIGHT_VAR in _internal/max-height.ts.
+	   The component may narrow this further (inline `max-height`) to the parent's
+	   available height — see the `maxHeight` / `capToParent` props. */
+	max-height: var(--stuic-markdown-editor-max-height, 32rem);
 	overflow: auto;
 	padding: var(--_pad-y) var(--_pad-x);
 }

package/docs/domains/actions.md

@@ -8,23 +8,23 @@
 
 ## Available Actions
 
-| Action                  | Purpose                                                       | File                                 |
-| ----------------------- | ------------------------------------------------------------- | ------------------------------------ |
-| `validate`              | Form field validation with i18n support                       | `validate.svelte.ts`                 |
-| `focusTrap`             | Keyboard focus containment (modals/dialogs)                   | `focus-trap.ts`                      |
-| `autogrow`              | Auto-resize textarea to content                               | `autogrow.svelte.ts`                 |
-| `autoscroll`            | Auto-scroll container to bottom                               | `autoscroll.ts`                      |
-| `dimBehind`             | Dim everything behind a target element (simplified spotlight) | `dim-behind/`                        |
-| `fileDropzone`          | Drag-and-drop file handling                                   | `file-dropzone.svelte.ts`            |
-| `highlightDragover`     | Visual feedback on drag-over                                  | `highlight-dragover.svelte.ts`       |
-| `resizableWidth`        | Draggable width resizing                                      | `resizable-width.svelte.ts`          |
-| `trim`                  | Auto-trim whitespace from input                               | `trim.svelte.ts`                     |
-| `typeahead`             | Advanced autocomplete behavior                                | `typeahead.svelte.ts`                |
-| `onSubmitValidityCheck` | Form submit validation                                        | `on-submit-validity-check.svelte.ts` |
-| `popover`               | Popover positioning                                           | `popover/`                           |
-| `spotlight`             | Spotlight/coach mark overlay with cutout hole                 | `spotlight/`                         |
-| `tooltip`               | Tooltip positioning and display                               | `tooltip/`                           |
-| `createTour` / `tourStep` | Multi-step onboarding tour (built on spotlight)             | `onboarding/`                        |
+| Action                    | Purpose                                                       | File                                 |
+| ------------------------- | ------------------------------------------------------------- | ------------------------------------ |
+| `validate`                | Form field validation with i18n support                       | `validate.svelte.ts`                 |
+| `focusTrap`               | Keyboard focus containment (modals/dialogs)                   | `focus-trap.ts`                      |
+| `autogrow`                | Auto-resize textarea to content                               | `autogrow.svelte.ts`                 |
+| `autoscroll`              | Auto-scroll container to bottom                               | `autoscroll.ts`                      |
+| `dimBehind`               | Dim everything behind a target element (simplified spotlight) | `dim-behind/`                        |
+| `fileDropzone`            | Drag-and-drop file handling                                   | `file-dropzone.svelte.ts`            |
+| `highlightDragover`       | Visual feedback on drag-over                                  | `highlight-dragover.svelte.ts`       |
+| `resizableWidth`          | Draggable width resizing                                      | `resizable-width.svelte.ts`          |
+| `trim`                    | Auto-trim whitespace from input                               | `trim.svelte.ts`                     |
+| `typeahead`               | Advanced autocomplete behavior                                | `typeahead.svelte.ts`                |
+| `onSubmitValidityCheck`   | Form submit validation                                        | `on-submit-validity-check.svelte.ts` |
+| `popover`                 | Popover positioning                                           | `popover/`                           |
+| `spotlight`               | Spotlight/coach mark overlay with cutout hole                 | `spotlight/`                         |
+| `tooltip`                 | Tooltip positioning and display                               | `tooltip/`                           |
+| `createTour` / `tourStep` | Multi-step onboarding tour (built on spotlight)               | `onboarding/`                        |
 
 ---
 
@@ -116,8 +116,8 @@ inline messages to render. They won't — the `validate` action's
 
 ### Hidden inputs and `required`
 
-Per the HTML spec, `<input type="hidden">` is *barred from constraint
-validation* — `validity.valueMissing` stays `false` regardless of the
+Per the HTML spec, `<input type="hidden">` is _barred from constraint
+validation_ — `validity.valueMissing` stays `false` regardless of the
 `required` attribute, and native browser submit blocking is skipped. Several
 STUIC field components (`FieldPhoneNumber`, `FieldCountry`, `FieldObject`,
 `FieldAssets`, `FieldInputLocalized`, `FieldKeyValues`, `FieldLikeButton`)
@@ -138,6 +138,29 @@ correctly fail validation when empty — both through the imperative
 `validate()` path and via `use:onSubmitValidityCheck`. Without this wrap
 they'd silently accept empty values.
 
+### `onSubmitValidityCheck` and synthetic events
+
+On submit the action walks `form.elements` and synthetically dispatches
+`input` + `change` on each control, so custom `validate` listeners run even on
+fields the user never touched. `form.elements` includes CSS-hidden controls
+(`display:none` does **not** remove an element — only `disabled` or being
+outside the form does), so this fan-out reaches every wired input.
+
+Two element types are deliberately exempt from the synthetic dispatch:
+
+- **`type="radio"`** — dispatching `change` auto-selects the last radio in the
+  group, which is wrong.
+- **`type="file"`** — a file input's value is read-only to script, so a
+  synthetic `change` can't re-validate it; worse, it re-triggers any dropzone /
+  upload listener bound to the input. `FieldAssets` wires its hidden
+  `<input type="file">` through `fileDropzone`, so a re-fired `change` would
+  re-run `processFiles` with the previously-picked file still in `inputEl.files`
+  — duplicating the asset and firing a real re-upload on every save. File inputs
+  are still read for native constraint validation (`required`); only the event
+  dispatch is skipped. (`FieldAssets` additionally clears its file input after
+  consuming a selection, both as defense-in-depth and to allow re-selecting the
+  same file twice in a row.)
+
 ### File Dropzone
 
 ```svelte

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/stuic",
-	"version": "3.110.0",
+	"version": "3.112.0",
 	"scripts": {
 		"dev": "vite dev",
 		"build": "vite build && pnpm run prepack",