NXT-16498: [Spotlight] Create sample for spotlight module

README.md

@@ -47,11 +47,14 @@ npm run build
 
 Copies of the source of Enact and other related libraries are placed into the `raw/` directory. If you need to link local copies, link them into that directory.  E.g.:
 
+`parse-docs` also clones `enactjs/samples` (branch `develop`) into `raw/samples`. Embedded samples are
+configured in `src/config/sampleEmbeds.json` and built by `make-runner` into `public/`.
+
 ## Check Broken Links
 
 To check the broken links, follow the steps below:
 
 1. `npm run parse-docs`
 2. `npm run parse-pages`
 3. `npm run build`
-4. `npm run check-links`
+4. `npm run check-links`

scripts/make-runner.mjs

@@ -1,15 +1,35 @@
 import fs from 'fs';
+import path from 'path';
 import parseArgs from 'minimist';
 import shell from 'shelljs';
 import {errorExit} from './utils.mjs';
 import allLibraries from '../src/data/libraryDescription.json' with {type: 'json'};
+import sampleEmbeds from '../src/config/sampleEmbeds.json' with {type: 'json'};
+
+await import('./prepare-raw.mjs');
+
+const rootDir = path.resolve(import.meta.dirname, '..');
+const cliScript = path.join(rootDir, 'raw/cli/bin/enact.js');
+
+// Resolves the enact cli command:
+//   (unset) / 'enact' -> the globally installed cli (default)
+//   any other value   -> the pinned cli cloned into raw/cli, referenced by an
+//                        absolute path so it resolves regardless of the cwd the
+//                        build runs from (theme and sample dirs sit at different depths)
+function resolveEnactCmd (cmd) {
+	if (!cmd || cmd === 'enact') {
+		return 'enact';
+	}
+
+	return `node "${cliScript}"`;
+}
 
 const includes = ['core', 'moonstone', 'sandstone', 'limestone', 'agate'],
 	themes = Object.keys(allLibraries).filter(name => includes.includes(name));
 
 const args = parseArgs(process.argv),
 	fast = args.fast,
-	enactCmd = args['enact-cmd'] || 'enact';
+	enactCmd = resolveEnactCmd(args['enact-cmd']);
 
 if (!enactCmd && !shell.which('enact')) {
 	errorExit('Sorry, this script requires the enact cli tool');
@@ -66,3 +86,28 @@ themes.forEach(theme => {
 		fs.writeFileSync(`${ilibDst}/ilibmanifest.json`, JSON.stringify({files: copiedIlib}));
 	}
 });
+
+sampleEmbeds.forEach(({id, build}) => {
+	const {src, output} = build;
+
+	if (!fs.existsSync(src)) {
+		return;
+	}
+
+	if (!fs.existsSync(`${src}/node_modules`)) {
+		if (shell.exec('npm install', {cwd: src}).code !== 0) {
+			errorExit(`Error installing dependencies for ${id}.  Aborting.`);
+		}
+	}
+
+	if (fast && fs.existsSync(`${output}/index.html`)) {
+		// eslint-disable-next-line no-console
+		console.log(`Sample ${id} exists, skipping build.  Use "npm run make-runner" to build`);
+	} else {
+		const relOut = path.relative(src, output).split(path.sep).join('/');
+		const command = `${enactCmd} pack -p -o ${relOut}`;
+		if (shell.exec(command, {async: false, cwd: src}).code !== 0) {
+			errorExit(`Error building ${id}.  Aborting.`);
+		}
+	}
+});

scripts/prepare-raw.mjs

@@ -40,6 +40,7 @@ const rebuild = args['rebuild-raw'],
 copyGitHub('enactjs/enact', 'raw/enact', rebuild, args['enact-branch'], args['ssh']);
 copyGitHub('enactjs/cli', 'raw/cli', rebuild, args['cli-branch'], args['ssh']);
 copyGitHub('enactjs/eslint-config-enact', 'raw/eslint-config-enact', rebuild, args['eslint-config-branch'], args['ssh']);
+copyGitHub('enactjs/samples', 'raw/samples', rebuild, 'develop', args['ssh']);
 
 if (extraRepos) {
 	const repos = extraRepos.split(',');

src/components/Page/[...data].astro

@@ -10,6 +10,7 @@ import {
 	MemberObjectTypeDef,
 	MemberProperties,
 	ModuleImport,
+	SampleEmbedSection,
 } from '../index';
 import {getJSONData, getMembers} from "./utils";
 
@@ -36,6 +37,7 @@ const [membersData, typeDefinitionsData] = getMembers(data);
 		<h5 class={css.livePreviewFallback} slot="fallback">Loading Live Preview</h5>
 	</LivePreview>
 )}
+<SampleEmbedSection moduleName={moduleName} />
 <ModuleImport moduleName={moduleName} title={title} />
 
 <!--Members Data-->

src/components/SampleEmbed/SampleEmbed.jsx

@@ -0,0 +1,13 @@
+import {withBase} from '../../utils/utils';
+import css from './SampleEmbed.module.css';
+
+const SampleEmbed = ({src, title = 'Sample preview'}) => (
+	<iframe
+		className={css.frame}
+		src={withBase(src, true)}
+		title={title}
+		loading="lazy"
+	/>
+);
+
+export default SampleEmbed;

src/components/SampleEmbed/SampleEmbed.module.css

@@ -0,0 +1,6 @@
+.frame {
+	background-color: inherit;
+	border: none;
+	width: 100%;
+	min-height: 600px;
+}

src/components/SampleEmbed/SampleEmbedSection.astro

@@ -0,0 +1,15 @@
+---
+import Heading from '../Heading/Heading.astro';
+import SampleEmbed from './SampleEmbed.jsx';
+import {getSampleEmbed} from '../../utils/sampleEmbeds.js';
+
+const {moduleName} = Astro.props;
+const embed = getSampleEmbed(moduleName);
+---
+
+{embed && (
+	<>
+		<Heading title="Interactive Demo" level={2} />
+		<SampleEmbed client:only="react" src={embed.src} title={embed.title} />
+	</>
+)}

src/components/index.js

@@ -2,6 +2,8 @@ import DocParse from './DocParse/DocParse.jsx';
 import Heading from './Heading/Heading.astro';
 import Link from './Link/Link.jsx';
 import LivePreview from './LivePreview/LivePreview.jsx';
+import SampleEmbed from './SampleEmbed/SampleEmbed.jsx';
+import SampleEmbedSection from './SampleEmbed/SampleEmbedSection.astro';
 import MemberClass from './MemberClass/MemberClass.astro';
 import MemberFunction from './MemberFunction/MemberFunction.jsx';
 import MemberHoC from './MemberHoC/MemberHoC.astro';
@@ -16,6 +18,8 @@ export {
 	Heading,
 	Link,
 	LivePreview,
+	SampleEmbed,
+	SampleEmbedSection,
 	MemberFunction,
 	MemberHoC,
 	MemberObjectTypeDef,

src/config/sampleEmbeds.json

@@ -0,0 +1,22 @@
+[
+	{
+		"id": "spotlight-sandbox",
+		"title": "Spotlight Sandbox",
+		"build": {
+			"src": "raw/samples/ui/spotlight-sandbox",
+			"output": "public/spotlight-sandbox"
+		},
+		"embed": {
+			"index": "/spotlight-sandbox/index.html",
+			"modules": ["spotlight"],
+			"routes": {
+				"spotlight": "",
+				"spotlight/Spottable": "#/SandboxSample",
+				"spotlight/SpotlightContainerDecorator": "#/ContainerSample",
+				"spotlight/SpotlightRootDecorator": "",
+				"spotlight/Pause": "#/DisappearSample",
+				"spotlight/Accelerator": "#/TestPage"
+			}
+		}
+	}
+]

src/utils/sampleEmbeds.js

@@ -0,0 +1,24 @@
+import sampleEmbeds from '../config/sampleEmbeds.json';
+
+const moduleMatches = (moduleName, prefixes) => prefixes.some(
+	(prefix) => moduleName === prefix || moduleName.startsWith(`${prefix}/`)
+);
+
+const getSampleEmbed = (moduleName) => {
+	for (const {title, embed} of sampleEmbeds) {
+		if (!embed?.modules?.length || !moduleMatches(moduleName, embed.modules)) {
+			continue;
+		}
+
+		const route = embed.routes?.[moduleName] ?? '';
+
+		return {
+			title,
+			src: `${embed.index}${route}`
+		};
+	}
+
+	return null;
+};
+
+export {getSampleEmbed, sampleEmbeds};