@inglorious/create-app 1.1.2 → 1.3.0

package/README.md

@@ -23,17 +23,31 @@ pnpm create @inglorious/app
 
 The CLI will guide you through the setup process, asking for a project name and which template you'd like to use.
 
-For JavaScript and TypeScript Vite app templates, the CLI can also add optional app targets:
+For the JavaScript and TypeScript Vite templates, the CLI then asks about the app's features:
+
+| Question                  | Flag                                                 | Adds                                                                                                  |
+| ------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| Use Inglorious UI?        | `--ui` / `--no-ui`                                   | `@inglorious/ui`, its base styles and an app bar                                                      |
+| Which theme?              | `--theme=inglorious\|material\|bootstrap`            | The theme's stylesheet and class                                                                      |
+| Is it a mobile app?       | `--mobile` / `--no-mobile`                           | Capacitor for Android and iOS; with Inglorious UI, a bottom tab bar and safe-area spacing             |
+| Add routing?              | `--routing` / `--no-routing`                         | The Router, a home and an about page, and navigation between them                                     |
+| Animate page transitions? | `--transitions` / `--no-transitions`                 | View transitions between pages (with routing and Inglorious UI)                                       |
+| Which icon packs?         | `--icons=material,fontawesome,lucide` / `--no-icons` | Iconify icon sets, drawn by Inglorious UI's `Icon` (with Inglorious UI)                               |
+| Translate the app?        | `--i18n` / `--no-i18n`, `--languages=en,it`          | `@inglorious/i18n`, a catalogue per language and a language picker; the first language is the default |
+| Enable PWA support?       | `--pwa` / `--no-pwa`                                 | `vite-plugin-pwa`, a manifest, icons and service worker registration                                  |
+
+The app is generated in the syntax you chose: lit-html, JSX or Vue. Every question answered on the command line is skipped, so a project can be created without any prompt:
+
+| Question                    | Argument or flag                             |
+| --------------------------- | -------------------------------------------- |
+| What is your project named? | The first argument, such as `my-app`         |
+| Select a template           | `--template=minimal\|js\|ts\|ssx-js\|ssx-ts` |
+| Select a rendering syntax   | `--syntax=lit-html\|jsx\|vue`                |
 
 ```bash
-npm create @inglorious/app@latest -- --pwa
-npm create @inglorious/app@latest -- --mobile
-npm create @inglorious/app@latest -- --pwa --mobile
+npm create @inglorious/app@latest -- my-app --template=ts --syntax=jsx --ui --theme=material --routing --transitions --icons=material --languages=en,it --no-mobile --no-pwa
 ```
 
-- `--pwa` adds `vite-plugin-pwa`, a basic web app manifest configuration, PWA icons, and browser-only service worker registration.
-- `--mobile` adds Capacitor dependencies, config, and mobile scripts for iOS and Android.
-
 ## Templates
 
 The following templates are available to get you started:

package/bin/index.js

@@ -8,22 +8,26 @@ import path from "path"
 import prompts from "prompts"
 import { fileURLToPath } from "url"
 
+import { addAppFeatures } from "./lib/app.js"
 import { parseCliOptions } from "./lib/cli.js"
 import {
-  EMPTY_LENGTH,
   INDENTATION,
   NPM_VIEW_TIMEOUT_MS,
   USER_ARG_START_INDEX,
   VITE_APP_TEMPLATES,
 } from "./lib/constants.js"
+import { SYNTAXES, TEMPLATES } from "./lib/features.js"
 import { copyDir } from "./lib/file.js"
 import { addMobileSupport } from "./lib/mobile.js"
 import { addPwaSupport } from "./lib/pwa.js"
+import { askAppFeatures } from "./lib/questions.js"
 
 async function main() {
   const __dirname = path.dirname(fileURLToPath(import.meta.url))
   const templatesRoot = path.join(__dirname, "../templates")
   const cliOptions = parseCliOptions(process.argv.slice(USER_ARG_START_INDEX))
+  validateChoice("template", cliOptions.template, TEMPLATES)
+  validateChoice("syntax", cliOptions.syntax, SYNTAXES)
 
   let canceled = false
 
@@ -32,45 +36,19 @@ async function main() {
     return false
   }
 
-  const { projectName, baseTemplate } = await prompts(
+  const answers = await prompts(
     [
       {
-        type: "text",
+        type: cliOptions.projectName ? null : "text",
         name: "projectName",
         message: "What is your project named?",
         initial: "my-app",
       },
       {
-        type: "select",
+        type: cliOptions.template ? null : "select",
         name: "baseTemplate",
         message: "Select a template",
-        choices: [
-          {
-            title: "Minimal",
-            description: "A single HTML file for a zero-build setup",
-            value: "minimal",
-          },
-          {
-            title: "JavaScript",
-            description: "A vanilla JavaScript setup with Vite",
-            value: "js",
-          },
-          {
-            title: "TypeScript",
-            description: "A TypeScript setup with Vite",
-            value: "ts",
-          },
-          {
-            title: "SSX (JavaScript)",
-            description: "Static Site Xecution with JavaScript",
-            value: "ssx-js",
-          },
-          {
-            title: "SSX (TypeScript)",
-            description: "Static Site Xecution with TypeScript",
-            value: "ssx-ts",
-          },
-        ],
+        choices: toChoices(TEMPLATES),
       },
     ],
     { onCancel },
@@ -81,33 +59,18 @@ async function main() {
     return
   }
 
+  const projectName = cliOptions.projectName ?? answers.projectName
+  const baseTemplate = cliOptions.template ?? answers.baseTemplate
+
   let renderer = "lit-html"
-  let pwa = cliOptions.pwa === true
-  let mobile = cliOptions.mobile === true
 
   if (baseTemplate !== "minimal") {
     const { selectedRenderer } = await prompts(
       {
-        type: "select",
+        type: cliOptions.syntax ? null : "select",
         name: "selectedRenderer",
         message: "Select a rendering syntax",
-        choices: [
-          {
-            title: "lit-html (default)",
-            description: "Tagged template literals (html`<div>...</div>`)",
-            value: "lit-html",
-          },
-          {
-            title: "JSX",
-            description: "JSX/TSX syntax (<div>...</div>)",
-            value: "jsx",
-          },
-          {
-            title: "Vue",
-            description: "Vue SFC-style templates",
-            value: "vue",
-          },
-        ],
+        choices: toChoices(SYNTAXES),
       },
       { onCancel },
     )
@@ -117,49 +80,31 @@ async function main() {
       return
     }
 
-    renderer = selectedRenderer
+    renderer = cliOptions.syntax ?? selectedRenderer
+  } else if (cliOptions.syntax && cliOptions.syntax !== "lit-html") {
+    console.warn("The minimal template is only available with lit-html.")
   }
 
-  const supportsAppFeatures = VITE_APP_TEMPLATES.has(baseTemplate)
-
-  if (supportsAppFeatures) {
-    const featureQuestions = []
-
-    if (cliOptions.pwa === null) {
-      featureQuestions.push({
-        type: "confirm",
-        name: "pwa",
-        message: "Enable PWA support?",
-        initial: false,
-      })
-    }
-
-    if (cliOptions.mobile === null) {
-      featureQuestions.push({
-        type: "confirm",
-        name: "mobile",
-        message: "Add hybrid mobile support with Capacitor?",
-        initial: false,
-      })
-    }
-
-    if (featureQuestions.length > EMPTY_LENGTH) {
-      const answers = await prompts(featureQuestions, { onCancel })
+  let features = {
+    ui: false,
+    routing: false,
+    icons: [],
+    languages: [],
+    mobile: false,
+    pwa: false,
+  }
 
-      if (canceled) {
-        console.log("Operation canceled.")
-        return
-      }
+  if (VITE_APP_TEMPLATES.has(baseTemplate)) {
+    features = await askAppFeatures(cliOptions)
 
-      pwa = cliOptions.pwa === true ? true : answers.pwa === true
-      mobile = cliOptions.mobile === true ? true : answers.mobile === true
+    if (!features) {
+      console.log("Operation canceled.")
+      return
     }
-  } else if (pwa || mobile) {
+  } else if (cliOptions.pwa || cliOptions.mobile) {
     console.warn(
       "PWA and mobile options are only available for JavaScript and TypeScript Vite app templates.",
     )
-    pwa = false
-    mobile = false
   }
 
   const spinner = ora(`Creating project "${projectName}"...`).start()
@@ -194,12 +139,28 @@ async function main() {
     const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"))
     pkg.name = projectName
 
-    if (pwa) {
+    const hasAppFeatures =
+      features.ui ||
+      features.routing ||
+      Boolean(features.icons.length) ||
+      Boolean(features.languages.length)
+
+    if (hasAppFeatures) {
+      spinner.text = "Adding app features..."
+      addAppFeatures(targetDir, pkg, {
+        ...features,
+        projectName,
+        isTypeScript: baseTemplate === "ts",
+        renderer,
+      })
+    }
+
+    if (features.pwa) {
       spinner.text = "Adding PWA support..."
       addPwaSupport(targetDir, pkg, projectName)
     }
 
-    if (mobile) {
+    if (features.mobile) {
       spinner.text = "Adding Capacitor support..."
       addMobileSupport(targetDir, pkg, projectName)
     }
@@ -228,6 +189,21 @@ async function main() {
   }
 }
 
+function toChoices(options) {
+  return Object.entries(options).map(([value, option]) => ({
+    value,
+    ...option,
+  }))
+}
+
+function validateChoice(flag, value, options) {
+  if (value !== null && !options[value]) {
+    throw new Error(
+      `Unknown ${flag} "${value}". Choose one of: ${Object.keys(options).join(", ")}.`,
+    )
+  }
+}
+
 function getLatestVersion(packageName) {
   try {
     const version = execSync(`npm view ${packageName} version`, {

package/bin/lib/app-jsx.js

@@ -0,0 +1,280 @@
+// The app's components in JSX: .jsx or .tsx files, compiled to lit-html by
+// @inglorious/vite-plugin-jsx. A capitalized tag with props renders a
+// component; `<Message entityId="message1" />` renders an entity. TypeScript
+// expects components to be functions, so in .tsx each capitalized tag is
+// preceded by a `@ts-expect-error`.
+
+import { renderLocals, selectChange } from "./app-lit.js"
+import { importBlock } from "./imports.js"
+
+export const extension = (app) => (app.isTypeScript ? "tsx" : "jsx")
+
+const EXPECT_ERROR =
+  "@ts-expect-error - Inglorious components are objects, not functions"
+
+// The comment line before a capitalized tag in .tsx: `{/* */}` among JSX
+// children, `//` inside code.
+function expectError(app, indent, isChild = true) {
+  if (!app.isTypeScript) return ""
+  const comment = isChild ? `{/* ${EXPECT_ERROR} */}` : `// ${EXPECT_ERROR}`
+  return `${indent}${comment}\n`
+}
+
+export function appSource(app, { pages, navIcons }) {
+  const imports = []
+  if (navIcons) {
+    for (const icon of Object.values(navIcons)) {
+      imports.push(`import ${icon.name} from "${icon.from}"`)
+    }
+    imports.push('import { Icon } from "@inglorious/ui/icon"')
+  }
+  if (app.ui) {
+    imports.push(
+      'import { AppBar } from "@inglorious/ui/app-bar"',
+      'import { Container } from "@inglorious/ui/container"',
+    )
+    if (app.tabs) {
+      imports.push(
+        'import { BottomNavigation } from "@inglorious/ui/bottom-navigation"',
+      )
+    }
+    if (app.links) imports.push('import { Link } from "@inglorious/ui/link"')
+    if (app.i18n) imports.push('import { Select } from "@inglorious/ui/select"')
+  }
+  if (app.isTypeScript) imports.push('import type { AppApi } from "../types"')
+  if (app.i18n) imports.push('import { t } from "./i18n"')
+
+  const signature = app.isTypeScript
+    ? "render(props: Record<string, unknown> | null, api: AppApi)"
+    : "render(props, api)"
+  const content = app.routing
+    ? "api.render(router.route)"
+    : 'api.render("home")'
+
+  const shell = app.ui
+    ? uiShell(app, { pages, content })
+    : plainShell(app, { pages, content })
+
+  return `${importBlock(imports)}
+
+export const App = {
+  ${signature} {
+${renderLocals(app)}    return (
+      <>
+${shell}
+      </>
+    )
+  },
+}
+`
+}
+
+// A callback's parameter. The components' props are not typed in .tsx, so
+// TypeScript cannot infer it.
+function typed(app, name, type) {
+  return app.isTypeScript ? `${name}: ${type}` : name
+}
+
+// A page's label: translated, or the English text.
+function labelText(app, page) {
+  return app.i18n ? `{t("${page.key}")}` : page.text
+}
+
+function labelValue(app, page) {
+  return app.i18n ? `t("${page.key}")` : `"${page.text}"`
+}
+
+function uiShell(app, { pages, content }) {
+  const nav = []
+  if (app.links) {
+    nav.push(
+      ...pages.map(
+        (page) =>
+          `${expectError(app, "                ")}                <Link href="${page.path}">${labelText(app, page)}</Link>`,
+      ),
+    )
+  }
+  if (app.i18n) {
+    nav.push(`${expectError(app, "                ")}                <Select
+                  value={i18n.locale}
+                  options={i18n.languages}
+                  size="sm"
+                  ariaLabel={t("language")}
+                  onChange={(${typed(app, "locale", "string")}) =>
+                    api.notify("#i18n:localeChange", locale)
+                  }
+                />`)
+  }
+
+  const appBar = nav.length
+    ? `${expectError(app, "          ")}          <AppBar
+            title="${app.projectName}"
+            trailing={
+              <nav className="app-nav">
+${nav.join("\n")}
+              </nav>
+            }
+          />`
+    : `${expectError(app, "          ")}          <AppBar title="${app.projectName}" />`
+
+  const header = `        <header${app.mobile ? ' className="pt-safe"' : ""}>
+${appBar}
+        </header>
+        <main>
+${expectError(app, "          ")}          <Container maxWidth="md">{${content}}</Container>
+        </main>`
+
+  if (!app.tabs) return header
+
+  const actions = pages.map((page) => {
+    const icon = page.icon
+      ? `
+${expectError(app, "                ", false)}                icon: <Icon icon={${page.icon.name}} size="lg" />,`
+      : ""
+    return `              {
+                value: "${page.path}",
+                label: ${labelValue(app, page)},${icon}
+              },`
+  })
+
+  return `${header}
+        <footer className="pb-safe">
+${expectError(app, "          ")}          <BottomNavigation
+            value={router.path}
+            actions={[
+${actions.join("\n")}
+            ]}
+            onChange={(${typed(app, "path", "string")}) => api.notify("#router:navigate", path)}
+          />
+        </footer>`
+}
+
+function plainShell(app, { pages, content }) {
+  const nav = app.routing
+    ? pages.map(
+        (page) =>
+          `            <a href="${page.path}">${labelText(app, page)}</a>`,
+      )
+    : []
+  if (app.i18n) {
+    nav.push(`            <select
+              aria-label={t("language")}
+              onChange={${selectChange(app, "              ")}
+              }
+            >
+              {i18n.languages${app.isTypeScript ? "?." : "."}map((language) => (
+                <option
+                  key={language.value}
+                  value={language.value}
+                  selected={language.value === i18n.locale}
+                >
+                  {language.label}
+                </option>
+              ))}
+            </select>`)
+  }
+  const navBlock = nav.length
+    ? `
+          <nav className="app-nav">
+${nav.join("\n")}
+          </nav>`
+    : ""
+
+  return `        <header>
+          <strong>${app.projectName}</strong>${navBlock}
+        </header>
+        <main>{${content}}</main>`
+}
+
+export function homeSource(app, { showcase }) {
+  const imports = ['import { Message } from "../types/message"']
+  for (const icon of showcase) {
+    imports.push(`import ${icon.name} from "${icon.from}"`)
+  }
+  if (showcase.length) {
+    imports.push('import { Icon } from "@inglorious/ui/icon"')
+  }
+  if (app.i18n) imports.push('import { t } from "../i18n"')
+
+  const text = (key, fallback) => (app.i18n ? `{t("${key}")}` : fallback)
+  const icons = showcase.length
+    ? `
+        <p className="app-icons">
+${showcase
+  .map(
+    (icon) =>
+      `${expectError(app, "          ")}          <Icon icon={${icon.name}} size="lg" label="${icon.label}" />`,
+  )
+  .join("\n")}
+        </p>`
+    : ""
+
+  return `${importBlock(imports)}
+
+export const Home = {
+  render() {
+    return (
+      <>
+        <h1>${text("home.title", "Welcome")}</h1>
+        <p>
+${expectError(app, "          ")}          <Message entityId="message1" />, <Message entityId="message2" />,{" "}
+${expectError(app, "          ")}          <Message entityId="message3" />!
+        </p>
+        <p>${text("home.hint", "Click a greeting to shout it.")}</p>${icons}
+      </>
+    )
+  },
+}
+`
+}
+
+export function aboutSource(app) {
+  const head = app.i18n ? 'import { t } from "../i18n"\n\n' : ""
+  const text = (key, fallback) => (app.i18n ? `{t("${key}")}` : fallback)
+
+  return `${head}export const About = {
+  render() {
+    return (
+      <>
+        <h1>${text("about.title", "About")}</h1>
+        <p>${text("about.body", "A page of its own, at its own address.")}</p>
+      </>
+    )
+  },
+}
+`
+}
+
+export function messageSource(app) {
+  const imports = []
+  if (app.isTypeScript) {
+    imports.push('import type { MessageType } from "../../types"')
+  }
+  if (app.i18n) imports.push('import { t } from "../i18n"')
+  const greeting = app.i18n ? '{t("message.hello", { who })}' : "Hello {who}"
+  const declaration = app.isTypeScript
+    ? "export const Message: MessageType = {"
+    : "export const Message = {"
+
+  const span = app.i18n
+    ? `      <span onClick={() => api.notify(\`#\${entity.id}:click\`)}>
+        ${greeting}
+      </span>`
+    : `      <span onClick={() => api.notify(\`#\${entity.id}:click\`)}>${greeting}</span>`
+
+  const head = imports.length ? `${importBlock(imports)}\n\n` : ""
+
+  return `${head}${declaration}
+  click(entity) {
+    entity.isUpperCase = !entity.isUpperCase
+  },
+
+  render(entity, api) {
+    const who = entity.isUpperCase ? entity.who.toUpperCase() : entity.who
+    return (
+${span}
+    )
+  },
+}
+`
+}