mark-3 0.0.5 → 0.0.9

package/CHANGELOG.md

@@ -2,6 +2,50 @@
 
 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.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)
+
+
+### 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)
 
 

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,255 @@
+<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
+				: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, floor } = Math;
+const heights = ref<number[]>([]);
+const identifiedItems = reactive<{ item: any, index: number }[]>([]);
+const container = ref<HTMLDivElement>( null );
+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 });
+
+
+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;
+});
+
+if( props.dontWatchResizing === false )
+{
+	useEventListener( window, "resize", debounce( resetHeights, 100 ), { passive: true });
+}
+
+function resetHeights()
+{
+	heights.value = identifiedItems.map(() => props.minHeight );
+	isHeightsDirty.value = true;
+}
+
+</script>

package/composables/index.js

@@ -1,5 +1,11 @@
 export { default as useMediaQuery } from "./use-media-query.js";
+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 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,4 +1,4 @@
-import { onMounted, onUnmounted, getCurrentInstance } from "vue";
+import { isRef, unref, onMounted, onUnmounted, getCurrentInstance } from "vue";
 
 /**
  * A composition function that adds a DOM event listener to the given target with the
@@ -8,15 +8,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.
+ * @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( target, eventName, callBack, options )
+export default function useEventListener( maybeRefTarget, eventName, callBack, options )
 {
-	if( getCurrentInstance())
+	if( getCurrentInstance() && isRef( maybeRefTarget ))
 	{
 		onMounted( listen );
 		onUnmounted( stop );
@@ -28,13 +28,35 @@ 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;
 }
+
+/**
+ * @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
+ */

package/composables/use-outside-clicks.js

@@ -0,0 +1,68 @@
+import { useEventListener } from ".";
+import { isArray } from "../helpers/types";
+
+/**
+ * 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|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" } = {})
+{
+	if( ! isArray( elRefs ))
+	{
+		elRefs = [ elRefs ];
+	}
+
+	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 );
+	});
+}