@egjs/flicking 4.15.0 → 4.16.0-beta.1

package/dist/camera/Camera.d.ts

@@ -0,0 +1,324 @@
+import { ORDER } from "../constants/values";
+import AnchorPoint from "../core/AnchorPoint";
+import Panel from "../core/panel/Panel";
+import Flicking, { FlickingOptions } from "../Flicking";
+import { ValueOf } from "../types/internal";
+import { CameraMode } from "./mode";
+export interface CameraOptions {
+    align: FlickingOptions["align"];
+}
+/**
+ * A range with minimum and maximum values
+ */
+export interface CameraRange {
+    /** A minimum position */
+    min: number;
+    /** A maximum position */
+    max: number;
+}
+/**
+ * A component that manages actual movement inside the viewport
+ * @public
+ */
+declare class Camera {
+    private _align;
+    private _flicking;
+    private _mode;
+    private _el;
+    private _transform;
+    private _lookedOffset;
+    private _position;
+    private _alignPos;
+    private _offset;
+    private _circularOffset;
+    private _circularEnabled;
+    private _range;
+    private _visiblePanels;
+    private _anchors;
+    private _needPanelTriggered;
+    private _panelOrder;
+    /**
+     * The camera element(`.flicking-camera`)
+     * @readonly
+     */
+    get element(): HTMLElement;
+    /**
+     * An array of the child elements of the camera element(`.flicking-camera`)
+     * @readonly
+     */
+    get children(): HTMLElement[];
+    /**
+     * Current position of the camera
+     * @readonly
+     */
+    get position(): number;
+    /**
+     * Align position inside the viewport where {@link Panel}'s {@link Panel.alignPosition | alignPosition} should be located at
+     * @readonly
+     */
+    get alignPosition(): number;
+    /**
+     * Position offset, used for the {@link Flicking.renderOnlyVisible | renderOnlyVisible} option
+     * @defaultValue 0
+     * @readonly
+     */
+    get offset(): number;
+    /**
+     * Whether the `circular` option is enabled.
+     * @remarks
+     * The {@link Flicking.circular | circular} option can't be enabled when sum of the panel sizes are too small.
+     * @defaultValue false
+     * @readonly
+     */
+    get circularEnabled(): boolean;
+    /**
+     * A current camera mode
+     * @readonly
+     */
+    get mode(): CameraMode;
+    /**
+     * A range that Camera's {@link Camera.position | position} can reach
+     * @readonly
+     */
+    get range(): CameraRange;
+    /**
+     * A difference between Camera's minimum and maximum position that can reach
+     * @readonly
+     */
+    get rangeDiff(): number;
+    /**
+     * An array of visible panels from the current position
+     * @readonly
+     */
+    get visiblePanels(): Panel[];
+    /**
+     * A range of the visible area from the current position
+     * @readonly
+     */
+    get visibleRange(): CameraRange;
+    /**
+     * An array of {@link AnchorPoint}s that Camera can be stopped at
+     * @readonly
+     */
+    get anchorPoints(): AnchorPoint[];
+    /**
+     * A current parameters of the Camera for updating {@link AxesController}
+     * @readonly
+     */
+    get controlParams(): {
+        range: CameraRange;
+        position: number;
+        circular: boolean;
+    };
+    /**
+     * A Boolean value indicating whether Camera's over the minimum or maximum position reachable
+     * @readonly
+     */
+    get atEdge(): boolean;
+    /**
+     * Return the size of the viewport
+     * @readonly
+     */
+    get size(): number;
+    /**
+     * Return the camera's position progress from the first panel to last panel
+     * @remarks
+     * Range is from 0 to last panel's index
+     * @readonly
+     */
+    get progress(): number;
+    /**
+     * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/direction | direction} CSS property applied to the camera element(`.flicking-camera`)
+     * @readonly
+     */
+    get panelOrder(): ValueOf<typeof ORDER>;
+    /**
+     * A value indicating where the {@link Camera.alignPosition | alignPosition} should be located at inside the viewport element
+     */
+    get align(): FlickingOptions["align"];
+    set align(val: FlickingOptions["align"]);
+    /**
+     * Creates a new Camera instance
+     * @param flicking - An instance of {@link Flicking}
+     * @param options - Options for the Camera
+     */
+    constructor(flicking: Flicking, { align }?: Partial<CameraOptions>);
+    /**
+     * Initialize Camera
+     * @remarks
+     * This method is called automatically during {@link Flicking.init}. It finds the camera element inside the viewport.
+     * @throws {@link InitializationErrors}
+     * @returns The current instance for method chaining
+     */
+    init(): this;
+    /**
+     * Destroy Camera and return to initial state
+     * @remarks
+     * This method resets all internal values to their initial state.
+     * @returns The current instance for method chaining
+     */
+    destroy(): this;
+    /**
+     * Move to the given position and apply CSS transform
+     * @remarks
+     * This method updates the camera position, toggles panels for circular mode, and refreshes visible panels.
+     * @param pos - A new position
+     * @throws {@link InitializationErrors}
+     */
+    lookAt(pos: number): void;
+    /**
+     * Return a previous {@link AnchorPoint} of given {@link AnchorPoint}
+     * @remarks
+     * If it does not exist, return `null` instead
+     * @param anchor - A reference {@link AnchorPoint}
+     * @returns The previous {@link AnchorPoint}
+     */
+    getPrevAnchor(anchor: AnchorPoint): AnchorPoint | null;
+    /**
+     * Return a next {@link AnchorPoint} of given {@link AnchorPoint}
+     * @remarks
+     * If it does not exist, return `null` instead
+     * @param anchor - A reference {@link AnchorPoint}
+     * @returns The next {@link AnchorPoint}
+     */
+    getNextAnchor(anchor: AnchorPoint): AnchorPoint | null;
+    /**
+     * Return the camera's position progress in the panel below
+     * @remarks
+     * Value is from 0 to 1 when the camera's inside panel.
+     * Value can be lower than 0 or bigger than 1 when it's in the margin area
+     * @param panel - A panel to check
+     * @returns Progress value from 0 to 1 (or outside this range when in margin area)
+     */
+    getProgressInPanel(panel: Panel): number;
+    /**
+     * Return {@link AnchorPoint} that includes given position
+     * @remarks
+     * If there's no {@link AnchorPoint} that includes the given position, return `null` instead
+     * @param position - A position to check
+     * @returns The {@link AnchorPoint} that includes the given position
+     */
+    findAnchorIncludePosition(position: number): AnchorPoint | null;
+    /**
+     * Return {@link AnchorPoint} nearest to given position
+     * @remarks
+     * If there're no {@link AnchorPoint}s, return `null` instead
+     * @param position - A position to check
+     * @returns The {@link AnchorPoint} nearest to the given position
+     */
+    findNearestAnchor(position: number): AnchorPoint | null;
+    /**
+     * Return {@link AnchorPoint} that matches {@link Flicking.currentPanel}
+     * @returns The {@link AnchorPoint} that matches current panel
+     */
+    findActiveAnchor(): AnchorPoint | null;
+    /**
+     * Clamp the given position between camera's range
+     * @param position - A position to clamp
+     * @returns A clamped position
+     */
+    clampToReachablePosition(position: number): number;
+    /**
+     * Check whether the given panel is inside of the Camera's range
+     * @param panel - An instance of {@link Panel} to check
+     * @returns Whether the panel's inside Camera's range
+     */
+    canReach(panel: Panel): boolean;
+    /**
+     * Check whether the given panel element is visible at the current position
+     * @param panel - An instance of {@link Panel} to check
+     * @returns Whether the panel element is visible at the current position
+     */
+    canSee(panel: Panel): boolean;
+    /**
+     * Update {@link Camera.range | range} of Camera
+     * @remarks
+     * This method recalculates the camera range based on the current panel positions and circular mode settings.
+     * @throws {@link InitializationErrors}
+     * @returns The current instance for method chaining
+     */
+    updateRange(): this;
+    /**
+     * Update Camera's {@link Camera.alignPosition | alignPosition}
+     * @returns The current instance for method chaining
+     */
+    updateAlignPos(): this;
+    /**
+     * Update Camera's {@link Camera.anchorPoints | anchorPoints}
+     * @remarks
+     * Anchor points are positions where the camera can stop. This method recalculates them based on the current mode.
+     * @throws {@link InitializationErrors}
+     * @returns The current instance for method chaining
+     */
+    updateAnchors(): this;
+    /**
+     * Update Viewport's height to visible panel's max height
+     * @remarks
+     * This method only takes effect when {@link FlickingOptions.horizontal | horizontal} is `true` and {@link FlickingOptions.adaptive | adaptive} is enabled.
+     * @throws {@link InitializationErrors}
+     */
+    updateAdaptiveHeight(): void;
+    /**
+     * Update current offset of the camera
+     * @returns The current instance for method chaining
+     */
+    updateOffset(): this;
+    /**
+     * Update direction to match the {@link https://developer.mozilla.org/en-US/docs/Web/CSS/direction | direction} CSS property applied to the camera element
+     * @returns The current instance for method chaining
+     */
+    updatePanelOrder(): this;
+    /**
+     * Reset the history of {@link Flicking.event:needPanel | needPanel} events so it can be triggered again
+     * @returns The current instance for method chaining
+     */
+    resetNeedPanelHistory(): this;
+    /**
+     * Apply "transform" style with the current position to camera element
+     * @returns The current instance for method chaining
+     */
+    applyTransform(): this;
+    /**
+     * @internal
+     * @privateRemarks
+     * Resets all internal state values to their defaults. Called during construction and destruction.
+     */
+    private _resetInternalValues;
+    /**
+     * @internal
+     * @privateRemarks
+     * Updates the list of visible panels and triggers {@link VisibleChangeEvent} if panels were added or removed.
+     */
+    private _refreshVisiblePanels;
+    /**
+     * @internal
+     * @privateRemarks
+     * Checks if the camera is near the edges and triggers {@link NeedPanelEvent} for infinite scrolling implementations.
+     */
+    private _checkNeedPanel;
+    /**
+     * @internal
+     * @privateRemarks
+     * Checks if the camera has reached the edge of the range and triggers {@link ReachEdgeEvent}.
+     */
+    private _checkReachEnd;
+    /**
+     * @internal
+     * @privateRemarks
+     * Checks for CSS transform support and stores the vendor-prefixed property name. Throws if transforms are not supported.
+     */
+    private _checkTranslateSupport;
+    /**
+     * @internal
+     * @privateRemarks
+     * Updates the camera mode based on {@link FlickingOptions.circular | circular} and {@link FlickingOptions.bound | bound} options.
+     */
+    private _updateMode;
+    /**
+     * @internal
+     * @privateRemarks
+     * Toggles panel positions for circular mode. Returns true if any panel was toggled.
+     */
+    private _togglePanels;
+}
+export default Camera;

package/{declaration → dist}/camera/mode/BoundCameraMode.d.ts

@@ -1,13 +1,14 @@
 import AnchorPoint from "../../core/AnchorPoint";
+import { CameraRange } from "../Camera";
 import CameraMode from "./CameraMode";
 declare class BoundCameraMode extends CameraMode {
     checkAvailability(): boolean;
-    getRange(): {
-        min: number;
-        max: number;
-    };
+    getRange(): CameraRange;
     getAnchors(): AnchorPoint[];
     findAnchorIncludePosition(position: number): AnchorPoint | null;
+    /**
+     * @internal
+     */
     private _findNearestPanel;
 }
 export default BoundCameraMode;

package/{declaration → dist}/camera/mode/CameraMode.d.ts

@@ -1,14 +1,15 @@
-import Flicking from "../../Flicking";
-import Panel from "../../core/panel/Panel";
 import AnchorPoint from "../../core/AnchorPoint";
+import Panel from "../../core/panel/Panel";
+import Flicking from "../../Flicking";
+import { CameraRange } from "../Camera";
+/**
+ * A mode of camera
+ */
 declare abstract class CameraMode {
     protected _flicking: Flicking;
     constructor(flicking: Flicking);
     abstract checkAvailability(): boolean;
-    abstract getRange(): {
-        min: number;
-        max: number;
-    };
+    abstract getRange(): CameraRange;
     getAnchors(): AnchorPoint[];
     findAnchorIncludePosition(position: number): AnchorPoint | null;
     findNearestAnchor(position: number): AnchorPoint | null;

package/{declaration → dist}/camera/mode/CircularCameraMode.d.ts

@@ -1,12 +1,13 @@
-import Panel from "../../core/panel/Panel";
 import AnchorPoint from "../../core/AnchorPoint";
+import Panel from "../../core/panel/Panel";
+import { CameraRange } from "../Camera";
 import CameraMode from "./CameraMode";
+/**
+ * A {@link Camera} mode that connects the last panel and the first panel, enabling continuous loop
+ */
 declare class CircularCameraMode extends CameraMode {
     checkAvailability(): boolean;
-    getRange(): {
-        min: number;
-        max: number;
-    };
+    getRange(): CameraRange;
     getAnchors(): AnchorPoint[];
     findNearestAnchor(position: number): AnchorPoint | null;
     findAnchorIncludePosition(position: number): AnchorPoint | null;
@@ -14,6 +15,9 @@ declare class CircularCameraMode extends CameraMode {
     clampToReachablePosition(position: number): number;
     canReach(panel: Panel): boolean;
     canSee(panel: Panel): boolean;
+    /**
+     * @internal
+     */
     private _calcPanelAreaSum;
 }
 export default CircularCameraMode;

package/{declaration → dist}/camera/mode/LinearCameraMode.d.ts

@@ -1,9 +1,7 @@
+import { CameraRange } from "../Camera";
 import CameraMode from "./CameraMode";
 declare class LinearCameraMode extends CameraMode {
     checkAvailability(): boolean;
-    getRange(): {
-        min: number;
-        max: number;
-    };
+    getRange(): CameraRange;
 }
 export default LinearCameraMode;

package/{declaration → dist}/cfc/getDefaultCameraTransform.d.ts

@@ -1,3 +1,3 @@
 import { FlickingOptions } from "../Flicking";
-declare const _default: (align?: FlickingOptions["align"], horizontal?: boolean, firstPanelSize?: string) => string;
+declare const _default: (align?: FlickingOptions["align"], horizontal?: boolean, firstPanelSize?: string | undefined) => string;
 export default _default;

package/dist/cfc/withFlickingMethods.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Decorator that makes the method of flicking available in the framework.
+ * @internal
+ * @example
+ * ```js
+ * import Flicking, { withFlickingMethods } from "@egjs/flicking";
+ *
+ * class Flicking extends React.Component<Partial<FlickingProps & FlickingOptions>> {
+ *   &#64;withFlickingMethods
+ *   private flicking: Flicking;
+ * }
+ * ```
+ */
+declare const withFlickingMethods: (prototype: any, flickingName: string) => void;
+export default withFlickingMethods;

package/{declaration/const/axes.d.ts → dist/constants/internal.d.ts}

@@ -1,3 +1,7 @@
+/**
+ * All possible @egjs/axes event keys
+ * @internal
+ */
 export declare const EVENT: {
     readonly HOLD: "hold";
     readonly CHANGE: "change";
@@ -5,4 +9,8 @@ export declare const EVENT: {
     readonly ANIMATION_END: "animationEnd";
     readonly FINISH: "finish";
 };
+/**
+ * An Axis key that Flicking uses
+ * @internal
+ */
 export declare const POSITION_KEY = "flick";

package/dist/constants/values.d.ts

@@ -0,0 +1,67 @@
+/**
+ * An object with all possible predefined literal string for the {@link Flicking.align | align} option
+ */
+export declare const ALIGN: {
+    /** left/top align */
+    readonly PREV: "prev";
+    /** center align */
+    readonly CENTER: "center";
+    /** right/bottom align */
+    readonly NEXT: "next";
+};
+/**
+ * An object of directions
+ */
+export declare const DIRECTION: {
+    /** "left" when {@link Flicking.horizontal | horizontal} is true, and "top" when {@link Flicking.horizontal | horizontal} is false */
+    readonly PREV: "PREV";
+    /** "right" when {@link Flicking.horizontal | horizontal} is true, and "bottom" when {@link Flicking.horizontal | horizontal} is false */
+    readonly NEXT: "NEXT";
+    /** This value usually means it's the same position */
+    readonly NONE: null;
+};
+/**
+ * An object with all possible {@link Flicking.moveType | moveType}s
+ */
+export declare const MOVE_TYPE: {
+    /** Flicking's {@link Flicking.moveType | moveType} that enables {@link SnapControl} as a Flicking's {@link Flicking.control | control} */
+    readonly SNAP: "snap";
+    /** Flicking's {@link Flicking.moveType | moveType} that enables {@link FreeControl} as a Flicking's {@link Flicking.control | control} */
+    readonly FREE_SCROLL: "freeScroll";
+    /** Flicking's {@link Flicking.moveType | moveType} that enables {@link StrictControl} as a Flicking's {@link Flicking.control | control} */
+    readonly STRICT: "strict";
+};
+export declare const CLASS: {
+    VIEWPORT: string;
+    CAMERA: string;
+    VERTICAL: string;
+    HIDDEN: string;
+    DEFAULT_VIRTUAL: string;
+};
+/**
+ * An object with all possible {@link Flicking.circularFallback | circularFallback}s
+ */
+export declare const CIRCULAR_FALLBACK: {
+    /** "linear" */
+    readonly LINEAR: "linear";
+    /** "bound" */
+    readonly BOUND: "bound";
+};
+/**
+ * An object for identifying {@link https://developer.mozilla.org/en-US/docs/Web/CSS/direction | direction} CSS property applied to the camera element(`.flicking-camera`)
+ */
+export declare const ORDER: {
+    /** "ltr" */
+    readonly LTR: "ltr";
+    /** "rtl" */
+    readonly RTL: "rtl";
+};
+/**
+ * An object that contains the direction that {@link Flicking} is moving
+ */
+export declare const MOVE_DIRECTION: {
+    /** horizontal */
+    readonly HORIZONTAL: "horizontal";
+    /** vertical */
+    readonly VERTICAL: "vertical";
+};