JS: gobj-ui API

gobj-ui API¶

@yuneta/gobj-ui is the UI library. It gives a declarative shell that draws the frame of an application from one JSON file, a set of component gclasses, and the helpers that go with them.

It sits on top of @yuneta/gobj-js, and it holds the same rules: a DOM callback translates a notification of the browser into an event, and the work happens in an action of a state machine.

Source code: github.com/artgins/gobj-ui.js — version: 7.27.0

Install¶

npm install @yuneta/gobj-ui

An application imports by the name of the package. The exports map of the package gives both the barrel and the modules of the source:

import { register_c_yui_shell } from "@yuneta/gobj-ui";
import { yui_shell_show_modal } from "@yuneta/gobj-ui/src/shell_modals.js";

The two lines¶

The repository carries two lines, and each one has its own consumers.

This reference covers the v2 line.

The pages¶

Two chapters describe the design, and they are not a reference of the API: The declarative shell and Routing.

Every symbol of the package is in the JS API index, and the index carries the symbols that a deep import reaches too.

The rules of a GUI gclass¶

These rules apply to every gclass that draws.

Every action goes through the state machine. A click is an action. The DOM handler sends an event, and the work happens in the action. A view whose whole life happens in one state gives a machine trace that shows nothing.

A kw is plain JSON. Never put a gobj, a widget or a DOM node in it. Pass an identity, and find the object inside the action.

Data is text, and markup is said out loud. A value from a backend, or a value that a user typed, goes into the DOM as text: a Text node in the third slot of a description, or a string in a list of children. Markup that you mean (an icon, an svg) goes in html_markup(). gobj-ui passes all its markup that way since 7.26.10. So an app can start with set_strings_are_text(true), and then a plain string is never markup. Run the check of gobj-ui on the app in its prebuild; it finds a literal markup or markup that is built with values:

['span', {class: 'icon'}, html_markup('<i class="yi-copy"></i>')]  // markup
['span', {class: 'HOST'}, document.createTextNode(host)]          // data

# gobj-ui publishes the check (7.26.11+); its acorn is a dependency of gobj-ui
# since 7.26.29, so the app declares nothing for it
node node_modules/@yuneta/gobj-ui/scripts/check-markup-strings.mjs src

Give a logical name to each block of the DOM. The root of a view carries the name of its gclass and a name of its own, such as class="C_AGENT_CONSOLE CONSOLE_CARD view-card". Each meaningful child carries a logical name with the prefix of the view. A logical name is UPPER_SNAKE, and a name of style is lower case, so the case alone separates the two.

Every text goes through i18n, and it must change language. A text that goes through the translator one time does not change language again. See refresh_language().

No transitions and no animations. A menu, a popover and a change of state appear at once.

Four spaces of indentation, everywhere that a structure appears as an indentation, and a rendered tree indents in ch and not in rem.