@dloizides/ui-tables 1.15.0 → 1.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,68 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.17.0
4
+
5
+ **`DataTable` rows now fade in on load — the Ant-design-like list entrance — via `@dloizides/ui-motion`.**
6
+
7
+ When a `DataTable` mounts its rows (first load, and whenever the row set changes — sort / filter /
8
+ page), each row now fades in with a small upward translate, staggered across the first few rows. It
9
+ is a subtle polish layer, gated hard so it never becomes jank on a large page, and **entirely
10
+ opt-outable** — omit nothing and the table behaves exactly as before minus the fade.
11
+
12
+ ### What changed
13
+
14
+ | Area | Detail |
15
+ |---|---|
16
+ | **New optional prop** | `animateRows?: boolean` (default **`true`**). Each row (and its expanded detail panel, if any) is wrapped in `@dloizides/ui-motion`'s `<FadeIn>`, keyed by the row key. |
17
+ | **Capped stagger** | Only the first `ROW_ENTRANCE_STAGGER_CAP` (10) rows stagger, `ROW_ENTRANCE_STAGGER_STEP_MS` (30 ms) apart; every row past the cap shares the capped delay. A 100- or 5,000-row page settles in a fixed ~300 ms, **never** row-by-row. |
18
+ | **Reduced-motion** | Honoured: rows render instantly, with **no wrapper node and no delay** (`FadeIn` gates too, but the wrapper is skipped entirely so the reduced-motion DOM is identical to the un-animated table). |
19
+ | **No re-fade on re-render** | Each row's `<FadeIn>` is keyed by its row key, so React keeps its identity across unrelated re-renders (hover, a re-fetch that resolves to the SAME keys) — the entrance plays once per key, not on every render. A genuine row-set change (new keys) re-fades, as intended. |
20
+ | **New test id** | `rowFadeTestID(tableTestID, key)` → `${tableTestID}-fade-${key}` (present only while animating), exported alongside the other row test-id helpers. |
21
+
22
+ ### Backward compatibility
23
+
24
+ - **MINOR, additive.** The public API gains one optional prop and one test-id helper; nothing is
25
+ renamed or removed.
26
+ - All existing behaviour is preserved: zebra, sticky header, mobile card-stack, row/per-cell/head/
27
+ detail-panel/select-checkbox test ids, `onRowPress`, bulk-select, keyboard navigation, the pager,
28
+ and the refetch-does-not-blank-the-grid guard.
29
+ - Pass `animateRows={false}` (or run under `prefers-reduced-motion`) and rows render with no
30
+ wrapper node — DOM identical to before this release.
31
+ - New peer of the kit: `@dloizides/ui-motion` (`^1.0.1`) is added as a dependency.
32
+
33
+ ## 1.16.0
34
+
35
+ **The responsive card-stack now reads as a proper mobile layout — and keeps every E2E hook.**
36
+
37
+ `DataTable` has always collapsed to a label:value card-stack below a breakpoint (`stackBreakpoint`),
38
+ but on a phone the multi-column tables it powers (e.g. the organizer Passes table) were still hard
39
+ to read, and the card-stack silently dropped test hooks a wide-viewport E2E suite relies on. This
40
+ release makes the card-stack the readable, self-explanatory mobile layout it was meant to be —
41
+ **with no change to the desktop grid and no broken selectors.**
42
+
43
+ ### What changed
44
+
45
+ | Area | Before | Now |
46
+ |---|---|---|
47
+ | **Default breakpoint** | `640` | `768` — the kit-wide narrow-viewport threshold, aligned with `@dloizides/ui-layout`'s `MENU_BREAKPOINT` (already the collapse point for the nav menu and tabs). `CARD_STACK_BREAKPOINT` is re-exported at the new value. |
48
+ | **Card line layout** | label LEFT, value RIGHT on one `space-between` row (cramped for long values / action buttons) | each column's header sits **ABOVE** its value, both left-aligned, so the value gets the full card width |
49
+ | **Per-cell test id `${row}-${colKey}`** | resolved **only** on the desktop grid | resolves in **BOTH** layouts (the card line carries the same id the desktop cell does) |
50
+ | **Head test id `ui-data-table-head`** | **absent** in card-stack mode | resolves in **BOTH** layouts via a hidden, a11y-inert carrier (`display: none`, `aria-hidden`) — E2E selectors survive at every width |
51
+
52
+ ### Backward compatibility
53
+
54
+ - **The desktop grid is byte-for-byte unchanged.** Opt out of the card-stack entirely, at every
55
+ width, with `stackBreakpoint={0}` (unchanged).
56
+ - A column's `render` node (badge, link, **action button**) renders identically in a card cell.
57
+ - Row / per-cell / head / detail-panel / select-checkbox test ids are all preserved; the only
58
+ net-new guarantee is that per-cell and head ids now ALSO resolve in the card-stack.
59
+ - The one observable difference for an existing consumer is cosmetic: tables between 640px and
60
+ 768px wide now show the card-stack (they showed the cramped desktop row before), and cards read
61
+ vertically rather than as a `space-between` row. Both are strict readability improvements — which
62
+ is what keeps this a MINOR bump.
63
+
64
+ All 272 tests pass (6 added for the both-layouts test-hook contract + the vertical card layout).
65
+
3
66
  ## 1.15.0
4
67
 
5
68
  **A re-fetch no longer blanks the grid — the server-paged paging defect.**
package/README.md CHANGED
@@ -226,10 +226,20 @@ const overrides: DataTableStyleOverrides = {
226
226
  | `Pager` | `PagerStyleOverrides` | `pager`, `pagerInfo`, `pagerNav`, `pagerRowsLabel`, `sizeGroup`, `control`, `controlText`, `sizePill`, `sizePillText` |
227
227
  | `FilterBar` | `FilterBarStyleOverrides` | `filters`, `filtersSpacer`, `results`, `filtersActions` |
228
228
 
229
- **Disabling the card-stack**: the label:value card-stack renders when `width < stackBreakpoint`,
230
- so `stackBreakpoint={0}` (never true) keeps the desktop grid at every width — the opt-out for a
231
- consumer whose table never had a card-stack. Omit `styleOverrides` entirely and every component
232
- renders exactly as it always has.
229
+ **The responsive card-stack** (default breakpoint `768`, aligned with `@dloizides/ui-layout`'s
230
+ `MENU_BREAKPOINT`): below `stackBreakpoint` each row collapses to a card where every column's
231
+ header sits **above** its value (left-aligned label:value pairs), so a narrow phone never crams a
232
+ multi-column table into a side-scrolling row. The desktop grid above the breakpoint is unchanged.
233
+
234
+ - **Test hooks survive both layouts.** The head test id (`ui-data-table-head`), the row test ids
235
+ (`${testID}-row-${key}`) and the **per-cell** test ids (`${testID}-row-${key}-${col.key}`) all
236
+ resolve in the card-stack exactly as they do on the desktop grid — so an E2E suite written
237
+ against the wide layout keeps working when a table goes card-stack on mobile. A column's `render`
238
+ node (badge, link, action button) renders identically in a card cell.
239
+ - **Disabling the card-stack**: it renders when `width < stackBreakpoint`, so `stackBreakpoint={0}`
240
+ (never true) keeps the desktop grid at every width — the opt-out for a table that never had one.
241
+
242
+ Omit `styleOverrides` entirely and every component renders exactly as it always has.
233
243
 
234
244
  Colours come entirely from `useUi().theme` (drive it with `@dloizides/design-tokens` via `tokensToUiTheme`), so the grid re-themes per tenant. Every component-authored string is routed through the UiProvider `t` — provide the `uiTables.*` keys (see `TABLE_I18N`) in your locale files; a caller may also pass already-translated `loadingLabel` / `emptyLabel` / `resultsLabel` directly.
235
245
 
package/dist/index.d.mts CHANGED
@@ -161,13 +161,31 @@ interface DataTableProps<T> {
161
161
  * Web-only in effect (focus movement and key events are DOM concerns); inert on native.
162
162
  */
163
163
  keyboardNavigation?: boolean;
164
+ /**
165
+ * Fade each row in (with a small upward translate) as the row SET mounts — the
166
+ * Ant-design-like list entrance, via `@dloizides/ui-motion`'s `<FadeIn>`. The first
167
+ * few rows stagger; every row past the cap shares one capped delay, so a full page
168
+ * never animates row-by-row (see `ROW_ENTRANCE_STAGGER_CAP`).
169
+ *
170
+ * The entrance plays when a row's key first appears — i.e. on first load and whenever
171
+ * the row set changes (sort / filter / page) — and **NOT** on unrelated re-renders
172
+ * (hover, a re-fetch that resolves to the same keys), because each row's `<FadeIn>` is
173
+ * keyed by its row key and so keeps its identity across those renders.
174
+ *
175
+ * Honours reduced-motion: the rows render instantly, with no wrapper and no delay.
176
+ * Default **on**; pass `animateRows={false}` to opt out — rows then render exactly as
177
+ * they did before this prop existed (no wrapper node, unchanged DOM).
178
+ */
179
+ animateRows?: boolean;
164
180
  loading?: boolean;
165
181
  /** Loading text (already translated). Falls back to the kit's `loading` translation. */
166
182
  loadingLabel?: string;
167
183
  /** Empty text (already translated). Falls back to the kit's `empty` translation. */
168
184
  emptyLabel?: string;
169
185
  /**
170
- * Below this width (px) rows collapse to a label:value card. Default 640.
186
+ * Below this width (px) rows collapse to a stacked label:value card (each column's
187
+ * header sits above its value). Default 768 — the kit-wide narrow-viewport threshold,
188
+ * aligned with `@dloizides/ui-layout`'s `MENU_BREAKPOINT` (`CARD_STACK_BREAKPOINT`).
171
189
  *
172
190
  * **Opt out of the card-stack entirely with `stackBreakpoint={0}`**: the stack is
173
191
  * chosen by `width < stackBreakpoint`, which is never true for 0, so the desktop
@@ -362,8 +380,17 @@ declare function Pager({ page, pageSize, total, onPageChange, onPageSizeChange,
362
380
  * Keeps every literal (test ids, i18n keys, layout numbers) in one place so the
363
381
  * components hold no magic numbers and no ad-hoc strings.
364
382
  */
365
- /** Default breakpoint (px): below this a row collapses to a label:value card. */
366
- declare const CARD_STACK_BREAKPOINT = 640;
383
+ /**
384
+ * Default breakpoint (px): below this a row collapses to a label:value card.
385
+ *
386
+ * Aligned with `@dloizides/ui-layout`'s `MENU_BREAKPOINT` (768) — the kit's single
387
+ * "this is a phone / narrow tablet" threshold, already the collapse point for the nav
388
+ * menu (`ModalDropdown`) and the tabs bar (`TABS_COLLAPSE_BREAKPOINT`). Kept as a plain
389
+ * literal rather than an import so a table has no runtime dependency on the layout kit
390
+ * for one number; the value is what is shared, and it is documented here as such. A table
391
+ * that never wants the card-stack still opts out with `stackBreakpoint={0}`.
392
+ */
393
+ declare const CARD_STACK_BREAKPOINT = 768;
367
394
  /** Default rows-per-page choices, matching the vanilla console's GRID.md pager. */
368
395
  declare const DEFAULT_PAGE_SIZE_OPTIONS: readonly number[];
369
396
  /** Stable test ids so consumers/e2e can target the shared chrome. */
@@ -376,6 +403,8 @@ declare const TABLE_TEST_IDS: {
376
403
  readonly rowDetailInfix: "row-detail";
377
404
  /** Infix of a row's select checkbox: `${tableTestID}-select-${key}`. */
378
405
  readonly rowSelectInfix: "select";
406
+ /** Infix of a row's entrance-fade wrapper: `${tableTestID}-fade-${key}`. */
407
+ readonly rowFadeInfix: "fade";
379
408
  /** Suffix of the header (select-all-on-page) checkbox: `${tableTestID}-select-all`. */
380
409
  readonly selectAllSuffix: "select-all";
381
410
  /** Suffix of the select-all-matching banner: `${tableTestID}-select-banner`. */
@@ -407,6 +436,12 @@ declare const rowDetailTestID: (tableTestID: string, key: string) => string;
407
436
  declare const rowSelectTestID: (tableTestID: string, key: string) => string;
408
437
  /** The test id of the header (select-all-on-page) checkbox: `${tableTestID}-select-all`. */
409
438
  declare const selectAllTestID: (tableTestID: string) => string;
439
+ /**
440
+ * The test id of a row's entrance-fade wrapper: `${tableTestID}-fade-${key}` (key from
441
+ * `keyExtractor`). Only present while `animateRows` is on and reduced-motion is off.
442
+ * Exported so consumers/e2e can target (or assert the absence of) the animation wrapper.
443
+ */
444
+ declare const rowFadeTestID: (tableTestID: string, key: string) => string;
410
445
  /**
411
446
  * Translation keys for every component-authored, user-facing string. Apps map
412
447
  * these in their UiProvider `t` (FM); the neutral default `t` returns the key, so
@@ -748,4 +783,4 @@ interface PagedRows<T> {
748
783
  */
749
784
  declare function usePagedRows<T>(rows: readonly T[], options?: UsePagedRowsOptions): PagedRows<T>;
750
785
 
751
- export { type BooleanFilterField, CARD_STACK_BREAKPOINT, DEFAULT_PAGE_SIZE, DEFAULT_PAGE_SIZE_OPTIONS, DataTable, type DataTableColumn, type DataTableProps, type DataTableStyleOverrides, type DateRangeFilterField, FIELD_MIN_WIDTH, FILTERS_I18N, FILTERS_TEST_ID, type FieldStrings, FilterBar, type FilterBarProps, type FilterBarStyleOverrides, type FilterDraft, type FilterField, type FilterFieldKind, type FilterOption, type FilterValue, type FilterValues, Filters, type FiltersProps, type NumberFilterField, type PagedRows, Pager, type PagerProps, type PagerStyleOverrides, type RenderSelectArgs, type SelectFilterField, StatCard, type StatCardProps, TABLE_I18N, TABLE_TEST_IDS, type TextFilterField, type TypeaheadFilterField, type UseFilterDraftOptions, type UsePagedRowsOptions, applyTestID, clearTestID, fieldTestID, rowDetailTestID, rowSelectTestID, rowTestID, selectAllTestID, useFilterDraft, usePagedRows };
786
+ export { type BooleanFilterField, CARD_STACK_BREAKPOINT, DEFAULT_PAGE_SIZE, DEFAULT_PAGE_SIZE_OPTIONS, DataTable, type DataTableColumn, type DataTableProps, type DataTableStyleOverrides, type DateRangeFilterField, FIELD_MIN_WIDTH, FILTERS_I18N, FILTERS_TEST_ID, type FieldStrings, FilterBar, type FilterBarProps, type FilterBarStyleOverrides, type FilterDraft, type FilterField, type FilterFieldKind, type FilterOption, type FilterValue, type FilterValues, Filters, type FiltersProps, type NumberFilterField, type PagedRows, Pager, type PagerProps, type PagerStyleOverrides, type RenderSelectArgs, type SelectFilterField, StatCard, type StatCardProps, TABLE_I18N, TABLE_TEST_IDS, type TextFilterField, type TypeaheadFilterField, type UseFilterDraftOptions, type UsePagedRowsOptions, applyTestID, clearTestID, fieldTestID, rowDetailTestID, rowFadeTestID, rowSelectTestID, rowTestID, selectAllTestID, useFilterDraft, usePagedRows };
package/dist/index.d.ts CHANGED
@@ -161,13 +161,31 @@ interface DataTableProps<T> {
161
161
  * Web-only in effect (focus movement and key events are DOM concerns); inert on native.
162
162
  */
163
163
  keyboardNavigation?: boolean;
164
+ /**
165
+ * Fade each row in (with a small upward translate) as the row SET mounts — the
166
+ * Ant-design-like list entrance, via `@dloizides/ui-motion`'s `<FadeIn>`. The first
167
+ * few rows stagger; every row past the cap shares one capped delay, so a full page
168
+ * never animates row-by-row (see `ROW_ENTRANCE_STAGGER_CAP`).
169
+ *
170
+ * The entrance plays when a row's key first appears — i.e. on first load and whenever
171
+ * the row set changes (sort / filter / page) — and **NOT** on unrelated re-renders
172
+ * (hover, a re-fetch that resolves to the same keys), because each row's `<FadeIn>` is
173
+ * keyed by its row key and so keeps its identity across those renders.
174
+ *
175
+ * Honours reduced-motion: the rows render instantly, with no wrapper and no delay.
176
+ * Default **on**; pass `animateRows={false}` to opt out — rows then render exactly as
177
+ * they did before this prop existed (no wrapper node, unchanged DOM).
178
+ */
179
+ animateRows?: boolean;
164
180
  loading?: boolean;
165
181
  /** Loading text (already translated). Falls back to the kit's `loading` translation. */
166
182
  loadingLabel?: string;
167
183
  /** Empty text (already translated). Falls back to the kit's `empty` translation. */
168
184
  emptyLabel?: string;
169
185
  /**
170
- * Below this width (px) rows collapse to a label:value card. Default 640.
186
+ * Below this width (px) rows collapse to a stacked label:value card (each column's
187
+ * header sits above its value). Default 768 — the kit-wide narrow-viewport threshold,
188
+ * aligned with `@dloizides/ui-layout`'s `MENU_BREAKPOINT` (`CARD_STACK_BREAKPOINT`).
171
189
  *
172
190
  * **Opt out of the card-stack entirely with `stackBreakpoint={0}`**: the stack is
173
191
  * chosen by `width < stackBreakpoint`, which is never true for 0, so the desktop
@@ -362,8 +380,17 @@ declare function Pager({ page, pageSize, total, onPageChange, onPageSizeChange,
362
380
  * Keeps every literal (test ids, i18n keys, layout numbers) in one place so the
363
381
  * components hold no magic numbers and no ad-hoc strings.
364
382
  */
365
- /** Default breakpoint (px): below this a row collapses to a label:value card. */
366
- declare const CARD_STACK_BREAKPOINT = 640;
383
+ /**
384
+ * Default breakpoint (px): below this a row collapses to a label:value card.
385
+ *
386
+ * Aligned with `@dloizides/ui-layout`'s `MENU_BREAKPOINT` (768) — the kit's single
387
+ * "this is a phone / narrow tablet" threshold, already the collapse point for the nav
388
+ * menu (`ModalDropdown`) and the tabs bar (`TABS_COLLAPSE_BREAKPOINT`). Kept as a plain
389
+ * literal rather than an import so a table has no runtime dependency on the layout kit
390
+ * for one number; the value is what is shared, and it is documented here as such. A table
391
+ * that never wants the card-stack still opts out with `stackBreakpoint={0}`.
392
+ */
393
+ declare const CARD_STACK_BREAKPOINT = 768;
367
394
  /** Default rows-per-page choices, matching the vanilla console's GRID.md pager. */
368
395
  declare const DEFAULT_PAGE_SIZE_OPTIONS: readonly number[];
369
396
  /** Stable test ids so consumers/e2e can target the shared chrome. */
@@ -376,6 +403,8 @@ declare const TABLE_TEST_IDS: {
376
403
  readonly rowDetailInfix: "row-detail";
377
404
  /** Infix of a row's select checkbox: `${tableTestID}-select-${key}`. */
378
405
  readonly rowSelectInfix: "select";
406
+ /** Infix of a row's entrance-fade wrapper: `${tableTestID}-fade-${key}`. */
407
+ readonly rowFadeInfix: "fade";
379
408
  /** Suffix of the header (select-all-on-page) checkbox: `${tableTestID}-select-all`. */
380
409
  readonly selectAllSuffix: "select-all";
381
410
  /** Suffix of the select-all-matching banner: `${tableTestID}-select-banner`. */
@@ -407,6 +436,12 @@ declare const rowDetailTestID: (tableTestID: string, key: string) => string;
407
436
  declare const rowSelectTestID: (tableTestID: string, key: string) => string;
408
437
  /** The test id of the header (select-all-on-page) checkbox: `${tableTestID}-select-all`. */
409
438
  declare const selectAllTestID: (tableTestID: string) => string;
439
+ /**
440
+ * The test id of a row's entrance-fade wrapper: `${tableTestID}-fade-${key}` (key from
441
+ * `keyExtractor`). Only present while `animateRows` is on and reduced-motion is off.
442
+ * Exported so consumers/e2e can target (or assert the absence of) the animation wrapper.
443
+ */
444
+ declare const rowFadeTestID: (tableTestID: string, key: string) => string;
410
445
  /**
411
446
  * Translation keys for every component-authored, user-facing string. Apps map
412
447
  * these in their UiProvider `t` (FM); the neutral default `t` returns the key, so
@@ -748,4 +783,4 @@ interface PagedRows<T> {
748
783
  */
749
784
  declare function usePagedRows<T>(rows: readonly T[], options?: UsePagedRowsOptions): PagedRows<T>;
750
785
 
751
- export { type BooleanFilterField, CARD_STACK_BREAKPOINT, DEFAULT_PAGE_SIZE, DEFAULT_PAGE_SIZE_OPTIONS, DataTable, type DataTableColumn, type DataTableProps, type DataTableStyleOverrides, type DateRangeFilterField, FIELD_MIN_WIDTH, FILTERS_I18N, FILTERS_TEST_ID, type FieldStrings, FilterBar, type FilterBarProps, type FilterBarStyleOverrides, type FilterDraft, type FilterField, type FilterFieldKind, type FilterOption, type FilterValue, type FilterValues, Filters, type FiltersProps, type NumberFilterField, type PagedRows, Pager, type PagerProps, type PagerStyleOverrides, type RenderSelectArgs, type SelectFilterField, StatCard, type StatCardProps, TABLE_I18N, TABLE_TEST_IDS, type TextFilterField, type TypeaheadFilterField, type UseFilterDraftOptions, type UsePagedRowsOptions, applyTestID, clearTestID, fieldTestID, rowDetailTestID, rowSelectTestID, rowTestID, selectAllTestID, useFilterDraft, usePagedRows };
786
+ export { type BooleanFilterField, CARD_STACK_BREAKPOINT, DEFAULT_PAGE_SIZE, DEFAULT_PAGE_SIZE_OPTIONS, DataTable, type DataTableColumn, type DataTableProps, type DataTableStyleOverrides, type DateRangeFilterField, FIELD_MIN_WIDTH, FILTERS_I18N, FILTERS_TEST_ID, type FieldStrings, FilterBar, type FilterBarProps, type FilterBarStyleOverrides, type FilterDraft, type FilterField, type FilterFieldKind, type FilterOption, type FilterValue, type FilterValues, Filters, type FiltersProps, type NumberFilterField, type PagedRows, Pager, type PagerProps, type PagerStyleOverrides, type RenderSelectArgs, type SelectFilterField, StatCard, type StatCardProps, TABLE_I18N, TABLE_TEST_IDS, type TextFilterField, type TypeaheadFilterField, type UseFilterDraftOptions, type UsePagedRowsOptions, applyTestID, clearTestID, fieldTestID, rowDetailTestID, rowFadeTestID, rowSelectTestID, rowTestID, selectAllTestID, useFilterDraft, usePagedRows };