# Especificação do Cordel — v0.1.0

Cordel é uma sintaxe mínima, inspirada em markdown, pra descrever dois efeitos de
texto direto na string de conteúdo: um **carrossel de palavras** que troca sozinho
e um **texto colorido**. A ideia é que quem escreve conteúdo (redator, editor)
consiga pedir esses efeitos sem escrever HTML/CSS/JS na mão.

Cordel não é um substituto do markdown — ele foi pensado pra ser usado **dentro**
de um título, frase ou trecho já existente, junto com markdown normal ou HTML puro.

## 1. Carrossel de palavras

```
[palavra1|palavra2|palavra3]
```

- Precisa de **no mínimo 2 opções** separadas por `|`. Com 0 ou 1 opção, o texto
  entre colchetes é devolvido literalmente (não vira carrossel).
- Espaços em volta de cada opção são ignorados (`[ Gmail | Outlook ]` funciona
  igual a `[Gmail|Outlook]`).
- Ordem importa: a primeira palavra é a que aparece antes da animação começar
  (relevante pra quem desabilitou animação, ou pra renderização sem JS).
- Troca em loop, continuamente, com um efeito de troca vertical (a palavra atual
  sobe e sai, a próxima entra por baixo).

**Exemplo:**

```
Seu e-mail nunca foi seu: como [Gmail|Outlook|Yahoo|big techs] decide o que você recebe
```

### Acessibilidade

O carrossel usa `aria-label` (com todas as opções separadas por vírgula) no elemento
que engloba a animação, e `aria-hidden="true"` na palavra visível/animada por dentro.
`aria-label` é um **atributo**, não um nó de texto — ele nunca aparece na tela e nunca
entra em seleção/cópia de texto (Ctrl+A/Ctrl+C), diferente da técnica antiga de um
`<span>` visualmente escondido só com CSS (`clip`/tamanho 1px), que continua presente
no DOM como texto de verdade e por isso aparece grudado no conteúdo copiado. O Cordel
já nasceu tendo passado por esse problema uma vez (numa versão anterior, ad-hoc, antes
do Cordel existir) — por isso a escolha por `aria-label` aqui.

### Respeitando `prefers-reduced-motion`

Quando o sistema do usuário pede menos animação, `Cordel.mount()` não inicia o
loop de troca — a primeira palavra fica fixa, sem nenhuma configuração adicional
necessária.

## 2. Texto colorido

```
{token:texto}
```

- `token` pode ser um nome de cor conhecido (`azul`, `amarelo`, `coral`, `lima`,
  `roxo`, `escuro` — os tokens padrão do Cordel, definidos como variáveis CSS) ou
  um valor hexadecimal direto, tipo `{#ff5a5f:texto}`.
- Nomes de cor viram a classe `cordel-cor--<token>`, então você pode definir seus
  próprios tokens só criando `--cordel-<nome>` no CSS e usando
  `.cordel-cor--<nome>{color:var(--cordel-<nome>)}`.
- Se não houver `:` dentro das chaves, o conteúdo é devolvido literalmente (não
  quebra a renderização).

**Exemplo:**

```
{coral:Isso é grave}: quase 700 mil pessoas pararam de receber o boletim.
```

## 3. Escape

Pra usar `[`, `]`, `{` ou `}` como caractere literal (não como sintaxe Cordel),
use barra invertida: `\[`, `\]`, `\{`, `\}`.

```
Isso não é um \[array\] de verdade.
```

## 4. O que Cordel NÃO faz (por enquanto)

- Não tem suporte a aninhamento (um carrossel dentro de um texto colorido, ou
  vice-versa) — isso fica pra uma v0.2, se fizer sentido.
- Não interpreta markdown normal (`**negrito**`, links, etc.) — Cordel cuida só
  dos dois efeitos acima; combine com seu parser de markdown de preferência se
  precisar dos dois.
- Não normaliza HTML de entrada — texto fora da sintaxe Cordel é sempre escapado
  (`&`, `<`, `>`, `"`), então não dá pra injetar HTML arbitrário através do texto.

## 5. Referência da API JS

```js
Cordel.render(texto, opcoes?) -> string   // converte a sintaxe em HTML
Cordel.mount(raiz?)                        // ativa a animação dos carrosséis presentes em `raiz` (padrão: document)
Cordel.unmount(elemento)                   // para a animação de um carrossel específico
Cordel.version                             // string da versão, ex: "0.1.0"
```

`opcoes.interval` (padrão `2600`, em milissegundos) define o tempo entre trocas
de palavra no carrossel.

Veja `cordel.js` e `cordel.css` — é só isso, sem dependências, sem build step.