@yuneta/gobj-ui 5.4.0 → 5.6.0

package/README.md

@@ -322,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
@@ -409,6 +464,46 @@ host can use it to toggle. The tree is a **pure child of the window**, so every
 teardown path (the ✕, or the host destroying the window to toggle the entry
 off) takes it down too.
 
+### Toolbar badge — a count pinned to an item's icon
+
+```js
+/*  app_config.json — seeds the FIRST paint only  */
+{ "id": "alarms", "icon": "yi-triangle-exclamation", "align": "end",
+  "aria_label": "alarms", "badge": 0,
+  "action": {"type": "navigate", "route": "/alarms"} }
+
+/*  the interface that matters: a count is a RUNTIME fact  */
+yui_shell_set_toolbar_item_badge(shell, "alarms", 3);
+yui_shell_set_toolbar_item_badge(shell, "alarms", 0);   // clears it
+```
+
+An icon-only toolbar button is a link; the badge is what makes it a
+**signal**. Without a number, an alarm bell cannot say whether anything needs
+you — which is the reason to look at it at all.
+
+Rules baked in, all for the same reason (a badge that lies costs more than no
+badge):
+
+- **`0`, `""`, `null` and `false` all clear it.** A badge reading "0" is worse
+  than none: it draws the eye to say nothing.
+- **Over 99 renders `99+`.** The toolbar is a fixed-width row and a four-digit
+  pill pushes its neighbours off a phone screen.
+- **A string passes through** for the states that are not counts (`"!"`, `"…"`).
+- **Unknown item id is a silent no-op**, so an app whose toolbar has no such
+  item does not log an error on every tick of whatever feeds the number.
+- Writing the **same** value again touches no DOM: the badge is a
+  `role="status"` live region, and rewriting it would have a screen reader
+  announce the same number on every tick.
+
+`role="status"` and not `aria-hidden`, deliberately: the button carries an
+explicit `aria-label`, and an explicit label **replaces** an element's content
+for a screen reader — a badge inside it would otherwise be silent. As its own
+live region it is both read and announced when it changes.
+
+> `C_YUI_NAV` items do **not** have this. Its item contract listed `badge` for a
+> long time and nothing ever rendered it; the claim is gone. Implement it there
+> the day a menu entry needs one.
+
 ### Modals — `yui_shell_show_modal` and the `before_close` veto
 
 `yui_shell_show_modal(shell, $box, opts)` is the standard popup: pass
@@ -440,6 +535,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