Diagram - Search and reveal

Query current-page records and use the graph explorer to select, reveal or inspect unavailable results.

#Usage

import { shallowRef } from 'vue';
import { Diagram, queryDiagramSemanticPage, type DiagramSemanticQuery, type DiagramViewportHandle } from '@primeui/vue-diagram';
import { DiagramExplorerUI } from '@ui/diagram';

const canvas = shallowRef<DiagramViewportHandle | null>(null);
const query: DiagramSemanticQuery = { search: 'Review', offset: 0, limit: 5 };
const results = queryDiagramSemanticPage(store.getSnapshot(), 'page', query);

results is an event-time query result. For live UI, use the copied explorer or recompute from the model ref in a child under Diagram.Root.

Query saved page records independently of mounted node views. Use the active session’s selection, focus, and reveal APIs when the reader chooses a result.

This skeleton assumes an initialized store with page page. Use First Diagram for model creation, style imports and store disposal.

#UI Composition

<Diagram.Root :store="store" page-id="page">
    <DiagramExplorerUI v-if="canvas" :canvas="canvas" />
    <Diagram.Viewport ref="canvas" label="Searchable workflow" style="height: 24rem" />
</Diagram.Root>

canvas is the actual viewport handle used to restore native focus. The copied UI import is application-local. The explorer shares the root's semantic model, selection and session; it does not mount a second copy of every node.

The explorer reads the root’s semantic graph and uses the referenced viewport for reveal. Search results remain available beyond currently mounted rich node views.

#Query the current page with bounded results

Change Search text, Result limit or Result offset. Review matches the named review tasks. Clear the text for all records. The result count distinguishes returned entries from matching records and the page total.

Loading Demo...
import { queryDiagramSemanticPage, type DiagramSemanticQuery } from '@primeui/vue-diagram';

const query: DiagramSemanticQuery = { search: 'Review', offset: 0, limit: 5 };
// queryDiagramSemanticPage(store.getSnapshot(), activePageId, query)
// returns pageName, total, matching, offset and entries.

search is a trimmed, case-insensitive substring, capped at 200 characters. It matches node names (title, first nonempty label or ID), labels, port IDs/titles, record ID, layer name, ancestor names and connected-item text. This is a text query, not a full-text relevance index or a type/tag filter language.

Default limit is 20; it is floored and bounded to 1–50 (a zero result falls back to 20). Offset is floored/nonnegative and clamped to the last available result page; no matches gives offset zero. The query iterates current-page nodes then connectors in model order and returns at most the requested limit. It bounds returned summaries; the query still scans the current page records.

entries expose id, kind, name, context, relationship, available and an optional unavailableReason. Layer and ancestry form context; incoming/outgoing summaries are relationships. A connection is never turned into a tree child. Optional text overrides localized summaries. Supply isVisible(id) from the active geometry when runtime clipping/collapse visibility must be authoritative.

#Use the copied graph explorer

In Graph explorer, search Remote review. Select changes selection while keeping the view; Reveal and focus selects, focuses and recenters on the offscreen task. Return to nearby tasks to compare. Search Backlog or Request review to see containment context separately from graph connections.

Loading Demo...

Import the copied DiagramExplorerUI from your local @ui/diagram path and place DiagramExplorerUI under a root. Its required canvas input is the actual DiagramViewportHandle, used to restore keyboard focus after revealing. The example places it above the canvas without a full editor shell. It uses the existing DiagramExplorerModel for querying and actions.

The copied explorer queries the active page in batches of 20. Editing search resets the offset and feedback; Previous/Next page through current matches. The result list contains record summaries, rather than mounted copies of node components. The offscreen Remote review can be found even before its rich view is mounted. The Archive page remains outside this page's query.

#Understand selection, focus and reveal

session.select([id]) changes selection. session.focus(id) supplies a keyboard focus identity. session.reveal(id) recenters at the existing zoom; it does not zoom to fit or select automatically. The copied explorer's Reveal and focus action combines all three and focuses the canvas. For navigation mechanics see Pan and Zoom.

This example initially fits nearby Request and Backlog only. Fit fits the current visible page; Return to nearby tasks repeats the local framing. Auto-fit remains one-shot in examples that enable it. Offscreen availability is about model/ scene visibility, not whether a rich DOM view is mounted; see Virtualization.

#Report hidden and collapsed results honestly

Collapse Backlog or hide the Audit layer, then search their children. The saved records remain in results with a reason, but copied Select/Reveal actions disable for unavailable entries. It also checks active geometry visibility for fully clipped or otherwise unavailable items. Locked visibility is different from edit permission; a visible locked record can still be a query result.

The Core reveal method may resolve a collapsed descendant to its visible ancestor. The copied explorer deliberately does not reveal unavailable results. Expand or show the owner through the proper container or layer command before choosing that child. Results can change after edits; the model rechecks the current entry and gives changed/unavailable feedback rather than acting on a stale row.

See Page links, Selection and the editor example for fuller composition.