blixify-ui-web-mcp 0.1.25 → 0.1.26

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

@@ -266,70 +266,228 @@ const DataTemplateDemo = () => {
           phone; without the props, narrowing alone would show a squashed
           desktop table, since Tailwind breakpoints key off the viewport. */}
       <div className={isMobile ? "mx-auto max-w-sm" : "w-full"}>
+        <DataTemplateImpl
+          title="Documents"
+          description="Three records hold five attachments between them"
+          type={typeParam}
+          id={dataId}
+          collectionId={DEMO_COLLECTION}
+          model={DEMO_SCHEMA}
+          localURLEndpoint=""
+          devSettings={demoDevSettings}
+          lib={{ axios, Menu, Transition, papaParser: Papa }}
+          limit={4}
+          // INFO: allEditable is what gates isEditor, and isEditor is what puts
+          // "+ New Tab" and the create button on screen. A read-only demo hides
+          // the very controls it is meant to demonstrate.
+          edit={{ allEditable: true, deleteBtn: true, createBtn: true }}
+          organise={{
+            extendedTabs: tabs,
+            viewId,
+            onChangeTabs: (value: any) => setTabs(value),
+            handleNavigate: (type: string, id?: string, view?: string) => {
+              setTypeParam(type as any);
+              setDataId(id ?? "");
+              if (view) setViewId(view);
+            },
+          }}
+          // INFO: mirrors a typical work-order list — mobile gets the card list and
+          // the mobile form; desktop pins the first column so the record name
+          // stays visible while scrolling wide tables. A pinned column on a
+          // phone-width card list would pin nothing useful.
+          bareSettings={{
+            // INFO: mobileView only reaches NewTable, and NewTable only renders
+            // under bareNewDTW — on the legacy table bareListMobileView does
+            // nothing and "Mobile" would just squash the desktop table.
+            // Apps that use the mobile cards set this unconditionally for the same reason.
+            bareNewDTW: true,
+            bareListMobileView: isMobile,
+            bareUpdateMobileView: isMobile,
+            bareListTablePinColumns: isMobile
+              ? undefined
+              : { left: [DEMO_SCHEMA[0].id] },
+          }}
+        />
+      </div>
+    </div>
+  );
+};
+
+export const DataTemplate = () => (
+  // INFO: not wrapped in StorySection — that is w-[90vw], and a data table
+  // wants the width it is given.
+  <div className="w-full">
+    <div className="font-semibold mb-1 text-gray-900">
+      Data Template — self-contained demo
+    </div>
+    <div className="text-sm mb-4 text-gray-600">
+      Carries its own schema and data, so everything works with no backend:
+      create a record, edit inline, delete one, and add a tab through + New Tab.
+      Three records hold five attachments and the File view lists FIVE tiles —
+      the server unwinds the chosen column, so a row is a file rather than a
+      record, and the count and paging follow. The record with no attachments
+      contributes nothing. Switch to Scans for the same records unwound on a
+      different column, which is why + New Tab asks which column a File view
+      should list. Any tab can be set to open by default from that same modal.
+    </div>
+    <DataTemplateDemo />
+  </div>
+);
+
+// INFO: a separate, minimal collection for the grid demo. The point is the
+// raw record — assigneeId (a reference id the display row loses to a label) and
+// createdAt (a Date the display row formats to a string) — reaching the grid
+// hooks as the SECOND argument, so a custom card can read the untouched value.
+const GRID_COLLECTION = "demo-grid-items";
+
+const GRID_SCHEMA: DataStructure[] = [
+  { id: "name", name: "Project", type: "string" },
+  {
+    id: "status",
+    name: "Status",
+    type: "list",
+    listSelection: ["new", "active", "done"],
+  },
+  { id: "assigneeId", name: "Assignee", type: "string" },
+  { id: "createdAt", name: "Created At", type: "date" },
+];
+
+const renderGridRecords = () => [
+  {
+    _id: "g1",
+    name: "Apollo",
+    status: "new",
+    assigneeId: "usr_1001",
+    createdAt: new Date("2026-01-05T09:00:00.000Z"),
+  },
+  {
+    _id: "g2",
+    name: "Borealis",
+    status: "active",
+    assigneeId: "usr_2002",
+    createdAt: new Date("2026-02-11T09:00:00.000Z"),
+  },
+  {
+    _id: "g3",
+    name: "Cassini",
+    status: "done",
+    assigneeId: "usr_3003",
+    createdAt: new Date("2026-03-20T09:00:00.000Z"),
+  },
+];
+
+const handleInstallGridMock = (store: any[]) => {
+  const mock = new MockAdapter(axios, {
+    onNoMatch: "passthrough",
+    delayResponse: 120,
+  });
+  const renderUrl = (type: string) =>
+    `${DEMO_ENDPOINT}/${GRID_COLLECTION}/${type}`;
+  const handleParseBody = (config: any) => {
+    try {
+      return JSON.parse(config?.data ?? "{}");
+    } catch (err) {
+      return {};
+    }
+  };
+
+  mock.onPost(renderUrl("list")).reply((config) => {
+    const body = handleParseBody(config);
+    const cursor = typeof body.cursor === "number" ? body.cursor : 0;
+    const limit = typeof body.limit === "number" ? body.limit : 10;
+    return [
+      200,
+      { data: store.slice(cursor, cursor + limit), 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(`${DEMO_ENDPOINT}/spaces/list`)
+    .reply(200, { data: [], count: 0 });
+
+  return mock;
+};
+
+const GridRawDataDemo = () => {
+  const store = React.useMemo(() => renderGridRecords(), []);
+  React.useMemo(() => handleInstallGridMock(store), [store]);
+
+  const [typeParam, setTypeParam] = useState<"list" | "read" | "update">(
+    "list",
+  );
+  const [dataId, setDataId] = useState<string>("");
+  const [viewId, setViewId] = useState<string | undefined>(undefined);
+  // INFO: grid view is driven by an extendedTabs entry with viewType "grid" —
+  // the same selector renderTabContent uses. organise.listType does not exist.
+  const [tabs] = useState<ExtendedTabs[]>([
+    { name: "Board", type: "list", viewType: "grid", defaultTab: true },
+  ]);
+
+  // INFO: reads rawData (the untouched fetched record), NOT data (the display
+  // row). assigneeId is a raw reference id the display row never carries, and
+  // createdAt is a real Date the display row would have formatted to a string.
+  const renderGridCard = (data: any, rawData: any) => (
+    <div className="rounded-lg border border-gray-200 p-3">
+      <p className="font-medium text-sm text-gray-900">{data.title}</p>
+      <p className="text-xs text-gray-500">
+        raw assigneeId: {rawData?.assigneeId}
+      </p>
+      <p className="text-xs text-gray-500">
+        raw createdAt ISO: {new Date(rawData?.createdAt).toISOString()}
+      </p>
+    </div>
+  );
+
+  return (
+    <div className="w-full">
       <DataTemplateImpl
-        title="Documents"
-        description="Three records hold five attachments between them"
+        title="Grid raw data"
+        description="Grid cards read the raw record via the 2nd hook argument"
         type={typeParam}
         id={dataId}
-        collectionId={DEMO_COLLECTION}
-        model={DEMO_SCHEMA}
+        collectionId={GRID_COLLECTION}
+        model={GRID_SCHEMA}
         localURLEndpoint=""
         devSettings={demoDevSettings}
         lib={{ axios, Menu, Transition, papaParser: Papa }}
-        limit={4}
-        // INFO: allEditable is what gates isEditor, and isEditor is what puts
-        // "+ New Tab" and the create button on screen. A read-only demo hides
-        // the very controls it is meant to demonstrate.
-        edit={{ allEditable: true, deleteBtn: true, createBtn: true }}
+        limit={12}
         organise={{
           extendedTabs: tabs,
           viewId,
-          onChangeTabs: (value: any) => setTabs(value),
           handleNavigate: (type: string, id?: string, view?: string) => {
             setTypeParam(type as any);
             setDataId(id ?? "");
             if (view) setViewId(view);
           },
         }}
-        // INFO: mirrors a typical work-order list — mobile gets the card list and
-        // the mobile form; desktop pins the first column so the record name
-        // stays visible while scrolling wide tables. A pinned column on a
-        // phone-width card list would pin nothing useful.
         bareSettings={{
-          // INFO: mobileView only reaches NewTable, and NewTable only renders
-          // under bareNewDTW — on the legacy table bareListMobileView does
-          // nothing and "Mobile" would just squash the desktop table.
-          // Apps that use the mobile cards set this unconditionally for the same reason.
-          bareNewDTW: true,
-          bareListMobileView: isMobile,
-          bareUpdateMobileView: isMobile,
-          bareListTablePinColumns: isMobile
-            ? undefined
-            : { left: [DEMO_SCHEMA[0].id] },
+          // INFO: 2nd arg (rawData) is the untouched fetched record for the card
+          bareListGridComponent: renderGridCard,
+          bareListGridRibbonText: (data: any, rawData: any) =>
+            rawData?.status === "new" ? "New" : "",
+          bareListGridTags: (data: any, rawData: any) => [rawData?.status],
         }}
       />
-      </div>
     </div>
   );
 };
 
-export const DataTemplate = () => (
-  // INFO: not wrapped in StorySection — that is w-[90vw], and a data table
-  // wants the width it is given.
+export const GridRawData = () => (
   <div className="w-full">
     <div className="font-semibold mb-1 text-gray-900">
-      Data Template — self-contained demo
+      Data Template — grid card reads raw record
     </div>
     <div className="text-sm mb-4 text-gray-600">
-      Carries its own schema and data, so everything works with no backend:
-      create a record, edit inline, delete one, and add a tab through + New Tab.
-      Three records hold five attachments and the File view lists FIVE tiles —
-      the server unwinds the chosen column, so a row is a file rather than a
-      record, and the count and paging follow. The record with no attachments
-      contributes nothing. Switch to Scans for the same records unwound on a
-      different column, which is why + New Tab asks which column a File view
-      should list. Any tab can be set to open by default from that same modal.
+      Each grid card renders from the second hook argument (the untouched
+      fetched record), so it can show the raw <code>assigneeId</code> reference
+      id and the raw <code>createdAt</code> Date — values the formatted display
+      row no longer carries.
     </div>
-    <DataTemplateDemo />
+    <GridRawDataDemo />
   </div>
 );

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

@@ -436,9 +436,12 @@ Use these together with `viewSettings={{ gridImage: "..." }}` to control how gri
 
 ```tsx
 bareSettings={{
-  // Fully replace the default grid card with your own component
-  bareListGridComponent: (data) => (
-    <div className="rounded-lg overflow-hidden border border-gray-200">
+  // Fully replace the default grid card with your own component.
+  // `data` = display row (formatted labels/dates, <img> elements);
+  // `rawData` = the untouched fetched record — use it to read raw values
+  // like a reference id or an unformatted date the display row has lost.
+  bareListGridComponent: (data, rawData) => (
+    <div className="rounded-lg overflow-hidden border border-gray-200" data-assignee={rawData?.assigneeId}>
       <img src={data.coverImage} className="w-full h-40 object-cover" />
       <div className="p-3">
         <p className="font-medium text-sm">{data.name}</p>
@@ -451,10 +454,10 @@ bareSettings={{
   bareListGridColClassName: "col-span-1",
 
   // Tag badges shown on the default grid card
-  bareListGridTags: (data) => [data.category, data.status],
+  bareListGridTags: (data, rawData) => [rawData?.category, rawData?.status],
 
   // Ribbon text overlaid on the card image (e.g. "New", "Sold")
-  bareListGridRibbonText: (data) => data.status === "new" ? "New" : "",
+  bareListGridRibbonText: (data, rawData) => rawData?.status === "new" ? "New" : "",
 
   // Fallback shown when the image column is empty
   bareListGridFallbackImg: () => "/placeholder.png",
@@ -825,6 +828,46 @@ The modal lists all queued records and lets the user confirm before uploading. R
 
 ---
 
+## Saved Views
+
+`organise.savedViews` adds a row of view tags under the tab bar. A user saves the current filters (toolbar and flex), sort, rows per page, hidden columns and column order under a name, then reapplies, updates or deletes it. **All** returns to the defaults.
+
+- Views belong to the tab they were saved on.
+- They are kept in this browser's `localStorage`, per collection, `persistKey` and user. Pass `devSettings.currentUser` so people sharing a browser keep their own views.
+- `organise.defaultSavedViews` adds views from the app, listed first and never deleted. Give each an `id`. 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.
+- Works with or without `persistViewState`.
+
+```tsx
+<DataTemplateWrapper
+  workspace={workspaceSettings}
+  collectionId={taskId}
+  schema={TaskSchema}
+  devSettings={{ currentUser: { userEmail, userName } }}
+  organise={{
+    savedViews: true,
+    defaultSavedViews: [
+      {
+        id: "in-progress",
+        name: "In progress",
+        state: {
+          flexFilters: [
+            { id: "f-stage", columnId: "stage", operator: "=", value: "In Progress" },
+          ],
+        },
+      },
+      {
+        id: "top-priority",
+        name: "Top priority",
+        tabId: "general",
+        state: { sort: { sortId: "priority", type: "desc" } },
+      },
+    ],
+  }}
+/>
+```
+
+`state` takes any of `filterSearchParams`, `filterSelection`, `filterReference`, `filterReferenceDate`, `flexFilters`, `sort`, `pageLimit`, `userHiddenColumnIds`, `hiddenColumnIds` and `columnOrder`. See the DataTemplate README for the storage key and details.
+
 ## Union Collections
 
 `unionCollections` is passed via `organise` and lets you merge data from multiple MongoDB collections into a single list view. Each entry defines a secondary collection to query, how to filter it, which fields to project, and an optional `source` label to identify which collection each row came from.
@@ -1233,50 +1276,50 @@ A shorthand that builds the `extendedTabs` and `viewId` config for you. Only one
 
 ### Bare Settings
 
-| Name                                     | Type                                                                                  | Description                                                                                                              |
-| ---------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `bareReadComponent`                      | `(data: any, rawData?: any) => ReactElement`                                          | Custom component rendered in read view. `data` is display data (labels + elements); `rawData` is the untouched DB doc    |
-| `bareReadComponentPos`                   | `"top"`                                                                               | Renders `bareReadComponent` above the default read content                                                               |
-| `bareReadComponentHide`                  | `boolean`                                                                             | Hides the default read content                                                                                           |
-| `bareReadDescription`                    | `(key, value) => any`                                                                 | Custom renderer for read view field values                                                                               |
-| `bareReadReferenceView`                  | `(dataId, collectionId, attributeId) => boolean \| void`                              | Controls whether a reference field opens a view                                                                          |
-| `bareReadHandleData`                     | `(data: any, rawData?: any) => void`                                                  | Called when read view data is loaded. `data` is display data (labels + elements); `rawData` is the untouched DB doc      |
-| `bareReadListTabs`                       | `boolean`                                                                             | Shows list-style tabs in read view                                                                                       |
-| `bareListComponent`                      | `(data, prettierData, loading, pageIndex) => ReactElement`                            | Fully replaces the list UI                                                                                               |
-| `bareListActionBtns`                     | `(data: any) => ReactElement[]`                                                       | Extra icon buttons on each list row                                                                                      |
-| `bareListMultipleSelectAddtionalActions` | `{ text: string; className?: string; onClick: (ids, selectAll, query) => void }[]`    | Extra bulk-action buttons when rows are selected                                                                         |
-| `bareListGridComponent`                  | `(data: any) => ReactElement`                                                         | Custom card renderer for grid view                                                                                       |
-| `bareListGridColClassName`               | `string`                                                                              | Tailwind class for grid column width                                                                                     |
-| `bareListGridTags`                       | `(data: any) => string[]`                                                             | Tag strings shown on grid cards                                                                                          |
-| `bareListGridRibbonText`                 | `(data: any) => string`                                                               | Ribbon text on grid cards                                                                                                |
-| `bareListGridFallbackImg`                | `(data: any) => string \| ReactElement`                                               | Fallback image for grid cards                                                                                            |
-| `bareListHandleData`                     | `(data, prettierData) => void`                                                        | Called when list data is loaded                                                                                          |
-| `bareListHandleFilter`                   | `(search, select, date, reference) => void`                                           | Called when any filter changes                                                                                           |
-| `bareListHandleSelection`                | `(selectAll, selectedIds, query?) => void`                                            | Called when row selection changes                                                                                        |
-| `bareListDescription`                    | `(key, value) => any`                                                                 | Custom renderer for list view field values                                                                               |
-| `bareListFilterQuery`                    | `Query[]`                                                                             | Additional queries always applied to list fetches                                                                        |
-| `bareListFilterAddComponent`             | `ReactElement[]`                                                                      | Extra filter components in the filter bar                                                                                |
-| `bareListFilterAsPopup`                  | `boolean`                                                                             | Collapses all `additionalQuery` filters into a funnel icon popup instead of showing them inline                          |
-| `bareListPipeline`                       | `PipeLine[]`                                                                          | Additional MongoDB aggregation pipeline stages                                                                           |
-| `bareListFilterSelected`                 | `(filterSearchParams, filterSelection, filterReference, filterReferenceDate) => void` | Called with the current filter state on every change                                                                     |
-| `bareUpdatePrefill`                      | `(data: any) => { key: string; value: any }[]`                                        | Returns prefill values for the update form                                                                               |
-| `bareUpdateComponent`                    | `(data: any) => ReactElement`                                                         | Custom component rendered inside the update form                                                                         |
-| `bareUpdateComponentAbove`               | `boolean`                                                                             | Renders `bareUpdateComponent` above the form fields                                                                      |
-| `bareUpdateActionComponent`              | `(data: any) => ReactElement`                                                         | Custom action buttons in the form footer                                                                                 |
-| `bareUpdateColumnType`                   | `"one" \| "two" \| "four"`                                                            | Form column layout                                                                                                       |
-| `bareUpdateMobileView`                   | `boolean`                                                                             | Mobile-optimised form layout                                                                                             |
-| `bareUpdateActionBottom`                 | `boolean`                                                                             | Moves the read/update action buttons below the content. Right aligned either way. The list's create button is unaffected |
-| `bareUpdateHandleData`                   | `(data, changedAttributeIds?) => void`                                                | Called on every form field change                                                                                        |
-| `bareUpdateHandlePreComplete`            | `(data: any) => Promise<boolean>`                                                     | Called before save — return `false` to cancel                                                                            |
-| `bareUpdateHandleComplete`               | `(data: any) => void`                                                                 | Called after save completes                                                                                              |
-| `bareUpdateHandlePostComplete`           | `(data: any) => void`                                                                 | Called after post-save operations complete                                                                               |
-| `bareUpdateTabId`                        | `(tabId: string) => void`                                                             | Called when the active form tab changes                                                                                  |
-| `bareUpdateTabComponent`                 | `(tabIds: string[]) => { tabId: string; icon?: ReactElement; skip?: boolean }[]`      | Customise tab icons or skip specific tabs in the form                                                                    |
-| `bareUpdateIndividualComponent`          | `(columnId, ref, selectedData, setSelectedData) => ReactElement \| null`              | Replaces a specific form field with a custom component                                                                   |
-| `bareReferenceDel`                       | `{ collectionId, collectionName, columnId, schema }[]`                                | Blocks deletion when the record is referenced elsewhere                                                                  |
-| `bareOffline`                            | `boolean`                                                                             | Enables offline data caching                                                                                             |
-| `bareCSVImportEndpoint`                  | `string`                                                                              | Custom CSV import endpoint                                                                                               |
-| `bareCSVExportEndpoint`                  | `string`                                                                              | Custom CSV export endpoint                                                                                               |
+| Name                                     | Type                                                                                  | Description                                                                                                                                    |
+| ---------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `bareReadComponent`                      | `(data: any, rawData?: any) => ReactElement`                                          | Custom component rendered in read view. `data` is display data (labels + elements); `rawData` is the untouched DB doc                          |
+| `bareReadComponentPos`                   | `"top"`                                                                               | Renders `bareReadComponent` above the default read content                                                                                     |
+| `bareReadComponentHide`                  | `boolean`                                                                             | Hides the default read content                                                                                                                 |
+| `bareReadDescription`                    | `(key, value) => any`                                                                 | Custom renderer for read view field values                                                                                                     |
+| `bareReadReferenceView`                  | `(dataId, collectionId, attributeId) => boolean \| void`                              | Controls whether a reference field opens a view                                                                                                |
+| `bareReadHandleData`                     | `(data: any, rawData?: any) => void`                                                  | Called when read view data is loaded. `data` is display data (labels + elements); `rawData` is the untouched DB doc                            |
+| `bareReadListTabs`                       | `boolean`                                                                             | Shows list-style tabs in read view                                                                                                             |
+| `bareListComponent`                      | `(data, prettierData, loading, pageIndex) => ReactElement`                            | Fully replaces the list UI. `data` is the fetched records (`_id` exposed as `id`), `prettierData` the display rows                                                 |
+| `bareListActionBtns`                     | `(data: any) => ReactElement[]`                                                       | Extra icon buttons on each list row. `data` is the raw fetched record                                                                          |
+| `bareListMultipleSelectAddtionalActions` | `{ text: string; className?: string; onClick: (ids, selectAll, query) => void }[]`    | Extra bulk-action buttons when rows are selected                                                                                               |
+| `bareListGridComponent`                  | `(data: any, rawData?: any) => any`                                                   | Custom card renderer for grid/kanban view. `data` is display data; `rawData` is the fetched record for that card (`_id` exposed as `id`)                               |
+| `bareListGridColClassName`               | `string`                                                                              | Tailwind class for grid column width                                                                                                           |
+| `bareListGridTags`                       | `(data: any, rawData?: any) => string[]`                                              | Tag strings shown on grid cards. `rawData` is the fetched record for that card (`_id` exposed as `id`)                                                                 |
+| `bareListGridRibbonText`                 | `(data: any, rawData?: any) => string`                                                | Ribbon text on grid cards. `rawData` is the fetched record for that card (`_id` exposed as `id`)                                                                       |
+| `bareListGridFallbackImg`                | `(data: any, rawData?: any) => string \| ReactElement`                                | Fallback image for grid cards. `rawData` is the fetched record for that card (`_id` exposed as `id`)                                                                   |
+| `bareListHandleData`                     | `(data, prettierData) => void`                                                        | Called when list data is loaded. `data` is the fetched records (`_id` exposed as `id`), `prettierData` the display rows                                            |
+| `bareListHandleFilter`                   | `(search, select, date, reference) => void`                                           | Called when any filter changes                                                                                                                 |
+| `bareListHandleSelection`                | `(selectAll, selectedIds, query?) => void`                                            | Called when row selection changes                                                                                                              |
+| `bareListDescription`                    | `(key, value) => any`                                                                 | Custom renderer for list view field values                                                                                                     |
+| `bareListFilterQuery`                    | `Query[]`                                                                             | Additional queries always applied to list fetches                                                                                              |
+| `bareListFilterAddComponent`             | `ReactElement[]`                                                                      | Extra filter components in the filter bar                                                                                                      |
+| `bareListFilterAsPopup`                  | `boolean`                                                                             | Collapses all `additionalQuery` filters into a funnel icon popup instead of showing them inline                                                |
+| `bareListPipeline`                       | `PipeLine[]`                                                                          | Additional MongoDB aggregation pipeline stages                                                                                                 |
+| `bareListFilterSelected`                 | `(filterSearchParams, filterSelection, filterReference, filterReferenceDate) => void` | Called with the current filter state on every change                                                                                           |
+| `bareUpdatePrefill`                      | `(data: any, rawData?: any) => { key: string; value: any }[]`                         | Returns prefill values for the update form. `rawData` is the stored doc as loaded (undefined for a new record)                                 |
+| `bareUpdateComponent`                    | `(data: any, rawData?: any) => any`                                                   | Custom component rendered inside the update form. `rawData` is the stored doc as loaded (undefined for a new record)                           |
+| `bareUpdateComponentAbove`               | `boolean`                                                                             | Renders `bareUpdateComponent` above the form fields                                                                                            |
+| `bareUpdateActionComponent`              | `(data: any, formRef?: any, rawData?: any) => any`                                    | Custom action buttons in the form footer. `rawData` is the stored doc as loaded (undefined for a new record)                                   |
+| `bareUpdateColumnType`                   | `"one" \| "two" \| "four"`                                                            | Form column layout                                                                                                                             |
+| `bareUpdateMobileView`                   | `boolean`                                                                             | Mobile-optimised form layout                                                                                                                   |
+| `bareUpdateActionBottom`                 | `boolean`                                                                             | Moves the read/update action buttons below the content. Right aligned either way. The list's create button is unaffected                       |
+| `bareUpdateHandleData`                   | `(data: any, changedAttributeIds?: string[], rawData?: any) => void`                  | Called on every form field change with the current data and changed field IDs. `rawData` is the stored doc as loaded (undefined for a new record) |
+| `bareUpdateHandlePreComplete`            | `(data: any, rawData?: any) => Promise<boolean>`                                      | Called before save — return `false` to cancel. `rawData` is the stored doc as loaded (undefined for a new record)                              |
+| `bareUpdateHandleComplete`               | `(data: any, rawData?: any) => Promise<any>`                                          | Called after save completes. `rawData` is the stored doc as loaded (undefined for a new record)                                                |
+| `bareUpdateHandlePostComplete`           | `(data: any, rawData?: any) => Promise<any>`                                          | Called after post-save operations complete. `rawData` is the stored doc as loaded (undefined for a new record); undefined for offline uploads  |
+| `bareUpdateTabId`                        | `(tabId: string) => void`                                                             | Called when the active form tab changes                                                                                                        |
+| `bareUpdateTabComponent`                 | `(tabIds: string[]) => { tabId: string; icon?: ReactElement; skip?: boolean }[]`      | Customise tab icons or skip specific tabs in the form                                                                                          |
+| `bareUpdateIndividualComponent`          | `(columnId, ref, selectedData, setSelectedData, rawData?) => ReactElement \| null`    | Replaces a specific form field with a custom component. `rawData` is the stored doc as loaded (undefined for a new record)                     |
+| `bareReferenceDel`                       | `{ collectionId, collectionName, columnId, schema }[]`                                | Blocks deletion when the record is referenced elsewhere                                                                                        |
+| `bareOffline`                            | `boolean`                                                                             | Enables offline data caching                                                                                                                   |
+| `bareCSVImportEndpoint`                  | `string`                                                                              | Custom CSV import endpoint                                                                                                                     |
+| `bareCSVExportEndpoint`                  | `string`                                                                              | Custom CSV export endpoint                                                                                                                     |
 
 ---
 

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

@@ -0,0 +1,149 @@
+import React, { useEffect, useMemo, useState } from "react";
+import { ButtonGroup } from "../../action/buttonGroup";
+import { DataTemplateWrapper } from ".";
+import {
+  DEFAULT_VIEWS,
+  DEMO_ENDPOINT,
+  demoDevSettings,
+  DEMO_SCHEMA,
+  handleInstallDemoMock,
+  OWNERS,
+  renderDemoRecords,
+  TABS,
+} from "../dataTemplate/savedViewsDemo.fixtures";
+import { buildSavedViewsKey } from "../dataTemplate/viewStatePersistence";
+
+const meta = { title: "Data/Data Wrapper/Saved Views" };
+export default meta;
+
+// INFO: its own collection, so views saved here do not mix with the DataTemplate story's
+const COLLECTION = "demo-saved-view-wrapper-tasks";
+
+// INFO: bareFlexFilters replaces the toolbar filters, so the two never show together
+const FILTER_MODES = [
+  { id: "flex", name: "Flex filters" },
+  { id: "toolbar", name: "Toolbar filters" },
+];
+
+const workspace = {
+  apiEndpointType: "mongoDB" as const,
+  apiEndpoint: DEMO_ENDPOINT,
+  apiEndpointToken: "",
+  apiUserToken: "",
+  assetEndpoint: "",
+  assetUploadEndpoint: "",
+};
+
+const SavedViewsWrapperDemo = () => {
+  const [viewId, setViewId] = useState("general");
+  const [isMockReady, setIsMockReady] = useState(false);
+  const [resetKey, setResetKey] = useState(0);
+  const [filterMode, setFilterMode] = useState<"flex" | "toolbar">("flex");
+
+  const store = useMemo(() => renderDemoRecords(), []);
+
+  // INFO: in an effect so it survives StrictMode's double mount
+  useEffect(() => {
+    const mock = handleInstallDemoMock(store, COLLECTION);
+    setIsMockReady(true);
+    return () => {
+      mock.restore();
+      setIsMockReady(false);
+    };
+  }, [store]);
+
+  const handleClearStoredViews = () => {
+    try {
+      window.localStorage.removeItem(
+        buildSavedViewsKey(
+          COLLECTION,
+          undefined,
+          demoDevSettings.currentUser.userEmail,
+        ),
+      );
+    } catch (err) {
+      // INFO: storage unavailable — nothing to clear
+    }
+    setResetKey((prev) => prev + 1);
+  };
+
+  return (
+    <div className="w-full">
+      <div className="mb-4 flex flex-wrap items-center gap-3">
+        <ButtonGroup
+          selection={FILTER_MODES}
+          selectedId={filterMode}
+          variant="tag"
+          size="small"
+          onClick={(id) => setFilterMode(id as "flex" | "toolbar")}
+        />
+        <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={handleClearStoredViews}
+        >
+          Clear my saved views
+        </button>
+      </div>
+      {isMockReady && (
+        <DataTemplateWrapper
+          key={`${resetKey}-${filterMode}`}
+          title="Tasks"
+          description="40 offline records"
+          type="list"
+          collectionId={COLLECTION}
+          schema={DEMO_SCHEMA}
+          workspace={workspace}
+          // INFO: what a workspace cannot carry — the schema endpoint the tab bar
+          // reads, and the user whose views these are
+          devSettings={{
+            schemaEndpoint: demoDevSettings.schemaEndpoint,
+            currentUser: demoDevSettings.currentUser,
+          }}
+          limit={10}
+          organise={{
+            breadcrumbType: "hidden",
+            extendedTabs: TABS,
+            viewId,
+            savedViews: true,
+            defaultSavedViews: DEFAULT_VIEWS,
+            filterComponentNewRow: true,
+          }}
+          additionalQuery={[
+            {
+              type: "list",
+              value: "owner",
+              options: OWNERS,
+              filterLabel: "Owner",
+            },
+            { type: "range", value: "dueDate" },
+          ]}
+          handleNavigate={(type, _id, view) => {
+            if (type === "list" && view) setViewId(view);
+          }}
+          bareSettings={{
+            bareNewDTW: true,
+            bareFlexFilters: filterMode === "flex",
+          }}
+        />
+      )}
+    </div>
+  );
+};
+
+export const SavedViews = () => (
+  <div className="w-full">
+    <div className="font-semibold mb-1 text-gray-900">
+      DataTemplateWrapper — saved views
+    </div>
+    <div className="text-sm mb-4 text-gray-600">
+      The same saved views as Data/Data Template → Saved Views, through
+      DataTemplateWrapper the way apps use it: organise.savedViews and
+      organise.defaultSavedViews, with devSettings.currentUser keeping each
+      user's views apart. Set a filter, sort or columns, then “+ Save view”;
+      click a view to apply it, “All” to go back, × to delete. Views are per tab
+      and kept in this browser.
+    </div>
+    <SavedViewsWrapperDemo />
+  </div>
+);

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

@@ -71,6 +71,27 @@ await query.call("update", {
 });
 ```
 
+### Version-checked update — refuse a stale save
+
+`sensitive: true` writes the update only if the record has not changed since the version in `data.baseUpdatedAt` was read. Send the version you read plus 1 ms; if someone else saved in between, the server answers `400 { err: "Refresh Sensitive Model" }` and `call` rethrows it.
+
+```ts
+try {
+  await query.call("update", {
+    id: org._id,
+    data: {
+      members,
+      baseUpdatedAt: new Date(new Date(org.baseUpdatedAt).getTime() + 1),
+    },
+    sensitive: true,
+  });
+} catch (err: any) {
+  if (err?.response?.data?.err === "Refresh Sensitive Model") {
+    // someone else saved since this was read: reload and ask the user to try again
+  }
+}
+```
+
 ### Delete a record
 
 ```ts
@@ -184,6 +205,7 @@ await query.call("create", {
 | `query`                 | `Query[]`            | Filter for `batchDelete` / `batchUpdate`          | ✓                                                             |
 | `isOrQuery`             | `boolean`            | Use OR between query conditions in `batchUpdate`  | ✓                                                             |
 | `upsert`                | `boolean`            | Create doc if not found during `update`           | ✓                                                             |
+| `sensitive`             | `boolean`            | Version-checked `update`: refused with `Refresh Sensitive Model` if the record changed since `data.baseUpdatedAt` was read | ✓ |
 | `unique`                | `string`             | Field name to enforce uniqueness on `create`      | ✓                                                             |
 | `stopRes`               | `boolean`            | Skip waiting for response body                    | ✓                                                             |
 | `createLabelsIfMissing` | `boolean`            | Auto-create label values if missing (Monday only) | ✓                                                             |