@petrarca/sonnet-graph 0.7.0 → 0.8.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-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';
@@ -272,6 +272,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.
  *
@@ -1961,4 +2062,204 @@ 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;
+
+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, type ExtractedGraphRows, type FlattenedEdge, type FlattenedGraphData, type FlattenedNode, 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, GraphFinder, 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 NormalizedData, type NormalizedGraph, type OramaDocument, type OramaSearchResult, OramaSearchService, type OramaSearchServiceConfig, Overview, PropertyFormSheet, type PropertyFormSheetProps, type PropertyInput, type PropertyView, QueryEditor, type QueryEditorProps, QueryHistory, type QueryHistoryState, type QueryHistoryStore, type RawGraphEdge, type RawGraphNode, type RelationCardinality, type RelationDef, type RelationDetailView, RelationFormSheet, type RelationFormSheetProps, type RelationInput, type RelationMap, type RelationView, type ResolvedCapabilities, type ResolvedGraphCapabilities, type SearchOptions, type SelectionStore, type ServiceStats, type StoreFactory, TypeDetailPanel, type TypeDetailPanelProps, type UpdateEdgeInput, type UpdateNodeInput, type UpdateNodeWithRelationsInput, type UpdateNodeWithRelationsResult, type UseGraphSearchReturn, type VisualGraphEdge, type VisualGraphNode, type VisualGraphNormalized, type WorkspaceStores, type XGraph, addEdgeType, addNodeType, addRelation, buildColorPalette, buildColorPaletteFromNodes, capabilitiesSchema, cardinalityLabel, createActionPanelStore, createGraphDataStore, createGraphExplorationStore, createGraphFilterStore, createGraphFocusStore, createQueryHistoryStore, createSelectionStore, deleteEdgeType, deleteEdgeTypeProperty, deleteNodeProperty, deleteNodeType, deleteRelation, deleteRelationProperty, edgeTypeView, editableRelations, enrichEdge, enrichEdges, enrichNode, enrichNodes, enrichSchemaWithRelations, extractDisplayLabel, extractGraphFromRows, extractRelationFields, findEdgeType, findType, flattenGraphData, 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, useGraphSearch, useLiveGraphData, useReagraphData, useStableRef, useWorkspaceGraphData, useWorkspaceGraphExploration, useWorkspaceGraphFilter, useWorkspaceGraphFocus, useWorkspaceSelection, validateCapabilities, validateGraphCapabilities };