@hotmeshio/long-tail 0.30.5 → 0.31.1

package/build/shared/labels/index.js

@@ -0,0 +1,54 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZplRenderError = exports.zplField = exports.renderSheetZpl = exports.escapeXml = exports.renderSheetSvg = exports.MAX_COPIES = exports.LabelLayoutError = exports.cutMarkSegments = exports.buildLabelSheet = exports.GLYPH_ADVANCE = exports.layoutLabelContent = exports.SymbolEncodeError = exports.quietZoneModules = exports.encodeSymbol = exports.slotsPerPage = exports.slotOrigin = exports.resolveMedia = exports.assertValidMedia = exports.LabelMediaError = exports.DEFAULT_LABEL_MEDIA_ID = exports.LABEL_MEDIA = exports.userTokenKeys = exports.unknownLabelTokens = exports.listLabelTokens = exports.renderLabelText = exports.ScanComposeError = exports.isMintableScheme = exports.composeScanCode = void 0;
+__exportStar(require("./types"), exports);
+var compose_1 = require("./compose");
+Object.defineProperty(exports, "composeScanCode", { enumerable: true, get: function () { return compose_1.composeScanCode; } });
+Object.defineProperty(exports, "isMintableScheme", { enumerable: true, get: function () { return compose_1.isMintableScheme; } });
+Object.defineProperty(exports, "ScanComposeError", { enumerable: true, get: function () { return compose_1.ScanComposeError; } });
+var tokens_1 = require("./tokens");
+Object.defineProperty(exports, "renderLabelText", { enumerable: true, get: function () { return tokens_1.renderLabelText; } });
+Object.defineProperty(exports, "listLabelTokens", { enumerable: true, get: function () { return tokens_1.listLabelTokens; } });
+Object.defineProperty(exports, "unknownLabelTokens", { enumerable: true, get: function () { return tokens_1.unknownLabelTokens; } });
+Object.defineProperty(exports, "userTokenKeys", { enumerable: true, get: function () { return tokens_1.userTokenKeys; } });
+var media_1 = require("./media");
+Object.defineProperty(exports, "LABEL_MEDIA", { enumerable: true, get: function () { return media_1.LABEL_MEDIA; } });
+Object.defineProperty(exports, "DEFAULT_LABEL_MEDIA_ID", { enumerable: true, get: function () { return media_1.DEFAULT_LABEL_MEDIA_ID; } });
+Object.defineProperty(exports, "LabelMediaError", { enumerable: true, get: function () { return media_1.LabelMediaError; } });
+Object.defineProperty(exports, "assertValidMedia", { enumerable: true, get: function () { return media_1.assertValidMedia; } });
+Object.defineProperty(exports, "resolveMedia", { enumerable: true, get: function () { return media_1.resolveMedia; } });
+Object.defineProperty(exports, "slotOrigin", { enumerable: true, get: function () { return media_1.slotOrigin; } });
+Object.defineProperty(exports, "slotsPerPage", { enumerable: true, get: function () { return media_1.slotsPerPage; } });
+var symbol_1 = require("./symbol");
+Object.defineProperty(exports, "encodeSymbol", { enumerable: true, get: function () { return symbol_1.encodeSymbol; } });
+Object.defineProperty(exports, "quietZoneModules", { enumerable: true, get: function () { return symbol_1.quietZoneModules; } });
+Object.defineProperty(exports, "SymbolEncodeError", { enumerable: true, get: function () { return symbol_1.SymbolEncodeError; } });
+var label_content_1 = require("./label-content");
+Object.defineProperty(exports, "layoutLabelContent", { enumerable: true, get: function () { return label_content_1.layoutLabelContent; } });
+Object.defineProperty(exports, "GLYPH_ADVANCE", { enumerable: true, get: function () { return label_content_1.GLYPH_ADVANCE; } });
+var layout_1 = require("./layout");
+Object.defineProperty(exports, "buildLabelSheet", { enumerable: true, get: function () { return layout_1.buildLabelSheet; } });
+Object.defineProperty(exports, "cutMarkSegments", { enumerable: true, get: function () { return layout_1.cutMarkSegments; } });
+Object.defineProperty(exports, "LabelLayoutError", { enumerable: true, get: function () { return layout_1.LabelLayoutError; } });
+Object.defineProperty(exports, "MAX_COPIES", { enumerable: true, get: function () { return layout_1.MAX_COPIES; } });
+var render_svg_1 = require("./render-svg");
+Object.defineProperty(exports, "renderSheetSvg", { enumerable: true, get: function () { return render_svg_1.renderSheetSvg; } });
+Object.defineProperty(exports, "escapeXml", { enumerable: true, get: function () { return render_svg_1.escapeXml; } });
+var render_zpl_1 = require("./render-zpl");
+Object.defineProperty(exports, "renderSheetZpl", { enumerable: true, get: function () { return render_zpl_1.renderSheetZpl; } });
+Object.defineProperty(exports, "zplField", { enumerable: true, get: function () { return render_zpl_1.zplField; } });
+Object.defineProperty(exports, "ZplRenderError", { enumerable: true, get: function () { return render_zpl_1.ZplRenderError; } });

package/build/shared/labels/label-content.d.ts

@@ -0,0 +1,17 @@
+import type { LabelContent, LabelElement, LabelSymbology, LabelWarningKind } from './types';
+export interface LabelContentOptions {
+    symbology: LabelSymbology;
+    humanReadable: boolean;
+    minModuleMm: number;
+}
+export interface LabelContentResult {
+    elements: LabelElement[];
+    warnings: {
+        kind: LabelWarningKind;
+        detail: string;
+    }[];
+}
+/** Average glyph advance as a fraction of the font size, for fitting text without font metrics. */
+export declare const GLYPH_ADVANCE = 0.56;
+/** Lay out one label's content inside a `width` × `height` box. */
+export declare function layoutLabelContent(content: LabelContent, width: number, height: number, opts: LabelContentOptions): LabelContentResult;

package/build/shared/labels/label-content.js

@@ -0,0 +1,137 @@
+"use strict";
+// Lays out one label: title, lines, then one panel per code (caption band,
+// symbol, readable code). Coordinates are millimetres from the label's corner.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GLYPH_ADVANCE = void 0;
+exports.layoutLabelContent = layoutLabelContent;
+const symbol_1 = require("./symbol");
+/** Average glyph advance as a fraction of the font size, for fitting text without font metrics. */
+exports.GLYPH_ADVANCE = 0.56;
+const MIN_TEXT_MM = 1.6;
+const MAX_LINEAR_MODULE_MM = 0.6;
+const MAX_MATRIX_MODULE_MM = 1.4;
+const MAX_BAR_HEIGHT_MM = 30;
+const clamp = (n, lo, hi) => Math.min(hi, Math.max(lo, n));
+/** The largest font size up to `size` at which `text` fits `width`, or null below the floor. */
+function fitText(text, width, size) {
+    const fitted = Math.min(size, width / Math.max(1, text.length * exports.GLYPH_ADVANCE));
+    return fitted >= MIN_TEXT_MM ? fitted : null;
+}
+/** Text that fits `width` at the floor size, cut with an ellipsis. */
+function truncateTo(text, width) {
+    const max = Math.max(1, Math.floor(width / (MIN_TEXT_MM * exports.GLYPH_ADVANCE)));
+    return text.length <= max ? text : `${text.slice(0, Math.max(1, max - 1))}…`;
+}
+function textRow(text, box, size, weight, out) {
+    let fitted = fitText(text, box.w, size);
+    let shown = text;
+    if (fitted === null) {
+        shown = truncateTo(text, box.w);
+        fitted = MIN_TEXT_MM;
+        out.warnings.push({ kind: 'overflow', detail: `"${text}" is too long for the label and was shortened` });
+    }
+    out.elements.push({ kind: 'text', x: box.x, y: box.y, w: box.w, size: fitted, text: shown, weight, align: 'center' });
+    return size * 1.2;
+}
+function planPanel(code, box, opts) {
+    const elements = [];
+    const gap = clamp(box.h * 0.04, 0.4, 1.5);
+    let y = box.y;
+    if (code.caption) {
+        const band = clamp(box.h * 0.2, 2.2, 7);
+        const size = Math.min(band * 0.62, box.w / Math.max(1, code.caption.length * exports.GLYPH_ADVANCE));
+        if (code.tone === 'solid')
+            elements.push({ kind: 'rect', x: box.x, y, w: box.w, h: band, fill: true });
+        if (code.tone === 'outline')
+            elements.push({ kind: 'rect', x: box.x, y, w: box.w, h: band, fill: false, stroke: clamp(band * 0.08, 0.2, 0.5) });
+        elements.push({
+            kind: 'text', x: box.x, y: y + (band - size) / 2, w: box.w, size: Math.max(size, MIN_TEXT_MM),
+            text: code.caption, weight: 'bold', align: 'center', inverse: code.tone === 'solid',
+        });
+        y += band + gap;
+    }
+    const readable = opts.humanReadable ? clamp(box.h * 0.1, 1.6, 3.2) : 0;
+    const symbolH = box.y + box.h - y - (readable ? readable + gap : 0);
+    const encoded = (0, symbol_1.encodeSymbol)(opts.symbology, code.code);
+    const quiet = (0, symbol_1.quietZoneModules)(opts.symbology);
+    const linear = opts.symbology === 'code128';
+    const moduleMm = linear
+        ? Math.min(MAX_LINEAR_MODULE_MM, box.w / (encoded.widthModules + 2 * quiet))
+        : Math.min(MAX_MATRIX_MODULE_MM, Math.min(box.w, symbolH) / (encoded.widthModules + 2 * quiet));
+    const w = encoded.widthModules * moduleMm;
+    const h = linear ? Math.min(symbolH, MAX_BAR_HEIGHT_MM) : encoded.heightModules * moduleMm;
+    elements.push({
+        kind: 'symbol', x: box.x + (box.w - w) / 2, y, w, h,
+        symbology: opts.symbology, data: code.code, moduleMm, path: encoded.path,
+    });
+    if (readable) {
+        elements.push({
+            kind: 'text', x: box.x, y: y + h + gap, w: box.w,
+            size: Math.max(MIN_TEXT_MM, Math.min(readable * 0.85, box.w / Math.max(1, code.code.length * exports.GLYPH_ADVANCE))),
+            text: code.code, weight: 'regular', align: 'center',
+        });
+    }
+    return { moduleMm, elements, quietOk: symbolH > 0 && w + 2 * quiet * moduleMm <= box.w + 1e-6 };
+}
+function planPanels(codes, area, across, opts) {
+    const n = codes.length;
+    const gap = clamp(Math.min(area.w, area.h) * 0.05, 0.8, 4);
+    return codes.map((code, i) => {
+        const box = across
+            ? { x: area.x + i * ((area.w - gap * (n - 1)) / n + gap), y: area.y, w: (area.w - gap * (n - 1)) / n, h: area.h }
+            : { x: area.x, y: area.y + i * ((area.h - gap * (n - 1)) / n + gap), w: area.w, h: (area.h - gap * (n - 1)) / n };
+        return planPanel(code, box, opts);
+    });
+}
+const smallest = (plans) => Math.min(...plans.map((p) => p.moduleMm));
+/** Lay out one label's content inside a `width` × `height` box. */
+function layoutLabelContent(content, width, height, opts) {
+    const out = { elements: [], warnings: [] };
+    const pad = clamp(Math.min(width, height) * 0.05, 1, 4);
+    const inner = { x: pad, y: pad, w: width - 2 * pad, h: height - 2 * pad };
+    let y = inner.y;
+    if (content.title) {
+        y += textRow(content.title, { ...inner, y }, clamp(inner.h * 0.15, 2.2, 10), 'bold', out);
+    }
+    const lineSize = clamp(inner.h * 0.09, 1.8, 6);
+    for (const line of content.lines.filter(Boolean)) {
+        y += textRow(line, { ...inner, y }, lineSize, 'regular', out);
+    }
+    if (content.codes.length === 0)
+        return out;
+    const area = { x: inner.x, y: y + (y > inner.y ? pad / 2 : 0), w: inner.w, h: 0 };
+    area.h = inner.y + inner.h - area.y;
+    let plans;
+    try {
+        const stacked = planPanels(content.codes, area, false, opts);
+        const across = content.codes.length > 1 ? planPanels(content.codes, area, true, opts) : stacked;
+        plans = smallest(across) > smallest(stacked) ? across : stacked;
+    }
+    catch (err) {
+        if (!(err instanceof symbol_1.SymbolEncodeError))
+            throw err;
+        out.warnings.push({ kind: 'unencodable', detail: err.message });
+        return out;
+    }
+    for (const plan of plans)
+        out.elements.push(...plan.elements);
+    const module = smallest(plans);
+    if (module < opts.minModuleMm) {
+        out.warnings.push({
+            kind: 'scale',
+            detail: `bars print at ${module.toFixed(2)} mm, below the ${opts.minModuleMm} mm a scanner reads reliably; use larger labels or fewer codes`,
+        });
+    }
+    if (plans.some((p) => !p.quietOk)) {
+        out.warnings.push({ kind: 'quiet_zone', detail: 'a code has too little blank margin around it to scan reliably' });
+    }
+    if (content.masked) {
+        for (const el of out.elements) {
+            if (el.kind === 'symbol')
+                Object.assign(el, { data: '', path: '', masked: true });
+            if (el.kind === 'text' && content.codes.some((c) => c.code === el.text))
+                el.text = '•'.repeat(8);
+        }
+    }
+    return out;
+}

package/build/shared/labels/layout.d.ts

@@ -0,0 +1,23 @@
+import type { LabelContent, LabelMedia, LabelSheet, LabelSymbology } from './types';
+export interface LabelSheetInput {
+    media: LabelMedia;
+    labels: LabelContent[];
+    symbology: LabelSymbology;
+    humanReadable: boolean;
+    /** The first slot to print on page one, counted from 1, so used labels are skipped. */
+    startPosition?: number;
+    /** Copies of each label, printed together. */
+    copies?: number;
+    /** One label per page, in the start slot (placards). */
+    onePerPage?: boolean;
+    cutMarks?: boolean;
+}
+/** A sheet request that cannot be laid out. */
+export declare class LabelLayoutError extends Error {
+    constructor(message: string);
+}
+export declare const MAX_COPIES = 50;
+/** Lay out every label of a job onto pages. */
+export declare function buildLabelSheet(input: LabelSheetInput): LabelSheet;
+/** Short tick marks at every label corner, outside the label, for cutting card stock. */
+export declare function cutMarkSegments(media: LabelMedia, length?: number): Array<[number, number, number, number]>;

package/build/shared/labels/layout.js

@@ -0,0 +1,81 @@
+"use strict";
+// Places labels on pages: start position on a partly used sheet, copies per
+// label, one label per page, and cut marks for card stock.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_COPIES = exports.LabelLayoutError = void 0;
+exports.buildLabelSheet = buildLabelSheet;
+exports.cutMarkSegments = cutMarkSegments;
+const label_content_1 = require("./label-content");
+const media_1 = require("./media");
+/** A sheet request that cannot be laid out. */
+class LabelLayoutError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'LabelLayoutError';
+    }
+}
+exports.LabelLayoutError = LabelLayoutError;
+exports.MAX_COPIES = 50;
+/** Lay out every label of a job onto pages. */
+function buildLabelSheet(input) {
+    const { media } = input;
+    const perPage = (0, media_1.slotsPerPage)(media);
+    const start = input.startPosition ?? 1;
+    const copies = input.copies ?? 1;
+    if (!Number.isInteger(start) || start < 1 || start > perPage) {
+        throw new LabelLayoutError(`start position must be between 1 and ${perPage}`);
+    }
+    if (!Number.isInteger(copies) || copies < 1 || copies > exports.MAX_COPIES) {
+        throw new LabelLayoutError(`copies must be between 1 and ${exports.MAX_COPIES}`);
+    }
+    const warnings = [];
+    const laidOut = input.labels.map((content, index) => {
+        const result = (0, label_content_1.layoutLabelContent)(content, media.labelWidthMm, media.labelHeightMm, {
+            symbology: input.symbology,
+            humanReadable: input.humanReadable,
+            minModuleMm: media.minModuleMm,
+        });
+        for (const w of result.warnings)
+            warnings.push({ index, ...w });
+        return result.elements;
+    });
+    const pages = [];
+    let slot = start - 1;
+    let page = null;
+    laidOut.forEach((elements, index) => {
+        for (let copy = 0; copy < copies; copy++) {
+            if (!page || slot >= perPage || input.onePerPage) {
+                if (page)
+                    slot = input.onePerPage ? start - 1 : 0;
+                page = { labels: [] };
+                pages.push(page);
+            }
+            const origin = (0, media_1.slotOrigin)(media, slot);
+            page.labels.push({ slot, index, x: origin.x, y: origin.y, w: media.labelWidthMm, h: media.labelHeightMm, elements });
+            slot += 1;
+        }
+    });
+    return { media, pages, cutMarks: !!input.cutMarks, warnings };
+}
+/** Short tick marks at every label corner, outside the label, for cutting card stock. */
+function cutMarkSegments(media, length = 3) {
+    const xs = new Set();
+    const ys = new Set();
+    for (let s = 0; s < (0, media_1.slotsPerPage)(media); s++) {
+        const o = (0, media_1.slotOrigin)(media, s);
+        xs.add(o.x).add(o.x + media.labelWidthMm);
+        ys.add(o.y).add(o.y + media.labelHeightMm);
+    }
+    const top = Math.min(...ys);
+    const bottom = Math.max(...ys);
+    const left = Math.min(...xs);
+    const right = Math.max(...xs);
+    const segments = [];
+    for (const x of xs) {
+        segments.push([x, Math.max(0, top - length - 1), x, top - 1], [x, bottom + 1, x, Math.min(media.pageHeightMm, bottom + length + 1)]);
+    }
+    for (const y of ys) {
+        segments.push([Math.max(0, left - length - 1), y, left - 1, y], [right + 1, y, Math.min(media.pageWidthMm, right + length + 1), y]);
+    }
+    return segments.filter(([x1, y1, x2, y2]) => x1 !== x2 || y1 !== y2);
+}

package/build/shared/labels/media.d.ts

@@ -0,0 +1,22 @@
+import type { LabelMedia } from './types';
+export declare const LABEL_MEDIA: readonly LabelMedia[];
+/** The default media when neither the job nor the template names one. */
+export declare const DEFAULT_LABEL_MEDIA_ID = "a4-l7160";
+/** A media definition that cannot hold its labels. */
+export declare class LabelMediaError extends Error {
+    constructor(message: string);
+}
+/** Throws LabelMediaError unless every label sits inside the page. */
+export declare function assertValidMedia(media: LabelMedia): void;
+/**
+ * The media a job prints on: a preset id (from `presets`, which hosts may
+ * extend) or a custom definition, validated either way.
+ */
+export declare function resolveMedia(media: string | LabelMedia, presets?: readonly LabelMedia[]): LabelMedia;
+/** Labels per page. */
+export declare function slotsPerPage(media: LabelMedia): number;
+/** The top-left corner of a slot on the page. */
+export declare function slotOrigin(media: LabelMedia, slot: number): {
+    x: number;
+    y: number;
+};

package/build/shared/labels/media.js

@@ -0,0 +1,116 @@
+"use strict";
+// Label media: sheet stock for office printers and thermal rolls. Geometry is
+// in millimetres, from the stock manufacturers' published templates.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LabelMediaError = exports.DEFAULT_LABEL_MEDIA_ID = exports.LABEL_MEDIA = void 0;
+exports.assertValidMedia = assertValidMedia;
+exports.resolveMedia = resolveMedia;
+exports.slotsPerPage = slotsPerPage;
+exports.slotOrigin = slotOrigin;
+const A4 = { pageWidthMm: 210, pageHeightMm: 297 };
+const LETTER = { pageWidthMm: 215.9, pageHeightMm: 279.4 };
+const IN = 25.4;
+const SHEET_MIN_MODULE_MM = 0.25;
+const THERMAL_MIN_MODULE_MM = 0.25;
+const THERMAL_DPI = 203;
+const CR80_W = 85.6;
+const CR80_H = 53.98;
+const CARD_GUTTER = 6;
+function sheet(m, page) {
+    return { family: 'sheet', minModuleMm: SHEET_MIN_MODULE_MM, ...page, ...m };
+}
+/** Cards centred on the page with cut gutters between them. */
+function cards(id, name, page, columns, rows) {
+    const marginLeftMm = (page.pageWidthMm - columns * CR80_W - (columns - 1) * CARD_GUTTER) / 2;
+    const marginTopMm = (page.pageHeightMm - rows * CR80_H - (rows - 1) * CARD_GUTTER) / 2;
+    return sheet({
+        id, name, columns, rows, labelWidthMm: CR80_W, labelHeightMm: CR80_H,
+        marginTopMm, marginLeftMm, gutterXMm: CARD_GUTTER, gutterYMm: CARD_GUTTER, cornerRadiusMm: 3.18,
+    }, page);
+}
+function thermal(id, name, widthIn, heightIn) {
+    return {
+        id, name, family: 'thermal', pageWidthMm: widthIn * IN, pageHeightMm: heightIn * IN,
+        columns: 1, rows: 1, labelWidthMm: widthIn * IN, labelHeightMm: heightIn * IN,
+        marginTopMm: 0, marginLeftMm: 0, gutterXMm: 0, gutterYMm: 0, cornerRadiusMm: 0,
+        dpi: THERMAL_DPI, minModuleMm: THERMAL_MIN_MODULE_MM,
+    };
+}
+exports.LABEL_MEDIA = [
+    sheet({ id: 'a4-l7160', name: 'A4 · L7160 · 21 per sheet (63.5 × 38.1 mm)', columns: 3, rows: 7, labelWidthMm: 63.5, labelHeightMm: 38.1, marginTopMm: 15.15, marginLeftMm: 7.25, gutterXMm: 2.54, gutterYMm: 0, cornerRadiusMm: 1.5 }, A4),
+    sheet({ id: 'a4-l7163', name: 'A4 · L7163 · 14 per sheet (99.1 × 38.1 mm)', columns: 2, rows: 7, labelWidthMm: 99.1, labelHeightMm: 38.1, marginTopMm: 15.15, marginLeftMm: 4.65, gutterXMm: 2.5, gutterYMm: 0, cornerRadiusMm: 1.5 }, A4),
+    sheet({ id: 'a4-l7165', name: 'A4 · L7165 · 8 per sheet (99.1 × 67.7 mm)', columns: 2, rows: 4, labelWidthMm: 99.1, labelHeightMm: 67.7, marginTopMm: 13.1, marginLeftMm: 4.65, gutterXMm: 2.5, gutterYMm: 0, cornerRadiusMm: 1.5 }, A4),
+    sheet({ id: 'a4-l7173', name: 'A4 · L7173 · 10 per sheet (99.1 × 57 mm)', columns: 2, rows: 5, labelWidthMm: 99.1, labelHeightMm: 57, marginTopMm: 6, marginLeftMm: 4.65, gutterXMm: 2.5, gutterYMm: 0, cornerRadiusMm: 1.5 }, A4),
+    sheet({ id: 'a4-l7651', name: 'A4 · L7651 · 65 per sheet (38.1 × 21.2 mm)', columns: 5, rows: 13, labelWidthMm: 38.1, labelHeightMm: 21.2, marginTopMm: 10.7, marginLeftMm: 4.7, gutterXMm: 2.5, gutterYMm: 0, cornerRadiusMm: 1 }, A4),
+    sheet({ id: 'a4-a6', name: 'A4 · 4 per sheet (A6, 105 × 148.5 mm)', columns: 2, rows: 2, labelWidthMm: 105, labelHeightMm: 148.5, marginTopMm: 0, marginLeftMm: 0, gutterXMm: 0, gutterYMm: 0, cornerRadiusMm: 0 }, A4),
+    sheet({ id: 'a4-placard', name: 'A4 · placard, 1 per page', columns: 1, rows: 1, labelWidthMm: 190, labelHeightMm: 277, marginTopMm: 10, marginLeftMm: 10, gutterXMm: 0, gutterYMm: 0, cornerRadiusMm: 0 }, A4),
+    cards('a4-cr80', 'A4 · ID cards (CR80), 10 per sheet', A4, 2, 5),
+    sheet({ id: 'letter-5160', name: 'Letter · 5160 · 30 per sheet (2.625 × 1 in)', columns: 3, rows: 10, labelWidthMm: 2.625 * IN, labelHeightMm: 1 * IN, marginTopMm: 0.5 * IN, marginLeftMm: 0.1875 * IN, gutterXMm: 0.125 * IN, gutterYMm: 0, cornerRadiusMm: 1.5 }, LETTER),
+    sheet({ id: 'letter-5163', name: 'Letter · 5163 · 10 per sheet (4 × 2 in)', columns: 2, rows: 5, labelWidthMm: 4 * IN, labelHeightMm: 2 * IN, marginTopMm: 0.5 * IN, marginLeftMm: 0.15625 * IN, gutterXMm: 0.1875 * IN, gutterYMm: 0, cornerRadiusMm: 1.5 }, LETTER),
+    sheet({ id: 'letter-22805', name: 'Letter · 22805 · 24 per sheet (1.5 in square)', columns: 4, rows: 6, labelWidthMm: 1.5 * IN, labelHeightMm: 1.5 * IN, marginTopMm: 0.625 * IN, marginLeftMm: 0.625 * IN, gutterXMm: 0.3125 * IN, gutterYMm: 0.2 * IN, cornerRadiusMm: 1.5 }, LETTER),
+    sheet({ id: 'letter-placard', name: 'Letter · placard, 1 per page', columns: 1, rows: 1, labelWidthMm: LETTER.pageWidthMm - 2 * 12.7, labelHeightMm: LETTER.pageHeightMm - 2 * 12.7, marginTopMm: 12.7, marginLeftMm: 12.7, gutterXMm: 0, gutterYMm: 0, cornerRadiusMm: 0 }, LETTER),
+    cards('letter-cr80', 'Letter · ID cards (CR80), 8 per sheet', LETTER, 2, 4),
+    thermal('thermal-4x6', 'Thermal roll · 4 × 6 in', 4, 6),
+    thermal('thermal-4x2', 'Thermal roll · 4 × 2 in', 4, 2),
+    thermal('thermal-2x1', 'Thermal roll · 2 × 1 in', 2, 1),
+];
+/** The default media when neither the job nor the template names one. */
+exports.DEFAULT_LABEL_MEDIA_ID = 'a4-l7160';
+/** A media definition that cannot hold its labels. */
+class LabelMediaError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'LabelMediaError';
+    }
+}
+exports.LabelMediaError = LabelMediaError;
+const EPSILON_MM = 0.05;
+/** Throws LabelMediaError unless every label sits inside the page. */
+function assertValidMedia(media) {
+    const sizes = [media.pageWidthMm, media.pageHeightMm, media.labelWidthMm, media.labelHeightMm];
+    if (sizes.some((n) => !Number.isFinite(n) || n <= 0)) {
+        throw new LabelMediaError(`media "${media.id}": page and label sizes must be positive`);
+    }
+    if (!Number.isInteger(media.columns) || !Number.isInteger(media.rows) || media.columns < 1 || media.rows < 1) {
+        throw new LabelMediaError(`media "${media.id}": columns and rows must be positive integers`);
+    }
+    const offsets = [media.marginTopMm, media.marginLeftMm, media.gutterXMm, media.gutterYMm, media.cornerRadiusMm];
+    if (offsets.some((n) => !Number.isFinite(n) || n < 0)) {
+        throw new LabelMediaError(`media "${media.id}": margins, gutters and radius must not be negative`);
+    }
+    const right = media.marginLeftMm + media.columns * media.labelWidthMm + (media.columns - 1) * media.gutterXMm;
+    const bottom = media.marginTopMm + media.rows * media.labelHeightMm + (media.rows - 1) * media.gutterYMm;
+    if (right > media.pageWidthMm + EPSILON_MM || bottom > media.pageHeightMm + EPSILON_MM) {
+        throw new LabelMediaError(`media "${media.id}": labels run past the page edge`);
+    }
+    if (!(media.minModuleMm > 0)) {
+        throw new LabelMediaError(`media "${media.id}": minModuleMm must be positive`);
+    }
+    if (media.family === 'thermal' && !(media.dpi && media.dpi > 0)) {
+        throw new LabelMediaError(`media "${media.id}": thermal media need a dpi`);
+    }
+}
+/**
+ * The media a job prints on: a preset id (from `presets`, which hosts may
+ * extend) or a custom definition, validated either way.
+ */
+function resolveMedia(media, presets = exports.LABEL_MEDIA) {
+    const found = typeof media === 'string' ? presets.find((m) => m.id === media) : media;
+    if (!found)
+        throw new LabelMediaError(`unknown media "${String(media)}"`);
+    assertValidMedia(found);
+    return found;
+}
+/** Labels per page. */
+function slotsPerPage(media) {
+    return media.columns * media.rows;
+}
+/** The top-left corner of a slot on the page. */
+function slotOrigin(media, slot) {
+    const column = slot % media.columns;
+    const row = Math.floor(slot / media.columns);
+    return {
+        x: media.marginLeftMm + column * (media.labelWidthMm + media.gutterXMm),
+        y: media.marginTopMm + row * (media.labelHeightMm + media.gutterYMm),
+    };
+}

package/build/shared/labels/render-svg.d.ts

@@ -0,0 +1,10 @@
+import type { LabelSheet } from './types';
+export interface SvgRenderOptions {
+    /** Draw each label's outline (screen preview only; never printed). */
+    outlines?: boolean;
+    fontFamily?: string;
+}
+/** Escape text for XML content and attributes. */
+export declare function escapeXml(text: string): string;
+/** Render every page of a sheet as a standalone SVG document string. */
+export declare function renderSheetSvg(sheet: LabelSheet, opts?: SvgRenderOptions): string[];

package/build/shared/labels/render-svg.js

@@ -0,0 +1,58 @@
+"use strict";
+// LabelSheet → one SVG per page, sized in millimetres for print. A barcode is
+// a document: black on white, whatever the screen theme.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.escapeXml = escapeXml;
+exports.renderSheetSvg = renderSheetSvg;
+const layout_1 = require("./layout");
+const DEFAULT_FONT = 'Helvetica, Arial, sans-serif';
+const r = (n) => Math.round(n * 1000) / 1000;
+/** Escape text for XML content and attributes. */
+function escapeXml(text) {
+    return text
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+function element(el, font) {
+    if (el.kind === 'rect') {
+        return el.fill
+            ? `<rect x="${r(el.x)}" y="${r(el.y)}" width="${r(el.w)}" height="${r(el.h)}" fill="#000"/>`
+            : `<rect x="${r(el.x)}" y="${r(el.y)}" width="${r(el.w)}" height="${r(el.h)}" fill="none" stroke="#000" stroke-width="${r(el.stroke ?? 0.3)}"/>`;
+    }
+    if (el.kind === 'text') {
+        const x = el.align === 'center' ? el.x + el.w / 2 : el.x;
+        return `<text x="${r(x)}" y="${r(el.y + el.size * 0.8)}" font-family="${escapeXml(font)}" font-size="${r(el.size)}" ` +
+            `font-weight="${el.weight === 'bold' ? 700 : 400}" text-anchor="${el.align === 'center' ? 'middle' : 'start'}" ` +
+            `fill="${el.inverse ? '#fff' : '#000'}">${escapeXml(el.text)}</text>`;
+    }
+    if (el.masked) {
+        const size = Math.min(el.h * 0.3, 3);
+        return `<rect x="${r(el.x)}" y="${r(el.y)}" width="${r(el.w)}" height="${r(el.h)}" fill="#ddd" stroke="#888" stroke-width="0.2" stroke-dasharray="1 1"/>` +
+            `<text x="${r(el.x + el.w / 2)}" y="${r(el.y + el.h / 2 + size * 0.35)}" font-family="${escapeXml(font)}" font-size="${r(size)}" text-anchor="middle" fill="#555">Code prints on confirm</text>`;
+    }
+    return `<path class="lt-label-symbol" data-code="${escapeXml(el.data)}" d="${el.path}" fill="#000" ` +
+        `transform="translate(${r(el.x)} ${r(el.y)}) scale(${r(el.moduleMm)} ${el.symbology === 'code128' ? r(el.h) : r(el.moduleMm)})"/>`;
+}
+function label(placed, font, outline, radius) {
+    const body = placed.elements.map((el) => element(el, font)).join('');
+    const frame = outline
+        ? `<rect x="0" y="0" width="${r(placed.w)}" height="${r(placed.h)}" rx="${r(radius)}" fill="none" stroke="#bbb" stroke-width="0.2" stroke-dasharray="1 1"/>`
+        : '';
+    return `<g class="lt-label" data-index="${placed.index}" data-slot="${placed.slot}" transform="translate(${r(placed.x)} ${r(placed.y)})">${frame}${body}</g>`;
+}
+/** Render every page of a sheet as a standalone SVG document string. */
+function renderSheetSvg(sheet, opts = {}) {
+    const { media } = sheet;
+    const font = opts.fontFamily ?? DEFAULT_FONT;
+    const marks = sheet.cutMarks
+        ? (0, layout_1.cutMarkSegments)(media).map(([x1, y1, x2, y2]) => `<line x1="${r(x1)}" y1="${r(y1)}" x2="${r(x2)}" y2="${r(y2)}" stroke="#000" stroke-width="0.15"/>`).join('')
+        : '';
+    return sheet.pages.map((page) => `<svg xmlns="http://www.w3.org/2000/svg" class="lt-print-page" width="${r(media.pageWidthMm)}mm" height="${r(media.pageHeightMm)}mm" ` +
+        `viewBox="0 0 ${r(media.pageWidthMm)} ${r(media.pageHeightMm)}">` +
+        `<rect width="100%" height="100%" fill="#fff"/>${marks}` +
+        page.labels.map((placed) => label(placed, font, !!opts.outlines, media.cornerRadiusMm)).join('') +
+        '</svg>');
+}

package/build/shared/labels/render-zpl.d.ts

@@ -0,0 +1,9 @@
+import type { LabelSheet } from './types';
+/** A sheet that cannot be rendered as ZPL. */
+export declare class ZplRenderError extends Error {
+    constructor(message: string);
+}
+/** Field data with ^FH escaping: the ZPL command characters and the escape itself become hex. */
+export declare function zplField(text: string): string;
+/** Render a thermal sheet as one ZPL document, one label format per printed label. */
+export declare function renderSheetZpl(sheet: LabelSheet): string;

package/build/shared/labels/render-zpl.js

@@ -0,0 +1,63 @@
+"use strict";
+// LabelSheet → ZPL for thermal printers: one ^XA…^XZ per printed label, with
+// the printer's own barcode commands so bars land on whole dots.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZplRenderError = void 0;
+exports.zplField = zplField;
+exports.renderSheetZpl = renderSheetZpl;
+/** A sheet that cannot be rendered as ZPL. */
+class ZplRenderError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ZplRenderError';
+    }
+}
+exports.ZplRenderError = ZplRenderError;
+const MM_PER_INCH = 25.4;
+/** Field data with ^FH escaping: the ZPL command characters and the escape itself become hex. */
+function zplField(text) {
+    return text.replace(/[\^~_\\]/g, (c) => `_${c.charCodeAt(0).toString(16).toUpperCase().padStart(2, '0')}`);
+}
+function element(el, dots) {
+    if (el.kind === 'rect') {
+        const w = Math.max(1, dots(el.w));
+        const h = Math.max(1, dots(el.h));
+        const thickness = el.fill ? Math.min(w, h) : Math.max(1, dots(el.stroke ?? 0.3));
+        return `^FO${dots(el.x)},${dots(el.y)}^GB${w},${h},${thickness}^FS`;
+    }
+    if (el.kind === 'text') {
+        const size = Math.max(10, dots(el.size));
+        const justify = el.align === 'center' ? 'C' : 'L';
+        return `^FO${dots(el.x)},${dots(el.y)}^A0N,${size},${size}^FB${Math.max(1, dots(el.w))},1,0,${justify}` +
+            `${el.inverse ? '^FR' : ''}^FH^FD${zplField(el.text)}^FS`;
+    }
+    if (el.masked) {
+        throw new ZplRenderError('a masked label cannot be sent to a printer');
+    }
+    const module = Math.max(1, dots(el.moduleMm));
+    const at = `^FO${dots(el.x)},${dots(el.y)}`;
+    if (el.symbology === 'code128') {
+        return `^BY${module},3,${Math.max(1, dots(el.h))}${at}^BCN,${Math.max(1, dots(el.h))},N,N,N,A^FH^FD${zplField(el.data)}^FS`;
+    }
+    if (el.symbology === 'qrcode') {
+        return `${at}^BQN,2,${Math.min(10, module)}^FH^FDMA,${zplField(el.data)}^FS`;
+    }
+    return `${at}^BXN,${module},200^FH^FD${zplField(el.data)}^FS`;
+}
+/** Render a thermal sheet as one ZPL document, one label format per printed label. */
+function renderSheetZpl(sheet) {
+    const { media } = sheet;
+    if (media.family !== 'thermal' || !media.dpi) {
+        throw new ZplRenderError(`media "${media.id}" is not thermal stock; ZPL renders thermal media only`);
+    }
+    const dpmm = media.dpi / MM_PER_INCH;
+    const dots = (mm) => Math.round(mm * dpmm);
+    const formats = [];
+    for (const page of sheet.pages) {
+        for (const placed of page.labels) {
+            const body = placed.elements.map((el) => element(el, dots)).join('\n');
+            formats.push(`^XA\n^CI28\n^LH0,0\n^PW${dots(media.labelWidthMm)}\n^LL${dots(media.labelHeightMm)}\n${body}\n^XZ`);
+        }
+    }
+    return formats.join('\n');
+}

package/build/shared/labels/symbol.d.ts

@@ -0,0 +1,18 @@
+import type { LabelSymbology } from './types';
+export interface EncodedSymbol {
+    /**
+     * Dark modules as an SVG path. Code 128: x in modules, y from 0 to 1
+     * (bars span the full height). Matrix codes: x and y in modules.
+     */
+    path: string;
+    widthModules: number;
+    heightModules: number;
+}
+/** Data the symbology cannot carry. The message never repeats the data. */
+export declare class SymbolEncodeError extends Error {
+    constructor(message: string);
+}
+/** The blank margin, in modules, a scanner needs around the symbol. */
+export declare function quietZoneModules(symbology: LabelSymbology): number;
+/** Encode `data` in `symbology`; throws SymbolEncodeError when it cannot be carried. */
+export declare function encodeSymbol(symbology: LabelSymbology, data: string): EncodedSymbol;