mark-3 0.0.6 → 0.0.9

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 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)
 
 

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,8 +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 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";
 
-/**
- * @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,7 +11,7 @@ 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 )
@@ -52,3 +48,15 @@ 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
+ */

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-resize-observer.js

@@ -0,0 +1,93 @@
+import { onUnmounted } from "vue";
+import { throttle as throttleHelper } from "../helpers/time";
+
+/**
+ * A composition function that creates a ResizeObserver instance and provides
+ * methods to observe elements for their resize events.
+ *
+ * @param {ResizeObserverCallback} callback - The callback function
+ *   to call when the observed elements are resized
+ * @returns {ResizeObserverReturnValue}
+ *   An object with three properties. The `observe` property is a function that
+ *   takes an element to observe and begins observing it for resize events.
+ *   The `unobserve` property is a function that takes an element to no longer
+ *   observe and stops observing it for resize events. The `disconnect` property
+ *   is a function that disconnects the ResizeObserver instance and clears the
+ *   set of observed elements.
+ */
+export default function useResizeObserver( callback, { throttle = 0 } = {})
+{
+	const observedElements = new Set;
+	
+	const maybeThrottledCallback = throttle
+		? throttleHelper( callback, throttle )
+		: callback;
+	
+	const observer = new ResizeObserver( entries =>
+	{
+		maybeThrottledCallback( entries );
+	});
+
+	onUnmounted( disconnect );
+
+	function observe( el )
+	{
+		if( ! el || observedElements.has( el ))
+		{
+			return;
+		}
+
+		observer.observe( el );
+		observedElements.add( el );
+	}
+
+	function unobserve( el )
+	{
+		if( ! el )
+		{
+			return;
+		}
+
+		observer.unobserve( el );
+		observedElements.delete( el );
+	}
+
+	function disconnect()
+	{
+		observer.disconnect();
+		observedElements.clear();
+	}
+
+	return {
+		observe,
+		unobserve,
+		disconnect
+	}
+}
+/**
+ * Callback function to be invoked when observed elements are resized.
+ *
+ * @callback ResizeObserverCallback
+ * @param {ResizeObserverEntry[]} entries - An array of ResizeObserverEntry objects
+ *   for each observed element that has changed size.
+ */
+/**
+ * @callback ObserveMethod
+ * @param {EventTarget} el - The element to observe
+ * @returns {void}
+ */
+/**
+ * @callback UnobserveMethod
+ * @param {EventTarget} el - The element to stop observing
+ * @returns {void}
+ */
+/**
+ * @callback DisconnectMethod
+ * @returns {void}
+ */
+/**
+ * @typedef {object} ResizeObserverReturnValue
+ * @property {ObserveMethod} observe - A function to observe an element for resize events
+ * @property {UnobserveMethod} unobserve - A function to stop observing an element for resize events
+ * @property {DisconnectMethod} disconnect - A function to disconnect the ResizeObserver instance
+ */

package/composables/use-scroll-event.js

@@ -1,19 +1,3 @@
-/**
- * @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
@@ -23,11 +7,7 @@
  * 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
+ * @param {LatestScrollMetrics} metrics latest scroll metrics
  * @return {ScrollMetrics}
  */
 export default function useScrollEvent(
@@ -95,3 +75,27 @@ export default function useScrollEvent(
 		horizontal
 	}
 }
+/**
+ * @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
+ */
+/**
+ * @typedef LatestScrollMetrics
+ * @type {object}
+ * @property {number} [latestScrollTop=0] latest vertically scrolled pixel
+ * @property {number} [latestScrollLeft=0] latest horizontally scrolled pixel
+ * @property {number} [biggestScrollLeft=0] biggest horizontally scrolled pixel
+ * @property {number} [biggestScrollTop=0] biggest vertically scrolled pixel
+ */