Einführung

Ein hochgradig responsiver und flexibler CSS-Grid-Layout-Container zum Aufbau rasterbasierter Seitenstrukturen und Interface-Layouts. Ordne Kindelemente mit expliziter Spalten- oder Zeilenzahl an, oder lasse sie dynamisch per Mindestbreite automatisch fließen – ohne explizite Media Queries. Vollständig unterstützt responsives, breakpoint-basiertes Layout.

Verwendung

Die Grid-Komponente ist als grid-Block vollständig im Page Builder integriert, sodass Redakteure und Entwickler responsive Strukturen, Kartenlisten und nebeneinander liegende Controls direkt im CMS bauen können.

---

• Dynamische Spalten & Zeilen: Leicht Spuren über numerische Werte oder CSS-Template-Definitionen festlegen.
• Auto-Fit-Skalierung: Ein Mindestbreiten-Schwellenwert (minChildWidth) lässt den Container Kindelemente platzsparend in Spalten fließen lassen.
• Responsive Breakpoints: Native Unterstützung für Breakpoint-Konfigurationen (base, sm, md, lg, xl, 2xl).
• Polymorphe Darstellung: Per as als semantisches HTML-Tag rendern, oder via asChild Grid-Styles auf ein Kind delegieren.
• Zero-Layout-Shift: Styles kompilieren zu optimierten statischen Panda-CSS-Utilities ohne JS-Messaufwand.

---

Usage

Diese Beispiele zeigen, wie Grid-Komponenten per Code (JSX/TSX) und Page-Builder-JSON konstruiert werden.

1. Feste Spaltenstruktur

Explizite Spaltenzahl, die drei Elemente nebeneinander anzeigt. Ideal für Feature-Grids, Metrik-Layouts oder Navigation.

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. Auto-Fit-Spalten per Mindestbreite

Spalten werden beim Skalieren automatisch hinzugefügt oder entfernt. Vermeidet Breakpoint-Definitionen und sorgt out-of-the-box für responsive Kartencontainer.

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. Responsive Spaltenzuweisung

Eine einzelne Spalte auf Mobilgeräten, zwei Spalten auf Tablets, drei Spalten auf Desktop.

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. Getrennte Spalten- und Zeilenabstände

Abstände zwischen Zeilen und Spalten lassen sich unabhängig konfigurieren, um asymmetrische Raster oder dichtere Zeilenverpackung zu erzeugen.

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

Eigenschaft	Typ / CMS-Feldtyp	Standard	Beschreibung
columns	number | string | Responsive<...>	-	Explizite Spaltenzahl (z. B. 3 oder "3"). Akzeptiert Breakpoint-Objekt oder JSON-String im CMS (z. B. '{"base": 1, "md": 3}'). Hat Vorrang vor minChildWidth.
rows	number | string | Responsive<...>	-	Explizite Zeilenzahl. Nützlich für strukturierte Template-Layouts.
minChildWidth	number | string | Responsive<...>	-	Breitenschwellenwert für Auto-Fit-Spalten (z. B. "120px", "16rem"). Ignoriert, wenn columns gesetzt.
gap	string | number | Responsive<...>	"8px"	Abstand zwischen aufeinanderfolgenden Zellen.
columnGap	string | number | Responsive<...>	-	Nur horizontaler Abstand zwischen Spalten.
rowGap	string | number | Responsive<...>	-	Nur vertikaler Abstand zwischen Zeilen.
class	string	-	Benutzerdefinierte CSS-Klassen-Überschreibungen.
children	any | list	-	Sammlung verschachtelter Layout- oder visueller Blöcke im Grid.

Responsive Werte: Responsive<T> akzeptiert einen flachen Wert oder ein nach Breakpoints gemapptes Objekt (z. B. { base: 1, md: 2, lg: 3 }). Das Designsystem unterstützt base, sm, md, lg, xl und 2xl.

---

Hydration & Architecture

Tier-3 Presentational Layout Primitive

Die Grid-Komponente ist als Tier-3-Presentational-Komponente klassifiziert. Sie hält null clientseitigen State und behandelt keine Events. Folglich:

• Sie mountet niemals eine interaktive Client-Insel.
• Kompiliert direkt zu Zero-JS-Static-HTML ohne Bundle-Overhead.
• Ein explizites interactive-Prop wird weder benötigt noch unterstützt.

Developer Implementation Notes

• Panda CSS Pattern Integration: Übersetzt columns, rows und gaps in Panda-CSS-grid-Utilities mit atomaren Klassen.
• Responsive JSON Strings: In Sveltia CMS sollten responsive Werte als JSON-Strings geschrieben werden (z. B. '{"base": 1, "md": 2}'). Sie werden zur Laufzeit geparst.

Accessibility Compliance

• Natural DOM Flow: Der Container bewahrt sequenzielle TAB-Navigation und DOM-Lesereihenfolge. Kindelemente sollten mit der logischen visuellen Sequenz alignen, damit Screenreader konsistent bleiben.