Docs: Document nextTick Microtask Scheduler Utility and Execution Order Lifecycle

[nathanschmid08]

Summary & Feature Context

Avenx-JS utilizes an asynchronous microtask scheduler (lib/core/reactive/scheduler.js) to batch reactive updates and DOM flushes. The nextTick utility function allows developers to execute callbacks or await Promises immediately after the current microtask flush cycle finishes updating the DOM.

Currently, nextTick is missing from docs/src/content/docs/core-concepts/reactivity.md and the API reference guides.

Detailed Scope of Work

1. nextTick API & Usage Variants

Document all exported and instance method variants:

• Framework Export: import { nextTick } from 'avenx-js';
• Component Method: this.nextTick(callback) on AvenxComponent and AvenxPage.
• Callback Signature: nextTick(callback?: Function): Promise<void> | void
  • Callback usage: this.nextTick(() => { console.log(this.$element.offsetHeight); });
  • Promise/Async-Await usage: await this.nextTick();

2. Scheduler Microtask Architecture & Queueing

Explain the underlying scheduling pipeline in scheduler.js:

• queueJob(job): Adds update callbacks (#updateJob) to the job queue, deduplicating identical jobs.
• queueFlushCallback(cb): Adds callbacks to flushCallbacks.
• Microtask Timing: queueFlush() schedules execution via Promise.resolve().then(() => Promise.resolve().then(flushJobs)).
• Hierarchical Job Ordering: Inside flushJobs(), the job queue is sorted ascending by job id (component UID). This guarantees parent components update and patch the DOM before child components, preventing duplicate updates or orphaned child renders.
• Callback Execution Phase: After all jobs are flushed, flushCallbacks (including nextTick callbacks) are drained and executed. Recursive flushing re-drains queues if callbacks schedule further updates.

3. Practical Use Cases & Code Examples

• Provide code samples showing:
  • Reading updated DOM layout dimensions (offsetWidth, scrollHeight) immediately after mutating reactive state.
  • Writing asynchronous unit tests verifying DOM content changes post-state assignment.

Target Location in Docs Site

• Update docs/src/content/docs/core-concepts/reactivity.md and docs/src/content/docs/api-reference/component.md.