insomni-plot 0.1.0-alpha.0

package/src/interactions.test.ts

@@ -0,0 +1,226 @@
+import { beforeEach, describe, expect, test, vi } from "vite-plus/test";
+
+import { viewportFrame } from "insomni";
+import { bindDataViewport } from "./interactions.ts";
+import { createDataViewport } from "./viewport.ts";
+
+// ============ Fixtures ============
+
+type Listener = (event: unknown) => void;
+
+class FakeEventTarget {
+  private readonly listeners = new Map<string, Set<Listener>>();
+
+  addEventListener(type: string, listener: Listener): void {
+    let set = this.listeners.get(type);
+    if (!set) {
+      set = new Set();
+      this.listeners.set(type, set);
+    }
+    set.add(listener);
+  }
+
+  removeEventListener(type: string, listener: Listener): void {
+    this.listeners.get(type)?.delete(listener);
+  }
+
+  dispatch(type: string, event: unknown): void {
+    for (const l of Array.from(this.listeners.get(type) ?? [])) l(event);
+  }
+}
+
+interface FakeCanvas extends FakeEventTarget {
+  style: { cursor: string; touchAction?: string };
+  clientWidth: number;
+  clientHeight: number;
+  width: number;
+  height: number;
+  getBoundingClientRect(): { left: number; top: number; width: number; height: number };
+  setPointerCapture(_: number): void;
+  releasePointerCapture(_: number): void;
+  hasPointerCapture(_: number): boolean;
+}
+
+const fixture = {
+  canvas: (rect = { left: 0, top: 0, width: 800, height: 600 }): FakeCanvas => {
+    const target = new FakeEventTarget() as FakeEventTarget & Partial<FakeCanvas>;
+    target.style = { cursor: "" };
+    target.clientWidth = rect.width;
+    target.clientHeight = rect.height;
+    target.width = rect.width;
+    target.height = rect.height;
+    target.getBoundingClientRect = () => rect;
+    target.setPointerCapture = () => {};
+    target.releasePointerCapture = () => {};
+    target.hasPointerCapture = () => false;
+    return target as FakeCanvas;
+  },
+  wheelEvent: (clientX: number, clientY: number, deltaY = 100) => ({
+    clientX,
+    clientY,
+    deltaX: 0,
+    deltaY,
+    shiftKey: false,
+    metaKey: false,
+    ctrlKey: false,
+    altKey: false,
+    preventDefault: vi.fn(),
+  }),
+  pointerEvent: (
+    clientX: number,
+    clientY: number,
+    opts: { pointerId?: number; buttons?: number; pointerType?: string } = {},
+  ) => ({
+    pointerId: opts.pointerId ?? 1,
+    pointerType: opts.pointerType ?? "mouse",
+    clientX,
+    clientY,
+    buttons: opts.buttons ?? 1,
+    shiftKey: false,
+    metaKey: false,
+    ctrlKey: false,
+    altKey: false,
+    preventDefault: vi.fn(),
+  }),
+};
+
+describe("bindDataViewport", () => {
+  beforeEach(() => {
+    vi.stubGlobal("window", new FakeEventTarget());
+  });
+
+  test("wheel inside the viewport frame calls preventDefault and zooms", () => {
+    const canvas = fixture.canvas({ left: 0, top: 0, width: 400, height: 300 });
+    const vp = createDataViewport({
+      frame: viewportFrame(400, 300).padded({ top: 20, right: 20, bottom: 20, left: 20 }),
+      x: { type: "linear", domain: [0, 100] },
+      y: { type: "linear", domain: [0, 100] },
+    });
+    const zoomAt = vi.spyOn(vp, "zoomAt");
+
+    const binding = bindDataViewport(vp, canvas as unknown as HTMLElement);
+    expect(binding.mode).toBe("data");
+
+    const ev = fixture.wheelEvent(200, 150);
+    (canvas as unknown as FakeEventTarget).dispatch("wheel", ev);
+
+    expect(ev.preventDefault).toHaveBeenCalledOnce();
+    expect(zoomAt).toHaveBeenCalledOnce();
+  });
+
+  test("wheel outside the viewport frame does not preventDefault or zoom", () => {
+    const canvas = fixture.canvas({ left: 0, top: 0, width: 400, height: 300 });
+    const vp = createDataViewport({
+      frame: viewportFrame(400, 300).padded({ top: 20, right: 20, bottom: 20, left: 20 }),
+      x: { type: "linear", domain: [0, 100] },
+      y: { type: "linear", domain: [0, 100] },
+    });
+    const zoomAt = vi.spyOn(vp, "zoomAt");
+
+    bindDataViewport(vp, canvas as unknown as HTMLElement);
+
+    const ev = fixture.wheelEvent(5, 5);
+    (canvas as unknown as FakeEventTarget).dispatch("wheel", ev);
+
+    expect(ev.preventDefault).not.toHaveBeenCalled();
+    expect(zoomAt).not.toHaveBeenCalled();
+  });
+
+  test("pointerdown outside the frame does not start a drag", () => {
+    const canvas = fixture.canvas({ left: 0, top: 0, width: 400, height: 300 });
+    const vp = createDataViewport({
+      frame: viewportFrame(400, 300).padded({ top: 20, right: 20, bottom: 20, left: 20 }),
+      x: { type: "linear", domain: [0, 100] },
+      y: { type: "linear", domain: [0, 100] },
+    });
+    const panBy = vi.spyOn(vp, "panBy");
+
+    const binding = bindDataViewport(vp, canvas as unknown as HTMLElement);
+
+    (canvas as unknown as FakeEventTarget).dispatch("pointerdown", fixture.pointerEvent(5, 5));
+    (canvas as unknown as FakeEventTarget).dispatch("pointermove", fixture.pointerEvent(50, 50));
+    expect(panBy).not.toHaveBeenCalled();
+    expect(binding.interacting).toBe(false);
+  });
+
+  test("drag started inside the frame keeps panning after the pointer leaves", () => {
+    const canvas = fixture.canvas({ left: 0, top: 0, width: 400, height: 300 });
+    const vp = createDataViewport({
+      frame: viewportFrame(400, 300).padded({ top: 20, right: 20, bottom: 20, left: 20 }),
+      x: { type: "linear", domain: [0, 100] },
+      y: { type: "linear", domain: [0, 100] },
+    });
+    const panBy = vi.spyOn(vp, "panBy");
+
+    const binding = bindDataViewport(vp, canvas as unknown as HTMLElement);
+
+    (canvas as unknown as FakeEventTarget).dispatch("pointerdown", fixture.pointerEvent(200, 150));
+    (canvas as unknown as FakeEventTarget).dispatch(
+      "pointermove",
+      fixture.pointerEvent(2000, 2000),
+    );
+    expect(binding.interacting).toBe(true);
+    expect(panBy).toHaveBeenCalled();
+
+    (canvas as unknown as FakeEventTarget).dispatch("pointerup", fixture.pointerEvent(2000, 2000));
+    expect(binding.interacting).toBe(false);
+  });
+
+  test("smart defaults exclude band axes from pan/zoom", () => {
+    const canvas = fixture.canvas({ left: 0, top: 0, width: 400, height: 300 });
+    const vp = createDataViewport({
+      frame: viewportFrame(400, 300),
+      x: { type: "band", domain: ["a", "b", "c"] as string[] },
+      y: { type: "linear", domain: [0, 100] },
+    });
+    const zoomAt = vi.spyOn(vp, "zoomAt");
+
+    bindDataViewport(vp, canvas as unknown as HTMLElement);
+
+    const ev = fixture.wheelEvent(200, 150);
+    (canvas as unknown as FakeEventTarget).dispatch("wheel", ev);
+
+    expect(zoomAt).toHaveBeenCalledOnce();
+    const call = zoomAt.mock.calls[0]!;
+    const factor = call[2] as { x: number; y: number };
+    expect(factor.x).toBe(1);
+    expect(factor.y).not.toBe(1);
+  });
+
+  test("disabled flag short-circuits wheel handling", () => {
+    const canvas = fixture.canvas({ left: 0, top: 0, width: 400, height: 300 });
+    const vp = createDataViewport({
+      frame: viewportFrame(400, 300),
+      x: { type: "linear", domain: [0, 100] },
+      y: { type: "linear", domain: [0, 100] },
+    });
+    const zoomAt = vi.spyOn(vp, "zoomAt");
+
+    const binding = bindDataViewport(vp, canvas as unknown as HTMLElement);
+    binding.enabled = false;
+
+    const ev = fixture.wheelEvent(200, 150);
+    (canvas as unknown as FakeEventTarget).dispatch("wheel", ev);
+
+    expect(ev.preventDefault).not.toHaveBeenCalled();
+    expect(zoomAt).not.toHaveBeenCalled();
+  });
+
+  test("destroy releases the node", () => {
+    const canvas = fixture.canvas();
+    const vp = createDataViewport({
+      frame: viewportFrame(400, 300),
+      x: { type: "linear", domain: [0, 100] },
+      y: { type: "linear", domain: [0, 100] },
+    });
+    const zoomAt = vi.spyOn(vp, "zoomAt");
+
+    const binding = bindDataViewport(vp, canvas as unknown as HTMLElement);
+    binding.destroy();
+
+    const ev = fixture.wheelEvent(200, 150);
+    (canvas as unknown as FakeEventTarget).dispatch("wheel", ev);
+    expect(zoomAt).not.toHaveBeenCalled();
+    expect(ev.preventDefault).not.toHaveBeenCalled();
+  });
+});

package/src/interactions.ts

@@ -0,0 +1,394 @@
+import {
+  createInteractionManager,
+  createVelocityTracker,
+  smoothDamp,
+  VIEWPORT_Z,
+  type FlingOptions,
+  type InteractionNode,
+  type SmoothDamp,
+  type VelocityTracker,
+} from "insomni";
+import type { DataViewport } from "./viewport.ts";
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export type AxisSelection = "x" | "y" | "xy" | "none";
+
+export interface BindDataViewportOptions {
+  /** Enable pointer drag pan. Default: true. */
+  drag?: boolean;
+  /** Enable mouse-wheel zoom. Default: true. */
+  wheel?: boolean;
+  /** Enable two-finger pinch (touch). Default: true. */
+  pinch?: boolean;
+  /** SmoothDamp time constant (seconds). `0` = instant (no smoothing). Default: `0`. */
+  smoothTime?: number;
+  /**
+   * Drag-release fling. `true` enables with defaults, `false` disables, or
+   * pass an object to tune. Default: off (fling on a chart feels disorienting).
+   */
+  fling?: boolean | FlingOptions;
+
+  /**
+   * Axes that respond to drag / pinch pan. Default: derived from axis types
+   * (continuous/time axes pan; band axes don't).
+   */
+  pan?: AxisSelection;
+  /** Axes that respond to wheel / pinch zoom. Default: derived from axis types. */
+  zoom?: AxisSelection;
+  /** Multiplier applied to wheel deltaY. Default: 0.001. */
+  wheelSensitivity?: number;
+  /**
+   * When true, Shift while wheeling zooms Y only; Meta / Ctrl zoom X only.
+   * Default: true.
+   */
+  axisModifiers?: boolean;
+}
+
+export interface DataViewportBinding {
+  readonly mode: "data";
+  /** True while the user is actively dragging or pinching. */
+  readonly interacting: boolean;
+  /** True while a drag-release fling is still decaying. */
+  readonly flinging: boolean;
+  /** Hard disable. */
+  enabled: boolean;
+  /** Advance smoothing / fling by `dt` seconds and apply pending pan. */
+  update(dt: number): void;
+  /** Immediately cancel any pending smoothing and fling. */
+  stopAnimation(): void;
+  /** Remove all listeners and release any pending state. */
+  destroy(): void;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function nowSeconds(): number {
+  return (typeof performance !== "undefined" ? performance.now() : Date.now()) / 1000;
+}
+
+interface ResolvedFling {
+  enabled: boolean;
+  friction: number;
+  minVelocity: number;
+  windowSeconds: number;
+}
+
+function resolveFling(
+  opts: BindDataViewportOptions["fling"],
+  defaultEnabled: boolean,
+): ResolvedFling {
+  if (opts === false) {
+    return { enabled: false, friction: 4, minVelocity: 50, windowSeconds: 0.08 };
+  }
+  const cfg: FlingOptions = opts === undefined || opts === true ? {} : opts;
+  return {
+    enabled: opts === undefined ? defaultEnabled : true,
+    friction: cfg.friction ?? 4,
+    minVelocity: cfg.minVelocity ?? 50,
+    windowSeconds: cfg.windowSeconds ?? 0.08,
+  };
+}
+
+function defaultAxes(viewport: DataViewport<unknown, unknown>): AxisSelection {
+  const state = viewport._state;
+  const xCont = state.xAxis.kind === "continuous";
+  const yCont = state.yAxis.kind === "continuous";
+  if (xCont && yCont) return "xy";
+  if (xCont) return "x";
+  if (yCont) return "y";
+  return "none";
+}
+
+function axisHas(axes: AxisSelection, axis: "x" | "y"): boolean {
+  return axes === "xy" || axes === axis;
+}
+
+// Returns the largest fraction of `factor` that BOTH continuous axes can apply
+// without hitting their per-axis caps. zoomAxis caps newSpan (= curSpan/f) to
+// [baseSpan/maxZoom, baseSpan/minZoom], so f ∈ [curSpan*minZoom/baseSpan,
+// curSpan*maxZoom/baseSpan]; intersect across axes, clamp `factor` into it.
+function clampJointFactor<X, Y>(viewport: DataViewport<X, Y>, factor: number): number {
+  const s = viewport._state;
+  const { minZoom, maxZoom } = s;
+  let lo = -Infinity;
+  let hi = Infinity;
+  for (const axis of [s.xAxis, s.yAxis]) {
+    if (axis.kind !== "continuous") continue;
+    const baseAbs = Math.abs(axis.baseT1 - axis.baseT0);
+    const curAbs = Math.abs(axis.t1 - axis.t0);
+    if (baseAbs === 0 || curAbs === 0) continue;
+    lo = Math.max(lo, (curAbs * minZoom) / baseAbs);
+    hi = Math.min(hi, (curAbs * maxZoom) / baseAbs);
+  }
+  if (!Number.isFinite(lo) || !Number.isFinite(hi)) return factor;
+  if (lo > hi) return 1;
+  if (factor < lo) return lo;
+  if (factor > hi) return hi;
+  return factor;
+}
+
+// ---------------------------------------------------------------------------
+// bindDataViewport
+// ---------------------------------------------------------------------------
+
+export function bindDataViewport<X, Y>(
+  viewport: DataViewport<X, Y>,
+  element: HTMLElement,
+  options: BindDataViewportOptions = {},
+): DataViewportBinding {
+  const auto = defaultAxes(viewport as DataViewport<unknown, unknown>);
+  const pan = options.pan ?? auto;
+  const zoom = options.zoom ?? auto;
+  const wheelEnabled = (options.wheel ?? true) && zoom !== "none";
+  const dragEnabled = (options.drag ?? true) && pan !== "none";
+  const pinchEnabled = (options.pinch ?? true) && (pan !== "none" || zoom !== "none");
+  const wheelSensitivity = options.wheelSensitivity ?? 0.001;
+  const axisModifiers = options.axisModifiers ?? true;
+  const smoothTime = options.smoothTime ?? 0;
+  const fling = resolveFling(options.fling, false);
+  // Only bother with the damper + update(dt) loop when the user has opted
+  // into smoothing or fling. Simple data viewports stay synchronous.
+  const animated = smoothTime > 0 || fling.enabled;
+
+  const sdX: SmoothDamp = smoothDamp({ smoothTime });
+  const sdY: SmoothDamp = smoothDamp({ smoothTime });
+  let lastAppliedX = 0;
+  let lastAppliedY = 0;
+
+  const tracker: VelocityTracker = createVelocityTracker({ windowSeconds: fling.windowSeconds });
+  let flingVx = 0;
+  let flingVy = 0;
+  let flinging = false;
+
+  let enabled = true;
+  let interacting = false;
+
+  const stopAnimation = () => {
+    sdX.setTarget(sdX.value);
+    sdX.setVelocity(0);
+    sdY.setTarget(sdY.value);
+    sdY.setVelocity(0);
+    lastAppliedX = sdX.value;
+    lastAppliedY = sdY.value;
+    flingVx = 0;
+    flingVy = 0;
+    flinging = false;
+  };
+
+  const resetPanTargets = () => {
+    sdX.setTarget(0);
+    sdX.setValue(0);
+    sdX.setVelocity(0);
+    sdY.setTarget(0);
+    sdY.setValue(0);
+    sdY.setVelocity(0);
+    lastAppliedX = 0;
+    lastAppliedY = 0;
+  };
+
+  const zoomAt = (x: number, y: number, factor: number, axes: AxisSelection) => {
+    const fx = axes !== "none" && axisHas(axes, "x") && axisHas(zoom, "x") ? factor : 1;
+    const fy = axes !== "none" && axisHas(axes, "y") && axisHas(zoom, "y") ? factor : 1;
+    if (fx === 1 && fy === 1) return;
+    // Lock both axes to the more-constrained one so e.g. an axis whose
+    // visible span already sits at its cap doesn't silently stop while the
+    // other keeps going (which stretches the chart out of proportion).
+    if (fx !== 1 && fy !== 1 && fx === fy) {
+      const locked = clampJointFactor(viewport, factor);
+      if (locked === 1) return;
+      viewport.zoomAt(x, y, { x: locked, y: locked });
+      return;
+    }
+    viewport.zoomAt(x, y, { x: fx, y: fy });
+  };
+
+  const panByImmediate = (dx: number, dy: number) => {
+    const ux = axisHas(pan, "x") ? dx : 0;
+    const uy = axisHas(pan, "y") ? dy : 0;
+    if (ux || uy) viewport.panBy(ux, uy);
+  };
+
+  const manager = createInteractionManager(element);
+  const node: InteractionNode = manager.add({
+    zIndex: VIEWPORT_Z,
+    enabled,
+    space: "ui",
+    bounds: () => viewport.absoluteFrame,
+    cursor: dragEnabled ? "grab" : "default",
+    dragCursor: "grabbing",
+
+    onScroll: wheelEnabled
+      ? (evt) => {
+          const raw = 1 - evt.dy * wheelSensitivity;
+          const factor = raw <= 0 ? 0.001 : raw;
+          if (axisModifiers && (evt.mods.shift || evt.mods.meta || evt.mods.ctrl)) {
+            const onlyY = evt.mods.shift && !(evt.mods.meta || evt.mods.ctrl);
+            zoomAt(evt.x, evt.y, factor, onlyY ? "y" : "x");
+          } else {
+            zoomAt(evt.x, evt.y, factor, "xy");
+          }
+        }
+      : undefined,
+
+    onDragStart: dragEnabled
+      ? (evt) => {
+          interacting = true;
+          flinging = false;
+          flingVx = 0;
+          flingVy = 0;
+          if (animated) resetPanTargets();
+          if (fling.enabled) {
+            tracker.reset();
+            tracker.sample(nowSeconds(), evt.x, evt.y);
+          }
+        }
+      : undefined,
+    onDragMove: dragEnabled
+      ? (evt) => {
+          panByImmediate(evt.dx, evt.dy);
+          if (fling.enabled) tracker.sample(nowSeconds(), evt.x, evt.y);
+        }
+      : undefined,
+    onDragEnd: dragEnabled
+      ? () => {
+          interacting = false;
+          if (!fling.enabled) return;
+          const v = tracker.velocity();
+          const vx = axisHas(pan, "x") ? v.x : 0;
+          const vy = axisHas(pan, "y") ? v.y : 0;
+          const mag = Math.hypot(vx, vy);
+          if (mag < fling.minVelocity) return;
+          resetPanTargets();
+          flingVx = vx;
+          flingVy = vy;
+          flinging = true;
+        }
+      : undefined,
+
+    onPinch: pinchEnabled
+      ? (evt) => {
+          if (evt.phase === "start") {
+            interacting = true;
+            flinging = false;
+            flingVx = 0;
+            flingVy = 0;
+            if (animated) resetPanTargets();
+            return;
+          }
+          if (evt.phase === "end") {
+            interacting = false;
+            return;
+          }
+          if (pan !== "none") {
+            panByImmediate(evt.deltaX, evt.deltaY);
+          }
+          if (
+            zoom !== "none" &&
+            evt.deltaScale !== 1 &&
+            Number.isFinite(evt.deltaScale) &&
+            evt.deltaScale > 0
+          ) {
+            zoomAt(evt.focalX, evt.focalY, evt.deltaScale, "xy");
+          }
+        }
+      : undefined,
+  });
+
+  const continuousDomainValue = (domain: unknown): [number, number] | null => {
+    if (!Array.isArray(domain) || domain.length !== 2) return null;
+    const a = domain[0];
+    const b = domain[1];
+    const av = a instanceof Date ? a.getTime() : typeof a === "number" ? a : NaN;
+    const bv = b instanceof Date ? b.getTime() : typeof b === "number" ? b : NaN;
+    if (!Number.isFinite(av) || !Number.isFinite(bv)) return null;
+    return [av, bv];
+  };
+
+  const domainsEqual = (a: [number, number] | null, b: [number, number] | null): boolean => {
+    if (a === null || b === null) return a === b;
+    return a[0] === b[0] && a[1] === b[1];
+  };
+
+  const update = (dt: number) => {
+    if (dt <= 0) return;
+    if (!animated) return;
+
+    if (flinging) {
+      if (axisHas(pan, "x")) sdX.setTarget(sdX.target + flingVx * dt);
+      if (axisHas(pan, "y")) sdY.setTarget(sdY.target + flingVy * dt);
+      const decay = Math.exp(-fling.friction * dt);
+      flingVx *= decay;
+      flingVy *= decay;
+      if (Math.hypot(flingVx, flingVy) < fling.minVelocity * 0.1) {
+        flingVx = 0;
+        flingVy = 0;
+        flinging = false;
+      }
+    }
+
+    const stepX = axisHas(pan, "x");
+    const stepY = axisHas(pan, "y");
+    if (stepX) sdX.step(dt);
+    if (stepY) sdY.step(dt);
+    const dx = stepX ? sdX.value - lastAppliedX : 0;
+    const dy = stepY ? sdY.value - lastAppliedY : 0;
+    if (dx === 0 && dy === 0) return;
+
+    const beforeX = stepX ? continuousDomainValue(viewport.visibleXDomain) : null;
+    const beforeY = stepY ? continuousDomainValue(viewport.visibleYDomain) : null;
+    viewport.panBy(dx, dy);
+    lastAppliedX += dx;
+    lastAppliedY += dy;
+
+    // Clamp detection: if the viewport rejected the pan (pan-bounds or a band
+    // axis), snap the damper to the current value so the user isn't fighting a
+    // growing residual target on the next drag. Fling velocity dies at the wall.
+    if (stepX && dx !== 0) {
+      const afterX = continuousDomainValue(viewport.visibleXDomain);
+      const clamped = !beforeX || !afterX || domainsEqual(beforeX, afterX);
+      if (clamped) {
+        sdX.setTarget(sdX.value);
+        sdX.setVelocity(0);
+        flingVx = 0;
+      }
+    }
+    if (stepY && dy !== 0) {
+      const afterY = continuousDomainValue(viewport.visibleYDomain);
+      const clamped = !beforeY || !afterY || domainsEqual(beforeY, afterY);
+      if (clamped) {
+        sdY.setTarget(sdY.value);
+        sdY.setVelocity(0);
+        flingVy = 0;
+      }
+    }
+    if (flingVx === 0 && flingVy === 0) flinging = false;
+  };
+
+  return {
+    mode: "data",
+    get interacting() {
+      return interacting;
+    },
+    get flinging() {
+      return flinging;
+    },
+    get enabled() {
+      return enabled;
+    },
+    set enabled(v: boolean) {
+      enabled = v;
+      node.update({ enabled: v });
+    },
+    update,
+    stopAnimation,
+    destroy() {
+      node.destroy();
+      manager.destroy();
+    },
+  };
+}

package/src/layout/box.d.ts

@@ -0,0 +1,48 @@
+import type { Layer } from "insomni";
+export interface MeasuredBox {
+    width: number;
+    height: number;
+}
+export interface BoxOrigin {
+    x: number;
+    y: number;
+}
+/**
+ * A measure-then-place rectangle. Implementations must return a stable
+ * `measure()` (called by parents to size themselves) and an `addTo` that
+ * draws into a layer at the given top-left.
+ */
+export interface Placeable {
+    measure(): MeasuredBox;
+    addTo(layer: Layer, origin: BoxOrigin): void;
+}
+export type StackDirection = "horizontal" | "vertical";
+export type StackAlign = "start" | "center" | "end";
+export interface StackOptions {
+    direction: StackDirection;
+    /** Cross-axis alignment. Default `"start"`. */
+    align?: StackAlign;
+    /** Pixel gap between items. Default `0`. */
+    gap?: number;
+}
+/**
+ * Lay out `items` along one axis. The stack's bbox is the sum of children
+ * along the main axis (plus gaps) and the max along the cross axis.
+ *
+ * Children are measured **once** at construction; `measure()` and `addTo()`
+ * are O(items) thereafter. If you need to refresh measurements, build a new
+ * stack.
+ */
+export declare function stack(items: readonly Placeable[], opts: StackOptions): Placeable;
+export interface Padding {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+}
+/** Wrap `item` so its bbox includes uniform or per-side margin. */
+export declare function pad(item: Placeable, p: Padding): Placeable;
+/** A degenerate Placeable that occupies space but draws nothing. */
+export declare function spacer(width: number, height: number): Placeable;
+/** Lift a measure + draw pair into a Placeable. */
+export declare function placeable(measure: MeasuredBox, draw: (layer: Layer, origin: BoxOrigin) => void): Placeable;