Aspectul iframe-ului: culori, fonturi, navigare

Cum îl trimiți

Aspectul este un obiect JSON. Îl dai iframe-ului în init, ca theme, ca să pornească direct așa, și îl schimbi oricând cu setTheme. Fiecare setTheme înlocuiește aspectul întreg: trimiți mereu tot obiectul, nu doar ce s-a schimbat.

→ { "chappa": "facturare/1", "kind": "request", "id": "7", "type": "setTheme",
    "payload": { "mode": "dark", "radius": 10, "colors": { "light": { "accent": "#1f6f50" } } } }
← { "chappa": "facturare/1", "kind": "response", "id": "7",
    "payload": { "ok": true, "result": { "theme": { … }, "ignored": [] } } }

Răspunsul spune ce s-a aplicat (theme, fără valorile implicite) și ce a rămas deoparte (ignored, fiecare cu cheia și motivul): o culoare care nu e hex, un număr în afara intervalului, o cheie necunoscută. Restul se aplică oricum.

Iframe-ul trece la aspectul nou fără să se reîncarce: îl estompează pe cel vechi, iar la trecerea dintre zi și noapte noul aspect coboară de sus (noaptea) sau urcă de jos (ziua). Schimbările care vin una după alta, ca de la un cursor tras, se aplică pe loc.

Cine îl poate schimba

Modul (mode: zi, noapte sau după sistem) îl alege oricine, inclusiv cu conturi Chappa și, fără JavaScript, cu ?theme= în adresă.
Restul (culori, forme, navigare, logo) se aplică în nivelul extins și în modul test, ca să-l poți construi înainte de înregistrare. În celelalte niveluri iframe-ul păstrează modul și trece restul în ignored.

Culorile

Două palete, colors.light și colors.dark, cu valori hex (#rrggbb sau #rgb). Nu e nevoie să le dai pe toate:

dintr-o culoare de bază calculăm nuanțele ei: din accent, culoarea la hover, fundalul și textul de pe butoane; din surface și text, textul secundar și discret;
accentul și culorile de stare date doar pentru zi primesc și o variantă de noapte, cu aceeași nuanță, destul de luminoasă pe fundal închis.

Ce dai explicit nu se mai calculează. Editorul de mai sus arată, pentru fiecare culoare, dacă e setată, calculată sau implicită, și contrastul perechilor care contează.

Cheia	Ce colorează	Zi	Noapte
`canvas`	fundalul paginii și bara de sus	`#eceeea`	`#0f1211`
`canvasAlt`	zonele de fundal secundare	`#e3e6e1`	`#151917`
`surface`	panouri, tabele, documente, câmpuri	`#ffffff`	`#1a1f1c`
`surfaceAlt`	rândurile la hover, câmpurile needitabile	`#f5f6f4`	`#212723`
`border`	liniile dintre rânduri, marginile panourilor	`#d8dcd5`	`#2e3531`
`borderStrong`	marginile câmpurilor și ale butoanelor	`#c2c8c0`	`#414a45`
`text`	textul principal	`#141716`	`#e8ebe8`
`textMuted`	etichete, text secundar	`#48504b`	`#b0b8b3`
`textSubtle`	note, date, text discret	`#616964`	`#8e9792`
`accent`	butoanele principale, linkurile, focusul, ștampila	`#2340a0`	`#94abff`
`accentHover`	butonul principal la hover	`#1a3283`	`#b3c3ff`
`accentSoft`	selecțiile, mesajele de informare	`#e6ebf8`	`#1d2747`
`onAccent`	textul de pe butoanele principale	`#ffffff`	`#0c1330`
`success`, `successSoft`	validată, încasată	`#1d6b44`	`#74d39c`
`warning`, `warningSoft`	atenționări, modul test	`#855000`	`#eab14f`
`danger`, `dangerSoft`	erori, respinsă, restantă	`#b3261e`	`#ff8d82`

Forma, textul, spațiul

Cheia	Valori	Implicit
`mode`	`auto` (după sistemul utilizatorului), `light`, `dark`	`auto`
`font`	`chappa`, `system`, `humanist`, `geometric`, `rounded`, `industrial`, `serif`; în afară de `chappa`, fonturi din sistemul utilizatorului, nimic descărcat	`chappa`
`fontScale`	între 0,875 și 1,125; mărește sau micșorează tot, proporțional	`1`
`radius`	pixeli, între 0 și 20: colțurile panourilor; cele mici sunt jumătate, ale ferestrelor de dialog 1,6 ori	`6`
`controlRadius`	pixeli, între 0 și 24, sau `"pill"`: butoanele, câmpurile, filele	ca `radius`
`density`	`compact`, `normal`, `comfortable`: spațiul din tabele, panouri și navigare	`normal`
`shadows`	`none` (doar linii), `soft`, `normal`	`normal`

Navigarea și elementele

Sub layout:

Cheia	Valori	Implicit
`nav`	`tabs` (file sub bara de sus), `side` (panou lateral; sub 720 px lățime devine file), `none` (fără navigare: pagina ta schimbă ecranele cu `navigate`)	`tabs`
`sections`	secțiunile arătate, în ordinea din listă: `dashboard`, `invoices`, `recurring`, `received`, `payments`, `clients`, `products`, `settings`	toate, în această ordine
`start`	secțiunea deschisă la pornire, când `init` nu cere alt ecran	`dashboard`
`companySwitcher`	`true` sau `false`: alegerea firmei	`true`
`newInvoiceButton`	`true` sau `false`: butonul „Factură nouă”	`true`
`logo`	vezi mai jos	niciunul

O secțiune scoasă din navigare rămâne accesibilă cu navigate; drepturile utilizatorului nu se schimbă. Fără alegerea firmei, pagina ta schimbă firma cu selectEntity.

Logo-ul

Logo-ul aplicației tale apare în bara de sus sau în capul panoului lateral. Îl dai ca adresă, de pe serverul tău:

"layout": { "logo": { "src": "https://aplicatia-ta.ro/logo.svg",
                      "srcDark": "https://aplicatia-ta.ro/logo-alb.svg",
                      "alt": "Aplicația ta", "height": 28 } }

Doar adrese https. srcDark e opțional și se arată când iframe-ul e pe noapte; height e în pixeli, între 16 și 56. Imaginea se cere fără Referer.

Un exemplu întreg

{
  "mode": "auto",
  "font": "humanist",
  "radius": 10,
  "controlRadius": "pill",
  "density": "comfortable",
  "colors": {
    "light": { "canvas": "#e9efeb", "surface": "#ffffff", "border": "#d0dcd4",
               "text": "#14201a", "accent": "#1f6f50" }
  },
  "layout": {
    "nav": "side",
    "sections": ["invoices", "clients", "products", "payments", "settings"],
    "start": "invoices",
    "logo": { "src": "https://aplicatia-ta.ro/logo.svg", "alt": "Aplicația ta" }
  }
}

Varianta de noapte a accentului se calculează; fundalurile de noapte rămân cele implicite, pentru că nu au fost date.