refactor(graph-layer): streamline loader data inputs

docs/modules/graph-layers/api-reference/layers/graph-layer.md

@@ -31,11 +31,12 @@ const layer = new GraphLayer({
 ```
 
 `GraphLayer` treats the `data` prop as its single entry point. Provide a
-`GraphEngine`, a [`Graph`](../graph.md), or raw graph payloads (arrays of edges
-or `{nodes, edges}` objects). When the layer receives new data it rebuilds the
-internal `GraphEngine`, re-runs the layout, and updates interactions
-automatically. Supplying raw data requires a `layout` so the layer can derive
-positions for you.
+`GraphEngine`, a [`Graph`](../graph.md), pre-normalized `GraphData`,
+`ArrowGraphData`, or raw graph
+payloads (arrays of edges or `{nodes, edges}` objects). When the layer receives
+new data it rebuilds the internal `GraphEngine`, re-runs the layout, and updates
+interactions automatically. Supplying raw data requires a `layout` so the layer
+can derive positions for you.
 
 ## Properties
 
@@ -64,10 +65,11 @@ releases will remove this prop.
 
 #### `graphLoader` (function, optional)
 
-Custom loader that converts raw `data` into a `Graph`. Defaults to the bundled
+Custom loader that converts raw `data` into `GraphData` or
+`ArrowGraphData`. Defaults to the bundled
 `JSONLoader`, which accepts arrays of edges or `{nodes, edges}` collections and
-automatically synthesizes missing nodes. Graph instances are no longer
-normalized by the loader—pass them directly to `data`.
+returns `GraphData`. Graph instances are no longer normalized by the
+loader—pass them directly to `data`.
 
 #### `engine` (`GraphEngine`, optional)
 

docs/upgrade-guide.md

@@ -15,6 +15,6 @@ Please refer the documentation of each module for detailed upgrade guides.
   - Replace `nodeStyle` / `edgeStyle` with `stylesheet.nodes` and `stylesheet.edges`
 - Deprecation: `graph` prop on `GraphLayer` is being phased out. Provide graphs via the `data` prop instead (supports `GraphEngine`,
   `Graph`, or raw `{nodes, edges}`/edge arrays) and supply a `layout` when the layer must build the engine for you.
-- Breaking change: `JSONLoader` only normalizes raw JSON payloads. Pass `Graph` instances directly to `GraphLayer.data` rather than
-  routing them through the loader.
+- Breaking change: `JSONLoader` only normalizes raw JSON payloads into `GraphData`. Pass `Graph` instances directly to
+  `GraphLayer.data` rather than routing them through the loader.
 

docs/whats-new.md

@@ -28,7 +28,7 @@ Highlights:
 
 - `GraphLayerProps` - NEW `data` prop (no longer requires applications to provide `engine: GraphEngine`).
   - `GraphLayer` now accepts `GraphEngine`, `Graph`, or raw JSON via its `data` prop (including async URLs), automatically builds a `GraphEngine` when given raw payloads, and deprecates the legacy `graph` prop.
-  - `JSONLoader` normalizes edge arrays or `{nodes, edges}` objects and no longer accepts `Graph` instances directly.
+  - `JSONLoader` normalizes edge arrays or `{nodes, edges}` objects into `GraphData` and no longer accepts `Graph` instances directly.
 - `GraphLayerProps` - NEW `stylesheet` prop that accepts a unified stylesheet containing all for node, edge, and decorator styles.
 - `GraphStylesheet` - NEW edge decorator `'arrow'` that renders arrows on directional edges.
 - `GraphStylesheet` - constants can now be defined using simple string literals (no need to import `NODE_TYPE` etc).

modules/graph-layers/src/core/graph-layout.ts

@@ -34,6 +34,7 @@ export const GRAPH_LAYOUT_DEFAULT_PROPS: Readonly<Required<GraphLayoutProps>> =
 export abstract class GraphLayout<
   PropsT extends GraphLayoutProps = GraphLayoutProps
 > implements GraphRuntimeLayout {
+  readonly type = 'graph-runtime-layout';
   /** Name of the layout. */
   protected readonly _name: string = 'GraphLayout';
   /** Extra configuration props of the layout. */

modules/graph-layers/src/core/graph-runtime-layout.ts

@@ -8,6 +8,7 @@ import type {GraphLayoutProps, GraphLayoutState} from './graph-layout';
 import type {EdgeInterface, Graph, NodeInterface} from '../graph/graph';
 
 export interface GraphRuntimeLayout {
+  readonly type: 'graph-runtime-layout';
   readonly version: number;
   readonly state: GraphLayoutState;
   getProps(): GraphLayoutProps;
@@ -27,3 +28,11 @@ export interface GraphRuntimeLayout {
 }
 
 export type TabularGraphLayout = GraphRuntimeLayout;
+
+export function isGraphRuntimeLayout(value: unknown): value is GraphRuntimeLayout {
+  return Boolean(
+    value &&
+      typeof value === 'object' &&
+      (value as {type?: unknown}).type === 'graph-runtime-layout'
+  );
+}

modules/graph-layers/src/graph-data/graph-data.ts

@@ -42,3 +42,16 @@ type GraphDataShape = {
 export type GraphData = GraphDataShape & {
   type?: 'graph-data';
 };
+
+export function isGraphData(value: unknown): value is GraphData {
+  if (!value || typeof value !== 'object') {
+    return false;
+  }
+
+  const candidate = value as GraphData;
+  if ((candidate as {type?: string}).type === 'graph-data') {
+    return true;
+  }
+
+  return Array.isArray(candidate.nodes) || Array.isArray(candidate.edges);
+}

modules/graph-layers/src/graph/classic-graph.ts

@@ -377,6 +377,7 @@ export class ClassicGraph extends Graph {
 }
 
 export class ClassicGraphLayoutAdapter implements GraphRuntimeLayout {
+  readonly type = 'graph-runtime-layout';
   private readonly layout: GraphLayout;
 
   constructor(layout: GraphLayout) {