feat(core): add data attr for adhesive status

Author: danielwaltz

packages/core/README.md

@@ -120,3 +120,26 @@ adhesive.cleanup();
 #### Static Methods
 
 - `Adhesive.create(options)` - Create and initialize in one call
+
+#### Markup & styling hooks
+
+Adhesive wraps your target element in two divs. The outer wrapper receives a data attribute reflecting the current status so you can style with attribute selectors or utilities:
+
+- `data-adhesive-status="initial"`
+- `data-adhesive-status="fixed"`
+- `data-adhesive-status="relative"`
+
+Example CSS:
+
+```css
+[data-adhesive-status="fixed"] { box-shadow: 0 1px 3px rgba(0,0,0,.1); }
+[data-adhesive-status="relative"] { opacity: .95; }
+```
+
+Tailwind/UnoCSS example (using arbitrary variants):
+
+```html
+<div id="sticky-element">
+  <span class="[[data-adhesive-status=initial]_&]:text-red-500 [[data-adhesive-status=fixed]_&]:text-green-500 [[data-adhesive-status=relative]_&]:text-blue-500">Dynamic styling based on status</span>
+</div>
+```

packages/core/src/lib/Adhesive.ts

@@ -261,6 +261,9 @@ const expectNever = (value: never): never => {
  * Adhesive.create({ targetEl: '#target-element' });
  * ```
  *
+ * Styling hook: the outer wrapper gets `data-adhesive-status` with values
+ * `initial` | `fixed` | `relative` to enable attribute-based styling.
+ *
  * @example Advanced configuration
  * ```ts
  * Adhesive.create({
@@ -808,6 +811,7 @@ export class Adhesive {
 
     overwriteClassNames(this.#outerWrapper, outerClasses);
     overwriteClassNames(this.#innerWrapper, innerClasses);
+    this.#outerWrapper.dataset.adhesiveStatus = this.#state.status;
   }
 
   #rerender(): void {

test/unit/core.test.ts

@@ -744,6 +744,30 @@ describe("Core", () => {
         const outerDomClassName = outerDomElement.className;
         expect(outerDomClassName).toBe(`${outerClassName} adhesive--initial`);
       });
+
+      it("sets data attribute for current status on outer wrapper", async () => {
+        const adhesive = createInitializedAdhesive({
+          boundingEl,
+          offset: 10,
+          position: "top",
+        });
+
+        const innerEl = targetEl.parentElement!;
+        const outerEl = innerEl.parentElement!;
+
+        // Initial state
+        expect(outerEl.dataset.adhesiveStatus).toBe("initial");
+
+        // Fixed state
+        await simulateScrollToPosition(200);
+        expect(outerEl.dataset.adhesiveStatus).toBe("fixed");
+
+        // Relative state at boundary
+        await simulateScrollToPosition(2000);
+        expect(outerEl.dataset.adhesiveStatus).toBe("relative");
+
+        adhesive.cleanup();
+      });
     });
   });