@egjs/flicking 4.15.0 → 4.16.0-beta.1

package/dist/control/AxesController.d.ts

@@ -0,0 +1,186 @@
+import Axes, { OnRelease, PanInput } from "@egjs/axes";
+import Flicking from "../Flicking";
+import { ControlParams } from "../types/external";
+import StateMachine from "./StateMachine";
+import State from "./states/State";
+/**
+ * A controller that handles the {@link https://naver.github.io/egjs-axes/ | @egjs/axes} events
+ * @internal
+ */
+declare class AxesController {
+    private _flicking;
+    private _axes;
+    private _panInput;
+    private _stateMachine;
+    private _animatingContext;
+    private _dragged;
+    /**
+     * An {@link https://naver.github.io/egjs-axes/docs/api/Axes | Axes} instance
+     * @see https://naver.github.io/egjs-axes/docs/api/Axes
+     * @readonly
+     */
+    get axes(): Axes | null;
+    /**
+     * An {@link https://naver.github.io/egjs-axes/docs/api/PanInput | PanInput} instance
+     * @see https://naver.github.io/egjs-axes/docs/api/PanInput
+     * @readonly
+     */
+    get panInput(): PanInput | null;
+    /**
+     * @internal
+     */
+    get stateMachine(): StateMachine;
+    /**
+     * A activated {@link State} that shows the current status of the user input or the animation
+     */
+    get state(): State;
+    /**
+     * A context of the current animation playing
+     * @readonly
+     */
+    get animatingContext(): {
+        start: number;
+        end: number;
+        offset: number;
+    };
+    /**
+     * A current control parameters of the Axes instance
+     */
+    get controlParams(): ControlParams;
+    /**
+     * A Boolean indicating whether the user input is enabled
+     * @readonly
+     */
+    get enabled(): boolean;
+    /**
+     * Current position value in {@link https://naver.github.io/egjs-axes/docs/api/Axes | Axes} instance
+     * @readonly
+     */
+    get position(): number;
+    /**
+     * Current range value in {@link https://naver.github.io/egjs-axes/docs/api/Axes | Axes} instance
+     * @readonly
+     */
+    get range(): number[];
+    /**
+     * Actual bounce size(px)
+     * @readonly
+     */
+    get bounce(): number[] | undefined;
+    constructor();
+    /**
+     * Initialize AxesController
+     * @remarks
+     * This method creates and configures the Axes and PanInput instances.
+     * @param flicking - An instance of {@link Flicking}
+     * @returns The current instance for method chaining
+     */
+    init(flicking: Flicking): this;
+    /**
+     * Destroy AxesController and return to initial state
+     * @remarks
+     * This method destroys the Axes and PanInput instances and removes all event handlers.
+     */
+    destroy(): void;
+    /**
+     * Enable input from the user (mouse/touch)
+     * @remarks
+     * Enables the PanInput to receive user interactions.
+     * @returns The current instance for method chaining
+     */
+    enable(): this;
+    /**
+     * Disable input from the user (mouse/touch)
+     * @remarks
+     * Disables the PanInput to ignore user interactions.
+     * @returns The current instance for method chaining
+     */
+    disable(): this;
+    /**
+     * Releases ongoing user input (mouse/touch)
+     * @remarks
+     * Immediately releases the PanInput, simulating the user lifting their finger.
+     * @returns The current instance for method chaining
+     */
+    release(): this;
+    /**
+     * Change the destination and duration of the animation currently playing
+     * @remarks
+     * This method updates the Axes animation target position and optionally the duration.
+     * @param position - A position to move
+     * @param duration - Duration of the animation (unit: ms)
+     * @returns The current instance for method chaining
+     */
+    updateAnimation(position: number, duration?: number): this;
+    /**
+     * Stops the animation currently playing
+     * @remarks
+     * This method immediately stops the Axes animation at the current position.
+     * @returns The current instance for method chaining
+     */
+    stopAnimation(): this;
+    /**
+     * Update {@link https://naver.github.io/egjs-axes/ | @egjs/axes}'s state
+     * @remarks
+     * This method synchronizes the Axes state with the given control parameters.
+     * @param controlParams - Control parameters
+     * @throws {@link InitializationErrors}
+     * @returns The current instance for method chaining
+     */
+    update(controlParams: ControlParams): this;
+    /**
+     * Attach a handler to the camera element to prevent click events during animation
+     * @remarks
+     * This is used when {@link FlickingOptions.preventClickOnDrag | preventClickOnDrag} is enabled.
+     * @returns The current instance for method chaining
+     */
+    addPreventClickHandler(): this;
+    /**
+     * Detach a handler to the camera element to prevent click events during animation
+     * @remarks
+     * This is used when {@link FlickingOptions.preventClickOnDrag | preventClickOnDrag} is disabled.
+     * @returns The current instance for method chaining
+     */
+    removePreventClickHandler(): this;
+    /**
+     * Run Axes's {@link https://naver.github.io/egjs-axes/docs/api/Axes#setTo | setTo} using the given position
+     * @remarks
+     * If the target position equals the current position, the promise resolves immediately without animation.
+     * @param position - A position to move
+     * @param duration - Duration of the animation (unit: ms)
+     * @param axesEvent - If provided, it'll use its {@link https://naver.github.io/egjs-axes/docs/api/Axes#setTo | setTo} method instead
+     * @throws {@link MovementErrors}
+     * @returns A Promise which will be resolved after reaching the target position
+     */
+    animateTo(position: number, duration: number, axesEvent?: OnRelease): Promise<void>;
+    /**
+     * Returns the current axes position
+     */
+    getCurrentPosition(): number;
+    updateDirection(): void;
+    /**
+     * @internal
+     * @privateRemarks
+     * Resets all internal values to their defaults. Called during construction and destruction.
+     */
+    private _resetInternalValues;
+    /**
+     * @internal
+     * @privateRemarks
+     * Handles the Axes hold event to reset the dragged state.
+     */
+    private _onAxesHold;
+    /**
+     * @internal
+     * @privateRemarks
+     * Handles the Axes change event to update the dragged state.
+     */
+    private _onAxesChange;
+    /**
+     * @internal
+     * @privateRemarks
+     * Prevents click events when the user has dragged. Used for {@link FlickingOptions.preventClickOnDrag}.
+     */
+    private _preventClickWhenDragged;
+}
+export default AxesController;

package/dist/control/Control.d.ts

@@ -0,0 +1,185 @@
+import { OnRelease } from "@egjs/axes";
+import { DIRECTION } from "../constants/values";
+import AxesController from "../control/AxesController";
+import Panel from "../core/panel/Panel";
+import Flicking from "../Flicking";
+import { ValueOf } from "../types/internal";
+/**
+ * Parameters for {@link Control.moveToPanel}
+ * @public
+ */
+export interface MoveToPanelParams {
+    /** Duration of the animation (unit: ms) */
+    duration: number;
+    /** Direction to move, only available in the {@link Flicking.circular | circular} mode */
+    direction?: ValueOf<typeof DIRECTION>;
+    /** {@link https://naver.github.io/egjs-axes/docs/api/Axes#event-release | release} event of {@link https://naver.github.io/egjs-axes/ | Axes} */
+    axesEvent?: OnRelease;
+}
+/**
+ * A component that manages inputs and animation of Flicking
+ * @public
+ */
+declare abstract class Control {
+    protected _flicking: Flicking | null;
+    protected _controller: AxesController;
+    protected _activePanel: Panel | null;
+    protected _nextPanel: Panel | null;
+    /**
+     * A controller that handles the {@link https://naver.github.io/egjs-axes/ | @egjs/axes} events
+     * @readonly
+     */
+    get controller(): AxesController;
+    /**
+     * Index number of the {@link Flicking.currentPanel | currentPanel}
+     * @defaultValue 0
+     * @readonly
+     */
+    get activeIndex(): number;
+    /**
+     * An active panel
+     * @readonly
+     */
+    get activePanel(): Panel | null;
+    /**
+     * Whether Flicking's animating
+     * @readonly
+     */
+    get animating(): boolean;
+    /**
+     * Whether user is clicking or touching
+     * @readonly
+     */
+    get holding(): boolean;
+    constructor();
+    /**
+     * Move {@link Camera} to the given position
+     * @param position - The target position to move
+     * @param duration - Duration of the panel movement animation (unit: ms)
+     * @param axesEvent - {@link https://naver.github.io/egjs-axes/docs/api/Axes#event-release | release} event of {@link https://naver.github.io/egjs-axes/ | Axes}
+     * @fires {@link MovementEvents}
+     * @throws {@link MovementErrors}
+     * @returns A Promise which will be resolved after reaching the target position
+     */
+    abstract moveToPosition(position: number, duration: number, axesEvent?: OnRelease): Promise<void>;
+    /**
+     * Initialize Control
+     * @remarks
+     * This method is called automatically during {@link Flicking.init}. It initializes the internal controller.
+     * @param flicking - An instance of {@link Flicking}
+     * @returns The current instance for method chaining
+     */
+    init(flicking: Flicking): this;
+    /**
+     * Destroy Control and return to initial state
+     * @remarks
+     * This method destroys the internal controller and resets all internal values.
+     */
+    destroy(): void;
+    /**
+     * Enable input from the user (mouse/touch)
+     * @remarks
+     * This is a shorthand for `Flicking.enableInput`.
+     * @returns The current instance for method chaining
+     */
+    enable(): this;
+    /**
+     * Disable input from the user (mouse/touch)
+     * @remarks
+     * This is a shorthand for `Flicking.disableInput`.
+     * @returns The current instance for method chaining
+     */
+    disable(): this;
+    /**
+     * Releases ongoing user input (mouse/touch)
+     * @remarks
+     * This method immediately releases the user's input, similar to the user lifting their finger.
+     * @returns The current instance for method chaining
+     */
+    release(): this;
+    /**
+     * Change the destination and duration of the animation currently playing
+     * @remarks
+     * This method does nothing if no animation is currently playing.
+     * @param panel - The target panel to move
+     * @param duration - Duration of the animation (unit: ms)
+     * @param direction - Direction to move, only available in the {@link Flicking.circular | circular} mode
+     * @throws {@link AnimationUpdateErrors}
+     * @returns The current instance for method chaining
+     */
+    updateAnimation(panel: Panel, duration?: number, direction?: ValueOf<typeof DIRECTION>): this;
+    /**
+     * Stops the animation currently playing
+     * @remarks
+     * This method does nothing if no animation is currently playing.
+     * @returns The current instance for method chaining
+     */
+    stopAnimation(): this;
+    /**
+     * Update position after resizing
+     * @remarks
+     * This method moves the camera to the active panel's position after a resize operation.
+     * @param progressInPanel - Previous camera's progress in active panel before resize
+     * @throws {@link InitializationErrors}
+     */
+    updatePosition(progressInPanel: number): void;
+    /**
+     * Update {@link Control.controller | controller}'s state
+     * @remarks
+     * This method synchronizes the controller state with the current camera parameters.
+     * @returns The current instance for method chaining
+     */
+    updateInput(): this;
+    /**
+     * Reset {@link Control.activePanel | activePanel} to `null`
+     * @remarks
+     * This method is called when the active panel is removed from the renderer.
+     * @returns The current instance for method chaining
+     */
+    resetActive(): this;
+    /**
+     * Move {@link Camera} to the given panel
+     * @param panel - The target panel to move
+     * @param options - {@link MoveToPanelParams}
+     * @fires {@link MovementEvents}
+     * @throws {@link MovementErrors}
+     * @returns A Promise which will be resolved after reaching the target panel
+     */
+    moveToPanel(panel: Panel, { duration, direction, axesEvent }: MoveToPanelParams): Promise<void>;
+    /**
+     * @internal
+     * @privateRemarks
+     * Sets the active panel and triggers {@link ChangedEvent} or {@link RestoredEvent} based on whether the panel changed.
+     */
+    setActive(newActivePanel: Panel, prevActivePanel: Panel | null, isTrusted: boolean): void;
+    /**
+     * @internal
+     * @privateRemarks
+     * Copies internal state from another Control instance. Used when changing moveType option.
+     */
+    copy(control: Control): void;
+    /**
+     * @internal
+     * @privateRemarks
+     * Triggers {@link WillChangeEvent} or {@link WillRestoreEvent} based on whether the target panel differs from the active panel.
+     */
+    protected _triggerIndexChangeEvent(panel: Panel, position: number, axesEvent?: OnRelease, direction?: ValueOf<typeof DIRECTION>): void;
+    /**
+     * @internal
+     * @privateRemarks
+     * Animates the camera to the target position and handles animation completion or interruption.
+     */
+    protected _animateToPosition({ position, duration, newActivePanel, axesEvent }: {
+        position: number;
+        duration: number;
+        newActivePanel: Panel;
+        axesEvent?: OnRelease;
+    }): Promise<void>;
+    /**
+     * @internal
+     * @privateRemarks
+     * Calculates the target position for a panel, considering circular mode and direction constraints.
+     */
+    private _getPosition;
+}
+export default Control;

package/dist/control/FreeControl.d.ts

@@ -0,0 +1,44 @@
+import { OnRelease } from "@egjs/axes";
+import Control from "./Control";
+/**
+ * Options for the {@link FreeControl}
+ */
+export interface FreeControlOptions {
+    /** Make scroll animation to stop at the start/end of the scroll area, not going out the bounce area */
+    stopAtEdge: boolean;
+}
+/**
+ * A {@link Control} that can be scrolled freely without alignment
+ * @public
+ */
+declare class FreeControl extends Control {
+    private _stopAtEdge;
+    /**
+     * Make scroll animation to stop at the start/end of the scroll area, not going out the bounce area
+     * @defaultValue true
+     */
+    get stopAtEdge(): boolean;
+    set stopAtEdge(val: FreeControlOptions["stopAtEdge"]);
+    constructor(options?: Partial<FreeControlOptions>);
+    /**
+     * Update position after resizing
+     * @remarks
+     * Unlike the base Control, FreeControl preserves the progress within the panel instead of snapping to the panel position.
+     * @param progressInPanel - Previous camera's progress in active panel before resize
+     * @throws {@link InitializationErrors}
+     */
+    updatePosition(progressInPanel: number): void;
+    /**
+     * Move {@link Camera} to the given position
+     * @remarks
+     * Unlike SnapControl, FreeControl moves to the exact position without snapping to panel boundaries.
+     * @param position - The target position to move
+     * @param duration - Duration of the panel movement animation (unit: ms)
+     * @param axesEvent - {@link https://naver.github.io/egjs-axes/docs/api/Axes#event-release | release} event of {@link https://naver.github.io/egjs-axes/ | Axes}
+     * @fires {@link MovementEvents}
+     * @throws {@link MovementErrors}
+     * @returns A Promise which will be resolved after reaching the target position
+     */
+    moveToPosition(position: number, duration: number, axesEvent?: OnRelease): Promise<void>;
+}
+export default FreeControl;

package/dist/control/SnapControl.d.ts

@@ -0,0 +1,54 @@
+import { OnRelease } from "@egjs/axes";
+import Control from "./Control";
+/**
+ * Options for the {@link SnapControl}
+ */
+export interface SnapControlOptions {
+    /** Maximum number of panels can go after release */
+    count: number;
+}
+/**
+ * A {@link Control} that uses a release momentum to choose destination panel
+ * @public
+ */
+declare class SnapControl extends Control {
+    private _count;
+    /**
+     * Maximum number of panels can go after release
+     * @defaultValue Infinity
+     */
+    get count(): number;
+    set count(val: SnapControlOptions["count"]);
+    constructor(options?: Partial<SnapControlOptions>);
+    /**
+     * Move {@link Camera} to the given position
+     * @remarks
+     * This method calculates the snap target based on the release momentum and threshold settings.
+     * @param position - The target position to move
+     * @param duration - Duration of the panel movement animation (unit: ms)
+     * @param axesEvent - {@link https://naver.github.io/egjs-axes/docs/api/Axes#event-release | release} event of {@link https://naver.github.io/egjs-axes/ | Axes}
+     * @fires {@link MovementEvents}
+     * @throws {@link MovementErrors}
+     * @returns A Promise which will be resolved after reaching the target position
+     */
+    moveToPosition(position: number, duration: number, axesEvent?: OnRelease): Promise<void>;
+    /**
+     * @internal
+     * @privateRemarks
+     * Finds the anchor point to snap to based on the target position and count option.
+     */
+    private _findSnappedAnchor;
+    /**
+     * @internal
+     * @privateRemarks
+     * Finds the adjacent anchor point based on the movement direction.
+     */
+    private _findAdjacentAnchor;
+    /**
+     * @internal
+     * @privateRemarks
+     * Calculates the snap threshold based on the panel size and alignment.
+     */
+    private _calcSnapThreshold;
+}
+export default SnapControl;

package/{declaration → dist}/control/StateMachine.d.ts

@@ -1,6 +1,9 @@
 import { AxesEvents } from "@egjs/axes";
 import Flicking from "../Flicking";
 import State, { STATE_TYPE } from "./states/State";
+/**
+ * @internal
+ */
 declare class StateMachine {
     private _state;
     get state(): State;

package/dist/control/StrictControl.d.ts

@@ -0,0 +1,60 @@
+import { OnRelease } from "@egjs/axes";
+import Panel from "../core/panel/Panel";
+import Control, { MoveToPanelParams } from "./Control";
+/**
+ * Options for the {@link StrictControl}
+ */
+export interface StrictControlOptions {
+    /** Maximum number of panels that can be moved at a time */
+    count: number;
+}
+/**
+ * A {@link Control} that allows you to select the maximum number of panels to move at a time
+ * @since 4.2.0
+ * @public
+ */
+declare class StrictControl extends Control {
+    private _count;
+    private _indexRange;
+    /**
+     * Maximum number of panels that can be moved at a time
+     * @defaultValue 1
+     */
+    get count(): number;
+    set count(val: StrictControlOptions["count"]);
+    constructor(options?: Partial<StrictControlOptions>);
+    /**
+     * Destroy Control and return to initial state
+     * @remarks
+     * This method also resets the index range used for movement constraints.
+     */
+    destroy(): void;
+    /**
+     * Update {@link Control.controller | controller}'s state
+     * @remarks
+     * StrictControl limits the movement range based on the {@link StrictControlOptions.count | count} option.
+     * @returns The current instance for method chaining
+     */
+    updateInput(): this;
+    moveToPanel(panel: Panel, options: MoveToPanelParams): Promise<void>;
+    /**
+     * Move {@link Camera} to the given position
+     * @remarks
+     * StrictControl restricts movement to panels within the allowed index range based on the count option.
+     * @param position - The target position to move
+     * @param duration - Duration of the panel movement animation (unit: ms)
+     * @param axesEvent - {@link https://naver.github.io/egjs-axes/docs/api/Axes#event-release | release} event of {@link https://naver.github.io/egjs-axes/ | Axes}
+     * @fires {@link MovementEvents}
+     * @throws {@link MovementErrors}
+     * @returns A Promise which will be resolved after reaching the target position
+     */
+    moveToPosition(position: number, duration: number, axesEvent?: OnRelease): Promise<void>;
+    setActive: (newActivePanel: Panel, prevActivePanel: Panel | null, isTrusted: boolean) => void;
+    /**
+     * @internal
+     * @privateRemarks
+     * Resets the index range to default values.
+     */
+    private _resetIndexRange;
+}
+export default StrictControl;

package/{declaration → dist}/control/states/AnimatingState.d.ts

@@ -1,6 +1,18 @@
 import State from "./State";
+/**
+ * A state that activates when Flicking's animating by user input or method call
+ * @internal
+ */
 declare class AnimatingState extends State {
+    /**
+     * Whether user is clicking or touching
+     * @readonly
+     */
     readonly holding = false;
+    /**
+     * Whether Flicking's animating
+     * @readonly
+     */
     readonly animating = true;
     onHold(ctx: Parameters<State["onHold"]>[0]): void;
     onChange(ctx: Parameters<State["onChange"]>[0]): void;

package/{declaration → dist}/control/states/DisabledState.d.ts

@@ -1,6 +1,18 @@
 import State from "./State";
+/**
+ * A state that activates when Flicking is stopped by event's `stop` method
+ * @internal
+ */
 declare class DisabledState extends State {
+    /**
+     * Whether user is clicking or touching
+     * @readonly
+     */
     readonly holding = false;
+    /**
+     * Whether Flicking's animating
+     * @readonly
+     */
     readonly animating = true;
     onAnimationEnd(ctx: Parameters<State["onAnimationEnd"]>[0]): void;
     onChange(ctx: Parameters<State["onChange"]>[0]): void;

package/{declaration → dist}/control/states/DraggingState.d.ts

@@ -1,6 +1,18 @@
 import State from "./State";
+/**
+ * A state that activates when user's dragging the Flicking area
+ * @internal
+ */
 declare class DraggingState extends State {
+    /**
+     * Whether user is clicking or touching
+     * @readonly
+     */
     readonly holding = true;
+    /**
+     * Whether Flicking's animating
+     * @readonly
+     */
     readonly animating = true;
     onChange(ctx: Parameters<State["onChange"]>[0]): void;
     onRelease(ctx: Parameters<State["onRelease"]>[0]): void;

package/{declaration → dist}/control/states/HoldingState.d.ts

@@ -1,6 +1,18 @@
 import State from "./State";
+/**
+ * A state that activates when user's holding the Flicking area, but not moved a single pixel yet
+ * @internal
+ */
 declare class HoldingState extends State {
+    /**
+     * Whether user is clicking or touching
+     * @readonly
+     */
     readonly holding = true;
+    /**
+     * Whether Flicking's animating
+     * @readonly
+     */
     readonly animating = false;
     private _releaseEvent;
     onChange(ctx: Parameters<State["onChange"]>[0]): void;

package/{declaration → dist}/control/states/IdleState.d.ts

@@ -1,6 +1,18 @@
 import State from "./State";
+/**
+ * A default state when there's no user input and no animation's playing
+ * @internal
+ */
 declare class IdleState extends State {
+    /**
+     * Whether user is clicking or touching
+     * @readonly
+     */
     readonly holding = false;
+    /**
+     * Whether Flicking's animating
+     * @readonly
+     */
     readonly animating = false;
     onEnter(): void;
     onHold(ctx: Parameters<State["onHold"]>[0]): void;