@inglorious/create-app 1.1.2 → 1.2.0

package/bin/lib/app.js

@@ -0,0 +1,402 @@
+import fs from "fs"
+import { EOL } from "os"
+import path from "path"
+
+import * as jsxComponents from "./app-jsx.js"
+import * as litComponents from "./app-lit.js"
+import * as vueComponents from "./app-vue.js"
+import { INDENTATION } from "./constants.js"
+import { ICON_PACKS, LANGUAGES } from "./features.js"
+import { importBlock } from "./imports.js"
+import { appModel, call, LINE_WIDTH, union } from "./source.js"
+
+const COMPONENTS = {
+  "lit-html": litComponents,
+  jsx: jsxComponents,
+  vue: vueComponents,
+}
+
+/**
+ * Writes the source of an app with the features chosen: Inglorious UI,
+ * routing, page transitions, icon packs, internationalization and a mobile
+ * layout, in lit-html, JSX or Vue. It replaces the template's hello world,
+ * keeping its message type as the example on the home page. The files come
+ * out as Prettier and the template's ESLint config would leave them.
+ *
+ * @param {string} targetDir
+ * @param {object} pkg - The package.json being built; dependencies are added.
+ * @param {object} options
+ * @param {string} options.projectName
+ * @param {boolean} options.isTypeScript
+ * @param {"lit-html" | "jsx" | "vue"} options.renderer
+ * @param {boolean} options.ui
+ * @param {string} options.theme - A key of THEMES.
+ * @param {boolean} options.mobile
+ * @param {boolean} options.routing
+ * @param {boolean} options.transitions
+ * @param {string[]} options.icons - Keys of ICON_PACKS.
+ * @param {string[]} options.languages - Keys of LANGUAGES, the default first.
+ */
+export function addAppFeatures(targetDir, pkg, options) {
+  const app = { ...options, ext: options.isTypeScript ? "ts" : "js" }
+  app.i18n = Boolean(app.languages.length)
+  // On a phone the pages are tabs at the bottom; elsewhere, links on top.
+  app.tabs = app.ui && app.routing && app.mobile
+  app.links = app.routing && !app.tabs
+  app.isVue = app.renderer === "vue"
+
+  const components = COMPONENTS[app.renderer]
+  const componentExt = components.extension(app)
+  const model = appModel(app)
+
+  addDependencies(pkg, app)
+
+  const files = {
+    [`src/main.${app.ext}`]: mainSource(app),
+    [`src/app.${componentExt}`]: components.appSource(app, model),
+    "src/app.css": appStyles(app),
+    [`src/pages/home.${componentExt}`]: components.homeSource(app, model),
+    [`src/types/message.${componentExt}`]: components.messageSource(app),
+    [`src/store/index.${app.ext}`]: storeSource(app),
+    [`src/store/entities.${app.ext}`]: entitiesSource(app),
+  }
+  if (app.routing) {
+    files[`src/pages/about.${componentExt}`] = components.aboutSource(app)
+    files[`src/store/routes.${app.ext}`] = routesSource(app)
+  }
+  if (app.i18n) {
+    files[`src/i18n/index.${app.ext}`] = i18nSource(app)
+    for (const language of app.languages) {
+      files[`src/i18n/locales/${language}.json`] =
+        JSON.stringify(LANGUAGES[language].texts, null, INDENTATION) + EOL
+    }
+  }
+  if (app.isTypeScript) {
+    files["types/index.d.ts"] = typesSource(app)
+  }
+
+  for (const [file, source] of Object.entries(files)) {
+    const filePath = path.join(targetDir, file)
+    fs.mkdirSync(path.dirname(filePath), { recursive: true })
+    fs.writeFileSync(filePath, source)
+  }
+
+  if (app.ui) applyTheme(targetDir, app)
+}
+
+function addDependencies(pkg, app) {
+  pkg.dependencies ??= {}
+  if (app.ui) pkg.dependencies["@inglorious/ui"] = "workspace:*"
+  if (app.i18n) pkg.dependencies["@inglorious/i18n"] = "workspace:*"
+  for (const key of app.icons) {
+    Object.assign(pkg.dependencies, ICON_PACKS[key].packages)
+  }
+}
+
+// The theme is a class on <body>, which the theme's stylesheet is scoped to.
+function applyTheme(targetDir, app) {
+  const htmlPath = path.join(targetDir, "index.html")
+  if (!fs.existsSync(htmlPath)) return
+  const page = fs.readFileSync(htmlPath, "utf-8")
+  fs.writeFileSync(
+    htmlPath,
+    page.replace("<body>", `<body class="iw-theme-${app.theme}">`),
+  )
+}
+
+// An import of one of the app's components: Vue's name their file, and
+// TypeScript cannot read .vue files, so it is told to expect that.
+function componentImport(app, names, from) {
+  if (!app.isVue) return `import { ${names} } from "${from}"`
+  const line = `import { ${names} } from "${from}.vue"`
+  return app.isTypeScript
+    ? `// @ts-expect-error - Handled by @inglorious/vite-plugin-vue\n${line}`
+    : line
+}
+
+// ---------------------------------------------------------------- main
+
+function mainSource(app) {
+  const imports = []
+  if (app.ui) {
+    imports.push(
+      'import "@inglorious/ui/base.css"',
+      `import "@inglorious/ui/themes/${app.theme}.css"`,
+      ...uiComponents(app).map((name) => `import "@inglorious/ui/${name}.css"`),
+    )
+    if (app.transitions) {
+      imports.push('import "@inglorious/ui/view-transitions.css"')
+    }
+  }
+  imports.push('import "./app.css"')
+  if (app.transitions) {
+    imports.push(
+      'import { withTransitions } from "@inglorious/ui/view-transitions"',
+    )
+  }
+  imports.push(
+    'import { mount } from "@inglorious/web"',
+    componentImport(app, "App", "./app"),
+    'import { store } from "./store"',
+  )
+  if (app.i18n) imports.push('import { ready } from "./i18n"')
+
+  const args = [
+    app.transitions ? "withTransitions(store)" : "store",
+    "(api) => App.render(null, api)",
+    app.isTypeScript
+      ? 'document.getElementById("root")!'
+      : 'document.getElementById("root")',
+  ]
+
+  const body = app.i18n
+    ? `// Mounts once the starting language has loaded, so the first render is
+// already translated.
+ready.then(() =>
+${call("mount", args, "  ", ",")}
+)`
+    : call("mount", args, "", "")
+
+  return `${importBlock(imports)}
+
+${body}
+`
+}
+
+// The Inglorious UI components the app uses, for their stylesheets.
+function uiComponents(app) {
+  const names = ["app-bar", "container"]
+  if (app.links) names.push("link")
+  if (app.tabs) names.push("bottom-navigation")
+  if (app.icons.length) names.push("icon")
+  if (app.i18n) names.push("select")
+  return names
+}
+
+function appStyles(app) {
+  const layout = `body {
+  min-height: 100dvh;
+  display: flex;
+  flex-direction: column;
+}
+
+#root {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+}
+
+main {
+  flex: 1;
+  padding-block: 1.5rem;
+}
+
+.app-nav {
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+}
+`
+  if (app.ui) {
+    // In Vue the navigation is the app bar's content rather than its trailing
+    // slot, so it pushes itself to the end.
+    return app.isVue
+      ? `${layout}
+.iw-app-bar .app-nav {
+  margin-inline-start: auto;
+}
+`
+      : layout
+  }
+  return `${layout}
+header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 1rem 1.5rem;
+  border-block-end: 1px solid #ddd;
+}
+
+main {
+  padding-inline: 1.5rem;
+}
+`
+}
+
+// ---------------------------------------------------------------- store
+
+function storeSource(app) {
+  const imports = [
+    app.isTypeScript
+      ? 'import { createStore, type TypesConfig } from "@inglorious/store"'
+      : 'import { createStore } from "@inglorious/store"',
+    componentImport(app, "Home", "../pages/home"),
+    componentImport(app, "Message", "../types/message"),
+    'import { entities } from "./entities"',
+    'import { middlewares } from "./middlewares"',
+  ]
+  if (app.routing) {
+    imports.push(
+      'import { Router, setRoutes } from "@inglorious/web/router"',
+      componentImport(app, "About", "../pages/about"),
+      'import { routes } from "./routes"',
+    )
+  }
+  if (app.isTypeScript) {
+    imports.push('import type { AppEntity, AppState } from "../../types"')
+  }
+  if (app.i18n) imports.push('import { I18n } from "../i18n"')
+
+  const types = ["Message", "Home"]
+  if (app.routing) types.push("About", "Router")
+  if (app.i18n) types.push("I18n")
+  const cast = app.isTypeScript ? " as unknown as TypesConfig<AppEntity>" : ""
+  const oneLine = `  types: { ${types.join(", ")} }${cast},`
+  const typesValue =
+    oneLine.length <= LINE_WIDTH
+      ? oneLine
+      : `  types: {
+${types.map((type) => `    ${type},`).join("\n")}
+  }${cast},`
+  const generics = app.isTypeScript ? "<AppEntity, AppState>" : ""
+
+  return `${importBlock(imports)}
+${app.routing ? "\nsetRoutes(routes)\n" : ""}
+export const store = createStore${generics}({
+${typesValue}
+  entities,
+  middlewares,
+  // Creates an entity for each type that has none: ${singletons(app).join(", ")}.
+  autoCreateEntities: true,
+})
+`
+}
+
+// The entities the store creates on its own, as the comment in the store
+// lists them.
+function singletons(app) {
+  const ids = ["home"]
+  if (app.routing) ids.push("about", "router")
+  if (app.i18n) ids.push("i18n")
+  return ids
+}
+
+// Only the entities that need data, or come more than one to a type; the
+// store creates the rest.
+function entitiesSource(app) {
+  const head = app.isTypeScript
+    ? `import type { AppState } from "../../types"
+
+export const entities: Partial<AppState> = {`
+    : "export const entities = {"
+  return `${head}
+  message1: { type: "Message", who: "world" },
+  message2: { type: "Message", who: "wide" },
+  message3: { type: "Message", who: "web" },
+}
+`
+}
+
+function routesSource(app) {
+  const head = app.isTypeScript
+    ? `import type { RoutesConfig } from "@inglorious/web/router"
+
+// Each path names the entity its page renders.
+export const routes: RoutesConfig = {`
+    : `// Each path names the entity its page renders.
+export const routes = {`
+  return `${head}
+  "/": "home",
+  "/about": "about",
+}
+`
+}
+
+// ---------------------------------------------------------------- i18n
+
+function i18nSource(app) {
+  const [defaultLocale] = app.languages
+  return `import { createI18n } from "@inglorious/i18n"
+
+// One catalogue per language in ./locales, loaded when it is needed. Adding a
+// language is adding its file.
+export const { I18n, t, ready } = createI18n({
+  catalogues: import.meta.glob("./locales/*.json"),
+  defaultLocale: "${defaultLocale}",
+  storageKey: "${app.projectName}-locale",
+})
+`
+}
+
+// ---------------------------------------------------------------- types
+
+function typesSource(app) {
+  const imports = [
+    'import "./vite-end"',
+    'import type { BaseEntity, EntitiesState } from "@inglorious/store"',
+    'import type { Api, TemplateResult } from "@inglorious/web"',
+  ]
+  const entities = ["MessageEntity", "HomeEntity"]
+  const declarations = [
+    `export interface MessageEntity extends BaseEntity {
+  type: "Message"
+  id?: string
+  who: string
+  isUpperCase?: boolean
+}`,
+    `export interface HomeEntity extends BaseEntity {
+  type: "Home"
+}`,
+  ]
+  const state = [
+    "  home: HomeEntity",
+    "  message1: MessageEntity",
+    "  message2: MessageEntity",
+    "  message3: MessageEntity",
+  ]
+
+  if (app.routing) {
+    imports.push('import type { RouterEntity } from "@inglorious/web/router"')
+    entities.push("AboutEntity", "AppRouterEntity")
+    declarations.push(
+      `export interface AboutEntity extends BaseEntity {
+  type: "About"
+}`,
+      `export interface AppRouterEntity extends BaseEntity, Omit<RouterEntity, "id"> {
+  type: "Router"
+}`,
+    )
+    state.unshift("  router: AppRouterEntity")
+    state.push("  about: AboutEntity")
+  }
+  if (app.i18n) {
+    imports.push('import type { I18nEntity } from "@inglorious/i18n"')
+    entities.push("AppI18nEntity")
+    declarations.push(
+      `export interface AppI18nEntity extends BaseEntity, Omit<I18nEntity, "id"> {
+  type: "I18n"
+}`,
+    )
+    state.unshift("  i18n: AppI18nEntity")
+  }
+
+  return `${importBlock(imports)}
+
+${declarations.join("\n\n")}
+
+// Union type of all entities
+${union("AppEntity", entities)}
+
+// State type with known entity IDs
+export interface AppState extends EntitiesState<AppEntity> {
+${state.join("\n")}
+}
+
+export type AppApi = Api<AppEntity, AppState>
+
+export interface MessageType {
+  click: (entity: MessageEntity) => void
+  render: (entity: MessageEntity, api: AppApi) => TemplateResult | null
+}
+`
+}

package/bin/lib/cli.js

@@ -2,6 +2,13 @@ export function parseCliOptions(args) {
   return {
     mobile: readBooleanFlag(args, "mobile"),
     pwa: readBooleanFlag(args, "pwa"),
+    ui: readBooleanFlag(args, "ui"),
+    theme: readValueFlag(args, "theme"),
+    routing: readBooleanFlag(args, "routing"),
+    transitions: readBooleanFlag(args, "transitions"),
+    icons: readListFlag(args, "icons"),
+    i18n: readBooleanFlag(args, "i18n"),
+    languages: readListFlag(args, "languages"),
   }
 }
 
@@ -16,3 +23,27 @@ export function readBooleanFlag(args, name) {
 
   return null
 }
+
+// `--name=value`, or null when the flag is not given.
+export function readValueFlag(args, name) {
+  const prefix = `--${name}=`
+  const arg = args.find((value) => value.startsWith(prefix))
+  return arg ? arg.slice(prefix.length) : null
+}
+
+// `--name=a,b`, `--no-name` for an empty list, or null when neither is given.
+export function readListFlag(args, name) {
+  if (args.includes(`--no-${name}`)) {
+    return []
+  }
+
+  const value = readValueFlag(args, name)
+  if (value === null) {
+    return null
+  }
+
+  return value
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean)
+}

package/bin/lib/constants.js

@@ -1,6 +1,6 @@
-export const CAPACITOR_VERSION = "^8.5.1"
-export const VITE_PLUGIN_PWA_VERSION = "^1.3.0"
-export const VITE_PWA_ASSETS_GENERATOR_VERSION = "^1.0.2"
+export const CAPACITOR_VERSION = "^8.5.3"
+export const VITE_PLUGIN_PWA_VERSION = "^2.0.0"
+export const VITE_PWA_ASSETS_GENERATOR_VERSION = "^2.0.0"
 export const TYPESCRIPT_VERSION = "^7.0.2"
 export const WORKBOX_WINDOW_VERSION = "^7.4.1"
 

package/bin/lib/features.js

@@ -0,0 +1,142 @@
+// The choices create-app offers for lit-html apps, and what each one brings.
+
+export const THEMES = {
+  inglorious: { title: "Inglorious", description: "Neon, videogame-inspired" },
+  material: { title: "Material", description: "Material Design inspired" },
+  bootstrap: { title: "Bootstrap", description: "Bootstrap inspired" },
+}
+
+// Icon sets from Iconify: one module per icon, so only the icons an app
+// imports are bundled. `nav` names the icons for the two example pages,
+// `showcase` the one shown on the home page.
+export const ICON_PACKS = {
+  material: {
+    title: "Material Symbols",
+    packages: { "@iconify-icons/material-symbols": "^2.0.6" },
+    nav: {
+      home: from("homeOutline", "@iconify-icons/material-symbols/home-outline"),
+      about: from(
+        "infoOutline",
+        "@iconify-icons/material-symbols/info-outline",
+      ),
+    },
+    showcase: {
+      ...from(
+        "favoriteOutline",
+        "@iconify-icons/material-symbols/favorite-outline",
+      ),
+      label: "Material Symbols",
+    },
+  },
+  fontawesome: {
+    title: "Font Awesome",
+    packages: {
+      "@iconify-icons/fa7-solid": "^2.0.0",
+      "@iconify-icons/fa7-regular": "^2.0.0",
+      "@iconify-icons/fa7-brands": "^2.0.0",
+    },
+    nav: {
+      home: from("house", "@iconify-icons/fa7-solid/house"),
+      about: from("circleInfo", "@iconify-icons/fa7-solid/circle-info"),
+    },
+    showcase: {
+      ...from("fontAwesome", "@iconify-icons/fa7-brands/font-awesome"),
+      label: "Font Awesome",
+    },
+  },
+  lucide: {
+    title: "Lucide",
+    packages: { "@iconify-icons/lucide": "^2.0.22" },
+    nav: {
+      home: from("house", "@iconify-icons/lucide/house"),
+      about: from("info", "@iconify-icons/lucide/info"),
+    },
+    showcase: {
+      ...from("sparkles", "@iconify-icons/lucide/sparkles"),
+      label: "Lucide",
+    },
+  },
+}
+
+// The languages offered for the example app, with its few texts in each.
+export const LANGUAGES = {
+  en: language("English", {
+    nav: { home: "Home", about: "About" },
+    language: "Language",
+    home: { title: "Welcome", hint: "Click a greeting to shout it." },
+    about: { title: "About", body: "A page of its own, at its own address." },
+    message: { hello: "Hello {{who}}" },
+  }),
+  it: language("Italiano", {
+    nav: { home: "Home", about: "Info" },
+    language: "Lingua",
+    home: { title: "Benvenuto", hint: "Clicca un saluto per urlarlo." },
+    about: { title: "Info", body: "Una pagina tutta sua, al suo indirizzo." },
+    message: { hello: "Ciao {{who}}" },
+  }),
+  fr: language("Français", {
+    nav: { home: "Accueil", about: "À propos" },
+    language: "Langue",
+    home: { title: "Bienvenue", hint: "Cliquez sur un salut pour le crier." },
+    about: {
+      title: "À propos",
+      body: "Une page à part entière, à sa propre adresse.",
+    },
+    message: { hello: "Bonjour {{who}}" },
+  }),
+  de: language("Deutsch", {
+    nav: { home: "Start", about: "Über" },
+    language: "Sprache",
+    home: {
+      title: "Willkommen",
+      hint: "Klicke auf einen Gruß, um ihn zu rufen.",
+    },
+    about: { title: "Über", body: "Eine eigene Seite unter eigener Adresse." },
+    message: { hello: "Hallo {{who}}" },
+  }),
+  es: language("Español", {
+    nav: { home: "Inicio", about: "Acerca de" },
+    language: "Idioma",
+    home: { title: "Bienvenido", hint: "Haz clic en un saludo para gritarlo." },
+    about: {
+      title: "Acerca de",
+      body: "Una página propia, en su propia dirección.",
+    },
+    message: { hello: "Hola {{who}}" },
+  }),
+  pt: language("Português", {
+    nav: { home: "Início", about: "Sobre" },
+    language: "Idioma",
+    home: { title: "Bem-vindo", hint: "Clique numa saudação para gritá-la." },
+    about: {
+      title: "Sobre",
+      body: "Uma página própria, no seu próprio endereço.",
+    },
+    message: { hello: "Olá {{who}}" },
+  }),
+  ja: language("日本語", {
+    nav: { home: "ホーム", about: "概要" },
+    language: "言語",
+    home: {
+      title: "ようこそ",
+      hint: "あいさつをクリックすると大きくなります。",
+    },
+    about: { title: "概要", body: "専用のアドレスを持つ独立したページです。" },
+    message: { hello: "こんにちは、{{who}}" },
+  }),
+  ar: language("العربية", {
+    nav: { home: "الرئيسية", about: "حول" },
+    language: "اللغة",
+    home: { title: "مرحبًا", hint: "انقر على تحية لتكبيرها." },
+    about: { title: "حول", body: "صفحة مستقلة بعنوانها الخاص." },
+    message: { hello: "مرحبًا {{who}}" },
+  }),
+}
+
+function from(name, source) {
+  return { name, from: source }
+}
+
+function language(title, texts) {
+  return { title, texts }
+}

package/bin/lib/imports.js

@@ -0,0 +1,64 @@
+// Import statements in the order eslint-plugin-simple-import-sort gives them,
+// so a generated project passes `eslint` as it is: side-effect imports first,
+// in the order given, then packages, then relative modules, a blank line
+// between groups.
+
+const collator = new Intl.Collator("en", { sensitivity: "base", numeric: true })
+
+/**
+ * @param {string[]} lines - One import statement each.
+ * @returns {string}
+ */
+export function importBlock(lines) {
+  const sideEffects = []
+  const packages = []
+  const relative = []
+
+  for (const line of lines) {
+    const source = sourceOf(line)
+    if (!line.includes(" from ")) sideEffects.push(line)
+    else if (source.startsWith(".")) relative.push(line)
+    else packages.push(line)
+  }
+
+  return [sideEffects, sortImports(packages), sortImports(relative)]
+    .filter((group) => group.length)
+    .map((group) => group.join("\n"))
+    .join("\n\n")
+}
+
+function sortImports(lines) {
+  return lines
+    .map((line) => ({ line, source: sourceOf(line) }))
+    .sort(
+      (a, b) =>
+        compare(normalize(a.source), normalize(b.source)) ||
+        compare(a.source, b.source) ||
+        // Type imports before regular ones from the same module.
+        Number(b.line.startsWith("import type")) -
+          Number(a.line.startsWith("import type")),
+    )
+    .map(({ line }) => line)
+}
+
+// The plugin's own normalization: by directory level, `.` and `/` before any
+// other punctuation.
+function normalize(source) {
+  return source
+    .replace(/^[./]*\.$/, "$&/")
+    .replace(/^[./]*\/$/, "$&,")
+    .replace(
+      /[./_-]/g,
+      (char) => ({ ".": "_", "/": "-", _: ".", "-": "/" })[char],
+    )
+}
+
+function compare(a, b) {
+  return collator.compare(a, b) || Number(a > b) - Number(a < b)
+}
+
+// The module an import statement imports from.
+function sourceOf(line) {
+  const [, source] = line.match(/"([^"]+)"/)
+  return source
+}

package/bin/lib/mobile.js

@@ -14,7 +14,9 @@ export function addMobileSupport(targetDir, pkg, projectName) {
   pkg.devDependencies["@capacitor/android"] = CAPACITOR_VERSION
   pkg.devDependencies["@capacitor/cli"] = CAPACITOR_VERSION
   pkg.devDependencies["@capacitor/ios"] = CAPACITOR_VERSION
-  pkg.devDependencies["typescript"] = TYPESCRIPT_VERSION
+  // For capacitor.config.ts. A TypeScript template already has its own, which
+  // its code is written against.
+  pkg.devDependencies["typescript"] ??= TYPESCRIPT_VERSION
 
   pkg.scripts.cap = "cap"
   pkg.scripts["mobile:init:ios"] = "cap add ios"
@@ -27,10 +29,26 @@ export function addMobileSupport(targetDir, pkg, projectName) {
     path.join(targetDir, "capacitor.config.ts"),
     createCapacitorConfigSource(projectName),
   )
+  includeInNodeProject(targetDir, "capacitor.config.ts")
 
   appendMobileSetupToReadme(targetDir)
 }
 
+// A TypeScript template type-checks and lints its config files through
+// tsconfig.node.json, so a new one has to be listed there. Edited as text, so
+// the `include` line keeps the one-line layout Prettier gives it.
+function includeInNodeProject(targetDir, file) {
+  const tsconfigPath = path.join(targetDir, "tsconfig.node.json")
+  if (!fs.existsSync(tsconfigPath)) return
+
+  const tsconfig = fs.readFileSync(tsconfigPath, "utf-8")
+  if (tsconfig.includes(`"${file}"`)) return
+  fs.writeFileSync(
+    tsconfigPath,
+    tsconfig.replace(/("include": \[[^\]]*)\]/, `$1, "${file}"]`),
+  )
+}
+
 export function appendMobileSetupToReadme(targetDir) {
   const readmePath = path.join(targetDir, "README.md")
   if (!fs.existsSync(readmePath)) {