yarramate 1.40.0 → 1.41.1

package/dist/adapters/visual-graph-entry.d.ts

@@ -2,3 +2,4 @@ export { projectGraphForCanvas, type CanvasGraph, type CanvasNode, type CanvasEd
 export { foldTree, foldGraph, nestingTree, liftedEdgeId, NESTING_KIND_IDS, type FoldInput, type FoldNode, type FoldEdge, type FoldMembership, type FoldTree, type LiftedEdge, type NestingConflict, type SlotWiring, } from '../fold-tree.js';
 export { edgeLabelText, type EdgeLabelData } from '../edge-label.js';
 export { DEFAULT_LAYOUT, LAYOUT_MODES, type LayoutMode } from '../layout-mode.js';
+export { canvasSceneInput, drawnCanvasEdges, resolveCanvasScene, type CanvasScene, type CanvasSceneEdge, type CanvasSceneFold, type CanvasSceneInput, type CanvasSceneNode, } from '../canvas-scene.js';

package/dist/adapters/visual-graph-entry.js

@@ -11,3 +11,9 @@ export { foldTree, foldGraph, nestingTree, liftedEdgeId, NESTING_KIND_IDS, } fro
 // cytoscape too. `edge-label.ts` and `layout-mode.ts` reach no package.
 export { edgeLabelText } from '../edge-label.js';
 export { DEFAULT_LAYOUT, LAYOUT_MODES } from '../layout-mode.js';
+// What the canvas puts on screen for a view, as plain data (#577): visibility,
+// containment as drawn, fold chips, which edges draw and what a lifted edge
+// counts. The canvas runs these two functions itself, so a host drawing the
+// same picture elsewhere reads the same decisions. No positions: those are
+// ELK's and the saved layout's. `canvas-scene.ts` reaches no package.
+export { canvasSceneInput, drawnCanvasEdges, resolveCanvasScene, } from '../canvas-scene.js';

package/dist/canvas-scene.d.ts

@@ -0,0 +1,116 @@
+/**
+ * What the canvas draws, as plain data (#577).
+ *
+ * Two steps, both pure, and the canvas itself runs both:
+ *
+ * 1. {@link canvasSceneInput} builds the scene's elements from the model:
+ *    which box holds what, which folded box stands for what, which edges are
+ *    drawn at all, and the edges lifted onto a folded box. `graphToElements`
+ *    turns exactly this into cytoscape elements.
+ * 2. {@link resolveCanvasScene} decides, for one view and one quick-filter
+ *    text, what is on screen: the nodes, the boxes pulled in to hold them, the
+ *    containment that holds while both ends are visible, what a folded box's
+ *    chip counts, which edges draw and what a lifted edge's count says.
+ *    `applyFilter` applies exactly this to the live canvas.
+ *
+ * So a host that draws the canvas's picture somewhere else, a server-side
+ * figure renderer, reads the same decisions rather than restating them. A
+ * restated copy was measured wrong twice in its edge labels alone (#576, #587).
+ *
+ * Positions are deliberately NOT here. Every rebuild, view switch and fold runs
+ * ELK over what is visible, and a saved layout is pinned over the result
+ * afterwards, so a subject the saved layout does not name is wherever ELK put
+ * it; a box's bounds are cytoscape's, derived from its members. Neither can be
+ * restated without the layout engine, and a host drawing an unsaved view
+ * places it by its own rules.
+ *
+ * Imports nothing with a runtime of its own, so it ships on the
+ * runtime-neutral `yarramate/adapter/visual-graph` subpath.
+ */
+import type { CanvasEdge, CanvasGraph } from './graph-projection.js';
+import { type FoldMembership, type FoldTree } from './fold-tree.js';
+import type { NestingKind } from './nesting.js';
+/** One node of the scene, carrying what {@link resolveCanvasScene} reads. */
+export interface CanvasSceneNode {
+    readonly id: string;
+    /** Matched by the quick filter, with `id` and `kindLabel`. */
+    readonly name?: string;
+    readonly kindLabel?: string;
+    /** The box the model nests this in, whether or not it is drawn nested. */
+    readonly parent?: string;
+    /** Drawn folded: everything under it is hidden and its edges lifted to it. */
+    readonly folded: boolean;
+    /** Everything nested under it, at any depth, over the whole model. */
+    readonly insideIds: readonly string[];
+}
+/** One edge of the scene: a drawn relationship, or one lifted onto a fold. */
+export interface CanvasSceneEdge {
+    readonly id: string;
+    readonly from: string;
+    readonly to: string;
+    /**
+     * Present only on a lifted edge (`lift:` ids): the relationships it stands
+     * for. Such an edge draws while the view selected any of them.
+     */
+    readonly relationshipIds?: readonly string[];
+    /** A lifted edge's kind, as its label names it. */
+    readonly liftedKind?: string;
+}
+export interface CanvasSceneInput {
+    readonly nodes: readonly CanvasSceneNode[];
+    /**
+     * The drawn relationships (nesting-consumed and, unless shown,
+     * responsibility edges already left out), then the lifted edges.
+     */
+    readonly edges: readonly CanvasSceneEdge[];
+    /** For the caller's own warnings: nesting conflicts and cycles. */
+    readonly tree: FoldTree;
+}
+export interface CanvasSceneFold {
+    /** Which instances draw folded. Empty or absent draws everything. */
+    readonly folded?: ReadonlySet<string>;
+    /** From the model frame; without them only view nesting contains anything. */
+    readonly memberships?: readonly FoldMembership[];
+    /** Whether responsibility edges are drawn (#557, ADR 0159). */
+    readonly showResponsibility?: boolean;
+}
+/** The drawn relationships: what nesting did not consume, and RACI only if shown. */
+export declare function drawnCanvasEdges(graph: Pick<CanvasGraph, 'edges'>, tree: Pick<FoldTree, 'consumedEdgeIds'>, showResponsibility: boolean): CanvasEdge[];
+/**
+ * The scene's elements for a model, before any view narrows them. What
+ * `graphToElements` builds cytoscape elements from.
+ */
+export declare function canvasSceneInput(graph: CanvasGraph, nesting: readonly NestingKind[], fold?: CanvasSceneFold): CanvasSceneInput;
+/** What one view, with one quick-filter text, puts on screen. */
+export interface CanvasScene {
+    /** The nodes drawn: matched, surviving the filter, pulled in, not folded away. */
+    readonly visibleNodeIds: ReadonlySet<string>;
+    /** Of those, the boxes drawn only to hold something the view matched. */
+    readonly contextNodeIds: ReadonlySet<string>;
+    /** Containment as drawn: a node sits in its box only while both are visible. */
+    readonly parentOf: ReadonlyMap<string, string>;
+    /** For each folded node: how many of what it holds this view selected. */
+    readonly insideCount: ReadonlyMap<string, number>;
+    /** The edges drawn, lifted ones included. */
+    readonly visibleEdgeIds: ReadonlySet<string>;
+    /** For each lifted edge: how many of its relationships this view selected. */
+    readonly liftedCount: ReadonlyMap<string, number>;
+    /**
+     * Edges between a box and something nested in it, left undrawn: the nesting
+     * already says it (ADR 0147). Whether or not they would otherwise draw.
+     */
+    readonly impliedEdgeIds: ReadonlySet<string>;
+    /**
+     * What a saved layout names for this view (#578): the matched subjects and
+     * the boxes that hold them, before the filter or a fold hides any. Null
+     * when no view narrows the canvas.
+     */
+    readonly viewNodeIds: ReadonlySet<string> | null;
+}
+/**
+ * What the canvas shows for a view. `matchedIds` is the view's match set, or
+ * null when no view narrows the canvas; it may name relationships as well as
+ * subjects. An edge draws only where the view selected it AND both its ends
+ * are drawn (#579, ADR 0164).
+ */
+export declare function resolveCanvasScene(input: Pick<CanvasSceneInput, 'nodes' | 'edges'>, matchedIds: readonly string[] | null, quickFilterText: string): CanvasScene;

package/dist/canvas-scene.js

@@ -0,0 +1,175 @@
+import { foldGraph, foldTree } from './fold-tree.js';
+import { spansNesting } from './nesting-span.js';
+import { subjectMatchesQuickFilter } from './subject-filter.js';
+/** The drawn relationships: what nesting did not consume, and RACI only if shown. */
+export function drawnCanvasEdges(graph, tree, showResponsibility) {
+    return graph.edges.filter((edge) => !tree.consumedEdgeIds.has(edge.id) &&
+        (showResponsibility || (edge.responsibility ?? null) === null));
+}
+/**
+ * The scene's elements for a model, before any view narrows them. What
+ * `graphToElements` builds cytoscape elements from.
+ */
+export function canvasSceneInput(graph, nesting, fold = {}) {
+    // CORE kinds, not the authored ones (#473): the rule that decides whether
+    // an assignment may nest reads what a subject IS.
+    const tree = foldTree({
+        nodes: graph.nodes.map((node) => ({
+            id: node.id,
+            kind: node.kind,
+            coreKind: node.coreKindLabel,
+        })),
+        edges: graph.edges,
+        memberships: fold.memberships ?? [],
+        nesting,
+    });
+    // What each box stands for, over the WHOLE tree rather than what a view
+    // shows; `resolveCanvasScene` narrows the chip to the view.
+    const insideIds = new Map();
+    for (const id of tree.parentOf.keys()) {
+        let ancestor = tree.parentOf.get(id);
+        const seen = new Set([id]);
+        while (ancestor !== undefined && !seen.has(ancestor)) {
+            seen.add(ancestor);
+            const held = insideIds.get(ancestor);
+            if (held === undefined)
+                insideIds.set(ancestor, [id]);
+            else
+                held.push(id);
+            ancestor = tree.parentOf.get(ancestor);
+        }
+    }
+    const folded = fold.folded ?? new Set();
+    const nodes = graph.nodes.map((node) => {
+        const parent = tree.parentOf.get(node.id);
+        return {
+            id: node.id,
+            name: node.name,
+            kindLabel: node.kindLabel,
+            ...(parent === undefined ? {} : { parent }),
+            folded: folded.has(node.id),
+            insideIds: insideIds.get(node.id) ?? [],
+        };
+    });
+    const drawn = drawnCanvasEdges(graph, tree, fold.showResponsibility === true);
+    // Every relationship with an end inside a shut box, lifted onto the box
+    // (#473). The originals stay: the view hides them, so opening the box has
+    // nothing to rebuild.
+    const lifted = folded.size === 0
+        ? []
+        : foldGraph({ nodes: graph.nodes, edges: drawn }, tree, folded).edges.flatMap((edge) => 'count' in edge
+            ? [
+                {
+                    id: edge.id,
+                    from: edge.from,
+                    to: edge.to,
+                    relationshipIds: edge.relationshipIds,
+                    liftedKind: edge.kind,
+                },
+            ]
+            : []);
+    return {
+        nodes,
+        edges: [...drawn.map((edge) => ({ id: edge.id, from: edge.from, to: edge.to })), ...lifted],
+        tree,
+    };
+}
+/**
+ * What the canvas shows for a view. `matchedIds` is the view's match set, or
+ * null when no view narrows the canvas; it may name relationships as well as
+ * subjects. An edge draws only where the view selected it AND both its ends
+ * are drawn (#579, ADR 0164).
+ */
+export function resolveCanvasScene(input, matchedIds, quickFilterText) {
+    const nodeById = new Map(input.nodes.map((node) => [node.id, node]));
+    const parentOfModel = (id) => nodeById.get(id)?.parent;
+    const filter = quickFilterText.trim().toLowerCase();
+    // A match set names relationships too; only its subjects seed the nodes.
+    const baseIds = matchedIds === null ? input.nodes.map((node) => node.id) : matchedIds.filter((id) => nodeById.has(id));
+    const baseVisible = new Set(baseIds.filter((id) => {
+        const node = nodeById.get(id);
+        return subjectMatchesQuickFilter(filter, id, node.name, node.kindLabel);
+    }));
+    // A nested part is drawn in its box, so every visible node's ancestor chain
+    // is pulled in.
+    const visible = new Set(baseVisible);
+    for (const id of baseVisible) {
+        const seen = new Set([id]);
+        let ancestor = parentOfModel(id);
+        while (ancestor !== undefined && !seen.has(ancestor)) {
+            seen.add(ancestor);
+            visible.add(ancestor);
+            ancestor = parentOfModel(ancestor);
+        }
+    }
+    // A FOLDED ancestor hides everything under it, whatever the view said
+    // (#473): a reader who shut a box asked not to see inside it.
+    for (const id of [...visible]) {
+        const seen = new Set([id]);
+        let ancestor = parentOfModel(id);
+        while (ancestor !== undefined && !seen.has(ancestor)) {
+            seen.add(ancestor);
+            if (nodeById.get(ancestor)?.folded === true) {
+                visible.delete(id);
+                break;
+            }
+            ancestor = parentOfModel(ancestor);
+        }
+    }
+    // Containment is a rendering device: it holds only while both ends are drawn.
+    const parentOf = new Map();
+    for (const node of input.nodes) {
+        if (node.parent !== undefined && visible.has(node.id) && visible.has(node.parent)) {
+            parentOf.set(node.id, node.parent);
+        }
+    }
+    // The chip counts what THIS VIEW shows: a member hidden by its own box still
+    // counts, one the view never selected does not.
+    const insideCount = new Map();
+    for (const node of input.nodes) {
+        if (!node.folded)
+            continue;
+        insideCount.set(node.id, node.insideIds.filter((id) => nodeById.has(id) && baseVisible.has(id)).length);
+    }
+    const selected = matchedIds === null ? null : new Set(matchedIds);
+    const liftedCount = new Map();
+    for (const edge of input.edges) {
+        if (edge.relationshipIds === undefined)
+            continue;
+        liftedCount.set(edge.id, selected === null
+            ? edge.relationshipIds.length
+            : edge.relationshipIds.filter((id) => selected.has(id)).length);
+    }
+    const viewSelected = (edge) => selected === null ||
+        (edge.relationshipIds !== undefined
+            ? edge.relationshipIds.some((id) => selected.has(id))
+            : selected.has(edge.id));
+    const impliedEdgeIds = new Set(input.edges.filter((edge) => spansNesting(edge.from, edge.to, parentOf)).map((edge) => edge.id));
+    const visibleEdgeIds = new Set(input.edges
+        .filter((edge) => visible.has(edge.from) &&
+        visible.has(edge.to) &&
+        viewSelected(edge) &&
+        !impliedEdgeIds.has(edge.id))
+        .map((edge) => edge.id));
+    let viewNodeIds = null;
+    if (matchedIds !== null) {
+        viewNodeIds = new Set(baseIds);
+        for (const id of baseIds) {
+            let ancestor = parentOfModel(id);
+            while (ancestor !== undefined && !viewNodeIds.has(ancestor)) {
+                viewNodeIds.add(ancestor);
+                ancestor = parentOfModel(ancestor);
+            }
+        }
+    }
+    return {
+        visibleNodeIds: visible,
+        contextNodeIds: new Set([...visible].filter((id) => !baseVisible.has(id))),
+        parentOf,
+        insideCount,
+        visibleEdgeIds,
+        liftedCount,
+        impliedEdgeIds,
+        viewNodeIds,
+    };
+}

package/dist/nesting-span.js

@@ -0,0 +1,29 @@
+/**
+ * Whether an edge's two ends are nested one inside the other (#439, ADR 0139).
+ *
+ * Composition maps onto cytoscape's compound `parent`, so a pair that also
+ * carries any OTHER relationship produces an edge from a container to its own
+ * child. ELK cannot lay that out: measured on a five-concept model, the
+ * container and its child render and every unrelated node loses its geometry.
+ *
+ * Its own module rather than a helper inside `graph-canvas.tsx`, following
+ * `subject-filter.ts`: the canvas is type-checked with JSX and a test that
+ * imports it is not, so pure rules live where a test can reach them.
+ */
+export function spansNesting(from, to, parentOf) {
+    const climbs = (start, target) => {
+        // `resolveNestingParents` already refuses to nest a composition cycle, so
+        // a cycle should be unreachable here. Guarded anyway: the cost of being
+        // wrong is a frozen canvas rather than a bad picture.
+        const seen = new Set();
+        let at = parentOf.get(start);
+        while (at !== undefined && !seen.has(at)) {
+            if (at === target)
+                return true;
+            seen.add(at);
+            at = parentOf.get(at);
+        }
+        return false;
+    };
+    return climbs(from, to) || climbs(to, from);
+}

package/dist/{visual-app-lib/types/visual-app/subject-filter.d.ts → subject-filter.d.ts}

@@ -10,7 +10,7 @@
  * the canvas module registers cytoscape-elk. So the predicate lives in this
  * small pure module and both surfaces import it from here.
  */
-import type { CanvasNode } from "../graph-projection.js";
+import type { CanvasNode } from "./graph-projection.js";
 /**
  * The slice of a subject the predicate reads — the render data both the
  * canvas and the rail already hold.

package/dist/subject-filter.js

@@ -0,0 +1,31 @@
+/**
+ * Typed filter text made comparable: trimmed and lowercased, once, so every
+ * surface trims the same way before matching.
+ */
+export const normalizeFilterText = (text) => text.trim().toLowerCase();
+/**
+ * Whether a subject survives the typed text: case-insensitive, against its
+ * id, name, and kind label. `name` and `kindLabel` are `unknown` because the
+ * canvas reads them out of cytoscape data, which types nothing.
+ */
+export function subjectMatchesQuickFilter(trimmedLowerFilter, id, name, kindLabel) {
+    if (trimmedLowerFilter === "")
+        return true;
+    if (id.toLowerCase().includes(trimmedLowerFilter))
+        return true;
+    if (typeof name === "string" &&
+        name.toLowerCase().includes(trimmedLowerFilter)) {
+        return true;
+    }
+    return (typeof kindLabel === "string" &&
+        kindLabel.toLowerCase().includes(trimmedLowerFilter));
+}
+/**
+ * How many of these subjects survive the typed text — the number a tree row
+ * shows while the filter narrows (#317). With no text every subject
+ * survives, so this is also the plain length.
+ */
+export const countMatchingSubjects = (subjects, filterText) => {
+    const needle = normalizeFilterText(filterText);
+    return subjects.filter((subject) => subjectMatchesQuickFilter(needle, subject.id, subject.name, subject.kindLabel)).length;
+};