pict-section-inlinedocumentation 0.0.4 → 0.0.7

package/example_applications/basic/index.html

@@ -9,7 +9,7 @@
 		body {
 			font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
 			background: #F5F3EE;
-			color: #3D3229;
+			color: var(--theme-color-text-primary, #3D3229);
 			padding: 2em;
 		}
 		h1 {
@@ -26,17 +26,17 @@
 			padding: 0.4em 0.8em;
 			border: 1px solid #C4BAA8;
 			border-radius: 4px;
-			background: #fff;
-			color: #3D3229;
+			background: var(--theme-color-background-panel, #fff);
+			color: var(--theme-color-text-primary, #3D3229);
 			cursor: pointer;
 			font-size: 0.9em;
 		}
 		.controls button:hover {
-			background: #F0ECE4;
+			background: var(--theme-color-background-secondary, #F0ECE4);
 		}
 		.controls button.active {
 			background: #2E7D74;
-			color: #fff;
+			color: var(--theme-color-background-panel, #fff);
 			border-color: #2E7D74;
 		}
 		#InlineDoc-Container {

package/example_applications/bookshop/html/index.html

@@ -13,8 +13,8 @@
 
 			/* --- Header Bar --- */
 			.pict-example-header { display: flex; align-items: stretch; background: #264653; border-bottom: 3px solid #E76F51; position: fixed; top: 0; left: 0; right: 0; z-index: 100; }
-			.pict-example-badge { background: #E76F51; color: #fff; padding: 0.6rem 1rem; font-size: 0.7rem; font-weight: 800; text-transform: uppercase; letter-spacing: 0.1em; display: flex; align-items: center; gap: 0.5rem; }
-			.pict-example-badge svg { width: 14px; height: 14px; fill: #fff; flex-shrink: 0; }
+			.pict-example-badge { background: #E76F51; color: var(--theme-color-background-panel, #fff); padding: 0.6rem 1rem; font-size: 0.7rem; font-weight: 800; text-transform: uppercase; letter-spacing: 0.1em; display: flex; align-items: center; gap: 0.5rem; }
+			.pict-example-badge svg { width: 14px; height: 14px; fill: var(--theme-color-background-panel, #fff); flex-shrink: 0; }
 			.pict-example-app-name { padding: 0.6rem 1rem; color: #FAEDCD; font-size: 1.1rem; font-weight: 600; display: flex; align-items: center; }
 			.pict-example-module { margin-left: auto; padding: 0.6rem 1rem; color: #D4A373; font-size: 0.75rem; display: flex; align-items: center; letter-spacing: 0.03em; }
 			.pict-example-header-help-btn {
@@ -41,7 +41,7 @@
 				margin-right: 380px;
 			}
 			#Bookshop-Content-Container {
-				background: #fff;
+				background: var(--theme-color-background-panel, #fff);
 				border: 1px solid #D4A373;
 				border-top: 4px solid #E76F51;
 				border-radius: 6px;
@@ -57,7 +57,7 @@
 				bottom: 0;
 				width: 380px;
 				min-width: 320px;
-				background: #FDFCFA;
+				background: var(--theme-color-background-panel, #FDFCFA);
 				border-left: 1px solid #D4A373;
 				box-shadow: -2px 0 12px rgba(38,70,83,0.08);
 				transform: translateX(100%);
@@ -153,7 +153,7 @@
 			#Bookshop-Help-Panel .pict-inline-doc-nav-item.active {
 				border-left: none;
 				background: #2E7D74;
-				color: #fff;
+				color: var(--theme-color-background-panel, #fff);
 			}
 			#Bookshop-Help-Panel .pict-inline-doc-nav-topic-badge {
 				margin: 0 0.3em;

package/example_applications/bookshop/views/PictView-Bookshop-BookList.js

@@ -42,7 +42,7 @@ const _ViewConfiguration =
 		}
 		.bookshop-help-btn:hover {
 			background: #D4A373;
-			color: #fff;
+			color: var(--theme-color-background-panel, #fff);
 		}
 		.bookshop-filter-bar {
 			margin-bottom: 1.25em;
@@ -53,14 +53,14 @@ const _ViewConfiguration =
 		.bookshop-filter-bar label {
 			font-size: 0.85em;
 			font-weight: 600;
-			color: #5E5549;
+			color: var(--theme-color-text-secondary, #5E5549);
 		}
 		.bookshop-filter-bar select {
 			padding: 0.35em 0.7em;
 			border: 1px solid #D4A373;
 			border-radius: 4px;
 			font-size: 0.85em;
-			background: #fff;
+			background: var(--theme-color-background-panel, #fff);
 			color: #264653;
 		}
 		.bookshop-book-grid {
@@ -72,7 +72,7 @@ const _ViewConfiguration =
 			display: flex;
 			gap: 1em;
 			padding: 1em;
-			background: #fff;
+			background: var(--theme-color-background-panel, #fff);
 			border: 1px solid #E5DED4;
 			border-radius: 6px;
 			cursor: pointer;
@@ -88,7 +88,7 @@ const _ViewConfiguration =
 			border-radius: 4px;
 			object-fit: cover;
 			flex-shrink: 0;
-			background: #F0ECE4;
+			background: var(--theme-color-background-secondary, #F0ECE4);
 		}
 		.bookshop-book-info {
 			flex: 1;
@@ -110,7 +110,7 @@ const _ViewConfiguration =
 			font-size: 0.7em;
 			padding: 0.15em 0.5em;
 			background: #E8E3D8;
-			color: #5E5549;
+			color: var(--theme-color-text-secondary, #5E5549);
 			border-radius: 3px;
 			margin-bottom: 0.4em;
 		}

package/example_applications/bookshop/views/PictView-Bookshop-Store.js

@@ -20,7 +20,7 @@ const _ViewConfiguration =
 			padding: 0.4em 0.8em;
 			border: 1px solid #D4A373;
 			border-radius: 4px;
-			background: #fff;
+			background: var(--theme-color-background-panel, #fff);
 			color: #264653;
 			cursor: pointer;
 			font-size: 0.85em;
@@ -40,7 +40,7 @@ const _ViewConfiguration =
 			border-radius: 6px;
 			object-fit: cover;
 			flex-shrink: 0;
-			background: #F0ECE4;
+			background: var(--theme-color-background-secondary, #F0ECE4);
 			box-shadow: 0 2px 12px rgba(38,70,83,0.12);
 		}
 		.bookshop-store-info {
@@ -94,7 +94,7 @@ const _ViewConfiguration =
 			display: inline-block;
 			padding: 0.6em 1.5em;
 			background: #E76F51;
-			color: #fff;
+			color: var(--theme-color-background-panel, #fff);
 			border: none;
 			border-radius: 5px;
 			font-size: 1em;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pict-section-inlinedocumentation",
-	"version": "0.0.4",
+	"version": "0.0.7",
 	"description": "Pict embeddable inline documentation browser with topic support",
 	"main": "source/Pict-Section-InlineDocumentation.js",
 	"scripts": {
@@ -22,17 +22,18 @@
 	},
 	"homepage": "https://github.com/stevenvelozo/pict-section-inlinedocumentation#readme",
 	"dependencies": {
-		"pict-provider": "^1.0.12",
-		"pict-section-content": "^0.1.5",
-		"pict-section-markdowneditor": "^1.0.9",
-		"pict-section-modal": "^0.0.4",
+		"lunr": "^2.3.9",
+		"pict-provider": "^1.0.13",
+		"pict-section-content": "^1.0.0",
+		"pict-section-markdowneditor": "^1.0.15",
+		"pict-section-modal": "^1.0.1",
 		"pict-view": "^1.0.68"
 	},
 	"devDependencies": {
-		"pict": "^1.0.363",
-		"pict-docuserve": "^0.1.5",
+		"pict": "^1.0.368",
+		"pict-docuserve": "^1.0.0",
 		"puppeteer": "^24.40.0",
-		"quackage": "^1.1.0"
+		"quackage": "^1.2.3"
 	},
 	"mocha": {
 		"diff": true,

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);
@@ -1429,7 +1468,7 @@ class InlineDocumentationProvider extends libPictProvider
 
 		let tmpEditorHTML = '<div class="pict-inline-doc-tm-form-group">';
 		tmpEditorHTML += '<label class="pict-inline-doc-tm-form-label">Tooltip Key</label>';
-		tmpEditorHTML += '<div style="font-family:monospace;font-size:0.85em;color:#8A7F72;padding:0.3em 0;">' + this._escapeTooltipHTML(pTooltipKey) + '</div>';
+		tmpEditorHTML += '<div style="font-family:monospace;font-size:0.85em;color:var(--theme-color-text-muted, #8A7F72);padding:0.3em 0;">' + this._escapeTooltipHTML(pTooltipKey) + '</div>';
 		tmpEditorHTML += '</div>';
 		tmpEditorHTML += '<div class="pict-inline-doc-tm-form-group">';
 		tmpEditorHTML += '<label class="pict-inline-doc-tm-form-label">Content (Markdown)</label>';
@@ -1458,7 +1497,7 @@ class InlineDocumentationProvider extends libPictProvider
 				{
 					// Initial preview
 					let tmpLinkResolver = tmpSelf._createTooltipLinkResolver();
-					let tmpInitialHTML = tmpCurrentContent ? tmpSelf._ContentProvider.parseMarkdown(tmpCurrentContent, tmpLinkResolver) : '<span style="color:#8A7F72;">No content yet.</span>';
+					let tmpInitialHTML = tmpCurrentContent ? tmpSelf._ContentProvider.parseMarkdown(tmpCurrentContent, tmpLinkResolver) : '<span style="color:var(--theme-color-text-muted, #8A7F72);">No content yet.</span>';
 					tmpPreview.innerHTML = tmpInitialHTML;
 
 					// Live preview on input
@@ -1471,7 +1510,7 @@ class InlineDocumentationProvider extends libPictProvider
 						}
 						else
 						{
-							tmpPreview.innerHTML = '<span style="color:#8A7F72;">No content yet.</span>';
+							tmpPreview.innerHTML = '<span style="color:var(--theme-color-text-muted, #8A7F72);">No content yet.</span>';
 						}
 					});
 
@@ -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 --
 
 	/**