fluentui-extended 2026.9.6 → 2026.9.16-beta.0

package/CHANGELOG.md

@@ -2,6 +2,51 @@
 
 > Version format: `YYYY.M.DD` (e.g., `2026.8.30` = August 30, 2026)
 
+## Unreleased
+
+- ✨ **[DataGrid](docs/DataGrid.md)** — a virtualised, editable grid on TanStack Table and TanStack
+  Virtual. Two production apps had each grown their own copy of the same machinery — row
+  virtualisation, column drag and resize, grouping with subtotals, a filter row, density, inline
+  editors and layout persistence — and the copies had begun to drift. This is that machinery,
+  extracted: fetching, saving and the toolbar stay with the consumer.
+
+  Notable behaviour: `getCellValue` layers unsaved edits over the stored record, and sorting,
+  filtering, grouping and the footer totals all read through it — so the grid orders by what is on
+  screen rather than by what the server last returned. Column layout restores during the first
+  render rather than in an effect, so the grid paints its saved layout instead of reflowing a frame
+  later, and the storage key includes the origin so dev, test and production orgs in one browser do
+  not share one layout. Sorting ascends first whatever the data type, unlike TanStack's default.
+
+  Also exports `useDataGrid`, the headless state machine, plus the chrome components and style hook,
+  so a bespoke render does not have to fork the component.
+
+  Hooks added so the grid can replace the two hand-built project grids (tracked in
+  `enhancements/DataGrid-replace-project-grids.md`):
+  - **States:** custom and restyled cell and row states (`cellStates`, `rowStates`), layered row
+    states from `getRowState`, and built-in `deleted` and `placeholder` states.
+  - **Cells:** `getCellTooltip`.
+  - **Groups:** banner hooks (`renderGroupHeader`, `groupContextMenu`, `onGroupDoubleClick`,
+    `groupSelection`), and row drops that report `toGroup`.
+  - **Keyboard:** spreadsheet keys — Tab, F2, type-over, and caret-aware arrows.
+  - **Totals:** function summaries, `includeInSummary` and `groupSubtotalsMinGroups`.
+  - **Visibility and views:** controlled visibility, `forceHiddenColumns`, `columnGroup`, and
+    `getLayout` / `applyLayout`.
+  - **Row chrome and toolbar:** `renderRowIndicator`, `showEditableHints`, `highlightRow`, and
+    `renderToolbarSearch`.
+
+  Fixes in the same pass:
+  - Changing `persist.scope` while mounted now loads that scope's layout. It used to overwrite it
+    with the current one.
+  - Nested group subtotals and counts now come from leaf rows rather than inner banners.
+  - Hiding a column while grouped no longer saves the grouped column as hidden.
+  - Keys pressed inside a cell's popup no longer move the active cell.
+
+  `cellStateClass` is replaced by `cellStateProps`.
+
+- 📦 `@tanstack/react-table`, `@tanstack/react-virtual` and the three `@dnd-kit` packages are
+  **optional** peer dependencies. Nothing outside `DataGrid` imports them, so consumers using only
+  the field components ship none of it.
+
 ## 2026.9.6
 
 - ✨ **`size` on [OptionSetField](README.md#optionsetfield)**, forwarded to the underlying Combobox.

package/README.md

@@ -103,6 +103,36 @@ sorting, and lookups rendered as names rather than GUIDs.
 
 ![EntityGrid](assets/screenshot-entitygrid.png)
 
+### DataGrid
+
+A virtualised, editable grid on TanStack Table and TanStack Virtual, for the spreadsheet-style
+screens a subgrid cannot carry: thousands of rows, inline editors, column drag and resize,
+grouping with subtotals, and a column layout that survives a reload.
+
+Bring your own rows — fetching and saving stay yours. The grid libraries are **optional** peer
+dependencies, so nothing ships them unless you use this component.
+
+```bash
+npm install @tanstack/react-table @tanstack/react-virtual \
+            @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities
+```
+
+```tsx
+<DataGrid
+  data={rows}
+  columns={columns}
+  getRowId={(row) => row.id}
+  getCellValue={(row, key, rowId) => pending[rowId]?.[key] ?? row[key]}
+  onCellChange={stageEdit}
+  getRowState={(_, rowId) => (pending[rowId] ? 'dirty' : null)}
+  selectable
+  groupBy="category"
+  persist={{ scope: 'quote-lines' }}
+/>
+```
+
+**[Read more &rarr;](https://github.com/garethcheyne/npm-fluentui-extended/blob/main/docs/DataGrid.md)** - columns, unsaved-edit layering, persistence, and the headless `useDataGrid` hook.
+
 ### DateTimeField
 
 A date/time field that respects the attribute's Dynamics `DateTimeBehavior`, so `DateOnly` values
@@ -143,6 +173,76 @@ selections render as the usual Lookup badges and multi-select comes for free.
 
 ![OwnerLookup users and teams](assets/screenshot-ownerlookup-open.png)
 
+### AddressLookup
+
+A preconfigured `Lookup` for Google Places. Type an address, hover a suggestion to see it on a
+map, and the selection arrives flattened into the columns an address is stored in.
+
+Google bills per request, so the work is split the way the API prices it: typing buys
+Autocomplete predictions only, and a place is resolved once - when its card opens, or when the
+row is chosen, whichever happens first. The result is cached, so hovering then clicking the same
+suggestion costs a single Place Details call.
+
+Each suggestion is iconed by what it actually is - a street address, a building, a suburb, a
+region, an airport, a shop - rather than every row carrying the same pin, so a list of mixed
+results can be read at a glance.
+
+```tsx
+import { AddressLookup } from 'fluentui-extended';
+import type { PlaceAddress } from 'fluentui-extended';
+
+const [address, setAddress] = useState<PlaceAddress | null>(null);
+
+<AddressLookup
+  apiKey={googleMapsKey}
+  label="Address"
+  value={address}
+  onSelect={(picked) => setAddress(picked)}
+  countries={['nz', 'au']}
+  stateShortName
+  countryShortName
+/>
+```
+
+`onSelect` receives the flattened address and the place it came from:
+
+```ts
+{
+  placeId: 'ChIJ...',
+  formattedAddress: '1 Queen Street, Auckland CBD, Auckland 1010, New Zealand',
+  building: '', street: '1 Queen Street', suburb: 'Auckland CBD',
+  city: 'Auckland', state: 'AUK', postcode: '1010', country: 'NZ',
+  latitude: -36.8442, longitude: 174.7676,
+}
+```
+
+The key needs the **Maps JavaScript API** and the **Places API** enabled, and the host's origin
+allowed under its HTTP referrer restrictions. The Maps script is loaded once per page and shared,
+so several AddressLookups on one form cost one script tag between them.
+
+#### AddressLookup Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `apiKey` | `string` | - | Google Maps API key (required) |
+| `value` / `onSelect` | `PlaceAddress \| null` | - | Selection (controlled). `onSelect` also receives the full `PlaceDetail` |
+| `countries` | `string \| string[]` | - | Restrict to ISO country codes, e.g. `['nz','au']`. Google allows five |
+| `searchTypes` | `string[]` | `['address']` | Use `['establishment']` for businesses, `['geocode']` for anything mappable |
+| `stateShortName` | `boolean` | `false` | Return `NSW` rather than `New South Wales` |
+| `countryShortName` | `boolean` | `false` | Return `AU` rather than `Australia` |
+| `showMapCard` | `boolean` | `true` | Map card on hover |
+| `mapCardTarget` | `'list' \| 'rest' \| 'both'` | `'both'` | Where the card is offered |
+| `mapCardDelayMs` | `number` | `400` | Pointer settle delay before the place is resolved |
+| `mapZoom` | `number` | `15` | Map zoom on the card |
+| `showCoordinates` / `showRatings` | `boolean` | `true` | Card detail toggles |
+| `cardActions` | `ReactNode` | - | Content at the bottom of the card |
+| `minSearchLength` | `number` | `3` | Short input never leaves the browser |
+| `onError` | `(error) => void` | - | Search or place lookup failures |
+
+The Places client is exported on its own for geocoding outside a form:
+`loadGoogleMaps`, `searchPlacePredictions`, `getPlaceDetails`, `parsePlaceAddress`,
+`placeMapUrl`, `isGoogleMapsReady`, `clearPlacesCache`.
+
 ### ParentPortal
 
 Renders Fluent UI content in the **parent document**, escaping an iframe boundary with full styling. Designed for Dynamics 365 web resources where dialogs must float above the entire D365 page rather than being trapped inside the iframe.