Code reference detail
graph-cy-controller.ts
packages/extension/webviews/shared/graph/graph-cy-controller.ts
| Idea | Status | Tags | Summary | Katz |
|---|---|---|---|---|
| imperative_view_controllers | done | Heavy imperative widgets ( Cytoscape graph ) keep lifecycle state on a controller class ( `GraphCyController` ), not inside AppState `$state` fields. AppState holds query / slice / loading / error and persisted UI prefs; the component holds the controller instance. See ["../extension/presentation/graph.rq".webview_threading] and ["../extension/workspace-summary/ideas_summary/graphical_graph.rq".graph_loading]. | 0.040 | |
| scope | TypeScript package standards for `packages/extension` ( npm `reqlan-extension` ), especially UI state. Complements [development_core.rust_mindset] and [extension_architecture.state_machine_mindset]. Webview inventory: [webview_doc.webview]. Package role: [core_architecture.extension_package]. | 0.040 | ||
| graph_cy_controller | the cytoscape object should use event driven patterns; lifecycle is documented here. GraphCyController in ["../../../packages/extension/webviews/shared/graph/graph-cy-controller.ts"] owns the cytoscape instance with inline lifecycle state ( idle, syncing, layouting, physics ). syncGeneration cancels stale layout callbacks when the slice changes mid-layout. Selection and drag-pinned positions are tracked in userPositionedNodes on the controller. syncSlice diffs elements ( add / remove / update the delta ) via ["../../../packages/extension/webviews/shared/graph/graph-cy-elements.ts"] so surviving nodes keep positions; requestLayout restarts the active algorithm and clears user pins. Pointer / selection wiring lives in ["../../../packages/extension/webviews/shared/graph/graph-cy-interactions.ts"]; compound hover / selection / title-hit in ["../../../packages/extension/webviews/shared/graph/graph-cy-highlight.ts"]. Compound grab / drag / free pins and unpins all childless descendants so live physics does not snap members back while the container moves; released child positions are stored in userPositionedNodes. File compounds ( `isFileCompound` ): title-band tap or double-tap opens the hosting `.rq` via onOpen ( compoundId ); GraphView resolves `compound:rq-file:…` to a file URI. Live physics is the custom simulation in ["../../../packages/extension/webviews/shared/graph/graph-physics.ts"]; one instance persists with the cytoscape instance and is paused / resumed, never rebuilt. Grabbing a node pins it in the running sim ( its live position keeps exerting forces ); release unpins with no restart and no snap. ResizeObserver debounces cy. resize ( ) and re-triggers a pending sync when the container gains size. Mount only while the graph container is visible and non-zero — do not keep cytoscape alive under display: none; WebGL init on a zero-size hidden container can break the host webview before messaging is attached. Viewport fitting per [reframe_view]; tracks lastSyncedNodeSetKey vs fittedNodeSetKey to drive [auto_reframe]. Label visibility per [graph_label_modes] / [graph_label_auto]: setLabelMode updates text-opacity from zoom ( and hover / drag force-opaque in auto ). | 0.103 | ||
| graph_design | The graph should show nodes for ideas and files and edges for references. Used by Ideas Summary, activity-bar minigraph, and export previews. | 0.040 | ||
| graph_label_auto | done | In Labels auto mode, visibility follows viewport zoom continuously rather than a hard cut. ( fade ) Below a low zoom threshold labels are fully hidden; above a slightly higher threshold they are fully opaque; between those thresholds opacity ramps briefly through a muted / semi-transparent phase ( GRAPH_LABEL_FADE_START → GRAPH_LABEL_FADE_END ). Labels start fully invisible during graph initialisation and layout settling so text paint does not lag those phases; zoom fade only applies once settle / reframe has finished. Hovered or dragged nodes remain fully opaque even when ambient auto opacity is low or zero. Zoom and Fit from [view_controls] / [reframe_view] must update this opacity on each paint or zoom event. Applies to Ideas Summary GraphCyController and HTML export canvas graph alike. | 0.184 | |
| graph_label_modes | done | Every interactive graph should provide a Labels control that cycles auto ( default ), on, and off without changing graph membership. On forces full opacity; off hides all labels; auto follows [graph_label_auto]. Reset / default restore auto. Ideas Summary: control in ["../../../packages/extension/webviews/ideas-summary/components/GraphControls.svelte"], mode persisted via ["../workspace-summary/ideas_summary/graphical_graph.rq".graph_ui_persistence]. HTML export: control in ["../../../crates/reqlan-export/src/html_template/mod.rs"] / ["../../../crates/reqlan-export/assets/app.js"]. Driven by the same viewport zoom as [view_controls]. | 0.148 | |
| graph_library | Reusable cytoscape-based graph visualization library for force-directed and compound graphs. Provides a mount → sync slice → layout → optional live physics → destroy lifecycle with a simplified API. Implementation lives in ["../../../packages/extension/webviews/shared/graph/graph-cytoscape.ts"], ["../../../packages/extension/webviews/shared/graph/graph-cy-controller.ts"], ["../../../packages/extension/webviews/shared/graph/graph-cy-elements.ts"], ["../../../packages/extension/webviews/shared/graph/graph-cy-interactions.ts"], ["../../../packages/extension/webviews/shared/graph/graph-cy-highlight.ts"], ["../../../packages/extension/webviews/shared/graph/graph-physics.ts"], ["../../../packages/extension/webviews/shared/graph/graph-groups.ts"], and ["../../../packages/extension/webviews/shared/graph/graph-theme.ts"]. Ideas Summary re-exports the shared modules from ["../../../packages/extension/webviews/ideas-summary/lib/"] for backward-compatible import paths. Consumers pass a node / edge slice and sync options; the library owns the cytoscape instance, diffing, layout runs, and optional continuous physics. | 0.064 | ||
| reframe_view | Shared viewport behaviour for every surface that mounts GraphCyController ( Ideas Summary graph tab, activity bar mini graph, and future consumers ). Implementation: reframeGraphToViewport and GraphCyController. reframeToViewport in ["../../../packages/extension/webviews/shared/graph/graph-cy-controller.ts"]. [manual_reframe] [auto_reframe] [reframe_animation] Constants: GRAPH_VIEWPORT_PADDING ( 36 px padding around the element bounding box ), GRAPH_REFRAME_ANIMATION_MS ( 400 ms animated transition ). Reframes resize the cytoscape container first, then fit all elements and centre the camera. Does not clear selection, centreId, user-pinned drag positions, or live physics state — viewport only. | 0.118 | ||
| file_treatment_toggle | done | Toolbar dropdown selects how hosting `.rq` files ( implicit ideasets ) appear in the graph — distinct from explicit AST `ideaset` declarations and from external `file:` reference nodes. Options ( with info tooltips / help text ): - invisible / Hidden — no file containers or file leaf nodes; ideas float free - compound — one compound parent per hosting file ( basename label ); nests under folder / tag compounds when Controls → Compound is also on. Containers are draggable ( members move with the box; live physics pins descendants while dragging ). Clicking the title opens the file; double-click also opens. - linked / Linked nodes ( default ) — synthetic ideaset-styled leaf per hosting file ( `rq-file:…` ) with `ideaset_member` edges to ideas in that file; click / dbl-click opens the hosting file like other nodes. Client reshape via `applyFileTreatment` in ["../../../../packages/extension/webviews/shared/graph/file-treatment.ts"]; no re-query on mode flip. Ideas Summary: `FileTreatmentSelect` on GraphControls; persisted as `fileTreatment` in [graph_ui_persistence]. HTML export: same three options via a select; compound boxes are hittable / draggable with clickable titles; linked nodes carry `pageUrl` / `hostFilePageUrl` for navigation. Related: [graphical_graph], [ui_controls], [webview_export_graph_parity], ["../../../ontology.rq".file], ["../../../ontology.rq".ideaset], [html_export_graph_page]. | 0.170 | |
| graphical_graph | There should be a tab that renders requirement ideas and references as a force-directed web. The graph tab lives in the Ideas Summary webview per [ideas_summary]. UI is implemented in ["../../../../packages/extension/webviews/ideas-summary/components/GraphView.svelte"]. Graph slices are built in ["../../../../packages/analytical/src/index-store/webview-graph-queries.ts"] and served by ["../../../../packages/extension/src/ideas_summary_module/ideas-summary-panel.ts"]. By default the view focuses on the active editor file's first idea; without a focus it shows a capped slice of matching ideas rather than dumping the full graph. Users can filter by search text, path, multi-select @ status, and multi-select tags per [graph_status_tag_filters]. An " Indirect references " toggle expands neighbourhood depth from 1 to 2 hops. A " Wildcard refs " toggle includes or hides edges expanded from path + idea wildcards per [wildcard_refs_toggle] ["@/reqlan rq/language/imports.rq".wildcard_references] A " Files " dropdown selects hosting- `.rq` treatment per [file_treatment_toggle] ( hidden / compound containers / linked ideaset nodes ), with per-option info tooltips. Interactive graph controls that also exist on HTML export must stay aligned per [webview_export_graph_parity]. Clicking a node opens its source; double-click or " Focus graph " recenters the slice on that idea. Linked file ideaset nodes and file-compound titles open the hosting `.rq` file per [file_treatment_toggle]. External file references render as dashed edges to file nodes; wildcard-fan-out edges render dotted. A toggleable key explains node colours and edge styles and toggles node-type visibility per [key_panel_toggle]; a toggleable [control_panel] exposes layout, physics, and node-budget settings. Key and Controls state persist per workspace via [graph_ui_persistence]. Pan, zoom, and drag repositioning per [view_controls]. [manual_reframe] via " Fit to view " in [ui_controls]; [auto_reframe] when the loaded node set changes; [reframe_animation] for smooth transitions after the first paint. Node text labels per [graph_labels], [graph_label_modes], and [graph_label_auto]. Layout, compound grouping, and live physics behaviour per [layout_physics], [layout_options], [physics_options], and [compound_graph]. Cytoscape lifecycle and threading constraints per [graph_cy_controller] and [webview_threading]. | 0.207 | ||
| key_panel_toggle | the key panel should be able to toggle inclusion / visibility of the different node types. Node-type rows in ["../../../../packages/extension/webviews/ideas-summary/components/GraphKeyPanel.svelte"] are toggle buttons; hidden types render dimmed with a struck-through label. Toggleable types are block, one-liner, ideaset, focused idea, and external file — GraphNodeTypeId in ["../../../../packages/extension/webviews/shared/graph/graph-theme.ts"], classified per node by graphNodeTypeId ( same priority as node fill colour ). Linked file ideaset nodes ( `isFileIdeaset` ) classify as ideaset for Key toggles; file compound containers are legend-only ( " File group " ) and follow member visibility like other compounds. GraphView tracks hidden types and calls GraphCyController. setHiddenNodeTypes in ["../../../../packages/extension/webviews/shared/graph/graph-cy-controller.ts"], which flags matching nodes with data typeHidden; a display: none stylesheet rule in ["../../../../packages/extension/webviews/shared/graph/graph-cytoscape.ts"] hides them, and cytoscape hides edges whose endpoint is hidden. Compound containers whose members are all hidden are hidden too. Hiding is client-side visibility only: the slice still contains the nodes, node / edge counts are unchanged, and flags reapply after every slice sync. Key open state and hidden node types persist per [graph_ui_persistence]. | 0.067 |
Reference labels
"../../../../packages/extension/webviews/shared/graph/graph-cy-controller.ts", "../../../packages/extension/webviews/shared/graph/graph-cy-controller.ts", "../../packages/extension/webviews/shared/graph/graph-cy-controller.ts", ../../../../packages/extension/webviews/shared/graph/graph-cy-controller.ts, ../../../packages/extension/webviews/shared/graph/graph-cy-controller.ts, ../../packages/extension/webviews/shared/graph/graph-cy-controller.ts