pict-section-inlinedocumentation 0.0.4 → 0.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pict-section-inlinedocumentation",
-	"version": "0.0.4",
+	"version": "0.0.5",
 	"description": "Pict embeddable inline documentation browser with topic support",
 	"main": "source/Pict-Section-InlineDocumentation.js",
 	"scripts": {
@@ -22,6 +22,7 @@
 	},
 	"homepage": "https://github.com/stevenvelozo/pict-section-inlinedocumentation#readme",
 	"dependencies": {
+		"lunr": "^2.3.9",
 		"pict-provider": "^1.0.12",
 		"pict-section-content": "^0.1.5",
 		"pict-section-markdowneditor": "^1.0.9",

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

@@ -3,6 +3,7 @@ const libPictSectionContent = require('pict-section-content');
 const libPictContentProvider = libPictSectionContent.PictContentProvider;
 const libPictSectionModal = require('pict-section-modal');
 const libPictSectionMarkdownEditor = require('pict-section-markdowneditor');
+const libLunr = require('lunr');
 
 const libViewLayout = require('../views/Pict-View-InlineDocumentation-Layout.js');
 const libViewContent = require('../views/Pict-View-InlineDocumentation-Content.js');
@@ -90,8 +91,31 @@ class InlineDocumentationProvider extends libPictProvider
 		tmpState.Topics = tmpState.Topics || {};
 		tmpState.NavigationHistory = [];
 
-		// Edit mode state
-		tmpState.EditEnabled = tmpState.EditEnabled || false;
+		// Navigation outline state
+		tmpState.NavCollapsed = true;
+		tmpState.CollapsedGroups = {};
+		tmpState.ActiveDocumentHeadings = [];
+		tmpState.NavFilterText = '';
+
+		// Full-text search state
+		tmpState.SearchIndexLoaded = false;
+		tmpState.SearchQuery = '';
+		tmpState.SearchResults = [];
+
+		// External link resolution — paths starting with / in the
+		// sidebar are cross-module references. ExternalDocBaseURL
+		// is prepended to make them full URLs opened in a new tab.
+		tmpState.ExternalDocBaseURL = tmpOptions.ExternalDocBaseURL || '';
+
+		// Edit mode state — read from pOptions if provided
+		if (tmpOptions.EditEnabled !== undefined)
+		{
+			tmpState.EditEnabled = !!tmpOptions.EditEnabled;
+		}
+		else
+		{
+			tmpState.EditEnabled = tmpState.EditEnabled || false;
+		}
 		tmpState.Editing = false;
 		tmpState.EditingPath = '';
 		tmpState.EditingContent = '';
@@ -142,17 +166,23 @@ class InlineDocumentationProvider extends libPictProvider
 			}
 		}
 
-		// Load sidebar and topics in parallel
+		// Load sidebar, topics, and search index in parallel
 		let tmpPending = 2;
+		if (tmpOptions.SearchIndexURL) tmpPending++;
+
+		let tmpSelf = this;
 		let tmpFinish = () =>
 		{
 			tmpPending--;
 			if (tmpPending <= 0)
 			{
+				// Mark sidebar items as external based on ExternalDocBaseURL
+				tmpSelf._markExternalSidebarItems();
+
 				// Render the layout (which contains nav and content containers)
-				this.pict.views['InlineDoc-Layout'].render();
+				tmpSelf.pict.views['InlineDoc-Layout'].render();
 				// Render the navigation
-				this.pict.views['InlineDoc-Nav'].render();
+				tmpSelf.pict.views['InlineDoc-Nav'].render();
 
 				return tmpCallback();
 			}
@@ -160,6 +190,11 @@ class InlineDocumentationProvider extends libPictProvider
 
 		this._loadSidebar(tmpFinish);
 		this._loadTopics(tmpOptions.TopicsURL, tmpFinish);
+
+		if (tmpOptions.SearchIndexURL)
+		{
+			this._loadSearchIndex(tmpOptions.SearchIndexURL, tmpFinish);
+		}
 	}
 
 	/**
@@ -226,7 +261,11 @@ class InlineDocumentationProvider extends libPictProvider
 				this._scrollToAnchor(tmpAnchor);
 			}
 
-			// Update nav to reflect active document
+			// Collapse the nav outline and clear search/filter
+			tmpState.NavCollapsed = true;
+			tmpState.NavFilterText = '';
+			tmpState.SearchQuery = '';
+			tmpState.SearchResults = [];
 			this.pict.views['InlineDoc-Nav'].render();
 
 			return tmpCallback(null, pHTML);
@@ -1615,6 +1654,251 @@ class InlineDocumentationProvider extends libPictProvider
 		}, 50);
 	}
 
+	// ================================================================
+	// Full-text search
+	// ================================================================
+
+	/**
+	 * Load a lunr.js keyword index from a URL.
+	 *
+	 * The index file is the same format generated by Indoctrinate's
+	 * generate_keyword_index command: { LunrIndex, Documents, DocumentCount }.
+	 *
+	 * @param {string} pURL - URL to the retold-keyword-index.json file
+	 * @param {Function} [fCallback] - Callback when done
+	 */
+	_loadSearchIndex(pURL, fCallback)
+	{
+		let tmpCallback = (typeof fCallback === 'function') ? fCallback : () => {};
+		let tmpSelf = this;
+
+		if (typeof fetch === 'undefined')
+		{
+			return tmpCallback();
+		}
+
+		fetch(pURL)
+			.then((pResponse) =>
+			{
+				if (!pResponse.ok)
+				{
+					return null;
+				}
+				return pResponse.json();
+			})
+			.then((pIndexData) =>
+			{
+				if (!pIndexData || !pIndexData.LunrIndex || !pIndexData.Documents)
+				{
+					if (tmpSelf.log) tmpSelf.log.info('InlineDocumentation: No keyword index found; search unavailable.');
+					return tmpCallback();
+				}
+
+				try
+				{
+					tmpSelf._LunrIndex = libLunr.Index.load(pIndexData.LunrIndex);
+					tmpSelf._SearchDocuments = pIndexData.Documents;
+
+					let tmpState = tmpSelf.pict.AppData.InlineDocumentation;
+					if (tmpState)
+					{
+						tmpState.SearchIndexLoaded = true;
+					}
+
+					if (tmpSelf.log) tmpSelf.log.info('InlineDocumentation: Search index loaded (' + (pIndexData.DocumentCount || 0) + ' documents).');
+				}
+				catch (pError)
+				{
+					if (tmpSelf.log) tmpSelf.log.warn('InlineDocumentation: Error hydrating lunr index: ' + pError);
+				}
+
+				return tmpCallback();
+			})
+			.catch((pError) =>
+			{
+				if (tmpSelf.log) tmpSelf.log.warn('InlineDocumentation: Error loading search index: ' + pError);
+				return tmpCallback();
+			});
+	}
+
+	/**
+	 * Search the loaded lunr index.
+	 *
+	 * @param {string} pQuery - The search query
+	 * @returns {Array} Array of { Key, Title, Group, DocPath, Score }
+	 */
+	search(pQuery)
+	{
+		if (!this._LunrIndex || !this._SearchDocuments || !pQuery || !pQuery.trim())
+		{
+			return [];
+		}
+
+		let tmpResults = [];
+
+		try
+		{
+			let tmpLunrResults = this._LunrIndex.search(pQuery);
+
+			for (let i = 0; i < tmpLunrResults.length; i++)
+			{
+				let tmpRef = tmpLunrResults[i].ref;
+				let tmpScore = tmpLunrResults[i].score;
+				let tmpDoc = this._SearchDocuments[tmpRef];
+
+				if (!tmpDoc)
+				{
+					continue;
+				}
+
+				tmpResults.push(
+				{
+					Key: tmpRef,
+					Title: tmpDoc.Title || tmpRef,
+					Group: tmpDoc.Group || '',
+					Module: tmpDoc.Module || '',
+					DocPath: tmpDoc.DocPath || tmpRef,
+					Score: tmpScore
+				});
+			}
+		}
+		catch (pError)
+		{
+			if (this.log) this.log.warn('InlineDocumentation: Search error: ' + pError);
+		}
+
+		return tmpResults;
+	}
+
+	// ================================================================
+	// External link resolution (catalog-based)
+	// ================================================================
+
+	/**
+	 * Check if a path is an external reference.
+	 *
+	 * Paths that started with / in the sidebar are cross-module
+	 * references. They get normalized during parsing (leading /
+	 * stripped), but they contain 2+ path segments (group/module/).
+	 * Simple filenames like README.md are local.
+	 *
+	 * An ExternalDocBaseURL must be configured for this to return true.
+	 *
+	 * @param {string} pPath - The normalized document path
+	 * @returns {boolean}
+	 */
+	isExternalPath(pPath)
+	{
+		if (!pPath) return false;
+
+		let tmpState = this.pict.AppData.InlineDocumentation;
+		if (!tmpState || !tmpState.ExternalDocBaseURL) return false;
+
+		// Paths with 2+ segments (e.g., pict/pict/, fable/fable/)
+		// are cross-module references. Simple filenames are local.
+		let tmpPath = pPath.replace(/^\.\//, '').replace(/^\//, '');
+		let tmpParts = tmpPath.split('/').filter((p) => p.length > 0);
+		return tmpParts.length >= 2;
+	}
+
+	/**
+	 * Resolve an external path to a full URL.
+	 *
+	 * @param {string} pPath - The document path
+	 * @returns {string|null} The external URL, or null if not external
+	 */
+	resolveExternalURL(pPath)
+	{
+		if (!this.isExternalPath(pPath)) return null;
+
+		let tmpState = this.pict.AppData.InlineDocumentation;
+		let tmpBaseURL = (tmpState && tmpState.ExternalDocBaseURL) || '';
+		if (!tmpBaseURL) return null;
+
+		let tmpPath = pPath.replace(/^\.\//, '').replace(/^\//, '');
+		return tmpBaseURL + tmpPath;
+	}
+
+	/**
+	 * After sidebar is loaded, mark items that are external
+	 * references with External: true and ExternalURL.
+	 */
+	_markExternalSidebarItems()
+	{
+		let tmpState = this.pict.AppData.InlineDocumentation;
+		if (!tmpState || !tmpState.ExternalDocBaseURL) return;
+
+		let tmpGroups = tmpState.SidebarGroups || [];
+		for (let i = 0; i < tmpGroups.length; i++)
+		{
+			let tmpItems = tmpGroups[i].Items || [];
+			for (let j = 0; j < tmpItems.length; j++)
+			{
+				let tmpItem = tmpItems[j];
+				if (this.isExternalPath(tmpItem.Path))
+				{
+					tmpItem.External = true;
+					tmpItem.ExternalURL = this.resolveExternalURL(tmpItem.Path);
+				}
+			}
+		}
+	}
+
+	/**
+	 * Extract h2 and h3 headings from the rendered content body.
+	 *
+	 * Queries #InlineDoc-Content-Body for heading elements, extracts
+	 * their text, generates slugified IDs for anchor scrolling, and
+	 * stores the results in AppData for the nav outline.
+	 *
+	 * @returns {Array} Array of { Text, Slug, Level }
+	 */
+	_extractHeadings()
+	{
+		let tmpHeadings = [];
+
+		if (typeof document === 'undefined')
+		{
+			return tmpHeadings;
+		}
+
+		let tmpContentBody = document.getElementById('InlineDoc-Content-Body');
+		if (!tmpContentBody)
+		{
+			return tmpHeadings;
+		}
+
+		let tmpElements = tmpContentBody.querySelectorAll('h2, h3');
+
+		for (let i = 0; i < tmpElements.length; i++)
+		{
+			let tmpElement = tmpElements[i];
+			let tmpText = (tmpElement.textContent || '').trim();
+			let tmpLevel = parseInt(tmpElement.tagName.substring(1), 10);
+			let tmpSlug = tmpText.toLowerCase()
+				.replace(/[^a-z0-9\s-]/g, '')
+				.replace(/\s+/g, '-')
+				.replace(/-+/g, '-');
+
+			// Assign the ID to the heading element if not already set
+			// so scrollIntoView can find it
+			if (!tmpElement.id)
+			{
+				tmpElement.id = tmpSlug;
+			}
+
+			tmpHeadings.push({ Text: tmpText, Slug: tmpSlug, Level: tmpLevel });
+		}
+
+		let tmpState = this.pict.AppData.InlineDocumentation;
+		if (tmpState)
+		{
+			tmpState.ActiveDocumentHeadings = tmpHeadings;
+		}
+
+		return tmpHeadings;
+	}
+
 	// -- Internal methods --
 
 	/**

package/source/views/Pict-View-InlineDocumentation-Content.js

@@ -150,6 +150,62 @@ const _ViewConfiguration =
 			font-size: 0.85em;
 			color: #9E6B47;
 		}
+		/* Code block action buttons (copy, fullscreen) from pict-section-content */
+		.pict-content-code-actions {
+			position: sticky;
+			top: 64px;
+			align-self: flex-start;
+			display: flex;
+			flex-direction: column;
+			gap: 6px;
+			flex: 0 0 auto;
+			padding-top: 6px;
+			opacity: 0;
+			transform: translateX(-4px);
+			transition: opacity 0.15s ease, transform 0.15s ease;
+			pointer-events: none;
+		}
+		.pict-content-code-container:hover .pict-content-code-actions,
+		.pict-content-code-container:focus-within .pict-content-code-actions {
+			opacity: 1;
+			transform: translateX(0);
+			pointer-events: auto;
+		}
+		.pict-content-code-action-btn {
+			display: inline-flex;
+			align-items: center;
+			justify-content: center;
+			width: 28px;
+			height: 28px;
+			padding: 0;
+			background: #FFFFFF;
+			color: #5E5549;
+			border: 1px solid #DDD6CA;
+			border-radius: 6px;
+			cursor: pointer;
+			box-shadow: 0 1px 3px rgba(0, 0, 0, 0.08);
+			transition: background-color 0.15s ease, color 0.15s ease;
+		}
+		.pict-content-code-action-btn svg {
+			display: block;
+			width: 14px;
+			height: 14px;
+			stroke: currentColor;
+			fill: none;
+			stroke-width: 1.6;
+			stroke-linecap: round;
+			stroke-linejoin: round;
+		}
+		.pict-content-code-action-btn:hover {
+			background: #2E7D74;
+			color: #FFFFFF;
+			border-color: #2E7D74;
+		}
+		.pict-content-code-action-btn.is-copied {
+			background: #2E7D74;
+			color: #FFFFFF;
+			border-color: #2E7D74;
+		}
 		.pict-inline-doc-edit-toolbar {
 			display: none;
 			align-items: center;
@@ -525,6 +581,19 @@ class InlineDocumentationContentView extends libPictContentView
 			let tmpRel = tmpLink.getAttribute('rel');
 			let tmpPath = tmpRel.replace('pict-inline-doc-link:', '');
 
+			// Check if this is a cross-module link that should open externally
+			if (tmpProvider && typeof tmpProvider.isExternalPath === 'function' && tmpProvider.isExternalPath(tmpPath))
+			{
+				let tmpExternalURL = tmpProvider.resolveExternalURL(tmpPath);
+				if (tmpExternalURL)
+				{
+					tmpLink.setAttribute('href', tmpExternalURL);
+					tmpLink.setAttribute('target', '_blank');
+					tmpLink.setAttribute('rel', 'noopener');
+					continue;
+				}
+			}
+
 			tmpLink.addEventListener('click', (pEvent) =>
 			{
 				pEvent.preventDefault();

package/source/views/Pict-View-InlineDocumentation-Layout.js

@@ -42,7 +42,7 @@ const _ViewConfiguration =
 		.pict-inline-doc-nav-container.pict-inline-doc-nav-hidden {
 			display: none;
 		}
-		/* Compact mode: nav moves to a horizontal top bar when container is narrow */
+		/* Compact mode: stack nav above content when container is narrow */
 		.pict-inline-doc.pict-inline-doc-compact {
 			flex-direction: column;
 		}
@@ -53,54 +53,7 @@ const _ViewConfiguration =
 			border-right: none;
 			border-bottom: 1px solid #E5DED4;
 			overflow-y: visible;
-			overflow-x: auto;
 			flex-shrink: 0;
-			max-height: none;
-		}
-		/* Compact mode: nav items flow horizontally */
-		.pict-inline-doc.pict-inline-doc-compact .pict-inline-doc-nav {
-			padding: 0.4em 0.5em;
-			display: flex;
-			flex-wrap: wrap;
-			align-items: center;
-			gap: 0.15em 0.3em;
-		}
-		.pict-inline-doc.pict-inline-doc-compact .pict-inline-doc-nav-group {
-			display: flex;
-			flex-wrap: wrap;
-			align-items: center;
-			margin-bottom: 0;
-			gap: 0.1em 0.2em;
-		}
-		.pict-inline-doc.pict-inline-doc-compact .pict-inline-doc-nav-group-header {
-			padding: 0.2em 0.5em;
-			font-size: 0.75em;
-			white-space: nowrap;
-		}
-		.pict-inline-doc.pict-inline-doc-compact .pict-inline-doc-nav-group-toggle {
-			display: none;
-		}
-		.pict-inline-doc.pict-inline-doc-compact .pict-inline-doc-nav-group-items {
-			display: flex !important;
-			flex-wrap: wrap;
-			gap: 0.1em;
-		}
-		.pict-inline-doc.pict-inline-doc-compact .pict-inline-doc-nav-item {
-			padding: 0.2em 0.5em;
-			font-size: 0.8em;
-			border-left: none;
-			border-radius: 3px;
-			white-space: nowrap;
-		}
-		.pict-inline-doc.pict-inline-doc-compact .pict-inline-doc-nav-item.active {
-			border-left: none;
-			background: #2E7D74;
-			color: #fff;
-		}
-		.pict-inline-doc.pict-inline-doc-compact .pict-inline-doc-nav-topic-badge {
-			margin: 0 0.3em;
-			padding: 0.15em 0.5em;
-			font-size: 0.75em;
 		}
 	`,