@yuneta/gobj-ui 5.3.3 → 5.4.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)
   ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@yuneta/gobj-ui",
-    "version": "5.3.3",
+    "version": "5.4.0",
     "type": "module",
     "main": "dist/gobj-ui.cjs.js",
     "module": "dist/gobj-ui.es.js",

package/src/c_yui_node.js

@@ -126,6 +126,10 @@ import {
     child_nav_items,
     chrome_visible,
     normalize_spec,
+    is_nav_mode,
+    nav_mode_renders,
+    nav_mode_depth,
+    NAV_MODES,
 } from "./node_tree_model.js";
 
 import {
@@ -169,6 +173,7 @@ SDATA(data_type_t.DTP_JSON,     "children",     0,  null,   "Declared child spec
 
 SDATA(data_type_t.DTP_STRING,   "base_route",   0,  "",     "ROOT only: the declared route the whole tree hangs from"),
 SDATA(data_type_t.DTP_STRING,   "tree_version", 0,  "",     "ROOT only: version of the tree CONTRACT (its paths are public urls)"),
+SDATA(data_type_t.DTP_STRING,   "nav_mode",     0,  "stack","ROOT only: how the way in is shown — stack|back|path"),
 
 SDATA(data_type_t.DTP_POINTER,  "$container",   0,  null,   "Root HTMLElement (shell view contract)"),
 SDATA_END()
@@ -389,6 +394,29 @@ function tree_root_of(gobj)
     }
 }
 
+/************************************************************
+ *  The navigation mode in force for this node.
+ *
+ *  It is ONE knob per tree, held by the root: a tree whose ancestors
+ *  stacked strips while a descendant drew a breadcrumb would be
+ *  showing the way in twice, in two languages.  Descendants read it
+ *  from the root rather than keeping a copy, so a node added at
+ *  runtime is born in the mode the tree is already in.
+ ************************************************************/
+function nav_mode_of(gobj)
+{
+    let mode = gobj_read_attr(tree_root_of(gobj), "nav_mode") || "stack";
+
+    if(!is_nav_mode(mode)) {
+        log_error(
+            `${GCLASS_NAME} '${node_path_str(gobj)}': unknown nav_mode ` +
+            `'${mode}' — expected one of ${NAV_MODES.join("|")}`
+        );
+        return "stack";
+    }
+    return mode;
+}
+
 /************************************************************
  *  Node ids from the root DOWN TO this node, root excluded
  *  (the root's own segment is already inside base_route).
@@ -494,12 +522,14 @@ function resolve_path_info(gobj, subpath, inherited)
 {
     let effective = (typeof inherited === "number") ? inherited : null;
 
+    let mode = nav_mode_of(gobj);
+
     let own = gobj_read_attr(gobj, "chrome_depth");
     if(typeof own === "number" && own >= 0) {
         effective = own;
     }
     if(has_link(gobj)) {
-        return {distance: 0, chrome_depth: effective, chain: []};
+        return {distance: 0, chrome_depth: nav_mode_depth(effective, mode), chain: []};
     }
 
     /*  Distance is counted in STRUCTURAL segments: the tail a viewer
@@ -524,7 +554,11 @@ function resolve_path_info(gobj, subpath, inherited)
             break;
         }
     }
-    return {distance: distance, chrome_depth: effective, chain: chain};
+    return {
+        distance: distance,
+        chrome_depth: nav_mode_depth(effective, mode),
+        chain: chain
+    };
 }
 
 /************************************************************
@@ -575,7 +609,8 @@ function render_projection(gobj, mode, $where, active_route, active_id, zones_on
     if(!priv.children.length) {
         return;
     }
-    let renders = projection_renders(gobj_read_attr(gobj, "projection"), mode);
+    let renders = nav_mode_renders(gobj_read_attr(gobj, "projection"),
+        nav_mode_of(gobj), mode, priv.is_root);
     if(!renders.length) {
         return;
     }
@@ -833,7 +868,8 @@ function render_child(gobj, child)
 function render_path(gobj, $where)
 {
     let priv = gobj.priv;
-    let renders = projection_renders(gobj_read_attr(gobj, "projection"), "path");
+    let renders = nav_mode_renders(gobj_read_attr(gobj, "projection"),
+        nav_mode_of(gobj), "path", priv.is_root);
 
     if(!renders.length) {
         return;
@@ -1328,6 +1364,54 @@ function ac_set_chrome_depth(gobj, event, kw, src)
     return 0;
 }
 
+/************************************************************
+ *  Runtime API: change how this TREE shows the way in.
+ *
+ *  One knob for the whole tree, and deliberately root-only: the
+ *  mode answers "how deep am I and how do I get back", a question
+ *  that has one answer per tree.  Set on a middle node it would
+ *  silently do nothing (descendants read the root's), and a knob
+ *  that accepts a call and ignores it is worse than one that
+ *  refuses it.
+ *
+ *  Nothing declared is rewritten — the mode filters the renders as
+ *  they are asked for — so going back to "stack" restores exactly
+ *  what the app declared, per branch, including layouts this mode
+ *  never mentions.
+ ************************************************************/
+function ac_set_nav_mode(gobj, event, kw, src)
+{
+    let priv = gobj.priv;
+    let mode = kw.nav_mode || "";
+
+    if(!is_nav_mode(mode)) {
+        log_error(
+            `${GCLASS_NAME} '${node_path_str(gobj)}': unknown nav_mode ` +
+            `'${mode}' — expected one of ${NAV_MODES.join("|")}`
+        );
+        return -1;
+    }
+    if(!priv.is_root) {
+        log_error(
+            `${GCLASS_NAME} '${node_path_str(gobj)}': nav_mode belongs to the ` +
+            `tree ROOT — set it there, the whole tree reads it`
+        );
+        return -1;
+    }
+    gobj_write_attr(gobj, "nav_mode", mode);
+
+    /*  Same reason as EV_SET_CHROME_DEPTH: what changes is the shape
+     *  of the ACTIVE PATH, whose strips are painted by the ancestors,
+     *  so the tree is asked to re-apply the current route instead of
+     *  repainting one node. */
+    let shell = yui_shell_of(gobj);
+    if(shell) {
+        yui_shell_navigate(shell, gobj_read_attr(shell, "current_route") ||
+            route_of(gobj), {replace: true});
+    }
+    return 0;
+}
+
 /************************************************************
  *  Runtime API: change (or set) my content.
  ************************************************************/
@@ -1402,6 +1486,20 @@ function yui_node_set_chrome_depth(node, depth)
         {chrome_depth: depth}, node);
 }
 
+/************************************************************
+ *  The tree's navigation mode: "stack" | "back" | "path".
+ *  Send it to the ROOT — the whole tree reads it from there.
+ ************************************************************/
+function yui_node_set_nav_mode(node, mode)
+{
+    return gobj_send_event(node, "EV_SET_NAV_MODE", {nav_mode: mode}, node);
+}
+
+function yui_node_nav_mode(node)
+{
+    return gobj_read_attr(tree_root_of(node), "nav_mode") || "stack";
+}
+
 /************************************************************
  *  Resolve a path of ids from a node ("" = the node itself).
  *  Returns null when any segment is missing — callers that mean
@@ -1484,6 +1582,7 @@ function create_gclass(gclass_name)
             ["EV_REMOVE_NODE",          ac_remove_node,         null],
             ["EV_SET_PROJECTION",       ac_set_projection,      null],
             ["EV_SET_CHROME_DEPTH",     ac_set_chrome_depth,    null],
+            ["EV_SET_NAV_MODE",         ac_set_nav_mode,        null],
             ["EV_SET_CONTENT",          ac_set_content,         null],
             ["EV_NODE_TREE_CHANGED",    ac_tree_changed,        null]
         ]],
@@ -1496,6 +1595,7 @@ function create_gclass(gclass_name)
             ["EV_REMOVE_NODE",          ac_remove_node,         null],
             ["EV_SET_PROJECTION",       ac_set_projection,      null],
             ["EV_SET_CHROME_DEPTH",     ac_set_chrome_depth,    null],
+            ["EV_SET_NAV_MODE",         ac_set_nav_mode,        null],
             ["EV_SET_CONTENT",          ac_set_content,         null],
             ["EV_NODE_TREE_CHANGED",    ac_tree_changed,        null]
         ]],
@@ -1508,6 +1608,7 @@ function create_gclass(gclass_name)
             ["EV_REMOVE_NODE",          ac_remove_node,         null],
             ["EV_SET_PROJECTION",       ac_set_projection,      null],
             ["EV_SET_CHROME_DEPTH",     ac_set_chrome_depth,    null],
+            ["EV_SET_NAV_MODE",         ac_set_nav_mode,        null],
             ["EV_SET_CONTENT",          ac_set_content,         null],
             ["EV_NODE_TREE_CHANGED",    ac_tree_changed,        null]
         ]]
@@ -1525,6 +1626,7 @@ function create_gclass(gclass_name)
         ["EV_REMOVE_NODE",          0],
         ["EV_SET_PROJECTION",       0],
         ["EV_SET_CHROME_DEPTH",     0],
+        ["EV_SET_NAV_MODE",         0],
         ["EV_SET_CONTENT",          0],
         ["EV_NODE_TREE_CHANGED",    0]
     ];
@@ -1565,6 +1667,8 @@ export {
     yui_node_set_projection,
     yui_node_set_content,
     yui_node_set_chrome_depth,
+    yui_node_set_nav_mode,
+    yui_node_nav_mode,
     yui_node_find,
     yui_node_route,
     yui_node_tree_version

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);
+});