@timelinekit/core 1.0.0 → 1.0.3

package/LICENSE

@@ -1,6 +1,6 @@
 TimelineKit Commercial License
 
-Copyright (c) 2025 TimelineKit. All rights reserved.
+Copyright (c) 2026-present TimelineKit. All rights reserved.
 
 This software is licensed under the TimelineKit Commercial License.
 

package/README.md

@@ -0,0 +1,200 @@
+# @timelinekit/core
+
+The framework-agnostic engine behind [TimelineKit](https://timelinekit.com) — a suite of high-performance, canvas-rendered scheduling components for JavaScript and TypeScript.
+
+> **Note:** This package is not intended to be used directly. Install a framework wrapper instead:
+>
+> - **React:** [`@timelinekit/react`](https://www.npmjs.com/package/@timelinekit/react)
+> - **Angular:** [`@timelinekit/angular`](https://www.npmjs.com/package/@timelinekit/angular)
+>
+> `@timelinekit/core` is included automatically as a dependency and re-exports all types through the wrapper packages.
+
+## Components
+
+### Gantt Chart
+
+Interactive project timeline with canvas rendering for 60 fps performance.
+
+- Tasks, summary tasks, and milestones
+- Four dependency types (FS, SS, FF, SF) with lag/lead
+- Critical path analysis (CPM)
+- Baseline comparison with visual overlay
+- Resource management with overallocation detection
+- Working calendars (business days, holidays, shifts)
+- Markers and today line
+- Zoom levels from hours to years
+- Drag & drop editing with undo/redo
+- Filtering and keyboard navigation
+
+### Resource Scheduler
+
+Visual resource planning with drag-and-drop event scheduling.
+
+- Hierarchical resource lanes
+- Automatic multi-lane event stacking
+- Frozen (pinned) resource rows
+- Conflict detection for overlapping events
+- Time scales from hours to months
+- Custom event rendering
+- Drag & drop editing with undo/redo
+- Filtering and keyboard navigation
+
+### Event Calendar
+
+Full-featured calendar with month, week, day, and agenda views.
+
+- Recurring events (RFC 5545 RRULE with exceptions)
+- Multiple color-coded calendars
+- 9 built-in item types (Meeting, Appointment, Task, Deadline, Holiday, Birthday, Reminder, Resource Booking, Availability Block)
+- iCalendar (.ics) import and export
+- Mini calendar and sidebar
+- All-day events
+- Custom event rendering
+- Drag & drop editing with undo/redo
+- Keyboard navigation
+
+## Quick Start
+
+### React
+
+```bash
+npm install @timelinekit/react @timelinekit/core
+```
+
+```tsx
+import { useRef, useEffect } from 'react';
+import { GanttChart, GanttChartRef } from '@timelinekit/react';
+import { Task, TaskLink } from '@timelinekit/core';
+import '@timelinekit/core/styles';
+
+function App() {
+  const ref = useRef<GanttChartRef>(null);
+
+  useEffect(() => {
+    const gantt = ref.current!;
+    const taskA = gantt.list.addTask(new Task({ id: '1', name: 'Design', startTime: '2027-01-05', endTime: '2027-01-09' }));
+    const taskB = gantt.list.addTask(new Task({ id: '2', name: 'Development', startTime: '2027-01-12', endTime: '2027-01-23' }));
+    gantt.list.addLink(new TaskLink({ id: 'l1', from: taskA, to: taskB, type: 'finishToStart' }));
+    gantt.zoomToFit();
+  }, []);
+
+  return <GanttChart ref={ref} style={{ height: '600px' }} />;
+}
+```
+
+### Angular
+
+```bash
+npm install @timelinekit/angular @timelinekit/core
+```
+
+```typescript
+import { GanttChartComponent } from '@timelinekit/angular';
+import { Task, TaskLink } from '@timelinekit/core';
+
+@Component({
+  imports: [GanttChartComponent],
+  template: `<tk-gantt-chart #gantt style="height: 600px" />`,
+})
+export class AppComponent implements AfterViewInit {
+  @ViewChild('gantt') gantt!: GanttChartComponent;
+
+  ngAfterViewInit() {
+    const taskA = this.gantt.list.addTask(new Task({ id: '1', name: 'Design', startTime: '2027-01-05', endTime: '2027-01-09' }));
+    const taskB = this.gantt.list.addTask(new Task({ id: '2', name: 'Development', startTime: '2027-01-12', endTime: '2027-01-23' }));
+    this.gantt.list.addLink(new TaskLink({ id: 'l1', from: taskA, to: taskB, type: 'finishToStart' }));
+    this.gantt.zoomToFit();
+  }
+}
+```
+
+## Styles
+
+Import the combined stylesheet for all components:
+
+```typescript
+import '@timelinekit/core/styles';
+```
+
+Or import individual component styles for smaller bundles:
+
+```typescript
+import '@timelinekit/core/styles/gc';    // Gantt Chart
+import '@timelinekit/core/styles/rs';    // Resource Scheduler
+import '@timelinekit/core/styles/ec';    // Event Calendar
+```
+
+SCSS sources are also available for custom builds:
+
+```scss
+@use '@timelinekit/core/styles/scss';        // All components
+@use '@timelinekit/core/styles/gc/scss';     // Gantt Chart
+@use '@timelinekit/core/styles/rs/scss';     // Resource Scheduler
+@use '@timelinekit/core/styles/ec/scss';     // Event Calendar
+```
+
+## Themes
+
+Four built-in themes for each component, fully customizable via CSS variables:
+
+| Theme | Gantt Chart | Resource Scheduler | Event Calendar |
+|-------|-------------|--------------------|----------------|
+| Light | `LightGanttChartTheme` | `LightSchedulerTheme` | `LightEventCalendarTheme` |
+| Dark | `DarkGanttChartTheme` | `DarkSchedulerTheme` | `DarkEventCalendarTheme` |
+| Modern | `ModernGanttChartTheme` | `ModernSchedulerTheme` | — |
+| Classic | `ClassicGanttChartTheme` | `ClassicSchedulerTheme` | — |
+
+## Localization
+
+English is included by default. Additional locales are available as separate imports:
+
+```typescript
+import { csLocale } from '@timelinekit/core/locales/cs';
+```
+
+| Code | Language | Code | Language |
+|------|----------|------|----------|
+| `cs` | Czech | `ko` | Korean |
+| `de` | German | `nl` | Dutch |
+| `es` | Spanish | `pl` | Polish |
+| `fr` | French | `pt` | Portuguese |
+| `it` | Italian | `ru` | Russian |
+| `ja` | Japanese | `sv` | Swedish |
+| | | `zh` | Chinese |
+
+## Export
+
+All components support export to multiple formats (requires optional peer dependencies for some formats):
+
+- **PNG** — requires `html2canvas` (Event Calendar only; Gantt and Scheduler use built-in canvas export)
+- **PDF** — requires `jspdf` (and `html2canvas` for Event Calendar)
+- **CSV** — built-in
+- **Excel** — requires `exceljs`
+- **ICS** — Event Calendar only, built-in
+
+## Licensing
+
+TimelineKit uses a commercial license with a free tier.
+
+**Free** — All components and all features with a "TimelineKit.com" watermark. No license key required.
+
+**Pro** — Remove the watermark and get email support. Licenses are per-developer and perpetual for the major version.
+
+```typescript
+import { setLicense } from '@timelinekit/core';
+
+setLicense('your-license-key');
+```
+
+See [pricing](https://timelinekit.com/pricing) for details.
+
+## Resources
+
+- [Documentation](https://timelinekit.com/docs)
+- [Live Demos](https://timelinekit.com/gantt-chart/demo)
+- [Examples](https://github.com/timelinekit/examples)
+- [Support](mailto:support@timelinekit.com)
+
+## License
+
+See [LICENSE](./LICENSE) for details.

package/dist/__tests__/calendar/sidebar/calendar-list.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/calendar/sidebar/mini-calendar.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/calendar/test-helpers.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Shared DOM shim and factory functions for EventCalendar tests.
+ * No jsdom required — provides a MinimalElement that covers all DOM APIs
+ * used by views, drag handlers, and keyboard navigation.
+ */
+import { EventCalendarContext } from '../../calendar/eventcalendar-context';
+import { Calendar } from '../../calendar/model/calendar';
+import { CalendarEntry } from '../../calendar/model/calendar-entry';
+import { Meeting, Appointment, type CalendarItem } from '../../calendar/model/calendar-item';
+export declare class MinimalCSSStyleDeclaration {
+    #private;
+    visibility: string;
+    display: string;
+    fontFamily: string;
+    fontSize: string;
+    top: string;
+    left: string;
+    height: string;
+    width: string;
+    backgroundColor: string;
+    color: string;
+    borderLeft: string;
+    cursor: string;
+    position: string;
+    setProperty(name: string, value: string): void;
+    getPropertyValue(name: string): string;
+    [key: string]: any;
+}
+export interface BoundingRect {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+    right: number;
+    bottom: number;
+}
+export declare class MinimalElement {
+    #private;
+    tagName: string;
+    className: string;
+    id: string;
+    tabIndex: number;
+    textContent: string;
+    offsetHeight: number;
+    offsetWidth: number;
+    scrollTop: number;
+    dataset: Record<string, string>;
+    style: MinimalCSSStyleDeclaration;
+    children: MinimalElement[];
+    childNodes: MinimalElement[];
+    parentNode: MinimalElement | null;
+    parentElement: MinimalElement | null;
+    get innerHTML(): string;
+    set innerHTML(value: string);
+    get firstElementChild(): MinimalElement | null;
+    classList: {
+        add: (...classes: string[]) => void;
+        remove: (...classes: string[]) => void;
+        contains: (c: string) => boolean;
+        toggle: (c: string, force?: boolean) => void;
+        readonly length: number;
+    };
+    constructor(tag: string);
+    setAttribute(name: string, value: string): void;
+    getAttribute(name: string): string | null;
+    removeAttribute(name: string): void;
+    appendChild(child: any): any;
+    removeChild(child: any): any;
+    remove(): void;
+    cloneNode(deep?: boolean): MinimalElement;
+    querySelector(selector: string): MinimalElement | null;
+    querySelectorAll(selector: string): MinimalElement[];
+    closest(selector: string): MinimalElement | null;
+    addEventListener(type: string, handler: Function, _options?: any): void;
+    removeEventListener(type: string, handler: Function): void;
+    dispatchEvent(event: any): boolean;
+    focus(): void;
+    setPointerCapture(_pointerId: number): void;
+    releasePointerCapture(_pointerId: number): void;
+    attachShadow(_init: any): MinimalElement;
+    getBoundingClientRect(): BoundingRect;
+    /** Set the bounding rect returned by getBoundingClientRect(). */
+    setBoundingRect(rect: Partial<BoundingRect>): void;
+}
+export declare class MinimalTextNode {
+    textContent: string;
+    constructor(text: string);
+}
+/** Install global document/ResizeObserver/requestAnimationFrame shims. */
+export declare function installDomShim(): void;
+/** Create a minimal EventCalendarContext for testing. */
+export declare function createTestContext(opts?: {
+    currentDate?: Date;
+    firstDayOfWeek?: number;
+    slotDuration?: number;
+    workingHours?: {
+        start: number;
+        end: number;
+    };
+    canEdit?: boolean;
+}): EventCalendarContext;
+export declare function createTestCalendar(id: string, opts?: {
+    name?: string;
+    color?: number;
+    isDefault?: boolean;
+    isVisible?: boolean;
+}): Calendar;
+export declare function createTestMeeting(id: string, calendarId: string, opts?: {
+    title?: string;
+    startTime?: Date;
+    endTime?: Date;
+    isAllDay?: boolean;
+    color?: number;
+    location?: string;
+    responseStatus?: 'accepted' | 'tentative' | 'needsAction' | 'declined';
+}): {
+    item: Meeting;
+    entry: CalendarEntry;
+};
+export declare function createTestAppointment(id: string, calendarId: string, opts?: {
+    title?: string;
+    startTime?: Date;
+    endTime?: Date;
+    isAllDay?: boolean;
+}): {
+    item: Appointment;
+    entry: CalendarEntry;
+};
+export interface TestScenario {
+    ec: EventCalendarContext;
+    calendar: Calendar;
+    items: CalendarItem[];
+    entries: CalendarEntry[];
+}
+/** Creates a context with one calendar and a set of meetings for a given week. */
+export declare function createWeekScenario(opts?: {
+    currentDate?: Date;
+    firstDayOfWeek?: number;
+}): TestScenario;
+export declare function createPointerEvent(type: string, opts?: {
+    clientX?: number;
+    clientY?: number;
+    button?: number;
+    ctrlKey?: boolean;
+    metaKey?: boolean;
+    pointerId?: number;
+    pointerType?: string;
+    isPrimary?: boolean;
+}): any;
+/** @deprecated Use createPointerEvent instead. Kept for non-drag tests. */
+export declare function createMouseEvent(type: string, opts?: {
+    clientX?: number;
+    clientY?: number;
+    button?: number;
+    ctrlKey?: boolean;
+    metaKey?: boolean;
+}): any;
+export declare function createKeyboardEvent(type: string, key: string, opts?: {
+    ctrlKey?: boolean;
+    metaKey?: boolean;
+    shiftKey?: boolean;
+}): any;
+/** Creates a grid of MinimalElement cells with sequential bounding rects. */
+export declare function createCellGrid(rows: number, cols: number, opts?: {
+    cellWidth?: number;
+    cellHeight?: number;
+    startX?: number;
+    startY?: number;
+}): MinimalElement[];

package/dist/__tests__/calendar/tooltip/calendar-tooltip-renderer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/calendar/validation.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/calendar/views/agenda-view.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/calendar/views/day-view.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/calendar/views/drag-handlers.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/calendar/views/keyboard-navigation.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/calendar/views/month-view.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/calendar/views/swipe-navigation-handler.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/calendar/views/time-grid-helper.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/calendar/views/view-utils.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/calendar/views/week-view.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/ganttchart/model/dependency-evaluator.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/ganttchart/model/task-filters.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/ganttchart/model/task-link.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/calendar/clipboard/calendar-clipboard.d.ts

@@ -0,0 +1,19 @@
+import type { EventCalendarContext } from "../eventcalendar-context";
+import type { CalendarEntry } from "../model/calendar-entry";
+import { type CalendarItem } from "../model/calendar-item";
+/** Emitted after a paste operation completes. */
+export interface CalendarEntriesPastedEventArgs {
+    /** Newly created items. */
+    items: CalendarItem[];
+}
+/** Handles copy, cut, and paste of calendar entries via internal buffer and system clipboard. */
+export declare class CalendarClipboardManager {
+    #private;
+    constructor(ec: EventCalendarContext);
+    /** Copy entries to the internal buffer and system clipboard (as TSV). */
+    copy(entries: CalendarEntry[]): Promise<void>;
+    /** Copy entries to the clipboard and remove the original items. */
+    cut(entries: CalendarEntry[]): Promise<void>;
+    /** Paste entries from the internal buffer. Shift times relative to targetDate. */
+    paste(targetDate: Date): Promise<CalendarEntriesPastedEventArgs | null>;
+}

package/dist/calendar/eventcalendar-context.d.ts

@@ -0,0 +1,157 @@
+import { BehaviorSubject, Subject } from "rxjs";
+import type { TimelineKitLocale } from "../common/locale";
+import type { Calendar } from "./model/calendar";
+import { CalendarData } from "./model/calendar-data";
+import { CalendarEntry } from "./model/calendar-entry";
+import type { EventCalendarEntryColor } from "./themes/eventcalendar-theme";
+import { EventCalendarTheme } from "./themes/eventcalendar-theme";
+import { EventCalendarSettings } from "./eventcalendar-settings";
+/** Calendar view modes. */
+export type ViewMode = 'month' | 'week' | 'day' | 'agenda';
+/** Event args for entry interaction events. */
+export interface EntryEventArgs {
+    entry: CalendarEntry;
+    domEvent: MouseEvent;
+}
+/** Event args for entry context menu. */
+export interface EntryContextMenuArgs {
+    entry: CalendarEntry;
+    domEvent: MouseEvent;
+}
+/** Event args for clicking the "+N more" label in month view. */
+export interface MoreClickArgs {
+    date: Date;
+    entries: CalendarEntry[];
+}
+/** Event args for clicking an empty date area. */
+export interface DateClickArgs {
+    date: Date;
+    isAllDay: boolean;
+    domEvent: MouseEvent;
+}
+/** Event args for right-clicking an empty date area. */
+export interface DateContextMenuArgs {
+    date: Date;
+    isAllDay: boolean;
+    entry: CalendarEntry | null;
+    domEvent: MouseEvent;
+}
+/** Event args for entry drag/move. Cancelable. */
+export interface EntryMovingArgs {
+    entry: CalendarEntry;
+    newStartTime: Date;
+    newEndTime: Date;
+    cancel: boolean;
+}
+/** Event args for entry resize. Cancelable. */
+export interface EntryResizingArgs {
+    entry: CalendarEntry;
+    newStartTime: Date;
+    newEndTime: Date;
+    edge: 'start' | 'end';
+    cancel: boolean;
+}
+/** Event args for entry creation via drag on empty area. Cancelable. */
+export interface EntryCreatingArgs {
+    startTime: Date;
+    endTime: Date;
+    isAllDay: boolean;
+    cancel: boolean;
+}
+/** Event args for entry deletion. Cancelable. */
+export interface EntryDeletingArgs {
+    entry: CalendarEntry;
+    /** Whether the entry belongs to a recurring series. */
+    isRecurring: boolean;
+    /**
+     * Scope of deletion for recurring entries: 'this' | 'thisAndFollowing' | 'all'.
+     * Defaults to 'all' for non-recurring entries.
+     * Subscribers can change this before the engine processes the deletion.
+     */
+    scope: 'this' | 'thisAndFollowing' | 'all';
+    cancel: boolean;
+}
+/** Event args for calendar removal. Cancelable. */
+export interface CalendarRemovingArgs {
+    calendar: Calendar;
+    cancel: boolean;
+}
+/** Arguments passed to the custom entry rendering callback. */
+export interface EntryRenderArgs {
+    /** The calendar entry being rendered. */
+    entry: CalendarEntry;
+    /** The DOM element for the entry. Modify its content/style to customize rendering. */
+    element: HTMLElement;
+    /** Whether this entry is rendered in an all-day section. */
+    isAllDay: boolean;
+    /** Current view mode. */
+    viewMode: ViewMode;
+    /** Resolved color for this entry. */
+    color: EventCalendarEntryColor;
+}
+/** Custom entry rendering function. Called after default content is rendered.
+ *  Return true if you handled the rendering (default content will be cleared first),
+ *  or false/undefined to keep the default rendering. */
+export type EntryRenderFn = (args: EntryRenderArgs) => boolean | void;
+/** Arguments passed to the custom tooltip callback. */
+export interface EntryTooltipArgs {
+    /** The calendar entry being hovered. */
+    entry: CalendarEntry;
+    /** Current view mode. */
+    viewMode: ViewMode;
+}
+/** Content to display in an entry tooltip. */
+export interface EntryTooltipContent {
+    /** Tooltip title. */
+    title: string;
+    /** Key-value rows displayed below the title. */
+    rows?: {
+        label: string;
+        value: string;
+    }[];
+}
+/** Custom tooltip function. Return content to display, or null to hide the tooltip. */
+export type EntryTooltipFn = (args: EntryTooltipArgs) => EntryTooltipContent | null | Promise<EntryTooltipContent | null>;
+/** Internal shared state for all EventCalendar sub-components. */
+export declare class EventCalendarContext {
+    data: CalendarData;
+    currentDate$: BehaviorSubject<Date>;
+    viewMode$: BehaviorSubject<ViewMode>;
+    locale$: BehaviorSubject<TimelineKitLocale>;
+    theme$: BehaviorSubject<EventCalendarTheme>;
+    firstDayOfWeek$: BehaviorSubject<number>;
+    workingHours$: BehaviorSubject<{
+        start: number;
+        end: number;
+    }>;
+    slotDuration$: BehaviorSubject<number>;
+    showWeekNumbers$: BehaviorSubject<boolean>;
+    agendaDays$: BehaviorSubject<number>;
+    canEdit$: BehaviorSubject<boolean>;
+    sidebarVisible$: BehaviorSubject<boolean>;
+    selectedEntries$: BehaviorSubject<CalendarEntry[]>;
+    hoveredEntry$: BehaviorSubject<CalendarEntry | null>;
+    entryRendering$: BehaviorSubject<EntryRenderFn | null>;
+    entryTooltip$: BehaviorSubject<EntryTooltipFn | null>;
+    entryClick$: Subject<EntryEventArgs>;
+    entryDblClick$: Subject<EntryEventArgs>;
+    entryContextMenu$: Subject<EntryContextMenuArgs>;
+    dateClick$: Subject<DateClickArgs>;
+    dateContextMenu$: Subject<DateContextMenuArgs>;
+    moreClick$: Subject<MoreClickArgs>;
+    entryMoving$: Subject<EntryMovingArgs>;
+    entryResizing$: Subject<EntryResizingArgs>;
+    entryCreating$: Subject<EntryCreatingArgs>;
+    entryDeleting$: Subject<EntryDeletingArgs>;
+    /** Emitted when the user clicks "Add calendar" in the sidebar. Host app should handle creation. */
+    calendarAddRequested$: Subject<void>;
+    /** Emitted before a calendar is removed via the sidebar. Set cancel=true to prevent removal. */
+    calendarRemoving$: Subject<CalendarRemovingArgs>;
+    /** Emitted when the visible date range changes (e.g. navigation, view switch). */
+    viewDateRangeChanged$: Subject<{
+        start: Date;
+        end: Date;
+    }>;
+    settings: EventCalendarSettings;
+    constructor();
+}