# Schema i ustawienia

## Sekcja i schema

Każdy plik `sections/*.html` i `blocks/*.html` ma osobny plik o tej samej nazwie z rozszerzeniem `.schema.json`. Przykład: `sections/hero.html` oraz `sections/hero.schema.json`. Schema nie pojawia się w HTML strony.

```html
<section>
  <h1 data-text-field="[[ section.settings_path ]].title">
    [[ section.settings.title ]]
  </h1>
  <template gs-slot="blocks"></template>
</section>
```

`*.schema.json`:

```json
{
  "name": "Sekcja powitalna",
  "settings": [
    {
      "type": "text",
      "id": "title",
      "label": "Nagłówek",
      "default": "Witaj"
    }
  ],
  "blocks": [
    {
      "type": "@theme"
    }
  ],
  "max_blocks": 12,
  "presets": [
    {
      "name": "Sekcja powitalna"
    }
  ]
}
```

`section.settings` i `block.settings` zawierają zapisane wartości, a dla brakujących pól wartości `default`. Pusty tekst, `false` oraz `0` są pełnoprawnymi wartościami i nie zostają zastąpione domyślnymi. Otwarcie formularza nie zapisuje zmian.

## Dostępne kontrolki

| Typ | Dane / zachowanie |
| --- | --- |
| `text`, `textarea` | Tekst; wybór własnej wartości lub dynamicznego źródła |
| `url` | Adres HTTP(S), względny, kotwica, `mailto:` lub `tel:` |
| `image_picker` | Adres obrazu; obecnie pole URL, nie przeglądarka plików |
| `color` | Wspólny custom picker i HEX; także `transparent` |
| `range` | Suwak oraz liczba; wymagane `min`, `max`, `step`, `default`; opcjonalne `unit` |
| `number` | Pole liczbowe |
| `select`, `radio` | Wspólna custom lista opcji `value` / `label` |
| `checkbox` | Wartość logiczna |
| `font_picker` | Inter, Arial lub Georgia |
| `header`, `paragraph` | Informacja w panelu, bez zapisywanej wartości; wymagane `content` |

Identyfikator ustawienia pozostaje stabilny między wersjami. Nie używaj `constructor`, `prototype` ani `__proto__`. HTML wpisany przez klienta jest wyświetlany jako tekst, nie wykonywany.

Typy związane z produktami, kolekcjami, metaobiektami, materiałami wideo i edytorem HTML nie są obecnie częścią tego kontraktu. Istniejący bogaty edytor tekstu GrowSite działa przez powiązania `data-text-field`.

## Przykłady kontrolek

```json
[
  {"type":"header","content":"Wygląd"},
  {"type":"range","id":"radius","label":"Zaokrąglenie","min":0,"max":48,"step":1,"default":16,"unit":"px"},
  {"type":"color","id":"background","label":"Tło","default":"#ffffff"},
  {"type":"checkbox","id":"show_link","label":"Pokaż link","default":true},
  {"type":"select","id":"alignment","label":"Wyrównanie","default":"left","options":[{"value":"left","label":"Do lewej"},{"value":"center","label":"Do środka"}]}
]
```

Liczbę zapisuj jako `16`, nie `"16px"`. Jednostkę dodaj przy renderowaniu: `border-radius:{{ block.settings.radius }}px`. Sama etykieta `unit` nie tworzy stylu CSS.

Każde ustawienie powinno mieć sensowną wartość początkową. Preset określa stan nowo dodanej instancji, nie migruje zapisanych danych. Zmiana wartości domyślnej może wpłynąć na wcześniej nieustawione pola; jawnie zapisane wartości pozostają.

ID zaczyna się literą lub podkreśleniem; dalej dopuszcza litery, cyfry, podkreślenia i myślniki, maksymalnie 80 znaków. Tablica ustawień ma limit 100 pozycji. Nie dodawaj komentarzy ani końcowych przecinków do JSON. Schema nie wykonuje wyrażeń Loom.

Kontrolka schema nie oznacza automatycznie, że każdy element HTML można kliknąć. Podłącz [edycję na podglądzie](/pl/editor/).