Gerenciamento de Estado em React: Guia Completo (sem overengineering)

// taxonomia de estado em React (mapa mental)
type StateKind =
    | "local_ui"      // toggle, open/close, input simples, hover, step local
    | "screen_logic"  // lógica de tela com múltiplas transições (wizard, filtros complexos)
    | "server_state"  // dados remotos com cache, invalidação, retry, optimistic update
    | "url_state"     // filtros/página/sort no querystring (deep-link e share)
    | "form_state"    // validação, touched/dirty, submit, errors
    | "app_session"   // sessão, permissões, tema, locale
    | "shared_workflow"; // carrinho, draft global, seleção cross-screen, etc.

// useState vs useReducer: quando a tela vira um mini-workflow
type Action =
    | { type: "OPEN" }
    | { type: "CLOSE" }
    | { type: "SET_FILTER"; value: string };
  
  type ScreenState = { isOpen: boolean; filter: string };
  
  function reducer(state: ScreenState, action: Action): ScreenState {
    switch (action.type) {
      case "OPEN": return { ...state, isOpen: true };
      case "CLOSE": return { ...state, isOpen: false };
      case "SET_FILTER": return { ...state, filter: action.value };
      default: return state;
    }
  }

// TanStack Query: defaults, staleTime e invalidação (padrão de times seniors)
// exemplo de padrão: defina defaults consistentes no QueryClient
  const queryClient = new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 30_000, // 30s 'fresh' para evitar refetch agressivo
        gcTime: 5 * 60_000 // ajuste conforme app (padrão é 5 min)
      }
    }
  });
  
  // após uma mutation, invalide a família de queries afetadas
  await queryClient.invalidateQueries({ queryKey: ["users"] });

// RTK Query: separa server-state (API slice) do resto do store
// ideia: server-state fica no api slice (cache + invalidation)
  const api = createApi({
    reducerPath: "api",
    baseQuery: fetchBaseQuery({ baseUrl: "/api" }),
    tagTypes: ["User"],
    endpoints: (builder) => ({
      getUsers: builder.query<User[], void>({
        query: () => "users",
        providesTags: ["User"],
      }),
      updateUser: builder.mutation<User, Partial<User>>({
        query: (body) => ({ url: `users/${body.id}`, method: "PATCH", body }),
        invalidatesTags: ["User"],
      }),
    }),
  });

// Zustand: selectors + actions (padrão de fronteira clara)
type CartItem = { id: string; qty: number };
  
  type CartState = {
    items: CartItem[];
    add: (id: string) => void;
    remove: (id: string) => void;
  };
  
  export const useCartStore = create<CartState>()((set, get) => ({
    items: [],
    add: (id) =>
      set((s) => {
        const existing = s.items.find((i) => i.id === id);
        return {
          items: existing
            ? s.items.map((i) => (i.id === id ? { ...i, qty: i.qty + 1 } : i))
            : [...s.items, { id, qty: 1 }],
        };
      }),
    remove: (id) => set((s) => ({ items: s.items.filter((i) => i.id !== id) })),
  }));
  
  // consumo com selector: assina só o necessário
  const qty = useCartStore((s) => s.items.length);
  const add = useCartStore((s) => s.add);

// checklist rápido de arquitetura de estado
const checklist = [
    "Cada estado tem um 'dono' claro?",
    "Server state tem cache + invalidation (não store genérica)?",
    "UI state fica local por padrão?",
    "URL state está na URL quando precisa ser compartilhável?",
    "Store tem selectors e API de ações (não setters soltos)?",
    "Existe regra de derivação (computed) fora da fonte de verdade?",
    "O que acontece em erro/retry/offline/optimistic update?",
  ];

// mapa de decisão para estratégia de estado
const stateStrategy = {
    localUI: "useState (simples) / useReducer (workflow de tela)",
    screenScopedShared: "Reducer + Context (escopo de uma feature/rota)",
    crossScreenWorkflow: "Store com selectors (Zustand ou Redux Toolkit)",
    serverData: "TanStack Query (ou RTK Query se já usa Redux)",
    urlState: "Querystring / router (deep-link)",
    appSessionConfig: "React Context (dados estáveis) + boundaries claras",
    formState: "React Hook Form / Form libs (evite reinventar)",
  };