@koppajs/koppajs-core 3.0.2 → 3.0.4

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 (6) hide show
  1. package/CHANGELOG.md +46 -0
  2. package/README.md +148 -79
  3. package/dist/index.cjs.js.map +1 -1
  4. package/dist/index.es.js.map +1 -1
  5. package/dist/utils/helper.d.ts +1 -1
  6. package/package.json +17 -13
package/CHANGELOG.md CHANGED
@@ -22,6 +22,52 @@ Changes will only appear here when they:
22
22
 
23
23
  ---
24
24
 
25
+ ## [3.0.4] — Documentation Contract And Release Guardrails
26
+
27
+ **2026-03-27**
28
+
29
+ Patch release to formalize governed repository-document contracts, strengthen
30
+ local release validation, and tighten contributor workflow guidance. No
31
+ intentional runtime or public API changes.
32
+
33
+ ### Added
34
+
35
+ - Added an explicit repository documentation contract spec and a local validator
36
+ for governed root documents
37
+
38
+ ### Changed
39
+
40
+ - Added `check:docs` to the main quality gate and local pre-commit flow
41
+ - Tightened README and contributor governance docs around documentation shape
42
+ and release expectations
43
+ - Updated GitHub Actions workflow action runtimes for CI and release automation
44
+
45
+ ---
46
+
47
+ ## [3.0.3] — Tooling Baseline And Ecosystem Cleanup
48
+
49
+ **2026-03-26**
50
+
51
+ Patch release to tighten repository quality workflow, align ecosystem-facing
52
+ docs, and harden a small helper type contract. No intentional breaking runtime
53
+ changes.
54
+
55
+ ### Added
56
+
57
+ - Added repository meta-layer documents, ADR/spec directories, and explicit
58
+ contributor workflow guidance
59
+
60
+ ### Changed
61
+
62
+ - Tightened `setValueByPath(...)` typing without widening runtime behavior
63
+ - Split source and test TypeScript checks and hardened coverage thresholds
64
+ - Simplified lint, format, hook, and CI workflow configuration around the
65
+ current repository baseline
66
+ - Updated README ecosystem links to point at the released starter/tooling
67
+ surface
68
+
69
+ ---
70
+
25
71
  ## [3.0.2] — Public API Cleanup
26
72
 
27
73
  **2026-03-11**
package/README.md CHANGED
@@ -1,81 +1,131 @@
1
1
  <a id="readme-top"></a>
2
2
 
3
- <!-- PROJECT LOGO -->
4
3
  <div align="center">
5
4
  <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">
6
5
  </div>
7
6
 
8
7
  <br>
9
8
 
10
- <!-- PROJECT SHIELDS -->
11
9
  <div align="center">
12
- <a href="https://www.npmjs.com/package/@koppajs/koppajs-core"><img src="https://img.shields.io/npm/v/@koppajs/koppajs-core?style=flat-square" alt="npm version"></a> <a href="https://github.com/koppajs/koppajs-core/actions"><img src="https://img.shields.io/github/actions/workflow/status/koppajs/koppajs-core/ci.yml?branch=main&style=flat-square" alt="CI Status"></a> <a href="https://www.npmjs.com/package/@koppajs/koppajs-core"><img src="https://img.shields.io/badge/gzip-13.6%20kB-blue?style=flat-square" alt="Bundle size"></a> <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue?style=flat-square" alt="License"></a>
10
+ <a href="https://www.npmjs.com/package/@koppajs/koppajs-core"><img src="https://img.shields.io/npm/v/@koppajs/koppajs-core?style=flat-square" alt="npm version"></a>
11
+ <a href="https://github.com/koppajs/koppajs-core/actions"><img src="https://img.shields.io/github/actions/workflow/status/koppajs/koppajs-core/ci.yml?branch=main&style=flat-square" alt="CI Status"></a>
12
+ <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue?style=flat-square" alt="License"></a>
13
13
  </div>
14
14
 
15
15
  <br>
16
16
 
17
- <!-- ELEVATOR PITCH -->
18
17
  <div align="center">
19
- <h1 align="center">KoppaJS – Pragmatic frontend made modular</h1>
20
- <h3 align="center">Build fast, simple, and growable – without the noise of modern frameworks.</h3>
21
- <p align="center">
22
- <i align="center">A quiet rebellion against complexity – and a wish that building can still feel good.</i>
23
- </p>
18
+ <h1 align="center">@koppajs/koppajs-core</h1>
19
+ <h3 align="center">Core runtime and component model for KoppaJS</h3>
20
+ <p align="center">
21
+ <i>Reactive components, explicit lifecycle seams, and a small runtime without virtual DOM overhead.</i>
22
+ </p>
24
23
  </div>
25
24
 
26
25
  <br>
27
26
 
28
- <!-- IMPORTANT LINKS -->
29
27
  <div align="center">
30
- <p align="center">
31
- <a href="https://github.com/koppajs/koppajs-documentation">Documentation</a>
32
- &middot;
33
- <a href="https://github.com/koppajs/koppajs-example">Example Project</a>
34
- &middot;
35
- <a href="https://github.com/koppajs/koppajs-core/issues">Issues</a>
36
- </p>
28
+ <p align="center">
29
+ <a href="https://github.com/koppajs/koppajs-documentation">Documentation</a>
30
+ &middot;
31
+ <a href="https://github.com/koppajs/create-koppajs">create-koppajs</a>
32
+ &middot;
33
+ <a href="https://github.com/koppajs/koppajs-vite-plugin">Vite Plugin</a>
34
+ &middot;
35
+ <a href="https://github.com/koppajs/koppajs-router">Router</a>
36
+ &middot;
37
+ <a href="https://github.com/koppajs/koppajs-core/issues">Issues</a>
38
+ </p>
37
39
  </div>
38
40
 
39
41
  <br>
40
42
 
41
- <!-- TABLE OF CONTENTS -->
42
43
  <details>
43
44
  <summary>Table of Contents</summary>
44
- <ol>
45
- <li><a href="#what-is-koppajs">What is KoppaJS?</a></li>
46
- <li><a href="#features">Features</a></li>
47
- <li><a href="#getting-started">Getting Started</a></li>
48
- <li><a href="#roadmap">Roadmap</a></li>
49
- <li><a href="#support">Support</a></li>
50
- <li><a href="#community--contribution">Community & Contribution</a></li>
51
- </ol>
45
+ <ol>
46
+ <li><a href="#what-is-koppajs-core">What is KoppaJS Core?</a></li>
47
+ <li><a href="#features">Features</a></li>
48
+ <li><a href="#installation">Installation</a></li>
49
+ <li><a href="#requirements">Requirements</a></li>
50
+ <li><a href="#getting-started">Getting Started</a></li>
51
+ <li><a href="#runtime-model">Runtime Model</a></li>
52
+ <li><a href="#roadmap">Roadmap</a></li>
53
+ <li><a href="#architecture-governance">Architecture & Governance</a></li>
54
+ <li><a href="#community-contribution">Community & Contribution</a></li>
55
+ <li><a href="#license">License</a></li>
56
+ </ol>
52
57
  </details>
53
58
 
54
59
  ---
55
60
 
56
- ## What is KoppaJS?
61
+ ## What is KoppaJS Core?
57
62
 
58
- KoppaJS is a lightweight, modular frontend framework designed to simplify development without sacrificing flexibility. It provides a pragmatic approach to building modern web applications, focusing on:
63
+ `@koppajs/koppajs-core` is the runtime package at the center of the KoppaJS
64
+ stack.
59
65
 
60
- - **Simplicity:** Minimal boilerplate and intuitive APIs.
61
- - **Performance:** Optimized for speed and scalability.
62
- - **Modularity:** Build only what you need, when you need it.
66
+ It owns the public bootstrap surface, component registration, DOM runtime
67
+ setup, lifecycle coordination, and the stable contracts that other KoppaJS
68
+ packages build on top of.
69
+
70
+ In practice that means:
71
+
72
+ - applications register components through `Core.take(...)`
73
+ - the runtime boots once through `Core()`
74
+ - the Vite plugin handles `.kpa` transformation, while core stays focused on
75
+ runtime behavior
63
76
 
64
77
  ---
65
78
 
66
79
  ## Features
67
80
 
68
- - **Declarative Components:** Define components with `.kpa` files.
69
- - **Reactive State Management:** Built-in reactivity for seamless updates.
70
- - **Lifecycle Hooks:** Control component behavior with hooks like `mounted`, `updated`, and `beforeUpdate`.
71
- - **Integration-Friendly:** Works with existing tools and libraries.
72
- - **TypeScript Support:** First-class TypeScript support for safer, more maintainable code.
81
+ - component registration via the stable `Core.take(...)` API
82
+ - one-time runtime bootstrap through `Core()`
83
+ - reactive component model with explicit methods, refs, props, and lifecycle
84
+ hooks
85
+ - modular extension surface for plugins and modules
86
+ - no virtual DOM dependency
87
+ - published package with ESM, CommonJS, and TypeScript types
88
+
89
+ ---
90
+
91
+ ## Installation
92
+
93
+ ```bash
94
+ pnpm add @koppajs/koppajs-core
95
+ pnpm add -D @koppajs/koppajs-vite-plugin vite typescript
96
+ ```
97
+
98
+ ```bash
99
+ npm install @koppajs/koppajs-core
100
+ npm install -D @koppajs/koppajs-vite-plugin vite typescript
101
+ ```
102
+
103
+ The fastest path for most users is still the official starter:
104
+
105
+ ```bash
106
+ pnpm create koppajs my-app
107
+ ```
108
+
109
+ ---
110
+
111
+ ## Requirements
112
+
113
+ For package consumers:
114
+
115
+ - a browser-based application environment
116
+ - a build pipeline that can consume KoppaJS components, typically Vite plus
117
+ `@koppajs/koppajs-vite-plugin`
118
+
119
+ For local repository work:
120
+
121
+ - Node.js >= 20
122
+ - pnpm >= 10.24.0
73
123
 
74
124
  ---
75
125
 
76
126
  ## Getting Started
77
127
 
78
- The fastest way to start a new KoppaJS project:
128
+ Recommended bootstrap path:
79
129
 
80
130
  ```bash
81
131
  pnpm create koppajs my-app
@@ -84,69 +134,88 @@ pnpm install
84
134
  pnpm dev
85
135
  ```
86
136
 
87
- This scaffolds a ready-to-run project with Vite, TypeScript, and two sample components.
137
+ Manual registration with the public core API:
88
138
 
89
- You can also use npm or npx:
139
+ ```ts
140
+ import { Core } from '@koppajs/koppajs-core'
90
141
 
91
- ```bash
92
- npm create koppajs my-app
93
- npx create-koppajs my-app
142
+ import appView from './app-view.kpa'
143
+ import counterComponent from './counter-component.kpa'
144
+
145
+ Core.take(appView, 'app-view')
146
+ Core.take(counterComponent, 'counter-component')
147
+ Core()
94
148
  ```
95
149
 
96
- ### Manual Setup
150
+ This mirrors the bootstrap used in the official example project.
97
151
 
98
- If you prefer to add KoppaJS to an existing project:
152
+ ---
99
153
 
100
- 1. **Install the core library and Vite plugin:**
154
+ ## Runtime Model
101
155
 
102
- ```bash
103
- pnpm add @koppajs/koppajs-core
104
- pnpm add -D @koppajs/koppajs-vite-plugin
105
- ```
156
+ KoppaJS Core deliberately keeps its top-level contract small:
106
157
 
107
- 2. **Create your first component:**
158
+ - `Core.take(componentSource, name)` registers a component definition
159
+ - `Core.take(pluginOrModule)` installs an extension definition
160
+ - `Core()` initializes the DOM environment and flushes queued registrations
161
+ - repeated `Core()` calls are safe and idempotent
108
162
 
109
- ```typescript
110
- import { Core } from '@koppajs/koppajs-core'
163
+ The runtime does not own `.kpa` parsing. That stays in
164
+ `@koppajs/koppajs-vite-plugin`, which emits the component source objects that
165
+ core consumes at runtime.
111
166
 
112
- Core.take(
113
- {
114
- state: { count: 0 },
115
- methods: {
116
- increment() {
117
- this.state.count++
118
- },
119
- },
120
- },
121
- 'counter',
122
- )
167
+ ---
123
168
 
124
- Core()
125
- ```
169
+ ## Roadmap
126
170
 
127
- 3. **Run your application:**
128
- Use the KoppaJS Vite plugin to build and serve your app.
171
+ - continue hardening the stable runtime contracts
172
+ - keep the public bootstrap surface small and explicit
173
+ - deepen runtime specs and package-level governance documents
174
+ - support ecosystem packages such as the router, component library, and editor
175
+ tooling without growing hidden runtime coupling
129
176
 
130
177
  ---
131
178
 
132
- ## Roadmap
179
+ ## Architecture & Governance
133
180
 
134
- - 🌐 **Official Website** — koppajs.org with documentation, guides, and examples
135
- - 🔌 **Official Plugins**
136
- - Router
137
- - Script Loader
138
- - DSGVO / Cookie Consent Banner
139
- - 🧩 **Ecosystem Growth** — Community plugins, starter templates, and integrations
140
- - 💻 **VS Code Extension** — Syntax highlighting, IntelliSense, and tooling for `.kpa` files
181
+ Project intent, contributor rules, and documentation contracts live in the local repo meta layer:
141
182
 
142
- ---
183
+ - [AI_CONSTITUTION.md](./AI_CONSTITUTION.md)
184
+ - [ARCHITECTURE.md](./ARCHITECTURE.md)
185
+ - [DECISION_HIERARCHY.md](./DECISION_HIERARCHY.md)
186
+ - [DEVELOPMENT_RULES.md](./DEVELOPMENT_RULES.md)
187
+ - [TESTING_STRATEGY.md](./TESTING_STRATEGY.md)
188
+ - [RELEASE.md](./RELEASE.md)
189
+ - [ROADMAP.md](./ROADMAP.md)
190
+ - [CHANGELOG.md](./CHANGELOG.md)
191
+ - [CONTRIBUTING.md](./CONTRIBUTING.md)
192
+ - [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)
193
+ - [docs/specs/README.md](./docs/specs/README.md)
194
+ - [docs/specs/repository-documentation-contract.md](./docs/specs/repository-documentation-contract.md)
195
+ - [docs/meta/README.md](./docs/meta/README.md)
143
196
 
144
- ## Support
197
+ The file-shape contract for `README.md`, `CHANGELOG.md`, `CODE_OF_CONDUCT.md`, and `CONTRIBUTING.md` is defined in [docs/specs/repository-documentation-contract.md](./docs/specs/repository-documentation-contract.md).
145
198
 
146
- For support, visit our [GitHub Issues](https://github.com/koppajs/koppajs-core/issues).
199
+ Run the local document guard before committing:
200
+
201
+ ```bash
202
+ pnpm run check:docs
203
+ ```
147
204
 
148
205
  ---
149
206
 
150
207
  ## Community & Contribution
151
208
 
152
- We welcome contributions! Check out our [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
209
+ Issues and pull requests are welcome:
210
+
211
+ https://github.com/koppajs/koppajs-core/issues
212
+
213
+ Contributor workflow details live in [CONTRIBUTING.md](./CONTRIBUTING.md).
214
+
215
+ Community expectations live in [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md).
216
+
217
+ ---
218
+
219
+ ## License
220
+
221
+ Apache License 2.0 — © 2026 KoppaJS, Bastian Bensch