fix: tornar completude FolEs contextual e sugerir valores

[oxbar]

Completude contextual de propriedades e valores em FolEs

Fixes #106

Problema

O provedor de completude de FolEs calculava a profundidade das chaves para decidir quando incluir propriedades, mas inicializava a resposta com todos os seletores LMHT de forma incondicional.

Na prática:

1. Fora de blocos, os seletores eram sugeridos corretamente;
2. Dentro de uma regra, os modificadores eram adicionados, mas os seletores continuavam presentes e geravam ruído irrelevante;
3. Depois de digitar uma propriedade seguida de :, o provedor continuava oferecendo propriedades e seletores, sem consultar os valores aceitos pelo modificador;
4. Propriedades de cor, como cor:, não ofereciam os nomes de cores existentes no pacote FolEs;
5. O registro do provedor não declarava : como caractere de gatilho, então a lista de valores não era aberta imediatamente após a propriedade.

Com os dados atuais do pacote, o comportamento anterior retornava 611 itens dentro de uma regra: 501 modificadores e 110 seletores LMHT sem utilidade naquele contexto.

Solução

O provedor passa a distinguir três contextos de completude:

Fora de blocos

Retorna exclusivamente seletores LMHT.

|  ← seletores LMHT

Dentro de uma regra, antes de :

Retorna exclusivamente modificadores FolEs.

paragrafo {
    |  ← modificadores
}

Os 110 seletores deixam de ser misturados aos 501 modificadores. A lista dentro da regra passa de 611 para 501 itens, eliminando o ruído apontado na issue.

Depois de propriedade:

Retorna valores relacionados à propriedade atual.

paragrafo {
    alinhamento: |  ← esquerda, centro, direita…
    cor: |          ← azul, vermelho, rgb, rgba…
}

Valores específicos dos modificadores

O pacote @designliquido/foles já contém as classes dos modificadores e seus dicionários valoresAceitos.

O provedor percorre as classes exportadas por @designliquido/foles/modificadores, instancia cada uma em modo de variável — evitando validação de uma declaração real — e monta um cache entre:

• nome FolEs da propriedade;
• nome CSS equivalente;
• valores aceitos pelo modificador.

Aliases com e sem acentuação continuam funcionando. Quando um alias não está diretamente disponível na classe, o provedor usa o nome CSS de listaModificadores para localizar o mesmo conjunto de valores.

A construção é defensiva: uma classe que eventualmente passe a exigir estado adicional é ignorada sem interromper o IntelliSense.

Valores globais

Todo modificador reconhecido também recebe os valores globais do pacote FolEs:

• herdar;
• inicial;
• reverter;
• reverter-camada;
• desarmar.

Esses itens são apresentados como CompletionItemKind.Value, com o equivalente CSS em detail e na documentação.

Cores e funções de cor

Para propriedades reconhecidas como propriedades de cor, o provedor usa:

• Cores, para identificar propriedades que aceitam cor;
• cores, para obter os nomes FolEs e os equivalentes CSS;
• DicionarioValores, para oferecer as funções hex, hsl, hsla, rgb e rgba quando elas existem no pacote.

Os nomes de cor são criados como CompletionItemKind.Color, permitindo que o VS Code os apresente com o tratamento visual específico de cores. O equivalente CSS aparece ao lado do item e na documentação.

Exemplo:

vermelho    Equivalente em CSS: red
azul        Equivalente em CSS: blue
rgb         Função de cor
rgba        Função de cor

Valores repetidos entre dicionários são deduplicados. Quando um valor também é uma cor, o tipo Color tem prioridade.

Detecção da declaração atual

A linha é analisada somente até a posição do cursor. O provedor considera o trecho depois do último:

• {;
• };
• ;.

Isso permite:

• completar uma declaração em uma linha própria;
• completar uma declaração na mesma linha da abertura do bloco;
• voltar à completude de propriedades depois de ;;
• não oferecer valores para propriedades desconhecidas.

Gatilho de completude

O registro de FolesProvedorCompletude em fontes/ativacao-linguagens.ts passa a declarar : como caractere de gatilho:

vscode.languages.registerCompletionItemProvider(
    seletoresFolEs,
    new FolesProvedorCompletude(),
    ':'
);

Como a ativação de linguagens é compartilhada pelas extensões desktop e web, o comportamento fica disponível nos dois ambientes.

Testes

testes/completude/foles-provedor-completude.test.ts foi atualizado para 19 casos de regressão:

1. Criação do provedor;
2. Somente seletores LMHT na raiz;
3. Retorno aos seletores depois do fechamento da regra;
4. Documentação do equivalente HTML;
5. Somente modificadores dentro de uma regra;
6. Presença dos modificadores esperados;
7. Documentação e equivalente CSS das propriedades;
8. Retorno às propriedades depois de ;;
9. Valores específicos de um modificador;
10. Ausência de seletores e propriedades no contexto de valores;
11. Valores globais para propriedades conhecidas;
12. Nenhum valor para propriedade desconhecida;
13. Declaração na mesma linha da abertura da regra;
14. Nomes de cores depois de cor:;
15. Uso de CompletionItemKind.Color e equivalente CSS;
16. Funções de cor do DicionarioValores;
17. Exclusão de funções genéricas que não representam cor;
18. Deduplicação de valores;
19. Registro de : como gatilho do provedor.

Validação focada

yarn jest \
  testes/completude/foles-provedor-completude.test.ts \
  --runInBand

Validações adicionais

yarn typecheck
yarn testes-unitarios --runInBand
yarn build-base
yarn compilar-web

Validação manual recomendada

1. Abrir um arquivo .foles vazio e confirmar que a raiz sugere seletores LMHT;
2. Criar uma regra e confirmar que o interior não sugere seletores;
3. Confirmar que o interior da regra sugere modificadores FolEs;
4. Digitar alinhamento: e verificar os valores qualitativos aceitos;
5. Digitar cor: e verificar nomes de cores e funções de cor;
6. Confirmar que os nomes de cor usam o tipo visual de cor e mostram o equivalente CSS;
7. Digitar ; depois de um valor e confirmar que o provedor volta a sugerir propriedades;
8. Repetir o fluxo na extensão desktop e no VS Code Web.

Observação de escopo

Este PR corrige o contexto da completude e utiliza os dicionários já expostos pelo pacote FolEs.

Não inclui um provedor separado de cores do documento (DocumentColorProvider) nem altera o parser, o formatador ou as regras de validação da linguagem.

Checklist

• Seletores oferecidos somente fora de blocos
• Modificadores oferecidos somente dentro de regras
• Valores oferecidos após propriedade:
• Valores específicos obtidos de valoresAceitos
• Aliases associados pelo nome FolEs ou pelo equivalente CSS
• Valores globais incluídos para propriedades reconhecidas
• 171 nomes de cores carregados do pacote FolEs
• Cores marcadas com CompletionItemKind.Color
• Funções hex, hsl, hsla, rgb e rgba carregadas de DicionarioValores
• Valores duplicados eliminados
• Propriedades desconhecidas não recebem sugestões arbitrárias
• : registrado como gatilho de completude
• 19 testes focados de regressão
• Teste focado executado com sucesso
• yarn typecheck executado com sucesso
• Suíte unitária completa executada com sucesso
• Builds desktop e web executados com sucesso
• Validação manual realizada no VS Code

[leonelsanchesdasilva]

Obrigado!