@ts-graphviz/react 0.10.6 → 0.11.1

package/example/example.tsx

@@ -1,4 +1,4 @@
-import { Digraph, Edge, Node, Subgraph, renderToDot } from '@ts-graphviz/react';
+import { Digraph, Edge, Node, renderToDot, Subgraph } from '@ts-graphviz/react';
 
 const Example = () => (
   <Digraph

package/lib/react.d.ts

@@ -1,19 +1,86 @@
+import { ComponentProps as ComponentProps_2 } from 'react';
+import { DotObjectModel } from 'ts-graphviz';
 import { EdgeAttributesObject } from '@ts-graphviz/common';
-import { EdgeModel } from 'ts-graphviz';
+import { EdgeModel } from '@ts-graphviz/common';
+import { EdgeModel as EdgeModel_2 } from 'ts-graphviz';
 import { EdgeTargetLikeTuple } from '@ts-graphviz/common';
 import { EdgeTargetLikeTuple as EdgeTargetLikeTuple_2 } from 'ts-graphviz';
 import { FC } from 'react';
+import { FilterableModel } from 'ts-graphviz';
 import { GraphAttributesObject } from '@ts-graphviz/common';
-import { GraphBaseModel } from 'ts-graphviz';
+import { GraphBaseModel } from '@ts-graphviz/common';
+import { GraphBaseModel as GraphBaseModel_2 } from 'ts-graphviz';
 import { HasComment } from '@ts-graphviz/common';
+import { isAttributeListModel } from 'ts-graphviz';
+import { isEdgeModel } from 'ts-graphviz';
+import { isNodeModel } from 'ts-graphviz';
+import { isRootGraphModel } from 'ts-graphviz';
+import { isSubgraphModel } from 'ts-graphviz';
 import { NodeAttributesObject } from '@ts-graphviz/common';
-import { NodeModel } from 'ts-graphviz';
+import { NodeModel } from '@ts-graphviz/common';
+import { NodeModel as NodeModel_2 } from 'ts-graphviz';
 import { ReactElement } from 'react';
 import { ReactNode } from 'react';
+import { Ref } from 'react';
 import { RootGraphModel } from 'ts-graphviz';
 import { SubgraphAttributesObject } from '@ts-graphviz/common';
 import { SubgraphModel } from 'ts-graphviz';
 
+/**
+ * Type that represents any graph-like container that can be used for rendering.
+ * This includes both base interfaces (GraphBaseModel) and root graph interfaces (RootGraphModel).
+ * Since Graph and Digraph implement RootGraphModel, they are covered by this union.
+ */
+export declare type AnyGraphContainer = GraphBaseModel_2 | RootGraphModel;
+
+/**
+ * Props for Graphviz components
+ */
+export declare type ComponentProps = ComponentProps_2<any>;
+
+/**
+ * React component type for Graphviz elements
+ */
+export declare type ComponentType = FC<any>;
+
+/**
+ * Create a Graphviz root for rendering React elements to Graphviz models
+ * @param options - Options for creating the root, including optional container
+ */
+export declare function createRoot<Container extends AnyGraphContainer = AnyGraphContainer>(options?: CreateRootOptions<Container>): GraphvizRoot;
+
+/**
+ * Options for creating a Graphviz root
+ */
+export declare interface CreateRootOptions<Container extends AnyGraphContainer = AnyGraphContainer> {
+    /**
+     * Container graph for rendering components.
+     * When provided, components will be rendered into this existing graph model.
+     */
+    container?: Container;
+    /**
+     * Called when an error is not caught by any error boundary
+     */
+    onUncaughtError?: (error: Error, errorInfo: ErrorInfo) => void;
+    /**
+     * Called when an error is caught by an error boundary
+     */
+    onCaughtError?: (error: Error, errorInfo: ErrorInfo) => void;
+    /**
+     * Called when React automatically recovers from errors
+     */
+    onRecoverableError?: (error: Error, errorInfo: ErrorInfo) => void;
+    /**
+     * Called when rendering completes successfully
+     */
+    onRenderComplete?: (models: DotObjectModel[]) => void;
+    /**
+     * Timeout for async rendering in milliseconds
+     * @default 5000
+     */
+    timeout?: number;
+}
+
 /**
  * `Digraph` component.
  */
@@ -34,8 +101,18 @@ export declare interface EdgeProps extends Omit<EdgeOptions, 'label'> {
     targets: EdgeTargetLikeTuple;
     /** Edge label */
     label?: ReactElement | string;
+    ref?: Ref<EdgeModel>;
+}
+
+/**
+ * Error information for React error handling
+ */
+export declare interface ErrorInfo {
+    componentStack?: string;
 }
 
+export { FilterableModel }
+
 /**
  * `Graph` component.
  */
@@ -66,6 +143,58 @@ export declare interface GraphPortalProps {
     children?: ReactNode;
 }
 
+/**
+ * Graphviz root interface
+ */
+export declare interface GraphvizRoot {
+    /**
+     * Render a React element asynchronously
+     */
+    render(element: ReactElement): Promise<void>;
+    /**
+     * Unmount the root and cleanup resources
+     */
+    unmount(): void;
+    /**
+     * Get all top-level models that were rendered (no type parameters)
+     * @returns Array of rendered models. In container mode, returns all non-container models.
+     *          In non-container mode, returns top-level graph models.
+     */
+    getTopLevelModels(): DotObjectModel[];
+    /**
+     * Get top-level models with generic type casting or type guard filtering
+     *
+     * @overload@overload
+     * When called with a type guard function, filters models by type using runtime type checking
+     * @param typeGuard - Type guard function to filter models
+     * @returns Array of models matching the specified type
+     *
+     * @overload@overload
+     * When called with only a generic type parameter, casts all models to the specified type (trusted user assertion)
+     * @returns Array of models cast to the specified type T
+     *
+     * @example
+     * ```typescript
+     * // Runtime type filtering with type guard
+     * const nodes = root.getTopLevelModels(isNodeModel);
+     *
+     * // Direct type casting (user knows the type)
+     * const nodes = root.getTopLevelModels<NodeModel>();
+     * ```
+     */
+    getTopLevelModels<T extends DotObjectModel>(typeGuard?: (model: DotObjectModel) => model is T): T[];
+}
+
+export { isAttributeListModel }
+
+export { isEdgeModel }
+
+export { isNodeModel }
+
+export { isRootGraphModel }
+
+export { isSubgraphModel }
+
 /**
  * `Node` component.
  */
@@ -83,77 +212,78 @@ export declare interface NodeProps extends Omit<NodeOptions, 'label' | 'xlabel'>
     label?: ReactElement | string;
     /** Node xlabel */
     xlabel?: ReactElement | string;
+    ref?: Ref<NodeModel>;
 }
 
+export { ReactNode }
+
 /**
- * Convert the given element to Graphviz model.
- *
- * @example Example of giving a cluster as a container with the second argument.
+ * Converts a React element into a custom HTML-like string representation.
  *
- * ```tsx
- * import React, { FC } from 'react';
- * import { digraph, toDot } from 'ts-graphviz';
- * import { Node, Subgraph, render, Edge } from '@ts-graphviz/react';
- *
- * const Example: FC = () => (
- *   <>
- *     <Node id="a" />
+ * If no {@link label} is provided, returns the string '<>'. Otherwise, renders the React element to static markup, transforms any `dot:`-prefixed tags by removing the prefix, and wraps the result in angle brackets.
  *
- *     <Subgraph id="my_cluster">
- *       <Node id="b" />
- *     </Subgraph>
- *     <Edge targets={['b', 'a']} />
- *   </>
- * );
- *
- * const G = digraph((g) => render(<Example />, g));
- * console.log(toDot(G));
- * // digraph {
- * //   "a";
- * //   subgraph "my_cluster" {
- * //     "b";
- * //   }
- * //   "b" -> "a";
- * // }
- * ```
+ * @param label - Optional React element to render.
+ * @returns A string representing the transformed HTML-like markup.
  */
-export declare function render<T extends GraphBaseModel>(element: ReactElement, container?: T): T;
-
 export declare function renderHTMLLike(label?: ReactElement): string;
 
 /**
- * Converts the given element to DOT language and returns it.
+ * Converts the given React element to DOT language asynchronously.
  *
- * @example
+ * This function creates a Graphviz root, renders the element, and returns the DOT representation.
  *
+ * @example Single top-level graph
  * ```tsx
- * import React, { FC } from 'react';
- * import { Digraph, Node, Subgraph, renderToDot, Edge } from '@ts-graphviz/react';
+ * const dot = await renderToDot(
+ *   <Digraph id="example">
+ *     <Node id="a" />
+ *     <Node id="b" />
+ *     <Edge targets={['a', 'b']} />
+ *   </Digraph>
+ * );
+ * console.log(dot);
+ * // digraph "example" {
+ * //   "a";
+ * //   "b";
+ * //   "a" -> "b";
+ * // }
+ * ```
  *
- * const Example: FC = () => (
- *   <Digraph>
+ * @example With container
+ * ```tsx
+ * const container = new DigraphModel('main');
+ * const dot = await renderToDot(
+ *   <>
  *     <Node id="a" />
- *     <Subgraph id="my_cluster">
+ *     <Subgraph id="cluster_sub">
  *       <Node id="b" />
  *     </Subgraph>
- *     <Edge targets={['b', 'a']} />
- *   </Digraph>
+ *     <Edge targets={['a', 'b']} />
+ *   </>,
+ *   { container }
  * );
- *
- * const dot = renderToDot(<Example />);
  * console.log(dot);
- * // digraph {
+ * // digraph "main" {
  * //   "a";
- * //   subgraph "my_cluster" {
+ * //   subgraph "cluster_sub" {
  * //     "b";
  * //   }
- * //   "b" -> "a";
+ * //   "a" -> "b";
  * // }
  * ```
- *
- * @returns Rendered dot string
  */
-export declare function renderToDot(element: ReactElement, container?: RootGraphModel): string;
+export declare function renderToDot<Container extends AnyGraphContainer = AnyGraphContainer>(element: ReactElement, options?: RenderToDotOptions<Container>): Promise<string>;
+
+/**
+ * Rendering options for renderToDot
+ */
+export declare interface RenderToDotOptions<Container extends AnyGraphContainer = AnyGraphContainer> extends CreateRootOptions {
+    /**
+     * Container graph to render into. When provided, the element will be rendered
+     * as children of this container and the container's DOT will be returned.
+     */
+    container?: Container;
+}
 
 /** Options for RootGraph */
 export declare interface RootGraphOptions extends GraphAttributesObject, GraphBaseAttributesProps {
@@ -165,6 +295,7 @@ export declare interface RootGraphOptions extends GraphAttributesObject, GraphBa
 export declare interface RootGraphProps extends Omit<RootGraphOptions, 'label'> {
     label?: ReactElement | string;
     children?: ReactNode;
+    ref?: Ref<GraphBaseModel>;
 }
 
 /**
@@ -183,14 +314,17 @@ export declare interface SubgraphProps extends Omit<SubgraphOptions, 'label'> {
     /** Subgraph label */
     label?: ReactElement | string;
     children?: ReactNode;
+    ref?: Ref<GraphBaseModel>;
 }
 
+export declare type TopLevelModel = FilterableModel;
+
 /**
  * Hook to get the current cluster(Digraph, Graph or Subgraph).
  *
  * @throws If it is out of the context of Cluster, it throws an exception.
  */
-export declare function useCurrentGraph(): GraphBaseModel;
+export declare function useCurrentGraph(): AnyGraphContainer;
 
 /**
  * `useDigraph` is a hook that creates an instance of Digraph
@@ -202,7 +336,7 @@ export declare function useDigraph(options?: RootGraphOptions): RootGraphModel;
  * `useEdge` is a hook that creates an instance of Edge
  * according to the object given by props.
  */
-export declare function useEdge(targets: EdgeTargetLikeTuple_2, props?: EdgeOptions): EdgeModel;
+export declare function useEdge(targets: EdgeTargetLikeTuple_2, props?: EdgeOptions): EdgeModel_2;
 
 /**
  * `useGraph` is a hook that creates an instance of Graph
@@ -213,13 +347,13 @@ export declare function useGraph(options?: RootGraphOptions): RootGraphModel;
 /**
  * Return the cluster of container.
  */
-export declare function useGraphContainer(): GraphBaseModel | null;
+export declare function useGraphContainer(): AnyGraphContainer | null;
 
 /**
  * `useNode` is a hook that creates an instance of Node
  * according to the object given by props.
  */
-export declare function useNode(id: string, options?: NodeOptions): NodeModel;
+export declare function useNode(id: string, options?: NodeOptions): NodeModel_2;
 
 /**
  * `useSubgraph` is a hook that creates an instance of Subgraph
@@ -230,49 +364,17 @@ export declare function useSubgraph(props?: SubgraphOptions): SubgraphModel;
 export { }
 
 
-declare global {
+declare module 'react' {
+    namespace JSX {
+        interface IntrinsicElements extends JSXIntrinsicElements {
+        }
+    }
+}
+
+
+declare module 'react/jsx-runtime' {
     namespace JSX {
-        interface IntrinsicElements {
-            'dot:port': {
-                children: string;
-            };
-            'dot:table': HTMLLikeLabel.TableAttributes & {
-                children?: ReactNode;
-            };
-            'dot:tr': HTMLLikeLabel.TrAttributes & {
-                children?: ReactNode;
-            };
-            'dot:td': HTMLLikeLabel.TdAttributes & {
-                children?: ReactNode;
-            };
-            'dot:font': HTMLLikeLabel.FontAttributes & {
-                children?: ReactNode;
-            };
-            'dot:br': HTMLLikeLabel.BrAttributes;
-            'dot:img': HTMLLikeLabel.ImgAttributes;
-            'dot:i': HTMLLikeLabel.IAttributes & {
-                children?: ReactNode;
-            };
-            'dot:b': HTMLLikeLabel.BAttributes & {
-                children?: ReactNode;
-            };
-            'dot:u': HTMLLikeLabel.UAttributes & {
-                children?: ReactNode;
-            };
-            'dot:o': HTMLLikeLabel.OAttributes & {
-                children?: ReactNode;
-            };
-            'dot:sub': HTMLLikeLabel.SubAttributes & {
-                children?: ReactNode;
-            };
-            'dot:sup': HTMLLikeLabel.SupAttributes & {
-                children?: ReactNode;
-            };
-            'dot:s': HTMLLikeLabel.SAttributes & {
-                children?: ReactNode;
-            };
-            'dot:hr': HTMLLikeLabel.HrAttributes;
-            'dot:vr': HTMLLikeLabel.VrAttributes;
+        interface IntrinsicElements extends JSXIntrinsicElements {
         }
     }
 }