fokus-styles 2.5.0 → 2.6.0

package/docs/components/collapse.md

@@ -1,78 +0,0 @@
-# Collapse
-
-Expande/recolhe um painel com transição de altura animada — primitivo
-usado internamente por [Accordion](accordion.md); use direto quando quiser
-só um "mostrar mais" sem a semântica de grupo do Accordion.
-
-## Visão geral
-
-```html
-<button type="button" class="fs-btn" data-fs="collapse" data-fs-target="#detalhes">
-  Ver detalhes
-</button>
-<div class="fs-collapse" id="detalhes">
-  Conteúdo que expande/recolhe.
-</div>
-```
-
-## Anatomia
-
-Gatilho (`data-fs="collapse"` + `data-fs-target`) + `.fs-collapse`
-(precisa de `overflow: hidden`, já incluso na classe — não remova via CSS
-próprio, quebra a animação de altura).
-
-## Variações
-
-Nenhuma — sem tamanho/cor; é um comportamento, não um estilo visual
-próprio (o conteúdo interno usa suas próprias classes).
-
-## Estados
-
-Estado inicial definido por `aria-expanded` no gatilho: `"true"` começa
-aberto, ausente ou `"false"` começa fechado.
-
-```html
-<button type="button" class="fs-btn" data-fs="collapse" data-fs-target="#painel" aria-expanded="true">
-  Recolher
-</button>
-```
-
-## A11y
-
-`aria-controls`/`aria-expanded` no gatilho são sincronizados
-automaticamente pelo JS a cada `show()`/`hide()`.
-[`prefers-reduced-motion: reduce`](../guides/accessibility.md#prefers-reduced-motion)
-pula a animação e aplica o estado final direto.
-
-## API JS
-
-Auto-init via `data-fs="collapse"` **no gatilho**. `Collapse.getInstance(triggerEl)`.
-
-| Método | Descrição |
-|---|---|
-| `show()` | Expande com animação de altura. |
-| `hide()` | Recolhe com animação de altura. |
-| `toggle()` | Alterna (é o que o clique no gatilho já faz). |
-| `dispose()` | Remove o listener de clique e desregistra a instância. |
-
-| Evento (no gatilho) | Cancelável | Quando |
-|---|---|---|
-| `fs:collapse:shown` | Não | Depois que a animação de expandir termina. |
-| `fs:collapse:hidden` | Não | Depois que a animação de recolher termina. |
-
-## Tokens
-
-Nenhum próprio — o conteúdo interno usa suas próprias cores/espaçamento.
-
-## Exemplo
-
-```html
-<button type="button" class="fs-btn fs-btn-outline-secondary" data-fs="collapse" data-fs-target="#mais-info">
-  Mais informações
-</button>
-<div class="fs-collapse" id="mais-info">
-  <p class="fs-u-mt-2">Texto adicional que só aparece quando expandido.</p>
-</div>
-```
-
-Mockup: [laboratório do componente](../../mockup/navigation-disclosure.html#collapse).

package/docs/components/combobox.md

@@ -1,123 +0,0 @@
-# Combobox / Autocomplete
-
-Um `<input>` de texto com uma listbox de sugestões que filtra conforme o
-usuário digita — diferente do [Select](select.md) (que troca a aparência
-de um `<select>` inteiro), o Combobox é sempre texto livre com sugestões,
-seguindo o padrão [WAI-ARIA Combobox (List Autocomplete)](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/).
-Reusa `packages/fokus-js/js/core/positioning.js` (mesmo posicionamento do [Dropdown](dropdown.md))
-e a classe `.fs-dropdown-menu`/`.fs-dropdown-item` para a listbox flutuante.
-
-## Visão geral
-
-```html
-<div class="fs-combobox">
-  <input type="text" class="fs-form-control" data-fs="combobox" data-fs-target="#lista-frameworks" placeholder="Buscar framework…">
-</div>
-<ul class="fs-dropdown-menu fs-combobox-listbox" id="lista-frameworks">
-  <li class="fs-dropdown-item" data-value="bootstrap">Bootstrap</li>
-  <li class="fs-dropdown-item" data-value="tailwind">Tailwind CSS</li>
-  <li class="fs-dropdown-item is-disabled" data-fs-empty hidden>Nenhum resultado encontrado.</li>
-</ul>
-```
-
-O JS reanexa a listbox a `document.body` (igual ao Dropdown/Select — evita
-recorte por `overflow: hidden` de um ancestral) e a posiciona relativa ao
-input. O item com `data-fs-empty` é opcional, mas recomendado: o
-componente alterna a visibilidade dele automaticamente quando nenhuma
-opção corresponde à busca — o texto dele é escrito por você (o framework
-não injeta texto/idioma).
-
-## Anatomia
-
-`.fs-combobox` (wrapper posicionador) > `input[role="combobox"]` +
-`.fs-dropdown-menu.fs-combobox-listbox[role="listbox"]` > um ou mais
-`.fs-dropdown-item[role="option"]`.
-
-## Variações
-
-- `data-value` em cada `.fs-dropdown-item` define o valor "de verdade"
-  (`instance.value`); sem ele, o valor é o texto visível do item.
-- Item desabilitado: `.fs-dropdown-item.is-disabled` — ignorado por
-  teclado, mouse e pelo filtro de "opções selecionáveis".
-- Item de "sem resultados": `.fs-dropdown-item.is-disabled[data-fs-empty]`,
-  `hidden` por padrão — visibilidade alternada automaticamente pelo JS.
-
-## Estados
-
-- Digitar filtra as opções por substring (case-insensitive) — as que não
-  correspondem recebem o atributo `hidden` (removidas da árvore de
-  acessibilidade junto, não só visualmente).
-- Campo vazio mostra a lista completa (sem filtro).
-- Opção destacada durante a navegação por teclado: `.is-active` (visual
-  idêntico ao item ativo do Dropdown/Select).
-- Opção escolhida: `aria-selected="true"` (só nela; as demais voltam a
-  `"false"`).
-
-## A11y
-
-`role="combobox"` + `aria-autocomplete="list"` + `aria-controls` +
-`aria-expanded` no input, `role="listbox"` na lista, `role="option"` +
-`aria-selected` em cada item — todos aplicados automaticamente, com `id`
-gerado para quem não tiver um. O foco **nunca sai do input**: a opção
-destacada é comunicada via `aria-activedescendant` (não `focus()`), como o
-padrão ARIA de combobox exige — por isso as opções não são elementos
-focáveis (`<li>`/`<div>`, não `<button>`).
-
-Teclado (com foco no input):
-- `ArrowDown`/`ArrowUp`: abre a listbox (se fechada) ou move o destaque
-  entre as opções selecionáveis, com wrap.
-- `Home`/`End`: vai pra primeira/última opção selecionável (listbox
-  aberta).
-- `Enter`: seleciona a opção destacada (se houver e a listbox estiver
-  aberta) — preenche o input, fecha a listbox.
-- `Escape`: fecha a listbox **sem** alterar o valor do input.
-
-## API JS
-
-Auto-init via `data-fs="combobox"` **no `<input>`**, com `data-fs-target`
-apontando pro seletor da listbox (convenção idêntica ao Dropdown).
-`Combobox.getInstance(inputEl)`.
-
-| Método | Descrição |
-|---|---|
-| `show()` | Abre a listbox e posiciona relativa ao input. |
-| `hide()` | Fecha a listbox, limpa o destaque e `aria-activedescendant`. |
-| `toggle()` | Alterna. |
-| `dispose()` | Fecha se aberto, remove listeners, desregistra a instância. |
-
-| Propriedade | Descrição |
-|---|---|
-| `value` | Valor da opção selecionada (`data-value` do item, ou o texto visível se não houver). `null` até a primeira seleção. |
-
-| Evento (no input) | Cancelável | Quando |
-|---|---|---|
-| `change` (nativo) | Não | Ao selecionar uma opção (clique ou `Enter`). |
-| `fs:combobox:changed` | Não | Mesmo momento, com `event.detail.value`/`event.detail.label`. |
-| `fs:combobox:shown` | Não | Depois de abrir a listbox. |
-| `fs:combobox:hidden` | Não | Depois de fechar. |
-
-## Tokens
-
-Os mesmos do [Dropdown](dropdown.md) (`.fs-dropdown-menu`/`.fs-dropdown-item`)
-e de [`.fs-form-control`](input.md) — sem tokens próprios. `.fs-combobox-listbox`
-soma `max-height: 240px` + scroll interno para listas longas.
-
-## Exemplo
-
-```html
-<div class="fs-combobox">
-  <input type="text" class="fs-form-control" id="cidade" data-fs="combobox" data-fs-target="#cidade-lista" placeholder="Buscar cidade…">
-</div>
-<ul class="fs-dropdown-menu fs-combobox-listbox" id="cidade-lista">
-  <li class="fs-dropdown-item" data-value="sp">São Paulo</li>
-  <li class="fs-dropdown-item" data-value="rj">Rio de Janeiro</li>
-  <li class="fs-dropdown-item is-disabled" data-fs-empty hidden>Nenhuma cidade encontrada.</li>
-</ul>
-<script>
-  document.getElementById("cidade").addEventListener("fs:combobox:changed", (e) => {
-    console.log("cidade escolhida:", e.detail.value);
-  });
-</script>
-```
-
-Mockup: [laboratório do componente](../../mockup/forms.html#combobox).

package/docs/components/command-palette.md

@@ -1,131 +0,0 @@
-# Command Palette
-
-Um diálogo de busca/comandos disparado por um botão ou por um atalho de
-teclado global (ex.: `Ctrl+K`/`Cmd+K`) — combina o overlay/focus trap do
-[Modal](modal.md) com o filtro/navegação por teclado do [Combobox](combobox.md).
-Reusa `.fs-dropdown-item`/`.is-active`/`.is-disabled` (mesmas classes do
-[Dropdown](dropdown.md)) para os itens da lista de comandos.
-
-## Visão geral
-
-```html
-<button type="button" class="fs-btn" data-fs="command-palette" data-fs-target="#paleta" data-fs-shortcut="mod+k">
-  Comandos (Ctrl+K)
-</button>
-
-<div class="fs-command-palette" id="paleta">
-  <div class="fs-command-palette-dialog">
-    <input type="text" class="fs-command-palette-input" placeholder="Digite um comando…">
-    <ul class="fs-command-palette-list">
-      <li class="fs-dropdown-item" data-value="new-file">Novo arquivo</li>
-      <li class="fs-dropdown-item" data-value="open-settings">Abrir configurações</li>
-      <li class="fs-dropdown-item is-disabled" data-fs-empty hidden>Nenhum comando encontrado.</li>
-    </ul>
-  </div>
-</div>
-```
-
-Auto-init em `data-fs="command-palette"` **no botão gatilho**, com
-`data-fs-target` apontando pro painel (convenção idêntica ao Modal). O
-painel não precisa estar pré-posicionado — é um overlay de tela cheia,
-como o Modal. `data-fs-shortcut="mod+k"` é opcional: quando presente,
-registra um atalho de teclado global (`mod` = Ctrl no Windows/Linux, Cmd
-no Mac) que abre/fecha o painel de qualquer lugar da página, sem precisar
-clicar no botão.
-
-## Anatomia
-
-`.fs-command-palette[role="dialog"]` > `.fs-command-palette-dialog` >
-`input.fs-command-palette-input[role="combobox"]` +
-`ul.fs-command-palette-list[role="listbox"]` > um ou mais
-`li.fs-dropdown-item[role="option"]`.
-
-## Variações
-
-- `data-value` em cada `.fs-dropdown-item` define o valor "de verdade"
-  (`event.detail.value` no evento de seleção); sem ele, o valor é o texto
-  visível do item.
-- Item desabilitado: `.fs-dropdown-item.is-disabled` — ignorado por
-  teclado, mouse e pelo filtro.
-- Item de "sem resultados": `.fs-dropdown-item.is-disabled[data-fs-empty]`,
-  `hidden` por padrão — visibilidade alternada automaticamente pelo JS.
-- `.fs-dropdown-header` agrupa comandos por seção, igual ao Dropdown.
-- `data-fs-shortcut="mod+k"` (ou `options.shortcut` no construtor): aceita
-  combinações com `mod`/`shift`/`alt` + uma tecla, ex. `"mod+shift+p"`.
-
-## Estados
-
-- Ao abrir, o input é limpo e a lista completa (sem filtro) é exibida.
-- Digitar filtra os itens por substring (case-insensitive) — os que não
-  correspondem recebem o atributo `hidden`.
-- Primeiro item selecionável sempre começa destacado (`.is-active`),
-  pronto pra `Enter` imediato.
-- Selecionar um item fecha o painel e devolve o foco ao gatilho.
-
-## A11y
-
-`role="dialog"` + `aria-modal="true"` no painel, `role="combobox"` +
-`aria-autocomplete="list"` + `aria-controls`/`aria-expanded` no input,
-`role="listbox"` na lista, `role="option"` + `aria-selected` em cada item.
-Foco preso dentro do diálogo (`packages/fokus-js/js/core/focus.js`, mesmo mecanismo do
-Modal) enquanto aberto; scroll da página travado
-(`packages/fokus-js/js/core/overlay.js#lockScroll`). O foco **nunca sai do input** — a opção
-destacada é comunicada via `aria-activedescendant`, como no Combobox.
-
-Teclado (com foco no input, painel aberto):
-- `ArrowDown`/`ArrowUp`: move o destaque entre os comandos visíveis, com
-  wrap.
-- `Enter`: executa o comando destacado — dispara `fs:command-palette:selected`
-  e fecha.
-- `Escape`: fecha o painel sem selecionar nada.
-- `Tab`/`Shift+Tab`: preso dentro do diálogo (focus trap).
-
-## API JS
-
-Auto-init via `data-fs="command-palette"` no botão gatilho, com
-`data-fs-target` apontando pro painel. `CommandPalette.getInstance(triggerEl)`.
-
-| Método | Descrição |
-|---|---|
-| `show()` | Abre o painel, limpa o filtro e foca o input. |
-| `hide()` | Fecha o painel, libera o scroll, devolve o foco ao gatilho. |
-| `toggle()` | Alterna. |
-| `dispose()` | Fecha se aberto, remove listeners (incluindo o atalho global, se houver), desregistra a instância. |
-
-| Evento (no gatilho) | Cancelável | Quando |
-|---|---|---|
-| `fs:command-palette:selected` | Não | Ao selecionar um comando (clique ou `Enter`), com `event.detail.value`/`event.detail.label`. |
-| `fs:command-palette:shown` | Não | Depois de abrir o painel. |
-| `fs:command-palette:hidden` | Não | Depois de fechar. |
-
-## Tokens
-
-Os mesmos do [Modal](modal.md) (backdrop, `--fs-radius-md`,
-`--fs-shadow-lg`) e do [Dropdown](dropdown.md) para os itens — sem tokens
-próprios de cor.
-
-## Exemplo
-
-```html
-<button type="button" class="fs-btn" id="abrir-paleta" data-fs="command-palette" data-fs-target="#paleta-exemplo" data-fs-shortcut="mod+k">
-  Comandos (Ctrl+K)
-</button>
-
-<div class="fs-command-palette" id="paleta-exemplo">
-  <div class="fs-command-palette-dialog">
-    <input type="text" class="fs-command-palette-input" placeholder="Digite um comando…">
-    <ul class="fs-command-palette-list">
-      <li class="fs-dropdown-item" data-value="new-file">Novo arquivo</li>
-      <li class="fs-dropdown-item" data-value="open-settings">Abrir configurações</li>
-      <li class="fs-dropdown-item is-disabled" data-fs-empty hidden>Nenhum comando encontrado.</li>
-    </ul>
-  </div>
-</div>
-<script>
-  document.getElementById("abrir-paleta").addEventListener("fs:command-palette:selected", (e) => {
-    console.log("comando executado:", e.detail.value);
-  });
-</script>
-```
-
-Mockup: [laboratório do componente](../../mockup/overlays-commands.html#command-palette).

package/docs/components/datatable.md

@@ -1,173 +0,0 @@
-# DataTable
-
-Camada JS opcional sobre uma [Table](table.md) comum: ordenação por coluna,
-filtro por texto e paginação client-side, tudo sobre a marcação `<table>`
-semântica já existente — sem framework de dados, sem dependência externa.
-Reusa `.fs-table` para a tabela, `.fs-pagination`/`.fs-page-link` para o
-paginador (mesmas classes do [Pagination](pagination.md)) e
-`.fs-empty-state` para a lista vazia.
-
-## Visão geral
-
-```html
-<div class="fs-datatable" data-fs="datatable" data-fs-page-size="5">
-  <div class="fs-datatable-toolbar">
-    <input type="search" class="fs-form-control" data-fs-datatable-filter placeholder="Filtrar…">
-  </div>
-  <table class="fs-table fs-table-striped fs-table-hover">
-    <thead>
-      <tr>
-        <th scope="col" data-fs-sort="name">Nome</th>
-        <th scope="col" data-fs-sort="age">Idade</th>
-      </tr>
-    </thead>
-    <tbody>
-      <tr><td>Ana</td><td>35</td></tr>
-      <tr><td>Bruno</td><td>19</td></tr>
-    </tbody>
-  </table>
-  <div class="fs-empty-state" data-fs-datatable-empty hidden>
-    <p class="fs-empty-state-title">Nenhum resultado encontrado.</p>
-  </div>
-</div>
-```
-
-Auto-init em `data-fs="datatable"`, colocado no `<div>` que envolve
-toolbar/tabela/estados — não no `<table>` diretamente. O JS lê as linhas de
-`<tbody>` uma vez na inicialização; se a tabela for repovoada por fora
-(ex.: resposta de uma API), chame `instance.refresh()`.
-
-## Anatomia
-
-`.fs-datatable[data-fs="datatable"]` > opcionalmente `.fs-datatable-toolbar`
-(com `input[data-fs-datatable-filter]`) + `table.fs-table` (com
-`th[data-fs-sort]` no `<thead>`) + opcionalmente
-`[data-fs-datatable-empty]`/`[data-fs-datatable-loading]`/`[data-fs-datatable-error]`
-+ `nav[data-fs-datatable-pagination]` (criado automaticamente se ausente).
-
-## Variações
-
-- `data-fs-sort="chave"` num `<th>` o torna ordenável — o JS envolve o
-  conteúdo existente num `<button class="fs-datatable-sort-btn">`
-  automaticamente (não escreva o botão você mesmo).
-- `data-fs-sort-type="number"`, `"currency"` ou `"date"` no `<th>` ativa
-  comparação tipada; sem o atributo, a ordenação usa texto. Combine com
-  `data-fs-sort-value` quando o valor exibido for formatado.
-- `data-fs-sort-value` numa `<td>` define o valor usado pra ordenar aquela
-  célula, se for diferente do texto exibido (ex.: data ISO por trás de um
-  texto formatado, número por trás de um texto com símbolo).
-- `data-fs-page-size="N"` no elemento raiz define quantas linhas por
-  página (padrão: 10).
-- `[data-fs-datatable-filter]` — um `<input>` (dentro do elemento raiz)
-  que filtra por substring em qualquer célula da linha, case-insensitive.
-- `[data-fs-datatable-empty]` — bloco (tipicamente `.fs-empty-state`)
-  mostrado no lugar da tabela quando o filtro não encontra nenhuma linha.
-- `[data-fs-datatable-loading]` / `[data-fs-datatable-error]` — blocos
-  mostrados via `setLoading()`/`setError()` (ver API JS); nenhum dos dois é
-  obrigatório.
-- `[data-fs-datatable-pagination]` — se você quiser controlar onde o
-  paginador aparece, forneça o elemento; senão o JS cria um `<nav>` e
-  anexa ao final do elemento raiz.
-
-## Estados
-
-- **Vazio**: filtro sem correspondências — tabela ocultada,
-  `[data-fs-datatable-empty]` exibido (se fornecido; sem ele, a tabela só
-  fica com zero linhas visíveis).
-- **Carregando**: acionado por `instance.setLoading(true)` — tabela e
-  paginador ocultados, `[data-fs-datatable-loading]` exibido (tipicamente
-  linhas `.fs-skeleton-text`).
-- **Erro**: acionado por `instance.setError("mensagem")` — tabela e
-  paginador ocultados, `[data-fs-datatable-error]` exibido, com o texto
-  escrito em `[data-fs-datatable-error-message]` dentro dele (se existir).
-- Paginação: o `<nav>` só é exibido quando há mais de uma página.
-
-## A11y
-
-`aria-sort` (`"none"`/`"ascending"`/`"descending"`) em cada `<th>`
-ordenável, atualizado a cada clique — o botão interno recebe o clique/foco
-(padrão recomendado pelo
-[WAI-ARIA Table Sort](https://www.w3.org/WAI/ARIA/apg/patterns/table/examples/sortable-table/),
-`aria-sort` no `th`, ativação num elemento focável dentro dele). Células de
-dados usam roving `tabindex` (uma célula visível por vez com `tabindex="0"`,
-as demais `-1"`) pra navegação em grade sem tornar cada célula uma parada
-extra no Tab da página.
-
-Teclado (com foco numa célula do corpo da tabela):
-- `ArrowRight`/`ArrowLeft`/`ArrowUp`/`ArrowDown`: move o foco pra célula
-  vizinha (não cruza limites da página visível).
-- `Home`/`End`: primeira/última célula da linha atual.
-- `Ctrl+Home`/`Ctrl+End`: primeira célula da tabela / última célula da
-  última linha visível.
-
-Teclado (com foco no botão de ordenação do cabeçalho): `Enter`/`Espaço`
-ativam nativamente (é um `<button>`), ciclando
-ascendente → descendente → nenhuma.
-
-## API JS
-
-Auto-init via `data-fs="datatable"` no elemento raiz.
-`DataTable.getInstance(rootEl)`.
-
-| Método | Descrição |
-|---|---|
-| `sort(key, direction)` | Ordena pela coluna com `data-fs-sort="key"`. `direction`: `"asc"` \| `"desc"` \| `"none"`. |
-| `filter(query)` | Filtra por substring (aplica também no input, se houver um). |
-| `goToPage(page)` | Navega pra página (1-indexado, com clamp nos limites). |
-| `refresh()` | Relê as linhas de `<tbody>` do zero — use após repovoar a tabela por fora. |
-| `setLoading(bool)` | Alterna o estado de carregamento. |
-| `setError(mensagem \| null)` | Mostra (com mensagem) ou limpa (`null`) o estado de erro. |
-| `dispose()` | Remove listeners e desregistra a instância. |
-
-| Propriedade | Descrição |
-|---|---|
-| `sortKey` / `sortDirection` | Coluna e direção de ordenação atuais (`sortDirection`: `"asc"` \| `"desc"` \| `"none"`). |
-| `filterQuery` | Texto de filtro atual. |
-| `currentPage` / `pageCount` | Página atual e total de páginas (considerando o filtro). |
-| `rowCount` | Quantidade de linhas que correspondem ao filtro atual. |
-| `pageSize` | Linhas por página (lido de `data-fs-page-size`, ou 10). |
-
-| Evento (no elemento raiz) | Cancelável | Quando |
-|---|---|---|
-| `fs:datatable:sorted` | Não | Após ordenar, com `detail.key`/`detail.direction`. |
-| `fs:datatable:filtered` | Não | Após filtrar, com `detail.query`/`detail.matched`. |
-| `fs:datatable:paged` | Não | Após trocar de página, com `detail.page`/`detail.pageCount`. |
-
-## Tokens
-
-Reusa os tokens de [Table](table.md) e [Pagination](pagination.md) — sem
-tokens próprios de cor. `.fs-datatable-sort-btn` usa
-`var(--fs-color-muted)`/`var(--fs-color-text)` pro indicador de direção
-(↕/↑/↓).
-
-## Exemplo
-
-```html
-<div class="fs-datatable" data-fs="datatable" data-fs-page-size="3">
-  <div class="fs-datatable-toolbar">
-    <input type="search" class="fs-form-control" data-fs-datatable-filter placeholder="Filtrar por nome ou status…">
-  </div>
-  <table class="fs-table fs-table-striped">
-    <thead>
-      <tr>
-        <th scope="col" data-fs-sort="name">Nome</th>
-        <th scope="col" data-fs-sort="status">Status</th>
-      </tr>
-    </thead>
-    <tbody>
-      <tr><td>Ana</td><td>Ativo</td></tr>
-      <tr><td>Bruno</td><td>Inativo</td></tr>
-    </tbody>
-  </table>
-  <div class="fs-empty-state" data-fs-datatable-empty hidden>
-    <p class="fs-empty-state-title">Nenhum resultado encontrado.</p>
-  </div>
-</div>
-<script>
-  document.querySelector(".fs-datatable").addEventListener("fs:datatable:sorted", (e) => {
-    console.log("ordenado por", e.detail.key, e.detail.direction);
-  });
-</script>
-```
-
-Mockup: [laboratório do componente](../../mockup/content-data.html#datatable).

package/docs/components/datepicker.md

@@ -1,137 +0,0 @@
-# Datepicker / Timepicker
-
-Duas abordagens complementares: **CSS-only**
-(`<input type="date">`/`<input type="time">` nativo, só estilizado) para
-quem quer o seletor do próprio sistema operacional/navegador, e um
-**Datepicker JS customizado** (`.fs-datepicker`) para quando o design
-precisa de controle total sobre a aparência do calendário — os nativos não
-podem ser restilizados além de cor/borda/fonte do campo (o popup em si é
-chrome do navegador, fora do alcance de CSS).
-
-## Visão geral
-
-### CSS-only (`<input type="date">`/`"time"`)
-
-```html
-<input type="date" class="fs-form-control">
-<input type="time" class="fs-form-control">
-```
-
-Herdam `.fs-form-control` normalmente (borda, fundo, foco). A única
-correção específica do framework é o indicador nativo (ícone de
-calendário/relógio) no tema escuro — por padrão o navegador desenha um
-ícone escuro fixo, invisível sobre `--fs-color-surface` escuro; o FokusStyles
-aplica `filter: invert(1)` nele sob `[data-theme="dark"]`.
-
-### Datepicker customizado (JS)
-
-```html
-<div class="fs-datepicker">
-  <input type="text" class="fs-form-control" data-fs="datepicker" data-fs-target="#dp-entrega" placeholder="dd/mm/aaaa">
-</div>
-<div id="dp-entrega"></div>
-```
-
-O elemento apontado por `data-fs-target` é o painel do calendário — fica
-vazio no HTML, o JS constrói o cabeçalho (mês/ano + navegação) e a grade de
-dias dinamicamente a cada abertura/troca de mês. Se o `<input>` já tiver um
-valor em `dd/mm/aaaa` (formato de exibição, pt-BR), o Datepicker abre no mês
-correspondente com o dia já marcado como selecionado.
-
-## Anatomia
-
-`.fs-datepicker` (wrapper posicionador) > `input[role="combobox"]` +
-`.fs-datepicker-panel` (reanexado a `document.body`, posicionado via
-`packages/fokus-js/js/core/positioning.js`) > `.fs-datepicker-header` (`.fs-datepicker-nav` ×2 +
-`.fs-datepicker-title`) + `.fs-datepicker-grid[role="grid"]` (uma
-`.fs-datepicker-week[role="row"]` por semana, cada uma com 7
-`.fs-datepicker-day[role="gridcell"]`).
-
-## Variações
-
-- Dias fora do mês corrente (preenchendo a primeira/última semana):
-  `.fs-datepicker-day.is-outside`.
-- Sem suporte a `min`/`max` (intervalo de datas permitido) nesta versão —
-  todo dia é selecionável.
-
-## Estados
-
-- `.is-today`: contorno sutil no dia atual.
-- `.is-selected`: preenchimento sólido na cor de ação primária (mesmo
-  `color-contrast()` dos demais preenchimentos sólidos do framework).
-- `:disabled`: dia desabilitado (não gerado automaticamente hoje — para uso
-  manual caso você desabilite dias específicos via JS próprio).
-
-## A11y
-
-Segue o padrão [WAI-ARIA Date Picker Dialog](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/datepicker-dialog/)
-adaptado (sem o modal — o painel é um popup não-modal, mesma filosofia do
-[Combobox](combobox.md)/[Dropdown](dropdown.md)):
-
-- `role="combobox"` + `aria-haspopup="grid"` + `aria-expanded` +
-  `aria-controls` no input — `aria-expanded` só é permitido em roles como
-  `combobox`/`button`, por isso o `role="combobox"` é necessário mesmo o
-  input não filtrando nada (diferente do Combobox de verdade).
-- `role="grid"`/`role="row"`/`role="gridcell"` na grade — ao contrário do
-  Combobox, os dias **são** focáveis de verdade (roving `tabindex`: só o
-  dia selecionado/hoje/primeiro do mês tem `tabindex="0"`).
-- Teclado (com o painel aberto):
-  - `ArrowDown`/`ArrowUp` com foco no input: abre o painel (se fechado) e
-    move o foco pro dia tabável — sem isso, as setas não teriam efeito
-    nenhum vindas do input.
-  - `ArrowRight`/`ArrowLeft`: dia seguinte/anterior (cruza mês).
-  - `ArrowDown`/`ArrowUp` com foco num dia: mesma semana, ±7 dias.
-  - `Home`/`End`: primeiro/último dia da semana atual.
-  - `PageDown`/`PageUp`: mês seguinte/anterior. `Shift+PageDown`/
-    `Shift+PageUp`: ano seguinte/anterior.
-  - `Enter`/`Space`: seleciona o dia com foco.
-  - `Escape`: fecha o painel sem alterar o valor do input, devolve o foco
-    a ele.
-- Título do mês/ano (`aria-live="polite"`) anuncia a troca ao navegar.
-
-## API JS
-
-Auto-init via `data-fs="datepicker"` **no `<input>`**, com `data-fs-target`
-apontando pro painel (convenção idêntica ao Dropdown/Combobox).
-`Datepicker.getInstance(inputEl)`.
-
-| Método | Descrição |
-|---|---|
-| `show()` | Abre o painel, renderiza o mês do valor atual (ou o mês corrente). |
-| `hide()` | Fecha o painel. |
-| `toggle()` | Alterna. |
-| `dispose()` | Fecha se aberto, remove listeners, desregistra a instância. |
-
-| Propriedade | Descrição |
-|---|---|
-| `value` | Data selecionada em ISO (`aaaa-mm-dd`), `null` até a primeira seleção. |
-
-| Evento (no input) | Cancelável | Quando |
-|---|---|---|
-| `change` (nativo) | Não | Ao selecionar um dia (clique ou `Enter`/`Space`). |
-| `fs:datepicker:changed` | Não | Mesmo momento, com `event.detail.value` (ISO) e `event.detail.date` (`Date`). |
-| `fs:datepicker:shown` | Não | Depois de abrir o painel. |
-| `fs:datepicker:hidden` | Não | Depois de fechar. |
-
-## Tokens
-
-Reusa `--fs-color-border`/`-surface`/`-text`/`-muted`/`-primary`,
-`--fs-radius-sm`/`-md` e `--fs-shadow-md` — sem tokens próprios.
-
-## Exemplo
-
-```html
-<div class="fs-datepicker">
-  <input type="text" class="fs-form-control" id="entrega" data-fs="datepicker" data-fs-target="#entrega-painel" placeholder="dd/mm/aaaa">
-</div>
-<div id="entrega-painel"></div>
-<script>
-  document.getElementById("entrega").addEventListener("fs:datepicker:changed", (e) => {
-    console.log("data escolhida:", e.detail.value); // "2026-07-20"
-  });
-</script>
-```
-
-Mockup: [laboratório do componente](../../mockup/forms.html#datepicker) (inclui o
-Datepicker customizado e os `<input type="date">`/`"time"` nativos lado a
-lado).