pict-section-flow 1.3.0 → 2.0.0

package/scripts/generate-card-help.js

@@ -1,214 +0,0 @@
-#!/usr/bin/env node
-/**
- * generate-card-help.js
- *
- * Reads markdown files from docs/card-help/ and generates a CommonJS module
- * that exports an object mapping card codes to rendered HTML strings.
- *
- * Each markdown file is named by its card code (e.g. ITE.md, SET.md).
- * The file content is converted from markdown to HTML and embedded as a
- * string in the generated module.
- *
- * Usage:
- *   node scripts/generate-card-help.js [source_dir] [output_file]
- *
- * Defaults:
- *   source_dir  = docs/card-help
- *   output_file = example_applications/simple_cards/source/card-help-content.js
- *
- * If the source directory does not exist or contains no markdown files the
- * script writes an empty map and exits cleanly — the build never fails due
- * to missing documentation.
- */
-
-const libFS = require('fs');
-const libPath = require('path');
-
-// ---------------------------------------------------------------------------
-// Minimal markdown-to-HTML converter
-// ---------------------------------------------------------------------------
-// Handles the subset of markdown used in card help documentation:
-//   headings (#, ##, ###), bold (**), italic (*), inline code (`),
-//   unordered lists (- or *), ordered lists (1.), paragraphs, line breaks,
-//   and horizontal rules (---).
-// ---------------------------------------------------------------------------
-
-function convertMarkdownToHTML(pMarkdown)
-{
-	let tmpLines = pMarkdown.split('\n');
-	let tmpHTML = [];
-	let tmpInList = false;
-	let tmpListType = '';
-	let tmpParagraph = [];
-
-	function flushParagraph()
-	{
-		if (tmpParagraph.length > 0)
-		{
-			tmpHTML.push('<p>' + tmpParagraph.join(' ') + '</p>');
-			tmpParagraph = [];
-		}
-	}
-
-	function closeList()
-	{
-		if (tmpInList)
-		{
-			tmpHTML.push(tmpListType === 'ul' ? '</ul>' : '</ol>');
-			tmpInList = false;
-			tmpListType = '';
-		}
-	}
-
-	function inlineFormat(pText)
-	{
-		// Inline code
-		pText = pText.replace(/`([^`]+)`/g, '<code>$1</code>');
-		// Bold (** or __)
-		pText = pText.replace(/\*\*([^*]+)\*\*/g, '<b>$1</b>');
-		pText = pText.replace(/__([^_]+)__/g, '<b>$1</b>');
-		// Italic (* or _)
-		pText = pText.replace(/\*([^*]+)\*/g, '<i>$1</i>');
-		pText = pText.replace(/(?<!\w)_([^_]+)_(?!\w)/g, '<i>$1</i>');
-		// Links
-		pText = pText.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2">$1</a>');
-		return pText;
-	}
-
-	for (let i = 0; i < tmpLines.length; i++)
-	{
-		let tmpLine = tmpLines[i];
-		let tmpTrimmed = tmpLine.trim();
-
-		// Empty line — flush paragraph
-		if (tmpTrimmed === '')
-		{
-			flushParagraph();
-			continue;
-		}
-
-		// Horizontal rule
-		if (/^-{3,}$/.test(tmpTrimmed) || /^\*{3,}$/.test(tmpTrimmed))
-		{
-			flushParagraph();
-			closeList();
-			tmpHTML.push('<hr>');
-			continue;
-		}
-
-		// Headings
-		let tmpHeadingMatch = tmpTrimmed.match(/^(#{1,6})\s+(.*)$/);
-		if (tmpHeadingMatch)
-		{
-			flushParagraph();
-			closeList();
-			let tmpLevel = tmpHeadingMatch[1].length;
-			tmpHTML.push('<h' + tmpLevel + '>' + inlineFormat(tmpHeadingMatch[2]) + '</h' + tmpLevel + '>');
-			continue;
-		}
-
-		// Unordered list item (- or *)
-		let tmpULMatch = tmpTrimmed.match(/^[-*]\s+(.*)$/);
-		if (tmpULMatch)
-		{
-			flushParagraph();
-			if (!tmpInList || tmpListType !== 'ul')
-			{
-				closeList();
-				tmpHTML.push('<ul>');
-				tmpInList = true;
-				tmpListType = 'ul';
-			}
-			tmpHTML.push('<li>' + inlineFormat(tmpULMatch[1]) + '</li>');
-			continue;
-		}
-
-		// Ordered list item (1. 2. etc)
-		let tmpOLMatch = tmpTrimmed.match(/^\d+\.\s+(.*)$/);
-		if (tmpOLMatch)
-		{
-			flushParagraph();
-			if (!tmpInList || tmpListType !== 'ol')
-			{
-				closeList();
-				tmpHTML.push('<ol>');
-				tmpInList = true;
-				tmpListType = 'ol';
-			}
-			tmpHTML.push('<li>' + inlineFormat(tmpOLMatch[1]) + '</li>');
-			continue;
-		}
-
-		// Regular text — accumulate into paragraph
-		closeList();
-		tmpParagraph.push(inlineFormat(tmpTrimmed));
-	}
-
-	flushParagraph();
-	closeList();
-
-	return tmpHTML.join('');
-}
-
-// ---------------------------------------------------------------------------
-// Main
-// ---------------------------------------------------------------------------
-
-let tmpModuleRoot = libPath.resolve(__dirname, '..');
-let tmpSourceDir = process.argv[2]
-	? libPath.resolve(process.argv[2])
-	: libPath.join(tmpModuleRoot, 'docs', 'card-help');
-let tmpOutputFile = process.argv[3]
-	? libPath.resolve(process.argv[3])
-	: libPath.join(tmpModuleRoot, 'example_applications', 'simple_cards', 'source', 'card-help-content.js');
-
-let tmpHelpMap = {};
-
-// Gracefully handle missing source directory
-if (libFS.existsSync(tmpSourceDir))
-{
-	let tmpFiles = libFS.readdirSync(tmpSourceDir).filter(
-		(pFile) => { return pFile.endsWith('.md'); }
-	);
-
-	for (let i = 0; i < tmpFiles.length; i++)
-	{
-		let tmpFile = tmpFiles[i];
-		let tmpCode = libPath.basename(tmpFile, '.md');
-		try
-		{
-			let tmpContent = libFS.readFileSync(libPath.join(tmpSourceDir, tmpFile), 'utf8');
-			let tmpHTML = convertMarkdownToHTML(tmpContent);
-			if (tmpHTML.length > 0)
-			{
-				tmpHelpMap[tmpCode] = tmpHTML;
-			}
-		}
-		catch (pError)
-		{
-			// Skip files that cannot be read — never fail the build
-			console.warn('generate-card-help: skipping ' + tmpFile + ' (' + pError.message + ')');
-		}
-	}
-
-	console.log('generate-card-help: processed ' + Object.keys(tmpHelpMap).length + ' card help files from ' + tmpSourceDir);
-}
-else
-{
-	console.log('generate-card-help: no docs/card-help directory found — generating empty map');
-}
-
-// Ensure output directory exists
-let tmpOutputDir = libPath.dirname(tmpOutputFile);
-if (!libFS.existsSync(tmpOutputDir))
-{
-	libFS.mkdirSync(tmpOutputDir, { recursive: true });
-}
-
-// Write the generated module
-let tmpOutput = '// Auto-generated by scripts/generate-card-help.js — do not edit manually.\n';
-tmpOutput += '// Source markdown files are in docs/card-help/\n';
-tmpOutput += 'module.exports = ' + JSON.stringify(tmpHelpMap, null, '\t') + ';\n';
-
-libFS.writeFileSync(tmpOutputFile, tmpOutput, 'utf8');
-console.log('generate-card-help: wrote ' + tmpOutputFile);

package/source/providers/edges/Edge-Bezier.js

@@ -1,41 +0,0 @@
-/**
- * Edge-Bezier
- *
- * Default edge theme: smooth cubic bezier between source and target ports,
- * with departure/approach geometry derived from each port's `Side`. This
- * is a thin wrapper around the renderer's pre-existing bezier path
- * generator — selecting it is equivalent to the historical default.
- *
- * Honors per-connection multi-handle waypoints (BezierHandles) when
- * present so user-edited curves still survive.
- */
-module.exports =
-{
-	Name: 'Bezier',
-	Label: 'Bezier (smooth)',
-	Description: 'Smooth cubic curves with side-aware departures.',
-
-	GeneratePath: function (pContext)
-	{
-		let tmpHelpers = pContext.Helpers;
-		let tmpSrc = pContext.Source;
-		let tmpTgt = pContext.Target;
-		let tmpData = (pContext.Connection && pContext.Connection.Data) || {};
-
-		// Preserve user-customized multi-handle bezier waypoints.
-		if (tmpData.HandleCustomized)
-		{
-			let tmpHandles = tmpHelpers.getBezierHandles(tmpData);
-			if (tmpHandles.length > 0)
-			{
-				return tmpHelpers.generateMultiBezier(tmpSrc, tmpTgt, tmpHandles);
-			}
-		}
-
-		return tmpHelpers.generateBezier(tmpSrc, tmpTgt);
-	},
-
-	DefaultParameters: {},
-
-	ParameterSchema: {}
-};

package/source/providers/edges/Edge-Orthogonal.js

@@ -1,37 +0,0 @@
-/**
- * Edge-Orthogonal
- *
- * Right-angle (Manhattan) routing between source and target. Reads
- * cleanly for layered DAGs and grid-shaped layouts. Per-connection
- * `OrthoMidOffset` and customized corner overrides are preserved.
- */
-module.exports =
-{
-	Name: 'Orthogonal',
-	Label: 'Orthogonal (right-angle)',
-	Description: 'Right-angle routing — reads well for DAGs and grids.',
-
-	GeneratePath: function (pContext)
-	{
-		let tmpHelpers = pContext.Helpers;
-		let tmpSrc = pContext.Source;
-		let tmpTgt = pContext.Target;
-		let tmpData = (pContext.Connection && pContext.Connection.Data) || {};
-
-		let tmpCorners = null;
-		if (tmpData.HandleCustomized && tmpData.OrthoCorner1X != null)
-		{
-			tmpCorners =
-			{
-				corner1: { x: tmpData.OrthoCorner1X, y: tmpData.OrthoCorner1Y },
-				corner2: { x: tmpData.OrthoCorner2X, y: tmpData.OrthoCorner2Y }
-			};
-		}
-
-		return tmpHelpers.generateOrthogonal(tmpSrc, tmpTgt, tmpCorners, tmpData.OrthoMidOffset || 0);
-	},
-
-	DefaultParameters: {},
-
-	ParameterSchema: {}
-};

package/source/providers/edges/Edge-OrthogonalSnap.js

@@ -1,72 +0,0 @@
-const libCoerce = require('../layouts/Layout-Coerce.js');
-
-/**
- * Edge-OrthogonalSnap
- *
- * Demonstrates the "edge theme can affect node placement" axis. Same
- * right-angle routing as Edge-Orthogonal, but with an `AdjustLayout`
- * pass that snaps every node's X/Y to a grid so corner segments line
- * up cleanly across the diagram.
- *
- * Trade-off: nodes shift slightly from the layout's natural positions
- * to gain visual alignment. The user opts into this by picking the
- * theme — the layout algorithm itself is unaware.
- */
-module.exports =
-{
-	Name: 'OrthogonalSnap',
-	Label: 'Orthogonal (snap to grid)',
-	Description: 'Right-angle routing; snaps node positions to a grid for cleaner corner alignment. Demonstrates an edge theme that adjusts node placement.',
-
-	GeneratePath: function (pContext)
-	{
-		let tmpHelpers = pContext.Helpers;
-		let tmpSrc = pContext.Source;
-		let tmpTgt = pContext.Target;
-		let tmpData = (pContext.Connection && pContext.Connection.Data) || {};
-
-		let tmpCorners = null;
-		if (tmpData.HandleCustomized && tmpData.OrthoCorner1X != null)
-		{
-			tmpCorners =
-			{
-				corner1: { x: tmpData.OrthoCorner1X, y: tmpData.OrthoCorner1Y },
-				corner2: { x: tmpData.OrthoCorner2X, y: tmpData.OrthoCorner2Y }
-			};
-		}
-
-		return tmpHelpers.generateOrthogonal(tmpSrc, tmpTgt, tmpCorners, tmpData.OrthoMidOffset || 0);
-	},
-
-	/**
-	 * Snap each node's (X, Y) to the configured grid after the layout
-	 * has run. Mutates pNodes in place.
-	 *
-	 * @param {Array} pNodes
-	 * @param {Array} pConnections
-	 * @param {Object} pParameters
-	 */
-	AdjustLayout: function (pNodes, pConnections, pParameters)
-	{
-		let tmpGridSize = libCoerce.toFloat((pParameters || {}).GridSize, 20);
-		if (tmpGridSize <= 0) return;
-
-		for (let i = 0; i < pNodes.length; i++)
-		{
-			let tmpNode = pNodes[i];
-			if (typeof tmpNode.X !== 'number' || typeof tmpNode.Y !== 'number') continue;
-			tmpNode.X = Math.round(tmpNode.X / tmpGridSize) * tmpGridSize;
-			tmpNode.Y = Math.round(tmpNode.Y / tmpGridSize) * tmpGridSize;
-		}
-	},
-
-	DefaultParameters:
-	{
-		GridSize: 20
-	},
-
-	ParameterSchema:
-	{
-		GridSize: { Type: 'PreciseNumber', Label: 'Grid size', Default: 20, Min: 1, Max: 200 }
-	}
-};

package/source/providers/edges/Edge-Perimeter-Linear.js

@@ -1,31 +0,0 @@
-const libPerimeterMath = require('./Edge-PerimeterMath.js');
-
-/**
- * Edge-Perimeter-Linear
- *
- * Perimeter attachment + literal straight line between the two
- * resolved exit points. Reads cleanly for force-directed and circular
- * layouts where the topology already determines edge angles, and the
- * curves of bezier add visual noise.
- */
-module.exports =
-{
-	Name: 'Perimeter-Linear',
-	Label: 'Perimeter (linear)',
-	Description: 'Each connection exits the node at the perimeter, then runs as a straight line to the other end.',
-
-	GeneratePath: function (pContext)
-	{
-		let tmpS = pContext.Source;
-		let tmpT = pContext.Target;
-		return `M ${tmpS.x} ${tmpS.y} L ${tmpT.x} ${tmpT.y}`;
-	},
-
-	ResolveAttachment: function (pContext)
-	{
-		return libPerimeterMath.resolvePerimeterAttachment(pContext);
-	},
-
-	DefaultParameters: {},
-	ParameterSchema: {}
-};

package/source/providers/edges/Edge-Perimeter-Orthogonal.js

@@ -1,39 +0,0 @@
-const libPerimeterMath = require('./Edge-PerimeterMath.js');
-
-/**
- * Edge-Perimeter-Orthogonal
- *
- * Perimeter attachment + right-angle (Manhattan) routing between
- * the two resolved exit points. Best when the layout already has
- * grid-like structure (Grid, Mesh) and you want connections to
- * leave from whichever side faces the partner.
- */
-module.exports =
-{
-	Name: 'Perimeter-Orthogonal',
-	Label: 'Perimeter (orthogonal)',
-	Description: 'Each connection exits the node at the perimeter, then routes via right-angle segments to the other end.',
-
-	GeneratePath: function (pContext)
-	{
-		let tmpData = (pContext.Connection && pContext.Connection.Data) || {};
-		let tmpCorners = null;
-		if (tmpData.HandleCustomized && tmpData.OrthoCorner1X != null)
-		{
-			tmpCorners =
-			{
-				corner1: { x: tmpData.OrthoCorner1X, y: tmpData.OrthoCorner1Y },
-				corner2: { x: tmpData.OrthoCorner2X, y: tmpData.OrthoCorner2Y }
-			};
-		}
-		return pContext.Helpers.generateOrthogonal(pContext.Source, pContext.Target, tmpCorners, tmpData.OrthoMidOffset || 0);
-	},
-
-	ResolveAttachment: function (pContext)
-	{
-		return libPerimeterMath.resolvePerimeterAttachment(pContext);
-	},
-
-	DefaultParameters: {},
-	ParameterSchema: {}
-};

package/source/providers/edges/Edge-Perimeter.js

@@ -1,48 +0,0 @@
-const libPerimeterMath = require('./Edge-PerimeterMath.js');
-
-/**
- * Edge-Perimeter (Bezier)
- *
- * "Smart exit" routing with smooth bezier curves. Each connection
- * exits the node at the perimeter point closest to its target —
- * solves star/hub topologies where many connections share one port.
- *
- * Renders the path as a side-aware bezier (uses the side returned by
- * `ResolveAttachment` so the curve departs in the right direction).
- *
- * See `Edge-Perimeter-Linear` and `Edge-Perimeter-Orthogonal` for the
- * straight-line and right-angle variants.
- */
-module.exports =
-{
-	Name: 'Perimeter',
-	Label: 'Perimeter (bezier)',
-	Description: 'Each connection exits the node at the perimeter point closest to its target, with smooth bezier curves. Fixes star/hub topologies where many lines share one port.',
-
-	GeneratePath: function (pContext)
-	{
-		// Honor user-edited bezier handles when the connection is selected
-		// and dragged. Without this, the drag handles render but moving
-		// them does nothing because Perimeter would always re-emit a
-		// fresh side-aware bezier.
-		let tmpHelpers = pContext.Helpers;
-		let tmpData = (pContext.Connection && pContext.Connection.Data) || {};
-		if (tmpData.HandleCustomized)
-		{
-			let tmpHandles = tmpHelpers.getBezierHandles(tmpData);
-			if (tmpHandles.length > 0)
-			{
-				return tmpHelpers.generateMultiBezier(pContext.Source, pContext.Target, tmpHandles);
-			}
-		}
-		return tmpHelpers.generateBezier(pContext.Source, pContext.Target);
-	},
-
-	ResolveAttachment: function (pContext)
-	{
-		return libPerimeterMath.resolvePerimeterAttachment(pContext);
-	},
-
-	DefaultParameters: {},
-	ParameterSchema: {}
-};

package/source/providers/edges/Edge-PerimeterMath.js

@@ -1,92 +0,0 @@
-/**
- * Edge-PerimeterMath
- *
- * Shared geometry helper for the Perimeter family of edge themes
- * (Perimeter, Perimeter-Linear, Perimeter-Orthogonal). Solves the
- * "where on this node's bounding box should the line attach so it
- * points at the other end" question.
- *
- * The themes themselves only differ in how they render the path
- * between the two attachment points; the attachment math is identical.
- */
-
-/**
- * Resolve a perimeter attachment point for one end of a connection.
- * Traces a line from the node's center toward the other end and returns
- * the first crossing of the node's bounding-box perimeter, plus the
- * `side` of that crossing (so the bezier helper departs in the right
- * direction).
- *
- * @param {Object} pContext - the same shape the renderer passes into
- *        ResolveAttachment (Node, OtherNode, OtherDefaultPosition,
- *        DefaultPosition, …).
- * @returns {{x: number, y: number, side: string}|Object|null}
- *        Returns null when node geometry is missing; returns
- *        DefaultPosition (verbatim) for degenerate same-center cases.
- */
-function _resolvePerimeterAttachment(pContext)
-{
-	let tmpNode = pContext.Node;
-	if (!tmpNode || typeof tmpNode.X !== 'number' || typeof tmpNode.Y !== 'number') return null;
-
-	let tmpW = tmpNode.Width || 180;
-	let tmpH = tmpNode.Height || 80;
-	let tmpCx = tmpNode.X + tmpW / 2;
-	let tmpCy = tmpNode.Y + tmpH / 2;
-
-	let tmpAimX, tmpAimY;
-	if (pContext.OtherNode && typeof pContext.OtherNode.X === 'number')
-	{
-		let tmpOW = pContext.OtherNode.Width || 180;
-		let tmpOH = pContext.OtherNode.Height || 80;
-		tmpAimX = pContext.OtherNode.X + tmpOW / 2;
-		tmpAimY = pContext.OtherNode.Y + tmpOH / 2;
-	}
-	else if (pContext.OtherDefaultPosition)
-	{
-		tmpAimX = pContext.OtherDefaultPosition.x;
-		tmpAimY = pContext.OtherDefaultPosition.y;
-	}
-	else
-	{
-		return null;
-	}
-
-	let tmpDX = tmpAimX - tmpCx;
-	let tmpDY = tmpAimY - tmpCy;
-
-	if (tmpDX === 0 && tmpDY === 0) return pContext.DefaultPosition || null;
-
-	let tmpHalfW = tmpW / 2;
-	let tmpHalfH = tmpH / 2;
-
-	let tmpTX = (tmpDX > 0) ? tmpHalfW / tmpDX
-		: (tmpDX < 0) ? -tmpHalfW / tmpDX
-		: Infinity;
-	let tmpTY = (tmpDY > 0) ? tmpHalfH / tmpDY
-		: (tmpDY < 0) ? -tmpHalfH / tmpDY
-		: Infinity;
-
-	let tmpT, tmpSide;
-	if (tmpTX < tmpTY)
-	{
-		tmpT = tmpTX;
-		tmpSide = (tmpDX > 0) ? 'right' : 'left';
-	}
-	else
-	{
-		tmpT = tmpTY;
-		tmpSide = (tmpDY > 0) ? 'bottom' : 'top';
-	}
-
-	return {
-		x: tmpCx + tmpT * tmpDX,
-		y: tmpCy + tmpT * tmpDY,
-		side: tmpSide
-	};
-}
-
-module.exports =
-{
-	resolvePerimeterAttachment: _resolvePerimeterAttachment
-};

package/source/providers/edges/Edge-Straight.js

@@ -1,24 +0,0 @@
-/**
- * Edge-Straight
- *
- * Literal straight line from source port to target port. Useful for
- * dense clusters where curves add visual noise, and for force-directed
- * layouts where the topology already determines edge angles.
- */
-module.exports =
-{
-	Name: 'Straight',
-	Label: 'Straight line',
-	Description: 'Plain straight line between ports.',
-
-	GeneratePath: function (pContext)
-	{
-		let tmpSrc = pContext.Source;
-		let tmpTgt = pContext.Target;
-		return `M ${tmpSrc.x} ${tmpSrc.y} L ${tmpTgt.x} ${tmpTgt.y}`;
-	},
-
-	DefaultParameters: {},
-
-	ParameterSchema: {}
-};