@aurea-uds/native 0.7.0 → 0.8.0

package/README.md

@@ -6,9 +6,18 @@ Pacote **irmão** do `@aurea-uds/react`, não um wrapper dele: componentes próp
 `View`/`Text`/`Pressable`, consumindo `@aurea-uds/tokens`. Só os tokens atravessam — decisão de
 18/07/2026, registrada no `ROADMAP.md` Fase 7.
 
-> **Estado: O ALVO NATIVO ESTÁ COMPLETO — 46 componentes, e agora sem exceção.** O Lote 6 fechou
-> o plano em 09/09/2026 (`Timeline`, `DataList`, `Table`), e o **`Chart`** — a única peça que
-> tinha ficado de fora — entrou no mesmo dia pela
+> **Estado: 51 componentes.** O **Lote 7** entrou em 11/09/2026 e é o primeiro que **não sai do
+> plano** — ele saiu do APP. O consumidor mediu três lacunas na primeira tela que a pessoa toca, e
+> elas viraram cinco componentes: **`Combobox`, `SearchField`, `NumberField`, `Image` e
+> `Gallery`**, mais a prop `formatOnBlur` no `Input`. **Zero dependência nova.**
+> Ver a seção **Buscar, número e mídia** abaixo, e o `NATIVE.md` §8.
+>
+> ⚠ **O `Combobox` DIVERGE da web de propósito** — ele aceita busca REMOTA em seleção única, que
+> lá não existe ([ADR-0043](../../decisions/0043-o-combobox-nativo-diverge-da-web-e-a-presenca-da-prop-e-a-chave.md)).
+> ⚠ **Os cinco do Lote 7 ainda não rodaram em aparelho** — só em teste.
+>
+> **O PLANO fechou no Lote 6**, em 09/09/2026 (`Timeline`, `DataList`, `Table`), e o **`Chart`** —
+> a única peça que tinha ficado de fora — entrou no mesmo dia pela
 > [ADR-0041](../../decisions/0041-o-motor-de-grafico-do-nativo-e-nosso-sobre-react-native-svg.md).
 >
 > ⚠ **O `Chart` é o único componente deste pacote cuja GEOMETRIA é nossa.** Na web ele é 79 linhas
@@ -219,6 +228,129 @@ leitor anuncia.
 O `behavior` muda com a plataforma — `padding` no iOS, `height` no Android — e a Aurea escolhe
 por você. Um só nos dois lados deixa metade dos aparelhos com o botão de salvar sob o teclado.
 
+## Buscar, número e mídia
+
+O **Lote 7** (11/09/2026). Três lacunas que o app mediu, e não o plano — `NATIVE.md` §8.
+
+### `Combobox` — digitar para achar um item
+
+⚠ **Não confunda com o `Select`.** A escolha entre os dois é de TAMANHO DE LISTA, e a linha é
+dura: o `Select` monta todos os itens num `ScrollView` — serve para unidades, estados e tipos.
+**Um catálogo de milhares de linhas ali trava.** O `Combobox` usa `FlatList` e aceita busca remota.
+
+```tsx
+import {Combobox, Field} from "@aurea-uds/native";
+
+// ① catálogo REMOTO — a Aurea não filtra, o app busca
+<Field label="Item">
+  <Combobox
+    items={resultados}          // a lista JÁ BUSCADA
+    value={escolhido}           // o ITEM inteiro, não o id
+    onValueChange={setEscolhido}
+    onSearchChange={buscar}     // ← a presença desta prop DESLIGA o filtro da Aurea
+    loading={buscando}
+    onEndReached={proximaPagina}
+  />
+</Field>
+
+// ② lista NA MÃO — a Aurea filtra, ignorando acento e caixa
+<Combobox items={unidades} value={unidade} onValueChange={setUnidade} />
+```
+
+**A regra em uma linha: `onSearchChange` presente = a Aurea não filtra.** É presença de prop, não
+configuração — e ela existe porque filtrar de novo o que o servidor devolveu esconde resultado.
+
+| | |
+|---|---|
+| espera antes de chamar `onSearchChange` | **250 ms**. `searchDelay={0}` desliga |
+| onde se digita | **dentro da folha**, não no gatilho — o teclado ocupa metade da tela |
+| `value` | o **item inteiro**: numa busca remota a lista some debaixo da escolha |
+| ícones a registrar | `chevron--down`, `search`, `close` |
+
+### `SearchField` — filtrar o que já está na tela
+
+Outro papel: o `Combobox` **escolhe** de um catálogo e devolve a escolha; este **filtra** e
+devolve texto.
+
+```tsx
+<SearchField placeholder="Filtrar" onSearchChange={setFiltro} />
+```
+
+### `NumberField` — moeda, medida e contador
+
+```tsx
+<Field label="Valor">
+  <NumberField value={valor} onValueChange={setValor}
+               format={{style: "currency", currency: "BRL"}} locale="pt-BR" />
+</Field>
+
+<Field label="Litros">
+  <NumberField value={litros} onValueChange={setLitros}
+               format={{maximumFractionDigits: 1}} locale="pt-BR" min={0} />
+</Field>
+
+<Field label="Quantidade">
+  <NumberField value={qtd} onValueChange={setQtd} min={0} step={1} />
+</Field>
+```
+
+⚠ **O que sai por `onValueChange` é `number`, sempre** — `1234.5`, nunca `"R$ 1.234,50"`.
+
+⚠ **Formata no BLUR, e só no blur** ([ADR-0024](../../decisions/0024-mascara-de-campo-e-o-momento-nao-o-formato.md)
+e [ADR-0042](../../decisions/0042-o-intl-e-o-formatador-do-nativo-e-a-volta-e-nossa.md)). Enquanto
+o campo tem foco, ele mostra exatamente o que foi digitado. Máscara ao vivo é o defeito que o
+USWDS publicou com reprovação WCAG registrada e que o MUI abandonou na v6.
+
+⚠ **`notation: "compact"` é recusado** — quebrado no motor JS do RN nos dois sistemas. Sai aviso em
+`__DEV__` e a opção é ignorada; o resto do formato sobrevive.
+
+Os três auxiliares são públicos, porque o app tem o mesmo problema fora do campo:
+
+```tsx
+import {formatarNumero, lerNumero, separadoresDoLocale} from "@aurea-uds/native";
+
+formatarNumero(1234.5, "pt-BR", {style: "currency", currency: "BRL"});  // "R$ 1.234,50"
+lerNumero("R$ 1.234,50", "pt-BR");                                      // 1234.5
+lerNumero("", "pt-BR");                                                 // null  ← não é 0
+```
+
+Para **texto** (placa, documento, telefone) o momento é o mesmo e o formato é seu:
+
+```tsx
+<Input value={placa} onChangeText={setPlaca} formatOnBlur={(v) => v.toUpperCase()} />
+```
+
+⚠ `formatOnBlur` exige o campo **controlado** — o valor formatado sai por `onChangeText`.
+
+### `Image` e `Gallery` — mostrar foto
+
+⚠ **`Image` NÃO é o `Image` do React Native com outra pele.** Ele faz as duas coisas que o
+primitivo cru não faz: **reserva a caixa** antes dos bytes (sem isso o layout salta) e **cai para
+um substituto** quando eles não vêm (sem isso uma URL quebrada deixa buraco).
+
+```tsx
+<Image source={foto.uri} alt="Frente do item" ratio="4/3" />
+
+<Gallery items={fotos} zoom selected={atual} onSelect={setAtual} />
+```
+
+| | |
+|---|---|
+| `ratio` | aceita `4/3`, `"4/3"`, `"16:9"` ou o número. A web usa string; o RN quer número |
+| `alt` | **obrigatório**. Decorativa de verdade se escreve `alt=""`, explícito |
+| ampliar | é o **`Dialog`** que já existe, não uma superfície nova |
+| legenda | com legenda, o nome vai para o LADRILHO e a imagem sai da árvore de acessibilidade |
+| ícone a registrar | `image` (o substituto) |
+
+Quem já usa `expo-image` por cache de disco troca o elemento sem perder a pele:
+
+```tsx
+<Image render={<ExpoImage contentFit="cover" transition={150} />} source={u} alt="…" />
+```
+
+⚠ `fit` **não** é traduzido para o elemento passado — `resizeMode` é do `Image` do RN e o
+`expo-image` chama a mesma coisa de `contentFit`. Quem passa o elemento escreve a prop dele.
+
 ## Data e câmera
 
 Estes dois **não saem do barril** — são o único ponto do pacote com importação própria:

package/dist/busca.d.ts

@@ -0,0 +1,119 @@
+import * as React from "react";
+import { type StyleProp, type ViewStyle } from "react-native";
+import { type IconName } from "./icon.js";
+import { type AureaFieldSize } from "./inputs.js";
+/** Uma linha do catálogo. **Mesma forma da web** (`ComboboxOption`), mais o `disabled` que o `Select` daqui já tinha. */
+export interface AureaComboboxItem {
+    value: string;
+    label: string;
+    disabled?: boolean;
+}
+export interface ComboboxProps {
+    /**
+     * O que a folha mostra. **Com `onSearchChange`, é a lista JÁ BUSCADA** — a Aurea não filtra e
+     * não guarda; ela desenha o que chegou.
+     */
+    items: AureaComboboxItem[];
+    /**
+     * O escolhido, como ITEM inteiro e não como `value` — mesma escolha da web, e ela tem razão
+     * prática aqui: numa busca remota o item escolhido pode não estar mais em `items` (a pessoa
+     * digitou outra coisa depois de escolher), e o gatilho ainda precisa saber que rótulo mostrar.
+     * Guardar só o `value` deixaria o campo em branco no instante seguinte à escolha.
+     */
+    value?: AureaComboboxItem | null;
+    onValueChange?: (v: AureaComboboxItem | null) => void;
+    /**
+     * O que foi digitado, já com espera. **A presença desta prop DESLIGA o filtro da Aurea** — é a
+     * chave entre catálogo remoto e lista na mão, e é presença, não configuração.
+     */
+    onSearchChange?: (query: string) => void;
+    /**
+     * A espera antes de chamar `onSearchChange`, em ms. Padrão **250**.
+     *
+     * Não é enfeite de performance: sem ela, "cadeira" são sete chamadas ao servidor e seis
+     * respostas descartadas — e a última a chegar pode não ser a última pedida. `0` desliga.
+     */
+    searchDelay?: number;
+    /** Mostra o anel no lugar da lista. Use enquanto a busca remota não voltou. */
+    loading?: boolean;
+    /** Fim da lista alcançado — é por aqui que o catálogo remoto pagina. */
+    onEndReached?: () => void;
+    /** O que o gatilho mostra sem escolha. */
+    placeholder?: string;
+    /** O que o campo da folha mostra vazio. Sem ele, a frase `comboboxSearch` do provider. */
+    searchPlaceholder?: string;
+    /** O que a folha mostra sem resultado. Sem ele, a frase `comboboxEmpty` do provider. */
+    empty?: React.ReactNode;
+    /** Mostra o botão de limpar no gatilho quando há escolha. Padrão **true**. */
+    clearable?: boolean;
+    disabled?: boolean;
+    size?: AureaFieldSize;
+    /** O glifo da seta. Registre-o, ou passe `false`. */
+    chevron?: IconName | false;
+    /** O glifo da lupa no campo da folha. Registre-o, ou passe `false`. */
+    searchIcon?: IconName | false;
+    style?: StyleProp<ViewStyle>;
+    testID?: string;
+}
+/**
+ * O campo em que se DIGITA para achar um item.
+ *
+ * ```tsx
+ * // catálogo remoto — a Aurea não filtra, o app busca
+ * <Field label="Item">
+ *   <Combobox
+ *     items={resultados}
+ *     value={escolhido}
+ *     onValueChange={setEscolhido}
+ *     onSearchChange={buscarNoServidor}
+ *     loading={buscando}
+ *     onEndReached={proximaPagina}
+ *   />
+ * </Field>
+ *
+ * // lista na mão — a Aurea filtra
+ * <Combobox items={unidades} value={unidade} onValueChange={setUnidade} />
+ * ```
+ *
+ * ⚠ **O gatilho é `button`, não `combobox`** — e desta vez a razão é medida, não herdada do
+ * `Select`: `role="combobox"` mapeia no Android (`roleDescription`) e **não mapeia no iOS**; e o
+ * gatilho, de qualquer forma, não aceita digitação. Quem digita é o campo da folha, que leva
+ * `role="search"` — esse mapeia nos dois. A tabela com arquivo e linha está no topo deste módulo.
+ *
+ * ⚠ **Ele não guarda a escolha nem o texto buscado.** `value` e o que se digita são do app, como
+ * na web e pela mesma razão do achado I1 da auditoria: um componente com a sua própria cópia do
+ * estado é a segunda fonte de verdade que ninguém sabe que existe.
+ */
+export declare function Combobox({ items, value, onValueChange, onSearchChange, searchDelay, loading, onEndReached, placeholder, searchPlaceholder, empty, clearable, disabled, size, chevron, searchIcon, style, testID, }: ComboboxProps): React.JSX.Element;
+export interface SearchFieldProps {
+    value?: string;
+    onChangeText?: (v: string) => void;
+    /** Chamado com o texto já esperado. Mesma espera do `Combobox`, e mesmo padrão de 250 ms. */
+    onSearchChange?: (query: string) => void;
+    searchDelay?: number;
+    placeholder?: string;
+    disabled?: boolean;
+    size?: AureaFieldSize;
+    /** O glifo da lupa. Padrão `search`; `false` tira. */
+    icon?: IconName | false;
+    /** Mostra o botão de limpar quando há texto. Padrão **true**. */
+    clearable?: boolean;
+    onSubmit?: () => void;
+    style?: StyleProp<ViewStyle>;
+    testID?: string;
+}
+/**
+ * A lupa + o campo, numa peça só.
+ *
+ * ⚠ **Não é o mesmo papel do `Combobox`, e confundir os dois é o erro comum:** o `Combobox`
+ * ESCOLHE um item de um catálogo e devolve a escolha; este FILTRA o que já está na tela e devolve
+ * texto. Um cadastro pede o primeiro; uma lista com muitas linhas pede o segundo.
+ *
+ * ⚠ **`role="search"`, e ele mapeia nos dois sistemas** — conferido no fonte do RN 0.87.1, com
+ * arquivo e linha no topo deste módulo. É a diferença entre este componente e o `Combobox`, cujo
+ * gatilho não pôde levar `combobox` porque o iOS não tem o trait.
+ *
+ * ⚠ **A borda mora no GRUPO, não no campo** — é o `.input-group` da web (`aurea.css:741`), e é o
+ * que deixa lupa, campo e botão de limpar dentro de uma caixa só em vez de três.
+ */
+export declare function SearchField({ value, onChangeText, onSearchChange, searchDelay, placeholder, disabled, size, icon, clearable, onSubmit, style, testID, }: SearchFieldProps): React.JSX.Element;

package/dist/busca.js

@@ -0,0 +1,338 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Aurea nativo — a BUSCA: `Combobox` e `SearchField`.
+//
+// Lote 7 do `NATIVE.md` §8 — o primeiro lote que nasce de DEMANDA MEDIDA e não do plano: o alvo
+// nativo fechou em 46 componentes em 11/09/2026, e o consumidor bateu em três lacunas na primeira
+// tela que a pessoa toca. Esta é a primeira delas, e é a que bloqueia o cadastro.
+//
+// ── O QUE FALTAVA, LITERALMENTE ──────────────────────────────────────────────────────────────
+// O `Select` (`inputs.tsx:576`) escreve a própria lacuna: *"O papel é `button` e não `combobox`.
+// `combobox` promete um campo em que se DIGITA para filtrar; isto só abre uma lista."* Era
+// honesto, e continua sendo — o `Select` não mudou. O que faltava era o componente que CUMPRE a
+// promessa, e é este.
+//
+// E havia um agravante que a demanda não citava, medido aqui: a folha do `Select` usa
+// `ScrollView` (`inputs.tsx:632`), que **monta todos os itens**. Um catálogo de milhares de
+// linhas ali não fica lento — ele trava. Este usa `FlatList`, como o `DataList` do Lote 6 já
+// fazia (`data.tsx:191`).
+//
+// ── A DIVERGÊNCIA DA WEB, E ELA É DELIBERADA ─────────────────────────────────────────────────
+// **A demanda é busca REMOTA de seleção única, e essa combinação não existe na web.** Medido em
+// `inputs-client.tsx`:
+//
+//     Combobox (seleção única)   -> `items` e filtro do Base UI, do lado do cliente. Sem `onInputChange`.
+//     MultiCombobox (múltipla)   -> tem `onInputChange` + `loading`, e desliga o filtro (`filter={null}`)
+//
+// Ou seja: quem quer buscar no servidor E escolher UM item não tem componente na web. Copiar o
+// contrato de lá deixaria o consumidor com um filtro de cliente sobre milhares de linhas que ele
+// nem baixou.
+//
+// Então este componente soma `onSearchChange` + `loading` + `onEndReached` ao contrato de seleção
+// única, e **a regra é uma só e vale para os dois lados**: se `onSearchChange` existe, a Aurea
+// NÃO filtra — a lista que chega é a lista que aparece, e quem busca é o app. Sem ele, a Aurea
+// filtra o que recebeu. É a mesma chave do `filter={null}` do `MultiCombobox`, escrita como
+// presença de prop em vez de configuração de motor.
+//
+// É a mesma classe de divergência que a `Table` do Lote 6 assumiu (`columns`+`rows` em vez de
+// `children`): quando a plataforma muda o problema, o contrato muda com ele — declarado, não
+// escondido.
+//
+// ── ONDE SE DIGITA, E POR QUE NÃO É NO GATILHO ───────────────────────────────────────────────
+// Na web o `<input>` É o combobox: digita-se nele e a lista desce ancorada. Aqui **o gatilho
+// continua sendo um botão, e o campo de digitar mora DENTRO da folha**. Três razões medidas, não
+// preferidas:
+//
+//   1. o teclado do telefone ocupa metade da tela. Um campo ancorado no meio de um formulário
+//      abre o teclado por cima da própria lista — a folha sobe do rodapé e fica acima dele;
+//   2. o gatilho precisa mostrar o ESCOLHIDO com a geometria do `.input` (mesma altura, mesma
+//      borda, a mesma seta) — é o que faz o campo parecer um campo no formulário. Um campo de
+//      texto ali mostraria o que se digitou, não o que se escolheu;
+//   3. é o idioma dos seletores do próprio sistema, nos dois lados.
+//
+// ── A ACESSIBILIDADE, MEDIDA NO FONTE DO RN 0.87.1 (e não presumida) ─────────────────────────
+// O Lote 5 ensinou que o RN ACEITA papel que não mapeia (`dialog` compila e vira `null`). Então
+// os dois papéis daqui foram conferidos no fonte do `react-native@0.87.1` antes de usados:
+//
+//   `role="search"`   -> `accessibilityPropsConversions.h:64-65` traduz para
+//                        `AccessibilityTraits::SearchField`, que o `RCTConversions.h:120-121`
+//                        vira `UIAccessibilityTraitSearchField` no iOS; no Android o
+//                        `ReactAccessibilityDelegate.kt:461` dá a `className`
+//                        `android.widget.EditText`. **Mapeia nos dois.**
+//   `role="combobox"` -> no Android o `ReactAccessibilityDelegate.kt:680-682` põe
+//                        `roleDescription` de `R.string.combobox_description` (o TalkBack diz
+//                        "caixa de combinação"); **no iOS não há trait equivalente** — não está
+//                        na tabela do `RCTConversions.h`. Mapeia em UM lado.
+//
+// Por isso o gatilho é `button` com `expanded`, como o do `Select`: ele abre uma folha e não
+// aceita digitação, então `button` é o que ele É nos dois sistemas. Quem digita é o campo da
+// folha, e ele leva `search` — que mapeia nos dois.
+import * as React from "react";
+import { FlatList, Modal, Pressable, TextInput, View, } from "react-native";
+import { IconButton } from "./actions.js";
+import { criarFolha } from "./estilos.js";
+import { Spinner } from "./feedback.js";
+import { Icon } from "./icon.js";
+import { useCampo } from "./inputs.js";
+import { Text } from "./text.js";
+import { useAureaStrings, useAureaTokens } from "./theme.js";
+// As mesmas contas do `inputs.tsx`, e elas são repetidas AQUI de propósito: exportá-las de lá
+// tornaria pública uma conta interna do outro módulo, e um `import` de função privada entre
+// módulos irmãos é o começo de um acoplamento que ninguém declara. São três linhas.
+const alturaDoTamanho = (t, s) => s === "sm" ? t.size.controlHSm : s === "lg" ? t.size.controlHLg : t.size.controlHMd;
+const fonteDoTamanho = (t, s) => s === "sm" ? t.size.textXs : s === "lg" ? t.size.textBase : t.size.textMd;
+const respiroDoTamanho = (t, s) => s === "sm" ? t.size.space3 : s === "lg" ? t.size.space4 : 13;
+const folha = criarFolha((t) => ({
+    // O gatilho é o `.input` da web (`aurea.css:685`), igual ao do `Select` — mesma altura, mesma
+    // borda, o mesmo raio de controle.
+    caixa: {
+        width: "100%", minWidth: 0,
+        borderWidth: t.size.borderWidth, borderColor: t.color.borderStrong,
+        borderRadius: t.size.radiusControl, backgroundColor: t.color.fieldBg,
+        flexDirection: "row", alignItems: "center",
+    },
+    invalido: { borderColor: t.color.danger400 ?? t.color.destructive },
+    desabilitado: { opacity: 0.5 },
+    // As ações do gatilho — limpar e a seta. O `.combobox-actions` da web (`aurea.css:1673`) é
+    // absoluto sobre o campo; aqui é um irmão na linha, porque não há campo por baixo.
+    acoes: { flexDirection: "row", alignItems: "center", gap: 2 },
+    // A folha, com a mesma anatomia da do `Select` (`inputs.tsx:98-113`) — e é de propósito que
+    // sejam iguais: são o mesmo gesto, e duas folhas diferentes para o mesmo gesto é como uma
+    // biblioteca deixa de ter linguagem.
+    fundoDaLista: { flex: 1, justifyContent: "flex-end", backgroundColor: "#00000080" },
+    fundoDeToque: { position: "absolute", top: 0, right: 0, bottom: 0, left: 0 },
+    lista: {
+        // `maxHeight` MAIOR que a do `Select` (60%), e a razão é o teclado: aqui ele sobe junto, e
+        // uma folha de 60% com teclado aberto deixa três linhas visíveis. O `KeyboardAvoidingView`
+        // não entra — dentro de um `Modal` do RN ele não recebe as métricas do teclado no Android.
+        maxHeight: "85%", minHeight: "45%",
+        borderTopLeftRadius: t.size.radiusCard, borderTopRightRadius: t.size.radiusCard,
+        backgroundColor: t.color.popover, borderWidth: t.size.borderWidth, borderColor: t.color.border,
+    },
+    // O campo de digitar, no topo da folha. É o `.input-group` da web (`aurea.css:741`): a borda
+    // mora no GRUPO e o campo dentro dele é transparente e sem borda.
+    grupo: {
+        flexDirection: "row", alignItems: "center", gap: t.size.space1,
+        margin: t.size.space3,
+        paddingHorizontal: t.size.space3,
+        borderWidth: t.size.borderWidth, borderColor: t.color.borderStrong,
+        borderRadius: t.size.radiusControl, backgroundColor: t.color.fieldBg,
+    },
+    // ⚠ `paddingVertical: 0` e `textAlignVertical: "center"` — a MESMA correção que o `Input` do
+    // Lote 4 levou depois do vidro (`inputs.tsx:280-296`): sem elas o Android injeta o padding do
+    // tema dele no nó do Yoga e o texto sai cortado dentro de uma caixa de altura fixa. A regra do
+    // `CLAUDE.md` ("correção local é proibida sem responder quem mais tem esse problema") é o que
+    // traz as duas linhas para cá, e este campo é exatamente "quem mais".
+    campoDeTexto: { flex: 1, minWidth: 0, paddingVertical: 0, textAlignVertical: "center" },
+    opcao: {
+        minHeight: t.size.controlHLg, justifyContent: "center",
+        paddingHorizontal: t.size.space4, paddingVertical: t.size.space2,
+    },
+    opcaoEscolhida: { backgroundColor: t.color.surface3 ?? t.color.muted },
+    vazio: { paddingHorizontal: t.size.space4, paddingVertical: t.size.space5, alignItems: "center" },
+    carregando: { paddingVertical: t.size.space4, alignItems: "center" },
+}));
+/**
+ * O campo em que se DIGITA para achar um item.
+ *
+ * ```tsx
+ * // catálogo remoto — a Aurea não filtra, o app busca
+ * <Field label="Item">
+ *   <Combobox
+ *     items={resultados}
+ *     value={escolhido}
+ *     onValueChange={setEscolhido}
+ *     onSearchChange={buscarNoServidor}
+ *     loading={buscando}
+ *     onEndReached={proximaPagina}
+ *   />
+ * </Field>
+ *
+ * // lista na mão — a Aurea filtra
+ * <Combobox items={unidades} value={unidade} onValueChange={setUnidade} />
+ * ```
+ *
+ * ⚠ **O gatilho é `button`, não `combobox`** — e desta vez a razão é medida, não herdada do
+ * `Select`: `role="combobox"` mapeia no Android (`roleDescription`) e **não mapeia no iOS**; e o
+ * gatilho, de qualquer forma, não aceita digitação. Quem digita é o campo da folha, que leva
+ * `role="search"` — esse mapeia nos dois. A tabela com arquivo e linha está no topo deste módulo.
+ *
+ * ⚠ **Ele não guarda a escolha nem o texto buscado.** `value` e o que se digita são do app, como
+ * na web e pela mesma razão do achado I1 da auditoria: um componente com a sua própria cópia do
+ * estado é a segunda fonte de verdade que ninguém sabe que existe.
+ */
+export function Combobox({ items, value, onValueChange, onSearchChange, searchDelay = 250, loading, onEndReached, placeholder, searchPlaceholder, empty, clearable = true, disabled, size, chevron = "chevron--down", searchIcon = "search", style, testID, }) {
+    const t = useAureaTokens();
+    const s = folha(t);
+    const strings = useAureaStrings();
+    const campo = useCampo();
+    const tam = size ?? campo?.size ?? "md";
+    const inativo = disabled ?? campo?.disabled;
+    const [aberto, setAberto] = React.useState(false);
+    const [texto, setTexto] = React.useState("");
+    // ── A ESPERA ────────────────────────────────────────────────────────────────────────────────
+    // O timer vive num `ref` e é limpo em três lugares: à digitação seguinte, ao fechar a folha e
+    // ao desmontar. O terceiro é o que importa e o que mais se esquece — sem ele, sair da tela com
+    // uma busca pendente dispara `onSearchChange` sobre um componente que já não existe, e o app
+    // leva um `setState` em árvore desmontada.
+    const relogio = React.useRef(null);
+    const cancelar = React.useCallback(() => {
+        if (relogio.current != null) {
+            clearTimeout(relogio.current);
+            relogio.current = null;
+        }
+    }, []);
+    React.useEffect(() => cancelar, [cancelar]);
+    // A referência mais recente da função de busca, para o timer não disparar a de um render
+    // anterior. É o padrão de `ref` para callback — e existe porque o app costuma passar uma
+    // arrow nova a cada render.
+    const buscaAtual = React.useRef(onSearchChange);
+    React.useEffect(() => { buscaAtual.current = onSearchChange; }, [onSearchChange]);
+    const digitar = React.useCallback((v) => {
+        setTexto(v);
+        if (!buscaAtual.current)
+            return;
+        cancelar();
+        if (searchDelay <= 0) {
+            buscaAtual.current(v);
+            return;
+        }
+        relogio.current = setTimeout(() => {
+            relogio.current = null;
+            buscaAtual.current?.(v);
+        }, searchDelay);
+    }, [cancelar, searchDelay]);
+    const fechar = React.useCallback(() => {
+        cancelar();
+        setAberto(false);
+        setTexto("");
+    }, [cancelar]);
+    // ── O FILTRO, QUANDO ELE É NOSSO ────────────────────────────────────────────────────────────
+    const filtrados = React.useMemo(() => {
+        if (onSearchChange)
+            return items; // busca remota: a lista que chegou é a lista.
+        const alvo = dobrar(texto.trim());
+        if (!alvo)
+            return items;
+        return items.filter((i) => dobrar(i.label).includes(alvo));
+    }, [items, texto, onSearchChange]);
+    const nada = !loading && filtrados.length === 0;
+    return (_jsxs(_Fragment, { children: [_jsxs(Pressable, { testID: testID, onPress: inativo ? undefined : () => setAberto(true), disabled: inativo, accessibilityRole: "button", accessibilityLabel: campo?.label, accessibilityHint: campo?.hint, accessibilityValue: { text: value?.label }, accessibilityState: { disabled: !!inativo, expanded: aberto }, style: [
+                    s.caixa,
+                    { height: alturaDoTamanho(t, tam), paddingHorizontal: respiroDoTamanho(t, tam) },
+                    campo?.invalido && s.invalido,
+                    inativo && s.desabilitado,
+                    style,
+                ], children: [_jsx(Text, { size: tam === "sm" ? "xs" : tam === "lg" ? "base" : "md", tone: value ? "default" : "subtle", numberOfLines: 1, style: { flex: 1, minWidth: 0 }, children: value?.label ?? placeholder ?? "" }), _jsxs(View, { style: s.acoes, children: [clearable && value != null && !inativo && (_jsx(IconButton, { name: "close", label: strings.comboboxClear, appearance: "ghost", size: "sm", onPress: () => onValueChange?.(null), testID: testID ? `${testID}-limpar` : undefined })), chevron && _jsx(Icon, { name: chevron, size: "sm", color: t.color.subtleForeground })] })] }), _jsx(Modal, { visible: aberto, transparent: true, animationType: "slide", statusBarTranslucent: true, navigationBarTranslucent: true, onRequestClose: fechar, children: _jsxs(View, { style: s.fundoDaLista, children: [_jsx(Pressable, { style: s.fundoDeToque, onPress: fechar, accessible: false, testID: testID ? `${testID}-fundo` : undefined }), _jsxs(View, { style: s.lista, onStartShouldSetResponder: () => true, children: [_jsxs(View, { style: [s.grupo, { height: alturaDoTamanho(t, tam) }], children: [searchIcon && _jsx(Icon, { name: searchIcon, size: "sm", color: t.color.subtleForeground }), _jsx(TextInput, { testID: testID ? `${testID}-busca` : undefined, value: texto, onChangeText: digitar, placeholder: searchPlaceholder ?? strings.comboboxSearch, placeholderTextColor: t.color.subtleForeground, 
+                                            // ⚠ `autoFocus` é o que faz a folha valer a pena: abrir um campo de busca e
+                                            // exigir um segundo toque para o teclado subir é um toque a mais em cada
+                                            // cadastro. O foco entra com a folha; o teclado vem junto.
+                                            autoFocus: true, autoCorrect: false, autoCapitalize: "none", 
+                                            // Mapeia nos dois sistemas — conferido no fonte do RN, tabela no topo do módulo.
+                                            accessibilityRole: "search", accessibilityLabel: searchPlaceholder ?? strings.comboboxSearch, 
+                                            // `returnKeyType="search"` troca o "enter" do teclado pela lupa. É pista de
+                                            // plataforma, não decoração: diz à pessoa que aquele campo é de busca antes de
+                                            // ela digitar a primeira letra.
+                                            returnKeyType: "search", style: [
+                                                s.campoDeTexto,
+                                                { fontSize: fonteDoTamanho(t, tam), fontFamily: t.font.ui[400],
+                                                    color: t.color.foreground },
+                                            ] }), texto.length > 0 && (_jsx(IconButton, { name: "close", label: strings.searchClear, appearance: "ghost", size: "sm", onPress: () => digitar(""), testID: testID ? `${testID}-busca-limpar` : undefined }))] }), loading && (_jsx(View, { style: s.carregando, children: _jsx(Spinner, { label: strings.comboboxLoading }) })), nada && (_jsx(View, { style: s.vazio, children: typeof empty === "string" || empty == null
+                                        ? _jsx(Text, { size: "sm", tone: "muted", children: empty ?? strings.comboboxEmpty })
+                                        : empty })), _jsx(FlatList, { data: filtrados, keyExtractor: (i) => i.value, keyboardShouldPersistTaps: "handled", onEndReached: onEndReached, onEndReachedThreshold: 0.5, renderItem: ({ item }) => (_jsx(Pressable, { disabled: item.disabled, onPress: () => { onValueChange?.(item); fechar(); }, accessibilityRole: "menuitem", accessibilityState: {
+                                            selected: item.value === value?.value, disabled: !!item.disabled,
+                                        }, style: [
+                                            s.opcao,
+                                            item.value === value?.value && s.opcaoEscolhida,
+                                            item.disabled && s.desabilitado,
+                                        ], children: _jsx(Text, { size: "md", weight: item.value === value?.value ? 600 : 400, children: item.label }) })) })] })] }) })] }));
+}
+// ── A DOBRA DE ACENTO, e por que ela é sondada em vez de presumida ───────────────────────────
+// Buscar "acucar" tem de achar "açúcar" — num catálogo em português, exigir o acento certo é
+// exigir que a pessoa saiba escrever o que está procurando. A dobra é `NFD` + remoção dos
+// diacríticos combinantes, que é a forma padrão.
+//
+// **A sonda existe porque o motor é o motor, não um navegador.** `String.prototype.normalize` é
+// ES2015 e está no motor, mas este pacote roda em qualquer motor que o consumidor escolha — e
+// um `normalize` ausente derrubaria a busca inteira com `TypeError` em vez de degradá-la. A
+// sonda roda UMA vez, no carregamento do módulo, e custa uma string de dois caracteres.
+const TEM_NORMALIZE = (() => {
+    try {
+        return "é".normalize("NFD").length === 2;
+    }
+    catch {
+        return false;
+    }
+})();
+const dobrar = (v) => {
+    const minusculo = v.toLowerCase();
+    return TEM_NORMALIZE
+        ? minusculo.normalize("NFD").replace(/[̀-ͯ]/g, "")
+        : minusculo;
+};
+/**
+ * A lupa + o campo, numa peça só.
+ *
+ * ⚠ **Não é o mesmo papel do `Combobox`, e confundir os dois é o erro comum:** o `Combobox`
+ * ESCOLHE um item de um catálogo e devolve a escolha; este FILTRA o que já está na tela e devolve
+ * texto. Um cadastro pede o primeiro; uma lista com muitas linhas pede o segundo.
+ *
+ * ⚠ **`role="search"`, e ele mapeia nos dois sistemas** — conferido no fonte do RN 0.87.1, com
+ * arquivo e linha no topo deste módulo. É a diferença entre este componente e o `Combobox`, cujo
+ * gatilho não pôde levar `combobox` porque o iOS não tem o trait.
+ *
+ * ⚠ **A borda mora no GRUPO, não no campo** — é o `.input-group` da web (`aurea.css:741`), e é o
+ * que deixa lupa, campo e botão de limpar dentro de uma caixa só em vez de três.
+ */
+export function SearchField({ value, onChangeText, onSearchChange, searchDelay = 250, placeholder, disabled, size, icon = "search", clearable = true, onSubmit, style, testID, }) {
+    const t = useAureaTokens();
+    const s = folha(t);
+    const strings = useAureaStrings();
+    const campo = useCampo();
+    const tam = size ?? campo?.size ?? "md";
+    const inativo = disabled ?? campo?.disabled;
+    const [focado, setFocado] = React.useState(false);
+    // O campo pode ser controlado (`value`) ou não; o texto interno cobre o segundo caso, e é o que
+    // o botão de limpar precisa para saber se tem o que limpar.
+    const [interno, setInterno] = React.useState("");
+    const texto = value ?? interno;
+    const relogio = React.useRef(null);
+    const cancelar = React.useCallback(() => {
+        if (relogio.current != null) {
+            clearTimeout(relogio.current);
+            relogio.current = null;
+        }
+    }, []);
+    React.useEffect(() => cancelar, [cancelar]);
+    const buscaAtual = React.useRef(onSearchChange);
+    React.useEffect(() => { buscaAtual.current = onSearchChange; }, [onSearchChange]);
+    const digitar = React.useCallback((v) => {
+        setInterno(v);
+        onChangeText?.(v);
+        if (!buscaAtual.current)
+            return;
+        cancelar();
+        if (searchDelay <= 0) {
+            buscaAtual.current(v);
+            return;
+        }
+        relogio.current = setTimeout(() => {
+            relogio.current = null;
+            buscaAtual.current?.(v);
+        }, searchDelay);
+    }, [cancelar, onChangeText, searchDelay]);
+    return (_jsxs(View, { testID: testID, style: [
+            s.caixa,
+            { height: alturaDoTamanho(t, tam), paddingHorizontal: respiroDoTamanho(t, tam),
+                gap: t.size.space1 },
+            campo?.invalido && s.invalido,
+            // O foco é a única pista de campo ativo que sobra no telefone — mesma decisão do `Input`
+            // do Lote 4, e ela vale igual aqui.
+            focado && { borderColor: t.color.focusStrong },
+            inativo && s.desabilitado,
+            style,
+        ], children: [icon && _jsx(Icon, { name: icon, size: "sm", color: t.color.subtleForeground }), _jsx(TextInput, { testID: testID ? `${testID}-campo` : undefined, value: value, onChangeText: digitar, placeholder: placeholder, placeholderTextColor: t.color.subtleForeground, editable: !inativo, autoCorrect: false, autoCapitalize: "none", returnKeyType: "search", onSubmitEditing: onSubmit, onFocus: () => setFocado(true), onBlur: () => setFocado(false), accessibilityRole: "search", accessibilityLabel: campo?.label ?? placeholder, accessibilityHint: campo?.hint, accessibilityState: { disabled: !!inativo }, style: [
+                    s.campoDeTexto,
+                    { fontSize: fonteDoTamanho(t, tam), fontFamily: t.font.ui[400],
+                        color: t.color.foreground },
+                ] }), clearable && texto.length > 0 && !inativo && (_jsx(IconButton, { name: "close", label: strings.searchClear, appearance: "ghost", size: "sm", onPress: () => digitar(""), testID: testID ? `${testID}-limpar` : undefined }))] }));
+}

package/dist/index.d.ts

@@ -33,3 +33,9 @@ export { Timeline, DataList, Table } from "./data.js";
 export type { TimelineProps, DataListProps, TableProps, AureaColumn, AureaTimelineItem, AureaDataListItem, } from "./data.js";
 export { Chart, ChartLegend } from "./chart.js";
 export type { ChartProps, ChartLegendProps, AureaSeries, AureaChartMark } from "./chart.js";
+export { Combobox, SearchField } from "./busca.js";
+export type { ComboboxProps, SearchFieldProps, AureaComboboxItem } from "./busca.js";
+export { NumberField, formatarNumero, lerNumero, separadoresDoLocale } from "./numero.js";
+export type { NumberFieldProps, AureaSeparadores } from "./numero.js";
+export { Image, Gallery } from "./midia.js";
+export type { ImageProps, GalleryProps, AureaGalleryItem, AureaImageSource, } from "./midia.js";

package/dist/index.js

@@ -86,3 +86,24 @@ export { Timeline, DataList, Table } from "./data.js";
 // ⚠ **Com duas ou mais séries a legenda NÃO desliga**: a paleta `--chart-*` é uma rampa de um
 // azul só, e duas séries vizinhas nela são indistinguíveis (ΔE 5.9, medido).
 export { Chart, ChartLegend } from "./chart.js";
+// ── Lote 7 — as três lacunas que o CONSUMIDOR mediu, e não o plano ─────────────────────────
+// ⚠ Este é o primeiro lote do alvo nativo que **não sai do `NATIVE.md` §5**: o plano fechou em
+// 11/09/2026 com 46 componentes e "não sobrou nada". Sobrou — só que a fila passou a ser a do
+// app, não a do documento. As três estão no §8, com a demanda de cada uma.
+//
+// ⚠ **O `Combobox` DIVERGE da web, e é deliberado:** ele soma `onSearchChange`, `loading` e
+// `onEndReached` ao contrato de seleção única, porque busca remota + escolha de UM item não
+// existe lá (o `Combobox` da web filtra no cliente; quem tem `onInputChange` é o
+// `MultiCombobox`, que é de seleção múltipla). A regra: **`onSearchChange` presente = a Aurea
+// não filtra.**
+export { Combobox, SearchField } from "./busca.js";
+// ⚠ O `NumberField` formata no BLUR, nunca enquanto se digita — a [ADR-0024] atravessa inteira.
+// O que muda no nativo é quem chama o `Intl` (não há Base UI) e a VOLTA, que a web não precisou
+// escrever: `lerNumero` converte de novo o que a pessoa digitou. Os dois auxiliares são públicos
+// porque o app tem o mesmo problema em toda tela de lançamento.
+export { NumberField, formatarNumero, lerNumero, separadoresDoLocale } from "./numero.js";
+// ⚠ O `Image` NÃO é o `Image` do React Native com outra pele: ele **reserva a caixa** antes dos
+// bytes e **cai para um substituto** quando eles não vêm — as duas coisas que a ficha da web
+// promete e que o primitivo cru não faz. Foi por não fazê-las que o `Avatar` precisou de
+// conserto em 31/07/2026.
+export { Image, Gallery } from "./midia.js";