pict-section-inlinedocumentation 1.0.1 → 1.0.3

package/example_applications/bookshop/package.json

@@ -30,5 +30,13 @@
 			"from": "./data/pict_documentation_topics.json",
 			"to": "./dist/docs/"
 		}
-	]
+	],
+	"retold": {
+		"ExampleApplication": {
+			"Stage": true,
+			"Title": "Bookshop",
+			"Summary": "E-commerce demo with route-mapped help, data-attribute tooltips, and F1 toggling for pict-section-inlinedocumentation.",
+			"Complexity": "Intermediate"
+		}
+	}
 }

package/package.json

@@ -1,56 +1,56 @@
 {
-	"name": "pict-section-inlinedocumentation",
-	"version": "1.0.1",
-	"description": "Pict embeddable inline documentation browser with topic support",
-	"main": "source/Pict-Section-InlineDocumentation.js",
-	"scripts": {
-		"start": "node source/Pict-Section-InlineDocumentation.js",
-		"test": "npx quack test",
-		"tests": "npx quack test -g",
-		"coverage": "npx quack coverage",
-		"build": "npx quack build",
-		"test-browser": "npx mocha test/Browser_Integration_tests.js --timeout 60000"
-	},
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/stevenvelozo/pict-section-inlinedocumentation.git"
-	},
-	"author": "steven velozo <steven@velozo.com>",
-	"license": "MIT",
-	"bugs": {
-		"url": "https://github.com/stevenvelozo/pict-section-inlinedocumentation/issues"
-	},
-	"homepage": "https://github.com/stevenvelozo/pict-section-inlinedocumentation#readme",
-	"dependencies": {
-		"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.368",
-		"pict-docuserve": "^1.0.0",
-		"puppeteer": "^24.40.0",
-		"quackage": "^1.2.3"
-	},
-	"mocha": {
-		"diff": true,
-		"extension": [
-			"js"
-		],
-		"package": "./package.json",
-		"reporter": "spec",
-		"slow": "75",
-		"timeout": "5000",
-		"ui": "tdd",
-		"watch-files": [
-			"source/**/*.js",
-			"test/**/*.js"
-		],
-		"watch-ignore": [
-			"lib/vendor"
-		]
-	}
+  "name": "pict-section-inlinedocumentation",
+  "version": "1.0.3",
+  "description": "Pict embeddable inline documentation browser with topic support",
+  "main": "source/Pict-Section-InlineDocumentation.js",
+  "scripts": {
+    "start": "node source/Pict-Section-InlineDocumentation.js",
+    "test": "npx quack test",
+    "tests": "npx quack test -g",
+    "coverage": "npx quack coverage",
+    "build": "npx quack build",
+    "test-browser": "npx mocha test/Browser_Integration_tests.js --timeout 60000"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fable-retold/pict-section-inlinedocumentation.git"
+  },
+  "author": "steven velozo <steven@velozo.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/fable-retold/pict-section-inlinedocumentation/issues"
+  },
+  "homepage": "https://github.com/fable-retold/pict-section-inlinedocumentation#readme",
+  "dependencies": {
+    "lunr": "^2.3.9",
+    "pict-provider": "^1.0.13",
+    "pict-section-content": "^1.0.7",
+    "pict-section-markdowneditor": "^1.0.15",
+    "pict-section-modal": "^1.1.4",
+    "pict-view": "^1.0.68"
+  },
+  "devDependencies": {
+    "pict": "^1.0.372",
+    "pict-docuserve": "^1.4.4",
+    "puppeteer": "^24.40.0",
+    "quackage": "^1.3.0"
+  },
+  "mocha": {
+    "diff": true,
+    "extension": [
+      "js"
+    ],
+    "package": "./package.json",
+    "reporter": "spec",
+    "slow": "75",
+    "timeout": "5000",
+    "ui": "tdd",
+    "watch-files": [
+      "source/**/*.js",
+      "test/**/*.js"
+    ],
+    "watch-ignore": [
+      "lib/vendor"
+    ]
+  }
 }

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

@@ -2213,24 +2213,48 @@ class InlineDocumentationProvider extends libPictProvider
 			}
 			else if (tmpCurrentGroup)
 			{
-				// Indented item — document within the current group
+				// Indented item — a document (link) or a sub-folder (no link)
+				// within the current group. Capture the nesting Level from the
+				// indentation so the nav can render real hierarchy.
+				let tmpLevel = Math.max(0, Math.floor((tmpIndent - 2) / 2));
 				if (tmpLinkMatch)
 				{
 					tmpCurrentGroup.Items.push({
 						Name: tmpLinkMatch[1].trim(),
-						Path: this._normalizePath(tmpLinkMatch[2].trim())
+						Path: this._normalizePath(tmpLinkMatch[2].trim()),
+						Level: tmpLevel
 					});
 				}
 				else
 				{
 					tmpCurrentGroup.Items.push({
 						Name: tmpItemContent,
-						Path: ''
+						Path: '',
+						Level: tmpLevel,
+						IsFolder: true
 					});
 				}
 			}
 		}
 
+		// Make sub-folder nodes actionable: resolve each folder's first
+		// descendant document (the items are in depth-first order, so scan
+		// forward until we leave the folder's subtree) so clicking the folder
+		// opens its first child.
+		for (let g = 0; g < tmpGroups.length; g++)
+		{
+			let tmpItems = tmpGroups[g].Items || [];
+			for (let a = 0; a < tmpItems.length; a++)
+			{
+				if (!tmpItems[a].IsFolder) { continue; }
+				for (let b = a + 1; b < tmpItems.length; b++)
+				{
+					if ((tmpItems[b].Level || 0) <= (tmpItems[a].Level || 0)) { break; }
+					if (tmpItems[b].Path) { tmpItems[a].FirstChildPath = tmpItems[b].Path; break; }
+				}
+			}
+		}
+
 		return tmpGroups;
 	}
 

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

@@ -25,14 +25,27 @@ const _ViewConfiguration =
 			overflow: hidden;
 		}
 		.pict-inline-doc-nav-container {
-			width: 240px;
-			min-width: 200px;
-			max-width: 300px;
+			width: var(--pict-inline-doc-nav-width, 240px);
+			min-width: 160px;
+			max-width: 640px;
 			border-right: 1px solid var(--theme-color-border-default, #E5DED4);
 			background: var(--theme-color-background-secondary, #F7F5F0);
 			overflow-y: auto;
 			flex-shrink: 0;
 		}
+		.pict-inline-doc-resizer {
+			flex: 0 0 6px;
+			width: 6px;
+			margin: 0 -3px;
+			z-index: 2;
+			cursor: col-resize;
+			background: transparent;
+			transition: background 0.12s ease;
+		}
+		.pict-inline-doc-resizer:hover,
+		.pict-inline-doc-resizer.pict-inline-doc-resizing {
+			background: var(--theme-color-brand-primary, #2E7D74);
+		}
 		.pict-inline-doc-content-container {
 			flex: 1;
 			overflow-y: auto;
@@ -42,6 +55,26 @@ const _ViewConfiguration =
 		.pict-inline-doc-nav-container.pict-inline-doc-nav-hidden {
 			display: none;
 		}
+		/* Whole-panel collapse: shrink the nav to a thin strip showing only the
+		   expand chevron, handing the freed width back to the content. The Nav
+		   view toggles .pict-inline-doc-nav-collapsed on the container. width is
+		   !important so it beats any inline width left by the drag-resizer. */
+		.pict-inline-doc-nav-container.pict-inline-doc-nav-collapsed {
+			width: 40px !important;
+			min-width: 40px;
+		}
+		.pict-inline-doc-nav-container.pict-inline-doc-nav-collapsed + .pict-inline-doc-resizer {
+			display: none;
+		}
+		.pict-inline-doc-nav-collapsed .pict-inline-doc-nav-collapsed-header {
+			flex-direction: column;
+			padding: 0.6em 0;
+			justify-content: flex-start;
+		}
+		.pict-inline-doc-nav-collapsed .pict-inline-doc-nav-current-title,
+		.pict-inline-doc-nav-collapsed .pict-inline-doc-nav-search-icon {
+			display: none;
+		}
 		/* Compact mode: stack nav above content when container is narrow */
 		.pict-inline-doc.pict-inline-doc-compact {
 			flex-direction: column;
@@ -55,6 +88,9 @@ const _ViewConfiguration =
 			overflow-y: visible;
 			flex-shrink: 0;
 		}
+		.pict-inline-doc.pict-inline-doc-compact .pict-inline-doc-resizer {
+			display: none;
+		}
 	`,
 
 	Templates:
@@ -64,6 +100,7 @@ const _ViewConfiguration =
 			Template: /*html*/`
 <div class="pict-inline-doc">
 	<div class="pict-inline-doc-nav-container" id="InlineDoc-Nav-Container"></div>
+	<div class="pict-inline-doc-resizer" id="InlineDoc-Resizer" title="Drag to resize the navigation"></div>
 	<div class="pict-inline-doc-content-container" id="InlineDoc-Content-Container"></div>
 </div>
 `
@@ -93,12 +130,107 @@ class InlineDocumentationLayoutView extends libPictView
 		// Inject all view CSS into the PICT-CSS style element
 		this.pict.CSSMap.injectCSS();
 
+		// Restore any saved nav width, then make the nav/content divider draggable
+		this._restoreNavWidth();
+		this._wireNavResizer();
+
 		// Watch for size changes and toggle compact mode
 		this._setupCompactModeObserver();
 
 		return super.onAfterRender();
 	}
 
+	/**
+	 * Make the divider between the nav and the content draggable so the reader
+	 * can widen or narrow the navigation. The width lives in a CSS custom
+	 * property on the layout container and is persisted to localStorage.
+	 */
+	_wireNavResizer()
+	{
+		if (typeof document === 'undefined')
+		{
+			return;
+		}
+
+		let tmpResizer = document.getElementById('InlineDoc-Resizer');
+		let tmpContainer = document.querySelector('.pict-inline-doc');
+		let tmpNav = document.getElementById('InlineDoc-Nav-Container');
+		if (!tmpResizer || !tmpContainer || !tmpNav)
+		{
+			return;
+		}
+
+		let tmpMin = 160;
+		let tmpMax = 640;
+		let tmpSelf = this;
+
+		tmpResizer.addEventListener('mousedown', (pDownEvent) =>
+		{
+			pDownEvent.preventDefault();
+			let tmpStartX = pDownEvent.clientX;
+			let tmpStartWidth = tmpNav.offsetWidth;
+
+			tmpResizer.classList.add('pict-inline-doc-resizing');
+			document.body.style.userSelect = 'none';
+			document.body.style.cursor = 'col-resize';
+
+			// A drag needs document-level move/up tracking; both listeners are
+			// removed on release, so nothing leaks across renders.
+			let fMove = (pMoveEvent) =>
+			{
+				let tmpWidth = tmpStartWidth + (pMoveEvent.clientX - tmpStartX);
+				tmpWidth = Math.max(tmpMin, Math.min(tmpMax, tmpWidth));
+				tmpContainer.style.setProperty('--pict-inline-doc-nav-width', tmpWidth + 'px');
+			};
+			let fUp = () =>
+			{
+				document.removeEventListener('mousemove', fMove);
+				document.removeEventListener('mouseup', fUp);
+				tmpResizer.classList.remove('pict-inline-doc-resizing');
+				document.body.style.userSelect = '';
+				document.body.style.cursor = '';
+				tmpSelf._persistNavWidth(tmpContainer.style.getPropertyValue('--pict-inline-doc-nav-width'));
+			};
+
+			document.addEventListener('mousemove', fMove);
+			document.addEventListener('mouseup', fUp);
+		});
+	}
+
+	_persistNavWidth(pWidth)
+	{
+		try
+		{
+			if (pWidth && typeof localStorage !== 'undefined')
+			{
+				localStorage.setItem('pict-inline-doc-nav-width', pWidth);
+			}
+		}
+		catch (pError) { /* storage unavailable — the width just won't persist */ }
+	}
+
+	_restoreNavWidth()
+	{
+		try
+		{
+			if (typeof localStorage === 'undefined')
+			{
+				return;
+			}
+			let tmpSaved = localStorage.getItem('pict-inline-doc-nav-width');
+			if (!tmpSaved)
+			{
+				return;
+			}
+			let tmpContainer = document.querySelector('.pict-inline-doc');
+			if (tmpContainer)
+			{
+				tmpContainer.style.setProperty('--pict-inline-doc-nav-width', tmpSaved);
+			}
+		}
+		catch (pError) { /* ignore */ }
+	}
+
 	/**
 	 * Set up a ResizeObserver to toggle compact mode when the container
 	 * is too narrow for a side-by-side nav + content layout.

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

@@ -112,7 +112,7 @@ const _ViewConfiguration =
 		}
 		.pict-inline-doc-nav-item {
 			display: block;
-			padding: 0.25em 0.8em 0.25em 1.6em;
+			padding: 0.25em 0.8em 0.25em calc(1.6em + var(--doc-nav-level, 0) * 0.85em);
 			color: var(--theme-color-text-secondary, #5E5549);
 			text-decoration: none;
 			font-size: 0.85em;
@@ -123,6 +123,25 @@ const _ViewConfiguration =
 		.pict-inline-doc-nav-item:hover {
 			background: var(--theme-color-background-tertiary, #EDE8DF);
 		}
+		.pict-inline-doc-nav-folder {
+			font-weight: 600;
+			color: var(--theme-color-text-primary, #3D3229);
+		}
+		.pict-inline-doc-nav-folder-icon {
+			margin-right: 0.4em;
+			vertical-align: -0.12em;
+			opacity: 0.65;
+		}
+		.pict-inline-doc-nav-file-icon {
+			margin-right: 0.4em;
+			vertical-align: -0.12em;
+			opacity: 0.55;
+		}
+		.pict-inline-doc-nav-section-dot {
+			margin-right: 0.4em;
+			vertical-align: -0.12em;
+			opacity: 0.3;
+		}
 		.pict-inline-doc-nav-item.active {
 			background: var(--theme-color-background-hover, #E8E3D8);
 			color: var(--theme-color-brand-primary, #2E7D74);
@@ -131,7 +150,7 @@ const _ViewConfiguration =
 		}
 		.pict-inline-doc-nav-heading {
 			display: block;
-			padding: 0.15em 0.8em 0.15em 2.4em;
+			padding: 0.15em 0.8em 0.15em calc(2.4em + var(--doc-nav-level, 0) * 0.85em);
 			color: var(--theme-color-text-muted, #8A7F72);
 			font-size: 0.78em;
 			cursor: pointer;
@@ -143,7 +162,7 @@ const _ViewConfiguration =
 			color: var(--theme-color-text-secondary, #5E5549);
 		}
 		.pict-inline-doc-nav-heading.h3 {
-			padding-left: 3.2em;
+			padding-left: calc(3.2em + var(--doc-nav-level, 0) * 0.85em);
 			font-size: 0.72em;
 		}
 		/* Search icon in collapsed header */
@@ -339,6 +358,16 @@ class InlineDocumentationNavView extends libPictView
 		let tmpFilterText = tmpState.NavFilterText || '';
 		let tmpCurrentDocName = this._resolveCurrentDocName(tmpState, tmpCurrentPath);
 
+		// Reflect the collapsed state on the nav CONTAINER (the layout owns its
+		// width). Collapsing then shrinks the whole panel to a thin strip and hands
+		// the freed width back to the content, instead of hiding the outline while
+		// the container stays full-width.
+		let tmpNavContainer = document.getElementById('InlineDoc-Nav-Container');
+		if (tmpNavContainer)
+		{
+			tmpNavContainer.classList.toggle('pict-inline-doc-nav-collapsed', tmpIsCollapsed);
+		}
+
 		let tmpHTML = '';
 
 		let tmpSearchQuery = tmpState.SearchQuery || '';
@@ -624,22 +653,44 @@ class InlineDocumentationNavView extends libPictView
 				let tmpActive = (pCurrentPath === tmpGroup.Path) ? ' active' : '';
 				tmpHTML += '<a class="pict-inline-doc-nav-item' + tmpActive
 					+ '" data-doc-path="' + this._escapeHTML(tmpGroup.Path) + '">'
+					+ this._fileIconSVG()
 					+ this._escapeHTML(tmpGroup.Name)
 					+ '</a>';
 
 				// If this is the active item, render heading sub-items
 				if (pCurrentPath === tmpGroup.Path)
 				{
-					tmpHTML += this._renderHeadingSubItems(pHeadings, tmpFilterLower);
+					tmpHTML += this._renderHeadingSubItems(pHeadings, tmpFilterLower, 0);
 				}
 			}
 
 			for (let j = 0; j < tmpGroupItems.length; j++)
 			{
 				let tmpItem = tmpGroupItems[j];
+				let tmpIndent = ' style="--doc-nav-level:' + (tmpItem.Level || 0) + '"';
+
+				// Sub-folder node (no document of its own). Indent it by its
+				// level and, when it has descendants, make it clickable so it
+				// opens its first child document; mark it with a folder glyph.
 				if (!tmpItem.Path)
 				{
-					tmpHTML += '<span class="pict-inline-doc-nav-item">' + this._escapeHTML(tmpItem.Name) + '</span>';
+					if (tmpItem.FirstChildPath)
+					{
+						// Folders are navigational shortcuts to their first child; the
+						// child item carries the active highlight, so the folder doesn't.
+						tmpHTML += '<a class="pict-inline-doc-nav-item pict-inline-doc-nav-folder'
+							+ '" data-doc-path="' + this._escapeHTML(tmpItem.FirstChildPath) + '"' + tmpIndent + '>'
+							+ this._folderIconSVG()
+							+ this._escapeHTML(tmpItem.Name)
+							+ '</a>';
+					}
+					else
+					{
+						tmpHTML += '<span class="pict-inline-doc-nav-item pict-inline-doc-nav-folder"' + tmpIndent + '>'
+							+ this._folderIconSVG()
+							+ this._escapeHTML(tmpItem.Name)
+							+ '</span>';
+					}
 					continue;
 				}
 
@@ -647,7 +698,8 @@ class InlineDocumentationNavView extends libPictView
 				{
 					// External link — opens in a new tab
 					tmpHTML += '<a class="pict-inline-doc-nav-item pict-inline-doc-nav-item-external'
-						+ '" data-external-url="' + this._escapeHTML(tmpItem.ExternalURL) + '">'
+						+ '" data-external-url="' + this._escapeHTML(tmpItem.ExternalURL) + '"' + tmpIndent + '>'
+						+ this._fileIconSVG()
 						+ this._escapeHTML(tmpItem.Name)
 						+ '<svg class="pict-inline-doc-nav-external-icon" width="0.75em" height="0.75em" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M12 9v4a1 1 0 01-1 1H3a1 1 0 01-1-1V5a1 1 0 011-1h4"/><polyline points="8,2 14,2 14,8"/><line x1="14" y1="2" x2="7" y2="9"/></svg>'
 						+ '</a>';
@@ -656,14 +708,15 @@ class InlineDocumentationNavView extends libPictView
 				{
 					let tmpActive = (pCurrentPath === tmpItem.Path) ? ' active' : '';
 					tmpHTML += '<a class="pict-inline-doc-nav-item' + tmpActive
-						+ '" data-doc-path="' + this._escapeHTML(tmpItem.Path) + '">'
+						+ '" data-doc-path="' + this._escapeHTML(tmpItem.Path) + '"' + tmpIndent + '>'
+						+ this._fileIconSVG()
 						+ this._escapeHTML(tmpItem.Name)
 						+ '</a>';
 
 					// If this is the active item, render heading sub-items
 					if (pCurrentPath === tmpItem.Path)
 					{
-						tmpHTML += this._renderHeadingSubItems(pHeadings, tmpFilterLower);
+						tmpHTML += this._renderHeadingSubItems(pHeadings, tmpFilterLower, tmpItem.Level || 0);
 					}
 				}
 			}
@@ -675,6 +728,40 @@ class InlineDocumentationNavView extends libPictView
 		return tmpHTML;
 	}
 
+	/**
+	 * A small folder glyph for sub-folder nav nodes. Uses currentColor so it
+	 * follows the theme like the other inline nav icons.
+	 *
+	 * @returns {string} inline SVG HTML
+	 */
+	_folderIconSVG()
+	{
+		return '<svg class="pict-inline-doc-nav-folder-icon" width="0.85em" height="0.85em" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M1.5 5a1 1 0 0 1 1-1h3.2l1.3 1.4h5.5a1 1 0 0 1 1 1V12a1 1 0 0 1-1 1h-11a1 1 0 0 1-1-1z"/></svg>';
+	}
+
+	/**
+	 * A small document glyph (a page with a folded corner) for markdown file
+	 * nodes. Same footprint as the folder glyph so files and folders line up at
+	 * the same depth.
+	 *
+	 * @returns {string} inline SVG HTML
+	 */
+	_fileIconSVG()
+	{
+		return '<svg class="pict-inline-doc-nav-file-icon" width="0.85em" height="0.85em" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M4 2.5H9L12 5.5V13.5H4Z"/><polyline points="9 2.5 9 5.5 12 5.5"/></svg>';
+	}
+
+	/**
+	 * A small filled dot marking an in-document section (a heading sub-item shown
+	 * beneath the active document). currentColor + low opacity keeps it quiet.
+	 *
+	 * @returns {string} inline SVG HTML
+	 */
+	_sectionDotSVG()
+	{
+		return '<svg class="pict-inline-doc-nav-section-dot" width="0.85em" height="0.85em" viewBox="0 0 16 16" aria-hidden="true"><circle cx="8" cy="8" r="2.3" fill="currentColor"/></svg>';
+	}
+
 	/**
 	 * Render heading sub-items (h2 and h3) beneath the active nav item.
 	 *
@@ -682,13 +769,16 @@ class InlineDocumentationNavView extends libPictView
 	 * @param {string} pFilterText - Lowercase filter text
 	 * @returns {string} HTML string for heading sub-items
 	 */
-	_renderHeadingSubItems(pHeadings, pFilterText)
+	_renderHeadingSubItems(pHeadings, pFilterText, pBaseLevel)
 	{
 		if (!pHeadings || pHeadings.length < 1)
 		{
 			return '';
 		}
 
+		// Indent the headings relative to their (possibly nested) parent
+		// document item, so they line up one notch under it at any tree depth.
+		let tmpLevelStyle = ' style="--doc-nav-level:' + (pBaseLevel || 0) + '"';
 		let tmpHTML = '';
 
 		for (let i = 0; i < pHeadings.length; i++)
@@ -704,7 +794,8 @@ class InlineDocumentationNavView extends libPictView
 
 			let tmpLevelClass = (tmpHeading.Level === 3) ? ' h3' : '';
 			tmpHTML += '<a class="pict-inline-doc-nav-heading' + tmpLevelClass
-				+ '" data-heading-slug="' + this._escapeHTML(tmpHeading.Slug) + '">'
+				+ '" data-heading-slug="' + this._escapeHTML(tmpHeading.Slug) + '"' + tmpLevelStyle + '>'
+				+ this._sectionDotSVG()
 				+ this._escapeHTML(tmpText)
 				+ '</a>';
 		}