blixify-ui-web-mcp 0.1.42 → 0.1.44

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,60 @@ 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" },
+    ],
+  },
+]
+```
+
+---
+
 ### With search and filter
 
 Use `organise.additionalQuery` to add filter controls above the list. Each entry maps to a filter UI control.
@@ -1095,7 +1149,6 @@ Which field types can be edited from the list table, and how. Types not listed u
 | `groupIdCollapsible`          | `{ [key: string]: boolean }`                                                | Initial collapsed/expanded state per group ID                                                                                                                                                                                                                                                                         |
 | `sortGroupByAlphabetically`   | `boolean`                                                                   | Sorts group-by values alphabetically                                                                                                                                                                                                                                                                                  |
 | `unionCollections`            | `any[]`                                                                     | Additional collections to union-query alongside the main collection                                                                                                                                                                                                                                                   |
-| `unionPagination`             | `boolean`                                                                   | Opt in to paging a union list: sends the page offset as `skip` and adds `_id` to the sort as a tie-break (default `false`). See *Union Collections* in the DataWrapper README                                                                                                                                         |
 | `moreSettings`                | `{ text: string; onClick: () => void }[]`                                   | Extra items appended to the "more" dropdown menu                                                                                                                                                                                                                                                                      |
 | `exportSettings`              | `ExportSettings`                                                            | See Export Settings below                                                                                                                                                                                                                                                                                             |
 | `onChangeSort`                | `(value: Sort) => void`                                                     | Called when the user changes the sort                                                                                                                                                                                                                                                                                 |
@@ -1234,12 +1287,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.stories.tsx

@@ -491,3 +491,264 @@ 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>
+);

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

@@ -1017,28 +1017,23 @@ organise={{
 
 ---
 
-### Paging a union list — `unionPagination`
+### Paging a union list
 
-A union list does not page on its own. The DTW sends `skip: 0` for every union request, so page 2 (or the next scroll load) returns the first rows again. If the app fetches the whole union in one request and pages it itself, that is fine and nothing changes.
+A union list pages on the server like any other list. Each page request:
 
-Set `organise.unionPagination` to let the server do the paging instead. It is **off by default**, so upgrading the library changes nothing until you opt in.
+- sends `skip = pageIndex × limit` (the first page is `0`);
+- sends the sort followed by `_id` in the same direction, e.g. `[{ sortId: "sortDate", type: "asc" }, { sortId: "_id", type: "asc" }]`. Every page is a separate request, and two rows with the same sort value have no fixed order between requests, so without the tie-break a row can appear on two pages or on none. With no sort set, the server default (`date` descending) is kept and `_id` is added after it.
 
 ```tsx
 organise={{
   unionCollections: [/* ... */],
-  unionPagination: true,
   paginationType: "scroll", // or "page"
   sort: { sortId: "sortDate", type: "asc" },
 }}
 limit={20}
 ```
 
-With it on, each page request:
-
-- sends `skip = pageIndex × limit` (the first page is `0`);
-- sends the sort followed by `_id` in the same direction, e.g. `[{ sortId: "sortDate", type: "asc" }, { sortId: "_id", type: "asc" }]`. Every page is a separate request, and two rows with the same sort value have no fixed order between requests, so without the tie-break a row can appear on two pages or on none. With no sort set, the server default (`date` descending) is kept and `_id` is added after it.
-
-It only applies with `unionCollections`. Calendar, map and timeline views fetch the full set and are not affected.
+Calendar, map, timeline and `groupId` views fetch the full set and are not paged.
 
 ---
 

package/lib/components/data/dataWrapper/dataWrapper.scrollFilters.stories.tsx

@@ -0,0 +1,122 @@
+import axios from "axios";
+import MockAdapter from "axios-mock-adapter";
+import React, { useEffect, useMemo, useState } from "react";
+import { DataTemplateWrapper } from ".";
+import {
+  DEFAULT_VIEWS,
+  DEMO_ENDPOINT,
+  DEMO_SCHEMA,
+  demoDevSettings,
+  renderDemoRecords,
+} from "../dataTemplate/savedViewsDemo.fixtures";
+
+const meta = { title: "Data/Data Wrapper/Scroll Filters" };
+export default meta;
+
+const COLLECTION = "demo-scroll-filter-tasks";
+
+// INFO: an unfiltered read answers slower than a filtered one, so applying a
+// view while the first load is in flight makes the old answer land last —
+// the order that put rows from an earlier filter on screen
+const UNFILTERED_DELAY = 1500;
+const FILTERED_DELAY = 100;
+
+const workspace = {
+  apiEndpointType: "mongoDB" as const,
+  apiEndpoint: DEMO_ENDPOINT,
+  apiEndpointToken: "",
+  apiUserToken: "",
+  assetEndpoint: "",
+  assetUploadEndpoint: "",
+};
+
+const handleInstallScrollMock = (store: any[]) => {
+  const mock = new MockAdapter(axios, { onNoMatch: "passthrough" });
+  mock.onPost(`${DEMO_ENDPOINT}/${COLLECTION}/list`).reply((config) => {
+    let body: any = {};
+    try {
+      body = JSON.parse(config?.data ?? "{}");
+    } catch (err) {
+      body = {};
+    }
+    const stageQuery = (body.query ?? []).find(
+      (eachQuery: any) => eachQuery?.queryId === "stage",
+    );
+    const rows = stageQuery
+      ? store.filter((each) => each.stage === stageQuery.value)
+      : store;
+    const cursor = typeof body.cursor === "number" ? body.cursor : 0;
+    const limit = typeof body.limit === "number" ? body.limit : rows.length;
+    return new Promise((resolve) =>
+      setTimeout(
+        () =>
+          resolve([
+            200,
+            { data: rows.slice(cursor, cursor + limit), count: rows.length },
+          ]),
+        stageQuery ? FILTERED_DELAY : UNFILTERED_DELAY,
+      ),
+    );
+  });
+  mock
+    .onPost(`${DEMO_ENDPOINT}/spaces/list`)
+    .reply(200, { data: [], count: 0 });
+  return mock;
+};
+
+const ScrollFiltersDemo = () => {
+  const [isMockReady, setIsMockReady] = useState(false);
+  const store = useMemo(() => renderDemoRecords(), []);
+
+  // INFO: in an effect so it survives StrictMode's double mount
+  useEffect(() => {
+    const mock = handleInstallScrollMock(store);
+    setIsMockReady(true);
+    return () => {
+      mock.restore();
+      setIsMockReady(false);
+    };
+  }, [store]);
+
+  if (!isMockReady) return null;
+  return (
+    <DataTemplateWrapper
+      title="Tasks"
+      description="40 offline records"
+      type="list"
+      collectionId={COLLECTION}
+      schema={DEMO_SCHEMA}
+      workspace={workspace}
+      devSettings={{
+        schemaEndpoint: demoDevSettings.schemaEndpoint,
+        currentUser: demoDevSettings.currentUser,
+      }}
+      limit={10}
+      organise={{
+        breadcrumbType: "hidden",
+        paginationType: "scroll",
+        savedViews: true,
+        defaultSavedViews: DEFAULT_VIEWS,
+      }}
+      bareSettings={{
+        bareNewDTW: true,
+        bareFlexFilters: true,
+      }}
+    />
+  );
+};
+
+export const ScrollFilters = () => (
+  <div className="w-full">
+    <div className="font-semibold mb-1 text-gray-900">
+      DataTemplateWrapper — scroll list with flex filters
+    </div>
+    <div className="text-sm mb-4 text-gray-600">
+      A scroll-paginated list where an unfiltered read answers slower than a
+      filtered one. Apply “In progress” during the first load, or clear the
+      filter afterwards: the table must show only the rows of the current
+      filter, and the result count must match the rows on screen.
+    </div>
+    <ScrollFiltersDemo />
+  </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.42",
+  "version": "0.1.44",
   "license": "MIT",
   "main": "lib/mcp/server.js",
   "bin": {