@xuda/core
O motor reativo sem dependências sobre o qual a plataforma, o compilador e as aplicações de demonstração se montam.
O @xuda/core é o motor reativo do Xuda (signals, agendador, comparação de listas com chaves, renderizador reativo,
router) como um pacote ESM sem dependências. Não lê nem escreve globais ao ser importado: nenhum func, nenhum
SESSION_OBJ, nenhum window, nenhum document.
O package.json do @xuda/core tem "private": false. É o único pacote entre os três
abordados nesta secção (juntamente com @xuda/compiler e @xuda/vite-plugin-xu, ambos private: true)
feito para ser usado como dependência fora deste repositório.
Também não é um motor separado do que a plataforma já disponibiliza: o próprio script
build:globals do pacote (esbuild src/globals.js --bundle ... --outfile ../../runtime/js/xuda_core.globals.js) é a forma como o runtime/js/xuda_core.globals.js, o bundle do renderizador reativo
da própria plataforma, é construído.
A superfície reativa
Há um só grafo de dependências, uma só árvore de proprietários, um só buffer de lotes e um só agendador por baixo de
tudo: um ref lido dentro de um effect() é acompanhado e volta a executá-lo, tal como um signal lido dentro de um
watch(). O computed aqui aceita um getter, ou um par { get, set } para um computed gravável.
O effectScope() responde a "quem descarta isto": um proprietário com nome que pode passar de mão em mão, aninhar e parar numa
só chamada, em vez de montar à mão um saco de descartadores.
Um componente instanciado através de createApp() já possui um destes: o seu <script> executa-se
dentro do âmbito separado do próprio componente, por isso um efeito escrito aí é descartado automaticamente quando
o componente é desmontado.
A primitiva de baixo nível
signal(initial) (.get(), .set(), .peek(), .notify(), .subscribe()) e
signalComputed são as células do próprio motor por baixo de ref e computed. Estão exportadas e
totalmente suportadas, não foram removidas, porque o renderizador e a ponte legada assentam nelas, e
porque o signal.notify(), que volta a executar os subscritores sem mudança de valor, não tem equivalente em ref.
O código da aplicação deve recorrer a ref e computed em vez disso; estes dois nomes estão documentados como
a camada de baixo, não como obsoletos em runtime (um aviso em signal() seria disparado por cada âmbito de linha e por cada
parâmetro de painel, milhares de vezes por ecrã, para código que está a fazer exatamente o certo nessa camada).
O ponto de entrada da aplicação
App é um módulo .xu compilado, produzido pelo @xuda/compiler ou pelo
passo de compilação do vite-plugin-xu. O createApp constrói as sete dependências injetadas de que o renderizador precisa sobre a
tabela de thunks que o setup() do módulo devolve, cria o renderizador e monta a árvore de componentes. Não
é um segundo renderizador: o caminho compilado e o caminho interpretado da plataforma partilham o render.js.
O examples/hello é a versão concreta e testada disto: createApp(App).mount('#app') sobre um
App.xu compilado com um contador, uma condicional e uma lista com chaves.
O renderizador, com injeção de dependências
O create_renderer(deps) é agnóstico quanto ao DOM. Tudo o que é ambiental chega através de um só objeto deps,
e o anfitrião honesto mais pequeno precisa exatamente de sete: document (createElement /
createTextNode / createComment), evaluate (um avaliador de expressões síncrono e acompanhado), cast_bool
(veracidade para xu-render / xu-if), resolve_rows (um resolvedor acompanhado de arrays de linhas para xu-for),
row_key (identidade estável da linha), write_field (escritas de xu-bind) e dispatch_event (tratadores
de xu-on:*). O packages/core/demo constrói exatamente isto sobre um objeto reactive({...}) simples, sem
SESSION_OBJ, sem camada de datasource e sem ponte legada por baixo.
Um nó de deps.document sem nodeType é lido como um objeto jQuery em vez de um verdadeiro nó do DOM,
o que pode aninhar cada linha dentro da anterior sem lançar erro. Um nó sem remove()
transforma uma linha descartada numa promessa rejeitada em silêncio: a lista deixa de atualizar e nada é registado.
O create_adapter na demonstração protege ambos lançando um erro ao criar o nó; passe { guard: false }
para desativar a proteção depois de perceber porque existe.
Diagnósticos e whenElement
onDiagnostic, getDiagnostics, diagnosticCount e resetDiagnostics transformam as desistências silenciosas do motor
num só canal observável, em vez de chamadas console.error dispersas, para que um adaptador de anfitrião
ou um teste se possa subscrever a elas por código. O whenElement executa uma callback quando um nó existe: pergunta
uma vez, depois volta a perguntar na fase de commit do agendador (exatamente quando o DOM assenta, antes da pintura), e
uma espera ainda por satisfazer depois de vinte renderizações assentadas reporta-se pelo nome em vez de desistir
em silêncio.
O router
createRouter, createWebHistory, createWebHashHistory, createMemoryHistory, useRouter e
useRoute vêm no mesmo pacote. A rota atual é o próprio reactive do @xuda/core, e o
histórico vem da plataforma, por isso usá-lo não acrescenta nenhuma dependência própria.
Exportações do pacote
O Node 18 ou posterior é o mínimo de motor declarado.