@connectedxm/zpl-generator 0.0.1

package/README.md

@@ -0,0 +1,422 @@
+# ZPL Generator
+
+A TypeScript library for generating ZPL (Zebra Programming Language) code from structured badge configurations. This library provides type-safe APIs for creating thermal printer labels with text fields, barcodes, and QR codes.
+
+## Features
+
+- **Type-Safe Configuration**: Full TypeScript support with Zod validation schemas
+- **Thermal Badge Support**: Generate ZPL for thermal transfer and direct thermal printers
+- **Multiple Block Types**: 
+  - Text fields with advanced formatting (word wrapping, alignment, vertical positioning)
+  - Barcodes (Code 128)
+  - QR codes with configurable error correction
+- **Comprehensive Printer Settings**: Control print speed, darkness, orientation, media type, and more
+- **Validation**: Built-in validation with detailed error messages
+- **Word Wrapping**: Accurate line counting with optional word-width measurements for precise text layout
+
+## Installation
+
+```bash
+npm install cxm-zpl-generator
+```
+
+## Quick Start
+
+```typescript
+import { generate } from 'cxm-zpl-generator';
+import {
+    ThermalBadge,
+    MediaType,
+    ThermalMediaType,
+    PrintOrientation,
+    FontOrientation,
+    TextAlignment,
+    VerticalAlignment,
+    PostPrintMode,
+    PrepeelMode,
+    AllMediaMode,
+    BackfeedAction,
+    ReverseMode,
+    PrintDensityAdjustment,
+} from 'cxm-zpl-generator';
+
+const badge: ThermalBadge = {
+    type: 'thermal',
+    tearOffAdjustment: 0,
+    backfeedActions: BackfeedAction.Normal,
+    media: MediaType.NonContinuousMarkSensing,
+    mediaOffset: 0,
+    thermalMediaType: ThermalMediaType.ThermalTransfer,
+    printOrientation: PrintOrientation.Normal,
+    mirror: MirrorMode.Normal,
+    labelHomeX: 20,
+    labelHomeY: 0,
+    printDensityAdjustment: PrintDensityAdjustment.Normal,
+    printSpeed: 1,
+    slewSpeed: 1,
+    backfeedSpeed: 1,
+    darkness: 30,
+    reverse: ReverseMode.Disable,
+    postPrintMode: PostPrintMode.TearOff,
+    prepeel: PrepeelMode.NoPrepeel,
+    printWidth: 900,
+    labelLength: 600,
+    allMedia: AllMediaMode.ContinuousOnly,
+    blocks: [
+        {
+            type: 'field',
+            name: 'title',
+            x: 0,
+            y: 100,
+            data: 'Hello World',
+            font: 'A',
+            fontHeight: 100,
+            maxWidth: 900,
+            maxLines: 1,
+            lineSpacing: 100,
+            alignment: TextAlignment.Center,
+            fontOrientation: FontOrientation.NoRotation,
+            hangingIndent: 0,
+            verticalAlignment: VerticalAlignment.Start,
+        },
+    ],
+};
+
+const zpl = generate(badge);
+console.log(zpl);
+// Output: ^XA
+// ~TA000
+// ~JSN
+// ...
+```
+
+## API Reference
+
+### `generate(badge: Badge): string`
+
+Generates ZPL code from a badge configuration.
+
+**Parameters:**
+- `badge`: A validated `Badge` object (must be of type `'thermal'`)
+
+**Returns:** A string containing valid ZPL code
+
+**Example:**
+```typescript
+const zpl = generate(badge);
+// Send zpl to your Zebra printer
+```
+
+### `validateBadge(data: unknown)`
+
+Validates a badge configuration object. Returns a Zod `SafeParseReturnType` with success/error information.
+
+**Example:**
+```typescript
+import { validateBadge } from 'cxm-zpl-generator';
+
+const result = validateBadge(jsonData);
+if (result.success) {
+    const badge = result.data; // Type-safe Badge object
+    const zpl = generate(badge);
+} else {
+    console.error(result.error.errors);
+}
+```
+
+### `validateBadgeOrThrow(data: unknown)`
+
+Validates a badge configuration and throws a `ZodError` if validation fails.
+
+**Example:**
+```typescript
+import { validateBadgeOrThrow } from 'cxm-zpl-generator';
+
+try {
+    const badge = validateBadgeOrThrow(jsonData);
+    const zpl = generate(badge);
+} catch (error) {
+    // Handle validation error
+}
+```
+
+## Badge Configuration
+
+### Base Badge Properties
+
+All thermal badges require the following configuration:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `type` | `'thermal'` | Badge type (currently only thermal is supported) |
+| `tearOffAdjustment` | `number` | Tear-off adjustment (0-120) |
+| `backfeedActions` | `BackfeedAction` | Backfeed sequence configuration |
+| `media` | `MediaType` | Media type (continuous, variable length, etc.) |
+| `mediaOffset` | `number` | Media offset (-75 to 283) |
+| `thermalMediaType` | `ThermalMediaType` | Direct thermal or thermal transfer |
+| `printOrientation` | `PrintOrientation` | Normal or inverted |
+| `mirror` | `MirrorMode` | Mirror mode setting |
+| `labelHomeX` | `number` | Label home X coordinate (0-32000) |
+| `labelHomeY` | `number` | Label home Y coordinate (0-32000) |
+| `printDensityAdjustment` | `PrintDensityAdjustment?` | Optional print density adjustment |
+| `printSpeed` | `number` | Print speed (1-14) |
+| `slewSpeed` | `number` | Slew speed (1-14) |
+| `backfeedSpeed` | `number` | Backfeed speed (1-14) |
+| `darkness` | `number` | Print darkness (0-30) |
+| `reverse` | `ReverseMode` | Reverse mode setting |
+| `postPrintMode` | `PostPrintMode` | Post-print action (tear off, peel off, etc.) |
+| `prepeel` | `PrepeelMode` | Prepeel mode setting |
+| `printWidth` | `number` | Print width in dots (minimum 2) |
+| `labelLength` | `number` | Label length in dots (1-32000) |
+| `allMedia` | `AllMediaMode` | All media mode setting |
+| `blocks` | `Block[]` | Array of content blocks |
+
+### Block Types
+
+#### Field Block (Text)
+
+Displays text with configurable font, size, alignment, and wrapping.
+
+```typescript
+{
+    type: 'field',
+    name: 'field_name',           // Identifier for the block
+    x: 0,                          // X position in dots
+    y: 100,                        // Y position in dots
+    data: 'Text content',         // Text to display
+    font: 'A',                     // Font identifier (A-Z, 0-9)
+    fontHeight: 100,               // Font height in dots (1-32000)
+    fontWidth?: number,            // Optional font width in dots
+    fontOrientation: FontOrientation, // Text rotation
+    maxWidth: 900,                 // Maximum width for wrapping (0-9999)
+    maxLines: 3,                   // Maximum number of lines (1-9999)
+    lineSpacing: 0,                // Line spacing (-9999 to 9999)
+    alignment: TextAlignment,      // Text alignment (Left, Right, Center, Justified)
+    hangingIndent: 0,              // Hanging indent (0-9999)
+    verticalAlignment: VerticalAlignment, // Vertical alignment (Start, End)
+    wordWidths?: WordWidth[],      // Optional word width measurements for accurate wrapping
+}
+```
+
+**Vertical Alignment:**
+- `VerticalAlignment.Start`: Text starts at the top of the field
+- `VerticalAlignment.End`: Text is aligned to the bottom (padded with line breaks)
+
+**Word Widths:**
+For accurate text wrapping with proportional fonts, provide `wordWidths`:
+
+```typescript
+wordWidths: [
+    { word: 'Hello', width: 50, spaceWidth: 10 },
+    { word: 'World', width: 60, spaceWidth: 10 },
+]
+```
+
+#### Barcode Block
+
+Generates a Code 128 barcode.
+
+```typescript
+{
+    type: 'barcode',
+    name: 'barcode_name',
+    x: 0,
+    y: 200,
+    data: '1234567890',           // Barcode data
+    barWidth: 5,                   // Bar width multiplier (4-9999)
+    orientation: FontOrientation,  // Barcode orientation
+    height: 60,                    // Barcode height in dots (1-32000)
+    line: YesNo,                   // Show human-readable line below
+    lineAbove: YesNo,              // Show human-readable line above
+    checkDigit: YesNo,             // Include check digit
+}
+```
+
+#### QR Code Block
+
+Generates a QR code.
+
+```typescript
+{
+    type: 'qrcode',
+    name: 'qrcode_name',
+    x: 0,
+    y: 300,
+    data: 'https://example.com',   // QR code data
+    orientation: 'N',               // Must be 'N' (no rotation)
+    model: '2',                     // Must be '2' (Model 2)
+    magnification: 5,               // Magnification factor (1-100)
+    errorCorrection: QRCodeErrorCorrection, // Error correction level
+    mask: 0,                        // Mask pattern (0-7)
+}
+```
+
+## Enums and Constants
+
+### Media Types
+- `MediaType.Continuous` - Continuous media
+- `MediaType.VariableLengthContinuous` - Variable length continuous
+- `MediaType.NonContinuousWebSensing` - Non-continuous web sensing
+- `MediaType.NonContinuousWebSensingAlt` - Non-continuous web sensing (alternate)
+- `MediaType.NonContinuousMarkSensing` - Non-continuous mark sensing
+- `MediaType.AutoDetect` - Auto-detect media type
+
+### Thermal Media Types
+- `ThermalMediaType.DirectThermal` - Direct thermal printing
+- `ThermalMediaType.ThermalTransfer` - Thermal transfer printing
+
+### Text Alignment
+- `TextAlignment.Left` - Left-aligned text
+- `TextAlignment.Right` - Right-aligned text
+- `TextAlignment.Center` - Center-aligned text
+- `TextAlignment.Justified` - Justified text
+
+### Font Orientation
+- `FontOrientation.NoRotation` - No rotation (0°)
+- `FontOrientation.Rotate90` - Rotate 90° clockwise
+- `FontOrientation.Rotate180` - Rotate 180°
+- `FontOrientation.Rotate270` - Rotate 270° clockwise
+
+### Post Print Modes
+- `PostPrintMode.TearOff` - Tear off after printing
+- `PostPrintMode.PeelOff` - Peel off after printing
+- `PostPrintMode.Rewind` - Rewind after printing
+- `PostPrintMode.Applicator` - Applicator mode
+- `PostPrintMode.Cut` - Cut after printing
+- `PostPrintMode.DelayedCut` - Delayed cut
+- `PostPrintMode.EncodeRFID` - Encode RFID
+- `PostPrintMode.Kiosk` - Kiosk mode
+
+### QR Code Error Correction
+- `QRCodeErrorCorrection.Highest` - Highest error correction (~30%)
+- `QRCodeErrorCorrection.High` - High error correction (~25%)
+- `QRCodeErrorCorrection.Medium` - Medium error correction (~15%)
+- `QRCodeErrorCorrection.Lower` - Lower error correction (~7%)
+
+## Advanced Usage
+
+### Dynamic Content with Templates
+
+You can use template strings in your badge data and replace them before generating ZPL:
+
+```typescript
+const badge: ThermalBadge = {
+    // ... configuration
+    blocks: [
+        {
+            type: 'field',
+            name: 'name',
+            x: 0,
+            y: 100,
+            data: '{{firstName}} {{lastName}}', // Template string
+            // ... other properties
+        },
+    ],
+};
+
+// Replace template variables
+const badgeWithData = {
+    ...badge,
+    blocks: badge.blocks.map(block => ({
+        ...block,
+        data: block.data
+            .replace('{{firstName}}', 'John')
+            .replace('{{lastName}}', 'Doe'),
+    })),
+};
+
+const zpl = generate(badgeWithData);
+```
+
+### Accurate Text Wrapping
+
+For precise text layout with proportional fonts, measure word widths and provide them:
+
+```typescript
+import { countLines } from 'cxm-zpl-generator';
+
+// Measure word widths (e.g., using canvas or font metrics)
+const wordWidths: WordWidth[] = [
+    { word: 'Hello', width: 50, spaceWidth: 10 },
+    { word: 'World', width: 60, spaceWidth: 10 },
+];
+
+const fieldBlock: FieldBlock = {
+    type: 'field',
+    name: 'text',
+    x: 0,
+    y: 0,
+    data: 'Hello World',
+    font: 'A',
+    fontHeight: 20,
+    maxWidth: 100,
+    maxLines: 5,
+    lineSpacing: 0,
+    alignment: TextAlignment.Left,
+    fontOrientation: FontOrientation.NoRotation,
+    hangingIndent: 0,
+    verticalAlignment: VerticalAlignment.End,
+    wordWidths, // Provide measured widths
+};
+
+// countLines can be used to preview line count
+const lines = countLines(fieldBlock);
+console.log(`Text will occupy ${lines} lines`);
+```
+
+### Validating JSON Configuration
+
+When loading badge configurations from JSON files or APIs:
+
+```typescript
+import { validateBadgeOrThrow, generate } from 'cxm-zpl-generator';
+
+// Load from JSON file or API
+const jsonData = await fetch('/api/badge-config').then(r => r.json());
+
+try {
+    const badge = validateBadgeOrThrow(jsonData);
+    const zpl = generate(badge);
+    // Send to printer
+} catch (error) {
+    if (error instanceof ZodError) {
+        console.error('Validation errors:', error.errors);
+    }
+}
+```
+
+## Examples
+
+See the `examples/` directory for complete working examples:
+
+- `simple-label.ts` - Basic label with text fields and barcode
+
+## Testing
+
+Run tests with:
+
+```bash
+npm test
+```
+
+Watch mode:
+
+```bash
+npm run test:watch
+```
+
+## Building
+
+Build the library:
+
+```bash
+npm run build
+```
+
+## License
+
+ISC
+
+## Contributing
+
+Contributions are welcome! Please ensure all tests pass and follow the existing code style.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './src/generate';
+export * from './src/validate';