@softize/opus 25.4.0 → 25.4.1

package/CHANGELOG.md

@@ -7,6 +7,18 @@ Depois de qualquer bump, rode os gates (`typecheck` · `test` · `opus check` ·
 `opus copy --check` · `base copy check` · `manifest:check`) — eles apontam o que a
 mudança cobra do seu código.
 
+## 25.4.1 — 2026-10-05
+
+Corrige a busca remota de filtros `lookup` quando a `ActionList` também recebe opções iniciais em
+`filterOptions`, como nas dimensões disponíveis para agrupamento. Enquanto há um termo de busca, as
+opções iniciais agora são filtradas localmente e combinadas com o resultado do servidor; antes,
+elas permaneciam todas visíveis e podiam esconder o efeito da busca. Não há migração para o
+consumidor. Valores já selecionados preservam o rótulo durante e depois da busca, inclusive quando
+a opção veio apenas do servidor. Fechar o seletor limpa o termo também no lookup remoto. No
+`Select` com `onSearch`, esse reset é comunicado imediatamente com `""` apenas quando uma busca não
+vazia chegou a ser enviada; abrir e fechar sem digitar não repete a consulta inicial. Respostas
+remotas fora de ordem não substituem mais o resultado da consulta mais recente.
+
 ## 25.4.0 — 2026-10-05
 
 `ListAction.grouping.fields` passa a aceitar filtros `select` ou `lookup` cujas opções completas

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "25.4.0",
+  "version": "25.4.1",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",

package/src/ui/components/patterns/list.tsx

@@ -516,14 +516,16 @@ function useLookupOptions(
 ): {
   options: SelectOption[];
   loading: boolean;
+  query: string;
   onSearch?: (q: string) => void;
 } {
+  const [query, setQuery] = useState("");
   const lookup = spec.options?.kind === "lookup" ? spec.options : undefined;
   const search = useLookupAction<Record<string, unknown>, SelectOption>({
     name: lookup?.source ?? "noop",
     kind: "list",
   } as unknown as ActionDef);
-  if (lookup === undefined) return { options: [], loading: false };
+  if (lookup === undefined) return { options: [], loading: false, query: "" };
   const depInput: Record<string, unknown> = {};
   for (const d of lookup.depends ?? []) {
     if (!isEmptyValue(allValues[d])) depInput[d] = allValues[d];
@@ -534,7 +536,9 @@ function useLookupOptions(
       label: i.label,
     })),
     loading: search.isLoading,
+    query,
     onSearch: (q: string) => {
+      setQuery(q);
       void search.run({ ...(q !== "" ? { q } : {}), ...depInput });
     },
   };
@@ -577,21 +581,66 @@ function FilterField({
   );
   const lookup = useLookupOptions(spec, allValues);
   const dicts = useDicts();
+  const resolvedOptionByValue = useRef(new Map<string, SelectOption>());
   // Precedência: runtime/estáticas (prop `options`) > dictionary do provider;
   // sem nenhuma, as do lookup (server-side).
   const base = options.length > 0 ? options : dictOptionsFor(spec, dicts);
+  const baseByValue = new Map(base.map((option) => [option.value, option]));
+  const canonicalLookupOptions = lookup.options.map(
+    (option) => baseByValue.get(option.value) ?? option,
+  );
+  for (const option of canonicalLookupOptions) {
+    if (!resolvedOptionByValue.current.has(option.value)) {
+      resolvedOptionByValue.current.set(option.value, option);
+    }
+  }
+  for (const option of base) {
+    resolvedOptionByValue.current.set(option.value, option);
+  }
+  const selectedValues = new Set(
+    Array.isArray(value)
+      ? value.filter((item): item is string => typeof item === "string")
+      : typeof value === "string"
+        ? value === ""
+          ? []
+          : [value]
+        : defaultValue === ""
+          ? []
+          : [defaultValue],
+  );
+  const runtimeOptions =
+    lookup.onSearch !== undefined && lookup.query !== ""
+      ? base.filter((option) =>
+          selectedValues.has(option.value) ||
+          option.label
+            .toLocaleLowerCase()
+            .includes(lookup.query.toLocaleLowerCase()),
+        )
+      : base;
+  const selectedResolvedOptions = [...selectedValues]
+    .map((selectedValue) => resolvedOptionByValue.current.get(selectedValue))
+    .filter((option): option is SelectOption => option !== undefined);
+  const mergeUniqueOptions = (
+    ...groups: SelectOption[][]
+  ): SelectOption[] => {
+    const merged = new Map<string, SelectOption>();
+    for (const group of groups) {
+      for (const option of group) {
+        if (!merged.has(option.value)) merged.set(option.value, option);
+      }
+    }
+    return [...merged.values()];
+  };
   const effOptions =
     lookup.onSearch !== undefined && base.length > 0
-      ? [
-          ...base,
-          ...lookup.options.filter(
-            (candidate) =>
-              !base.some((option) => option.value === candidate.value),
-          ),
-        ]
+      ? mergeUniqueOptions(
+          runtimeOptions,
+          canonicalLookupOptions,
+          selectedResolvedOptions,
+        )
       : base.length > 0
         ? base
-        : lookup.options;
+        : mergeUniqueOptions(canonicalLookupOptions, selectedResolvedOptions);
   const singleValue = (value as string | undefined) ?? defaultValue;
   const changedFromDefault = singleValue !== defaultValue;
   const acceptsEmptyValue = spec.allowEmpty !== false;

package/src/ui/components/primitives/select.tsx

@@ -95,7 +95,7 @@ interface SelectCustomBase extends SelectBaseProps {
   /** Liga a busca no próprio campo (lista longa/que cresce). */
   searchable?: boolean;
   /** Busca SERVER-SIDE (debounced): quando definida, o filtro local desliga e o pai
-   *  atualiza `options`. Implica `searchable`. */
+   *  atualiza `options`. Implica `searchable`; ao fechar, limpa uma busca enviada. */
   onSearch?: (query: string) => void;
   /** "Buscando…" enquanto o fetch corre (use com `onSearch`). */
   loading?: boolean;
@@ -279,6 +279,10 @@ function CustomSelect(
   /** Fechando por Esc: o foco volta pro gatilho, e focar abre. Marca pra ignorar UM foco. */
   const closingRef = React.useRef(false);
   const searchRef = React.useRef<HTMLInputElement>(null);
+  const wasOpenRef = React.useRef(false);
+  const lastSearchedQueryRef = React.useRef("");
+  const onSearchRef = React.useRef(onSearch);
+  onSearchRef.current = onSearch;
 
   const selectedOption = options.find((o) => o.value === singleValue);
 
@@ -303,7 +307,14 @@ function CustomSelect(
    * reabrir filtrada por algo que a pessoa procurou minutos antes e já esqueceu.
    */
   React.useEffect(() => {
-    if (!open) setQuery("");
+    if (!open && wasOpenRef.current) {
+      setQuery("");
+      if (lastSearchedQueryRef.current !== "") {
+        lastSearchedQueryRef.current = "";
+        onSearchRef.current?.("");
+      }
+    }
+    wasOpenRef.current = open;
   }, [open]);
 
   // O cmdk carimba o id DELE no input (a11y interna) e descarta o nosso — reaplicamos por
@@ -312,11 +323,13 @@ function CustomSelect(
     if (id !== undefined && inputRef.current !== null) inputRef.current.id = id;
   }, [id]);
 
-  const onSearchRef = React.useRef(onSearch);
-  onSearchRef.current = onSearch;
   React.useEffect(() => {
     if (onSearchRef.current === undefined || !open) return;
-    const t = setTimeout(() => onSearchRef.current?.(query.trim()), 200);
+    const t = setTimeout(() => {
+      const normalizedQuery = query.trim();
+      lastSearchedQueryRef.current = normalizedQuery;
+      onSearchRef.current?.(normalizedQuery);
+    }, 200);
     return () => clearTimeout(t);
   }, [query, open]);
 

package/src/ui/docs/content/action-list.md

@@ -409,7 +409,10 @@ render(
 - **`options: { kind: 'dictionary', ref: 'sessionStatus' }`:** resolve opções e rótulos por um
   dicionário registrado no `OpusProvider`. `filterOptions` substitui essa fonte quando informado.
 - **`options: { kind: 'lookup', source: 'x.lookup' }`:** consulta uma action com `{ q }` e os valores
-  das dependências. A resposta segue o formato `{ value, label }`.
+  das dependências. A resposta segue o formato `{ value, label }`. Quando o consumidor também
+  fornece `filterOptions`, essas opções são filtradas localmente pelo termo e combinadas com a
+  resposta remota. Para o mesmo `value`, o rótulo e a apresentação de `filterOptions` prevalecem;
+  valores selecionados preservam o rótulo mesmo depois que a busca é limpa.
 
 ```tsx
 filters: {

package/src/ui/docs/content/select.md

@@ -140,8 +140,10 @@ render(
 
 ## Busca no servidor
 
-Com `onSearch`, o consumidor consulta as opções ao abrir e ao digitar, com debounce. Atualize
-`options` com a resposta e use `loading` durante a consulta. Esse modo já habilita o campo de busca.
+Com `onSearch`, o consumidor consulta as opções ao abrir e ao digitar, com debounce. Ao fechar o
+seletor depois de uma busca, recebe `""` imediatamente para restaurar as opções iniciais; abrir e
+fechar sem digitar não repete a consulta vazia. Atualize `options` com a resposta e use `loading`
+durante a consulta. Esse modo já habilita o campo de busca.
 
 ```tsx preview col md
 const ASSIGNEES = [
@@ -395,7 +397,7 @@ render(
 | `placeholder` | `string` | `'Selecione…'`; sem padrão com `native` | Texto do campo vazio. Com `native`, só existe quando declarado e vira uma opção desabilitada no início da lista. |
 | `searchPlaceholder` | `string` | `'Buscar…'` | Placeholder da linha de busca dentro da lista. |
 | `emptyText` | `string` | `'Nada encontrado.'` | Mensagem quando a busca não acha nada. |
-| `onSearch` | `(query: string) => void` | | Busca no servidor, chamada ao abrir a lista e depois de uma breve pausa na digitação. Desliga o filtro local; o consumidor atualiza `options` com a resposta. |
+| `onSearch` | `(query: string) => void` | | Busca no servidor, chamada ao abrir a lista e depois de uma breve pausa na digitação. Ao fechar depois de uma busca enviada, recebe `""` imediatamente para restaurar as opções iniciais. Desliga o filtro local; o consumidor atualiza `options` com a resposta. |
 | `loading` | `boolean` | | Mostra “Buscando…” enquanto a consulta de `onSearch` está em andamento. |
 | `clearable` | `boolean` | `false` | Mostra, quando há seleção, uma ação que limpa o valor sem abrir a lista. |
 | `icon` | `React.ReactNode` | | Ícone decorativo no início do controle, em `1rem` e no tom atenuado. |

package/src/ui/drivers/react.tsx

@@ -14,6 +14,7 @@
 import {
   useCallback,
   useMemo,
+  useRef,
   useState,
 } from 'react'
 import {
@@ -126,9 +127,11 @@ export function useLookupAction<TInput = unknown, TItem = unknown>(
 ): UseLookupActionResult<TInput, TItem> {
   const client = useClient('useLookupAction')
   const [state, setState] = useState<ListState<TItem>>(() => idleLookup<TItem>())
+  const latestRunRef = useRef(0)
 
   const run = useCallback(
     async (input: TInput): Promise<ListState<TItem>> => {
+      const runId = ++latestRunRef.current
       setState((prev) => ({
         ...prev,
         error: undefined,
@@ -162,13 +165,14 @@ export function useLookupAction<TInput = unknown, TItem = unknown>(
             isError: true,
           }
 
-      setState(next)
+      if (runId === latestRunRef.current) setState(next)
       return next
     },
     [client, action],
   )
 
   const reset = useCallback(() => {
+    latestRunRef.current += 1
     setState(idleLookup<TItem>())
   }, [])