@aurea-uds/native 0.7.0 → 0.8.1

package/dist/busca.js

@@ -0,0 +1,393 @@
+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 { Animated, Easing, FlatList, Modal, PanResponder, 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 { KeyboardAvoiding, useCampo } from "./inputs.js";
+import { useReduceMotion } from "./movimento.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;
+// ⚠ O `13` do tamanho `md` NÃO é número inventado: é o `padding-inline` literal do `.input`
+// (`aurea.css:685`), e é o mesmo valor que o `inputs.tsx:60` usa. Não há token de 13 — a escala
+// tem `space3`=12 e `space4`=16 —, e é por isso que o CSS o escreve cru dos dois lados.
+const respiroDoTamanho = (t, s) => s === "sm" ? t.size.space3 : s === "lg" ? t.size.space4 : 13;
+// ── AS DUAS CONSTANTES DE INTERAÇÃO, e elas NÃO são geometria ────────────────────────────────
+// Ficam nomeadas e no topo porque número solto no meio do componente é o que o `CLAUDE.md`
+// passou a proibir em 12/09/2026. **Nenhuma das duas tem linha de `aurea.css` atrás, e não
+// deveria ter:** uma é tempo de digitação, a outra é fração de viewport do motor de lista.
+//
+// 250 ms é o intervalo entre teclas de quem digita corrido. Abaixo disso a espera não junta
+// letra nenhuma e cada tecla vira uma ida ao servidor; muito acima, a lista demora a reagir e a
+// pessoa acha que o campo travou. `searchDelay` existe para o app discordar.
+const ESPERA_PADRAO = 250;
+// Fração da altura visível que sobra abaixo antes de pedir a próxima página. Meia tela de
+// antecedência: menos que isso e a lista chega ao fim antes da resposta; mais, e o app pagina
+// páginas que ninguém vai ver. É prop do `FlatList`, não medida de desenho.
+const ANTECEDENCIA_DE_PAGINA = 0.5;
+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.
+    // `space05` mede 2 — o mesmo valor, agora com nome. O `.combobox-actions` da web
+    // (`aurea.css:1673`) usa `gap:2px` literal; aqui o token existe, então é ele que entra.
+    acoes: { flexDirection: "row", alignItems: "center", gap: t.size.space05 },
+    // 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 },
+    // 🔴 OS 85% E OS 45% ERAM INVENTADOS, e saíram em 12/09/2026. **A casa já tinha a medida:**
+    // o `folhaBaixo` do `BottomSheet` do Lote 5 (`overlays.tsx:104`) usa `maxHeight: "90%"`, e
+    // duas folhas que sobem do rodapé com alturas diferentes é como uma biblioteca deixa de ter
+    // linguagem. O `minHeight` sumiu: folha abraça o conteúdo, e uma altura mínima só servia para
+    // desenhar vazio.
+    lista: {
+        maxHeight: "90%",
+        borderTopLeftRadius: t.size.radiusCard, borderTopRightRadius: t.size.radiusCard,
+        backgroundColor: t.color.popover, borderWidth: t.size.borderWidth, borderColor: t.color.border,
+    },
+    // O puxador, copiado do `BottomSheet` (`overlays.tsx:111-112`) — mesma medida, mesmo token.
+    puxadorArea: { alignItems: "center", paddingVertical: t.size.space2 },
+    puxador: { width: 40, height: 4, borderRadius: t.size.radiusFull,
+        backgroundColor: t.color.borderStrong },
+    // 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 = ESPERA_PADRAO, loading, onEndReached, placeholder, searchPlaceholder, empty, clearable = true, draggable = 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("");
+    const reduzir = useReduceMotion();
+    // ── 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 ARRASTO, copiado do `BottomSheet` do Lote 5 (`overlays.tsx:427-451`) ──────────────────
+    // Os números são os DE LÁ, não novos: 6dp para reivindicar, limiar de 80dp ou um terço da
+    // altura, velocidade 1.2. Copiar em vez de reinventar é o que mantém as duas folhas com o
+    // mesmo tato — e é a regra do `BUILDING.md` sobre não criar escala nova no meio de um
+    // componente.
+    const arrasto = React.useRef(new Animated.Value(0)).current;
+    const altura = React.useRef(0);
+    React.useEffect(() => { if (!aberto)
+        arrasto.setValue(0); }, [aberto, arrasto]);
+    const gestos = React.useMemo(() => PanResponder.create({
+        onMoveShouldSetPanResponder: (_e, g) => draggable && g.dy > 6,
+        onPanResponderMove: (_e, g) => { if (g.dy > 0)
+            arrasto.setValue(g.dy); },
+        onPanResponderRelease: (_e, g) => {
+            const limiar = Math.max(80, altura.current / 3);
+            if (g.dy > limiar || g.vy > 1.2) {
+                fechar();
+                return;
+            }
+            if (reduzir !== false) {
+                arrasto.setValue(0);
+                return;
+            }
+            Animated.timing(arrasto, {
+                toValue: 0, duration: t.size.durationSlow, useNativeDriver: true,
+                easing: Easing.bezier(...t.easing.easeEmphasized),
+            }).start();
+        },
+    }), [draggable, fechar, arrasto, reduzir, t.size.durationSlow, t.easing.easeEmphasized]);
+    // ── 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: reduzir !== false ? "none" : "slide", statusBarTranslucent: true, navigationBarTranslucent: true, onRequestClose: fechar, children: _jsxs(KeyboardAvoiding, { style: s.fundoDaLista, children: [_jsx(Pressable, { style: s.fundoDeToque, onPress: fechar, accessible: false, testID: testID ? `${testID}-fundo` : undefined }), _jsxs(Animated.View, { style: [s.lista, { transform: [{ translateY: arrasto }] }], onLayout: (e) => { altura.current = e.nativeEvent.layout.height; }, onStartShouldSetResponder: () => true, children: [_jsx(View, { style: s.puxadorArea, ...(draggable ? gestos.panHandlers : null), accessibilityElementsHidden: true, importantForAccessibility: "no-hide-descendants", children: _jsx(View, { style: s.puxador }) }), _jsxs(View, { style: [s.grupo, { height: alturaDoTamanho(t, tam) }], ...(draggable ? gestos.panHandlers : null), 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: ANTECEDENCIA_DE_PAGINA, 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 = ESPERA_PADRAO, 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";

package/dist/inputs.d.ts

@@ -61,10 +61,34 @@ export interface InputProps {
     /**
      * O teclado que sobe. **O plano do consumidor pede `numeric` nos campos de medida e moeda**, e
      * é a prop que faz a diferença entre digitar 12,4 em dois toques ou em oito.
+     *
+     * ⚠ **Teclado não é formato, e esta prop resolve só a metade fácil** — foi a segunda lacuna
+     * que o consumidor mediu. Moeda, medida decimal e contador são o `NumberField` (Lote 7,
+     * `numero.tsx`), que formata no blur e devolve `number`. Este campo continua devolvendo texto.
      */
     keyboardType?: KeyboardTypeOptions;
     secureTextEntry?: boolean;
     autoCapitalize?: "none" | "sentences" | "words" | "characters";
+    /**
+     * Normaliza o texto **quando o foco sai** — placa, documento, telefone.
+     *
+     * ⚠ **A Aurea entrega o MOMENTO, não o formato**, e isso é a [ADR-0024] inteira: formatar
+     * enquanto se digita é o defeito que o USWDS publicou com reprovação WCAG registrada e que o
+     * MUI abandonou na v6. O formato é conhecimento de DOMÍNIO — a Aurea não sabe o que é um
+     * documento válido em lugar nenhum, e uma tabela de formatos por país dentro de uma biblioteca
+     * de interface envelhece sem ninguém perceber.
+     *
+     *     <Input value={placa} onChangeText={setPlaca} formatOnBlur={(v) => v.toUpperCase()} />
+     *
+     * ⚠ **Exige o campo CONTROLADO** (`value` + `onChangeText`), e a diferença com a web é honesta:
+     * lá o componente escreve em `e.currentTarget.value` e o `<input>` não controlado obedece. Aqui
+     * o texto do `TextInput` não controlado vive dentro do nó nativo, e escrevê-lo de fora exigiria
+     * `setNativeProps` — API que a Nova Arquitetura desencoraja. Então o que sai daqui é o valor
+     * formatado por `onChangeText`; quem guarda o estado desenha.
+     *
+     * Para MOEDA e MEDIDA não use isto: use o `NumberField`, que já faz a conta e devolve `number`.
+     */
+    formatOnBlur?: (value: string) => string;
     onBlur?: () => void;
     onFocus?: () => void;
     /** Várias linhas. É o que o `Textarea` liga — raramente se põe à mão. */
@@ -79,7 +103,7 @@ export interface InputProps {
  * (`aurea.css:686`); **não há ponteiro no telefone**. O foco continua existindo e é o que marca o
  * campo ativo.
  */
-export declare function Input({ value, defaultValue, onChangeText, placeholder, disabled, size, keyboardType, secureTextEntry, autoCapitalize, onBlur, onFocus, multiline, style, testID, }: InputProps): React.JSX.Element;
+export declare function Input({ value, defaultValue, onChangeText, placeholder, disabled, size, keyboardType, secureTextEntry, autoCapitalize, formatOnBlur, onBlur, onFocus, multiline, style, testID, }: InputProps): React.JSX.Element;
 export interface TextareaProps extends InputProps {
     /** Linhas visíveis. Vira altura mínima, porque no RN não há `rows`. */
     rows?: number;
@@ -169,6 +193,12 @@ export interface SelectProps {
  * ⚠ **O papel é `button` e não `combobox`.** `combobox` promete um campo em que se DIGITA para
  * filtrar; isto só abre uma lista. Prometer o que não se faz é o mesmo defeito do `tablist` no
  * Lote 3.
+ *
+ * ⚠ **Quem DIGITA para filtrar é o `Combobox`** (Lote 7, `busca.tsx`), e ele nasceu desta
+ * lacuna — o consumidor bateu nela no cadastro. **A escolha entre os dois é de tamanho de
+ * lista, e a linha é dura:** este monta todos os itens num `ScrollView` (abaixo), o que serve
+ * para unidades, estados e tipos; um catálogo de milhares de linhas aqui não fica lento, trava.
+ * O `Combobox` usa `FlatList` e aceita busca remota.
  */
 export declare function Select({ items, value, onChange, placeholder, disabled, size, chevron, style, testID, }: SelectProps): React.JSX.Element;
 export interface FormProps extends ViewProps {

package/dist/inputs.js

@@ -147,14 +147,25 @@ export function Label({ children, trailing, style, ...rest }) {
  * (`aurea.css:686`); **não há ponteiro no telefone**. O foco continua existindo e é o que marca o
  * campo ativo.
  */
-export function Input({ value, defaultValue, onChangeText, placeholder, disabled, size, keyboardType, secureTextEntry, autoCapitalize, onBlur, onFocus, multiline, style, testID, }) {
+export function Input({ value, defaultValue, onChangeText, placeholder, disabled, size, keyboardType, secureTextEntry, autoCapitalize, formatOnBlur, onBlur, onFocus, multiline, style, testID, }) {
     const t = useAureaTokens();
     const s = folha(t);
     const campo = useCampo();
     const tam = size ?? campo?.size ?? "md";
     const inativo = disabled ?? campo?.disabled;
     const [focado, setFocado] = React.useState(false);
-    return (_jsx(TextInput, { testID: testID, value: value, defaultValue: defaultValue, onChangeText: onChangeText, placeholder: placeholder, placeholderTextColor: t.color.subtleForeground, editable: !inativo, keyboardType: keyboardType, secureTextEntry: secureTextEntry, autoCapitalize: autoCapitalize, multiline: multiline, onFocus: () => { setFocado(true); onFocus?.(); }, onBlur: () => { setFocado(false); onBlur?.(); }, 
+    return (_jsx(TextInput, { testID: testID, value: value, defaultValue: defaultValue, onChangeText: onChangeText, placeholder: placeholder, placeholderTextColor: t.color.subtleForeground, editable: !inativo, keyboardType: keyboardType, secureTextEntry: secureTextEntry, autoCapitalize: autoCapitalize, multiline: multiline, onFocus: () => { setFocado(true); onFocus?.(); }, onBlur: () => {
+            setFocado(false);
+            // Só avisa quando o texto MUDOU: emitir o mesmo valor a cada saída de foco faria o app
+            // re-renderizar sem motivo, e num formulário de dez campos isso é dez renders por
+            // preenchimento. Mesma guarda da web (`inputs-client.tsx:194`).
+            if (formatOnBlur && value != null) {
+                const formatado = formatOnBlur(value);
+                if (formatado !== value)
+                    onChangeText?.(formatado);
+            }
+            onBlur?.();
+        }, 
         // O nome e a dica vêm do `Field` — ver o bloco acima sobre por que a ligação da web não
         // atravessa. Sem isto, o campo é um nó anônimo para o leitor de tela.
         accessibilityLabel: campo?.label, accessibilityHint: campo?.hint, accessibilityState: { disabled: !!inativo }, "aria-invalid": campo?.invalido, style: [
@@ -319,6 +330,12 @@ export function SegmentedControl({ items, value, onChange, label, disabled, styl
  * ⚠ **O papel é `button` e não `combobox`.** `combobox` promete um campo em que se DIGITA para
  * filtrar; isto só abre uma lista. Prometer o que não se faz é o mesmo defeito do `tablist` no
  * Lote 3.
+ *
+ * ⚠ **Quem DIGITA para filtrar é o `Combobox`** (Lote 7, `busca.tsx`), e ele nasceu desta
+ * lacuna — o consumidor bateu nela no cadastro. **A escolha entre os dois é de tamanho de
+ * lista, e a linha é dura:** este monta todos os itens num `ScrollView` (abaixo), o que serve
+ * para unidades, estados e tipos; um catálogo de milhares de linhas aqui não fica lento, trava.
+ * O `Combobox` usa `FlatList` e aceita busca remota.
  */
 export function Select({ items, value, onChange, placeholder, disabled, size, chevron = "chevron--down", style, testID, }) {
     const t = useAureaTokens();

package/dist/midia.d.ts

@@ -0,0 +1,98 @@
+import * as React from "react";
+import { type ImageSourcePropType, type StyleProp, type ViewStyle } from "react-native";
+import { type IconName } from "./icon.js";
+/** URL ou `require()` de um asset local — as duas formas do `Image` do RN, como no `Avatar`. */
+export type AureaImageSource = ImageSourcePropType | string;
+export interface ImageProps {
+    source: AureaImageSource;
+    /**
+     * O nome acessível. **É o `alt` da web, e é obrigatório pelo mesmo motivo que o `label` do
+     * `IconButton`:** uma foto sem texto alternativo não diz nada a quem não a vê. Decorativa de
+     * verdade se escreve `alt=""` — explícito, como manda a WAI.
+     */
+    alt: string;
+    /** `16/9`, `"16/9"`, `"16:9"` ou `1.777…`. Sem ela, a imagem ocupa a altura que o `style` der. */
+    ratio?: number | string;
+    fit?: "cover" | "contain";
+    /** O que aparece no lugar quando o bitmap não vem. Sem ele, o glifo `image` sobre a caixa reservada. */
+    fallback?: React.ReactNode;
+    /** O glifo do substituto. Registre-o, ou passe `false`. */
+    fallbackIcon?: IconName | false;
+    /**
+     * Desenha OUTRO componente de imagem com a nossa pele — é o caso do consumidor que já usa
+     * `expo-image` por cache de disco.
+     *
+     *     <Image render={<ExpoImage contentFit="cover" transition={150} />} source={u} alt="…" />
+     *
+     * Recebe `source`, `style`, `onError` e o nome acessível. **`fit` NÃO é traduzido para ele** —
+     * `resizeMode` é do `Image` do RN, e o `expo-image` chama a mesma coisa de `contentFit`; quem
+     * passa o elemento escreve a prop dele.
+     */
+    render?: React.ReactElement;
+    onError?: () => void;
+    style?: StyleProp<ViewStyle>;
+    testID?: string;
+}
+/**
+ * A foto, com a caixa reservada e um substituto quando ela não vem.
+ *
+ * ```tsx
+ * <Image source={foto.uri} alt="Frente do item" ratio="4/3" />
+ * ```
+ *
+ * ⚠ **A caixa nasce reservada e pintada** com a mesma superfície do `Skeleton` — sem `ratio`, o
+ * layout salta quando o bitmap chega, e num telefone esse salto acontece com o dedo já a caminho
+ * do botão.
+ *
+ * ⚠ **O substituto continua sendo a imagem para quem usa leitor de tela**, com o mesmo `alt`.
+ * Trocar o bitmap por uma caixa muda o que se vê, não o que a foto É — e o `role="image"` mapeia
+ * nos dois sistemas (`ReactAccessibilityDelegate.kt:461`, `RCTConversions.h:96`).
+ */
+export declare function Image({ source, alt, ratio, fit, fallback, fallbackIcon, render, onError, style, testID, }: ImageProps): React.JSX.Element;
+export interface AureaGalleryItem {
+    id: string;
+    source: AureaImageSource;
+    alt: string;
+    caption?: React.ReactNode;
+}
+export interface GalleryProps {
+    items: AureaGalleryItem[];
+    /** O nome da grade para o leitor de tela. Sem ele, a frase `galleryLabel` do provider. */
+    label?: string;
+    /** O `id` escolhido. **A galeria não guarda escolha** — é constante do app, como na web. */
+    selected?: string;
+    onSelect?: (id: string) => void;
+    /** Tocar abre a foto grande no `Dialog` que já existe. */
+    zoom?: boolean;
+    /** Proporção dos ladrilhos. Padrão **1** (quadrado), como o `ratio="1/1"` da web. */
+    ratio?: number | string;
+    /**
+     * Largura mínima de cada ladrilho, em dp. O `--gallery-min` da web é `8rem` — e `1rem = 16dp`,
+     * medido, então **128**.
+     */
+    minTileWidth?: number;
+    style?: StyleProp<ViewStyle>;
+    testID?: string;
+}
+/**
+ * A grade de fotos, e a foto grande quando se toca.
+ *
+ * ```tsx
+ * <Gallery items={fotos} zoom selected={atual} onSelect={setAtual} />
+ * ```
+ *
+ * ⚠ **Ampliar é DIÁLOGO, e diálogo já existe.** É a trava que a web escreveu no item L2 e ela
+ * atravessa inteira: a foto grande abre no `Dialog` do Lote 5, com o confinamento de foco que o
+ * `Modal` do RN dá pelo sistema e a saída pelo botão VOLTAR do Android. Uma segunda superfície
+ * flutuante aqui seria uma segunda linguagem.
+ *
+ * ⚠ **Legenda visível torna a miniatura decorativa**, e quem exigiu isso na web foi o axe, não a
+ * teoria: com `alt` e legenda dizendo a mesma coisa, o leitor de tela anuncia duas vezes seguidas.
+ * Aqui a tradução é outra (não há `alt=""` no RN) mas a regra é a mesma — **com legenda, quem
+ * carrega o nome é o LADRILHO, e a imagem sai da árvore**. O `alt` não se perde: ele continua
+ * nomeando a foto ampliada, que é onde não há legenda ao lado.
+ *
+ * ⚠ **Sem `onSelect` e sem `zoom` os ladrilhos não são alvos.** Um `Pressable` que não faz nada é
+ * um alvo que engana quem navega por leitor de tela — mesma decisão da web, mesma razão.
+ */
+export declare function Gallery({ items, label, selected, onSelect, zoom, ratio, minTileWidth, style, testID, }: GalleryProps): React.JSX.Element;