blixify-ui-web-mcp 0.1.1

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

@@ -0,0 +1,903 @@
+# Data Template
+
+<!-- STORY -->
+
+<hr>
+
+A full-featured data management component that handles list, read, and update views with pagination, filtering, sorting, export, inline editing, and extensible bare/render settings.
+
+`DataTemplate` is the right choice when you already have a **Space object** from the Blixify backend. The Space object carries the full schema, sort config, extended tabs, and additional queries — you pass it via the `space` prop and use `parseSpaceToDataStructure` to derive the `model`. This makes `DataTemplate` ideal for building dynamic, schema-driven dashboards where the structure is defined in the database rather than hardcoded in the app.
+
+If you don't have a Space object and want to define the schema yourself, use `DataTemplateWrapper` instead — it removes most of the boilerplate and is the recommended starting point for custom integrations.
+
+### Import
+
+```js
+import { DataTemplate } from "blixify-ui-web/data/dataTemplate";
+```
+
+---
+
+## How It Works
+
+`DataTemplate` is driven by a single `type` prop that controls which view is rendered:
+
+- `"list"` — renders the table/list/grid/kanban/calendar view with pagination, search, and filters
+- `"read"` — renders the detail view for a single record (identified by `id`)
+- `"update"` — renders the create/edit form (pass `id=""` or `id="new"` for create, or an existing record ID to edit)
+
+Navigation between views is entirely controlled by your app. The component calls `organise.handleNavigate(type, selectedId?, viewId?)` whenever the user clicks a row, a breadcrumb, or a create button. You store `type`, `id`, and `viewId` in your own state and pass them back as props — the component re-renders into the new view.
+
+```
+User clicks row  →  handleNavigate("read", "abc123")  →  setType("read"), setId("abc123")
+User clicks Edit →  handleNavigate("update", "abc123") →  setType("update"), setId("abc123")
+User clicks Back →  handleNavigate("list")             →  setType("list"), setId("")
+```
+
+The `model` prop defines the columns/fields. You can build it manually as a `DataStructure[]` array, or derive it from a Space object using the `parseSpaceToDataStructure` utility.
+
+`devSettings` tells the component which backend to talk to. You can build it manually or derive it from a Workspace object using the `parseWorkspaceSettings` utility.
+
+---
+
+## Step-by-Step Setup
+
+**1. Install peer dependencies**
+
+```bash
+npm install axios @headlessui/react papaparse
+```
+
+**2. Create a ref and state**
+
+```tsx
+const dataTemplateRef = useRef<any>(null);
+const [type, setType] = useState("list");
+const [id, setId] = useState("");
+const [viewId, setViewId] = useState("general");
+```
+
+**3. Define your model**
+
+```tsx
+const model: DataStructure[] = [
+  { id: "name", name: "Name", type: "string" },
+  {
+    id: "status",
+    name: "Status",
+    type: "list",
+    listSelection: ["active", "inactive"],
+  },
+  { id: "createdAt", name: "Created", type: "date" },
+];
+```
+
+Or derive it from a Space object fetched from your backend:
+
+```tsx
+import { parseSpaceToDataStructure } from "blixify-ui-web/data/utils";
+const model = parseSpaceToDataStructure(spaceObject);
+```
+
+**4. Configure devSettings**
+
+```tsx
+const devSettings = {
+  server: "mongoServer",
+  dbEndpoint: "https://api.example.com/api/data",
+  dbAPIToken: "your-api-token",
+  dbUserToken: "",
+  schemaEndpoint: "https://api.example.com/api/schema",
+  imageEndpoint: "https://storage.example.com/o/",
+};
+```
+
+Or derive it from a Workspace object:
+
+```tsx
+import { parseWorkspaceSettings } from "blixify-ui-web/data/utils";
+const devSettings = parseWorkspaceSettings(
+  { dbEndpoint, imageEndpoint, uploadEndpoint },
+  workspaceObject
+);
+```
+
+**5. Wire navigation**
+
+```tsx
+const handleNavigate = (
+  nextType: string,
+  selectedId?: string,
+  nextViewId?: string
+) => {
+  setType(nextType);
+  if (selectedId !== undefined) setId(selectedId);
+  if (nextViewId) setViewId(nextViewId);
+};
+```
+
+`handleNavigate` is just a callback — you're in full control of what happens inside it. Instead of updating local state you can navigate to a different route entirely:
+
+```tsx
+const handleNavigate = (type: string, selectedId?: string) => {
+  if (type === "read" && selectedId) {
+    router.push(`/records/${selectedId}`); // React Router / Next.js
+    // or: window.location.href = `/records/${selectedId}`;
+  } else if (type === "update" && selectedId) {
+    router.push(`/records/${selectedId}/edit`);
+  } else {
+    setType("list");
+    setId("");
+  }
+};
+```
+
+**6. Render the component**
+
+```tsx
+<DataTemplate
+  ref={dataTemplateRef}
+  title="Sites"
+  description="Manage your sites"
+  type={type}
+  id={id}
+  collectionId="sites"
+  model={model}
+  localURLEndpoint="https://dashboard.example.com"
+  devSettings={devSettings}
+  lib={{ axios, Menu, Transition, navigate: null, papaParser: Papa }}
+  organise={{ viewId, handleNavigate }}
+/>
+```
+
+---
+
+## Use Case Examples
+
+### Read-only list
+
+No `edit` prop — hides all create/update/delete controls. Users can browse and search but cannot modify data.
+
+```tsx
+<DataTemplate
+  title="Products"
+  description="Browse products"
+  type={type}
+  id={id}
+  collectionId="products"
+  model={model}
+  localURLEndpoint="https://dashboard.example.com"
+  devSettings={devSettings}
+  lib={{ axios, Menu, Transition, navigate: null }}
+  organise={{ handleNavigate }}
+/>
+```
+
+---
+
+### Full CRUD
+
+Enable all editing features. `allEditable` turns on create, update, and delete in one flag.
+
+```tsx
+<DataTemplate
+  ref={dataTemplateRef}
+  title="Orders"
+  description="Manage orders"
+  type={type}
+  id={id}
+  collectionId="orders"
+  model={model}
+  localURLEndpoint="https://dashboard.example.com"
+  devSettings={devSettings}
+  lib={{ axios, Menu, Transition, navigate: null, papaParser: Papa }}
+  edit={{
+    allEditable: true,
+    listEditable: true, // inline cell editing in table view
+    listAddable: true, // inline row creation in table view
+    deleteBtn: true,
+  }}
+  organise={{ handleNavigate }}
+/>
+```
+
+---
+
+### Calendar view
+
+Set `organise.viewId="calendar"` and add an `extendedTabs` entry with `calendarSettings` pointing to your date columns.
+
+```tsx
+<DataTemplate
+  title="Events"
+  description="Event calendar"
+  type={type}
+  id={id}
+  collectionId="events"
+  model={model}
+  localURLEndpoint="https://dashboard.example.com"
+  devSettings={devSettings}
+  lib={{ axios, Menu, Transition, navigate: null }}
+  organise={{
+    viewId: "calendar",
+    extendedTabs: [
+      {
+        name: "Calendar",
+        type: "list",
+        viewType: "calendar",
+        calendarSettings: {
+          title: "name", // column ID for event title
+          startDate: "startAt", // column ID for start date
+          endDate: "endAt", // column ID for end date
+        },
+      },
+    ],
+    handleNavigate,
+  }}
+/>
+```
+
+---
+
+### Grid view
+
+Set `organise.viewId="grid"` (or add an `extendedTabs` entry with `viewType="grid"`) to render records as image cards. Use `bareSettings.bareListGridComponent` to fully customise each card, or use the built-in grid with `viewImage` pointing to an image column.
+
+```tsx
+<DataTemplate
+  title="Products"
+  description="Browse products as cards"
+  type={type}
+  id={id}
+  collectionId="products"
+  model={model}
+  localURLEndpoint="https://dashboard.example.com"
+  devSettings={devSettings}
+  lib={{ axios, Menu, Transition, navigate: null }}
+  organise={{
+    viewId: "grid",
+    handleNavigate,
+    extendedTabs: [
+      {
+        name: "Grid",
+        type: "list",
+        viewType: "grid",
+        viewImage: "coverImage", // column ID of an image field
+      },
+    ],
+  }}
+  bareSettings={{
+    // Optional: fully replace the default grid card
+    bareListGridComponent: (rowData) => (
+      <div className="p-4 rounded-lg border border-gray-200">
+        <img
+          src={rowData.coverImage}
+          className="w-full h-32 object-cover rounded"
+        />
+        <p className="mt-2 font-medium">{rowData.name}</p>
+        <p className="text-sm text-gray-500">{rowData.price}</p>
+      </div>
+    ),
+    // Tags shown on the default grid card
+    bareListGridTags: (rowData) => [rowData.category, rowData.status],
+    // Ribbon text on the default grid card
+    bareListGridRibbonText: (rowData) =>
+      rowData.status === "new" ? "New" : "",
+    // Fallback when the image column is empty
+    bareListGridFallbackImg: () => "/placeholder.png",
+  }}
+/>
+```
+
+---
+
+### List view
+
+Set `organise.viewId="list"` to render records as a vertical list instead of a table. Useful for content-heavy records where a table layout feels cramped. Use `bareSettings.bareListComponent` to fully replace the list UI with your own renderer.
+
+```tsx
+<DataTemplate
+  title="Articles"
+  description="Browse articles"
+  type={type}
+  id={id}
+  collectionId="articles"
+  model={model}
+  localURLEndpoint="https://dashboard.example.com"
+  devSettings={devSettings}
+  lib={{ axios, Menu, Transition, navigate: null }}
+  organise={{
+    viewId: "list",
+    handleNavigate,
+  }}
+  bareSettings={{
+    // Optional: fully replace the list UI
+    bareListComponent: (data, prettierData, loading, pageIndex) => {
+      if (loading) return <div>Loading...</div>;
+      return (
+        <ul className="divide-y divide-gray-200">
+          {data.map((item) => (
+            <li key={item._id} className="py-4 flex gap-4">
+              <div>
+                <p className="font-medium">{item.title}</p>
+                <p className="text-sm text-gray-500">{item.summary}</p>
+              </div>
+            </li>
+          ))}
+        </ul>
+      );
+    },
+  }}
+/>
+```
+
+---
+
+### Kanban view
+
+Set `viewType="kanban"` on an `extendedTabs` entry and configure `kanbanSettings` to define which column drives the board columns. `title` is the column ID shown on each card; `groupCluster` maps column names to the list-selection values that belong in that column.
+
+```tsx
+<DataTemplate
+  title="Tasks"
+  description="Task board"
+  type={type}
+  id={id}
+  collectionId="tasks"
+  model={[
+    { id: "name", name: "Name", type: "string" },
+    { id: "assignee", name: "Assignee", type: "string" },
+    {
+      id: "status",
+      name: "Status",
+      type: "list",
+      listSelection: ["backlog", "in_progress", "review", "done"],
+    },
+  ]}
+  localURLEndpoint="https://dashboard.example.com"
+  devSettings={devSettings}
+  lib={{ axios, Menu, Transition, navigate: null }}
+  edit={{ allEditable: true }}
+  organise={{
+    viewId: "kanban",
+    handleNavigate,
+    extendedTabs: [
+      {
+        name: "Board",
+        type: "list",
+        viewType: "kanban",
+        kanbanSettings: {
+          title: "name", // column ID for card title
+          useColumnName: true, // show column name on cards
+          // groupCluster maps each board column to one or more list values
+          groupCluster: [
+            { Backlog: ["backlog"] },
+            { "In Progress": ["in_progress"] },
+            { Review: ["review"] },
+            { Done: ["done"] },
+          ],
+        },
+      },
+    ],
+  }}
+/>
+```
+
+---
+
+### With search and filter
+
+Use `organise.additionalQuery` to add filter controls above the list. Each entry maps to a filter UI control.
+
+```tsx
+<DataTemplate
+  title="Leads"
+  description="Filter leads by status and owner"
+  type={type}
+  id={id}
+  collectionId="leads"
+  model={model}
+  localURLEndpoint="https://dashboard.example.com"
+  devSettings={devSettings}
+  lib={{ axios, Menu, Transition, navigate: null }}
+  organise={{
+    additionalQuery: [
+      {
+        type: "list",
+        value: "status",
+        filterLabel: "Status",
+        options: ["new", "contacted", "closed"],
+      },
+      {
+        type: "reference",
+        value: "ownerId",
+        filterLabel: "Owner",
+        spaceId: "users",
+        label: "name",
+      },
+    ],
+    handleNavigate,
+  }}
+/>
+```
+
+---
+
+### With activity log (comments + audit trail)
+
+Enable `edit.activityLog` to show a comments panel and a change-log timeline in the read view.
+
+```tsx
+<DataTemplate
+  title="Tickets"
+  description="Support tickets"
+  type={type}
+  id={id}
+  collectionId="tickets"
+  model={model}
+  localURLEndpoint="https://dashboard.example.com"
+  devSettings={devSettings}
+  lib={{ axios, Menu, Transition, navigate: null }}
+  edit={{
+    allEditable: true,
+    activityLog: {
+      enableComments: true,
+      commentCollectionId: "tickets-comments",
+      enableLogs: true,
+      logsCollectionId: "tickets-logs",
+      userAPIEndpoint: "https://api.example.com/api/data/users",
+      currentUserId: currentUser.id,
+    },
+  }}
+  organise={{ handleNavigate }}
+/>
+```
+
+---
+
+### Export PDF from read view
+
+Enable `organise.exportSettings.enableExportReadPDF` to add a PDF export button in the read view toolbar. You can also trigger it programmatically via `ref.handleExportReadPDF()`.
+
+```tsx
+<DataTemplate
+  ref={dataTemplateRef}
+  title="Reports"
+  description="View and export reports"
+  type={type}
+  id={id}
+  collectionId="reports"
+  model={model}
+  localURLEndpoint="https://dashboard.example.com"
+  devSettings={devSettings}
+  lib={{ axios, Menu, Transition, navigate: null }}
+  organise={{
+    handleNavigate,
+    exportSettings: {
+      // ── Read-view PDF ─────────────────────────────────────────────────────
+      enableExportReadPDF: true, // show PDF export button in read view toolbar
+      defaultExportPDFName: "report", // default filename (no extension)
+      onExportReadPDFBlob: (blob) => uploadPDF(blob), // callback with the generated PDF blob
+
+      // ── PDF header (first page only) ──────────────────────────────────────
+      exportReadPDFHeader: {
+        text: {
+          value: "Acme Corp — Confidential",
+          alignment: "left", // "left" | "center" | "right"
+          x: 10, // x position in mm (optional)
+          y: 10, // y position in mm (optional)
+        },
+        image: {
+          src: logoUrl, // URL or imported image asset
+          width: 40, // width in mm
+          height: 15, // height in mm
+          alignment: "right", // "left" | "center" | "right"
+          x: 160, // x position in mm (optional)
+          y: 8, // y position in mm (optional)
+        },
+      },
+
+      // ── Page dimensions & capture ─────────────────────────────────────────
+      exportReadPDFDimensions: {
+        pageSize: "a4", // "a4" | "a3" | "letter" | "legal" | "custom"
+        orientation: "p", // "p" portrait | "l" landscape
+        // width: 210,            // custom page width in mm (pageSize="custom" only)
+        // height: 297,           // custom page height in mm (pageSize="custom" only)
+        useElementDimensions: false, // use element's actual size instead of pageSize
+        scale: 2, // html2canvas scale — higher = sharper, larger file
+        margin: 10, // page margin in mm
+        forceDesktopView: true, // simulate desktop viewport during capture
+        captureWidth: 1440, // simulated viewport width in px
+        captureHeight: 900, // simulated viewport height in px (omit to auto-expand)
+      },
+
+      // ── List-view export controls ─────────────────────────────────────────
+      columnIds: ["name", "status", "createdAt"], // columns to include (omit = all)
+      csvHeaderUseName: true, // use column name instead of id as CSV header
+      dateFormatString: "DD/MM/YYYY", // date format in exported documents
+      sumColumnId: ["amount", "quantity"], // columns to sum in export footer
+      sort: { sortId: "createdAt", type: "desc" }, // sort applied to exported data
+      excludeDataId: true, // exclude record _id from exports
+      excludeReferenceId: true, // exclude reference _id from exports
+      excludeSecondaryLabel: false, // exclude reference secondary label
+      disableEmail: false, // disable email-export feature
+      hideExportCSV: false, // hide Export CSV option
+      hideImportCSV: false, // hide Import CSV option
+      hideExportExcel: false, // hide Export Excel option
+      hideExportPDF: false, // hide list-view PDF export (not read-view)
+      hideExportPrint: false, // hide Print option
+      hideExportQR: false, // hide Export QR option
+      hideExportDraft: false, // hide Filter Draft option
+      hideSubItems: false, // hide nested rows in exports
+    },
+  }}
+/>
+```
+
+---
+
+## Utility Functions
+
+### `parseSpaceToDataStructure(space: Space): DataStructure[]`
+
+Converts a Space object (fetched from your backend) into the `model` array that `DataTemplate` expects. It maps all field types and their sub-settings (reference queries, list selections, image upload config, etc.) automatically.
+
+```tsx
+import { parseSpaceToDataStructure } from "blixify-ui-web/data/utils";
+
+const space = await fetchSpace(collectionId);
+const model = parseSpaceToDataStructure(space);
+```
+
+### `parseWorkspaceSettings(defaultEndpoint, workspace?): DevSettings`
+
+Builds a `DevSettings` object from a Workspace record. It maps `apiEndpointType` → `server`, `apiEndpoint` → `dbEndpoint`, `assetEndpoint` → `imageEndpoint`, and so on. Pass your fallback endpoints as the first argument; the workspace values override them when present.
+
+```tsx
+import { parseWorkspaceSettings } from "blixify-ui-web/data/utils";
+
+const devSettings = parseWorkspaceSettings(
+  {
+    dbEndpoint: process.env.DB_ENDPOINT,
+    imageEndpoint: process.env.IMAGE_ENDPOINT,
+    uploadEndpoint: process.env.UPLOAD_ENDPOINT,
+  },
+  workspaceObject // optional — overrides defaults when provided
+);
+```
+
+---
+
+### Ref Methods
+
+| Method                             | Description                                                       |
+| ---------------------------------- | ----------------------------------------------------------------- |
+| `handleRefresh()`                  | Re-fetches the current list data                                  |
+| `handleFormSubmit()`               | Programmatically submits the update/create form                   |
+| `handleFormCheck()`                | Validates the form without submitting                             |
+| `handlePopUpModal()`               | Opens the create/update modal                                     |
+| `handleDeleteModal()`              | Opens the delete confirmation modal                               |
+| `handleUpdateSelectedData(fields)` | Prefills form fields. `fields` is `{ key: string; value: any }[]` |
+| `handleExportReadPDF()`            | Triggers a PDF export of the current read view                    |
+| `handleUploadOfflineData()`        | Uploads any locally cached offline data                           |
+
+### Required props
+
+| Name               | Type                           | Description                                               |
+| ------------------ | ------------------------------ | --------------------------------------------------------- |
+| `title`            | `string \| ReactElement`       | Title shown in the header                                 |
+| `description`      | `string \| ReactElement`       | Description shown below the title                         |
+| `collectionId`     | `string`                       | Database collection / space ID                            |
+| `type`             | `"read" \| "update" \| "list"` | Current view mode                                         |
+| `model`            | `DataStructure[]`              | Column/field definitions — see DataStructure below        |
+| `localURLEndpoint` | `string`                       | Base URL of the dashboard (used for breadcrumb links)     |
+| `devSettings`      | `DevSettings`                  | Server and endpoint configuration — see DevSettings below |
+
+### Optional props
+
+| Name             | Type                                    | Default | Description                                                                                              |
+| ---------------- | --------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------- |
+| `id`             | `string`                                | `""`    | Selected record ID. Pass `"new"` to open a blank create form                                             |
+| `limit`          | `number`                                | `10`    | Records per page in list view                                                                            |
+| `space`          | `Space`                                 | —       | Full Space object from Blixify Space — enables extended features like tabs, sort, and additional queries |
+| `edit`           | `Edit`                                  | —       | Controls create/update/delete permissions — see Edit below                                               |
+| `organise`       | `Organise`                              | —       | Controls view, sort, filter, tabs, export, and navigation — see Organise below                           |
+| `bareSettings`   | `BareSettings`                          | —       | Injects custom React components and callbacks into list/read/update views — see BareSettings below       |
+| `renderSettings` | `RenderSettings`                        | —       | Overrides the entire list UI or loading UI with custom renderers                                         |
+| `roles`          | `string[]`                              | —       | Role strings (reserved for future permission checks)                                                     |
+| `darkMode`       | `boolean`                               | —       | Applies dark colour scheme                                                                               |
+| `uniqueLabel`    | `string`                                | —       | Unique label appended to internal query keys to avoid collisions                                         |
+| `groupId`        | `string`                                | —       | Groups list results by this field. Grouped items are returned with a `children` array                    |
+| `defaultTab`     | `any`                                   | —       | Pre-selects a tab on mount                                                                               |
+| `workspaceId`    | `string`                                | —       | Workspace ID (used for workspace-scoped operations)                                                      |
+| `newTabUrl`      | `{ default?: string; addons?: string }` | —       | URL config for row links. `default` is the base URL; `addons` is appended after the record id            |
+| `lib`            | `LibSettings`                           | —       | External library instances — see lib below                                                               |
+| `linkProps`      | `LinkProps`                             | —       | Refer to Link component documentation                                                                    |
+| `onComplete`     | `(id: string) => void`                  | —       | Called after a create/update operation completes                                                         |
+| `onLoadIframe`   | `() => void`                            | —       | Called when an iframe tab finishes loading                                                               |
+
+### lib
+
+| Name             | Type  | Description                                                    |
+| ---------------- | ----- | -------------------------------------------------------------- |
+| `axios`          | `any` | Axios instance for HTTP requests                               |
+| `firebase`       | `any` | Firebase app instance (required when `server="firebase"`)      |
+| `navigate`       | `any` | Router navigate function (e.g. React Router's `useNavigate`)   |
+| `navigateNext`   | `any` | Secondary navigate function                                    |
+| `Menu`           | `any` | Headless UI `Menu` component — required                        |
+| `Transition`     | `any` | Headless UI `Transition` component — required                  |
+| `papaParser`     | `any` | PapaParse instance — required for CSV import/export            |
+| `storage`        | `any` | Firebase Storage instance (Firebase client mode only)          |
+| `ref`            | `any` | Firebase `ref` function (Firebase client mode only)            |
+| `uploadBytes`    | `any` | Firebase `uploadBytes` function (Firebase client mode only)    |
+| `getDownloadURL` | `any` | Firebase `getDownloadURL` function (Firebase client mode only) |
+
+### DevSettings
+
+| Name                  | Type                                                          | Description                                               |
+| --------------------- | ------------------------------------------------------------- | --------------------------------------------------------- |
+| `server`              | `"mongoServer" \| "fbServer" \| "firebase" \| "mondayServer"` | Database server type                                      |
+| `dbEndpoint`          | `string`                                                      | Database API base URL                                     |
+| `dbAPIToken`          | `string`                                                      | API token for database requests                           |
+| `dbUserToken`         | `string`                                                      | Per-user auth token (pass `""` if not used)               |
+| `schemaEndpoint`      | `string`                                                      | Schema API endpoint URL                                   |
+| `schemaEndpointToken` | `string`                                                      | Optional token for schema endpoint                        |
+| `schemaReference`     | `{ [key: string]: DataStructure[] }`                          | Hardcoded schema reference (bypasses schema endpoint)     |
+| `imageEndpoint`       | `string`                                                      | Asset retrieval base URL                                  |
+| `uploadEndpoint`      | `string`                                                      | Upload endpoint (required when `imageEndpoint` is custom) |
+| `bucketName`          | `string`                                                      | Storage bucket name (required for AWS/GCS)                |
+| `maxFileSize`         | `number`                                                      | Global max file size in MB for uploads                    |
+| `organisationMembers` | `Option[]`                                                    | Member list used for `person` / `listPerson` field types  |
+| `roleOptions`         | `Option[]`                                                    | Role list used for `roles` field type                     |
+| `currentUser`         | `{ userEmail: string; userName: string }`                     | Current user info used for export email and QR features   |
+| `importEndpoint`      | `string`                                                      | Firebase CSV import function URL                          |
+| `functionEndpoint`    | `string`                                                      | Firebase export/function URL                              |
+
+### Edit
+
+| Name                    | Type          | Description                                              |
+| ----------------------- | ------------- | -------------------------------------------------------- |
+| `allEditable`           | `boolean`     | Enables add, update, and delete                          |
+| `listAddable`           | `boolean`     | Enables adding rows inline in list view                  |
+| `listEditable`          | `boolean`     | Enables inline cell editing in list view                 |
+| `createBtn`             | `boolean`     | Shows a create button even when `allEditable` is `false` |
+| `deleteBtn`             | `boolean`     | Enables delete and batch delete                          |
+| `disabledUpdate`        | `boolean`     | Disables update and batch update                         |
+| `disableBatchUpdate`    | `boolean`     | Disables batch update only                               |
+| `enableUpdateDraft`     | `boolean`     | Enables save-as-draft on the update form                 |
+| `disabledTabsDeleteBtn` | `boolean`     | Disables the delete button inside extended tabs          |
+| `activityLog`           | `ActivityLog` | See ActivityLog below                                    |
+
+### ActivityLog
+
+| Name                  | Type      | Description                                                                                       |
+| --------------------- | --------- | ------------------------------------------------------------------------------------------------- |
+| `enableComments`      | `boolean` | Enables create/update/delete comments                                                             |
+| `commentCollectionId` | `string`  | Collection ID for comments                                                                        |
+| `commentQuery`        | `Query[]` | Additional queries to filter comments                                                             |
+| `enableLogs`          | `boolean` | Displays create/update/delete logs in list and read views                                         |
+| `logsCollectionId`    | `string`  | Collection ID for logs                                                                            |
+| `logQuery`            | `Query[]` | Additional queries to filter logs                                                                 |
+| `userAPIEndpoint`     | `string`  | URL returning `{ data: { name: string, ...rest } }` — used to resolve user names in comments/logs |
+| `currentUserId`       | `string`  | Current user's record ID — required when `enableComments` is `true`                               |
+
+### Organise
+
+| Name                          | Type                                                                        | Description                                                                                  |
+| ----------------------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `sort`                        | `Sort`                                                                      | Default sort applied to list queries                                                         |
+| `pageIndex`                   | `number`                                                                    | Initial page index                                                                           |
+| `viewId`                      | `string`                                                                    | Active view type: `"general"`, `"calendar"`, `"grid"`, `"list"`, `"feeds"`, `"kanban"`, etc. |
+| `idField`                     | `string`                                                                    | DataStructure column ID whose value becomes the new record's ID on creation                  |
+| `extendedTabs`                | `ExtendedTabs[]`                                                            | Additional tabs rendered alongside the main view — see Extended Tab below                    |
+| `additionalQuery`             | `AdditionalQuery[]`                                                         | Filter/search controls rendered above the list — see Additional Query below                  |
+| `darkMode`                    | `boolean`                                                                   | Applies dark colour scheme to the organise bar                                               |
+| `hideSearch`                  | `boolean`                                                                   | Hides the search input                                                                       |
+| `hidePagination`              | `boolean`                                                                   | Hides pagination on Table, List, Grid, and Feeds views                                       |
+| `hideNewTabs`                 | `boolean`                                                                   | Hides the new-tab creation button                                                            |
+| `splitView`                   | `boolean`                                                                   | Renders a split list/detail layout in read mode                                              |
+| `listObjectTableView`         | `boolean`                                                                   | Shows list objects in table view during read and update                                      |
+| `disableMulti`                | `boolean`                                                                   | Disables multi-row selection                                                                 |
+| `disableSelectFullData`       | `{ table?: boolean; list?: boolean }`                                       | Disables "select all pages" for table and/or list views                                      |
+| `disabledOnEnter`             | `boolean`                                                                   | Prevents Enter key from submitting forms                                                     |
+| `breadcrumbType`              | `"button" \| "hidden"`                                                      | `"button"` shows a back button; `"hidden"` hides the breadcrumb entirely                     |
+| `breadcrumbAttributeId`       | `string`                                                                    | Column ID whose value is used as the breadcrumb label in read view                           |
+| `tabAlign`                    | `"top" \| "left" \| "stepper"`                                              | Tab layout direction                                                                         |
+| `groupRead`                   | `"groupId"`                                                                 | Groups and separates read view sections by DataStructure `groupId`                           |
+| `showCollapsibleTab`          | `boolean`                                                                   | Renders tabs as collapsible sections                                                         |
+| `showBaseUpdatedAt`           | `boolean`                                                                   | Shows the `baseUpdatedAt` timestamp in Table, Grid, List, and Kanban views                   |
+| `showGroupByFeature`          | `boolean`                                                                   | Shows the group-by selector in the toolbar                                                   |
+| `showReadFloatingNav`         | `boolean`                                                                   | Shows a floating section navigator in read view                                              |
+| `showExport`                  | `boolean`                                                                   | Shows import/export options (default `true`)                                                 |
+| `disableEllipsisOnLongWord`   | `boolean`                                                                   | Wraps long text instead of truncating with ellipsis                                          |
+| `fixedPagination`             | `boolean`                                                                   | Fixes the pagination bar to the bottom of the viewport                                       |
+| `filterComponentNewRow`       | `boolean`                                                                   | Renders each filter component on its own row                                                 |
+| `addColumnEnabled`            | `boolean`                                                                   | Shows an add-column button in the table header                                               |
+| `advSortEnabled`              | `boolean`                                                                   | Shows advanced sort controls                                                                 |
+| `advFilterEnabled`            | `boolean`                                                                   | Shows advanced filter controls                                                               |
+| `advDragEnabled`              | `boolean`                                                                   | Enables drag-to-reorder columns                                                              |
+| `groupBy`                     | `string`                                                                    | Column ID to group list results by                                                           |
+| `groupIdCollapsible`          | `{ [key: string]: boolean }`                                                | Initial collapsed/expanded state per group ID                                                |
+| `sortGroupByAlphabetically`   | `boolean`                                                                   | Sorts group-by values alphabetically                                                         |
+| `unionCollections`            | `any[]`                                                                     | Additional collections to union-query alongside the main collection                          |
+| `moreSettings`                | `{ text: string; onClick: () => void }[]`                                   | Extra items appended to the "more" dropdown menu                                             |
+| `exportSettings`              | `ExportSettings`                                                            | See Export Settings below                                                                    |
+| `onChangeSort`                | `(value: Sort) => void`                                                     | Called when the user changes the sort                                                        |
+| `onChangeFilter`              | `(value: AdditionalQuery[]) => void`                                        | Called when the user changes filters                                                         |
+| `onChangeHide`                | `(value: DataStructure[]) => void`                                          | Called when the user hides/shows columns                                                     |
+| `onChangeDrag`                | `(dragId: string, dropId: string, newHeader: TableHeader[]) => void`        | Called after a column is reordered                                                           |
+| `onChangeTabs`                | `(value: ExtendedTabs[]) => void`                                           | Called when tabs are added/removed/reordered                                                 |
+| `onChangePagination`          | `(page: number) => void`                                                    | Called when the page changes                                                                 |
+| `onAddColumns`                | `(model: DataStructure[]) => void`                                          | Called when a new column is added                                                            |
+| `handleNavigate`              | `(type: string, selectedId?: string, viewId?: string) => void`              | Called when the component needs to navigate (e.g. row click → read view)                     |
+| `handleCustomDownloadFile`    | `(url: string, fileName?: string) => void`                                  | Overrides the default file download behaviour                                                |
+| `renderReferenceLabelOptions` | `(spaceId?: string, includeReference?: boolean, type?: string) => Option[]` | Returns column options for reference label selectors                                         |
+| `renderReferenceSpaceOptions` | `() => Option[]`                                                            | Returns space options for reference space selectors                                          |
+| `renderGroupByOptions`        | `() => Option[]`                                                            | Returns custom options for the group-by selector                                             |
+
+### Export Settings
+
+| Name                      | Type                   | Description                                                                      |
+| ------------------------- | ---------------------- | -------------------------------------------------------------------------------- |
+| `dateFormatString`        | `string`               | Date format string for exported documents                                        |
+| `disableEmail`            | `boolean`              | Disables email functionality for exports                                         |
+| `excludeReferenceId`      | `boolean`              | Excludes reference `_id` from exported documents                                 |
+| `excludeSecondaryLabel`   | `boolean`              | Excludes reference secondary label from exported documents                       |
+| `csvHeaderUseName`        | `boolean`              | Uses DataStructure `name` instead of `id` for CSV/Excel headers                  |
+| `excludeDataId`           | `boolean`              | Excludes record `_id` from exported documents                                    |
+| `columnIds`               | `string[]`             | DataStructure IDs to include in exports (all columns if omitted)                 |
+| `defaultExportPDFName`    | `string`               | Default filename for exported PDFs                                               |
+| `sumColumnId`             | `string[]`             | Column IDs to sum in exported documents                                          |
+| `generateBy`              | `string`               | Specifies how the export is generated                                            |
+| `sort`                    | `Sort`                 | Sort applied to exported data                                                    |
+| `hideSubItems`            | `boolean`              | Hides sub-items in exported documents                                            |
+| `hideExportCSV`           | `boolean`              | Hides the Export CSV option                                                      |
+| `hideImportCSV`           | `boolean`              | Hides the Import CSV option                                                      |
+| `hideExportExcel`         | `boolean`              | Hides the Export Excel option                                                    |
+| `hideExportPDF`           | `boolean`              | Hides the Export PDF option                                                      |
+| `hideExportPrint`         | `boolean`              | Hides the Print option                                                           |
+| `hideExportQR`            | `boolean`              | Hides the Export QR option                                                       |
+| `hideExportDraft`         | `boolean`              | Hides the Filter Draft option                                                    |
+| `enableExportReadPDF`     | `boolean`              | Enables PDF export from read view                                                |
+| `exportReadPDFHeader`     | `PDFHeaderConfig`      | Header config for read-view PDF export — see PDFHeaderConfig below               |
+| `exportReadPDFDimensions` | `PDFDimensionsConfig`  | Page/capture dimensions for read-view PDF export — see PDFDimensionsConfig below |
+| `onExportReadPDFBlob`     | `(blob: Blob) => void` | Callback receiving the PDF blob after export                                     |
+
+### PDFHeaderConfig
+
+| Name    | Type                                                                                                                  | Description                                                                                                       |
+| ------- | --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `text`  | `{ value: string; x?: number; y?: number; alignment?: "left" \| "center" \| "right" }`                                | Text shown in the PDF header (first page only). `x`/`y` are positions in mm                                       |
+| `image` | `{ src: string; x?: number; y?: number; width?: number; height?: number; alignment?: "left" \| "center" \| "right" }` | Image shown in the PDF header (first page only). `src` can be a URL or imported image. `width`/`height` are in mm |
+
+### PDFDimensionsConfig
+
+| Name                   | Type                                              | Description                                                        |
+| ---------------------- | ------------------------------------------------- | ------------------------------------------------------------------ |
+| `pageSize`             | `"a4" \| "a3" \| "letter" \| "legal" \| "custom"` | Page size preset                                                   |
+| `orientation`          | `"p" \| "l"`                                      | Portrait or landscape                                              |
+| `width`                | `number`                                          | Custom page width in mm (when `pageSize="custom"`)                 |
+| `height`               | `number`                                          | Custom page height in mm (when `pageSize="custom"`)                |
+| `useElementDimensions` | `boolean`                                         | Uses the element's actual dimensions instead of a page size preset |
+| `scale`                | `number`                                          | html2canvas scale factor (higher = better quality, larger file)    |
+| `margin`               | `number`                                          | Page margin in mm                                                  |
+| `forceDesktopView`     | `boolean`                                         | Captures as if on a desktop viewport                               |
+| `captureWidth`         | `number`                                          | Simulated desktop capture width in pixels                          |
+| `captureHeight`        | `number`                                          | Simulated desktop capture height in pixels                         |
+
+### BareSettings
+
+Injects custom React components and callbacks into the list, read, and update views.
+
+| Name                                     | Type                                                                                  | Description                                                                                     |
+| ---------------------------------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `bareReadComponent`                      | `(data: any) => any`                                                                  | Custom component rendered in read view                                                          |
+| `bareReadComponentPos`                   | `"top"`                                                                               | Renders `bareReadComponent` above the default read content                                      |
+| `bareReadComponentHide`                  | `boolean`                                                                             | Hides the default read content (shows only `bareReadComponent`)                                 |
+| `bareReadReferenceView`                  | `(dataId, collectionId, attributeId) => boolean \| void`                              | Controls whether a reference field opens a view                                                 |
+| `bareReadDescription`                    | `(key: string, value: any) => any`                                                    | Custom renderer for read view field values                                                      |
+| `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) => any`                                     | Fully replaces the list UI with a custom component                                              |
+| `bareListActionBtns`                     | `(data: any) => ReactElement[]`                                                       | Extra icon buttons rendered on each list row                                                    |
+| `bareListMultipleSelectAddtionalActions` | `{ text: string; className?: string; onClick: (ids, selectAll, query) => void }[]`    | Extra bulk-action buttons shown when rows are selected                                          |
+| `bareListGridComponent`                  | `(data: any) => any`                                                                  | Custom card renderer for grid view                                                              |
+| `bareListGridColClassName`               | `string`                                                                              | Tailwind class for grid column width                                                            |
+| `bareListGridTags`                       | `(data: any) => string[]`                                                             | Returns tag strings shown on grid cards                                                         |
+| `bareListGridFallbackImg`                | `(data: any) => string \| ReactElement`                                               | Fallback image/element for grid cards without an image                                          |
+| `bareListGridRibbonText`                 | `(data: any) => string`                                                               | Text shown as a ribbon on grid cards                                                            |
+| `bareListHandleData`                     | `(data, prettierData) => void`                                                        | Called when list data is loaded                                                                 |
+| `bareListHandleSelection`                | `(selectAll, selectedIds, query?) => void`                                            | Called when row selection changes                                                               |
+| `bareListHandleFilter`                   | `(search, select, date, reference) => void`                                           | Called when any filter changes                                                                  |
+| `bareListFilterSelected`                 | `(filterSearchParams, filterSelection, filterReference, filterReferenceDate) => void` | Called with the current filter state whenever it changes                                        |
+| `bareListDescription`                    | `(key: string, value: any) => any`                                                    | Custom renderer for list view field values                                                      |
+| `bareListFilterQuery`                    | `Query[]`                                                                             | Additional queries always applied to list fetches                                               |
+| `bareListFilterAddComponent`             | `ReactElement[]`                                                                      | Extra filter components rendered in the filter bar                                              |
+| `bareListPipeline`                       | `PipeLine[]`                                                                          | Additional pipeline stages appended to list queries                                             |
+| `bareListObjectHandleData`               | `(type: "read" \| "update" \| "new", data: any) => void`                              | Called when a list-object row is opened                                                         |
+| `bareUpdatePrefill`                      | `(data: any) => { key: string; value: any }[]`                                        | Returns prefill values for the update form based on existing data                               |
+| `bareUpdateComponent`                    | `(data: any) => any`                                                                  | Custom component rendered inside the update form                                                |
+| `bareUpdateComponentAbove`               | `boolean`                                                                             | Renders `bareUpdateComponent` above the default form fields                                     |
+| `bareUpdateActionComponent`              | `(data: any, formRef?: any) => any`                                                   | Custom action buttons rendered in the update form footer                                        |
+| `bareUpdateHandleData`                   | `(data: any, changedAttributeIds?: string[]) => void`                                 | Called on every form field change with the current data and changed field IDs                   |
+| `bareUpdateHandlePreComplete`            | `(data: any) => Promise<boolean>`                                                     | Called before save — return `false` to cancel                                                   |
+| `bareUpdateHandleComplete`               | `(data: any) => Promise<any>`                                                         | Called after save completes                                                                     |
+| `bareUpdateHandlePostComplete`           | `(data: any) => Promise<any>`                                                         | Called after post-save operations complete                                                      |
+| `bareUpdateColumnType`                   | `"one" \| "two" \| "four"`                                                            | Form column layout: `"one"` = 2-col grid, `"two"` = 4-col grid (default), `"four"` = 4-col grid |
+| `bareUpdateTabComponent`                 | `(tabIds: string[]) => { tabId: string; icon?: ReactElement; skip?: boolean }[]`      | Custom icons/skip flags for form tabs                                                           |
+| `bareUpdateActionBottom`                 | `boolean`                                                                             | Renders action buttons at the bottom of the form                                                |
+| `bareUpdateTabId`                        | `(tabId: string) => void`                                                             | Called when the active form tab changes                                                         |
+| `bareUpdateIndividualComponent`          | `(columnId, ref, selectedData, setSelectedData) => ReactElement \| null`              | Replaces a specific form field with a custom component                                          |
+| `bareUpdateMobileView`                   | `boolean`                                                                             | Renders the update form in mobile-optimised layout                                              |
+| `bareOffline`                            | `boolean`                                                                             | Enables offline data caching via IndexedDB                                                      |
+| `bareCSVImportEndpoint`                  | `string`                                                                              | Custom CSV import endpoint                                                                      |
+| `bareCSVExportEndpoint`                  | `string`                                                                              | Custom CSV export endpoint                                                                      |
+| `bareHideTableExtraMultipleAction`       | `boolean`                                                                             | Hides the extra multiple-action button in table view                                            |
+
+### Extended Tab
+
+| Name               | Type                                                                | Description                                                 |
+| ------------------ | ------------------------------------------------------------------- | ----------------------------------------------------------- |
+| `name`             | `string`                                                            | Tab label                                                   |
+| `type`             | `"read" \| "list"`                                                  | `"list"` shows all data; `"read"` shows the selected record |
+| `viewType`         | `"grid" \| "list" \| "iframe" \| "calendar" \| "feeds" \| "kanban"` | View layout for this tab                                    |
+| `viewImage`        | `string`                                                            | Column ID of an `image` field to display in grid/list view  |
+| `src`              | `string`                                                            | URL for iframe tabs                                         |
+| `calendarSettings` | `CalendarSettings`                                                  | See Calendar Settings below                                 |
+| `feedsSettings`    | `FeedsSettings`                                                     | See Feeds Settings below                                    |
+| `kanbanSettings`   | `KanbanSettings`                                                    | See Kanban Settings below                                   |
+
+### Additional Query
+
+| Name                             | Type                                                                          | Description                                       |
+| -------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------- |
+| `type`                           | `"search" \| "reference" \| "listReference" \| "list" \| "range" \| "person"` | Filter type                                       |
+| `value`                          | `string`                                                                      | Column ID to filter on                            |
+| `defaultValue`                   | `any`                                                                         | Initial filter value                              |
+| `filterLabel`                    | `string`                                                                      | Overrides the filter control label                |
+| `options`                        | `string[]`                                                                    | Option list for `type="list"`                     |
+| `spaceId`                        | `string`                                                                      | Space ID for `type="reference"`                   |
+| `label`                          | `string`                                                                      | Reference label for `type="reference"`            |
+| `referenceQuery`                 | `Query[]`                                                                     | Additional queries for `type="reference"`         |
+| `selectInputCloseOnClickOutside` | `boolean`                                                                     | Refer to Select component's `closeOnClickOutside` |
+
+### Calendar Settings
+
+| Name               | Type                 | Description                                                      |
+| ------------------ | -------------------- | ---------------------------------------------------------------- |
+| `title`            | `string`             | Column ID for event title                                        |
+| `startDate`        | `string`             | Column ID for event start date                                   |
+| `endDate`          | `string`             | Column ID for event end date                                     |
+| `defaultStartDate` | `Date`               | Default calendar start date                                      |
+| `customView`       | `CalendarCustomView` | Custom calendar view config                                      |
+| `groupId`          | `string`             | Column ID — events with the same value share a background colour |
+| `groupColor`       | `Color[]`            | Background colours for groups                                    |
+| `customHeader`     | `string`             | Custom title replacing the default calendar header               |
+
+### Feeds Settings
+
+| Name              | Type                                                                      | Description                                                                            |
+| ----------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `title`           | `string`                                                                  | Column ID for feed item title                                                          |
+| `content`         | `string`                                                                  | Column ID for feed item content                                                        |
+| `desc`            | `string`                                                                  | Column ID for the right-corner element                                                 |
+| `icon`            | `string`                                                                  | Heroicon name e.g. `"HeartIcon"`                                                       |
+| `iconClass`       | `string`                                                                  | Tailwind class for the icon                                                            |
+| `customFeedsData` | `(data, prettierData) => { id, title, content, desc, iconClass, icon }[]` | Fully custom feed data renderer. When provided and non-empty, overrides `title`/`desc` |
+
+### Kanban Settings
+
+| Name            | Type                          | Description                                            |
+| --------------- | ----------------------------- | ------------------------------------------------------ |
+| `title`         | `string`                      | Column ID for kanban card title                        |
+| `groupCluster`  | `{ [key: string]: string }[]` | Group cluster config for kanban columns                |
+| `useColumnName` | `boolean`                     | Shows column name instead of column ID on cards        |
+| `query`         | `Query[]`                     | Additional queries to filter and organise kanban cards |
+
+### Map Settings
+
+| Name      | Type     | Description                                |
+| --------- | -------- | ------------------------------------------ |
+| `title`   | `string` | Column ID for map marker info window title |
+| `address` | `string` | Column ID for marker coordinates           |
+| `group`   | `string` | Column ID to group markers by colour       |