Publish in-progress navigation source and independent canvas reviews
This commit is contained in:
@@ -0,0 +1,106 @@
|
||||
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.
|
||||
Reference in New Issue
Block a user