anu-verzum 1.21.6 → 1.22.0

package/README.md

@@ -4,7 +4,7 @@
 
 <h3>@author: <strong>Anubis-programmer</strong></h3>
 <h3>@license: <strong>MIT</strong></h3>
-<h3>@version: <strong>1.21.6</strong></h3>
+<h3>@version: <strong>1.22.0</strong></h3>
 
 <br>
 
@@ -17,6 +17,7 @@ A lightweight React-inspired UI library for building component-based web applica
 - Client-side routing over the History API
 - Context API, i18n (Intl), feature flags, and built-in event analytics (Anulytics)
 - Ships with TypeScript declaration files — no `@types` package needed
+- Built-in testing companion — **Anu Testing Library (ATL)** shipped as `anu-verzum/testing`
 
 <br>
 <hr>
@@ -143,6 +144,18 @@ Create `tsconfig.json`:
 | `moduleResolution` | `"bundler"` | Correct setting for Webpack/Babel projects |
 | `target` | `"ES2018"` | Because Babel handles compilation (`noEmit: true`), `target` only controls which TypeScript built-in type definitions are available — it does not affect emitted code. ES2018 is the minimum required to include `Promise.prototype.finally` on values returned by `Anu.ServerAPI` methods. |
 
+#### Typing `process.env`
+
+TypeScript does not know about `process` in a browser project by default — it is a Node.js global. If you reference `process.env.SOME_VAR` in your source (for example, to pass a value injected by webpack `DefinePlugin`), add a declaration file so the type checker can resolve it without pulling in the full Node.js type surface:
+
+Create `src/env.d.ts`:
+
+```typescript
+declare const process: { env: Record<string, string | undefined> };
+```
+
+This is enough for any `process.env.*` access. If your project already depends on `@types/node` for other reasons, you can skip the declaration file and add `"types": ["node"]` to `compilerOptions` in `tsconfig.json` instead — but prefer the declaration file for a pure browser project to avoid Node-specific type collisions (e.g. `setTimeout` return type, `Buffer`, etc.).
+
 Compilation and type checking are intentionally separate — `npm start` and `npm run build` succeed regardless of type errors. Run `npx tsc --noEmit` during development to catch type issues without blocking the build.
 
 #### Exported types
@@ -176,13 +189,40 @@ The following types are exported from `anu-verzum` for use in consumer projects:
 #### Library development scripts
 
 ```bash
-npm run clean       # Delete dist/ entirely
-npm run build       # Clean, compile TypeScript sources to dist/, and emit .d.ts files
-npm run typecheck   # Type-check without emitting any output
-npm run lint        # Run ESLint on all source files
-npm run format      # Format all source files with Prettier
+npm run clean           # Delete dist/ entirely
+npm run build           # Clean, compile TypeScript sources to dist/, and emit .d.ts files
+npm run typecheck       # Type-check without emitting any output
+npm run lint            # Run ESLint on all source files
+npm run format          # Format all source files with Prettier
+npm test                # Run the Anu Testing Library test suite with Jest
+npm run test:watch      # Run Jest in interactive watch mode
+npm run test:coverage   # Run Jest and generate a coverage report
+```
+
+<br>
+<hr>
+
+<h2 id="testing">Testing</h2>
+
+ANUVerzum ships a built-in testing library — **Anu Testing Library (ATL)** — importable as `anu-verzum/testing`. It mirrors the philosophy of Testing Library: query the DOM the way a user would (by role, text, label), fire events, and assert on real output — no component internals, no custom matchers.
+
+```typescript
+import Anu from 'anu-verzum';
+import { render, fireEvent } from 'anu-verzum/testing';
+
+const { getByText, getByRole } = render(<Counter />);
+fireEvent.click(getByRole('button'));
+expect(getByText('Count: 1')).toBeDefined();
 ```
 
+If TypeScript reports that `describe`, `test`, or `expect` are not found, your `tsconfig.json` likely has an explicit `"types"` list. Add `"jest"` to it — and `"node"` if tests reference `process.env`:
+
+```json
+{ "compilerOptions": { "types": ["node", "jest"] } }
+```
+
+See **[USERS_MANUAL.md — Testing](./documentation/USERS_MANUAL.md#testing)** for the full API reference and usage guide.
+
 <br>
 <hr>
 

package/dist/core/components/AnulyticsProvider.d.ts

@@ -29,3 +29,6 @@ declare class AnulyticsProvider extends Component<AnulyticsProviderProps> {
     render(): AnuElement | AnuElement[] | null;
 }
 export default AnulyticsProvider;
+export declare const __testing: {
+    reset(): void;
+};

package/dist/core/components/AnulyticsProvider.js

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.trackStateChange = exports.trackRouteChange = exports.trackEvent = exports.default = void 0;
+exports.trackStateChange = exports.trackRouteChange = exports.trackEvent = exports.default = exports.__testing = void 0;
 var _Component = require("./Component");
 var _serverApi = _interopRequireDefault(require("../../server-api/server-api"));
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
@@ -15,30 +15,42 @@ const EventTypes = {
   PAGE_LEAVE: 'pageLeave'
 };
 const AnulyticsState = (() => {
-  const initStart = new Date().getTime();
+  const startDate = new Date().getTime();
   let _anulyticsInstanceExist = false;
-  const setAnulyticsInstanceExist = instanceExist => {
-    _anulyticsInstanceExist = instanceExist;
-  };
-  const getAnulyticsInstanceExist = () => _anulyticsInstanceExist;
-  const _anulytics = {
-    startDate: initStart,
-    events: [{
-      [EventTypes.INITIALIZATION]: {
-        eventType: window.location.pathname,
-        timestamp: initStart,
-        properties: {}
-      }
-    }],
-    user: {}
+  let _analyticsUrl = '';
+  let _onSuccess = () => {};
+  let _onFail = () => {};
+  let _user = {};
+  const send = (event, extra) => {
+    _serverApi.default.post(_analyticsUrl, {
+      startDate,
+      user: _user,
+      ...event,
+      ...(extra || {})
+    }).then(({
+      response
+    }) => _onSuccess(response)).catch(({
+      status
+    }) => _onFail(status));
   };
   return {
-    getAnulyticsInstanceExist,
-    setAnulyticsInstanceExist,
-    addEvent: (key, val) => {
-      _anulytics.events.push({
+    getAnulyticsInstanceExist: () => _anulyticsInstanceExist,
+    setAnulyticsInstanceExist: instanceExist => {
+      _anulyticsInstanceExist = instanceExist;
+    },
+    setConfig: (url, onSuccess, onFail) => {
+      _analyticsUrl = url;
+      _onSuccess = onSuccess;
+      _onFail = onFail;
+    },
+    setUser: user => {
+      _user = user || {};
+    },
+    getStartDate: () => startDate,
+    sendEvent: (key, val, extra) => {
+      send({
         [key]: val
-      });
+      }, extra);
     },
     trackEvent: ({
       type,
@@ -55,7 +67,7 @@ const AnulyticsState = (() => {
       const scrollTop = document.body.scrollTop || document.documentElement.scrollTop;
       const scrollLeft = document.body.scrollLeft || document.documentElement.scrollLeft;
       const props = typeof rawProps === 'object' && !Array.isArray(rawProps) && rawProps !== null ? rawProps : null;
-      const event = {
+      send({
         [EventTypes.USER_ACTION]: {
           eventType: type,
           timestamp: new Date().getTime(),
@@ -73,11 +85,10 @@ const AnulyticsState = (() => {
             props
           }
         }
-      };
-      _anulytics.events.push(event);
+      });
     },
     trackStateChange: (prevState, action, nextState) => {
-      const event = {
+      send({
         [EventTypes.STATE_CHANGE]: {
           eventType: action['type'],
           timestamp: new Date().getTime(),
@@ -88,13 +99,8 @@ const AnulyticsState = (() => {
             nextState
           }
         }
-      };
-      _anulytics.events.push(event);
-    },
-    setUser: user => {
-      _anulytics.user = user || {};
-    },
-    getAnulyticsData: () => _anulytics
+      });
+    }
   };
 })();
 const _isBot = !!(window.phantom || window._phantom || window.__nightmare || window.navigator.webdriver || window.Cypress);
@@ -122,26 +128,34 @@ exports.trackStateChange = trackStateChange;
 const trackRouteChange = path => {
   if (AnulyticsState.getAnulyticsInstanceExist()) {
     const url = path || window.location.pathname;
-    const event = {
+    AnulyticsState.sendEvent(EventTypes.NAVIGATION, {
       eventType: url,
       timestamp: new Date().getTime(),
       properties: {}
-    };
-    AnulyticsState.addEvent(EventTypes.NAVIGATION, event);
+    });
   }
 };
 exports.trackRouteChange = trackRouteChange;
 class AnulyticsProvider extends _Component.Component {
   constructor(props) {
     super(props);
-    AnulyticsState.setAnulyticsInstanceExist(true);
     this.handleVisibilityChange = this.handleVisibilityChange.bind(this);
   }
   componentDidMount() {
     const {
-      userData
+      analyticsUrl,
+      userData,
+      onSuccess,
+      onFail
     } = this.props;
+    AnulyticsState.setConfig(analyticsUrl, onSuccess, onFail);
     AnulyticsState.setUser(userData || null);
+    AnulyticsState.setAnulyticsInstanceExist(true);
+    AnulyticsState.sendEvent(EventTypes.INITIALIZATION, {
+      eventType: window.location.pathname,
+      timestamp: AnulyticsState.getStartDate(),
+      properties: {}
+    });
     document.addEventListener('visibilitychange', this.handleVisibilityChange, {
       passive: true
     });
@@ -151,23 +165,12 @@ class AnulyticsProvider extends _Component.Component {
     AnulyticsState.setAnulyticsInstanceExist(false);
   }
   handleVisibilityChange() {
-    const {
-      analyticsUrl,
-      onSuccess,
-      onFail
-    } = this.props;
     if (_isBot) {
       return;
     }
     if (document.visibilityState === 'hidden') {
       const url = window.location.pathname;
-      const event = {
-        eventType: url,
-        timestamp: new Date().getTime(),
-        properties: {}
-      };
       let ua;
-      AnulyticsState.addEvent(EventTypes.PAGE_LEAVE, event);
       if (window.navigator.userAgentData) {
         const {
           brands,
@@ -186,21 +189,18 @@ class AnulyticsProvider extends _Component.Component {
           platform: ''
         };
       }
-      const data = {
-        ...AnulyticsState.getAnulyticsData(),
-        endDate: new Date().getTime(),
+      AnulyticsState.sendEvent(EventTypes.PAGE_LEAVE, {
+        eventType: url,
+        timestamp: new Date().getTime(),
+        properties: {}
+      }, {
         system: {
           referrer: document.referrer || null,
           innerWidth: window.innerWidth,
           isMobileAppInstalled: _isInstalled(),
           userAgentData: ua
         }
-      };
-      _serverApi.default.post(analyticsUrl, data).then(({
-        response
-      }) => onSuccess(response)).catch(({
-        status
-      }) => onFail(status));
+      });
     } else {
       this.setState();
     }
@@ -218,4 +218,12 @@ class AnulyticsProvider extends _Component.Component {
     }
   }
 }
-var _default = exports.default = AnulyticsProvider;
+var _default = exports.default = AnulyticsProvider;
+const __testing = exports.__testing = {
+  reset() {
+    if (process.env.NODE_ENV !== 'test') {
+      return;
+    }
+    AnulyticsState.setAnulyticsInstanceExist(false);
+  }
+};

package/dist/core/components/History.d.ts

@@ -47,3 +47,6 @@ declare const History: {
     getAllUrlParamNames: () => string[];
 };
 export default History;
+export declare const __testing: {
+    reset(): void;
+};

package/dist/core/components/History.js

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.goTo = exports.default = void 0;
+exports.goTo = exports.default = exports.__testing = void 0;
 var _elements = require("../elements");
 var _Component = require("./Component");
 var _AnulyticsProvider = require("./AnulyticsProvider");
@@ -210,4 +210,12 @@ const History = {
   getUrlParams,
   getAllUrlParamNames
 };
-var _default = exports.default = History;
+var _default = exports.default = History;
+const __testing = exports.__testing = {
+  reset() {
+    if (process.env.NODE_ENV !== 'test') {
+      return;
+    }
+    instances.length = 0;
+  }
+};

package/dist/core/components/Intl.d.ts

@@ -21,3 +21,6 @@ declare const Intl: {
     Provider: ({ locale, messages, defaultLocale, children }: IntlProviderProps) => AnuElement | null;
 };
 export default Intl;
+export declare const __testing: {
+    reset(): void;
+};

package/dist/core/components/Intl.js

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.default = void 0;
+exports.default = exports.__testing = void 0;
 var _elements = require("../elements");
 var _Context = require("./Context");
 const _Intl = (0, _Context.createContext)({});
@@ -168,4 +168,15 @@ const Intl = {
   formatMessage,
   Provider: IntlProvider
 };
-var _default = exports.default = Intl;
+var _default = exports.default = Intl;
+const __testing = exports.__testing = {
+  reset() {
+    if (process.env.NODE_ENV !== 'test') {
+      return;
+    }
+    __messagesContext = {
+      locale: undefined,
+      messages: {}
+    };
+  }
+};

package/dist/core/elements.d.ts

@@ -12,7 +12,7 @@ export type Ref<T> = {
 };
 export type FunctionComponent<P extends Props = Props> = (props: P) => AnuElement<any, any> | AnuElement<any, any>[] | string | number | boolean | null | undefined;
 export type ComponentConstructor<P extends Props = Props> = new (props: P, context?: Record<string, any>) => any;
-export type ElementType = string | FunctionComponent | ComponentConstructor;
+export type ElementType = string | FunctionComponent<any> | ComponentConstructor<any>;
 export type AnuElement<P = Props, T extends ElementType = ElementType> = {
     type: T;
     props: P;

package/dist/core/reconciler.d.ts

@@ -2,3 +2,8 @@ import { AnuElement, Ref } from './elements';
 export declare const createRef: <T = any>() => Ref<T>;
 export declare const scheduleUpdate: (instance: any, partialState: Record<string, any>, partialStateCallback?: (prevState: any, prevProps: any) => any) => void;
 export declare const render: (elements: AnuElement | AnuElement[], containerDom: Element) => void;
+export declare const unmountComponentAtNode: (containerDom: Element) => void;
+export declare const __testing: {
+    flushSync(): void;
+    resetGlobals(): void;
+};

package/dist/core/reconciler.js

@@ -3,7 +3,7 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.scheduleUpdate = exports.render = exports.createRef = void 0;
+exports.unmountComponentAtNode = exports.scheduleUpdate = exports.render = exports.createRef = exports.__testing = void 0;
 var _domUtils = require("./domUtils");
 const HOST_COMPONENT = 'host';
 const CLASS_COMPONENT = 'class';
@@ -446,4 +446,43 @@ const render = (elements, containerDom) => {
   });
   requestIdleCallback(performWork);
 };
-exports.render = render;
+exports.render = render;
+const unmountComponentAtNode = containerDom => {
+  if (!containerDom._rootContainerFiber) {
+    return;
+  }
+  updateQueue.push({
+    from: HOST_ROOT,
+    dom: containerDom,
+    newProps: {
+      children: []
+    }
+  });
+  requestIdleCallback(performWork);
+};
+exports.unmountComponentAtNode = unmountComponentAtNode;
+const __testing = exports.__testing = {
+  flushSync() {
+    if (process.env.NODE_ENV !== 'test') {
+      return;
+    }
+    const syncDeadline = {
+      didTimeout: false,
+      timeRemaining: () => 999
+    };
+    while (updateQueue.length > 0 || nextUnitOfWork != null) {
+      workLoop(syncDeadline);
+    }
+    nextUnitOfWork = null;
+    pendingCommit = null;
+  },
+  resetGlobals() {
+    if (process.env.NODE_ENV !== 'test') {
+      return;
+    }
+    updateQueue.length = 0;
+    componentLifecyclesQueue.length = 0;
+    nextUnitOfWork = null;
+    pendingCommit = null;
+  }
+};

package/dist/testing/__tests__/smoke.test.d.ts

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

package/dist/testing/__tests__/smoke.test.js

@@ -0,0 +1,180 @@
+"use strict";
+
+var _index = _interopRequireWildcard(require("../../index"));
+var _index2 = require("../index");
+function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
+class Counter extends _index.Component {
+  state = {
+    count: 0
+  };
+  render() {
+    return _index.default.createElement('div', {}, _index.default.createElement('p', {}, `Count: ${this.state.count}`), _index.default.createElement('button', {
+      onClick: () => this.setState({
+        count: this.state.count + 1
+      })
+    }, 'Increment'));
+  }
+}
+const Greeting = ({
+  name
+}) => _index.default.createElement('h1', {}, `Hello, ${name}!`);
+describe('render', () => {
+  test('renders a function component', () => {
+    const {
+      getByText
+    } = (0, _index2.render)(_index.default.createElement(Greeting, {
+      name: 'World'
+    }));
+    expect(getByText('Hello, World!')).toBeDefined();
+  });
+  test('renders a class component', () => {
+    const {
+      getByText
+    } = (0, _index2.render)(_index.default.createElement(Counter, {}));
+    expect(getByText('Count: 0')).toBeDefined();
+  });
+  test('returns a container attached to document.body', () => {
+    const {
+      container
+    } = (0, _index2.render)(_index.default.createElement(Greeting, {
+      name: 'test'
+    }));
+    expect(document.body.contains(container)).toBe(true);
+  });
+});
+describe('queries', () => {
+  test('getByRole finds button', () => {
+    const {
+      getByRole
+    } = (0, _index2.render)(_index.default.createElement(Counter, {}));
+    const btn = getByRole('button');
+    expect(btn).toBeDefined();
+    expect(btn.textContent).toBe('Increment');
+  });
+  test('getByRole with name option', () => {
+    const {
+      getByRole
+    } = (0, _index2.render)(_index.default.createElement(Counter, {}));
+    const btn = getByRole('button', {
+      name: 'Increment'
+    });
+    expect(btn).toBeDefined();
+  });
+  test('queryByText returns null when not found', () => {
+    const {
+      queryByText
+    } = (0, _index2.render)(_index.default.createElement(Greeting, {
+      name: 'test'
+    }));
+    expect(queryByText('Not here')).toBeNull();
+  });
+  test('getByText throws when not found', () => {
+    const {
+      getByText
+    } = (0, _index2.render)(_index.default.createElement(Greeting, {
+      name: 'test'
+    }));
+    expect(() => getByText('Not here')).toThrow();
+  });
+  test('findByText resolves asynchronously', async () => {
+    const {
+      findByText
+    } = (0, _index2.render)(_index.default.createElement(Greeting, {
+      name: 'World'
+    }));
+    const el = await findByText('Hello, World!');
+    expect(el).toBeDefined();
+  });
+});
+describe('fireEvent', () => {
+  test('click triggers onClick and re-renders', () => {
+    const {
+      getByText,
+      getByRole
+    } = (0, _index2.render)(_index.default.createElement(Counter, {}));
+    expect(getByText('Count: 0')).toBeDefined();
+    _index2.fireEvent.click(getByRole('button'));
+    expect(getByText('Count: 1')).toBeDefined();
+  });
+  test('multiple clicks accumulate', () => {
+    const {
+      getByText,
+      getByRole
+    } = (0, _index2.render)(_index.default.createElement(Counter, {}));
+    _index2.fireEvent.click(getByRole('button'));
+    _index2.fireEvent.click(getByRole('button'));
+    _index2.fireEvent.click(getByRole('button'));
+    expect(getByText('Count: 3')).toBeDefined();
+  });
+});
+describe('userEvent', () => {
+  test('click fires full mouse event sequence', () => {
+    const {
+      getByText,
+      getByRole
+    } = (0, _index2.render)(_index.default.createElement(Counter, {}));
+    _index2.userEvent.click(getByRole('button'));
+    expect(getByText('Count: 1')).toBeDefined();
+  });
+});
+describe('rerender', () => {
+  test('updates the component with new props', () => {
+    const {
+      getByText,
+      rerender
+    } = (0, _index2.render)(_index.default.createElement(Greeting, {
+      name: 'Alice'
+    }));
+    expect(getByText('Hello, Alice!')).toBeDefined();
+    rerender(_index.default.createElement(Greeting, {
+      name: 'Bob'
+    }));
+    expect(getByText('Hello, Bob!')).toBeDefined();
+  });
+});
+describe('waitFor', () => {
+  test('polls until assertion passes', async () => {
+    const {
+      getByText
+    } = (0, _index2.render)(_index.default.createElement(Greeting, {
+      name: 'World'
+    }));
+    await (0, _index2.waitFor)(() => {
+      expect(getByText('Hello, World!')).toBeDefined();
+    });
+  });
+  test('rejects when assertion never passes', async () => {
+    const {
+      queryByText
+    } = (0, _index2.render)(_index.default.createElement(Greeting, {
+      name: 'World'
+    }));
+    await expect((0, _index2.waitFor)(() => {
+      expect(queryByText('MISSING')).not.toBeNull();
+    }, {
+      timeout: 100,
+      interval: 20
+    })).rejects.toThrow();
+  });
+});
+describe('act', () => {
+  test('flushes state updates synchronously', () => {
+    const {
+      getByText,
+      getByRole
+    } = (0, _index2.render)(_index.default.createElement(Counter, {}));
+    (0, _index2.act)(() => {
+      _index2.fireEvent.click(getByRole('button'));
+    });
+    expect(getByText('Count: 1')).toBeDefined();
+  });
+  test('wraps async callbacks', async () => {
+    const {
+      getByText
+    } = (0, _index2.render)(_index.default.createElement(Counter, {}));
+    await (0, _index2.act)(async () => {
+      await Promise.resolve();
+    });
+    expect(getByText('Count: 0')).toBeDefined();
+  });
+});

package/dist/testing/act.d.ts

@@ -0,0 +1,4 @@
+export declare const installSyncScheduler: () => void;
+export declare const uninstallSyncScheduler: () => void;
+export declare const flushEffects: () => void;
+export declare const act: (callback: () => void | Promise<void>) => void | Promise<void>;

package/dist/testing/act.js

@@ -0,0 +1,42 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.uninstallSyncScheduler = exports.installSyncScheduler = exports.flushEffects = exports.act = void 0;
+var _reconciler = require("../core/reconciler");
+const FAKE_DEADLINE = {
+  didTimeout: false,
+  timeRemaining: () => 999
+};
+let _installed = false;
+const installSyncScheduler = () => {
+  if (_installed) {
+    return;
+  }
+  _installed = true;
+  window.requestIdleCallback = cb => {
+    cb(FAKE_DEADLINE);
+    return 0;
+  };
+  window.cancelIdleCallback = () => {};
+};
+exports.installSyncScheduler = installSyncScheduler;
+const uninstallSyncScheduler = () => {
+  _installed = false;
+};
+exports.uninstallSyncScheduler = uninstallSyncScheduler;
+const flushEffects = () => {
+  _reconciler.__testing.flushSync();
+};
+exports.flushEffects = flushEffects;
+const act = callback => {
+  const result = callback();
+  if (result && typeof result.then === 'function') {
+    return result.then(() => {
+      _reconciler.__testing.flushSync();
+    });
+  }
+  _reconciler.__testing.flushSync();
+};
+exports.act = act;

package/dist/testing/cleanup.d.ts

@@ -0,0 +1,3 @@
+export declare const registerContainer: (container: Element) => void;
+export declare const cleanup: () => void;
+export declare const setupAutoCleanup: () => void;