@kekonic/diagrams-geometry 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,23 @@
+# @kekonic/diagrams-geometry
+
+Shared shape geometry for KDiagram: paths, safe content regions, ports, perimeter intersection, and layout footprints.
+
+Renderers and layout/routing consume this package so semantic node kinds do not each invent their own shape math. The DSL exposes the same shape ids as first-class kinds (`diamond`, `cylinder`, `cloud`, …).
+
+## ShapeGeometry
+
+```ts
+import { resolveShapeGeometry, resolveNodeTypeGeometry } from "@kekonic/diagrams-geometry";
+
+const diamond = resolveShapeGeometry("diamond");
+const fromKind = resolveNodeTypeGeometry("gateway"); // → hexagon
+```
+
+Each geometry implements path generation, content/visual/footprint bounds, port placement, ray intersection, and hit testing.
+
+Non-rect shapes project side/fan ports onto the silhouette (`projectSidePortOntoOutline`) so ELK `FIXED_POS` pins and `attachPointOnPerimeter` / `snapEdgeEndpointsToGeometry` agree — diamonds, hexes, ellipses, clouds, cylinders, pills, people, etc.
+
+## Related
+
+- Kind catalog: `@kekonic/diagrams-core` (`BUILTIN_KIND_CATALOG`, `listGeometryKinds`)
+- Pipeline boundaries: [`docs/architecture/pipeline.md`](../../docs/architecture/pipeline.md)

package/dist/index.d.mts

@@ -0,0 +1,393 @@
+import { NodeCapability, Point, Point as Point$1, Rect, Rect as Rect$1, Vec2, Vec2 as Vec2$1 } from "@kekonic/diagrams-core";
+
+//#region src/types.d.ts
+/** Per-side insets in logical diagram units. */
+type Insets = {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+};
+type Size = {
+  width: number;
+  height: number;
+};
+/** Cardinal / compass port sides. */
+type PortSide = "north" | "east" | "south" | "west";
+/** Optional corner ports. */
+type PortCorner = "northwest" | "northeast" | "southeast" | "southwest";
+type PortRef = {
+  kind: "side";
+  side: PortSide;
+  index?: number;
+  count?: number;
+} | {
+  kind: "corner";
+  corner: PortCorner;
+} | {
+  kind: "center";
+} | {
+  kind: "radial";
+  angleDeg: number;
+} | {
+  kind: "named";
+  name: string;
+};
+type PortStrategy = "bbox-mid" | "perimeter" | "distributed-sides" | "vertices" | "radial" | "semantic";
+/** Stroke / fill hints that affect bounds and content insets. */
+type ShapeStyle = {
+  strokeWidth?: number;
+  cornerRadius?: number; /** Shadow blur radius (visual bounds only). */
+  shadowBlur?: number;
+  shadowOffsetX?: number;
+  shadowOffsetY?: number;
+};
+type LayoutDensity = "compact" | "standard" | "presentation";
+type LayoutContext = {
+  density?: LayoutDensity; /** Extra clear space beyond geometry defaults. */
+  clearSpace?: Partial<Insets>; /** Edge-launch corridor beyond the perimeter (layout footprint). */
+  edgeLaunch?: number; /** External label boxes already measured (world coords relative to node origin). */
+  externalLabels?: Rect[]; /** Badges / markers relative to node origin. */
+  badges?: Rect[];
+};
+/**
+ * Full anatomy of a placed node in logical units.
+ * Coordinates are relative to the geometry bounds origin unless noted.
+ */
+type NodeBoundsModel = {
+  /** Visible outline of the primary shape (no shadows/labels/ports). */geometry: Rect; /** Interior region for text, icons, compartments. */
+  content: Rect; /** Complete visible extent including stroke, shadow, labels, badges, ports. */
+  visual: Rect; /** Pointer hit region (at least visual; may expand for small targets). */
+  interaction: Rect; /** Area reserved by layout (visual + clear space + launch corridors). */
+  footprint: Rect; /** Non-rendered exclusion zone around the node. */
+  clearSpace: Insets;
+};
+/** Path data returned by geometries — SVG `d` plus optional polygons. */
+type PathData = {
+  /** Primary closed outline as SVG path `d`. */d: string; /** Optional secondary strokes (cylinder rim, subprocess markers, …). */
+  decorations?: Array<{
+    d: string;
+    role: string;
+  }>; /** Polygon vertices when the shape is polygonal (for intersection). */
+  polygon?: Point[];
+};
+type ContentPolicy = {
+  /** Preferred content alignment. */align?: "center" | "start" | "end"; /** Max preferred label lines before expand/truncate. */
+  maxLabelLines?: number; /** Whether long labels should prefer external placement. */
+  preferExternalLabel?: boolean; /** Icon placement when present. */
+  iconPlacement?: "leading" | "above" | "centered" | "none";
+};
+type ClearSpacePreset = LayoutDensity;
+declare const CLEAR_SPACE_PRESETS: Record<ClearSpacePreset, number>;
+declare const EDGE_LAUNCH_PRESETS: Record<ClearSpacePreset, number>;
+/** Minimum interactive target in logical units (ports / markers). */
+declare const MIN_INTERACTION_TARGET = 22;
+declare const DEFAULT_STROKE_WIDTH = 1.6;
+declare function uniformInsets(n: number): Insets;
+declare function insets(partial: Partial<Insets>, fallback?: number): Insets;
+declare function insetRect(r: Rect, pad: Insets | number): Rect;
+declare function expandRectInsets(r: Rect, pad: Insets | number): Rect;
+declare function unionRects(rects: Rect[]): Rect;
+declare function rectFromSize(size: Size, origin?: Point): Rect;
+declare function normalizeVector(v: Vec2): Vec2;
+declare function sideNormal(side: PortSide): Vec2;
+declare function sideMidpoint(bounds: Rect, side: PortSide): Point;
+//#endregion
+//#region src/shape-geometry.d.ts
+/**
+ * Renderer-neutral shape geometry contract.
+ *
+ * Every foundational shape implements this so measure, layout, routing, and
+ * renderers share one source of truth for paths, content, ports, and hits.
+ */
+interface ShapeGeometry {
+  readonly id: string;
+  /** SVG path / polygon for the primary outline. */
+  getPath(bounds: Rect$1, style?: ShapeStyle): PathData;
+  /** Safe interior rectangle for text/icons/compartments. */
+  getContentBounds(bounds: Rect$1, style?: ShapeStyle): Rect$1;
+  /** Visible extent including stroke (and optional shadow). */
+  getVisualBounds(bounds: Rect$1, style?: ShapeStyle): Rect$1;
+  /** Layout reservation including clear space and edge-launch corridor. */
+  getLayoutFootprint(bounds: Rect$1, context?: LayoutContext, style?: ShapeStyle): Rect$1;
+  /** World position of a port on/around the shape. */
+  getPortPosition(port: PortRef, bounds: Rect$1, style?: ShapeStyle): Point$1;
+  /** Outward unit normal at a port (edge launch direction). */
+  getPortNormal(port: PortRef, bounds: Rect$1, style?: ShapeStyle): Vec2$1;
+  /** Intersection of a ray with the visible perimeter. */
+  intersectRay(bounds: Rect$1, origin: Point$1, direction: Vec2$1, style?: ShapeStyle): Point$1 | null;
+  /** Point-in-shape test for hit testing (geometry fill, not interaction pad). */
+  containsPoint(bounds: Rect$1, point: Point$1, style?: ShapeStyle): boolean;
+  /** Optional preferred default / min sizes. */
+  defaultSize?: Size;
+  minSize?: Size;
+  defaultPadding?: Insets;
+  contentPolicy?: ContentPolicy;
+  /** Extra clear-space units beyond density preset (pointed corners, etc.). */
+  clearSpaceBoost?: number;
+}
+type ShapeGeometryBaseOptions = {
+  id: string;
+  defaultSize?: Size;
+  minSize?: Size;
+  defaultPadding?: Insets;
+  contentPolicy?: ContentPolicy; /** Extra clear space beyond density preset (e.g. pointed corners). */
+  clearSpaceBoost?: number;
+};
+/** Assemble the full node bounds model from a geometry + style + context. */
+declare function buildNodeBoundsModel(geometry: ShapeGeometry, bounds: Rect$1, style?: ShapeStyle, context?: LayoutContext): NodeBoundsModel;
+/** Shared helpers for concrete geometries. */
+declare function defaultVisualBounds(bounds: Rect$1, style?: ShapeStyle): Rect$1;
+declare function defaultLayoutFootprint(geometry: ShapeGeometry, bounds: Rect$1, context?: LayoutContext, style?: ShapeStyle): Rect$1;
+declare function defaultSidePortPosition(port: PortRef, bounds: Rect$1): Point$1;
+/**
+ * Place a side port on a non-rect silhouette.
+ * Starts from the AABB mid/distributed point, then casts from the shape center
+ * onto the outline so FIXED_POS pins and perimeter snap share one attach truth.
+ */
+declare function projectSidePortOntoOutline(port: PortRef, bounds: Rect$1, hitFromCenter: (direction: Vec2$1) => Point$1 | null): Point$1;
+/** Convenience: project onto a polygon silhouette via center→AABB ray. */
+declare function projectSidePortOntoPolygon(port: PortRef, bounds: Rect$1, polygon: Point$1[], intersect: (polygon: Point$1[], origin: Point$1, direction: Vec2$1) => Point$1 | null): Point$1;
+declare function distributedSidePort(bounds: Rect$1, side: PortSide, index: number, count: number, sideInset?: number): Point$1;
+declare function defaultPortNormal(port: PortRef, _bounds: Rect$1): Vec2$1;
+//#endregion
+//#region src/math.d.ts
+/** Ray from origin along direction; returns closest intersection with t >= 0. */
+declare function intersectRayPolygon(polygon: Point[], origin: Point, direction: Vec2): Point | null;
+/** Ellipse / circle ray intersection (axis-aligned). */
+declare function intersectRayEllipse(bounds: Rect, origin: Point, direction: Vec2): Point | null;
+/** Axis-aligned rect ray intersection. */
+declare function intersectRayRect(bounds: Rect, origin: Point, direction: Vec2): Point | null;
+declare function rectPolygon(bounds: Rect): Point[];
+declare function pointInPolygon(point: Point, polygon: Point[]): boolean;
+declare function pointInEllipse(point: Point, bounds: Rect): boolean;
+declare function polygonToPath(points: Point[], close?: boolean): string;
+/**
+ * Closed Catmull–Rom spline as cubic Béziers.
+ * Yields smooth SVG path data (`C` commands) from a polygon of control points.
+ */
+declare function closedCatmullRomToPath(points: Point[]): string;
+/** Inscribed content rect as a fraction of geometry bounds, centered. */
+declare function centeredContentRect(bounds: Rect, widthRatio: number, heightRatio: number): Rect;
+/** Stroke expands visual bounds by half stroke on each side. */
+declare function strokeOutset(strokeWidth: number): number;
+//#endregion
+//#region src/registry.d.ts
+type RenderDecoration = {
+  id: string; /** Decoration roles from PathData (rim, fold, markers, …). */
+  role: string;
+};
+type ShapeDefinition = {
+  id: string;
+  geometry: ShapeGeometry;
+  defaultSize: Size;
+  minSize: Size;
+  defaultPadding: Insets;
+  supportedPortStrategies: PortStrategy[];
+  contentPolicy: ContentPolicy;
+  renderDecorations?: RenderDecoration[];
+};
+type NodeTypeDefinition = {
+  id: string;
+  shapeId: string;
+  defaultIcon?: string;
+  defaultStyle?: Record<string, string>;
+  contentTemplate?: string;
+  defaultPorts?: Array<{
+    side: "north" | "east" | "south" | "west";
+  }>;
+  capabilities?: NodeCapability[];
+  subtitle?: string;
+  category?: string;
+};
+/** Register a custom shape without changing the renderer core. */
+declare function registerShape(definition: ShapeDefinition): void;
+declare function unregisterShape(id: string): void;
+declare function getShapeDefinition(id: string): ShapeDefinition | undefined;
+declare function getShapeGeometry(id: string): ShapeGeometry | undefined;
+/**
+ * Resolve a shape id with fallback.
+ * Unknown ids fall back to rounded rectangle (same as historic SVG default).
+ */
+declare function resolveShapeGeometry(id: string | undefined | null): ShapeGeometry;
+declare function listRegisteredShapeIds(): string[];
+/** Map authored shape synonyms onto registry ids (delegates to core). */
+declare function normalizeShapeId(shape: string | undefined | null): string;
+/** Register or override a semantic node type → shape mapping. */
+declare function registerNodeType(definition: NodeTypeDefinition): void;
+declare function unregisterNodeType(id: string): void;
+declare function getNodeTypeDefinition(id: string): NodeTypeDefinition | undefined;
+/**
+ * Resolve the geometry for a semantic kind (with optional shape override).
+ * Kind defaults come from the DSL catalog; shape overrides win.
+ */
+declare function resolveNodeTypeGeometry(kind: string, shapeOverride?: string | null): ShapeGeometry;
+declare function listRegisteredNodeTypeIds(): string[];
+//#endregion
+//#region src/measure.d.ts
+type ContentSize = {
+  width: number;
+  height: number;
+};
+/**
+ * Given a measured content size, find geometry bounds large enough that
+ * getContentBounds() can contain it. Uses iterative refinement because
+ * content insets are not always linear (cylinder caps, hex chamfers, …).
+ */
+declare function geometrySizeForContent(geometry: ShapeGeometry, content: ContentSize, seed?: ContentSize): ContentSize;
+/** Relative content box (origin at geometry top-left) for MeasuredNode.contentBox. */
+declare function relativeContentBox(geometry: ShapeGeometry, width: number, height: number): Rect;
+//#endregion
+//#region src/attach.d.ts
+type PerimeterAttachInput = {
+  shapeId: string | undefined;
+  bounds: Rect; /** Ray origin (typically the adjacent bend / corridor point, outside the fill). */
+  origin: Point; /** Direction toward this node (will be normalized). */
+  direction: Vec2;
+  style?: ShapeStyle;
+};
+/** Intersection of a ray with the shape perimeter; falls back via center ray, then center. */
+declare function attachPointOnPerimeter(input: PerimeterAttachInput): Point;
+//#endregion
+//#region src/shapes/rectangle.d.ts
+declare const rectangleGeometry: ShapeGeometry;
+declare const roundedRectangleGeometry: ShapeGeometry;
+declare const pillGeometry: ShapeGeometry;
+//#endregion
+//#region src/shapes/diamond.d.ts
+/** Diamond tips sit on bbox mid-sides so LR/TD ports land on vertices. */
+declare function diamondPolygon(bounds: Rect): Point[];
+declare function diamondPointsString(bounds: Rect): string;
+declare const diamondGeometry: ShapeGeometry;
+//#endregion
+//#region src/shapes/hexagon.d.ts
+/** Flat-top hexagon inset: height-led so wide short nodes keep real chamfers. */
+declare function hexagonInset(width: number, height: number): number;
+declare function hexagonPolygon(bounds: Rect): Point[];
+declare function hexagonPointsString(bounds: Rect): string;
+declare const hexagonGeometry: ShapeGeometry;
+//#endregion
+//#region src/shapes/cylinder.d.ts
+declare function cylinderRadii(width: number, height: number): {
+  rx: number;
+  ry: number;
+};
+/**
+ * Cylinder as one closed silhouette + front rim arc.
+ * Prefer a single coordinated path set for intersection/hit testing.
+ */
+declare function cylinderPaths(bounds: Rect): {
+  body: string;
+  rim: string;
+};
+/**
+ * Sampled silhouette matching `cylinderPaths` body (top arc → right side → bottom arc → left).
+ * Used for perimeter attachment so tall cylinders hit vertical walls, not a bounding ellipse.
+ */
+declare function cylinderSilhouettePolygon(bounds: Rect, samplesPerCap?: number): Point[];
+declare const cylinderGeometry: ShapeGeometry;
+//#endregion
+//#region src/shapes/queue.d.ts
+/**
+ * Horizontal pipe (sideways cylinder) — the ubiquitous message-queue silhouette.
+ * End-cap radius is height-led so short wide queues keep readable openings.
+ */
+declare function queueRadii(width: number, height: number): {
+  rx: number;
+  ry: number;
+};
+/**
+ * Pipe body + left-end rim (front opening), matching vertical cylinder conventions.
+ */
+declare function queuePaths(bounds: Rect): {
+  body: string;
+  rim: string;
+};
+/**
+ * Sampled silhouette for ports / ray hits (left ellipse → top → right ellipse → bottom).
+ */
+declare function queueSilhouettePolygon(bounds: Rect, samplesPerCap?: number): Point[];
+declare const queueGeometry: ShapeGeometry;
+//#endregion
+//#region src/shapes/stream.d.ts
+/** Corner radius for the stacked-log shell. */
+declare function streamCornerRadius(height: number, width: number): number;
+/**
+ * Partition y positions (absolute) for the stacked-log / Kafka-style silhouette.
+ * Two interior rules divide the card into three record bands.
+ */
+declare function streamPartitionYs(bounds: Rect): [number, number];
+declare function streamShellPath(bounds: Rect): string;
+/**
+ * Short left-rail ticks — suggest stacked partitions without slicing through label/icon.
+ */
+declare function streamPartitionPaths(bounds: Rect): string[];
+/**
+ * Stacked-log card — ubiquitous for streams, topics, and append-only partitions.
+ * Outer shell holds the label; interior rules suggest record bands.
+ */
+declare const streamGeometry: ShapeGeometry;
+//#endregion
+//#region src/shapes/ellipse.d.ts
+declare const ellipseGeometry: ShapeGeometry;
+declare const circleGeometry: ShapeGeometry;
+//#endregion
+//#region src/shapes/polygons.d.ts
+declare const parallelogramGeometry: ShapeGeometry;
+/** Manual operation: wider top. */
+declare const trapezoidGeometry: ShapeGeometry;
+declare const triangleGeometry: ShapeGeometry;
+//#endregion
+//#region src/shapes/document.d.ts
+declare const documentGeometry: ShapeGeometry;
+declare const foldedDocumentGeometry: ShapeGeometry;
+//#endregion
+//#region src/shapes/cloud.d.ts
+declare const cloudGeometry: ShapeGeometry;
+//#endregion
+//#region src/shapes/person.d.ts
+/** Port anchors: head (N), torso sides (E/W), feet (S). */
+declare function personPortAnchors(bounds: Rect): Record<"north" | "east" | "south" | "west", Point>;
+/** Closed silhouette for rays / multi-port projection (head arc + rounded torso). */
+declare function personSilhouettePolygon(bounds: Rect, headSamples?: number): Point[];
+/**
+ * Person / actor — C4-style head + rounded torso.
+ * The torso is the content box: it grows with label/subtitle width.
+ */
+declare function personPaths(bounds: Rect): {
+  head: string;
+  body: string;
+};
+/** Extra height above the torso content for head + neck (used by measure). */
+declare function personHeadStackHeight(bodyWidth: number): number;
+declare const personGeometry: ShapeGeometry;
+declare const compartmentedRectangleGeometry: ShapeGeometry;
+declare const boundaryGeometry: ShapeGeometry;
+//#endregion
+//#region src/shapes/index.d.ts
+/** All built-in geometries keyed by id. */
+declare const BUILTIN_GEOMETRIES: {
+  readonly rectangle: ShapeGeometry;
+  readonly rounded: ShapeGeometry;
+  readonly pill: ShapeGeometry;
+  readonly diamond: ShapeGeometry;
+  readonly hexagon: ShapeGeometry;
+  readonly queue: ShapeGeometry;
+  readonly stream: ShapeGeometry;
+  readonly cylinder: ShapeGeometry;
+  readonly circle: ShapeGeometry;
+  readonly ellipse: ShapeGeometry;
+  readonly parallelogram: ShapeGeometry;
+  readonly trapezoid: ShapeGeometry;
+  readonly triangle: ShapeGeometry;
+  readonly document: ShapeGeometry;
+  readonly "folded-document": ShapeGeometry;
+  readonly cloud: ShapeGeometry;
+  readonly person: ShapeGeometry;
+  readonly table: ShapeGeometry;
+  readonly boundary: ShapeGeometry;
+};
+type BuiltinGeometryId = keyof typeof BUILTIN_GEOMETRIES;
+//#endregion
+export { BUILTIN_GEOMETRIES, BuiltinGeometryId, CLEAR_SPACE_PRESETS, type ClearSpacePreset, type ContentPolicy, type ContentSize, DEFAULT_STROKE_WIDTH, EDGE_LAUNCH_PRESETS, type Insets, type LayoutContext, type LayoutDensity, MIN_INTERACTION_TARGET, type NodeBoundsModel, type NodeTypeDefinition, type PathData, type PerimeterAttachInput, type Point, type PortCorner, type PortRef, type PortSide, type PortStrategy, type Rect, type RenderDecoration, type ShapeDefinition, type ShapeGeometry, type ShapeGeometryBaseOptions, type ShapeStyle, type Size, type Vec2, attachPointOnPerimeter, boundaryGeometry, buildNodeBoundsModel, centeredContentRect, circleGeometry, closedCatmullRomToPath, cloudGeometry, compartmentedRectangleGeometry, cylinderGeometry, cylinderPaths, cylinderRadii, cylinderSilhouettePolygon, defaultLayoutFootprint, defaultPortNormal, defaultSidePortPosition, defaultVisualBounds, diamondGeometry, diamondPointsString, diamondPolygon, distributedSidePort, documentGeometry, ellipseGeometry, expandRectInsets, foldedDocumentGeometry, geometrySizeForContent, getNodeTypeDefinition, getShapeDefinition, getShapeGeometry, hexagonGeometry, hexagonInset, hexagonPointsString, hexagonPolygon, insetRect, insets, intersectRayEllipse, intersectRayPolygon, intersectRayRect, listRegisteredNodeTypeIds, listRegisteredShapeIds, normalizeShapeId, normalizeVector, parallelogramGeometry, personGeometry, personHeadStackHeight, personPaths, personPortAnchors, personSilhouettePolygon, pillGeometry, pointInEllipse, pointInPolygon, polygonToPath, projectSidePortOntoOutline, projectSidePortOntoPolygon, queueGeometry, queuePaths, queueRadii, queueSilhouettePolygon, rectFromSize, rectPolygon, rectangleGeometry, registerNodeType, registerShape, relativeContentBox, resolveNodeTypeGeometry, resolveShapeGeometry, roundedRectangleGeometry, sideMidpoint, sideNormal, streamCornerRadius, streamGeometry, streamPartitionPaths, streamPartitionYs, streamShellPath, strokeOutset, trapezoidGeometry, triangleGeometry, uniformInsets, unionRects, unregisterNodeType, unregisterShape };
+//# sourceMappingURL=index.d.mts.map