# card-layouts

Wspólne źródło schematów, layoutów i generatora kart pracy używanych przez
serie edukacyjne. Jeden plik `card_source.json` opisuje treść oraz mapowanie
edukacyjne, a `tools/render_card.py` generuje z niego równolegle LaTeX i HTML.

Repozytorium rozdziela trzy warstwy:

1. **Treść karty** — `card_source.json`: cele, efekty nauczania, kryteria,
   drzewka marginesowe, kroki oraz zadania.
2. **Layout** — `templates/*.json`: geometria strony, role marginesów,
   komponenty i wybór emitera TeX/HTML.
3. **Seria** — `series.json`: kolejność kart, repozytoria, wersje i kontrakt
   uruchamiania zadań.

## Zawartość

```text
card-layouts/
├── schemas/
│   ├── card-source.schema.json
│   ├── card-template.schema.json
│   ├── reference-registry.schema.json
│   └── series.schema.json
├── templates/
│   ├── karta-klasyczna.json
│   ├── karta-5a.json
│   └── karta-5b.json
├── tools/render_card.py
├── docs/
│   ├── CARD.md
│   └── SERIES.md
└── examples/
    ├── card/
    └── series/
```

## Layouty

| Layout | Przeznaczenie | Marginesy | Emitery |
|---|---|---|---|
| `karta-klasyczna` | elastyczna karta sekcyjna | dwa panele drzewek | TeX + HTML |
| `karta-5a` | wielostronicowa karta A4 landscape | TECH po lewej, OG po prawej | TeX + HTML |
| `karta-5b` | referencyjna karta A4 portrait | gołe drzewka TECH/OG | TeX + HTML |

`karta-5b` jest obecnym layoutem referencyjnym. Używa geometrii
`0,55 / 2,05 / 0,55 / 14,70 / 0,55 / 2,05 / 0,55 cm`; lewy margines
zawiera efekty zawodowe `TECH`, a prawy efekty ogólne `OG`.

## Szybki start

Wygenerowanie przykładowej karty:

```bash
make render-example
```

Powstaną:

```text
examples/card/build/tex/main.tex
examples/card/build/html/index.html
examples/card/build/html/style.css
```

Złożenie kontrolnego PDF-u wymaga `latexmk` i pakietów LaTeX używanych przez
generator:

```bash
make pdf-example
```

Pełna kontrola repozytorium:

```bash
make check
```

Walidacja względem JSON Schema jest wykonywana, gdy dostępny jest pakiet
`jsonschema`. Workflow Gitei pozostaje samowystarczalny i zawsze uruchamia
walidację relacji generatora; pełną walidację schematów można włączyć lokalnie:

```bash
python3 -m pip install -r requirements-dev.txt
CARD_LAYOUTS_REQUIRE_JSONSCHEMA=1 python3 scripts/check_repository.py
```

Generator można też wywołać bezpośrednio dla dowolnego katalogu karty:

```bash
python3 tools/render_card.py /sciezka/do/karty
python3 tools/render_card.py /sciezka/do/karty --template templates/karta-5b.json
```

Katalog karty musi zawierać `json/card_source.json`. Ścieżki wyjściowe
określa obiekt `generated` w tym pliku.

## Model edukacyjny

Źródłem marginesów nie jest luźny tekst. Relacje są jawne:

```text
WE (wymaganie edukacyjne)
└── EN/EK (efekt nauczania lub efekt kształcenia)
    └── KW (kryterium weryfikacji)
```

Każda sekcja i każdy krok mogą wskazywać te same drzewka przez `tree_refs`.
Dzięki temu TeX i HTML pokazują identyczne powiązanie treści z efektami.

Sekcje mogą także deklarować strukturalne `assets` (najczęściej zrzuty ekranu
z `doc/assets`). Generator wstawia je do TeX/PDF i HTML, zachowuje podpis,
tekst alternatywny i stabilną etykietę oraz przygotowuje link do pełnego
obrazu w wersji ekranowej.

Szczegóły modelu karty opisuje [docs/CARD.md](docs/CARD.md), a manifestu
serii [docs/SERIES.md](docs/SERIES.md).

## Słowniki podstaw programowych

Generator może rozszerzać skróty z zewnętrznych słowników JSON. Karta podaje
ich katalog przez:

```json
{
  "dictionary_refs": {
    "pp_json_root": "../../pp/json"
  }
}
```

Brak słowników nie blokuje generowania, jeśli karta zawiera kompletne pola
`display` i `text` we własnych drzewkach.

## Rejestry referencji

Wspólnej strategii, innej karty, treści ani wzoru nie kopiujemy do karty.
`card_source.json` przechowuje stabilne UUID-y, a generator rozwiązuje je przez
lokalny kanoniczny rejestr JSON. Widocznym hiperłączem jest kod strategii
(`Mxx`), nazwa karty albo etykieta treści/wzoru. Model danych i przykład są w
[docs/CARD.md](docs/CARD.md#referencje-zewnętrzne-bez-kopiowania-treści).

## Zasada zmian

- zmiana treści należy do `card_source.json`;
- zmiana geometrii i stylu należy do `templates/*.json` oraz emitera;
- wygenerowanych plików nie edytujemy ręcznie;
- nowa wersja layoutu wymaga aktualizacji numeru `version`, przykładu i testu
  obu wyjść.