Introducción

Un contenedor de diseño CSS Grid altamente responsivo y flexible para construir estructuras de página y layouts de interfaz basados en cuadrículas. Dispón elementos secundarios con un conteo explícito de columnas o filas, o deja que se ajusten automáticamente según un ancho mínimo de hijo sin necesidad de media queries explícitas. Admite plenamente configuraciones responsivas por breakpoint.

El componente Grid también está totalmente integrado como bloque grid en el Page Builder, permitiendo a autores y desarrolladores construir estructuras responsivas, listas de tarjetas y controles lado a lado directamente en el CMS.

---

Features

• Columnas y filas dinámicas: Especifica pistas fácilmente con valores numéricos o definiciones de plantilla CSS.
• Escalado Auto-Fit: Define un umbral de ancho mínimo (minChildWidth) para que el contenedor haga fluir hijos en columnas según el espacio.
• Breakpoints responsivos: Soporte nativo para configuraciones a través de breakpoints (base, sm, md, lg, xl, 2xl).
• Renderizado polimórfico: Renderiza como cualquier etiqueta HTML semántica vía as, o delega estilos a un hijo vía asChild.
• Rendimiento sin saltos de diseño: Los estilos compilan a utilidades Panda CSS estáticas optimizadas, sin sobrecarga de JS en cliente.

---

Usage

Estos ejemplos ilustran cómo estructurar componentes grid tanto en código (JSX/TSX) como vía JSON del Page Builder.

1. Estructura de columnas fijas

Especifica un conteo explícito de columnas que muestra tres elementos en paralelo. Excelente para grids de funciones, métricas o navegación.

JSX / TSX

import { Grid } from "../components/ui";

export default function Example() {
  return (
    <Grid columns={3} gap="4">
      <div>1</div>
      <div>2</div>
      <div>3</div>
    </Grid>
  );
}

Page Builder JSON

{
  "type": "grid",
  "columns": 3,
  "gap": "4",
  "children": [
    { "type": "text", "content": "1" },
    { "type": "text", "content": "2" },
    { "type": "text", "content": "3" }
  ]
}

---

2. Columnas Auto-Fit por ancho mínimo

Las columnas se agregan o eliminan automáticamente al redimensionar. Evita definir breakpoints, asegurando contenedores de tarjetas totalmente responsivos.

JSX / TSX

import { Grid } from "../components/ui";

export default function Example() {
  return (
    <Grid minChildWidth="120px" gap="4">
      <div>Card A</div>
      <div>Card B</div>
      <div>Card C</div>
    </Grid>
  );
}

Page Builder JSON

{
  "type": "grid",
  "minChildWidth": "120px",
  "gap": "4",
  "children": [
    { "type": "text", "content": "Card A" },
    { "type": "text", "content": "Card B" },
    { "type": "text", "content": "Card C" }
  ]
}

---

3. Asignación de columnas responsiva

Muestra una sola columna en móviles, escala a dos en tablets y tres en escritorio.

Programmatic Usage (TSX)

import { Grid } from "@/components/ui";

export default function ResponsiveGrid() {
  return (
    <Grid columns={{ base: 1, md: 2, lg: 3 }} gap="6">
      <div>Responsive Grid Item 1</div>
      <div>Responsive Grid Item 2</div>
      <div>Responsive Grid Item 3</div>
    </Grid>
  );
}

Page Builder Configuration (CMS JSON)

JSX / TSX

import { Grid } from "../components/ui";

export default function Example() {
  return (
    <Grid columns={{ base: 1, md: 2, lg: 3 }} gap="6">
      <div>Responsive Grid Item 1</div>
      <div>Responsive Grid Item 2</div>
      <div>Responsive Grid Item 3</div>
    </Grid>
  );
}

Page Builder JSON

{
  "type": "grid",
  "columns": "{\"base\": 1, \"md\": 2, \"lg\": 3}",
  "gap": "6",
  "children": [
    { "type": "text", "content": "Responsive Grid Item 1" },
    { "type": "text", "content": "Responsive Grid Item 2" },
    { "type": "text", "content": "Responsive Grid Item 3" }
  ]
}

---

4. Separación de espacios de columna y fila

Los espacios entre filas y columnas se configuran de forma independiente para crear cuadrículas asimétricas o empaquetado de filas más ajustado.

JSX / TSX

import { Grid } from "../components/ui";

export default function Example() {
  return (
    <Grid columns={2} columnGap="6" rowGap="2">
      <div>1</div>
      <div>2</div>
      <div>3</div>
      <div>4</div>
    </Grid>
  );
}

Page Builder JSON

{
  "type": "grid",
  "columns": 2,
  "columnGap": "6",
  "rowGap": "2",
  "children": [
    { "type": "text", "content": "1" },
    { "type": "text", "content": "2" },
    { "type": "text", "content": "3" },
    { "type": "text", "content": "4" }
  ]
}

---

Props

Propiedad	Tipo / Tipo de campo CMS	Predeterminado	Descripción
columns	number | string | Responsive<...>	-	Conteo explícito de columnas (ej. 3 o "3"). Acepta objeto de breakpoint o string JSON en CMS (ej. '{"base": 1, "md": 3}'). Tiene prioridad sobre minChildWidth.
rows	number | string | Responsive<...>	-	Conteo explícito de filas. Útil para layouts de plantilla estructurados.
minChildWidth	number | string | Responsive<...>	-	Umbral de ancho para columnas auto-fit (ej. "120px", "16rem"). Ignorado si se especifica columns.
gap	string | number | Responsive<...>	"8px"	Espacio entre celdas consecutivas.
columnGap	string | number | Responsive<...>	-	Espacio horizontal solo entre columnas.
rowGap	string | number | Responsive<...>	-	Espacio vertical solo entre filas.
class	string	-	Anulaciones de clase CSS personalizadas.
children	any | list	-	Colección de bloques de layout o visuales anidados dentro del grid.

Valores responsivos: Responsive<T> acepta un valor plano o un objeto mapeado por breakpoints (ej. { base: 1, md: 2, lg: 3 }). El design system soporta base, sm, md, lg, xl y 2xl.

---

Hydration & Architecture

Tier-3 Presentational Layout Primitive

El componente Grid se clasifica como Componente Presentacional Tier-3 en la arquitectura Island Hydration. No mantiene estado reactivo en cliente ni maneja eventos. Por consiguiente:

• Nunca monta una isla interactiva en cliente.
• Compila directamente a HTML estático sin JS, con overhead de bundle nulo.
• Un prop interactive explícito no es requerido ni admitido.

Developer Implementation Notes

• Integración Panda CSS: Traduce columns, rows y gaps en utilidades grid de Panda CSS con clases atómicas de alto rendimiento.
• Strings JSON responsivos: En Sveltia CMS, los valores responsivos deben escribirse como strings JSON (ej. '{"base": 1, "md": 2}'). Se parsean automáticamente en runtime.

Accessibility Compliance

• Flujo DOM natural: El contenedor preserva la navegación secuencial por teclado (Tab) y el orden de lectura del DOM. Alinea los hijos con la secuencia visual lógica para mantener la accesibilidad.