, , ...]\n\n// Example 2: Get siblings that match a selector\nconst filteredSiblings = $be.siblings(element, '.filter-class');\nconsole.log(filteredSiblings); // [, , ...]\n\n// Example 3: Include the reference element in the results\nconst siblingsWithKeyEl = $be.siblings(element, null, true);\nconsole.log(siblingsWithKeyEl); // [,
, , <.my-element>, ...]\n```\n\n\n### prev\nThe `prev` function retrieves the `previousElementSibling`, or if passing in a selector it can find the previous sibling that matches that criteria. If there is not a match available, the function will simply return the same element.\n\n```typescript\nconst lastLi = $be.findOne('li:last-child');\nconst prevLi = $be.prev(lastLi,'li'); // or just $be.prev(lastLi) to get previous sibling\n\n```\n\n### next\nThe `next` does the same as the `prev` function, but retrieves the `nextElementSibling`. It also behaves the same if there is no match or next sibling.\n\n```typescript\nconst firstLi = $be.findOne('li');\nconst $nextLi = $be.next(firstLi, 'li'); // or just $be.next(firstLi)\n```\n\n### addClass\nAdds the specified class(es) to the element.\n\n```typescript\n$be.addClass(elem: HTMLElement, cssNames: string | string[]): void;\n\n// Examples\nconst div = $be.findOne('div');\n\n// add a single class\n$be.addClass(div, 'new-class');\n\n// add multiple\n$be.addClass(div, ['new-class', 'another']);\n\n```\n\n### rmClass\nRemoves the specified class(es) from the element.\n\n```typescript\n$be.rmClass(elem: HTMLElement, cssNames: string | string[]): void\n```\n\n### tgClass\nToggles the specified class(es) on the element.\n\n```typescript\n$be.tgClass(elem: HTMLElement, cssNames: string | string[], toggle?: boolean): void\n```\n\n### hasClass\nChecks if the element has the specified class(es).\n\n```typescript\n$be.hasClass(elem: HTMLElement, cssNames: string | string[], method: 'some' | 'every' = 'some'): boolean\n```\n\n### attr\nSets or gets attributes for the element.\n\n```typescript\n$be.attr(elem: HTMLElement, attrs: Record | string): void\n```\n\n### empty\nEmpties the content of the element.\n\n```typescript\n$be.empty(elem: HTMLElement): void\n```\n\n### remove\nRemoves the element from the DOM.\n\n```typescript\n$be.remove(elem: HTMLElement): void\n```\n\n### html\nSets the inner HTML of the element.\n\n```typescript\n$be.html(elem: HTMLElement, html: string): void\n```\n\n### text\nSets the inner text of the element.\n\n```typescript\n$be.text(elem: HTMLElement, text: string): void\n```\n\n\n### htmlParse\n\nThe `htmlParse` function parses a string of HTML into an array of DOM `ChildNode` objects. It ensures that any `');\nconsole.log(nodesWithScript); // [HTMLDivElement]\n```\n\n### on\nAdds an event listener to the current elements. Namespace the events with a '.', for example `click.myClickName`.\n\n```typescript\n$be.on(\n baseEl: EventElem, \n evtName: `${Event['type']}.${string}` | string, \n fn: EventFn, \n delegateEl: string | HTMLElement[] = null, \n config: boolean | AddEventListenerOptions = false\n);\n```\n\n\n### off\nRemoves an event listener from the current elements. Pass in the same string value as the 'on' method. Namespace with '.', or `click.myClickName` as the function name.\n\n```typescript\n$be.off(evtName: string, config: boolean | AddEventListenerOptions = false);\n```\n\n### trigger\nTrigger native, synthetic and namespaced navtive events.\n\n```typescript\n$be.trigger( \n target: HTMLElement, \n evtName: string, \n delegateEl?: string | null, \n data?: any[], \n config?: boolean | AddEventListenerOptions\n);\n```\n\n### merge\nThe `merge` function is a utility for combining multiple objects into a single target object. It supports options for deep merging, excluding null or falsy values.\n\n```typescript\n$be.merge(\n configOrTarget: MergeOptions | MergeOptions[] | GenericObj, \n ...objects: GenericObj[]\n): GenericObj\n```\n#### Parameters\n1. configOrTarget\n - Type: MergeOptions | MergeOptions[] | GenericObj \n - Description: The first parameter can either be:\n - A configuration option or array of options ('deep', 'noNull', 'noFalsy').\n - The target object to merge into.\n2. ...objects\n - Type: `GenericObj[]`\n - Description: One or more objects to merge into the target object.\n\n#### Options\nThe following options can be passed as part of configuration as the first paramenter:\n\n- 'deep'/true: Enables deep merging of nested objects.\n- 'noNull': Excludes properties with null values from the merged result.\n- 'noFalsy': Excludes properties with falsy values (`null, undefined, false, 0, ''`) from the merged result.\n- Or an array of the above.\n__note:__ Falsy or `null` values will not be removed from the base target object.\n\n#### Examples\n\n##### Basic Merge\n```typescript\nconst obj1 = { a: 1, b: 2 };\nconst obj2 = { b: 3, c: 4 };\n\nconst result = $be.merge(obj1, obj2);\nconsole.log(result); // { a: 1, b: 3, c: 4 }\n```\n##### Deep Merge\n```typescript\nconst obj1 = { a: { x: 1 }, b: 2 };\nconst obj2 = { a: { y: 2 }, c: 3 };\n\nconst result = $be.merge(['deep'], obj1, obj2); \nconst result2 = $be.merge(true, obj1, obj2);// or could pass in `true` for first param\nconsole.log(result); // { a: { x: 1, y: 2 }, b: 2, c: 3 }\n```\n\n##### Exclude `null` or Falsy Values\n```typescript\nconst obj1 = { a: 1, b: 'B', c: 'C', d: \"D\" };\nconst obj2 = { b: 2, c: null, d: '' };\n\nconst result = $be.merge('noNull', obj1, obj2);\nconsole.log(result); // { a: 1, b: 2 }\n```\n\n## Utils\n\n### toType\nFixes the `typeof` which isn't actually reliable in JS. Taken verbatim from [Angus Croll](https://goo.gl/pxwQGp) and is used internally in this project.\n\n```typescript\n$be.toType(object: any);\n```\n\n#### Examples\n```typescript\n$be.toType([]) // returns 'array'\n$be.toType('') // return 'string'\n$be.toType(null) // returns 'null' (instead of 'object')\n\n// etc...\n```\n\nFew utility short-cuts used internally that are now available.\n\n### af\nShort-cut for `Array.from`.\n\n### isStr\nShort-cut function for `typeof someVar === 'string'`.\n\n### isArr\nShort-cut for `Array.isArray`.\n\n### oa\nShort-cut for `Object.assign`.\n\n## Animate/Transition Static Methods\nThis library includes a couple extra functions to help with transitions and simple animations.\n\n### useCssAnimate\nThe `useCssAnimate` function is a utility for handling CSS animations on HTML elements. It provides a way to start and end CSS animations with a specified duration and optional callback function.\n\n\n```typescript\nconst [cssAnimate, cssState] = $be.useCssAnimate(elems: HTMLElement | HTMLElement[], baseCss: string = '');\n```\nAdds the following CSS classes to and element or elements\n\n- `[custom name]-starting` or `starting` (if second param is empty) at the start of the animation\n- `[custom name]-ending` or `ending` as the animation is ending\n- `[custom name]-active` or `active` if the animation is active. Inactive state would be left without this class\n\n#### Returns\n`[(start: boolean, duration?: number, endFn?: () => void) => void, CSSActionStates]`: A tuple containing: A function to start the animation. An object representing the CSS action states. \n\n#### Example\n```typescript\nconst [cssAnimate, cssState] = $be.useCssAnimate(element, 'my-animation');\n\n// To start the animation\n$be.cssAnimate(true, 500, () => {\n console.log('Animation started');\n});\n\n// To end the animation\n$be.cssAnimate(false, 500, () => {\n console.log('Animation ended');\n});\n\nconsole.log(cssState.starting) // returns the name of the starting class\nconsole.log(cssState.ending) // returns the name of the ending class\nconsole.log(cssState.active) // returns the name of the active class\n```\n\n### useTransition\nThe `useTransition` function is a utility for managing transitions. It provides a way to handle the start and end of transitions with a specified duration.\n\n#### Returns\nFunction: A function that takes three parameters:\n`startFn ((...args: any) => void)`: A function to be called when the transition starts.\n`endFn ((...args: any) => void)`: A function to be called when the transition ends.\n`duration (number, optional)`: The duration of the transition in milliseconds. Default is 300ms.\n\n```typescript\nconst transition = $be.useTransition();\n\nconst startTransition = () => {\n console.log('Transition started');\n};\n\nconst endTransition = () => {\n console.log('Transition ended');\n};\n\n// Start the transition with a duration of 400ms\n$be.transition(startTransition, endTransition, 400);\n```\n\n#### Internal Functionality\nThe `useTransition` function maintains the state of the transition using a boolean flag (inTransition) and a timeout (tto). It also keeps track of the current end transition function (currEndTransitionFn).\n\nWhen the returned function is called:\n\n- If a transition is already in progress, it clears the current timeout and calls the current end transition function.\n- It then calls the provided startFn to start the transition.\n- It sets a timeout to call the provided endFn after the specified duration, marking the transition as complete.\n\nThis ensures that transitions are properly managed and do not overlap.\n\n### animateByFrame\nThe `animateByFrame` function is a utility for creating frame-based animations with customizable frame rates. It provides a way to run animation logic at a specified frames per second (FPS) while optimizing performance using `requestAnimationFrame`.\n\n```typescript\n$be.animateByFrame(fn: CancelAnimateFn, fps: number = 60): () => void\n```\n\n#### Parameters\n\n1. **`fn`** *(CancelAnimateFn)*: \n A callback function that contains the animation logic. This function receives a `cancelAnimation` function as its parameter, which can be called to stop the animation.\n \n2. **`fps`** *(number, optional)*: \n The target frames per second for the animation. Defaults to `60`.\n\n#### Returns\n\n**`() => void`**: A function that when called, cancels the animation by stopping the `requestAnimationFrame` loop.\n\n#### Behavior\n\nThe function uses `requestAnimationFrame` to create a smooth animation loop while throttling the frame rate to the specified FPS. This is useful when you need precise control over animation timing or want to reduce CPU usage by running animations at lower frame rates.\n\n1. The animation function (`fn`) is called immediately once.\n2. A recursive `requestAnimationFrame` loop is initiated.\n3. On each frame, the elapsed time is checked against the target frame duration.\n4. The animation function is only called when enough time has passed to match the target FPS.\n5. The loop continues until the returned cancel function is called.\n\n#### Examples\n\n```typescript\nimport $be from 'base-elem-js';\n\n// Example 1: Create a simple animation at 30 FPS\nconst element = $be.findOne('.animated-element');\nlet position = 0;\n\nconst cancelAnimation = $be.animateByFrame((cancel) => {\n position += 2;\n element.style.left = position + 'px';\n \n // Stop animation when position reaches 500\n if (position >= 500) {\n cancel();\n }\n}, 30);\n\n// Example 2: Animation with manual cancellation\nlet rotation = 0;\nconst spinElement = $be.findOne('.spinner');\n\nconst stopSpin = $be.animateByFrame((cancel) => {\n rotation += 5;\n spinElement.style.transform = `rotate(${rotation}deg)`;\n}, 60);\n\n// Stop the animation after 3 seconds\nsetTimeout(() => {\n stopSpin();\n console.log('Animation stopped');\n}, 3000);\n\n// Example 3: Counter animation at 10 FPS\nconst counter = $be.findOne('.counter');\nlet count = 0;\n\nconst stopCounter = $be.animateByFrame((cancel) => {\n count++;\n counter.textContent = count;\n \n if (count >= 100) {\n cancel();\n }\n}, 10); // Lower FPS for slower counting\n```\n\n#### Notes\n\n- The function optimizes performance by only executing the animation callback when the target frame time has elapsed.\n- FPS is clamped between 1-60 frames.\n- Lower FPS values (e.g., 10-30) can reduce CPU usage for animations that don't require high frame rates.\n- The animation function receives a `cancel` parameter that should be called when you want to stop the animation from within the callback.\n- You can also cancel the animation from outside by calling the returned function.\n- Excess time from frame calculations is carried over to prevent frame drift.\n\n\n","readmeFilename":"readme.md"}