pict-section-formeditor 1.0.0

package/source/Pict-Section-FormEditor.js

@@ -0,0 +1,35 @@
+// Pict Section: Form Editor
+// A visual editor for pict-section-form configuration manifests.
+
+// The main form editor view class
+module.exports = require('./views/PictView-FormEditor.js');
+
+// Default configuration
+module.exports.default_configuration = require('./Pict-Section-FormEditor-DefaultConfiguration.js');
+
+// Iconography provider for SVG icons
+module.exports.IconographyProvider = require('./providers/Pict-Provider-FormEditorIconography.js');
+
+// Rendering provider for visual editor HTML generation
+module.exports.RenderingProvider = require('./providers/Pict-Provider-FormEditorRendering.js');
+
+// Manifest operations provider for CRUD operations
+module.exports.ManifestOpsProvider = require('./providers/Pict-Provider-FormEditorManifestOps.js');
+
+// Drag-and-drop provider
+module.exports.DragDropProvider = require('./providers/Pict-Provider-FormEditorDragDrop.js');
+
+// Utilities provider for string helpers, InputType definitions, selection, and stats
+module.exports.UtilitiesProvider = require('./providers/Pict-Provider-FormEditorUtilities.js');
+
+// Properties panel view
+module.exports.PropertiesPanel = require('./views/PictView-FormEditor-PropertiesPanel.js');
+
+// Inline editing view
+module.exports.InlineEditing = require('./views/PictView-FormEditor-InlineEditing.js');
+
+// Input type picker view
+module.exports.InputTypePicker = require('./views/PictView-FormEditor-InputTypePicker.js');
+
+// Documentation provider for embedded help system
+module.exports.DocumentationProvider = require('./providers/Pict-Provider-FormEditorDocumentation.js');

package/source/providers/Pict-Provider-ChildPictManager-Application.js

@@ -0,0 +1,40 @@
+const libPictSectionForm = require('pict-section-form');
+
+class ChildPictApplication extends libPictSectionForm.PictFormApplication
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+
+		// Trying this pattern -- it seems to make the most sense.
+		// MainViewportViewIdentifier: 'Default-View',
+		// MainViewportRenderableHash: false,
+		// MainViewportDestinationAddress: false,
+		// MainViewportDefaultDataAddress: false,
+
+		this.options.AutoSolveAfterInitialize = false;
+		this.options.AutoRenderMainViewportViewAfterInitialize = false;
+		this.options.AutoRenderViewsAfterInitialize = false;
+		this.options.AutoLoginAfterInitialize = false;
+		this.options.AutoLoadDataAfterLogin = false;
+	}
+
+	onBeforeInitialize()
+	{
+		this.log.trace(`Initializing embedded application.`);
+		return super.onBeforeInitialize();
+	}
+
+	onAfterInitialize()
+	{
+		this.log.trace(`Finished initializing embedded application.`);
+		return super.onAfterInitialize();
+	}
+
+	onAfterRender()
+	{
+		return super.onAfterRender();
+	}
+}
+
+module.exports = ChildPictApplication;

package/source/providers/Pict-Provider-ChildPictManager.js

@@ -0,0 +1,238 @@
+const libPictProvider = require('pict-provider');
+
+const libPict = require('pict');
+const libPictCustomApplication = require('./Pict-Provider-ChildPictManager-Application.js');
+
+class ChildPictManager extends libPictProvider
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+
+		this.serviceType = 'PictProvider';
+
+		// The cache location for other instances of pict
+		this._PictCache = {};
+	}
+
+	// Check if a pict instance exists for this cache
+	childApplicationExists(pFormHash)
+	{
+		const tmpFormHash = this.fable.DataFormat.sanitizeObjectKey(pFormHash);
+
+		if (this._PictCache[tmpFormHash])
+		{
+			return true;
+		}
+
+		return false;
+	}
+
+	childApplication(pFormHash)
+	{
+		const tmpFormHash = this.fable.DataFormat.sanitizeObjectKey(pFormHash);
+
+		if (this.childApplicationExists(tmpFormHash))
+		{
+			return this._PictCache[tmpFormHash];
+		}
+
+		return null;
+	}
+
+	/**
+	 * Destroy and remove a cached child application.
+	 * Cleans up the child pict's views, providers, and application so
+	 * nothing leaks between successive preview loads.
+	 *
+	 * @param {string} pFormHash - The form hash key for the cached application
+	 */
+	destroyChildApplication(pFormHash)
+	{
+		const tmpFormHash = this.fable.DataFormat.sanitizeObjectKey(pFormHash);
+
+		let tmpChildPict = this._PictCache[tmpFormHash];
+		if (!tmpChildPict)
+		{
+			return;
+		}
+
+		// Tear down all views registered on the child pict
+		let tmpViewKeys = Object.keys(tmpChildPict.views);
+		for (let i = 0; i < tmpViewKeys.length; i++)
+		{
+			try
+			{
+				let tmpView = tmpChildPict.views[tmpViewKeys[i]];
+				if (tmpView && typeof tmpView.destroy === 'function')
+				{
+					tmpView.destroy();
+				}
+			}
+			catch (pError)
+			{
+				this.log.warn('Error destroying child pict view [' + tmpViewKeys[i] + ']: ' + pError);
+			}
+		}
+
+		// Remove the application reference
+		if (tmpChildPict.PictApplication)
+		{
+			try
+			{
+				if (typeof tmpChildPict.PictApplication.destroy === 'function')
+				{
+					tmpChildPict.PictApplication.destroy();
+				}
+			}
+			catch (pError)
+			{
+				this.log.warn('Error destroying child pict application: ' + pError);
+			}
+		}
+
+		delete this._PictCache[tmpFormHash];
+	}
+
+	// Initialize a new child application
+	initializeChildApplication(pFormHash, pPictSectionFormManifest)
+	{
+		const tmpFormHash = this.fable.DataFormat.sanitizeObjectKey(pFormHash);
+
+		try
+		{
+			// Construct a new pict instance
+			const tmpChildPictSettings =
+				{
+					Product: `Form-${tmpFormHash}`,
+					ProductVersion: '1.0.0',
+					DefaultFormManifest: pPictSectionFormManifest
+				};
+
+			let tmpChildPict = new libPict(tmpChildPictSettings);
+
+			this._PictCache[tmpFormHash] = tmpChildPict;
+
+			tmpChildPict.addApplication(tmpFormHash, {}, libPictCustomApplication);
+
+			tmpChildPict.PictApplication.initializeAsync(
+				function (pError)
+				{
+					if (pError)
+					{
+						console.log('Error initializing the pict application: ' + pError);
+					}
+					tmpChildPict.log.info('Loading the Application and associated views.');
+				});
+
+			// NOTICE: This application is initializing async
+			return tmpChildPict;
+		}
+		catch (pError)
+		{
+			this.log.error(`Error initializing child pict application for form ${pFormHash}: ${pError}`);
+			return null;
+		}
+	}
+
+	/**
+	 * Initialize a child application configured for browser rendering.
+	 * Sets BrowserAddress so the child pict is available on the window
+	 * and {~P~} template expressions resolve correctly.
+	 *
+	 * @param {string} pFormHash - Cache key for the child application
+	 * @param {Object} pPictSectionFormManifest - The form manifest (DefaultFormManifest)
+	 * @param {string} pBrowserAddress - The global window address (e.g. 'window._ChildPict')
+	 * @param {string} pDestinationSelector - CSS selector for the render target (e.g. '#Preview-Container')
+	 * @param {Function} fCallback - Called with (pError, pChildPict) when initialization completes
+	 */
+	initializeRenderableChildApplication(pFormHash, pPictSectionFormManifest, pBrowserAddress, pDestinationSelector, fCallback)
+	{
+		const tmpFormHash = this.fable.DataFormat.sanitizeObjectKey(pFormHash);
+
+		try
+		{
+			// Destroy any previous instance with this hash
+			this.destroyChildApplication(tmpFormHash);
+
+			// Clean up previous global reference if it exists
+			if (typeof window !== 'undefined' && pBrowserAddress)
+			{
+				let tmpAddressParts = pBrowserAddress.split('.');
+				if (tmpAddressParts.length === 2 && tmpAddressParts[0] === 'window')
+				{
+					delete window[tmpAddressParts[1]];
+				}
+			}
+
+			// Construct a new pict instance with BrowserAddress
+			const tmpChildPictSettings =
+				{
+					Product: `FormPreview-${tmpFormHash}`,
+					ProductVersion: '1.0.0',
+					BrowserAddress: pBrowserAddress || 'window._ChildPict',
+					DefaultFormManifest: pPictSectionFormManifest
+				};
+
+			let tmpChildPict = new libPict(tmpChildPictSettings);
+
+			// Disable CSS injection on the child pict so it does not
+			// overwrite the parent's #PICT-CSS style element.
+			// The parent already has all pict-section-form CSS loaded.
+			if (tmpChildPict.CSSMap)
+			{
+				tmpChildPict.CSSMap.injectCSS = function() {};
+			}
+
+			this._PictCache[tmpFormHash] = tmpChildPict;
+
+			// Set the global reference so {~P~} expressions resolve
+			if (typeof window !== 'undefined' && pBrowserAddress)
+			{
+				let tmpAddressParts = pBrowserAddress.split('.');
+				if (tmpAddressParts.length === 2 && tmpAddressParts[0] === 'window')
+				{
+					window[tmpAddressParts[1]] = tmpChildPict;
+				}
+			}
+
+			// Configure the application to render into the target container
+			let tmpAppOptions =
+				{
+					MainViewportDestinationAddress: pDestinationSelector,
+					AutoPopulateAfterRender: true
+				};
+
+			tmpChildPict.addApplication(tmpFormHash, tmpAppOptions, libPictCustomApplication);
+
+			let tmpSelf = this;
+			tmpChildPict.PictApplication.initializeAsync(
+				function (pError)
+				{
+					if (pError)
+					{
+						tmpSelf.log.error('Error initializing renderable child pict application: ' + pError);
+					}
+					if (typeof fCallback === 'function')
+					{
+						fCallback(pError, tmpChildPict);
+					}
+				});
+
+			return tmpChildPict;
+		}
+		catch (pError)
+		{
+			this.log.error(`Error initializing renderable child pict application for form ${pFormHash}: ${pError}`);
+			if (typeof fCallback === 'function')
+			{
+				fCallback(pError, null);
+			}
+			return null;
+		}
+	}
+
+}
+
+module.exports = ChildPictManager;
+module.exports.default_configuration = {};

package/source/providers/Pict-Provider-FormEditorDocumentation.js

@@ -0,0 +1,356 @@
+const libPictProvider = require('pict-provider');
+
+/**
+ * Documentation Provider for the Form Editor.
+ *
+ * Manages fetching, caching, and navigation of markdown help articles.
+ * Delegates markdown parsing to PictContentProvider and HTML rendering
+ * to PictContentView (both from pict-section-content).
+ *
+ * By default loads articles from relative file paths (e.g. docs/ToC.md).
+ * Can be extended to use custom REST endpoints by overriding loadArticle().
+ */
+class FormEditorDocumentation extends libPictProvider
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+
+		this.serviceType = 'PictProvider';
+
+		// Back-reference to the parent FormEditor view (set after construction)
+		this._ParentFormEditor = null;
+
+		// Navigation state
+		this._NavigationStack = [];
+		this._CurrentPath = null;
+		this._CurrentTitle = 'Help';
+
+		// Base path for documentation files (relative to the served app)
+		this._BasePath = 'docs/';
+
+		// Cache of parsed HTML keyed by path
+		this._Cache = {};
+
+		// Whether the click handler has been wired on the help body container
+		this._ClickHandlerAttached = false;
+	}
+
+	/**
+	 * Load and display a documentation article.
+	 *
+	 * Fetches the markdown file, parses it via PictContentProvider, and
+	 * renders the HTML via PictContentView.displayContent().
+	 *
+	 * @param {string} pPath - Path to the markdown file (e.g. 'docs/ToC.md')
+	 * @param {boolean} pPushToStack - If true, push the current article onto the navigation stack before navigating
+	 */
+	loadArticle(pPath, pPushToStack)
+	{
+		if (!pPath)
+		{
+			pPath = this._BasePath + 'ToC.md';
+		}
+
+		if (!this._ParentFormEditor)
+		{
+			return;
+		}
+
+		// Push current location onto the stack before navigating
+		if (pPushToStack && this._CurrentPath)
+		{
+			this._NavigationStack.push(
+			{
+				path: this._CurrentPath,
+				title: this._CurrentTitle
+			});
+		}
+
+		this._CurrentPath = pPath;
+
+		// If cached, render immediately
+		if (this._Cache[pPath])
+		{
+			this._renderArticle(this._Cache[pPath].html, this._Cache[pPath].title);
+			return;
+		}
+
+		// Show loading state
+		let tmpContentView = this._ParentFormEditor._HelpContentView;
+		if (tmpContentView && typeof tmpContentView.showLoading === 'function')
+		{
+			let tmpBodyId = 'Pict-Content-Body';
+			tmpContentView.showLoading('Loading article...', tmpBodyId);
+		}
+
+		// Fetch the markdown file
+		let tmpXHR = new XMLHttpRequest();
+		tmpXHR.open('GET', pPath, true);
+		tmpXHR.onreadystatechange = () =>
+		{
+			if (tmpXHR.readyState === 4)
+			{
+				if (tmpXHR.status === 200)
+				{
+					let tmpMarkdown = tmpXHR.responseText;
+					let tmpTitle = this._extractTitle(tmpMarkdown);
+					let tmpContentProvider = this._ParentFormEditor._HelpContentProvider;
+
+					if (tmpContentProvider)
+					{
+						let tmpLinkResolver = (pHref, pLinkText) =>
+						{
+							return this._linkResolver(pHref, pLinkText);
+						};
+						let tmpHTML = tmpContentProvider.parseMarkdown(tmpMarkdown, tmpLinkResolver);
+
+						// Cache the result
+						this._Cache[pPath] = { html: tmpHTML, title: tmpTitle };
+
+						this._renderArticle(tmpHTML, tmpTitle);
+					}
+				}
+				else
+				{
+					this._renderError(pPath, tmpXHR.status);
+				}
+			}
+		};
+		tmpXHR.send();
+	}
+
+	/**
+	 * Navigate back to the previous article.
+	 */
+	navigateBack()
+	{
+		if (this._NavigationStack.length < 1)
+		{
+			return;
+		}
+
+		let tmpPrevious = this._NavigationStack.pop();
+		this.loadArticle(tmpPrevious.path, false);
+	}
+
+	/**
+	 * Navigate to the table of contents.
+	 */
+	navigateHome()
+	{
+		// Clear the stack and go home
+		this._NavigationStack = [];
+		this.loadArticle(this._BasePath + 'ToC.md', false);
+	}
+
+	/**
+	 * Custom link resolver for parseMarkdown().
+	 *
+	 * Intercepts links to .md files and converts them to in-panel navigation.
+	 * External links open in a new tab.
+	 *
+	 * @param {string} pHref - The href from the markdown link
+	 * @param {string} pLinkText - The display text of the link
+	 * @returns {object|null} Link attributes object or null for default behavior
+	 */
+	_linkResolver(pHref, pLinkText)
+	{
+		if (!pHref)
+		{
+			return null;
+		}
+
+		// If it's a .md file, intercept for in-panel navigation.
+		// Use a #help: scheme rather than javascript: to avoid the href being
+		// corrupted by the markdown parser's italic regex (underscores in
+		// variable names like _DocumentationProvider get wrapped in <em> tags).
+		// A click handler on the help body container intercepts these links.
+		if (pHref.endsWith('.md'))
+		{
+			let tmpFullPath = this._BasePath + pHref;
+
+			return {
+				href: '#help:' + tmpFullPath
+			};
+		}
+
+		// External links open in new tab
+		if (pHref.startsWith('http://') || pHref.startsWith('https://'))
+		{
+			return {
+				href: pHref,
+				target: '_blank',
+				rel: 'noopener noreferrer'
+			};
+		}
+
+		return null;
+	}
+
+	/**
+	 * Render the parsed HTML article into the help content area.
+	 *
+	 * @param {string} pHTML - The parsed HTML content
+	 * @param {string} pTitle - The article title (from first heading)
+	 */
+	_renderArticle(pHTML, pTitle)
+	{
+		this._CurrentTitle = pTitle || 'Help';
+
+		let tmpContentView = this._ParentFormEditor._HelpContentView;
+		if (tmpContentView)
+		{
+			let tmpBodyId = 'Pict-Content-Body';
+			tmpContentView.displayContent(pHTML, tmpBodyId);
+		}
+
+		this._attachClickHandler();
+		this._renderBreadcrumbs();
+	}
+
+	/**
+	 * Attach a delegated click handler on the help body container to
+	 * intercept clicks on #help: links. This avoids putting JavaScript
+	 * in href attributes (which gets corrupted by the markdown parser's
+	 * italic regex treating underscores in variable names as emphasis).
+	 */
+	_attachClickHandler()
+	{
+		if (this._ClickHandlerAttached)
+		{
+			return;
+		}
+
+		if (typeof document === 'undefined')
+		{
+			return;
+		}
+
+		let tmpHash = this._ParentFormEditor.Hash;
+		let tmpBody = document.getElementById(`FormEditor-Help-Body-${tmpHash}`);
+
+		if (!tmpBody)
+		{
+			return;
+		}
+
+		let tmpSelf = this;
+		tmpBody.addEventListener('click', (pEvent) =>
+		{
+			// Walk up from the click target to find an anchor with #help: href
+			let tmpEl = pEvent.target;
+			while (tmpEl && tmpEl !== tmpBody)
+			{
+				if (tmpEl.tagName === 'A' && tmpEl.getAttribute('href') && tmpEl.getAttribute('href').indexOf('#help:') === 0)
+				{
+					pEvent.preventDefault();
+					let tmpPath = tmpEl.getAttribute('href').substring(6); // strip '#help:'
+					tmpSelf.loadArticle(tmpPath, true);
+					return;
+				}
+				tmpEl = tmpEl.parentElement;
+			}
+		});
+
+		this._ClickHandlerAttached = true;
+	}
+
+	/**
+	 * Render an error message when an article fails to load.
+	 *
+	 * @param {string} pPath - The path that failed to load
+	 * @param {number} pStatus - The HTTP status code
+	 */
+	_renderError(pPath, pStatus)
+	{
+		let tmpHTML = '<div style="padding: 20px; color: #8A7F72; text-align: center;">';
+		tmpHTML += '<p>Could not load article.</p>';
+		tmpHTML += `<p style="font-size: 12px; color: #B0A89E;">${pPath} (HTTP ${pStatus})</p>`;
+		tmpHTML += '</div>';
+
+		let tmpContentView = this._ParentFormEditor._HelpContentView;
+		if (tmpContentView)
+		{
+			let tmpBodyId = 'Pict-Content-Body';
+			tmpContentView.displayContent(tmpHTML, tmpBodyId);
+		}
+
+		this._renderBreadcrumbs();
+	}
+
+	/**
+	 * Render the breadcrumb navigation bar.
+	 */
+	_renderBreadcrumbs()
+	{
+		let tmpHash = this._ParentFormEditor.Hash;
+		let tmpNavEl = `#FormEditor-Help-Nav-${tmpHash}`;
+		let tmpViewRef = this._ParentFormEditor._browserViewRef();
+
+		let tmpHTML = '';
+
+		// Home link
+		tmpHTML += `<a href="javascript:void(0)" onclick="${tmpViewRef}._DocumentationProvider.navigateHome()">Help</a>`;
+
+		// Stack entries
+		for (let i = 0; i < this._NavigationStack.length; i++)
+		{
+			let tmpEntry = this._NavigationStack[i];
+			tmpHTML += '<span class="pict-fe-help-nav-sep">\u203A</span>';
+			tmpHTML += `<a href="javascript:void(0)" onclick="${tmpViewRef}._DocumentationProvider.loadArticle('${tmpEntry.path}', false); ${tmpViewRef}._DocumentationProvider._NavigationStack.splice(${i});">${this._escapeHTML(tmpEntry.title)}</a>`;
+		}
+
+		// Current article
+		if (this._CurrentTitle && this._CurrentTitle !== 'Help')
+		{
+			tmpHTML += '<span class="pict-fe-help-nav-sep">\u203A</span>';
+			tmpHTML += `<span>${this._escapeHTML(this._CurrentTitle)}</span>`;
+		}
+
+		this.pict.ContentAssignment.assignContent(tmpNavEl, tmpHTML);
+	}
+
+	/**
+	 * Extract the title from the first heading in a markdown string.
+	 *
+	 * @param {string} pMarkdown - The raw markdown text
+	 * @returns {string} The title text, or 'Help' if no heading found
+	 */
+	_extractTitle(pMarkdown)
+	{
+		if (!pMarkdown)
+		{
+			return 'Help';
+		}
+
+		let tmpMatch = pMarkdown.match(/^#\s+(.+)$/m);
+		if (tmpMatch)
+		{
+			return tmpMatch[1].trim();
+		}
+
+		return 'Help';
+	}
+
+	/**
+	 * Escape HTML special characters in a string.
+	 *
+	 * @param {string} pString - The string to escape
+	 * @returns {string} The escaped string
+	 */
+	_escapeHTML(pString)
+	{
+		if (typeof pString !== 'string')
+		{
+			return '';
+		}
+		return pString
+			.replace(/&/g, '&amp;')
+			.replace(/</g, '&lt;')
+			.replace(/>/g, '&gt;')
+			.replace(/"/g, '&quot;');
+	}
+}
+
+module.exports = FormEditorDocumentation;