@appius-fr/apx 2.7.0 → 2.7.1

package/modules/scrollableTable/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog — Scrollable Table module
+
+All notable changes to this module are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## [2.7.1] - 2025-02-16
+
+### Added
+- Option **`height`**: fixed body height (number or CSS length). When set, the tbody row always uses this height; `maxHeight` is ignored. Class `apx-scrollable-table--body-height` is applied.
+- Option **`bodyHeightDynamic`**: dynamic body height — `{ get: (table) => number|string, useAs: 'height'|'maxHeight', updateOn?: { scroll?, resize?, scrollOn?, resizeOn? } }`. Re-resolves body size when scroll/resize sources fire (viewport, scrollbar appearance, or custom elements). **updateOn** uses booleans `scroll`/`resize` (default true = document scroll + window resize) or explicit `scrollOn`/`resizeOn` arrays with sentinels `'document'`/`'window'` or elements (ResizeObserver for resize elements). Lazy cleanup: tables removed from the DOM are dropped from updates on the next event (no MutationObserver).
+- Option **`gridTemplateColumns`**: full override for column tracks (e.g. `'1fr 2fr 1fr'`). Skips width measurement.
+- Option **`gridTemplateRows`**: per-section override `{ thead?, tbody?, tfoot? }` for row tracks.
+- Option **`columnOverrides`**: hybrid mode — column index → CSS value (object or array). Columns not overridden keep measured width.
+- Option **`rowOverrides`**: hybrid mode — per-section row index → CSS value. Rows not overridden keep measured height.
+- **Column width preservation**: widths are measured from the table’s natural layout (before applying the module) and applied as `grid-template-columns`; stored in ref for refresh.
+- **Row height preservation**: each `<tr>` height is measured and applied so rowspan cells keep correct proportions.
+- **Scrollbar gutter**: dedicated grid column for the vertical scrollbar so it does not overlap the last data column. CSS variable `--apx-scrollable-gutter-width` (default 17px); set to `0` to allow overlap.
+- CSS variables **`--apx-scrollable-thead-template-rows`**, **`--apx-scrollable-tbody-template-rows`**, **`--apx-scrollable-tfoot-template-rows`** for row track overrides.
+
+### Fixed
+- **Horizontal scrollbar on init**: the grid class and template-columns were applied in the same layout pass, causing the tbody to overflow horizontally. The grid is now established first (with a forced reflow) before setting the measured template-columns.
+- Measured column widths now use `fr` units instead of `px` so they remain flexible alongside the fixed gutter column.
+
+### Changed
+- Removed `scrollbar-gutter: stable` from tbody; scrollbar space is now the dedicated gutter column.
+- Grid template columns: value is set via `--apx-scrollable-template-columns` (with gutter suffix). Fallback in CSS includes gutter.
+- Body size: when `height` is set, grid row uses fixed size; otherwise `fit-content(max-height)` as before. With `bodyHeightDynamic`, body size is resolved from `get(table)` at init and on scroll/resize (throttled).
+
+## [2.7.0] - 2025-02-16
+
+### Added
+- Initial release: scrollable tbody with fixed thead/tfoot, CSS Grid + subgrid.
+- `APX('table').scrollableTable(options)` and `scrollableTable('refresh')`.
+- Option `maxHeight` (number or CSS length).
+- Full colspan/rowspan support via explicit grid placement.
+- Demo: `demo/modules/scrollableTable/index.html`.

package/modules/scrollableTable/README.md

@@ -34,9 +34,65 @@ APX('table.my-table').scrollableTable('refresh');
 
 ## Options
 
-| Option      | Type             | Default   | Description                          |
-| ----------- | ---------------- | --------- | ------------------------------------ |
-| `maxHeight` | `number` or `string` | `'200px'` | Max height of the tbody. Number is treated as pixels; string can be any CSS length (e.g. `'50vh'`, `'20rem'`). |
+| Option                 | Type             | Default   | Description                                                                 |
+| ---------------------- | ---------------- | --------- | --------------------------------------------------------------------------- |
+| `maxHeight`            | `number` or `string` | `'200px'` | Max height of the tbody (content can be shorter). Number = pixels; string = any CSS length (e.g. `'50vh'`). Ignored when `height` or `bodyHeightDynamic` is set. |
+| `height`               | `number` or `string` | —         | Fixed height of the tbody (same syntax as `maxHeight`). When set, the tbody row always uses this height even with few rows. Ignored when `bodyHeightDynamic` is set. |
+| `bodyHeightDynamic`    | `object`         | —         | **Dynamic body height:** `{ get: (table) => number|string, useAs: 'height'\|'maxHeight', updateOn?: { scroll?, resize?, scrollOn?, resizeOn? } }`. Re-resolves height when scroll/resize sources fire. See [Dynamic body height](#dynamic-body-height) below. |
+| `gridTemplateColumns`  | `string`         | —         | CSS value for column tracks (e.g. `'1fr 2fr 1fr'`). When set, measured widths are skipped and this value is used as-is. |
+| `gridTemplateRows`     | `object`         | —         | Per-section row tracks: `{ thead?: string, tbody?: string, tfoot?: string }` (e.g. `{ tbody: 'auto 40px 40px' }`). When set for a section, measured row heights are skipped for that section. |
+| `rowOverrides`         | `object`         | —         | **Hybrid mode (rows):** per-section row index → CSS value. E.g. `{ tbody: { 0: '48px', 2: '2fr' } }` or `{ thead: ['50px', null] }`. Rows not overridden keep the measured height. Ignored when `gridTemplateRows` is set for that section. |
+| `columnOverrides`       | `object` or `array` | —     | **Hybrid mode:** column index → CSS value. Columns not overridden keep the measured width. E.g. `{ 0: '2fr', 2: '80px' }` or `['2fr', null, '80px']`. Ignored when `gridTemplateColumns` is set. |
+| `resizeObserver`       | `boolean`        | `false`   | When `true`, observes the table size and re-applies column widths proportionally on resize. (Ignored when `gridTemplateColumns` is set.) |
+
+### Dynamic body height
+
+When `bodyHeightDynamic` is set, the tbody size is computed by `get(table)` (returning a number or CSS length string) and applied as `height` or `maxHeight` according to `useAs`. The value is re-resolved when the sources in `updateOn` fire, so the table can adapt to viewport resize or scrollbar appearance.
+
+**updateOn** (optional) controls where we listen:
+
+- **Booleans:** `scroll` (default `false`) / `resize` (default `true` when omitted). When `scroll` is `true`, we listen to document/window scroll. When `resize` is `true`, we listen to window resize and observe `document.documentElement` (so scrollbar appearance triggers an update). Set to `false` to disable.
+- **Explicit sources:** `scrollOn` / `resizeOn` — arrays of targets. Use sentinels `'document'` (scroll) and `'window'` (resize), or pass elements (we listen to `scroll` on them, or observe them with `ResizeObserver` for resize). When provided (non-empty), they override the boolean defaults.
+
+Example: viewport-based max-height with default resize (scrollbar pop + window resize):
+
+```js
+APX('table.my-table').scrollableTable({
+  bodyHeightDynamic: {
+    get: (table) => window.innerHeight - table.getBoundingClientRect().top - 40,
+    useAs: 'maxHeight',
+    // updateOn omitted => scroll: false, resize: true (window + ResizeObserver on document)
+  }
+});
+```
+
+Example: also react to a scrollable parent:
+
+```js
+APX('table.my-table').scrollableTable({
+  bodyHeightDynamic: {
+    get: (table) => ...,
+    useAs: 'maxHeight',
+    updateOn: { scrollOn: ['document', document.querySelector('#main')], resizeOn: ['window'] }
+  }
+});
+```
+
+**Cleanup:** Tables removed from the DOM are removed from the update set on the next scroll/resize (lazy cleanup via `isConnected`). No MutationObserver is used.
+
+## CSS variables (override)
+
+You can override row tracks in CSS via custom properties (e.g. on the table or a parent):
+
+- `--apx-scrollable-thead-template-rows` — thead row tracks (e.g. `50px 50px`)
+- `--apx-scrollable-tbody-template-rows` — tbody row tracks
+- `--apx-scrollable-tfoot-template-rows` — tfoot row tracks
+
+If set, they override the measured or default row heights for that section.
+
+A dedicated column is reserved for the vertical scrollbar so it does not overlap the last data column. Its width is controlled by:
+
+- `--apx-scrollable-gutter-width` — default `17px`. Set to `0` if you want the scrollbar to overlap (e.g. with thin scrollbars).
 
 ## Colspan and rowspan
 

package/modules/scrollableTable/css/scrollableTable.css

@@ -1,60 +1,67 @@
-/* APX Scrollable Table: scrollable tbody with fixed thead/tfoot and aligned columns (CSS Grid + subgrid) */
+/* APX Scrollable Table: scrollable tbody with fixed thead/tfoot and aligned columns (CSS Grid + subgrid)
+   Use !important so page styles (e.g. display: table) do not override the grid layout. */
 
+/* --apx-scrollable-template-columns: set by JS (measured widths + gutter); fallback = equal columns + gutter */
+/* --apx-scrollable-gutter-width: space for vertical scrollbar so it does not overlap the last column (set to 0 to allow overlap) */
+/* --apx-scrollable-body-height: when class apx-scrollable-table--body-height is set, tbody row uses fixed height instead of max-height */
 .apx-scrollable-table {
-    display: grid;
-    grid-template-columns: repeat(var(--apx-scrollable-cols, 3), minmax(0, 1fr));
-    grid-template-rows: auto fit-content(var(--apx-scrollable-body-max-height, 200px)) auto;
+    display: grid !important;
+    grid-template-columns: var(--apx-scrollable-template-columns, repeat(var(--apx-scrollable-cols, 3), minmax(0, 1fr)) minmax(var(--apx-scrollable-gutter-width, 17px), var(--apx-scrollable-gutter-width, 17px)));
+    grid-template-rows: auto var(--apx-scrollable-body-row-size, fit-content(var(--apx-scrollable-body-max-height, 200px))) auto;
     width: 100%;
+    table-layout: unset !important;
+}
+
+.apx-scrollable-table--body-height {
+    --apx-scrollable-body-row-size: var(--apx-scrollable-body-max-height, 200px);
 }
 
 /* Table with no tfoot: thead + tbody only */
 .apx-scrollable-table:not(.apx-scrollable-table--has-tfoot) {
-    grid-template-rows: auto fit-content(var(--apx-scrollable-body-max-height, 200px));
+    grid-template-rows: auto var(--apx-scrollable-body-row-size, fit-content(var(--apx-scrollable-body-max-height, 200px)));
 }
 
 /* Table with no thead: tbody + tfoot only */
 .apx-scrollable-table.apx-scrollable-table--no-thead {
-    grid-template-rows: fit-content(var(--apx-scrollable-body-max-height, 200px)) auto;
+    grid-template-rows: var(--apx-scrollable-body-row-size, fit-content(var(--apx-scrollable-body-max-height, 200px))) auto;
 }
 
 /* Table with neither thead nor tfoot: tbody only */
 .apx-scrollable-table.apx-scrollable-table--no-thead:not(.apx-scrollable-table--has-tfoot) {
-    grid-template-rows: fit-content(var(--apx-scrollable-body-max-height, 200px));
+    grid-template-rows: var(--apx-scrollable-body-row-size, fit-content(var(--apx-scrollable-body-max-height, 200px)));
 }
 
+/* --apx-scrollable-*-template-rows: set by JS (measured heights) or override in CSS / via options */
 .apx-scrollable-table > thead,
 .apx-scrollable-table > tbody,
 .apx-scrollable-table > tfoot {
-    display: grid;
+    display: grid !important;
     grid-template-columns: subgrid;
     grid-column: 1 / -1;
-    grid-template-rows: repeat(var(--apx-scrollable-thead-rows, 1), auto);
     min-height: 0;
 }
 
 .apx-scrollable-table > thead {
-    grid-template-rows: repeat(var(--apx-scrollable-thead-rows, 1), auto);
+    grid-template-rows: var(--apx-scrollable-thead-template-rows, repeat(var(--apx-scrollable-thead-rows, 1), auto));
 }
 
 .apx-scrollable-table > tbody {
-    grid-template-rows: repeat(var(--apx-scrollable-tbody-rows, 1), auto);
+    grid-template-rows: var(--apx-scrollable-tbody-template-rows, repeat(var(--apx-scrollable-tbody-rows, 1), auto));
     overflow: auto;
-    /* Reserve space for the vertical scrollbar so it doesn't shrink content width and trigger a horizontal scrollbar */
-    scrollbar-gutter: stable;
 }
 
 .apx-scrollable-table > tfoot {
-    grid-template-rows: repeat(var(--apx-scrollable-tfoot-rows, 1), auto);
+    grid-template-rows: var(--apx-scrollable-tfoot-template-rows, repeat(var(--apx-scrollable-tfoot-rows, 1), auto));
 }
 
 .apx-scrollable-table > thead > tr,
 .apx-scrollable-table > tbody > tr,
 .apx-scrollable-table > tfoot > tr {
-    display: contents;
+    display: contents !important;
 }
 
 .apx-scrollable-table th,
 .apx-scrollable-table td {
-    /* Grid placement set by JS (grid-row, grid-column) for colspan/rowspan */
     min-width: 0;
+    box-sizing: border-box;
 }