pict-section-flow 0.0.1 → 0.0.2

package/source/PictFlowCard.js

@@ -0,0 +1,207 @@
+const libFableServiceProviderBase = require('fable-serviceproviderbase');
+
+/**
+ * PictFlowCard - Base class for flow diagram cards.
+ *
+ * Developers create subclasses of PictFlowCard to define reusable node types
+ * that appear in the flow palette. Each card describes a discrete operation
+ * (e.g. "If-Then-Else", "File Read") with configurable inputs, outputs, and
+ * metadata. Pict-Section-Flow uses registered cards to build a palette for
+ * the user to drag onto the graph.
+ *
+ * Configurable properties:
+ *   - Title          (string, required) - Display name shown on the node
+ *   - Name           (string, optional) - Longer descriptive name
+ *   - Code           (string, required) - Short identifier (e.g. "ITE", "SW")
+ *   - Description    (string, optional) - Brief explanation of what the card does
+ *   - Icon           (string, optional) - Icon identifier or emoji
+ *   - PreviewImage   (string, optional) - URL to a preview/thumbnail image
+ *   - Documentation  (string, optional) - URL or inline documentation text
+ *   - Tooltip        (string, optional) - Hover tooltip text
+ *   - Inputs         (array)  - Named input ports, each with:
+ *       - Name                 (string)  - Port label
+ *       - Side                 (string)  - Port side ('left', 'top', etc.)
+ *       - MinimumInputCount    (number)  - Minimum connections accepted (default 0)
+ *       - MaximumInputCount    (number)  - Maximum connections accepted (default -1, unlimited)
+ *   - Outputs        (array)  - Named output ports
+ *   - Enabled        (boolean) - Whether this card is available in the palette
+ *   - PropertiesPanel (object, optional) - Configuration for the on-graph properties panel
+ *       - PanelType      (string)  - 'Template', 'Markdown', 'Form', or 'View'
+ *       - DefaultWidth   (number)  - Panel width (default 300)
+ *       - DefaultHeight  (number)  - Panel height (default 200)
+ *       - Title          (string)  - Panel title bar text
+ *       - Configuration  (object)  - Panel-type-specific configuration
+ *
+ * Usage:
+ *   class MyCard extends PictFlowCard {
+ *     constructor(pFable, pOptions, pServiceHash) {
+ *       super(pFable, pOptions, pServiceHash);
+ *       this.cardTitle = 'My Card';
+ *       this.cardCode = 'MC';
+ *       this.cardInputs = [{ Name: 'Data', Side: 'left', MinimumInputCount: 1, MaximumInputCount: 1 }];
+ *       this.cardOutputs = [{ Name: 'Result', Side: 'right' }];
+ *     }
+ *   }
+ */
+class PictFlowCard extends libFableServiceProviderBase
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		let tmpOptions = Object.assign({}, PictFlowCard.default_configuration, pOptions);
+		super(pFable, tmpOptions, pServiceHash);
+
+		this.serviceType = 'PictFlowCard';
+
+		// --- Card metadata ---
+		this.cardTitle = (tmpOptions.Title) ? tmpOptions.Title : 'Card';
+		this.cardName = (tmpOptions.Name) ? tmpOptions.Name : false;
+		this.cardCode = (tmpOptions.Code) ? tmpOptions.Code : '';
+		this.cardDescription = (tmpOptions.Description) ? tmpOptions.Description : false;
+		this.cardIcon = (tmpOptions.Icon) ? tmpOptions.Icon : false;
+		this.cardPreviewImage = (tmpOptions.PreviewImage) ? tmpOptions.PreviewImage : false;
+		this.cardDocumentation = (tmpOptions.Documentation) ? tmpOptions.Documentation : false;
+		this.cardTooltip = (tmpOptions.Tooltip) ? tmpOptions.Tooltip : false;
+
+		// --- Card enabled state ---
+		this.cardEnabled = (typeof tmpOptions.Enabled === 'boolean') ? tmpOptions.Enabled : true;
+
+		// --- Card appearance ---
+		this.cardTitleBarColor = (tmpOptions.TitleBarColor) ? tmpOptions.TitleBarColor : '#2c3e50';
+		this.cardBodyStyle = (tmpOptions.BodyStyle) ? tmpOptions.BodyStyle : {};
+		this.cardWidth = (typeof tmpOptions.Width === 'number') ? tmpOptions.Width : 180;
+		this.cardHeight = (typeof tmpOptions.Height === 'number') ? tmpOptions.Height : 80;
+		this.cardCategory = (tmpOptions.Category) ? tmpOptions.Category : 'General';
+
+		// --- Input and Output port definitions ---
+		// Inputs: [{ Name: 'In', Side: 'left', MinimumInputCount: 0, MaximumInputCount: -1 }]
+		// Outputs: [{ Name: 'Out', Side: 'right' }]
+		this.cardInputs = Array.isArray(tmpOptions.Inputs) ? tmpOptions.Inputs : [];
+		this.cardOutputs = Array.isArray(tmpOptions.Outputs) ? tmpOptions.Outputs : [];
+
+		// --- Properties panel configuration ---
+		this.cardPropertiesPanel = (tmpOptions.PropertiesPanel && typeof tmpOptions.PropertiesPanel === 'object')
+			? tmpOptions.PropertiesPanel
+			: null;
+	}
+
+	/**
+	 * Generate the node type configuration object for the NodeTypes provider.
+	 * This converts the card's properties into the format expected by
+	 * PictProviderFlowNodeTypes.registerNodeType().
+	 *
+	 * @returns {Object} Node type configuration
+	 */
+	getNodeTypeConfiguration()
+	{
+		let tmpPorts = [];
+
+		// Build input ports
+		for (let i = 0; i < this.cardInputs.length; i++)
+		{
+			let tmpInput = this.cardInputs[i];
+			let tmpPort =
+				{
+					Hash: null,
+					Direction: 'input',
+					Side: tmpInput.Side || 'left',
+					Label: tmpInput.Name || `In ${i + 1}`,
+					MinimumInputCount: (typeof tmpInput.MinimumInputCount === 'number') ? tmpInput.MinimumInputCount : 0,
+					MaximumInputCount: (typeof tmpInput.MaximumInputCount === 'number') ? tmpInput.MaximumInputCount : -1
+				};
+			tmpPorts.push(tmpPort);
+		}
+
+		// Build output ports
+		for (let i = 0; i < this.cardOutputs.length; i++)
+		{
+			let tmpOutput = this.cardOutputs[i];
+			tmpPorts.push(
+				{
+					Hash: null,
+					Direction: 'output',
+					Side: tmpOutput.Side || 'right',
+					Label: tmpOutput.Name || `Out ${i + 1}`
+				});
+		}
+
+		// If no ports were defined, provide sensible defaults
+		if (tmpPorts.length === 0)
+		{
+			tmpPorts.push({ Hash: null, Direction: 'input', Side: 'left', Label: 'In' });
+			tmpPorts.push({ Hash: null, Direction: 'output', Side: 'right', Label: 'Out' });
+		}
+
+		let tmpResult =
+		{
+			Hash: this.cardCode,
+			Label: this.cardTitle,
+			DefaultWidth: this.cardWidth,
+			DefaultHeight: this.cardHeight,
+			DefaultPorts: tmpPorts,
+			TitleBarColor: this.cardTitleBarColor,
+			BodyStyle: JSON.parse(JSON.stringify(this.cardBodyStyle)),
+			// Extended FlowCard metadata stored alongside the type
+			CardMetadata:
+			{
+				Name: this.cardName,
+				Code: this.cardCode,
+				Description: this.cardDescription,
+				Icon: this.cardIcon,
+				PreviewImage: this.cardPreviewImage,
+				Documentation: this.cardDocumentation,
+				Tooltip: this.cardTooltip,
+				Enabled: this.cardEnabled,
+				Category: this.cardCategory
+			}
+		};
+
+		// Include properties panel config if defined
+		if (this.cardPropertiesPanel)
+		{
+			tmpResult.PropertiesPanel = JSON.parse(JSON.stringify(this.cardPropertiesPanel));
+		}
+
+		return tmpResult;
+	}
+
+	/**
+	 * Register this card with a FlowView's node type provider.
+	 *
+	 * @param {Object} pFlowView - The PictViewFlow instance
+	 * @returns {boolean} Whether registration succeeded
+	 */
+	registerWithFlowView(pFlowView)
+	{
+		if (!pFlowView || !pFlowView._NodeTypeProvider)
+		{
+			this.log.warn('PictFlowCard registerWithFlowView: no valid FlowView or NodeTypeProvider');
+			return false;
+		}
+
+		let tmpConfig = this.getNodeTypeConfiguration();
+		return pFlowView._NodeTypeProvider.registerNodeType(tmpConfig);
+	}
+}
+
+module.exports = PictFlowCard;
+
+module.exports.default_configuration =
+{
+	Title: 'Card',
+	Name: false,
+	Code: '',
+	Description: false,
+	Icon: false,
+	PreviewImage: false,
+	Documentation: false,
+	Tooltip: false,
+	Inputs: [],
+	Outputs: [],
+	Enabled: true,
+	TitleBarColor: '#2c3e50',
+	BodyStyle: {},
+	Width: 180,
+	Height: 80,
+	Category: 'General',
+	PropertiesPanel: null
+};

package/source/PictFlowCardPropertiesPanel.js

@@ -0,0 +1,105 @@
+const libFableServiceProviderBase = require('fable-serviceproviderbase');
+
+/**
+ * PictFlowCardPropertiesPanel - Base class for flow card property panels.
+ *
+ * Developers create subclasses to define what UI appears when a user opens
+ * the properties panel for a node on the flow graph. Four built-in panel
+ * types are provided:
+ *
+ *   - Template  - Renders pict templates
+ *   - Markdown  - Renders markdown via pict-section-content
+ *   - Form      - Creates an ephemeral pict-section-form section
+ *   - View      - Renders an existing registered pict-view
+ *
+ * Configurable properties:
+ *   - PanelType      (string)  - Panel type identifier
+ *   - Title          (string)  - Panel title bar text
+ *   - Width          (number)  - Default panel width in pixels
+ *   - Height         (number)  - Default panel height in pixels
+ *   - Configuration  (object)  - Panel-type-specific configuration
+ */
+class PictFlowCardPropertiesPanel extends libFableServiceProviderBase
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		let tmpOptions = Object.assign({}, PictFlowCardPropertiesPanel.default_configuration, pOptions);
+		super(pFable, tmpOptions, pServiceHash);
+
+		this.serviceType = 'PictFlowCardPropertiesPanel';
+
+		// Panel metadata
+		this.panelType = tmpOptions.PanelType || 'Base';
+		this.panelTitle = tmpOptions.Title || 'Properties';
+		this.panelWidth = (typeof tmpOptions.Width === 'number') ? tmpOptions.Width : 300;
+		this.panelHeight = (typeof tmpOptions.Height === 'number') ? tmpOptions.Height : 200;
+
+		// Reference to the flow view (set when panel is activated)
+		this._FlowView = null;
+
+		// The node data this panel is operating on (set when panel is opened)
+		this._NodeData = null;
+
+		// The DOM container element for panel content (set during render)
+		this._ContentContainer = null;
+
+		// The panel configuration (panel-type-specific)
+		this._Configuration = tmpOptions.Configuration || {};
+	}
+
+	/**
+	 * Render the panel's content into a DOM container element.
+	 * Subclasses MUST override this.
+	 *
+	 * @param {HTMLElement} pContainer - The DOM element to render into
+	 * @param {Object} pNodeData - The node data object (has .Data property)
+	 */
+	render(pContainer, pNodeData)
+	{
+		this._ContentContainer = pContainer;
+		this._NodeData = pNodeData;
+	}
+
+	/**
+	 * Marshal data FROM the node's Data object INTO the panel UI.
+	 * Called when the panel opens or when data changes externally.
+	 *
+	 * @param {Object} pNodeData
+	 */
+	marshalToPanel(pNodeData)
+	{
+		this._NodeData = pNodeData;
+	}
+
+	/**
+	 * Marshal data FROM the panel UI INTO the node's Data object.
+	 * Called before saving or when the panel is about to close.
+	 *
+	 * @param {Object} pNodeData
+	 */
+	marshalFromPanel(pNodeData)
+	{
+		// Subclasses override
+	}
+
+	/**
+	 * Called when the panel is being destroyed (closed).
+	 * Subclasses should clean up resources.
+	 */
+	destroy()
+	{
+		this._ContentContainer = null;
+		this._NodeData = null;
+	}
+}
+
+module.exports = PictFlowCardPropertiesPanel;
+
+module.exports.default_configuration =
+{
+	PanelType: 'Base',
+	Title: 'Properties',
+	Width: 300,
+	Height: 200,
+	Configuration: {}
+};

package/source/panels/FlowCardPropertiesPanel-Form.js

@@ -0,0 +1,174 @@
+const libPictFlowCardPropertiesPanel = require('../PictFlowCardPropertiesPanel.js');
+
+/**
+ * FlowCardPropertiesPanel-Form
+ *
+ * Creates an ephemeral pict-section-form section to edit the node's Data object.
+ * Uses PictViewFormMetacontroller.injectManifest() to dynamically create form
+ * sections at runtime.
+ *
+ * Note: pict-section-form must be available in the consuming application
+ * (it is an optional/peer dependency, not bundled with pict-section-flow).
+ *
+ * Configuration:
+ *   {
+ *     PanelType: 'Form',
+ *     Configuration: {
+ *       Manifest: {
+ *         Sections: [...],
+ *         Descriptors: {...}
+ *       }
+ *     }
+ *   }
+ */
+class FlowCardPropertiesPanelForm extends libPictFlowCardPropertiesPanel
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+
+		this.serviceType = 'PictFlowCardPropertiesPanel-Form';
+
+		this._Metacontroller = null;
+		this._InjectedSectionHash = null;
+	}
+
+	/**
+	 * Render the form into the panel body.
+	 */
+	render(pContainer, pNodeData)
+	{
+		super.render(pContainer, pNodeData);
+
+		if (!this._Configuration || !this._Configuration.Manifest)
+		{
+			pContainer.innerHTML = '<em>No form manifest configured</em>';
+			return;
+		}
+
+		// Create a unique container ID for the form section
+		let tmpContainerID = `pict-flow-panel-form-${pNodeData.Hash}`;
+		pContainer.innerHTML = `<div id="${tmpContainerID}"></div>`;
+
+		try
+		{
+			// Look for an existing metacontroller or create one
+			if (!this._Metacontroller)
+			{
+				// Try to find PictFormMetacontroller service type (check both common names)
+				let tmpServiceType = null;
+				if (this.fable.servicesMap.hasOwnProperty('PictFormMetacontroller'))
+				{
+					tmpServiceType = 'PictFormMetacontroller';
+				}
+				else if (this.fable.servicesMap.hasOwnProperty('PictViewFormMetacontroller'))
+				{
+					tmpServiceType = 'PictViewFormMetacontroller';
+				}
+
+				if (tmpServiceType)
+				{
+					this._Metacontroller = this.fable.instantiateServiceProviderWithoutRegistration(tmpServiceType,
+						{
+							ViewIdentifier: `FlowPanelForm-${pNodeData.Hash}`,
+							DefaultDestinationAddress: `#${tmpContainerID}`,
+							AutoRender: false,
+							AutoPopulateAfterRender: true,
+							AutoSolveBeforeRender: false
+						});
+				}
+			}
+
+			if (this._Metacontroller && typeof this._Metacontroller.injectManifestAndRender === 'function')
+			{
+				// Create the FormContainer div that the metacontroller's
+				// updateMetatemplateInDOM() expects when adding section wrappers.
+				// Normally this is created when the metacontroller renders its own
+				// metatemplate, but we skip that step since we only need the
+				// injected section views, not the metacontroller's own renderable.
+				let tmpFormContainerID = `Pict-${this._Metacontroller.UUID}-FormContainer`;
+				let tmpContainerEl = pContainer.querySelector(`#${tmpContainerID}`);
+				if (tmpContainerEl)
+				{
+					tmpContainerEl.innerHTML = `<div id="${tmpFormContainerID}" class="pict-form"></div>`;
+				}
+
+				// Deep clone the manifest so each panel gets its own copy
+				let tmpManifest = JSON.parse(JSON.stringify(this._Configuration.Manifest));
+				this._InjectedSectionHash = tmpManifest.Hash || null;
+
+				// Use injectManifestAndRender which properly creates section views,
+				// updates the metatemplate in the DOM, and renders each section view
+				this._Metacontroller.injectManifestAndRender(tmpManifest);
+			}
+			else if (this._Metacontroller && typeof this._Metacontroller.injectManifest === 'function')
+			{
+				// Fallback for older pict-section-form versions: inject the
+				// manifest and render each section view individually
+				let tmpManifest = JSON.parse(JSON.stringify(this._Configuration.Manifest));
+				let tmpViewsToRender = this._Metacontroller.injectManifest(tmpManifest);
+				this._InjectedSectionHash = tmpManifest.Hash || null;
+
+				// Create container divs for each section view and render them
+				let tmpContainerEl = pContainer.querySelector(`#${tmpContainerID}`);
+				if (tmpContainerEl && tmpViewsToRender.length > 0)
+				{
+					let tmpInnerHTML = '';
+					for (let i = 0; i < tmpViewsToRender.length; i++)
+					{
+						let tmpDestID = tmpViewsToRender[i].options.DefaultDestinationAddress;
+						if (tmpDestID && tmpDestID.charAt(0) === '#')
+						{
+							tmpDestID = tmpDestID.substring(1);
+						}
+						tmpInnerHTML += `<div id="${tmpDestID}" class="pict-form-view"></div>`;
+					}
+					tmpContainerEl.innerHTML = tmpInnerHTML;
+
+					for (let i = 0; i < tmpViewsToRender.length; i++)
+					{
+						tmpViewsToRender[i].render();
+					}
+				}
+			}
+			else
+			{
+				pContainer.innerHTML = '<em>pict-section-form is not available. Install it in your application to use Form panels.</em>';
+			}
+		}
+		catch (pError)
+		{
+			this.log.warn(`FlowCardPropertiesPanel-Form render error: ${pError.message}`);
+			pContainer.innerHTML = `<em>Form render error: ${pError.message}</em>`;
+		}
+	}
+
+	marshalFromPanel(pNodeData)
+	{
+		if (this._Metacontroller && typeof this._Metacontroller.marshalFromView === 'function')
+		{
+			this._Metacontroller.marshalFromView();
+		}
+	}
+
+	destroy()
+	{
+		this._Metacontroller = null;
+		this._InjectedSectionHash = null;
+		super.destroy();
+	}
+}
+
+module.exports = FlowCardPropertiesPanelForm;
+
+module.exports.default_configuration = Object.assign(
+	{},
+	libPictFlowCardPropertiesPanel.default_configuration,
+	{
+		PanelType: 'Form',
+		Configuration:
+		{
+			Manifest: null
+		}
+	}
+);

package/source/panels/FlowCardPropertiesPanel-Markdown.js

@@ -0,0 +1,148 @@
+const libPictFlowCardPropertiesPanel = require('../PictFlowCardPropertiesPanel.js');
+
+/**
+ * FlowCardPropertiesPanel-Markdown
+ *
+ * Renders markdown content into the panel body using pict-section-content's
+ * PictContentProvider service.  When pict-section-content is installed and its
+ * PictContentProvider service type has been registered with the pict instance,
+ * full markdown rendering is available (headings, lists, tables, code blocks
+ * with syntax highlighting, KaTeX equations, Mermaid diagrams, etc.).
+ *
+ * If PictContentProvider is not available, the panel falls back to displaying
+ * the raw markdown as pre-formatted text.
+ *
+ * Configuration:
+ *   {
+ *     PanelType: 'Markdown',
+ *     Configuration: {
+ *       Markdown: '# Title\nSome **markdown** content'
+ *     }
+ *   }
+ *
+ * Or use an address to pull markdown from the node's data:
+ *   {
+ *     PanelType: 'Markdown',
+ *     Configuration: {
+ *       MarkdownAddress: 'Data.MarkdownContent'
+ *     }
+ *   }
+ */
+class FlowCardPropertiesPanelMarkdown extends libPictFlowCardPropertiesPanel
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+
+		this.serviceType = 'PictFlowCardPropertiesPanel-Markdown';
+
+		this._ContentProvider = null;
+	}
+
+	/**
+	 * Render markdown into the panel.
+	 */
+	render(pContainer, pNodeData)
+	{
+		super.render(pContainer, pNodeData);
+
+		this._renderMarkdown();
+	}
+
+	marshalToPanel(pNodeData)
+	{
+		super.marshalToPanel(pNodeData);
+		this._renderMarkdown();
+	}
+
+	_renderMarkdown()
+	{
+		if (!this._ContentContainer || !this._Configuration) return;
+
+		let tmpMarkdown = '';
+
+		if (this._Configuration.MarkdownAddress && this._NodeData)
+		{
+			// Resolve markdown from node data using manyfest
+			tmpMarkdown = this.fable.manifest.getValueByHash(this._NodeData, this._Configuration.MarkdownAddress) || '';
+		}
+		else if (this._Configuration.Markdown)
+		{
+			tmpMarkdown = this._Configuration.Markdown;
+		}
+
+		if (!tmpMarkdown)
+		{
+			this._ContentContainer.innerHTML = '<em>No content</em>';
+			return;
+		}
+
+		// Use pict-section-content's PictContentProvider for markdown rendering.
+		// The consuming application must register the PictContentProvider service
+		// type (from pict-section-content) for this to work.
+		try
+		{
+			if (!this._ContentProvider)
+			{
+				if (this.fable.servicesMap.hasOwnProperty('PictContentProvider'))
+				{
+					this._ContentProvider = this.fable.instantiateServiceProviderWithoutRegistration('PictContentProvider', {});
+				}
+			}
+
+			if (this._ContentProvider && typeof this._ContentProvider.parseMarkdown === 'function')
+			{
+				let tmpHTML = this._ContentProvider.parseMarkdown(tmpMarkdown);
+				this._ContentContainer.innerHTML = tmpHTML;
+
+				// Post-render hooks for equations and diagrams
+				if (typeof this._ContentProvider.renderKaTeXEquations === 'function')
+				{
+					this._ContentProvider.renderKaTeXEquations(this._ContentContainer);
+				}
+				if (typeof this._ContentProvider.renderMermaidDiagrams === 'function')
+				{
+					this._ContentProvider.renderMermaidDiagrams(this._ContentContainer);
+				}
+			}
+			else
+			{
+				// PictContentProvider not registered — render as pre-formatted text
+				this._ContentContainer.innerHTML = `<pre style="white-space: pre-wrap; font-family: inherit;">${this._escapeHTML(tmpMarkdown)}</pre>`;
+			}
+		}
+		catch (pError)
+		{
+			this.log.warn(`FlowCardPropertiesPanel-Markdown render error: ${pError.message}`);
+			this._ContentContainer.innerHTML = `<pre style="white-space: pre-wrap; font-family: inherit;">${this._escapeHTML(tmpMarkdown)}</pre>`;
+		}
+	}
+
+	_escapeHTML(pText)
+	{
+		let tmpDiv = document.createElement('div');
+		tmpDiv.textContent = pText;
+		return tmpDiv.innerHTML;
+	}
+
+	destroy()
+	{
+		this._ContentProvider = null;
+		super.destroy();
+	}
+}
+
+module.exports = FlowCardPropertiesPanelMarkdown;
+
+module.exports.default_configuration = Object.assign(
+	{},
+	libPictFlowCardPropertiesPanel.default_configuration,
+	{
+		PanelType: 'Markdown',
+		Configuration:
+		{
+			Markdown: '',
+			MarkdownAddress: ''
+		}
+	}
+);