@gg-web-engine/mobile-controls 0.0.0-stage → 0.0.78

package/README.md

@@ -1,3 +1,152 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="../../documentation/assets/banner.png" width="100%" alt="GG Web Engine"/>
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+## On-screen touch controls for [gg-web-engine](https://github.com/AndyGura/gg-web-engine)
+
+`@gg-web-engine/mobile-controls` puts buttons, sticks and d-pads over the game canvas on phones and
+tablets. It is plain DOM with no dependency besides the core, and a separate package on purpose: an
+app that does not import it ships none of it.
+
+### Installation:
+1) make sure **@gg-web-engine/core** installed
+1) `npm install --save @gg-web-engine/mobile-controls`
+
+### Usage
+```typescript
+import { MobileControls } from '@gg-web-engine/mobile-controls';
+
+world.addEntity(new MobileControls());
+```
+
+That is the whole setup. The overlay watches the world and shows the controls of whichever input
+controller is active, swapping them as controllers are activated, deactivated, spawned and removed
+(walking up to a car and driving off swaps the character controls for the car controls):
+
+| Controller | Controls |
+|---|---|
+| `GgCarHandlingController` | steering, accelerate, brake, handbrake, gears when the driver has to shift |
+| `CarHandlingController` (on its own) | steering, accelerate, brake |
+| `PlayerCharacterController` | move stick, look by dragging, jump, run, crouch, switch view |
+| `PlayerCharacterController2d` | left/right, jump, run, crouch |
+| `FreeCameraController` | move stick, look by dragging, up, down, boost |
+
+`OrbitCameraController` needs no controls, it follows one- and two-finger drags on the canvas itself.
+
+By default the overlay exists only on a touch-first device (`enabled: 'auto'`); pass `enabled: true`
+to try it with a mouse.
+
+### Choosing a control scheme
+Every built-in layout has variants:
+
+```typescript
+new MobileControls({
+  // 'buttons' (default) | 'stick' | 'tilt' - tilt steers by turning the device like a wheel
+  car: { steering: 'tilt', gears: false },
+  // movement: 'stick' (default, appears under the thumb) | 'dpad'
+  // look: 'drag' (default) | 'stick' (a second stick) | false
+  character: { movement: 'dpad', look: 'drag', lookSensitivity: 4 },
+  character2d: { movement: 'stick' },
+  freeCamera: false, // no touch controls for this controller
+});
+```
+
+### Adjusting a layout
+Each control of a layout has an id (`'accelerate'`, `'jump'`, `'move'`, ... - see the
+`*LayoutControlId` types). The layout options take them to move, restyle, hide or add controls:
+
+```typescript
+new MobileControls({
+  car: {
+    placements: { handbrake: { right: 28, bottom: 4 } }, // numbers are multiples of --gg-mc-unit
+    icons: { accelerate: '<img src="assets/pedal.svg">', brake: 'B' },
+    hide: ['gear-up', 'gear-down'],
+    extra: (controller, { world }) => [
+      new TouchButton({ id: 'horn', content: '📣', placement: { right: 4, top: 4 } })
+        .bindKey(world.keyboardInput, 'KeyH'),
+    ],
+  },
+});
+```
+
+Controls that belong to no controller stay on screen all the time:
+
+```typescript
+const controls = new MobileControls();
+controls.addControls(
+  new TouchButton({ id: 'pause', content: 'II', placement: { left: 4, top: 4 } }).onPress(() => togglePause()),
+);
+world.addEntity(controls);
+```
+
+A single control is hidden and shown with `control.visible` (an action not available right now) and
+moved with `control.place({...})`. `controls.visible = false` hides everything (a menu, a cutscene) and releases whatever was held.
+
+### Styling
+The default stylesheet is driven by CSS custom properties on the overlay, so a class of your own
+restyles everything, and `.gg-mc-id-<id>` reaches a single control:
+
+```css
+.my-controls {
+  --gg-mc-unit: 9px;                 /* everything is sized in this */
+  --gg-mc-color: #ffd166;
+  --gg-mc-background: rgba(0, 0, 0, 0.4);
+  --gg-mc-border: rgba(255, 209, 102, 0.7);
+  --gg-mc-active-background: rgba(255, 209, 102, 0.5);
+  --gg-mc-opacity: 1;
+}
+.my-controls .gg-mc-id-jump { border-radius: 20%; }
+```
+```typescript
+new MobileControls({ className: 'my-controls' });
+```
+
+`injectStyles: false` drops the default stylesheet altogether for a fully custom look.
+
+### Your own layout, your own controller
+A layout is a function from a controller to controls. Register one for any entity class - your own
+controller, or a built-in one to replace its layout wholesale:
+
+```typescript
+controls.registerLayout(TurretController, (turret, { world }) => [
+  new TouchLookArea().bindMouse(turret.mouseInput, 3),
+  new TouchStick({ id: 'aim', placement: { left: 4, bottom: 3 } }).bindDirection(turret.directionsInput),
+  new TouchButton({ id: 'fire', content: 'FIRE', placement: { right: 4, bottom: 4, width: 12, height: 12 } })
+    .onPress(() => turret.fire()),
+]);
+```
+
+The controls bind to what the engine already has, so nothing in the controller needs to know about
+touch:
+
+| Binding | Effect |
+|---|---|
+| `button.bindKey(keyboard, 'Space')` | the button is that key (`KeyboardInput.emulateKeyDown/Up`) |
+| `button.bindDirection(input, { x: -1 })` | pushes a `DirectionInput` while pressed |
+| `stick.bindDirection(input)` | analog direction into a `DirectionInput` |
+| `stick.bindKeys(keyboard, { up: 'KeyW', ... })` | holds keys past a threshold |
+| `stick.bindLook(mouse)` / `lookArea.bindMouse(mouse)` | turns the view like the mouse does (`MouseInput.emulateMove`) |
+| `button.pressed$`, `stick.value$`, `lookArea.delta$`/`tap$` | plain observables for anything else |
+
+`TouchButton`, `TouchStick`, `TouchDPad` and `TouchLookArea` do not need the overlay: each owns a DOM
+`element` you can append anywhere in your own UI. `TiltInput` is likewise usable alone.
+
+### Where the overlay goes
+By default it is added to `document.body` and covers the viewport, which suits a game filling the
+page. For a canvas that takes a part of the page, or one shown through the Fullscreen API, wrap the
+canvas in a positioned element and pass it as `container`: the overlay then covers exactly that
+element and goes fullscreen with it.
+
+```typescript
+new MobileControls({ container: document.getElementById('game-wrapper') });
+```
+
+### Notes
+- A look area covers the canvas, so taps on the canvas itself do not reach the page while a layout
+  with `look: 'drag'` is shown; use the area's `tap$`, or `look: false`.
+- Tilt steering works on pages served over https (or from localhost) only - a phone opening a dev
+  server by its LAN address over plain http gets no orientation data.
+- Tilt steering needs the device orientation permission on iOS. `TiltInput` asks for it on the first
+  tap after it starts and reports the outcome through `permission$`.
+- A layout is built once per activation of its controller. After changing something it was built
+  from (e.g. giving the car controller a car with another gearbox), call `controls.refresh()`.

package/dist/controls/touch-axis-control.d.ts

@@ -0,0 +1,38 @@
+import { Observable } from 'rxjs';
+import { DirectionInput, KeyboardInput, MouseInput, Point2 } from '@gg-web-engine/core';
+import { TouchControl, TouchControlOptions } from './touch-control';
+/** The key codes a `TouchAxisControl` presses for each direction - see `bindKeys`. */
+export type AxisKeys = {
+    up?: string;
+    down?: string;
+    left?: string;
+    right?: string;
+};
+/**
+ * The base of the controls that point in a direction (`TouchStick`, `TouchDPad`). `value$` is a
+ * vector with `x` from -1 (left) to 1 (right) and `y` from -1 (down) to 1 (up), never longer than 1 -
+ * the same convention as `DirectionInput.direction$`.
+ */
+export declare abstract class TouchAxisControl extends TouchControl {
+    private readonly _value$;
+    /** Emits the current value on subscription and then every change; completes on `dispose`. */
+    get value$(): Observable<Point2>;
+    get value(): Point2;
+    protected constructor(kind: string, options: TouchControlOptions);
+    protected setValue(value: Point2): void;
+    /**
+     * Feeds the control into `input` as an analog direction, which every built-in controller moving by
+     * direction keys (car, character, free camera) follows proportionally.
+     */
+    bindDirection(input: DirectionInput): this;
+    /**
+     * Makes the control hold a key of `keyboard` down per direction while it points that way further
+     * than `threshold` - for anything that only understands keys.
+     */
+    bindKeys(keyboard: KeyboardInput, keys: AxisKeys, threshold?: number): this;
+    /**
+     * Makes the control turn a view the way a mouse does: while it is deflected, `mouse` reports a
+     * continuous movement of up to `speed` pixels per second in that direction.
+     */
+    bindLook(mouse: MouseInput, speed?: number): this;
+}

package/dist/controls/touch-axis-control.js

@@ -0,0 +1,91 @@
+import { BehaviorSubject, takeUntil } from 'rxjs';
+import { distinctUntilChanged } from 'rxjs/operators';
+import { Pnt2 } from '@gg-web-engine/core';
+import { TouchControl } from './touch-control';
+/**
+ * The base of the controls that point in a direction (`TouchStick`, `TouchDPad`). `value$` is a
+ * vector with `x` from -1 (left) to 1 (right) and `y` from -1 (down) to 1 (up), never longer than 1 -
+ * the same convention as `DirectionInput.direction$`.
+ */
+export class TouchAxisControl extends TouchControl {
+    /** Emits the current value on subscription and then every change; completes on `dispose`. */
+    get value$() {
+        return this._value$.pipe(distinctUntilChanged((a, b) => a.x === b.x && a.y === b.y), takeUntil(this.disposed$));
+    }
+    get value() {
+        return this._value$.getValue();
+    }
+    constructor(kind, options) {
+        super(kind, options);
+        this._value$ = new BehaviorSubject(Pnt2.O);
+    }
+    setValue(value) {
+        if (!this.disposed) {
+            this._value$.next(value);
+        }
+    }
+    /**
+     * Feeds the control into `input` as an analog direction, which every built-in controller moving by
+     * direction keys (car, character, free camera) follows proportionally.
+     */
+    bindDirection(input) {
+        this.value$.subscribe(v => input.setAnalogDirection(this, v.x === 0 && v.y === 0 ? null : v));
+        return this;
+    }
+    /**
+     * Makes the control hold a key of `keyboard` down per direction while it points that way further
+     * than `threshold` - for anything that only understands keys.
+     */
+    bindKeys(keyboard, keys, threshold = 0.5) {
+        const held = {};
+        const set = (code, down) => {
+            if (!code || !!held[code] === down) {
+                return;
+            }
+            held[code] = down;
+            down ? keyboard.emulateKeyDown(code) : keyboard.emulateKeyUp(code);
+        };
+        this.value$.subscribe(v => {
+            set(keys.up, v.y > threshold);
+            set(keys.down, v.y < -threshold);
+            set(keys.left, v.x < -threshold);
+            set(keys.right, v.x > threshold);
+        });
+        return this;
+    }
+    /**
+     * Makes the control turn a view the way a mouse does: while it is deflected, `mouse` reports a
+     * continuous movement of up to `speed` pixels per second in that direction.
+     */
+    bindLook(mouse, speed = 900) {
+        let frame = null;
+        let last = 0;
+        const step = (time) => {
+            frame = null;
+            const { x, y } = this.value;
+            if (this.disposed || (x === 0 && y === 0)) {
+                return;
+            }
+            // the first frame's timestamp is its start time, which may precede the moment `last` was taken
+            const dt = Math.max(0, Math.min(100, time - last)) / 1000;
+            last = time;
+            // the pointer's y grows downwards, the control's upwards
+            mouse.emulateMove({ x: x * speed * dt, y: -y * speed * dt });
+            frame = requestAnimationFrame(step);
+        };
+        this.value$.subscribe({
+            next: v => {
+                if (frame === null && (v.x !== 0 || v.y !== 0)) {
+                    last = performance.now();
+                    frame = requestAnimationFrame(step);
+                }
+            },
+            complete: () => {
+                if (frame !== null) {
+                    cancelAnimationFrame(frame);
+                }
+            },
+        });
+        return this;
+    }
+}

package/dist/controls/touch-button.d.ts

@@ -0,0 +1,49 @@
+import { Observable } from 'rxjs';
+import { AnalogDirection, DirectionInput, KeyboardInput } from '@gg-web-engine/core';
+import { TouchControl, TouchControlOptions } from './touch-control';
+export type TouchButtonOptions = TouchControlOptions & {
+    /** What the button shows: markup (an inline SVG, plain text) or a DOM node. */
+    content?: string | Node;
+    /**
+     * `'hold'` (default): pressed while a finger is on it. `'toggle'`: every tap flips it, for an
+     * action that would otherwise need a finger parked on the button (sprint, crouch).
+     */
+    mode?: 'hold' | 'toggle';
+};
+/**
+ * An on-screen button. Read it through `pressed$`, or bind it to what a key already does with
+ * `bindKey`, so anything an app maps to its keyboard gets a touch button without further code.
+ */
+export declare class TouchButton extends TouchControl {
+    readonly mode: 'hold' | 'toggle';
+    private readonly _pressed$;
+    private _pressed;
+    private emitting;
+    private disposeRequested;
+    /** Emits the current state on subscription and then every change; completes on `dispose`. */
+    get pressed$(): Observable<boolean>;
+    get pressed(): boolean;
+    /** Settable, e.g. to bring a toggle button in line with a state that changed by other means. */
+    set pressed(value: boolean);
+    constructor(options?: TouchButtonOptions);
+    setContent(content: string | Node): void;
+    /**
+     * Makes the button act as the key `code` of `keyboard`: pressing it is that key going down,
+     * releasing it the key going up.
+     */
+    bindKey(keyboard: KeyboardInput, code: string): this;
+    /**
+     * Makes the button push `input` in a direction while pressed, e.g. `{ x: -1 }` for "left".
+     */
+    bindDirection(input: DirectionInput, value: AnalogDirection): this;
+    /** Calls `callback` every time the button becomes pressed. */
+    onPress(callback: () => void): this;
+    /** Calls `callback` every time the button stops being pressed. */
+    onRelease(callback: () => void): this;
+    reset(): void;
+    dispose(): void;
+    /** `pressed$` without the value it replays on subscription. */
+    private get changes$();
+    protected onPointerStart(): void;
+    protected onPointerEnd(): void;
+}

package/dist/controls/touch-button.js

@@ -0,0 +1,111 @@
+import { BehaviorSubject, skip, takeUntil } from 'rxjs';
+import { distinctUntilChanged, filter } from 'rxjs/operators';
+import { TouchControl } from './touch-control';
+/**
+ * An on-screen button. Read it through `pressed$`, or bind it to what a key already does with
+ * `bindKey`, so anything an app maps to its keyboard gets a touch button without further code.
+ */
+export class TouchButton extends TouchControl {
+    /** Emits the current state on subscription and then every change; completes on `dispose`. */
+    get pressed$() {
+        return this._pressed$.pipe(distinctUntilChanged(), takeUntil(this.disposed$));
+    }
+    get pressed() {
+        return this._pressed;
+    }
+    /** Settable, e.g. to bring a toggle button in line with a state that changed by other means. */
+    set pressed(value) {
+        if (this.disposed || value === this._pressed) {
+            return;
+        }
+        this._pressed = value;
+        this.element.classList.toggle('gg-mc-active', value);
+        this.element.setAttribute('aria-pressed', `${value}`);
+        if (this.emitting) {
+            // set from within a subscriber: the loop below delivers it once every subscriber has seen
+            // the change being emitted, so all of them get the changes in the same order
+            return;
+        }
+        this.emitting = true;
+        try {
+            while (this._pressed$.getValue() !== this._pressed) {
+                this._pressed$.next(this._pressed);
+            }
+        }
+        finally {
+            this.emitting = false;
+        }
+        if (this.disposeRequested) {
+            super.dispose();
+        }
+    }
+    constructor(options = {}) {
+        var _a;
+        super('button', options);
+        this._pressed$ = new BehaviorSubject(false);
+        this._pressed = false;
+        this.emitting = false;
+        this.disposeRequested = false;
+        this.mode = options.mode || 'hold';
+        this.element.setAttribute('role', 'button');
+        this.setContent((_a = options.content) !== null && _a !== void 0 ? _a : '');
+    }
+    setContent(content) {
+        if (typeof content === 'string') {
+            this.element.innerHTML = content;
+        }
+        else {
+            this.element.replaceChildren(content);
+        }
+    }
+    /**
+     * Makes the button act as the key `code` of `keyboard`: pressing it is that key going down,
+     * releasing it the key going up.
+     */
+    bindKey(keyboard, code) {
+        this.changes$.subscribe(pressed => (pressed ? keyboard.emulateKeyDown(code) : keyboard.emulateKeyUp(code)));
+        return this;
+    }
+    /**
+     * Makes the button push `input` in a direction while pressed, e.g. `{ x: -1 }` for "left".
+     */
+    bindDirection(input, value) {
+        this.changes$.subscribe(pressed => input.setAnalogDirection(this, pressed ? value : null));
+        return this;
+    }
+    /** Calls `callback` every time the button becomes pressed. */
+    onPress(callback) {
+        this.changes$.pipe(filter(pressed => pressed)).subscribe(() => callback());
+        return this;
+    }
+    /** Calls `callback` every time the button stops being pressed. */
+    onRelease(callback) {
+        this.changes$.pipe(filter(pressed => !pressed)).subscribe(() => callback());
+        return this;
+    }
+    reset() {
+        super.reset();
+        this.pressed = false;
+    }
+    dispose() {
+        if (this.emitting) {
+            // disposed from within a subscriber: the release has to reach every subscriber first
+            this.disposeRequested = true;
+            this.reset();
+            return;
+        }
+        super.dispose();
+    }
+    /** `pressed$` without the value it replays on subscription. */
+    get changes$() {
+        return this.pressed$.pipe(skip(1));
+    }
+    onPointerStart() {
+        this.pressed = this.mode === 'toggle' ? !this.pressed : true;
+    }
+    onPointerEnd() {
+        if (this.mode === 'hold') {
+            this.pressed = false;
+        }
+    }
+}

package/dist/controls/touch-control.d.ts

@@ -0,0 +1,76 @@
+import { Subject } from 'rxjs';
+/**
+ * Where a control sits inside the overlay and how big it is. A number is a multiple of the overlay's
+ * `--gg-mc-unit` (an edge offset also keeps clear of the device's safe-area inset on that side); a
+ * string is used as a CSS value as is. Leave `width`/`height` out to keep the size the stylesheet
+ * gives that kind of control.
+ */
+export type ControlPlacement = {
+    left?: number | string;
+    right?: number | string;
+    top?: number | string;
+    bottom?: number | string;
+    width?: number | string;
+    height?: number | string;
+};
+export type TouchControlOptions = {
+    /**
+     * Identifies the control within its layout. Becomes the element's `gg-mc-id-<id>` class and
+     * `data-gg-mc` attribute, for styling one control from CSS.
+     */
+    id?: string;
+    placement?: ControlPlacement;
+    /** Extra CSS class names for the element, space-separated. */
+    className?: string;
+    /** Accessible name of the control. */
+    label?: string;
+};
+/**
+ * Sets a control element's inline position/size from a `ControlPlacement`.
+ */
+export declare function applyControlPlacement(element: HTMLElement, placement: ControlPlacement): void;
+/**
+ * The base of every on-screen control: owns one DOM element and follows one pointer on it at a time.
+ * A control is plain DOM with no dependency on a world, so it works inside a `MobileControls` overlay
+ * and equally in an app's own markup - append `element` anywhere.
+ *
+ * A pointer that goes down on the control is captured by it and never reaches the elements below
+ * (the game canvas, a `MouseInput` listening on the window).
+ */
+export declare abstract class TouchControl {
+    readonly element: HTMLElement;
+    readonly id: string | undefined;
+    protected readonly disposed$: Subject<void>;
+    private activePointerId;
+    private _disposed;
+    get disposed(): boolean;
+    /** Whether a pointer is currently down on the control. */
+    get touched(): boolean;
+    get visible(): boolean;
+    /**
+     * Takes the control off the screen (and back) without disposing it, for an action that is not
+     * available at the moment. Hiding releases whatever the control holds.
+     */
+    set visible(value: boolean);
+    /** Moves/resizes the control; edges and sizes left out of `placement` stay as they are. */
+    place(placement: ControlPlacement): void;
+    protected constructor(kind: string, options: TouchControlOptions);
+    /**
+     * Returns the control to its untouched state, releasing whatever it holds (a pressed button, a
+     * deflected stick). A latched toggle button is released too.
+     */
+    reset(): void;
+    /**
+     * Resets the control, completes its observables (ending every binding made through it) and removes
+     * its element from the document.
+     */
+    dispose(): void;
+    protected abstract onPointerStart(event: PointerEvent): void;
+    protected onPointerMove(event: PointerEvent): void;
+    /** `event` is `null` when the control was reset rather than released by the pointer. */
+    protected abstract onPointerEnd(event: PointerEvent | null): void;
+    private handlePointerDown;
+    private handlePointerMove;
+    private handlePointerEnd;
+    private releaseCapture;
+}

package/dist/controls/touch-control.js

@@ -0,0 +1,151 @@
+import { Subject } from 'rxjs';
+const EDGES = ['left', 'right', 'top', 'bottom'];
+/**
+ * Sets a control element's inline position/size from a `ControlPlacement`.
+ */
+export function applyControlPlacement(element, placement) {
+    for (const edge of EDGES) {
+        const value = placement[edge];
+        if (value !== undefined) {
+            element.style.setProperty(edge, typeof value === 'number' ? `calc(var(--gg-mc-unit) * ${value} + env(safe-area-inset-${edge}, 0px))` : value);
+        }
+    }
+    for (const dimension of ['width', 'height']) {
+        const value = placement[dimension];
+        if (value !== undefined) {
+            element.style.setProperty(dimension, typeof value === 'number' ? `calc(var(--gg-mc-unit) * ${value})` : value);
+        }
+    }
+}
+/**
+ * The base of every on-screen control: owns one DOM element and follows one pointer on it at a time.
+ * A control is plain DOM with no dependency on a world, so it works inside a `MobileControls` overlay
+ * and equally in an app's own markup - append `element` anywhere.
+ *
+ * A pointer that goes down on the control is captured by it and never reaches the elements below
+ * (the game canvas, a `MouseInput` listening on the window).
+ */
+export class TouchControl {
+    get disposed() {
+        return this._disposed;
+    }
+    /** Whether a pointer is currently down on the control. */
+    get touched() {
+        return this.activePointerId !== null;
+    }
+    get visible() {
+        return !this.element.hidden;
+    }
+    /**
+     * Takes the control off the screen (and back) without disposing it, for an action that is not
+     * available at the moment. Hiding releases whatever the control holds.
+     */
+    set visible(value) {
+        if (!value) {
+            this.reset();
+        }
+        this.element.hidden = !value;
+    }
+    /** Moves/resizes the control; edges and sizes left out of `placement` stay as they are. */
+    place(placement) {
+        applyControlPlacement(this.element, placement);
+    }
+    constructor(kind, options) {
+        this.disposed$ = new Subject();
+        this.activePointerId = null;
+        this._disposed = false;
+        this.id = options.id;
+        this.element = document.createElement('div');
+        this.element.className = `gg-mc-control gg-mc-${kind}`;
+        if (options.id) {
+            this.element.classList.add(`gg-mc-id-${options.id}`);
+            this.element.dataset.ggMc = options.id;
+        }
+        if (options.className) {
+            this.element.classList.add(...options.className.split(/\s+/).filter(x => !!x));
+        }
+        if (options.label) {
+            this.element.setAttribute('aria-label', options.label);
+        }
+        if (options.placement) {
+            applyControlPlacement(this.element, options.placement);
+        }
+        this.handlePointerDown = this.handlePointerDown.bind(this);
+        this.handlePointerMove = this.handlePointerMove.bind(this);
+        this.handlePointerEnd = this.handlePointerEnd.bind(this);
+        this.element.addEventListener('pointerdown', this.handlePointerDown);
+        this.element.addEventListener('pointermove', this.handlePointerMove);
+        this.element.addEventListener('pointerup', this.handlePointerEnd);
+        this.element.addEventListener('pointercancel', this.handlePointerEnd);
+        this.element.addEventListener('lostpointercapture', this.handlePointerEnd);
+        this.element.addEventListener('contextmenu', e => e.preventDefault());
+        // stops the long-press text selection/magnifier of iOS, which `touch-action` does not cover
+        this.element.addEventListener('touchstart', e => e.preventDefault(), { passive: false });
+    }
+    /**
+     * Returns the control to its untouched state, releasing whatever it holds (a pressed button, a
+     * deflected stick). A latched toggle button is released too.
+     */
+    reset() {
+        if (this.activePointerId !== null) {
+            this.releaseCapture(this.activePointerId);
+            this.activePointerId = null;
+            this.onPointerEnd(null);
+        }
+    }
+    /**
+     * Resets the control, completes its observables (ending every binding made through it) and removes
+     * its element from the document.
+     */
+    dispose() {
+        if (this._disposed) {
+            return;
+        }
+        this.reset();
+        this._disposed = true;
+        this.disposed$.next();
+        this.disposed$.complete();
+        this.element.remove();
+    }
+    onPointerMove(event) { }
+    handlePointerDown(event) {
+        event.preventDefault();
+        event.stopPropagation();
+        if (this.activePointerId !== null || (event.pointerType === 'mouse' && event.button !== 0)) {
+            return;
+        }
+        this.activePointerId = event.pointerId;
+        try {
+            this.element.setPointerCapture(event.pointerId);
+        }
+        catch (err) {
+            // not capturable (a synthetic event, a pointer already gone): the control still works while
+            // the pointer stays over it
+        }
+        this.onPointerStart(event);
+    }
+    handlePointerMove(event) {
+        event.stopPropagation();
+        if (event.pointerId === this.activePointerId) {
+            event.preventDefault();
+            this.onPointerMove(event);
+        }
+    }
+    handlePointerEnd(event) {
+        event.stopPropagation();
+        if (event.pointerId !== this.activePointerId) {
+            return;
+        }
+        this.activePointerId = null;
+        this.releaseCapture(event.pointerId);
+        this.onPointerEnd(event);
+    }
+    releaseCapture(pointerId) {
+        try {
+            this.element.releasePointerCapture(pointerId);
+        }
+        catch (err) {
+            // was not captured
+        }
+    }
+}