@yuneta/gobj-ui 5.2.1 → 5.3.0

package/README.md

@@ -138,8 +138,160 @@ toggles it closed. The tree model is `yui_shell_nav_map()` /
 protocols (`yui_shell_set_sub_routes`, `yui_shell_register_event_handler`)
 live in [`ROUTING.md`](ROUTING.md).
 
+### C_YUI_NODE — navigation as a tree of gobjs (prototype)
+
+`C_YUI_SHELL`'s menu tree is **two levels** (a primary item and its
+`submenu.items`); a submenu item cannot declare a submenu of its own, so a
+section with sub-sections has to flatten everything into one tab strip.
+
+`C_YUI_NODE` is the prototype of the other model: **the gobj tree IS the
+navigation tree.** A node is a gobj, the URL is the path of node ids under a
+single declared `base_route`, and a parent holds *how it wants its children
+seen*:
+
+```json
+{
+    "gclass": "C_YUI_NODE",
+    "kw": {
+        "node_id": "cards", "base_route": "/cards",
+        "projection": {
+            "index":  {"layout": "cards"},
+            "chrome": [{"layout": "tabs", "show_on": ">=tablet"},
+                       {"layout": "backbar", "show_on": "<tablet"}]
+        },
+        "content":  {"gclass": "C_MY_LANDING", "kw": {}},
+        "children": [
+            {"id": "energy", "label": "Energy", "icon": "yi-bolt",
+             "projection": {"index": {"layout": "cards"}},
+             "children": [ /* … any depth … */ ]}
+        ]
+    }
+}
+```
+
+- **`projection`** is a `C_YUI_NAV` render config (so cards/tabs/vertical/
+  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.
+- **`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
+  below arrives as the shell's `subpath` (ROUTING.md §4), and the tree
+  contributes its full shape to the site map via `yui_shell_set_sub_routes`.
+- **Two ways to show depth.** Stacked chrome — one strip per ancestor —
+  reads well at three levels and eats the screen at five. The other way is
+  **`projection.path`**: the trail down to the user as ONE line
+  (`{"layout": "breadcrumb"}`), drawn from the tree root whichever node
+  declares it, each crumb a link to that level. Declared per branch, so a
+  deep corner can trade its strips for a breadcrumb (`chrome_depth: 0` +
+  `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.
+- **`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
+  path wins, and an intermediate node whose only job is to hold that number is
+  a legitimate node.
+- **Declarative and dynamic are the same code.** The declared `children` attr
+  is fed to the same `EV_ADD_NODE` the runtime API uses:
+
+  ```js
+  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_find(node, "energy/north")  yui_node_route(node)
+  ```
+
+  A node added at runtime is deep-linkable like one declared at boot. Removing
+  the branch the user is standing on moves them to the nearest living ancestor
+  (`replace`, logged) — with a live tree the ground can disappear under a
+  bookmark.
+
+Every move goes through the URL: a projection click publishes
+`EV_NAV_CLICKED`, the node turns it into a push navigation, and the shell's
+`EV_ROUTE_CHANGED` walks back down the tree as `EV_ACTIVATE`. Back, Forward,
+F5 and deep links are therefore correct by construction.
+
+**The root can be a node too** — `config.shell.tree`. Declared there, the
+shell stops owning the menu and keeps only the **space** (zones, layers,
+stages, toolbar, overlays, theme, breakpoints): the root node's children are
+the app's primary options, and it projects them into zones instead of into its
+own body.
+
+```json
+"shell": {
+    "zones": {"top": {"host": "toolbar"}, "left": {"show_on": ">=desktop"},
+              "bottom": {"show_on": "<desktop"}, "center": {"host": "stage.main"}},
+    "stages": {"main": {"zone": "center", "default_route": "/"}},
+    "tree": {
+        "base_route": "/", "stage": "main",
+        "projection": {
+            "index":  [{"zone": "left", "layout": "vertical"},
+                       {"zone": "bottom", "layout": "icon-bar"}],
+            "chrome": [{"zone": "left", "layout": "vertical"},
+                       {"zone": "bottom", "layout": "icon-bar"}]
+        },
+        "children": [ /* the primary options, and everything under them */ ]
+    }
+}
+```
+
+Note what is NOT there: no zone declares `host: "menu.<id>"`, and there is no
+`menu` block at all. A render config with a `zone` mounts through
+`yui_shell_zone()` and **persists** — the rail is standing chrome, so it is
+built once and told where the user is, not rebuilt per navigation.
+`menu.primary.render` always was a per-zone projection; this just gives it an
+owner that can hold it.
+
+`shell.tree` synthesizes exactly ONE route entry, flagged `owns_subtree`, which
+is the only case where root `/` may match as an ancestor (`route_resolver.js`).
+The unknown-route diagnostic is not lost by that: it moves to the node that
+actually knows the names of its children. Runnable reference:
+`test-app/tree.html` (`_qa_root.mjs`), served beside `index.html` so the two
+navigation models can be compared in one browser.
+
+**Where the tree ends.** One gobj per structural node is right; one gobj per
+meter reading is not. A node marks the boundary with `link` — a pointer into a
+data space (a timeranger: millions of raw records, series/time, key/value) plus
+the viewer suited to that shape:
+
+```json
+{"id": "m1", "label": "Meter 1",
+ "link": {"kind": "tranger", "gclass": "C_MY_TRANGER_VIEW",
+          "kw": {"topic": "meters^north^m1"}}}
+```
+
+A link node is always the **tip of the structure**: the url keeps going, but
+its tail is handed to the viewer as `EV_ROUTE_CHANGED {base, subpath}` — the
+same contract the shell gives a view (ROUTING.md §5), so a viewer cannot tell
+whether the shell mounted it at a declared route or a node did, deep in a tree.
+`base` is the node's canonical route, which is what the viewer builds its own
+deep links from. An empty subpath means the viewer's home, which is what makes
+Back out of a deep data position land on it. Below a link there are no nodes:
+`link` + `children` (or `link` + `content`) is a config error, because a silent
+winner in "who owns the subpath" would be the worst outcome.
+
+**The tree is a contract, not runtime state.** Once published, a node's path
+is a url a client may have bookmarked, scripted, or been sold as another door
+into the system. So there is deliberately **no reparent/move API**: the shape
+is versioned (`tree_version` on the root, `yui_node_tree_version()`), and a
+rename migrates through `aliases` — the former id keeps resolving and the URL
+is rewritten (replace) to the canonical spelling, the same shape as an HTTP
+301. Anything a version bump cannot cover is a new tree, declared as such.
+
+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_JSON — lazy JSON tree viewer
 
+Indentation follows the house rule: four characters per level, plus a **guide
+line per ancestor**. The rows are siblings with growing padding rather than
+nested boxes, so the guides are painted as a repeating gradient bounded to
+each row's own indentation (`background-size` set per row) — which is why the
+hover state must set `background-color`, never the `background` shorthand, or
+the guides vanish under the cursor.
+
 A container-agnostic viewer (like `C_YUI_PAGER`): it owns only a toolbar +
 scrollable tree body and exposes a `$container` the parent mounts wherever it
 wants (a `C_YUI_WINDOW` body, a `yui_shell_show_modal` card, or inline). It is
@@ -371,6 +523,19 @@ handlers re-run on their own (which is why a component rarely needs a dedicated
 fires **no** `input` event — a value loaded into the form, or `readonly` toggled
 by the form mode. No-op on an input that never got a clear.
 
+### Indentation is always FOUR spaces
+
+Anywhere structure is shown as indentation — the site map's tree, `C_YUI_JSON`
+and the raw dump behind it, any `JSON.stringify` a view puts on screen — one
+level is **four** characters. Not two here and four there: the reader is using
+the indentation to see the shape, and a shape that changes width between two
+panels of the same app is one more thing to decode.
+
+- `JSON.stringify(value, null, 4)` — never `2`.
+- Rendered trees indent in **`ch`** (`padding-left: 4ch`), not `rem`: it
+  follows the row's own monospace font, so the guides stay lined up with the
+  text they belong to instead of drifting at some zoom level.
+
 ### Logical class names on important DOM blocks
 
 When a gclass builds DOM, tag its elements so the tree is self-describing in