@ue-too/board
Version:
<h1 align="center"> uē-tôo </h1> <p align="center"> pan, zoom, rotate, and more with your html canvas. </p>
288 lines (287 loc) • 12.9 kB
TypeScript
import type { State, EventReactions, BaseContext } from "@ue-too/being";
import { TemplateState, TemplateStateMachine } from "@ue-too/being";
import { Point } from "@ue-too/math";
/**
* State identifiers for the zoom control state machine.
*
* @remarks
* Three states manage zoom input and animations:
* - `ACCEPTING_USER_INPUT`: Normal state, accepts user zoom input
* - `TRANSITION`: Animation/transition state, may block user input
* - `LOCKED_ON_OBJECT`: Camera locked to follow a specific object with zoom
*
* @category Input Flow Control
*/
export type ZoomControlStates = "ACCEPTING_USER_INPUT" | "TRANSITION" | "LOCKED_ON_OBJECT";
/**
* Payload for zoom-by-at input events (relative zoom around a point).
* @category Input Flow Control
*/
export type ZoomByAtInputPayload = {
/** Zoom delta amount (multiplier) */
deltaZoom: number;
/** Anchor point for zoom operation */
anchorPoint: Point;
};
/**
* Payload for zoom-to-at input events (absolute zoom to target around a point).
* @category Input Flow Control
*/
export type ZoomToAtInputPayload = {
/** Target zoom level */
targetZoom: number;
/** Anchor point for zoom operation */
anchorPoint: Point;
};
/**
* Payload for zoom-by input events (relative zoom without anchor).
* @category Input Flow Control
*/
export type ZoomByPayload = {
/** Zoom delta amount (multiplier) */
deltaZoom: number;
};
/**
* Payload for zoom-to input events (absolute zoom to target level).
* @category Input Flow Control
*/
export type ZoomToPayload = {
/** Target zoom level */
targetZoom: number;
};
/**
* Event payload type mapping for the zoom control state machine.
*
* @remarks
* Maps event names to their payload types. Events include:
* - User input events (`userZoomByAtInput`, `userZoomToAtInput`)
* - Transition/animation events (`transitionZoomByAtInput`, `transitionZoomToAtInput`, etc.)
* - Locked object events (`lockedOnObjectZoomByAtInput`, `lockedOnObjectZoomToAtInput`)
* - Control events (`unlock`, `initiateTransition`)
*
* @category Input Flow Control
*/
export type ZoomEventPayloadMapping = {
"userZoomByAtInput": ZoomByAtInputPayload;
"userZoomToAtInput": ZoomToAtInputPayload;
"transitionZoomByAtInput": ZoomByAtInputPayload;
"transitionZoomToAtInput": ZoomToAtInputPayload;
"transitionZoomByAtCenterInput": ZoomByPayload;
"transitionZoomToAtCenterInput": ZoomToAtInputPayload;
"transitionZoomToAtWorldInput": ZoomToAtInputPayload;
"lockedOnObjectZoomByAtInput": ZoomByAtInputPayload;
"lockedOnObjectZoomToAtInput": ZoomToAtInputPayload;
"unlock": {};
"initiateTransition": {};
};
/**
* Discriminated union of output events from zoom control state machine.
*
* @remarks
* Output events instruct the camera system what zoom operation to perform:
* - `zoomByAt`: Relative zoom around anchor point
* - `zoomToAt`: Absolute zoom to target level around anchor point
* - `zoomBy`: Relative zoom without anchor
* - `zoomTo`: Absolute zoom to target level without anchor
* - `zoomByAtWorld`: Relative zoom around world anchor point
* - `zoomToAtWorld`: Absolute zoom to target level around world anchor point
* - `none`: No operation (input blocked)
*
* @category Input Flow Control
*/
export type ZoomControlOutputEvent = {
type: "zoomByAt";
deltaZoom: number;
anchorPoint: Point;
} | {
type: "zoomToAt";
targetZoom: number;
anchorPoint: Point;
} | {
type: "zoomBy";
deltaZoom: number;
} | {
type: "zoomTo";
targetZoom: number;
} | {
type: "zoomByAtWorld";
deltaZoom: number;
anchorPoint: Point;
} | {
type: "zoomToAtWorld";
targetZoom: number;
anchorPoint: Point;
} | {
type: "none";
};
/**
* Output event type mapping for zoom control events.
* Maps input event names to their corresponding output event types.
*
* @category Input Flow Control
*/
export type ZoomControlOutputMapping = {
"userZoomByAtInput": ZoomControlOutputEvent;
"userZoomToAtInput": ZoomControlOutputEvent;
"transitionZoomByAtInput": ZoomControlOutputEvent;
"transitionZoomToAtInput": ZoomControlOutputEvent;
"transitionZoomByAtCenterInput": ZoomControlOutputEvent;
"transitionZoomToAtCenterInput": ZoomControlOutputEvent;
"transitionZoomToAtWorldInput": ZoomControlOutputEvent;
"lockedOnObjectZoomByAtInput": ZoomControlOutputEvent;
"lockedOnObjectZoomToAtInput": ZoomControlOutputEvent;
};
/**
* State implementation for accepting user zoom input (idle/normal state).
* Accepts user zoom input and can transition to animation or locked states.
* @category Input Flow Control
*/
export declare class ZoomAcceptingUserInputState extends TemplateState<ZoomEventPayloadMapping, BaseContext, ZoomControlStates, ZoomControlOutputMapping> {
protected _eventReactions: EventReactions<ZoomEventPayloadMapping, BaseContext, ZoomControlStates, ZoomControlOutputMapping>;
userZoomByAtInput(context: BaseContext, payload: ZoomEventPayloadMapping["userZoomByAtInput"]): ZoomControlOutputEvent;
userZoomToAtInput(context: BaseContext, payload: ZoomEventPayloadMapping["userZoomToAtInput"]): ZoomControlOutputEvent;
}
/**
* State implementation for zoom animations and transitions.
* Processes animation updates and allows user input to interrupt.
* @category Input Flow Control
*/
export declare class ZoomTransitionState extends TemplateState<ZoomEventPayloadMapping, BaseContext, ZoomControlStates, ZoomControlOutputMapping> {
constructor();
protected _eventReactions: EventReactions<ZoomEventPayloadMapping, BaseContext, ZoomControlStates, ZoomControlOutputMapping>;
lockedOnObjectZoomByAtInput(context: BaseContext, payload: ZoomEventPayloadMapping["lockedOnObjectZoomByAtInput"]): ZoomControlOutputEvent;
lockedOnObjectZoomToAtInput(context: BaseContext, payload: ZoomEventPayloadMapping["lockedOnObjectZoomToAtInput"]): ZoomControlOutputEvent;
userZoomByAtInput(context: BaseContext, payload: ZoomEventPayloadMapping["userZoomByAtInput"]): ZoomControlOutputEvent;
userZoomToAtInput(context: BaseContext, payload: ZoomEventPayloadMapping["userZoomToAtInput"]): ZoomControlOutputEvent;
transitionZoomByAtInput(context: BaseContext, payload: ZoomEventPayloadMapping["transitionZoomByAtInput"]): ZoomControlOutputEvent;
transitionZoomByAtCenterInput(context: BaseContext, payload: ZoomEventPayloadMapping["transitionZoomByAtCenterInput"]): ZoomControlOutputEvent;
transitionZoomToAtInput(context: BaseContext, payload: ZoomEventPayloadMapping["transitionZoomToAtInput"]): ZoomControlOutputEvent;
transitionZoomToAtCenterInput(context: BaseContext, payload: ZoomEventPayloadMapping["transitionZoomToAtCenterInput"]): ZoomControlOutputEvent;
transitionZoomToAtWorldInput(context: BaseContext, payload: ZoomEventPayloadMapping["transitionZoomToAtWorldInput"]): ZoomControlOutputEvent;
}
/**
* State implementation for camera locked to follow an object with zoom.
* Accepts locked object zoom events and user input to unlock.
* @category Input Flow Control
*/
export declare class ZoomLockedOnObjectState extends TemplateState<ZoomEventPayloadMapping, BaseContext, ZoomControlStates, ZoomControlOutputMapping> {
constructor();
protected _eventReactions: EventReactions<ZoomEventPayloadMapping, BaseContext, ZoomControlStates, ZoomControlOutputMapping>;
lockedOnObjectZoomByAtInput(context: BaseContext, payload: ZoomEventPayloadMapping["lockedOnObjectZoomByAtInput"]): ZoomControlOutputEvent;
lockedOnObjectZoomToAtInput(context: BaseContext, payload: ZoomEventPayloadMapping["lockedOnObjectZoomToAtInput"]): ZoomControlOutputEvent;
userZoomByAtInput(context: BaseContext, payload: ZoomEventPayloadMapping["userZoomByAtInput"]): ZoomControlOutputEvent;
userZoomToAtInput(context: BaseContext, payload: ZoomEventPayloadMapping["userZoomToAtInput"]): ZoomControlOutputEvent;
}
/**
* State machine controlling zoom input flow and animations.
*
* @remarks
* This state machine manages the lifecycle of zoom operations:
* - **User input handling**: Accepts or blocks user zoom gestures based on state
* - **Animation control**: Manages smooth zoom-to animations
* - **Object tracking**: Supports locking camera to follow objects with zoom
*
* **State transitions:**
* - `ACCEPTING_USER_INPUT` → `TRANSITION`: Start animation (`initiateTransition`)
* - `ACCEPTING_USER_INPUT` → `LOCKED_ON_OBJECT`: Lock to object (`lockedOnObjectZoom...`)
* - `TRANSITION` → `ACCEPTING_USER_INPUT`: User input interrupts animation
* - `LOCKED_ON_OBJECT` → `ACCEPTING_USER_INPUT`: User input unlocks
*
* Helper methods simplify event dispatching without memorizing event names.
*
* @example
* ```typescript
* const stateMachine = createDefaultZoomControlStateMachine(cameraRig);
*
* // User zooms - accepted in ACCEPTING_USER_INPUT state
* const result = stateMachine.notifyZoomByAtInput(1.2, { x: 400, y: 300 });
*
* // Start animation - transitions to TRANSITION state
* stateMachine.notifyZoomToAtWorldInput(2.0, { x: 1000, y: 500 });
*
* // User input now may interrupt animation
* ```
*
* @category Input Flow Control
* @see {@link createDefaultZoomControlStateMachine} for factory function
*/
export declare class ZoomControlStateMachine extends TemplateStateMachine<ZoomEventPayloadMapping, BaseContext, ZoomControlStates, ZoomControlOutputMapping> {
constructor(states: Record<ZoomControlStates, State<ZoomEventPayloadMapping, BaseContext, ZoomControlStates, ZoomControlOutputMapping>>, initialState: ZoomControlStates, context: BaseContext);
/**
* Notifies the state machine of user zoom input around an anchor point.
*
* @param delta - Zoom delta (multiplier)
* @param at - Anchor point for zoom
* @returns Event handling result with output event
*
* @remarks
* Dispatches `userZoomByAtInput` event. Accepted in `ACCEPTING_USER_INPUT` and `TRANSITION` states.
*/
notifyZoomByAtInput(delta: number, at: Point): import("@ue-too/being").EventResult<ZoomControlStates, ZoomControlOutputEvent>;
/**
* Initiates a zoom animation around an anchor point.
*
* @param delta - Zoom delta (multiplier)
* @param at - Anchor point for zoom
* @returns Event handling result
*
* @remarks
* Dispatches `transitionZoomByAtInput` event, starting a zoom animation.
*/
notifyZoomByAtInputAnimation(delta: number, at: Point): import("@ue-too/being").EventResult<ZoomControlStates, ZoomControlOutputEvent>;
/**
* Initiates a zoom animation to target level around center anchor.
*
* @param targetZoom - Target zoom level
* @param at - Anchor point for zoom
* @returns Event handling result
*
* @remarks
* Dispatches `transitionZoomToAtCenterInput` event for center-anchored zoom animation.
*/
notifyZoomToAtCenterInput(targetZoom: number, at: Point): import("@ue-too/being").EventResult<ZoomControlStates, ZoomControlOutputEvent>;
/**
* Initiates a zoom animation to target level around world anchor.
*
* @param targetZoom - Target zoom level
* @param at - World anchor point for zoom
* @returns Event handling result
*
* @remarks
* Dispatches `transitionZoomToAtWorldInput` event for world-anchored zoom animation.
*/
notifyZoomToAtWorldInput(targetZoom: number, at: Point): import("@ue-too/being").EventResult<ZoomControlStates, ZoomControlOutputEvent>;
/**
* Initiates transition to `TRANSITION` state.
*
* @remarks
* Forces state change to begin animation or transition sequence.
* Called when starting programmatic camera movements.
*/
initateTransition(): import("@ue-too/being").EventResult<ZoomControlStates, void>;
}
/**
* Creates the default set of zoom control states.
* @returns State instances for all zoom control states
* @category Input Flow Control
*/
export declare function createDefaultZoomControlStates(): Record<ZoomControlStates, State<ZoomEventPayloadMapping, BaseContext, ZoomControlStates, ZoomControlOutputMapping>>;
/**
* Creates a zoom control state machine with default configuration.
*
* @param context - Camera rig or context for zoom operations
* @returns Configured zoom control state machine starting in `ACCEPTING_USER_INPUT` state
*
* @remarks
* Factory function for creating a zoom state machine with sensible defaults.
* The machine starts in `ACCEPTING_USER_INPUT` state, ready to accept user zoom gestures.
*
* @example
* ```typescript
* const cameraRig = createDefaultCameraRig(camera);
* const zoomSM = createDefaultZoomControlStateMachine(cameraRig);
* ```
*
* @category Input Flow Control
*/
export declare function createDefaultZoomControlStateMachine(context?: BaseContext): ZoomControlStateMachine;