blixify-ui-web-mcp 0.1.19 → 0.1.21

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

@@ -0,0 +1,197 @@
+// INFO: the drive view over an in-memory collection. The story mocks its own
+// API, so it opens without a server and the e2e spec drives it as it is.
+
+import React, { useEffect, useRef, useState } from "react";
+import MockAdapter from "axios-mock-adapter";
+import axios from "axios";
+import { DataTemplateWrapper } from "../dataWrapper";
+import { DataStructure } from "./model";
+import { ExtendedTabs } from "./spaceModel";
+
+const meta = {
+  title: "Data/Data Template/Drive",
+  decorators: [
+    (Story: () => React.ReactElement) => (
+      <div className="bg-gray-50 min-h-screen p-4">
+        <Story />
+      </div>
+    ),
+  ],
+};
+export default meta;
+
+const DRIVE_ENDPOINT = "http://localhost:3000/api/data";
+const DRIVE_UPLOAD = "http://localhost:3000/api/asset";
+const DRIVE_COLLECTION = "demo-drive";
+
+const DriveSchema: DataStructure[] = [
+  { id: "name", name: "Name", type: "string" },
+  { id: "kind", name: "Kind", type: "list", listSelection: ["folder", "file"] },
+  { id: "parentId", name: "Folder", type: "string" },
+  { id: "file", name: "File", type: "multipleFile" },
+  { id: "size", name: "Size", type: "number" },
+];
+
+const DriveTabs: ExtendedTabs[] = [
+  {
+    name: "Drive",
+    type: "list",
+    viewType: "drive",
+    defaultTab: true,
+    driveSettings: {
+      nameColumnId: "name",
+      kindColumnId: "kind",
+      parentColumnId: "parentId",
+      fileColumnId: "file",
+      sizeColumnId: "size",
+    },
+  },
+];
+
+const handleBuildDriveStore = () => [
+  { _id: "f-contracts", name: "Contracts", kind: "folder", parentId: "" },
+  { _id: "f-invoices", name: "Invoices", kind: "folder", parentId: "" },
+  { _id: "f-2025", name: "2025", kind: "folder", parentId: "f-invoices" },
+  {
+    _id: "d-handbook",
+    name: "Team handbook.pdf",
+    kind: "file",
+    parentId: "",
+    size: 482000,
+    file: [{ token: "demo", fileName: "demo-handbook.pdf" }],
+  },
+  {
+    _id: "d-inv-01",
+    name: "Invoice 01.pdf",
+    kind: "file",
+    parentId: "f-2025",
+    size: 91000,
+    file: [{ token: "demo", fileName: "demo-inv-01.pdf" }],
+  },
+  {
+    _id: "d-nda",
+    name: "Supplier NDA.docx",
+    kind: "file",
+    parentId: "f-contracts",
+    size: 34000,
+    file: [{ token: "demo", fileName: "demo-nda.docx" }],
+  },
+];
+
+const handleParseBody = (config: any) => {
+  try {
+    return JSON.parse(config?.data ?? "{}");
+  } catch (err) {
+    return {};
+  }
+};
+
+// INFO: enough of the query language for a drive — equality, `in` with null
+// matching a missing field the way Mongo does, and a name search
+const handleMatchQuery = (row: any, query: any[]) =>
+  query.every((eachQuery) => {
+    const value = row[eachQuery.queryId];
+    if (eachQuery.type === "=") return value === eachQuery.value;
+    if (eachQuery.type === "in")
+      return (eachQuery.value ?? []).some((eachValue: any) =>
+        eachValue === null
+          ? value === undefined || value === null
+          : value === eachValue,
+      );
+    if (eachQuery.type === "search")
+      return String(row.name ?? "")
+        .toLowerCase()
+        .includes(String(eachQuery.value ?? "").toLowerCase());
+    return true;
+  });
+
+export const Drive = () => {
+  const [folderId, setFolderId] = useState("");
+  const [mounted, setMounted] = useState(false);
+  const storeRef = useRef<any[]>(handleBuildDriveStore());
+
+  useEffect(() => {
+    const store = storeRef.current;
+    const mock = new MockAdapter(axios, {
+      onNoMatch: "passthrough",
+      delayResponse: 120,
+    });
+    const base = `${DRIVE_ENDPOINT}/${DRIVE_COLLECTION}`;
+
+    mock.onPost(`${base}/list`).reply((config) => {
+      const body = handleParseBody(config);
+      const rows = store.filter((eachRow) =>
+        handleMatchQuery(eachRow, body.query ?? []),
+      );
+      return [200, { data: rows, count: rows.length }];
+    });
+    mock.onPost(`${base}/get`).reply((config) => {
+      const body = handleParseBody(config);
+      return [200, { data: store.find((row) => row._id === body.id) ?? null }];
+    });
+    mock.onPost(`${base}/create`).reply((config) => {
+      store.push(handleParseBody(config).data);
+      return [200, { success: true }];
+    });
+    mock.onPost(`${base}/update`).reply((config) => {
+      const body = handleParseBody(config);
+      const row = store.find((eachRow) => eachRow._id === body.id);
+      if (row) Object.assign(row, body.data);
+      return [200, { success: true }];
+    });
+    mock.onPost(`${base}/batchDelete`).reply((config) => {
+      const ids: string[] = handleParseBody(config).id ?? [];
+      for (let index = store.length - 1; index >= 0; index -= 1)
+        if (ids.includes(store[index]._id)) store.splice(index, 1);
+      return [200, { success: true }];
+    });
+    mock.onPost(`${DRIVE_UPLOAD}/upload`).reply(200, { data: "demo-token" });
+    mock
+      .onPost(`${DRIVE_UPLOAD}/batchDeleteDirectory`)
+      .reply(200, { success: true });
+
+    setMounted(true);
+    return () => mock.restore();
+  }, []);
+
+  if (!mounted) return null;
+
+  return (
+    <div className="w-full">
+      <div className="font-semibold mb-1 text-gray-900">Drive</div>
+      <div className="text-sm font-light mb-4 text-gray-500">
+        A folder browser over a collection where every row is a file or a
+        folder. Open folders, use the path to go back, create, upload, rename,
+        move and delete. Deleting a folder takes everything inside it.
+      </div>
+      <DataTemplateWrapper
+        title="Documents"
+        type="list"
+        collectionId={DRIVE_COLLECTION}
+        schema={DriveSchema}
+        workspace={{
+          apiEndpointType: "mongoDB",
+          apiEndpoint: DRIVE_ENDPOINT,
+          apiEndpointToken: "",
+          apiUserToken: "",
+          assetEndpoint:
+            "https://firebasestorage.googleapis.com/v0/b/demo-bucket.firebasestorage.app/o/",
+          assetUploadEndpoint: DRIVE_UPLOAD,
+        }}
+        edit={{
+          allEditable: true,
+          listEditable: true,
+          disabledUpdate: false,
+          deleteBtn: true,
+        }}
+        bareSettings={{ bareNewDTW: true, bareCompactMode: true }}
+        organise={{
+          extendedTabs: DriveTabs,
+          folderId,
+          onChangeFolder: setFolderId,
+        }}
+        handleNavigate={() => {}}
+      />
+    </div>
+  );
+};

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

@@ -14,7 +14,7 @@ For most custom integrations, **`DataTemplateWrapper` is the recommended startin
 
 These `DataTemplate` props are handled internally and cannot be passed:
 
-- `devSettings` — replaced by `workspace`
+- `devSettings` — mostly replaced by `workspace`, but see the override below
 - `lib.axios`, `lib.Menu`, `lib.Transition`, `lib.papaParser` — always bundled
 - `model` — replaced by `schema`
 - `onComplete` — replaced by `handleComplete`
@@ -25,6 +25,34 @@ These `DataTemplate` props are handled internally and cannot be passed:
 
 You can still pass `organise` for everything else (`breadcrumbType`, `tabAlign`, `splitView`, `exportSettings`, etc.).
 
+### `devSettings` override
+
+`workspace` is a `WorkspaceDevSettings` — deliberately narrower than
+`DevSettings`, because it maps to what a workspace record actually stores. Some
+app-level values have no place on a workspace and so cannot travel that way:
+
+- `schemaEndpoint` / `schemaEndpointToken` — schema editing
+- `roleOptions` — role pickers in forms
+- `currentUser` — activity log attribution
+
+Pass those as `devSettings`. It is **merged last**, so anything you set wins over
+the value derived from `workspace`, and anything you omit keeps the derived one:
+
+```tsx
+<DataTemplateWrapper
+  workspace={workspaceSettings}
+  devSettings={{
+    schemaEndpoint: getSchemaUrl,
+    schemaEndpointToken: securityToken,
+    roleOptions: renderRoleOptions(),
+    currentUser: { userEmail, userName },
+  }}
+/>
+```
+
+This is an override for what `workspace` cannot express, not a replacement for
+it — the endpoints still come from `workspace`.
+
 ### Props forwarded straight through
 
 The wrapper names every prop it hands to `DataTemplate` rather than spreading, so
@@ -163,6 +191,11 @@ When `edit` is not passed, the wrapper defaults to:
 
 Pass your own `edit` object to override any of these.
 
+> `deleteBtn` is independent of `allEditable`. `{ allEditable: false, deleteBtn: true }`
+> renders Delete in the read and update action bars — grant it per role rather than
+> unconditionally. See DataTemplate's Write permission matrix for the full rules,
+> including which controls the imperative API deliberately does not gate.
+
 ---
 
 **7. Apply a pre-filter (optional)**
@@ -181,6 +214,51 @@ bareSettings={{
 
 Call `dataRef.current?.handleRefresh()` after changing the filter to re-fetch.
 
+> `bareListFilterQuery` is baked into every query and **cannot be cleared by the user**. When you want programmatic filters that the user can still edit or remove, use flex filters instead — see Flex Filters below.
+
+**7b. Flex filters (optional)**
+
+Flex filters are the Monday.com-style filter rows shown in the filter bar. Enable them with `bareSettings.bareFlexFilters`, then apply or clear them programmatically via the ref. Unlike `bareListFilterQuery`, filters applied this way land as normal flex filter rows the user can edit or clear themselves.
+
+```tsx
+bareSettings={{ bareFlexFilters: true }}
+
+// Apply — merged by columnId: an incoming filter REPLACES any existing row on
+// the same column, so applying status="Closed" over an existing status="Open"
+// swaps it rather than producing a contradictory AND (which returns zero rows).
+// Filters on other columns are preserved.
+dataRef.current?.handleApplyFlexFilters([
+  { id: "card-status", columnId: "status", operator: "=", value: "Closed" },
+]);
+
+// Clear specific columns (others preserved)
+dataRef.current?.handleClearFlexFilters(["status"]);
+
+// Clear all flex filters
+dataRef.current?.handleClearFlexFilters();
+```
+
+A `FlexFilterData` row is `{ id: string; columnId: string; operator: FlexFilterOperator; value: any }`. Import the type from `blixify-ui-web/data/flexFilter/model`.
+
+**Observing live filter state**
+
+To keep external UI (e.g. stat cards) in sync with what's actually applied, pass `bareOnFlexFiltersChange`. It fires whenever the applied filters change — from user edits in the panel or your own apply/clear calls — using the debounced state so it emits on committed changes, not every keystroke.
+
+```tsx
+const [liveFilters, setLiveFilters] = useState<FlexFilterData[]>([]);
+
+bareSettings={{
+  bareFlexFilters: true,
+  bareOnFlexFiltersChange: setLiveFilters,
+}}
+
+// Derive "is this filter applied" from the real state rather than click history,
+// so a card de-highlights on its own if the user edits or clears that row.
+const isStatusClosed = liveFilters.some(
+  (f) => f.columnId === "status" && f.operator === "=" && String(f.value) === "Closed",
+);
+```
+
 **8. newTabUrl (Optional)**
 
 Enables right-click → "Open in new tab" on list rows. The component builds the link as `default + recordId + addons`.
@@ -447,14 +525,19 @@ bareSettings={{
     <MyCustomDateRangePicker key="range" onChange={setRange} />,
   ],
 
-  // MongoDB aggregation pipeline stages appended to list queries
+  // MongoDB aggregation pipeline stages appended to list queries.
+  // Each result lands on the row as `<spaceReferenceAs>_<field>` (or
+  // `<spaceReferenceAs>_count`); match a schema column `id` to that key to show it.
   bareListPipeline: [
     {
       spaceReferenceId: "users",
       spaceReferenceAs: "assigneeData",
       condition: [{ type: "=", fromColumnId: "assigneeId", toColumnId: "_id" }],
-      referenceSpaceLabel: ["name", "email"],
+      referenceSpaceLabel: ["name", "email"], // → assigneeData_name, assigneeData_email
       referenceFirstItem: true,
+      // Optional, opt-in — existing pipelines are unaffected when omitted:
+      referenceQuery: [{ type: "=", queryId: "active", value: true }], // extra filter on the joined collection, on top of `condition`
+      referenceShowCount: true, // emits assigneeData_count = size of the joined set after condition + referenceQuery
     },
   ],
 }}
@@ -469,11 +552,12 @@ Use these to inject extra content into the read view, intercept data on load, or
 ```tsx
 bareSettings={{
   // Inject a custom component into the read view
-  // By default it renders below the field list
-  bareReadComponent: (data) => (
+  // By default it renders below the field list.
+  // `data` is display data (labels + elements); `rawData` is the untouched DB doc.
+  bareReadComponent: (data, rawData) => (
     <div className="mt-4 p-4 bg-blue-50 rounded-lg">
-      <p className="text-sm font-medium">Custom summary for {data.name}</p>
-      <p className="text-xs text-gray-500">Last updated: {data.updatedAt}</p>
+      <p className="text-sm font-medium">Custom summary for {rawData.name}</p>
+      <p className="text-xs text-gray-500">Last updated: {rawData.updatedAt}</p>
     </div>
   ),
 
@@ -489,8 +573,9 @@ bareSettings={{
     return null; // return null to use the default renderer
   },
 
-  // Called when read view data loads — use to sync external state
-  bareReadHandleData: (data) => setPageTitle(data.name),
+  // Called when read view data loads — use to sync external state.
+  // `data` is display data (labels + elements); `rawData` is the untouched DB doc.
+  bareReadHandleData: (data, rawData) => setPageTitle(rawData.name),
 
   // Control whether clicking a reference field opens its detail view
   bareReadReferenceView: (dataId, collectionId, attributeId) => {
@@ -618,7 +703,7 @@ Set `bareOffline: true` in `bareSettings` to enable offline data caching via Ind
 
 Fields of type `reference` and `listReference` that pull their options from the server will be empty when offline. You must fetch those options while online and store them in IndexedDB yourself so the form stays usable offline.
 
-Use the same database name the component uses and store each option set under a key with the format `[collectionId]-ref` (e.g. meraque-cycles-ref). Each value must be an array of `Option` objects — `{ key, label, secondaryLabel?, color?, image?, icon? }` — where `key` is the record's `_id`.
+Use the same database name the component uses and store each option set under a key with the format `[collectionId]-ref` (e.g. work-cycles-ref). Each value must be an array of `Option` objects — `{ key, label, secondaryLabel?, color?, image?, icon? }` — where `key` is the record's `_id`.
 
 ```tsx
 // Call this once on app load (or when the user logs in) while online
@@ -1019,16 +1104,18 @@ needs to know about the other.
 
 ## Ref Methods
 
-| Method                             | Description                                                       |
-| ---------------------------------- | ----------------------------------------------------------------- |
-| `handleRefresh()`                  | Re-fetches the current list data, resetting pagination to page 1  |
-| `handleRefreshCurrentPage()`       | Re-fetches in place, keeping page index, cursor, and filters      |
-| `handleFormSubmit()`               | Programmatically submits the form                                 |
-| `handleFormCheck()`                | Validates the form without submitting                             |
-| `handleUpdateSelectedData(fields)` | Prefills form fields. `fields` is `{ key: string; value: any }[]` |
-| `handleDeleteModal()`              | Opens the delete confirmation modal                               |
-| `handleExportReadPDF()`            | Triggers PDF export of the current read view                      |
-| `handleUploadOfflineModal()`       | Opens the offline data upload modal                               |
+| Method                               | Description                                                                                                                                               |
+| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `handleRefresh()`                    | Re-fetches the current list data, resetting pagination to page 1                                                                                          |
+| `handleRefreshCurrentPage()`         | Re-fetches in place, keeping page index, cursor, and filters                                                                                              |
+| `handleFormSubmit()`                 | Programmatically submits the form                                                                                                                         |
+| `handleFormCheck()`                  | Validates the form without submitting                                                                                                                     |
+| `handleUpdateSelectedData(fields)`   | Prefills form fields. `fields` is `{ key: string; value: any }[]`                                                                                         |
+| `handleDeleteModal()`                | Opens the delete confirmation modal                                                                                                                       |
+| `handleExportReadPDF()`              | Triggers PDF export of the current read view                                                                                                              |
+| `handleUploadOfflineModal()`         | Opens the offline data upload modal                                                                                                                       |
+| `handleApplyFlexFilters(filters)`    | Applies flex filters to the list, merged by `columnId`. `filters` is `FlexFilterData[]`. Requires `bareSettings.bareFlexFilters` — see Flex Filters below |
+| `handleClearFlexFilters(columnIds?)` | Clears flex filters by `columnId` (others preserved), or all when called with no args. Requires `bareSettings.bareFlexFilters`                            |
 
 ---
 
@@ -1148,12 +1235,12 @@ A shorthand that builds the `extendedTabs` and `viewId` config for you. Only one
 
 | Name                                     | Type                                                                                  | Description                                                                                                              |
 | ---------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `bareReadComponent`                      | `(data: any) => ReactElement`                                                         | Custom component rendered in read view                                                                                   |
+| `bareReadComponent`                      | `(data: any, rawData?: any) => ReactElement`                                          | Custom component rendered in read view. `data` is display data (labels + elements); `rawData` is the untouched DB doc    |
 | `bareReadComponentPos`                   | `"top"`                                                                               | Renders `bareReadComponent` above the default read content                                                               |
 | `bareReadComponentHide`                  | `boolean`                                                                             | Hides the default read content                                                                                           |
 | `bareReadDescription`                    | `(key, value) => any`                                                                 | Custom renderer for read view field values                                                                               |
 | `bareReadReferenceView`                  | `(dataId, collectionId, attributeId) => boolean \| void`                              | Controls whether a reference field opens a view                                                                          |
-| `bareReadHandleData`                     | `(data: any) => void`                                                                 | Called when read view data is loaded                                                                                     |
+| `bareReadHandleData`                     | `(data: any, rawData?: any) => void`                                                  | Called when read view data is loaded. `data` is display data (labels + elements); `rawData` is the untouched DB doc      |
 | `bareReadListTabs`                       | `boolean`                                                                             | Shows list-style tabs in read view                                                                                       |
 | `bareListComponent`                      | `(data, prettierData, loading, pageIndex) => ReactElement`                            | Fully replaces the list UI                                                                                               |
 | `bareListActionBtns`                     | `(data: any) => ReactElement[]`                                                       | Extra icon buttons on each list row                                                                                      |