mark-3 0.0.6 → 0.0.10

package/CHANGELOG.md

@@ -2,6 +2,57 @@
 
 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.10](https://github.com/ismailceylan/mark-3/compare/v0.0.9...v0.0.10) (2025-09-19)
+
+
+### Features
+
+* **composables:** add new use-timeout composable ([e55c99b](https://github.com/ismailceylan/mark-3/commit/e55c99becb211c006b853682d699b6df543c3bf0))
+* **composables:** add persistent option for the use-event-listener composable ([3361183](https://github.com/ismailceylan/mark-3/commit/3361183e77ac2a3842834efabfe2ea057d890ddf))
+* **composables:** add persistent option for the use-media-query composable ([1cbff8f](https://github.com/ismailceylan/mark-3/commit/1cbff8f6d92fe9a08a73840789261552eecfdd03))
+* **helpers:** add new date/seconds-remaining helper ([0404d06](https://github.com/ismailceylan/mark-3/commit/0404d066f8240152a3a4aa25ee49129549636983))
+
+
+### Bug Fixes
+
+* **composables:** reattach the events when ref-type elements are reassigned ([dde2c85](https://github.com/ismailceylan/mark-3/commit/dde2c85039b69bb6ca75f88334c9d5d81664c08f))
+* **helpers:** correct from-timestamp filename without affecting exports ([15273cb](https://github.com/ismailceylan/mark-3/commit/15273cb7ade8be17a5dda74d8402dbd1f1371b5c))
+* **helpers:** correct is-on-same-day filename without affecting exports ([015b92a](https://github.com/ismailceylan/mark-3/commit/015b92ada54f67fb7d529b92c084f0e82d744f0a))
+
+### [0.0.9](https://github.com/ismailceylan/mark-3/compare/v0.0.8...v0.0.9) (2025-08-30)
+
+
+### Features
+
+* **components:** add an option to ignore window size changes in virtual-scroll component ([2e27806](https://github.com/ismailceylan/mark-3/commit/2e2780680718824df973d050b109cf81ef657dc5))
+* **components:** add support for two-way top scroll determination using the v-model method for virtual-scroll component ([123c89e](https://github.com/ismailceylan/mark-3/commit/123c89e6cc216305ac7d66e2c8d961d50cc7aaad))
+* **helpers:** add new chunk method for arrays ([9150623](https://github.com/ismailceylan/mark-3/commit/9150623b9194830b5699c0863e8313fcde21c3d3))
+* **helpers:** add new number/compact helper ([6d40850](https://github.com/ismailceylan/mark-3/commit/6d40850dcb174d32232e70e9139fe71f43a05d96))
+* **helpers:** add new number/reduce helper ([1881c99](https://github.com/ismailceylan/mark-3/commit/1881c992547a42eb6b23aa60298d5abfc2ef0c56))
+
+
+### Bug Fixes
+
+* **components:** add a watch getter to watch some ref elements in virtual-scroll component ([a74b0b7](https://github.com/ismailceylan/mark-3/commit/a74b0b7061a3fef9da8acc1177dda03f54edd9ae))
+* **components:** add the immediate flag to process the already full item store immediately in virtual-scroll component ([a45a4da](https://github.com/ismailceylan/mark-3/commit/a45a4da63c3921714b0df8f86e33601956ad9a69))
+* **components:** use a more secure value to ensure that the key value of the virtual scroll element is unique ([1db4081](https://github.com/ismailceylan/mark-3/commit/1db40812aadbbc186bcae6a7169a298060aa9ced))
+* **components:** use the getter watch pattern to watch elements properly when they are sent as refs in virtual-scroll component ([6556ae8](https://github.com/ismailceylan/mark-3/commit/6556ae8abec1c2b5715fd914503d539bb1dd8e8a))
+* **composables:** fix virtual-scroll artifact problems and add relative position to wrapper ([a7566c3](https://github.com/ismailceylan/mark-3/commit/a7566c352f0f83f8ab0df910d3e7d6517d0e5c3a))
+* **composables:** virtual-scroll recalculate properly item heights when the screen size changed ([0749124](https://github.com/ismailceylan/mark-3/commit/07491247c28461c9cc65b49c98d992dfab07aeea))
+
+### [0.0.8](https://github.com/ismailceylan/mark-3/compare/v0.0.7...v0.0.8) (2025-08-13)
+
+### [0.0.7](https://github.com/ismailceylan/mark-3/compare/v0.0.6...v0.0.7) (2025-08-13)
+
+
+### Features
+
+* **components:** add new virtual-scroll component ([c73a31d](https://github.com/ismailceylan/mark-3/commit/c73a31d6dc2ec37d8e70a15160bda495425712ca))
+* **composables:** add new use-css-metrics composable ([8500859](https://github.com/ismailceylan/mark-3/commit/85008595788348956cd2f40cc0fff65d038672b0))
+* **composables:** add new use-resize-observer composable ([6d110b5](https://github.com/ismailceylan/mark-3/commit/6d110b5c17facd4918a8a02a49d2f7644ada8f96))
+* **composables:** add new use-scroll-position composable ([f847cb0](https://github.com/ismailceylan/mark-3/commit/f847cb0a9f19f09f82ab55d447227a7aa21516d5))
+* **helpers:** add new time/throttle method ([60b8472](https://github.com/ismailceylan/mark-3/commit/60b8472fdb56119888c90446fe237b1fc9573f2b))
+
 ### [0.0.6](https://github.com/ismailceylan/mark-3/compare/v0.0.5...v0.0.6) (2025-08-09)
 
 

package/components/index.js

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

package/components/virtual-scroll.vue

@@ -0,0 +1,275 @@
+<template>
+	<!-- Mark-3/VirtualScroll -->
+	<div ref="container">
+		<div :style="{ transform: 'translateZ(0)', position: 'relative', minHeight: totalHeight + 'px' }">
+			<slot
+				v-for="{ item, index } of visibleItems"
+				:key="index"
+				:item
+				:index
+				:observe
+				:has-scrollbar
+				:style="{ position: 'absolute', transform: 'translateY(' + offsets[ index ] + 'px)' }"
+			/>
+		</div>
+
+		<slot name="bottom" />
+	</div>
+</template>
+
+<script lang="ts" setup>
+import { ref, watch, computed, reactive, nextTick } from "vue";
+import { useCssMetrics, useEventListener, useResizeObserver, useScrollPosition } from "../composables";
+import { debounce } from "../helpers/time";
+import { clamp } from "../helpers/number";
+
+const emit = defineEmits([ "threshold-reached" ]);
+
+const scrollTop = defineModel( "scrollTop", { default: 0 });
+
+const props = defineProps(
+{
+	pageMode: Boolean,
+	dontWatchResizing: Boolean,
+
+	items: {
+		type: Array,
+		required: true
+	},
+
+	buffer: {
+		type: Number,
+		default: 5
+	},
+
+	minHeight: {
+		type: Number,
+		default: 20
+	},
+
+	itemGapClasses: {
+		type: String
+	},
+
+	threshold: {
+		type: Number,
+		default: 3
+	}
+});
+
+const { max, abs, floor } = Math;
+const heights = ref<number[]>([]);
+const identifiedItems = reactive<{ item: any, index: number }[]>([]);
+const container = ref<HTMLDivElement>( null );
+const hasScrollbar = ref( false );
+const metrics = useCssMetrics( props.itemGapClasses, [ "gap" ] as const, { throttle: 100 });
+const isHeightsDirty = ref( false );
+const dirtyItems = {}
+
+const scrollableElement = computed(() =>
+	props.pageMode
+		? window
+		: container.value
+);
+
+const scrollPos = useScrollPosition( scrollableElement, { throttle: 150 });
+
+const offsets = computed<number[]>(() =>
+{
+	const arr = new Array( heights.value.length );
+	let sum = 0;
+
+	for( let i = 0; i < heights.value.length; i++ )
+	{
+		arr[ i ] = sum;
+		sum += heights.value[ i ] || 0;
+	}
+
+	return arr;
+});
+
+const totalHeight = computed(() =>
+{
+	if( identifiedItems.length === 0 )
+	{
+		return 0;
+	}
+
+	const latestOffset = offsets.value[ offsets.value.length - 1 ] || 0;
+	const latestHeight = heights.value[ heights.value.length - 1 ] || 0;
+	const h = latestOffset + latestHeight;
+
+	if( h === metrics.value.gap * 2 )
+	{
+		return 0;
+	}
+
+	return h + 1;
+});
+
+const startIndex = computed(() =>
+{
+	let low = 0;
+	let high = offsets.value.length - 1;
+	let mid: number;
+	
+	while( low <= high )
+	{
+		mid = floor(( low + high ) / 2 );
+
+		if( offsets.value[ mid ] === scrollPos.y.value )
+		{
+			return mid;
+		}
+		
+		if( offsets.value[ mid ] < scrollPos.y.value )
+		{
+			low = mid + 1;
+		}
+		else
+		{
+			high = mid - 1;
+		}
+	}
+	
+	return low - 1 < 0
+		? 0
+		: low - 1;
+});
+
+const endIndex = computed(() =>
+{
+	let total = 0;
+	let idx = startIndex.value;
+
+	while( idx < heights.value.length && total < window.innerHeight )
+	{
+		total += heights.value[ idx ];
+		idx++;
+	}
+	
+	return max( 0, idx - 1 );
+});
+
+const startIndexWithMargin = computed(() =>
+	max( 0, startIndex.value - props.buffer )
+);
+
+const endIndexWithMargin = computed(() =>
+	clamp( endIndex.value + props.buffer, 0, heights.value.length )
+);
+
+const visibleItems = computed(() =>
+	identifiedItems.slice( startIndexWithMargin.value, endIndexWithMargin.value )
+);
+
+const { observe } = useResizeObserver(( entries ) =>
+{
+	entries.forEach( entry =>
+	{
+		const index = parseInt(( entry.target as HTMLElement ).dataset.index );
+		const newHeight = entry.contentRect.height;
+		const oldHeight = heights.value[ index ] || 0;
+
+		heights.value[ index ] = index in dirtyItems
+			// replace old height
+			? newHeight + metrics.value.gap
+			: max( newHeight + metrics.value.gap, oldHeight );
+
+		delete dirtyItems[ index ];
+	});
+});
+
+watch( scrollPos.y, () => scrollTop.value = scrollPos.y.value );
+
+watch( scrollTop, async () =>
+{
+	await nextTick();
+	
+	if( scrollableElement.value instanceof HTMLElement )
+	{
+		scrollableElement.value.scrollTop = scrollTop.value;
+	}
+	else if( scrollableElement.value === window )
+	{
+		window.scrollTo( 0, scrollTop.value );
+	}
+}, { immediate: true, once: true });
+
+watch( endIndex, () =>
+{
+	if(( identifiedItems.length - 1 ) - endIndex.value <= props.threshold )
+	{
+		emit( "threshold-reached" );
+	}
+});
+
+watch(() => props.items, items =>
+{
+	const normalizedItems = items.map(( item, i ) =>
+	({
+		item,
+		index: i
+	}));
+
+	identifiedItems.length = 0;
+	identifiedItems.push( ...normalizedItems );
+
+	heights.value = items.map(( _, i ) =>
+		heights.value[ i ] ?? props.minHeight
+	);
+}, { immediate: true, deep: true });
+
+watch( isHeightsDirty, () =>
+{
+	if( isHeightsDirty.value === false )
+	{
+		return;
+	}
+
+	visibleItems.value.forEach(({ index }) =>
+	{
+		const itemEl = container.value.querySelector( "[data-index='" + index + "']" );
+		
+		if( itemEl === null )
+		{
+			return dirtyItems[ index ] = true;
+		}
+
+		heights.value[ index ] = itemEl.getBoundingClientRect().height + metrics.value.gap;
+	});
+
+	isHeightsDirty.value = false;
+});
+
+watch( container, () =>
+{
+	setTimeout(() =>
+		hasScrollbar.value = container.value.scrollHeight > container.value.clientHeight
+	);
+});
+
+if( props.dontWatchResizing === false )
+{
+	let latestWidth = 0;
+	const debouncedResetHeights = debounce( resetHeights, 500 );
+
+	useEventListener( window, "resize", () =>
+	{
+		const newWidth = window.innerWidth;
+		
+		if( newWidth !== latestWidth )
+		{
+			latestWidth = newWidth;
+			debouncedResetHeights();
+		}
+	}, { passive: true });
+}
+
+function resetHeights()
+{
+	heights.value = identifiedItems.map(() => props.minHeight );
+	isHeightsDirty.value = true;
+}
+
+</script>

package/composables/index.js

@@ -1,8 +1,12 @@
-export { default as useMediaQuery } from "./use-media-query.js";
+export { default as useTimeout } from "./use-timeout.ts";
+export { default as useMediaQuery } from "./use-media-query.ts";
+export { default as useCssMetrics } from "./use-css-metrics.ts";
 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 useResizeObserver } from "./use-resize-observer.js";
+export { default as useScrollPosition } from "./use-scroll-position.js";
+export { default as useSwipeableDrawer } from "./use-swipeable-drawer.ts";
 export { default as useIntersectionObserver } from "./use-intersection-observer.js";

package/composables/use-css-metrics.ts

@@ -0,0 +1,115 @@
+import { ref, onMounted, onUnmounted, Ref } from "vue";
+import { useResizeObserver } from ".";
+
+/**
+ * Creates a reactive reference containing numeric values of specified CSS properties
+ * for elements with given classes. It observes size changes and updates the metrics
+ * accordingly.
+ *
+ * @template P
+ * @param classes - CSS classes to apply to the ghost element used for measurement.
+ * @param properties - Array of CSS property names to track.
+ * @param options - Optional configuration object.
+ * @returns A reactive reference with the current values of the specified CSS properties.
+ */
+export default function useCssMetrics<P extends readonly string[]>(
+	classes: string|string[],
+	properties: P, { throttle = 0 } = {}
+): Ref<{[ K in typeof properties[ number ]]: number }>
+{
+	const metrics = ref({});
+	let ghostEl = null;
+	let widthEl = null;
+	let observer = null;
+	const { observe, unobserve, disconnect } = useResizeObserver( updateMetrics, { throttle });
+
+	metrics.value = Object.fromEntries( properties.map( prop =>
+		[ prop, 0 ]
+	));
+
+	if( classes === undefined || ( Array.isArray( classes ) && classes.length === 0 ))
+	{
+		return metrics;
+	}
+
+	onMounted( init );
+	onUnmounted( destroy );
+
+	function init()
+	{
+		if( ghostEl )
+		{
+			return;
+		}
+
+		ghostEl = document.createElement( "div" );
+		widthEl = document.createElement( "div" );
+
+		const ghostStyle = ghostEl.style;
+		const widthStyle = widthEl.style;
+
+		ghostStyle.position = "absolute";
+		ghostStyle.top = "0";
+		ghostStyle.left = "0";
+		ghostStyle.width = "100%";
+		ghostStyle.height = "100%";
+		ghostStyle.visibility = "hidden";
+		ghostStyle.pointerEvents = "none";
+
+		widthStyle.position = "absolute";
+		widthStyle.visibility = "hidden";
+		widthStyle.pointerEvents = "none";
+
+		ghostEl.appendChild( widthEl );
+
+		const cls = Array.isArray( classes )
+			? classes
+			: classes.split( " " );
+
+		ghostEl.classList.add( ...cls );
+		widthEl.classList.add( ...cls );
+
+		document.body.appendChild( ghostEl );
+
+		observe( ghostEl );
+		updateMetrics();
+	}
+
+	function updateMetrics()
+	{
+		if( ! ghostEl )
+		{
+			return;
+		}
+
+		const computed = getComputedStyle( ghostEl );
+		const computed2 = getComputedStyle( widthEl );
+
+		properties.forEach( prop =>
+		{
+			const source = [ "width", "height" ].includes( prop )
+				? computed2
+				: computed;
+			
+			metrics.value[ prop ] = parseFloat( source.getPropertyValue( prop )) || 0;
+		});
+	}
+
+	function destroy()
+	{
+		if( observer && ghostEl )
+		{
+			unobserve( ghostEl );
+			disconnect();
+		}
+
+		if( ghostEl && ghostEl.parentElement )
+		{
+			ghostEl.parentElement.removeChild( ghostEl );
+		}
+
+		ghostEl = null;
+	}
+
+	return metrics;
+}

package/composables/use-event-listener.js

@@ -1,9 +1,5 @@
-import { isRef, unref, onMounted, onUnmounted, getCurrentInstance } from "vue";
+import { 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
@@ -15,12 +11,12 @@ import { isRef, unref, onMounted, onUnmounted, getCurrentInstance } from "vue";
  * @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.
+ * @param {EventListenerOptions} [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( maybeRefTarget, eventName, callBack, options )
+export default function useEventListener( maybeRefTarget, eventName, callBack, options = {})
 {
-	if( getCurrentInstance() && isRef( maybeRefTarget ))
+	if( getCurrentInstance() && ! options.persistent )
 	{
 		onMounted( listen );
 		onUnmounted( stop );
@@ -52,3 +48,16 @@ export default function useEventListener( maybeRefTarget, eventName, callBack, o
 
 	return stop;
 }
+
+/**
+ * @template T
+ * @typedef {import("vue").Ref<T>} Ref
+ */
+/**
+ * @typedef EventListenerOptions
+ * @type {object}
+ * @property {boolean} [capture=false] true for capturing, false for bubbling
+ * @property {boolean} [once=false] true for run the event once or false for keep it persistent
+ * @property {boolean} [passive=false] true for passive, false for not passive
+ * @property {boolean} [persistent=false] true for persistent, false for not persistent
+ */

package/composables/use-media-query.ts

@@ -0,0 +1,51 @@
+import { type Ref, ref } from "vue";
+import { useEventListener } from ".";
+
+/**
+ * Creates a reactive reference that tracks whether the given media query matches the current viewport.
+ *
+ * @param query - A valid media query string.
+ * @returns A reactive reference to the match status.
+ * @example
+ * const isMobileRef = useMediaQuery( "(max-width: 767px)",
+ * {
+ *     onChange: matches => console.log( matches )
+ * });
+ */
+export default function useMediaQuery(
+	query: string,
+	{ persistent = false, onChange }: UseMediaQueryOptions = {}
+): Ref<boolean>
+{
+	const match = matchMedia( query );
+	const matches = ref( match.matches );
+
+	triggerWatcher();
+
+	useEventListener(
+		match, "change",
+		( e: MediaQueryListEvent ) => triggerWatcher( matches.value = e.matches ),
+		{ persistent }
+	);
+
+	function triggerWatcher( _?: boolean )
+	{
+		onChange && onChange( matches.value );
+	}
+
+	return matches;
+}
+
+type ChangeListener = ( matches: boolean ) => void;
+
+interface UseMediaQueryOptions
+{
+	/** Whether to persist the match status across component mounts and unmounts */
+	persistent?: boolean;
+	/**
+	 * A function that will be called whenever the match status
+	 * changes. The function will receive the current match status
+	 * as a boolean argument.
+	 */
+	onChange?: ChangeListener;
+}

package/composables/use-outside-clicks.js

@@ -1,4 +1,5 @@
 import { useEventListener } from ".";
+import { isArray } from "../helpers/types";
 
 /**
  * Watches for clicks outside of the given element and calls the
@@ -16,7 +17,7 @@ import { useEventListener } from ".";
  *   listener when the extraordinary circumstances arise.
  * 
  * @typedef {import('vue').Ref<Element>} ElementRef
- * @param {ElementRef[]} elRefs - The elements to watch for clicks outside of.
+ * @param {ElementRef|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.
@@ -40,6 +41,11 @@ import { useEventListener } from ".";
  */
 export default function useOutsideClick( elRefs, callback, { on = "click" } = {})
 {
+	if( ! isArray( elRefs ))
+	{
+		elRefs = [ elRefs ];
+	}
+
 	return useEventListener( document, on, e =>
 	{
 		if( elRefs.length === 0 )

package/composables/use-pointer-swipe.js

@@ -1,4 +1,4 @@
-import { ref, reactive, computed, onMounted, onUnmounted } from "vue";
+import { ref, isRef, watch, reactive, computed, onMounted, onUnmounted } from "vue";
 import { useEventListener } from ".";
 
 /**
@@ -61,30 +61,6 @@ export default function usePointerSwipe( maybeRefEl, { threshold = 50, disableTe
 		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 )
@@ -101,6 +77,67 @@ export default function usePointerSwipe( maybeRefEl, { threshold = 50, disableTe
 		}
 	});
 
+	if( isRef( maybeRefEl ))
+	{
+		watch( maybeRefEl, listen, { immediate: true });
+	}
+	else
+	{
+		listen();
+	}
+
+	function listen()
+	{
+		useEventListener(
+			maybeRefEl,
+			"pointerdown",
+			onDown
+		);
+	}
+
+	function onDown( e )
+	{
+		onStart( e );
+
+		const stopMoving = useEventListener(
+			maybeRefEl,
+			"pointermove",
+			onMove,
+			{ passive: true, capture: false }
+		);
+
+		useEventListener(
+			maybeRefEl,
+			"pointerup",
+			() => onUp( stopMoving ),
+			{ once: true }
+		);
+	}
+
+	function onStart( e )
+	{
+		isSwiping.value = true;
+		posStart.x = e.clientX;
+		posStart.y = e.clientY;
+		timeStart.value = performance.now();
+	}
+	
+	function onMove( e )
+	{
+		posEnd.x = e.clientX;
+		posEnd.y = e.clientY;
+		distanceX.value = posEnd.x - posStart.x;
+		distanceY.value = posEnd.y - posStart.y;
+	}
+
+	function onUp( stopMoving )
+	{
+		isSwiping.value = false;
+		timeEnd.value = performance.now();
+
+		stopMoving();
+	}
+
 	return {
 		isSwiping,
 		posStart,