blixify-ui-web-mcp 0.1.44 → 0.1.46

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

@@ -679,6 +679,18 @@ Editors (`edit.allEditable`) get add, edit, remove and move on each chart; add i
 
 ---
 
+### Related records
+
+Set `organise.showRelatedTab` to give the read view a tab for each other space with a `reference` or `listReference` column pointing at this record, beside Card View and named with its row count (e.g. `Orders (3)`). It is off by default: it shows other spaces' rows, and opening a record then runs one schema query plus one single-row count per referencing column. Spaces are found the same way the delete check finds them: through `devSettings.schemaEndpoint` (the workspace's datasheets, which needs the `space` prop) or `bareSettings.bareReferenceDel`. Only spaces with matching rows get a tab.
+
+A tab shows that space as a read-only list Data Template (table, search, paging), filtered with `=` for a reference or `in` for a list reference. Picking a row opens it in the same tab with a Back button, so the record's own tabs stay on screen.
+
+```tsx
+organise={{ viewId, handleNavigate, showRelatedTab: true }}
+```
+
+---
+
 ### With search and filter
 
 Use `organise.additionalQuery` to add filter controls above the list. Each entry maps to a filter UI control.
@@ -1145,6 +1157,11 @@ Which field types can be edited from the list table, and how. Types not listed u
 | `persistKey`                  | `string`                                                                    | Keeps a separate saved view state for this instance: the storage key becomes `blixify-dtw-persist-<collectionId>-<persistKey>`. Saved state is read once, on mount, so give the component a React `key` that changes with `persistKey`                                                                               |
 | `savedViews`                  | `boolean`                                                                   | Shows a row of view tags under the tab bar: save the current filters, flex filters, sort, rows per page and columns under a name, reapply it, update it or delete it. Views belong to the tab they were saved on and are kept in `localStorage` under `blixify-dtw-views-<collectionId>[-<persistKey>][-<currentUser.userEmail>]`. Sort is held by the template while it is on, as with `persistViewState`, and applying a view calls `onChangeSort`, `onChangePagination(0)` and `bareListHandleFilter` when those change. Each write re-reads storage first, so views saved in another browser tab are kept. With `onChangeHide` / `onChangeDrag`, a view's hides and column order stay on screen only: a toggle or reorder after applying one writes back the schema's columns plus that single change |
 | `defaultSavedViews`           | `DefaultSavedView[]`                                                        | Views provided by the app (`{ id?, name, tabId?, state }`), listed before the user's own and never deleted. Without `tabId` a view is listed on every tab. A field left out of `state` is reset to its default when the view is applied. `id` must be unique; without one the view gets `default-<index>`, its position in the whole array |
+| `sharedViews`                 | `SharedSavedView[]`                                                         | Views the app stores for everyone (`{ id, name, tabId, state }`), e.g. on the record the list belongs to. Given, it replaces this browser's storage: the list shows only these, saving goes to `onChangeSharedViews`, and nothing is read from or written to `localStorage` |
+| `onChangeSharedViews`         | `(views: SharedSavedView[]) => void`                                        | Called with the whole list after a view is saved, updated or deleted, for the app to store and pass back as `sharedViews`; a second change before it comes back builds on the list just sent. The whole list is replaced each time, so two editors saving at once is last-writer-wins. Without it the app's views are read-only and “+ Save view” is hidden |
+| `defaultSavedViewId`          | `string`                                                                    | The view everyone opens on, marked ★, stored by the app. The list opens on it when no `initialSavedViewId` is given — also when it arrives after mount — unless `persistViewState` restored a state or a view was already picked. A view that no longer exists leaves the list on All. Opening on it does not call `onChangeSort` |
+| `onChangeDefaultSavedViewId`  | `(id: string \| null) => void`                                              | Gives each view a ☆ that makes it the default; the ★ on the default takes it off (`null`, the list opens on All). Deleting the default view also sends `null` |
+| `initialSavedViewId`          | `string`                                                                    | A view the list opens on, once, in place of the ★ default — e.g. a page embedding a datasheet opens it on a chosen view. A view that no longer exists, or is on another tab, leaves the list on All. Opening on it does not call `onChangeSort` |
 | `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                                                                                                                                                                                                                                                                                  |
@@ -1159,6 +1176,7 @@ Which field types can be edited from the list table, and how. Types not listed u
 | `customPaginationCount`       | `(pageDataCount: number) => void`                                           | Called after each data fetch with the actual record count. Use this to override the count shown in the pagination bar — store the value in your own state and pass it back via `customPaginationSize` on `Table`, `Grid`, `List`, or `Pagination` if needed, or use it to display a custom count elsewhere in your UI |
 | `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)                                                                                                                                                                                                                                              |
+| `showRelatedTab`              | `boolean`                                                                   | Adds a read view tab per other space whose rows reference the record. Default `false` |
 | `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                                                                                                                                                                                                                                                                   |

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

@@ -14,7 +14,7 @@ import {
   renderDemoRecords,
   TABS,
 } from "./savedViewsDemo.fixtures";
-import { buildSavedViewsKey } from "./viewStatePersistence";
+import { buildSavedViewsKey, SharedSavedView } from "./viewStatePersistence";
 
 const meta = { title: "Data/Data Template" };
 export default meta;
@@ -140,3 +140,146 @@ export const SavedViews = () => (
     <SavedViewsDemo />
   </div>
 );
+
+const SharedViewsDemo = () => {
+  const [viewId, setViewId] = useState("general");
+  const [isMockReady, setIsMockReady] = useState(false);
+  // INFO: what an app would store on the record the list belongs to
+  const [sharedViews, setSharedViews] = useState<SharedSavedView[]>([
+    {
+      id: "shared-due-last",
+      name: "Due last",
+      tabId: "general",
+      state: { sort: { sortId: "dueDate", type: "desc" } },
+    },
+  ]);
+  const [defaultSavedViewId, setDefaultSavedViewId] = useState<string | null>(
+    null,
+  );
+  const [openOn, setOpenOn] = useState("");
+  const [isEditor, setIsEditor] = useState(true);
+  // INFO: remounts the list, as reopening the page would
+  const [reloadKey, setReloadKey] = useState(0);
+  // INFO: hands the default over a moment after mount, as an app loading it
+  // from its record does
+  const [isDefaultLoading, setIsDefaultLoading] = useState(false);
+
+  const handleReloadWithLateDefault = () => {
+    setIsDefaultLoading(true);
+    setReloadKey((prev) => prev + 1);
+    setTimeout(() => setIsDefaultLoading(false), 1000);
+  };
+  const store = useMemo(() => renderDemoRecords(), []);
+
+  useEffect(() => {
+    const mock = handleInstallDemoMock(store);
+    setIsMockReady(true);
+    return () => {
+      mock.restore();
+      setIsMockReady(false);
+    };
+  }, [store]);
+
+  return (
+    <div className="w-full">
+      <div className="mb-4 flex flex-wrap items-center gap-3">
+        <ButtonGroup
+          selection={[
+            { id: "editor", name: "Editor" },
+            { id: "reader", name: "Reader" },
+          ]}
+          selectedId={isEditor ? "editor" : "reader"}
+          variant="tag"
+          size="small"
+          onClick={(id) => setIsEditor(id === "editor")}
+        />
+        <select
+          className="rounded-md border border-gray-300 px-2 py-1 text-sm"
+          value={openOn}
+          onChange={(event) => setOpenOn(event.target.value)}
+        >
+          <option value="">Open on: ★ default</option>
+          <option value="missing-view">Open on: a deleted view</option>
+          {sharedViews.map((eachView) => (
+            <option key={eachView.id} value={eachView.id}>
+              Open on: {eachView.name}
+            </option>
+          ))}
+        </select>
+        <button
+          type="button"
+          className="rounded-md border border-gray-300 bg-white px-3 py-1 text-sm text-gray-700 hover:bg-gray-50"
+          onClick={() => setReloadKey((prev) => prev + 1)}
+        >
+          Reload
+        </button>
+        <button
+          type="button"
+          className="rounded-md border border-gray-300 bg-white px-3 py-1 text-sm text-gray-700 hover:bg-gray-50"
+          onClick={handleReloadWithLateDefault}
+        >
+          Reload, default arrives late
+        </button>
+      </div>
+      {isMockReady && (
+        <DataTemplateImpl
+          key={`${openOn}-${isEditor}-${reloadKey}`}
+          title="Tasks"
+          description="40 offline records"
+          type="list"
+          collectionId={DEMO_COLLECTION}
+          model={DEMO_SCHEMA}
+          localURLEndpoint=""
+          devSettings={demoDevSettings}
+          lib={{ axios, Menu, Transition, papaParser: Papa }}
+          limit={10}
+          organise={{
+            extendedTabs: TABS,
+            viewId,
+            savedViews: true,
+            sharedViews,
+            onChangeSharedViews: isEditor ? setSharedViews : undefined,
+            defaultSavedViewId: isDefaultLoading
+              ? undefined
+              : (defaultSavedViewId ?? undefined),
+            onChangeDefaultSavedViewId: isEditor
+              ? setDefaultSavedViewId
+              : undefined,
+            initialSavedViewId: openOn || undefined,
+            handleNavigate: (type: string, _id?: string, view?: string) => {
+              if (type === "list" && view) setViewId(view);
+            },
+          }}
+          bareSettings={{ bareNewDTW: true, bareFlexFilters: true }}
+        />
+      )}
+      <pre
+        data-testid="shared-views-store"
+        className="mt-4 max-h-48 overflow-auto rounded bg-gray-50 p-3 text-xs text-gray-600"
+      >
+        {JSON.stringify({ defaultSavedViewId, views: sharedViews }, null, 2)}
+      </pre>
+    </div>
+  );
+};
+
+export const SharedSavedViews = () => (
+  <div className="w-full">
+    <div className="font-semibold mb-1 text-gray-900">
+      Data Template — views stored by the app
+    </div>
+    <div className="text-sm mb-4 text-gray-600">
+      With sharedViews, views come from the app — here story state, shown below
+      — instead of this browser, so the whole team sees the same ones. As Editor
+      (onChangeSharedViews and onChangeDefaultSavedViewId given), “+ Save view”
+      hands the list to the app, and the ☆ on a view makes it the ★ default
+      everyone opens on; ★ again takes it off, leaving All. As Reader the views
+      are used, the default shows ★, and nothing can be changed. “Open on” sets
+      initialSavedViewId, how a page embedding a datasheet opens it on a chosen
+      view; a deleted view opens on All. “Reload” remounts the list, and
+      “default arrives late” hands the ★ over a second after mount, as an app
+      loading it does.
+    </div>
+    <SharedViewsDemo />
+  </div>
+);

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

@@ -752,3 +752,275 @@ export const ChartView = () => (
     <ChartViewDemo />
   </div>
 );
+
+// INFO: a Customers space that three other datasheets point at — Orders with a
+// reference column, Support Tickets with a list reference, and Invoices whose
+// rows reference other customers only. Notes holds a text column that names
+// the space but is not a reference, which the Related tab must ignore.
+const RELATED_WORKSPACE = "demo-workspace";
+const RELATED_CUSTOMERS = "demo-customers";
+
+const RELATED_CUSTOMER_SCHEMA: DataStructure[] = [
+  { id: "name", name: "Customer", type: "string" },
+  { id: "email", name: "Email", type: "email" },
+  {
+    id: "tier",
+    name: "Tier",
+    type: "list",
+    listSelection: ["standard", "gold"],
+    listSelectionLabel: ["Standard", "Gold"],
+  },
+];
+
+const RELATED_SPACES: any[] = [
+  {
+    _id: "demo-orders",
+    name: "Orders",
+    type: "datasheet",
+    workspaceId: RELATED_WORKSPACE,
+    structure: [
+      { id: "orderNo", name: "Order No", type: "string" },
+      {
+        id: "status",
+        name: "Status",
+        type: "list",
+        listSelection: ["pending", "paid", "shipped"],
+        listSelectionLabel: ["Pending", "Paid", "Shipped"],
+      },
+      { id: "amount", name: "Amount", type: "number" },
+      { id: "createdAt", name: "Created At", type: "date" },
+      {
+        id: "customerId",
+        name: "Customer",
+        type: "reference",
+        referenceSpaceId: RELATED_CUSTOMERS,
+        referenceLabel: "name",
+      },
+    ],
+  },
+  {
+    _id: "demo-tickets",
+    name: "Support Tickets",
+    type: "datasheet",
+    workspaceId: RELATED_WORKSPACE,
+    structure: [
+      { id: "subject", name: "Subject", type: "string" },
+      {
+        id: "priority",
+        name: "Priority",
+        type: "list",
+        listSelection: ["low", "high"],
+        listSelectionLabel: ["Low", "High"],
+      },
+      { id: "openedAt", name: "Opened", type: "date" },
+      {
+        id: "customerIds",
+        name: "Customers",
+        type: "listReference",
+        referenceSpaceId: RELATED_CUSTOMERS,
+        referenceLabel: "name",
+      },
+    ],
+  },
+  {
+    _id: "demo-invoices",
+    name: "Invoices",
+    type: "datasheet",
+    workspaceId: RELATED_WORKSPACE,
+    structure: [
+      { id: "invoiceNo", name: "Invoice No", type: "string" },
+      { id: "total", name: "Total", type: "number" },
+      {
+        id: "customerId",
+        name: "Customer",
+        type: "reference",
+        referenceSpaceId: RELATED_CUSTOMERS,
+        referenceLabel: "name",
+      },
+    ],
+  },
+  {
+    _id: "demo-notes",
+    name: "Notes",
+    type: "datasheet",
+    workspaceId: RELATED_WORKSPACE,
+    structure: [
+      { id: "text", name: "Text", type: "string" },
+      {
+        id: "customerName",
+        name: "Customer Name",
+        type: "string",
+        referenceSpaceId: RELATED_CUSTOMERS,
+      },
+    ],
+  },
+];
+
+const renderRelatedRecords = (): { [collection: string]: any[] } => {
+  const day = (offset: number) =>
+    new Date(Date.UTC(2026, 9, 12 - offset, 9)).toISOString();
+  return {
+    [RELATED_CUSTOMERS]: [
+      {
+        _id: "c1",
+        name: "Northwind Traders",
+        email: "orders@northwind.example",
+        tier: "gold",
+      },
+      {
+        _id: "c2",
+        name: "Contoso Retail",
+        email: "hello@contoso.example",
+        tier: "standard",
+      },
+    ],
+    "demo-orders": [
+      ["o1", "ORD-1001", "paid", 420, 1, "c1"],
+      ["o2", "ORD-1002", "shipped", 1280, 3, "c1"],
+      ["o3", "ORD-1003", "pending", 95, 5, "c2"],
+      ["o4", "ORD-1004", "pending", 310, 6, "c1"],
+    ].map(([_id, orderNo, status, amount, ago, customerId]) => ({
+      _id,
+      orderNo,
+      status,
+      amount,
+      createdAt: day(ago as number),
+      customerId,
+    })),
+    "demo-tickets": [
+      {
+        _id: "t1",
+        subject: "Late delivery",
+        priority: "high",
+        openedAt: day(2),
+        customerIds: ["c1"],
+      },
+      {
+        _id: "t2",
+        subject: "Invoice copy",
+        priority: "low",
+        openedAt: day(4),
+        customerIds: ["c1", "c2"],
+      },
+    ],
+    "demo-invoices": [
+      { _id: "i1", invoiceNo: "INV-77", total: 95, customerId: "c2" },
+    ],
+    "demo-notes": [{ _id: "n1", text: "Call back", customerName: "c1" }],
+  };
+};
+
+const handleInstallRelatedMock = (store: { [collection: string]: any[] }) => {
+  const mock = new MockAdapter(axios, {
+    onNoMatch: "passthrough",
+    delayResponse: 120,
+  });
+  const handleParseBody = (config: any) => {
+    try {
+      return JSON.parse(config?.data ?? "{}");
+    } catch (err) {
+      return {};
+    }
+  };
+  // INFO: "=" for a reference column, "in" for a list reference — the two
+  // queries the Related tab sends
+  const handleMatch = (record: any, query: any[] = []) =>
+    query.every((eachQuery) => {
+      const value = record[eachQuery.queryId];
+      if (eachQuery.type === "=") return value === eachQuery.value;
+      if (eachQuery.type === "in") {
+        const values = Array.isArray(value) ? value : [value];
+        return values.some((eachValue) => eachQuery.value.includes(eachValue));
+      }
+      return true;
+    });
+
+  mock.onPost(`${DEMO_ENDPOINT}/spaces/list`).reply(200, {
+    data: RELATED_SPACES,
+    count: RELATED_SPACES.length,
+  });
+
+  mock.onPost(new RegExp(`${DEMO_ENDPOINT}/([^/]+)/list$`)).reply((config) => {
+    const collection = config.url?.split("/").slice(-2)[0] ?? "";
+    const body = handleParseBody(config);
+    const rows = (store[collection] ?? []).filter((eachRecord) =>
+      handleMatch(eachRecord, body.query),
+    );
+    const limit = typeof body.limit === "number" ? body.limit : 10;
+    return [200, { data: rows.slice(0, limit), count: rows.length }];
+  });
+
+  mock.onPost(new RegExp(`${DEMO_ENDPOINT}/([^/]+)/get$`)).reply((config) => {
+    const collection = config.url?.split("/").slice(-2)[0] ?? "";
+    const body = handleParseBody(config);
+    return [
+      200,
+      {
+        data:
+          (store[collection] ?? []).find(
+            (eachRecord) => eachRecord._id === body.id,
+          ) ?? null,
+      },
+    ];
+  });
+
+  return mock;
+};
+
+const RelatedRecordsDemo = () => {
+  const store = React.useMemo(() => renderRelatedRecords(), []);
+  React.useMemo(() => handleInstallRelatedMock(store), [store]);
+
+  const [typeParam, setTypeParam] = useState<"list" | "read" | "update">(
+    "read",
+  );
+  const [dataId, setDataId] = useState<string>("c1");
+  const [viewId, setViewId] = useState<string | undefined>(undefined);
+
+  return (
+    <div className="w-full">
+      <DataTemplateImpl
+        title="Customers"
+        type={typeParam}
+        id={dataId}
+        collectionId={RELATED_CUSTOMERS}
+        model={RELATED_CUSTOMER_SCHEMA}
+        localURLEndpoint=""
+        devSettings={demoDevSettings}
+        lib={{ axios, Menu, Transition, papaParser: Papa }}
+        edit={{ deleteBtn: true }}
+        space={
+          {
+            _id: RELATED_CUSTOMERS,
+            name: "Customers",
+            workspaceId: RELATED_WORKSPACE,
+          } as any
+        }
+        organise={{
+          viewId,
+          showRelatedTab: true,
+          handleNavigate: (type: string, id?: string, view?: string) => {
+            setTypeParam(type as any);
+            setDataId(id ?? "");
+            setViewId(view);
+          },
+        }}
+      />
+    </div>
+  );
+};
+
+export const RelatedRecords = () => (
+  <div className="w-full">
+    <div className="font-semibold mb-1 text-gray-900">
+      Data Template — related records
+    </div>
+    <div className="text-sm mb-4 text-gray-600">
+      The read view adds a tab for each other space whose <code>reference</code>{" "}
+      or <code>listReference</code> column points at this record. A tab lists
+      those rows; a row opens in place with Back to the list, and the record's
+      tabs stay on screen.
+    </div>
+    <RelatedRecordsDemo />
+  </div>
+);

package/package.json

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