@yuneta/gobj-ui 5.3.3 → 5.5.0

package/src/c_yui_service_view.js

@@ -0,0 +1,362 @@
+/***********************************************************************
+ *          c_yui_service_view.js
+ *
+ *      Mounting a view that TALKS TO A BACKEND.
+ *
+ *      THE PROBLEM
+ *      -----------
+ *      A view that asks the backend for data does it with
+ *          gobj_command(remote, "...", kw, src = itself)
+ *      and C_IEVENT_CLI routes the answer back with
+ *          gobj_find_service(gobj_name(src))
+ *      which only finds REGISTERED SERVICES.
+ *
+ *      Neither host creates one: C_YUI_SHELL mounts a route's view with
+ *      `gobj_create()` and C_YUI_NODE with `gobj_create_pure_child()`.
+ *      So a backend-talking view mounted directly never receives a single
+ *      answer — and not quietly: the ievent logs "service not found" once
+ *      per answer while the view sits empty forever.
+ *
+ *      There is a second half.  A route's `target.kw` is STATIC JSON, so
+ *      it cannot carry the live transport pointer the view needs.  It has
+ *      to be resolved at mount time and injected.
+ *
+ *      THE PIECE
+ *      ---------
+ *      Both halves had been written four separate times, in three repos,
+ *      each wrapper saying the same thing in its own header.  They are
+ *      here now, in two shapes, because the four callers are not alike:
+ *
+ *        yui_mount_service_view(host, spec) — the helper.  For a wrapper
+ *          that has its OWN extras on top (bridging url segments to the
+ *          hosted view, rebinding it when a connection drops).  Those
+ *          extras are app or route logic and do NOT belong here; the
+ *          wrapper keeps them and drops only the boilerplate.
+ *
+ *        C_YUI_SERVICE_VIEW — the gclass, for a route with NO extras:
+ *          declare it in the route/node and name the view it hosts.  It
+ *          is the helper plus a lifecycle, nothing more.
+ *
+ *      CONTRACT of the hosted gclass:
+ *        - declares the attr the transport is injected under
+ *          (`gobj_remote_yuno` by default),
+ *        - builds its `$container` in mt_create (re-exposed as the
+ *          host's, which is what the shell/node mounts),
+ *        - flags EVF_PUBLIC_EVENT on what arrives from the backend
+ *          (EV_MT_COMMAND_ANSWER and anything the remote publishes): the
+ *          ievent drops events that are not public.
+ *
+ *      NAMES: the service name must be UNIQUE per mount.  A duplicate is
+ *      not fatal and that is the danger — gobj-js logs "service ALREADY
+ *      REGISTERED. Will be UPDATED" and REBINDS the name, so the answers
+ *      of one view would land in the other.  Derive it from the route (or
+ *      from whatever else makes the mount unique: a connection id, a
+ *      workspace) and never from the gclass alone.
+ *
+ *          Copyright (c) 2026, ArtGins.
+ *          All Rights Reserved.
+ ***********************************************************************/
+import {
+    SDATA,
+    SDATA_END,
+    data_type_t,
+    gclass_create,
+    gclass_find_by_name,
+    log_error,
+    gobj_parent,
+    gobj_read_attr,
+    gobj_read_str_attr,
+    gobj_read_pointer_attr,
+    gobj_write_attr,
+    gobj_subscribe_event,
+    gobj_find_service,
+    gobj_create_service,
+    gobj_start,
+    gobj_stop,
+    gobj_is_running,
+    gobj_short_name,
+    is_gobj,
+    is_string,
+    empty_string,
+    createElement2,
+} from "@yuneta/gobj-js";
+
+
+/***************************************************************
+ *              Constants
+ ***************************************************************/
+const GCLASS_NAME = "C_YUI_SERVICE_VIEW";
+
+/*  What the four wrappers all did: the app's single transport, injected
+ *  under the attr every backend-talking gclass in this library declares. */
+const DEFAULT_TRANSPORT_SERVICE = "__remote_service__";
+const DEFAULT_TRANSPORT_ATTR    = "gobj_remote_yuno";
+
+
+/***************************************************************
+ *              Data
+ ***************************************************************/
+const attrs_table = [
+SDATA(data_type_t.DTP_POINTER,  "subscriber",   0,  null,   "Subscriber of output events"),
+
+SDATA(data_type_t.DTP_STRING,   "view_gclass",  0,  "",     "GClass of the hosted view (must be registered)"),
+SDATA(data_type_t.DTP_STRING,   "service_name", 0,  "",     "Service name of the hosted view — UNIQUE per mount"),
+SDATA(data_type_t.DTP_JSON,     "view_kw",      0,  null,   "kw passed to the hosted view"),
+SDATA(data_type_t.DTP_STRING,   "transport_service", 0, DEFAULT_TRANSPORT_SERVICE, "Service name of the live transport"),
+SDATA(data_type_t.DTP_STRING,   "transport_attr",    0, DEFAULT_TRANSPORT_ATTR,    "Attr of the hosted view the transport is injected under"),
+SDATA(data_type_t.DTP_POINTER,  "$container",   0,  null,   "Root HTMLElement"),
+SDATA_END()
+];
+
+let PRIVATE_DATA = {
+    view: null,
+};
+
+let __gclass__ = null;
+
+
+
+
+                    /***************************
+                     *      Public helper
+                     ***************************/
+
+
+
+
+/************************************************************
+ *  Create `spec.gclass` as a NAMED SERVICE under `host`, with the
+ *  live transport injected, and return it (null on failure, error
+ *  already logged).  The caller owns what happens next — starting
+ *  it, exposing its DOM, bridging routes into it.
+ *
+ *  spec = {
+ *      gclass,           // string, required — must be registered
+ *      name,             // string, required — service name, unique per mount
+ *      kw,               // object, optional — the view's kw
+ *      transport,        // gobj | service name | omitted:
+ *                        //   a gobj is used as-is (the caller already
+ *                        //   resolved it — e.g. per connection), a string
+ *                        //   is looked up with gobj_find_service(), and
+ *                        //   omitted means "__remote_service__".
+ *                        //   null DISABLES injection: for a hosted view
+ *                        //   that takes its transport some other way.
+ *      transport_attr    // string, optional — default "gobj_remote_yuno"
+ *  }
+ ************************************************************/
+function yui_mount_service_view(host, spec)
+{
+    if(!host || !is_gobj(host) || !spec) {
+        log_error(`${GCLASS_NAME}: yui_mount_service_view without host or spec`);
+        return null;
+    }
+
+    const gclass = spec.gclass;
+    const name   = spec.name;
+
+    if(empty_string(gclass) || empty_string(name)) {
+        log_error(
+            `${gobj_short_name(host)}: mounting a service view needs gclass and name`
+        );
+        return null;
+    }
+    if(!gclass_find_by_name(gclass)) {
+        log_error(`${gobj_short_name(host)}: gclass '${gclass}' is not registered`);
+        return null;
+    }
+
+    let kw = Object.assign({}, spec.kw || {});
+
+    /*  `undefined` means "the app's single transport"; an explicit null
+     *  means "do not inject one".  They are NOT the same, hence the
+     *  hasOwnProperty test instead of a truthiness check. */
+    let transport = Object.prototype.hasOwnProperty.call(spec, "transport")
+        ? spec.transport
+        : DEFAULT_TRANSPORT_SERVICE;
+
+    if(transport !== null) {
+        if(is_string(transport)) {
+            const service_name = transport;
+            transport = gobj_find_service(service_name);
+            if(!transport) {
+                log_error(
+                    `${gobj_short_name(host)}: transport service ` +
+                    `'${service_name}' not found`
+                );
+                return null;
+            }
+        }
+        if(!is_gobj(transport)) {
+            log_error(`${gobj_short_name(host)}: transport is not a gobj`);
+            return null;
+        }
+        kw[spec.transport_attr || DEFAULT_TRANSPORT_ATTR] = transport;
+    }
+
+    const view = gobj_create_service(name, gclass, kw, host);
+    if(!view) {
+        log_error(`${gobj_short_name(host)}: cannot create '${gclass}' as '${name}'`);
+        return null;
+    }
+    return view;
+}
+
+/************************************************************
+ *  The hosted view's $container, re-exposed as the host's — the
+ *  shell/node mounts the HOST, so without this nothing is drawn.
+ *  Never returns without setting one: an empty div beats a blank
+ *  screen with the reason only in the console.
+ ************************************************************/
+function expose_view_container(host, view)
+{
+    let $c = view ? gobj_read_attr(view, "$container") : null;
+    if(!$c) {
+        log_error(
+            `${gobj_short_name(host)}: hosted view does not expose $container ` +
+            `— check its mt_create`
+        );
+        $c = createElement2(["div", {}, ""]);
+    }
+    gobj_write_attr(host, "$container", $c);
+    return $c;
+}
+
+
+
+
+                    /***************************
+                     *      Framework Methods
+                     ***************************/
+
+
+
+
+/***************************************************************
+ *          Framework Method: Create
+ ***************************************************************/
+function mt_create(gobj)
+{
+    let priv = gobj.priv;
+
+    /*
+     *  CHILD subscription model
+     */
+    let subscriber = gobj_read_pointer_attr(gobj, "subscriber");
+    if(!subscriber) {
+        subscriber = gobj_parent(gobj);
+    }
+    gobj_subscribe_event(gobj, null, {}, subscriber);
+
+    priv.view = yui_mount_service_view(gobj, {
+        gclass:         gobj_read_str_attr(gobj, "view_gclass"),
+        name:           gobj_read_str_attr(gobj, "service_name"),
+        kw:             gobj_read_attr(gobj, "view_kw") || {},
+        transport:      gobj_read_str_attr(gobj, "transport_service"),
+        transport_attr: gobj_read_str_attr(gobj, "transport_attr")
+    });
+
+    expose_view_container(gobj, priv.view);
+}
+
+/***************************************************************
+ *          Framework Method: Start
+ *
+ *  The view starts HERE and not in mt_create, so its first
+ *  request goes out when the host shows it.
+ ***************************************************************/
+function mt_start(gobj)
+{
+    const view = gobj.priv.view;
+    if(view && !gobj_is_running(view)) {
+        gobj_start(view);
+    }
+}
+
+/***************************************************************
+ *          Framework Method: Stop
+ ***************************************************************/
+function mt_stop(gobj)
+{
+    const view = gobj.priv.view;
+    if(view && gobj_is_running(view)) {
+        gobj_stop(view);
+    }
+}
+
+/***************************************************************
+ *          Framework Method: Destroy
+ *
+ *  The view is a SERVICE created with this gobj as its parent, so
+ *  gobj_destroy cascades onto it — and deregisters its name.  Do
+ *  NOT destroy it again here.
+ ***************************************************************/
+function mt_destroy(gobj)
+{
+    let priv = gobj.priv;
+
+    priv.view = null;
+
+    const $c = gobj_read_attr(gobj, "$container");
+    if($c && $c.parentNode) {
+        $c.parentNode.removeChild($c);
+    }
+    gobj_write_attr(gobj, "$container", null);
+}
+
+
+
+
+                    /***************************
+                     *          FSM
+                     ***************************/
+
+
+
+
+const gmt = {
+    mt_create:  mt_create,
+    mt_start:   mt_start,
+    mt_stop:    mt_stop,
+    mt_destroy: mt_destroy
+};
+
+function create_gclass(gclass_name)
+{
+    if(__gclass__) {
+        log_error(`GClass ALREADY created: ${gclass_name}`);
+        return -1;
+    }
+
+    const states = [
+        ["ST_IDLE", []]
+    ];
+
+    const event_types = [];
+
+    __gclass__ = gclass_create(
+        gclass_name,
+        event_types,
+        states,
+        gmt,
+        0,
+        attrs_table,
+        PRIVATE_DATA,
+        0,
+        0,
+        0,
+        0
+    );
+
+    return __gclass__ ? 0 : -1;
+}
+
+function register_c_yui_service_view()
+{
+    return create_gclass(GCLASS_NAME);
+}
+
+export {
+    register_c_yui_service_view,
+    yui_mount_service_view,
+    expose_view_container,
+};

package/src/c_yui_shell.js

@@ -1542,10 +1542,8 @@ function build_view_gobj(gobj, entry, route, stage)
      *  (synthesized "cards" C_YUI_NAV) is SHELL-owned DOM built after
      *  the host's one-shot refresh_language — apply the registered
      *  translator, same policy as lazily-built dropdown panels. */
-    let priv = gobj.priv;
-    if(priv && typeof priv.translator === "function" &&
-            target.gclass === "C_YUI_NAV") {
-        refresh_language($view, priv.translator);
+    if(target.gclass === "C_YUI_NAV") {
+        yui_shell_translate(gobj, $view);
     }
     return view;
 }
@@ -2050,9 +2048,7 @@ function open_toolbar_dropdown(gobj, item, action, $trigger)
     priv.layers.popup.appendChild($panel);
 
     /*  Translate the lazily-built panel (see the note above). */
-    if(typeof priv.translator === "function") {
-        refresh_language($panel, priv.translator);
-    }
+    yui_shell_translate(gobj, $panel);
 
     /*  Click-outside (capture-phase mousedown) closes the dropdown.
      *  Capture phase so a click on a sibling toolbar trigger lands
@@ -2857,10 +2853,7 @@ function yui_shell_set_submenu(shell_gobj, parent_item_id, items)
                 gobj_send_event(view, "EV_SET_ITEMS", {items: items}, shell_gobj);
                 /*  EV_SET_ITEMS rebuilt the DOM: re-apply the translator
                  *  (shell-owned DOM, same policy as build_view_gobj). */
-                let $view = gobj_read_attr(view, "$container");
-                if($view && typeof priv.translator === "function") {
-                    refresh_language($view, priv.translator);
-                }
+                yui_shell_translate(shell_gobj, gobj_read_attr(view, "$container"));
             }
         }
     }
@@ -3265,9 +3258,10 @@ function yui_shell_refresh_avatars(shell_gobj)
  *  Register the host's i18n translator (a t-function:
  *  key => translated string).  The host still translates the
  *  static shell tree itself via refresh_language($container, t);
- *  this is only so the shell can translate DOM it builds LAZILY
- *  and OUTSIDE $container — today the toolbar dropdown panel.
- *  Optional: with no translator the panel renders raw keys
+ *  this is only so the shell — and the library components that
+ *  build DOM under it — can translate DOM built LAZILY, after
+ *  that one-shot pass and often outside $container.
+ *  Optional: with no translator such DOM renders raw keys
  *  (the previous behaviour).
  ************************************************************/
 function yui_shell_set_translator(shell_gobj, t)
@@ -3279,6 +3273,39 @@ function yui_shell_set_translator(shell_gobj, t)
     priv.translator = (typeof t === "function") ? t : null;
 }
 
+/************************************************************
+ *  Apply the registered translator to a FRESHLY BUILT subtree.
+ *
+ *  Carrying the `i18n` key on a node is not enough for it to
+ *  render translated: the node is born holding the raw English
+ *  key, and the host's refresh_language() passes walk what
+ *  ALREADY exists — the shell tree at start up, document.body on
+ *  a language switch.  Anything built after that (a dropdown
+ *  panel, a nav a node renders when you walk into it) is reached
+ *  by neither, so it renders the key: lower-case English that
+ *  never changes language, i.e. exactly what a MISSING key looks
+ *  like.
+ *
+ *  The division of labour, unchanged: LIBRARY-built DOM is
+ *  translated through here; APP view gclasses translate their own
+ *  DOM (they own a `t` — see mount_view).
+ *
+ *  Silent no-op with no shell or no translator: an app that never
+ *  registered one keeps the previous behaviour instead of losing
+ *  its chrome.
+ ************************************************************/
+function yui_shell_translate(shell_gobj, $el)
+{
+    if(!$el || !shell_gobj || !is_gobj(shell_gobj)) {
+        return;
+    }
+    let priv = shell_gobj.priv;
+    if(!priv || typeof priv.translator !== "function") {
+        return;
+    }
+    refresh_language($el, priv.translator);
+}
+
 /************************************************************
  *  The app switched the language: re-translate the whole document (every
  *  node carrying data-i18n / data-i18n-title / data-i18n-aria-label) and
@@ -3383,6 +3410,7 @@ export {
     yui_shell_set_avatar_provider,
     yui_shell_refresh_avatars,
     yui_shell_set_translator,
+    yui_shell_translate,
     yui_shell_language_changed,
     yui_shell_set_connection_state,
     yui_shell_set_toolbar_item_icon,

package/src/node_tree_model.js

@@ -211,6 +211,73 @@ export function chrome_visible(distance, depth)
     return distance <= depth;
 }
 
+/************************************************************
+ *  NAVIGATION MODES — the three ways a tree can show the way in.
+ *
+ *      "stack"  — one chrome strip per ancestor.  Whatever each
+ *                 node declared, painted at every level.
+ *      "back"   — only the tip's parent, and only as a "← parent".
+ *      "path"   — no strips at all: the trail as ONE breadcrumb
+ *                 line, drawn by the root.
+ *
+ *  A mode is a FILTER over what the app declared, applied when the
+ *  renders are asked for — never a rewrite of the declared
+ *  projections.  That is what makes going back to "stack" free and
+ *  exact: an app that declares `vertical` chrome gets `vertical`
+ *  back, not the tabs a canonical "stack" shape would have imposed.
+ *
+ *  The index projection is NEVER touched: how a node shows its own
+ *  children when it IS the page is not a statement about depth.
+ ************************************************************/
+export const NAV_MODES = ["stack", "back", "path"];
+
+export function is_nav_mode(mode)
+{
+    return NAV_MODES.indexOf(mode) >= 0;
+}
+
+/************************************************************
+ *  The renders of one projection slot under a nav mode.
+ *
+ *  `is_root` only matters for "path": the trail is drawn from the
+ *  tree root down to the tip whoever declares it, so exactly one
+ *  node must draw it or the same line appears once per ancestor.
+ ************************************************************/
+export function nav_mode_renders(projection, mode, slot, is_root)
+{
+    if(slot === "index" || !is_nav_mode(mode) || mode === "stack") {
+        return projection_renders(projection, slot);
+    }
+    if(mode === "back") {
+        return (slot === "chrome") ? [{layout: "backbar"}] : [];
+    }
+    /*  "path"  */
+    if(slot === "path") {
+        return is_root ? [{layout: "breadcrumb"}] : [];
+    }
+    return [];
+}
+
+/************************************************************
+ *  The effective chrome depth under a nav mode.
+ *
+ *  "back" is exactly `chrome_depth: 1` — one strip, the parent's.
+ *  "path" is `0`: the trail already says everything the strips
+ *  would, and a strip under it would be the same information twice.
+ *  Both override what the tree declared, because the user asked for
+ *  a shape and the declaration is what they asked to change.
+ ************************************************************/
+export function nav_mode_depth(declared_depth, mode)
+{
+    if(mode === "back") {
+        return 1;
+    }
+    if(mode === "path") {
+        return 0;
+    }
+    return declared_depth;
+}
+
 /************************************************************
  *  Validate + fill one node spec.  Returns the normalized spec,
  *  or null when it is unusable; every rejection pushes a

package/src/node_tree_model.test.js

@@ -12,6 +12,9 @@ import {
     projection_renders,
     child_nav_items,
     normalize_spec,
+    is_nav_mode,
+    nav_mode_renders,
+    nav_mode_depth,
 } from "./node_tree_model.js";
 
 
@@ -280,3 +283,70 @@ test("a link IS the node's content — declaring both is rejected", () => {
     }, errors, "/")).toBe(null);
     expect(errors.some((e) => /both 'link' and 'content'/.test(e))).toBe(true);
 });
+
+
+/***************************************************************
+ *      navigation modes
+ ***************************************************************/
+const DECLARED = {
+    index:  {layout: "cards"},
+    chrome: [
+        {layout: "tabs", show_on: ">=tablet"},
+        {layout: "backbar", show_on: "<tablet"}
+    ]
+};
+
+test("only the three modes are modes", () => {
+    expect(is_nav_mode("stack")).toBe(true);
+    expect(is_nav_mode("back")).toBe(true);
+    expect(is_nav_mode("path")).toBe(true);
+    expect(is_nav_mode("breadcrumb")).toBe(false);   /*  that is a LAYOUT  */
+    expect(is_nav_mode("")).toBe(false);
+});
+
+test("stack gives back exactly what the node declared", () => {
+    expect(nav_mode_renders(DECLARED, "stack", "chrome", true))
+        .toEqual(DECLARED.chrome);
+    expect(nav_mode_renders("vertical", "stack", "index", false))
+        .toEqual([{layout: "vertical"}]);
+    /*  An unknown mode must not silently reshape a tree  */
+    expect(nav_mode_renders(DECLARED, "nonsense", "chrome", true))
+        .toEqual(DECLARED.chrome);
+});
+
+test("back replaces every chrome with one backbar, and drops the trail", () => {
+    expect(nav_mode_renders(DECLARED, "back", "chrome", true))
+        .toEqual([{layout: "backbar"}]);
+    expect(nav_mode_renders(DECLARED, "back", "chrome", false))
+        .toEqual([{layout: "backbar"}]);
+    expect(nav_mode_renders({path: {layout: "breadcrumb"}}, "back", "path", true))
+        .toEqual([]);
+});
+
+test("path draws the trail ONCE, at the root, and no strips anywhere", () => {
+    expect(nav_mode_renders(DECLARED, "path", "path", true))
+        .toEqual([{layout: "breadcrumb"}]);
+    expect(nav_mode_renders(DECLARED, "path", "path", false)).toEqual([]);
+    expect(nav_mode_renders(DECLARED, "path", "chrome", true)).toEqual([]);
+    expect(nav_mode_renders(DECLARED, "path", "chrome", false)).toEqual([]);
+});
+
+test("the index projection survives every mode", () => {
+    for(const mode of ["stack", "back", "path"]) {
+        expect(nav_mode_renders(DECLARED, mode, "index", true))
+            .toEqual([{layout: "cards"}]);
+    }
+    /*  and an undeclared projection keeps defaulting to cards  */
+    expect(nav_mode_renders(null, "path", "index", true))
+        .toEqual([{layout: "cards"}]);
+});
+
+test("back is depth 1 and path is depth 0, whatever the tree declared", () => {
+    expect(nav_mode_depth(null, "back")).toBe(1);
+    expect(nav_mode_depth(3, "back")).toBe(1);
+    expect(nav_mode_depth(null, "path")).toBe(0);
+    expect(nav_mode_depth(3, "path")).toBe(0);
+    /*  stack keeps the declaration, unlimited included  */
+    expect(nav_mode_depth(null, "stack")).toBe(null);
+    expect(nav_mode_depth(2, "stack")).toBe(2);
+});