fixup! chore(util): complete the tiltFollowingTheCursor utility fun…

…ction

Update docblock

src/util/3d-tilt-hover-effect.ts

@@ -1,108 +1,81 @@
 /**
  * Utility functions for creating a 3D tilt hover effect.
  *
- * This module provides functions that enables consumer components to display a nice 3D effect,
- * when being hovered; enabling them to follow the cursor's position and tilt towards it.
+ * This module provides functions to enable a 3D tilt effect for consumer components,
+ * allowing elements to visually follow the cursor's position and tilt towards it.
+ * It also includes a glow effect for added interactivity.
  *
- * ## What you need, to make this work
- * ### Typescript
- * 1. Import the functions:
+ * ## Usage
+ *
+ * 1. **Import the utility**:
  *
  * ```tsx
- * import {
- *     tiltFollowingTheCursor,
- *     handleMouseEnter,
- *     handleMouseLeave,
- * } from './path/to/3d-tilt-hover-effect';
+ * import { getMouseEventHandlers } from './path/to/3d-tilt-hover-effect';
  * ```
  *
- * 2. In your component, define the necessary properties.
- * For example, if your 3D element is a `section` element:
+ * 2. **Initialize in your component**:
+ *
+ * Call `getMouseEventHandlers()` in your component to retrieve the `handleMouseEnter`
+ * and `handleMouseLeave` functions, and attach them to the target element.
+ * For example, if your interactive element is the host itself:
  *
  * ```tsx
- * @Element() private element: HTMLElement;
- * private the3dElementBounds: DOMRect;
+ * @Element()
+ * private host: HTMLElement;
  *
- * public componentDidLoad() {
- *     const the3dElement = this.element.shadowRoot.querySelector('section');
- *     the3dElement.addEventListener('mouseenter', this.handleMouseEnter);
- *     the3dElement.addEventListener('mouseleave', this.handleMouseLeave);
- * }
+ * private handleMouseEnter: () => void;
+ * private handleMouseLeave: () => void;
  *
- * public disconnectedCallback() {
- *     const the3dElement = this.element.shadowRoot.querySelector('section');
- *     if (the3dElement) {
- *         the3dElement.removeEventListener(
- *             'mouseenter',
- *             this.handleMouseEnter,
- *         );
- *         the3dElement.removeEventListener(
- *             'mouseleave',
- *             this.handleMouseLeave,
- *         );
- *     }
+ * public componentWillLoad() {
+ *     const { handleMouseEnter, handleMouseLeave } = getMouseEventHandlers(this.host);
+ *     this.handleMouseEnter = handleMouseEnter;
+ *     this.handleMouseLeave = handleMouseLeave;
  * }
  * ```
  *
- * 3. If your component does not already have event handlers,
- * implement them using the imported functions from this file:
- *
- * ```tsx
- * private handleMouseEnter = () => {
- *     handleMouseEnter(this.element, 'section', (bounds) => {
- *         this.the3dElementBounds = bounds;
- *     }, this.tiltFollowingTheCursor);
- * };
- *
- * private handleMouseLeave = () => {
- *     handleMouseLeave(this.element, this.tiltFollowingTheCursor);
- * };
- *
- * private tiltFollowingTheCursor = (e: MouseEvent) => {
- *     tiltFollowingTheCursor(e, this.the3dElementBounds, this.element);
- * };
- * ```
- *
- * 4. Attach the event handlers to the relevant elements in your render method:
+ * 3. **Attach event handlers in your render method**:
  *
  * ```tsx
  * public render() {
  *     return (
- *         <section
+ *         <Host
  *             onMouseEnter={this.handleMouseEnter}
  *             onMouseLeave={this.handleMouseLeave}
  *         >
- *             Your content here
- *         </section>
+ *             <!-- Your component content -->
+ *         </Host>
  *     );
  * }
  * ```
  *
- * :::note
- * - Ensure that the `element` and `the3dElementBounds` properties are properly
- * defined in your component.
- * - The `selector` parameter in `handleMouseEnter` should match the selector
- * of the element you want to apply the 3D effect to.
- * - The `tiltFollowingTheCursor` function calculates the 3D rotation and glow
- * position based on the cursor's position relative to the element's bounds.
- * :::
- *
- * ### HTML elements + CSS
- * 1. Add a `<div class="limel-3d-hover-effect-glow" />` element to your component's template,
- * inside the element you want to apply the 3D effect to, and preferably at the bottom of all
- * other elements within that element (to avoid the need to specifying `z-index`es).
- * 2. Add the following `mixin` to your component's SCSS file:
- * `limel-3d-hover-effect-glow($the3dElement, $border-radius);`
- *
- * and don't forget to define the `$the3dElement` variables for the mixin to work
- * (and optionally the `$border-radius`).
- * 3. Keep in mind that the `<div class="limel-3d-hover-effect-glow" />` will be
- * absolutely positioned inside the parent element, so make sure the parent element
- * has `position` set.
- * 4. Add the following `mixin` to the host element: `parent-of-the-3d-element`.
- * 5. Add the following `mixin` to the 3D element: `the-3d-element`.
- * 6. And if your element is supposed to be clickable, add this `mixin` as well: `the-3d-element--clickable`.
+ * ## Styling Requirements
+ *
+ * To enable the 3D tilt and glow effect:
+ *
+ * 1. Add a `<div class="limel-3d-hover-effect-glow" />` inside the target element,
+ *    preferably as the last child.
+ *
+ * 2. Use the following SCSS mixins in your component:
+ *
+ * - **On the host element**:
+ *   ```scss
+ *   @include parent-of-the-3d-element;
+ *   ```
+ *
+ * - **On the 3D element**:
+ *   ```scss
+ *   @include the-3d-element;
+ *   ```
+ *
+ * - **For clickable elements**:
+ *   ```scss
+ *   @include the-3d-element--clickable;
+ *   ```
  *
+ * - **For the glow effect**:
+ *   ```scss
+ *   @include limel-3d-hover-effect-glow($selector, $border-radius);
+ *   ```
  */
 
 export const MOUSE_SCALE_FACTOR = 100;