@marianmeres/stuic 3.119.0 → 3.121.0

package/dist/actions/draggable.svelte.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Options for the {@link draggable} action.
+ */
+export interface DraggableOptions {
+    /** Master switch. When `false` the action is inert. Default `true`. */
+    enabled?: boolean;
+    /**
+     * CSS selector for descendants that must NOT initiate a drag. A `pointerdown`
+     * whose target matches (via `closest`) is ignored — e.g. `"[data-no-drag]"`
+     * for buttons living inside an otherwise-draggable header.
+     */
+    ignore?: string;
+    /**
+     * Distance in px the pointer must travel before the gesture counts as a real
+     * drag (reported via `onEnd`'s `moved`). Used by consumers to distinguish a
+     * click/double-click from a drag. Default `3`.
+     */
+    threshold?: number;
+    /** Called on a valid drag start (pointer captured). */
+    onStart?: (e: PointerEvent) => void;
+    /**
+     * Called on every pointer move while dragging, with the cumulative delta from
+     * the drag's start point.
+     */
+    onMove?: (delta: {
+        dx: number;
+        dy: number;
+    }, e: PointerEvent) => void;
+    /** Called when the drag ends; `moved` is `true` if it passed `threshold`. */
+    onEnd?: (info: {
+        moved: boolean;
+    }, e: PointerEvent) => void;
+}
+/**
+ * A Svelte action that turns an element into a drag handle and reports pointer
+ * deltas — without taking any opinion on what gets moved. The consumer owns the
+ * positioned element, clamping, and persistence; this action only translates
+ * pointer gestures into `{dx, dy}` deltas.
+ *
+ * Built on Pointer Events with pointer capture, so a single code path covers
+ * mouse, touch and pen, and the drag keeps tracking even if the pointer leaves
+ * the element. Pair with `touch-action: none` on the handle to stop the browser
+ * from scrolling/zooming mid-drag.
+ *
+ * @param node - The handle element.
+ * @param fn - Function returning the current {@link DraggableOptions}.
+ *
+ * @example
+ * ```svelte
+ * <div
+ *   use:draggable={() => ({
+ *     ignore: "[data-no-drag]",
+ *     onStart: () => (start = { ...pos }),
+ *     onMove: ({ dx, dy }) => (pos = clamp(start.x + dx, start.y + dy)),
+ *     onEnd: ({ moved }) => (wasDragged = moved),
+ *   })}
+ * >
+ *   drag me
+ * </div>
+ * ```
+ */
+export declare function draggable(node: HTMLElement, fn?: () => DraggableOptions): void;

package/dist/actions/draggable.svelte.js

@@ -0,0 +1,93 @@
+/**
+ * A Svelte action that turns an element into a drag handle and reports pointer
+ * deltas — without taking any opinion on what gets moved. The consumer owns the
+ * positioned element, clamping, and persistence; this action only translates
+ * pointer gestures into `{dx, dy}` deltas.
+ *
+ * Built on Pointer Events with pointer capture, so a single code path covers
+ * mouse, touch and pen, and the drag keeps tracking even if the pointer leaves
+ * the element. Pair with `touch-action: none` on the handle to stop the browser
+ * from scrolling/zooming mid-drag.
+ *
+ * @param node - The handle element.
+ * @param fn - Function returning the current {@link DraggableOptions}.
+ *
+ * @example
+ * ```svelte
+ * <div
+ *   use:draggable={() => ({
+ *     ignore: "[data-no-drag]",
+ *     onStart: () => (start = { ...pos }),
+ *     onMove: ({ dx, dy }) => (pos = clamp(start.x + dx, start.y + dy)),
+ *     onEnd: ({ moved }) => (wasDragged = moved),
+ *   })}
+ * >
+ *   drag me
+ * </div>
+ * ```
+ */
+export function draggable(node, fn) {
+    $effect(() => {
+        const { enabled = true, ignore, threshold = 3, onStart, onMove, onEnd, } = fn?.() || {};
+        if (!enabled)
+            return;
+        let dragging = false;
+        let moved = false;
+        let startX = 0;
+        let startY = 0;
+        let pointerId = -1;
+        function onPointerDown(e) {
+            // primary button / touch / pen only
+            if (e.button !== 0 && e.pointerType === "mouse")
+                return;
+            if (ignore && e.target?.closest?.(ignore))
+                return;
+            dragging = true;
+            moved = false;
+            startX = e.clientX;
+            startY = e.clientY;
+            pointerId = e.pointerId;
+            try {
+                node.setPointerCapture(e.pointerId);
+            }
+            catch {
+                /* capture is best-effort */
+            }
+            document.body.style.userSelect = "none";
+            onStart?.(e);
+        }
+        function onPointerMove(e) {
+            if (!dragging)
+                return;
+            const dx = e.clientX - startX;
+            const dy = e.clientY - startY;
+            if (!moved && Math.hypot(dx, dy) > threshold)
+                moved = true;
+            onMove?.({ dx, dy }, e);
+        }
+        function onPointerUp(e) {
+            if (!dragging)
+                return;
+            dragging = false;
+            try {
+                node.releasePointerCapture(pointerId);
+            }
+            catch {
+                /* noop */
+            }
+            document.body.style.userSelect = "";
+            onEnd?.({ moved }, e);
+        }
+        node.addEventListener("pointerdown", onPointerDown);
+        node.addEventListener("pointermove", onPointerMove);
+        node.addEventListener("pointerup", onPointerUp);
+        node.addEventListener("pointercancel", onPointerUp);
+        return () => {
+            node.removeEventListener("pointerdown", onPointerDown);
+            node.removeEventListener("pointermove", onPointerMove);
+            node.removeEventListener("pointerup", onPointerUp);
+            node.removeEventListener("pointercancel", onPointerUp);
+            document.body.style.userSelect = "";
+        };
+    });
+}

package/dist/actions/index.d.ts

@@ -2,6 +2,7 @@ export * from "./autogrow.svelte.js";
 export * from "./onboarding/onboarding.svelte.js";
 export * from "./autoscroll.js";
 export * from "./dim-behind/dim-behind.svelte.js";
+export * from "./draggable.svelte.js";
 export * from "./file-dropzone.svelte.js";
 export * from "./focus-trap.js";
 export * from "./highlight-dragover.svelte.js";

package/dist/actions/index.js

@@ -2,6 +2,7 @@ export * from "./autogrow.svelte.js";
 export * from "./onboarding/onboarding.svelte.js";
 export * from "./autoscroll.js";
 export * from "./dim-behind/dim-behind.svelte.js";
+export * from "./draggable.svelte.js";
 export * from "./file-dropzone.svelte.js";
 export * from "./focus-trap.js";
 export * from "./highlight-dragover.svelte.js";

package/dist/components/AssetsPreview/_internal/AssetsPreviewContent.svelte

@@ -135,8 +135,24 @@
 
 	$effect(() => () => clearTimeout(_previewSettleTimer));
 
-	// Drag guard for area clicks (prevent click after drag/pan)
-	let _wasDragged = false;
+	// ---- Tap vs drag discrimination for area activation ----
+	// Areas activate via pointer events (pointerdown/pointerup), not a synthesized
+	// `click`. On touch the synthesized click is dropped whenever the gesture involves
+	// any movement/scroll — unreliable in general, worst on inner SVG shapes (iOS
+	// Safari) — which made small, closely-spaced area taps a no-op on mobile. A tap is
+	// a pointerup landing within TAP_SLOP_PX of its pointerdown. (Mirrors Book.svelte.)
+	const TAP_SLOP_PX = 10;
+	let _tapDownX = 0;
+	let _tapDownY = 0;
+
+	function handleTapDown(e: PointerEvent) {
+		_tapDownX = e.clientX;
+		_tapDownY = e.clientY;
+	}
+
+	function isTap(e: PointerEvent): boolean {
+		return Math.hypot(e.clientX - _tapDownX, e.clientY - _tapDownY) <= TAP_SLOP_PX;
+	}
 
 	const BUTTON_CLS = "stuic-assets-preview-control pointer-events-auto p-0!";
 
@@ -279,7 +295,6 @@
 
 	// Pan/drag handlers
 	function panStart(e: MouseEvent | TouchEvent) {
-		_wasDragged = false;
 		// Detect two-finger pinch gesture
 		if ("touches" in e && e.touches.length === 2) {
 			if (noZoom) return;
@@ -336,11 +351,6 @@
 		const newPanX = startPanX + (clientX - startMouseX);
 		const newPanY = startPanY + (clientY - startMouseY);
 
-		// Track drag for area click guard
-		if (Math.abs(clientX - startMouseX) > 3 || Math.abs(clientY - startMouseY) > 3) {
-			_wasDragged = true;
-		}
-
 		if (clampPan) {
 			const clamped = getClampedPan(newPanX, newPanY);
 			panX = clamped.x;
@@ -389,10 +399,6 @@
 		}
 
 		isPanning = false;
-		// Reset _wasDragged after a microtask so onclick handlers can check it first
-		requestAnimationFrame(() => {
-			_wasDragged = false;
-		});
 	}
 
 	async function slideToIndex(targetIdx: number, direction: "next" | "prev") {
@@ -565,6 +571,7 @@
 					use:interactable
 					bind:this={containerEl}
 					class="w-full h-full overflow-hidden flex items-center justify-center relative"
+					style:touch-action="none"
 				>
 					<img
 						use:pannable
@@ -600,7 +607,6 @@
 							style:transform-origin="center center"
 						>
 							{#each previewAsset.areas as area, i (`${area.id}-${i}`)}
-								<!-- svelte-ignore a11y_click_events_have_key_events -->
 								<!-- svelte-ignore a11y_no_static_element_interactions -->
 								<rect
 									x={area.x}
@@ -608,8 +614,9 @@
 									width={area.w}
 									height={area.h}
 									class="stuic-assets-preview-area"
-									onclick={(e: MouseEvent) => {
-										if (_wasDragged) return;
+									onpointerdown={handleTapDown}
+									onpointerup={(e: PointerEvent) => {
+										if (!isTap(e)) return;
 										e.stopPropagation();
 										onAreaClick({ area, asset: previewAsset });
 									}}

package/dist/components/Float/Float.fixture.svelte

@@ -0,0 +1,26 @@
+<script lang="ts">
+	// Float's runtime control is imperative (methods via a ref), so the browser
+	// test drives it through this fixture: it holds the `bind:this` ref and exposes
+	// testid buttons that call each method. Float props are forwarded via `...rest`.
+	import Float from "./Float.svelte";
+
+	let float = $state<Float>();
+	let { ...rest } = $props();
+</script>
+
+<button data-testid="m-minimize" onclick={() => float?.minimize()}>minimize</button>
+<button data-testid="m-expand" onclick={() => float?.expand()}>expand</button>
+<button data-testid="m-toggle" onclick={() => float?.toggleMinimize()}>toggle</button>
+<button data-testid="m-moveto" onclick={() => float?.moveTo(123, 45)}>moveTo</button>
+<button
+	data-testid="m-placement-br"
+	onclick={() => float?.moveToPlacement("bottom-right")}
+>
+	placement
+</button>
+<button data-testid="m-front" onclick={() => float?.bringToFront()}>front</button>
+
+<Float bind:this={float} title="Panel" {...rest}>
+	<input data-testid="body-input" type="text" />
+	<p>body content</p>
+</Float>

package/dist/components/Float/Float.fixture.svelte.d.ts

@@ -0,0 +1,4 @@
+import Float from "./Float.svelte";
+declare const Float: import("svelte").Component<Record<string, any>, {}, "">;
+type Float = ReturnType<typeof Float>;
+export default Float;

package/dist/components/Float/Float.svelte

@@ -0,0 +1,369 @@
+<script lang="ts" module>
+	import type { Snippet } from "svelte";
+	import type { HTMLAttributes } from "svelte/elements";
+	import type { THC } from "../Thc/Thc.svelte";
+	import type { FloatPlacement, FloatPoint } from "./float-utils.js";
+
+	let _uid = 0;
+
+	export interface Props extends Omit<
+		HTMLAttributes<HTMLDivElement>,
+		"title" | "draggable" | "class"
+	> {
+		/** Header title (rendered via `Thc`). Stays visible when minimized. */
+		title?: THC;
+		/** Initial left position in px. Overrides the `placement` x. */
+		x?: number;
+		/** Initial top position in px. Overrides the `placement` y. */
+		y?: number;
+		/** Initial placement preset, used for any axis `x`/`y` does not pin. */
+		placement?: FloatPlacement;
+		/** Edge gap (px) used when resolving `placement`. Number or `{x,y}`. */
+		offset?: number | Partial<FloatPoint>;
+		/** Panel width: a number (px) or any CSS length. Defaults to a token. */
+		width?: number | string;
+		/** Initial collapsed state. Runtime changes go through the methods below. */
+		minimized?: boolean;
+		/** Enable drag-repositioning by the header. Default `true`. */
+		draggable?: boolean;
+		/** Show the close `×` and enable `close()` / Escape. Default `false`. */
+		closable?: boolean;
+		/** Called by `close()`, the `×` button, and Escape (when closable). */
+		onClose?: () => void;
+		/** Close on Escape when `closable`. Default `true`. */
+		closeOnEscape?: boolean;
+		/** Raise above sibling Floats on pointerdown. Default `true`. */
+		bringToFrontOnClick?: boolean;
+		/**
+		 * Opt-in persistence key. When set, `{x, y, minimized}` is remembered
+		 * across reloads in localStorage under `stuic-float-<storageKey>`.
+		 */
+		storageKey?: string;
+		/** Minimum gap kept from every viewport edge while clamping. Default `0`. */
+		margin?: number;
+		/** Accessible labels for the built-in buttons. */
+		minimizeLabel?: string;
+		restoreLabel?: string;
+		closeLabel?: string;
+		/** Leading header slot (e.g. a grip/icon). Drag still works over it. */
+		icon?: Snippet;
+		/** Header actions slot, placed left of the minimize/close buttons. */
+		actions?: Snippet;
+		/** Body content (hidden when minimized). */
+		children?: Snippet;
+		/** Root element classes (merged). */
+		class?: string;
+		classHeader?: string;
+		classTitle?: string;
+		classActions?: string;
+		classBody?: string;
+		/** Drop all default styling (still positioned/draggable). */
+		unstyled?: boolean;
+		/** Bindable root element reference. */
+		el?: HTMLDivElement;
+	}
+</script>
+
+<script lang="ts">
+	import { untrack } from "svelte";
+	import { twMerge } from "../../utils/tw-merge.js";
+	import { localStorageState } from "../../utils/persistent-state.svelte.js";
+	import { draggable as draggableAction } from "../../actions/draggable.svelte.js";
+	import { iconChevronDown, iconX } from "../../icons/index.js";
+	import Thc, { isTHCNotEmpty } from "../Thc/Thc.svelte";
+	import { clampToViewport, resolvePlacement, type FloatSize } from "./float-utils.js";
+	import { nextFloatOrder } from "./float-stack.js";
+
+	let {
+		title,
+		x: xProp,
+		y: yProp,
+		placement = "top-right",
+		offset = 16,
+		width,
+		minimized: minimizedProp = false,
+		draggable = true,
+		closable = false,
+		onClose,
+		closeOnEscape = true,
+		bringToFrontOnClick = true,
+		storageKey,
+		margin = 0,
+		minimizeLabel = "Minimize",
+		restoreLabel = "Restore",
+		closeLabel = "Close",
+		icon,
+		actions,
+		children,
+		class: classProp,
+		classHeader,
+		classTitle,
+		classActions,
+		classBody,
+		unstyled = false,
+		el = $bindable(),
+		...rest
+	}: Props = $props();
+
+	const titleId = `stuic-float-title-${_uid++}`;
+
+	// reactive runtime state. `minimizedProp`/`storageKey` are initial-only by
+	// design (runtime changes flow through the methods), so we capture them once.
+	let x = $state(0);
+	let y = $state(0);
+	let minimized = $state(untrack(() => minimizedProp));
+	let dragging = $state(false);
+	let zOrder = $state(0);
+	let initialized = $state(false);
+
+	// optional persistence (created once; key is not expected to change)
+	type Persisted = { x: number | null; y: number | null; minimized: boolean };
+	const persist = untrack(() =>
+		storageKey
+			? localStorageState<Persisted>(`stuic-float-${storageKey}`, {
+					x: null,
+					y: null,
+					minimized: minimizedProp,
+				})
+			: null
+	);
+
+	function viewport(): FloatSize {
+		if (typeof window === "undefined") return { width: 0, height: 0 };
+		return { width: window.innerWidth, height: window.innerHeight };
+	}
+
+	function currentSize(): FloatSize {
+		return { width: el?.offsetWidth ?? 0, height: el?.offsetHeight ?? 0 };
+	}
+
+	// Persist imperatively (not via an $effect): an effect that writes persist.current
+	// while the init effect reads it forms a reactive cycle, and it would also hit
+	// localStorage on every pointermove. We save at meaningful end points instead.
+	function persistNow() {
+		if (persist) persist.current = { x, y, minimized };
+	}
+
+	// one-time position resolution (stored -> explicit x/y -> placement)
+	$effect(() => {
+		if (initialized || !el) return;
+
+		// read the stored value once, untracked (no reactive dependency on it)
+		const stored = persist ? untrack(() => persist.current) : undefined;
+		if (stored && stored.x != null && stored.y != null) {
+			x = stored.x;
+			y = stored.y;
+			if (typeof stored.minimized === "boolean") minimized = stored.minimized;
+		} else {
+			const base = resolvePlacement(placement, currentSize(), viewport(), offset);
+			const next = clampToViewport(
+				{ x: xProp ?? base.x, y: yProp ?? base.y },
+				currentSize(),
+				viewport(),
+				margin
+			);
+			x = next.x;
+			y = next.y;
+		}
+
+		zOrder = nextFloatOrder();
+		initialized = true;
+	});
+
+	// keep inside the viewport on window resize
+	$effect(() => {
+		if (typeof window === "undefined") return;
+		function onResize() {
+			if (!initialized) return;
+			const next = clampToViewport({ x, y }, currentSize(), viewport(), margin);
+			x = next.x;
+			y = next.y;
+			persistNow();
+		}
+		window.addEventListener("resize", onResize);
+		return () => window.removeEventListener("resize", onResize);
+	});
+
+	// --- drag wiring -------------------------------------------------------------
+	let dragStart = { x: 0, y: 0 };
+	let lastDragMoved = false;
+
+	function onDragStart() {
+		dragStart = { x, y };
+		dragging = true;
+		lastDragMoved = false;
+	}
+	function onDragMove({ dx, dy }: { dx: number; dy: number }) {
+		const next = clampToViewport(
+			{ x: dragStart.x + dx, y: dragStart.y + dy },
+			currentSize(),
+			viewport(),
+			margin
+		);
+		x = next.x;
+		y = next.y;
+	}
+	function onDragEnd({ moved }: { moved: boolean }) {
+		dragging = false;
+		lastDragMoved = moved;
+		if (moved) persistNow();
+	}
+
+	function onRootPointerDown() {
+		if (bringToFrontOnClick) bringToFront();
+	}
+
+	function onHeaderDblClick(e: MouseEvent) {
+		// ignore the dbl-click synthesized right after a real drag
+		if (lastDragMoved) {
+			lastDragMoved = false;
+			return;
+		}
+		if ((e.target as Element)?.closest?.("[data-no-drag]")) return;
+		toggleMinimize();
+	}
+
+	function onRootKeydown(e: KeyboardEvent) {
+		if (e.key === "Escape" && closable && closeOnEscape) {
+			e.stopPropagation();
+			close();
+		}
+	}
+
+	// --- imperative API (via bind:this) -----------------------------------------
+	/** Move to an absolute `(x, y)` (clamped into the viewport). */
+	export function moveTo(nx: number, ny: number) {
+		const next = clampToViewport({ x: nx, y: ny }, currentSize(), viewport(), margin);
+		x = next.x;
+		y = next.y;
+		persistNow();
+	}
+	/** Move to a named placement preset (optionally with a custom offset). */
+	export function moveToPlacement(
+		a: FloatPlacement,
+		o: number | Partial<FloatPoint> = offset
+	) {
+		const p = resolvePlacement(a, currentSize(), viewport(), o);
+		x = p.x;
+		y = p.y;
+		persistNow();
+	}
+	/** Current top-left position. */
+	export function getPosition(): FloatPoint {
+		return { x, y };
+	}
+	/** Collapse to the title bar. */
+	export function minimize() {
+		minimized = true;
+		persistNow();
+	}
+	/** Expand the body. */
+	export function expand() {
+		minimized = false;
+		persistNow();
+	}
+	/** Toggle minimized state. */
+	export function toggleMinimize() {
+		minimized = !minimized;
+		persistNow();
+	}
+	/** Whether currently minimized. */
+	export function isMinimized(): boolean {
+		return minimized;
+	}
+	/** Fire `onClose` (consumer decides to unmount). */
+	export function close() {
+		onClose?.();
+	}
+	/** Raise above sibling Floats. */
+	export function bringToFront() {
+		zOrder = nextFloatOrder();
+	}
+
+	// --- derived presentation ----------------------------------------------------
+	const cssWidth = $derived(
+		width == null ? undefined : typeof width === "number" ? `${width}px` : width
+	);
+</script>
+
+<!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
+<div
+	bind:this={el}
+	{...rest}
+	class={twMerge(unstyled ? "" : "stuic-float", classProp)}
+	role="dialog"
+	aria-modal="false"
+	aria-labelledby={isTHCNotEmpty(title) ? titleId : undefined}
+	data-minimized={minimized}
+	data-dragging={dragging}
+	data-draggable={draggable}
+	style:left="{x}px"
+	style:top="{y}px"
+	style:width={cssWidth}
+	style:visibility={initialized ? undefined : "hidden"}
+	style:--stuic-float-z-order={zOrder}
+	onpointerdown={onRootPointerDown}
+	onkeydown={onRootKeydown}
+>
+	<!-- svelte-ignore a11y_no_static_element_interactions -->
+	<div
+		class={twMerge(unstyled ? "" : "stuic-float-header", classHeader)}
+		ondblclick={onHeaderDblClick}
+		use:draggableAction={() => ({
+			enabled: draggable,
+			ignore: "[data-no-drag]",
+			onStart: onDragStart,
+			onMove: onDragMove,
+			onEnd: onDragEnd,
+		})}
+	>
+		{#if icon}
+			<span class={unstyled ? "" : "stuic-float-icon"}>{@render icon()}</span>
+		{/if}
+
+		<div id={titleId} class={twMerge(unstyled ? "" : "stuic-float-title", classTitle)}>
+			{#if isTHCNotEmpty(title)}<Thc thc={title!} />{/if}
+		</div>
+
+		<div
+			class={twMerge(unstyled ? "" : "stuic-float-actions", classActions)}
+			data-no-drag
+		>
+			{#if actions}{@render actions()}{/if}
+
+			<button
+				type="button"
+				class={unstyled ? "" : "stuic-float-btn"}
+				data-no-drag
+				aria-label={minimized ? restoreLabel : minimizeLabel}
+				title={minimized ? restoreLabel : minimizeLabel}
+				onclick={toggleMinimize}
+			>
+				<span class={unstyled ? "" : "stuic-float-chevron"}>
+					{@html iconChevronDown({ size: 16 })}
+				</span>
+			</button>
+
+			{#if closable}
+				<button
+					type="button"
+					class={unstyled ? "" : "stuic-float-btn"}
+					data-no-drag
+					aria-label={closeLabel}
+					title={closeLabel}
+					onclick={() => close()}
+				>
+					{@html iconX({ size: 16 })}
+				</button>
+			{/if}
+		</div>
+	</div>
+
+	<div class={unstyled ? "" : "stuic-float-body-wrap"}>
+		<div class={unstyled ? "" : "stuic-float-body-inner"}>
+			<div class={twMerge(unstyled ? "" : "stuic-float-body", classBody)}>
+				{@render children?.()}
+			</div>
+		</div>
+	</div>
+</div>