useMergeRefs

Author: huntabyte

packages/floating-ui-svelte/src/hooks/use-merge-refs.svelte.ts

@@ -0,0 +1,67 @@
+import type { ReferenceType } from "../types.js";
+import { FloatingState } from "./use-floating.svelte.js";
+
+interface BoxedRef {
+	current: ReferenceType | null;
+}
+
+/**
+ * Merges the references of either floating instances or refs into a single reference
+ * that can be accessed and set via the `.current` property.
+ */
+class MergeRefs {
+	#current = $state<ReferenceType | null>(null);
+	constructor(
+		private readonly floatingOrRef: Array<FloatingState | BoxedRef>,
+	) {}
+
+	get current() {
+		return this.#current;
+	}
+
+	set current(node: ReferenceType | null) {
+		for (const arg of this.floatingOrRef) {
+			if (arg instanceof FloatingState) {
+				arg.reference = node;
+				continue;
+			}
+			arg.current = node;
+		}
+		this.#current = node;
+	}
+}
+
+/**
+ * Use the same reference for multiple floating instances at once.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { useMergeRefs, useFloating, type BoxedRef } from "@skeletonlabs/floating-ui-svelte";
+ *   const tooltip = useFloating();
+ *   const menu = useFloating()
+ *
+ *   let someOtherRef: BoxedRef = $state({ current: null })
+ *
+ *   const tooltipInt = useInteractions([])
+ *   const menuInt = useInteractions([])
+ *
+ *   const ref = useMergeRefs([tooltip, menu, someOtherRef])
+ *   const props = $derived(tooltipInt.getReferenceProps(menuInt.getReferenceProps()))
+ * </script>
+ *
+ * <button bind:this={ref.current} {...props}>
+ * 	<!-- ... -->
+ * </button>
+ *```
+ *
+ *
+ * @param floatingInstances
+ * @returns
+ */
+function useMergeRefs(refLikes: Array<FloatingState | BoxedRef>) {
+	return new MergeRefs(refLikes);
+}
+
+export { MergeRefs, useMergeRefs };
+export type { BoxedRef };

packages/floating-ui-svelte/test/hooks/use-click.ts renamed to packages/floating-ui-svelte/test/hooks/use-click.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it, vi } from "vitest";
+import { useFloating } from "../../src/index.js";
+import { withRunes } from "../internal/with-runes.svelte.js";
+import {
+	useMergeRefs,
+	type BoxedRef,
+} from "../../src/hooks/use-merge-refs.svelte.js";
+
+describe("useMergeRefs", () => {
+	vi.mock(import("svelte"), async (importOriginal) => {
+		const actual = await importOriginal();
+		return {
+			...actual,
+			getContext: vi.fn().mockReturnValue(null),
+		};
+	});
+
+	it(
+		"merges the references of multiple floating instances or other boxed elements",
+		withRunes(() => {
+			const ref1 = useFloating();
+			const ref2 = useFloating();
+			const ref3: BoxedRef = $state({ current: null });
+
+			const mergedRef = useMergeRefs([ref1, ref2, ref3]);
+			expect(mergedRef.current).toBe(null);
+			expect(ref1.reference).toBe(null);
+			expect(ref2.reference).toBe(null);
+			expect(ref3.current).toBe(null);
+
+			const node = document.createElement("div");
+			mergedRef.current = node;
+			expect(mergedRef.current).toBe(node);
+			expect(ref1.reference).toBe(node);
+			expect(ref2.reference).toBe(node);
+			expect(ref3.current).toBe(node);
+			mergedRef.current = null;
+			expect(mergedRef.current).toBe(null);
+			expect(ref1.reference).toBe(null);
+			expect(ref2.reference).toBe(null);
+			expect(ref3.current).toBe(null);
+		}),
+	);
+});

packages/floating-ui-svelte/test/hooks/use-dismiss.ts renamed to packages/floating-ui-svelte/test/hooks/use-dismiss.test.ts

@@ -1,21 +1,20 @@
 <script lang="ts">
-import CodeBlock from "$lib/components/CodeBlock/CodeBlock.svelte";
-import Table from "$lib/components/Table/Table.svelte";
-import { tableProps } from "./data.js";
+	import CodeBlock from "$lib/components/CodeBlock/CodeBlock.svelte";
+	import Table from "$lib/components/Table/Table.svelte";
+	import { tableProps } from "./data.js";
 </script>
 
 <div class="space-y-10">
 	<!-- Header -->
 	<header class="card card-gradient space-y-8">
 		<h1 class="h1"><span>FloatingArrow</span></h1>
 		<p>
-			Renders a customizable <code class="code">{'<svg>'}</code> pointing arrow triangle inside the floating
-			element that gets automatically positioned.
+			Renders a customizable <code class="code">{"<svg>"}</code> pointing arrow
+			triangle inside the floating element that gets automatically positioned.
 		</p>
 		<CodeBlock
 			lang="ts"
-			code={`import { FloatingArrow } from '@skeletonlabs/floating-ui-svelte';`}
-		/>
+			code={`import { FloatingArrow } from '@skeletonlabs/floating-ui-svelte';`} />
 	</header>
 	<!-- Usage -->
 	<section class="space-y-8">
@@ -35,8 +34,7 @@ const floating = useFloating({
 		];
 	}
 });
-`}
-		/>
+`} />
 		<CodeBlock
 			lang="svelte"
 			code={`
@@ -57,8 +55,7 @@ const floating = useFloating({
 		context="{floating.context}"
 	/>
 </div>
-		`}
-		/>
+		`} />
 	</section>
 	<!-- Table: Props -->
 	<section class="space-y-8">
@@ -69,7 +66,9 @@ const floating = useFloating({
 	<section class="space-y-8">
 		<h2 class="h2">Utility Classes and Styles</h2>
 		<p>Provide arbitrary utility classes using the standard attribute.</p>
-		<CodeBlock lang="svelte" code={`<FloatingArrow class="fill-white" />`} />
+		<CodeBlock
+			lang="svelte"
+			code={`<FloatingArrow class="fill-white" />`} />
 	</section>
 	<!-- Compare -->
 	<section class="space-y-8">

packages/floating-ui-svelte/test/hooks/use-floating.svelte.ts renamed to packages/floating-ui-svelte/test/hooks/use-floating.test.svelte.ts

@@ -1,25 +1,24 @@
 <script lang="ts">
-import {
-	useClick,
-	useFloating,
-	useInteractions,
-} from "@skeletonlabs/floating-ui-svelte";
+	import {
+		useClick,
+		useFloating,
+		useInteractions,
+	} from "@skeletonlabs/floating-ui-svelte";
 
-const floating = useFloating();
-const click = useClick(floating.context);
-const interactions = useInteractions([click]);
+	const floating = useFloating();
+	const click = useClick(floating.context);
+	const interactions = useInteractions([click]);
 </script>
 
 <!-- Reference Element -->
-<button bind:this={floating.elements.reference} {...interactions.getReferenceProps()}>
+<button bind:this={floating.reference} {...interactions.getReferenceProps()}>
 	Reference
 </button>
 
 <!-- Floating Element -->
 <div
-	bind:this={floating.elements.floating}
+	bind:this={floating.floating}
 	style={floating.floatingStyles}
-	{...interactions.getFloatingProps()}
->
+	{...interactions.getFloatingProps()}>
 	Floating
 </div>

packages/floating-ui-svelte/test/hooks/use-focus.ts renamed to packages/floating-ui-svelte/test/hooks/use-focus.test.ts

@@ -1,25 +1,24 @@
 <script lang="ts">
-import {
-	useDismiss,
-	useFloating,
-	useInteractions,
-} from "@skeletonlabs/floating-ui-svelte";
+	import {
+		useDismiss,
+		useFloating,
+		useInteractions,
+	} from "@skeletonlabs/floating-ui-svelte";
 
-const floating = useFloating();
-const dismiss = useDismiss(floating.context);
-const interactions = useInteractions([dismiss]);
+	const floating = useFloating();
+	const dismiss = useDismiss(floating.context);
+	const interactions = useInteractions([dismiss]);
 </script>
 
 <!-- Reference Element -->
-<button bind:this={floating.elements.reference} {...interactions.getReferenceProps()}>
+<button bind:this={floating.reference} {...interactions.getReferenceProps()}>
 	Reference
 </button>
 
 <!-- Floating Element -->
 <div
-	bind:this={floating.elements.floating}
+	bind:this={floating.floating}
 	style={floating.floatingStyles}
-	{...interactions.getFloatingProps()}
->
+	{...interactions.getFloatingProps()}>
 	Floating
 </div>

packages/floating-ui-svelte/test/hooks/use-hover.ts renamed to packages/floating-ui-svelte/test/hooks/use-hover.test.ts

@@ -1,28 +1,34 @@
 <script lang="ts">
-import CodeBlock from "$lib/components/CodeBlock/CodeBlock.svelte";
-import Table from "$lib/components/Table/Table.svelte";
-import { tableOptions, tableReturns } from "./data.js";
+	import CodeBlock from "$lib/components/CodeBlock/CodeBlock.svelte";
+	import Table from "$lib/components/Table/Table.svelte";
+	import { tableOptions, tableReturns } from "./data.js";
 </script>
 
 <div class="space-y-10">
 	<!-- Header -->
 	<header class="card card-gradient space-y-8">
 		<h1 class="h1"><span>useFloating</span></h1>
 		<p>
-			The main Hook of the library that acts as a controller for all other Hooks and components.
+			The main Hook of the library that acts as a controller for all other
+			Hooks and components.
 		</p>
-		<CodeBlock lang="ts" code={`import { useFloating } from '@skeletonlabs/floating-ui-svelte';`} />
+		<CodeBlock
+			lang="ts"
+			code={`import { useFloating } from '@skeletonlabs/floating-ui-svelte';`} />
 	</header>
 	<!-- Usage -->
 	<section class="space-y-8">
 		<h2 class="h2">Usage</h2>
 		<p>
-			The <code class="code">useFloating</code> Svelte hook acts as a controller for all other Floating
-			UI Svelte features. It handles positioning your floating elements (tooltips, popovers, etc.) relative
-			to an anchored element. Automatically calculates the best placement and updates it as needed, providing
-			access to properties for position and style.
+			The <code class="code">useFloating</code> Svelte hook acts as a controller
+			for all other Floating UI Svelte features. It handles positioning your
+			floating elements (tooltips, popovers, etc.) relative to an anchored
+			element. Automatically calculates the best placement and updates it as
+			needed, providing access to properties for position and style.
 		</p>
-		<CodeBlock lang="ts" code={`const floating = useFloating({\n\t/* options */\n});`} />
+		<CodeBlock
+			lang="ts"
+			code={`const floating = useFloating({\n\t/* options */\n});`} />
 		<CodeBlock
 			lang="html"
 			code={`
@@ -38,13 +44,15 @@ import { tableOptions, tableReturns } from "./data.js";
 >
 	Floating
 </div>
-		`}
-		/>
+		`} />
 	</section>
 	<!-- Alert: Destructuring -->
 	<div class="alert">
 		<h3 class="h3">Note</h3>
-		<p>Destructured variables are not supported as this would break reactivity.</p>
+		<p>
+			Destructured variables are not supported as this would break
+			reactivity.
+		</p>
 	</div>
 	<!-- Table: Options -->
 	<section class="space-y-8">

packages/floating-ui-svelte/test/hooks/use-id.ts renamed to packages/floating-ui-svelte/test/hooks/use-id.test.ts

@@ -1,30 +1,34 @@
 <script lang="ts">
-import CodeBlock from "$lib/components/CodeBlock/CodeBlock.svelte";
-import Table from "$lib/components/Table/Table.svelte";
-import ExampleRaw from "./Example.svelte?raw";
-import { tableOptions } from "./data.js";
+	import CodeBlock from "$lib/components/CodeBlock/CodeBlock.svelte";
+	import Table from "$lib/components/Table/Table.svelte";
+	import ExampleRaw from "./Example.svelte?raw";
+	import { tableOptions } from "./data.js";
 </script>
 
 <div class="space-y-10">
 	<!-- Header -->
 	<header class="card card-gradient space-y-8">
 		<h1 class="h1"><span>useFocus</span></h1>
 		<p>
-			Opens the floating element while the reference element has focus, like CSS
+			Opens the floating element while the reference element has focus,
+			like CSS
 			<code class="code">:focus</code>.
 		</p>
-		<CodeBlock lang="ts" code={`import { useFocus } from '@skeletonlabs/floating-ui-svelte';`} />
+		<CodeBlock
+			lang="ts"
+			code={`import { useFocus } from '@skeletonlabs/floating-ui-svelte';`} />
 		<!-- TODO: add when FloatingFocusManager is ready -->
 		<!-- <p>To manage focus within the floating element itself, use <a class="anchor" href="/api/floating-focus-manager">FloatingFocusManager</a>.</p> -->
 	</header>
 	<!-- Usage -->
 	<section class="space-y-8">
 		<h2 class="h2">Usage</h2>
 		<p>
-			This Hook returns event handler props. To use it, pass it the context object returned from <code
-				class="code">useFloating()</code
-			>, and then feed its result into the <code class="code">useInteractions()</code> array. The returned
-			prop getters are then spread onto the elements for rendering.
+			This Hook returns event handler props. To use it, pass it the
+			context object returned from <code class="code">useFloating()</code
+			>, and then feed its result into the
+			<code class="code">useInteractions()</code> array. The returned prop
+			getters are then spread onto the elements for rendering.
 		</p>
 		<CodeBlock code={ExampleRaw} lang="svelte" mark={[2, 5, 6]} />
 	</section>

packages/floating-ui-svelte/test/hooks/use-interactions.svelte.ts renamed to packages/floating-ui-svelte/test/hooks/use-interactions.test.svelte.ts

@@ -1,25 +1,24 @@
 <script lang="ts">
-import {
-	useFloating,
-	useFocus,
-	useInteractions,
-} from "@skeletonlabs/floating-ui-svelte";
+	import {
+		useFloating,
+		useFocus,
+		useInteractions,
+	} from "@skeletonlabs/floating-ui-svelte";
 
-const floating = useFloating();
-const focus = useFocus(floating.context);
-const interactions = useInteractions([focus]);
+	const floating = useFloating();
+	const focus = useFocus(floating.context);
+	const interactions = useInteractions([focus]);
 </script>
 
 <!-- Reference Element -->
-<button bind:this={floating.elements.reference} {...interactions.getReferenceProps()}>
+<button bind:this={floating.reference} {...interactions.getReferenceProps()}>
 	Reference
 </button>
 
 <!-- Floating Element -->
 <div
-	bind:this={floating.elements.floating}
+	bind:this={floating.floating}
 	style={floating.floatingStyles}
-	{...interactions.getFloatingProps()}
->
+	{...interactions.getFloatingProps()}>
 	Floating
 </div>