create-koppajs 1.0.1 → 1.2.0

package/template-overlays/router/README.md

@@ -0,0 +1,243 @@
+<a id="readme-top"></a>
+
+<div align="center">
+  <img src="https://public-assets-1b57ca06-687a-4142-a525-0635f7649a5c.s3.eu-central-1.amazonaws.com/koppajs/koppajs-logo-text-900x226.png" width="500" alt="KoppaJS Logo">
+</div>
+
+<br>
+
+<div align="center">
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue?style=flat-square" alt="License"></a>
+</div>
+
+<br>
+
+<div align="center">
+  <h1 align="center">__PROJECT_NAME__</h1>
+  <h3 align="center">KoppaJS router starter project</h3>
+  <p align="center">
+    <i>Scaffolded from the official KoppaJS router starter baseline.</i>
+  </p>
+</div>
+
+<br>
+
+<div align="center">
+  <p align="center">
+    <a href="https://github.com/koppajs/koppajs-documentation">Documentation</a>
+    &middot;
+    <a href="https://github.com/koppajs/koppajs-core">KoppaJS Core</a>
+    &middot;
+    <a href="https://github.com/koppajs/koppajs-router">KoppaJS Router</a>
+    &middot;
+    <a href="https://github.com/koppajs/koppajs-vite-plugin">Vite Plugin</a>
+  </p>
+</div>
+
+<br>
+
+<details>
+<summary>Table of Contents</summary>
+  <ol>
+    <li><a href="#what-is-this">What is this?</a></li>
+    <li><a href="#requirements">Requirements</a></li>
+    <li><a href="#getting-started">Getting Started</a></li>
+    <li><a href="#quality-workflow">Quality Workflow</a></li>
+    <li><a href="#routing-overview">Routing Overview</a></li>
+    <li><a href="#project-structure">Project Structure</a></li>
+    <li><a href="#meta-layer">Meta Layer</a></li>
+    <li><a href="#community--contribution">Community & Contribution</a></li>
+    <li><a href="#license">License</a></li>
+  </ol>
+</details>
+
+---
+
+## What is this?
+
+This project was scaffolded from the official KoppaJS router starter baseline.
+
+It keeps the application intentionally small while demonstrating one extra
+subsystem beyond the minimal starter:
+
+- one HTML shell
+- one TypeScript bootstrap file
+- one root app shell component
+- one router instance with a visible two-page flow
+- one counter component on the home route
+- one explicit catch-all route for unmatched paths
+
+It also carries the same quality and governance baseline as the minimal starter:
+
+- ESLint for source and tooling files
+- Prettier plus `.editorconfig` for supported text formats
+- Vitest for local unit and integration coverage
+- Playwright for a real-browser smoke test
+- Husky plus lint-staged for fast staged-file checks
+- Conventional Commits enforcement via `commitlint`
+- a tag-driven GitHub release baseline with `CHANGELOG.md` and `RELEASE.md`
+
+Use it when you want to start from a small KoppaJS app that already shows how
+route definitions, `data-route` links, and route-based outlet rendering fit
+together.
+
+---
+
+## Requirements
+
+- Node.js 20.19+, 22.13+, or 24+
+- pnpm >= 10
+
+Node 23 is intentionally not treated as supported here because the current
+upstream frontend toolchain excludes it.
+
+---
+
+## Getting Started
+
+```bash
+pnpm install
+pnpm dev
+```
+
+Install the Playwright browser once if you want to run the browser smoke test locally:
+
+```bash
+pnpm exec playwright install chromium
+```
+
+Useful commands:
+
+```bash
+pnpm lint
+pnpm format:check
+pnpm typecheck
+pnpm test:run
+pnpm test:coverage
+pnpm build
+pnpm serve
+pnpm release:check
+```
+
+---
+
+## Quality Workflow
+
+Fast local baseline:
+
+```bash
+pnpm check
+```
+
+Full validation, including Playwright:
+
+```bash
+pnpm validate
+```
+
+Standalone browser smoke test:
+
+```bash
+pnpm test:e2e
+```
+
+---
+
+## Routing Overview
+
+The starter wires `@koppajs/koppajs-router` in `src/main.ts`.
+
+The route table currently contains:
+
+- `/` -> `home-page`
+- `/router` -> `router-page`
+- `*` -> `not-found-page`
+
+The router renders into `#app-outlet`, updates active navigation state for
+links that use `data-route`, and keeps the browser URL aligned with the current
+page.
+
+---
+
+## Project Structure
+
+```text
+__PROJECT_NAME__/
+├── .editorconfig
+├── .github/
+├── .gitignore
+├── .husky/
+├── .npmrc
+├── .prettierignore
+├── CHANGELOG.md
+├── commitlint.config.mjs
+├── AI_CONSTITUTION.md
+├── ARCHITECTURE.md
+├── CONTRIBUTING.md
+├── DECISION_HIERARCHY.md
+├── DEVELOPMENT_RULES.md
+├── RELEASE.md
+├── ROADMAP.md
+├── TESTING_STRATEGY.md
+├── eslint.config.mjs
+├── index.html
+├── package.json
+├── playwright.config.ts
+├── pnpm-lock.yaml
+├── prettier.config.mjs
+├── tsconfig.json
+├── vite.config.mjs
+├── vitest.config.mjs
+├── docs/
+│   ├── adr/
+│   ├── architecture/
+│   ├── meta/
+│   ├── quality/
+│   └── specs/
+├── public/
+│   └── favicon.svg
+├── src/
+│   ├── main.ts
+│   ├── style.css
+│   ├── app-view.kpa
+│   ├── counter-component.kpa
+│   ├── home-page.kpa
+│   ├── router-page.kpa
+│   └── not-found-page.kpa
+└── tests/
+    ├── e2e/
+    ├── integration/
+    └── unit/
+```
+
+---
+
+## Meta Layer
+
+The repository includes an explicit meta layer so architecture, testing, and
+contributor rules evolve together with the codebase.
+
+Start here:
+
+- `DECISION_HIERARCHY.md`
+- `AI_CONSTITUTION.md`
+- `ARCHITECTURE.md`
+- `DEVELOPMENT_RULES.md`
+- `TESTING_STRATEGY.md`
+- `CHANGELOG.md`
+- `RELEASE.md`
+- `docs/quality/quality-gates.md`
+- `docs/adr/`
+- `docs/specs/`
+
+---
+
+## Community & Contribution
+
+Contribution workflow details live in `CONTRIBUTING.md`.
+Update this section with your own repository links once the project has a
+canonical home.
+
+---
+
+## License

package/template-overlays/router/ROADMAP.md

@@ -0,0 +1,34 @@
+# Roadmap
+
+This roadmap describes intended directions, not guaranteed delivery dates.
+
+## Current priorities
+
+- Keep the router starter focused and production-like.
+- Preserve a clear bootstrap path for new KoppaJS users.
+- Keep the meta layer synchronized with the actual repository.
+
+## Near-term opportunities
+
+- Add route-level examples only when they demonstrate a real starter need.
+- Strengthen route-related tests if the starter gains redirects, params, or nested routes.
+- Keep documentation aligned with the actual router wiring.
+
+## Longer-term expansion triggers
+
+These should happen only with a spec and ADR:
+
+- async data fetching
+- persistence
+- richer route hierarchies
+- shared state beyond local component state
+- CI automation changes
+
+## Meta-layer maintenance
+
+Every release or architecture-changing change should answer:
+
+- Does the architecture document still match the code?
+- Did any new decision deserve an ADR?
+- Did testing expectations change?
+- Did contributor instructions stay accurate?

package/template-overlays/router/TESTING_STRATEGY.md

@@ -0,0 +1,67 @@
+# Testing Strategy
+
+## Current state
+
+This repository carries a small automated testing stack aligned with the router starter's actual risk profile:
+
+- `pnpm test:run` for unit and integration tests in Vitest
+- `pnpm test:coverage` for local coverage reporting
+- `pnpm test:e2e` for a Playwright smoke test against `vite preview`
+- `pnpm check` for the fast repository baseline
+- `pnpm validate` for the full local and CI validation path
+- `pnpm release:check` for tagged release candidates
+- `commitlint` through `.husky/commit-msg` for commit message validation
+
+## Philosophy
+
+- Test the smallest meaningful unit that gives confidence.
+- Prefer extracting logic into `.ts` modules when it becomes complex enough to warrant focused unit tests.
+- Avoid brittle tests that mirror implementation details instead of observable behavior.
+- Reuse the real Vite loading path in automated tests whenever `.kpa` handling is part of the risk surface.
+
+## Test pyramid for this repository
+
+### Unit tests
+
+Use unit tests for isolated logic that can fail independently of the browser runtime.
+
+### Integration or component tests
+
+Use integration tests when bootstrap, component registration, and router startup
+must be verified together but a full browser run would be disproportionate.
+
+Typical triggers:
+
+- bootstrap registration in `src/main.ts`
+- router startup wiring and route table shape
+- build-time behavior that depends on the Vite plugin
+
+### End-to-end tests
+
+Keep Playwright intentionally user-facing and smoke-level.
+
+Typical triggers:
+
+- root UI rendering
+- route navigation between starter pages
+- critical starter interactions such as the counter behavior
+- preview/build regressions that would not be caught by Vitest alone
+
+## Coverage expectations
+
+- There is no blanket repository percentage target right now.
+- New non-trivial logic should come with focused tests.
+- When a subsystem introduces more branching logic, async behavior, or shared state, test automation stops being optional.
+
+## Quality gates by change size
+
+- Documentation-only change: verify links and document consistency.
+- Small style or copy change: run `pnpm check`.
+- Source or config change: run `pnpm check`.
+- UI, bootstrap, or browser-sensitive change: run `pnpm validate`.
+- Version, changelog, or release workflow change: run `pnpm release:check`.
+
+## Maintenance rule
+
+Whenever test tooling, quality gates, or expected confidence levels change,
+update this file and [docs/quality/quality-gates.md](./docs/quality/quality-gates.md) in the same change.

package/template-overlays/router/docs/adr/0001-keep-the-starter-minimal.md

@@ -0,0 +1,32 @@
+# ADR 0001: Keep the router starter focused
+
+## Context
+
+This repository starts from the maintained KoppaJS router starter baseline.
+Its audience needs a runnable reference that demonstrates routing without
+turning into a broad showcase application.
+
+## Decision
+
+The router starter remains intentionally small:
+
+- one HTML shell,
+- one TypeScript bootstrap file,
+- one root KoppaJS view,
+- one router instance,
+- two primary routes plus one explicit fallback route,
+- one stateful child component,
+- published npm packages instead of local monorepo `file:` dependencies.
+
+Any expansion beyond that baseline requires a spec and ADR.
+
+## Consequences
+
+- New users get a fast example of routing without a lot of incidental complexity.
+- The repository stays easy to audit and maintain.
+- More advanced route features must be introduced deliberately rather than accumulating ad hoc.
+
+## Alternatives considered
+
+- A feature-rich demo app that showcases many KoppaJS patterns at once
+- A monorepo-linked starter that depends on local sibling packages

package/template-overlays/router/docs/architecture/module-boundaries.md

@@ -0,0 +1,39 @@
+# Module Boundaries
+
+## Repository boundary model
+
+This repository is intentionally shallow. Its boundaries keep the starter easy to inspect.
+
+| Path                        | Responsibility                                                    | Allowed dependencies                                                     | Must not depend on                                  |
+| --------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------ | --------------------------------------------------- |
+| `index.html`                | Document shell, root element, asset references                    | Static assets, `src/main.ts`, `src/style.css`                            | Feature logic, router setup, extra scripts          |
+| `src/main.ts`               | Application bootstrap, component registration, and router startup | `@koppajs/koppajs-core`, `@koppajs/koppajs-router`, local `.kpa` modules | Page copy, route component visuals, unrelated state |
+| `src/app-view.kpa`          | Shared shell, primary navigation, and route outlet                | Local markup, local CSS                                                  | Route matching, component registration              |
+| `src/home-page.kpa`         | Landing-route content and counter composition                     | Local markup, local CSS, `counter-component`                             | Router setup or global shell orchestration          |
+| `src/router-page.kpa`       | Second-route content                                              | Local markup and local CSS                                               | Bootstrap or route resolution concerns              |
+| `src/not-found-page.kpa`    | Explicit fallback-route content                                   | Local markup and local CSS                                               | Route matching rules or global state                |
+| `src/counter-component.kpa` | Example local state and interaction                               | Local markup, local methods, local CSS                                   | Route orchestration or app-shell concerns           |
+| `src/style.css`             | Global tokens and truly global base rules                         | Standard CSS                                                             | Route-specific or component-specific visual rules   |
+| `tests/integration/`        | Bootstrap and router boundary verification                        | Vitest, local modules, selective mocks                                   | Browser-only smoke assertions                       |
+| `tests/e2e/`                | Real-browser smoke coverage                                       | Playwright, preview server                                               | Implementation-detail assertions                    |
+| `vite.config.mjs`           | Build and dev server integration                                  | Vite and the KoppaJS Vite plugin                                         | Application runtime logic                           |
+
+## Boundary rules
+
+- Registration and route configuration happen in `src/main.ts`.
+- `app-view.kpa` may compose navigation and the outlet but must not become a second router.
+- Route components own their own copy and layout.
+- Shared logic belongs in dedicated `.ts` modules once reuse or complexity justifies it.
+- Vitest owns helper-level and bootstrap-level confidence; Playwright owns browser smoke confidence.
+
+## Escalation rules
+
+Before crossing existing boundaries, add a spec and ADR if the change introduces:
+
+- nested or parameterized routing beyond the current baseline,
+- shared state,
+- async workflows,
+- persistence,
+- more than one root entrypoint,
+- npm publishing or deployment automation,
+- new top-level source folders.

package/template-overlays/router/docs/meta/maintenance.md

@@ -0,0 +1,38 @@
+# Meta-Layer Maintenance
+
+The meta layer is a living system. Any change that alters the real system must update the corresponding governance document in the same change.
+
+## Update matrix
+
+| Change                                     | Required updates                                                                               |
+| ------------------------------------------ | ---------------------------------------------------------------------------------------------- |
+| New feature or behavior                    | Add or update a spec in `docs/specs/`; update `README.md` if setup or visible behavior changes |
+| New enduring technical decision            | Add or update an ADR in `docs/adr/`                                                            |
+| New module, folder, or data flow           | Update `ARCHITECTURE.md` and `docs/architecture/module-boundaries.md`                          |
+| New coding pattern or dependency rule      | Update `DEVELOPMENT_RULES.md`                                                                  |
+| New test tooling or quality gate           | Update `TESTING_STRATEGY.md` and `docs/quality/quality-gates.md`                               |
+| New hook, CI step, or contributor workflow | Update `CONTRIBUTING.md` and `.github/instructions/ai-workflow.md`                             |
+| Version, changelog, or release workflow    | Update `CHANGELOG.md`, `RELEASE.md`, `package.json`, and affected GitHub workflow files        |
+
+## Review triggers
+
+Perform a meta-layer review when:
+
+- a pull request changes the repo structure,
+- a new dependency is added,
+- a public component tag changes,
+- a build or test command changes,
+- a hook or CI workflow changes,
+- the routing model or route surface changes,
+- a README section no longer matches the actual code.
+
+## Periodic review checklist
+
+- Does [ARCHITECTURE.md](../../ARCHITECTURE.md) still match the runtime flow?
+- Do current specs cover the user-visible behaviors in the repo?
+- Do ADRs still represent active decisions?
+- Do contributor instructions still match the actual toolchain?
+- Did a recent change deserve a new quality gate?
+- Do `CHANGELOG.md`, `RELEASE.md`, and the release workflow still match actual branch and tag practice?
+
+If any answer is "no", update the meta layer before considering the repository aligned.

package/template-overlays/router/docs/specs/README.md

@@ -0,0 +1,19 @@
+# Specifications
+
+Specs define expected behavior before or alongside implementation. They are the highest-precedence project documents.
+
+## When a spec is required
+
+Create or update a spec when a change:
+
+- introduces or changes user-visible behavior,
+- adds a subsystem,
+- changes public setup or bootstrap behavior,
+- changes a feature in a way that needs explicit acceptance criteria.
+
+## Current specs
+
+- [`app-bootstrap.md`](./app-bootstrap.md)
+- [`counter-component.md`](./counter-component.md)
+- [`router-navigation.md`](./router-navigation.md)
+- [`quality-workflow.md`](./quality-workflow.md)

package/template-overlays/router/docs/specs/app-bootstrap.md

@@ -0,0 +1,42 @@
+# Spec: App bootstrap
+
+## Status
+
+Approved
+
+## Purpose
+
+Provide a predictable startup path for a KoppaJS application that includes the official router runtime.
+
+## Behavior
+
+- The application starts from `index.html`.
+- The HTML shell loads one global stylesheet and one module entrypoint.
+- The document declares exactly one root custom element: `<app-view>`.
+- `src/main.ts` registers `app-view`, `home-page`, `router-page`, `not-found-page`, and `counter-component` with KoppaJS Core.
+- `src/main.ts` invokes `Core()` once and starts one `KoppajsRouter` instance.
+
+## Inputs
+
+- Browser loading `index.html`
+- Static asset and source file paths resolved by Vite
+
+## Outputs
+
+- A rendered `<app-view>` application shell
+- A rendered route component inside `#app-outlet`
+- A registered `<counter-component>` available to the home route
+
+## Constraints
+
+- There must be a single bootstrap entrypoint.
+- The root tag in `index.html` must stay aligned with the component registered in `src/main.ts`.
+- `Core()` must remain the only KoppaJS bootstrap call.
+- Router initialization must happen after the route outlet exists.
+- No extra runtime dependencies are required beyond the declared npm packages.
+
+## Acceptance criteria
+
+- Opening the app through Vite renders the root view without manual DOM scripting.
+- `src/main.ts` remains the only location that calls `Core()`.
+- The route outlet is initialized by the router and can render the home route immediately after bootstrap.

package/template-overlays/router/docs/specs/router-navigation.md

@@ -0,0 +1,41 @@
+# Spec: Router navigation
+
+## Status
+
+Approved
+
+## Purpose
+
+Define the starter's router baseline so the generated project demonstrates a small but real navigation flow.
+
+## Behavior
+
+- The starter initializes one `KoppajsRouter` instance from `src/main.ts`.
+- The router renders matched route components into `#app-outlet`.
+- Primary navigation links use `data-route` and participate in active-link state updates.
+- The starter includes a home route, a second content route, and an explicit `*` fallback route.
+
+## Inputs
+
+- Route definitions declared in `src/main.ts`
+- Browser URL and History API state
+- User clicks on matching `data-route` links
+
+## Outputs
+
+- URL changes that stay aligned with the rendered route component
+- Active navigation state on the current route link
+- A predictable not-found page for unmatched paths
+
+## Constraints
+
+- The route table must stay small and inspectable.
+- The fallback route must be explicit rather than implicit.
+- Route content stays in consumer-owned `.kpa` files, not inside the router package.
+
+## Acceptance criteria
+
+- Visiting `/` renders the home route.
+- Visiting `/router` renders the second route.
+- Visiting an unmatched path renders the fallback route.
+- The active navigation link exposes `aria-current="page"` for the current route.

package/template-overlays/router/index.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>KoppaJS Router Starter</title>
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <link rel="stylesheet" href="/src/style.css" />
+  </head>
+  <body>
+    <app-view></app-view>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/template-overlays/router/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "__PROJECT_NAME__",
+  "version": "1.0.0",
+  "private": true,
+  "description": "KoppaJS router application scaffolded with create-koppajs.",
+  "author": "Bastian Bensch",
+  "license": "Apache-2.0",
+  "keywords": [
+    "koppajs",
+    "koppa",
+    "starter",
+    "scaffold",
+    "vite",
+    "typescript",
+    "web-components",
+    "router"
+  ],
+  "packageManager": "pnpm@10.12.1",
+  "engines": {
+    "node": "^20.19.0 || ^22.13.0 || >=24.0.0",
+    "pnpm": ">=10"
+  },
+  "scripts": {
+    "dev": "vite --host",
+    "build": "tsc --noEmit && vite build",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier . --write --ignore-unknown",
+    "format:check": "prettier . --check --ignore-unknown",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:run": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:e2e": "pnpm build && playwright test",
+    "test:e2e:headed": "pnpm build && playwright test --headed",
+    "test:e2e:ui": "pnpm build && playwright test --ui",
+    "check": "pnpm lint && pnpm format:check && pnpm typecheck && pnpm test:run && pnpm build",
+    "validate": "pnpm check && playwright test",
+    "release:check": "pnpm validate",
+    "typecheck": "tsc --noEmit",
+    "serve": "vite preview",
+    "serve:e2e": "vite preview --host 127.0.0.1 --strictPort --port 4173",
+    "prepare": "husky"
+  },
+  "dependencies": {
+    "@koppajs/koppajs-core": "^3.0.2",
+    "@koppajs/koppajs-router": "^0.1.0"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^20.1.0",
+    "@commitlint/config-conventional": "^20.0.0",
+    "@eslint/js": "^10.0.1",
+    "@koppajs/koppajs-vite-plugin": "^1.0.0",
+    "@playwright/test": "^1.58.2",
+    "@types/node": "^25.4.0",
+    "@vitest/coverage-v8": "^4.0.18",
+    "eslint": "^10.0.3",
+    "globals": "^17.4.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.3.3",
+    "prettier": "^3.8.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.57.0",
+    "vite": "7.2.6",
+    "vitest": "^4.0.18"
+  },
+  "lint-staged": {
+    "*.{js,mjs,cjs,ts,mts,cts}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{css,html,json,md,yml,yaml}": "prettier --write"
+  }
+}