ember.nvp 1.6.0 → 1.7.1

package/src/cli/index.js

@@ -20,7 +20,7 @@ import { askReplaceOrUpdate } from "./questions/replace-or-update.js";
  * This whole file's primary purpose is to be an interactive CLI
  * for `generateProject`.
  *
- * Other tools can call `generateProject` themselves if they wish
+ * Other tools can call `generateProject` themselves
  * if they want to provide different TUI/GUIs.
  */
 async function main() {
@@ -38,19 +38,19 @@ async function main() {
   await askIfOK();
 
   /**
-   * Everything is generated in a stage: a real directory (in the OS temp
-   * dir) acting as a writable overlay of the target directory.
+   * Everything is generated in a stage:
+   * a real directory (in the OS temp dir) acting as a writable overlay of the target directory.
    *
-   * When updating an existing project, the stage is seeded with a full
-   * copy of it (sans node_modules/.git), so the bases and layers run
-   * against the project's current state -- isSetup checks, package.json
-   * reads, file existence checks, etc. all see the existing files, and
-   * the codemods modify them in the stage exactly as if they were
-   * operating in place. "replace" starts from an empty stage instead.
+   * When updating an existing project, the stage is seeded with a full copy of it
+   * (sans node_modules/.git), so the bases and layers run against the project's current state:
+   * - isSetup checks, package.json reads, file existence checks, etc. all see the existing files
+   * - the codemods modify them in the stage exactly as if they were operating in place
    *
-   * The target itself is not touched until stage.commit() below, which
-   * applies the difference between the stage and the target (or the
-   * subset of it the user accepts during review).
+   * "replace" starts from an empty stage instead.
+   *
+   * The target itself is not touched until stage.commit() below.
+   * That applies the difference between the stage and the target
+   * (or the subset of it the user accepts during review).
    */
   const stage = await Stage.create(projectPath, { seed: replaceOrUpdate !== "replace" });
 
@@ -98,9 +98,12 @@ async function main() {
   }
 
   /**
-   * New projects (and "replace", which was already confirmed) are written
-   * without asking. Updates to an existing project must be confirmed:
-   * write all / review each change (accept/reject) / cancel.
+   * New projects (and "replace", which was already confirmed) are written without asking.
+   *
+   * Updates to an existing project must be confirmed:
+   * - write all
+   * - review each change (accept/reject)
+   * - cancel
    */
   const isUpdate = !stage.isNew && replaceOrUpdate !== "replace";
 
@@ -123,9 +126,11 @@ async function main() {
 
   /**
    * Converted / generated files are written expecting the project's own
-   * formatting and lint pass to run right away (e.g. blank lines between
-   * import groups are `eslint --fix`'s job) -- so when the project has a
-   * lint:fix script, surface it as the step right after install.
+   * formatting and lint pass to run right away.
+   * (e.g. blank lines between import groups are `eslint --fix`'s job)
+   *
+   * So when the project has a lint:fix script,
+   * surface it as the step right after install.
    */
   let lintFixStep = "";
   try {

package/src/cli/questions/project-type.js

@@ -4,12 +4,21 @@ import { answers, printArgInUse } from "#args";
 /**
  * addon is alias for library
  * web-extension is alias for extension
+ * web-component is alias for custom-element
  */
-const SUPPORTED = new Set(["app", "library", "addon", "extension", "web-extension"]);
+const SUPPORTED = new Set([
+  "app",
+  "library",
+  "addon",
+  "extension",
+  "web-extension",
+  "custom-element",
+  "web-component",
+]);
 
 /**
  * @param {string | undefined} selected
- * @returns {selected is "app" | "library" | "addon" | "extension" | "web-extension"}
+ * @returns {selected is "app" | "library" | "addon" | "extension" | "web-extension" | "custom-element" | "web-component"}
  */
 function isValid(selected) {
   if (!selected) return false;
@@ -27,6 +36,7 @@ export async function askProjectType() {
 
     if (answers.type === "addon") return "library";
     if (answers.type === "web-extension") return "extension";
+    if (answers.type === "web-component") return "custom-element";
 
     return answers.type;
   }
@@ -45,6 +55,11 @@ export async function askProjectType() {
         label: "browser extension",
         hint: "Manifest V3 extension whose popup is an Ember app",
       },
+      {
+        value: "custom-element",
+        label: "custom element",
+        hint: "an Ember component packaged as a web component, usable from any page",
+      },
     ],
   });
 

package/src/cli/questions/write.js

@@ -17,10 +17,11 @@ function isValid(selected) {
 }
 
 /**
- * Nothing has been written to the target directory yet -- everything so
- * far only exists in the stage. Ask whether to write the staged changes,
- * with the option to review the diff change-by-change, accepting or
- * rejecting each one.
+ * Nothing has been written to the target directory yet.
+ * Everything so far only exists in the stage.
+ *
+ * Ask whether to write the staged changes,
+ * with the option to review the diff change-by-change, accepting or rejecting each one.
  *
  * @param {import('#utils/stage.js').Stage} stage
  * @param {import('#utils/stage.js').Change[]} changes
@@ -61,10 +62,11 @@ export async function askToWrite(stage, changes) {
 }
 
 /**
- * Show each change's diff and ask what to do with it. "accept remaining"
- * and "reject remaining" finish the review early, so they require an
- * extra confirmation; declining the confirmation returns to the change
- * being reviewed.
+ * Show each change's diff and ask what to do with it.
+ *
+ * "accept remaining" and "reject remaining" finish the review early,
+ * so they require an extra confirmation.
+ * Declining the confirmation returns to the change being reviewed.
  *
  * @param {import('#utils/stage.js').Stage} stage
  * @param {import('#utils/stage.js').Change[]} changes
@@ -83,8 +85,8 @@ async function reviewEachChange(stage, changes) {
 
     const remaining = changes.length - index;
 
-    // Bypass clack for the diff itself: diffs are long, and clack's
-    // log decorations wrap every line.
+    // Bypass clack for the diff itself.
+    // Diffs are long, and clack's log decorations wrap every line.
     console.log("\n" + (await stage.diff([change])));
 
     const answer = await p.select({

package/src/layers/are-the-types-wrong/index.js

@@ -15,13 +15,13 @@ export default {
 
   async run(project) {
     // Publish checks: apps aren't published
-    if (project.type !== "library") return;
+    if (!project.isLibrary) return;
 
     // Declarations are the thing being checked
     if (!(await project.hasOrWantsLayer("typescript"))) return;
 
-    // ESM-only packages don't offer the CJS resolution modes the strict
-    // profile requires
+    // ESM-only packages don't offer the CJS resolution modes
+    // that the strict profile requires
     await addTsdownConfigProperty(project, "attw", `attw: { profile: "esm-only" }`);
     await packageJson.addDevDependencies(await getLatest(deps), project.directory);
   },
@@ -42,9 +42,9 @@ export default {
     /** @type {string[]} */
     const reasons = [];
 
-    // Nothing to set up outside TypeScript libraries, so nothing can be
-    // missing
-    if (project.type !== "library" || !(await project.hasOrWantsLayer("typescript"))) {
+    // Nothing to set up outside TypeScript libraries,
+    // so nothing can be missing
+    if (!project.isLibrary || !(await project.hasOrWantsLayer("typescript"))) {
       return explain ? { isSetup: true, reasons } : true;
     }
 

package/src/layers/github-actions/index.js

@@ -55,8 +55,9 @@ export default {
 };
 
 /**
- * This is a very silly way to handle YAML, but 🤷
- * will update if this starts getting to be troublesome.
+ * String concatenation is a very silly way to handle YAML, but 🤷
+ *
+ * Will update if this starts getting to be troublesome.
  */
 const preamble = `name: CI
 
@@ -135,8 +136,10 @@ async function transform(project) {
   content = await addOrUpdateTests(project, content);
 
   /**
-   * If we've still added nothing, we can't actually add the preamble
-   * because there are no jobs to run (we need at least one job).
+   * A workflow needs at least one job.
+   *
+   * If nothing was added, there is no job to run,
+   * so the preamble is not added either.
    */
   if (content === "") {
     return { content, original, didChange: original !== content, outputPath };

package/src/layers/inspector-support/index.js

@@ -42,8 +42,8 @@ export default {
       await writeFile(path, wired);
     }
 
-    // the dependency is only useful once the Application actually got
-    // wired (the codemod leaves unrecognized Application shapes alone)
+    // The codemod leaves unrecognized Application shapes alone.
+    // The dependency is only useful once the Application is wired.
     if (!hasInspectorSupport(wired, path)) return;
 
     await packageJson.addDevDependencies(await getLatest(deps), project.directory);

package/src/layers/publint/index.js

@@ -15,7 +15,7 @@ export default {
 
   async run(project) {
     // Publish checks: apps aren't published
-    if (project.type !== "library") return;
+    if (!project.isLibrary) return;
 
     await addTsdownConfigProperty(project, "publint", "publint: true");
     await packageJson.addDevDependencies(await getLatest(deps), project.directory);
@@ -38,7 +38,7 @@ export default {
     const reasons = [];
 
     // Nothing to set up outside libraries, so nothing can be missing
-    if (project.type !== "library") {
+    if (!project.isLibrary) {
       return explain ? { isSetup: true, reasons } : true;
     }
 

package/src/layers/qunit/index.js

@@ -18,9 +18,12 @@ const tsDeps = {
 };
 
 /**
- * Libraries don't have the app base's vite stack, so the test build
- * brings the pieces the generated configs and test-helper import
- * directly. Everything else (babel itself, the embroider machinery)
+ * Libraries don't have the app base's vite stack.
+ *
+ * So the test build brings the pieces that the generated configs
+ * and test-helper import directly.
+ *
+ * Everything else (babel itself, the embroider machinery)
  * comes with @nullvoxpopuli/ember-vite.
  */
 const libraryDeps = {
@@ -41,14 +44,14 @@ const TEST_BABEL_CONFIG = "config/test/babel.config.js";
  * @param {import('#utils/project.js').Project} project
  */
 function depsFor(project) {
-  return project.type === "library" ? libraryDeps : deps;
+  return project.isLibrary ? libraryDeps : deps;
 }
 
 /**
  * @param {import('#utils/project.js').Project} project
  */
 function tsDepsFor(project) {
-  return project.type === "library" ? libraryTsDeps : tsDeps;
+  return project.isLibrary ? libraryTsDeps : tsDeps;
 }
 
 /**
@@ -58,7 +61,7 @@ export default {
   label: "QUnit",
 
   async run(project) {
-    let isLibrary = project.type === "library";
+    let isLibrary = project.isLibrary;
     let ts = await project.hasOrWantsLayer("typescript");
 
     if (isLibrary) {
@@ -79,7 +82,6 @@ export default {
       project.directory,
     );
 
-    // Add scripts
     await packageJson.addScripts(
       {
         "build:test": "EMBER_ENV=test NODE_ENV=development vite build --mode development",
@@ -151,10 +153,11 @@ export default {
 };
 
 /**
- * Tests import the library's source (not its published dist), so the
- * `#src/*` subpath must exist before the test files are applied --
- * applying rewrites their import extensions by resolving each specifier
- * through this mapping.
+ * Tests import the library's source, not its published dist.
+ *
+ * The `#src/*` subpath must exist before the test files are applied:
+ * applying rewrites their import extensions
+ * by resolving each specifier through this mapping.
  *
  * @param {import('#utils/project.js').Project} project
  */
@@ -166,12 +169,13 @@ async function addSourceImports(project) {
 }
 
 /**
- * The test babel config is the qunit layer's own (a root babel config,
- * when a library has one, belongs to the publish build), so this layer
- * also keeps the config's TypeScript handling in step with the project:
- * the shipped config carries the TS plugin, which must not survive in a
- * JavaScript project, and must come back when a project adopts the
- * typescript layer later.
+ * The test babel config is the qunit layer's own.
+ * (a root babel config, when a library has one, belongs to the publish build)
+ *
+ * So this layer keeps the config's TypeScript handling in step with the project:
+ * - the shipped config carries the TS plugin
+ * - it must not survive in a JavaScript project
+ * - it must come back when a project adopts the typescript layer later
  *
  * @param {import('#utils/project.js').Project} project
  * @param {boolean} ts

package/src/layers/readme/index.js

@@ -2,6 +2,7 @@ import { existsSync } from "node:fs";
 import { writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { formatLabel } from "#utils/cli.js";
+import { tagNameFor } from "#bases/minimal-custom-element";
 
 /**
  * @param {import('#utils/project.js').Project} project
@@ -73,13 +74,13 @@ ${project.runPrefix} start
 
 ### Building
 
-To build the library:
+To build the extension:
 
 \`\`\`sh
 ${project.runPrefix} build
 \`\`\`
 
-or
+or, to rebuild on change:
 
 \`\`\`sh
 ${project.runPrefix} build:watch
@@ -113,6 +114,55 @@ ${project.runPrefix} build
 ${layerDocsMarkdown}`;
 }
 
+/**
+ * @param {import('#utils/project.js').Project} project
+ * @param {string} layerDocsMarkdown
+ */
+function customElementReadme(project, layerDocsMarkdown) {
+  let tagName = tagNameFor(project.name);
+
+  return `# ${project.name}
+
+An Ember component, packaged as a custom element, created with \`ember.nvp\`.
+The built package contains ember, so the page that uses the element needs nothing else.
+
+## Usage
+
+Import the \`register\` entry once. It defines the \`<${tagName}>\` tag.
+
+\`\`\`js
+import "${project.name}/register";
+\`\`\`
+
+\`\`\`html
+<${tagName} label="Clicks" step="2"></${tagName}>
+\`\`\`
+
+To choose your own tag name, import the class and define it yourself:
+
+\`\`\`js
+import { CounterElement } from "${project.name}";
+
+customElements.define("my-counter", CounterElement);
+\`\`\`
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js >= 24
+- ${project.packageManager}
+
+### Development & Building
+
+To build the package:
+
+\`\`\`sh
+${project.runPrefix} build
+\`\`\`
+${layerDocsMarkdown}`;
+}
+
 export default {
   label: formatLabel("README.md", "generate project documentation"),
   hint: "project README",
@@ -125,7 +175,6 @@ export default {
    * @param {import('#utils/project.js').Project} project
    */
   async run(project) {
-    // Collect layer docs
     const layerDocs = [];
     for (const layer of project.desires.layers) {
       if (layer.name === "readme" || !layer.readme) {
@@ -149,7 +198,6 @@ export default {
       layerDocsMarkdown = `\n## Features & Tooling\n\n${layerDocs.join("\n\n")}\n`;
     }
 
-    // Merge the layers' snippets into the main readme template
     let content;
     switch (project.type) {
       case "extension":
@@ -158,6 +206,9 @@ export default {
       case "library":
         content = libraryReadme(project, layerDocsMarkdown);
         break;
+      case "custom-element":
+        content = customElementReadme(project, layerDocsMarkdown);
+        break;
       default:
         content = appReadme(project, layerDocsMarkdown);
         break;

package/src/layers/renovate/index.js

@@ -14,11 +14,11 @@ export default {
       return;
     }
 
-    // extensions aren't published to npm either, so they follow the app config
-    let source =
-      project.type === "library"
-        ? join(import.meta.dirname, "files/library.json5")
-        : join(import.meta.dirname, "files/app.json5");
+    // extensions aren't published to npm either,
+    // so they follow the app config
+    let source = project.isLibrary
+      ? join(import.meta.dirname, "files/library.json5")
+      : join(import.meta.dirname, "files/app.json5");
 
     let destination = join(project.directory, ".github/renovate.json5");
 

package/src/layers/typescript/index.js

@@ -4,11 +4,13 @@ import { cp } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { hasConfiguredTSBabel, prependPlugin } from "#utils/babel.js";
 import { getLatest } from "#utils/npm.js";
+import { isLibraryType } from "#utils/project-type.js";
 
 const bases = join(import.meta.dirname, "../../bases");
 const appBase = join(bases, "minimal-app/files");
 const extensionBase = join(bases, "minimal-extension/files");
 const libraryBase = join(bases, "minimal-library/files");
+const customElementBase = join(bases, "minimal-custom-element/files");
 
 const sharedDeps = {
   "@glint/ember-tsc": "^1.0.8",
@@ -18,8 +20,8 @@ const sharedDeps = {
 };
 
 const appDeps = {
-  // Apps strip types via their own babel.config.js; libraries have no babel
-  // config -- ember() handles type stripping.
+  // Apps strip types via their own babel.config.js.
+  // Libraries have no babel config: ember() handles type stripping.
   "@babel/plugin-transform-typescript": "^7.28.5",
   "@ember/app-tsconfig": "^2.0.0",
 };
@@ -34,7 +36,7 @@ const libraryDeps = {
 function depsFor(project) {
   return {
     ...sharedDeps,
-    ...(project.type === "library" ? libraryDeps : appDeps),
+    ...(project.isLibrary ? libraryDeps : appDeps),
   };
 }
 
@@ -45,21 +47,19 @@ export default {
   label: "TypeScript",
 
   /**
-   * Libraries publish declarations, so they are TypeScript unless the
-   * user opts out.
+   * Libraries publish declarations,
+   * so they are TypeScript unless the user opts out.
    *
    * @param {import('#types').ProjectType} projectType
    */
   defaultValue(projectType) {
-    return projectType === "library";
+    return isLibraryType(projectType);
   },
 
   async run(project) {
     /**
-     * if jsconfig exists, switch to tsconfig
-     */
-    /**
-     * if tsconfig exists,
+     * TODO:
+     * - if jsconfig exists, switch to tsconfig
      */
     await addTSConfig(project);
     await updatePackageJson(project);
@@ -87,8 +87,8 @@ export default {
       reasons.push("tsconfig.json is missing");
     }
 
-    // Only projects with their own babel config need the TS plugin in it;
-    // without one (libraries), ember() strips types.
+    // Only projects with their own babel config need the TS plugin in it.
+    // Without one (libraries), ember() strips types.
     if (project.hasFile("babel.config.js") && !(await hasConfiguredTSBabel(project))) {
       if (!explain) return false;
 
@@ -149,6 +149,8 @@ async function updatePackageJson(project) {
 }
 
 /**
+ * Copies the base's tsconfig, unless the project already has one.
+ *
  * @param {import('#utils/project.js').Project} project
  */
 async function addTSConfig(project) {
@@ -168,6 +170,11 @@ async function addTSConfig(project) {
 
   if (project.type === "library") {
     await cp(join(libraryBase, "tsconfig.json"), project.path("tsconfig.json"));
+    return;
+  }
+
+  if (project.type === "custom-element") {
+    await cp(join(customElementBase, "tsconfig.json"), project.path("tsconfig.json"));
   }
 }
 
@@ -176,7 +183,7 @@ async function addTSConfig(project) {
  */
 async function updateBabelConfig(project) {
   if (!project.hasFile("babel.config.js")) {
-    // No babel config to patch (libraries): ember() strips types.
+    // Nothing to patch (libraries): ember() strips types.
     return;
   }
 

package/src/layers/vitest/index.js

@@ -13,9 +13,13 @@ const deps = {
   webdriverio: "^9.29.1",
 };
 
-// Apps already get these from their base. The babel plugins are resolved
-// by name from the project by @nullvoxpopuli/ember-vite's no-config babel
-// fallback (decorator-transforms is already a base dependency).
+/**
+ * Apps already get these from their base.
+ *
+ * The babel plugins are resolved by name from the project,
+ * by @nullvoxpopuli/ember-vite's no-config babel fallback.
+ * (decorator-transforms is already a base dependency)
+ */
 const libraryDeps = {
   "@babel/plugin-transform-typescript": "^7.28.10",
   "@nullvoxpopuli/ember-vite": "workspace:*",
@@ -35,7 +39,7 @@ const scripts = {
 function depsFor(project) {
   return {
     ...deps,
-    ...(project.type === "library" ? libraryDeps : {}),
+    ...(project.isLibrary ? libraryDeps : {}),
   };
 }
 

package/src/utils/babel.js

@@ -80,8 +80,9 @@ export async function prependPlugin(project, plugin, configPath = "babel.config.
 }
 
 /**
- * The plugins value may be the array itself, or the array with
- * methods chained off of it: `[ ... ].filter(Boolean)`
+ * The plugins value may be:
+ * - the array itself
+ * - the array with methods chained off of it: `[ ... ].filter(Boolean)`
  *
  * @param {any} node
  * @returns {any | undefined} the underlying ArrayExpression

package/src/utils/buffer.js

@@ -1,8 +1,8 @@
 /**
+ * Takes a substring of a string based on byte offsets.
+ *
  * from https://github.com/ember-cli/ember-cli/blob/8ea5b2e22d37805f5749a4917e0ef25fac3c9cda/lib/models/blueprint.js#L1789
  *
- *  Takes a substring of a string based on byte offsets.
-
  * @param {string} value : The input string.
  * @param {number} start : The byte index of the substring start.
  * @param {number} end : The byte index of the substring end.

package/src/utils/cli.js

@@ -7,12 +7,12 @@ export function isInteractive() {
 }
 
 /**
- * I would like to have selecs look more like a table,
+ * I would like to have selects look more like a table,
  * but @clack/prompts makes this a bit hard.
  *
- * I tried using padding, but then when it prints your selection,
- * I don't think there is a way to format just that, so
- * there are a bunch of goofy spacings in the labels.
+ * I tried using padding.
+ * But when it prints your selection, I don't think there is a way to format just that.
+ * So there are a bunch of goofy spacings in the labels.
  */
 const PADDING = 10;