@yuneta/gobj-ui 5.16.0 → 6.0.0

package/README.md

@@ -430,6 +430,27 @@ Logical DOM classes: `JSON_VIEWER`, `JSON_TOOLBAR`, `JSON_SEARCH`, `JSON_TREE`,
 `JSON_ROW`, `JSON_KEY`, `JSON_VALUE`, `JSON_SUMMARY`, `JSON_COLLAPSED`,
 `JSON_TIME`. The gclass imports its own `c_yui_json.css`.
 
+### What a node in the graph is CALLED
+
+`C_G6_NODES_TREE` (the record graph inside `C_YUI_TREEDB_GRAPH`) labels a card
+by what NAMES the record, which is not always what KEYS it. A topic whose id
+column is flagged `rowid`, `uuid` or `qualified` keys its records by something
+that is not the plain name — a counter, a random string, or the name with
+every ancestor in front of it — and the name lives in the secondary key the
+topic declares (`pkey2s`). `treedb_system_schema` is the case that forced it:
+its `topics` and `cols` records are named in `value`, so the graph drew cards
+reading `181`, `225`, `193` while they were keyed by rowid, and would read the
+whole path now that they are qualified.
+
+The rule is in **`treedb_node_label.js`** (pure, unit-tested): read the pkey
+column's flags from the desc; if the key is not the plain name, take the first
+`pkey2s` field the record actually carries; otherwise keep the id. **The pkey is never
+lost** — it is the card's tooltip, on the chip and on the entity card alike.
+
+It needs the descriptor to carry `pkey2s`, which `tranger2_topic_desc()` only
+clones from **SDK > 7.13.0**. Against an older node the desc has no `pkey2s`, the
+label falls back to the id, and nothing else changes.
+
 ### Read-only treedbs: `readonly`
 
 `C_YUI_TREEDB_TOPICS` and `C_YUI_TREEDB_GRAPH` take a **`readonly`** attr; the
@@ -469,14 +490,44 @@ Two implementation notes worth keeping:
   still arrive from a keyboard path or a form that outlived the flag, and an
   ignored write is exactly the behaviour this whole change exists to stop.
 
-### C_YUI_TREEDB_SCHEMA — the treedb as a graph of topics (prototype)
-
-A landing view that draws a treedb as a **graph of topics** — one node per
-topic, one edge per hook/fkey relationship — built from the schema `descs`
-**alone**: no data, no backend calls. It is the "every treedb is a graph" rule
-applied to the schema itself, and an alternate landing to the topic cards. A
-node click opens that topic's table through a real hash navigation, so the
-graph is a navigation surface rather than a picture.
+### C_YUI_TREEDB_SCHEMA — the treedb drawn the way its `.c` draws it
+
+A landing view that draws a treedb the way its schema literal draws it in ASCII
+(`treedb_schema_*.c`, `treedb_system_schema.c`): **one card per topic**,
+listing its fields in schema order, and **one edge per hook**, leaving the row
+that declares the hook and landing on the fkey row of the child it names. Built
+from the schema `descs` **alone**: no data, no backend calls. It is the "every
+treedb is a graph" rule applied to the schema itself, and an alternate landing
+to the topic cards. A node click opens that topic's table through a real hash
+navigation, so the graph is a navigation surface rather than a picture.
+
+The marks are the notation of those `.c` literals, so the drawing and the
+source read the same:
+
+| Mark | Meaning |
+|------|---------|
+| `{}` | dict hook — N unique children |
+| `[]` | list hook — n not-unique children |
+| `()` | a single child |
+| `(↖)` | 1 fkey — 1 parent |
+| `[↖]` | n fkeys — n parents |
+| `{↖}` | N fkeys — N parents |
+| `*` | required |
+| `#` | the primary key |
+
+`dict` and `object` are one shape and `list` and `array` are another, exactly
+as tr_treedb's hook/fkey switches treat them. A self-referent hook (a tree)
+draws as a loop.
+
+**Not to be confused with the node graph** (`C_G6_NODES_TREE`, hosted by
+`C_YUI_TREEDB_GRAPH`), which draws the **records**. On a treedb whose records
+are schemas — `treedb_system_schema` — that one draws a box per column,
+hundreds of them, each labelled by a pkey that is a rowid: a correct picture of
+the storage and an unreadable picture of the schema. This view answers the
+schema question; that one answers the data question.
+
+The demo `test-app/schema.html` mounts it alone against the real yuneta agent
+schema, so the drawing can be held against the ASCII one in its `.c`.
 
 **Contract:**
 
@@ -489,8 +540,9 @@ graph is a navigation surface rather than a picture.
   graph in place, preserving the user's zoom/pan), plus the internal
   `EV_NODE_CLICK` a node click sends into the FSM.
 
-Marked a **prototype**: it is barrel-exported and public from 4.0.0, but its
-shape may still move. Renders with `@antv/g6` (no CSS of its own).
+Barrel-exported and public from 4.0.0. Renders with `@antv/g6`; the cards are
+HTML nodes carrying their own inline colours, so a theme switch repaints them in
+place (no CSS of its own).
 
 ### Frontend view — `setup_frontend_view`