@petrarca/sonnet-graph 0.7.0 → 0.9.0

package/dist/index.d.ts

@@ -1,10 +1,9 @@
-import * as zustand from 'zustand';
-import { UseBoundStore, StoreApi } from 'zustand';
 import * as React from 'react';
 import React__default, { ReactNode } from 'react';
+import * as zustand from 'zustand';
+import { UseBoundStore, StoreApi } from 'zustand';
 import { GraphEdge, GraphNode } from 'reagraph';
 import cytoscape from 'cytoscape';
-import * as react_jsx_runtime from 'react/jsx-runtime';
 import { z } from 'zod';
 import { JsonSchema, UISchema } from '@petrarca/sonnet-core/schema';
 import { WidgetRegistry } from '@petrarca/sonnet-forms';
@@ -272,6 +271,107 @@ declare function normalizeGraph(nodes: VisualGraphNode[], edges: VisualGraphEdge
  */
 declare const EMPTY_NORMALIZED: VisualGraphNormalized;
 
+/**
+ * Extracts graph elements from tabular Cypher query rows.
+ *
+ * cypher-graphdb (the underlying graph-database library) serializes a
+ * node/relationship RETURN-column value wrapped as `{ node: RawGraphNode }` /
+ * `{ edge: RawGraphEdge }` (its `serialize_model(with_type=True)` default,
+ * shared by every consumer of a cypher-graphdb-backed Cypher endpoint) --
+ * scalar columns (a property projection, an aggregate) are unwrapped plain
+ * values. A host whose backend returns query results as plain tabular rows
+ * (rather than a pre-shaped `{ nodes, edges }` response) uses this to decide
+ * whether a result is graph-shaped at all and to collect its elements, deduped
+ * by `id_` (the same node/edge commonly repeats across rows).
+ */
+interface ExtractedGraphRows {
+    nodes: RawGraphNode[];
+    edges: RawGraphEdge[];
+    /** True if any row cell was a wrapped node/edge -- the result has something to draw. */
+    isGraph: boolean;
+}
+/** Scan tabular rows (each an array of RETURN-column cell values) for wrapped node/edge cells. */
+declare function extractGraphFromRows(rows: unknown[][]): ExtractedGraphRows;
+
+/**
+ * QueryEditor -- a pure, reusable query editor (no store or app dependencies).
+ *
+ * A props-based editor for graph query languages (Cypher, Datalog, ...): an
+ * auto-sizing textarea, Ctrl/Cmd+Enter to execute, an inline error alert with
+ * copy-to-clipboard, and an optional custom action-button slot. Every host
+ * (an app's own query bar, a graph workbench) drives it purely through props,
+ * so it carries none of the caller's state.
+ *
+ * Promoted into sonnet-graph from the cypher-graphdb explorer, decoupled from
+ * that app's clipboard hook (uses sonnet-core's copyTextToClipboard).
+ */
+
+interface QueryEditorProps {
+    /** Current query text value. */
+    value: string;
+    /** Called when the user executes (Ctrl/Cmd+Enter or the Run button). */
+    onExecute: (query: string) => void;
+    /** Called when the query text changes. */
+    onChange?: (query: string) => void;
+    /** Whether execution is in progress. */
+    isLoading?: boolean;
+    /** Error message to display (null = none). */
+    error?: string | null;
+    /** Placeholder for the empty editor. */
+    placeholder?: string;
+    /** Minimum rows (default 1). */
+    minRows?: number;
+    /** Maximum rows before the textarea scrolls (default 12). */
+    maxRows?: number;
+    /** Extra class on the wrapper. */
+    className?: string;
+    /** Custom action buttons (replaces the default Run button). */
+    renderActions?: (props: {
+        onExecute: () => void;
+        isLoading: boolean;
+    }) => React__default.ReactNode;
+}
+declare function QueryEditor({ value, onExecute, onChange, isLoading, error, placeholder, minRows, maxRows, className, renderActions, }: QueryEditorProps): React__default.ReactElement;
+
+/**
+ * createQueryHistoryStore -- a persisted list of recently-run query strings.
+ *
+ * A reusable Zustand store factory for a graph query editor's history: add()
+ * prepends (de-duping repeats), the list is capped, and it persists to
+ * localStorage under a caller-chosen key so history survives reloads. Language-
+ * and backend-agnostic (it stores plain query text), so any editor -- Cypher,
+ * Datalog -- can use it. The consuming app creates one instance and shares it
+ * between the query bar (which add()s on run) and the History dropdown.
+ */
+
+interface QueryHistoryState {
+    queries: string[];
+    add: (query: string) => void;
+    clear: () => void;
+}
+type QueryHistoryStore = UseBoundStore<StoreApi<QueryHistoryState>>;
+/**
+ * Build a persisted query-history store.
+ *
+ * @param persistKey localStorage key (unique per editor, e.g. "graph-query-history").
+ * @param limit max entries to retain (default 50).
+ */
+declare function createQueryHistoryStore(persistKey: string, limit?: number): QueryHistoryStore;
+
+/**
+ * QueryHistory -- a dropdown of recently-run queries.
+ *
+ * Reads a QueryHistoryStore (created by createQueryHistoryStore) and lets the
+ * user pick a past query (onSelect) or clear the list. Presentational + store-
+ * bound only; the consuming app decides what onSelect does (typically: load the
+ * query into the editor). Designed to sit in a QueryEditor's renderActions slot.
+ */
+
+declare function QueryHistory({ store, onSelect, }: {
+    store: QueryHistoryStore;
+    onSelect: (query: string) => void;
+}): React__default.ReactElement;
+
 /**
  * Extract display label from a node or edge using resolved display config.
  *
@@ -880,23 +980,23 @@ interface GraphVisualizerProps {
     /** Fetch distinct edge types for a node (for expand options panel). */
     getNodeEdgeTypes?: (id: number) => Promise<string[]>;
 }
-declare function GraphVisualizer({ onCopyNode, extraToolbarContent, getNodeEdgeTypes, }: GraphVisualizerProps): react_jsx_runtime.JSX.Element;
+declare function GraphVisualizer({ onCopyNode, extraToolbarContent, getNodeEdgeTypes, }: GraphVisualizerProps): React.JSX.Element;
 
 interface ActionPanelProps {
     /** Optional actions rendered at the top of the panel (e.g. CRUD buttons) */
     actions?: ReactNode;
 }
-declare function ActionPanel({ actions }: ActionPanelProps): react_jsx_runtime.JSX.Element;
+declare function ActionPanel({ actions }: ActionPanelProps): React.JSX.Element;
 
 type Props$1 = {
     node: VisualGraphNode;
 };
-declare function NodeInfoCard({ node }: Props$1): react_jsx_runtime.JSX.Element;
+declare function NodeInfoCard({ node }: Props$1): React.JSX.Element;
 
 type Props = {
     edge: VisualGraphEdge;
 };
-declare function EdgeInfoCard({ edge }: Props): react_jsx_runtime.JSX.Element;
+declare function EdgeInfoCard({ edge }: Props): React.JSX.Element;
 
 /** A named group of node labels shown as its own legend sub-section. */
 interface NodeLabelBucket {
@@ -910,7 +1010,22 @@ interface OverviewProps {
     /** Heading for the edge (arrow) section. Default "Relations". */
     edgeSectionTitle?: string;
 }
-declare function Overview({ nodeBuckets, edgeSectionTitle }?: OverviewProps): react_jsx_runtime.JSX.Element | null;
+declare function Overview({ nodeBuckets, edgeSectionTitle }?: OverviewProps): React.JSX.Element | null;
+
+/**
+ * CenteredMessage -- a message centered in the pane it fills: empty states,
+ * "cannot display" notices, loading placeholders, and error text. One component
+ * so every graph pane (and host apps' own loading/error states) look the same.
+ */
+
+declare const TONE: {
+    readonly muted: "text-muted-foreground";
+    readonly destructive: "text-destructive";
+};
+declare function CenteredMessage({ children, tone, }: {
+    children: React__default.ReactNode;
+    tone?: keyof typeof TONE;
+}): React__default.ReactElement;
 
 interface GraphA11yListProps {
     /** Render on-screen instead of visually-hidden (still a11y-present). */
@@ -921,7 +1036,7 @@ interface GraphA11yListProps {
     maxHeight?: number;
     className?: string;
 }
-declare function GraphA11yList({ visible, rowHeight, maxHeight, className, }: GraphA11yListProps): react_jsx_runtime.JSX.Element;
+declare function GraphA11yList({ visible, rowHeight, maxHeight, className, }: GraphA11yListProps): React.JSX.Element;
 
 /**
  * Graph model (metamodel) types.
@@ -1961,4 +2076,526 @@ interface DeleteNodeDialogProps {
 }
 declare function DeleteNodeDialog({ open, onOpenChange, node, port, onDeleted, }: DeleteNodeDialogProps): React__default.ReactElement;
 
-export { ActionPanel, type ActionPanelState, type ActionPanelStore, type CapabilitiesValidation, type Cardinality, type ColorPalette, type CreateEdgeInput, type CreateNodeInput, type CreateNodeWithRelationsInput, type CreateNodeWithRelationsResult, DeleteNodeDialog, type DeleteNodeDialogProps, EMPTY_NORMALIZED, EdgeFormSheet, type EdgeFormSheetProps, EdgeInfoCard, type EdgeTypeMode, type EdgeTypeView, type EdgeVisual, type EditMode$1 as EditMode, type EditableMode, type ExpandOptions, type ExpandResult, GraphA11yList, type GraphA11yListProps, type GraphCapabilities, type GraphCapabilitiesValidation, type GraphDataHook, type GraphDataStore, type GraphDisplayConfig, type EditMode as GraphEditMode, GraphEditToolbar, type GraphEditToolbarProps, type GraphExplorationDeps, type GraphExplorationStore, type GraphFilterStore, type GraphFocusAction, type GraphFocusStore, type GraphModel, type GraphModelCapabilities, type GraphModelDisplay, GraphModelEditor, type GraphModelEditorProps, type GraphModelProperty, type GraphMutationPort, type GraphProperties, type GraphProperty, type GraphRelation, type GraphRenderer, GraphRendererProvider, type GraphSchemaProvider, type GraphStatistics, type WorkspaceStores as GraphStoreBundle, GraphStoresContext, type GraphTypeSchema, GraphVisualizer, type GraphVisualizerProps, type LabelDisplayMap, type LiveGraphDataResult, ModelActionPanel, type ModelActionPanelProps, type ModelGraph, NodeFormSheet, type NodeFormSheetProps, NodeInfoCard, NodeTypeNameSheet, type NodeTypeNameSheetProps, type NodeTypeView, type NodeVisual, type NormalizedGraph, Overview, PropertyFormSheet, type PropertyFormSheetProps, type PropertyInput, type PropertyView, type RawGraphEdge, type RawGraphNode, type RelationCardinality, type RelationDef, type RelationDetailView, RelationFormSheet, type RelationFormSheetProps, type RelationInput, type RelationMap, type RelationView, type ResolvedCapabilities, type ResolvedGraphCapabilities, type SelectionStore, type StoreFactory, TypeDetailPanel, type TypeDetailPanelProps, type UpdateEdgeInput, type UpdateNodeInput, type UpdateNodeWithRelationsInput, type UpdateNodeWithRelationsResult, type VisualGraphEdge, type VisualGraphNode, type VisualGraphNormalized, type WorkspaceStores, type XGraph, addEdgeType, addNodeType, addRelation, buildColorPalette, buildColorPaletteFromNodes, capabilitiesSchema, cardinalityLabel, createActionPanelStore, createGraphDataStore, createGraphExplorationStore, createGraphFilterStore, createGraphFocusStore, createSelectionStore, deleteEdgeType, deleteEdgeTypeProperty, deleteNodeProperty, deleteNodeType, deleteRelation, deleteRelationProperty, edgeTypeView, editableRelations, enrichEdge, enrichEdges, enrichNode, enrichNodes, enrichSchemaWithRelations, extractDisplayLabel, extractRelationFields, findEdgeType, findType, graphCapabilitiesSchema, groupEdgesByRelation, hasProperties, hasRelationFields, initializeFormData, isEdgeType, isNodeType, isRawGraphNode, isRelationField, isVisualEdge, isVisualNode, modelToGraph, nodeTypeView, normalizeGraph, reconcileFilter, relationFieldName, relationTitle, relationTypeFromField, relationView, renameEdgeType, renameNodeType, resolveCapabilities, resolveGraphCapabilities, resolveRelationEdge, setEdgeTypeProperty, setNodeProperty, setRelationProperty, toCytoscapeEdge, toCytoscapeNode, toReagraphEdge, toReagraphNode, typeLabel, updateRelation, useActionPanelStore, useCytoscapeData, useGraphFocus, useGraphRenderer, useLiveGraphData, useReagraphData, useStableRef, useWorkspaceGraphData, useWorkspaceGraphExploration, useWorkspaceGraphFilter, useWorkspaceGraphFocus, useWorkspaceSelection, validateCapabilities, validateGraphCapabilities };
+/**
+ * GraphFinder -- locate nodes and edges within the currently loaded graph.
+ *
+ * Three modes:
+ * - Full-Text: natural-language, typo-tolerant search (Orama index over all
+ *   loaded elements).
+ * - Expression: MistQL pipe expressions over the flattened graph
+ *   (e.g. ``Person | filter name == "John"``). Collections available:
+ *   nodes/edges/graph (all), vnodes/vedges/vgraph (visible only), and each
+ *   label (Person, ACTED_IN, ...).
+ * - Both: expression filters first, then full-text searches that subset.
+ *
+ * Results are click-to-focus, double-click-to-focus-and-select on the canvas.
+ * Renderer-agnostic: uses only the workspace stores and live graph data.
+ */
+
+declare function GraphFinder(): React__default.ReactElement;
+
+/**
+ * Graph finder types.
+ *
+ * Type definitions for the client-side graph finder: the Orama full-text
+ * index over the loaded nodes/edges, its documents, results, and options.
+ */
+/**
+ * Orama document structure for indexing nodes and edges.
+ *
+ * Contains fallback fields (always present) that make any node/edge
+ * searchable without a data-model schema.
+ */
+interface OramaDocument {
+    /** Unique ID (node or edge ID) */
+    id_: string;
+    /** Type: 'node' or 'edge' */
+    type: "node" | "edge";
+    /** Label (e.g. 'Person', 'ACTED_IN') */
+    label_: string;
+    /** Display name for UI */
+    displayName: string;
+    /** Concatenated text from all properties for full-text search */
+    searchableText: string;
+    /** JSON-stringified properties (fallback field) */
+    properties_json: string;
+    /** Whether this item is currently visible in the graph */
+    isVisible: boolean;
+    /** Start node ID (edges only) */
+    start_id_?: string;
+    /** End node ID (edges only) */
+    end_id_?: string;
+}
+/** A finder full-text result with relevance score. */
+interface OramaSearchResult {
+    /** The matched document */
+    document: OramaDocument;
+    /** Relevance score (higher = more relevant) */
+    score: number;
+    /** Matched terms (for highlighting) */
+    positions?: Record<string, unknown>;
+}
+/** Finder index statistics for status display. */
+interface ServiceStats {
+    totalIndexed: number;
+    nodesIndexed: number;
+    edgesIndexed: number;
+    /** Timestamp of last index build */
+    lastIndexBuild: number | null;
+    /** Whether the index is ready to search */
+    isReady: boolean;
+}
+/** Configuration for the finder's Orama search service. */
+interface OramaSearchServiceConfig {
+    /** Enable debug logging (default: false) */
+    debug?: boolean;
+    /** Maximum nodes to index -- safety limit (default: 100000) */
+    maxNodes?: number;
+    /** Lazy initialization -- only build when needed (default: true) */
+    lazyInit?: boolean;
+}
+/** Options for a full-text finder query. */
+interface SearchOptions {
+    /** Search term (natural language query) */
+    term: string;
+    /** Filter by node/edge labels (optional) */
+    labels?: string[];
+    /** Only search visible items (default: false) */
+    visibleOnly?: boolean;
+    /** Maximum number of results (default: 50) */
+    limit?: number;
+    /** Include edge results (default: true) */
+    includeEdges?: boolean;
+    /** Include node results (default: true) */
+    includeNodes?: boolean;
+    /** Custom field boosting (optional) */
+    boost?: Record<string, number>;
+}
+/**
+ * Visibility tracking subset used when building documents.
+ * A subset of the normalized graph shape.
+ */
+interface NormalizedData {
+    hiddenNodeIds: Set<string>;
+    hiddenEdgeIds: Set<string>;
+}
+
+/**
+ * useGraphSearch -- full-text finder over the currently loaded graph.
+ *
+ * Wraps an OramaSearchService whose index is built on demand: not when the
+ * finder opens, only when the user actually runs a full-text search. The
+ * index covers ALL nodes/edges from the last query (``baseNormalized``, the
+ * same source expression mode uses), independent of label filters or focus.
+ * When the underlying data changes the index is marked dirty and rebuilt on
+ * the next search.
+ */
+
+interface UseGraphSearchReturn {
+    /** Run a full-text search; builds/rebuilds the index on demand. */
+    search: (query: string, options?: Omit<SearchOptions, "term">) => Promise<OramaSearchResult[]>;
+    /** Whether the index is initialized and current. */
+    isReady: boolean;
+    /** Whether the index is being (re)built. */
+    isIndexing: boolean;
+    /** Current index statistics (null before first build). */
+    stats: ServiceStats | null;
+    /** Any initialization/indexing error. */
+    error: Error | null;
+}
+declare function useGraphSearch(): UseGraphSearchReturn;
+
+/**
+ * Orama full-text index for the graph finder.
+ *
+ * Maintains a client-side Orama index over the nodes/edges currently loaded
+ * from a query. Uses a full rebuild when the index becomes dirty (simple and
+ * fast for typical graphs) and lazily initializes only when first searched.
+ */
+
+declare class OramaSearchService {
+    private db;
+    private config;
+    private isDirty;
+    private isInitialized;
+    private lastIndexBuild;
+    private stats;
+    constructor(config?: OramaSearchServiceConfig);
+    /** Create the empty index with the finder schema (idempotent). */
+    initialize(): Promise<void>;
+    /** Drop all documents (recreates the index; Orama has no bulk delete). */
+    clear(): Promise<void>;
+    /** Mark the index stale so the next search rebuilds it. */
+    markDirty(): void;
+    /** Whether the index needs a (re)build before searching. */
+    needsRebuild(): boolean;
+    /** Rebuild the whole index from the given nodes and edges. */
+    rebuildIndex(nodes: VisualGraphNode[], edges: VisualGraphEdge[], normalized?: NormalizedData): Promise<void>;
+    /** Run a full-text query against the index. */
+    search(options: SearchOptions): Promise<OramaSearchResult[]>;
+    /** Current index statistics. */
+    getStats(): ServiceStats;
+    /** Whether the index is ready to serve searches. */
+    isReady(): boolean;
+}
+
+/**
+ * Flatten a normalized graph into a query-friendly shape for the finder's
+ * expression mode (MistQL). Node/edge properties are spread to the top level,
+ * and collections are grouped by label, so queries like
+ * ``Person | filter name == "John"`` or ``graph | filter name == "ABC"`` work.
+ */
+
+/** A node with its properties spread to the top level. */
+interface FlattenedNode {
+    id_: number;
+    label_: string;
+    displayName: string;
+    color: string;
+    [key: string]: unknown;
+}
+/** An edge with its properties spread to the top level. */
+interface FlattenedEdge {
+    id_: number;
+    label_: string;
+    start_id_: number;
+    end_id_: number;
+    [key: string]: unknown;
+}
+/** Flattened graph with raw, combined, and label-grouped collections. */
+interface FlattenedGraphData {
+    nodes: FlattenedNode[];
+    edges: FlattenedEdge[];
+    /** All nodes and edges as a single array. */
+    graph: Array<FlattenedNode | FlattenedEdge>;
+    _labels: string[];
+    _edgeLabels: string[];
+    /** Dynamic label groups, e.g. Person / ACTED_IN. */
+    [key: string]: unknown;
+}
+/** Flatten normalized graph data. Pure function -- no React hooks. */
+declare function flattenGraphData(normalized: NormalizedGraph): FlattenedGraphData;
+
+/**
+ * Tabular result types.
+ *
+ * Transport-agnostic shapes for rendering a query result as a table. A host
+ * app maps its own query response onto {@link TabularResult}; the visualizer
+ * never fetches -- data and paging arrive as props.
+ */
+
+/** One result row: positional cells, a record, or a bare scalar. */
+type TabularRow = Record<string, unknown> | unknown[] | unknown;
+/** How rows are interpreted when deriving columns. */
+type TabularMode = "record" | "array" | "value";
+/** Resolved header list plus the row interpretation it implies. */
+interface TabularHeaders {
+    headers: string[];
+    mode: TabularMode;
+}
+/**
+ * Window metadata for a server-paged result. ``total`` is null when the
+ * backend cannot cheaply count (then rely on ``has_more``); ``truncated``
+ * means the result was capped before counting.
+ */
+interface TabularPageInfo {
+    offset: number;
+    limit: number;
+    returned?: number;
+    total?: number | null;
+    has_more: boolean;
+    truncated?: boolean;
+}
+/** A query result to render as a table. */
+interface TabularResult {
+    /** Result rows (tabular cells in RETURN-column order, or records). */
+    rows: TabularRow[];
+    /** Column-name metadata from the server (RETURN argument -> name). */
+    colNames?: Record<string, string> | null;
+    /** Present when the result is one server-paged window. */
+    page?: TabularPageInfo | null;
+}
+/** A graph node/edge found inside a table cell (``{node}``/``{edge}``-wrapped). */
+type GraphCell = {
+    kind: "node";
+    data: RawGraphNode;
+} | {
+    kind: "edge";
+    data: RawGraphEdge;
+};
+
+/**
+ * PaginationFooter -- "Showing a-b of total" plus page-size and prev/next
+ * controls for a server-paged tabular result. Renders nothing when unpaged.
+ */
+
+interface PaginationControls {
+    pageIndex: number;
+    pageSize?: number;
+    pageSizeOptions?: readonly number[];
+    onPageChange?: (index: number) => void;
+    onPageSizeChange?: (size: number) => void;
+}
+
+/**
+ * TabularVisualizer -- render a query result as a table.
+ *
+ * Pure and transport-agnostic: the host passes the result (and, for server
+ * paging, the page state + callbacks); nothing is fetched here. Graph node/edge
+ * cells render as label-colored chips that open an inspector sheet; other
+ * values render as syntax-highlighted JSON. Offers sort (disabled while
+ * server-paged, since it would only reorder the current page), column resize,
+ * row virtualization, CSV/TSV/JSON export and copy, and a pagination footer.
+ */
+
+interface TabularVisualizerProps extends Partial<PaginationControls> {
+    /** The result to render; undefined = nothing run yet. */
+    result?: TabularResult;
+    /** Optional schema display config for node/edge captions. */
+    labelDisplayMap?: LabelDisplayMap;
+    /** Base file name for exports (default "query-result"). */
+    exportFileName?: string;
+}
+declare function TabularVisualizer({ result, labelDisplayMap, exportFileName, pageIndex, ...controls }: TabularVisualizerProps): React__default.ReactElement;
+
+/**
+ * Graph | Table result view switch.
+ *
+ * useResultView carries cypher-graphdb's ViewContext intent without its URL
+ * coupling. The rule, per result:
+ *
+ *   keep the current view if it can display the result; otherwise switch to a
+ *   view that can.
+ *
+ * In practice the only automatic switch is Graph -> Table when a graph result
+ * is replaced by a scalar/aggregate (which Graph cannot draw). A graph or empty
+ * result never forces a switch (both views can show it), so the operator's
+ * choice -- including a manual one -- is preserved. The first result (no view
+ * chosen yet) opens in its natural view, or in ``initialView`` if given.
+ *
+ * Routing/URL sync stays in the host app (ResultWorkspace's view/onViewChange).
+ */
+type ResultView = "graph" | "table";
+/** Result shape: a graph (nodes/edges), tabular rows (scalars/aggregates), or empty. */
+type ResultKind = "graph" | "tabular" | "empty";
+/** Classify a result from whether it holds graph elements and how many rows it has. */
+declare function classifyResult(isGraph: boolean, rowCount: number): ResultKind;
+/**
+ * Whether a view can display a result kind. Graph can show graph + empty (an
+ * empty canvas) but not tabular rows; Table can show anything.
+ */
+declare function isViewValid(view: ResultView, kind: ResultKind): boolean;
+/** The view a fresh result opens in: graph for a graph result, table otherwise. */
+declare function naturalView(kind: ResultKind): ResultView;
+interface ResultViewOptions {
+    /** View to open the FIRST result in (e.g. read from the URL). Honored once. */
+    initialView?: ResultView;
+}
+/**
+ * Active result view for the current result (identified by ``resultKey``).
+ * Adjusts during render, not in an effect, so a view that would be invalid for
+ * a new result never paints before correcting.
+ */
+declare function useResultView(kind: ResultKind, resultKey: unknown, { initialView }?: ResultViewOptions): [ResultView, (view: ResultView) => void];
+
+/** Graph | Table result view switch (controlled). See resultView.ts for the view state. */
+
+declare function ResultViewTabs({ value, onChange, }: {
+    value: ResultView;
+    onChange: (view: ResultView) => void;
+}): React__default.ReactElement;
+
+/**
+ * GraphInspector -- right-side sheet inspecting a node/edge from a table cell:
+ * header (color, label, id, caption), copy actions, then Properties and JSON tabs.
+ */
+
+interface GraphInspectorProps {
+    cell: GraphCell | null;
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    palette?: ColorPalette;
+    labelDisplayMap?: LabelDisplayMap;
+}
+declare function GraphInspector({ cell, open, onOpenChange, palette, labelDisplayMap, }: GraphInspectorProps): React__default.ReactElement;
+
+/**
+ * GraphChip -- compact single-line chip for a node/edge in a table cell:
+ * label-colored dot (node) or arrow (edge), label, caption, "+N" properties.
+ * Activating it opens the inspector.
+ */
+
+declare function GraphChipImpl({ cell }: {
+    cell: GraphCell;
+}): React__default.ReactElement;
+declare const GraphChip: React__default.MemoExoticComponent<typeof GraphChipImpl>;
+
+/**
+ * Table cell renderers: graph node/edge values become a GraphChip, everything
+ * else renders as syntax-highlighted JSON (colors from the --json-* tokens).
+ */
+
+/** Syntax-highlighted rendering of any JSON value. */
+declare function JsonRenderer({ value, className, }: {
+    value: unknown;
+    className?: string;
+}): React__default.ReactElement;
+/**
+ * One table cell. Memoized on ``value`` so the recursive JSON formatting is
+ * not recomputed on sort/resize/scroll re-renders (cell values are stable).
+ */
+declare function JsonCellImpl({ value }: {
+    value: unknown;
+}): React__default.ReactElement;
+declare const JsonCell: React__default.MemoExoticComponent<typeof JsonCellImpl>;
+
+/**
+ * Helpers for graph node/edge values inside table cells.
+ *
+ * A tabular cell holding a graph object is wrapped as ``{ node: {...} }`` or
+ * ``{ edge: {...} }`` (the cypher-graphdb serialization convention also used by
+ * extractGraphFromRows). These helpers detect that shape and derive a caption
+ * and label color, reusing the graph view's enrichment so they match.
+ */
+
+/** Detect a graph node/edge wrapped in a cell; null for scalars, maps, arrays. */
+declare function asGraphCell(value: unknown): GraphCell | null;
+/** Caption: schema display config first, then a property heuristic, then ``Label #id``. */
+declare function captionFor(cell: GraphCell, labelDisplayMap?: LabelDisplayMap): string;
+/** Number of properties (drives the ``+N`` indicator). */
+declare function propertyCount(cell: GraphCell): number;
+/** Label color from the palette, falling back to neutral. */
+declare function colorForLabel(label: string, palette?: ColorPalette): string;
+
+/**
+ * Column derivation for tabular results.
+ */
+
+/**
+ * Resolve display column names from the server's col_names metadata.
+ *
+ * Wildcard columns (all-numeric keys) use the VALUES (resolved labels, e.g.
+ * "Product"); explicit columns use the KEYS (aliases/expressions, e.g.
+ * "p.name"). Missing columns are padded as ``column_N``.
+ */
+declare function resolveColumnNames(colNames: Record<string, string> | null | undefined, columnCount: number): string[];
+/**
+ * Derive the header list and row interpretation from the rows.
+ * Records win over arrays (union of keys, sorted); arrays use col_names;
+ * otherwise a single ``value`` column.
+ */
+declare function deriveHeaders(rows: TabularRow[], colNames?: Record<string, string> | null): TabularHeaders;
+/** Extract one cell value from a row by header/index under a mode. */
+declare function getCellValue(row: TabularRow, header: string, index: number, mode: TabularMode): unknown;
+
+/**
+ * Export helpers for tabular results: CSV / TSV / JSON strings and a browser
+ * download trigger.
+ */
+
+/** CSV (comma-separated, RFC 4180). */
+declare function toCsv(rows: TabularRow[], headers: string[], mode: TabularMode): string;
+/** TSV (tab-separated; avoids the CSV locale/separator ambiguity in Excel). */
+declare function toTsv(rows: TabularRow[], headers: string[], mode: TabularMode): string;
+/** Pretty JSON array of objects keyed by header, whatever the row shape. */
+declare function toJson(rows: TabularRow[], headers: string[], mode: TabularMode): string;
+/**
+ * Whether CSV/TSV is meaningful: true when at least one sampled cell is flat
+ * (scalar). If every sampled cell is an object/array, flat formats would only
+ * produce stringified JSON blobs.
+ */
+declare function isFlatExportSuitable(rows: TabularRow[], headers: string[], mode: TabularMode): boolean;
+/** Trigger a browser download of in-memory content. */
+declare function downloadFile(content: string, filename: string, mimeType: string): void;
+
+/**
+ * Pane selection for the result workspace (cypher-graphdb's Workspace rules).
+ *
+ * The kind vocabulary and view validity live in tabular/resultView (the single
+ * source of truth the view-switch logic uses); this adds which concrete pane to
+ * render for a given view + result:
+ *   - graph: a graph result in the graph view (nodes/edges, or an empty canvas);
+ *   - table: a result shown as a table;
+ *   - graph-unavailable: a tabular result while in the graph view (cannot draw);
+ *   - table-empty: an empty result in the table view ("no results").
+ */
+
+type PaneChoice = "graph" | "table" | "graph-unavailable" | "table-empty";
+declare function choosePane(view: ResultView, kind: ResultKind): PaneChoice;
+
+/**
+ * ResultWorkspace -- the result area under a query bar: the Graph | Table
+ * switch plus the pane for the active view.
+ *
+ * Owns the layout and the pane rules so every app renders results the same
+ * way; the host supplies the two panes (the graph pane and the table) and
+ * describes the result (kind + a key that changes on each execution). Each new
+ * result opens in its natural view; the operator's own switch sticks until the
+ * next result.
+ *
+ * The view is managed here by default. A host that keeps it elsewhere (e.g. in
+ * the URL, with back/forward) passes ``view`` + ``onViewChange`` to control it,
+ * or just ``initialView`` to choose the first result's view.
+ */
+
+interface ResultWorkspaceProps {
+    kind: ResultKind;
+    /** Changes on every execution (also re-runs of the same query). */
+    resultKey: unknown;
+    /** The graph pane, e.g. a GraphPane. */
+    graphPane: React__default.ReactNode;
+    /** The table pane, e.g. a TabularVisualizer wired to the host's data. */
+    tablePane: React__default.ReactNode;
+    /** Controlled view. When set, the host owns the view and must update it. */
+    view?: ResultView;
+    /**
+     * Called when the operator switches view (controlled or not). Tabs report on
+     * both pointer-down and focus, so one click can call this twice with the same
+     * value before the host re-renders -- keep it idempotent (e.g. navigate only
+     * if the path actually differs).
+     */
+    onViewChange?: (view: ResultView) => void;
+    /** View for the first result (uncontrolled), e.g. read from the URL. */
+    initialView?: ResultView;
+}
+declare function ResultWorkspace({ kind, resultKey, graphPane, tablePane, view: controlledView, onViewChange, initialView, }: ResultWorkspaceProps): React__default.ReactElement;
+
+/**
+ * GraphPane -- the graph result pane: accessible element list, the renderer
+ * canvas, and a resizable action (details/overview) panel.
+ *
+ * The generic part of cypher-graphdb's GraphViewer. App-specific behavior comes
+ * in through props -- action buttons, extra toolbar content, copy handling,
+ * edge-type lookup, a banner, and renderer persistence -- never through app
+ * stores. The host provides the graph stores (GraphStoresContext).
+ */
+
+interface GraphPaneProps extends GraphVisualizerProps {
+    /** False while the graph data is still being prepared (shows the placeholder). */
+    ready?: boolean;
+    /** Placeholder text while not ready. */
+    loadingLabel?: string;
+    /** Overlay over the canvas, e.g. a LargeResultBanner. */
+    banner?: React__default.ReactNode;
+    /** Actions at the top of the action panel (e.g. CRUD buttons). */
+    actions?: React__default.ReactNode;
+    /** Initial renderer (default cytoscape). */
+    defaultRenderer?: GraphRenderer;
+    /** Called when the operator switches renderer (e.g. to persist it in the URL). */
+    onRendererChange?: (renderer: GraphRenderer) => void;
+}
+declare function GraphPane({ ready, loadingLabel, banner, actions, defaultRenderer, onRendererChange, ...visualizerProps }: GraphPaneProps): React__default.ReactElement;
+
+/**
+ * LargeResultBanner -- persistent, non-blocking notice over the graph canvas
+ * when the server bounded the query to the node budget: how many of the total
+ * results are shown, and a nudge to refine. Renders nothing unless the result
+ * was windowed and more rows exist.
+ */
+
+declare function LargeResultBanner({ page, }: {
+    page?: TabularPageInfo | null;
+}): React__default.ReactElement | null;
+
+export { ActionPanel, CenteredMessage, DeleteNodeDialog, EMPTY_NORMALIZED, EdgeFormSheet, EdgeInfoCard, GraphA11yList, GraphChip, GraphEditToolbar, GraphFinder, GraphInspector, GraphModelEditor, GraphPane, GraphRendererProvider, GraphStoresContext, GraphVisualizer, JsonCell, JsonRenderer, LargeResultBanner, ModelActionPanel, NodeFormSheet, NodeInfoCard, NodeTypeNameSheet, OramaSearchService, Overview, PropertyFormSheet, QueryEditor, QueryHistory, RelationFormSheet, ResultViewTabs, ResultWorkspace, TabularVisualizer, TypeDetailPanel, addEdgeType, addNodeType, addRelation, asGraphCell, buildColorPalette, buildColorPaletteFromNodes, capabilitiesSchema, captionFor, cardinalityLabel, choosePane, classifyResult, colorForLabel, createActionPanelStore, createGraphDataStore, createGraphExplorationStore, createGraphFilterStore, createGraphFocusStore, createQueryHistoryStore, createSelectionStore, deleteEdgeType, deleteEdgeTypeProperty, deleteNodeProperty, deleteNodeType, deleteRelation, deleteRelationProperty, deriveHeaders, downloadFile, edgeTypeView, editableRelations, enrichEdge, enrichEdges, enrichNode, enrichNodes, enrichSchemaWithRelations, extractDisplayLabel, extractGraphFromRows, extractRelationFields, findEdgeType, findType, flattenGraphData, getCellValue, graphCapabilitiesSchema, groupEdgesByRelation, hasProperties, hasRelationFields, initializeFormData, isEdgeType, isFlatExportSuitable, isNodeType, isRawGraphNode, isRelationField, isViewValid, isVisualEdge, isVisualNode, modelToGraph, naturalView, nodeTypeView, normalizeGraph, propertyCount, reconcileFilter, relationFieldName, relationTitle, relationTypeFromField, relationView, renameEdgeType, renameNodeType, resolveCapabilities, resolveColumnNames, resolveGraphCapabilities, resolveRelationEdge, setEdgeTypeProperty, setNodeProperty, setRelationProperty, toCsv, toCytoscapeEdge, toCytoscapeNode, toJson, toReagraphEdge, toReagraphNode, toTsv, typeLabel, updateRelation, useActionPanelStore, useCytoscapeData, useGraphFocus, useGraphRenderer, useGraphSearch, useLiveGraphData, useReagraphData, useResultView, useStableRef, useWorkspaceGraphData, useWorkspaceGraphExploration, useWorkspaceGraphFilter, useWorkspaceGraphFocus, useWorkspaceSelection, validateCapabilities, validateGraphCapabilities };
+export type { ActionPanelState, ActionPanelStore, CapabilitiesValidation, Cardinality, ColorPalette, CreateEdgeInput, CreateNodeInput, CreateNodeWithRelationsInput, CreateNodeWithRelationsResult, DeleteNodeDialogProps, EdgeFormSheetProps, EdgeTypeMode, EdgeTypeView, EdgeVisual, EditMode$1 as EditMode, EditableMode, ExpandOptions, ExpandResult, ExtractedGraphRows, FlattenedEdge, FlattenedGraphData, FlattenedNode, GraphA11yListProps, GraphCapabilities, GraphCapabilitiesValidation, GraphCell, GraphDataHook, GraphDataStore, GraphDisplayConfig, EditMode as GraphEditMode, GraphEditToolbarProps, GraphExplorationDeps, GraphExplorationStore, GraphFilterStore, GraphFocusAction, GraphFocusStore, GraphModel, GraphModelCapabilities, GraphModelDisplay, GraphModelEditorProps, GraphModelProperty, GraphMutationPort, GraphPaneProps, GraphProperties, GraphProperty, GraphRelation, GraphRenderer, GraphSchemaProvider, GraphStatistics, WorkspaceStores as GraphStoreBundle, GraphTypeSchema, GraphVisualizerProps, LabelDisplayMap, LiveGraphDataResult, ModelActionPanelProps, ModelGraph, NodeFormSheetProps, NodeTypeNameSheetProps, NodeTypeView, NodeVisual, NormalizedData, NormalizedGraph, OramaDocument, OramaSearchResult, OramaSearchServiceConfig, PaneChoice, PropertyFormSheetProps, PropertyInput, PropertyView, QueryEditorProps, QueryHistoryState, QueryHistoryStore, RawGraphEdge, RawGraphNode, RelationCardinality, RelationDef, RelationDetailView, RelationFormSheetProps, RelationInput, RelationMap, RelationView, ResolvedCapabilities, ResolvedGraphCapabilities, ResultKind, ResultView, ResultWorkspaceProps, SearchOptions, SelectionStore, ServiceStats, StoreFactory, TabularHeaders, TabularMode, TabularPageInfo, TabularResult, TabularRow, TabularVisualizerProps, TypeDetailPanelProps, UpdateEdgeInput, UpdateNodeInput, UpdateNodeWithRelationsInput, UpdateNodeWithRelationsResult, UseGraphSearchReturn, VisualGraphEdge, VisualGraphNode, VisualGraphNormalized, WorkspaceStores, XGraph };