@yuneta/gobj-ui 5.3.3 → 5.5.0

package/README.md

@@ -162,7 +162,11 @@ seen*:
         "content":  {"gclass": "C_MY_LANDING", "kw": {}},
         "children": [
             {"id": "energy", "label": "Energy", "icon": "yi-bolt",
-             "projection": {"index": {"layout": "cards"}},
+             "projection": {
+                 "index":  {"layout": "cards"},
+                 "chrome": [{"layout": "tabs", "show_on": ">=tablet"},
+                            {"layout": "backbar", "show_on": "<tablet"}]
+             },
              "children": [ /* … any depth … */ ]}
         ]
     }
@@ -173,6 +177,16 @@ seen*:
   icon-bar/backbar and `show_on` all work unchanged) in two modes: `index`
   when the node is the tip of the path — the projection IS the page — and
   `chrome` when a child is showing — the projection is the strip around it.
+- **Chrome belongs to the node that declares it — so every branch declares its
+  own.** A node's `chrome` strip lists *that* node's children, and its backbar
+  goes back to *that* node's route (`back_route = my_route`). A branch that
+  declares no `chrome` therefore contributes no strip, and the only ← the user
+  can reach is the nearest ancestor that did declare one. Declaring the pair
+  **only at the root** is the mistake this rule exists to name: the whole
+  subtree then shows one "← root" that says the same thing at every depth,
+  instead of one ← per level going up exactly one level. Repeat the same
+  `chrome` on every branch that can have a tip below it — that is what
+  `test-app`'s `/cards` does, and what makes its ← hierarchical.
 - **`content` and `children` are not exclusive**: a section with its own page
   and sub-pages is one node.
 - **The route table does not grow.** The host declares ONE route; everything
@@ -187,6 +201,30 @@ seen*:
   `projection.path`) while the rest of the tree keeps its tabs. Note the
   asymmetry that makes it a third mode and not a layout: `index` and `chrome`
   project a node's CHILDREN; `path` projects the way in.
+- **`nav_mode` — the three shapes as one runtime knob.** The two bullets above
+  describe what a tree *declares*; `nav_mode` is how a user *chooses* between
+  the shapes without the app rewriting anything:
+
+  | mode | what it shows | equivalent declaration |
+  |---|---|---|
+  | `"stack"` (default) | one strip per ancestor | whatever each branch declares |
+  | `"back"` | only the tip's parent, as a `← parent` | `chrome: {"layout":"backbar"}` everywhere + `chrome_depth: 1` |
+  | `"path"` | the trail as ONE line | `path: {"layout":"breadcrumb"}` on the root + `chrome_depth: 0` |
+
+  It belongs to the **root** (`yui_node_set_nav_mode(root, "path")`, or
+  `"nav_mode"` in its declaration) and the whole tree reads it from there —
+  ancestors stacking strips while a descendant drew a breadcrumb would be
+  saying the same thing twice in two languages. Set on a middle node it is
+  refused, loudly, rather than accepted and ignored.
+
+  A mode **filters the renders as they are asked for; it never rewrites what
+  the app declared.** That is what makes `"stack"` an exact restore: a branch
+  that declared `vertical` chrome comes back as `vertical`, not as the tabs a
+  canonical "stacked" shape would have imposed. The `index` projection is
+  never touched by a mode — how a node shows its own children when it IS the
+  page is not a statement about depth. Modes are per tree, so an app can run
+  `/admin` as a breadcrumb and `/alarms` as a backbar; `test-app`'s node lab
+  cycles all three on the live tree.
 - **`chrome_depth`** caps the stacked chrome: with every ancestor painting its
   own strip, depth N shows N-1 of them. A node declares how many its corner of
   the tree deserves (`0` = none, omit = all), the **deepest declaration on the
@@ -199,6 +237,7 @@ seen*:
   yui_node_add(node, spec, index)      yui_node_remove(node, node_id)
   yui_node_set_projection(node, proj)  yui_node_set_content(node, content)
   yui_node_set_chrome_depth(node, n)   yui_node_tree_version(node)
+  yui_node_set_nav_mode(root, mode)    yui_node_nav_mode(node)
   yui_node_find(node, "energy/north")  yui_node_route(node)
   ```
 
@@ -283,6 +322,61 @@ Runnable reference: the **Cards** chapter of `test-app` (four levels plus a
 panel that mutates the live tree), driven by `test-app/_qa_nodetree.mjs` and
 `test-app/_qa_extra.mjs`.
 
+### C_YUI_SERVICE_VIEW — mounting a view that talks to a backend
+
+A view asks the backend for data with `gobj_command(remote, …, 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, so a backend-talking view mounted directly at a route
+never receives a single answer: it sits empty while the ievent logs *"service
+not found"* once per answer. And a route's `target.kw` is static JSON, so it
+cannot carry the live transport pointer either.
+
+Two shapes, because the callers are not alike:
+
+```js
+/*  A route with NO extras: declare the host, name the view it hosts.  */
+{ gclass: "C_YUI_SERVICE_VIEW", kw: {
+    view_gclass:  "C_MY_VIEW",
+    service_name: "#my-view",          // UNIQUE per mount — see below
+    view_kw:      { title: "…" }
+}}
+
+/*  A wrapper that keeps its own extras (url segments into the hosted view,
+ *  rebinding it when a connection drops): drop only the boilerplate.       */
+let view = yui_mount_service_view(gobj, {
+    gclass:    "C_YUI_TREEDB_TOPICS",
+    name:      service_name(gobj),
+    kw:        {...},
+    transport: remote            // already resolved (e.g. per connection);
+});                              // omit it for "__remote_service__"
+```
+
+The hosted gclass must declare the attr the transport is injected under
+(`gobj_remote_yuno` by default), build its `$container` in `mt_create`, and flag
+`EVF_PUBLIC_EVENT` on whatever arrives from the backend — the ievent drops
+events that are not public.
+
+**The service name must be unique per mount**, and a duplicate is dangerous
+precisely because it is not fatal: gobj-js logs *"service ALREADY REGISTERED.
+Will be UPDATED"* and **rebinds the name**, so two mounts of one route would
+cross their answers. Derive it from the route (or from whatever else makes the
+mount unique — a connection id, a workspace), never from the gclass alone.
+
+> **Why the hosts do not just create services.** It would make every routed view
+> an inter-yuno endpoint by default, against the framework's rule that only
+> named services are; most views never talk to a backend; and the collision
+> above would become the default failure mode. Opt-in per route instead.
+>
+> **Known asymmetry, deliberately left alone:** `C_YUI_SHELL` mounts a view with
+> `gobj_create()` (a plain child) and `C_YUI_NODE` with
+> `gobj_create_pure_child()`. The flag decides whether a gclass that consults
+> `gobj_is_pure_child()` sends its output event straight to the parent or
+> publishes it. Today nothing consults it *on a view* (only `c_ievent_cli` and
+> `c_timer` do, and always about themselves), so the difference has no observed
+> consequence — but the same view gclass does get a different flag depending on
+> who mounted it. Align it the day it bites, with the case that bit.
+
 ### C_YUI_JSON — lazy JSON tree viewer
 
 Indentation follows the house rule: four characters per level, plus a **guide
@@ -401,6 +495,25 @@ shapes, and the fix for each:
 | A composed string (`` `${key} · ${t(mode)}` ``) | carries no key at all | split it: the translatable halves get their own key. (Note `createElement2` **trims** text nodes — space a `·` separator with CSS, not with spaces.) |
 | `title` / `aria-label` set with `t()` | tooltip stuck in the old language | `data-i18n-title` / `data-i18n-aria-label` |
 | Anything a WIDGET renders (a Tabulator header, its paginator, a formatter) | drawn once; no attribute reaches it | subscribe to the shell and re-render (below) |
+| DOM built AFTER start up (a node's strips, a dropdown panel) | renders the raw key — indistinguishable from a MISSING key | `yui_shell_translate(shell, $el)` right after building it (below) |
+
+**Carrying the key is not enough for the FIRST render.** A node is born holding
+the raw English key, and the app's `refresh_language()` passes only walk what
+already exists: the shell tree at start up, `document.body` on a language
+switch. Anything built later — a `C_YUI_NODE` strip rendered when you walk into
+it, a lazily-built toolbar panel — is reached by neither, so it renders the key:
+lower-case English that never changes language, which is exactly what a missing
+key looks like. Division of labour:
+
+```js
+yui_shell_translate(shell, $el);   // LIBRARY-built DOM, right after building it
+```
+
+and **app view gclasses translate their own DOM** — they own a `t`, so they call
+`refresh_language($container, t)` at the end of their build (this is why the
+shell does not translate a mounted view: see `mount_view` in `c_yui_shell.js`).
+`yui_shell_translate` is a no-op when the app registered no translator, so
+behaviour is unchanged for apps that never call `yui_shell_set_translator`.
 
 **The contract.** The app owns the locales: it switches its i18next and calls