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

package/dist/pointLabel.d.ts

@@ -0,0 +1,68 @@
+import { LineData } from './line';
+import { RGBA, Vec2 } from './ruler';
+import { UIKitFontMetrics } from './text/font';
+import { UIKitTextItem } from './textOverlay';
+export interface PointLabelBounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface PointLabelSpec {
+    /** The labelled point in screen pixels. */
+    target: Vec2;
+    text: string;
+    /**
+     * Where the leader ends and the text starts, in screen pixels. Omit to place
+     * it `leaderLength` from the target, pointing away from the centre of
+     * `bounds` (or up and to the right without bounds).
+     */
+    anchor?: Vec2;
+    /**
+     * The drawable area. Used to choose the automatic anchor direction and to
+     * keep the text inside the frame: the text flips to the other side of the
+     * anchor when it would run off an edge.
+     */
+    bounds?: PointLabelBounds;
+    /**
+     * The eight projected corners of a box to outline around the target (a
+     * volume brick, say), in screen pixels. Corner `c` sits at the box's
+     * minimum on each axis whose bit of `c` is clear and at its maximum where
+     * it is set, so the twelve edges join corners whose indices differ in one
+     * bit. Omit for no box.
+     */
+    box?: readonly Vec2[];
+    /** Colour of the box edges. Defaults to `lineColor`. */
+    boxColor?: RGBA;
+    /** Thickness of the box edges in pixels. Defaults to `thickness`. */
+    boxThickness?: number;
+    /** Leader length for the automatic anchor, in pixels. Default 110. */
+    leaderLength?: number;
+    /** Text height in pixels. Default 28. */
+    sizePx?: number;
+    lineColor?: RGBA;
+    textColor?: RGBA;
+    /** Line thickness in pixels. Default 3. */
+    thickness?: number;
+    /** Half-size of the diamond marking the target, in pixels. Default 6. */
+    markerSize?: number;
+    /** Text outline width in pixels, 0 for none. Default 2. */
+    textOutlineWidthPx?: number;
+    /**
+     * Multiplies every pixel size above (given or default), so one spec reads
+     * the same on a 1x and a 2x display. The overlay passes the frame's device
+     * pixel ratio. Default 1.
+     */
+    scale?: number;
+}
+export interface PointLabelGeometry {
+    lines: LineData[];
+    text: UIKitTextItem[];
+    /** The resolved anchor (useful for tests and for chaining labels). */
+    anchor: Vec2;
+}
+/**
+ * Build the line + text draw data for a point label. Pure geometry; the font
+ * metrics are only used to measure the text so it can be kept in frame.
+ */
+export declare function buildPointLabel(metrics: UIKitFontMetrics, spec: PointLabelSpec): PointLabelGeometry;

package/dist/pointLabelOverlay.d.ts

@@ -0,0 +1,39 @@
+import { UIKitOverlayFrame, UIKitOverlayRenderer } from '@niivue/niivue';
+import { PointLabelSpec } from './pointLabel';
+import { UIKitFont } from './text/font';
+export type MMPoint = readonly [number, number, number];
+/** Maps a world-mm point to canvas backing-store pixels, or null if off screen. */
+export type MMProjector = (mm: MMPoint) => [number, number] | null;
+/**
+ * A label pinned to a world-mm point; the rest styles the callout. Pixel
+ * sizes are in CSS pixels: the overlay scales them by the frame's device
+ * pixel ratio (times any `scale` given here).
+ */
+export type PointLabelPlacement = Omit<PointLabelSpec, 'target' | 'bounds' | 'box'> & {
+    mm: MMPoint;
+    /**
+     * The eight world-mm corners of a box to outline around the point (the
+     * volume brick holding it, say), in the corner order `PointLabelSpec.box`
+     * describes. The overlay projects them each frame.
+     */
+    boxMM?: readonly MMPoint[];
+};
+export declare class UIKitPointLabelOverlay implements UIKitOverlayRenderer {
+    private project;
+    private readonly lines;
+    private readonly labels;
+    private readonly font;
+    private placements;
+    constructor(font: UIKitFont, project: MMProjector, labels?: PointLabelPlacement[]);
+    /** Replace the labels. Trigger a redraw via the host. */
+    setLabels(labels: PointLabelPlacement[]): void;
+    /** Swap the projection (after a view change, say). */
+    setProjector(project: MMProjector): void;
+    /** Remove every label so nothing draws. */
+    clear(): void;
+    drawOverlay(frame: UIKitOverlayFrame): void;
+    /** The box's corners on the canvas, or undefined when any is off screen. */
+    private projectBox;
+    /** Release GPU resources on both backends. */
+    destroy(): void;
+}

package/dist/rect.d.ts

@@ -0,0 +1,27 @@
+export type RectData = {
+    data: Float32Array;
+};
+export declare const FLOATS_PER_RECT = 16;
+export interface RectSpec {
+    /** Top-left corner in canvas pixels. */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** Corner radius in pixels; clamped to half the shorter side. Default 0. */
+    radius?: number;
+    /** Border ring width in pixels, drawn inside the rect edge. Default 0. */
+    borderWidth?: number;
+    /** Interior color. Default an opaque mid grey. */
+    fill?: readonly number[];
+    /** Border ring color. Default the fill color (an invisible border). */
+    border?: readonly number[];
+}
+export declare function buildRect(spec: RectSpec): RectData;
+/** True when canvas point (px, py) lies inside the rect's axis-aligned box. */
+export declare function rectContains(rect: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}, px: number, py: number): boolean;

package/dist/rectOverlay.d.ts

@@ -0,0 +1,13 @@
+import { UIKitOverlayFrame, UIKitOverlayRenderer } from '@niivue/niivue';
+import { RectData } from './rect';
+export declare class UIKitRectOverlay implements UIKitOverlayRenderer {
+    private rects;
+    private readonly gl;
+    private readonly wgpu;
+    constructor(rects?: RectData[]);
+    /** Replace the rects drawn each frame. Trigger a redraw via the host. */
+    setRects(rects: RectData[]): void;
+    drawOverlay(frame: UIKitOverlayFrame): void;
+    /** Release GPU resources on both backends. */
+    destroy(): void;
+}

package/dist/render/glRectRenderer.d.ts

@@ -0,0 +1,13 @@
+import { RectData } from '../rect';
+export declare class GlRectRenderer {
+    private gl;
+    private program;
+    private vao;
+    private buffer;
+    private uCanvasSize;
+    private scratch;
+    private ensure;
+    /** Draw `rects` in screen-pixel space over a `width` x `height` bounds rect. */
+    draw(gl: WebGL2RenderingContext, rects: RectData[], width: number, height: number): void;
+    destroy(): void;
+}

package/dist/render/shaders.d.ts

@@ -4,3 +4,6 @@ export declare const WGSL_LINE = "\nstruct LineUniforms {\n    canvasSize: vec2f
 export declare const GL_TEXT_VERT = "#version 300 es\nprecision highp float;\nuniform vec2 canvasSize;\nin vec2 pos;\nin vec2 uv;\nin vec4 color;\nout vec2 vUv;\nout vec4 vColor;\n\nvoid main() {\n  vec2 ndc = (pos / canvasSize) * 2.0 - 1.0;\n  gl_Position = vec4(ndc.x, -ndc.y, 0.0, 1.0);\n  vUv = uv;\n  vColor = color;\n}\n";
 export declare const GL_TEXT_FRAG = "#version 300 es\nprecision highp float;\nuniform highp sampler2D fontTexture;\nuniform float screenPxRange;\nin vec2 vUv;\nin vec4 vColor;\nout vec4 fragColor;\n\nfloat median(float r, float g, float b) {\n  return max(min(r, g), min(max(r, g), b));\n}\n\nvoid main() {\n  vec3 msd = texture(fontTexture, vUv).rgb;\n  float sd = median(msd.r, msd.g, msd.b);\n  float opacity = clamp(screenPxRange * (sd - 0.5) + 0.5, 0.0, 1.0);\n  if (opacity <= 0.0) discard;\n  fragColor = vec4(vColor.rgb, vColor.a * opacity);\n}\n";
 export declare const WGSL_TEXT = "\nstruct TextUniforms {\n    canvasSize: vec2f,\n    screenPxRange: f32,\n    _pad: f32,\n};\n\n@group(0) @binding(0) var<uniform> u: TextUniforms;\n@group(0) @binding(1) var fontTex: texture_2d<f32>;\n@group(0) @binding(2) var fontSampler: sampler;\n\nstruct VertexOutput {\n    @builtin(position) position: vec4f,\n    @location(0) uv: vec2f,\n    @location(1) color: vec4f,\n};\n\n@vertex\nfn vertex_main(\n    @location(0) pos: vec2f,\n    @location(1) uv: vec2f,\n    @location(2) color: vec4f\n) -> VertexOutput {\n    var out: VertexOutput;\n    let ndc = (pos / u.canvasSize) * 2.0 - 1.0;\n    out.position = vec4f(ndc.x, -ndc.y, 0.0, 1.0);\n    out.uv = uv;\n    out.color = color;\n    return out;\n}\n\nfn median(r: f32, g: f32, b: f32) -> f32 {\n    return max(min(r, g), min(max(r, g), b));\n}\n\n@fragment\nfn fragment_main(in: VertexOutput) -> @location(0) vec4f {\n    let msd = textureSample(fontTex, fontSampler, in.uv).rgb;\n    let sd = median(msd.r, msd.g, msd.b);\n    let opacity = clamp(u.screenPxRange * (sd - 0.5) + 0.5, 0.0, 1.0);\n    return vec4f(in.color.rgb, in.color.a * opacity);\n}\n";
+export declare const GL_RECT_VERT = "#version 300 es\nprecision highp float;\nuniform vec2 canvasSize;\nin vec2 rectPos;\nin vec2 rectSize;\nin vec2 rectShape; // (cornerRadius, borderWidth)\nin vec4 rectFill;\nin vec4 rectBorder;\nout vec2 vLocal;\nout vec2 vHalfSize;\nout vec2 vShape;\nout vec4 vFill;\nout vec4 vBorder;\n\nvoid main() {\n  int vIdx = gl_VertexID;\n  // Corner order (0,0) (0,1) (1,0) (1,1): the strip's first triangle winds\n  // counter-clockwise in clip space like the line and text quads, so the quad\n  // survives when the host leaves back-face culling enabled.\n  vec2 corner = vec2(float(vIdx >> 1), float(vIdx & 1));\n  vec2 halfSize = rectSize * 0.5;\n  vec2 centre = rectPos + halfSize;\n  vec2 grown = halfSize + 1.0;\n  vec2 local = (corner * 2.0 - 1.0) * grown;\n  vec2 pixelPos = centre + local;\n  vec2 ndc = (pixelPos / canvasSize) * 2.0 - 1.0;\n  gl_Position = vec4(ndc.x, -ndc.y, 0.0, 1.0);\n  vLocal = local;\n  vHalfSize = halfSize;\n  vShape = rectShape;\n  vFill = rectFill;\n  vBorder = rectBorder;\n}\n";
+export declare const GL_RECT_FRAG = "#version 300 es\nprecision highp float;\nin vec2 vLocal;\nin vec2 vHalfSize;\nin vec2 vShape;\nin vec4 vFill;\nin vec4 vBorder;\nout vec4 fragColor;\n\nfloat sdRoundBox(vec2 p, vec2 halfSize, float r) {\n  vec2 q = abs(p) - halfSize + r;\n  return min(max(q.x, q.y), 0.0) + length(max(q, 0.0)) - r;\n}\n\nvoid main() {\n  float d = sdRoundBox(vLocal, vHalfSize, vShape.x);\n  float coverage = 1.0 - smoothstep(-0.5, 0.5, d);\n  // The border ring is the band within borderWidth of the outer edge.\n  float ring = vShape.y > 0.0 ? smoothstep(-0.5, 0.5, d + vShape.y) : 0.0;\n  vec4 color = mix(vFill, vBorder, ring);\n  float alpha = color.a * coverage;\n  if (alpha <= 0.0) discard;\n  fragColor = vec4(color.rgb, alpha);\n}\n";
+export declare const WGSL_RECT = "\nstruct RectUniforms {\n    canvasSize: vec2f,\n};\n\nstruct Rect {\n    pos: vec2f,\n    size: vec2f,\n    radius: f32,\n    border: f32,\n    _pad0: f32,\n    _pad1: f32,\n    fill: vec4f,\n    borderColor: vec4f,\n};\n\n@group(0) @binding(0) var<uniform> u: RectUniforms;\n@group(0) @binding(1) var<storage, read> rects: array<Rect>;\n\nstruct VertexOutput {\n    @builtin(position) position: vec4f,\n    @location(0) local: vec2f,\n    @location(1) halfSize: vec2f,\n    @location(2) shape: vec2f,\n    @location(3) fill: vec4f,\n    @location(4) borderColor: vec4f,\n};\n\n@vertex\nfn vertex_main(\n    @builtin(vertex_index) vIdx: u32,\n    @builtin(instance_index) iIdx: u32\n) -> VertexOutput {\n    let rect = rects[iIdx];\n    let corner = vec2f(f32(vIdx >> 1u), f32(vIdx & 1u));\n    let halfSize = rect.size * 0.5;\n    let centre = rect.pos + halfSize;\n    let grown = halfSize + 1.0;\n    let local = (corner * 2.0 - 1.0) * grown;\n    let pixelPos = centre + local;\n    let ndc = (pixelPos / u.canvasSize) * 2.0 - 1.0;\n    var out: VertexOutput;\n    out.position = vec4f(ndc.x, -ndc.y, 0.0, 1.0);\n    out.local = local;\n    out.halfSize = halfSize;\n    out.shape = vec2f(rect.radius, rect.border);\n    out.fill = rect.fill;\n    out.borderColor = rect.borderColor;\n    return out;\n}\n\nfn sdRoundBox(p: vec2f, halfSize: vec2f, r: f32) -> f32 {\n    let q = abs(p) - halfSize + r;\n    return min(max(q.x, q.y), 0.0) + length(max(q, vec2f(0.0))) - r;\n}\n\n@fragment\nfn fragment_main(in: VertexOutput) -> @location(0) vec4f {\n    let d = sdRoundBox(in.local, in.halfSize, in.shape.x);\n    let coverage = 1.0 - smoothstep(-0.5, 0.5, d);\n    var ring = 0.0;\n    if (in.shape.y > 0.0) {\n        ring = smoothstep(-0.5, 0.5, d + in.shape.y);\n    }\n    let color = mix(in.fill, in.borderColor, ring);\n    return vec4f(color.rgb, color.a * coverage);\n}\n";

package/dist/render/wgpuRectRenderer.d.ts

@@ -0,0 +1,18 @@
+import { RectData } from '../rect';
+export declare class WgpuRectRenderer {
+    private device;
+    private pipeline;
+    private bindLayout;
+    private paramsBuffer;
+    private storageBuffer;
+    private bindGroup;
+    private capacity;
+    private key;
+    private scratch;
+    private readonly params;
+    private ensurePipeline;
+    private ensureCapacity;
+    /** Append `rects` (screen-pixel space) to the open pass over a bounds rect. */
+    draw(device: GPUDevice, pass: GPURenderPassEncoder, colorFormat: GPUTextureFormat, sampleCount: number, depthFormat: GPUTextureFormat | undefined, rects: RectData[], width: number, height: number): void;
+    destroy(): void;
+}

package/dist/scroll.d.ts

@@ -0,0 +1,70 @@
+import { LineData } from './line';
+import { RGBA } from './text/layout';
+/** An axis-aligned box in canvas pixels. */
+export interface UIKitBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** The run of rows a viewport shows, by index. */
+export interface ScrollRange {
+    /** Index of the first visible row. */
+    first: number;
+    /** Index after the last visible row. */
+    end: number;
+}
+/** A scroll range plus what `scrollWindow` learned while fitting it. */
+export interface ScrollWindow extends ScrollRange {
+    /** The largest `first` at which the tail of the list still fills the viewport. */
+    maxFirst: number;
+    /** Total height of the visible rows (at most the viewport height). */
+    usedHeight: number;
+}
+/**
+ * The rows that fit in a viewport of `viewport` height starting at row
+ * `first`, after clamping `first` into [0, maxFirst] so the list never
+ * scrolls past its end. Rows are given by their heights in order. A row
+ * taller than the viewport is never shown.
+ */
+export declare function scrollWindow(heights: readonly number[], viewport: number, first: number): ScrollWindow;
+/**
+ * The `first` row that brings row `index` into a viewport currently showing
+ * `shown`, moving as little as possible: unchanged when the row is already
+ * visible, the row itself when it lies above, and otherwise the earliest row
+ * from which `index` is still the last one that fits.
+ */
+export declare function revealRow(heights: readonly number[], viewport: number, shown: ScrollRange, index: number): number;
+/** True when rows precede the shown range. */
+export declare function canScrollUp(shown: ScrollRange): boolean;
+/** True when rows follow the shown range. */
+export declare function canScrollDown(shown: ScrollRange, rowCount: number): boolean;
+/**
+ * Turns a stream of wheel deltas (pixels) into whole row steps, carrying the
+ * remainder so a trackpad's small deltas add up. `rowStep` is the number of
+ * pixels per row.
+ */
+export declare class WheelAccumulator {
+    private readonly rowStep;
+    private carry;
+    constructor(rowStep: number);
+    /** Feed a delta; returns the number of rows to scroll (negative is up). */
+    add(delta: number): number;
+    /** Drop any carried remainder (when the scrolled container closes). */
+    reset(): void;
+}
+/** The look of the strips a container reserves at each end of a scrolled list. */
+export interface ScrollStripStyle {
+    /** Height of each strip. */
+    height: number;
+    /** Width of the chevron drawn on an active strip. */
+    arrowSize: number;
+    /** Chevron stroke width. */
+    arrowWidth: number;
+    arrowColor: RGBA;
+}
+/**
+ * The chevron on a scroll strip: pointing up for `direction` -1, down for 1,
+ * centred in `strip`.
+ */
+export declare function buildScrollArrow(strip: UIKitBox, direction: -1 | 1, style: ScrollStripStyle): LineData[];

package/dist/segmented.d.ts

@@ -0,0 +1,127 @@
+import { LineData } from './line';
+import { RectData } from './rect';
+import { UIKitFontMetrics } from './text/font';
+import { RGBA } from './text/layout';
+import { UIKitTextItem } from './textOverlay';
+/** Every visual knob on a segmented control. All lengths are in canvas pixels. */
+export interface SegmentedStyle {
+    /** Control height, unless the spec fixes one. */
+    height: number;
+    /** Space between a segment's edge and its label (sets the segment width). */
+    paddingX: number;
+    /** Space between the track edge and the segment faces. */
+    inset: number;
+    /** Corner radius of the track; segment faces use what is left after the inset. */
+    radius: number;
+    trackFill: RGBA;
+    trackBorder: RGBA;
+    trackBorderWidth: number;
+    /** Face of the selected segment. */
+    selectedFill: RGBA;
+    /** Face of an unselected segment under the pointer. */
+    hoverFill: RGBA;
+    /** Face of a segment while the pointer holds it down. */
+    pressedFill: RGBA;
+    textColor: RGBA;
+    selectedTextColor: RGBA;
+    disabledTextColor: RGBA;
+    /** Label em size. */
+    textSizePx: number;
+    /** Rule between two adjacent unselected segments. */
+    dividerColor: RGBA;
+    /** Focus ring color (around the track while the control has keyboard focus). */
+    focusRing: RGBA;
+    focusRingWidth: number;
+}
+export declare const DEFAULT_SEGMENTED_STYLE: SegmentedStyle;
+export interface SegmentSpec {
+    /** The value reported to `onChange` and held by the control. Unique per control. */
+    value: string;
+    label: string;
+    /** A disabled segment draws dimmed and cannot be chosen. Default true. */
+    enabled?: boolean;
+}
+export interface SegmentedSpec {
+    /** Stable key: the handle for updates, pointer tracking and the callback. */
+    id: string;
+    /** Top-left corner of the track, in canvas pixels. */
+    x: number;
+    y: number;
+    segments: readonly SegmentSpec[];
+    /** The selected segment's value, or null for none. */
+    value: string | null;
+    /** Width of every segment. Defaults to the widest label plus padding. */
+    segmentWidth?: number;
+    /** Control height. Defaults to the style's. */
+    height?: number;
+    /** A disabled control draws dimmed and ignores input. Default true. */
+    enabled?: boolean;
+    /** Per-control overrides of the overlay's default style. */
+    style?: Partial<SegmentedStyle>;
+    /** Fired when the user selects a different segment (pointer or keyboard), not by `setValue`. */
+    onChange?: (value: string, id: string) => void;
+}
+/** One segment's face, in canvas pixels. */
+export interface SegmentLayout {
+    index: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** The track and its segments, in canvas pixels. */
+export interface SegmentedLayout {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    segments: SegmentLayout[];
+}
+/** The transient state that changes how a segmented control looks. */
+export interface SegmentedVisual {
+    /** Index of the selected segment, or -1. */
+    selected: number;
+    /** Index of the segment under the pointer, or -1. */
+    hover: number;
+    /** Index of the segment the pointer holds down, or -1. */
+    pressed: number;
+    focused: boolean;
+    enabled: boolean;
+}
+export declare function resolveSegmentedStyle(base: SegmentedStyle, override?: Partial<SegmentedStyle>): SegmentedStyle;
+/** The track for a spec, with equal-width segment faces inside the inset. */
+export declare function layoutSegmented(spec: SegmentedSpec, style: SegmentedStyle, metrics: UIKitFontMetrics): SegmentedLayout;
+/** Scale every length in a spec and style by `k` (CSS pixels to canvas pixels). */
+export declare function scaleSegmented(spec: SegmentedSpec, style: SegmentedStyle, k: number): {
+    spec: SegmentedSpec;
+    style: SegmentedStyle;
+};
+/** True when canvas point (px, py) lies inside the track. */
+export declare function segmentedContains(layout: SegmentedLayout, px: number, py: number): boolean;
+/**
+ * The index of the segment under a canvas point, or -1. The inset around the
+ * faces counts toward the nearest segment, so the whole track is clickable.
+ */
+export declare function segmentAt(layout: SegmentedLayout, px: number, py: number): number;
+/** The index of the segment holding `value`, or -1. */
+export declare function segmentIndex(segments: readonly SegmentSpec[], value: string | null): number;
+/**
+ * The value of the next enabled segment from the current one in `direction`,
+ * wrapping around like a radio group. From no value, the first step lands on
+ * the first (or last) enabled segment. Returns the current value when no
+ * segment is enabled.
+ */
+export declare function stepSegmentValue(segments: readonly SegmentSpec[], value: string | null, direction: 1 | -1): string | null;
+/** The first or last enabled segment's value, or the current one when there is none. */
+export declare function endSegmentValue(segments: readonly SegmentSpec[], value: string | null, end: 'first' | 'last'): string | null;
+/**
+ * The draw data for one segmented control in one visual state: a focus ring
+ * when focused, the track, a face under the selected segment and under a
+ * hovered or pressed one, dividers between adjacent plain segments, and the
+ * centred labels.
+ */
+export declare function buildSegmented(spec: SegmentedSpec, style: SegmentedStyle, metrics: UIKitFontMetrics, layout: SegmentedLayout, visual: SegmentedVisual): {
+    rects: RectData[];
+    lines: LineData[];
+    text: UIKitTextItem[];
+};

package/dist/segmentedOverlay.d.ts

@@ -0,0 +1,87 @@
+import { UIKitOverlayFrame, UIKitOverlayRenderer } from '@niivue/niivue';
+import { UIKitInteractive, UIKitKeyEvent, UIKitRedrawSource } from './controls';
+import { SegmentedLayout, SegmentedSpec, SegmentedStyle, SegmentSpec } from './segmented';
+import { UIKitFont } from './text/font';
+export interface UIKitSegmentedOverlayOptions {
+    /** 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<SegmentedStyle>;
+    /**
+     * 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 UIKitSegmentedOverlay implements UIKitOverlayRenderer, UIKitInteractive {
+    readonly hoverCursor = "pointer";
+    private readonly font;
+    private readonly rects;
+    private readonly lines;
+    private readonly labels;
+    private readonly entries;
+    private baseStyle;
+    private readonly cssUnits;
+    private requestRedraw;
+    private scale;
+    private geometryDirty;
+    private pressedId;
+    /** Index of the segment the press started on. */
+    private pressedIndex;
+    /** While pressed: whether the pointer is over the pressed segment. */
+    private pressInside;
+    private hoverId;
+    private focusedId;
+    private layer;
+    constructor(font: UIKitFont, options?: UIKitSegmentedOverlayOptions);
+    /** Replace the default style for every control (per-spec overrides still win). */
+    setDefaultStyle(style: Partial<SegmentedStyle>): void;
+    /**
+     * Add a control, or replace the one with the same id. A replacement takes
+     * the new spec's value; a value no segment holds clears the selection.
+     */
+    addSegmented(spec: SegmentedSpec): void;
+    /** Replace the whole control set. */
+    setSegmenteds(specs: readonly SegmentedSpec[]): void;
+    removeSegmented(id: string): void;
+    /** Patch one control's spec. The value is kept unless the patch sets `value`. */
+    updateSegmented(id: string, patch: Partial<Omit<SegmentedSpec, 'id'>>): void;
+    setEnabled(id: string, enabled: boolean): void;
+    /** Replace a control's segments. A value no longer offered clears. */
+    setSegments(id: string, segments: readonly SegmentSpec[]): void;
+    getSegments(id: string): readonly SegmentSpec[];
+    /** Set a control's value from code. Does not fire `onChange`. Unknown values clear it. */
+    setValue(id: string, value: string | null): void;
+    getValue(id: string): string | null;
+    /** Select a segment as the user would (a keyboard shortcut, say): fires `onChange`. */
+    select(id: string, value: string): void;
+    /** The ids of all controls, in draw order. */
+    get ids(): string[];
+    /** A control's track and segments in spec units (canvas pixels, or CSS pixels with `cssUnits`). */
+    getLayout(id: string): SegmentedLayout | null;
+    /** The control with keyboard focus, if any. */
+    get focusedSegmented(): string | null;
+    /** Give a control keyboard focus (arrows move the selection), or null to clear. */
+    focus(id: string | null): void;
+    hitTest(x: number, y: number): boolean;
+    /** Presses the segment under the pointer (disabled segments still take focus). */
+    pointerDown(x: number, y: number): boolean;
+    pointerMove(x: number, y: number): boolean;
+    /** Selects the pressed segment when released over it. */
+    pointerUp(x: number, y: number): boolean;
+    pointerCancel(): void;
+    /** Arrows move the focused control's selection (wrapping); Home and End jump to the ends. */
+    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 segmentEnabled;
+    private scaled;
+    private layoutOf;
+    /** The topmost (last added) enabled control under a canvas point. */
+    private hitEntry;
+    private rebuild;
+}

package/dist/select.d.ts

@@ -0,0 +1,66 @@
+import { ButtonStyle } from './button';
+import { MenuButtonSpec, MenuItemSpec, MenuStyle } from './menu';
+import { UIKitFontMetrics } from './text/font';
+export interface SelectOption {
+    /** The value reported to `onChange` and held by the select. Unique per select. */
+    value: string;
+    label: string;
+    /** A disabled option draws dimmed and cannot be chosen. Default true. */
+    enabled?: boolean;
+}
+export interface SelectSpec {
+    /** Stable key: the handle for updates, open state and the callback. */
+    id: string;
+    /** Top-left corner of the button, in canvas pixels. */
+    x: number;
+    y: number;
+    /**
+     * Fixed button size. Width defaults to the widest option label (and the
+     * placeholder) so the button keeps its size as the value changes; height
+     * defaults to the label plus padding.
+     */
+    width?: number;
+    height?: number;
+    options: readonly SelectOption[];
+    /** The chosen option's value, or null for none (the placeholder shows). */
+    value: string | null;
+    /** Shown while nothing is chosen. Default ''. */
+    placeholder?: string;
+    /** A disabled select draws dimmed and ignores input. Default true. */
+    enabled?: boolean;
+    /** Per-select overrides of the overlay's default button style. */
+    buttonStyle?: Partial<ButtonStyle>;
+    /** Per-select overrides of the overlay's default popup style. */
+    style?: Partial<MenuStyle>;
+    /** Fired when the user chooses a different option (pointer or keyboard), not by `setValue`. */
+    onChange?: (value: string, id: string) => void;
+}
+/** The radio group every select's options share in the menu model. */
+export declare const SELECT_GROUP = "select";
+/** The option holding `value`, if any. */
+export declare function selectOption(options: readonly SelectOption[], value: string | null): SelectOption | null;
+/** The text the button shows: the chosen option's label, else the placeholder. */
+export declare function selectLabel(spec: SelectSpec): string;
+/**
+ * The button width that fits the widest option label and the placeholder,
+ * plus padding and the chevron. Used when the spec fixes no width.
+ */
+export declare function selectWidth(spec: SelectSpec, buttonStyle: ButtonStyle, style: MenuStyle, metrics: UIKitFontMetrics): number;
+/** The options as menu items: one radio group with the chosen option checked. */
+export declare function selectItems(spec: SelectSpec): MenuItemSpec[];
+/**
+ * The `MenuButtonSpec` a select draws and behaves as. Callbacks are left off:
+ * the select overlay reports value changes through its own `onChange`.
+ */
+export declare function selectMenuSpec(spec: SelectSpec, buttonStyle: ButtonStyle, style: MenuStyle, metrics: UIKitFontMetrics): MenuButtonSpec;
+/** The index of the option holding `value`, or -1. */
+export declare function selectIndex(options: readonly SelectOption[], value: string | null): number;
+/**
+ * The value `count` enabled options away from the current one in `direction`
+ * without wrapping (the ends stop), like a closed native select on arrow keys.
+ * From no value, the first step lands on the first (or last) enabled option.
+ * Returns the current value when nothing lies that way.
+ */
+export declare function stepSelectValue(options: readonly SelectOption[], value: string | null, direction: 1 | -1, count?: number): string | null;
+/** The first or last enabled option's value, or the current one when there is none. */
+export declare function endSelectValue(options: readonly SelectOption[], value: string | null, end: 'first' | 'last'): string | null;

package/dist/selectOverlay.d.ts

@@ -0,0 +1,102 @@
+import { UIKitOverlayFrame, UIKitOverlayRenderer } from '@niivue/niivue';
+import { ButtonLayout, ButtonStyle } from './button';
+import { UIKitInteractive, UIKitKeyEvent, UIKitRedrawSource } from './controls';
+import { MenuBounds, MenuPopupLayout, MenuStyle } from './menu';
+import { SelectOption, SelectSpec } from './select';
+import { UIKitFont } from './text/font';
+export interface UIKitSelectOverlayOptions {
+    /** Called whenever the overlay needs another frame. A control layer fills it in. */
+    requestRedraw?: () => void;
+    /** Default button style for every select; a spec's `buttonStyle` overrides per key. */
+    buttonStyle?: Partial<ButtonStyle>;
+    /** Default popup style for every select; a spec's `style` overrides per key. */
+    style?: Partial<MenuStyle>;
+    /**
+     * 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 UIKitSelectOverlay implements UIKitOverlayRenderer, UIKitInteractive {
+    readonly hoverCursor = "pointer";
+    private readonly font;
+    private readonly menu;
+    private readonly entries;
+    private readonly baseButtonStyle;
+    private readonly baseStyle;
+    constructor(font: UIKitFont, options?: UIKitSelectOverlayOptions);
+    /**
+     * Add a select, or replace the one with the same id. A replacement takes the
+     * new spec's value; an open replaced select closes.
+     */
+    addSelect(spec: SelectSpec): void;
+    /** Replace the whole select set. */
+    setSelects(specs: readonly SelectSpec[]): void;
+    removeSelect(id: string): void;
+    /** Patch one select's spec. The value is kept unless the patch sets `value`. */
+    updateSelect(id: string, patch: Partial<Omit<SelectSpec, 'id'>>): void;
+    setEnabled(id: string, enabled: boolean): void;
+    /**
+     * Replace a select's options (closing it if open and the values offered
+     * change). A value no longer offered clears.
+     */
+    setOptions(id: string, options: readonly SelectOption[]): void;
+    getOptions(id: string): readonly SelectOption[];
+    /** Set a select's value from code. Does not fire `onChange`. Unknown values clear it. */
+    setValue(id: string, value: string | null): void;
+    getValue(id: string): string | null;
+    /** The ids of all selects, in draw order. */
+    get ids(): string[];
+    /** A select button's box in spec units (canvas pixels, or CSS pixels with `cssUnits`). */
+    getLayout(id: string): ButtonLayout | null;
+    /** The open list's panel and rows in spec units, or null when none is open. */
+    getPopupLayout(): MenuPopupLayout | null;
+    /** The id of the select whose list is open, if any. */
+    get openSelect(): string | null;
+    isOpen(id: string): boolean;
+    /** The index of the highlighted option in the open list, or -1. */
+    get highlightedIndex(): number;
+    /** The select with keyboard focus, if any. */
+    get focusedSelect(): string | null;
+    /** Close an open list without choosing (the control layer's outside-press hook). */
+    dismiss(): void;
+    /** True while a list is open: the overlay then wants every event first. */
+    isModal(): boolean;
+    /** Open a select's list with the current option highlighted (closing any other). */
+    open(id: string): void;
+    /** Close the open list, if any, without choosing. */
+    close(): void;
+    /** Give a select keyboard focus, or null to clear. Disabled selects refuse. */
+    focus(id: string | null): void;
+    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;
+    /**
+     * The area popups must stay inside, in canvas pixels. `drawOverlay`
+     * refreshes it from every frame; call it yourself when driving the overlay
+     * without one. A list taller than the bounds scrolls.
+     */
+    setBounds(bounds: MenuBounds | null): void;
+    /** An open popup scrolls with the wheel; a closed select ignores it. */
+    wheel(x: number, y: number, deltaX: number, deltaY: number): boolean;
+    /**
+     * Open: the list handles the key (arrows move, Enter or Space choose, Escape
+     * closes). Closed and focused: ArrowUp/Down step the value (Shift or
+     * PageUp/PageDown by ten), Home and End jump to the ends, Enter, Space or
+     * Alt+ArrowDown open the list on the current option.
+     */
+    keyDown(e: UIKitKeyEvent): boolean;
+    blur(): void;
+    bindLayer(layer: UIKitRedrawSource): void;
+    drawOverlay(frame: UIKitOverlayFrame): void;
+    /** Draw the open list; a control layer calls this after every widget. */
+    drawPopup(frame: UIKitOverlayFrame): void;
+    /** Release GPU resources on both backends. */
+    destroy(): void;
+    /** Apply a user choice: update the value, the button label, and fire `onChange`. */
+    private choose;
+    /** Push an entry's current spec and value into the menu model. */
+    private sync;
+}