blixify-ui-web-mcp 0.1.2 → 0.1.18

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

@@ -4,53 +4,23 @@
 
 <hr>
 
-A heatmap chart component for displaying data density and patterns. e.g: User activity across different time periods
+A heatmap chart for visualising data density across two dimensions. Each cell is colour-coded by value using a built-in four-range scale (Low → Medium → High → Very High). Supports multi-series data, dark mode, date range filtering, and a clickable title link.
 
 ##### Import
 
 ```js
-import { HeatmapChart } from "blixify-ui-web/lib";
+import { HeatmapChart } from "blixify-ui-web/components/chart/heatmapChart";
 ```
 
 ##### Usage
 
+Basic multi-series heatmap:
+
 ```jsx
 const multiSeriesData = [
-  {
-    name: "Metric1",
-    data: [
-      10, 20, 30, 40, 50, 60, 70, 80, 90, 100, 110, 120, 130, 140, 150, 160,
-      170, 180,
-    ],
-  },
-  {
-    name: "Metric2",
-    data: [
-      15, 25, 35, 45, 55, 65, 75, 85, 95, 105, 115, 125, 135, 145, 155, 165,
-      175, 185,
-    ],
-  },
-  {
-    name: "Metric3",
-    data: [
-      20, 30, 40, 50, 60, 70, 80, 90, 100, 110, 120, 130, 140, 150, 160, 170,
-      180, 190,
-    ],
-  },
-  {
-    name: "Metric4",
-    data: [
-      25, 35, 45, 55, 65, 75, 85, 95, 105, 115, 125, 135, 145, 155, 165, 175,
-      185, 195,
-    ],
-  },
-  {
-    name: "Metric5",
-    data: [
-      30, 40, 50, 60, 70, 80, 90, 100, 110, 120, 130, 140, 150, 160, 170, 180,
-      190, 200,
-    ],
-  },
+  { name: "Week 1", data: [10, 45, 80, 120, 5, 60, 30, 95, 15, 70, 40, 110] },
+  { name: "Week 2", data: [20, 55, 90, 10, 75, 35, 100, 25, 85, 50, 130, 65] },
+  { name: "Week 3", data: [5, 30, 60, 95, 40, 115, 20, 80, 45, 105, 15, 70] },
 ];
 
 const categories = [
@@ -66,39 +36,51 @@ const categories = [
   "Oct",
   "Nov",
   "Dec",
-  "Q1",
-  "Q2",
-  "Q3",
-  "Q4",
-  "Y1",
-  "Y2",
 ];
 
-return (
-  <>
-    <div className="font-medium mb-5">Multi-Series Heatmap Chart</div>
-    <HeatmapChart
-      title="Metrics Heatmap"
-      multiSeriesData={multiSeriesData}
-      categories={categories}
-      tool={<PencilIcon className="h-4 w-4 text-primary-600" />}
-      showDataLabel={true}
-      newTabUrl="https://www.google.com/"
-    />
-
-    <div className="font-medium my-5">Dark Mode Heatmap Chart</div>
-    <HeatmapChart
-      title="Activity Distribution"
-      multiSeriesData={multiSeriesData}
-      categories={categories}
-      tool={<PencilIcon className="h-4 w-4 text-primary-600" />}
-      showDataLabel={true}
-      darkMode={true}
-      darkModeBg="bg-gradient-to-r from-slate-700 to-gray-900"
-      borderColor=""
-    />
-  </>
-);
+<HeatmapChart
+  title="Monthly Activity"
+  multiSeriesData={multiSeriesData}
+  categories={categories}
+  showDataLabel={true}
+/>;
+```
+
+With date range picker and toolbar:
+
+```jsx
+<HeatmapChart
+  title="Activity Distribution"
+  multiSeriesData={multiSeriesData}
+  categories={categories}
+  showToolbar={true}
+  dateRangeVisible={true}
+  onChangeDate={(range) => console.log(range)}
+/>
+```
+
+Dark mode:
+
+```jsx
+<HeatmapChart
+  title="Activity Distribution"
+  multiSeriesData={multiSeriesData}
+  categories={categories}
+  darkMode={true}
+  darkModeBg="bg-gray-900"
+/>
+```
+
+Chart only (no card wrapper):
+
+```jsx
+<HeatmapChart
+  title="Minimal"
+  multiSeriesData={multiSeriesData}
+  categories={categories}
+  chartOnly={true}
+  containerStyle="h-64 w-full"
+/>
 ```
 
 ##### Required props
@@ -109,17 +91,46 @@ return (
 
 ##### Optional props
 
-| Name              | Type           | Default | Description                                |
-| ----------------- | -------------- | ------- | ------------------------------------------ |
-| `multiSeriesData` | `SeriesItem[]` | `[]`    | Multi-series data with name and data array |
-| `categories`      | `string[]`     | `[]`    | X-axis categories for multi-series format  |
-| `showToolbar`     | `boolean`      | `false` |                                            |
-| `showDataLabel`   | `boolean`      | `true`  |                                            |
-| `newTabUrl`       | `string`       | ""      | set URL for create hyperlinks              |
-
-##### Series Item props
-
-| Name   | Type       | Description   |
-| ------ | ---------- | ------------- |
-| `name` | `string`   | Name of data  |
-| `data` | `number[]` | Value of data |
+| Name               | Type                                                       | Default       | Description                                                                                      |
+| ------------------ | ---------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------ |
+| `multiSeriesData`  | `SeriesItem[]`                                             | —             | Array of series — each becomes a row in the heatmap. See SeriesItem below.                       |
+| `categories`       | `string[] \| number[]`                                     | —             | X-axis category labels. Length should match the `data` array length in each series.              |
+| `showDataLabel`    | `boolean`                                                  | `true`        | Show or hide the numeric value label inside each cell                                            |
+| `showToolbar`      | `boolean`                                                  | —             | Show or hide the ApexCharts toolbar (download, zoom, etc.)                                       |
+| `borderColor`      | `string`                                                   | `#e7e7e7`     | Grid border color                                                                                |
+| `newTabUrl`        | `string`                                                   | —             | When set, wraps the chart title in a link to this URL                                            |
+| `onClick`          | `(x: string, y: string, value: number) => void`            | —             | Called when a cell is clicked with its x category, y series name, and numeric value              |
+| `colors`           | `string[]`                                                 | —             | Custom color array. Falls back to `localStorage.localChartColors` then the built-in color scale. |
+| `enableGradient`   | `boolean`                                                  | `false`       | Applies a gradient fill to cells                                                                 |
+| `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`                                                   | `280`         | 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                                      |
+| `minInterval`      | `number`                                                   | —             | Minimum interval for the date range picker                                                       |
+| `linkType`         | `"react" \| "gatsby" \| "next" \| "external" \| "default"` | —             | Router adapter used when `newTabUrl` is set                                                      |
+| `custom`           | `any`                                                      | —             | Custom link component used when `linkType` is `"react"`, `"gatsby"`, or `"next"`                 |
+
+##### Built-in colour scale
+
+The heatmap uses a fixed four-range colour scale by default:
+
+| Range     | Colour    | Label     |
+| --------- | --------- | --------- |
+| 0 – 10    | `#00A100` | Low       |
+| 11 – 50   | `#128FD9` | Medium    |
+| 51 – 100  | `#FFB200` | High      |
+| 101 – 200 | `#FF4560` | Very High |
+
+Pass `colors` to override this scale with ApexCharts' default colour assignment.
+
+##### SeriesItem
+
+| Name   | Type       | Description                                                |
+| ------ | ---------- | ---------------------------------------------------------- |
+| `name` | `string`   | Row label shown on the y-axis                              |
+| `data` | `number[]` | Numeric values for each x-axis category, in the same order |

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

@@ -1,106 +1,144 @@
-import { PencilIcon } from "@heroicons/react/24/outline";
-import { storiesOf } from "@storybook/react";
 import React, { useMemo } from "react";
 import { HeatmapChart } from ".";
-import README from "./README.md";
+import { StorySection } from "../../storyUtils";
 
-const stories = storiesOf("Chart", module);
+const meta = { title: "Chart/Heatmap Chart" };
+export default meta;
 
-stories.addParameters({
-  readme: {
-    content: README,
-  },
-});
 
-// Utility function to generate random data
-const generateData = (
-  count: number,
-  options: { min: number; max: number }
-): number[] => {
-  const data: number[] = [];
-  for (let i = 0; i < count; i++) {
-    data.push(
-      Math.floor(Math.random() * (options.max - options.min + 1)) + options.min
-    );
-  }
-  return data;
-};
+const categories = [
+  "Jan",
+  "Feb",
+  "Mar",
+  "Apr",
+  "May",
+  "Jun",
+  "Jul",
+  "Aug",
+  "Sep",
+  "Oct",
+  "Nov",
+  "Dec",
+];
 
-stories.add("Heatmap Chart", () => {
-  // Multi-series data example
+const rand = (min: number, max: number) =>
+  Math.floor(Math.random() * (max - min + 1)) + min;
+
+export const HeatmapChartStory = () => {
   const multiSeriesData = useMemo(
     () => [
-      {
-        name: "Metric1",
-        data: generateData(18, { min: 0, max: 90 }),
-      },
-      {
-        name: "Metric2",
-        data: generateData(18, { min: 0, max: 90 }),
-      },
-      {
-        name: "Metric3",
-        data: generateData(18, { min: 0, max: 90 }),
-      },
-      {
-        name: "Metric4",
-        data: generateData(18, { min: 0, max: 90 }),
-      },
-      {
-        name: "Metric5",
-        data: generateData(18, { min: 0, max: 90 }),
-      },
+      { name: "Week 1", data: categories.map(() => rand(0, 90)) },
+      { name: "Week 2", data: categories.map(() => rand(0, 90)) },
+      { name: "Week 3", data: categories.map(() => rand(0, 90)) },
+      { name: "Week 4", data: categories.map(() => rand(0, 90)) },
+      { name: "Week 5", data: categories.map(() => rand(0, 90)) },
     ],
     []
   );
 
-  const categories = useMemo(
+  const wideSeriesData = useMemo(
     () => [
-      "Jan",
-      "Feb",
-      "Mar",
-      "Apr",
-      "May",
-      "Jun",
-      "Jul",
-      "Aug",
-      "Sep",
-      "Oct",
-      "Nov",
-      "Dec",
-      "Q1",
-      "Q2",
-      "Q3",
-      "Q4",
-      "Y1",
-      "Y2",
+      { name: "Metric A", data: categories.map(() => rand(0, 200)) },
+      { name: "Metric B", data: categories.map(() => rand(0, 200)) },
+      { name: "Metric C", data: categories.map(() => rand(0, 200)) },
     ],
     []
   );
 
   return (
     <>
-      <div className="font-medium mb-5">Multi-Series Heatmap Chart</div>
-      <HeatmapChart
-        title="Metrics Heatmap"
-        multiSeriesData={multiSeriesData}
-        categories={categories}
-        tool={<PencilIcon className="h-4 w-4 text-primary-600" />}
-        showDataLabel={true}
-        newTabUrl="https://www.google.com/"
-      />
+      <StorySection
+        title="Default"
+        description="Each SeriesItem becomes a row. Values are colour-coded by the built-in scale: green (0–10), blue (11–50), amber (51–100), red (101–200). showDataLabel shows the numeric value inside each cell."
+      >
+        <div className="w-full">
+          <HeatmapChart
+            title="Monthly Activity"
+            multiSeriesData={multiSeriesData}
+            categories={categories}
+            showDataLabel={true}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Full Colour Scale"
+        description="Values spanning all four ranges (0–200) show the complete built-in colour scale in one chart."
+      >
+        <div className="w-full">
+          <HeatmapChart
+            title="Full Range Metrics"
+            multiSeriesData={wideSeriesData}
+            categories={categories}
+            showDataLabel={true}
+            showToolbar={true}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="With Date Range Picker"
+        description="dateRangeVisible=true shows a date range picker below the chart. onChangeDate is called when the range changes."
+      >
+        <div className="w-full">
+          <HeatmapChart
+            title="Activity Over Time"
+            multiSeriesData={multiSeriesData}
+            categories={categories}
+            showDataLabel={false}
+            dateRangeVisible={true}
+            onChangeDate={(range) => console.log("Date range changed", range)}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Clickable Title Link"
+        description="newTabUrl wraps the chart title in a link. Useful for navigating to a detail page from a dashboard."
+      >
+        <div className="w-full">
+          <HeatmapChart
+            title="Activity (click title)"
+            multiSeriesData={multiSeriesData}
+            categories={categories}
+            showDataLabel={true}
+            newTabUrl="https://www.google.com/"
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Dark Mode"
+        description="darkMode=true switches axis labels and text to white. darkModeBg sets the card background colour."
+        dark
+      >
+        <div className="w-full">
+          <HeatmapChart
+            title="Activity Distribution"
+            multiSeriesData={multiSeriesData}
+            categories={categories}
+            showDataLabel={true}
+            darkMode={true}
+            darkModeBg="bg-gray-900"
+          />
+        </div>
+      </StorySection>
 
-      <div className="font-medium my-5">Dark Mode Heatmap Chart</div>
-      <HeatmapChart
-        title="Activity Distribution"
-        multiSeriesData={multiSeriesData}
-        categories={categories}
-        tool={<PencilIcon className="h-4 w-4 text-primary-600" />}
-        showDataLabel={true}
-        darkMode={true}
-        darkModeBg="bg-gradient-to-r from-slate-700 to-gray-900"
-        borderColor=""
-      />
+      <StorySection
+        title="Chart Only"
+        description="chartOnly=true strips the card wrapper and renders just the chart. Use containerStyle to control dimensions."
+      >
+        <div className="w-full h-64">
+          <HeatmapChart
+            title="Minimal"
+            multiSeriesData={multiSeriesData}
+            categories={categories}
+            chartOnly={true}
+            containerStyle="h-64 w-full"
+            showDataLabel={false}
+          />
+        </div>
+      </StorySection>
     </>
   );
-});
+}

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

@@ -1,25 +1,19 @@
 import { PencilIcon } from "@heroicons/react/24/outline";
-import { storiesOf } from "@storybook/react";
 import React, { useCallback, useEffect, useState } from "react";
 import { LineChart } from ".";
 import { RangeInterface } from "../DateRange";
-import README from "./README.md";
 import { StorySection } from "../../storyUtils";
 
-const stories = storiesOf("Chart", module);
+const meta = { title: "Chart/Line Chart" };
+export default meta;
 
-stories.addParameters({
-  readme: {
-    content: README,
-  },
-});
 
 const multiLineSeries = [
   { name: "High - 2013", data: [-50, 29.1, 33.453, 60.09, 32, 32, 90] },
   { name: "Low - 2013", data: [12, 60, 14, 18, 17, 70, 13] },
 ];
 
-stories.add("Line Chart", () => {
+export const LineChartStory = () => {
   const [seriesData, setSeriesData] = useState([12, 60, 14, 18, 17]);
   const [categoryData, setCategoryData] = useState<string[]>([
     "JAN",
@@ -149,4 +143,4 @@ stories.add("Line Chart", () => {
       </StorySection>
     </div>
   );
-});
+}

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

@@ -1,18 +1,12 @@
 import { PencilIcon } from "@heroicons/react/24/outline";
-import { storiesOf } from "@storybook/react";
 import React, { useCallback, useEffect, useMemo, useState } from "react";
 import { PieChart } from ".";
 import { StorySection } from "../../storyUtils";
 import { RangeInterface } from "../DateRange";
-import README from "./README.md";
 
-const stories = storiesOf("Chart", module);
+const meta = { title: "Chart/Pie Chart" };
+export default meta;
 
-stories.addParameters({
-  readme: {
-    content: README,
-  },
-});
 
 const dummyData = [
   { label: "Apple", value: 10 },
@@ -25,7 +19,7 @@ const dummyData = [
 const series = dummyData.map((d) => d.value);
 const labels = dummyData.map((d) => d.label);
 
-stories.add("Pie Chart", () => {
+export const PieChartStory = () => {
   const [seriesData, setSeriesData] = useState<number[]>([]);
   const [labelData, setLabelData] = useState<string[]>([]);
 
@@ -177,4 +171,4 @@ stories.add("Pie Chart", () => {
       </StorySection>
     </>
   );
-});
+}

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

@@ -1,20 +1,14 @@
 import { PencilIcon } from "@heroicons/react/24/outline";
-import { storiesOf } from "@storybook/react";
-import moment from "moment";
+import dayjs from "../../dayjs";
 import React, { useCallback, useEffect, useMemo, useState } from "react";
 import { PolarAreaChart } from ".";
 import { RangeInterface } from "../DateRange";
-import README from "./README.md";
 
-const stories = storiesOf("Chart", module);
+const meta = { title: "Chart/Polar Area Chart" };
+export default meta;
 
-stories.addParameters({
-  readme: {
-    content: README,
-  },
-});
 
-stories.add("Polar Area Chart", () => {
+export const PolarAreaChartStory = () => {
   const [seriesData, setSeriesData] = useState<any[]>([]);
 
   const chartDummyData = useMemo(() => {
@@ -63,7 +57,7 @@ stories.add("Polar Area Chart", () => {
   }, [handleSetData]);
 
   const sevenDaysAgo = new Date();
-  sevenDaysAgo.setDate(moment().toDate().getDate() - 7);
+  sevenDaysAgo.setDate(dayjs().toDate().getDate() - 7);
 
   return (
     <>
@@ -76,7 +70,7 @@ stories.add("Polar Area Chart", () => {
         dateRangeVisible={true}
         customDate={{
           startDate: sevenDaysAgo,
-          endDate: moment().toDate(),
+          endDate: dayjs().toDate(),
           isDuration: true,
         }}
         onChangeDate={handleSetData}
@@ -92,7 +86,7 @@ stories.add("Polar Area Chart", () => {
         dateRangeVisible={true}
         customDate={{
           startDate: sevenDaysAgo,
-          endDate: moment().toDate(),
+          endDate: dayjs().toDate(),
           isDuration: true,
         }}
         onChangeDate={handleSetData}
@@ -103,4 +97,4 @@ stories.add("Polar Area Chart", () => {
       />
     </>
   );
-});
+}

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

@@ -1,17 +1,11 @@
-import { storiesOf } from "@storybook/react";
 import React from "react";
 import { RadarChart } from ".";
-import README from "./README.md";
 
-const stories = storiesOf("Chart", module);
+const meta = { title: "Chart/Radar Chart" };
+export default meta;
 
-stories.addParameters({
-  readme: {
-    content: README,
-  },
-});
 
-stories.add("Radar Chart", () => {
+export const RadarChartStory = () => {
   return (
     <RadarChart
       title={"Test Chart"}
@@ -33,4 +27,4 @@ stories.add("Radar Chart", () => {
       onChangeDate={() => {}}
     />
   );
-});
+}

package/lib/components/chart/radialBar/radialChart.stories.tsx

@@ -1,20 +1,14 @@
 import { PencilIcon } from "@heroicons/react/24/outline";
-import { storiesOf } from "@storybook/react";
 import React, { useCallback, useEffect, useMemo, useState } from "react";
 import { RadialBar } from ".";
 import { RangeInterface } from "../DateRange";
-import README from "./README.md";
 import colors from "tailwindcss/colors";
 
-const stories = storiesOf("Chart", module);
+const meta = { title: "Chart/Radial Chart" };
+export default meta;
 
-stories.addParameters({
-  readme: {
-    content: README,
-  },
-});
 
-stories.add("Radial Chart", () => {
+export const RadialChart = () => {
   const [seriesData, setSeriesData] = useState<number[]>([]);
   const [labelData, setLabelData] = useState<string[]>([]);
 
@@ -133,4 +127,4 @@ stories.add("Radial Chart", () => {
       />
     </div>
   );
-});
+}

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

@@ -1,23 +1,17 @@
 import { PencilIcon } from "@heroicons/react/24/outline";
-import { storiesOf } from "@storybook/react";
 import React, { useEffect, useMemo, useState } from "react";
 import { RangeBarChart } from ".";
-import README from "./README.md";
 
-const stories = storiesOf("Chart", module);
+const meta = { title: "Chart/Range Bar Chart" };
+export default meta;
 
-stories.addParameters({
-  readme: {
-    content: README,
-  },
-});
 
 interface RangeData {
   category: string;
   value: [Date, Date];
 }
 
-stories.add("Range Bar Chart", () => {
+export const RangeBarChartStory = () => {
   const [rangeData, setRangeData] = useState<RangeData[]>([]);
 
   const chartDummyData = useMemo((): RangeData[] => {
@@ -205,4 +199,4 @@ stories.add("Range Bar Chart", () => {
       />
     </>
   );
-});
+}