IA · A2UI
Decisões
As 12 decisões de projeto do renderer A2UI da ui-nova. Todas estão aplicadas no catálogo, nos exemplos e no pacote @vueui-nova/a2ui 1.0.0. A coluna “Onde está aplicada” mostra onde conferir cada uma.
IA · A2UI
As 12 decisões de projeto do renderer A2UI da ui-nova. Todas estão aplicadas no catálogo, nos exemplos e no pacote @vueui-nova/a2ui 1.0.0. A coluna “Onde está aplicada” mostra onde conferir cada uma.
| # | Decisão | Escolha adotada | Onde está aplicada | Opções consideradas |
|---|---|---|---|---|
D1aplicado | Nome e local do pacote | Pacote separado @vueui-nova/a2ui, no repositório ui-nova-a2ui. | ui-nova-a2ui/packages/a2ui 1.0.0: build ES + CJS, .d.ts, CSS, catálogo, instruções e galeria incluídos. Esta doc renderiza tudo com o pacote. | @vueui-nova/a2ui (separado) · vueui-nova-kit/a2ui (subpath) |
D2aplicado | Núcleo | Adapter Vue sobre @a2ui/web_core. | O MessageProcessor, o Catalog, o DataContext e o SurfaceModel do @a2ui/web_core 0.15 cuidam de validação, surfaces, data model, @path, @call, checks e actions; o Vue lê um espelho reativo. O runtime aceita as duas grafias de checks e acessibilidade (@checks/checks, @accessibility/accessibility). Ids seguem UAX #31. A suíte de conformance oficial da v1.0 roda no pacote. | Adapter sobre @a2ui/web_core · núcleo próprio |
D3aplicado | catalogId / $id | catalogId e $id em https://, servidos pela doc em /a2ui/catalog/v1.json. | Domínio https://uinova.walderpinheiro.com.br, configurável com A2UI_BASE_URL=https://seu-dominio no gerador do catálogo e no build da doc. O renderer também aceita o URN anterior. | urn:vueui-nova-kit:a2ui:catalog:v1 (anterior) · https://<domínio-da-doc>/a2ui/catalog/v1.json |
D4aplicado | Compatibilidade com o catálogo básico | Camada de compatibilidade opcional com o catálogo básico. | Opção compat do runtime: o catálogo básico do web_core valida a surface e o renderer traduz TextField, CheckBox, ChoicePicker, MultipleChoice, DateTimeInput, Tabs, Modal e Icon para a ui-nova. Ligada no playground. | Aceitar também catalogId básico mapeando para V* · só o catálogo ui-nova |
D5aplicado | Transportes | Helpers finos de transporte; A2A e AG-UI ficam como receita do host. | parseJsonl, processStream (JSONL/SSE em pedaços) e connectWebSocket. A mensagem manual do playground aceita JSONL. | Nenhum (host integra) · JSONL/SSE + WebSocket · A2A/AG-UI |
D6aplicado | Lista do catálogo v1 | Catálogo v1 único e completo. | 73 componentes: 67 da lib e 6 primitivos. Componentes com dois valores ligados (TimeRange, TreeNavigation, Pagination) usam bind múltiplo. Os 44 restantes ficam fora do catálogo com o motivo registrado no mapeamento. | Os 39 propostos · cortar ou adicionar |
D7aplicado | IconName central na lib | Fonte única de nomes de ícone (IconName). | A lib exporta iconNames, iconRegistry e resolveIconName (vueui-nova-kit 1.0.0-rc.5). O IconName do catálogo sai de iconNames, e o renderer resolve os ícones, inclusive os aninhados em itens, com resolveIconName. | Lib exporta um tipo/registry único · gerador continua extraindo dos .types.ts |
D8aplicado | Props de cor livre | Props de cor livre viram enum de tokens semânticos. | dotColor, items[].color e stats[].color aceitam só primary, info, success, warning, danger ou neutral, e o renderer traduz para --v-color-*. | Enum de tokens · excluir |
D9aplicado | Action de change | Sem action de change nos inputs: os valores vão no context quando uma action dispara. | Catálogo e renderer seguem isso. Busca ao vivo usa a action própria do SearchField. | Não (só context no envio) · opcional (changeAction) |
D10aplicado | Table.rows | Table.rows livre, com validação semântica no renderer. | O renderer emite error VALIDATION_FAILED quando falta id numa linha ou quando uma coluna não existe em nenhuma linha. | Livre (additionalProperties: true) · schema por coluna derivado de columns |
D11aplicado | Inputs sensíveis | Inputs sensíveis com opt-in explícito do host. | PasswordInput e OtpInput estão no catálogo, marcados como sensíveis. Sem allowSensitive: true o runtime não os monta e responde com error. FileUpload fica fora do catálogo: arquivo não cabe no data model JSON. | Nunca · opt-in do host |
D12aplicado | Mojibake | Mojibake corrigido na lib, e o gerador falha se encontrar U+FFFD. | Corrigido na lib (VCardGrid e VAutoLayoutGrid). O gerador do catálogo, o gen-a2ui da doc e o build do pacote interrompem se encontrarem U+FFFD. | Corrigir já (outro agente/Walder) · deixar |
| # | Risco | Prob. | Impacto | Tratamento |
|---|---|---|---|---|
| R1 | @a2ui/web_core ainda é 0.x e muda de API entre minors | Alta | Médio | Versão exata pinada; camada fina de bridge isolando o core; conformance no CI detecta quebras; atualizar em PRs dedicados |
| R2 | web_core traz lit/preact/zod para o bundle (lit é dependência declarada) | Média | Médio | Spike L0 mede; importar só subpaths de core; se inaceitável, D2 = núcleo próprio (+10–15 dias) |
| R3 | setSignalImplementation é global: conflito com outro renderer A2UI na mesma página | Baixa | Médio | Documentar: um renderer A2UI por app. Alternativa: manter preact signals e só fazer bridge por effect → shallowRef |
| R4 | Spec v1.0 recente: a conformance pode ter casos ambíguos | Média | Baixo | Registrar divergências; seguir o comportamento do renderer React como referência |
| R5 | Catálogo depende do formato de ui-nova-docs/app/generated/components/*.json (outro agente mexe na doc) | Média | Médio | Gerador falha alto em campo ausente; --check no CI; plano B: extrair direto dos .types.ts (já usado para enums e IconName) |
| R6 | Órfãos: updateComponents não remove componentes, que acumulam em sessões longas | Média | Baixo | Montar só o alcançável a partir de root; validador avisa (já faz: 2 avisos esperados no exemplo 01); coletor de órfãos opcional no renderer |
| R7 | Props de cor livre (Badge.dotColor, StatCard.stats[].color, BarList.items[].color) permitem cor arbitrária | Alta (se nada for feito) | Baixo | D8: enum de tokens ou exclusão |
| R8 | $id/catalogId em URN quebra a resolução relativa de common_types.json em validadores | Média | Médio | Hoje o catálogo embute o necessário; D3 recomenda https:// |
| R9 | Mojibake no upstream (U+FFFD em descrições) vaza para o catálogo e para a doc | Certa (já ocorre) | Baixo | Corrigir na lib (fora do escopo deste repo; ver seção 17); o gerador poderá falhar se encontrar U+FFFD |
| R10 | LLMs inventam props ou componentes | Alta | Médio | additionalProperties: false, instructions, skill com catálogo gerado, error com path para autocorreção |
| R11 | Phishing via UI gerada (pedir senha/cartão) | Média | Alto | Inputs sensíveis fora do catálogo; UrlPolicy; host pode exibir selo "conteúdo gerado por agente" |
| R12 | Componentes da lib chamam requestAnimationFrame no setup (SSR) | Certa | Baixo | Playground client-only; recomendar o raf-shim (já na skill ui-nova-vue) |