@skydesign/tf 0.2.2

package/dist/index.d.ts

@@ -0,0 +1,394 @@
+import * as d3_2 from 'd3';
+import { ForwardRefExoticComponent } from 'react';
+import { JSX } from 'react/jsx-runtime';
+import { RefAttributes } from 'react';
+
+/**
+ * Create a custom layout config by merging with defaults.
+ * @param overrides - Partial config to override defaults
+ * @returns Complete LayoutConfig with overrides applied
+ */
+export declare function createLayoutConfig(overrides?: Partial<LayoutConfig>): LayoutConfig;
+
+/**
+ * Decode a JSON string that may be single or double-encoded.
+ * Tries direct parse first, then falls back to double-parse for double-encoded strings.
+ * @param str - The JSON string (either single or double-encoded)
+ * @returns The parsed object
+ */
+export declare function decodeDotString<T>(str: string): T;
+
+/**
+ * Default layout configuration with sensible values.
+ */
+export declare const DEFAULT_LAYOUT_CONFIG: LayoutConfig;
+
+declare interface DrawOp {
+    op: string;
+    grad?: string;
+    color?: string;
+    points?: number[][];
+    rect?: number[];
+    pt?: number[];
+    align?: string;
+    width?: number;
+    size?: number;
+    face?: string;
+    text?: string;
+    style?: string;
+}
+
+/**
+ * Content structure for graph edges
+ */
+export declare interface EdgeContent {
+    /** Index of the edge */
+    index: number;
+    /** Color of the edge */
+    color: string;
+    /** Text elements on the edge */
+    elems: TextElem[];
+    /** Optional group identifier for the edge */
+    group?: string;
+}
+
+/**
+ * Lightweight edge metadata returned to consumers after rendering.
+ * Provides the essential identifiers needed for edge navigation.
+ */
+export declare interface EdgeInfo {
+    /** Internal Graphviz ID */
+    id: number;
+    /** Edge index from EdgeContent (used for selection and navigation) */
+    index: number;
+    /** Source node name */
+    sourceNodeId: string;
+    /** Target node name */
+    targetNodeId: string;
+    /** Displayable label text (null if no label) */
+    label: string | null;
+}
+
+/**
+ * Encode an object by double JSON.stringify for use in DOT string labels.
+ * This escapes special characters that would break DOT syntax.
+ * @param obj - The object to encode
+ * @returns Double-stringified JSON string
+ */
+export declare function encodeDotString<T>(obj: T): string;
+
+export declare interface GraphvizJson {
+    name: string;
+    directed: boolean;
+    strict: boolean;
+    bb?: string;
+    objects?: GraphvizObject[];
+    edges?: GraphvizObject[];
+}
+
+declare interface GraphvizObject {
+    _gvid: number;
+    name: string;
+    _draw_?: DrawOp[];
+    _ldraw_?: DrawOp[];
+    _hdraw_?: DrawOp[];
+    _tdraw_?: DrawOp[];
+    bb?: string;
+    pos?: string;
+    width?: string;
+    height?: string;
+    label?: string;
+    head?: number;
+    tail?: number;
+}
+
+/**
+ * GraphvizRenderer - Component that renders DOT strings using Web Worker
+ * and automatically renders them with custom layout.
+ *
+ * Supports both declarative (props) and imperative (ref) APIs for zoom control.
+ *
+ * @example
+ * ```tsx
+ * const rendererRef = useRef<GraphvizRendererRef>(null);
+ *
+ * <GraphvizRenderer
+ *   ref={rendererRef}
+ *   dotString={example.dot}
+ *   nodeMapping={example.nodeMapping}
+ *   maxDepth={2}
+ *   className="w-full h-full"
+ * />
+ *
+ * // Use ref API
+ * rendererRef.current?.zoomIn();
+ * rendererRef.current?.zoomOut(15);
+ * rendererRef.current?.toggleZoom();
+ * ```
+ */
+export declare const GraphvizRenderer: ForwardRefExoticComponent<GraphvizRendererProps & RefAttributes<GraphvizRendererRef>>;
+
+export declare interface GraphvizRendererProps {
+    /** DOT string to render */
+    dotString: string;
+    /** Node mapping for custom rendering */
+    nodeMapping?: Record<string, NodeMapping>;
+    /** SVG font size */
+    svgFontSize?: number;
+    /** Optional custom loading indicator component */
+    loadingIndicator?: React.ReactNode;
+    /** Callback when rendering succeeds */
+    onSuccess?: (result: {
+        json: GraphvizJson;
+        svgElement: SVGSVGElement;
+        edges: EdgeInfo[];
+    }) => void;
+    /** Callback when rendering fails */
+    onError?: (error: Error) => void;
+    /** Callback on zoom with font size information */
+    onZoom?: (info: {
+        baseFontSize: number;
+        actualFontSize: number;
+        scale: number;
+    }) => void;
+    /** Callback for render progress with elapsed time in milliseconds */
+    onRenderProgress?: (elapsedMs: number) => void;
+    /** Callback when rendering is cancelled by user */
+    onCancel?: () => void;
+    /** Callback when large graph warning is triggered. Receives node and edge count. */
+    onWarning?: (info: {
+        nodeCount: number;
+        edgeCount: number;
+    }) => void;
+    /** Additional class name for the container */
+    className?: string;
+    /** Show loading indicator (default: true) */
+    showLoading?: boolean;
+    /** Enable large graph warning dialog - shows warning before rendering graphs with edge count > threshold (default: true) */
+    enableLargeGraphWarning?: boolean;
+    /** Custom threshold for large graph warning (default: LARGE_GRAPH_THRESHOLD = 500) */
+    largeGraphThreshold?: number;
+    /** Enable debug visual indicators (yellow border and center dot) */
+    debug?: boolean;
+    /** Currently selected edge ID (controlled component) */
+    selectedEdgeId?: number | null;
+    /** Callback when an edge is selected or deselected */
+    onEdgeSelect?: (edgeId: number | null) => void;
+    /** Use native Graphviz rendering instead of custom rendering (default: false) */
+    useNativeRendering?: boolean;
+    /** Custom node width in points (default: 240) */
+    nodeWidth?: number;
+    /** Custom node height in points (default: 64) */
+    nodeHeight?: number;
+    /** Custom spacing between node columns in points */
+    nodeColumnSpacing?: number;
+    /** Forward click events to elements beneath the SVG (while preserving zoom/pan) */
+    clickPassthrough?: boolean;
+    /** Enable zoom via mouse wheel (default: true) */
+    enableWheelZoom?: boolean;
+    /**
+     * Initial pan/zoom transform to apply instead of the default getBBox fit.
+     * Pass the `initialTransform` returned by `@skydesign/tf/server`'s
+     * `renderToString` so the hydrated interactive graph matches the SSR'd
+     * static SVG pixel-for-pixel (no jump on handover).
+     */
+    initialTransform?: InitialTransform;
+}
+
+/**
+ * Ref API for programmatic control of GraphvizRenderer
+ */
+export declare interface GraphvizRendererRef {
+    /**
+     * Zoom in by increasing the effective font size
+     * @param percentage - Percentage to increase (default: 10)
+     */
+    zoomIn: (percentage?: number) => void;
+    /**
+     * Zoom out by decreasing the effective font size
+     * @param percentage - Percentage to decrease (default: 10)
+     */
+    zoomOut: (percentage?: number) => void;
+    /**
+     * Toggle between full overview and centered view with normal font size (16px)
+     */
+    toggleZoom: () => void;
+    /**
+     * Stop the current rendering operation and terminate the worker
+     */
+    stopRendering: () => void;
+    /**
+     * Navigate to the previous edge in the rendered edge list.
+     * Selects it, centers it in the viewport with smooth animation.
+     * Wraps to the last edge when at the beginning. Starts from last if no edge is selected.
+     * Fires onEdgeSelect with the new edge index.
+     */
+    highlightPrevEdge: () => void;
+    /**
+     * Navigate to the next edge in the rendered edge list.
+     * Selects it, centers it in the viewport with smooth animation.
+     * Wraps to the first edge when at the end. Starts from first if no edge is selected.
+     * Fires onEdgeSelect with the new edge index.
+     */
+    highlightNextEdge: () => void;
+}
+
+/**
+ * Render graph using custom SVG based on Graphviz JSON output
+ * @param maxDepth - Edge depth to filter by (null = show all)
+ * @param includeLesserDepths - If true, show depth <= maxDepth; if false, show only exact depth
+ * @param config - Layout configuration
+ * @returns Object containing zoom behavior and SVG references for imperative control
+ */
+/** Pan/zoom transform: g = translate(x,y) scale(k). */
+export declare interface InitialTransform {
+    x: number;
+    y: number;
+    k: number;
+}
+
+export declare const LARGE_GRAPH_THRESHOLD = 500;
+
+/**
+ * Layout configuration for the Graphviz custom layout renderer.
+ * All layout-related constants are consolidated here for easy customization.
+ */
+export declare interface LayoutConfig {
+    /** Horizontal extension at start/end of edges (in pixels) */
+    horizontalExtension: number;
+    /** Minimum distance between edge midY values (in pixels) */
+    minEdgeDistance: number;
+    /** Threshold for skipping vertical segments (in pixels) */
+    minVerticalSegment: number;
+    /** Radius for self-loop edges (in pixels) */
+    loopRadius: number;
+    /** Spacing between edges (in pixels) */
+    edgeSpacing: number;
+    /** Corner radius for edge paths (in pixels) */
+    cornerRadius: number;
+    /** Width of arrowhead (in pixels) */
+    arrowWidth: number;
+    /** Height of arrowhead (in pixels) */
+    arrowHeight: number;
+    /** Extra height for edge labels (in pixels) */
+    labelHeight: number;
+    /** Font size for edge labels (in pixels) */
+    labelFontSize: number;
+    /** Padding around label text (in pixels) */
+    labelPadding: number;
+    /** Corner radius for label background (in pixels) */
+    labelCornerRadius: number;
+    /** Spacing between nodes (in pixels) */
+    nodeSpacing: number;
+    /** Threshold for considering edges as nearly horizontal (in pixels) */
+    nearlyHorizontalThreshold: number;
+    /** Threshold for nearly aligned edges in 3seg path (in pixels) */
+    nearlyAlignedThreshold: number;
+}
+
+/**
+ * Content structure for graph nodes
+ */
+export declare interface NodeContent {
+    /** Unique key for the node */
+    key?: string;
+    /** Tags associated with the node */
+    tags: string[];
+    /** Display label for the node */
+    label?: string;
+    /** Text content of the node */
+    text: string;
+    /** Optional text color */
+    color?: string;
+    /** Optional background color for the node */
+    background?: string;
+}
+
+export declare interface NodeMapping {
+    sourceNodeId: string;
+    targetNodeId: string;
+}
+
+declare interface NodeMapping_2 {
+    sourceNodeId: string;
+    targetNodeId: string;
+}
+
+export declare function renderCustomGraph(container: HTMLDivElement, json: GraphvizJson, _nodeMapping?: Record<string, NodeMapping_2>, maxDepth?: number | null, includeLesserDepths?: boolean, config?: LayoutConfig, useOrthogonalRendering?: boolean, svgFontSize?: number, debug?: boolean, selectedEdgeId?: number | null, onEdgeSelect?: (edgeIndex: number | null) => void, nodeWidth?: number, nodeHeight?: number, nodeColumnSpacing?: number, enableWheelZoom?: boolean, extra?: RenderExtraOptions): {
+    zoomBehavior: d3_2.ZoomBehavior<SVGSVGElement, unknown>;
+    svgElement: SVGSVGElement;
+    gElement: SVGGElement;
+    baseFontSize: number;
+    viewBoxWidth: number;
+    edges: EdgeInfo[];
+    initialTransform: InitialTransform;
+};
+
+export declare interface RenderExtraOptions {
+    /**
+     * Headless (Node / SSR) mode. Skips the d3-zoom attachment and never calls
+     * `getBBox`/`getComputedTextLength`; bakes a deterministic initial transform
+     * straight onto `<g>` so the SVG can be serialized to a string. Geometry is
+     * fully determined by the graphviz JSON, so it matches the browser render.
+     */
+    headless?: boolean;
+    /**
+     * Use this exact initial transform instead of measuring the fit via
+     * `getBBox`. Pass the `initialTransform` returned from a headless render so
+     * the hydrated interactive graph lines up with the SSR'd SVG pixel-for-pixel
+     * (no jump on handover). When omitted in non-headless mode, the legacy
+     * getBBox-based fit is used (unchanged behavior for existing callers).
+     */
+    initialTransform?: InitialTransform;
+}
+
+/**
+ * Setup zoom and pan for graphviz native SVG rendering
+ */
+export declare function setupZoomPan(container: HTMLDivElement): void;
+
+/**
+ * Text element with optional color and background
+ */
+export declare interface TextElem {
+    /** Text content */
+    text: string;
+    /** Optional color for the text */
+    color?: string;
+    /** Optional background color */
+    background?: string;
+}
+
+export declare function useGraphvizWorker(): UseGraphvizWorkerResult;
+
+declare interface UseGraphvizWorkerResult {
+    layout: (dot: string) => Promise<string>;
+    cancel: () => void;
+    isLoading: boolean;
+    error: string | null;
+}
+
+/**
+ * Loading indicator shown during graph layout processing.
+ *
+ * Uses CSS variables from color.css for theming support.
+ */
+export declare function WorkerLoadingIndicator({ onCancel }: WorkerLoadingIndicatorProps): JSX.Element;
+
+export declare interface WorkerLoadingIndicatorProps {
+    onCancel: () => void;
+}
+
+export declare interface WorkerRequest {
+    id: string;
+    dot: string;
+}
+
+export declare interface WorkerResponse {
+    id: string;
+    success: boolean;
+    json?: string;
+    error?: string;
+}
+
+export { }