pict-docuserve 1.4.0 → 1.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pict-docuserve",
-	"version": "1.4.0",
+	"version": "1.4.2",
 	"description": "Pict Documentation Server - A single-page documentation viewer built on Pict",
 	"main": "source/Pict-Application-Docuserve.js",
 	"bin": {
@@ -14,9 +14,7 @@
 	"scripts": {
 		"start": "node source/cli/Docuserve-CLI-Run.js serve",
 		"brand": "node node_modules/pict-section-theme/bin/pict-section-theme-brand.js --manifest ../../../Retold-Modules-Manifest.json --module pict-docuserve",
-		"prebuild": "npm run brand",
 		"build": "npx quack build && npx quack copy",
-		"prebuild-docs": "npm run brand",
 		"build-docs": "npx quack build && npx quack copy && node source/cli/Docuserve-CLI-Run.js inject ./docs && node example_applications/build-examples.js stage-docs",
 		"serve-docs": "node source/cli/Docuserve-CLI-Run.js serve ./docs",
 		"serve-examples": "node example_applications/build-examples.js",
@@ -34,16 +32,16 @@
 		"pict-application": "^1.0.34",
 		"pict-provider": "^1.0.13",
 		"pict-section-code": "^1.0.11",
-		"pict-section-content": "^1.0.4",
+		"pict-section-content": "^1.0.5",
 		"pict-section-histogram": "^1.0.1",
-		"pict-section-modal": "^1.1.3",
+		"pict-section-modal": "^1.1.4",
 		"pict-section-theme": "^1.0.6",
 		"pict-service-commandlineutility": "^1.0.19",
 		"pict-view": "^1.0.68"
 	},
 	"devDependencies": {
-		"pict-docuserve": "^1.3.3",
-		"quackage": "^1.2.4"
+		"pict-docuserve": "^1.4.1",
+		"quackage": "^1.2.5"
 	},
 	"copyFilesSettings": {
 		"whenFileExists": "overwrite"

package/source/Pict-Application-Docuserve.js

@@ -23,6 +23,7 @@ const libViewContent      = require('./views/PictView-Docuserve-Content.js');
 const libViewSearch       = require('./views/PictView-Docuserve-Search.js');
 const libViewDemo         = require('./views/PictView-Docuserve-Demo.js');
 const libViewFablePlayground = require('./views/PictView-Docuserve-Fable-Playground.js');
+const libViewSectionPlayground = require('./views/PictView-Docuserve-Section-Playground.js');
 
 class DocuserveApplication extends libPictApplication
 {
@@ -55,6 +56,7 @@ class DocuserveApplication extends libPictApplication
 		this.pict.addView('Docuserve-Search',       libViewSearch.default_configuration,       libViewSearch);
 		this.pict.addView('Docuserve-Demo',         libViewDemo.default_configuration,         libViewDemo);
 		this.pict.addView('Docuserve-Fable-Playground', libViewFablePlayground.default_configuration, libViewFablePlayground);
+		this.pict.addView('Docuserve-Section-Playground', libViewSectionPlayground.default_configuration, libViewSectionPlayground);
 
 		// Theme-Section is added later from onAfterInitializeAsync, after
 		// the brand has been resolved.  Docuserve is a viewer — the docs
@@ -288,10 +290,23 @@ class DocuserveApplication extends libPictApplication
 			return;
 		}
 
-		// #/playground/<kind> — live editor + sandbox for trying Fable
-		// (eventually Pict too).
+		// #/playground/<kind> — live editor + sandbox.  Three shapes:
+		//   #/playground/fable                       — Fable JS REPL (bottom drawer)
+		//   #/playground/section                     — section playground for the
+		//                                              current module (standalone-mode
+		//                                              docs site)
+		//   #/playground/section/<group>/<module>    — section playground for a
+		//                                              specific module (catalog-mode
+		//                                              docs site serving multiple)
 		if (tmpParts[0] === 'playground' && tmpParts.length >= 2)
 		{
+			if (tmpParts[1] === 'section')
+			{
+				let tmpGroup  = (tmpParts.length >= 4) ? tmpParts[2] : (this.pict.AppData.Docuserve.CurrentGroup || '');
+				let tmpModule = (tmpParts.length >= 4) ? tmpParts[3] : (this.pict.AppData.Docuserve.CurrentModule || '');
+				this.navigateToSectionPlayground(tmpGroup, tmpModule);
+				return;
+			}
 			this.navigateToPlayground(tmpParts[1]);
 			return;
 		}
@@ -374,6 +389,55 @@ class DocuserveApplication extends libPictApplication
 		}
 	}
 
+	/**
+	 * Open the section playground for `<group>/<module>`.  Unlike the
+	 * Fable playground (which lives in the bottom drawer), the section
+	 * playground takes over the main content area — it needs full
+	 * vertical space for its four editor tabs + iframe pane.
+	 *
+	 * @param {string} pGroup
+	 * @param {string} pModule
+	 */
+	navigateToSectionPlayground(pGroup, pModule)
+	{
+		this.pict.AppData.Docuserve.CurrentGroup  = pGroup;
+		this.pict.AppData.Docuserve.CurrentModule = pModule;
+		this.pict.AppData.Docuserve.CurrentDemo   = '';
+		this.pict.AppData.Docuserve.CurrentPath   = 'section-playground';
+
+		// Hide the bottom playground drawer — the section playground
+		// is the whole show on this route.
+		let tmpLayout = this.pict.views['Docuserve-Layout'];
+		if (tmpLayout && typeof tmpLayout.setPlaygroundEnabled === 'function')
+		{
+			tmpLayout.setPlaygroundEnabled(false);
+		}
+
+		let tmpPlayground = this.pict.views['Docuserve-Section-Playground'];
+		if (!tmpPlayground || typeof tmpPlayground.openPlayground !== 'function')
+		{
+			let tmpContentView = this.pict.views['Docuserve-Content'];
+			if (tmpContentView && typeof tmpContentView.displayContent === 'function')
+			{
+				tmpContentView.render();
+				tmpContentView.displayContent('<h1>Section playground unavailable</h1><p>The Section Playground view is not registered.</p>');
+			}
+			return;
+		}
+		tmpPlayground.openPlayground(pGroup, pModule);
+
+		// Keep the sidebar in sync — show the module's nav + active item.
+		let tmpSidebarView = this.pict.views['Docuserve-Sidebar'];
+		if (tmpSidebarView)
+		{
+			tmpSidebarView.renderSidebarGroups();
+			if (typeof tmpSidebarView.renderModuleNav === 'function')
+			{
+				tmpSidebarView.renderModuleNav(pGroup, pModule);
+			}
+		}
+	}
+
 	/**
 	 * Navigate to a hash route.
 	 *
@@ -433,12 +497,16 @@ class DocuserveApplication extends libPictApplication
 				? ('JS Playground: ' + tmpModule)
 				: 'JS Playground');
 		}
-		// Load the module's _playground.json (cached after first load).
-		// Stash the config in AppData so the playground view's require
-		// shim and the per-run capture logic can consult it.  We don't
-		// gate the playground on the config landing — it's purely
-		// informative right now since all fable modules are bundled.
-		if (tmpEnabled && tmpDoc && typeof tmpDoc.loadPlaygroundConfig === 'function')
+		// Load the module's _playground.json.  Two reasons to always do
+		// this (regardless of tmpEnabled):
+		//   1. The async `Kind` check inside isPlaygroundEnabled needs
+		//      the cache populated.  If the config declares Kind:
+		//      "section", we have to re-call setPlaygroundEnabled(false)
+		//      to hide the Fable drawer that the sync sidebar-based
+		//      check just turned on.
+		//   2. Apps still consult AppData.Docuserve.Playground.Config
+		//      (DOM-sandbox pane visibility etc.).
+		if (tmpDoc && typeof tmpDoc.loadPlaygroundConfig === 'function')
 		{
 			tmpDoc.loadPlaygroundConfig(tmpGroup, tmpModule).then((pConfig) =>
 			{
@@ -447,6 +515,16 @@ class DocuserveApplication extends libPictApplication
 					this.pict.AppData.Docuserve.Playground = {};
 				}
 				this.pict.AppData.Docuserve.Playground.Config = pConfig || null;
+
+				// Re-evaluate the drawer's enabled state now that the
+				// cache is populated — a Kind: "section" config flips
+				// it from true back to false.
+				if (typeof tmpDoc.isPlaygroundEnabled === 'function')
+				{
+					let tmpReEnabled = tmpDoc.isPlaygroundEnabled(tmpGroup, tmpModule);
+					tmpLayout.setPlaygroundEnabled(tmpReEnabled);
+				}
+
 				// Config controls DOM-sandbox pane visibility; let the
 				// playground view re-evaluate the moment it lands.  No-op
 				// if the view hasn't been mounted yet.
@@ -457,18 +535,6 @@ class DocuserveApplication extends libPictApplication
 				}
 			});
 		}
-		else
-		{
-			if (this.pict.AppData.Docuserve.Playground)
-			{
-				this.pict.AppData.Docuserve.Playground.Config = null;
-			}
-			let tmpPlaygroundView = this.pict.views['Docuserve-Fable-Playground'];
-			if (tmpPlaygroundView && typeof tmpPlaygroundView._applySandboxMode === 'function')
-			{
-				tmpPlaygroundView._applySandboxMode();
-			}
-		}
 	}
 
 	/**

package/source/cli/Docuserve-CLI-Program.js

@@ -13,6 +13,7 @@ let _PictCLIProgram = new libCLIProgram(
 		require('./commands/Docuserve-Command-Inject.js'),
 		require('./commands/Docuserve-Command-PrepareLocal.js'),
 		require('./commands/Docuserve-Command-StageExamples.js'),
+		require('./commands/Docuserve-Command-StagePlayground.js'),
 		require('./commands/Docuserve-Command-CheckLinks.js')
 	]);
 

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

@@ -0,0 +1,279 @@
+const libCommandLineCommand = require('pict-service-commandlineutility').ServiceCommandLineCommand;
+
+const libFS = require('fs');
+const libPath = require('path');
+
+/**
+ * Recursively create a directory if it does not exist.
+ */
+function ensureDir(pPath)
+{
+	if (!libFS.existsSync(pPath))
+	{
+		libFS.mkdirSync(pPath, { recursive: true });
+	}
+}
+
+/**
+ * `pict-docuserve stage-playground <docs>` — read `<docs>/_playground.json`
+ * and copy every `Imports[]` entry with `Source: "local"` from its resolved
+ * source bundle into `<docs>/<Path>`.
+ *
+ * This is the per-module half of the section-playground story: each module's
+ * `_playground.json` declares which UMD bundles its iframe needs, this
+ * command stages them into the docs tree so the iframe can `<script src=...>`
+ * them relative to the docs root.  Without it, the bundles either have to be
+ * hand-copied (the original section-form workflow) or loaded from the CDN —
+ * which doesn't work for un-published in-development versions.
+ *
+ * Resolution order for each Import's source bundle:
+ *   1. `<moduleRoot>/node_modules/<Name>/dist/<Name>.min.js` — the normal
+ *      case for peer dependencies.
+ *   2. `<moduleRoot>/dist/<Name>.min.js` — when the Import IS the module
+ *      being staged (e.g. pict-section-form staging itself).
+ *   3. Sibling monorepo checkout — walks up looking for a `modules/`
+ *      directory and searches `modules/<group>/<Name>/dist/<Name>.min.js`.
+ *      Lets in-monorepo dev workflows pick up a freshly-built bundle even
+ *      when the umbrella `node_modules/` is stale.
+ *
+ * Clean no-op when `_playground.json` is absent — safe to wire into
+ * `quack prepare-docs` for every module.
+ */
+class DocuserveCommandStagePlayground extends libCommandLineCommand
+{
+	constructor(pFable, pManifest, pServiceHash)
+	{
+		super(pFable, pManifest, pServiceHash);
+
+		this.options.CommandKeyword = 'stage-playground';
+		this.options.Description = 'Stage local Imports referenced by docs/_playground.json into the docs playground runtime folder.';
+
+		this.options.CommandArguments.push({ Name: '[docs_folder]', Description: 'The documentation folder to stage into.  Defaults to ./docs.' });
+		this.options.CommandOptions.push({ Name: '-m, --module_root [module_root]', Description: 'Root of the module being staged (where node_modules lives).  Defaults to the docs folder\'s parent.', Default: '' });
+
+		this.options.Aliases.push('stage-playground-runtime');
+
+		this.addCommand();
+	}
+
+	onRun()
+	{
+		let tmpDocsFolder = libPath.resolve(this.ArgumentString || './docs');
+		let tmpModuleRoot = libPath.resolve(this.CommandOptions.module_root || libPath.dirname(tmpDocsFolder));
+
+		let tmpPlaygroundConfigPath = libPath.join(tmpDocsFolder, '_playground.json');
+		if (!libFS.existsSync(tmpPlaygroundConfigPath))
+		{
+			this.log.info(`No _playground.json at [${tmpPlaygroundConfigPath}]; nothing to stage.`);
+			return;
+		}
+
+		let tmpConfig;
+		try
+		{
+			tmpConfig = JSON.parse(libFS.readFileSync(tmpPlaygroundConfigPath, 'utf8'));
+		}
+		catch (pError)
+		{
+			this.log.error(`Failed to parse _playground.json [${tmpPlaygroundConfigPath}]: ${pError.message}`);
+			process.exit(1);
+			return;
+		}
+
+		let tmpImports = (tmpConfig && Array.isArray(tmpConfig.Imports)) ? tmpConfig.Imports : [];
+		let tmpStylesheets = (tmpConfig && Array.isArray(tmpConfig.Stylesheets)) ? tmpConfig.Stylesheets : [];
+
+		// Staging targets — every Import / Stylesheet with Source: "local".
+		// Each entry produces { kind, name, source, dest } once resolved.
+		let tmpJobs = [];
+		for (let i = 0; i < tmpImports.length; i++)
+		{
+			let tmpImp = tmpImports[i];
+			if (!tmpImp || tmpImp.Source !== 'local') { continue; }
+			tmpJobs.push({ kind: 'script', spec: tmpImp });
+		}
+		for (let i = 0; i < tmpStylesheets.length; i++)
+		{
+			let tmpSheet = tmpStylesheets[i];
+			if (!tmpSheet || tmpSheet.Source !== 'local') { continue; }
+			tmpJobs.push({ kind: 'stylesheet', spec: tmpSheet });
+		}
+
+		if (tmpJobs.length === 0)
+		{
+			this.log.info(`No local Imports or Stylesheets declared in _playground.json; nothing to stage.`);
+			return;
+		}
+
+		this.log.info(`Staging ${tmpJobs.length} playground runtime asset(s) from module root [${tmpModuleRoot}]...`);
+
+		let tmpCopied = 0;
+		let tmpFailed = 0;
+		for (let i = 0; i < tmpJobs.length; i++)
+		{
+			let tmpJob = tmpJobs[i];
+			let tmpKind = tmpJob.kind;
+			let tmpSpec = tmpJob.spec;
+			let tmpName = tmpSpec.Name;
+			let tmpExt = (tmpKind === 'stylesheet') ? 'css' : 'js';
+
+			if (!tmpName && !tmpSpec.Path)
+			{
+				this.log.warn(`${tmpKind} #${i} has neither Name nor Path; skipping.`);
+				tmpFailed++;
+				continue;
+			}
+
+			let tmpRelativePath = tmpSpec.Path || `playground/runtime/${tmpName}.min.${tmpExt}`;
+			let tmpDest = libPath.join(tmpDocsFolder, tmpRelativePath);
+
+			let tmpSource = this._resolveAssetSource(tmpKind, tmpName, tmpSpec.Path, tmpModuleRoot);
+			if (!tmpSource)
+			{
+				this.log.warn(`[${tmpName || tmpRelativePath}] No ${tmpKind} source found; skipping.  Build it (npx quack build) and re-run prepare-docs.`);
+				tmpFailed++;
+				continue;
+			}
+
+			try
+			{
+				ensureDir(libPath.dirname(tmpDest));
+				libFS.copyFileSync(tmpSource, tmpDest);
+				this.log.info(`Staged ${tmpKind} ${tmpName || tmpRelativePath}: ${tmpSource} -> ${tmpDest}`);
+				tmpCopied++;
+			}
+			catch (pError)
+			{
+				this.log.error(`[${tmpName || tmpRelativePath}] Copy failed: ${pError.message}`);
+				tmpFailed++;
+			}
+		}
+
+		this.log.info(`Playground staging complete: ${tmpCopied} copied, ${tmpFailed} failed.`);
+		if (tmpFailed > 0 && tmpCopied === 0)
+		{
+			// Hard failure only when nothing landed — a partial copy is a
+			// warning so prepare-docs can keep going.
+			process.exit(1);
+		}
+	}
+
+	/**
+	 * Resolve the source asset (script bundle or stylesheet) for an Import
+	 * or Stylesheet entry.  Scripts look at `<pkg>/dist/<pkg>.min.js`;
+	 * stylesheets look at `<pkg>/dist/<file>` for whatever Path was declared
+	 * (since CSS filenames don't follow a single naming convention).
+	 *
+	 * @param {string} pKind - "script" or "stylesheet".
+	 * @param {string} pName - Package name (may be empty for ad-hoc paths).
+	 * @param {string} pSpecPath - Optional Path from the spec; for stylesheets
+	 *                             we use its basename to find the source CSS.
+	 * @param {string} pModuleRoot - Root of the module being staged.
+	 * @returns {string|null} Absolute source path, or null if not found.
+	 */
+	_resolveAssetSource(pKind, pName, pSpecPath, pModuleRoot)
+	{
+		if (pKind === 'script')
+		{
+			return this._resolveBundleSource(pName, pModuleRoot);
+		}
+		// Stylesheet — look under the package's dist (or root) for a matching
+		// CSS file.  The spec's Path basename hints at what file to find.
+		let tmpBasename = pSpecPath ? libPath.basename(pSpecPath) : (pName ? pName + '.min.css' : null);
+		if (!tmpBasename) { return null; }
+
+		let tmpCandidates = [];
+		if (pName)
+		{
+			tmpCandidates.push(libPath.join(pModuleRoot, 'node_modules', pName, 'dist', tmpBasename));
+			tmpCandidates.push(libPath.join(pModuleRoot, 'node_modules', pName, tmpBasename));
+		}
+		// Also check the module root in case the CSS lives alongside source/
+		tmpCandidates.push(libPath.join(pModuleRoot, 'dist', tmpBasename));
+		tmpCandidates.push(libPath.join(pModuleRoot, tmpBasename));
+
+		for (let i = 0; i < tmpCandidates.length; i++)
+		{
+			if (libFS.existsSync(tmpCandidates[i]))
+			{
+				return tmpCandidates[i];
+			}
+		}
+		return null;
+	}
+
+	/**
+	 * Resolve the source UMD bundle for an Import by Name.
+	 *
+	 * @param {string} pName - Package name (e.g. "pict", "pict-section-form").
+	 * @param {string} pModuleRoot - Root of the module being staged.
+	 * @returns {string|null} Absolute path to the bundle, or null if not found.
+	 */
+	_resolveBundleSource(pName, pModuleRoot)
+	{
+		let tmpCandidates = [];
+
+		// 1. Peer dependency: <moduleRoot>/node_modules/<Name>/dist/<Name>.min.js
+		tmpCandidates.push(libPath.join(pModuleRoot, 'node_modules', pName, 'dist', `${pName}.min.js`));
+
+		// 2. Module IS the package being staged: <moduleRoot>/dist/<Name>.min.js
+		try
+		{
+			let tmpPkgPath = libPath.join(pModuleRoot, 'package.json');
+			if (libFS.existsSync(tmpPkgPath))
+			{
+				let tmpPkg = JSON.parse(libFS.readFileSync(tmpPkgPath, 'utf8'));
+				if (tmpPkg && tmpPkg.name === pName)
+				{
+					tmpCandidates.push(libPath.join(pModuleRoot, 'dist', `${pName}.min.js`));
+				}
+			}
+		}
+		catch (pError)
+		{
+			// Non-fatal — fall through to other candidates.
+		}
+
+		// 3. Sibling monorepo checkout — walk up until we find a `modules/`
+		// directory, then search modules/<group>/<Name>/dist/<Name>.min.js.
+		let tmpUp = pModuleRoot;
+		for (let i = 0; i < 5; i++)
+		{
+			let tmpModulesDir = libPath.join(tmpUp, 'modules');
+			if (libFS.existsSync(tmpModulesDir) && libFS.statSync(tmpModulesDir).isDirectory())
+			{
+				try
+				{
+					let tmpGroups = libFS.readdirSync(tmpModulesDir);
+					for (let g = 0; g < tmpGroups.length; g++)
+					{
+						let tmpCandidate = libPath.join(tmpModulesDir, tmpGroups[g], pName, 'dist', `${pName}.min.js`);
+						tmpCandidates.push(tmpCandidate);
+					}
+				}
+				catch (pError)
+				{
+					// readdirSync can fail on permission errors; skip silently.
+				}
+				break;
+			}
+			let tmpNext = libPath.dirname(tmpUp);
+			if (tmpNext === tmpUp)
+			{
+				break;
+			}
+			tmpUp = tmpNext;
+		}
+
+		for (let i = 0; i < tmpCandidates.length; i++)
+		{
+			if (libFS.existsSync(tmpCandidates[i]))
+			{
+				return tmpCandidates[i];
+			}
+		}
+		return null;
+	}
+}
+
+module.exports = DocuserveCommandStagePlayground;

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

@@ -1617,18 +1617,24 @@ class DocuserveDocumentationProvider extends libPictProvider
 	}
 
 	/**
-	 * Decide whether the playground panel should be enabled for the
-	 * given group/module.
-	 *
-	 * Opt-in signal: a module's `_sidebar.md` (baked into the catalog as
-	 * `module.Sidebar`) contains an entry whose Path matches
-	 * `playground.md` (case-insensitive, anywhere in the tree).  When the
-	 * sidebar contains that entry, code blocks in the module's docs get
-	 * the "Try in Playground" button and the bottom drawer/tab strip
-	 * becomes visible; otherwise the drawer is suppressed entirely.
-	 *
-	 * Falls back to the root SidebarGroups (standalone mode — docuserve
-	 * serving a single module's docs directly without a catalog).
+	 * Decide whether the **Fable bottom-drawer** playground panel should
+	 * be enabled for the given group/module.
+	 *
+	 * Resolution order:
+	 *   1. If `_playground.json` is cached AND its `Kind` is `"section"`,
+	 *      return false.  Section-playground modules use the full-page
+	 *      `#/playground/section` route and explicitly do NOT want the
+	 *      Fable JS REPL drawer popping up on every doc page.
+	 *   2. Otherwise the opt-in signal is a `playground.md` entry in the
+	 *      module's sidebar (catalog mode) or the root SidebarGroups
+	 *      (standalone mode).  Presence of that entry → drawer + tab
+	 *      strip + "Try in Playground" buttons on code blocks.
+	 *
+	 * The cache is populated by `loadPlaygroundConfig()` (called on each
+	 * navigation by `_syncPlaygroundVisibility`).  On the first visit to
+	 * a module, the cache may not yet be populated — this method
+	 * conservatively falls through to the sidebar check, and the caller
+	 * re-invokes once the async config load resolves.
 	 *
 	 * @param {string} [pGroup]  - Current group key (may be empty)
 	 * @param {string} [pModule] - Current module name (may be empty)
@@ -1636,6 +1642,20 @@ class DocuserveDocumentationProvider extends libPictProvider
 	 */
 	isPlaygroundEnabled(pGroup, pModule)
 	{
+		// Check the _playground.json cache for an explicit Kind: 'section'
+		// declaration — that module uses the full-page playground and
+		// the Fable drawer must stay out of its way on every doc page,
+		// not just on the playground route itself.
+		let tmpCacheKey = (pGroup || '') + '/' + (pModule || '');
+		if (Object.prototype.hasOwnProperty.call(this._PlaygroundConfigCache, tmpCacheKey))
+		{
+			let tmpConfig = this._PlaygroundConfigCache[tmpCacheKey];
+			if (tmpConfig && tmpConfig.Kind === 'section')
+			{
+				return false;
+			}
+		}
+
 		// Per-module sidebar (catalog mode).
 		if (pGroup && pModule)
 		{