@kekonic/diagrams 1.0.0-rc.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kekonic
+
+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

@@ -0,0 +1,92 @@
+# `@kekonic/diagrams`
+
+The default KDiagram SDK: semantic text diagrams with measured ELK layout, orthogonal routing,
+crossing treatment, accessible SVG, interactive browser hosts, themes, icons, and diagram stories.
+
+## Install
+
+```bash
+pnpm add @kekonic/diagrams
+```
+
+KDiagram is ESM. Use the CLI package when you only need files and CI:
+`@kekonic/diagrams-cli`.
+
+## Render SVG
+
+```ts
+import { KDiagram } from "@kekonic/diagrams";
+
+const source = `diagram "Checkout" {
+  direction LR
+
+  group app "Application" {
+    api: gateway "API"
+    checkout: service "Checkout" { icon: shopping-cart }
+  }
+
+  db: database "Postgres"
+  bus: broker "Events"
+
+  api -> checkout "POST /orders"
+  checkout -> db "write"
+  checkout => bus "OrderPlaced"
+
+  animation "Order path" {}
+}`;
+
+const result = await KDiagram.renderToSvg(source, {
+  theme: "light",
+  snapshotTheme: true,
+});
+
+if (!result.ok || !result.svg) {
+  throw new Error(result.diagnostics.map((item) => item.message).join("\n"));
+}
+```
+
+`snapshotTheme: true` makes SVG self-contained for README files, wikis, email, and CI artifacts.
+
+## Interactive host
+
+```ts
+const controller = KDiagram.renderToElement(source, container, { theme: "dark" });
+await controller.ready();
+
+await controller.update(nextSource);
+controller.animations.play("order-path");
+controller.fit();
+controller.destroy();
+```
+
+Prefer `@kekonic/diagrams-element` for a framework-agnostic custom element or
+`@kekonic/diagrams-ui` for React.
+
+## Primary API
+
+- `KDiagram.parse(source)` — AST and diagnostics
+- `KDiagram.compile(source)` — semantic graph and policy hints
+- `await KDiagram.layout(graph, options)` — measured ELK layout and edge paths
+- `KDiagram.route(graph, layout, options)` — label placement and endpoint treatment
+- `KDiagram.format(source)` — normalized source
+- `await KDiagram.renderToSvg(source, options)` — complete static pipeline
+- `KDiagram.renderToElement(source, container, options)` — live host and controller
+- `registerTheme`, `registerIcon`, `registerCollection` — extension points
+
+API options override source `layout`, `edges`, `render`, and `presentation` blocks.
+
+## Icons
+
+Built-in glyphs require no loading. Node uses installed Iconify collections offline; browsers fetch
+only requested icon names. Register a collection or custom loader for CSP-controlled/offline browser
+apps. The complete icon vocabulary remains available without shipping whole collections to every
+browser.
+
+## Documentation
+
+- [Quickstart](https://diagrams.kekonic.com/start/quick-start/)
+- [Gallery](https://diagrams.kekonic.com/gallery/)
+- [Language](https://diagrams.kekonic.com/reference/language/)
+- [Animations](https://diagrams.kekonic.com/design/stories/)
+- [JavaScript API](https://diagrams.kekonic.com/reference/api/)
+- [Publishing guides](https://diagrams.kekonic.com/publish/)

package/dist/index.d.mts

@@ -0,0 +1,173 @@
+import { AnimationController, AnimationListItem, AnimationPlayerState, AutoWalkStep, BUILTIN_KIND_CATALOG, BUILTIN_KIND_LIST, BUILTIN_SHAPE_IDS, CompileResult, CompileResult as CompileResult$1, Diagnostic, Direction, EDGE_OPS, EdgeOperator, GraphModel, GraphModel as GraphModel$1, InteractiveRenderOptions, LayoutOptions, LayoutOptions as LayoutOptions$1, ParseResult, ParseResult as ParseResult$1, PresentationOptions, RenderController, RenderOptions, RenderOptions as RenderOptions$1, RenderResult, RenderResult as RenderResult$1, ResolvedPresentation, RoutingOptions, RoutingOptions as RoutingOptions$1, STATEMENT_KEYWORDS, ThemeMode, animationIdFromName, compile, displayLabelCase, edgeOpsPattern, enumerateAutoPaths, formatLabelText, formatSource, getKindDefaults, inferAutoAnimation, isBuiltinKind, isGeometryKind, isKnownShapeId, kindHasCapability, kindSubtitle, listGeometryKinds, listKindsByCategory, mergeOptions, mergePresentationOptions, normalizeShapeId, parse, planAutoWalk, resolvePresentation, traceDeclarationPath } from "@kekonic/diagrams-core";
+import { DiagramTopology, DiagramTopology as DiagramTopology$1, ELK_LAYOUT_ALGORITHM, ELK_ROUTER_ALGORITHM, LaidOutGroup, LaidOutNode, LayoutEdgePath, LayoutEdgePath as LayoutEdgePath$1, LayoutResult, LayoutResult as LayoutResult$1, MeasuredNode, TextMeasurer, analyzeDiagramTopology, layoutAndRouteWithElk, measureGraph } from "@kekonic/diagrams-layout";
+import { THEME_CSS, getThemeTokens, registerTheme, themeToCss } from "@kekonic/diagrams-theme";
+import { BUILTIN_ICON_ALIASES, collectIconIds, listBuiltinIconIds, listDefaultCollections, normalizeIconId, parseIconId, preloadCollections, preloadIcons, registerCollection, registerCollectionLoader, registerIcon, renderIconById, resolveIcon, setIconifyApiBaseUrl } from "@kekonic/diagrams-icons";
+import { renderSvg } from "@kekonic/diagrams-render-svg";
+import { EdgeLabelPlacement, EdgeLabelPlacement as EdgeLabelPlacement$1, RoutedEdge, RoutedEdge as RoutedEdge$1, RoutingResult, RoutingResult as RoutingResult$1, TreatedEdge, TreatedEdge as TreatedEdge$1, applyCrossingTreatment, attachPointOnPerimeter } from "@kekonic/diagrams-routing";
+import { NodeBoundsModel, NodeTypeDefinition, ShapeGeometry, buildNodeBoundsModel, getNodeTypeDefinition, listRegisteredNodeTypeIds, listRegisteredShapeIds, registerNodeType, registerShape, resolveNodeTypeGeometry, resolveShapeGeometry } from "@kekonic/diagrams-geometry";
+export type * from "@kekonic/diagrams-core";
+
+//#region src/pipeline/artifacts.d.ts
+type MeasuredGraph = {
+  graph: GraphModel$1;
+  measured: MeasuredNode[];
+  topology: DiagramTopology$1;
+  diagnostics: Diagnostic[];
+};
+type LaidOutGraph = MeasuredGraph & {
+  layout: LayoutResult$1;
+};
+type RoutedGraph = LaidOutGraph & {
+  routing: RoutingResult$1;
+};
+type FinalizedGraph = RoutedGraph & {
+  labels: EdgeLabelPlacement$1[];
+  treatedEdges: TreatedEdge$1[];
+};
+//#endregion
+//#region src/pipeline/render.d.ts
+type PipelineRenderResult = Omit<RenderResult$1, "layout" | "routing"> & {
+  layout?: LayoutResult$1;
+  routing?: RoutingResult$1; /** KDiagram-placed edge label boxes (post-ELK). */
+  labels?: EdgeLabelPlacement$1[];
+};
+declare function parseSource(source: string): ParseResult$1;
+declare function compileSource(source: string, diagramIndex?: number): CompileResult$1;
+declare function measureFromGraph(graph: GraphModel$1, direction?: Direction): MeasuredGraph;
+declare function layoutFromGraph(graph: GraphModel$1, layoutOpts?: LayoutOptions$1): Promise<LayoutResult$1>;
+declare function layoutMeasuredGraph(measuredGraph: MeasuredGraph, layoutOpts?: LayoutOptions$1): Promise<LaidOutGraph>;
+type RouteFromLayoutResult = {
+  labels: EdgeLabelPlacement$1[];
+  treatedEdges: TreatedEdge$1[];
+  routing: RoutingResult$1;
+};
+/**
+ * Finalize labels + endpoint trim from ELK edge paths on `layout`.
+ * Does not re-run layout — ELK already owned routing in `layoutFromGraph` / `layoutMeasuredGraph`.
+ */
+declare function routeFromLayout(graph: GraphModel$1, layout: LayoutResult$1, routingOpts?: RoutingOptions$1): RouteFromLayoutResult;
+declare function routeLaidOutGraph(laidOut: LaidOutGraph, routingOpts?: RoutingOptions$1): RoutedGraph;
+declare function finalizeRoutedGraph(routed: RoutedGraph, routingOpts?: RoutingOptions$1): FinalizedGraph;
+declare function renderPipeline(source: string, options?: RenderOptions$1 & {
+  layout?: LayoutOptions$1;
+  edges?: RoutingOptions$1;
+}): Promise<PipelineRenderResult>;
+//#endregion
+//#region src/pipeline/finalize-edges.d.ts
+type FinalizeElkEdgesInput = {
+  graph: GraphModel$1;
+  layout: LayoutResult$1;
+  edgePaths: LayoutEdgePath$1[];
+  routingOpts: RoutingOptions$1;
+  measurer?: TextMeasurer;
+};
+type FinalizeElkEdgesResult = {
+  labels: EdgeLabelPlacement$1[];
+  treatedEdges: TreatedEdge$1[];
+  routingEdges: RoutedEdge$1[];
+};
+/** ELK labels + ERD column snap + marker inset (silhouette attach already ran in layout). */
+declare function finalizeElkEdges(input: FinalizeElkEdgesInput): FinalizeElkEdgesResult;
+//#endregion
+//#region src/capabilities.d.ts
+declare const KDIAGRAM_CAPABILITIES_VERSION: 1;
+type KDiagramCapabilities = {
+  version: 1;
+  registryScope: "built-in";
+  language: {
+    version: 1;
+    diagramFamilies: readonly ["flow", "state", "sequence"];
+    statementKeywords: string[];
+    edgeOperators: string[];
+  };
+  nodes: Array<{
+    id: string;
+    category: string;
+    shape: string;
+    subtitle: string;
+    capabilities: string[];
+    defaultIcon?: string;
+  }>;
+  shapes: string[];
+  icons: {
+    builtin: string[];
+    collections: string[];
+  };
+  layout: {
+    algorithm: string;
+    router: string;
+    directions: readonly ["LR", "RL", "TD", "BT"];
+    densities: readonly ["compact", "normal", "spacious"];
+    groupLayouts: readonly ["compound", "swimlane"];
+    regionArrangements: readonly ["stack", "row", "grid"];
+  };
+  presentation: {
+    themes: readonly ["dark", "light"];
+    exportFormats: readonly ["svg"];
+    themeModes: readonly ["snapshot", "live"];
+  };
+  qualityChecks: string[];
+};
+/** Deterministic, JSON-safe description of the active built-in KDiagram surface. */
+declare function getCapabilities(): KDiagramCapabilities;
+//#endregion
+//#region src/quality.d.ts
+declare const DEFAULT_TARGET_ASPECT_RATIO: number;
+declare const QUALITY_CHECKS: readonly ["extreme-aspect-ratio", "canvas-spanning-edges", "excessive-edge-crossings", "reverse-layout-flow", "edge-label-pressure"];
+type QualityCheck = (typeof QUALITY_CHECKS)[number];
+type DiagramQualityMetrics = {
+  width: number;
+  height: number;
+  aspectRatio: number;
+  targetAspectRatio: number;
+  targetAspectRatioDifference: number;
+  edgeCrossings: number;
+  canvasSpanningEdges: number;
+  reverseFlowEdges: number;
+  labeledEdges: number;
+};
+type DiagramQualityAnalysis = {
+  metrics: DiagramQualityMetrics;
+  diagnostics: Diagnostic[];
+};
+/** Measure rendered geometry and return evidence plus actionable, human-readable diagnostics. */
+declare function analyzeDiagramQuality(graph: GraphModel$1, layout: LayoutResult$1, routedEdges: RoutingResult$1["edges"]): DiagramQualityAnalysis;
+//#endregion
+//#region src/animation/player.d.ts
+/**
+ * Interactive SVG animation player bound to a mounted KDiagram diagram.
+ */
+declare class AnimationPlayer implements AnimationController {
+  #private;
+  list(): AnimationListItem[];
+  getState(): AnimationPlayerState;
+  subscribe(listener: (state: AnimationPlayerState) => void): () => void;
+  /** Rebind after SVG replace. Preserves current animation id and time when possible. */
+  rebind(svg: SVGSVGElement | null, graph: GraphModel$1 | null): void;
+  play(id?: string): void;
+  pause(): void;
+  stop(): void;
+  seek(ms: number): void;
+  step(delta: -1 | 1): void;
+  setLoop(on: boolean): void;
+  setSpeed(rate: number): void;
+  destroy(): void;
+}
+//#endregion
+//#region src/index.d.ts
+declare const KDiagram: {
+  parse(source: string): ParseResult;
+  compile(source: string, _options?: Record<string, never>): CompileResult;
+  layout(graph: GraphModel, options?: LayoutOptions): Promise<LayoutResult$1>;
+  route(graph: GraphModel, layout: LayoutResult$1, options?: RoutingOptions): RouteFromLayoutResult;
+  format(source: string): string;
+  ensureFonts(): Promise<void>;
+  renderToSvg(source: string, options?: RenderOptions & {
+    layout?: LayoutOptions;
+    edges?: RoutingOptions;
+  }): Promise<RenderResult>;
+  renderToElement(source: string, container: HTMLElement, options?: InteractiveRenderOptions): RenderController;
+};
+//#endregion
+export { AnimationPlayer, type AutoWalkStep, BUILTIN_ICON_ALIASES, BUILTIN_KIND_CATALOG, BUILTIN_KIND_LIST, BUILTIN_SHAPE_IDS, type CompileResult, DEFAULT_TARGET_ASPECT_RATIO, type DiagramQualityAnalysis, type DiagramQualityMetrics, type DiagramTopology, EDGE_OPS, ELK_LAYOUT_ALGORITHM, ELK_ROUTER_ALGORITHM, type EdgeLabelPlacement, type EdgeOperator, type FinalizeElkEdgesInput, type FinalizeElkEdgesResult, type FinalizedGraph, type GraphModel, type InteractiveRenderOptions, KDIAGRAM_CAPABILITIES_VERSION, KDiagram, type KDiagramCapabilities, type LaidOutGraph, type LaidOutGroup, type LaidOutNode, type LayoutEdgePath, type LayoutOptions, type LayoutResult, type MeasuredGraph, type NodeBoundsModel, type NodeTypeDefinition, type ParseResult, type PresentationOptions, QUALITY_CHECKS, type QualityCheck, type RenderController, type RenderOptions, type RenderResult, type ResolvedPresentation, type RouteFromLayoutResult, type RoutedEdge, type RoutedGraph, type RoutingOptions, type RoutingResult, STATEMENT_KEYWORDS, type ShapeGeometry, THEME_CSS, type ThemeMode, type TreatedEdge, analyzeDiagramQuality, analyzeDiagramTopology, animationIdFromName, applyCrossingTreatment, attachPointOnPerimeter, buildNodeBoundsModel, collectIconIds, compile, compileSource, displayLabelCase, edgeOpsPattern, enumerateAutoPaths, finalizeElkEdges, finalizeRoutedGraph, formatLabelText, formatSource, getCapabilities, getKindDefaults, getNodeTypeDefinition, getThemeTokens, inferAutoAnimation, isBuiltinKind, isGeometryKind, isKnownShapeId, kindHasCapability, kindSubtitle, layoutAndRouteWithElk, layoutFromGraph, layoutMeasuredGraph, listBuiltinIconIds, listDefaultCollections, listGeometryKinds, listKindsByCategory, listRegisteredNodeTypeIds, listRegisteredShapeIds, measureFromGraph, measureGraph, mergeOptions, mergePresentationOptions, normalizeIconId, normalizeShapeId, parse, parseIconId, parseSource, planAutoWalk, preloadCollections, preloadIcons, registerCollection, registerCollectionLoader, registerIcon, registerNodeType, registerShape, registerTheme, renderIconById, renderPipeline, renderSvg, resolveIcon, resolveNodeTypeGeometry, resolvePresentation, resolveShapeGeometry, routeFromLayout, routeLaidOutGraph, setIconifyApiBaseUrl, themeToCss, traceDeclarationPath };
+//# sourceMappingURL=index.d.mts.map