@marianmeres/stuic 3.112.0 → 3.114.0

package/dist/actions/autogrow.svelte.js

@@ -33,7 +33,14 @@ export function autogrow(el, fn) {
             // console.log(123, el.value);
             if (enabled) {
                 el.style.height = "auto"; // Reset height to auto to correctly calculate scrollHeight
-                el.style.height = Math.max(min, Math.min(el.scrollHeight, max)) + "px";
+                // `scrollHeight` excludes the border, but with `box-sizing: border-box` the
+                // height we set *includes* it — so without adding the vertical border back
+                // we undershoot by a couple px and a scrollbar lingers.
+                const cs = getComputedStyle(el);
+                const borderY = cs.boxSizing === "border-box"
+                    ? parseFloat(cs.borderTopWidth) + parseFloat(cs.borderBottomWidth)
+                    : 0;
+                el.style.height = Math.max(min, Math.min(el.scrollHeight + borderY, max)) + "px";
             }
         }
         // eventlistener strategy (we're not passing value)

package/dist/actions/popover/popover.svelte.js

@@ -1,6 +1,7 @@
 import { mount, unmount } from "svelte";
 import { twMerge } from "../../utils/tw-merge.js";
 import { addAnchorName, removeAnchorName } from "../../utils/anchor-name.js";
+import { clampIntoViewport } from "../../utils/anchor-position.js";
 import { iconX } from "../../icons/index.js";
 import { BodyScroll } from "../../utils/body-scroll-locker.js";
 import PopoverContent from "./PopoverContent.svelte";
@@ -434,8 +435,15 @@ export function popover(anchorEl, fn) {
                 requestAnimationFrame(() => {
                     if (!popoverEl)
                         return;
+                    // Clamp into the viewport first. The discrete @position-try
+                    // fallbacks can leave a residual overflow (and don't cover
+                    // sub-pixel/vertical cases); clamping keeps small edge-anchored
+                    // popovers anchored instead of switching them to a modal.
+                    clampIntoViewport(popoverEl);
                     const rect = popoverEl.getBoundingClientRect();
                     const viewportWidth = window.innerWidth;
+                    // If it STILL overflows horizontally after clamping, the content
+                    // is too wide to fit anchored — fall back to the centered modal.
                     if (rect.left < 0 || rect.right > viewportWidth) {
                         debug("overflow detected, switching to fallback mode");
                         switchingToFallback = true;

package/dist/actions/spotlight/index.css

@@ -26,11 +26,18 @@
 
 @supports (anchor-name: --anchor) {
 	.stuic-spotlight-annotation {
-		position-try-order: most-width;
+		/* The spotlight action overrides these inline per-instance, tailoring the
+		   fallbacks to each annotation's position (see buildPositionTryFallbacks).
+		   These are a sane default for the centered `bottom` placement. `normal`
+		   order keeps the base position when it fits and only engages the span
+		   fallbacks on overflow; the JS clamp is the final backstop. */
+		position-try-order: normal;
 		position-try-fallbacks:
 			flip-block,
 			flip-inline,
-			flip-block flip-inline;
+			flip-block flip-inline,
+			bottom span-left,
+			bottom span-right;
 
 		&.spot-block {
 			display: block;

package/dist/actions/spotlight/spotlight.svelte.js

@@ -1,6 +1,7 @@
 import { mount, unmount } from "svelte";
 import { twMerge } from "../../utils/tw-merge.js";
 import { addAnchorName, removeAnchorName } from "../../utils/anchor-name.js";
+import { buildPositionTryFallbacks, clampIntoViewport, } from "../../utils/anchor-position.js";
 import { BodyScroll } from "../../utils/body-scroll-locker.js";
 import SpotlightContent from "./SpotlightContent.svelte";
 //
@@ -189,6 +190,9 @@ export function spotlight(targetEl, fn) {
     let resizeObserver = null;
     let rafId = null;
     let lastRect = null;
+    // True once the annotation is display:block and laid out — gates the
+    // viewport clamp so it never measures a `display:none` element (zeros).
+    let annotationShown = false;
     // Unique identifiers
     const rnd = Math.random().toString(36).slice(2);
     const anchorName = `--anchor-spotlight-${rnd}`;
@@ -230,9 +234,14 @@ export function spotlight(targetEl, fn) {
             anchorEl.style.width = `${rect.width + padding * 2}px`;
             anchorEl.style.height = `${rect.height + padding * 2}px`;
         }
-        // Update fallback annotation position
-        if (annotationEl && !isSupported) {
-            positionAnnotationFallback(rect, padding);
+        // Reposition / re-clamp the annotation. The fallback path recomputes its
+        // base left/top here; the anchor path is re-placed by the browser. Either
+        // way we re-clamp so an edge-anchored annotation stays on-screen as the
+        // target moves (the anchor path has no built-in viewport clamping).
+        if (annotationEl) {
+            if (!isSupported)
+                positionAnnotationFallback(rect, padding);
+            clampAnnotationIntoViewport();
         }
     }
     /**
@@ -305,27 +314,21 @@ export function spotlight(targetEl, fn) {
             annotationEl.style.left = `${x + w + offset}px`;
             annotationEl.style.top = `${y}px`;
         }
-        // Clamp into viewport after layout settles. Using transform keeps the
-        // underlying left/top intent intact so the next call recomputes cleanly.
-        requestAnimationFrame(() => {
-            if (!annotationEl)
-                return;
-            const a = annotationEl.getBoundingClientRect();
-            const m = 8;
-            const vw = window.innerWidth;
-            const vh = window.innerHeight;
-            let dx = 0;
-            let dy = 0;
-            if (a.left < m)
-                dx = m - a.left;
-            else if (a.right > vw - m)
-                dx = vw - m - a.right;
-            if (a.top < m)
-                dy = m - a.top;
-            else if (a.bottom > vh - m)
-                dy = vh - m - a.bottom;
-            annotationEl.style.transform = dx || dy ? `translate(${dx}px, ${dy}px)` : "";
-        });
+        // Viewport clamping is handled by clampAnnotationIntoViewport(), called by
+        // the caller once the annotation is laid out (and on every reposition).
+    }
+    /**
+     * Clamp the annotation into the viewport, on BOTH positioning paths. The CSS
+     * Anchor Positioning path has no built-in way to slide a centered annotation
+     * back on-screen when the target is near a viewport edge (visible on Android
+     * Chrome, which supports anchor positioning; iOS Safari ≤18 takes the JS
+     * fallback path). Gated on `annotationShown` so it never measures a
+     * `display:none` element. See {@link clampIntoViewport}.
+     */
+    function clampAnnotationIntoViewport() {
+        if (!annotationEl || !annotationShown)
+            return;
+        clampIntoViewport(annotationEl);
     }
     function renderContent() {
         if (!annotationEl || !currentOptions.content)
@@ -406,8 +409,8 @@ export function spotlight(targetEl, fn) {
 						position: fixed;
 						position-anchor: ${anchorName};
 						position-area: ${POSITION_MAP[currentOptions.position || "bottom"] || "bottom"};
-						position-try-fallbacks: flip-block, flip-inline, flip-block flip-inline;
-						position-try-order: most-width;
+						position-try-fallbacks: ${buildPositionTryFallbacks(currentOptions.position || "bottom")};
+						position-try-order: normal;
 						max-width: calc(100vw - 1rem);
 						max-height: calc(100vh - 1rem);
 						transition-duration: ${TRANSITION}ms;
@@ -437,6 +440,10 @@ export function spotlight(targetEl, fn) {
                 backdropEl?.classList.add("spot-visible");
                 if (annotationEl) {
                     annotationEl.classList.add("spot-block");
+                    // Now display:block and laid out — clamp into the viewport before
+                    // it fades in. Applies to both the anchor and fallback paths.
+                    annotationShown = true;
+                    clampAnnotationIntoViewport();
                     requestAnimationFrame(() => {
                         annotationEl?.classList.add("spot-visible");
                     });
@@ -467,6 +474,7 @@ export function spotlight(targetEl, fn) {
         if (!isVisible)
             return;
         isVisible = false;
+        annotationShown = false;
         if (currentOptions.id) {
             spotlightOpenStates[currentOptions.id] = false;
         }
@@ -555,6 +563,7 @@ export function spotlight(targetEl, fn) {
     $effect(() => {
         return () => {
             // Cleanup on unmount
+            annotationShown = false;
             if (mountedComponent) {
                 unmount(mountedComponent);
                 mountedComponent = null;

package/dist/actions/tooltip/tooltip.svelte.js

@@ -1,5 +1,6 @@
 import { twMerge } from "../../utils/tw-merge.js";
 import { addAnchorName, removeAnchorName } from "../../utils/anchor-name.js";
+import { clampIntoViewport } from "../../utils/anchor-position.js";
 const TIMEOUT = 200;
 const TRANSITION = 200;
 /**
@@ -224,6 +225,10 @@ export function tooltip(anchorEl, fn) {
                 anchorEl.setAttribute("aria-expanded", "true");
                 //
                 tooltipEl.classList.add("tt-block");
+                // Backstop: the CSS @position-try fallbacks handle most edge cases,
+                // but can leave a residual overflow (and don't cover the "no fallback
+                // fits" case) — clamp fully on-screen now that it's laid out.
+                clampIntoViewport(tooltipEl);
                 requestAnimationFrame(() => {
                     tooltipEl.classList.add("tt-visible");
                     on_show?.();

package/dist/actions/validate.svelte.js

@@ -170,9 +170,20 @@ export function validate(el, fn) {
         // 	}">`,
         // 	{ enabled, on, hasCustomValidator: typeof customValidator === "function" }
         // );
+        // Flipped to `true` in this $effect's cleanup. Guards the deferred blur
+        // validation (and any other stray late event) from running after the action
+        // is torn down — see the guard in `_doValidate` and the `onBlur` deferral.
+        let destroyed = false;
         const _doValidate = () => {
             if (!enabled)
                 return;
+            // Bail if the action has already been torn down. Together with the
+            // deferral in `onBlur`, this makes the deferred validation a guaranteed
+            // no-op after unmount even in the rare case the node stays connected —
+            // e.g. a keyed `{#each}` move that destroys this effect while the DOM
+            // node persists, where the `isConnected` check below would still pass.
+            if (destroyed)
+                return;
             // A focused, dirty field torn down by a route change fires a final
             // synchronous `change`/`blur` while being removed from the DOM. That
             // removal runs inside Svelte's flush, so writing `validation` state here
@@ -241,13 +252,36 @@ export function validate(el, fn) {
         let _touchCount = 0;
         const onFocus = () => _touchCount++;
         el.addEventListener("focus", onFocus);
-        // also validate on first blur
+        // also validate on first blur — but DEFERRED out of the current task.
+        //
+        // When a focused, touched field is unmounted (e.g. a successful submit
+        // navigates away and tears down the form), the browser fires a final
+        // synchronous `blur` *during* Svelte's destroy flush, while the node is
+        // still connected. Running `_doValidate` there reads any consumer `$derived`
+        // belonging to the now-destroyed effect (`derived_inert` warning) and writes
+        // the parent's `validation` `$state` (`state_unsafe_mutation`, uncaught) —
+        // the existing `isConnected` guard misses it because the node hasn't been
+        // detached yet at blur time.
+        //
+        // A microtask runs *after* the synchronous flush completes: by then a
+        // torn-down node is detached and this $effect's cleanup has set `destroyed`,
+        // so `_doValidate`'s guards bail (no derived read, no state write). On a real
+        // user blur the field is still connected and alive, so validation runs as
+        // before — just one microtask later (imperceptible).
+        //
+        // Only `blur` is deferred. The `change`/`input` listener and the imperative
+        // `setDoValidate` path must stay synchronous: `onSubmitValidityCheck`
+        // dispatches synthetic `input`/`change` and reads `el.validity` immediately,
+        // and `FieldInput.validate()` reads `validation` right after invoking the
+        // exposed validator — deferring either would break submit-time validation.
         const onBlur = () => {
-            if (_touchCount === 1)
-                _doValidate();
+            if (_touchCount !== 1)
+                return;
+            queueMicrotask(_doValidate);
         };
         el.addEventListener("blur", onBlur);
         return () => {
+            destroyed = true;
             el.removeEventListener(on, _doValidate);
             el.removeEventListener("focus", onFocus);
             el.removeEventListener("blur", onBlur);

package/dist/components/Input/FieldKeyValues.svelte

@@ -42,13 +42,23 @@
 		addLabel?: string;
 		emptyMessage?: string;
 		onChange?: (value: string) => void;
+		/**
+		 * When `true`, a value that *looks like* JSON (starts with `{`/`[`) but
+		 * fails to parse becomes a blocking validation error on submit.
+		 *
+		 * Defaults to `false`: the component detects/parses JSON for convenience
+		 * (pretty-print + the inline indicator) but does **not** enforce validity —
+		 * whether a value must be valid JSON is a business rule the consumer owns.
+		 * Unparseable values are simply stored as plain strings. Opt in to `true`
+		 * only for a strictly JSON-only field.
+		 */
 		strictJsonValidation?: boolean;
 		t?: TranslateFn;
 	}
 </script>
 
 <script lang="ts">
-	import { iconPlus, iconTrash } from "../../icons/index.js";
+	import { iconAlertWarning, iconCode, iconPlus, iconTrash } from "../../icons/index.js";
 	import { tick } from "svelte";
 	import { autogrow } from "../../actions/autogrow.svelte.js";
 	import { validate as validateAction } from "../../actions/validate.svelte.js";
@@ -75,6 +85,7 @@
 			remove_entry: "Remove entry",
 			duplicate_keys: "Duplicate keys are not allowed",
 			invalid_json_syntax: "Invalid JSON syntax. Check for missing quotes or brackets.",
+			json_detected: "Valid JSON",
 		};
 		let out = m[k] ?? fallback ?? k;
 		return isPlainObject(values) ? replaceMap(out, values as any) : out;
@@ -118,7 +129,7 @@
 		addLabel,
 		emptyMessage,
 		onChange,
-		strictJsonValidation = true,
+		strictJsonValidation = false,
 		t = t_default,
 	}: Props = $props();
 
@@ -159,7 +170,7 @@
 			if (!isPlainObject(parsed)) return [];
 			return Object.entries(parsed).map(([key, val]) => ({
 				key,
-				value: typeof val === "string" ? val : JSON.stringify(val),
+				value: typeof val === "string" ? val : JSON.stringify(val, null, 2),
 				parsedValue: val,
 			}));
 		} catch (e) {
@@ -232,6 +243,35 @@
 		syncToValue();
 	}
 
+	// Pretty-print structured JSON (objects/arrays) on blur. Display-only: the
+	// parsed value is unchanged, so the serialized external `value` is identical
+	// and `syncToValue()` is intentionally not called. Primitives, plain strings,
+	// and invalid JSON are left exactly as typed (no surprising normalization).
+	function formatValueEntry(idx: number) {
+		const raw = entries[idx].value;
+		const trimmed = raw.trim();
+		if (!(trimmed.startsWith("{") || trimmed.startsWith("["))) return;
+		try {
+			const parsed = JSON.parse(trimmed);
+			const pretty = JSON.stringify(parsed, null, 2);
+			if (pretty !== raw) {
+				entries[idx].value = pretty;
+				entries[idx].parsedValue = parsed;
+				entryJsonErrors[idx] = false;
+			}
+		} catch {
+			// invalid JSON: leave as typed; indicator + validation handle it
+		}
+	}
+
+	// Per-entry JSON signal for the subtle inline indicator.
+	function jsonState(entry: KeyValueEntry, idx: number): "valid" | "error" | "none" {
+		if (entryJsonErrors[idx]) return "error";
+		const v = entry.parsedValue;
+		if (isPlainObject(v) || Array.isArray(v)) return "valid";
+		return "none";
+	}
+
 	// Validation
 	let validation: ValidationResult | undefined = $state();
 	const setValidationResult = (res: ValidationResult) => (validation = res);
@@ -314,6 +354,7 @@
 
 	const INPUT_CLS = [
 		"rounded bg-(--stuic-color-input)",
+		"font-mono",
 		"focus:outline-none focus:ring-0",
 		"border border-(--stuic-color-border)",
 		"focus:border-(--stuic-color-border-hover)",
@@ -355,6 +396,7 @@
 		{:else}
 			<div class="p-2">
 				{#each entries as entry, idx (idx)}
+					{@const st = jsonState(entry, idx)}
 					<div
 						class={twMerge(
 							"flex gap-2 items-start py-2",
@@ -382,15 +424,42 @@
 							/>
 
 							<!-- Value textarea -->
-							<textarea
-								value={entry.value}
-								oninput={(e) => updateEntry(idx, "value", e.currentTarget.value)}
-								placeholder={valuePlaceholder ?? t("value_placeholder")}
-								class={twMerge(INPUT_CLS, "min-h-10 flex-none", classValueInput)}
-								{disabled}
-								{tabindex}
-								use:autogrow={() => ({ enabled: true, value: entry.value })}
-							></textarea>
+							<div class="relative">
+								<textarea
+									value={entry.value}
+									oninput={(e) => updateEntry(idx, "value", e.currentTarget.value)}
+									onblur={() => formatValueEntry(idx)}
+									placeholder={valuePlaceholder ?? t("value_placeholder")}
+									class={twMerge(
+										INPUT_CLS,
+										"w-full min-h-10 flex-none pr-6",
+										classValueInput
+									)}
+									{disabled}
+									{tabindex}
+									use:autogrow={() => ({ enabled: true, value: entry.value })}
+								></textarea>
+
+								<!-- Subtle JSON state indicator -->
+								{#if st !== "none"}
+									<span
+										class={twMerge(
+											"pointer-events-none absolute top-1.5 right-1.5",
+											st === "valid"
+												? "opacity-40"
+												: "text-amber-500 opacity-80"
+										)}
+										title={st === "valid"
+											? t("json_detected")
+											: t("invalid_json_syntax")}
+										aria-hidden="true"
+									>
+										{@html st === "valid"
+											? iconCode({ size: 14 })
+											: iconAlertWarning({ size: 14 })}
+									</span>
+								{/if}
+							</div>
 						</div>
 
 						<!-- Delete button -->

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

@@ -37,6 +37,16 @@ export interface Props extends InputWrapClassProps, Record<string, any> {
     addLabel?: string;
     emptyMessage?: string;
     onChange?: (value: string) => void;
+    /**
+     * When `true`, a value that *looks like* JSON (starts with `{`/`[`) but
+     * fails to parse becomes a blocking validation error on submit.
+     *
+     * Defaults to `false`: the component detects/parses JSON for convenience
+     * (pretty-print + the inline indicator) but does **not** enforce validity —
+     * whether a value must be valid JSON is a business rule the consumer owns.
+     * Unparseable values are simply stored as plain strings. Opt in to `true`
+     * only for a strictly JSON-only field.
+     */
     strictJsonValidation?: boolean;
     t?: TranslateFn;
 }

package/dist/utils/anchor-position.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Shared helpers for CSS Anchor Positioning based actions (spotlight, popover,
+ * tooltip).
+ */
+/**
+ * Builds the `position-try-fallbacks` value for an anchored element at a given
+ * position.
+ *
+ * For the centered positions (`top`/`bottom` are inline-centered; `left`/`right`
+ * are block-centered) a `flip-inline`/`flip-block` is a no-op on the centered
+ * axis, so the browser cannot slide the element back on-screen when the target
+ * sits near a viewport edge. We append `span-*` variants that give it an edge to
+ * align to. A JS clamp (see {@link clampIntoViewport}) should still be used as
+ * the ultimate backstop; these fallbacks just yield nicer native placement.
+ *
+ * Note: tooltip/popover declare their fallbacks via `@position-try` named rules
+ * in CSS instead and don't use this; it's primarily for the spotlight action,
+ * which sets `position-try-fallbacks` inline.
+ */
+export declare function buildPositionTryFallbacks(position: string): string;
+/**
+ * Pull an element fully into the viewport with a corrective `transform`.
+ *
+ * This is the backstop for CSS Anchor Positioning: `position-try` can only swap
+ * between discrete declared positions and cannot slide a centered annotation
+ * back on-screen when the target is near a viewport edge — so without this an
+ * anchored element can render off-screen on browsers that support anchor
+ * positioning (e.g. Android Chrome).
+ *
+ * Synchronous and flicker-free: it clears any prior transform, force-measures
+ * the natural rect (`getBoundingClientRect` triggers a synchronous layout), then
+ * applies a single translate — all within one JS turn, so the browser only
+ * paints the final, clamped position. The element MUST be laid out
+ * (`display: block`) when called, and `transform` MUST NOT be in its
+ * `transition-property` (callers use `transition-property: opacity`) so the
+ * correction applies instantly. The caller owns the element's `transform`.
+ *
+ * @param el - The (anchored, position:fixed) element to clamp
+ * @param margin - Minimum gap from each viewport edge, in px (default 8)
+ */
+export declare function clampIntoViewport(el: HTMLElement, margin?: number): void;

package/dist/utils/anchor-position.js

@@ -0,0 +1,69 @@
+/**
+ * Shared helpers for CSS Anchor Positioning based actions (spotlight, popover,
+ * tooltip).
+ */
+/**
+ * Builds the `position-try-fallbacks` value for an anchored element at a given
+ * position.
+ *
+ * For the centered positions (`top`/`bottom` are inline-centered; `left`/`right`
+ * are block-centered) a `flip-inline`/`flip-block` is a no-op on the centered
+ * axis, so the browser cannot slide the element back on-screen when the target
+ * sits near a viewport edge. We append `span-*` variants that give it an edge to
+ * align to. A JS clamp (see {@link clampIntoViewport}) should still be used as
+ * the ultimate backstop; these fallbacks just yield nicer native placement.
+ *
+ * Note: tooltip/popover declare their fallbacks via `@position-try` named rules
+ * in CSS instead and don't use this; it's primarily for the spotlight action,
+ * which sets `position-try-fallbacks` inline.
+ */
+export function buildPositionTryFallbacks(position) {
+    const flips = "flip-block, flip-inline, flip-block flip-inline";
+    if (position === "top" || position === "bottom") {
+        return `${flips}, ${position} span-left, ${position} span-right`;
+    }
+    if (position === "left" || position === "right") {
+        return `${flips}, ${position} span-top, ${position} span-bottom`;
+    }
+    return flips;
+}
+/**
+ * Pull an element fully into the viewport with a corrective `transform`.
+ *
+ * This is the backstop for CSS Anchor Positioning: `position-try` can only swap
+ * between discrete declared positions and cannot slide a centered annotation
+ * back on-screen when the target is near a viewport edge — so without this an
+ * anchored element can render off-screen on browsers that support anchor
+ * positioning (e.g. Android Chrome).
+ *
+ * Synchronous and flicker-free: it clears any prior transform, force-measures
+ * the natural rect (`getBoundingClientRect` triggers a synchronous layout), then
+ * applies a single translate — all within one JS turn, so the browser only
+ * paints the final, clamped position. The element MUST be laid out
+ * (`display: block`) when called, and `transform` MUST NOT be in its
+ * `transition-property` (callers use `transition-property: opacity`) so the
+ * correction applies instantly. The caller owns the element's `transform`.
+ *
+ * @param el - The (anchored, position:fixed) element to clamp
+ * @param margin - Minimum gap from each viewport edge, in px (default 8)
+ */
+export function clampIntoViewport(el, margin = 8) {
+    // Remove any prior correction so we measure the natural (anchored or
+    // left/top) position, then recompute from scratch.
+    el.style.transform = "";
+    const a = el.getBoundingClientRect();
+    const vw = window.innerWidth;
+    const vh = window.innerHeight;
+    let dx = 0;
+    let dy = 0;
+    if (a.left < margin)
+        dx = margin - a.left;
+    else if (a.right > vw - margin)
+        dx = vw - margin - a.right;
+    if (a.top < margin)
+        dy = margin - a.top;
+    else if (a.bottom > vh - margin)
+        dy = vh - margin - a.bottom;
+    if (dx || dy)
+        el.style.transform = `translate(${dx}px, ${dy}px)`;
+}

package/package.json

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