@x12i/diagrams 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 x12i
+
+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/README.md

@@ -1,3 +1,42 @@
-# Temporary Holding Version
-
-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.
+# @x12i/diagrams
+
+Diagram document schema for the Unified UI Kit, plus a text outline for screen
+readers.
+
+> **Status: foundation.** This package ships the versioned JSON schema and the
+> outline generator. The node canvas, Mermaid and Excalidraw wrappers are not
+> built yet.
+
+```ts
+import { defineDiagram, diagramToOutline } from "@x12i/diagrams";
+
+const diagram = defineDiagram({
+  version: 1,
+  title: "Order approval",
+  nodes: [
+    { id: "a", kind: "start", label: "Order placed", position: { x: 0, y: 0 } },
+    { id: "b", kind: "task", label: "Review", position: { x: 200, y: 0 } },
+    { id: "c", kind: "end", label: "Shipped", position: { x: 400, y: 0 } },
+  ],
+  edges: [
+    { id: "ab", source: "a", target: "b" },
+    { id: "bc", source: "b", target: "c" },
+  ],
+});
+
+diagramToOutline(diagram); // ["Order placed to Review to Shipped"]
+```
+
+Every canvas will generate this outline, so a diagram has a form screen readers
+can read (spec section 10).
+
+## Planned engines
+
+| Tier | Engine |
+| --- | --- |
+| Text to diagram | Mermaid (MIT) |
+| Node canvas | `@xyflow/react` (MIT) |
+| Freeform whiteboard | Excalidraw (MIT) |
+| Specialized layouts | D3 hierarchy (ISC) |
+
+tldraw is excluded on license grounds.

package/dist/index.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The kit's own diagram document (spec section 10). It is versioned JSON, so
+ * the node canvas engine can change without breaking saved diagrams.
+ */
+declare const DIAGRAM_VERSION = 1;
+/** The node library. Every node reads kit tokens. */
+type NodeKind = "start" | "end" | "task" | "decision" | "group" | "note" | "image" | "entity" | "code" | "chart" | "agent" | "subflow";
+/** Status colors match the rest of the kit: a status means the same in a badge, a chart and a node. */
+type NodeStatus = "neutral" | "success" | "warning" | "danger" | "info";
+type EdgeKind = "straight" | "bezier" | "step" | "smooth-step";
+interface Position {
+    x: number;
+    y: number;
+}
+interface DiagramNode {
+    id: string;
+    kind: NodeKind;
+    /** The text read aloud in the outline. Pass a translated string. */
+    label: string;
+    position: Position;
+    status?: NodeStatus;
+    /** Set on children of a group or subflow. */
+    parentId?: string;
+    width?: number;
+    height?: number;
+    /** Typed handles, for connection validation. */
+    ports?: Array<{
+        id: string;
+        direction: "in" | "out";
+        type?: string;
+    }>;
+    /** Free-form payload for custom node bodies, such as a ChartSpec for a chart node. */
+    data?: Record<string, unknown>;
+}
+interface DiagramEdge {
+    id: string;
+    source: string;
+    target: string;
+    sourcePort?: string;
+    targetPort?: string;
+    kind?: EdgeKind;
+    label?: string;
+    /** Draw arrowheads at both ends. */
+    bidirectional?: boolean;
+    animated?: boolean;
+}
+interface DiagramDocument {
+    version: typeof DIAGRAM_VERSION;
+    /** Every diagram has a title that states what it shows. */
+    title: string;
+    nodes: DiagramNode[];
+    edges: DiagramEdge[];
+}
+/** Identity helper for authoring-time type checking. */
+declare function defineDiagram(document: DiagramDocument): DiagramDocument;
+
+interface OutlineOptions {
+    /** Joins labels along a path. Pass a translated word. Defaults to "to". */
+    connector?: string;
+    /** Stop after this many paths so a dense graph cannot flood the outline. */
+    maxPaths?: number;
+}
+/**
+ * Generates the text outline that makes a diagram readable by screen readers:
+ * one line per path through the graph, such as "Start to Review to Approve".
+ * Nodes with no connections get a line of their own, and a path that loops back
+ * ends with the node it returns to.
+ */
+declare function diagramToOutline(diagram: DiagramDocument, { connector, maxPaths }?: OutlineOptions): string[];
+
+export { DIAGRAM_VERSION, defineDiagram, diagramToOutline };
+export type { DiagramDocument, DiagramEdge, DiagramNode, EdgeKind, NodeKind, NodeStatus, OutlineOptions, Position };

package/dist/index.js

@@ -0,0 +1,46 @@
+// src/schema.ts
+var DIAGRAM_VERSION = 1;
+function defineDiagram(document) {
+  return document;
+}
+
+// src/outline.ts
+function diagramToOutline(diagram, { connector = "to", maxPaths = 100 } = {}) {
+  const labels = new Map(diagram.nodes.map((node) => [node.id, node.label]));
+  const outgoing = /* @__PURE__ */ new Map();
+  const hasIncoming = /* @__PURE__ */ new Set();
+  for (const edge of diagram.edges) {
+    if (!labels.has(edge.source) || !labels.has(edge.target)) continue;
+    outgoing.set(edge.source, [...outgoing.get(edge.source) ?? [], edge.target]);
+    hasIncoming.add(edge.target);
+  }
+  const lines = [];
+  const visited = /* @__PURE__ */ new Set();
+  const label = (id) => labels.get(id) ?? id;
+  const sentence = (ids) => ids.map(label).join(` ${connector} `);
+  const walk = (id, trail) => {
+    if (lines.length >= maxPaths) return;
+    visited.add(id);
+    const path = [...trail, id];
+    const next = outgoing.get(id) ?? [];
+    if (next.length === 0) {
+      lines.push(sentence(path));
+      return;
+    }
+    for (const target of next) {
+      if (path.includes(target)) lines.push(sentence([...path, target]));
+      else walk(target, path);
+    }
+  };
+  for (const node of diagram.nodes) {
+    if (!hasIncoming.has(node.id)) walk(node.id, []);
+  }
+  for (const node of diagram.nodes) {
+    if (!visited.has(node.id)) walk(node.id, []);
+  }
+  return lines;
+}
+
+export { DIAGRAM_VERSION, defineDiagram, diagramToOutline };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schema.ts","../src/outline.ts"],"names":[],"mappings":";AAKO,IAAM,eAAA,GAAkB;AAkExB,SAAS,cAAc,QAAA,EAA4C;AACxE,EAAA,OAAO,QAAA;AACT;;;AC1DO,SAAS,gBAAA,CACd,SACA,EAAE,SAAA,GAAY,MAAM,QAAA,GAAW,GAAA,EAAI,GAAoB,EAAC,EAC9C;AACV,EAAA,MAAM,MAAA,GAAS,IAAI,GAAA,CAAI,OAAA,CAAQ,MAAM,GAAA,CAAI,CAAC,IAAA,KAAS,CAAC,IAAA,CAAK,EAAA,EAAI,IAAA,CAAK,KAAK,CAAC,CAAC,CAAA;AACzE,EAAA,MAAM,QAAA,uBAAe,GAAA,EAAsB;AAC3C,EAAA,MAAM,WAAA,uBAAkB,GAAA,EAAY;AAEpC,EAAA,KAAA,MAAW,IAAA,IAAQ,QAAQ,KAAA,EAAO;AAChC,IAAA,IAAI,CAAC,MAAA,CAAO,GAAA,CAAI,IAAA,CAAK,MAAM,CAAA,IAAK,CAAC,MAAA,CAAO,GAAA,CAAI,IAAA,CAAK,MAAM,CAAA,EAAG;AAC1D,IAAA,QAAA,CAAS,GAAA,CAAI,IAAA,CAAK,MAAA,EAAQ,CAAC,GAAI,QAAA,CAAS,GAAA,CAAI,IAAA,CAAK,MAAM,CAAA,IAAK,EAAC,EAAI,IAAA,CAAK,MAAM,CAAC,CAAA;AAC7E,IAAA,WAAA,CAAY,GAAA,CAAI,KAAK,MAAM,CAAA;AAAA,EAC7B;AAEA,EAAA,MAAM,QAAkB,EAAC;AACzB,EAAA,MAAM,OAAA,uBAAc,GAAA,EAAY;AAChC,EAAA,MAAM,QAAQ,CAAC,EAAA,KAAe,MAAA,CAAO,GAAA,CAAI,EAAE,CAAA,IAAK,EAAA;AAChD,EAAA,MAAM,QAAA,GAAW,CAAC,GAAA,KAAkB,GAAA,CAAI,GAAA,CAAI,KAAK,CAAA,CAAE,IAAA,CAAK,CAAA,CAAA,EAAI,SAAS,CAAA,CAAA,CAAG,CAAA;AAGxE,EAAA,MAAM,IAAA,GAAO,CAAC,EAAA,EAAY,KAAA,KAAoB;AAC5C,IAAA,IAAI,KAAA,CAAM,UAAU,QAAA,EAAU;AAC9B,IAAA,OAAA,CAAQ,IAAI,EAAE,CAAA;AACd,IAAA,MAAM,IAAA,GAAO,CAAC,GAAG,KAAA,EAAO,EAAE,CAAA;AAC1B,IAAA,MAAM,IAAA,GAAO,QAAA,CAAS,GAAA,CAAI,EAAE,KAAK,EAAC;AAElC,IAAA,IAAI,IAAA,CAAK,WAAW,CAAA,EAAG;AACrB,MAAA,KAAA,CAAM,IAAA,CAAK,QAAA,CAAS,IAAI,CAAC,CAAA;AACzB,MAAA;AAAA,IACF;AAEA,IAAA,KAAA,MAAW,UAAU,IAAA,EAAM;AACzB,MAAA,IAAI,IAAA,CAAK,QAAA,CAAS,MAAM,CAAA,EAAG,KAAA,CAAM,IAAA,CAAK,QAAA,CAAS,CAAC,GAAG,IAAA,EAAM,MAAM,CAAC,CAAC,CAAA;AAAA,WAC5D,IAAA,CAAK,QAAQ,IAAI,CAAA;AAAA,IACxB;AAAA,EACF,CAAA;AAEA,EAAA,KAAA,MAAW,IAAA,IAAQ,QAAQ,KAAA,EAAO;AAChC,IAAA,IAAI,CAAC,WAAA,CAAY,GAAA,CAAI,IAAA,CAAK,EAAE,GAAG,IAAA,CAAK,IAAA,CAAK,EAAA,EAAI,EAAE,CAAA;AAAA,EACjD;AAGA,EAAA,KAAA,MAAW,IAAA,IAAQ,QAAQ,KAAA,EAAO;AAChC,IAAA,IAAI,CAAC,OAAA,CAAQ,GAAA,CAAI,IAAA,CAAK,EAAE,GAAG,IAAA,CAAK,IAAA,CAAK,EAAA,EAAI,EAAE,CAAA;AAAA,EAC7C;AAEA,EAAA,OAAO,KAAA;AACT","file":"index.js","sourcesContent":["/**\r\n * The kit's own diagram document (spec section 10). It is versioned JSON, so\r\n * the node canvas engine can change without breaking saved diagrams.\r\n */\r\n\r\nexport const DIAGRAM_VERSION = 1;\r\n\r\n/** The node library. Every node reads kit tokens. */\r\nexport type NodeKind =\r\n  | \"start\"\r\n  | \"end\"\r\n  | \"task\"\r\n  | \"decision\"\r\n  | \"group\"\r\n  | \"note\"\r\n  | \"image\"\r\n  | \"entity\"\r\n  | \"code\"\r\n  | \"chart\"\r\n  | \"agent\"\r\n  | \"subflow\";\r\n\r\n/** Status colors match the rest of the kit: a status means the same in a badge, a chart and a node. */\r\nexport type NodeStatus = \"neutral\" | \"success\" | \"warning\" | \"danger\" | \"info\";\r\n\r\nexport type EdgeKind = \"straight\" | \"bezier\" | \"step\" | \"smooth-step\";\r\n\r\nexport interface Position {\r\n  x: number;\r\n  y: number;\r\n}\r\n\r\nexport interface DiagramNode {\r\n  id: string;\r\n  kind: NodeKind;\r\n  /** The text read aloud in the outline. Pass a translated string. */\r\n  label: string;\r\n  position: Position;\r\n  status?: NodeStatus;\r\n  /** Set on children of a group or subflow. */\r\n  parentId?: string;\r\n  width?: number;\r\n  height?: number;\r\n  /** Typed handles, for connection validation. */\r\n  ports?: Array<{ id: string; direction: \"in\" | \"out\"; type?: string }>;\r\n  /** Free-form payload for custom node bodies, such as a ChartSpec for a chart node. */\r\n  data?: Record<string, unknown>;\r\n}\r\n\r\nexport interface DiagramEdge {\r\n  id: string;\r\n  source: string;\r\n  target: string;\r\n  sourcePort?: string;\r\n  targetPort?: string;\r\n  kind?: EdgeKind;\r\n  label?: string;\r\n  /** Draw arrowheads at both ends. */\r\n  bidirectional?: boolean;\r\n  animated?: boolean;\r\n}\r\n\r\nexport interface DiagramDocument {\r\n  version: typeof DIAGRAM_VERSION;\r\n  /** Every diagram has a title that states what it shows. */\r\n  title: string;\r\n  nodes: DiagramNode[];\r\n  edges: DiagramEdge[];\r\n}\r\n\r\n/** Identity helper for authoring-time type checking. */\r\nexport function defineDiagram(document: DiagramDocument): DiagramDocument {\r\n  return document;\r\n}\r\n","import type { DiagramDocument } from \"./schema\";\r\n\r\nexport interface OutlineOptions {\r\n  /** Joins labels along a path. Pass a translated word. Defaults to \"to\". */\r\n  connector?: string;\r\n  /** Stop after this many paths so a dense graph cannot flood the outline. */\r\n  maxPaths?: number;\r\n}\r\n\r\n/**\r\n * Generates the text outline that makes a diagram readable by screen readers:\r\n * one line per path through the graph, such as \"Start to Review to Approve\".\r\n * Nodes with no connections get a line of their own, and a path that loops back\r\n * ends with the node it returns to.\r\n */\r\nexport function diagramToOutline(\r\n  diagram: DiagramDocument,\r\n  { connector = \"to\", maxPaths = 100 }: OutlineOptions = {},\r\n): string[] {\r\n  const labels = new Map(diagram.nodes.map((node) => [node.id, node.label]));\r\n  const outgoing = new Map<string, string[]>();\r\n  const hasIncoming = new Set<string>();\r\n\r\n  for (const edge of diagram.edges) {\r\n    if (!labels.has(edge.source) || !labels.has(edge.target)) continue;\r\n    outgoing.set(edge.source, [...(outgoing.get(edge.source) ?? []), edge.target]);\r\n    hasIncoming.add(edge.target);\r\n  }\r\n\r\n  const lines: string[] = [];\r\n  const visited = new Set<string>();\r\n  const label = (id: string) => labels.get(id) ?? id;\r\n  const sentence = (ids: string[]) => ids.map(label).join(` ${connector} `);\r\n\r\n  /** `trail` holds the ids on the path so far, not including `id`. */\r\n  const walk = (id: string, trail: string[]) => {\r\n    if (lines.length >= maxPaths) return;\r\n    visited.add(id);\r\n    const path = [...trail, id];\r\n    const next = outgoing.get(id) ?? [];\r\n\r\n    if (next.length === 0) {\r\n      lines.push(sentence(path));\r\n      return;\r\n    }\r\n\r\n    for (const target of next) {\r\n      if (path.includes(target)) lines.push(sentence([...path, target]));\r\n      else walk(target, path);\r\n    }\r\n  };\r\n\r\n  for (const node of diagram.nodes) {\r\n    if (!hasIncoming.has(node.id)) walk(node.id, []);\r\n  }\r\n\r\n  // Anything left over sits on a cycle with no entry point.\r\n  for (const node of diagram.nodes) {\r\n    if (!visited.has(node.id)) walk(node.id, []);\r\n  }\r\n\r\n  return lines;\r\n}\r\n"]}

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@x12i/diagrams",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0",
+  "description": "Diagram document schema for the Unified UI Kit, plus a text outline for screen readers. The node canvas (on @xyflow/react) is planned.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/x12i/unified-ui-kit.git",
+    "directory": "packages/diagrams"
+  },
+  "homepage": "https://github.com/x12i/unified-ui-kit/tree/main/packages/diagrams#readme",
+  "bugs": {
+    "url": "https://github.com/x12i/unified-ui-kit/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run --passWithNoTests"
+  }
 }