blixify-ui-web-mcp 0.1.72 → 0.1.76

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

@@ -0,0 +1,334 @@
+import { Menu, Transition } from "@headlessui/react";
+import axios from "axios";
+import MockAdapter from "axios-mock-adapter";
+import Papa from "papaparse";
+import React, { useEffect, useMemo, useState } from "react";
+import { ButtonGroup } from "../../action/buttonGroup";
+import { DataTemplate as DataTemplateImpl } from ".";
+import { handleApplyStoryQueries } from "../dataWrapper/storyBackend.fixtures";
+import { DataStructure } from "./model";
+
+const meta = { title: "Data/Data Template" };
+export default meta;
+
+// INFO: its own endpoint, so the mock never answers for another story
+const DEMO_ENDPOINT = "https://dtw-read-drawer-demo.local/api";
+const DEMO_COLLECTION = "demo-read-drawer-records";
+const COMMENTS_COLLECTION = `${DEMO_COLLECTION}-comments`;
+const LOGS_COLLECTION = `${DEMO_COLLECTION}-logs`;
+const CURRENT_USER = "alice";
+const STAGES = ["New", "In Progress", "Done"];
+const OWNERS = ["Alice", "Ben", "Chitra", "Dan"];
+
+const DEMO_SCHEMA: DataStructure[] = [
+  { id: "name", name: "Record", type: "string" },
+  { id: "stage", name: "Stage", type: "list", listSelection: STAGES },
+  { id: "owner", name: "Owner", type: "string" },
+  { id: "summary", name: "Summary", type: "string" },
+];
+
+const DRAWER_TOGGLE = [
+  { id: "drawer", name: "Read drawer" },
+  { id: "page", name: "No drawer" },
+];
+const ROLE_TOGGLE = [
+  { id: "editor", name: "Can update" },
+  { id: "viewer", name: "Viewer" },
+];
+const COMMENTS_TOGGLE = [
+  { id: "on", name: "Comments" },
+  { id: "off", name: "No comments" },
+];
+const LAYOUT_TOGGLE = [
+  { id: "desktop", name: "Desktop" },
+  { id: "mobile", name: "Mobile" },
+];
+
+const demoDevSettings: any = {
+  server: "mongoServer",
+  dbEndpoint: DEMO_ENDPOINT,
+  dbAPIToken: "",
+  dbUserToken: "",
+  schemaEndpoint: DEMO_ENDPOINT,
+  schemaEndpointToken: "",
+  imageEndpoint: "https://placehold.co/600x400/e2e8f0/475569.png?text=",
+  uploadEndpoint: "",
+  organisationMembers: [
+    { key: "alice", label: "Alice Tan" },
+    { key: "ben", label: "Ben Wong" },
+  ],
+};
+
+// INFO: a few records carry comments so the bubble's count shows on some rows
+// and not others
+const COMMENT_COUNTS: { [id: string]: number } = {
+  "rec-01": 3,
+  "rec-02": 1,
+  "rec-04": 12,
+  "rec-07": 120,
+};
+
+const renderDemoComments = () =>
+  Object.entries(COMMENT_COUNTS).flatMap(([itemId, count]) =>
+    Array.from({ length: Math.min(count, 5) }, (_, index) => ({
+      _id: `${itemId}-comment-${index + 1}`,
+      collectionId: DEMO_COLLECTION,
+      itemId,
+      userId: index % 2 === 0 ? "ben" : "alice",
+      comment: `Comment ${index + 1} on ${itemId}`,
+      createdAt: new Date(Date.UTC(2026, 10, 1, 9, index)).toISOString(),
+    })),
+  );
+
+const renderDemoRecords = () =>
+  Array.from({ length: 12 }, (_, index) => {
+    const number = String(index + 1).padStart(2, "0");
+    return {
+      _id: `rec-${number}`,
+      name: `Record ${number}`,
+      stage: STAGES[index % STAGES.length],
+      owner: OWNERS[index % OWNERS.length],
+      summary: `Summary for record ${number}`,
+    };
+  });
+
+const handleInstallDemoMock = (
+  store: any[],
+  activity: { [collection: string]: any[] },
+) => {
+  const mock = new MockAdapter(axios, {
+    onNoMatch: "passthrough",
+    delayResponse: 150,
+  });
+  const renderUrl = (type: string) =>
+    `${DEMO_ENDPOINT}/${DEMO_COLLECTION}/${type}`;
+  const handleParseBody = (config: any) => {
+    try {
+      return JSON.parse(config?.data ?? "{}");
+    } catch (err) {
+      return {};
+    }
+  };
+
+  mock
+    .onPost(renderUrl("list"))
+    .reply(() => [200, { data: store, count: store.length }]);
+  mock.onPost(renderUrl("get")).reply((config) => {
+    const body = handleParseBody(config);
+    return [200, { data: store.find((each) => each._id === body.id) ?? null }];
+  });
+  mock.onPost(renderUrl("update")).reply((config) => {
+    const body = handleParseBody(config);
+    const index = store.findIndex((each) => each._id === body.id);
+    if (index >= 0) store[index] = { ...store[index], ...body.data };
+    return [200, { data: body.id }];
+  });
+  mock
+    .onPost(
+      new RegExp(
+        `^${DEMO_ENDPOINT}/(${COMMENTS_COLLECTION}|${LOGS_COLLECTION})/[a-z]+$`,
+      ),
+    )
+    .reply((config) => {
+      const [collection, action] = (config.url ?? "").split("/").slice(-2);
+      const body = handleParseBody(config);
+      const rows = activity[collection];
+      if (action === "list") {
+        const data = handleApplyStoryQueries(rows, body.query).sort(
+          (a: any, b: any) =>
+            String(b.createdAt ?? "").localeCompare(String(a.createdAt ?? "")),
+        );
+        const cursor = body.cursor ?? 0;
+        return [
+          200,
+          {
+            data: data.slice(cursor, cursor + (body.limit ?? 10)),
+            count: data.length,
+          },
+        ];
+      }
+      if (action === "get")
+        return [200, { data: rows.find((row) => row._id === body.id) }];
+      if (action === "create") rows.push(body.data);
+      if (action === "update") {
+        const index = rows.findIndex((row) => row._id === body.id);
+        if (index >= 0) rows[index] = { ...rows[index], ...body.data };
+      }
+      if (action === "delete") {
+        const index = rows.findIndex((row) => row._id === body.id);
+        if (index >= 0) rows.splice(index, 1);
+      }
+      return [200, { success: true }];
+    });
+  // INFO: the tab bar waits on this lookup
+  mock
+    .onPost(`${DEMO_ENDPOINT}/spaces/list`)
+    .reply(200, { data: [], count: 0 });
+
+  return mock;
+};
+
+const ReadDrawerDemo = () => {
+  const [typeParam, setTypeParam] = useState<"list" | "read" | "update">(
+    "list",
+  );
+  const [dataId, setDataId] = useState<string>("");
+  const [drawerMode, setDrawerMode] = useState<"drawer" | "page">("drawer");
+  const [role, setRole] = useState<"editor" | "viewer">("editor");
+  const [comments, setComments] = useState<"on" | "off">("on");
+  const [layout, setLayout] = useState<"desktop" | "mobile">("desktop");
+  const [isMockReady, setIsMockReady] = useState(false);
+
+  const store = useMemo(() => renderDemoRecords(), []);
+  const activity = useMemo(
+    () => ({
+      [COMMENTS_COLLECTION]: renderDemoComments(),
+      [LOGS_COLLECTION]: [] as any[],
+    }),
+    [],
+  );
+  const hasComments = comments === "on";
+  const hasDrawer = drawerMode === "drawer";
+  const canUpdate = role === "editor";
+  const isMobile = layout === "mobile";
+
+  // INFO: in an effect so it survives StrictMode's double mount
+  useEffect(() => {
+    const mock = handleInstallDemoMock(store, activity);
+    setIsMockReady(true);
+    return () => {
+      mock.restore();
+      setIsMockReady(false);
+    };
+  }, [store, activity]);
+
+  const handleNavigate = (type: string, id?: string) => {
+    setTypeParam(type as "list" | "read" | "update");
+    setDataId(id ?? "");
+  };
+
+  return (
+    <div className="w-full">
+      <div className="mb-4 flex flex-wrap items-center gap-3">
+        <ButtonGroup
+          selection={DRAWER_TOGGLE}
+          selectedId={drawerMode}
+          variant="tag"
+          size="small"
+          onClick={(id) => {
+            setDrawerMode(id as "drawer" | "page");
+            handleNavigate("list");
+          }}
+        />
+        <ButtonGroup
+          selection={ROLE_TOGGLE}
+          selectedId={role}
+          variant="tag"
+          size="small"
+          onClick={(id) => setRole(id as "editor" | "viewer")}
+        />
+        <ButtonGroup
+          selection={COMMENTS_TOGGLE}
+          selectedId={comments}
+          variant="tag"
+          size="small"
+          onClick={(id) => setComments(id as "on" | "off")}
+        />
+        <ButtonGroup
+          selection={LAYOUT_TOGGLE}
+          selectedId={layout}
+          variant="tag"
+          size="small"
+          onClick={(id) => setLayout(id as "desktop" | "mobile")}
+        />
+        {typeParam !== "list" && !hasDrawer && (
+          <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={() => handleNavigate("list")}
+          >
+            ← Back to list
+          </button>
+        )}
+      </div>
+      <div className={isMobile ? "mx-auto max-w-sm" : "w-full"}>
+        {isMockReady && (
+          <DataTemplateImpl
+            key={`${drawerMode}-${role}-${comments}-${layout}`}
+            title="Read Drawer"
+            description="Offline records"
+            type={typeParam}
+            id={dataId}
+            collectionId={DEMO_COLLECTION}
+            model={DEMO_SCHEMA}
+            localURLEndpoint=""
+            devSettings={demoDevSettings}
+            lib={{ axios, Menu, Transition, papaParser: Papa }}
+            organise={{
+              handleNavigate,
+              // INFO: counted from the live comments, so a comment added in
+              // the panel shows on the row once the list reloads
+              onFetchCommentCounts: hasComments
+                ? async (ids: string[]) =>
+                    Object.fromEntries(
+                      ids.map((id) => [
+                        id,
+                        id in COMMENT_COUNTS && COMMENT_COUNTS[id] > 5
+                          ? COMMENT_COUNTS[id]
+                          : activity[COMMENTS_COLLECTION].filter(
+                              (row) => row.itemId === id,
+                            ).length,
+                      ]),
+                    )
+                : undefined,
+            }}
+            edit={{
+              allEditable: canUpdate,
+              listEditable: canUpdate,
+              disabledUpdate: !canUpdate,
+              activityLog: hasComments
+                ? {
+                    enableComments: true,
+                    commentCollectionId: COMMENTS_COLLECTION,
+                    enableLogs: true,
+                    logsCollectionId: LOGS_COLLECTION,
+                    currentUserId: CURRENT_USER,
+                  }
+                : undefined,
+            }}
+            bareSettings={{
+              bareNewDTW: true,
+              bareFormDrawer: hasDrawer,
+              bareListMobileView: isMobile,
+              bareUpdateMobileView: isMobile,
+            }}
+            viewSettings={
+              hasDrawer
+                ? { readDrawer: { anchor: "responsive", maxWidth: "3xl" } }
+                : undefined
+            }
+          />
+        )}
+      </div>
+    </div>
+  );
+};
+
+export const ReadDrawerRowAction = () => (
+  <div className="w-full">
+    <div className="font-semibold mb-1 text-gray-900">
+      Data Template — row action beside the title
+    </div>
+    <div className="text-sm mb-4 text-gray-600">
+      Hover a table row to show the chevron beside its title, which opens the
+      record's read view for anyone who can see it — in the drawer with a read
+      drawer, as a page with No drawer. Then come two divided columns: the
+      pencil, which opens the edit form, only for people who can update, and the
+      comment bubble, with a count on rows that have any (12 and 120 show the
+      two-digit and 99+ badges). Drag the Record column narrower to see its
+      floor. Mobile cards open from the card, so they carry the pencil and the
+      bubble but no chevron.
+    </div>
+    <ReadDrawerDemo />
+  </div>
+);

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

@@ -1368,3 +1368,165 @@ export const GroupByPagePagination = () => (
     <GroupByScrollPaginationDemo paginationType="page" />
   </div>
 );
+
+const DEFAULTS_COLLECTION = "demo-workspace-defaults";
+const DEFAULTS_MEMBERS = [
+  { key: "u1", label: "Aisha Rahman" },
+  { key: "u2", label: "Ben Tan" },
+];
+const DEFAULTS_SCHEMA: DataStructure[] = [
+  { id: "name", name: "Name", type: "string" },
+  {
+    id: "stage",
+    name: "Stage",
+    type: "list",
+    listSelection: ["New", "Quoted", "Won"],
+    optional: true,
+  },
+  {
+    id: "status",
+    name: "Status",
+    type: "list",
+    listSelection: ["Open", "Waiting", "Closed"],
+    optional: true,
+  },
+  { id: "owner", name: "Owner", type: "person", optional: true },
+  { id: "amount", name: "Amount", type: "number", optional: true },
+  { id: "due", name: "Due", type: "date", optional: true },
+];
+
+const handleInstallDefaultsMock = (store: any[]) => {
+  const mock = new MockAdapter(axios, { onNoMatch: "passthrough" });
+  const renderUrl = (type: string) =>
+    `${DEMO_ENDPOINT}/${DEFAULTS_COLLECTION}/${type}`;
+  const handleParse = (config: any) => JSON.parse(config?.data ?? "{}");
+  const handleMatch = (row: any, query: any[]) =>
+    (query ?? []).every((eachQuery: any) => {
+      const value = row[eachQuery.queryId];
+      const handleIn = (list: any[]) =>
+        list.some((each) => (each === null ? value == null : each === value));
+      if (eachQuery.type === "=") return value === eachQuery.value;
+      if (eachQuery.type === "in") return handleIn(eachQuery.value);
+      if (eachQuery.type === "!in") return !handleIn(eachQuery.value);
+      return true;
+    });
+  mock.onPost(renderUrl("list")).reply((config) => {
+    const body = handleParse(config);
+    const rows = store.filter((each) => handleMatch(each, body.query));
+    // INFO: a grouped sum, in the shape the list endpoint answers one with
+    if (body.aggregate?.type === "sum") {
+      const totals: { [key: string]: any } = {};
+      rows.forEach((each) => {
+        const key = each[body.aggregate.groupId] ?? null;
+        const total = (totals[String(key)] = totals[String(key)] ?? {
+          _id: key,
+          value: 0,
+        });
+        total.value += Number(each[body.aggregate.queryId]) || 0;
+      });
+      return [200, { data: [{ _id: "range", value: Object.values(totals) }] }];
+    }
+    return [200, { data: rows, count: rows.length }];
+  });
+  mock.onPost(renderUrl("create")).reply((config) => {
+    const row = { ...handleParse(config).data, _id: `r${store.length + 1}` };
+    store.push(row);
+    (window as any).__defaultsWrites = [
+      ...((window as any).__defaultsWrites ?? []),
+      { type: "create", data: row },
+    ];
+    return [200, { success: true, data: row }];
+  });
+  mock.onPost(renderUrl("update")).reply((config) => {
+    const body = handleParse(config);
+    const row = store.find((each) => each._id === body.id);
+    if (row) Object.assign(row, body.data);
+    (window as any).__defaultsWrites = [
+      ...((window as any).__defaultsWrites ?? []),
+      { type: "update", id: body.id, data: body.data },
+    ];
+    return [200, { success: true }];
+  });
+  mock
+    .onPost(`${DEMO_ENDPOINT}/spaces/list`)
+    .reply(200, { data: [], count: 0 });
+  return mock;
+};
+
+const WorkspaceDefaultsDemo = () => {
+  const store = React.useMemo(
+    () => [
+      {
+        _id: "r1",
+        name: "Rooftop survey",
+        stage: "New",
+        status: "Open",
+        owner: "u1",
+        amount: 1200,
+        due: new Date(Date.now() - 2 * 86400000).toISOString(),
+      },
+      {
+        _id: "r2",
+        name: "Inverter quote",
+        stage: "Quoted",
+        status: "Waiting",
+        owner: "u2",
+        amount: 5400.5,
+        due: new Date().toISOString(),
+      },
+      {
+        _id: "r3",
+        name: "Panel install",
+        stage: "Won",
+        status: "Closed",
+        owner: "u1",
+        amount: 18000,
+      },
+    ],
+    [],
+  );
+  React.useMemo(() => handleInstallDefaultsMock(store), [store]);
+
+  return (
+    <DataTemplateImpl
+      title="Workspace defaults"
+      description=""
+      type="list"
+      collectionId={DEFAULTS_COLLECTION}
+      model={DEFAULTS_SCHEMA}
+      localURLEndpoint=""
+      devSettings={{ ...demoDevSettings, organisationMembers: DEFAULTS_MEMBERS }}
+      lib={{ axios, Menu, Transition, papaParser: Papa }}
+      edit={{
+        allEditable: true,
+        listAddable: true,
+        activityLog: {
+          enableLogs: true,
+          logsCollectionId: `${DEFAULTS_COLLECTION}-logs`,
+          currentUserId: "u1",
+        },
+      }}
+      bareSettings={{ bareNewDTW: true }}
+      organise={{
+        groupBy: "stage",
+        showGroupByFeature: true,
+        dateWarnings: true,
+        datasheetDefaults: true,
+        renderGroupByOptions: () => [
+          { key: "stage", label: "Stage" },
+          { key: "owner", label: "Owner" },
+        ],
+        onFetchCommentCounts: async () => ({ r1: 3 }),
+      }}
+    />
+  );
+};
+
+export const WorkspaceDefaults = () => (
+  <div className="w-full">
+    <div className="font-semibold mb-1 text-gray-900">
+      Data Template — workspace defaults
+    </div>
+    <WorkspaceDefaultsDemo />
+  </div>
+);

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

@@ -242,14 +242,14 @@ const res = await query.call({
 
 ## Query
 
-| Param            | Type                                                                                      | Description                                 | Optional                 |
-| ---------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------- | ------------------------ |
-| `type`           | `search \| = \| != \| > \| < \| >< \| in \| !in \| exists \| elemMatch \| >size \| <size` | Operator                                    |                          |
-| `value`          | `any`                                                                                     | Filter value (array for `><` and `in`)      |                          |
-| `queryId`        | `string`                                                                                  | Field name                                  | Required except `search` |
-| `searchIds`      | `string[]`                                                                                | Fields to search across                     | Required for `search`    |
-| `orQuery`        | `boolean`                                                                                 | Use OR instead of AND                       | ✓                        |
-| `orQueryGroupId` | `string`                                                                                  | Group OR conditions with AND between groups | ✓                        |
+| Param            | Type                                                                                      | Description                            | Optional                 |
+| ---------------- | ----------------------------------------------------------------------------------------- | -------------------------------------- | ------------------------ |
+| `type`           | `search \| = \| != \| > \| < \| >< \| in \| !in \| exists \| elemMatch \| >size \| <size` | Operator                               |                          |
+| `value`          | `any`                                                                                     | Filter value (array for `><` and `in`) |                          |
+| `queryId`        | `string`                                                                                  | Field name                             | Required except `search` |
+| `searchIds`      | `string[]`                                                                                | Fields to search across                | Required for `search`    |
+| `orQuery`        | `boolean`                                                                                 | Use OR instead of AND                  | ✓                        |
+| `orQueryGroupId` | `string`                                                                                  | AND inside a block, OR between blocks  | ✓                        |
 
 ## Aggregate
 

package/lib/components/display/modal/README.md

@@ -44,3 +44,4 @@ import { Overlay } from "blixify-ui-web/components/display/overlay";
 | `bgColor`        | `string`        | `bg-white` | Tailwind background class for the panel in light mode                                               |
 | `darkMode`       | `boolean`       | `false`    | Switches the panel, text and icons to the dark palette                                              |
 | `darkModeBg`     | `string`        | `bg-gray-900` | Tailwind background class for the panel when `darkMode` is on                                    |
+| `zIndex`         | `string`        | `z-40`     | Tailwind z-index class for the dialog. Pass a higher one for a modal opened from a layer drawn above z-40, such as the activity drawer (z-50) |

package/lib/components/display/newList/README.md

@@ -41,6 +41,36 @@ The legacy `List` renders **every** extra key on an item. `NewList` renders only
 <NewList list={tasks} extraKeys={["details", "activity"]} />
 ```
 
+## Compact rows
+
+Set `compact` on an item to draw it as a two-line row, like a mail inbox: the title with a pill and a short date on the first line, one grey line under it, and an arrow that opens the rest. Every compact row is the same height. An item without `compact` keeps the layout above, so existing keys such as an `extraKeys` "details" keep their meaning.
+
+| `compact` field | Rendered as                                                                   |
+| --------------- | ----------------------------------------------------------------------------- |
+| `subtitle`      | One grey line under the title, cut to fit                                     |
+| `details`       | Shown under the row when its arrow is tapped; the arrow does not open the row |
+| `badge`         | A pill leading the second line. Without it, the item's `tags` / `tag`         |
+| `trailing`      | The right end of the title line. Without it, the item's `date`                |
+
+```tsx
+<NewList
+  list={[
+    {
+      id: "a1",
+      title: "Ahmad Solar House",
+      compact: {
+        badge: <Tag tagText="Done" color="green" size="small" />,
+        trailing: "12 Nov",
+        subtitle: "Selangor · RM 12,400",
+        details: <DetailList title="" list={fields} size="compact" />,
+      },
+    },
+  ]}
+/>
+```
+
+`NewListCompactRow` (`newList/compactRow`) is the row on its own; the new table draws its phone rows with it. `handlePickListRowFields` (`newList/listRowFields`) picks a row's fields from a column list in view order: the first date column for `trailing`, the first list column for `badge`, and the next two columns that hold something for `subtitle`. Pictures, files, drawings, long text, nested lists, buttons, timers and star ratings are left off the second line. `handleFormatListRowDate` writes a date as "12 Nov", adding the year outside the current one.
+
 ## Date
 
 | `date` value                                                   | Output                                                                                    |

package/lib/components/display/newTable/README.md

@@ -1,12 +1,14 @@
 # NewTable
 
-Tabular display with a List-shaped mobile breakpoint. The architectural key: **`mobileView=true` delegates row rendering to `NewListRow`**, so the same tap-rhythm and avatar/title/trailing geometry shows up across NewList, NewFeeds, and NewTable mobile.
+Tabular display with a List-shaped mobile breakpoint. With `mobileView=true` each row is a two-line `NewListCompactRow`, like a mail inbox: the title and a short date, then a pill and a grey line of key values, and an arrow that opens every field. Tapping the row opens the record (`onClickRow` / `newTabUrl`), the checkbox ticks it without opening it, and groups draw the same foldable headers, counts and per-group paging as the computer layout. Rows are drawn again only when their own data changes, and a group with 120 or more loaded rows draws only the rows near the screen.
+
+Without `mobileTooltip.titleAdjacent`, the view's column order picks a row's fields (`handlePickListRowFields`): the first list column is the pill, the first date column the date, and the next two columns that hold something the grey line.
 
 ## Row activity
 
 Pass `onRowActivity={(id) => ...}` to show a keyboard-accessible chat button at the right of the first visible cell (beside the title on mobile cards). It stops row navigation and does not enter inline editing. When no left pins are configured, the first ungrouped column is pinned automatically; existing pin configurations are preserved. DTW wires this callback automatically when `edit.activityLog` is enabled with `bareNewDTW`.
 
-Pass `onRowEdit={(id) => ...}` as well to put an edit pencil before the chat button, at the same size and colour. Both sit over the cell's right padding, so the row does not grow. DTW passes it only when the user can update records (`edit.allEditable`) and opens the record's edit form with `handleNavigate("update", id, "general")`.
+Pass `onRowEdit={(id) => ...}` as well to put an edit pencil before the chat button, at the same size and colour, and `onRowOpen={(id) => ...}` to put a chevron beside the title. The pencil and the chat button each sit in their own divided strip at the title cell's right edge, like columns of their own, with the chevron just left of them. The chevron shows only when the row is hovered or the chevron is focused, and always on a touch screen, which cannot hover. While it shows, the title cell's padding grows to take it, so it never covers the title or its inline editor. All of them sit over the cell's right padding, so the row does not grow. While the title carries these actions, its column cannot be dragged — or set, or saved — narrower than its left padding, the actions' room (with the chevron's) and 48px of title; other columns keep the 80px floor. DTW passes the pencil only when the user can update records and opens the edit form with `handleNavigate("update", id, "general")`. It passes the chevron to anyone who can see the record, when `organise.handleNavigate` is set, and opens the read view with `handleNavigate("read", id, "general")` — in the drawer when `viewSettings.readDrawer` is set, as a page otherwise. An editable title cell is hard to click open, so the chevron is the sure way in. Mobile cards open from the card, so they show the pencil and the chat button but no chevron.
 
 ## Adding a row
 
@@ -26,18 +28,18 @@ Columns flagged `hideOnMobile` are dropped from the mobile rendering entirely.
 
 ## Mobile tooltip (`mobileTooltip`)
 
-With `mobileView`, `mobileTooltip` adds row data to the collapsed row and to a hover card. Through `DataTemplate` it is `bareSettings.bareMobileTooltip`, which applies when `bareNewDTW` and `bareListMobileView` are both on.
+With `mobileView`, `mobileTooltip` picks what the row shows, in place of the column order, and adds a hover card. Through `DataTemplate` it is `bareSettings.bareMobileTooltip`, which applies when `bareNewDTW` and `bareListMobileView` are both on.
 
-| Key                         | Type                       | Shows                                                                                                                                                                                                                  |
-| --------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `titleAdjacent.tagKey`      | `string`                   | That row field's value as a Tag next to the row title                                                                                                                                                                  |
-| `titleAdjacent.tagColor`    | `Record<string, TagColor>` | The Tag colour for each value                                                                                                                                                                                          |
-| `titleAdjacent.trailingKey` | `string`                   | That row field's value as trailing text, e.g. a price                                                                                                                                                                  |
-| `titleAdjacent.summaryKeys` | `string[]`                 | A second line under the title while the row is collapsed, as label + value pairs. Labels come from the column titles; a dotted key (`shippingAddress.name`) falls back to its parent column's title. Empty values are skipped. Tapping the line expands the row |
-| `tooltip.imageKey`          | `string`                   | The image URL field shown in the hover card                                                                                                                                                                            |
-| `tooltip.summaryKeys`       | `string[]`                 | Label + value pairs in the hover card                                                                                                                                                                                  |
-| `tooltip.tagKeys`           | `string[]`                 | Tag pills in the hover card                                                                                                                                                                                            |
-| `tooltip.tagColors`         | `Record<string, TagColor>` | The Tag colour for each value                                                                                                                                                                                          |
+| Key                         | Type                       | Shows                                                                                                                                                                                                                                                                                                                                    |
+| --------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `titleAdjacent.tagKey`      | `string`                   | That row field's value as a Tag next to the row title                                                                                                                                                                                                                                                                                    |
+| `titleAdjacent.tagColor`    | `Record<string, TagColor>` | The Tag colour for each value                                                                                                                                                                                                                                                                                                            |
+| `titleAdjacent.trailingKey` | `string`                   | That row field's value at the right of the title line, e.g. a price. Without it the row shows no date                                                                                                                                                                                                                                    |
+| `titleAdjacent.summaryKeys` | `string[]`                 | The grey line under the title, as "Label: value" pairs joined with " · ". Labels come from the column titles; a dotted key (`shippingAddress.name`) falls back to its parent column's title. Empty values, hidden columns, the title and the `tagKey` column are skipped. Without it, and with `titleAdjacent` set, the line is left out |
+| `tooltip.imageKey`          | `string`                   | The image URL field shown in the hover card                                                                                                                                                                                                                                                                                              |
+| `tooltip.summaryKeys`       | `string[]`                 | Label + value pairs in the hover card                                                                                                                                                                                                                                                                                                    |
+| `tooltip.tagKeys`           | `string[]`                 | Tag pills in the hover card                                                                                                                                                                                                                                                                                                              |
+| `tooltip.tagColors`         | `Record<string, TagColor>` | The Tag colour for each value                                                                                                                                                                                                                                                                                                            |
 
 ```tsx
 <NewTable
@@ -117,8 +119,11 @@ Types that need more than a name and a type are completed in the popup:
 | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `reference`, `listReference`, `referenceSelection` | endpoint and label, from `renderReferenceSpaceOptions` / `renderReferenceLabelOptions` — required, since a reference with no target resolves nothing |
 | `list`, `multipleList`                             | options, as a comma-separated line                                                                                                                   |
+| `lookup`                                           | a `reference` or `listReference` column of this table, then a column of the space it links to, from `renderReferenceLabelOptions(spaceId, true)`; `lookup`, `password` and `button` columns are left out. Offered only with `renderReferenceLabelOptions`. Saved as `{ type: "lookup", referenceFieldId, lookupFieldId }`, always optional and read-only |
 | `image`, `file`, `multipleImage`, `multipleFile`   | nothing — the consumer fills the storage path from its own settings                                                                                  |
 
+A `reference` or `listReference` column has a solid line under its header, and a `lookup` column (or a column drawn from one, carrying `lookupFieldId`) a dashed one, both in the primary colour.
+
 A **Required** toggle sets the field's `optional` flag. New columns default to
 optional, since the rows already in the table have no value for one the moment it
 is added — ticking it says so.
@@ -206,10 +211,10 @@ With `editable.active` most columns edit in the cell (`supportedInlineEditList`)
 
 `groups` draws rows as coloured, collapsible bands inside the one table. DataTemplate builds them from `organise.groupBy`; a consumer using NewTable on its own passes them directly.
 
-| Prop                 | Type                                                                                  | Behavior                                                                                                                                       |
-| -------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| `groups`             | `{ id, title, colour?, rowIds, count? }[]`                                            | One band per entry; `rowIds` reference row ids. `count` is the band's real total, shown in its header instead of the rows it holds |
-| `onGroupLoadMore`    | `(groupId: string) => void`                                                           | Scroll paging: fired when the bottom of a band scrolls into view, so that band loads its next rows                                              |
-| `onGroupPageChange`  | `(groupId: string, page: number) => void`                                             | Page paging: each band gets the list footer (numbered pages, chevrons, go-to-page) under its rows, scoped to that band. 0-based page            |
-| `groupLoadingStatus` | `{ [groupId]: { loadingMore?, exhausted?, page?, size?, fetched? } }`                 | Per band: a spinner while a page loads; `exhausted` removes the scroll sentinel; `page` and `size` drive the band pager once `fetched`          |
-
+| Prop                 | Type                                                                  | Behavior                                                                                                                               |
+| -------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `groups`             | `{ id, title, colour?, rowIds, count? }[]`                            | One band per entry; `rowIds` reference row ids. `count` is the band's real total, shown in its header instead of the rows it holds     |
+| `groupColumnKey`     | `string`                                                              | The column the groups are built from. Phone rows leave it off, since the group header shows it. Group headers show on a phone while their rows load |
+| `onGroupLoadMore`    | `(groupId: string) => void`                                           | Scroll paging: fired when the bottom of a band scrolls into view, so that band loads its next rows                                     |
+| `onGroupPageChange`  | `(groupId: string, page: number) => void`                             | Page paging: each band gets the list footer (numbered pages, chevrons, go-to-page) under its rows, scoped to that band. 0-based page   |
+| `groupLoadingStatus` | `{ [groupId]: { loadingMore?, exhausted?, page?, size?, fetched? } }` | Per band: a spinner while a page loads; `exhausted` removes the scroll sentinel; `page` and `size` drive the band pager once `fetched` |