@thermal-print/escpos 0.3.1-beta.6 → 0.4.0-beta.0

package/dist/generator.js

@@ -1,6 +1,22 @@
 import { encodeText } from "./commands/escpos";
-import { extractTextStyle, extractViewStyle, generateDividerLine, isBold, isDashedBorder, mapTextAlign, } from "./styles";
+import { baseFontLevel, calculateSpacing, columnsForLevel, extractTextStyle, extractViewStyle, FONT_LEVEL_COLUMN_UNITS, FONT_LEVEL_SIZES, generateDividerLine, isBold, isDashedBorder, mapTextAlign, resolveFontLevel, wrapText, } from "./styles";
 import { ESCPOSCommandAdapter } from "./command-adapters";
+/**
+ * Decodes base64 without Buffer, so the generator also runs in the browser.
+ * `atob` is a global in browsers and in Node >= 16.
+ */
+function base64ToBytes(base64) {
+    const decode = globalThis.atob;
+    if (typeof decode !== "function") {
+        throw new Error("base64 decoding requires a global atob() (browser, or Node >= 16)");
+    }
+    const binary = decode(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
 /**
  * Simple buffer implementation for accumulating ESC/POS commands
  */
@@ -21,10 +37,15 @@ class ESCPOSBuffer {
         this.buffer.push(...bytes);
     }
     /**
-     * Get the buffer as a Node.js Buffer
+     * Get the accumulated bytes.
+     *
+     * Uint8Array, not Buffer: the generator runs in the browser too (the pdv-web
+     * inside the Android WebView), where `Buffer` does not exist. A Node Buffer
+     * IS a Uint8Array, so consumers that already fed the result to a serial port
+     * or an IPC channel keep working.
      */
-    toBuffer() {
-        return Buffer.from(this.buffer);
+    toUint8Array() {
+        return Uint8Array.from(this.buffer);
     }
     /**
      * Get buffer size
@@ -45,18 +66,34 @@ class ESCPOSBuffer {
  * Pure JavaScript implementation - no Node.js dependencies
  */
 export class ESCPOSGenerator {
-    constructor(paperWidth = 42, encoding = "cp860", debug = false, commandAdapter, fontMode = "medium", compact = false) {
-        this.fontMode = fontMode;
+    constructor(paperWidth = 42, encoding = "cp860", debug = false, commandAdapter, fontMode = "medium", compact = false, styleMode = "legacy") {
+        /** Horizontal padding in force, in Font A columns, as a stack of View frames. */
+        this.paddingStack = [];
+        this.reservedLeft = 0;
+        this.reservedRight = 0;
+        /** Whether the next addText() starts a new printed line (so it gets the indent). */
+        this.atLineStart = true;
         this.compact = compact;
+        this.styleMode = styleMode;
         this.buffer = new ESCPOSBuffer();
         // Use provided adapter or default to ESC/POS
         this.commandAdapter = commandAdapter || new ESCPOSCommandAdapter();
+        this.baseLevel = baseFontLevel(fontMode);
+        this.currentLevel = this.baseLevel;
+        // Which ESC/POS font the document starts in. In "rico" it always follows
+        // fontMode; in "legacy" an adapter may pin its historical font so the
+        // printers already in the field keep receiving the same bytes
+        // (ESC/Bematech hardcoded Font B before DEV-2390).
+        const fontFromMode = FONT_LEVEL_SIZES[this.baseLevel].font;
+        const baseFont = styleMode === "rico"
+            ? fontFromMode
+            : this.commandAdapter.getLegacyDefaultFont?.() ?? fontFromMode;
         this.context = {
             paperWidth,
             basePaperWidth: paperWidth,
             currentAlign: "left",
             currentSize: { width: 1, height: 1 },
-            currentFont: 0,
+            currentFont: baseFont,
             currentBold: false,
             encoding,
             debug,
@@ -119,13 +156,126 @@ export class ESCPOSGenerator {
             this.applyPrintMode();
         }
     }
+    /**
+     * Move the printer to a font level (font + character size in one ESC ! ).
+     * Also re-derives the line width, since a Font B line fits 4/3 of the
+     * characters a Font A line does and a 2x2 line fits half.
+     */
+    setFontLevel(level) {
+        this.currentLevel = level;
+        const size = FONT_LEVEL_SIZES[level];
+        const changed = this.context.currentFont !== size.font ||
+            this.context.currentSize.width !== size.width ||
+            this.context.currentSize.height !== size.height;
+        this.context.currentFont = size.font;
+        this.context.currentSize = { width: size.width, height: size.height };
+        this.syncPaperWidth();
+        if (changed) {
+            this.applyPrintMode();
+        }
+    }
+    /**
+     * Set font level and bold together, emitting at most one ESC ! command.
+     * Used by "rico" mode, where both can change on the same element.
+     */
+    setPrintState(level, bold) {
+        const size = FONT_LEVEL_SIZES[level];
+        const changed = this.context.currentFont !== size.font ||
+            this.context.currentSize.width !== size.width ||
+            this.context.currentSize.height !== size.height ||
+            this.context.currentBold !== bold;
+        this.currentLevel = level;
+        this.context.currentFont = size.font;
+        this.context.currentSize = { width: size.width, height: size.height };
+        this.context.currentBold = bold;
+        this.syncPaperWidth();
+        if (changed) {
+            this.applyPrintMode();
+        }
+    }
+    /** Recomputes the usable line width from the current level and padding. */
+    syncPaperWidth() {
+        this.context.paperWidth = columnsForLevel(this.context.basePaperWidth, this.baseLevel, this.currentLevel, this.reservedLeft + this.reservedRight);
+    }
+    /** A reserved width in Font A columns, in characters of the CURRENT level. */
+    paddingChars(reserved) {
+        if (reserved <= 0)
+            return 0;
+        return Math.round(reserved / FONT_LEVEL_COLUMN_UNITS[this.currentLevel]);
+    }
+    /**
+     * The indent for a line that is starting, in characters of the CURRENT level.
+     * A right-aligned line hangs off the right edge, so its left inset is the
+     * printer's business and spaces on the left would only push it further in.
+     */
+    indentChars() {
+        if (this.context.currentAlign === "right")
+            return 0;
+        return this.paddingChars(this.reservedLeft);
+    }
+    /**
+     * Close a printed line by padding it out to the right inset.
+     *
+     * ESC a centres or right-aligns whatever bytes reach it, counting the spaces
+     * we prepended: a centred line carrying only the left indent lands half that
+     * indent to the right of the box it belongs to. Padding the right side as
+     * well makes the printer align the text inside the padded box instead of
+     * inside the paper. Left-aligned lines need nothing — they already start at
+     * the indent.
+     */
+    endTextLine() {
+        if (this.atLineStart || this.context.currentAlign === "left")
+            return;
+        const right = this.paddingChars(this.reservedRight);
+        if (right > 0) {
+            this.buffer.pushArray(encodeText(" ".repeat(right)));
+        }
+    }
+    /** Print a COMPLETE line: the left indent, the text, and the right inset. */
+    addTextLine(text) {
+        this.addText(text);
+        this.endTextLine();
+    }
+    /**
+     * Reserve horizontal padding for the children of a View (or a Page).
+     * Widths and wrapping inside the frame shrink, and every line printed while
+     * the frame is open is indented by paddingLeft.
+     */
+    pushHorizontalPadding(leftColumns, rightColumns) {
+        // Never let padding eat more than half the paper — a Page margin arrives in
+        // points and a bad value would otherwise leave a one-character column.
+        const maxTotal = Math.floor((this.context.basePaperWidth * FONT_LEVEL_COLUMN_UNITS[this.baseLevel]) / 2);
+        const available = Math.max(0, maxTotal - this.reservedLeft - this.reservedRight);
+        const left = Math.max(0, Math.min(leftColumns, available));
+        const right = Math.max(0, Math.min(rightColumns, available - left));
+        this.paddingStack.push({ left, right });
+        this.reservedLeft += left;
+        this.reservedRight += right;
+        this.syncPaperWidth();
+    }
+    /** Release the innermost horizontal padding frame. */
+    popHorizontalPadding() {
+        const frame = this.paddingStack.pop();
+        if (!frame)
+            return;
+        this.reservedLeft -= frame.left;
+        this.reservedRight -= frame.right;
+        this.syncPaperWidth();
+    }
+    /** Feed blank lines for a vertical margin/padding/height given in points. */
+    addSpacing(points) {
+        const lines = calculateSpacing(points);
+        if (lines > 0) {
+            this.addLineFeed(lines);
+        }
+    }
     /**
      * Apply current print mode (size + bold + font) using command adapter.
-     * Uses fontMode to determine Font A vs Font B base.
+     * The font comes from context.currentFont, which starts at the fontMode base
+     * and only moves in "rico" mode, when a fontSize asks for another level.
      */
     applyPrintMode() {
-        // For "small" mode, use Font B (bit 0 = 1). For "medium", use Font A (bit 0 = 0).
-        const useFontB = this.fontMode === "small";
+        const useFontB = this.context.currentFont === 1;
         const command = this.commandAdapter.getCharacterSizeCommand(this.context.currentSize.width, this.context.currentSize.height, this.context.currentBold, useFontB);
         this.buffer.pushArray(command);
     }
@@ -135,6 +285,10 @@ export class ESCPOSGenerator {
      */
     resetFormatting() {
         this.setAlign("left");
+        if (this.styleMode === "rico") {
+            this.setPrintState(this.baseLevel, false);
+            return;
+        }
         this.setBold(false);
         this.setSize({ width: 1, height: 1 });
     }
@@ -143,9 +297,10 @@ export class ESCPOSGenerator {
      */
     addText(text) {
         if (text) {
-            // Encode text to CP860 for Portuguese support
-            const encodedBytes = encodeText(text);
+            const indent = this.atLineStart ? this.indentChars() : 0;
+            const encodedBytes = encodeText(indent > 0 ? " ".repeat(indent) + text : text);
             this.buffer.pushArray(encodedBytes);
+            this.atLineStart = false;
         }
     }
     /**
@@ -158,6 +313,7 @@ export class ESCPOSGenerator {
         }
         const command = this.commandAdapter.getLineFeedCommand(count);
         this.buffer.pushArray(command);
+        this.atLineStart = true;
     }
     /**
      * Add line feed using command adapter
@@ -165,6 +321,7 @@ export class ESCPOSGenerator {
     addLineFeed(lines = 1) {
         const command = this.commandAdapter.getLineFeedCommand(lines);
         this.buffer.pushArray(command);
+        this.atLineStart = true;
     }
     /**
      * Add divider line.
@@ -172,7 +329,7 @@ export class ESCPOSGenerator {
      */
     addDivider(dashed = false) {
         this.setAlign("left");
-        const line = generateDividerLine(this.context.paperWidth, dashed);
+        const line = generateDividerLine(this.getPaperWidth(), dashed);
         this.addText(line);
         this.addNewline();
     }
@@ -201,8 +358,11 @@ export class ESCPOSGenerator {
      * Add image from base64 or data URI
      * Converts image to monochrome bitmap and prints using ESC/POS raster graphics
      * @param source - Base64 string, data URI, or object with uri property
+     * @param maxWidthColumns - width budget in characters; comes from the parent
+     *   View's percentage width. Without it an image inside a `width: "30%"` View
+     *   printed across the whole paper.
      */
-    async addImage(source) {
+    async addImage(source, maxWidthColumns) {
         try {
             // Import Jimp dynamically to avoid loading if not needed
             const { Jimp } = await import("jimp");
@@ -227,14 +387,16 @@ export class ESCPOSGenerator {
                     base64Data = base64Match[1];
                 }
             }
-            // Convert base64 to buffer
-            const imageBuffer = Buffer.from(base64Data, "base64");
-            // Load image with Jimp (v1.x API)
-            const image = await Jimp.read(imageBuffer);
+            // Convert base64 to bytes (isomorphic: no Buffer)
+            const imageBytes = base64ToBytes(base64Data);
+            // Load image with Jimp (v1.x API). Jimp.read accepts an ArrayBuffer, and
+            // `imageBytes` owns its buffer exactly, so handing over `.buffer` is a
+            // zero-copy pass of the same bytes.
+            const image = await Jimp.read(imageBytes.buffer);
             // Get paper width in pixels (assuming 8 dots per mm for 80mm thermal printer)
             // Standard 80mm paper = ~576 pixels at 8 dots/mm (72 dpi)
             // We'll use 384 pixels as max width (48 chars * 8 pixels per char)
-            const maxWidth = this.context.paperWidth * 8;
+            const maxWidth = Math.max(1, maxWidthColumns ?? this.getPaperWidth()) * 8;
             // Resize image to fit paper width while maintaining aspect ratio
             if (image.width > maxWidth) {
                 await image.resize({ w: maxWidth });
@@ -278,46 +440,86 @@ export class ESCPOSGenerator {
         }
     }
     /**
-     * Apply text styles from style object.
-     * When fontMode is set, fontSize from components is IGNORED for font selection.
-     * The fontMode determines the global ESC/POS font (small/medium/large).
+     * Apply text styles from a style object.
+     *
+     * @param style - the element's own style
+     * @param options.inheritedAlign - alignment from an ancestor View's alignItems,
+     *   used only when the element does not set textAlign itself. Before DEV-2390
+     *   `alignItems: "center"` on a View simply never reached its children.
+     * @param options.text - the text about to be printed. In "rico" mode it is
+     *   used to check whether a 2x2 line actually fits; on 58mm paper a double
+     *   size title only has ~16 columns, and wrapping it looks worse than
+     *   printing it one level down.
      */
-    applyTextStyle(style) {
+    applyTextStyle(style, options) {
         const textStyle = extractTextStyle(style);
-        // Set alignment
-        const align = mapTextAlign(textStyle.textAlign);
+        // Set alignment — the element's own textAlign wins over the inherited one
+        const align = style?.textAlign
+            ? mapTextAlign(style.textAlign)
+            : options?.inheritedAlign ?? "left";
         this.setAlign(align);
-        // Set bold
         const bold = isBold(textStyle);
-        this.setBold(bold);
-        // Font mode determines the fixed size — fontSize from components is ignored
-        const size = this.getFontModeSize();
-        this.setSize(size);
+        if (this.styleMode !== "rico") {
+            // Legacy: fontSize is ignored, the whole document prints at fontMode size
+            this.setBold(bold);
+            this.setSize({ width: 1, height: 1 });
+            return;
+        }
+        this.setPrintState(this.resolveTextLevel(textStyle.fontSize, options?.text), bold);
     }
     /**
-     * Get the ESC/POS character size based on the global fontMode.
-     * - small: Font B 1x1 (64 cols)
-     * - medium: Font A 1x1 (48 cols)
+     * The font level a piece of text should print at, honouring the 2x2 fallback.
+     * Public so the row layout can size its columns before printing them.
      */
-    getFontModeSize() {
-        return { width: 1, height: 1 };
+    resolveTextLevel(fontSize, text) {
+        const level = resolveFontLevel(this.baseLevel, fontSize);
+        if (level === 2 && text) {
+            const doubleWidth = columnsForLevel(this.context.basePaperWidth, this.baseLevel, 2, this.reservedLeft + this.reservedRight);
+            if (wrapText(text, doubleWidth).length > 1) {
+                return 1;
+            }
+        }
+        return level;
+    }
+    /** The font level currently loaded in the printer. */
+    getFontLevel() {
+        return this.currentLevel;
+    }
+    /** The document's base font level (what fontMode asked for). */
+    getBaseFontLevel() {
+        return this.baseLevel;
+    }
+    /** Whether richer styling (fontSize, spacing, per-column styles) is enabled. */
+    isRichStyleMode() {
+        return this.styleMode === "rico";
     }
     /**
      * Apply spacing from view style
      */
     applyViewSpacing(style, type) {
         const viewStyle = extractViewStyle(style);
+        const rich = this.styleMode === "rico";
+        const padding = viewStyle.padding;
+        const margin = viewStyle.margin;
+        // CSS box model order, the same one @thermal-print/pdf follows:
+        // margin -> border -> padding -> content -> padding -> border -> margin
         if (type === "before") {
-            // Apply top border
+            if (rich)
+                this.addSpacing(viewStyle.marginTop ?? margin);
             if (viewStyle.borderTop) {
                 this.addDivider(isDashedBorder(viewStyle.borderTop));
             }
+            if (rich)
+                this.addSpacing(viewStyle.paddingTop ?? padding);
         }
         else {
-            // Apply bottom border
+            if (rich)
+                this.addSpacing(viewStyle.paddingBottom ?? padding);
             if (viewStyle.borderBottom) {
                 this.addDivider(isDashedBorder(viewStyle.borderBottom));
             }
+            if (rich)
+                this.addSpacing(viewStyle.marginBottom ?? margin);
         }
     }
     /**
@@ -354,7 +556,7 @@ export class ESCPOSGenerator {
     }
     /**
      * Add raw ESC/POS command
-     * @param data - Raw buffer data to send to printer
+     * @param data - Raw bytes to send to printer
      */
     addRawCommand(data) {
         this.buffer.pushArray(Array.from(data));
@@ -363,8 +565,11 @@ export class ESCPOSGenerator {
      * Get the final buffer
      */
     getBuffer() {
-        const buffer = this.buffer.toBuffer();
-        // Remove leading line feeds (0x0A)
+        const buffer = this.buffer.toUint8Array();
+        // Defensive: drop leading line feeds so a receipt could never start with
+        // blank paper. The buffer opens with the adapter's init command, so in
+        // practice nothing is ever stripped here — in particular a marginTop on the
+        // first View survives, which the "rico" spacing tests rely on.
         let start = 0;
         while (start < buffer.length && buffer[start] === 0x0a) {
             start++;

package/dist/index.d.ts

@@ -3,16 +3,17 @@
  *
  * ESC/POS command generation and thermal printer control
  *
- * Main API: printNodesToESCPOS(printNode, options) -> Buffer
+ * Main API: printNodesToESCPOS(printNode, options) -> Uint8Array
  */
 export { printNodesToESCPOS } from './converter';
-export type { PrintNodeToESCPOSOptions, FontMode } from './converter';
+export type { PrintNodeToESCPOSOptions, FontMode, StyleMode } from './converter';
 export { ESCPOSGenerator } from './generator';
 export { TreeTraverser } from './traverser';
 export type { CommandAdapter, CharacterSize } from './command-adapters/types';
 export { ESCPOSCommandAdapter } from './command-adapters/escpos-adapter';
 export { ESCBematechCommandAdapter } from './command-adapters/escbematech-adapter';
-export { extractTextStyle, extractViewStyle, isBold, mapFontSizeToESCPOS, mapTextAlign, calculateSpacing, isDashedBorder, generateDividerLine, mergeStyles, parseWidth, alignTextInColumn, wrapText, } from './styles';
+export { extractTextStyle, extractViewStyle, isBold, baseFontLevel, fontSizeLevelDelta, resolveFontLevel, mapFontSizeToESCPOS, columnsForLevel, FONT_LEVEL_SIZES, FONT_LEVEL_COLUMN_UNITS, POINTS_PER_LINE, POINTS_PER_COLUMN, mapTextAlign, parseSize, parsePercentageWidth, calculateSpacing, calculateHorizontalSpacing, isDashedBorder, generateDividerLine, mergeStyles, parseWidth, distributeColumnWidths, distributeGaps, alignTextInColumn, wrapText, } from './styles';
+export type { ESCPOSFontSize, FontLevel } from './styles';
 export { encodeCP860 } from './encodings/cp860';
 export type * from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,YAAY,EAAE,wBAAwB,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAGtE,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AACzE,OAAO,EAAE,yBAAyB,EAAE,MAAM,wCAAwC,CAAC;AAGnF,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,MAAM,EACN,mBAAmB,EACnB,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,mBAAmB,EACnB,WAAW,EACX,UAAU,EACV,iBAAiB,EACjB,QAAQ,GACT,MAAM,UAAU,CAAC;AAGlB,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhD,mBAAmB,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,YAAY,EAAE,wBAAwB,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGjF,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AACzE,OAAO,EAAE,yBAAyB,EAAE,MAAM,wCAAwC,CAAC;AAGnF,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,MAAM,EACN,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,EACnB,eAAe,EACf,gBAAgB,EAChB,uBAAuB,EACvB,eAAe,EACf,iBAAiB,EACjB,YAAY,EACZ,SAAS,EACT,oBAAoB,EACpB,gBAAgB,EAChB,0BAA0B,EAC1B,cAAc,EACd,mBAAmB,EACnB,WAAW,EACX,UAAU,EACV,sBAAsB,EACtB,cAAc,EACd,iBAAiB,EACjB,QAAQ,GACT,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAG1D,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhD,mBAAmB,SAAS,CAAC"}

package/dist/index.js

@@ -3,7 +3,7 @@
  *
  * ESC/POS command generation and thermal printer control
  *
- * Main API: printNodesToESCPOS(printNode, options) -> Buffer
+ * Main API: printNodesToESCPOS(printNode, options) -> Uint8Array
  */
 // Main conversion function
 export { printNodesToESCPOS } from './converter';
@@ -13,6 +13,6 @@ export { TreeTraverser } from './traverser';
 export { ESCPOSCommandAdapter } from './command-adapters/escpos-adapter';
 export { ESCBematechCommandAdapter } from './command-adapters/escbematech-adapter';
 // Style utilities
-export { extractTextStyle, extractViewStyle, isBold, mapFontSizeToESCPOS, mapTextAlign, calculateSpacing, isDashedBorder, generateDividerLine, mergeStyles, parseWidth, alignTextInColumn, wrapText, } from './styles';
+export { extractTextStyle, extractViewStyle, isBold, baseFontLevel, fontSizeLevelDelta, resolveFontLevel, mapFontSizeToESCPOS, columnsForLevel, FONT_LEVEL_SIZES, FONT_LEVEL_COLUMN_UNITS, POINTS_PER_LINE, POINTS_PER_COLUMN, mapTextAlign, parseSize, parsePercentageWidth, calculateSpacing, calculateHorizontalSpacing, isDashedBorder, generateDividerLine, mergeStyles, parseWidth, distributeColumnWidths, distributeGaps, alignTextInColumn, wrapText, } from './styles';
 // Encodings
 export { encodeCP860 } from './encodings/cp860';

package/dist/styles.d.ts

@@ -20,25 +20,76 @@ export interface ESCPOSFontSize {
     height: number;
 }
 /**
- * Maps fontSize to ESC/POS font selection + character size multipliers
+ * The three visual sizes an ESC ! command can reach on the printers we support.
  *
- * Three visual levels using standard ESC/POS fonts:
- * - Condensada: Font B 1x1 (9x17, 64 cols) — fontSize <= 10
- * - Normal:     Font A 1x1 (12x24, 48 cols) — fontSize 11-19
- * - Expandida:  Font A 2x2 (12x24, 24 cols) — fontSize >= 20
+ * Level 0 — Font B 1x1: the condensed font.
+ * Level 1 — Font A 1x1: the normal font.
+ * Level 2 — Font A 2x2: the double-size font (ESC ! caps out at 2x2).
  *
- * Note: ESC ! command only supports up to 2x2 character size.
+ * The number of columns each level fits is NOT hardcoded here: it is derived
+ * from the paperWidth the caller passes, which is already calibrated per
+ * printer/paper (42 for Font A on 80mm, 56 for Font B on 80mm, 32 on 58mm).
  */
-export declare function mapFontSizeToESCPOS(fontSize?: number | string): ESCPOSFontSize;
+export type FontLevel = 0 | 1 | 2;
+export declare const FONT_LEVEL_SIZES: Record<FontLevel, ESCPOSFontSize>;
+/**
+ * How many Font A 1x1 columns one character of each level occupies.
+ * Font B fits 4/3 of the characters Font A does (56 vs 42 on the MP-4200 TH),
+ * so one Font B character is 3/4 of a column.
+ */
+export declare const FONT_LEVEL_COLUMN_UNITS: Record<FontLevel, number>;
+/** The level a document sits at before any per-element fontSize is applied. */
+export declare function baseFontLevel(fontMode: "small" | "medium"): FontLevel;
+/**
+ * How many levels a fontSize moves relative to the document's base level.
+ *
+ * fontSize is RELATIVE, not absolute: the same `fontSize: 22` means "one step
+ * bigger than this document's body text", so a receipt printed in `fontMode:
+ * "small"` does not suddenly jump to double size.
+ */
+export declare function fontSizeLevelDelta(fontSize?: number | string): -1 | 0 | 1;
+/** Clamps base level + fontSize delta into the three levels ESC ! can express. */
+export declare function resolveFontLevel(baseLevel: FontLevel, fontSize?: number | string): FontLevel;
+/**
+ * Maps fontSize to the ESC/POS font + character size multipliers of its level.
+ *
+ * @param fontSize - fontSize from the component style (relative to baseLevel)
+ * @param baseLevel - the document's base level (see baseFontLevel)
+ */
+export declare function mapFontSizeToESCPOS(fontSize?: number | string, baseLevel?: FontLevel): ESCPOSFontSize;
+/**
+ * Characters that fit on one line at `level`, on a paper that fits
+ * `baseColumns` characters at `baseLevel`.
+ *
+ * @param reservedColumns - columns taken by horizontal padding, in Font A units
+ */
+export declare function columnsForLevel(baseColumns: number, baseLevel: FontLevel, level: FontLevel, reservedColumns?: number): number;
 /**
  * Maps textAlign to ESC/POS alignment
  */
 export declare function mapTextAlign(textAlign?: string): "left" | "center" | "right";
 /**
- * Calculates spacing (margin/padding) in lines
- * Approximates pixels to line feeds
+ * Points per printed line, and per character column.
+ *
+ * margin/padding/height arrive in POINTS, the same unit @react-pdf/renderer
+ * and @thermal-print/pdf use — a 10pt body line is 12pt tall with the default
+ * 1.2 line height, and an 80mm page is 226pt wide for 42 Font A columns.
+ * Converting with those two constants is what makes a `marginTop: 12` produce
+ * the same visual gap in the PDF preview and on the thermal printer.
  */
-export declare function calculateSpacing(value?: number): number;
+export declare const POINTS_PER_LINE = 12;
+export declare const POINTS_PER_COLUMN: number;
+/** Parses a size that may arrive as a number or as "12px" / "12pt". */
+export declare function parseSize(value?: number | string): number;
+/**
+ * Converts a vertical spacing (margin/padding/height) in points to line feeds.
+ * Capped at 6 lines so a stray `marginTop: 400` cannot eject a page of paper.
+ */
+export declare function calculateSpacing(value?: number | string): number;
+/** Converts a horizontal spacing (padding left/right) in points to columns. */
+export declare function calculateHorizontalSpacing(value?: number | string): number;
+/** Parses a percentage width ("30%") into a fraction (0.3). Returns undefined otherwise. */
+export declare function parsePercentageWidth(width?: string | number): number | undefined;
 /**
  * Determines if a border is dashed
  */
@@ -56,6 +107,21 @@ export declare function mergeStyles(...styles: any[]): any;
  * Uses Math.round() to minimize rounding errors
  */
 export declare function parseWidth(width: string | number | undefined, totalWidth: number): number;
+/**
+ * Splits the row width across its columns.
+ *
+ * Columns with an explicit width (fixed or percentage) take it; whatever is
+ * left over is shared evenly by the columns that declared none. Before
+ * DEV-2390 a column without a width got `parseWidth(undefined) === totalWidth`,
+ * so a three-column row asked for three full paper widths and printed each
+ * cell padded to the whole line.
+ */
+export declare function distributeColumnWidths(widths: (string | number | undefined)[], totalWidth: number): number[];
+/**
+ * Splits the free space of a space-between row across its gaps.
+ * Every gap gets at least one space; the remainder goes to the leftmost gaps.
+ */
+export declare function distributeGaps(contentWidth: number, totalWidth: number, gapCount: number): number[];
 /**
  * Aligns text within a column width (using CP860 byte length for accurate padding)
  */

package/dist/styles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"styles.d.ts","sourceRoot":"","sources":["../src/styles.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAE3D;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,GAAG,GAAG,SAAS,CAOtD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,GAAG,GAAG,SAAS,CAoBtD;AAED;;GAEG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAOhD;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,cAAc,CAiB9E;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAI5E;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAIvD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,UAAQ,GAAG,MAAM,CAGzE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,MAAM,EAAE,GAAG,EAAE,GAAG,GAAG,CAEjD;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,EAClC,UAAU,EAAE,MAAM,GACjB,MAAM,CAaR;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,GACjC,MAAM,CA8BR;AAED;;GAEG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAyB9D"}
+{"version":3,"file":"styles.d.ts","sourceRoot":"","sources":["../src/styles.ts"],"names":[],"mappings":"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"}