blixify-ui-web-mcp 0.1.60 → 0.1.62

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

@@ -89,6 +89,46 @@ Radar chart comparing multiple attributes across query groups:
 }
 ```
 
+Grouped by any column, top 5 with the rest as "Others", highest first:
+
+```jsx
+{
+  gridSize: 2,
+  type: "table",
+  title: "Leads by Agent",
+  spaceId: "leads",
+  query: [],
+  queryBaseType: "count",
+  groupBy: "agent",
+  sortBy: "value",
+  sortDirection: "desc",
+  topN: 5,
+}
+```
+
+Revenue per month as a running total, split by status:
+
+```jsx
+{
+  gridSize: 2,
+  type: "bar",
+  title: "Revenue per Month",
+  spaceId: "orders",
+  query: [],
+  queryBaseType: "sum",
+  queryAttributeId: ["amount"],
+  queryBaseDateId: "paidAt",
+  queryDateInterval: "month",
+  cumulative: true,
+  segmentBy: "status",
+}
+```
+
+A chart that can't load or draw shows an error card in its place — a plain
+message, Retry, and the technical cause under Details — and the other charts
+keep drawing. Pass `structure` so a sum or average of a text column is caught
+before any request is sent.
+
 Custom layout via renderSettings:
 
 ```jsx
@@ -114,6 +154,9 @@ Custom layout via renderSettings:
 | ---------------- | ------------------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------- |
 | `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. |
+| `structure`      | `DataStructure[]`                          | —       | The datasheet's columns. Groups read by their labels, and a chart measuring a column that is not a number shows why before any request. |
+| `personOptions`  | `Option[]`                                 | —       | Names for the user ids a `person` column groups by.                                                                                    |
+| `onDrillDown`    | `(drillDown: ChartDrillDown) => void`      | —       | Called when a bar, slice or table row is clicked, with its label and the query that finds its records.                                 |
 
 ##### Charts
 
@@ -139,6 +182,13 @@ Custom layout via renderSettings:
 | `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                                                                                                        |
+| `groupBy`          | `string`                                        | Column of any type to group by in one request. A `reference` or `person` column reads by name.                                           |
+| `queryDateInterval`| `"day" \| "week" \| "month"`                    | With `queryBaseDateId`, buckets records by day, week or month. Defaults to the last 30 days, 12 weeks or 12 months.                      |
+| `segmentBy`        | `string`                                        | Second column split into stacked series (bar, line, table), at most 10 values plus "Others".                                             |
+| `sortBy`           | `"value" \| "label"`                             | Sort the groups. `sortDirection` is `"asc"` or `"desc"` (default).                                                                       |
+| `topN`             | `number`                                        | Keep the first N groups; the rest are added up as "Others" unless `showOthers` is `false` (averages never get "Others").                 |
+| `showPercent`      | `boolean`                                       | Show each group as a percentage of the total (count and sum, unsplit charts).                                                            |
+| `cumulative`       | `boolean`                                       | Running total over the date buckets.                                                                                                     |
 
 ##### WorkspaceDevSettings
 

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

@@ -513,14 +513,24 @@ const CHART_SCHEMA: DataStructure[] = [
     listSelection: ["web", "store", "phone"],
     listSelectionLabel: ["Web", "Store", "Phone"],
   },
+  { id: "agent", name: "Agent", type: "person" },
   { id: "amount", name: "Amount", type: "number" },
   { id: "items", name: "Items", type: "number" },
   { id: "createdAt", name: "Created At", type: "date" },
 ];
 
+const CHART_MEMBERS = [
+  { key: "u1", label: "Aisha" },
+  { key: "u2", label: "Ben" },
+  { key: "u3", label: "Chong" },
+  { key: "u4", label: "Devi" },
+  { key: "u5", label: "Eli" },
+];
+
 const renderChartRecords = () => {
   const statuses = ["pending", "paid", "shipped", "cancelled"];
   const channels = ["web", "store", "phone"];
+  const agents = ["u1", "u2", "u3", "u1", "u4", "u1", "u2", "u5"];
   return Array.from({ length: 40 }, (_, index) => ({
     _id: `o${index + 1}`,
     orderNo: `ORD-${1000 + index}`,
@@ -528,7 +538,16 @@ const renderChartRecords = () => {
     channel: channels[(index * 5) % channels.length],
     amount: 20 + ((index * 37) % 180),
     items: 1 + ((index * 3) % 6),
-    createdAt: new Date(Date.now() - (index % 7) * 24 * 60 * 60 * 1000),
+    agent: index % 9 === 0 ? undefined : agents[index % agents.length],
+    // INFO: half in the last week for the daily line, the rest over months
+    createdAt: new Date(
+      Date.now() -
+        (index % 2 === 0 ? index % 7 : (index * 11) % 300) *
+          24 *
+          60 *
+          60 *
+          1000,
+    ),
   }));
 };
 
@@ -552,12 +571,26 @@ const handleInstallChartMock = (store: any[]) => {
       return {};
     }
   };
-  // INFO: "=" for chart groups, "search" for the search box — enough to show
+  // INFO: the conditions charts and their drill-downs send — enough to show
   // the table's filters reaching the charts
   const handleMatch = (record: any, query: any[] = []) =>
     query.every((eachQuery) => {
-      if (eachQuery.type === "=")
-        return record[eachQuery.queryId] === eachQuery.value;
+      const value = record[eachQuery.queryId];
+      // INFO: null matches a missing value too, as Mongo's { column: null }
+      if (eachQuery.type === "=") return (value ?? null) === eachQuery.value;
+      if (eachQuery.type === "in")
+        return eachQuery.value.includes(value ?? null);
+      if (eachQuery.type === "!in")
+        return !eachQuery.value.includes(value ?? null);
+      if (eachQuery.type === "exists")
+        return (value !== undefined && value !== null) === eachQuery.value;
+      if (eachQuery.type === "><")
+        return (
+          new Date(value) >= new Date(eachQuery.value[0]) &&
+          new Date(value) <= new Date(eachQuery.value[1])
+        );
+      if (eachQuery.type === "<")
+        return new Date(value) < new Date(eachQuery.value);
       if (eachQuery.type === "search")
         return Object.values(record).some((eachValue) =>
           String(eachValue)
@@ -602,6 +635,20 @@ const handleInstallChartMock = (store: any[]) => {
             );
           })
         : matched;
+      if (body.aggregate.groupId) {
+        const groups = new Map<any, any[]>();
+        inRange.forEach((eachRecord) => {
+          const key = eachRecord[body.aggregate.groupId] ?? null;
+          groups.set(key, [...(groups.get(key) ?? []), eachRecord]);
+        });
+        return {
+          _id: eachRange,
+          value: Array.from(groups.entries()).map(([key, records]) => ({
+            _id: key,
+            value: handleAggregate(records, body.aggregate),
+          })),
+        };
+      }
       return {
         _id: eachRange,
         value: handleAggregate(inRange, body.aggregate),
@@ -705,6 +752,55 @@ const ChartViewDemo = () => {
           seriesLabels: ["Pending", "Paid", "Shipped", "Cancelled"],
           queryBaseType: "count",
         },
+        {
+          title: "Top Agents",
+          type: "table",
+          gridSize: 2,
+          spaceId: CHART_COLLECTION,
+          query: [],
+          queryBaseType: "count",
+          groupBy: "agent",
+          sortBy: "value",
+          sortDirection: "desc",
+          topN: 3,
+        },
+        {
+          title: "Revenue Per Month",
+          type: "bar",
+          orientation: "col",
+          gridSize: 2,
+          spaceId: CHART_COLLECTION,
+          query: [],
+          queryBaseType: "sum",
+          queryAttributeId: ["amount"],
+          queryBaseDateId: "createdAt",
+          queryDateInterval: "month",
+          cumulative: true,
+        },
+        {
+          title: "Channel By Status",
+          type: "bar",
+          orientation: "col",
+          gridSize: 2,
+          spaceId: CHART_COLLECTION,
+          query: ["web", "store", "phone"].map((eachValue) => ({
+            type: "=" as const,
+            queryId: "channel",
+            value: eachValue,
+          })),
+          seriesLabels: ["Web", "Store", "Phone"],
+          queryBaseType: "count",
+          segmentBy: "status",
+        },
+        {
+          title: "Sum Of Order No",
+          type: "card",
+          gridSize: 2,
+          spaceId: CHART_COLLECTION,
+          query: [],
+          queryBaseType: "sum",
+          queryAttributeId: ["orderNo"],
+        },
       ],
     },
   ]);
@@ -719,7 +815,7 @@ const ChartViewDemo = () => {
         collectionId={CHART_COLLECTION}
         model={CHART_SCHEMA}
         localURLEndpoint=""
-        devSettings={demoDevSettings}
+        devSettings={{ ...demoDevSettings, organisationMembers: CHART_MEMBERS }}
         lib={{ axios, Menu, Transition, papaParser: Papa }}
         limit={10}
         edit={{ allEditable: true }}

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

@@ -259,6 +259,38 @@ const isStatusClosed = liveFilters.some(
 );
 ```
 
+**Filtering on a referenced record's fields**
+
+`bareFlexFilterReferences` maps a `reference` or `listReference` column to the collection it points to and that collection's columns. The list and export filters then offer each of those columns as `<Column> › <Field>`, one level deep. A condition on one is sent with a `foreign` lookup (alias `ref_<column>`), which MongoWrapper joins before its `$match`. Hidden columns, `_id`, and reference, file and object columns of the referenced record are not offered.
+
+```tsx
+bareSettings={{
+  bareFlexFilters: true,
+  bareFlexFilterReferences: {
+    lead: { collection: "master-leads", structure: LeadSchema },
+  },
+}}
+
+// "Lead › Status is Won" is sent as
+// { type: "=", queryId: "ref_lead.status", value: "Won",
+//   foreign: [{ collection: "master-leads", localField: "lead", alias: "ref_lead", searchFields: [] }] }
+```
+
+**Filtering on a listObject**
+
+`bareFlexFilterListObjects: true` offers each `listObject` column's fields as `<List> › <Field>`, sent on their path (`crew.role`), so a record matches when any row does. It also offers `<List> › Count` with Is, Greater Than, Less Than and Between. A count is sent as whether the list's n-th row exists, so it holds on records where the list was never set:
+
+| Count filter | Sent as |
+| --- | --- |
+| Is 3 | `crew.2` exists, `crew.3` does not |
+| Greater Than 2 | `crew.2` exists |
+| Less Than 2 | `crew.1` does not exist |
+| Between 2 and 5 | `crew.1` exists, `crew.5` does not |
+
+Two conditions on one list may each be met by a different row. Referenced records and listObjects are not offered on Firebase or `unionCollections` lists.
+
+The standalone `FlexFilter` takes both as `extras={{ references, listObjects: true }}`; pass the same object to `renderFlexFilterConditions` when building the query.
+
 **8. newTabUrl (Optional)**
 
 Enables right-click → "Open in new tab" on list rows. The component builds the link as `default + recordId + addons`.

package/lib/components/data/flexFilter/flexFilterReference.stories.tsx

@@ -0,0 +1,183 @@
+import { Transition } from "@headlessui/react";
+import axios from "axios";
+import React, { useState } from "react";
+import { StorySection } from "../../storyUtils";
+import { Loading } from "../../display/loading";
+import { DataStructure, DevSettings } from "../dataTemplate/model";
+import { DataTemplateWrapper } from "../dataWrapper";
+import {
+  STORY_API_ENDPOINT,
+  STORY_NAMES,
+  storyWorkspace,
+  useStoryBackend,
+} from "../dataWrapper/storyBackend.fixtures";
+import {
+  FlexFilter,
+  FlexFilterReferences,
+  renderFlexFilterConditions,
+} from ".";
+import { FlexFilterData } from "./model";
+
+const meta = { title: "Data/Flex Filter/Referenced Record" };
+export default meta;
+
+const LEAD_COLLECTION = "demo-ref-leads";
+const REFERRAL_COLLECTION = "demo-ref-referrals";
+const LEAD_STATUSES = ["New", "Quoted", "Won", "Lost"];
+
+const leadSchema: DataStructure[] = [
+  { id: "name", name: "Name", type: "string" },
+  {
+    id: "status",
+    name: "Status",
+    type: "list",
+    listSelection: LEAD_STATUSES,
+  },
+  { id: "systemSize", name: "System Size (kWp)", type: "number" },
+  { id: "signedAt", name: "Signed Date", type: "date" },
+];
+
+const referralSchema: DataStructure[] = [
+  { id: "referrer", name: "Referrer", type: "string" },
+  {
+    id: "leadId",
+    name: "Lead",
+    type: "reference",
+    referenceSpaceId: LEAD_COLLECTION,
+    referenceLabel: "name",
+  },
+  {
+    id: "payout",
+    name: "Payout",
+    type: "list",
+    listSelection: ["Pending", "Paid"],
+  },
+  { id: "createdAt", name: "Created At", type: "date" },
+  {
+    id: "followUps",
+    name: "Follow-ups",
+    type: "listObject",
+    objectData: [
+      {
+        id: "outcome",
+        name: "Outcome",
+        type: "list",
+        listSelection: ["No Answer", "Callback", "Site Visit"],
+      },
+      { id: "note", name: "Note", type: "string" },
+    ],
+  },
+];
+
+const OUTCOMES = ["No Answer", "Callback", "Site Visit"];
+
+const references: FlexFilterReferences = {
+  leadId: { collection: LEAD_COLLECTION, structure: leadSchema },
+};
+
+// INFO: dates spread around today, so "This month" and "Last 30 days" match some
+const handleDaysAgo = (days: number) =>
+  new Date(Date.now() - days * 86400000).toISOString();
+
+const leads = STORY_NAMES.slice(0, 12).map((name, index) => ({
+  _id: `lead-${index + 1}`,
+  name,
+  status: LEAD_STATUSES[index % LEAD_STATUSES.length],
+  systemSize: 4 + (index % 5) * 2,
+  signedAt: handleDaysAgo(index * 9),
+}));
+
+const referrals = leads.map((eachLead, index) => ({
+  _id: `referral-${index + 1}`,
+  referrer: STORY_NAMES[(index + 5) % STORY_NAMES.length],
+  leadId: eachLead._id,
+  payout: index % 3 === 0 ? "Paid" : "Pending",
+  createdAt: handleDaysAgo(index * 4),
+  // INFO: 0 to 3 follow-ups, so a count filter has something to split
+  followUps: Array.from({ length: index % 4 }, (_, row) => ({
+    outcome: OUTCOMES[(index + row) % OUTCOMES.length],
+    note: `Call ${row + 1}`,
+  })),
+}));
+
+const extras = { references, listObjects: true };
+
+const devSettings: DevSettings = {
+  server: "mongoServer",
+  dbEndpoint: STORY_API_ENDPOINT,
+  imageEndpoint: "",
+  uploadEndpoint: "",
+  dbAPIToken: "",
+  dbUserToken: "",
+  schemaEndpoint: "",
+  bucketName: "",
+  organisationMembers: [],
+};
+
+export const ReferencedRecord = () => {
+  const mount = useStoryBackend({
+    collections: {
+      [LEAD_COLLECTION]: leads,
+      [REFERRAL_COLLECTION]: referrals,
+    },
+  });
+  const [filters, setFilters] = useState<FlexFilterData[]>([
+    { id: "init", columnId: "", operator: "=", value: undefined },
+  ]);
+  const query = renderFlexFilterConditions(filters, referralSchema, extras);
+
+  if (!mount) return <Loading />;
+
+  return (
+    <div className="flex flex-col space-y-12">
+      <StorySection
+        title="Referrals list filtered on the lead and the follow-ups"
+        description="Open the filter and pick a Lead › field, e.g. Lead › Status is Won, or Follow-ups › Count / Outcome."
+      >
+        <DataTemplateWrapper
+          title="Referrals"
+          type="list"
+          collectionId={REFERRAL_COLLECTION}
+          schema={referralSchema}
+          workspace={storyWorkspace()}
+          limit={20}
+          organise={{ breadcrumbType: "hidden" }}
+          bareSettings={{
+            bareNewDTW: true,
+            bareFlexFilters: true,
+            bareFlexFilterReferences: references,
+            bareFlexFilterListObjects: true,
+          }}
+        />
+      </StorySection>
+
+      <StorySection
+        title="Standalone filter (notification audience)"
+        description="The same extras on the bare FlexFilter, with the query it builds."
+      >
+        <div className="flex flex-col">
+          <div className="max-w-[700px]">
+            <FlexFilter
+              structure={referralSchema}
+              extras={extras}
+              filters={filters}
+              onChange={setFilters}
+              devSettings={devSettings}
+              dbModule={axios}
+              variant="bare"
+              lib={{ Transition }}
+            />
+          </div>
+          <div className="mt-4 p-4 bg-gray-50 rounded-lg border">
+            <p className="text-sm font-semibold mb-2">
+              Generated Query Conditions ({query.length})
+            </p>
+            <pre className="text-xs whitespace-pre-wrap">
+              {JSON.stringify(query, null, 2)}
+            </pre>
+          </div>
+        </div>
+      </StorySection>
+    </div>
+  );
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blixify-ui-web-mcp",
-  "version": "0.1.60",
+  "version": "0.1.62",
   "license": "MIT",
   "main": "lib/mcp/server.js",
   "bin": {