tauri-plugin-thermal-printer 1.3.0 → 1.3.1

package/README.md

@@ -274,7 +274,7 @@ Send a print test to a specific printer to verify functionality.
 
 #### Request:
 ```typescript
-import { test_thermal_printer, type TestPrintRequest } from "tauri-plugin-thermal-printer";
+import { ENCODE, test_thermal_printer, type TestPrintRequest } from "tauri-plugin-thermal-printer";
 
 try { await test_thermal_printer({
   "printer_info": {
@@ -283,7 +283,12 @@ try { await test_thermal_printer({
     "options": {
       "cut_paper": true,
       "beep": true,
-      "open_cash_drawer": false
+      "open_cash_drawer": false,
+      "code_page": {
+        "codepage": 6,
+        "encode": ENCODE.WINDOWS_1252,
+        "use_gbk": false
+      }
     },
     "sections": [] // it's not going to print anything
   },
@@ -341,7 +346,7 @@ Print a personalized document with the specified sections.
 
 #### Request:
 ```typescript
-import { print_thermal_printer, type PrintJobRequest } from "tauri-plugin-thermal-printer";
+import { ENCODE, print_thermal_printer, type PrintJobRequest } from "tauri-plugin-thermal-printer";
 
 try { await print_thermal_printer({
   "printer": "TM-T20II",
@@ -349,7 +354,12 @@ try { await print_thermal_printer({
   "options": {
     "cut_paper": true,
     "beep": false,
-    "open_cash_drawer": false
+    "open_cash_drawer": false,
+    "code_page": {
+      "codepage": 6,
+      "encode": ENCODE.WINDOWS_1252,
+      "use_gbk": false
+    }
   },
   "sections": [
     {"Title": {"text": "My Business"}},
@@ -384,7 +394,7 @@ Returns `Promise<void>`. Resolves when printing completes successfully. **Throws
 | `options.cut_paper` | boolean | ❌ No | Cut paper after printing (default: `true`) |
 | `options.beep` | boolean | ❌ No | Beep after printing (default: `false`) |
 | `options.open_cash_drawer` | boolean | ❌ No | Open cash drawer after printing (default: `false`) |
-| `options.code_page` | CodePage | ❌ No | Character encoding for special characters (default: `"Default"`) — see [CodePage](#codepage) |
+| `options.code_page` | CodePage | ✅ Yes | Required ESC/POS page selection plus host-side encoding strategy — see [CodePage](#codepage) |
 | `sections` | array | ✅ Yes | Array of sections to print (see [Section Types](#section-types)) |
 
 #### Paper Sizes
@@ -881,25 +891,50 @@ The plugin exports typed constants and builder functions so you never have to ty
 
 Set the character encoding once in `PrinterOptions.code_page` and all text sections (`Title`, `Subtitle`, `Text`, `Table`) will use it automatically.
 
-Each printer model assigns its own numbers to code pages, so `CodePage` accepts the raw page number directly via `codePage(n)`. Check your printer's manual for the correct value.
+Each printer model assigns its own `ESC t n` values, so `CodePage.codepage` accepts the raw page number directly. `CodePage.encode` controls the host-side encoding used before bytes are sent to the printer. `CodePage.use_gbk` explicitly controls whether characters that the selected `encode` cannot represent should be retried with GBK before falling back to the original UTF-8 bytes.
 
 ```typescript
-import { codePage, CODE_PAGE, type CodePage } from "tauri-plugin-thermal-printer";
+import { ENCODE, type CodePage } from "tauri-plugin-thermal-printer";
 
 const options = {
   cut_paper: true,
   beep: false,
   open_cash_drawer: false,
-  code_page: codePage(2),  // sends ESC t 2 — CP850 on most Epson-compatible printers
+  code_page: {
+    codepage: 6,
+    encode: ENCODE.WINDOWS_1252,
+    use_gbk: false,
+  }, // sends ESC t 6
 };
 ```
 
-| Value | Description |
-|---|---|
-| `codePage(n)` | Sends `ESC t n` with the given number. The user is responsible for choosing the correct value for their printer model. |
-| `CODE_PAGE.ACCENT_REMOVER` | Removes accents and special characters by converting them to their ASCII equivalents (á→a, ß→ss, ¿→?, €→EUR). Useful when printers do not support alternative code pages. |
+`CodePage` fields:
+
+| Field | Required | Description |
+|---|---|---|
+| `codepage` | ✅ Yes | Raw `ESC t n` value sent to the printer. |
+| `encode` | ❌ No | Host-side encoding strategy. Defaults to `ENCODE.ACCENT_REMOVER`. |
+| `use_gbk` | ❌ No | Retries GBK for characters that `encode` cannot represent before falling back to the original UTF-8 bytes. Defaults to `false`. |
+
+`ENCODE.ACCENT_REMOVER`:
 
-> **Note**: Without a `code_page`, accented characters (á, ñ, ü, etc.) will print as `?`. Set it once in `options` and it applies to the entire document.
+- Transliterates accented characters to ASCII before any optional GBK retry
+  and final UTF-8 passthrough.
+- Useful when the printer does not have a reliable legacy code page for your
+  text.
+- Examples: `á -> a`, `ß -> ss`, `€ -> EUR`.
+
+All other `ENCODE.*` values come directly from
+[`encoding_rs` statics](https://docs.rs/encoding_rs/latest/encoding_rs/#statics).
+Use them with the same uppercase names exposed by the package.
+
+Examples:
+
+- `ENCODE.WINDOWS_1252` for Western European text
+- `ENCODE.GBK` for GBK output
+- `ENCODE.SHIFT_JIS` for Shift JIS output
+
+> **Note**: `options.code_page` is required. If the selected `encode` cannot represent a character, the plugin retries GBK only when `use_gbk` is `true`; otherwise it silently emits the original UTF-8 bytes for that character.
 
 ---
 
@@ -1020,13 +1055,13 @@ import {
   pdf417,
   image,
   logo,
+  ENCODE,
   TEXT_ALIGN,
   TEXT_SIZE,
   BARCODE_TYPE,
   BARCODE_TEXT_POSITION,
   QR_ERROR_CORRECTION,
   IMAGE_MODE,
-  CODE_PAGE,
 } from "tauri-plugin-thermal-printer";
 
 const job: PrintJobRequest = {
@@ -1036,7 +1071,11 @@ const job: PrintJobRequest = {
     cut_paper: true,
     beep: false,
     open_cash_drawer: false,
-    code_page: CODE_PAGE.WINDOWS_LATIN,
+    code_page: {
+      codepage: 6,
+      encode: ENCODE.WINDOWS_1252,
+      use_gbk: false,
+    },
   },
   sections: [
     globalStyles({ align: TEXT_ALIGN.LEFT }),

package/dist-js/code-page.contract.d.ts

@@ -0,0 +1 @@
+export {};

package/dist-js/encode.d.ts

@@ -0,0 +1,44 @@
+export declare const ENCODE: {
+    readonly BIG5: "BIG5";
+    readonly EUC_JP: "EUC_JP";
+    readonly EUC_KR: "EUC_KR";
+    readonly GBK: "GBK";
+    readonly IBM866: "IBM866";
+    readonly ISO_2022_JP: "ISO_2022_JP";
+    readonly ISO_8859_10: "ISO_8859_10";
+    readonly ISO_8859_13: "ISO_8859_13";
+    readonly ISO_8859_14: "ISO_8859_14";
+    readonly ISO_8859_15: "ISO_8859_15";
+    readonly ISO_8859_16: "ISO_8859_16";
+    readonly ISO_8859_2: "ISO_8859_2";
+    readonly ISO_8859_3: "ISO_8859_3";
+    readonly ISO_8859_4: "ISO_8859_4";
+    readonly ISO_8859_5: "ISO_8859_5";
+    readonly ISO_8859_6: "ISO_8859_6";
+    readonly ISO_8859_7: "ISO_8859_7";
+    readonly ISO_8859_8: "ISO_8859_8";
+    readonly ISO_8859_8_I: "ISO_8859_8_I";
+    readonly KOI8_R: "KOI8_R";
+    readonly KOI8_U: "KOI8_U";
+    readonly SHIFT_JIS: "SHIFT_JIS";
+    readonly UTF_16BE: "UTF_16BE";
+    readonly UTF_16LE: "UTF_16LE";
+    readonly UTF_8: "UTF_8";
+    readonly GB18030: "GB18030";
+    readonly MACINTOSH: "MACINTOSH";
+    readonly REPLACEMENT: "REPLACEMENT";
+    readonly WINDOWS_1250: "WINDOWS_1250";
+    readonly WINDOWS_1251: "WINDOWS_1251";
+    readonly WINDOWS_1252: "WINDOWS_1252";
+    readonly WINDOWS_1253: "WINDOWS_1253";
+    readonly WINDOWS_1254: "WINDOWS_1254";
+    readonly WINDOWS_1255: "WINDOWS_1255";
+    readonly WINDOWS_1256: "WINDOWS_1256";
+    readonly WINDOWS_1257: "WINDOWS_1257";
+    readonly WINDOWS_1258: "WINDOWS_1258";
+    readonly WINDOWS_874: "WINDOWS_874";
+    readonly X_MAC_CYRILLIC: "X_MAC_CYRILLIC";
+    readonly X_USER_DEFINED: "X_USER_DEFINED";
+    readonly ACCENT_REMOVER: "ACCENT_REMOVER";
+};
+export type Encode = typeof ENCODE[keyof typeof ENCODE];

package/dist-js/index.cjs

@@ -2,6 +2,50 @@
 
 var core = require('@tauri-apps/api/core');
 
+const ENCODE = {
+    BIG5: 'BIG5',
+    EUC_JP: 'EUC_JP',
+    EUC_KR: 'EUC_KR',
+    GBK: 'GBK',
+    IBM866: 'IBM866',
+    ISO_2022_JP: 'ISO_2022_JP',
+    ISO_8859_10: 'ISO_8859_10',
+    ISO_8859_13: 'ISO_8859_13',
+    ISO_8859_14: 'ISO_8859_14',
+    ISO_8859_15: 'ISO_8859_15',
+    ISO_8859_16: 'ISO_8859_16',
+    ISO_8859_2: 'ISO_8859_2',
+    ISO_8859_3: 'ISO_8859_3',
+    ISO_8859_4: 'ISO_8859_4',
+    ISO_8859_5: 'ISO_8859_5',
+    ISO_8859_6: 'ISO_8859_6',
+    ISO_8859_7: 'ISO_8859_7',
+    ISO_8859_8: 'ISO_8859_8',
+    ISO_8859_8_I: 'ISO_8859_8_I',
+    KOI8_R: 'KOI8_R',
+    KOI8_U: 'KOI8_U',
+    SHIFT_JIS: 'SHIFT_JIS',
+    UTF_16BE: 'UTF_16BE',
+    UTF_16LE: 'UTF_16LE',
+    UTF_8: 'UTF_8',
+    GB18030: 'GB18030',
+    MACINTOSH: 'MACINTOSH',
+    REPLACEMENT: 'REPLACEMENT',
+    WINDOWS_1250: 'WINDOWS_1250',
+    WINDOWS_1251: 'WINDOWS_1251',
+    WINDOWS_1252: 'WINDOWS_1252',
+    WINDOWS_1253: 'WINDOWS_1253',
+    WINDOWS_1254: 'WINDOWS_1254',
+    WINDOWS_1255: 'WINDOWS_1255',
+    WINDOWS_1256: 'WINDOWS_1256',
+    WINDOWS_1257: 'WINDOWS_1257',
+    WINDOWS_1258: 'WINDOWS_1258',
+    WINDOWS_874: 'WINDOWS_874',
+    X_MAC_CYRILLIC: 'X_MAC_CYRILLIC',
+    X_USER_DEFINED: 'X_USER_DEFINED',
+    ACCENT_REMOVER: 'ACCENT_REMOVER',
+};
+
 const PAPER_SIZE_CHARS_PER_LINE = {
     Mm40: 21,
     Mm44: 24,
@@ -25,10 +69,6 @@ function getPaperSizeCharsPerLine(paperSize) {
 function getPaperSizePixelsWidth(paperSize) {
     return PAPER_SIZE_PIXELS_WIDTH[paperSize];
 }
-/** Creates a `CodePage` that sends the given ESC/POS code page number. */
-function codePage(n) {
-    return { Page: n };
-}
 // ─── Convenience style presets ────────────────────────────────────────────────
 const TEXT_ALIGN = {
     LEFT: 'left',
@@ -83,11 +123,6 @@ const CUT_MODE = {
     FULL: 'full',
     PARTIAL: 'partial',
 };
-const CODE_PAGE = {
-    /** Strips accents and special chars to plain ASCII. Use when the printer
-     *  ignores ESC t commands. á→a, é→e, ñ→n, ß→ss, ¿→?, €→EUR, etc. */
-    ACCENT_REMOVER: 'AccentRemover',
-};
 // ─── Helper builders ──────────────────────────────────────────────────────────
 /** Creates a Title section */
 function title(text, styles) {
@@ -234,9 +269,9 @@ async function test_thermal_printer(testPrintRequest) {
 
 exports.BARCODE_TEXT_POSITION = BARCODE_TEXT_POSITION;
 exports.BARCODE_TYPE = BARCODE_TYPE;
-exports.CODE_PAGE = CODE_PAGE;
 exports.CUT_MODE = CUT_MODE;
 exports.DEFAULT_PAPER_SIZE = DEFAULT_PAPER_SIZE;
+exports.ENCODE = ENCODE;
 exports.IMAGE_MODE = IMAGE_MODE;
 exports.PAPER_SIZE_CHARS_PER_LINE = PAPER_SIZE_CHARS_PER_LINE;
 exports.PAPER_SIZE_PIXELS_WIDTH = PAPER_SIZE_PIXELS_WIDTH;
@@ -246,7 +281,6 @@ exports.TEXT_FONT = TEXT_FONT;
 exports.TEXT_SIZE = TEXT_SIZE;
 exports.barcode = barcode;
 exports.beep = beep;
-exports.codePage = codePage;
 exports.cut = cut;
 exports.dataMatrix = dataMatrix;
 exports.drawer = drawer;

package/dist-js/index.d.ts

@@ -1,3 +1,6 @@
+import type { Encode } from './encode';
+export { ENCODE } from './encode';
+export type { Encode } from './encode';
 export type PaperSize = 'Mm40' | 'Mm44' | 'Mm58' | 'Mm72' | 'Mm80' | 'Mm104';
 export declare const PAPER_SIZE_CHARS_PER_LINE: Record<PaperSize, number>;
 export declare const PAPER_SIZE_PIXELS_WIDTH: Record<PaperSize, number>;
@@ -5,20 +8,19 @@ export declare const DEFAULT_PAPER_SIZE: PaperSize;
 export declare function getPaperSizeCharsPerLine(paperSize: PaperSize): number;
 export declare function getPaperSizePixelsWidth(paperSize: PaperSize): number;
 /**
- * Character encoding page to use for printing.
+ * ESC/POS page selection plus explicit host-side encoding behavior.
  *
- * - `{ Page: n }` — sends `ESC t n` to the printer; the user is responsible
- *   for choosing the correct number for their printer model and ensuring the
- *   text is already encoded accordingly.
- * - `"AccentRemover"` — strips accents/diacritics to plain ASCII before
- *   sending. Use when the printer ignores `ESC t` or has no alternate code
- *   page. Examples: á→a, é→e, ñ→n, ß→ss, ¿→?, €→EUR.
+ * - `codepage` controls the `ESC t n` command sent to the printer.
+ * - `encode` selects the host-side encoding and defaults to
+ *   `ENCODE.ACCENT_REMOVER`.
+ * - `use_gbk` controls whether unmapped non-ASCII characters may fall back
+ *   to GBK. It defaults to `false`.
  */
-export type CodePage = {
-    Page: number;
-} | 'AccentRemover';
-/** Creates a `CodePage` that sends the given ESC/POS code page number. */
-export declare function codePage(n: number): CodePage;
+export interface CodePage {
+    codepage: number;
+    encode?: Encode;
+    use_gbk?: boolean;
+}
 /** Text alignment options */
 export type TextAlign = 'left' | 'center' | 'right';
 /** Text size options */
@@ -90,17 +92,12 @@ export declare const CUT_MODE: {
     readonly FULL: CutMode;
     readonly PARTIAL: CutMode;
 };
-export declare const CODE_PAGE: {
-    /** Strips accents and special chars to plain ASCII. Use when the printer
-     *  ignores ESC t commands. á→a, é→e, ñ→n, ß→ss, ¿→?, €→EUR, etc. */
-    readonly ACCENT_REMOVER: CodePage;
-};
 export interface PrinterOptions {
     cut_paper: boolean;
     beep: boolean;
     open_cash_drawer: boolean;
-    /** Character encoding for the printer. Default: `{ Page: 0 }` (CP437, ASCII only). */
-    code_page?: CodePage;
+    /** Required ESC/POS page plus host-side encoding strategy. */
+    code_page: CodePage;
 }
 export interface GlobalStyles {
     bold?: boolean;

package/dist-js/index.js

@@ -1,5 +1,49 @@
 import { invoke } from '@tauri-apps/api/core';
 
+const ENCODE = {
+    BIG5: 'BIG5',
+    EUC_JP: 'EUC_JP',
+    EUC_KR: 'EUC_KR',
+    GBK: 'GBK',
+    IBM866: 'IBM866',
+    ISO_2022_JP: 'ISO_2022_JP',
+    ISO_8859_10: 'ISO_8859_10',
+    ISO_8859_13: 'ISO_8859_13',
+    ISO_8859_14: 'ISO_8859_14',
+    ISO_8859_15: 'ISO_8859_15',
+    ISO_8859_16: 'ISO_8859_16',
+    ISO_8859_2: 'ISO_8859_2',
+    ISO_8859_3: 'ISO_8859_3',
+    ISO_8859_4: 'ISO_8859_4',
+    ISO_8859_5: 'ISO_8859_5',
+    ISO_8859_6: 'ISO_8859_6',
+    ISO_8859_7: 'ISO_8859_7',
+    ISO_8859_8: 'ISO_8859_8',
+    ISO_8859_8_I: 'ISO_8859_8_I',
+    KOI8_R: 'KOI8_R',
+    KOI8_U: 'KOI8_U',
+    SHIFT_JIS: 'SHIFT_JIS',
+    UTF_16BE: 'UTF_16BE',
+    UTF_16LE: 'UTF_16LE',
+    UTF_8: 'UTF_8',
+    GB18030: 'GB18030',
+    MACINTOSH: 'MACINTOSH',
+    REPLACEMENT: 'REPLACEMENT',
+    WINDOWS_1250: 'WINDOWS_1250',
+    WINDOWS_1251: 'WINDOWS_1251',
+    WINDOWS_1252: 'WINDOWS_1252',
+    WINDOWS_1253: 'WINDOWS_1253',
+    WINDOWS_1254: 'WINDOWS_1254',
+    WINDOWS_1255: 'WINDOWS_1255',
+    WINDOWS_1256: 'WINDOWS_1256',
+    WINDOWS_1257: 'WINDOWS_1257',
+    WINDOWS_1258: 'WINDOWS_1258',
+    WINDOWS_874: 'WINDOWS_874',
+    X_MAC_CYRILLIC: 'X_MAC_CYRILLIC',
+    X_USER_DEFINED: 'X_USER_DEFINED',
+    ACCENT_REMOVER: 'ACCENT_REMOVER',
+};
+
 const PAPER_SIZE_CHARS_PER_LINE = {
     Mm40: 21,
     Mm44: 24,
@@ -23,10 +67,6 @@ function getPaperSizeCharsPerLine(paperSize) {
 function getPaperSizePixelsWidth(paperSize) {
     return PAPER_SIZE_PIXELS_WIDTH[paperSize];
 }
-/** Creates a `CodePage` that sends the given ESC/POS code page number. */
-function codePage(n) {
-    return { Page: n };
-}
 // ─── Convenience style presets ────────────────────────────────────────────────
 const TEXT_ALIGN = {
     LEFT: 'left',
@@ -81,11 +121,6 @@ const CUT_MODE = {
     FULL: 'full',
     PARTIAL: 'partial',
 };
-const CODE_PAGE = {
-    /** Strips accents and special chars to plain ASCII. Use when the printer
-     *  ignores ESC t commands. á→a, é→e, ñ→n, ß→ss, ¿→?, €→EUR, etc. */
-    ACCENT_REMOVER: 'AccentRemover',
-};
 // ─── Helper builders ──────────────────────────────────────────────────────────
 /** Creates a Title section */
 function title(text, styles) {
@@ -230,4 +265,4 @@ async function test_thermal_printer(testPrintRequest) {
     });
 }
 
-export { BARCODE_TEXT_POSITION, BARCODE_TYPE, CODE_PAGE, CUT_MODE, DEFAULT_PAPER_SIZE, IMAGE_MODE, PAPER_SIZE_CHARS_PER_LINE, PAPER_SIZE_PIXELS_WIDTH, QR_ERROR_CORRECTION, TEXT_ALIGN, TEXT_FONT, TEXT_SIZE, barcode, beep, codePage, cut, dataMatrix, drawer, feed, getPaperSizeCharsPerLine, getPaperSizePixelsWidth, globalStyles, image, line, list_thermal_printers, logo, pdf417, print_thermal_printer, qr, subtitle, table, test_thermal_printer, text, title };
+export { BARCODE_TEXT_POSITION, BARCODE_TYPE, CUT_MODE, DEFAULT_PAPER_SIZE, ENCODE, IMAGE_MODE, PAPER_SIZE_CHARS_PER_LINE, PAPER_SIZE_PIXELS_WIDTH, QR_ERROR_CORRECTION, TEXT_ALIGN, TEXT_FONT, TEXT_SIZE, barcode, beep, cut, dataMatrix, drawer, feed, getPaperSizeCharsPerLine, getPaperSizePixelsWidth, globalStyles, image, line, list_thermal_printers, logo, pdf417, print_thermal_printer, qr, subtitle, table, test_thermal_printer, text, title };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tauri-plugin-thermal-printer",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "author": "luis3132",
   "description": "Plugin for Tauri to send esc/pos commands to thermal_printer",
   "type": "module",