create-koppajs 1.1.0 → 1.2.1

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.3",
+    "@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.1",
+    "@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"
+  }
+}