pi-weave 0.1.7 → 0.1.8

package/src/web/client/context/context.model.ts

@@ -0,0 +1,313 @@
+/**
+ * The context rail: everything related, visible without navigating
+ * (weave-workspace §1.1, §1.2, §10, P2.5).
+ *
+ * §1.1's UX principle is the one that decides arguments here:
+ *
+ * > **Don't make the user navigate to information. Bring related information
+ * > into the current view.**
+ *
+ * The rail is that principle made concrete. Whatever is selected, the four
+ * groups below say what it points at, what points at it, what it is filed
+ * under, and what code it talks about — all at a glance, with no click that
+ * costs you your place. §1.2 sketches it as `LINKS` / `BACKLINKS`, and §11's
+ * P2 line adds mentions and tags now that §4.3 and §4.4 have shipped the data.
+ *
+ * ## Where each group comes from
+ *
+ * | Group | Source | Why not something else |
+ * | --- | --- | --- |
+ * | LINKS | `detailModel().links`, minus mentions | Core's projection, shared with the TUI (§3). |
+ * | BACKLINKS | `deriveBacklinks()` over all edges | One pass for the whole graph, not O(nodes × edges) per selection. |
+ * | TAGS | `GraphPayload.tags` (§4.3) | The structured index. Never `detail.tags`, which is a display string. |
+ * | MENTIONS | `mentions` edges (§4.4) | Both directions: what a note names, and which notes name a file. |
+ *
+ * `detailModel` is used rather than `focusModel` even though `focusModel`
+ * groups the neighbourhood already: its grouping is by *edge kind* with the
+ * headings a terminal wants ("links to →", "← linked from"), and the rail
+ * needs tags and mentions interleaved on equal footing with those. Reaching
+ * through `detailModel` and regrouping keeps core's link/backlink derivation
+ * shared while letting the browser decide its own section order.
+ *
+ * ## Tier rules (§2)
+ *
+ * `src/web/client/**`. View-models via `../../shared/view`; never `src/core`.
+ * No DOM type is named, so the root `tsconfig.json` project compiles the
+ * tests.
+ */
+
+import type { DetailLinkRow, ViewGraphModel } from "../../shared/view";
+import { deriveBacklinks, detailModel, listLabel } from "../../shared/view";
+import type { GraphPayload, WireGraphNode, WireNodeKind, WireNoteSource } from "../../shared/wire";
+import { kindGlyph, provenanceGlyph, provenanceTitle, viewModel } from "../tree/tree.model";
+
+// --- rows and groups ---------------------------------------------------------------
+
+/** One clickable entry in the rail. */
+export interface ContextRow {
+  /** Unique within the rail, for a stable render key. */
+  readonly id: string;
+  /** The node id to select. Every row is clickable — that is the point. */
+  readonly target: string;
+  readonly label: string;
+  readonly kind: WireNodeKind;
+  readonly kindGlyph: string;
+  readonly provenance: WireNoteSource | null;
+  readonly provenanceGlyph: string;
+  readonly provenanceTitle: string;
+  /** Highlighted when this row is what is currently selected. */
+  readonly selected: boolean;
+}
+
+/** One labelled section. */
+export interface ContextGroup {
+  /** `LINKS`, `BACKLINKS`, `TAGS`, `MENTIONS`. */
+  readonly heading: string;
+  /** Shown when the group is present but empty. Never rendered when hidden. */
+  readonly rows: readonly ContextRow[];
+}
+
+/** The whole rail for one selection. */
+export interface ContextModel {
+  /** The selected node's own label, for the rail's subtitle. */
+  readonly subject: string | null;
+  /** LINKS, BACKLINKS and MENTIONS. Empty groups are omitted, never rendered. */
+  readonly groups: readonly ContextGroup[];
+  /**
+   * TAGS, carried separately because a tag row is not a {@link ContextRow}.
+   *
+   * A tag has a name, a count and a list of sibling notes; flattening that
+   * into the same array as the link rows would mean a union type and a
+   * discriminant check inside the component — which is a branch, in a `.tsx`,
+   * where §10 says branches cannot be covered. Two fields is the cheaper
+   * shape.
+   */
+  readonly tags: readonly TagGroupRow[];
+  /** Present instead of groups when there is nothing to show. */
+  readonly empty: string | null;
+}
+
+/** Section headings, in the order §1.2 sketches them. */
+export const HEADINGS = { links: "LINKS", backlinks: "BACKLINKS", tags: "TAGS", mentions: "MENTIONS" } as const;
+
+// --- building rows ------------------------------------------------------------------
+
+/** A row from a node. The rail's one place that reads a node's presentation. */
+export function rowFor(id: string, node: WireGraphNode, selectedId: string | null): ContextRow {
+  return {
+    id,
+    target: node.id,
+    label: listLabel(node),
+    kind: node.kind,
+    kindGlyph: kindGlyph(node.kind),
+    provenance: node.provenance,
+    provenanceGlyph: provenanceGlyph(node.provenance),
+    provenanceTitle: provenanceTitle(node.provenance),
+    selected: node.id === selectedId,
+  };
+}
+
+/**
+ * A row from one of core's `DetailLinkRow`s.
+ *
+ * `DetailLinkRow.label` is pre-composed for a terminal — `"links-to → Alpha"`,
+ * `"← Alpha"` — and the rail already says which direction a section is in its
+ * heading, so repeating it in every row is noise. The node is looked up and
+ * relabelled instead, which also recovers the kind glyph and provenance mark
+ * that the terminal's single label string had flattened away.
+ *
+ * Exported so its two `null` paths are directly testable. Both are guards
+ * against a shape core does not currently produce — `SelectableRow.target` is
+ * optional in general but always set on a `DetailLinkRow`, and core filters
+ * unresolvable targets before returning — so reaching them through
+ * {@link contextModel} would mean constructing a payload core cannot emit.
+ * A guard that cannot be exercised is a guard nobody can check is right.
+ */
+export function rowFromDetail(row: DetailLinkRow, byId: ReadonlyMap<string, WireGraphNode>, selectedId: string | null): ContextRow | null {
+  const target = row.target;
+  if (target === undefined) return null;
+  const node = byId.get(target);
+  // The guard for a truncated payload, where an edge can outlive the node it
+  // points at.
+  return node === undefined ? null : rowFor(row.id, node, selectedId);
+}
+
+/** Index a payload's nodes by id. */
+function nodesById(model: ViewGraphModel): Map<string, WireGraphNode> {
+  const byId = new Map<string, WireGraphNode>();
+  for (const node of model.nodes) byId.set(node.id, node);
+  return byId;
+}
+
+// --- the four groups ------------------------------------------------------------------
+
+/**
+ * Outgoing edges, excluding `mentions` and structural containment.
+ *
+ * `contains` and `anchored-at` are deliberately dropped: they are the tree's
+ * job, the tree is on screen at the same time, and a `repository` node's rail
+ * would otherwise be a second copy of the tree with every module in it.
+ * `mentions` is dropped here because it gets a section of its own.
+ */
+const LINK_EDGE_PREFIXES = ["link:links-to:"];
+
+/** True when a `DetailLinkRow`'s id names an edge kind the LINKS group shows. */
+function isLinkRow(row: DetailLinkRow): boolean {
+  return LINK_EDGE_PREFIXES.some((prefix) => row.id.startsWith(prefix));
+}
+
+/** True when a `DetailLinkRow` names a `mentions` edge. */
+function isMentionRow(row: DetailLinkRow): boolean {
+  return row.id.startsWith("link:mentions:");
+}
+
+/**
+ * Tag rows for a note.
+ *
+ * From `GraphPayload.tags` (§4.3) — the structured `tag → slugs` index — and
+ * never from `WireGraphNode.detail.tags`, which is a comma-joined display
+ * string that §4.2 forbids turning back into structure. The membership test is
+ * therefore "does this tag's slug list contain mine", which is exact even for
+ * a tag whose name contains a comma.
+ *
+ * The rows target the tag's *other* notes rather than the tag itself, because
+ * there is no tag node in the graph to select. A tag with only this note in it
+ * still renders — it says something true about the note — but contributes no
+ * navigable siblings, so its count reads `1`.
+ */
+export interface TagGroupRow {
+  readonly tag: string;
+  /** Notes carrying this tag, this one included. */
+  readonly count: number;
+  /** The other notes, clickable. */
+  readonly siblings: readonly ContextRow[];
+}
+
+/** Tags for a slug, with the notes that share them. */
+export function tagsFor(payload: GraphPayload, slug: string, byId: ReadonlyMap<string, WireGraphNode>, selectedId: string | null): TagGroupRow[] {
+  const out: TagGroupRow[] = [];
+  // Key order is `deriveTagIndex`'s: count descending, then tag ascending
+  // (§4.3), and `Object.entries` preserves it. So the popular tags surface
+  // first with no sorting here — re-sorting would discard a ranking the server
+  // already computed and the ETag already depends on.
+  for (const [tag, slugs] of Object.entries(payload.tags)) {
+    if (!slugs.includes(slug)) continue;
+    const siblings: ContextRow[] = [];
+    for (const other of slugs) {
+      if (other === slug) continue;
+      const node = byId.get(`note:${other}`);
+      if (node !== undefined) siblings.push(rowFor(`tag:${tag}:${other}`, node, selectedId));
+    }
+    out.push({ tag, count: slugs.length, siblings });
+  }
+  return out;
+}
+
+/**
+ * Incoming `mentions`: which notes name this file or module (§4.4).
+ *
+ * The complement of the outgoing half, and the more useful direction of the
+ * two — standing on `src/core/vault.ts` and seeing which notes discuss it is
+ * the question a repository workspace exists to answer. `deriveBacklinks` is
+ * no help here: it filters to `links-to` by design, so mentions need their own
+ * pass.
+ */
+export function incomingMentions(model: ViewGraphModel, id: string, byId: ReadonlyMap<string, WireGraphNode>, selectedId: string | null): ContextRow[] {
+  const rows: ContextRow[] = [];
+  for (const edge of model.edges) {
+    if (edge.kind !== "mentions" || edge.target !== id) continue;
+    const node = byId.get(edge.source);
+    if (node !== undefined) rows.push(rowFor(`mentioned-by:${edge.source}`, node, selectedId));
+  }
+  return rows;
+}
+
+// --- the model ----------------------------------------------------------------------------
+
+/**
+ * The slug inside a `note:<slug>` id, or `null`.
+ *
+ * Mirrors `workspace.ts`' `noteSlug` and `note.model.ts`' `slugOfNode`. Three
+ * copies of a five-line rule is one too many, and the right fix is for the
+ * node-id format to live in one module the client tier shares — but that is a
+ * refactor across three files that P2 is not the commit for. Exported so the
+ * empty-slug case is testable here rather than only through a payload that
+ * would need a malformed node in it.
+ */
+export function slugOf(id: string): string | null {
+  if (!id.startsWith("note:")) return null;
+  const slug = id.slice("note:".length);
+  return slug === "" ? null : slug;
+}
+
+/** Copy for the rail's own empty states. */
+export const RAIL_EMPTY = {
+  loading: "Loading…",
+  noSelection: "Select anything to see what it connects to.",
+  unknown: "This node is not in the current graph.",
+  isolated: "Nothing links to or from this yet.",
+} as const;
+
+/** The rail with nothing to show, and a reason. */
+function emptyRail(reason: string): ContextModel {
+  return { subject: null, groups: [], tags: [], empty: reason };
+}
+
+/**
+ * Build the rail.
+ *
+ * Empty groups are **omitted**, not rendered as headings over nothing. The
+ * rail sits under the graph column in a fixed-height region (§1.2), so four
+ * headings with one row between them wastes the space that the one populated
+ * group needed — and a heading with nothing under it reads as a load that
+ * failed rather than as an absence.
+ *
+ * `now` is not a parameter: unlike the tree and the note header, nothing in
+ * the rail is time-relative. Rows are labels and glyphs, which is the point —
+ * a rail that changed as the clock moved would re-render three columns for no
+ * reason.
+ */
+export function contextModel(payload: GraphPayload | null, selectedId: string | null): ContextModel {
+  if (payload === null) return emptyRail(RAIL_EMPTY.loading);
+  if (selectedId === null) return emptyRail(RAIL_EMPTY.noSelection);
+
+  const model = viewModel(payload);
+  const detail = detailModel(model, selectedId);
+  if (detail === null) return emptyRail(RAIL_EMPTY.unknown);
+
+  const byId = nodesById(model);
+  const groups: ContextGroup[] = [];
+  const push = (heading: string, rows: readonly ContextRow[]): void => {
+    if (rows.length > 0) groups.push({ heading, rows });
+  };
+
+  const resolve = (rows: readonly DetailLinkRow[]): ContextRow[] =>
+    rows.map((row) => rowFromDetail(row, byId, selectedId)).filter((row): row is ContextRow => row !== null);
+
+  push(HEADINGS.links, resolve(detail.links.filter(isLinkRow)));
+
+  // From the whole-graph pass rather than `detail.backlinks`, which is the
+  // same data — but this map is built once and the rail is rebuilt on every
+  // selection, so the shared pass is the one that scales.
+  const backlinks = deriveBacklinks(model.edges).get(selectedId) ?? [];
+  push(
+    HEADINGS.backlinks,
+    backlinks
+      .map((source) => byId.get(source))
+      .filter((node): node is WireGraphNode => node !== undefined)
+      .map((node) => rowFor(`backlink:${node.id}`, node, selectedId)),
+  );
+
+  // Both directions in one section: what this names, and what names it. A
+  // note sees the code it discusses; a module sees the notes discussing it,
+  // and no node is ever both in practice.
+  push(HEADINGS.mentions, [...resolve(detail.links.filter(isMentionRow)), ...incomingMentions(model, selectedId, byId, selectedId)]);
+
+  const slug = slugOf(selectedId);
+  const tags = slug === null ? [] : tagsFor(payload, slug, byId, selectedId);
+
+  if (groups.length === 0 && tags.length === 0) {
+    return { subject: detail.label, groups: [], tags: [], empty: RAIL_EMPTY.isolated };
+  }
+  return { subject: detail.label, groups, tags, empty: null };
+}