@ue-too/board/camera/camera-mux/animation-and-lock/rotation-control-state-machine.d.ts

<h1 align="center"> uē-tôo </h1> <p align="center"> pan, zoom, rotate, and more with your html canvas. </p>

import type { EventReactions, State, BaseContext } from "@ue-too/being";
import { TemplateState, TemplateStateMachine } from "@ue-too/being";
/**
 * State identifiers for the rotation control state machine.
 *
 * @remarks
 * Three states manage rotation input and animations:
 * - `ACCEPTING_USER_INPUT`: Normal state, accepts user rotation input
 * - `TRANSITION`: Animation/transition state, may block user input
 * - `LOCKED_ON_OBJECT`: Camera locked to follow a specific object rotation
 *
 * @category Input Flow Control
 */
export type RotateControlStates = "ACCEPTING_USER_INPUT" | "TRANSITION" | "LOCKED_ON_OBJECT";
/**
 * Payload for rotate-by input events (relative rotation).
 * @category Input Flow Control
 */
export type RotateByInputEventPayload = {
    /** Rotation angle delta in radians */
    diff: number;
};
/**
 * Payload for rotate-to input events (absolute rotation).
 * @category Input Flow Control
 */
export type RotateToInputEventPayload = {
    /** Target rotation angle in radians */
    target: number;
};
/** Empty payload for events that don't need data */
type EmptyPayload = {};
/**
 * Event payload type mapping for the rotation control state machine.
 *
 * @remarks
 * Maps event names to their payload types. Events include:
 * - User input events (`userRotateByInput`, `userRotateToInput`)
 * - Transition/animation events (`transitionRotateByInput`, `transitionRotateToInput`)
 * - Locked object events (`lockedOnObjectRotateByInput`, `lockedOnObjectRotateToInput`)
 * - Control events (`unlock`, `initateTransition`)
 *
 * @category Input Flow Control
 */
export type RotateEventPayloadMapping = {
    "userRotateByInput": RotateByInputEventPayload;
    "userRotateToInput": RotateToInputEventPayload;
    "transitionRotateByInput": RotateByInputEventPayload;
    "transitionRotateToInput": RotateToInputEventPayload;
    "lockedOnObjectRotateByInput": RotateByInputEventPayload;
    "lockedOnObjectRotateToInput": RotateToInputEventPayload;
    "unlock": EmptyPayload;
    "initateTransition": EmptyPayload;
};
/**
 * Discriminated union of output events from rotation control state machine.
 *
 * @remarks
 * Output events instruct the camera system what rotation operation to perform:
 * - `rotateBy`: Relative rotation by delta angle
 * - `rotateTo`: Absolute rotation to target angle
 * - `none`: No operation (input blocked)
 *
 * @category Input Flow Control
 */
export type RotateControlOutputEvent = {
    type: "rotateBy";
    delta: number;
} | {
    type: "rotateTo";
    target: number;
} | {
    type: "none";
};
/**
 * Output event type mapping for rotation control events.
 * Maps input event names to their corresponding output event types.
 *
 * @category Input Flow Control
 */
export type RotateControlOutputMapping = {
    "userRotateByInput": RotateControlOutputEvent;
    "userRotateToInput": RotateControlOutputEvent;
    "transitionRotateByInput": RotateControlOutputEvent;
    "transitionRotateToInput": RotateControlOutputEvent;
    "lockedOnObjectRotateByInput": RotateControlOutputEvent;
    "lockedOnObjectRotateToInput": RotateControlOutputEvent;
};
/**
 * State machine controlling rotation input flow and animations.
 *
 * @remarks
 * This state machine manages the lifecycle of rotation operations:
 * - **User input handling**: Accepts or blocks user rotation gestures based on state
 * - **Animation control**: Manages smooth rotate-to animations
 * - **Object tracking**: Supports locking camera to follow objects with rotation
 *
 * **State transitions:**
 * - `ACCEPTING_USER_INPUT` → `TRANSITION`: Start animation (`initateTransition`)
 * - `ACCEPTING_USER_INPUT` → `LOCKED_ON_OBJECT`: Lock to object (`lockedOnObjectRotate...`)
 * - `TRANSITION` → `ACCEPTING_USER_INPUT`: User input interrupts animation
 * - `LOCKED_ON_OBJECT` → `ACCEPTING_USER_INPUT`: Unlock (`unlock` event)
 *
 * Helper methods simplify event dispatching without memorizing event names.
 *
 * @example
 * ```typescript
 * const stateMachine = createDefaultRotateControlStateMachine(cameraRig);
 *
 * // User rotates - accepted in ACCEPTING_USER_INPUT state
 * const result = stateMachine.notifyRotateByInput(Math.PI / 4);
 *
 * // Start animation - transitions to TRANSITION state
 * stateMachine.notifyRotateToAnimationInput(Math.PI);
 *
 * // User input now blocked while animating
 * ```
 *
 * @category Input Flow Control
 * @see {@link createDefaultRotateControlStateMachine} for factory function
 */
export declare class RotateControlStateMachine extends TemplateStateMachine<RotateEventPayloadMapping, BaseContext, RotateControlStates, RotateControlOutputMapping> {
    constructor(states: Record<RotateControlStates, State<RotateEventPayloadMapping, BaseContext, RotateControlStates, RotateControlOutputMapping>>, initialState: RotateControlStates, context: BaseContext);
    /**
     * Notifies the state machine of user rotation input.
     *
     * @param diff - Rotation angle delta in radians
     * @returns Event handling result with output event
     *
     * @remarks
     * Dispatches `userRotateByInput` event. Accepted in `ACCEPTING_USER_INPUT` and `TRANSITION` states,
     * where it may transition back to `ACCEPTING_USER_INPUT` (user interrupting animation).
     */
    notifyRotateByInput(diff: number): import("@ue-too/being").EventResult<RotateControlStates, RotateControlOutputEvent>;
    /**
     * Initiates a rotation animation to a target angle.
     *
     * @param target - Target rotation angle in radians
     * @returns Event handling result
     *
     * @remarks
     * Dispatches `transitionRotateToInput` event, starting a rotation animation.
     * Transitions to `TRANSITION` state where animation updates occur.
     */
    notifyRotateToAnimationInput(target: number): import("@ue-too/being").EventResult<RotateControlStates, RotateControlOutputEvent>;
    /**
     * Initiates transition to `TRANSITION` state.
     *
     * @remarks
     * Forces state change to begin animation or transition sequence.
     * Called when starting programmatic camera movements.
     */
    initateTransition(): void;
}
/**
 * State implementation for accepting user rotation input (idle/normal state).
 * Accepts user rotation input and can transition to animation or locked states.
 * @category Input Flow Control
 */
export declare class RotationAcceptingUserInputState extends TemplateState<RotateEventPayloadMapping, BaseContext, RotateControlStates, RotateControlOutputMapping> {
    constructor();
    protected _eventReactions: EventReactions<RotateEventPayloadMapping, BaseContext, RotateControlStates, RotateControlOutputMapping>;
    userRotateByInputHandler(context: BaseContext, payload: RotateByInputEventPayload): RotateControlOutputEvent;
    userRotateToInputHandler(context: BaseContext, payload: RotateToInputEventPayload): RotateControlOutputEvent;
    lockedOnObjectRotateByInputHandler(context: BaseContext, payload: RotateByInputEventPayload): RotateControlOutputEvent;
    lockedOnObjectRotateToInputHandler(context: BaseContext, payload: RotateToInputEventPayload): RotateControlOutputEvent;
}
/**
 * State implementation for rotation animations and transitions.
 * Processes animation updates and allows user input to interrupt.
 * @category Input Flow Control
 */
export declare class RotationTransitionState extends TemplateState<RotateEventPayloadMapping, BaseContext, RotateControlStates, RotateControlOutputMapping> {
    constructor();
    protected _eventReactions: EventReactions<RotateEventPayloadMapping, BaseContext, RotateControlStates, RotateControlOutputMapping>;
    userRotateByInputHandler(context: BaseContext, payload: RotateByInputEventPayload): RotateControlOutputEvent;
    userRotateToInputHandler(context: BaseContext, payload: RotateToInputEventPayload): RotateControlOutputEvent;
    transitionRotateByInputHandler(context: BaseContext, payload: RotateByInputEventPayload): RotateControlOutputEvent;
    transitionRotateToInputHandler(context: BaseContext, payload: RotateToInputEventPayload): RotateControlOutputEvent;
    lockedOnObjectRotateByInputHandler(context: BaseContext, payload: RotateByInputEventPayload): RotateControlOutputEvent;
    lockedOnObjectRotateToInputHandler(context: BaseContext, payload: RotateToInputEventPayload): RotateControlOutputEvent;
}
/**
 * State implementation for camera locked to follow an object rotation.
 * Only accepts locked object rotation events until unlocked.
 * @category Input Flow Control
 */
export declare class RotationLockedOnObjectState extends TemplateState<RotateEventPayloadMapping, BaseContext, RotateControlStates, RotateControlOutputMapping> {
    constructor();
    protected _eventReactions: EventReactions<RotateEventPayloadMapping, BaseContext, RotateControlStates, RotateControlOutputMapping>;
    lockedOnObjectRotateByInputHandler(context: BaseContext, payload: RotateByInputEventPayload): RotateControlOutputEvent;
    lockedOnObjectRotateToInputHandler(context: BaseContext, payload: RotateToInputEventPayload): RotateControlOutputEvent;
}
/**
 * Creates the default set of rotation control states.
 * @returns State instances for all rotation control states
 * @category Input Flow Control
 */
export declare function createDefaultRotateControlStates(): Record<RotateControlStates, State<RotateEventPayloadMapping, BaseContext, RotateControlStates, RotateControlOutputMapping>>;
/**
 * Creates a rotation control state machine with default configuration.
 *
 * @param context - Camera rig or context for rotation operations
 * @returns Configured rotation control state machine starting in `ACCEPTING_USER_INPUT` state
 *
 * @remarks
 * Factory function for creating a rotation state machine with sensible defaults.
 * The machine starts in `ACCEPTING_USER_INPUT` state, ready to accept user rotation gestures.
 *
 * @example
 * ```typescript
 * const cameraRig = createDefaultCameraRig(camera);
 * const rotateSM = createDefaultRotateControlStateMachine(cameraRig);
 * ```
 *
 * @category Input Flow Control
 */
export declare function createDefaultRotateControlStateMachine(context?: BaseContext): RotateControlStateMachine;
export {};