@1doc/1ds-react 0.0.1 → 2.7.1

package/CHANGELOG.md

@@ -0,0 +1,667 @@
+# @1doc/1ds-react
+
+## 2.7.1
+
+### Patch Changes
+
+- 89150e3: fix(alto-contraste): superfícies sobrepostas ganham borda no tema de alto contraste
+
+  No `1doc-high-contrast` a página e as superfícies flutuantes são pretas e a
+  sombra (preta) não aparece: Modal, ConfirmDialog, Drawer, BottomSheet e
+  Tooltip não tinham borda visível. Agora ganham um traço branco
+  (`--umds-semantic-color-neutral-light-down`, a borda de campo do tema), em
+  outline para dentro — não muda o tamanho de nenhuma superfície.
+
+  Quem já tinha traço, mas apagado neste tema, passa à mesma borda branca: o
+  tooltip do Chart e os painéis do TimePicker e do PhoneInput (#5A5A5A), o
+  painel do AILabel (`ai-light`, quase preto) e o Toast `neutral` (sem traço —
+  e que também ganha a cor de texto do tema: herdava a do body e saía preto
+  sobre preto).
+  As barras que flutuavam só com sombra — rodapé do Drawer e do BottomSheet e a
+  BottomNavigation `raised` — ganham uma linha no topo.
+
+  O fechar do Alert e do Toast deixa de nascer esmaecido neste tema, e o realce
+  de hover do fechar do Alert acompanha a cor do texto.
+
+  Tudo escopado em `[data-theme="1doc-high-contrast"]`: os outros 12 temas não
+  mudam. Nenhum token novo.
+
+- fe1ba4f: **Chart:** a ponta da barra passa do raio de 4px (fora da escala) para o raio
+  canônico do DS, 8px (`--umds-primitive-border-radius-sm`), limitado a metade da
+  largura e da altura da barra — barra fina não vira pílula e barra curta não
+  estoura a linha de base. Continua arredondada só na ponta do dado, inclusive
+  nas negativas. A dica do gráfico troca o respiro de 12px por 8px/16px, da
+  escala oficial. Os literais de largura mínima que batiam com um token de
+  espaçamento passam a usá-lo (mesmo valor, sem mudança visual).
+- 5fcde30: fix(kanban): borda da coluna acima do limite usa o token de negativo direto
+
+  A borda da coluna acima do limite de WIP passa de `color-mix(... negative-pure 40%, transparent)`
+  para `var(--umds-semantic-color-feedback-negative-pure)`, sem mistura. Contraste da borda contra
+  o fundo da coluna: 6.41:1 (1doc), 4.65:1 (1doc-dark), 6.62:1 (1doc-high-contrast) — antes
+  ficava entre 1.7:1 e 2.1:1, abaixo do mínimo de 3:1. O fundo da coluna destacada durante o
+  arrasto passa a usar `primary-light` direto. Comentários "candidato a novo token" reescritos:
+  o 1DS não cria tokens novos; os literais restantes são intencionais.
+
+## 2.7.0
+
+### Minor Changes
+
+- 14108ac: feat(chart): BarChart, LineChart e DonutChart — gráficos em SVG puro
+
+  Família nova de gráficos, sem biblioteca externa: o Mitosis desenha o SVG e o
+  resultado é o mesmo no React e no Vue.
+
+  - `BarChart` — barras verticais, com séries agrupadas lado a lado e suporte a
+    valores negativos (a barra arredonda na ponta do dado, nunca na base).
+  - `LineChart` — uma ou mais séries; `null` interrompe a linha em vez de cair a
+    zero; pontos opcionais (`showPoints`) e, na categoria em foco, uma linha
+    vertical marcando o ponto.
+  - `DonutChart` — partes de um todo com o total no centro e legenda com valor e
+    percentual em texto. Mais de 5 partes: o excedente vira "Outros", em neutro.
+
+  API comum: `data` (`[{ label, value }]`) ou `series` + `labels`, `title`,
+  `ariaLabel`, `valueFormatter` ou `unit`, `showLegend`, `showGrid`, `height`,
+  `emptyText`.
+
+  Cores só de tokens semânticos, numa ordem fixa de até 5 séries — primary, info,
+  primary-dark, primary-medium, ai — escolhida com o validador de daltonismo nos
+  temas 1doc e 1doc-dark. O tema escuro vem dos próprios tokens. A largura
+  acompanha o contêiner, então o texto dos eixos fica sempre em 12px.
+
+  Acessibilidade: resumo no `role="img"`, tabela visualmente oculta com todos os
+  números, e cada categoria é focável — Tab entra, setas andam, Esc fecha o
+  tooltip. Respeita `prefers-reduced-motion`.
+
+- eb9927c: feat(kanban): quadro de colunas com cartões que se movem por arrasto e por teclado
+
+  Três componentes novos: `Kanban` (o quadro), `KanbanColumn` (título, contagem,
+  limite de WIP, corpo que rola, rodapé com "Adicionar cartão") e `KanbanCard`
+  (etiquetas, título, descrição, metadado, responsável).
+
+  O `Kanban` é orientado a dados e controlado: recebe `columns` e chama
+  `onCardMove({ cardId, fromColumnId, fromIndex, toColumnId, toIndex })` — o
+  `toIndex` já desconta a saída do cartão da origem, é o índice de `splice`
+  direto. Move-se arrastando (HTML5 Drag and Drop nativo, com linha de soltura)
+  ou pelo teclado: Espaço pega, setas movem com prévia na tela, Espaço ou Enter
+  soltam, Esc cancela, e cada passo é anunciado numa região `aria-live`. O quadro
+  é uma parada só de Tab (roving tabindex).
+
+- 8bff8c5: feat(podium): os três primeiros de um ranking num pódio
+
+  Componente novo. O 1º fica no centro, no degrau mais alto; o 2º à esquerda e o
+  3º à direita. Com `showRest`, do 4º em diante vira uma lista numerada abaixo.
+
+  A ordem visual (2º, 1º, 3º) é posta pelo CSS Grid, por área: o DOM e o leitor
+  de tela seguem 1º, 2º, 3º, e cada lugar tem uma frase acessível completa
+  ("1º lugar: Ana Paula, 128 pontos"). Os itens chegam já ordenados.
+
+  O 1DS não tem ouro, prata e bronze: os degraus usam `feedback-info`, `neutral`
+  e `primary` até existir um token de medalha.
+
+- 70dc082: feat(tokens): tema de alto contraste `1doc-high-contrast`
+
+  Novo `theme-1doc-high-contrast.css`, ativado com
+  `data-theme="1doc-high-contrast"`: fundo preto, texto branco e cor interativa
+  amarela (`#FFFF00`) — links, botões, foco e selecionado —, com texto preto
+  sobre o amarelo cheio. Define as mesmas 29 variáveis `--umds-theme-*` dos
+  outros temas, então nenhum token cai no valor do tema padrão.
+
+  Todo texto passa WCAG AAA (7:1) contra o fundo, e toda fronteira de componente
+  passa 3:1. A tabela de contraste está no README de `@1doc/1ds-tokens`.
+
+  `Theme` (core/react/vue) ganha `"1doc-high-contrast"`, e `setTheme`,
+  `getTheme` e `getAvailableThemes` passam a aceitá-lo. O DS não liga o tema
+  sozinho: o README mostra como o produto pode seguir
+  `prefers-contrast: more`. Os 12 temas existentes não mudam.
+
+### Patch Changes
+
+- ffaa5c0: fix(dropdown): no Vue o menu não abria — e mais 9 componentes com a mesma causa
+
+  Clicar no gatilho do `Dropdown` no Vue não renderizava nada, `mounted` voltava a
+  `false`, e não havia erro nenhum no console. No React funcionava.
+
+  `open` era tipada `boolean`. O Vue aplica _boolean casting_: prop booleana
+  ausente chega como `false`, não como `undefined`. Com isso
+  `isControlled = props.open !== undefined` nascia **verdadeiro** mesmo sem
+  ninguém passar `open`, o `toggle()` montava o menu, e no `onUpdate` seguinte o
+  `syncOpenState()` via `!!props.open === false` contra `lastOpen === true` e
+  chamava `close()` — fechando o menu no mesmo tick em que ele abriu.
+
+  É o defeito de `.agent/troubleshooting/vue-boolean-prop-default.md`, o mesmo do
+  `SidePanel` e do `Popover`. Como já era a terceira reincidência, esta correção
+  varre a família inteira em vez de um componente por vez.
+
+  **Além de `!== false`, `=== false` é o mesmo defeito em espelho** — e era o mais
+  caro dos três: `if (props.closeOnEsc === false) return;` nasce verdadeiro no
+  Vue, e o Escape simplesmente parava de fechar `Modal`, `ConfirmDialog` e
+  `BottomSheet`. O grep original da dívida não pegava essa forma.
+
+  Passam a ser `any`, com o porquê comentado em cada `.lite.tsx`:
+  `Dropdown.open` · `AppHeader.bordered` · `AppSidebar.toggleable` ·
+  `BottomNavigation.fixed` ·
+  `BottomSheet.grabber`/`closable`/`closeOnEsc`/`closeOnBackdrop` ·
+  `ConfirmDialog.closeOnEsc` · `Modal.closeOnEsc`/`closeOnOverlayClick` ·
+  `Pagination.showPrevNext` · `ProgressBar.animated` · `Toast.closable`.
+
+  Ficam `boolean` de propósito os `open` de `Modal`, `ConfirmDialog`, `Toast` e
+  `BottomSheet`: são totalmente controlados, sem estado interno, e prop ausente
+  significando "fechado" é o comportamento certo.
+
+  `Dropdown.restoreFocus` e `Popover.restoreFocus`, que a dívida listava, eram
+  falso positivo — são parâmetro de função, não prop.
+
+  **A baseline visual do Vue estava gravada COM o bug**, e é a prova mais forte de
+  que a correção pega: a esteira reprovou 22 stories, todas de componentes desta
+  correção, e o que mudou foi o que passou a aparecer. A `Pagination/SinglePage`
+  era 80×80 com só o número "1"; agora é 302×84, com "Anterior" e "Próxima" de
+  volta. O rodapé do `AppSidebar` ganhou o botão de alternar. O `AppHeader`,
+  a borda. A `ProgressBar`, a listra.
+
+  O React não mexeu um pixel — 415/415 iguais, no Windows e no runner Linux —,
+  que é o esperado: lá nunca houve defeito. Só a baseline de `vue/linux` foi
+  regravada, e só as 22 imagens que de fato mudaram, para não sujar o MR com PNG
+  idêntico (o Chromium não é byte a byte determinístico).
+
+  O preço de tirar o `boolean` é que `<Dropdown open>` num template Vue passa a
+  entregar a string vazia, que é falsy. `Dropdown` e `Popover` passam a tratar o
+  `""`, como o `Drawer` já fazia.
+
+  E no `Dropdown`, dois defeitos de gatilho achados ao escrever o teste — mesma
+  raiz, o `<span>` wrapper não é o gatilho real:
+
+  - o **Escape fechava o menu e largava o foco no `<body>`**: quem recebia o
+    `focus()` era o wrapper, que fica sem `tabindex` quando o slot já traz um
+    `Button`, e `focus()` num span sem tabindex é no-op;
+  - o gatilho **não tinha `aria-haspopup` nem `aria-expanded` em lugar nenhum**
+    quando o slot trazia um `Button`. Os dois moravam no wrapper, e o wrapper só
+    os recebe quando ELE vira o botão — que é justamente o caso em que não há
+    botão dentro. Leitor de tela nunca anunciava que aquilo abre um menu.
+
+  Os dois têm o tratamento que o `Popover` já tinha: `alvoInterativo()` e
+  `sincronizarEstadoDoGatilho()` escrevem foco e `aria-` no elemento interativo
+  de dentro.
+
+## 2.6.0
+
+### Minor Changes
+
+- 3d2977e: fix(app-header): menu do usuário fora do botão, ícones sem registro e barra que não estoura
+
+  - O bloco do usuário vira um `<button>` de verdade (Enter/Espaço nativos) e o
+    `userMenu` é renderizado ao lado dele, não dentro — clicar no menu não
+    dispara mais `onUserClick`. Prop nova `userMenuOpen` liga `aria-haspopup` e
+    `aria-expanded`. No Vue o slot é `#user-menu`.
+  - A lupa e a seta do usuário usam o objeto do ícone: aparecem sem
+    `library.add` no app.
+  - Em larguras apertadas a barra não passa mais do contêiner: a navegação é
+    cortada, a busca encolhe e o nome do usuário ganha reticências.
+
+- 80b417c: feat(attachmentcard): cartão de anexo com tipo de documento e conferência
+
+  Componente novo. Substitui a miniatura de PDF solta dos despachos, que só
+  mostrava o nome do arquivo: o cartão diz que documento aquele arquivo cumpre
+  (CNH, RG…), se é obrigatório e qual foi a situação da conferência.
+
+  Com `statusDetails`, o selo de situação abre o painel de conferência — o que foi
+  concluído e os dados extraídos, com botão de copiar por campo. Abre no hover sem
+  tirar o foco de onde está; no clique ou no teclado, fixa e leva o foco para
+  dentro. Com `onOpen`, o cartão inteiro abre o arquivo, com um único ponto de foco.
+
+- 93ad870: feat(combobox): campo de texto que filtra a lista enquanto se digita
+
+  Componente novo, extraído do autocomplete de usuários da 1Doc. A diferença para
+  o `Select` está em onde se digita: no `Select` o campo mostra o rótulo escolhido
+  e a busca mora dentro do dropdown; no `Combobox` o próprio campo é um `<input>`,
+  e a lista é sugestão do que está sendo digitado.
+
+  A caixa do campo é a do `Input` e a lista é a do `Select` — de propósito, para
+  não inventar anatomia nova. `allowCustomValue` aceita texto fora da lista;
+  `onInputChange` observa a digitação sem desligar o filtro local, que é o que a
+  presença de `onSearchChange` faz.
+
+- 92bf640: feat(campos): contrato de validação único, `readOnly` de verdade e rótulos localizáveis
+
+  **Os dez campos passam a falar a mesma língua.** `helperText` é o nome canônico
+  do texto de apoio; `Select`, `MultiSelect`, `Checkbox` e `Radio` chamavam de
+  `description`, que continua funcionando como apelido. E a dica agora fica
+  visível **junto** com o erro nos dez — `Select` e `MultiSelect` escondiam.
+
+  **`Checkbox.readOnly` funciona.** Era pior que prop fantasma: chegava ao
+  `<input>`, mas `readonly` não existe para checkbox em HTML, então o navegador
+  ignorava e o valor alternava assim mesmo. Agora tem guarda e `aria-readonly`, e
+  continua focável e enviado no submit — o que o distingue de `disabled`.
+
+  **`Input.mask` foi removida.** Estava declarada e nenhum código a lia. Máscara
+  de verdade (cursor, colar, apagar) é componente próprio, não prop. Nenhum
+  produto passava.
+
+  **40 rótulos fixos em português viraram 29 props com default**, em 12
+  componentes — `aria-label={props.closeLabel || "Fechar"}`. Quem não passa nada
+  continua vendo português.
+
+- 440201d: fix(drawer): a página de catálogo estava ilegível, e faltava o `inline`
+
+  Cada story do Drawer nascia aberta, e sem `inline` cada uma vira um overlay
+  `position: fixed` sobre a viewport inteira — várias na mesma página se
+  empilhavam e o catálogo virava um borrão de backdrops cortados.
+
+  O `Modal` já resolvia isso com uma prop `inline` ("renderiza sem fixed/overlay,
+  útil para documentação"). O Drawer não tinha. Agora tem, com o mesmo nome e o
+  mesmo motivo.
+
+- 74a549f: feat(drawer): painel que entra por uma borda lateral, por cima do conteúdo
+
+  Componente novo, extraído da gaveta do assistente e do painel de tarefas da
+  1Doc. É o irmão do `BottomSheet` em outra borda, de propósito: mesma pilha de
+  overlay, mesma camada, mesmo backdrop, mesmo trap de foco, mesmos nomes de prop.
+
+  Não confundir com o `SidePanel`, que é mobília de layout — vive na tela, contrai
+  para um trilho e não tem backdrop.
+
+- 9143493: feat(grid): `equalHeight` deixa os cards de uma linha com a mesma altura
+
+  A célula do Grid já esticava, mas o card dentro dela não — cards lado a lado
+  ficavam com alturas diferentes. `<Grid container equalHeight>` faz o filho
+  único de cada item preencher a altura da linha. É opcional: ligado para todos,
+  um botão ou campo sozinho na célula esticaria junto.
+
+- 48f140b: feat(input): limites e passo no campo numérico, e o girador nativo escondido
+
+  `min`, `max` e `step` viram props do `Input`, e o botão nativo de girar do
+  `type="number"` passa a vir escondido por padrão (`numberSpinner` traz de
+  volta).
+
+  É o que a auditoria chamava de "NumberInput ausente". O produto já usa
+  `<Input type="number" min max>` em três telas e escondia o girador à mão no CSS
+  de cada uma — o que faltava eram as props, não um componente novo com +/− que o
+  produto rejeitou.
+
+- 73dc06f: feat(modal): o modal base da 1Doc vira o padrão — três faixas, controles de janela e rodapé com região de apoio
+
+  O `Modal` tinha uma anatomia só, a do diálogo de feedback: tudo centralizado
+  numa coluna com `overflow-y: auto` em volta do conjunto. Como a rolagem
+  envolvia o cabeçalho e o rodapé, com conteúdo alto **o título subia e sumia e
+  os botões desciam e sumiam junto**.
+
+  Agora, sem `variant`, o `Modal` é o modal base da 1Doc — o "Criar Novo
+  Documento", medido em `NovoDocumentoModal.css`:
+
+  - **cabeçalho fixo** com título (16/700), subtítulo (12px) e divisor;
+  - **corpo**, o único que rola;
+  - **rodapé fixo** com divisor, sombra que o levanta, região de apoio à esquerda
+    e ações à direita.
+
+  Props novas:
+
+  - `windowControls` — restaurar · expandir · tela cheia · minimizar, antes do ×.
+    É tudo ou nada: ou o modal tem só o ×, ou o conjunto inteiro. Ligado, o modal
+    muda de tamanho sozinho (780px · 1120px · tela cheia).
+  - `onMinimize` — o clique no minimizar; só existe com `windowControls`.
+  - `footerStart` — a região esquerda do rodapé (a caixa "Urgente", um
+    "Selecionado: 0"). No Vue, o slot chama `footer-start`.
+
+  Sem `footerStart`, `footerSlot`, `confirmLabel` nem `cancelLabel`, não há
+  rodapé nem divisor.
+
+  **Muda a aparência de quem usa `<Modal>` sem `variant`**: era centralizado, passa
+  a ser alinhado à esquerda e com faixas. Os três de feedback (`positive`,
+  `negative`, `info`) e quem passa `layout="dialog"` continuam idênticos.
+
+- 6e917e6: feat(popover): painel flutuante ancorado, com conteúdo livre
+
+  Terceiro da família de flutuantes. A escolha entre os três é pelo que vai
+  dentro: o `Tooltip` carrega uma frase e abre no hover; o `Dropdown` carrega uma
+  lista de ações e é navegado por setas; o `Popover` carrega qualquer coisa — um
+  formulário de filtro, uma explicação com link — e por isso abre no clique e não
+  sequestra o teclado.
+
+  Usa a mesma máquina do `Dropdown` (Portal, `@floating-ui/dom`, `autoUpdate`) e a
+  mesma superfície do menu dele.
+
+- ebc09c5: feat(progress-bar): `tone="on-color"` para usar sobre superfície colorida
+
+  O rótulo e o valor tinham cor escura fixa e sumiam sobre um hero azul. Com
+  `tone="on-color"`, texto, trilha e preenchimento passam para as cores de
+  conteúdo sobre cor. As variáveis `--umds-progress-label-color`,
+  `--umds-progress-value-color` e `--umds-progress-track-color` permitem ajuste
+  fino sem mexer em classe interna. Sem a prop, nada muda.
+
+- a062984: feat(segmentedcontrol): escolha única entre poucas opções, lado a lado
+
+  Componente novo, extraído do seletor de itens por página da fila de tarefas da
+  1Doc. É um `RadioGroup` com outra apresentação, e a API é a mesma de propósito.
+
+  Por baixo são `<input type="radio">` de verdade compartilhando `name` — as setas
+  do teclado, o submit de formulário e a semântica de grupo vêm do navegador, não
+  de código.
+
+- f718568: feat(stat-card): `trendIntent` separa a cor da variação da direção da seta
+
+  Até aqui a cor da variação vinha da direção: `up` pintava de verde, `down` de
+  vermelho. Não havia como dizer "custo caiu 8%" (boa notícia, seta para baixo)
+  nem "dívida técnica subiu" (má notícia, seta para cima).
+
+  A prop nova `trendIntent` (`positive` | `negative` | `neutral`) define a cor;
+  `trend` continua definindo só a seta. Sem `trendIntent`, a cor segue a direção
+  exatamente como antes — nenhuma tela existente muda de pixel.
+
+- 08c7dc1: fix(tag): ícone clicável tem nome acessível também quando é objeto
+
+  O `aria-label` do ícone clicável só existia quando o ícone vinha como texto;
+  com o objeto do Font Awesome o botão ficava sem nome. Agora o nome sai do
+  ícone em qualquer formato, e as props novas `iconStartAriaLabel` e
+  `iconEndAriaLabel` permitem um rótulo de verdade (ex.: "Editar filtro").
+
+- afca360: feat(timeline): histórico de eventos numa trilha vertical
+
+  Componente novo, extraído do histórico de versões do processo e da timeline de
+  despachos da 1Doc.
+
+  A diferença para o `Stepper` é o tempo: o `Stepper` mostra um processo com
+  etapas futuras e existe para dizer quanto falta; a Timeline mostra o que já
+  aconteceu, cada evento com quando e por quem, e não tem etapa "pendente".
+
+  A geometria da trilha é a do `Stepper` vertical, não a do protótipo: os dois
+  componentes aparecem na mesma tela na 1Doc, e duas trilhas com medidas
+  diferentes lado a lado é a inconsistência que esta rodada existe para eliminar.
+
+### Patch Changes
+
+- 02eef38: fix(app-shell): o shell mede a própria altura e não depende mais do CSS da raiz
+
+  `.umds-app-shell` usava `height: 100%`. Sem `height: 100%` em `html`, `body` e
+  `#root`/`#app`, o shell crescia com o conteúdo: quem rolava era o `<body>`, e o
+  cabeçalho, a barra lateral e o rodapé da `AppSidebar` (com o botão de recolher)
+  saíam da tela — o contrário do que o componente promete.
+
+  A altura agora vem da custom property `--umds-app-shell-height`, que por padrão
+  é `100dvh` (com `100vh` para navegador sem `dvh`). Para embutir o shell num
+  contêiner de altura própria, defina `--umds-app-shell-height: 100%` nele ou num
+  ancestral. Quem já tinha o contorno `html, body, #root { height: 100% }` não
+  precisa mudar nada — e pode removê-lo.
+
+- 2364d02: fix(phoneinput): as bandeiras saem do `flagcdn.com` e passam a vir embutidas
+
+  O campo buscava a imagem da bandeira num serviço de terceiros em tempo de
+  execução. Se a rede corporativa bloqueia, a bandeira some; cada usuário que abre
+  o campo entrega o IP dele para fora; e não há contrato de disponibilidade.
+
+  As dez bandeiras agora vêm embutidas como data URI, 18 KB no total. Era a única
+  dependência externa em runtime que o DS tinha.
+
+- 7e73deb: fix(button): `startIcon`/`endIcon` aceitam o objeto do Font Awesome
+
+  Passar o ícone importado (`startIcon={faPlus}`) derrubava a tela no React
+  (erro #31): só o nome em texto passava pelo `Icon`, e o objeto caía cru no
+  slot. Agora texto, par `[prefixo, nome]` e objeto passam pelo `Icon`. Quem
+  passava um nó pronto continua funcionando.
+
+- 74244eb: fix(side-panel): o fechar e a busca aparecem sem registrar ícones no app
+
+  `SidePanel` (`xmark`) e `SidePanelSearch` (lupa) pediam o ícone pelo nome e
+  saíam vazios quando o app não chamava `library.add`. Agora usam o objeto.
+
+- 9ab7adc: fix(sidepanel): no Vue, o painel sem `open` nascia fechado e sem botão de fechar
+
+  `open` e `closable` eram tipadas `boolean`. O Vue aplica _boolean casting_: prop
+  booleana ausente chega como `false`, não como `undefined` — então
+  `props.open !== false` dava falso e o mesmo código abria expandido no React e
+  contraído no Vue. As duas passam a ser `any`, que é o remédio já registrado em
+  `.agent/troubleshooting/vue-boolean-prop-default.md`.
+
+  Achado pela esteira de regressão visual, comparando as stories dos dois
+  frameworks.
+
+  E, no mesmo componente: contraído, o painel saía da vista mas o **Tab continuava
+  entrando nos botões de dentro** (`aria-hidden-focus`, gravidade séria no axe).
+  Agora ele também recebe `visibility: hidden`, com 200ms de atraso para a
+  animação de largura continuar a mesma.
+
+## 2.5.0
+
+### Minor Changes
+
+- 5f916d7: **A moldura da 1Doc passa a ser a do produto, e não uma interpretação dela.**
+
+  O `AppHeader` e o `SidePanel` que saíram na 2.4.0 tinham sido desenhados a partir da ideia de "app shell". Comparados à 1Doc lado a lado, não tinham relação: faltavam o botão de ação principal, o campo de busca, o grupo de ações, o bloco do usuário com nome — e o painel lateral era uma lista de navegação, não os dois painéis que o produto tem.
+
+  Agora a anatomia e as medidas vêm do produto **rodando**, não do CSS lido.
+
+  **`AppHeader`** ganha a anatomia real: marca (via `Logo`), ação principal, navegação, busca, ações, assistente e bloco do usuário. **`AppHeaderAction`** (novo) é o botão de ícone do topo, com o contador sobreposto do sino — o contador some em `0`, porque "tem algo" sem número não ajuda a decidir se vale abrir.
+
+  **`SidePanel`** vira o que o produto tem: trilho de abas de 49px sempre visível, painel de 254px que anima a largura até zero, conteúdo trocando por aba. Acompanham **`SidePanelItem`** (linha contada), **`SidePanelSection`** (rótulo de grupo) e **`SidePanelSearch`** (busca do painel), que juntos montam tanto o painel da emissão quanto o da fila de tarefas.
+
+  **`Logo`**: a base das letras estava sendo recortada por ~1px. O `<svg>` tem `overflow: hidden` e o navegador arredonda a altura para 1/64px, deixando o desenho 0,01px maior que a caixa. Afetava todo lugar que usa o componente.
+
+  **Mudança visual esperada** em `AppHeader`, `AppNavItem` e `SidePanel`: eles passam a parecer a 1Doc. O `AppNavItem` perde o fundo no hover e o padding lateral que não existiam no produto.
+
+  Medida sem degrau na escala vai como literal comentado, com o valor do produto ao lado — é o que a regra 2 permite. Só **cor** continua sendo token obrigatório: as quatro do produto que o DS não tem (`#222222`, `#e1e3e6`, `#edf2ff`, `#0046b5`) ficam no vizinho mais próximo.
+
+## 2.4.0
+
+### Minor Changes
+
+- fa15735: **App shell: `AppShell`, `AppHeader` e `AppSidebar`.**
+
+  Era a maior lacuna apontada pela auditoria interna — o padrão de layout da 1Doc estava escrito e mesmo assim cada produto o reconstruía do zero. Só no protótipo são ~1.000 linhas entre `App.tsx`, `Header.tsx`, `Subheader.tsx` e CSS.
+
+  - **`AppShell`** — a moldura. Cabeçalho e barra não rolam; só o conteúdo rola. Traz as duas linhas que faltam em quase toda implementação manual: `min-height: 0` (sem ela a rolagem escapa para o body e o header "fixo" sobe junto) e `min-width: 0` (sem ela uma tabela larga empurra o layout inteiro).
+  - **`AppHeader`** — barra de 56px com marca, navegação e ações. O que vai dentro é do produto.
+  - **`AppSidebar`** — 48px fechada, 248px aberta. Com a barra fechada o rótulo **continua no HTML**, só sai da vista: trocá-lo por um ícone solto deixaria a navegação muda para leitor de tela.
+
+  A geometria virou token (`--umds-semantic-shell-*`), então mudar o padrão de todos os produtos é editar um arquivo.
+
+  **Paridade com o protótipo: 16 de 22 medidas batem exatamente.** As 6 restantes não têm valor exato na escala do DS — nos casos de espaço e tamanho, os dois degraus vizinhos ficam à mesma distância do protótipo, e bater com ele exigiria inventar token. A regra aplicada foi cor e medida sempre 100% do design system, escolhendo o valor mais próximo. A conta é refeita com `node scripts/verifica-paridade-shell.mjs`.
+
+- 2a86d8c: Três componentes novos na trilha **Preview**, para telas onde parte do conteúdo ou parte da decisão vem de um modelo:
+
+  - **`AILabel`** — selo de conteúdo gerado, com painel de explicabilidade que responde de onde veio, o que não entrou e o que fazer se estiver errado.
+  - **`AIContent`** — envolve conteúdo gerado. Quando o usuário edita, o tratamento de IA **sai**: a partir dali o texto é dele, e manter a marca atribuiria autoria errada. Mantém a ação de reverter para a sugestão.
+  - **`ConfirmAIAction`** — conteúdo para o `ConfirmDialog` quando a ação foi sugerida por IA. Escalona a confirmação pelo risco e lista o que será afetado. Cascata conta como risco alto mesmo com cada passo reversível.
+
+  Trilha Preview: a API pode mudar sem virar versão quebrada. O contrato de instabilidade está na página _Sobre o Preview_ do Storybook.
+
+- ab2f457: Contrato único de validação na família de campos: invalid + errorMessage + helperText
+- 2b78aca: Stack, Box e Container — as primitivas de layout que faltavam
+- 7c44c6d: **As peças que faltavam para reproduzir a tela da 1Doc:** `AppSubheader`, `SidePanel`, `AppNavItem` e `StatCard`, somadas ao `AppShell`, `AppHeader` e `AppSidebar`.
+
+  Levantadas medindo o protótipo, não por suposição: o `SidePanel` tem 254px porque é o número do protótipo, o mesmo na Emissão e nas Tarefas; o `AppSubheader` tem 42px pelo mesmo motivo. Toda a geometria virou token `--umds-semantic-shell-*`.
+
+  - **`AppNavItem`** — o item da navegação horizontal do topo: rótulo, contador e seta. O contador aceita `badgeLabel`, porque "9" sozinho não diz nada a quem usa leitor de tela.
+  - **`AppSubheader`** — a barra de contexto: trilha à esquerda, setor e ações à direita.
+  - **`SidePanel`** — o painel lateral **da tela** (histórico, filtros), que fecha animando a largura até zero. Não confundir com `AppSidebar`: na 1Doc a navegação do app é horizontal, e o que fica à esquerda é sempre um destes.
+  - **`StatCard`** — cartão de indicador. A variação vem com seta, não só com cor.
+
+  **Correção junto:** `Input.iconLeft` e `InputAction.icon` renderizavam o valor cru quando não era string. Como as props são tipadas `IconProp`, passar o objeto importado do Font Awesome derrubava a tela no React (erro #31). Agora vão sempre pelo `Icon`, que resolve string, tupla e objeto.
+
+### Patch Changes
+
+- 34decba: Alvos de toque de 24px e o X do Chips visível nas variantes negative e info
+- 637c60c: **`DataTable`: a linha clicável deixa de se anunciar como botão.**
+
+  Com `onRowClick`, a linha recebia `role="button"`. Isso causava dois problemas: o role substituía `row` e derrubava a navegação de grade do leitor de tela — a pessoa deixava de percorrer a tabela célula a célula; e, junto com `selectable`, a linha "botão" passava a conter o checkbox de seleção, aninhando dois controles interativos.
+
+  O `tabIndex` continua: quem navega por teclado alcança a linha e Enter/Espaço acionam, igual a antes. O que muda é só o anúncio — que, dentro de uma tabela, já estava errado.
+
+- 2bc13c1: Três falhas de comportamento apontadas pela auditoria interna, todas verificadas na tela:
+
+  - **`DataTable`** — com `selectable` e `onRowClick` juntos, o Espaço dentro do checkbox era engolido pelo `preventDefault` do handler da linha e acionava a linha inteira: marcar por teclado era impossível. O caminho do mouse já tinha a guarda equivalente; só o teclado ficou de fora.
+  - **`DatePicker`** — o foco nunca entrava no painel. `ArrowDown` abria o calendário e o teclado ficava inerte, porque o painel vive num Portal e o Tab a partir do gatilho ia para o resto da página. O alvo do foco passou a ser o dia marcado pelo roving tabindex, que é a verdade do DOM no instante em que o frame roda — o seletor anterior lia um valor de estado da closure do render anterior, que ao abrir ainda era o antigo.
+  - **`BottomSheet`** — o listener global de `keydown` era registrado a cada montagem e nunca removido, acumulando ao trocar de tela, em StrictMode e em navegação por rotas. Junto, o id da instância passou a ser gerado no inicializador: um painel que montasse já com `open=true` registrava id vazio na pilha de overlays e o Esc não fechava.
+
+- 188db4a: Tag: conteúdo passado entre as tags (`children`) voltou a renderizar no Vue.
+
+  `{props.label || props.children}` funciona no React e não no Vue: o Mitosis traduz `props.children` para `$slots.default` e o template gerado vira `{{ label || $slots.default }}` — interpolação do objeto de slots em vez de renderização do slot. `<Tag>texto</Tag>` aparecia no React e sumia no Vue, sem erro.
+
+  Trocado por `Show`/`else` com `Slot`, que é o idioma que o Mitosis traduz corretamente nos dois alvos (mesmo padrão já usado no `Icon`).
+
+## 2.3.0
+
+### Minor Changes
+
+- fe70f80: BottomNavigation: componente novo — Tabs não serve para bottom-nav sem sobrescrever classes internas (indicador
+  embaixo, sem ícone acima do label, itens sem flex:1). Componente próprio:
+  ícone acima do label, indicador no TOPO do item ativo, alvos >=44px, fixed
+  com safe-area do notch.
+- 2940c64: Componente `BottomSheet`: painel inferior com alça, encaixes opcionais e arraste, consumindo a mesma pilha de overlays, camada e backdrop do `Modal`.
+- 1edf7be: DataTable: componente novo — column.render(row, index) oficializa células ricas (antes só funcionava por contrato não documentado); rowKey + selectedKeys/onSelectKeys para seleção estável entre páginas e ordenações; density=compact; onRowClick; ícones de ordenação e vazio como objeto FA.
+- ca794cc: DatePicker: componente novo — Ícones calendário/chevrons como objeto FA; anéis de foco/erro via color-mix (seguem a marca e o dark); modo touch.
+- 6f72387: Empacotamento: `utils/toast` e `utils/density` passam a ser exportados pelo índice dos pacotes (antes o código existia mas não havia como importar). `sideEffects: ["**/*.css"]` para o bundler do consumidor não descartar os estilos, mapa de `exports` com subpath `./utils/*` e `@1doc/1ds-tokens` promovido a peerDependency.
+- 3d69114: FileInput: componente novo — prop name: os File selecionados/arrastados ficam no input nativo (DataTransfer) e entram no FormData — era o único campo fora do submit; ícones como objeto FA.
+- 4688b99: Input: errorMessage/helperText com ids estáveis e aria-describedby; anéis de foco/erro via color-mix; fonte >=16px em telas <=640px (evita o zoom automático do Safari iOS); ícones olho/ações como objeto FA; min-height 44px no modo touch.
+- e8a8c93: Link: Paridade UX.
+- 191d211: MCP e catálogo do Storybook passam a dizer QUANDO usar cada componente, não só o que ele faz
+- 8390232: Modal: size sm|md|lg|fullscreen (era fixo em 498px); layout=content (texto à esquerda, footer à direita) para formulários e wizards; corpo rolável (overflow:clip cortava o wizard e escondia o footer); Esc integrado à pilha de overlays + closeOnEsc; superfície elevada; ícone info em feedback-info-dark.
+
+  Mantém `variant="success"|"error"|"warning"` como aliases depreciados de `positive`/`negative`/`info` — quem já usa os nomes antigos não quebra.
+
+- 1dfb2c2: MultiSelect: componente novo — role=listbox só no container das options (busca e rodapé não são filhos válidos); checkbox das options decorativo; value/onChange tipados; hover do remover e anéis via color-mix; modo touch.
+- 2992d54: PageHeader: componente novo — size=sm (título 24→18px) para headers compactos/mobile; chevron do breadcrumb como objeto FA.
+- 1bd877e: Pagination: componente novo — Cinco variantes (default com campo de página, alternative, resumed, full-width, bordered); texto "de" com contraste AA; chevrons como objeto FA; alvos 44px no modo touch. BREAKING: o layout numerado antigo corresponde a variant="full-width".
+- 81cdee5: PhoneInput: componente novo — errorMessage/helperText com aria-describedby (era o único campo sem); hidden input {name}\_ddi — o FormData levava só o número local e o país se perdia; painel portalado; fonte 16px em mobile; ícones como objeto FA.
+- 965037b: Select: Label visível vira nome acessível do combobox (aria-labelledby); value/onChange tipados; anéis via color-mix; fonte 16px em mobile; ícones como objeto FA; modo touch.
+- 972cb57: Stepper: componente novo — Título do passo pendente com contraste AA; ícones check/xmark como objeto FA.
+- 10cc624: Switch: checked tipado como boolean; slots iconChecked/iconNotChecked declarados; glifos proporcionais; ícones como objeto FA.
+- bc7873f: Tabs: A linha-guia do tablist virou background interno: o indicador da aba ativa a cobre por completo (com border no container, e tablist rolável, isso era impossível); overflow-x auto (labels nowrap transbordavam em 375px); Tab.icon documentado como Font Awesome.
+- 9bb944b: Tag: variant semântico neutral|primary|positive|negative|info (paridade com o Badge) — tag de status sem trocar de componente; ícone de fechar como objeto FA.
+
+  Mantém `variant="outlined"|"solid"` aceito como aparência (era o significado antigo da prop) — quem já usa não quebra.
+
+- 5287da5: Textarea: Anéis de foco/erro via color-mix; fonte >=16px em telas <=640px; autoSize e contador.
+- b7bcdb5: TimePicker: componente novo — Anéis via color-mix; ícones relógio/chevrons como objeto FA; literais de handler movidos para métodos do store (aspas inline quebram a geração Vue); modo touch.
+- 600a198: Toast: componente novo — ToastStack + fila imperativa (mensagens em sequência se atropelavam e cada app reinventava o host); prop portalContainer; description sem opacity (reprovava AA); ícones como objeto FA.
+- cb4ce56: Tooltip: Seta estática nas 12 posições side×align, CSS próprio, content aceita ReactNode.
+- acdbae1: Componente `Tree`: hierarquia com expansão, seleção (simples, múltipla e em cascata opcional), teclado APG com foco roving e conteúdo da linha por `renderItem`.
+
+## 2.2.0
+
+### Minor Changes
+
+- e4a801b: Accordion: componente novo — Ícone chevron importado como objeto FA (renderizava vazio sem library.add no app do consumidor); content aceita ReactNode (era string, e rejeitava o JSX que já funcionava em runtime).
+- 9ef86c4: Alert: Ícones de variante e fechar importados como objeto FA; hover do close revisado.
+
+  Mantém a prop `type` (success/error/warning) e `variant="soft"|"solid"` como aliases depreciados — a API antiga continua compilando.
+
+- adb399c: Avatar: Paridade visual UX + AvatarGroup.
+- 15401a6: Badge: Variantes solid/soft/outlined com contraste AA.
+
+  Atributos HTML (`style`, `data-*`, `aria-*`, `title`, `role`, `tabIndex`) voltam a chegar ao elemento raiz, agora por spread filtrado — props do componente nao vazam mais como atributo invalido no DOM.
+
+- 4c21e5f: Breadcrumb: componente novo — Getter no store para o For (expressão binária quebra a geração Mitosis).
+- 8b150de: Button: Interface de props alinhada aos demais componentes (aceita data-_/aria-_ declarados); spinner com faRefresh já importado como objeto; min-height 44px no modo touch.
+- ac954b5: Card: componente novo — Implementação de referência do plano de porte (padrão-ouro): variantes, elevação e composição por slots.
+- 2ef27b9: Checkbox: errorMessage com aria-describedby (antes só invalid, e a mensagem ficava fora do componente); modo decorative (sem input nativo) para indicadores dentro de widgets com semântica própria; readOnly/tabIndex declarados; label do success com contraste AA no variant background; ícones check/minus como objeto FA.
+- 18b6c2a: Chips: componente novo — onClick + selected (filter chip com aria-pressed e botão real, sem nested-interactive); ícone xmark como objeto FA.
+- 0d604b5: ConfirmDialog: componente novo — Camada acima do Modal (empatava em layer-modal e a ordem no DOM decidia quem aparecia); Esc via pilha de overlays + prop closeOnEsc; hover do botão info derivado por color-mix (era hex cru #7a3909, único do dist); ícone info em feedback-info-dark (o pure reprovava 3:1); superfície elevada.
+- db42a2d: Core: utilitários novos — `registerTheme()` (aceita tema de marca própria, white-label), `setDensity()` (modo touch global com alvos ≥44px), pilha de overlays (só o diálogo do topo reage a Esc) e fila imperativa de toasts (`toast()`, `dismissToast()`, `subscribeToasts()`). Build: dedup dos blocos JSDoc que o gerador Mitosis re-emitia duplicados nos pacotes publicados.
+- 08f82d3: Divider: Paridade UX.
+- 8a201d5: Dropdown: componente novo — Wrapper do trigger só recebe role/tabindex/aria quando o conteúdo NÃO é interativo — passar um Button (caso típico) gerava botão dentro de botão; ícones dos itens como objeto FA.
+- 9f62f77: EmptyState: componente novo — icon aceita IconProp (objeto FA) em vez de string de classes CSS — mecanismo unificado com o resto do DS.
+- 03ceb61: Grid: spacing tipado como união dos sufixos de token (string crua gerava var() inválida silenciosa).
+
+  Atributos HTML (`style`, `data-*`, `aria-*`) voltam a ser repassados ao elemento raiz, como na versão anterior — a remoção do spread os tornava aceitos na tipagem e ignorados na renderização.
+
+  Atributos HTML (`style`, `data-*`, `aria-*`, `title`, `role`, `tabIndex`) voltam a chegar ao elemento raiz — a remoção do spread os tornava aceitos na tipagem e ignorados na renderização. O spread agora é filtrado, então props do componente não vazam mais como atributo inválido no DOM.
+
+- 79175ba: Icon: Base do contrato: aceita objeto IconDefinition (recomendado), nome registrado ou par [prefix, name].
+- 1c17f08: Logo: currentColor (sem cor inline).
+
+  Atributos HTML (`style`, `data-*`, `aria-*`) voltam a ser repassados ao elemento raiz, como na versão anterior — a remoção do spread os tornava aceitos na tipagem e ignorados na renderização.
+
+  Atributos HTML (`style`, `data-*`, `aria-*`, `title`, `role`, `tabIndex`) voltam a chegar ao elemento raiz — a remoção do spread os tornava aceitos na tipagem e ignorados na renderização. O spread agora é filtrado, então props do componente não vazam mais como atributo inválido no DOM.
+
+- d308db9: Portal: prop container (shadow DOM, dialogs nativos, containers de scroll próprios).
+- 27e6c41: ProgressBar: componente novo — Paridade UX.
+- 47267c4: Radio: errorMessage com aria-describedby e aria-invalid; checked tipado como boolean.
+- 518dc54: RadioGroup: componente novo — Montar grupo à mão exigia amarrar checked/onChange item a item e criar
+  role="radiogroup" manualmente — e o modo não-controlado de radios soltos é
+  terreno de bug conhecido. RadioGroup resolve: value/onChange (ou defaultValue),
+  name compartilhado (submit nativo + setas do navegador), direção, errorMessage
+  de grupo com aria-describedby.
+- 8c3032f: Skeleton: Paridade UX.
+- 59db0a5: Spinner: Reexcluído do bloco global de prefers-reduced-motion (o giro é a informação).
+
+  Atributos HTML (`style`, `data-*`, `aria-*`) voltam a ser repassados ao elemento raiz, como na versão anterior — a remoção do spread os tornava aceitos na tipagem e ignorados na renderização.
+
+  Atributos HTML (`style`, `data-*`, `aria-*`, `title`, `role`, `tabIndex`) voltam a chegar ao elemento raiz — a remoção do spread os tornava aceitos na tipagem e ignorados na renderização. O spread agora é filtrado, então props do componente não vazam mais como atributo inválido no DOM.
+
+- b615cab: Text: Media queries alinhadas aos tokens de breakpoint (usava a escala Bootstrap, divergente do Grid: tipografia e colunas quebravam em larguras diferentes).
+
+  Mantém `color="error"` como alias depreciado de `"negative"`: Input, Select e
+  Textarea ainda passam o nome antigo, e o `tsc` do pacote gerado falha sem ele.
+
+  Atributos HTML (`style`, `data-*`, `aria-*`) voltam a ser repassados ao elemento raiz, como na versão anterior — a remoção do spread os tornava aceitos na tipagem e ignorados na renderização.
+
+  Atributos HTML (`style`, `data-*`, `aria-*`, `title`, `role`, `tabIndex`) voltam a chegar ao elemento raiz — a remoção do spread os tornava aceitos na tipagem e ignorados na renderização. O spread agora é filtrado, então props do componente não vazam mais como atributo inválido no DOM.
+
+### Patch Changes
+
+- 6ae6955: Espaçamentos do `Badge` passam a usar os primitivos de espaço em vez de literais.
+- ee4c39a: Foco canônico (outline em `primary-pure`) e espaçamentos em token no `Checkbox`.
+- 009944f: Animação da `ProgressBar` passa de listras com branco fixo para varredura de gradiente que acompanha o tema.
+- b132637: Geometria do `Radio` conforme o Figma (12/14/16px com `border-box`), foco canônico e token circular.
+- 34a8405: O raio circular do `Skeleton` passa a usar o token em vez de `50%`.
+- a65bf9a: O raio circular do `Spinner` passa a usar o token em vez de `50%`.
+- Updated dependencies [eccc44b]
+- Updated dependencies [6e16218]
+  - @1doc/1ds-tokens@0.2.0
+
+## 2.1.0
+
+### Minor Changes
+
+- e51ee6f: ---
+
+  "@1doc/1ds-core": minor
+  "@1doc/1ds-react": minor
+  "@1doc/1ds-vue": minor
+
+  ***
+
+  Adiciona o componente `Portal` e corrige o Tooltip.
+
+  **Portal (novo):** componente que move seu conteúdo para `document.body`. No React/Solid/Svelte usa `appendChild`; no Vue é convertido para `<Teleport to="body">` no post-build. Serve de base para componentes flutuantes (tooltip, e futuros modal/dropdown).
+
+  **Tooltip (correção):** deixa de ser cortado por containers com `overflow: hidden` e elimina o erro `Cannot read properties of null (reading 'insertBefore')` no Vue ao fechar. O posicionamento passou a usar `@floating-ui/dom` (`offset`, `flip`, `shift`, `arrow`) e o conteúdo é renderizado via `Portal`. Também corrige o flicker no hover rápido.
+
+## 1.0.0
+
+### Major Changes
+
+- 445de52: feat(icon): nova API dinâmica, remoção do Font Awesome Pro e tipagem extensível
+
+  **Breaking change** — a prop `name` foi removida do `<Icon>`. Use `icon` no lugar, que aceita três formatos:
+
+  - string: `<Icon icon="home" />`
+  - tupla `[prefix, iconName]`: `<Icon icon={["fas", "home"]} />`
+  - objeto `IconLookup` (ex.: `<Icon icon={faHome} />`)
+
+  **Novas props:**
+
+  - `transform`: aceita string (parseada via `faParse.transform`) ou objeto `Transform` do FA core.
+  - `mask` / `maskId`: ícone de máscara (suporta os mesmos formatos de `icon`).
+  - `symbol`: cria `<symbol>` reutilizável (`FaSymbol` do FA core).
+  - `customSize`: tamanho livre em CSS (`"32px"`, `"2rem"`) que sobrescreve `size`.
+
+  **Type augmentation:** o tipo `IconKit` é exportado vazio por padrão (fallback para `FaIconLookup`). Projetos consumidores podem restringir os ícones tipados via `declare module`:
+
+  ```ts
+  declare module "@1doc/1ds-react" {
+    interface IconKit {
+      prefix: "fas" | "far";
+      iconName: "user" | "home" | "gear";
+    }
+  }
+  ```
+
+### Minor Changes
+
+- Adiciona o componente Tooltip para React e Vue, com suporte a título, conteúdo, ícone, posicionamento configurável (side: top/bottom/left/right, align: start/center/end), delay de abertura e estado desabilitado.
+
+## 0.0.2
+
+### Patch Changes
+
+- Updated dependencies
+  - @1doc/1ds-tokens@0.1.0