@egjs/flicking 4.15.0 → 4.16.0-beta.0

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+import Flicking from "./Flicking";
+export * from "./CrossFlicking";
+export * from "./CrossFlicking";
+export * from "./camera";
+export * from "./cfc";
+export * from "./constants/values";
+export * from "./control";
+export * from "./core";
+export * from "./error";
+export * from "./event";
+export * from "./Flicking";
+export * from "./reactive";
+export * from "./renderer";
+export * from "./types/external";
+export * from "./utils";
+export default Flicking;

package/dist/reactive/index.d.ts

@@ -0,0 +1,126 @@
+import { ReactiveObject, ReactiveSetupAdapter } from "@cfcs/core";
+import Flicking from "../Flicking";
+/**
+ * Reactive object type that combines state and methods for Flicking
+ * @remarks
+ * This type provides reactive state properties and methods that automatically update
+ * when the Flicking instance state changes.
+ * @see {@link https://naver.github.io/egjs-flicking/Demos#reactive-api-demo}
+ * @example
+ * ```jsx
+ *   const flickingRef = React.useRef(null);
+ *   const {
+ *     progress
+ *   } = useFlickingReactiveAPI(flickingRef);
+ *  ```
+ */
+export declare type FlickingReactiveObject = ReactiveObject<FlickingReactiveState & FlickingReactiveMethod>;
+/**
+ * Reactive state properties for Flicking
+ */
+export interface FlickingReactiveState {
+    /** Whether Flicking has reached the first panel */
+    isReachStart: boolean;
+    /** Whether Flicking has reached the last panel */
+    isReachEnd: boolean;
+    /** Total number of panels */
+    totalPanelCount: number;
+    /** Current active panel index */
+    currentPanelIndex: number;
+    /** Overall scroll progress percentage (0-100) */
+    progress: number;
+    /** Panel progress with decimal values */
+    indexProgress: number;
+}
+/**
+ * Reactive methods for Flicking
+ */
+export interface FlickingReactiveMethod {
+    /**
+     * Move to a specific panel index
+     * @param i - Target panel index
+     * @returns Promise that resolves when movement is complete
+     */
+    moveTo: (i: number) => Promise<void>;
+}
+/**
+ * Data required for reactive API setup
+ */
+export interface FlickingReactiveData {
+    /** Flicking instance to connect */
+    flicking?: Flicking;
+    /** Flicking options used for initialization */
+    options?: FlickingReactiveAPIOptions;
+}
+/**
+ * Options for Flicking reactive API that help optimize initial rendering in SSR scenarios
+ * @remarks
+ * These options allow you to set initial state values before the Flicking instance is fully initialized,
+ * preventing unnecessary re-renders when the actual Flicking state is applied.
+ * @example
+ * ```js
+ * const options = {
+ *   defaultIndex: 2,
+ *   totalPanelCount: 5
+ * };
+ * const reactiveObj = connectFlickingReactiveAPI(flicking, options);
+ * ```
+ */
+export interface FlickingReactiveAPIOptions {
+    /**
+     * Initial panel index to start with. This sets the currentPanelIndex and indexProgress initial values.
+     * @remarks
+     * Also affects isReachStart and isReachEnd initial value setting.
+     * @defaultValue 0
+     */
+    defaultIndex?: number;
+    /**
+     * Total number of panels in the Flicking instance. This sets the totalPanelCount initial value
+     * @remarks
+     * Helps prevent layout shifts during SSR hydration.
+     * @defaultValue 0
+     */
+    totalPanelCount?: number;
+}
+/**
+ * Internal reactive API adapter for Flicking that manages state and event listeners
+ * @remarks
+ * This adapter is used internally by framework-specific packages (react-flicking, vue-flicking, etc.)
+ * to provide reactive API support. Users rarely need to use this directly.
+ * @param onInit - Callback when reactive object is initialized
+ * @param onDestroy - Callback when reactive object is destroyed
+ * @param setMethods - Function to set available methods
+ * @returns Reactive object with Flicking state and methods
+ */
+declare const flickingReactiveAPIAdapter: ReactiveSetupAdapter<FlickingReactiveObject, FlickingReactiveState, "moveTo", FlickingReactiveData>;
+/**
+ * Connect Flicking instance to reactive API
+ * @param flicking - Flicking instance to connect
+ * @param options - Flicking options
+ * @returns Reactive object with Flicking state and methods
+ * @example
+ * ```js
+ * import Flicking, { connectFlickingReactiveAPI } from "@egjs/flicking";
+ *
+ * const flicking = new Flicking("#el");
+ * const reactiveObj = connectFlickingReactiveAPI(flicking);
+ *
+ * // Access reactive state
+ * console.log("Current panel:", reactiveObj.currentPanelIndex);
+ * console.log("Progress:", reactiveObj.progress + "%");
+ * console.log("Is at start:", reactiveObj.isReachStart);
+ * console.log("Is at end:", reactiveObj.isReachEnd);
+ * console.log("Total panels:", reactiveObj.totalPanelCount);
+ * console.log("Index progress:", reactiveObj.indexProgress);
+ *
+ * // Subscribe to state changes
+ * reactiveObj.subscribe("currentPanelIndex", (nextValue) => {
+ *   console.log("Panel changed to:", nextValue);
+ * });
+ *
+ * // Use reactive methods
+ * reactiveObj.moveTo(2); // Move to third panel
+ * ```
+ */
+declare const connectFlickingReactiveAPI: (flicking: Flicking, options?: FlickingReactiveAPIOptions | undefined) => FlickingReactiveObject;
+export { flickingReactiveAPIAdapter, connectFlickingReactiveAPI };

package/{declaration → dist}/renderer/ExternalRenderer.d.ts

@@ -1,5 +1,8 @@
 import Panel from "../core/panel/Panel";
 import Renderer from "./Renderer";
+/**
+ * @internal
+ */
 declare abstract class ExternalRenderer extends Renderer {
     protected _removePanelElements(panels: Panel[]): void;
     protected _removeAllChildsFromCamera(): void;

package/dist/renderer/Renderer.d.ts

@@ -0,0 +1,215 @@
+import Panel, { PanelOptions } from "../core/panel/Panel";
+import Flicking, { FlickingOptions } from "../Flicking";
+import RenderingStrategy from "./strategy/RenderingStrategy";
+/**
+ * Options for creating a {@link Renderer}
+ */
+export interface RendererOptions {
+    /** An {@link Flicking.align | align} value that will be applied to all panels */
+    align?: FlickingOptions["align"];
+    /** An instance of RenderingStrategy(internal module) */
+    strategy: RenderingStrategy;
+}
+/**
+ * Parameters for {@link Renderer.batchInsert}
+ * @public
+ */
+export interface BatchInsertParams {
+    /** Index to insert new panels at */
+    index: number;
+    /** An array of element or framework component with element in it */
+    elements: any[];
+    /** Whether it contains actual DOM elements. If set to true, renderer will add them to the camera element */
+    hasDOMInElements: boolean;
+}
+/**
+ * Parameters for {@link Renderer.batchRemove}
+ * @public
+ */
+export interface BatchRemoveParams {
+    /** Index of panel to remove */
+    index: number;
+    /** Number of panels to remove from index */
+    deleteCount: number;
+    /** Whether it contains actual DOM elements. If set to true, renderer will remove them from the camera element */
+    hasDOMInElements: boolean;
+}
+/**
+ * A component that manages {@link Panel} and its elements
+ * @public
+ */
+declare abstract class Renderer {
+    protected _flicking: Flicking | null;
+    protected _panels: Panel[];
+    protected _rendering: boolean;
+    protected _align: NonNullable<RendererOptions["align"]>;
+    protected _strategy: RendererOptions["strategy"];
+    /**
+     * Array of panels
+     * @readonly
+     * @see Panel
+     */
+    get panels(): Panel[];
+    /**
+     * A boolean value indicating whether rendering is in progress
+     * @readonly
+     * @internal
+     */
+    get rendering(): boolean;
+    /**
+     * Count of panels
+     * @readonly
+     */
+    get panelCount(): number;
+    /**
+     * @internal
+     */
+    get strategy(): RendererOptions["strategy"];
+    /**
+     * A {@link Panel}'s {@link Panel.align | align} value that applied to all panels
+     */
+    get align(): NonNullable<RendererOptions["align"]>;
+    set align(val: NonNullable<RendererOptions["align"]>);
+    /**
+     * @param options - {@link RendererOptions}
+     */
+    constructor(options: RendererOptions);
+    /**
+     * Render panel elements inside the camera element
+     * @remarks
+     * This method updates the DOM to reflect the current panel state.
+     * @returns A Promise that resolves when rendering is complete
+     */
+    abstract render(): Promise<void>;
+    /**
+     * @internal
+     * @privateRemarks
+     * Collects panel elements from the camera element and creates Panel instances.
+     */
+    protected abstract _collectPanels(): void;
+    /**
+     * @internal
+     * @privateRemarks
+     * Creates a Panel instance from an element with the given options.
+     */
+    protected abstract _createPanel(el: any, options: Omit<PanelOptions, "elementProvider">): Panel;
+    /**
+     * Initialize Renderer
+     * @remarks
+     * This method is called automatically during {@link Flicking.init}. It collects existing panel elements.
+     * @param flicking - An instance of {@link Flicking}
+     * @returns The current instance for method chaining
+     */
+    init(flicking: Flicking): this;
+    /**
+     * Destroy Renderer and return to initial state
+     * @remarks
+     * This method clears all panel references and resets the internal state.
+     */
+    destroy(): void;
+    /**
+     * Return the {@link Panel} at the given index. `null` if it doesn't exist.
+     * @remarks
+     * This is equivalent to accessing `Flicking.panels[index]`.
+     * @param index - Index of the panel to get
+     * @returns Panel at the given index
+     * @see Panel
+     */
+    getPanel(index: number): Panel | null;
+    forceRenderAllPanels(): Promise<void>;
+    /**
+     * Return Rendered Panels
+     * @returns Rendered Panels
+     */
+    getRenderedPanels(): Panel[];
+    /**
+     * Update all panel sizes
+     * @returns The current instance for method chaining
+     */
+    updatePanelSize(): this;
+    /**
+     * Insert new panels at given index
+     * @remarks
+     * This will increase index of panels after by the number of panels added.
+     * @param items - An array of {@link BatchInsertParams}
+     * @throws {@link DOMManipulationErrors}
+     * @returns An array of inserted panels
+     */
+    batchInsert(...items: BatchInsertParams[]): Panel[];
+    /**
+     * @internal
+     * @privateRemarks
+     * Defers update. Camera position & others will be updated after calling updateAfterPanelChange.
+     */
+    batchInsertDefer(...items: BatchInsertParams[]): Panel[];
+    /**
+     * Remove the panel at the given index
+     * @remarks
+     * This will decrease index of panels after by the number of panels removed.
+     * @param items - An array of {@link BatchRemoveParams}
+     * @throws {@link DOMManipulationErrors}
+     * @returns An array of removed panels
+     */
+    batchRemove(...items: BatchRemoveParams[]): Panel[];
+    /**
+     * @internal
+     * @privateRemarks
+     * Defers update. Camera position & others will be updated after calling updateAfterPanelChange.
+     */
+    batchRemoveDefer(...items: BatchRemoveParams[]): Panel[];
+    /**
+     * @internal
+     * @privateRemarks
+     * Updates camera, control, and triggers {@link PanelChangeEvent} after panels are added or removed.
+     */
+    updateAfterPanelChange(panelsAdded: Panel[], panelsRemoved: Panel[]): void;
+    /**
+     * @internal
+     * @privateRemarks
+     * Checks if panel contents (images/videos) are ready and triggers resize when loaded.
+     */
+    checkPanelContentsReady(checkingPanels: Panel[]): void;
+    /**
+     * @internal
+     * @privateRemarks
+     * Updates camera range, anchors, and control input after panel changes.
+     */
+    protected _updateCameraAndControl(): void;
+    /**
+     * @internal
+     * @privateRemarks
+     * Marks only visible panels for rendering when {@link FlickingOptions.renderOnlyVisible | renderOnlyVisible} is enabled.
+     */
+    protected _showOnlyVisiblePanels(flicking: Flicking): void;
+    /**
+     * @internal
+     * @privateRemarks
+     * Calculates and applies panel sizes when {@link FlickingOptions.panelsPerView | panelsPerView} is enabled.
+     */
+    protected _updatePanelSizeByGrid(referencePanel: Panel, panels: Panel[]): void;
+    /**
+     * @internal
+     * @privateRemarks
+     * Removes all child elements from the camera element.
+     */
+    protected _removeAllChildsFromCamera(): void;
+    /**
+     * @internal
+     * @privateRemarks
+     * Inserts panel elements into the camera element at the specified position.
+     */
+    protected _insertPanelElements(panels: Panel[], nextSibling?: Panel | null): void;
+    /**
+     * @internal
+     * @privateRemarks
+     * Removes panel elements from the camera element.
+     */
+    protected _removePanelElements(panels: Panel[]): void;
+    /**
+     * @internal
+     * @privateRemarks
+     * Called after rendering to apply the camera transform.
+     */
+    protected _afterRender(): void;
+}
+export default Renderer;

package/{declaration → dist}/renderer/VanillaRenderer.d.ts

@@ -4,7 +4,13 @@ declare class VanillaRenderer extends Renderer {
     render(): Promise<void>;
     protected _collectPanels(): void;
     protected _createPanel(el: HTMLElement, options: Omit<PanelOptions, "elementProvider">): Panel;
+    /**
+     * @internal
+     */
     private _resetPanelElementOrder;
+    /**
+     * @internal
+     */
     private _removeAllTextNodes;
 }
 export default VanillaRenderer;

package/{declaration → dist}/renderer/strategy/NormalRenderingStrategy.d.ts

@@ -1,13 +1,13 @@
-import Flicking from "../../Flicking";
 import Panel, { PanelOptions } from "../../core/panel/Panel";
 import ElementProvider from "../../core/panel/provider/ElementProvider";
+import Flicking from "../../Flicking";
 import RenderingStrategy from "./RenderingStrategy";
 export interface NormalRenderingStrategyOptions {
     providerCtor: new (...args: any) => ElementProvider;
 }
 declare class NormalRenderingStrategy implements RenderingStrategy {
     private _providerCtor;
-    constructor({ providerCtor }: NormalRenderingStrategyOptions);
+    constructor(options: NormalRenderingStrategyOptions);
     renderPanels(): void;
     getRenderingIndexesByOrder(flicking: Flicking): number[];
     getRenderingElementsByOrder(flicking: Flicking): HTMLElement[];
@@ -18,6 +18,9 @@ declare class NormalRenderingStrategy implements RenderingStrategy {
         width: number | string;
         height: number | string;
     }>): void;
+    /**
+     * @internal
+     */
     private _showOnlyVisiblePanels;
 }
 export default NormalRenderingStrategy;

package/{declaration → dist}/renderer/strategy/RenderingStrategy.d.ts

@@ -1,5 +1,8 @@
-import Flicking from "../../Flicking";
 import Panel, { PanelOptions } from "../../core/panel/Panel";
+import Flicking from "../../Flicking";
+/**
+ * @internal
+ */
 interface RenderingStrategy {
     renderPanels(flicking: Flicking): void;
     getRenderingIndexesByOrder(flicking: Flicking): number[];

package/dist/types/external.d.ts

@@ -0,0 +1,58 @@
+import { MOVE_TYPE } from "../constants/values";
+import { FreeControlOptions, SnapControlOptions, StrictControlOptions } from "../control";
+import Flicking from "../Flicking";
+import { ValueOf } from "./internal";
+/**
+ * HTML `string` of single/mutiple HTMLElement, or an instance of `HTMLElement`
+ */
+export declare type ElementLike = string | HTMLElement;
+/**
+ * Flicking Plugin
+ */
+export interface Plugin {
+    /** Initialize the plugin */
+    init(flicking: Flicking): void;
+    /** Destroy plugin and detach all events binded */
+    destroy(): void;
+    /** Update plugin to match current Flicking's status */
+    update(flicking: Flicking): void;
+}
+/**
+ * Flicking Status returned by {@link Flicking.getStatus}
+ */
+export interface Status {
+    /** An index of the active panel */
+    index?: number;
+    /** A info to restore camera {@link Camera.position | position} */
+    position?: {
+        /** An index of the panel camera is located at */
+        panel: number;
+        /** A progress of the camera position inside the panel */
+        progressInPanel: number;
+    };
+    /** An offset to visible panel's original index. This value is available only when `visiblePanelsOnly` is `true` */
+    visibleOffset?: number;
+    /** A data array of panels */
+    panels: Array<{
+        /** An index of the panel */
+        index: number;
+        /** An `outerHTML` of the panel element */
+        html?: string;
+    }>;
+}
+export declare type MoveTypeOptions<T extends ValueOf<typeof MOVE_TYPE>> = T extends typeof MOVE_TYPE.SNAP ? [T] | [T, Partial<SnapControlOptions>] : T extends typeof MOVE_TYPE.FREE_SCROLL ? [T] | [T, Partial<FreeControlOptions>] : T extends typeof MOVE_TYPE.STRICT ? [T] | [T, Partial<StrictControlOptions>] : [T];
+/**
+ * A current parameters of the Camera for updating {@link AxesController}
+ * @readonly
+ */
+export interface ControlParams {
+    /** A moveable range for Camera */
+    range: {
+        min: number;
+        max: number;
+    };
+    /** Current camera position */
+    position: number;
+    /** A Boolean indicating whether the {@link Flicking.circular | circular} option is enabled */
+    circular: boolean;
+}

package/dist/types/params.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Parameters for setting element size
+ * @public
+ */
+export interface SetSizeParams {
+    /** CSS string or number(in px) */
+    width?: number | string;
+    /** CSS string or number(in px) */
+    height?: number | string;
+}

package/{declaration → dist}/utils.d.ts

@@ -1,9 +1,9 @@
+import { ALIGN, DIRECTION } from "./constants/values";
 import Flicking, { FlickingOptions } from "./Flicking";
-import { ALIGN, DIRECTION } from "./const/external";
-import { LiteralUnion, Merged, ValueOf } from "./type/internal";
-import { ElementLike } from "./type/external";
+import { ElementLike } from "./types/external";
+import { LiteralUnion, Merged, ValueOf } from "./types/internal";
 export declare const merge: <From extends object, To extends object>(target: From, ...sources: To[]) => Merged<From, To>;
-export declare const getElement: (el: HTMLElement | string | null, parent?: HTMLElement) => HTMLElement;
+export declare const getElement: (el: HTMLElement | string | null, parent?: HTMLElement | undefined) => HTMLElement;
 export declare const checkExistence: (value: any, nameOnErrMsg: string) => void;
 export declare const clamp: (x: number, min: number, max: number) => number;
 export declare const getFlickingAttached: (val: Flicking | null) => Flicking;
@@ -23,8 +23,8 @@ export declare const getMinusCompensatedIndex: (idx: number, max: number) => num
 export declare const includes: <T>(array: T[], target: any) => target is T;
 export declare const isString: (val: any) => val is string;
 export declare const circulatePosition: (pos: number, min: number, max: number) => number;
-export declare const find: <T>(array: T[], checker: (val: T) => boolean) => T;
-export declare const findRight: <T>(array: T[], checker: (val: T) => boolean) => T;
+export declare const find: <T>(array: T[], checker: (val: T) => boolean) => T | null;
+export declare const findRight: <T>(array: T[], checker: (val: T) => boolean) => T | null;
 export declare const findIndex: <T>(array: T[], checker: (val: T) => boolean) => number;
 export declare const getProgress: (pos: number, prev: number, next: number) => number;
 export declare const getStyle: (el: HTMLElement) => CSSStyleDeclaration;
@@ -42,6 +42,6 @@ export declare const getElementSize: ({ el, horizontal, useFractionalSize, useOf
     useOffset: boolean;
     style: CSSStyleDeclaration;
 }) => number;
-export declare const setPrototypeOf: (o: any, proto: object) => any;
+export declare const setPrototypeOf: (o: any, proto: object | null) => any;
 export declare const camelize: (str: string) => string;
 export declare const getDataAttributes: (element: HTMLElement, attributePrefix: string) => Record<string, string>;