Directivas — Sistema General

Cómo funciona el sistema de directivas V2: sintaxis, props, slots, shorthands, nesting, y el patrón de override.

Sintaxis Básica

:::type {key="value" key2="value2"}
Content here
:::

Short-form

Sin bloque {}, el texto después del tipo se convierte en prop title:

:::note My Quick Title
→ :::note {title="My Quick Title"}

Props

Shorthands

Combinado: {.flex .gap-4 #my-id} → { class: "flex gap-4", id: "my-id" }

Slots

Los slots dividen el contenido en regiones nombradas usando marcadores #slotname.

Reglas de slots:

El renderSlot(name) parsea el contenido del slot como markdown completo, incluyendo formato inline, listas, tablas, y directivas anidadas.

Nesting

Las directivas pueden anidarse. El parser trackea nestedLevel — el ::: exterior solo cierra cuando todos los interiores están cerrados.

Directivas sin cerrar → se renderizan como párrafos de texto plano.

Patrón de Override

Todas las directivas soportan props class y style para customización.

Cómo funciona: El prop class se anexa después de las clases default del componente. Dado que CSS sigue source order, la última clase gana para propiedades conflictivas.

El prop style acepta un string CSS que se parsea en React.CSSProperties via parseCssString().

Smart Detection (Button & Modal)

Button y Modal tienen detección inteligente de clases para evitar defaults conflictivos:

Si el usuario proporciona una clase que matchea, el default se omite (no solo se sobreescribe).

Position Shorthands

Data Attributes

La directiva Wrapper soporta atributos data-* arbitrarios:

:::div {data-tab="1" data-panel="settings"}

Auto-batching de Cards

Cuando múltiples card, card-m, o card-b aparecen consecutivos, se agrupan automáticamente en un flex-wrap responsive.

Desactivar batching: batch="off" en la primera card.

Justificación: Extraer justify-* del prop class de la primera card.

Registry de Directivas

Directivas Desconocidas

Si un tipo no está en el registry, se renderiza como un <div> con el contenido del slot default:

<div class="my-4 p-4 rounded-2xl border border-border bg-background-primary/5">
  {contenido del slot default}
</div>