blixify-ui-web-mcp 0.1.24 → 0.1.26

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

@@ -454,11 +454,12 @@ Set `organise.viewId="grid"` (or add an `extendedTabs` entry with `viewType="gri
         <p className="text-sm text-gray-500">{rowData.price}</p>
       </div>
     ),
-    // Tags shown on the default grid card
-    bareListGridTags: (rowData) => [rowData.category, rowData.status],
+    // Tags shown on the default grid card. The second argument is the fetched
+    // record, for values the display row has formatted away
+    bareListGridTags: (rowData, rawData) => [rawData?.category, rawData?.status],
     // Ribbon text on the default grid card
-    bareListGridRibbonText: (rowData) =>
-      rowData.status === "new" ? "New" : "",
+    bareListGridRibbonText: (rowData, rawData) =>
+      rawData?.status === "new" ? "New" : "",
     // Fallback when the image column is empty
     bareListGridFallbackImg: () => "/placeholder.png",
   }}
@@ -983,8 +984,10 @@ Which field types can be edited from the list table, and how. Types not listed u
 | `fixedPagination`             | `boolean`                                                                   | Fixes the pagination bar to the bottom of the viewport                                                                                                                                                                                                                                                                |
 | `filterComponentNewRow`       | `boolean`                                                                   | Renders each filter component on its own row                                                                                                                                                                                                                                                                          |
 | `addColumnEnabled`            | `boolean`                                                                   | Shows an add-column button in the table header                                                                                                                                                                                                                                                                        |
-| `persistViewState`            | `"persistent" \| "session"`                                                 | Remembers the list's sort, filters, hidden columns, page and search per collection, so a Back navigation lands where the user left. `"persistent"` uses `localStorage`; `"session"` writes `sessionStorage` and reads it first, falling back to `localStorage`. List view only                                        |
+| `persistViewState`            | `"persistent" \| "session"`                                                 | Remembers the list's sort, filters, hidden columns, page, rows per page, search and reading position per collection, so a Back navigation lands where the user left. `"persistent"` uses `localStorage`; `"session"` writes `sessionStorage` and reads it first, falling back to `localStorage`. The reading position is restored on mount and on returning from a record, not on a tab switch; with several lists on one page, only the list a record was last opened from restores (tracked in `blixify-dtw-persist-last-drill`). Covers table, list, grid, kanban and feeds; not map. List view only                                        |
 | `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` |
+| `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 |
 | `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                                                                                                                                                                                                                                                                                  |
@@ -1068,15 +1071,15 @@ Injects custom React components and callbacks into the list, read, and update vi
 | `bareReadDescription`                    | `(key: string, value: any) => any`                                                    | Custom renderer for read view field values                                                                                                                                                                           |
 | `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) => any`                                     | Fully replaces the list UI with a custom component                                                                                                                                                                   |
-| `bareListActionBtns`                     | `(data: any) => ReactElement[]`                                                       | Extra icon buttons rendered on each list row                                                                                                                                                                         |
+| `bareListComponent`                      | `(data, prettierData, loading, pageIndex) => any`                                     | 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 shown when rows are selected                                                                                                                                                               |
-| `bareListGridComponent`                  | `(data: any) => any`                                                                  | Custom card renderer for grid view                                                                                                                                                                                   |
+| `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) => string[]`                                                             | Returns tag strings shown on grid cards                                                                                                                                                                              |
-| `bareListGridFallbackImg`                | `(data: any) => string \| ReactElement`                                               | Fallback image/element for grid cards without an image                                                                                                                                                               |
-| `bareListGridRibbonText`                 | `(data: any) => string`                                                               | Text shown as a ribbon on grid cards                                                                                                                                                                                 |
-| `bareListHandleData`                     | `(data, prettierData) => void`                                                        | Called when list data is loaded                                                                                                                                                                                      |
+| `bareListGridTags`                       | `(data: any, rawData?: any) => string[]`                                              | Tag strings shown 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`)                                                                                                                                         |
+| `bareListGridRibbonText`                 | `(data: any, rawData?: any) => string`                                                | Ribbon text on 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                                                                                                                  |
 | `bareListHandleSelection`                | `(selectAll, selectedIds, query?) => void`                                            | Called when row selection changes                                                                                                                                                                                    |
 | `bareListHandleFilter`                   | `(search, select, date, reference) => void`                                           | Called when any filter changes                                                                                                                                                                                       |
 | `bareListFilterSelected`                 | `(filterSearchParams, filterSelection, filterReference, filterReferenceDate) => void` | Called with the current filter state whenever it changes                                                                                                                                                             |
@@ -1084,13 +1087,13 @@ Injects custom React components and callbacks into the list, read, and update vi
 | `bareListFilterQuery`                    | `Query[]`                                                                             | Additional queries always applied to list fetches                                                                                                                                                                    |
 | `bareListFilterAddComponent`             | `ReactElement[]`                                                                      | Extra filter components rendered in the filter bar                                                                                                                                                                   |
 | `bareListPipeline`                       | `PipeLine[]`                                                                          | Additional pipeline stages appended to list queries                                                                                                                                                                  |
-| `bareListObjectHandleData`               | `(type: "read" \| "update" \| "new", data: any) => void`                              | Called when a list-object row is opened                                                                                                                                                                              |
-| `bareUpdatePrefill`                      | `(data: any) => { key: string; value: any }[]`                                        | Returns prefill values for the update form based on existing data                                                                                                                                                    |
-| `bareUpdateComponent`                    | `(data: any) => any`                                                                  | Custom component rendered inside the update form                                                                                                                                                                     |
+| `bareListObjectHandleData`               | `(type: "read" \| "update" \| "new", data: any, rawData?: any) => void`               | Called when a list-object row is opened. `rawData` is that row as stored (undefined for a new row)                                                                                                                   |
+| `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 default form fields                                                                                                                                                          |
 | `bareSaveOnTabChange`                    | `boolean`                                                                             | Auto-save: every Next / Previous on a tabbed update form writes a draft first, silently (no toast). Pair with `edit.enableUpdateDraft`                                                                               |
 | `bareUpsertPartialUpdate`                | `boolean`                                                                             | Upsert by `props.id` and send only the fields that changed since load; a save with no changes skips the write. Makes auto-save safe across devices                                                                   |
-| `bareUpdateActionComponent`              | `(data: any, formRef?: any) => any`                                                   | Custom action buttons rendered in the update form footer                                                                                                                                                             |
+| `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)                                                                                                         |
 | `bareFlexFilters`                        | `boolean`                                                                             | Funnel icon opens the Filters builder (column · condition · value, values from the schema) — replaces hand-rolled page filters; new table only                                                                       |
 | `bareOnFlexFiltersChange`                | `(flexFilters: FlexFilterData[]) => void`                                             | Fires when the applied (debounced) flex filters change — from user panel edits or programmatic `handleApplyFlexFilters` / `handleClearFlexFilters`. Lets a parent observe live filter state. Needs `bareFlexFilters` |
 | `bareListFilterAsPopup`                  | `boolean`                                                                             | Shows the list's filter inputs in a popup instead of the header row                                                                                                                                                  |
@@ -1100,15 +1103,15 @@ Injects custom React components and callbacks into the list, read, and update vi
 | `bareMobileTooltip`                      | `MobileViewTooltip`                                                                   | Passed to NewTable as `mobileTooltip` when `bareNewDTW` and `bareListMobileView` are on: a Tag, trailing text and summary line on the collapsed row, plus a hover card. See the NewTable README → Mobile tooltip   |
 | `bareListMobileTooltip`                  | `NewListMobileTooltip`                                                                | Passed to NewList when `bareNewDTW` is on: `imageKey`, `summaryKeys`, `tagKeys` and `tagColors` for the hover card on list items                                                                                     |
 | `bareListMaxSelectedCount`               | `number`                                                                              | Caps how many rows the checkbox column may select at once                                                                                                                                                            |
-| `bareUpdateHandleData`                   | `(data: any, changedAttributeIds?: string[]) => void`                                 | Called on every form field change with the current data and changed field IDs                                                                                                                                        |
-| `bareUpdateHandlePreComplete`            | `(data: any) => Promise<boolean>`                                                     | Called before save — return `false` to cancel                                                                                                                                                                        |
-| `bareUpdateHandleComplete`               | `(data: any) => Promise<any>`                                                         | Called after save completes                                                                                                                                                                                          |
-| `bareUpdateHandlePostComplete`           | `(data: any) => Promise<any>`                                                         | Called after post-save operations complete                                                                                                                                                                           |
+| `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                                                                        |
 | `bareUpdateColumnType`                   | `"one" \| "two" \| "four"`                                                            | Form column layout: `"one"` = 2-col grid, `"two"` = 4-col grid (default), `"four"` = 4-col grid                                                                                                                      |
 | `bareUpdateTabComponent`                 | `(tabIds: string[]) => { tabId: string; icon?: ReactElement; skip?: boolean }[]`      | Custom icons/skip flags for form tabs                                                                                                                                                                                |
 | `bareUpdateActionBottom`                 | `boolean`                                                                             | Plain right-aligned action row instead of the floating pill — for short forms inside a `Modal`                                                                                                                       |
 | `bareUpdateTabId`                        | `(tabId: string) => void`                                                             | Called when the active form tab changes                                                                                                                                                                              |
-| `bareUpdateIndividualComponent`          | `(columnId, ref, selectedData, setSelectedData) => ReactElement \| null`              | Replaces a specific form field with a custom component                                                                                                                                                               |
+| `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)                                                                                           |
 | `bareUpdateMobileView`                   | `boolean`                                                                             | Renders the update form in mobile-optimised layout                                                                                                                                                                   |
 | `bareOffline`                            | `boolean`                                                                             | Enables offline data caching via IndexedDB                                                                                                                                                                           |
 | `bareOfflineNetworkListener`             | `boolean`                                                                             | With `bareOffline`: follow `navigator.onLine` — saves go to the server while online and to IndexedDB only when the network is down. Without it every save goes to IndexedDB until `handleUploadOfflineData()`        |

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

@@ -0,0 +1,142 @@
+import { Menu, Transition } from "@headlessui/react";
+import axios from "axios";
+import Papa from "papaparse";
+import React, { useEffect, useMemo, useState } from "react";
+import { ButtonGroup } from "../../action/buttonGroup";
+import { DataTemplate as DataTemplateImpl } from ".";
+import {
+  DEFAULT_VIEWS,
+  DEMO_COLLECTION,
+  demoDevSettings,
+  DEMO_SCHEMA,
+  handleInstallDemoMock,
+  OWNERS,
+  renderDemoRecords,
+  TABS,
+} from "./savedViewsDemo.fixtures";
+import { buildSavedViewsKey } from "./viewStatePersistence";
+
+const meta = { title: "Data/Data Template" };
+export default meta;
+
+// 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 SavedViewsDemo = () => {
+  const [viewId, setViewId] = useState("general");
+  const [isMockReady, setIsMockReady] = useState(false);
+  // INFO: remounts the template after the stored views are cleared
+  const [resetKey, setResetKey] = useState(0);
+  const [filterMode, setFilterMode] = useState<"flex" | "toolbar">("flex");
+
+  const store = useMemo(() => renderDemoRecords(), []);
+  const storageKey = buildSavedViewsKey(
+    DEMO_COLLECTION,
+    undefined,
+    demoDevSettings.currentUser.userEmail,
+  );
+
+  // INFO: in an effect so it survives StrictMode's double mount
+  useEffect(() => {
+    const mock = handleInstallDemoMock(store);
+    setIsMockReady(true);
+    return () => {
+      mock.restore();
+      setIsMockReady(false);
+    };
+  }, [store]);
+
+  const handleClearStoredViews = () => {
+    try {
+      window.localStorage.removeItem(storageKey);
+    } 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 && (
+        <DataTemplateImpl
+          key={`${resetKey}-${filterMode}`}
+          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,
+            // INFO: toolbar filters on their own full-width row, instead of
+            // sharing the title row with the action buttons
+            filterComponentNewRow: true,
+            // INFO: the toolbar filters outside the flex filter popup — normal
+            // size, and captured by saved views like any other filter
+            additionalQuery: [
+              {
+                type: "list",
+                value: "owner",
+                options: OWNERS,
+                filterLabel: "Owner",
+              },
+              { type: "range", value: "dueDate" },
+            ],
+            defaultSavedViews: DEFAULT_VIEWS,
+            handleNavigate: (type: string, _id?: string, view?: string) => {
+              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">
+      Data Template — saved views
+    </div>
+    <div className="text-sm mb-4 text-gray-600">
+      Offline, with 40 tasks. “Flex filters” uses the compact filter popup;
+      “Toolbar filters” shows the normal Owner and Due filters above the list
+      instead. Set a filter, a sort or hide a column, then “+ Save view” and
+      name it. Click a view to apply it, “All” to go back, and × to delete one.
+      Change something while a view is active and it shows “•” with an Update
+      action. Views belong to the tab they were saved on — the Board tab keeps
+      its own list. “In progress” and “Top priority” are provided by the app and
+      cannot be deleted. Views are kept in this browser, so they survive a
+      reload.
+    </div>
+    <SavedViewsDemo />
+  </div>
+);

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

@@ -0,0 +1,246 @@
+import { Menu, Transition } from "@headlessui/react";
+import axios from "axios";
+import MockAdapter from "axios-mock-adapter";
+import Papa from "papaparse";
+import React, { useEffect, useMemo, useState } from "react";
+import { ButtonGroup } from "../../action/buttonGroup";
+import { DataTemplate as DataTemplateImpl } from ".";
+import { DataStructure } from "./model";
+import { ExtendedTabs } from "./spaceModel";
+
+const meta = { title: "Data/Data Template" };
+export default meta;
+
+// INFO: its own endpoint, so the mock never answers for another story
+const DEMO_ENDPOINT = "https://dtw-scroll-demo.local/api";
+const DEMO_COLLECTION = "demo-scroll-records";
+const RECORD_COUNT = 60;
+const STAGES = ["New", "In Progress", "Done"];
+const OWNERS = ["Alice", "Ben", "Chitra", "Dan"];
+
+const DEMO_SCHEMA: DataStructure[] = [
+  { id: "name", name: "Record", type: "string" },
+  { id: "stage", name: "Stage", type: "list", listSelection: STAGES },
+  { id: "owner", name: "Owner", type: "string" },
+  { id: "summary", name: "Summary", type: "string" },
+];
+
+const TABS: ExtendedTabs[] = [
+  { name: "List", type: "list", viewType: "list" },
+  { name: "Grid", type: "list", viewType: "grid" },
+  {
+    name: "Kanban",
+    type: "list",
+    viewType: "kanban",
+    kanbanSettings: { title: "stage" },
+  },
+  {
+    name: "Feeds",
+    type: "list",
+    viewType: "feeds",
+    feedsSettings: { title: "name", content: "stage", desc: "summary" },
+  },
+] as ExtendedTabs[];
+
+const DTW_TOGGLE = [
+  { id: "new", name: "New DTW" },
+  { id: "legacy", name: "Legacy" },
+];
+const LAYOUT_TOGGLE = [
+  { id: "desktop", name: "Desktop" },
+  { id: "mobile", name: "Mobile" },
+];
+
+const demoDevSettings: any = {
+  server: "mongoServer",
+  dbEndpoint: DEMO_ENDPOINT,
+  dbAPIToken: "",
+  dbUserToken: "",
+  schemaEndpoint: DEMO_ENDPOINT,
+  schemaEndpointToken: "",
+  imageEndpoint: "https://placehold.co/600x400/e2e8f0/475569.png?text=",
+  uploadEndpoint: "",
+};
+
+const renderDemoRecords = () =>
+  Array.from({ length: RECORD_COUNT }, (_, index) => {
+    const number = String(index + 1).padStart(2, "0");
+    return {
+      _id: `rec-${number}`,
+      name: `Record ${number}`,
+      stage: STAGES[index % STAGES.length],
+      owner: OWNERS[index % OWNERS.length],
+      summary: `Summary for record ${number}`,
+    };
+  });
+
+// INFO: Kanban queries per column — unfiltered, every card would appear in every column
+const handleApplyQuery = (rows: any[], query: any[] = []) =>
+  query.reduce((filtered: any[], eachQuery: any) => {
+    if (!eachQuery?.queryId) return filtered;
+    if (eachQuery.type === "=" || eachQuery.type === "==")
+      return filtered.filter(
+        (eachRow) => eachRow[eachQuery.queryId] === eachQuery.value,
+      );
+    if (eachQuery.type === "in" && Array.isArray(eachQuery.value))
+      return filtered.filter((eachRow) =>
+        eachQuery.value.includes(eachRow[eachQuery.queryId]),
+      );
+    return filtered;
+  }, rows);
+
+const handleInstallDemoMock = (store: any[]) => {
+  const mock = new MockAdapter(axios, {
+    onNoMatch: "passthrough",
+    delayResponse: 150,
+  });
+  const renderUrl = (type: string) =>
+    `${DEMO_ENDPOINT}/${DEMO_COLLECTION}/${type}`;
+  const handleParseBody = (config: any) => {
+    try {
+      return JSON.parse(config?.data ?? "{}");
+    } catch (err) {
+      return {};
+    }
+  };
+
+  mock.onPost(renderUrl("list")).reply((config) => {
+    const body = handleParseBody(config);
+    const rows = handleApplyQuery(store, body.query);
+    const cursor = typeof body.cursor === "number" ? body.cursor : 0;
+    const limit = typeof body.limit === "number" ? body.limit : RECORD_COUNT;
+    return [
+      200,
+      { data: rows.slice(cursor, cursor + limit), count: rows.length },
+    ];
+  });
+
+  mock.onPost(renderUrl("get")).reply((config) => {
+    const body = handleParseBody(config);
+    return [200, { data: store.find((each) => each._id === body.id) ?? null }];
+  });
+
+  // INFO: the tab bar waits on this lookup
+  mock
+    .onPost(`${DEMO_ENDPOINT}/spaces/list`)
+    .reply(200, { data: [], count: 0 });
+
+  return mock;
+};
+
+const ScrollRestoreDemo = () => {
+  const [typeParam, setTypeParam] = useState<"list" | "read" | "update">(
+    "list",
+  );
+  const [dataId, setDataId] = useState<string>("");
+  // INFO: kept apart from viewId — opening a record navigates with "general"
+  const [listViewId, setListViewId] = useState<string>("general");
+  const [dtwMode, setDtwMode] = useState<"new" | "legacy">("new");
+  const [layout, setLayout] = useState<"desktop" | "mobile">("desktop");
+  const [isMockReady, setIsMockReady] = useState(false);
+
+  const store = useMemo(() => renderDemoRecords(), []);
+  const isMobile = layout === "mobile";
+  const isNewDTW = dtwMode === "new";
+
+  // INFO: in an effect so it survives StrictMode's double mount
+  useEffect(() => {
+    const mock = handleInstallDemoMock(store);
+    setIsMockReady(true);
+    return () => {
+      mock.restore();
+      setIsMockReady(false);
+    };
+  }, [store]);
+
+  const handleNavigate = (type: string, id?: string, view?: string) => {
+    if (type === "list" && view) setListViewId(view);
+    setTypeParam(type as "list" | "read" | "update");
+    setDataId(id ?? "");
+  };
+
+  const handleBackToList = () => handleNavigate("list", "", listViewId);
+
+  const renderToggles = () => (
+    <div className="mb-4 flex flex-wrap gap-3">
+      <ButtonGroup
+        selection={DTW_TOGGLE}
+        selectedId={dtwMode}
+        variant="tag"
+        size="small"
+        onClick={(id) => setDtwMode(id as "new" | "legacy")}
+      />
+      <ButtonGroup
+        selection={LAYOUT_TOGGLE}
+        selectedId={layout}
+        variant="tag"
+        size="small"
+        onClick={(id) => setLayout(id as "desktop" | "mobile")}
+      />
+      {typeParam !== "list" && (
+        <button
+          id="scroll-restore-back"
+          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={handleBackToList}
+        >
+          ← Back to list
+        </button>
+      )}
+    </div>
+  );
+
+  return (
+    <div className="w-full">
+      {renderToggles()}
+      <div className={isMobile ? "mx-auto max-w-sm" : "w-full"}>
+        {/* INFO: keyed on the mode and layout so switching either one starts a
+            fresh DataTemplate instead of reusing state from the other set of
+            components */}
+        {isMockReady && (
+          <DataTemplateImpl
+            key={`${dtwMode}-${layout}`}
+            title="Scroll Restore"
+            description={`${RECORD_COUNT} offline records`}
+            type={typeParam}
+            id={dataId}
+            collectionId={DEMO_COLLECTION}
+            model={DEMO_SCHEMA}
+            localURLEndpoint=""
+            devSettings={demoDevSettings}
+            lib={{ axios, Menu, Transition, papaParser: Papa }}
+            limit={RECORD_COUNT}
+            organise={{
+              extendedTabs: TABS,
+              viewId: typeParam === "list" ? listViewId : "general",
+              persistViewState: "session",
+              persistKey: listViewId,
+              handleNavigate,
+            }}
+            bareSettings={{
+              bareNewDTW: isNewDTW,
+              bareListMobileView: isMobile,
+              bareUpdateMobileView: isMobile,
+            }}
+          />
+        )}
+      </div>
+    </div>
+  );
+};
+
+export const ScrollRestore = () => (
+  <div className="w-full">
+    <div className="font-semibold mb-1 text-gray-900">
+      Data Template — scroll position restore
+    </div>
+    <div className="text-sm mb-4 text-gray-600">
+      Offline, with {RECORD_COUNT} records. Pick a view, scroll well down, open
+      a record, then go back to the list. You should land on the record you
+      opened, not the top. Each view keeps its own position. Switch between New
+      DTW and Legacy to cover both sets of list components, and Mobile for the
+      mobile table cards and kanban tabs.
+    </div>
+    <ScrollRestoreDemo />
+  </div>
+);