mark-3 0.0.4 → 0.0.6

package/composables/use-swipeable-drawer.js

@@ -0,0 +1,161 @@
+import { ref, watch, provide } from "vue";
+import { usePointerSwipe } from ".";
+
+/**
+ * A composition function that provides a swipeable drawer.
+ *
+ * @param {string} name - A unique name for the drawer.
+ * @param {object} [options] - Configuration options.
+ * @param {number} [options.drawerSize=0] - The width of the drawer.
+ * @param {"horizontal"|"vertical"} [options.axis="horizontal"] - The axis of the drawer's movement.
+ * @param {"left"|"right"|"up"|"down"} [options.openFrom="left"] - The starting position of the drawer.
+ * @returns {SwipeableDrawerReturnValue} - An object containing reactive properties
+ * and methods related to the drawer.
+ */
+export default function useSwipeableDrawer(
+	name,
+	{ drawerSize, axis = "horizontal", openFrom = "left" } = {}
+)
+{
+	const swipeDistance = ref( 0 );
+	const swipeableEl = ref( null );
+	const swipeTriggerEl = ref( null );
+	const isDrawerOpen = ref( false );
+	const { min, max } = Math;
+
+	const { isSwiping, distanceX, distanceY, direction, velocity } =
+		usePointerSwipe( swipeTriggerEl,
+		{
+			threshold: 0
+		});
+
+	const axialDistance = (
+	{
+		horizontal: distanceX,
+		vertical: distanceY
+	})[ axis ];
+
+	const motionReversalMap =
+	{
+		left: "right",
+		right: "left",
+		up: "down",
+		down: "up"
+	}
+
+	watch( axialDistance, () =>
+	{
+		// opening movement
+		if( direction.value == openFrom )
+		{
+			if( isDrawerOpen.value )
+			{
+				return;
+			}
+
+			swipeDistance.value = min( drawerSize, axialDistance.value );
+		}
+		// closing movement
+		else if( direction.value == reverse( openFrom ))
+		{
+			if( ! isDrawerOpen.value )
+			{
+				return;
+			}
+			
+			swipeDistance.value = max( 0, drawerSize + axialDistance.value );
+		}
+	});
+
+	watch( isSwiping, () =>
+	{
+		if( isSwiping.value )
+		{
+			return;
+		}
+
+		// opening movement
+		if( direction.value == openFrom )
+		{
+			velocity.value >= 0.25 || swipeDistance.value > .35 * drawerSize
+				? open()
+				: close();
+		}
+		// closing movement
+		else if( direction.value == reverse( openFrom ))
+		{
+			velocity.value >= 0.25 || swipeDistance.value < .65 * drawerSize
+				? close()
+				: open();
+		}
+		// movements on the other axis
+		else
+		{
+			close();
+		}
+	});
+
+	function open()
+	{
+		swipeDistance.value = drawerSize;
+		isDrawerOpen.value = true;
+	}
+
+	function close()
+	{
+		swipeDistance.value = 0;
+		isDrawerOpen.value = false;
+	}
+
+	function toggle()
+	{
+		isDrawerOpen.value
+			? close()
+			: open();
+	}
+
+	function reverse( motion )
+	{
+		return motionReversalMap[ motion ];
+	}
+
+	const returnValue =
+	{
+		swipeableEl,
+		swipeTriggerEl,
+		isSwiping,
+		swipeDistance,
+		isDrawerOpen,
+		openDrawer: open,
+		closeDrawer: close,
+		toggleDrawer: toggle
+	}
+
+	provide( "drawer:" + name, returnValue );
+	
+	return returnValue;
+}
+
+/**
+ * @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} SwipeableDrawerReturnValue
+ * @property {Ref<EventTarget>} swipeableEl - The element that is the drawer.
+ * @property {Ref<EventTarget>} swipeTriggerEl - The element that can trigger the drawer's opening.
+ * @property {Ref<boolean>} isSwiping - Indicates if a swipe is currently happening.
+ * @property {Ref<number>} swipeDistance - The distance of the drawer from its starting position.
+ * @property {Ref<boolean>} isDrawerOpen - Indicates if the drawer is open.
+ * @property {function():void} openDrawer - Opens the drawer.
+ * @property {function():void} closeDrawer - Closes the drawer.
+ * @property {function():void} toggleDrawer - Toggles the drawer's open state.
+ */

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

package/helpers/string/{camel-to-dash/index.js → camel-to-dash.js}

@@ -1,5 +1,5 @@
-import { trim } from "..";
-import { isString } from "../../types";
+import { trim } from ".";
+import { isString } from "../types";
 
 /**
  * Converts a camelCase string to dash-case.

package/helpers/string/encode-subscript.js

@@ -0,0 +1,45 @@
+const map =
+{ 
+	0: "₀", 1: "₁", 2: "₂", 3: "₃", 4: "₄", 5: "₅", 6: "₆", 7: "₇", 8: "₈", 9: "₉",
+	a: "ₐ", e: "ₑ", h: "ₕ", k: "ₖ", l: "ₗ", m: "ₘ", n: "ₙ", o: "ₒ", p: "ₚ", s: "ₛ",
+	t: "ₜ", "+": "₊", "-": "₋", "=": "₌", "(": "₍", ")": "₎",
+}
+
+/**
+ * Converts a given string into its subscript equivalent, if available.
+ *
+ * @param {string} str - The string to be converted.
+ * @param {boolean} [rollbackWhenMismatch=true] If true, returns the original string
+ *  a character is not in the map.
+ * @returns {string} The subscript representation of the string if it exists in the
+ * map, otherwise the original string.
+ */
+export default function encodeSubscript( str, rollbackWhenMismatch = true )
+{
+	if( typeof str !== "string" )
+	{
+		return str;
+	}
+
+	if( rollbackWhenMismatch )
+	{
+		let stack = "";
+
+		for( let char of str )
+		{
+			if( ! ( char in map ))
+			{
+				return str;
+			}
+
+			stack += map[ char ];
+		}
+
+		return stack;
+	}
+	
+	return str
+		.split( "" )
+		.map( char => map[ char ] || char )
+		.join( "" );
+}

package/helpers/string/encode-superscript.js

@@ -0,0 +1,46 @@
+const map =
+{
+	1: "¹", 2: "²", 3: "³", 4: "⁴", 5: "⁵", 6: "⁶", 7: "⁷", 8: "⁸", 9: "⁹", 0: "⁰",
+	a: "ᵃ", b: "ᵇ", c: "ᶜ", d: "ᵈ", e: "ᵉ", f: "ᶠ", g: "ᵍ", h: "ʰ", i: "ⁱ", j: "ʲ",
+	k: "ᵏ", l: "ˡ", m: "ᵐ", n: "ⁿ", o: "ᵒ", p: "ᵖ", r: "ʳ", s: "ˢ", t: "ᵗ", u: "ᵘ",
+	v: "ᵛ", w: "ʷ", x: "ˣ", y: "ʸ", z: "ᶻ",
+}
+
+/**
+ * Converts a given string into its superscript equivalent, if available.
+ *
+ * @param {string} str - The string to be converted.
+ * @param {boolean} [rollbackWhenMismatch=true] If true, returns the original string
+ * when a character is not in the map.
+ * @returns {string} The superscript representation of the string if it exists in the
+ * map, otherwise the original string.
+ */
+export default function convertToSuperscript( str, rollbackWhenMismatch = true )
+{
+	if( typeof str !== "string" )
+	{
+		return str;
+	}
+
+	if( rollbackWhenMismatch )
+	{
+		let stack = "";
+
+		for( let char of str )
+		{
+			if( ! ( char in map ))
+			{
+				return str;
+			}
+
+			stack += map[ char ];
+		}
+
+		return stack;
+	}
+	
+	return str
+		.split( "" )
+		.map( char => map[ char ] || char )
+		.join( "" );
+}

package/helpers/string/{escape-regex/index.js → escape-regex.js}

@@ -1,4 +1,4 @@
-import { isString } from "../../types";
+import { isString } from "../types";
 
 /**
  * Escapes special characters in a string to be used in a regular expression.

package/helpers/string/index.js

@@ -1,3 +1,5 @@
 export { default as trim } from "./trim";
 export { default as escapeRegex } from "./escape-regex";
 export { default as camelToDash } from "./camel-to-dash";
+export { default as encodeSubscript } from "./encode-subscript";
+export { default as encodeSuperscript } from "./encode-superscript";

package/helpers/string/{camel-to-dash/index.test.js → tests/camel-to-dash.test.js}

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

package/helpers/string/tests/encode-subscript.test.js

@@ -0,0 +1,41 @@
+import { describe, it, expect } from "vitest";
+import { encodeSubscript } from "..";
+
+describe("encodeSubscript", () =>
+{
+	it("converts full match to subscript", () =>
+	{
+		expect(encodeSubscript("h2o")).toBe("ₕ₂ₒ");
+		expect(encodeSubscript("123")).toBe("₁₂₃");
+	});
+
+	it("returns original string if any character mismatches and rollbackWhenMismatch is true", () =>
+	{
+		expect(encodeSubscript("H2O")).toBe("H2O"); // 'H' and 'O' not in map
+		expect(encodeSubscript("x+2")).toBe("x+2"); // 'x' not in map
+	});
+
+	it("fallbacks partially when rollbackWhenMismatch is false", () =>
+	{
+		expect(encodeSubscript("x+2", false)).toBe("x₊₂");
+		expect(encodeSubscript("H2O", false)).toBe("H₂O");
+	});
+
+	it("returns non-string inputs as-is", () =>
+	{
+		expect(encodeSubscript(null)).toBe(null);
+		expect(encodeSubscript(undefined)).toBe(undefined);
+		expect(encodeSubscript(123)).toBe(123);
+		expect(encodeSubscript({})).toEqual({});
+	});
+
+	it("handles empty string correctly", () =>
+	{
+		expect(encodeSubscript("")).toBe("");
+	});
+
+	it("works with symbols like + - ( )", () =>
+	{
+		expect(encodeSubscript("2+(3-1)", false)).toBe("₂₊₍₃₋₁₎");
+	});
+});