@yuneta/gobj-ui 7.18.3 → 7.19.0

package/README.md

@@ -719,6 +719,41 @@ so it survived that — two light islands over a dark canvas.
 (all tooltips, so a host that has not defined them shows the key on hover and
 nothing else breaks).
 
+### Tabs opened at runtime, and the two decisions their url costs
+
+`yui_tab_routes.js`. A workspace whose tabs are opened by the operator —
+`/<ws>/<home>/<id>`, with whatever the tab is showing below it — pays for that
+url twice, and both apps in this family learned the same two lessons, one of
+them the hard way.
+
+**`yui_tab_split_subpath(subpath)` → `{id, tail}`.** On a cold load the tab's
+route does not exist yet: it is registered when the tab is opened, so a reload
+on `/<ws>/<home>/<id>/<tail>` resolves only as far as the workspace home and the
+shell hands the WHOLE rest over as the subpath — `<id>/<tail>`, not `<id>`.
+Reading all of it as the id matches nothing, and an app that then falls back to
+its first tab **answers a reload with somebody else's default**. It hides well:
+a bare tab route survives, because there the subpath IS the id, so only the deep
+case breaks and only for whoever reloads on one.
+
+Only the id segment is decoded. These ids are composite (`<node>`+`0x1F`+
+`<yuno>`, `<conn>`+`0x1F`+`<treedb>`) and reach the url percent-encoded, so
+decoding the whole tail first would turn an encoded slash inside an id into a
+separator and cut it in two.
+
+**`yui_tab_position_plan(prev_base, base, subpath, remembered)` →
+`{record, replay}`.** A tab's nav item is a FIXED route —
+`yui_shell_set_submenu()` registers it, and that route is where the view is
+mounted — so the position inside a tab cannot travel in the item and has to be
+replayed when the tab is entered again. "Entered again" is the whole subtlety:
+arriving at the root of the tab you were ALREADY in is the way OUT of whatever
+was open, and replaying the position there would make that button do nothing.
+
+**What is NOT here: the wiring.** One host restores on its transport's
+`EV_ON_OPEN`, another normalizes the route as it arrives, and both are right for
+what they know about when their tabs become real. These are the decisions, not
+the plumbing — which is also why they are pure and tested rather than three
+lines inside an action.
+
 ### Selecting several nodes, and moving them together
 
 In **edition** mode the graph has a real selection, not just "the node you

package/package.json

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

package/src/yui_tab_routes.js

@@ -0,0 +1,146 @@
+/***********************************************************************
+ *          yui_tab_routes.js
+ *
+ *      A workspace whose tabs are opened at RUNTIME, and the two
+ *      decisions its url costs.
+ *
+ *      The shape is always the same: a workspace home `/<ws>/<home>`
+ *      with one tab per thing the operator has opened, at
+ *      `/<ws>/<home>/<id>`, and whatever the tab is showing below
+ *      that. The agent console does it per node, the treedb browser
+ *      per (connection, treedb) — and both learned the same two
+ *      lessons, one of them the hard way.
+ *
+ *      1. ON A COLD LOAD THE TAB'S ROUTE DOES NOT EXIST YET.
+ *
+ *      It is registered when the tab is opened, so a reload on
+ *      `/<ws>/<home>/<id>/<what the tab was showing>` resolves only as
+ *      far as the workspace home, and the shell hands the WHOLE rest
+ *      over as the subpath: `<id>/<tail>`, not `<id>`. Reading all of
+ *      it as the id matches nothing, and an app that then falls back
+ *      to its first tab answers a reload with somebody else's default
+ *      — which is the one thing a reload must not do. It also hides
+ *      itself well: a BARE tab route survives, because there the
+ *      subpath IS the id.
+ *
+ *      `yui_tab_split_subpath()` is that split. Only the id segment is
+ *      decoded, and that is not a detail: these ids are composite
+ *      (`<node>` + 0x1F + `<yuno>`, `<conn>` + 0x1F + `<treedb>`) and
+ *      reach the url percent-encoded, so decoding the whole tail first
+ *      would turn an encoded slash inside an id into a separator and
+ *      cut it in two.
+ *
+ *      2. A TAB'S NAV ITEM IS A FIXED ROUTE.
+ *
+ *      `yui_shell_set_submenu()` registers it in the shell's item
+ *      index, and that route is where the tab's view is MOUNTED and
+ *      what a deep link resolves to. So the position inside a tab
+ *      cannot travel in the item — moving it would move the mount —
+ *      and has to be replayed when the tab is entered again.
+ *
+ *      "Entered again" is the whole subtlety, and it is why
+ *      `yui_tab_position_plan()` is a function with tests rather than
+ *      three lines inside an action: arriving at the root of the tab
+ *      you were ALREADY in is the way OUT of whatever was open (the
+ *      view's own back button), and replaying the position there would
+ *      make that button do nothing.
+ *
+ *      WHAT IS NOT HERE: the wiring. One host restores on its
+ *      transport's `EV_ON_OPEN`, another normalizes the route as it
+ *      arrives, and both are right for what they know about when their
+ *      tabs become real. These are the decisions, not the plumbing.
+ *
+ *          Copyright (c) 2026, ArtGins.
+ *          All Rights Reserved.
+ ***********************************************************************/
+
+/***************************************************************
+ *  Decode one url segment, or hand it back as it came.
+ *
+ *  A malformed percent escape throws, and an id that cannot be
+ *  decoded is still better read raw than not read at all: it
+ *  simply will not match an open tab, which is the honest answer.
+ ***************************************************************/
+function yui_tab_decode_id(segment)
+{
+    try {
+        return decodeURIComponent(String(segment || ""));
+    } catch(e) {
+        return String(segment || "");
+    }
+}
+
+/***************************************************************
+ *  yui_tab_split_subpath(subpath) -> {id, tail}
+ *
+ *      subpath   what the shell left below the workspace home
+ *
+ *      `id`      the tab's id, decoded
+ *      `tail`    what the tab was showing, untouched — it is the
+ *                tab's own business and travels with it
+ ***************************************************************/
+function yui_tab_split_subpath(subpath)
+{
+    let sub = String(subpath || "");
+
+    if(!sub) {
+        return {id: "", tail: ""};
+    }
+
+    let slash = sub.indexOf("/");
+    let raw_id = (slash < 0) ? sub : sub.slice(0, slash);
+    let tail   = (slash < 0) ? ""  : sub.slice(slash + 1);
+
+    return {id: yui_tab_decode_id(raw_id), tail: tail};
+}
+
+/***************************************************************
+ *  yui_tab_position_plan(prev_base, base, subpath, remembered)
+ *
+ *      prev_base   the tab base the previous route resolved to
+ *      base        the tab base this route resolves to
+ *      subpath     what is left of the url below `base`
+ *      remembered  the position last recorded for THIS tab
+ *
+ *      -> {record, replay}
+ *
+ *      `record` is the position to remember (null = leave it), and
+ *      `replay` the route to normalize to (null = stay). Never both:
+ *      a position is either being made or being restored.
+ ***************************************************************/
+function yui_tab_position_plan(prev_base, base, subpath, remembered)
+{
+    let inner = String(subpath || "");
+    let here = String(base || "");
+
+    if(!here) {
+        return {record: null, replay: null};
+    }
+
+    /*  Somewhere inside the tab: that IS the position.  */
+    if(inner) {
+        return {record: `${here}/${inner}`, replay: null};
+    }
+
+    /*  At the root of the tab we were already in: the operator walked
+     *  UP, on purpose, and that is a position too.  */
+    if(prev_base === here) {
+        return {record: here, replay: null};
+    }
+
+    /*  Entering the tab again: go back to where it was left, if that is
+     *  anywhere other than the root it would land on anyway.  */
+    let back = String(remembered || "");
+    if(back && back !== here) {
+        return {record: null, replay: back};
+    }
+
+    return {record: null, replay: null};
+}
+
+
+export {
+    yui_tab_decode_id,
+    yui_tab_split_subpath,
+    yui_tab_position_plan,
+};

package/src/yui_tab_routes.test.js

@@ -0,0 +1,138 @@
+/***********************************************************************
+ *          yui_tab_routes.test.js
+ *
+ *      The two decisions a runtime-opened tab costs its url.
+ *
+ *      The split is here because of what it cost to find: a reload on
+ *      a deep tab route answered with another tab's default for as
+ *      long as nobody reloaded on one.
+ *
+ *      The position plan is here because the case that makes it
+ *      non-trivial reads like a duplicate of the one above it: the
+ *      root of the tab you are already in is not the same event as
+ *      the root of a tab you are coming back to, and reading them as
+ *      one breaks the view's own way out of a topic.
+ ***********************************************************************/
+import { describe, test, expect } from "vitest";
+import {
+    yui_tab_decode_id,
+    yui_tab_split_subpath,
+    yui_tab_position_plan,
+} from "./yui_tab_routes.js";
+
+const US = String.fromCharCode(31);   /*  the composite-id separator  */
+
+
+describe("yui_tab_split_subpath", () => {
+    test("a bare tab tail is all id", () => {
+        expect(yui_tab_split_subpath("wattyzer")).toEqual({id: "wattyzer", tail: ""});
+    });
+
+    test("a deep tail keeps the id and hands the rest back", () => {
+        expect(yui_tab_split_subpath("wattyzer/treedb_authzs/__graphs__"))
+            .toEqual({id: "wattyzer", tail: "treedb_authzs/__graphs__"});
+    });
+
+    test("a composite id survives the url it travelled in", () => {
+        /*  0x1F joins the two halves of these ids and reaches the url
+         *  percent-encoded.  */
+        expect(yui_tab_split_subpath("yunovatios-controlador%1F1630/treedb_authzs/__graphs__"))
+            .toEqual({id: "yunovatios-controlador" + US + "1630",
+                      tail: "treedb_authzs/__graphs__"});
+    });
+
+    test("an encoded slash inside the id stays inside the id", () => {
+        /*  Which is why the WHOLE tail must not be decoded first: that
+         *  would turn this %2F into a separator and cut the id in two.  */
+        expect(yui_tab_split_subpath("a%2Fb/treedb_x"))
+            .toEqual({id: "a/b", tail: "treedb_x"});
+    });
+
+    test("a malformed escape is taken as it came, not thrown", () => {
+        expect(yui_tab_split_subpath("%E0%A4%A/treedb_x"))
+            .toEqual({id: "%E0%A4%A", tail: "treedb_x"});
+    });
+
+    test("nothing in, nothing out", () => {
+        expect(yui_tab_split_subpath("")).toEqual({id: "", tail: ""});
+        expect(yui_tab_split_subpath(null)).toEqual({id: "", tail: ""});
+        expect(yui_tab_split_subpath(undefined)).toEqual({id: "", tail: ""});
+    });
+});
+
+describe("yui_tab_decode_id", () => {
+    test("decodes, and survives what cannot be decoded", () => {
+        expect(yui_tab_decode_id("a%2Fb")).toBe("a/b");
+        expect(yui_tab_decode_id("%E0%A4%A")).toBe("%E0%A4%A");
+        expect(yui_tab_decode_id("")).toBe("");
+        expect(yui_tab_decode_id(null)).toBe("");
+    });
+});
+
+const A = "/topics/db/conn1%1Fdb1";
+const B = "/topics/db/conn1%1Fdb2";
+
+
+describe("inside a tab", () => {
+    test("a position is recorded, and nothing is replayed", () => {
+        expect(yui_tab_position_plan(A, A, "users", "")).toEqual(
+            {record: `${A}/users`, replay: null});
+    });
+
+    test("a deeper position is recorded whole", () => {
+        expect(yui_tab_position_plan(A, A, "users/info", `${A}/users`)).toEqual(
+            {record: `${A}/users/info`, replay: null});
+    });
+
+    test("arriving deep from ANOTHER tab records too — the url won", () => {
+        expect(yui_tab_position_plan(B, A, "users", `${A}/roles`)).toEqual(
+            {record: `${A}/users`, replay: null});
+    });
+});
+
+describe("the root of the tab you were already in", () => {
+    test("is the way OUT of a topic, so it records and never replays", () => {
+        /*  The view's own "back to Topics" button lands here. Replaying
+            the position would make that button do nothing at all.  */
+        expect(yui_tab_position_plan(A, A, "", `${A}/users`)).toEqual(
+            {record: A, replay: null});
+    });
+});
+
+describe("the root of a tab you are coming back to", () => {
+    test("replays what was left open", () => {
+        expect(yui_tab_position_plan(B, A, "", `${A}/users`)).toEqual(
+            {record: null, replay: `${A}/users`});
+    });
+
+    test("...including from OUTSIDE the tabs — the picker, the settings", () => {
+        /*  The caller says "no tab" with an empty prev_base. It must, or a
+         *  return from Select reads as the walk UP that records the root
+         *  (and the tab comes back on its cards, its position gone).  */
+        expect(yui_tab_position_plan("", A, "", `${A}/users`)).toEqual(
+            {record: null, replay: `${A}/users`});
+    });
+
+    test("...and does nothing when the tab was left at its own root", () => {
+        expect(yui_tab_position_plan(B, A, "", A)).toEqual({record: null, replay: null});
+    });
+
+    test("...or when it has never been visited", () => {
+        expect(yui_tab_position_plan(B, A, "", "")).toEqual({record: null, replay: null});
+        expect(yui_tab_position_plan("", A, "", undefined)).toEqual({record: null, replay: null});
+    });
+});
+
+describe("edges", () => {
+    test("no base is no decision", () => {
+        expect(yui_tab_position_plan(A, "", "users", A)).toEqual({record: null, replay: null});
+    });
+
+    test("record and replay are never both set", () => {
+        for(const args of [[A, A, "users", A], [A, A, "", A], [B, A, "", `${A}/x`],
+                           [B, A, "", ""], ["", A, "", ""]]) {
+            const plan = yui_tab_position_plan(...args);
+            expect(!!(plan.record && plan.replay)).toBe(false);
+        }
+    });
+});