portakal 0.2.0 → 0.3.0

package/README.md

@@ -4,7 +4,7 @@
   <br><br>
   <b style="font-size: 2em;">portakal</b>
   <br><br>
-  Universal printer language SDK — TSC, ZPL, EPL, ESC/POS and more.
+  Universal printer language SDK — 9 languages, one API.
   <br>
   Text, barcodes, QR codes, images, shapes — anything you can print.
   <br>
@@ -14,6 +14,8 @@
   <a href="https://npmjs.com/package/portakal"><img src="https://img.shields.io/npm/dm/portakal?style=flat&colorA=18181B&colorB=F97316" alt="npm downloads"></a>
   <a href="https://bundlephobia.com/result?p=portakal"><img src="https://img.shields.io/bundlephobia/minzip/portakal?style=flat&colorA=18181B&colorB=F97316" alt="bundle size"></a>
   <a href="https://github.com/productdevbook/portakal/blob/main/LICENSE"><img src="https://img.shields.io/github/license/productdevbook/portakal?style=flat&colorA=18181B&colorB=F97316" alt="license"></a>
+  <br><br>
+  <a href="https://portakal.productdevbook.com">Playground</a> · <a href="https://github.com/productdevbook/portakal">GitHub</a> · <a href="https://npmjs.com/package/portakal">npm</a>
 </p>
 
 > [!NOTE]
@@ -94,6 +96,28 @@ myLabel.toEPL(); // Eltron EPL2 — LP/TLP 2824, GX420, ZD220
 myLabel.toESCPOS(); // ESC/POS — Epson, Bixolon, Star, Citizen
 ```
 
+### Tree Shaking
+
+Import only what you need — each module is a separate entry point:
+
+```ts
+import { compileToTSC } from "portakal/tsc";
+import { compileToZPL } from "portakal/zpl";
+import { compileToEPL } from "portakal/epl";
+import { compileToESCPOS } from "portakal/escpos";
+import { compileToCPCL } from "portakal/cpcl";
+import { compileToDPL } from "portakal/dpl";
+import { compileToSBPL } from "portakal/sbpl";
+import { compileToStarPRNT } from "portakal/starprnt";
+import { compileToIPL } from "portakal/ipl";
+import { imageToMonochrome } from "portakal/image";
+import { formatPair, separator } from "portakal/receipt";
+import { encodeTextForPrinter } from "portakal/encoding";
+import { getProfile } from "portakal/profiles";
+import { chunkedWrite } from "portakal/transport";
+import { renderPreview } from "portakal/preview";
+```
+
 ### Software-rendered barcode/QR (with etiket)
 
 For pixel-perfect output, styled QR codes, or when the printer doesn't support a format natively:
@@ -376,6 +400,7 @@ await usbDevice.transferOut(endpointNumber, escpos);
 
 - Zero dependencies — pure computation, no native modules, no node-gyp
 - **9 printer languages** — TSC, ZPL, EPL, CPCL, DPL, SBPL, ESC/POS, Star PRNT, IPL
+- **Tree-shakeable** — sub-path exports for every module (`portakal/tsc`, `portakal/image`, etc.)
 - Pure ESM, edge-runtime compatible (Cloudflare Workers, Deno, Bun)
 - TypeScript-first with strict types (tsgo)
 - Transport-agnostic — generates commands, you handle the connection

package/dist/_chunks/types.d.mts

@@ -0,0 +1,169 @@
+//#region src/types.d.ts
+/** Unit of measurement for label dimensions */
+type Unit = "mm" | "inch" | "dot";
+/** Print orientation / rotation */
+type Rotation = 0 | 90 | 180 | 270;
+/** Text alignment */
+type Alignment = "left" | "center" | "right";
+/** Dithering algorithm for image processing */
+type DitherAlgorithm = "threshold" | "floyd-steinberg" | "atkinson" | "ordered";
+/** Label configuration */
+interface LabelConfig {
+  /** Label width */
+  width: number;
+  /** Label height (optional for receipt/continuous mode) */
+  height?: number;
+  /** Unit of measurement (default: "mm") */
+  unit?: Unit;
+  /** Printer DPI (default: 203) */
+  dpi?: number;
+  /** Gap between labels in mm (label printers only) */
+  gap?: number;
+  /** Print speed (1-10, printer-dependent) */
+  speed?: number;
+  /** Print darkness/density (0-15) */
+  density?: number;
+  /** Print direction */
+  direction?: 0 | 1;
+  /** Number of copies */
+  copies?: number;
+}
+/** Text element options */
+interface TextOptions {
+  /** X position */
+  x?: number;
+  /** Y position */
+  y?: number;
+  /** Font name or ID */
+  font?: string;
+  /** Font size or magnification */
+  size?: number;
+  /** Horizontal magnification (1-10) */
+  xScale?: number;
+  /** Vertical magnification (1-10) */
+  yScale?: number;
+  /** Rotation */
+  rotation?: Rotation;
+  /** Bold */
+  bold?: boolean;
+  /** Underline */
+  underline?: boolean;
+  /** Reverse (white on black) */
+  reverse?: boolean;
+  /** Alignment */
+  align?: Alignment;
+  /** Max width for word-wrap (in dots) */
+  maxWidth?: number;
+  /** Line spacing (in dots) */
+  lineSpacing?: number;
+}
+/** Image element options */
+interface ImageOptions {
+  /** X position */
+  x?: number;
+  /** Y position */
+  y?: number;
+  /** Target width in dots (auto-scale if set) */
+  width?: number;
+  /** Target height in dots (auto-scale if set) */
+  height?: number;
+  /** Dithering algorithm (default: "threshold") */
+  dither?: DitherAlgorithm;
+  /** Threshold for monochrome conversion (0-255, default: 128) */
+  threshold?: number;
+}
+/** Box/rectangle element options */
+interface BoxOptions {
+  /** X position */
+  x: number;
+  /** Y position */
+  y: number;
+  /** Width */
+  width: number;
+  /** Height */
+  height: number;
+  /** Border thickness in dots (default: 1) */
+  thickness?: number;
+  /** Corner radius in dots */
+  radius?: number;
+}
+/** Line element options */
+interface LineOptions {
+  /** Start X */
+  x1: number;
+  /** Start Y */
+  y1: number;
+  /** End X */
+  x2: number;
+  /** End Y */
+  y2: number;
+  /** Line thickness in dots (default: 1) */
+  thickness?: number;
+}
+/** Circle element options */
+interface CircleOptions {
+  /** Center X */
+  x: number;
+  /** Center Y */
+  y: number;
+  /** Diameter in dots */
+  diameter: number;
+  /** Border thickness in dots (default: 1) */
+  thickness?: number;
+}
+/** 1-bit monochrome bitmap (universal intermediate format for images) */
+interface MonochromeBitmap {
+  /** Packed 1-bit pixel data, row-major, MSB-first */
+  data: Uint8Array;
+  /** Width in pixels */
+  width: number;
+  /** Height in pixels */
+  height: number;
+  /** Bytes per row = ceil(width / 8) */
+  bytesPerRow: number;
+}
+/** Internal label element union type */
+type LabelElement = {
+  type: "text";
+  content: string;
+  options: TextOptions;
+} | {
+  type: "image";
+  bitmap: MonochromeBitmap;
+  options: ImageOptions;
+} | {
+  type: "box";
+  options: BoxOptions;
+} | {
+  type: "line";
+  options: LineOptions;
+} | {
+  type: "circle";
+  options: CircleOptions;
+} | {
+  type: "raw";
+  content: string | Uint8Array;
+};
+/** Resolved label configuration with computed values */
+interface ResolvedLabel {
+  /** Width in dots */
+  widthDots: number;
+  /** Height in dots (0 for continuous/receipt) */
+  heightDots: number;
+  /** DPI */
+  dpi: number;
+  /** Gap in dots */
+  gapDots: number;
+  /** Speed */
+  speed: number;
+  /** Density */
+  density: number;
+  /** Direction */
+  direction: 0 | 1;
+  /** Copies */
+  copies: number;
+  /** All elements to render */
+  elements: LabelElement[];
+}
+//#endregion
+export { ImageOptions as a, LineOptions as c, Rotation as d, TextOptions as f, DitherAlgorithm as i, MonochromeBitmap as l, BoxOptions as n, LabelConfig as o, Unit as p, CircleOptions as r, LabelElement as s, Alignment as t, ResolvedLabel as u };

package/dist/encoding.d.mts

@@ -0,0 +1,42 @@
+//#region src/encoding.d.ts
+/**
+ * UTF-8 to ESC/POS code page encoding engine.
+ *
+ * Accepts UTF-8 text and produces encoded byte segments with minimal
+ * code page switching. Solves the #1 pain point across all thermal
+ * printer libraries (200+ issues in the ecosystem).
+ */
+/** ESC/POS code page ID → ESC t parameter value */
+interface CodePage {
+  /** ESC t parameter value */
+  id: number;
+  /** Human-readable name */
+  name: string;
+  /** Character mapping: Unicode code point → byte value (0x80-0xFF range) */
+  chars: Map<number, number>;
+}
+/** Encoded segment — a chunk of bytes with an associated code page switch */
+interface EncodedSegment {
+  /** Code page ID to switch to (ESC t n), or -1 for ASCII (no switch needed) */
+  codePage: number;
+  /** Encoded bytes */
+  data: Uint8Array;
+}
+/** Available code pages in priority order */
+declare const CODE_PAGES: CodePage[];
+/**
+ * Encode a UTF-8 string into ESC/POS byte segments with optimal code page switching.
+ *
+ * Strategy: greedily encode as much as possible in the current code page before switching.
+ * ASCII (0x20-0x7E) never requires a code page switch.
+ */
+declare function encodeText(text: string): EncodedSegment[];
+/**
+ * Encode text and return complete ESC/POS bytes including code page switch commands.
+ * Ready to send to printer.
+ */
+declare function encodeTextForPrinter(text: string): Uint8Array;
+/** Check if a string contains only ASCII printable characters */
+declare function isASCII(text: string): boolean;
+//#endregion
+export { CODE_PAGES, CodePage, EncodedSegment, encodeText, encodeTextForPrinter, isASCII };

package/dist/encoding.mjs

@@ -0,0 +1 @@
+function e(e){let t=new Map;for(let[n,r]of e)t.set(n,r);return t}const t=[[199,128],[252,129],[233,130],[226,131],[228,132],[224,133],[229,134],[231,135],[234,136],[235,137],[232,138],[239,139],[238,140],[236,141],[196,142],[197,143],[201,144],[230,145],[198,146],[244,147],[246,148],[242,149],[251,150],[249,151],[255,152],[214,153],[220,154],[162,155],[163,156],[165,157],[223,225],[181,230],[241,164],[209,165]],n=[...t,[8364,213]],r=[[8364,128],[8218,130],[402,131],[8222,132],[8230,133],[8224,134],[8225,135],[710,136],[8240,137],[352,138],[8249,139],[338,140],[381,142],[8216,145],[8217,146],[8220,147],[8221,148],[8226,149],[8211,150],[8212,151],[732,152],[8482,153],[353,154],[8250,155],[339,156],[382,158],[376,159],...Array.from({length:96},(e,t)=>[160+t,160+t])],i=[...Array.from({length:32},(e,t)=>[1040+t,128+t]),...Array.from({length:16},(e,t)=>[1072+t,160+t]),...Array.from({length:16},(e,t)=>[1088+t,224+t]),[1025,240],[1105,241],[1028,242],[1108,243],[1031,244],[1111,245],[1038,246],[1118,247]],a=[...t.filter(([e])=>e!==223),[286,160],[287,161],[304,152],[305,141],[350,158],[351,159]],o=[{id:0,name:`CP437`,chars:e(t)},{id:19,name:`CP858`,chars:e(n)},{id:16,name:`CP1252`,chars:e(r)},{id:17,name:`CP866`,chars:e(i)},{id:13,name:`CP857`,chars:e(a)}];function s(e){for(let t of o){let n=t.chars.get(e);if(n!==void 0)return{cpId:t.id,byte:n}}return null}function c(e){let t=[],n=-1,r=[];function i(){r.length>0&&(t.push({codePage:n,data:new Uint8Array(r)}),r=[])}for(let t=0;t<e.length;t++){let a=e.codePointAt(t);if(a>=32&&a<=126){r.push(a);continue}if(a===10||a===13){r.push(a);continue}let o=s(a);o?(o.cpId!==n&&(i(),n=o.cpId),r.push(o.byte)):r.push(63),a>65535&&t++}return i(),t}function l(e){let t=c(e),n=[];for(let e of t)e.codePage>=0&&n.push(new Uint8Array([27,116,e.codePage])),n.push(e.data);let r=0;for(let e of n)r+=e.length;let i=new Uint8Array(r),a=0;for(let e of n)i.set(e,a),a+=e.length;return i}function u(e){for(let t=0;t<e.length;t++){let n=e.charCodeAt(t);if((n<32||n>126)&&n!==10&&n!==13)return!1}return!0}export{o as CODE_PAGES,c as encodeText,l as encodeTextForPrinter,u as isASCII};

package/dist/image.d.mts

@@ -0,0 +1,22 @@
+import { i as DitherAlgorithm, l as MonochromeBitmap } from "./_chunks/types.mjs";
+
+//#region src/image.d.ts
+/** Convert RGBA pixel data to grayscale (BT.601 luminance, alpha composited on white) */
+declare function rgbaToGrayscale(rgba: Uint8Array | Uint8ClampedArray, width: number, height: number): Uint8Array;
+/** Simple threshold: pixels below threshold become black */
+declare function ditherThreshold(gray: Uint8Array, width: number, height: number, threshold?: number): Uint8Array;
+/** Floyd-Steinberg error diffusion dithering */
+declare function ditherFloydSteinberg(gray: Uint8Array, width: number, height: number): Uint8Array;
+/** Atkinson dithering — preserves more contrast (75% error propagation) */
+declare function ditherAtkinson(gray: Uint8Array, width: number, height: number): Uint8Array;
+/** Ordered dithering using 4x4 Bayer matrix */
+declare function ditherOrdered(gray: Uint8Array, width: number, height: number): Uint8Array;
+/** Pack 8-bit dithered pixels (0 or 255) into 1-bit MonochromeBitmap */
+declare function packBitmap(dithered: Uint8Array, width: number, height: number): MonochromeBitmap;
+/** Convert RGBA image to MonochromeBitmap with specified dithering algorithm */
+declare function imageToMonochrome(rgba: Uint8Array | Uint8ClampedArray, width: number, height: number, options?: {
+  dither?: DitherAlgorithm;
+  threshold?: number;
+}): MonochromeBitmap;
+//#endregion
+export { ditherAtkinson, ditherFloydSteinberg, ditherOrdered, ditherThreshold, imageToMonochrome, packBitmap, rgbaToGrayscale };

package/dist/image.mjs

@@ -0,0 +1 @@
+function e(e,t,n){let r=new Uint8Array(t*n);for(let i=0;i<t*n;i++){let t=e[i*4],n=e[i*4+1],a=e[i*4+2],o=e[i*4+3],s=(t*o+255*(255-o))/255,c=(n*o+255*(255-o))/255,l=(a*o+255*(255-o))/255;r[i]=Math.round(.299*s+.587*c+.114*l)}return r}function t(e,t,n,r=128){let i=new Uint8Array(e.length);for(let t=0;t<e.length;t++)i[t]=e[t]<r?0:255;return i}function n(e,t,n){let r=new Float32Array(e.length);for(let t=0;t<e.length;t++)r[t]=e[t];for(let e=0;e<n;e++){let i=(e&1)==0,a=i?0:t-1,o=i?t:-1,s=i?1:-1;for(let i=a;i!==o;i+=s){let a=e*t+i,o=r[a],c=o<128?0:255;r[a]=c;let l=o-c,u=i+s;u>=0&&u<t&&(r[e*t+u]+=l*7/16),e+1<n&&(i-s>=0&&i-s<t&&(r[(e+1)*t+i-s]+=l*3/16),r[(e+1)*t+i]+=l*5/16,u>=0&&u<t&&(r[(e+1)*t+u]+=l*1/16))}}let i=new Uint8Array(e.length);for(let t=0;t<e.length;t++)i[t]=r[t]<128?0:255;return i}function r(e,t,n){let r=new Float32Array(e.length);for(let t=0;t<e.length;t++)r[t]=e[t];for(let e=0;e<n;e++)for(let i=0;i<t;i++){let a=e*t+i,o=r[a],s=o<128?0:255;r[a]=s;let c=(o-s)/8;i+1<t&&(r[a+1]+=c),i+2<t&&(r[a+2]+=c),e+1<n&&(i-1>=0&&(r[(e+1)*t+i-1]+=c),r[(e+1)*t+i]+=c,i+1<t&&(r[(e+1)*t+i+1]+=c)),e+2<n&&(r[(e+2)*t+i]+=c)}let i=new Uint8Array(e.length);for(let t=0;t<e.length;t++)i[t]=r[t]<128?0:255;return i}const i=[[0,8,2,10],[12,4,14,6],[3,11,1,9],[15,7,13,5]];function a(e,t,n){let r=new Uint8Array(e.length);for(let a=0;a<n;a++)for(let n=0;n<t;n++){let o=i[a%4][n%4]/16*255;r[a*t+n]=e[a*t+n]>o?255:0}return r}function o(e,t,n){let r=Math.ceil(t/8),i=new Uint8Array(r*n);for(let a=0;a<n;a++)for(let n=0;n<t;n++)if(e[a*t+n]===0){let e=a*r+Math.floor(n/8),t=7-n%8;i[e]|=1<<t}return{data:i,width:t,height:n,bytesPerRow:r}}function s(i,s,c,l={}){let u=e(i,s,c),d=l.dither??`threshold`,f;switch(d){case`floyd-steinberg`:f=n(u,s,c);break;case`atkinson`:f=r(u,s,c);break;case`ordered`:f=a(u,s,c);break;default:f=t(u,s,c,l.threshold??128);break}return o(f,s,c)}export{r as ditherAtkinson,n as ditherFloydSteinberg,a as ditherOrdered,t as ditherThreshold,s as imageToMonochrome,o as packBitmap,e as rgbaToGrayscale};