@softize/opus 8.6.6

package/src/ui/drivers/react.tsx

@@ -0,0 +1,627 @@
+/**
+ * @softize/opus/ui/react — React driver
+ *
+ * Hooks + Provider pra invocar actions client-side.
+ *   - `TbdlibProvider` — injeta ClientAdapter no contexto
+ *   - `useAction(action)` — invoca actions simple/form/view
+ *   - `useLookupAction(action)` — variante pra search (output Paginated)
+ *
+ * Compatível com React 18 e 19. Não dona estado global de cache —
+ * cada hook mantém o seu (suficiente pra v0). Integração com
+ * TanStack Query fica em `@softize/opus/client/tanstack` no futuro.
+ */
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useMemo,
+  useState,
+  type ReactNode,
+} from 'react'
+import {
+  useForm,
+  type DefaultValues,
+  type FieldValues,
+  type UseFormReturn,
+} from 'react-hook-form'
+import { zodResolver } from '@hookform/resolvers/zod'
+import { keepPreviousData, useQuery, useQueryClient } from '@tanstack/react-query'
+import type { ZodType } from 'zod'
+import type {
+  ActionContract,
+  ActionDef,
+  ActionError,
+  ClientAdapter,
+  FormContract,
+  Paginated,
+} from '../../core/index.ts'
+import {
+  type ActionState,
+  type ListState,
+  idleAction,
+  idleLookup,
+} from '../index.ts'
+import { zodErrorMapPtBr } from '../lib/zod-pt-br.ts'
+
+// =============================================================================
+// Provider
+// =============================================================================
+
+/**
+ * Dicionário estrutural pro resolvedor de `options: { kind: 'dictionary', ref }`:
+ * qualquer coisa com `options()` → `{ value, label }`. O `DictType` do `t.dict`
+ * satisfaz direto — sem este driver importar o driver de schema.
+ */
+export interface DictLike {
+  options(): Array<{ value: string; label: string }>
+}
+
+interface TbdlibContextValue {
+  client: ClientAdapter
+  dicts: Record<string, DictLike>
+}
+
+const TbdlibContext = createContext<TbdlibContextValue | null>(null)
+
+export interface TbdlibProviderProps {
+  client: ClientAdapter
+  /** Dicionários por ref — resolvem `options: { kind: 'dictionary', ref }` de
+   *  filters/fields (ActionList/ActionForm). Campo de dict sem registro aqui ainda
+   *  resolve pelo fallback (a meta do `t.dict` viaja no schema do contrato). */
+  dicts?: Record<string, DictLike>
+  children: ReactNode
+}
+
+export function TbdlibProvider({
+  client,
+  dicts,
+  children,
+}: TbdlibProviderProps): ReactNode {
+  const value = useMemo<TbdlibContextValue>(() => ({ client, dicts: dicts ?? {} }), [client, dicts])
+  return <TbdlibContext.Provider value={value}>{children}</TbdlibContext.Provider>
+}
+
+function useClient(): ClientAdapter {
+  const ctx = useContext(TbdlibContext)
+  if (ctx === null) {
+    throw new Error(
+      'useAction/useLookupAction must be used inside <TbdlibProvider>',
+    )
+  }
+  return ctx.client
+}
+
+const NO_DICTS: Record<string, DictLike> = {}
+
+/** Dicts do provider. Default {} — inclusive fora do provider: o resolvedor cai
+ *  nos fallbacks (estáticas do spec, meta do `t.dict`) sem exigir registry. */
+export function useDicts(): Record<string, DictLike> {
+  return useContext(TbdlibContext)?.dicts ?? NO_DICTS
+}
+
+// =============================================================================
+// useAction
+// =============================================================================
+
+export interface UseActionResult<TInput, TData> extends ActionState<TData> {
+  run: (input: TInput) => Promise<ActionState<TData>>
+  reset: () => void
+}
+
+export function useAction<TInput = unknown, TData = unknown>(
+  action: ActionDef,
+): UseActionResult<TInput, TData> {
+  const client = useClient()
+  const [state, setState] = useState<ActionState<TData>>(() => idleAction<TData>())
+
+  const run = useCallback(
+    async (input: TInput): Promise<ActionState<TData>> => {
+      setState({
+        data: undefined,
+        error: undefined,
+        isIdle: false,
+        isLoading: true,
+        isSuccess: false,
+        isError: false,
+      })
+
+      const result = await client.run<TData>(action, input)
+
+      const next: ActionState<TData> = result.ok
+        ? {
+            data: result.data,
+            error: undefined,
+            isIdle: false,
+            isLoading: false,
+            isSuccess: true,
+            isError: false,
+          }
+        : {
+            data: undefined,
+            error: result.error,
+            isIdle: false,
+            isLoading: false,
+            isSuccess: false,
+            isError: true,
+          }
+
+      setState(next)
+      return next
+    },
+    [client, action],
+  )
+
+  const reset = useCallback(() => {
+    setState(idleAction<TData>())
+  }, [])
+
+  return { ...state, run, reset }
+}
+
+// =============================================================================
+// useLookupAction
+// =============================================================================
+
+export interface UseLookupActionResult<TInput, TItem>
+  extends ListState<TItem> {
+  run: (input: TInput) => Promise<ListState<TItem>>
+  reset: () => void
+}
+
+export function useLookupAction<TInput = unknown, TItem = unknown>(
+  action: ActionDef,
+): UseLookupActionResult<TInput, TItem> {
+  const client = useClient()
+  const [state, setState] = useState<ListState<TItem>>(() => idleLookup<TItem>())
+
+  const run = useCallback(
+    async (input: TInput): Promise<ListState<TItem>> => {
+      setState((prev) => ({
+        ...prev,
+        error: undefined,
+        isIdle: false,
+        isLoading: true,
+        isSuccess: false,
+        isError: false,
+      }))
+
+      const result = await client.run<Paginated<TItem>>(action, input)
+
+      const next: ListState<TItem> = result.ok
+        ? {
+            items: result.data.items,
+            cursor: result.data.cursor,
+            total: result.data.total,
+            error: undefined,
+            isIdle: false,
+            isLoading: false,
+            isSuccess: true,
+            isError: false,
+          }
+        : {
+            items: [],
+            cursor: { next: null },
+            total: undefined,
+            error: result.error,
+            isIdle: false,
+            isLoading: false,
+            isSuccess: false,
+            isError: true,
+          }
+
+      setState(next)
+      return next
+    },
+    [client, action],
+  )
+
+  const reset = useCallback(() => {
+    setState(idleLookup<TItem>())
+  }, [])
+
+  return { ...state, run, reset }
+}
+
+// =============================================================================
+// useListAction
+// =============================================================================
+//
+// Lista QUERY-BACKED de uma search action: busca no mount e cacheia em
+// queryKey [action.name, input]. É o par do `action.invalidates` — quando um
+// form/trigger invalida 'x.list', toda lista montada com este hook refaz
+// sozinha (invalidateQueries casa por prefixo do queryKey).
+//
+// Difere do useLookupAction (imperativo, run() sob demanda, pro ActionList):
+// aqui o fetch é declarativo — montou, buscou. Pre-requisito: <QueryClientProvider>.
+
+export interface UseListActionResult<TItem> {
+  items: TItem[]
+  total: number | undefined
+  error: ActionError | undefined
+  /** Primeiro load (sem dado nenhum ainda) — o skeleton. */
+  isLoading: boolean
+  /** Qualquer busca em andamento (inclui refetch com dados na tela). */
+  isFetching: boolean
+  isSuccess: boolean
+  isError: boolean
+  /** Força re-fetch (além da invalidação declarativa via action.invalidates). */
+  refetch: () => Promise<void>
+}
+
+// O param é estrutural (name + kind) de propósito: ListContract é invariante no
+// input, o que quebraria a chamada `useListAction<Row>(contract)` quando o contrato
+// tem filtros opcionais. O hook só usa name/kind; o item é tipado pelo caller.
+export function useListAction<TItem = unknown, TInput extends Record<string, unknown> = Record<string, unknown>>(
+  action: { name: string; kind: 'list' },
+  input?: TInput,
+): UseListActionResult<TItem> {
+  const client = useClient()
+
+  const query = useQuery<Paginated<TItem>, ActionError>({
+    queryKey: [action.name, input ?? {}],
+    queryFn: async () => {
+      const result = await client.run<Paginated<TItem>>(action as unknown as ActionDef, input ?? {})
+      if (!result.ok) throw result.error
+      return result.data
+    },
+    // Input mudou (filtro/página) → mantém os itens na tela enquanto busca: o
+    // ActionList esmaece em vez de piscar skeleton. isPending = só o 1º load.
+    placeholderData: keepPreviousData,
+  })
+
+  const refetch = useCallback(async () => {
+    await query.refetch()
+  }, [query])
+
+  const isLoading = query.isPending
+  return {
+    items: query.data?.items ?? [],
+    total: query.data?.total,
+    error: query.error ?? undefined,
+    isLoading,
+    // Busca em andamento COM dados na tela (troca de recorte, invalidates, refetch).
+    isFetching: query.isFetching,
+    isSuccess: query.isSuccess,
+    isError: query.isError,
+    refetch,
+  }
+}
+
+// =============================================================================
+// useFormAction
+// =============================================================================
+//
+// Pre-requisito: app está envolvido em `<QueryClientProvider>` do TanStack
+// Query. Sem ele, useFormAction lança no primeiro render.
+//
+// Usa react-hook-form internamente. Se `action.input` é um Zod schema,
+// validation client-side roda automaticamente via zodResolver. Submit
+// invoca `client.run(action, input)`; em sucesso, invalida queryKeys
+// derivadas de `action.invalidates` automaticamente.
+
+export interface UseFormActionOptions<TInput extends FieldValues, TData> {
+  /** Valores iniciais do form. Mesmo shape do input da action. */
+  defaultValues?: DefaultValues<TInput>
+  /** Callback chamado ao sucesso. Cache invalidation acontece antes do callback. */
+  onSuccess?: (data: TData) => void | Promise<void>
+  /** Callback chamado em erro (validation client-side passou mas servidor rejeitou). */
+  onError?: (error: ActionError) => void
+}
+
+export interface UseFormActionResult<TInput extends FieldValues, TData>
+  extends ActionState<TData> {
+  /** RHF form methods — passe `{...form.formMethods}` no `<Form>` do shadcn. */
+  form: UseFormReturn<TInput>
+  /** Handler pronto pra usar em `<form onSubmit={submit}>`. */
+  submit: (event?: React.BaseSyntheticEvent) => Promise<void>
+  /** Reseta form + estado de execução. */
+  reset: () => void
+}
+
+/**
+ * Normaliza strings vazias do form conforme o schema — reproduz o `trim() || null`
+ * dos forms à mão: campo NULLABLE → null (limpa no servidor); só OPTIONAL → undefined
+ * (omite, não mexe); obrigatório → mantém '' (o zod acusa). Anda pelos wrappers via
+ * _def.typeName (string, sem instanceof — atravessa zod v3/v4; se não reconhecer,
+ * passa reto, fail-open).
+ */
+function normalizeEmptyStrings(schema: unknown, values: Record<string, unknown>): Record<string, unknown> {
+  const shape = (schema as { shape?: Record<string, unknown> } | null)?.shape
+  if (shape === undefined || shape === null) return values
+  const out: Record<string, unknown> = { ...values }
+  for (const [key, value] of Object.entries(out)) {
+    if (value !== '') continue
+    let node = shape[key] as { _def?: { typeName?: string; innerType?: unknown } } | undefined
+    let nullable = false
+    let optional = false
+    while (
+      node?._def?.typeName === 'ZodOptional' ||
+      node?._def?.typeName === 'ZodNullable' ||
+      node?._def?.typeName === 'ZodDefault'
+    ) {
+      if (node._def.typeName === 'ZodNullable') nullable = true
+      else optional = true
+      node = node._def.innerType as typeof node
+    }
+    if (nullable) out[key] = null
+    else if (optional) delete out[key]
+  }
+  return out
+}
+
+export function useFormAction<
+  TInput extends FieldValues = FieldValues,
+  TData = unknown,
+>(
+  action: FormContract<TInput, TData>,
+  options: UseFormActionOptions<TInput, TData> = {},
+): UseFormActionResult<TInput, TData> {
+  const client = useClient()
+  const queryClient = useQueryClient()
+
+  const resolver = useMemo(() => {
+    // action.input é Schema<TInput>. Se for Zod, embrulhamos com zodResolver.
+    // Caso seja outra implementação de StandardSchemaV1, fica sem resolver
+    // (servidor ainda valida no fail-closed pipeline).
+    const schema = action.input as unknown as ZodType<TInput>
+    if (
+      schema !== null &&
+      typeof schema === 'object' &&
+      '_def' in schema &&
+      typeof (schema as { parse?: unknown }).parse === 'function'
+    ) {
+      // Cast version-agnostic: há zod v3 e v4 no monorepo e qual o Opus resolve varia
+      // por install (passava local, quebrava na VPS). O guard de runtime acima já
+      // garante que é um schema Zod; o tipo exato não importa pro zodResolver.
+      // errorMap = dicionário pt-BR (mensagem específica no schema tem precedência).
+      return zodResolver(
+        schema as unknown as Parameters<typeof zodResolver>[0],
+        { errorMap: zodErrorMapPtBr } as never,
+      )
+    }
+    return undefined
+  }, [action.input])
+
+  const form = useForm<TInput>({
+    ...(resolver !== undefined ? { resolver } : {}),
+    ...(options.defaultValues !== undefined
+      ? { defaultValues: options.defaultValues }
+      : {}),
+  })
+
+  const [state, setState] = useState<ActionState<TData>>(() =>
+    idleAction<TData>(),
+  )
+
+  const submit = useMemo(
+    () =>
+      form.handleSubmit(async (input: TInput) => {
+        setState({
+          data: undefined,
+          error: undefined,
+          isIdle: false,
+          isLoading: true,
+          isSuccess: false,
+          isError: false,
+        })
+
+        // O ClientAdapter tipa `run` com ActionDef (action ligado, com handler), mas o
+        // cliente só tem o FormContract — e em runtime o adapter só usa `action.name`.
+        const payload = normalizeEmptyStrings(action.input, input as Record<string, unknown>) as TInput
+        const result = await client.run<TData>(action as unknown as ActionDef, payload)
+
+        if (result.ok) {
+          // Invalidação cache declarativa via action.invalidates
+          const invalidates =
+            typeof action.invalidates === 'function'
+              ? action.invalidates(input)
+              : action.invalidates
+          if (invalidates !== undefined && invalidates.length > 0) {
+            await Promise.all(
+              invalidates.map((key) =>
+                queryClient.invalidateQueries({ queryKey: [key] }),
+              ),
+            )
+          }
+
+          const next: ActionState<TData> = {
+            data: result.data,
+            error: undefined,
+            isIdle: false,
+            isLoading: false,
+            isSuccess: true,
+            isError: false,
+          }
+          setState(next)
+          await options.onSuccess?.(result.data)
+        } else {
+          const next: ActionState<TData> = {
+            data: undefined,
+            error: result.error,
+            isIdle: false,
+            isLoading: false,
+            isSuccess: false,
+            isError: true,
+          }
+          setState(next)
+          options.onError?.(result.error)
+        }
+      }),
+    [form, client, action, queryClient, options],
+  )
+
+  const reset = useCallback(() => {
+    form.reset()
+    setState(idleAction<TData>())
+  }, [form])
+
+  return { ...state, form, submit, reset }
+}
+
+// =============================================================================
+// useViewAction
+// =============================================================================
+//
+// Auto-roda action.run(input) no mount + quando input muda. Pensado pra
+// view actions (kind=view) que carregam um recurso por id, mas funciona
+// pra qualquer action determinística por input.
+//
+// Pre-requisito: app está envolvido em `<QueryClientProvider>` — cache é
+// armazenado em queryKey [action.name, input]. Múltiplos componentes que
+// usam mesmo action+input compartilham o cache automaticamente.
+
+export interface UseViewActionResult<TData> extends ActionState<TData> {
+  /** Força re-fetch (invalida o cache desta queryKey + refetch). */
+  refetch: () => Promise<void>
+}
+
+// O param é estrutural (name + kind) de propósito, como no useListAction: no
+// client só existe o CONTRATO (sem handler) — exigir ViewAction barraria todo
+// callsite `useViewAction(contract, input)`. O hook só usa name/kind.
+export function useViewAction<TInput = unknown, TData = unknown>(
+  action: { name: string; kind: 'view' },
+  input: TInput,
+): UseViewActionResult<TData> {
+  const client = useClient()
+
+  // TanStack Query serializa queryKey → dedupe automático mesmo com input
+  // inline (referência nova a cada render). Sem isso entraria em loop.
+  const query = useQuery<TData, ActionError>({
+    queryKey: [action.name, input],
+    queryFn: async () => {
+      const result = await client.run<TData>(action as unknown as ActionDef, input)
+      if (!result.ok) {
+        throw result.error
+      }
+      return result.data
+    },
+  })
+
+  const refetch = useCallback(async () => {
+    await query.refetch()
+  }, [query])
+
+  // Mapeia 4 estados do TanStack Query (pending/success/error/idle) pros
+  // 5 flags do ActionState. Pending pré-data = loading; sem fetch ainda = idle.
+  const isLoading = query.isPending || query.isFetching
+  const isSuccess = query.isSuccess && !isLoading
+  const isError = query.isError
+  const isIdle = !isLoading && !isSuccess && !isError
+
+  return {
+    data: query.data,
+    error: query.error ?? undefined,
+    isIdle,
+    isLoading,
+    isSuccess,
+    isError,
+    refetch,
+  }
+}
+
+// =============================================================================
+// useTriggerAction
+// =============================================================================
+//
+// Dispara QUALQUER contrato via `trigger(input)` — o caso típico é simple
+// (kind=simple), mas um FormContract submetido fora de form (modal composto)
+// roda igual: o hook só usa name/kind e lê `action.invalidates`.
+//
+// Diferença pra useAction (genérico):
+// - Auto-invalidação via action.invalidates
+// - Callbacks declarativos (onSuccess/onError)
+// - Foco em mutation sem form
+//
+// Pre-requisito: <QueryClientProvider> no app.
+
+export interface UseTriggerActionOptions<TInput, TData> {
+  onSuccess?: (data: TData, input: TInput) => void | Promise<void>
+  onError?: (error: ActionError, input: TInput) => void
+}
+
+export interface UseTriggerActionResult<TInput, TData>
+  extends ActionState<TData> {
+  trigger: (input: TInput) => Promise<ActionState<TData>>
+  reset: () => void
+}
+
+export function useTriggerAction<TInput = unknown, TData = unknown>(
+  action: ActionContract<TInput, TData>,
+  options: UseTriggerActionOptions<TInput, TData> = {},
+): UseTriggerActionResult<TInput, TData> {
+  const client = useClient()
+  const queryClient = useQueryClient()
+  const [state, setState] = useState<ActionState<TData>>(() =>
+    idleAction<TData>(),
+  )
+
+  const trigger = useCallback(
+    async (input: TInput): Promise<ActionState<TData>> => {
+      setState({
+        data: undefined,
+        error: undefined,
+        isIdle: false,
+        isLoading: true,
+        isSuccess: false,
+        isError: false,
+      })
+
+      // Contrato (sem handler) no cliente; o adapter só usa `action.name`/`kind`.
+      const result = await client.run<TData>(action as unknown as ActionDef, input)
+
+      if (result.ok) {
+        // Cast: o braço FormContract do union restringe o input a `& Record<...>`,
+        // mas o TInput do chamador JÁ é o In do contrato passado.
+        const invalidates =
+          typeof action.invalidates === 'function'
+            ? (action.invalidates as (input: TInput) => string[])(input)
+            : action.invalidates
+        if (invalidates !== undefined && invalidates.length > 0) {
+          await Promise.all(
+            invalidates.map((key) =>
+              queryClient.invalidateQueries({ queryKey: [key] }),
+            ),
+          )
+        }
+
+        const next: ActionState<TData> = {
+          data: result.data,
+          error: undefined,
+          isIdle: false,
+          isLoading: false,
+          isSuccess: true,
+          isError: false,
+        }
+        setState(next)
+        await options.onSuccess?.(result.data, input)
+        return next
+      }
+
+      const next: ActionState<TData> = {
+        data: undefined,
+        error: result.error,
+        isIdle: false,
+        isLoading: false,
+        isSuccess: false,
+        isError: true,
+      }
+      setState(next)
+      options.onError?.(result.error, input)
+      return next
+    },
+    [client, action, queryClient, options],
+  )
+
+  const reset = useCallback(() => {
+    setState(idleAction<TData>())
+  }, [])
+
+  return { ...state, trigger, reset }
+}
+
+// =============================================================================
+// Re-exports
+// =============================================================================
+
+export type { ActionError, ActionState, ListState }