@react-x11/components 0.8.0 → 0.9.0

package/dist/maps/controller.d.ts

@@ -0,0 +1,283 @@
+import type { A11ySceneItem } from 'react-x11/node';
+import type { MapMarker } from './overlay.js';
+import type { LngLat, LngLatBounds, MapCamera, ScreenRect, Transform } from './proj.js';
+import type { FitBoundsOptions, MapFrameStats, MapHandle, MapPointerEvent } from './types.js';
+/** Where a map with no camera given starts. */
+export declare const DEFAULT_CAMERA: MapCamera;
+/** Logical pixels the pointer may travel before a press becomes a drag. */
+export declare const DRAG_THRESHOLD = 3;
+/**
+ * How long after the last camera change the map counts as moving.
+ *
+ * One window for both renderers, and both ask it the same question — is this
+ * a gesture? The retained renderer rasterizes nothing inside it, so a drag or
+ * a wheel is composites only; the GL renderer draws at reduced detail inside
+ * it when adaptive quality asks, and admits no new labels. `onMoveEnd` fires
+ * when it closes. Long enough that a wheel zoom's many notches count as one
+ * gesture, short enough that the map sharpens before the user has finished
+ * looking. (The retained renderer had 140 ms and the GL proof of concept
+ * 180; the retained number was the one its tests had pinned.)
+ */
+export declare const SETTLE_MS = 140;
+/** A zoom on the {@link ZOOM_STEP} grid — also what a label placement is
+ *  keyed on, so a placement and the zooms a wheel produces agree. */
+export declare function quantizeZoom(zoom: number): number;
+/** The props the controller reads — `<Map>`'s, whichever renderer draws. */
+export interface MapControllerProps {
+    camera?: MapCamera;
+    onCameraChange?: (camera: MapCamera) => void;
+    onMoveEnd?: (camera: MapCamera) => void;
+    minZoom?: number;
+    maxZoom?: number;
+    interactive?: boolean;
+    markers?: readonly MapMarker[];
+    onMapClick?: (event: MapPointerEvent) => void;
+    onMarkerClick?: (marker: MapMarker, event: MapPointerEvent) => void;
+    onMarkerHover?: (marker: MapMarker | null, event: MapPointerEvent | null) => void;
+}
+/**
+ * A renderer, as the controller sees it: where its pane is, and what a camera
+ * move costs it. Nothing about how it draws.
+ */
+export interface MapView {
+    /** The pane, in the window's logical pixels — empty before layout. */
+    pane(): ScreenRect;
+    /** Device pixels per logical pixel. */
+    scale(): number;
+    /**
+     * The camera moved, and the view should show it. `blit` says whether the
+     * move is a translation of what is already on screen — a pan — rather
+     * than a zoom or a jump: the retained renderer's difference between a
+     * blit and a repaint.
+     */
+    moved(previous: MapCamera, next: MapCamera, blit: boolean): void;
+    /** The settle window closed: the map is still, and may sharpen. */
+    settled(): void;
+    /** `refresh()`: throw away everything derived from the style. */
+    refresh(): void;
+    stats(): MapFrameStats | null;
+    /** Take the keyboard focus — a pan is where the arrows start working. */
+    focus(): void;
+}
+/** A pointer event as the controller reads it: pane-local logical pixels,
+ *  the button, the click count and the modifiers. */
+export interface MapPointerInput {
+    x: number;
+    y: number;
+    /** `1` left, `2` middle, `3` right. */
+    button?: number;
+    /** The click count: `2` is the second press of a double click. */
+    detail?: number;
+    shiftKey?: boolean;
+    ctrlKey?: boolean;
+    altKey?: boolean;
+    metaKey?: boolean;
+}
+/** What a press began — see {@link MapController.pointerDown}. */
+export type PressKind = 'marker' | 'pan' | 'frozen';
+export declare class MapController {
+    /**
+     * What `<Map>`'s ref hands out. Made once, so it is the **same object**
+     * for the life of the mount — across a renderer switch too, which is
+     * what lets an application hold it in a ref and never look again.
+     */
+    readonly handle: MapHandle;
+    /**
+     * Set by the view for the length of a frame. A camera change made inside
+     * one — the fit that a `fitBounds` asked for before layout, applied at
+     * the first frame with a size — is already what the frame draws, so it
+     * claims nothing and starts no gesture.
+     */
+    painting: boolean;
+    private _props;
+    /** The camera, when the application does not control it. */
+    private _camera;
+    private _view;
+    private _gesture;
+    private _hover;
+    /** Wall-clock time the settle window closes at. */
+    private _settleAt;
+    private _settleTimer;
+    private _glide;
+    private _glideTimer;
+    private _pendingFit;
+    constructor(seed?: MapCamera);
+    /** The props to read from here on. Read lazily, at event and frame time,
+     *  so a new object per render costs an assignment. */
+    setProps(props: MapControllerProps): void;
+    get props(): MapControllerProps;
+    /** The renderer drawing the map from now on. */
+    attach(view: MapView): void;
+    /** …and letting go, if it still is: during a renderer switch the new
+     *  view can attach before the old one is torn down. */
+    detach(view: MapView): void;
+    get view(): MapView | null;
+    /**
+     * Stop the timers — the settle window's, and a wheel glide in flight.
+     * They are the only things held that outlive a frame. The camera and the
+     * view stay, so a mount that React only pretends to tear down (a
+     * strict-mode double effect) comes back to a working controller; the next
+     * camera move arms the settle timer again, and the next notch a glide.
+     */
+    dispose(): void;
+    private _minZoom;
+    private _maxZoom;
+    private _interactive;
+    private _markers;
+    /** The camera in effect: the application's when it controls one. */
+    camera(): MapCamera;
+    /** The camera this controller keeps for itself — the one in effect
+     *  whenever the application is not controlling it. */
+    ownCamera(): MapCamera;
+    /** The pane, in the window's logical pixels — empty with no view. */
+    pane(): ScreenRect;
+    /** A camera resolved against the pane. */
+    transform(camera?: MapCamera): Transform;
+    /**
+     * Move the camera — the one place it changes.
+     *
+     * Clamped (the zoom to the range, the latitude to what Web Mercator can
+     * represent; the longitude is not, because the map wraps and a camera just
+     * past the antimeridian is a camera in the next copy of the world),
+     * reported, and the settle window restarted: every camera move is a
+     * gesture, not only a pointer one, because an application animating the
+     * camera with `panBy` in a loop wants what a drag wants.
+     *
+     * A camera the application controls is only *asked* to move:
+     * `onCameraChange` is the request, and the view hears about the move when
+     * the new `camera` prop arrives. Telling it here as well was a double
+     * shift — the retained renderer blitted the pane for the request and then
+     * again for the prop, and `scrollContents` adds two shifts in a frame
+     * together.
+     */
+    apply(next: MapCamera, blit: boolean): void;
+    getCamera(): MapCamera;
+    setCamera(camera: Partial<MapCamera>): void;
+    /** Move by a distance in pane-local logical pixels. */
+    panBy(dx: number, dy: number): void;
+    zoomIn(step?: number): void;
+    zoomOut(step?: number): void;
+    zoomTo(zoom: number): void;
+    /**
+     * Zoom by `delta` levels about a pane-local point that must not move —
+     * the pointer under a wheel, the pane's centre for a key.
+     */
+    zoomAbout(delta: number, x: number, y: number): void;
+    /**
+     * A scroll, as a zoom: where the wheel wants the camera, and how the
+     * frames after it get there.
+     *
+     * **Two devices arrive here and they want opposite things.** A wheel
+     * *clicks*: one event carrying a whole notch, with nothing in between, so
+     * the notch becomes a target the frames after it glide towards. A touchpad
+     * *measures*: a stream of fractions that is already as smooth as the hand
+     * making it, which wants applying the moment it arrives and only needs
+     * keeping from rounding away. `ev.smooth` is core's word for which device
+     * this is — "a whole notch is worth easing towards, a stream of measured
+     * pixels is not" (react-x11's docs/events.md).
+     *
+     * Either way the *target* accumulates. A second notch arriving mid-glide
+     * lengthens the one gesture instead of starting another, and a fraction
+     * too small to move the quantized camera is still on the books when the
+     * next one arrives.
+     */
+    private _wheelZoom;
+    /** Keep stepping a glide until it arrives. Idempotent: a notch arriving
+     *  mid-glide moves the target and finds the timer already running. */
+    private _armGlide;
+    /**
+     * One step of a glide: how far the camera moves this frame.
+     *
+     * Exponential rather than a curve with a duration, because the distance is
+     * not known when it starts — a second notch moves the target while the
+     * first is still being delivered — and because `elapsed` being the real
+     * gap between two frames is what makes the glide the same speed on a
+     * display that paints 120 frames a second and one that manages 30.
+     *
+     * Returns whether the camera moved. The move itself is what brings the
+     * frame that shows it: `apply` tells the view, exactly as a drag's every
+     * pointer step does.
+     */
+    stepZoom(at: number, elapsed: number): boolean;
+    fitBounds(bounds: LngLatBounds, options?: FitBoundsOptions): void;
+    fitMarkers(ids?: readonly string[], options?: FitBoundsOptions): void;
+    /** What the pane can see — the whole world before it has a size. */
+    getBounds(): LngLatBounds;
+    project(position: LngLat): {
+        x: number;
+        y: number;
+    };
+    unproject(x: number, y: number): LngLat;
+    markerAt(x: number, y: number): MapMarker | null;
+    /**
+     * A view is about to draw a frame: a `fitBounds` that arrived before the
+     * pane had a size is applied now, so the frame draws it.
+     */
+    beginFrame(): void;
+    /** Whether the camera moved within the settle window. */
+    get moving(): boolean;
+    /** …or a press is still down: what the retained renderer holds
+     *  rasterization off for. */
+    get gesturing(): boolean;
+    /** Whether a pan gesture is under way — a press that may yet drag. */
+    get dragging(): boolean;
+    /**
+     * Restart the settle window. When it closes the camera has held still for
+     * {@link SETTLE_MS}: `onMoveEnd` fires — the moment an application fetches
+     * what is now on screen — and the view is told it may sharpen.
+     *
+     * Wall-clock time rather than a frame clock: this is a window a hundred
+     * and forty milliseconds long compared inside a timer callback, and a
+     * timer is the one thing that runs when no frame does.
+     */
+    touch(): void;
+    /**
+     * A press. Answers what it began, for the view to capture the pointer — and
+     * for a pan, to take the focus — or null when nothing is.
+     *
+     * A press on a marker is a marker gesture: its release is a marker click.
+     * A press anywhere else is a pan, or on a map that does not move a
+     * `'frozen'` press, which pans nothing and is still a click when it is
+     * released — an application listening for clicks on a frozen map gets
+     * them.
+     */
+    pointerDown(input: MapPointerInput): PressKind;
+    /** The pointer moved with the press still down. */
+    pointerDrag(input: MapPointerInput): void;
+    /**
+     * The press let go. A release within the drag threshold of a marker press
+     * is that marker's click, then the map's; one that ended no drag is the
+     * map's click. And the second release of a double click zooms in about the
+     * pointer, Shift for out — the convention every map client has.
+     */
+    pointerUp(input: MapPointerInput): void;
+    /** The pointer moved with nothing pressed: the marker under it, if that
+     *  changed, is `onMarkerHover`'s. */
+    pointerMove(input: MapPointerInput): void;
+    /**
+     * The pointer left the map. No event: there is no position on the map to
+     * report, and inventing one would be worse than saying so.
+     */
+    pointerLeave(): void;
+    /**
+     * The wheel, which is a zoom about the pointer. True when it was consumed
+     * — always, on a map that moves: a wheel over a map is never meant for
+     * whatever is behind it.
+     */
+    wheel(input: MapPointerInput, deltaY: number, smooth?: boolean): boolean;
+    /** A key: the arrows pan, +/− zoom about the centre. True when it was one
+     *  of those, on a map that moves. */
+    keyDown(keysym: number, shiftKey: boolean): boolean;
+    /** Where a pointer event happened, in every space that could be wanted. */
+    pointerEvent(input: MapPointerInput, marker: MapMarker | null): MapPointerEvent;
+    /**
+     * What a screen reader meets: the markers in view, as buttons.
+     *
+     * A map is one painted rectangle to an assistive technology, and its
+     * markers are the only things in it that are *objects* rather than
+     * cartography — so those are the scene. Announcing every road would be
+     * worse than announcing none. The same whichever renderer draws.
+     */
+    markerScene(): A11ySceneItem[];
+}
+//# sourceMappingURL=controller.d.ts.map

package/dist/maps/controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../../src/maps/controller.ts"],"names":[],"mappings":"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"}