Enhance DOM utilities: support HTMLElement inputs, detailed feedback, and safer handling

[bnidev]

Changes

• Support both CSS selector strings and HTMLElements as inputs across all DOM utilities
• Return null or empty arrays when target elements are not found, avoiding errors
• Enhance focusElement to return a detailed result object with focus attempt status and error info
• Make scrollToElementAfterRender accept HTMLElements and handle errors with callback feedback
• Add safe handling for null parents in toggleInertAround to prevent runtime errors

[Copilot]

Pull Request Overview

This PR enhances several DOM utility functions to accept both CSS selectors and direct HTMLElements, improves safety by returning null or empty arrays when targets aren’t found, and provides detailed feedback and error handling in focus and scroll helpers.

• Support for passing HTMLElements alongside selectors in all utilities
• Safe null handling: return null or [] instead of throwing
• Detailed result objects (focusElement) and callbacks (scrollToElementAfterRender) with error info

Reviewed Changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/dom/toggleInertAround.ts	Accepts HTMLElement inputs and safely handles null parent elements
src/dom/scrollToElementAfterRender.ts	Accepts selectors/HTMLElements, adds onScrollComplete callback, error handling
src/dom/isElementInViewport.ts	Accepts selectors or elements, returns false if not found
src/dom/getFocusableElements.ts	Supports selector or element containers, returns empty array if none
src/dom/getElementDimensions.ts	Accepts selector or element, returns null if not found
src/dom/focusElement.ts	Accepts selectors/HTMLElements, returns detailed focus result objects

Comments suppressed due to low confidence (3)

src/dom/scrollToElementAfterRender.ts:2

• Update the description to reference CSS selectors instead of 'ID', since the function now accepts selectors or HTMLElements (e.g., 'specified CSS selector or HTMLElement').

 * Scrolls the element with the specified ID or element reference into view after the next render frame.

src/dom/tests/scrollToElementAfterRender.test.ts:59

• Consider adding a test to verify that onScrollComplete is invoked with element: null and no error when the selector matches no element.

  it('does nothing if element is not found via selector', () => {

src/dom/getFocusableElements.ts:41

• [nitpick] Consider extracting the repeated "string vs HTMLElement" resolution logic into a shared helper to reduce duplication across DOM utilities.

  if (typeof containerOrSelector === 'string') {