blixify-ui-web-mcp 0.1.2 → 0.1.18

package/lib/components/data/dataGraph/README.md

@@ -4,10 +4,144 @@
 
 <hr>
 
-Data Graph for Dashboard
+A dashboard chart grid that fetches and renders analytics data from a remote API. Supports card, bar, line, pie, and radar chart types in a responsive grid layout. Each chart handles its own data fetching, date range filtering, and attribute filtering.
 
 ##### Import
 
 ```js
 import { DataGraph } from "blixify-ui-web/components/data/dataGraph";
 ```
+
+##### Usage
+
+Basic dashboard with card and bar charts:
+
+```jsx
+<DataGraph
+  charts={[
+    {
+      gridSize: 1,
+      type: "card",
+      title: "Total Products",
+      spaceId: "products",
+      query: [],
+      queryBaseType: "count",
+    },
+    {
+      gridSize: 1,
+      type: "card",
+      title: "Total Revenue",
+      spaceId: "orders",
+      query: [],
+      queryBaseType: "sum",
+      queryAttributeId: ["price"],
+      queryBaseDateId: "createdAt",
+    },
+    {
+      gridSize: 2,
+      type: "bar",
+      title: "Sales by Product",
+      spaceId: "orders",
+      query: [
+        { type: "=", queryId: "code", value: "P001" },
+        { type: "=", queryId: "code", value: "P002" },
+      ],
+      queryBaseType: "sum",
+      queryAttributeId: ["price"],
+    },
+  ]}
+  workspace={{
+    apiEndpoint: "http://localhost:3000/api",
+    apiEndpointType: "mongoDB",
+  }}
+/>
+```
+
+Line chart with date range:
+
+```jsx
+{
+  gridSize: 2,
+  type: "line",
+  title: "Orders Over Time",
+  spaceId: "orders",
+  query: [],
+  queryBaseType: "count",
+  queryBaseDateId: "createdAt",
+}
+```
+
+Radar chart comparing multiple attributes across query groups:
+
+```jsx
+{
+  gridSize: 2,
+  type: "radar",
+  title: "Performance",
+  spaceId: "reports",
+  query: [
+    { type: "=", queryId: "status", value: "Completed" },
+    { type: "=", queryId: "status", value: "Pending" },
+  ],
+  queryBaseType: "sum",
+  queryAttributeId: ["revenue", "units", "returns"],
+  queryBaseDateId: "createdAt",
+}
+```
+
+Custom layout via renderSettings:
+
+```jsx
+<DataGraph
+  charts={charts}
+  workspace={workspace}
+  renderSettings={(chartsElement, data) => (
+    <div className="my-custom-wrapper">{chartsElement}</div>
+  )}
+/>
+```
+
+##### Required props
+
+| Name        | Type                   | Description                                              |
+| ----------- | ---------------------- | -------------------------------------------------------- |
+| `charts`    | `Charts[]`             | List of chart definitions — see Charts below             |
+| `workspace` | `WorkspaceDevSettings` | API connection settings — see WorkspaceDevSettings below |
+
+##### Optional props
+
+| Name             | Type                                       | Default | Description                                                                                                                            |
+| ---------------- | ------------------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `gridSize`       | `2 \| 3`                                   | —       | Override the grid column layout. Default is a responsive `1 → 2 → 4` column grid. `2` forces 2 cols, `3` forces 3 cols.                |
+| `renderSettings` | `(charts: ReactElement, data: any) => any` | —       | Custom render function. Receives the rendered charts element and the raw analytics data object. Use to wrap charts in a custom layout. |
+
+##### Charts
+
+| Name               | Type                                            | Description                                                                                                                               |
+| ------------------ | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `type`             | `"card" \| "bar" \| "line" \| "pie" \| "radar"` | Chart type to render                                                                                                                      |
+| `title`            | `string`                                        | Chart title — also used as the key for internal state                                                                                     |
+| `spaceId`          | `string`                                        | The collection/space ID to query data from                                                                                                |
+| `gridSize`         | `number`                                        | Number of grid columns this chart spans                                                                                                   |
+| `query`            | `Query[]`                                       | Data series definitions. Each query entry produces one data point or series segment. Pass `[]` for a single aggregate.                    |
+| `queryBaseType`    | `"count" \| "sum" \| "avg" \| "value"`          | Aggregate function. Defaults to `"count"`.                                                                                                |
+| `queryAttributeId` | `string[]`                                      | Required when `queryBaseType` is `"sum"`, `"avg"`, or `"value"`. The field(s) to aggregate. For `radar`, each entry becomes a radar axis. |
+| `queryBaseDateId`  | `string`                                        | Field used for date range filtering. When set, a date range picker is shown on the chart.                                                 |
+| `queryReferenceId` | `string`                                        | Field used for reference-based filtering when a reference filter is active.                                                               |
+| `baseQuery`        | `Query[]`                                       | Static filter queries always applied alongside any dynamic filters.                                                                       |
+| `description`      | `string`                                        | Subtitle shown on `card` type charts                                                                                                      |
+| `cardIcon`         | `string`                                        | Heroicon name (solid) for the card icon, e.g. `"UserIcon"`. Defaults to `FolderIcon`.                                                     |
+| `cardIconBgColor`  | `string`                                        | Tailwind bg class for the card icon background                                                                                            |
+| `colors`           | `string[]`                                      | Custom color array for chart segments/bars/lines                                                                                          |
+| `orientation`      | `"col" \| "row"`                                | Bar chart orientation. Defaults to `"row"`.                                                                                               |
+| `stackedVertical`  | `boolean`                                       | Enables stacked bars on bar charts                                                                                                        |
+
+##### WorkspaceDevSettings
+
+| Name               | Type                                                                       | Description                     |
+| ------------------ | -------------------------------------------------------------------------- | ------------------------------- |
+| `apiEndpoint`      | `string`                                                                   | Base URL for the data API       |
+| `apiEndpointType`  | `"mongoDB" \| "firebase" \| "mongoServer" \| "fbServer" \| "mondayServer"` | Server/DB type driving the API  |
+| `apiEndpointToken` | `string`                                                                   | Auth token for the API endpoint |
+| `apiUserToken`     | `string`                                                                   | Per-user auth token             |
+| `assetEndpoint`    | `string`                                                                   | Base URL for asset/file storage |

package/lib/components/data/dataGraph/dataGraph.stories.tsx

@@ -1,84 +1,97 @@
-import { storiesOf } from "@storybook/react";
 import React from "react";
-import { Container } from "../../structure/container";
-import README from "./README.md";
+import { StorySection } from "../../storyUtils";
 import { DataGraph } from "./index";
 
-const stories = storiesOf("Data", module);
+const meta = { title: "Data/Data Graph" };
+export default meta;
 
-stories.addParameters({
-  readme: {
-    content: README,
-  },
-});
 
-stories.add("Data Graph", () => {
+const workspace = {
+  apiEndpoint: "http://localhost:3000/api",
+  apiEndpointType: "mongoDB" as const,
+};
+
+export const DataGraphStory = () => {
   return (
-    <Container bgColor="bg-white">
-      <DataGraph
-        charts={[
-          {
-            gridSize: 1,
-            type: "card",
-            title: "All Products",
-            description: "Related to ESH",
-            spaceId: "esh-products",
-            query: [],
-            queryBaseType: "count",
-          },
-          {
-            gridSize: 1,
-            type: "card",
-            title: "Price",
-            description: "Related to ESH",
-            spaceId: "esh-products",
-            query: [],
-            queryBaseType: "sum",
-            queryAttributeId: ["price"],
-          },
-          {
-            gridSize: 2,
-            type: "bar",
-            title: "Price per kg",
-            description: "Related to ESH",
-            spaceId: "esh-products",
-            query: [
-              { type: "=", queryId: "code", value: "P001" },
-              { type: "=", queryId: "code", value: "N001" },
-              { type: "=", queryId: "code", value: "A001" },
-            ],
-            queryBaseType: "sum",
-            queryAttributeId: ["price"],
-          },
-          // {
-          //   gridSize: 2,
-          //   type: "radar",
-          //   title: "Price per kg",
-          //   description: "Related to ESH",
-          //   spaceId: "meraque-order",
-          //   query: [
-          //     {
-          //       type: "=",
-          //       queryId: "status",
-          //       value: "Not Completed",
-          //     },
-          //     {
-          //       type: "=",
-          //       queryId: "status",
-          //       value: "Completed",
-          //     },
-          //   ],
-          //   queryBaseType: "sum",
-          //   queryAttributeId: ["cropSprayed", "areaSprayed", "pesticideUsed"],
-          //   queryBaseDateId: "startDate",
-          // },
-        ]}
-        workspace={{
-          apiEndpoint: "http://localhost:3000/api/data",
-          assetEndpoint:
-            "https://firebasestorage.googleapis.com/v0/b/esh-web-dev.appspot.com/o/",
-        }}
-      />
-    </Container>
+    <>
+      <StorySection
+        title="Card Charts"
+        description="type='card' renders a stat card. queryBaseType='count' counts records; 'sum' totals a numeric field specified in queryAttributeId. queryBaseDateId enables a date range picker on the card."
+      >
+        <div className="w-full">
+          <DataGraph
+            charts={[
+              {
+                gridSize: 1,
+                type: "card",
+                title: "Total Products",
+                description: "All products in catalogue",
+                spaceId: "esh-products",
+                query: [],
+                queryBaseType: "count",
+              },
+              {
+                gridSize: 1,
+                type: "card",
+                title: "Total Revenue",
+                description: "Sum of all order prices",
+                spaceId: "esh-products",
+                query: [],
+                queryBaseType: "sum",
+                queryAttributeId: ["price"],
+                queryBaseDateId: "createdAt",
+              },
+            ]}
+            workspace={workspace}
+            gridSize={2}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Mixed Dashboard"
+        description="Combine multiple chart types in one DataGraph. Each chart's gridSize controls how many columns it spans within the grid."
+      >
+        <div className="w-full">
+          <DataGraph
+            charts={[
+              {
+                gridSize: 1,
+                type: "card",
+                title: "All Products",
+                description: "Total product count",
+                spaceId: "esh-products",
+                query: [],
+                queryBaseType: "count",
+              },
+              {
+                gridSize: 1,
+                type: "card",
+                title: "Total Price",
+                description: "Sum of all prices",
+                spaceId: "esh-products",
+                query: [],
+                queryBaseType: "sum",
+                queryAttributeId: ["price"],
+              },
+              {
+                gridSize: 2,
+                type: "bar",
+                title: "Price per Code",
+                spaceId: "esh-products",
+                query: [
+                  { type: "=", queryId: "code", value: "P001" },
+                  { type: "=", queryId: "code", value: "N001" },
+                  { type: "=", queryId: "code", value: "A001" },
+                ],
+                queryBaseType: "sum",
+                queryAttributeId: ["price"],
+              },
+            ]}
+            workspace={workspace}
+          />
+        </div>
+      </StorySection>
+    </>
   );
-});
+}

package/lib/components/data/dataReference/README.md

@@ -4,59 +4,157 @@
 
 <hr>
 
-Data Reference
+A searchable select input that fetches its options from a remote data source. Supports single (`reference`) and multi-select (`listReference`) modes, live search, query filtering, and sort.
 
 ##### Import
 
 ```js
 import { DataReference } from "blixify-ui-web/components/data/dataReference";
+```
+
+##### Usage
+
+Single reference select:
+
+```jsx
+const [value, setValue] = useState("");
+
+<DataReference
+  value={value}
+  schema={{
+    id: "salesSelected",
+    name: "Sales Person",
+    type: "reference",
+    referenceSpaceId: "salesNameList",
+    referenceLabel: "name",
+  }}
+  devSettings={{
+    apiEndpoint: "http://localhost:3000/api",
+    apiEndpointType: "mongoDB",
+  }}
+  lib={{ axios }}
+  onChange={(value) => setValue(value)}
+/>;
+```
+
+With query filter and sort:
 
-return (
-  <div className="p-4 rounded-md bg-zinc-700">
-    <DataReference
-      value={value}
-      schema={{
-        id: "title",
-        type: "reference",
-        name: "Reference",
-        referenceLabel: "title",
-        referenceSpaceId: "meraque-cycles",
-      }}
-      devSettings={{
-        apiEndpoint: "http://localhost:3000/api/data",
-        apiEndpointType: "mongoDB",
-        assetEndpoint:
-          "https://firebasestorage.googleapis.com/v0/b/esh-web-dev.appspot.com/o/",
-      }}
-      lib={{
-        axios: axios,
-      }}
-      onChange={(value) => {
-        setValue(value);
-      }}
-      darkMode
-      staticDropdown
-    />
-  </div>
-);
+```jsx
+<DataReference
+  value={value}
+  schema={{
+    id: "salesSelected",
+    name: "Sales Person",
+    type: "reference",
+    referenceSpaceId: "salesNameList",
+    referenceLabel: "name",
+    referenceQuery: [{ type: "=", value: "Sales", queryId: "role" }],
+    referenceSort: { sortId: "name", type: "asc" },
+  }}
+  devSettings={{
+    apiEndpoint: "http://localhost:3000/api",
+    apiEndpointType: "mondayServer",
+  }}
+  lib={{ axios }}
+  onChange={(value) => setValue(value)}
+/>
+```
+
+Multi-select (listReference):
+
+```jsx
+const [value, setValue] = useState([]);
+
+<DataReference
+  value={value}
+  schema={{
+    id: "assignees",
+    name: "Assignees",
+    type: "listReference",
+    referenceSpaceId: "members",
+    referenceLabel: "name",
+  }}
+  devSettings={{
+    apiEndpoint: "http://localhost:3000/api",
+    apiEndpointType: "mongoDB",
+  }}
+  lib={{ axios }}
+  onChange={(value) => setValue(value)}
+  closeOnClickOutside
+/>;
+```
+
+Dark mode with static dropdown:
+
+```jsx
+<div className="p-4 rounded-md bg-zinc-800">
+  <DataReference
+    value={value}
+    schema={{
+      id: "title",
+      name: "Reference",
+      type: "reference",
+      referenceSpaceId: "items",
+      referenceLabel: "title",
+    }}
+    devSettings={{
+      apiEndpoint: "http://localhost:3000/api",
+      apiEndpointType: "mongoDB",
+    }}
+    lib={{ axios }}
+    onChange={(value) => setValue(value)}
+    darkMode
+    staticDropdown
+  />
+</div>
 ```
 
 ##### Required props
 
-| Name   | Type            | Description                          |
-| ------ | --------------- | ------------------------------------ |
-| value  | `any`           | Value (string or an array of string) |
-| schema | `DataStructure` | Refer to DataStructure               |
+| Name     | Type            | Description                                                                 |
+| -------- | --------------- | --------------------------------------------------------------------------- |
+| `value`  | `any`           | Current value — a string for `reference`, or `string[]` for `listReference` |
+| `schema` | `DataStructure` | Column definition — see schema fields below                                 |
 
 ##### Optional props
 
-| Name                | Type                   | Description                                                                                                                            |
-| ------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
-| devSettings         | `WorkspaceDevSettings` | Refer WorkspaceDevSettings                                                                                                             |
-| onChange            | `(value: any) => void` | On change callback function                                                                                                            |
-| lib                 | `{ axios?: any}`       | Additional libraries                                                                                                                   |
-| optional            | `boolean`              |                                                                                                                                        |
-| darkMode            | `booelan`              |                                                                                                                                        |
-| staticDropdown      | `booelan`              | When `true`, the parent container's height will expand to fit this component.                                                          |
-| closeOnClickOutside | `booelan`              | When `true`, the option container will remain open and close when users clicks outside of the container. Only applies to multi select. |
-| subLabel            | `string`               | Sub Label text for better UI/UX Explanation for the select                                                                             |
+| Name                  | Type                   | Description                                                                                                          |
+| --------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `devSettings`         | `WorkspaceDevSettings` | API connection settings — see WorkspaceDevSettings below                                                             |
+| `lib`                 | `{ axios?: any }`      | Pass your axios instance for making API requests                                                                     |
+| `onChange`            | `(value: any) => void` | Called with the new value when the selection changes                                                                 |
+| `optional`            | `boolean`              | When `true`, skips validation on `handleSubmit`                                                                      |
+| `subLabel`            | `string`               | Secondary label rendered below the main label for additional context                                                 |
+| `darkMode`            | `boolean`              | Switches the select to a dark theme                                                                                  |
+| `staticDropdown`      | `boolean`              | When `true`, the parent container expands to fit the open dropdown instead of the dropdown overlapping content below |
+| `closeOnClickOutside` | `boolean`              | When `true`, the dropdown closes when the user clicks outside. Applies to `listReference` (multi-select) mode        |
+
+##### Schema fields (DataStructure)
+
+Only fields relevant to `DataReference` are listed. `type` must be `"reference"` or `"listReference"`.
+
+| Name                      | Type                             | Description                                                                         |
+| ------------------------- | -------------------------------- | ----------------------------------------------------------------------------------- |
+| `id`                      | `string`                         | Unique field identifier                                                             |
+| `name`                    | `string`                         | Label displayed above the select                                                    |
+| `type`                    | `"reference" \| "listReference"` | `"reference"` for single select, `"listReference"` for multi-select                 |
+| `referenceSpaceId`        | `string`                         | The collection/space ID to fetch options from                                       |
+| `referenceLabel`          | `string`                         | The field key in each fetched record to use as the option label                     |
+| `referenceSecondaryLabel` | `string`                         | Optional secondary label field shown below the primary label in each option         |
+| `referenceQuery`          | `Query[]`                        | Optional filter queries applied when fetching options                               |
+| `referenceSort`           | `Sort`                           | Optional sort applied when fetching options, e.g. `{ sortId: "name", type: "asc" }` |
+| `placeholder`             | `string`                         | Placeholder text shown when no value is selected                                    |
+| `disabled`                | `boolean`                        | Disables the select input                                                           |
+| `optional`                | `boolean`                        | Marks the field as optional in form validation                                      |
+
+##### WorkspaceDevSettings
+
+| Name               | Type                                                                       | Description                        |
+| ------------------ | -------------------------------------------------------------------------- | ---------------------------------- |
+| `apiEndpoint`      | `string`                                                                   | Base URL for the data API          |
+| `apiEndpointType`  | `"mongoDB" \| "firebase" \| "mongoServer" \| "fbServer" \| "mondayServer"` | The server/DB type driving the API |
+| `apiEndpointToken` | `string`                                                                   | Auth token for the API endpoint    |
+| `apiUserToken`     | `string`                                                                   | Per-user auth token                |
+| `assetEndpoint`    | `string`                                                                   | Base URL for asset/file storage    |
+| `assetType`        | `"firebase" \| "aws"`                                                      | Storage provider type              |
+| `assetBucket`      | `string`                                                                   | Storage bucket name                |