@yuneta/gobj-ui 6.0.0 → 6.1.1

package/src/c_yui_treedb_schema.js

@@ -31,8 +31,10 @@ import {
     SDATA,
     SDATA_END,
     data_type_t,
+    event_flag_t,
     gclass_create,
     log_error,
+    gobj_publish_event,
     gobj_read_pointer_attr,
     gobj_subscribe_event,
     gobj_send_event,
@@ -615,13 +617,28 @@ function destroy_graph(gobj)
 
 
 /************************************************************
- *   A topic node was clicked: open its table via the host route.
+ *   A topic node was clicked.
+ *
+ *   With a `node_route` the click IS a navigation and this view
+ *   makes it: that is what the route was handed down for.
+ *
+ *   Without one it is still an action, and it belongs to whoever
+ *   mounted this view — the schema editor draws the same picture
+ *   inside its own screens, where a topic opens in place and no
+ *   hash is involved. So the click is published rather than
+ *   dropped. A host that subscribes must DECLARE EV_NODE_CLICK in
+ *   its own FSM, as with every event a child publishes.
  ************************************************************/
 function ac_node_click(gobj, event, kw, src)
 {
     let topic = kw && kw.node_id;
     let route = gobj_read_str_attr(gobj, "node_route");
-    if(!topic || !route) {
+
+    if(!topic) {
+        return 0;
+    }
+    if(!route) {
+        gobj_publish_event(gobj, "EV_NODE_CLICK", {topic: topic});
         return 0;
     }
     let href = route.replace("{topic}", topic);
@@ -749,7 +766,9 @@ function create_gclass(gclass_name)
     ];
 
     const event_types = [
-        ["EV_NODE_CLICK",   0],
+        /*  Sent to itself by the graph, and published to the host when no
+         *  `node_route` was given: optional there, so no warning.  */
+        ["EV_NODE_CLICK",   event_flag_t.EVF_OUTPUT_EVENT|event_flag_t.EVF_NO_WARN_SUBS],
         ["EV_SHOW",         0],
         ["EV_THEME",        0],
         ["EV_REBUILD",      0],

package/src/schema_descs.js

@@ -0,0 +1,172 @@
+/***********************************************************************
+ *          schema_descs.js
+ *
+ *      The schema being EDITED, in the shape every treedb view already
+ *      draws.
+ *
+ *      `C_YUI_TREEDB_SCHEMA` draws a `descs` — `{topic_name: desc}` —
+ *      and gets one from the treedb it opened. In the schema editor
+ *      that treedb is `treedb_system_schema`, so the picture it draws
+ *      is the META schema (treedbs -> topics -> cols): three cards,
+ *      the same three on every yuno, and never the schema the operator
+ *      came to look at.
+ *
+ *      What the operator is editing is stored as RECORDS, and this
+ *      turns those records back into a desc. The drawing then costs no
+ *      backend call at all, and it follows an edit immediately —
+ *      before the restart that publishes it, which is exactly when it
+ *      is worth looking at.
+ *
+ *      THE ONE THING THAT IS NOT A COPY: `fkey`. A schema literal
+ *      declares the link ONCE, on the parent's `hook`; the treedb
+ *      derives `col.fkey = {parent_topic: hook_name}` on the child's
+ *      column when it opens the schema (tr_treedb.c). Views read that
+ *      derived field — `fkey_in_col()`, the info panel's "→", the
+ *      graph's edges — so a desc built without it draws every link
+ *      half missing.
+ *
+ *          Copyright (c) 2026, ArtGins.
+ *          All Rights Reserved.
+ ***********************************************************************/
+import {
+    col_flags,
+    col_hook,
+    col_enum,
+    topic_pkey2s,
+    as_json,
+    is_empty_value,
+} from "./schema_model.js";
+
+
+/*  Storage-only fields of a `cols` record: they describe where the
+ *  record LIVES in treedb_system_schema, not the column it declares.
+ *  The C validator drops the same ones (_treedb_create_topic_cols_desc).  */
+const COL_STORAGE_FIELDS = ["id", "value", "topics", "order", "_geometry", "__md_treedb__"];
+
+/*  Same, one level up, for a `topics` record.  */
+const TOPIC_STORAGE_FIELDS = ["id", "value", "treedbs", "cols", "order", "_geometry",
+                              "__md_treedb__"];
+
+/*  Fields of a column whose stored form is TEXT and whose desc form is
+ *  the value: they are `blob` columns of the `cols` topic.  */
+const COL_JSON_FIELDS = ["enum", "hook", "default", "template", "properties", "pkey2s"];
+
+
+/***************************************************************
+ *  One column record -> the col of a desc.
+ *
+ *  The desc keys a column by its BARE name under `id`; the record
+ *  keys it by the qualified one and carries the bare name in
+ *  `value`. Getting that backwards names every column after its
+ *  whole path.
+ ***************************************************************/
+function col_desc(col)
+{
+    let record = col.record || {};
+    let desc = {};
+
+    for(let [key, value] of Object.entries(record)) {
+        if(COL_STORAGE_FIELDS.indexOf(key) >= 0) {
+            continue;
+        }
+        if(is_empty_value(value)) {
+            continue;
+        }
+        let read = COL_JSON_FIELDS.indexOf(key) >= 0 ? as_json(value) : value;
+        if(is_empty_value(read)) {
+            continue;
+        }
+        desc[key] = read;
+    }
+    desc.id = col.name;
+    desc.flag = col_flags(record);
+    let hook = col_hook(record);
+    if(hook && !is_empty_value(hook)) {
+        desc.hook = hook;
+    } else {
+        delete desc.hook;
+    }
+    let e = col_enum(record);
+    if(e.length > 0) {
+        desc.enum = e;
+    }
+    return desc;
+}
+
+/***************************************************************
+ *  topic_descs(treedb) -> {topic_name: desc}
+ *
+ *      treedb   one entry of build_schema_model().treedbs
+ ***************************************************************/
+function topic_descs(treedb)
+{
+    let descs = {};
+
+    if(!treedb || !Array.isArray(treedb.topics)) {
+        return descs;
+    }
+
+    for(let topic of treedb.topics) {
+        let record = topic.record || {};
+        let desc = {};
+        for(let [key, value] of Object.entries(record)) {
+            if(TOPIC_STORAGE_FIELDS.indexOf(key) >= 0) {
+                continue;
+            }
+            if(is_empty_value(value)) {
+                continue;
+            }
+            desc[key] = value;
+        }
+        desc.topic_name = topic.name;
+        desc.pkey = topic.pkey || "id";
+        let pkey2s = topic_pkey2s(record);
+        if(pkey2s.length > 0) {
+            desc.pkey2s = pkey2s;
+        } else {
+            delete desc.pkey2s;
+        }
+        desc.cols = topic.cols.map(col_desc);
+        descs[topic.name] = desc;
+    }
+
+    /*  The link the schema declares once, given to the half that does
+     *  not declare it — the same derivation the treedb makes when it
+     *  opens a schema. A hook naming a topic or a column that is not
+     *  there derives nothing: that is the validator's finding, not a
+     *  reason to draw a broken desc.  */
+    for(let topic of treedb.topics) {
+        let desc = descs[topic.name];
+        for(let col of desc.cols) {
+            let hook = col.hook;
+            if(!hook || typeof hook !== "object") {
+                continue;
+            }
+            for(let [child_topic, fkey_col] of Object.entries(hook)) {
+                let child = descs[child_topic];
+                if(!child) {
+                    continue;
+                }
+                for(let child_col of child.cols) {
+                    if(child_col.id !== fkey_col) {
+                        continue;
+                    }
+                    if(!child_col.fkey || typeof child_col.fkey !== "object") {
+                        child_col.fkey = {};
+                    }
+                    child_col.fkey[topic.name] = col.id;
+                }
+            }
+        }
+    }
+
+    return descs;
+}
+
+
+export {
+    COL_STORAGE_FIELDS,
+    TOPIC_STORAGE_FIELDS,
+    col_desc,
+    topic_descs,
+};

package/src/schema_descs.test.js

@@ -0,0 +1,170 @@
+/***********************************************************************
+ *          schema_descs.test.js
+ *
+ *      The records drawn as the schema they describe, pinned.
+ *
+ *      The half worth testing is the derived `fkey`: it is declared
+ *      nowhere in the store, every view reads it, and a desc built
+ *      without it draws links that are simply not there.
+ ***********************************************************************/
+import { describe, test, expect } from "vitest";
+import { build_schema_model } from "./schema_model.js";
+import { topic_descs, col_desc } from "./schema_descs.js";
+
+
+const MODEL = build_schema_model({
+    treedbs: [{id: "db", schema_version: 4}],
+    topics: [
+        {id: "db.departments", value: "departments", order: 1, pkey: "id",
+         topic_version: 3, system_flag: "sf_string_key", treedbs: ["treedbs^db^topics"]},
+        {id: "db.users", value: "users", order: 2, pkey: "id", topic_version: 5,
+         pkey2s: "name", treedbs: ["treedbs^db^topics"]},
+    ],
+    cols: [
+        {id: "db.departments.id", value: "id", order: 1, type: "string",
+         header: "Id", flag: ["persistent", "required"], topics: ["topics^db.departments^cols"]},
+        {id: "db.departments.users", value: "users", order: 2, type: "dict",
+         header: "Users", flag: ["hook"], hook: {users: "departments"},
+         topics: ["topics^db.departments^cols"]},
+        {id: "db.users.id", value: "id", order: 1, type: "string", header: "Id",
+         flag: ["persistent"], topics: ["topics^db.users^cols"]},
+        {id: "db.users.name", value: "name", order: 2, type: "string", header: "Name",
+         flag: ["persistent"], topics: ["topics^db.users^cols"]},
+        {id: "db.users.departments", value: "departments", order: 3, type: "array",
+         header: "Departments", flag: ["fkey"], topics: ["topics^db.users^cols"]},
+    ],
+});
+
+
+describe("topic_descs", () => {
+    const descs = topic_descs(MODEL.treedbs[0]);
+
+    test("one desc per topic, keyed by the topic NAME", () => {
+        expect(Object.keys(descs).sort()).toEqual(["departments", "users"]);
+        expect(descs.users.topic_name).toBe("users");
+    });
+
+    test("a column is keyed by its bare name, not by its whole path", () => {
+        expect(descs.users.cols.map(c => c.id)).toEqual(["id", "name", "departments"]);
+    });
+
+    test("the columns keep their declared order", () => {
+        expect(descs.departments.cols.map(c => c.id)).toEqual(["id", "users"]);
+    });
+
+    test("topic metadata the views read travels", () => {
+        expect(descs.users.topic_version).toBe(5);
+        expect(descs.users.pkey).toBe("id");
+        expect(descs.departments.system_flag).toBe("sf_string_key");
+    });
+
+    test("a pkey2 declared as a bare string becomes the list the desc uses", () => {
+        expect(descs.users.pkey2s).toEqual(["name"]);
+    });
+
+    test("no storage field leaks into the desc", () => {
+        for(const key of ["value", "treedbs", "order"]) {
+            expect(descs.users[key]).toBeUndefined();
+        }
+        for(const col of descs.users.cols) {
+            for(const key of ["value", "topics", "order"]) {
+                expect(col[key]).toBeUndefined();
+            }
+        }
+    });
+
+    test("the FKEY the store never holds is derived onto the child column", () => {
+        const fkey_col = descs.users.cols.find(c => c.id === "departments");
+        expect(fkey_col.fkey).toEqual({departments: "users"});
+    });
+
+    test("the hook stays on the parent, whole", () => {
+        const hook_col = descs.departments.cols.find(c => c.id === "users");
+        expect(hook_col.hook).toEqual({users: "departments"});
+    });
+});
+
+describe("what a broken hook derives", () => {
+    test("a hook naming a topic that is not there derives nothing and throws nothing", () => {
+        const model = build_schema_model({
+            treedbs: [{id: "db"}],
+            topics:  [{id: "db.a", value: "a", treedbs: ["treedbs^db^topics"]}],
+            cols:    [{id: "db.a.x", value: "x", type: "dict", flag: ["hook"],
+                       hook: {gone: "parent"}, topics: ["topics^db.a^cols"]}],
+        });
+        const descs = topic_descs(model.treedbs[0]);
+        expect(descs.a.cols[0].hook).toEqual({gone: "parent"});
+        expect(descs.a.cols[0].fkey).toBeUndefined();
+    });
+
+    test("a hook naming a column that is not there derives nothing", () => {
+        const model = build_schema_model({
+            treedbs: [{id: "db"}],
+            topics:  [{id: "db.a", value: "a", order: 1, treedbs: ["treedbs^db^topics"]},
+                      {id: "db.b", value: "b", order: 2, treedbs: ["treedbs^db^topics"]}],
+            cols:    [{id: "db.a.x", value: "x", type: "dict", flag: ["hook"],
+                       hook: {b: "nope"}, topics: ["topics^db.a^cols"]},
+                      {id: "db.b.y", value: "y", type: "string", topics: ["topics^db.b^cols"]}],
+        });
+        const descs = topic_descs(model.treedbs[0]);
+        expect(descs.b.cols[0].fkey).toBeUndefined();
+    });
+});
+
+describe("the fields stored as JSON text", () => {
+    test("an enum, hook and default written as text come back as values", () => {
+        const desc = col_desc({name: "x", record: {
+            id: "db.a.x", value: "x", type: "string",
+            flag: '["enum","persistent"]',
+            enum: '["a","b"]',
+            hook: '{"c":"parent"}',
+            default: '{"k":1}'
+        }});
+        expect(desc.flag).toEqual(["enum", "persistent"]);
+        expect(desc.enum).toEqual(["a", "b"]);
+        expect(desc.hook).toEqual({c: "parent"});
+        expect(desc.default).toEqual({k: 1});
+    });
+
+    test("a default that is plain text stays plain text", () => {
+        expect(col_desc({name: "x", record: {default: "hello"}}).default).toBe("hello");
+    });
+
+    test("an empty value is left out rather than declared as empty", () => {
+        const desc = col_desc({name: "x", record: {type: "string", tkey: "", hook: null}});
+        expect("tkey" in desc).toBe(false);
+        expect("hook" in desc).toBe(false);
+    });
+});
+
+describe("edges", () => {
+    test("no treedb gives an empty descs, never a throw", () => {
+        expect(topic_descs(null)).toEqual({});
+        expect(topic_descs({})).toEqual({});
+    });
+});
+
+describe("the empty collections the store answers with", () => {
+    const model = build_schema_model({
+        treedbs: [{id: "db"}],
+        topics: [{id: "db.t", value: "t", _geometry: {}, treedbs: ["treedbs^db^topics"]}],
+        cols: [{id: "db.t.id", value: "id", type: "string",
+                enum: {}, hook: {}, default: {}, _geometry: {},
+                topics: ["topics^db.t^cols"]}],
+    });
+    const descs = topic_descs(model.treedbs[0]);
+
+    test("an unset blob does not become a value in the desc", () => {
+        for(const key of ["enum", "hook", "default", "_geometry"]) {
+            expect(key in descs.t.cols[0]).toBe(false);
+        }
+    });
+
+    test("an empty hook is NOT a hook — the info panel would draw an arrow to nothing", () => {
+        expect(descs.t.cols[0].hook).toBeUndefined();
+    });
+
+    test("the topic record's own _geometry does not travel", () => {
+        expect("_geometry" in descs.t).toBe(false);
+    });
+});

package/src/schema_flags.js

@@ -0,0 +1,237 @@
+/***********************************************************************
+ *          schema_flags.js
+ *
+ *      WHAT A COLUMN FLAG MEANS, next to the checkbox that sets it.
+ *
+ *      `flag` is the field of a column definition that decides the
+ *      most and explains the least: an array picked from 30-odd words
+ *      whose effects live in tr_treedb.c. Edited as a raw array — which
+ *      is how it is edited today — the difference between `required`
+ *      and `notnull`, or between `hook` and `fkey`, is something the
+ *      operator has to already know or find out by restarting a yuno.
+ *
+ *      So the flags are DATA here: grouped the way they act, each with
+ *      one line of what it does, and each knowing which column types it
+ *      is meaningful on. The editor draws checkboxes from this table
+ *      and nothing else knows the list.
+ *
+ *      The descriptions are English sentences used as i18n keys, the
+ *      same convention as the rest of the library's strings.
+ *
+ *      The catalogue is not a whitelist: a flag this table does not
+ *      know is still shown and still editable. A newer node may declare
+ *      one, and a schema editor that silently drops what it does not
+ *      recognize is worse than one that admits it.
+ *
+ *          Copyright (c) 2026, ArtGins.
+ *          All Rights Reserved.
+ ***********************************************************************/
+
+/*  Every column type, for the flags that are meaningful on all of them.  */
+const ANY = null;
+
+/*  The groups, in the order the editor draws them: what the column IS
+ *  before what it looks like.  */
+const FLAG_GROUPS = ["storage", "validation", "access", "relation", "key", "stats", "format"];
+
+/*  name    the word written into `flag`
+ *  group   which block it is drawn in
+ *  desc    one line of what it does (an i18n key)
+ *  types   the column types it is meaningful on, or ANY  */
+const FLAG_CATALOG = [
+    /*  ---- storage ---- */
+    {name: "persistent", group: "storage", types: ANY,
+     desc: "saved to disk; a column without it lives only while the yuno runs"},
+    {name: "wild", group: "storage", types: ANY,
+     desc: "convert a value of another type instead of refusing it"},
+    {name: "inherit", group: "storage", types: ANY,
+     desc: "copied from the primary record to its other instances"},
+
+    /*  ---- validation ---- */
+    {name: "required", group: "validation", types: ANY,
+     desc: "the field must be present when the record is written"},
+    {name: "notnull", group: "validation", types: ANY,
+     desc: "the field may be absent, but never null"},
+    {name: "enum", group: "validation", types: ["string", "array", "list"],
+     desc: "the value must be one of the `enum` list"},
+    {name: "template", group: "validation", types: ANY,
+     desc: "the value is built from the `template` field"},
+
+    /*  ---- access ---- */
+    {name: "writable", group: "access", types: ANY,
+     desc: "may be changed after the record is created"},
+    {name: "readable", group: "access", types: ANY,
+     desc: "may be read back"},
+    {name: "hidden", group: "access", types: ANY,
+     desc: "left out of listings"},
+
+    /*  ---- relation ---- */
+    {name: "hook", group: "relation", types: ["dict", "object", "list", "array"],
+     desc: "holds the children this record owns; needs a `hook` mapping"},
+    {name: "fkey", group: "relation", types: ["string", "dict", "object", "list", "array"],
+     desc: "holds the reference to a parent; written by the parent's hook"},
+
+    /*  ---- key ---- */
+    {name: "rowid", group: "key", types: ["string", "integer"],
+     desc: "key generated as a counter when none is given"},
+    {name: "uuid", group: "key", types: ["string"],
+     desc: "key generated as a uuid when none is given"},
+    {name: "qualified", group: "key", types: ["string"],
+     desc: "key composed as the parent's id plus this record's name"},
+    {name: "id", group: "key", types: ["string"],
+     desc: "the value is an identifier of something else"},
+
+    /*  ---- stats ---- */
+    {name: "stats", group: "stats", types: ["integer", "real"],
+     desc: "a counter, reported in the yuno statistics"},
+    {name: "rstats", group: "stats", types: ["integer", "real"],
+     desc: "a counter read through mt_reading when it is asked for"},
+    {name: "pstats", group: "stats", types: ["integer", "real"],
+     desc: "a counter kept across restarts"},
+
+    /*  ---- format ---- */
+    {name: "time", group: "format", types: ["integer", "string"],
+     desc: "the value is a timestamp"},
+    {name: "now", group: "format", types: ["integer"],
+     desc: "stamped with the current time when the record is created"},
+    {name: "date", group: "format", types: ["integer", "string"], desc: "a date"},
+    {name: "password", group: "format", types: ["string"],
+     desc: "shown masked, and never echoed back"},
+    {name: "email", group: "format", types: ["string"], desc: "an email address"},
+    {name: "url", group: "format", types: ["string"], desc: "a url"},
+    {name: "tel", group: "format", types: ["string"], desc: "a telephone number"},
+    {name: "color", group: "format", types: ["string"], desc: "a colour"},
+    {name: "image", group: "format", types: ["string"], desc: "an image"},
+    {name: "coordinates", group: "format", types: ["string", "array", "list"],
+     desc: "a geographic position"},
+    {name: "currency", group: "format", types: ["integer", "real"], desc: "an amount of money"},
+    {name: "percent", group: "format", types: ["integer", "real"], desc: "a percentage"},
+    {name: "hex", group: "format", types: ["integer", "string"], desc: "written in hexadecimal"},
+    {name: "binary", group: "format", types: ["string", "blob"], desc: "binary content"},
+    {name: "base64", group: "format", types: ["string", "blob"], desc: "encoded in base64"},
+    {name: "gbuffer", group: "format", types: ["blob"], desc: "carried as a gbuffer"},
+    {name: "table", group: "format", types: ["array", "list", "dict", "object"],
+     desc: "drawn as a table"},
+];
+
+/*  Flags that decide the SHAPE of the record and cannot both be on the
+ *  same column: the treedb writes one half of a link, never both.  */
+const EXCLUSIVE = [["hook", "fkey"], ["rowid", "uuid", "qualified"]];
+
+
+/***************************************************************
+ *  flags_for_type(type) -> [{name, group, desc, meaningful}]
+ *
+ *      The whole catalogue, every entry saying whether it is
+ *      meaningful on this type. Not filtered: a flag already SET on
+ *      a column of another type has to stay visible, or the editor
+ *      silently drops it on the next save.
+ ***************************************************************/
+function flags_for_type(type)
+{
+    return FLAG_CATALOG.map((flag) => {
+        return {
+            name:       flag.name,
+            group:      flag.group,
+            desc:       flag.desc,
+            meaningful: flag.types === ANY || flag.types.indexOf(type) >= 0
+        };
+    });
+}
+
+/***************************************************************
+ *  The catalogue as the editor draws it: by group, plus a last
+ *  group holding whatever this column carries that the catalogue
+ *  does not know.
+ *
+ *      grouped_flags(type, current) -> [{group, flags: [...]}]
+ ***************************************************************/
+function grouped_flags(type, current)
+{
+    let set = Array.isArray(current) ? current : [];
+    let known = {};
+    let by_group = {};
+
+    for(let flag of flags_for_type(type)) {
+        known[flag.name] = true;
+        if(!by_group[flag.group]) {
+            by_group[flag.group] = [];
+        }
+        by_group[flag.group].push(Object.assign({on: set.indexOf(flag.name) >= 0}, flag));
+    }
+
+    let out = [];
+    for(let group of FLAG_GROUPS) {
+        if(by_group[group]) {
+            out.push({group: group, flags: by_group[group]});
+        }
+    }
+
+    let unknown = set.filter(f => typeof f === "string" && f.length > 0 && !known[f]);
+    if(unknown.length > 0) {
+        out.push({
+            group: "other",
+            flags: unknown.map(name => ({
+                name: name, group: "other", desc: "", meaningful: true, on: true
+            }))
+        });
+    }
+    return out;
+}
+
+/***************************************************************
+ *  Turning a flag on may turn another off. Returns the flag list
+ *  the change produces, so the caller never has to know which
+ *  pairs exclude each other.
+ *
+ *      toggle_flag(current, name, on) -> [flag, ...]
+ ***************************************************************/
+function toggle_flag(current, name, on)
+{
+    let set = (Array.isArray(current) ? current : [])
+        .filter(f => typeof f === "string" && f.length > 0);
+
+    if(!on) {
+        return set.filter(f => f !== name);
+    }
+    let excluded = {};
+    for(let group of EXCLUSIVE) {
+        if(group.indexOf(name) < 0) {
+            continue;
+        }
+        for(let other of group) {
+            if(other !== name) {
+                excluded[other] = true;
+            }
+        }
+    }
+    let out = set.filter(f => !excluded[f]);
+    if(out.indexOf(name) < 0) {
+        out.push(name);
+    }
+    return out;
+}
+
+/***************************************************************
+ *  What a flag does, or "" when the catalogue does not know it.
+ ***************************************************************/
+function flag_description(name)
+{
+    for(let flag of FLAG_CATALOG) {
+        if(flag.name === name) {
+            return flag.desc;
+        }
+    }
+    return "";
+}
+
+
+export {
+    FLAG_GROUPS,
+    FLAG_CATALOG,
+    EXCLUSIVE,
+    flags_for_type,
+    grouped_flags,
+    toggle_flag,
+    flag_description,
+};