@rocket/js 0.1.0 → 0.1.2

package/src/cli/RocketStart.js

@@ -5,6 +5,9 @@ import { debounce } from '../debounce.js';
 import path from 'path';
 
 export class RocketStart {
+  /** @type {RocketStartOptions} */
+  startOptions = {};
+
   /**
    * @param {import('commander').Command} program
    * @param {import('./RocketCli.js').RocketCli} cli
@@ -12,17 +15,29 @@ export class RocketStart {
   async setupCommand(program, cli) {
     this.cli = cli;
 
-    program.command('start').action(async () => {
-      await cli.getConfig();
-      await this.start();
-    });
+    program
+      .command('start')
+      .option('-p, --port <port>', 'port for the development server')
+      .option('--no-open', 'do not open the browser')
+      .option('--no-watch', 'disable automatic file watching and reloads')
+      .action(async options => {
+        const startOptions = normalizeStartOptions(options);
+        await cli.getConfig();
+        await this.start(startOptions);
+      });
   }
 
-  spawnServer() {
+  /**
+   * @param {RocketStartOptions} [options]
+   */
+  spawnServer(options = {}) {
     process.stdin.setRawMode?.(true);
     return spawn(
       'node',
-      [path.join(import.meta.dirname, '../main.js'), this.cli?.configFilePath || ''],
+      startServerArgs({
+        configFilePath: this.cli?.configFilePath,
+        options,
+      }),
       {
         stdio: 'inherit',
         cwd: process.cwd(),
@@ -32,36 +47,42 @@ export class RocketStart {
 
   restartServer() {
     this.server?.kill();
-    this.server = this.spawnServer();
+    this.server = this.spawnServer(this.startOptions);
     console.clear();
     console.log('Restarting rocket server...');
   }
 
-  async start() {
-    this.server = this.spawnServer();
+  /**
+   * @param {RocketStartOptions} [options]
+   */
+  async start(options = {}) {
+    this.startOptions = options;
+    this.server = this.spawnServer(options);
 
-    // watch config
-    watch(
-      path.join(process.cwd(), this.cli?.configFilePath || 'rocket-config.js'),
-      debounce(async (_, filename) => {
-        if (!filename) {
-          return;
-        }
-        this.restartServer();
-      }, 100),
-    );
+    if (options.watch !== false) {
+      // watch config
+      watch(
+        path.join(process.cwd(), this.cli?.configFilePath || 'rocket-config.js'),
+        debounce(async (_, filename) => {
+          if (!filename) {
+            return;
+          }
+          this.restartServer();
+        }, 100),
+      );
 
-    // watch src
-    watch(
-      import.meta.dirname,
-      { recursive: true },
-      debounce(async (_, filename) => {
-        if (!filename) {
-          return;
-        }
-        this.restartServer();
-      }, 100),
-    );
+      // watch src
+      watch(
+        import.meta.dirname,
+        { recursive: true },
+        debounce(async (_, filename) => {
+          if (!filename) {
+            return;
+          }
+          this.restartServer();
+        }, 100),
+      );
+    }
 
     process.stdin.on('data', data => {
       const char = data.toString();
@@ -77,3 +98,48 @@ export class RocketStart {
     console.log('Restart the server with Ctrl+R');
   }
 }
+
+/**
+ * @typedef {{ port?: number; open?: boolean; watch?: boolean }} RocketStartOptions
+ */
+
+/**
+ * @param {{ port?: string; open?: boolean; watch?: boolean }} options
+ * @returns {RocketStartOptions}
+ */
+export function normalizeStartOptions(options) {
+  return {
+    ...(options.port !== undefined ? { port: parsePortOption(options.port) } : {}),
+    ...(options.open !== undefined ? { open: options.open } : {}),
+    ...(options.watch !== undefined ? { watch: options.watch } : {}),
+  };
+}
+
+/**
+ * @param {{ configFilePath?: string; options?: RocketStartOptions }} input
+ */
+export function startServerArgs({ configFilePath, options = {} }) {
+  return [
+    path.join(import.meta.dirname, '../main.js'),
+    configFilePath || '',
+    JSON.stringify(options),
+  ];
+}
+
+/**
+ * @param {string} value
+ */
+function parsePortOption(value) {
+  if (!/^\d+$/.test(value)) {
+    throw new Error(
+      `Invalid --port ${JSON.stringify(value)}. Expected an integer from 1 to 65535.`,
+    );
+  }
+  const port = Number(value);
+  if (port < 1 || port > 65535) {
+    throw new Error(
+      `Invalid --port ${JSON.stringify(value)}. Expected an integer from 1 to 65535.`,
+    );
+  }
+  return port;
+}

package/src/components.js

@@ -1,6 +1,25 @@
 import { resolve } from '@rocket/js/resolve.js';
 import { createComponentHydration } from './component-hydration.js';
 
+/** @type {import('@rocket/js/types.js').Components} */
+export const rocketDemoComponents = {
+  'rocket-code-block': {
+    file: './RocketCodeBlock.js',
+    className: 'RocketCodeBlock',
+    loading: 'hydrate:onVisible',
+  },
+  'rocket-js-demo': {
+    file: './RocketJsDemo.js',
+    className: 'RocketJsDemo',
+    loading: 'client',
+  },
+  'rocket-request-demo': {
+    file: './RocketRequestDemo.js',
+    className: 'RocketRequestDemo',
+    loading: 'client',
+  },
+};
+
 /**
  * @param {import('@rocket/js/types.js').Components} components
  */

package/src/icons.js

@@ -46,6 +46,21 @@ export function iconsFromPath(files) {
   };
 }
 
+export const rocketBootstrapIconLibraries = {
+  bootstrap: iconsFromPackage('bootstrap-icons', 'icons/*.svg'),
+};
+
+export const rocketDefaultBootstrapIconLibrary = 'bootstrap';
+
+/**
+ * @param {{ addIconLibraries: (iconLibraries: import('@rocket/js/types.js').IconLibrariesConfig, options?: { defaultIconLibrary?: string }) => void }} pageData
+ */
+export function addBootstrapIconLibrary(pageData) {
+  pageData.addIconLibraries(rocketBootstrapIconLibraries, {
+    defaultIconLibrary: rocketDefaultBootstrapIconLibrary,
+  });
+}
+
 export class IconAssetStore {
   constructor() {
     /** @type {Map<string, { url: string; svg: string; library: string; name: string }>} */

package/src/layouts/atlas/atlasDocLayout.js

@@ -5,6 +5,7 @@ import { resolve } from '../../resolve.js';
 import { webAwesomeComponents } from '@rocket/js/components/web-awesome.js';
 import { addBootstrapIconLibrary } from '../layout.js';
 import { pageNavigationLinks } from '../../menus/pageNavigation.js';
+import { rocketDemoComponents } from '../../components.js';
 
 export const DEFAULT_ATLAS_DOC_NAVIGATION_ICON_SERVER_BUDGET = 35;
 
@@ -35,21 +36,7 @@ export const atlasDocComponents = {
     className: 'RocketSocialLink',
     loading: 'server',
   },
-  'rocket-code-block': {
-    file: './RocketCodeBlock.js',
-    className: 'RocketCodeBlock',
-    loading: 'hydrate:onVisible',
-  },
-  'rocket-js-demo': {
-    file: './RocketJsDemo.js',
-    className: 'RocketJsDemo',
-    loading: 'client',
-  },
-  'rocket-request-demo': {
-    file: './RocketRequestDemo.js',
-    className: 'RocketRequestDemo',
-    loading: 'client',
-  },
+  ...rocketDemoComponents,
   ...webAwesomeComponents,
 };
 
@@ -132,6 +119,13 @@ export function renderHeaderNav(links = []) {
   `;
 }
 
+/**
+ * @param {string[] | undefined} stylesheets
+ */
+export function renderStylesheets(stylesheets = []) {
+  return stylesheets.map(href => html`<link rel="stylesheet" href=${href} />`);
+}
+
 /**
  * @param {import('@rocket/js/types.js').PageMetadataCustomValue | undefined} customValue
  * @returns {import('@rocket/js/types.js').AtlasDocAsideTip | false | undefined}
@@ -282,6 +276,7 @@ export const atlasDocLayout = (pageData, data) => {
           href="${resolve('@awesome.me/webawesome/dist/styles/webawesome.css', import.meta)}"
         />
         <link rel="stylesheet" href="${resolve('@rocket/js/layouts/atlasDoc.css', import.meta)}" />
+        ${renderStylesheets(data.stylesheets)}
       `,
     },
   );

package/src/layouts/atlas/atlasHeroLayout.js

@@ -3,7 +3,13 @@ import { document } from '../layout-helper.js';
 import { resolve } from '../../resolve.js';
 import { webAwesomeComponents } from '@rocket/js/components/web-awesome.js';
 import { addBootstrapIconLibrary } from '../layout.js';
-import { renderHeaderLogo, renderHeaderNav, renderSocials } from './atlasDocLayout.js';
+import {
+  renderHeaderLogo,
+  renderHeaderNav,
+  renderSocials,
+  renderStylesheets,
+} from './atlasDocLayout.js';
+import { rocketDemoComponents } from '../../components.js';
 
 /** @type {import('@rocket/js/types.js').Components} */
 export const atlasHeroComponents = {
@@ -27,21 +33,11 @@ export const atlasHeroComponents = {
     className: 'FeatureList',
     loading: 'server',
   },
+  ...rocketDemoComponents,
   'rocket-code-block': {
-    file: './RocketCodeBlock.js',
-    className: 'RocketCodeBlock',
+    ...rocketDemoComponents['rocket-code-block'],
     loading: 'hydrate:onClientLoad',
   },
-  'rocket-js-demo': {
-    file: './RocketJsDemo.js',
-    className: 'RocketJsDemo',
-    loading: 'client',
-  },
-  'rocket-request-demo': {
-    file: './RocketRequestDemo.js',
-    className: 'RocketRequestDemo',
-    loading: 'client',
-  },
   ...webAwesomeComponents,
 };
 
@@ -340,6 +336,7 @@ export const atlasHeroLayout = (pageData, data) => {
           href="${resolve('@awesome.me/webawesome/dist/styles/webawesome.css', import.meta)}"
         />
         <link rel="stylesheet" href="${resolve('@rocket/js/layouts/atlasHero.css', import.meta)}" />
+        ${renderStylesheets(data.stylesheets)}
       `,
     },
   );

package/src/layouts/atlas/atlasNotFoundLayout.js

@@ -1,6 +1,7 @@
 import { html } from 'lit';
 import { document } from '../layout-helper.js';
 import { resolve } from '../../resolve.js';
+import { renderStylesheets } from './atlasDocLayout.js';
 
 /** @type {import('@rocket/js/types.js').Components} */
 export const atlasNotFoundComponents = {};
@@ -61,9 +62,10 @@ export const atlasNotFoundLayout = (pageData, data) => {
     {
       menu: false,
       headerContent: html`<link
-        rel="stylesheet"
-        href="${resolve('@rocket/js/layouts/atlasNotFound.css', import.meta)}"
-      />`,
+          rel="stylesheet"
+          href="${resolve('@rocket/js/layouts/atlasNotFound.css', import.meta)}"
+        />
+        ${renderStylesheets(data.stylesheets)}`,
     },
   );
 };

package/src/layouts/layout.js

@@ -2,7 +2,7 @@
 import { html } from 'lit';
 import { document } from './layout-helper.js';
 import { resolve } from '../resolve.js';
-import { iconsFromPackage } from '../icons.js';
+import { addBootstrapIconLibrary } from '../icons.js';
 
 /** @type {import('@rocket/js/types.js').Layout<null>} */
 export const layout = data => {
@@ -49,14 +49,4 @@ export const singleDemoLayout = data => {
   });
 };
 
-/**
- * @param {import('@rocket/js/PageData.js').PageData} pageData
- */
-export function addBootstrapIconLibrary(pageData) {
-  pageData.addIconLibraries(
-    {
-      bootstrap: iconsFromPackage('bootstrap-icons', 'icons/*.svg'),
-    },
-    { defaultIconLibrary: 'bootstrap' },
-  );
-}
+export { addBootstrapIconLibrary };

package/src/main.js

@@ -6,7 +6,8 @@ import { MessageChannel } from 'node:worker_threads';
 import { customElements } from '@lit-labs/ssr-dom-shim';
 import { readConfig } from './config.js';
 
-const configFilePath = process.argv.at(-1);
+const configFilePath = process.argv[2] || undefined;
+const startOptions = readStartOptions(process.argv[3]);
 
 customElements.define = (name, ctor) => {
   customElements.__definitions.set(name, {
@@ -37,12 +38,13 @@ let devServerConfig = {
       urlLifecycle: config.urlLifecycle,
       iconLibraries: config.iconLibraries,
       defaultIconLibrary: config.defaultIconLibrary,
+      watch: startOptions.watch,
     }),
   ],
-  open: true,
+  open: startOptions.open ?? true,
   nodeResolve: { exportConditions: ['browser'] },
-  watch: true,
-  port: 8888,
+  watch: startOptions.watch ?? true,
+  port: startOptions.port ?? 8888,
 };
 
 devServerConfig = config.adjustDevServerConfig(devServerConfig);
@@ -53,3 +55,18 @@ const server = await startDevServer({
   readCliArgs: false,
   readFileConfig: false,
 });
+
+/**
+ * @param {string | undefined} value
+ * @returns {{ port?: number; open?: boolean; watch?: boolean }}
+ */
+function readStartOptions(value) {
+  if (!value) {
+    return {};
+  }
+  const parsed = JSON.parse(value);
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return {};
+  }
+  return /** @type {{ port?: number; open?: boolean; watch?: boolean }} */ (parsed);
+}

package/src/standalone-demo-url.js

@@ -89,14 +89,16 @@ export function matchStandaloneDemoUrl(pathname, origin, pages) {
     if (!isMarkdownPage(page) || !page.demoNames?.includes(standaloneDemo.demoName)) {
       continue;
     }
-    const match = matchPagePath(standaloneDemo.parentPathname, origin, routePath);
-    if (match) {
-      return {
-        page,
-        routePath,
-        params: match.pathname.groups,
-        variant: { kind: 'standalone-demo', demoName: standaloneDemo.demoName },
-      };
+    for (const parentPathname of parentPathnameCandidates(standaloneDemo.parentPathname)) {
+      const match = matchPagePath(parentPathname, origin, routePath);
+      if (match) {
+        return {
+          page,
+          routePath,
+          params: match.pathname.groups,
+          variant: { kind: 'standalone-demo', demoName: standaloneDemo.demoName },
+        };
+      }
     }
   }
   return null;
@@ -126,6 +128,17 @@ function matchPagePath(pathname, origin, routePath) {
   return pattern.exec(pathname, origin);
 }
 
+/**
+ * @param {string} parentPathname
+ */
+function parentPathnameCandidates(parentPathname) {
+  const documentPath = normalizeDocumentPath(parentPathname);
+  if (documentPath === parentPathname) {
+    return [parentPathname];
+  }
+  return [parentPathname, documentPath];
+}
+
 /**
  * @param {Page} page
  */

package/src/transform.js

@@ -13,6 +13,7 @@ import { visit } from 'unist-util-visit';
 import { init, parse as parseExports } from 'es-module-lexer';
 import { headLinesToTree } from './menu.js';
 import { parseRequestDemoMetadata } from './requestDemoMetadata.js';
+import ts from 'typescript';
 
 /** @type {import('rehype-autolink-headings').Options} */
 const headingAnchorOptions = {
@@ -119,13 +120,14 @@ export function contentFn(data, layout) {
  */
 async function makeJsFile(serverCode, clientCode, markdown, headlines) {
   let litImport = "import { html } from 'lit'";
-  if (/import\s*?{(?:\n|.)*?html(\n|.)*}.*/m.test(serverCode)) {
+  const normalizedServerCode = normalizeLayoutExportBindings(serverCode);
+  if (/import\s*?{(?:\n|.)*?html(\n|.)*}.*/m.test(normalizedServerCode)) {
     litImport = '';
   }
   return `
 import {render} from '@lit-labs/ssr';
 ${litImport}
-${serverCode}
+${normalizedServerCode}
 export function contentFn(data, defaultLayout) {
   let renderLayout = defaultLayout;
   if (typeof layout !== 'undefined') {
@@ -143,6 +145,91 @@ export function contentFn(data, defaultLayout) {
 }`;
 }
 
+/**
+ * Direct ESM re-exports do not create local bindings, but the generated Markdown module calls the
+ * selected layout from inside contentFn. Rewriting only direct `layout` re-exports keeps the public
+ * Page syntax working while preserving the generated function's local binding lookup.
+ *
+ * @param {string} serverCode
+ * @returns {string}
+ */
+function normalizeLayoutExportBindings(serverCode) {
+  if (typeof serverCode !== 'string') {
+    return '';
+  }
+  const sourceFile = ts.createSourceFile(
+    'page-server.js',
+    serverCode,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.JS,
+  );
+  /** @type {{start: number; end: number; text: string}[]} */
+  const replacements = [];
+
+  for (const statement of sourceFile.statements) {
+    if (
+      !ts.isExportDeclaration(statement) ||
+      !statement.moduleSpecifier ||
+      !statement.exportClause ||
+      !ts.isNamedExports(statement.exportClause)
+    ) {
+      continue;
+    }
+
+    const layoutExport = statement.exportClause.elements.find(
+      element => element.name.text === 'layout',
+    );
+    if (!layoutExport) {
+      continue;
+    }
+
+    const moduleSpecifier = statement.moduleSpecifier.getText(sourceFile);
+    const attributes = statement.attributes ? ` ${statement.attributes.getText(sourceFile)}` : '';
+    const importedName = (layoutExport.propertyName || layoutExport.name).getText(sourceFile);
+    const layoutImportSpecifier =
+      importedName === 'layout' ? 'layout' : `${importedName} as layout`;
+    const replacementLines = [
+      `import { ${layoutImportSpecifier} } from ${moduleSpecifier}${attributes};`,
+      'export { layout };',
+    ];
+
+    const remainingExports = statement.exportClause.elements.filter(
+      element => element !== layoutExport,
+    );
+    if (remainingExports.length) {
+      const remainingSpecifiers = remainingExports.map(element => {
+        if (element.propertyName) {
+          return `${element.propertyName.getText(sourceFile)} as ${element.name.getText(sourceFile)}`;
+        }
+        return element.name.getText(sourceFile);
+      });
+      replacementLines.push(
+        `export { ${remainingSpecifiers.join(', ')} } from ${moduleSpecifier}${attributes};`,
+      );
+    }
+
+    replacements.push({
+      start: statement.getStart(sourceFile),
+      end: statement.end,
+      text: replacementLines.join('\n'),
+    });
+  }
+
+  if (!replacements.length) {
+    return serverCode;
+  }
+
+  let normalizedCode = serverCode;
+  for (const replacement of replacements.toReversed()) {
+    normalizedCode =
+      normalizedCode.slice(0, replacement.start) +
+      replacement.text +
+      normalizedCode.slice(replacement.end);
+  }
+  return normalizedCode;
+}
+
 function parseDemos() {
   /** @type {{name: string, code: string}[]} */
   const demos = [];

package/src/wds-plugin.js

@@ -24,12 +24,13 @@ let pageRegistry = new Map();
 let modules = new Map();
 
 /** @typedef {import('@rocket/js/types.js').UrlLifecycleConfig} UrlLifecycleConfig */
-/** @typedef {{ urlLifecycle?: UrlLifecycleConfig; siteHeadMetadata?: import('@rocket/js/types.js').SiteHeadMetadataConfig; siteOrigin?: string; siteDiscoverability?: import('@rocket/js/types.js').SiteDiscoverabilityConfig; iconLibraries?: import('@rocket/js/types.js').IconLibrariesConfig; defaultIconLibrary?: string; captureSocialPreviewImage?: import('./socialPreviewImages.js').SocialPreviewCapture }} RocketDevServerPluginOptions */
+/** @typedef {{ urlLifecycle?: UrlLifecycleConfig; siteHeadMetadata?: import('@rocket/js/types.js').SiteHeadMetadataConfig; siteOrigin?: string; siteDiscoverability?: import('@rocket/js/types.js').SiteDiscoverabilityConfig; iconLibraries?: import('@rocket/js/types.js').IconLibrariesConfig; defaultIconLibrary?: string; captureSocialPreviewImage?: import('./socialPreviewImages.js').SocialPreviewCapture; watch?: boolean }} RocketDevServerPluginOptions */
 /** @typedef {RocketDevServerPluginOptions | UrlLifecycleConfig} RocketDevServerPluginInput */
 
 /** @type {(include: string[], exclude: (string | RegExp)[], resolverPort: import('node:worker_threads').MessagePort, options?: RocketDevServerPluginInput) => import('@web/dev-server-core').Plugin} */
 export default (include, exclude, resolverPort, options = {}) => {
   const pluginOptions = normalizePluginOptions(options);
+  const watchEnabled = pluginOptions.watch !== false;
   const iconAssetStore = createIconAssetStore();
   /** @type {import('node:fs').FSWatcher[]} */
   const watchers = [];
@@ -65,19 +66,23 @@ export default (include, exclude, resolverPort, options = {}) => {
         } else {
           modules.set(message.url, new Set([message.parent]));
         }
-        watchFileDirectory(message.url);
+        if (watchEnabled) {
+          watchFileDirectory(message.url);
+        }
         resolverPort.postMessage('ok');
       });
       pageRegistry = await getPages(process.cwd(), include, exclude);
       validateDevelopmentPublicAssets(pluginOptions);
-      pageRegistry.forEach(page => {
-        watchFileDirectory(page.file);
-      });
-      modules.forEach((_, url) => {
-        watchFileDirectory(url);
-      });
+      if (watchEnabled) {
+        pageRegistry.forEach(page => {
+          watchFileDirectory(page.file);
+        });
+        modules.forEach((_, url) => {
+          watchFileDirectory(url);
+        });
+      }
       const publicDir = path.join(process.cwd(), PUBLIC_ASSETS_DIR);
-      if (fs.existsSync(publicDir)) {
+      if (watchEnabled && fs.existsSync(publicDir)) {
         fileWatcher?.add(publicDir);
       }
     },