@marianmeres/stuic 3.113.0 → 3.114.0

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/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.113.0",
+	"version": "3.114.0",
 	"scripts": {
 		"dev": "vite dev",
 		"build": "vite build && pnpm run prepack",