@appius-fr/apx 2.7.0 → 2.8.0

package/modules/scrollableTable/CHANGELOG.md

@@ -0,0 +1,45 @@
+# 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.8.0] - 2026-02-19
+
+### Added
+- Option **`defaultSizingUnit`**: `{ cols?: string, rows?: string }` — controls the CSS unit used for measured column widths and row heights. `cols` defaults to `'fr'` (proportional), `rows` defaults to `'px'` (exact). Accepts any CSS unit string, but only `'fr'` and `'px'` produce meaningful results with measured pixel values. Per-column/per-row overrides and full template strings still take precedence.
+
+### Changed
+- **Scrollbar gutter default**: the fallback for `--apx-scrollable-gutter-width` is now the measured vertical scrollbar width (`getScrollbarSize('vertical')`) instead of a fixed 17px. Override in CSS or set to `0` still works as before.
+
+## [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

@@ -1,52 +1,122 @@
-# APX Scrollable Table Module
-
-Makes the **tbody** of a table scrollable while keeping **thead** and **tfoot** fixed and column alignment consistent. Uses CSS Grid with subgrid so no JavaScript is needed for width syncing or scrollbar compensation.
-
-## Requirements
-
-- Modern browsers with **CSS subgrid** support (Chrome 117+, Safari 16+, Firefox 71+). See [caniuse](https://caniuse.com/css-subgrid).
-
-## Installation
-
-The module is part of APX. Ensure the scrollableTable augment is applied (see `APX.mjs`).
-
-CSS is loaded automatically when the module is imported.
-
-## Usage
-
-### Init
-
-```js
-APX('table.my-table').scrollableTable({ maxHeight: 300 });
-// or with a CSS length
-APX('table.my-table').scrollableTable({ maxHeight: '50vh' });
-```
-
-Calling `scrollableTable(options)` again with no options or an empty object does nothing (idempotent). Passing new options (e.g. a different `maxHeight`) updates the stored options and re-applies the layout.
-
-### Refresh
-
-After changing the table DOM (adding/removing rows, changing colspan/rowspan), re-apply the layout with the same options:
-
-```js
-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'`). |
-
-## Colspan and rowspan
-
-Tables with **colspan** and **rowspan** are supported. The module sets explicit grid placement on each cell so thead, tbody, and tfoot stay aligned. Complex headers or merged cells in the body/foot work as expected.
-
-## Edge cases
-
-- **Empty tbody:** The layout is still applied; the tbody area is scrollable with no content.
-- **No thead or no tfoot:** Tables with only thead+tbody or tbody+tfoot are supported; grid rows adjust automatically.
-
-## Browser support
-
-Requires **CSS subgrid**. No fallback is provided in this module; for legacy browsers, consider a different approach or a separate fallback implementation.
+# APX Scrollable Table Module
+
+Makes the **tbody** of a table scrollable while keeping **thead** and **tfoot** fixed and column alignment consistent. Uses CSS Grid with subgrid so no JavaScript is needed for width syncing or scrollbar compensation.
+
+## Requirements
+
+- Modern browsers with **CSS subgrid** support (Chrome 117+, Safari 16+, Firefox 71+). See [caniuse](https://caniuse.com/css-subgrid).
+
+## Installation
+
+The module is part of APX. Ensure the scrollableTable augment is applied (see `APX.mjs`).
+
+CSS is loaded automatically when the module is imported.
+
+## Usage
+
+### Init
+
+```js
+APX('table.my-table').scrollableTable({ maxHeight: 300 });
+// or with a CSS length
+APX('table.my-table').scrollableTable({ maxHeight: '50vh' });
+```
+
+Calling `scrollableTable(options)` again with no options or an empty object does nothing (idempotent). Passing new options (e.g. a different `maxHeight`) updates the stored options and re-applies the layout.
+
+### Refresh
+
+After changing the table DOM (adding/removing rows, changing colspan/rowspan), re-apply the layout with the same options:
+
+```js
+APX('table.my-table').scrollableTable('refresh');
+```
+
+## Options
+
+| 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. |
+| `defaultSizingUnit`    | `object`         | —         | CSS unit for measured widths/heights: `{ cols?: string, rows?: string }`. `cols` defaults to `'fr'` (proportional), `rows` defaults to `'px'` (exact). See [Default sizing unit](#default-sizing-unit) below. |
+
+### 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.
+
+### Default sizing unit
+
+By default, measured column widths are applied as `fr` (proportional — columns fill the container and maintain their ratios) and row heights as `px` (exact pixel values). Use `defaultSizingUnit` to swap these defaults:
+
+```js
+// Lock columns to exact pixel widths instead of proportional
+APX('table.my-table').scrollableTable({
+  maxHeight: 300,
+  defaultSizingUnit: { cols: 'px' }
+});
+```
+
+Only `'fr'` and `'px'` produce meaningful results (the numeric values come from `getBoundingClientRect()`). Per-column/per-row overrides (`columnOverrides`, `rowOverrides`) and full template strings (`gridTemplateColumns`, `gridTemplateRows`) still take precedence over the default unit.
+
+## 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 is the measured vertical scrollbar width (via `getScrollbarSize`). Set to `0` if you want the scrollbar to overlap (e.g. with thin scrollbars).
+
+## Colspan and rowspan
+
+Tables with **colspan** and **rowspan** are supported. The module sets explicit grid placement on each cell so thead, tbody, and tfoot stay aligned. Complex headers or merged cells in the body/foot work as expected.
+
+## Edge cases
+
+- **Empty tbody:** The layout is still applied; the tbody area is scrollable with no content.
+- **No thead or no tfoot:** Tables with only thead+tbody or tbody+tfoot are supported; grid rows adjust automatically.
+
+## Browser support
+
+Requires **CSS subgrid**. No fallback is provided in this module; for legacy browsers, consider a different approach or a separate fallback implementation.

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 {
-    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;
-    width: 100%;
-}
-
-/* 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));
-}
-
-/* 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;
-}
-
-/* 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));
-}
-
-.apx-scrollable-table > thead,
-.apx-scrollable-table > tbody,
-.apx-scrollable-table > tfoot {
-    display: grid;
-    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);
-}
-
-.apx-scrollable-table > tbody {
-    grid-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);
-}
-
-.apx-scrollable-table > thead > tr,
-.apx-scrollable-table > tbody > tr,
-.apx-scrollable-table > tfoot > tr {
-    display: contents;
-}
-
-.apx-scrollable-table th,
-.apx-scrollable-table td {
-    /* Grid placement set by JS (grid-row, grid-column) for colspan/rowspan */
-    min-width: 0;
-}
+/* 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 !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 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: 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: 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 !important;
+    grid-template-columns: subgrid;
+    grid-column: 1 / -1;
+    min-height: 0;
+}
+
+.apx-scrollable-table > thead {
+    grid-template-rows: var(--apx-scrollable-thead-template-rows, repeat(var(--apx-scrollable-thead-rows, 1), auto));
+}
+
+.apx-scrollable-table > tbody {
+    grid-template-rows: var(--apx-scrollable-tbody-template-rows, repeat(var(--apx-scrollable-tbody-rows, 1), auto));
+    overflow: auto;
+}
+
+.apx-scrollable-table > tfoot {
+    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 !important;
+}
+
+.apx-scrollable-table th,
+.apx-scrollable-table td {
+    min-width: 0;
+    box-sizing: border-box;
+}