From a block to the screen¶
The path of a view¶
view [
title "Cog & Chain"
count: text muted "No bikes in yet."
button "Book in" [count/text: "One bike in." count/role: 'success]
]
Three things happen between that block and what you see.
layoutreads the block. It is Trebol code, insrc/ui/ui.trb, written withparse. Each word of style (title,text,button) starts a face, and the words, strings and blocks after it are read as its modifiers. Styles give each face its starting fields. The result is a tree of faces: objects with fields such asstyle,text,role,dataandpane(the children), as in Red.layoutis pure: it touches no DOM, so it runs the same in Node, in the tests.showdraws the tree. It is a native of the browser host (browser.ts) that makes one DOM node per face, with semantic elements: abuttonis a<button>, a field is an<input>with its<label for>, a table is a<table>. The classes on them are a fixed set; the look comes from the theme (see Themes: a few numbers, every color).Changes repaint by themselves.
count/text: "One bike in."sets a field of a face that is on screen. The host has given that face’s context awatchlist, and the core’sctxSetadds the context to it the first time a field changes. After each round of the scheduler, the host copies the fields of the faces in that list to their nodes, and clears it. Repainting costs what changed, not the number of faces.
Changing a series in place, append count/text "!", changes the string but not the field, so it does not
repaint: set the field again.
Events¶
A click, a key, a change in a field: the host turns each DOM event into a call of a Trebol function
(ui-click, ui-input, ui-blur…) in a new task. Those functions, in ui.trb, find the handler, bind
face, value, event and, in a form, values, and run it. Validation runs there too, in Trebol: the
rules on a field, the messages in the active language, the submit that stays disabled while a field has an
error.
So the host knows how to draw and how to listen, and the dialect knows what things mean. The line between them is the face: fields the dialect writes and the host reads.
Tables and lists¶
A table’s data is a block of rows. When it is set again, the host compares the new rows with the old ones
by key (the id field, or key another field, or the position) and only makes, moves or removes the rows
that changed. On a narrow screen the same table is drawn as a list of cards.
Accessibility is the default¶
Because the host draws every control, it can give each one what assistive technology needs, every time:
labels tied to fields, aria-invalid and the error message in aria-describedby, a disabled submit that
stays in the keyboard order and shows the errors when pressed, toasts in an aria-live region, icon buttons
named by their icon. An app gets all of it without asking.
Why this way — and the alternatives¶
A virtual DOM, as React does: build a new description of the whole screen after every change and compare it with the last. It frees the program from saying what changed. Trebol knows what changed, because every change is a field set on a face, so it has nothing to compare; one node per face is enough.
Signals or observables, as Solid or Vue do: every value is wrapped, and reading it records who depends on it. It is precise, but every value in the program would need wrapping. In Trebol only a face’s own fields are watched, and the program uses plain values everywhere else.
Templates of HTML, as most web frameworks do. They give full control and need you to know HTML, CSS and their accessibility rules. Trebol’s promise is the opposite: you say what, and the host knows how. A style you cannot express is a style to add to Trebol, for everyone.
Canvas drawing, as some UI toolkits do in a browser: draw every pixel yourself. It looks the same everywhere, and loses text selection, the browser’s accessibility, translation and zoom. Real DOM elements keep all of that.