@egjs/flicking 4.15.0 → 4.16.0-beta.1

package/dist/control/states/State.d.ts

@@ -0,0 +1,86 @@
+import { OnAnimationEnd, OnChange, OnFinish, OnHold, OnRelease } from "@egjs/axes";
+import Panel from "../../core/panel/Panel";
+import Flicking from "../../Flicking";
+export declare enum STATE_TYPE {
+    IDLE = 0,
+    HOLDING = 1,
+    DRAGGING = 2,
+    ANIMATING = 3,
+    DISABLED = 4
+}
+/**
+ * Event context for State event handlers
+ * @internal
+ */
+export interface StateContext<T> {
+    /** An instance of Flicking */
+    flicking: Flicking;
+    /** An Axes event */
+    axesEvent: T;
+    /** A function for changing current state to other state */
+    transitTo: (nextState: STATE_TYPE) => State;
+}
+/**
+ * A component that shows the current status of the user input or the animation
+ * @internal
+ */
+declare abstract class State {
+    /**
+     * Whether user is clicking or touching
+     * @readonly
+     */
+    abstract readonly holding: boolean;
+    /**
+     * Whether Flicking's animating
+     * @readonly
+     */
+    abstract readonly animating: boolean;
+    protected _delta: number;
+    protected _targetPanel: Panel | null;
+    /**
+     * A sum of delta values of change events from the last hold event of Axes
+     * @readonly
+     */
+    get delta(): number;
+    /**
+     * A panel to set as {@link Control.activePanel} after the animation is finished
+     * @readonly
+     */
+    get targetPanel(): Panel | null;
+    set targetPanel(val: Panel | null);
+    /**
+     * An callback which is called when state has changed to this state
+     * @param prevState - An previous state
+     */
+    onEnter(prevState: State): void;
+    /**
+     * An event handler for Axes's {@link https://naver.github.io/egjs-axes/docs/api/Axes#event-hold | hold} event
+     * @param ctx - {@link StateContext}
+     */
+    onHold(ctx: StateContext<OnHold>): void;
+    /**
+     * An event handler for Axes's {@link https://naver.github.io/egjs-axes/docs/api/Axes#event-change | change} event
+     * @param ctx - {@link StateContext}
+     */
+    onChange(ctx: StateContext<OnChange>): void;
+    /**
+     * An event handler for Axes's {@link https://naver.github.io/egjs-axes/docs/api/Axes#event-release | release} event
+     * @param ctx - {@link StateContext}
+     */
+    onRelease(ctx: StateContext<OnRelease>): void;
+    /**
+     * An event handler for Axes's {@link https://naver.github.io/egjs-axes/docs/api/Axes#event-animationEnd | animationEnd} event
+     * @param ctx - {@link StateContext}
+     */
+    onAnimationEnd(ctx: StateContext<OnAnimationEnd>): void;
+    /**
+     * An event handler for Axes's {@link https://naver.github.io/egjs-axes/docs/api/Axes#event-finish | finish} event
+     * @param ctx - {@link StateContext}
+     */
+    onFinish(ctx: StateContext<OnFinish>): void;
+    /**
+     * @internal
+     */
+    protected _moveToChangedPosition(ctx: StateContext<OnChange>): void;
+}
+export default State;

package/dist/core/AnchorPoint.d.ts

@@ -0,0 +1,40 @@
+import Panel from "./panel/Panel";
+/**
+ * Options for creating an AnchorPoint
+ */
+export interface AnchorPointOptions {
+    /** Index of AnchorPoint */
+    index: number;
+    /** Position of AnchorPoint */
+    position: number;
+    /** A {@link Panel} instance AnchorPoint is referencing to */
+    panel: Panel;
+}
+/**
+ * A data component that has actual position where the camera should be stopped at
+ */
+declare class AnchorPoint {
+    private _index;
+    private _pos;
+    private _panel;
+    /**
+     * Index of AnchorPoint
+     * @readonly
+     */
+    get index(): number;
+    /**
+     * Position of AnchorPoint
+     * @readonly
+     */
+    get position(): number;
+    /**
+     * A {@link Panel} instance AnchorPoint is referencing to
+     * @readonly
+     */
+    get panel(): Panel;
+    /**
+     * @param options - {@link AnchorPointOptions}
+     */
+    constructor(options: AnchorPointOptions);
+}
+export default AnchorPoint;

package/{declaration → dist}/core/AutoResizer.d.ts

@@ -1,4 +1,7 @@
 import Flicking from "../Flicking";
+/**
+ * A component that detects size change and trigger resize method when the autoResize option is used
+ */
 declare class AutoResizer {
     private _flicking;
     private _enabled;
@@ -6,6 +9,9 @@ declare class AutoResizer {
     private _resizeTimer;
     private _maxResizeDebounceTimer;
     get enabled(): boolean;
+    /**
+     * @param flicking
+     */
     constructor(flicking: Flicking);
     enable(): this;
     observePanels(): this;

package/dist/core/Viewport.d.ts

@@ -0,0 +1,60 @@
+import Flicking from "../Flicking";
+import { SetSizeParams } from "../types/params";
+export interface ViewportPadding {
+    /** CSS `padding-left` */
+    left: number;
+    /** CSS `padding-right` */
+    right: number;
+    /** CSS `padding-top` */
+    top: number;
+    /** CSS `padding-bottom` */
+    bottom: number;
+}
+/**
+ * A component that manages viewport size
+ */
+declare class Viewport {
+    private _flicking;
+    private _el;
+    private _width;
+    private _height;
+    private _isBorderBoxSizing;
+    private _padding;
+    /**
+     * A viewport(root) element
+     * @readonly
+     */
+    get element(): HTMLElement;
+    /**
+     * Viewport width, without paddings
+     * @readonly
+     */
+    get width(): number;
+    /**
+     * Viewport height, without paddings
+     * @readonly
+     */
+    get height(): number;
+    /**
+     * Viewport paddings
+     * @readonly
+     */
+    get padding(): ViewportPadding;
+    /**
+     * @param flicking - Flicking instance
+     * @param el - A viewport element
+     */
+    constructor(flicking: Flicking, el: HTMLElement);
+    /**
+     * Change viewport's size.
+     * @remarks
+     * This will change the actual size of `.flicking-viewport` element by changing its CSS width/height property
+     * @param size - {@link SetSizeParams}
+     */
+    setSize(size: SetSizeParams): void;
+    /**
+     * Update width/height to the current viewport element's size
+     */
+    resize(): void;
+}
+export default Viewport;

package/dist/core/VirtualManager.d.ts

@@ -0,0 +1,84 @@
+import Flicking from "../Flicking";
+import VirtualPanel from "./panel/VirtualPanel";
+export declare type PanelRenderCallback = ((
+/** Virtual panel to render */
+panel: VirtualPanel, 
+/** Index of the panel */
+index: number) => string) | (() => string);
+export interface VirtualOptions {
+    renderPanel: PanelRenderCallback;
+    initialPanelCount: number;
+    cache?: boolean;
+    panelClass?: string;
+}
+/**
+ * A manager class to add / remove virtual panels
+ */
+declare class VirtualManager {
+    private _flicking;
+    private _renderPanel;
+    private _initialPanelCount;
+    private _cache;
+    private _panelClass;
+    private _elements;
+    get elements(): {
+        nativeElement: HTMLElement;
+        visible: boolean;
+    }[];
+    /**
+     * A rendering function for the panel element's innerHTML
+     */
+    get renderPanel(): PanelRenderCallback;
+    /**
+     * Initial panel count to render
+     * @readonly
+     * @defaultValue -1
+     */
+    get initialPanelCount(): number;
+    /**
+     * Whether to cache rendered panel's innerHTML
+     * @defaultValue false
+     */
+    get cache(): boolean;
+    /**
+     * The class name that will be applied to rendered panel elements
+     * @defaultValue "flicking-panel"
+     */
+    get panelClass(): string;
+    set renderPanel(val: VirtualOptions["renderPanel"]);
+    set cache(val: NonNullable<VirtualOptions["cache"]>);
+    set panelClass(val: NonNullable<VirtualOptions["panelClass"]>);
+    constructor(flicking: Flicking, options: VirtualOptions | null);
+    init(): void;
+    show(index: number): void;
+    hide(index: number): void;
+    /**
+     * Add new virtual panels at the end of the list
+     * @param count - The number of panels to add
+     * @returns The new panels added
+     */
+    append(count?: number): VirtualPanel[];
+    /**
+     * Add new virtual panels at the start of the list
+     * @param count - The number of panels to add
+     * @returns The new panels added
+     */
+    prepend(count?: number): VirtualPanel[];
+    /**
+     * Add new virtual panels at the given index
+     * @param count - The number of panels to add
+     * @returns The new panels added
+     */
+    insert(index: number, count?: number): VirtualPanel[];
+    /**
+     * Remove panels at the given index
+     * @param count - The number of panels to remove
+     * @returns The panels removed
+     */
+    remove(index: number, count: number): VirtualPanel[];
+    /**
+     * @internal
+     */
+    private _initVirtualElements;
+}
+export default VirtualManager;

package/dist/core/index.d.ts

@@ -0,0 +1,6 @@
+import AnchorPoint from "./AnchorPoint";
+import Viewport, { ViewportPadding } from "./Viewport";
+import VirtualManager, { PanelRenderCallback, VirtualOptions } from "./VirtualManager";
+export { Viewport, AnchorPoint, VirtualManager };
+export type { ViewportPadding, VirtualOptions, PanelRenderCallback };
+export * from "./panel";

package/dist/core/panel/Panel.d.ts

@@ -0,0 +1,298 @@
+import { ALIGN, DIRECTION } from "../../constants/values";
+import Flicking from "../../Flicking";
+import { LiteralUnion, ValueOf } from "../../types/internal";
+import { SetSizeParams } from "../../types/params";
+import ElementProvider from "./provider/ElementProvider";
+export interface PanelOptions {
+    /** An initial index of the panel */
+    index: number;
+    /** An initial {@link Flicking.align | align} value of the panel */
+    align: LiteralUnion<ValueOf<typeof ALIGN>> | number;
+    /** The Flicking instance that this panel belongs to */
+    flicking: Flicking;
+    /** A provider instance that returns the actual html element */
+    elementProvider: ElementProvider;
+}
+export interface PanelMarginInfo {
+    /** CSS `margin-left` when the {@link Flicking.horizontal | horizontal} is `true`, and `margin-top` else */
+    prev: number;
+    /** CSS `margin-right` when the {@link Flicking.horizontal | horizontal} is `true`, and `margin-bottom` else */
+    next: number;
+}
+export interface PanelBoundingBoxRange {
+    /** Bounding box's left({@link Flicking.horizontal | horizontal}: true) / top({@link Flicking.horizontal | horizontal}: false) */
+    min: number;
+    /** Bounding box's right({@link Flicking.horizontal | horizontal}: true) / bottom({@link Flicking.horizontal | horizontal}: false) */
+    max: number;
+}
+/**
+ * A slide data component that holds information of a single HTMLElement
+ * @public
+ */
+declare class Panel {
+    protected _flicking: Flicking;
+    protected _elProvider: ElementProvider;
+    protected _index: number;
+    protected _pos: number;
+    protected _size: number;
+    protected _height: number;
+    protected _margin: PanelMarginInfo;
+    protected _alignPos: number;
+    protected _rendered: boolean;
+    protected _removed: boolean;
+    protected _loading: boolean;
+    protected _toggleDirection: ValueOf<typeof DIRECTION>;
+    protected _toggled: boolean;
+    protected _togglePosition: number;
+    protected _align: PanelOptions["align"];
+    /**
+     * `HTMLElement` that panel's referencing
+     * @readonly
+     */
+    get element(): HTMLElement;
+    /**
+     * @internal
+     * @readonly
+     */
+    get elementProvider(): ElementProvider;
+    /**
+     * Index of the panel
+     * @readonly
+     */
+    get index(): number;
+    /**
+     * Position of the panel, including {@link Panel.alignPosition | alignPosition}
+     * @readonly
+     */
+    get position(): number;
+    /**
+     * Cached size of the panel element
+     * @remarks
+     * This is equal to {@link Panel.element | element}'s `offsetWidth` if {@link Flicking.horizontal | horizontal} is `true`, and `offsetHeight` else
+     * @readonly
+     */
+    get size(): number;
+    /**
+     * Panel's size including CSS `margin`
+     * @remarks
+     * This value includes {@link Panel.element | element}'s margin left/right if {@link Flicking.horizontal | horizontal} is `true`, and margin top/bottom else
+     * @readonly
+     */
+    get sizeIncludingMargin(): number;
+    /**
+     * Height of the panel element
+     * @readonly
+     */
+    get height(): number;
+    /**
+     * Cached CSS `margin` value of the panel element
+     * @readonly
+     */
+    get margin(): PanelMarginInfo;
+    /**
+     * Align position inside the panel where {@link Camera}'s {@link Camera.alignPosition | alignPosition} inside viewport should be located at
+     * @readonly
+     */
+    get alignPosition(): number;
+    /**
+     * A value indicating whether the panel's {@link Flicking.remove | remove}d
+     * @readonly
+     */
+    get removed(): boolean;
+    /**
+     * A value indicating whether the panel's element is being rendered on the screen
+     * @readonly
+     */
+    get rendered(): boolean;
+    /**
+     * A value indicating whether the panel's image/video is not loaded and waiting for resize
+     * @readonly
+     */
+    get loading(): boolean;
+    /**
+     * Panel element's range of the bounding box
+     * @readonly
+     */
+    get range(): PanelBoundingBoxRange;
+    /**
+     * A value indicating whether the panel's position is toggled by circular behavior
+     * @readonly
+     */
+    get toggled(): boolean;
+    /**
+     * A direction where the panel's position is toggled
+     * @readonly
+     */
+    get toggleDirection(): ValueOf<typeof DIRECTION>;
+    /**
+     * Actual position offset determined by {@link Panel.order}
+     * @readonly
+     */
+    get offset(): number;
+    /**
+     * Progress of movement between previous or next panel relative to current panel
+     * @readonly
+     */
+    get progress(): number;
+    /**
+     * Progress of movement between points that panel is completely invisible outside of viewport(prev direction: -1, selected point: 0, next direction: 1)
+     * @readonly
+     */
+    get outsetProgress(): number;
+    /**
+     * Percentage of area where panel is visible in the viewport
+     * @readonly
+     */
+    get visibleRatio(): number;
+    set loading(val: boolean);
+    /**
+     * A value indicating where the {@link Panel.alignPosition | alignPosition} should be located at inside the panel element
+     */
+    get align(): PanelOptions["align"];
+    set align(val: PanelOptions["align"]);
+    /**
+     * Creates a new Panel instance
+     * @param panelOptions - Options for creating the panel
+     */
+    constructor(panelOptions: PanelOptions);
+    /**
+     * @internal
+     * @privateRemarks
+     * Marks this panel to be rendered on the camera element.
+     */
+    markForShow(): void;
+    /**
+     * @internal
+     * @privateRemarks
+     * Marks this panel to be hidden from the camera element.
+     */
+    markForHide(): void;
+    /**
+     * Update size of the panel
+     * @remarks
+     * This method recalculates the panel's size, margin, and position based on the current DOM state.
+     * @param cached - Predefined cached size of the panel
+     * @returns The current instance for method chaining
+     */
+    resize(cached?: {
+        size: number;
+        height?: number;
+        margin: {
+            prev: number;
+            next: number;
+        };
+    }): this;
+    /**
+     * Change panel's size
+     * @remarks
+     * This will change the actual size of the panel element by changing its CSS width/height property.
+     * @param size - {@link SetSizeParams}
+     * @returns The current instance for method chaining
+     */
+    setSize(size: SetSizeParams): this;
+    /**
+     * Check whether the given element is inside of this panel's {@link Panel.element | element}
+     * @remarks
+     * This is useful for determining which panel contains a clicked element.
+     * @param element - The HTMLElement to check
+     * @returns A Boolean value indicating the element is inside of this panel {@link Panel.element | element}
+     */
+    contains(element: HTMLElement): boolean;
+    /**
+     * Reset internal state and set {@link Panel.removed | removed} to `true`
+     * @remarks
+     * After calling this method, the panel should no longer be used.
+     */
+    destroy(): void;
+    /**
+     * Check whether the given position is inside of this panel's {@link Panel.range | range}
+     * @param pos - A position to check
+     * @param includeMargin - Include {@link Panel.margin | margin} to the range
+     * @returns A Boolean value indicating whether the given position is included in the panel range
+     */
+    includePosition(pos: number, includeMargin?: boolean): boolean;
+    /**
+     * Check whether the given range is fully included in this panel's area (inclusive)
+     * @param min - Minimum value of the range to check
+     * @param max - Maximum value of the range to check
+     * @param includeMargin - Include {@link Panel.margin | margin} to the range
+     * @returns A Boolean value indicating whether the given range is fully included in the panel range
+     */
+    includeRange(min: number, max: number, includeMargin?: boolean): boolean;
+    /**
+     * Check whether the panel is visble in the given range (exclusive)
+     * @param min - Minimum value of the range to check
+     * @param max - Maximum value of the range to check
+     * @returns A Boolean value indicating whether the panel is visible
+     */
+    isVisibleOnRange(min: number, max: number): boolean;
+    /**
+     * Move {@link Camera} to this panel
+     * @remarks
+     * This is equivalent to calling `Flicking.moveTo(panel.index, duration)`.
+     * @param duration - Duration of the animation (unit: ms). Defaults to {@link FlickingOptions.duration}
+     * @fires {@link MovementEvents}
+     * @throws {@link MovementErrors}
+     * @returns A Promise which will be resolved after reaching the panel
+     */
+    focus(duration?: number): Promise<void>;
+    /**
+     * Get previous(`index - 1`) panel.
+     * @remarks
+     * When the previous panel does not exist, this will return `null` instead
+     * If the {@link Flicking.circularEnabled | circular} is enabled, this will return the last panel if called from the first panel
+     * @returns The previous panel
+     */
+    prev(): Panel | null;
+    /**
+     * Get next(`index + 1`) panel.
+     * @remarks
+     * When the next panel does not exist, this will return `null` instead
+     * If the {@link Flicking.circularEnabled | circular} is enabled, this will return the first panel if called from the last panel
+     * @returns The next panel
+     */
+    next(): Panel | null;
+    /**
+     * @internal
+     * @privateRemarks
+     * Increases the panel's index by the given value. Called when panels are inserted before this panel.
+     */
+    increaseIndex(val: number): this;
+    /**
+     * @internal
+     * @privateRemarks
+     * Decreases the panel's index by the given value. Called when panels are removed before this panel.
+     */
+    decreaseIndex(val: number): this;
+    /**
+     * @internal
+     * @privateRemarks
+     * Recalculates the panel's position based on the previous panel's position and margins.
+     */
+    updatePosition(): this;
+    /**
+     * @internal
+     * @privateRemarks
+     * Toggles the panel's position for circular mode. Returns true if the panel was toggled.
+     */
+    toggle(prevPos: number, newPos: number): boolean;
+    /**
+     * @internal
+     * @privateRemarks
+     * Updates the toggle direction for circular mode based on the panel's visibility at the camera range edges.
+     */
+    updateCircularToggleDirection(): this;
+    /**
+     * @internal
+     * @privateRemarks
+     * Recalculates the align position based on the align option and panel size.
+     */
+    private _updateAlignPos;
+    /**
+     * @internal
+     * @privateRemarks
+     * Resets all internal state values to their defaults.
+     */
+    private _resetInternalStates;
+}
+export default Panel;

package/dist/core/panel/VirtualPanel.d.ts

@@ -0,0 +1,41 @@
+import Panel, { PanelOptions } from "./Panel";
+import VirtualElementProvider from "./provider/VirtualElementProvider";
+/**
+ * Options for creating a {@link VirtualPanel}
+ */
+export interface VirtualPanelOptions extends PanelOptions {
+    /** A provider instance that returns the actual html element */
+    elementProvider: VirtualElementProvider;
+}
+/**
+ * A slide data component that holds information of a single HTMLElement
+ */
+declare class VirtualPanel extends Panel {
+    protected _elProvider: VirtualElementProvider;
+    protected _cachedInnerHTML: string | null;
+    /**
+     * `HTMLElement` that panel's referencing
+     * @readonly
+     */
+    get element(): HTMLElement;
+    /**
+     * Cached innerHTML by the previous render function
+     * @readonly
+     */
+    get cachedInnerHTML(): string | null;
+    /**
+     * A number for indexing which element it will be rendered on
+     * @readonly
+     */
+    get elementIndex(): number;
+    /**
+     * @param options - {@link VirtualPanelOptions}
+     */
+    constructor(options: VirtualPanelOptions);
+    cacheRenderResult(result: string): void;
+    uncacheRenderResult(): void;
+    render(): void;
+    increaseIndex(val: number): this;
+    decreaseIndex(val: number): this;
+}
+export default VirtualPanel;

package/dist/core/panel/index.d.ts

@@ -0,0 +1,5 @@
+import Panel, { PanelBoundingBoxRange, PanelMarginInfo, PanelOptions } from "./Panel";
+import VirtualPanel, { VirtualPanelOptions } from "./VirtualPanel";
+export * from "./provider";
+export { Panel, VirtualPanel };
+export type { PanelOptions, PanelBoundingBoxRange, PanelMarginInfo, VirtualPanelOptions };

package/{declaration → dist}/core/panel/provider/VanillaElementProvider.d.ts

@@ -1,5 +1,8 @@
 import Flicking from "../../../Flicking";
 import ElementProvider from "./ElementProvider";
+/**
+ * @internal
+ */
 declare class VanillaElementProvider implements ElementProvider {
     private _element;
     private _rendered;

package/{declaration → dist}/core/panel/provider/VirtualElementProvider.d.ts

@@ -1,6 +1,9 @@
 import Flicking from "../../../Flicking";
 import VirtualPanel from "../VirtualPanel";
 import ElementProvider from "./ElementProvider";
+/**
+ * @internal
+ */
 declare class VirtualElementProvider implements ElementProvider {
     private _flicking;
     private _panel;

package/dist/error/FlickingError.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Special type of known error that {@link Flicking} throws.
+ * @remarks
+ * see {@link FlickingErrors} for possible error codes and explantaion
+ * @example
+ * ```ts
+ * import Flicking, { FlickingError, ERROR_CODES } from "@egjs/flicking";
+ * try {
+ *   const flicking = new Flicking(".flicking-viewport")
+ * } catch (e) {
+ *   if (e instanceof FlickingError && e.code === ERROR_CODES.ELEMENT_NOT_FOUND) {
+ *     console.error(e.message)
+ *   }
+ * }
+ * ```
+ */
+declare class FlickingError extends Error {
+    code: number;
+    /**
+     * @param message - Error message
+     * @param code - Error code
+     */
+    constructor(message: string, code: number);
+}
+export default FlickingError;