@yuneta/gobj-ui 7.23.170 → 7.23.172

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yuneta/gobj-ui",
-  "version": "7.23.170",
+  "version": "7.23.172",
   "type": "module",
   "main": "dist/gobj-ui.cjs.js",
   "module": "dist/gobj-ui.es.js",
@@ -30,13 +30,13 @@
   "devDependencies": {
     "@rollup/plugin-terser": "^1.0.0",
     "@vitest/coverage-v8": "^4.1.10",
-    "@yuneta/gobj-js": "^7.21.0",
+    "@yuneta/gobj-js": "^7.22.0",
     "vite": "^8.2.1",
     "vitest": "^4.1.10"
   },
   "peerDependencies": {
     "@antv/g6": "^5.1.0",
-    "@yuneta/gobj-js": "^7.16.6",
+    "@yuneta/gobj-js": "^7.22.0",
     "bulma": "^1.0.4",
     "i18next": "^26.3.6",
     "maplibre-gl": "^6.4.1",

package/src/c_yui_treedb_schema.js

@@ -68,6 +68,7 @@ import {
     yui_graph_update_zoom,
 } from "./yui_graph_camera.js";
 import {ensure_pinch_zoom_patch} from "./g6_touch_gestures.js";
+import {col_key_roles} from "./treedb_topic_keys.js";
 
 import {getStrokeColor} from "./lib_graph.js";
 
@@ -260,12 +261,20 @@ function hook_mark(type)
  *      (↖)  1 fkey      (1 parent)
  *      [↖]  n fkeys     (n parents)
  *      {↖}  N fkeys     (N parents)
+ *      (2)  a secondary key (pkey2)
+ *      (t)  the time key (tkey)
  *      *    required
  *      #    the primary key
  *
- *   A column can be BOTH hook and fkey, so the flags are read
- *   here rather than through treedb_get_field_desc's single
- *   `type`, which keeps only the last flag it saw.
+ *   The key marks lead the mark column, and a pkey2 is drawn in
+ *   bold like the pkey: a topic with secondary keys keeps several
+ *   instances under one id, which is the first thing to know
+ *   about it. `(t)` is new to the notation: the literals' legend
+ *   carries it too.
+ *
+ *   The flags are read here rather than through
+ *   treedb_get_field_desc's single `type`, which keeps only the
+ *   last flag it saw.
  ************************************************************/
 function schema_rows(desc)
 {
@@ -280,6 +289,14 @@ function schema_rows(desc)
         let flags = Array.isArray(col.flag)? col.flag : [];
         let is_hook = flags.indexOf("hook") >= 0;
         let is_fkey = flags.indexOf("fkey") >= 0;
+        let roles = col_key_roles(desc, col.id);
+        let key_marks = [];
+        if(roles.includes("pkey2")) {
+            key_marks.push("(2)");
+        }
+        if(roles.includes("tkey")) {
+            key_marks.push("(t)");
+        }
         let mark = "";
         if(is_hook) {
             mark = hook_mark(col.type);
@@ -290,13 +307,17 @@ function schema_rows(desc)
                                            .replace(")", "↖)");
             mark = mark? (mark + " " + fmark) : fmark;
         }
+        if(key_marks.length) {
+            mark = mark? (key_marks.join(" ") + " " + mark) : key_marks.join(" ");
+        }
         rows.push({
             name:     col.id,
             type:     col.type || "",
             mark:     mark,
             is_hook:  is_hook,
             is_fkey:  is_fkey,
-            is_pkey:  (col.id === desc.pkey),
+            is_pkey:  roles.includes("pkey"),
+            is_pkey2: roles.includes("pkey2"),
             required: (flags.indexOf("required") >= 0 || flags.indexOf("notnull") >= 0),
         });
     }
@@ -367,7 +388,7 @@ function build_card_innerHTML(topic, rows, color, dark)
     let rows_html = "";
     for(let row of rows) {
         let lead = row.is_pkey? "#" : (row.required? "*" : "");
-        let name_weight = (row.is_pkey || row.required)? "600" : "400";
+        let name_weight = (row.is_pkey || row.is_pkey2)? "700" : (row.required? "600" : "400");
         let name_color = (row.is_hook || row.is_fkey)? title_color : text_color;
         rows_html +=
 `    <div class="TREEDB_SCHEMA_FIELD" style="

package/src/c_yui_treedb_topics.css

@@ -61,6 +61,9 @@
     text-overflow: ellipsis;
     color: var(--bulma-text, inherit);
 }
+.TREEDB_TOPIC_CARD_PKEY2S .TREEDB_TOPIC_CARD_REL_LIST {
+    font-weight: 600;
+}
 .TREEDB_TOPIC_CARD_ACTIONS {
     display: flex;
     justify-content: center;

package/src/c_yui_treedb_topics.js

@@ -3,7 +3,7 @@
  *
  *          Management of TreeDB's topics with Bulma tabs
  *
- *          Copyright (c) 2025, ArtGins.
+ *          Copyright (c) 2025-2026, ArtGins.
  *          All Rights Reserved.
  ***********************************************************************/
 
@@ -66,6 +66,9 @@ import {
 } from "./c_yui_shell.js";
 import {nodes_answer} from "./nodes_answer.js";
 import {yui_toolbar_icon} from "./yui_toolbar.js";
+import {
+    desc_pkey2s, desc_tkey, col_key_roles, system_flag_names
+} from "./treedb_topic_keys.js";
 
 import {t} from "i18next";
 
@@ -688,6 +691,17 @@ function topic_card_meta(desc)
     ]]);
     meta.push(['div', {class: 'TREEDB_TOPIC_CARD_META'}, head]);
 
+    /*  The secondary keys come before the relations: they change what
+     *  a record of this topic IS (several instances under one id).  */
+    let pkey2s = desc_pkey2s(desc);
+    if(pkey2s.length) {
+        let list = pkey2s.join(", ");
+        meta.push(['div', {class: 'TREEDB_TOPIC_CARD_REL TREEDB_TOPIC_CARD_PKEY2S', title: list}, [
+            ['span', {class: 'TREEDB_TOPIC_CARD_REL_LABEL', i18n: 'pkey2s'}, 'pkey2s'],
+            ['span', {class: 'TREEDB_TOPIC_CARD_REL_LIST'}, list]
+        ]]);
+    }
+
     let relation = (cls, key, arrow, names) => {
         let list = names.join(", ");
         return ['div', {class: `TREEDB_TOPIC_CARD_REL ${cls}`, title: list}, [
@@ -1021,9 +1035,15 @@ function show_topic_info(gobj, topic)
 
 /************************************************************
  *  Build the read-only topic-info panel from a topic desc: the
- *  topic name, its pkey, and a table of columns (name / type /
+ *  topic name, its KEYS, and a table of columns (name / type /
  *  key relationship). Everything is guarded — a malformed desc
  *  renders a shorter panel, never throws.
+ *
+ *  The keys are what an operator has to know before touching a
+ *  record, so they are all said, and the empty ones too: a
+ *  topic with `pkey2s` keeps several instances under one id,
+ *  and an empty `tkey` means the time of a record is the time
+ *  it was appended -- a row missing is not the same as "none".
  ************************************************************/
 function build_topic_info_panel(gobj, $info, topic, desc)
 {
@@ -1032,38 +1052,39 @@ function build_topic_info_panel(gobj, $info, topic, desc)
     }
 
     let pkey = desc.pkey || "";
+    let pkey2s = desc_pkey2s(desc);
+    let tkey = desc_tkey(desc);
 
-    /*  Topic metadata (version matters to the operator): version /
-     *  system / pkey / tkey. Each row is shown only when its value is
-     *  present; the version is emphasised as a tag. */
-    let fmt_flag = (v) => {
-        if(is_array(v)) {
-            return v.join(", ");
-        }
-        if(is_object(v)) {
-            return Object.keys(v).join(", ");
-        }
-        return (v === undefined || v === null) ? "" : String(v);
-    };
+    /*  Topic metadata: version / system / pkey / pkey2s / tkey. The
+     *  version and the secondary keys are emphasised as tags. */
     let $meta = [];
-    let push_meta = (key, value, highlight) => {
-        if(value === undefined || value === null || value === "") {
-            return;
-        }
-        let $val = highlight
-            ? ["span", {class: "tag is-info"}, `${value}`]
-            : ["code", {}, `${value}`];
+    let push_meta = (key, $val) => {
         $meta.push(
-            ["tr", {}, [
+            ["tr", {class: `TREEDB_TOPIC_INFO_${key.toUpperCase()}`}, [
                 ["th", {i18n: key, style: "width:11rem;"}, key],
                 ["td", {}, [$val]]
             ]]
         );
     };
-    push_meta("version", desc.topic_version, true);
-    push_meta("system", fmt_flag(desc.system_flag));
-    push_meta("pkey", pkey);
-    push_meta("tkey", desc.tkey);
+    if(desc.topic_version !== undefined && desc.topic_version !== null && desc.topic_version !== "") {
+        push_meta("version", ["span", {class: "tag is-info"}, `${desc.topic_version}`]);
+    }
+    let sf_names = system_flag_names(desc.system_flag);
+    if(sf_names.length > 0) {
+        push_meta("system", ["code", {title: `${desc.system_flag}`}, sf_names.join(" | ")]);
+    }
+    if(pkey) {
+        push_meta("pkey", ["code", {}, pkey]);
+    }
+    if(pkey2s.length > 0) {
+        push_meta("pkey2s", ["span", {class: "tags"},
+            pkey2s.map(name => ["span", {class: "tag is-warning"}, name])
+        ]);
+    }
+    push_meta("tkey", tkey
+        ? ["code", {}, tkey]
+        : ["span", {class: "has-text-grey", i18n: "append time"}, "append time"]
+    );
 
     let $rows = [];
     let cols = is_array(desc.cols) ? desc.cols : [];
@@ -1072,19 +1093,20 @@ function build_topic_info_panel(gobj, $info, topic, desc)
             continue;
         }
         let type = col.type || (is_array(col.flag) ? col.flag.join(", ") : (col.flag || ""));
-        let rel = "";
-        if(col.id === pkey) {
-            rel = "pkey";
-        } else if(is_object(col.fkey)) {
-            rel = "→ " + Object.keys(col.fkey).join(", ");
+        let roles = col_key_roles(desc, col.id);
+        let parts = roles.slice();
+        if(is_object(col.fkey)) {
+            parts.push("→ " + Object.keys(col.fkey).join(", "));
         } else if(is_object(col.hook)) {
-            rel = "hook → " + Object.keys(col.hook).join(", ");
+            parts.push("hook → " + Object.keys(col.hook).join(", "));
         }
+        let rel = parts.join(" · ");
+        let is_key = roles.length > 0;
         $rows.push(
-            ["tr", {}, [
-                ["td", {}, [["code", {}, `${col.id}`]]],
+            ["tr", is_key ? {class: "TREEDB_TOPIC_INFO_KEY_COL"} : {}, [
+                ["td", {}, [["code", is_key ? {class: "has-text-weight-bold"} : {}, `${col.id}`]]],
                 ["td", {}, `${type}`],
-                ["td", {}, `${rel}`]
+                ["td", is_key ? {class: "has-text-weight-semibold"} : {}, `${rel}`]
             ]]
         );
     }

package/src/treedb_topic_keys.js

@@ -0,0 +1,122 @@
+/***********************************************************************
+ *          treedb_topic_keys.js
+ *
+ *      The KEYS of a treedb topic, read from its desc: the pkey, the
+ *      secondary keys (`pkey2s`) and the time key (`tkey`), plus the
+ *      names behind its `system_flag` number.
+ *
+ *      Every view that describes a topic -- the schema diagram, the
+ *      topic-info panel, the topic cards -- must say them, and say them
+ *      the same way. A topic with `pkey2s` is not a topic with one more
+ *      column: one id holds several INSTANCES, an update has to carry
+ *      the pkey2 or it lands on the primary, and `delete-instance`
+ *      exists. `tkey` names where the time of every record comes from.
+ *      The views said neither, so this is where they ask.
+ *
+ *      Pure, so it is tested with no DOM.
+ *
+ *          Copyright (c) 2026, ArtGins.
+ *          All Rights Reserved.
+ ***********************************************************************/
+import {topic_pkey2s} from "./schema_model.js";
+
+/*  The names of the system_flag bits, in bit order: the `sf_names`
+ *  table of timeranger2.c, which the C enum points at. Keep the two in
+ *  step -- an empty slot is a bit with no name.  */
+const SF_NAMES = [
+    "sf_string_key",            // 0x0001
+    "sf_rowid_key",             // 0x0002
+    "sf_int_key",               // 0x0004
+    "",                         // 0x0008
+    "sf_zip_record",            // 0x0010
+    "sf_cipher_record",         // 0x0020
+    "",                         // 0x0040
+    "",                         // 0x0080
+    "sf_t_ms",                  // 0x0100
+    "sf_tm_ms",                 // 0x0200
+    "sf_deleted_instance",      // 0x0400
+    "sf_immutable_record",      // 0x0800
+    "sf_loading_from_disk",     // 0x1000
+    "",                         // 0x2000
+    "",                         // 0x4000
+    "",                         // 0x8000
+];
+
+
+/************************************************************
+ *  The secondary keys of a topic, always a list. The desc
+ *  carries a list; a schema literal may declare a bare
+ *  string.
+ ************************************************************/
+function desc_pkey2s(desc)
+{
+    return topic_pkey2s(desc);
+}
+
+/************************************************************
+ *  The time key of a topic, "" when it has none -- and then
+ *  the time of a record is the time it was appended.
+ ************************************************************/
+function desc_tkey(desc)
+{
+    let tkey = desc ? desc.tkey : "";
+    return (typeof tkey === "string") ? tkey : "";
+}
+
+/************************************************************
+ *  Which keys of its topic a column IS, in the order the
+ *  views print them: "pkey", "pkey2", "tkey". Empty for a
+ *  column that is none.
+ ************************************************************/
+function col_key_roles(desc, col_id)
+{
+    let roles = [];
+    if(!desc || typeof col_id !== "string" || col_id.length === 0) {
+        return roles;
+    }
+    if(col_id === (desc.pkey || "id")) {
+        roles.push("pkey");
+    }
+    if(desc_pkey2s(desc).includes(col_id)) {
+        roles.push("pkey2");
+    }
+    if(desc_tkey(desc) === col_id) {
+        roles.push("tkey");
+    }
+    return roles;
+}
+
+/************************************************************
+ *  The names of a system_flag. The desc carries the NUMBER
+ *  (`1`), a schema literal carries the names
+ *  ("sf_string_key|sf_t_ms"); both come back as a list. A
+ *  set bit with no name is shown by its value, never
+ *  dropped.
+ ************************************************************/
+function system_flag_names(system_flag)
+{
+    if(Array.isArray(system_flag)) {
+        return system_flag.filter(n => typeof n === "string" && n.length > 0);
+    }
+    if(typeof system_flag === "string") {
+        return system_flag.split(/[|,]/).map(n => n.trim()).filter(n => n.length > 0);
+    }
+    if(typeof system_flag !== "number" || !Number.isInteger(system_flag) || system_flag <= 0) {
+        return [];
+    }
+    let names = [];
+    for(let bit = 0; bit < SF_NAMES.length; bit++) {
+        let mask = 1 << bit;
+        if(system_flag & mask) {
+            names.push(SF_NAMES[bit] || `0x${mask.toString(16).padStart(4, "0")}`);
+        }
+    }
+    return names;
+}
+
+export {
+    desc_pkey2s,
+    desc_tkey,
+    col_key_roles,
+    system_flag_names,
+};

package/src/treedb_topic_keys.test.js

@@ -0,0 +1,79 @@
+/***********************************************************************
+ *          treedb_topic_keys.test.js
+ *
+ *      The keys of a topic, read from its desc, pinned: the shapes the
+ *      backend and the schema literals really send.
+ ***********************************************************************/
+import { describe, test, expect } from "vitest";
+import {
+    desc_pkey2s, desc_tkey, col_key_roles, system_flag_names
+} from "./treedb_topic_keys.js";
+
+/*  The `binaries` topic of treedb_yuneta_agent, as `descs` answers it.  */
+const BINARIES = {
+    topic_name: "binaries", pkey: "id", tkey: "", system_flag: 1,
+    topic_version: 3, pkey2s: ["version"],
+    cols: [{id: "id"}, {id: "version"}, {id: "size"}]
+};
+
+describe("desc_pkey2s", () => {
+    test("a list, as the desc carries it", () => {
+        expect(desc_pkey2s(BINARIES)).toEqual(["version"]);
+    });
+    test("a bare string, as a schema literal declares it", () => {
+        expect(desc_pkey2s({pkey2s: "yuno_release"})).toEqual(["yuno_release"]);
+    });
+    test("absent or empty is no secondary key", () => {
+        expect(desc_pkey2s({})).toEqual([]);
+        expect(desc_pkey2s({pkey2s: ""})).toEqual([]);
+        expect(desc_pkey2s(null)).toEqual([]);
+    });
+});
+
+describe("desc_tkey", () => {
+    test("empty is the append time", () => {
+        expect(desc_tkey(BINARIES)).toBe("");
+        expect(desc_tkey({})).toBe("");
+        expect(desc_tkey(null)).toBe("");
+    });
+    test("a named column", () => {
+        expect(desc_tkey({tkey: "tm"})).toBe("tm");
+    });
+});
+
+describe("col_key_roles", () => {
+    test("the pkey, a pkey2, and a column that is neither", () => {
+        expect(col_key_roles(BINARIES, "id")).toEqual(["pkey"]);
+        expect(col_key_roles(BINARIES, "version")).toEqual(["pkey2"]);
+        expect(col_key_roles(BINARIES, "size")).toEqual([]);
+    });
+    test("a column can be a pkey2 AND the tkey", () => {
+        expect(col_key_roles({pkey: "id", pkey2s: ["tm"], tkey: "tm"}, "tm"))
+            .toEqual(["pkey2", "tkey"]);
+    });
+    test("an empty tkey marks no column", () => {
+        expect(col_key_roles({pkey: "id", tkey: ""}, "")).toEqual([]);
+    });
+    test("the pkey defaults to id", () => {
+        expect(col_key_roles({}, "id")).toEqual(["pkey"]);
+    });
+});
+
+describe("system_flag_names", () => {
+    test("the number the desc carries", () => {
+        expect(system_flag_names(1)).toEqual(["sf_string_key"]);
+        expect(system_flag_names(0x0002 | 0x0100)).toEqual(["sf_rowid_key", "sf_t_ms"]);
+    });
+    test("a set bit with no name is shown by its value", () => {
+        expect(system_flag_names(0x0009)).toEqual(["sf_string_key", "0x0008"]);
+    });
+    test("the names a schema literal carries", () => {
+        expect(system_flag_names("sf_string_key|sf_t_ms")).toEqual(["sf_string_key", "sf_t_ms"]);
+        expect(system_flag_names(["sf_int_key"])).toEqual(["sf_int_key"]);
+    });
+    test("nothing, zero or garbage is no name", () => {
+        expect(system_flag_names(0)).toEqual([]);
+        expect(system_flag_names(undefined)).toEqual([]);
+        expect(system_flag_names(1.5)).toEqual([]);
+    });
+});