@koppajs/koppajs-core 3.0.2 → 3.0.3
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.
- package/CHANGELOG.md +24 -0
- package/README.md +137 -79
- package/dist/index.cjs.js.map +1 -1
- package/dist/index.es.js.map +1 -1
- package/dist/utils/helper.d.ts +1 -1
- package/package.json +13 -11
package/CHANGELOG.md
CHANGED
|
@@ -22,6 +22,30 @@ Changes will only appear here when they:
|
|
|
22
22
|
|
|
23
23
|
---
|
|
24
24
|
|
|
25
|
+
## [3.0.3] — Tooling Baseline And Ecosystem Cleanup
|
|
26
|
+
|
|
27
|
+
**2026-03-26**
|
|
28
|
+
|
|
29
|
+
Patch release to tighten repository quality workflow, align ecosystem-facing
|
|
30
|
+
docs, and harden a small helper type contract. No intentional breaking runtime
|
|
31
|
+
changes.
|
|
32
|
+
|
|
33
|
+
### Added
|
|
34
|
+
|
|
35
|
+
- Added repository meta-layer documents, ADR/spec directories, and explicit
|
|
36
|
+
contributor workflow guidance
|
|
37
|
+
|
|
38
|
+
### Changed
|
|
39
|
+
|
|
40
|
+
- Tightened `setValueByPath(...)` typing without widening runtime behavior
|
|
41
|
+
- Split source and test TypeScript checks and hardened coverage thresholds
|
|
42
|
+
- Simplified lint, format, hook, and CI workflow configuration around the
|
|
43
|
+
current repository baseline
|
|
44
|
+
- Updated README ecosystem links to point at the released starter/tooling
|
|
45
|
+
surface
|
|
46
|
+
|
|
47
|
+
---
|
|
48
|
+
|
|
25
49
|
## [3.0.2] — Public API Cleanup
|
|
26
50
|
|
|
27
51
|
**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>
|
|
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
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
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
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
28
|
+
<p align="center">
|
|
29
|
+
<a href="https://github.com/koppajs/koppajs-documentation">Documentation</a>
|
|
30
|
+
·
|
|
31
|
+
<a href="https://github.com/koppajs/create-koppajs">create-koppajs</a>
|
|
32
|
+
·
|
|
33
|
+
<a href="https://github.com/koppajs/koppajs-vite-plugin">Vite Plugin</a>
|
|
34
|
+
·
|
|
35
|
+
<a href="https://github.com/koppajs/koppajs-router">Router</a>
|
|
36
|
+
·
|
|
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
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
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
|
-
|
|
63
|
+
`@koppajs/koppajs-core` is the runtime package at the center of the KoppaJS
|
|
64
|
+
stack.
|
|
59
65
|
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
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
|
-
-
|
|
69
|
-
-
|
|
70
|
-
-
|
|
71
|
-
|
|
72
|
-
-
|
|
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
|
-
|
|
128
|
+
Recommended bootstrap path:
|
|
79
129
|
|
|
80
130
|
```bash
|
|
81
131
|
pnpm create koppajs my-app
|
|
@@ -84,69 +134,77 @@ pnpm install
|
|
|
84
134
|
pnpm dev
|
|
85
135
|
```
|
|
86
136
|
|
|
87
|
-
|
|
137
|
+
Manual registration with the public core API:
|
|
88
138
|
|
|
89
|
-
|
|
139
|
+
```ts
|
|
140
|
+
import { Core } from '@koppajs/koppajs-core'
|
|
90
141
|
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
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
|
-
|
|
150
|
+
This mirrors the bootstrap used in the official example project.
|
|
97
151
|
|
|
98
|
-
|
|
152
|
+
---
|
|
99
153
|
|
|
100
|
-
|
|
154
|
+
## Runtime Model
|
|
101
155
|
|
|
102
|
-
|
|
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
|
-
|
|
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
|
-
|
|
110
|
-
|
|
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
|
-
|
|
113
|
-
{
|
|
114
|
-
state: { count: 0 },
|
|
115
|
-
methods: {
|
|
116
|
-
increment() {
|
|
117
|
-
this.state.count++
|
|
118
|
-
},
|
|
119
|
-
},
|
|
120
|
-
},
|
|
121
|
-
'counter',
|
|
122
|
-
)
|
|
167
|
+
---
|
|
123
168
|
|
|
124
|
-
|
|
125
|
-
```
|
|
169
|
+
## Roadmap
|
|
126
170
|
|
|
127
|
-
|
|
128
|
-
|
|
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
|
-
##
|
|
179
|
+
## Architecture & Governance
|
|
180
|
+
|
|
181
|
+
Project intent, runtime constraints, and contributor rules live in the repo
|
|
182
|
+
meta layer:
|
|
183
|
+
|
|
184
|
+
- [AI_CONSTITUTION.md](./AI_CONSTITUTION.md)
|
|
185
|
+
- [ARCHITECTURE.md](./ARCHITECTURE.md)
|
|
186
|
+
- [DECISION_HIERARCHY.md](./DECISION_HIERARCHY.md)
|
|
187
|
+
- [DEVELOPMENT_RULES.md](./DEVELOPMENT_RULES.md)
|
|
188
|
+
- [TESTING_STRATEGY.md](./TESTING_STRATEGY.md)
|
|
189
|
+
- [RELEASE.md](./RELEASE.md)
|
|
190
|
+
- [ROADMAP.md](./ROADMAP.md)
|
|
191
|
+
- [docs/specs/component-runtime-contract.md](./docs/specs/component-runtime-contract.md)
|
|
192
|
+
- [docs/architecture/runtime-flow.md](./docs/architecture/runtime-flow.md)
|
|
133
193
|
|
|
134
|
-
|
|
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
|
|
194
|
+
Tagged releases are documented in `CHANGELOG.md`.
|
|
141
195
|
|
|
142
196
|
---
|
|
143
197
|
|
|
144
|
-
##
|
|
198
|
+
## Community & Contribution
|
|
199
|
+
|
|
200
|
+
Issues and pull requests are welcome:
|
|
145
201
|
|
|
146
|
-
|
|
202
|
+
https://github.com/koppajs/koppajs-core/issues
|
|
203
|
+
|
|
204
|
+
Contributor workflow details live in [CONTRIBUTING.md](./CONTRIBUTING.md).
|
|
147
205
|
|
|
148
206
|
---
|
|
149
207
|
|
|
150
|
-
##
|
|
208
|
+
## License
|
|
151
209
|
|
|
152
|
-
|
|
210
|
+
Apache License 2.0 — © 2026 KoppaJS, Bastian Bensch
|