npm - @smartbit4all/ng-client - Versions diffs - 7.3.3 → 7.3.5 - Mend

@smartbit4all/ng-client 7.3.3 → 7.3.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/HTML-WIDGET.md +707 -645
package/MIGRATION-7.0.md +2214 -2187
package/README.md +206 -206
package/WIDGETS.md +226 -226
package/fesm2022/smartbit4all-ng-client.mjs +8419 -8177
package/fesm2022/smartbit4all-ng-client.mjs.map +1 -1
package/package.json +1 -1
package/smartbit4all-ng-client-7.3.5.tgz +0 -0
package/types/smartbit4all-ng-client.d.ts +777 -131
package/smartbit4all-ng-client-7.3.3.tgz +0 -0

package/HTML-WIDGET.md CHANGED Viewed

@@ -1,645 +1,707 @@
-# 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* |
-| `icons` | az **ikon-szótár**: `kulcs → ImageResource`, amit az ikon-slotok `data-sb4-icon-key`-jel címeznek — lásd *Ikon-slot* |
-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.
-A html sima szöveg, tehát a `Tag` builder helyett **text blockként** is írható — így a sablon
-ugyanúgy néz ki, ahogy a kliens megkapja:
-```java
-.html("""
-    <div class="card">
-      <smart-icon data-sb4-icon="{{typeIcon}}"></smart-icon>
-      <b>{{name}}</b>
-    </div>""")
-```
-A `html(String, Object...)` `String.format`-tal illeszti be az argumentumokat (akciókód,
-toolbar-id), ilyenkor a szövegben a `%` `%%`.
-## 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`. Egyetlen kivétel: egy **ikon-slot**
-  név-attribútumának teljes értékeként az objektum az ikon `ImageResource`-a lesz — lásd
-  *Ikon-slot*.
-- 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` /
-`data-sb4-icon` / `data-sb4-icon-key`, `data-sb4-icon` és `data-sb4-icon-key` ugyanazon az elemen |
-| Java-builder (`build()`) | `IllegalStateException`: a sablonban álló literál ikon-kulcs, amit az ikon-szótár nem tartalmaz |
-| 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.
-## Ikon-slot
-```html
-<smart-icon data-sb4-icon="mail" data-sb4-icon-color="warn"></smart-icon>
-<smart-icon data-sb4-icon="{{typeIcon}}"></smart-icon>
-<smart-icon data-sb4-icon-key="{{type}}"></smart-icon>
-```
-A kliens a marker-elembe egy **valódi `smart-icon`-t hidratál**, ugyanazt a komponenst, amit a
-gomb, a grid-cella és a form használ. Java: `Tag.icon(name)`, `Tag.icon(name, color)`,
-`Tag.icon(imageResource)`, `Tag.iconKey(key)`, a szótár a widget-builderen: `h.icon(key, resource)`
-/ `h.icons(map)`.
-Az ikon címe négyféle lehet, és mindegyiknek megvan a maga esete:
-| Forma | Mit ad az ikonnak | Mikor |
-|---|---|---|
-| `data-sb4-icon="mail"` | `icon` input: a név előbb a regisztrált svg-névterekben, aztán Material-ligatúraként | fix ikon, vagy adatból jövő **ikonnév** |
-| `data-sb4-icon="{{typeIcon}}"`, az érték **objektum** | `imageResource` input | soronként más erőforrás (feltöltött kép, `ImageSettingApi` a modellben) |
-| `data-sb4-icon="{…}"` (JSON) | `imageResource` input | a page által **egyszer** feloldott erőforrás (`Tag.icon(resource)`) |
-| `data-sb4-icon-key="{{type}}"` | `imageResource` input a **szótárból** | véges típus → ikon leképezés |
-- **`data-sb4-icon-color`**: a `color` input, vagyis téma- vagy host-osztálynév (`primary`,
-  `text-primary`, `warn` …), **nem** CSS-szín. Csak a név-formához való: az `ImageResource` a saját
-  `color`-ját hozza. Elhagyva a komponens alapértelmezése (`primary`) marad.
-- **Objektum csak ott**, ahol az attribútum értéke pontosan egy helyőrző. Szöveggel keverve
-  (`data-sb4-icon="ic-{{typeIcon}}"`), pipe-pal vagy listán az érték a nyelvtan általános szabálya
-  szerint üres marad, warninggal. A feloldó az objektumot egy **renderelésenként újrahúzott,
-  véletlen tokennel** adja át a hidratálásnak, hogy adatból ne lehessen másik ikon erőforrására
-  hivatkozni.
-- **Üres cím** (nincs ikonja ennek a sornak) → néma kihagyás, az elem üresen marad. A sablonban
-  **szó szerint üres** marker (`data-sb4-icon=""`) viszont `build()`-hiba, ahogy a toolbarnál.
-- **Ismeretlen szótárkulcs** → nincs ikon, egy warning. A sablonban álló **literál** kulcsot, ami
-  nincs a szótárban, már a `build()` elutasítja.
-- Egy elemen **nem állhat** a `data-sb4-icon` és a `data-sb4-icon-key` egyszerre: `build()`-hiba, a
-  kliens a kulcsot használja és warningot ír.
-- **A jelölő bármely elemen állhat** (`<span class="badge" data-sb4-icon="mail"></span>`), nem csak
-  `<smart-icon>`-on: a kliens attribútum szerint keres, és a komponenst magába a jelölő-elembe
-  rendereli. A `Tag.icon(...)` azért mégis `<smart-icon>` taget generál, mert a hostok tag-szelektorral
-  szokták stílusozni az ikont — saját elemnél erre a szelektorra ne számíts.
-- **Üres tartalommal írd**, mint a toolbar-slotot: a jelölő-elem gyerekei helyére a komponens
-  kerül. A saját `class`, `style` és `title` attribútuma megmarad, a méretezés a widget CSS-éből
-  megy (`.card-icon mat-icon { font-size: … }`). Ha szöveg és ikon is kell egy elemben — például egy
-  badge-ben —, az ikon **gyerek**-slot legyen:
-  `<span class="pill"><smart-icon data-sb4-icon="bolt"></smart-icon>count 0</span>`.
-- Az ikon a nevét a regiszterben keresi meg, ezért **egy microtaskkal később** jelenik meg — a
-  kliens ettől még ugyanabban a renderelésben írja ki a html-t.
-### Példa: típus szerinti ikon egy ImageResource-ból
-A szerveren az `ImageSettingApi` képezi le a típust ikonra (`images-*.properties`):
-```properties
-ContactType.EMAIL={"identifier":"mail","color":"accent","tooltip":{"tooltip":"E-mail cím"}}
-ContactType.PHONE={"identifier":"call","color":"primary","tooltip":{"tooltip":"Telefonszám"}}
-```
-**Soronként más erőforrás** — az objektum az adatban utazik:
-```java
-row.getData().put("typeIcon", imageSettingApi.get("ContactType", type.name()));
-```
-```html
-<div class="pg-row">
-  <smart-icon data-sb4-icon="{{typeIcon}}"></smart-icon>
-  <b>{{name}}</b>
-</div>
-```
-**Véges leképezés** — az erőforrás egyszer utazik, a sor csak a kódot viszi:
-```java
-.htmlColumn("type", h -> h
-    .icon("EMAIL", imageSettingApi.get("ContactType", "EMAIL"))
-    .icon("PHONE", imageSettingApi.get("ContactType", "PHONE"))
-    .html("""
-        <div class="pg-row">
-          <smart-icon data-sb4-icon-key="{{type}}"></smart-icon>
-          <b>{{name}}</b>
-        </div>"""))
-```
-Mindkettőből ugyanaz lesz a DOM-ban:
-```html
-<smart-icon data-sb4-icon="…"><mat-icon class="mat-accent material-icons">mail</mat-icon></smart-icon>
-```
-A szótár a **sablon** része (`HtmlProperties.icons`), nem a soré: a sima HTML widgetnél is egyszer
-megy le, és egy újra-feloldás már a leküldött erőforrások közül választ. Nem tévesztendő össze a
-`GridRow.icons`-szal, ami a **cella értéke mellé** rajzolt ikonokat írja le.
-## Akció-trigger
-```html
-<div class="card" data-sb4-action="OPEN_ENTRY">…</div>
-<li data-sb4-action="REMOVE_MEMBER" data-sb4-action-identifier="{{id}}">…</li>
-<div data-sb4-action="OPEN_MEMBER" data-sb4-action-identifier="{{id}}" data-sb4-action-direct>…</div>
-```
-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.
-- **Direkt trigger** (`data-sb4-action-direct`): akkor is lő, ha a lista nem kínálja az akciót —
-  ilyenkor a kliens maga rakja össze a `{ code, identifier }` akciót az attribútumokból. Ha a lista
-  kínál egyező akciót, az nyer (letiltás, descriptor a listából jön). Nem inert és nem warn-ol.
-  Mivel a kínált-akció lista már nem kapuzza, **a szerver handlere maga ellenőrizze a
-  jogosultságot**. Java: `Tag.directAction(code)` / `Tag.directAction(code, identifier)`.
-- 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`, `icons`, é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**: ikon-slot (`data-sb4-icon` / `data-sb4-icon-key`), a leképezés az `ImageSettingApi`-ban;
-  értékfüggő megjelenés egyébként: 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* |
+| `icons` | az **ikon-szótár**: `kulcs → ImageResource`, amit az ikon-slotok `data-sb4-icon-key`-jel címeznek — lásd *Ikon-slot* |
+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.
+A html sima szöveg, tehát a `Tag` builder helyett **text blockként** is írható — így a sablon
+ugyanúgy néz ki, ahogy a kliens megkapja:
+```java
+.html("""
+    <div class="card">
+      <smart-icon data-sb4-icon="{{typeIcon}}"></smart-icon>
+      <b>{{name}}</b>
+    </div>""")
+```
+A `html(String, Object...)` `String.format`-tal illeszti be az argumentumokat (akciókód,
+toolbar-id), ilyenkor a szövegben a `%` `%%`.
+## 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.
+Négy ú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 |
+| `h.templateKey(KEY)` + `resolveHtml(ctx, viewName, layout)` | a **felépített vagy tárolt layouton**, kulcsból (lásd *Template-kulcs egy tárolt layoutban*) | 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 négy ú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.
+### Template-kulcs egy tárolt layoutban
+Egy elmentett layout (`ObjectLayoutDescriptor`) nem a page kódjában épül, ezért nem tud
+`template(ctx, KEY)`-t hívni. Ott a widget csak **megnevezi** a kulcsot a
+`HtmlProperties.templateKey` mezőben, és a szerver tölti be, amikor a layout a view-ra kerül:
+```java
+// kódból:      f.html(h -> h.root("contact").templateKey("CONTACT_CARD"))
+// layout DSL:  html card { template: CONTACT_CARD, root: contact }
+view.putComponentLayoutsItem(Layouts.DEFAULT_LAYOUT,               // PageApiImpl
+    resolvedCopy(ctx, view.getViewName(), descriptor.getLayouts().get(Layouts.DEFAULT_LAYOUT)));
+```
+- **Tárolt layoutot a `resolvedCopy` visz a view-ra**: mély másolatot készít, és azon futtatja a
+  `resolveHtml`-t. A `resolveHtml` helyben ír, a descriptor példánya pedig lehet cache-elt — a
+  másolat nélkül a betöltött html a descriptorba kerülne. Page-en kívül:
+  `ObjectLayouts.resolvedCopy(layout, resolver, objectApi, ctx, viewName)`. Kódból épített
+  layoutra (ahol nincs mit megőrizni) elég a `resolveHtml(ctx, viewName, layout)`.
+- **Ugyanazok a szabályok, mint a `template(ctx, KEY)`-nél**: a html a legspecifikusabb névről jön
+  (`<viewName>.<KEY>` → `<KEY>` → …), a stíluslapok mind összefűződnek (fájl, aztán MDM), és
+  lecserélik a widget saját `css`-ét, ha van belőlük. A betöltött html ugyanazt az ellenőrzést
+  kapja, mint a `build()`-ben: a kliens-helyőrzők nyelvtana és az ikon-szótár kulcsai.
+- **A `viewName` kötelező a page-en.** A kulcsos layoutra hívott `resolveHtml(ctx, layout)`
+  kivételt dob: név nélkül ugyanaz a kulcs más template-et adhatna, mint a view-n épített widgeté.
+  Aki szándékosan nem akar nézetenkénti template-et, `null` nevet ad át.
+- **A kulcs nyer, és a widgetben marad.** A mellette tárolt `html`-t a betöltött felülírja, és a
+  kulcsos widget **minden futásnál újratöltődik** — rá tehát nem igaz, hogy a második futás nem
+  csinál semmit: az MDM-ben módosított template a következő futásnál megjelenik. A layout DSL
+  ezért hibát jelez, ha egy widgeten `template` és `html` is van.
+- **A field-lista: a megadott és a betöltött uniója.** A betöltött html mezői hozzáadódnak ahhoz,
+  amit a widget maga megadott (`fields`). Amíg a layout nincs feloldva, a kulcsos widgetnek csak a
+  megadott mezői vannak — ha a layout modelljét feloldás előtt kell belőle felépíteni
+  (`constructSimpleModel`, object editing), add meg őket kézzel.
+- **Hangosan bukik**, ha nincs template-modul, ha a kulcs egyik neve sem létezik, ha a betöltött
+  html-ben a ctx-szel sem oldódott fel egy `${alias:/`, vagy ha a html nem megy át az
+  ellenőrzésen.
+- **Aminek a layoutján nem futott feloldás, az üresen megy ki.** A kliens ilyenkor egy
+  konzol-figyelmeztetést ír a kulcs nevével; a `GridBuilder.rowLayout(...)` már a szerveren
+  kivételt dob a betöltetlen kulcsra.
+- **Egy helyben újra feloldott layout csak bővül.** Ha ugyanazon a példányon fut újra a feloldás,
+  és a template közben mezőt vagy stíluslapot veszített, a régi mező a listában, a régi `css` a
+  widgeten marad. A `resolvedCopy` minden alkalommal a tárolt állapotból indul, ott ez nem fordul
+  elő.
+A platform saját útjai, amelyek tárolt layoutot tesznek view-ra, mind a `resolvedCopy`-n mennek át:
+| Út | Ctx | Megjegyzés |
+|---|---|---|
+| `ObjectLayoutDescriptorUtilApi.initLayoutDescriptor(view, descriptor)` | üres | csak `${…}` nélküli template-re |
+| `…initLayoutDescriptor(view, descriptor, ctx)` | a hívóé | a `DataSheetPageApiImpl` ezt hívja, a view modelljével `dataSheet` néven: `${dataSheet:/#name}` |
+| MDM bejegyzés-szerkesztő (`MDMEntryListPageApiImpl`) | üres | az `MDM_VIEW.<név>` descriptor layoutja |
+| Object navigation (`NavigationNodeLayoutInternalApi`) | a node adata `node` néven | a view nevével |
+Az `ObjectLayoutApi.getObjectDisplay` **nem** old fel: aki annak a layoutját, vagy közvetlenül a
+`descriptor.getLayouts()`-ét teszi a view-ba, a `resolvedCopy`-t maga hívja.
+## 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`. Egyetlen kivétel: egy **ikon-slot**
+  név-attribútumának teljes értékeként az objektum az ikon `ImageResource`-a lesz — lásd
+  *Ikon-slot*.
+- 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` /
+`data-sb4-icon` / `data-sb4-icon-key`, `data-sb4-icon` és `data-sb4-icon-key` ugyanazon az elemen |
+| Java-builder (`build()`) | `IllegalStateException`: a sablonban álló literál ikon-kulcs, amit az ikon-szótár nem tartalmaz |
+| 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.
+## Ikon-slot
+```html
+<smart-icon data-sb4-icon="mail" data-sb4-icon-color="warn"></smart-icon>
+<smart-icon data-sb4-icon="{{typeIcon}}"></smart-icon>
+<smart-icon data-sb4-icon-key="{{type}}"></smart-icon>
+```
+A kliens a marker-elembe egy **valódi `smart-icon`-t hidratál**, ugyanazt a komponenst, amit a
+gomb, a grid-cella és a form használ. Java: `Tag.icon(name)`, `Tag.icon(name, color)`,
+`Tag.icon(imageResource)`, `Tag.iconKey(key)`, a szótár a widget-builderen: `h.icon(key, resource)`
+/ `h.icons(map)`.
+Az ikon címe négyféle lehet, és mindegyiknek megvan a maga esete:
+| Forma | Mit ad az ikonnak | Mikor |
+|---|---|---|
+| `data-sb4-icon="mail"` | `icon` input: a név előbb a regisztrált svg-névterekben, aztán Material-ligatúraként | fix ikon, vagy adatból jövő **ikonnév** |
+| `data-sb4-icon="{{typeIcon}}"`, az érték **objektum** | `imageResource` input | soronként más erőforrás (feltöltött kép, `ImageSettingApi` a modellben) |
+| `data-sb4-icon="{…}"` (JSON) | `imageResource` input | a page által **egyszer** feloldott erőforrás (`Tag.icon(resource)`) |
+| `data-sb4-icon-key="{{type}}"` | `imageResource` input a **szótárból** | véges típus → ikon leképezés |
+- **`data-sb4-icon-color`**: a `color` input, vagyis téma- vagy host-osztálynév (`primary`,
+  `text-primary`, `warn` …), **nem** CSS-szín. Csak a név-formához való: az `ImageResource` a saját
+  `color`-ját hozza. Elhagyva a komponens alapértelmezése (`primary`) marad.
+- **Objektum csak ott**, ahol az attribútum értéke pontosan egy helyőrző. Szöveggel keverve
+  (`data-sb4-icon="ic-{{typeIcon}}"`), pipe-pal vagy listán az érték a nyelvtan általános szabálya
+  szerint üres marad, warninggal. A feloldó az objektumot egy **renderelésenként újrahúzott,
+  véletlen tokennel** adja át a hidratálásnak, hogy adatból ne lehessen másik ikon erőforrására
+  hivatkozni.
+- **Üres cím** (nincs ikonja ennek a sornak) → néma kihagyás, az elem üresen marad. A sablonban
+  **szó szerint üres** marker (`data-sb4-icon=""`) viszont `build()`-hiba, ahogy a toolbarnál.
+- **Ismeretlen szótárkulcs** → nincs ikon, egy warning. A sablonban álló **literál** kulcsot, ami
+  nincs a szótárban, már a `build()` elutasítja.
+- Egy elemen **nem állhat** a `data-sb4-icon` és a `data-sb4-icon-key` egyszerre: `build()`-hiba, a
+  kliens a kulcsot használja és warningot ír.
+- **A jelölő bármely elemen állhat** (`<span class="badge" data-sb4-icon="mail"></span>`), nem csak
+  `<smart-icon>`-on: a kliens attribútum szerint keres, és a komponenst magába a jelölő-elembe
+  rendereli. A `Tag.icon(...)` azért mégis `<smart-icon>` taget generál, mert a hostok tag-szelektorral
+  szokták stílusozni az ikont — saját elemnél erre a szelektorra ne számíts.
+- **Üres tartalommal írd**, mint a toolbar-slotot: a jelölő-elem gyerekei helyére a komponens
+  kerül. A saját `class`, `style` és `title` attribútuma megmarad, a méretezés a widget CSS-éből
+  megy (`.card-icon mat-icon { font-size: … }`). Ha szöveg és ikon is kell egy elemben — például egy
+  badge-ben —, az ikon **gyerek**-slot legyen:
+  `<span class="pill"><smart-icon data-sb4-icon="bolt"></smart-icon>count 0</span>`.
+- Az ikon a nevét a regiszterben keresi meg, ezért **egy microtaskkal később** jelenik meg — a
+  kliens ettől még ugyanabban a renderelésben írja ki a html-t.
+### Példa: típus szerinti ikon egy ImageResource-ból
+A szerveren az `ImageSettingApi` képezi le a típust ikonra (`images-*.properties`):
+```properties
+ContactType.EMAIL={"identifier":"mail","color":"accent","tooltip":{"tooltip":"E-mail cím"}}
+ContactType.PHONE={"identifier":"call","color":"primary","tooltip":{"tooltip":"Telefonszám"}}
+```
+**Soronként más erőforrás** — az objektum az adatban utazik:
+```java
+row.getData().put("typeIcon", imageSettingApi.get("ContactType", type.name()));
+```
+```html
+<div class="pg-row">
+  <smart-icon data-sb4-icon="{{typeIcon}}"></smart-icon>
+  <b>{{name}}</b>
+</div>
+```
+**Véges leképezés** — az erőforrás egyszer utazik, a sor csak a kódot viszi:
+```java
+.htmlColumn("type", h -> h
+    .icon("EMAIL", imageSettingApi.get("ContactType", "EMAIL"))
+    .icon("PHONE", imageSettingApi.get("ContactType", "PHONE"))
+    .html("""
+        <div class="pg-row">
+          <smart-icon data-sb4-icon-key="{{type}}"></smart-icon>
+          <b>{{name}}</b>
+        </div>"""))
+```
+Mindkettőből ugyanaz lesz a DOM-ban:
+```html
+<smart-icon data-sb4-icon="…"><mat-icon class="mat-accent material-icons">mail</mat-icon></smart-icon>
+```
+A szótár a **sablon** része (`HtmlProperties.icons`), nem a soré: a sima HTML widgetnél is egyszer
+megy le, és egy újra-feloldás már a leküldött erőforrások közül választ. Nem tévesztendő össze a
+`GridRow.icons`-szal, ami a **cella értéke mellé** rajzolt ikonokat írja le.
+## Akció-trigger
+```html
+<div class="card" data-sb4-action="OPEN_ENTRY">…</div>
+<li data-sb4-action="REMOVE_MEMBER" data-sb4-action-identifier="{{id}}">…</li>
+<div data-sb4-action="OPEN_MEMBER" data-sb4-action-identifier="{{id}}" data-sb4-action-direct>…</div>
+```
+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.
+- **Direkt trigger** (`data-sb4-action-direct`): akkor is lő, ha a lista nem kínálja az akciót —
+  ilyenkor a kliens maga rakja össze a `{ code, identifier }` akciót az attribútumokból. Ha a lista
+  kínál egyező akciót, az nyer (letiltás, descriptor a listából jön). Nem inert és nem warn-ol.
+  Mivel a kínált-akció lista már nem kapuzza, **a szerver handlere maga ellenőrizze a
+  jogosultságot**. Java: `Tag.directAction(code)` / `Tag.directAction(code, identifier)`.
+- 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`, `icons`, é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.
+- **Kulcsból**: `gridBuilder.htmlColumn("name", h -> h.template(objectApi.contextObject(), KEY))`
+  — a page `gridBuilder(...)`-e átadja a template-feloldót, a sablon és a stíluslapja a kulcsról
+  jön, mint a widgetnél. Soronkénti szerver-kontextus itt sincs, a sablonban `{{…}}` legyen. A
+  halasztott `templateKey(KEY)` oszlopon nem megy (nincs layout, amin a `resolveHtml` futna), a
+  builder kivételt dob rá. Sor-layoutnál mindkettő működik: `template(ctx, KEY)` építéskor, vagy
+  `templateKey(KEY)` és `resolveHtml(ctx, viewName, rowLayout)` a `rowLayout(...)` hívás előtt.
+## 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**: ikon-slot (`data-sb4-icon` / `data-sb4-icon-key`), a leképezés az `ImageSettingApi`-ban;
+  értékfüggő megjelenés egyébként: 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.