diff --git a/src/util/3d-tilt-hover-effect.ts b/src/util/3d-tilt-hover-effect.ts index 1a6a01adf0..8a43883b98 100644 --- a/src/util/3d-tilt-hover-effect.ts +++ b/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 ( - *
- * Your content here - *
+ * + * * ); * } * ``` * - * :::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 `
` 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 `
` 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 `
` 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;