pict-docuserve 1.3.2 → 1.3.4

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

@@ -17,6 +17,7 @@ class DocuserveDocumentationProvider extends libPictProvider
 		super(pFable, pOptions, pServiceHash);
 
 		this._Catalog = null;
+		this._KeywordIndexMode = null;
 		this._ContentCache = {};
 		// (group, module) -> playground config | null (negative cache).
 		// Loaded lazily by loadPlaygroundConfig on first navigation into
@@ -43,18 +44,44 @@ class DocuserveDocumentationProvider extends libPictProvider
 	{
 		return (pHref, pLinkText) =>
 		{
+			let tmpHref = String(pHref || '');
+			let tmpIsModuleMode = (this.getDocsMode() === 'module');
+
+			// Built example applications (and other static .html pages) are
+			// served as plain files alongside the docs.  Link straight to
+			// them in a new tab rather than SPA-routing through #/page/.  In
+			// module mode the href is resolved against the current
+			// document's directory, exactly the way a .md link is — so every
+			// relative link in the docs shares one base.
+			if (!tmpHref.match(/^[a-z][a-z0-9+.-]*:/i) && tmpHref.match(/\.html($|[?#])/i))
+			{
+				let tmpAssetHref = tmpIsModuleMode ? this._toModuleAssetHref(tmpHref, pCurrentDocPath) : tmpHref;
+				return { href: tmpAssetHref, target: '_blank', rel: 'noopener' };
+			}
 			// Convert internal doc links to hash routes
-			if (pHref.match(/^\//) || pHref.match(/^[^:]+\.md/))
+			if (tmpHref.match(/^\//) || tmpHref.match(/^[^:]+\.md/))
 			{
-				let tmpRoute = this.convertDocLink(pHref, pCurrentGroup, pCurrentModule, pCurrentDocPath);
+				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(pHref);
+			let tmpCatalogRoute = this.resolveGitHubURLToRoute(tmpHref);
 			if (tmpCatalogRoute)
 			{
 				return { href: tmpCatalogRoute };
 			}
+			// 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
+			// rather than silently falling back to the docs root.
+			if (tmpIsModuleMode
+				&& tmpHref
+				&& (tmpHref.charAt(0) !== '#')
+				&& (tmpHref.indexOf('//') !== 0)
+				&& !tmpHref.match(/^[a-z][a-z0-9+.-]*:/i))
+			{
+				return { href: this._toModuleAssetHref(tmpHref, pCurrentDocPath) };
+			}
 			// Use default behavior for other links
 			return null;
 		};
@@ -306,15 +333,38 @@ class DocuserveDocumentationProvider extends libPictProvider
 			Tagline: '',
 			Description: '',
 			Highlights: [],
-			Actions: []
+			Actions: [],
+			ExamplesMarkdown: ''
 		};
 
 		let tmpLines = pMarkdown.split('\n');
+		let tmpInExamples = false;
 
 		for (let i = 0; i < tmpLines.length; i++)
 		{
 			let tmpLine = tmpLines[i].trim();
 
+			// Generated examples region — collected verbatim for the splash's
+			// "Interactive Examples" section, never parsed as cover fields.
+			if (tmpLine === '<!-- docuserve:examples:start -->')
+			{
+				tmpInExamples = true;
+				continue;
+			}
+			if (tmpLine === '<!-- docuserve:examples:end -->')
+			{
+				tmpInExamples = false;
+				continue;
+			}
+			if (tmpInExamples)
+			{
+				if (tmpLine)
+				{
+					tmpCover.ExamplesMarkdown += (tmpCover.ExamplesMarkdown ? '\n' : '') + tmpLine;
+				}
+				continue;
+			}
+
 			if (!tmpLine)
 			{
 				continue;
@@ -728,6 +778,7 @@ class DocuserveDocumentationProvider extends libPictProvider
 				{
 					this._LunrIndex = libLunr.Index.load(pIndexData.LunrIndex);
 					this._KeywordDocuments = pIndexData.Documents;
+					this._KeywordIndexMode = (pIndexData.Mode === 'module' || pIndexData.Mode === 'ecosystem') ? pIndexData.Mode : null;
 					this.pict.AppData.Docuserve.KeywordIndexLoaded = true;
 					this.pict.AppData.Docuserve.KeywordDocumentCount = pIndexData.DocumentCount || 0;
 					this.log.info(`Docuserve: Keyword index loaded (${pIndexData.DocumentCount || 0} documents).`);
@@ -746,6 +797,141 @@ class DocuserveDocumentationProvider extends libPictProvider
 			});
 	}
 
+	/**
+	 * Resolve the documentation site mode.
+	 *
+	 *   'module'    — a single module's own docs site; every doc is a local
+	 *                 page (#/page/<docpath>).
+	 *   'ecosystem' — a catalog of <group>/<module> repos (#/doc/...).
+	 *   'legacy'    — built before the Mode stamp existed; callers keep the
+	 *                 pre-Mode heuristic so old docs sites are unaffected.
+	 *
+	 * @returns {string} 'module' | 'ecosystem' | 'legacy'
+	 */
+	getDocsMode()
+	{
+		if (this._Catalog && (this._Catalog.Mode === 'module' || this._Catalog.Mode === 'ecosystem'))
+		{
+			return this._Catalog.Mode;
+		}
+		if (this._KeywordIndexMode === 'module' || this._KeywordIndexMode === 'ecosystem')
+		{
+			return this._KeywordIndexMode;
+		}
+		return 'legacy';
+	}
+
+	/**
+	 * Module-mode link resolution: every internal documentation reference is
+	 * a local page.  Relative links (./sibling.md, ../other.md, bare names)
+	 * resolve against the directory of the document that contains them — the
+	 * way the links read on disk — while a /-rooted href resolves against the
+	 * docs root.  "." and ".." segments are collapsed; ".." is clamped at the
+	 * docs root so a link can never escape above it.
+	 *
+	 * @param {string} pHref - The raw link href
+	 * @param {string} [pCurrentDocPath] - Docs-root-relative path of the
+	 *                  document the link lives in (e.g.
+	 *                  "examples/gradebook/README.md").  Absent for root-level
+	 *                  contexts such as the sidebar.
+	 * @returns {string} A #/page/ hash route (#/Home for an empty path)
+	 */
+	_toModulePageRoute(pHref, pCurrentDocPath)
+	{
+		let tmpHref = String(pHref || '').trim();
+
+		// A /-rooted href resolves against the docs root; every other href
+		// resolves against the current document's directory.
+		let tmpBaseDir = '';
+		if (tmpHref.charAt(0) === '/')
+		{
+			tmpHref = tmpHref.replace(/^\/+/, '');
+		}
+		else if (pCurrentDocPath)
+		{
+			let tmpDirParts = String(pCurrentDocPath).split('/');
+			tmpDirParts.pop();
+			tmpBaseDir = tmpDirParts.join('/');
+		}
+
+		let tmpPath = this._resolveRelativeDocPath(tmpBaseDir, tmpHref);
+		if (!tmpPath)
+		{
+			return '#/Home';
+		}
+		return '#/page/' + tmpPath.replace(/\.md$/i, '');
+	}
+
+	/**
+	 * Resolve a relative href against a base directory, collapsing "." and
+	 * ".." segments.  ".." is clamped at the docs root — it can never escape
+	 * above it.  Both arguments are POSIX-style docs-root-relative paths.
+	 *
+	 * @param {string} pBaseDir - The directory the href is relative to.
+	 * @param {string} pHref - The href to resolve.
+	 * @returns {string} The resolved docs-root-relative path (no leading slash).
+	 */
+	_resolveRelativeDocPath(pBaseDir, pHref)
+	{
+		let tmpSegments = [];
+		let tmpCombined = (pBaseDir ? pBaseDir + '/' : '') + String(pHref || '');
+		let tmpParts = tmpCombined.split('/');
+		for (let i = 0; i < tmpParts.length; i++)
+		{
+			let tmpPart = tmpParts[i];
+			if ((tmpPart === '') || (tmpPart === '.'))
+			{
+				continue;
+			}
+			if (tmpPart === '..')
+			{
+				if (tmpSegments.length > 0)
+				{
+					tmpSegments.pop();
+				}
+				continue;
+			}
+			tmpSegments.push(tmpPart);
+		}
+		return tmpSegments.join('/');
+	}
+
+	/**
+	 * Module-mode resolution for a non-routed link — a built .html page, a
+	 * media file, a directory.  Resolves the href against the current
+	 * document's directory (a /-rooted href against the docs root), the same
+	 * way _toModulePageRoute resolves a .md link, and returns a plain
+	 * docs-root-relative href.  The browser resolves that href against the
+	 * docs-root index.html, so it points at the right file from any page.
+	 *
+	 * @param {string} pHref - The raw link href
+	 * @param {string} [pCurrentDocPath] - Docs-root-relative path of the
+	 *                  document the link lives in.
+	 * @returns {string} A docs-root-relative href.
+	 */
+	_toModuleAssetHref(pHref, pCurrentDocPath)
+	{
+		let tmpHref = String(pHref || '').trim();
+		if (!tmpHref)
+		{
+			return tmpHref;
+		}
+
+		let tmpBaseDir = '';
+		if (tmpHref.charAt(0) === '/')
+		{
+			tmpHref = tmpHref.replace(/^\/+/, '');
+		}
+		else if (pCurrentDocPath)
+		{
+			let tmpDirParts = String(pCurrentDocPath).split('/');
+			tmpDirParts.pop();
+			tmpBaseDir = tmpDirParts.join('/');
+		}
+
+		return this._resolveRelativeDocPath(tmpBaseDir, tmpHref);
+	}
+
 	/**
 	 * Check whether a group/module pair exists in the loaded catalog.
 	 *
@@ -864,6 +1050,7 @@ class DocuserveDocumentationProvider extends libPictProvider
 		try
 		{
 			let tmpLunrResults = this._LunrIndex.search(pQuery);
+			let tmpMode = this.getDocsMode();
 
 			for (let i = 0; i < tmpLunrResults.length; i++)
 			{
@@ -876,24 +1063,37 @@ class DocuserveDocumentationProvider extends libPictProvider
 					continue;
 				}
 
-				// Build the hash route from the document key (group/module/docpath)
-				let tmpParts = tmpRef.split('/');
+				// Build the hash route for this result based on the site mode.
 				let tmpRoute = '';
-				if (tmpParts.length >= 2)
+				if (tmpMode === 'module')
 				{
-					// Check whether this group/module exists in the catalog.
-					// If it does, route to #/doc/ which fetches from GitHub.
-					// If not, fall back to #/page/ which fetches locally.
-					let tmpGroup = tmpParts[0];
-					let tmpModule = tmpParts[1];
-
-					if (this.isModuleInCatalog(tmpGroup, tmpModule))
+					// Single-module site: every doc is a local page; the
+					// keyword-index key is the docs-relative path.
+					tmpRoute = '#/page/' + (tmpDoc.DocPath || tmpRef);
+				}
+				else if (tmpMode === 'ecosystem')
+				{
+					// Ecosystem: catalog modules render from their GitHub docs.
+					if (tmpDoc.Group && tmpDoc.Module && tmpDoc.DocPath)
+					{
+						tmpRoute = '#/doc/' + tmpDoc.Group + '/' + tmpDoc.Module + '/' + tmpDoc.DocPath;
+					}
+					else
+					{
+						tmpRoute = '#/page/' + tmpRef;
+					}
+				}
+				else
+				{
+					// Legacy keyword index (no Mode stamp) — the pre-Mode
+					// heuristic: split the key and check the catalog.
+					let tmpParts = tmpRef.split('/');
+					if (tmpParts.length >= 2 && this.isModuleInCatalog(tmpParts[0], tmpParts[1]))
 					{
 						tmpRoute = '#/doc/' + tmpRef;
 					}
 					else
 					{
-						// Local document — route via #/page/ using the full ref path
 						tmpRoute = '#/page/' + tmpRef;
 					}
 				}
@@ -1076,6 +1276,14 @@ class DocuserveDocumentationProvider extends libPictProvider
 			return '';
 		}
 
+		// Already a fully-formed hash route (e.g. "#/page/examples/foo/README").
+		// Pass it straight through — the author has named the exact route, so
+		// do not re-derive one (re-deriving would mangle it into "#/page/#/...").
+		if (pHref.match(/^#\//))
+		{
+			return pHref;
+		}
+
 		// Root home link
 		if (pHref === '/')
 		{
@@ -1112,6 +1320,21 @@ class DocuserveDocumentationProvider extends libPictProvider
 			return '#/Home';
 		}
 
+		// Static .html pages (built example apps, etc.) — link straight to
+		// the file rather than SPA-routing it through #/page/.  Scoped
+		// strictly to the .html extension.
+		if (pHref.match(/\.html($|[?#])/i) && !pHref.match(/^[a-z][a-z0-9+.-]*:/i))
+		{
+			return pHref;
+		}
+
+		// Single-module docs site: every internal reference is a local page —
+		// no catalog #/doc/ routing, no group/module guesswork.
+		if (this.getDocsMode() === 'module')
+		{
+			return this._toModulePageRoute(pHref);
+		}
+
 		// Strip leading/trailing slashes for parsing
 		let tmpPath = pHref.replace(/^\//, '').replace(/\/$/, '');
 
@@ -1572,6 +1795,13 @@ class DocuserveDocumentationProvider extends libPictProvider
 	 */
 	convertDocLink(pHref, pCurrentGroup, pCurrentModule, pCurrentDocPath)
 	{
+		// Single-module docs site: every internal reference is a local page,
+		// resolved relative to the current document's directory.
+		if (this.getDocsMode() === 'module')
+		{
+			return this._toModulePageRoute(pHref, pCurrentDocPath);
+		}
+
 		// Strip leading ./ prefix for relative paths
 		let tmpPath = pHref.replace(/^\.\//, '');
 		// Remove leading slash

package/source/views/PictView-Docuserve-Splash.js

@@ -111,6 +111,70 @@ const _ViewConfiguration =
 			border-color: var(--theme-color-brand-primary-hover, #236660);
 			color: var(--theme-color-brand-primary, #2E7D74);
 		}
+		.docuserve-splash-examples {
+			max-width: 900px;
+			width: 100%;
+			margin-bottom: 2.5em;
+		}
+		/* No staged examples — collapse the section entirely. */
+		.docuserve-splash-examples:empty {
+			display: none;
+			margin: 0;
+		}
+		.docuserve-splash-examples-heading {
+			font-size: 0.95em;
+			font-weight: 700;
+			text-transform: uppercase;
+			letter-spacing: 0.08em;
+			color: var(--theme-color-text-muted, #8A7F72);
+			margin: 0 0 0.85em 0;
+		}
+		.docuserve-splash-examples table {
+			width: 100%;
+			border-collapse: collapse;
+			background: var(--theme-color-background-panel, #FFFFFF);
+			border: 1px solid var(--theme-color-border-default, #DDD6CA);
+			border-radius: 8px;
+			overflow: hidden;
+		}
+		.docuserve-splash-examples thead th {
+			text-align: left;
+			font-size: 0.72em;
+			font-weight: 700;
+			text-transform: uppercase;
+			letter-spacing: 0.06em;
+			color: var(--theme-color-text-muted, #8A7F72);
+			padding: 0.7em 1.1em;
+			background: var(--theme-color-background-tertiary, #F4EFE6);
+		}
+		.docuserve-splash-examples tbody td {
+			padding: 0.7em 1.1em;
+			border-top: 1px solid var(--theme-color-border-default, #DDD6CA);
+			font-size: 0.9em;
+			color: var(--theme-color-text-secondary, #5E5549);
+			text-align: left;
+		}
+		.docuserve-splash-examples tbody tr:hover td {
+			background: var(--theme-color-background-tertiary, #F4EFE6);
+		}
+		.docuserve-splash-examples a {
+			color: var(--theme-color-brand-primary, #2E7D74);
+			font-weight: 600;
+			text-decoration: none;
+		}
+		.docuserve-splash-examples a:hover {
+			text-decoration: underline;
+		}
+		/* docs/README.md content rendered beneath the hero. */
+		.docuserve-splash-readme {
+			max-width: 820px;
+			margin: 0 auto;
+			padding: 3.5em 2em 5em 2em;
+			text-align: left;
+		}
+		.docuserve-splash-readme:empty {
+			display: none;
+		}
 	`,
 
 	Templates:
@@ -123,8 +187,10 @@ const _ViewConfiguration =
 	<div class="docuserve-splash-tagline" id="Docuserve-Splash-Tagline"></div>
 	<div class="docuserve-splash-description" id="Docuserve-Splash-Description"></div>
 	<div class="docuserve-splash-highlights" id="Docuserve-Splash-Highlights"></div>
+	<div class="docuserve-splash-examples" id="Docuserve-Splash-Examples"></div>
 	<div class="docuserve-splash-actions" id="Docuserve-Splash-Actions"></div>
 </div>
+<div class="docuserve-splash-readme" id="Docuserve-Splash-Readme"></div>
 `
 		}
 	],
@@ -154,12 +220,17 @@ class DocusserveSplashView extends libPictView
 		if (tmpDocuserve.CoverLoaded && tmpDocuserve.Cover)
 		{
 			this.renderFromCover(tmpDocuserve.Cover);
+			this.renderExamples(tmpDocuserve.Cover);
 		}
 		else
 		{
 			this.renderFromCatalog(tmpDocuserve);
 		}
 
+		// Render docs/README.md beneath the hero — the splash fills the
+		// viewport above the fold, the README content follows on scroll.
+		this.renderReadme();
+
 		return super.onAfterRender(pRenderable, pRenderDestinationAddress, pRecord, pContent);
 	}
 
@@ -270,6 +341,61 @@ class DocusserveSplashView extends libPictView
 		this.pict.ContentAssignment.assignContent('#Docuserve-Splash-Actions', '');
 	}
 
+	/**
+	 * Render the "Interactive Examples" section of the splash from the
+	 * examples region of _cover.md.  When the cover carries no examples the
+	 * section is left empty — CSS collapses it — so it appears only when a
+	 * module has staged interactive examples.
+	 *
+	 * @param {Object} pCover - The parsed cover data.
+	 */
+	renderExamples(pCover)
+	{
+		let tmpExamplesMarkdown = (pCover && pCover.ExamplesMarkdown) ? pCover.ExamplesMarkdown : '';
+		let tmpDocProvider = this.pict.providers['Docuserve-Documentation'];
+
+		if (!tmpExamplesMarkdown || !tmpDocProvider || !tmpDocProvider._ContentProvider)
+		{
+			this.pict.ContentAssignment.assignContent('#Docuserve-Splash-Examples', '');
+			return;
+		}
+
+		let tmpLinkResolver = tmpDocProvider._createLinkResolver('', '', '');
+		let tmpExamplesHTML = tmpDocProvider._ContentProvider.parseMarkdown(tmpExamplesMarkdown, tmpLinkResolver);
+		this.pict.ContentAssignment.assignContent('#Docuserve-Splash-Examples',
+			'<h2 class="docuserve-splash-examples-heading">Interactive Examples</h2>' + tmpExamplesHTML);
+	}
+
+	/**
+	 * Render docs/README.md beneath the splash hero.  The landing page is the
+	 * full-viewport splash above the fold and the module's README content on
+	 * scroll.  A missing or unreadable README simply leaves the section empty.
+	 */
+	renderReadme()
+	{
+		let tmpDocProvider = this.pict.providers['Docuserve-Documentation'];
+		let tmpDocsBase = this.pict.AppData.Docuserve.DocsBaseURL || '';
+
+		fetch(tmpDocsBase + 'README.md')
+			.then((pResponse) => (pResponse.ok ? pResponse.text() : null))
+			.then((pMarkdown) =>
+			{
+				if (!pMarkdown || !tmpDocProvider || !tmpDocProvider._ContentProvider)
+				{
+					this.pict.ContentAssignment.assignContent('#Docuserve-Splash-Readme', '');
+					return;
+				}
+				let tmpLinkResolver = tmpDocProvider._createLinkResolver('', '', 'README.md');
+				let tmpImageResolver = tmpDocProvider._createImageResolver(tmpDocsBase + 'README.md');
+				let tmpHTML = tmpDocProvider._ContentProvider.parseMarkdown(pMarkdown, tmpLinkResolver, tmpImageResolver);
+				this.pict.ContentAssignment.assignContent('#Docuserve-Splash-Readme', '<div class="pict-content">' + tmpHTML + '</div>');
+			})
+			.catch(() =>
+			{
+				this.pict.ContentAssignment.assignContent('#Docuserve-Splash-Readme', '');
+			});
+	}
+
 	/**
 	 * Sanitize a title string, preserving only <small> tags.
 	 * All other HTML is escaped.