Docs: Document <resource> SFC Compiler Tag and Resource Class API for Asynchronous Data Fetching

[nathanschmid08]

Summary & Feature Context

Avenx-JS provides built-in reactive data fetching abstractions through the <resource> SFC compiler tag (lib/compiler/expressionParser.js) and the Resource runtime class (lib/core/reactive/Resource.js). Resources automatically track reactive dependencies using an internal AvenxWatcher, automatically re-fetch data when dependencies change, and expose a .read() method supporting Suspense and Error Boundary error propagation.

Currently, <resource> tags and the Resource class API are completely undocumented in docs/src/content/docs/.

Detailed Scope of Work

1. SFC Compiler Tag Syntax (<resource>)

Document both supported <resource> tag formats inside .component.js files:

• Block Syntax:

  <resource name="userData">
    return fetch(`/api/users/${this.state.userId}`).then(res => res.json());
  </resource>

  (Note: Single expressions automatically prepend return if omitted).
• Self-Closing Syntax:

  <resource name="userData" handler="fetchUserData" />

  (Where fetchUserData is a component action/method).

2. Runtime Resource Class API (lib/core/reactive/Resource.js)

• Constructor: new Resource(name, handlerFn, componentContext)
• Public Instance Properties:
  • name: string — Identifier of the resource.
  • status: 'idle' | 'pending' | 'resolved' | 'rejected' — Current state.
  • value: any — The resolved result (or undefined while pending/rejected).
  • error: Error | any — The rejection error (or undefined if resolved/pending).
  • promise: Promise<any> | null — Active promise instance.
• Public Instance Methods:
  • read(): Suspense-compatible getter.
    • If status === 'pending', throws this.promise (for Suspense boundary catching).
    • If status === 'rejected', throws this.error (for Error Boundary catching).
    • If status === 'resolved', returns this.value.
  • teardown(): Cleans up the underlying AvenxWatcher dependency tracker to prevent memory leaks on component unmount.

3. Reactive Re-fetching & Render Integration

• Detail how Resource wraps handlerFn inside an AvenxWatcher. When any reactive state property accessed during handlerFn execution changes, AvenxWatcher triggers this.fetch(newVal) automatically.
• Explain how fetch() sets componentContext.renderWatcher.dirty = true and calls componentContext.update() on resolution/rejection to trigger re-renders.

4. Code Examples

• Provide a full Single File Component example showing <resource> tag usage, loading state handling, error handling, and reactive state dependency re-fetching.

Target Location in Docs Site

• New section in docs/src/content/docs/core-concepts/reactivity.md or new page docs/src/content/docs/core-concepts/resources.md.