@xuda/core
Motorul reactiv fără dependențe pe care se montează platforma, compilatorul și aplicațiile demo.
@xuda/core este motorul reactiv Xuda (semnale, scheduler, diff de liste cu chei, renderer reactiv,
router) ca pachet ESM fără dependențe. Nu citește și nu scrie variabile globale la import: nici func, nici
SESSION_OBJ, nici window, nici document.
package.json al lui @xuda/core poartă "private": false. Este singurul pachet dintre cele trei
tratate în această secțiune (alături de @xuda/compiler și @xuda/vite-plugin-xu, ambele private: true)
făcut ca să fie folosit ca dependență în afara acestui repository.
Nu este nici un motor separat de cel pe care îl livrează deja platforma: scriptul propriu al pachetului,
build:globals (esbuild src/globals.js --bundle ... --outfile ../../runtime/js/xuda_core.globals.js), este cel care construiește runtime/js/xuda_core.globals.js, bundle-ul
de renderer reactiv livrat chiar de platformă.
Suprafața reactivă
Dedesubtul tuturor există un singur graf de dependențe, un singur arbore de proprietari, un singur buffer de batch și un
singur scheduler: un ref citit într-un effect() este urmărit și îl rulează din nou, la fel ca un semnal citit într-un
watch(). computed primește aici un getter sau o pereche { get, set } pentru un computed scriptibil.
effectScope() răspunde la întrebarea „cine eliberează asta": un proprietar cu nume pe care îl poți transmite, îmbrica și opri
printr-un singur apel, în loc să asamblezi manual o grămadă de funcții de eliberare.
O componentă instanțiată prin createApp() deține deja unul: <script> ei rulează
în scope-ul propriu, detașat, al componentei, deci un efect scris acolo este eliberat automat când
componenta se demontează.
Primitiva de nivel jos
signal(initial) (.get(), .set(), .peek(), .notify(), .subscribe()) și
signalComputed sunt celulele proprii ale motorului, aflate sub ref și computed. Sunt exportate și
pe deplin susținute, nu eliminate, pentru că renderer-ul și puntea legacy sunt construite pe ele și
pentru că signal.notify(), care rulează din nou abonații fără o schimbare de valoare, nu are echivalent în ref.
Codul de aplicație ar trebui să folosească ref și computed; aceste două nume sunt documentate ca
stratul de dedesubt, nu ca depreciate la runtime (un avertisment pe signal() s-ar declanșa la fiecare scope de rând și la fiecare
parametru de panou, de mii de ori pe ecran, pentru cod care face exact ce trebuie la acel nivel).
Punctul de intrare al aplicației
App este un modul .xu compilat, produs de @xuda/compiler sau de pasul de build
vite-plugin-xu. createApp construiește cele șapte dependențe injectate de care are nevoie renderer-ul, peste
tabelul de thunk-uri returnat de setup() al modulului, creează renderer-ul și montează arborele de componente. Nu
este un al doilea renderer: calea compilată și calea interpretată a platformei folosesc același render.js.
examples/hello este versiunea concretă, testată, a acestui lucru: createApp(App).mount('#app') peste un
App.xu compilat, cu un contor, o condiție și o listă cu chei.
Renderer-ul, cu dependențe injectate
create_renderer(deps) este agnostic față de DOM. Tot ce ține de mediu sosește printr-un singur obiect deps,
iar cel mai mic host onest are nevoie de exact șapte: document (createElement /
createTextNode / createComment), evaluate (un evaluator de expresii sincron, urmărit), cast_bool
(valoarea de adevăr pentru xu-render / xu-if), resolve_rows (un rezolvator urmărit de array-uri de rânduri pentru xu-for),
row_key (identitatea stabilă a rândului), write_field (scrierile xu-bind) și dispatch_event (handler-ele xu-on:*).
packages/core/demo construiește exact asta peste un simplu obiect reactive({...}), fără
SESSION_OBJ, fără strat de surse de date și fără punte legacy dedesubt.
Un nod deps.document fără nodeType este citit ca obiect jQuery, nu ca nod DOM real,
ceea ce poate îmbrica fiecare rând în cel dinainte, fără nicio eroare aruncată. Un nod fără remove()
transformă un rând eliminat într-un promise respins în tăcere: lista nu se mai actualizează și nu se loghează nimic.
create_adapter din demo apără împotriva ambelor aruncând o eroare la crearea nodului; transmite { guard: false }
ca să renunți la protecție după ce înțelegi de ce există.
Diagnostice și whenElement
onDiagnostic, getDiagnostics, diagnosticCount și resetDiagnostics transformă renunțările tăcute ale motorului
într-un singur canal observabil, în loc de apeluri console.error risipite, astfel încât un adaptor de host
sau un test să se poată abona la ele din cod. whenElement rulează un callback când există un nod: întreabă
o dată, apoi întreabă din nou la faza de commit a scheduler-ului (exact când DOM-ul se stabilizează, înainte de paint), iar
o așteptare nesatisfăcută după douăzeci de randări stabilizate se raportează singură pe nume, în loc să renunțe
în tăcere.
Router-ul
createRouter, createWebHistory, createWebHashHistory, createMemoryHistory, useRouter și
useRoute vin din același pachet. Ruta curentă este propriul reactive al lui @xuda/core, iar
istoricul vine de la platformă, deci folosirea lui nu adaugă nicio dependență proprie.
Exporturile pachetului
Node 18 sau mai nou este pragul minim declarat al motorului.