@yuneta/gobj-ui 5.15.0 → 5.17.0

package/README.md

@@ -430,12 +430,32 @@ 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` or `uuid` keys its records by a value nobody reads —
+that is the point of those flags — 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 keyed by rowid and named in `value`, so the
+graph drew cards reading `181`, `225`, `193`.
+
+The rule is in **`treedb_node_label.js`** (pure, unit-tested): read the pkey
+column's flags from the desc; if the key is synthetic, 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` takes a **`readonly`** attr, propagated to every topic it
-builds. It is not one more button flag: it is the STATE of the treedb and it
-beats each `with_*` flag at once, because a treedb whose tranger the yuno does
-not master answers **every** write with
+`C_YUI_TREEDB_TOPICS` and `C_YUI_TREEDB_GRAPH` take a **`readonly`** attr; the
+topics view propagates it to every topic it builds. It is not one more button
+flag: it is the STATE of the treedb and it beats each `with_*` flag at once,
+because a treedb whose tranger the yuno does not master answers **every** write
+with
 
 ```
 ERROR -1: <yuno>: treedb '<name>' is READ-ONLY, this yuno is not the master of its tranger
@@ -453,23 +473,59 @@ buttons, the in-row edit icons, and the write half of the record form's toolbar
 (`copy` stays — reading a record includes taking it with you) with the cells not
 editable. The record form still OPENS: looking is the point of a replica.
 
+In the **graph** it takes away the `edition` operation mode, which is the only
+one that draws the create / delete / link affordances — the mode select stops
+offering it, and a graph left in edition on a master comes back in `reading` on
+a replica (the mode is a persisted preference). The other modes are untouched:
+panning, zooming and opening a node are reading.
+
 Two implementation notes worth keeping:
 
 - the decision lives in **`treedb_write_plan.js`** (pure, tested), not in five
   `!readonly && with_x` expressions — five places to forget the sixth;
-- and the write **events** are refused as well, in both gclasses, with a
+- and the write **events** are refused as well, in every gclass, with a
   `log_error`. Hiding a button is not the same as refusing a write: an event can
   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:**
 
@@ -482,8 +538,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`