@aurea-uds/native 0.7.0 → 0.8.1

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,126 @@
+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;
+    /**
+     * Arrastar o cabeçalho da folha para baixo fecha. Ligado.
+     *
+     * ⚠ **É a ÚNICA saída por gesto no iOS** — lá não há botão VOLTAR, então sem isto restaria só
+     * tocar no fundo. Mesmo gesto, mesmo limiar e mesma curva do `BottomSheet` do Lote 5.
+     */
+    draggable?: 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, draggable, 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;