@ai-matrx/print 0.1.0

package/dist/labels.d.ts

@@ -0,0 +1,270 @@
+import { PrintSettings, BlockPrinter } from './core.js';
+
+/**
+ * @ai-matrx/print/labels — the label-sheet engine.
+ *
+ * ONE module carrying the three matrx-frontend files this lane was extracted
+ * from, ported behaviour-verbatim (2026-08-29 state):
+ *   lib/label-print/label-templates.ts   → the template registry
+ *   lib/label-print/qr-labels-printer.ts → qrLabelsPrinter / printQrLabelSheet
+ *   lib/label-print/qr-labels-pdf.ts     → downloadLabelsPdf
+ *
+ * Warehouse-grade QR labels on standard 8.5" × 11" label stock (Avery and
+ * compatibles) AND on continuous/die-cut roll stock. ONE generic grid renderer
+ * driven by the LabelTemplate registry — geometry is data, never per-stock CSS.
+ *
+ * Fidelity rules (the reasons this exists):
+ * - The print window is a fresh, unauthenticated document: every QR image is
+ *   inlined as a data URI, never fetched.
+ * - Spec-compliant quiet zone: the `qrcode` lib renders 4 modules of white
+ *   margin INSIDE each data URI (its default; we pass it explicitly).
+ * - `print-color-adjust: exact` on code cells so the browser never "helps".
+ * - Modules are crisp: each QR is rasterized at 300 dpi for its printed size,
+ *   and `image-rendering: pixelated` stops resampling blur.
+ * - Captions auto-shrink to fit their box (FIT_TEXT pattern) — they never
+ *   overflow onto the neighboring label.
+ * - `startAtLabel` inserts LEADING blank cells so a partially-used sheet can
+ *   be reused; trailing cells pad out the last page.
+ *
+ * THE IMAGE RULE — the one deliberate exception to "data URIs only": a label's
+ * optional `imageUrl` is a DURABLE http(s) URL and is emitted as a plain
+ * `<img src>`. Anything that is not http(s) is SKIPPED rather than rendered.
+ * The QR itself is never a URL; it is always an inlined data URI.
+ *
+ * SEAM INVERSIONS versus the matrx-frontend originals (the only changes to the
+ * ported behaviour):
+ * 1. `@/lib/block-print/block-print-utils` → `./core` (identical export names).
+ * 2. The deferred `import("qrcode")` + `QRCode.toDataURL(...)` call is now
+ *    `generateQrDataUrl` from `./qr`, which performs the same lazy import at
+ *    call time and maps 1:1 — errorCorrectionLevel → ecLevel, margin →
+ *    quietZoneModules, width → widthPx. The original also passed
+ *    `color: { dark: "#000000", light: "#ffffff" }`, which is byte-for-byte the
+ *    `qrcode` default, so dropping it changes no output.
+ * 3. LP_FIT_SCRIPT is KEPT VERBATIM rather than replaced by core's
+ *    `buildFitTextScript`. The two scripts are NOT behaviourally identical for
+ *    label cells: core's steps and writes font sizes in **pt** (and pre-assigns
+ *    `size + "pt"` from a px-derived number before measuring) with a **6pt**
+ *    floor, while the label script steps and writes **px** with a **4px** floor
+ *    and no pre-assignment. On a 9pt caption inside a 0.28in box those two
+ *    produce different final sizes, so swapping them would regress captions on
+ *    the small Avery stocks.
+ *
+ * Docs: lib/label-print/FEATURE.md (matrx-frontend), NOTES-CHANGELOG.md.
+ */
+
+/**
+ * Label-sheet template registry — the geometry source of truth for QR label
+ * printing on standard 8.5" × 11" label stock (Avery and compatibles) and on
+ * roll stock.
+ *
+ * ONE generic grid renderer is driven entirely by these numbers — never a
+ * hand-written CSS block per stock. All dimensions in inches, taken from
+ * Avery's published templates:
+ *   - horizontal pitch = labelWIn + gutterXIn; vertical pitch = labelHIn + gutterYIn
+ *   - a template is valid when marginLeft*2 + cols*labelW + (cols-1)*gutterX = sheetW
+ *     (same vertically) — `assertTemplateGeometry` checks this in dev.
+ */
+interface LabelTemplate {
+    id: string;
+    name: string;
+    /** Stock code as printed on the box (e.g. "Avery 5160"). */
+    stockCode: string;
+    sheetWIn: number;
+    sheetHIn: number;
+    marginTopIn: number;
+    marginLeftIn: number;
+    labelWIn: number;
+    labelHIn: number;
+    cols: number;
+    rows: number;
+    /** Horizontal gap BETWEEN columns (not the outer margin). */
+    gutterXIn: number;
+    /** Vertical gap BETWEEN rows. */
+    gutterYIn: number;
+    /** Corner radius; equal to labelWIn/2 for round labels. */
+    cornerRadiusIn?: number;
+    /** True round label (die-cut circle) — preview/calibration draw a circle. */
+    round?: boolean;
+    /**
+     * Stock family. Absent means "sheet" — a multi-up page of labels. "roll" is
+     * a continuous/die-cut roll where the sheet IS the label: margins 0, a 1×1
+     * grid, and `@page` sized to the single label.
+     */
+    kind?: "sheet" | "roll";
+}
+/**
+ * Seeded templates. Sheet geometry verified against Avery's published template
+ * dimensions (avery.com template pages for each SKU):
+ *
+ * 5160 — see AVERY_5160 above.
+ * 5163 — 2" × 4" shipping, 10-up (2×5). Top/bottom 0.5", side 0.15625",
+ *        0.1875" column gutter, zero row gutter.
+ * 5164 — 3⅓" × 4" shipping, 6-up (2×3). Same horizontal grid as 5163.
+ * 22806 — 2" × 2" rounded square, 12-up (3×4). Margins 0.5" sides /
+ *        0.75" top, 0.75" column gutter, 0.5" row gutter — i.e. Avery's
+ *        published 2.75" horizontal pitch and 2.5" vertical pitch. (The
+ *        matrx-frontend original had 0.375"/0.375" here and tiled only 7.5"
+ *        of the 8.5" sheet; see NOTES-CHANGELOG.md.)
+ * 22807 — 2" round, 12-up (3×4). Same grid as 22806, circular die-cut.
+ *
+ * Roll stock (`kind: "roll"`) — the sheet IS the label, so every roll row is a
+ * 1×1 grid with zero margins and zero gutters, and its die-cut size is given
+ * as width × height in the feed orientation:
+ *
+ * DK-1202  — Brother die-cut shipping, 62mm × 100mm = 2.4" × 3.9".
+ * DK-11201 — Brother die-cut address, 29mm × 90mm = 1.14" × 3.5".
+ * 30252    — DYMO address, 1⅛" × 3½".
+ * 4x6      — the generic 4" × 6" thermal shipping label.
+ */
+declare const LABEL_TEMPLATES: readonly LabelTemplate[];
+declare function getLabelTemplate(id: string): LabelTemplate | undefined;
+/**
+ * Build a `custom` template for stock not in the registry. Callers supply the
+ * full geometry; id is fixed to "custom".
+ *
+ * The geometry spread comes FIRST so an explicitly-present `name: undefined` /
+ * `stockCode: undefined` cannot overwrite the resolved default (see
+ * NOTES-CHANGELOG.md).
+ */
+declare function customLabelTemplate(geometry: Omit<LabelTemplate, "id" | "name" | "stockCode"> & Partial<Pick<LabelTemplate, "name" | "stockCode">>): LabelTemplate;
+/** Dev-time sanity check: the grid must tile the sheet exactly (±1/64"). */
+declare function assertTemplateGeometry(t: LabelTemplate): void;
+interface QrLabel {
+    /** The value encoded in the QR code (SKU, URL, id…). */
+    qrValue: string;
+    /** Bold headline under/next to the code. Defaults to qrValue when captions are on. */
+    caption?: string;
+    /** Additional small text lines (wide labels only — there is no room on tiny stock). */
+    lines?: string[];
+    /**
+     * A single short, LARGE, bold token (a garment size, a bin letter, a grade).
+     * Rendered in the caption zone ABOVE the caption at ~2× the caption size and
+     * auto-shrunk by the fit script.
+     */
+    badge?: string;
+    /**
+     * Durable http(s) image URL rendered in the lines zone with
+     * `object-fit: contain`. Anything that is not http(s) is skipped — THE IMAGE
+     * RULE. Ignored by the PDF lane, which cannot fetch a remote image.
+     */
+    imageUrl?: string;
+}
+interface QrLabelPrintData {
+    labels: QrLabel[];
+    /** Default template; the dialog's variant picker overrides it. */
+    templateId: string;
+    /** Optional custom-stock geometry used when templateId === "custom". */
+    customTemplate?: LabelTemplate;
+}
+type QrEcLevel = "L" | "M" | "Q";
+interface QrLabelSettings {
+    startAtLabel: number;
+    copiesPerCode: number;
+    showCaption: boolean;
+    showLines: boolean;
+    rangeFrom: number;
+    rangeTo: number;
+    ecLevel: QrEcLevel;
+    calibrationPage: boolean;
+}
+declare function generateQrDataUri(value: string, ecLevel: QrEcLevel, sizeInches: number): Promise<string>;
+interface CellLayout {
+    /** true = QR left, text right; false = QR on top, caption below. */
+    wide: boolean;
+    qrIn: number;
+    padIn: number;
+    /** Height reserved above the caption for a `badge`; 0 when there is none. */
+    badgeZoneIn: number;
+}
+declare function computeCellLayout(t: LabelTemplate, showCaption: boolean, hasBadge?: boolean): CellLayout;
+declare function expandLabels(labels: QrLabel[], s: QrLabelSettings): QrLabel[];
+/** Print the grid outline + crop marks only — verify alignment before burning labels. */
+declare function printCalibrationSheet(template: LabelTemplate): void;
+/**
+ * The printed-module floor a 300 dpi thermal printer and a warehouse scanner
+ * can both resolve. Below this a symbol prints, looks fine on screen, and
+ * refuses to scan on the dock.
+ */
+declare const MIN_SCANNABLE_MODULE_MM = 0.4;
+interface ScannabilityReport {
+    ok: boolean;
+    version: number;
+    moduleSizeMm: number;
+    minModuleSizeMm: number;
+    message?: string;
+}
+/**
+ * Will a payload of `payloadByteLen` bytes actually scan off this stock?
+ *
+ * The printed side comes from the SAME layout brain the printer uses
+ * (`computeCellLayout`), evaluated with captions ON — the smaller, and
+ * therefore conservative, QR box. Module size divides that side by the symbol's
+ * modules PLUS the two 4-module quiet zones the data URI carries inside it.
+ *
+ * Never throws: an over-capacity payload comes back as `ok: false` with
+ * `version: 0` and the capacity error as the message.
+ */
+declare function assertScannable(template: LabelTemplate, payloadByteLen: number, ecLevel?: QrEcLevel): ScannabilityReport;
+/** Core render path — also used by the demo page's direct print entry point. */
+declare function printQrLabelSheet(data: QrLabelPrintData, variantId?: string, rawSettings?: PrintSettings): Promise<void>;
+declare const qrLabelsPrinter: BlockPrinter;
+/**
+ * Generate a PDF of QR labels for the given template and hand it to the
+ * browser as a download. Same data seam as the printer: `{ labels, templateId }`.
+ */
+declare function downloadLabelsPdf(data: QrLabelPrintData, templateId?: string, rawSettings?: PrintSettings, filename?: string): Promise<void>;
+/** Where an element's text comes from: a row column, or a fixed string. */
+type LabelField = {
+    field: string;
+} | {
+    literal: string;
+};
+type LabelElement = {
+    kind: "qr";
+    source: LabelField;
+} | {
+    kind: "text";
+    source: LabelField;
+    role: "title" | "detail" | "badge";
+    /**
+     * Cap on how many lines the value may occupy. The value is split on
+     * newlines; beyond `maxLines` the extra lines are dropped and the last
+     * kept line gains an ellipsis.
+     */
+    maxLines?: number;
+}
+/** Durable http(s) URL only — THE IMAGE RULE. A non-http value is SKIPPED. */
+ | {
+    kind: "image";
+    source: LabelField;
+};
+interface LabelFormat {
+    id: string;
+    name: string;
+    elements: LabelElement[];
+}
+/**
+ * Map rows through a format into the printer's label shape.
+ *
+ * - the qr element's resolved value → `qrValue` (first one wins)
+ * - the FIRST title-role text       → `caption`
+ * - the FIRST badge-role text       → `badge`
+ * - detail-role texts, in element order → `lines[]`
+ * - the first http(s) image element → `imageUrl`
+ *
+ * A row missing a `field` resolves to "" and that element is skipped.
+ */
+declare function applyLabelFormat(format: LabelFormat, rows: Record<string, string>[]): {
+    labels: QrLabelPrintData["labels"];
+};
+/**
+ * The shipped formats. Every preset reads the QR payload from the `qrValue`
+ * column, so a row is always `{ qrValue, …format-specific columns }`.
+ *
+ * NOTE on `asset-spec`: the cell renderer auto-shrinks only the caption/badge
+ * (`.lp-fit`); detail lines are fixed 8pt, so the title never loses size to a
+ * long spec list.
+ */
+declare const LABEL_FORMAT_PRESETS: readonly LabelFormat[];
+
+export { LABEL_FORMAT_PRESETS, LABEL_TEMPLATES, type LabelElement, type LabelField, type LabelFormat, type LabelTemplate, MIN_SCANNABLE_MODULE_MM, type QrEcLevel, type QrLabel, type QrLabelPrintData, type QrLabelSettings, type ScannabilityReport, applyLabelFormat, assertScannable, assertTemplateGeometry, computeCellLayout, customLabelTemplate, downloadLabelsPdf, expandLabels, generateQrDataUri, getLabelTemplate, printCalibrationSheet, printQrLabelSheet, qrLabelsPrinter };