@marianmeres/stuic 3.154.0 → 3.156.0

package/API.md

@@ -1629,10 +1629,12 @@ Multi-step onboarding tour built on the spotlight primitive. Define steps centra
 | `onSkip`         | `() => void`                        | —         | Called when tour is skipped                      |
 | `onStepChange`   | `(step, index) => void`             | —         | Called on every step change                      |
 
-**Returns:** `{ start(), stop(), next(), prev(), skip(), reset(), reposition(), active, currentStep, currentIndex }`
+**Returns:** `{ start(), next(), prev(), skip(), reset(), reposition(), active, currentStep, currentIndex, seen }`
 
 `reposition()` forces the active step's spotlight to re-measure its target and re-apply the cutout/anchor. Useful after a layout shift the spotlight's auto-tracking can't observe (or when a step opted out of it).
 
+`reset()` clears the `storageKey` result so `start()` will run the tour again; `seen` is that flag read back. Every `start()` re-resolves `selector` steps against the current DOM, so a tour whose targets remount between runs (a lazy tab, a route, a keyed block) points at the nodes that are on screen now. Targets registered through `use:tourStep` are left to the action, which already tracks their mount and unmount.
+
 **`TourStepDef`:**
 
 | Field          | Type                | Description                                                             |

package/dist/actions/onboarding/onboarding.container.fixture.svelte

@@ -0,0 +1,76 @@
+<script lang="ts">
+	import { untrack } from "svelte";
+	import { createTour, tourStep } from "./onboarding.svelte.js";
+
+	let {
+		/** Register the target through `use:tourStep` instead of a `selector`. */
+		useAction = false,
+		/** Re-keys the target, i.e. destroys the node and mounts a fresh one at
+		 *  different coordinates — what a lazy tab or a keyed block does between
+		 *  two runs of the same tour. */
+		swapped = false,
+		storageKey = undefined,
+	}: {
+		useAction?: boolean;
+		swapped?: boolean;
+		storageKey?: string;
+	} = $props();
+
+	const tour = createTour({
+		steps: [
+			{
+				id: "one",
+				title: "Step one",
+				content: "the only step",
+				position: "bottom",
+				padding: 0,
+				borderRadius: 0,
+				// The whole point of the two modes: an action-registered step has
+				// no selector to be re-resolved from. untracked for the same reason
+				// as `storageKey` below.
+				selector: untrack(() => (useAction ? undefined : "[data-testid='target']")),
+			},
+		],
+		// Short: the action test asserts a step is NOT skipped, and a skip costs
+		// this whole wait before it can be observed.
+		waitForElement: 300,
+		// untrack: read once at init, which is when `createTour` needs it — a
+		// tracked read here would be a reactivity warning for a prop that never
+		// changes after mount.
+		storageKey: untrack(() => storageKey),
+		storage: "session",
+		showSteps: false,
+	});
+</script>
+
+<!-- Above the spotlight backdrop (z-index 50), which would otherwise swallow
+every click the test makes while a tour is running. -->
+<div style="position: relative; z-index: 100;">
+	<button data-testid="start" onclick={() => tour.start()}>start</button>
+	<button data-testid="reset" onclick={() => tour.reset()}>reset</button>
+	<button data-testid="skip" onclick={() => void tour.skip()}>skip</button>
+	<div data-testid="active">{tour.active ? "yes" : "no"}</div>
+</div>
+
+{#key swapped}
+	{#if useAction}
+		<div
+			data-testid="target"
+			use:tourStep={[tour, "one"]}
+			style="position: absolute; left: {swapped ? 160 : 40}px; top: {swapped
+				? 130
+				: 30}px; width: 60px; height: 20px;"
+		>
+			t
+		</div>
+	{:else}
+		<div
+			data-testid="target"
+			style="position: absolute; left: {swapped ? 160 : 40}px; top: {swapped
+				? 130
+				: 30}px; width: 60px; height: 20px;"
+		>
+			t
+		</div>
+	{/if}
+{/key}

package/dist/actions/onboarding/onboarding.container.fixture.svelte.d.ts

@@ -0,0 +1,8 @@
+type $$ComponentProps = {
+    useAction?: boolean;
+    swapped?: boolean;
+    storageKey?: string;
+};
+declare const Onboarding: import("svelte").Component<$$ComponentProps, {}, "">;
+type Onboarding = ReturnType<typeof Onboarding>;
+export default Onboarding;

package/dist/actions/onboarding/onboarding.svelte.js

@@ -225,12 +225,51 @@ export function createTour(options) {
         store?.set(options.storageKey, "completed");
         options.onEnd?.();
     }
+    /**
+     * Drop every SELECTOR-resolved target, so the next run resolves them against
+     * the DOM as it is now.
+     *
+     * The registry is a cache and `advanceTo` only queries the DOM for a step it
+     * does not already hold, so without this a second run re-uses the first
+     * run's nodes. For a tour whose targets all sit in one stable subtree that
+     * is harmless. For one that crosses a lazy tab, a route or a keyed block it
+     * is fatal, and silently: a detached node's `getBoundingClientRect()` is all
+     * zeroes, so the cutout collapses to 0x0 in the top-left corner and the
+     * annotation follows it there. Nothing throws and nothing warns.
+     *
+     * Steps registered through `use:tourStep` are deliberately SPARED. The
+     * action owns their lifetime — it registers on mount and unregisters on
+     * destroy — so their entries are never stale, and such a step has no
+     * `selector` to be re-resolved from: dropping one whose element is still on
+     * screen would leave `advanceTo` nothing to find, and it would skip the step
+     * after waiting `waitForElement` ms for a registration that already
+     * happened. `actionRegistered` is exactly the set to spare.
+     */
+    function clearResolvedTargets() {
+        for (const id of registry.keys()) {
+            if (!actionRegistered.has(id))
+                registry.delete(id);
+        }
+    }
     // -- Public API ---------------------------------------------------------------------
+    /**
+     * Begin the tour at its first available step.
+     *
+     * No-op while a tour is already running, and — if `storageKey` is set — for
+     * anyone who has already completed or skipped it. Use {@link reset} to
+     * clear that.
+     *
+     * Resolved targets are cleared HERE rather than in `reset()`, because the
+     * staleness is per-RUN and not per-persisted-flag: a tour with no
+     * `storageKey` is re-startable without ever calling `reset()`, and would
+     * otherwise walk the previous run's nodes. See {@link clearResolvedTargets}.
+     */
     function start() {
         if (active)
             return;
         if (store && store.has(options.storageKey))
             return;
+        clearResolvedTargets();
         options.onStart?.();
         advanceTo(0);
     }
@@ -248,6 +287,13 @@ export function createTour(options) {
         store?.set(options.storageKey, "skipped");
         options.onSkip?.();
     }
+    /**
+     * Forget that this tour was completed or skipped, so {@link start} runs it
+     * again. A no-op without `storageKey` — there is nothing persisted to clear.
+     *
+     * It does NOT touch the resolved-target cache; `start()` does, on every run.
+     * See {@link clearResolvedTargets} for why that is the right boundary.
+     */
     function reset() {
         store?.remove(options.storageKey);
     }

package/dist/components/Input/README.md

@@ -291,6 +291,27 @@ Each size (sm, md, lg) has corresponding tokens:
 | `--stuic-input-font-size-{size}`  | `--text-sm`             | `--text-base`           | `--text-lg`           |
 | `--stuic-input-min-height-{size}` | `2.5rem`                | `2.75rem`               | `3rem`                |
 
+#### iOS zoom guard
+
+iOS/iPadOS Safari zooms the whole page when a text control with a computed
+font-size below 16px receives focus — which the `sm` size (14px) triggers. On
+touch-capable Apple devices only, inputs, textareas and selects are therefore
+raised to at least:
+
+| Variable                            | Default | Description                                        |
+| ----------------------------------- | ------- | -------------------------------------------------- |
+| `--stuic-input-font-size-touch-min` | `16px`  | Minimum font-size on touch WebKit (iOS zoom guard) |
+
+Desktop (including macOS Safari) and Android keep the original, smaller size —
+neither zooms on focus. The guard never shrinks a control, so `md`/`lg` are
+unaffected at their default sizes. Opt out with:
+
+```css
+:root {
+	--stuic-input-font-size-touch-min: 0px;
+}
+```
+
 ### Checkbox/Radio Tokens
 
 | Variable                          | Default                | Description            |

package/dist/components/Input/index.css

@@ -42,6 +42,10 @@
 	--stuic-input-font-size-lg: var(--text-lg);
 	--stuic-input-min-height-lg: 3rem;
 
+	/* Smallest font-size a text control may compute to on touch WebKit.
+	   See the "IOS ZOOM GUARD" section at the bottom of this file. */
+	--stuic-input-font-size-touch-min: 16px;
+
 	/* Range input */
 	--stuic-input-range-thumb-size: 18px;
 	--stuic-input-range-track-height: 4px;
@@ -674,3 +678,77 @@
 		padding-bottom: 0;
 	}
 }
+
+/* ============================================================================
+   IOS ZOOM GUARD
+
+   Mobile WebKit (iOS/iPadOS) auto-zooms the viewport when a text control whose
+   computed font-size is below 16px receives focus. The `sm` size (14px) trips
+   it, so tapping into e.g. a FieldsBuilder input jumps the whole page.
+
+   Raise the font-size to at least `--stuic-input-font-size-touch-min`, but only
+   where the zoom actually happens. Two conditions, both required:
+     - `@supports (font: -apple-system-body) or (-webkit-touch-callout: none)`
+       → an Apple/WebKit engine (verified: true in WebKit, false in Blink and
+       Gecko). Two signals OR-ed because `-webkit-touch-callout` is iOS-only
+       while `-apple-system-body` covers Apple platforms generally.
+     - `@media (any-pointer: coarse)` → ...on a touch-capable device, which on
+       Apple means iOS/iPadOS. This is what excludes desktop Safari.
+
+   Desktop (incl. Safari) and Android/Blink — neither of which zooms on focus —
+   keep the original, smaller size.
+
+   `max()` respects consumer overrides of the size tokens and never shrinks a
+   control. Opt out with `--stuic-input-font-size-touch-min: 0px`.
+
+   Deliberately NOT in `@layer components`: unlayered rules beat layered ones,
+   so this also wins over the Tailwind `text-sm` utilities some components put
+   on their own raw inputs (FieldsBuilder's mono key/value inputs, ...), which
+   would otherwise stay at 14px regardless of the size tokens.
+   ============================================================================ */
+
+@supports (font: -apple-system-body) or (-webkit-touch-callout: none) {
+	@media (any-pointer: coarse) {
+		.stuic-input[data-size="sm"]
+			input:not([type="checkbox"]):not([type="radio"]):not([type="range"]):not(
+				[type="file"]
+			),
+		.stuic-input[data-size="sm"] textarea,
+		.stuic-input[data-size="sm"] select {
+			font-size: max(
+				var(--stuic-input-font-size-touch-min),
+				var(--stuic-input-font-size-sm)
+			);
+		}
+
+		.stuic-input[data-size="md"]
+			input:not([type="checkbox"]):not([type="radio"]):not([type="range"]):not(
+				[type="file"]
+			),
+		.stuic-input[data-size="md"] textarea,
+		.stuic-input[data-size="md"] select,
+		.stuic-input:not([data-size])
+			input:not([type="checkbox"]):not([type="radio"]):not([type="range"]):not(
+				[type="file"]
+			),
+		.stuic-input:not([data-size]) textarea,
+		.stuic-input:not([data-size]) select {
+			font-size: max(
+				var(--stuic-input-font-size-touch-min),
+				var(--stuic-input-font-size-md)
+			);
+		}
+
+		.stuic-input[data-size="lg"]
+			input:not([type="checkbox"]):not([type="radio"]):not([type="range"]):not(
+				[type="file"]
+			),
+		.stuic-input[data-size="lg"] textarea,
+		.stuic-input[data-size="lg"] select {
+			font-size: max(
+				var(--stuic-input-font-size-touch-min),
+				var(--stuic-input-font-size-lg)
+			);
+		}
+	}
+}

package/package.json

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