@qkix/strapi-plugin-blueprint 0.1.0

package/dist/server/src/services/graph.d.ts

@@ -0,0 +1,69 @@
+import type { Core } from '@strapi/strapi';
+import type { Edge, Field, Graph, GraphOptions } from '../types';
+export declare const DEFAULTS: GraphOptions;
+export interface RawAttribute {
+    type: string;
+    relation?: string;
+    target?: string;
+    component?: string;
+    components?: string[];
+    repeatable?: boolean;
+    required?: boolean;
+    /** Present on the *non-owning* side of a two-sided relation. */
+    mappedBy?: string;
+    inversedBy?: string;
+}
+export interface RawModel {
+    uid: string;
+    kind?: string;
+    modelType?: string;
+    category?: string;
+    info?: {
+        displayName?: string;
+        singularName?: string;
+    };
+    attributes?: Record<string, RawAttribute>;
+    pluginOptions?: {
+        'content-type-builder'?: {
+            visible?: boolean;
+        };
+    };
+}
+declare const graph: ({ strapi }: {
+    strapi: Core.Strapi;
+}) => {
+    /**
+     * The whole schema as a graph.
+     *
+     * Reads Strapi's own loaded models rather than the files on disk, so a
+     * content type a plugin adds at runtime is on the diagram too, and nothing
+     * has to be parsed.
+     */
+    build(options?: Partial<GraphOptions>): Graph;
+    fieldsOf(model: RawModel, opts: GraphOptions): Field[];
+    /**
+     * Edges, one per reason two boxes are joined.
+     *
+     * Both ends of a two-sided relation describe the same line. Strapi marks
+     * the non-owning end with `mappedBy`, so skipping those leaves exactly one
+     * edge — deduplicating by node pair instead would silently merge two
+     * genuinely different relations between the same two types.
+     *
+     * Edges to something not on the diagram are dropped rather than drawn into
+     * nothing: with `includeComponents` off, every component attribute would
+     * otherwise become a line to a box that is not there.
+     *
+     * A field that is not drawn does not get a line either, and that is not a
+     * detail. i18n adds a `localizations` relation **to every content type,
+     * pointing at itself**, so skipping it in the field list but not here put a
+     * self-loop on every single box on the diagram.
+     */
+    edgesOf(present: Map<string, RawModel>, opts: GraphOptions): Edge[];
+    /** Everything that could be excluded, for the settings UI. */
+    catalogue(): Array<{
+        uid: string;
+        label: string;
+        kind: string;
+    }>;
+};
+export default graph;

package/dist/server/src/services/index.d.ts

@@ -0,0 +1,15 @@
+declare const _default: {
+    graph: ({ strapi }: {
+        strapi: import("@strapi/types/dist/core").Strapi;
+    }) => {
+        build(options?: Partial<import("../types").GraphOptions>): import("../types").Graph;
+        fieldsOf(model: import("./graph").RawModel, opts: import("../types").GraphOptions): import("../types").Field[];
+        edgesOf(present: Map<string, import("./graph").RawModel>, opts: import("../types").GraphOptions): import("../types").Edge[];
+        catalogue(): {
+            uid: string;
+            label: string;
+            kind: string;
+        }[];
+    };
+};
+export default _default;

package/dist/server/src/services/layout.d.ts

@@ -0,0 +1,42 @@
+import type { Graph, Layout } from '../types';
+/**
+ * Box metrics. Kept here rather than in the renderer because the layout has to
+ * agree with the drawing about how big a box is, and two copies of that drift.
+ */
+export declare const METRICS: {
+    headerHeight: number;
+    rowHeight: number;
+    paddingX: number;
+    /** Rough width of one character at the font size the renderer uses. */
+    charWidth: number;
+    minWidth: number;
+    maxWidth: number;
+    /** Room for the type, drawn right-aligned on the same row as the name. */
+    typeGutter: number;
+};
+export type Direction = 'TB' | 'LR';
+/**
+ * How many fields a box shows before it gives up and counts the rest.
+ *
+ * Strapi's own `File` has fifteen, and a diagram where one box is four times
+ * the height of its neighbours reads as a wall rather than a shape. The whole
+ * list is still a click away in the Content-Type Builder; the picture is for
+ * seeing how things connect.
+ */
+export declare const MAX_ROWS = 12;
+/** What a box actually draws, and how much it is leaving out. */
+export declare const rowsOf: (node: Graph['nodes'][number]) => {
+    fields: import("../types").Field[];
+    hidden: number;
+};
+/**
+ * Positions every box and routes every line.
+ *
+ * dagre does the hard part. It runs on the server, which is the whole point:
+ * the incumbents in this category all layout in the browser with a React graph
+ * library, which is what tied them to React and styled-components versions and
+ * is why both of them broke. A layered-graph algorithm has no opinion about the
+ * UI framework, and the SVG it feeds can be produced with no browser at all.
+ */
+export declare const layout: (graph: Graph, direction?: Direction) => Layout;
+export default layout;

package/dist/server/src/services/svg.d.ts

@@ -0,0 +1,23 @@
+import type { Layout } from '../types';
+/**
+ * Every string that reaches the output goes through here.
+ *
+ * Content-type names come from developers rather than from the public, so this
+ * is not the front line of anything — but the SVG is injected into the admin
+ * panel's DOM and also handed to people to commit into a repository, and a
+ * display name containing `</text><script>` must not become script in either
+ * place. Escaping at the boundary is the only version of this that stays true
+ * as the renderer grows.
+ */
+export declare const escapeXml: (value: string) => string;
+/**
+ * The diagram, as a standalone SVG document.
+ *
+ * Standalone on purpose — styles and marker inline, no external references — so
+ * the same bytes work in the admin panel, in a README, and opened straight from
+ * a downloads folder. An `<img>` tag will not fetch anything an SVG refers to,
+ * which is what makes the usual "export" of this category a raster screenshot
+ * rather than a drawing you can scale.
+ */
+export declare const render: (placed: Layout) => string;
+export default render;

package/dist/server/src/types.d.ts

@@ -0,0 +1,83 @@
+/** What a node on the diagram is. The three kinds are drawn differently. */
+export type NodeKind = 'collectionType' | 'singleType' | 'component';
+export interface Field {
+    name: string;
+    /** The Strapi attribute type, shown verbatim: `string`, `media`, `relation`… */
+    type: string;
+    /** `oneToMany`, `manyToOne`… only on relations, and only when Strapi says so. */
+    relation?: string;
+    required?: boolean;
+}
+export interface Node {
+    /** The content-type or component uid — unique, and what edges point at. */
+    uid: string;
+    kind: NodeKind;
+    /** `Article`, `Shared / Seo` — what the admin panel calls it. */
+    label: string;
+    /** `api`, `plugin::users-permissions`, or the component category. */
+    group: string;
+    fields: Field[];
+    /** True for anything Strapi or a plugin owns, rather than the user's own API. */
+    foreign: boolean;
+    /**
+     * Whether this box has a page in the Content-Type Builder to open.
+     *
+     * A plugin's internal tables — Greenlight's transition log, upload's folders,
+     * every `admin::` type — are real content types and belong on the diagram, but
+     * there is nowhere to send someone who clicks one.
+     */
+    navigable: boolean;
+}
+/**
+ * Why two nodes are joined.
+ *
+ * `relation` is the classic ERD edge. The other two are the reason this plugin
+ * exists: every diagram in this category draws relations only, so a schema built
+ * out of components — which is most of them — shows up as a handful of
+ * disconnected boxes and tells you nothing.
+ */
+export type EdgeKind = 'relation' | 'component' | 'dynamiczone';
+export interface Edge {
+    from: string;
+    to: string;
+    kind: EdgeKind;
+    /** The attribute on `from` that causes the edge. */
+    field: string;
+    /** `oneToMany` and friends, for relations. */
+    cardinality?: string;
+    /** A repeatable component, or a dynamic zone: many of the target, not one. */
+    many?: boolean;
+}
+export interface Graph {
+    nodes: Node[];
+    edges: Edge[];
+}
+/** What the caller asked to see. Everything defaults to the useful answer. */
+export interface GraphOptions {
+    /** Content types owned by Strapi or by plugins — noise for most people. */
+    includeForeign: boolean;
+    /** Components and dynamic zones, and the edges into them. */
+    includeComponents: boolean;
+    /** `createdAt`, `updatedAt`, `publishedAt`, `locale` and friends. */
+    includeDefaultFields: boolean;
+    /** Uids to leave out entirely, whatever else is on. */
+    exclude: string[];
+}
+export interface Placed extends Node {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface RoutedEdge extends Edge {
+    points: Array<{
+        x: number;
+        y: number;
+    }>;
+}
+export interface Layout {
+    nodes: Placed[];
+    edges: RoutedEdge[];
+    width: number;
+    height: number;
+}

package/dist/server/src/uids.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The plugin id, in one place.
+ *
+ * It appears in route paths, permission names and the admin panel's URL, so
+ * changing it later breaks installs rather than merely renaming a thing.
+ */
+export declare const PLUGIN_ID = "blueprint";

package/package.json

@@ -0,0 +1,121 @@
+{
+  "name": "@qkix/strapi-plugin-blueprint",
+  "version": "0.1.0",
+  "description": "A diagram of your Strapi v5 content types, components and dynamic zones — rendered as real SVG",
+  "strapi": {
+    "kind": "plugin",
+    "name": "blueprint",
+    "displayName": "Blueprint",
+    "description": "A diagram of your Strapi v5 content types, components and dynamic zones — rendered as real SVG"
+  },
+  "keywords": [
+    "strapi",
+    "strapi-plugin",
+    "strapi-v5",
+    "erd",
+    "diagram",
+    "schema",
+    "content-types",
+    "visualisation",
+    "documentation",
+    "svg",
+    "cms",
+    "headless-cms"
+  ],
+  "type": "commonjs",
+  "exports": {
+    "./package.json": "./package.json",
+    "./strapi-admin": {
+      "types": "./dist/admin/src/index.d.ts",
+      "source": "./admin/src/index.ts",
+      "import": "./dist/admin/index.mjs",
+      "require": "./dist/admin/index.js",
+      "default": "./dist/admin/index.js"
+    },
+    "./strapi-server": {
+      "types": "./dist/server/src/index.d.ts",
+      "source": "./server/src/index.ts",
+      "import": "./dist/server/index.mjs",
+      "require": "./dist/server/index.js",
+      "default": "./dist/server/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@dagrejs/dagre": "^1.1.4"
+  },
+  "devDependencies": {
+    "@strapi/sdk-plugin": "^5.3.2",
+    "@strapi/strapi": "^5.12.5",
+    "@strapi/typescript-utils": "^5.12.5",
+    "@types/react": "^18.3.8",
+    "@types/react-dom": "^18.3.0",
+    "eslint": "^10.8.1",
+    "prettier": "^3.5.3",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "react-router-dom": "^6.30.0",
+    "styled-components": "^6.1.17",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4",
+    "@qkix/eslint-config": "0.0.0",
+    "@qkix/strapi-test-harness": "0.0.0",
+    "@qkix/tsconfig": "0.0.0"
+  },
+  "peerDependencies": {
+    "@strapi/admin": "^5.0.0",
+    "@strapi/design-system": "^2.0.0",
+    "@strapi/icons": "^2.0.0",
+    "@strapi/strapi": "^5.0.0",
+    "react": "^17.0.0 || ^18.0.0",
+    "react-dom": "^17.0.0 || ^18.0.0",
+    "react-intl": "^6.0.0 || ^7.0.0",
+    "react-router-dom": "^6.0.0",
+    "styled-components": "^6.0.0"
+  },
+  "engines": {
+    "node": ">=20.0.0 <=24.x.x",
+    "npm": ">=6.0.0"
+  },
+  "license": "MIT",
+  "author": "qkix",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/qkix/strapi-plugins.git",
+    "directory": "packages/strapi-plugin-blueprint"
+  },
+  "bugs": {
+    "url": "https://github.com/qkix/strapi-plugins/issues"
+  },
+  "homepage": "https://github.com/qkix/strapi-plugins#readme",
+  "nx": {
+    "tags": [
+      "scope:plugin"
+    ],
+    "targets": {
+      "test": {
+        "dependsOn": [
+          "build",
+          "^build"
+        ]
+      }
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && strapi-plugin build --minify",
+    "clean": "rm -rf dist",
+    "lint": "eslint . && prettier --check .",
+    "format": "prettier --write .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "verify": "strapi-plugin verify",
+    "watch": "strapi-plugin watch",
+    "watch:link": "strapi-plugin watch:link",
+    "typecheck": "tsc -p admin/tsconfig.json --noEmit && tsc -p server/tsconfig.json --noEmit"
+  }
+}