@lemonadejs/timeline/dist/index.d.ts

LemonadeJS timeline component

/**
 * Official Type definitions for LemonadeJS plugins
 * https://lemonadejs.net
 */

declare function Timeline(el: HTMLElement, options?: Timeline.Options): Timeline.Instance;

declare namespace Timeline {
    interface Tag {
        /** The tag label text */
        title: string;
        /** The background color of the tag (e.g., '#dc2626', 'red') */
        color?: string;
        /** Click handler for the tag */
        onclick?: (event: MouseEvent, tag: Tag) => void;
    }

    /**
     * Loose input shape — what consumers pass into `data`. Only `date` is
     * required; `title` is filled in by the component when omitted. The
     * index signature lets consumers attach app-specific metadata (e.g.
     * `id`, foreign keys) without casts.
     */
    interface ItemInput {
        /** The date of the item */
        date: string | Date;
        /** The item main label text */
        title?: string;
        /** The text displayed under the title */
        subtitle?: string;
        /** The description of the item */
        description?: string;
        /** The color of border in the item, also influence bullets */
        borderColor?: string;
        /** The style of border in the item */
        borderStyle?: string;
        /** Show editable icon */
        editable?: boolean;
        /** Array of tags to display on this item */
        tags?: Tag[];
        /** Allow consumers to attach their own metadata. */
        [key: string]: any;
    }

    /** Resolved runtime shape — what `result` / callbacks hand back. */
    interface Item extends ItemInput {
        title: string;
        /** Formatted date string (computed at runtime) */
        day?: string;
        /** DOM element reference (set at runtime) */
        el?: HTMLElement;
    }

    interface Options {
        /** The data that the component will base to render */
        data?: ItemInput[];
        /** Format of the date. Default dddd, dd */
        format?: string;
        /** The initial date to start the timeline. Useful for monthly navigation. Accepts string ('2022-12-12') or Date object */
        value?: string | Date;
        /** The type of the Timeline. Use 'monthly' to enable month-based filtering and navigation. */
        type?: "monthly";
        /** The side that item texts will be aligned to */
        align?: "left" | "right" | "top" | "bottom";
        /** The displayed message case no item is found */
        message?: string;
        /** The order the dates will follow, either ascendant or descendant */
        order?: 'asc' | 'desc';
        /** The width of the container */
        width?: number;
        /** The height of the container */
        height?: number;
        /** Specifies the URL for fetching the data. */
        url?: string;
        /** Enable the remote functionality. Default: false */
        remote?: boolean;
        /** Show the navigation header. Defaults to `true` when `type` is 'monthly', `false` otherwise. */
        controls?: boolean;
        /** Sets the `data-mode` attribute on the timeline data container for CSS hooks. */
        position?: string;
        /** The function called when data is updated */
        onupdate?: (instance: Instance, result: Item[]) => void;
        /** Function when the user clicks on edition */
        onedition?: (entry: Item) => void;
    }

    interface Instance {
        /** The root DOM element */
        el: HTMLElement;
        /** The data that the component will base to render */
        data: Item[];
        /** The filtered and sorted result array */
        result: Item[];
        /** Current year */
        year: number;
        /** Current month (1-12) */
        month: number;
        /** Array of month names */
        months: string[];
        /** Format of the date */
        format: string;
        /** The type of the Timeline */
        type?: "monthly";
        /** The side that item texts will be aligned to */
        align: "left" | "right" | "top" | "bottom";
        /** The displayed message when no items found */
        message: string;
        /** The order the dates will follow */
        order: 'asc' | 'desc';
        /** The width of the container */
        width?: number;
        /** The height of the container */
        height?: number;
        /** The initial date value */
        value?: string | Date;
        /** Specifies the URL for fetching the data */
        url?: string;
        /** Enable the remote functionality */
        remote?: boolean;
        /** Show navigation controls */
        controls?: boolean;
        /** Position mode for timeline items */
        position?: string;
        /** Navigate to the next month */
        next: () => void;
        /** Navigate to the previous month */
        prev: () => void;
        /** The function called when data is updated */
        onupdate?: (instance: Instance, result: Item[]) => void;
        /** Function when the user clicks on edition */
        onedition?: (entry: Item) => void;
    }
}

export default Timeline;