create-spark-html-app 0.3.2

package/README.md

@@ -0,0 +1,46 @@
+# create-spark-html-app
+
+Scaffold a [Spark](https://github.com/wilkinnovo/spark) app in seconds — a Vite
+project wired to `spark-html` with a live, reactive **Welcome to Spark** screen.
+
+## Usage
+
+```bash
+npm create spark-html-app@latest my-app
+# or
+npx create-spark-html-app my-app
+```
+
+Then:
+
+```bash
+cd my-app
+npm install
+npm run dev
+```
+
+Run it with no name to be prompted:
+
+```bash
+npm create spark-html-app@latest
+```
+
+## What you get
+
+```
+my-app/
+├── index.html              ← import placeholder + boot script
+├── src/main.js             ← mount() + a shared store
+├── public/components/
+│   ├── app.html            ← theme + shell
+│   └── welcome.html        ← reactive welcome screen (counter, store, derived state)
+├── vite.config.js          ← spark-html/vite plugin
+└── package.json
+```
+
+Everything is plain HTML and JavaScript — no compiler, no virtual DOM, no
+proprietary file format. Edit a component, save, and the page reloads.
+
+## License
+
+MIT

package/bin/index.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+/**
+ * create-spark-html-app
+ *
+ *   npm create spark-html-app@latest my-app
+ *   npx create-spark-html-app my-app
+ *
+ * Scaffolds a ready-to-run Vite + spark-html project with a live,
+ * reactive "Welcome to Spark" screen. Zero runtime dependencies —
+ * just Node built-ins, in keeping with Spark's no-build ethos.
+ */
+import { fileURLToPath } from 'node:url';
+import { dirname, join, resolve, relative, basename } from 'node:path';
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from 'node:fs';
+import { createInterface } from 'node:readline/promises';
+import { stdin, stdout, argv, exit } from 'node:process';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const templateDir = resolve(here, '..', 'template');
+
+// ── tiny ANSI palette (no chalk; one less thing to install) ───────────
+const supportsColor = stdout.isTTY && process.env.NO_COLOR === undefined;
+const paint = (code) => (s) =>
+  supportsColor ? `\x1b[${code}m${s}\x1b[0m` : String(s);
+const c = {
+  spark: paint('38;5;220'), // ⚡ gold
+  accent: paint('38;5;141'), // spark purple
+  dim: paint('2'),
+  bold: paint('1'),
+  green: paint('32'),
+  red: paint('31'),
+  cyan: paint('36'),
+};
+
+const BOLT = c.spark('⚡');
+
+function bail(msg) {
+  stdout.write(`\n${c.red('✘')} ${msg}\n\n`);
+  exit(1);
+}
+
+// A valid, polite npm package name.
+function sanitizeName(name) {
+  return name
+    .trim()
+    .toLowerCase()
+    .replace(/^[._]+/, '')
+    .replace(/[^a-z0-9-~]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+function isEmptyDir(dir) {
+  if (!existsSync(dir)) return true;
+  const entries = readdirSync(dir).filter((f) => f !== '.git');
+  return entries.length === 0;
+}
+
+async function prompt(question, fallback) {
+  const rl = createInterface({ input: stdin, output: stdout });
+  try {
+    const answer = (await rl.question(question)).trim();
+    return answer || fallback;
+  } finally {
+    rl.close();
+  }
+}
+
+async function main() {
+  stdout.write(`\n${BOLT} ${c.bold('create-spark-html-app')}\n`);
+  stdout.write(`${c.dim('   HTML that reacts — no compiler, no virtual DOM.')}\n\n`);
+
+  // 1 ─ figure out the target directory ────────────────────────────────
+  let targetArg = argv[2];
+  if (!targetArg) {
+    if (!stdin.isTTY) bail('Please pass a project name: create-spark-html-app <name>');
+    targetArg = await prompt(
+      `${c.accent('?')} Project name: ${c.dim('(my-spark-app)')} `,
+      'my-spark-app',
+    );
+  }
+
+  const targetDir = resolve(process.cwd(), targetArg);
+  const projectName = sanitizeName(basename(targetDir)) || 'my-spark-app';
+
+  // 2 ─ make sure we won't clobber anything ────────────────────────────
+  if (!isEmptyDir(targetDir)) {
+    if (!stdin.isTTY) bail(`Directory "${targetArg}" already exists and is not empty.`);
+    const ok = await prompt(
+      `${c.accent('?')} "${targetArg}" is not empty. Continue and overwrite files? ${c.dim('(y/N)')} `,
+      'n',
+    );
+    if (!/^y(es)?$/i.test(ok)) bail('Aborted — nothing was written.');
+  }
+
+  // 3 ─ copy the template ──────────────────────────────────────────────
+  mkdirSync(targetDir, { recursive: true });
+  cpSync(templateDir, targetDir, { recursive: true });
+
+  // npm renames/strips dotfiles on publish, so the template ships them
+  // with safe underscore prefixes. Restore the real names here.
+  const dotfiles = [
+    ['_gitignore', '.gitignore'],
+    ['_npmrc', '.npmrc'],
+  ];
+  for (const [from, to] of dotfiles) {
+    const src = join(targetDir, from);
+    if (existsSync(src)) renameSync(src, join(targetDir, to));
+  }
+
+  // 4 ─ stamp the project name into package.json ───────────────────────
+  const pkgPath = join(targetDir, 'package.json');
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+  pkg.name = projectName;
+  writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+
+  // 5 ─ celebrate + print next steps ───────────────────────────────────
+  const rel = relative(process.cwd(), targetDir) || '.';
+  stdout.write(`\n${c.green('✔')} Scaffolded ${c.bold(projectName)} in ${c.cyan(rel)}\n\n`);
+  stdout.write(`${c.bold('Next steps:')}\n`);
+  if (rel !== '.') stdout.write(`  ${c.dim('1.')} cd ${rel}\n`);
+  stdout.write(`  ${c.dim(rel !== '.' ? '2.' : '1.')} npm install\n`);
+  stdout.write(`  ${c.dim(rel !== '.' ? '3.' : '2.')} npm run dev\n\n`);
+  stdout.write(`${BOLT} Then open the dev server and edit ${c.cyan('public/components/welcome.html')}.\n\n`);
+}
+
+main().catch((err) => bail(err?.message || String(err)));

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "create-spark-html-app",
+  "version": "0.3.2",
+  "description": "Scaffold a Vite + spark-html app with a live reactive welcome screen.",
+  "type": "module",
+  "bin": {
+    "create-spark-html-app": "bin/index.js"
+  },
+  "files": [
+    "bin",
+    "template"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wilkinnovo/spark.git",
+    "directory": "packages/create-spark-html-app"
+  },
+  "keywords": [
+    "spark",
+    "spark-html",
+    "create",
+    "scaffold",
+    "cli",
+    "vite",
+    "reactive",
+    "html",
+    "no-build"
+  ],
+  "license": "MIT"
+}

package/template/README.md

@@ -0,0 +1,41 @@
+# ⚡ Spark App
+
+A starter built with [spark-html](https://github.com/wilkinnovo/spark) — single-file
+HTML components with built-in reactivity. No compiler, no virtual DOM, no build step.
+
+## Develop
+
+```bash
+npm install
+npm run dev
+```
+
+Open the dev server and edit `public/components/welcome.html`. Save, and the
+page reloads instantly.
+
+## Build
+
+```bash
+npm run build     # static output → dist/, serve anywhere
+npm run preview   # preview the production build locally
+```
+
+## How it's wired
+
+```
+.
+├── index.html              ← <div import="components/app"> + boot script
+├── src/main.js             ← mount() + a shared store
+├── public/components/      ← your components (plain .html files)
+│   ├── app.html            ← theme + shell
+│   └── welcome.html        ← the live reactive welcome screen
+└── vite.config.js          ← spark-html/vite plugin
+```
+
+A component is a `.html` file with optional `<script>` and `<style>`. Top-level
+variables are reactive state — assigning to one re-patches that component's DOM.
+Derive values with `$:`, share state across components with `useStore(name)`,
+and pass props as attributes on the `import` placeholder.
+
+See the [full docs](https://github.com/wilkinnovo/spark#readme) for the
+complete template syntax reference.

package/template/_gitignore

@@ -0,0 +1,5 @@
+node_modules
+dist
+*.local
+.DS_Store
+.vite

package/template/index.html

@@ -0,0 +1,18 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Spark App</title>
+    <link
+      rel="icon"
+      href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 100 100'><text y='.9em' font-size='90'>⚡</text></svg>"
+    />
+  </head>
+  <body>
+    <!-- Each placeholder is replaced by the component file it names. -->
+    <div import="components/app"></div>
+
+    <script type="module" src="/src/main.js"></script>
+  </body>
+</html>

package/template/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "spark-app",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "spark-html": "^0.12.0"
+  },
+  "devDependencies": {
+    "vite": "^5.0.0"
+  }
+}

package/template/public/components/app.html

@@ -0,0 +1,41 @@
+<div import="components/welcome"></div>
+
+<style>
+  /* Resets and page-level rules use :global to escape component scoping. */
+  :global(*),
+  :global(*::before),
+  :global(*::after) {
+    box-sizing: border-box;
+    margin: 0;
+    padding: 0;
+  }
+  :global(:root) {
+    --bg: #0c0c11;
+    --surface: #14141c;
+    --surface-2: #1b1b26;
+    --border: #26263a;
+    --text: #e8e6f0;
+    --muted: #8b89a0;
+    --accent: #8b7cff;
+    --accent-dim: #2a2545;
+    --spark: #ffd24a;
+    --radius: 14px;
+    --mono: ui-monospace, "SF Mono", "Cascadia Code", Menlo, Consolas, monospace;
+  }
+  :global(body) {
+    min-height: 100vh;
+    font-family: system-ui, -apple-system, "Segoe UI", sans-serif;
+    color: var(--text);
+    line-height: 1.6;
+    background:
+      radial-gradient(ellipse 70% 50% at 50% -10%, rgba(139, 124, 255, 0.16), transparent),
+      linear-gradient(rgba(139, 124, 255, 0.035) 1px, transparent 1px),
+      linear-gradient(90deg, rgba(139, 124, 255, 0.035) 1px, transparent 1px),
+      var(--bg);
+    background-size: 100% 100%, 44px 44px, 44px 44px, 100% 100%;
+  }
+  :global(::selection) {
+    background: var(--accent);
+    color: #0c0c11;
+  }
+</style>

package/template/public/components/welcome.html

@@ -0,0 +1,201 @@
+<main class="wrap">
+  <header class="hero">
+    <div class="bolt" onclick={ignite} :class="igniting ? 'bolt lit' : 'bolt'" title="Click me">⚡</div>
+
+    <h1>Welcome to <span class="grad">Spark</span></h1>
+    <p class="tagline">
+      Single-file HTML components with built-in reactivity.
+      No compiler, no virtual DOM, no build step.
+    </p>
+
+    <div class="badges">
+      <span class="badge">spark-html</span>
+      <span class="badge">+ vite</span>
+      <span class="badge ready">⚡ ready</span>
+    </div>
+  </header>
+
+  <!-- Live proof that reactivity works the moment you load the page. -->
+  <section class="demo">
+    <p class="demo-label">This counter is live — state is just a variable</p>
+
+    <div class="counter">
+      <button class="round" onclick={dec} :disabled="count <= 0" aria-label="decrement">–</button>
+      <div class="readout">
+        <span class="num">{count}</span>
+        <span class="doubled">doubled is {doubled} · {mood}</span>
+      </div>
+      <button class="round plus" onclick={inc} aria-label="increment">+</button>
+    </div>
+
+    <p class="store-line">
+      You've struck the bolt <strong>{app.sparks}</strong>
+      time{app.sparks === 1 ? '' : 's'} — that value lives in a shared store.
+    </p>
+  </section>
+
+  <!-- Next steps -->
+  <section class="next">
+    <template each="card in cards">
+      <a class="card" href="{card.href}" target="_blank" rel="noopener">
+        <span class="card-ico">{card.ico}</span>
+        <span class="card-title">{card.title}</span>
+        <span class="card-body">{card.body}</span>
+      </a>
+    </template>
+  </section>
+
+  <footer class="foot">
+    Edit <code>public/components/welcome.html</code> and save — the page reloads instantly.
+  </footer>
+</main>
+
+<script>
+  // ── local reactive state — assign to re-patch the DOM ──────────────
+  let count = 0;
+  let igniting = false;
+
+  // ── derived values — re-run automatically on change ────────────────
+  $: doubled = count * 2;
+  $: mood = count === 0 ? 'a calm start' : count < 5 ? 'warming up' : 'on fire';
+
+  // ── shared store, seeded in main.js ────────────────────────────────
+  const app = useStore('app');
+
+  function inc() { count = count + 1; }
+  function dec() { count = Math.max(0, count - 1); }
+
+  function ignite() {
+    app.sparks = app.sparks + 1;   // updates every subscriber
+    igniting = true;
+    setTimeout(() => { igniting = false; }, 450);
+  }
+
+  const cards = [
+    { ico: '📖', title: 'Documentation', body: 'Template syntax, props, stores & the API.',
+      href: 'https://github.com/wilkinnovo/spark#readme' },
+    { ico: '🧩', title: 'Components', body: 'Plain .html files in public/components.',
+      href: 'https://github.com/wilkinnovo/spark' },
+    { ico: '⚡', title: 'How it works', body: 'No virtual DOM — assignments patch the real one.',
+      href: 'https://github.com/wilkinnovo/spark#readme' },
+  ];
+</script>
+
+<style>
+  .wrap {
+    max-width: 720px;
+    margin: 0 auto;
+    padding: 88px 24px 64px;
+    display: flex;
+    flex-direction: column;
+    gap: 44px;
+  }
+
+  /* hero */
+  .hero { text-align: center; display: flex; flex-direction: column; align-items: center; gap: 18px; }
+  .bolt {
+    font-size: 72px;
+    line-height: 1;
+    cursor: pointer;
+    user-select: none;
+    filter: drop-shadow(0 0 22px rgba(255, 210, 74, 0.45));
+    transition: transform 0.25s ease, filter 0.25s ease;
+  }
+  .bolt:hover { transform: translateY(-2px) scale(1.04); }
+  .bolt.lit { animation: zap 0.45s ease; }
+  @keyframes zap {
+    0%   { transform: scale(1); filter: drop-shadow(0 0 22px rgba(255, 210, 74, 0.45)); }
+    40%  { transform: scale(1.3) rotate(-8deg); filter: drop-shadow(0 0 40px rgba(255, 210, 74, 0.95)); }
+    100% { transform: scale(1); filter: drop-shadow(0 0 22px rgba(255, 210, 74, 0.45)); }
+  }
+  h1 { font-size: clamp(34px, 7vw, 52px); font-weight: 800; letter-spacing: -0.02em; }
+  .grad {
+    background: linear-gradient(110deg, var(--accent), var(--spark));
+    -webkit-background-clip: text;
+    background-clip: text;
+    color: transparent;
+  }
+  .tagline { max-width: 460px; color: var(--muted); font-size: 16px; }
+  .badges { display: flex; gap: 8px; flex-wrap: wrap; justify-content: center; }
+  .badge {
+    font-family: var(--mono);
+    font-size: 12px;
+    padding: 4px 11px;
+    border-radius: 999px;
+    border: 1px solid var(--border);
+    background: var(--surface);
+    color: var(--muted);
+  }
+  .badge.ready { color: var(--spark); border-color: rgba(255, 210, 74, 0.4); }
+
+  /* demo */
+  .demo {
+    background: var(--surface);
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    padding: 26px;
+    text-align: center;
+  }
+  .demo-label {
+    font-family: var(--mono);
+    font-size: 11px;
+    text-transform: uppercase;
+    letter-spacing: 0.14em;
+    color: var(--muted);
+    margin-bottom: 18px;
+  }
+  .counter { display: flex; align-items: center; justify-content: center; gap: 22px; }
+  .round {
+    width: 46px; height: 46px;
+    border-radius: 50%;
+    border: 1px solid var(--border);
+    background: var(--surface-2);
+    color: var(--text);
+    font-size: 22px;
+    cursor: pointer;
+    transition: border-color 0.15s, transform 0.1s;
+  }
+  .round:hover:not(:disabled) { border-color: var(--accent); }
+  .round:active:not(:disabled) { transform: scale(0.93); }
+  .round:disabled { opacity: 0.35; cursor: not-allowed; }
+  .round.plus { background: var(--accent-dim); border-color: var(--accent); color: var(--accent); }
+  .readout { min-width: 120px; }
+  .num { display: block; font-size: 46px; font-weight: 800; font-variant-numeric: tabular-nums; }
+  .doubled { font-size: 12px; color: var(--muted); font-family: var(--mono); }
+  .store-line { margin-top: 20px; font-size: 14px; color: var(--muted); }
+  .store-line strong { color: var(--spark); }
+
+  /* next steps */
+  .next { display: grid; grid-template-columns: repeat(3, 1fr); gap: 12px; }
+  .card {
+    display: flex;
+    flex-direction: column;
+    gap: 6px;
+    padding: 18px;
+    border-radius: var(--radius);
+    border: 1px solid var(--border);
+    background: var(--surface);
+    text-decoration: none;
+    color: var(--text);
+    transition: border-color 0.15s, transform 0.15s;
+  }
+  .card:hover { border-color: var(--accent); transform: translateY(-2px); }
+  .card-ico { font-size: 22px; }
+  .card-title { font-weight: 700; font-size: 14px; }
+  .card-body { font-size: 12.5px; color: var(--muted); line-height: 1.5; }
+
+  .foot { text-align: center; font-size: 13px; color: var(--muted); }
+  .foot code {
+    font-family: var(--mono);
+    background: var(--surface);
+    border: 1px solid var(--border);
+    border-radius: 6px;
+    padding: 2px 7px;
+    color: var(--accent);
+  }
+
+  @media (max-width: 560px) {
+    .next { grid-template-columns: 1fr; }
+    .wrap { padding-top: 56px; }
+  }
+</style>

package/template/src/main.js

@@ -0,0 +1,8 @@
+import { mount, store } from 'spark-html';
+
+// Shared, reactive state. Any component can subscribe with useStore('app').
+// Assigning a property re-patches every subscriber — that's the whole model.
+store('app', { sparks: 0 });
+
+// Resolve every <div import="..."> placeholder and boot the components.
+mount();

package/template/vite.config.js

@@ -0,0 +1,10 @@
+import { defineConfig } from 'vite';
+import spark from 'spark-html/vite';
+
+// Spark needs no build step — Vite is just a convenient dev server and
+// bundler. The plugin serves component fragments raw and full-reloads
+// when one changes. Components live in public/ so they ship verbatim to
+// the production build too.
+export default defineConfig({
+  plugins: [spark()],
+});