pict-docuserve 1.4.12 → 1.4.13

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pict-docuserve",
-	"version": "1.4.12",
+	"version": "1.4.13",
 	"description": "Pict Documentation Server - A single-page documentation viewer built on Pict",
 	"main": "source/Pict-Application-Docuserve.js",
 	"bin": {

package/source/Pict-Application-Docuserve.js

@@ -236,6 +236,19 @@ class DocuserveApplication extends libPictApplication
 	 *   #/doc/<group>/<module>/<path>   -> navigateToModulePath(group, module, path)
 	 */
 	resolveHash()
+	{
+		this._resolveHashRoute();
+		// Keep the topbar "view source" (octocat) link pointed at whatever
+		// module the current route resolves to (fixed on per-module sites,
+		// changes per navigation on the aggregate).
+		let tmpTopBarUser = this.pict.views['Docuserve-TopBar-User'];
+		if (tmpTopBarUser && (typeof tmpTopBarUser.render === 'function'))
+		{
+			tmpTopBarUser.render();
+		}
+	}
+
+	_resolveHashRoute()
 	{
 		let tmpHash = (window.location.hash || '').replace(/^#\/?/, '');
 

package/source/cli/commands/Docuserve-Command-StageExamples.js

@@ -495,7 +495,7 @@ class DocuserveCommandStageExamples extends libCommandLineCommand
 		// The launch link is a plain browser link the browser resolves against
 		// the docs-root index.html — so it carries the full docs-root-relative
 		// path and works from the writeup's folder or anywhere else.
-		let tmpInner = `> **[▶ Launch the live app](${mdSafeUrl('examples/' + tmpName + '/index.html')})** — runs in your browser, opens in a new tab.`;
+		let tmpInner = `> **[Launch the live app](${mdSafeUrl('examples/' + tmpName + '/index.html')})** - runs in your browser, opens in a new tab.`;
 
 		let tmpText;
 		if (libFS.existsSync(tmpReadmePath))
@@ -542,7 +542,7 @@ class DocuserveCommandStageExamples extends libCommandLineCommand
 			// The writeup is a .md SPA route resolved relative to this index;
 			// the launch link is a plain browser link carrying the full
 			// docs-root-relative path.
-			return `| [${escapeTableCell(pEx.Title)}](${mdSafeUrl(pEx.Name + '/README.md')}) | ${tmpComplexity} | ${escapeTableCell(pEx.Summary)} | [▶ Launch](${mdSafeUrl('examples/' + pEx.Name + '/index.html')}) |`;
+			return `| [${escapeTableCell(pEx.Title)}](${mdSafeUrl(pEx.Name + '/README.md')}) | ${tmpComplexity} | ${escapeTableCell(pEx.Summary)} | [Launch](${mdSafeUrl('examples/' + pEx.Name + '/index.html')}) |`;
 		});
 		let tmpInner = [
 			'| Example | Complexity | Summary | Live |',
@@ -584,7 +584,7 @@ class DocuserveCommandStageExamples extends libCommandLineCommand
 		let tmpRows = pStaged.map((pEx) =>
 		{
 			let tmpComplexity = escapeTableCell(pEx.Complexity) || '—';
-			return `| [${escapeTableCell(pEx.Title)}](${mdSafeUrl('examples/' + pEx.Name + '/README.md')}) | ${tmpComplexity} | [▶ Launch](${mdSafeUrl('examples/' + pEx.Name + '/index.html')}) |`;
+			return `| [${escapeTableCell(pEx.Title)}](${mdSafeUrl('examples/' + pEx.Name + '/README.md')}) | ${tmpComplexity} | [Launch](${mdSafeUrl('examples/' + pEx.Name + '/index.html')}) |`;
 		});
 		let tmpInner = [
 			'| Example | Complexity | Launch |',

package/source/providers/Pict-Provider-Docuserve-Documentation.js

@@ -26,6 +26,20 @@ class DocuserveDocumentationProvider extends libPictProvider
 
 		// Create an instance of the content provider for markdown parsing
 		this._ContentProvider = this.pict.addProvider('Pict-Content', libPictContentProvider.default_configuration, libPictContentProvider);
+
+		// Register the GitHub mark icon scoped to docuserve (NOT pict core --
+		// most pict apps don't need it). Powers the topbar "view source" link.
+		// Official GitHub mark, painted with currentColor so it follows the theme.
+		if (this.pict && this.pict.providers && this.pict.providers.Icon && (typeof this.pict.providers.Icon.registerSet === 'function'))
+		{
+			this.pict.providers.Icon.registerSet(
+				{
+					Outline:
+					{
+						GitHub: '<svg viewBox="0 0 16 16" fill="currentColor" aria-hidden="true"><path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg>'
+					}
+				});
+		}
 	}
 
 	/**
@@ -62,12 +76,15 @@ class DocuserveDocumentationProvider extends libPictProvider
 				let tmpRoute = this.convertDocLink(tmpHref, pCurrentGroup, pCurrentModule, pCurrentDocPath);
 				return { href: tmpRoute };
 			}
-			// Check if this is a GitHub URL that matches a catalog module
-			let tmpCatalogRoute = this.resolveGitHubURLToRoute(tmpHref);
-			if (tmpCatalogRoute)
-			{
-				return { href: tmpCatalogRoute };
-			}
+			// GitHub URLs (github.com/org/repo, /blob/..., /issues, "Source"
+			// links, etc.) are intentionally left as external links and open on
+			// GitHub exactly as written. Earlier versions auto-rewrote any
+			// github.com URL that matched a catalog module into an internal #/doc/
+			// route, which "hijacked" Source / View-on-GitHub links and links to
+			// specific files or issues. Cross-module documentation references
+			// should instead use docuserve routes (e.g. /pict/pict-view/), which
+			// the rule above resolves through the catalog. resolveGitHubURLToRoute()
+			// remains available as an explicit utility for code that wants it.
 			// Module mode: a remaining relative link (a directory, a media
 			// file, a .json) is resolved against the current document's
 			// directory too, so it shares the one base every other link uses
@@ -1579,6 +1596,49 @@ class DocuserveDocumentationProvider extends libPictProvider
 		return null;
 	}
 
+	/**
+	 * Resolve the GitHub source-repository URL for a module.
+	 *
+	 * Returns a URL like https://github.com/fable-retold/pict-view. Used by
+	 * the docuserve topbar "view source" (octocat) link so every docs site
+	 * links back to the repo it documents. Honours a per-module Org field
+	 * when the catalog carries one (manifest-driven), else the catalog org.
+	 *
+	 * @param {string} pGroup - The group key
+	 * @param {string} pModule - The module name
+	 * @returns {string|null} The GitHub repository URL or null
+	 */
+	resolveGitHubRepoURL(pGroup, pModule)
+	{
+		if (!this._Catalog || !this._Catalog.Groups)
+		{
+			return null;
+		}
+
+		for (let i = 0; i < this._Catalog.Groups.length; i++)
+		{
+			let tmpGroup = this._Catalog.Groups[i];
+			if (tmpGroup.Key !== pGroup)
+			{
+				continue;
+			}
+
+			for (let j = 0; j < tmpGroup.Modules.length; j++)
+			{
+				let tmpModule = tmpGroup.Modules[j];
+				if (tmpModule.Name !== pModule)
+				{
+					continue;
+				}
+
+				let tmpOrg = tmpModule.Org || this._Catalog.GitHubOrg || 'stevenvelozo';
+				return 'https://github.com/' + tmpOrg + '/' + tmpModule.Repo;
+			}
+		}
+
+		return null;
+	}
+
 	/**
 	 * Get the module-specific sidebar entries for a given group/module.
 	 *

package/source/views/PictView-Docuserve-TopBar-User.js

@@ -46,6 +46,17 @@ const _ViewConfiguration =
 			background-color: var(--theme-color-background-hover, rgba(255, 255, 255, 0.06));
 			color: var(--theme-color-text-on-brand, var(--theme-color-text-primary, #E8E0D4));
 		}
+		.docuserve-user a.docuserve-repo-link
+		{
+			display: inline-flex;
+			align-items: center;
+			font-size: 1.15em;
+			padding: 0.35em 0.5em;
+		}
+		.docuserve-user a.docuserve-repo-link .docuserve-octocat
+		{
+			line-height: 0;
+		}
 	`,
 
 	Templates:
@@ -105,6 +116,26 @@ class DocuserveTopBarUserView extends libPictView
 				tmpHTML += '<a href="' + tmpHref + '"' + (tmpIsExternal ? ' target="_blank" rel="noopener"' : '') + '>' + tmpText + '</a>';
 			}
 		}
+		// "View source" — octocat link to the current module's GitHub repo, so
+		// every docs site links back to the source it documents (fixed on a
+		// per-module site, follows the current module on the aggregate).
+		let tmpGroup = tmpDocuserve.CurrentGroup;
+		let tmpModule = tmpDocuserve.CurrentModule;
+		if (tmpGroup && tmpModule)
+		{
+			let tmpDocProvider = this.pict.providers['Docuserve-Documentation'];
+			let tmpRepoURL = (tmpDocProvider && (typeof tmpDocProvider.resolveGitHubRepoURL === 'function'))
+				? tmpDocProvider.resolveGitHubRepoURL(tmpGroup, tmpModule)
+				: null;
+			if (tmpRepoURL)
+			{
+				let tmpIcon = this.pict.icon('GitHub', { class: 'docuserve-octocat', ariaLabel: 'View source on GitHub' });
+				tmpHTML += '<a class="docuserve-repo-link" href="' + this._escapeHTML(tmpRepoURL) + '"'
+					+ ' target="_blank" rel="noopener"'
+					+ ' title="View ' + this._escapeHTML(tmpModule) + ' source on GitHub">'
+					+ tmpIcon + '</a>';
+			}
+		}
 		tmpEl.innerHTML = tmpHTML;
 	}