laranex-schema-viewer-ui 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright (c) Laranex
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/NOTICE

@@ -0,0 +1,22 @@
+Laranex Schema Viewer UI is licensed under the MIT License (see LICENSE).
+
+The viewer's visual design, layout, palette and interaction model follow
+Laranex Python Schema Viewer, src/laranex_schema_viewer/static/, inspected at
+commit de08475 (https://github.com/laranex/python-schema-viewer).
+
+The automatic layout (arrange modes and packed columns)
+and orthogonal edge routing are adapted from Laranex Laravel Schema Viewer,
+ui/src/elk.ts, ui/src/layout.ts and ui/src/routing.ts, inspected at commit
+62b056a (https://github.com/laranex/laravel-schema-viewer).
+
+The laranex-schema contract takes its structure and camelCase naming from
+Laravel Schema Viewer's serialized document (src/Schema/*.php) and its
+provenance-preserving rules from Python Schema Viewer's snapshot contract
+(src/laranex_schema_viewer/document.py). The graph rules follow Laravel's
+src/Graph/SchemaGraph.php. All fixtures are synthetic.
+
+Copyright (c) Laranex. Used under the MIT License reproduced in LICENSE.
+
+The standalone bundle includes IBM Plex Sans and IBM Plex Mono
+(SIL Open Font License 1.1, via @fontsource), elkjs (Eclipse Public License
+2.0), React and React DOM (MIT) and @xyflow/react (MIT).

package/README.md

@@ -1,3 +1,26 @@
-# Temporary Holding Version
+# Laranex Schema Viewer UI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+One JSON contract, one shared viewer, many frameworks: the `laranex-schema` contract and the ERD viewer shared by the
+Laravel, Python and Node.js schema viewers.
+
+The contract is specified in [docs/contract.md](docs/contract.md); hosts integrate the viewer as described in
+[docs/integration.md](docs/integration.md); planned work is in
+[ROADMAP.md](ROADMAP.md); see `AGENTS.md` for the architecture and development workflow.
+
+```tsx
+import { SchemaViewer } from 'laranex-schema-viewer-ui';
+import 'laranex-schema-viewer-ui/styles.css';
+
+<SchemaViewer document={laranexSchemaDocument} />;
+```
+
+```js
+import { validateDocument, buildGraph, canonicalJson } from 'laranex-schema-viewer-ui/contract';
+```
+
+Hosts without Node.js serve `node_modules/laranex-schema-viewer-ui/dist/viewer/` as static files with a
+`snapshot.json` beside `index.html`, or use `<laranex-schema-viewer src="snapshot.json">`.
+
+## License
+
+MIT. See [LICENSE](LICENSE) and [NOTICE](NOTICE).

package/contract/check.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// Checks laranex-schema documents a producer wrote, for Laravel, Python and Node.js CI alike:
+//
+//   node node_modules/laranex-schema-viewer-ui/contract/check.mjs [--lenient] [--no-graph] [--no-canonical] FILE...
+//
+// By default a document must pass strict validation, store exactly the links the shared graph builder produces, and
+// be written in canonical form. Exits 1 when any file fails.
+import { readFileSync } from 'node:fs';
+import { buildGraph, canonicalJson, validateDocument } from '../dist/lib/contract.js';
+
+const args = process.argv.slice(2);
+const flags = new Set(args.filter((a) => a.startsWith('--')));
+const files = args.filter((a) => !a.startsWith('--'));
+if (files.length === 0 || flags.has('--help')) {
+    console.error('usage: check.mjs [--lenient] [--no-graph] [--no-canonical] FILE...');
+    process.exit(files.length === 0 ? 2 : 0);
+}
+
+let failed = false;
+for (const file of files) {
+    const problems = [];
+    const text = readFileSync(file, 'utf8');
+    let doc;
+    try {
+        doc = JSON.parse(text);
+    } catch (error) {
+        problems.push(`not JSON: ${error.message}`);
+    }
+    if (doc !== undefined) {
+        const result = validateDocument(doc, { strict: !flags.has('--lenient') });
+        problems.push(...result.errors);
+        if (result.ok && !flags.has('--no-graph')) {
+            const expected = buildGraph(doc);
+            if (canonicalJson(expected.links) !== canonicalJson(doc.links)) {
+                problems.push('links differ from the shared graph builder');
+            }
+            if (canonicalJson(expected.derivedLinks) !== canonicalJson(doc.derivedLinks)) {
+                problems.push('derivedLinks differ from the shared graph builder');
+            }
+        }
+        if (!flags.has('--no-canonical') && canonicalJson(doc) !== text) {
+            problems.push('not in canonical form (sorted keys, two-space indentation, trailing newline)');
+        }
+    }
+    if (problems.length) {
+        failed = true;
+        console.error(`✗ ${file}`);
+        problems.forEach((p) => console.error(`  ${p}`));
+    } else {
+        console.log(`✓ ${file}`);
+    }
+}
+process.exit(failed ? 1 : 0);

package/contract/conformance/graph/composite-unordered-pairs.json

@@ -0,0 +1,222 @@
+{
+  "description": "Composite keys match as unordered column pairs; the link keeps the foreign key column order",
+  "expected": {
+    "derivedLinks": [],
+    "links": [
+      {
+        "foreignKey": "t:lines:fk:lines_product_fk",
+        "from": {
+          "columns": [
+            "sku",
+            "region"
+          ],
+          "table": "t:lines"
+        },
+        "id": "l14daded68942fdde",
+        "note": null,
+        "polymorphic": false,
+        "relationships": [
+          "r:product"
+        ],
+        "state": "both",
+        "to": {
+          "columns": [
+            "sku",
+            "region"
+          ],
+          "table": "t:products"
+        }
+      }
+    ]
+  },
+  "input": {
+    "connections": [
+      {
+        "coverage": {
+          "database": null,
+          "declared": null
+        },
+        "defaultSchema": null,
+        "driver": "pgsql",
+        "id": "connection:c",
+        "name": "c",
+        "tables": [
+          {
+            "columns": [
+              {
+                "autoIncrement": false,
+                "collation": null,
+                "comment": null,
+                "default": null,
+                "enum": null,
+                "generated": null,
+                "name": "sku",
+                "note": null,
+                "nullable": false,
+                "ormDefault": null,
+                "provenance": [
+                  "database"
+                ],
+                "timezone": null,
+                "type": "integer",
+                "typeName": "integer"
+              },
+              {
+                "autoIncrement": false,
+                "collation": null,
+                "comment": null,
+                "default": null,
+                "enum": null,
+                "generated": null,
+                "name": "region",
+                "note": null,
+                "nullable": false,
+                "ormDefault": null,
+                "provenance": [
+                  "database"
+                ],
+                "timezone": null,
+                "type": "integer",
+                "typeName": "integer"
+              }
+            ],
+            "comment": null,
+            "constraints": [],
+            "foreignKeys": [
+              {
+                "columns": [
+                  "sku",
+                  "region"
+                ],
+                "deferrable": null,
+                "foreignColumns": [
+                  "sku",
+                  "region"
+                ],
+                "foreignTable": "t:products",
+                "id": "t:lines:fk:lines_product_fk",
+                "initially": null,
+                "name": "lines_product_fk",
+                "onDelete": null,
+                "onUpdate": null,
+                "provenance": [
+                  "database"
+                ]
+              }
+            ],
+            "id": "t:lines",
+            "indexes": [],
+            "name": "lines",
+            "note": null,
+            "owner": {
+              "kind": "application",
+              "package": null
+            },
+            "primaryKey": [],
+            "provenance": [
+              "database"
+            ],
+            "schema": null
+          },
+          {
+            "columns": [
+              {
+                "autoIncrement": false,
+                "collation": null,
+                "comment": null,
+                "default": null,
+                "enum": null,
+                "generated": null,
+                "name": "sku",
+                "note": null,
+                "nullable": false,
+                "ormDefault": null,
+                "provenance": [
+                  "database"
+                ],
+                "timezone": null,
+                "type": "integer",
+                "typeName": "integer"
+              },
+              {
+                "autoIncrement": false,
+                "collation": null,
+                "comment": null,
+                "default": null,
+                "enum": null,
+                "generated": null,
+                "name": "region",
+                "note": null,
+                "nullable": false,
+                "ormDefault": null,
+                "provenance": [
+                  "database"
+                ],
+                "timezone": null,
+                "type": "integer",
+                "typeName": "integer"
+              }
+            ],
+            "comment": null,
+            "constraints": [],
+            "foreignKeys": [],
+            "id": "t:products",
+            "indexes": [],
+            "name": "products",
+            "note": null,
+            "owner": {
+              "kind": "application",
+              "package": null
+            },
+            "primaryKey": [
+              "sku",
+              "region"
+            ],
+            "provenance": [
+              "database"
+            ],
+            "schema": null
+          }
+        ]
+      }
+    ],
+    "relationships": [
+      {
+        "cardinality": "many-to-one",
+        "collection": false,
+        "constraints": [],
+        "id": "r:product",
+        "inverse": null,
+        "join": null,
+        "keys": {
+          "from": {
+            "columns": [
+              "region",
+              "sku"
+            ],
+            "table": "t:lines"
+          },
+          "to": {
+            "columns": [
+              "region",
+              "sku"
+            ],
+            "table": "t:products"
+          }
+        },
+        "model": "m",
+        "name": "r:product",
+        "note": null,
+        "pivot": null,
+        "polymorphic": null,
+        "readOnly": false,
+        "relatedModel": null,
+        "relatedTable": "t:products",
+        "source": null,
+        "table": "t:lines",
+        "through": null,
+        "type": "test"
+      }
+    ]
+  }
+}

package/contract/conformance/graph/cross-connection-foreign-key.json

@@ -0,0 +1,153 @@
+{
+  "description": "A foreign key naming a table in another connection has no link: constraints never cross connections",
+  "expected": {
+    "derivedLinks": [],
+    "links": []
+  },
+  "input": {
+    "connections": [
+      {
+        "coverage": {
+          "database": null,
+          "declared": null
+        },
+        "defaultSchema": null,
+        "driver": "pgsql",
+        "id": "connection:a",
+        "name": "a",
+        "tables": [
+          {
+            "columns": [
+              {
+                "autoIncrement": false,
+                "collation": null,
+                "comment": null,
+                "default": null,
+                "enum": null,
+                "generated": null,
+                "name": "id",
+                "note": null,
+                "nullable": false,
+                "ormDefault": null,
+                "provenance": [
+                  "database"
+                ],
+                "timezone": null,
+                "type": "integer",
+                "typeName": "integer"
+              }
+            ],
+            "comment": null,
+            "constraints": [],
+            "foreignKeys": [],
+            "id": "a:users",
+            "indexes": [],
+            "name": "users",
+            "note": null,
+            "owner": {
+              "kind": "application",
+              "package": null
+            },
+            "primaryKey": [
+              "id"
+            ],
+            "provenance": [
+              "database"
+            ],
+            "schema": null
+          }
+        ]
+      },
+      {
+        "coverage": {
+          "database": null,
+          "declared": null
+        },
+        "defaultSchema": null,
+        "driver": "mysql",
+        "id": "connection:b",
+        "name": "b",
+        "tables": [
+          {
+            "columns": [
+              {
+                "autoIncrement": false,
+                "collation": null,
+                "comment": null,
+                "default": null,
+                "enum": null,
+                "generated": null,
+                "name": "id",
+                "note": null,
+                "nullable": false,
+                "ormDefault": null,
+                "provenance": [
+                  "database"
+                ],
+                "timezone": null,
+                "type": "integer",
+                "typeName": "integer"
+              },
+              {
+                "autoIncrement": false,
+                "collation": null,
+                "comment": null,
+                "default": null,
+                "enum": null,
+                "generated": null,
+                "name": "user_id",
+                "note": null,
+                "nullable": false,
+                "ormDefault": null,
+                "provenance": [
+                  "database"
+                ],
+                "timezone": null,
+                "type": "integer",
+                "typeName": "integer"
+              }
+            ],
+            "comment": null,
+            "constraints": [],
+            "foreignKeys": [
+              {
+                "columns": [
+                  "user_id"
+                ],
+                "deferrable": null,
+                "foreignColumns": [
+                  "id"
+                ],
+                "foreignTable": "a:users",
+                "id": "b:sessions:fk:sessions_user_fk",
+                "initially": null,
+                "name": "sessions_user_fk",
+                "onDelete": null,
+                "onUpdate": null,
+                "provenance": [
+                  "database"
+                ]
+              }
+            ],
+            "id": "b:sessions",
+            "indexes": [],
+            "name": "sessions",
+            "note": null,
+            "owner": {
+              "kind": "application",
+              "package": null
+            },
+            "primaryKey": [
+              "id"
+            ],
+            "provenance": [
+              "database"
+            ],
+            "schema": null
+          }
+        ]
+      }
+    ],
+    "relationships": []
+  }
+}

package/contract/conformance/graph/cross-connection-relationship.json

@@ -0,0 +1,192 @@
+{
+  "description": "A relationship from a table in one connection to a table in another is a relationship link; no constraint is implied",
+  "expected": {
+    "derivedLinks": [],
+    "links": [
+      {
+        "foreignKey": null,
+        "from": {
+          "columns": [
+            "user_id"
+          ],
+          "table": "b:sessions"
+        },
+        "id": "lf0820d9a701f3777",
+        "note": null,
+        "polymorphic": false,
+        "relationships": [
+          "r:user"
+        ],
+        "state": "relationship",
+        "to": {
+          "columns": [
+            "id"
+          ],
+          "table": "a:users"
+        }
+      }
+    ]
+  },
+  "input": {
+    "connections": [
+      {
+        "coverage": {
+          "database": null,
+          "declared": null
+        },
+        "defaultSchema": null,
+        "driver": "pgsql",
+        "id": "connection:a",
+        "name": "a",
+        "tables": [
+          {
+            "columns": [
+              {
+                "autoIncrement": false,
+                "collation": null,
+                "comment": null,
+                "default": null,
+                "enum": null,
+                "generated": null,
+                "name": "id",
+                "note": null,
+                "nullable": false,
+                "ormDefault": null,
+                "provenance": [
+                  "database"
+                ],
+                "timezone": null,
+                "type": "integer",
+                "typeName": "integer"
+              }
+            ],
+            "comment": null,
+            "constraints": [],
+            "foreignKeys": [],
+            "id": "a:users",
+            "indexes": [],
+            "name": "users",
+            "note": null,
+            "owner": {
+              "kind": "application",
+              "package": null
+            },
+            "primaryKey": [
+              "id"
+            ],
+            "provenance": [
+              "database"
+            ],
+            "schema": null
+          }
+        ]
+      },
+      {
+        "coverage": {
+          "database": null,
+          "declared": null
+        },
+        "defaultSchema": null,
+        "driver": "mysql",
+        "id": "connection:b",
+        "name": "b",
+        "tables": [
+          {
+            "columns": [
+              {
+                "autoIncrement": false,
+                "collation": null,
+                "comment": null,
+                "default": null,
+                "enum": null,
+                "generated": null,
+                "name": "id",
+                "note": null,
+                "nullable": false,
+                "ormDefault": null,
+                "provenance": [
+                  "database"
+                ],
+                "timezone": null,
+                "type": "integer",
+                "typeName": "integer"
+              },
+              {
+                "autoIncrement": false,
+                "collation": null,
+                "comment": null,
+                "default": null,
+                "enum": null,
+                "generated": null,
+                "name": "user_id",
+                "note": null,
+                "nullable": false,
+                "ormDefault": null,
+                "provenance": [
+                  "database"
+                ],
+                "timezone": null,
+                "type": "integer",
+                "typeName": "integer"
+              }
+            ],
+            "comment": null,
+            "constraints": [],
+            "foreignKeys": [],
+            "id": "b:sessions",
+            "indexes": [],
+            "name": "sessions",
+            "note": null,
+            "owner": {
+              "kind": "application",
+              "package": null
+            },
+            "primaryKey": [
+              "id"
+            ],
+            "provenance": [
+              "database"
+            ],
+            "schema": null
+          }
+        ]
+      }
+    ],
+    "relationships": [
+      {
+        "cardinality": "many-to-one",
+        "collection": false,
+        "constraints": [],
+        "id": "r:user",
+        "inverse": null,
+        "join": null,
+        "keys": {
+          "from": {
+            "columns": [
+              "user_id"
+            ],
+            "table": "b:sessions"
+          },
+          "to": {
+            "columns": [
+              "id"
+            ],
+            "table": "a:users"
+          }
+        },
+        "model": "m",
+        "name": "r:user",
+        "note": null,
+        "pivot": null,
+        "polymorphic": null,
+        "readOnly": false,
+        "relatedModel": null,
+        "relatedTable": "a:users",
+        "source": null,
+        "table": "b:sessions",
+        "through": null,
+        "type": "test"
+      }
+    ]
+  }
+}