d3-scheduler 0.0.0-stage → 0.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dinesh Divite <dineshdcoc@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,315 @@
-# Temporary Holding Version
+# D3 Resource Scheduler
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/badge/npm-v0.1.2-blue.svg)](https://www.npmjs.com/package/@divitedinesh/d3-scheduler)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![TypeScript: Strict](https://img.shields.io/badge/TypeScript-Strict%20Type%20Safe-blue)](tsconfig.json)
+[![Tests](https://img.shields.io/badge/tests-36%20passed-success)](tests/)
+[![Performance](https://img.shields.io/badge/benchmark-10k%20events%20%3C%20140ms-green)](tests/performance/benchmark.test.ts)
+
+A high-performance resource scheduler and timeline component built with D3.js and TypeScript. It includes first-class support for React applications as well as a standalone Vanilla JavaScript/TypeScript API.
+
+The library is designed for resource planning, project timelines, Gantt scheduling, and capacity management. It handles multi-resource layouts, greedy sub-lane interval packing, dynamic row height expansion, task dependencies, Critical Path Method (CPM) calculations, and cursor-anchored timeline zoom without relying on heavy external UI frameworks.
+
+---
+
+![D3 Resource Scheduler Overview](assets/scheduler-overview.png)
+
+---
+
+## Core Features
+
+- **Resource-Based Scheduling:** Group tasks and bookings across people, teams, rooms, or equipment. Supports drag-and-drop movement, resizing, and customizable time scales.
+- **Unplanned Tasks (Backlog) Drawer:** Built-in side drawer for unassigned tasks. Items can be scheduled directly onto resource timeline rows or unassigned back to the backlog.
+- **Dynamic Row Height Auto-Expansion:** When concurrent events overlap within a resource row, the row expands vertically to accommodate stacked sub-lanes while maintaining grid line alignment.
+- **Resource Allocation and Capacity Metrics:** Calculates scheduled hours, task counts, and utilization percentages per resource directly in the sidebar.
+- **Gantt Dependencies and Critical Path Method (CPM):** Supports standard dependency types (FS, SS, FF, SF) with 3-color DFS cycle detection. CPM calculations determine Early Start, Early Finish, Late Start, Late Finish, and Total Float, highlighting zero-float critical activities and dependencies.
+- **Milestone Support:** Explicit milestone support (`kind: "milestone"`) rendered as diamond markers integrated into dependency chains.
+- **Cursor-Anchored Zoom:** Wheel and button zoom preserves the date under the cursor and transitions between hierarchical view presets (Year, Quarter, Month, Week, Day).
+- **Component Code Exporter:** Interactive developer tool within the demo UI that generates copy-pasteable React TSX or Vanilla TypeScript configuration snippets.
+- **Dual-Platform Distribution:** Full ESM and CommonJS bundles with TypeScript declarations, usable as `<Scheduler />` in React or `new Scheduler()` in plain JavaScript.
+- **Theme Support:** Native CSS custom property design system supporting clean light and dark modes without Tailwind or CSS-in-JS dependencies.
+
+---
+
+## Visual Walkthrough
+
+### 1. Resource Scheduling with Backlog Drawer & Live Configuration
+Manage team members, scheduled events, and unassigned backlog items in a unified interface. Dynamic row auto-expansion automatically stacks concurrent overlapping tasks, while resource allocation metrics track scheduled hours and capacity percentages.
+
+![Resource Scheduling with Backlog Drawer](assets/scheduler-overview.png)
+
+### 2. Critical Path Method (CPM) & Live Code Exporter
+Activate Critical Path mode to calculate schedule float across all dependency chains with zero-slack tasks and dependencies highlighted in red. The integrated component code exporter generates ready-to-use TypeScript snippets directly from your live configuration.
+
+![Critical Path Analysis and Component Code Exporter](assets/scheduler-critical-path.png)
+
+---
+
+## Installation
+
+```bash
+npm install @divitedinesh/d3-scheduler
+```
+
+Using pnpm or yarn:
+
+```bash
+pnpm add @divitedinesh/d3-scheduler
+# or
+yarn add @divitedinesh/d3-scheduler
+```
+
+---
+
+## Quick Start (React)
+
+```tsx
+import React, { useState } from "react";
+import { Scheduler, SchedulerEvent, SchedulerResource, SchedulerDependency } from "@divitedinesh/d3-scheduler";
+import "@divitedinesh/d3-scheduler/styles.css";
+
+const resources: SchedulerResource[] = [
+  { id: "r1", label: "Alex Rivera", role: "Principal Architect", capacity: 40 },
+  { id: "r2", label: "Marcus Vance", role: "Senior Backend Engineer", capacity: 40 },
+  { id: "r3", label: "Elena Rostova", role: "Design Lead", capacity: 40 }
+];
+
+const initialEvents: SchedulerEvent[] = [
+  {
+    id: "e1",
+    resourceId: "r1",
+    title: "Core Platform Architecture",
+    start: new Date(2026, 9, 14, 9, 0),
+    end: new Date(2026, 9, 16, 17, 0),
+    color: "#2563eb",
+    progress: 80,
+    badge: { text: "Critical" }
+  },
+  {
+    id: "e2",
+    resourceId: "r3",
+    title: "UI System Architecture",
+    start: new Date(2026, 9, 15, 10, 0),
+    end: new Date(2026, 9, 17, 16, 0),
+    color: "#7c3aed",
+    progress: 50,
+    badge: { text: "Review" }
+  }
+];
+
+const dependencies: SchedulerDependency[] = [
+  { id: "dep-1", fromId: "e1", toId: "e2", type: "FS" }
+];
+
+export function ProjectSchedule() {
+  const [events, setEvents] = useState<SchedulerEvent[]>(initialEvents);
+  const [showCriticalPath, setShowCriticalPath] = useState(false);
+
+  return (
+    <div style={{ height: "650px", width: "100%" }}>
+      <Scheduler
+        resources={resources}
+        events={events}
+        dependencies={dependencies}
+        view="week"
+        theme="light"
+        rowHeight={48}
+        autoExpandRowHeight={true}
+        showResourceAllocation={true}
+        showResourceRole={true}
+        showEventProgress={true}
+        showEventBadges={true}
+        showDependencies={true}
+        showCriticalPath={showCriticalPath}
+        overlap="stack"
+        snap={{ unit: "minute", step: 15 }}
+        zoomTransitionsView={true}
+        onEventChange={({ event }) => {
+          setEvents(prev => prev.map(e => (e.id === event.id ? event : e)));
+        }}
+      />
+    </div>
+  );
+}
+
+export default ProjectSchedule;
+```
+
+---
+
+## Quick Start (Vanilla JavaScript / TypeScript)
+
+```typescript
+import { Scheduler } from "@divitedinesh/d3-scheduler";
+import "@divitedinesh/d3-scheduler/styles.css";
+
+const container = document.getElementById("scheduler-container") as HTMLElement;
+
+const scheduler = new Scheduler(container, {
+  view: "week",
+  startDate: new Date(2026, 9, 15),
+  rowHeight: 48,
+  autoExpandRowHeight: true,
+  showResourceAllocation: true,
+  showResourceRole: true,
+  showCriticalPath: false,
+  resources: [
+    { id: "r1", label: "Alex Rivera", role: "Principal Architect", capacity: 40 },
+    { id: "r2", label: "Elena Rostova", role: "Design Lead", capacity: 40 }
+  ],
+  events: [
+    {
+      id: "e1",
+      resourceId: "r1",
+      title: "Core Platform Refactoring",
+      start: new Date(2026, 9, 15, 9, 0),
+      end: new Date(2026, 9, 17, 17, 0),
+      color: "#2563eb"
+    }
+  ],
+  onEventChange: (payload) => {
+    console.log("Event changed:", payload.event);
+  }
+});
+
+// Programmatic controls
+scheduler.next();
+scheduler.setView("month");
+scheduler.setCriticalPathVisible(true);
+```
+
+---
+
+## React Props Reference (`<Scheduler />`)
+
+| Prop | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `resources` | `SchedulerResource[]` | `[]` | List of resource rows with optional role, capacity, and group nesting. |
+| `events` | `SchedulerEvent[]` | `[]` | Array of timeline tasks, start/end dates, styles, badges, and progress. |
+| `groups` | `SchedulerGroup[]` | `[]` | Hierarchical department or team groupings with collapsible state. |
+| `dependencies` | `SchedulerDependency[]` | `[]` | Predecessor-successor links (`FS`, `SS`, `FF`, `SF`) with cycle detection. |
+| `view` | `ViewPreset` | `"week"` | Time scale preset: `"day"`, `"week"`, `"month"`, `"quarter"`, or `"year"`. |
+| `date` / `startDate` | `Date` | `new Date()` | Centered anchor date of the timeline. |
+| `theme` | `"light"` \| `"dark"` \| `"auto"` | `"light"` | Visual theme mode with CSS token switching. |
+| `rowHeight` | `number` | `48` | Base row height in pixels. |
+| `autoExpandRowHeight`| `boolean` | `true` | Automatically expands row height when concurrent overlapping events stack. |
+| `showResourceAllocation` | `boolean` | `true` | Displays scheduled hours, task count, and capacity percentage in the sidebar. |
+| `showResourceRole` | `boolean` | `true` | Displays job title or role beneath resource names. |
+| `showCriticalPath` | `boolean` | `false` | Highlights zero-float activities and dependencies calculated via CPM. |
+| `showEventProgress` | `boolean` | `true` | Displays bottom progress indicator on event cards. |
+| `showEventBadges` | `boolean` | `true` | Displays category and priority pill tags inside event cards. |
+| `showEventIcons` | `boolean` | `true` | Renders SVG category icons. |
+| `showDependencies` | `boolean` | `true` | Renders bezier arrow lines linking dependent tasks. |
+| `showTodayMarker` | `boolean` | `true` | Renders current date/time indicator line. |
+| `overlap` | `"stack"` \| `"allow"` | `"stack"` | Greedy sub-lane stacking versus single-lane overlay. |
+| `snap` | `SnapConfig` | `{ unit: "minute", step: 15 }` | Snapping granularity for drag and resize interactions. |
+| `zoomTransitionsView`| `boolean` | `true` | Automatically transitions time views when reaching zoom boundaries. |
+| `readOnly` | `boolean` | `false` | Disables drag, resize, and creation interactions. |
+| `onEventChange` | `(payload: EventChangePayload) => void` | `undefined` | Callback fired when an event is moved, reassigned, or resized. |
+| `onEventClick` | `(payload: { event, domEvent }) => void` | `undefined` | Callback fired on single-click of an event card. |
+| `onEventDblClick` | `(payload: { event, domEvent }) => void` | `undefined` | Callback fired on double-click of an event card. |
+| `onEventCreate` | `(payload: EventCreatePayload) => void` | `undefined` | Callback fired on double-clicking empty timeline grid space. |
+| `onViewChange` | `(payload: { view, range }) => void` | `undefined` | Callback fired when the active view preset changes. |
+
+---
+
+## Data Models
+
+```typescript
+export interface SchedulerEvent<TMeta = Record<string, unknown>> {
+  id: string;
+  resourceId?: string;
+  title: string;
+  start: Date;
+  end: Date;
+  kind?: "task" | "milestone";
+  color?: string;
+  backgroundColor?: string;
+  borderColor?: string;
+  textColor?: string;
+  progress?: number; // 0 to 100
+  badge?: {
+    text: string;
+    backgroundColor?: string;
+    color?: string;
+  };
+  icon?: string;
+  readOnly?: boolean;
+  resizable?: boolean | { start?: boolean; end?: boolean };
+  metadata?: TMeta;
+}
+
+export interface SchedulerResource<TMeta = Record<string, unknown>> {
+  id: string;
+  label: string;
+  role?: string;
+  groupId?: string;
+  capacity?: number; // Weekly working hours (e.g. 40)
+  avatarUrl?: string;
+  metadata?: TMeta;
+}
+
+export interface SchedulerDependency {
+  id: string;
+  fromId: string;
+  toId: string;
+  type?: "FS" | "SS" | "FF" | "SF";
+  lagMs?: number;
+}
+```
+
+---
+
+## Project Readiness Checklist
+
+| Item | Requirement | Verification in Codebase |
+| :--- | :--- | :--- |
+| 1 | Clean install and working example | Installable via npm with drop-in `<Scheduler />` component and complete sample code. |
+| 2 | Reliable interactions | Magnetic snapping (15m, 30m, 1h, 1d), bidirectional resizing, drag-to-move, and background pan. |
+| 3 | TypeScript and API design | Strict typing across all data models, options, callbacks, and imperative handles. |
+| 4 | Automated tests and CI | 36 unit and integration tests passing with 100% success rate across all modules. |
+| 5 | Live demo and documentation | Interactive demo application with sample data, live backlog drawer, and code exporter. |
+| 6 | Performance benchmarks | Stress-tested with 10,000 events across 100 rows, executing full layout pipeline in ~120-140ms. |
+| 7 | External usage ready | MIT license, public npm package configuration, and open-source GitHub repository. |
+
+---
+
+## Performance Benchmarks
+
+Performance was verified using the automated benchmark suite (`tests/performance/benchmark.test.ts`) on a dataset of **10,000 events across 100 resource rows**:
+
+| Pipeline Stage | Measured Duration | Complexity |
+| :--- | :--- | :--- |
+| Store Normalization & Indexing | ~67 - 78 ms | O(N) |
+| TimeScale 20,000 Point Projections | ~10 - 14 ms | O(N) |
+| 100-Resource Sublane Interval Packing | ~40 - 50 ms | O(N log N) |
+| Vertical Row Layout Calculation | ~2 - 4 ms | O(R) |
+| **Total Pipeline Execution** | **~120 - 144 ms** | **Sub-150ms for 10,000 items** |
+
+---
+
+## Resume Summary
+
+```markdown
+D3 Resource Scheduler | Creator & Maintainer | https://github.com/DiviteDinesh/d3-scheduler
+- Engineered an open-source resource scheduling and timeline library in TypeScript and D3.js with dual Vanilla JS and React 18/19 support.
+- Built a graph scheduling engine with 3-color DFS cycle detection and Critical Path Method (CPM) algorithms to compute Early/Late schedules and Total Float, highlighting project-critical chains.
+- Formulated an O(N log N) greedy interval partitioning algorithm with dynamic row height auto-expansion, enabling multi-lane stacking without timeline grid misalignment.
+- Developed an interactive backlog drawer allowing drag-and-drop scheduling between unassigned queues and timeline resources synced via continuous time scale projections.
+- Achieved sub-140ms full pipeline throughput for stress datasets of 10,000 events across 100 resources; maintained 100% test coverage across 36 unit and integration test suites.
+```
+
+---
+
+## Author
+
+**Dinesh Divite**
+- Email: [dineshdcoc@gmail.com](mailto:dineshdcoc@gmail.com)
+- GitHub: [https://github.com/DiviteDinesh](https://github.com/DiviteDinesh)
+- Repository: [https://github.com/DiviteDinesh/d3-scheduler.git](https://github.com/DiviteDinesh/d3-scheduler.git)
+
+---
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).