React
Revisa patrones para diseñar APIs de componentes flexibles mediante composición, controlled props, compound components, render props y separación de responsabilidades.
Una buena API expresa intención, limita combinaciones inválidas y permite composición.
<Tabs value={tab} onValueChange={setTab}>
<Tabs.List>
<Tabs.Trigger value="details">Detalles</Tabs.Trigger>
<Tabs.Trigger value="reviews">Reseñas</Tabs.Trigger>
</Tabs.List>
<Tabs.Content value="details">...</Tabs.Content>
</Tabs>Context puede coordinar internamente las piezas sin obligar al consumidor a gestionar detalles.
Ofrecer ambos modos puede hacer una librería flexible:
<Accordion defaultValue="first" />
<Accordion value={value} onValueChange={setValue} />Define claramente cuál tiene prioridad y no cambies de modo durante la vida de la instancia.
<DataLoader>
{({ data, isLoading }) => ...}
</DataLoader>Siguen siendo útiles cuando el consumidor necesita decidir el render, aunque custom hooks suelen ser más simples para reutilizar lógica.
Un componente que cambia la etiqueta debe preservar tipos, semántica y accesibilidad. No conviertas cada div en botón solo por aceptar as.
Modela variantes con uniones discriminadas para impedir combinaciones incompatibles.
type ButtonProps =
| { href: string; onClick?: never }
| { href?: never; onClick: () => void };El diseño de componentes es diseño de producto para otros desarrolladores.
Cada prop amplía las combinaciones posibles. Una API bien diseñada hace fáciles los casos correctos e imposibles los contradictorios.
type ButtonProps =
| {
kind: "link";
href: string;
onClick?: never;
}
| {
kind: "button";
href?: never;
onClick: () => void;
};El tipo comunica semántica y evita renderizar un enlace incompleto o un botón con destino ambiguo.
<UserCard user={user} />El componente controla representación consistente.
<Card
header={<CustomHeader />}
actions={<CustomActions />}
/>El consumidor controla regiones. Usa datos cuando el componente conoce el dominio; usa slots cuando necesita flexibilidad estructural.
<Tabs value={tab} onValueChange={setTab}>
<Tabs.List aria-label="Secciones del producto">
<Tabs.Trigger value="details">Detalles</Tabs.Trigger>
<Tabs.Trigger value="reviews">Reseñas</Tabs.Trigger>
</Tabs.List>
<Tabs.Content value="details">...</Tabs.Content>
<Tabs.Content value="reviews">...</Tabs.Content>
</Tabs>El componente raíz puede distribuir state e IDs mediante Context. Las piezas deben validar que se usan dentro del provider y conservar teclado, roles y relaciones accesibles.
<Tabs defaultValue="details" />
<Tabs value={tab} onValueChange={setTab} />Define:
value tiene prioridad.defaultValue solo inicializa.Un hook interno puede centralizar el patrón, pero no ocultes warnings de ownership.
<Collection>
{({ items, isEmpty }) => ...}
</Collection>Render props permiten que el componente controle el proceso y el consumidor el resultado visual. Custom hooks suelen reducir anidamiento cuando no necesitas una frontera de árbol. Render props siguen siendo útiles para componentes que aportan contexto, medición o comportamiento alrededor del contenido.
<Button as="a" href="/docs">Documentación</Button>Cambiar elemento afecta:
Una API as demasiado abierta puede permitir combinaciones inválidas. A veces es mejor ofrecer Button y LinkButton con contratos explícitos.
Librerías headless pueden devolver props para combinar:
const { getTriggerProps, getPanelProps } = useDisclosure();El getter puede fusionar handlers, IDs y ARIA. Debe definir qué ocurre si el consumidor también pasa onClick y en qué orden se ejecutan. Sin reglas claras, el spreading puede sobrescribir comportamiento crítico.
Un componente puede poseer state o delegarlo. Cuanta más flexibilidad, mayor superficie de API, documentación y tests. No ofrezcas todas las variantes antes de existir consumidores reales.
Separa cuando aporta:
useSelect / SelectRoot → comportamiento, state, accesibilidad
SelectVisual → estilos y tokensPero una separación extrema puede hacer que cada uso deba reconstruir accesibilidad. Una primitive bien diseñada ofrece defaults seguros y personalización controlada.
Prefiere callbacks de dominio:
onValueChange(nextValue)
onOpenChange(open)
onItemRemove(itemId)frente a exponer setters o eventos DOM cuando el consumidor no necesita esos detalles. Si la API envuelve un elemento nativo, puede conservar también sus eventos estándar.
Defaults deberían resolver el caso común sin ocultar decisiones críticas. Añadir una prop es fácil; retirarla de una librería pública no. Evalúa:
En componentes compartidos, cambios aparentemente visuales pueden romper:
Documenta API pública y usa migraciones para cambios incompatibles.
Prueba variantes públicas, no internals:
as puede romper accesibilidad?React Router: rutas, layouts y navegación aplica diseño de APIs a una estructura controlada por URL.