mark-3 0.0.4 → 0.0.6

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [0.0.6](https://github.com/ismailceylan/mark-3/compare/v0.0.5...v0.0.6) (2025-08-09)
+
+
+### Features
+
+* **composables:** add new use-outside-clicks composable ([6657b90](https://github.com/ismailceylan/mark-3/commit/6657b90c8330888d7f5d23b20cd85519bd44530b))
+* **composables:** add new use-pointer-swipe composable ([c048b5c](https://github.com/ismailceylan/mark-3/commit/c048b5ce2aafe1f8d8a79aa7b1b37398a8e195e2))
+* **composables:** add new use-swipeable-drawer composable ([f9e7c7a](https://github.com/ismailceylan/mark-3/commit/f9e7c7a0f757b04d63fef2ce078ed89d5e044dd8))
+* **helpers:** add new string/encode-superscript method ([655fb59](https://github.com/ismailceylan/mark-3/commit/655fb59692486202e04da2f742c5ce0d432e3b71))
+
+### [0.0.5](https://github.com/ismailceylan/mark-3/compare/v0.0.4...v0.0.5) (2025-08-03)
+
+
+### Features
+
+* **component:** add new scroll-aware-content component ([5cb2645](https://github.com/ismailceylan/mark-3/commit/5cb2645a7f2ed778adc5f30a6e684b89b4ac360a))
+* **composables:** add new use-intersection-observer composable ([5d71054](https://github.com/ismailceylan/mark-3/commit/5d710544a3067f29c8b5c4ce1db66c1ab3549a06))
+* **composables:** add new use-scroll-event composable ([00e87cc](https://github.com/ismailceylan/mark-3/commit/00e87cc5bab981f53c4c61a7f3858ad4d0c45a9c))
+* **helpers:** add new array/pick-random method ([1679cfa](https://github.com/ismailceylan/mark-3/commit/1679cfa821219fe85aef19afc17ed1b831d08ffd))
+* **helpers:** add new number/clamp method ([3694de5](https://github.com/ismailceylan/mark-3/commit/3694de551c05ad8cab78e139f35225f92d7e50b1))
+* **helpers:** add new number/random method ([bf718b3](https://github.com/ismailceylan/mark-3/commit/bf718b3ffca5147fb7985bde8d5c22e2763b3bfc))
+* **helpers:** add new string/encode-subscript method ([3dce61a](https://github.com/ismailceylan/mark-3/commit/3dce61a8c9d927126ddb94118a33d0663bba5269))
+* **helpers:** add new time/debounce helper method ([e9c4232](https://github.com/ismailceylan/mark-3/commit/e9c423233f7b946715f8624432af40f96aba9e90))
+* **helpers:** add new types/is-numeric helper method ([ab84773](https://github.com/ismailceylan/mark-3/commit/ab847736ae695fce62e42155c3653a216f6e321b))
+
 ### [0.0.4](https://github.com/ismailceylan/mark-3/compare/v0.0.3...v0.0.4) (2025-08-02)
 
 

package/components/index.js

@@ -0,0 +1 @@
+export { default as ScrollAwareContent } from "./scroll-aware-content.vue";

package/components/scroll-aware-content.vue

@@ -0,0 +1,162 @@
+<template>
+	<!-- mark-3/components/scroll-aware-content -->
+	<section ref="rootEl">
+		<slot
+			v-bind="
+			{
+				observe, biggestScrollTop, biggestScrollLeft,
+				latestScrollTop, latestScrollLeft
+			}"
+		/>
+	</section>
+</template>
+
+<script setup>
+import { ref, onMounted, onUnmounted } from "vue";
+import { debounce } from "../helpers/time";
+import { useIntersectionObserver, useScrollEvent } from "../composables";
+
+const rootEl = ref( null );
+const targetEl = ref( null );
+const emit = defineEmits([ "scroll", "metrics" ]);
+
+let biggestScrollTop = 0;
+let latestScrollTop = 0;
+let biggestScrollLeft = 0;
+let latestScrollLeft = 0;
+
+defineExpose({ scrollTo, reset });
+
+const { factor, scrollable, delay, intersect } = defineProps(
+{
+	scrollable: [ String, HTMLElement, Document ],
+	intersect: Function,
+	delay:
+	{
+		type: Number,
+		default: 50
+	},
+	factor:
+	{
+		type: Number,
+		default: 1.2
+	}
+});
+
+const onScrollThrottled = debounce( onScroll, delay );
+const { observe } = useIntersectionObserver( targetEl,
+{
+	intersect,
+	rootMargin: "-0px",
+	threshold: [ 0, 1, .6 ]
+});
+
+onMounted(() =>
+{
+	targetEl.value = (() =>
+	{
+		if( typeof scrollable == "string" )
+		{
+			if( scrollable == "html" )
+			{
+				return document;
+			}
+
+			if( scrollable == "body" )
+			{
+				return document.body;
+			}
+
+			if( scrollable[ 0 ] == "#" )
+			{
+				return document.querySelector( scrollable );
+			}
+
+			return rootEl.value.querySelector( scrollable );
+		}
+		else
+		{
+			return scrollable || rootEl.value;
+		}
+	})();
+
+	targetEl.value.scrollTop = latestScrollTop;
+	targetEl.value.scrollLeft = latestScrollLeft;
+
+	targetEl.value.addEventListener( "scroll", onScrollThrottled,
+	{
+		passive: true
+	});
+
+});
+
+onUnmounted(() =>
+	targetEl.value.removeEventListener( "scroll", onScrollThrottled )
+);
+
+function scrollTo({ top = 0, left = 0 })
+{
+	targetEl.value.scrollTo({ top, left });
+	latestScrollTop = biggestScrollTop = top;
+	latestScrollLeft = biggestScrollLeft = left;
+}
+
+function reset()
+{
+	biggestScrollTop = 0;
+	latestScrollTop = 0;
+	biggestScrollLeft = 0;
+	latestScrollLeft = 0;
+}
+
+function onScroll( evt )
+{
+	const metrics = useScrollEvent( evt,
+	{
+		latestScrollTop, latestScrollLeft,
+		biggestScrollLeft, biggestScrollTop
+	});
+
+	const { direction, scrollable, visible, maxScrolled, scrolled } = metrics;
+
+	// if user scroll to one way and scroll back to starting point
+	// immediately, direction variable will be null which that means
+	// there was no scrolling at all
+	if( ! direction )
+	{
+		return;
+	}
+
+	if( direction == "vertical" )
+	{
+		latestScrollTop = scrolled;
+
+		if( scrolled > biggestScrollTop )
+		{
+			biggestScrollTop = scrolled;
+		}
+	}
+	else if( direction == "horizontal" )
+	{
+		latestScrollLeft = scrolled;
+
+		if( scrolled > biggestScrollLeft )
+		{
+			biggestScrollLeft = scrolled;
+		}
+	}
+
+	emit( "metrics",
+	{
+		biggestScrollLeft, biggestScrollTop,
+		latestScrollLeft, latestScrollTop,
+		...metrics
+	});
+
+	if( scrollable - visible - maxScrolled < visible * factor )
+	{
+		emit( "scroll", metrics );
+	}
+}
+
+</script>

package/composables/index.js

@@ -1,3 +1,8 @@
 export { default as useMediaQuery } from "./use-media-query.js";
+export { default as useScrollEvent } from "./use-scroll-event.js";
+export { default as usePointerSwipe } from "./use-pointer-swipe.js";
+export { default as useOutsideClicks } from "./use-outside-clicks.js";
 export { default as useEventListener } from "./use-event-listener.js";
 export { default as useResponsiveness } from "./use-responsiveness.js";
+export { default as useSwipeableDrawer } from "./use-swipeable-drawer.js";
+export { default as useIntersectionObserver } from "./use-intersection-observer.js";

package/composables/use-event-listener.js

@@ -1,5 +1,9 @@
-import { onMounted, onUnmounted, getCurrentInstance } from "vue";
+import { isRef, unref, onMounted, onUnmounted, getCurrentInstance } from "vue";
 
+/**
+ * @template T
+ * @typedef {import("vue").Ref<T>} Ref
+ */
 /**
  * A composition function that adds a DOM event listener to the given target with the
  * given event name and callback. The options object is optional. If the composition
@@ -8,15 +12,15 @@ import { onMounted, onUnmounted, getCurrentInstance } from "vue";
  * composition function is called outside of a component, then the event listener is
  * added immediately and must be removed manually by calling the returned function.
  *
- * @param {Element} target - The target element to add the event listener to.
+ * @param {EventTarget|Ref<EventTarget>} maybeRefTarget - The target element to add the event listener to.
  * @param {string} eventName - The name of the event to add a listener for.
  * @param {function} callBack - The callback function to call when the event happens.
  * @param {object} [options] - The options object to pass to addEventListener.
  * @returns {function} - A function that can be called to remove the event listener.
  */
-export default function useEventListener( target, eventName, callBack, options )
+export default function useEventListener( maybeRefTarget, eventName, callBack, options )
 {
-	if( getCurrentInstance())
+	if( getCurrentInstance() && isRef( maybeRefTarget ))
 	{
 		onMounted( listen );
 		onUnmounted( stop );
@@ -28,12 +32,22 @@ export default function useEventListener( target, eventName, callBack, options )
 
 	function listen()
 	{
-		target.addEventListener( eventName, callBack, options );
+		const el = unref( maybeRefTarget );
+		
+		if( el && el.addEventListener )
+		{
+			el.addEventListener( eventName, callBack, options );
+		}
 	}
 
 	function stop()
 	{
-		target.removeEventListener( eventName, callBack );
+		const el = unref( maybeRefTarget );
+		
+		if( el && el.addEventListener )
+		{
+			el.removeEventListener( eventName, callBack );
+		}
 	}
 
 	return stop;

package/composables/use-intersection-observer.js

@@ -0,0 +1,67 @@
+import { unref, onMounted } from "vue";
+
+/**
+ * A composition function that creates an IntersectionObserver instance and
+ * provides a method to observe the provided elements.
+ *
+ * @param {Ref<Element>|Element} maybeRefSourceElement - The source element
+ *   that the observer will observe for intersection.
+ * @param {Object} [options] - The options to pass to the IntersectionObserver
+ *   constructor.
+ * @returns {{ observe: (el: Element) => void, observer: IntersectionObserver }}
+ *   A object with two properties. The `observe` property is a function that
+ *   takes an element to observe and the `observer` property is the created
+ *   IntersectionObserver instance.
+ */
+export default function useIntersectionObserver( maybeRefSourceElement, options = {})
+{
+	let observer;
+	
+	onMounted( init );
+
+	function init()
+	{
+		options.source = unref( maybeRefSourceElement );
+		observer = new IntersectionObserver( handleObservations, options );
+	}
+	
+	function handleObservations( entries )
+	{
+		requestAnimationFrame(() =>
+		{
+			for( const { target: { item }, isIntersecting } of entries )
+			{
+				if( options.intersect )
+				{
+					options.intersect( item, isIntersecting );
+				}
+				else
+				{
+					item.isIntersecting = isIntersecting;
+				}
+			}
+		});
+	}
+
+	function observe( item )
+	{
+		return el =>
+		{
+			if( ! el )
+			{
+				return;
+			}
+	
+			el.item = item;
+
+			if( ! observer )
+			{
+				init();
+			}
+	
+			observer && observer.observe( el );
+		}
+	}
+
+	return { observe, observer }
+}

package/composables/use-outside-clicks.js

@@ -0,0 +1,62 @@
+import { useEventListener } from ".";
+
+/**
+ * Watches for clicks outside of the given element and calls the
+ *   callback when it happens.
+ * 
+ * This is useful for things like dropdowns, where you want to close
+ *   the dropdown when the user clicks outside of it.
+ * 
+ * This is a composition function that uses useEventListener under the
+ *   hood. So, it will automatically remove the event listener when the
+ *   component is unmounted.
+ * 
+ * It also returns a function that can be used to remove the event
+ *   listener. This is useful for when you want to remove the event
+ *   listener when the extraordinary circumstances arise.
+ * 
+ * @typedef {import('vue').Ref<Element>} ElementRef
+ * @param {ElementRef[]} elRefs - The elements to watch for clicks outside of.
+ * @param {function} callback - The callback to call when a click is outside of the element.
+ * @param {object} options - The options object.
+ * @property {string} options.on - The event to listen for.
+ * @returns {function}
+ * @example
+ * const elRef = ref();
+ * 
+ * useOutsideClick( elRef, () =>
+ *     console.log( "Clicked outside!" )
+ * );
+ * @example
+ * const elRef = ref();
+ * 
+ * useOutsideClick(
+ *     elRef,
+ *     () => console.log( "Clicked outside!" ),
+ *     {
+ *         on: "mousedown"
+ *     }
+ * );
+ */
+export default function useOutsideClick( elRefs, callback, { on = "click" } = {})
+{
+	return useEventListener( document, on, e =>
+	{
+		if( elRefs.length === 0 )
+		{
+			return;
+		}
+
+		for( let el of elRefs )
+		{
+			el = el.value;
+
+			if( el?.contains( e.target ))
+			{
+				return;
+			}
+		}
+
+		callback( e );
+	});
+}

package/composables/use-pointer-swipe.js

@@ -0,0 +1,138 @@
+import { ref, reactive, computed, onMounted, onUnmounted } from "vue";
+import { useEventListener } from ".";
+
+/**
+ * A composition function that detects swipe gestures on a given element and provides
+ * reactive properties related to the swipe event.
+ *
+ * @param {Ref<EventTarget>|EventTarget} maybeRefEl - The element to detect swipe gestures on.
+ * @param {Object} [options] - Configuration options.
+ * @param {number} [options.threshold=50] - The minimum distance in pixels to consider a swipe.
+ * @param {boolean} [options.disableTextSelect=false] - Whether to disable text selection during swipe.
+ * @returns {PointerSwipeReturnValue} - An object containing reactive properties related to the swipe:
+ */
+export default function usePointerSwipe( maybeRefEl, { threshold = 50, disableTextSelect = false } = {})
+{
+	const { abs, max } = Math;
+	const isSwiping = ref( false );
+	const posStart = reactive({ x: 0, y: 0 });
+	const posEnd = reactive({ x: 0, y: 0 });
+	const timeStart = ref( 0 );
+	const timeEnd = ref( 0 );
+	const distanceX = ref( 0 );
+	const distanceY = ref( 0 );
+
+	const timePassed = computed(() => timeEnd.value - timeStart.value );
+
+	const isThresholdExceeded = computed(() =>
+		max(abs( distanceX.value ), abs( distanceY.value )) >= threshold
+	);
+
+	const direction = computed(() =>
+	{
+		if( ! isThresholdExceeded.value )
+		{
+			return "none";
+		}
+
+		if( abs( distanceX.value ) > abs( distanceY.value ))
+		{
+			return distanceX.value > 0
+				? "left"
+				: "right";
+		}
+
+		return distanceY.value > 0
+			? "up"
+			: "down";
+	});
+
+	const velocity = computed(() =>
+	{
+		if( direction.value === "none" )
+		{
+			return 0;
+		}
+
+		const distance = [ "up", "down" ].includes( direction.value )
+			? distanceY.value
+			: distanceX.value;
+
+		return abs( distance / timePassed.value );
+	});
+
+	useEventListener( maybeRefEl, "pointerdown", e =>
+	{
+		isSwiping.value = true;
+		posStart.x = e.clientX;
+		posStart.y = e.clientY;
+		timeStart.value = performance.now();
+
+		const stopListeningMove = useEventListener( maybeRefEl, "pointermove", e =>
+		{
+			posEnd.x = e.clientX;
+			posEnd.y = e.clientY;
+			distanceX.value = posEnd.x - posStart.x;
+			distanceY.value = posEnd.y - posStart.y;
+		});
+
+		useEventListener( maybeRefEl, "pointerup", () =>
+		{
+			isSwiping.value = false;
+			timeEnd.value = performance.now();
+
+			stopListeningMove();
+		},{ once: true });
+	});
+
+	onMounted(() =>
+	{
+		if( disableTextSelect )
+		{
+			document.documentElement.style.setProperty( "user-select", "none" );
+		}
+	});
+
+	onUnmounted(() =>
+	{
+		if( disableTextSelect )
+		{
+			document.documentElement.style.removeProperty( "user-select" );
+		}
+	});
+
+	return {
+		isSwiping,
+		posStart,
+		posEnd,
+		distanceX,
+		distanceY,
+		isThresholdExceeded,
+		direction,
+		velocity
+	}
+}
+
+/**
+ * @template T
+ * @typedef {import("vue").Ref<T>} Ref
+ */
+/**
+ * @template T
+ * @typedef {import("vue").ComputedRef<T>} ComputedRef
+ */
+/**
+ * @template T
+ * @typedef {import("vue").Reactive<T>} Reactive
+ */
+/**
+ * @typedef {object} PointerSwipeReturnValue
+ * @property {Ref<boolean>} isSwiping - Indicates if a swipe is currently happening.
+ * @property {Reactive<{x: number, y: number}>} posStart - The starting position of the swipe.
+ * @property {Reactive<{x: number, y: number}>} posEnd - The ending position of the swipe.
+ * @property {Ref<number>} distanceX - The horizontal distance swiped.
+ * @property {Ref<number>} distanceY - The vertical distance swiped.
+ * @property {ComputedRef<boolean>} isThresholdExceeded - Whether the swipe exceeded the threshold.
+ * @property {ComputedRef<"left"|"right"|"up"|"down"|"none">} direction - The direction of the swipe.
+ * @property {ComputedRef<number>} velocity - The velocity of the swipe.
+ */

package/composables/use-scroll-event.js

@@ -0,0 +1,97 @@
+/**
+ * @typedef ScrollMetrics
+ * @type {object}
+ * @property {number} maxScrolled the furthest point reached by scrolling
+ * @property {"vertical"|"horizontal"} direction scroll direction
+ * @property {number} seen seen pixels
+ * @property {number} unseen unseen pixels
+ * @property {number} visible the area covered by the scrollable content
+ * on the screen
+ * @property {number} scrolled currently scrolled pixels
+ * @property {number} scrollable total scrollable pixels
+ * @property {"up"|"down"} vertical whether the vertical direction is
+ * towards the up or the down
+ * @property {"left"|"right"} horizontal whether the horizontal direction
+ * is towards the left or the right
+ */
+/**
+ * This function takes a scroll event and calculates the scrolling
+ * direction, along with metrics for visible, scrollable, and
+ * unseen areas.
+ * 
+ * The direction is determined as vertical or horizontal, and returned
+ * along with relevant metrics.
+ * 
+ * @param {Event} evt scroll event object
+ * @param {object} metrics
+ * @property {number} metrics.latestScrollTop latest vertically scrolled pixel
+ * @property {number} metrics.latestScrollLeft latest horizontally scrolled pixel
+ * @property {number} metrics.biggestScrollLeft biggest horizontally scrolled pixel
+ * @property {number} metrics.biggestScrollTop biggest vertically scrolled pixel
+ * @return {ScrollMetrics}
+ */
+export default function useScrollEvent(
+	{ target },
+	{ latestScrollTop = 0, latestScrollLeft = 0, biggestScrollLeft = 0, biggestScrollTop = 0 } = {}
+)
+{
+	target = target === document
+		? document.scrollingElement
+		: target;
+
+	const { clientHeight, clientWidth, scrollTop, scrollLeft, scrollHeight, scrollWidth } = target;
+	const vertical = calcDirection( "down", null, "up", [ scrollTop, latestScrollTop ]);
+	const horizontal = calcDirection( "right", null, "left", [ scrollLeft, latestScrollLeft ]);
+	const direction = ( vertical && "vertical" ) || ( horizontal && "horizontal" );
+	let visible = 0, scrollable = 0, scrolled = 0;
+	let seen = 0, unseen = 0, maxScrolled = 0;
+
+	if( direction == "vertical" )
+	{
+		visible = clientHeight;
+		scrollable = scrollHeight;
+		scrolled = scrollTop;
+		maxScrolled = biggestScrollTop;
+	}
+	else if( direction == "horizontal" )
+	{
+		visible = clientWidth;
+		scrollable = scrollWidth;
+		scrolled = scrollLeft;
+		maxScrolled = biggestScrollLeft;
+	}
+
+	seen = scrolled + visible;
+	unseen = scrollable - seen;
+	maxScrolled = Math.max( maxScrolled, scrolled );
+
+	function calcDirection( a, middle, b, [ v1, v2 ])
+	{
+		if( v1 === v2 )
+		{
+			return middle;
+		}
+
+		if( v2 > v1 )
+		{
+			return b;
+		}
+
+		if( v2 < v1 )
+		{
+			return a;
+		}
+	}
+
+	return {
+		maxScrolled,
+		direction,
+		seen,
+		unseen,
+		visible,
+		scrolled,
+		scrollable,
+		vertical,
+		horizontal
+	}
+}