Add label for links

2026-09-09 21:47:34 +02:00
parent a64a5327e7
commit e7d8c6081b
10 changed files with 431 additions and 15 deletions
@@ -0,0 +1,52 @@
+# Additions to JSON Canvas 1.0
+
+Everything `jsoncanvas-desktop` does beyond JSON Canvas 1.0, and nothing else.
+The original is kept alongside as [1.0.md](1.0.md); the whole format, original
+and additions together, is in [spec.md](spec.md).
+
+Two rules keep the additions from splitting the format in two:
+
+1. **Every addition is optional.** A file that uses none of them is a plain JSON
+   Canvas 1.0 file, and a reader that ignores all of them sees a complete canvas —
+   an addition may improve how something is displayed, never what it means.
+2. **An addition reuses a name the format already has** where one fits, so that
+   the same idea is not called two things in one file.
+
+A client that does not know an addition will ignore it. Whether it keeps the
+attribute when it saves is up to that client; this editor keeps every attribute
+it does not know (see *Unrecognised data* in [spec.md](spec.md)).
+
+## Format additions
+
+| Attribute | Applies to | Added |
+| --- | --- | --- |
+| `label` | Link type nodes | 2026-09-09 |
+
+### `label` on link type nodes
+
+`label` (optional, string) is a text label shown in place of the URL when the
+node is displayed.
+
+A canvas is read at a glance, and a URL is rarely what a reader wants to see: an
+address is long, it repeats the same prefix on every node, and the part that says
+what the page actually is tends to be at the end, past where the node is wide
+enough to show. The label lets the node say `The JSON Canvas spec` instead of
+`https://jsoncanvas.org/spec/1.0/`.
+
+- The name is `label` because group nodes and edges already use `label` for
+  exactly this — a piece of text that names the thing.
+- The URL is not hidden: the node still shows the host, and the full address is
+  the link's tooltip.
+- Without the attribute, or with a blank one, the node displays its URL, which is
+  what a JSON Canvas 1.0 file gets.
+- The label is display text only. Clicking the node still opens `url`.
+
+```json
+{
+  "id": "spec",
+  "type": "link",
+  "url": "https://jsoncanvas.org/spec/1.0/",
+  "label": "The JSON Canvas spec",
+  "x": 220, "y": -250, "width": 320, "height": 140
+}
+```