blixify-ui-web-mcp 0.1.72 → 0.1.76

package/lib/components/chart/barChart/README.md

@@ -103,6 +103,7 @@ Custom styled with annotation labels:
 | `stackedVertical`  | `boolean`                                   | `false`     | Stack series on top of each other (requires `stackedBarSeries`) |
 | `distributed`      | `boolean`                                   | `false`     | Give each bar in a single series a distinct colour              |
 | `showDataLabel`    | `boolean`                                   | `true`      | Show value labels on bars                                       |
+| `dataLabelPosition` | `"inside" \| "outside"`              | —           | Where each bar's value is printed: inside the bar, or outside past its end (above an upright bar, beside a horizontal one) in dark text. Unset, it is outside on a chart with `benchmarkLines` and inside otherwise. A stacked chart always keeps its values inside |
 | `showToolbar`      | `boolean`                                   | `false`     | Show the ApexCharts toolbar                                     |
 | `borderColor`      | `string`                                    | `"#e7e7e7"` | Grid line colour. Pass `""` to remove grid lines                |
 | `newTabUrl`        | `string`                                    | `""`        | Makes the chart title a link that opens in a new tab            |
@@ -119,6 +120,7 @@ Custom styled with annotation labels:
 | `roundedBars`      | `boolean`         | `false` | Apply rounded corners to bar tops                            |
 | `disableZoom`      | `boolean`         | `false` | Disable zoom interaction                                     |
 | `disableTooltip`   | `boolean`         | `false` | Disable hover tooltips                                       |
+| `benchmarkLines`   | `{ value, label?, color? }[]` | — | Dashed benchmark lines across the chart, each with its label (or its value, for one without a label) and colour (default purple); hovering a label shows both. Placed like monday.com: just above the line at its left end on an upright bar, and along the top just right of the line on a horizontal one (left of it at the right edge). Close labels move apart, and none covers a bar value: with benchmark lines the bars show their values past their ends. Past 3 rows, a horizontal label shows as "…". The value axis grows to show a benchmark above every bar |
 | `customAnimation`  | `AnimationConfig` | —       | Override default animation settings                          |
 | `xAxisLabels`      | `AxisLabelConfig` | —       | Customise X-axis label rotation, style, and formatter        |
 | `yAxisLabels`      | `AxisLabelConfig` | —       | Customise Y-axis label rotation, style, and formatter        |

package/lib/components/chart/barChart/barChart.stories.tsx

@@ -8,13 +8,20 @@ import { StorySection } from "../../storyUtils";
 const meta = { title: "Chart/Bar Chart" };
 export default meta;
 
-
 const stackedSeries = [
   { name: "Company A", data: [400, 430, 448] },
   { name: "Company B", data: [430, 460, 478] },
   { name: "Company C", data: [448, 470, 490] },
 ];
 
+const benchmarkLines = [
+  { value: 15, label: "April SF Target", color: "#8B5CF6" },
+  { value: 30, label: "May SF Target", color: "#8B5CF6" },
+  { value: 45, label: "June SF Target", color: "#8B5CF6" },
+  { value: 3, label: "April LF Target", color: "#EF4444" },
+  { value: 6, label: "June LF Target", color: "#EF4444" },
+];
+
 const rawData = [
   { label: "Apple", value: 10, daysAgo: 7 },
   { label: "Mango", value: 20, daysAgo: 7 },
@@ -50,7 +57,7 @@ export const BarChart = () => {
         .map((d) => ({ x: d.label, y: d.value }));
       setSeriesData(points);
     },
-    [chartDummyData]
+    [chartDummyData],
   );
 
   useEffect(() => {
@@ -95,6 +102,82 @@ export const BarChart = () => {
         />
       </StorySection>
 
+      <StorySection
+        title="Values Outside The Bars"
+        description={
+          <>
+            <code>dataLabelPosition="outside"</code> prints each bar's value
+            past its end: above an upright bar, beside a horizontal one. Charts
+            with <code>benchmarkLines</code> do this on their own.
+          </>
+        }
+      >
+        <BarChartImpl
+          title="Videos Done by Tier"
+          seriesName="Videos"
+          orientation="col"
+          distributed
+          dataLabelPosition="outside"
+          categories={["Tier 3", "Tier 2", "Tier 1"]}
+          seriesData={[
+            { x: "Tier 3", y: 8 },
+            { x: "Tier 2", y: 12 },
+            { x: "Tier 1", y: 33 },
+          ]}
+        />
+      </StorySection>
+
+      <StorySection
+        title="Benchmark Lines"
+        description={
+          <>
+            <code>benchmarkLines</code> draws a dashed line across the chart at
+            each goal, with its label, in its <code>color</code>. The value axis
+            grows to show a goal above every bar, and a horizontal bar draws its
+            goals upright.
+          </>
+        }
+      >
+        <BarChartImpl
+          title="Videos Done by Type"
+          seriesName="Videos"
+          orientation="col"
+          distributed
+          categories={[
+            "Poster (Static)",
+            "Photo",
+            "Video (Long)",
+            "Video (short)",
+          ]}
+          seriesData={[
+            { x: "Poster (Static)", y: 3 },
+            { x: "Photo", y: 4 },
+            { x: "Video (Long)", y: 17 },
+            { x: "Video (short)", y: 57 },
+          ]}
+          benchmarkLines={benchmarkLines}
+        />
+        <div className="mt-6">
+          <BarChartImpl
+            title="Videos Done by Type (horizontal, close goals stack)"
+            seriesName="Videos"
+            orientation="row"
+            categories={["Poster (Static)", "Photo", "Video (Long)"]}
+            seriesData={[
+              { x: "Poster (Static)", y: 3 },
+              { x: "Photo", y: 4 },
+              { x: "Video (Long)", y: 17 },
+            ]}
+            benchmarkLines={[
+              { value: 30, label: "May SF Target", color: "#8B5CF6" },
+              { value: 4, label: "April LF Target", color: "#EF4444" },
+              { value: 5, label: "May LF Target", color: "#EF4444" },
+              { value: 6, label: "June LF Target", color: "#10B981" },
+            ]}
+          />
+        </div>
+      </StorySection>
+
       <StorySection
         title="Stacked Vertical Bar Chart"
         description={
@@ -309,4 +392,4 @@ export const BarChart = () => {
       </StorySection>
     </div>
   );
-}
+};

package/lib/components/chart/pieChart/README.md

@@ -83,8 +83,10 @@ Chart only (no header or date range):
 | `type`        | `"pie" \| "donut"`                       | `"donut"`   | Chart type                                                    |
 | `valueType`   | `"percent" \| "value"`                   | `"percent"` | Whether labels and data labels show percentages or raw values |
 | `roundValue`  | `boolean`                                | `false`     | Round displayed values to whole numbers                       |
-| `legendPos`   | `"top" \| "bottom" \| "right" \| "left"` | `"top"`     | Position of the legend                                        |
+| `legendPos`   | `"top" \| "bottom" \| "right" \| "left"` | `"top"`     | Position of the legend. Left and Right move below, centred, while the chart is narrower than 360px (`PIE_SIDE_LEGEND_MIN_WIDTH`), and return beside it from 384px |
 | `legendAlign` | `"right" \| "left" \| "center"`          | `"right"`   | Horizontal alignment of the legend                            |
+| `showTotal`   | `boolean`                                | `false`     | Show the sum of the series in the centre of a donut. Ignored for `type="pie"`. Selecting a slice shows its name and value there instead |
+| `showDataLabel` | `boolean`                              | `true`      | Draw each slice's value on the pie. The legend and tooltip still show it when `false` |
 | `newTabUrl`   | `string`                                 | `""`        | Makes the chart title a link that opens in a new tab          |
 
 > Note: Legend labels are truncated to 10 characters. The full label is shown in the tooltip on hover.

package/lib/components/chart/pieChart/pieChart.stories.tsx

@@ -137,9 +137,25 @@ export const PieChart = () => {
         </div>
       </StorySection>
 
+      <StorySection
+        title="Total And Slice Values"
+        description='showTotal=true puts the sum in the centre of a donut, its "Total" caption smaller and lighter than the number. showDataLabel=false hides the value on each slice; the legend and tooltip still show it.'
+      >
+        <div className="w-full">
+          <PieChartImpl
+            title="Orders By Channel"
+            series={series}
+            labels={labels}
+            showTotal
+            showDataLabel={false}
+            roundValue={true}
+          />
+        </div>
+      </StorySection>
+
       <StorySection
         title="Dark Mode"
-        description="Pass darkMode=true and optionally darkModeBg to customise the background."
+        description="Pass darkMode=true and optionally darkModeBg to customise the background. The total in the centre turns white, with a lighter grey caption."
         dark
       >
         <div className="w-full">
@@ -150,6 +166,7 @@ export const PieChart = () => {
             tool={<PencilIcon className="h-4 w-4 text-primary-600" />}
             darkMode={true}
             darkModeBg="bg-gradient-to-r from-slate-700 to-gray-900"
+            showTotal
             roundValue={true}
           />
         </div>

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

@@ -177,6 +177,9 @@ Custom layout via renderSettings:
 | `cardIcon`         | `string`                                        | Heroicon name (solid) for the card icon, e.g. `"UserIcon"`. Defaults to `FolderIcon`.                                                     |
 | `cardSize`         | `"default" \| "compact"`                        | `card` layout; `"compact"` is the short stat-first card. Defaults to `"default"`.                                                       |
 | `pieType`          | `"donut" \| "pie"`                               | `pie` style. Defaults to `"donut"`.                                                                                                       |
+| `legendPosition`   | `"top" \| "bottom" \| "left" \| "right"`        | `pie` legend placement. Defaults to `"top"`.                                                                                              |
+| `showDataLabel`    | `boolean`                                       | `pie` only: `false` hides the value on each slice; the legend and tooltip still show it. Defaults to shown.                                |
+| `showTotal`        | `boolean`                                       | `pie` donut only: the total in the centre. Ignored for averages. Defaults to hidden.                                                       |
 | `cardEmoji`        | `string`                                        | Emoji shown instead of `cardIcon` when set, e.g. `"📦"`. Clearing it brings `cardIcon` back.                                              |
 | `cardIconBgColor`  | `string`                                        | Tailwind bg class for the card icon background                                                                                            |
 | `colors`           | `string[]`                                      | Custom color array for chart segments/bars/lines                                                                                          |
@@ -187,15 +190,29 @@ Custom layout via renderSettings:
 | `segmentBy`        | `string`                                        | Second column split into stacked series (bar, line, table), at most 10 values plus "Others".                                             |
 | `sortBy`           | `"value" \| "label"`                             | Sort the groups. `sortDirection` is `"asc"` or `"desc"` (default).                                                                       |
 | `topN`             | `number`                                        | Keep the first N groups; the rest are added up as "Others" unless `showOthers` is `false` (averages never get "Others").                 |
-| `showPercent`      | `boolean`                                       | Show each group as a percentage of the total (count and sum, unsplit charts).                                                            |
+| `showPercent`      | `boolean`                                       | Show each group as a percentage of the total (count and sum, unsplit charts). Ignored for `pie`, which already draws slices as shares.     |
 | `cumulative`       | `boolean`                                       | Running total over the date buckets.                                                                                                     |
 | `datesAcross`      | `boolean`                                       | Table grouped by a date interval: the dates become the columns (every bucket in the range, oldest first) and the `segmentBy` values the rows, with a Total column and a Total row for count and sum. With no `segmentBy`, one row named by its measure. |
 | `higherIsBetter`   | `boolean`                                       | Dates-across table: colours the Change column (last complete period vs the one before) green for good and red for bad. Unset leaves it grey. |
+| `benchmarks`          | `{ label?, value, colour? }[]`                  | `bar` only: goals drawn as dashed lines across the chart, each with its label. `colour` is `purple` (default) `red` `amber` `green` `blue`, the same five as `highlights`, each with a lighter shade ready for dark mode (`handleChartBenchmarkLines(chart, darkMode)`); DataGraph's cards are light today, so it uses the light one. Picked from a row of swatches in the builder's Benchmark lines section. |
+| `valuePosition`    | `"inside" \| "outside" \| "hidden"`        | `bar` only: where the values are printed, or `"hidden"` for none. Unset is inside; with `benchmarks` it is outside, and inside counts as outside. A chart split by a column (`segmentBy`) has no benchmark lines and keeps its values inside or hidden. Set in the builder's Values position dropdown. |
 | `highlights`       | `{ row, colour?, bold? }[]`                     | Table rows marked by label: tint (`red` `amber` `green` `blue` `purple`) and/or bold. Set by an editor from the highlight bar beside a row label (`onHighlightRow`). |
 | `valueDisplay`     | `"count" \| "percent" \| "both"`          | Dates-across table split by `segmentBy`: cells as counts, as each period's share of its total, or both. In `percent`, Change is in percentage points. |
 | `recordColumns` / `recordSort` / `recordPageSize` | `string[]` / `Sort` / `number` | What clicking a value opens: the columns in order, the sort and the rows per page. Unset follows the datasheet. ChartView's `renderDrillDown` lets an app render that view itself. |
 | `rangeOverride`    | `{ startDate?: string; endDate: string }`       | ISO range set by the page the chart sits on; replaces the chart's own range and hides its picker. No `startDate` counts all time, and date buckets then start at the first record's day. Not saved with the chart. |
 
+##### Chart builder sections
+
+ChartView's Edit Chart form groups these settings into collapsible sections, like monday.com's Widget settings. A header opens or closes its section, and a closed one keeps its fields in the form and shows a one-line summary.
+
+| Section         | Opens by default | Fields                                                                                                                   | Summary when closed                  |
+| --------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------ |
+| Chart           | Yes              | Datasheet, Title, type, Emoji (card), Orientation / Style, Width                                                         | The chart type                       |
+| Data            | Only when a setting is missing | Measure, Of column, Group By, Date Range On / Over Time, Interval, Split By                                | e.g. "Sum of Amount by Status", or what's missing in red, such as "Pick a column to sum" |
+| Customize       | No               | Values position, Legend, Show values / Show total, Sort / Show, Show as %, Multicolour bars, the table options, Running total. Hidden when the chart has none of these, such as a card | —                                    |
+| Benchmark lines | No               | `bar` only: the goal lines. A chart split by a column says why it has none                                               | e.g. "2 lines", "None"               |
+| Records list    | No               | Columns, Sort by, Order, Rows per page                                                                                   | e.g. "20 rows per page, sorted by Amount" |
+
 ##### WorkspaceDevSettings
 
 | Name               | Type                                                                       | Description                     |

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

@@ -480,7 +480,7 @@ Under `bareNewDTW` the grid hides `Grid`'s own page buttons and renders the same
 
 Set `organise.viewId="grid"` (or add an `extendedTabs` entry with `viewType="grid"`) to render records as cards. Use `bareSettings.bareListGridComponent` to fully customise each card, or use the built-in grid. `viewImage` is optional: point it at an image or multipleImage column to show a picture on each card, or leave it empty for cards with only the title and fields. The Add Tab modal offers **Grid** on every space, and shows the Preview Image picker only when the space has an image column.
 
-The list, kanban and grid items show the view's visible columns in column order, with the table's cell renderers. The title column is the item's title, the grid's image column is its picture, and a column with nothing stored is left out. A button, timer or rating is always shown. Each item carries the edit pencil (only for users who can update) and the comment bubble (when `edit.activityLog` is on) beside its title.
+The list, kanban and grid items show the view's visible columns in column order, with the table's cell renderers. Under `bareNewDTW` a list item is a two-line row like a mail inbox (`NewList` `compact`): the first list column as a pill leading the second line, the first date column as a short date at the right, the next two columns that hold something on a grey line after the pill, and every field behind the row's arrow. On a wide screen the row is one line: title, pill, values, date. The grouped column is left off rows under group sections. `bareListDescription` still renders each value, the row's date included, and `bareListComponent` still replaces the row. The title column is the item's title, the grid's image column is its picture, and a column with nothing stored is left out. A button, timer or rating is left off the row's second line and shown behind its arrow; grid and kanban cards always show them. Each item carries the edit pencil (only for users who can update) and the comment bubble (when `edit.activityLog` is on) beside its title. The table also shows a chevron beside each title that opens the read view, for anyone who can see the record when `organise.handleNavigate` is set, since an editable title cell is hard to click open; its pencil and bubble sit in divided columns at the title cell's edge.
 
 ```tsx
 <DataTemplate
@@ -750,6 +750,8 @@ A `type: "formula"` column is a monday.com-style formula. It is worked out from
 - **Values:** an empty cell is blank text, 0 in arithmetic and equal to 0 in a comparison with a number. Reference and role columns read their label; a math column reads the number it shows. A time tracking column reads in hours; a date range reads as `start - end`, and `{Timeline#Start}` / `{Timeline#End}` read one end as a date. A formula can read another formula; a circular reference shows `Error`. Files, images, addresses, objects, passwords, signatures, canvas and gantt columns cannot be used.
 - **Adding:** with `bareAddColumns`, pick **Formula** as the type in the header + panel. The builder lists columns and functions with an example of each, validates as you type and previews the first row.
 - **Sort and filter** use the computed value, as monday does: header / view settings sort, and the flex filters. Either makes the list read the matching rows — at most `FORMULA_VIEW_MAX_ROWS` (5,000), in a fixed order, with a notice when there are more — and filter, order and page them locally. The cap also applies to the calendar, map, timeline and legacy grouped views, which otherwise read every row. On Firebase and union lists formula columns are not offered for sorting or filtering. CSV export sends the rows a formula filter kept, by id; "Select all pages" is off in a formula view, and the selection callbacks' query does not carry formula conditions.
+- **On a server**, wrap evaluation in `handleWithFormulaTimezone(timezone, () => …)` so `TODAY()`, `NOW()` and stored dates are read on the reader's calendar rather than the server's (UTC). Inside it, a `Date` or zoned text (`…Z`, `…+08:00`) becomes that timezone's wall-clock time; text without a zone is read as written. An invalid or missing timezone changes nothing, and the browser needs no wrapper.
+- **Charts** offer formula columns to group by (bar, pie, table) and to sum or average (`handleGetMeasureOptions`). Their values are never stored, so the server answering the chart works them out per row; Space does this.
 - **Earlier library versions** have no case for `formula`, so they show its cell blank. Apps that build schemas with `parseSpaceToDataStructure` need this version to receive `formulaExpression`; a consumer with its own `DataType` list (blixify-space-next `models/Data.ts`) adds `"formula"` to it.
 
 ---
@@ -764,6 +766,7 @@ Column types with monday.com counterparts. The value maths is in `src/components
 | Time tracking | `type: "timeTracking"` | `{ totalSeconds, running, startedAt?, sessions? }` | table, read view and the record form show the total with start / stop, ticking each second inside the cell only; the form draws it as a field box, read-only on a record not created yet or without update rights. Start / stop saves at once, apart from Submit, and a form save never sends the timer. With `organise.onTimeTrackingAction` a click sends only `"start"` / `"stop"` and shows the value the host's server stored, timed on the server's clock (the cell ticks at once and is corrected to the reply, or put back if it fails); without it the cell works the value out and saves that one field. `handleStartTimeTracking` / `handleStopTimeTracking` are idempotent, so a flow can drive the same value. Sorts on `<id>.totalSeconds`; formulas read hours (`handleGetTimeTrackingHours`) |
 | Date range | `type: "dateRange"`, `minDate?`, `maxDate?` | `{ start, end }` | `12 – 18 Nov`; a range picker in the form; in an editable table the whole cell opens it, with the inline date cell's border on hover; filters and sorts on `<id>.start`. A calendar or timeline tab can use `<id>.start` and `<id>.end` as its dates |
 | Rating | `type: "number"`, `ratingMax` | a number | stars in every view; a tap saves the number, tapping the current rating clears it |
+| Lookup | `type: "lookup"`, `referenceFieldId`, `lookupFieldId`, `lookupFieldType?`, `lookupFieldSettings?` | the linked record's `lookupFieldId` value, written by the host's server | every view draws it as `lookupFieldType` (a `multipleList` through a `listReference`) with `lookupFieldSettings`, disabled and optional; `organise.onAddColumns` gets it back as stored, with only its name, width and visibility taken from the table; the column dialog edits it as a lookup |
 
 `bareSettings.bareSystemColumns` adds the server-stamped columns without declaring them: Created At / By (`baseCreatedAt`, `baseCreatedBy`), Updated At / By (`baseUpdatedAt`, `baseUpdatedBy`), Record ID (the record's `_id`) and Number (`baseNumber`). They start hidden; showing one is kept per view (`shownSystemColumnIds`) and never written back through `onChangeHide` or `onChangeDrag`. They are read-only, sortable and filterable, empty on a record the server never stamped, and a form save never sends them (nor a timer or a button).
 
@@ -1275,14 +1278,14 @@ Which field types can be edited from the list table, and how. Types not listed u
 | `addColumnEnabled`            | `boolean`                                                                   | Shows an add-column button in the table header                                                                                                                                                                                                                                                                        |
 | `persistViewState`            | `"persistent" \| "session"`                                                 | Remembers the list's sort, filters, hidden columns, page, rows per page, search and reading position per collection, so a Back navigation lands where the user left. `"persistent"` uses `localStorage`; `"session"` writes `sessionStorage` and reads it first, falling back to `localStorage`. The reading position is restored on mount and on returning from a record, not on a tab switch; with several lists on one page, only the list a record was last opened from restores (tracked in `blixify-dtw-persist-last-drill`). Covers table, list, grid, kanban and feeds; not map. List view only                                        |
 | `persistKey`                  | `string`                                                                    | Keeps a separate saved view state for this instance: the storage key becomes `blixify-dtw-persist-<collectionId>-<persistKey>`. Saved state is read once, on mount, so give the component a React `key` that changes with `persistKey`                                                                               |
-| `savedViews`                  | `boolean`                                                                   | Shows a row of view tags under the tab bar: save the current filters, flex filters, sort, rows per page, grouping, columns and column widths under a name, reapply it, update it or delete it. Views belong to the tab they were saved on and are kept in `localStorage` under `blixify-dtw-views-<collectionId>[-<persistKey>][-<currentUser.userEmail>]`. Sort is held by the template while it is on, as with `persistViewState`, and applying a view calls `onChangeSort`, `onChangeGroupBy`, `onChangePagination(0)` and `bareListHandleFilter` when those change. Each write re-reads storage first, so views saved in another browser tab are kept. With `onChangeHide` / `onChangeDrag`, a view's hides and column order stay on screen only: a toggle or reorder after applying one writes back the schema's columns plus that single change |
+| `savedViews`                  | `boolean`                                                                   | Shows a row of view tags under the tab bar: save the current filters, flex filters, sort, rows per page, grouping, columns and column widths under a name, reapply it, update, rename or delete it. Past eight views the rest fold behind “+N more”; the open view always shows. Views belong to the tab they were saved on and are kept in `localStorage` under `blixify-dtw-views-<collectionId>[-<persistKey>][-<currentUser.userEmail>]`. Sort is held by the template while it is on, as with `persistViewState`, and applying a view calls `onChangeSort`, `onChangeGroupBy`, `onChangePagination(0)` and `bareListHandleFilter` when those change. Each write re-reads storage first, so views saved in another browser tab are kept. With `onChangeHide` / `onChangeDrag`, a view's hides and column order stay on screen only: a toggle or reorder after applying one writes back the schema's columns plus that single change |
 | `defaultSavedViews`           | `DefaultSavedView[]`                                                        | Views provided by the app (`{ id?, name, tabId?, state }`), listed before the user's own and never deleted. Without `tabId` a view is listed on every tab. A field left out of `state` is reset to its default when the view is applied. `id` must be unique; without one the view gets `default-<index>`, its position in the whole array |
 | `sharedViews`                 | `SharedSavedView[]`                                                         | Views the app stores for everyone (`{ id, name, tabId, state }`), e.g. on the record the list belongs to. Given, it replaces this browser's storage: the list shows only these, saving goes to `onChangeSharedViews`, and nothing is read from or written to `localStorage` |
 | `onChangeSharedViews`         | `(views: SharedSavedView[]) => void`                                        | Called with the whole list after a view is saved, updated or deleted, for the app to store and pass back as `sharedViews`; a second change before it comes back builds on the list just sent. The whole list is replaced each time, so two editors saving at once is last-writer-wins. Without it the app's views are read-only and “+ Save view” is hidden |
 | `defaultSavedViewId`          | `string`                                                                    | The view everyone opens on, marked ★, stored by the app. The list opens on it when no `initialSavedViewId` is given — also when it arrives after mount — unless `persistViewState` restored a state or a view was already picked. A view that no longer exists leaves the list on All. Opening on it does not call `onChangeSort` |
 | `onChangeDefaultSavedViewId`  | `(id: string \| null) => void`                                              | Gives each view a ☆ that makes it the default; the ★ on the default takes it off (`null`, the list opens on All). Deleting the default view also sends `null` |
 | `initialSavedViewId`          | `string`                                                                    | A view the list opens on, once, in place of the ★ default — e.g. a page embedding a datasheet opens it on a chosen view. A view that no longer exists, or is on another tab, leaves the list on All. Opening on it does not call `onChangeSort` |
-| `groupBy`                     | `string`                                                                    | Column ID to group list results by. With `bareNewDTW` the groups are bands in one table. Grouped by a `list` or `boolean` column, every option (in option order, with its colour) plus "Unknown" (a value outside the options) and "No Value" (missing or blank) is a band with its real total that reads its own rows under the list's filters, search and sort: in scroll mode each band loads more as it scrolls, in page mode each band has its own pager and the list-wide pager is hidden. Grouped by any other column (a `person` column's sections follow the member order), page mode groups the rows of the current page and scroll mode keeps the normal scroll; a section built from loaded rows draws 50 rows and a "Show more" at a time. A search, filter, sort or regroup starts every band over. Firebase and `bareListMobileView` keep the normal pagination. Saved views store and restore it                                                                                                                                                                                                                                                                                    |
+| `groupBy`                     | `string`                                                                    | Column ID to group list results by. With `bareNewDTW` the groups are bands in one table. Grouped by a `list` or `boolean` column, every option (in option order, with its colour) plus "Unknown" (a value outside the options) and "No Value" (missing or blank) is a band with its real total that reads its own rows under the list's filters, search and sort: in scroll mode each band loads more as it scrolls, one band at a time, and a band not read yet shows the grouped count's total (a band it counts empty stays hidden until its own read), in page mode each band has its own pager and the list-wide pager is hidden. Grouped by any other column (a `person` column's sections follow the member order), page mode groups the rows of the current page and scroll mode keeps the normal scroll; a section built from loaded rows draws 50 rows and a "Show more" at a time. A search, filter, sort or regroup starts every band over. Firebase and `bareListMobileView` keep the normal pagination. Saved views store and restore it                                                                                                                                                                                                                                                                                    |
 | `onButtonClick`               | `(columnId: string, row: any) => Promise<any> \| void`                     | Called when a `button` column is tapped, with the stored record. The button is busy until the promise settles. See Button, time tracking … columns |
 | `onTimeTrackingAction`        | `(columnId: string, row: any, action: "start" \| "stop") => Promise<any>` | Starts or stops a `timeTracking` timer on the host's server, with the stored record. Resolve with the value the server stored; the timer shows it, and goes back to where it was if the promise rejects. Without it a timer works its value out on the device and saves it through the single-field update |
 | `allView`                     | `PersistedViewState`                                                        | All's settings as the app stores them for everyone (`{}` when none are saved yet): sort, grouping, filters, hidden columns, column order, column widths (`columnWidths`, `"180px"` by column id) and rows per page. A setting left out falls back to the model and the props. Needs `savedViews`. Given, the list opens on it, and every change a person makes to All or a saved view is kept in their browser (`blixify-dtw-draft-<collectionId>[-<persistKey>][-<currentUser.userEmail>]-<all \| view id>`) until they choose Update or Reset; a saved view with no width of its own for a column follows All's |

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

@@ -0,0 +1,311 @@
+import { Menu, Transition } from "@headlessui/react";
+import axios from "axios";
+import MockAdapter from "axios-mock-adapter";
+import React, { useMemo, useState } from "react";
+import { DataTemplate as DataTemplateImpl } from ".";
+import { SharedSavedView } from "./dataStateModel";
+import { DataStructure } from "./model";
+
+const meta = { title: "Data/Data Template" };
+export default meta;
+
+const ENDPOINT = "https://grouped-board.local/api";
+const COLLECTION = "grouped-board";
+
+// INFO: the group sizes of a real 148,936-row leads board grouped by state —
+// a few very large groups, many small ones, blanks and stray spellings that
+// fall under Unknown
+const STATE_SIZES: [string | null, number][] = [
+  ["Selangor", 63116],
+  ["Johor", 18340],
+  ["Kuala Lumpur", 14488],
+  ["Penang", 11831],
+  ["Perak", 9141],
+  ["Negeri Sembilan", 7690],
+  ["Kedah", 6460],
+  ["Melaka", 6119],
+  ["", 5014],
+  ["Pahang", 2226],
+  [null, 2108],
+  ["Perlis", 904],
+  ["Kelantan", 533],
+  ["Terengganu", 409],
+  ["Kuantan", 221],
+  ["Putrajaya", 182],
+  ["Sabah", 38],
+  ["Sarawak", 32],
+  ["Puchong", 16],
+  ["Pulau Pinang", 12],
+  ["Pahang (Kuantan)", 11],
+  ["Kedah (Exclude Langkawi)", 9],
+  ["Cyberjaya", 9],
+  ["KL", 8],
+  ["Negri Sembilan", 7],
+  ["Pahang (non-Kuantan)", 7],
+  ["Ipoh", 3],
+  ["Labuan", 1],
+];
+
+const STATES = STATE_SIZES.map(([state]) => state).filter(
+  (state): state is string => !!state,
+);
+const STATUSES = ["New Lead", "Contacted", "Site Survey", "Closed", "Dropped"];
+
+const SCHEMA: DataStructure[] = [
+  { id: "name", name: "Name", type: "string" },
+  { id: "area", name: "State (Area)", type: "list", listSelection: STATES },
+  { id: "status", name: "Status", type: "list", listSelection: STATUSES },
+  { id: "createdAt", name: "Created At", type: "date" },
+];
+
+// INFO: rows interleaved across states, so the first page of the whole list
+// holds a few states and one Pahang row — every other band has to load itself
+const handleBuildRows = () => {
+  const pools = STATE_SIZES.map(([state, size]) => ({ state, left: size }));
+  const total = pools.reduce((sum, pool) => sum + pool.left, 0);
+  const rows: any[] = [];
+  let index = 0;
+  while (rows.length < total) {
+    const pool = pools[index % pools.length];
+    index++;
+    if (pool.left === 0) continue;
+    pool.left--;
+    const number = String(rows.length + 1).padStart(6, "0");
+    rows.push({
+      _id: `lead-${number}`,
+      name: `Load Test Lead ${number}`,
+      ...(pool.state === null ? {} : { area: pool.state }),
+      status: STATUSES[rows.length % STATUSES.length],
+      createdAt: new Date(2025, 0, 1, 0, rows.length).toISOString(),
+    });
+  }
+  return rows;
+};
+
+const handleIsIn = (list: any[], value: any) =>
+  list.some((each) =>
+    each === null ? value === null || value === undefined : each === value,
+  );
+
+const handleMatch = (row: any, query: any[]) =>
+  (Array.isArray(query) ? query : []).every((each) => {
+    if (!each?.queryId) return true;
+    const value = row[each.queryId];
+    if (each.type === "=") return value === each.value;
+    if (each.type === "in") return handleIsIn(each.value, value);
+    if (each.type === "!in") return !handleIsIn(each.value, value);
+    return true;
+  });
+
+// INFO: answers band reads, the whole-list read and the grouped count the way
+// the list endpoint does, after a short delay so loading can be watched
+const handleInstallMock = (rows: any[]) => {
+  const mock = new MockAdapter(axios, { onNoMatch: "passthrough" });
+  // INFO: e2e reads how many band reads were ever in flight at once
+  const tracker = ((window as any).__groupedBoardReads = {
+    inFlight: 0,
+    maxInFlight: 0,
+  });
+  // INFO: e2e reads how many table rows were drawn
+  (window as any).__newTableRowDraws = { count: 0 };
+  const handleDelay = () => new Promise((resolve) => setTimeout(resolve, 400));
+  mock.onPost(`${ENDPOINT}/${COLLECTION}/list`).reply(async (config) => {
+    const body = JSON.parse(config.data ?? "{}");
+    const isBandRead =
+      !body.aggregate &&
+      (body.query ?? []).some((each: any) => each?.queryId === "area");
+    if (isBandRead) {
+      tracker.inFlight += 1;
+      tracker.maxInFlight = Math.max(tracker.maxInFlight, tracker.inFlight);
+    }
+    await handleDelay();
+    if (isBandRead) tracker.inFlight -= 1;
+    const matched = rows.filter((row) => handleMatch(row, body.query));
+    if (body.aggregate?.type === "count") {
+      const counts = new Map<any, number>();
+      matched.forEach((row) => {
+        const key = row[body.aggregate.groupId] ?? null;
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+      });
+      return [
+        200,
+        {
+          data: [
+            {
+              _id: "range",
+              value: Array.from(counts, ([key, value]) => ({
+                _id: key,
+                value,
+              })),
+            },
+          ],
+        },
+      ];
+    }
+    if (body.aggregate) return [200, { data: [] }];
+    const cursor = typeof body.cursor === "number" ? body.cursor : 0;
+    const limit = typeof body.limit === "number" ? body.limit : 50;
+    return [
+      200,
+      { data: matched.slice(cursor, cursor + limit), count: matched.length },
+    ];
+  });
+  // INFO: a row typed into a band's "Add item" row joins the front of the list
+  mock.onPost(`${ENDPOINT}/${COLLECTION}/create`).reply((config) => {
+    const body = JSON.parse(config.data ?? "{}");
+    const row = { _id: `lead-new-${rows.length + 1}`, ...(body.data ?? {}) };
+    rows.unshift(row);
+    return [200, { data: row._id }];
+  });
+  mock.onPost(`${ENDPOINT}/${COLLECTION}/update`).reply((config) => {
+    const body = JSON.parse(config.data ?? "{}");
+    const row = rows.find((each) => each._id === body.id);
+    if (row) Object.assign(row, body.data ?? {});
+    return [200, { data: body.id }];
+  });
+  mock.onPost(`${ENDPOINT}/${COLLECTION}/get`).reply((config) => {
+    const body = JSON.parse(config.data ?? "{}");
+    return [200, { data: rows.find((row) => row._id === body.id) ?? null }];
+  });
+  return mock;
+};
+
+const VIEW_NAMES = [
+  "Closed Case",
+  "Drawing",
+  "Hunting & Referral",
+  "Marketing",
+  "1.60 Nuqman's Lead Board · Closed Case",
+  "1.60 Nuqman's Lead Board · Drawing",
+  "1.60 Nuqman's Lead Board · Marketing",
+  "1.59 Mei Jun's Lead Board · Closed Case",
+  "1.59 Mei Jun's Lead Board · Drawing",
+  "1.59 Mei Jun's Lead Board · Marketing",
+  "1.49 Hazim Suhaimi's Lead Board · Closed Case",
+  "1.49 Hazim Suhaimi's Lead Board · FB & Google",
+  "1.49 Hazim Suhaimi's Lead Board · Drawing",
+  "1.42 Wang's Lead Board · Closed Case",
+  "1.42 Wang's Lead Board · FB & Google",
+  "1.42 Wang's Lead Board · Drawing",
+];
+
+const GroupedBoardDemo = (props: { isPhone?: boolean }) => {
+  const rows = useMemo(() => handleBuildRows(), []);
+  const [openedId, setOpenedId] = useState("");
+  useMemo(() => handleInstallMock(rows), [rows]);
+  const [sharedViews, setSharedViews] = useState<SharedSavedView[]>(() => [
+    {
+      id: "closed-only",
+      name: "Closed only",
+      tabId: "general",
+      state: {
+        flexFilters: [
+          { id: "f1", columnId: "status", operator: "=", value: "Closed" },
+        ],
+      },
+    },
+    ...VIEW_NAMES.map((name, index) => ({
+      id: `view-${index}`,
+      name,
+      tabId: "general",
+      state: {},
+    })),
+  ]);
+
+  return (
+    <>
+      {props.isPhone && (
+        <div data-testid="grouped-board-opened" className="mb-2 text-xs">
+          {openedId ? `Opened ${openedId}` : ""}
+        </div>
+      )}
+      <DataTemplateImpl
+        title="Master Leads"
+        description="148,936 leads grouped by state"
+        type="list"
+        collectionId={COLLECTION}
+        model={SCHEMA}
+        localURLEndpoint=""
+        devSettings={{
+          server: "mongoServer",
+          dbEndpoint: ENDPOINT,
+          dbAPIToken: "",
+          dbUserToken: "",
+          schemaEndpoint: "",
+          imageEndpoint: "",
+        }}
+        lib={{ axios, Menu, Transition }}
+        edit={{ listAddable: true, listEditable: true }}
+        limit={50}
+        bareSettings={{
+          bareNewDTW: true,
+          bareFlexFilters: true,
+          bareListMobileView: props.isPhone,
+          // INFO: rows can be ticked on the phone board
+          ...(props.isPhone
+            ? { bareListMultipleSelectAddtionalActions: [] }
+            : {}),
+        }}
+        organise={{
+          viewId: "general",
+          datasheetDefaults: true,
+          showGroupByFeature: true,
+          groupBy: "area",
+          paginationType: "scroll",
+          savedViews: true,
+          sharedViews,
+          onChangeSharedViews: setSharedViews,
+          renderGroupByOptions: () => [
+            { key: "area", label: "State (Area)" },
+            { key: "status", label: "Status" },
+          ],
+          ...(props.isPhone
+            ? {
+                handleNavigate: (_type: string, id?: string) =>
+                  setOpenedId(id ?? ""),
+              }
+            : {}),
+        }}
+      />
+    </>
+  );
+};
+
+export const GroupedLargeBoard = () => (
+  <div className="w-full">
+    <div className="mb-1 font-semibold text-gray-900">
+      Data Template — a large board grouped by a list column
+    </div>
+    <div className="mb-4 text-sm text-gray-600">
+      148,936 mock leads across 28 state values (blanks included), sized like a
+      real leads board, grouped by State in scroll mode. Each read waits 400 ms.
+      Scroll up and down: every band shows its full total from the start, bands
+      not read yet draw no "Add item" rows, and bands load one at a time. The 16
+      views fold behind "+N more"; the pencil on a view renames it, and "Closed
+      only" filters every band. Cells edit in place on hover, and only the rows
+      near the screen are drawn.
+    </div>
+    <GroupedBoardDemo />
+  </div>
+);
+
+export const GroupedLargeBoardPhone = () => (
+  <div className="w-full max-w-sm">
+    <div className="mb-1 font-semibold text-gray-900">
+      Data Template — the large grouped board on a phone
+    </div>
+    <div className="mb-4 text-sm text-gray-600">
+      The same 148,936 leads in the phone layout. Each row reads like a mail
+      inbox: the name and date on top, the status pill under it, and an arrow
+      that opens every field. The state is left off the row, as its header
+      already says it. Tapping a row opens it, the box ticks it, and each
+      state&apos;s header folds its rows. Only the rows near the screen are
+      drawn.
+    </div>
+    <GroupedBoardDemo isPhone />
+  </div>
+);
+
+GroupedLargeBoardPhone.parameters = {
+  viewport: { defaultViewport: "mobile2" },
+};