feat(tools): site.subpath config (#2462)

Author: bennypowers

.changeset/tools-site-subpath.md

@@ -0,0 +1,5 @@
+---
+"@patternfly/pfe-tools": minor
+---
+Added `site.componentSubpath` config to `.pfe.config.json`, representing the 
+site subpath for component pages and demos. Default is `'components'`.

.pfe.config.json

@@ -1,6 +1,3 @@
 {
-  "renderTitleInOverview": false,
-  "site": {
-    "renderTitleInOverview": false
-  }
+  "renderTitleInOverview": false
 }

elements/custom-elements-manifest.config.js

@@ -1,6 +1,11 @@
 import { pfeCustomElementsManifestConfig } from '@patternfly/pfe-tools/custom-elements-manifest/config.js';
+import { fileURLToPath } from 'node:url'
+import { dirname } from 'node:path'
 
+// HACK: cem runs from `./elements` in a monorepo
+let rootDir = dirname(dirname(fileURLToPath(import.meta.url)))
 export default pfeCustomElementsManifestConfig({
+  rootDir,
   globs: [
     './*/pf-*.ts',
     './*/Base*.ts'

tools/pfe-tools/11ty/plugins/custom-elements-manifest.cjs

@@ -70,8 +70,10 @@ module.exports = function configFunction(eleventyConfig, pluginOpts = {}) {
   // Netlify tends to turn html files into directories with index.html,
   // but 11ty already did that, so let's delete the html file.
   eleventyConfig.on('eleventy.after', async function({ runMode, dir }) {
+    const { getPfeConfig } = await import('../../config.js');
+    const options = { ...getPfeConfig(), ...pluginOpts };
     if (runMode === 'build') {
-      const files = await glob(`${dir.output}/components/*/demo/*`);
+      const files = await glob(`${dir.output}/${options.site.componentSubpath}/*/demo/*`);
       const htmls = files.filter(x => x.endsWith('.html') && !x.endsWith('/index.html'));
       for (const file of htmls) {
         const dir = file.replace(/\.html$/, '');

tools/pfe-tools/config.ts

@@ -13,6 +13,8 @@ interface SiteOptions {
   stylesheets?: string[];
   /** Title for main page of the demo */
   title?: string;
+  /** Site subpath for components. e.g. 'elements'. default: 'components' */
+  componentSubpath?: string;
 }
 
 export interface PfeConfig {
@@ -37,7 +39,8 @@ const SITE_DEFAULTS: Required<SiteOptions> = {
   favicon: '/docs/images/logo/pfe-icon-blue.svg',
   logoUrl: '/docs/images/pfe-logo-inverse-white.svg',
   stylesheets: [],
-  title: 'PatternFly Elements'
+  title: 'PatternFly Elements',
+  componentSubpath: 'components',
 };
 
 const DEFAULT_CONFIG: PfeConfig = {
@@ -70,7 +73,8 @@ export function getPfeConfig(rootDir = process.cwd()): Required<PfeConfig> {
 
 const slugsConfigMap = new Map<string, { config: PfeConfig; slugs: Map<string, string> }>();
 const reverseSlugifyObject = ([k, v]: [string, string]): [string, string] =>
-  [slugify(v).toLowerCase(), k];
+  [slugify(v, { lower: true }), k];
+
 function getSlugsMap(rootDir: string) {
   if (!slugsConfigMap.get(rootDir)) {
     const config = getPfeConfig(rootDir);

tools/pfe-tools/custom-elements-manifest/config.ts

@@ -14,15 +14,15 @@ import { getPfeConfig, type PfeConfig } from '../config.js';
 
 import Chalk from 'chalk';
 
-type Options = Config & Pick<PfeConfig, 'sourceControlURLPrefix' | 'demoURLPrefix'>;
+type Options = Config & Pick<PfeConfig, 'sourceControlURLPrefix' | 'demoURLPrefix'> & { rootDir?: string };
 
 /**
  * PFE Default custom-elements-manifest analyzer config
  * @deprecated
  */
 export function pfeCustomElementsManifestConfig(options?: Options): Config {
   console.log(`${Chalk.yellow(`pfeCustomElementsManifestConfig is ${Chalk.bold('deprecated')}`)}`);
-  const config = getPfeConfig();
+  const config = getPfeConfig(options?.rootDir);
   const { demoURLPrefix, sourceControlURLPrefix, dev } = { ...config, ...options ?? {} };
   return {
     globs: options?.globs ?? ['src/**/*.ts'],
@@ -43,7 +43,7 @@ export function pfeCustomElementsManifestConfig(options?: Options): Config {
       deprecatedDescriptionInlineTagPlugin(),
       dedentDescriptionsPlugin(),
       summaryPlugin(),
-      demosPlugin({ demoURLPrefix, sourceControlURLPrefix }),
+      demosPlugin({ ...options, demoURLPrefix, sourceControlURLPrefix }),
       ecmaPrivateClassMembersPlugin(),
       versionStaticFieldPlugin(),
 

tools/pfe-tools/custom-elements-manifest/demos.ts

@@ -27,7 +27,9 @@ import slugify from 'slugify';
  * `/elements/pf-jazz-hands/pf-jazz-hands.js`
  */
 export function demosPlugin(options?: PfeConfig): Plugin {
-  const config = { ...getPfeConfig(), ...options };
+  const fileOptions = getPfeConfig(options?.rootDir);
+  const config = { ...fileOptions, ...options };
+  const subpath = config.site.componentSubpath ?? 'components';
   const { rootDir, demoURLPrefix, sourceControlURLPrefix } = config;
   return {
     name: 'demos-plugin',
@@ -37,7 +39,7 @@ export function demosPlugin(options?: PfeConfig): Plugin {
 
       for (const moduleDoc of customElementsManifest.modules) {
         const primaryElementName = moduleDoc.path.split(sep).find(x => x !== 'elements') ?? '';
-        let demoPath = join(rootDir, primaryElementName, 'demo');
+        let demoPath = join(rootDir, 'elements', primaryElementName, 'demo');
 
         if (!existsSync(demoPath)) {
           demoPath = join('elements', primaryElementName, 'demo');
@@ -52,19 +54,19 @@ export function demosPlugin(options?: PfeConfig): Plugin {
               const { tagName } = decl;
               for (const demo of allDemos) {
                 const demoName = demo.replace(/\.html$/, '');
-                const slug = slugify(alias).toLowerCase();
+                const slug = slugify(alias, { strict: true, lower: true });
                 const href = new URL(`elements/${primaryElementName}/demo/${demo}/`, sourceControlURLPrefix || '/').href.replace(/\/$/, '');
                 if (demoName === tagName && demoName === primaryElementName) {
                 // case: elements/pf-jazz-hands/demo/pf-jazz-hands.html
-                  const { href: url } = new URL(`/components/${slug}/demo/`, demoURLPrefix || '/');
+                  const { href: url } = new URL(`/${subpath}/${slug}/demo/`, demoURLPrefix || '/');
                   decl.demos.push({ url, source: { href } });
                 } else if (allTagNames.includes(demoName) && demoName === tagName) {
                 // case: elements/pf-jazz-hands/demo/pf-jazz-shimmy.html
-                  const { href: url } = new URL(`/components/${slug}/demo/${demoName}/`, demoURLPrefix || '/');
+                  const { href: url } = new URL(`/${subpath}/${slug}/demo/${demoName}/`, demoURLPrefix || '/');
                   decl.demos.push({ url, source: { href } });
                 } else if (tagName === primaryElementName && !allTagNames.includes(demoName)) {
                 // case: elements/pf-jazz-hands/demo/ack.html
-                  const { href: url } = new URL(`/components/${slug}/demo/${demoName}/`, demoURLPrefix || '/');
+                  const { href: url } = new URL(`/${subpath}/${slug}/demo/${demoName}/`, demoURLPrefix || '/');
                   decl.demos.push({ url, source: { href } });
                 }
               }

tools/pfe-tools/custom-elements-manifest/lib/Manifest.ts

@@ -267,7 +267,15 @@ export class Manifest {
     const { prettyTag } = Manifest;
     return this.getDemos(tagName).map(demo => {
       const permalink = demo.url.replace(options.demoURLPrefix, '/');
-      let [, slug = ''] = permalink.match(/\/components\/(.*)\/demo/) ?? [];
+
+      /**
+       * `/components/`
+       * capture group 1:
+       * > **ANY** (_>= 0x_)
+       * `/demo`
+       */
+      const DEMO_PATH_RE = new RegExp(`/${options.site.componentSubpath}/(.*)/demo`);
+      let [, slug = ''] = permalink.match(DEMO_PATH_RE) ?? [];
       // strict removes all special characters from slug
       slug = slugify(slug, { strict: true, lower: true });
       const primaryElementName = deslugify(slug, options.rootDir);