infi-grid 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,141 @@
+# Changelog
+
+## 1.0.0
+
+First release of InfiGrid, published as `infi-grid`. It is angpackage-grid 1.2.1 under its new name: the same features, behaviour, configuration, API, events and types. Only the names change (the README's "Coming from angpackage-grid" has the full table):
+
+- The package: `angpackage-grid` → `infi-grid` (`npm install infi-grid`).
+- The component: `<ang-grid>` → `<infi-grid>`; `AngGridComponent`, `AngGridModule` and `ANG_GRID` → `InfiGridComponent`, `InfiGridModule` and `INFI_GRID`.
+- The template directives: `angGrid…` → `infiGrid…` (for example `angGridCell` → `infiGridCell`).
+- The CSS: classes `.ang-grid…` → `.infi-grid…`, theme variables `--ang-grid-*` → `--infi-grid-*`.
+
+## angpackage-grid releases
+
+The releases below were published as `angpackage-grid`, under its names.
+
+### 1.2.1
+
+Fast scrolling without blank rows or columns, cell reuse by column type (`templateKey`), and the filter row fix.
+
+#### Added
+- `templateKey` (column): template cells are reused while scrolling sideways, and a cell that leaves the view is given to a column with the same key. Rows get enough cells for the most columns of each key that can be in view, so once each cell has met its kind, scrolling only updates cells instead of re-rendering their content. Use it when columns share a template that renders different content, for example one template with an `@switch` on the column's type. Without keys, nothing changes.
+  - Why it matters: re-rendering a cell's content creates views. That is slow for rich cells (components, form controls), and in zone.js apps it also makes Angular check the whole application, so fast sideways scrolling or scrollbar jumps could leave parts of the grid blank for a moment.
+
+- `virtualization.syncScroll` (default `true`): fast scrolling never shows blank rows or columns. See Fixes.
+
+#### Fixes
+- Fast scrolling (a mouse-wheel flick, a trackpad fling, a scrollbar drag) no longer shows blank rows or columns. Browsers scroll on their own thread and show the new position before the page's code runs; the grid draws the rows and columns for it a frame later (more on a slow PC, or while the first scroll after loading sets everything up), so areas past the drawn ones were blank until it caught up, the whole body during a fast scrollbar drag. Now the drawn content stays where it is while the browser scrolls, and moves in the same frame as the rows and columns drawn for the new position: it can follow the scrollbar a frame late, but is never blank. The header, the summary row and the pinned checkbox and action columns move with it, so nothing gets out of line.
+  - The checkbox and action columns are placed by the grid instead of being sticky in every row. A sticky element in each row made the browser draw every row as a separate layer (about 70 layers for a typical grid instead of about 6), with more work for each frame and rows that could be drawn a frame apart.
+  - Nothing changes once scrolling stops: the grid looks the same as before. `virtualization: { syncScroll: false }` brings back the earlier behaviour.
+- The filter row (`filtering.mode: 'row'` or `'both'`) is shown only while at least one displayed column is filterable. With filtering off (`filtering.enabled: false` with no column set to `filterable: true`, every column `filterable: false`, or the filterable columns hidden), an empty row used to stay under the header. The rows, the loading, empty and error overlays and the inline add row now start right under the header, and `aria-rowindex` counts only the header row.
+
+#### Behaviour changes
+1. The viewport has three more wrapper elements, with or without `syncScroll`: `.ang-grid__stage` and `.ang-grid__stage-inner` around the header, the rows and the summary row, and `.ang-grid__rows-track` around the rows. CSS that relies on the old nesting with `>` (for example `.ang-grid__rows > .ang-grid__row`) needs updating; selectors without `>` keep working.
+2. With `syncScroll`, the checkbox and action columns (`.ang-grid__pin`) are absolutely positioned by the grid (class `is-placed`) instead of `position: sticky`. Custom CSS that sets their `position`, `left` or `right` can move them. `virtualization: { syncScroll: false }` makes them sticky again.
+
+### 1.2.0
+
+Fixes and changes from the 1.1 test report, and cell selection.
+
+#### Fixes
+- The row and header checkboxes show the selection right after every change, in zone.js and zoneless apps: a click, the keyboard, the API, a filter, a sort or a data refresh. In zone.js apps, a clicked row's box could stay unchecked (and the header box miss its indeterminate state) until the next scroll.
+
+#### Row selection
+- `selection.clickBehavior` is removed; the mode decides what a click (checkbox, or cell and row with `selectOnClick`) and Space do:
+  - `'multiple'`: toggle that row and keep the other selected rows. Shift+click and Shift+↑/↓ select the rows from the last clicked row, keeping the rows selected before; repeating Shift grows or shrinks that range. Ctrl/Cmd+click is the same as a click.
+  - `'single'`: select that row instead of the selected one; on the selected row, deselect it.
+- Changing `selection.mode` at runtime: `'none'` deselects every row, `'single'` keeps only the last selected row (`selectionChange` with source `'api'`).
+
+#### Cell selection (new, off by default)
+- `cellSelection: { enabled, activeRow }`, a section of its own: no `selection` option applies to it.
+  - A click or the keyboard (arrows, Home/End, Page Up/Down, Ctrl+Home/End, Tab between editors) selects one cell: focus outline, `is-selected`, `aria-selected`.
+  - It follows its row by key through sorting, filtering, scrolling and refreshes, and is cleared when its row leaves the data or its column is removed.
+  - Clicks never change the row selection while it is on (`selectOnClick` is ignored). Rows are selected with the checkbox column, the keyboard and the API.
+  - `activeRow`: the selected cell's row gets `.ang-grid__row--active` (`--ang-grid-active-row-bg`). Visual only.
+- `(cellSelectionChange)`: the cell's row, key, indexes, field, column, value and formatted value, the previous cell, the source and the DOM event. `cancel` in `(cellClick)`/`(rowClick)` stops the cell selection.
+- API: `getSelectedCell()`, `selectCell(key, field, { scroll })`, `clearCellSelection()`.
+- Theme variables: `--ang-grid-active-row-bg`, `--ang-grid-selected-cell-bg`.
+
+#### Behaviour changes
+1. `selection.clickBehavior` is removed (setting it is a type error; a value that still arrives at runtime is ignored).
+   - Multiple mode: a plain click used to replace the selection (the default, `'replace'`); it now toggles the row. Apps whose users relied on a click replacing the selection can use `'single'` mode.
+   - Single mode: a click on the selected row now deselects it.
+2. Shift+click in multiple mode keeps the rows selected before the range (it used to replace them unless Ctrl/Cmd was held).
+3. Changing `selection.mode` at runtime reduces the selection, as described above.
+
+### 1.1.0
+
+All additions are opt-in or backwards compatible, except the behaviour changes listed at the end.
+
+#### Row identity and data refresh
+- `primaryKey` (field, dot path or function) identifies rows. Duplicate and missing keys are reported once through `(gridError)` (source `'data'`).
+- `setData()`, `refreshData()` (re-read the same array after `push`/`splice`), and `dataRefresh` options for what a refresh keeps (filter, sort, selection, scroll).
+- New outputs: `(dataRefresh)` and `(loadingChange)`.
+- Lookups by key: `getRowKey()`, `getRowByKey()`, `getRowIndexByKey()`, `scrollToRowByKey()`.
+- Every API method is also available on the component instance (for `@ViewChild`).
+- Fix: after changing the array in place, `refresh()` now also updates the row count and the empty state.
+
+#### Row selection
+- `selection.mode`: `'single'` or `'multiple'`.
+  - Selecting by click (Ctrl/Cmd toggles, Shift selects a range), a pinned checkbox column with select-all (indeterminate state), or the keyboard (Space, Shift+arrows, Ctrl/Cmd+A).
+  - `rowSelectable`, `selectAllScope`, and `onFilter` (rows hidden by a filter are deselected by default).
+- API: `selectRowByKey`, `deselectRowByKey`, `selectRowsByKeys`, `deselectRowsByKeys`, `toggleRowSelection`, `selectAll`, `deselectAll`, `clearSelection`, `getSelectedRows`, `getSelectedKeys`, `isRowSelected`.
+- Events: `(selectionChange)` (added/removed rows, old/new row in single mode, previous/current selection), `(rowSelected)`, `(rowDeselected)`, `(selectionCleared)`, and the cancelable `(selectionClick)`.
+
+#### Add, update and delete
+- API: `addRow()`, `beginAddRow()` (the inline add row), `updateRow()`, `deleteRow()`, `deleteRows()`, `requestDeleteRows()` and `deleteSelectedRows()` (both with confirmation). Each returns a `GridCrudResult`.
+- Validation:
+  - column `required`, `defaultValue` and `editableOnAdd`;
+  - `editing.newRow` (initializer) and `editing.rowValidator`;
+  - unique, present primary keys. Keys can't be changed.
+- UI:
+  - `editing.actionColumn`, pinned at the right: ✎ 🗑 per row, ✓ ✕ while editing, + in the header.
+  - The Delete key (`allowDelete`).
+  - A delete confirmation dialog, or your own `angGridDeleteConfirm` template.
+- Events: the cancelable `(rowAdding)`, `(rowUpdating)` and `(rowDeleting)`; then `(rowAdded)`, `(rowUpdated)` (with an `oldRow` snapshot) and `(rowDeleted)`.
+- `(dataChange)`: adds and deletes never change your array; they emit a new one (`[(data)]` works).
+
+#### Batch editing
+- `editing.batch`: changes are kept as pending changes.
+  - New, modified and deleted rows are marked; deleted rows stay visible with a restore button.
+  - Undo and redo, also with Ctrl/Cmd+Z and Ctrl/Cmd+Shift+Z or Ctrl+Y.
+  - A built-in toolbar with the change count, Undo, Redo, Discard and Save.
+- API: `saveChanges(handler?)` (Promise or Observable handler, or `editing.saveHandler`; a failed save keeps everything pending), `cancelChanges()`, `getPendingChanges()`, `hasPendingChanges()`, `undo()`, `redo()`, `canUndo()`, `canRedo()`.
+- Events: `(changesSaved)`, `(changesCancelled)`, `(changesSaveFailed)`, `(pendingChange)`.
+
+#### Tooltips
+- `tooltips`: cut-off text by default, or always, or never; show and hide delays; placement with flipping near the window edges; `disabledTypes`.
+- Column options: `tooltip` (on/off, mode, or a function), `description` (always shown in the header tooltip), `headerTooltip`, and tooltip templates (`angGridCellTooltip`, `angGridHeaderTooltip`, or per column).
+- Keyboard focus shows tooltips too. They are accessible (`role="tooltip"`, `aria-describedby`).
+- There is one element per grid, removed with the grid.
+
+#### Filtering
+- The popup:
+  - offers "Clear filter" and "Clear all filters";
+  - takes up to 5 conditions (`maxConditions`) with add and remove buttons and one AND/OR choice.
+- Filter row (`filtering.mode: 'row' | 'both'`):
+  - a debounced input per column (`rowDebounce`), with an operator menu and a clear button;
+  - a select for booleans;
+  - Tab moves in column order.
+- Filtered headers get an accent line, and their filter button reads "(filtered)".
+- API: `clearAllFilters()`, `isFiltered()`, `getDisplayedRowCount()`.
+
+#### Events and columns
+- `(rowDoubleClick)`, `(headerClick)`, `(cellContextMenu)` (`events.preventContextMenu`), `(cellMouseEnter)` and `(cellMouseLeave)`. The mouse events are matched once per frame and never fire while scrolling.
+- Click events carry `key`, `dataIndex` and `formattedValue`, and a `cancel` flag that stops the grid's own reaction.
+- `events.clickMode: 'waitForDoubleClick'`.
+- `(columnResize)` adds `column`, `oldWidth`, `newWidth` and `source` (`'user' | 'api' | 'reset'`). New: `resetColumnWidth()`.
+
+#### Behaviour changes
+1. The second click of a double click no longer emits `cellClick`/`rowClick`.
+2. Cut-off cells and headers show a tooltip by default (`tooltips.enabled: false` turns it off). The native `title` of headers and summary cells is replaced by it.
+3. In the filter popup, more conditions are added with "+ Add condition", with no empty second row any more. "Clear" became "Clear filter", in the popup header.
+4. With a `primaryKey`, the key column isn't editable.
+5. Inline edits emit `(rowUpdating)` and `(rowUpdated)`; `required` and `editing.rowValidator` apply to them.
+6. In row edit mode, a checkbox editor no longer saves the row when ticked.
+7. Summaries of computed columns update when the fields they use are edited.
+8. The sort-order badge only takes space in multi-column sorts, so header labels have more room.
+
+### 1.0.0
+
+First release: row and column virtualization, Excel-style filtering, multi-sort, editing (cell, row and grid modes), summaries, templates, loading/empty/error states, theming and the grid API.