107 lines
6.2 KiB
ReStructuredText
107 lines
6.2 KiB
ReStructuredText
Diagram representation navigation
|
|
=================================
|
|
|
|
This contract derives from user issues `14: Text symbol usages
|
|
<http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/issues/14>`_
|
|
and `17: tree-to-diagram navigation
|
|
<http://217.177.34.108:3000/sorokin.oleg.edu/ARCADIA-Studio/issues/17>`_.
|
|
Implementation and acceptance status belong to those issues. The source language
|
|
and identity rules remain in ``language.rst``.
|
|
|
|
Identity and membership
|
|
-----------------------
|
|
|
|
A result identifies the queried subject, a diagram destination, and a specific
|
|
graphical representation. A destination is a saved diagram UUID, a process or
|
|
functional-chain UUID, or a scenario UUID. Saved state diagrams retain their own
|
|
diagram UUID; membership in the same state machine does not make their contents
|
|
interchangeable.
|
|
|
|
Representation identities are node placement, port plus owner placement, edge,
|
|
state row plus owner placement, process occurrence plus qualified reference path,
|
|
process link, or scenario lifeline/occurrence. Opening an owner itself is a
|
|
separate whole-diagram target. Names and aliases describe these identities; they
|
|
are never replacement identities. Repeated occurrences remain independently
|
|
selectable even when they represent the same activity or exchange.
|
|
|
|
The current renderer determines membership:
|
|
|
|
* Saved node, port, and edge results come from the final projection, including
|
|
folds, projection-kind rules, and view filters. A stored route or two placed
|
|
endpoints does not establish a visible edge.
|
|
* Process results use the displayed contribution graph. A contextual preview
|
|
retains its full caller path and is included only while its actual tile is
|
|
present. An inactive process uses the same initial preview policy as entering
|
|
its canvas. Preview adjacency has no invented relation UUID.
|
|
* Scenario results use the actual scene, preserving lifeline and message
|
|
occurrence identities, nested fragment operands, and repeated messages.
|
|
A scenario-reference box represents its called scenario. It does not also
|
|
represent the called scenario's messages or lifelines.
|
|
* State action and internal-transition rows retain their relation identity.
|
|
Visible named references, such as a state action's work or a transition's
|
|
trigger, can target the row or edge whose label displays that reference.
|
|
Label-only membership must account for the renderer's shortening policy.
|
|
|
|
An arbitrary semantic reference is insufficient. A description mentioning a
|
|
name, an exchange item hidden by the selected label mode, or an unexpanded callee
|
|
does not automatically add a diagram result. The result count describes
|
|
currently rendered representations, not all semantic dependencies. Folded,
|
|
filtered, and unexpanded representations are explicitly excluded by this version;
|
|
an empty result must disclose this scope and must not claim that an object is
|
|
unused everywhere. Semantic dependencies remain available through Connections.
|
|
|
|
Two additional representation forms remain gaps in this branch: allocation
|
|
relations expressed through nesting, and persisted sequence links drawn inside
|
|
qualified caller previews. These must either receive precise grouping/qualified
|
|
edge targets or remain explicitly disclosed limitations; a passing direct-edge
|
|
test does not establish their coverage.
|
|
|
|
Interaction and lifecycle
|
|
-------------------------
|
|
|
|
``Show in diagrams`` opens one searchable destination list from the Text caret,
|
|
an object's context/Actions menu, or Connections. It identifies the subject by
|
|
name and alias, groups targets by destination, reports counts, and presents a
|
|
bounded page. A destination then exposes its individual representations. Search
|
|
matches destination names, aliases, categories, representation names, and roles.
|
|
Long descriptions remain available without replacing stable identities.
|
|
|
|
The Text entry point uses the exact current caret and the source-symbol service's
|
|
immutable snapshot. It requires a unique, validated, included declaration whose
|
|
authored identity and alias still match the accepted model. It never substitutes
|
|
the previously selected tree object. Unapplied source is retained with an explicit
|
|
instruction to apply it before diagram lookup. Comment, prose, ambiguous, missing,
|
|
detached, and stale symbols cannot trigger a diagram jump.
|
|
|
|
Every open request captures the document instance, accepted revision, and subject.
|
|
Every chooser action captures that chooser's unique token. Before opening a
|
|
representation, re-resolve the full subject-to-target relationship and renderer
|
|
geometry. If the model or presentation changed, refresh the list and require a
|
|
fresh choice. Matching names, reused aliases, or surviving endpoints cannot make
|
|
a stale target current. An asynchronous source response must also match its job,
|
|
source session/revision, raw interaction, active file, and caret.
|
|
|
|
Lookup and reveal do not execute model commands, Apply, Revert, or Save. They do
|
|
not expand persisted folds, change filters, rewrite source, or alter undo/redo.
|
|
Pending edits that would be displaced prevent the jump and remain intact.
|
|
Successful reveal updates only the navigation owner/page, precise selection,
|
|
tool lifetime, and camera. The camera centers the target at a readable scale;
|
|
fitting a huge whole diagram is not sufficient evidence of locating one object.
|
|
Escape closes the chooser and restores Text focus/caret when invoked there.
|
|
|
|
Verification obligations
|
|
------------------------
|
|
|
|
Independent fixtures must cover actual versus filtered edges, folded children,
|
|
ports, same-name distinct identities, repeated work/message/lifeline occurrences,
|
|
qualified reuse paths, opaque scenario references, state rows and label references.
|
|
For each activation, compare the complete accepted Project, SourceBundle, raw
|
|
buffers, revision, dirty flags, and undo/redo reachability before and after.
|
|
Exercise stale document/revision/token/subject relationships and retained drafts.
|
|
|
|
Native acceptance additionally checks keyboard and pointer selection, exact
|
|
visible target highlight, camera behavior after the destination's first layout,
|
|
empty and multi-result states, readable long Unicode names, minimum-window layout,
|
|
return to editing, and representative large-model latency. Unit tests and a
|
|
successful build do not by themselves establish these interaction outcomes.
|