retail-print-kit 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+## 0.3.0 (2026-10-17)
+
+* `retail-print-kit/label-design`: label designs in millimetres (design JSON version 1) with validation, one canvas renderer for screen and print, an EZPL/ZPL encoder (printer-font elements as native commands, designer fonts, QR codes and logos as graphics), printer offsets, eleven built-in shelf-label layouts and the fonts with their licences in `dist/label-fonts/`.
+* `retail-print-kit/label-designer`: the `<rpk-label-designer>` Web Component (palette, drag and resize, guides, undo/redo, properties, logo upload, printer view, check against real items) and `<rpk-label-preview>`. Defined only in a browser; requiring it in Node does nothing.
+* `typesVersions` so TypeScript projects using `moduleResolution: node` find the types of every subpath.
+* Guide on the website: shelf labels from a label design.
+
+## 0.2.3 (2026-10-05)
+
+* Website with a landing page and ten task guides (receipts, Electron, cash drawer, Star TSP100, labels, templates, QR and barcodes, logos, discovery and status, migration from escpos / node-thermal-printer).
+* The designer moved to `/designer/` on the site; `sitemap.xml`, `robots.txt`, `llms.txt` and `llms-full.txt` are published.
+* README: guides and FAQ sections. Package description leads with the printer families.
+
+## 0.2.2 (2026-10-05)
+
+* A plain install is now 4 packages and under 2 MB with no native modules (was 34 packages and 30 MB).
+* `@napi-rs/canvas` is an optional peer, as intended; it was being installed for everyone.
+* QR codes are generated with the dependency-free `qrcode-generator`; text is encoded as UTF-8.
+
+## 0.2.1 (2026-10-03)
+
+* The repository and the designer address were renamed to `retail-print-kit`; all links follow.
+
+## 0.2.0 (2026-10-03)
+
+* Images and logos: `loadImage` with optional Floyd-Steinberg dithering, `ditherRgba`, `serializeBitmap`, a template `image` block, logo upload in the designer.
+* `discoverNetworkPrinters` finds raw-printing hosts on the local networks and can identify each.
+* CLI: `verify`, `verify-label`, `discover`, `image`. A hardware checklist documents what to confirm on real units.
+
+## 0.1.0 (2026-10-03)
+
+First release.
+
+* ESC/POS, Star Line Mode and Star raster encoders with printer profiles.
+* Network, USB and serial transports; printer status and `identify`.
+* Receipt templates, HTML and PNG previews.
+* Label printing in ZPL, TSPL and EZPL with an SVG preview and label templates.
+* Browser bundle and the template designer.
+* CLI: `test`, `drawer`, `status`, `identify`, `preview`, `print`, `profiles`, `list`.

package/README.md

@@ -10,7 +10,7 @@ A modern replacement for `escpos` / `node-thermal-printer`: ESC/POS **and** Star
 network / serial, printer profiles instead of model `if`s, receipt and label **templates**, live
 **previews**, a visual **designer**, and a CLI for testing hardware in the field.
 
-**[Open the designer](https://arka162.github.io/retail-print-kit/)** · [Printer matrix](docs/printer-matrix.md) · [Hardware checklist](docs/hardware-checklist.md)
+**[Website](https://arka162.github.io/retail-print-kit/)** · **[Designer](https://arka162.github.io/retail-print-kit/designer/)** · [Guides](https://arka162.github.io/retail-print-kit/guides/) · [Printer matrix](docs/printer-matrix.md) · [Changelog](CHANGELOG.md)
 
 ![Receipt designer](https://raw.githubusercontent.com/arka162/retail-print-kit/main/docs/images/designer-receipt.png)
 
@@ -77,6 +77,20 @@ const { UsbTransport } = require('retail-print-kit/usb');       // new UsbTransp
 const { SerialTransport } = require('retail-print-kit/serial'); // new SerialTransport('COM3', { baudRate: 9600 })
 ```
 
+## Guides
+
+* [Print a receipt from Node.js on an ESC/POS thermal printer](https://arka162.github.io/retail-print-kit/guides/print-receipt-nodejs.html)
+* [Print receipts from an Electron app](https://arka162.github.io/retail-print-kit/guides/electron-receipt-printing.html)
+* [Open a cash drawer](https://arka162.github.io/retail-print-kit/guides/open-cash-drawer-nodejs.html)
+* [Print to a Star TSP100 or TSP143](https://arka162.github.io/retail-print-kit/guides/star-tsp100-nodejs.html)
+* [Print ZPL, TSPL and EZPL labels](https://arka162.github.io/retail-print-kit/guides/zpl-tspl-ezpl-label-printing-nodejs.html)
+* [Receipt and label templates and the visual designer](https://arka162.github.io/retail-print-kit/guides/receipt-template-designer.html)
+* [Design shelf labels in millimetres and print them on Godex or Zebra](https://arka162.github.io/retail-print-kit/guides/label-design-shelf-labels.html)
+* [QR codes and barcodes](https://arka162.github.io/retail-print-kit/guides/print-qr-code-barcode-receipt.html)
+* [Print a logo or image](https://arka162.github.io/retail-print-kit/guides/print-logo-image-thermal-printer.html)
+* [Find printers on the network and read status](https://arka162.github.io/retail-print-kit/guides/network-printer-discovery-status.html)
+* [Migrating from escpos or node-thermal-printer](https://arka162.github.io/retail-print-kit/guides/escpos-node-thermal-printer-alternative.html)
+
 ## Supported printers
 
 | Family | Profile ids | Command set |
@@ -157,9 +171,52 @@ const label = renderLabel(labelTemplate, data); // from a designer JSON
 
 ![Label designer](https://raw.githubusercontent.com/arka162/retail-print-kit/main/docs/images/designer-label.png)
 
+## Label designs (`retail-print-kit/label-design`)
+
+A label design is a JSON document in millimetres (`version: 1`) made of text, price, barcode, QR, line,
+box, fill and image elements with `{{field}}` placeholders. One renderer draws it on screen and at
+printer resolution, so the preview is the print; one encoder turns it into EZPL (Godex) or ZPL (Zebra).
+Elements with a printer-font pattern print as native commands byte for byte; designer fonts, prices,
+QR codes and logos go as graphics (ZPL `^GFA`, EZPL `Q`). Eleven classic shelf-label layouts ship as
+built-ins.
+
+```js
+const ld = require('retail-print-kit/label-design');
+
+ld.validateDesign(design);                                      // null, or the first problem
+const data = ld.labelDataFromItem(item, { storeName: 'Main' }); // itemName, price, barcode, ...
+ld.drawLabel(canvas, design, data, { ppm: 8 });                 // screen preview, returns warnings
+const rasterize = ld.createRasterizer();                        // browser canvas, or pass canvasFactory
+const bytes = ld.encodeDesignLabel(design, 'zpl', data, rasterize, { x: 0, y: 0 });
+
+const builtin = ld.findBuiltinTemplate('2 X 1', 'dual', 'ezpl');
+ld.encodeBuiltinLabel(builtin, 'ezpl', data);                   // printer fonts only
+ld.designFromBuiltin(builtin, 'ezpl');                          // editable copy, prints the same
+```
+
+The import has no DOM access, so it runs in Node, Electron and the browser. The fonts the designer
+uses are in `dist/label-fonts/` with their licences; serve them and call `ld.ensureLabelFonts(url)`.
+
+### The label designer element (`retail-print-kit/label-designer`)
+
+A framework-free Web Component for apps where people design labels: palette of item fields, drag and
+resize with guides and snapping, undo and redo, properties per element, logo upload, printer view
+and a check against real items. It works in any framework (Angular, React, plain pages) and in Electron.
+
+```js
+import 'retail-print-kit/label-designer';              // defines <rpk-label-designer> and <rpk-label-preview>
+const el = document.querySelector('rpk-label-designer');
+el.fontsUrl = '/assets/label-fonts/';
+el.design = design; el.name = 'Shelf tag';
+el.itemSource = { search: (q) => api.items(q), page: (offset, limit) => api.page(offset, limit) };
+el.addEventListener('designsave', (e) => api.save(e.detail.name, e.detail.design).then(() => el.markSaved()));
+```
+
+Put your own buttons in its toolbar with `slot="actions"`. Colours come from `--rpk-*` CSS variables.
+
 ## Designer
 
-**https://arka162.github.io/retail-print-kit/** edits receipt and label templates in the browser:
+**https://arka162.github.io/retail-print-kit/designer/** edits receipt and label templates in the browser:
 block palette, nested `each` / `if`, property editor, sample data, live preview, drag-to-position
 on labels, logo upload with dithering, JSON import and export. It runs entirely in the page from
 the browser bundle (`retail-print-kit/browser`); nothing is uploaded.
@@ -201,11 +258,25 @@ npx retail-print-kit profiles
 
 Add `--dry` to any printing command to dump the bytes as hex instead of sending them.
 
+## FAQ
+
+**Does it work in Electron?** Yes, in the main process; the renderer asks for prints over IPC and the
+browser build renders previews.
+
+**Does it need a printer driver?** No. It sends the printer's own commands over TCP, USB or serial,
+so there is no OS print dialog and nothing to install on the machine.
+
+**Why does a Star TSP100 print nothing with other libraries?** It is raster-only and ignores ESC/POS
+text. Use the `star-tsp100` profile.
+
+**Can I print without a printer attached?** `--dry` dumps the bytes, and the HTML, PNG and SVG
+previews show the result.
+
 ## Status of hardware verification
 
 Encoders are covered by byte-exact tests. Items still to be confirmed on real units are listed in
 the [hardware checklist](docs/hardware-checklist.md): Star raster cut modes, Star status bits,
-Godex font sizes, and QR syntax on EZPL and TSPL. Reports from the field are welcome as issues.
+Godex font sizes, QR syntax on EZPL and TSPL, and the `label-design` graphics commands (EZPL `Q`, ZPL `^GFA`). Reports from the field are welcome as issues.
 
 ## License
 

package/dist/label-design/builtins-data.d.ts

@@ -0,0 +1,2 @@
+import { BuiltinTemplate } from './types';
+export declare const BUILTIN_TEMPLATES: BuiltinTemplate[];