@hotmeshio/long-tail 0.30.5 → 0.31.0

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;

package/build/shared/labels/symbol.js

@@ -0,0 +1,74 @@
+"use strict";
+// Barcode encoding: the one module that knows bwip-js. Renderers draw the
+// dark modules this returns; ZPL uses the printer's own encoder instead.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SymbolEncodeError = void 0;
+exports.quietZoneModules = quietZoneModules;
+exports.encodeSymbol = encodeSymbol;
+const bwip_js_1 = __importDefault(require("bwip-js"));
+/** Data the symbology cannot carry. The message never repeats the data. */
+class SymbolEncodeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SymbolEncodeError';
+    }
+}
+exports.SymbolEncodeError = SymbolEncodeError;
+const BCID = { code128: 'code128', qrcode: 'qrcode', datamatrix: 'datamatrix' };
+const QUIET_ZONE = { code128: 10, qrcode: 4, datamatrix: 1 };
+const PRINTABLE_ASCII = /^[\x20-\x7e]+$/;
+/** The blank margin, in modules, a scanner needs around the symbol. */
+function quietZoneModules(symbology) {
+    return QUIET_ZONE[symbology];
+}
+function linearPath(sbs) {
+    let x = 0;
+    const bars = [];
+    sbs.forEach((run, i) => {
+        if (i % 2 === 0)
+            bars.push(`M${x} 0h${run}v1h-${run}z`);
+        x += run;
+    });
+    return { path: bars.join(''), width: x };
+}
+function matrixPath(raw) {
+    const rows = [];
+    for (let y = 0; y < raw.pixy; y++) {
+        let x = 0;
+        while (x < raw.pixx) {
+            if (!raw.pixs[y * raw.pixx + x]) {
+                x++;
+                continue;
+            }
+            const start = x;
+            while (x < raw.pixx && raw.pixs[y * raw.pixx + x])
+                x++;
+            rows.push(`M${start} ${y}h${x - start}v1h-${x - start}z`);
+        }
+    }
+    return rows.join('');
+}
+/** Encode `data` in `symbology`; throws SymbolEncodeError when it cannot be carried. */
+function encodeSymbol(symbology, data) {
+    if (!data)
+        throw new SymbolEncodeError('a code is empty');
+    if (symbology === 'code128' && !PRINTABLE_ASCII.test(data)) {
+        throw new SymbolEncodeError('Code 128 carries printable ASCII only');
+    }
+    let raw;
+    try {
+        raw = bwip_js_1.default.raw(BCID[symbology], data, {});
+    }
+    catch {
+        throw new SymbolEncodeError(`a code cannot be encoded as ${symbology}`);
+    }
+    const first = raw[0];
+    if ('sbs' in first) {
+        const { path, width } = linearPath(first.sbs);
+        return { path, widthModules: width, heightModules: 1 };
+    }
+    return { path: matrixPath(first), widthModules: first.pixx, heightModules: first.pixy };
+}

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

@@ -0,0 +1,18 @@
+export interface LabelTokenContext {
+    target: string;
+    /** The row's metadata (action schemes) or a pasted list's columns. */
+    item?: Record<string, unknown>;
+    /** The identity scheme's user: name, display_name, email, roles, and metadata keys. */
+    user?: Record<string, unknown>;
+    scheme?: {
+        name: string;
+    };
+}
+/** Render one line of label text. */
+export declare function renderLabelText(template: string, ctx: LabelTokenContext): string;
+/** Every token a line uses, valid or not, without braces. */
+export declare function listLabelTokens(template: string): string[];
+/** Tokens in a line that renderLabelText does not know. */
+export declare function unknownLabelTokens(template: string): string[];
+/** `user.<key>` tokens a line uses, as keys. */
+export declare function userTokenKeys(template: string): string[];

package/build/shared/labels/tokens.js

@@ -0,0 +1,43 @@
+"use strict";
+// Label text tokens: {target}, {item.<facet>}, {user.<key>}, {scheme.name}.
+// A missing value renders empty; template validation names unknown tokens.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderLabelText = renderLabelText;
+exports.listLabelTokens = listLabelTokens;
+exports.unknownLabelTokens = unknownLabelTokens;
+exports.userTokenKeys = userTokenKeys;
+const TOKEN = /\{(target|scheme\.name|(?:item|user)\.[a-zA-Z0-9_]+)\}/g;
+const ANY_TOKEN = /\{([^{}]*)\}/g;
+function display(value) {
+    if (value === null || value === undefined)
+        return '';
+    if (Array.isArray(value))
+        return value.map(display).filter(Boolean).join(', ');
+    if (typeof value === 'object')
+        return '';
+    return String(value);
+}
+function resolve(token, ctx) {
+    if (token === 'target')
+        return ctx.target;
+    if (token === 'scheme.name')
+        return ctx.scheme?.name;
+    const [bag, key] = token.split('.', 2);
+    return (bag === 'item' ? ctx.item : ctx.user)?.[key];
+}
+/** Render one line of label text. */
+function renderLabelText(template, ctx) {
+    return template.replace(TOKEN, (_m, token) => display(resolve(token, ctx))).trim();
+}
+/** Every token a line uses, valid or not, without braces. */
+function listLabelTokens(template) {
+    return [...template.matchAll(ANY_TOKEN)].map((m) => m[1]);
+}
+/** Tokens in a line that renderLabelText does not know. */
+function unknownLabelTokens(template) {
+    return listLabelTokens(template).filter((t) => !new RegExp(`^${TOKEN.source}$`).test(`{${t}}`));
+}
+/** `user.<key>` tokens a line uses, as keys. */
+function userTokenKeys(template) {
+    return listLabelTokens(template).filter((t) => t.startsWith('user.')).map((t) => t.slice(5));
+}

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

@@ -0,0 +1,105 @@
+export declare const LABEL_SYMBOLOGIES: readonly ["code128", "qrcode", "datamatrix"];
+export type LabelSymbology = (typeof LABEL_SYMBOLOGIES)[number];
+/** How a code's caption band prints on black-only stock: filled, outlined, or bare text. */
+export declare const LABEL_TONES: readonly ["solid", "outline", "plain"];
+export type LabelTone = (typeof LABEL_TONES)[number];
+/** A sheet of labels (office printer) or a thermal roll (one label per page). */
+export interface LabelMedia {
+    id: string;
+    name: string;
+    family: 'sheet' | 'thermal';
+    pageWidthMm: number;
+    pageHeightMm: number;
+    columns: number;
+    rows: number;
+    labelWidthMm: number;
+    labelHeightMm: number;
+    marginTopMm: number;
+    marginLeftMm: number;
+    gutterXMm: number;
+    gutterYMm: number;
+    cornerRadiusMm: number;
+    /** Thermal print resolution in dots per inch. */
+    dpi?: number;
+    /** The narrowest bar or module a scanner reads reliably from this stock. */
+    minModuleMm: number;
+}
+/** One code on a label: the payload, the act it names, and its band tone. */
+export interface LabelCode {
+    code: string;
+    caption: string;
+    tone: LabelTone;
+}
+/** What one label says, before layout. A masked label draws placeholders instead of codes. */
+export interface LabelContent {
+    title?: string;
+    lines: string[];
+    codes: LabelCode[];
+    masked?: boolean;
+}
+export interface LabelTextElement {
+    kind: 'text';
+    x: number;
+    y: number;
+    w: number;
+    /** Font size in millimetres (the em box). */
+    size: number;
+    text: string;
+    weight: 'regular' | 'bold';
+    align: 'left' | 'center';
+    /** White text, printed over a solid band. */
+    inverse?: boolean;
+}
+export interface LabelRectElement {
+    kind: 'rect';
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    /** Filled black when true; outlined with `stroke` mm otherwise. */
+    fill: boolean;
+    stroke?: number;
+}
+export interface LabelSymbolElement {
+    kind: 'symbol';
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    symbology: LabelSymbology;
+    /** The encoded payload; empty when masked. */
+    data: string;
+    moduleMm: number;
+    /** Dark modules as an SVG path in module units; empty when masked. */
+    path: string;
+    masked?: boolean;
+}
+export type LabelElement = LabelTextElement | LabelRectElement | LabelSymbolElement;
+export interface PlacedLabel {
+    /** Position on the page, counted from 0, left to right then top to bottom. */
+    slot: number;
+    /** Index of the label in the job's input. */
+    index: number;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    elements: LabelElement[];
+}
+export interface LabelPage {
+    labels: PlacedLabel[];
+}
+export declare const LABEL_WARNING_KINDS: readonly ["scale", "quiet_zone", "unencodable", "unparseable", "rule_disabled", "unresolved", "overflow", "missing_token"];
+export type LabelWarningKind = (typeof LABEL_WARNING_KINDS)[number];
+export interface LabelWarning {
+    /** Index of the label in the job's input. */
+    index: number;
+    kind: LabelWarningKind;
+    detail: string;
+}
+export interface LabelSheet {
+    media: LabelMedia;
+    pages: LabelPage[];
+    cutMarks: boolean;
+    warnings: LabelWarning[];
+}