Merge pull request #25 from 0xPlaygrounds/ryz-1562-per-group-direction

feat(canvas-layout-ts): per-group direction override

Author: mateobelanger

.changeset/rectpacking-algorithm.md

@@ -0,0 +1,5 @@
+---
+"@ryzome-ai/canvas-layout-ts": minor
+---
+
+Add `rectpacking` layout algorithm alongside the existing `layered` flow. Configurable at the root (`LayoutOptions.algorithm`, `LayoutOptions.aspectRatio`) and per-group (`LayoutGroupInput.algorithm`, `LayoutGroupInput.aspectRatio`). Groups whose algorithm or direction differs from the root are isolated via `SEPARATE_CHILDREN` so the override actually applies.

packages/canvas-layout-ts/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ryzome-ai/canvas-layout-ts",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"description": "Ryzome canvas layout — compound-graph placement for nodes, edges, and groups via elkjs",
 	"license": "MIT",
 	"type": "module",

packages/canvas-layout-ts/src/__tests__/layout.test.ts

@@ -204,6 +204,85 @@ describe("computeCanvasLayout", () => {
 		expect(result.nodes.a.y).toBeLessThan(result.nodes.b.y);
 	});
 
+	it("lays out a group's members along its direction override", async () => {
+		// Horizontal root direction, but g1 asks for DOWN internally.
+		const result = await computeCanvasLayout(
+			{
+				nodes: [
+					{ id: "a", group: "g1" },
+					{ id: "b", group: "g1", dependsOn: ["a"] },
+					{ id: "c", group: "g1", dependsOn: ["b"] },
+				],
+				groups: [{ id: "g1", direction: "DOWN" }],
+			},
+			{ direction: "RIGHT" },
+		);
+
+		const { a, b, c } = result.nodes;
+		// DOWN inside g1 -> successor y strictly greater, x roughly equal.
+		expect(a.y).toBeLessThan(b.y);
+		expect(b.y).toBeLessThan(c.y);
+		expect(Math.abs(a.x - b.x)).toBeLessThan(10);
+		expect(Math.abs(b.x - c.x)).toBeLessThan(10);
+	});
+
+	it("packs edgeless nodes into a rectangle when algorithm is rectpacking", async () => {
+		const nodes = Array.from({ length: 30 }, (_, i) => ({ id: `n${i}` }));
+		const result = await computeCanvasLayout(
+			{ nodes },
+			{ algorithm: "rectpacking", aspectRatio: 1.6 },
+		);
+
+		const rects = Object.values(result.nodes);
+		expect(rects).toHaveLength(30);
+		// No overlaps.
+		for (let i = 0; i < rects.length; i++) {
+			for (let j = i + 1; j < rects.length; j++) {
+				expect(rectsOverlap(rects[i], rects[j])).toBe(false);
+			}
+		}
+		// With 30 identical 320x180 nodes and aspectRatio 1.6, rectpacking
+		// should produce a rough rectangle — nowhere near a single row or
+		// single column. Bounding-box width and height should both be
+		// meaningfully non-zero.
+		const minX = Math.min(...rects.map((r) => r.x));
+		const maxX = Math.max(...rects.map((r) => r.x + r.width));
+		const minY = Math.min(...rects.map((r) => r.y));
+		const maxY = Math.max(...rects.map((r) => r.y + r.height));
+		const boxWidth = maxX - minX;
+		const boxHeight = maxY - minY;
+		expect(boxWidth).toBeGreaterThan(500);
+		expect(boxHeight).toBeGreaterThan(500);
+	});
+
+	it("packs a group's edgeless members with rectpacking while the root stays layered", async () => {
+		// 12 edgeless members inside g1 (rectpacking), plus a free node outside.
+		const members = Array.from({ length: 12 }, (_, i) => ({
+			id: `m${i}`,
+			group: "g1",
+		}));
+		const result = await computeCanvasLayout({
+			nodes: [...members, { id: "free" }],
+			groups: [{ id: "g1", algorithm: "rectpacking", aspectRatio: 1.6 }],
+		});
+
+		const memberRects = members.map((m) => result.nodes[m.id]);
+		// Every member nested inside g1's rect.
+		for (const rect of memberRects) {
+			expect(rectContains(result.groups.g1, rect, 1)).toBe(true);
+		}
+		// Members packed into a rectangle — both dimensions should be
+		// substantially > the width of a single node.
+		const minX = Math.min(...memberRects.map((r) => r.x));
+		const maxX = Math.max(...memberRects.map((r) => r.x + r.width));
+		const minY = Math.min(...memberRects.map((r) => r.y));
+		const maxY = Math.max(...memberRects.map((r) => r.y + r.height));
+		expect(maxX - minX).toBeGreaterThan(400);
+		expect(maxY - minY).toBeGreaterThan(200);
+		// Free node must not overlap g1.
+		expect(rectsOverlap(result.groups.g1, result.nodes.free, 1)).toBe(false);
+	});
+
 	it("handles a 50-node DAG with groups without overlaps", async () => {
 		const nodes = Array.from({ length: 50 }, (_, i) => ({
 			id: `n${i}`,

packages/canvas-layout-ts/src/index.ts

@@ -1,5 +1,6 @@
 export { computeCanvasLayout } from "./layout.js";
 export type {
+	LayoutAlgorithm,
 	LayoutDirection,
 	LayoutEdgeInput,
 	LayoutGroupInput,

packages/canvas-layout-ts/src/layout.ts

@@ -1,6 +1,12 @@
 import ELK from "elkjs/lib/elk.bundled.js";
-import type { ElkNode, ElkExtendedEdge, LayoutOptions as ElkLayoutOptions } from "elkjs/lib/elk-api";
 import type {
+	ElkNode,
+	ElkExtendedEdge,
+	LayoutOptions as ElkLayoutOptions,
+} from "elkjs/lib/elk-api";
+import type {
+	LayoutAlgorithm,
+	LayoutDirection,
 	LayoutInput,
 	LayoutNodeInput,
 	LayoutOptions,
@@ -20,6 +26,38 @@ const DEFAULT_SPACING = {
 const DEFAULT_GROUP_PADDING = 40;
 const GROUP_HEADER_PADDING = 60;
 
+/**
+ * Build ELK layoutOptions for a given algorithm. `rectpacking` and `layered`
+ * share `elk.spacing.nodeNode` but otherwise take disjoint option keys — ELK
+ * silently ignores irrelevant keys but we keep the output narrow for clarity.
+ */
+function buildAlgorithmLayoutOptions(params: {
+	algorithm: LayoutAlgorithm;
+	direction: LayoutDirection;
+	spacing: { nodeNode: number; nodeNodeBetweenLayers: number; edgeNode: number };
+	aspectRatio?: number;
+	includeHierarchyHandling?: "INCLUDE_CHILDREN" | "SEPARATE_CHILDREN";
+}): ElkLayoutOptions {
+	const options: ElkLayoutOptions = {
+		"elk.algorithm": params.algorithm,
+		"elk.spacing.nodeNode": String(params.spacing.nodeNode),
+	};
+	if (params.algorithm === "layered") {
+		options["elk.direction"] = params.direction;
+		options["elk.layered.spacing.nodeNodeBetweenLayers"] = String(
+			params.spacing.nodeNodeBetweenLayers,
+		);
+		options["elk.spacing.edgeNode"] = String(params.spacing.edgeNode);
+	}
+	if (params.algorithm === "rectpacking" && params.aspectRatio !== undefined) {
+		options["elk.aspectRatio"] = String(params.aspectRatio);
+	}
+	if (params.includeHierarchyHandling) {
+		options["elk.hierarchyHandling"] = params.includeHierarchyHandling;
+	}
+	return options;
+}
+
 /**
  * Lay out a Ryzome canvas with elkjs. Groups become compound (parent) nodes so
  * members stay spatially clustered; the result includes both individual node
@@ -36,6 +74,7 @@ export async function computeCanvasLayout(
 
 	const spacing = { ...DEFAULT_SPACING, ...options.spacing };
 	const direction = options.direction ?? "DOWN";
+	const algorithm: LayoutAlgorithm = options.algorithm ?? "layered";
 	const groupPadding = options.groupPadding ?? DEFAULT_GROUP_PADDING;
 
 	const measureNode =
@@ -100,36 +139,47 @@ export async function computeCanvasLayout(
 		if (members.length === 0) continue;
 
 		const pad = group.padding ?? groupPadding;
+		const groupDirection = group.direction ?? direction;
+		const groupAlgorithm = group.algorithm ?? algorithm;
+		// When the group's direction or algorithm differs from the root, the
+		// root's INCLUDE_CHILDREN hierarchy handling would otherwise let the
+		// parent layout dominate. Force SEPARATE_CHILDREN so the override
+		// actually takes effect on this group's members.
+		const needsLocalLayout =
+			groupDirection !== direction || groupAlgorithm !== algorithm;
+		const groupLayoutOptions = buildAlgorithmLayoutOptions({
+			algorithm: groupAlgorithm,
+			direction: groupDirection,
+			spacing,
+			aspectRatio: group.aspectRatio,
+			includeHierarchyHandling: needsLocalLayout
+				? "SEPARATE_CHILDREN"
+				: undefined,
+		});
+		groupLayoutOptions["elk.padding"] =
+			`[top=${GROUP_HEADER_PADDING},left=${pad},bottom=${pad},right=${pad}]`;
 		const groupNode: ElkNode = {
 			id: group.id,
 			children: members.map(makeLeafNode),
-			layoutOptions: {
-				"elk.padding": `[top=${GROUP_HEADER_PADDING},left=${pad},bottom=${pad},right=${pad}]`,
-				// Still layer members inside the group.
-				"elk.algorithm": "layered",
-				"elk.direction": direction,
-				"elk.layered.spacing.nodeNodeBetweenLayers": String(
-					spacing.nodeNodeBetweenLayers,
-				),
-				"elk.spacing.nodeNode": String(spacing.nodeNode),
-			},
+			layoutOptions: groupLayoutOptions,
 		};
 		rootChildren.push(groupNode);
 	}
 
-	const rootLayoutOptions: ElkLayoutOptions = {
-		"elk.algorithm": "layered",
-		"elk.direction": direction,
-		"elk.layered.spacing.nodeNodeBetweenLayers": String(
-			spacing.nodeNodeBetweenLayers,
-		),
-		"elk.spacing.nodeNode": String(spacing.nodeNode),
-		"elk.spacing.edgeNode": String(spacing.edgeNode),
-		// Place disconnected components side-by-side instead of overlapping them at the origin.
-		"elk.separateConnectedComponents": "true",
+	const rootLayoutOptions = buildAlgorithmLayoutOptions({
+		algorithm,
+		direction,
+		spacing,
+		aspectRatio: options.aspectRatio,
 		// Consider node size when routing; hierarchical edges cross group boundaries.
-		"elk.hierarchyHandling": "INCLUDE_CHILDREN",
-	};
+		// Only meaningful for `layered`.
+		includeHierarchyHandling:
+			algorithm === "layered" ? "INCLUDE_CHILDREN" : undefined,
+	});
+	if (algorithm === "layered") {
+		// Place disconnected components side-by-side instead of overlapping at origin.
+		rootLayoutOptions["elk.separateConnectedComponents"] = "true";
+	}
 
 	const root: ElkNode = {
 		id: "__root__",

packages/canvas-layout-ts/src/types.ts

@@ -15,6 +15,23 @@ export interface LayoutGroupInput {
 	id: string;
 	title?: string;
 	padding?: number;
+	/**
+	 * Override the layout direction for this group's members only. When omitted,
+	 * the group inherits the root layout direction. Useful for canvases whose
+	 * subgraphs want different orientations (e.g., a vertical pipeline nested
+	 * inside a horizontally-flowing outer graph).
+	 */
+	direction?: LayoutDirection;
+	/**
+	 * Override the algorithm used inside this group. Set to `"rectpacking"`
+	 * for edgeless clusters (moodboards) while the root stays `"layered"`.
+	 */
+	algorithm?: LayoutAlgorithm;
+	/**
+	 * Target aspect ratio (width / height) forwarded as `elk.aspectRatio`
+	 * when using `rectpacking`. Ignored for `layered`.
+	 */
+	aspectRatio?: number;
 }
 
 export interface LayoutInput {
@@ -37,6 +54,13 @@ export interface LayoutResult {
 
 export type LayoutDirection = "DOWN" | "RIGHT" | "UP" | "LEFT";
 
+/**
+ * Supported elkjs algorithms. `layered` is the default Sugiyama-style
+ * flow layout for DAGs. `rectpacking` packs edgeless or near-edgeless
+ * inputs into a rectangle — used for moodboard-style clusters.
+ */
+export type LayoutAlgorithm = "layered" | "rectpacking";
+
 export interface LayoutSpacing {
 	/** Space between sibling nodes in the same layer. */
 	nodeNode?: number;
@@ -58,4 +82,14 @@ export interface LayoutOptions {
 	spacing?: LayoutSpacing;
 	/** Padding applied around every group's members. Default 40 (60 on top for label room). */
 	groupPadding?: number;
+	/**
+	 * Root-level ELK algorithm. Default `"layered"`. Use `"rectpacking"` when
+	 * the input has no (or few) edges and should be packed into a rectangle.
+	 */
+	algorithm?: LayoutAlgorithm;
+	/**
+	 * Target aspect ratio (width / height) forwarded as `elk.aspectRatio` when
+	 * using `rectpacking`. Ignored for `layered`.
+	 */
+	aspectRatio?: number;
 }