@koppajs/koppajs-core 3.0.0

package/CHANGELOG.md

@@ -0,0 +1,153 @@
+# Change Log
+
+All notable changes to **@koppajs/koppajs-core** 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]
+
+This section is intentionally empty.
+
+Changes will only appear here when they:
+
+- affect runtime behavior,
+- change documented guarantees,
+- or modify the public API surface.
+
+---
+
+## [3.0.0] — Baseline Runtime Release
+
+**2026-03-01**
+
+This release establishes the **stable runtime foundation of KoppaJS**.
+
+It defines the final component model, lifecycle semantics, reactivity rules,
+and architectural boundaries that KoppaJS is built upon.
+
+From this version onward, the core runtime is considered **intentionally
+defined and stable**, with changes happening only through explicit,
+well-justified releases.
+
+---
+
+### Architecture
+
+- Fully **class-free, factory-free, and virtual-DOM-free** runtime design
+- Component system built directly on **native Web Components**
+- No hidden lifecycle phases or implicit execution paths
+- Clear separation of responsibilities across runtime modules
+- Explicit teardown and cleanup semantics
+
+---
+
+### Component Model & Lifecycle
+
+- Deterministic lifecycle with explicit hooks:
+  - `created`
+  - `processed`
+  - `beforeMount`
+  - `mounted`
+  - `beforeUpdate`
+  - `updated`
+  - `beforeDestroy`
+  - `destroyed`
+- No implicit lifecycle execution
+- Guaranteed cleanup of:
+  - watchers
+  - reactive effects
+  - event listeners
+- Predictable registration and destruction flow
+
+---
+
+### Reactivity & Data Flow
+
+- Proxy-based reactive state model
+- Referential prop binding (`:prop="state.value"`)
+  - Parent and child share the same reference
+  - Updates propagate through explicit observation
+- No deep or implicit reactivity magic
+- Rendering is triggered only by intentional, observable state changes
+
+---
+
+### Template & Rendering
+
+- Inline template directives:
+  - `loop`
+  - `if` / `else`
+  - `ref`
+  - `slot`
+- Text and attribute interpolation via `{{ expression }}`
+- Declarative slot system for composition
+- Direct DOM reconciliation (no virtual DOM diffing)
+
+---
+
+### Event System
+
+- Custom event handling with:
+  - bubbling support
+  - scoped delegation
+- Automatic listener cleanup on component destruction
+- No global event leakage
+
+---
+
+### Typing & Contracts
+
+- Strong typing throughout the runtime
+- `satisfies`-based validation for internal structures
+- Dedicated TypeScript configuration for public type generation
+- Global type declarations (`globals.d.ts`, `kpa.d.ts`) intentionally provided
+  for editor integration and DX
+- Clear separation between public API contracts and internal implementation types
+
+---
+
+### Tooling & Quality
+
+- pnpm-based project setup
+- Deterministic dependency resolution via committed lockfile
+- Vite-based build pipeline:
+  - typecheck
+  - bundle
+  - type generation
+- ESLint (flat config) and Prettier enforced
+- Vitest test suite following the **KoppaJS “Three Test Rule”**
+
+---
+
+### Guarantees
+
+Starting with `3.0.0`, the following guarantees apply:
+
+- **Explicit runtime behavior**
+- **No hidden global state**
+- **Deterministic lifecycle execution**
+- **Predictable reactivity and rendering**
+- **Stability over feature velocity**
+
+---
+
+### Non-Goals
+
+- No virtual DOM
+- No implicit runtime magic
+- No auto-registration side effects
+- No framework-level convenience abstractions
+- No hidden global mutations
+
+---
+
+## [0.0.0] — Initial Development Phase
+
+Experimental and exploratory development phase.
+No stability or API guarantees.

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Bastian Bensch
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,152 @@
+<a id="readme-top"></a>
+
+<!-- PROJECT LOGO -->
+<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>
+
+<!-- PROJECT SHIELDS -->
+<div align="center">
+  <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://bundlephobia.com/package/@koppajs/koppajs-core"><img src="https://img.shields.io/bundlephobia/minzip/@koppajs/koppajs-core?style=flat-square" alt="Bundle size"></a> <a href="./LICENSE"><img src="https://img.shields.io/github/license/koppajs/koppajs-core?style=flat-square" alt="License"></a>
+</div>
+
+<br>
+
+<!-- ELEVATOR PITCH -->
+<div align="center">
+	<h1 align="center">KoppaJS – Pragmatic frontend made modular</h1>
+	<h3 align="center">Build fast, simple, and growable – without the noise of modern frameworks.</h3>
+	<p align="center">
+		<i align="center">A quiet rebellion against complexity – and a wish that building can still feel good.</i>
+	</p>
+</div>
+
+<br>
+
+<!-- IMPORTANT LINKS -->
+<div align="center">
+	<p align="center">
+		<a href="https://github.com/koppajs/koppajs-documentation">Documentation</a>
+		&middot;
+		<a href="https://github.com/koppajs/koppajs-example">Example Project</a>
+		&middot;
+		<a href="https://github.com/koppajs/koppajs-core/issues">Issues</a>
+	</p>
+</div>
+
+<br>
+
+<!-- TABLE OF CONTENTS -->
+<details>
+<summary>Table of Contents</summary>
+	<ol>
+		<li><a href="#what-is-koppajs">What is KoppaJS?</a></li>
+		<li><a href="#features">Features</a></li>
+		<li><a href="#getting-started">Getting Started</a></li>
+		<li><a href="#roadmap">Roadmap</a></li>
+		<li><a href="#support">Support</a></li>
+		<li><a href="#community--contribution">Community & Contribution</a></li>
+	</ol>
+</details>
+
+---
+
+## What is KoppaJS?
+
+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:
+
+- **Simplicity:** Minimal boilerplate and intuitive APIs.
+- **Performance:** Optimized for speed and scalability.
+- **Modularity:** Build only what you need, when you need it.
+
+---
+
+## Features
+
+- **Declarative Components:** Define components with `.kpa` files.
+- **Reactive State Management:** Built-in reactivity for seamless updates.
+- **Lifecycle Hooks:** Control component behavior with hooks like `mounted`, `updated`, and `beforeUpdate`.
+- **Integration-Friendly:** Works with existing tools and libraries.
+- **TypeScript Support:** First-class TypeScript support for safer, more maintainable code.
+
+---
+
+## Getting Started
+
+The fastest way to start a new KoppaJS project:
+
+```bash
+pnpm create koppajs my-app
+cd my-app
+pnpm install
+pnpm dev
+```
+
+This scaffolds a ready-to-run project with Vite, TypeScript, and two sample components.
+
+You can also use npm or npx:
+
+```bash
+npm create koppajs my-app
+npx create-koppajs my-app
+```
+
+### Manual Setup
+
+If you prefer to add KoppaJS to an existing project:
+
+1. **Install the core library and Vite plugin:**
+
+   ```bash
+   pnpm add @koppajs/koppajs-core
+   pnpm add -D @koppajs/koppajs-vite-plugin
+   ```
+
+2. **Create your first component:**
+
+   ```typescript
+   import { Core } from '@koppajs/koppajs-core'
+
+   Core.take(
+     {
+       state: { count: 0 },
+       methods: {
+         increment() {
+           this.state.count++
+         },
+       },
+     },
+     'counter',
+   )
+
+   Core()
+   ```
+
+3. **Run your application:**
+   Use the KoppaJS Vite plugin to build and serve your app.
+
+---
+
+## Roadmap
+
+- 🌐 **Official Website** — koppajs.org with documentation, guides, and examples
+- 🔌 **Official Plugins**
+  - Router
+  - Script Loader
+  - DSGVO / Cookie Consent Banner
+- 🧩 **Ecosystem Growth** — Community plugins, starter templates, and integrations
+- 💻 **VS Code Extension** — Syntax highlighting, IntelliSense, and tooling for `.kpa` files
+
+---
+
+## Support
+
+For support, visit our [GitHub Issues](https://github.com/koppajs/koppajs-core/issues).
+
+---
+
+## Community & Contribution
+
+We welcome contributions! Check out our [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.

package/dist/component.d.ts

@@ -0,0 +1,29 @@
+import { type ComponentSource, type Props } from './types';
+/**
+ * Processes slot elements in component template.
+ * Replaces <slot> elements with content from host element.
+ * @param container - Template fragment containing slot elements
+ * @param host - Host element containing slot content
+ */
+export declare function processSlots({ container, host, }: {
+    container: DocumentFragment;
+    host: HTMLElement;
+}): void;
+/**
+ * Validates a prop value against its definition.
+ * @param propName - Name of the prop
+ * @param propValue - Value to validate
+ * @param props - Props definition object
+ * @returns True if prop is valid, false otherwise
+ */
+export declare function validateProp({ propName, propValue, props, }: {
+    propName: string;
+    propValue: unknown;
+    props: Props;
+}): boolean;
+/**
+ * Registers a component with the custom elements registry.
+ * @param componentName - Custom element tag name
+ * @param source - Component source with template, script, and style
+ */
+export declare function registerComponent(componentName: string, source: ComponentSource): void;

package/dist/compose.d.ts

@@ -0,0 +1,11 @@
+import { ComposeOptions } from './types';
+/**
+ * Composes multiple objects into a single Proxy that delegates property access.
+ * Properties are read from the first layer that contains them.
+ * Writes go to the layer where the property exists, or to defaultWriteIndex if not found.
+ * @param layers - Array of objects to compose
+ * @param options - Composition options
+ * @returns Proxy object that combines all layers
+ * @throws Error if layers is empty or contains invalid objects
+ */
+export declare function composeBySource<T extends object[]>(layers: T, options?: ComposeOptions): T[number];

package/dist/event-handler.d.ts

@@ -0,0 +1,40 @@
+import type { State, Events, Refs, Methods } from './types';
+/**
+ * Sets up custom event listeners for component events.
+ * Handles window events, selector-based events, and ref-based events.
+ * Returns a cleanup function that removes all listeners added by this call.
+ * @param userContext - User context to bind handlers to
+ * @param events - Array of event definitions
+ * @param container - Document fragment to query selectors from
+ * @param refs - Component element references
+ * @returns Cleanup function that removes all listeners added by this call
+ */
+export declare function setupEvents(userContext: State, events: Events, container: DocumentFragment, refs: Refs): () => void;
+/**
+ * Binds native DOM event handlers from element attributes (e.g., onclick, oninput).
+ * Walks all elements once instead of querying per event type for better performance.
+ * Handlers are retrieved from userContext and assumed to be already bound (for options type).
+ * @param userContext - User context containing event handlers
+ * @param fragment - Document fragment to process
+ */
+export declare function bindNativeEvents(userContext: State, fragment: DocumentFragment): void;
+/**
+ * Binds native DOM event handlers for composite component type.
+ * Walks all elements once instead of querying per event type for better performance.
+ * Handlers are retrieved directly from methods object without binding.
+ * @param methods - Methods object containing event handlers
+ * @param fragment - Document fragment to process
+ */
+export declare function bindNativeEventsForComposite(methods: Methods, fragment: DocumentFragment): void;
+/**
+ * Sets up custom event listeners for composite component type.
+ * Handlers are bound to state using bindOnce.
+ * Returns a cleanup function that removes all listeners added by this call.
+ * @param methods - Methods object (unused, kept for signature consistency)
+ * @param state - Component state to bind handlers to
+ * @param events - Array of event definitions
+ * @param container - Document fragment to query selectors from
+ * @param refs - Component element references
+ * @returns Cleanup function that removes all listeners added by this call
+ */
+export declare function setupEventsForComposite(methods: Methods, state: State, events: Events, container: DocumentFragment, refs: Refs): () => void;

package/dist/global-event-cleaner.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Patches EventTarget.prototype.addEventListener/removeEventListener
+ * to globally track registered listeners.
+ *
+ * This only runs when EventTarget exists (browser/JSDOM).
+ * In Node/SSR it is a safe no-op.
+ */
+export declare function patchGlobalEventTracking(): void;
+/**
+ * Removes all listeners registered on a specific EventTarget.
+ */
+export declare function cleanupAllEventListeners(target: EventTarget): void;
+/**
+ * Recursively cleans up all event listeners in a DOM subtree.
+ * This is only active in environments where DOM APIs exist.
+ */
+export declare function cleanupSubtree(root: Node): void;
+/**
+ * Starts a global MutationObserver that automatically cleans up
+ * event listeners from removed DOM elements.
+ *
+ * In SSR/Node environments this function is a safe no-op.
+ */
+export declare function startGlobalDisconnectionObserver(): void;
+/**
+ * Stops the global observer (useful in tests).
+ */
+export declare function stopGlobalDisconnectionObserver(): void;