Sections & Settings

Sections sind React-Komponenten mit einem typisierten Settings-Vertrag. Die Komponente exportiert ein schema; die Plattform validiert es beim Build, Händler bearbeiten die Werte im Workspace-Theme-Editor — ohne Codeänderung, ohne Redeploy.

Eine Section

app/sections/hero.tsx

import type { SectionSchema } from "@kotao/storefront-contracts";

export const schema: SectionSchema = {
  type: "hero",
  label: "Hero",
  settings: [
    { type: "text", name: "heading", label: "Heading", defaultValue: "Welcome" },
    { type: "richtext", name: "subheading", label: "Subheading" },
    { type: "image", name: "background", label: "Background image" },
  ],
};

export function Hero({ heading, subheading }: HeroProps) {
  /* … */
}

Das Schema spiegelt den Eintrag der Section in kotao.theme.json — das Validierungs-Gate des Builds prüft beide gegen SectionSchemaSchema aus @kotao/storefront-contracts.

Setting-Input-Typen

Einfache Werte: text, textarea, richtext, number, boolean, color, color_scheme, date, font, url, link, file, video.

Strukturierte Werte: range (min/max/step), select / radio / segmented (Optionen), image (optionales Seitenverhältnis) sowie die Commerce-Maße dimension, weight, money (Wert + Einheit).

Werte zur Laufzeit lesen

Die App in ThemeSettingsProvider wrappen und mit den Hooks aus @kotao/storefront/react lesen:

• useThemeSettings() — globale Theme-Settings.
• useSectionSettings(sectionId) — die Werte einer Section-Instanz.
• useGlobalThemeTokens() — aus Settings abgeleitete Design-Tokens.

Serverseitig laden und mergen fetchThemeSettings / resolveThemeSettings (aus @kotao/storefront/settings) das Werte-Dokument mit deinen Schema-Defaults.

Live-Preview

Der Workspace-Editor spricht über die Editor-Bridge (@kotao/storefront/editor) mit deinem Theme — der Scaffold verdrahtet sie, Änderungen an Settings erscheinen live in der Preview, ohne Reload.