@niivue/uikit 1.0.0-rc.2 → 1.0.0-rc.21

package/dist/button.d.ts

@@ -0,0 +1,97 @@
+import { RectData } from './rect';
+import { UIKitFontMetrics } from './text/font';
+import { RGBA } from './text/layout';
+import { UIKitTextItem } from './textOverlay';
+/** Every visual knob on a button. All lengths are in canvas pixels. */
+export interface ButtonStyle {
+    /** Face color at rest. */
+    fill: RGBA;
+    /** Face color while the pointer hovers (not pressed). */
+    hoverFill: RGBA;
+    /** Face color at full press; blended in by the press amount. */
+    pressedFill: RGBA;
+    /** Face color when the button is disabled. */
+    disabledFill: RGBA;
+    /** Border ring color. */
+    border: RGBA;
+    /** Border ring width; 0 draws no border. */
+    borderWidth: number;
+    /** Corner radius. */
+    radius: number;
+    textColor: RGBA;
+    disabledTextColor: RGBA;
+    /** Label em size. */
+    textSizePx: number;
+    /** Space between the label and the left/right edges when auto-sized. */
+    paddingX: number;
+    /** Space between the cap-height box and the top/bottom edges when auto-sized. */
+    paddingY: number;
+    /** Scale of the whole button at full press (1 disables the shrink). */
+    pressScale: number;
+    /** Time for the press amount to go from 0 to 1 on pointer down. */
+    pressMs: number;
+    /** Time for the press amount to go from 1 back to 0 on release. */
+    releaseMs: number;
+}
+export declare const DEFAULT_BUTTON_STYLE: ButtonStyle;
+export interface ButtonSpec {
+    /** Stable key: the handle for updates, pointer tracking and the click callback. */
+    id: string;
+    label: string;
+    /** Top-left corner of the resting box, in canvas pixels. */
+    x: number;
+    y: number;
+    /** Fixed box size. Omit either to size that axis to the label plus padding. */
+    width?: number;
+    height?: number;
+    /** Per-button overrides of the overlay's default style. */
+    style?: Partial<ButtonStyle>;
+    /** A disabled button draws dimmed and ignores the pointer. Default true. */
+    enabled?: boolean;
+    /** Fired on a completed click (pointer up inside the button it went down on). */
+    onClick?: (id: string) => void;
+}
+/** The button's resting box (before any press shrink), in canvas pixels. */
+export interface ButtonLayout {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** The transient state that changes how a button looks. */
+export interface ButtonVisual {
+    hover: boolean;
+    /** Press amount, 0 (at rest) to 1 (fully pressed). */
+    press: number;
+    enabled: boolean;
+}
+export declare function resolveButtonStyle(base: ButtonStyle, override?: Partial<ButtonStyle>): ButtonStyle;
+/** Linear blend of two colors, t in [0, 1]. */
+export declare function mixColor(a: RGBA, b: RGBA, t: number): RGBA;
+/** Resting box for a spec: fixed where given, otherwise fitted to the label. */
+export declare function layoutButton(spec: ButtonSpec, style: ButtonStyle, metrics: UIKitFontMetrics): ButtonLayout;
+/**
+ * Scale every length in a spec and style by `k` (used to lay out CSS-pixel
+ * specs on a high-DPR canvas). Returns new objects; the inputs are untouched.
+ */
+export declare function scaleButton(spec: ButtonSpec, style: ButtonStyle, k: number): {
+    spec: ButtonSpec;
+    style: ButtonStyle;
+};
+/**
+ * The draw data for one button in one visual state: the face rect and the
+ * centred label. A press shrinks both about the box centre by
+ * `1 - (1 - pressScale) * press` and blends the face toward `pressedFill`.
+ */
+export declare function buildButton(spec: ButtonSpec, style: ButtonStyle, metrics: UIKitFontMetrics, layout: ButtonLayout, visual: ButtonVisual): {
+    rect: RectData;
+    text: UIKitTextItem;
+};
+/**
+ * Move a press amount toward its target at a constant rate so the full travel
+ * takes `durationMs`. A non-positive or non-finite duration (or a non-finite
+ * clock) snaps to the target, so the animation always ends.
+ */
+export declare function advancePress(current: number, target: number, dtMs: number, durationMs: number): number;
+/** True when canvas point (px, py) lies inside the resting box. */
+export declare function buttonContains(layout: ButtonLayout, px: number, py: number): boolean;

package/dist/buttonOverlay.d.ts

@@ -0,0 +1,121 @@
+import { UIKitOverlayFrame, UIKitOverlayRenderer } from '@niivue/niivue';
+import { ButtonLayout, ButtonSpec, ButtonStyle } from './button';
+import { UIKitHost, UIKitInteractive, UIKitKeyEvent, UIKitRedrawSource } from './controls';
+import { UIKitFont } from './text/font';
+/** What `attach` needs from a host: NiiVue satisfies it as-is. */
+export type UIKitButtonHost = UIKitHost;
+export interface UIKitButtonOverlayOptions {
+    /**
+     * Called whenever the overlay needs another frame (a hover/press change, or
+     * each step of a running press animation). `attach` fills this in with the
+     * host's `drawScene` when it is not set.
+     */
+    requestRedraw?: () => void;
+    /** Default style for every button; a spec's `style` overrides per key. */
+    style?: Partial<ButtonStyle>;
+    /**
+     * Interpret spec positions, sizes and style lengths as CSS pixels and scale
+     * them by the frame's device pixel ratio, instead of canvas pixels. Pointer
+     * coordinates always arrive in canvas pixels (the hook's convention).
+     */
+    cssUnits?: boolean;
+    /** Clock for the press animation (ms). Default `performance.now`. */
+    now?: () => number;
+}
+export declare class UIKitButtonOverlay implements UIKitOverlayRenderer, UIKitInteractive {
+    readonly hoverCursor = "pointer";
+    private readonly font;
+    private readonly rects;
+    private readonly labels;
+    private readonly entries;
+    private baseStyle;
+    private readonly cssUnits;
+    private readonly now;
+    private requestRedraw;
+    /** Scale from spec units to canvas pixels (the frame dpr when cssUnits). */
+    private scale;
+    private geometryDirty;
+    private lastTick;
+    private pressedId;
+    private hoverId;
+    /** The button that takes Enter/Space, set by the last press on it. */
+    private focusedId;
+    constructor(font: UIKitFont, options?: UIKitButtonOverlayOptions);
+    /** Replace the default style for every button (per-spec overrides still win). */
+    setDefaultStyle(style: Partial<ButtonStyle>): void;
+    /** Add a button, or replace the one with the same id (keeping its press state). */
+    addButton(spec: ButtonSpec): void;
+    /** Replace the whole button set. */
+    setButtons(specs: readonly ButtonSpec[]): void;
+    removeButton(id: string): void;
+    /** Patch one button's spec (label, position, style, enabled, callback). */
+    updateButton(id: string, patch: Partial<Omit<ButtonSpec, 'id'>>): void;
+    setEnabled(id: string, enabled: boolean): void;
+    /** The ids of all buttons, in draw order. */
+    get ids(): string[];
+    /**
+     * The resting box of a button in spec units (canvas pixels, or CSS pixels
+     * with `cssUnits`), or null for an unknown id. Handy for placing the next
+     * button after an auto-sized one.
+     */
+    getLayout(id: string): ButtonLayout | null;
+    /** True while the pointer is over an enabled button. */
+    get hovering(): boolean;
+    /**
+     * Click a button from code (a keyboard shortcut, say): plays the press and
+     * release animation and fires its callback as a pointer click would.
+     */
+    click(id: string): void;
+    /** True when canvas point (x, y) is over an enabled button. */
+    hitTest(x: number, y: number): boolean;
+    /**
+     * Pointer down at canvas pixel (x, y). Returns true when a button took it
+     * (the host should then not treat it as a scene interaction). The button
+     * also takes keyboard focus: Enter or Space clicks it until focus moves.
+     */
+    pointerDown(x: number, y: number): boolean;
+    /**
+     * Pointer move to canvas pixel (x, y); pass coordinates outside the canvas
+     * (or a negative pair) when the pointer leaves. Updates hover, and while a
+     * press is held, releases the face when the pointer strays off the button and
+     * re-presses when it comes back. Returns true while a press is held.
+     */
+    pointerMove(x: number, y: number): boolean;
+    /**
+     * Pointer up at canvas pixel (x, y). Fires the click when it lands inside the
+     * button the pointer went down on. Returns true when a press was being held.
+     */
+    pointerUp(x: number, y: number): boolean;
+    /** Abandon a held press (pointer cancelled or captured away) without a click. */
+    pointerCancel(): void;
+    /** Enter or Space clicks the last-pressed button. */
+    keyDown(e: UIKitKeyEvent): boolean;
+    blur(): void;
+    bindLayer(layer: UIKitRedrawSource): void;
+    /**
+     * Wire the host canvas's pointer events to this overlay alone and return a
+     * function that unwires them: a one-widget `UIKitControls` layer. To combine
+     * buttons with other widgets, add this overlay to a shared layer instead.
+     */
+    attach(host: UIKitButtonHost): () => void;
+    /** Current press amount of a button (0 at rest, 1 fully pressed). */
+    pressOf(id: string): number;
+    /**
+     * Step the press animation as a frame would, without drawing. Exposed for
+     * headless tests of the animation; a host never needs it.
+     * @internal
+     */
+    tickForTest(): boolean;
+    /** Advance every running press animation by the wall clock. */
+    private tick;
+    drawOverlay(frame: UIKitOverlayFrame): void;
+    /** Release GPU resources on both backends. */
+    destroy(): void;
+    private invalidate;
+    private startAnimation;
+    private scaled;
+    private layoutOf;
+    /** The topmost (last added) enabled button under a canvas point. */
+    private hitEntry;
+    private rebuild;
+}

package/dist/colorControl.d.ts

@@ -0,0 +1,130 @@
+import { RectData } from './rect';
+import { UIKitBox } from './scroll';
+import { SliderStyle } from './slider';
+import { UIKitFontMetrics } from './text/font';
+import { RGBA } from './text/layout';
+import { UIKitTextItem } from './textOverlay';
+/** Every visual knob on a color control. All lengths are in canvas pixels. */
+export interface ColorControlStyle {
+    textColor: RGBA;
+    disabledTextColor: RGBA;
+    /** Label and channel letter em size. */
+    textSizePx: number;
+    /** Halo outline width around the label and letters (they sit on the scene); 0 draws none. */
+    textOutlineWidth: number;
+    /** Halo color; null picks black or white against `textColor`. */
+    textOutlineColor: RGBA | null;
+    /** Space between the label row and the block below it. */
+    labelGap: number;
+    /** Side of the square preview swatch. */
+    previewSize: number;
+    previewRadius: number;
+    previewBorder: RGBA;
+    previewBorderWidth: number;
+    /** Drawn under the preview so a translucent color shows its alpha. */
+    previewBackdrop: RGBA;
+    /** Space between the preview and the sliders, and between the letters and tracks. */
+    gap: number;
+    /** Vertical space between channel sliders. */
+    channelGap: number;
+    /** Style overrides for the channel sliders. */
+    slider: Partial<SliderStyle>;
+    /** Side of each palette swatch. */
+    swatchSize: number;
+    swatchGap: number;
+    swatchRadius: number;
+    swatchBorder: RGBA;
+    swatchBorderWidth: number;
+    /** Ring around the swatch matching the current color. */
+    selectedRing: RGBA;
+    selectedRingWidth: number;
+    /** Ring around the hovered swatch. */
+    hoverRing: RGBA;
+    /** Space between the sliders block and the palette row. */
+    paletteGap: number;
+}
+export declare const DEFAULT_COLOR_CONTROL_STYLE: ColorControlStyle;
+/** A named palette choice. */
+export interface ColorSwatch {
+    name: string;
+    color: RGBA;
+}
+export interface ColorControlSpec {
+    /** Stable key: the handle for updates, pointer tracking and the callbacks. */
+    id: string;
+    /** Optional label, drawn above the control at the left. */
+    label?: string;
+    /** Top-left corner of the whole control, in canvas pixels. */
+    x: number;
+    y: number;
+    /** Width of the whole control. Default 220. */
+    width?: number;
+    /** Initial color, channels 0 to 1. */
+    value: RGBA;
+    /** Show an alpha slider. Default false (alpha stays as given). */
+    alpha?: boolean;
+    /** Named colors drawn as a row of swatches under the sliders. */
+    palette?: readonly ColorSwatch[];
+    /** A disabled control draws dimmed and ignores input. Default true. */
+    enabled?: boolean;
+    /** Per-control overrides of the overlay's default style. */
+    style?: Partial<ColorControlStyle>;
+    /** Fired for every change: each slider move or key press, each swatch press. */
+    onInput?: (color: RGBA, id: string) => void;
+    /** Fired once per committed change: slider release, key press, swatch press. */
+    onChange?: (color: RGBA, id: string) => void;
+}
+export type ColorChannel = 'r' | 'g' | 'b' | 'a';
+export declare const COLOR_CHANNELS: readonly ColorChannel[];
+/** The control's boxes in canvas pixels. */
+export interface ColorControlLayout {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Baseline of the label, or null without one. */
+    labelBaseline: number | null;
+    preview: UIKitBox;
+    /** One row per channel: the letter's position and the slider's box. */
+    channels: {
+        channel: ColorChannel;
+        letterX: number;
+        baseline: number;
+        slider: UIKitBox;
+    }[];
+    /** Palette swatches in spec order. */
+    swatches: UIKitBox[];
+}
+/** The transient state that changes how a color control looks. */
+export interface ColorControlVisual {
+    value: RGBA;
+    /** Index of the hovered swatch, or -1. */
+    hoverSwatch: number;
+    enabled: boolean;
+}
+export declare function resolveColorControlStyle(base: ColorControlStyle, override?: Partial<ColorControlStyle>): ColorControlStyle;
+/** True when two colors agree in every channel within a rounding tolerance. */
+export declare function colorsEqual(a: RGBA, b: RGBA, tolerance?: number): boolean;
+/** A copy of `color` with one channel replaced (clamped to 0..1). */
+export declare function withChannel(color: RGBA, channel: ColorChannel, v: number): RGBA;
+/** The palette index whose color equals `color`, or -1. */
+export declare function selectedSwatch(palette: readonly ColorSwatch[] | undefined, color: RGBA): number;
+export declare function layoutColorControl(spec: ColorControlSpec, style: ColorControlStyle, metrics: UIKitFontMetrics): ColorControlLayout;
+/** Scale every length in a spec and style by `k` (CSS pixels to canvas pixels). */
+export declare function scaleColorControl(spec: ColorControlSpec, style: ColorControlStyle, k: number): {
+    spec: ColorControlSpec;
+    style: ColorControlStyle;
+};
+/** The index of the swatch under canvas point (px, py), or -1. */
+export declare function colorSwatchAt(layout: ColorControlLayout, px: number, py: number): number;
+/** True when canvas point (px, py) lies inside the whole control. */
+export declare function colorControlContains(layout: ColorControlLayout, px: number, py: number): boolean;
+/**
+ * The draw data for a color control: the label, the preview over its
+ * backdrop, the channel letters and the palette swatches with the selected
+ * and hovered rings. The sliders are a slider overlay's.
+ */
+export declare function buildColorControl(spec: ColorControlSpec, style: ColorControlStyle, layout: ColorControlLayout, visual: ColorControlVisual): {
+    rects: RectData[];
+    text: UIKitTextItem[];
+};

package/dist/colorControlOverlay.d.ts

@@ -0,0 +1,72 @@
+import { UIKitOverlayFrame, UIKitOverlayRenderer } from '@niivue/niivue';
+import { ColorControlLayout, ColorControlSpec, ColorControlStyle } from './colorControl';
+import { UIKitInteractive, UIKitKeyEvent, UIKitRedrawSource } from './controls';
+import { UIKitFont } from './text/font';
+import { RGBA } from './text/layout';
+export interface UIKitColorControlOverlayOptions {
+    /** Called whenever the overlay needs another frame. A control layer fills it in. */
+    requestRedraw?: () => void;
+    /** Default style for every control; a spec's `style` overrides per key. */
+    style?: Partial<ColorControlStyle>;
+    /**
+     * Interpret spec positions and style lengths as CSS pixels and scale them by
+     * the frame's device pixel ratio, instead of canvas pixels.
+     */
+    cssUnits?: boolean;
+}
+export declare class UIKitColorControlOverlay implements UIKitOverlayRenderer, UIKitInteractive {
+    readonly hoverCursor = "pointer";
+    private readonly font;
+    private readonly rects;
+    private readonly labels;
+    /** The channel sliders of every control, placed in spec units. */
+    private readonly sliders;
+    private readonly entries;
+    private baseStyle;
+    private readonly cssUnits;
+    private requestRedraw;
+    private scale;
+    private geometryDirty;
+    /** The control whose slider holds the pointer. */
+    private draggingId;
+    private focusedId;
+    constructor(font: UIKitFont, options?: UIKitColorControlOverlayOptions);
+    /** Replace the default style for every control (per-spec overrides still win). */
+    setDefaultStyle(style: Partial<ColorControlStyle>): void;
+    /** Add a control, or replace the one with the same id (keeping its color). */
+    addColorControl(spec: ColorControlSpec): void;
+    setColorControls(specs: readonly ColorControlSpec[]): void;
+    removeColorControl(id: string): void;
+    /** Patch one control's spec (label, position, palette, callbacks, ...). */
+    updateColorControl(id: string, patch: Partial<Omit<ColorControlSpec, 'id'>>): void;
+    setEnabled(id: string, enabled: boolean): void;
+    /** Set a control's color without firing its callbacks. */
+    setValue(id: string, color: RGBA): void;
+    getValue(id: string): RGBA | undefined;
+    get ids(): string[];
+    /** A control's boxes in spec units, or null for an unknown id. */
+    getLayout(id: string): ColorControlLayout | null;
+    /** The control whose slider has keyboard focus, if any. */
+    get focusedControl(): string | null;
+    hitTest(x: number, y: number): boolean;
+    pointerDown(x: number, y: number): boolean;
+    pointerMove(x: number, y: number): boolean;
+    pointerUp(x: number, y: number): boolean;
+    pointerCancel(): void;
+    /** Arrow keys, Home, End and Page keys move the focused channel slider. */
+    keyDown(e: UIKitKeyEvent): boolean;
+    blur(): void;
+    bindLayer(layer: UIKitRedrawSource): void;
+    drawOverlay(frame: UIKitOverlayFrame): void;
+    /** Release GPU resources on both backends. */
+    destroy(): void;
+    private invalidate;
+    private rebuild;
+    private getValueOf;
+    private layoutOf;
+    private swatchHit;
+    /** Create or move the channel sliders of a control, in spec units. */
+    private placeSliders;
+    /** Push a control's color into its sliders without firing callbacks. */
+    private syncSliders;
+}

package/dist/controls.d.ts

@@ -0,0 +1,151 @@
+import { UIKitOverlayFrame, UIKitOverlayRenderer } from '@niivue/niivue';
+/** What `attach` needs from a host: a NiiVue controller satisfies it as-is. */
+export interface UIKitHost {
+    canvas: HTMLCanvasElement | null;
+    /** Client (CSS) coordinates to canvas backing-store pixels, or null if outside. */
+    clientToCanvas(clientX: number, clientY: number): [number, number] | null;
+    /** Schedule a redraw of the scene (and so of the overlays). */
+    drawScene(): void;
+}
+/** The parts of a keyboard event a widget reacts to. */
+export interface UIKitKeyEvent {
+    /** The DOM `KeyboardEvent.key` value ('ArrowLeft', 'Enter', ' ', 'a', ...). */
+    key: string;
+    shiftKey: boolean;
+    ctrlKey: boolean;
+    altKey: boolean;
+    metaKey: boolean;
+}
+/**
+ * Something the control layer can bind a widget to: redraw requests, and a
+ * way to take the keyboard back when the widget opens or focuses from code.
+ */
+export interface UIKitRedrawSource {
+    requestRedraw(): void;
+    /**
+     * Make `child` the keyboard focus and let the layer route keys again, as a
+     * canvas press would. Widgets call it from their own `open` and `focus`
+     * so a dialog opened from a page button gets its keys at once.
+     */
+    focus?(child: UIKitInteractive): void;
+}
+/**
+ * An interactive overlay: drawn through the overlay hook and fed pointer and
+ * keyboard input in canvas pixels. Every pointer method returns whether the
+ * widget consumed the event (the host must then not treat it as a scene
+ * interaction).
+ */
+export interface UIKitInteractive extends UIKitOverlayRenderer {
+    /** True when (x, y) is over an interactive part (hover routing, cursor). */
+    hitTest(x: number, y: number): boolean;
+    pointerDown(x: number, y: number): boolean;
+    /** Pass a point off the canvas (e.g. -1, -1) when the pointer leaves. */
+    pointerMove(x: number, y: number): boolean;
+    pointerUp(x: number, y: number): boolean;
+    /** Abandon a held interaction without completing it. */
+    pointerCancel(): void;
+    /** Handle a key while focused or modal. Return true to consume it. */
+    keyDown?(e: UIKitKeyEvent): boolean;
+    /**
+     * Whether a key this widget took should also submit the dialog it sits
+     * in, as Enter in a form's text field submits the form. A text area's
+     * Enter (a new line) and a select's (opening its list) do not.
+     */
+    submitsForm?(e: UIKitKeyEvent): boolean;
+    /**
+     * Handle a wheel turn over (x, y), deltas in pixels (positive is down and
+     * right). Sent to the modal widget first, else the widget under the point.
+     * Return true to consume it (the page then does not scroll).
+     */
+    wheel?(x: number, y: number, deltaX: number, deltaY: number): boolean;
+    /** Drop keyboard focus (another widget took it, or the scene was clicked). */
+    blur?(): void;
+    /** True while this widget must see every event first (an open popup). */
+    isModal?(): boolean;
+    /** Close any popup without choosing (the pointer or focus went elsewhere in the page). */
+    dismiss?(): void;
+    /** CSS cursor to show while this widget is hovered or captured. */
+    readonly hoverCursor?: string;
+    /** Draw anything that must sit above every other widget (a popup). */
+    drawPopup?(frame: UIKitOverlayFrame): void;
+    /**
+     * Called when added to a control layer: a widget without its own redraw
+     * requester should take the layer's, and may stop drawing its popup from
+     * `drawOverlay` because the layer calls `drawPopup` after all widgets.
+     */
+    bindLayer?(layer: UIKitRedrawSource): void;
+    destroy?(): void;
+}
+export interface UIKitControlsOptions {
+    /** Called whenever a widget needs a frame. `attach` defaults it to `drawScene`. */
+    requestRedraw?: () => void;
+}
+export declare class UIKitControls implements UIKitOverlayRenderer, UIKitRedrawSource {
+    private readonly children;
+    private redraw;
+    private captured;
+    private focused;
+    private hovered;
+    private active;
+    constructor(options?: UIKitControlsOptions);
+    /** Add a widget on top of the existing ones. Returns the layer for chaining. */
+    add(child: UIKitInteractive): this;
+    remove(child: UIKitInteractive): void;
+    /** The widgets in draw order (bottom first). */
+    get widgets(): readonly UIKitInteractive[];
+    /** The widget holding keyboard focus, if any. */
+    get focusedWidget(): UIKitInteractive | null;
+    /** The widget that currently owns the pointer (a held press or drag). */
+    get capturedWidget(): UIKitInteractive | null;
+    /** The widget that must see every event first, if any. */
+    get modalWidget(): UIKitInteractive | null;
+    /** CSS cursor for the current hover or capture, or null for the default. */
+    get hoverCursor(): string | null;
+    requestRedraw(): void;
+    /**
+     * Give keyboard focus to a widget (blurring the previous one). With a
+     * widget this also ends a `deactivate`: the layer routes keys again.
+     */
+    focus(child: UIKitInteractive | null): void;
+    blur(): void;
+    /**
+     * Drop every live interaction: cancel a held press, dismiss open popups and
+     * blur the focus. `attach` calls this when the user presses outside the
+     * canvas, moves focus to another element or leaves the window, so the
+     * layer stops consuming keys the page should get.
+     */
+    deactivate(): void;
+    /** Pointer down at canvas pixel (x, y): true when a widget took it. */
+    pointerDown(x: number, y: number): boolean;
+    /**
+     * Pointer move to canvas pixel (x, y), or off-canvas coordinates when the
+     * pointer leaves. True while a widget owns the pointer or a modal is up.
+     */
+    pointerMove(x: number, y: number): boolean;
+    /** Pointer up at canvas pixel (x, y): true when a widget owned the pointer. */
+    pointerUp(x: number, y: number): boolean;
+    pointerCancel(): void;
+    /**
+     * Route a key to the modal widget, else the focused one. True if consumed.
+     * The layer owns keys until `deactivate`, and again from the next canvas
+     * press or `focus` call; an open dialog does not keep them once the user
+     * has moved to the rest of the page.
+     */
+    keyDown(e: UIKitKeyEvent): boolean;
+    /**
+     * Route a wheel turn to the modal widget, else to the topmost widget under
+     * (x, y) that handles wheels. True if consumed.
+     */
+    wheel(x: number, y: number, deltaX: number, deltaY: number): boolean;
+    /**
+     * Wire the host canvas's pointer and wheel events (and the window's keydown)
+     * to this layer and return a function that unwires them. Events a widget consumes are
+     * stopped before the host's own handlers run; the cursor follows the widgets.
+     */
+    attach(host: UIKitHost): () => void;
+    /** Draw every widget in order, then every popup on top. */
+    drawOverlay(frame: UIKitOverlayFrame): void;
+    /** Release every widget's GPU resources. */
+    destroy(): void;
+    private topDown;
+}