blixify-ui-web-mcp 0.1.61 → 0.1.62

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.61",
+  "version": "0.1.62",
   "license": "MIT",
   "main": "lib/mcp/server.js",
   "bin": {