blixify-ui-web-mcp 0.1.1

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

@@ -0,0 +1,56 @@
+# Query Form
+
+<!-- STORY -->
+
+<hr>
+
+Query Form
+
+##### Import
+
+```js
+import { QueryForm } from "blixify-ui-web/components/data/readQuery";
+```
+
+##### Usage
+
+```jsx
+return (
+  <QueryForm
+    dbModule={axios}
+    model={schema}
+    devSettings={{
+      schemaEndpoint: schemaUrl,
+      server: devSettings.defaultServer,
+      dbEndpoint: devSettings.defaultAPIUrl,
+      dbAPIToken: devSettings.defaultDBAPIToken,
+      imageEndpoint: devSettings.defaultAssetAPI,
+      uploadEndpoint: devSettings.defaultAssetUploadEndpoint,
+      bucketName: devSettings.defaultBucketName,
+    }}
+    renderReferenceLabelOptions={renderReferenceLabelOptions}
+  />
+);
+```
+
+##### Query Form Props
+
+| Name          | Type                   | Description                  | Optional |
+| ------------- | ---------------------- | ---------------------------- | -------- |
+| `dbModule`    | `axios or firebase`    | Class                        |          |
+| `model`       | `Model Data Structure` | Refer to Blixify Space Model |          |
+| `devSettings` | `DevSettings`          | Eg api.example.com           |          |
+
+##### Call Method
+
+| Name          | Type              | Description | Optional                          |
+| ------------- | ----------------- | ----------- | --------------------------------- |
+| `referenceRQ` | `ReadQuery Class` | Query Type  | Returns { data : any } if success |
+
+##### QueryInput Class
+
+| Name      | Type             | Description | Optional |
+| --------- | ---------------- | ----------- | -------- |
+| `queryId` | `string`         | Query ID    |          |
+| `type`    | `= / < / > / ><` | Query Type  |          |
+| `value`   | `string`         | Query Value |          |

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

@@ -0,0 +1,85 @@
+import { storiesOf } from "@storybook/react";
+import axios from "axios";
+import React, { useEffect, useState } from "react";
+import { QueryForm } from ".";
+import { Loading } from "../../display/loading";
+import { Space } from "../dataTemplate/spaceModel";
+import { Workspace } from "../dataTemplate/workspaceModel";
+import {
+  defaultDBEndpoint,
+  defaultImageEndpoint,
+  defaultUploadEndpoint,
+  getAllSpacesList,
+  getSpaceData,
+  getWorkspaceData,
+  schemaUrl,
+  storyRenderReferenceLabelOptions,
+} from "../stories";
+import { blixifyDevCollection, blixifyDevWorkspace } from "../testData";
+import { parseSpaceToDataStructure, parseWorkspaceSettings } from "../utils";
+import README from "./README.md";
+
+const stories = storiesOf("Data", module);
+
+stories.addParameters({
+  readme: {
+    content: README,
+  },
+});
+
+stories.add("Query Form", () => {
+  const [selectedSpace, setSelectedSpace] = useState<Space | null>(null);
+  const [allWorkspaceSpace, setAllWorkspaceSpace] = useState<Space[]>([]);
+  const [selectedWorkspace, setSelectedWorkspace] =
+    useState<Workspace | null>(null);
+  const devSettings = parseWorkspaceSettings(
+    {
+      dbEndpoint: defaultDBEndpoint,
+      imageEndpoint: defaultImageEndpoint,
+      uploadEndpoint: defaultUploadEndpoint,
+    },
+    selectedWorkspace
+  );
+  const collectionParam = blixifyDevCollection;
+  const workspaceParam = blixifyDevWorkspace;
+
+  useEffect(() => {
+    handleRetrieveData();
+  }, []);
+
+  const handleRetrieveData = async () => {
+    if (collectionParam) {
+      const space: Space = await getSpaceData(collectionParam);
+      if (space) {
+        setSelectedSpace(space);
+      }
+    }
+    if (workspaceParam) {
+      const workspace: any = await getWorkspaceData(workspaceParam);
+      if (workspace) {
+        setSelectedWorkspace(workspace);
+        const allSpaces = await getAllSpacesList(workspaceParam);
+        if (allSpaces) setAllWorkspaceSpace(allSpaces);
+      }
+    }
+  };
+
+  if (selectedSpace && selectedWorkspace) {
+    return (
+      <QueryForm
+        updateQuery={undefined}
+        dbModule={axios}
+        model={parseSpaceToDataStructure(selectedSpace)}
+        devSettings={{
+          ...devSettings,
+          schemaEndpoint: schemaUrl,
+        }}
+        handleCloseForm={() => {}}
+        renderReferenceLabelOptions={storyRenderReferenceLabelOptions(
+          allWorkspaceSpace,
+          selectedSpace
+        )}
+      />
+    );
+  } else return <Loading />;
+});

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

@@ -0,0 +1,282 @@
+# Read Query
+
+<!-- STORY -->
+
+<hr>
+
+`ReadQuery` is a low-level utility class for fetching data directly from MongoDB (via server) or Firebase. Use it when you need raw query access outside of DataTemplate or DataTemplateWrapper — for example, fetching lookup data, running aggregations, or building custom data flows.
+
+## How It Works
+
+1. Instantiate `ReadQuery` with your database config
+2. Call `.call(cond)` with a `ReadQueryType` object
+3. Get back `{ data, count? }` on success
+
+## Setup
+
+```ts
+import axios from "axios";
+import { ReadQuery } from "blixify-ui-web/data/readQuery";
+
+const query = new ReadQuery({
+  dbModule: axios,
+  dbType: "mongoDB", // "mongoDB" | "fbServer" | "firebase"
+  dbCollection: "tasks",
+  dbEndpoint: "https://api.example.com/api/mongoData",
+  dbAPIToken: "your-api-token", // optional
+  dbUserToken: "user-id-token", // optional
+});
+```
+
+## Usage Examples
+
+### Get a single record
+
+```ts
+const res = await query.call({
+  type: "get",
+  id: "abc123",
+});
+// res.data → single document
+```
+
+### List with filter and sort
+
+```ts
+const res = await query.call({
+  type: "list",
+  query: [{ queryId: "status", type: "=", value: "active" }],
+  sort: { sortId: "createdAt", type: "desc" },
+  limit: 20,
+});
+// res.data → array, res.count → cursor for next page
+```
+
+### Paginate with cursor
+
+```ts
+const res = await query.call({
+  type: "list",
+  query: [],
+  sort: { sortId: "createdAt", type: "desc" },
+  limit: 20,
+  cursor: lastCursorValue, // from previous res.count
+});
+```
+
+### Range filter (date between two values)
+
+```ts
+const res = await query.call({
+  type: "list",
+  query: [
+    {
+      queryId: "createdAt",
+      type: "><",
+      value: ["2024-01-01T00:00:00Z", "2024-12-31T23:59:59Z"],
+    },
+  ],
+  limit: 50,
+});
+```
+
+### OR query (group multiple conditions)
+
+```ts
+const res = await query.call({
+  type: "list",
+  query: [
+    {
+      queryId: "proposed_date",
+      type: ">",
+      value: "2024-01-01",
+      orQuery: true,
+      orQueryGroupId: "dateGroup",
+    },
+    {
+      queryId: "actual_date",
+      type: ">",
+      value: "2024-01-01",
+      orQuery: true,
+      orQueryGroupId: "dateGroup",
+    },
+  ],
+  limit: 50,
+});
+```
+
+### Search across multiple fields
+
+```ts
+const res = await query.call({
+  type: "list",
+  query: [
+    {
+      type: "search",
+      searchIds: ["name", "email"],
+      value: "john",
+    },
+  ],
+  limit: 20,
+});
+```
+
+### Aggregate — count
+
+```ts
+const res = await query.call({
+  type: "list",
+  query: [{ queryId: "status", type: "=", value: "active" }],
+  aggregate: { type: "count", queryId: "" },
+});
+// res.data → number
+```
+
+### Aggregate — sum with date range
+
+```ts
+const res = await query.call({
+  type: "list",
+  aggregate: {
+    type: "sum",
+    queryId: "amount",
+    dateId: "createdAt",
+    range: ["01/01/2024 00:00:00-31/12/2024 23:59:59"],
+    timezone: "Asia/Kuala_Lumpur",
+  },
+});
+```
+
+### Union collections (merge multiple collections)
+
+```ts
+const res = await query.call({
+  type: "list",
+  unionCollections: [
+    {
+      collection: "deliveries",
+      source: "Delivery",
+      query: [{ queryId: "status", type: "=", value: "active" }],
+      projection: { _id: 1, name: 1, status: 1, createdAt: 1 },
+    },
+    {
+      collection: "service-tickets",
+      source: "dynamic",
+      sourceLogic: {
+        $cond: {
+          if: { $eq: ["$category", "Defect"] },
+          then: "Defect",
+          else: "Other",
+        },
+      },
+      projection: { _id: 1, name: 1, status: 1, createdAt: 1 },
+    },
+  ],
+  sort: { sortId: "createdAt", type: "desc" },
+  limit: 50,
+});
+```
+
+### Pipeline (advanced MongoDB aggregation)
+
+```ts
+const res = await query.call({
+  type: "get",
+  id: "abc123",
+  pipeline: [
+    {
+      $lookup: {
+        from: "users",
+        localField: "userId",
+        foreignField: "_id",
+        as: "user",
+      },
+    },
+    { $unwind: "$user" },
+  ],
+});
+```
+
+### Fetch only specific fields
+
+```ts
+const res = await query.call({
+  type: "list",
+  attributeIds: ["name", "status", "createdAt"], // only return these fields
+  limit: 50,
+});
+```
+
+---
+
+## Constructor
+
+| Param          | Type                              | Description          | Optional |
+| -------------- | --------------------------------- | -------------------- | -------- |
+| `dbModule`     | `axios \| firebase`               | HTTP/Firebase module |          |
+| `dbType`       | `mongoDB \| fbServer \| firebase` | Backend type         |          |
+| `dbCollection` | `string`                          | Collection name      |          |
+| `dbEndpoint`   | `string`                          | API base URL         | ✓        |
+| `dbAPIToken`   | `string`                          | API token            | ✓        |
+| `dbUserToken`  | `string`                          | User ID token        | ✓        |
+
+## ReadQueryType
+
+| Param                 | Type                | Description                 | Optional              |
+| --------------------- | ------------------- | --------------------------- | --------------------- |
+| `type`                | `get \| list`       | Query type                  |                       |
+| `id`                  | `string`            | Document ID                 | Required for `get`    |
+| `query`               | `Query[]`           | Filter conditions           | ✓                     |
+| `attributeIds`        | `string[]`          | Fields to include           | ✓                     |
+| `excludeAttributeIds` | `string[]`          | Fields to exclude           | ✓                     |
+| `cursor`              | `any`               | Pagination cursor           | ✓                     |
+| `skip`                | `number`            | Skip N records (union only) | ✓                     |
+| `limit`               | `number`            | Max records to return       | Required for Firebase |
+| `sort`                | `Sort \| Sort[]`    | Sort config                 | ✓                     |
+| `aggregate`           | `Aggregate`         | Aggregation config          | ✓                     |
+| `stopLimit`           | `boolean`           | Pull all records (no limit) | ✓                     |
+| `pipeline`            | `PipeLine[]`        | Raw MongoDB pipeline        | ✓                     |
+| `foreign`             | `Foreign[]`         | Foreign collection joins    | ✓                     |
+| `unionCollections`    | `UnionCollection[]` | Merge multiple collections  | ✓                     |
+| `uniqueLabel`         | `string`            | Cache label for the query   | ✓                     |
+
+## Query
+
+| Param            | Type                                                                                      | Description                                 | Optional                 |
+| ---------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------- | ------------------------ |
+| `type`           | `search \| = \| != \| > \| < \| >< \| in \| !in \| exists \| elemMatch \| >size \| <size` | Operator                                    |                          |
+| `value`          | `any`                                                                                     | Filter value (array for `><` and `in`)      |                          |
+| `queryId`        | `string`                                                                                  | Field name                                  | Required except `search` |
+| `searchIds`      | `string[]`                                                                                | Fields to search across                     | Required for `search`    |
+| `orQuery`        | `boolean`                                                                                 | Use OR instead of AND                       | ✓                        |
+| `orQueryGroupId` | `string`                                                                                  | Group OR conditions with AND between groups | ✓                        |
+
+## Aggregate
+
+| Param      | Type                           | Description                                            | Optional |
+| ---------- | ------------------------------ | ------------------------------------------------------ | -------- |
+| `type`     | `count \| avg \| sum \| value` | Aggregation type                                       |          |
+| `queryId`  | `string`                       | Field to aggregate                                     |          |
+| `groupId`  | `string`                       | Group by field                                         | ✓        |
+| `dateId`   | `string`                       | Date field for range filter                            | ✓        |
+| `range`    | `string[]`                     | Date range `"DD/MM/YYYY HH:mm:ss-DD/MM/YYYY HH:mm:ss"` | ✓        |
+| `timezone` | `string`                       | Timezone string e.g. `"Asia/Kuala_Lumpur"`             | ✓        |
+
+## Sort
+
+| Param              | Type          | Description                  | Optional |
+| ------------------ | ------------- | ---------------------------- | -------- |
+| `sortId`           | `string`      | Field to sort by             |          |
+| `type`             | `asc \| desc` | Sort direction               |          |
+| `sortBeforeFilter` | `boolean`     | Sort before applying filters | ✓        |
+
+## UnionCollection
+
+| Param         | Type                  | Description                                                | Optional |
+| ------------- | --------------------- | ---------------------------------------------------------- | -------- |
+| `collection`  | `string`              | Collection name                                            |          |
+| `source`      | `string \| "dynamic"` | Label for this source, or `"dynamic"` to use `sourceLogic` |          |
+| `sourceLogic` | `any`                 | MongoDB `$cond` expression for dynamic source label        | ✓        |
+| `query`       | `Query[]`             | Per-collection filters                                     | ✓        |
+| `projection`  | `any`                 | Fields to return                                           | ✓        |
+| `addFields`   | `any`                 | Computed fields to add                                     | ✓        |

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

@@ -0,0 +1,256 @@
+import { storiesOf } from "@storybook/react";
+import axios from "axios";
+import moment from "moment-timezone";
+import React, { useState } from "react";
+import { ReadQuery } from ".";
+import { Button } from "../../action/button";
+import { StorySection } from "../../storyUtils";
+import README from "./README.md";
+
+const stories = storiesOf("Data", module);
+
+stories.addParameters({
+  readme: { content: README },
+});
+
+const query = new ReadQuery({
+  dbModule: axios,
+  dbType: "fbServer",
+  dbCollection: "users",
+  dbEndpoint: "https://api.example.com/api/mongoData",
+});
+
+stories.add("Read Query", () => {
+  const [result, setResult] = useState<string>("");
+
+  const run = async (label: string, fn: () => Promise<any>) => {
+    try {
+      const res = await fn();
+      setResult(`[${label}] ${JSON.stringify(res?.data ?? res)}`);
+    } catch (err: any) {
+      setResult(`[${label}] Error: ${err?.message ?? String(err)}`);
+    }
+  };
+
+  return (
+    <div className="flex flex-col gap-6 w-full p-4">
+      <StorySection
+        title="Get Single Record"
+        description="Fetch one document by ID using type: 'get'."
+      >
+        <Button
+          text="Get by ID"
+          type="light"
+          onClick={() =>
+            run("get", () => query.call({ type: "get", id: "abc123" }))
+          }
+        />
+      </StorySection>
+
+      <StorySection
+        title="List with Filter & Sort"
+        description="Fetch a filtered, sorted list. Returns data array and a cursor for pagination."
+      >
+        <Button
+          text="List Active Users"
+          type="light"
+          onClick={() =>
+            run("list", () =>
+              query.call({
+                type: "list",
+                query: [{ queryId: "status", type: "=", value: "active" }],
+                sort: { sortId: "createdAt", type: "desc" },
+                limit: 20,
+              })
+            )
+          }
+        />
+      </StorySection>
+
+      <StorySection
+        title="Range Filter"
+        description="Filter records where a field falls between two values using type: '><'."
+      >
+        <Button
+          text="Date Range Query"
+          type="light"
+          onClick={() =>
+            run("range", () =>
+              query.call({
+                type: "list",
+                query: [
+                  {
+                    queryId: "createdAt",
+                    type: "><",
+                    value: ["2024-01-01T00:00:00Z", "2024-12-31T23:59:59Z"],
+                  },
+                ],
+                sort: { sortId: "createdAt", type: "desc" },
+                limit: 50,
+              })
+            )
+          }
+        />
+      </StorySection>
+
+      <StorySection
+        title="OR Query"
+        description="Group conditions with orQuery + orQueryGroupId so records matching either condition are returned."
+      >
+        <Button
+          text="OR Query"
+          type="light"
+          onClick={() =>
+            run("or", () =>
+              query.call({
+                type: "list",
+                query: [
+                  {
+                    queryId: "proposed_date",
+                    type: ">",
+                    value: "2024-01-01",
+                    orQuery: true,
+                    orQueryGroupId: "dateGroup",
+                  },
+                  {
+                    queryId: "actual_date",
+                    type: ">",
+                    value: "2024-01-01",
+                    orQuery: true,
+                    orQueryGroupId: "dateGroup",
+                  },
+                ],
+                limit: 50,
+              })
+            )
+          }
+        />
+      </StorySection>
+
+      <StorySection
+        title="Search Across Fields"
+        description="Full-text style search across multiple fields using type: 'search'."
+      >
+        <Button
+          text="Search 'john'"
+          type="light"
+          onClick={() =>
+            run("search", () =>
+              query.call({
+                type: "list",
+                query: [
+                  {
+                    type: "search",
+                    searchIds: ["name", "email"],
+                    value: "john",
+                  },
+                ],
+                limit: 20,
+              })
+            )
+          }
+        />
+      </StorySection>
+
+      <StorySection
+        title="Aggregate — Count"
+        description="Count documents matching a filter. Returns a number in res.data."
+      >
+        <Button
+          text="Count Active"
+          type="light"
+          onClick={() =>
+            run("count", () =>
+              query.call({
+                type: "list",
+                query: [{ queryId: "status", type: "=", value: "active" }],
+                aggregate: { type: "count", queryId: "" },
+              })
+            )
+          }
+        />
+      </StorySection>
+
+      <StorySection
+        title="Aggregate — Sum with Date Range"
+        description="Sum a numeric field within a date range. Requires dateId and range together."
+      >
+        <Button
+          text="Sum Amount"
+          type="light"
+          onClick={() =>
+            run("sum", () =>
+              query.call({
+                type: "list",
+                aggregate: {
+                  type: "sum",
+                  queryId: "amount",
+                  dateId: "createdAt",
+                  range: ["01/01/2024 00:00:00-31/12/2024 23:59:59"],
+                  timezone: moment.tz.guess(),
+                },
+              })
+            )
+          }
+        />
+      </StorySection>
+
+      <StorySection
+        title="Fetch Specific Fields"
+        description="Use attributeIds to return only the fields you need, reducing payload size."
+      >
+        <Button
+          text="Fetch name + status only"
+          type="light"
+          onClick={() =>
+            run("fields", () =>
+              query.call({
+                type: "list",
+                attributeIds: ["name", "status", "createdAt"],
+                limit: 50,
+              })
+            )
+          }
+        />
+      </StorySection>
+
+      <StorySection
+        title="Union Collections"
+        description="Merge records from multiple collections into one list. Each collection can have its own query and projection."
+      >
+        <Button
+          text="Union Query"
+          type="light"
+          onClick={() =>
+            run("union", () =>
+              query.call({
+                type: "list",
+                unionCollections: [
+                  {
+                    collection: "deliveries",
+                    source: "Delivery",
+                    query: [{ queryId: "status", type: "=", value: "active" }],
+                    projection: { _id: 1, name: 1, status: 1, createdAt: 1 },
+                  },
+                  {
+                    collection: "service-tickets",
+                    source: "Service Ticket",
+                    projection: { _id: 1, name: 1, status: 1, createdAt: 1 },
+                  },
+                ],
+                sort: { sortId: "createdAt", type: "desc" },
+                limit: 50,
+              })
+            )
+          }
+        />
+      </StorySection>
+
+      {result && (
+        <div className="mt-4 p-3 bg-gray-100 rounded text-xs text-gray-700 break-all w-full">
+          {result}
+        </div>
+      )}
+    </div>
+  );
+});