@yuneta/gobj-ui 5.2.0 → 5.3.0

package/src/c_yui_shell.css

@@ -271,6 +271,24 @@
     opacity: 0.5;
 }
 
+/*--- breadcrumb: the path as one line (C_YUI_NODE's `projection.path`) ---*/
+.yui-nav-breadcrumb {
+    padding: 0.35rem 0.75rem;
+}
+.yui-nav-breadcrumb .yui-nav-crumb {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.35rem;
+}
+/*  Bulma marks the last crumb with li.is-active and greys it; the
+ *  active_route highlight lands there, so "where I am" reads as the end
+ *  of the trail instead of as one more link. */
+.yui-nav-breadcrumb li.is-active > a {
+    color: var(--bulma-text-strong, #363636);
+    font-weight: 600;
+    pointer-events: none;
+}
+
 /*--- backbar (mobile "← <section>" back-to-index, submenu.index) ---*/
 .yui-nav-backbar {
     display: flex;

package/src/c_yui_shell.js

@@ -100,6 +100,7 @@ SDATA(data_type_t.DTP_POINTER,  "subscriber",     0,  null,  "Subscriber of outp
 SDATA(data_type_t.DTP_JSON,     "config",         0,  null,  "Shell declarative config (zones, menu, stages, toolbar)"),
 SDATA(data_type_t.DTP_STRING,   "default_route",  0,  "",    "Fallback route if hash is empty"),
 SDATA(data_type_t.DTP_STRING,   "current_route",  0,  "",    "Current active route"),
+SDATA(data_type_t.DTP_BOOLEAN,  "remember_section_position", 0, false, "A menu click returns to the last position visited inside that section"),
 SDATA(data_type_t.DTP_BOOLEAN,  "use_hash",       0,  true,  "Bind navigation to window.location.hash"),
 SDATA(data_type_t.DTP_POINTER,  "mount_element",  0,  null,  "HTMLElement to mount shell into (default: document.body)"),
 
@@ -113,6 +114,9 @@ let PRIVATE_DATA = {
     stages:          {},
     navs:            [],
     item_index:      {},
+    /*  Section route -> last position visited inside it.  Mirrors the
+     *  url for the duration of the page; see remember_position(). */
+    section_pos:     {},
     /*  Sub-route contributor registry (ROUTING.md): a mounted view
      *  declares the deep, view-owned children of its base route
      *  (topics, /info, /schema, focus topics — subpaths that are NOT
@@ -225,6 +229,14 @@ function mt_start(gobj)
         return;
     }
 
+    /*  Declarative sugar over the attr, which stays the runtime truth:
+     *  an app can flip it later without rebuilding the shell. */
+    let shell_cfg = config.shell || {};
+    if(typeof shell_cfg.remember_section_position === "boolean") {
+        gobj_write_attr(gobj, "remember_section_position",
+            shell_cfg.remember_section_position);
+    }
+
     build_item_index(gobj, config);
     instantiate_menus(gobj, config);
     build_toolbar(gobj, config);
@@ -838,6 +850,76 @@ function build_item_index(gobj, config)
             };
         }
     }
+
+    index_node_tree(gobj, config);
+}
+
+/************************************************************
+ *  config.shell.tree — the navigation is a TREE OF NODES and
+ *  its root is where the shell's own root used to be.
+ *
+ *  The shell keeps what it is good at, the SPACE: zones, layers,
+ *  stages, toolbar, overlays, theme, breakpoints.  It stops being
+ *  the owner of the menu: the root C_YUI_NODE holds the primary
+ *  options as its children and projects them into zones (a left
+ *  rail, a bottom bar) exactly as `menu.primary.render` used to
+ *  say — a per-zone projection is still a projection.
+ *
+ *  All this does is synthesize ONE route entry.  `owns_subtree`
+ *  lets it match as the ancestor of everything (route_resolver),
+ *  so the whole url space below it is the tree's `subpath` and no
+ *  route table grows.  The unknown-route diagnostic is not lost:
+ *  it moves to the node that knows the names of its children.
+ *
+ *  `menu` and `tree` are not exclusive — an app may declare both
+ *  while it migrates — but a tree at "/" owns every route no
+ *  other entry claims, which is the point.
+ ************************************************************/
+function index_node_tree(gobj, config)
+{
+    let priv = gobj.priv;
+    let tree = (config.shell && config.shell.tree) || null;
+
+    if(!tree) {
+        return;
+    }
+    if(!is_object(tree)) {
+        log_error("C_YUI_SHELL: config.shell.tree must be an object");
+        return;
+    }
+
+    let base_route = normalize_route(tree.base_route || "/");
+
+    /*  JSON has no comments and these configs annotate themselves with
+     *  sibling `_name_comment` keys (the established idiom — see
+     *  app_config.json).  They are documentation, not attrs: handing
+     *  them to gobj_create is an "Attribute NOT FOUND" per comment. */
+    let kw = {};
+    for(let key of Object.keys(tree)) {
+        if(key.charAt(0) === "_" || key === "stage") {
+            continue;
+        }
+        kw[key] = tree[key];
+    }
+    kw.base_route = base_route;
+    if(!kw.node_id) {
+        kw.node_id = "root";
+    }
+
+    let prev = priv.item_index[base_route];
+    priv.item_index[base_route] = {
+        item:        (prev && prev.item) || null,
+        parent_item: (prev && prev.parent_item) || null,
+        stage:       tree.stage || "main",
+        menu_id:     (prev && prev.menu_id) || "",
+        target: {
+            stage:        tree.stage || "main",
+            gclass:       "C_YUI_NODE",
+            lifecycle:    "keep_alive",
+            owns_subtree: true,
+            kw:           kw
+        }
+    };
 }
 
 /************************************************************
@@ -1365,6 +1447,7 @@ function navigate_to(gobj, route, depth, no_drain)
 
     stage.active_route = matched_route;
     gobj_write_attr(gobj, "current_route", route);
+    remember_position(gobj, route);
 
     /*  Show/hide secondary navs according to parent item */
     update_secondary_nav_visibility(gobj, entry);
@@ -2234,7 +2317,11 @@ function pop_escape(gobj, handler)
  *    - navigate_to() drains (closes) every registered overlay when the
  *      RESTING route changes — overlays are transient and do not
  *      outlive the view they float above.  An action route or a
- *      subpath-only move keeps them open.
+ *      subpath-only move keeps them open.  An overlay registered with
+ *      `keep_on_navigate` opts OUT of the drain: it is a NAVIGATION
+ *      PANEL, not a thing floating above one view — the site map is
+ *      the reference case, where every row click is meant to move the
+ *      user with the panel still up.
  *    - a drained/buried entry is left INERT: overlay_dismissed only
  *      history.back()s when the marker is the CURRENT history entry
  *      (adjacent, so the back() is invisible) — never over real route
@@ -2254,14 +2341,25 @@ function drain_overlays(gobj)
     if(!priv || !priv.overlay_stack) {
         return;
     }
+    /*  Survivors keep their relative order: the stack is a LIFO and a
+     *  panel that outlives the drain must stay where it was, or Escape
+     *  would start closing overlays in an order the user never built. */
+    let kept = [];
     while(priv.overlay_stack.length > 0) {
         let entry = priv.overlay_stack.pop();
+        if(entry.keep_on_navigate) {
+            kept.unshift(entry);
+            continue;
+        }
         try {
             entry.close();
         } catch(e) {
             log_warning(`C_YUI_SHELL: overlay close on navigation failed: ${e}`);
         }
     }
+    for(let entry of kept) {
+        priv.overlay_stack.push(entry);
+    }
 }
 
 /*  A URL rewrite moved the entry `st` tags to `hash`.  When `st` is a live
@@ -2279,7 +2377,7 @@ function retag_overlay_hash(gobj, st, hash)
     }
 }
 
-function push_overlay_history(gobj, close)
+function push_overlay_history(gobj, close, opts)
 {
     let priv = gobj.priv;
     if(!priv || !priv.overlay_stack || !gobj_read_attr(gobj, "use_hash")) {
@@ -2547,6 +2645,11 @@ function ac_nav_clicked(gobj, event, kw, src)
         return 0;
     }
 
+    /*  A click on a section returns to where the user was inside it.
+     *  It stays a PUSH: they chose to go there, so Back must bring them
+     *  back — only WHICH spot inside was decided for them. */
+    route = remembered_position(gobj, route);
+
     /*  When hash routing is on, let the hash drive navigate_to() — that
      *  way back/forward buttons and programmatic hash changes all flow
      *  through the same code path.  Otherwise call navigate_to directly.
@@ -2852,6 +2955,77 @@ function register_c_yui_shell()
  *  bottom of the file to keep the skeleton layout intact.
  ***************************************************************/
 
+/************************************************************
+ *  Last position inside each section — the routes a MENU CLICK
+ *  returns to (`remember_section_position`).
+ *
+ *  A section is a menu item's route; anything under it is a
+ *  position inside it.  The memory MIRRORS the url and is never
+ *  the authority for it (ROUTING.md §3): it lives for the page,
+ *  not on disk, and only a click on the section's own menu item
+ *  consults it.  Typing the url, a deep link, Back/Forward and
+ *  programmatic navigation all land exactly where they say —
+ *  which is the property that would be lost if this were stored
+ *  and applied everywhere.
+ ************************************************************/
+function remember_position(gobj, route)
+{
+    let priv = gobj.priv;
+
+    if(!gobj_read_attr(gobj, "remember_section_position")) {
+        return;
+    }
+    for(let section of Object.keys(priv.item_index)) {
+        if(section === "/") {
+            continue;
+        }
+        /*  The section's own root IS a position inside it.  Recording it
+         *  is what keeps the memory a MIRROR: after deliberately resting
+         *  at /cards, a click on Cards must land there, not teleport
+         *  back into the deep spot visited before. */
+        if(route === section || route.indexOf(section + "/") === 0) {
+            priv.section_pos[section] = route;
+        }
+    }
+}
+
+/************************************************************
+ *  Where a click on `route` should actually land: the last
+ *  position inside it, when there is one and it still resolves.
+ *  A remembered route whose node has since disappeared is
+ *  dropped rather than followed — the tree is allowed to change
+ *  under a memory.
+ ************************************************************/
+function remembered_position(gobj, route)
+{
+    let priv = gobj.priv;
+
+    if(!gobj_read_attr(gobj, "remember_section_position")) {
+        return route;
+    }
+
+    /*  Only a click that ENTERS the section from outside it restores a
+     *  position.  From INSIDE — a backbar going up to the index, a tab
+     *  strip, the rail item of the section you are already in — the
+     *  click means the route it names and nothing else.  Without this,
+     *  "← Section index" put the user back on the leaf they were
+     *  leaving and the control looked dead. */
+    let current = gobj_read_attr(gobj, "current_route") || "";
+    if(current === route || current.indexOf(route + "/") === 0) {
+        return route;
+    }
+    let last = priv.section_pos[route];
+    if(!last || last === route) {
+        return route;
+    }
+    let r = resolve_route(priv.item_index, last);
+    if(!r || !r.entry || !r.entry.target) {
+        delete priv.section_pos[route];
+        return route;
+    }
+    return last;
+}
+
 /************************************************************
  *  Resolve the shell that governs `gobj`: the nearest
  *  C_YUI_SHELL ancestor, else the last shell created on the
@@ -2871,6 +3045,29 @@ function yui_shell_of(gobj)
     return __last_shell__;
 }
 
+/************************************************************
+ *  The DOM of a zone, for whoever projects into the space.
+ *
+ *  The shell owns the space; a root C_YUI_NODE that projects its
+ *  children into a left rail or a bottom bar needs the element to
+ *  mount them in.  Null (and a warning) for an unknown zone —
+ *  silently projecting into nowhere is how a menu disappears with
+ *  no explanation.
+ ************************************************************/
+function yui_shell_zone(shell_gobj, zone_id)
+{
+    if(!shell_gobj || !shell_gobj.priv || !shell_gobj.priv.zones) {
+        log_warning(`C_YUI_SHELL: yui_shell_zone — no shell`);
+        return null;
+    }
+    let $zone = shell_gobj.priv.zones[zone_id];
+    if(!$zone) {
+        log_warning(`C_YUI_SHELL: yui_shell_zone — unknown zone '${zone_id}'`);
+        return null;
+    }
+    return $zone;
+}
+
 /************************************************************
  *  Programmatic navigation.
  *
@@ -3000,9 +3197,13 @@ function yui_shell_pop_escape(shell_gobj, handler)
  *  `close_fn` is what the Back button invokes to tear the overlay down.
  *  Returns null when history integration is off (no shell / use_hash) —
  *  callers just skip the paired yui_shell_overlay_dismissed then. */
-function yui_shell_register_overlay(shell_gobj, close_fn)
+/*  `opts.keep_on_navigate` — this overlay is a navigation PANEL and
+ *  survives a resting-route change (see drain_overlays).  Default off:
+ *  an overlay is transient, and outliving the view it floats above is
+ *  the exception that has to be asked for. */
+function yui_shell_register_overlay(shell_gobj, close_fn, opts)
 {
-    return push_overlay_history(shell_gobj, close_fn);
+    return push_overlay_history(shell_gobj, close_fn, opts);
 }
 function yui_shell_overlay_dismissed(shell_gobj, overlay)
 {
@@ -3160,6 +3361,7 @@ function yui_shell_close_dropdown(shell_gobj)
 export {
     register_c_yui_shell,
     yui_shell_of,
+    yui_shell_zone,
     yui_shell_navigate,
     yui_shell_nav_map,
     yui_shell_set_sub_routes,

package/src/c_yui_treedb_schema.js

@@ -20,6 +20,7 @@ import {
     log_error,
     gobj_read_pointer_attr,
     gobj_subscribe_event,
+    gobj_send_event,
     gobj_parent,
     gobj_read_attr,
     createElement2,

package/src/c_yui_window.js

@@ -107,6 +107,7 @@ SDATA(data_type_t.DTP_POINTER,  "focus",        0,  null,   "Brings focus to the
 SDATA(data_type_t.DTP_BOOLEAN,  "modal",        0,  false,  "Enable modal mode"),
 SDATA(data_type_t.DTP_BOOLEAN,  "keyboard",     0,  true,   "Close window on ESC if not modal"),
 SDATA(data_type_t.DTP_BOOLEAN,  "back_dismissable", 0, true, "Browser Back closes this window (floating overlays only; ignored when it has a `manager`)"),
+SDATA(data_type_t.DTP_BOOLEAN,  "keep_on_navigate", 0, false, "This window is a navigation PANEL: a route change does not close it"),
 SDATA(data_type_t.DTP_POINTER,  "back_overlay", 0,  null,   "Internal: overlay-history entry (Back-button integration)"),
 SDATA(data_type_t.DTP_POINTER,  "$container",   0,  null,   "Internal: Window container element"),
 SDATA(data_type_t.DTP_STRING,   "window_id",    0,  "",     "Internal: Window ID"),
@@ -183,12 +184,16 @@ function mt_create(gobj)
     } else if(gobj_read_bool_attr(gobj, "back_dismissable")) {
         /*  Floating overlay window (no dock manager): the browser Back
          *  button closes it, like a modal/popup.  Dock-managed windows
-         *  are persistent workspace surfaces and are left out.  Retired
-         *  in mt_destroy (covers every teardown path). */
+         *  are persistent workspace surfaces and are left out — which
+         *  is also why a navigation panel prefers a manager, and falls
+         *  back to `keep_on_navigate` when the app has no dock.
+         *  Retired in mt_destroy (covers every teardown path). */
         let shell = yui_shell_of(gobj);
         if(shell) {
             let overlay = yui_shell_register_overlay(
-                shell, function() { close_window(gobj); }
+                shell,
+                function() { close_window(gobj); },
+                {keep_on_navigate: gobj_read_bool_attr(gobj, "keep_on_navigate")}
             );
             gobj_write_attr(gobj, "back_overlay", overlay);
         }