blixify-ui-web-mcp 0.1.2 → 0.1.3

package/lib/components/chart/ganttChart/README.md

@@ -4,100 +4,82 @@
 
 <hr>
 
-A Gantt chart component for displaying project timelines and task management. e.g: Project schedules, task dependencies, and progress tracking
+A horizontal range bar chart for visualising project timelines. Supports read-only display, an editable write mode with an inline task table, date range filtering, dark mode, and click callbacks.
 
 ##### Import
 
 ```js
-import { GanttChart } from "blixify-ui-web/lib";
+import { GanttChart } from "blixify-ui-web/components/chart/ganttChart";
 ```
 
 ##### Usage
 
-```jsx
-const [ganttTasks, setGanttTasks] = useState<any[]>([]);
+Read mode (display only):
 
-const sampleTasks = [
+```jsx
+const [tasks, setTasks] = useState([
   {
     id: "task1",
-    name: "Project Planning",
-    start: new Date(Date.now() - 5 * 24 * 60 * 60 * 1000),
-    end: new Date(Date.now() - 3 * 24 * 60 * 60 * 1000),
-    duration: 2,
-    progress: 100,
-    color: "#008FFB", // Individual task color
+    name: "Planning",
+    start: new Date("2024-01-01"),
+    end: new Date("2024-01-05"),
   },
   {
     id: "task2",
-    name: "Design Phase",
-    start: new Date(Date.now() - 3 * 24 * 60 * 60 * 1000),
-    end: new Date(Date.now() + 2 * 24 * 60 * 60 * 1000),
-    duration: 5,
-    progress: 75,
-    color: "#00E396", // Individual task color
-    dependencies: ["task1"],
-  },
-  {
-    id: "task3",
     name: "Development",
-    start: new Date(),
-    end: new Date(Date.now() + 10 * 24 * 60 * 60 * 1000),
-    duration: 10,
-    progress: 40,
-    color: "#FEB019", // Individual task color
-    dependencies: ["task2"],
+    start: new Date("2024-01-05"),
+    end: new Date("2024-01-15"),
   },
-];
-
-const handleTaskClick = useCallback((taskId: string, taskName: string) => {
-  console.log(`Clicked task: ${taskName} (ID: ${taskId})`);
-}, []);
-
-useEffect(() => {
-  setGanttTasks(sampleTasks);
-}, []);
-
-return (
-  <>
-    <div className="font-medium mb-5">Gantt Chart</div>
-    <GanttChart
-      title="Project Timeline"
-      tasks={ganttTasks}
-      tool={<CalendarIcon className="h-4 w-4 text-primary-600" />}
-      dateRangeVisible={true}
-      customDate={{
-        startDate: sevenDaysAgo,
-        endDate: fourteenDaysFromNow,
-        isDuration: true,
-      }}
-      onChangeDate={handleDateRangeChange}
-      onClick={handleTaskClick}
-      showDataLabel={true}
-      showTooltip={true}
-      colors={["#008FFB", "#00E396", "#FEB019", "#FF4560", "#775DD0"]}
-    />
-
-    {/*
-      Color mapping:
-      - Task 1 (Project Planning) → #008FFB (first color)
-      - Task 2 (Design Phase) → #00E396 (second color)
-      - Task 3 (Development) → #FEB019 (third color)
-      - Task 4 (Testing) → #FF4560 (fourth color)
-      - Task 5 (Deployment) → #775DD0 (fifth color)
-    */}
-
-    <div className="font-medium my-5">Dark Mode Gantt Chart</div>
-    <GanttChart
-      title="Development Sprint"
-      tasks={ganttTasks.slice(1, 3)}
-      onClick={handleTaskClick}
-      darkMode={true}
-      darkModeBg="bg-gradient-to-r from-slate-700 to-gray-900"
-      enableGradient={true}
-      colors={["#3B82F6", "#10B981", "#F59E0B", "#EF4444", "#8B5CF6"]}
-    />
-  </>
-);
+]);
+
+<GanttChart
+  title="Project Timeline"
+  tasks={tasks}
+  showTooltip={true}
+  showDataLabel={true}
+  dateRangeVisible={true}
+  onClick={(taskId, taskName) => console.log(taskId, taskName)}
+/>;
+```
+
+Write mode (editable table + chart):
+
+```jsx
+<GanttChart
+  title="Project Timeline"
+  tasks={tasks}
+  mode="write"
+  label="Tasks"
+  onTaskChange={(updatedTasks) => setTasks(updatedTasks)}
+  onClick={(taskId, taskName) => console.log(taskId, taskName)}
+/>
+```
+
+Dark mode:
+
+```jsx
+<GanttChart
+  title="Sprint"
+  tasks={tasks}
+  darkMode={true}
+  darkModeBg="bg-gray-900"
+  borderColor="#374151"
+  enableGradient={true}
+  colors={["#3B82F6", "#10B981", "#F59E0B"]}
+/>
+```
+
+Chart only (no card wrapper):
+
+```jsx
+<GanttChart
+  title="Minimal"
+  tasks={tasks}
+  chartOnly={true}
+  containerStyle="h-64 w-full"
+  showDataLabel={false}
+  showToolbar={false}
+/>
 ```
 
 ##### Required props
@@ -108,35 +90,39 @@ return (
 
 ##### Optional props
 
-| Name            | Type            | Default     | Description                                                                        |
-| --------------- | --------------- | ----------- | ---------------------------------------------------------------------------------- |
-| `tasks`         | `GanttTask[]`   | `[]`        | Array of task objects for timeline visualization                                   |
-| `series`        | `GanttSeries[]` | `[]`        | Alternative series format for advanced usage                                       |
-| `duration`      | `object`        | `undefined` | Overall project duration with startDate and endDate                                |
-| `showGrid`      | `boolean`       | `true`      | Show/hide grid lines                                                               |
-| `showTooltip`   | `boolean`       | `true`      | Enable/disable tooltips                                                            |
-| `showDataLabel` | `boolean`       | `true`      | Show/hide data labels                                                              |
-| `showToolbar`   | `boolean`       | `true`      | Show/hide chart toolbar                                                            |
-| `borderColor`   | `string`        | `#e7e7e7`   | Custom border color                                                                |
-| `colors`        | `string[]`      | `undefined` | Array of colors - first task uses first color, second task uses second color, etc. |
-| `onClick`       | `function`      | `undefined` | Callback when task is clicked                                                      |
-
-##### GanttTask props
-
-| Name           | Type       | Description                          |
-| -------------- | ---------- | ------------------------------------ |
-| `id`           | `string`   | Unique identifier for the task       |
-| `name`         | `string`   | Display name of the task             |
-| `start`        | `Date`     | Task start date                      |
-| `end`          | `Date`     | Task end date                        |
-| `duration`     | `number`   | Duration in days (optional)          |
-| `progress`     | `number`   | Progress percentage 0-100            |
-| `dependencies` | `string[]` | Array of dependent task IDs          |
-| `color`        | `string`   | Custom color for the task (optional) |
-
-##### GanttSeries props
-
-| Name   | Type     | Description                   |
-| ------ | -------- | ----------------------------- |
-| `name` | `string` | Series name                   |
-| `data` | `array`  | Array of timeline data points |
+| Name               | Type                                         | Default       | Description                                                                                                   |
+| ------------------ | -------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------- |
+| `tasks`            | `GanttTask[]`                                | `[]`          | Array of task objects to render on the chart                                                                  |
+| `mode`             | `"read" \| "write"`                          | `"read"`      | `"write"` renders an editable table above the chart where tasks can be added, edited, and deleted             |
+| `label`            | `string`                                     | —             | Field label shown above the chart in write mode                                                               |
+| `labelExtra`       | `ReactElement`                               | —             | Extra element rendered next to the label                                                                      |
+| `infoElement`      | `ReactElement`                               | —             | Content for an info popover shown via a question mark icon next to the label                                  |
+| `onClick`          | `(taskId: string, taskName: string) => void` | —             | Called when a task bar is clicked                                                                             |
+| `onTaskChange`     | `(tasks: GanttTask[]) => void`               | —             | Called with the updated task array when tasks are added, edited, or deleted. Required when `mode="write"`.    |
+| `showGrid`         | `boolean`                                    | `true`        | Show or hide chart grid lines                                                                                 |
+| `showTooltip`      | `boolean`                                    | `true`        | Show or hide the hover tooltip with task name, start, end, and duration                                       |
+| `showDataLabel`    | `boolean`                                    | `true`        | Show or hide the task name label inside each bar                                                              |
+| `showToolbar`      | `boolean`                                    | `true`        | Show or hide the ApexCharts toolbar (download, zoom, etc.)                                                    |
+| `borderColor`      | `string`                                     | `#e7e7e7`     | Grid line border color                                                                                        |
+| `colors`           | `string[]`                                   | —             | Color array applied per task in order. Falls back to localStorage `localChartColors` then ApexCharts defaults |
+| `enableGradient`   | `boolean`                                    | `false`       | Applies a gradient fill to task bars                                                                          |
+| `darkMode`         | `boolean`                                    | `false`       | Switches axis labels and text to white                                                                        |
+| `darkModeBg`       | `string`                                     | `bg-gray-900` | Tailwind bg class for the card background in dark mode                                                        |
+| `dateRangeVisible` | `boolean`                                    | `false`       | Shows a date range picker below the chart                                                                     |
+| `customDate`       | `RangeInterface`                             | —             | Pre-selected date range passed to the date range picker                                                       |
+| `onChangeDate`     | `(date?: RangeInterface) => void`            | —             | Called when the date range picker value changes                                                               |
+| `chartSize`        | `number`                                     | `400`         | Chart height in pixels                                                                                        |
+| `chartOnly`        | `boolean`                                    | `false`       | Renders only the chart with no card wrapper. Use `containerStyle` to size the container.                      |
+| `containerStyle`   | `string`                                     | —             | Tailwind classes applied to the outer container                                                               |
+| `tool`             | `ReactElement`                               | —             | Extra element rendered in the top-right of the chart header (e.g. an icon button)                             |
+| `minInterval`      | `number`                                     | —             | Minimum interval for the date range picker                                                                    |
+
+##### GanttTask
+
+| Name    | Type     | Description                                    |
+| ------- | -------- | ---------------------------------------------- |
+| `id`    | `string` | Unique identifier for the task                 |
+| `name`  | `string` | Display name shown on the bar and in the table |
+| `start` | `Date`   | Task start date                                |
+| `end`   | `Date`   | Task end date                                  |
+| `color` | `string` | Optional per-task color override               |

package/lib/components/chart/ganttChart/ganttChart.stories.tsx

@@ -1,7 +1,7 @@
-import { CalendarIcon } from "@heroicons/react/24/outline";
 import { storiesOf } from "@storybook/react";
-import React, { useCallback, useState } from "react";
+import React, { useState } from "react";
 import { GanttChart } from ".";
+import { StorySection } from "../../storyUtils";
 import README from "./README.md";
 
 const stories = storiesOf("Chart", module);
@@ -12,127 +12,143 @@ stories.addParameters({
   },
 });
 
-stories.add("Gantt Chart", () => {
-  const today = new Date();
-  const oneDay = 24 * 60 * 60 * 1000;
-
-  const [ganttTasks, setGanttTasks] = useState<any[]>([
-    {
-      id: "task1",
-      name: "Project Planning",
-      start: new Date(today.getTime() - 5 * oneDay),
-      end: new Date(today.getTime() - 3 * oneDay),
-      duration: 2,
-      progress: 100,
-    },
-    {
-      id: "task2",
-      name: "Design Phase",
-      start: new Date(today.getTime() - 3 * oneDay),
-      end: new Date(today.getTime() + 2 * oneDay),
-      duration: 5,
-      progress: 75,
-      dependencies: ["task1"],
-    },
-    {
-      id: "task3",
-      name: "Development",
-      start: new Date(today.getTime()),
-      end: new Date(today.getTime() + 10 * oneDay),
-      duration: 10,
-      progress: 40,
-      dependencies: ["task2"],
-    },
-    {
-      id: "task4",
-      name: "Testing",
-      start: new Date(today.getTime() + 8 * oneDay),
-      end: new Date(today.getTime() + 12 * oneDay),
-      duration: 4,
-      progress: 0,
-      dependencies: ["task3"],
-    },
-    {
-      id: "task5",
-      name: "Deployment",
-      start: new Date(today.getTime() + 12 * oneDay),
-      end: new Date(today.getTime() + 14 * oneDay),
-      duration: 2,
-      progress: 0,
-      dependencies: ["task4"],
-    },
-  ]);
+const today = new Date();
+const day = 24 * 60 * 60 * 1000;
 
-  const handleTaskClick = useCallback((taskId: string, taskName: string) => {
-    console.log(`Clicked task: ${taskName} (ID: ${taskId})`);
-  }, []);
+const baseTasks = [
+  {
+    id: "task1",
+    name: "Planning",
+    start: new Date(today.getTime() - 5 * day),
+    end: new Date(today.getTime() - 3 * day),
+  },
+  {
+    id: "task2",
+    name: "Design",
+    start: new Date(today.getTime() - 3 * day),
+    end: new Date(today.getTime() + 2 * day),
+  },
+  {
+    id: "task3",
+    name: "Development",
+    start: new Date(today.getTime()),
+    end: new Date(today.getTime() + 10 * day),
+  },
+  {
+    id: "task4",
+    name: "Testing",
+    start: new Date(today.getTime() + 8 * day),
+    end: new Date(today.getTime() + 12 * day),
+  },
+  {
+    id: "task5",
+    name: "Deployment",
+    start: new Date(today.getTime() + 12 * day),
+    end: new Date(today.getTime() + 14 * day),
+  },
+];
 
-  const handleTaskChange = useCallback((tasks: any[]) => {
-    setGanttTasks(tasks);
-    console.log(`Tasks updated: ${tasks.length} tasks`);
-  }, []);
+stories.add("Gantt Chart", () => {
+  const [tasks, setTasks] = useState(baseTasks);
 
   return (
     <>
-      <div className="font-medium mb-5">
-        Gantt Chart - Write Mode (Editable)
-      </div>
-      <GanttChart
-        title="Project Management Dashboard"
-        tasks={ganttTasks}
-        mode="write"
-        tool={<CalendarIcon className="h-4 w-4 text-primary-600" />}
-        dateRangeVisible={true}
-        onClick={handleTaskClick}
-        onTaskChange={handleTaskChange}
-        showDataLabel={true}
-        showTooltip={true}
-        showGrid={true}
-        showToolbar={true}
-        colors={["#008FFB", "#00E396", "#FEB019", "#FF4560", "#775DD0"]}
-      />
-      <div className="font-medium mb-5">
-        Gantt Chart (Individual Task Colors)
-      </div>
-      <GanttChart
-        title="Project Timeline"
-        tasks={ganttTasks}
-        tool={<CalendarIcon className="h-4 w-4 text-primary-600" />}
-        dateRangeVisible={true}
-        onClick={handleTaskClick}
-        showDataLabel={true}
-        showTooltip={true}
-        showGrid={true}
-        showToolbar={true}
-        colors={["#008FFB", "#00E396", "#FEB019", "#FF4560", "#775DD0"]}
-      />
+      <StorySection
+        title="Read Mode"
+        description="Default display mode. Renders a horizontal range bar chart. Each task in the tasks array becomes one bar. colors are applied per task in order."
+      >
+        <div className="w-full">
+          <GanttChart
+            title="Project Timeline"
+            tasks={tasks}
+            showGrid={true}
+            showTooltip={true}
+            showDataLabel={true}
+            showToolbar={true}
+            onClick={(taskId, taskName) =>
+              alert(`Clicked: ${taskName} (${taskId})`)
+            }
+            colors={["#008FFB", "#00E396", "#FEB019", "#FF4560", "#775DD0"]}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Write Mode"
+        description="mode='write' renders an editable table above the chart. Tasks can be added, edited inline, and deleted. onTaskChange is called with the updated task array on every change."
+      >
+        <div className="w-full">
+          <GanttChart
+            title="Project Timeline"
+            label="Tasks"
+            tasks={tasks}
+            mode="write"
+            onTaskChange={(updated) => setTasks(updated)}
+            onClick={(taskId, taskName) =>
+              alert(`Clicked: ${taskName} (${taskId})`)
+            }
+            showGrid={true}
+            showTooltip={true}
+            showDataLabel={true}
+            colors={["#008FFB", "#00E396", "#FEB019", "#FF4560", "#775DD0"]}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Date Range Picker"
+        description="dateRangeVisible=true shows a date range picker below the chart. Pass customDate to pre-select a range and onChangeDate to handle updates."
+      >
+        <div className="w-full">
+          <GanttChart
+            title="Project Timeline"
+            tasks={tasks}
+            dateRangeVisible={true}
+            showTooltip={true}
+            showDataLabel={true}
+            onChangeDate={(range) => console.log("Date range changed", range)}
+            colors={["#008FFB", "#00E396", "#FEB019", "#FF4560", "#775DD0"]}
+          />
+        </div>
+      </StorySection>
 
-      <div className="font-medium my-5">Dark Mode Gantt Chart</div>
-      <GanttChart
-        title="Development Sprint"
-        tasks={ganttTasks.slice(1, 4)}
-        tool={<CalendarIcon className="h-4 w-4 text-primary-600" />}
-        onClick={handleTaskClick}
-        showDataLabel={true}
-        showTooltip={true}
-        darkMode={true}
-        darkModeBg="bg-gradient-to-r from-slate-700 to-gray-900"
-        borderColor="#374151"
-        enableGradient={true}
-        colors={["#3B82F6", "#10B981", "#F59E0B", "#EF4444", "#8B5CF6"]}
-      />
+      <StorySection
+        title="Dark Mode"
+        description="darkMode=true switches axis labels and text to white. darkModeBg sets the card background. enableGradient applies a gradient fill to bars."
+        dark
+      >
+        <div className="w-full">
+          <GanttChart
+            title="Development Sprint"
+            tasks={tasks.slice(1, 4)}
+            darkMode={true}
+            darkModeBg="bg-gray-900"
+            borderColor="#374151"
+            enableGradient={true}
+            showTooltip={true}
+            showDataLabel={true}
+            colors={["#3B82F6", "#10B981", "#F59E0B", "#EF4444", "#8B5CF6"]}
+          />
+        </div>
+      </StorySection>
 
-      <div className="font-medium my-5">Chart Only Mode</div>
-      <GanttChart
-        title="Minimal Gantt"
-        tasks={ganttTasks.slice(0, 3)}
-        chartOnly={true}
-        containerStyle="h-64 w-full"
-        showDataLabel={false}
-        showToolbar={false}
-        onClick={handleTaskClick}
-        colors={["#3B82F6", "#10B981", "#F59E0B"]}
-      />
+      <StorySection
+        title="Chart Only"
+        description="chartOnly=true strips the card wrapper and renders just the chart. Use containerStyle to control the dimensions."
+      >
+        <div className="w-full h-64">
+          <GanttChart
+            title="Minimal"
+            tasks={tasks.slice(0, 3)}
+            chartOnly={true}
+            containerStyle="h-64 w-full"
+            showDataLabel={false}
+            showToolbar={false}
+            showTooltip={true}
+            colors={["#008FFB", "#00E396", "#FEB019"]}
+          />
+        </div>
+      </StorySection>
     </>
   );
 });