mark-3 0.0.4 → 0.0.5

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 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.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,5 @@
 export { default as useMediaQuery } from "./use-media-query.js";
+export { default as useScrollEvent } from "./use-scroll-event.js";
 export { default as useEventListener } from "./use-event-listener.js";
 export { default as useResponsiveness } from "./use-responsiveness.js";
+export { default as useIntersectionObserver } from "./use-intersection-observer.js";

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-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
+	}
+}

package/helpers/array/index.js

@@ -0,0 +1 @@
+export { default as pickRandom } from "./pick-random";

package/helpers/array/pick-random.js

@@ -0,0 +1,24 @@
+import { random } from "../number";
+import { isArray } from "../types";
+
+/**
+ * Picks a random element from the given array.
+ * 
+ * @template T
+ * @param {T[]} arr - The array to pick a random element from.
+ * @returns {T|undefined} - The random element from the array, or undefined if the array is empty.
+ */
+export default function pickRandom( arr )
+{
+	if( ! isArray( arr ))
+	{
+		return undefined;
+	}
+
+	if( arr.length === 0 )
+	{
+		return undefined;
+	}
+
+	return arr[ random( 0, arr.length - 1 )];
+}

package/helpers/array/tests/pick-random.test.js

@@ -0,0 +1,39 @@
+import { describe, it, expect } from "vitest";
+import { pickRandom } from "..";
+
+// örnek test verisi
+const sampleArray = [10, 20, 30, 40, 50];
+
+describe("pickRandom", () =>
+{
+	it("should return undefined if input is not an array", () =>
+	{
+		expect(pickRandom(null)).toBeUndefined();
+		expect(pickRandom({})).toBeUndefined();
+		expect(pickRandom("not array")).toBeUndefined();
+		expect(pickRandom(123)).toBeUndefined();
+	});
+
+	it("should return undefined if array is empty", () =>
+	{
+		expect(pickRandom([])).toBeUndefined();
+	});
+
+	it("should return an element from the array", () =>
+	{
+		const value = pickRandom(sampleArray);
+		expect(sampleArray).toContain(value);
+	});
+
+	it("should return different results across multiple calls", () =>
+	{
+		const results = new Set();
+		for (let i = 0; i < 20; i++)
+		{
+			const val = pickRandom(sampleArray);
+			results.add(val);
+		}
+		// Rastgelelik garantisi yok ama çeşitlilik kontrolü yapılabilir
+		expect(results.size).toBeGreaterThan(1);
+	});
+});

package/helpers/date/index.js

@@ -1,4 +1,4 @@
 export { default as format } from "./format";
 export { default as isOnSameDay } from "./is-on-same-day";
-export { default as fromTimestamp } from "./from-timestamp";
+export { default as fromTimestamp } from "./format-timestamp";
 export { default as isOnSameYear } from "./is-on-same-year";

package/helpers/date/{from-timestamp/index.test.js → tests/format-timestamp.test.js}

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import fromTimestamp from "./index";
+import { fromTimestamp } from "..";
 
 describe( "fromTimestamp", () =>
 {

package/helpers/date/tests/format.test.js

@@ -0,0 +1,97 @@
+import { describe, it, expect } from "vitest";
+import { format } from "..";
+
+describe( "format", () =>
+{
+	const date = new Date( "2025-12-21T22:10:05" );
+
+	it( "formats full year (Y)", () =>
+	{
+		expect( format( date, "Y" )).toBe( "2025" );
+	});
+	
+	it( "formats short year (y)", () =>
+	{
+		expect( format( date, "y" )).toBe( "25" );
+	});
+	
+	it( "formats zero-padded month (m)", () =>
+	{
+		expect( format( date, "m" )).toBe( "12" );
+	});
+	
+	it( "formats non-padded month (n)", () =>
+	{
+		expect( format( date, "n" )).toBe( "12" );
+	});
+	
+	it( "formats short month name (M)", () =>
+	{
+		expect( format( date, "M" )).toBe( "Dec" );
+	});
+	
+	it( "formats full month name (MM)", () =>
+	{
+		expect( format( date, "MM" )).toBe( "December" );
+	});
+	
+	it( "formats day padded (d)", () =>
+	{
+		expect( format( date, "d" )).toBe( "21" );
+	});
+	
+	it( "formats day non-padded (j)", () =>
+	{
+		expect( format( date, "j" )).toBe( "21" );
+	});
+	
+	it( "formats zero-padded hour (H)", () =>
+	{
+		expect( format( date, "H" )).toBe( "22" );
+	});
+	
+	it( "formats non-padded hour (G)", () =>
+	{
+		expect( format( date, "G" )).toBe( "22" );
+	});
+	
+	it( "formats minutes (i)", () =>
+	{
+		expect( format( date, "i" )).toBe( "10" );
+	});
+	
+	it( "formats seconds (s)", () =>
+	{
+		expect( format( date, "s" )).toBe( "05" );
+	});
+	
+	it( "formats a custom pattern", () =>
+	{
+		expect( format( date, "d.m.Y H:i" )).toBe( "21.12.2025 22:10" );
+	});
+	
+	it( "supports localized short month (M) in TR", () =>
+	{
+		expect( format( date, "M", "tr" )).toBe( "Ara" ); // Aralık
+	});
+	
+	it( "supports localized long month (MM) in TR", () =>
+	{
+		expect( format( date, "MM", "tr" )).toBe( "Aralık" );
+	});
+	
+	it( "returns empty string for empty pattern", () =>
+	{
+		expect( format( date, "" )).toBe( "" );
+	});
+	
+	it( "leaves unknown tokens as-is", () =>
+	{
+		expect( format( date, "[foo] Y" )).toBe( "[foo] 2025" );
+	});
+	
+	it( "mixes plain text and tokens", () =>
+	{
+		expect( format( date, "d MM Y, H:i" )).toBe( "21 December 2025, 22:10" );
+	});
+});

package/helpers/date/{is-on-same-day/index.test.js → tests/is-on-same-day.test.js}

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import isOnSameDay from "./index";
+import { isOnSameDay } from "..";
 
 describe( "isOnSameDay", () =>
 {

package/helpers/date/{is-on-same-year/index.test.js → tests/is-on-same-year.test.js}

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import isOnSameYear from "./index";
+import { isOnSameYear } from "..";
 
 describe( "isOnSameYear", () =>
 {

package/helpers/number/clamp.js

@@ -0,0 +1,17 @@
+/**
+ * Clamps a value within a range.
+ *
+ * @param {number} value value to be clamped
+ * @param {number} min minimum value
+ * @param {number} max maximum value
+ * @return {number} clamped value
+ */
+export default function clamp( value, min, max )
+{
+	if( min > max )
+	{
+		[ min, max ] = [ max, min ];
+	}
+
+	return Math.max( min, Math.min( max, value ));
+}

package/helpers/number/index.js

@@ -0,0 +1,2 @@
+export { default as clamp } from "./clamp";
+export { default as random } from "./random";

package/helpers/number/random.js

@@ -0,0 +1,24 @@
+import { clamp } from ".";
+
+/**
+ * Produce a random number between two values. If no value is provided,
+ * a random number is produced.
+ *
+ * @param {number} min minimum value
+ * @param {number} max maximum value
+ * @param {boolean} shouldFloat should the result be a float
+ * @return {number}
+ */
+export default function random( min = 0, max = 1, shouldFloat = false )
+{
+	if( min > max )
+	{
+		[ min, max ] = [ max, min ];
+	}
+
+	const rnd = clamp( Math.random() * max, min, max );
+
+	return shouldFloat
+		? parseFloat( rnd )
+		: Math.floor( rnd );
+}

package/helpers/number/tests/clamp.test.js

@@ -0,0 +1,37 @@
+import { describe, it, expect } from "vitest";
+import { clamp } from "..";
+
+describe("clamp()", () =>
+{
+	it("returns the same value if it is within the min and max range", () =>
+	{
+		expect(clamp(5, 0, 10)).toBe(5);
+		expect(clamp(0, -10, 10)).toBe(0);
+		expect(clamp(9.5, 0, 10)).toBe(9.5);
+	});
+
+	it("clamps the value to the min if it is less than min", () =>
+	{
+		expect(clamp(-5, 0, 10)).toBe(0);
+		expect(clamp(-100, -10, 10)).toBe(-10);
+	});
+
+	it("clamps the value to the max if it is greater than max", () =>
+	{
+		expect(clamp(15, 0, 10)).toBe(10);
+		expect(clamp(99, -10, 10)).toBe(10);
+	});
+
+	it("returns the only possible value if min and max are equal", () =>
+	{
+		expect(clamp(5, 7, 7)).toBe(7);
+		expect(clamp(10, 10, 10)).toBe(10);
+		expect(clamp(-5, -3, -3)).toBe(-3);
+	});
+
+	it("swaps min and max if needed", () =>
+	{
+		expect(clamp(5, 10, 0)).toBe(5);
+		expect(clamp(-5, 3, -3)).toBe(-3);
+	});
+});

package/helpers/number/tests/random.test.js

@@ -0,0 +1,51 @@
+import { describe, it, expect } from "vitest";
+import { random } from "..";
+
+describe("random", () =>
+{
+	it("should return a number between 0 and 1 by default", () =>
+	{
+		const result = random();
+		expect(result).toBeGreaterThanOrEqual(0);
+		expect(result).toBeLessThanOrEqual(1);
+		expect(Number.isInteger(result)).toBe(true);
+	});
+
+	it("should return float if shouldFloat is true", () =>
+	{
+		const result = random(0, 1, true);
+		expect(result).toBeGreaterThanOrEqual(0);
+		expect(result).toBeLessThanOrEqual(1);
+		expect(Number.isInteger(result)).toBe(false);
+	});
+
+	it("should respect min and max range with integers", () =>
+	{
+		const result = random(5, 10);
+		expect(result).toBeGreaterThanOrEqual(5);
+		expect(result).toBeLessThanOrEqual(10);
+		expect(Number.isInteger(result)).toBe(true);
+	});
+
+	it("should respect min and max range with floats", () =>
+	{
+		const result = random(5, 10, true);
+		expect(result).toBeGreaterThanOrEqual(5);
+		expect(result).toBeLessThanOrEqual(10);
+	});
+
+	it("should always return at least the min value", () =>
+	{
+		for (let i = 0; i < 100; i++)
+		{
+			const result = random(10, 20);
+			expect(result).toBeGreaterThanOrEqual(10);
+		}
+	});
+
+	it("should return exactly min if min and max are both 0", () =>
+	{
+		const result = random(0, 0);
+		expect(result).toBe(0);
+	});
+});