@smartbit4all/ng-client 7.1.2 → 7.2.0

package/HTML-WIDGET.md

@@ -0,0 +1,458 @@
+# 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 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` |
+| 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`) ne építs, a motor átírja.
+
+## 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):
+
+- **klikk = kijelölés**, ha a grid `selectionMode`-ja nem `NONE` és a sor `selectable`; a kijelölt
+  kártya hostja `selected` osztályt és egy minimális, felülírható outline-t kap;
+- **dupla klikk = a sor default akciója** (`defaultRowActions`);
+- a toolbar-gomb és a trigger megtartja magának a kattintást.
+
+Ha a kártyának „klikk = megnyitás" kell, tegyél a html gyökérelemére triggert.
+
+## 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.