timeline-scheduler 0.1.0

package/README.md

@@ -0,0 +1,370 @@
+# timeline-scheduler
+
+A framework-agnostic Web Component for scheduling and visualising events across multiple resources on a daily timeline.
+
+![timeline-scheduler preview](scheduler.png)
+
+- **Zero dependencies** — built with Lit, works in any framework or plain HTML
+- **Drag & drop** — move events across resources and time with snapping
+- **Resize** — drag event edges to adjust duration
+- **Hold to create** — press and hold on empty space to draw a new event
+- **Navigation** — built-in prev/next day buttons with date picker and zoom controls
+- **Overlap handling** — overlapping events are automatically stacked in sub-rows
+- **Multi-day events** — events spanning midnight are clipped and shown on each day
+- **Keyboard accessible** — Tab between items, arrow keys to move them
+- **Customisable** — CSS custom properties for theming, custom item renderer, and full event hooks
+- **TypeScript** — fully typed
+
+---
+
+## Install
+
+```bash
+npm install timeline-scheduler
+```
+
+---
+
+## Quick start
+
+```html
+<script type="module">
+  import "timeline-scheduler";
+</script>
+
+<timeline-scheduler id="tl"></timeline-scheduler>
+```
+
+```js
+const tl = document.getElementById("tl");
+
+tl.resources = [
+  { id: "r1", name: "Alice Johnson", avatar: "https://example.com/alice.jpg" },
+  { id: "r2", name: "Bob Smith" },
+];
+
+tl.items = [
+  {
+    id: "i1",
+    resourceId: "r1",
+    name: "Team sync",
+    color: "#3b82f6",
+    start: new Date("2024-04-13T09:00:00"),
+    end: new Date("2024-04-13T10:00:00"),
+    description: "Weekly check-in",
+  },
+];
+
+tl.date = new Date("2024-04-13");
+tl.showNav = true;
+tl.draggable = true;
+tl.resizable = true;
+tl.creatable = true;
+
+// Keep data in sync after drag / resize
+tl.addEventListener("change", (e) => {
+  tl.items = e.detail.items;
+});
+
+// Navigate to the new date when the user clicks prev/next
+tl.addEventListener("date-change", (e) => {
+  tl.date = e.detail.date;
+});
+```
+
+### React
+
+```tsx
+import "timeline-scheduler";
+import type { TimelineScheduler } from "timeline-scheduler";
+
+declare global {
+  namespace JSX {
+    interface IntrinsicElements {
+      "timeline-scheduler": React.DetailedHTMLProps<
+        React.HTMLAttributes<TimelineScheduler>,
+        TimelineScheduler
+      >;
+    }
+  }
+}
+
+function App() {
+  const ref = useRef<TimelineScheduler>(null);
+
+  useEffect(() => {
+    const tl = ref.current!;
+    tl.resources = [...];
+    tl.items = [...];
+    tl.showNav = true;
+    tl.draggable = true;
+
+    tl.addEventListener("change", (e: Event) => {
+      tl.items = (e as CustomEvent).detail.items;
+    });
+  }, []);
+
+  return <timeline-scheduler ref={ref} style={{ maxHeight: "600px" }} />;
+}
+```
+
+---
+
+## Features
+
+### Navigation bar
+
+```js
+tl.showNav = true;
+```
+
+Shows previous/next day buttons, a clickable date label that opens the native date picker, and zoom controls. Control individual parts:
+
+```js
+tl.showDateNav = false; // hide prev/next + date picker
+tl.showZoomControls = false; // hide zoom buttons
+// nav bar auto-hides when both are false
+```
+
+### Zoom
+
+```js
+tl.zoom = 2; // 1 (default), 2, or 4
+```
+
+At zoom > 1 the timeline scrolls horizontally while resource labels and the time header stay sticky.
+
+### Hold to create
+
+```js
+tl.creatable = true;
+
+tl.addEventListener("item-create", (e) => {
+  const { resourceId, start, end } = e.detail;
+  tl.items = [
+    ...tl.items,
+    {
+      id: crypto.randomUUID(),
+      resourceId,
+      name: "New event",
+      color: "#64748b",
+      start,
+      end,
+    },
+  ];
+});
+```
+
+Press and hold on empty space for ~400 ms, then drag to set the duration.
+
+### Custom item renderer
+
+Replace the default name + time display with your own content:
+
+```js
+tl.renderItem = (item) => {
+  const el = document.createElement("span");
+  el.textContent = `★ ${item.name}`;
+  el.style.fontWeight = "600";
+  return el;
+};
+
+tl.renderItem = null; // reset to default
+```
+
+### Resize constraints
+
+```js
+tl.minDurationMinutes = 30; // can't resize shorter than 30 min
+tl.maxDurationMinutes = 240; // can't resize longer than 4 hours
+```
+
+### Multi-day items
+
+Items whose `start` and `end` span multiple days are automatically clipped to the visible day. An event from April 12 at 15:00 to April 13 at 09:00 will show as 15:00–24:00 on the 12th and 00:00–09:00 on the 13th.
+
+### Keyboard navigation
+
+| Key                        | Action                              |
+| -------------------------- | ----------------------------------- |
+| `ArrowLeft` / `ArrowRight` | Move focused item one snap interval |
+| `Tab` / `Shift+Tab`        | Move focus between items            |
+
+### Built-in context menu
+
+Right-clicking an item opens a context menu with **Edit**, **Delete**, and **Close**. Edit opens a modal to change the name, resource, and times. Disable with `editable = false` to handle it yourself:
+
+```js
+tl.editable = false;
+
+tl.addEventListener("item-contextmenu", (e) => {
+  const { item, x, y } = e.detail;
+  // show your own menu at (x, y)
+});
+```
+
+### Theming
+
+```css
+timeline-scheduler {
+  max-height: 600px;
+  --tl-resource-col-width: 200px;
+  --tl-font-family: "Inter", sans-serif;
+}
+```
+
+Dark mode:
+
+```css
+timeline-scheduler {
+  --tl-bg: #0f172a;
+  --tl-header-bg: #1e293b;
+  --tl-resource-border-color: #334155;
+  --tl-grid-line-color: #334155;
+  --tl-text-color: #f1f5f9;
+  --tl-time-label-color: #64748b;
+}
+```
+
+---
+
+## Reference
+
+### Properties
+
+#### Data
+
+| Property    | Type             | Default | Description                                     |
+| ----------- | ---------------- | ------- | ----------------------------------------------- |
+| `resources` | `Resource[]`     | `[]`    | Rows to display                                 |
+| `items`     | `TimelineItem[]` | `[]`    | Events to render                                |
+| `date`      | `Date`           | today   | The day shown. Items are filtered to this date. |
+
+#### Time range
+
+| Property      | Type     | Default | Description                                 |
+| ------------- | -------- | ------- | ------------------------------------------- |
+| `startHour`   | `number` | `0`     | First visible hour (0–23)                   |
+| `endHour`     | `number` | `24`    | Last visible hour (1–24)                    |
+| `snapMinutes` | `number` | `15`    | Snap interval in minutes during drag/resize |
+
+#### Interaction
+
+| Property             | Type      | Default | Description                                             |
+| -------------------- | --------- | ------- | ------------------------------------------------------- |
+| `draggable`          | `boolean` | `true`  | Allow drag & drop                                       |
+| `resizable`          | `boolean` | `false` | Allow resizing by dragging edges                        |
+| `readonly`           | `boolean` | `false` | Disable all interaction                                 |
+| `creatable`          | `boolean` | `false` | Allow hold-to-create on empty space                     |
+| `editable`           | `boolean` | `true`  | Allow built-in edit modal on double-click / right-click |
+| `minDurationMinutes` | `number`  | `0`     | Minimum duration during resize (0 = no limit)           |
+| `maxDurationMinutes` | `number`  | `0`     | Maximum duration during resize (0 = no limit)           |
+
+#### Display
+
+| Property           | Type                                        | Default | Description                               |
+| ------------------ | ------------------------------------------- | ------- | ----------------------------------------- |
+| `showNav`          | `boolean`                                   | `false` | Show the navigation bar                   |
+| `showDateNav`      | `boolean`                                   | `true`  | Show prev/next + date picker in nav bar   |
+| `showZoomControls` | `boolean`                                   | `true`  | Show zoom buttons in nav bar              |
+| `zoom`             | `number`                                    | `1`     | Horizontal zoom factor (`1`, `2`, or `4`) |
+| `showTime`         | `boolean`                                   | `true`  | Show start–end time inside event blocks   |
+| `showAvatar`       | `boolean`                                   | `true`  | Show avatar / initials in resource column |
+| `showEventCount`   | `boolean`                                   | `true`  | Show event count below resource name      |
+| `showTooltip`      | `boolean`                                   | `true`  | Show hover tooltip on events              |
+| `showNowLine`      | `boolean`                                   | `true`  | Show current-time indicator line          |
+| `renderItem`       | `((item: TimelineItem) => unknown) \| null` | `null`  | Custom render function for event content  |
+
+---
+
+### Events
+
+| Event              | Detail                               | Fires when                                                    |
+| ------------------ | ------------------------------------ | ------------------------------------------------------------- |
+| `change`           | `{ items: TimelineItem[] }`          | An item is moved or resized. Always write back to `tl.items`. |
+| `item-click`       | `{ item }`                           | An item is clicked                                            |
+| `item-dblclick`    | `{ item }`                           | An item is double-clicked                                     |
+| `item-hover`       | `{ item, type: 'enter' \| 'leave' }` | Pointer enters or leaves an item                              |
+| `item-contextmenu` | `{ item, x, y }`                     | An item is right-clicked                                      |
+| `item-dragstart`   | `{ item }`                           | Drag begins                                                   |
+| `item-dragend`     | `{ item, resourceId, start, end }`   | Drag released — final position                                |
+| `item-resizestart` | `{ item }`                           | Resize begins                                                 |
+| `item-resizeend`   | `{ item, start, end }`               | Resize released — final times                                 |
+| `item-create`      | `{ resourceId, start, end }`         | New item created via hold-to-create                           |
+| `date-change`      | `{ date }`                           | User navigated to a different day                             |
+
+---
+
+### CSS custom properties
+
+| Property                     | Default      | Description                               |
+| ---------------------------- | ------------ | ----------------------------------------- |
+| `--tl-font-family`           | `sans-serif` | Font used throughout the component        |
+| `--tl-bg`                    | `#ffffff`    | Background color                          |
+| `--tl-header-bg`             | `#f8fafc`    | Time header and nav bar background        |
+| `--tl-resource-col-width`    | `160px`      | Width of the resource label column        |
+| `--tl-resource-border-color` | `#e2e8f0`    | Border between resource rows              |
+| `--tl-grid-line-color`       | `#e2e8f0`    | Hour grid lines                           |
+| `--tl-text-color`            | `#1e293b`    | Primary text color                        |
+| `--tl-time-label-color`      | `#94a3b8`    | Hour labels in the header                 |
+| `--tl-item-radius`           | `4px`        | Border radius of event blocks             |
+| `--tl-item-text-color`       | `#ffffff`    | Text color inside event blocks            |
+| `--tl-item-opacity-dragging` | `0.4`        | Opacity of the source item while dragging |
+| `--tl-focus-color`           | `#3b82f6`    | Focus outline color                       |
+| `--tl-now-line-color`        | `#ef4444`    | Current-time indicator color              |
+| `--tl-create-ghost-color`    | `#3b82f6`    | Hold-to-create ghost block color          |
+| `--tl-tooltip-bg`            | `#1e293b`    | Tooltip background                        |
+| `--tl-tooltip-color`         | `#ffffff`    | Tooltip text color                        |
+
+---
+
+### TypeScript types
+
+```ts
+import type {
+  Resource,
+  TimelineItem,
+  ChangeDetail,
+  ItemClickDetail,
+  ItemDblClickDetail,
+  ItemHoverDetail,
+  ItemContextMenuDetail,
+  ItemDragStartDetail,
+  ItemDragEndDetail,
+  ItemResizeStartDetail,
+  ItemResizeEndDetail,
+  ItemCreateDetail,
+  DateChangeDetail,
+} from "timeline-scheduler";
+
+interface Resource {
+  id: string;
+  name: string;
+  avatar?: string; // URL — falls back to coloured initials
+}
+
+interface TimelineItem {
+  id: string;
+  resourceId: string;
+  name: string;
+  color: string; // any valid CSS color
+  start: Date;
+  end: Date;
+  description?: string; // shown in the hover tooltip
+}
+```
+
+---
+
+## Development
+
+```bash
+npm install
+npm run dev    # playground at localhost:5173
+npm test       # run tests
+npm run build  # build dist/
+```
+
+## License
+
+MIT

package/dist/components/tl-grid.d.ts

@@ -0,0 +1,12 @@
+import { LitElement } from 'lit';
+export declare class TlGrid extends LitElement {
+    startHour: number;
+    endHour: number;
+    static styles: import("lit").CSSResult;
+    render(): import("lit-html").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'tl-grid': TlGrid;
+    }
+}

package/dist/components/tl-item.d.ts

@@ -0,0 +1,73 @@
+import { LitElement } from 'lit';
+import type { TimelineItem } from '../types';
+export interface TlItemDragStartDetail {
+    item: TimelineItem;
+    pointerId: number;
+    clientX: number;
+    clientY: number;
+    itemClientLeft: number;
+    itemClientWidth: number;
+}
+export interface TlItemClickDetail {
+    item: TimelineItem;
+}
+export interface TlItemHoverDetail {
+    item: TimelineItem;
+    type: 'enter' | 'leave';
+}
+export interface TlItemResizeStartDetail {
+    item: TimelineItem;
+    edge: 'left' | 'right';
+    pointerId: number;
+    clientX: number;
+    itemClientLeft: number;
+    itemClientWidth: number;
+}
+export interface TlItemContextMenuDetail {
+    item: TimelineItem;
+    x: number;
+    y: number;
+}
+export interface TlItemKeyMoveDetail {
+    item: TimelineItem;
+    direction: 'left' | 'right';
+}
+export interface TlItemDblClickDetail {
+    item: TimelineItem;
+}
+export declare class TlItemElement extends LitElement {
+    item: TimelineItem;
+    dragEnabled: boolean;
+    resizable: boolean;
+    showTime: boolean;
+    showTooltip: boolean;
+    readonly: boolean;
+    /** Optional custom render function for item content. Replaces the default name + time display. */
+    renderContent: ((item: TimelineItem) => unknown) | null;
+    private _tooltipVisible;
+    private _tooltipRect;
+    private _downX;
+    private _downY;
+    private _downPointerId;
+    private _holdTimer;
+    private _lastClickTime;
+    static styles: import("lit").CSSResult;
+    render(): import("lit-html").TemplateResult<1>;
+    private _formatDuration;
+    private _onPointerDown;
+    private _onHoldMove;
+    private _onHoldUp;
+    private _onHoldCancel;
+    private _cleanHoldListeners;
+    private _startDrag;
+    private _onPointerEnter;
+    private _onPointerLeave;
+    private _onContextMenu;
+    private _onKeyDown;
+    private _onResizeStart;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'tl-item': TlItemElement;
+    }
+}