@node-k/qr

Gefaste, zweifarbige QR-Codes im node·K-Look — als ES-Modul (client- und serverseitig) und als Web Component. Offline, ohne Backend, ohne Tracking.

Schnellstart

Vollwertiges QR-Tool: strukturierte Inhaltstypen (URL/WLAN/vCard/SEPA/…), Logo, echter In-Browser-Decode-Test, Export (SVG/PNG/JPG/PDF/EPS, Batch-ZIP), CTA-Frame + Druckvorstufe. Kein Build, keine Abhängigkeiten — reine ES-Module.

git clone https://git.node-k.at/the.true.fox/node-K_QR.git
cd node-K_QR
npm start            # startet einen statischen Server auf Port 5173
# Browser: http://localhost:5173/app/

Klick-to-Start (macOS): Im Finder auf node-K-QR.command doppelklicken — startet den lokalen Server und öffnet den Generator im Browser (Fenster offen lassen; Schließen beendet ihn).

ES-Module brauchen einen Server — app/index.html nicht per Doppelklick (file://) öffnen, sondern über npm start, den .command-Launcher oder einen beliebigen statischen Server. Alles Weitere (Fonts, Icon, jsQR) ist mit-committet → 100 % offline.

In eine Webseite einbinden:

<script type="module" src="/pfad/zu/src/nodek-qr.js"></script>
<nodek-qr content="https://node-k.at"></nodek-qr>

Aufbau

Datei	Zweck
src/qrcode-core.js	QR-Engine (gevendortes qrcode.js © Kazuhiko Arase, MIT), als ESM, UTF-8-Default.
src/microqr-core.js	Eigener Micro-QR-Encoder (M1–M4) nach ISO/IEC 18004, bit-für-bit gegen qrencode -M verifiziert.
src/styled-qr.js	renderStyledQR(opts) + renderMicroStyled(opts) → { svg, moduleCount, version }. DOM-frei.
src/content-types.js	Strukturierte Inhalte: URL, WLAN, vCard, E-Mail, SMS, Tel, Geo, Termin (.ics), ICS-Import, SEPA.
src/scannability.js	Decode-Test (jsQR) + Scannability-Score.
src/config.js	Konfig-Serialisierung, Konfig-als-URL, Preset-Store.
src/export.js	Export SVG/PNG/JPG/PDF/EPS, beliebige Größen, Batch-ZIP.
src/zip.js	Minimaler ZIP-Writer (STORE), für Batch-Download.
src/frame.js	CTA-Frame (gefaste Ecken + Banner-Text), als Geometrie.
src/print.js	Druck-Anschnitt (Bleed) + Schnittmarken, als Geometrie.
src/nodek-qr.js	Web Component <nodek-qr>.
src/embed.js	Headless-Factory createGenerator(fixed) / defineGenerator (fixe Settings, keine UI).
app/index.html	Tool-Oberfläche: gestaffelter Editor (01–05) + sticky Live-Vorschau.

Einbindung in die Webseite

<script type="module" src="/assets/nodek-qr.js"></script>

<nodek-qr content="https://node-k.at"></nodek-qr>

<nodek-qr type="wifi"
  fields='{"ssid":"node-K","password":"…","encryption":"WPA"}'></nodek-qr>

<nodek-qr content="https://node-k.at" frame="SCAN ME"></nodek-qr>

Attribute

Attribut	Default	Beschreibung
content	—	Roh-Text/URL (wenn kein type).
type	text	url, wifi, vcard, email, sms, tel, geo, event, sepa.
fields	—	JSON mit den Feldern des Typs (oder .fields-Property).
ecc	typabhängig	L / M / Q / H.
qz	4	Quiet Zone (Module).
mod-chamfer	0.4	Fase Datenmodule.
finder-bevel	0.35	Fase Finder.
module-size	18	SVG-Einheiten pro Modul.
data-color	#00baba	Module + Finder-Kern.
ring-color	#fbaa2b	Finder-Rahmen.
bg	#171717	Hintergrund.
include-bg	true	false = freigestellt.
logo	—	Bild-URL / Data-URL; mittig, Module darunter ausgestanzt.
logo-scale	0.2	Logo-Breite als Anteil der Datenfläche.
logo-pad	0.4	Rand ums Logo (Module) für das Plate.
logo-shape	rounded	rounded / square / circle.
logo-plate	auto	Plattenfarbe; auto = bg, none = keine.
auto-ecc	true	Bei Logo Redundanz automatisch auf ≥ Q anheben.
validate	—	Vorhanden = nach jedem Render Decode-Test, feuert scannability.
frame	—	Vorhanden = CTA-Frame; Wert = Banner-Text (leer → „SCAN ME").
frame-color	Ring-Farbe	Rahmen + Banner.
frame-text-color	#141414	Textfarbe im Banner.
frame-bg	QR-Bg	Kartenhintergrund.
frame-position	bottom	bottom / top.
frame-font	mono	mono / sans (SVG/Raster); PDF/EPS nutzen Helvetica-Bold.
print-marks	—	Vorhanden = Anschnitt (Bleed) + Schnittmarken.
bleed	0.05	Anschnitt als Anteil der QR-Seite.
mark-length	0.06	Länge der Schnittmarken (Anteil der QR-Seite).
mark-color	#111111	Farbe der Schnittmarken.
micro	—	Vorhanden = Micro-QR (M1–M4, ein Finder) statt Standard-QR. Siehe unten.
micro-version	auto	1–4 (= M1…M4) erzwingen; sonst kleinste passende.
micro-ecc	auto	L / M / Q (versionsabhängig; M1 nur ohne, M4 bis Q).

JS-API

const el = document.querySelector('nodek-qr');
el.toSVG();        // aktueller SVG-String
el.metadata;       // { moduleCount, version }
el.addEventListener('render', e => console.log(e.detail));

// Echter Decode-Test (lädt jsQR lazy nach):
const report = await el.checkScannability();
// → { score, rating, decoded, matches, robustness, contrast, warnings, … }

// Konfiguration lesen/anwenden (Presets, Konfig-als-URL):
const cfg = el.getConfig();   // { type, content, fields, ecc, …, logo*, autoEcc }
el.applyConfig({ dataColor: '#141414', bg: '#ffffff' });   // partiell

// Export: ein Format×Größe → Einzeldownload, mehrere → ein ZIP:
await el.exportTo({ formats: ['svg','png','pdf'], sizes: [256, 1024], includeBg: true });
await el.exportTo({ formats: ['png'], sizes: [16, 32, 64] });   // Icon-Set

Micro-QR (M1–M4)

Kompaktere Symbole mit nur einem Finder (11×11 bis 17×17 Module), node·K-gestylt wie der Standard-QR. Encoder nach ISO/IEC 18004, bit-für-bit gegen qrencode -M verifiziert.

<nodek-qr micro content="12345"></nodek-qr>                    <!-- kleinste passende Version -->
<nodek-qr micro micro-version="4" micro-ecc="L" content="HELLO"></nodek-qr>

Version	Größe	Modi	max. Kapazität (ECC)
M1	11×11	nur numerisch	5 Ziffern (nur ohne ECC)
M2	13×13	num. / alphanum.	10 Ziffern · 6 alphanum. (L/M)
M3	15×15	+ Byte	23 Ziffern · 14 alphanum. · 9 Byte (L/M)
M4	17×17	+ Byte	35 Ziffern · 21 alphanum. · 15 Byte (L/M/Q)

Grenzen — bitte beachten:

• Winzige Kapazität. Für URLs, WLAN, vCard oder .ics zu klein (M4 ≤ 15 Byte). Gedacht für kurze IDs, Teile-/Seriennummern, numerische Codes.
• Scanner-Unterstützung. Micro-QR wird von vielen Handy-Kameras nicht zuverlässig gelesen. Vor Produktiveinsatz auf den Zielgeräten gegentesten.
• Kein In-Browser-Decode-Test. jsQR liest kein Micro-QR → die Scannability-Prüfung entfällt (die App zeigt stattdessen einen Hinweis). Die Encoder-Korrektheit ist dafür per Referenz-Oracle (qrencode) in der Test-Suite abgesichert.

Programmatisch (ohne DOM, z. B. Server)

import { renderStyledQR, renderMicroStyled } from '@node-k/qr';
import { encodeContent } from '@node-k/qr/content-types';

const { svg } = renderStyledQR({ text: encodeContent('wifi', { ssid: 'node-K', password: '…' }) });
const { svg: micro } = renderMicroStyled({ text: 'AC-42', microVersion: 2, microEcc: 'L' });

Headless einbetten (fixierte Einstellungen, ohne UI)

Für die direkte Einbettung in Anwendungen/Apps: Stil einmal festlegen, danach nur noch Inhalt reingeben. createGenerator(fixed) liefert eine Funktion content → { svg, geometry, … }.

import { createGenerator } from '@node-k/qr/embed';

// Stil fixieren (inkl. optional logo, frame, print):
const qr = createGenerator({
  dataColor: '#00baba', ringColor: '#fbaa2b', bg: '#171717', ecc: 'Q',
  frame: 'SCAN ME',
});

el.innerHTML = qr('https://node-k.at').svg;                       // URL
el.innerHTML = qr(null, { type: 'wifi', fields: { ssid: 'node-K', password: '…' } }).svg;
el.innerHTML = qr('…', { overrides: { dataColor: '#ff0000' } }).svg;  // pro Aufruf übersteuern

// Micro-QR: entweder im fixen Stil (micro: true) oder pro Aufruf:
const mqr = createGenerator({ micro: true, microVersion: 4, microEcc: 'L' });
el.innerHTML = mqr('HELLO').svg;
el.innerHTML = qr('12345', { micro: true }).svg;                  // Standard-Generator, Micro erzwingen

Als vorkonfiguriertes Custom-Element (Entwickler setzt nur noch content):

import { defineGenerator } from '@node-k/qr/embed';
defineGenerator('meine-qr', { dataColor: '#00baba', frame: 'SCAN ME' });

<meine-qr content="https://node-k.at"></meine-qr>

Die App (app/) hat unter 06 · Einbetten einen Code-Export aus den aktuellen Einstellungen: die Snippets oben (Web Component · createGenerator · Konfig-JSON) und einen Button „Generator (.js)", der Engine + Renderer (inkl. Micro-QR) + fixe Config in eine self-contained Datei (nodek-qr-headless.js, ~92 KB, keine Abhängigkeiten) bündelt:

import generate from './nodek-qr-headless.js';
el.innerHTML = generate('https://node-k.at').svg;

Oberfläche lokal starten

npm start      # http://localhost:5173/app/

Tests

Abhängigkeitsfrei über Nodes eingebauten Test-Runner (Node ≥ 18):

npm test       # node --test → test/*.test.mjs

Deckt die DOM-freie Kernlogik ab: Inhaltstypen (inkl. .ics/SEPA-Regressionen), Renderer + Geometrie, Micro-QR (4 qrencode-Referenzmatrizen), Konfig-Roundtrip, Frame/Print, ZIP, Headless-createGenerator (inkl. Micro), PDF/EPS/SVG-Export. Läuft in der CI als Gate vor dem npm-Publish (.forgejo/workflows/package.yml). Canvas-abhängige Teile (PNG/JPG-Raster, Decode-Test, Web-Component) werden im Browser geprüft.

Export

exportTo({ formats, sizes, includeBg, baseName }) bzw. exportBatch(...) aus export.js.

• Formate: svg, png, jpg, pdf, eps. SVG/PDF/EPS sind echte Vektoren; PNG/JPG werden gerastert.
• Größen: beliebige Pixelwerte (16, 32, … 2048 oder eigene). Bei Vektorformaten setzt die Größe nur die Dokument-/Viewport-Maße.
• Batch: jede Format×Größe-Kombination wird erzeugt; ein Ergebnis → Einzeldownload, mehrere → ein ZIP.
• Logo wird in PDF/EPS als eingebettetes JPEG (auf Plate-Farbe geflacht) mitgeführt.

Hinweis: EPS ist Vektor (Level-2-PostScript) und strukturell geprüft, lokal aber nicht gerendert (macOS hat den EPS-Viewer entfernt). PDF deckt denselben Vektor-Workflow ab und ist visuell verifiziert. Für sehr kleine Größen (≤ 32 px) ist ein QR nicht mehr scanbar — gedacht für Icons/Assets.

Roadmap

• Engine als ESM extrahiert, Web Component, strukturierte Inhaltstypen
• Logo-Einbettung (auto ECC-Anhebung, Modul-Ausstanzung, Plate, rund/eckig)
• Echter In-Browser-Decode-Test (jsQR) + Scannability-Score 0–100
• Presets (built-in + localStorage) + Konfig-als-URL (#cfg=…, base64url)
• Export SVG/PNG/JPG + Vektor-PDF/EPS, beliebige Größen, Batch-ZIP
• CTA-Frame („SCAN ME"), gefaste Ecken, in allen Formaten (Text als Vektor)
• Druck-Anschnitt (Bleed) + Schnittmarken, vektorbasiert in allen Formaten
• Micro-QR (M1–M4), eigener Encoder gegen qrencode verifiziert, node·K-gestylt

Lizenz

MIT. Enthält qrcode.js © 2009 Kazuhiko Arase (MIT). „QR Code" ist eingetragenes Warenzeichen von DENSO WAVE INCORPORATED.