sibujs 4.5.0 → 4.6.0

package/dist/testing.d.cts

@@ -1,7 +1,31 @@
+/**
+ * Listener tracking for accessibility checks.
+ *
+ * Listeners added with `addEventListener` leave no trace in the DOM, so
+ * `checkKeyboardAccess` could not see `on: { click }` handlers attached by the
+ * framework. Once tracking is enabled, `EventTarget.prototype.addEventListener`
+ * and `removeEventListener` are wrapped to record which listeners each element
+ * currently has. Because the wrap sits below the framework, it covers tag
+ * factories, `html` templates and hand-written listeners alike, in development
+ * and production builds, without adding anything to the core bundle.
+ *
+ * The record follows DOM listener identity: an entry is `(type, callback,
+ * capture)`, so registering the same callback twice with the same capture flag
+ * is one listener, and removing it with the other flag removes nothing. Entries
+ * also disappear when a `once` listener is dispatched or its `signal` aborts.
+ *
+ * The testing entry point enables tracking when it loads. Listeners attached
+ * before that are not seen. State lives on a global symbol, so several copies of
+ * the testing utilities share one wrap.
+ */
+/** Start recording element listeners. Idempotent. */
+declare function enableListenerTracking(): void;
+
 /**
  * Accessibility testing utilities for SibuJS.
  * Provides automated a11y checks and WCAG compliance validation.
  */
+
 type A11yViolationLevel = "error" | "warning" | "info";
 interface A11yViolation {
     rule: string;
@@ -17,6 +41,13 @@ interface A11yCheckResult {
     info: A11yViolation[];
     summary: string;
 }
+interface KeyboardAccessOptions {
+    /**
+     * Recognise a container as delegating activation to its own controls, instead
+     * of marking it with `data-a11y-delegates`.
+     */
+    delegatesActivation?: (el: Element) => boolean;
+}
 /**
  * Check that all images have alt text.
  */
@@ -41,7 +72,7 @@ declare function checkColorContrast(root: Element): A11yViolation[];
  * Check that interactive elements are keyboard accessible.
  * Elements with click handlers should have tabindex, role, and key handlers.
  */
-declare function checkKeyboardAccess(root: Element): A11yViolation[];
+declare function checkKeyboardAccess(root: Element, options?: KeyboardAccessOptions): A11yViolation[];
 /**
  * Check ARIA attribute validity.
  * - role attributes use valid ARIA roles
@@ -155,6 +186,8 @@ declare function createCypressAdapter(): {
     }): {
         element: HTMLElement;
         container: HTMLElement;
+        /** Dispose the mounted component and remove the container this call created. Idempotent. */
+        unmount: () => void;
     };
     /** Generate Cypress custom commands for SibuJS */
     commands: {
@@ -292,7 +325,7 @@ declare function createTimerMock(options?: {
  */
 declare function createDOMSnapshot(element: Element): string;
 /**
- * Assert that two DOM trees are structurally equivalent.
+ * Assert two DOM elements have the same structure.
  */
 declare function assertDOMEquals(actual: Element, expected: Element): void;
 /**
@@ -324,6 +357,17 @@ declare function testComponent(component: (() => HTMLElement) | HTMLElement, opt
  * `null` if no match is found — unlike `getByText`, does not throw.
  */
 declare function queryByText(container: HTMLElement, text: string): HTMLElement | null;
+/**
+ * First descendant of `container` whose `attribute` is exactly `value`.
+ *
+ * Deliberately not `querySelector(`[attr="${value}"]`)`: interpolating an
+ * arbitrary attribute value into a selector breaks on quotes, backslashes and
+ * brackets (an invalid-selector DOMException) or matches something else. Only
+ * the attribute NAME, which is always a fixed literal here, reaches the selector.
+ */
+declare function queryByAttribute(container: ParentNode, attribute: string, value: string): HTMLElement | null;
+/** Every descendant of `container` whose `attribute` is exactly `value`. See {@link queryByAttribute}. */
+declare function queryAllByAttribute(container: ParentNode, attribute: string, value: string): HTMLElement[];
 declare function queryByTestId(container: HTMLElement, testId: string): HTMLElement | null;
 declare function queryByRole(container: HTMLElement, role: string): HTMLElement | null;
 declare function queryByLabel(container: HTMLElement, labelText: string): HTMLElement | null;
@@ -444,16 +488,23 @@ interface VisualFingerprint {
     inlineStyles: string[];
     /** Data attributes */
     dataAttributes: Record<string, string>;
+    /**
+     * Appearance-relevant computed styles per element, in tree order. Captures
+     * stylesheet, inherited and custom-property driven changes that leave the
+     * markup untouched.
+     */
+    computedStyles: string[];
     /** Computed hash of the fingerprint */
     hash: string;
 }
 /**
  * Capture a visual fingerprint of a component.
- * Includes DOM structure, attributes, text content, and inline styles.
+ * Includes DOM structure, attributes, text content, inline styles and the
+ * appearance-relevant computed styles of every element.
  */
 declare function captureFingerprint(element: Element): VisualFingerprint;
 interface FingerprintChange {
-    type: "structure" | "text" | "class" | "style" | "data" | "elements";
+    type: "structure" | "text" | "class" | "style" | "data" | "elements" | "computed";
     description: string;
 }
 /**
@@ -542,4 +593,4 @@ declare function mockStore<T extends object>(initialState: T): {
     reset: () => void;
 };
 
-export { type A11yCheckResult, type A11yViolation, type A11yViolationLevel, type FindOptions, type FingerprintChange, type MockResponse, type MockRoute, type VisualFingerprint, assertA11y, assertDOMEquals, captureFingerprint, checkA11y, checkAriaAttributes, checkColorContrast, checkFormLabels, checkHeadingHierarchy, checkImageAlt, checkKeyboardAccess, checkLandmarks, checkLinksAndButtons, checkListSemantics, checkTabOrder, compareFingerprints, createCypressAdapter, createDOMSnapshot, createHttpMock, createJestAdapter, createPlaywrightAdapter, createSnapshotMatcher, createSnapshotStore, createTimerMock, createUniversalAdapter, createVisualSuite, findByRole, findByTestId, findByText, fireEvent, matchSnapshot, mockRouter, mockStore, queryByLabel, queryByRole, queryByTestId, queryByText, render, snapshotComponent, testComponent, type, unmountAll, waitFor, waitForSignal };
+export { type A11yCheckResult, type A11yViolation, type A11yViolationLevel, type FindOptions, type FingerprintChange, type KeyboardAccessOptions, type MockResponse, type MockRoute, type VisualFingerprint, assertA11y, assertDOMEquals, captureFingerprint, checkA11y, checkAriaAttributes, checkColorContrast, checkFormLabels, checkHeadingHierarchy, checkImageAlt, checkKeyboardAccess, checkLandmarks, checkLinksAndButtons, checkListSemantics, checkTabOrder, compareFingerprints, createCypressAdapter, createDOMSnapshot, createHttpMock, createJestAdapter, createPlaywrightAdapter, createSnapshotMatcher, createSnapshotStore, createTimerMock, createUniversalAdapter, createVisualSuite, enableListenerTracking, findByRole, findByTestId, findByText, fireEvent, matchSnapshot, mockRouter, mockStore, queryAllByAttribute, queryByAttribute, queryByLabel, queryByRole, queryByTestId, queryByText, render, snapshotComponent, testComponent, type, unmountAll, waitFor, waitForSignal };

package/dist/testing.d.ts

@@ -1,7 +1,31 @@
+/**
+ * Listener tracking for accessibility checks.
+ *
+ * Listeners added with `addEventListener` leave no trace in the DOM, so
+ * `checkKeyboardAccess` could not see `on: { click }` handlers attached by the
+ * framework. Once tracking is enabled, `EventTarget.prototype.addEventListener`
+ * and `removeEventListener` are wrapped to record which listeners each element
+ * currently has. Because the wrap sits below the framework, it covers tag
+ * factories, `html` templates and hand-written listeners alike, in development
+ * and production builds, without adding anything to the core bundle.
+ *
+ * The record follows DOM listener identity: an entry is `(type, callback,
+ * capture)`, so registering the same callback twice with the same capture flag
+ * is one listener, and removing it with the other flag removes nothing. Entries
+ * also disappear when a `once` listener is dispatched or its `signal` aborts.
+ *
+ * The testing entry point enables tracking when it loads. Listeners attached
+ * before that are not seen. State lives on a global symbol, so several copies of
+ * the testing utilities share one wrap.
+ */
+/** Start recording element listeners. Idempotent. */
+declare function enableListenerTracking(): void;
+
 /**
  * Accessibility testing utilities for SibuJS.
  * Provides automated a11y checks and WCAG compliance validation.
  */
+
 type A11yViolationLevel = "error" | "warning" | "info";
 interface A11yViolation {
     rule: string;
@@ -17,6 +41,13 @@ interface A11yCheckResult {
     info: A11yViolation[];
     summary: string;
 }
+interface KeyboardAccessOptions {
+    /**
+     * Recognise a container as delegating activation to its own controls, instead
+     * of marking it with `data-a11y-delegates`.
+     */
+    delegatesActivation?: (el: Element) => boolean;
+}
 /**
  * Check that all images have alt text.
  */
@@ -41,7 +72,7 @@ declare function checkColorContrast(root: Element): A11yViolation[];
  * Check that interactive elements are keyboard accessible.
  * Elements with click handlers should have tabindex, role, and key handlers.
  */
-declare function checkKeyboardAccess(root: Element): A11yViolation[];
+declare function checkKeyboardAccess(root: Element, options?: KeyboardAccessOptions): A11yViolation[];
 /**
  * Check ARIA attribute validity.
  * - role attributes use valid ARIA roles
@@ -155,6 +186,8 @@ declare function createCypressAdapter(): {
     }): {
         element: HTMLElement;
         container: HTMLElement;
+        /** Dispose the mounted component and remove the container this call created. Idempotent. */
+        unmount: () => void;
     };
     /** Generate Cypress custom commands for SibuJS */
     commands: {
@@ -292,7 +325,7 @@ declare function createTimerMock(options?: {
  */
 declare function createDOMSnapshot(element: Element): string;
 /**
- * Assert that two DOM trees are structurally equivalent.
+ * Assert two DOM elements have the same structure.
  */
 declare function assertDOMEquals(actual: Element, expected: Element): void;
 /**
@@ -324,6 +357,17 @@ declare function testComponent(component: (() => HTMLElement) | HTMLElement, opt
  * `null` if no match is found — unlike `getByText`, does not throw.
  */
 declare function queryByText(container: HTMLElement, text: string): HTMLElement | null;
+/**
+ * First descendant of `container` whose `attribute` is exactly `value`.
+ *
+ * Deliberately not `querySelector(`[attr="${value}"]`)`: interpolating an
+ * arbitrary attribute value into a selector breaks on quotes, backslashes and
+ * brackets (an invalid-selector DOMException) or matches something else. Only
+ * the attribute NAME, which is always a fixed literal here, reaches the selector.
+ */
+declare function queryByAttribute(container: ParentNode, attribute: string, value: string): HTMLElement | null;
+/** Every descendant of `container` whose `attribute` is exactly `value`. See {@link queryByAttribute}. */
+declare function queryAllByAttribute(container: ParentNode, attribute: string, value: string): HTMLElement[];
 declare function queryByTestId(container: HTMLElement, testId: string): HTMLElement | null;
 declare function queryByRole(container: HTMLElement, role: string): HTMLElement | null;
 declare function queryByLabel(container: HTMLElement, labelText: string): HTMLElement | null;
@@ -444,16 +488,23 @@ interface VisualFingerprint {
     inlineStyles: string[];
     /** Data attributes */
     dataAttributes: Record<string, string>;
+    /**
+     * Appearance-relevant computed styles per element, in tree order. Captures
+     * stylesheet, inherited and custom-property driven changes that leave the
+     * markup untouched.
+     */
+    computedStyles: string[];
     /** Computed hash of the fingerprint */
     hash: string;
 }
 /**
  * Capture a visual fingerprint of a component.
- * Includes DOM structure, attributes, text content, and inline styles.
+ * Includes DOM structure, attributes, text content, inline styles and the
+ * appearance-relevant computed styles of every element.
  */
 declare function captureFingerprint(element: Element): VisualFingerprint;
 interface FingerprintChange {
-    type: "structure" | "text" | "class" | "style" | "data" | "elements";
+    type: "structure" | "text" | "class" | "style" | "data" | "elements" | "computed";
     description: string;
 }
 /**
@@ -542,4 +593,4 @@ declare function mockStore<T extends object>(initialState: T): {
     reset: () => void;
 };
 
-export { type A11yCheckResult, type A11yViolation, type A11yViolationLevel, type FindOptions, type FingerprintChange, type MockResponse, type MockRoute, type VisualFingerprint, assertA11y, assertDOMEquals, captureFingerprint, checkA11y, checkAriaAttributes, checkColorContrast, checkFormLabels, checkHeadingHierarchy, checkImageAlt, checkKeyboardAccess, checkLandmarks, checkLinksAndButtons, checkListSemantics, checkTabOrder, compareFingerprints, createCypressAdapter, createDOMSnapshot, createHttpMock, createJestAdapter, createPlaywrightAdapter, createSnapshotMatcher, createSnapshotStore, createTimerMock, createUniversalAdapter, createVisualSuite, findByRole, findByTestId, findByText, fireEvent, matchSnapshot, mockRouter, mockStore, queryByLabel, queryByRole, queryByTestId, queryByText, render, snapshotComponent, testComponent, type, unmountAll, waitFor, waitForSignal };
+export { type A11yCheckResult, type A11yViolation, type A11yViolationLevel, type FindOptions, type FingerprintChange, type KeyboardAccessOptions, type MockResponse, type MockRoute, type VisualFingerprint, assertA11y, assertDOMEquals, captureFingerprint, checkA11y, checkAriaAttributes, checkColorContrast, checkFormLabels, checkHeadingHierarchy, checkImageAlt, checkKeyboardAccess, checkLandmarks, checkLinksAndButtons, checkListSemantics, checkTabOrder, compareFingerprints, createCypressAdapter, createDOMSnapshot, createHttpMock, createJestAdapter, createPlaywrightAdapter, createSnapshotMatcher, createSnapshotStore, createTimerMock, createUniversalAdapter, createVisualSuite, enableListenerTracking, findByRole, findByTestId, findByText, fireEvent, matchSnapshot, mockRouter, mockStore, queryAllByAttribute, queryByAttribute, queryByLabel, queryByRole, queryByTestId, queryByText, render, snapshotComponent, testComponent, type, unmountAll, waitFor, waitForSignal };