@graphty/graphty-element 2.6.1 → 3.0.0

package/dist/src/config/GraphStyle.d.ts

@@ -116,8 +116,8 @@ export declare const GraphStyle: z.ZodObject<{
     viewMode: z.ZodDefault<z.ZodEnum<{
         "2d": "2d";
         "3d": "3d";
-        vr: "vr";
         ar: "ar";
+        vr: "vr";
     }>>;
     /**
      * @deprecated Use viewMode instead. twoD: true is equivalent to viewMode: "2d"

package/dist/src/config/StyleTemplate.d.ts

@@ -28,8 +28,8 @@ declare const StyleTemplateV1: z.ZodObject<{
         viewMode: z.ZodDefault<z.ZodEnum<{
             "2d": "2d";
             "3d": "3d";
-            vr: "vr";
             ar: "ar";
+            vr: "vr";
         }>>;
         twoD: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strict>>;
@@ -964,8 +964,8 @@ export declare const StyleTemplate: z.ZodDiscriminatedUnion<[z.ZodObject<{
         viewMode: z.ZodDefault<z.ZodEnum<{
             "2d": "2d";
             "3d": "3d";
-            vr: "vr";
             ar: "ar";
+            vr: "vr";
         }>>;
         twoD: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strict>>;

package/dist/src/config/xr-config-schema.d.ts

@@ -201,12 +201,12 @@ export declare const xrConfigSchema: z.ZodDefault<z.ZodObject<{
         enableZAmplificationInDesktop: boolean;
     };
     enabled: boolean;
-    vr: {
+    ar: {
         enabled: boolean;
         optionalFeatures: string[];
         referenceSpaceType: "unbounded" | "local" | "local-floor" | "bounded-floor";
     };
-    ar: {
+    vr: {
         enabled: boolean;
         optionalFeatures: string[];
         referenceSpaceType: "unbounded" | "local" | "local-floor" | "bounded-floor";
@@ -231,12 +231,12 @@ export declare const xrConfigSchema: z.ZodDefault<z.ZodObject<{
         enableZAmplificationInDesktop?: boolean | undefined;
     } | undefined;
     enabled?: boolean | undefined;
-    vr?: {
+    ar?: {
         enabled?: boolean | undefined;
         optionalFeatures?: string[] | undefined;
         referenceSpaceType?: "unbounded" | "local" | "local-floor" | "bounded-floor" | undefined;
     } | undefined;
-    ar?: {
+    vr?: {
         enabled?: boolean | undefined;
         optionalFeatures?: string[] | undefined;
         referenceSpaceType?: "unbounded" | "local" | "local-floor" | "bounded-floor" | undefined;

package/dist/src/data/CSVDataSource.d.ts

@@ -1,7 +1,8 @@
-import { type CSVVariant } from "./csv-variant-detection.js";
 import { BaseDataSourceConfig, DataSource, DataSourceChunk } from "./DataSource.js";
+/** The CSV shapes the reader can be told to read, or recognises when it is not told. */
+export type CSVVariant = "neo4j" | "gephi" | "cytoscape" | "adjacency-list" | "edge-list" | "node-list" | "generic";
 interface CSVDataSourceConfig extends BaseDataSourceConfig {
-    /** The column separator. Worked out from the first line (comma, tab, semicolon or pipe) when unset. */
+    /** The column separator. Worked out from the first rows (comma, tab, semicolon or pipe) when unset. */
     delimiter?: string;
     variant?: CSVVariant;
     /**
@@ -22,8 +23,9 @@ interface CSVDataSourceConfig extends BaseDataSourceConfig {
     edgeURL?: string;
 }
 /**
- * Data source for loading graph data from CSV files.
- * Supports edge lists, adjacency lists, and paired node/edge files.
+ * Data source for loading graph data from CSV files, read by `@graphty/graph-io`.
+ * Supports edge lists (plain, Gephi, Cytoscape), adjacency lists, node lists, Neo4j admin-import
+ * files and paired node and edge files.
  */
 export declare class CSVDataSource extends DataSource {
     static readonly type = "csv";
@@ -36,28 +38,81 @@ export declare class CSVDataSource extends DataSource {
     protected getConfig(): BaseDataSourceConfig;
     /**
      * Fetches and parses CSV data into graph chunks.
-     * Automatically detects CSV variant (edge list, adjacency list, or paired files).
+     * Recognises a Neo4j file from its header; every other file is read as the variant asked for,
+     * or as whatever table its header describes.
      * @yields DataSourceChunk objects containing parsed nodes and edges
      */
     sourceFetchData(): AsyncGenerator<DataSourceChunk, void, unknown>;
     /**
-     * Create an edge from CSV row data
-     * Returns null if source or target is missing (and logs error)
-     * @param src - Source node ID (will be converted to string)
-     * @param dst - Target node ID (will be converted to string)
-     * @param row - Full row data for additional properties
-     * @param sourceColName - Name of source column (for error messages)
-     * @param targetColName - Name of target column (for error messages)
-     * @param rowIndex - Row index (for error messages)
-     * @returns Edge data object or null if invalid
-     */
-    private createEdge;
-    private parseEdgeList;
-    private parseNodeList;
-    private parseNeo4jFormat;
-    private parseGephiFormat;
-    private parseCytoscapeFormat;
-    private parseAdjacencyList;
+     * Read a single table, choosing an edge table's endpoint columns.
+     *
+     * The endpoint columns are the configured ones, else the variant's, else the first pair of
+     * {@link ENDPOINT_PAIRS} the header holds both halves of. A configured column the file does not
+     * have is recorded as an error and nothing is read. The import's issues are recorded.
+     * @param content - the file's text
+     * @param table - the variant's table options
+     * @param mayBeNodeList - read a header with no endpoint pair and an `id` column as a node table
+     *     (a node table's own id column is looked for the same way, and is the row number without one)
+     * @returns the records, or null when the header names no endpoint pair (and, where it may be a
+     *     node list, no id column): the rows are then handed to the element unread
+     */
+    private readTable;
+    /**
+     * Read one table with the options every CSV route shares.
+     * @param content - the file's text
+     * @param table - the variant's table options
+     * @param nodes - a node file read before the edges, for a pair of files
+     * @returns the records and the report
+     */
+    private importTable;
+    /**
+     * Hand the rows of a file whose header names no endpoint column to the element unread.
+     *
+     * Such a row is not a malformed edge, it is a file whose endpoint columns are named something
+     * else entirely -- and the reader has no idea what. Dropping it produced a graph with no edges,
+     * a pile of "Missing source" errors and a load that reported success. Handing it over unread
+     * lets the ELEMENT refuse the batch and name the columns the file does carry, which is the one
+     * message a reader can act on. The rows are read as a node table numbered by row, so no column
+     * is taken as an id and every column of every row is kept.
+     * @param content - the file's text
+     * @yields the rows as edge records, and no nodes
+     */
+    private passThroughRows;
+    /**
+     * Read a Neo4j admin-import file: node sections and relationship sections, each under its own
+     * header row.
+     *
+     * The records keep the keys the element's reader always gave them: a node's `:LABEL` cell
+     * arrives as `label` (several labels joined by `;`, as the cell wrote them) and a
+     * relationship's `:TYPE` as `type`.
+     *
+     * This importer declares NO direction, deliberately. A Neo4j relationship is directed as a
+     * property of the database, not as something the CSV states -- the file carries :START_ID and
+     * :END_ID and no field that could say otherwise -- so there is nothing here to read. The
+     * element's own configuration stands, and under "auto" that is already directed.
+     * @param content - the file's text
+     * @yields the nodes and relationships
+     */
+    private parseNeo4j;
     private parsePairedFiles;
+    /**
+     * Declare the direction a Gephi `Type` column states, then yield the records in chunks.
+     *
+     * The same `Type` column is read on every route -- a single edge file, or the edge file of a
+     * pair: an export split into a node file and an edge file is the same export, and must not be
+     * read as a different graph because of how it was handed over. It is declared before the first
+     * chunk is yielded, and therefore before the first edge reaches the builder.
+     * The id and endpoints are written last, so an attribute column that happens to be named
+     * `id`, `source` or `target` cannot take their place.
+     * @param nodes - the nodes
+     * @param edges - the edges
+     * @yields the chunks
+     */
+    private emit;
+    /**
+     * Record an error, and stop the load at the error limit as every reader does.
+     * @param error - the error
+     */
+    private addError;
 }
 export {};

package/dist/src/data/ErrorAggregator.d.ts

@@ -50,6 +50,11 @@ export declare class ErrorAggregator {
      * @returns The count of accumulated errors
      */
     getErrorCount(): number;
+    /**
+     * Get the number of errors this aggregator collects before it stops
+     * @returns The error limit
+     */
+    getErrorLimit(): number;
     /**
      * Check if error limit has been reached
      * @returns True if the maximum error count has been reached

package/dist/src/data/GEXFDataSource.d.ts

@@ -1,16 +1,18 @@
 import { BaseDataSourceConfig, DataSource, DataSourceChunk } from "./DataSource.js";
 type GEXFDataSourceConfig = BaseDataSourceConfig;
 /**
- * Data source for loading graph data from GEXF (Graph Exchange XML Format) files.
- * Supports node and edge attributes, attribute types, and dynamic graphs.
+ * Data source for loading graph data from GEXF (Graph Exchange XML Format) files, read by
+ * `@graphty/graph-io`'s GEXF importer. Supports node and edge attributes, attribute types, the viz
+ * namespace and dynamic graphs.
  *
  * Dynamic graphs keep their time data on each record rather than acting on it:
- * - a node's or edge's `start` / `end` / `timestamp` (see {@link readInterval}) go onto its data
- *   under those names, and its `<spells>` go onto `spells` as a list of the same intervals;
+ * - a node's or edge's `start` / `end` / `timestamp` go onto its data under those names, with
+ *   `startOpen` / `endOpen` set for an open bound, and its `<spells>` go onto `spells` as a list of
+ *   `{ start, end }` intervals;
  * - an attribute with time-sliced `attvalue`s becomes a list of `{ value, start, end }` slices
  *   instead of a single value. An attribute with no timed `attvalue` keeps its plain value.
  *
- * Dynamic `viz:*` elements (timed positions, colours or sizes) are not read.
+ * An edge that names a node the file never declared is kept, and the node is created for it.
  */
 export declare class GEXFDataSource extends DataSource {
     static readonly type = "gexf";
@@ -27,62 +29,11 @@ export declare class GEXFDataSource extends DataSource {
      */
     sourceFetchData(): AsyncGenerator<DataSourceChunk, void, unknown>;
     /**
-     * The direction the `<graph>` element declares.
-     *
-     * `defaultedgetype` is optional in GEXF and its schema gives it the default `undirected`, so a
-     * GEXF file that omits it is NOT silent about its direction: it has said undirected, the same
-     * way it would have by writing the attribute out, and that is how every other GEXF reader
-     * takes it, NetworkX included.
-     *
-     * WHY THE CALLER IS TOLD WHETHER THE ATTRIBUTE WAS WRITTEN. A direction the file's author typed
-     * out and a direction the schema supplied for them are not equally strong, and the difference
-     * decides what happens when the edges say something else. An author who wrote
-     * `defaultedgetype="undirected"` and then marked one edge `type="directed"` described a mixed
-     * graph, and the graph-level statement is the one to keep. An author who wrote no
-     * `defaultedgetype` at all and marked every edge `type="directed"` stated direction in exactly
-     * one place, and reading that file as undirected would invent a reverse path for every edge in
-     * it. Both cases arrive here as `directed: false`; only `written` separates them.
-     *
-     * An unreadable value is reported as unwritten, because a keyword GEXF does not define is not a
-     * statement the element can act on -- but the text says the attribute was there and could not
-     * be read, rather than claiming the file omitted it.
-     * @param graph - the parsed `<graph>` element
-     * @returns the direction, whether the file actually wrote it, and the text that stated it
+     * Import the document through graph-io.
+     * @param text - the document
+     * @param defaultDirected - the direction an edge without a `type` takes when the graph wrote none
+     * @returns the import
      */
-    private readDefaultEdgeType;
-    private parseAttributeDefinitions;
-    private parseNodes;
-    /**
-     * Parse the `<edges>` children, and tally what each one said about its own direction.
-     *
-     * A GEXF edge may carry its own `type`, which makes a MIXED graph expressible in the file and
-     * not in the element: the snapshot holds one direction flag for the whole graph. So the two
-     * tallies returned here are raw counts rather than a count of disagreements -- which edges
-     * disagree cannot be known until the graph's direction is settled, and on a file that never
-     * wrote `defaultedgetype` these tallies are what settles it. {@link resolveDirection} decides.
-     *
-     * Nothing is thrown away either way: each edge keeps its own `type` on its record, so a style
-     * layer can still draw that one edge differently.
-     * @param edgeData - the parsed `<edge>` elements
-     * @param attributes - the edge attribute definitions
-     * @returns the edge records, and how many edges stated each direction
-     */
-    private parseEdges;
-    /**
-     * Copy a node's or edge's lifetime, spells and attribute values onto its record.
-     *
-     * Every `attvalue` for one attribute is kept: if any of them is timed, the attribute becomes
-     * the list of all its slices, `{ value, start, end }`, in file order; otherwise it keeps its
-     * plain value, so a static file reads exactly as it always has.
-     * @param obj - the parsed `<node>` or `<edge>`
-     * @param obj.attvalues - its `<attvalues>` element, if any
-     * @param obj.attvalues.attvalue - the `<attvalue>` children
-     * @param obj.spells - its `<spells>` element, if any
-     * @param obj.spells.spell - the `<spell>` children
-     * @param record - the record being built, written in place
-     * @param attributes - the attribute definitions for this element class
-     */
-    private readTimeData;
-    private parseValue;
+    private read;
 }
 export {};

package/dist/src/data/GraphMLDataSource.d.ts

@@ -1,8 +1,9 @@
 import { BaseDataSourceConfig, DataSource, DataSourceChunk } from "./DataSource.js";
 type GraphMLDataSourceConfig = BaseDataSourceConfig;
 /**
- * Data source for loading graph data from GraphML files.
- * Supports GraphML format with yFiles extensions for node shapes and edge styles.
+ * Data source for loading graph data from GraphML files, read by `@graphty/graph-io`'s GraphML
+ * importer. Supports key definitions and data elements, and the yFiles `ShapeNode` and
+ * `PolyLineEdge` graphics (position, size, colours, border, label, shape and arrows).
  */
 export declare class GraphMLDataSource extends DataSource {
     static readonly type = "graphml";
@@ -18,47 +19,5 @@ export declare class GraphMLDataSource extends DataSource {
      * @yields DataSourceChunk objects containing parsed nodes and edges
      */
     sourceFetchData(): AsyncGenerator<DataSourceChunk, void, unknown>;
-    private parseKeyDefinitions;
-    private parseNodes;
-    /**
-     * Parse the `<edge>` children, and count the ones that contradict the graph's declaration.
-     *
-     * A GraphML edge may carry `directed="true|false"` of its own, which overrides `edgedefault`
-     * for that edge alone and so makes a MIXED graph expressible in the file but not in the
-     * element, whose snapshot holds one direction flag for the whole graph. `edgedefault` is what
-     * the element adopts, because it is the file's statement about the graph AS A WHOLE. The
-     * per-edge value is not discarded: it is kept on the edge record as `directed`, where a style
-     * layer can still read it, and the count returned here is what the element logs.
-     * @param edgeData - the parsed `<edge>` elements
-     * @param keys - the key definitions
-     * @param declaredDirected - what `edgedefault` declared, or null when it declared nothing
-     * @returns the edge records, and how many carried a `directed` attribute that disagrees
-     */
-    private parseEdges;
-    private parseValue;
-    /**
-     * Maps yFiles shape types to Graphty shape types
-     * @param yfilesShape - yFiles shape type identifier
-     * @returns Corresponding Graphty shape type
-     */
-    private mapYFilesShape;
-    /**
-     * Normalizes color to standard hex format (#RRGGBB)
-     * @param color - Color value in any format
-     * @returns Normalized hex color string
-     */
-    private normalizeColor;
-    /**
-     * Parses yFiles ShapeNode data and extracts visual properties
-     * @param shapeNode - yFiles ShapeNode data structure
-     * @returns Object containing extracted node properties
-     */
-    private parseYFilesShapeNode;
-    /**
-     * Parses yFiles PolyLineEdge data and extracts visual properties
-     * @param polyLineEdge - yFiles PolyLineEdge data structure
-     * @returns Object containing extracted edge properties
-     */
-    private parseYFilesPolyLineEdge;
 }
 export {};