@smartbit4all/ng-client 7.2.3 → 7.2.4

package/HTML-WIDGET.md

@@ -1,526 +1,526 @@
-# HTML widget — szerverről küldött html a `@smartbit4all/ng-client` 7.2-ben
-
-Ez a dokumentum a **HTML widget**, a **kliens-helyőrzők** (`{{…}}`), a html-be írt **toolbar-slot**
-és **akció-trigger**, a kártya-grid **sor-layoutjainak**, valamint a tábla **html-celláinak**
-referenciája. A Java-oldali builder (`HtmlWidgetBuilder`, `HtmlBuilder.Tag.toolbar/action`,
-`GridBuilder.rowLayout/htmlColumn/contentType`) javadocja
-ide hivatkozik; ha a kettő ellentmond egymásnak, ez a fájl az igazság.
-
-## Mire való
-
-A backend egy `HTML` típusú form-widgetet tehet a layoutba, amelynek a tartalma egy darab html. A
-html-t **két fázisban** oldjuk fel, két külön jelöléssel:
-
-| Fázis | Jelölés | Ki oldja fel | Mire jó |
-|---|---|---|---|
-| szerver-helyőrző | `${…}` | a backend, a page-ben, mielőtt a html elhagyja | feltétel, iteráció, szkript, lokalizáció — a platform meglévő template-dialektusa |
-| kliens-helyőrző | `{{…}}` | a kliens, a widget **feloldási kontextusán** | ugyanaz a html egyszer utazik és soronként / modell-változásonként újra feloldódik |
-
-A kliens a szerver-fázisból semmit nem lát: mire a html megérkezik, a `${…}` már nincs benne.
-
-**Bizalmi határ.** A html-t a backend írta, ezért a kliens **változtatás nélkül** írja ki (nincs
-sanitizálás: `data-*`, `style`, `<svg>`, inline `on*` mind él). Amit viszont a kliens helyettesít be
-egy `{{…}}` helyére, az **mindig HTML-escape-en** megy át, kivétel és „raw" forma nélkül. Ha a host
-Trusted Types-ot használ, a html kiírása miatt engedélyeznie kell a megfelelő policy-t. A widget
-stíluslapja (`css`, lásd *Stíluslap*) ugyanígy, változatlanul kerül a dokumentumba.
-
-A `DIV` widget változatlanul megmarad; a HTML widget annak a használatnak a rendes helye, amikor a
-`DIV`-be kész html-t tettünk.
-
-## A widget a dróton
-
-`SmartWidgetDefinition.type = HTML`, a tulajdonságai a `properties["HTML_properties"]` alatt
-(`HtmlProperties`):
-
-| Mező | Jelentés |
-|---|---|
-| `html` | a html, a `${…}` már feloldva, a `{{…}}` benne hagyva |
-| `root` | dot-path a kontextus `data`-jához képest, amihez minden helyőrző relatív; **objektumot** nevez; üres = a `data` maga |
-| `fields` | a widget által olvasott abszolút pathok — a builder származtatja a helyőrzőkből, a kliens **nem** olvassa |
-| `css` | a widget stíluslapja, a html mellett utazik — lásd *Stíluslap* |
-
-A **feloldási kontextus** nézeten a `ComponentModel` (`data` + `valueSets`), grid-kártyán a sor
-(`GridRow.data`) a gridet mutató oldal `valueSets`-ével. Ha a `root` listát, egyetlen értéket vagy
-semmit nevez, minden helyőrző üres marad, és a kliens egyszer `console.warn`-t ír.
-
-A widgetnek nincs kontrollja, címkéje, validálása és saját kattintása sem (lásd *Akció-trigger*).
-
-Java-oldalon:
-
-```java
-layoutBuilder(view).vForm(f -> f
-    .html(h -> h.root("card").html("<div class=\"card\">{{name}}</div>")))
-```
-
-vagy template-kulcsból (`h.template(ctx, "CONTACT_ENTRY_LIST")`): a kulcs a szerveren oldódik fel,
-a dróton nem utazik.
-
-## Stíluslap
-
-A widget a kinézetét is hozhatja: a `css` mezőben egy CSS-szöveget, amit a kliens a dokumentum
-`<head>`-jébe tesz (`<style data-sb4-html-css>`). Így a widget teljes egészében a szerverről jön, a
-hostnak nem kell hozzá stíluslapot szállítania.
-
-```java
-vf.html(h -> h.root("card")
-    .html("<div class=\"contact-card\">{{name}}</div>")
-    .css(".contact-card { padding: 1rem; border-radius: 12px; }"))
-```
-
-- **Egyszer kerül ki**, akárhány widget, kártya vagy cella hozza ugyanazt a szöveget, és az
-  utolsó eltűnésével a kliens kiveszi. A sor-layout és az oszlop-sablon is így működik: a `css` a
-  layout, illetve a sablon része, nem soronként utazik.
-- **Globális, nincs hatóköre.** Minden szelektor a html gyökérelemének egy osztályával kezdődjön
-  (`.contact-card …`), különben az egész oldalra hat. Két különböző szöveg ugyanarra a
-  szelektorra a betöltés sorrendjében nyer: adj widgetenként saját előtagot.
-- **Nem oldódik fel**: a `{{…}}`-nak nincs benne jelentése, modell-értéket nem lehet belevinni. Ami
-  a modelltől függ, az a html-ben legyen osztály (`class="status-{{status}}"`), a CSS pedig
-  osztályonként szabályozzon.
-- **CSP**: ha a host `style-src`-je nonce-os, adja meg az Angular `CSP_NONCE` tokenjét, a kliens
-  ráteszi a `<style>`-ra. Nonce és `'unsafe-inline'` nélkül a böngésző a stíluslapot blokkolja.
-- A builder nem vizsgálja és nem formázza: a `%` és a `{{` sem zavarja.
-
-### Stíluslap a template-kulcs mellől
-
-A `template(ctx, KEY)` a html mellé a stíluslapot is behúzza, ugyanazokon a neveken egy `.css`
-szegmenssel: `<viewName>.<KEY>.css`, `<KEY>.css`, … egészen a kulcs utolsó szegmenséig (a puszta
-`css` név sosem jön szóba). A fájl-registryben ez egy sor, pl.
-`CONTACT_ENTRY_LIST.css=templates/contact_entry_list.css`; MDM-ben egy ugyanilyen nevű
-`text/css` template.
-
-A html-lel ellentétben itt **nem egy nyer, hanem mind összefűződik**: előbb a fájlos stíluslapok,
-aztán az MDM-esek, mindkét rétegen belül az általánostól a specifikusig:
-
-```
-<KEY>.css (fájl) → <viewName>.<KEY>.css (fájl) → <KEY>.css (MDM) → <viewName>.<KEY>.css (MDM)
-```
-
-Mivel egyenlő specificitásnál a később jövő szabály nyer, az MDM a kódban szállított kinézetet
-szabályonként felülírhatja (ugyanazzal a szelektorral) vagy kiegészítheti (új szabállyal). A
-fájlban lévő `!important`-ot csak `!important` írja felül. A template-ből jött stíluslap lecseréli
-az addigi `css(...)`-t, egy későbbi `css(...)` pedig őt; ha a kulcshoz nincs stíluslap, az addigi
-`css` marad. A stíluslap nem értékelődik ki.
-
-### Belépő és kilépő animáció
-
-A stíluslap (a widgeté vagy a hosté) animálhatja a widget és a cella tartalmának érkezését és
-távozását:
-
-```css
-.contact-card { animation: contact-card-enter 300ms ease-out backwards; }
-.sb4-html-leaving .contact-card { animation: contact-card-leave 150ms ease-in forwards; }
-
-@keyframes contact-card-enter { from { opacity: 0; transform: translateY(12px); } }
-@keyframes contact-card-leave { to { opacity: 0; transform: translateY(-8px); } }
-
-@media (prefers-reduced-motion: reduce) {
-  .contact-card, .sb4-html-leaving .contact-card { animation: none; }
-}
-```
-
-- **Belépés**: a kiírt html új elemei a szokásos módon animálódnak. Ez minden olyan renderkor
-  lefut, amely **új html-t ír**: az első megjelenéskor, és valahányszor a feloldás eredménye
-  megváltozik (a modell vagy a sor olyan mezője változott, amit a html olvas). A változatlan
-  eredményű push semmit nem ír, ott nem fut.
-- **Kilépés**: mielőtt a kliens a képernyőn lévő html-t lecseréli, a widget, illetve a cella
-  elemére (`smart-html-widget`, `smart-html-cell`) felteszi az **`sb4-html-leaving`** osztályt.
-  Ha egy stíluslap erre az osztályra animációt vagy transitiont indít, a kliens megvárja a
-  végét, és csak utána írja ki az új html-t (és veszi le az osztályt). Ha semmi nem indul, azonnal
-  ír: kilépő CSS nélkül minden úgy működik, mint eddig.
-- A várakozás **legfeljebb 600 ms**: egy végtelen vagy túl hosszú kilépő animáció sem tartja fel
-  a frissítést. Csak az osztály által **elindított** animáció számít; ami már futott (pl. egy még
-  tartó belépő vagy egy végtelen pörgés), az nem.
-- Kilépés közben érkező újabb renderből **az utolsó** html kerül ki. Ha a feloldás közben
-  visszatér a képernyőn lévő html-re, a kilépés elmarad, az osztály lekerül.
-- Az első megjelenésnek nincs kilépése, csak belépése. Ugyanígy, ha a nézet layoutja cserélődik,
-  a widget újraépül: a régi elem kilépés nélkül tűnik el, az új belép.
-- A kilépés alatt a régi html és a hidratált toolbarjai még élnek és kattinthatók. A kilépő
-  animációt ezért érdemes röviden tartani, és `forwards` kitöltéssel a végállapotban hagyni, hogy
-  az új html kiírásáig ne villanjon vissza.
-- A `backwards` kitöltés a belépésnél azért jó, mert a vége után a `:hover` és a többi szabály
-  ismét mozgathatja az elemet (a `both` vagy a `forwards` animációs értéke felülírná őket).
-
-## A szerver-fázis
-
-A szerver-helyőrző a platform template-dialektusa: `${alias:/útvonal#mező?stratégia}`, mellette a
-`data-sb4-context` (iteráció) és a `data-sb4-if` (feltétel) attribútum. A builder a **nyitásáról**
-ismeri fel — `${alias:/` —, a sima `${name}` neki és a motornak is közömbös szöveg. Literálként
-`&#36;{`-nak írd.
-
-Három út oldja fel, és **egyik sem fut magától**:
-
-| Út | Mikor | Hiba esetén |
-|---|---|---|
-| `resolveTemplate(ctx, …)`, és az eredmény megy a `html(...)`-be | a build előtt | elnyel: logol, és a kulcsot vagy üres stringet ad vissza |
-| `h.template(ctx, KEY)` | a widget felépítésekor, kulcsból (lásd *Stíluslap a template-kulcs mellől*) | dob |
-| `h.resolveLater()` + `resolveHtml(ctx, layout)` | a **felépített layouton** | dob |
-
-```java
-SmartComponentLayoutDefinition layout = layoutBuilder(view)
-    .vForm(f -> f.html(h -> h.html(CARD_HTML).resolveLater()))
-    .build();
-resolveHtml(objectApi.contextObject().set("contact", contact), layout);   // PageApiImpl
-```
-
-- A `resolveHtml` bejárja a layout `FORM` / `CONTAINER` fáját és a widgetek gyerek-widgetjeit, és
-  minden HTML widget `html`-jét feloldja **ugyanazzal a ctx-szel**. A `css`, a `root` és a `fields`
-  marad. A gridekhez nem nyúl — egy sor-layout maga is layout, arra külön hívható. Page-en kívül:
-  `ObjectLayouts.resolveHtml(layout, resolver, objectApi, ctx)`; listára is van változata.
-- **Amiben nincs `${alias:/`, ahhoz hozzá sem ér** — az a html nem megy át a motoron, tehát nem is
-  normalizálódik. Ezért bármilyen layoutra ráhívható, és a második futás egy már feloldott
-  widgeten nem csinál semmit.
-- **Helyben módosít.** Ha az adat változik, **építsd újra a layoutot, ne oldd fel újra**: a
-  view-ban tárolt, egyszer már feloldott layoutban nincs mit feloldani, az új ctx-szel hívott
-  második futás némán a régi értékeket hagyja. Aki a feloldatlan eredetit meg akarja tartani,
-  másolaton hívja.
-- **Hangosan bukik** (`IllegalStateException`): ha van `${alias:/`, de nincs template-modul a
-  hostban; és ha a feloldás **után** is maradt — a motor az ismeretlen aliasú helyőrzőt ugyanis
-  szó nélkül benne hagyja. A motor másik két csendes esete megmarad: a hiányzó / `null` mező
-  helyére szóköz kerül, a mezőszintű feloldási hiba helyére a „Feldolgozási hiba" szöveg.
-
-**A `build()` őre.** Az a `${alias:/`, amit a három út egyike sem oldott fel, régen szó nélkül
-kiment a kliensre, és nyersen megjelent. Most a `HtmlWidgetBuilder.build()` `IllegalStateException`-t
-dob rá, kivéve ha a widget `resolveLater()`-t mondott. Ez a `vf.html(String)`, az
-`ObjectLayoutBuilder.html(...)` és a `GridBuilder.htmlColumn(...)` útjára is igaz.
-
-**Üres ctx-szel semmi nem oldódik fel**: a `${…}` literál marad (és a `build()` elbukik rajta), a
-`data-sb4-context` elemek eltűnnek. A grid-szintű sor-layoutnak és az oszlop-sablonnak nincs
-szerver-oldali, soronkénti kontextusa — ott a sorból jövő érték `{{…}}`, a szerveren számolt érték
-pedig a sor egy mezője legyen.
-
-## A kliens-helyőrzők nyelvtana
-
-Logika-mentes Mustache-részhalmaz. Ugyanezt a nyelvtant olvassa a Java-oldali
-`HtmlTemplateScanner` is, ezért a hibás template már a page felépítésekor elbukik.
-
-### Tag és path
-
-```
-{{path}}                          érték
-{{path | pipe:'arg' | pipe2}}     érték formázó pipe-okkal
-{{#path}} … {{/path}}             belépő szekció
-{{?path}} … {{/path}}             őr: van érték
-{{^path}} … {{/path}}             őr: nincs érték
-{{.}}  /  {{. | pipe}}            az aktuális scope maga
-{{../path}}                       path a körülvevő belépő szekció scope-jából
-```
-
-- A tagen belül a szóköz megengedett (`{{ name }}`, `{{# parties }}`).
-- **Path**: `(../)*azonosító(.azonosító)*`, az azonosító `[A-Za-z_][A-Za-z0-9_]*`. **Nincs** index
-  (`list[0]`), abszolút út, `{{..}}` és a path közepén álló `../` (`a/../b`).
-- Helyőrző text-node-ban és attribútum-**értékben** állhat (`class="status-{{status}}"`); tag- vagy
-  attribútum-névben nem.
-- **Nincs** raw (`{{{x}}}`, `{{&x}}` → hiba), partial, komment, delimiter-váltás, `@index`.
-- Literál `{{` a html-ben: `&#123;&#123;`.
-
-### Értékek
-
-- Hiányzó, `null` vagy `null`-on átvezető path → **üres string, csendben**.
-- Primitív → `String(v)` (`false` → `false`, `0` → `0`).
-- Objektum vagy lista `{{p}}`-ként → üres + `console.warn`.
-- Minden behelyettesített érték HTML-escape (`& < > " '`). URL-attribútumban (`href="{{url}}"`)
-  nincs séma-szűrés: az érték a szerver saját modelljéből jön, a szerző felel érte.
-
-### Szekciók — a jel dönt, nem az érték
-
-| Jel | Név | Mit csinál |
-|---|---|---|
-| `{{#p}}` | **belépő** szekció | lista: elemenként egyszer, a scope az elem; objektum: egyszer, a scope az objektum |
-| `{{?p}}` | **őr** | egyszer renderel, ha van érték; **a scope nem mozdul** |
-| `{{^p}}` | hamis-őr | egyszer renderel, ha nincs érték; a scope nem mozdul |
-
-- **„Nincs érték"** = hiányzó, `null`, `false`, `""`, üres lista. **A `0` érték** (szándékos eltérés
-  a Mustache-től: `{{?count}}` a nullát ne rejtse el).
-- **Szigorú scope**: belépő szekción belül a path csak az aktuális elemben oldódik, a szülő mezőit
-  magától nem éri el (nincs Mustache-féle felfelé keresés — attól a szerver mezőlistája az adattól
-  függne). A körülvevő scope **kimondva** érhető el: `{{../path}}`.
-- **`../`**: minden `../` egy **belépő** szekcióval lép kijjebb. A `?` és `^` őr nem szint (a scope-ot
-  sem mozdítja), átlát rajta. Érték-tagen, pipe-pal, attribútum-értékben és szekció-tagen is állhat
-  (`{{#../members}}…{{/../members}}` — a záró tag ugyanazt a pathot ismétli). A widget `root`-ja
-  fölé nem megy: több `../`, mint ahány belépő szekció nyitva van, hiba.
-- Szekció-tagen nincs pipe.
-- `{{#p}}` egyetlen értéken (szám, string): a kliens őrként rendereli és `console.warn`-t ír — a
-  Java-builder ezt nem látja előre (nincs adata), ilyenkor `{{?p}}` kell. A `../`-nek ez is egy
-  szint (a scope-ja a körülvevő), így a kliens és a szerver mezőlistája egyezik.
-- A szekció-tag üres stringre cserélődik, a körülötte lévő whitespace marad.
-
-```html
-<ul>
-  {{#parties}}
-  <li>{{displayName}} {{#roles}}<span>{{. | label:'BusinessRole'}}</span>{{/roles}}</li>
-  {{/parties}}
-</ul>
-{{^parties}}<p>— nincs érintett —</p>{{/parties}}
-{{?note}}<p class="note">{{note}}</p>{{/note}}
-```
-
-A kártya saját mezői a lista elemein belül, `root = "card"` mellett:
-
-```html
-<ul>
-  {{#parties}}
-  <li data-sb4-action="REMOVE_PARTY" data-sb4-action-identifier="{{../id}}_{{id}}">
-    {{displayName}} — {{../title}}
-    {{#roles}}<span>{{. | label:'BusinessRole'}} ({{../displayName}})</span>{{/roles}}
-  </li>
-  {{/parties}}
-</ul>
-```
-
-A származtatott mezők: `card.parties`, `card.id`, `card.parties.id`, `card.parties.displayName`,
-`card.title`, `card.parties.roles` — a `{{../displayName}}` a `roles`-on belülről a
-`card.parties.displayName`, a `{{../title}}` a `card.title`.
-
-### Formázó pipe-ok
-
-`| név` vagy `| név:'arg'`; az argumentum egyetlen, **egyszeres idézőjelű** literál (`\'` és `\\`
-escape-pel), a pipe-ok balról jobbra láncolhatók, a kimenetük is escape-en megy át. A készlet
-**zárt**:
-
-| Pipe | Argumentum | Default | Szemantika |
-|---|---|---|---|
-| `date` | date-fns formátum | `'yyyy.MM.dd'` | ISO string → böngésző-időzóna szerinti dátum |
-| `datetime` | date-fns formátum | `'yyyy.MM.dd H:mm'` | ugyanaz |
-| `time` | date-fns formátum | `'H:mm'` | ugyanaz; a csak-idő (`12:34:56`) értéket is olvassa |
-| `number` | Angular `digitsInfo` | `'1.0-3'` | `Intl.NumberFormat` a session locale-jával; szám és numerikus string |
-| `label` | a valueSet neve (**kötelező**) | — | kód → címke a kontextus `valueSets`-éből |
-| `default` | literál | `''` | üres / hiányzó érték helyett a literál |
-| `upper` / `lower` | nincs | — | kis/nagybetű a session locale-jával |
-
-- A defaultok a grid cella-defaultjai: a kártya és a tábla ugyanazt mutatja.
-- **Dátum**: a dróton nem minden dátum zulu (`…Z` / offset, offset nélküli `LocalDateTime`,
-  `LocalDate`, `LocalTime`) — mindet olvassa. Nem ISO érték → nyers érték + warn.
-  **A date-fns `YYYY` / `DD` tokenje hibás**: `yyyy` / `dd` kell.
-- **`label`**: a kulcs-mező `valueSetData.keyProperty`, különben `objectUri`, különben `uri`; a címke
-  `displayValue`, különben `name` — ugyanaz a lánc, mint a form select-jeinél. Nincs valueSet vagy
-  nincs találat → a nyers kód. A valueSetnek az oldal `ComponentModel.valueSets`-ében kell lennie.
-- Üres értéket a `default` kivételével minden pipe érintetlenül enged tovább.
-
-### Hibák
-
-| Hol | Mi történik |
-|---|---|
-| Java-builder (`build()`) | `IllegalArgumentException`: párosítatlan / keresztezett szekció, raw tag, érvénytelen path vagy `root`, a `root` fölé mutató `../`, ismeretlen pipe, rossz pipe-szintaxis, üres `data-sb4-toolbar` / `data-sb4-action` |
-| Java-builder (`build()`), `resolveHtml` | `IllegalStateException`: feloldatlan szerver-helyőrző (`${alias:/`), lásd *A szerver-fázis* |
-| kliens | nem dob: `console.error`, és a html **feloldatlanul** kerül ki — látható hiba, nem üres kártya |
-
-Egyetlen szándékos különbség: az ismeretlen pipe-név a kliensen csak warn (az érték formázatlanul
-megy ki), hogy egy régebbi kliens ne törjön el egy újabb szerver pipe-ján.
-
-### Szerzői szabályok a szerver-fázis miatt
-
-Ha a html átmegy a szerver template-motorján (Jsoup), akkor:
-
-- **egy gyökérelem kötelező** — a gyökér-szintű szöveg és szekció-tag eldobódik;
-- táblázatban **explicit `<tbody>`** kell, különben a parser a `{{#rows}}` után szúr egyet;
-- a whitespace-re (`:empty`, `white-space: pre`, `&nbsp;`) ne építs, a motor átírja;
-- a szerverről behelyettesített **érték ne tartalmazzon `{{`-t**: a motor HTML-escape-eli, de a
-  `{{` átmegy rajta, és a kliens helyőrzőnek olvasná (a néző saját adatán oldaná fel);
-- `?stratégia` után is állhat `{{…}}` — a stratégia a `{{`-on nem nyúl át.
-
-## Toolbar-slot
-
-```html
-<smart-ui-action-toolbar data-sb4-toolbar="ROW_TOOLBAR"
-    data-sb4-toolbar-direction="HORIZONTAL" data-sb4-toolbar-alignment="END"
-    data-sb4-toolbar-scrollable></smart-ui-action-toolbar>
-```
-
-A kliens a marker-elembe egy **valódi toolbart hidratál**, amely a `data-sb4-toolbar` alatti
-címre (`uiAction.toolbar == id`) címzett akciókat rajzolja ki — ugyanazokkal a szabályokkal, mint
-bármely más toolbar: a listát és a végrehajtót a környezetéből húzza (kártyán a sor akcióit,
-nézeten az oldalét). Java: `Tag.toolbar(id)` / `Tag.toolbar(id, toolbarProperties)`.
-
-- A marker **maga a `<smart-ui-action-toolbar>` tag** legyen: a hostok tag-szelektorral stílusozzák
-  a toolbart, egy `<div data-sb4-toolbar>` működne, de a host-CSS nem érné el.
-- Üres tartalommal írd (a hidratálás úgyis kitörli); a saját `class` / `style` attribútumaid
-  megmaradnak.
-- `direction`: `HORIZONTAL` | `VERTICAL`, `alignment`: `START` | `END`, a `scrollable` logikai
-  attribútum. Ismeretlen érték → warn, a tulajdonság kimarad.
-- A helyőrzők feloldása **megelőzi** a hidratálást, tehát az id is lehet sablon:
-  `data-sb4-toolbar="addr_{{id}}_toolbar"` — szekcióban elemenként más toolbar.
-- Üres vagy üresre feloldott id → warn, a slot kimarad. Ismétlődő marker → markerenként saját
-  toolbar.
-- A kliens csak akkor írja újra a html-t, ha a feloldás eredménye **megváltozott**; változatlan
-  eredménynél a hidratált toolbarok élnek tovább.
-
-## Akció-trigger
-
-```html
-<div class="card" data-sb4-action="OPEN_ENTRY">…</div>
-<li data-sb4-action="REMOVE_MEMBER" data-sb4-action-identifier="{{id}}">…</li>
-```
-
-Bármely elem hordozhat triggert: a kattintás (vagy Enter / Space) azt az akciót futtatja, amelynek
-a `code`-ja — és ha meg van adva, az `identifier`-e — egyezik. Az akciót a kliens **kattintáskor**
-keresi meg ugyanabban a listában, amiből az ott lévő toolbarok húznak, **a toolbar-címtől
-függetlenül**. Hiányzó `data-sb4-action-identifier` = identifier nélküli akció. Java:
-`Tag.action(code)` / `Tag.action(code, identifier)`.
-
-- **Lista-szekcióban elemenként egy akció kell a szerveren.** A `{{id}}`-s identifier címez, nem
-  paraméterez: a kliens a (kód, identifier) párt keresi a listában, tehát a page minden elemhez
-  kínáljon egy akciót a megfelelő `identifier`-rel (kártyán a sor akciói közt, nézeten a view akciói
-  közt). Egyetlen, identifier nélküli akció mellett az identifieres triggerek nem interaktívak.
-- **A gyökérelemre tett trigger a `DIV` widget `onClick`-jének megfelelője.** A HTML widgetnek
-  nincs saját kattintása.
-- **Csak-trigger akció**: ha egy nézet-szintű akciót csak trigger lőhet, a címe legyen
-  `UiActions.NO_TOOLBAR` (`"_none"`) — olyan cím, amit egyetlen toolbar sem visel, így az id nélküli
-  toolbarok sem rajzolják ki gombként. Kártyán (sorakciónál) nem kell.
-- A trigger nem enged tovább se klikket, se dupla klikket a körülötte lévő elemeknek: kártyán nem
-  jelöl ki és nem futtat default akciót. Beágyazott triggereknél a legbelső nyer.
-- `<a href>`-re tett triggernél az akció nyer, a link nem navigál.
-- **a11y**: nem natív elem (`div`, `span`, `li`…) `role="button"`-t és `tabindex="0"`-t kap, ha a
-  szerző nem adott mást; natív elemhez (`button`, `a[href]`, `input`…) a kliens nem nyúl.
-- **Letiltott akció**: `aria-disabled="true"` + `sb4-action-disabled` osztály, a kattintás no-op; az
-  állapot a lista változását a html újraírása nélkül követi.
-- **Nem kínált akció** (a sor / nézet nem adja): az elem nem interaktív, `sb4-action-inert` osztályt
-  kap, a kliens egyszer warn-ol, a kattintás a körülötte lévő triggerre vagy a kártyára jut.
-- Paraméter-attribútum nincs: az identifier és a sor-scope (`params.model` = a sor) fedi az
-  eseteket.
-
-## Sor-layoutok a kártya-griden
-
-A `GridViewDescriptor.rowLayouts` kulcsonként egy-egy layoutot visz **gridenként egyszer**; a
-kliens soronként rendereli a sor `data`-jával. Csak `kind == CARDS` mellett él.
-
-```java
-gridBuilder.kind(KindEnum.CARDS)
-    .rowLayout(layoutBuilder(view).vForm(f -> f.html(h -> h.html(CARD_HTML))).build())       // default
-    .rowLayout("DISTRIBUTION_LIST", listLayout);                                              // kulcsos
-```
-
-Melyik layouttal renderel egy sor, sorrendben:
-
-1. a sor saját `layoutDescriptor.componentLayouts.GRID_ROW_LAYOUT`-ja (soronkénti felülbírálás);
-2. a `rowLayouts[row.rowLayout]`;
-3. a **default sor-layout**: a `"default"` kulcs (`Layouts.DEFAULT_LAYOUT`), vagy ha csak egy
-   bejegyzés van, az;
-4. a host `<gridId>Card` néven regisztrált kártya-komponense;
-5. semmi.
-
-Ismeretlen kulcs → a default + egy `console.warn` (grid, sor, kulcs): az elgépelt kulcs nem tüntet
-el kártyát, de látszik.
-
-**Oszlopok.** A kártyán olvasott mezőket a grid oszlopainak kell adniuk: a `GridBuilder.build()`
-WARN-t ír minden olyan mezőre, amit egy oszlop sem fed (név vagy dot-prefix szerint: a `card`
-oszlop fedi a `card.parties.displayName`-et). A mezőlista ellenőriz, nem választ oszlopot.
-Szerver-származtatott mező (pl. `partyCount`) legyen valódi oszlop.
-
-**Kattintás** (csak a layoutból renderelt kártyán; a host-regisztrált kártya maga kezeli a saját
-klikkjeit). Két független tengely, ugyanaz a modell, mint a táblán:
-
-- **a kijelölést a `selectionMode` adja** (hiányzó = `NONE` = nincs kijelölés);
-- **a default sor-akció gesztusát a `GridViewDescriptor.defaultRowActionTrigger`**
-  (`click` | `doubleClick`), Java: `GridBuilder.defaultRowActionTrigger(...)`.
-
-| `defaultRowActionTrigger` | klikk | dupla klikk |
-|---|---|---|
-| nincs megadva (kártyán = `click`) | a sor **első** illő default akciója | — |
-| `click` | default akció; több illő akciónál **menü az egérnél** | — |
-| `doubleClick` | kijelölés, ha a grid és a sor jelölhető | default akció; több illőnél menü |
-
-- **A klikkes trigger elviszi a klikket a kijelölés elől**: ha a sornak van default akciója és a
-  trigger `click` (vagy nincs megadva), a kártya klikkre nem jelölhető ki, akármi a
-  `selectionMode`. Kártya-kijelöléshez `doubleClick` trigger kell, vagy default akció nélküli grid.
-- „Illő" default akció: a grid `defaultRowActions` kódjai közül az, amit a sor `actions`-e kínál —
-  a menü tehát soronként más lehet. Megadott trigger mellett egy illő akció azonnal elsül.
-- A dupla klikk második klikkje nem számít külön klikknek: nem nyit kétszer, és nem vonja vissza
-  az első klikk kijelölését (dupla klikk = kijelöl + megnyit). Amíg a default akció fut, az újabb
-  klikk is eldobódik.
-- A kijelölt kártya hostja `selected` osztályt és egy minimális, felülírható outline-t kap. A
-  kijelölés toggle, mint a táblán; `selectionType: CHECKBOX` a kártyán nem rajzol checkboxot.
-- A toolbar-gomb és a trigger megtartja magának a kattintást.
-- A tábla gesztusa változatlanul a dupla klikk, a mező értékétől függetlenül.
-
-## Html a tábla cellájában
-
-A tábla egy cellája kétféleképpen kaphat html-t, és a kettő **más bizalmi szinten** áll.
-
-| | HTML column | Column template |
-|---|---|---|
-| Honnan jön a html | a cella **értéke**, adatként (`GridRow.data`) | az oszlop **sablonja** (`GridColumnMeta.htmlProperties`) |
-| Ki írta | bármi, ami az adatot előállítja | a backend, mint a HTML widgetnél |
-| Kiírás | **sanitizált** innerHTML (Angular default) | változtatás nélkül, a behelyettesített értékek escape-elve |
-| Helyőrzők, toolbar-slot, trigger | nincs (a `data-*` és az ismeretlen tag kiesik) | mind, mint a widgetben |
-
-### HTML column és `contentType`
-
-A `GridColumnMeta.contentType` mondja meg, hogyan kerül ki az érték:
-
-- **hiányzó** vagy `html` — sanitizált innerHTML, ahogy a tábla mindig is írta. Semmi nem változik
-  annak a hostnak, amelyik nem állítja.
-- `text` — **escape-elt** szöveg: a `<b>` betűkként látszik. Erre való minden adat, amiben
-  felhasználói szöveg van és nem jelölésként kell olvasni.
-
-A rendezés a szerveren a **nyers** értéken fut, ezért html-oszlophoz adj
-`sortOrderPropertyName`-et. Java:
-
-```java
-gridBuilder.contentType(GridColumnContentType.TEXT, "name", "comment")
-```
-
-### Column template
-
-```java
-gridBuilder.htmlColumn("name", h -> h.html(t -> t
-    .b(b -> b.text("{{name}}"))
-    .span(s -> s.action("OPEN").text("megnyitás"))
-    .toolbar("ROW_TOOLBAR")))
-```
-
-- **Ugyanaz a bean, mint a widgeté** (`HtmlProperties`): `html`, `root`, `fields`, `css`, és
-  ugyanaz a nyelvtan, pipe-készlet, escape, stíluslap- és hibakezelés. A `root` a **sor `data`-jához** relatív; a
-  `valueSets` a gridet mutató oldalé.
-- A sablon az oszlop **minden érték-renderelését** kiváltja, a `typeClass` szerinti dátum-,
-  checkbox- és ikon-formázást is — a formázás a sablon pipe-jaiba kerül. A sor ikonjai
-  (`GridRow.icons`) és az oszlop cella-toolbarja (`columnActions`) mellette megmaradnak. Ha van
-  sablon, a `contentType` nem számít.
-- A toolbar-slot és a trigger **a sor akcióit** látja (`row.actions`), pontosan úgy, mint a
-  sor-layouttal renderelt kártya: az akció modellje a sor, a scope a grid és a sor. A trigger a
-  kattintást és a dupla kattintást megtartja magának, a sor-klikk nem fut.
-- **Sor-menü**: a csak-trigger akció (`UiActions.NO_TOOLBAR`) sosem kerül a sor menüjébe. Ha a
-  táblában van oszlop-sablon, akkor a **toolbar-címes** sorakció sem — az egy sablonbeli slot-é.
-  Sablon nélküli táblán a címes sorakció a menüben marad, ahogy eddig.
-- A cella a sor minden cseréjekor újra felold; változatlan eredménynél a html és a hidratált
-  toolbar él tovább. Teljesítmény-kalap nincs: nagy táblán a sablon soronként egyszer oldódik fel,
-  hidratálás csak ott fut, ahol slot van.
-- A `GridBuilder.build()` a sablon mezőit is ellenőrzi az oszlopokkal szemben, ugyanazzal a
-  WARN-nal, mint a sor-layoutét (`column '<név>' reads '<mező>' which no column covers`). Az
-  ismeretlen oszlopra adott sablon vagy `contentType` szintén WARN.
-- A `GridBuilder`-nek nincs template-feloldója: a `template(ctx, KEY)` itt nem működik. Kulcsból
-  épített sablonhoz építsd a widgetet a page layout-builderével, és add át a `properties(...)`-szel.
-
-## Példa: egy kártya
-
-```html
-<div class="contact-card contact-card-{{status}}" data-sb4-action="OPEN_CONTACT_ENTRY">
-  <div class="contact-card-main">
-    <div class="contact-card-icon contact-card-icon-{{channelType}}"></div>
-    <div class="contact-card-value">{{value}}</div>
-    <div class="contact-card-channel-type">{{channelType | label:'ContactChannelType'}}</div>
-    <div class="contact-card-modified">{{modifiedAt | datetime}}</div>
-    <smart-ui-action-toolbar data-sb4-toolbar="CONTACT_ROW_TOOLBAR"></smart-ui-action-toolbar>
-  </div>
-  <div class="contact-card-associations">
-    <div class="contact-card-associations-title">Érintettek ({{partyCount}})</div>
-    {{#parties}}
-    <div class="contact-card-related-party">
-      <div class="contact-card-related-party-initials">{{monogram}}</div>
-      <div class="contact-card-related-party-company">{{displayName}}</div>
-      <div>{{#businessRoles}}<span>{{. | label:'BusinessRole'}}</span> {{/businessRoles}}</div>
-    </div>
-    {{/parties}}
-    {{^parties}}<div class="contact-card-associations-title">— nincs érintett —</div>{{/parties}}
-  </div>
-</div>
-```
-
-`root = "card"`, ha a sor `data`-jában a kártya a `card` oszlop alatt van. Amit a kliens-dialektus
-szándékosan nem tud, annak a helye:
-
-- **ikon / értékfüggő megjelenés**: szerver-származtatott mező, vagy érték-alapú CSS-osztály
-  (`contact-card-icon-{{channelType}}`);
-- **feltétel egy érték egyenlőségére**: sor-layout kulcs (`row.rowLayout`), vagy szerver-származtatott
-  logikai mező + `{{?…}}` őr;
-- **darabszám** (`parties.size()`): valódi oszlop (`partyCount`);
-- **fordítás**: `label` pipe valueSetből, vagy a szerver-fázis `${…}`-e.
+# HTML widget — szerverről küldött html a `@smartbit4all/ng-client` 7.2-ben
+
+Ez a dokumentum a **HTML widget**, a **kliens-helyőrzők** (`{{…}}`), a html-be írt **toolbar-slot**
+és **akció-trigger**, a kártya-grid **sor-layoutjainak**, valamint a tábla **html-celláinak**
+referenciája. A Java-oldali builder (`HtmlWidgetBuilder`, `HtmlBuilder.Tag.toolbar/action`,
+`GridBuilder.rowLayout/htmlColumn/contentType`) javadocja
+ide hivatkozik; ha a kettő ellentmond egymásnak, ez a fájl az igazság.
+
+## Mire való
+
+A backend egy `HTML` típusú form-widgetet tehet a layoutba, amelynek a tartalma egy darab html. A
+html-t **két fázisban** oldjuk fel, két külön jelöléssel:
+
+| Fázis | Jelölés | Ki oldja fel | Mire jó |
+|---|---|---|---|
+| szerver-helyőrző | `${…}` | a backend, a page-ben, mielőtt a html elhagyja | feltétel, iteráció, szkript, lokalizáció — a platform meglévő template-dialektusa |
+| kliens-helyőrző | `{{…}}` | a kliens, a widget **feloldási kontextusán** | ugyanaz a html egyszer utazik és soronként / modell-változásonként újra feloldódik |
+
+A kliens a szerver-fázisból semmit nem lát: mire a html megérkezik, a `${…}` már nincs benne.
+
+**Bizalmi határ.** A html-t a backend írta, ezért a kliens **változtatás nélkül** írja ki (nincs
+sanitizálás: `data-*`, `style`, `<svg>`, inline `on*` mind él). Amit viszont a kliens helyettesít be
+egy `{{…}}` helyére, az **mindig HTML-escape-en** megy át, kivétel és „raw" forma nélkül. Ha a host
+Trusted Types-ot használ, a html kiírása miatt engedélyeznie kell a megfelelő policy-t. A widget
+stíluslapja (`css`, lásd *Stíluslap*) ugyanígy, változatlanul kerül a dokumentumba.
+
+A `DIV` widget változatlanul megmarad; a HTML widget annak a használatnak a rendes helye, amikor a
+`DIV`-be kész html-t tettünk.
+
+## A widget a dróton
+
+`SmartWidgetDefinition.type = HTML`, a tulajdonságai a `properties["HTML_properties"]` alatt
+(`HtmlProperties`):
+
+| Mező | Jelentés |
+|---|---|
+| `html` | a html, a `${…}` már feloldva, a `{{…}}` benne hagyva |
+| `root` | dot-path a kontextus `data`-jához képest, amihez minden helyőrző relatív; **objektumot** nevez; üres = a `data` maga |
+| `fields` | a widget által olvasott abszolút pathok — a builder származtatja a helyőrzőkből, a kliens **nem** olvassa |
+| `css` | a widget stíluslapja, a html mellett utazik — lásd *Stíluslap* |
+
+A **feloldási kontextus** nézeten a `ComponentModel` (`data` + `valueSets`), grid-kártyán a sor
+(`GridRow.data`) a gridet mutató oldal `valueSets`-ével. Ha a `root` listát, egyetlen értéket vagy
+semmit nevez, minden helyőrző üres marad, és a kliens egyszer `console.warn`-t ír.
+
+A widgetnek nincs kontrollja, címkéje, validálása és saját kattintása sem (lásd *Akció-trigger*).
+
+Java-oldalon:
+
+```java
+layoutBuilder(view).vForm(f -> f
+    .html(h -> h.root("card").html("<div class=\"card\">{{name}}</div>")))
+```
+
+vagy template-kulcsból (`h.template(ctx, "CONTACT_ENTRY_LIST")`): a kulcs a szerveren oldódik fel,
+a dróton nem utazik.
+
+## Stíluslap
+
+A widget a kinézetét is hozhatja: a `css` mezőben egy CSS-szöveget, amit a kliens a dokumentum
+`<head>`-jébe tesz (`<style data-sb4-html-css>`). Így a widget teljes egészében a szerverről jön, a
+hostnak nem kell hozzá stíluslapot szállítania.
+
+```java
+vf.html(h -> h.root("card")
+    .html("<div class=\"contact-card\">{{name}}</div>")
+    .css(".contact-card { padding: 1rem; border-radius: 12px; }"))
+```
+
+- **Egyszer kerül ki**, akárhány widget, kártya vagy cella hozza ugyanazt a szöveget, és az
+  utolsó eltűnésével a kliens kiveszi. A sor-layout és az oszlop-sablon is így működik: a `css` a
+  layout, illetve a sablon része, nem soronként utazik.
+- **Globális, nincs hatóköre.** Minden szelektor a html gyökérelemének egy osztályával kezdődjön
+  (`.contact-card …`), különben az egész oldalra hat. Két különböző szöveg ugyanarra a
+  szelektorra a betöltés sorrendjében nyer: adj widgetenként saját előtagot.
+- **Nem oldódik fel**: a `{{…}}`-nak nincs benne jelentése, modell-értéket nem lehet belevinni. Ami
+  a modelltől függ, az a html-ben legyen osztály (`class="status-{{status}}"`), a CSS pedig
+  osztályonként szabályozzon.
+- **CSP**: ha a host `style-src`-je nonce-os, adja meg az Angular `CSP_NONCE` tokenjét, a kliens
+  ráteszi a `<style>`-ra. Nonce és `'unsafe-inline'` nélkül a böngésző a stíluslapot blokkolja.
+- A builder nem vizsgálja és nem formázza: a `%` és a `{{` sem zavarja.
+
+### Stíluslap a template-kulcs mellől
+
+A `template(ctx, KEY)` a html mellé a stíluslapot is behúzza, ugyanazokon a neveken egy `.css`
+szegmenssel: `<viewName>.<KEY>.css`, `<KEY>.css`, … egészen a kulcs utolsó szegmenséig (a puszta
+`css` név sosem jön szóba). A fájl-registryben ez egy sor, pl.
+`CONTACT_ENTRY_LIST.css=templates/contact_entry_list.css`; MDM-ben egy ugyanilyen nevű
+`text/css` template.
+
+A html-lel ellentétben itt **nem egy nyer, hanem mind összefűződik**: előbb a fájlos stíluslapok,
+aztán az MDM-esek, mindkét rétegen belül az általánostól a specifikusig:
+
+```
+<KEY>.css (fájl) → <viewName>.<KEY>.css (fájl) → <KEY>.css (MDM) → <viewName>.<KEY>.css (MDM)
+```
+
+Mivel egyenlő specificitásnál a később jövő szabály nyer, az MDM a kódban szállított kinézetet
+szabályonként felülírhatja (ugyanazzal a szelektorral) vagy kiegészítheti (új szabállyal). A
+fájlban lévő `!important`-ot csak `!important` írja felül. A template-ből jött stíluslap lecseréli
+az addigi `css(...)`-t, egy későbbi `css(...)` pedig őt; ha a kulcshoz nincs stíluslap, az addigi
+`css` marad. A stíluslap nem értékelődik ki.
+
+### Belépő és kilépő animáció
+
+A stíluslap (a widgeté vagy a hosté) animálhatja a widget és a cella tartalmának érkezését és
+távozását:
+
+```css
+.contact-card { animation: contact-card-enter 300ms ease-out backwards; }
+.sb4-html-leaving .contact-card { animation: contact-card-leave 150ms ease-in forwards; }
+
+@keyframes contact-card-enter { from { opacity: 0; transform: translateY(12px); } }
+@keyframes contact-card-leave { to { opacity: 0; transform: translateY(-8px); } }
+
+@media (prefers-reduced-motion: reduce) {
+  .contact-card, .sb4-html-leaving .contact-card { animation: none; }
+}
+```
+
+- **Belépés**: a kiírt html új elemei a szokásos módon animálódnak. Ez minden olyan renderkor
+  lefut, amely **új html-t ír**: az első megjelenéskor, és valahányszor a feloldás eredménye
+  megváltozik (a modell vagy a sor olyan mezője változott, amit a html olvas). A változatlan
+  eredményű push semmit nem ír, ott nem fut.
+- **Kilépés**: mielőtt a kliens a képernyőn lévő html-t lecseréli, a widget, illetve a cella
+  elemére (`smart-html-widget`, `smart-html-cell`) felteszi az **`sb4-html-leaving`** osztályt.
+  Ha egy stíluslap erre az osztályra animációt vagy transitiont indít, a kliens megvárja a
+  végét, és csak utána írja ki az új html-t (és veszi le az osztályt). Ha semmi nem indul, azonnal
+  ír: kilépő CSS nélkül minden úgy működik, mint eddig.
+- A várakozás **legfeljebb 600 ms**: egy végtelen vagy túl hosszú kilépő animáció sem tartja fel
+  a frissítést. Csak az osztály által **elindított** animáció számít; ami már futott (pl. egy még
+  tartó belépő vagy egy végtelen pörgés), az nem.
+- Kilépés közben érkező újabb renderből **az utolsó** html kerül ki. Ha a feloldás közben
+  visszatér a képernyőn lévő html-re, a kilépés elmarad, az osztály lekerül.
+- Az első megjelenésnek nincs kilépése, csak belépése. Ugyanígy, ha a nézet layoutja cserélődik,
+  a widget újraépül: a régi elem kilépés nélkül tűnik el, az új belép.
+- A kilépés alatt a régi html és a hidratált toolbarjai még élnek és kattinthatók. A kilépő
+  animációt ezért érdemes röviden tartani, és `forwards` kitöltéssel a végállapotban hagyni, hogy
+  az új html kiírásáig ne villanjon vissza.
+- A `backwards` kitöltés a belépésnél azért jó, mert a vége után a `:hover` és a többi szabály
+  ismét mozgathatja az elemet (a `both` vagy a `forwards` animációs értéke felülírná őket).
+
+## A szerver-fázis
+
+A szerver-helyőrző a platform template-dialektusa: `${alias:/útvonal#mező?stratégia}`, mellette a
+`data-sb4-context` (iteráció) és a `data-sb4-if` (feltétel) attribútum. A builder a **nyitásáról**
+ismeri fel — `${alias:/` —, a sima `${name}` neki és a motornak is közömbös szöveg. Literálként
+`&#36;{`-nak írd.
+
+Három út oldja fel, és **egyik sem fut magától**:
+
+| Út | Mikor | Hiba esetén |
+|---|---|---|
+| `resolveTemplate(ctx, …)`, és az eredmény megy a `html(...)`-be | a build előtt | elnyel: logol, és a kulcsot vagy üres stringet ad vissza |
+| `h.template(ctx, KEY)` | a widget felépítésekor, kulcsból (lásd *Stíluslap a template-kulcs mellől*) | dob |
+| `h.resolveLater()` + `resolveHtml(ctx, layout)` | a **felépített layouton** | dob |
+
+```java
+SmartComponentLayoutDefinition layout = layoutBuilder(view)
+    .vForm(f -> f.html(h -> h.html(CARD_HTML).resolveLater()))
+    .build();
+resolveHtml(objectApi.contextObject().set("contact", contact), layout);   // PageApiImpl
+```
+
+- A `resolveHtml` bejárja a layout `FORM` / `CONTAINER` fáját és a widgetek gyerek-widgetjeit, és
+  minden HTML widget `html`-jét feloldja **ugyanazzal a ctx-szel**. A `css`, a `root` és a `fields`
+  marad. A gridekhez nem nyúl — egy sor-layout maga is layout, arra külön hívható. Page-en kívül:
+  `ObjectLayouts.resolveHtml(layout, resolver, objectApi, ctx)`; listára is van változata.
+- **Amiben nincs `${alias:/`, ahhoz hozzá sem ér** — az a html nem megy át a motoron, tehát nem is
+  normalizálódik. Ezért bármilyen layoutra ráhívható, és a második futás egy már feloldott
+  widgeten nem csinál semmit.
+- **Helyben módosít.** Ha az adat változik, **építsd újra a layoutot, ne oldd fel újra**: a
+  view-ban tárolt, egyszer már feloldott layoutban nincs mit feloldani, az új ctx-szel hívott
+  második futás némán a régi értékeket hagyja. Aki a feloldatlan eredetit meg akarja tartani,
+  másolaton hívja.
+- **Hangosan bukik** (`IllegalStateException`): ha van `${alias:/`, de nincs template-modul a
+  hostban; és ha a feloldás **után** is maradt — a motor az ismeretlen aliasú helyőrzőt ugyanis
+  szó nélkül benne hagyja. A motor másik két csendes esete megmarad: a hiányzó / `null` mező
+  helyére szóköz kerül, a mezőszintű feloldási hiba helyére a „Feldolgozási hiba" szöveg.
+
+**A `build()` őre.** Az a `${alias:/`, amit a három út egyike sem oldott fel, régen szó nélkül
+kiment a kliensre, és nyersen megjelent. Most a `HtmlWidgetBuilder.build()` `IllegalStateException`-t
+dob rá, kivéve ha a widget `resolveLater()`-t mondott. Ez a `vf.html(String)`, az
+`ObjectLayoutBuilder.html(...)` és a `GridBuilder.htmlColumn(...)` útjára is igaz.
+
+**Üres ctx-szel semmi nem oldódik fel**: a `${…}` literál marad (és a `build()` elbukik rajta), a
+`data-sb4-context` elemek eltűnnek. A grid-szintű sor-layoutnak és az oszlop-sablonnak nincs
+szerver-oldali, soronkénti kontextusa — ott a sorból jövő érték `{{…}}`, a szerveren számolt érték
+pedig a sor egy mezője legyen.
+
+## A kliens-helyőrzők nyelvtana
+
+Logika-mentes Mustache-részhalmaz. Ugyanezt a nyelvtant olvassa a Java-oldali
+`HtmlTemplateScanner` is, ezért a hibás template már a page felépítésekor elbukik.
+
+### Tag és path
+
+```
+{{path}}                          érték
+{{path | pipe:'arg' | pipe2}}     érték formázó pipe-okkal
+{{#path}} … {{/path}}             belépő szekció
+{{?path}} … {{/path}}             őr: van érték
+{{^path}} … {{/path}}             őr: nincs érték
+{{.}}  /  {{. | pipe}}            az aktuális scope maga
+{{../path}}                       path a körülvevő belépő szekció scope-jából
+```
+
+- A tagen belül a szóköz megengedett (`{{ name }}`, `{{# parties }}`).
+- **Path**: `(../)*azonosító(.azonosító)*`, az azonosító `[A-Za-z_][A-Za-z0-9_]*`. **Nincs** index
+  (`list[0]`), abszolút út, `{{..}}` és a path közepén álló `../` (`a/../b`).
+- Helyőrző text-node-ban és attribútum-**értékben** állhat (`class="status-{{status}}"`); tag- vagy
+  attribútum-névben nem.
+- **Nincs** raw (`{{{x}}}`, `{{&x}}` → hiba), partial, komment, delimiter-váltás, `@index`.
+- Literál `{{` a html-ben: `&#123;&#123;`.
+
+### Értékek
+
+- Hiányzó, `null` vagy `null`-on átvezető path → **üres string, csendben**.
+- Primitív → `String(v)` (`false` → `false`, `0` → `0`).
+- Objektum vagy lista `{{p}}`-ként → üres + `console.warn`.
+- Minden behelyettesített érték HTML-escape (`& < > " '`). URL-attribútumban (`href="{{url}}"`)
+  nincs séma-szűrés: az érték a szerver saját modelljéből jön, a szerző felel érte.
+
+### Szekciók — a jel dönt, nem az érték
+
+| Jel | Név | Mit csinál |
+|---|---|---|
+| `{{#p}}` | **belépő** szekció | lista: elemenként egyszer, a scope az elem; objektum: egyszer, a scope az objektum |
+| `{{?p}}` | **őr** | egyszer renderel, ha van érték; **a scope nem mozdul** |
+| `{{^p}}` | hamis-őr | egyszer renderel, ha nincs érték; a scope nem mozdul |
+
+- **„Nincs érték"** = hiányzó, `null`, `false`, `""`, üres lista. **A `0` érték** (szándékos eltérés
+  a Mustache-től: `{{?count}}` a nullát ne rejtse el).
+- **Szigorú scope**: belépő szekción belül a path csak az aktuális elemben oldódik, a szülő mezőit
+  magától nem éri el (nincs Mustache-féle felfelé keresés — attól a szerver mezőlistája az adattól
+  függne). A körülvevő scope **kimondva** érhető el: `{{../path}}`.
+- **`../`**: minden `../` egy **belépő** szekcióval lép kijjebb. A `?` és `^` őr nem szint (a scope-ot
+  sem mozdítja), átlát rajta. Érték-tagen, pipe-pal, attribútum-értékben és szekció-tagen is állhat
+  (`{{#../members}}…{{/../members}}` — a záró tag ugyanazt a pathot ismétli). A widget `root`-ja
+  fölé nem megy: több `../`, mint ahány belépő szekció nyitva van, hiba.
+- Szekció-tagen nincs pipe.
+- `{{#p}}` egyetlen értéken (szám, string): a kliens őrként rendereli és `console.warn`-t ír — a
+  Java-builder ezt nem látja előre (nincs adata), ilyenkor `{{?p}}` kell. A `../`-nek ez is egy
+  szint (a scope-ja a körülvevő), így a kliens és a szerver mezőlistája egyezik.
+- A szekció-tag üres stringre cserélődik, a körülötte lévő whitespace marad.
+
+```html
+<ul>
+  {{#parties}}
+  <li>{{displayName}} {{#roles}}<span>{{. | label:'BusinessRole'}}</span>{{/roles}}</li>
+  {{/parties}}
+</ul>
+{{^parties}}<p>— nincs érintett —</p>{{/parties}}
+{{?note}}<p class="note">{{note}}</p>{{/note}}
+```
+
+A kártya saját mezői a lista elemein belül, `root = "card"` mellett:
+
+```html
+<ul>
+  {{#parties}}
+  <li data-sb4-action="REMOVE_PARTY" data-sb4-action-identifier="{{../id}}_{{id}}">
+    {{displayName}} — {{../title}}
+    {{#roles}}<span>{{. | label:'BusinessRole'}} ({{../displayName}})</span>{{/roles}}
+  </li>
+  {{/parties}}
+</ul>
+```
+
+A származtatott mezők: `card.parties`, `card.id`, `card.parties.id`, `card.parties.displayName`,
+`card.title`, `card.parties.roles` — a `{{../displayName}}` a `roles`-on belülről a
+`card.parties.displayName`, a `{{../title}}` a `card.title`.
+
+### Formázó pipe-ok
+
+`| név` vagy `| név:'arg'`; az argumentum egyetlen, **egyszeres idézőjelű** literál (`\'` és `\\`
+escape-pel), a pipe-ok balról jobbra láncolhatók, a kimenetük is escape-en megy át. A készlet
+**zárt**:
+
+| Pipe | Argumentum | Default | Szemantika |
+|---|---|---|---|
+| `date` | date-fns formátum | `'yyyy.MM.dd'` | ISO string → böngésző-időzóna szerinti dátum |
+| `datetime` | date-fns formátum | `'yyyy.MM.dd H:mm'` | ugyanaz |
+| `time` | date-fns formátum | `'H:mm'` | ugyanaz; a csak-idő (`12:34:56`) értéket is olvassa |
+| `number` | Angular `digitsInfo` | `'1.0-3'` | `Intl.NumberFormat` a session locale-jával; szám és numerikus string |
+| `label` | a valueSet neve (**kötelező**) | — | kód → címke a kontextus `valueSets`-éből |
+| `default` | literál | `''` | üres / hiányzó érték helyett a literál |
+| `upper` / `lower` | nincs | — | kis/nagybetű a session locale-jával |
+
+- A defaultok a grid cella-defaultjai: a kártya és a tábla ugyanazt mutatja.
+- **Dátum**: a dróton nem minden dátum zulu (`…Z` / offset, offset nélküli `LocalDateTime`,
+  `LocalDate`, `LocalTime`) — mindet olvassa. Nem ISO érték → nyers érték + warn.
+  **A date-fns `YYYY` / `DD` tokenje hibás**: `yyyy` / `dd` kell.
+- **`label`**: a kulcs-mező `valueSetData.keyProperty`, különben `objectUri`, különben `uri`; a címke
+  `displayValue`, különben `name` — ugyanaz a lánc, mint a form select-jeinél. Nincs valueSet vagy
+  nincs találat → a nyers kód. A valueSetnek az oldal `ComponentModel.valueSets`-ében kell lennie.
+- Üres értéket a `default` kivételével minden pipe érintetlenül enged tovább.
+
+### Hibák
+
+| Hol | Mi történik |
+|---|---|
+| Java-builder (`build()`) | `IllegalArgumentException`: párosítatlan / keresztezett szekció, raw tag, érvénytelen path vagy `root`, a `root` fölé mutató `../`, ismeretlen pipe, rossz pipe-szintaxis, üres `data-sb4-toolbar` / `data-sb4-action` |
+| Java-builder (`build()`), `resolveHtml` | `IllegalStateException`: feloldatlan szerver-helyőrző (`${alias:/`), lásd *A szerver-fázis* |
+| kliens | nem dob: `console.error`, és a html **feloldatlanul** kerül ki — látható hiba, nem üres kártya |
+
+Egyetlen szándékos különbség: az ismeretlen pipe-név a kliensen csak warn (az érték formázatlanul
+megy ki), hogy egy régebbi kliens ne törjön el egy újabb szerver pipe-ján.
+
+### Szerzői szabályok a szerver-fázis miatt
+
+Ha a html átmegy a szerver template-motorján (Jsoup), akkor:
+
+- **egy gyökérelem kötelező** — a gyökér-szintű szöveg és szekció-tag eldobódik;
+- táblázatban **explicit `<tbody>`** kell, különben a parser a `{{#rows}}` után szúr egyet;
+- a whitespace-re (`:empty`, `white-space: pre`, `&nbsp;`) ne építs, a motor átírja;
+- a szerverről behelyettesített **érték ne tartalmazzon `{{`-t**: a motor HTML-escape-eli, de a
+  `{{` átmegy rajta, és a kliens helyőrzőnek olvasná (a néző saját adatán oldaná fel);
+- `?stratégia` után is állhat `{{…}}` — a stratégia a `{{`-on nem nyúl át.
+
+## Toolbar-slot
+
+```html
+<smart-ui-action-toolbar data-sb4-toolbar="ROW_TOOLBAR"
+    data-sb4-toolbar-direction="HORIZONTAL" data-sb4-toolbar-alignment="END"
+    data-sb4-toolbar-scrollable></smart-ui-action-toolbar>
+```
+
+A kliens a marker-elembe egy **valódi toolbart hidratál**, amely a `data-sb4-toolbar` alatti
+címre (`uiAction.toolbar == id`) címzett akciókat rajzolja ki — ugyanazokkal a szabályokkal, mint
+bármely más toolbar: a listát és a végrehajtót a környezetéből húzza (kártyán a sor akcióit,
+nézeten az oldalét). Java: `Tag.toolbar(id)` / `Tag.toolbar(id, toolbarProperties)`.
+
+- A marker **maga a `<smart-ui-action-toolbar>` tag** legyen: a hostok tag-szelektorral stílusozzák
+  a toolbart, egy `<div data-sb4-toolbar>` működne, de a host-CSS nem érné el.
+- Üres tartalommal írd (a hidratálás úgyis kitörli); a saját `class` / `style` attribútumaid
+  megmaradnak.
+- `direction`: `HORIZONTAL` | `VERTICAL`, `alignment`: `START` | `END`, a `scrollable` logikai
+  attribútum. Ismeretlen érték → warn, a tulajdonság kimarad.
+- A helyőrzők feloldása **megelőzi** a hidratálást, tehát az id is lehet sablon:
+  `data-sb4-toolbar="addr_{{id}}_toolbar"` — szekcióban elemenként más toolbar.
+- Üres vagy üresre feloldott id → warn, a slot kimarad. Ismétlődő marker → markerenként saját
+  toolbar.
+- A kliens csak akkor írja újra a html-t, ha a feloldás eredménye **megváltozott**; változatlan
+  eredménynél a hidratált toolbarok élnek tovább.
+
+## Akció-trigger
+
+```html
+<div class="card" data-sb4-action="OPEN_ENTRY">…</div>
+<li data-sb4-action="REMOVE_MEMBER" data-sb4-action-identifier="{{id}}">…</li>
+```
+
+Bármely elem hordozhat triggert: a kattintás (vagy Enter / Space) azt az akciót futtatja, amelynek
+a `code`-ja — és ha meg van adva, az `identifier`-e — egyezik. Az akciót a kliens **kattintáskor**
+keresi meg ugyanabban a listában, amiből az ott lévő toolbarok húznak, **a toolbar-címtől
+függetlenül**. Hiányzó `data-sb4-action-identifier` = identifier nélküli akció. Java:
+`Tag.action(code)` / `Tag.action(code, identifier)`.
+
+- **Lista-szekcióban elemenként egy akció kell a szerveren.** A `{{id}}`-s identifier címez, nem
+  paraméterez: a kliens a (kód, identifier) párt keresi a listában, tehát a page minden elemhez
+  kínáljon egy akciót a megfelelő `identifier`-rel (kártyán a sor akciói közt, nézeten a view akciói
+  közt). Egyetlen, identifier nélküli akció mellett az identifieres triggerek nem interaktívak.
+- **A gyökérelemre tett trigger a `DIV` widget `onClick`-jének megfelelője.** A HTML widgetnek
+  nincs saját kattintása.
+- **Csak-trigger akció**: ha egy nézet-szintű akciót csak trigger lőhet, a címe legyen
+  `UiActions.NO_TOOLBAR` (`"_none"`) — olyan cím, amit egyetlen toolbar sem visel, így az id nélküli
+  toolbarok sem rajzolják ki gombként. Kártyán (sorakciónál) nem kell.
+- A trigger nem enged tovább se klikket, se dupla klikket a körülötte lévő elemeknek: kártyán nem
+  jelöl ki és nem futtat default akciót. Beágyazott triggereknél a legbelső nyer.
+- `<a href>`-re tett triggernél az akció nyer, a link nem navigál.
+- **a11y**: nem natív elem (`div`, `span`, `li`…) `role="button"`-t és `tabindex="0"`-t kap, ha a
+  szerző nem adott mást; natív elemhez (`button`, `a[href]`, `input`…) a kliens nem nyúl.
+- **Letiltott akció**: `aria-disabled="true"` + `sb4-action-disabled` osztály, a kattintás no-op; az
+  állapot a lista változását a html újraírása nélkül követi.
+- **Nem kínált akció** (a sor / nézet nem adja): az elem nem interaktív, `sb4-action-inert` osztályt
+  kap, a kliens egyszer warn-ol, a kattintás a körülötte lévő triggerre vagy a kártyára jut.
+- Paraméter-attribútum nincs: az identifier és a sor-scope (`params.model` = a sor) fedi az
+  eseteket.
+
+## Sor-layoutok a kártya-griden
+
+A `GridViewDescriptor.rowLayouts` kulcsonként egy-egy layoutot visz **gridenként egyszer**; a
+kliens soronként rendereli a sor `data`-jával. Csak `kind == CARDS` mellett él.
+
+```java
+gridBuilder.kind(KindEnum.CARDS)
+    .rowLayout(layoutBuilder(view).vForm(f -> f.html(h -> h.html(CARD_HTML))).build())       // default
+    .rowLayout("DISTRIBUTION_LIST", listLayout);                                              // kulcsos
+```
+
+Melyik layouttal renderel egy sor, sorrendben:
+
+1. a sor saját `layoutDescriptor.componentLayouts.GRID_ROW_LAYOUT`-ja (soronkénti felülbírálás);
+2. a `rowLayouts[row.rowLayout]`;
+3. a **default sor-layout**: a `"default"` kulcs (`Layouts.DEFAULT_LAYOUT`), vagy ha csak egy
+   bejegyzés van, az;
+4. a host `<gridId>Card` néven regisztrált kártya-komponense;
+5. semmi.
+
+Ismeretlen kulcs → a default + egy `console.warn` (grid, sor, kulcs): az elgépelt kulcs nem tüntet
+el kártyát, de látszik.
+
+**Oszlopok.** A kártyán olvasott mezőket a grid oszlopainak kell adniuk: a `GridBuilder.build()`
+WARN-t ír minden olyan mezőre, amit egy oszlop sem fed (név vagy dot-prefix szerint: a `card`
+oszlop fedi a `card.parties.displayName`-et). A mezőlista ellenőriz, nem választ oszlopot.
+Szerver-származtatott mező (pl. `partyCount`) legyen valódi oszlop.
+
+**Kattintás** (csak a layoutból renderelt kártyán; a host-regisztrált kártya maga kezeli a saját
+klikkjeit). Két független tengely, ugyanaz a modell, mint a táblán:
+
+- **a kijelölést a `selectionMode` adja** (hiányzó = `NONE` = nincs kijelölés);
+- **a default sor-akció gesztusát a `GridViewDescriptor.defaultRowActionTrigger`**
+  (`click` | `doubleClick`), Java: `GridBuilder.defaultRowActionTrigger(...)`.
+
+| `defaultRowActionTrigger` | klikk | dupla klikk |
+|---|---|---|
+| nincs megadva (kártyán = `click`) | a sor **első** illő default akciója | — |
+| `click` | default akció; több illő akciónál **menü az egérnél** | — |
+| `doubleClick` | kijelölés, ha a grid és a sor jelölhető | default akció; több illőnél menü |
+
+- **A klikkes trigger elviszi a klikket a kijelölés elől**: ha a sornak van default akciója és a
+  trigger `click` (vagy nincs megadva), a kártya klikkre nem jelölhető ki, akármi a
+  `selectionMode`. Kártya-kijelöléshez `doubleClick` trigger kell, vagy default akció nélküli grid.
+- „Illő" default akció: a grid `defaultRowActions` kódjai közül az, amit a sor `actions`-e kínál —
+  a menü tehát soronként más lehet. Megadott trigger mellett egy illő akció azonnal elsül.
+- A dupla klikk második klikkje nem számít külön klikknek: nem nyit kétszer, és nem vonja vissza
+  az első klikk kijelölését (dupla klikk = kijelöl + megnyit). Amíg a default akció fut, az újabb
+  klikk is eldobódik.
+- A kijelölt kártya hostja `selected` osztályt és egy minimális, felülírható outline-t kap. A
+  kijelölés toggle, mint a táblán; `selectionType: CHECKBOX` a kártyán nem rajzol checkboxot.
+- A toolbar-gomb és a trigger megtartja magának a kattintást.
+- A tábla gesztusa változatlanul a dupla klikk, a mező értékétől függetlenül.
+
+## Html a tábla cellájában
+
+A tábla egy cellája kétféleképpen kaphat html-t, és a kettő **más bizalmi szinten** áll.
+
+| | HTML column | Column template |
+|---|---|---|
+| Honnan jön a html | a cella **értéke**, adatként (`GridRow.data`) | az oszlop **sablonja** (`GridColumnMeta.htmlProperties`) |
+| Ki írta | bármi, ami az adatot előállítja | a backend, mint a HTML widgetnél |
+| Kiírás | **sanitizált** innerHTML (Angular default) | változtatás nélkül, a behelyettesített értékek escape-elve |
+| Helyőrzők, toolbar-slot, trigger | nincs (a `data-*` és az ismeretlen tag kiesik) | mind, mint a widgetben |
+
+### HTML column és `contentType`
+
+A `GridColumnMeta.contentType` mondja meg, hogyan kerül ki az érték:
+
+- **hiányzó** vagy `html` — sanitizált innerHTML, ahogy a tábla mindig is írta. Semmi nem változik
+  annak a hostnak, amelyik nem állítja.
+- `text` — **escape-elt** szöveg: a `<b>` betűkként látszik. Erre való minden adat, amiben
+  felhasználói szöveg van és nem jelölésként kell olvasni.
+
+A rendezés a szerveren a **nyers** értéken fut, ezért html-oszlophoz adj
+`sortOrderPropertyName`-et. Java:
+
+```java
+gridBuilder.contentType(GridColumnContentType.TEXT, "name", "comment")
+```
+
+### Column template
+
+```java
+gridBuilder.htmlColumn("name", h -> h.html(t -> t
+    .b(b -> b.text("{{name}}"))
+    .span(s -> s.action("OPEN").text("megnyitás"))
+    .toolbar("ROW_TOOLBAR")))
+```
+
+- **Ugyanaz a bean, mint a widgeté** (`HtmlProperties`): `html`, `root`, `fields`, `css`, és
+  ugyanaz a nyelvtan, pipe-készlet, escape, stíluslap- és hibakezelés. A `root` a **sor `data`-jához** relatív; a
+  `valueSets` a gridet mutató oldalé.
+- A sablon az oszlop **minden érték-renderelését** kiváltja, a `typeClass` szerinti dátum-,
+  checkbox- és ikon-formázást is — a formázás a sablon pipe-jaiba kerül. A sor ikonjai
+  (`GridRow.icons`) és az oszlop cella-toolbarja (`columnActions`) mellette megmaradnak. Ha van
+  sablon, a `contentType` nem számít.
+- A toolbar-slot és a trigger **a sor akcióit** látja (`row.actions`), pontosan úgy, mint a
+  sor-layouttal renderelt kártya: az akció modellje a sor, a scope a grid és a sor. A trigger a
+  kattintást és a dupla kattintást megtartja magának, a sor-klikk nem fut.
+- **Sor-menü**: a csak-trigger akció (`UiActions.NO_TOOLBAR`) sosem kerül a sor menüjébe. Ha a
+  táblában van oszlop-sablon, akkor a **toolbar-címes** sorakció sem — az egy sablonbeli slot-é.
+  Sablon nélküli táblán a címes sorakció a menüben marad, ahogy eddig.
+- A cella a sor minden cseréjekor újra felold; változatlan eredménynél a html és a hidratált
+  toolbar él tovább. Teljesítmény-kalap nincs: nagy táblán a sablon soronként egyszer oldódik fel,
+  hidratálás csak ott fut, ahol slot van.
+- A `GridBuilder.build()` a sablon mezőit is ellenőrzi az oszlopokkal szemben, ugyanazzal a
+  WARN-nal, mint a sor-layoutét (`column '<név>' reads '<mező>' which no column covers`). Az
+  ismeretlen oszlopra adott sablon vagy `contentType` szintén WARN.
+- A `GridBuilder`-nek nincs template-feloldója: a `template(ctx, KEY)` itt nem működik. Kulcsból
+  épített sablonhoz építsd a widgetet a page layout-builderével, és add át a `properties(...)`-szel.
+
+## Példa: egy kártya
+
+```html
+<div class="contact-card contact-card-{{status}}" data-sb4-action="OPEN_CONTACT_ENTRY">
+  <div class="contact-card-main">
+    <div class="contact-card-icon contact-card-icon-{{channelType}}"></div>
+    <div class="contact-card-value">{{value}}</div>
+    <div class="contact-card-channel-type">{{channelType | label:'ContactChannelType'}}</div>
+    <div class="contact-card-modified">{{modifiedAt | datetime}}</div>
+    <smart-ui-action-toolbar data-sb4-toolbar="CONTACT_ROW_TOOLBAR"></smart-ui-action-toolbar>
+  </div>
+  <div class="contact-card-associations">
+    <div class="contact-card-associations-title">Érintettek ({{partyCount}})</div>
+    {{#parties}}
+    <div class="contact-card-related-party">
+      <div class="contact-card-related-party-initials">{{monogram}}</div>
+      <div class="contact-card-related-party-company">{{displayName}}</div>
+      <div>{{#businessRoles}}<span>{{. | label:'BusinessRole'}}</span> {{/businessRoles}}</div>
+    </div>
+    {{/parties}}
+    {{^parties}}<div class="contact-card-associations-title">— nincs érintett —</div>{{/parties}}
+  </div>
+</div>
+```
+
+`root = "card"`, ha a sor `data`-jában a kártya a `card` oszlop alatt van. Amit a kliens-dialektus
+szándékosan nem tud, annak a helye:
+
+- **ikon / értékfüggő megjelenés**: szerver-származtatott mező, vagy érték-alapú CSS-osztály
+  (`contact-card-icon-{{channelType}}`);
+- **feltétel egy érték egyenlőségére**: sor-layout kulcs (`row.rowLayout`), vagy szerver-származtatott
+  logikai mező + `{{?…}}` őr;
+- **darabszám** (`parties.size()`): valódi oszlop (`partyCount`);
+- **fordítás**: `label` pipe valueSetből, vagy a szerver-fázis `${…}`-e.