@kreiseck/kasseneck-api 0.6.7

package/dist/cjs/printing/escpos.d.ts

@@ -0,0 +1,219 @@
+/**
+ * ESC/POS-Bytefolgen fuer Bondrucker — Zwilling von
+ * `kasseneck_api/lib/src/printing/escpos/` (Flutter).
+ *
+ * Dieses Modul erzeugt **nur Bytes**. Es kennt keinen Transport: kein
+ * Bluetooth, kein WLAN, kein USB, keine Verbindung. Wer die Bytes wohin
+ * schickt, entscheidet der Aufrufer.
+ *
+ * Die Steuerbefehle sind wortwoertlich aus `commands.dart`, `generator.dart`
+ * und `qrcode.dart` uebernommen. Bei ESC/POS zaehlt jedes Byte: ein
+ * "ungefaehr richtiger" Befehl druckt Unsinn oder gar nichts. Reihenfolge und
+ * Bytefolge deshalb nicht anpassen, ohne die Erwartungswerte in
+ * `test/escpos.test.ts` gegen das Flutter-Vorbild neu abzugleichen.
+ *
+ * **Zeichenkodierung.** Bondrucker sprechen kein UTF-8, sondern eine
+ * Codepage. Dieses Modul kodiert Text wie das Vorbild nach Latin-1 (ein Byte
+ * je Zeichen) und meldet dem Drucker dazu die passende Codepage ueber
+ * `ESC t n`. Vorgabe ist CP1252: dort stehen alle deutschen Umlaute an
+ * denselben Stellen wie in Latin-1, "ä" ist also genau 0xE4 — ein Byte, nicht
+ * zwei. Waeren es zwei (UTF-8), verschoeben sich zusaetzlich alle
+ * Spaltenbreiten, weil die Spaltenrechnung mit Byte-Laengen arbeitet.
+ * CP437 ist ebenfalls waehlbar — manche (Bluetooth-)Drucker ignorieren
+ * `ESC t 16` und bleiben in CP437; dann werden die Umlaute auf ihre
+ * CP437-Plaetze umkodiert (ä = 0x84, ü = 0x81, ß = 0xE1, ...). Zeichen ohne
+ * CP437-Platz werden zu `?` — weiterhin ein Byte je Zeichen.
+ *
+ * Nicht enthalten (bewusst): Rasterbilder/Logos, Capability-Profile einzelner
+ * Druckermodelle, Kassenlade, 1D-Barcodes.
+ */
+/** Papierbreite der Bonrolle. */
+export type PosPaperSize = 'mm58' | 'mm80';
+/** Ausrichtung einer Textzeile bzw. innerhalb einer Spalte. */
+export type PosAlign = 'left' | 'center' | 'right';
+/** Druckerschrift: A ist breiter, B schmaler (mehr Zeichen je Zeile). */
+export type PosFont = 'fontA' | 'fontB';
+/** Voller oder teilweiser Papierschnitt. */
+export type PosCutMode = 'full' | 'partial';
+/** Vom Drucker zu verwendende Codepage. */
+export type PosCodeTable = 'CP437' | 'CP1252';
+/** Zeichenvergroesserung (1 = einfach, 2 = doppelt, ... bis 8). */
+export type PosTextSize = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
+/** Modulgroesse des QR-Codes (Punkte je Modul). */
+export type QrSize = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
+/** Fehlerkorrekturstufe des QR-Codes. */
+export type QrCorrection = 'L' | 'M' | 'Q' | 'H';
+/** Textstil. Fehlende Felder gelten als Vorgabewert (nicht als "unveraendert"). */
+export interface PosStyles {
+    bold?: boolean;
+    reverse?: boolean;
+    underline?: boolean;
+    turn90?: boolean;
+    align?: PosAlign;
+    height?: PosTextSize;
+    width?: PosTextSize;
+    fontType?: PosFont;
+    codeTable?: PosCodeTable;
+}
+/**
+ * Eine Spalte einer Zeile. `width` ist ein Zwoelftel-Anteil (1..12), die
+ * Breiten aller Spalten einer Zeile muessen zusammen 12 ergeben.
+ * Entweder `text` **oder** `textEncoded` angeben, nicht beides.
+ */
+export interface PosColumn {
+    text?: string;
+    textEncoded?: Uint8Array;
+    width: number;
+    styles?: PosStyles;
+}
+export interface EscPosOptions {
+    /** Papierbreite, Vorgabe `mm58`. */
+    paperSize?: PosPaperSize;
+    /** Globale Codepage, Vorgabe `CP1252`; `null` laesst die des Druckers stehen. */
+    codeTable?: PosCodeTable | null;
+    /** Abstand zwischen Spalten in Punkten, Vorgabe 5. */
+    spaceBetweenRows?: number;
+}
+export interface EscPosTextOptions {
+    styles?: PosStyles;
+    /** Zusaetzliche Leerzeilen nach dem Text (der eine Zeilenumbruch kommt immer). */
+    linesAfter?: number;
+}
+export interface EscPosHrOptions {
+    /** Fuellzeichen, Vorgabe `-`. */
+    ch?: string;
+    /** Laenge in Zeichen; ohne Angabe die volle Zeilenbreite. */
+    len?: number;
+    linesAfter?: number;
+}
+export interface EscPosQrOptions {
+    align?: PosAlign;
+    size?: QrSize;
+    correction?: QrCorrection;
+}
+/** Interner Stilzustand — immer vollstaendig, nie teilbefuellt. */
+interface AktuelleStile {
+    bold: boolean;
+    reverse: boolean;
+    underline: boolean;
+    turn90: boolean;
+    align: PosAlign;
+    height: PosTextSize;
+    width: PosTextSize;
+    fontType: PosFont | null;
+    codeTable: PosCodeTable | null;
+}
+/**
+ * Aufbauender Puffer. Die Felder ausser `paperSize`/`spaceBetweenRows` sind
+ * interner Zustand des Bytestroms — nicht von aussen aendern, sondern ueber
+ * die `escPos*`-Funktionen.
+ */
+export interface EscPosDocument {
+    readonly paperSize: PosPaperSize;
+    readonly spaceBetweenRows: number;
+    /** intern: bisher erzeugte Bytes */
+    readonly bytes: number[];
+    /** intern: global gesetzte Codepage (ueberlebt `escPosReset`) */
+    globalCodeTable: PosCodeTable | null;
+    /** intern: global gesetzte Schrift (ueberlebt `escPosReset`) */
+    globalFont: PosFont | null;
+    /** intern: Zeichen je Zeile aus der globalen Schrift */
+    maxCharsPerLine: number | null;
+    /** intern: zuletzt an den Drucker gesendeter Stil */
+    styles: AktuelleStile;
+}
+/**
+ * Kodiert Text so, wie ihn der Drucker erwartet: ein Byte je Zeichen nach
+ * Latin-1, vorher die vier Zeichenersetzungen des Vorbilds. Ein Umlaut wird
+ * damit zu genau einem Byte — Voraussetzung dafuer, dass die Spaltenrechnung
+ * stimmt.
+ */
+export declare function encodeEscPosText(text: string, codeTable?: PosCodeTable): Uint8Array;
+/** Zeichen je Zeile fuer Papier und Schrift (`fontA`, wenn nichts gesetzt ist). */
+export declare function escPosMaxCharsPerLine(paperSize: PosPaperSize, font?: PosFont | null): number;
+/** Legt einen leeren Bytepuffer an. Der erste Befehl ist ueblicherweise `escPosReset`. */
+export declare function createEscPosDocument(options?: EscPosOptions): EscPosDocument;
+/** Die bisher erzeugten Bytes als Kopie. */
+export declare function escPosBytes(doc: EscPosDocument): Uint8Array;
+/**
+ * `ESC @`: Drucker initialisieren und den gemerkten Stil verwerfen. Danach
+ * werden globale Codepage und Schrift erneut gesendet — der Drucker vergisst
+ * sie beim Initialisieren.
+ */
+export declare function escPosReset(doc: EscPosDocument): void;
+/**
+ * `ESC t n`: Codepage waehlen. Sie gilt bis zum naechsten `escPosReset` und
+ * wird von diesem erneut gesendet. `null` schaltet die Vorgabe ab; dann
+ * bleibt die Codepage des Druckers stehen und Umlaute werden unlesbar.
+ */
+export declare function escPosSetGlobalCodeTable(doc: EscPosDocument, codeTable: PosCodeTable | null): void;
+/**
+ * `ESC M n`: Schrift waehlen. Die Schrift bestimmt auch, wie viele Zeichen in
+ * eine Zeile passen (32/42 bei 58 mm, 48/64 bei 80 mm).
+ */
+export declare function escPosSetGlobalFont(doc: EscPosDocument, font: PosFont | null, options?: {
+    maxCharsPerLine?: number;
+}): void;
+/**
+ * Sendet die Stilbefehle, die sich gegenueber dem zuletzt gesendeten Stand
+ * geaendert haben. Fehlende Felder in [styles] gelten als Vorgabe: wer fett
+ * weglaesst, schaltet fett also ab.
+ */
+export declare function escPosSetStyles(doc: EscPosDocument, styles?: PosStyles): void;
+/**
+ * Interner Textdruck: absolute Position setzen (`ESC $`), Stil senden, Bytes
+ * ausgeben. [colInd]/[colWidth] beschreiben die Spalte im Zwoelftel-Raster.
+ */
+/**
+ * Wortweiser Umbruch von (kodierten) Text-Bytes auf hoechstens `max` Zeichen
+ * je Zeile: geschnitten wird am letzten Leerzeichen innerhalb der Grenze
+ * (das Leerzeichen selbst faellt weg); gibt es keines, hart bei `max` --
+ * sonst kaeme die Zeile nie voran. Ein Bondrucker bricht sonst hart mitten
+ * im Wort ("Kleinunter|nehmer", "0,7|9"); das soll nie aufs Papier.
+ */
+export declare function escPosWortzeilen(textBytes: Uint8Array, max: number): Uint8Array[];
+/**
+ * Dieselbe Regel fuer Zeichenketten -- fuer Bildschirm-Vorschauen, die das
+ * Papier nachstellen, und fuer das Zeichenraster. Zusaetzlich:
+ * - geschuetztes Leerzeichen (U+00A0) ist kein Umbruchpunkt ("je 0,79" bleibt
+ *   zusammen) und wird als normales Leerzeichen ausgegeben;
+ * - ein ueberlanges Wort bricht nach einem Bindestrich, wenn es einen hat
+ *   ("Bio-" / "Dinkelvollkornsemmel"), sonst hart.
+ */
+export declare function wortzeilenText(text: string, max: number): string[];
+/**
+ * Druckt Text und schliesst die Zeile ab. Nach dem Text folgt immer genau ein
+ * Zeilenumbruch, `linesAfter` haengt weitere an.
+ */
+export declare function escPosText(doc: EscPosDocument, text: string, options?: EscPosTextOptions): void;
+/** [n] Zeilenumbrueche (0x0A) — nicht der Vorschubbefehl, sondern echte Umbrueche. */
+export declare function escPosEmptyLines(doc: EscPosDocument, n: number): void;
+/** `ESC d n`: Papier um [n] Zeilen vorschieben. */
+export declare function escPosFeed(doc: EscPosDocument, n: number): void;
+/**
+ * Papierschnitt: fuenf Leerzeilen (damit der Text ueber der Schneide steht)
+ * und danach `GS V 0` bzw. `GS V 1`.
+ */
+export declare function escPosCut(doc: EscPosDocument, mode?: PosCutMode): void;
+/** Trennlinie ueber die volle Zeilenbreite (oder [len] Zeichen). */
+export declare function escPosHr(doc: EscPosDocument, options?: EscPosHrOptions): void;
+/**
+ * Druckt eine Zeile aus bis zu zwoelf Spalten. Die Breiten (Zwoelftel) muessen
+ * zusammen 12 ergeben. Passt der Inhalt einer Spalte nicht, laeuft der Rest in
+ * eine Folgezeile.
+ */
+export declare function escPosRow(doc: EscPosDocument, columns: readonly PosColumn[]): void;
+/**
+ * Bytes des nativen QR-Befehls (`GS ( k`, Funktionen 167/169/180/182/181) —
+ * ohne Ausrichtung, ohne Zeilenumbruch. Der Drucker zeichnet den Code selbst;
+ * es wird kein Bild uebertragen.
+ *
+ * Bei Kasseneck-Belegen steht hier der maschinenlesbare RKSV-Code.
+ */
+export declare function qrCodeBytes(text: string, options?: {
+    size?: QrSize;
+    correction?: QrCorrection;
+}): Uint8Array;
+/** Setzt die Ausrichtung und haengt den nativen QR-Befehl an. */
+export declare function escPosQrCode(doc: EscPosDocument, text: string, options?: EscPosQrOptions): void;
+export {};