pict-docuserve 1.3.2 → 1.3.3

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,6 +44,15 @@ class DocuserveDocumentationProvider extends libPictProvider
 	{
 		return (pHref, pLinkText) =>
 		{
+			// 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' };
+			}
 			// Convert internal doc links to hash routes
 			if (pHref.match(/^\//) || pHref.match(/^[^:]+\.md/))
 			{
@@ -728,6 +738,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 +757,47 @@ 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.  Normalizes an href to a #/page/ hash route.
+	 *
+	 * @param {string} pHref - The raw link href
+	 * @returns {string} A #/page/ hash route (#/Home for an empty path)
+	 */
+	_toModulePageRoute(pHref)
+	{
+		let tmpPath = String(pHref || '').replace(/^\.\//, '').replace(/^\//, '').replace(/\/+$/, '');
+		if (!tmpPath)
+		{
+			return '#/Home';
+		}
+		return '#/page/' + tmpPath.replace(/\.md$/i, '');
+	}
+
 	/**
 	 * Check whether a group/module pair exists in the loaded catalog.
 	 *
@@ -864,6 +916,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 +929,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 +1142,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 +1186,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 +1661,12 @@ class DocuserveDocumentationProvider extends libPictProvider
 	 */
 	convertDocLink(pHref, pCurrentGroup, pCurrentModule, pCurrentDocPath)
 	{
+		// Single-module docs site: every internal reference is a local page.
+		if (this.getDocsMode() === 'module')
+		{
+			return this._toModulePageRoute(pHref);
+		}
+
 		// Strip leading ./ prefix for relative paths
 		let tmpPath = pHref.replace(/^\.\//, '');
 		// Remove leading slash

package/dist/css/docuserve.css

@@ -1,327 +0,0 @@
-/* ============================================================================
-   Pict Docuserve - Base Styles & Theme Variables
-   ============================================================================ */
-
-/* ----------------------------------------------------------------------------
-   Theme variables — light defaults on :root.
-   Dark mode applies when either:
-     (a) the user explicitly selected dark via <html data-theme="dark">
-     (b) the user hasn't chosen anything AND the system prefers dark
-   An explicit <html data-theme="light"> pins the light palette regardless.
-   ---------------------------------------------------------------------------- */
-
-:root
-{
-	/* Surfaces */
-	--docuserve-bg: #FDFBF7;
-	--docuserve-bg-elevated: #FFFFFF;
-	--docuserve-border: #DDD6CA;
-	--docuserve-border-soft: #EAE3D8;
-
-	/* Text */
-	--docuserve-text: #2A241E;
-	--docuserve-text-strong: #3D3229;
-	--docuserve-text-muted: #5E5549;
-	--docuserve-text-dim: #8A7F72;
-
-	/* Accent / links */
-	--docuserve-accent: #2E7D74;
-	--docuserve-accent-hover: #236660;
-
-	/* Top bar */
-	--docuserve-topbar-bg: #3D3229;
-	--docuserve-topbar-text: #E8E0D4;
-	--docuserve-topbar-text-muted: #B5AA9A;
-	--docuserve-topbar-text-dim: #8A7F72;
-	--docuserve-topbar-hover-bg: #524438;
-	--docuserve-topbar-version-bg: rgba(255, 255, 255, 0.06);
-	--docuserve-topbar-version-border: rgba(255, 255, 255, 0.08);
-	--docuserve-topbar-version-text: #B5AA9A;
-
-	/* Sidebar */
-	--docuserve-sidebar-bg: #FAF7F1;
-	--docuserve-sidebar-border: #DDD6CA;
-	--docuserve-sidebar-border-soft: #E5DED1;
-	--docuserve-sidebar-text: #423D37;
-	--docuserve-sidebar-group-title: #3D3229;
-	--docuserve-sidebar-module-text: #5E5549;
-	--docuserve-sidebar-hover-bg: #EAE3D8;
-	--docuserve-sidebar-hover-text: #2E7D74;
-	--docuserve-sidebar-active-bg: #E5DED1;
-	--docuserve-sidebar-active-text: #2E7D74;
-	--docuserve-sidebar-search-bg: #FFFFFF;
-	--docuserve-sidebar-search-border: #DDD6CA;
-
-	/* Inline code */
-	--docuserve-inline-code-bg: #F0ECE4;
-	--docuserve-inline-code-text: #9E3A50;
-
-	/* Code block panel */
-	--docuserve-code-bg: #F6F3EE;
-	--docuserve-code-border: #E5DED1;
-	--docuserve-code-gutter-bg: #EFEAE0;
-	--docuserve-code-gutter-border: #DDD6CA;
-	--docuserve-code-gutter-text: #A59986;
-	--docuserve-code-text: #2A241E;
-
-	/* Syntax tokens — low-chroma dark-on-light palette */
-	--docuserve-tok-keyword: #A03472;
-	--docuserve-tok-string: #1A6640;
-	--docuserve-tok-number: #B25A00;
-	--docuserve-tok-comment: #8A7F72;
-	--docuserve-tok-operator: #2E7D74;
-	--docuserve-tok-punctuation: #2A241E;
-	--docuserve-tok-function: #2A5DB0;
-	--docuserve-tok-property: #9E3A50;
-	--docuserve-tok-tag: #9E3A50;
-	--docuserve-tok-attr-name: #B25A00;
-	--docuserve-tok-attr-value: #1A6640;
-
-	/* Tables, blockquotes, mermaid */
-	--docuserve-table-header-bg: #F5F0E8;
-	--docuserve-table-row-alt-bg: #F9F6F0;
-	--docuserve-blockquote-bg: #F7F5F0;
-	--docuserve-blockquote-border: #2E7D74;
-	--docuserve-blockquote-text: #5E5549;
-	--docuserve-mermaid-bg: #FFFFFF;
-
-	/* Scrollbars */
-	--docuserve-scrollbar-track: #F5F0E8;
-	--docuserve-scrollbar-thumb: #D4CCBE;
-	--docuserve-scrollbar-thumb-hover: #B5AA9A;
-}
-
-@media (prefers-color-scheme: dark)
-{
-	:root:not([data-theme="light"])
-	{
-		--docuserve-bg: #15120F;
-		--docuserve-bg-elevated: #1B1814;
-		--docuserve-border: #2F2823;
-		--docuserve-border-soft: #26211C;
-
-		--docuserve-text: #E8E0D4;
-		--docuserve-text-strong: #F2ECE0;
-		--docuserve-text-muted: #B5AA9A;
-		--docuserve-text-dim: #7A6F62;
-
-		--docuserve-accent: #5DB8A8;
-		--docuserve-accent-hover: #7FCCB8;
-
-		--docuserve-topbar-bg: #1A1612;
-		--docuserve-topbar-text: #E8E0D4;
-		--docuserve-topbar-text-muted: #B5AA9A;
-		--docuserve-topbar-text-dim: #7A6F62;
-		--docuserve-topbar-hover-bg: #2A241E;
-		--docuserve-topbar-version-bg: rgba(255, 255, 255, 0.05);
-		--docuserve-topbar-version-border: rgba(255, 255, 255, 0.09);
-		--docuserve-topbar-version-text: #B5AA9A;
-
-		--docuserve-sidebar-bg: #1B1814;
-		--docuserve-sidebar-border: #2F2823;
-		--docuserve-sidebar-border-soft: #26211C;
-		--docuserve-sidebar-text: #C9C0B3;
-		--docuserve-sidebar-group-title: #F2ECE0;
-		--docuserve-sidebar-module-text: #B5AA9A;
-		--docuserve-sidebar-hover-bg: #2A241E;
-		--docuserve-sidebar-hover-text: #7FCCB8;
-		--docuserve-sidebar-active-bg: #2F2823;
-		--docuserve-sidebar-active-text: #7FCCB8;
-		--docuserve-sidebar-search-bg: #26211C;
-		--docuserve-sidebar-search-border: #2F2823;
-
-		--docuserve-inline-code-bg: #2A241E;
-		--docuserve-inline-code-text: #E8B07A;
-
-		--docuserve-code-bg: #1E1A17;
-		--docuserve-code-border: #2F2823;
-		--docuserve-code-gutter-bg: #17130F;
-		--docuserve-code-gutter-border: #2F2823;
-		--docuserve-code-gutter-text: #6A6052;
-		--docuserve-code-text: #E8E0D4;
-
-		--docuserve-tok-keyword: #C678DD;
-		--docuserve-tok-string: #98C379;
-		--docuserve-tok-number: #D19A66;
-		--docuserve-tok-comment: #7F848E;
-		--docuserve-tok-operator: #56B6C2;
-		--docuserve-tok-punctuation: #E8E0D4;
-		--docuserve-tok-function: #61AFEF;
-		--docuserve-tok-property: #E06C75;
-		--docuserve-tok-tag: #E06C75;
-		--docuserve-tok-attr-name: #D19A66;
-		--docuserve-tok-attr-value: #98C379;
-
-		--docuserve-table-header-bg: #26211C;
-		--docuserve-table-row-alt-bg: #1F1B17;
-		--docuserve-blockquote-bg: #1F1B17;
-		--docuserve-blockquote-border: #5DB8A8;
-		--docuserve-blockquote-text: #C9C0B3;
-		--docuserve-mermaid-bg: #E8E0D4;
-
-		--docuserve-scrollbar-track: #1B1814;
-		--docuserve-scrollbar-thumb: #3A322B;
-		--docuserve-scrollbar-thumb-hover: #524438;
-	}
-}
-
-:root[data-theme="dark"]
-{
-	--docuserve-bg: #15120F;
-	--docuserve-bg-elevated: #1B1814;
-	--docuserve-border: #2F2823;
-	--docuserve-border-soft: #26211C;
-
-	--docuserve-text: #E8E0D4;
-	--docuserve-text-strong: #F2ECE0;
-	--docuserve-text-muted: #B5AA9A;
-	--docuserve-text-dim: #7A6F62;
-
-	--docuserve-accent: #5DB8A8;
-	--docuserve-accent-hover: #7FCCB8;
-
-	--docuserve-topbar-bg: #1A1612;
-	--docuserve-topbar-text: #E8E0D4;
-	--docuserve-topbar-text-muted: #B5AA9A;
-	--docuserve-topbar-text-dim: #7A6F62;
-	--docuserve-topbar-hover-bg: #2A241E;
-	--docuserve-topbar-version-bg: rgba(255, 255, 255, 0.05);
-	--docuserve-topbar-version-border: rgba(255, 255, 255, 0.09);
-	--docuserve-topbar-version-text: #B5AA9A;
-
-	--docuserve-sidebar-bg: #1B1814;
-	--docuserve-sidebar-border: #2F2823;
-	--docuserve-sidebar-border-soft: #26211C;
-	--docuserve-sidebar-text: #C9C0B3;
-	--docuserve-sidebar-group-title: #F2ECE0;
-	--docuserve-sidebar-module-text: #B5AA9A;
-	--docuserve-sidebar-hover-bg: #2A241E;
-	--docuserve-sidebar-hover-text: #7FCCB8;
-	--docuserve-sidebar-active-bg: #2F2823;
-	--docuserve-sidebar-active-text: #7FCCB8;
-	--docuserve-sidebar-search-bg: #26211C;
-	--docuserve-sidebar-search-border: #2F2823;
-
-	--docuserve-inline-code-bg: #2A241E;
-	--docuserve-inline-code-text: #E8B07A;
-
-	--docuserve-code-bg: #1E1A17;
-	--docuserve-code-border: #2F2823;
-	--docuserve-code-gutter-bg: #17130F;
-	--docuserve-code-gutter-border: #2F2823;
-	--docuserve-code-gutter-text: #6A6052;
-	--docuserve-code-text: #E8E0D4;
-
-	--docuserve-tok-keyword: #C678DD;
-	--docuserve-tok-string: #98C379;
-	--docuserve-tok-number: #D19A66;
-	--docuserve-tok-comment: #7F848E;
-	--docuserve-tok-operator: #56B6C2;
-	--docuserve-tok-punctuation: #E8E0D4;
-	--docuserve-tok-function: #61AFEF;
-	--docuserve-tok-property: #E06C75;
-	--docuserve-tok-tag: #E06C75;
-	--docuserve-tok-attr-name: #D19A66;
-	--docuserve-tok-attr-value: #98C379;
-
-	--docuserve-table-header-bg: #26211C;
-	--docuserve-table-row-alt-bg: #1F1B17;
-	--docuserve-blockquote-bg: #1F1B17;
-	--docuserve-blockquote-border: #5DB8A8;
-	--docuserve-blockquote-text: #C9C0B3;
-	--docuserve-mermaid-bg: #E8E0D4;
-
-	--docuserve-scrollbar-track: #1B1814;
-	--docuserve-scrollbar-thumb: #3A322B;
-	--docuserve-scrollbar-thumb-hover: #524438;
-}
-
-/* ----------------------------------------------------------------------------
-   Reset and base
-   ---------------------------------------------------------------------------- */
-
-*, *::before, *::after
-{
-	box-sizing: border-box;
-}
-
-html, body
-{
-	margin: 0;
-	padding: 0;
-	font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
-	font-size: 16px;
-	line-height: 1.5;
-	color: var(--docuserve-text);
-	background-color: var(--docuserve-bg);
-	-webkit-font-smoothing: antialiased;
-	-moz-osx-font-smoothing: grayscale;
-	transition: background-color 0.15s ease, color 0.15s ease;
-}
-
-/* Typography */
-h1, h2, h3, h4, h5, h6
-{
-	margin-top: 0;
-	line-height: 1.3;
-	color: var(--docuserve-text-strong);
-}
-
-a
-{
-	color: var(--docuserve-accent);
-	text-decoration: none;
-}
-
-a:hover
-{
-	color: var(--docuserve-accent-hover);
-}
-
-/* Application container */
-#Docuserve-Application-Container
-{
-	min-height: 100vh;
-}
-
-/* Utility: scrollbar styling */
-::-webkit-scrollbar
-{
-	width: 8px;
-	height: 8px;
-}
-
-::-webkit-scrollbar-track
-{
-	background: var(--docuserve-scrollbar-track);
-}
-
-::-webkit-scrollbar-thumb
-{
-	background: var(--docuserve-scrollbar-thumb);
-	border-radius: 4px;
-}
-
-::-webkit-scrollbar-thumb:hover
-{
-	background: var(--docuserve-scrollbar-thumb-hover);
-}
-
-/* Responsive adjustments */
-@media (max-width: 768px)
-{
-	html
-	{
-		font-size: 14px;
-	}
-
-	#Docuserve-Sidebar-Container
-	{
-		display: none;
-	}
-
-	.docuserve-body
-	{
-		flex-direction: column;
-	}
-}