@guiexpert/table 1.1.96 → 1.1.97

package/lib/table/render-scope.d.ts

@@ -26,6 +26,8 @@ import { AreaObjectMapType } from './data/common/area-map.type.js';
 import { TableCellUpdateEventIf } from './data/common/event/input/table-cell-update-event.if.js';
 import { AriaGridInfo } from './aria/aria-grid-info.js';
 import { AriaTextsIf } from './aria/aria-texts.if.js';
+import { RowLayout } from './row-layout/row-layout.js';
+import { MasterDetailService } from './master-detail/master-detail-service.js';
 
 /** @category Internals */
 export declare class RenderScope extends EleScope {
@@ -103,6 +105,16 @@ export declare class RenderScope extends EleScope {
      * @since 1.1.96
      */
     fillHandleService?: FillHandleService;
+    /**
+     * Master/detail of this table (detail rows below master rows) – created by {@link TableScope} with
+     * `tableOptions.masterDetail`.
+     * @since 1.1.97
+     */
+    masterDetailService?: MasterDetailService;
+    /** Positions of the body rows (prefix sums of the heights + detail rows), see {@link getBodyRowLayout}. */
+    private readonly bodyRowLayout;
+    private bodyRowLayoutDirty;
+    private bodyRowLayoutModel?;
     constructor(hostElement: HTMLDivElement, tableModel: TableModelIf, dom: ConvenienceDomService, tableOptions: TableOptionsIf);
     /**
      * The DOM service of this table (all DOM access of the table goes through it).
@@ -155,6 +167,52 @@ export declare class RenderScope extends EleScope {
      * @since 1.1.96
      */
     getBodyCellAtHostPoint(x: number, y: number): [number, number];
+    /**
+     * The positions of the body rows: prefix sums of the row heights (O(log n) lookups also for variable heights) plus
+     * the heights of open detail rows. Built lazily – again after {@link invalidateRowLayout}, a new body model or
+     * another row count.
+     *
+     * @returns {RowLayout} the layout of the body rows
+     * @since 1.1.97
+     */
+    getBodyRowLayout(): RowLayout;
+    /**
+     * Marks the positions of the body rows as outdated (rows filtered, sorted, edited, added or removed, a detail row
+     * opened or closed) – they are computed again on the next access.
+     *
+     * @since 1.1.97
+     */
+    invalidateRowLayout(): void;
+    /**
+     * Sets the height of the detail row behind one body row in the current row layout without building it again
+     * (a detail row was expanded or collapsed). Does nothing if the layout is outdated anyway.
+     *
+     * @param {number} rowIndex - display index of the master row
+     * @param {number} height - the detail height, 0 = none
+     * @returns {boolean} true if the layout was updated, false if it is outdated (it is built again on the next access)
+     * @since 1.1.97
+     */
+    setBodyRowExtra(rowIndex: number, height: number): boolean;
+    /** True if open detail rows take space between the body rows. */
+    protected hasBodyRowExtras(): boolean;
+    /**
+     * The top of a body row in content pixels: {@link AreaModelIf.getYPosByRowIndex} plus the heights of the open detail
+     * rows above it (master/detail).
+     *
+     * @param {number} rowIndex - display index
+     * @returns {number} px from the top of the first body row
+     * @since 1.1.97
+     */
+    getBodyRowTop(rowIndex: number): number;
+    /**
+     * The body row at a content position (a position in an open detail row belongs to its master row). Above the rows:
+     * 0, below: the last row, without rows: -1.
+     *
+     * @param {number} contentY - px from the top of the first body row
+     * @returns {number} display index
+     * @since 1.1.97
+     */
+    getBodyRowIndexAtY(contentY: number): number;
     /**
      * Scroll bar pixels per content pixel: 1, below 1 for a capped scroll height ({@link isScrollHeightCapped}).
      *
@@ -338,6 +396,15 @@ export declare class RenderScope extends EleScope {
      * scaled and scrollTop is no longer a content pixel position.
      */
     isScrollHeightCapped(): boolean;
+    /**
+     * The model's content height plus the heights of open detail rows (master/detail).
+     *
+     * @returns {number} px
+     * @since 1.1.97
+     */
+    /** The detail layer (master/detail) covers the visible body. @since 1.1.97 */
+    protected adjustDetailLayerBounds(left: number, top: number, width: number, height: number): void;
+    protected getBodyContentHeight(): number;
     /** Scrollable range of the content in content pixels (content height minus visible body height). */
     protected getContentScrollRangeY(): number;
     /** Scrollable range of the scroll viewport in scroll bar pixels. */
@@ -550,6 +617,12 @@ export declare class RenderScope extends EleScope {
      *
      * @returns {void}
      */
+    /**
+     * Hides the hover row and column – e.g. while the pointer is over a detail row (master/detail).
+     *
+     * @since 1.1.97
+     */
+    hideHover(): void;
     protected hideHoverRow(): void;
     /**
      * Adjusts the position and size of the hover column based on the mouse move event.

package/lib/table/row-layout/row-layout.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Vertical positions of the body rows: the row heights as prefix sums plus optional extra heights behind single rows
+ * (the detail rows of master/detail). DOM-free; the table keeps one instance for its body
+ * ({@link RenderScope.getBodyRowTop}, {@link RenderScope.getBodyRowIndexAtY}).
+ *
+ * - Constant row height: positions are computed (`i * h`), no array.
+ * - Variable row heights: a `Float64Array` of `rowCount + 1` prefix sums, built lazily on the first access after
+ *   {@link setRows} – then {@link getTop} is O(1) and {@link findIndexAt} O(log n) (before 1.1.97 the table summed the
+ *   heights of all rows above the viewport in every scroll frame).
+ * - Extras: sorted row indices with their extra heights and the prefix sums of the extras (O(log k) per lookup,
+ *   k = number of extras). Changing one extra height ({@link setExtraHeight}) costs O(k), not O(n).
+ *
+ * The slot of a row is the row plus its extra height below it: `getTop(i + 1) = getTop(i) + getRowHeight(i) +
+ * getExtraHeight(i)`.
+ *
+ * @example
+ * const layout = new RowLayout();
+ * layout.setRows(1000, i => i % 2 ? 30 : 50);       // variable heights
+ * layout.setExtras([12, 40], [180, 240]);            // details behind rows 12 and 40
+ * const top = layout.getTop(41);                     // top of row 41 below both details
+ * const row = layout.findIndexAt(5000);              // the row whose slot contains y = 5000
+ *
+ * @category Internals
+ * @since 1.1.97
+ */
+export declare class RowLayout {
+    private rowCount;
+    private constantHeight?;
+    private heightOf;
+    private prefix?;
+    private extraIndices;
+    private extraHeights;
+    private extraPrefix;
+    /**
+     * Sets the rows. Prefix sums of variable heights are built lazily on the first access.
+     * Extras behind rows that no longer exist are dropped.
+     *
+     * @param {number} rowCount - number of rows
+     * @param {(rowIndex: number) => number} heightOf - height of a row (called only for variable heights)
+     * @param {number} [constantHeight] - the height of every row, if they are all equal (`AreaModelIf.getConstantRowHeight`)
+     */
+    setRows(rowCount: number, heightOf: (rowIndex: number) => number, constantHeight?: number): void;
+    /**
+     * Sets the extra heights (e.g. detail rows) behind rows. Unsorted input is fine; heights of the same row add up;
+     * indices outside the rows and heights ≤ 0 are ignored. Replaces all previous extras.
+     *
+     * @param {ArrayLike<number>} rowIndices - the rows with an extra height below them
+     * @param {ArrayLike<number>} heights - the extra heights (same order as `rowIndices`)
+     */
+    setExtras(rowIndices: ArrayLike<number>, heights: ArrayLike<number>): void;
+    /**
+     * Changes the extra height behind one row that already has one (see {@link setExtras}).
+     *
+     * @param {number} rowIndex - the row
+     * @param {number} height - the new extra height (> 0)
+     * @returns {boolean} false if the row has no extra or the height did not change
+     */
+    setExtraHeight(rowIndex: number, height: number): boolean;
+    /**
+     * Sets, changes or (height ≤ 0) removes the extra height behind one row – O(k), the other extras stay.
+     *
+     * @param {number} rowIndex - the row (ignored outside the rows)
+     * @param {number} height - the extra height, ≤ 0 removes it
+     * @returns {boolean} true if something changed
+     */
+    setExtra(rowIndex: number, height: number): boolean;
+    /** The number of rows. */
+    getRowCount(): number;
+    /** The number of rows with an extra height. */
+    getExtraCount(): number;
+    /** True after the prefix sums of variable heights were built (never for constant heights). */
+    hasPrefixSums(): boolean;
+    /**
+     * The height of a row (without its extra).
+     *
+     * @param {number} rowIndex - the row
+     * @returns {number} the height in px
+     */
+    getRowHeight(rowIndex: number): number;
+    /**
+     * The extra height below a row (0 = none).
+     *
+     * @param {number} rowIndex - the row
+     * @returns {number} the extra height in px
+     */
+    getExtraHeight(rowIndex: number): number;
+    /**
+     * The sum of the extra heights of the rows above a row.
+     *
+     * @param {number} rowIndex - the row (`rowCount` = all extras)
+     * @returns {number} px
+     */
+    getExtraBefore(rowIndex: number): number;
+    /** The sum of all extra heights. */
+    getExtraTotal(): number;
+    /**
+     * The top of a row: heights and extras of all rows above it. `getTop(rowCount)` = total height. The index is
+     * clamped to `0 … rowCount`.
+     *
+     * @param {number} rowIndex - the row
+     * @returns {number} px from the top of the first row
+     */
+    getTop(rowIndex: number): number;
+    /** The height of all rows and extras. */
+    getTotalHeight(): number;
+    /**
+     * The row whose slot (row + extra) contains `y`; rows of height 0 are skipped. Above the first row: 0, below the
+     * last: the last row, without rows: -1. O(1) for constant heights without extras, otherwise O(log n).
+     *
+     * @param {number} y - px from the top of the first row
+     * @returns {number} the row index
+     */
+    findIndexAt(y: number): number;
+    private getBaseTop;
+    private ensurePrefix;
+    private rebuildExtraPrefix;
+    /** The number of extras behind rows with an index < rowIndex (lower bound). */
+    private countExtrasBelow;
+    private findExtra;
+}

package/lib/table/state/table-state.if.d.ts

@@ -21,11 +21,12 @@ export type TableStateRowId = string | number;
  * | `selection` | selected rows, columns, cells or ranges | `autoRestoreSelectedState` |
  * | `headerGroups` | collapsed header groups | `autoRestoreHeaderGroupState` |
  * | `custom` | data of your application ({@link TableApi.setCustomState}) | `autoRestoreCustomState` |
+ * | `details` | expanded detail rows of master/detail (since 1.1.97) | `autoRestoreDetailState` |
  *
  * @category State
  * @since 1.1.92
  */
-export type TableStatePart = "columns" | "sort" | "scroll" | "tree" | "checked" | "selection" | "headerGroups" | "custom";
+export type TableStatePart = "columns" | "sort" | "scroll" | "tree" | "checked" | "selection" | "headerGroups" | "custom" | "details";
 /**
  * The state of a table as plain JSON: column layout, sorting, scroll position, tree, checked and selected rows,
  * header groups and data of your own. Get it with {@link TableApi.getState}, apply it with
@@ -72,6 +73,8 @@ export interface TableStateIf {
     tree?: TableTreeStateIf;
     /** The ids of the checked rows. */
     checkedRowIds?: TableStateRowId[];
+    /** The ids of the master rows with an expanded detail row (master/detail). @since 1.1.97 */
+    detailRowIds?: TableStateRowId[];
     /** The selection. */
     selection?: TableSelectionStateIf;
     /** The state of the header groups with a toggle. */

package/lib/table/state/table-state.service.d.ts

@@ -115,6 +115,10 @@ export declare class TableStateService {
     private computeScroll;
     private computeTree;
     private computeChecked;
+    /** The ids of the expanded master rows (master/detail, since 1.1.97); `undefined` without master/detail. */
+    private computeDetails;
+    /** Expands exactly the master rows with these ids (master/detail, since 1.1.97). */
+    private applyDetails;
     private computeSelection;
     /**
      * A cell range → ids and properties. A range to the last row / column (`MAX_SAFE_INTEGER`) has no `toRowId` /

package/lib/table/table-api.d.ts

@@ -1538,6 +1538,107 @@ export declare class TableApi {
      * @since 1.1.96
      */
     cancelFill(): void;
+    /**
+     * Expands or collapses the detail row of a master row (master/detail, {@link TableOptionsIf.masterDetail}). The
+     * content is created when the detail row becomes visible; collapsing destroys it. Reports
+     * {@link EventListenerIf.onDetailExpandedChanged} (source `"api"`).
+     *
+     * @param {number | object} rowOrIndex - display index or row object
+     * @param {boolean} expanded - `true` = expand, `false` = collapse
+     * @returns {boolean} false if nothing changed (no master row, already in that state, no master/detail)
+     *
+     * @example
+     * tableApi.setDetailExpanded(0, true);                  // the first shown row
+     * tableApi.setDetailExpanded(orders[42], true);         // a row object (also if it is filtered out)
+     *
+     * @since 1.1.97
+     */
+    setDetailExpanded(rowOrIndex: number | object, expanded: boolean): boolean;
+    /**
+     * Expands a collapsed or collapses an expanded detail row (master/detail).
+     *
+     * @param {number | object} rowOrIndex - display index or row object
+     * @returns {boolean} false if it is no master row (or no master/detail)
+     *
+     * @example
+     * tableApi.toggleDetail(3);   // e.g. from a button outside the table
+     *
+     * @since 1.1.97
+     */
+    toggleDetail(rowOrIndex: number | object): boolean;
+    /**
+     * True if the detail row of a master row is expanded (master/detail).
+     *
+     * @param {number | object} rowOrIndex - display index or row object
+     * @returns {boolean} whether it is expanded
+     *
+     * @example
+     * const open = tableApi.isDetailExpanded(3);
+     *
+     * @since 1.1.97
+     */
+    isDetailExpanded(rowOrIndex: number | object): boolean;
+    /**
+     * The master rows whose detail rows are expanded, in the order they were expanded (also rows that are filtered out).
+     *
+     * @returns {T[]} the row objects
+     *
+     * @example
+     * const openOrders = tableApi.getExpandedDetailRows<Order>().map(order => order.id);
+     *
+     * @since 1.1.97
+     */
+    getExpandedDetailRows<T = any>(): T[];
+    /**
+     * Expands the detail rows of all shown master rows. The contents are created only when they scroll into view, so this
+     * is cheap also for many rows. No event per row.
+     *
+     * @returns {number} the number of rows that were expanded
+     *
+     * @example
+     * document.querySelector("#expand-all")!.addEventListener("click", () => tableApi.expandAllDetails());
+     *
+     * @since 1.1.97
+     */
+    expandAllDetails(): number;
+    /**
+     * Collapses all detail rows (their contents are destroyed). No event per row.
+     *
+     * @returns {number} the number of rows that were collapsed
+     *
+     * @example
+     * tableApi.collapseAllDetails();
+     *
+     * @since 1.1.97
+     */
+    collapseAllDetails(): number;
+    /**
+     * Destroys the content of an expanded detail row and creates it again (`context.recreated` is `true`) – e.g. after
+     * the data it shows changed.
+     *
+     * @param {number | object} rowOrIndex - display index or row object
+     * @returns {boolean} false if the row is not expanded
+     *
+     * @example
+     * order.items.push(newItem);
+     * tableApi.refreshDetail(order);
+     *
+     * @since 1.1.97
+     */
+    refreshDetail(rowOrIndex: number | object): boolean;
+    /**
+     * The container of a detail row (the element your `detailRenderer` renders into) – only while its content exists
+     * (it is created when the detail row becomes visible).
+     *
+     * @param {number | object} rowOrIndex - display index or row object
+     * @returns {HTMLDivElement | undefined} the container
+     *
+     * @example
+     * const notes = tableApi.getDetailElement(order)?.querySelector("textarea");
+     *
+     * @since 1.1.97
+     */
+    getDetailElement(rowOrIndex: number | object): HTMLDivElement | undefined;
     /**
      * Starts a batch edit: from now on edited and filled values are **collected** – shown in the cells (class
      * `ge-table-cell-pending`), but not written into your rows – until {@link commitBatchEdit} or

package/lib/table/table-scope.d.ts

@@ -36,6 +36,7 @@ import { ResizeHandler } from './resize-handler.js';
 import { ExcelServiceIf } from './service/excel-service.if.js';
 import { ColumnDefIf } from './data/tablemodel/column/column-def.if.js';
 import { LiveAnnouncer } from './aria/live-announcer.js';
+import { GeDetailEventSource } from './data/common/event/ge-detail-event.js';
 import { FillHandleOptionsIf } from './fill/fill-handle-options.if.js';
 import { CellChangeIf, CellChangeSource } from './batch-edit/cell-change.if.js';
 import { CellValueChangeIf } from './batch-edit/cell-value-change.if.js';
@@ -377,6 +378,69 @@ export declare class TableScope extends RenderScope implements OnActionTriggered
      * new TableScope(hostDiv, newTableModel, new SimpleDomService(), new TableOptions(), new EventAdapter()).firstInit();
      */
     destroy(): void;
+    /**
+     * True if a DOM event comes from a detail row (master/detail) – e.g. from a nested table. The mouse, keyboard and
+     * pointer handlers of this table ignore such events.
+     *
+     * @param {Event} evt - an event while it is dispatched
+     * @returns {boolean} whether it comes from the detail layer
+     * @since 1.1.97
+     */
+    isEventInDetail(evt: Event): boolean;
+    /**
+     * Expands or collapses the detail row of a master row (see {@link TableApi.setDetailExpanded}).
+     *
+     * @param {number | object} rowOrIndex - display index or row object
+     * @param {boolean} expanded - the new state
+     * @param {GeDetailEventSource} [source] - what changed it
+     * @returns {boolean} false if nothing changed
+     * @since 1.1.97
+     */
+    setDetailExpanded(rowOrIndex: unknown, expanded: boolean, source?: GeDetailEventSource): boolean;
+    /**
+     * Toggles the detail row of a master row (see {@link TableApi.toggleDetail}).
+     *
+     * @param {number | object} rowOrIndex - display index or row object
+     * @param {GeDetailEventSource} [source] - what changed it
+     * @returns {boolean} false if it is no master row
+     * @since 1.1.97
+     */
+    toggleDetail(rowOrIndex: unknown, source?: GeDetailEventSource): boolean;
+    /**
+     * Called by {@link MasterDetailService} after detail rows were expanded or collapsed: new row positions and scroll
+     * height, repaint, event, announcement, table state.
+     *
+     * @param {unknown} row - the master row (`undefined` for several rows)
+     * @param {number} rowIndex - its display index (-1 for several rows or a row that is not shown)
+     * @param {boolean} expanded - the new state
+     * @param {GeDetailEventSource} source - what changed it
+     * @param {boolean} [emit] - false: no event (several rows at once)
+     * @param {boolean} [layoutUpdated] - true: the row layout was already updated for this one row
+     * @since 1.1.97
+     */
+    onDetailToggled(row: unknown, rowIndex: number, expanded: boolean, source: GeDetailEventSource, emit?: boolean, layoutUpdated?: boolean): void;
+    /**
+     * Called by {@link MasterDetailService} after a detail row with `detailHeight: "auto"` got a new height: new scroll
+     * height and repaint (the rows below move).
+     *
+     * @since 1.1.97
+     */
+    onDetailHeightChanged(): void;
+    /**
+     * The focus came back from a detail row (Shift+Tab): its master row gets the focus (same column).
+     *
+     * @param {number} rowIndex - display index of the master row
+     * @since 1.1.97
+     */
+    /**
+     * A detail row that holds the keyboard focus goes away (collapsed, destroyed, scrolled out of view): the host takes
+     * the focus and the master row becomes the focused row – without a repaint (the caller repaints).
+     *
+     * @param {number} rowIndex - display index of the master row (-1: only the host)
+     * @since 1.1.97
+     */
+    takeFocusFromDetail(rowIndex: number): void;
+    focusDetailMaster(rowIndex: number): void;
     /**
      * Returns `true` once {@link destroy} has been called.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guiexpert/table",
-  "version": "1.1.96",
+  "version": "1.1.97",
   "license": "MIT",
   "author": "Dr. Marc Kronberg <info@gui.expert> (https://gui.expert)",
   "repository": {