create-koppajs 1.0.1 → 1.2.0

package/template/prettier.config.mjs

@@ -0,0 +1,6 @@
+export default {
+  semi: true,
+  singleQuote: false,
+  tabWidth: 2,
+  trailingComma: "all",
+};

package/template/src/app-view.kpa

@@ -1,36 +1,35 @@
-[template]
-  <div class="app-root">
-    <img src="https://public-assets-1b57ca06-687a-4142-a525-0635f7649a5c.s3.eu-central-1.amazonaws.com/koppajs/koppajs-logo-text-900x226.png" width="420" alt="KoppaJS Logo" class="logo">
-    <p class="subtitle">Minimal Starter</p>
-    <counter-component></counter-component>
-  </div>
-[/template]
-
-[css]
-  .app-root {
-    display: flex;
-    flex-direction: column;
-    align-items: center;
-    justify-content: center;
-    min-height: 100vh;
-    background: #0f1117;
-    font-family: system-ui, -apple-system, sans-serif;
-    padding: 2rem;
-  }
-
-  .logo {
-    margin-bottom: .9rem;
-  }
-  
-  .subtitle {
-    color: #64dce8;
-    font-size: 1rem;
-    letter-spacing: 0.25em;
-    text-transform: uppercase;
-    margin: 0 0 1.5rem 0;
-    opacity: 0.8;
-  }
-[/css]
-
-
-
+[template]
+  <div class="app-root">
+    <img src="https://public-assets-1b57ca06-687a-4142-a525-0635f7649a5c.s3.eu-central-1.amazonaws.com/koppajs/koppajs-logo-text-900x226.png" width="420" alt="KoppaJS Logo" class="logo">
+    <p class="subtitle">Minimal Starter</p>
+    <counter-component></counter-component>
+  </div>
+[/template]
+
+[css]
+  .app-root {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    min-height: 100vh;
+    background: #0f1117;
+    font-family: system-ui, -apple-system, sans-serif;
+    padding: 2rem;
+  }
+
+  .logo {
+    margin-bottom: .9rem;
+  }
+
+  .subtitle {
+    color: #64dce8;
+    font-size: 1rem;
+    letter-spacing: 0.25em;
+    text-transform: uppercase;
+    margin: 0 0 1.5rem 0;
+    opacity: 0.8;
+  }
+[/css]
+
+

package/template/src/counter-component.kpa

@@ -1,87 +1,87 @@
-[template]
-  <div class="counter-card">
-    <span class="counter-label">Counter</span>
-    <p class="counter-value">{{ count }}</p>
-    <div class="counter-buttons">
-      <button onClick="decrement">−</button>
-      <button onClick="increment">+</button>
-    </div>
-  </div>
-[/template]
-
-[ts]
-  return {
-    state: { count: 0 },
-    methods: {
-      increment() {
-        this.count++;
-      },
-      decrement() {
-        this.count--;
-      },
-    },
-  };
-[/ts]
-
-[css]
-  .counter-card {
-    background: #1a1d2e;
-    border: 1px solid #2a2d3e;
-    border-radius: 1.2rem;
-    padding: 2.5rem 3rem;
-    display: flex;
-    flex-direction: column;
-    align-items: center;
-    gap: 1.2rem;
-    min-width: 260px;
-    box-shadow: 0 8px 32px rgba(0, 0, 0, 0.3), 0 0 48px rgba(100, 220, 232, 0.05);
-  }
-
-  .counter-label {
-    font-size: 0.85rem;
-    color: #64dce8;
-    text-transform: uppercase;
-    letter-spacing: 0.2em;
-    opacity: 0.7;
-  }
-
-  .counter-value {
-    font-size: 3rem;
-    font-weight: 700;
-    color: #e8eaf0;
-    margin: 0;
-    font-variant-numeric: tabular-nums;
-  }
-
-  .counter-buttons {
-    display: flex;
-    gap: 1rem;
-  }
-
-  button {
-    background: transparent;
-    color: #64dce8;
-    border: 1px solid #64dce8;
-    border-radius: 0.6rem;
-    padding: 0.6rem 1.5rem;
-    font-size: 1.3rem;
-    font-weight: 600;
-    cursor: pointer;
-    transition: background 0.35s cubic-bezier(0.4, 0, 0.2, 1),
-                color 0.35s cubic-bezier(0.4, 0, 0.2, 1),
-                transform 0.15s cubic-bezier(0.4, 0, 0.2, 1),
-                border-color 0.35s cubic-bezier(0.4, 0, 0.2, 1);
-  }
-
-  button:hover {
-    background: rgba(100, 220, 232, 0.12);
-    color: #8ff0f8;
-    border-color: #8ff0f8;
-  }
-  
-  button:active {
-    background: #64dce8;
-    color: #0f1117;
-    transform: scale(0.93);
-  }
-[/css]
+[template]
+  <div class="counter-card">
+    <span class="counter-label">Counter</span>
+    <p class="counter-value" role="status" aria-live="polite">{{ count }}</p>
+    <div class="counter-buttons">
+      <button type="button" aria-label="Decrement counter" onClick="decrement">−</button>
+      <button type="button" aria-label="Increment counter" onClick="increment">+</button>
+    </div>
+  </div>
+[/template]
+
+[ts]
+  return {
+    state: { count: 0 },
+    methods: {
+      increment() {
+        this.count++;
+      },
+      decrement() {
+        this.count--;
+      },
+    },
+  };
+[/ts]
+
+[css]
+  .counter-card {
+    background: #1a1d2e;
+    border: 1px solid #2a2d3e;
+    border-radius: 1.2rem;
+    padding: 2.5rem 3rem;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: 1.2rem;
+    min-width: 260px;
+    box-shadow: 0 8px 32px rgba(0, 0, 0, 0.3), 0 0 48px rgba(100, 220, 232, 0.05);
+  }
+
+  .counter-label {
+    font-size: 0.85rem;
+    color: #64dce8;
+    text-transform: uppercase;
+    letter-spacing: 0.2em;
+    opacity: 0.7;
+  }
+
+  .counter-value {
+    font-size: 3rem;
+    font-weight: 700;
+    color: #e8eaf0;
+    margin: 0;
+    font-variant-numeric: tabular-nums;
+  }
+
+  .counter-buttons {
+    display: flex;
+    gap: 1rem;
+  }
+
+  button {
+    background: transparent;
+    color: #64dce8;
+    border: 1px solid #64dce8;
+    border-radius: 0.6rem;
+    padding: 0.6rem 1.5rem;
+    font-size: 1.3rem;
+    font-weight: 600;
+    cursor: pointer;
+    transition: background 0.35s cubic-bezier(0.4, 0, 0.2, 1),
+                color 0.35s cubic-bezier(0.4, 0, 0.2, 1),
+                transform 0.15s cubic-bezier(0.4, 0, 0.2, 1),
+                border-color 0.35s cubic-bezier(0.4, 0, 0.2, 1);
+  }
+
+  button:hover {
+    background: rgba(100, 220, 232, 0.12);
+    color: #8ff0f8;
+    border-color: #8ff0f8;
+  }
+
+  button:active {
+    background: #64dce8;
+    color: #0f1117;
+    transform: scale(0.93);
+  }
+[/css]

package/template/src/style.css

@@ -1,5 +1,5 @@
-* {
-    box-sizing: border-box;
-    margin: 0;
-    padding: 0;
-}
+* {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}

package/template/tests/e2e/app.spec.ts

@@ -0,0 +1,18 @@
+import { expect, test } from "@playwright/test";
+
+test("renders the starter and updates the counter", async ({ page }) => {
+  await page.goto("/");
+
+  await expect(page.getByText("Minimal Starter")).toBeVisible();
+
+  const counterValue = page.getByRole("status");
+
+  await expect(counterValue).toHaveText("0");
+
+  await page.getByRole("button", { name: "Increment counter" }).click();
+  await expect(counterValue).toHaveText("1");
+
+  await page.getByRole("button", { name: "Decrement counter" }).click();
+  await page.getByRole("button", { name: "Decrement counter" }).click();
+  await expect(counterValue).toHaveText("-1");
+});

package/template/tests/integration/main-bootstrap.test.ts

@@ -0,0 +1,33 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const { core, take } = vi.hoisted(() => {
+  const take = vi.fn();
+  const core = Object.assign(vi.fn(), { take });
+
+  return { core, take };
+});
+
+vi.mock("@koppajs/koppajs-core", () => ({
+  Core: core,
+}));
+
+describe("main bootstrap", () => {
+  afterEach(() => {
+    core.mockClear();
+    take.mockClear();
+    vi.resetModules();
+  });
+
+  it("registers the root components and boots the app once", async () => {
+    await import("../../src/main");
+
+    expect(take).toHaveBeenCalledTimes(2);
+    expect(take).toHaveBeenNthCalledWith(1, expect.anything(), "app-view");
+    expect(take).toHaveBeenNthCalledWith(
+      2,
+      expect.anything(),
+      "counter-component",
+    );
+    expect(core).toHaveBeenCalledTimes(1);
+  });
+});

package/template/tests/unit/normalize-kpa-module-export.test.ts

@@ -0,0 +1,46 @@
+import type { Plugin } from "vite";
+import { describe, expect, it } from "vitest";
+
+import { normalizeKpaModuleExport } from "../../vite.config.mjs";
+
+async function transformWith(plugin: Plugin, code: string, id: string) {
+  const transform = plugin.transform;
+
+  if (!transform) {
+    return null;
+  }
+
+  if (typeof transform === "function") {
+    return transform.call({} as never, code, id);
+  }
+
+  return transform.handler.call({} as never, code, id);
+}
+
+describe("normalizeKpaModuleExport", () => {
+  it("wraps raw KPA output in an ES module export", async () => {
+    const plugin = normalizeKpaModuleExport();
+
+    await expect(
+      transformWith(plugin, '{ template: "<div></div>" }', "/src/app-view.kpa"),
+    ).resolves.toEqual({
+      code: 'export default { template: "<div></div>" };',
+      map: null,
+    });
+  });
+
+  it("ignores non-KPA files and already exported modules", async () => {
+    const plugin = normalizeKpaModuleExport();
+
+    await expect(
+      transformWith(plugin, "const count = 0;", "/src/main.ts"),
+    ).resolves.toBeNull();
+    await expect(
+      transformWith(
+        plugin,
+        "export default { template: '<div></div>' };",
+        "/src/app-view.kpa",
+      ),
+    ).resolves.toBeNull();
+  });
+});

package/template/tsconfig.json

@@ -10,6 +10,17 @@
     "forceConsistentCasingInFileNames": true,
     "noEmit": true
   },
-  "include": ["src/**/*.ts"],
-  "exclude": ["node_modules", "dist"]
+  "include": [
+    "src/**/*.ts",
+    "tests/**/*.ts",
+    "playwright.config.ts",
+    "vite.config.d.mts"
+  ],
+  "exclude": [
+    "coverage",
+    "dist",
+    "node_modules",
+    "playwright-report",
+    "test-results"
+  ]
 }

package/template/vite.config.d.mts

@@ -0,0 +1,7 @@
+import type { Plugin, UserConfig } from "vite";
+
+export declare function normalizeKpaModuleExport(): Plugin;
+
+declare const config: UserConfig;
+
+export default config;

package/template/vite.config.mjs

@@ -1,10 +1,45 @@
-import { defineConfig } from "vite";
 import koppaPlugin from "@koppajs/koppajs-vite-plugin";
+import { defineConfig } from "vite";
+
+/**
+ * Wrap raw `.kpa` object output in a valid ES module export.
+ *
+ * @returns {import("vite").Plugin}
+ */
+export function normalizeKpaModuleExport() {
+  return {
+    name: "normalize-kpa-module-export",
+    enforce: "post",
+    /**
+     * @param {string} code
+     * @param {string} id
+     */
+    transform(code, id) {
+      const cleanId = id.split("?")[0];
+
+      if (!cleanId.endsWith(".kpa")) {
+        return null;
+      }
+
+      const trimmed = code.trim();
+
+      if (!trimmed.startsWith("{") || trimmed.startsWith("export default")) {
+        return null;
+      }
+
+      return {
+        code: `export default ${trimmed};`,
+        map: null,
+      };
+    },
+  };
+}
 
 export default defineConfig({
   plugins: [
     koppaPlugin({
-      tsconfigFile: "./tsconfig.json"
-    })
-  ]
+      tsconfigFile: "./tsconfig.json",
+    }),
+    normalizeKpaModuleExport(),
+  ],
 });

package/template/vitest.config.mjs

@@ -0,0 +1,19 @@
+import { defineConfig, mergeConfig } from "vitest/config";
+
+import viteConfig from "./vite.config.mjs";
+
+export default mergeConfig(
+  viteConfig,
+  defineConfig({
+    test: {
+      include: ["tests/**/*.test.ts"],
+      coverage: {
+        provider: "v8",
+        reporter: ["text", "html"],
+        reportsDirectory: "./coverage",
+        include: ["src/**/*.ts"],
+        exclude: ["playwright.config.ts", "tests/**/*.ts", "vitest.config.mjs"],
+      },
+    },
+  }),
+);

package/template-overlays/router/ARCHITECTURE.md

@@ -0,0 +1,86 @@
+# Architecture
+
+This repository is a small KoppaJS router starter. It demonstrates a clear
+bootstrap path: HTML shell, TypeScript entrypoint, one root app shell
+component, one router instance, two primary routes, and one explicit not-found
+route. The repository also carries the same quality and release automation
+baseline as the minimal starter so the example remains production-like.
+
+## System overview
+
+- `index.html` provides the document shell, loads global CSS, declares the
+  `<app-view>` root element, and imports the TypeScript entrypoint.
+- `src/main.ts` registers local components with `Core.take(...)`, calls
+  `Core()` once, waits for the route outlet to exist, and initializes one
+  `KoppajsRouter` instance.
+- `src/app-view.kpa` is the root shell. It renders the hero area, the primary
+  navigation, and the `#app-outlet` container that receives route content.
+- `src/home-page.kpa` is the default route and composes `counter-component`.
+- `src/router-page.kpa` is the second route and explains the router wiring.
+- `src/not-found-page.kpa` is the explicit catch-all route.
+- `src/counter-component.kpa` remains the example local-state component.
+- `src/style.css` defines global tokens, base layout, and the background.
+- `tests/integration/` verifies bootstrap wiring and router startup.
+- `tests/e2e/` verifies the user-visible route flow and counter behavior.
+
+More detailed boundaries live in [docs/architecture/module-boundaries.md](./docs/architecture/module-boundaries.md).
+
+## Runtime flow
+
+1. The browser loads [`index.html`](./index.html).
+2. The document loads [`src/style.css`](./src/style.css) and [`src/main.ts`](./src/main.ts).
+3. [`src/main.ts`](./src/main.ts) registers `app-view`, `home-page`,
+   `router-page`, `not-found-page`, and `counter-component`, then calls
+   `Core()`.
+4. KoppaJS instantiates `<app-view>`.
+5. [`src/app-view.kpa`](./src/app-view.kpa) renders the app shell, navigation,
+   and `#app-outlet`.
+6. `src/main.ts` initializes `KoppajsRouter` with the route table and outlet.
+7. The router renders the matching route component into `#app-outlet`,
+   synchronizes active links, and updates the current browser URL.
+
+## Quality automation layer
+
+- `eslint.config.mjs` lint-checks TypeScript source plus tooling files.
+- `prettier.config.mjs` and `.editorconfig` keep supported text files consistent.
+- `.npmrc` enforces the declared engine floor during installs.
+- `.husky/pre-commit` runs `lint-staged`.
+- `.husky/commit-msg` validates commit headers with `commitlint`.
+- `.github/workflows/ci.yml` runs the full repository validation flow on GitHub.
+- `.github/workflows/release.yml` runs tagged release validation and creates GitHub Releases.
+
+## Module responsibilities
+
+| Module                      | Responsibility                                                   | Must not do                                            |
+| --------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------ |
+| `index.html`                | Declare the root tag and static assets                           | Hold feature logic or router setup                     |
+| `src/main.ts`               | Bootstrap the app, register components, and start one router     | Accumulate page copy or unrelated UI state             |
+| `src/app-view.kpa`          | Render the shared shell, nav, and router outlet                  | Own route resolution or register components            |
+| `src/home-page.kpa`         | Render the landing route and compose the counter example         | Reach into router internals or mutate global DOM state |
+| `src/router-page.kpa`       | Render the second route and explain the router baseline          | Own bootstrap logic or global navigation state         |
+| `src/not-found-page.kpa`    | Render the explicit fallback route                               | Replace route matching or bootstrap responsibilities   |
+| `src/counter-component.kpa` | Demonstrate local interactive state                              | Reach into route orchestration or app-shell concerns   |
+| `src/style.css`             | Hold global tokens and truly global base styles                  | Duplicate component-local visuals                      |
+| `tests/integration/`        | Verify bootstrap and router-start boundaries                     | Duplicate full browser smoke expectations              |
+| `tests/e2e/`                | Verify visible navigation and counter behavior in a real browser | Assert brittle implementation details                  |
+
+## Invariants
+
+- There is exactly one bootstrap entrypoint.
+- The root tag in `index.html` must match a component registered in `src/main.ts`.
+- `Core()` is called once from `src/main.ts`.
+- The starter owns exactly one router instance.
+- The route table contains an explicit `*` fallback route.
+- Route rendering happens through `#app-outlet`.
+- Official releases require matching versions across `package.json`,
+  `CHANGELOG.md`, and `vX.Y.Z` tags.
+
+## Extension guidance
+
+- Add new route components under `src/` and register them from `src/main.ts`.
+- Keep route definitions in one obvious place.
+- Extract reusable route helpers into `.ts` modules only when logic becomes
+  shared or branch-heavy.
+- Add a spec before changing visible navigation behavior.
+- Add an ADR before changing the routing model, adding data fetching,
+  persistence, or another major subsystem.

package/template-overlays/router/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Change Log
+
+All notable changes to **__PROJECT_NAME__** are documented in this file.
+
+This project uses a **manual, tag-driven release process**.
+Only tagged versions represent official releases.
+
+This changelog documents **intentional milestones and guarantees**,
+not every internal refactor.
+
+---
+
+## [Unreleased]
+
+_No unreleased changes yet._
+
+---
+
+## [1.0.0] — Initial Starter Baseline
+
+**2026-03-17**
+
+### Added
+
+- a small KoppaJS router app shell with `app-view`, `home-page`,
+  `router-page`, `not-found-page`, and `counter-component`
+- route-based rendering through `@koppajs/koppajs-router`
+- ESLint, Prettier, Vitest, Playwright, Husky, lint-staged, and commitlint
+- starter governance docs, ADRs, specs, and release workflow files
+
+---
+
+## Versioning Policy
+
+- Semantic Versioning (SemVer) is followed pragmatically
+- **Breaking changes** include:
+  - public runtime behavior changes
+  - route structure changes
+  - release workflow changes
+
+---
+
+_This changelog documents intent.
+If something is not written here, it is not guaranteed._

package/template-overlays/router/DEVELOPMENT_RULES.md

@@ -0,0 +1,57 @@
+# Development Rules
+
+## Scope
+
+These rules describe how code and documentation are expected to evolve in this repository.
+
+## Source layout rules
+
+- Keep `index.html` as a static shell with asset references and the single root element.
+- Keep `src/main.ts` limited to bootstrap concerns: imports, `Core.take(...)`
+  registrations, route definitions, and initialization of the single router instance.
+- Use `.kpa` files for UI composition, local component state, and component-scoped CSS.
+- Keep the route outlet inside `app-view.kpa` and keep route rendering consumer-owned.
+- If logic becomes reusable, asynchronous, or branch-heavy, move it into `.ts` modules under `src/`.
+- Keep `public/` for static assets only.
+
+## Naming conventions
+
+- Custom element names must be kebab-case.
+- Root-level application components should use `app-` prefixes when they represent app shells or app-wide structure.
+- Route component filenames should match their registered component tags or route purpose.
+- New files and folders should use descriptive names over abbreviations.
+
+## Dependency rules
+
+- Runtime dependencies must be justified by a concrete need in a spec or ADR.
+- Prefer browser APIs and KoppaJS primitives before adding helper libraries.
+- Keep this repository wired to published npm packages unless there is an explicit ADR stating otherwise.
+- Build tooling changes must update contributor docs and architecture docs in the same change.
+- Quality tooling must stay proportionate to the starter.
+
+## Coding patterns
+
+- Favor simple, local state over premature abstraction.
+- Keep route definitions obvious and close to router initialization.
+- Avoid hidden side effects during import.
+- Keep CSS local to components unless the style truly applies application-wide.
+- Preserve strict TypeScript settings; do not weaken `tsconfig.json` to work around errors.
+- Give interactive controls stable accessible names so smoke tests can target public semantics instead of brittle selectors.
+
+## Forbidden without a spec and ADR
+
+- Replacing the starter's single-router model with a second navigation system
+- Adding global state containers
+- Adding network or persistence layers
+- Introducing SSR, multi-page bootstraps, or multiple root entries
+- Switching dependency sourcing from npm packages to local monorepo links
+- Expanding the starter into a feature-rich demo application
+- Adding heavyweight hooks that run the entire suite on every commit
+
+## Documentation obligations
+
+- Update [ARCHITECTURE.md](./ARCHITECTURE.md) when source layout or runtime flow changes.
+- Update [TESTING_STRATEGY.md](./TESTING_STRATEGY.md) when quality gates or tooling change.
+- Update or create a spec in [docs/specs](./docs/specs) for user-visible changes.
+- Add an ADR in [docs/adr](./docs/adr) for durable technical decisions.
+- Update [docs/quality/quality-gates.md](./docs/quality/quality-gates.md) when scripts, hooks, CI checks, or browser-smoke expectations change.