pict-docuserve 1.3.3 → 1.3.4

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

@@ -44,27 +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/.
-			// Scoped strictly to the .html extension — .md pages, catalog
-			// routes and http(s):// links fall through unaffected.
-			if (!pHref.match(/^[a-z][a-z0-9+.-]*:/i) && pHref.match(/\.html($|[?#])/i))
-			{
-				return { href: pHref, target: '_blank', rel: 'noopener' };
+			// 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;
 		};
@@ -316,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;
@@ -783,14 +823,38 @@ class DocuserveDocumentationProvider extends libPictProvider
 
 	/**
 	 * Module-mode link resolution: every internal documentation reference is
-	 * a local page.  Normalizes an href to a #/page/ hash route.
+	 * 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)
+	_toModulePageRoute(pHref, pCurrentDocPath)
 	{
-		let tmpPath = String(pHref || '').replace(/^\.\//, '').replace(/^\//, '').replace(/\/+$/, '');
+		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';
@@ -798,6 +862,76 @@ class DocuserveDocumentationProvider extends libPictProvider
 		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.
 	 *
@@ -1661,10 +1795,11 @@ class DocuserveDocumentationProvider extends libPictProvider
 	 */
 	convertDocLink(pHref, pCurrentGroup, pCurrentModule, pCurrentDocPath)
 	{
-		// Single-module docs site: every internal reference is a local page.
+		// 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);
+			return this._toModulePageRoute(pHref, pCurrentDocPath);
 		}
 
 		// Strip leading ./ prefix for relative paths

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.