@logimaxx/kviews.js 1.2.3

package/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Changed
+
+- npm package name is **`@logimaxx/kviews.js`** (renamed from `@logimaxx/kviews`). Install with `npm install @logimaxx/kviews.js`.
+
+## [1.2.1]
+
+### Changed
+
+- **`docs/examples/test.html`** — remade as a posts board demo with a two-column layout (collection + detail), compose form, and local JSON only (no external API).
+- **`docs/examples/demo.css`** — self-contained styles for the example page (replaces Bootstrap in the demo).
+- **`docs/examples/posts.json`** and **`post-1.json`** — JSON:API sample data with authors in `included`, status badges, and excerpts.
+- **`docs/examples/collection.json`** and **`item.json`** — aligned with the posts example model.
+- Removed legacy **`companies.json`** / **`company-1.json`** example files.
+
+## [1.2.0] - 2026-05-20
+
+### Changed
+
+- npm package name is **`@logimaxx/kviews`** (unscoped `kviews` is blocked by npm as too similar to `iview`). Install with `npm install @logimaxx/kviews`.
+- Release checklist script is now **`scripts/release.mjs`** (replaces `scripts/release.sh`).
+
+### Added
+
+- **Data adapters** — pluggable wire-format layer; default remains JSON:API (`adapter: 'jsonapi'`).
+- **`PlainRestAdapter`** — built-in plain REST support via `adapter: 'plain'`.
+- **`JsonApiAdapter`** — existing JSON:API parsing and serialization extracted into the default adapter.
+- **`loadFromRemoteDoc()`** on `Item` — adapter-aware remote load; `loadFromJSONAPIDoc()` deprecated.
+- **`KViews.defaultAdapter`**, **`KViews.registerAdapter()`** — global default and custom adapter registration.
+- Exports: `JsonApiAdapter`, `PlainRestAdapter`, `resolveAdapter`, `registerAdapter`, `setDefaultAdapter`, `getDefaultAdapter`.
+- Documentation: [docs/guides/adapters.md](docs/guides/adapters.md) and API updates for the `adapter` option.
+- **`KViews.defaultHeaders`** (and `apiBaseConfig.defaultHeaders`) for default HTTP headers on every `fetch`.
+- Per-instance **`headers`** and **`ajaxOpts`** for collections and items; documented merge order in `README.md` and `docs/`.
+- **`KViews.basePath`** documented alongside `KViews.baseUrl` for resolving relative request URLs.
+- **`CODE_OF_CONDUCT.md`** and **`SUPPORT.md`**; npm package `files` include community docs.
+- Unit tests for adapters (`tests/unit/adapters.test.js`, `tests/unit/plain-rest-integration.test.js`).
+
+### Fixed
+
+- `createOverlay` returns a valid jQuery chain and uses `document.createElement("div")` for reliable DOM creation.
+- `getRenderContext` includes `type` on flattened relationship objects, consistent with docs and tests.
+- Test jQuery mock: two-argument `.data(key, value)` chains like jQuery even when `value` is `undefined`.
+
+## [1.1.3] - 2026-05-04
+
+### Fixed
+
+- Item update and render-context fixes; test and documentation alignment (see git history for detail).
+
+## [1.1.2] - 2026-05-04
+
+Earlier releases — see git tags and commit history.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,133 @@
+# Contributor Covenant Code of Conduct
+
+## Our pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at the contact
+options listed on [logimaxx.ro](https://logimaxx.ro) or by reaching out to the
+repository maintainers through GitHub. All complaints will be reviewed and
+investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2_1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2_1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

package/CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing to KViews
+
+Thank you for helping improve KViews.
+
+This project follows the [Code of Conduct](./CODE_OF_CONDUCT.md). By participating, you agree to uphold it.
+
+## Development setup
+
+```bash
+git clone https://github.com/logimaxx/kviews.git
+cd kviews
+npm install
+```
+
+## Checks before you open a PR
+
+1. **Tests** — all Vitest tests should pass:
+
+   ```bash
+   npm test
+   ```
+
+2. **Build** — the IIFE bundle should build without errors:
+
+   ```bash
+   npm run build
+   ```
+
+3. **End-to-end tests** (optional locally; CI can be extended to run them):
+
+   ```bash
+   npm run test:e2e
+   ```
+
+## Guidelines
+
+- Match the existing style in the files you touch.
+- Add or update tests for behavior changes.
+- Update user-facing docs (`README.md`, `docs/`) when the public API or install story changes. Any HTML or “quick start” snippet that loads KViews should mention **jQuery** and **Handlebars** as runtime dependencies (load **jQuery → Handlebars → KViews**).
+
+## Pull requests
+
+- One logical change per PR when possible.
+- Describe **what** changed and **why** in the PR description.
+
+## Publishing (maintainers)
+
+See **[RELEASE_FLOW.md](./RELEASE_FLOW.md)** for the full checklist (tests, build, version bump, `CHANGELOG.md`, `npm publish`, tags).
+
+Briefly: `npm publish` runs `prepack`, which runs `npm run build`, so `dist/` in the tarball matches the sources. Bump `package.json` (for example with `npm version patch`) only after `[Unreleased]` in `CHANGELOG.md` is ready for that version.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergiu Voicu, Logimaxx System SRL (https://logimaxx.ro)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,399 @@
+# KViews
+
+[![npm version](https://img.shields.io/npm/v/@logimaxx/kviews.js.svg)](https://www.npmjs.com/package/@logimaxx/kviews.js)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A modern, class-based JavaScript library for binding API data to DOM elements. KViews provides a clean, declarative way to work with REST APIs (JSON:API by default, plain REST via adapters) and render data using Handlebars templates. **Runtime requirements:** [jQuery](https://jquery.com/) (DOM and selectors) and [Handlebars](https://handlebarsjs.com/) (templates); both are `peerDependencies` when you install from npm.
+
+## Features
+
+- ✅ **Class-based architecture** - Modern ES6 classes for better organization
+- ✅ **JSON API support** - Full JSON API specification support (default adapter)
+- ✅ **Plain REST adapter** - Flat JSON APIs via `adapter: 'plain'`
+- ✅ **Template rendering** - Handlebars template support for flexible rendering
+- ✅ **Event system** - Comprehensive event handling for reactivity
+- ✅ **jQuery required** - Uses jQuery exclusively for DOM manipulation
+- ✅ **Filtering** - Built-in form filtering support
+- ✅ **CRUD operations** - Create, Read, Update, Delete support
+- ✅ **Bundle & ES6 modules** - Use as bundle or ES6 modules
+- ✅ **TypeScript ready** - Written in modern JavaScript
+
+## Installation
+
+### npm
+
+```bash
+npm install @logimaxx/kviews.js
+```
+
+ES module import (browser app with your bundler):
+
+```javascript
+import KViews from '@logimaxx/kviews.js';
+// or: import { KViews, Collection, Item, Storage } from '@logimaxx/kviews.js';
+```
+
+Peer dependencies: **Handlebars** and **jQuery** must be installed in your app (`npm install handlebars jquery`).
+
+The **npm tarball** ships **`dist/`** only: `dist/index.js` is the ES module entry (`"main"` / `"exports"`), and `dist/kviews.js` / `dist/kviews.min.js` are IIFE bundles for `<script>` tags. The `src/` tree lives in the git repository for development. `npm publish` runs `prepack`, which runs `npm run build`, so published `dist/` always matches the release.
+
+### Using Bundle (No Build Step Required)
+
+Download `dist/kviews.js` and include it in your HTML:
+
+```html
+<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/handlebars@latest/dist/handlebars.min.js"></script>
+<script src="./dist/kviews.js"></script>
+```
+
+### Using ES6 modules
+
+```bash
+npm install @logimaxx/kviews.js
+```
+
+Use `import` from the `kviews` package (see **Quick Start** below). To hack on the library itself, clone this repo and import from `src/index.js`.
+
+### Requirements
+
+Load **jQuery** before **Handlebars**, then KViews (bundle or your module entry), so globals `$` / `jQuery` and `Handlebars` exist when KViews runs.
+
+- **jQuery** (required) — DOM manipulation and selectors throughout the library (`peerDependency`, typically ^3)
+- **Handlebars** (required) — Template compilation (`peerDependency`, typically ^4)
+- **Modern browser** — ES6 support (Chrome 61+, Firefox 60+, Safari 11+, Edge 16+)
+
+## Quick Start
+
+### Bundle Version
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/handlebars@latest/dist/handlebars.min.js"></script>
+    <script src="./dist/kviews.js"></script>
+</head>
+<body>
+    <div id="posts">
+        <div class="post">
+            <h2>{{title}}</h2>
+            <p>{{content}}</p>
+        </div>
+    </div>
+
+    <script>
+        KViews.createCollectionInstance('#posts', {
+            url: '/api/posts',
+            type: 'posts'
+        });
+    </script>
+</body>
+</html>
+```
+
+### ES6 Modules
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/handlebars@latest/dist/handlebars.min.js"></script>
+</head>
+<body>
+    <div id="posts">
+        <div class="post">
+            <h2>{{title}}</h2>
+            <p>{{content}}</p>
+        </div>
+    </div>
+
+    <script type="module">
+        // With a bundler (Vite, webpack, etc.) after `npm install @logimaxx/kviews.js`:
+        import KViews from '@logimaxx/kviews.js';
+
+        KViews.createCollectionInstance('#posts', {
+            url: '/api/posts',
+            type: 'posts'
+        });
+    </script>
+</body>
+</html>
+```
+
+## Usage Examples
+
+### Collections
+
+```javascript
+// Create a collection
+const collection = KViews.createCollectionInstance('#posts', {
+    url: '/api/posts',
+    type: 'posts',
+    pageSize: 20
+});
+
+// Listen to events
+collection.on('load', (collection) => {
+    log('Loaded', collection.items.length, 'items');
+});
+
+// Add new item
+collection.append({
+    attributes: {
+        title: 'New Post',
+        content: 'Post content'
+    }
+});
+```
+
+### Items
+
+```javascript
+// Create an item
+const item = KViews.createItemInstance('#post-detail', {
+    url: '/api/posts/1',
+    type: 'posts'
+});
+
+// Update item
+item.update({
+    attributes: {
+        title: 'Updated Title'
+    }
+});
+
+// Delete item
+item.delete();
+```
+
+### Form Integration
+
+```javascript
+// Fill form with item data
+KViews.helpers.fillForm('#edit-form', item);
+
+// Capture form submission
+KViews.helpers.captureFormSubmit('#create-form', (formData) => {
+    collection.append({ attributes: formData });
+});
+```
+
+### Filtering
+
+```javascript
+const collection = KViews.createCollectionInstance('#posts', {
+    url: '/api/posts',
+    type: 'posts',
+    filter: '#filter-form'  // Form element for filtering
+});
+```
+
+## API Overview
+
+### KViews (Factory Class)
+
+- `KViews.createCollectionInstance(el, opts)` - Create collection instance
+- `KViews.createItemInstance(el, opts, data)` - Create item instance
+- `KViews.baseUrl` - Prefix for relative request URLs (full origin or any path prefix)
+- `KViews.basePath` - Same role as `baseUrl` when you only need a path prefix; ignored if `baseUrl` is set
+- `KViews.defaultHeaders` - Default HTTP headers merged into every request (e.g. global auth); per-instance `headers` override on duplicate keys
+- `KViews.helpers` - Utility functions (fillForm, captureFormSubmit, fetchFormData)
+
+### HTTP: URLs and headers
+
+Relative `url` values are resolved with `KViews.baseUrl` or `KViews.basePath` before `fetch`. Absolute `http(s)://` URLs are left unchanged.
+
+Default headers apply app-wide; each collection or item can add or override headers via the `headers` option (and optional `ajaxOpts` for lower-level `Storage` defaults). Merge order is: **global `defaultHeaders` → instance / `Storage` defaults → per-request overrides** (later wins on the same header name).
+
+```javascript
+KViews.defaultHeaders = { Authorization: 'Bearer ' + token };
+
+KViews.createCollectionInstance('#posts', {
+    url: '/api/posts',
+    type: 'posts',
+    headers: { 'X-Request-Id': crypto.randomUUID() }
+});
+```
+
+With jQuery, `$.fn.kviews.baseUrl`, `basePath`, and `defaultHeaders` mirror the `KViews` static properties.
+
+### Collection
+
+- `loadFromRemote()` - Load data from API
+- `append(itemData)` - Add new item
+- `render()` - Render collection
+- `on(event, callback)` - Event listeners
+- `items` - Array of Item instances
+
+### Item
+
+- `loadFromRemote()` - Load item from API
+- `update(data)` - Update item
+- `delete()` - Delete item
+- `render()` - Render item
+- `on(event, callback)` - Event listeners
+
+## Contributing, support, and security
+
+We welcome issues and pull requests.
+
+- **[CONTRIBUTING.md](./CONTRIBUTING.md)** — setup, tests, build, PR expectations  
+- **[SUPPORT.md](./SUPPORT.md)** — where to ask questions and report bugs  
+- **[CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)** — community guidelines  
+- **[SECURITY.md](./SECURITY.md)** — **private** vulnerability reporting  
+- **[CHANGELOG.md](./CHANGELOG.md)** — release notes  
+- **[RELEASE_FLOW.md](./RELEASE_FLOW.md)** — checklist for maintainers cutting a release  
+
+## GitHub Pages
+
+This repo includes a static site in [`website/`](./website/) (landing page, **live collection demo** that loads [`website/data/posts.json`](./website/data/posts.json), and a minimal bundle check page). The workflow [`.github/workflows/pages.yml`](.github/workflows/pages.yml) runs tests, builds `dist/`, copies `kviews.js` / `kviews.min.js` into `website/dist/`, and deploys to **GitHub Pages**.
+
+**One-time setup in the GitHub repo**
+
+1. Open **Settings → Pages**.
+2. Under **Build and deployment**, set **Source** to **GitHub Actions** (not “Deploy from a branch”).
+3. Push to `main` or `master` (or run the **Deploy GitHub Pages** workflow manually from the Actions tab).
+
+The site will be available at **`https://logimaxx.github.io/kviews/`** (replace `logimaxx` with your user or org name if different). The first deploy may ask you to approve the **github-pages** environment.
+
+## Documentation
+
+Comprehensive documentation is available in the [`docs/`](./docs/) directory:
+
+- **[API Reference](./docs/api/)** — class and method reference  
+- **[User guides](./docs/guides/)** — step-by-step tutorials ([adapters](./docs/guides/adapters.md) for JSON:API vs plain REST)
+- **[Examples](./docs/examples/)** — sample HTML and JSON:API payloads
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/logimaxx/kviews.git
+cd kviews
+
+npm install
+```
+
+### Build
+
+```bash
+# Build bundle (normal + minified)
+npm run build
+```
+
+This creates:
+- `dist/kviews.js` - Normal bundle with sourcemap
+- `dist/kviews.min.js` - Minified bundle
+
+### Testing
+
+```bash
+# Run unit tests
+npm run test
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run with coverage
+npm run test:coverage
+
+# Run E2E tests
+npm run test:e2e
+
+# Run all tests
+npm run test:all
+```
+
+### Development Server
+
+```bash
+# Python
+npm run serve:python
+
+# PHP
+npm run serve:php
+
+# Node.js
+npm run serve:node
+```
+
+## Project Structure
+
+```
+kviews.js/
+├── src/                  # Source code
+│   ├── KViews.js        # Main factory class
+│   ├── Item.js          # Item class
+│   ├── Collection.js     # Collection class
+│   ├── Storage.js        # HTTP operations
+│   ├── URL.js            # URL parsing
+│   ├── utilities.js      # Utility functions
+│   └── ...
+├── dist/                 # Built bundles
+├── docs/                 # Documentation
+│   ├── api/             # API reference
+│   ├── guides/          # User guides
+│   └── examples/        # Code examples
+├── tests/                # Test suite
+│   ├── unit/            # Unit tests
+│   ├── integration/     # Integration tests
+│   └── e2e/             # End-to-end tests
+└── build.js             # Build script
+```
+
+## Browser support
+
+- **ES modules** (`import … from '@logimaxx/kviews.js'` via a bundler): evergreen browsers aligned with baseline ES modules (approx. Chrome 61+, Firefox 60+, Safari 11+, Edge 16+).
+
+- **IIFE bundle** (`dist/kviews.js`): same modern JavaScript assumptions as the build (see `build.js`). Very old browsers (for example IE 11) are **not** a supported target unless you fork and downgrade the toolchain; use an evergreen browser or upgrade client environments.
+
+## JSON API Format
+
+KViews expects data in JSON API format:
+
+```json
+{
+  "data": {
+    "id": "1",
+    "type": "posts",
+    "attributes": {
+      "title": "Post Title",
+      "content": "Post content"
+    },
+    "relationships": {
+      "author": {
+        "data": {
+          "id": "123",
+          "type": "users"
+        }
+      }
+    }
+  }
+}
+```
+
+## License
+
+This project is licensed under the MIT License — see [LICENSE](./LICENSE).
+
+## Changelog
+
+Version history and migration notes live in **[CHANGELOG.md](./CHANGELOG.md)**.
+
+## Support
+
+See **[SUPPORT.md](./SUPPORT.md)** for documentation links, GitHub issues, and security reporting.
+
+## Acknowledgments
+
+- Built with modern JavaScript (ES6+)
+- Uses [jQuery](https://jquery.com/) for DOM APIs and [Handlebars](https://handlebarsjs.com/) for templating
+- Inspired by modern data-binding patterns
+
+---
+
+Created to tame complexity: code cleaner, work less.

package/SECURITY.md

@@ -0,0 +1,13 @@
+# Security
+
+If you believe you have found a security vulnerability in KViews, please report it responsibly.
+
+**Preferred:** use [GitHub private vulnerability reporting](https://github.com/logimaxx/kviews/security/advisories/new) for this repository, if enabled.
+
+Otherwise, open a **private** security advisory or contact the maintainers through the contact options listed on the [Logimaxx](https://logimaxx.ro) site or your existing support channel with the organization—please do **not** file public issues for undisclosed vulnerabilities.
+
+Include steps to reproduce, affected versions, and impact if you can. Maintainers will acknowledge reputable reports when possible and coordinate fixes and disclosure.
+
+## Disclosure policy
+
+Please keep vulnerability details non-public until a fix or mitigation is agreed. Coordinate through private channels linked above—not through public GitHub issues.