gobj-ui: DOM helpers

DOM helpers¶

Source code: src/lib_graph.js, src/lib_icons.js, src/yui_inputs.js, src/yui_toolbar.js

Classes of a set of elements¶

Each function takes a container and a selector, and it works on every element that matches inside the container.

`addClasses($container, selector, ...classNames)`¶

Adds the classes.

`removeClasses($container, selector, ...classNames)`¶

Removes the classes.

`toggleClasses($container, selector, ...classNames)`¶

Adds the classes that are absent, and removes the classes that are present.

`removeChildElements($element)`¶

Removes every child of an element.

`disableElements($container, selector)`¶

Disables the elements that match. Since 7.26.28, a disabled control tells this to the keyboard and to a screen reader too, not only to the pointer. On each element, the function writes three attributes:

disabled: the stylesheets and the click guards read it. On a div that is drawn as a button, the browser itself does not read it.
aria-disabled="true": a screen reader announces it. Without it, a reader announced a disabled toolbar item as a button that works.
tabindex="-1": the Tab key does not stop on the control.

The function keeps the tabindex that the element had in data-enabled-tabindex. The value is empty when the element had no tabindex. A second call does not change the kept value, so the first tabindex is not lost. An element that has the focus keeps it: tabindex="-1" only removes the element from the Tab order.

`enableElements($container, selector)`¶

Enables the elements that match. It removes disabled and aria-disabled, and it gives back the tabindex that data-enabled-tabindex keeps. When the kept value is empty, it removes tabindex. Then it removes data-enabled-tabindex. An element without data-enabled-tabindex keeps its tabindex.

// <button class="SAVE">                         (no tabindex)
disableElements($toolbar, ".SAVE");
// <button class="SAVE" disabled aria-disabled="true"
//         data-enabled-tabindex="" tabindex="-1">
enableElements($toolbar, ".SAVE");
// <button class="SAVE">                         (no tabindex again)

Important

If you BUILD a control that is disabled, write the four attributes yourself. Put in data-enabled-tabindex the tabindex that the control takes when it is enabled. If you do not, enableElements() has no tabindex to give back, and the enabled control stays out of the Tab order (tabindex="-1"). The toolbar of C_G6_NODES_TREE builds a disabled item like this:

'<div class="g6-toolbar-item EV_SAVE_GRAPH" role="button"' +
' tabindex="-1" aria-disabled="true" data-enabled-tabindex="0" disabled>…</div>'

A div gets no protection from disabled. Block the pointer in the stylesheet, and test the attribute before a key press clicks the item:

.g6-toolbar-item[disabled] {
    pointer-events: none;
}

if(item.hasAttribute("disabled")) {
    return;
}
item.click();

States of an action¶

The functions below write the state of a set of elements. The first three write a color; the fourth writes the look of a control that is pressed.

`set_submit_state($container, selector, set)`¶

Writes the state of “there are changes to save”, in orange.

`set_cancel_state($container, selector, set)`¶

Writes the state of “the cancel is possible”, in red.

`set_active_state($container, selector, set)`¶

Writes the state of “active”, in violet. The library uses it for the buttons of the history, undo and redo.

`set_pressed_state($container, selector, set)`¶

Writes the state of “this toggle is on”. It does not use a color: it gives the control the look of a button that is pressed, an inverted neutral. A color of the group above tells which KIND of action a control does, and a toggle that is on is not an action — it is a state. Two controls of the same toolbar with the same color, for two different reasons, are more difficult to read than one control that looks pressed.

Color¶

`getStrokeColor(fillColor, theme, factor)`¶

Gives a color of line for a color of fill, in the form rgba(). It makes the color lighter or darker by factor, which is 0.2 by default, and the direction depends on the theme. It accepts the hexadecimal form and the rgb() form.

Icons¶

`inject_svg_icons()`¶

Puts the set of SVG symbols in the document. A second call does nothing, because a guard on the identifier of the element stops it.

Warning

yui_icons.css is a small set of CSS masks, and it is not FontAwesome. A class yi-* that the set does not hold draws a black square. Read the set before you use an icon:

grep -oE '^\.yi-[a-z0-9-]+::before' src/yui_icons.css

Add a missing icon as a rule of mask. Never name one on hope.

`yui_icon_is_defined(name)`¶

Tells if name is a class that draws an icon in the loaded stylesheets. It asks the real stylesheet, so an icon that an app adds is seen too. The answer is kept for each name; a change of the user icons clears the answers about yi-u- names.

if(!yui_icon_is_defined("yi-bolt")) {
    show_the_name_instead();
}

User icons¶

A user adds icons as data. Each treedb has the system topic __icons__: one node for each icon, with the name in id and the drawing in svg. A column with the flag icon names such an icon as yi-u-<id>. The prefix yi-u- is not used by the icons of the library, so a user icon cannot replace one of them. C_YUI_TREEDB_TOPICS loads __icons__ and keeps the registry current. An app that does not mount that view calls the functions below itself.

`ICONS_TOPIC`¶

The name of the system topic: "__icons__".

`USER_ICON_PREFIX`¶

The prefix of the class of a user icon: "yi-u-".

`yui_user_icon_class(id)`¶

Gives the class of the user icon id.

yui_user_icon_class("transformer");     // "yi-u-transformer"

`yui_svg_sanitize(svg_text)`¶

Parses an svg and writes a new one from its shapes only (path, circle, rect, ellipse, line, polyline, polygon, g) and their geometric and stroke attributes. It gives {svg, dropped}, where dropped names what it removed, or {error}. The error is one of "empty svg", "svg too big", "not an svg document", "svg without size", "svg without shapes".

yui_svg_sanitize("<svg viewBox='0 0 10 10' onload='x()'><circle cx='5' cy='5' r='5'/></svg>");
// {svg: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 10 10"><circle cx="5" cy="5" r="5"></circle></svg>',
//  dropped: ["@onload"]}

`yui_svg_icon_element(svg_text)`¶

Gives {element}, a span that shows the svg as an icon (the same box and the same mask as a yi- icon), or {error}. Use it for a preview, before the icon is registered.

let r = yui_svg_icon_element(textarea.value);
if(r.error) {
    note.textContent = r.error;
} else {
    box.replaceChildren(r.element);
}

`yui_icons_set_user(nodes)`¶

Replaces all the user icons with the nodes of __icons__, and gives the number of icons registered. A node with a bad name or an svg that cannot be drawn is not registered, and a warning is logged. Tell the views after it:

yui_icons_set_user(nodes);          // the answer of `nodes` of __icons__
yui_shell_icons_changed(shell);     // publishes EV_ICONS_CHANGED

`yui_icons_put_user(node)`¶

Registers one node that was created or updated, and gives true if the icon is drawn. If the new svg cannot be drawn, the old icon is removed.

yui_icons_put_user({id: "transformer", svg: "<svg viewBox='0 0 24 24'><path d='M4 4h16v16H4z'/></svg>"});

`yui_icons_remove_user(id)`¶

Removes the user icon id, after its node was deleted.

yui_icons_remove_user("transformer");

`yui_icons_list()`¶

Gives every icon that can be chosen, as [{name, user}]: the icons of the library, read from the loaded stylesheets, then the user icons. Each part is sorted by name. The form uses it for the picker of an icon column.

yui_icons_list().filter(icon => icon.user).map(icon => icon.name);
// ["yi-u-transformer"]

Inputs¶

`attach_clear($control, $input, on_clear)`¶

Adds a button of clear to a control that holds an input, and gives the button back. The button appears only when the input holds a value and accepts a write.

`refresh_clear($input)`¶

Looks at the button of clear again, after a change that the code made: a value that a form loaded, or a change of the read-only state. Neither of those sends an event of input, so nothing else looks. It does nothing on an input that has no button of clear.

Builds a toolbar that scrolls, with an arrow at each end when the items do not fit. The arrows take the icons of the set of the library, and they take their color from currentColor, so the two themes work.