blixify-ui-web-mcp 0.1.3 → 0.1.19

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

@@ -40,6 +40,177 @@ The `model` prop defines the columns/fields. You can build it manually as a `Dat
 
 ---
 
+### Layout: tabs, sections and extended tabs
+
+Three schema-level settings shape how a record is laid out. They nest in one fixed order:
+
+```
+Tab  (DataStructure.tabId)                ← tab bar across the top of the read + update views
+ └─ Section  (DataStructure.groupId)      ← titled card inside the tab; collapsible in the form
+     └─ fields                             ← an object / listObject field renders as a nested
+                                             block or table INSIDE its section — it is a field,
+                                             not a further structural level
+```
+
+- Columns with a `tabId` but no `groupId` sit directly under the tab; columns with
+  neither land in an automatic **Others** tab. Order follows the schema.
+- `extendedTabs` is a different thing: extra **list** views (grid / calendar / kanban /
+  map / report / iframe) rendered as tabs next to the main list — see Extended Tab below.
+  It never appears on a single record.
+- `organise.groupBy` is different again: it splits the **list** into one table per value
+  of a column ("Group By X"), and has nothing to do with `groupId`.
+
+**How a tabbed form is dressed** (`tabAlign: "left"`):
+
+- The rail is a numbered `Stepper` (`variant="checklist"`) — the active step is a filled primary block, and a
+  step whose required fields are all filled shows a tick instead of its number.
+- Each tab's fields open with the tab name and, when `organise.tabDescriptions[tabId]`
+  is set, a one-line description. A horizontal stepper (`tabAlign: "stepper"`) shows
+  `organise.tabShortLabels[tabId]` under each dot on a phone (the tab id itself stays the
+  only key); without short labels only the active step keeps its name there. Each section is a white card with its title and, when
+  `organise.groupDescriptions[groupId]` is set, its own description. The library never
+  paints the page background — the host does (Space uses grey), the cards sit on it.
+- **Every update form and every read view** ends in a sticky, single-row floating bar
+  carrying its actions — Save · Submit on the form, Update (or the app's own component),
+  Export PDF and Log on the read view; a tabbed form adds the navigation cluster to it.
+  The bar's left is reserved for the step navigation; the actions group on the right,
+  Delete first (an icon on phones), then Save · Submit / Export PDF · Log · Update. The
+  header keeps only the title. Success toasts clear themselves after 4 s and, on phones,
+  appear at the bottom lifted above the bar. It is the form's only action bar —
+  a floating pill (rounded, shadow, lifted off the bottom edge, stretched into the page
+  margin on phones), 60 px tall on desktop and phone. Left cluster is navigation —
+  `‹ Previous · Step x of y · Next ›` (icons and `x/y` on a phone); Next moves to the
+  next tab, saving a draft silently first when `bareSaveOnTabChange` is on, and is
+  disabled on the last tab. Right cluster is actions — `Save · Submit`; Submit is
+  reachable on every step and is the one filled (primary) button. The header row keeps only Delete. `bareUpdateActionComponent`, when
+  set, takes the place of Save / Submit (navigation stays); return an empty fragment to
+  hide the library's buttons — the bar is then dropped on a plain form and keeps only its
+  navigation on a tabbed one. `bareUpdateActionBottom` swaps the pill for a plain
+  right-aligned row (same buttons, no border / shadow / sticky) — use it for short forms
+  inside a `Modal`, where the pill would be a card inside a card. Inside a `Modal` without
+  `overflowScroll` the panel is `overflow-hidden`, so the pill sits at the end of the form
+  instead of floating.
+- `listObject` tables inside the form render their inputs in cell mode (16 px text,
+  low padding) so a checklist row is ~44 px, the same as an editable list row.
+
+**Saving: create, update, drafts, auto-save**
+
+- `id="new"` (or no id) → **create**; any other id → **update** of that record. The toast says
+  "Created Successfully" / "Updated Successfully"; with `enableUpdateDraft` a draft save
+  says "Draft Saved" instead.
+- `edit.enableUpdateDraft: true` adds **Save** (draft, `baseDraft: true`) next to Submit.
+- `bareSettings.bareSaveOnTabChange: true` is the **auto-save**: Next / Previous write a draft
+  before moving, silently. Only an explicit Save or Submit shows a toast.
+- `bareSettings.bareUpsertPartialUpdate: true` turns the update into an upsert by id that sends
+  only the changed fields, and **skips the write when nothing changed** — so a Next on an
+  untouched tab costs no request. Without it every save writes the full record and toasts,
+  changed or not.
+  The API behind the collection must accept a partial document (an upsert by id that
+  `$set`s only the sent fields) — Verdant's `mongoData` route does; check before turning it
+  on elsewhere.
+
+**Offline mode** (`bareOffline`, the Meraque work-order checklist pattern)
+
+```
+mount (online)   ─▶ prefetch latest N docs + bareOfflineReferences ─▶ IndexedDB store "local"
+                                                                       key = collectionId
+save             ─▶ online  → server (with bareOfflineNetworkListener)
+                 ─▶ offline → IndexedDB, stamped { baseOnline:false, syncStatus:"pending", dirtySections }
+ref.handleUploadOfflineData() ─▶ every pending doc → server (diffed against the baseline it was
+                                 loaded with, 300 ms apart) ─▶ marked synced
+```
+
+- The DTW does the prefetch, the local reads, the local writes and the upload; the app owns the
+  _policy_: when to go offline, when to sync, what to tell the user. Meraque keeps an `offline`
+  state, shows a banner ("Going offline? Sync data required…" / "You're in offline mode." /
+  "Data synced. Ready for offline."), passes `bareOffline: offline`, and calls
+  `dtwRef.current.handleUploadOfflineData()` when the connection is back.
+- Prefetch never overwrites pending local edits — pending docs win over the server copy of the
+  same id. Reference collections listed in `bareOfflineReferences` are what make reference
+  fields (team, pilot, robot…) selectable with no network.
+- Story: `Data / Data Wrapper / Consumer Fixtures / Meraque · Work Order (Offline)` — prefetch,
+  an offline toggle, an offline save and Sync now, all mocked in the page.
+- This is a feature, not a test harness — stories fake the server with `axios-mock-adapter`
+  instead (see the Consumer Fixtures file).
+
+**Dark mode** — `organise.darkMode: true` darkens everything DataTemplate renders: list
+chrome, tables and lists, the update form's section cards and **every input's field** (not
+just its label — text, textarea, select and its dropdown, date, checkbox and radio boxes),
+the read view's cards, modals, the drawer, toasts and the floating action bar. Pass
+`organise.darkModeBg` with the class your page already uses (`"bg-neutral-900"`) and those
+surfaces adopt it; without it they fall back to `bg-gray-900`. Story: `Consumer Fixtures /
+Dark Mode` (Sales Leads list + KPJ form on a Meraque-style page).
+
+**Wide tables** — every table scrolls inside a `ScrollShadow`: a soft fade on the edge
+that still hides columns, gone at the end of the scroll, over a thin always-visible
+scrollbar. `listObject` tables inside a form also pin their first column
+(`FlexTable pinColumns`, the same `{ left, right }` shape as `NewTable`) so the row label stays put.
+
+**Sheet habits in `NewTable`** (`bareNewDTW`):
+
+- A `list` column with `listSelectionColour` paints the whole cell in the value's
+  colour with contrasting text; in an editable table one tap on it enters the row's inline
+  edit and opens that cell's ordinary `Select`, its options in the same colours — picking one
+  commits a single update. Colour keys are the Tag palette (`red`, `blue`, `green`, `yellow`, `indigo`,
+  `dark`, `default`).
+  In a read-only table (`listEditable` off — the wrapper default) that cell is the same
+  filled `Select` an editable table shows, just disabled, so it looks identical in both modes
+  and the row click still opens the record.
+- `organise.groupBy` keeps rows in **one** table: each group is a tinted, collapsible band
+  (chevron, title, count) in the grouping column's colour, and its rows carry the same
+  colour as a bar down their left edge. Legacy `Table` keeps the separate-tables layout.
+- Row selection gains **Shift-click** (extend from the last clicked row), **drag** down
+  the checkbox column (paint a range), **Esc** (clear), and a **Copy** action on the
+  floating bar that writes the selected rows' visible columns as TSV to the clipboard
+  (`enableCopy={false}` hides it).
+
+**Field polish** — a `list` shown as radios (`listView: "radioview"`) with more than six
+options lays out in two columns; a `boolean` with `enableRadioButtons` renders as
+Yes / No pills; `TextInput` / `TextArea` show a character counter whenever `maxLength`
+is set.
+
+None of these carry a colour of their own. Everything coloured follows the theme's
+primary: the active tab's underline (`border-primary-500 text-primary-600`) and, in the
+update form only, the light `bg-primary-50` tint behind a collapsible section. Read-view
+section cards are plain white. Per-value colour exists only on `list` / `multipleList`
+columns via `listSelectionColour`.
+
+A worked example is Blixify Space's KPJ **Projects** space: every column carries a lettered
+`tabId` (`A. Research Identification` … `P. Applicant Endorsement`) plus a `groupId`
+(`Research Details`, `Application Details`, …), and its `kpjuResearchers` listObject shows
+as a nested table inside the _Applicants' Details_ section.
+
+## View Settings
+
+One panel behind the sliders icon carries every list-view setting — it replaces the old
+Slice Data, Model Overview and Sort modals and the desktop-only header drag.
+
+| Section       | What it does                                                                                                                                     |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Columns       | search the column list, drag a handle to reorder, eye / eye-slash to hide. The last visible column stays locked so the table always has a header |
+| Sort          | pick the column and the direction — the only sort UI on a phone, where the table renders cards with no headers                                   |
+| Rows per page | 10 / 25 / 50 / 100, persisted with the rest of the view state                                                                                    |
+
+The column list is the only scrolling region (capped height with a `ScrollShadow`), so Sort
+and Rows per page stay in view on a collection with dozens of fields. Desktop opens a
+popover; a phone opens a modal, since the popover cannot fit the panel inside the viewport.
+
+The panel is standard under `bareNewDTW`; `bareSettings.bareViewSettings` opts a legacy or bare
+DTW into it. There are no separate sort / filter / drag flags — the feature carries all three,
+and per-column filtering comes from `bareFlexFilters`.
+
+The table header carries the same actions for the column you are pointing at: sort, and a hide
+button revealed on hover so a wide header stays clean (the sort icon stays visible because it
+also reports the current sort). Reordering has no icon — the header shows a grab cursor and
+the panel carries an explicit handle. Both run the same
+reorder and hide as the panel, so the result persists identically whichever one is used. The
+panel remains the only surface on a phone, where the card view has no headers.
+
+Hide and reorder are **per user** by default, kept in `persistViewState`. Wire
+`organise.onChangeHide` / `organise.onChangeDrag` and the panel switches to **schema mode**:
+the change is written to the model and handed to the consumer to persist for everyone — which
+is what a Space-backed DTW wants.
+
 ## Step-by-Step Setup
 
 **1. Install peer dependencies**
@@ -98,7 +269,7 @@ Or derive it from a Workspace object:
 import { parseWorkspaceSettings } from "blixify-ui-web/data/utils";
 const devSettings = parseWorkspaceSettings(
   { dbEndpoint, imageEndpoint, uploadEndpoint },
-  workspaceObject
+  workspaceObject,
 );
 ```
 
@@ -108,7 +279,7 @@ const devSettings = parseWorkspaceSettings(
 const handleNavigate = (
   nextType: string,
   selectedId?: string,
-  nextViewId?: string
+  nextViewId?: string,
 ) => {
   setType(nextType);
   if (selectedId !== undefined) setId(selectedId);
@@ -241,6 +412,8 @@ Set `organise.viewId="calendar"` and add an `extendedTabs` entry with `calendarS
 
 ### Grid view
 
+Under `bareNewDTW` the grid hides `Grid`'s own page buttons and renders the same `NewPagination` footer as the table and list views.
+
 Set `organise.viewId="grid"` (or add an `extendedTabs` entry with `viewType="grid"`) to render records as image cards. Use `bareSettings.bareListGridComponent` to fully customise each card, or use the built-in grid with `viewImage` pointing to an image column.
 
 ```tsx
@@ -335,6 +508,8 @@ Set `organise.viewId="list"` to render records as a vertical list instead of a t
 
 ### Kanban view
 
+On phones (`bareListMobileView`) the columns become a tab rail with one column visible; the first column is selected as soon as data arrives, and cards move by long-press onto another tab. Cards, rail and columns follow `organise.darkMode`.
+
 Set `viewType="kanban"` on an `extendedTabs` entry and configure `kanbanSettings` to define which column drives the board columns. `title` is the column ID shown on each card; `groupCluster` maps column names to the list-selection values that belong in that column.
 
 ```tsx
@@ -536,6 +711,27 @@ Enable `organise.exportSettings.enableExportReadPDF` to add a PDF export button
 
 ---
 
+## Stacking (z-index) Layers
+
+The layers every DataTemplate surface stacks in, lowest to highest. Anything that floats
+must sit above the sticky action bar (`z-20`) and below overlays/modals.
+
+| Layer          | Components                                                                                                                                                                                             |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `z-0` – `z-10` | In-flow accents: sticky table headers / pinned columns (`z-10`–`z-20` in FlexTable), stepper rail, grid/list image overlays, modal sticky title (`z-10`)                                               |
+| `z-20`         | **DataTemplate sticky action bar** (form + read view), stepper connectors, date-picker mobile overlay                                                                                                  |
+| `z-30`         | Floating pieces that must clear the action bar: **Select option list**, `PopUp` panels (filters, ⋮ menu, select-all), drawer root, page `Header` / `BottomTab` / `LeftNav`, legacy list/table popovers |
+| `z-[35]`       | Drawer sticky header (above its own content, below a Modal)                                                                                                                                            |
+| `z-40`         | **Modal** (overlay + panel) — deliberately above the drawer (`z-30`) so a modal opened from a drawer wins                                                                                              |
+| `z-50`         | Toasts (**Notification**), calendar day popup, kanban drag ghost, row hover tooltips, markdown editor menus, onboarding                                                                                |
+| `z-[51]`       | Stepper description popover (above toasts so it stays readable)                                                                                                                                        |
+| `z-[100]`      | DataTemplate fixed utilities: offline sync badge, scroll-to-top                                                                                                                                        |
+| `z-[9999]`     | App-level attention layers: `Bars` celebration overlay, `InfoWindow`                                                                                                                                   |
+
+Rules of thumb: a dropdown or popover opened from inside the form → `z-30`; anything modal →
+`z-40`; transient feedback (toast, drag ghost, tooltip) → `z-50`; never introduce a new value
+without placing it in this table.
+
 ## Utility Functions
 
 ### `parseSpaceToDataStructure(space: Space): DataStructure[]`
@@ -562,7 +758,7 @@ const devSettings = parseWorkspaceSettings(
     imageEndpoint: process.env.IMAGE_ENDPOINT,
     uploadEndpoint: process.env.UPLOAD_ENDPOINT,
   },
-  workspaceObject // optional — overrides defaults when provided
+  workspaceObject, // optional — overrides defaults when provided
 );
 ```
 
@@ -572,7 +768,8 @@ const devSettings = parseWorkspaceSettings(
 
 | Method                             | Description                                                       |
 | ---------------------------------- | ----------------------------------------------------------------- |
-| `handleRefresh()`                  | Re-fetches the current list data                                  |
+| `handleRefresh()`                  | Re-fetches the current list data, resetting pagination to page 1  |
+| `handleRefreshCurrentPage()`       | Re-fetches in place, keeping page index, cursor, and filters      |
 | `handleFormSubmit()`               | Programmatically submits the update/create form                   |
 | `handleFormCheck()`                | Validates the form without submitting                             |
 | `handlePopUpModal()`               | Opens the create/update modal                                     |
@@ -595,26 +792,27 @@ const devSettings = parseWorkspaceSettings(
 
 ### Optional props
 
-| Name             | Type                                    | Default | Description                                                                                              |
-| ---------------- | --------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------- |
-| `id`             | `string`                                | `""`    | Selected record ID. Pass `"new"` to open a blank create form                                             |
-| `limit`          | `number`                                | `10`    | Records per page in list view                                                                            |
-| `space`          | `Space`                                 | —       | Full Space object from Blixify Space — enables extended features like tabs, sort, and additional queries |
-| `edit`           | `Edit`                                  | —       | Controls create/update/delete permissions — see Edit below                                               |
-| `organise`       | `Organise`                              | —       | Controls view, sort, filter, tabs, export, and navigation — see Organise below                           |
-| `bareSettings`   | `BareSettings`                          | —       | Injects custom React components and callbacks into list/read/update views — see BareSettings below       |
-| `renderSettings` | `RenderSettings`                        | —       | Overrides the entire list UI or loading UI with custom renderers                                         |
-| `roles`          | `string[]`                              | —       | Role strings (reserved for future permission checks)                                                     |
-| `darkMode`       | `boolean`                               | —       | Applies dark colour scheme                                                                               |
-| `uniqueLabel`    | `string`                                | —       | Unique label appended to internal query keys to avoid collisions                                         |
-| `groupId`        | `string`                                | —       | Groups list results by this field. Grouped items are returned with a `children` array                    |
-| `defaultTab`     | `any`                                   | —       | Pre-selects a tab on mount                                                                               |
-| `workspaceId`    | `string`                                | —       | Workspace ID (used for workspace-scoped operations)                                                      |
-| `newTabUrl`      | `{ default?: string; addons?: string }` | —       | URL config for row links. `default` is the base URL; `addons` is appended after the record id            |
-| `lib`            | `LibSettings`                           | —       | External library instances — see lib below                                                               |
-| `linkProps`      | `LinkProps`                             | —       | Refer to Link component documentation                                                                    |
-| `onComplete`     | `(id: string) => void`                  | —       | Called after a create/update operation completes                                                         |
-| `onLoadIframe`   | `() => void`                            | —       | Called when an iframe tab finishes loading                                                               |
+| Name             | Type                                    | Default                                                                                                                                                                                                                                                                                             | Description                                                                                              |
+| ---------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `id`             | `string`                                | `""`                                                                                                                                                                                                                                                                                                | Selected record ID. Pass `"new"` to open a blank create form                                             |
+| `limit`          | `number`                                | `10`                                                                                                                                                                                                                                                                                                | Records per page in list view                                                                            |
+| `space`          | `Space`                                 | —                                                                                                                                                                                                                                                                                                   | Full Space object from Blixify Space — enables extended features like tabs, sort, and additional queries |
+| `edit`           | `Edit`                                  | —                                                                                                                                                                                                                                                                                                   | Controls create/update/delete permissions — see Edit below                                               |
+| `organise`       | `Organise`                              | —                                                                                                                                                                                                                                                                                                   | Controls view, sort, filter, tabs, export, and navigation — see Organise below                           |
+| `bareSettings`   | `BareSettings`                          | —                                                                                                                                                                                                                                                                                                   | Injects custom React components and callbacks into list/read/update views — see BareSettings below       |
+| `renderSettings` | `RenderSettings`                        | —                                                                                                                                                                                                                                                                                                   | Overrides the entire list UI or loading UI with custom renderers                                         |
+| `roles`          | `string[]`                              | —                                                                                                                                                                                                                                                                                                   | Role strings (reserved for future permission checks)                                                     |
+| `darkMode`       | `boolean`                               | —                                                                                                                                                                                                                                                                                                   | Applies dark colour scheme                                                                               |
+| `darkModeBg`     | `string`                                | The app's own dark surface class (e.g. `"bg-neutral-900"`). With `darkMode`, every panel DataTemplate paints — modals, tables, lists, section cards, read-view cards, the drawer, the floating action bar — uses it instead of the default `bg-gray-900`, so nothing comes out navy on a black page |
+| `uniqueLabel`    | `string`                                | —                                                                                                                                                                                                                                                                                                   | Unique label appended to internal query keys to avoid collisions                                         |
+| `groupId`        | `string`                                | —                                                                                                                                                                                                                                                                                                   | Groups list results by this field. Grouped items are returned with a `children` array                    |
+| `defaultTab`     | `any`                                   | —                                                                                                                                                                                                                                                                                                   | Pre-selects a tab on mount                                                                               |
+| `workspaceId`    | `string`                                | —                                                                                                                                                                                                                                                                                                   | Workspace ID (used for workspace-scoped operations)                                                      |
+| `newTabUrl`      | `{ default?: string; addons?: string }` | —                                                                                                                                                                                                                                                                                                   | URL config for row links. `default` is the base URL; `addons` is appended after the record id            |
+| `lib`            | `LibSettings`                           | —                                                                                                                                                                                                                                                                                                   | External library instances — see lib below                                                               |
+| `linkProps`      | `LinkProps`                             | —                                                                                                                                                                                                                                                                                                   | Refer to Link component documentation                                                                    |
+| `onComplete`     | `(id: string) => void`                  | —                                                                                                                                                                                                                                                                                                   | Called after a create/update operation completes                                                         |
+| `onLoadIframe`   | `() => void`                            | —                                                                                                                                                                                                                                                                                                   | Called when an iframe tab finishes loading                                                               |
 
 ### lib
 
@@ -668,6 +866,36 @@ const devSettings = parseWorkspaceSettings(
 | `disabledTabsDeleteBtn` | `boolean`     | Disables the delete button inside extended tabs          |
 | `activityLog`           | `ActivityLog` | See ActivityLog below                                    |
 
+#### Inline editability matrix (`listEditable`)
+
+Which field types can be edited from the list table, and how. Types not listed under
+"Never rendered" appear as read-only cells when they are not editable.
+
+| Edited **in the cell**                                                                                                                                                                                                   | Edited **in a modal** (cell click opens it)                                                                                 | Read-only in list             | Never rendered as a list column |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- | ----------------------------- | ------------------------------- |
+| `string`, `contact`, `email`, `textArea`, `number`, `boolean` (checkbox and radio commit on select), `date`, `list`, `multipleList`, `person`, `listPerson`, `roles`, `reference`, `listReference`, `referenceSelection` | `image`, `multipleImage`, `address`, `object`, `listObject`, `markdown`, `signature`, `file`, `multipleFile`, `listAddress` | `math` (computed), `password` | `canvas`, `ganttchart`          |
+
+- **Why some types edit in a modal:** their editor is bigger than one line. An
+  `address` is a Places autocomplete plus a map with a draggable pin plus
+  country/state/district fields; `image` / `multipleImage` are an upload area
+  with previews; `object` / `listObject` are a nested form. None of that fits a
+  table cell, so the cell shows the value (or `Add`) and a click opens the same
+  editor the update view uses. Keep them there — an inline variant would have to
+  drop the map / previews / nested fields to fit.
+- Inline commits fire **one single-column update on blur**, and only when the value
+  actually changed — an untouched blur fires nothing.
+- `reference` / `listReference` options load with **one call per cell focus** (the
+  select's own fetch — the table adds none of its own); typing searches
+  server-side, debounced.
+- Reference labels — top-level **and** nested inside `object` / `listObject` —
+  are resolved once at list load, one query per referenced collection, and seed
+  both the inline cell and the object editor; nothing is fetched on open.
+- An `object` cell prints every readable field joined with `·`
+  (`Blixify Sdn Bhd · Admin`), with nested reference ids already swapped for labels.
+- Modal saves go through the same single-column update; Cancel and no-change saves
+  fire nothing.
+- See the `DTW Inline Edit Matrix` story for a live fixture with every type.
+
 ### ActivityLog
 
 | Name                  | Type      | Description                                                                                       |
@@ -683,57 +911,55 @@ const devSettings = parseWorkspaceSettings(
 
 ### Organise
 
-| Name                          | Type                                                                        | Description                                                                                  |
-| ----------------------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| `sort`                        | `Sort`                                                                      | Default sort applied to list queries                                                         |
-| `pageIndex`                   | `number`                                                                    | Initial page index                                                                           |
-| `viewId`                      | `string`                                                                    | Active view type: `"general"`, `"calendar"`, `"grid"`, `"list"`, `"feeds"`, `"kanban"`, etc. |
-| `idField`                     | `string`                                                                    | DataStructure column ID whose value becomes the new record's ID on creation                  |
-| `extendedTabs`                | `ExtendedTabs[]`                                                            | Additional tabs rendered alongside the main view — see Extended Tab below                    |
-| `additionalQuery`             | `AdditionalQuery[]`                                                         | Filter/search controls rendered above the list — see Additional Query below                  |
-| `darkMode`                    | `boolean`                                                                   | Applies dark colour scheme to the organise bar                                               |
-| `hideSearch`                  | `boolean`                                                                   | Hides the search input                                                                       |
-| `hidePagination`              | `boolean`                                                                   | Hides pagination on Table, List, Grid, and Feeds views                                       |
-| `hideNewTabs`                 | `boolean`                                                                   | Hides the new-tab creation button                                                            |
-| `splitView`                   | `boolean`                                                                   | Renders a split list/detail layout in read mode                                              |
-| `listObjectTableView`         | `boolean`                                                                   | Shows list objects in table view during read and update                                      |
-| `disableMulti`                | `boolean`                                                                   | Disables multi-row selection                                                                 |
-| `disableSelectFullData`       | `{ table?: boolean; list?: boolean }`                                       | Disables "select all pages" for table and/or list views                                      |
-| `disabledOnEnter`             | `boolean`                                                                   | Prevents Enter key from submitting forms                                                     |
-| `breadcrumbType`              | `"button" \| "hidden"`                                                      | `"button"` shows a back button; `"hidden"` hides the breadcrumb entirely                     |
-| `breadcrumbAttributeId`       | `string`                                                                    | Column ID whose value is used as the breadcrumb label in read view                           |
-| `tabAlign`                    | `"top" \| "left" \| "stepper"`                                              | Tab layout direction                                                                         |
-| `groupRead`                   | `"groupId"`                                                                 | Groups and separates read view sections by DataStructure `groupId`                           |
-| `showCollapsibleTab`          | `boolean`                                                                   | Renders tabs as collapsible sections                                                         |
-| `showBaseUpdatedAt`           | `boolean`                                                                   | Shows the `baseUpdatedAt` timestamp in Table, Grid, List, and Kanban views                   |
-| `showGroupByFeature`          | `boolean`                                                                   | Shows the group-by selector in the toolbar                                                   |
-| `showReadFloatingNav`         | `boolean`                                                                   | Shows a floating section navigator in read view                                              |
-| `showExport`                  | `boolean`                                                                   | Shows import/export options (default `true`)                                                 |
-| `disableEllipsisOnLongWord`   | `boolean`                                                                   | Wraps long text instead of truncating with ellipsis                                          |
-| `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                                               |
-| `advSortEnabled`              | `boolean`                                                                   | Shows advanced sort controls                                                                 |
-| `advFilterEnabled`            | `boolean`                                                                   | Shows advanced filter controls                                                               |
-| `advDragEnabled`              | `boolean`                                                                   | Enables drag-to-reorder columns                                                              |
-| `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                                                         |
-| `unionCollections`            | `any[]`                                                                     | Additional collections to union-query alongside the main collection                          |
-| `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                                                        |
-| `onChangeFilter`              | `(value: AdditionalQuery[]) => void`                                        | Called when the user changes filters                                                         |
-| `onChangeHide`                | `(value: DataStructure[]) => void`                                          | Called when the user hides/shows columns                                                     |
-| `onChangeDrag`                | `(dragId: string, dropId: string, newHeader: TableHeader[]) => void`        | Called after a column is reordered                                                           |
-| `onChangeTabs`                | `(value: ExtendedTabs[]) => void`                                           | Called when tabs are added/removed/reordered                                                 |
-| `onChangePagination`          | `(page: number) => void`                                                    | Called when the page changes                                                                 |
-| `onAddColumns`                | `(model: DataStructure[]) => void`                                          | Called when a new column is added                                                            |
-| `handleNavigate`              | `(type: string, selectedId?: string, viewId?: string) => void`              | Called when the component needs to navigate (e.g. row click → read view)                     |
-| `handleCustomDownloadFile`    | `(url: string, fileName?: string) => void`                                  | Overrides the default file download behaviour                                                |
-| `renderReferenceLabelOptions` | `(spaceId?: string, includeReference?: boolean, type?: string) => Option[]` | Returns column options for reference label selectors                                         |
-| `renderReferenceSpaceOptions` | `() => Option[]`                                                            | Returns space options for reference space selectors                                          |
-| `renderGroupByOptions`        | `() => Option[]`                                                            | Returns custom options for the group-by selector                                             |
+| Name                          | Type                                                                        | Description                                                                                                                                                                                                                                                                                                           |
+| ----------------------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `sort`                        | `Sort`                                                                      | Default sort applied to list queries                                                                                                                                                                                                                                                                                  |
+| `pageIndex`                   | `number`                                                                    | Initial page index                                                                                                                                                                                                                                                                                                    |
+| `viewId`                      | `string`                                                                    | Active view type: `"general"`, `"calendar"`, `"grid"`, `"list"`, `"feeds"`, `"kanban"`, etc.                                                                                                                                                                                                                          |
+| `idField`                     | `string`                                                                    | DataStructure column ID whose value becomes the new record's ID on creation                                                                                                                                                                                                                                           |
+| `extendedTabs`                | `ExtendedTabs[]`                                                            | Additional tabs rendered alongside the main view — see Extended Tab below                                                                                                                                                                                                                                             |
+| `additionalQuery`             | `AdditionalQuery[]`                                                         | Filter/search controls rendered above the list — see Additional Query below                                                                                                                                                                                                                                           |
+| `darkMode`                    | `boolean`                                                                   | Applies dark colour scheme to the organise bar                                                                                                                                                                                                                                                                        |
+| `hideSearch`                  | `boolean`                                                                   | Hides the search input                                                                                                                                                                                                                                                                                                |
+| `hidePagination`              | `boolean`                                                                   | Hides pagination on Table, List, Grid, and Feeds views                                                                                                                                                                                                                                                                |
+| `hideNewTabs`                 | `boolean`                                                                   | Hides the new-tab creation button                                                                                                                                                                                                                                                                                     |
+| `splitView`                   | `boolean`                                                                   | Renders a split list/detail layout in read mode                                                                                                                                                                                                                                                                       |
+| `listObjectTableView`         | `boolean`                                                                   | Shows list objects in table view during read and update                                                                                                                                                                                                                                                               |
+| `disableMulti`                | `boolean`                                                                   | Disables multi-row selection                                                                                                                                                                                                                                                                                          |
+| `disableSelectFullData`       | `{ table?: boolean; list?: boolean }`                                       | Disables "select all pages" for table and/or list views                                                                                                                                                                                                                                                               |
+| `disabledOnEnter`             | `boolean`                                                                   | Prevents Enter key from submitting forms                                                                                                                                                                                                                                                                              |
+| `breadcrumbType`              | `"button" \| "hidden"`                                                      | `"button"` shows a back button; `"hidden"` hides the breadcrumb entirely                                                                                                                                                                                                                                              |
+| `breadcrumbAttributeId`       | `string`                                                                    | Column ID whose value is used as the breadcrumb label in read view                                                                                                                                                                                                                                                    |
+| `tabAlign`                    | `"top" \| "left" \| "stepper"`                                              | Tab layout direction                                                                                                                                                                                                                                                                                                  |
+| `groupRead`                   | `"groupId"`                                                                 | Groups and separates read view sections by DataStructure `groupId`                                                                                                                                                                                                                                                    |
+| `showCollapsibleTab`          | `boolean`                                                                   | Renders tabs as collapsible sections                                                                                                                                                                                                                                                                                  |
+| `showBaseUpdatedAt`           | `boolean`                                                                   | Shows the `baseUpdatedAt` timestamp in Table, Grid, List, and Kanban views                                                                                                                                                                                                                                            |
+| `showGroupByFeature`          | `boolean`                                                                   | Shows the group-by selector in the toolbar                                                                                                                                                                                                                                                                            |
+| `showReadFloatingNav`         | `boolean`                                                                   | Shows a floating section navigator in read view                                                                                                                                                                                                                                                                       |
+| `showExport`                  | `boolean`                                                                   | Shows import/export options (default `true`)                                                                                                                                                                                                                                                                          |
+| `disableEllipsisOnLongWord`   | `boolean`                                                                   | Wraps long text instead of truncating with ellipsis                                                                                                                                                                                                                                                                   |
+| `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`            | `"session" \| "local"`                                                      | Remembers the list's sort, filters, hidden columns, page and search in `sessionStorage` / `localStorage` per collection, so a Back navigation lands where the user left                                                                                                                                               |
+| `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                                                                                                                                                                                                                                                                                  |
+| `unionCollections`            | `any[]`                                                                     | Additional collections to union-query alongside the main collection                                                                                                                                                                                                                                                   |
+| `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                                                                                                                                                                                                                                                                                 |
+| `onChangeHide`                | `(value: DataStructure[]) => void`                                          | Called when a column is hidden from the view settings panel. Providing it switches the panel to schema mode — the hide is written to the model for everyone instead of being this user's own                                                                                                                          |
+| `onChangeDrag`                | `(dragId: string, dropId: string, newHeader: TableHeader[]) => void`        | Called after a column is reordered in the view settings panel, so the consumer can persist the order                                                                                                                                                                                                                  |
+| `onChangeTabs`                | `(value: ExtendedTabs[]) => void`                                           | Called when tabs are added/removed/reordered                                                                                                                                                                                                                                                                          |
+| `onChangePagination`          | `(page: number) => void`                                                    | Called when the page changes                                                                                                                                                                                                                                                                                          |
+| `customPaginationCount`       | `(pageDataCount: number) => void`                                           | Called after each data fetch with the actual record count. Use this to override the count shown in the pagination bar — store the value in your own state and pass it back via `customPaginationSize` on `Table`, `Grid`, `List`, or `Pagination` if needed, or use it to display a custom count elsewhere in your UI |
+| `onAddColumns`                | `(model: DataStructure[]) => void`                                          | Called when a new column is added                                                                                                                                                                                                                                                                                     |
+| `handleNavigate`              | `(type: string, selectedId?: string, viewId?: string) => void`              | Called when the component needs to navigate (e.g. row click → read view)                                                                                                                                                                                                                                              |
+| `handleCustomDownloadFile`    | `(url: string, fileName?: string) => void`                                  | Overrides the default file download behaviour                                                                                                                                                                                                                                                                         |
+| `renderReferenceLabelOptions` | `(spaceId?: string, includeReference?: boolean, type?: string) => Option[]` | Returns column options for reference label selectors                                                                                                                                                                                                                                                                  |
+| `renderReferenceSpaceOptions` | `() => Option[]`                                                            | Returns space options for reference space selectors                                                                                                                                                                                                                                                                   |
+| `renderGroupByOptions`        | `() => Option[]`                                                            | Returns custom options for the group-by selector                                                                                                                                                                                                                                                                      |
 
 ### Export Settings
 
@@ -789,50 +1015,62 @@ const devSettings = parseWorkspaceSettings(
 
 Injects custom React components and callbacks into the list, read, and update views.
 
-| Name                                     | Type                                                                                  | Description                                                                                     |
-| ---------------------------------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
-| `bareReadComponent`                      | `(data: any) => any`                                                                  | Custom component rendered in read view                                                          |
-| `bareReadComponentPos`                   | `"top"`                                                                               | Renders `bareReadComponent` above the default read content                                      |
-| `bareReadComponentHide`                  | `boolean`                                                                             | Hides the default read content (shows only `bareReadComponent`)                                 |
-| `bareReadReferenceView`                  | `(dataId, collectionId, attributeId) => boolean \| void`                              | Controls whether a reference field opens a view                                                 |
-| `bareReadDescription`                    | `(key: string, value: any) => any`                                                    | Custom renderer for read view field values                                                      |
-| `bareReadHandleData`                     | `(data: any) => void`                                                                 | Called when read view data is loaded                                                            |
-| `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                                                    |
-| `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                                                              |
-| `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                                                                 |
-| `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                                        |
-| `bareListDescription`                    | `(key: string, value: any) => any`                                                    | Custom renderer for list view field values                                                      |
-| `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                                                |
-| `bareUpdateComponentAbove`               | `boolean`                                                                             | Renders `bareUpdateComponent` above the default form fields                                     |
-| `bareUpdateActionComponent`              | `(data: any, formRef?: any) => any`                                                   | Custom action buttons rendered in the update form footer                                        |
-| `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                                                      |
-| `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`                                                                             | Renders action buttons at the bottom of the form                                                |
-| `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                                          |
-| `bareUpdateMobileView`                   | `boolean`                                                                             | Renders the update form in mobile-optimised layout                                              |
-| `bareOffline`                            | `boolean`                                                                             | Enables offline data caching via IndexedDB                                                      |
-| `bareCSVImportEndpoint`                  | `string`                                                                              | Custom CSV import endpoint                                                                      |
-| `bareCSVExportEndpoint`                  | `string`                                                                              | Custom CSV export endpoint                                                                      |
-| `bareHideTableExtraMultipleAction`       | `boolean`                                                                             | Hides the extra multiple-action button in table view                                            |
+| Name                                     | Type                                                                                  | Description                                                                                                                                                                                                   |
+| ---------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `bareViewSettings`                       | `boolean`                                                                             | Turns on the view settings feature — the panel (columns hide / reorder / search, sort, rows per page) and the hide, drag and sort controls in the table header. Always on under `bareNewDTW`                  |
+| `bareReadComponent`                      | `(data: any) => any`                                                                  | Custom component rendered in read view                                                                                                                                                                        |
+| `bareReadComponentPos`                   | `"top"`                                                                               | Renders `bareReadComponent` above the default read content                                                                                                                                                    |
+| `bareReadComponentHide`                  | `boolean`                                                                             | Hides the default read content (shows only `bareReadComponent`)                                                                                                                                               |
+| `bareReadReferenceView`                  | `(dataId, collectionId, attributeId) => boolean \| void`                              | Controls whether a reference field opens a view                                                                                                                                                               |
+| `bareReadDescription`                    | `(key: string, value: any) => any`                                                    | Custom renderer for read view field values                                                                                                                                                                    |
+| `bareReadHandleData`                     | `(data: any) => void`                                                                 | Called when read view data is loaded                                                                                                                                                                          |
+| `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                                                                                                                                                                  |
+| `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                                                                                                                                                                            |
+| `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                                                                                                                                                                               |
+| `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                                                                                                                                                      |
+| `bareListDescription`                    | `(key: string, value: any) => any`                                                    | Custom renderer for list view field values                                                                                                                                                                    |
+| `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                                                                                                                                                              |
+| `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                                                                                                                                                      |
+| `bareFlexFilters`                        | `boolean`                                                                             | Funnel icon opens the Filters builder (column · condition · value, values from the schema) — replaces hand-rolled page filters; new table only                                                                |
+| `bareListFilterAsPopup`                  | `boolean`                                                                             | Shows the list's filter inputs in a popup instead of the header row                                                                                                                                           |
+| `bareListTablePinColumns`                | `{ left?: string[]; right?: string[] }`                                               | Columns kept sticky at the edges while the table scrolls sideways (`"update"` is the actions column); new table only                                                                                          |
+| `bareListMobileView`                     | `boolean`                                                                             | Phone card list instead of the table (the app passes its own isMobile)                                                                                                                                        |
+| `bareListMobileFloatingSearch`           | `boolean`                                                                             | Floating search bar at the bottom on phones; the list reserves room under its last row for it                                                                                                                 |
+| `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                                                                                                                                                                    |
+| `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                                                                                                                                                        |
+| `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()` |
+| `bareOfflinePrefetchLimit`               | `number`                                                                              | With `bareOffline`: how many of the collection's latest docs to download into IndexedDB on mount (default 10)                                                                                                 |
+| `bareOfflineReferences`                  | `Array<{ collectionId: string; limit?: number }>`                                     | With `bareOffline`: reference collections to download on mount so reference dropdowns keep working offline                                                                                                    |
+| `bareCSVImportEndpoint`                  | `string`                                                                              | Custom CSV import endpoint                                                                                                                                                                                    |
+| `bareCSVExportEndpoint`                  | `string`                                                                              | Custom CSV export endpoint                                                                                                                                                                                    |
+| `bareHideTableExtraMultipleAction`       | `boolean`                                                                             | Hides the extra multiple-action button in table view                                                                                                                                                          |
 
 ### Extended Tab
 
@@ -863,19 +1101,81 @@ Injects custom React components and callbacks into the list, read, and update vi
 
 ### Calendar Settings
 
-| Name               | Type                 | Description                                                      |
-| ------------------ | -------------------- | ---------------------------------------------------------------- |
-| `title`            | `string`             | Column ID for event title                                        |
-| `startDate`        | `string`             | Column ID for event start date                                   |
-| `endDate`          | `string`             | Column ID for event end date                                     |
-| `defaultStartDate` | `Date`               | Default calendar start date                                      |
-| `customView`       | `CalendarCustomView` | Custom calendar view config                                      |
-| `groupId`          | `string`             | Column ID — events with the same value share a background colour |
-| `groupColor`       | `Color[]`            | Background colours for groups                                    |
-| `customHeader`     | `string`             | Custom title replacing the default calendar header               |
+| Name               | Type                       | Description                                                                                               |
+| ------------------ | -------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `title`            | `string`                   | Column ID for event title                                                                                 |
+| `startDate`        | `string`                   | Column ID for event start date                                                                            |
+| `endDate`          | `string`                   | Column ID for event end date                                                                              |
+| `defaultStartDate` | `Date`                     | Default calendar start date                                                                               |
+| `customView`       | `CalendarCustomView`       | Custom calendar view config                                                                               |
+| `groupId`          | `string`                   | Column ID — events with the same value share a background colour                                          |
+| `groupColor`       | `Color[]`                  | Background colours for groups                                                                             |
+| `customHeader`     | `string`                   | Custom title replacing the default calendar header                                                        |
+| `eventColorRules`  | `CalendarEventColorRule[]` | Maps a field+value on each event to an explicit color. Takes priority over `groupId` coloring. See below. |
+
+### CalendarEventColorRule
+
+| Name         | Type     | Required | Description                                                          |
+| ------------ | -------- | -------- | -------------------------------------------------------------------- |
+| `field`      | `string` | yes      | Column ID on the event data to match against (e.g. `"status"`)       |
+| `value`      | `any`    | yes      | The value to match (e.g. `"Approved"`)                               |
+| `color`      | `string` | yes      | Tailwind bg class for the event pill, e.g. `"bg-green-500"`          |
+| `hoverColor` | `string` | no       | Tailwind hover class for the event pill, e.g. `"hover:bg-green-700"` |
+| `textColor`  | `string` | no       | Tailwind text class for the event pill, e.g. `"text-white"`          |
+
+Example — color events by status:
+
+```tsx
+calendarSettings: {
+  title: "name",
+  startDate: "startAt",
+  endDate: "endAt",
+  eventColorRules: [
+    { field: "status", value: "Approved", color: "bg-green-500", hoverColor: "hover:bg-green-700", textColor: "text-white" },
+    { field: "status", value: "Pending",  color: "bg-yellow-400", hoverColor: "hover:bg-yellow-600", textColor: "text-white" },
+    { field: "status", value: "Rejected", color: "bg-red-500",   hoverColor: "hover:bg-red-700",   textColor: "text-white" },
+  ],
+}
+```
+
+### List / MultipleList Field Settings
+
+Properties specific to `type: "list"` and `type: "multipleList"` fields in the DataStructure schema.
+
+| Name                     | Type                                | Default     | Description                                                                                                            |
+| ------------------------ | ----------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `listSelection`          | `string[]`                          | —           | Available options for the select field                                                                                 |
+| `listSelectionLabel`     | `string[]`                          | —           | Display labels for each option (matched by index). When omitted, the key itself is shown                               |
+| `listSelectionColour`    | `string[]`                          | —           | Colour for each option (matched by index). Supports named colours or hex values starting with `#`                      |
+| `listView`               | `"radioview" \| "modal" \| "chips"` | `undefined` | Render style. `undefined` = dropdown. `"chips"` renders options as inline toggleable chips                             |
+| `listNewValue`           | `boolean`                           | `false`     | Allows users to add values not in `listSelection`. In chips mode, shows a `+ Add` chip that expands to an inline input |
+| `listNewValueLabel`      | `string`                            | `"+ Add"`   | Custom label for the add-new-value chip (only applies when `listView: "chips"` and `listNewValue: true`)               |
+| `disabledAutoSelect`     | `boolean`                           | `false`     | When `true`, no option is pre-selected. The field starts empty                                                         |
+| `disabledKeyboardSearch` | `boolean`                           | `false`     | Disables typeahead filtering in the dropdown                                                                           |
+| `showTagSelections`      | `boolean`                           | `false`     | Shows selected values as removable tags below the dropdown input                                                       |
+| `closeOnClickOutside`    | `boolean`                           | `false`     | For `multipleList` dropdown, closes the options panel when clicking outside                                            |
+
+#### Chips example
+
+```tsx
+{
+  id: "weather",
+  name: "Weather",
+  type: "multipleList",
+  listView: "chips",
+  listSelection: ["Sunny", "Cloudy", "Drizzle", "Rainy", "Thunderstorm"],
+  listNewValue: true,
+  listNewValueLabel: "+ Other",
+  disabledAutoSelect: true,
+}
+```
+
+This renders all weather options as toggleable chips. Users can select multiple and also add custom values via the `+ Other` chip.
 
 ### Feeds Settings
 
+Under `bareNewDTW` the feeds tab renders `NewFeeds` (timeline card that matches NewList's row geometry) with the shared `NewPagination` footer; tapping a row opens the record's read view, the pencil / trash actions stay in the row. Without the flag the legacy `Feeds` renders as before.
+
 | Name              | Type                                                                      | Description                                                                            |
 | ----------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
 | `title`           | `string`                                                                  | Column ID for feed item title                                                          |
@@ -901,3 +1201,17 @@ Injects custom React components and callbacks into the list, read, and update vi
 | `title`   | `string` | Column ID for map marker info window title |
 | `address` | `string` | Column ID for marker coordinates           |
 | `group`   | `string` | Column ID to group markers by colour       |
+
+**Stories** — four groups under `Data / Data Wrapper`: **View** (list, read, drawer, grouped
+sections, scroll paging), **Edit** (CRUD, inline-edit matrix), **Utils** (flex filters, hidden
+columns, persisted view state, SSE live) and **Consumer Fixtures** below.
+Every story mocks its own API and opens without a server.
+
+**Consumer fixtures** — `Data / Data Wrapper / Consumer Fixtures` holds the DataTemplateWrapper
+configurations the apps run in production, copied field for field and self-mocked (no
+server): the KPJ grant proposal form (Blixify Space's kpj-projects shape), Verdant's
+installer pre- and post-installation checklists, its Sales Leads list and its simulator
+proposal form, Meraque's offline work order, and an **Action Component Cases** story showing
+the update form under the three things `bareUpdateActionComponent` can return (undefined /
+own buttons / an empty fragment). Open them on a phone and a desktop before bumping the app — what changes
+there is what changes in the app.