npm - create-spark-html-app - Versions diffs - 0.10.0 → 0.11.0 - Mend

create-spark-html-app 0.10.0 → 0.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (16) hide show

package/package.json +1 -1
package/template-ssr/README.md +33 -17
package/template-ssr/components/todo-list.html +6 -1
package/template-ssr/package.json +2 -1
package/template-ssr/pages/_layout.html +14 -0
package/template-ssr/pages/about.html +2 -7
package/template-ssr/pages/admin/index.html +20 -25
package/template-ssr/pages/blog/[slug].html +4 -8
package/template-ssr/pages/index.html +4 -9
package/template-ssr/pages/login.html +19 -0
package/template-ssr/seed/posts.json +38 -0
package/template-ssr/seed/todos.json +5 -0
package/template-ssr/seed/users.json +8 -0
package/template-ssr/components/login-form.html +0 -38
package/template-ssr/components/logout-button.html +0 -8
package/template-ssr/setup.js +0 -76

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "create-spark-html-app",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Scaffold a spark-html app — dev/build/preview on Bun",
   "type": "module",
   "bin": {

package/template-ssr/README.md CHANGED Viewed

@@ -2,55 +2,71 @@
 A complete blog: public posts with SEO titles/meta, dynamic routes, an
 about page, and an auth-gated admin panel where the author manages posts —
-and a private todo list. All of it is a handful of `.html` files, one SQLite
-database, and **zero build steps**.
+and a live-updating private todo list. All of it is a handful of `.html`
+files and one SQLite database. **No build step. No setup script. No fetch
+calls for the basics.**
 ## Run it
 ```bash
 bun install
-bun run dev     # seeds dev.db, serves on :3000, live-reloads on every edit
+bun run dev     # creates + seeds the DB from the templates, serves on :3000
 ```
-Sign in at [/admin](http://localhost:3000/admin) with
-**me@spark-html.com** / **spark**.
+Sign in at [/login](http://localhost:3000/login) with
+**me@spark-html.com** / **spark** — a plain form; it works with JavaScript
+disabled.
 ## What's demonstrated where
 | Feature | Where |
 |---|---|
+| Layouts | `pages/_layout.html` — nav, styles, `app.js` and the `author` query, once for every page |
 | Filesystem routing | `pages/index.html` → `/`, `pages/about.html` → `/about` |
 | Dynamic routes | `pages/blog/[slug].html` → `/blog/:slug` — `:slug` binds into the SQL |
-| Per-page `<title>`/`<meta>` | literal tags at the top of each page, `{expr}`-interpolated (spark-html-head/ssr) |
-| Declarative data | `<spark-ssr>` blocks — the query names feed the template variables |
+| Named page data | `posts = SELECT …` — the variable is named in the block, no endpoint exposed |
+| Real 404s | `<template else status="404">` on the missing-post branch |
+| Guards | `/admin`: `<spark-ssr guard="session" redirect="/login" />` — one line |
+| No-JS forms | `pages/login.html` and the logout button — plain forms, 303 back |
+| Form validation | the login form's `required`/`type="email"` run server-side too |
+| The template is the schema | `seed/*.json` + `<spark-ssr table="…" seed="…">` — tables created and seeded at startup; `bun run db` shows the diff |
+| Live updates | `<spark-ssr table="todos" … live />` — open /admin in two tabs |
+| Per-page `<title>`/`<meta>` | literal tags at the top of each page, `{expr}`-interpolated |
+| SEO | og:title/og:description derive from the head; `/sitemap.xml` enumerates `/blog/:slug` from its query; `/robots.txt` honors the admin page's `noindex` |
 | Server → component props | `index.html` passes each whole `post` row into `post-card.html` |
-| Pure-UI components | `nav.html`, `post-card.html` — no `<script>`, props are the scope |
-| Client components | `login-form`, `post-editor`, `todo-list` — their `<script>` runs in the browser |
+| Client components | `post-editor`, `todo-list` — their `<script>` runs in the browser |
 | Auth | `spark.json` `"auth"` → sessions, `POST /api/users?auth` login, hashed passwords |
 | Auth-scoped CRUD | `posts` and `todos` carry `user_id` → their APIs are session-scoped (401 anonymous) |
 | Draft privacy | the `[slug]` query: `published = 1 OR :session.id IS NOT NULL` — authors preview drafts |
 | Middleware | `middleware.html` disables public signups (single-author blog) |
 | Aggregates | `about.html`'s `COUNT(*)` serves an object → `{stats.n}` |
-| Custom error page | `404.html` |
 | Dark/light theme | spark-html-theme — `app.js` one-liner + `theme-toggle.html`; no-flash init is auto-inlined |
-| Fonts | spark.json `"fonts"` → spark-html-font tags in every `<head>` (preload, no-shift fallback) |
-| Images | `bun run build` runs spark-html-image over `dist/` — webp + srcset for every `<img>` |
+| Fonts | spark.json `"fonts"` → spark-html-font tags in every `<head>` |
+| Images | `bun run build` runs spark-html-image over `dist/` — webp + srcset |
 ## The mental model
+- `pages/_layout.html` wraps every page in the folder; `<slot>` is the page.
+  Its `<spark-ssr>` vars are in scope everywhere it wraps.
 - A **page**'s plain `<script>` runs on the **server** (it's the escape
   hatch); `<script type="module">`/`src` scripts ship to the browser.
 - A **component**'s `<script>` runs in the **browser**. Components are
   otherwise pure UI: they render the props they're given.
-- `<spark-ssr>` declares data. A `table="…"` gives you scoped REST CRUD;
-  a `GET /api/x → SELECT …` line is both an endpoint and page data.
-- Everything hot-reloads — pages, components, queries, middleware — no
-  restart, the browser refreshes itself.
+- `<spark-ssr>` declares data. `var = SELECT …` names page data;
+  `table="…"` gives you scoped REST CRUD (+ `seed`, `live`, `limit`,
+  `search`); `guard="…"` protects the page.
+- Plain forms to `/api/*` work without JavaScript — success 303s back,
+  the markup's constraint attributes validate on the server.
+- Everything hot-reloads — pages, layouts, components, queries, middleware
+  — and dev errors land on the page, not in a bare 500. Open
+  [/__spark/plan](http://localhost:3000/__spark/plan) to see the inferred
+  backend.
 ## Deploy
 ```bash
-bun run build   # dist/ + compiled binary; images optimized if sharp installs
+bun run build            # dist/ + compiled binary; images optimized
+bun spark-ssr build --docker   # …plus a Dockerfile
 PORT=3000 ./dist/app
 ```

package/template-ssr/components/todo-list.html CHANGED Viewed

@@ -1,6 +1,8 @@
 <!-- The author's private todos. Same auto-CRUD pattern as posts — the
      user_id column scopes every row to the session, so nobody else can
-     read or touch them (try /api/todos signed out: 401). -->
+     read or touch them (try /api/todos signed out: 401). The todos block
+     declares `live`, so writes ping /__spark/live: the two lines at the
+     bottom keep every open tab (or the author's phone) in sync. -->
 <section class="panel">
   <h2>Private todos</h2>
   <div class="row">
@@ -48,4 +50,7 @@
   }
   refresh();
+  const es = new EventSource('/__spark/live');
+  es.onmessage = (e) => { if (e.data === 'todos') refresh(); };
 </script>

package/template-ssr/package.json CHANGED Viewed

@@ -4,7 +4,8 @@
   "version": "0.0.0",
   "type": "module",
   "scripts": {
-    "dev": "bun setup.js && bun spark-ssr",
+    "dev": "bun spark-ssr",
+    "db": "bun spark-ssr db",
     "start": "bun spark-ssr start",
     "build": "bun spark-ssr build"
   },

package/template-ssr/pages/_layout.html ADDED Viewed

@@ -0,0 +1,14 @@
+<!-- The layout: every page in pages/ renders inside it — <slot> is the page.
+     Its <spark-ssr> vars (author) are in scope for every page it wraps, and
+     its head tags lift into <head> too (a page's own tags win on conflict).
+     The three lines every page used to repeat live here, once. -->
+<link rel="stylesheet" href="/style.css">
+<script type="module" src="/app.js"></script>
+<div import="/components/nav" blog="{author.name}"></div>
+<slot></slot>
+<spark-ssr>
+  author = SELECT id, name, email, bio FROM users LIMIT 1
+</spark-ssr>

package/template-ssr/pages/about.html CHANGED Viewed

@@ -1,11 +1,7 @@
-<!-- /about — profile straight from the users table, plus an aggregate:
+<!-- /about — {author} comes from the layout; this page adds one aggregate:
      a COUNT(*) query serves an object, so {stats.n} just works. -->
 <title>About {author.name}</title>
 <meta name="description" content="Who is {author.name} — {author.bio}">
-<link rel="stylesheet" href="/style.css">
-<script type="module" src="/app.js"></script>
-<div import="/components/nav" blog="{author.name}" active="about"></div>
 <article class="post">
   <img class="avatar" src="/img/avatar.png" alt="{author.name}" width="88" height="88">
@@ -17,6 +13,5 @@
 </article>
 <spark-ssr>
-  GET /api/author → SELECT id, name, email, bio FROM users LIMIT 1
-  GET /api/stats → SELECT COUNT(*) AS n FROM posts WHERE published = 1
+  stats = SELECT COUNT(*) AS n FROM posts WHERE published = 1
 </spark-ssr>

package/template-ssr/pages/admin/index.html CHANGED Viewed

@@ -1,30 +1,25 @@
-<!-- /admin — the author's private side. `session` is always in page scope:
-     signed out you get the login form, signed in the management panels.
-     The two table declarations give the components their scoped REST APIs
-     (posts + todos both carry user_id → session-scoped, 401 for anyone else). -->
+<!-- /admin — one guard line protects the whole page: signed out → 303 to
+     /login. The table blocks give the components their scoped REST APIs
+     (posts + todos carry user_id → session-scoped, 401 for anyone else);
+     the seed="…" files define AND fill the tables on first run — there is
+     no setup.js — and `live` keeps every open todos tab in sync. -->
 <title>Manage · {author.name}</title>
 <meta name="robots" content="noindex">
-<link rel="stylesheet" href="/style.css">
-<script type="module" src="/app.js"></script>
-<div import="/components/nav" blog="{author.name}" active="admin"></div>
+<spark-ssr guard="session" redirect="/login" />
-<template if="session">
-  <main class="admin">
-    <header class="admin-head">
-      <p>Signed in as <strong>{session.email}</strong></p>
-      <div import="/components/logout-button"></div>
-    </header>
-    <div import="/components/post-editor"></div>
-    <div import="/components/todo-list"></div>
-  </main>
-</template>
-<template else>
-  <div import="/components/login-form"></div>
-</template>
+<main class="admin">
+  <header class="admin-head">
+    <p>Signed in as <strong>{session.email}</strong></p>
+    <!-- Logout is a plain form too — works with JavaScript disabled. -->
+    <form action="/api/logout" method="post" redirect="/">
+      <button class="ghost">Sign out</button>
+    </form>
+  </header>
+  <div import="/components/post-editor"></div>
+  <div import="/components/todo-list"></div>
+</main>
-<spark-ssr table="posts" />
-<spark-ssr table="todos" />
-<spark-ssr>
-  GET /api/author → SELECT id, name, email, bio FROM users LIMIT 1
-</spark-ssr>
+<spark-ssr table="users" seed="./seed/users.json" />
+<spark-ssr table="posts" seed="./seed/posts.json" />
+<spark-ssr table="todos" seed="./seed/todos.json" live />

package/template-ssr/pages/blog/[slug].html CHANGED Viewed

@@ -1,12 +1,9 @@
 <!-- /blog/:slug — the filename IS the route; :slug binds into the query.
-     Drafts stay invisible to anonymous readers, but the signed-in author
+     A missing row is a REAL 404 (the status= on the rendered branch), and
+     drafts stay invisible to anonymous readers while the signed-in author
      gets a live preview (the OR :session.id clause). -->
 <title>{post ? post.title : 'Not found'} · {author.name}</title>
 <meta name="description" content="{post ? post.excerpt : 'This post does not exist.'}">
-<link rel="stylesheet" href="/style.css">
-<script type="module" src="/app.js"></script>
-<div import="/components/nav" blog="{author.name}"></div>
 <template if="post">
   <article class="post">
@@ -19,7 +16,7 @@
     <div class="body">{post.body}</div>
   </article>
 </template>
-<template else>
+<template else status="404">
   <article class="post">
     <h1>Not found</h1>
     <p>That post doesn't exist — or it's a draft and you're not signed in.</p>
@@ -28,8 +25,7 @@
 </template>
 <spark-ssr>
-  GET /api/author → SELECT id, name, email, bio FROM users LIMIT 1
-  GET /api/blog/[slug] → SELECT * FROM posts
+  post = SELECT * FROM posts
     WHERE slug = :slug AND (published = 1 OR :session.id IS NOT NULL)
     LIMIT 1
 </spark-ssr>

package/template-ssr/pages/index.html CHANGED Viewed

@@ -1,12 +1,8 @@
-<!-- The homepage. Everything the page needs is declared at the bottom in
-     <spark-ssr>; the title/meta lift into <head> (spark-html-head/ssr);
-     app.js is a client module (theme toggle). -->
+<!-- The homepage. The layout owns the chrome and provides {author}; this
+     page declares only what's unique to it. `posts = SELECT …` is page data
+     with NO public endpoint — name the variable, skip the route. -->
 <title>{author.name} — a spark blog</title>
 <meta name="description" content="{author.bio}">
-<link rel="stylesheet" href="/style.css">
-<script type="module" src="/app.js"></script>
-<div import="/components/nav" blog="{author.name}" active="home"></div>
 <header class="hero">
   <img class="avatar" src="/img/avatar.png" alt="{author.name}" width="88" height="88">
@@ -28,6 +24,5 @@
 </main>
 <spark-ssr>
-  GET /api/author → SELECT id, name, email, bio FROM users LIMIT 1
-  GET /api/published → SELECT * FROM posts WHERE published = 1 ORDER BY created_at DESC
+  posts = SELECT * FROM posts WHERE published = 1 ORDER BY created_at DESC
 </spark-ssr>

package/template-ssr/pages/login.html ADDED Viewed

@@ -0,0 +1,19 @@
+<!-- Sign in with a PLAIN FORM — no JavaScript required. The server answers
+     a browser like a browser: success 303s to redirect="/admin"; a wrong
+     password re-renders this page with {errors} in scope. The `required`
+     attributes are enforced server-side too — the form is the validator. -->
+<title>Sign in · {author.name}</title>
+<meta name="robots" content="noindex">
+<form class="panel login" action="/api/users?auth" method="post" redirect="/admin">
+  <h2>Author sign-in</h2>
+  <label>Email
+    <input type="email" name="email" autocomplete="username" required>
+  </label>
+  <label>Password
+    <input type="password" name="password" autocomplete="current-password" required>
+  </label>
+  <button>Sign in</button>
+  <template if="errors"><p class="error">Wrong email or password.</p></template>
+  <p class="hint">Seeded account: me@spark-html.com / spark</p>
+</form>

package/template-ssr/seed/posts.json ADDED Viewed

@@ -0,0 +1,38 @@
+[
+  {
+    "user_id": 1,
+    "slug": "hello-spark",
+    "title": "Hello, Spark",
+    "excerpt": "Why this blog runs on HTML that infers its own backend.",
+    "body": "This site is a handful of .html files and one SQLite database.\n\nEach page declares the data it needs in a <spark-ssr> block, and the server infers the rest: routes from filenames, APIs from SQL, auth from a user_id column — even these tables and rows came from seed files the templates point at.\n\nView source on any page — what you see is what I wrote.",
+    "published": 1,
+    "created_at": "2026-06-21"
+  },
+  {
+    "user_id": 1,
+    "slug": "html-that-reacts",
+    "title": "HTML that reacts",
+    "excerpt": "Templates, loops and conditionals — in plain HTML attributes.",
+    "body": "A <template each=\"post in posts\"> renders a list. A <template if> branches. {curly} braces interpolate.\n\nOn the server they render to static HTML; in the browser the same syntax comes alive as components. One mental model, both sides of the wire.",
+    "published": 1,
+    "created_at": "2026-06-27"
+  },
+  {
+    "user_id": 1,
+    "slug": "zero-config-ssr",
+    "title": "Zero-config SSR",
+    "excerpt": "Filesystem routing, layouts, sessions, live updates — from the template.",
+    "body": "pages/blog/[slug].html serves /blog/:slug, and :slug binds straight into the page query. pages/_layout.html wraps every page — nav, styles, footer, once.\n\nDeclare <spark-ssr table=\"todos\" live /> and the REST endpoints exist, the table is created from the template, and every open tab stays in sync. Delete the file and it all goes away.",
+    "published": 1,
+    "created_at": "2026-07-02"
+  },
+  {
+    "user_id": 1,
+    "slug": "drafts-are-private",
+    "title": "Drafts are private",
+    "excerpt": "This post is unpublished — only the signed-in author sees it.",
+    "body": "The page query keeps drafts out of anonymous requests:\n\nWHERE slug = :slug AND (published = 1 OR :session.id IS NOT NULL)\n\nAnd a missing row is a REAL 404 now — <template else status=\"404\"> sets the response status, so crawlers never index an empty page. Sign in at /admin and this post appears.",
+    "published": 0,
+    "created_at": "2026-07-04"
+  }
+]

package/template-ssr/seed/todos.json ADDED Viewed

@@ -0,0 +1,5 @@
+[
+  { "user_id": 1, "title": "Finish the drafts post", "done": 1 },
+  { "user_id": 1, "title": "Write about companion packages", "done": 0 },
+  { "user_id": 1, "title": "Reply to reader mail", "done": 0 }
+]

package/template-ssr/seed/users.json ADDED Viewed

@@ -0,0 +1,8 @@
+[
+  {
+    "email": "me@spark-html.com",
+    "password": "spark",
+    "name": "Ada Spark",
+    "bio": "I write HTML that reacts. No compiler, no virtual DOM, no build step — just the platform, with a spark."
+  }
+]

package/template-ssr/components/login-form.html DELETED Viewed

@@ -1,38 +0,0 @@
-<!-- A component <script> runs in the BROWSER (pages' plain <script> runs on
-     the server — that's the split). POST /api/users?auth is the login
-     endpoint spark-ssr derives from the auth config. -->
-<form class="panel login" onsubmit={login}>
-  <h2>Author sign-in</h2>
-  <label>Email
-    <input type="email" bind:value="email" autocomplete="username" required>
-  </label>
-  <label>Password
-    <input type="password" bind:value="password" autocomplete="current-password" required>
-  </label>
-  <button :disabled="pending">{pending ? 'Signing in…' : 'Sign in'}</button>
-  <template if="error"><p class="error">{error}</p></template>
-  <p class="hint">Seeded account: me@spark-html.com / spark</p>
-</form>
-<script>
-  let email = '';
-  let password = '';
-  let error = '';
-  let pending = false;
-  async function login() {
-    pending = true;
-    error = '';
-    const res = await fetch('/api/users?auth', {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({ email, password }),
-    });
-    if (res.ok) {
-      location.reload();
-    } else {
-      error = 'Wrong email or password.';
-      pending = false;
-    }
-  }
-</script>

package/template-ssr/components/logout-button.html DELETED Viewed

@@ -1,8 +0,0 @@
-<button class="ghost" onclick={logout}>Sign out</button>
-<script>
-  async function logout() {
-    await fetch('/api/logout', { method: 'POST' });
-    location.href = '/';
-  }
-</script>

package/template-ssr/setup.js DELETED Viewed

@@ -1,76 +0,0 @@
-// One-time (idempotent) dev database setup — `bun run dev` runs it for you.
-// Swap spark.json's db to postgres:// any time; no code changes needed.
-import { Database } from 'bun:sqlite';
-const db = new Database('./dev.db', { create: true });
-db.run(`CREATE TABLE IF NOT EXISTS users (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  email TEXT NOT NULL UNIQUE,
-  password TEXT NOT NULL,
-  name TEXT NOT NULL,
-  bio TEXT DEFAULT ''
-)`);
-db.run(`CREATE TABLE IF NOT EXISTS posts (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  user_id INTEGER NOT NULL,
-  slug TEXT NOT NULL UNIQUE,
-  title TEXT NOT NULL,
-  excerpt TEXT DEFAULT '',
-  body TEXT DEFAULT '',
-  published INTEGER DEFAULT 0,
-  created_at TEXT DEFAULT (date('now'))
-)`);
-db.run(`CREATE TABLE IF NOT EXISTS todos (
-  id INTEGER PRIMARY KEY AUTOINCREMENT,
-  user_id INTEGER NOT NULL,
-  title TEXT NOT NULL,
-  done INTEGER DEFAULT 0
-)`);
-if (db.query('SELECT COUNT(*) AS n FROM users').get().n === 0) {
-  // The author account — sign in at /admin to manage the blog.
-  const hash = await Bun.password.hash('spark');
-  db.run('INSERT INTO users (email, password, name, bio) VALUES (?, ?, ?, ?)', [
-    'me@spark-html.com',
-    hash,
-    'Ada Spark',
-    'I write HTML that reacts. No compiler, no virtual DOM, no build step — just the platform, with a spark.',
-  ]);
-  const posts = [
-    ['hello-spark', 'Hello, Spark',
-      'Why this blog runs on HTML that infers its own backend.',
-      'This site is a handful of .html files and one SQLite database.\n\nEach page declares the data it needs in a <spark-ssr> block, and the server infers the rest: routes from filenames, APIs from SQL, auth from a user_id column.\n\nView source on any page — what you see is what I wrote.',
-      1, '2026-06-21'],
-    ['html-that-reacts', 'HTML that reacts',
-      'Templates, loops and conditionals — in plain HTML attributes.',
-      'A <template each="post in posts"> renders a list. A <template if> branches. {curly} braces interpolate.\n\nOn the server they render to static HTML; in the browser the same syntax comes alive as components. One mental model, both sides of the wire.',
-      1, '2026-06-27'],
-    ['zero-config-ssr', 'Zero-config SSR',
-      'Filesystem routing, sessions, uploads and CRUD — from the template.',
-      'pages/blog/[slug].html serves /blog/:slug, and :slug binds straight into the page query.\n\nDeclare <spark-ssr table="todos"> and the REST endpoints exist. Add a user_id column and they are scoped to the signed-in user. Delete the file and it all goes away.',
-      1, '2026-07-02'],
-    ['drafts-are-private', 'Drafts are private',
-      'This post is unpublished — only the signed-in author sees it.',
-      'The page query keeps drafts out of anonymous requests:\n\nWHERE slug = :slug AND (published = 1 OR :session.id IS NOT NULL)\n\nSign in at /admin and this post appears on the homepage preview and here. Publish it from the admin panel when it is ready.',
-      0, '2026-07-04'],
-  ];
-  for (const [slug, title, excerpt, body, published, at] of posts) {
-    db.run(
-      'INSERT INTO posts (user_id, slug, title, excerpt, body, published, created_at) VALUES (1, ?, ?, ?, ?, ?, ?)',
-      [slug, title, excerpt, body, published, at],
-    );
-  }
-  db.run(`INSERT INTO todos (user_id, title, done) VALUES
-    (1, 'Finish the drafts post', 1),
-    (1, 'Write about companion packages', 0),
-    (1, 'Reply to reader mail', 0)`);
-  console.log('⚡ seeded dev.db — sign in at /admin with me@spark-html.com / spark');
-}
-db.close();