// Type declarations for @labelviewer/elements. Importing the package defines <zpl-editor> and <zpl-viewer>.

/** 'fit' (fit the element), 'actual' (physical size on a calibrated screen) or CSS pixels per printer dot (1 = 100%). */
export type ZplZoom = 'fit' | 'actual' | number;

/** Printhead density in dots per millimetre: 6 (152 dpi), 8 (203 dpi), 12 (300 dpi) or 24 (600 dpi). */
export type ZplDpmm = 6 | 8 | 12 | 24;

/** One sample record, or an array of records (one copy of the template per record). */
export type ZplData = Record<string, unknown> | Array<Record<string, unknown>>;

/** Feature names that `features="no-<name> ..."` turns off. */
export type ZplEditorFeature = 'file' | 'samples' | 'history' | 'settings' | 'help' | 'toolbox' | 'properties' | 'code' | 'data' | 'variables' | 'api' | 'warnings';

/**
 * A starter template for the "New from sample" gallery. The built-in ones are GS1-128 carton and pallet labels; they are
 * starting points, not certified for any retailer.
 */
export interface ZplSample {
    id: string;
    title: string;
    /** Hint only: a retailer with similar fields, shown as "Similar fields to: Walmart". Not a claim of compliance. */
    retailer?: string;
    description: string;
    widthIn: number;
    heightIn: number;
    dpmm: ZplDpmm;
    /** ZPL template; `{{path|example}}` placeholders show their example in the preview. */
    zpl: string;
    /** Loaded into the Sample data tab. */
    data?: ZplData;
}

export interface ZplSampleLoadDetail {
    /** The id of the sample that replaced the document. */
    id: string;
}

export interface ZplChangeDetail {
    /** The template after the edit. */
    value: string;
}

/** The label settings a template was saved with. */
export interface ZplSaveSettings {
    dpmm: ZplDpmm;
    /** Label width in inches. */
    widthIn: number;
    /** Label height in inches. */
    heightIn: number;
}

export interface ZplSaveDetail {
    /** The template being saved. */
    value: string;
    /** The sample data (a copy), or undefined when there is none or it is not valid JSON. */
    sampleData: ZplData | undefined;
    settings: ZplSaveSettings;
    /** The file name given to load(), or of the file last opened with Open (default "label.zpl"). */
    fileName: string;
}

/**
 * Stores the template (Save button, Ctrl/Cmd+S). While it runs the status bar says "Saving…" and Save is disabled. Resolve
 * when stored: the saved value becomes the baseline (edits made meanwhile stay unsaved). Return `{ value }` if you stored
 * something else (e.g. normalised it). Reject to report "Save failed: <message>" (and an `error` event, source "save").
 */
export type ZplSaveHandler = (detail: ZplSaveDetail) => Promise<void | { value?: string }> | void | { value?: string };

/** `load()`: a document from your storage, replacing the current one in one step. */
export interface ZplLoadOptions {
    /** The template. */
    zpl: string;
    /** Sample data (object, array, or JSON text); omitted = no sample data. */
    sampleData?: ZplData | string;
    dpmm?: ZplDpmm;
    /** Label width in inches (0.1 to 15). */
    width?: number;
    /** Label height in inches (0.1 to 15). */
    height?: number;
    /** Reported in the `save` event's detail; default "label.zpl". */
    fileName?: string;
}

export interface ZplDirtyChangeDetail {
    /** True when the template differs from the saved baseline. */
    dirty: boolean;
}

export interface ZplFieldInfo {
    /** Index of the field in the template (0-based), stable until the text before it changes. */
    ordinal: number;
    kind: 'text' | 'barcode' | 'graphic' | 'image' | 'other';
    /** The field's type command, e.g. "^A", "^BC", "^GB"; null when it has none. */
    command: string | null;
    /** The field's span in the template text (string offsets, end exclusive). */
    start: number;
    end: number;
    /** Ink bounding box in label dots on label `label`; null when the field draws nothing. */
    box: { label: number; x: number; y: number; w: number; h: number } | null;
}

export interface ZplSelectDetail {
    /** The first selected field, or null when nothing is selected. */
    field: ZplFieldInfo | null;
    ordinals: number[];
}

export interface ZplRenderDetail {
    /** Number of labels rendered. */
    labels: number;
    warnings: string[];
}

export interface ZplErrorDetail {
    /** `license`: the install's license does not cover the element's product; a notice replaces its content. */
    source: 'fonts' | 'render' | 'api' | 'merge' | 'data' | 'save' | 'license';
    message: string;
    /** HTTP status, for source "api". */
    status?: number;
    /** Merge error details, for source "merge": [{ record, placeholder, reason }]. */
    details?: Array<{ record: number | null; placeholder: string | null; reason: string }>;
}

/** The element's events; `change`, `select` and `error` are CustomEvents here, not the DOM's events of those names. */
export interface ZplEditorEventMap extends Omit<HTMLElementEventMap, 'change' | 'select' | 'error' | 'save' | 'render'> {
    change: CustomEvent<ZplChangeDetail>;
    save: CustomEvent<ZplSaveDetail>;
    select: CustomEvent<ZplSelectDetail>;
    render: CustomEvent<ZplRenderDetail>;
    error: CustomEvent<ZplErrorDetail>;
    'sample-load': CustomEvent<ZplSampleLoadDetail>;
    'dirty-change': CustomEvent<ZplDirtyChangeDetail>;
}

export interface ZplViewerEventMap extends Omit<HTMLElementEventMap, 'error' | 'render'> {
    render: CustomEvent<ZplRenderDetail>;
    error: CustomEvent<ZplErrorDetail>;
}

/** The label designer. */
export class ZplEditorElement extends HTMLElement {
    /** The ZPL template. Setting a different value replaces the document and clears the undo history. */
    value: string;
    /** Sample data for the preview, the Variables tab and Export merged (attribute `sample-data`: JSON). */
    sampleData: ZplData | undefined;
    dpmm: ZplDpmm;
    /** Label width in inches (0.1 to 15). */
    width: number;
    /** Label height in inches (0.1 to 15). */
    height: number;
    /** Ignore ^PO I so the label reads the right way up (default true; attribute `upright="false"` turns it off). */
    upright: boolean;
    zoom: ZplZoom;
    /**
     * Base URL of the labelviewer install's API (attribute `api-base`), e.g. "https://labels.example.com". Default: the
     * origin of the install the bundle was loaded from (`…/sdk/<version>/labelviewer-elements[.min].js`), else '' (Test
     * with API and the API tab are hidden). Setting '' returns to the default; reading gives the effective value.
     */
    apiBase: string;
    /** Where the font files are served (attribute `fonts-base-url`); default: fonts/ next to the script. */
    fontsBaseUrl: string;
    readonly: boolean;
    /** Space-separated `no-<feature>` tokens, e.g. "no-file no-api". */
    features: string;
    /** localStorage key for drafts (attribute `autosave-key`); no storage without it. Read on connect. */
    autosaveKey: string;
    /** The "New from sample" gallery (property only). Default: the built-in starter samples; [] hides the action. */
    samples: ZplSample[];
    /** Property only. Stores the template on Save; without it Save only fires `save` and you call markSaved(). */
    saveHandler: ZplSaveHandler | undefined;
    /** Ask before the page is left while the template is unsaved (attribute `warn-unsaved`). */
    warnUnsaved: boolean;
    /** True when the template differs from the saved baseline (load, value set, markSaved or a successful saveHandler). */
    readonly dirty: boolean;
    /** Resolves after the fonts are loaded and the first render is done. */
    readonly ready: Promise<void>;
    /** Replace the document: clears the undo history, `zpl` becomes the saved baseline, no `change` event. Wins over an autosaved draft. */
    load(options: ZplLoadOptions): void;
    /** Make `value` (default: the current template) the saved baseline. */
    markSaved(value?: string): void;
    getValue(): string;
    setValue(value: string): void;
    render(): ZplRenderDetail;
    /** The template merged with `data` (default: the sample data) in the browser. Throws a MergeError. */
    exportMerged(data?: ZplData): string;
    undo(): void;
    redo(): void;
    focus(options?: FocusOptions): void;
    addEventListener<K extends keyof ZplEditorEventMap>(type: K, listener: (this: ZplEditorElement, ev: ZplEditorEventMap[K]) => unknown, options?: boolean | AddEventListenerOptions): void;
    addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
    removeEventListener<K extends keyof ZplEditorEventMap>(type: K, listener: (this: ZplEditorElement, ev: ZplEditorEventMap[K]) => unknown, options?: boolean | EventListenerOptions): void;
    removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
}

/**
 * Read-only label preview: the rendered label as a PNG image (`<img>`, part `image`), with a pager for several labels.
 * Shadow parts: `frame`, `stage`, `image` (also `canvas`, deprecated), `pager`, `message`, `blocked` (the not-licensed notice).
 */
export class ZplViewerElement extends HTMLElement {
    /** ZPL, or a template with {{placeholders}}. */
    zpl: string;
    /** Data to merge into `zpl`; an array renders every record (pager), unless `record` picks one. Attribute: JSON. */
    data: ZplData | undefined;
    /** With array data: the record to show (0-based); null = all. */
    record: number | null;
    dpmm: ZplDpmm;
    width: number;
    height: number;
    upright: boolean;
    zoom: ZplZoom;
    /** The label shown (0-based). */
    label: number;
    /** Alternative text of the label image (attribute `alt`). Default "Label preview". */
    alt: string;
    fontsBaseUrl: string;
    /**
     * The labelviewer install whose license applies (attribute `api-base`). Default: the origin of the install the bundle
     * was loaded from, else '' (the license cannot be checked: the viewer works and warns once in the console).
     */
    apiBase: string;
    /** Number of labels of the last render. */
    readonly labelCount: number;
    render(): ZplRenderDetail;
    /** The label (default: the one shown) as a 1-bit PNG at printer dots (watermarked on a trial license). Rejects when not licensed. */
    toPNG(index?: number): Promise<Blob>;
    /** Print the label (default: the one shown) at its physical size. */
    print(index?: number): Promise<void>;
    addEventListener<K extends keyof ZplViewerEventMap>(type: K, listener: (this: ZplViewerElement, ev: ZplViewerEventMap[K]) => unknown, options?: boolean | AddEventListenerOptions): void;
    addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
    removeEventListener<K extends keyof ZplViewerEventMap>(type: K, listener: (this: ZplViewerElement, ev: ZplViewerEventMap[K]) => unknown, options?: boolean | EventListenerOptions): void;
    removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
}

/** The font files the renderer needs. */
export const FONT_FILE_NAMES: readonly string[];

/** Supply the font bytes yourself instead of serving them from fonts-base-url. Call before the first element connects. */
export function registerFonts(fonts: Record<string, ArrayBuffer | Uint8Array>): void;

/** Start loading the fonts now; resolves when they are available. */
export function loadFonts(baseUrl?: string): Promise<void>;

export const version: string;

declare global {
    interface HTMLElementTagNameMap {
        'zpl-editor': ZplEditorElement;
        'zpl-viewer': ZplViewerElement;
    }
}