@ai-matrx/print 0.1.0

package/dist/react.d.cts

@@ -0,0 +1,301 @@
+import * as React from 'react';
+
+/**
+ * @ai-matrx/print/core — the Block Print contract & print-window composition.
+ *
+ * Ported VERBATIM from matrx-frontend `lib/block-print/block-print-utils.ts`
+ * (2026-08-29 state, including the `number` and `select` PrintSetting types the
+ * commerce label lane added). Zero dependencies; touches `window` only at call
+ * time, so the module stays import-inert and RSC-safe.
+ *
+ * BlockPrinter is the only interface a host system needs to know about.
+ * Each printable unit exports its own BlockPrinter alongside its render
+ * component; host code only ever calls print(data, variantId, settings).
+ *
+ * `buildFitTextScript` is the ONE auto-shrink script (the flashcards
+ * FIT_TEXT pattern, parameterized by selector so the label lane shares it).
+ */
+interface PrintVariant {
+    id: string;
+    label: string;
+    description?: string;
+}
+/**
+ * A single user-configurable setting shown in the print dialog.
+ * Extend the discriminated union for new control types
+ * without breaking existing printers.
+ */
+type PrintSetting = {
+    type: "boolean";
+    id: string;
+    label: string;
+    description?: string;
+    /** Default value shown when the dialog first opens */
+    defaultValue: boolean;
+    /** Which variant IDs this setting applies to. Omit = applies to all. */
+    appliesTo?: string[];
+} | {
+    /**
+     * A numeric "from → to" range control, rendered as two small number inputs.
+     * Writes two entries into the resolved PrintSettings map — one under fromId,
+     * one under toId. Printers interpret 0 (or missing) as "no bound" by convention.
+     */
+    type: "range";
+    /** Stable id used as React key — not written to the settings map */
+    id: string;
+    label: string;
+    description?: string;
+    /** Settings map key for the lower bound value */
+    fromId: string;
+    /** Settings map key for the upper bound value */
+    toId: string;
+    defaultFrom: number;
+    defaultTo: number;
+    /** Minimum accepted value for each input (inclusive). Default 0. */
+    min?: number;
+    /** Placeholder shown when the input is empty (0). Default "start" / "end". */
+    fromPlaceholder?: string;
+    toPlaceholder?: string;
+    /** Which variant IDs this setting applies to. Omit = applies to all. */
+    appliesTo?: string[];
+} | {
+    /** A single numeric input (e.g. "start at label #", "copies"). */
+    type: "number";
+    id: string;
+    label: string;
+    description?: string;
+    defaultValue: number;
+    /** Minimum accepted value (inclusive). Default 0. */
+    min?: number;
+    /** Maximum accepted value (inclusive). Omit = unbounded. */
+    max?: number;
+    /** Which variant IDs this setting applies to. Omit = applies to all. */
+    appliesTo?: string[];
+} | {
+    /** A one-of-N choice rendered as a compact segmented row. */
+    type: "select";
+    id: string;
+    label: string;
+    description?: string;
+    options: {
+        value: string;
+        label: string;
+    }[];
+    defaultValue: string;
+    /** Which variant IDs this setting applies to. Omit = applies to all. */
+    appliesTo?: string[];
+};
+/** A resolved map of setting id → current value, passed to print(). */
+type PrintSettings = Record<string, boolean | string | number>;
+/**
+ * The self-contained print capability that each block can export.
+ * Host code only ever calls print(data, variantId, settings) — it never inspects internals.
+ */
+interface BlockPrinter {
+    /** Tooltip / aria-label for the print button in the block header */
+    label: string;
+    /**
+     * Variants offered to the user before printing.
+     * Empty array = no options dialog shown; prints immediately with defaults.
+     */
+    variants: PrintVariant[];
+    /**
+     * Optional user-configurable settings shown below the variant picker.
+     * Omit entirely if the block has no configurable settings.
+     */
+    settings?: PrintSetting[];
+    /**
+     * Execute the print.
+     * data      — the block's structured data (serverData or parsed content)
+     * variantId — which variant was chosen (undefined = default / no variants)
+     * settings  — resolved setting values chosen by the user
+     */
+    print: (data: unknown, variantId?: string, settings?: PrintSettings) => void | Promise<void>;
+}
+
+/**
+ * @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";
+}
+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;
+}
+type QrEcLevel = "L" | "M" | "Q";
+
+/**
+ * @ai-matrx/print/react — the package's ONLY React entry.
+ *
+ * Two components, ported verbatim from matrx-frontend:
+ *   PrintOptionsDialog  ← lib/block-print/PrintOptionsDialog.tsx
+ *   LabelSheetPreview   ← lib/label-print/LabelSheetPreview.tsx
+ *
+ * The app seams are inverted here and NOWHERE else:
+ *   @/components/ui/dialog  → inline minimal wrappers over @radix-ui/react-dialog
+ *   @/components/ui/drawer  → inline minimal wrappers over vaul
+ *   @/components/ui/button  → PrintDialogButton (the design-system Button's
+ *                             exact class strings for the used variants)
+ *   @/hooks/use-mobile      → useIsMobile, reproduced behavior-for-behavior
+ *   lucide-react            → inline SVGs carrying lucide's own path data
+ *   @/lib/block-print/*     → ./core
+ *   ./label-templates, ./qr-labels-printer → ./labels
+ *
+ * NO "use client" directive lives in this file — tsup stamps this entry via a
+ * banner (see tsup.config.ts); a second literal directive here would be
+ * duplicated into dist.
+ *
+ * Tailwind class strings are the originals verbatim: the consuming app's theme
+ * tokens (bg-primary, text-muted-foreground, pb-safe…) style these components,
+ * exactly as they did in matrx-frontend.
+ */
+
+interface PrintOptionsDialogProps {
+    printer: BlockPrinter;
+    data: unknown;
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+}
+/**
+ * Shared pre-print options UI — shown when a BlockPrinter has variants or settings.
+ * Desktop: Dialog. Mobile: Drawer (bottom sheet).
+ */
+declare function PrintOptionsDialog({ printer, data, open, onOpenChange, }: PrintOptionsDialogProps): React.JSX.Element;
+/**
+ * Manages open state for PrintOptionsDialog.
+ * If the printer has variants or settings, shows the dialog.
+ * If it has neither, calls printer.print() immediately with no settings.
+ */
+declare function usePrintOptions(printer: BlockPrinter | null, data: unknown): {
+    open: boolean;
+    setOpen: React.Dispatch<React.SetStateAction<boolean>>;
+    triggerPrint: () => Promise<void>;
+};
+/**
+ * LabelSheetPreview — scaled on-screen preview of one label sheet, driven by
+ * the same LabelTemplate geometry as the printer (percent-positioned cells,
+ * so it is exactly proportional at any width). Also renders a calibration
+ * view (outlines only) so a user can eyeball the grid before printing.
+ *
+ * QR images are generated client-side to data URIs via `qrcode` (deferred
+ * import at effect time).
+ */
+interface LabelSheetPreviewProps {
+    template: LabelTemplate;
+    labels: QrLabel[];
+    /** 1-based first cell to fill — leading cells render empty. */
+    startAtLabel?: number;
+    showCaption?: boolean;
+    ecLevel?: QrEcLevel;
+    /** Outlines-only calibration view. */
+    calibration?: boolean;
+    /** Which sheet to show (0-based). */
+    pageIndex?: number;
+    className?: string;
+}
+declare function LabelSheetPreview({ template: t, labels, startAtLabel, showCaption, ecLevel, calibration, pageIndex, className, }: LabelSheetPreviewProps): React.JSX.Element;
+
+export { LabelSheetPreview, type LabelSheetPreviewProps, PrintOptionsDialog, type PrintOptionsDialogProps, usePrintOptions };

package/dist/react.d.ts

@@ -0,0 +1,301 @@
+import * as React from 'react';
+
+/**
+ * @ai-matrx/print/core — the Block Print contract & print-window composition.
+ *
+ * Ported VERBATIM from matrx-frontend `lib/block-print/block-print-utils.ts`
+ * (2026-08-29 state, including the `number` and `select` PrintSetting types the
+ * commerce label lane added). Zero dependencies; touches `window` only at call
+ * time, so the module stays import-inert and RSC-safe.
+ *
+ * BlockPrinter is the only interface a host system needs to know about.
+ * Each printable unit exports its own BlockPrinter alongside its render
+ * component; host code only ever calls print(data, variantId, settings).
+ *
+ * `buildFitTextScript` is the ONE auto-shrink script (the flashcards
+ * FIT_TEXT pattern, parameterized by selector so the label lane shares it).
+ */
+interface PrintVariant {
+    id: string;
+    label: string;
+    description?: string;
+}
+/**
+ * A single user-configurable setting shown in the print dialog.
+ * Extend the discriminated union for new control types
+ * without breaking existing printers.
+ */
+type PrintSetting = {
+    type: "boolean";
+    id: string;
+    label: string;
+    description?: string;
+    /** Default value shown when the dialog first opens */
+    defaultValue: boolean;
+    /** Which variant IDs this setting applies to. Omit = applies to all. */
+    appliesTo?: string[];
+} | {
+    /**
+     * A numeric "from → to" range control, rendered as two small number inputs.
+     * Writes two entries into the resolved PrintSettings map — one under fromId,
+     * one under toId. Printers interpret 0 (or missing) as "no bound" by convention.
+     */
+    type: "range";
+    /** Stable id used as React key — not written to the settings map */
+    id: string;
+    label: string;
+    description?: string;
+    /** Settings map key for the lower bound value */
+    fromId: string;
+    /** Settings map key for the upper bound value */
+    toId: string;
+    defaultFrom: number;
+    defaultTo: number;
+    /** Minimum accepted value for each input (inclusive). Default 0. */
+    min?: number;
+    /** Placeholder shown when the input is empty (0). Default "start" / "end". */
+    fromPlaceholder?: string;
+    toPlaceholder?: string;
+    /** Which variant IDs this setting applies to. Omit = applies to all. */
+    appliesTo?: string[];
+} | {
+    /** A single numeric input (e.g. "start at label #", "copies"). */
+    type: "number";
+    id: string;
+    label: string;
+    description?: string;
+    defaultValue: number;
+    /** Minimum accepted value (inclusive). Default 0. */
+    min?: number;
+    /** Maximum accepted value (inclusive). Omit = unbounded. */
+    max?: number;
+    /** Which variant IDs this setting applies to. Omit = applies to all. */
+    appliesTo?: string[];
+} | {
+    /** A one-of-N choice rendered as a compact segmented row. */
+    type: "select";
+    id: string;
+    label: string;
+    description?: string;
+    options: {
+        value: string;
+        label: string;
+    }[];
+    defaultValue: string;
+    /** Which variant IDs this setting applies to. Omit = applies to all. */
+    appliesTo?: string[];
+};
+/** A resolved map of setting id → current value, passed to print(). */
+type PrintSettings = Record<string, boolean | string | number>;
+/**
+ * The self-contained print capability that each block can export.
+ * Host code only ever calls print(data, variantId, settings) — it never inspects internals.
+ */
+interface BlockPrinter {
+    /** Tooltip / aria-label for the print button in the block header */
+    label: string;
+    /**
+     * Variants offered to the user before printing.
+     * Empty array = no options dialog shown; prints immediately with defaults.
+     */
+    variants: PrintVariant[];
+    /**
+     * Optional user-configurable settings shown below the variant picker.
+     * Omit entirely if the block has no configurable settings.
+     */
+    settings?: PrintSetting[];
+    /**
+     * Execute the print.
+     * data      — the block's structured data (serverData or parsed content)
+     * variantId — which variant was chosen (undefined = default / no variants)
+     * settings  — resolved setting values chosen by the user
+     */
+    print: (data: unknown, variantId?: string, settings?: PrintSettings) => void | Promise<void>;
+}
+
+/**
+ * @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";
+}
+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;
+}
+type QrEcLevel = "L" | "M" | "Q";
+
+/**
+ * @ai-matrx/print/react — the package's ONLY React entry.
+ *
+ * Two components, ported verbatim from matrx-frontend:
+ *   PrintOptionsDialog  ← lib/block-print/PrintOptionsDialog.tsx
+ *   LabelSheetPreview   ← lib/label-print/LabelSheetPreview.tsx
+ *
+ * The app seams are inverted here and NOWHERE else:
+ *   @/components/ui/dialog  → inline minimal wrappers over @radix-ui/react-dialog
+ *   @/components/ui/drawer  → inline minimal wrappers over vaul
+ *   @/components/ui/button  → PrintDialogButton (the design-system Button's
+ *                             exact class strings for the used variants)
+ *   @/hooks/use-mobile      → useIsMobile, reproduced behavior-for-behavior
+ *   lucide-react            → inline SVGs carrying lucide's own path data
+ *   @/lib/block-print/*     → ./core
+ *   ./label-templates, ./qr-labels-printer → ./labels
+ *
+ * NO "use client" directive lives in this file — tsup stamps this entry via a
+ * banner (see tsup.config.ts); a second literal directive here would be
+ * duplicated into dist.
+ *
+ * Tailwind class strings are the originals verbatim: the consuming app's theme
+ * tokens (bg-primary, text-muted-foreground, pb-safe…) style these components,
+ * exactly as they did in matrx-frontend.
+ */
+
+interface PrintOptionsDialogProps {
+    printer: BlockPrinter;
+    data: unknown;
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+}
+/**
+ * Shared pre-print options UI — shown when a BlockPrinter has variants or settings.
+ * Desktop: Dialog. Mobile: Drawer (bottom sheet).
+ */
+declare function PrintOptionsDialog({ printer, data, open, onOpenChange, }: PrintOptionsDialogProps): React.JSX.Element;
+/**
+ * Manages open state for PrintOptionsDialog.
+ * If the printer has variants or settings, shows the dialog.
+ * If it has neither, calls printer.print() immediately with no settings.
+ */
+declare function usePrintOptions(printer: BlockPrinter | null, data: unknown): {
+    open: boolean;
+    setOpen: React.Dispatch<React.SetStateAction<boolean>>;
+    triggerPrint: () => Promise<void>;
+};
+/**
+ * LabelSheetPreview — scaled on-screen preview of one label sheet, driven by
+ * the same LabelTemplate geometry as the printer (percent-positioned cells,
+ * so it is exactly proportional at any width). Also renders a calibration
+ * view (outlines only) so a user can eyeball the grid before printing.
+ *
+ * QR images are generated client-side to data URIs via `qrcode` (deferred
+ * import at effect time).
+ */
+interface LabelSheetPreviewProps {
+    template: LabelTemplate;
+    labels: QrLabel[];
+    /** 1-based first cell to fill — leading cells render empty. */
+    startAtLabel?: number;
+    showCaption?: boolean;
+    ecLevel?: QrEcLevel;
+    /** Outlines-only calibration view. */
+    calibration?: boolean;
+    /** Which sheet to show (0-based). */
+    pageIndex?: number;
+    className?: string;
+}
+declare function LabelSheetPreview({ template: t, labels, startAtLabel, showCaption, ecLevel, calibration, pageIndex, className, }: LabelSheetPreviewProps): React.JSX.Element;
+
+export { LabelSheetPreview, type LabelSheetPreviewProps, PrintOptionsDialog, type PrintOptionsDialogProps, usePrintOptions };