@appius-fr/apx 2.6.2 → 2.7.1

package/modules/scrollableTable/README.md

@@ -0,0 +1,108 @@
+# 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. |
+| `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
+
+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

@@ -0,0 +1,67 @@
+/* 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;
+}