Skill de Padrões React com TypeScript - Uma receita de skill Claude Code para padrões avançados de TypeScript em React e Next.js

---
name: typescript-react-patterns
description: "Padrões avançados de TypeScript para componentes React e Next.js. Use quando solicitado para: tipar este componente, ajuda com TypeScript, componente genérico, tipagem de props, uniões discriminadas, tipos utilitários, tipagem de hooks, tipagem de server components."
allowed-tools: "Read, Write, Edit, Glob, Grep, Bash(npm:*), Bash(npx:*), Agent"
---
 
# Padrões React com TypeScript
 
Você é um especialista em TypeScript com foco em padrões React e Next.js. Forneça os tipos mais precisos e estritos para cada cenário.
 
## Princípios Fundamentais
 
1. **Prefira tipos estreitos a tipos amplos** - Use literais de string em vez de `string`, objetos específicos em vez de `Record`
2. **Use uniões discriminadas para renderização condicional** - Nunca use optional chaining para percorrer props de variantes
3. **Derive tipos a partir de dados** - Use `typeof`, `ReturnType` e inferência Zod em vez de declarações de tipo manuais
4. **Modo estrito sempre** - Habilite `strict: true` e `noUncheckedIndexedAccess: true`
 
## Biblioteca de Padrões
 
### 1. Componente Polimórfico (prop 'as')
```tsx
type PolymorphicProps<E extends React.ElementType> = \{
  as?: E;
  children: React.ReactNode;
\} & Omit<React.ComponentPropsWithoutRef<E>, "as" | "children">;
 
function Box<E extends React.ElementType = "div">(\{
  as,
  children,
  ...props
\}: PolymorphicProps<E>) \{
  const Component = as ?? "div";
  return <Component \{...props\}>\{children\}</Component>;
\}
 
// Uso - totalmente tipado
<Box as="a" href="/about">Link</Box>      // href é válido
<Box as="button" onClick=\{handleClick\}>Go</Box>  // onClick é válido

// Em vez de props opcionais que dependem umas das outras:
// RUIM
type BadProps = \{ variant?: "link"; href?: string; onClick?: () => void \};
 
// BOM - união discriminada
type ButtonProps =
  | \{ variant: "button"; onClick: () => void; href?: never \}
  | \{ variant: "link"; href: string; onClick?: never \}
  | \{ variant: "submit"; onClick?: never; href?: never \};
 
function Action(props: ButtonProps) \{
  switch (props.variant) \{
    case "button":
      return <button onClick=\{props.onClick\}>Click</button>;
    case "link":
      return <a href=\{props.href\}>Link</a>;
    case "submit":
      return <button type="submit">Submit</button>;
  \}
\}

type ListProps<T> = \{
  items: T[];
  renderItem: (item: T, index: number) => React.ReactNode;
  keyExtractor: (item: T) => string;
  emptyMessage?: string;
\};
 
function List<T>(\{ items, renderItem, keyExtractor, emptyMessage \}: ListProps<T>) \{
  if (items.length === 0) \{
    return <p>\{emptyMessage ?? "No items"\}</p>;
  \}
  return (
    <ul>
      \{items.map((item, i) => (
        <li key=\{keyExtractor(item)\}>\{renderItem(item, i)\}</li>
      ))\}
    </ul>
  );
\}
 
// Uso - T é inferido a partir de items
<List
  items=\{users\}
  renderItem=\{(user) => <span>\{user.name\}</span>\}  // user é tipado como User
  keyExtractor=\{(user) => user.id\}
/>

import type \{ ComponentProps, ComponentRef \} from "react";
 
// Extrai props de qualquer componente
type InputProps = ComponentProps<"input">;
type ButtonProps = ComponentProps<typeof Button>;
 
// Extrai o tipo de ref
type InputRef = ComponentRef<"input">; // HTMLInputElement
 
// Seleciona props específicas
type PartialInputProps = Pick<ComponentProps<"input">, "value" | "onChange" | "placeholder">;

// Retorna uma tupla (como useState)
function useToggle(initial = false) \{
  const [value, setValue] = useState(initial);
  const toggle = useCallback(() => setValue((v) => !v), []);
  const setTrue = useCallback(() => setValue(true), []);
  const setFalse = useCallback(() => setValue(false), []);
  return [value, \{ toggle, setTrue, setFalse \}] as const;
\}
// Tipo de retorno: readonly [boolean, \{ toggle, setTrue, setFalse \}]
 
// Hook genérico
function useLocalStorage<T>(key: string, initialValue: T) \{
  const [stored, setStored] = useState<T>(() => \{
    if (typeof window === "undefined") return initialValue;
    const item = window.localStorage.getItem(key);
    return item ? (JSON.parse(item) as T) : initialValue;
  \});
 
  const setValue = useCallback(
    (value: T | ((prev: T) => T)) => \{
      setStored((prev) => \{
        const next = value instanceof Function ? value(prev) : value;
        window.localStorage.setItem(key, JSON.stringify(next));
        return next;
      \});
    \},
    [key]
  );
 
  return [stored, setValue] as const;
\}

// Props do Server Component - params e searchParams são Promises no Next.js 15+
type PageProps = \{
  params: Promise<\{ slug: string \}>;
  searchParams: Promise<\{ [key: string]: string | string[] | undefined \}>;
\};
 
export default async function Page(\{ params, searchParams \}: PageProps) \{
  const \{ slug \} = await params;
  const \{ q \} = await searchParams;
  // ...
\}
 
// Props do Layout
type LayoutProps = \{
  children: React.ReactNode;
  params: Promise<\{ slug: string \}>;
\};
 
export default async function Layout(\{ children, params \}: LayoutProps) \{
  const \{ slug \} = await params;
  return <div>\{children\}</div>;
\}

// Server Action com estado tipado
type FormState = \{
  errors?: \{
    name?: string[];
    email?: string[];
  \};
  message?: string;
  success: boolean;
\};
 
export async function createUser(
  prevState: FormState,
  formData: FormData
): Promise<FormState> \{
  // valida e processa
  return \{ success: true, message: "Usuário criado" \};
\}
 
// Componente cliente usando a action
"use client";
import \{ useActionState \} from "react";
 
function Form() \{
  const [state, action, pending] = useActionState(createUser, \{
    success: false,
  \});
  // state é tipado como FormState
\}

// Tipos de evento específicos em vez de React.SyntheticEvent genérico
function Form() \{
  const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => \{
    console.log(e.target.value); // string
  \};
 
  const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => \{
    e.preventDefault();
    const formData = new FormData(e.currentTarget);
  \};
 
  const handleKeyDown = (e: React.KeyboardEvent<HTMLInputElement>) => \{
    if (e.key === "Enter") submit();
  \};
 
  return (
    <form onSubmit=\{handleSubmit\}>
      <input onChange=\{handleChange\} onKeyDown=\{handleKeyDown\} />
    </form>
  );
\}

// Torna chaves específicas obrigatórias
type WithRequired<T, K extends keyof T> = T & Required<Pick<T, K>>;
 
// Torna chaves específicas opcionais
type WithOptional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
 
// Partial profundo
type DeepPartial<T> = \{
  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
\};
 
// Omit estrito (gera erro se a chave não existir)
type StrictOmit<T, K extends keyof T> = Omit<T, K>;
 
// Extrai membro de união
type ExtractMember<T, U> = T extends U ? T : never;

// Função type guard
function isError(result: SuccessResult | ErrorResult): result is ErrorResult \{
  return "error" in result;
\}
 
// Switch exaustivo
function assertNever(value: never): never \{
  throw new Error(`Valor inesperado: ${value}`);
\}
 
function handleStatus(status: "idle" | "loading" | "success" | "error") \{
  switch (status) \{
    case "idle": return null;
    case "loading": return <Spinner />;
    case "success": return <Done />;
    case "error": return <Error />;
    default: return assertNever(status); // erro de compilação se o case for perdido
  \}
\}

import { z } from "zod";
 
const UserSchema = z.object({
  id: z.string().uuid(),
  name: z.string(),
  email: z.string().email(),
  role: z.enum(["admin", "user", "moderator"]),
});
 
type User = z.infer<typeof UserSchema>;
// Agora o tipo User é derivado do schema - única fonte de verdade

mkdir -p .claude/skills/typescript-react-patterns
# Cole o conteúdo da Receita em .claude/skills/typescript-react-patterns/SKILL.md