@rokkit/helpers 1.0.0-next.101

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jerry Thomas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/src/index.d.ts

@@ -0,0 +1 @@
+export * from "./simulators/touch";

package/dist/src/matchers/action.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Checks if all the given events are registered by the action and cleaned up on destroy.
+ *
+ * @param {*} action
+ * @param {Object<string,any>} options
+ * @param {string|Array<string>} events
+ * @returns
+ */
+export function toUseHandlersFor(action: any, options: {
+    [x: string]: any;
+}, events: string | Array<string>): {
+    message: () => string;
+    pass: boolean;
+};
+/**
+ * Verifies that only the specified events are triggered. Expects an object of spies with key as event names.
+ *
+ * @param {Object<string,any>} handler : Object with keys as event names and values as spies
+ * @param {string|Array<string>} events : An event name or an array of event names
+ * @returns
+ */
+export function toOnlyTrigger(handler: {
+    [x: string]: any;
+}, events: string | Array<string>): {
+    message: () => string;
+    pass: boolean;
+};

package/dist/src/matchers/array.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Verify that an array contains all of the expected values
+ *
+ * @param {Array} received - the array to inspect
+ * @param {Array} expected - the values to check for
+ */
+export function toIncludeAll(received: any[], expected: any[]): {
+    message: () => string;
+    pass: boolean;
+};

package/dist/src/matchers/dataset.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Check if the element has valid data attributes
+ *
+ * @param {HTMLElement} received - HTML element to be checked
+ * @param {Object}      expected - data to be compared
+ */
+export function toHaveValidData(received: HTMLElement, expected: Object): {
+    message: () => string;
+    pass: any;
+};

package/dist/src/matchers/event.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Verify that a spy event has been dispatched with data in event detail
+ *
+ * @param {Function} spy  - the event handler to inspect
+ * @param {Object}   data - data expected inthe event detail
+ */
+export function toHaveBeenDispatchedWith(spy: Function, data: Object): {
+    message: () => string;
+    pass: boolean;
+};

package/dist/src/matchers/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./array";
+export * from "./action";
+export * from "./dataset";
+export * from "./event";

package/dist/src/matchers/internal.d.ts

@@ -0,0 +1 @@
+export function getMessage(actual: any, expected: any, pass: any, condition?: string): string;

package/dist/src/mocks/animate.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/mocks/element.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Creates an array of elements with the specified size
+ *
+ * @param {number} count
+ * @param {number} size
+ * @param {string} [prop='offsetHeight']
+ * @returns {Array<Object<string, number>>}
+ */
+export function elementsWithSize(count: number, size: number, prop?: string): Array<{
+    [x: string]: number;
+}>;
+/**
+ * Creates an array of elements with mixed sizes
+ *
+ * @param {Array<{count: number, size: number}>} data
+ * @param {string} prop
+ * @returns {Array<Object<string, number>>}
+ */
+export function mixedSizeElements(data: Array<{
+    count: number;
+    size: number;
+}>, prop: string): Array<{
+    [x: string]: number;
+}>;
+/**
+ * Creates a mock node with functions to add and remove event handlers
+ *
+ * @param {Array<string} events
+ * @returns {{node: HTMLElement, listeners: Object<string, integer>}}
+ */
+export function getMockNode(events: Array<string>): {
+    node: HTMLElement;
+    listeners: {
+        [x: string]: integer;
+    };
+};
+/**
+ * @typedef {Object} NestedItem
+ * @property {string} name
+ * @property {string} [dataPath]
+ * @property {string} [id]
+ * @property {Array<NestedItem>} [children]
+ */
+/**
+ * Creates a nested HTML element structure using the provided data
+ *
+ * @param {NestedItem} item
+ * @returns {HTMLElement}
+ */
+export function createNestedElement(item: NestedItem): HTMLElement;
+export type NestedItem = {
+    name: string;
+    dataPath?: string | undefined;
+    id?: string | undefined;
+    children?: NestedItem[] | undefined;
+};

package/dist/src/mocks/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./match-media";
+export * from "./element";

package/dist/src/mocks/match-media.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Updates the media query matches
+ * @returns {void}
+ */
+export function updateMedia(): void;
+/**
+ * Mocks the window.matchMedia function
+ * @param {string} query
+ * @returns {Object}
+ */
+export const matchMediaMock: import("vitest").Mock<(...args: any[]) => any>;
+export type MediaQuery = {
+    "min-width"?: integer;
+    "max-width"?: integer;
+    "min-height"?: integer;
+    "max-height"?: integer;
+    width?: integer;
+    height?: integer;
+    orientation?: integer;
+    "aspect-ratio"?: integer;
+    "min-aspect-ratio"?: integer;
+    "max-aspect-ratio"?: integer;
+    resolution?: integer;
+    "min-resolution"?: integer;
+    "max-resolution"?: integer;
+    scan?: integer;
+    grid?: integer;
+    update?: integer;
+    "overflow-block"?: integer;
+};

package/dist/src/mocks/resize-observer.d.ts

@@ -0,0 +1,9 @@
+export class ResizeObserver {
+    constructor(callback: any);
+    callback: any;
+    elements: Map<any, any>;
+    observe(element: any): void;
+    unobserve(element: any): void;
+    disconnect(): void;
+    simulateResize(element: any, contentRect: any): void;
+}

package/dist/src/simulators/touch.d.ts

@@ -0,0 +1,16 @@
+export function simulateMouseEvent(x: any, y: any): {
+    clientX: any;
+    clientY: any;
+    stopPropagation: import("vitest").Mock<(...args: any[]) => any>;
+    preventDefault: import("vitest").Mock<(...args: any[]) => any>;
+};
+export function simulateTouchEvent(clientX: any, clientY: any): {
+    touches: {
+        clientX: any;
+        clientY: any;
+    }[];
+    preventDefault: import("vitest").Mock<(...args: any[]) => any>;
+    stopPropagation: import("vitest").Mock<(...args: any[]) => any>;
+};
+export function simulateTouchSwipe(node: any, distance: any, delay?: number): void;
+export function simulateMouseSwipe(node: any, distance: any, delay?: number): void;

package/dist/vitest.config.d.ts

@@ -0,0 +1 @@
+export default defineConfig;

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@rokkit/helpers",
+  "version": "1.0.0-next.101",
+  "description": "Custom matchers for vitest.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "vitest",
+    "matchers",
+    "validators",
+    "svelte"
+  ],
+  "author": "Jerry Thomas<me@jerrythomas.name>",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    "./mocks": "./src/mocks/index.js",
+    "./matchers": "./src/matchers/index.js",
+    "./simulators": "./src/simulators/index.js",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
+  "dependencies": {
+    "@vitest/expect": "^2.1.8",
+    "ramda": "^0.30.1"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "pnpm clean && pnpm prepublishOnly"
+  }
+}

package/spec/index.spec.js

@@ -0,0 +1,14 @@
+import { describe, it, expect } from 'vitest'
+// skipcq: JS-C1003 - Importing all components for verification
+import * as functions from '../src'
+
+describe('functions', () => {
+	it('should contain all exported functions', () => {
+		expect(Object.keys(functions)).toEqual([
+			'simulateMouseEvent',
+			'simulateTouchEvent',
+			'simulateTouchSwipe',
+			'simulateMouseSwipe'
+		])
+	})
+})

package/spec/matchers/action.spec.js

@@ -0,0 +1,102 @@
+import { describe, it, expect, vi, afterEach } from 'vitest'
+import { toOnlyTrigger, toUseHandlersFor } from '../../src/matchers/action'
+
+describe('action', () => {
+	describe('toOnlyTrigger', () => {
+		const handler = {
+			a: vi.fn(),
+			b: vi.fn(),
+			c: vi.fn()
+		}
+
+		expect.extend({ toOnlyTrigger })
+		afterEach(() => {
+			vi.resetAllMocks()
+		})
+
+		it('should pass if only the specified events are triggered', () => {
+			let result = toOnlyTrigger(handler, 'a')
+			expect(result.pass).toBe(false)
+			expect(result.message()).toBe(
+				'Expected only [a] to be called once and the other handlers to not be called'
+			)
+			expect(handler).not.toOnlyTrigger('a')
+
+			handler.a()
+			result = toOnlyTrigger(handler, 'a')
+			expect(result.pass).toBe(true)
+			expect(result.message()).toBe(
+				'Expected other handlers besides [a] to be called, but none were'
+			)
+			expect(handler).toOnlyTrigger('a')
+
+			handler.b()
+			result = toOnlyTrigger(handler, ['a', 'b'])
+			expect(result.pass).toBe(true)
+			expect(result.message()).toBe(
+				'Expected other handlers besides [a, b] to be called, but none were'
+			)
+			expect(handler).toOnlyTrigger(['a', 'b'])
+		})
+
+		it('should fail if no/other events are triggered', () => {
+			let result = toOnlyTrigger(handler, ['a', 'b'])
+			expect(result.pass).toBe(false)
+
+			handler.c()
+			result = toOnlyTrigger(handler, ['a', 'b'])
+			expect(result.pass).toBe(false)
+			expect(result.message()).toBe(
+				'Expected only [a, b] to be called once and the other handlers to not be called'
+			)
+			expect(handler).not.toOnlyTrigger(['a', 'b'])
+		})
+
+		it('should fail if event is not in handler', () => {
+			const result = toOnlyTrigger(handler, ['x'])
+			expect(result.pass).toBe(false)
+			expect(result.message()).toBe('Expected events from [a, b, c] but got unexpected events [x]')
+			expect(handler).not.toOnlyTrigger(['a', 'b'])
+		})
+	})
+
+	describe('toUseHandlersFor', () => {
+		const mockAction = (node, options) => {
+			const handler = vi.fn()
+			node.addEventListener('click', handler)
+			if (options.touch) node.addEventListener('touchstart', handler)
+			return {
+				destroy: () => {
+					node.removeEventListener('click', handler)
+					if (options.touch) node.removeEventListener('touchstart', handler)
+				}
+			}
+		}
+		expect.extend({ toUseHandlersFor })
+
+		it('should pass if all events are registered and cleanued up', () => {
+			let result = toUseHandlersFor(mockAction, {}, 'click')
+			expect(result.pass).toBe(true)
+			expect(result.message()).toBe(
+				'Expected action not to manage handlers for [click] but result is [{"event":"click","created":true,"destroyed":true,"pass":true}]'
+			)
+			expect(mockAction).toUseHandlersFor({}, 'click')
+
+			result = toUseHandlersFor(mockAction, { touch: true }, ['click', 'touchstart'])
+			expect(result.pass).toBe(true)
+			expect(result.message()).toBe(
+				'Expected action not to manage handlers for [click,touchstart] but result is [{"event":"click","created":true,"destroyed":true,"pass":true},{"event":"touchstart","created":true,"destroyed":true,"pass":true}]'
+			)
+			expect(mockAction).toUseHandlersFor({ touch: true }, ['click', 'touchstart'])
+		})
+
+		it('should fail if all events are not registered or not cleaned up', () => {
+			const result = toUseHandlersFor(mockAction, {}, ['click', 'touchstart'])
+			expect(result.pass).toBe(false)
+			expect(result.message()).toBe(
+				'Expected action to manage handlers for [click,touchstart] but result is [{"event":"click","created":true,"destroyed":true,"pass":true},{"event":"touchstart","created":false,"destroyed":true,"pass":false}]'
+			)
+			expect(mockAction).not.toUseHandlersFor({}, ['click', 'touchstart'])
+		})
+	})
+})

package/spec/matchers/array.spec.js

@@ -0,0 +1,33 @@
+import { describe, it, expect, vi, afterEach } from 'vitest'
+import { toIncludeAll } from '../../src/matchers/array'
+
+describe('event', () => {
+	describe('toIncludeAll', () => {
+		expect.extend({ toIncludeAll })
+		afterEach(() => {
+			vi.resetAllMocks()
+		})
+
+		it('should pass if the array includes all the values', () => {
+			const input = [1, 2, 3]
+			const expected = [1, 2]
+			const result = toIncludeAll(input, expected)
+			expect(result.pass).toBe(true)
+			expect(result.message()).toBe(
+				`expected ${JSON.stringify(input)} to not include all of ${JSON.stringify(expected)}`
+			)
+			expect(input).toIncludeAll(expected)
+		})
+
+		it('should fail if the array does not include all the values', () => {
+			const input = [1, 2, 3]
+			const expected = [1, 2, 4]
+			const result = toIncludeAll(input, expected)
+			expect(result.pass).toBe(false)
+			expect(result.message()).toBe(
+				`expected ${JSON.stringify(input)} to include all of ${JSON.stringify(expected)}`
+			)
+			expect(input).not.toIncludeAll(expected)
+		})
+	})
+})

package/spec/matchers/dataset.spec.js

@@ -0,0 +1,32 @@
+import { describe, it, expect, vi, afterEach } from 'vitest'
+import { toHaveValidData } from '../../src/matchers/dataset'
+
+describe('event', () => {
+	describe('toHaveValidData', () => {
+		expect.extend({ toHaveValidData })
+		afterEach(() => {
+			vi.resetAllMocks()
+		})
+
+		it('should pass if the element dataset matches expected', () => {
+			const input = { dataset: { a: 1, b: 2 } }
+			const expected = { a: 1, b: 2 }
+			const result = toHaveValidData(input, expected)
+			expect(result.pass).toBe(true)
+			expect(result.message()).toBe(
+				`expected ${JSON.stringify(input.dataset)} to not deeply equal ${JSON.stringify(expected)}`
+			)
+			expect(input).toHaveValidData(expected)
+		})
+		it('should fail if the element dataset does not match expected', () => {
+			const input = { dataset: { a: 1, b: 2 } }
+			const expected = { a: 1, b: 3 }
+			const result = toHaveValidData(input, expected)
+			expect(result.pass).toBe(false)
+			expect(result.message()).toBe(
+				`expected ${JSON.stringify(input.dataset)} to deeply equal ${JSON.stringify(expected)}`
+			)
+			expect(input).not.toHaveValidData(expected)
+		})
+	})
+})

package/spec/matchers/event.spec.js

@@ -0,0 +1,35 @@
+import { describe, it, expect, vi, afterEach } from 'vitest'
+import { toHaveBeenDispatchedWith } from '../../src/matchers/event'
+
+describe('event', () => {
+	describe('toHaveBeenDispatchedWith', () => {
+		const detail = { foo: 'bar' }
+		const spy = vi.fn()
+
+		expect.extend({ toHaveBeenDispatchedWith })
+		afterEach(() => {
+			vi.resetAllMocks()
+		})
+
+		it('should pass if the event was dispatched with the correct data', () => {
+			spy({ detail })
+			const result = toHaveBeenDispatchedWith(spy, detail)
+
+			expect(result.pass).toBe(true)
+			expect(result.message()).toBe(
+				`expected ${JSON.stringify(detail)} to not deeply equal ${JSON.stringify(detail)}`
+			)
+			expect(spy).toHaveBeenDispatchedWith(detail)
+		})
+
+		it('should fail if the event was dispatched with the incorrect data', () => {
+			spy({ detail: 'baz' })
+			const result = toHaveBeenDispatchedWith(spy, detail)
+			expect(result.pass).toBe(false)
+			expect(result.message()).toBe(
+				`expected ${JSON.stringify('baz')} to deeply equal ${JSON.stringify(detail)}`
+			)
+			expect(spy).not.toHaveBeenDispatchedWith(detail)
+		})
+	})
+})

package/spec/matchers/index.spec.js

@@ -0,0 +1,15 @@
+import { describe, it, expect } from 'vitest'
+// skipcq: JS-C1003 - Importing all components for verification
+import * as validators from '../../src/matchers/index'
+
+describe('validators', () => {
+	it('should contain all exported validators', () => {
+		expect(Object.keys(validators)).toEqual([
+			'toIncludeAll',
+			'toUseHandlersFor',
+			'toOnlyTrigger',
+			'toHaveValidData',
+			'toHaveBeenDispatchedWith'
+		])
+	})
+})

package/spec/mocks/animate.spec.js

@@ -0,0 +1,24 @@
+import { describe, it, expect, vi } from 'vitest'
+import '../../src/mocks/animate'
+
+describe('animate', () => {
+	it('should mock global.Element.prototype.animate', () => {
+		// Verify the mock is attached
+		expect(typeof global.Element.prototype.animate).toBe('function')
+
+		// Create an element and call animate
+		const el = document.createElement('div')
+		const animation = el.animate([{ opacity: 0 }, { opacity: 1 }], 1000)
+
+		// Check that animate was called
+		expect(global.Element.prototype.animate).toHaveBeenCalledTimes(1)
+
+		// animation should be the mock return object
+		expect(animation).toHaveProperty('play')
+		expect(animation.play).toBeInstanceOf(Function)
+
+		// Optional: you could further exercise the mock
+		animation.play()
+		expect(animation.play).toHaveBeenCalledTimes(1)
+	})
+})

package/spec/mocks/element.spec.js

@@ -0,0 +1,136 @@
+import { describe, it, expect } from 'vitest'
+import {
+	getMockNode,
+	createNestedElement,
+	elementsWithSize,
+	mixedSizeElements
+} from '../../src/mocks/element'
+
+describe('element', () => {
+	describe('getMockNode', () => {
+		it('should return a mock node', () => {
+			const node = getMockNode(['click'])
+			expect(node).toEqual({
+				node: {
+					scrollTo: expect.any(Function),
+					querySelector: expect.any(Function),
+					querySelectorAll: expect.any(Function),
+					dispatchEvent: expect.any(Function),
+					addEventListener: expect.any(Function),
+					removeEventListener: expect.any(Function)
+				},
+				listeners: { click: 0 }
+			})
+		})
+		it('should get a mock node for querySelector', () => {
+			const { node } = getMockNode(['click'])
+
+			expect(typeof node.querySelector('div')).toEqual('object')
+			expect(Array.isArray(node.querySelectorAll('div'))).toBeTruthy()
+		})
+	})
+
+	describe('createNestedElement', () => {
+		it('should return a mock nested node', () => {
+			const item = {
+				name: 'div'
+			}
+			const node = createNestedElement(item)
+			expect(node.getAttribute('id')).toBeFalsy()
+			expect(node.getAttribute('data-path')).toBeFalsy()
+			expect(node.scrollIntoView).toEqual(expect.any(Function))
+			expect(node.children.length).toBe(0)
+		})
+
+		it('should return a mock nested node with id', () => {
+			const item = {
+				name: 'div',
+				id: 'foo'
+			}
+			const node = createNestedElement(item)
+			expect(node.getAttribute('id')).toBe('foo')
+			expect(node.getAttribute('data-path')).toBeFalsy()
+			expect(node.scrollIntoView).toEqual(expect.any(Function))
+			expect(node.children.length).toBe(0)
+		})
+
+		it('should return a mock nested node with data-path', () => {
+			const item = {
+				name: 'div',
+				dataPath: 'foo'
+			}
+			const node = createNestedElement(item)
+			expect(node.getAttribute('id')).toBeFalsy()
+			expect(node.getAttribute('data-path')).toBe('foo')
+			expect(node.scrollIntoView).toEqual(expect.any(Function))
+			expect(node.children.length).toBe(0)
+		})
+
+		it('should return a mock nested node with children', () => {
+			const item = {
+				name: 'div',
+				children: [
+					{
+						name: 'div'
+					}
+				]
+			}
+			const node = createNestedElement(item)
+			expect(node.getAttribute('id')).toBeFalsy()
+			expect(node.getAttribute('data-path')).toBeFalsy()
+			expect(node.scrollIntoView).toEqual(expect.any(Function))
+			expect(node.children.length).toBe(1)
+		})
+	})
+
+	describe('elementsWithSize', () => {
+		it('should return an array of elements with offsetHeight property', () => {
+			const result = elementsWithSize(10, 20)
+			expect(result.length).toBe(10)
+			result.forEach((element) => {
+				expect(element.offsetHeight).toBe(20)
+			})
+		})
+		it('should return an array of elements with offsetWidth property', () => {
+			const result = elementsWithSize(10, 20, 'offsetWidth')
+			expect(result.length).toBe(10)
+			result.forEach((element) => {
+				expect(element.offsetWidth).toBe(20)
+			})
+		})
+	})
+
+	describe('mixedSizeElements', () => {
+		it('should create an array of mixed size elements', () => {
+			const result = mixedSizeElements([
+				{ count: 10, size: 20 },
+				{ count: 5, size: 10 }
+			])
+			expect(result.length).toBe(15)
+			result.forEach((element, index) => {
+				if (index < 10) {
+					expect(element.offsetHeight).toBe(20)
+				} else {
+					expect(element.offsetHeight).toBe(10)
+				}
+			})
+		})
+		it('should create an array of mixed size elements with offsetWidth', () => {
+			const result = mixedSizeElements(
+				[
+					{ count: 10, size: 20 },
+					{ count: 5, size: 10 }
+				],
+				'offsetWidth'
+			)
+			expect(result.length).toBe(15)
+			result.forEach((element, index) => {
+				if (index < 10) {
+					expect(element.offsetWidth).toBe(20)
+				} else {
+					expect(element.offsetWidth).toBe(10)
+				}
+			})
+		})
+	})
+})

package/spec/mocks/index.spec.js

@@ -0,0 +1,16 @@
+import { describe, it, expect } from 'vitest'
+// skipcq: JS-C1003 - Importing all components for verification
+import * as mocks from '../../src/mocks'
+
+describe('mocks', () => {
+	it('should contain all exported mocks', () => {
+		expect(Object.keys(mocks)).toEqual([
+			'matchMediaMock',
+			'updateMedia',
+			'elementsWithSize',
+			'mixedSizeElements',
+			'getMockNode',
+			'createNestedElement'
+		])
+	})
+})