@statelyai/layout 0.1.2 → 0.2.0

package/NOTICE.md

@@ -16,3 +16,46 @@ https://github.com/eclipse/elk-models. Those examples are available under the
 Eclipse Public License 2.0. Their ELKT graph source and upstream paths are
 preserved in the generated example catalog; the upstream repository retains
 the original per-file notices.
+
+## Kiwi constraint solver
+
+Runtime bundles include `@lume/kiwi` 0.4.4 (https://github.com/lume/kiwi).
+
+```text
+=========================
+ The Kiwi licensing terms
+=========================
+Kiwi is licensed under the terms of the Modified BSD License (also known as
+New or Revised BSD), as follows:
+
+Copyright (c) 2013, Nucleic Development Team
+Copyright (c) 2021, Joseph Orbegoso Pea
+Copyright (c) 2021, LUME
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+Redistributions of source code must retain the above copyright notice, this
+list of conditions and the following disclaimer.
+
+Redistributions in binary form must reproduce the above copyright notice, this
+list of conditions and the following disclaimer in the documentation and/or
+other materials provided with the distribution.
+
+Neither the name of the Nucleic Development Team nor the names of its
+contributors may be used to endorse or promote products derived from this
+software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+```

package/README.md

@@ -16,8 +16,9 @@ layered inventory with one simplified typed name per ELK option. Flat and
 compound graphs, cross-hierarchy edges, ports, labels, self-loops, wrapping,
 four directions, constraints, and replaceable phases are differential-tested
 against elkjs, including a curated complex state-machine corpus in both primary
-layout orientations. Partial, incremental, and route-only layout remain
-explicit unimplemented capabilities.
+layout orientations. Native layered layout also supports partial selection,
+route-only execution, and geometric constraints. Incremental layout remains
+explicitly unsupported.
 
 ## Install
 
@@ -54,6 +55,48 @@ result.diagnostics;
 result.metrics;
 ```
 
+## Layout while authoring
+
+<!-- partial scopes and geometry constraints from src/types.ts and src/constraints.ts -->
+
+Select nodes and edges independently. Edge selection never moves endpoints:
+
+```ts
+import { c, getLayout } from "@statelyai/layout";
+
+const result = await getLayout({
+  graph,
+  scope: {
+    mode: "partial",
+    edgeIds: ["ab", "bc"],
+    edgeGeometry: "labels",
+    routing: "selected",
+  },
+  constraints: [
+    c.align({
+      id: "label-centers",
+      entities: [
+        { edgeId: "ab", part: "label" },
+        { edgeId: "bc", part: "label" },
+      ],
+      axis: "x",
+      anchor: "center",
+    }),
+  ],
+});
+```
+
+`nodeIds` permits position changes; `edgeIds` permits routes, label positions,
+or both. `routing: "affected"` (default) also repairs edges affected by moved
+nodes, within `edgeGeometry` permissions. Unselected nodes, dimensions, ports,
+and topology remain fixed. Results include field-specific graph patches and
+repair/conflict diagnostics. Constraints support alignment, distribution, pins,
+linear equalities/inequalities, and route waypoints.
+
+See [authoring layout](docs/authoring-layout.md) for baseline requirements,
+selection semantics, routing limits, and examples. Existing ELK compatibility
+behavior is unchanged.
+
 ## elkjs compatibility
 
 <!-- elkjs-compatible entry point and layered mapping exports from package.json#exports and src/layered/index.ts -->
@@ -67,9 +110,29 @@ const elk = new ELK();
 const legacyResult = await elk.layout(elkJsonGraph);
 ```
 
+Migration-compatible package aliases are also available for
+`lib/main.js`, `lib/elk-api.js`, `lib/elk.bundled.js`, `lib/elk-worker.js`,
+and `lib/elk-worker.min.js`. The worker entries implement elkjs's message
+protocol in-process, including custom `workerFactory` construction and
+termination. Both ESM imports and the original CommonJS `require()` style are
+supported. Worker calls merge constructor defaults with per-layout overrides;
+terminal worker errors reject pending and later requests.
+
 The adapter accepts ELK JSON and option aliases, translates to
 `@statelyai/graph`, runs native algorithms, and translates the result back.
-Native algorithms never consume ELK JSON directly.
+Native algorithms never consume ELK JSON directly. `getLayout` and the
+compatibility adapter dispatch through one typed internal engine; direct native
+functions expose those same algorithm implementations. ELK-specific defaults
+and quirks remain local to the pinned compatibility adapter.
+
+Compatibility policies currently preserve exact elkjs 0.11.1 Random geometry
+and Box SIMPLE geometry, including provider bounds and whether edge sections
+are routed or left authored. Rectangle Packing has an exact default baseline;
+its full Java packing strategy remains in progress.
+
+The compatibility entry's named graph, edge, option, and result types are
+mutually assignable with the declarations shipped by `elkjs@0.11.1`. Its
+default class also accepts the library's broader internal graph inputs.
 
 <!-- fixed-port placement and inline center-label guarantees from src/layered/index.ts and src/layered/strategies.ts -->
 
@@ -153,13 +216,28 @@ pnpm install
 pnpm verify
 pnpm bench
 pnpm demo
+pnpm storybook
 pnpm changeset
 pnpm release
 ```
 
 `pnpm verify` checks Oxfmt, Oxlint, source and repository TypeScript projects,
 generated layered-option and demo-corpus freshness, tests,
-declarations/runtime builds, the demo bundle, and the packed package surface.
+declarations/runtime builds, demo and Storybook bundles, and the packed package surface.
+
+<!-- authoring stories derived from stories/*.stories.tsx and package.json#scripts -->
+
+`pnpm storybook` opens the authoring workbench at `http://127.0.0.1:6018`.
+The **Layout / Partial selection** story starts with a fully laid-out graph.
+Click nodes (or select the review branch), choose a direction, and press
+**Auto-layout selection**. Unselected nodes remain fixed; dashed outlines show
+previous positions. Reset restores the original full layout.
+
+Eight additional stories cover edge-only routing, independently editable constraint groups,
+selected-node placement, affected-route repair, constraint conflicts, overlap
+diagnostics, nested coordinates, and unsupported incremental layout. Controls
+rerun the real API; each story shows matched before/after geometry, patches, and
+current limitations. `pnpm storybook:build` writes a static build to `dist-storybook`.
 
 <!-- exported source compatibility derived from tsconfig.json -->
 

package/dist/elkjs/index.cjs

@@ -0,0 +1,8 @@
+Object.defineProperty(exports, '__esModule', { value: true });
+require('../layered-Cf9Rn8l7.cjs');
+const require_elkjs = require('../elkjs-BVnDwnBQ.cjs');
+
+exports.compileStatechartLayout = require_elkjs.compileStatechartLayout;
+exports.default = require_elkjs.ELK;
+exports.layoutStatechart = require_elkjs.layoutStatechart;
+exports.scoreStatechartLayout = require_elkjs.scoreStatechartLayout;

package/dist/elkjs/index.d.cts

@@ -0,0 +1,146 @@
+import { _ as ElkShape, a as ElkEdgeSection, c as ElkLabel, d as ElkLayoutCategoryDescription, f as ElkLayoutOptionDescription, g as ElkPrimitiveEdge, h as ElkPort, i as ElkEdge, l as ElkLayoutAlgorithmDescription, m as ElkPoint, n as ELKConstructorArguments, o as ElkExtendedEdge, p as ElkNode, r as ElkCommonDescription, s as ElkGraphElement, t as ELK, u as ElkLayoutArguments, v as LaidOutElkNode, y as LayoutOptions } from "../public-types-CVB0hXGk.cjs";
+
+//#region src/elkjs/types.d.ts
+type ElkId = string | number;
+interface ElkGraphElement$1 {
+  id?: ElkId;
+  layoutOptions?: Record<string, unknown>;
+  properties?: Record<string, unknown>;
+}
+interface ElkPoint$1 {
+  x: number;
+  y: number;
+}
+interface ElkShape$1 extends ElkGraphElement$1 {
+  x?: number;
+  y?: number;
+  width?: number;
+  height?: number;
+}
+interface ElkLabel$1 extends ElkShape$1 {
+  text?: string;
+}
+interface ElkPort$1 extends ElkShape$1 {
+  labels?: ElkLabel$1[];
+}
+interface ElkEdgeSection$1 extends ElkGraphElement$1 {
+  startPoint: ElkPoint$1;
+  endPoint: ElkPoint$1;
+  bendPoints?: ElkPoint$1[];
+  incomingShape?: ElkId;
+  outgoingShape?: ElkId;
+}
+interface ElkEdge$1 extends ElkGraphElement$1 {
+  sources?: ElkId[];
+  targets?: ElkId[];
+  source?: ElkId;
+  target?: ElkId;
+  sourcePort?: ElkId;
+  targetPort?: ElkId;
+  labels?: ElkLabel$1[];
+  sections?: ElkEdgeSection$1[];
+  junctionPoints?: ElkPoint$1[];
+}
+interface ElkNode$1 extends ElkShape$1 {
+  labels?: ElkLabel$1[];
+  ports?: ElkPort$1[];
+  children?: ElkNode$1[];
+  edges?: ElkEdge$1[];
+  logging?: ElkLogging;
+}
+interface ElkLogging {
+  name?: string;
+  executionTime?: number;
+  logs?: string[];
+  children?: ElkLogging[];
+}
+interface ElkLayoutArguments$1 {
+  layoutOptions?: Record<string, unknown>;
+  logging?: boolean;
+  measureExecutionTime?: boolean;
+}
+interface ElkConstructorArguments {
+  defaultLayoutOptions?: Record<string, unknown>;
+  algorithms?: string[];
+  workerUrl?: string;
+  workerFactory?: (url?: string) => unknown;
+}
+interface ElkCommonDescription$1 {
+  id?: string;
+  name?: string;
+  description?: string;
+}
+interface ElkLayoutAlgorithmDescription$1 extends ElkCommonDescription$1 {
+  category?: string;
+  knownOptions?: string[];
+  supportedFeatures?: string[];
+}
+interface ElkLayoutOptionDescription$1 extends ElkCommonDescription$1 {
+  group?: string;
+  type?: string;
+  targets?: string[];
+}
+interface ElkLayoutCategoryDescription$1 extends ElkCommonDescription$1 {
+  knownLayouters?: string[];
+}
+type LaidOutElkNode$1<T extends ElkNode$1> = Omit<T, "children" | "edges"> & Omit<ElkNode$1, "children" | "edges"> & {
+  children?: Array<NonNullable<T["children"]>[number] & ElkNode$1>;
+  edges?: Array<NonNullable<T["edges"]>[number] & ElkEdge$1>;
+};
+//#endregion
+//#region src/elkjs/statechart.d.ts
+interface StatechartScope {
+  /** Direct child of this container; never inferred from state names. */
+  initialNodeId?: ElkId;
+  /** Connected direct-child path. Explicit paths resolve branching ambiguity. */
+  preferredPath?: readonly ElkId[];
+  direction?: "UP" | "DOWN" | "LEFT" | "RIGHT";
+}
+interface StatechartLayoutOptions {
+  scopes: Readonly<Record<string, StatechartScope>>;
+  /** Total engine calls, including baseline; integer from 1 to 3. Default 3. */
+  maxAttempts?: number;
+}
+interface StatechartLayoutScore {
+  invalid: number;
+  overlaps: number;
+  pathOrder: number;
+  crossings: number;
+  bends: number;
+  routeLength: number;
+}
+interface StatechartLayoutPlan {
+  graph: ElkNode$1;
+  paths: Record<string, ElkId[]>;
+  commonExits: Record<string, ElkId[]>;
+}
+/** Compile semantic hints into settings implemented by this package's ELK adapter. */
+declare function compileStatechartLayout(input: ElkNode$1, scopes: StatechartLayoutOptions["scopes"]): StatechartLayoutPlan;
+/** Diagnostic objective, not a proof of geometric validity. Coordinates are container-relative. */
+declare function scoreStatechartLayout(graph: ElkNode$1, paths?: StatechartLayoutPlan["paths"]): StatechartLayoutScore;
+/** Each attempt starts from original input. No post-layout geometry edits. */
+declare function layoutStatechart<T extends ElkNode$1>(input: T, options: StatechartLayoutOptions): Promise<{
+  attempts: {
+    kind: "baseline" | "policy" | "spacing";
+    score: StatechartLayoutScore;
+  }[];
+  paths: Record<string, ElkId[]>;
+  commonExits: Record<string, ElkId[]>;
+  graph: LaidOutElkNode$1<T>;
+  score: StatechartLayoutScore;
+  attempt: number;
+}>;
+//#endregion
+//#region src/elkjs/index.d.ts
+declare class ELK$1 {
+  #private;
+  constructor(options?: ElkConstructorArguments);
+  knownLayoutAlgorithms(): Promise<ElkLayoutAlgorithmDescription$1[]>;
+  knownLayoutOptions(): Promise<ElkLayoutOptionDescription$1[]>;
+  knownLayoutCategories(): Promise<ElkLayoutCategoryDescription$1[]>;
+  terminateWorker(): void;
+  layout<T extends ElkNode>(graph: T, arguments_?: ElkLayoutArguments): Promise<ElkNode & LaidOutElkNode<T>>;
+  layout<T extends ElkNode$1>(graph: T, arguments_?: ElkLayoutArguments$1): Promise<LaidOutElkNode$1<T>>;
+}
+//#endregion
+export { type ELK, type ELKConstructorArguments, type ElkCommonDescription, type ElkEdge, type ElkEdgeSection, type ElkExtendedEdge, type ElkGraphElement, type ElkId, type ElkLabel, type ElkLayoutAlgorithmDescription, type ElkLayoutArguments, type ElkLayoutCategoryDescription, type ElkLayoutOptionDescription, type ElkLogging, type ElkNode, type ElkPoint, type ElkPort, type ElkPrimitiveEdge, type ElkShape, type LaidOutElkNode, type LayoutOptions, type StatechartLayoutOptions, type StatechartLayoutPlan, type StatechartLayoutScore, type StatechartScope, compileStatechartLayout, ELK$1 as default, layoutStatechart, scoreStatechartLayout };

package/dist/elkjs/index.d.mts

@@ -1,49 +1,51 @@
+import { _ as ElkShape, a as ElkEdgeSection, c as ElkLabel, d as ElkLayoutCategoryDescription, f as ElkLayoutOptionDescription, g as ElkPrimitiveEdge, h as ElkPort, i as ElkEdge, l as ElkLayoutAlgorithmDescription, m as ElkPoint, n as ELKConstructorArguments, o as ElkExtendedEdge, p as ElkNode, r as ElkCommonDescription, s as ElkGraphElement, t as ELK, u as ElkLayoutArguments, v as LaidOutElkNode, y as LayoutOptions } from "../public-types-B8rAALJq.mjs";
+
 //#region src/elkjs/types.d.ts
 type ElkId = string | number;
-interface ElkGraphElement {
+interface ElkGraphElement$1 {
   id?: ElkId;
   layoutOptions?: Record<string, unknown>;
   properties?: Record<string, unknown>;
 }
-interface ElkPoint {
+interface ElkPoint$1 {
   x: number;
   y: number;
 }
-interface ElkShape extends ElkGraphElement {
+interface ElkShape$1 extends ElkGraphElement$1 {
   x?: number;
   y?: number;
   width?: number;
   height?: number;
 }
-interface ElkLabel extends ElkShape {
+interface ElkLabel$1 extends ElkShape$1 {
   text?: string;
 }
-interface ElkPort extends ElkShape {
-  labels?: ElkLabel[];
+interface ElkPort$1 extends ElkShape$1 {
+  labels?: ElkLabel$1[];
 }
-interface ElkEdgeSection extends ElkGraphElement {
-  startPoint: ElkPoint;
-  endPoint: ElkPoint;
-  bendPoints?: ElkPoint[];
+interface ElkEdgeSection$1 extends ElkGraphElement$1 {
+  startPoint: ElkPoint$1;
+  endPoint: ElkPoint$1;
+  bendPoints?: ElkPoint$1[];
   incomingShape?: ElkId;
   outgoingShape?: ElkId;
 }
-interface ElkEdge extends ElkGraphElement {
+interface ElkEdge$1 extends ElkGraphElement$1 {
   sources?: ElkId[];
   targets?: ElkId[];
   source?: ElkId;
   target?: ElkId;
   sourcePort?: ElkId;
   targetPort?: ElkId;
-  labels?: ElkLabel[];
-  sections?: ElkEdgeSection[];
-  junctionPoints?: ElkPoint[];
-}
-interface ElkNode extends ElkShape {
-  labels?: ElkLabel[];
-  ports?: ElkPort[];
-  children?: ElkNode[];
-  edges?: ElkEdge[];
+  labels?: ElkLabel$1[];
+  sections?: ElkEdgeSection$1[];
+  junctionPoints?: ElkPoint$1[];
+}
+interface ElkNode$1 extends ElkShape$1 {
+  labels?: ElkLabel$1[];
+  ports?: ElkPort$1[];
+  children?: ElkNode$1[];
+  edges?: ElkEdge$1[];
   logging?: ElkLogging;
 }
 interface ElkLogging {
@@ -52,7 +54,7 @@ interface ElkLogging {
   logs?: string[];
   children?: ElkLogging[];
 }
-interface ElkLayoutArguments {
+interface ElkLayoutArguments$1 {
   layoutOptions?: Record<string, unknown>;
   logging?: boolean;
   measureExecutionTime?: boolean;
@@ -63,27 +65,27 @@ interface ElkConstructorArguments {
   workerUrl?: string;
   workerFactory?: (url?: string) => unknown;
 }
-interface ElkCommonDescription {
+interface ElkCommonDescription$1 {
   id?: string;
   name?: string;
   description?: string;
 }
-interface ElkLayoutAlgorithmDescription extends ElkCommonDescription {
+interface ElkLayoutAlgorithmDescription$1 extends ElkCommonDescription$1 {
   category?: string;
   knownOptions?: string[];
   supportedFeatures?: string[];
 }
-interface ElkLayoutOptionDescription extends ElkCommonDescription {
+interface ElkLayoutOptionDescription$1 extends ElkCommonDescription$1 {
   group?: string;
   type?: string;
   targets?: string[];
 }
-interface ElkLayoutCategoryDescription extends ElkCommonDescription {
+interface ElkLayoutCategoryDescription$1 extends ElkCommonDescription$1 {
   knownLayouters?: string[];
 }
-type LaidOutElkNode<T extends ElkNode> = Omit<T, "children" | "edges"> & Omit<ElkNode, "children" | "edges"> & {
-  children?: Array<NonNullable<T["children"]>[number] & ElkNode>;
-  edges?: Array<NonNullable<T["edges"]>[number] & ElkEdge>;
+type LaidOutElkNode$1<T extends ElkNode$1> = Omit<T, "children" | "edges"> & Omit<ElkNode$1, "children" | "edges"> & {
+  children?: Array<NonNullable<T["children"]>[number] & ElkNode$1>;
+  edges?: Array<NonNullable<T["edges"]>[number] & ElkEdge$1>;
 };
 //#endregion
 //#region src/elkjs/statechart.d.ts
@@ -108,36 +110,37 @@ interface StatechartLayoutScore {
   routeLength: number;
 }
 interface StatechartLayoutPlan {
-  graph: ElkNode;
+  graph: ElkNode$1;
   paths: Record<string, ElkId[]>;
   commonExits: Record<string, ElkId[]>;
 }
 /** Compile semantic hints into settings implemented by this package's ELK adapter. */
-declare function compileStatechartLayout(input: ElkNode, scopes: StatechartLayoutOptions["scopes"]): StatechartLayoutPlan;
+declare function compileStatechartLayout(input: ElkNode$1, scopes: StatechartLayoutOptions["scopes"]): StatechartLayoutPlan;
 /** Diagnostic objective, not a proof of geometric validity. Coordinates are container-relative. */
-declare function scoreStatechartLayout(graph: ElkNode, paths?: StatechartLayoutPlan["paths"]): StatechartLayoutScore;
+declare function scoreStatechartLayout(graph: ElkNode$1, paths?: StatechartLayoutPlan["paths"]): StatechartLayoutScore;
 /** Each attempt starts from original input. No post-layout geometry edits. */
-declare function layoutStatechart<T extends ElkNode>(input: T, options: StatechartLayoutOptions): Promise<{
+declare function layoutStatechart<T extends ElkNode$1>(input: T, options: StatechartLayoutOptions): Promise<{
   attempts: {
     kind: "baseline" | "policy" | "spacing";
     score: StatechartLayoutScore;
   }[];
   paths: Record<string, ElkId[]>;
   commonExits: Record<string, ElkId[]>;
-  graph: LaidOutElkNode<T>;
+  graph: LaidOutElkNode$1<T>;
   score: StatechartLayoutScore;
   attempt: number;
 }>;
 //#endregion
 //#region src/elkjs/index.d.ts
-declare class ELK {
+declare class ELK$1 {
   #private;
   constructor(options?: ElkConstructorArguments);
-  knownLayoutAlgorithms(): Promise<ElkLayoutAlgorithmDescription[]>;
-  knownLayoutOptions(): Promise<ElkLayoutOptionDescription[]>;
-  knownLayoutCategories(): Promise<ElkLayoutCategoryDescription[]>;
+  knownLayoutAlgorithms(): Promise<ElkLayoutAlgorithmDescription$1[]>;
+  knownLayoutOptions(): Promise<ElkLayoutOptionDescription$1[]>;
+  knownLayoutCategories(): Promise<ElkLayoutCategoryDescription$1[]>;
   terminateWorker(): void;
-  layout<T extends ElkNode>(graph: T, arguments_?: ElkLayoutArguments): Promise<LaidOutElkNode<T>>;
+  layout<T extends ElkNode>(graph: T, arguments_?: ElkLayoutArguments): Promise<ElkNode & LaidOutElkNode<T>>;
+  layout<T extends ElkNode$1>(graph: T, arguments_?: ElkLayoutArguments$1): Promise<LaidOutElkNode$1<T>>;
 }
 //#endregion
-export { type ElkCommonDescription, type ElkConstructorArguments, type ElkEdge, type ElkEdgeSection, type ElkGraphElement, type ElkId, type ElkLabel, type ElkLayoutAlgorithmDescription, type ElkLayoutArguments, type ElkLayoutCategoryDescription, type ElkLayoutOptionDescription, type ElkLogging, type ElkNode, type ElkPoint, type ElkPort, type ElkShape, type LaidOutElkNode, type StatechartLayoutOptions, type StatechartLayoutPlan, type StatechartLayoutScore, type StatechartScope, compileStatechartLayout, ELK as default, layoutStatechart, scoreStatechartLayout };
+export { type ELK, type ELKConstructorArguments, type ElkCommonDescription, type ElkEdge, type ElkEdgeSection, type ElkExtendedEdge, type ElkGraphElement, type ElkId, type ElkLabel, type ElkLayoutAlgorithmDescription, type ElkLayoutArguments, type ElkLayoutCategoryDescription, type ElkLayoutOptionDescription, type ElkLogging, type ElkNode, type ElkPoint, type ElkPort, type ElkPrimitiveEdge, type ElkShape, type LaidOutElkNode, type LayoutOptions, type StatechartLayoutOptions, type StatechartLayoutPlan, type StatechartLayoutScore, type StatechartScope, compileStatechartLayout, ELK$1 as default, layoutStatechart, scoreStatechartLayout };