blixify-ui-web-mcp 0.1.43 → 0.1.46

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

@@ -119,11 +119,12 @@ Custom layout via renderSettings:
 
 | Name               | Type                                            | Description                                                                                                                               |
 | ------------------ | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `type`             | `"card" \| "bar" \| "line" \| "pie" \| "radar"` | Chart type to render                                                                                                                      |
+| `type`             | `"card" \| "bar" \| "line" \| "pie" \| "radar" \| "table"` | Chart type to render. `table` lists each `query` entry with its value and, except for `avg`, a total row                     |
 | `title`            | `string`                                        | Chart title — also used as the key for internal state                                                                                     |
 | `spaceId`          | `string`                                        | The collection/space ID to query data from                                                                                                |
 | `gridSize`         | `number`                                        | Number of grid columns this chart spans                                                                                                   |
 | `query`            | `Query[]`                                       | Data series definitions. Each query entry produces one data point or series segment. Pass `[]` for a single aggregate.                    |
+| `seriesLabels`     | `string[]`                                      | One label per `query` entry, shown instead of `<queryId> = <value>` on `bar` and `pie` charts.                                            |
 | `queryBaseType`    | `"count" \| "sum" \| "avg" \| "value"`          | Aggregate function. Defaults to `"count"`.                                                                                                |
 | `queryAttributeId` | `string[]`                                      | Required when `queryBaseType` is `"sum"`, `"avg"`, or `"value"`. The field(s) to aggregate. For `radar`, each entry becomes a radar axis. |
 | `queryBaseDateId`  | `string`                                        | Field used for date range filtering. When set, a date range picker is shown on the chart.                                                 |
@@ -131,6 +132,9 @@ Custom layout via renderSettings:
 | `baseQuery`        | `Query[]`                                       | Static filter queries always applied alongside any dynamic filters.                                                                       |
 | `description`      | `string`                                        | Subtitle shown on `card` type charts                                                                                                      |
 | `cardIcon`         | `string`                                        | Heroicon name (solid) for the card icon, e.g. `"UserIcon"`. Defaults to `FolderIcon`.                                                     |
+| `cardSize`         | `"default" \| "compact"`                        | `card` layout; `"compact"` is the short stat-first card. Defaults to `"default"`.                                                       |
+| `pieType`          | `"donut" \| "pie"`                               | `pie` style. Defaults to `"donut"`.                                                                                                       |
+| `cardEmoji`        | `string`                                        | Emoji shown instead of `cardIcon` when set, e.g. `"📦"`. Clearing it brings `cardIcon` back.                                              |
 | `cardIconBgColor`  | `string`                                        | Tailwind bg class for the card icon background                                                                                            |
 | `colors`           | `string[]`                                      | Custom color array for chart segments/bars/lines                                                                                          |
 | `orientation`      | `"col" \| "row"`                                | Bar chart orientation. Defaults to `"row"`.                                                                                               |

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

@@ -625,6 +625,72 @@ Set `viewType="kanban"` on an `extendedTabs` entry and configure `kanbanSettings
 
 ---
 
+### Chart view
+
+Set `viewType="chart"` on an `extendedTabs` entry and list its charts in `chartSettings`. Each entry is a `Charts` object drawn by `DataGraph`, so a tab can hold several charts and a template can hold several chart tabs. `spaceId` falls back to the template's `collectionId`, and the table's active filters are added to every chart's `baseQuery`.
+
+Editors (`edit.allEditable`) get add, edit, remove and move on each chart; add inserts the new chart before the one it sits on, and an empty tab shows an `EmptyState` with an Add Chart button instead. Cards use the compact layout unless `cardSize` is set. A card's emoji button opens a Choose Emoji popup with suggestions and the full emoji picker, which loads only when opened. The choice is saved as `cardEmoji` and shown instead of `cardIcon`; Clear brings the icon back. The builder offers Card, Bar, Line, Pie, Radar and Table, with a Style choice for Bar (horizontal or vertical) and Pie (donut or pie). The builder offers only the columns a chart can use: number columns for Sum and Average, list columns for Group By, date columns for the time axis. Every change is reported through `organise.onChangeTabs`, the same as other tab changes, and nothing is written to browser storage. Without `onChangeTabs` the charts are read-only.
+
+```tsx
+<DataTemplate
+  title="Orders"
+  description="Order overview"
+  type={type}
+  id={id}
+  collectionId="orders"
+  model={model}
+  localURLEndpoint="https://dashboard.example.com"
+  devSettings={devSettings}
+  lib={{ axios, Menu, Transition, navigate: null }}
+  edit={{ allEditable: true }}
+  organise={{
+    handleNavigate,
+    extendedTabs: tabs,
+    onChangeTabs: setTabs,
+  }}
+/>
+
+// tabs
+[
+  {
+    name: "Overview",
+    type: "list",
+    viewType: "chart",
+    chartSettings: [
+      { title: "Orders", type: "card", gridSize: 1, spaceId: "", query: [], queryBaseType: "count" },
+      {
+        title: "Orders By Status",
+        type: "pie",
+        gridSize: 2,
+        spaceId: "",
+        query: [
+          { type: "=", queryId: "status", value: "paid" },
+          { type: "=", queryId: "status", value: "shipped" },
+        ],
+        // one label per query entry
+        seriesLabels: ["Paid", "Shipped"],
+        queryBaseType: "count",
+      },
+      { title: "Orders Per Day", type: "line", gridSize: 2, spaceId: "", query: [], queryBaseType: "count", queryBaseDateId: "createdAt" },
+    ],
+  },
+]
+```
+
+---
+
+### 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.
@@ -1091,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                                                                                                                                                                                                                                                                                  |
@@ -1105,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                                                                                                                                                                                                                                                                   |
@@ -1233,12 +1305,13 @@ Injects custom React components and callbacks into the list, read, and update vi
 | ------------------ | ------------------------------------------------------------------- | ----------------------------------------------------------- |
 | `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                                    |
+| `viewType`         | `"grid" \| "list" \| "iframe" \| "calendar" \| "feeds" \| "kanban" \| "chart"` | 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                                   |
+| `chartSettings`    | `Charts[]`                                                          | Charts drawn by a `"chart"` tab, see Chart view above       |
 
 ### Additional Query
 

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

@@ -491,3 +491,536 @@ export const GridRawData = () => (
     <GridRawDataDemo />
   </div>
 );
+
+// INFO: a chart tab asks the list endpoint for aggregates, so this mock
+// answers those from the in-memory store — count/sum/avg over the records that
+// match the request's "=" queries, one bucket per requested date range
+const CHART_COLLECTION = "demo-chart-orders";
+
+const CHART_SCHEMA: DataStructure[] = [
+  { id: "orderNo", name: "Order No", type: "string" },
+  {
+    id: "status",
+    name: "Status",
+    type: "list",
+    listSelection: ["pending", "paid", "shipped", "cancelled"],
+    listSelectionLabel: ["Pending", "Paid", "Shipped", "Cancelled"],
+  },
+  {
+    id: "channel",
+    name: "Channel",
+    type: "list",
+    listSelection: ["web", "store", "phone"],
+    listSelectionLabel: ["Web", "Store", "Phone"],
+  },
+  { id: "amount", name: "Amount", type: "number" },
+  { id: "items", name: "Items", type: "number" },
+  { id: "createdAt", name: "Created At", type: "date" },
+];
+
+const renderChartRecords = () => {
+  const statuses = ["pending", "paid", "shipped", "cancelled"];
+  const channels = ["web", "store", "phone"];
+  return Array.from({ length: 40 }, (_, index) => ({
+    _id: `o${index + 1}`,
+    orderNo: `ORD-${1000 + index}`,
+    status: statuses[(index * 7) % statuses.length],
+    channel: channels[(index * 5) % channels.length],
+    amount: 20 + ((index * 37) % 180),
+    items: 1 + ((index * 3) % 6),
+    createdAt: new Date(Date.now() - (index % 7) * 24 * 60 * 60 * 1000),
+  }));
+};
+
+const handleParseRangeDate = (value: string) => {
+  const [date, time] = value.trim().split(" ");
+  const [day, month, year] = date.split("/").map(Number);
+  const [hour, minute, second] = (time ?? "00:00:00").split(":").map(Number);
+  return new Date(year, month - 1, day, hour, minute, second);
+};
+
+const handleInstallChartMock = (store: any[]) => {
+  const mock = new MockAdapter(axios, {
+    onNoMatch: "passthrough",
+    delayResponse: 120,
+  });
+  const listUrl = `${DEMO_ENDPOINT}/${CHART_COLLECTION}/list`;
+  const handleParseBody = (config: any) => {
+    try {
+      return JSON.parse(config?.data ?? "{}");
+    } catch (err) {
+      return {};
+    }
+  };
+  // INFO: "=" for chart groups, "search" for the search box — enough to show
+  // the table's filters reaching the charts
+  const handleMatch = (record: any, query: any[] = []) =>
+    query.every((eachQuery) => {
+      if (eachQuery.type === "=")
+        return record[eachQuery.queryId] === eachQuery.value;
+      if (eachQuery.type === "search")
+        return Object.values(record).some((eachValue) =>
+          String(eachValue)
+            .toLowerCase()
+            .includes(String(eachQuery.value).toLowerCase()),
+        );
+      return true;
+    });
+  const handleAggregate = (records: any[], aggregate: any) => {
+    if (aggregate.type === "count") return records.length;
+    const total = records.reduce(
+      (sum, eachRecord) => sum + Number(eachRecord[aggregate.queryId] ?? 0),
+      0,
+    );
+    if (aggregate.type === "avg")
+      return records.length ? total / records.length : 0;
+    return total;
+  };
+
+  mock.onPost(listUrl).reply((config) => {
+    const body = handleParseBody(config);
+    const matched = store.filter((eachRecord) =>
+      handleMatch(eachRecord, body.query),
+    );
+    if (!body.aggregate) {
+      const cursor = typeof body.cursor === "number" ? body.cursor : 0;
+      const limit = typeof body.limit === "number" ? body.limit : 10;
+      return [
+        200,
+        { data: matched.slice(cursor, cursor + limit), count: matched.length },
+      ];
+    }
+    const ranges: string[] = body.aggregate.range ?? [];
+    const data = ranges.map((eachRange) => {
+      const [start, end] = eachRange.split(" - ");
+      const inRange = end
+        ? matched.filter((eachRecord) => {
+            const date = new Date(eachRecord[body.aggregate.dateId]);
+            return (
+              date >= handleParseRangeDate(start) &&
+              date <= handleParseRangeDate(end)
+            );
+          })
+        : matched;
+      return {
+        _id: eachRange,
+        value: handleAggregate(inRange, body.aggregate),
+      };
+    });
+    return [200, { data }];
+  });
+
+  mock
+    .onPost(`${DEMO_ENDPOINT}/spaces/list`)
+    .reply(200, { data: [], count: 0 });
+
+  return mock;
+};
+
+const ChartViewDemo = () => {
+  const store = React.useMemo(() => renderChartRecords(), []);
+  React.useMemo(() => handleInstallChartMock(store), [store]);
+
+  const [typeParam, setTypeParam] = useState<"list" | "read" | "update">(
+    "list",
+  );
+  const [dataId, setDataId] = useState<string>("");
+  const [viewId, setViewId] = useState<string | undefined>(undefined);
+  const [tabs, setTabs] = useState<ExtendedTabs[]>([
+    {
+      name: "Overview",
+      type: "list",
+      viewType: "chart",
+      defaultTab: true,
+      chartSettings: [
+        {
+          title: "Orders",
+          type: "card",
+          cardEmoji: "📦",
+          gridSize: 1,
+          spaceId: CHART_COLLECTION,
+          query: [],
+          queryBaseType: "count",
+        },
+        {
+          title: "Revenue",
+          type: "card",
+          cardEmoji: "💰",
+          gridSize: 1,
+          spaceId: CHART_COLLECTION,
+          query: [],
+          queryBaseType: "sum",
+          queryAttributeId: ["amount"],
+        },
+        {
+          title: "Orders By Channel",
+          type: "pie",
+          gridSize: 2,
+          spaceId: CHART_COLLECTION,
+          query: ["web", "store", "phone"].map((eachValue) => ({
+            type: "=" as const,
+            queryId: "channel",
+            value: eachValue,
+          })),
+          seriesLabels: ["Web", "Store", "Phone"],
+          queryBaseType: "count",
+        },
+        {
+          title: "Orders Per Day",
+          type: "line",
+          gridSize: 2,
+          spaceId: CHART_COLLECTION,
+          query: [],
+          queryBaseType: "count",
+          queryBaseDateId: "createdAt",
+        },
+        {
+          title: "Revenue By Status",
+          type: "bar",
+          gridSize: 2,
+          spaceId: CHART_COLLECTION,
+          query: ["pending", "paid", "shipped", "cancelled"].map(
+            (eachValue) => ({
+              type: "=" as const,
+              queryId: "status",
+              value: eachValue,
+            }),
+          ),
+          seriesLabels: ["Pending", "Paid", "Shipped", "Cancelled"],
+          queryBaseType: "sum",
+          queryAttributeId: ["amount"],
+        },
+        {
+          title: "Orders By Status",
+          type: "table",
+          gridSize: 2,
+          spaceId: CHART_COLLECTION,
+          query: ["pending", "paid", "shipped", "cancelled"].map(
+            (eachValue) => ({
+              type: "=" as const,
+              queryId: "status",
+              value: eachValue,
+            }),
+          ),
+          seriesLabels: ["Pending", "Paid", "Shipped", "Cancelled"],
+          queryBaseType: "count",
+        },
+      ],
+    },
+  ]);
+
+  return (
+    <div className="w-full">
+      <DataTemplateImpl
+        title="Orders"
+        description="Charts over the same records the table lists"
+        type={typeParam}
+        id={dataId}
+        collectionId={CHART_COLLECTION}
+        model={CHART_SCHEMA}
+        localURLEndpoint=""
+        devSettings={demoDevSettings}
+        lib={{ axios, Menu, Transition, papaParser: Papa }}
+        limit={10}
+        edit={{ allEditable: true }}
+        organise={{
+          extendedTabs: tabs,
+          viewId,
+          onChangeTabs: (value: ExtendedTabs[]) => setTabs(value),
+          handleNavigate: (type: string, id?: string, view?: string) => {
+            setTypeParam(type as any);
+            setDataId(id ?? "");
+            if (view) setViewId(view);
+          },
+        }}
+      />
+    </div>
+  );
+};
+
+export const ChartView = () => (
+  <div className="w-full">
+    <div className="font-semibold mb-1 text-gray-900">
+      Data Template — chart view
+    </div>
+    <div className="text-sm mb-4 text-gray-600">
+      A tab with <code>viewType: "chart"</code> draws its{" "}
+      <code>chartSettings</code> with the table's active filters applied. The +
+      and pencil on each chart open the builder; every change is sent through{" "}
+      <code>onChangeTabs</code>, the same as any other tab.
+    </div>
+    <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/lib/components/navigation/leftNav/README.md

@@ -131,6 +131,7 @@ const navigation = [
 | `custom`                       | `any`                                                      | —       | Custom link component used when `linkType` is `"react"`, `"gatsby"`, or `"next"`                            |
 | `compactMode`                  | `boolean`                                                  | `false` | Tighter rows, smaller icons and a smaller expand chevron, keeping every label                               |
 | `searchable`                   | `boolean`                                                  | `false` | Shows a filter box. Matches are listed flat, each with the path it sits under (e.g. `Sales › Reports`)      |
+| `searchAction`                 | `ReactElement`                                             | —       | A small control inside the right end of the filter box, such as a filter button opening the app's own pop-up. Shown only with `searchable` |
 | `persistKey`                   | `string`                                                   | —       | localStorage key that remembers open groups and pages. A new key loads that key's stored state.             |
 | `defaultExpandedIds`           | `string[]`                                                 | —       | Groups (by `groupId`) and pages (by `id`) open when nothing is stored for them                              |
 

package/lib/components/navigation/leftNav/leftNav.stories.tsx

@@ -1,4 +1,9 @@
-import { FolderIcon, HomeIcon, UsersIcon } from "@heroicons/react/24/outline";
+import {
+  FolderIcon,
+  FunnelIcon,
+  HomeIcon,
+  UsersIcon,
+} from "@heroicons/react/24/outline";
 import React, { useState } from "react";
 import { LeftNav as LeftNavImpl, Navigation } from ".";
 import { BarMove } from "../bars";
@@ -275,6 +280,17 @@ export const LeftNav = () => {
   const [workspaceSelectedId, setWorkspaceSelectedId] = useState("sales-q3");
   const [movableNav, setMovableNav] = useState(workspaceNavigation);
   const [lastMove, setLastMove] = useState("");
+  const [topLevelOnly, setTopLevelOnly] = useState(false);
+  // INFO: below lg the nav lives in a drawer opened from the header's menu
+  // button, so each story needs its own open state for that button to work on
+  // a phone
+  const [mobileStoryId, setMobileStoryId] = useState("");
+
+  const handleMobileMenu = (storyId: string) => ({
+    leftNavMobileMenu: mobileStoryId === storyId,
+    handleToggleLeftNavMobileMenu: () =>
+      setMobileStoryId(mobileStoryId === storyId ? "" : storyId),
+  });
 
   return (
     <>
@@ -304,12 +320,11 @@ export const LeftNav = () => {
           <LeftNavImpl
             selectedId={selectedId}
             navigation={groupedNav}
-            leftNavMobileMenu={false}
+            {...handleMobileMenu("story-1")}
             draggable={true}
             handleBarsOnClick={(id) => setSelectedId(id)}
             handleChangeNavigation={(value) => setGroupedNav(value)}
             handleDropEnd={() => {}}
-            handleToggleLeftNavMobileMenu={() => {}}
             renderDashboardLogo={() => renderLogo()}
             renderDashboardContent={renderContent}
             renderDashboardHeaderContent={renderHeader}
@@ -367,9 +382,8 @@ export const LeftNav = () => {
                 groupId: "Site data",
               },
             ]}
-            leftNavMobileMenu={false}
+            {...handleMobileMenu("story-2")}
             handleBarsOnClick={(id) => setGroupedSelectedId(id)}
-            handleToggleLeftNavMobileMenu={() => {}}
             renderDashboardLogo={() => renderLogo()}
             renderDashboardContent={renderContent}
             renderDashboardHeaderContent={renderHeader}
@@ -385,11 +399,10 @@ export const LeftNav = () => {
           <LeftNavImpl
             selectedId={selectedId}
             navigation={navigation}
-            leftNavMobileMenu={false}
+            {...handleMobileMenu("story-3")}
             transition={{ headerVisible: true, collapse }}
             handleBarsOnClick={(id) => setSelectedId(id)}
             handleToggleCollapse={() => setCollapse(!collapse)}
-            handleToggleLeftNavMobileMenu={() => {}}
             renderDashboardLogo={() => renderLogo(collapse)}
             renderDashboardContent={renderContent}
             renderDashboardHeaderContent={renderHeader}
@@ -405,9 +418,8 @@ export const LeftNav = () => {
           <LeftNavImpl
             selectedId={selectedId}
             navigation={navigation}
-            leftNavMobileMenu={false}
+            {...handleMobileMenu("story-4")}
             handleBarsOnClick={(id) => setSelectedId(id)}
-            handleToggleLeftNavMobileMenu={() => {}}
             renderDashboardLogo={() => renderLogo()}
             renderDashboardContent={renderContent}
             renderDashboardHeaderContent={renderHeader}
@@ -451,9 +463,8 @@ export const LeftNav = () => {
             <LeftNavImpl
               selectedId={selectedId}
               navigation={manyNavigation}
-              leftNavMobileMenu={false}
+              {...handleMobileMenu("story-5")}
               handleBarsOnClick={(id) => setSelectedId(id)}
-              handleToggleLeftNavMobileMenu={() => {}}
               renderDashboardLogo={() => renderLogo()}
               renderDashboardContent={() => (
                 <div className="p-6 text-gray-500 text-sm">Default density</div>
@@ -465,10 +476,9 @@ export const LeftNav = () => {
             <LeftNavImpl
               selectedId={selectedId}
               navigation={manyNavigation}
-              leftNavMobileMenu={false}
+              {...handleMobileMenu("story-6")}
               compactMode={true}
               handleBarsOnClick={(id) => setSelectedId(id)}
-              handleToggleLeftNavMobileMenu={() => {}}
               renderDashboardLogo={() => renderLogo()}
               renderDashboardContent={() => (
                 <div className="p-6 text-gray-500 text-sm">compactMode</div>
@@ -487,12 +497,48 @@ export const LeftNav = () => {
           <LeftNavImpl
             selectedId={selectedId}
             navigation={manyNavigation}
-            leftNavMobileMenu={false}
+            {...handleMobileMenu("story-7")}
             searchable={true}
             compactMode={true}
             searchPlaceholder="Filter pages"
             handleBarsOnClick={(id) => setSelectedId(id)}
-            handleToggleLeftNavMobileMenu={() => {}}
+            renderDashboardLogo={() => renderLogo()}
+            renderDashboardContent={renderContent}
+            renderDashboardHeaderContent={renderHeader}
+          />
+        </div>
+      </StorySection>
+
+      <StorySection
+        title="Search Action"
+        description="searchAction puts a small control inside the right end of the filter box, so narrowing the nav costs no row of its own. Here a funnel button toggles a filter the app owns — top-level pages only — and shows a dot while it is on. LeftNav only draws the control; what it opens and filters is up to the app."
+      >
+        <div className="w-full h-96 relative overflow-hidden border rounded-lg">
+          <LeftNavImpl
+            selectedId={workspaceSelectedId}
+            navigation={
+              topLevelOnly
+                ? workspaceNavigation.filter((eachItem) => !eachItem.parentId)
+                : workspaceNavigation
+            }
+            {...handleMobileMenu("story-8")}
+            compactMode={true}
+            searchable={true}
+            searchPlaceholder="Filter spaces"
+            searchAction={
+              <button
+                type="button"
+                aria-label="Filter"
+                className="relative rounded p-0.5 text-gray-400 hover:text-gray-600"
+                onClick={() => setTopLevelOnly(!topLevelOnly)}
+              >
+                <FunnelIcon className="h-4 w-4" />
+                {topLevelOnly && (
+                  <span className="absolute -right-0.5 -top-0.5 h-1.5 w-1.5 rounded-full bg-primary-600" />
+                )}
+              </button>
+            }
+            handleBarsOnClick={(id) => setWorkspaceSelectedId(id)}
             renderDashboardLogo={() => renderLogo()}
             renderDashboardContent={renderContent}
             renderDashboardHeaderContent={renderHeader}
@@ -508,12 +554,11 @@ export const LeftNav = () => {
           <LeftNavImpl
             selectedId={workspaceSelectedId}
             navigation={workspaceNavigation}
-            leftNavMobileMenu={false}
+            {...handleMobileMenu("story-9")}
             compactMode={true}
             searchable={true}
             searchPlaceholder="Filter spaces"
             handleBarsOnClick={(id) => setWorkspaceSelectedId(id)}
-            handleToggleLeftNavMobileMenu={() => {}}
             renderDashboardLogo={() => renderLogo()}
             renderDashboardContent={renderContent}
             renderDashboardHeaderContent={renderHeader}
@@ -529,7 +574,7 @@ export const LeftNav = () => {
           <LeftNavImpl
             selectedId={workspaceSelectedId}
             navigation={movableNav}
-            leftNavMobileMenu={false}
+            {...handleMobileMenu("story-10")}
             compactMode={true}
             defaultExpandedIds={["ws-sales", "ws-marketing"]}
             handleBarsOnClick={(id) => setWorkspaceSelectedId(id)}
@@ -543,7 +588,6 @@ export const LeftNav = () => {
               !dragId.startsWith("ws-") &&
               (!targetId.startsWith("ws-") || position === "inside")
             }
-            handleToggleLeftNavMobileMenu={() => {}}
             renderDashboardLogo={() => renderLogo()}
             renderDashboardContent={() => (
               <div className="p-6 text-sm text-gray-500">
@@ -565,10 +609,9 @@ export const LeftNav = () => {
           <LeftNavImpl
             selectedId={selectedId}
             navigation={twoGroupNavigation}
-            leftNavMobileMenu={false}
+            {...handleMobileMenu("story-11")}
             persistKey="storybook-leftnav-expanded"
             handleBarsOnClick={(id) => setSelectedId(id)}
-            handleToggleLeftNavMobileMenu={() => {}}
             renderDashboardLogo={() => renderLogo()}
             renderDashboardContent={renderContent}
             renderDashboardHeaderContent={renderHeader}
@@ -584,12 +627,11 @@ export const LeftNav = () => {
           <LeftNavImpl
             selectedId={selectedId}
             navigation={dragGroupNav}
-            leftNavMobileMenu={false}
+            {...handleMobileMenu("story-12")}
             draggable={true}
             handleBarsOnClick={(id) => setSelectedId(id)}
             handleChangeNavigation={(value) => setDragGroupNav(value)}
             handleDropEnd={() => {}}
-            handleToggleLeftNavMobileMenu={() => {}}
             renderDashboardLogo={() => renderLogo()}
             renderDashboardContent={renderContent}
             renderDashboardHeaderContent={renderHeader}
@@ -605,13 +647,12 @@ export const LeftNav = () => {
           <LeftNavImpl
             selectedId={selectedId}
             navigation={manyNavigation}
-            leftNavMobileMenu={false}
+            {...handleMobileMenu("story-13")}
             transparent={true}
             mobileOpaque={true}
             compactMode={true}
             searchable={true}
             handleBarsOnClick={(id) => setSelectedId(id)}
-            handleToggleLeftNavMobileMenu={() => {}}
             renderDashboardLogo={() => renderLogo()}
             renderDashboardContent={() => (
               <div className="p-6 text-gray-600 text-sm">

package/package.json

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