import { type SaveImageHandler, type SaveTextHandler, type UserGuideExtension } from './toolbar.js';
import type { Die } from '../core/dies.js';
import type { WaferViewOptions } from './renderWaferMap.js';
import type { RenderableWaferMap } from './renderWaferMap.js';
import type { LotStatsSummary } from '../stats/types.js';
import { type WarningsOptions } from './warnings.js';
import type { SummaryPanelOptions } from './summaryPanel.js';
import { type InsightsOptions } from './insightsTab.js';
/**
 * The data and display overrides for a single gallery card.
 *
 * `WaferMapResult` satisfies this interface structurally, so you can pass
 * `buildWaferMap(...)` results directly. Spread in display overrides as needed:
 *
 * ```ts
 * renderWaferGallery(container, [
 *   result1,
 *   { ...result2, label: 'W02', statsSummary: summary2 },
 * ]);
 * ```
 */
export interface WaferMapDisplayItem extends RenderableWaferMap {
    label?: string;
    /** Merged on top of the shared gallery options for this card only. */
    viewOptions?: Partial<WaferViewOptions>;
    /** Shown in the findings panel when this card is opened in its own window. */
    statsSummary?: import('../stats/types.js').StatsSummary;
    onClick?: (die: Die, event: MouseEvent) => void;
    onSelect?: (dies: Die[]) => void;
}
/**
 * A factory function that builds a WaferMapDisplayItem on demand.
 * The gallery calls each factory in a deferred task (`setTimeout(0)`) so the
 * browser stays responsive while large item sets are built progressively.
 */
export type WaferMapDisplayItemFactory = () => WaferMapDisplayItem;
export interface GalleryOptions {
    /** Initial shared scene options applied to all cards. */
    viewOptions?: WaferViewOptions;
    /** Called whenever a shared gallery option changes. */
    onViewOptionsChange?: (opts: WaferViewOptions, changed: (keyof WaferViewOptions)[], category: 'preference' | 'state' | 'mixed') => void;
    /** Legend position for bin modes. Default 'default'. */
    legendPosition?: 'default' | 'compact' | 'bottom' | 'top' | 'left' | 'floating';
    /** Padding inside each card canvas in CSS pixels. Default 6. */
    cardPadding?: number;
    /** Filename stem for the composite gallery PNG. Default 'wafer-gallery'. */
    downloadFilename?: string;
    /**
     * Host hook for persisting the composite gallery PNG. When provided, the save
     * action calls `onSaveImage(blob, suggestedName)` instead of triggering a
     * browser `<a download>` — letting embedded hosts (Tauri, Electron, WebView2)
     * route the image through a native save dialog. `suggestedName` includes the
     * `.png` extension and is derived from `downloadFilename`. When omitted, the
     * default browser download behaviour is unchanged.
     */
    onSaveImage?: SaveImageHandler;
    /**
     * Host hook for saving the Summary/Insights test-values table's "Export CSV"
     * button. Mirrors `onSaveImage` — when provided, called with
     * `(text, suggestedName, mimeType)` instead of triggering a browser
     * `<a download>` (a silent no-op in Tauri/Electron/WebView2). When omitted,
     * the default browser download behaviour is unchanged.
     */
    onSaveText?: SaveTextHandler;
    /**
     * Format to use for unitless values outside the normal display range [0.1, 9999].
     * `'engineering'` (default): multiples-of-3 exponent notation (e.g. `12E-6`).
     * `'si'`: SI prefix with no unit suffix (e.g. `12 µ`).
     * Values with a unit always use SI prefix regardless of this setting.
     */
    fallbackFormat?: 'si' | 'engineering';
    /**
     * Show the plot mode selector in the gallery control bar. Default true.
     * Set to false when the host application manages mode switching itself.
     */
    showPlotModeSelector?: boolean;
    /** Precomputed lot-level stats summary. Enables the summary panel toggle button in the control bar. */
    lotStatsSummary?: LotStatsSummary;
    /**
     * Options for the always-available Summary panel alongside the gallery
     * grid — a "Lot" tab with full lot-level stats (metadata, yield, bin
     * breakdown, ring/quadrant yield, test values, findings) and a combined
     * Report button, plus a "Wafers" tab listing every wafer that has its own
     * per-wafer findings (click a row to open that wafer). Independent of
     * `insights` below: this always shows/hides its own toolbar button
     * regardless of whether Insights is open, since Insights has no per-wafer
     * map for a finding to highlight against.
     */
    summaryPanel?: SummaryPanelOptions;
    /**
     * Bin numbers treated as pass for yield calculation in the summary panel.
     * Defaults to `[1]`. Must match the `passBins` passed to `analyzeWaferLot` / `buildWaferMap`
     * to ensure the summary panel yield label is consistent with the rest of the display.
     */
    passBins?: number[];
    /**
     * Fix the number of columns in the gallery grid. When set, overrides the
     * auto-computed minimum card width and the toolbar columns control.
     * Omit (default) to let the gallery auto-size cards based on die pitch.
     */
    columns?: number;
    /**
     * Cap each gallery card's rendered width and height at this many CSS pixels.
     * Cards pack from the left rather than stretching to fill the grid width.
     *
     * Omit it and the cap is derived from die density: 480px for an ordinary
     * wafer, widening (to at most 720px) for high-DPW wafers that need the room
     * to keep dies readable. Set it to take hard control instead — an explicit
     * value is never widened, so you own the readability trade-off at high DPW.
     */
    maxSize?: number;
    /**
     * Show a help button in the gallery control bar that opens the built-in end-user guide in a modal.
     * Default false. Enable in applications that want to surface the guide without linking externally.
     */
    showHelpButton?: boolean;
    /**
     * Host-supplied content inserted into the built-in end-user guide window
     * (see `showHelpButton`) — e.g. a host app's own documentation, so the user
     * has one help button instead of two. See `UserGuideExtension`.
     */
    userGuideExtension?: UserGuideExtension;
    /**
     * Base `z-index` for wmap's transient overlays — toolbar menus, the die
     * tooltip, the expand modal, and the user-guide modal. wmap layers its own
     * overlays from this value upward. Set this when embedding the gallery inside
     * your own modal/overlay so wmap's menus and tooltips appear above it.
     *
     * Omit it and wmap defaults overlays to a high value (above typical app modal
     * layers). Applied for the lifetime of this render and restored on `destroy()`.
     */
    zIndex?: number;
    /**
     * Show an "Insights" tab in the control bar (see `InsightsOptions`).
     * Selecting it replaces the gallery grid with wmap's own chart suite
     * across Overview/Distributions/Correlation sub-tabs. The tab computes
     * its own "Group by" facets from each item's `wafer.metadata`
     * (`stats/facets.ts`) and, when `lotStatsSummary` is also provided,
     * reuses its precomputed per-wafer yield directly rather than
     * recomputing it — no other host wiring beyond this option.
     */
    insights?: InsightsOptions;
    /**
     * Built-in surfacing of the library's own data warnings (see `WarningsOptions`).
     * Defaults on. The gallery collects across every item and de-duplicates, so a
     * geometry advisory affecting the whole lot is stated once, not per card.
     */
    warnings?: WarningsOptions;
}
export interface GalleryController {
    /** Replace all items — destroys existing cards and rebuilds the grid. Accepts pre-built items, factory functions, or a mix. */
    setItems(items: Array<WaferMapDisplayItem | WaferMapDisplayItemFactory>): void;
    /** Merge shared scene option overrides across all cards. */
    setOptions(opts: Partial<WaferViewOptions>): void;
    /** Return the current shared scene options. */
    getOptions(): WaferViewOptions;
    /** Update the fallback format for unitless values across all cards. */
    setFallbackFormat(format: 'si' | 'engineering'): void;
    /** Replace the lot-level stats summary used by the built-in Summary panel. */
    setLotStatsSummary(summary: LotStatsSummary | undefined): void;
    /**
     * Set the number of columns in the gallery grid. Pass `undefined` to restore
     * the auto-computed layout based on die pitch.
     */
    setColumns(columns: number | undefined): void;
    /**
     * Opens the built-in end-user guide window — the same action the help
     * toolbar button performs, but callable directly. Works regardless of
     * `showHelpButton`'s current value, so a host that hides wmap's own help
     * button (e.g. to fold it into its own combined help menu) can still
     * trigger the guide without a DOM query against wmap's internal button
     * markup.
     */
    openUserGuide(): void;
    /** Remove all DOM and event listeners. */
    destroy(): void;
}
export declare function renderWaferGallery(container: HTMLElement, items: Array<WaferMapDisplayItem | WaferMapDisplayItemFactory>, options?: GalleryOptions): GalleryController;
//# sourceMappingURL=renderWaferGallery.d.ts.map