@oscarpalmer/atoms 0.9.0 → 0.10.0

package/dist/js/element/index.js

@@ -0,0 +1,60 @@
+// src/js/element/index.ts
+function findElements(selector, context) {
+  const contexts = context === undefined ? [document] : findElements(context);
+  const elements = [];
+  if (typeof selector === "string") {
+    for (const context2 of contexts) {
+      elements.push(...Array.from(context2.querySelectorAll(selector) ?? []));
+    }
+    return elements;
+  }
+  const nodes = Array.isArray(selector) || selector instanceof NodeList ? selector : [selector];
+  for (const node of nodes) {
+    if (node instanceof Element && contexts.some((context2) => context2.contains(node))) {
+      elements.push(node);
+    }
+  }
+  return elements;
+}
+function findParentElement(origin, selector) {
+  if (origin == null || selector == null) {
+    return;
+  }
+  function matches(element) {
+    return typeof selector === "string" ? element.matches?.(selector) ?? false : typeof selector === "function" ? selector(element) : false;
+  }
+  if (matches(origin)) {
+    return origin;
+  }
+  let parent = origin.parentElement;
+  while (parent != null && !matches(parent)) {
+    if (parent === document.body) {
+      return;
+    }
+    parent = parent.parentElement;
+  }
+  return parent ?? undefined;
+}
+function getElementUnderPointer(skipIgnore) {
+  const elements = Array.from(document.querySelectorAll(":hover")).filter((element) => {
+    if (/^head$/i.test(element.tagName)) {
+      return false;
+    }
+    const style = getComputedStyle(element);
+    return typeof skipIgnore === "boolean" && skipIgnore || style.pointerEvents !== "none" && style.visibility !== "hidden";
+  });
+  return elements[elements.length - 1];
+}
+function getTextDirection(element) {
+  const direction = element.getAttribute("dir");
+  if (direction !== null && /^(ltr|rtl)$/i.test(direction)) {
+    return direction.toLowerCase();
+  }
+  return getComputedStyle?.(element)?.direction === "rtl" ? "rtl" : "ltr";
+}
+export {
+  getTextDirection,
+  getElementUnderPointer,
+  findParentElement,
+  findElements
+};

package/dist/js/event.js

@@ -0,0 +1,16 @@
+// src/js/event.ts
+function getEventPosition(event) {
+  let x;
+  let y;
+  if (event instanceof MouseEvent) {
+    x = event.clientX;
+    y = event.clientY;
+  } else if (event instanceof TouchEvent) {
+    x = event.touches[0]?.clientX;
+    y = event.touches[0]?.clientY;
+  }
+  return typeof x === "number" && typeof y === "number" ? { x, y } : undefined;
+}
+export {
+  getEventPosition
+};

package/dist/js/{atoms.js → index.js}

@@ -1,84 +1,3 @@
-// src/js/element/index.ts
-function findParentElement(origin, selector) {
-  if (origin == null || selector == null) {
-    return;
-  }
-  function matches(element) {
-    return typeof selector === "string" ? element.matches?.(selector) ?? false : typeof selector === "function" ? selector(element) : false;
-  }
-  if (matches(origin)) {
-    return origin;
-  }
-  let parent = origin.parentElement;
-  while (parent != null && !matches(parent)) {
-    if (parent === document.body) {
-      return;
-    }
-    parent = parent.parentElement;
-  }
-  return parent ?? undefined;
-}
-function getElementUnderPointer(skipIgnore) {
-  const elements = Array.from(document.querySelectorAll(":hover")).filter((element) => {
-    if (/^head$/i.test(element.tagName)) {
-      return false;
-    }
-    const style = getComputedStyle(element);
-    return typeof skipIgnore === "boolean" && skipIgnore || style.pointerEvents !== "none" && style.visibility !== "hidden";
-  });
-  return elements[elements.length - 1];
-}
-function getTextDirection(element) {
-  const direction = element.getAttribute("dir");
-  if (direction !== null && /^(ltr|rtl)$/i.test(direction)) {
-    return direction.toLowerCase();
-  }
-  return getComputedStyle?.(element)?.direction === "rtl" ? "rtl" : "ltr";
-}
-// src/js/event.ts
-function getPosition(event) {
-  let x;
-  let y;
-  if (event instanceof MouseEvent) {
-    x = event.clientX;
-    y = event.clientY;
-  } else if (event instanceof TouchEvent) {
-    x = event.touches[0]?.clientX;
-    y = event.touches[0]?.clientY;
-  }
-  return typeof x === "number" && typeof y === "number" ? { x, y } : undefined;
-}
-// src/js/number.ts
-function clampNumber(value, min, max) {
-  return Math.min(Math.max(getNumber(value), getNumber(min)), getNumber(max));
-}
-function getNumber(value) {
-  if (typeof value === "number") {
-    return value;
-  }
-  if (typeof value === "symbol") {
-    return NaN;
-  }
-  let parsed = value?.valueOf?.() ?? value;
-  if (typeof parsed === "object") {
-    parsed = parsed?.toString() ?? parsed;
-  }
-  if (typeof parsed !== "string") {
-    return parsed == null ? NaN : typeof parsed === "number" ? parsed : +parsed;
-  }
-  if (/^\s*0+\s*$/.test(parsed)) {
-    return 0;
-  }
-  const trimmed = parsed.trim();
-  if (trimmed.length === 0) {
-    return NaN;
-  }
-  const isBinary = /^0b[01]+$/i.test(trimmed);
-  if (isBinary || /^0o[0-7]+$/i.test(trimmed)) {
-    return parseInt(trimmed.slice(2), isBinary ? 2 : 8);
-  }
-  return +(/^0x[0-9a-f]+$/i.test(trimmed) ? trimmed : trimmed.replace(/_/g, ""));
-}
 // src/js/string.ts
 function createUuid() {
   return "10000000-1000-4000-8000-100000000000".replace(/[018]/g, (substring) => (substring ^ crypto.getRandomValues(new Uint8Array(1))[0] & 15 >> substring / 4).toString(16));
@@ -89,6 +8,7 @@ function getString(value) {
 function isNullableOrWhitespace(value) {
   return value == null || getString(value).trim().length === 0;
 }
+
 // src/js/value.ts
 var _getValue = function(data, key) {
   if (typeof data !== "object" || data === null || /^(__proto__|constructor|prototype)$/i.test(key)) {
@@ -155,8 +75,204 @@ function setValue(data, key, value) {
   }
   return data;
 }
+
+// src/js/number.ts
+function clampNumber(value, min, max) {
+  return Math.min(Math.max(getNumber(value), getNumber(min)), getNumber(max));
+}
+function getNumber(value) {
+  if (typeof value === "number") {
+    return value;
+  }
+  if (typeof value === "symbol") {
+    return NaN;
+  }
+  let parsed = value?.valueOf?.() ?? value;
+  if (typeof parsed === "object") {
+    parsed = parsed?.toString() ?? parsed;
+  }
+  if (typeof parsed !== "string") {
+    return parsed == null ? NaN : typeof parsed === "number" ? parsed : +parsed;
+  }
+  if (/^\s*0+\s*$/.test(parsed)) {
+    return 0;
+  }
+  const trimmed = parsed.trim();
+  if (trimmed.length === 0) {
+    return NaN;
+  }
+  const isBinary = /^0b[01]+$/i.test(trimmed);
+  if (isBinary || /^0o[0-7]+$/i.test(trimmed)) {
+    return parseInt(trimmed.slice(2), isBinary ? 2 : 8);
+  }
+  return +(/^0x[0-9a-f]+$/i.test(trimmed) ? trimmed : trimmed.replace(/_/g, ""));
+}
+
+// src/js/timer.ts
+function repeat(callback, options) {
+  const count = typeof options?.count === "number" ? options.count : Infinity;
+  return timer(callback, { ...{ count }, ...options ?? {} }).start();
+}
+var timer = function(callback, config) {
+  const options = {
+    afterCallback: typeof config.afterCallback === "function" ? config.afterCallback : undefined,
+    callback,
+    count: typeof config.count === "number" && config.count >= 1 ? config.count : 1,
+    interval: typeof config.interval === "number" && config.interval >= 0 ? config.interval : 0
+  };
+  const state = {
+    active: false
+  };
+  const timer2 = Object.create(null);
+  Object.defineProperties(timer2, {
+    active: {
+      get() {
+        return state.active;
+      }
+    },
+    restart: {
+      value() {
+        return work("restart", timer2, state, options);
+      }
+    },
+    start: {
+      value() {
+        return work("start", timer2, state, options);
+      }
+    },
+    stop: {
+      value() {
+        return work("stop", timer2, state, options);
+      }
+    }
+  });
+  return timer2;
+};
+function wait(callback, time) {
+  return timer(callback, {
+    count: 1,
+    interval: time
+  }).start();
+}
+var work = function(type, timer2, state, options) {
+  if (type === "start" && timer2.active || type === "stop" && !timer2.active) {
+    return timer2;
+  }
+  const { afterCallback, callback, count, interval } = options;
+  if (typeof state.frame === "number") {
+    cancelAnimationFrame(state.frame);
+    afterCallback?.(false);
+  }
+  if (type === "stop") {
+    state.active = false;
+    state.frame = undefined;
+    return timer2;
+  }
+  state.active = true;
+  const isRepeated = count > 0;
+  const milliseconds = 16.666666666666668;
+  let index = 0;
+  let start;
+  function step(timestamp) {
+    if (!state.active) {
+      return;
+    }
+    start ??= timestamp;
+    const elapsed = timestamp - start;
+    const maximum = elapsed + milliseconds;
+    const minimum = elapsed - milliseconds;
+    if (minimum < interval && interval < maximum) {
+      if (state.active) {
+        callback(isRepeated ? index : undefined);
+      }
+      index += 1;
+      if (index < count) {
+        start = undefined;
+      } else {
+        state.active = false;
+        state.frame = undefined;
+        afterCallback?.(true);
+        return;
+      }
+    }
+    state.frame = requestAnimationFrame(step);
+  }
+  state.frame = requestAnimationFrame(step);
+  return timer2;
+};
+
+// src/js/element/index.ts
+function findElements(selector, context) {
+  const contexts = context === undefined ? [document] : findElements(context);
+  const elements = [];
+  if (typeof selector === "string") {
+    for (const context2 of contexts) {
+      elements.push(...Array.from(context2.querySelectorAll(selector) ?? []));
+    }
+    return elements;
+  }
+  const nodes = Array.isArray(selector) || selector instanceof NodeList ? selector : [selector];
+  for (const node of nodes) {
+    if (node instanceof Element && contexts.some((context2) => context2.contains(node))) {
+      elements.push(node);
+    }
+  }
+  return elements;
+}
+function findParentElement(origin, selector) {
+  if (origin == null || selector == null) {
+    return;
+  }
+  function matches(element) {
+    return typeof selector === "string" ? element.matches?.(selector) ?? false : typeof selector === "function" ? selector(element) : false;
+  }
+  if (matches(origin)) {
+    return origin;
+  }
+  let parent = origin.parentElement;
+  while (parent != null && !matches(parent)) {
+    if (parent === document.body) {
+      return;
+    }
+    parent = parent.parentElement;
+  }
+  return parent ?? undefined;
+}
+function getElementUnderPointer(skipIgnore) {
+  const elements = Array.from(document.querySelectorAll(":hover")).filter((element) => {
+    if (/^head$/i.test(element.tagName)) {
+      return false;
+    }
+    const style = getComputedStyle(element);
+    return typeof skipIgnore === "boolean" && skipIgnore || style.pointerEvents !== "none" && style.visibility !== "hidden";
+  });
+  return elements[elements.length - 1];
+}
+function getTextDirection(element) {
+  const direction = element.getAttribute("dir");
+  if (direction !== null && /^(ltr|rtl)$/i.test(direction)) {
+    return direction.toLowerCase();
+  }
+  return getComputedStyle?.(element)?.direction === "rtl" ? "rtl" : "ltr";
+}
+
+// src/js/event.ts
+function getEventPosition(event) {
+  let x;
+  let y;
+  if (event instanceof MouseEvent) {
+    x = event.clientX;
+    y = event.clientY;
+  } else if (event instanceof TouchEvent) {
+    x = event.touches[0]?.clientX;
+    y = event.touches[0]?.clientY;
+  }
+  return typeof x === "number" && typeof y === "number" ? { x, y } : undefined;
+}
 export {
+  wait,
   setValue,
+  repeat,
   isObject,
   isNullableOrWhitespace,
   isNullable,
@@ -164,10 +280,11 @@ export {
   getValue,
   getTextDirection,
   getString,
-  getPosition,
   getNumber,
+  getEventPosition,
   getElementUnderPointer,
   findParentElement,
+  findElements,
   createUuid,
   clampNumber
 };

package/dist/js/number.js

@@ -0,0 +1,35 @@
+// src/js/number.ts
+function clampNumber(value, min, max) {
+  return Math.min(Math.max(getNumber(value), getNumber(min)), getNumber(max));
+}
+function getNumber(value) {
+  if (typeof value === "number") {
+    return value;
+  }
+  if (typeof value === "symbol") {
+    return NaN;
+  }
+  let parsed = value?.valueOf?.() ?? value;
+  if (typeof parsed === "object") {
+    parsed = parsed?.toString() ?? parsed;
+  }
+  if (typeof parsed !== "string") {
+    return parsed == null ? NaN : typeof parsed === "number" ? parsed : +parsed;
+  }
+  if (/^\s*0+\s*$/.test(parsed)) {
+    return 0;
+  }
+  const trimmed = parsed.trim();
+  if (trimmed.length === 0) {
+    return NaN;
+  }
+  const isBinary = /^0b[01]+$/i.test(trimmed);
+  if (isBinary || /^0o[0-7]+$/i.test(trimmed)) {
+    return parseInt(trimmed.slice(2), isBinary ? 2 : 8);
+  }
+  return +(/^0x[0-9a-f]+$/i.test(trimmed) ? trimmed : trimmed.replace(/_/g, ""));
+}
+export {
+  getNumber,
+  clampNumber
+};

package/dist/js/string.js

@@ -0,0 +1,15 @@
+// src/js/string.ts
+function createUuid() {
+  return "10000000-1000-4000-8000-100000000000".replace(/[018]/g, (substring) => (substring ^ crypto.getRandomValues(new Uint8Array(1))[0] & 15 >> substring / 4).toString(16));
+}
+function getString(value) {
+  return typeof value === "string" ? value : typeof value?.toString === "function" ? value.toString() : String(value);
+}
+function isNullableOrWhitespace(value) {
+  return value == null || getString(value).trim().length === 0;
+}
+export {
+  isNullableOrWhitespace,
+  getString,
+  createUuid
+};

package/dist/js/timer.js

@@ -0,0 +1,96 @@
+// src/js/timer.ts
+function repeat(callback, options) {
+  const count = typeof options?.count === "number" ? options.count : Infinity;
+  return timer(callback, { ...{ count }, ...options ?? {} }).start();
+}
+var timer = function(callback, config) {
+  const options = {
+    afterCallback: typeof config.afterCallback === "function" ? config.afterCallback : undefined,
+    callback,
+    count: typeof config.count === "number" && config.count >= 1 ? config.count : 1,
+    interval: typeof config.interval === "number" && config.interval >= 0 ? config.interval : 0
+  };
+  const state = {
+    active: false
+  };
+  const timer2 = Object.create(null);
+  Object.defineProperties(timer2, {
+    active: {
+      get() {
+        return state.active;
+      }
+    },
+    restart: {
+      value() {
+        return work("restart", timer2, state, options);
+      }
+    },
+    start: {
+      value() {
+        return work("start", timer2, state, options);
+      }
+    },
+    stop: {
+      value() {
+        return work("stop", timer2, state, options);
+      }
+    }
+  });
+  return timer2;
+};
+function wait(callback, time) {
+  return timer(callback, {
+    count: 1,
+    interval: time
+  }).start();
+}
+var work = function(type, timer2, state, options) {
+  if (type === "start" && timer2.active || type === "stop" && !timer2.active) {
+    return timer2;
+  }
+  const { afterCallback, callback, count, interval } = options;
+  if (typeof state.frame === "number") {
+    cancelAnimationFrame(state.frame);
+    afterCallback?.(false);
+  }
+  if (type === "stop") {
+    state.active = false;
+    state.frame = undefined;
+    return timer2;
+  }
+  state.active = true;
+  const isRepeated = count > 0;
+  const milliseconds = 16.666666666666668;
+  let index = 0;
+  let start;
+  function step(timestamp) {
+    if (!state.active) {
+      return;
+    }
+    start ??= timestamp;
+    const elapsed = timestamp - start;
+    const maximum = elapsed + milliseconds;
+    const minimum = elapsed - milliseconds;
+    if (minimum < interval && interval < maximum) {
+      if (state.active) {
+        callback(isRepeated ? index : undefined);
+      }
+      index += 1;
+      if (index < count) {
+        start = undefined;
+      } else {
+        state.active = false;
+        state.frame = undefined;
+        afterCallback?.(true);
+        return;
+      }
+    }
+    state.frame = requestAnimationFrame(step);
+  }
+  state.frame = requestAnimationFrame(step);
+  return timer2;
+};
+export {
+  wait,
+  repeat
+};

package/dist/js/value.js

@@ -0,0 +1,84 @@
+// src/js/string.ts
+function createUuid() {
+  return "10000000-1000-4000-8000-100000000000".replace(/[018]/g, (substring) => (substring ^ crypto.getRandomValues(new Uint8Array(1))[0] & 15 >> substring / 4).toString(16));
+}
+function getString(value) {
+  return typeof value === "string" ? value : typeof value?.toString === "function" ? value.toString() : String(value);
+}
+function isNullableOrWhitespace(value) {
+  return value == null || getString(value).trim().length === 0;
+}
+
+// src/js/value.ts
+var _getValue = function(data, key) {
+  if (typeof data !== "object" || data === null || /^(__proto__|constructor|prototype)$/i.test(key)) {
+    return;
+  }
+  if (data instanceof Map) {
+    return data.get(key);
+  }
+  return data[key];
+};
+var _setValue = function(data, key, value) {
+  if (typeof data !== "object" || data === null || /^(__proto__|constructor|prototype)$/i.test(key)) {
+    return;
+  }
+  if (data instanceof Map) {
+    data.set(key, value);
+  } else {
+    data[key] = value;
+  }
+};
+function getValue(data, key) {
+  if (typeof data !== "object" || data === null || isNullableOrWhitespace(key)) {
+    return;
+  }
+  const parts = getString(key).split(".").reverse();
+  let position = parts.length;
+  let value = data;
+  while (position--) {
+    value = _getValue(value, parts[position]);
+    if (value == null) {
+      break;
+    }
+  }
+  return value;
+}
+function isArrayOrObject(value) {
+  return /^(array|object)$/i.test(value?.constructor?.name);
+}
+function isNullable(value) {
+  return value == null;
+}
+function isObject(value) {
+  return value?.constructor?.name === "Object";
+}
+function setValue(data, key, value) {
+  if (typeof data !== "object" || data === null || isNullableOrWhitespace(key)) {
+    return data;
+  }
+  const parts = getString(key).split(".").reverse();
+  let position = parts.length;
+  let target = data;
+  while (position--) {
+    const key2 = parts[position];
+    if (position === 0) {
+      _setValue(target, key2, value);
+      break;
+    }
+    let next = _getValue(target, key2);
+    if (typeof next !== "object" || next === null) {
+      next = /^\d+$/.test(parts[position - 1]) ? [] : {};
+      target[key2] = next;
+    }
+    target = next;
+  }
+  return data;
+}
+export {
+  setValue,
+  isObject,
+  isNullable,
+  isArrayOrObject,
+  getValue
+};

package/package.json

@@ -14,40 +14,66 @@
 	"exports": {
 		".": {
 			"types": "./types/index.d.ts",
-			"import": "./dist/js/atoms.js"
+			"import": "./dist/js/index.js"
+		},
+		"./element": {
+			"types": "./types/element/index.d.ts",
+			"import": "./dist/js/element.index.js"
+		},
+		"./event": {
+			"types": "./types/event.d.ts",
+			"import": "./dist/js/event.js"
 		},
 		"./focusable": {
-			"types": "./types/focusable.d.ts",
+			"types": "./types/element/focusable.d.ts",
 			"import": "./dist/js/focusable.js"
 		},
+		"./number": {
+			"types": "./types/number.d.ts",
+			"import": "./dist/js/number.js"
+		},
+		"./string": {
+			"types": "./types/string.d.ts",
+			"import": "./dist/js/string.js"
+		},
 		"./supports-touch": {
 			"types": "./types/touch.d.ts",
 			"import": "./dist/js/touch.js"
 		},
+		"./timer": {
+			"types": "./types/timer.d.ts",
+			"import": "./dist/js/timer.js"
+		},
+		"./value": {
+			"types": "./types/value.d.ts",
+			"import": "./dist/js/value.js"
+		},
 		"./package.json": "./package.json"
 	},
-	"files": ["dist", "src", "types"],
+	"files": [
+		"dist",
+		"src",
+		"types"
+	],
 	"keywords": [],
 	"license": "MIT",
-	"main": "./dist/js/atoms.js",
-	"module": "./dist/js/atoms.js",
+	"main": "./dist/js/index.js",
+	"module": "./dist/js/index.js",
 	"name": "@oscarpalmer/atoms",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/oscarpalmer/atoms.git"
 	},
 	"scripts": {
-		"build": "bun run build:css && bun run build:js && bun run build:js-focusable && bun run build:js-touch && bun run types",
+		"build": "bun run build:css && bun run build:js && bun run types",
 		"build:css": "bunx sass ./src/css:./dist/css --no-source-map",
-		"build:js": "bunx bun build ./src/js/index.ts --outfile ./dist/js/atoms.js",
-		"build:js-focusable": "bunx bun build ./src/js/element/focusable.ts --outfile ./dist/js/focusable.js",
-		"build:js-touch": "bunx bun build ./src/js/touch.ts --outfile ./dist/js/touch.js",
+		"build:js": "bunx bun ./.bun.ts",
 		"test": "bun test --preload ./test/_preload.ts --coverage",
 		"types": "bunx tsc -p ./tsconfig.json",
 		"watch:css": "bunx sass ./src/css:./dist/css --no-source-map --watch",
-		"watch:js": "bun build ./src/js/index.ts --outfile ./dist/js/atoms.js --watch"
+		"watch:js": "bun build ./src/js/index.ts --outfile ./dist/js/index.js --watch"
 	},
 	"type": "module",
 	"types": "./types/index.d.ts",
-	"version": "0.9.0"
+	"version": "0.10.0"
 }

package/src/js/element/index.ts

@@ -1,8 +1,50 @@
+type Selector = string | Element | Element[] | NodeList;
+
 type TextDirection = 'ltr' | 'rtl';
 
+/**
+ * - Find elements that match the selector
+ * - `context` is optional and defaults to `document`
+ */
+export function findElements(
+	selector: Selector,
+	context?: Selector,
+): Element[] {
+	const contexts = context === undefined ? [document] : findElements(context);
+
+	const elements: Element[] = [];
+
+	if (typeof selector === 'string') {
+		for (const context of contexts) {
+			elements.push(
+				...Array.from((context as Element).querySelectorAll(selector) ?? []),
+			);
+		}
+
+		return elements;
+	}
+
+	const nodes =
+		Array.isArray(selector) || selector instanceof NodeList
+			? selector
+			: [selector];
+
+	for (const node of nodes) {
+		if (
+			node instanceof Element &&
+			contexts.some(context => context.contains(node))
+		) {
+			elements.push(node);
+		}
+	}
+
+	return elements;
+}
+
 /**
  * - Find the parent element that matches the selector
  * - Matches may be found by a query string or a callback
+ * - If no match is found, `undefined` is returned
  */
 export function findParentElement(
 	origin: Element,

package/src/js/event.ts

@@ -6,7 +6,7 @@ type Position = {
 /**
  * Get the X- and Y-coordinates from a pointer event
  */
-export function getPosition(
+export function getEventPosition(
 	event: MouseEvent | TouchEvent,
 ): Position | undefined {
 	let x: number | undefined;

package/src/js/index.ts

@@ -2,4 +2,5 @@ export * from './element';
 export * from './event';
 export * from './number';
 export * from './string';
+export * from './timer';
 export * from './value';

package/src/js/timer.ts

@@ -0,0 +1,207 @@
+/**
+ * Callback that runs after the timer has finished (or is stopped)
+ * - `finished` is `true` if the timer was allowed to finish, and `false` if it was stopped
+ */
+type AfterCallback = (finished: boolean) => void;
+
+/**
+ * Callback that runs for each iteration of the timer
+ */
+type IndexedCallback = (index: number) => void;
+
+type Options = {
+	/**
+	 * Callback to run after the timer has finished (or is stopped)
+	 * - `finished` is `true` if the timer was allowed to finish, and `false` if it was stopped
+	 */
+	afterCallback?: AfterCallback;
+	/**
+	 * How many times the timer should repeat
+	 */
+	count?: number;
+	/**
+	 * Interval between each callback
+	 */
+	interval?: number;
+};
+
+type Timer = {
+	/**
+	 * Is the timer running?
+	 */
+	get active(): boolean;
+	/**
+	 * Restarts the timer
+	 */
+	restart: () => Timer;
+	/**
+	 * Starts the timer
+	 */
+	start: () => Timer;
+	/**
+	 * Stops the timer
+	 */
+	stop: () => Timer;
+};
+
+type TimerOptions = {
+	afterCallback?: AfterCallback;
+	callback: IndexedCallback;
+	count: number;
+	interval: number;
+};
+
+type TimerState = {
+	active: boolean;
+	frame?: number;
+};
+
+type WorkType = 'restart' | 'start' | 'stop';
+
+/**
+ * - Creates a timer which calls a callback after a certain amount of time, and repeats it a certain amount of times, with an optional callback after it's finished (or stopped)
+ * - `options.count` defaults to `Infinity`
+ * - `options.time` defaults to `0`
+ * - `options.afterCallback` defaults to `undefined`
+ */
+export function repeat(
+	callback: (index: number) => void,
+	options?: Options,
+): Timer {
+	const count = typeof options?.count === 'number' ? options.count : Infinity;
+
+	return timer(callback, {...{count}, ...(options ?? {})}).start();
+}
+
+function timer(callback: IndexedCallback, config: Options): Timer {
+	const options: TimerOptions = {
+		afterCallback:
+			typeof config.afterCallback === 'function'
+				? config.afterCallback
+				: undefined,
+		callback,
+		count:
+			typeof config.count === 'number' && config.count >= 1 ? config.count : 1,
+		interval:
+			typeof config.interval === 'number' && config.interval >= 0
+				? config.interval
+				: 0,
+	};
+
+	const state: TimerState = {
+		active: false,
+	};
+
+	const timer = Object.create(null);
+
+	Object.defineProperties(timer, {
+		active: {
+			get() {
+				return state.active;
+			},
+		},
+		restart: {
+			value() {
+				return work('restart', timer, state, options);
+			},
+		},
+		start: {
+			value() {
+				return work('start', timer, state, options);
+			},
+		},
+		stop: {
+			value() {
+				return work('stop', timer, state, options);
+			},
+		},
+	});
+
+	return timer;
+}
+
+/**
+ * - Creates a timer which calls a callback after a certain amount of time
+ * - `time` defaults to `0`
+ */
+export function wait(callback: () => void, time?: number): Timer {
+	return timer(callback, {
+		count: 1,
+		interval: time,
+	}).start();
+}
+
+function work(
+	type: WorkType,
+	timer: Timer,
+	state: TimerState,
+	options: TimerOptions,
+): Timer {
+	if (
+		(type === 'start' && timer.active) ||
+		(type === 'stop' && !timer.active)
+	) {
+		return timer;
+	}
+
+	const {afterCallback, callback, count, interval} = options;
+
+	if (typeof state.frame === 'number') {
+		cancelAnimationFrame(state.frame);
+
+		afterCallback?.(false);
+	}
+
+	if (type === 'stop') {
+		state.active = false;
+		state.frame = undefined;
+
+		return timer;
+	}
+
+	state.active = true;
+
+	const isRepeated = count > 0;
+	const milliseconds = 1000 / 60;
+
+	let index = 0;
+
+	let start: DOMHighResTimeStamp | undefined;
+
+	function step(timestamp: DOMHighResTimeStamp): void {
+		if (!state.active) {
+			return;
+		}
+
+		start ??= timestamp;
+
+		const elapsed = timestamp - start;
+		const maximum = elapsed + milliseconds;
+		const minimum = elapsed - milliseconds;
+
+		if (minimum < interval && interval < maximum) {
+			if (state.active) {
+				callback((isRepeated ? index : undefined) as never);
+			}
+
+			index += 1;
+
+			if (index < count) {
+				start = undefined;
+			} else {
+				state.active = false;
+				state.frame = undefined;
+
+				afterCallback?.(true);
+
+				return;
+			}
+		}
+
+		state.frame = requestAnimationFrame(step);
+	}
+
+	state.frame = requestAnimationFrame(step);
+
+	return timer;
+}

package/types/element/index.d.ts

@@ -1,7 +1,14 @@
+type Selector = string | Element | Element[] | NodeList;
 type TextDirection = 'ltr' | 'rtl';
+/**
+ * - Find elements that match the selector
+ * - `context` is optional and defaults to `document`
+ */
+export declare function findElements(selector: Selector, context?: Selector): Element[];
 /**
  * - Find the parent element that matches the selector
  * - Matches may be found by a query string or a callback
+ * - If no match is found, `undefined` is returned
  */
 export declare function findParentElement(origin: Element, selector: string | ((element: Element) => boolean)): Element | undefined;
 /**

package/types/event.d.ts

@@ -5,5 +5,5 @@ type Position = {
 /**
  * Get the X- and Y-coordinates from a pointer event
  */
-export declare function getPosition(event: MouseEvent | TouchEvent): Position | undefined;
+export declare function getEventPosition(event: MouseEvent | TouchEvent): Position | undefined;
 export {};

package/types/index.d.ts

@@ -2,4 +2,5 @@ export * from './element';
 export * from './event';
 export * from './number';
 export * from './string';
+export * from './timer';
 export * from './value';

package/types/timer.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Callback that runs after the timer has finished (or is stopped)
+ * - `finished` is `true` if the timer was allowed to finish, and `false` if it was stopped
+ */
+type AfterCallback = (finished: boolean) => void;
+type Options = {
+    /**
+     * Callback to run after the timer has finished (or is stopped)
+     * - `finished` is `true` if the timer was allowed to finish, and `false` if it was stopped
+     */
+    afterCallback?: AfterCallback;
+    /**
+     * How many times the timer should repeat
+     */
+    count?: number;
+    /**
+     * Interval between each callback
+     */
+    interval?: number;
+};
+type Timer = {
+    /**
+     * Is the timer running?
+     */
+    get active(): boolean;
+    /**
+     * Restarts the timer
+     */
+    restart: () => Timer;
+    /**
+     * Starts the timer
+     */
+    start: () => Timer;
+    /**
+     * Stops the timer
+     */
+    stop: () => Timer;
+};
+/**
+ * - Creates a timer which calls a callback after a certain amount of time, and repeats it a certain amount of times, with an optional callback after it's finished (or stopped)
+ * - `options.count` defaults to `Infinity`
+ * - `options.time` defaults to `0`
+ * - `options.afterCallback` defaults to `undefined`
+ */
+export declare function repeat(callback: (index: number) => void, options?: Options): Timer;
+/**
+ * - Creates a timer which calls a callback after a certain amount of time
+ * - `time` defaults to `0`
+ */
+export declare function wait(callback: () => void, time?: number): Timer;
+export {};