manim-web 0.30.0 → 0.31.0

package/dist/interaction/KeyboardInput.d.ts

@@ -0,0 +1,210 @@
+/**
+ * KeyboardInput — a general-purpose keyboard controller for interactive apps
+ * and games.
+ *
+ * manim-web already has pointer interaction (`Clickable` / `Draggable` /
+ * `Hoverable`) and a `StateMachine`, but no general keyboard primitive. This
+ * controller tracks held keys, exposes per-frame edge queries (`wasPressed` /
+ * `wasReleased`), derives a movement vector from arrow keys and WASD, and binds
+ * a key to a `StateMachine` input or a `ValueTracker`. It makes the kind of
+ * interactive software and games that plain Manim cannot do first-class in the
+ * browser.
+ *
+ * All DOM access is feature-detected, so the controller is safe to construct
+ * in Node, jsdom, or a headless render. Without a window the reads return
+ * `false` or zero and never throw.
+ *
+ * @example
+ * ```typescript
+ * const keys = new KeyboardInput({ preventDefault: true });
+ * // In the render loop, each frame:
+ * function frame(dt: number): void {
+ *   const [dx, dy] = keys.getDirectionVector();
+ *   player.shift([dx * speed * dt, dy * speed * dt, 0]);
+ *   if (keys.wasPressed('Space')) player.jump();
+ *   keys.endFrame(); // clear the per-frame pressed/released edges
+ * }
+ * ```
+ */
+/** A per-key or wildcard callback. `key` is the normalized key name. */
+export type KeyCallback = (key: string, event: KeyboardEvent) => void;
+/** Unsubscribe from a callback registration. */
+export type Unsubscribe = () => void;
+/**
+ * Minimal view of a `StateMachine` for binding. Both `StateMachine.setInput`
+ * and `StateMachine.fire` match this, so no import of the class is needed.
+ */
+export interface StateMachineInputSink {
+    setInput(name: string, value: boolean | number): unknown;
+    fire(name: string): unknown;
+}
+/** Minimal view of a `ValueTracker` for binding. */
+export interface ValueSink {
+    setValue(value: number): unknown;
+}
+/** Options for a {@link KeyboardInput}. */
+export interface KeyboardInputOptions {
+    /**
+     * Call `preventDefault()` on handled key events. `true` applies to every
+     * key; an array restricts it to the listed (normalized) keys. Use it so game
+     * keys such as the arrows and Space do not scroll the page. Default `false`.
+     */
+    preventDefault?: boolean | string[];
+    /**
+     * Attach the listeners immediately on construction. Set `false` to attach
+     * later with {@link KeyboardInput.enable}. Default `true`.
+     */
+    autoEnable?: boolean;
+}
+/** Options for {@link KeyboardInput.bindValue}. */
+export interface BindValueOptions {
+    /** Value written to the tracker while the key is held. */
+    heldValue: number;
+    /** Value written when the key is released. Default `0`. */
+    releasedValue?: number;
+}
+/**
+ * Normalize a raw `KeyboardEvent.key` or a user query to a canonical,
+ * lowercase name. `'ArrowUp'`, `'W'`, and `' '` become `'arrowup'`, `'w'`, and
+ * `'space'`, so a held key reads back under any common spelling.
+ * @param key - A raw key name.
+ * @returns The canonical key name.
+ */
+export declare function normalizeKey(key: string): string;
+/**
+ * Tracks keyboard state for interactive apps and games. Mirrors the
+ * `Clickable` / `OrbitControls` lifecycle: construct, then
+ * {@link enable} / {@link disable} / {@link dispose}.
+ */
+export declare class KeyboardInput {
+    private readonly _target;
+    private readonly _preventDefault;
+    private readonly _down;
+    private readonly _pressed;
+    private readonly _released;
+    private readonly _downCallbacks;
+    private readonly _upCallbacks;
+    private _enabled;
+    private readonly _onKeyDown;
+    private readonly _onKeyUp;
+    /**
+     * Create a KeyboardInput.
+     * @param options - Behavior options.
+     * @param domTarget - Event target for key events. Defaults to `window` (or
+     *   `document`), or `null` when no DOM is present.
+     */
+    constructor(options?: KeyboardInputOptions, domTarget?: EventTarget | null);
+    /** Whether the listeners are attached. */
+    get isEnabled(): boolean;
+    /** Whether a DOM target is available. `false` in a headless environment. */
+    get hasTarget(): boolean;
+    /**
+     * Attach the key listeners. A no-op when already enabled or headless.
+     */
+    enable(): void;
+    /**
+     * Detach the key listeners and clear all held and edge state, so no key stays
+     * stuck. Reads return defaults until {@link enable} is called again.
+     */
+    disable(): void;
+    /**
+     * Detach listeners and drop every registered callback. Use when the
+     * controller is no longer needed.
+     */
+    dispose(): void;
+    /** Clear held keys and both per-frame edge sets. */
+    clear(): void;
+    /**
+     * Whether the key is held right now.
+     * @param key - A key name in any common spelling (`'ArrowUp'`, `'w'`, `' '`).
+     */
+    isKeyDown(key: string): boolean;
+    /** Whether any key is held right now. */
+    anyKeyDown(): boolean;
+    /**
+     * Whether the key went down during the current frame. Cleared by
+     * {@link update} / {@link endFrame}. Key auto-repeat does not re-fire it.
+     * @param key - A key name in any common spelling.
+     */
+    wasPressed(key: string): boolean;
+    /**
+     * Whether the key came up during the current frame. Cleared by
+     * {@link update} / {@link endFrame}.
+     * @param key - A key name in any common spelling.
+     */
+    wasReleased(key: string): boolean;
+    /**
+     * The raw movement axes from the arrow keys and WASD, each component in
+     * `{-1, 0, 1}`. Up is +y and right is +x; opposite keys cancel.
+     * @returns `[x, y]`.
+     */
+    getAxis(): [number, number];
+    /**
+     * The movement vector from {@link getAxis}, normalized to unit length so a
+     * diagonal is not faster than a straight line. A zero axis stays `[0, 0]`.
+     * @returns `[x, y]`.
+     */
+    getDirectionVector(): [number, number];
+    /**
+     * Register a key-down callback. Repeated auto-repeat events do not re-fire it.
+     * @param key - A key name, or `'any'` for every key.
+     * @param callback - Called with the normalized key and the event.
+     * @returns An unsubscribe function.
+     */
+    onKeyDown(key: string, callback: KeyCallback): Unsubscribe;
+    /**
+     * Register a key-up callback.
+     * @param key - A key name, or `'any'` for every key.
+     * @param callback - Called with the normalized key and the event.
+     * @returns An unsubscribe function.
+     */
+    onKeyUp(key: string, callback: KeyCallback): Unsubscribe;
+    /**
+     * Hold a `StateMachine` bool input to match a key: `true` while held, `false`
+     * on release.
+     * @param machine - The `StateMachine` (or any {@link StateMachineInputSink}).
+     * @param inputName - The bool input name.
+     * @param key - The key to track.
+     * @returns An unsubscribe function.
+     */
+    bindBool(machine: StateMachineInputSink, inputName: string, key: string): Unsubscribe;
+    /**
+     * Fire a `StateMachine` trigger input on each key-down.
+     * @param machine - The `StateMachine` (or any {@link StateMachineInputSink}).
+     * @param triggerName - The trigger input name.
+     * @param key - The key to track.
+     * @returns An unsubscribe function.
+     */
+    bindTrigger(machine: StateMachineInputSink, triggerName: string, key: string): Unsubscribe;
+    /**
+     * Drive a `ValueTracker` from a key: `heldValue` while held, `releasedValue`
+     * on release.
+     * @param tracker - The `ValueTracker` (or any {@link ValueSink}).
+     * @param key - The key to track.
+     * @param options - The held and released values.
+     * @returns An unsubscribe function.
+     */
+    bindValue(tracker: ValueSink, key: string, options: BindValueOptions): Unsubscribe;
+    /**
+     * Clear the per-frame pressed and released edge sets. Call once per frame
+     * after reading {@link wasPressed} / {@link wasReleased}.
+     * @param _dt - Delta time (seconds), accepted for render-loop compatibility.
+     */
+    update(_dt?: number): void;
+    /** Alias of {@link update} that clears the per-frame edge sets. */
+    endFrame(): void;
+    private _anyDown;
+    private _handleKeyDown;
+    private _handleKeyUp;
+    private _maybePreventDefault;
+    private _addCallback;
+    private _emit;
+}
+/**
+ * Factory for a {@link KeyboardInput}.
+ * @param options - Behavior options.
+ * @param domTarget - Event target for key events.
+ * @returns A new KeyboardInput.
+ */
+export declare function makeKeyboardInput(options?: KeyboardInputOptions, domTarget?: EventTarget | null): KeyboardInput;
+//# sourceMappingURL=KeyboardInput.d.ts.map

package/dist/interaction/KeyboardInput.d.ts.map

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

package/dist/interaction/index.d.ts

@@ -12,6 +12,7 @@ export { Slider, makeSlider, type SliderOptions } from './Slider';
 export { MatrixTracker, makeMatrixTracker, applyMatrixLive, type Matrix2x2, type MatrixSource, type BasisVectorSource, type DependentPoint, type DynamicMatrixOptions, type LiveMatrixBinding, } from './DynamicMatrix';
 export { SelectionManager, type SelectionManagerOptions } from './SelectionManager';
 export { StateMachine, GuardBuilder, when, allOf, anyOf, type InputValue, type InputKind, type InputsSnapshot, type Guard, type StateContext, type StateAction, type StateConfig, type TransitionConfig, type StateMachineOptions, } from './StateMachine';
+export { KeyboardInput, makeKeyboardInput, normalizeKey, type KeyboardInputOptions, type KeyCallback, type Unsubscribe, type StateMachineInputSink, type ValueSink, type BindValueOptions, } from './KeyboardInput';
 export { OrbitControls, type OrbitControlsOptions } from './OrbitControls';
 export { PanZoomControls, makePanZoomControls, type PanZoomControlsOptions, type PanZoomCamera, type PanZoomBounds, } from './PanZoomControls';
 //# sourceMappingURL=index.d.ts.map

package/dist/interaction/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/interaction/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,QAAQ,EACR,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,iBAAiB,GACvB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,gBAAgB,EAChB,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,GACxB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG9E,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC1F,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AAGlE,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,GACvB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAGpF,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,IAAI,EACJ,KAAK,EACL,KAAK,EACL,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,KAAK,EACV,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,GACzB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC3E,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,KAAK,sBAAsB,EAC3B,KAAK,aAAa,EAClB,KAAK,aAAa,GACnB,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/interaction/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,QAAQ,EACR,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,iBAAiB,GACvB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,gBAAgB,EAChB,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,GACxB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAG9E,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC1F,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AAGlE,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,GACvB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAGpF,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,IAAI,EACJ,KAAK,EACL,KAAK,EACL,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,KAAK,EACV,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,GACzB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,KAAK,oBAAoB,EACzB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,qBAAqB,EAC1B,KAAK,SAAS,EACd,KAAK,gBAAgB,GACtB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC3E,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,KAAK,sBAAsB,EAC3B,KAAK,aAAa,EAClB,KAAK,aAAa,GACnB,MAAM,mBAAmB,CAAC"}