@wafertools/wafermap 0.26.1 → 0.28.0

package/dist/packages/canvas-adapter/toolbar.d.ts

@@ -3,8 +3,172 @@ import type { Die } from '../core/dies.js';
 import type { TestDef, MetadataFieldDef } from '../renderer/buildWaferMap.js';
 import type { StatsSeverity } from '../stats/types.js';
 export declare function logWmapVersionOnce(): void;
-export declare const WMAP_TOKEN_NAMES: readonly ["z", "icon", "icon-hover", "icon-active", "bg-hover", "bg-active", "separator", "surface", "border", "menu-hover", "menu-active", "panel-bg", "text-muted", "text", "text-strong", "warn-bg", "warn-border", "warn-text", "err-bg", "err-border", "err-text", "info-bg", "info-text", "selected", "finding-indicator", "canvas-bg", "bar-fill", "bar-fill-muted"];
+export declare const WMAP_TOKEN_NAMES: readonly ["z", "icon", "icon-hover", "icon-active", "bg-hover", "bg-active", "separator", "surface", "border", "control-border", "menu-hover", "menu-active", "font-family", "font-size", "density", "panel-bg", "text-muted", "text", "text-strong", "warn-bg", "warn-border", "warn-text", "err-bg", "err-border", "err-text", "info-bg", "info-text", "selected", "finding-indicator", "canvas-bg", "bar-fill"];
 export type WmapTokenName = (typeof WMAP_TOKEN_NAMES)[number];
+/**
+ * The shapes an interactive element comes in. Nineteen sites set
+ * `cursor: pointer` with their own padding, border, radius and hover handling;
+ * they were not nineteen different controls, but four shapes restated by hand.
+ * That restatement is the mechanism behind most of the drift this file's other
+ * scales exist to stop.
+ *
+ * These return STYLE, not elements — call sites keep their own markup and event
+ * wiring, and merely stop deciding what a button looks like. Spread first, then
+ * add layout:
+ *
+ *   Object.assign(btn.style, { ...controlStyle('outlined'), marginLeft: 'auto' });
+ */
+export type ControlKind = 
+/** Bordered, transparent ground — the default button (Summary report, Export CSV). */
+'outlined'
+/** No border or ground — icon buttons and inline text actions. */
+ | 'bare'
+/** Bordered, tinted when on — segmented options and filter toggles. */
+ | 'toggle';
+/**
+ * Give a control the library's hover feedback. `controlStyle` returns static
+ * style and cannot attach listeners, so this is the second half of the pair —
+ * call it wherever you spread `controlStyle`.
+ *
+ * Without it a bordered control is indistinguishable from a bordered label: it
+ * has the shape of a button and does nothing when the pointer is over it.
+ * wmap's toolbar icon buttons wired this from the start; its outlined TEXT
+ * buttons (Summary report, View die list, the CSV exports, Back) wired nothing
+ * at all, so the two halves of the same library disagreed about whether a
+ * button reacts. tsmap's `.tb-btn` has always had it.
+ */
+export declare function wireControlHover(el: HTMLElement, kind?: ControlKind): void;
+export declare function controlStyle(kind: ControlKind, on?: boolean): Partial<CSSStyleDeclaration>;
+export declare const SPACE: {
+    xxs: string;
+    xs: string;
+    sm: string;
+    md: string;
+    lg: string;
+    xl: string;
+    xxl: string;
+    xxxl: string;
+};
+/**
+ * Elevation. Fourteen distinct box-shadow literals existed across the two repos
+ * with no rule for which belonged where, so every new component invented one.
+ * Three tiers is what the values actually clustered into.
+ */
+export declare const SHADOW: {
+    /** Resting surface — a panel or card sitting on the page. */
+    panel: string;
+    /** Transient overlay — menu, dropdown, popover, tooltip. */
+    menu: string;
+    /** Modal — the only thing above everything else. */
+    modal: string;
+};
+/**
+ * Motion. One duration and one easing: a UI this dense has no reason to vary
+ * them, and ten different `transition` literals is not expressiveness, it is
+ * ten authors guessing. Respect `prefers-reduced-motion` at the call site.
+ */
+export declare const MOTION: {
+    /** State changes — hover, active, disclosure. */
+    fast: string;
+    /** Movement the eye should follow — a chevron rotating, a panel sliding. */
+    base: string;
+};
+/** Line height. Tight for single-line chrome, base for prose. */
+export declare const LEADING: {
+    none: string;
+    tight: string;
+    base: string;
+};
+/** Opacity. `muted` de-emphasises; `disabled` is the one WCAG-relevant value. */
+export declare const ALPHA: {
+    muted: string;
+    disabled: string;
+};
+/** Uppercase micro-label tracking — one value, not four. */
+export declare const TRACKING = "0.05em";
+/**
+ * Horizontal gutter between a scrolling surface's cards and the edge of the
+ * window (or host container) they scroll inside.
+ *
+ * A card is a bounded surface: flush to the viewport you see three borders and
+ * the screen edge standing in for the fourth, which reads as clipped rather
+ * than as a design choice. This is the gap that stops that.
+ *
+ * Why 12 (`SPACE.xl`): three different insets were in use when this was added —
+ * the Insights bands at 10, the gallery bar at 4, and tsmap's own `#toolbar` at
+ * 12 — so there was no incumbent value to inherit. 12 is on the `SPACE` scale,
+ * sits at the tight end of the 12-24px page-margin range the major design
+ * systems use (Material/HIG 16, Bootstrap 12), which is the right end for a
+ * dense analysis tool, and is the only candidate with an anchor outside this
+ * library: it matches the host toolbar directly above the map, so cards line up
+ * with the toolbar's own content rather than missing it by a couple of pixels.
+ *
+ * Deliberately NOT applied to the wafer map canvas, which stays full-bleed —
+ * map area is the priority and a margin would only shrink it. Same exception
+ * UI_STANDARDS.md already names for content that wants to fill its box.
+ */
+export declare const EDGE_GUTTER: string;
+/**
+ * Inset for a wafer map's OWN chrome — its chrome row (identity + toolbar) and
+ * a Summary panel docked inside the map area — from the edge of that map area.
+ *
+ * Deliberately small, and deliberately NOT `EDGE_GUTTER`. That one is the gap
+ * between a bounded surface and the edge of the REGION it lives in. A map
+ * embedded in a gallery card is already inside such a region: the card supplies
+ * the outer inset, and a second 12px within it stacks two gutters — the thing
+ * UI_STANDARDS.md's gutter rule forbids. It reads exactly like what it is, a
+ * toolbar standing 12px off the side of a card.
+ *
+ * A STANDALONE map is the other case: there the map area IS the region, so its
+ * chrome takes `EDGE_GUTTER` like any other bounded surface against an edge.
+ * `RenderOptions.chromeInset` is how the caller says which it is —
+ * `renderWaferGallery` passes this value for its cards, everything else takes
+ * the `EDGE_GUTTER` default.
+ *
+ * This constant was deleted once, when the toolbar moved out of the map box and
+ * the Summary panel was briefly its only user. That was wrong: the chrome row
+ * inherited the same context problem the moment it started carrying the
+ * toolbar, and giving every map `EDGE_GUTTER` put the two-gutter bug straight
+ * back into gallery cards.
+ */
+export declare const MAP_CHROME_INSET: string;
+export declare const RADIUS: {
+    /** Buttons, inputs, menu rows, segmented toggles, swatches. */
+    control: string;
+    /** Cards, panels, menus, modals — anything that contains other components. */
+    container: string;
+    /** Badges, count pills, status chips — fully rounded, size-independent. */
+    pill: string;
+};
+export declare const FONT: {
+    /**
+     * The typeface. wmap is embedded in a host and should read as part of it, so
+     * this INHERITS by default rather than imposing a stack — a host that sets
+     * nothing still gets the fallback below.
+     *
+     * There were three different hardcoded stacks across five sites
+     * (`system-ui, sans-serif` in the summary panel and toolbar,
+     * `system-ui, -apple-system, "Segoe UI", sans-serif` in the gallery), none
+     * matching tsmap's own `-apple-system`-first body stack. On Linux those
+     * resolve to different faces, so the summary panel's value table and the
+     * Insights value table — the same data, side by side — rendered in different
+     * typefaces.
+     */
+    family: string;
+    meta: string;
+    body: string;
+    sub: string;
+    heading: string;
+    stat: string;
+};
+/**
+ * The resolved numeric size for canvas `ctx.font`, in px. `delta` matches FONT's
+ * tiers for 0 and above (`body`, `sub`, `heading`, `stat`) and `-1` for `meta`.
+ * `-2` has no DOM tier by design: it is the map canvas's plot-coupled floor
+ * (colorbar tick labels, axis ticks — see toCanvas.ts), which annotates dense
+ * data rather than chrome and so sits below the 11px DOM minimum.
+ */
+export declare function fontPx(delta?: number, el?: Element | null): number;
 export declare const CLR: {
     icon: string;
     iconHover: string;
@@ -14,8 +178,10 @@ export declare const CLR: {
     separator: string;
     menuBg: string;
     menuBorder: string;
+    controlBorder: string;
     menuHover: string;
     menuActive: string;
+    canvasBg: string;
     panelBg: string;
     label: string;
     value: string;
@@ -31,7 +197,6 @@ export declare const CLR: {
     findingHighlight: string;
     findingIndicator: string;
     barFill: string;
-    barFillMuted: string;
 };
 /**
  * Findings-severity → colour, shared by summaryPanel.ts (severity dots/borders
@@ -110,7 +275,29 @@ export declare function setDetachWindowOpener(opener: DetachWindowOpener | null)
  * window is treated as titleless regardless of `document.title`). Navigating
  * to a real URL would fix it but means either re-running the host page's own
  * script inside the popup (real risk of double side effects) or requiring a
- * dedicated blank same-origin asset — not worth it for a cosmetic issue. */
+ * dedicated blank same-origin asset — not worth it for a cosmetic issue.
+ *
+ * Why this looks different from renderWaferMap's own "Expand" (a modal with
+ * wmap's own JS-drawn title bar, see `openOverlay` below): a real
+ * `window.open()` popup always carries genuine OS/browser chrome (title bar,
+ * and — deliberately, for anti-phishing reasons — an address-bar-ish
+ * element), and no window-features flag suppresses that in modern browsers;
+ * the feature string above (`width=560,height=600`) is sized-only for
+ * exactly this reason. This is a real inconsistency (raised 2026-08-29):
+ * `openWindowForCard`'s own fallback path (`window.open` returning null,
+ * e.g. Tauri's WebView) already routes through `openFloatingWindow` —
+ * wmap's own chrome, pixel-identical to the modal — so the mismatch is
+ * scoped to the real-popup case specifically.
+ *
+ * Possible future change: make `openWindowForCard` always take the
+ * `openFloatingWindow` branch (never call this function), for visual
+ * consistency with the standalone map's modal everywhere. Deliberately not
+ * done: the whole reason gallery cards detach into real windows rather than
+ * modals is so several can be open at once for side-by-side comparison,
+ * including dragged out to a second monitor — `openFloatingWindow`'s content
+ * is confined inside the host page/tab, so forcing it would trade away that
+ * capability for cosmetic consistency. Revisit only if that comparison
+ * workflow turns out not to matter in practice. */
 export declare function openDetachWindow(label: string): Window | null;
 export declare const MODE_LABELS: Record<PlotMode, string>;
 export declare const BIN_LEGEND_MODES: Set<PlotMode>;
@@ -170,6 +357,29 @@ export declare function saveTextFile(text: string, filename: string, mimeType: s
  * window." Passing the popup's own `window` fixes this.
  */
 export declare function nextFrame(fn: () => void, ownerWindow?: Window): void;
+/**
+ * Wire roving-focus keyboard navigation onto an already-roled menu:
+ * ArrowUp/Down move between items, Home/End jump to ends, Enter/Space activate
+ * the focused item, Escape (or Tab) closes the menu and returns focus to the
+ * trigger. `close` should remove the menu and clear any open-menu bookkeeping.
+ * Focus moves to the first item on open. Returns nothing; the listener lives on
+ * the menu element and dies with it.
+ */
+/**
+ * Roving keyboard focus over a live list of options — Arrow/Home/End to move,
+ * Enter/Space to activate, Escape/Tab to dismiss.
+ *
+ * Deliberately does NOT move focus itself: that is the one thing the two
+ * callers genuinely disagree about. A toolbar menu wants its first item focused
+ * on open; the searchable list in `chartShell.ts` must leave focus on its
+ * search box, and had its own copy of this whole switch for that single
+ * difference — thirty duplicated lines guarding one line of divergence.
+ *
+ * `items()` is called per keystroke, not captured: the searchable list filters
+ * its rows as you type, and a snapshot would navigate rows that are no longer
+ * shown.
+ */
+export declare function wireListNavigation(container: HTMLElement, items: () => HTMLElement[], dismiss: () => void): void;
 export declare function overlayRootFor(anchor: Element): Element;
 export declare function menuLayerFor(anchor: Element): HTMLElement;
 /** The shared tooltip element for `doc` (default: the host page's own
@@ -202,7 +412,48 @@ export declare function reparentTooltip(parent?: HTMLElement): void;
  * map), and the `parentElement !==` guard means the DOM is only actually
  * touched when the root has changed, not on every mousemove.
  */
+/**
+ * Place the tooltip near the cursor without covering the thing it describes.
+ *
+ * `anchor` used to be consulted only for `overlayRootFor` — placement was
+ * computed from the cursor point alone, and since `y` starts ABOVE the cursor
+ * (`clientY - 8`) the box then extended down over whatever was being pointed at.
+ * On the map canvas that is harmless and in fact necessary: the anchor is the
+ * whole canvas, so "don't overlap the anchor" would push the tooltip off the map
+ * entirely. On a small anchor — a bar, a badge, a row, an icon button — there IS
+ * somewhere else to go, and covering it while describing it is a real defect.
+ *
+ * So the anchor's box is avoided only when the anchor is small enough for that to
+ * be feasible: flip to just below it, else just above it. A large anchor keeps
+ * exactly the previous cursor-following behaviour.
+ */
 export declare function positionTooltip(tooltip: HTMLDivElement, anchor: Element, clientX: number, clientY: number): void;
+/**
+ * Wire the shared themed tooltip onto a plain DOM element.
+ *
+ * Hoisted out of `maplessSummary.ts`, which had the only copy — and whose comment
+ * already recorded why this exists: a native `title` is a different, browser-native
+ * tooltip, slow to appear (OS hover delay) and in an unthemed system font/colour,
+ * while every hover surface built through `createToolbarHelpers` uses this instant
+ * dark one. `summaryPanel.ts` and the hand-built expand buttons in
+ * `renderWaferMap`/`renderWaferGallery` were still on `title`.
+ *
+ * `text` may be a string, a getter (for a hint that changes with the control's own
+ * state, e.g. the findings severity chips' show/hide), or omitted to live-read the
+ * element's `aria-label` at hover time — the same thing `makeBtn` does, so a
+ * control whose label changes with its state (expand ⇄ reattach) stays correct
+ * without re-wiring.
+ *
+ * `asDataPoint` is for an element that is NOT already a control: it makes the
+ * element a tab stop, announces it as a single datum (`role="img"`), and sets
+ * `aria-label`, so the tooltip's content reaches the keyboard and a screen reader
+ * (WCAG 1.4.13 — content shown on hover must be reachable and dismissable without
+ * a pointer). Never pass it for a `<button>`: that would add a nested focus stop
+ * and overwrite the control's own accessible name.
+ */
+export declare function wireTooltip(target: HTMLElement, text?: string | (() => string), opts?: {
+    asDataPoint?: boolean;
+}): void;
 export interface ToolbarHelpers {
     makeBtn(iconKey: string, label: string, onClick: () => void): HTMLButtonElement;
     setActive(btn: HTMLButtonElement, active: boolean): void;
@@ -302,8 +553,9 @@ export interface ExpandToggleHandle {
 /**
  * Shared "click/Enter/Space toggles an expand/collapse state, Escape or an
  * outside click closes it" wiring — the small interaction pattern behind both
- * the metadata badge's own expand (metadataBadge.ts) and the gallery card
- * header's metadata reveal (renderWaferGallery.ts). `trigger` gets
+ * the shared identity header's metadata reveal (identityHeader.ts, used by
+ * renderWaferMap.ts) and the gallery card header's own reveal
+ * (renderWaferGallery.ts). `trigger` gets
  * `role="button"`/`tabindex` and the event listeners; `onChange(open)` is
  * called whenever the state actually changes (never redundantly) — the
  * caller owns all the resulting DOM (aria-expanded text, panel visibility,
@@ -327,6 +579,14 @@ export type CheckMenuRow = {
      * missing feature, and the user has no way to learn the condition.
      */
     disabledHint?: string;
+    /**
+     * Marks a row that *does* something rather than holding a state — "Clear
+     * overlays", "Reset orientation". Rendered as a plain `menuitem` with no
+     * tick: every other row here is a checkbox, and an action wearing an
+     * unchecked ✓ both looks like a toggle that is off and announces itself as
+     * one to a screen reader.
+     */
+    action?: boolean;
     onClick: (e: MouseEvent) => void;
 };
 /**
@@ -334,13 +594,27 @@ export type CheckMenuRow = {
  * Each row with an `onClick` is a toggleable item; rows with `section` are headers.
  * Stays open after each click so the user can toggle multiple items.
  */
-export declare function buildCheckMenuEl(anchorRect: DOMRect, rows: CheckMenuRow[], helpers: Pick<ToolbarHelpers, 'makeMenuRow' | 'makeMenuSection'>, ownerWindow?: Window): HTMLDivElement;
+export declare function buildCheckMenuEl(anchorRect: DOMRect, rows: CheckMenuRow[], helpers: Pick<ToolbarHelpers, 'makeMenuSection'>, ownerWindow?: Window): HTMLDivElement;
 export declare function createToolbarHelpers(tooltip: HTMLDivElement): ToolbarHelpers;
 export type OverlayMode = 'modal' | 'window';
 export interface OverlayOptions {
     /** Optional title shown in the header left. */
     title?: string;
     mode: OverlayMode;
+    /**
+     * Override the box's natural (non-maximized) size. Defaults to a 700px
+     * square, which suits a circular wafer map — the content this overlay was
+     * built for — but is actively wrong for wide content: the Insights suite
+     * lays out ~1330px wide in a normal page, so a 700px square modal makes
+     * "expand" produce something SMALLER than the view it expanded from.
+     *
+     * Also the restore target for maximize and minimize, so an overridden size
+     * survives both round trips.
+     */
+    boxSize?: {
+        width: string;
+        height: string;
+    };
     /**
      * Called when the maximized state changes — use to reparent tooltips etc. Uses
      * a CSS maximize (the box grows to fill its backdrop/the viewport), not the
@@ -412,6 +686,11 @@ export declare function openFloatingWindow(opts: Omit<OverlayOptions, 'mode'>):
 export interface ReparentModalOptions {
     ownerDocument?: Document;
     title?: string;
+    /** Natural box size — see `OverlayOptions.boxSize`. */
+    boxSize?: {
+        width: string;
+        height: string;
+    };
     /** Called after the modal has closed and every element has been restored to its original position (or appended back, if its original spot is no longer available — see the stale-reference note above). Runs once, even if nothing was actually moved (the re-entrancy guard tripped). */
     onClosed?: () => void;
 }
@@ -433,18 +712,33 @@ export declare function openReparentedModal(elements: HTMLElement[], opts?: Repa
  * hardBin/softBin restriction (which still changes the die colours, just from
  * a smaller scheme set).
  */
+/** The colour preferences the palette menu reads and writes. */
+export interface PaletteState {
+    plotMode: PlotMode;
+    binColorScheme?: string;
+    valueColorScheme?: string;
+    useDefinedBinColors?: boolean;
+}
 /**
- * Colour-scheme picker, plus the optional non-colour failure marking.
+ * Colour-scheme picker. Lists bin palettes in `hardBin`/`softBin` and value
+ * gradients everywhere else — including the stacked modes, whose maps are
+ * values (a bin's occurrence rate per position), not bin categories. The two
+ * are separate preferences, so choosing a gradient for values leaves the bin
+ * palette alone and vice versa; nothing is reset on a mode switch.
+ *
+ * Colours that arrive with the data (`BinDef.color`) are a layer over the bin
+ * palette, not a pseudo-palette: the "Use colours from bin definitions" row
+ * appears only when some definition carries a colour, and turning it off
+ * shows the palette's own colours for those bins.
  *
- * `markFail` is supplied by hosts that support it. It sits in this menu rather
- * than getting a button of its own because it answers the same question the
- * schemes do — "how is this data encoded" — and keeping it here means one
- * control rather than a new axis of settings.
+ * "Mark failing dies" used to live here too; it is in Overlays, beside the
+ * pass/fail display rows it belongs with.
  */
-export declare function makePaletteBtn(helpers: ToolbarHelpers, getPlotMode: () => PlotMode, getColorScheme: () => string, hasCustomColors: () => boolean, setColorScheme: (v: string) => void, markFail?: {
-    get: () => boolean;
-    set: (v: boolean) => void;
-}): {
+export declare function makePaletteBtn(helpers: ToolbarHelpers, getState: () => PaletteState, hasDefinedBinColors: () => boolean, apply: (partial: {
+    binColorScheme?: string;
+    valueColorScheme?: string;
+    useDefinedBinColors?: boolean;
+}) => void): {
     btn: HTMLButtonElement;
     sync: () => void;
 };
@@ -460,6 +754,49 @@ export declare function requestedPassFailDisplay(opts: {
  * test returns no entries at all — its value mode IS test pass/fail, there is
  * no alternative display to choose.
  */
+/** The overlay flags an overlays menu offers, however the host stores them. */
+export interface OverlayFlags {
+    showRingBoundaries?: boolean;
+    showQuadrantBoundaries?: boolean;
+    showDieLabels?: boolean;
+    showReticle?: boolean;
+    showXYIndicator?: boolean;
+    passFailDisplay?: 'off' | 'spec' | 'test';
+    /**
+     * Moved here from the Colour scheme menu, where it had been the one entry
+     * that was not a scheme — a marker drawn over dies sitting among mutually
+     * exclusive palettes. Overlays is where its sibling already lived: the
+     * pass/fail display rows below are the same kind of judgement about the same
+     * dies, and putting the two in different menus made neither findable from the
+     * other.
+     */
+    markFailingDies?: boolean;
+}
+/**
+ * The Overlays menu's rows — the five geometry toggles plus whatever
+ * `passFailMenuRows` offers for the active test.
+ *
+ * Built identically by `renderWaferMap` and `renderWaferGallery`, which is the
+ * problem it solves: the two lists were the same five labels in the same order
+ * with the same option keys, differing only in where the flags live
+ * (`viewOpts` vs `sharedOpts`) and how a change is applied (`applyOpts` vs
+ * `updateShared`). Adding a sixth overlay meant remembering both, and the map
+ * and the gallery quietly offering different menus is the failure that follows
+ * from forgetting.
+ *
+ * `reticleEnabled` stays a caller input: a single map knows whether ITS wafer
+ * has a reticle, and the gallery whether ANY item does — genuinely different
+ * questions with the same answer type.
+ */
+export declare function overlayMenuRows(flags: OverlayFlags, reticleEnabled: boolean, passFail: {
+    functionalActive: boolean;
+    hasLimits: boolean;
+    hasRecorded: boolean;
+    binMode: boolean;
+}, apply: (patch: OverlayFlags) => void): CheckMenuRow[];
+/** Whether any overlay is on — the Overlays button's "active" state. Shared for
+ *  the same reason as the rows: it enumerates the same five flags. */
+export declare function anyOverlayActive(flags: OverlayFlags): boolean;
 export declare function passFailMenuRows(state: {
     functionalActive: boolean;
     hasLimits: boolean;