blixify-ui-web-mcp 0.1.1

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

@@ -0,0 +1,1077 @@
+# Data Wrapper
+
+<!-- STORY -->
+
+<hr>
+
+`DataTemplateWrapper` is a simplified wrapper around `DataTemplate` designed for embedding data views inside existing dashboards or app pages — without needing to manage routing, backend config, or library wiring yourself.
+
+For most custom integrations, **`DataTemplateWrapper` is the recommended starting point**. You define the schema directly in code, pass a `workspace` config instead of building `devSettings` manually, and the wrapper handles axios, headlessUI, and papaparse internally. Use `DataTemplate` directly only when you have a Space object from the Blixify backend and want to drive the schema and config from the database.
+
+---
+
+### Props from Data Template that do NOT apply to DataTemplateWrapper
+
+These `DataTemplate` props are handled internally and cannot be passed:
+
+- `devSettings` — replaced by `workspace`
+- `lib.axios`, `lib.Menu`, `lib.Transition`, `lib.papaParser` — always bundled
+- `localURLEndpoint` — always `""`
+- `model` — replaced by `schema`
+- `onComplete` — replaced by `handleComplete`
+- `organise.handleNavigate` — replaced by top-level `handleNavigate`
+- `organise.additionalQuery` — replaced by top-level `additionalQuery`
+- `organise.sort` — replaced by top-level `sort`
+- `organise.extendedTabs` / `organise.viewId` — replaced by `viewSettings`
+
+You can still pass `organise` for everything else (`breadcrumbType`, `tabAlign`, `splitView`, `exportSettings`, etc.).
+
+---
+
+## Import
+
+```js
+import { DataTemplateWrapper } from "blixify-ui-web/data/dataWrapper";
+```
+
+---
+
+## Step-by-Step Setup
+
+**1. Create a ref and navigation state**
+
+The wrapper is a class component, so use `useRef` to access its imperative methods. Store `type` and `id` in state — these drive which view is rendered.
+
+```tsx
+const dataRef = useRef<any>(null);
+const [viewType, setViewType] = useState<"list" | "read" | "update">("list");
+const [selectedId, setSelectedId] = useState<string | undefined>(undefined);
+```
+
+**2. Define your schema**
+
+Same shape as `DataTemplate`'s `model`. Define the columns you want to display and edit.
+
+```tsx
+const schema: DataStructure[] = [
+  { id: "name", name: "Name", type: "string" },
+  {
+    id: "status",
+    name: "Status",
+    type: "list",
+    listSelection: ["active", "inactive"],
+  },
+  { id: "date", name: "Date", type: "date" },
+];
+```
+
+**3. Wire navigation**
+
+The wrapper calls `handleNavigate` whenever the user clicks a row, a breadcrumb, or a create button. Update your state here.
+
+```tsx
+const handleNavigate = (type: string, id?: string) => {
+  setViewType(type as any);
+  if (id !== undefined) setSelectedId(id);
+};
+```
+
+You can also use `handleNavigate` to redirect to a different page entirely instead of updating local state — useful when the read or update view lives on a separate route:
+
+```tsx
+const handleNavigate = (type: string, id?: string) => {
+  if (type === "read" && id) {
+    router.push(`/records/${id}`); // React Router / Next.js
+    // or: window.location.href = `/records/${id}`;
+  } else if (type === "update" && id) {
+    router.push(`/records/${id}/edit`);
+  } else {
+    setViewType("list");
+    setSelectedId(undefined);
+  }
+};
+```
+
+**4. Configure the workspace**
+
+Pass your backend connection details via `workspace`. No need to build `devSettings` manually.
+
+```tsx
+const workspace = {
+  apiEndpointType: "mongoDB",
+  apiEndpoint: "https://api.example.com/api/mongoData",
+  apiEndpointToken: "your-token",
+  apiUserToken: "",
+  assetEndpoint: "https://storage.example.com/o/",
+  assetUploadEndpoint: "https://api.example.com/api/asset",
+};
+```
+
+**5. Render the component**
+
+```tsx
+<DataTemplateWrapper
+  ref={dataRef}
+  title="Checklists"
+  description="O&M service checklists"
+  type={viewType}
+  id={selectedId}
+  collectionId="checklists"
+  schema={schema}
+  workspace={workspace}
+  handleNavigate={handleNavigate}
+/>
+```
+
+**6. Override edit permissions (optional)**
+
+The wrapper defaults to read-only (`disabledUpdate: true, deleteBtn: false`). Pass `edit` to enable create/update/delete.
+
+```tsx
+edit={{ allEditable: true, deleteBtn: true }}
+```
+
+When `edit` is not passed, the wrapper defaults to:
+
+```ts
+{
+  allEditable: true,
+  listEditable: false,
+  disabledUpdate: true,
+  disableBatchUpdate: true,
+  deleteBtn: false,
+}
+```
+
+Pass your own `edit` object to override any of these.
+
+---
+
+**7. Apply a pre-filter (optional)**
+
+Use `bareSettings.bareListFilterQuery` to always filter the list by a condition — useful when embedding the component inside a page that has its own filter state.
+
+```tsx
+const [statusFilter, setStatusFilter] = useState("active");
+
+bareSettings={{
+  bareListFilterQuery: statusFilter !== "all"
+    ? [{ queryId: "status", type: "=", value: statusFilter }]
+    : [],
+}}
+```
+
+Call `dataRef.current?.handleRefresh()` after changing the filter to re-fetch.
+
+**8. newTabUrl (Optional)**
+
+Enables right-click → "Open in new tab" on list rows. The component builds the link as `default + recordId + addons`.
+
+```tsx
+newTabUrl={{
+  default: "https://dashboard.example.com/records/", // base URL — record ID is appended here
+  addons: "?view=read",                              // optional suffix appended after the record ID
+}}
+// resulting link: https://dashboard.example.com/records/<id>?view=read
+```
+
+Both fields are optional — omit `addons` if you don't need a suffix.
+
+**9. Use a non-table view (optional)**
+
+Pass `viewSettings` to activate an alternate view instead of the default table.
+
+```tsx
+// Grid view — renders records as image cards
+viewSettings={{
+  gridImage: "coverImage",  // column ID of an image field
+  gridScroll: true, // gridScroll enables infinite scroll;
+  gridContain: false, //gridContain uses object-contain instead of object-cover
+}}
+
+// List view — renders records as a vertical image list
+viewSettings={{
+  listImage: "coverImage",  // column ID of an image field
+}}
+
+// Calendar view — renders records as calendar events
+viewSettings={{
+  calendarSettings: {
+    title: "name",        // column ID for event title
+    startDate: "startAt", // column ID for start date
+    endDate: "endAt",     // column ID for end date (optional)
+    groupId: "category",  // column ID to colour-group events (optional)
+  },
+}}
+
+// Custom calendar view — pass your own FullCalendar plugin via customPlugin
+// When customPlugin is set, the default view switches to "timeGridWeek"
+// unless you override it with defaultView
+viewSettings={{
+  calendarSettings: {
+    title: "name",
+    startDate: "startAt",
+    endDate: "endAt",
+    customPlugin: myFullCalendarPlugin, // any FullCalendar-compatible plugin
+    defaultView: "timeGridWeek",        // override the initial view (optional)
+    headerToolbar: {                    // override the toolbar buttons (optional)
+      left: "prev,next today",
+      center: "title",
+      right: "dayGridMonth,timeGridWeek,timeGridDay",
+    },
+    footerToolbar: { right: "prev,next" }, // optional footer toolbar
+    customButtons: {                       // define custom toolbar buttons (optional)
+      myBtn: { text: "Sync", click: () => handleSync() },
+    },
+    customView: { view: "week", duration: 2 }, // multi-week span (optional)
+    handleCalendarResize: (calendarRef, isMobileWidth) => {  // respond to resize (optional)
+      if (isMobileWidth) calendarRef.current?.getApi().changeView("timeGridDay");
+    },
+  },
+}}
+
+// Feeds view — renders records as a timeline/activity feed
+viewSettings={{
+  feedsSettings: {
+    title: "name",    // column ID for feed item title
+    content: "notes", // column ID for feed item body
+    desc: "createdAt", // column ID for the right-corner element
+    icon: "HeartIcon", // heroicon name (optional)
+    iconClass: "text-red-500", // tailwind class for the icon (optional)
+  },
+}}
+
+// Kanban view — renders records as a drag-and-drop board
+viewSettings={{
+  kanbanSettings: {
+    title: "name", // column ID for card title
+    useColumnName: true,
+    groupCluster: [
+      { "To Do":       ["todo"] },
+      { "In Progress": ["in_progress"] },
+      { "Review":      ["review"] },
+      { "Done":        ["done"] },
+    ],
+  },
+}}
+```
+
+---
+
+### Form section grouping
+
+Fields in the update/create form can be grouped into named sections using `groupId` on each `DataStructure` entry. Fields without a `groupId` are placed in a default section at the bottom.
+
+```tsx
+schema={[
+  { id: "name",     name: "Name",     type: "string", groupId: "Basic Info" },
+  { id: "email",    name: "Email",    type: "email",  groupId: "Basic Info" },
+  { id: "region",   name: "Region",   type: "string", groupId: "Location" },
+  { id: "address",  name: "Address",  type: "address", groupId: "Location" },
+  { id: "notes",    name: "Notes",    type: "textArea" }, // no groupId → default section
+]}
+```
+
+By default, groups render as labelled sections separated by a divider. To make groups collapsible, pass `groupIdCollapsible` via `organise`:
+
+```tsx
+organise={{
+  groupIdCollapsible: {
+    "Basic Info": false, // false = expanded by default
+    "Location":   true,  // true  = collapsed by default
+  },
+}}
+```
+
+When `groupIdCollapsible` is set, each group renders as a `Collapse` panel with a bold title. Groups are sorted alphabetically — fields without a `groupId` always render last.
+
+You can also split the form into tabs using `tabId` on each field. Fields with the same `tabId` are grouped under that tab. Use `organise.tabAlign` to control the tab style (`"top"`, `"left"`, or `"stepper"`).
+
+```tsx
+schema={[
+  { id: "name",    name: "Name",    type: "string", tabId: "Details" },
+  { id: "status",  name: "Status",  type: "list",   tabId: "Details" },
+  { id: "notes",   name: "Notes",   type: "textArea", tabId: "Notes" },
+  { id: "signoff", name: "Sign Off", type: "signature", tabId: "Sign Off" },
+]}
+
+organise={{ tabAlign: "stepper" }} // renders tabs as a step-by-step wizard
+```
+
+`tabId` and `groupId` can be combined — fields are first split by tab, then grouped within each tab.
+
+---
+
+## Usage
+
+```tsx
+<DataTemplateWrapper
+  ref={dataRef}
+  title="Maintenance Checklists"
+  description="O&M service checklists"
+  type={viewType} // "list" | "read" | "update"
+  id={selectedId}
+  collectionId="checklists"
+  schema={checklistSchema}
+  workspace={{
+    apiEndpointType: "mongoDB",
+    apiEndpoint: "https://api.example.com/api/mongoData",
+    apiEndpointToken: "your-token",
+    apiUserToken: "",
+    assetEndpoint: "https://storage.example.com/o/",
+    assetUploadEndpoint: "https://api.example.com/api/asset",
+  }}
+  edit={{ allEditable: true, deleteBtn: true }}
+  organise={{ breadcrumbType: "hidden", tabAlign: "left" }}
+  handleNavigate={(type, id) => {
+    setViewType(type);
+    setSelectedId(id);
+  }}
+  handleComplete={(id) => console.log("saved", id)}
+  limit={30}
+/>
+```
+
+---
+
+### Grid view customisation
+
+Use these together with `viewSettings={{ gridImage: "..." }}` to control how grid cards look and behave.
+
+```tsx
+bareSettings={{
+  // Fully replace the default grid card with your own component
+  bareListGridComponent: (data) => (
+    <div className="rounded-lg overflow-hidden border border-gray-200">
+      <img src={data.coverImage} className="w-full h-40 object-cover" />
+      <div className="p-3">
+        <p className="font-medium text-sm">{data.name}</p>
+        <p className="text-xs text-gray-500">{data.location}</p>
+      </div>
+    </div>
+  ),
+
+  // Tailwind col-span class controlling how many columns each card takes
+  bareListGridColClassName: "col-span-1",
+
+  // Tag badges shown on the default grid card
+  bareListGridTags: (data) => [data.category, data.status],
+
+  // Ribbon text overlaid on the card image (e.g. "New", "Sold")
+  bareListGridRibbonText: (data) => data.status === "new" ? "New" : "",
+
+  // Fallback shown when the image column is empty
+  bareListGridFallbackImg: () => "/placeholder.png",
+}}
+```
+
+---
+
+### List view customisation
+
+Use these to control the table/list rows — add row-level action buttons, bulk actions, intercept data, or apply permanent filters.
+
+```tsx
+bareSettings={{
+  // Icon buttons appended to each row
+  bareListActionBtns: (data) => [
+    <button key="send" onClick={(e) => { e.stopPropagation(); sendItem(data._id); }}>
+      <PaperAirplaneIcon className="w-4 h-4 text-primary-500" />
+    </button>,
+  ],
+
+  // Bulk-action buttons shown when rows are selected
+  bareListMultipleSelectAddtionalActions: [
+    {
+      text: "Export Selected",
+      onClick: (ids, selectAll, query) => exportItems(ids),
+    },
+  ],
+
+  // Fully replace the list UI with your own renderer
+  bareListComponent: (data, prettierData, loading, pageIndex) => (
+    <ul className="divide-y">
+      {data.map((item) => (
+        <li key={item._id} className="py-3 flex justify-between">
+          <span>{item.name}</span>
+          <span className="text-sm text-gray-500">{item.status}</span>
+        </li>
+      ))}
+    </ul>
+  ),
+
+  // Always-on filter applied to every list fetch (e.g. scope to current user)
+  bareListFilterQuery: [{ queryId: "assigneeId", type: "=", value: currentUserId }],
+
+  // Custom renderer for individual field values in the list
+  bareListDescription: (key, value) => {
+    if (key === "status") return <StatusBadge value={value} />;
+    return null; // return null to use the default renderer
+  },
+
+  // Called whenever list data loads — use to sync external state
+  bareListHandleData: (data, prettierData) => setRowCount(data.length),
+
+  // Called when row selection changes
+  bareListHandleSelection: (selectAll, selectedIds) => setSelected(selectedIds),
+
+  // Called whenever any filter changes
+  bareListHandleFilter: (search, select, date, reference) => console.log(search),
+
+  // Called with the full filter state on every change
+  bareListFilterSelected: (searchParams, selection, reference, refDate) => {
+    syncFiltersToURL(searchParams);
+  },
+
+  // Extra filter components rendered in the filter bar
+  bareListFilterAddComponent: [
+    <MyCustomDateRangePicker key="range" onChange={setRange} />,
+  ],
+
+  // MongoDB aggregation pipeline stages appended to list queries
+  bareListPipeline: [
+    {
+      spaceReferenceId: "users",
+      spaceReferenceAs: "assigneeData",
+      condition: [{ type: "=", fromColumnId: "assigneeId", toColumnId: "_id" }],
+      referenceSpaceLabel: ["name", "email"],
+      referenceFirstItem: true,
+    },
+  ],
+}}
+```
+
+---
+
+### Read view customisation
+
+Use these to inject extra content into the read view, intercept data on load, or override how individual field values are displayed.
+
+```tsx
+bareSettings={{
+  // Inject a custom component into the read view
+  // By default it renders below the field list
+  bareReadComponent: (data) => (
+    <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>
+    </div>
+  ),
+
+  // Render the custom component above the field list instead of below
+  bareReadComponentPos: "top",
+
+  // Hide the default field list entirely — show only bareReadComponent
+  bareReadComponentHide: true,
+
+  // Custom renderer for individual field values in the read view
+  bareReadDescription: (key, value) => {
+    if (key === "status") return <StatusBadge value={value} />;
+    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),
+
+  // Control whether clicking a reference field opens its detail view
+  bareReadReferenceView: (dataId, collectionId, attributeId) => {
+    // return false to disable the view button for this reference
+    return collectionId !== "restricted-collection";
+  },
+
+  // Show list-style tabs in read view (useful without a schemaEndpoint)
+  bareReadListTabs: true,
+}}
+```
+
+---
+
+### Update / form customisation
+
+Use these to control the create/edit form layout, prefill values, inject custom components, intercept saves, or replace individual fields.
+
+```tsx
+bareSettings={{
+  // Prefill form fields based on existing record data
+  bareUpdatePrefill: (data) => [
+    { key: "assigneeId", value: currentUserId },
+    { key: "region",     value: data.siteRegion },
+  ],
+
+  // Inject a custom component into the form (renders below fields by default)
+  bareUpdateComponent: (data) => (
+    <div className="p-3 bg-yellow-50 rounded text-sm">
+      Note: changes will notify {data.assigneeName}
+    </div>
+  ),
+
+  // Render bareUpdateComponent above the fields instead of below
+  bareUpdateComponentAbove: true,
+
+  // Replace the default save/cancel buttons with your own
+  bareUpdateActionComponent: (data, formRef) => (
+    <div className="flex gap-2">
+      <button onClick={() => formRef?.handleFormSubmit()}>Save</button>
+      <button onClick={onCancel}>Discard</button>
+    </div>
+  ),
+
+  // Move action buttons to the bottom of the form
+  bareUpdateActionBottom: true,
+
+  // Form column layout: "one" = 2-col grid, "two"/"four" = 4-col grid
+  bareUpdateColumnType: "two",
+
+  // Mobile-optimised layout: horizontal label/input on mobile, standard on desktop
+  bareUpdateMobileView: true,
+
+  // Replace a specific field with a fully custom component
+  bareUpdateIndividualComponent: (columnId, ref, selectedData, setSelectedData) => {
+    if (columnId === "coordinates") {
+      return (
+        <MapPicker
+          value={selectedData.coordinates}
+          onChange={(val) => setSelectedData({ ...selectedData, coordinates: val })}
+        />
+      );
+    }
+    return null; // return null to use the default field component
+  },
+
+  // Called on every field change — use to react to form state
+  bareUpdateHandleData: (data, changedIds) => {
+    if (changedIds?.includes("siteId")) refetchSiteDetails(data.siteId);
+  },
+
+  // Called when the active form tab changes
+  bareUpdateTabId: (tabId) => setActiveTab(tabId),
+
+  // Called before save — return false to cancel submission
+  bareUpdateHandlePreComplete: async (data) => {
+    const ok = await validateWithServer(data);
+    if (!ok) { showError("Validation failed"); return false; }
+    return true;
+  },
+
+  // Called after save completes
+  bareUpdateHandleComplete: async (data) => {
+    await sendNotification(data._id);
+  },
+
+  // Called after all post-save operations complete
+  bareUpdateHandlePostComplete: async (data) => {
+    await refreshRelatedList(data.projectId);
+  },
+
+  // Block deletion when this record is referenced elsewhere
+  bareReferenceDel: [
+    {
+      collectionId: "work-orders",
+      collectionName: "Work Orders",
+      columnId: "siteId",
+      schema: workOrderSchema,
+    },
+  ],
+
+  // Enable offline data caching via IndexedDB
+  bareOffline: true,
+
+  // Custom CSV import/export endpoints
+  bareCSVImportEndpoint: "https://api.example.com/api/import",
+  bareCSVExportEndpoint: "https://api.example.com/api/export",
+}}
+```
+
+---
+
+## Offline Mode
+
+Set `bareOffline: true` in `bareSettings` to enable offline data caching via IndexedDB. When active, the component saves form submissions locally when there is no network connection. Once the user is back online, they click the "Submit Offline Data" button (or you trigger `dataRef.current?.handleUploadOfflineModal()` programmatically) to flush the cached records to the server.
+
+### How it works
+
+1. User fills in and submits a form while offline — the record is written to IndexedDB instead of the server.
+2. Only offline records are shown in the list (pulled from IndexedDB). The user can open them in read view and update view — all data is served from IndexedDB. These offline records are invisible when `bareOffline` is `false`.
+3. When connectivity resumes, the user clicks "Submit Offline Data" (or you call `handleUploadOfflineModal()`). The component reads the queue from IndexedDB and replays each submission against the server.
+
+### Pre-fetching reference options
+
+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`.
+
+```tsx
+// Call this once on app load (or when the user logs in) while online
+async function prefetchReferenceOptions() {
+  const db = await openDB("blixify-offline", 1, {
+    upgrade(db) {
+      if (!db.objectStoreNames.contains("references")) {
+        db.createObjectStore("references");
+      }
+    },
+  });
+
+  // Fetch raw records for every collection your form references
+  const [siteRecords, userRecords] = await Promise.all([
+    fetch("https://api.example.com/api/mongoData", {
+      method: "POST",
+      headers: { Authorization: "Bearer your-token" },
+      body: JSON.stringify({ collectionId: "sites", query: [] }),
+    }).then((r) => r.json()),
+
+    fetch("https://api.example.com/api/mongoData", {
+      method: "POST",
+      headers: { Authorization: "Bearer your-token" },
+      body: JSON.stringify({ collectionId: "users", query: [] }),
+    }).then((r) => r.json()),
+  ]);
+
+  // Shape each record into an Option and store under "[collectionId]-ref"
+  await db.put(
+    "references",
+    siteRecords.map((r) => ({ key: r._id, label: r.name })),
+    "sites-ref"
+  );
+  await db.put(
+    "references",
+    userRecords.map((r) => ({
+      key: r._id,
+      label: r.name,
+      secondaryLabel: r.email,
+    })),
+    "users-ref"
+  );
+}
+
+// Call on mount, before rendering the form
+useEffect(() => {
+  prefetchReferenceOptions();
+}, []);
+```
+
+> Use library [`idb`](https://github.com/jakearchibald/idb) (`yarn add idb`) for a promise-based IndexedDB API.
+
+### Full example
+
+```tsx
+import { openDB } from "idb";
+
+function ChecklistPage() {
+  const dataRef = useRef<any>(null);
+  const [viewType, setViewType] = useState<"list" | "read" | "update">("list");
+  const [selectedId, setSelectedId] = useState<string | undefined>(undefined);
+
+  // Pre-fetch reference options while online
+  useEffect(() => {
+    prefetchReferenceOptions();
+  }, []);
+
+  const schema: DataStructure[] = [
+    { id: "name", name: "Name", type: "string" },
+    { id: "siteId", name: "Site", type: "reference", referenceId: "sites" },
+    { id: "assignee", name: "Assignee", type: "listPerson" },
+    { id: "notes", name: "Notes", type: "textArea" },
+  ];
+
+  return (
+    <DataTemplateWrapper
+      ref={dataRef}
+      title="Checklists"
+      type={viewType}
+      id={selectedId}
+      collectionId="checklists"
+      schema={schema}
+      workspace={{
+        apiEndpointType: "mongoDB",
+        apiEndpoint: "https://api.example.com/api/mongoData",
+        apiEndpointToken: "your-token",
+        apiUserToken: "",
+        assetEndpoint: "https://storage.example.com/o/",
+        assetUploadEndpoint: "https://api.example.com/api/asset",
+      }}
+      edit={{ allEditable: true, deleteBtn: false }}
+      handleNavigate={(type, id) => {
+        setViewType(type as any);
+        if (id !== undefined) setSelectedId(id);
+      }}
+      bareSettings={{
+        bareOffline: true, // enable IndexedDB caching
+      }}
+    />
+  );
+}
+```
+
+### Triggering the upload modal programmatically
+
+If you want to prompt the user to sync as soon as connectivity is detected, listen for the `online` event and call `handleUploadOfflineModal()`:
+
+```tsx
+useEffect(() => {
+  const handleOnline = () => {
+    dataRef.current?.handleUploadOfflineModal();
+  };
+  window.addEventListener("online", handleOnline);
+  return () => window.removeEventListener("online", handleOnline);
+}, []);
+```
+
+The modal lists all queued records and lets the user confirm before uploading. Records that upload successfully are removed from IndexedDB automatically.
+
+---
+
+## Union Collections
+
+`unionCollections` is passed via `organise` and lets you merge data from multiple MongoDB collections into a single list view. Each entry defines a secondary collection to query, how to filter it, which fields to project, and an optional `source` label to identify which collection each row came from.
+
+This is only supported with `server: "mongoServer"`.
+
+### Basic example — two collections, static source label
+
+```tsx
+organise={{
+  unionCollections: [
+    {
+      collection: "work-orders",   // secondary collection to union in
+      source: "Work Order",        // static label added as a "source" field on each row
+      query: [
+        { queryId: "status", type: "=", value: "active" },
+      ],
+      projection: {
+        _id: 1,
+        name: 1,
+        status: 1,
+        assigneeId: 1,
+        createdAt: 1,
+      },
+    },
+  ],
+  sort: { sortId: "createdAt", type: "desc" },
+}}
+```
+
+The `source` field is automatically added to every row from that collection. Include `{ id: "source", name: "Source", type: "string", hideForm: true }` in your `schema` to display it as a column.
+
+---
+
+### Dynamic source label — derive the label from the row's own data
+
+When `source` is `"dynamic"`, use `sourceLogic` to compute the label using a MongoDB `$cond` expression.
+
+```tsx
+organise={{
+  unionCollections: [
+    {
+      collection: "deliveries",
+      source: "dynamic",            // compute label per row
+      sourceLogic: {
+        $cond: {
+          if:   { $eq: ["$type", "om"] },
+          then: "O&M Maintenance",
+          else: "PV Delivery",
+        },
+      },
+      query: [
+        { queryId: "type", type: "in", value: ["om", "pv"] },
+      ],
+      projection: {
+        _id: 1, name: 1, type: 1, status: 1, createdAt: 1,
+      },
+    },
+  ],
+  sort: { sortId: "createdAt", type: "desc" },
+}}
+```
+
+---
+
+### addFields — compute a virtual field for sorting across collections
+
+Use `addFields` to add a computed field (e.g. a unified sort date) that doesn't exist natively on every collection. Sort by that field so rows from different collections interleave correctly.
+
+```tsx
+organise={{
+  unionCollections: [
+    {
+      collection: "deliveries",
+      source: "Delivery",
+      query: [],
+      projection: {
+        _id: 1, name: 1, proposed_date: 1, installation_date: 1, createdAt: 1,
+      },
+      // Add a virtual "sortDate" field — pick the first non-null date
+      addFields: {
+        sortDate: {
+          $ifNull: ["$proposed_date", "$createdAt"],
+        },
+      },
+    },
+    {
+      collection: "service-tickets",
+      source: "Service Ticket",
+      query: [],
+      projection: {
+        _id: 1, name: 1, service_date: 1, createdAt: 1,
+      },
+      addFields: {
+        sortDate: {
+          $ifNull: ["$service_date", "$createdAt"],
+        },
+      },
+    },
+  ],
+  // Sort all rows by the computed field across both collections
+  sort: { sortId: "sortDate", type: "desc" },
+}}
+```
+
+---
+
+### Dynamic queries — rebuild unionCollections when filters change
+
+Because `unionCollections` is inside `organise`, you can recompute it reactively when your filter state changes. Call `dataRef.current?.handleRefresh()` after updating state.
+
+```tsx
+const [installer, setInstaller] = useState("");
+const [startDate, setStartDate] = useState("");
+const [endDate, setEndDate] = useState("");
+
+const buildOrganise = () => {
+  const dateQuery = startDate && endDate
+    ? [{ queryId: "date", type: "><", value: [new Date(startDate).toISOString(), new Date(endDate).toISOString()] }]
+    : [];
+
+  const personQuery = installer
+    ? [{ type: "search", searchIds: ["installer", "inspector"], value: installer }]
+    : [];
+
+  return {
+    unionCollections: [
+      {
+        collection: "deliveries",
+        source: "Delivery",
+        query: [...dateQuery, ...personQuery],
+        projection: { _id: 1, name: 1, status: 1, installer: 1, date: 1 },
+        addFields: { sortDate: { $ifNull: ["$date", "$createdAt"] } },
+      },
+      {
+        collection: "service-tickets",
+        source: "Service Ticket",
+        query: [...dateQuery, ...personQuery],
+        projection: { _id: 1, name: 1, status: 1, installer: 1, service_date: 1 },
+        addFields: { sortDate: { $ifNull: ["$service_date", "$createdAt"] } },
+      },
+    ],
+    sort: { sortId: "sortDate", type: "desc" as const },
+  };
+};
+
+// Re-fetch whenever filters change
+useEffect(() => {
+  dataRef.current?.handleRefresh();
+}, [installer, startDate, endDate]);
+
+<DataTemplateWrapper
+  ...
+  organise={buildOrganise()}
+/>
+```
+
+---
+
+### Schema for union views
+
+All fields that may appear across any of the unioned collections must be declared in `schema`. Mark them `optional: true` and `hideForm: true` since they are read-only display columns.
+
+```tsx
+schema={[
+  { id: "source",       name: "Source",    type: "string", hideForm: true },
+  { id: "name",         name: "Name",      type: "string", hideForm: true, optional: true },
+  { id: "status",       name: "Status",    type: "string", hideForm: true, optional: true },
+  { id: "installer",    name: "Installer", type: "string", hideForm: true, optional: true },
+  { id: "date",         name: "Date",      type: "date",   hideForm: true, optional: true },
+  { id: "service_date", name: "Svc Date",  type: "date",   hideForm: true, optional: true },
+]}
+```
+
+---
+
+## Ref Methods
+
+| Method                             | Description                                                       |
+| ---------------------------------- | ----------------------------------------------------------------- |
+| `handleRefresh()`                  | Re-fetches the current list data                                  |
+| `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                               |
+
+---
+
+## Props
+
+| Name              | Type                                    | Default   | Description                                                                              |
+| ----------------- | --------------------------------------- | --------- | ---------------------------------------------------------------------------------------- |
+| `title`           | `string \| ReactElement`                | —         | Title shown in the header                                                                |
+| `description`     | `string \| ReactElement`                | `""`      | Description shown below the title                                                        |
+| `type`            | `"list" \| "read" \| "update"`          | —         | Current view mode                                                                        |
+| `id`              | `string`                                | —         | Selected record ID. Pass `"new"` for a blank create form                                 |
+| `collectionId`    | `string`                                | —         | Database collection ID                                                                   |
+| `schema`          | `DataStructure[]`                       | —         | Column/field definitions (same shape as `DataTemplate`'s `model`)                        |
+| `workspace`       | `WorkspaceDevSettings`                  | —         | Backend connection config — see Workspace below                                          |
+| `space`           | `Space`                                 | —         | Full Space object — enables tabs, sort, and additional queries                           |
+| `edit`            | `Edit`                                  | see below | Create/update/delete permissions — see DataTemplate's Edit                               |
+| `organise`        | `Organise`                              | —         | View, sort, filter, export, and tab config — see DataTemplate's Organise                 |
+| `bareSettings`    | `BareSettings`                          | —         | Custom components and callbacks — see Bare Settings below                                |
+| `renderSettings`  | `RenderSettings`                        | —         | Override the list or loading UI                                                          |
+| `viewSettings`    | `ViewSettings`                          | —         | Shorthand for setting up grid/list/calendar/feeds/kanban views — see View Settings below |
+| `additionalQuery` | `AdditionalQuery[]`                     | —         | Filter controls rendered above the list                                                  |
+| `sort`            | `Sort`                                  | —         | Default sort applied to list queries                                                     |
+| `limit`           | `number`                                | `10`      | Records per page                                                                         |
+| `groupId`         | `string`                                | —         | Groups list results by this field                                                        |
+| `uniqueLabel`     | `string`                                | —         | Appended to internal query keys to avoid collisions                                      |
+| `schemaReference` | `{ [key: string]: DataStructure[] }`    | —         | Hardcoded schema reference (bypasses schema endpoint)                                    |
+| `newTabUrl`       | `{ default?: string; addons?: string }` | —         | URL config for row links                                                                 |
+| `lib`             | `LibSettings`                           | —         | Firebase storage helpers — see Lib below                                                 |
+| `handleNavigate`  | `(type, selectedId, viewId) => void`    | —         | Called when the component needs to navigate between views                                |
+| `handleComplete`  | `(id: string) => void`                  | —         | Called after a create/update operation completes                                         |
+
+## Workspace
+
+Replaces `DataTemplate`'s `devSettings`. The wrapper calls `parseWorkspaceSettings` internally to build the full config.
+
+| Name                  | Type                                | Description                                    |
+| --------------------- | ----------------------------------- | ---------------------------------------------- |
+| `apiEndpointType`     | `"mongoDB" \| "firebase" \| string` | Maps to `devSettings.server`                   |
+| `apiEndpoint`         | `string`                            | Database API base URL                          |
+| `apiEndpointToken`    | `string`                            | API token                                      |
+| `apiUserToken`        | `string`                            | Per-user auth token                            |
+| `assetEndpoint`       | `string`                            | Asset retrieval base URL                       |
+| `assetUploadEndpoint` | `string`                            | Upload endpoint                                |
+| `assetBucket`         | `string`                            | Storage bucket name (AWS/GCS)                  |
+| `maxFileSize`         | `number`                            | Global max file size in MB                     |
+| `organisationMembers` | `Option[]`                          | Member list for `person` / `listPerson` fields |
+
+---
+
+## Lib
+
+Only Firebase storage helpers are needed here — axios, headlessUI, and papaparse are bundled internally.
+
+| Name             | Type  | Description                        |
+| ---------------- | ----- | ---------------------------------- |
+| `storage`        | `any` | Firebase Storage instance          |
+| `ref`            | `any` | Firebase `ref` function            |
+| `uploadBytes`    | `any` | Firebase `uploadBytes` function    |
+| `getDownloadURL` | `any` | Firebase `getDownloadURL` function |
+
+---
+
+## Organise
+
+The `organise` prop is the same type as `DataTemplate`'s `Organise` — refer to [DataTemplate's Organise prop](?path=/story/data--data-template) for the full list of options.
+
+A few keys are handled differently in `DataTemplateWrapper`:
+
+| Key                       | Behaviour                                                                        |
+| ------------------------- | -------------------------------------------------------------------------------- |
+| `handleNavigate`          | Use the top-level `handleNavigate` prop instead — it is merged in automatically  |
+| `additionalQuery`         | Use the top-level `additionalQuery` prop instead — it is merged in automatically |
+| `sort`                    | Use the top-level `sort` prop instead — it is merged in automatically            |
+| `viewId` / `extendedTabs` | Use `viewSettings` instead — the wrapper builds these for you                    |
+
+Everything else (`breadcrumbType`, `tabAlign`, `splitView`, `exportSettings`, `advSortEnabled`, `advFilterEnabled`, `groupIdCollapsible`, etc.) works exactly the same as in `DataTemplate` and can be passed directly via `organise`.
+
+---
+
+## View Settings
+
+A shorthand that builds the `extendedTabs` and `viewId` config for you. Only one view type can be active at a time — the first matching key wins in this order: `listImage` → `calendarSettings` → `feedsSettings` → `kanbanSettings` → `gridImage`.
+
+| Name               | Type               | Description                                                     |
+| ------------------ | ------------------ | --------------------------------------------------------------- |
+| `gridImage`        | `string`           | Column ID of an image field — activates grid view               |
+| `gridScroll`       | `boolean`          | Enables infinite scroll in grid view                            |
+| `gridContain`      | `boolean`          | Uses `object-contain` instead of `object-cover` for grid images |
+| `listImage`        | `string`           | Column ID of an image field — activates list view               |
+| `calendarSettings` | `CalendarSettings` | Activates calendar view — see CalendarSettings below            |
+| `feedsSettings`    | `FeedsSettings`    | Activates feeds view — see DataTemplate's Feeds Settings        |
+| `kanbanSettings`   | `KanbanSettings`   | Activates kanban view — see DataTemplate's Kanban Settings      |
+
+### CalendarSettings
+
+| Name                   | Type                                                            | Description                                                                                                 | Optional |
+| ---------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | -------- |
+| `title`                | `string`                                                        | Column ID for the event title                                                                               |          |
+| `startDate`            | `string`                                                        | Column ID for the event start date                                                                          |          |
+| `endDate`              | `string`                                                        | Column ID for the event end date                                                                            | ✓        |
+| `groupId`              | `string`                                                        | Column ID — events with the same value share a background colour                                            | ✓        |
+| `groupColor`           | `Color[]`                                                       | Background colours for groups                                                                               | ✓        |
+| `defaultStartDate`     | `Date`                                                          | Initial date the calendar opens on                                                                          | ✓        |
+| `defaultView`          | `string`                                                        | Initial calendar view — e.g. `"dayGridMonth"`, `"timeGridWeek"`, `"timeGridDay"`, `"listMonth"`             | ✓        |
+| `customPlugin`         | `any`                                                           | A FullCalendar-compatible plugin. When set, the default view switches to `"timeGridWeek"` unless overridden | ✓        |
+| `customView`           | `{ view: "week"; duration: number }`                            | Multi-week span for week view — e.g. `{ view: "week", duration: 2 }` shows a 2-week range                   | ✓        |
+| `headerToolbar`        | `{ left?: string; center?: string; right?: string }`            | Override the calendar header toolbar buttons                                                                | ✓        |
+| `footerToolbar`        | `{ left?: string; center?: string; right?: string }`            | Override the calendar footer toolbar buttons                                                                | ✓        |
+| `customButtons`        | `{ [key: string]: any }`                                        | Define custom toolbar buttons — keys match button names used in `headerToolbar`/`footerToolbar`             | ✓        |
+| `customHeader`         | `string`                                                        | Static string to override the toolbar title                                                                 | ✓        |
+| `handleCalendarResize` | `(calendarRef: RefObject<any>, isMobileWidth: boolean) => void` | Called when the calendar container resizes — use to switch views on mobile                                  | ✓        |
+
+---
+
+### Bare Settings
+
+| Name                                     | Type                                                                                  | Description                                                |
+| ---------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| `bareReadComponent`                      | `(data: any) => ReactElement`                                                         | Custom component rendered in read view                     |
+| `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                       |
+| `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                        |
+| `bareListMultipleSelectAddtionalActions` | `{ text: string; className?: string; onClick: (ids, selectAll, query) => void }[]`    | Extra bulk-action buttons when rows are selected           |
+| `bareListGridComponent`                  | `(data: any) => ReactElement`                                                         | Custom card renderer for grid view                         |
+| `bareListGridColClassName`               | `string`                                                                              | Tailwind class for grid column width                       |
+| `bareListGridTags`                       | `(data: any) => string[]`                                                             | Tag strings shown on grid cards                            |
+| `bareListGridRibbonText`                 | `(data: any) => string`                                                               | Ribbon text on grid cards                                  |
+| `bareListGridFallbackImg`                | `(data: any) => string \| ReactElement`                                               | Fallback image for grid cards                              |
+| `bareListHandleData`                     | `(data, prettierData) => void`                                                        | Called when list data is loaded                            |
+| `bareListHandleFilter`                   | `(search, select, date, reference) => void`                                           | Called when any filter changes                             |
+| `bareListHandleSelection`                | `(selectAll, selectedIds, query?) => void`                                            | Called when row selection changes                          |
+| `bareListDescription`                    | `(key, value) => any`                                                                 | Custom renderer for list view field values                 |
+| `bareListFilterQuery`                    | `Query[]`                                                                             | Additional queries always applied to list fetches          |
+| `bareListFilterAddComponent`             | `ReactElement[]`                                                                      | Extra filter components in the filter bar                  |
+| `bareListPipeline`                       | `PipeLine[]`                                                                          | Additional MongoDB aggregation pipeline stages             |
+| `bareListFilterSelected`                 | `(filterSearchParams, filterSelection, filterReference, filterReferenceDate) => void` | Called with the current filter state on every change       |
+| `bareUpdatePrefill`                      | `(data: any) => { key: string; value: any }[]`                                        | Returns prefill values for the update form                 |
+| `bareUpdateComponent`                    | `(data: any) => ReactElement`                                                         | Custom component rendered inside the update form           |
+| `bareUpdateComponentAbove`               | `boolean`                                                                             | Renders `bareUpdateComponent` above the form fields        |
+| `bareUpdateActionComponent`              | `(data: any) => ReactElement`                                                         | Custom action buttons in the form footer                   |
+| `bareUpdateColumnType`                   | `"one" \| "two" \| "four"`                                                            | Form column layout                                         |
+| `bareUpdateMobileView`                   | `boolean`                                                                             | Mobile-optimised form layout                               |
+| `bareUpdateActionBottom`                 | `boolean`                                                                             | Moves action buttons to the bottom of the form             |
+| `bareUpdateHandleData`                   | `(data, changedAttributeIds?) => void`                                                | Called on every form field change                          |
+| `bareUpdateHandlePreComplete`            | `(data: any) => Promise<boolean>`                                                     | Called before save — return `false` to cancel              |
+| `bareUpdateHandleComplete`               | `(data: any) => void`                                                                 | Called after save completes                                |
+| `bareUpdateHandlePostComplete`           | `(data: any) => void`                                                                 | Called after post-save operations complete                 |
+| `bareUpdateTabId`                        | `(tabId: string) => void`                                                             | Called when the active form tab changes                    |
+| `bareUpdateTabComponent`                 | `(tabIds: string[]) => { tabId: string; icon?: ReactElement; skip?: boolean }[]`      | Customise tab icons or skip specific tabs in the form      |
+| `bareUpdateIndividualComponent`          | `(columnId, ref, selectedData, setSelectedData) => ReactElement \| null`              | Replaces a specific form field with a custom component     |
+| `bareReferenceDel`                       | `{ collectionId, collectionName, columnId, schema }[]`                                | Blocks deletion when the record is referenced elsewhere    |
+| `bareOffline`                            | `boolean`                                                                             | Enables offline data caching                               |
+| `bareCSVImportEndpoint`                  | `string`                                                                              | Custom CSV import endpoint                                 |
+| `bareCSVExportEndpoint`                  | `string`                                                                              | Custom CSV export endpoint                                 |
+
+---
+
+## Render Settings
+
+| Name              | Type                                                                | Description                          |
+| ----------------- | ------------------------------------------------------------------- | ------------------------------------ |
+| `renderListUI`    | `(actionComponent, filterComponent, dataComponent) => ReactElement` | Fully replaces the list layout       |
+| `renderLoadingUI` | `() => ReactElement`                                                | Replaces the default loading spinner |