blixify-ui-web-mcp 0.1.2 → 0.1.3

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,7 +1,7 @@
-import { PencilIcon } from "@heroicons/react/24/outline";
 import { storiesOf } from "@storybook/react";
 import React, { useMemo } from "react";
 import { HeatmapChart } from ".";
+import { StorySection } from "../../storyUtils";
 import README from "./README.md";
 
 const stories = storiesOf("Chart", module);
@@ -12,95 +12,139 @@ stories.addParameters({
   },
 });
 
-// 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",
+];
+
+const rand = (min: number, max: number) =>
+  Math.floor(Math.random() * (max - min + 1)) + min;
 
 stories.add("Heatmap Chart", () => {
-  // Multi-series data example
   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/chat/chatAnchor/README.md

@@ -4,110 +4,92 @@
 
 <hr>
 
-Chat Anchor
+A floating chat button fixed to the viewport. Clicking it toggles the `ChatBase` panel open/closed with an animated transition. On mobile (< 640px) the chat panel expands to full screen when open.
 
 ##### Import
 
 ```js
 import { ChatAnchor } from "blixify-ui-web/components/chat/chatAnchor";
-import {
-  ChatBase,
-  Conversation,
-} from "blixify-ui-web/components/chat/chatBase";
+import { Conversation } from "blixify-ui-web/components/chat/chatBase";
 ```
 
 ##### Usage
 
 ```tsx
-const [openChatBase, setOpenChatBase] = useState<boolean>(false);
+const [open, setOpen] = useState(false);
 const [message, setMessage] = useState("");
-const [search, setSearch] = useState("");
-const [filteredConversation, setFilteredConversation] =
-  useState<Conversation | null>();
 const [conversation, setConversation] = useState<Conversation>({
   id: "1",
   members: [currentUser, botUser],
-  messageList: [
-    {
-      sender: botUser,
-      messageBody: "Hi! How can I help you? 🤖",
-      createdAt: moment(
-        "Fri Nov 03 2023 12:21:14 GMT+0800 (Malaysia Time)"
-      ).toDate(),
-    },
-    {
-      sender: currentUser,
-      messageBody: "Yo, my computer's acting up.",
-      createdAt: moment(
-        "Fri Nov 03 2023 13:21:14 GMT+0800 (Malaysia Time)"
-      ).toDate(),
-    },
-  ],
+  messageList: [],
 });
 
-const handleOnClick = () => setOpenChatBase(!openChatBase);
-
-const handleOnSendMessage = (conversation: Conversation) => {
-  setConversation(conversation);
-  setMessage("");
-};
-
-const handleOnSearch = (searchMessage: string) => {
-  if (searchMessage.length === 0) {
-    setSearch("");
-    setFilteredConversation(null);
-  } else {
-    const dupMessageList = conversation.messageList.filter((eachMessage) => {
-      return eachMessage.messageBody
-        .toLowerCase()
-        .includes(searchMessage.toLowerCase());
-    });
-    const dupConversation = {
-      id: conversation.id,
-      members: [...conversation.members],
-      messageList: [...dupMessageList],
-    };
-    setFilteredConversation(dupConversation);
-  }
-};
-
-const headerElement = (
-  <div className="p-2 bg-primary-500 rounded-t-md">
-    <img src={Logo} alt="" className="h-12" />
-  </div>
-);
-
 return (
   <ChatAnchor
-    open={openChatBase}
+    open={open}
     value={message}
     currentUser={currentUser}
-    conversation={filteredConversation ?? conversation}
-    headerElement={headerElement}
-    searchMessage={search}
-    onChangeSearch={(e) => setSearch(e.target.value)}
-    onSendMessage={handleOnSendMessage}
+    conversation={conversation}
+    headerElement={
+      <div className="p-2 bg-primary-500">
+        <img src={Logo} className="h-12" />
+      </div>
+    }
+    onSendMessage={(c) => {
+      setConversation(c);
+      setMessage("");
+    }}
     onChangeMessage={(e) => setMessage(e.target.value)}
-    onSearch={handleOnSearch}
-    onClose={handleOnClick}
+    onClose={() => setOpen(false)}
+    onClick={() => setOpen(!open)}
     className="shadow-lg border border-gray-200"
-    onClick={handleOnClick}
+    greetingCard
+    greetingText="Ask me anything!"
   />
 );
 ```
 
 ##### Required props
 
-| Name    | Type         | Description                                      |
-| ------- | ------------ | ------------------------------------------------ |
-| onClick | `() => void` | Function that triggers upon clicking Chat Anchor |
-
-##### Optional props
-
-| Name             | Type                          | Default | Description                      |
-| ---------------- | ----------------------------- | ------- | -------------------------------- |
-| `positionOffset` | `Tailwind class`              | null    |                                  |
-| `greetingText`   | `string`                      | null    | Text to display                  |
-| `greetingCard`   | `boolean`                     | null    | Boolean to display greeting card |
-| `openIcon`       | `string` or `React.ReactNode` | null    | Icon to expand chat              |
-| `closeIcon`      | `string` or `React.ReactNode` | null    | Icon to collapse chat            |
+| Name           | Type           | Description                                            |
+| -------------- | -------------- | ------------------------------------------------------ |
+| `onClick`      | `() => void`   | Called when the floating anchor button is clicked      |
+| `open`         | `boolean`      | Controls whether the chat panel is visible             |
+| `value`        | `string`       | Current value of the message input                     |
+| `currentUser`  | `User`         | The logged-in user (`{ id, name, imageUrl? }`)         |
+| `conversation` | `Conversation` | Conversation object containing members and messageList |
+
+##### Optional props — ChatAnchor specific
+
+| Name             | Type                          | Default                                | Description                                                                                     |
+| ---------------- | ----------------------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `positionOffset` | `string`                      | `"bottom-8 right-8"`                   | Tailwind classes that control the fixed position of the anchor. Ignored on mobile when open.    |
+| `greetingCard`   | `boolean`                     | `false`                                | When `true`, shows a greeting bubble next to the anchor button while the chat is closed.        |
+| `greetingText`   | `string`                      | `"Welcome! How can I help you today?"` | Text displayed inside the greeting card bubble.                                                 |
+| `openIcon`       | `React.ReactNode` \| `string` | `ChatBubbleOvalLeftIcon`               | Icon shown when the chat is closed. A string is treated as an image URL (64×64 rounded circle). |
+| `closeIcon`      | `React.ReactNode` \| `string` | `XMarkIcon`                            | Icon shown when the chat is open. A string is treated as an image URL (64×64 rounded circle).   |
+
+##### Optional props — inherited from ChatBase
+
+| Name                   | Type                                   | Description                                                                    |
+| ---------------------- | -------------------------------------- | ------------------------------------------------------------------------------ |
+| `headerElement`        | `ReactElement`                         | Custom header rendered at the top of the chat panel                            |
+| `bodyElement`          | `ReactElement`                         | Replaces the default message list with a custom element                        |
+| `footerElement`        | `ReactElement`                         | Rendered below the message list, above the input bar                           |
+| `additionalAction`     | `ChatBaseAction[]`                     | Extra items added to the actions dropdown menu                                 |
+| `hideAdditionalAction` | `boolean`                              | Hides the actions dropdown entirely                                            |
+| `disableMessageInput`  | `boolean`                              | Disables the text input                                                        |
+| `isLoadingReply`       | `boolean`                              | Shows a typing indicator and disables input while waiting for a reply          |
+| `className`            | `string`                               | Extra classes applied to the chat panel container                              |
+| `sizeClassName`        | `string`                               | Overrides the default panel size (`h-[75vh] w-96` on desktop)                  |
+| `disableMobileResize`  | `boolean`                              | Prevents the panel from going full screen on mobile                            |
+| `paddingTop`           | `number`                               | Top padding (px) applied to the chat panel — useful when a sticky bar overlaps |
+| `searchMessage`        | `string`                               | Current search query value                                                     |
+| `onSendMessage`        | `(conversation: Conversation) => void` | Called with the updated conversation when a message is sent                    |
+| `onChangeMessage`      | `(event: any) => void`                 | Called on every keystroke in the message input                                 |
+| `onSearch`             | `(searchMessage: string) => void`      | Called when the search is submitted                                            |
+| `onChangeSearch`       | `(event: any) => void`                 | Called on every keystroke in the search input                                  |
+| `onClose`              | `() => void`                           | Called when the mobile close button is tapped                                  |
+| `onHiddenChatText`     | `boolean`                              | Hides the text input and file clip icon entirely                               |
+| `fileUpload`           | `FileUpload`                           | Configuration object for file upload support                                   |
+| `lib`                  | `{ axios?: any }`                      | Additional libraries (e.g. axios for file uploads)                             |