# LemonadeJS

## JavaScript Timeline

LemonadeJS Timeline is a framework-agnostic JavaScript plugin that offers integration with **Vue**, **React**, and **Angular**. Designed to enable developers to craft logs, event highlights, and minimalist roadmaps easily, it provides extensive customization options. Users have the flexibility to modify colours, content, and point positions and can take advantage of the automatic event grouping by month, complete with navigation functionality.

### Settings

| Attribute | Type                                    | Description                                                                                                 |
| --------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| data      | Item[]                                  | An array of items to be displayed. See **Item Properties** below.                                           |
| type?     | `'monthly'`                             | Enables month-based filtering plus the navigation header. Omit for a flat timeline.                         |
| value?    | string \| Date                          | Initial date used to seed `year` / `month` (useful with `type: 'monthly'`).                                 |
| format?   | string                                  | Mask used to render each item's `day` label. Defaults: `dd mmm yyyy` (monthly), `dddd, dd` (otherwise).     |
| align?    | `'left' \| 'right' \| 'top' \| 'bottom'`| Side the bullet line is aligned to. `Default: 'left'`.                                                      |
| order?    | `'asc' \| 'desc'`                       | Sort order applied to `result`. `Default: 'asc'`.                                                           |
| message?  | string                                  | Displayed when no items match. `Default: 'No records found'`.                                               |
| width?    | number                                  | Container width in pixels.                                                                                  |
| height?   | number                                  | Container height in pixels.                                                                                 |
| controls? | boolean                                 | Show the navigation header. `Default: true` when `type` is `'monthly'`, `false` otherwise.                  |
| position? | string                                  | Passthrough value for `data-mode` on the data container; hook for custom CSS.                               |
| url?      | string                                  | URL for fetching data.                                                                                      |
| remote?   | boolean                                 | When `true` together with `url` and `type: 'monthly'`, items are refetched on month/order change.           |
| onupdate? | (instance, result) => void              | Called every time `result` is recomputed.                                                                   |
| onedition?| (entry) => void                         | Called when the edit icon on an editable item is clicked.                                                   |

### Item Properties

| Attribute             | Description                                                                   |
| --------------------- | ----------------------------------------------------------------------------- |
| date: string \| Date  | The item's date. Required.                                                    |
| title: string         | The item's main label.                                                        |
| subtitle?: string     | Secondary label shown under the title.                                        |
| description?: string  | Long-form description.                                                        |
| borderColor?: string  | CSS color applied to the item's border (`--lm-border-color`).                 |
| borderStyle?: string  | CSS border style (`solid`, `dashed`, `dotted`, ...) — sets `--lm-border-style`. |
| editable?: boolean    | When `true`, renders an edit icon that fires `onedition`.                     |
| tags?: Tag[]          | Array of tag chips rendered under the description.                            |
| day?: string          | Formatted date label. Computed from `date` and `format` at runtime.           |

### Tag Properties

| Attribute  | Description                                                       |
| ---------- | ----------------------------------------------------------------- |
| title      | Tag label.                                                        |
| color?     | Background color applied to the chip (e.g. `'#dc2626'`, `'red'`). |
| onclick?   | `(event, tag) => void` — called when the tag is clicked.          |

### Instance

Calling `Timeline(root, options)` returns an instance exposing:

| Property / Method   | Description                                                 |
| ------------------- | ----------------------------------------------------------- |
| el                  | The root DOM element.                                       |
| data                | Reactive array of items (assign to replace).                |
| result              | Filtered + sorted array used for rendering.                 |
| year / month        | Current navigation position (`month` is 1-12).              |
| months              | Localized month names.                                      |
| next() / prev()     | Navigate one month forward / backward.                      |

### Events

| Event     | Trigger                                                      |
| --------- | ------------------------------------------------------------ |
| onupdate  | Fired after `result` is recomputed (initial render + every change). Signature: `(instance, result)`. |
| onedition | Fired when the edit icon is clicked on an `editable` item. Signature: `(entry)`.                     |

### Installation

To install it in your project using npm, run the following command:

```bash
$ npm install @lemonadejs/timeline
```

### CDN

To use timeline via a CDN, include the following script tags in your HTML file:

```html
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/lemonadejs/dist/lemonade.min.js"></script>
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/@lemonadejs/timeline/dist/index.min.js"></script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@lemonadejs/timeline/dist/style.min.css" />
```

### Usage

Quick example with Lemonade

```javascript
import lemonade from 'lemonadejs';
import Timeline from '@lemonadejs/timeline';
import '@lemonadejs/timeline/dist/style.css';

export default function App() {
    const data = [
        {
            title: 'Issue Identification',
            date: new Date(2022, 6, 1),
            tags: [{ title: 'urgent', color: '#dc2626' }],
        },
        {
            title: 'Root Cause Analysis',
            date: new Date(2022, 6, 2),
        },
        {
            title: 'Implementation of Solution',
            date: new Date(2022, 6, 3),
            borderColor: '#808000',
            borderStyle: 'dashed',
            editable: true,
        },
        {
            title: 'Review',
            date: new Date(2022, 6, 4),
        },
    ];

    return (render) => render`<Timeline data="${data}" align="left" onedition="${(e) => console.log(e)}" /></div>`;
}
```

Quick example with React

```jsx
import React, { useRef } from 'react';
import Timeline from '@lemonadejs/timeline/dist/react';
import '@lemonadejs/timeline/dist/style.css';

const data = [
    { title: 'Issue Identification', date: new Date(2022, 6, 1) },
    { title: 'Root Cause Analysis', date: new Date(2022, 6, 2) },
    {
        title: 'Implementation of Solution',
        date: new Date(2022, 6, 3),
        borderColor: '#808000',
        borderStyle: 'dashed',
    },
    { title: 'Review', date: new Date(2022, 6, 4) },
];

export default function App() {
    const ref = useRef();
    return <Timeline ref={ref} data={data} align="left" />;
}
```

A micro reactive timeline in javascript and LemonadeJS.
https://lemonadejs.com

Other useful tools

https://jspreadsheet.com

https://jsuites.net