refactor!: update integration usage to pass target as first param

Author: danielwaltz

README.md

@@ -79,7 +79,7 @@ import { useRef } from 'react';
 export function App() {
   const targetEl = useRef<HTMLElement>(null);
 
-  useAdhesive({ target: targetEl, position: 'top' });
+  useAdhesive(targetEl, { position: 'top' });
 
   return (
     <div>
@@ -124,7 +124,7 @@ import { useTemplateRef } from 'vue';
 
 const targetEl = useTemplateRef('target');
 
-useAdhesive({ target: targetEl }, { position: 'top' });
+useAdhesive(targetEl, { position: 'top' });
 </script>
 
 <template>

packages/react/README.md

@@ -72,8 +72,9 @@ export function App() {
   const [position, setPosition] = useState<AdhesivePosition>('top');
 
   useAdhesive(
-    { target: targetEl, bounding: boundingEl },
+    targetEl,
     {
+      boundingEl,
       position,
       offset: 20,
       enabled,
@@ -133,13 +134,14 @@ For more control over the sticky behavior.
 
 **Parameters:**
 
-- `elements`: Object with `target` (required) and `bounding` (optional) refs
+- `target`: React ref object for the element that should become sticky
 - `options`: Configuration options (optional)
 
 **UseAdhesiveOptions:**
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
+| `boundingEl` | `React.RefObject` \| `string` | `undefined` | The element that defines the sticky boundaries |
 | `position` | `'top' \| 'bottom'` | `'top'` | Where the element should stick |
 | `offset` | `number` | `0` | Offset in pixels from the position |
 | `zIndex` | `number` | `1` | Z-index for the fixed element |

packages/react/src/components/AdhesiveContainer.tsx

@@ -1,9 +1,5 @@
 import { useMemo, useRef, type ComponentProps } from "react";
-import {
-  useAdhesive,
-  type UseAdhesiveElements,
-  type UseAdhesiveOptions,
-} from "../hooks/useAdhesive.js";
+import { useAdhesive, type UseAdhesiveOptions } from "../hooks/useAdhesive.js";
 
 export type AdhesiveContainerProps = Partial<UseAdhesiveOptions> &
   ComponentProps<"div">;
@@ -32,12 +28,7 @@ export function AdhesiveContainer({
   children,
   ...rest
 }: AdhesiveContainerProps) {
-  const targetEl = useRef<HTMLDivElement>(null);
-
-  const elements = useMemo<UseAdhesiveElements>(
-    () => ({ target: targetEl }),
-    [],
-  );
+  const targetRef = useRef<HTMLDivElement>(null);
 
   const options = useMemo<UseAdhesiveOptions>(
     () => ({
@@ -64,10 +55,10 @@ export function AdhesiveContainer({
     ],
   );
 
-  useAdhesive(elements, options);
+  useAdhesive(targetRef, options);
 
   return (
-    <div ref={targetEl} {...rest}>
+    <div ref={targetRef} {...rest}>
       {children}
     </div>
   );

packages/react/src/hooks/useAdhesive.ts

@@ -1,21 +1,15 @@
 import { Adhesive, type AdhesiveOptions } from "@adhesivejs/core";
-import { useEffect, useRef, type RefObject } from "react";
+import { useEffect, useRef } from "react";
+import {
+  unrefElement,
+  type MaybeElementOrSelectorRef,
+} from "../utils/unrefElement.js";
 
-/**
- * Template ref objects for React elements used by the Adhesive hook.
- */
-export interface UseAdhesiveElements {
-  /** React ref to the element that should become sticky */
-  target: RefObject<HTMLDivElement | null | undefined>;
-  /** Optional React ref to the element that defines sticky boundaries */
-  bounding?: RefObject<HTMLDivElement | null | undefined> | null;
-}
-
-/**
- * Configuration options for the `useAdhesive` hook.
- * Excludes `targetEl` and `boundingEl` since they're provided via template refs.
- */
-export type UseAdhesiveOptions = Partial<Omit<AdhesiveOptions, "targetEl">>;
+export type UseAdhesiveOptions = Partial<
+  Omit<AdhesiveOptions, "targetEl" | "boundingEl">
+> & {
+  boundingEl?: AdhesiveOptions["boundingEl"] | MaybeElementOrSelectorRef;
+};
 
 /**
  * React hook for adding sticky positioning behavior to DOM elements.
@@ -24,8 +18,8 @@ export type UseAdhesiveOptions = Partial<Omit<AdhesiveOptions, "targetEl">>;
  * handling initialization, updates, and cleanup. It integrates seamlessly
  * with React's ref system and component lifecycle.
  *
- * @param elements - Object containing React refs for target and optional bounding elements
- * @param options - Configuration options for sticky behavior (excluding element references)
+ * @param target - React ref for the element that should become sticky
+ * @param options - Configuration options for sticky behavior
  *
  * @example
  * ```tsx
@@ -37,8 +31,8 @@ export type UseAdhesiveOptions = Partial<Omit<AdhesiveOptions, "targetEl">>;
  *   const boundingEl = useRef<HTMLDivElement>(null);
  *
  *   useAdhesive(
- *     { target: targetEl, bounding: boundingEl },
- *     { position: 'top' }
+ *     targetEl,
+ *     { boundingEl, position: 'top' }
  *   );
  *
  *   return (
@@ -50,12 +44,12 @@ export type UseAdhesiveOptions = Partial<Omit<AdhesiveOptions, "targetEl">>;
  * ```
  */
 export function useAdhesive(
-  elements: UseAdhesiveElements,
+  target: MaybeElementOrSelectorRef,
   options?: UseAdhesiveOptions,
 ) {
   function getValidatedOptions() {
-    const targetEl = elements.target.current;
-    const boundingEl = elements.bounding?.current ?? options?.boundingEl;
+    const targetEl = unrefElement(target);
+    const boundingEl = unrefElement(options?.boundingEl);
 
     if (!targetEl) {
       throw new Error("@adhesivejs/react: sticky element is not defined");
@@ -73,7 +67,7 @@ export function useAdhesive(
       adhesive.current?.cleanup();
       adhesive.current = null;
     };
-  }, [elements.target]);
+  }, [target]);
 
   useEffect(() => {
     if (!adhesive.current) return;

packages/react/src/index.ts

@@ -8,11 +8,7 @@ export {
   type AdhesiveStatus,
 } from "@adhesivejs/core";
 
-export {
-  useAdhesive,
-  type UseAdhesiveElements,
-  type UseAdhesiveOptions,
-} from "./hooks/useAdhesive.js";
+export { useAdhesive, type UseAdhesiveOptions } from "./hooks/useAdhesive.js";
 
 export {
   AdhesiveContainer,

packages/react/src/utils/unrefElement.ts

@@ -0,0 +1,27 @@
+import type { RefObject } from "react";
+
+type MaybeElementRefObject = RefObject<HTMLElement | HTMLDivElement | null>;
+
+export type MaybeElementOrSelectorRef =
+  | MaybeElementRefObject
+  | HTMLElement
+  | string
+  | null
+  | undefined;
+
+type UnRefElementReturn = HTMLElement | string | null | undefined;
+
+export function unrefElement(
+  elOrSelectorRef: MaybeElementOrSelectorRef,
+): UnRefElementReturn {
+  // Handle React ref objects by accessing their .current property
+  // For non-ref values, return them as-is
+  if (
+    elOrSelectorRef &&
+    typeof elOrSelectorRef === "object" &&
+    "current" in elOrSelectorRef
+  ) {
+    return elOrSelectorRef.current;
+  }
+  return elOrSelectorRef as UnRefElementReturn;
+}

packages/vue/README.md

@@ -77,8 +77,9 @@ const enabled = ref(true);
 const position = ref<AdhesivePosition>('top');
 
 useAdhesive(
-  { target: targetEl, bounding: boundingEl },
+  targetEl,
   () => ({
+    boundingEl: boundingEl.value,
     position: position.value,
     offset: 20,
     enabled: enabled.value,
@@ -128,7 +129,7 @@ A simple wrapper component that automatically applies sticky positioning to its
 <AdhesiveContainer
   position="bottom"
   :offset="30"
-  className="custom-class"
+  class="custom-class"
 >
   Content to make sticky
 </AdhesiveContainer>
@@ -140,13 +141,14 @@ For more control over the sticky behavior with full Vue reactivity support.
 
 **Parameters:**
 
-- `elements`: Object with `target` (required) and `bounding` (optional) template refs
+- `target`: Vue template ref for the element that should become sticky
 - `options`: Reactive configuration options (optional, can be a ref or getter function)
 
 **UseAdhesiveOptions:**
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
+| `boundingEl` | `TemplateRef` \| `string` | `undefined` | The element that defines the sticky boundaries |
 | `position` | `'top' \| 'bottom'` | `'top'` | Where the element should stick |
 | `offset` | `number` | `0` | Offset in pixels from the position |
 | `zIndex` | `number` | `1` | Z-index for the fixed element |

packages/vue/src/components/AdhesiveContainer.vue

@@ -2,7 +2,6 @@
 import { computed, useTemplateRef } from "vue";
 import {
   useAdhesive,
-  type UseAdhesiveElements,
   type UseAdhesiveOptions,
 } from "../composables/useAdhesive";
 
@@ -47,11 +46,7 @@ const {
   releasedClass,
 } = defineProps<AdhesiveContainerProps>();
 
-const targetEl = useTemplateRef("target");
-
-const elements = {
-  target: targetEl,
-} satisfies UseAdhesiveElements;
+const targetRef = useTemplateRef("target");
 
 const options = computed<UseAdhesiveOptions>(() => ({
   boundingEl,
@@ -65,7 +60,7 @@ const options = computed<UseAdhesiveOptions>(() => ({
   releasedClassName: releasedClass,
 }));
 
-useAdhesive(elements, options);
+useAdhesive(targetRef, options);
 </script>
 
 <template>

packages/vue/src/composables/useAdhesive.ts

@@ -8,24 +8,14 @@ import {
 } from "vue";
 import {
   unrefElement,
-  type MaybeComputedElementRef,
+  type MaybeElementOrSelectorRef,
 } from "../utils/unrefElement.js";
 
-/**
- * Template ref objects for Vue elements used by the Adhesive composable.
- */
-export interface UseAdhesiveElements {
-  /** Vue template ref or element that should become sticky */
-  target: MaybeComputedElementRef;
-  /** Optional Vue template ref or element that defines sticky boundaries */
-  bounding?: MaybeComputedElementRef;
-}
-
-/**
- * Configuration options for the `useAdhesive` composable.
- * Excludes `targetEl` and `boundingEl` since they're provided via template refs.
- */
-export type UseAdhesiveOptions = Partial<Omit<AdhesiveOptions, "targetEl">>;
+export type UseAdhesiveOptions = Partial<
+  Omit<AdhesiveOptions, "targetEl" | "boundingEl">
+> & {
+  boundingEl?: AdhesiveOptions["boundingEl"] | MaybeElementOrSelectorRef;
+};
 
 /**
  * Vue composable for adding sticky positioning behavior to DOM elements.
@@ -34,8 +24,8 @@ export type UseAdhesiveOptions = Partial<Omit<AdhesiveOptions, "targetEl">>;
  * handling initialization, updates, and cleanup. It integrates seamlessly
  * with Vue's reactivity system and component lifecycle.
  *
- * @param elements - Object containing Vue refs for target and optional bounding elements
- * @param options - Reactive configuration options for sticky behavior (excluding element references)
+ * @param target - Vue template ref for the element that should become sticky
+ * @param options - Reactive configuration options for sticky behavior
  *
  * @example
  * ```vue
@@ -47,8 +37,8 @@ export type UseAdhesiveOptions = Partial<Omit<AdhesiveOptions, "targetEl">>;
  * const boundingEl = useTemplateRef('bounding');
  *
  * useAdhesive(
- *   { target: targetEl, bounding: boundingEl },
- *   { position: 'top' }
+ *   targetEl,
+ *   () => ({ boundingEl: boundingEl.value, position: 'top' })
  * );
  * </script>
  *
@@ -70,24 +60,23 @@ export type UseAdhesiveOptions = Partial<Omit<AdhesiveOptions, "targetEl">>;
  * const offset = ref(10);
  *
  * // Reactive options
- * useAdhesive({ target: targetEl }, () => ({
- *   position: 'top'
+ * useAdhesive(targetEl, () => ({
+ *   position: 'top',
  *   enabled: enabled.value,
  *   offset: offset.value,
  * }));
  * </script>
  * ```
  */
 export function useAdhesive(
-  elements: UseAdhesiveElements,
+  target: MaybeElementOrSelectorRef,
   options?: MaybeRefOrGetter<UseAdhesiveOptions>,
 ) {
   function getValidatedOptions() {
     const optionsValue = toValue(options);
 
-    const targetEl = unrefElement(elements.target);
-    const boundingEl =
-      unrefElement(elements.bounding) ?? optionsValue?.boundingEl;
+    const targetEl = unrefElement(target);
+    const boundingEl = unrefElement(optionsValue?.boundingEl);
 
     if (!targetEl) {
       throw new Error("@adhesivejs/vue: sticky element is not defined");

packages/vue/src/index.ts

@@ -10,7 +10,6 @@ export {
 
 export {
   useAdhesive,
-  type UseAdhesiveElements,
   type UseAdhesiveOptions,
 } from "./composables/useAdhesive.js";