silegis-mg/editor-articulacao

Biblioteca javascript (ES6, com build para ES5) de edição da articulação de uma norma ou projeto de lei, conforme formato especificado pelo LexML.

Editor de Articulação

O editor de articulação é uma biblioteca javascript elaborada pela Assembleia Legislativa de Minas Gerais, como parte do Sistema de Informação Legislativa de Minas Gerais (Silegis-MG).

Ele permite a edição de texto articulado, formatando e numerando automaticamente artigos, parágrafos, incisos, alíneas e itens, bem como as divisões em títulos, capítulos, seções e subseções. O texto articulado é estruturado em formato XML, conforme elemento Articulacao definido pelo schema do LexML.

Demonstração

Acesse https://silegis-mg.github.io/editor-articulacao/ para ver uma simples demonstração do editor de articulação funcionando em seu navegador.

Funcionalidades

• Criação de rótulo e numeração automática para dispositivos (artigo, parágrafo, inciso, alínea e item);

• Formatação padrão dos dispositivos, conforme regras de redação definidas no art. 12 da LCP 78/2004.

  • A formatação pode ser configurada, para atender ao padrão de redação federal, sem alteração no código.

• Divisão dos artigos em títulos, capítulos, seções e subseções;

• Validação automática de:

  • caixa alta: artigos e parágrafos não devem ser escritos usando apenas caixa alta;
  • uso de aspas: citações devem estar entre aspas e terminar com ponto final (.);
  • enumerações: enumerações devem possuir mais de um elemento;
  • letra maiúscula: artigos e parágrafos devem ser iniciados com letra maiúscula;
  • pontuação: artigos e parágrafos devem ser terminados com ponto final (.) ou dois pontos (:), sem espaço antes da pontuação, e enumerações devem ser terminadas com ponto final (.), ponto e vírgula (;) ou dois pontos (:), sem espaço antes da pontuação.;
  • sentença única: dispositivos devem conter uma única sentença.

• Auto-formatação:

  • ao abrir aspas, formata-se automaticamente como um texto dentro do caput, permitindo múltiplas linhas dentro das aspas;
  • ao fechar aspas, formata-se a próxima linha como um novo artigo;
  • ao finalizar com dois pontos, inicia-se uma enumeração (de artigo ou parágrafo para inciso, de inciso para alínea e de alínea para item);
  • ao finalizar com ponto final, finaliza-se a enumeração (de item para alínea, de alínea para inciso, de inciso para artigo ou parágrafo);
  • ao dar enter em uma linha vazia, troca a formatação da linha vazia para artigo, quando formatado como parágrafo, ou encerra a enumeração, quando formatado como inciso, alínea ou item.

• Articulação pode ser importada/exportada de/para XML, seguindo especificação do LexML;

• Interpretação de conteúdo colado, de forma a permitir a formatação e numeração automática em dispositivos estruturados.

Como usar a partir do código fonte

Pré-requisitos para compilação

• NodeJS com npm

Baixando o editor

git clone https://github.com/silegis-mg/editor-articulacao.git

Instalação das dependências

Após baixar o editor, mude para o diretório onde encontram os fontes e instale as dependências:

cd editor-articulacao
npm install

Executando exemplo

Finalizado o passo anterior, execute:

npm start

Em seguida, basta abrir o navegador no endereço http://localhost:8080/exemplo.html

Testando

O editor de articulação possui testes automatizados utilizando karma e protractor.

npm test

Se estiver utlizando proxy, defina a variável de ambiente http_proxy para que o teste consiga baixar o webdriver do Chrome mais atual.

Gerando pacote para aplicações finais em ES5

O javascript minificado é gerado por meio do webpack, a partir de uma tarefa do grunt. Existem dois empacotamentos para uso em aplicações finais:

Plain-JS

O empacotamento plain-js define silegismgEditorArticulacao como uma função global para transformar um elemento no DOM em um editor de articulação. Também define a função silegismgEditorArticulacaoController para criar o controller, caso o utilizador queira maior controle da interface de usuário.

Também é definida a função global silegismgInterpretadorArticulacao.interpretar para interpretação de texto articulado.

Gerando pacote

npx grunt build-plain

É possível incluir o polyfill do babel também, utilizando:

npx grunt build-plain-polyfill

Utilizando plain-js

Existem duas possibilidades para criar o editor de articulação. Uma que incorpora a barra de ferramentas e outra que apenas vincula o controlador do editor de articulação, permitindo ao utilizador personalizar por completo a interface de usuário.

Para criar o editor de articulação com barra de ferramentas padrão, utilize a sintaxe silegismgEditorArticulacao(elemento, opcoes). Para criar o editor de articulação personalizando por completa a interface de usuário, utilize a sintaxe silegismgEditorArticulacaoController(elemento, opcoes), que retornará o controlador, cujos métodos estão descritos na API do controlador. Para exemplo de como personalizar a interface, veja o arquivo de teste do protractor.

Veja também a API do interpretador de articulação.

Exemplo

<script src="build/silegismg-editor-articulacao-plain-js.js"></script>
<div id="editor"></div>
<script>
  silegismgEditorArticulacao(document.getElementById('editor'));
</script>

Angular 1

O empacotamento angular1 registra a diretiva silegismgEditorArticulacaoConteudo no módulo silegismg-editor-articulacao para AngularJS 1.x.

Gerando pacote

npx grunt build-angular1

Exemplo

<script src="build/silegismg-editor-articulacao-angular1.js"></script>
<silegismg-editor-articulacao-conteudo id="editor" opcoes="opcoes"></silegismg-editor-articulacao-conteudo>

Utilizando como módulo ES6 e webpack

npm install silegismg-editor-articulacao

JS:

import { ComponenteEdicao, EditorArticulacaoController, interpretadorArticulacao } from 'silegismg-editor-articulacao';

const opcoes = { /* ... */ };
var elemento = document.getElementById('exemplo');
var ctrl = new EditorArticulacaoController(elemento, opcoes);

HTML:

<div id="exemplo"></div>

Configuração do webpack

O editor de articulação importa o conteúdo do CSS e manipula em tempo de execução, a fim de aplicar os parâmetros de configuração. Para tanto, deve-se utilizar o seguinte loader para os arquivos CSS deste módulo:

{
    test: /\.css$/,
    use: {
        loader: 'css-loader',
        options: {
            minimize: true,
            sourceMap: true
        }
    }
}

Opções do editor de articulação

Atributo	Tipo	Valor padrão	Descrição
shadowDOM	Boolean	false	(Experimental) Determina se deve adotar o Shadow DOM, se suportado pelo navegador.
transformacaoAutomatica	Boolean	true	Determina se o editor de articulação deve aplicar transformação automática.
escaparXML	Boolean	false	Determina o escapamento de caracteres de código alto unicode durante a exportação para lexmlString.
rotulo	Object		Determina o sufixo para os rótulos dos dispositivos.
validarAoAtribuir	Boolean	true	Determina se deve validar o conteúdo atribuído ao componente.
validacao	Object		Determina as validações que devem ocorrer.

Opções de rótulo

Todos os atributos de rótulo são do tipo literal (String).

Atributo	Valor padrão	Descrição
separadorArtigo	–	Separador do rótulo do artigo 1º ao 9º
separadorArtigoSemOrdinal	–	Separador do rótulo do artigo 10 em diante
separadorParagrafo	–	Separador do rótulo do parágrafo 1º ao 9º
separadorParagrafoSemOrdinal	–	Separador do rótulo do parágrafo 10 em diante
separadorParagrafoUnico	–	Separador do rótulo parágrafo único
separadorInciso	–	Separador do rótulo de inciso
separadorAlinea	)	Separador do rótulo da alínea
separadorItem	)	Separador do rótulo do item

Opções de validação

Todas as opções de validação são habilitadas (valor true) por padrão.

Atributo	Descrição
caixaAlta	Determina se deve validar o uso de caixa alta.
citacao	Determina se deve validar o uso de aspas em citações.
enumeracaoElementos	Determina se deve validar a presença de múltiplos elementos em uma enumeração.
inicialMaiuscula	Determina se deve validar o uso de letra maiúscula no caput do artigo e em parágrafos.
pontuacao	Determina se deve validar as pontuações.
pontuacaoEnumeracao	Determina se deve validar pontuação de enumeração.
sentencaUnica	Determina se deve exigir sentença única no dispositivo.

API do controlador

Propriedade/Função	Retorno/Valor	Descrição
lexml (propriedade)	ElementNS	Obtém ou define o XML da articulação no formato LexML.
lexmlString (propriedade)	String	Obtém ou define o XML da articulação no formato LexML, porém em String.
alterado (propriedade, somente leitura)	Boolean	Verifica se o editor de articulação sofreu alteração.
alterarTipoDispositivoSelecionado(novoTipo)	void	Altera o tipo do dispositivo em que o cursor se encontra, pelo novo tipo (String) fornecido como parâmetro. Os tipos possíveis são: titulo, capitulo, secao, subsecao, artigo, paragrafo, inciso, alinea e continuacao (todos sem acentuação ou cedilha).
contexto	object	Obtém o contexto atual do editor

Eventos do controlador

Evento	Disparo	Condição	Classe do evento	Dados do evento
change	blur	Texto articulado alterado	ArticulacaoChangeEvent	N/A
contexto		Objeto de contexto atualizado	ContextoArticulacaoAtualizadoEvent	ContextoArticulacao
transformacao		Controlador aplicou alguma transformação automática	TransformacaoAutomaticaEvent	Objeto contendo os seguintes atributos: automatica (booleano), tipoAnterior (literal, tipo do elemento antes da alteração), novoTipo (literal, tipo do elemento depois da alteração), transformacao (literal, nome da transformacao), editorArticulacaoCtrl (controller)

API do interpretador

Para interpretar um texto puro, transformando em um texto estruturado utilizando LexML, utilize a função interpretar (veja código-fonte), com a seguinte sintaxe:

interpretadorArticulacao.interpretar(texto, formatoDestino, formatoOrigem);

onde texto é uma string, formatoDestino é uma das opções "json", "lexml" (padrão) ou "lexmlString" e formatoOrigem é "texto" (padrão) ou "html".

Contribuições desejadas

• Identificação de remissões;
• Renumeração automática de remissões, em caso de alterações nos dispositivos;
• Modo de edição de norma, em que alterações a um texto original são consideradas emendas.

Limitações conhecidas (aceita-se contribuições)

As limitações conhecidas correspondem a um conjunto de funcionalidade que não funciona como deveria, mas seu comportamento é aceitável para a proposta do editor. Contribuições são bem-vindas.

• Copiar do editor de articulação e colar em editor externo omite os rótulos;
• Interpretação de artigo com emenda (exemplo: Art. 283-A da Constituição do Estado de Minas Gerais), apesar de haver suporte para importação de LexML com este tipo de dispositivo.

Compatibilidade com navegadores

Navegador	Compatível	Mantida1
Firefox 52	✓	✓
Firefox Quantum 57	✓
Chrome 62	✓	✓
IE 11	✓
Edge	✓
Safari	?

¹: Considera-se compatibilidade com navegador mantida aquela que é constantemente testada pela equipe de desenvolvimento.

editor-articulacao's Issues

Editor vazio não funciona no Firefox Quantum (57.0.1)

O editor de articulação no Firefox Quantum, versão 57.0.1, não funciona quando a articulação está vazia. Entretanto, o editor funciona quando já tem conteúdo e então ganha foco.

Passos para reprdouzir:

1. Abra o exemplo do editor de articulação em https://silegis-mg.github.io/editor-articulacao/ com o Firefox 57.0.1
2. Clique sobre o "Art. 1º"
3. Digite: "Teste".

Resultado esperado

Texto articulado contendo "Art. 1º Teste"

Resultado obtido

Texto articulado contendo:

Teste
     Art. 1º

Animação no rótulo prejudica o desempenho no Microsoft Edge

Ao importar a constituição federal no editor de articulação, o Microsoft Edge tem seu desempenho bastante prejudicado, aparentemente pela animação dos rótulos, levando segundos. O texto da constituição, ao ser exibido na tela, aparece sem rótulos nos dispositivos e depois de segundos a animação completa.

Versão do navegador: Edge 16.16299

Problema não ocorre no IE 11.

Apenas alguns erros são renderizados instantaneamente ao colar um novo texto.

Quando colamos um texto que tenha erros em diversas articulações, apenas alguns erros são renderizados instantaneamente. É necessário navegar pelo texto alterando o contexto para que eventualmente os erros reminescentes sejam renderizados.

Há algum caminho sugerido para investigar uma solução desse bug?

Escapamento de unicode passou a falhar no Chrome 75

A função escaparXml utiliza expressão regular para substituir caracteres com código alto no XML, usando a flag "i" para casamento insensível à caixa.

editor-articulacao/src/EditorArticulacaoController.js

Lines 539 to 550 in a0af32c

	/**
	* Substitui caracteres de código alto por códigos unicode.
	* Substitui entidades não suportadas no XML por códigos unicode.
	*
	* @param {String} xml XML original.
	* @returns {String} XML escapado.
	*/
	function escaparXml(xml) {
	return xml.replace(/[\u00A0-\u9999]/gim, function (i) {
	return '&#' + i.charCodeAt(0) + ';'; // Converte em unicode escapado.
	});
	}

A partir do Chrome 75, a expressão regular passou a casar a letra "s" (código 115) com o caractere "ſ" (s longo, código 383, unicode 017F).

Veja que:

"\u017F" !== 's' && "\u017F".toUpperCase() === 'S' // true

Dessa forma, o editor de articulação passou a escapar toda letra "s" minúscula, inclusive

<Articulacao xmlns="http://www.lexml.gov.br/1.0">

que passou a ser escapado como

<Articulacao xmln&#x115;="http://www.lexml.gov.br/1.0">

Editor de articulação não funciona corretamente no Edge quando vazio

Apesar de funcionar corretamente no IE 11, no Microsoft Edge o editor de articulação não funciona quando vazio. Ao digitar um termo qualquer, como "Teste", no Art. 1º, e pressionar Enter, o navegador quebra o termo "Teste", encapsulando em um div, provocando uma separação de linha entre o rótulo do dispositivo e o caput.

O html incorreto resultante é:

<p style="min-height: 1em;" data-tipo="artigo">
   <div>Teste.</div>
   <div>
      <br>
   </div>
</p>

O html esperado seria:

<p data-tipo="artigo" style="min-height: 1em;">Teste.</p>
<p data-tipo="artigo" style="min-height: 1em;"><br></p>

Quando o editor de articulação já possui conteúdo (como importação da constituição na página de exemplo), ele funciona corretamente.

Versão do Edge: 16.16299

Hangout para tirar dúvidas

Olá! Sou desenvolvedor do Laboratório Hacker da Câmara dos Deputados e estamos construindo uma ferramenta para os consultores da Casa e gostamos bastante do editor-articulacao e estamos querendo incluí-lo no projeto. Mas temos algumas dúvidas e gostaríamos de saber se poderia rolar um hangout pra trocarmos uma ideia...
Desde já, agradeço!