timescale.info#329 · Relationship arrows: per-relationship arrows on each end, drawn as their union
- timeline-app
- pull request
## What changed A new official plugin, **Relationship arrows** (`relationship-arrows`, version 1), following the maintainer's revised design for #326. It is a plugin only: the document format doesn't change, relationships stay undirected and unlabeled, and the data lives in entity metadata. ### Data Each moment or duration may keep a list under the metadata key `arrows`: ```json [{ "target": { "moment": " " }, "arrow": "to" }] ``` - **`target`:** the other end of one of the entity's relationships, in the same `{moment|duration: id}` form the `relationships` array uses. Relationships have no IDs of their own in the code; an arc's ID is just `m:a~m:b`, built from its endpoints. - **`arrow`:** `none`, `to`, `from` or `both`, from this entity's point of view. `to` puts an arrowhead at the other end, `from` at this entity's own end, and `both` at both ends. ### Union An arc's arrowheads are the union of what its two ends say: each side's choice becomes "an arrowhead at which end", and the two are combined. This is `arcArrowheads` / `arrowsToward` in src/plugins.ts. Tolerant reading (`readRelationshipArrows`) never throws. Entries that aren't exactly a target plus one of the four arrows are unreadable: they are ignored for drawing and kept in place. ### Editor There is a new host field kind, `relationship-arrows`, for moment details and the duration dialog. Stack entries don't get it, since they aren't relationship endpoints. - **Rows:** each entry gets a row with the other end's name, a none/to/from/both choice and ×. - **Adding:** **Add an arrow…** lists the entity's relationships that have no entry yet. It loads them page by page the way **Related to** does, up to 1,000, and re-reads them when focused. - **Other end:** a note says what the other end's own arrows add, when that entity's metadata is in memory. - **Dangling:** a target that doesn't exist or is no longer related gets a red outline, the note "No relationship with this entity", and ×. This only happens when the full relationship list is known. Nothing is dropped: saves, exports and round trips keep such entries, and unreadable ones, until the user removes them. - **Not a list:** a value that isn't a list is shown read-only, as for stacks. ### Drawing `renderEdgeArcs` works as before, and `arrowheadPath` in src/relationships.ts builds the heads. - **Look:** arrowheads are tangent-aligned and drawn in the scaled arc layer, so they follow content scaling. They take the arc's color and highlight with it on hover. An off-screen end gets none. - **Off:** without the plugin installed and enabled, nothing is drawn, and the metadata lookup is skipped entirely. - **Hover text:** `A → B` when exactly one end has an arrowhead; otherwise `A ↔ B`. - **Separated tracks:** they still draw no arcs. - **Cost:** for each arc (at most 256 per window), only the two endpoints' metadata is read, from what the view already has. That is the timeline in memory, or the overview's moment groups and duration bands. ### Projections, so server and desktop views can draw arrows - Moments: `pluginMetadata` projects `relationship-arrows` arrays, as it already does for stack and links fields. The desktop store already sends plugin-key arrays of up to 2,048 characters. - Duration bands: `durationOverview` now carries arrays of up to 1,024 characters as JSON, within its existing 4 KiB budget, excluding tags and content labels. The desktop store's `BAND_COLUMNS` matches this (native-store/src/lib.rs). ### API and docs - OpenAPI `PluginField` gains the new kind. - docs/plugins.md has a new section. docs/relationships.md gets a paragraph: direction is a drawing convention stored on the entities, Separate doesn't follow it, and there are no labels. The earlier `toggle` field kind and "Arrow here" design have been removed from this PR, so it no longer overlaps #325's `toggle`. Closes #326. ## Testing - `npm test`: 331 pass, 0 fail. Unit tests cover reading (odd values, dangling and unreadable entries), the un…